@xemahq/xema 0.59.0 → 0.60.1

package/edition/canonical-evidence-json.mjs

@@ -1,82 +0,0 @@
-// Canonical evidence JSON, exact UTF-8 and sha256 digests: the primitives every evidence module shares. Its own module so a
-// module `image-evidence.mjs` imports (the third-party pin loader) can use them without an import cycle.
-
-import { createHash } from 'node:crypto';
-
-import { compareStrings } from './lib.mjs';
-
-const STRICT_UTF8 = new TextDecoder('utf-8', {
-  fatal: true,
-  ignoreBOM: true,
-});
-
-export function canonicalJson(value) {
-  if (
-    value === null ||
-    typeof value === 'boolean' ||
-    typeof value === 'string'
-  ) {
-    return JSON.stringify(value);
-  }
-  if (typeof value === 'number') {
-    if (!Number.isSafeInteger(value)) {
-      throw new Error('canonical evidence JSON permits only safe integers');
-    }
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map(canonicalJson).join(',')}]`;
-  }
-  if (typeof value === 'object') {
-    const entries = Object.entries(value).sort(([left], [right]) =>
-      compareStrings(left, right),
-    );
-    return `{${entries
-      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
-      .join(',')}}`;
-  }
-  throw new Error(`unsupported canonical evidence JSON value ${typeof value}`);
-}
-
-export function canonicalJsonBytes(value) {
-  return Buffer.from(`${canonicalJson(value)}\n`, 'utf8');
-}
-
-export function sha256Digest(bytes) {
-  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
-}
-
-/**
- * Exact UTF-8 decode. Exported because the producers need byte-for-byte the
- * same strictness the verifier applies — a producer that accepts bytes the
- * verifier will reject signs evidence that can never verify.
- */
-export function decodeExactUtf8(bytes, label) {
-  let text;
-  try {
-    text = STRICT_UTF8.decode(bytes);
-  } catch {
-    throw new Error(`${label} contains invalid UTF-8`);
-  }
-  if (!Buffer.from(text, 'utf8').equals(bytes)) {
-    throw new Error(`${label} is not exact UTF-8`);
-  }
-  return text;
-}
-
-export function parseCanonicalJsonBytes(bytes, label) {
-  const text = decodeExactUtf8(bytes, label);
-  let value;
-  try {
-    value = JSON.parse(text);
-  } catch (error) {
-    throw new Error(`${label} is not valid JSON: ${error.message}`);
-  }
-  const canonical = canonicalJsonBytes(value);
-  if (!bytes.equals(canonical)) {
-    throw new Error(
-      `${label} is not canonical JSON (duplicate keys, non-canonical ordering, or whitespace are refused)`,
-    );
-  }
-  return value;
-}

package/edition/canonical-repository-url.mjs

@@ -1,47 +0,0 @@
-// The canonical form of a public HTTPS repository URL, and the refusals that
-// define it. Leaf module: the workspace config and the git source hold read it
-// without importing the edition library.
-
-export function canonicalPublicHttpsRepositoryUrl(raw, context) {
-  if (typeof raw !== 'string' || raw.length === 0 || raw.trim() !== raw) {
-    throw new Error(`${context} must be a non-empty canonical HTTPS URL`);
-  }
-  let parsed;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    throw new Error(`${context} is not a valid URL`);
-  }
-  if (parsed.protocol !== 'https:') {
-    throw new Error(`${context} must use HTTPS`);
-  }
-  if (parsed.username.length > 0 || parsed.password.length > 0) {
-    throw new Error(
-      `${context} must not contain username/password credentials`,
-    );
-  }
-  if (
-    parsed.search.length > 0 ||
-    parsed.hash.length > 0 ||
-    raw.includes('?') ||
-    raw.includes('#')
-  ) {
-    throw new Error(`${context} must not contain a query or fragment`);
-  }
-  if (parsed.hostname.length === 0) {
-    throw new Error(`${context} must identify a repository host`);
-  }
-  return parsed.toString();
-}
-
-/**
- * The `owner/name` of a canonical public HTTPS repository URL (`https://host/owner/name[.git]`): exactly two
- * path segments, the optional `.git` suffix dropped. Anything else is refused, naming `context`.
- */
-export function repositoryOwnerName(canonicalUrl, context) {
-  const segments = new URL(canonicalUrl).pathname.replace(/\.git$/, '').split('/').filter((segment) => segment.length > 0);
-  if (segments.length !== 2) {
-    throw new Error(`${context} must name exactly <owner>/<name> on its host; got ${JSON.stringify(canonicalUrl)}`);
-  }
-  return segments.join('/');
-}

