@xemahq/xema 0.25.1 → 0.27.0

package/edition/distribution-evidence-set.mjs

@@ -0,0 +1,987 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// 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 { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { compareStrings } from './lib.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import {
+  createRegistryClientResolver,
+  resolveImageSourceEvidenceReferrer,
+} 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';
+
+/**
+ * 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.
+ */
+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;
+    }
+    const subjectKey = sourceIdentity({
+      kind: entry.subjectKind,
+      id: 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,
+}) {
+  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 } =
+    await loadValidatedLocks(distributionId, dataRoot, schemas, { editionsRoot });
+  assertKernelContractAuthorityEqual(
+    runtimeSourceIndex.contractAuthority,
+    expectedContractAuthority,
+    'runtime-image-source-index.json',
+  );
+  const clientFor = createRegistryClientResolver({
+    dataRoot,
+    factory: registryClientFactory,
+  });
+
+  const producers = [];
+  for (const subject of imageLock.subjects) {
+    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 ociEvidence = await resolveImageSourceEvidenceReferrer({
+      client,
+      imageRepository: subject.imageRef,
+      subjectDigest: image.digest,
+      schemas,
+    });
+    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 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,
+  releaseSequence,
+  releaseSourceCommit,
+  runId,
+  runAttempt,
+  issuedAt,
+  expiresAt,
+  maxTtlSeconds,
+  schemas,
+}) {
+  if (!schemas?.parseDistributionImagesStatement) {
+    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) => sourceIdentity(subject))
+    .sort(compareStrings);
+  const actualIdentities = images
+    .map((image) =>
+      sourceIdentity({ kind: image.subjectKind, id: image.subjectId }),
+    )
+    .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: 1,
+      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({
+  distributionId,
+  completenessStatementDigest,
+  customerId,
+  mode,
+  targetRegistry,
+  idempotencyKey,
+  runId,
+  runAttempt,
+  issuedAt,
+  expiresAt,
+  maxTtlSeconds,
+  schemas,
+}) {
+  if (!schemas?.parseImageDeliveryEntitlementStatement) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  assertCanonicalDistributionId(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: 1,
+      customerId,
+      distributionId,
+      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;
+    },
+  };
+}