@wavehouse/chtypes 2.0.0-dev.1 → 2.0.0-dev.11

package/dist/ocifetch/resolve.js

@@ -0,0 +1,90 @@
+/**
+ * `chtypes resolve` (`docs/guides/fetch-v1.md` §3, "What a request resolves
+ * to"; public issue #493): what a line, a patch or an exact version resolves
+ * to on every platform the registry offers, each verified exactly as a fetch
+ * verifies it (§4), and never a layer downloaded. Offline it is the cache's
+ * answer instead, the lookup an open makes.
+ */
+import { noteIgnoredOverrides, offlineMode } from './channel.js';
+import { PLATFORMS } from './constants.gen.js';
+import { missingNotes, requestOptionsFor, resolveBases, resolveInstalled, verifyManifestTrust, withNotes } from './ensure.js';
+import { ArtifactMissingError, ArtifactUnpublishedError } from './errors.js';
+import { unwritable } from './faults.js';
+import { cacheRoot } from './layout.js';
+import { checkSpelling, fetchManifestBytesByDigest, parseManifest, resolveIndex, selectPlatformDescriptor } from './oci.js';
+/**
+ * What `spelling` resolves to, one `Resolution` per platform, in the
+ * constants' platform order. Online it resolves the index (through the dev
+ * channel's alias first, §3), and for each platform the index offers it
+ * fetches the manifest by digest and verifies its signed statement against the
+ * request (§4), exactly as `ensure` does; no layer is requested and nothing is
+ * written. A platform the index does not offer is left out, and an index that
+ * offers none of them is `ArtifactUnpublishedError`. Offline it answers from
+ * the cache: each platform's `resolveInstalled`, and `ArtifactMissingError`
+ * when no platform has an installed build. A refused spelling is refused
+ * first, before anything is read (`SpellingRefusedError`).
+ */
+export async function resolveBuilds(spelling, options = {}) {
+    noteIgnoredOverrides(options);
+    try {
+        return await resolveIn(spelling, options);
+    }
+    catch (err) {
+        // An offline lookup may verify a pre-seeded entry into the cache: a write
+        // that failed there is one class in every mode, as for `ensure`.
+        throw await unwritable(err, cacheRoot(options.cacheDir));
+    }
+}
+async function resolveIn(spelling, options) {
+    checkSpelling(spelling);
+    if (offlineMode(options.offline)) {
+        const resolutions = [];
+        for (const p of PLATFORMS) {
+            const hit = await resolveInstalled(spelling, p.key, options);
+            if (hit !== undefined) {
+                resolutions.push({ platform: p.key, version: hit.version, build: hit.build, manifest: hit.digests.manifest });
+            }
+        }
+        if (resolutions.length === 0) {
+            throw new ArtifactMissingError(withNotes(`chtypes: no installed artifact for ${spelling} on any platform, and --offline forbids a network fetch`, await missingNotes(options)));
+        }
+        return { resolutions, warnings: [] };
+    }
+    const bases = resolveBases(options);
+    const baseReqOptions = requestOptionsFor(options, bases);
+    const reqOptions = { ...baseReqOptions, maxBytes: 0 };
+    const index = await resolveIndex(bases, spelling, reqOptions);
+    const resolutions = [];
+    const warnings = [];
+    for (const p of PLATFORMS) {
+        let descriptor;
+        try {
+            descriptor = selectPlatformDescriptor(index, spelling, p.key);
+        }
+        catch (err) {
+            if (err instanceof ArtifactUnpublishedError)
+                continue; // the index does not offer this platform
+            throw err;
+        }
+        const manifest = parseManifest(descriptor.digest, await fetchManifestBytesByDigest(bases, descriptor, reqOptions));
+        // Under allow-unsigned with no verified statement, the version and build
+        // are the config blob's, as an unsigned install records them.
+        const verified = await verifyManifestTrust(index.repositoryRoot, manifest, index.aliasAbsent, p.key, spelling, options, baseReqOptions);
+        warnings.push(...verified.warnings);
+        resolutions.push({
+            platform: p.key,
+            version: stringMember(verified.predicate.clickhouse_version),
+            build: stringMember(verified.predicate.build),
+            manifest: manifest.digest,
+        });
+    }
+    if (resolutions.length === 0) {
+        throw new ArtifactUnpublishedError(`chtypes: the index for ${spelling} offers no platform this SDK knows`);
+    }
+    return { resolutions, warnings };
+}
+/** A predicate member read as the signed statement holds it: its text, or `''` for anything that is not a string. */
+function stringMember(v) {
+    return typeof v === 'string' ? v : '';
+}
+//# sourceMappingURL=resolve.js.map