package/edition/catalogue-edition.mjs

@@ -1,49 +0,0 @@
-#!/usr/bin/env node
-// catalogue-edition — write the catalogue of a RELEASE offering from its committed, sealed locks.
-//
-//   catalogue <id> --out <dir>
-//
-// Writes <dir>/catalogue.json (catalogue.mjs). `xema edition artifact` writes the
-// same file into the offering artifact; this verb is for inspecting it or
-// publishing it on its own.
-
-import { mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-import { writeCatalogue } from './catalogue.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromProcess,
-  isEntryModule,
-} from './edition-workspace.mjs';
-import { releaseCatalogue } from './release-catalogue.mjs';
-import { readCommittedEdition } from './release-edition-artifact.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
-}
-
-/** `{ id, out }` of `<distribution-id> --out <dir>` (the argv AFTER the `catalogue` verb, which the edition dispatcher has already stripped); anything else is the usage error. */
-export function parseCatalogueArgs(argv) {
-  const [id, flag, out, ...extra] = argv;
-  if (id === undefined || flag !== '--out' || out === undefined || out.startsWith('--') || extra.length > 0) {
-    throw new Error('usage: xema edition catalogue <distribution-id> --out <dir>');
-  }
-  assertCanonicalDistributionId(id);
-  return { id, out };
-}
-
-async function run(argv) {
-  const { id, out } = parseCatalogueArgs(argv);
-  const dir = resolve(out);
-  mkdirSync(dir, { recursive: true });
-  console.log(writeCatalogue(dir, await releaseCatalogue(id, await readCommittedEdition(id))));
-}
-
-if (isEntryModule(import.meta.url)) {
-  run(process.argv.slice(2)).catch((error) => {
-    console.error(`[edition-catalogue] ${error.message}`);
-    process.exit(1);
-  });
-}

package/edition/catalogue-evidence.mjs

