@xemahq/xema 0.59.1 → 0.60.1

package/edition/distribution-evidence-set.mjs

@@ -1,1064 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// THE DISTRIBUTION-LEVEL EVIDENCE SET — ONE OWNER FOR ITS SHAPE
-//
-//   `produce-image-source-evidence.mjs` signs ONE statement per image, in the
-//   repository that built it. This module owns everything that happens ABOVE
-//   that: gathering those per-image bundles for one edition, stating that the
-//   set is COMPLETE, entitling a customer to a delivery of it, and assembling
-//   the `evidence-set.json` the offline verifier reads.
-//
-//   It exists as its own module because three entrypoints need exactly the
-//   same shapes and would otherwise each grow their own copy:
-//
-//     * produce-distribution-completeness-evidence.mjs  (signs completeness)
-//     * produce-image-delivery-entitlement-evidence.mjs (signs entitlement)
-//     * distribution-evidence-producer-contract-tests.mjs (proves both agree
-//       with the VERIFIER's own binding validators)
-//
-//   Every shape here is parsed through the kernel schema before it is returned,
-//   so a statement this module builds and a statement the verifier accepts are
-//   the same object by construction, not by review.
-//
-// WHAT IS DELIBERATELY *NOT* HERE
-//
-//   Signature verification. Staging reads committed bundles and proves they are
-//   internally consistent (descriptor digests, DSSE payload equality, kernel
-//   schema, exact source coordinate) — it does NOT verify Sigstore signatures.
-//   That is `image-evidence.mjs verifyDistributionImageEvidenceSet`, offline,
-//   against the armed trust policy, at delivery. Re-implementing it here would
-//   be a second trust decision in a place with no trust anchor.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { createHash } from 'node:crypto';
-import {
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  writeFileSync,
-} from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
-
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { COMMIT_PATTERN, SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
-import {
-  loadPinnedDeclaredTrustPolicy,
-} from './evidence-trust-pin.mjs';
-import {
-  EVIDENCE_TREE_ROOT,
-  canonicalJson,
-  canonicalJsonBytes,
-  compareCompletenessImages,
-  decodeExactUtf8,
-  evidenceDirectoryForDigest,
-  loadValidatedLocks,
-  normalizedImageLockDigest,
-  sha256Digest,
-  sourceIdentity,
-} from './image-evidence.mjs';
-import { completenessImageKey } from './image-subject-identity.mjs';
-import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
-import { compareStrings } from './lib.mjs';
-import { readBoundedNoFollowFile } from './no-follow-file.mjs';
-import {
-  createRegistryClientResolver,
-  describeInvalidReferrer,
-  resolveImageSourceEvidenceReferrer,
-  writeInvalidReferrerReport,
-} from './oci-image-source-evidence.mjs';
-import { BUNDLE_MEDIA_TYPE, canonicalSignedBundleBytes, cosignVerifyAttestationArgs, validateProducedBundle } from './produce-image-source-evidence.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-import { imageSubjectKey, thirdPartyImagePins } from './third-party-image-pins.mjs';
-import { thirdPartyProducerRecord } from './third-party-producer-evidence.mjs';
-
-/**
- * The ONE Sigstore bundle media type this plane stores — re-exported, never
- * re-declared. The kernel's `SigstoreEvidenceDescriptorSchema` accepts this
- * literal and nothing else, and `produce-image-source-evidence.mjs` owns it.
- */
-export { BUNDLE_MEDIA_TYPE };
-
-/** Same bound `check-committed-image-evidence.mjs` reads committed files at. */
-const MAX_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
-
-/** `evidence/sha256-<64 hex>` — the shape `evidenceDirectoryForDigest` emits. */
-const EVIDENCE_DIRECTORY_PATTERN = /^sha256-[a-f0-9]{64}$/;
-
-
-function assertAbsolutePath(value, label) {
-  if (typeof value !== 'string' || !isAbsolute(value)) {
-    throw new Error(`${label} must be an absolute path`);
-  }
-  return value;
-}
-
-/**
- * The issuance window a statement may carry.
- *
- * `image-evidence.mjs assertTimeWindow` is the VERIFIER's copy of this rule and
- * additionally compares against `now`. A producer cannot use it: it signs at
- * issuance, so "not yet valid" and "expired" are not decidable statements about
- * its own output — but the MAXIMUM TTL is, and refusing an over-long TTL here
- * is what stops a statement that can never verify from being signed at all.
- */
-function assertIssuanceWindow({ issuedAt, expiresAt, maxTtlSeconds, label }) {
-  const issued = Date.parse(issuedAt);
-  const expires = Date.parse(expiresAt);
-  if (!Number.isFinite(issued) || !Number.isFinite(expires)) {
-    throw new Error(`${label} has an invalid issuedAt/expiresAt`);
-  }
-  if (!Number.isSafeInteger(maxTtlSeconds) || maxTtlSeconds <= 0) {
-    throw new Error(`${label} requires a positive maximum TTL from the policy`);
-  }
-  if (expires <= issued) {
-    throw new Error(`${label} expiresAt must be after issuedAt`);
-  }
-  if (expires - issued > maxTtlSeconds * 1000) {
-    throw new Error(
-      `${label} TTL ${Math.floor((expires - issued) / 1000)}s exceeds the ` +
-        `policy maximum of ${maxTtlSeconds}s`,
-    );
-  }
-}
-
-/**
- * The canonical order of an evidence subject list — the VERIFIER's own
- * comparator, re-exported. `validateCompletenessStatementBinding` refuses a
- * statement whose `images[]` is not in this order, so a second copy here would
- * be a comparator a signature is bound to, drifting from the one that judges it.
- */
-export { compareCompletenessImages as compareEvidenceSubjects };
-
-/**
- * Deterministic per-subject artifact stem inside a staged evidence root.
- * Keyed by the same `kind\0id` identity `image-evidence.mjs` uses everywhere
- * else, so two subjects can never collide and one subject can never move.
- */
-export function subjectStem(subject) {
-  return createHash('sha256')
-    .update(sourceIdentity(subject))
-    .digest('hex');
-}
-
-/**
- * Nonces are DERIVED from run identity, never random.
- *
- * Same construction as `evidenceNonce` in `produce-image-source-evidence.mjs`,
- * with its own domain-separation prefix so a completeness nonce can never
- * collide with a producer or entitlement nonce — the verifier keeps ONE
- * consumed-nonce set across all three and rejects a reuse
- * (`validateCompletenessStatementBinding` refuses a statement that replays a
- * producer nonce).
- *
- * Derivation, not randomness, is what makes a re-run of the SAME release
- * byte-identical: a random nonce would make every retry a distinct statement
- * and the replay state could never tell a retry from a rollback attempt.
- */
-function derivedNonce(domain, parts) {
-  const hash = createHash('sha256').update(`${domain}\0`);
-  for (const part of parts) {
-    hash.update(String(part)).update('\0');
-  }
-  return hash.digest('base64url');
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Reading the committed producer evidence of every producing repository
-// ─────────────────────────────────────────────────────────────────────────────
-
-function readCommittedArtifact(evidenceDirectory, relativePath, label) {
-  return readBoundedNoFollowFile(
-    evidenceDirectory,
-    relativePath,
-    label,
-    MAX_EVIDENCE_FILE_BYTES,
-  ).bytes;
-}
-
-/**
- * Index every committed producer bundle reachable from the given producing
- * repository checkouts, keyed by the EXACT source coordinate its statement
- * attests (`canonicalJson(predicate.source)`).
- *
- * `onDefect` is REQUIRED and has no default: the two callers make opposite —
- * and both correct — decisions about a malformed committed bundle. Staging must
- * abort (it is about to build a release around this evidence); the refresh
- * planner must classify and continue (its entire job is reporting what is
- * broken). A default here would silently give one of them the other's posture.
- *
- * @returns {Map<string, Array<object>>}
- */
-export function indexCommittedProducerEvidence({
-  producerRepositoryRoots,
-  schemas,
-  onDefect,
-}) {
-  if (
-    !Array.isArray(producerRepositoryRoots) ||
-    producerRepositoryRoots.length === 0
-  ) {
-    throw new Error('at least one producing repository root is required');
-  }
-  if (typeof onDefect !== 'function') {
-    throw new Error(
-      'a defect handler is required — staging and planning must not share a default posture',
-    );
-  }
-  if (!schemas?.parseImageProducerStatement) {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
-  const seenRoots = new Set();
-  const index = new Map();
-  for (const root of producerRepositoryRoots) {
-    assertAbsolutePath(root, 'producing repository root');
-    if (seenRoots.has(root)) {
-      throw new Error(`producing repository root ${root} was given twice`);
-    }
-    seenRoots.add(root);
-    const evidenceRoot = join(root, EVIDENCE_TREE_ROOT);
-    let entries;
-    try {
-      entries = readdirSync(evidenceRoot, { withFileTypes: true });
-    } catch {
-      // A producing repository that has never produced evidence is not a
-      // defect — it is exactly the ABSENT verdict the planner must report and
-      // the "no matching bundle" failure staging must raise, per subject.
-      continue;
-    }
-    for (const entry of [...entries].sort((left, right) =>
-      compareStrings(left.name, right.name),
-    )) {
-      const directory = join(evidenceRoot, entry.name);
-      if (entry.isSymbolicLink()) {
-        onDefect({
-          root,
-          directory,
-          subjectKey: null,
-          reason: `${EVIDENCE_TREE_ROOT}/${entry.name} is a symlink`,
-        });
-        continue;
-      }
-      if (!entry.isDirectory()) {continue;}
-      if (!EVIDENCE_DIRECTORY_PATTERN.test(entry.name)) {
-        onDefect({
-          root,
-          directory,
-          subjectKey: null,
-          reason: `${EVIDENCE_TREE_ROOT}/${entry.name} is not a sha256-<digest> evidence directory`,
-        });
-        continue;
-      }
-      indexOneEvidenceDirectory({
-        root,
-        directory,
-        directoryName: entry.name,
-        schemas,
-        onDefect,
-        index,
-      });
-    }
-  }
-  return index;
-}
-
-function indexOneEvidenceDirectory({
-  root,
-  directory,
-  directoryName,
-  schemas,
-  onDefect,
-  index,
-}) {
-  let indexDocument;
-  try {
-    indexDocument = JSON.parse(
-      decodeExactUtf8(
-        readCommittedArtifact(directory, 'producer-evidence.json', 'producer index'),
-        'producer index',
-      ),
-    );
-  } catch (error) {
-    onDefect({
-      root,
-      directory,
-      subjectKey: null,
-      reason: `producer-evidence.json is missing or unreadable: ${error.message}`,
-    });
-    return;
-  }
-  if (
-    indexDocument?.schemaVersion !== 1 ||
-    !Array.isArray(indexDocument.producerEvidence) ||
-    indexDocument.producerEvidence.length === 0
-  ) {
-    onDefect({
-      root,
-      directory,
-      subjectKey: null,
-      reason: 'producer-evidence.json is not a non-empty schemaVersion 1 index',
-    });
-    return;
-  }
-  for (const entry of indexDocument.producerEvidence) {
-    if (
-      entry === null ||
-      typeof entry !== 'object' ||
-      typeof entry.subjectKind !== 'string' ||
-      typeof entry.subjectId !== 'string' ||
-      entry.evidence === null ||
-      typeof entry.evidence !== 'object'
-    ) {
-      onDefect({
-        root,
-        directory,
-        subjectKey: null,
-        reason: 'producer-evidence.json carries a malformed entry',
-      });
-      continue;
-    }
-    // Only named in a defect: the record is indexed by the statement's own source coordinate, which already
-    // tells the generations of a composed artifact apart (its sourceTreeHash).
-    const subjectKey = `${entry.subjectKind}:${entry.subjectId}`;
-    const descriptor = entry.evidence;
-    let statementBytes;
-    let bundleBytes;
-    let statement;
-    try {
-      statementBytes = readCommittedArtifact(
-        directory,
-        descriptor.statementPath,
-        `${entry.subjectKind}:${entry.subjectId} statement`,
-      );
-      bundleBytes = readCommittedArtifact(
-        directory,
-        descriptor.bundlePath,
-        `${entry.subjectKind}:${entry.subjectId} bundle`,
-      );
-      if (
-        sha256Digest(statementBytes) !== descriptor.statementDigest ||
-        sha256Digest(bundleBytes) !== descriptor.bundleDigest ||
-        descriptor.bundleMediaType !== BUNDLE_MEDIA_TYPE
-      ) {
-        throw new Error(
-          'committed artifacts do not match the digests and media type producer-evidence.json records',
-        );
-      }
-      // Proves the bundle carries exactly ONE DSSE in-toto signature whose
-      // payload is byte-identical to the statement. Reused from the producer so
-      // the staged bytes are validated by the very code that wrote them.
-      validateProducedBundle(statementBytes, bundleBytes);
-      statement = schemas.parseImageProducerStatement(
-        JSON.parse(decodeExactUtf8(statementBytes, 'committed statement')),
-      );
-      if (
-        evidenceDirectoryForDigest(statement.predicate.artifact.manifestDigest) !==
-        `${EVIDENCE_TREE_ROOT}/${directoryName}`
-      ) {
-        throw new Error(
-          `statement attests ${statement.predicate.artifact.manifestDigest}, which is not the digest this directory is named after`,
-        );
-      }
-      if (
-        statement.predicate.source.kind !== entry.subjectKind ||
-        statement.predicate.source.id !== entry.subjectId
-      ) {
-        throw new Error(
-          `statement attests ${statement.predicate.source.kind}:${statement.predicate.source.id}, which producer-evidence.json indexes as ${entry.subjectKind}:${entry.subjectId}`,
-        );
-      }
-    } catch (error) {
-      onDefect({ root, directory, subjectKey, reason: error.message });
-      continue;
-    }
-    const coordinate = canonicalJson(statement.predicate.source);
-    const record = {
-      root,
-      directory,
-      subjectKind: statement.predicate.source.kind,
-      subjectId: statement.predicate.source.id,
-      statement,
-      statementBytes,
-      bundleBytes,
-      descriptor,
-    };
-    const incumbent = index.get(coordinate);
-    if (incumbent === undefined) {
-      index.set(coordinate, [record]);
-    } else {
-      incumbent.push(record);
-    }
-  }
-}
-
-/**
- * The exact source coordinate a producer statement must attest for one locked
- * subject: the lock's own fields joined with the repository pin the runtime
- * index committed. Value-identical to `expectedSource` in
- * `image-evidence.mjs validateProducerStatementBinding` — that function is the
- * verifier's authority and the contract tests prove agreement by round-tripping
- * a staged statement through it.
- */
-export function expectedProducerSource({
-  subject,
-  repositoryPin,
-  sourceHashAlgorithm,
-}) {
-  if (
-    repositoryPin?.repo !== subject.repo ||
-    repositoryPin.sourceCommit !== subject.sourceCommit
-  ) {
-    throw new Error(
-      `runtime subject "${subject.kind}:${subject.id}" does not match the committed repository pin for ${subject.repo}`,
-    );
-  }
-  return {
-    kind: subject.kind,
-    id: subject.id,
-    repositoryUrl: repositoryPin.repositoryUrl,
-    repo: subject.repo,
-    path: subject.path,
-    sourceCommit: subject.sourceCommit,
-    sourceManifestHash: subject.sourceManifestHash,
-    sourceHashAlgorithm,
-    sourceTreeHash: subject.contentHash,
-  };
-}
-
-/**
- * Resolve the committed producer bundle of every subject in one edition's
- * `images.lock.json` and COPY the pairs into `outputRoot`.
- *
- * Copying (rather than referencing the producing checkouts in place) is what
- * makes the evidence root a self-contained artifact: `evidence-set.json`
- * descriptor paths are relative to it, and the offline verifier is handed that
- * one directory with no access to any producing repository.
- *
- * @returns {Promise<{distributionLock, imageLock, producers: Array<object>,
- *   producerEvidence: Array<object>, images: Array<object>}>}
- */
-export async function stageProducerEvidence({ outputRoot, ...resolution }) {
-  assertAbsolutePath(outputRoot, 'staging output root');
-  const resolved = await resolveProducerEvidence(resolution);
-  for (const producer of resolved.producers) {
-    mkdirSync(join(outputRoot, 'producers', producer.stem), { recursive: true, mode: 0o700 });
-    for (const [path, bytes] of stagedProducerFiles(producer)) {
-      writeFileSync(join(outputRoot, path), bytes, { flag: 'wx', mode: 0o644 });
-    }
-  }
-  return resolved;
-}
-
-/** The staged path and the exact bytes of both files of one producer's evidence. */
-export function stagedProducerFiles(producer) {
-  return [
-    [producer.evidence.statementPath, producer.statementBytes],
-    [producer.evidence.bundlePath, producer.bundleBytes],
-  ];
-}
-
-/**
- * Resolve the published producer evidence of every subject in one edition's
- * `images.lock.json`; writes nothing. The accept re-derives it with this and
- * compares it with the staging, so what it seals is what the registry serves.
- */
-export async function resolveProducerEvidence({
-  distributionId,
-  dataRoot,
-  editionsRoot,
-  schemas,
-  expectedContractAuthority,
-  registryClientFactory,
-  channel,
-  // The reader of the edition's validated locks; a seam so the assembly is testable without a whole edition tree.
-  loadLocks = loadValidatedLocks,
-}) {
-  assertCanonicalDistributionId(distributionId);
-  assertAbsolutePath(dataRoot, 'data root');
-  assertAbsolutePath(editionsRoot, 'editions root');
-  if (!expectedContractAuthority) {
-    throw new Error('the expected kernel contract authority is required');
-  }
-  const { distributionLock, imageLock, repositoryPins, runtimeSourceIndex, thirdPartySources } =
-    await loadLocks(distributionId, dataRoot, schemas, { editionsRoot, channel });
-  assertKernelContractAuthorityEqual(
-    runtimeSourceIndex.contractAuthority,
-    expectedContractAuthority,
-    'runtime-image-source-index.json',
-  );
-  const clientFor = createRegistryClientResolver({
-    dataRoot,
-    factory: registryClientFactory,
-  });
-
-  const thirdPartyImages = thirdPartyImagePins({
-    pins: { byRepository: (repository) => thirdPartySources.get(repository) },
-    subjects: imageLock.subjects,
-  });
-  const producers = [];
-  for (const subject of imageLock.subjects) {
-    const pinImage = thirdPartyImages.get(imageSubjectKey(subject));
-    if (pinImage !== undefined) {
-      // A third-party subject's contentHash is publisher-attested, not a tag: its evidence is the committed evidence its pin
-      // binds, read from the data root with no registry call.
-      producers.push(
-        thirdPartyProducerRecord({
-          subject,
-          pinImage,
-          dataRoot,
-          schemas,
-          expectedSource: expectedProducerSource({
-            subject,
-            repositoryPin: repositoryPins.get(subject.repo),
-            sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
-          }),
-          stem: subjectStem(subject),
-        }),
-      );
-      continue;
-    }
-    const expectedSource = expectedProducerSource({
-      subject,
-      repositoryPin: repositoryPins.get(subject.repo),
-      sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
-    });
-    const { authority, repository } = splitImageRef(subject.imageRef);
-    const client = clientFor(authority);
-    const image = await client.getManifestByTag(repository, subject.contentHash);
-    const invalidReferrers = [];
-    const ociEvidence = await resolveImageSourceEvidenceReferrer({
-      client,
-      imageRepository: subject.imageRef,
-      subjectDigest: image.digest,
-      schemas,
-      expectedContractAuthority,
-      onInvalidReferrer: (skipped) => {
-        invalidReferrers.push(skipped);
-        writeInvalidReferrerReport(skipped);
-      },
-    });
-    if (ociEvidence === null && invalidReferrers.length > 0) {
-      throw new Error(
-        `no valid OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +
-          `at ${subject.imageRef}@${image.digest}: ` +
-          invalidReferrers.map(describeInvalidReferrer).join('; '),
-      );
-    }
-    if (ociEvidence === null) {
-      throw new Error(
-        `no OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +
-          `at ${subject.imageRef}@${image.digest}`,
-      );
-    }
-    const matches = ociEvidence.records
-      .filter(
-        (record) =>
-          canonicalJson(record.statement.predicate.source) ===
-          canonicalJson(expectedSource),
-      )
-      .map((record) => ({
-        ...record,
-        root: subject.imageRef,
-        directory: `oci://${subject.imageRef}@${ociEvidence.artifactDigest}`,
-      }));
-    if (matches.length === 0) {
-      throw new Error(
-        `no published producer evidence attests "${subject.kind}:${subject.id}" at ` +
-          `${subject.repo}@${subject.sourceCommit} (source tree ${subject.contentHash})`,
-      );
-    }
-    const [match] = matches;
-    const { artifact } = match.statement.predicate;
-    if (
-      artifact.imageRepository !== subject.imageRef ||
-      match.statement.subject[0].name !== subject.imageRef ||
-      `sha256:${match.statement.subject[0].digest.sha256}` !==
-        artifact.manifestDigest
-    ) {
-      throw new Error(
-        `committed producer evidence for "${subject.kind}:${subject.id}" attests image ` +
-          `"${artifact.imageRepository}", not the locked "${subject.imageRef}"`,
-      );
-    }
-    const stem = subjectStem(subject);
-    producers.push({
-      stem,
-      subjectKind: subject.kind,
-      subjectId: subject.id,
-      imageRepository: subject.imageRef,
-      manifestDigest: artifact.manifestDigest,
-      statement: match.statement,
-      sourceDirectory: match.directory,
-      statementBytes: match.statementBytes,
-      bundleBytes: match.bundleBytes,
-      evidence: {
-        statementPath: `producers/${stem}/statement.json`,
-        statementDigest: sha256Digest(match.statementBytes),
-        bundlePath: `producers/${stem}/bundle.sigstore.json`,
-        bundleDigest: sha256Digest(match.bundleBytes),
-        bundleMediaType: BUNDLE_MEDIA_TYPE,
-      },
-    });
-  }
-  producers.sort(compareCompletenessImages);
-
-  return {
-    distributionLock,
-    imageLock,
-    producers,
-    producerEvidence: producers.map(({ subjectKind, subjectId, evidence }) => ({
-      subjectKind,
-      subjectId,
-      evidence,
-    })),
-    images: producers.map((producer) => ({
-      subjectKind: producer.subjectKind,
-      subjectId: producer.subjectId,
-      imageRepository: producer.imageRepository,
-      manifestDigest: producer.manifestDigest,
-      producerStatementDigest: producer.evidence.statementDigest,
-      producerBundleDigest: producer.evidence.bundleDigest,
-    })),
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Statement shapes
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * The evidence channel a signer signs for: the one whose kernel-assigned ref (`EVIDENCE_CHANNEL_REFS`) is the
- * signer's workflow ref. The kernel's policy schema ties each policy row to exactly that ref, so the signer's ref
- * IS the channel the verifying row will state. A ref no channel owns is refused.
- */
-export function evidenceChannelOfSigner(signer, schemas) {
-  const ref = signer?.githubWorkflow?.ref;
-  const channel = schemas.EVIDENCE_CHANNELS.find((candidate) => schemas.EVIDENCE_CHANNEL_REFS[candidate] === ref);
-  if (channel === undefined) {
-    throw new Error(
-      `the signer workflow ref "${String(ref)}" is the ref of no evidence channel (${schemas.EVIDENCE_CHANNELS.map((candidate) => `${candidate}: ${schemas.EVIDENCE_CHANNEL_REFS[candidate]}`).join(', ')})`,
-    );
-  }
-  return channel;
-}
-
-/**
- * The distribution-completeness statement: "these EXACT images, produced by
- * these EXACT bundles, are the complete image set of this edition at this
- * release commit."
- */
-export function buildDistributionImagesStatement({
-  distributionLock,
-  imageLock,
-  images,
-  channel,
-  releaseSequence,
-  releaseSourceCommit,
-  runId,
-  runAttempt,
-  issuedAt,
-  expiresAt,
-  maxTtlSeconds,
-  schemas,
-}) {
-  if (!schemas?.parseDistributionImagesStatement || typeof schemas.distributionLockDigest !== 'function') {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
-  if (
-    distributionLock?.distributionId !== imageLock?.distributionId ||
-    typeof distributionLock.inputHash !== 'string'
-  ) {
-    throw new Error(
-      'distribution completeness requires the distribution and image locks of ONE edition',
-    );
-  }
-  const label = `distribution completeness for ${imageLock.distributionId}`;
-  if (!COMMIT_PATTERN.test(releaseSourceCommit ?? '')) {
-    throw new Error(`${label} requires an exact 40-hex release source commit`);
-  }
-  if (!Number.isSafeInteger(releaseSequence) || releaseSequence < 0) {
-    throw new Error(`${label} requires a non-negative release sequence`);
-  }
-  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0) {
-    throw new Error(`${label} requires a positive run attempt`);
-  }
-  assertIssuanceWindow({ issuedAt, expiresAt, maxTtlSeconds, label });
-
-  if (!Array.isArray(images) || images.length === 0) {
-    throw new Error(`${label} has an empty image set`);
-  }
-  // The COMPLETE set, exactly: the verifier rebuilds this list from the lock
-  // and refuses anything that is missing, extra, or out of canonical order.
-  // Refusing here as well means an incomplete set can never be SIGNED, rather
-  // than being signed and rejected days later at a customer install.
-  const expectedIdentities = imageLock.subjects
-    .map((subject) =>
-      completenessImageKey({
-        subjectKind: subject.kind,
-        subjectId: subject.id,
-        imageRepository: subject.imageRef,
-        manifestDigest: subject.imageDigest,
-      }),
-    )
-    .sort(compareStrings);
-  const actualIdentities = images
-    .map((image) => completenessImageKey(image))
-    .sort(compareStrings);
-  if (
-    new Set(actualIdentities).size !== actualIdentities.length ||
-    canonicalJson(expectedIdentities) !== canonicalJson(actualIdentities)
-  ) {
-    throw new Error(
-      `${label} image set is not the exact complete subject set of images.lock.json`,
-    );
-  }
-  const ordered = [...images].sort(compareCompletenessImages);
-  if (canonicalJson(images) !== canonicalJson(ordered)) {
-    throw new Error(`${label} image set is not canonically ordered`);
-  }
-
-  // ONE owner for "what digest names this lock": the verifier compares against
-  // `normalizedImageLockDigest(imageLock)`, so a second inline computation here
-  // would be the exact drift this binding exists to catch.
-  const normalizedLockDigest = normalizedImageLockDigest(imageLock);
-  const statement = {
-    _type: 'https://in-toto.io/Statement/v1',
-    subject: [
-      {
-        name: `xema-distribution/${imageLock.distributionId}`,
-        digest: { sha256: normalizedLockDigest.slice('sha256:'.length) },
-      },
-    ],
-    predicateType: schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE,
-    predicate: {
-      schemaVersion: 2,
-      channel,
-      lockDigest: schemas.distributionLockDigest(distributionLock),
-      distributionId: imageLock.distributionId,
-      distributionInputHash: distributionLock.inputHash,
-      normalizedImageLockDigest: normalizedLockDigest,
-      releaseSequence,
-      releaseSourceCommit,
-      runId,
-      runAttempt,
-      nonce: derivedNonce('xema.distribution-completeness-evidence.nonce.v1', [
-        runId,
-        runAttempt,
-        imageLock.distributionId,
-        releaseSourceCommit,
-        releaseSequence,
-        normalizedLockDigest,
-      ]),
-      issuedAt,
-      expiresAt,
-      images: ordered.map((image) => ({
-        subjectKind: image.subjectKind,
-        subjectId: image.subjectId,
-        imageRepository: image.imageRepository,
-        manifestDigest: image.manifestDigest,
-        producerStatementDigest: image.producerStatementDigest,
-        producerBundleDigest: image.producerBundleDigest,
-      })),
-    },
-  };
-  return schemas.parseDistributionImagesStatement(statement);
-}
-
-/**
- * The delivery-entitlement statement: "this customer may take THIS release,
- * in THIS mode, to THIS target, once, before it expires."
- *
- * The mode/targetRegistry pairing is enforced by the kernel schema's own
- * `superRefine` (mirror REQUIRES a target registry; shared and airgap FORBID
- * one) at the `parse` below — which happens here, in the builder, BEFORE any
- * signing. Restating the rule in this file would be a second copy of a closed
- * decision that already has an owner.
- */
-export function buildImageDeliveryEntitlementStatement({
-  distributionLock,
-  distributionId,
-  completenessStatementDigest,
-  customerId,
-  mode,
-  targetRegistry,
-  idempotencyKey,
-  runId,
-  runAttempt,
-  issuedAt,
-  expiresAt,
-  maxTtlSeconds,
-  schemas,
-}) {
-  if (!schemas?.parseImageDeliveryEntitlementStatement || typeof schemas.distributionLockDigest !== 'function') {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
-  assertCanonicalDistributionId(distributionId);
-  if (distributionLock?.distributionId !== distributionId) {
-    throw new Error(`delivery entitlement for ${String(customerId)} requires the distribution lock of ${distributionId}`);
-  }
-  const label = `delivery entitlement for ${String(customerId)}`;
-  if (!SHA256_DIGEST_PATTERN.test(completenessStatementDigest ?? '')) {
-    throw new Error(
-      `${label} requires the exact sha256 digest of the completeness statement`,
-    );
-  }
-  if (targetRegistry !== null && typeof targetRegistry !== 'string') {
-    throw new Error(
-      `${label} requires an explicit target registry or an explicit null`,
-    );
-  }
-  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0) {
-    throw new Error(`${label} requires a positive run attempt`);
-  }
-  assertIssuanceWindow({ issuedAt, expiresAt, maxTtlSeconds, label });
-
-  const statement = {
-    _type: 'https://in-toto.io/Statement/v1',
-    subject: [
-      {
-        name: `xema-distribution/${distributionId}`,
-        digest: {
-          sha256: completenessStatementDigest.slice('sha256:'.length),
-        },
-      },
-    ],
-    predicateType: schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
-    predicate: {
-      schemaVersion: 2,
-      customerId,
-      distributionId,
-      lockDigest: schemas.distributionLockDigest(distributionLock),
-      // Present-and-nullable: null states the lock carries no catalogue; the lock digest binds the lock either way.
-      catalogueDigest: distributionLock.catalogueDigest ?? null,
-      // The field the lock carries, never both: a catalogue-free lock's catalogueContentDigest.
-      ...(distributionLock.catalogueContentDigest === undefined ? {} : { catalogueContentDigest: distributionLock.catalogueContentDigest }),
-      distributionStatementDigest: completenessStatementDigest,
-      mode,
-      targetRegistry,
-      nonce: derivedNonce('xema.image-delivery-entitlement.nonce.v1', [
-        runId,
-        runAttempt,
-        customerId,
-        distributionId,
-        completenessStatementDigest,
-        idempotencyKey,
-      ]),
-      idempotencyKey,
-      issuedAt,
-      expiresAt,
-    },
-  };
-  return schemas.parseImageDeliveryEntitlementStatement(statement);
-}
-
-/**
- * `evidence-set.json` — the one document the offline verifier is handed.
- *
- * It can only be assembled once completeness EXISTS: the kernel schema requires
- * the `completeness` descriptor, so there is no such thing as a half-assembled
- * set on disk. That ordering is the design, not an accident of this function.
- */
-export function buildDistributionImageEvidenceSet({
-  distributionId,
-  producerEvidence,
-  completeness,
-  schemas,
-}) {
-  if (!schemas?.parseDistributionImageEvidenceSet) {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
-  assertCanonicalDistributionId(distributionId);
-  return schemas.parseDistributionImageEvidenceSet({
-    schemaVersion: 1,
-    distributionId,
-    producerEvidence,
-    completeness,
-  });
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The signing path shared by the completeness and entitlement producers
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * The pinned cosign version is read from the COMMITTED trust policy, never from
- * a literal in this file: the policy is what the offline verifier enforces, so
- * a producer signing with a different cosign than the verifier trusts must fail
- * at signing time, not at delivery.
- */
-export function assertPinnedCosignVersion(output, expectedVersion) {
-  if (!/^v\d+\.\d+\.\d+$/.test(expectedVersion ?? '')) {
-    throw new Error('the trust policy declares no exact cosign version');
-  }
-  const match = /\bGitVersion:\s*(v\d+\.\d+\.\d+)\b/.exec(String(output));
-  if (!match || match[1] !== expectedVersion) {
-    throw new Error(`cosign version does not match pinned ${expectedVersion}`);
-  }
-  return match[1];
-}
-
-/**
- * The trust policy the data root declares, held to the data root's pin of it.
- * Producers take their cosign version and TTL bounds from this policy, the
- * same one the verifier verifies under.
- */
-export function loadPinnedTrustPolicy({ dataRoot, schemas }) {
-  return loadPinnedDeclaredTrustPolicy({
-    dataRoot,
-    declaration: editionWorkspaceConfig().evidenceTrustPolicy,
-    schemas,
-  });
-}
-
-function assertSignableStatement({ statement, root, certificateWorkflowSha, predicateType }) {
-  assertAbsolutePath(root, 'signing root');
-  if (!COMMIT_PATTERN.test(certificateWorkflowSha ?? '')) {
-    throw new Error(
-      'signing requires the exact 40-hex commit of the signing workflow',
-    );
-  }
-  if (statement.predicateType !== predicateType) {
-    throw new Error(
-      `refusing to stage a ${statement.predicateType} statement as ${predicateType}`,
-    );
-  }
-}
-
-/**
- * Write the canonical bytes of ONE statement for signing and return its
- * signing plan entry. This library never signs: the caller runs
- * `cosign attest-blob` and hands the bundle to {@link acceptSignedEvidenceStatement}.
- */
-export function stageEvidenceStatement({
-  statement,
-  root,
-  statementPath,
-  bundlePath,
-  signer,
-  certificateWorkflowSha,
-  predicateType,
-}) {
-  assertSignableStatement({ statement, root, certificateWorkflowSha, predicateType });
-  const absoluteStatement = join(root, statementPath);
-  mkdirSync(dirname(absoluteStatement), { recursive: true, mode: 0o700 });
-  mkdirSync(dirname(join(root, bundlePath)), { recursive: true, mode: 0o700 });
-  writeFileSync(absoluteStatement, canonicalJsonBytes(statement), { flag: 'wx', mode: 0o600 });
-  return {
-    schemaVersion: 1,
-    root,
-    predicateType,
-    signer,
-    certificateWorkflowSha,
-    statements: [{ statementPath, bundlePath }],
-  };
-}
-
-/**
- * Accept the signed bundle of a staged statement into `sealingRoot`. `statement`
- * is re-derived by the caller; the staged bytes must be exactly its canonical
- * bytes and the bundle must carry exactly them. The canonical statement and
- * bundle are WRITTEN to `sealingRoot` (the staging is only read) and cosign
- * verifies the bundle there, against the declared signer at the exact workflow
- * commit.
- */
-export function acceptSignedEvidenceStatement({
-  statement,
-  root,
-  sealingRoot,
-  statementPath,
-  bundlePath,
-  signer,
-  certificateWorkflowSha,
-  predicateType,
-  runCosign,
-}) {
-  assertSignableStatement({ statement, root, certificateWorkflowSha, predicateType });
-  assertAbsolutePath(sealingRoot, 'sealing root');
-  if (typeof runCosign !== 'function') {
-    throw new Error('a cosign runner is required');
-  }
-  const statementBytes = canonicalJsonBytes(statement);
-  if (!readFileSync(join(root, statementPath)).equals(statementBytes)) {
-    throw new Error(
-      `staged statement ${statementPath} is not the statement these inputs build`,
-    );
-  }
-  const bundleBytes = canonicalSignedBundleBytes({ statementBytes, bundlePath: join(root, bundlePath) });
-  mkdirSync(dirname(join(sealingRoot, statementPath)), { recursive: true, mode: 0o755 });
-  mkdirSync(dirname(join(sealingRoot, bundlePath)), { recursive: true, mode: 0o755 });
-  writeFileSync(join(sealingRoot, statementPath), statementBytes, { flag: 'wx', mode: 0o644 });
-  writeFileSync(join(sealingRoot, bundlePath), bundleBytes, { flag: 'wx', mode: 0o644 });
-  // Verified where it is sealed: the bytes cosign accepts are the bytes kept.
-  runCosign(
-    cosignVerifyAttestationArgs({
-      bundlePath: join(sealingRoot, bundlePath),
-      signer,
-      certificateWorkflowSha,
-      predicateType,
-    }),
-  );
-  return {
-    statementPath,
-    statementDigest: sha256Digest(statementBytes),
-    bundlePath,
-    bundleDigest: sha256Digest(bundleBytes),
-    bundleMediaType: BUNDLE_MEDIA_TYPE,
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The CLI contract shared by this family's three entrypoints
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Strict `--flag value` parsing.
- *
- * One owner for the three entrypoints in this family so they cannot drift in
- * how they refuse an unknown flag, a repeated single-valued flag, or a missing
- * value. A typo'd flag that parses as "not provided" is exactly how a producer
- * silently signs with a default nobody chose.
- */
-export function parseEvidenceCliFlags(argv, { single = [], repeated = [] }) {
-  const singles = new Set(single);
-  const repeats = new Set(repeated);
-  const flags = new Map();
-  for (let index = 0; index < argv.length; index += 2) {
-    const flag = argv[index];
-    if (typeof flag !== 'string' || !flag.startsWith('--')) {
-      throw new Error(`unexpected argument "${String(flag)}"`);
-    }
-    const name = flag.slice(2);
-    const value = argv[index + 1];
-    if (value === undefined || value.startsWith('--')) {
-      throw new Error(`--${name} requires a value`);
-    }
-    if (repeats.has(name)) {
-      flags.set(name, [...(flags.get(name) ?? []), value]);
-      continue;
-    }
-    if (!singles.has(name)) {
-      throw new Error(`unknown option "--${name}"`);
-    }
-    if (flags.has(name)) {
-      throw new Error(`--${name} was given twice`);
-    }
-    flags.set(name, value);
-  }
-  return {
-    optional: (name) => flags.get(name),
-    many: (name) => flags.get(name) ?? [],
-    require(name) {
-      const value = flags.get(name);
-      if (value === undefined) {
-        throw new Error(`--${name} is required`);
-      }
-      return value;
-    },
-    requireMany(name) {
-      const values = flags.get(name);
-      if (!Array.isArray(values) || values.length === 0) {
-        throw new Error(`--${name} is required at least once`);
-      }
-      return values;
-    },
-  };
-}