package/dist/ocifetch/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/ocifetch/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC9H,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAmB,0BAA0B,EAAE,aAAa,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAoB7I;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,OAAO,GAAmB,EAAE;IAChF,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,iEAAiE;QACjE,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAuB;IAChE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,WAAW,GAAiB,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC7D,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YAChH,CAAC;QACH,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,oBAAoB,CAC5B,SAAS,CAAC,sCAAsC,QAAQ,yDAAyD,EAAE,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC,CAChJ,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,cAAc,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,EAAE,GAAG,cAAc,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACtD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,UAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,UAAU,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,wBAAwB;gBAAE,SAAS,CAAC,yCAAyC;YAChG,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,0BAA0B,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;QACnH,yEAAyE;QACzE,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;QACxI,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpC,WAAW,CAAC,IAAI,CAAC;YACf,QAAQ,EAAE,CAAC,CAAC,GAAG;YACf,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,kBAAkB,CAAC;YAC5D,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC;YAC7C,QAAQ,EAAE,QAAQ,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,wBAAwB,CAAC,0BAA0B,QAAQ,oCAAoC,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED,qHAAqH;AACrH,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/dist/ocifetch/retired.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A retired repository (`docs/guides/fetch-v1.md` §2, "A retired repository";
+ * public issue #571). The registry's operator answers every route of a
+ * retired repository with 410 Gone (`RETIRED_STATUSES`) and a short error
+ * document. That is permanent: `http.ts` never retries it and throws
+ * `SourceRetiredError`, which every loop over bases or candidates lets
+ * through, so the caller sees the URL that answered and the registry's own
+ * message, made safe to print by `retiredMessage`, the one function every
+ * binding has (`tests/fixtures/retired-message/cases.json` is the table all
+ * four answer alike).
+ */
+import type * as http from 'node:http';
+import { type Advisory, ArtifactRevokedError, type FetchV1Error, SourceRetiredError } from './errors.js';
+/** Is this status a retired repository's? */
+export declare function isRetiredStatus(status: number): boolean;
+/**
+ * The registry's own message in a retired repository's response body, made
+ * safe to print, or `null` when it sent none. `body` is what was read of it
+ * (at most `RETIRED_BODY_MAX_BYTES`). When it is UTF-8 JSON whose
+ * `errors[0].message` is a string, that string is the message: every code
+ * point in U+0000-U+001F, U+007F-U+009F, U+200E, U+200F, U+202A-U+202E and
+ * U+2066-U+2069 is removed, and the rest is cut to
+ * `RETIRED_MESSAGE_MAX_CODE_POINTS` code points, with U+2026 appended when it
+ * was cut. Nothing else is changed, and an empty result is no message.
+ */
+export declare function retiredMessage(body: Uint8Array): string | null;
+/**
+ * `text` made safe to print, the retired message's rule for every served
+ * string: every code point in U+0000-U+001F, U+007F-U+009F, U+200E, U+200F,
+ * U+202A-U+202E and U+2066-U+2069 removed, then cut to
+ * `RETIRED_MESSAGE_MAX_CODE_POINTS` code points with U+2026 appended when it was
+ * cut. A string holding a lone surrogate is not Unicode text and is `''`, as is
+ * one that is empty once made safe.
+ */
+export declare function sanitizeRetiredText(text: string): string;
+/** The error text for a retired repository's answer: the URL and status that answered, and the registry's message when it sent one. */
+export declare function retiredText(url: string, status: number, body: Uint8Array): string;
+/**
+ * A 410's body read as a revocation (guide, "Build-level revocation", "A `410`
+ * on a tag"): `undefined` unless it is UTF-8 JSON whose `errors[0].detail.revoked`
+ * is an object; otherwise that object's advisories, each field made safe, and one
+ * that is absent, not a string, empty once made safe or a lone surrogate left
+ * `''`. An entry that is not an object, or leaves every field empty, is skipped.
+ * A repeated key reads as its last value, and a byte order mark is not JSON.
+ * `tests/fixtures/revoked-410/cases.json` is the table all four bindings answer
+ * alike.
+ */
+export declare function revoked410(body: Uint8Array): readonly Advisory[] | undefined;
+/** What follows `<url> answered 410 Gone: ` for a revoked tag. */
+export declare function revoked410Text(advisories: readonly Advisory[]): string;
+/**
+ * The error for a 410 (guide §2): `ArtifactRevokedError` when `revocation` is on
+ * (generation 2) and the body's `errors[0].detail.revoked` is an object, else a
+ * retired repository's `SourceRetiredError`. Both are permanent.
+ */
+export declare function goneError(url: string, status: number, body: Uint8Array, revocation: boolean): FetchV1Error;
+/** Is `err` a 410's: `SourceRetiredError` or, under generation 2, `ArtifactRevokedError`? Either is permanent, so every loop over bases or candidates throws it at once. */
+export declare function isGone(err: unknown): err is SourceRetiredError | ArtifactRevokedError;
+/** At most `maxBytes` of a response body. A body that fails part way is no body. */
+export declare function readRetiredBody(stream: http.IncomingMessage, maxBytes: number): Promise<Buffer>;
+//# sourceMappingURL=retired.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retired.d.ts","sourceRoot":"","sources":["../../src/ocifetch/retired.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,KAAK,QAAQ,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzG,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvD;AAkCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAe9D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYxD;AAED,uIAAuI;AACvI,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAIjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,QAAQ,EAAE,GAAG,SAAS,CAmC5E;AAsBD,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,UAAU,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,GAAG,YAAY,CAY1G;AAED,4KAA4K;AAC5K,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,GAAG,oBAAoB,CAErF;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB/F"}

package/dist/ocifetch/retired.js

@@ -0,0 +1,236 @@
+/**
+ * A retired repository (`docs/guides/fetch-v1.md` §2, "A retired repository";
+ * public issue #571). The registry's operator answers every route of a
+ * retired repository with 410 Gone (`RETIRED_STATUSES`) and a short error
+ * document. That is permanent: `http.ts` never retries it and throws
+ * `SourceRetiredError`, which every loop over bases or candidates lets
+ * through, so the caller sees the URL that answered and the registry's own
+ * message, made safe to print by `retiredMessage`, the one function every
+ * binding has (`tests/fixtures/retired-message/cases.json` is the table all
+ * four answer alike).
+ */
+import { RETIRED_MESSAGE_MAX_CODE_POINTS, RETIRED_STATUSES } from './constants.gen.js';
+import { ArtifactRevokedError, SourceRetiredError } from './errors.js';
+/** Is this status a retired repository's? */
+export function isRetiredStatus(status) {
+    return RETIRED_STATUSES.includes(status);
+}
+function removed(codePoint) {
+    return (codePoint <= 0x1f ||
+        (codePoint >= 0x7f && codePoint <= 0x9f) ||
+        codePoint === 0x200e ||
+        codePoint === 0x200f ||
+        (codePoint >= 0x202a && codePoint <= 0x202e) ||
+        (codePoint >= 0x2066 && codePoint <= 0x2069));
+}
+/** A UTF-16 surrogate that is not half of a high-then-low pair: not a Unicode string. */
+function hasLoneSurrogate(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const d = s.charCodeAt(i + 1);
+            if (d >= 0xdc00 && d <= 0xdfff) {
+                i++;
+                continue;
+            }
+            return true;
+        }
+        if (c >= 0xdc00 && c <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+function objectOrUndefined(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+/**
+ * The registry's own message in a retired repository's response body, made
+ * safe to print, or `null` when it sent none. `body` is what was read of it
+ * (at most `RETIRED_BODY_MAX_BYTES`). When it is UTF-8 JSON whose
+ * `errors[0].message` is a string, that string is the message: every code
+ * point in U+0000-U+001F, U+007F-U+009F, U+200E, U+200F, U+202A-U+202E and
+ * U+2066-U+2069 is removed, and the rest is cut to
+ * `RETIRED_MESSAGE_MAX_CODE_POINTS` code points, with U+2026 appended when it
+ * was cut. Nothing else is changed, and an empty result is no message.
+ */
+export function retiredMessage(body) {
+    let doc;
+    try {
+        // fatal: invalid UTF-8 is no message. ignoreBOM: a byte order mark stays
+        // in the text, so JSON.parse refuses it, as the other bindings' readers do.
+        doc = JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(body));
+    }
+    catch {
+        return null;
+    }
+    const errors = objectOrUndefined(doc)?.['errors'];
+    if (!Array.isArray(errors) || errors.length === 0)
+        return null;
+    const message = objectOrUndefined(errors[0])?.['message'];
+    if (typeof message !== 'string')
+        return null;
+    const safe = sanitizeRetiredText(message);
+    return safe === '' ? null : safe;
+}
+/**
+ * `text` made safe to print, the retired message's rule for every served
+ * string: every code point in U+0000-U+001F, U+007F-U+009F, U+200E, U+200F,
+ * U+202A-U+202E and U+2066-U+2069 removed, then cut to
+ * `RETIRED_MESSAGE_MAX_CODE_POINTS` code points with U+2026 appended when it was
+ * cut. A string holding a lone surrogate is not Unicode text and is `''`, as is
+ * one that is empty once made safe.
+ */
+export function sanitizeRetiredText(text) {
+    if (hasLoneSurrogate(text))
+        return '';
+    const kept = [];
+    for (const ch of text) {
+        // A string iterates by code point, so a character outside the BMP is one.
+        if (!removed(ch.codePointAt(0) ?? 0))
+            kept.push(ch);
+    }
+    if (kept.length > RETIRED_MESSAGE_MAX_CODE_POINTS) {
+        kept.length = RETIRED_MESSAGE_MAX_CODE_POINTS;
+        kept.push('…');
+    }
+    return kept.join('');
+}
+/** The error text for a retired repository's answer: the URL and status that answered, and the registry's message when it sent one. */
+export function retiredText(url, status, body) {
+    const message = retiredMessage(body);
+    const text = `${url} answered ${status} Gone: the repository is retired`;
+    return message === null ? text : `${text}; the registry says: ${message}`;
+}
+/**
+ * A 410's body read as a revocation (guide, "Build-level revocation", "A `410`
+ * on a tag"): `undefined` unless it is UTF-8 JSON whose `errors[0].detail.revoked`
+ * is an object; otherwise that object's advisories, each field made safe, and one
+ * that is absent, not a string, empty once made safe or a lone surrogate left
+ * `''`. An entry that is not an object, or leaves every field empty, is skipped.
+ * A repeated key reads as its last value, and a byte order mark is not JSON.
+ * `tests/fixtures/revoked-410/cases.json` is the table all four bindings answer
+ * alike.
+ */
+export function revoked410(body) {
+    let doc;
+    try {
+        doc = JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(body));
+    }
+    catch {
+        return undefined;
+    }
+    const errors = objectOrUndefined(doc)?.['errors'];
+    if (!Array.isArray(errors) || errors.length === 0)
+        return undefined;
+    const detail = objectOrUndefined(objectOrUndefined(errors[0])?.['detail']);
+    const revoked = objectOrUndefined(detail?.['revoked']);
+    if (revoked === undefined)
+        return undefined;
+    const entries = revoked['advisories'];
+    const advisories = [];
+    if (!Array.isArray(entries))
+        return advisories;
+    for (const e of entries) {
+        const obj = objectOrUndefined(e);
+        if (obj === undefined)
+            continue;
+        const field = (key) => {
+            const v = obj[key];
+            return typeof v === 'string' ? sanitizeRetiredText(v) : '';
+        };
+        const a = {
+            id: field('id'),
+            url: field('url'),
+            class: field('class'),
+            summary: field('summary'),
+            build: field('build'),
+            supersededBy: field('superseded_by'),
+            revokedAt: '',
+        };
+        if (a.id === '' && a.url === '' && a.class === '' && a.summary === '' && a.build === '' && a.supersededBy === '')
+            continue;
+        advisories.push(a);
+    }
+    return advisories;
+}
+/**
+ * One 410 advisory: `<id> <url> (<class>) build <build>, superseded by build
+ * <superseded_by>: <summary>`, a part whose field is empty left out with the
+ * separator before it, and the first part present taking none.
+ */
+function advisoryText(a) {
+    let s = '';
+    const join = (sep, part) => {
+        if (s !== '')
+            s += sep;
+        s += part;
+    };
+    if (a.id !== '')
+        join(' ', a.id);
+    if (a.url !== '')
+        join(' ', a.url);
+    if (a.class !== '')
+        join(' ', `(${a.class})`);
+    if (a.build !== '')
+        join(' ', `build ${a.build}`);
+    if (a.supersededBy !== '')
+        join(', ', `superseded by build ${a.supersededBy}`);
+    if (a.summary !== '')
+        join(': ', a.summary);
+    return s;
+}
+/** What follows `<url> answered 410 Gone: ` for a revoked tag. */
+export function revoked410Text(advisories) {
+    const parts = advisories.map(advisoryText).filter((t) => t !== '');
+    return parts.length === 0 ? 'revoked, and the registry names no advisory' : `revoked: ${parts.join('; ')}`;
+}
+/**
+ * The error for a 410 (guide §2): `ArtifactRevokedError` when `revocation` is on
+ * (generation 2) and the body's `errors[0].detail.revoked` is an object, else a
+ * retired repository's `SourceRetiredError`. Both are permanent.
+ */
+export function goneError(url, status, body, revocation) {
+    if (revocation) {
+        const advisories = revoked410(body);
+        if (advisories !== undefined) {
+            return new ArtifactRevokedError(`chtypes: ${url} answered ${status} Gone: ${revoked410Text(advisories)}`, {
+                signed: false,
+                manifest: '',
+                advisories,
+            });
+        }
+    }
+    return new SourceRetiredError(`chtypes: ${retiredText(url, status, body)}`);
+}
+/** Is `err` a 410's: `SourceRetiredError` or, under generation 2, `ArtifactRevokedError`? Either is permanent, so every loop over bases or candidates throws it at once. */
+export function isGone(err) {
+    return err instanceof SourceRetiredError || err instanceof ArtifactRevokedError;
+}
+/** At most `maxBytes` of a response body. A body that fails part way is no body. */
+export function readRetiredBody(stream, maxBytes) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let done = false;
+        const finish = (body) => {
+            if (done)
+                return;
+            done = true;
+            resolve(body);
+        };
+        stream.on('data', (chunk) => {
+            if (done)
+                return;
+            chunks.push(chunk);
+            total += chunk.length;
+            if (total >= maxBytes) {
+                finish(Buffer.concat(chunks).subarray(0, maxBytes));
+                stream.destroy();
+            }
+        });
+        stream.on('end', () => finish(Buffer.concat(chunks)));
+        stream.on('error', () => finish(Buffer.alloc(0)));
+        stream.on('close', () => finish(Buffer.alloc(0)));
+    });
+}
+//# sourceMappingURL=retired.js.map