@@ -1,228 +0,0 @@
-// catalogue-evidence — the catalogue's signed E4 evidence, verified BEFORE the catalogue is read.
-//
-// A release catalogue is the ceiling of everything resolved against it, so its bytes are not parsed, and not even
-// fetched, until the E4 statement over its digest, catalogue layer and lock layer has been verified against the evidence
-// trust policy of the CALLER'S OWN data root (never the vendor's). The statement is an `oras attach` referrer of the
-// edition artifact digest (`EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE`): two layers, `statement.json` (in-toto) and
-// `bundle.sigstore.json` (the Sigstore bundle), and the exact commit of the signing workflow as an annotation.
-//
-// The verification is ONE seam, `verifyCatalogueEvidenceReferrer`, and it is done by the data root's PINNED built
-// verifier (`catalogue-evidence verify`, verify-catalogue-evidence.mjs): there is no second verifier. The only
-// kernel-dependent parts of the judgement are the policy schema (parseSigstoreOfflineTrustPolicy) and the
-// predicate-type/channel constants; before the catalogue's kernel is adopted (kernel-package.mjs) there is no kernel
-// package to load them from, so they come from the pinned bundle's own embedded kernel. The library never judges the
-// statement itself: it checks the referrer's layout, hands the two blobs to the bundle (only after the bundle's digests
-// equal the data-root pin; otherwise CatalogueVerifierNotPinnedError, before anything is spawned) and reads its verdict.
-
-import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
-import { assertPinnedVerifier, readEvidenceTrustPin } from './evidence-trust-pin.mjs';
-import { EvidenceTrustRequiredError } from './evidence-trust-policy.mjs';
-import { EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE } from './oci-image-source-evidence.mjs';
-import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
-
-const TITLE = 'org.opencontainers.image.title';
-/** The titles of the two layers of an E4 referrer, the in-toto statement's media type and the annotation naming the signing workflow commit. */
-export const CATALOGUE_EVIDENCE_STATEMENT_TITLE = 'statement.json';
-export const CATALOGUE_EVIDENCE_BUNDLE_TITLE = 'bundle.sigstore.json';
-export const CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE = 'application/vnd.in-toto+json';
-export const CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION = 'dev.xema.evidence.signer-workflow-sha';
-/** The variables the pinned verifier bundle is launched with (it refuses NODE_OPTIONS, NODE_PATH, DYLD_*, LD_*, GIT_*). */
-export const VERIFIER_LAUNCH_ENV_KEYS = Object.freeze(['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ']);
-const STATEMENT_MAX_BYTES = 2 * 1024 * 1024;
-const BUNDLE_MAX_BYTES = 16 * 1024 * 1024;
-const SPAWN_TIMEOUT_MS = 120_000;
-const COMMIT = /^[a-f0-9]{40}$/;
-const sha256Of = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
-
-/** No E4 referrer is attached to the artifact: the catalogue has no signed evidence at all. */
-export class CatalogueEvidenceMissingError extends Error {
-  constructor(ref) {
-    super(
-      `${ref} carries no ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} referrer: its catalogue has no signed edition evidence (E4), ` +
-        'so it is refused before it is read',
-    );
-    this.name = 'CatalogueEvidenceMissingError';
-  }
-}
-
-/** An E4 referrer exists but does not verify against the caller's evidence trust policy. */
-export class CatalogueEvidenceNotVerifiedError extends Error {
-  constructor(ref, reason) {
-    super(`${ref}: the catalogue's edition evidence (E4) is not verified: ${reason}; the catalogue is refused before it is read`);
-    this.name = 'CatalogueEvidenceNotVerifiedError';
-  }
-}
-
-/** The built verifier is not the one the data root pins (or is missing): nothing is spawned. */
-export class CatalogueVerifierNotPinnedError extends Error {
-  constructor(reason) {
-    super(`the catalogue's edition evidence (E4) cannot be verified: this CLI's built evidence verifier is not the one the data root pins: ${reason}`);
-    this.name = 'CatalogueVerifierNotPinnedError';
-  }
-}
-
-/** The edition a catalogue-consumer refusal names: the customer edition of `channel` that reads the catalogue. */
-const catalogueConsumer = (channel) => ({ edition: `${channel} edition`, channel });
-
-/** The pinned built verifier's bundle path, after the data root's pin of it held; refuses before anything is spawned. */
-function pinnedVerifierBundle(locateVerifier, channel) {
-  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
-  const root = configuredDataRoot();
-  if (declaration.policy === null) {throw new EvidenceTrustRequiredError(root, 'declares no policy', catalogueConsumer(channel));}
-  try {
-    const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
-    assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
-    return { bundlePath: locateVerifier().bundlePath, root };
-  } catch (error) {
-    throw new CatalogueVerifierNotPinnedError(error.message);
-  }
-}
-
-function launchEnvironment(source = process.env) {
-  const reduced = {};
-  for (const key of VERIFIER_LAUNCH_ENV_KEYS) {
-    if (source[key] !== undefined) {reduced[key] = source[key];}
-  }
-  return reduced;
-}
-
-function runVerifier({ spawn, bundlePath, args }) {
-  return spawn(process.execPath, [bundlePath, 'catalogue-evidence', ...args], {
-    encoding: 'utf8',
-    env: launchEnvironment(),
-    timeout: SPAWN_TIMEOUT_MS,
-    maxBuffer: 1024 * 1024,
-  });
-}
-
-const stderrOf = (result) => String(result.stderr ?? '').trim() || (result.error ? result.error.message : `exit ${String(result.status)}`);
-
-/**
- * Before any registry call: the caller's data root declares a policy, the built verifier is the one the pin records, and
- * the policy is ARMED on `channel` with the E4 row required (the one arming rule, judged by the pinned bundle with its own
- * kernel). Throws EvidenceTrustRequiredError for no policy / not armed, CatalogueVerifierNotPinnedError for a verifier the
- * pin does not record.
- *
- * @param {{ channel: string, locateVerifier?: Function, spawn?: Function }} options
- */
-export function assertCatalogueConsumerArmed({ channel, locateVerifier = locateBuiltVerifier, spawn = spawnSync }) {
-  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier, channel);
-  const result = runVerifier({ spawn, bundlePath, args: ['arming', '--channel', channel, '--data-root', root] });
-  if (result.status === 0) {return;}
-  const stderr = stderrOf(result);
-  if (stderr.includes('EVIDENCE_TRUST_REQUIRED_UNARMED')) {
-    throw new EvidenceTrustRequiredError(root, `declares a policy that is not armed on the ${channel} channel for a catalogue consumer (${stderr})`, catalogueConsumer(channel));
-  }
-  throw new CatalogueEvidenceNotVerifiedError(`the ${channel} catalogue`, `the arming check failed: ${stderr}`);
-}
-
-function layerOf(layers, title, mediaType, ref) {
-  const found = layers.filter((layer) => layer?.annotations?.[TITLE] === title);
-  if (found.length !== 1 || found[0].mediaType !== mediaType || typeof found[0].digest !== 'string') {
-    throw new CatalogueEvidenceNotVerifiedError(ref, `the referrer must carry exactly one ${title} layer of media type ${mediaType}`);
-  }
-  return found[0];
-}
-
-async function readReferrerLayers({ client, repository, referrer, manifestDigest, ref }) {
-  const manifest = await client.getManifestByDigest(repository, referrer.digest);
-  const document = manifest.document ?? {};
-  if (document.artifactType !== EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is not a ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} artifact`);
-  }
-  if (document.subject?.digest !== manifestDigest) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is a referrer of ${String(document.subject?.digest)}, not of ${manifestDigest}`);
-  }
-  const layers = Array.isArray(document.layers) ? document.layers : [];
-  if (layers.length !== 2) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} must carry exactly two layers (${CATALOGUE_EVIDENCE_STATEMENT_TITLE}, ${CATALOGUE_EVIDENCE_BUNDLE_TITLE}), it carries ${layers.length}`);
-  }
-  const statement = layerOf(layers, CATALOGUE_EVIDENCE_STATEMENT_TITLE, CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE, ref);
-  const bundle = layerOf(layers, CATALOGUE_EVIDENCE_BUNDLE_TITLE, BUNDLE_MEDIA_TYPE, ref);
-  const workflowSha = document.annotations?.[CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION];
-  if (typeof workflowSha !== 'string' || !COMMIT.test(workflowSha)) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} states no 40-hex ${CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION} annotation`);
-  }
-  return { statement, bundle, workflowSha };
-}
-
-/**
- * The seam. Hold one E4 referrer to the caller's policy and to the exact catalogue and lock layers: read its two layers
- * (bounded) into a private temporary directory and have the PINNED built verifier judge them. Throws when it does not
- * verify, returns when it does. The verifier's pin is re-checked here, before anything is spawned.
- *
- * @param {{ ref: string, client: object, repository: string, referrer: object, channel: string, offeringId: string, manifestDigest: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign: string, locateVerifier?: Function, spawn?: Function }} subject
- */
-export async function verifyCatalogueEvidenceReferrer({
-  ref,
-  client,
-  repository,
-  referrer,
-  channel,
-  offeringId,
-  manifestDigest,
-  catalogueLayerDigest,
-  lockLayerDigest,
-  cosign,
-  locateVerifier = locateBuiltVerifier,
-  spawn = spawnSync,
-}) {
-  if (typeof cosign !== 'string' || !cosign.startsWith('/')) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, 'a release catalogue is verified with a cosign binary: pass --cosign <absolute path>');
-  }
-  const layers = await readReferrerLayers({ client, repository, referrer, manifestDigest, ref });
-  const statementBytes = await client.getBlob(repository, layers.statement.digest, STATEMENT_MAX_BYTES);
-  const bundleBytes = await client.getBlob(repository, layers.bundle.digest, BUNDLE_MAX_BYTES);
-  if (sha256Of(statementBytes) !== layers.statement.digest || sha256Of(bundleBytes) !== layers.bundle.digest) {
-    throw new CatalogueEvidenceNotVerifiedError(ref, 'a referrer layer does not hash to its digest');
-  }
-  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier, channel);
-  const evidenceRoot = mkdtempSync(join(tmpdir(), 'xema-catalogue-evidence-'));
-  try {
-    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_STATEMENT_TITLE), statementBytes, { flag: 'wx', mode: 0o600 });
-    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_BUNDLE_TITLE), bundleBytes, { flag: 'wx', mode: 0o600 });
-    const result = runVerifier({
-      spawn,
-      bundlePath,
-      args: [
-        'verify',
-        '--channel', channel,
-        '--data-root', root,
-        '--evidence-root', evidenceRoot,
-        '--statement-digest', layers.statement.digest,
-        '--bundle-digest', layers.bundle.digest,
-        '--workflow-sha', layers.workflowSha,
-        '--offering-id', offeringId,
-        '--subject-digest', manifestDigest,
-        '--catalogue-layer-digest', catalogueLayerDigest,
-        '--lock-layer-digest', lockLayerDigest,
-        '--cosign', cosign,
-      ],
-    });
-    if (result.status !== 0) {throw new CatalogueEvidenceNotVerifiedError(ref, stderrOf(result));}
-  } finally {
-    rmSync(evidenceRoot, { recursive: true, force: true });
-  }
-}
-
-/**
- * Verify the catalogue's E4 evidence from the registry, before any catalogue byte is fetched or parsed.
- *
- * @param {{ client: object, ref: string, repository: string, manifestDigest: string, channel: string, offeringId: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign?: string, locateVerifier?: Function, verifyReferrer?: Function }} options
- */
-export async function verifyCatalogueEvidence({ client, ref, repository, manifestDigest, channel, offeringId, catalogueLayerDigest, lockLayerDigest, cosign, locateVerifier, verifyReferrer = verifyCatalogueEvidenceReferrer }) {
-  const listed = await client.listReferrers(repository, manifestDigest, EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
-  const referrers = listed.filter((descriptor) => descriptor?.artifactType === EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
-  if (referrers.length === 0) {throw new CatalogueEvidenceMissingError(ref);}
-  for (const referrer of referrers) {
-    await verifyReferrer({ ref, client, repository, referrer, channel, offeringId, manifestDigest, catalogueLayerDigest, lockLayerDigest, cosign, ...(locateVerifier === undefined ? {} : { locateVerifier }) });
-  }
-}

package/edition/catalogue-fetch.mjs

@@ -1,124 +0,0 @@
-// catalogue-fetch — read the catalogue layer of an offering artifact, by digest.
-//
-// The reference is `oci://<registry root>/<channel segment>/xema-edition-<id>@sha256:<digest>`
-// (it comes from catalogue.pin.json): a tag is refused, because a catalogue is pinned, not
-// followed. The repository is parsed by `parseEditionRepository`; a reference whose
-// repository channel is not the channel being resolved is refused before any fetch, and a
-// catalogue that states another channel than the repository it came from is refused before
-// it is used. The manifest and the
-// layer are fetched with the one OCI client (`oras.mjs`, the pinned oras), which verifies that
-// every body hashes to the digest it was asked for. Credentials are named by
-// environment variable (never inlined): `--catalogue-username` with
-// `--catalogue-token-env`, or neither for an anonymous read.
-
-import { Buffer } from 'node:buffer';
-
-import { verifyCatalogueEvidence } from './catalogue-evidence.mjs';
-import { CATALOGUE_FILE, CatalogueError, parseCatalogue } from './catalogue.mjs';
-import { parseEditionRepository } from './edition-artifact.mjs';
-import { EDITION_ARTIFACT_TYPE, EditionChannel, EditionLockFile } from './edition-constants.mjs';
-import { OrasRegistry } from './oras.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-
-const REF = /^oci:\/\/([^@]+)@(sha256:[a-f0-9]{64})$/;
-const CATALOGUE_MAX_BYTES = 32 * 1024 * 1024;
-const TITLE = 'org.opencontainers.image.title';
-
-/**
- * `{ authority, repository, digest, edition }` of an `oci://<repository>@sha256:<digest>` reference, where
- * `edition` is the parsed repository (`{ registryRoot, channel, distributionId }`); a tag is refused.
- */
-export function parseCatalogueRef(ref) {
-  const match = REF.exec(String(ref));
-  if (match === null) {
-    throw new CatalogueError(`catalogue reference ${JSON.stringify(ref)} is not oci://<registry>/<repository>@sha256:<64 hex>: a catalogue is pinned by digest, never by tag`);
-  }
-  const { authority, repository } = splitImageRef(match[1]);
-  let edition;
-  try {
-    edition = parseEditionRepository(match[1]);
-  } catch (error) {
-    throw new CatalogueError(`catalogue reference ${JSON.stringify(ref)}: ${error.message}`, { cause: error });
-  }
-  return { authority, repository, digest: match[2], edition };
-}
-
-/** The credential the client needs: named by env var, or anonymous. */
-export function catalogueCredential({ authority, username, tokenEnv, env = process.env }) {
-  if ((username === undefined) !== (tokenEnv === undefined)) {
-    throw new CatalogueError('--catalogue-username and --catalogue-token-env go together (or neither, for an anonymous read)');
-  }
-  if (tokenEnv === undefined) {return { authority, access: 'anonymous', basicAuth: null };}
-  const token = env[tokenEnv];
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new CatalogueError(`--catalogue-token-env names ${tokenEnv}, which is unset or empty`);
-  }
-  return { authority, access: 'authenticated', basicAuth: Buffer.from(`${username}:${token}`, 'utf8').toString('base64') };
-}
-
-/** The one layer of `manifest` titled `title`; an offering artifact carries exactly one of each. */
-export function layerTitled(manifest, title, ref) {
-  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === title);
-  if (layers.length !== 1) {
-    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${title}; an offering artifact carries exactly one`);
-  }
-  return layers[0];
-}
-
-/**
- * Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. A RELEASE catalogue is read
- * only after its E4 evidence verified against the caller's own evidence trust policy (catalogue-evidence.mjs): the
- * verification precedes the blob fetch and the parse, so an unverified catalogue is never read. It is done by the data
- * root's pinned built verifier, with the absolute `cosign` the caller names. `client` and `verifyEvidence` are injectable
- * for tests.
- */
-export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client, cosign, locateVerifier, verifyEvidence = verifyCatalogueEvidence }) {
-  const { authority, repository, digest, edition } = parseCatalogueRef(ref);
-  if (edition.channel !== channel) {
-    throw new CatalogueError(
-      `${ref}: its repository ${authority}/${repository} is a ${edition.channel} repository, but this resolve is for the ${channel} channel; ` +
-        'a catalogue is read only from the repository of the channel being resolved',
-    );
-  }
-  const registry = client ?? new OrasRegistry({ credential: catalogueCredential({ authority, username, tokenEnv, env }) });
-  const manifest = await registry.getManifestByDigest(repository, digest);
-  if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
-    throw new CatalogueError(`${ref} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
-  }
-  const catalogueLayer = layerTitled(manifest, CATALOGUE_FILE, ref);
-  if (channel === EditionChannel.Release) {
-    await verifyEvidence({
-      client: registry,
-      ref,
-      repository,
-      manifestDigest: digest,
-      channel,
-      offeringId: edition.distributionId,
-      cosign,
-      locateVerifier,
-      catalogueLayerDigest: catalogueLayer.digest,
-      lockLayerDigest: layerTitled(manifest, EditionLockFile.Distribution, ref).digest,
-    });
-  }
-  const bytes = await registry.getBlob(repository, catalogueLayer.digest, CATALOGUE_MAX_BYTES);
-  let document;
-  try {
-    document = JSON.parse(bytes.toString('utf8'));
-  } catch (error) {
-    throw new CatalogueError(`${ref}: ${CATALOGUE_FILE} is not JSON: ${error.message}`);
-  }
-  const catalogue = parseCatalogue(document);
-  if (catalogue.offeringId !== edition.distributionId) {
-    throw new CatalogueError(
-      `${ref}: ${CATALOGUE_FILE} is the catalogue of offering ${catalogue.offeringId}, but it was fetched from the repository of offering ${edition.distributionId}; ` +
-        'an artifact whose stated offering differs from its repository is refused',
-    );
-  }
-  if (catalogue.channel !== edition.channel) {
-    throw new CatalogueError(
-      `${ref}: ${CATALOGUE_FILE} states channel ${catalogue.channel}, but it was fetched from the ${edition.channel} repository ${authority}/${repository}; ` +
-        'an artifact whose stated channel differs from its repository is refused',
-    );
-  }
-  return { catalogue, digest };
-}

