@wavehouse/chtypes 0.5.2 → 1.0.0

package/dist/ocifetch/localverify.js

@@ -0,0 +1,164 @@
+/**
+ * Verifying a pre-seeded cache entry from local blobs alone, zero network
+ * (`docs/guides/fetch-v1.md` §1, §6): "a pre-seeded layout has entries in
+ * `index.json` with no corresponding `unpacked/` directory yet; the first
+ * request for one verifies it against its signature exactly as a freshly
+ * downloaded layer would, then unpacks it." `--offline`/`resolve_installed`
+ * are the only callers — never `ensure`'s normal online path, which always
+ * has a live referrers API to ask.
+ *
+ * There is no referrers API to query here, so trust discovery is a local
+ * scan: every blob under `blobs/sha256/` that parses as an OCI manifest
+ * with the signature bundle's own `artifactType` is a *candidate* referrer
+ * of the platform manifest, tried the same way `dsse.ts`'s
+ * `verifyAnyReferrerBundle` tries referrers fetched over the network —
+ * stopping at the first whose signature verifies AND whose statement names
+ * this exact platform manifest's layer as its subject. `oras copy -r
+ * --to-oci-layout` is what populates these blobs when pulling from a real
+ * registry (guide §1); `index.json` itself carries no referrers listing (no
+ * such thing exists in the OCI image-layout spec), which is exactly why
+ * this is a scan rather than a lookup.
+ */
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { MEDIA_TYPE_BUNDLE, PREDICATE_TYPE_ARTIFACT } from './constants.gen.js';
+import { checkArtifactStatement, parseStatement, verifyBundleSignature } from './dsse.js';
+import { ArtifactCorruptError } from './errors.js';
+import { buildRecord, commitStaging, freshStagingDir, listLocalBlobHexes, readLocalBlob, readVerifiedRecord, unpackedDir, writeVerifiedRecord, } from './layout.js';
+import { parseManifest, verifyDescriptor } from './oci.js';
+import { digestOfHex, hexOfDigest, platformInfo } from './types.js';
+import { measureLibrary, verifyAndUnpackLayerBytes, verifyInstalledLibrary } from './unpack.js';
+/**
+ * Verifies and installs the platform manifest named by `manifestDigest`,
+ * reading every blob it needs from `blobsSourceDir`'s `blobs/sha256/` but
+ * always **writing** the result (the unpacked library and its
+ * `verified.json`) under `writeRoot` — the two differ for a read-only
+ * system directory (guide §1: "never written to"), where `blobsSourceDir`
+ * is that system dir and `writeRoot` is the user's own cache.
+ *
+ * Idempotent and cheap on a repeat call: if `writeRoot` already has a
+ * `verified.json` for this digest, returns it without touching
+ * `blobsSourceDir` again. Returns `undefined` (never throws) when this
+ * specific entry cannot be locally verified — a bad or incomplete
+ * pre-seeded blob is "not usable", not a hard failure for whatever broader
+ * scan is trying several candidates. The caller decides whether the
+ * resulting predicate's own `clickhouse_version` fits whatever request
+ * prompted the scan — this function verifies the entry on its own terms,
+ * not against any one request.
+ */
+export async function verifyAndInstallFromLocalBlobs(blobsSourceDir, writeRoot, manifestDigest, platform, trustedKeys) {
+    const manifestHex = hexOfDigest(manifestDigest);
+    const existing = await readVerifiedRecord(unpackedDir(writeRoot, manifestHex));
+    if (existing !== undefined)
+        return existing;
+    try {
+        const manifestBytes = await readLocalBlob(blobsSourceDir, manifestHex);
+        if (manifestBytes === undefined)
+            return undefined;
+        verifyDescriptor({ mediaType: '', digest: manifestDigest }, manifestBytes, `manifest ${manifestDigest}`);
+        const manifest = parseManifest(manifestDigest, manifestBytes);
+        const info = platformInfo(platform);
+        const found = await findLocalSignature(blobsSourceDir, manifest.layer, trustedKeys);
+        if (found === undefined)
+            return undefined;
+        const predicate = checkArtifactStatement(found.statement, PREDICATE_TYPE_ARTIFACT, manifest.layer.digest, {
+            os: info.os,
+            arch: info.architecture,
+            // No `requestedSpelling`: this entry is verified on its own terms,
+            // not against one request — see this function's own doc comment.
+        });
+        const layerBytes = await readLocalBlob(blobsSourceDir, hexOfDigest(manifest.layer.digest));
+        if (layerBytes === undefined)
+            return undefined;
+        const staging = await freshStagingDir(writeRoot);
+        try {
+            const entries = await verifyAndUnpackLayerBytes(layerBytes, manifest.layer, staging);
+            if (!entries.some((e) => e.name === predicate.library)) {
+                throw new ArtifactCorruptError(`chtypes: the local layer does not contain its own predicate's library ${JSON.stringify(predicate.library)}`);
+            }
+            await verifyInstalledLibrary(path.join(staging, predicate.library), predicate.library_sha256, predicate.library_bytes);
+            const record = buildRecord({
+                platform,
+                predicate,
+                library: await measureLibrary(path.join(staging, predicate.library)),
+                indexDigest: null,
+                manifestDigest,
+                layerDigest: manifest.layer.digest,
+                bundleDigest: found.bundleDigest,
+                bundleManifestDigest: found.bundleManifestDigest,
+                signedBy: found.signedBy,
+            });
+            await writeVerifiedRecord(staging, record);
+            await commitStaging(staging, unpackedDir(writeRoot, manifestHex));
+            return record;
+        }
+        catch {
+            await rm(staging, { recursive: true, force: true }).catch(() => { });
+            return undefined;
+        }
+    }
+    catch {
+        // Any failure anywhere in this local-only verification (malformed
+        // blob, bad signature, wrong subject) just means this candidate is not
+        // usable — never a hard error, since a scan may have other candidates
+        // to try, and `--offline` would otherwise crash on one bad bystander
+        // entry in an otherwise-healthy cache.
+        return undefined;
+    }
+}
+/**
+ * Scans every local blob for one that is an OCI manifest of the signature
+ * bundle's `artifactType`, tries its own layer (the bundle JSON) against
+ * `trustedKeys`, and accepts the first whose verified statement names
+ * `layer`'s digest as its subject. Order is the filesystem's own
+ * `readdir` order — deterministic per run, immaterial to correctness since
+ * every candidate is checked.
+ */
+async function findLocalSignature(blobsSourceDir, layer, trustedKeys) {
+    const hexes = await listLocalBlobHexes(blobsSourceDir);
+    for (const hex of hexes) {
+        const bytes = await readLocalBlob(blobsSourceDir, hex);
+        if (bytes === undefined)
+            continue;
+        const artifactType = readArtifactType(bytes);
+        if (artifactType !== MEDIA_TYPE_BUNDLE)
+            continue;
+        let candidateManifest;
+        try {
+            candidateManifest = parseManifest(digestOfHex(hex), bytes);
+        }
+        catch {
+            continue; // Names the bundle artifactType but is not a readable manifest — not a candidate.
+        }
+        const bundleBytes = await readLocalBlob(blobsSourceDir, hexOfDigest(candidateManifest.layer.digest));
+        if (bundleBytes === undefined)
+            continue;
+        const verified = verifyBundleSignature(bundleBytes, trustedKeys);
+        if (verified === undefined)
+            continue;
+        let statement;
+        try {
+            statement = parseStatement(verified.payload);
+        }
+        catch {
+            continue;
+        }
+        if (statement.subject[0]?.digest.sha256 !== hexOfDigest(layer.digest))
+            continue;
+        return { statement, signedBy: verified.signedBy, bundleDigest: candidateManifest.layer.digest, bundleManifestDigest: digestOfHex(hex) };
+    }
+    return undefined;
+}
+function readArtifactType(manifestBytes) {
+    try {
+        const parsed = JSON.parse(manifestBytes.toString('utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const v = parsed['artifactType'];
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=localverify.js.map

package/dist/ocifetch/localverify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localverify.js","sourceRoot":"","sources":["../../src/ocifetch/localverify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,WAAW,EAEX,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAmB,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,cAAsB,EACtB,SAAiB,EACjB,cAAsB,EACtB,QAAqB,EACrB,WAAkC;IAElC,MAAM,WAAW,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAC/E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAE5C,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QACvE,IAAI,aAAa,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAClD,gBAAgB,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,aAAa,EAAE,YAAY,cAAc,EAAE,CAAC,CAAC;QACzG,MAAM,QAAQ,GAAG,aAAa,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;QAE9D,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,cAAc,EAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACpF,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,SAAS,GAAsB,sBAAsB,CAAC,KAAK,CAAC,SAAS,EAAE,uBAAuB,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE;YAC3H,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,YAAY;YACvB,mEAAmE;YACnE,iEAAiE;SAClE,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,cAAc,EAAE,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3F,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAE/C,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,yBAAyB,CAAC,UAAU,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACrF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBACvD,MAAM,IAAI,oBAAoB,CAC5B,yEAAyE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAC7G,CAAC;YACJ,CAAC;YACD,MAAM,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;YACvH,MAAM,MAAM,GAAG,WAAW,CAAC;gBACzB,QAAQ;gBACR,SAAS;gBACT,OAAO,EAAE,MAAM,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;gBACpE,WAAW,EAAE,IAAI;gBACjB,cAAc;gBACd,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM;gBAClC,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;gBAChD,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC,CAAC;YACH,MAAM,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC3C,MAAM,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;YAClE,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACpE,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,uEAAuE;QACvE,sEAAsE;QACtE,qEAAqE;QACrE,uCAAuC;QACvC,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAUD;;;;;;;GAOG;AACH,KAAK,UAAU,kBAAkB,CAC/B,cAAsB,EACtB,KAAiB,EACjB,WAAkC;IAElC,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,cAAc,CAAC,CAAC;IACvD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACvD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,YAAY,KAAK,iBAAiB;YAAE,SAAS;QACjD,IAAI,iBAAmD,CAAC;QACxD,IAAI,CAAC;YACH,iBAAiB,GAAG,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,kFAAkF;QAC9F,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,cAAc,EAAE,WAAW,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACrG,IAAI,WAAW,KAAK,SAAS;YAAE,SAAS;QACxC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACjE,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAS;QACrC,IAAI,SAAoB,CAAC;QACzB,IAAI,CAAC;YACH,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,SAAS;QAChF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,oBAAoB,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1I,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,aAAqB;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpE,MAAM,CAAC,GAAI,MAAkC,CAAC,cAAc,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/ocifetch/lock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lock schema 3 (`docs/guides/fetch-v1.md` §6, `spec/fetch-v1/schema/lock3.schema.json`):
+ * per declared platform, the request, the exact version and build, and the
+ * platform manifest/layer/bundle digests — never a hostname. Schema 1 and 2
+ * (v0) are refused outright, never silently reinterpreted, exactly as v0
+ * refuses a lock newer than it understands.
+ */
+import { type PlatformKey } from './types.js';
+export interface LockPin {
+    readonly version: string;
+    readonly build: string;
+    readonly manifest: string;
+    readonly layer: string;
+    readonly bundle: string;
+    readonly index?: string;
+}
+export interface LockFile {
+    readonly schema: 3;
+    readonly abi: 1;
+    readonly platforms: readonly PlatformKey[];
+    /** Keyed by the originally-requested spelling, then by platform key. */
+    readonly requests: Readonly<Record<string, Readonly<Record<string, LockPin>>>>;
+}
+export declare function emptyLock(): LockFile;
+export declare function defaultLockPath(cwd?: string): string;
+/**
+ * Validates and narrows a parsed JSON value into a `LockFile`. Any v0 lock
+ * (`schema: 1` or `schema: 2` in v0's own numbering) and any other
+ * malformed shape is `ArtifactPinnedError`, naming re-lock — `--frozen`
+ * reads this the same way a missing pin does (guide §6).
+ */
+export declare function validateLock(parsed: unknown, path_: string): LockFile;
+/** `undefined` when no lock file exists at `lockPath`. */
+export declare function readLock(lockPath: string): Promise<LockFile | undefined>;
+export declare function writeLock(lockPath: string, lock: LockFile): Promise<void>;
+export declare function getPin(lock: LockFile, spelling: string, platform: PlatformKey): LockPin | undefined;
+/** Returns a new lock with `pin` set for `spelling`/`platform`, adding `platform` to the declared list if new. */
+export declare function withPin(lock: LockFile, spelling: string, platform: PlatformKey, pin: LockPin): LockFile;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/ocifetch/lock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAChF;AAID,wBAAgB,SAAS,IAAI,QAAQ,CAEpC;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAEnE;AAQD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAqErE;AAED,0DAA0D;AAC1D,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAe9E;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/E;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,GAAG,SAAS,CAEnG;AAED,kHAAkH;AAClH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAOvG"}

package/dist/ocifetch/lock.js

@@ -0,0 +1,140 @@
+/**
+ * Lock schema 3 (`docs/guides/fetch-v1.md` §6, `spec/fetch-v1/schema/lock3.schema.json`):
+ * per declared platform, the request, the exact version and build, and the
+ * platform manifest/layer/bundle digests — never a hostname. Schema 1 and 2
+ * (v0) are refused outright, never silently reinterpreted, exactly as v0
+ * refuses a lock newer than it understands.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { LOCK_DEFAULT_FILE, LOCK_SCHEMA, PLATFORMS } from './constants.gen.js';
+import { ArtifactPinnedError } from './errors.js';
+import { isPlatformKey } from './types.js';
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+export function emptyLock() {
+    return { schema: LOCK_SCHEMA, abi: 1, platforms: [], requests: {} };
+}
+export function defaultLockPath(cwd = process.cwd()) {
+    return path.join(cwd, LOCK_DEFAULT_FILE);
+}
+function pinName(digest, field) {
+    if (!DIGEST_RE.test(digest)) {
+        throw new ArtifactPinnedError(`chtypes: lock pin's ${field} ${JSON.stringify(digest)} is not a sha256 digest`);
+    }
+}
+/**
+ * Validates and narrows a parsed JSON value into a `LockFile`. Any v0 lock
+ * (`schema: 1` or `schema: 2` in v0's own numbering) and any other
+ * malformed shape is `ArtifactPinnedError`, naming re-lock — `--frozen`
+ * reads this the same way a missing pin does (guide §6).
+ */
+export function validateLock(parsed, path_) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ArtifactPinnedError(`chtypes: ${path_} is not a lock file object; re-lock with \`fetch --lock\``);
+    }
+    const doc = parsed;
+    const schema = doc['schema'];
+    if (schema !== LOCK_SCHEMA) {
+        throw new ArtifactPinnedError(`chtypes: ${path_} is schema ${JSON.stringify(schema)}, not v1's schema ${LOCK_SCHEMA}` +
+            (schema === 1 || schema === 2 ? ' (a v0 lock is never reinterpreted)' : '') +
+            '; re-lock with `fetch --lock`');
+    }
+    if (doc['abi'] !== 1) {
+        throw new ArtifactPinnedError(`chtypes: ${path_}'s abi is ${JSON.stringify(doc['abi'])}, not 1; re-lock with \`fetch --lock\``);
+    }
+    const platformsRaw = doc['platforms'];
+    if (!Array.isArray(platformsRaw) || platformsRaw.length === 0) {
+        throw new ArtifactPinnedError(`chtypes: ${path_} names no platforms; re-lock with \`fetch --lock\``);
+    }
+    const platforms = [];
+    for (const p of platformsRaw) {
+        if (typeof p !== 'string' || !isPlatformKey(p)) {
+            throw new ArtifactPinnedError(`chtypes: ${path_} names an unknown platform ${JSON.stringify(p)}`);
+        }
+        platforms.push(p);
+    }
+    const requestsRaw = doc['requests'];
+    if (requestsRaw === null || typeof requestsRaw !== 'object' || Array.isArray(requestsRaw)) {
+        throw new ArtifactPinnedError(`chtypes: ${path_} has no readable requests table`);
+    }
+    const requests = {};
+    for (const [spelling, byPlatform] of Object.entries(requestsRaw)) {
+        if (byPlatform === null || typeof byPlatform !== 'object' || Array.isArray(byPlatform)) {
+            throw new ArtifactPinnedError(`chtypes: ${path_}'s request ${JSON.stringify(spelling)} is malformed`);
+        }
+        const row = {};
+        for (const [platform, pinRaw] of Object.entries(byPlatform)) {
+            if (!isPlatformKey(platform) || !platforms.includes(platform)) {
+                throw new ArtifactPinnedError(`chtypes: ${path_}'s request ${JSON.stringify(spelling)} names platform ${JSON.stringify(platform)}, not in its own platforms list`);
+            }
+            if (pinRaw === null || typeof pinRaw !== 'object' || Array.isArray(pinRaw)) {
+                throw new ArtifactPinnedError(`chtypes: ${path_}'s pin for ${spelling}/${platform} is malformed`);
+            }
+            const p = pinRaw;
+            const version = p['version'];
+            const build = p['build'];
+            const manifest = p['manifest'];
+            const layer = p['layer'];
+            const bundle = p['bundle'];
+            const index = p['index'];
+            if (typeof version !== 'string' || typeof build !== 'string') {
+                throw new ArtifactPinnedError(`chtypes: ${path_}'s pin for ${spelling}/${platform} is missing version or build`);
+            }
+            if (typeof manifest !== 'string' || typeof layer !== 'string' || typeof bundle !== 'string') {
+                throw new ArtifactPinnedError(`chtypes: ${path_}'s pin for ${spelling}/${platform} is missing a digest`);
+            }
+            pinName(manifest, 'manifest');
+            pinName(layer, 'layer');
+            pinName(bundle, 'bundle');
+            if (index !== undefined) {
+                if (typeof index !== 'string')
+                    throw new ArtifactPinnedError(`chtypes: ${path_}'s pin for ${spelling}/${platform} has a non-string index`);
+                pinName(index, 'index');
+            }
+            row[platform] = { version, build, manifest, layer, bundle, ...(index !== undefined ? { index } : {}) };
+        }
+        requests[spelling] = row;
+    }
+    return { schema: LOCK_SCHEMA, abi: 1, platforms, requests };
+}
+/** `undefined` when no lock file exists at `lockPath`. */
+export async function readLock(lockPath) {
+    let raw;
+    try {
+        raw = await readFile(lockPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ArtifactPinnedError(`chtypes: ${lockPath} is not valid JSON: ${err.message}`);
+    }
+    return validateLock(parsed, lockPath);
+}
+export async function writeLock(lockPath, lock) {
+    const serializable = { schema: LOCK_SCHEMA, abi: 1, platforms: lock.platforms, requests: lock.requests };
+    await mkdir(path.dirname(lockPath), { recursive: true });
+    const tmp = `${lockPath}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    await writeFile(tmp, `${JSON.stringify(serializable, null, 2)}\n`);
+    await rename(tmp, lockPath);
+}
+export function getPin(lock, spelling, platform) {
+    return lock.requests[spelling]?.[platform];
+}
+/** Returns a new lock with `pin` set for `spelling`/`platform`, adding `platform` to the declared list if new. */
+export function withPin(lock, spelling, platform, pin) {
+    // Platforms are kept in the contract's own order (`PLATFORMS`), never
+    // insertion order, so two writers that pinned the same set agree byte for byte.
+    const unsorted = lock.platforms.includes(platform) ? lock.platforms : [...lock.platforms, platform];
+    const platforms = PLATFORMS.map((p) => p.key).filter((k) => unsorted.includes(k));
+    const row = { ...(lock.requests[spelling] ?? {}), [platform]: pin };
+    return { ...lock, platforms, requests: { ...lock.requests, [spelling]: row } };
+}
+//# sourceMappingURL=lock.js.map

package/dist/ocifetch/lock.js.map

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

package/dist/ocifetch/oci.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { type RequestOptions } from './http.js';
+import { type PlatformKey } 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 declare function checkSpelling(spelling: string): void;
+/** A descriptor's `size` is absent when it comes from a lock pin (schema 3 stores digests only, never sizes). */
+export interface Descriptor {
+    readonly mediaType: string;
+    readonly digest: string;
+    readonly size?: number;
+}
+export interface ManifestInfo {
+    readonly digest: string;
+    readonly bytes: Buffer;
+    readonly layer: Descriptor;
+    readonly config: Descriptor | undefined;
+}
+/**
+ * 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 declare function parseManifest(digest: string, bytes: Buffer): ManifestInfo;
+/**
+ * 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 declare function verifyDescriptor(descriptor: Descriptor, bytes: Buffer, what: string): void;
+/**
+ * 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 declare function verifyDigestAndSize(descriptor: Descriptor, actualSha256Hex: string, actualSize: number, what: string): void;
+/**
+ * `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 declare function fetchManifestBytesByDigest(bases: readonly string[], descriptor: Descriptor, options: RequestOptions): Promise<Buffer>;
+/** `GET blobs/<digest>`, tried across every base, fully buffered — a bundle, never the (potentially huge) library layer. */
+export declare function fetchBlobBytesByDigest(bases: readonly string[], descriptor: Descriptor, options: RequestOptions): Promise<Buffer>;
+export interface ByteSink {
+    reset(): void;
+    write(chunk: Buffer): void;
+}
+/**
+ * `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 declare function fetchBlobToSink(bases: readonly string[], descriptor: Descriptor, options: RequestOptions, sink: ByteSink): Promise<void>;
+/** `fetchManifestBytesByDigest` plus parsing — `--frozen`'s and `fetchSigned`'s "give me this manifest" primitive. */
+export declare function fetchManifestByDigest(bases: readonly string[], digest: string, options: RequestOptions): Promise<ManifestInfo>;
+export interface IndexResolveResult {
+    readonly repositoryRoot: string;
+    readonly indexDigest: string;
+    readonly indexBytes: Buffer;
+    readonly manifest: ManifestInfo;
+}
+/**
+ * `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 declare function resolveTag(bases: readonly string[], spelling: string, platform: PlatformKey, options: RequestOptions): Promise<IndexResolveResult>;
+//# sourceMappingURL=oci.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oci.d.ts","sourceRoot":"","sources":["../../src/ocifetch/oci.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAAE,KAAK,cAAc,EAA+C,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAiE,KAAK,WAAW,EAAgB,MAAM,YAAY,CAAC;AAE3H;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOpD;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAmCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAqBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO3H;AAmDD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,4HAA4H;AAC5H,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B9I;AAED,sHAAsH;AACtH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAGpI;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAiF7B"}