@wavehouse/chtypes 0.5.2 → 1.0.0

package/dist/ocifetch/dsse.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Trust (`docs/guides/fetch-v1.md` §4): verifying one Sigstore bundle v0.3 by
+ * hand — never a Sigstore client library, which cannot verify a key-only
+ * bundle at all (`layout-v2.md` §4.3). `node:crypto`'s `verify(null, …)` is
+ * ed25519 (no digest algorithm to name), matching Go `crypto/ed25519`,
+ * Python's own RFC 8032 verifier and Rust's `ed25519-dalek` — the primitive
+ * every binding already ships for v0.
+ *
+ * The split this module enforces (guide §4): a bundle whose SIGNATURE does
+ * not verify under any trusted key is simply "not this one" — a caller tries
+ * the next referrer and only reports `UNTRUSTED` once every candidate has
+ * failed this way. A bundle whose signature DOES verify but whose STATEMENT
+ * fails a content check (wrong predicateType, wrong subject, wrong platform,
+ * wrong version, a duplicate JSON key) is `CORRUPT` **immediately** — an
+ * authentically-signed statement that asserts the wrong thing is a real
+ * inconsistency, never something to paper over by trying another referrer.
+ */
+import type { RequestOptions } from './http.js';
+import type { ArtifactPredicate, Statement, TrustedKey } from './types.js';
+/**
+ * `bytes` as a plain JS value, refusing a duplicate key **anywhere** in the
+ * document (guide §4's "a duplicate key anywhere in the statement's JSON is
+ * CORRUPT") — `../json.ts`'s parser keeps every key/value pair, duplicates
+ * included, specifically so a caller can detect this; `JSON.parse` would
+ * silently keep only the last and could never see it.
+ */
+export declare function parseJsonNoDuplicates(bytes: Buffer): unknown;
+/** DSSE's pre-authentication encoding (PAE): `DSSEv1 LEN(type) SP type LEN(body) SP body`. */
+/** A key's id: `sha256-first16hex`, the first 16 hex characters of sha256 over the raw 32-byte public key (`spec/fetch-v1/constants.json`, `trust.keyid_algorithm`). */
+export declare function keyIdOfRawKey(publicKeyHex: string): string;
+export declare function dssePAE(payloadType: string, payload: Buffer): Buffer;
+/** Verifies one ed25519 signature over `message` against a raw 32-byte public key given as hex. */
+export declare function verifyEd25519(publicKeyHex: string, message: Buffer, signature: Buffer): boolean;
+/**
+ * Attempts to verify one bundle's DSSE signature against `trustedKeys`.
+ * Returns the trusted key id that verified it, or `undefined` when none did
+ * (including an unparseable bundle) — callers try the next candidate.
+ *
+ * This checks the SIGNATURE only. The caller parses and checks the
+ * statement's content afterward, using the authenticated `payload` bytes.
+ */
+export declare function verifyBundleSignature(bundleBytes: Buffer, trustedKeys: readonly TrustedKey[]): {
+    readonly signedBy: string;
+    readonly payload: Buffer;
+} | undefined;
+/**
+ * Parses an already-authenticated DSSE payload into a `Statement`, refusing
+ * a duplicate key anywhere (guide §4). Call this only after
+ * `verifyBundleSignature` has returned a `signedBy` for these exact bytes —
+ * parsing content checks are meaningless, and must never run, on bytes no
+ * signature has covered.
+ */
+export declare function parseStatement(payload: Buffer): Statement;
+/** `clickhouse_version`'s relationship to the original request spelling (guide §4). */
+export declare function versionWithinRequest(actualVersion: string, requestedSpelling: string): boolean;
+export interface ArtifactStatementCheck {
+    readonly os: string;
+    readonly arch: string;
+    /**
+     * Omit only when there is no one request to check against yet —
+     * `localverify.ts`'s local-blob scan verifies a pre-seeded entry on its
+     * own terms first, and the caller checks the resulting predicate's own
+     * `clickhouse_version` against whatever request prompted the scan
+     * afterward. Every other caller always supplies this.
+     */
+    readonly requestedSpelling?: string;
+}
+/**
+ * The full statement check for a **platform artifact** manifest (guide §4):
+ * predicateType, subject digest, `abi` (never `abi_revision`), os/arch and
+ * — when `check.requestedSpelling` is given — the version-within-request
+ * rule. Throws `ArtifactCorruptError` naming the first failing check.
+ */
+export declare function checkArtifactStatement(statement: Statement, expectedPredicateType: string, expectedLayerDigest: string, check: ArtifactStatementCheck): ArtifactPredicate;
+/**
+ * The reduced statement check `fetchSigned` uses for goldens and fixtures
+ * (guide §9): predicateType and subject digest only. These objects' own
+ * predicate shapes are not yet specified (blocked on the producer, plan
+ * §1.2), so `fetchSigned`'s caller reads `statement.predicate` itself.
+ */
+export declare function checkGenericStatement(statement: Statement, expectedPredicateType: string, expectedLayerDigest: string): void;
+export interface TrustResult {
+    readonly statement: Statement;
+    /** The trusted key id that verified it, or the fixture test key's id under `trust: "test"`. */
+    readonly signedBy: string;
+    /** The digest of the verified bundle blob itself (the referrer manifest's layer), as a lock pin's `bundle` records it. */
+    readonly bundleDigest: string;
+    /** The digest of the referrer manifest that carried the bundle. */
+    readonly bundleManifestDigest: string;
+}
+/**
+ * Finds, fetches and verifies a signature for `subjectDigest` within
+ * `repositoryRoot`: every referrer-API-or-fallback-tag candidate of
+ * `bundleArtifactType` (`referrers.ts`), each one's own manifest-then-layer
+ * hop (a referrer is itself a small OCI artifact; its layer blob holds the
+ * actual bundle JSON), tried in order until one verifies.
+ *
+ * `checkContent` is the caller's statement check (`checkArtifactStatement`
+ * for the main artifact, `checkGenericStatement` for `fetchSigned`) — it
+ * throws `ArtifactCorruptError` on a content mismatch, and that throw
+ * propagates immediately, out of this function, without trying further
+ * candidates (this module's header explains why).
+ *
+ * A candidate whose manifest or layer cannot even be fetched is skipped
+ * (treated the same as a signature that failed to verify) rather than
+ * aborting the whole search — a dangling or unreachable referrer on one
+ * mirror should not prevent trying another.
+ *
+ * Returns `undefined` when no candidate's signature verified under any
+ * trusted key at all — the caller raises `ArtifactUntrustedError` (or
+ * honors allow-unsigned).
+ */
+export declare function verifyAnyReferrerBundle(repositoryRoot: string, subjectDigest: string, bundleArtifactType: string, trustedKeys: readonly TrustedKey[], checkContent: (statement: Statement) => void, options: RequestOptions): Promise<TrustResult | undefined>;
+//# sourceMappingURL=dsse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dsse.d.ts","sourceRoot":"","sources":["../../src/ocifetch/dsse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK3E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAI5D;AAkCD,8FAA8F;AAC9F,wKAAwK;AACxK,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAiB/F;AAqDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAarE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAmCzD;AAID,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAQ9F;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,EACpB,qBAAqB,EAAE,MAAM,EAC7B,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,sBAAsB,GAC5B,iBAAiB,CA+BnB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAU5H;AAID,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0HAA0H;IAC1H,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,uBAAuB,CAC3C,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,YAAY,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,EAC5C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAkBlC"}

