Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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`
1 change: 1 addition & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
54 changes: 54 additions & 0 deletions src/workspace-service/models/artifact-metadata-mirror.test.ts
Original file line number Diff line number Diff line change
@@ -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<typeof fetch>()
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<typeof fetch>(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' })
)
})
28 changes: 26 additions & 2 deletions src/workspace-service/models/artifact-metadata.ts
Original file line number Diff line number Diff line change
@@ -1,18 +1,42 @@
/** 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 {
sha: string
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<ArtifactPlan> {
const base = hubBase(hub)
const trees = new Map<string, Promise<Tree>>()
const files = await Promise.all(
plan.files.map(async (item) => {
Expand All @@ -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',
Expand Down
Loading