package/edition/catalogue-lock-field.mjs

@@ -1,41 +0,0 @@
-// catalogue-lock-field — how a customer edition's distribution lock names the catalogue it was resolved against
-// (kernel edition protocol v37, DistributionLock): EXACTLY ONE of
-//
-//   catalogueDigest         the digest of a PUBLISHED catalogue artifact (the catalogue pin form);
-//   catalogueContentDigest  sha256 of the exact catalogue.json bytes a catalogue-free resolve's vendor step wrote
-//                           (the catalogue-free pin form: no catalogue artifact exists).
-//
-// The kernel refuses a lock carrying both; this CLI refuses a request naming both or neither, and a field that is
-// not its pin form's, before anything is resolved or sealed.
-
-/** The two lock fields, by what they digest. */
-export const CatalogueLockField = Object.freeze({ Artifact: 'catalogueDigest', Content: 'catalogueContentDigest' });
-
-/**
- * `{ key, digest }` of the one catalogue field `request` names (CatalogueLockField). Throws `new ErrorType(message)`
- * when it names both or neither; `what` names the caller in the message.
- */
-export function catalogueLockFieldOf(request, { what, ErrorType = Error }) {
-  const named = Object.values(CatalogueLockField).filter((key) => request?.[key] !== undefined);
-  if (named.length !== 1) {
-    throw new ErrorType(`${what} names ${named.length === 0 ? 'neither' : 'both'} ${CatalogueLockField.Artifact} (a published catalogue) ${named.length === 0 ? 'nor' : 'and'} ${CatalogueLockField.Content} (a catalogue-free resolve): exactly one`);
-  }
-  const [key] = named;
-  return { key, digest: request[key] };
-}
-
-/** The lock field of a customer edition's pin form: the catalogue-free form records the content digest, the catalogue form the artifact digest. */
-export const catalogueLockFieldOfForm = (catalogueFree) => (catalogueFree ? CatalogueLockField.Content : CatalogueLockField.Artifact);
-
-/**
- * The one catalogue field of a customer edition's lock, `{ key, digest }`: exactly one named, and the one its pin form
- * records (`catalogueFree`: the catalogue-free form). Throws `new ErrorType(message)` otherwise.
- */
-export function customerLockCatalogueField({ catalogueFree, catalogueDigest, catalogueContentDigest }, { what, ErrorType = Error }) {
-  const field = catalogueLockFieldOf({ catalogueDigest, catalogueContentDigest }, { what, ErrorType });
-  const formField = catalogueLockFieldOfForm(catalogueFree);
-  if (field.key !== formField) {
-    throw new ErrorType(`a ${catalogueFree ? 'catalogue-free' : 'catalogue-form'} customer edition names its catalogue by ${formField}, not ${field.key}`);
-  }
-  return field;
-}

