diff --git a/docs/decisions/2026-11-18-validate-hub-destination-before-artifact-metadata.md b/docs/decisions/2026-11-18-validate-hub-destination-before-artifact-metadata.md new file mode 100644 index 0000000..048b2d2 --- /dev/null +++ b/docs/decisions/2026-11-18-validate-hub-destination-before-artifact-metadata.md @@ -0,0 +1,11 @@ +# Validate the Hub destination before fetching artifact metadata + +- **Context:** Media artifact planning reads pinned Hugging Face metadata. The server can supply + `HF_ENDPOINT` and `HF_TOKEN` together, so the endpoint determines the recipient of the credential. +- **Decision:** Use the public Hub when no endpoint is configured. Require an explicitly configured + endpoint to be an absolute HTTP(S) URL without credentials, a query, or a fragment. Preserve a + valid mirror's base path and refuse malformed configuration before making a request. +- **Consequences:** A malformed mirror produces an actionable configuration error. The operator can + correct the endpoint or unset it to select the public Hub. +- **Owner:** team +- **Links:** `src/workspace-service/models/artifact-metadata.ts` diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 403513d..4b06e66 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -179,6 +179,7 @@ add a new one that says which record it supersedes. - **2026-11-01** — [Add audio.cpp before the core pin has it](2026-11-01-add-audio-cpp-before-the-core-pin.md) — `audio.*`, the `audio-cpp` engine, the catalog and a web studio ship against local contract copies; a core without audio is detected by its missing routes, offers nothing and answers one plain refusal; `core-workaround` markers fail lint when the pin moves. - **2026-11-02** — [Preserve audio selection after Stop](2026-11-02-preserve-audio-selection-after-stop.md) — retained core capabilities preserve the studio draft and catalog duration while the engine process is stopped; explicit unload clears the selection; ARM tests synchronise on worker requests and progress events. - **2026-11-01** — [Pin model catalog and resume plans](2026-11-01-pin-model-catalog-and-resume-plans.md) — use the unified catalog, record immutable source commits and resume saved plans. +- **2026-11-18** — [Validate the Hub destination before fetching artifact metadata](2026-11-18-validate-hub-destination-before-artifact-metadata.md) — reject a malformed mirror before sending requests with `HF_TOKEN`. - **2026-11-02** — [Distinguish unavailable quantizations from invalid catalogs](2026-11-02-distinguish-unavailable-quants-from-invalid-catalogs.md) — unknown explicit choices are usage refusals; broken catalog lists remain reportable, and valid selection stays unchanged. - **2026-11-02** — [Keep managed-model compatibility refusals local](2026-11-02-keep-managed-model-refusals-local.md) — display incompatible or empty engine verdicts without reporting an action failure; preserve genuine check exceptions. - **2026-11-02** — [Pin core 0.20.7 for audio](2026-11-02-pin-core-0-20-7-for-audio.md) — use the released audio contracts and engine registry; drop temporary feature detection; preserve both catalogs and verify audio file provenance before downloading. diff --git a/src/workspace-service/models/artifact-metadata-mirror.test.ts b/src/workspace-service/models/artifact-metadata-mirror.test.ts new file mode 100644 index 0000000..e0ab1cb --- /dev/null +++ b/src/workspace-service/models/artifact-metadata-mirror.test.ts @@ -0,0 +1,54 @@ +import { expect, it, vi } from 'vitest' +import { artifactMetadata } from './artifact-metadata.js' +import type { ArtifactPlan } from './artifact-plan.js' + +const A = 'a'.repeat(40) +const tree = { sha: A, siblings: [{ rfilename: 'weights.gguf', size: 4 }] } +const plan: ArtifactPlan = { + digest: 'old', + category: 'audio', + model_id: 'voice', + name: 'Voice', + engine: 'audio-cpp', + created_at: 1, + files: [ + { + url: `https://huggingface.co/a/model/resolve/${A}/weights.gguf`, + save_path: 'models/weights.gguf', + size: 4, + }, + ], + total_download_bytes: 4, + load: {}, +} + +it.each([ + '', + ' ', + 'hf-mirror.example', + 'https:mirror.example', + 'ftp://mirror.example', + 'https://user:secret@mirror.example', + 'https://mirror.example/hub?query=1', + 'https://mirror.example/hub#fragment', +])('rejects an invalid configured Hub without sending a request (%j)', async (mirror) => { + const request = vi.fn() + await expect(artifactMetadata(plan, request, 'hub-token', mirror)).rejects.toMatchObject({ + code: 'ATC_USAGE', + message: expect.stringContaining('HF_ENDPOINT'), + }) + expect(request).not.toHaveBeenCalled() +}) + +it.each([ + [undefined, 'https://huggingface.co'], + ['https://mirror.example/hub/', 'https://mirror.example/hub'], +])('sends the token to the selected Hub (%j)', async (mirror, destination) => { + const request = vi.fn(async () => Response.json(tree)) + const result = await artifactMetadata(plan, request, 'hub-token', mirror) + expect(result.total_download_bytes).toBe(4) + expect(request).toHaveBeenCalledWith( + `${destination}/api/models/a/model/revision/${A}?blobs=true&files_metadata=true`, + expect.objectContaining({ headers: { Authorization: 'Bearer hub-token' }, redirect: 'error' }) + ) +}) diff --git a/src/workspace-service/models/artifact-metadata.ts b/src/workspace-service/models/artifact-metadata.ts index 49f11cd..60f9e96 100644 --- a/src/workspace-service/models/artifact-metadata.ts +++ b/src/workspace-service/models/artifact-metadata.ts @@ -1,5 +1,6 @@ /** Verify every catalog file against its own immutable HF repository tree. No transfer happens here. */ import { createHash } from 'node:crypto' +import { AtcError } from '../../errors/index.js' import type { ArtifactPlan } from './artifact-plan.js' interface Tree { @@ -7,12 +8,35 @@ interface Tree { siblings: { rfilename: string; size?: number; lfs?: { size: number; sha256: string } }[] } +const HUB = 'https://huggingface.co' + +/** A configured mirror is part of the destination for the Hub token. */ +function hubBase(hub: string | undefined): string { + if (hub === undefined) return HUB + const url = URL.canParse(hub) ? new URL(hub) : undefined + if ( + !url || + !/^https?:\/\/[^/\\]/i.test(hub) || + url.username || + url.password || + url.href.includes('?') || + url.href.includes('#') + ) { + throw new AtcError( + 'ATC_USAGE', + 'Set HF_ENDPOINT to an absolute HTTP(S) URL without credentials, a query, or a fragment.' + ) + } + return url.href.replace(/\/+$/, '') +} + export async function artifactMetadata( plan: ArtifactPlan, request: typeof fetch, token?: string, - hub = 'https://huggingface.co' + hub?: string ): Promise { + const base = hubBase(hub) const trees = new Map>() const files = await Promise.all( plan.files.map(async (item) => { @@ -28,7 +52,7 @@ export async function artifactMetadata( if (!reading) { reading = (async () => { const response = await request( - `${hub.replace(/\/+$/, '')}/api/models/${repo}/revision/${revision}?blobs=true&files_metadata=true`, + `${base}/api/models/${repo}/revision/${revision}?blobs=true&files_metadata=true`, { signal: AbortSignal.timeout(15000), redirect: 'error',