package/dist/ocifetch/retired.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retired.js","sourceRoot":"","sources":["../../src/ocifetch/retired.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAiB,oBAAoB,EAAqB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzG,6CAA6C;AAC7C,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAQ,gBAAsC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,OAAO,CAAC,SAAiB;IAChC,OAAO,CACL,SAAS,IAAI,IAAI;QACjB,CAAC,SAAS,IAAI,IAAI,IAAI,SAAS,IAAI,IAAI,CAAC;QACxC,SAAS,KAAK,MAAM;QACpB,SAAS,KAAK,MAAM;QACpB,CAAC,SAAS,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,CAAC;QAC5C,CAAC,SAAS,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,gBAAgB,CAAC,CAAS;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,EAAE,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,EAAE,CAAC;gBAC/B,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM;YAAE,OAAO,IAAI,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAU;IACnC,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/G,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,yEAAyE;QACzE,4EAA4E;QAC5E,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,0EAA0E;QAC1E,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,+BAA+B,EAAE,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,+BAA+B,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED,uIAAuI;AACvI,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,MAAc,EAAE,IAAgB;IACvE,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,GAAG,GAAG,aAAa,MAAM,kCAAkC,CAAC;IACzE,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,wBAAwB,OAAO,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,MAAM,GAAG,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,UAAU,GAAe,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,UAAU,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE;YACpC,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,CAAC,CAAC;QACF,MAAM,CAAC,GAAa;YAClB,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC;YACjB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACrB,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;YACzB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACrB,YAAY,EAAE,KAAK,CAAC,eAAe,CAAC;YACpC,SAAS,EAAE,EAAE;SACd,CAAC;QACF,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,IAAI,CAAC,CAAC,YAAY,KAAK,EAAE;YAAE,SAAS;QAC3H,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,CAAW;IAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;IACX,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,IAAY,EAAQ,EAAE;QAC/C,IAAI,CAAC,KAAK,EAAE;YAAE,CAAC,IAAI,GAAG,CAAC;QACvB,CAAC,IAAI,IAAI,CAAC;IACZ,CAAC,CAAC;IACF,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,YAAY,KAAK,EAAE;QAAE,IAAI,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/E,IAAI,CAAC,CAAC,OAAO,KAAK,EAAE;QAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAAC,UAA+B;IAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC7G,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,MAAc,EAAE,IAAgB,EAAE,UAAmB;IAC1F,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,oBAAoB,CAAC,YAAY,GAAG,aAAa,MAAM,UAAU,cAAc,CAAC,UAAU,CAAC,EAAE,EAAE;gBACxG,MAAM,EAAE,KAAK;gBACb,QAAQ,EAAE,EAAE;gBACZ,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC,YAAY,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,4KAA4K;AAC5K,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,GAAG,YAAY,kBAAkB,IAAI,GAAG,YAAY,oBAAoB,CAAC;AAClF,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,MAA4B,EAAE,QAAgB;IAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,MAAM,MAAM,GAAG,CAAC,IAAY,EAAQ,EAAE;YACpC,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,GAAG,IAAI,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI;gBAAE,OAAO;YACjB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;YACtB,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;gBACtB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;gBACpD,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/ocifetch/revocation.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Build-level revocation (`docs/guides/fetch-v1.md`, "Build-level revocation";
+ * public issue #625). A revocation is a signed referrer of a platform manifest,
+ * read from the listing its signature lookup reads; one that verifies refuses the
+ * build with `ArtifactRevokedError` and is stored in the build's cache entry, and
+ * one that does not is ignored with one warning. A 410 whose body's
+ * `errors[0].detail.revoked` is an object is the same code (`retired.ts`). A
+ * status that cannot be read fails open with one warning, or in strict mode is the
+ * transport's error. Generation 2 only (`Channel.revocation`): the v1 contract has
+ * none of it.
+ *
+ * Four paths check, each with its own budget, exactly as Go's `revocation.go`:
+ *
+ *   - an install reads its revocation candidates from the trust listing it already
+ *     made, under the retry table;
+ *   - `--frozen` reads one listing, warm or cold, under the retry table;
+ *   - a build already installed and used without a download (a registry open,
+ *     preload, an ensure that finds it installed) is checked at most once per
+ *     process (the memo below), one attempt per base, no backoff, and one deadline
+ *     for the whole check;
+ *   - `--lock` and `update` refuse a revoked build on every platform they pin.
+ */
+import { type FetchV1ErrorCode, type Revocation } from './errors.js';
+import type { RequestOptions } from './http.js';
+import { type ReferrerDescriptor } from './referrers.js';
+import type { Resolved, Statement, TrustedKey } from './types.js';
+/** What one revocation check reads from the call's options, derived once (`ensure.ts`'s `revocationContext`). */
+export interface RevocationContext {
+    /** The configured bases, in order. */
+    readonly bases: readonly string[];
+    /** The trust list the build itself is checked under. */
+    readonly trustedKeys: readonly TrustedKey[];
+    /** The request options every fetch over `bases` sends (`requestOptionsFor`). */
+    readonly request: Omit<RequestOptions, 'maxBytes'>;
+    /** The cache root a writable entry lies under. */
+    readonly cacheRoot: string;
+    readonly offline: boolean;
+    /** Per call, and never with a lock or an update (`revocationContext` drops it). */
+    readonly allowRevoked: boolean;
+    /** A revocation status that cannot be read is the transport's error, not a warning. */
+    readonly requireRevocationCheck: boolean;
+}
+/** Whether the active contract has revocation at all. */
+export declare function revocationOn(): boolean;
+/**
+ * The build a check concerns: its own digests and signed predicate, and its
+ * installed entry (`dir`) when it has one, writable when that entry is in the
+ * user cache.
+ */
+export interface RevocationSubject {
+    readonly manifest: string;
+    readonly layer: string;
+    readonly predicate: Readonly<Record<string, unknown>>;
+    readonly version: string;
+    readonly platform: string;
+    readonly build: string;
+    readonly request: string;
+    readonly dir: string;
+    readonly writable: boolean;
+}
+/** The subject an installed build's `Resolved` names. */
+export declare function subjectOf(ctx: RevocationContext, res: Resolved): RevocationSubject;
+/** The subject of a build not yet installed: the signed statement verified for it. */
+export declare function subjectOfStatement(statement: Statement, manifest: string, layer: string, platform: string, request: string): RevocationSubject;
+/**
+ * One revocation bundle against `sub` (the guide's five rules): the signature
+ * under `keys`, the statement and predicate types, the subject and manifest, the
+ * build's identity, and the advisory's shape. The revocation, or why it does not
+ * verify. A signed payload that is not a statement is ignored, never CORRUPT.
+ */
+export declare function verifyRevocation(body: Buffer, keys: readonly TrustedKey[], sub: RevocationSubject): {
+    readonly revocation: Revocation;
+} | {
+    readonly reason: string;
+};
+/**
+ * The guide's message for a verified revocation: `<version> <platform> build
+ * <build> (manifest <digest>) is revoked: <id> <url> (<class>); superseded by
+ * build <superseded_by>: <summary>`, a part whose field is empty left out.
+ */
+export declare function revokedText(sub: RevocationSubject, rev: Revocation): string;
+/** One verified revocation: the bundle, for the stored record, and what it says. */
+export interface FoundRevocation {
+    readonly bundle: Buffer;
+    readonly revocation: Revocation;
+}
+/** Why a status could not be read: the text, and the code the transport's error carries in strict mode. */
+export interface Unread {
+    readonly text: string;
+    readonly code: FetchV1ErrorCode;
+}
+/**
+ * What one check learned: a verified revocation, the warnings for the candidates
+ * it ignored, and, when it could not read the status, why.
+ */
+export interface RevocationOutcome {
+    verified: FoundRevocation | undefined;
+    readonly warnings: string[];
+    unread: Unread | undefined;
+}
+/**
+ * Fetches and verifies each revocation candidate in turn; the first that
+ * verifies is the answer. A candidate whose bytes cannot be fetched leaves the
+ * status unread; one fetched but corrupt or not verifying is ignored with a
+ * warning. Its only error is a 410's.
+ */
+export declare function checkCandidates(ctx: RevocationContext, bases: readonly string[], cands: readonly ReferrerDescriptor[], sub: RevocationSubject, single: boolean, signal?: AbortSignal): Promise<RevocationOutcome>;
+/**
+ * One network check of `sub`: its listing, then its candidates. A listing that
+ * names no signature referrer is an unread status.
+ */
+export declare function checkListing(ctx: RevocationContext, sub: RevocationSubject, single: boolean, signal?: AbortSignal): Promise<RevocationOutcome>;
+/**
+ * Turns an outcome into the call's answer, its warnings pushed on `warn`: a
+ * verified revocation is stored in an installed, writable entry (when `store`)
+ * and refuses the build, or with the override becomes one warning; an unread
+ * status is one warning, or in strict mode the transport's error.
+ */
+export declare function settle(ctx: RevocationContext, sub: RevocationSubject, out: RevocationOutcome, store: boolean, warn: string[]): Promise<void>;
+/** Stores a verified revocation's bundle, byte for byte, in an installed build's entry: a temporary file, then a rename. */
+export declare function writeRevocationRecord(dir: string, bundle: Buffer): Promise<void>;
+/** The revocation an install let through under the override, stored in the entry it installed (a failed write is ignored). */
+export declare function storePending(ctx: RevocationContext, dir: string, pending: FoundRevocation | undefined): Promise<void>;
+/**
+ * Reads `sub`'s stored record, if its entry holds one: verified, it decides the
+ * call (returns `true`; a refusal is thrown); one that does not verify is a
+ * warning, and the call goes on.
+ */
+export declare function checkStored(ctx: RevocationContext, sub: RevocationSubject, warn: string[]): Promise<boolean>;
+/** The revocation `res`'s stored record holds, when it verifies, and its message (`chtypes verify`'s). */
+export declare function storedRevocation(ctx: RevocationContext, res: Resolved): Promise<{
+    readonly revocation: Revocation;
+    readonly text: string;
+} | undefined>;
+/** The check every call that answers from the cache with no request makes (`--offline`, `--frozen --offline`): the stored record. */
+export declare function checkInstalledStored(ctx: RevocationContext, res: Resolved): Promise<readonly string[]>;
+/** `--frozen`'s check of the build installed under its pin: the stored record, then one listing under the retry table. */
+export declare function checkFrozenInstalled(ctx: RevocationContext, res: Resolved): Promise<readonly string[]>;
+/** Forgets every kept outcome, as a new process would. A conformance runner calls it before every case. Test-only. */
+export declare function resetRevocationMemoForTests(): void;
+/** Shortens (or, with `undefined`, restores) the installed-build check's one deadline. Test-only. */
+export declare function setRevocationCheckDeadlineForTests(seconds: number | undefined): void;
+/**
+ * The installed-build check: the stored record, then, unless offline, the kept
+ * outcome or one check of its own, with one attempt per base, no backoff and one
+ * deadline. Concurrent checks of one build share one; a kept "not checked"
+ * answers only a call without strict mode, and a check that ends in an error
+ * keeps nothing. Warnings go on `warn`; a refusal is thrown.
+ */
+export declare function checkInstalledOnce(ctx: RevocationContext, res: Resolved, warn: string[]): Promise<void>;
+//# sourceMappingURL=revocation.d.ts.map

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

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