@wavehouse/chtypes 0.5.2 → 1.0.0

package/dist/ocifetch/oci.js

@@ -0,0 +1,323 @@
+/**
+ * Resolve (`docs/guides/fetch-v1.md` §3): the version spelling check, the
+ * multi-base tag GET returning an OCI image index, platform selection, and
+ * by-digest fetches (manifests and blobs) with their own integrity check
+ * (size + sha256 against the descriptor that named them — independent of,
+ * and prior to, the trust check in `dsse.ts`).
+ *
+ * Every by-digest fetch tries every configured base in order (guide §7 A5):
+ * a 404 moves to the next base, and on the **last** base a 404 is retried
+ * within the normal budget before `CHTYPES_SOURCE_UNREACHABLE` ("a listed
+ * digest that 404s is a host fault", never `UNPUBLISHED` — that verdict is
+ * for the tag alone).
+ */
+import { createHash } from 'node:crypto';
+import { asString, field, items, parseJsonValue } from '../json.js';
+import { MANIFEST_MAX_BYTES, MAX_UNPACKED_BYTES, MEDIA_TYPE_INDEX, MEDIA_TYPE_MANIFEST, SPELLING_REFUSE_HINT_REGEX } from './constants.gen.js';
+import { ArtifactCorruptError, ArtifactUnpublishedError, SourceIncompatibleError, SourceUnreachableError } from './errors.js';
+import { readFileUrl, requestBuffered, requestToSink } from './http.js';
+import { digestOfHex, endpointUrl, hexOfDigest, MANIFEST_ACCEPT_HEADER, platformInfo } from './types.js';
+/**
+ * Refuses the two documented spelling mistakes (a `v` prefix, a
+ * `-lts`/`-stable` channel suffix) before any network call (guide §3). A
+ * spelling that is simply not numeric is NOT refused here: the tag lookup
+ * answers for it (`CHTYPES_ARTIFACT_UNPUBLISHED` when nothing matches), the
+ * same path any arbitrary OCI tag takes — and the conformance trees publish
+ * symbolic tags such as `t-untrusted-key`. `SPELLING_REGEX` is a positive
+ * pattern used elsewhere (`versionWithinRequest`) to decide whether a
+ * resolved predicate's version is compared against the request at all.
+ */
+export function checkSpelling(spelling) {
+    if (new RegExp(SPELLING_REFUSE_HINT_REGEX).test(spelling)) {
+        throw new Error(`chtypes: ${JSON.stringify(spelling)} is not a v1 version spelling (no "v" prefix, no "-lts"/"-stable" suffix); ` +
+            'use the bare version, e.g. "26.8" or "26.8.15.10"');
+    }
+}
+/** A `GET …/manifests/<ref>` (the tag resolve) — always carries the manifest `Accept` header (delivery-side review: our host ignores it, a mirror may need it). */
+async function getJsonAt(url, maxBytes, options) {
+    const res = url.startsWith('file:')
+        ? await readFileUrl(url, maxBytes)
+        : await requestBuffered(url, { ...options, maxBytes, headers: { ...options.headers, accept: MANIFEST_ACCEPT_HEADER } });
+    if (res.status !== 200)
+        return { status: res.status, body: res.body, json: null };
+    const json = parseJsonValue(res.body);
+    return { status: res.status, body: res.body, json };
+}
+function descriptorField(json, key) {
+    const d = field(json, key);
+    if (d === undefined)
+        return undefined;
+    const digest = asString(field(d, 'digest'));
+    if (digest === '')
+        return undefined;
+    return { mediaType: asString(field(d, 'mediaType')), digest, size: numberField(d, 'size') };
+}
+function numberField(json, key) {
+    const v = field(json, key);
+    if (v === undefined || v.kind !== 'number')
+        return 0;
+    const n = Number(v.raw.toString('utf8'));
+    return Number.isFinite(n) ? n : 0;
+}
+function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * Parses an OCI image manifest's layer (exactly one, required) and config
+ * descriptors. `CHTYPES_SOURCE_INCOMPATIBLE` is reserved for a recognized-but-wrong
+ * media type (guide §3); unparseable JSON or a manifest that disagrees with
+ * its own shape (not exactly one layer) is `CORRUPT` — "a release that
+ * disagrees with itself", the same bucket a hash mismatch falls into.
+ */
+export function parseManifest(digest, bytes) {
+    const json = parseJsonValue(bytes);
+    if (json === null)
+        throw new ArtifactCorruptError(`chtypes: manifest ${digest} is not valid JSON`);
+    const mediaType = asString(field(json, 'mediaType'));
+    if (mediaType !== '' && mediaType !== MEDIA_TYPE_MANIFEST) {
+        throw new SourceIncompatibleError(`chtypes: manifest ${digest} has mediaType ${JSON.stringify(mediaType)}, not ${MEDIA_TYPE_MANIFEST}`);
+    }
+    const layers = items(field(json, 'layers'));
+    if (layers.length !== 1) {
+        throw new ArtifactCorruptError(`chtypes: manifest ${digest} has ${layers.length} layers, expected exactly 1`);
+    }
+    const layerJson = layers[0];
+    const layerDigest = asString(field(layerJson, 'digest'));
+    if (layerDigest === '')
+        throw new ArtifactCorruptError(`chtypes: manifest ${digest}'s layer has no digest`);
+    const layer = {
+        mediaType: asString(field(layerJson, 'mediaType')),
+        digest: layerDigest,
+        size: numberField(layerJson, 'size'),
+    };
+    const config = descriptorField(json, 'config');
+    return { digest, bytes, layer, config };
+}
+/**
+ * Verifies fetched bytes against the descriptor that named them (OCI content
+ * addressing — independent of signature trust, and checked **before** any
+ * decompression or JSON parsing of untrusted content). `size` is checked
+ * only when the descriptor carries one — a lock pin (schema 3) has a digest
+ * only, never a size. A mismatch is `CORRUPT`: "any hash mismatch along the
+ * chain" (the same verdict v0's `ArtifactCorruptError` names), never
+ * `SOURCE_INCOMPATIBLE`, which is reserved for a wrong media type.
+ */
+export function verifyDescriptor(descriptor, bytes, what) {
+    verifyDigestAndSize(descriptor, sha256Hex(bytes), bytes.length, what);
+}
+/**
+ * The same check as `verifyDescriptor`, for a caller that streamed the bytes
+ * through a hasher rather than holding them in one `Buffer` — `unpack.ts`'s
+ * layer download, which is never buffered whole in memory.
+ */
+export function verifyDigestAndSize(descriptor, actualSha256Hex, actualSize, what) {
+    if (descriptor.size !== undefined && actualSize !== descriptor.size) {
+        throw new ArtifactCorruptError(`chtypes: ${what} is ${actualSize} bytes, descriptor named ${descriptor.size}`);
+    }
+    if (actualSha256Hex !== hexOfDigest(descriptor.digest)) {
+        throw new ArtifactCorruptError(`chtypes: ${what}'s sha256 does not match its own descriptor`);
+    }
+}
+async function fetchByDigestAcrossBases(bases, pathFor, descriptor, what, defaultMaxBytes, options, extraHeaders) {
+    if (bases.length === 0)
+        throw new Error('chtypes: no base URLs configured');
+    let lastUnreachable;
+    for (let i = 0; i < bases.length; i++) {
+        const base = bases[i];
+        const isLast = i === bases.length - 1;
+        const url = endpointUrl(base, pathFor(descriptor.digest));
+        const maxBytes = descriptor.size ?? defaultMaxBytes;
+        let res;
+        try {
+            res = url.startsWith('file:')
+                ? await readFileUrl(url, maxBytes)
+                : await requestBuffered(url, {
+                    ...options,
+                    maxBytes,
+                    retryOn404: isLast,
+                    headers: { ...options.headers, ...extraHeaders },
+                });
+        }
+        catch (err) {
+            // A temporary error (guide §2: a timeout, a 5xx exhausted, a dead
+            // host) moves to the next base — never a verification failure, which
+            // propagates immediately (`mirror-no-failover-on-verify-fail`).
+            if (err instanceof SourceUnreachableError && !isLast) {
+                lastUnreachable = err;
+                continue;
+            }
+            throw err;
+        }
+        if (res.status === 404)
+            continue;
+        if (res.status !== 200)
+            throw new SourceUnreachableError(`chtypes: ${url} returned status ${res.status}`);
+        verifyDescriptor(descriptor, res.body, what);
+        return res.body;
+    }
+    if (lastUnreachable !== undefined)
+        throw lastUnreachable;
+    // Unreachable through an ordinary persistent 404 on the last base: that
+    // already throws `SourceUnreachableError` from inside `requestBuffered`
+    // (via `retryOn404`) before control returns here. This covers only an
+    // empty `bases` list.
+    throw new SourceUnreachableError(`chtypes: ${what} (${descriptor.digest}) was not found on any configured base`);
+}
+/**
+ * `GET manifests/<digest>`, tried across every base (guide §6: `--frozen`'s
+ * manifest fetch; also `fetchSigned`'s referrer manifest hop), always with
+ * the manifest `Accept` header (delivery-side review).
+ */
+export async function fetchManifestBytesByDigest(bases, descriptor, options) {
+    if (descriptor.size !== undefined && descriptor.size > MANIFEST_MAX_BYTES) {
+        throw new ArtifactCorruptError(`chtypes: manifest ${descriptor.digest}'s descriptor names ${descriptor.size} bytes, over the ${MANIFEST_MAX_BYTES}-byte manifest cap`);
+    }
+    return fetchByDigestAcrossBases(bases, (d) => `/manifests/${d}`, descriptor, `manifest ${descriptor.digest}`, MANIFEST_MAX_BYTES, options, {
+        accept: MANIFEST_ACCEPT_HEADER,
+    });
+}
+/** `GET blobs/<digest>`, tried across every base, fully buffered — a bundle, never the (potentially huge) library layer. */
+export async function fetchBlobBytesByDigest(bases, descriptor, options) {
+    return fetchByDigestAcrossBases(bases, (d) => `/blobs/${d}`, descriptor, `blob ${descriptor.digest}`, MAX_UNPACKED_BYTES, options);
+}
+/**
+ * `GET blobs/<digest>` straight into `sink` (`unpack.ts`'s hashing temp
+ * file) — the library layer, which is never buffered whole in memory. Tries
+ * every base in order, same as every other by-digest fetch in this module. A
+ * `file://` base has no streaming primitive of its own, so it is read whole
+ * and written to the sink in one call — acceptable because fixture layers
+ * are small test artifacts, never the multi-hundred-megabyte real ones.
+ */
+export async function fetchBlobToSink(bases, descriptor, options, sink) {
+    if (bases.length === 0)
+        throw new Error('chtypes: no base URLs configured');
+    const maxBytes = descriptor.size ?? MAX_UNPACKED_BYTES;
+    let lastUnreachable;
+    for (let i = 0; i < bases.length; i++) {
+        const base = bases[i];
+        const isLast = i === bases.length - 1;
+        const url = endpointUrl(base, `/blobs/${descriptor.digest}`);
+        try {
+            if (url.startsWith('file:')) {
+                const res = await readFileUrl(url, maxBytes);
+                if (res.status === 404)
+                    continue;
+                if (res.status !== 200)
+                    throw new SourceUnreachableError(`chtypes: ${url} returned status ${res.status}`);
+                sink.reset();
+                sink.write(res.body);
+                return;
+            }
+            const res = await requestToSink(url, { ...options, maxBytes, retryOn404: isLast }, sink);
+            if (res.status === 404)
+                continue;
+            if (res.status !== 200 && res.status !== 206)
+                throw new SourceUnreachableError(`chtypes: ${url} returned status ${res.status}`);
+            return;
+        }
+        catch (err) {
+            if (err instanceof SourceUnreachableError && !isLast) {
+                lastUnreachable = err;
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (lastUnreachable !== undefined)
+        throw lastUnreachable;
+    throw new SourceUnreachableError(`chtypes: blob ${descriptor.digest} was not found on any configured base`);
+}
+/** `fetchManifestBytesByDigest` plus parsing — `--frozen`'s and `fetchSigned`'s "give me this manifest" primitive. */
+export async function fetchManifestByDigest(bases, digest, options) {
+    const bytes = await fetchManifestBytesByDigest(bases, { mediaType: MEDIA_TYPE_MANIFEST, digest }, options);
+    return parseManifest(digest, bytes);
+}
+/**
+ * `GET manifests/<spelling>` across `bases` in order (guide §3, §7 A5's tag
+ * rule: a tag 404 moves to the next base, and every base 404ing is
+ * `UNPUBLISHED`), then the platform's manifest by digest across every base
+ * (mirrors may carry the same tag pointing at the same digest, so a base
+ * that served the index is not the only one asked for its blobs).
+ */
+export async function resolveTag(bases, spelling, platform, options) {
+    checkSpelling(spelling);
+    if (bases.length === 0)
+        throw new Error('chtypes: no base URLs configured');
+    const info = platformInfo(platform);
+    const triedBases = [];
+    for (let baseIndex = 0; baseIndex < bases.length; baseIndex++) {
+        const base = bases[baseIndex];
+        const isLastBase = baseIndex === bases.length - 1;
+        const url = endpointUrl(base, `/manifests/${spelling}`);
+        let status;
+        let body;
+        let json;
+        try {
+            ({ status, body, json } = await getJsonAt(url, MANIFEST_MAX_BYTES, options));
+        }
+        catch (err) {
+            // A temporary error (guide §2: a timeout, a 5xx exhausted, a dead
+            // host) moves to the next base, same as a tag 404 — never a
+            // verification failure, which propagates immediately.
+            if (err instanceof SourceUnreachableError && !isLastBase) {
+                triedBases.push(base);
+                continue;
+            }
+            throw err;
+        }
+        if (status === 404) {
+            triedBases.push(base);
+            continue;
+        }
+        if (status !== 200) {
+            // A persistent retryable status on the last base already threw from
+            // inside `requestBuffered`; anything reaching here (400, 418, …) is an
+            // anomaly this fetcher does not have a specific verdict for.
+            throw new SourceUnreachableError(`chtypes: ${url} returned status ${status}`);
+        }
+        if (json === null) {
+            throw new ArtifactCorruptError(`chtypes: ${url} did not return valid JSON`);
+        }
+        const mediaType = asString(field(json, 'mediaType'));
+        if (mediaType !== '' && mediaType !== MEDIA_TYPE_INDEX) {
+            throw new SourceIncompatibleError(`chtypes: ${url} has mediaType ${JSON.stringify(mediaType)}, not ${MEDIA_TYPE_INDEX}`);
+        }
+        const manifests = items(field(json, 'manifests'));
+        const matches = manifests.filter((m) => {
+            const p = field(m, 'platform');
+            return asString(field(p, 'os')) === info.os && asString(field(p, 'architecture')) === info.architecture;
+        });
+        if (matches.length === 0) {
+            const offered = manifests
+                .map((m) => {
+                const p = field(m, 'platform');
+                return `${asString(field(p, 'os'))}-${asString(field(p, 'architecture'))}`;
+            })
+                .filter((k) => k !== '-');
+            throw new ArtifactUnpublishedError(`chtypes: ${spelling} offers no manifest for ${platform}; the index offers: ${offered.join(', ') || '(none)'}`);
+        }
+        if (matches.length > 1) {
+            // `index-duplicate-platform`: the index disagrees with itself about
+            // which manifest is this platform's — `CORRUPT`, the plan's own
+            // annotation for this case.
+            throw new ArtifactCorruptError(`chtypes: ${spelling}'s index names ${platform} more than once`);
+        }
+        const d = matches[0];
+        const manifestDigest = asString(field(d, 'digest'));
+        if (manifestDigest === '')
+            throw new ArtifactCorruptError(`chtypes: ${spelling}'s ${platform} descriptor has no digest`);
+        const manifestDescriptor = {
+            mediaType: asString(field(d, 'mediaType')),
+            digest: manifestDigest,
+            size: numberField(d, 'size'),
+        };
+        if (manifestDescriptor.mediaType !== MEDIA_TYPE_MANIFEST) {
+            throw new SourceIncompatibleError(`chtypes: ${spelling}'s ${platform} descriptor has mediaType ${JSON.stringify(manifestDescriptor.mediaType)}, not ${MEDIA_TYPE_MANIFEST}`);
+        }
+        const manifestBytes = await fetchManifestBytesByDigest(bases, manifestDescriptor, options);
+        const manifest = parseManifest(manifestDigest, manifestBytes);
+        return { repositoryRoot: base, indexDigest: digestOfHex(sha256Hex(body)), indexBytes: body, manifest };
+    }
+    throw new ArtifactUnpublishedError(`chtypes: ${spelling} is unpublished: every base 404d the tag (${triedBases.join(', ')})`);
+}
+//# sourceMappingURL=oci.js.map

package/dist/ocifetch/oci.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oci.js","sourceRoot":"","sources":["../../src/ocifetch/oci.ts"],"names":[],"mappings":"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"}

package/dist/ocifetch/referrers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Referrer discovery (`docs/guides/fetch-v1.md` §4): the OCI referrers API,
+ * **and** the tag-schema fallback (`sha256-<hex>`) — both implemented, never
+ * only one, because which a host serves is a property of that host, not of
+ * this fetcher.
+ *
+ * **The fallback tag is consulted only when the referrers API's own answer
+ * has no bundle of the trusted signature artifactType** — an empty list, a
+ * list holding only other artifactTypes (goldens, say), or the API itself
+ * unsupported (errors, or any non-200). When the referrers API already
+ * names a candidate of that artifactType, the fallback tag is never fetched
+ * — this keeps the request count the same shape as Go, Python and Rust's
+ * lanes, which conformance cases assert on (a case can require "no fallback
+ * request" for a referrers-API-only host). A referrers-API 404 reads the
+ * same as "unsupported": fall back at once, with no retry — this is a
+ * discovery probe, not a promise that a specific digest exists (unlike a
+ * by-digest manifest/blob fetch, which does retry a 404 on the last base;
+ * `oci.ts`'s `retryOn404`).
+ */
+import { type RequestOptions } from './http.js';
+export interface ReferrerDescriptor {
+    readonly digest: string;
+    readonly mediaType: string;
+    readonly artifactType: string | undefined;
+    readonly size: number;
+}
+/** The fallback tag schema name for a digest, e.g. `sha256:ab12..` -> `sha256-ab12..`. */
+export declare function fallbackTagFor(digest: string): string;
+/**
+ * Every referrer of `artifactType` for `digest` within `repositoryRoot`,
+ * from the referrers API alone. `[]` whenever the API's own answer has no
+ * bundle of this `artifactType` — an empty list, a list of only other
+ * artifactTypes, a 404 (treated as "unsupported here", not retried — see
+ * this module's header), or any other error — and in every one of those
+ * cases `discoverSignatureCandidates` then also tries the fallback tag.
+ */
+export declare function discoverReferrers(repositoryRoot: string, digest: string, artifactType: string, options: RequestOptions): Promise<ReferrerDescriptor[]>;
+/**
+ * The fallback tag's own referrer list for `digest` (the tag-schema index,
+ * `GET manifests/<tag>` — always with the manifest `Accept` header), filtered
+ * the same way as the referrers API. Only ever called by
+ * `discoverSignatureCandidates` when the referrers API found nothing of the
+ * trusted artifactType.
+ */
+export declare function discoverFallbackTag(repositoryRoot: string, digest: string, artifactType: string, options: RequestOptions): Promise<ReferrerDescriptor[]>;
+/**
+ * The candidate list a caller should try verifying in order, stopping at
+ * the first success. Queries the referrers API first; the fallback tag is
+ * fetched **only** when the referrers API named no candidate of
+ * `artifactType` at all (see this module's header) — never unconditionally,
+ * so a referrers-API-only host sees exactly one discovery request, matching
+ * Go, Python and Rust.
+ */
+export declare function discoverSignatureCandidates(repositoryRoot: string, digest: string, artifactType: string, options: RequestOptions): Promise<ReferrerDescriptor[]>;
+//# sourceMappingURL=referrers.d.ts.map

package/dist/ocifetch/referrers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referrers.d.ts","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAgC,MAAM,WAAW,CAAC;AAG9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMrD;AAkDD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAe/B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAM/B;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAI/B"}

package/dist/ocifetch/referrers.js

@@ -0,0 +1,132 @@
+/**
+ * Referrer discovery (`docs/guides/fetch-v1.md` §4): the OCI referrers API,
+ * **and** the tag-schema fallback (`sha256-<hex>`) — both implemented, never
+ * only one, because which a host serves is a property of that host, not of
+ * this fetcher.
+ *
+ * **The fallback tag is consulted only when the referrers API's own answer
+ * has no bundle of the trusted signature artifactType** — an empty list, a
+ * list holding only other artifactTypes (goldens, say), or the API itself
+ * unsupported (errors, or any non-200). When the referrers API already
+ * names a candidate of that artifactType, the fallback tag is never fetched
+ * — this keeps the request count the same shape as Go, Python and Rust's
+ * lanes, which conformance cases assert on (a case can require "no fallback
+ * request" for a referrers-API-only host). A referrers-API 404 reads the
+ * same as "unsupported": fall back at once, with no retry — this is a
+ * discovery probe, not a promise that a specific digest exists (unlike a
+ * by-digest manifest/blob fetch, which does retry a 404 on the last base;
+ * `oci.ts`'s `retryOn404`).
+ */
+import { asString, field, items, parseJsonValue } from '../json.js';
+import { MANIFEST_MAX_BYTES, MAX_REFERRERS } from './constants.gen.js';
+import { ArtifactCorruptError } from './errors.js';
+import { readFileUrl, requestBuffered } from './http.js';
+import { endpointUrl, MANIFEST_ACCEPT_HEADER } from './types.js';
+/** The fallback tag schema name for a digest, e.g. `sha256:ab12..` -> `sha256-ab12..`. */
+export function fallbackTagFor(digest) {
+    const [algo, hex] = digest.split(':', 2);
+    if (algo !== 'sha256' || hex === undefined) {
+        throw new ArtifactCorruptError(`chtypes: cannot derive a fallback tag from digest ${JSON.stringify(digest)}`);
+    }
+    return `sha256-${hex}`;
+}
+async function getJson(url, maxBytes, options, extraHeaders) {
+    const res = url.startsWith('file:')
+        ? await readFileUrl(url, maxBytes)
+        : await requestBuffered(url, {
+            ...options,
+            maxBytes,
+            headers: { ...options.headers, ...extraHeaders },
+        });
+    if (res.status !== 200)
+        return { status: res.status, json: null };
+    const json = parseJsonValue(res.body);
+    if (json === null)
+        throw new ArtifactCorruptError(`chtypes: ${url} did not return valid JSON`);
+    return { status: res.status, json };
+}
+function descriptorsFromIndex(json) {
+    // A host may omit the index's own `mediaType`; the `manifests` array is
+    // read either way, so this is not itself a shape check (`oci.ts` checks
+    // media types where their presence is load-bearing).
+    const manifests = items(field(json, 'manifests'));
+    const out = [];
+    for (const m of manifests.slice(0, MAX_REFERRERS)) {
+        const digest = asString(field(m, 'digest'));
+        const descMediaType = asString(field(m, 'mediaType'));
+        const artifactTypeField = field(m, 'artifactType');
+        const size = numberField(m, 'size');
+        if (digest === '')
+            continue;
+        out.push({
+            digest,
+            mediaType: descMediaType,
+            artifactType: artifactTypeField === undefined ? undefined : asString(artifactTypeField),
+            size,
+        });
+    }
+    return out;
+}
+function numberField(json, key) {
+    const v = field(json, key);
+    if (v === undefined || v.kind !== 'number')
+        return 0;
+    const n = Number(v.raw.toString('utf8'));
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * Every referrer of `artifactType` for `digest` within `repositoryRoot`,
+ * from the referrers API alone. `[]` whenever the API's own answer has no
+ * bundle of this `artifactType` — an empty list, a list of only other
+ * artifactTypes, a 404 (treated as "unsupported here", not retried — see
+ * this module's header), or any other error — and in every one of those
+ * cases `discoverSignatureCandidates` then also tries the fallback tag.
+ */
+export async function discoverReferrers(repositoryRoot, digest, artifactType, options) {
+    const url = `${endpointUrl(repositoryRoot, `/referrers/${digest}`)}?artifactType=${encodeURIComponent(artifactType)}`;
+    const fromApi = [];
+    try {
+        const { status, json } = await getJson(url, MANIFEST_MAX_BYTES, options);
+        if (status === 200 && json !== null) {
+            for (const d of descriptorsFromIndex(json)) {
+                if (d.artifactType === artifactType)
+                    fromApi.push(d);
+            }
+        }
+    }
+    catch {
+        // The referrers API is not guaranteed on every host (mirrors) — read as
+        // "no candidates here", exactly as an empty or goldens-only answer would.
+    }
+    return fromApi;
+}
+/**
+ * The fallback tag's own referrer list for `digest` (the tag-schema index,
+ * `GET manifests/<tag>` — always with the manifest `Accept` header), filtered
+ * the same way as the referrers API. Only ever called by
+ * `discoverSignatureCandidates` when the referrers API found nothing of the
+ * trusted artifactType.
+ */
+export async function discoverFallbackTag(repositoryRoot, digest, artifactType, options) {
+    const tag = fallbackTagFor(digest);
+    const url = endpointUrl(repositoryRoot, `/manifests/${tag}`);
+    const { status, json } = await getJson(url, MANIFEST_MAX_BYTES, options, { accept: MANIFEST_ACCEPT_HEADER });
+    if (status !== 200 || json === null)
+        return [];
+    return descriptorsFromIndex(json).filter((d) => d.artifactType === artifactType);
+}
+/**
+ * The candidate list a caller should try verifying in order, stopping at
+ * the first success. Queries the referrers API first; the fallback tag is
+ * fetched **only** when the referrers API named no candidate of
+ * `artifactType` at all (see this module's header) — never unconditionally,
+ * so a referrers-API-only host sees exactly one discovery request, matching
+ * Go, Python and Rust.
+ */
+export async function discoverSignatureCandidates(repositoryRoot, digest, artifactType, options) {
+    const fromApi = await discoverReferrers(repositoryRoot, digest, artifactType, options);
+    if (fromApi.length > 0)
+        return fromApi;
+    return discoverFallbackTag(repositoryRoot, digest, artifactType, options);
+}
+//# sourceMappingURL=referrers.js.map

package/dist/ocifetch/referrers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"referrers.js","sourceRoot":"","sources":["../../src/ocifetch/referrers.ts"],"names":[],"mappings":"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"}