@xemahq/xema 0.25.1 → 0.27.0

package/edition/image-evidence.mjs

@@ -0,0 +1,1225 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import {
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+import { TextDecoder } from 'node:util';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
+import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import {
+  compareStrings,
+  validateImmutableImageLock,
+} from './lib.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import {
+  assertPreparedExecutable,
+  exactExecutableOutput,
+  prepareDigestPinnedExecutable,
+} from './trusted-executable.mjs';
+
+const STRICT_UTF8 = new TextDecoder('utf-8', {
+  fatal: true,
+  ignoreBOM: true,
+});
+const MAX_CANONICAL_JSON_BYTES = 2 * 1024 * 1024;
+const MAX_STATEMENT_BYTES = 2 * 1024 * 1024;
+const MAX_SIGSTORE_BUNDLE_BYTES = 16 * 1024 * 1024;
+const MAX_TRUSTED_ROOT_BYTES = 8 * 1024 * 1024;
+const COSIGN_ENV = Object.freeze({
+  LANG: 'C',
+  LC_ALL: 'C',
+  PATH: '/usr/bin:/bin',
+  TZ: 'UTC',
+});
+
+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;
+}
+
+export function resolveContainedFile(root, candidate, label) {
+  if (
+    typeof candidate !== 'string' ||
+    candidate.length === 0 ||
+    isAbsolute(candidate)
+  ) {
+    throw new Error(`${label} must be a repository-relative path`);
+  }
+  const rootReal = realpathSync(root);
+  const path = resolve(rootReal, candidate);
+  const pathReal = realpathSync(path);
+  const rel = relative(rootReal, pathReal);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${label} escapes its evidence root`);
+  }
+  return pathReal;
+}
+
+function readExactDescriptorFile(root, path, expectedDigest, label, maxBytes) {
+  if (!SHA256_DIGEST_PATTERN.test(expectedDigest)) {
+    throw new Error(`${label} has an invalid expected sha256 digest`);
+  }
+  const { path: resolved, bytes } = readBoundedNoFollowFile(
+    root,
+    path,
+    `${label} path`,
+    maxBytes,
+  );
+  const actual = sha256Digest(bytes);
+  if (actual !== expectedDigest) {
+    throw new Error(
+      `${label} digest mismatch: expected ${expectedDigest}, got ${actual}`,
+    );
+  }
+  return { path: resolved, bytes };
+}
+
+export function readCanonicalJsonFromRoot(
+  root,
+  path,
+  label,
+  maxBytes = MAX_CANONICAL_JSON_BYTES,
+) {
+  return parseCanonicalJsonBytes(
+    readBoundedNoFollowFile(root, path, label, maxBytes).bytes,
+    label,
+  );
+}
+
+export function validatePinnedTrustedRoot(policyRoot, policy) {
+  const trustedRootFile = readBoundedNoFollowFile(
+    policyRoot,
+    policy.trustedRootPath,
+    'trusted root',
+    MAX_TRUSTED_ROOT_BYTES,
+  );
+  const { path: trustedRoot, bytes: rootBytes } = trustedRootFile;
+  if (sha256Digest(rootBytes) !== policy.trustedRootDigest) {
+    throw new Error('pinned Sigstore trusted-root digest mismatch');
+  }
+  const rootDocument = JSON.parse(
+    decodeExactUtf8(rootBytes, 'Sigstore trusted root'),
+  );
+  if (
+    rootDocument?.mediaType !==
+    'application/vnd.dev.sigstore.trustedroot+json;version=0.1'
+  ) {
+    throw new Error('Sigstore trusted root has an unsupported mediaType');
+  }
+  return { path: trustedRoot, bytes: rootBytes };
+}
+
+function assertTimeWindow({ issuedAt, expiresAt, now, maxTtlSeconds, label }) {
+  const issued = Date.parse(issuedAt);
+  const expires = Date.parse(expiresAt);
+  const instant = now instanceof Date ? now.getTime() : Date.parse(now);
+  if (![issued, expires, instant].every(Number.isFinite)) {
+    throw new Error(`${label} has an invalid time`);
+  }
+  if (issued > instant) {
+    throw new Error(`${label} is not yet valid`);
+  }
+  if (expires <= instant) {
+    throw new Error(`${label} is expired`);
+  }
+  if (expires <= issued) {
+    throw new Error(`${label} expiresAt must be after issuedAt`);
+  }
+  if (expires - issued > maxTtlSeconds * 1000) {
+    throw new Error(`${label} exceeds the trusted maximum TTL`);
+  }
+}
+
+export function sourceIdentity(subject) {
+  return `${subject.kind}\0${subject.id}`;
+}
+
+/** Root of the committed evidence tree, in every producing repository. */
+export const EVIDENCE_TREE_ROOT = 'evidence';
+
+/**
+ * The repository-relative directory a producer commits ONE subject digest's
+ * evidence bundle to. ONE owner: the producing workflows, the reuse check and
+ * (later) the delivery-side loader all read the name from here rather than
+ * interpolating a digest into a path themselves.
+ *
+ * `sha256-<hex>`, NOT `sha256:<hex>`. `:` is illegal in an NTFS path component,
+ * so a `sha256:`-named directory cannot be checked out on Windows at all — the
+ * clone fails, which would make the evidence plane silently undeliverable to
+ * any Windows operator. `sha256-<hex>` is cosign's own on-registry convention
+ * for exactly this reason (`sha256-<digest>.att`), so the plane gains no new
+ * vocabulary.
+ */
+export function evidenceDirectoryForDigest(manifestDigest) {
+  if (!/^sha256:[a-f0-9]{64}$/.test(manifestDigest ?? '')) {
+    throw new Error(
+      `evidence directory requires an exact sha256:<64-hex> manifest digest, got "${String(manifestDigest)}"`,
+    );
+  }
+  return `${EVIDENCE_TREE_ROOT}/${manifestDigest.replace(':', '-')}`;
+}
+
+function comparePlatform(left, right) {
+  return compareStrings(
+    `${left.os}/${left.architecture}/${left.variant ?? ''}`,
+    `${right.os}/${right.architecture}/${right.variant ?? ''}`,
+  );
+}
+
+function platformIdentity(platform) {
+  return `${platform.os}/${platform.architecture}/${platform.variant ?? ''}`;
+}
+
+function assertPlatforms(platforms, requiredPlatforms, label) {
+  if (platforms.length === 0) {
+    throw new Error(`${label} omits its complete platform set`);
+  }
+  const sorted = [...platforms].sort(comparePlatform);
+  if (canonicalJson(platforms) !== canonicalJson(sorted)) {
+    throw new Error(`${label} platforms are not canonically ordered`);
+  }
+  const identities = new Set();
+  const digests = new Set();
+  for (const platform of platforms) {
+    const identity = platformIdentity(platform);
+    if (identities.has(identity)) {
+      throw new Error(`${label} has duplicate platform "${identity}"`);
+    }
+    if (digests.has(platform.manifestDigest)) {
+      throw new Error(
+        `${label} reuses platform digest "${platform.manifestDigest}"`,
+      );
+    }
+    identities.add(identity);
+    digests.add(platform.manifestDigest);
+  }
+  // COVERAGE, not equality. `requiredPlatforms` is what the edition DEMANDS
+  // the published coordinate serve — `verify-image-platforms.mjs` reads it the
+  // same way at delivery (`missing = required.filter(not present)`), and this
+  // gate must not contradict it.
+  //
+  // Equality here was a latent, total break of the whole plane. The canonical
+  // `<imageRef>:<contentHash>` coordinate becomes a MULTI-ARCH INDEX once the
+  // arm64 lane merges, so a statement produced against the delivered digest
+  // necessarily proves BOTH platforms — while every non-appliance edition
+  // declares `[linux/amd64]` and both appliance editions declare
+  // `[linux/arm64]`. Under equality NO single statement could ever satisfy any
+  // of them, and the same subject would need contradictory evidence per
+  // edition. The producer signs ONE statement about ONE published artifact;
+  // the edition's requirement is a subset of what that artifact serves.
+  //
+  // Nothing is weakened: every entry in `platforms` was proven at assembly
+  // time through its own hash-verified image config
+  // (`resolvePublishedPlatforms`), the ordering/uniqueness invariants above
+  // still hold exactly, and a REQUIRED platform that the statement does not
+  // attest is still a hard failure — which is the property that matters.
+  const actualIdentities = new Set(platforms.map(platformIdentity));
+  const missing = [
+    ...new Set(requiredPlatforms.map(platformIdentity)),
+  ]
+    .filter((identity) => !actualIdentities.has(identity))
+    .sort();
+  if (missing.length > 0) {
+    throw new Error(
+      `${label} attests platforms ${[...actualIdentities].sort().join(', ')}, ` +
+        `which omit ${missing.join(', ')} required by images.lock.json`,
+    );
+  }
+}
+
+export function normalizedImageLockDigest(imageLock) {
+  return sha256Digest(canonicalJsonBytes(imageLock));
+}
+
+/**
+ * Membership in an OPTIONAL policy allowlist.
+ *
+ * `imageProducer.buildDefinitionDigests` / `.parametersDigests` are optional in
+ * `SigstoreIdentityPolicySchema`. Both are derived from the BuildKit SLSA v1
+ * `buildDefinition`, which carries the build's VCS revision and resolved
+ * dependencies — they change on essentially every build, so an armed policy
+ * cannot enumerate them ahead of time. OMITTED therefore means "this dimension
+ * is not pinned", and the build stays bound by builder id, build type, OCI
+ * media type and the Sigstore certificate identity / workflow binding.
+ *
+ * PRESENT means a hermetic deployment pinned an exact build, and membership is
+ * then STRICT — there is no "empty list means anything" escape: the kernel
+ * schema rejects an empty list, and one reaching here anyway admits nothing.
+ */
+function pinnedAllowlistAdmits(allowlist, value) {
+  return allowlist === undefined || allowlist.includes(value);
+}
+
+export function validateProducerStatementBinding({
+  statement,
+  subject,
+  sourceHashAlgorithm,
+  expectedContractAuthority,
+  now,
+  maxTtlSeconds,
+  producerPolicy,
+  repositoryPin,
+  consumedNonces = new Set(),
+}) {
+  if (
+    typeof sourceHashAlgorithm !== 'string' ||
+    sourceHashAlgorithm.length === 0
+  ) {
+    throw new Error(
+      "producer evidence validation requires the image lock's declared source hash algorithm",
+    );
+  }
+  const { predicate } = statement;
+  const label = `producer evidence for ${subject.kind}:${subject.id}`;
+  assertKernelContractAuthorityEqual(
+    predicate.contractAuthority,
+    expectedContractAuthority,
+    label,
+  );
+  assertTimeWindow({
+    issuedAt: predicate.producerRun.issuedAt,
+    expiresAt: predicate.producerRun.expiresAt,
+    now,
+    maxTtlSeconds,
+    label,
+  });
+  if (consumedNonces.has(predicate.producerRun.nonce)) {
+    throw new Error(`${label} replays an already-consumed nonce`);
+  }
+  if (
+    repositoryPin?.repo !== subject.repo ||
+    repositoryPin.sourceCommit !== subject.sourceCommit
+  ) {
+    throw new Error(`${label} does not match the committed repository pin`);
+  }
+  const expectedSource = {
+    kind: subject.kind,
+    id: subject.id,
+    repositoryUrl: repositoryPin.repositoryUrl,
+    repo: subject.repo,
+    path: subject.path,
+    sourceCommit: subject.sourceCommit,
+    sourceManifestHash: subject.sourceManifestHash,
+    // Read from the lock, never a literal: the lock's declared algorithm IS the
+    // coordinate's identity, and a hardcoded copy here would silently keep
+    // validating against a retired algorithm after the coordinate widened.
+    sourceHashAlgorithm,
+    sourceTreeHash: subject.contentHash,
+  };
+  if (canonicalJson(predicate.source) !== canonicalJson(expectedSource)) {
+    throw new Error(`${label} source identity does not match images.lock.json`);
+  }
+  if (
+    statement.subject[0].name !== subject.imageRef ||
+    `sha256:${statement.subject[0].digest.sha256}` !==
+      predicate.artifact.manifestDigest ||
+    predicate.artifact.imageRepository !== subject.imageRef
+  ) {
+    throw new Error(`${label} has an OCI subject/digest substitution`);
+  }
+  // THE SEALED ARTIFACT. `imageDigest` names the exact manifest that SHIPS
+  // (`seal-image-digests.mjs` writes it from the delivery-time platform
+  // verifier; the chart plane installs by it). The producer statement attests
+  // one manifest digest. If the two differ, the evidence proves an image OTHER
+  // than the one the lock installs — every check above still passes, because
+  // they bind the SOURCE coordinate and the statement's internal consistency,
+  // not the shipped bytes. That is the one substitution a self-consistent
+  // evidence set can carry, and it is the one a customer verifying its own
+  // edition most needs refused. A subject with NO `imageDigest` gives the
+  // statement nothing to be bound to, so it is refused, never read as "binds
+  // nothing": evidence is verified against a sealed lock only.
+  if (typeof subject.imageDigest !== 'string') {
+    throw new Error(
+      `${label}: images.lock.json seals no imageDigest for ${subject.kind}:${subject.id}, so the ` +
+        'attested manifest is bound to nothing. Run `xema edition seal` first.',
+    );
+  }
+  if (subject.imageDigest !== predicate.artifact.manifestDigest) {
+    throw new Error(
+      `${label} attests manifest ${predicate.artifact.manifestDigest} but ` +
+        `images.lock.json seals ${subject.imageDigest} for ${subject.imageRef}`,
+    );
+  }
+  assertPlatforms(predicate.build.platforms, subject.requiredPlatforms, label);
+  // The always-required anchors are checked unconditionally; the two per-build
+  // digests only narrow the identity when the policy actually pinned them (see
+  // `pinnedAllowlistAdmits`). Reading them unconditionally would throw a
+  // TypeError on `undefined.includes` for every ordinary policy, and simply
+  // ignoring a PRESENT list would be a gate that cannot fail.
+  const authorizedBuildIdentity =
+    Boolean(producerPolicy) &&
+    producerPolicy.builderIds.includes(predicate.build.builderId) &&
+    producerPolicy.buildTypes.includes(predicate.build.buildType) &&
+    producerPolicy.manifestMediaTypes.includes(
+      predicate.artifact.manifestMediaType,
+    ) &&
+    pinnedAllowlistAdmits(
+      producerPolicy.buildDefinitionDigests,
+      predicate.build.buildDefinitionDigest,
+    ) &&
+    pinnedAllowlistAdmits(
+      producerPolicy.parametersDigests,
+      predicate.build.parametersDigest,
+    );
+  if (!authorizedBuildIdentity) {
+    throw new Error(
+      `${label} build identity, definition, parameters, or OCI media type is not authorized`,
+    );
+  }
+  const protectedDigests = new Set([
+    predicate.artifact.manifestDigest,
+    predicate.artifact.sbom.digest,
+    predicate.artifact.provenance.digest,
+  ]);
+  if (protectedDigests.size !== 3) {
+    throw new Error(
+      `${label} substitutes an image, SBOM, or provenance digest`,
+    );
+  }
+  return statement;
+}
+
+/**
+ * The canonical order of a completeness `images[]` entry.
+ *
+ * Exported because the PRODUCER must emit exactly the order the verifier
+ * demands: `validateCompletenessStatementBinding` REFUSES a statement whose
+ * `images[]` is not in this order. Two copies of a comparator that a signature
+ * is bound to is a signed artifact waiting to become unverifiable.
+ */
+export function compareCompletenessImages(left, right) {
+  return (
+    compareStrings(left.subjectKind, right.subjectKind) ||
+    compareStrings(left.subjectId, right.subjectId)
+  );
+}
+
+function normalizedCompletenessImages(images) {
+  return [...images].sort(compareCompletenessImages);
+}
+
+export function validateCompletenessStatementBinding({
+  statement,
+  distributionLock,
+  imageLock,
+  verifiedProducers,
+  evidenceDescriptors,
+  now,
+  maxTtlSeconds,
+  expectedReleaseSourceCommit,
+  evidenceNonces = new Set(),
+}) {
+  const { predicate } = statement;
+  const label = `distribution completeness for ${imageLock.distributionId}`;
+  assertTimeWindow({
+    issuedAt: predicate.issuedAt,
+    expiresAt: predicate.expiresAt,
+    now,
+    maxTtlSeconds,
+    label,
+  });
+  if (evidenceNonces.has(predicate.nonce)) {
+    throw new Error(`${label} reuses a producer nonce`);
+  }
+  if (predicate.releaseSourceCommit !== expectedReleaseSourceCommit) {
+    throw new Error(
+      `${label} does not bind the exact editions release source commit`,
+    );
+  }
+  const lockDigest = normalizedImageLockDigest(imageLock);
+  if (
+    predicate.distributionId !== distributionLock.distributionId ||
+    predicate.distributionInputHash !== distributionLock.inputHash ||
+    predicate.normalizedImageLockDigest !== lockDigest ||
+    statement.subject[0].name !==
+      `xema-distribution/${distributionLock.distributionId}` ||
+    `sha256:${statement.subject[0].digest.sha256}` !== lockDigest
+  ) {
+    throw new Error(`${label} does not bind the selected distribution locks`);
+  }
+  const expectedImages = imageLock.subjects.map((subject) => {
+    const key = sourceIdentity(subject);
+    const producer = verifiedProducers.get(key);
+    const descriptor = evidenceDescriptors.get(key);
+    if (!producer || !descriptor) {
+      throw new Error(`${label} omits producer evidence for ${key}`);
+    }
+    return {
+      subjectKind: subject.kind,
+      subjectId: subject.id,
+      imageRepository: subject.imageRef,
+      manifestDigest: producer.predicate.artifact.manifestDigest,
+      producerStatementDigest: descriptor.statementDigest,
+      producerBundleDigest: descriptor.bundleDigest,
+    };
+  });
+  const actual = normalizedCompletenessImages(predicate.images);
+  const expected = normalizedCompletenessImages(expectedImages);
+  if (
+    canonicalJson(predicate.images) !== canonicalJson(actual) ||
+    canonicalJson(actual) !== canonicalJson(expected)
+  ) {
+    throw new Error(
+      `${label} image set is incomplete, contains extras, or is not canonically ordered`,
+    );
+  }
+  return statement;
+}
+
+export function validateEntitlementStatementBinding({
+  statement,
+  completenessStatementDigest,
+  customerId,
+  distributionId,
+  mode,
+  targetRegistry,
+  now,
+  maxTtlSeconds,
+  consumedNonces = new Set(),
+}) {
+  const { predicate } = statement;
+  const label = `delivery entitlement for ${customerId}`;
+  assertTimeWindow({
+    issuedAt: predicate.issuedAt,
+    expiresAt: predicate.expiresAt,
+    now,
+    maxTtlSeconds,
+    label,
+  });
+  // The predicate's `idempotencyKey` is the issuer's own request key. Nothing
+  // on the verifying side records keys across runs, so it is not checked here:
+  // replay is refused by the nonce, and by the replay state's release sequence.
+  if (consumedNonces.has(predicate.nonce)) {
+    throw new Error(`${label} is replayed`);
+  }
+  if (
+    predicate.customerId !== customerId ||
+    predicate.distributionId !== distributionId ||
+    predicate.distributionStatementDigest !== completenessStatementDigest ||
+    predicate.mode !== mode ||
+    predicate.targetRegistry !== targetRegistry
+  ) {
+    throw new Error(
+      `${label} does not authorize the requested customer, distribution, mode, and target`,
+    );
+  }
+  if (
+    statement.subject[0].name !== `xema-distribution/${distributionId}` ||
+    `sha256:${statement.subject[0].digest.sha256}` !==
+      completenessStatementDigest
+  ) {
+    throw new Error(`${label} substitutes the distribution release`);
+  }
+  return statement;
+}
+
+function assertEvidenceChannel(channel) {
+  if (typeof channel !== 'string' || channel === '') {
+    throw new Error('evidence verification requires the channel of the edition being verified');
+  }
+}
+
+/**
+ * The signers a policy authorizes for one predicate on ONE channel. Producer
+ * evidence is further bound to the exact image repository the subject's
+ * imageRef names (no prefix match).
+ */
+function policyCandidates(policy, predicateType, channel, imageRepository) {
+  return policy.policies.filter(
+    (candidate) =>
+      candidate.channel === channel &&
+      candidate.predicateTypes.includes(predicateType) &&
+      (imageRepository === undefined ||
+        candidate.imageRepositories?.includes(imageRepository) === true),
+  );
+}
+
+function cosignVersion(cosignBinary) {
+  const output = exactExecutableOutput(cosignBinary, ['version'], {
+    env: COSIGN_ENV,
+    timeout: 10_000,
+  });
+  const match = /\bGitVersion:\s*(v\d+\.\d+\.\d+)\b/.exec(output);
+  if (!match) {
+    throw new Error('cosign version output has no exact GitVersion');
+  }
+  return match[1];
+}
+
+export function prepareTrustedCosignBinary({ cosignBinary, policy }) {
+  return prepareDigestPinnedExecutable({
+    executablePath: cosignBinary,
+    trustedDigests: policy.trustedCosignBinaryDigests,
+    label: 'cosign',
+    verifyVersion(privateBinary) {
+      if (cosignVersion(privateBinary) !== policy.cosignVersion) {
+        throw new Error(
+          `cosign version does not match pinned ${policy.cosignVersion}`,
+        );
+      }
+    },
+  });
+}
+
+export function verifySigstoreEvidenceDescriptor({
+  evidenceRoot,
+  descriptor,
+  policy,
+  predicateType,
+  channel,
+  imageRepository,
+  expectedWorkflowSha,
+  parseStatement,
+  policyRoot = evidenceRoot,
+  trustedCosign,
+}) {
+  assertEvidenceChannel(channel);
+  const statementFile = readExactDescriptorFile(
+    evidenceRoot,
+    descriptor.statementPath,
+    descriptor.statementDigest,
+    'evidence statement',
+    MAX_STATEMENT_BYTES,
+  );
+  const bundleFile = readExactDescriptorFile(
+    evidenceRoot,
+    descriptor.bundlePath,
+    descriptor.bundleDigest,
+    'Sigstore bundle',
+    MAX_SIGSTORE_BUNDLE_BYTES,
+  );
+  const bundle = JSON.parse(
+    decodeExactUtf8(bundleFile.bytes, 'Sigstore bundle'),
+  );
+  if (bundle.mediaType !== descriptor.bundleMediaType) {
+    throw new Error('Sigstore bundle mediaType does not match its descriptor');
+  }
+  if (
+    bundle.messageSignature !== undefined ||
+    typeof bundle.dsseEnvelope !== 'object' ||
+    bundle.dsseEnvelope === null ||
+    bundle.dsseEnvelope.payloadType !== 'application/vnd.in-toto+json' ||
+    !Array.isArray(bundle.dsseEnvelope.signatures) ||
+    bundle.dsseEnvelope.signatures.length !== 1 ||
+    typeof bundle.dsseEnvelope.payload !== 'string' ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+      bundle.dsseEnvelope.payload,
+    )
+  ) {
+    throw new Error(
+      'Sigstore bundle must contain exactly one DSSE in-toto signature',
+    );
+  }
+  const dssePayload = Buffer.from(bundle.dsseEnvelope.payload, 'base64');
+  if (
+    dssePayload.toString('base64') !== bundle.dsseEnvelope.payload ||
+    !dssePayload.equals(statementFile.bytes)
+  ) {
+    throw new Error(
+      'Sigstore DSSE payload does not exactly match the canonical statement',
+    );
+  }
+  const statement = parseStatement(
+    parseCanonicalJsonBytes(statementFile.bytes, 'evidence statement'),
+  );
+  if (statement.predicateType !== predicateType) {
+    throw new Error('evidence statement predicateType is not authorized');
+  }
+  const candidates = policyCandidates(
+    policy,
+    predicateType,
+    channel,
+    imageRepository,
+  );
+  if (candidates.length === 0) {
+    throw new Error(
+      `offline trust policy authorizes no signer for ${predicateType} on channel "${channel}"` +
+        (imageRepository === undefined
+          ? ''
+          : ` and image repository "${imageRepository}"`),
+    );
+  }
+  const trustedCosignPath = assertPreparedExecutable(trustedCosign, 'cosign');
+  const trustedRoot = validatePinnedTrustedRoot(policyRoot, policy);
+  const verifiedWorkflowSha =
+    expectedWorkflowSha ??
+    statement.predicate?.producerRun?.producerWorkflowSha;
+  let verified = false;
+  let verifiedIdentityPolicy;
+  const verificationErrors = [];
+  for (const candidate of candidates) {
+    if (!verifiedWorkflowSha) {
+      throw new Error(
+        `policy "${candidate.policyId}" requires an exact workflow SHA`,
+      );
+    }
+    const verifiedOutputDirectory = mkdtempSync(
+      join(tmpdir(), 'xema-verified-dsse-'),
+    );
+    try {
+      const verifiedBundlePath = join(
+        verifiedOutputDirectory,
+        'bundle.sigstore.json',
+      );
+      const verifiedTrustedRootPath = join(
+        verifiedOutputDirectory,
+        'trusted-root.json',
+      );
+      writeFileSync(verifiedBundlePath, bundleFile.bytes, {
+        flag: 'wx',
+        mode: 0o600,
+      });
+      writeFileSync(verifiedTrustedRootPath, trustedRoot.bytes, {
+        flag: 'wx',
+        mode: 0o600,
+      });
+      // `--check-claims=false`: the attested claim is bound to the statement,
+      // not to a blob — the DSSE payload was already proven byte-identical to
+      // the canonical statement above, so cosign only has to prove the
+      // signature under the exact certificate constraints.
+      const args = [
+        'verify-blob-attestation',
+        '--check-claims=false',
+        '--offline',
+        '--new-bundle-format',
+        '--trusted-root',
+        verifiedTrustedRootPath,
+        '--bundle',
+        verifiedBundlePath,
+        '--certificate-identity',
+        candidate.certificateIdentity,
+        '--certificate-oidc-issuer',
+        candidate.oidcIssuer,
+        '--type',
+        predicateType,
+      ];
+      args.push(
+        '--certificate-github-workflow-repository',
+        candidate.githubWorkflow.repository,
+        '--certificate-github-workflow-ref',
+        candidate.githubWorkflow.ref,
+        '--certificate-github-workflow-sha',
+        verifiedWorkflowSha,
+      );
+      execFileSync(trustedCosignPath, args, {
+        env: COSIGN_ENV,
+        stdio: ['ignore', 'ignore', 'pipe'],
+        timeout: 60_000,
+      });
+      verified = true;
+      verifiedIdentityPolicy = candidate;
+      break;
+    } catch (error) {
+      verificationErrors.push(
+        `${candidate.policyId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    } finally {
+      rmSync(verifiedOutputDirectory, {
+        recursive: true,
+        force: true,
+      });
+    }
+  }
+  if (!verified) {
+    throw new Error(
+      'offline Sigstore verification failed for every trusted identity: ' +
+        verificationErrors.join('; '),
+    );
+  }
+  return {
+    statement,
+    statementPath: statementFile.path,
+    identityPolicy: verifiedIdentityPolicy,
+  };
+}
+
+export async function verifyDistributionImageEvidenceSet(options) {
+  assertEvidenceChannel(options.channel);
+  const trustedCosign = prepareTrustedCosignBinary({
+    cosignBinary: options.cosignBinary,
+    policy: options.policy,
+  });
+  try {
+    return await verifyDistributionImageEvidenceSetWithCosign({
+      ...options,
+      trustedCosign,
+    });
+  } finally {
+    trustedCosign.dispose();
+  }
+}
+
+async function verifyDistributionImageEvidenceSetWithCosign({
+  distributionId,
+  channel,
+  dataRoot,
+  // WHERE THE LOCKS ARE READ FROM: the editions root. The runtime index comes
+  // from `dataRoot`: the index is the data root's, the lock is the edition's.
+  editionsRoot,
+  evidenceRoot,
+  evidenceSet,
+  policy,
+  now,
+  expectedReleaseSourceCommit,
+  policyRoot = evidenceRoot,
+  trustedCosign,
+  schemas,
+}) {
+  // The authority the producer statements are held to is the one the data
+  // root's index states, which the entry has already held to the data root's
+  // evidence-trust pin (`readTrustAnchors`); the bundled kernel is held to that
+  // authority by the `--kernel` equality check at the entry, and the schemas that
+  // parse the index are the bundled ones, held to their edition protocol.
+  const {
+    distributionLock,
+    imageLock,
+    repositoryPins,
+    runtimeSourceIndex: { contractAuthority: expectedContractAuthority },
+  } = await loadValidatedLocks(distributionId, dataRoot, schemas, {
+    editionsRoot,
+  });
+  if (evidenceSet.distributionId !== distributionId) {
+    throw new Error(
+      `evidence set "${evidenceSet.distributionId}" does not match requested distribution "${distributionId}"`,
+    );
+  }
+
+  const evidenceDescriptors = new Map();
+  for (const producerEvidence of evidenceSet.producerEvidence) {
+    const key = `${producerEvidence.subjectKind}\0${producerEvidence.subjectId}`;
+    if (evidenceDescriptors.has(key)) {
+      throw new Error(`evidence set duplicates producer subject ${key}`);
+    }
+    evidenceDescriptors.set(key, producerEvidence.evidence);
+  }
+  if (evidenceDescriptors.size !== imageLock.subjects.length) {
+    throw new Error(
+      `evidence set has ${evidenceDescriptors.size} producer subjects; images.lock.json requires exactly ${imageLock.subjects.length}`,
+    );
+  }
+
+  const verifiedProducers = new Map();
+  const verifiedNonces = new Set();
+  for (const subject of imageLock.subjects) {
+    const key = sourceIdentity(subject);
+    const descriptor = evidenceDescriptors.get(key);
+    if (!descriptor) {
+      throw new Error(`evidence set omits producer subject ${key}`);
+    }
+    const repositoryPin = repositoryPins.get(subject.repo);
+    if (!repositoryPin) {
+      throw new Error(
+        `runtime subject "${subject.kind}:${subject.id}" has no committed repository pin`,
+      );
+    }
+    const { statement, identityPolicy } = verifySigstoreEvidenceDescriptor({
+      evidenceRoot,
+      descriptor,
+      policy,
+      predicateType: schemas.IMAGE_PRODUCER_PREDICATE_TYPE,
+      channel,
+      imageRepository: subject.imageRef,
+      parseStatement: schemas.parseImageProducerStatement,
+      policyRoot,
+      trustedCosign,
+    });
+    validateProducerStatementBinding({
+      statement,
+      subject,
+      sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
+      expectedContractAuthority,
+      now,
+      maxTtlSeconds: policy.maxProducerTtlSeconds,
+      producerPolicy: identityPolicy.imageProducer,
+      repositoryPin,
+      consumedNonces: verifiedNonces,
+    });
+    verifiedNonces.add(statement.predicate.producerRun.nonce);
+    verifiedProducers.set(key, statement);
+  }
+  for (const key of evidenceDescriptors.keys()) {
+    if (!verifiedProducers.has(key)) {
+      throw new Error(`evidence set contains unknown producer subject ${key}`);
+    }
+  }
+
+  const { statement: completenessStatement } = verifySigstoreEvidenceDescriptor(
+    {
+      evidenceRoot,
+      descriptor: evidenceSet.completeness,
+      policy,
+      predicateType: schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE,
+      channel,
+      expectedWorkflowSha: expectedReleaseSourceCommit,
+      parseStatement: schemas.parseDistributionImagesStatement,
+      policyRoot,
+      trustedCosign,
+    },
+  );
+  validateCompletenessStatementBinding({
+    statement: completenessStatement,
+    distributionLock,
+    imageLock,
+    verifiedProducers,
+    evidenceDescriptors,
+    now,
+    maxTtlSeconds: policy.maxCompletenessTtlSeconds,
+    expectedReleaseSourceCommit,
+    evidenceNonces: verifiedNonces,
+  });
+  verifiedNonces.add(completenessStatement.predicate.nonce);
+
+  return {
+    distributionLock,
+    imageLock,
+    producerStatements: verifiedProducers,
+    completenessStatement,
+    completenessStatementDigest: evidenceSet.completeness.statementDigest,
+    verifiedNonces,
+  };
+}
+
+export async function verifyImageDeliveryEntitlement(options) {
+  assertEvidenceChannel(options.channel);
+  const trustedCosign = prepareTrustedCosignBinary({
+    cosignBinary: options.cosignBinary,
+    policy: options.policy,
+  });
+  try {
+    return await verifyImageDeliveryEntitlementWithCosign({
+      ...options,
+      trustedCosign,
+    });
+  } finally {
+    trustedCosign.dispose();
+  }
+}
+
+async function verifyImageDeliveryEntitlementWithCosign({
+  evidenceRoot,
+  descriptor,
+  policy,
+  completenessStatementDigest,
+  customerId,
+  distributionId,
+  channel,
+  mode,
+  targetRegistry,
+  now,
+  expectedWorkflowSha,
+  consumedNonces = new Set(),
+  policyRoot = evidenceRoot,
+  trustedCosign,
+  schemas,
+}) {
+  const { statement } = verifySigstoreEvidenceDescriptor({
+    evidenceRoot,
+    descriptor,
+    policy,
+    predicateType: schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    channel,
+    expectedWorkflowSha,
+    parseStatement: schemas.parseImageDeliveryEntitlementStatement,
+    policyRoot,
+    trustedCosign,
+  });
+  validateEntitlementStatementBinding({
+    statement,
+    completenessStatementDigest,
+    customerId,
+    distributionId,
+    mode,
+    targetRegistry,
+    now,
+    maxTtlSeconds: policy.maxEntitlementTtlSeconds,
+    consumedNonces,
+  });
+  return statement;
+}
+
+/**
+ * Repository pins for the sources an EDITION declares itself.
+ *
+ * The runtime image source index pins the VENDOR fleet — every `repos/…` and
+ * `submodules/…` repository the vendor builds images from. A customer edition
+ * additionally draws biomes from sources declared in its own manifest
+ * (`sources[]`, `kind: git`), and the images built from those have a `repo`
+ * the index has never heard of and never will: `presenca-biomes`, not
+ * `repos/xema-base`. Without a pin for it every such subject is refused as
+ * "has no committed repository pin", so a customer could verify the vendor's
+ * images in its edition and never its own.
+ *
+ * The pin for an external source is two facts from two records, and each is
+ * the record that OWNS the fact:
+ *
+ *   * `repositoryUrl` — the edition manifest's declaration, by source name.
+ *     The manifest is read from the editions checkout and is HEAD-bound there
+ *     exactly like the locks (the verifier names it a required edition path).
+ *   * `sourceCommit` — the image lock's subjects. A declared `ref` may be a
+ *     branch; the lock records the exact commit the walk materialised, and it
+ *     is the authority for what was built. Every subject of one source must
+ *     agree on one commit, or the lock describes a walk that never happened.
+ *
+ * A declared source that ships no image yields no pin. A source whose name
+ * collides with an index pin is refused: the index is the vendor's record and
+ * an edition may not restate it. Non-git sources build no images from a
+ * repository and yield no pin; a subject naming one stays unpinned and is
+ * refused downstream, as before.
+ */
+export function externalSourceRepositoryPins({
+  distribution,
+  imageLock,
+  repositoryPins,
+}) {
+  const derived = new Map();
+  for (const source of distribution.sources ?? []) {
+    if (source.kind !== 'git') {continue;}
+    if (repositoryPins.has(source.name)) {
+      throw new Error(
+        `edition source "${source.name}" shadows a repository pin the runtime image source index already commits`,
+      );
+    }
+    const subjects = imageLock.subjects.filter(
+      (subject) => subject.repo === source.name,
+    );
+    if (subjects.length === 0) {continue;}
+    const commits = [...new Set(subjects.map((subject) => subject.sourceCommit))];
+    if (commits.length !== 1) {
+      throw new Error(
+        `edition source "${source.name}" is built at ${commits.length} different commits in images.lock.json (${commits.join(', ')}); one source resolves to one commit`,
+      );
+    }
+    derived.set(source.name, {
+      repo: source.name,
+      repositoryUrl: source.url,
+      sourceCommit: commits[0],
+    });
+  }
+  return derived;
+}
+
+/**
+ * The ONLY facts image evidence binds from `distribution.lock.json`, read
+ * TOLERANTLY and nothing else.
+ *
+ * WHY THIS IS NOT `schemas.parseDistributionLock`. The standalone verifier is a
+ * bundle of the kernel at its contract-authority commit, and that commit's lock
+ * schema is the strict WRITER schema of its day. Measured 2026-10-01 against
+ * the kernel at `24e9f12` (the authority every committed image lock names): a
+ * committed lock parses, and the SAME lock with one additive biome key
+ * (`provenance`) is refused — `[biomes.0] Unrecognized key: "provenance"`. So
+ * every additive section the resolver ever learns would have made every
+ * edition unverifiable until the verifier was rebuilt from a newer kernel, and
+ * rebuilding it meant re-pinning the authority, which rewrites
+ * `contractAuthority` in every `images.lock.json` and thereby invalidates every
+ * signed producer statement and completeness digest. An edition's image
+ * evidence would have been unsealed by a change that touched no image.
+ *
+ * What the evidence actually binds is two fields: the completeness predicate
+ * names `distributionId` and `distributionInputHash`
+ * (`validateCompletenessStatementBinding`), and every other caller reads the
+ * same two. The lock's biome roster is the PRODUCER's contract, graded by
+ * dist-check with the current kernel; the verifier never read it. So read
+ * exactly those, validate exactly those, and ignore every other key — the
+ * tolerant read-only posture `parseDistributionLockForReading` gives a
+ * runtime, without depending on which kernel the bundle was built from.
+ *
+ * `schemaVersion` must be 5, the one grammar there is (the kernel's
+ * `DISTRIBUTION_LOCK_SCHEMA_VERSIONS`): a pre-v5 lock is refused, with no
+ * compatibility path.
+ */
+export function readDistributionLockBinding(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('distribution.lock.json is not a JSON object');
+  }
+  const { schemaVersion, distributionId, inputHash } = raw;
+  if (schemaVersion !== 5) {
+    throw new Error(
+      `distribution.lock.json has schemaVersion ${String(schemaVersion)}; the only accepted grammar is 5 (regenerate the lock)`,
+    );
+  }
+  // The id is format-checked only. Which edition it must equal is decided by
+  // the bindings that USE it — the completeness predicate and the evidence set
+  // compare it to the image lock and the signed statement — exactly as before
+  // this reader existed; tightening that here would be a second, unasked rule.
+  assertCanonicalDistributionId(distributionId);
+  if (typeof inputHash !== 'string' || !/^[a-f0-9]{64}$/.test(inputHash)) {
+    throw new Error(
+      `distribution "${distributionId}" has invalid inputHash "${String(inputHash)}" — ` +
+        'expected 64 lowercase sha256 hex characters',
+    );
+  }
+  return Object.freeze({ schemaVersion, distributionId, inputHash });
+}
+
+/**
+ * Read and validate an edition's two locks plus the runtime image source index
+ * they must agree with.
+ *
+ * `dataRoot` holds the runtime image source index, read from it always.
+ * `editionsRoot` is where `<id>/distribution.lock.json`,
+ * `<id>/images.lock.json` and `<id>/xema-distribution.json` are read from. The
+ * manifest extends the repository pins with the edition's own declared sources
+ * ({@link externalSourceRepositoryPins}); the verifier grades the editions
+ * checkout so all three files are HEAD-bound.
+ */
+export async function loadValidatedLocks(
+  distributionId,
+  dataRoot,
+  schemas,
+  { editionsRoot },
+) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  const distributionLock = readDistributionLockBinding(
+    JSON.parse(
+      readFileSync(
+        join(editionsRoot, distributionId, 'distribution.lock.json'),
+        'utf8',
+      ),
+    ),
+  );
+  const imageLock = validateImmutableImageLock(
+    schemas.parseImageLock(
+      JSON.parse(
+        readFileSync(
+          join(editionsRoot, distributionId, 'images.lock.json'),
+          'utf8',
+        ),
+      ),
+    ),
+    schemas,
+  );
+  const runtimeSourceIndex = schemas.parseRuntimeImageSourceIndex(
+    JSON.parse(
+      readFileSync(
+        join(dataRoot, 'runtime-image-source-index.json'),
+        'utf8',
+      ),
+    ),
+  );
+  if (
+    canonicalJson(imageLock.contractAuthority) !==
+    canonicalJson(runtimeSourceIndex.contractAuthority)
+  ) {
+    throw new Error(
+      'images.lock.json kernel contract authority does not exactly match runtime-image-source-index.json',
+    );
+  }
+  const repositoryPins = new Map(
+    runtimeSourceIndex.repositoryPins.map((repository) => [
+      repository.repo,
+      repository,
+    ]),
+  );
+  const distribution = schemas.parseDistribution(
+    JSON.parse(
+      readFileSync(
+        join(editionsRoot, distributionId, 'xema-distribution.json'),
+        'utf8',
+      ),
+    ),
+  );
+  if (distribution.id !== distributionId) {
+    throw new Error(
+      `edition manifest at ${editionsRoot} declares id "${distribution.id}", not "${distributionId}"`,
+    );
+  }
+  for (const [repo, pin] of externalSourceRepositoryPins({
+    distribution,
+    imageLock,
+    repositoryPins,
+  })) {
+    repositoryPins.set(repo, pin);
+  }
+  return {
+    schemas,
+    distributionLock,
+    imageLock,
+    runtimeSourceIndex,
+    repositoryPins,
+  };
+}