package/dist/ocifetch/dsse.js

@@ -0,0 +1,331 @@
+/**
+ * Trust (`docs/guides/fetch-v1.md` §4): verifying one Sigstore bundle v0.3 by
+ * hand — never a Sigstore client library, which cannot verify a key-only
+ * bundle at all (`layout-v2.md` §4.3). `node:crypto`'s `verify(null, …)` is
+ * ed25519 (no digest algorithm to name), matching Go `crypto/ed25519`,
+ * Python's own RFC 8032 verifier and Rust's `ed25519-dalek` — the primitive
+ * every binding already ships for v0.
+ *
+ * The split this module enforces (guide §4): a bundle whose SIGNATURE does
+ * not verify under any trusted key is simply "not this one" — a caller tries
+ * the next referrer and only reports `UNTRUSTED` once every candidate has
+ * failed this way. A bundle whose signature DOES verify but whose STATEMENT
+ * fails a content check (wrong predicateType, wrong subject, wrong platform,
+ * wrong version, a duplicate JSON key) is `CORRUPT` **immediately** — an
+ * authentically-signed statement that asserts the wrong thing is a real
+ * inconsistency, never something to paper over by trying another referrer.
+ */
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { items, parseJsonValue } from '../json.js';
+import { ABI_GENERATION, DSSE_MAX_SIGNATURES, DSSE_PAYLOAD_TYPE, SPELLING_REGEX } from './constants.gen.js';
+import { ArtifactCorruptError } from './errors.js';
+import { fetchBlobBytesByDigest, fetchManifestByDigest } from './oci.js';
+import { discoverSignatureCandidates } from './referrers.js';
+import { hexOfDigest } from './types.js';
+// -------------------------------------------------------------- strict JSON
+/**
+ * `bytes` as a plain JS value, refusing a duplicate key **anywhere** in the
+ * document (guide §4's "a duplicate key anywhere in the statement's JSON is
+ * CORRUPT") — `../json.ts`'s parser keeps every key/value pair, duplicates
+ * included, specifically so a caller can detect this; `JSON.parse` would
+ * silently keep only the last and could never see it.
+ */
+export function parseJsonNoDuplicates(bytes) {
+    const parsed = parseJsonValue(bytes);
+    if (parsed === null)
+        throw new ArtifactCorruptError('chtypes: not a single valid JSON value');
+    return toPlain(parsed);
+}
+function toPlain(json) {
+    switch (json.kind) {
+        case 'null':
+            return null;
+        case 'bool':
+            return json.raw[0] === 0x74;
+        case 'number': {
+            const n = Number(json.raw.toString('utf8'));
+            return Number.isFinite(n) ? n : json.raw.toString('utf8');
+        }
+        case 'string':
+            return json.bytes.toString('utf8');
+        case 'array':
+            return items(json).map(toPlain);
+        case 'object': {
+            const seen = new Set();
+            const obj = {};
+            for (let i = 0; i < json.keys.length; i++) {
+                const key = json.keys[i].toString('utf8');
+                if (seen.has(key))
+                    throw new ArtifactCorruptError(`chtypes: duplicate JSON key ${JSON.stringify(key)}`);
+                seen.add(key);
+                obj[key] = toPlain(json.items[i]);
+            }
+            return obj;
+        }
+        default:
+            return null;
+    }
+}
+// ------------------------------------------------------------------- ed25519
+/** DSSE's pre-authentication encoding (PAE): `DSSEv1 LEN(type) SP type LEN(body) SP body`. */
+/** A key's id: `sha256-first16hex`, the first 16 hex characters of sha256 over the raw 32-byte public key (`spec/fetch-v1/constants.json`, `trust.keyid_algorithm`). */
+export function keyIdOfRawKey(publicKeyHex) {
+    return createHash('sha256').update(Buffer.from(publicKeyHex, 'hex')).digest('hex').slice(0, 16);
+}
+export function dssePAE(payloadType, payload) {
+    const typeBytes = Buffer.from(payloadType, 'utf8');
+    return Buffer.concat([
+        Buffer.from('DSSEv1 ', 'ascii'),
+        Buffer.from(String(typeBytes.length), 'ascii'),
+        Buffer.from(' ', 'ascii'),
+        typeBytes,
+        Buffer.from(' ', 'ascii'),
+        Buffer.from(String(payload.length), 'ascii'),
+        Buffer.from(' ', 'ascii'),
+        payload,
+    ]);
+}
+/** Verifies one ed25519 signature over `message` against a raw 32-byte public key given as hex. */
+export function verifyEd25519(publicKeyHex, message, signature) {
+    const keyBytes = Buffer.from(publicKeyHex, 'hex');
+    if (keyBytes.length !== 32)
+        return false;
+    let keyObject;
+    try {
+        keyObject = createPublicKey({
+            key: { kty: 'OKP', crv: 'Ed25519', x: keyBytes.toString('base64url') },
+            format: 'jwk',
+        });
+    }
+    catch {
+        return false;
+    }
+    try {
+        return cryptoVerify(null, message, keyObject, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parses a Sigstore bundle v0.3's DSSE envelope. Lenient on purpose: a
+ * malformed or unexpectedly-shaped bundle among several referrer candidates
+ * is "not usable", not a hard failure — `null` lets the caller move on to
+ * the next candidate instead of raising `CORRUPT` for bytes nothing has
+ * authenticated yet.
+ */
+function parseEnvelope(bundleBytes) {
+    let bundle;
+    try {
+        bundle = JSON.parse(bundleBytes.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (bundle === null || typeof bundle !== 'object')
+        return null;
+    const envelope = bundle['dsseEnvelope'];
+    if (envelope === null || typeof envelope !== 'object')
+        return null;
+    const e = envelope;
+    const payloadType = e['payloadType'];
+    const payloadB64 = e['payload'];
+    const signaturesRaw = e['signatures'];
+    if (typeof payloadType !== 'string' || typeof payloadB64 !== 'string' || !Array.isArray(signaturesRaw))
+        return null;
+    let payload;
+    try {
+        payload = Buffer.from(payloadB64, 'base64');
+    }
+    catch {
+        return null;
+    }
+    const signatures = [];
+    for (const row of signaturesRaw.slice(0, DSSE_MAX_SIGNATURES)) {
+        if (row === null || typeof row !== 'object')
+            continue;
+        const sigB64 = row['sig'];
+        const keyid = row['keyid'];
+        if (typeof sigB64 !== 'string')
+            continue;
+        try {
+            signatures.push({ sig: Buffer.from(sigB64, 'base64'), keyid: typeof keyid === 'string' ? keyid : undefined });
+        }
+        catch {
+            // Not valid base64 — skip this one signature, not the whole bundle.
+        }
+    }
+    return { payloadType, payload, signatures };
+}
+/**
+ * Attempts to verify one bundle's DSSE signature against `trustedKeys`.
+ * Returns the trusted key id that verified it, or `undefined` when none did
+ * (including an unparseable bundle) — callers try the next candidate.
+ *
+ * This checks the SIGNATURE only. The caller parses and checks the
+ * statement's content afterward, using the authenticated `payload` bytes.
+ */
+export function verifyBundleSignature(bundleBytes, trustedKeys) {
+    const envelope = parseEnvelope(bundleBytes);
+    if (envelope === null)
+        return undefined;
+    if (envelope.payloadType !== DSSE_PAYLOAD_TYPE)
+        return undefined;
+    const pae = dssePAE(envelope.payloadType, envelope.payload);
+    for (const sig of envelope.signatures) {
+        for (const key of trustedKeys) {
+            if (verifyEd25519(key.ed25519Hex, pae, sig.sig)) {
+                return { signedBy: key.keyid, payload: envelope.payload };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Parses an already-authenticated DSSE payload into a `Statement`, refusing
+ * a duplicate key anywhere (guide §4). Call this only after
+ * `verifyBundleSignature` has returned a `signedBy` for these exact bytes —
+ * parsing content checks are meaningless, and must never run, on bytes no
+ * signature has covered.
+ */
+export function parseStatement(payload) {
+    const value = parseJsonNoDuplicates(payload);
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ArtifactCorruptError('chtypes: the DSSE payload is not a JSON object');
+    }
+    const v = value;
+    const type = v['_type'];
+    const predicateType = v['predicateType'];
+    const predicate = v['predicate'];
+    const subject = v['subject'];
+    if (typeof type !== 'string' || typeof predicateType !== 'string') {
+        throw new ArtifactCorruptError('chtypes: the statement is missing _type or predicateType');
+    }
+    if (predicate === null || typeof predicate !== 'object' || Array.isArray(predicate)) {
+        throw new ArtifactCorruptError('chtypes: the statement predicate is not an object');
+    }
+    if (!Array.isArray(subject) || subject.length === 0) {
+        throw new ArtifactCorruptError('chtypes: the statement names no subject');
+    }
+    const parsedSubjects = subject.map((s) => {
+        if (s === null || typeof s !== 'object')
+            throw new ArtifactCorruptError('chtypes: a statement subject is not an object');
+        const row = s;
+        const digest = row['digest'];
+        const name = row['name'];
+        if (digest === null || typeof digest !== 'object')
+            throw new ArtifactCorruptError('chtypes: a subject has no digest');
+        const sha256 = digest['sha256'];
+        if (typeof sha256 !== 'string')
+            throw new ArtifactCorruptError('chtypes: a subject digest has no sha256');
+        return { name: typeof name === 'string' ? name : '', digest: { sha256 } };
+    });
+    return {
+        _type: type,
+        predicateType,
+        predicate: predicate,
+        subject: parsedSubjects,
+    };
+}
+// --------------------------------------------------------- content checking
+/** `clickhouse_version`'s relationship to the original request spelling (guide §4). */
+export function versionWithinRequest(actualVersion, requestedSpelling) {
+    const actual = actualVersion.split('.');
+    const requested = requestedSpelling.split('.');
+    if (requested.length > actual.length)
+        return false;
+    for (let i = 0; i < requested.length; i++) {
+        if (requested[i] !== actual[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * The full statement check for a **platform artifact** manifest (guide §4):
+ * predicateType, subject digest, `abi` (never `abi_revision`), os/arch and
+ * — when `check.requestedSpelling` is given — the version-within-request
+ * rule. Throws `ArtifactCorruptError` naming the first failing check.
+ */
+export function checkArtifactStatement(statement, expectedPredicateType, expectedLayerDigest, check) {
+    if (statement.predicateType !== expectedPredicateType) {
+        throw new ArtifactCorruptError(`chtypes: statement predicateType ${JSON.stringify(statement.predicateType)} != expected ${JSON.stringify(expectedPredicateType)}`);
+    }
+    const expectedHex = hexOfDigest(expectedLayerDigest);
+    if (statement.subject[0]?.digest.sha256 !== expectedHex) {
+        throw new ArtifactCorruptError(`chtypes: statement subject digest does not match the manifest's own layer digest`);
+    }
+    const p = statement.predicate;
+    if (p['abi'] !== ABI_GENERATION) {
+        throw new ArtifactCorruptError(`chtypes: statement predicate.abi is ${JSON.stringify(p['abi'])}, not ${ABI_GENERATION}`);
+    }
+    if (p['os'] !== check.os || p['arch'] !== check.arch) {
+        throw new ArtifactCorruptError(`chtypes: statement predicate is for ${JSON.stringify(p['os'])}-${JSON.stringify(p['arch'])}, not ${check.os}-${check.arch}`);
+    }
+    const version = p['clickhouse_version'];
+    if (typeof version !== 'string') {
+        throw new ArtifactCorruptError(`chtypes: statement predicate.clickhouse_version ${JSON.stringify(version)} is not a string`);
+    }
+    if (check.requestedSpelling !== undefined && new RegExp(SPELLING_REGEX).test(check.requestedSpelling) && !versionWithinRequest(version, check.requestedSpelling)) {
+        throw new ArtifactCorruptError(`chtypes: statement predicate.clickhouse_version ${JSON.stringify(version)} does not lie within requested ${JSON.stringify(check.requestedSpelling)}`);
+    }
+    return p;
+}
+/**
+ * The reduced statement check `fetchSigned` uses for goldens and fixtures
+ * (guide §9): predicateType and subject digest only. These objects' own
+ * predicate shapes are not yet specified (blocked on the producer, plan
+ * §1.2), so `fetchSigned`'s caller reads `statement.predicate` itself.
+ */
+export function checkGenericStatement(statement, expectedPredicateType, expectedLayerDigest) {
+    if (statement.predicateType !== expectedPredicateType) {
+        throw new ArtifactCorruptError(`chtypes: statement predicateType ${JSON.stringify(statement.predicateType)} != expected ${JSON.stringify(expectedPredicateType)}`);
+    }
+    const expectedHex = hexOfDigest(expectedLayerDigest);
+    if (statement.subject[0]?.digest.sha256 !== expectedHex) {
+        throw new ArtifactCorruptError("chtypes: statement subject digest does not match the fetched object's own layer digest");
+    }
+}
+/**
+ * Finds, fetches and verifies a signature for `subjectDigest` within
+ * `repositoryRoot`: every referrer-API-or-fallback-tag candidate of
+ * `bundleArtifactType` (`referrers.ts`), each one's own manifest-then-layer
+ * hop (a referrer is itself a small OCI artifact; its layer blob holds the
+ * actual bundle JSON), tried in order until one verifies.
+ *
+ * `checkContent` is the caller's statement check (`checkArtifactStatement`
+ * for the main artifact, `checkGenericStatement` for `fetchSigned`) — it
+ * throws `ArtifactCorruptError` on a content mismatch, and that throw
+ * propagates immediately, out of this function, without trying further
+ * candidates (this module's header explains why).
+ *
+ * A candidate whose manifest or layer cannot even be fetched is skipped
+ * (treated the same as a signature that failed to verify) rather than
+ * aborting the whole search — a dangling or unreachable referrer on one
+ * mirror should not prevent trying another.
+ *
+ * Returns `undefined` when no candidate's signature verified under any
+ * trusted key at all — the caller raises `ArtifactUntrustedError` (or
+ * honors allow-unsigned).
+ */
+export async function verifyAnyReferrerBundle(repositoryRoot, subjectDigest, bundleArtifactType, trustedKeys, checkContent, options) {
+    const candidates = await discoverSignatureCandidates(repositoryRoot, subjectDigest, bundleArtifactType, options);
+    for (const candidate of candidates) {
+        let bundleBytes;
+        let referrerManifest;
+        try {
+            referrerManifest = await fetchManifestByDigest([repositoryRoot], candidate.digest, options);
+            bundleBytes = await fetchBlobBytesByDigest([repositoryRoot], referrerManifest.layer, options);
+        }
+        catch {
+            continue;
+        }
+        const verified = verifyBundleSignature(bundleBytes, trustedKeys);
+        if (verified === undefined)
+            continue;
+        const statement = parseStatement(verified.payload);
+        checkContent(statement);
+        return { statement, signedBy: verified.signedBy, bundleDigest: referrerManifest.layer.digest, bundleManifestDigest: referrerManifest.digest };
+    }
+    return undefined;
+}
+//# sourceMappingURL=dsse.js.map

package/dist/ocifetch/dsse.js.map

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

package/dist/ocifetch/ensure.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The seam (`docs/guides/fetch-v1.md` §9): `ensure`, `resolveInstalled`,
+ * `listInstalled`, `verifyInstalled`, `fetchSigned`. This is the only file
+ * that wires resolve (`oci.ts`), trust (`dsse.ts`), bytes (`unpack.ts`), the
+ * cache (`layout.ts`) and the lock (`lock.ts`) together; nothing outside
+ * `index.ts` calls into those modules directly.
+ */
+import type { FetchV1Options, PlatformKey, Resolved, VerifyResult } from './types.js';
+/**
+ * Never touches the network (guide §9). The source of truth is the
+ * immutable `unpacked/sha256/*\/verified.json` records (guide §6) — never
+ * `index.json` directly, though a pre-seeded `index.json` entry with no
+ * `verified.json` of its own yet is verified and unpacked from local blobs
+ * first (guide §1), exactly once, so every call after the first reads the
+ * same way `verified.json`-backed entries always have. Picks the newest
+ * match (version, then build, both compared as fixed-width strings per the
+ * guide's monotonicity rule) among records whose platform matches and whose
+ * `clickhouse_version` lies within `request`.
+ */
+export declare function resolveInstalled(request: string, platform: PlatformKey, options?: FetchV1Options): Promise<Resolved | undefined>;
+export declare function listInstalled(options?: FetchV1Options): Promise<readonly Resolved[]>;
+/** Re-checks every installed library's bytes against its own `verified.json` record (guide §9). */
+export declare function verifyInstalled(options?: FetchV1Options): Promise<readonly VerifyResult[]>;
+/**
+ * `ensure(request, options)`: resolve unless `frozen` or `offline`, verify
+ * trust, download and unpack bytes, install into the cache, optionally write
+ * a lock entry. See `docs/guides/fetch-v1.md` §9 for the full contract.
+ */
+export declare function ensure(request: string, options?: FetchV1Options): Promise<Resolved>;
+export interface FetchSignedResult {
+    readonly path: string;
+    readonly statement: unknown;
+    readonly digests: {
+        readonly manifest: string;
+        readonly layer: string;
+    };
+}
+/**
+ * The generic signed-artifact fetch (guide §9): `repository` is a full
+ * repository root (like a base — see `types.ts`'s `endpointUrl`), `ref` a
+ * tag or digest. Resolves the manifest, downloads and verifies its single
+ * layer, and verifies a referrer bundle of `predicateType` against it —
+ * `predicateType` and subject digest only (`checkGenericStatement`): these
+ * objects' predicate shapes are not yet specified (blocked on the producer,
+ * plan §1.2), so the caller reads `statement.predicate` itself. Returns the
+ * verified blob's path on disk (written into this layout's `blobs/`, not
+ * unpacked — unpacking is this fetch's caller's job, since goldens and
+ * fixtures are not necessarily tarballs).
+ *
+ * For `predicateType` = `PREDICATE_TYPE_GOLDENS`, `ref` is instead a
+ * PLATFORM manifest digest: the registry is append-only, so a corrected
+ * goldens set is a second goldens referrer of it, and the result is the
+ * highest-`revision` verified one (`goldens.ts`, guide §9).
+ */
+export declare function fetchSigned(repository: string, ref: string, predicateType: string, options?: FetchV1Options): Promise<FetchSignedResult>;
+/**
+ * The version spellings a repository publishes: `GET tags/list` from the first
+ * base that has the repository, every tag that is not a version spelling
+ * (`SPELLING_REGEX`: the `sha256-<hex>` referrers fallback tags, symbolic tags)
+ * dropped, the rest in ascending numeric order. A tag names a version, not a
+ * platform: whether a platform is offered is that tag's index, which only a
+ * resolve reads. A next page is followed through the `Link` header.
+ */
+export declare function listTags(options?: FetchV1Options): Promise<readonly string[]>;
+//# sourceMappingURL=ensure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensure.d.ts","sourceRoot":"","sources":["../../src/ocifetch/ensure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyDH,OAAO,KAAK,EAAqB,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAc,YAAY,EAAE,MAAM,YAAY,CAAC;AA6ErH;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAkB/B;AAmFD,wBAAsB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAQ9F;AAID,mGAAmG;AACnG,wBAAsB,eAAe,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAapG;AAID;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA0I7F;AAgQD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA+B5B;AA4HD;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CA2CvF"}