@dejadex/web 0.0.0-stage → 0.1.0

package/src/identify/identifier.ts

@@ -0,0 +1,419 @@
+/**
+ * `createIdentifier`: crops in, catalogue ids out, on the device or through
+ * `POST /v1/identify`, under a verified lease, with usage counted on the
+ * device. See `types.ts` beside this file for the answer's shape and README.md
+ * for host wiring.
+ *
+ * Per call:
+ *   1. The lease must be set, unexpired, and have allowance left.
+ *   2. `router.ts` picks the device or the server.
+ *   3. A server attempt is bounded by the fallback deadline; on any failure
+ *      (or a late answer) the same crops are identified on the device.
+ *   4. The answer is metered (`usage/meter.ts`) before it is returned.
+ *
+ * `identify` never throws: every failure is an outcome.
+ */
+import { ScannerError } from '../errors.js'
+import { verifyLease, type Ed25519Verify, type LeasePublicKey } from '../lease/verify.js'
+import type { DomainCode, Lease, LeaseClaims, LeaseGrant, LeaseRequest } from '../types.js'
+import { UsageMeter, type DrainResult } from '../usage/meter.js'
+import { defaultUsageStore, randomId, type UsageStore } from '../usage/store.js'
+import { defaultEngineDeps, loadDeviceEngine, type DeviceEngine, type EngineConfig } from './engine.js'
+import {
+  DEFAULT_SERVER_TIMEOUT_MS,
+  DEFAULT_SLOW_DEVICE_BUDGET_MS,
+  ServerHealth,
+  chooseRoute,
+  serverDeadline,
+  type DeviceState,
+} from './router.js'
+import type { RuntimeOptions } from './runtime.js'
+import { postIdentify, type ServerAnswer, type ServerFetch } from './server.js'
+import {
+  DEFAULT_TOP,
+  MAX_CROPS_PER_REQUEST,
+  MAX_TOP,
+  type DeviceEngineInfo,
+  type IdentificationMode,
+  type IdentifierStatus,
+  type IdentifyCallOptions,
+  type IdentifyOutcome,
+  type IdentifyResult,
+} from './types.js'
+import { connectWorkerEngine, type WorkerLike } from './workerProtocol.js'
+import type { UsageBatch } from '../types.js'
+
+const DOMAIN_CODE = /^[a-z][a-z0-9]*_[a-z]{2}$/
+const SESSION = /^[\x20-\x7e]{1,128}$/
+
+export interface IdentifierOptions {
+  /** The shard to identify against; the lease must grant it. */
+  readonly domain: DomainCode
+  /** The service's lease-signing public keys (JWK `x`, optionally with `kid`). */
+  readonly leasePublicKeys: readonly LeasePublicKey[]
+  /** The first lease, as the host's backend returned it. Later ones go through `setLease`. */
+  readonly lease?: LeaseGrant
+  /** Base URL of the identify route, `{serverUrl}/v1/identify`. Omit or null: the device only. */
+  readonly serverUrl?: string | null
+  /** Default `auto`. `local` never sends an image. */
+  readonly identification?: IdentificationMode
+  /** `auto` uses the server when the device takes longer than this per crop (no WebGPU). Default 300. */
+  readonly slowDeviceBudgetMs?: number
+  /** The server's deadline while the device engine is not loaded yet. Default 8000. */
+  readonly serverTimeoutMs?: number
+  readonly runtime?: RuntimeOptions
+  /**
+   * Where the device engine runs: `worker` (default where `Worker` exists), `inline`
+   * (this thread; tests, or a host that already runs the SDK in its own Worker), or a
+   * factory for a Worker the host builds from `@dejadex/web/identify-worker`.
+   */
+  readonly engine?: 'worker' | 'inline' | (() => WorkerLike)
+  /** Download and warm the device engine as soon as a lease is set. Default true. */
+  readonly preload?: boolean
+  /** The page origin the lease must allow. Default `location.origin`. */
+  readonly origin?: string | null
+  /** Default IndexedDB (`dejadex-usage`), memory where it is unavailable. */
+  readonly usageStore?: UsageStore
+  /** Background failures (a device engine that failed to load). Never called from `identify`. */
+  readonly onError?: (error: Error) => void
+
+  /** @internal Test seams. */
+  readonly fetch?: ServerFetch
+  /** @internal */
+  readonly now?: () => number
+  /** @internal */
+  readonly online?: () => boolean
+  /** @internal */
+  readonly loadEngine?: (config: EngineConfig) => Promise<DeviceEngine>
+  /** @internal */
+  readonly verify?: Ed25519Verify
+}
+
+export interface Identifier {
+  /** At most 9 crops (JPEG for the server path). Always resolves. */
+  identify(crops: readonly Blob[], options?: IdentifyCallOptions): Promise<IdentifyOutcome>
+  /** Verifies and installs a lease (rejects with a `ScannerError` when it is not valid here). */
+  setLease(grant: LeaseGrant): Promise<Lease>
+  /** The identifier's own session id, used when a call names none. */
+  readonly session: string
+  /** Starts a new default session: cards seen before are counted again. */
+  newSession(): string
+  /** Loads (or awaits) the device engine for the current lease. */
+  prepare(): Promise<DeviceEngineInfo>
+  status(): IdentifierStatus
+  /** Hands queued usage to `deliver` (the host forwards it to its backend). See `UsageMeter.drain`. */
+  drainUsage(deliver: (batch: UsageBatch) => Promise<void>): Promise<DrainResult>
+  pendingUsage(): Promise<number>
+  /**
+   * The body the host sends its backend to renew: the current lease and the
+   * last report `seq` of it already delivered (null before the first lease).
+   * Drain usage first, or the service refuses the renewal (USAGE_UNREPORTED).
+   *
+   * `previousLeaseId` names another lease to renew instead: one the host
+   * stored but has not set here (it expired, or this page never identified).
+   * Null asks as a device with no lease.
+   */
+  leaseRequest(previousLeaseId?: string | null): Promise<LeaseRequest>
+  /** Releases the device engine and its Worker. Later calls resolve `unavailable`. */
+  destroy(): Promise<void>
+}
+
+const errorText = (err: unknown): string => (err instanceof Error ? err.message || err.name : String(err))
+const codeText = (err: unknown): string => (err instanceof ScannerError ? `${err.code}: ${err.message}` : errorText(err))
+
+function validate(options: IdentifierOptions): void {
+  const fail = (m: string): never => {
+    throw new ScannerError('INVALID_OPTIONS', m)
+  }
+  if (typeof options !== 'object' || options === null) fail('options are required')
+  if (typeof options.domain !== 'string' || !DOMAIN_CODE.test(options.domain)) fail(`not a domain code: ${String(options.domain)}`)
+  if (!Array.isArray(options.leasePublicKeys) || options.leasePublicKeys.length === 0) fail('leasePublicKeys must list at least one key')
+  const modes: readonly unknown[] = ['auto', 'local', 'server']
+  if (options.identification !== undefined && !modes.includes(options.identification)) fail(`unknown identification mode: ${String(options.identification)}`)
+  if (options.serverUrl !== undefined && options.serverUrl !== null) {
+    try {
+      const u = new URL(options.serverUrl)
+      if (u.protocol !== 'https:' && u.protocol !== 'http:') fail('serverUrl must be http(s)')
+    } catch {
+      fail(`serverUrl is not a URL: ${options.serverUrl}`)
+    }
+  }
+  for (const [name, v] of [['slowDeviceBudgetMs', options.slowDeviceBudgetMs], ['serverTimeoutMs', options.serverTimeoutMs]] as const) {
+    if (v !== undefined && (!Number.isFinite(v) || v <= 0)) fail(`${name} must be a positive number`)
+  }
+}
+
+function defaultOrigin(): string | null {
+  const loc = (globalThis as { location?: { origin?: string } }).location
+  return typeof loc?.origin === 'string' && loc.origin !== 'null' ? loc.origin : null
+}
+
+function defaultEngineLoader(choice: IdentifierOptions['engine']): (config: EngineConfig) => Promise<DeviceEngine> {
+  const useWorker = choice === undefined ? typeof Worker !== 'undefined' : choice !== 'inline'
+  if (!useWorker) return async (config) => loadDeviceEngine(config, await defaultEngineDeps())
+  const make =
+    typeof choice === 'function' ? choice : (): WorkerLike => new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })
+  return async (config) => {
+    const worker = make()
+    try {
+      return await connectWorkerEngine(worker, config)
+    } catch (err) {
+      worker.terminate()
+      throw err
+    }
+  }
+}
+
+export function createIdentifier(options: IdentifierOptions): Identifier {
+  validate(options)
+  const mode = options.identification ?? 'auto'
+  const endpoint = options.serverUrl ? `${options.serverUrl.trim().replace(/\/+$/, '')}/v1/identify` : null
+  const budget = options.slowDeviceBudgetMs ?? DEFAULT_SLOW_DEVICE_BUDGET_MS
+  const serverTimeoutMs = options.serverTimeoutMs ?? DEFAULT_SERVER_TIMEOUT_MS
+  const now = options.now ?? (() => Date.now())
+  const online = options.online ?? (() => (globalThis as { navigator?: { onLine?: boolean } }).navigator?.onLine !== false)
+  const origin = options.origin === undefined ? defaultOrigin() : options.origin
+  const doFetch: ServerFetch = options.fetch ?? ((url, init) => fetch(url, init))
+  const loadEngine = options.loadEngine ?? defaultEngineLoader(options.engine)
+  const health = new ServerHealth()
+  const meterReady: Promise<UsageMeter> = (options.usageStore ? Promise.resolve(options.usageStore) : defaultUsageStore()).then(
+    (store) => new UsageMeter({ store, now }),
+  )
+
+  let lease: Lease | null = null
+  /** The constructor's lease while it is being verified; `identify` waits for it. */
+  let initialLease: Promise<unknown> | null = null
+  let manifestUrl: string | null = null
+  let session = randomId()
+  let destroyed = false
+
+  // The device engine for the current lease, and its load.
+  let engine: DeviceEngine | null = null
+  let engineKey: string | null = null
+  let loading: Promise<DeviceEngine> | null = null
+  let deviceError: string | null = null
+
+  const keyOf = (claims: LeaseClaims, url: string) => `${url}\n${claims.modelVersion}\n${claims.indexVersion}`
+
+  function startLoad(): Promise<DeviceEngine> {
+    if (destroyed) return Promise.reject(new ScannerError('INVALID_OPTIONS', 'the identifier was destroyed'))
+    if (!lease || !manifestUrl) return Promise.reject(new ScannerError('LEASE_INVALID', 'no lease is set'))
+    const key = keyOf(lease.claims, manifestUrl)
+    if (engine && engineKey === key) return Promise.resolve(engine)
+    if (loading) return loading
+    const config: EngineConfig = {
+      manifestUrl,
+      expect: { modelVersion: lease.claims.modelVersion, indexVersion: lease.claims.indexVersion, shard: options.domain },
+      runtime: options.runtime ?? {},
+    }
+    deviceError = null
+    const attempt = loadEngine(config).then(
+      async (loaded) => {
+        const previous = engine
+        engine = loaded
+        engineKey = key
+        loading = null
+        if (previous && previous !== loaded) await previous.release().catch(() => undefined)
+        if (destroyed) await loaded.release().catch(() => undefined)
+        return loaded
+      },
+      (err: unknown) => {
+        loading = null
+        deviceError = codeText(err)
+        throw err
+      },
+    )
+    loading = attempt
+    return attempt
+  }
+
+  const preload = () => {
+    if (options.preload === false) return
+    startLoad().catch((err: unknown) => options.onError?.(err instanceof Error ? err : new Error(String(err))))
+  }
+
+  function deviceState(): DeviceState {
+    const e = engine
+    if (e === null || lease === null || manifestUrl === null || engineKey !== keyOf(lease.claims, manifestUrl)) {
+      return { ready: false, backend: null, perCropMs: Number.NaN }
+    }
+    return { ready: true, backend: e.info.backend, perCropMs: e.info.perCropMs }
+  }
+
+  async function setLease(grant: LeaseGrant): Promise<Lease> {
+    if (destroyed) throw new ScannerError('INVALID_OPTIONS', 'the identifier was destroyed')
+    if (typeof grant?.token !== 'string' || typeof grant.manifestUrl !== 'string') {
+      throw new ScannerError('INVALID_OPTIONS', 'a lease grant is { token, manifestUrl }')
+    }
+    const verified = await verifyLease(grant.token, {
+      publicKeys: options.leasePublicKeys,
+      origin,
+      domains: [options.domain],
+      now: Math.floor(now() / 1000),
+      ...(options.verify ? { verify: options.verify } : {}),
+    })
+    let url: string
+    try {
+      url = new URL(grant.manifestUrl, defaultOrigin() ?? undefined).href
+    } catch {
+      throw new ScannerError('INVALID_OPTIONS', `manifestUrl is not a URL: ${grant.manifestUrl}`)
+    }
+    lease = verified
+    manifestUrl = url
+    // Every lease reports at least once (the renewal gate), used or not.
+    await (await meterReady).touch(verified.claims.jti, session)
+    preload()
+    return verified
+  }
+
+  const aborted = (): IdentifyOutcome => ({ ok: false, reason: 'unavailable', detail: 'aborted' })
+
+  /** Resolves with the device's answer, or `null` when the caller aborted first. */
+  async function onDevice(crops: readonly Blob[], top: number, signal: AbortSignal | undefined): Promise<IdentifyResult[] | null> {
+    const work = startLoad().then((e) => e.identify(crops, top))
+    if (!signal) return work
+    if (signal.aborted) return null
+    return new Promise((resolve, reject) => {
+      const onAbort = () => resolve(null)
+      signal.addEventListener('abort', onAbort, { once: true })
+      work.then(
+        (r) => {
+          signal.removeEventListener('abort', onAbort)
+          resolve(r)
+        },
+        (e: unknown) => {
+          signal.removeEventListener('abort', onAbort)
+          reject(e)
+        },
+      )
+    })
+  }
+
+  async function identify(crops: readonly Blob[], call: IdentifyCallOptions = {}): Promise<IdentifyOutcome> {
+    try {
+      if (destroyed) return { ok: false, reason: 'unavailable', detail: 'INVALID_OPTIONS: the identifier was destroyed' }
+      if (!Array.isArray(crops) || crops.length > MAX_CROPS_PER_REQUEST) {
+        return { ok: false, reason: 'rejected', detail: `INVALID_OPTIONS: at most ${MAX_CROPS_PER_REQUEST} crops per call` }
+      }
+      const top = call.top ?? DEFAULT_TOP
+      if (!Number.isInteger(top) || top < 1 || top > MAX_TOP) return { ok: false, reason: 'rejected', detail: `INVALID_OPTIONS: top must be 1..${MAX_TOP}` }
+      const sessionId = call.session ?? session
+      if (!SESSION.test(sessionId)) return { ok: false, reason: 'rejected', detail: 'INVALID_OPTIONS: session must be 1..128 printable characters' }
+      if (call.signal?.aborted) return aborted()
+
+      if (initialLease) await initialLease
+      const current = lease
+      if (!current) return { ok: false, reason: 'rejected', detail: 'LEASE_INVALID: no lease is set' }
+      if (Math.floor(now() / 1000) >= current.claims.exp) return { ok: false, reason: 'rejected', detail: 'LEASE_EXPIRED: renew the lease' }
+      const meter = await meterReady
+      if (meter.exhausted(current.claims)) return { ok: false, reason: 'rejected', detail: 'ALLOWANCE_EXHAUSTED: renew the lease' }
+      if (crops.length === 0) return { ok: true, modelVersion: current.claims.modelVersion, results: [], source: 'device' }
+
+      const device = deviceState()
+      const serverBlocked = endpoint === null ? 'no serverUrl' : health.blocked(current.claims.jti, now(), online())
+      const route = chooseRoute({ mode, device, serverBlocked, slowDeviceBudgetMs: budget })
+
+      let results: readonly IdentifyResult[] | null = null
+      let source: 'device' | 'server' = 'device'
+      let serverFailure: ServerAnswer | null = null
+      if (route === 'server' && endpoint !== null) {
+        const answer = await postIdentify({
+          endpoint,
+          crops,
+          token: current.token,
+          top,
+          session: sessionId,
+          ...(call.purpose ? { purpose: call.purpose } : {}),
+          timeoutMs: serverDeadline(device, crops.length, serverTimeoutMs),
+          ...(call.signal ? { signal: call.signal } : {}),
+          fetch: doFetch,
+        })
+        const checked: ServerAnswer =
+          answer.ok && answer.modelVersion !== current.claims.modelVersion
+            ? { ok: false, kind: 'malformed', detail: `answer is model ${answer.modelVersion}, the lease is ${current.claims.modelVersion}` }
+            : answer
+        health.record(checked, current.claims.jti, now())
+        if (checked.ok) {
+          results = checked.results
+          source = 'server'
+        } else if (checked.kind === 'aborted') {
+          return aborted()
+        } else {
+          serverFailure = checked
+        }
+      }
+
+      if (results === null) {
+        try {
+          results = await onDevice(crops, top, call.signal)
+        } catch (err) {
+          const why = codeText(err)
+          if (serverFailure?.ok === false && serverFailure.kind === 'timeout') return { ok: false, reason: 'timeout', detail: `${serverFailure.detail}; device: ${why}` }
+          const reason = err instanceof ScannerError && err.code === 'INVALID_OPTIONS' ? 'rejected' : 'unavailable'
+          return { ok: false, reason, detail: serverFailure?.ok === false ? `${serverFailure.detail}; device: ${why}` : why }
+        }
+        if (results === null) return aborted()
+      }
+
+      await meter.record({ lease: current.claims, session: sessionId, purpose: call.purpose, results })
+      return { ok: true, modelVersion: current.claims.modelVersion, results, source }
+    } catch (err) {
+      return { ok: false, reason: 'unavailable', detail: codeText(err) }
+    }
+  }
+
+  const identifier: Identifier = {
+    identify,
+    setLease,
+    get session() {
+      return session
+    },
+    newSession() {
+      session = randomId()
+      return session
+    },
+    async prepare() {
+      return (await startLoad()).info
+    },
+    status() {
+      const claims = lease?.claims ?? null
+      const ready = deviceState().ready
+      return {
+        lease: claims,
+        device: ready ? 'ready' : loading ? 'loading' : deviceError ? 'failed' : 'idle',
+        deviceInfo: ready && engine ? engine.info : null,
+        deviceError,
+        serverPaused: endpoint === null ? 'no serverUrl' : health.blocked(claims?.jti ?? null, now(), online()),
+      }
+    },
+    async drainUsage(deliver) {
+      return (await meterReady).drain(deliver)
+    },
+    async pendingUsage() {
+      return (await meterReady).pending()
+    },
+    async leaseRequest(previousLeaseId) {
+      return (await meterReady).leaseRequest(previousLeaseId === undefined ? (lease?.claims.jti ?? null) : previousLeaseId)
+    },
+    async destroy() {
+      destroyed = true
+      const e = engine
+      engine = null
+      engineKey = null
+      await e?.release().catch(() => undefined)
+    },
+  }
+
+  if (options.lease) {
+    initialLease = setLease(options.lease).then(
+      () => {
+        initialLease = null
+      },
+      (err: unknown) => {
+        initialLease = null
+        options.onError?.(err instanceof Error ? err : new Error(String(err)))
+      },
+    )
+  }
+  return identifier
+}