package/edition/catalogue-pin.mjs

@@ -1,71 +0,0 @@
-// catalogue-pin — `catalogue.pin.json`, the catalogues a customer edition is resolved against.
-//
-// It sits in the SAME directory as the customer's definition file:
-//   { "schemaVersion": 1, "develop": "oci://<repository>@sha256:<64 hex>" | null, "release": ... | null }
-// Exactly these keys, both channel keys present; null states that the edition is not produced on
-// that channel. A reference is parsed by `parseCatalogueRef`, and the repository channel of the
-// reference under a key must be that key. This is the only reader of the file: every customer
-// resolve takes the catalogue reference of its channel from here.
-
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-
-import { parseCatalogueRef } from './catalogue-fetch.mjs';
-import { CatalogueError } from './catalogue.mjs';
-import { EditionChannel } from './edition-constants.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-
-export const CATALOGUE_PIN_FILE = 'catalogue.pin.json';
-export const CATALOGUE_PIN_SCHEMA_VERSION = 1;
-
-const SCHEMA_VERSION_KEY = 'schemaVersion';
-
-/** The catalogue pin file that sits beside `definitionFile`. */
-export const cataloguePinFile = (definitionFile) => join(dirname(definitionFile), CATALOGUE_PIN_FILE);
-
-/** The strict parse of a pin document read from `file`; returns it unchanged. */
-export function parseCataloguePins(document, file) {
-  const channels = Object.values(EditionChannel);
-  const expected = [SCHEMA_VERSION_KEY, ...channels].sort().join();
-  if (document === null || typeof document !== 'object' || Array.isArray(document) || Object.keys(document).sort().join() !== expected) {
-    throw new CatalogueError(`${file} must be exactly {${[SCHEMA_VERSION_KEY, ...channels].join(', ')}}, every key present`);
-  }
-  if (document[SCHEMA_VERSION_KEY] !== CATALOGUE_PIN_SCHEMA_VERSION) {
-    throw new CatalogueError(`${file}: ${SCHEMA_VERSION_KEY} must be ${CATALOGUE_PIN_SCHEMA_VERSION}`);
-  }
-  for (const channel of channels) {
-    const ref = document[channel];
-    if (ref === null) {continue;}
-    if (typeof ref !== 'string') {
-      throw new CatalogueError(`${file}: "${channel}" must be an oci://<repository>@sha256:<64 hex> reference or null`);
-    }
-    let parsed;
-    try {
-      parsed = parseCatalogueRef(ref);
-    } catch (error) {
-      throw new CatalogueError(`${file}: "${channel}": ${error.message}`, { cause: error });
-    }
-    if (parsed.edition.channel !== channel) {
-      throw new CatalogueError(
-        `${file}: "${channel}" pins ${ref}, whose repository is a ${parsed.edition.channel} repository; a ${channel} catalogue is pinned in a ${channel} repository`,
-      );
-    }
-  }
-  return document;
-}
-
-/** The catalogue reference pinned for `channel` beside `definitionFile`; a null pin or a missing file is refused. */
-export function readCataloguePin({ definitionFile, channel }) {
-  const file = cataloguePinFile(definitionFile);
-  if (!existsSync(file)) {
-    throw new CatalogueError(`${file} does not exist: a customer edition pins its catalogues in ${CATALOGUE_PIN_FILE}, beside the definition`);
-  }
-  const ref = parseCataloguePins(readStrictJsonFile(file), file)[channel];
-  if (ref === undefined) {
-    throw new CatalogueError(`${file}: ${JSON.stringify(channel)} is not a channel (${Object.values(EditionChannel).join(' | ')})`);
-  }
-  if (ref === null) {
-    throw new CatalogueError(`${file}: no ${channel} catalogue is pinned for this edition`);
-  }
-  return ref;
-}