package/src/identify/manifest.ts

@@ -0,0 +1,240 @@
+/**
+ * The model-and-index manifest of one shard, as `ml/src/dejadex_ml/shard_export.py`
+ * writes it (`manifest_<domain>.json`). It names every file the device
+ * downloads with its SHA-256 and size, and carries the values the SDK decides
+ * with, so none of them is hard-coded here:
+ *
+ *   { format: 1, modelVersion, indexVersion, shard, rows, dims, dtype: "fp16",
+ *     notACardBelow, confidentMargin, checksum: "sha256:<index>",
+ *     preprocessing: { width, height, resize: "pil-bilinear", mean, std, orientations },
+ *     embedding: { input, output, token },
+ *     files: { index: File, ids: File, models: [ File & { precision, licence } ] } }
+ *
+ *   File = { path, sha256, size }; `path` resolves against the manifest's URL,
+ *   so a manifest may list relative paths or absolute (signed) URLs.
+ *
+ * The lease's manifest URL carries a Cloud CDN prefix signature over its
+ * pair's directory (`URLPrefix`, `Expires`, `KeyName`, `Signature`). Resolving
+ * a relative path drops the query, so the signature is carried onto each file
+ * URL that falls under the signed prefix, on the same origin, and onto no
+ * other: a file elsewhere never sees this lease's signature.
+ */
+import { ScannerError } from '../errors.js'
+import type { Orientation } from './preprocess.js'
+
+export interface ManifestFile {
+  /** Absolute, resolved against the manifest's URL; carries its signature when under the signed prefix. */
+  readonly url: string
+  readonly sha256: string
+  readonly size: number
+}
+
+export type ModelPrecision = 'fp16' | 'fp32'
+
+export interface ManifestModel extends ManifestFile {
+  readonly precision: ModelPrecision
+  readonly licence: string
+}
+
+export interface Manifest {
+  readonly modelVersion: string
+  readonly indexVersion: string
+  readonly shard: string
+  readonly rows: number
+  readonly dims: number
+  readonly notACardBelow: number
+  readonly confidentMargin: number
+  readonly preprocessing: {
+    readonly width: number
+    readonly height: number
+    readonly mean: readonly [number, number, number]
+    readonly std: readonly [number, number, number]
+    readonly orientations: readonly Orientation[]
+  }
+  readonly embedding: { readonly input: string; readonly output: string; readonly token: number }
+  readonly index: ManifestFile
+  readonly ids: ManifestFile
+  readonly models: readonly ManifestModel[]
+}
+
+/** Licences a shipped model may carry (closed commercial distribution). */
+export const LICENCE_ALLOWLIST: readonly string[] = ['Apache-2.0', 'MIT', 'BSD-2-Clause', 'BSD-3-Clause']
+
+const SHA256 = /^[0-9a-f]{64}$/
+
+const bad = (why: string): ScannerError => new ScannerError('MODEL_INTEGRITY', `manifest: ${why}`)
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0
+const posInt = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) > 0
+const cosine = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= -1 && v <= 1
+
+function triple(v: unknown, name: string): readonly [number, number, number] {
+  if (!Array.isArray(v) || v.length !== 3 || !v.every((x) => typeof x === 'number' && Number.isFinite(x))) {
+    throw bad(`${name} must be three numbers`)
+  }
+  return [v[0], v[1], v[2]] as const
+}
+
+/** The four signing parameters, in Cloud CDN's order. */
+const SIGNING_PARAMS = ['URLPrefix', 'Expires', 'KeyName', 'Signature'] as const
+
+export interface SignedPrefix {
+  /** The decoded `URLPrefix`: scheme, host and path. */
+  readonly prefix: string
+  /** `URLPrefix=…&Expires=…&KeyName=…&Signature=…`, the values exactly as received. */
+  readonly query: string
+}
+
+/** base64url (padded or not) to text; null when it is not base64url of UTF-8. */
+function base64urlText(value: string): string | null {
+  if (!/^[A-Za-z0-9_-]+={0,2}$/.test(value)) return null
+  try {
+    const b64 = value.replace(/=+$/, '').replace(/-/g, '+').replace(/_/g, '/')
+    const bin = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4))
+    return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)))
+  } catch {
+    return null
+  }
+}
+
+/** The raw values of the signing parameters in a query, undecoded. */
+function signingValues(search: string): Map<string, string[]> {
+  const found = new Map<string, string[]>()
+  for (const part of search.replace(/^\?/, '').split('&')) {
+    const eq = part.indexOf('=')
+    const name = eq < 0 ? part : part.slice(0, eq)
+    if ((SIGNING_PARAMS as readonly string[]).includes(name)) found.set(name, [...(found.get(name) ?? []), eq < 0 ? '' : part.slice(eq + 1)])
+  }
+  return found
+}
+
+/**
+ * The prefix signature a manifest URL carries, or null when it carries none
+ * (or a malformed one). The raw query is read, never `URLSearchParams`, so
+ * the values, `=` padding included, travel byte for byte.
+ */
+export function signedPrefixOf(manifestUrl: string): SignedPrefix | null {
+  let url: URL
+  try {
+    url = new URL(manifestUrl)
+  } catch {
+    return null
+  }
+  const found = signingValues(url.search)
+  const values: string[] = []
+  for (const p of SIGNING_PARAMS) {
+    const v = found.get(p)
+    if (v === undefined || v.length !== 1 || v[0] === '') return null
+    values.push(v[0] as string)
+  }
+  const prefix = base64urlText(values[0] as string)
+  if (prefix === null) return null
+  let prefixUrl: URL
+  try {
+    prefixUrl = new URL(prefix)
+  } catch {
+    return null
+  }
+  if (prefixUrl.protocol !== 'https:' && prefixUrl.protocol !== 'http:') return null
+  return { prefix, query: SIGNING_PARAMS.map((p, i) => `${p}=${values[i] as string}`).join('&') }
+}
+
+/**
+ * `url` with the signing query added when it lies under the signed prefix and
+ * on the prefix's origin; anything else is returned unchanged, so another
+ * host or another pair's directory never receives this signature. A URL that
+ * already carries signing parameters (an absolute signed URL) keeps its own.
+ */
+export function carrySignature(url: string, signed: SignedPrefix | null): string {
+  if (signed === null) return url
+  const u = new URL(url)
+  if (u.origin !== new URL(signed.prefix).origin) return url
+  if (!`${u.origin}${u.pathname}`.startsWith(signed.prefix)) return url
+  if (signingValues(u.search).size > 0) return url
+  return `${u.origin}${u.pathname}${u.search === '' ? '?' : `${u.search}&`}${signed.query}${u.hash}`
+}
+
+function file(v: unknown, name: string, base: string, signed: SignedPrefix | null): ManifestFile {
+  if (!isRecord(v)) throw bad(`files.${name} is missing`)
+  if (!nonEmpty(v.path)) throw bad(`files.${name}.path is missing`)
+  if (typeof v.sha256 !== 'string' || !SHA256.test(v.sha256)) throw bad(`files.${name}.sha256 is not a SHA-256 hex digest`)
+  if (!posInt(v.size)) throw bad(`files.${name}.size is not a positive integer`)
+  let url: string
+  try {
+    url = new URL(v.path, base).href
+  } catch {
+    throw bad(`files.${name}.path does not resolve against ${base}`)
+  }
+  return { url: carrySignature(url, signed), sha256: v.sha256, size: v.size }
+}
+
+/** Validates a parsed manifest document. `manifestUrl` is what relative paths resolve against. */
+export function parseManifest(doc: unknown, manifestUrl: string): Manifest {
+  if (!isRecord(doc)) throw bad('not a JSON object')
+  if (doc.format !== 1) throw bad(`format ${String(doc.format)} is not supported`)
+  const { modelVersion, indexVersion, shard, rows, dims, dtype, notACardBelow, confidentMargin, checksum } = doc
+  if (!nonEmpty(modelVersion) || !nonEmpty(indexVersion) || !nonEmpty(shard)) throw bad('modelVersion, indexVersion and shard are required')
+  if (!posInt(rows) || !posInt(dims)) throw bad('rows and dims must be positive integers')
+  if (dtype !== 'fp16') throw bad(`dtype ${String(dtype)} is not supported`)
+  if (!cosine(notACardBelow) || !cosine(confidentMargin)) throw bad('notACardBelow and confidentMargin must be cosines')
+
+  const p = doc.preprocessing
+  if (!isRecord(p)) throw bad('preprocessing is missing')
+  if (p.resize !== 'pil-bilinear') throw bad(`resize ${String(p.resize)} is not supported`)
+  if (!posInt(p.width) || !posInt(p.height)) throw bad('preprocessing width and height must be positive integers')
+  const orientations = p.orientations
+  if (
+    !Array.isArray(orientations) ||
+    orientations.length === 0 ||
+    !orientations.every((o) => o === 0 || o === 180) ||
+    new Set(orientations).size !== orientations.length
+  ) {
+    throw bad('orientations must list 0 and/or 180')
+  }
+
+  const e = doc.embedding
+  if (!isRecord(e) || !nonEmpty(e.input) || !nonEmpty(e.output) || !Number.isSafeInteger(e.token) || (e.token as number) < 0) {
+    throw bad('embedding must name input, output and token')
+  }
+
+  const files = doc.files
+  if (!isRecord(files)) throw bad('files is missing')
+  const signed = signedPrefixOf(manifestUrl)
+  const index = file(files.index, 'index', manifestUrl, signed)
+  if (checksum !== `sha256:${index.sha256}`) throw bad('checksum does not match files.index.sha256')
+  const ids = file(files.ids, 'ids', manifestUrl, signed)
+  if (!Array.isArray(files.models) || files.models.length === 0) throw bad('files.models lists no model')
+  const models = files.models.map((m, i): ManifestModel => {
+    if (!isRecord(m)) throw bad(`files.models[${i}] is not an object`)
+    if (m.precision !== 'fp16' && m.precision !== 'fp32') {
+      throw bad(`files.models[${i}].precision ${String(m.precision)} is not shipped (fp16 or fp32)`)
+    }
+    if (typeof m.licence !== 'string' || !LICENCE_ALLOWLIST.includes(m.licence)) {
+      throw bad(`files.models[${i}].licence ${String(m.licence)} is outside the allowlist`)
+    }
+    return { ...file(m, `models[${i}]`, manifestUrl, signed), precision: m.precision, licence: m.licence }
+  })
+  if (new Set(models.map((m) => m.precision)).size !== models.length) throw bad('one model file per precision')
+
+  return {
+    modelVersion,
+    indexVersion,
+    shard,
+    rows,
+    dims,
+    notACardBelow,
+    confidentMargin,
+    preprocessing: {
+      width: p.width,
+      height: p.height,
+      mean: triple(p.mean, 'preprocessing.mean'),
+      std: triple(p.std, 'preprocessing.std'),
+      orientations: orientations as Orientation[],
+    },
+    embedding: { input: e.input, output: e.output, token: e.token as number },
+    index,
+    ids,
+    models,
+  }
+}