@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/third-party-bundle-registry.mjs

@@ -0,0 +1,349 @@
+// The registry side of the third-party writer (XEMA-1611 design section 3 (a)): the biome bundle, by digest, and its
+// SLSA provenance in the CLASSIC cosign format (`sha256-<hex>.sig` / `.att` tags). The provenance statement is the
+// payload `cosign verify-attestation` verified; the certificate and tlog entry beside it are read from the `.att` tag
+// and verified offline by cosign (`third-party-source-evidence.mjs`) before anything is committed.
+
+import { execFileSync } from 'node:child_process';
+import { X509Certificate } from 'node:crypto';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { certificateConstraintArgs, certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
+import { COSIGN_ENV, classicCosignTrustMaterial, decodeExactUtf8, sha256Digest, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import {
+  PROVENANCE_BUNDLE_MEDIA_TYPE,
+  SLSA_PROVENANCE_V1,
+  decodeJsonStatement,
+  digestOfOciRef,
+  parseProvenanceStatement,
+} from './third-party-source-evidence.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+
+const BIOME_MANIFEST_FILE = 'xema-biome.json';
+const BIOME_GENERATED_INDEX_FILE = 'xema-biome.index.json';
+const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';
+const MAX_BIOME_MANIFEST_BYTES = 4 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
+const REGISTRY_COSIGN_TIMEOUT_MS = 120_000;
+/** What `cosign verify-attestation --type` calls the SLSA v1 provenance predicate. */
+const COSIGN_SLSA_PROVENANCE_ALIAS = 'slsaprovenance1';
+/** The classic cosign attestation tag layout (`cosign attest`): one DSSE envelope per layer, its material in annotations. */
+const CLASSIC_DSSE_LAYER_MEDIA_TYPE = 'application/vnd.dsse.envelope.v1+json';
+const CLASSIC_CERTIFICATE_ANNOTATION = 'dev.sigstore.cosign/certificate';
+const CLASSIC_REKOR_BUNDLE_ANNOTATION = 'dev.sigstore.cosign/bundle';
+
+const repositoryOf = (ociRef) => splitImageRef(ociRef.slice(0, ociRef.indexOf('@')));
+
+/**
+ * The biome bundle manifest JSON (`xema-biome.json`) of an OCI artifact, fetched by digest.
+ *
+ * @returns {Promise<{manifest: object, bytes: Buffer}>}
+ */
+export async function fetchBundleManifest({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_MANIFEST_FILE });
+  return { manifest: decodeJsonStatement(bytes, `${ociRef} ${BIOME_MANIFEST_FILE}`), bytes };
+}
+
+/**
+ * The committed generated index (`xema-biome.index.json`) of an OCI biome bundle, fetched by digest: the authority for
+ * the biomes the bundle requires, read from the same bundle bytes as its manifest, so it cannot describe another revision.
+ */
+export async function fetchBundleGeneratedIndex({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_GENERATED_INDEX_FILE });
+  return decodeJsonStatement(bytes, `${ociRef} ${BIOME_GENERATED_INDEX_FILE}`);
+}
+
+/** The one layer of the bundle manifest at `ociRef` (by digest) annotated with `title`. */
+async function fetchTitledLayer({ clientFor, ociRef, title }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const { document } = await client.getManifestByDigest(repository, digestOfOciRef(ociRef));
+  const layers = (document.layers ?? []).filter((layer) => layer.annotations?.[OCI_TITLE_ANNOTATION] === title);
+  if (layers.length !== 1) {
+    throw new Error(`${ociRef} has ${layers.length} layers titled ${title}; a biome bundle has exactly one`);
+  }
+  const bytes = await client.getBlob(repository, layers[0].digest, MAX_BIOME_MANIFEST_BYTES);
+  if (sha256Digest(bytes) !== layers[0].digest) {
+    throw new Error(`${ociRef} layer titled ${title} does not match its descriptor`);
+  }
+  return bytes;
+}
+
+/**
+ * The image names a biome manifest ships: its service and worker components with an `oci-image` artifact, named the way
+ * the index builder names them (a service by `protocol.serviceName`, a worker by its component `key`).
+ */
+export function bundleImageNames(manifest) {
+  const components = Array.isArray(manifest?.xema?.components) ? manifest.xema.components : [];
+  return new Set(
+    components
+      .filter((component) => (component?.kind === 'service' || component?.kind === 'worker') && component.artifact?.kind === 'oci-image')
+      .map((component) => (component.kind === 'service' ? component.protocol?.serviceName : component.key)),
+  );
+}
+
+const IN_TOTO_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+const STRICT_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+
+/**
+ * The SLSA provenance of the bundle, taken from what `cosign verify-attestation` VERIFIED: cosign prints each verified
+ * DSSE envelope on stdout, one JSON object per line. Exactly one envelope is required; it must be an in-toto DSSE
+ * envelope with one signature, its payload an in-toto statement of `https://slsa.dev/provenance/v1` over exactly one
+ * subject, the bundle digest. Nothing is read from the registry here: the statement is the payload cosign verified.
+ *
+ * @returns {{statementBytes: Buffer, envelope: {payloadType: string, payload: string, signatures: object[]}}}
+ */
+export function verifiedProvenanceOf(output, ociRef) {
+  const lines = String(output).split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length !== 1) {
+    throw new Error(
+      `cosign verify-attestation of ${ociRef} printed ${lines.length} verified attestation envelopes; exactly one SLSA provenance (${SLSA_PROVENANCE_V1}) attestation is required, so the evidence is unambiguous`,
+    );
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(lines[0]);
+  } catch {
+    throw new Error(`cosign verify-attestation of ${ociRef} printed a verified attestation that is not a JSON DSSE envelope`);
+  }
+  if (
+    envelope === null ||
+    typeof envelope !== 'object' ||
+    envelope.payloadType !== IN_TOTO_PAYLOAD_TYPE ||
+    typeof envelope.payload !== 'string' ||
+    !STRICT_BASE64.test(envelope.payload) ||
+    !Array.isArray(envelope.signatures) ||
+    envelope.signatures.length !== 1 ||
+    typeof envelope.signatures[0]?.sig !== 'string'
+  ) {
+    throw new Error(`cosign verify-attestation of ${ociRef} printed a verified attestation that is not an in-toto DSSE envelope with exactly one signature`);
+  }
+  const statementBytes = Buffer.from(envelope.payload, 'base64');
+  let statement;
+  try {
+    statement = parseProvenanceStatement(decodeJsonStatement(statementBytes, `${ociRef} verified attestation payload`));
+  } catch (error) {
+    throw new Error(`cosign verify-attestation of ${ociRef}: ${error.message}`);
+  }
+  const attested = `sha256:${statement.subject[0].digest.sha256}`;
+  if (attested !== digestOfOciRef(ociRef)) {
+    throw new Error(`the verified SLSA provenance of ${ociRef} attests ${attested}, not the bundle digest ${digestOfOciRef(ociRef)}`);
+  }
+  return { statementBytes, envelope: { payloadType: envelope.payloadType, payload: envelope.payload, signatures: envelope.signatures } };
+}
+
+const sameSignatures = (left, right) =>
+  Array.isArray(left) && left.length === right.length && left.every((signature, index) => signature?.sig === right[index].sig);
+
+/**
+ * The committed, offline-verifiable form of the VERIFIED provenance envelope: a Sigstore bundle v0.1
+ * (`PROVENANCE_BUNDLE_MEDIA_TYPE`) built from the classic `sha256-<hex>.att` layer that carries exactly that envelope,
+ * its Fulcio certificate (`dev.sigstore.cosign/certificate`) and its Rekor v1 entry with the signed entry timestamp
+ * (`dev.sigstore.cosign/bundle`). v0.1 because a classic entry carries an inclusion promise, not an inclusion proof.
+ * The envelope is cosign's verified one, never the registry's; the certificate and the tlog entry are unauthenticated
+ * here and are proven by the offline `verify-blob-attestation` the writer runs on the staged evidence before commit.
+ */
+export async function fetchClassicProvenanceBundle({ clientFor, ociRef, envelope }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const tag = `${digestOfOciRef(ociRef).replace(':', '-')}.att`;
+  const { document } = await client.getManifestByTag(repository, tag);
+  const matching = [];
+  for (const layer of document.layers ?? []) {
+    if (layer.mediaType !== CLASSIC_DSSE_LAYER_MEDIA_TYPE) {continue;}
+    const bytes = await client.getBlob(repository, layer.digest, MAX_BUNDLE_BYTES);
+    if (sha256Digest(bytes) !== layer.digest) {
+      throw new Error(`${ociRef} attestation layer ${layer.digest} does not match its descriptor`);
+    }
+    let candidate;
+    try {
+      candidate = JSON.parse(decodeExactUtf8(bytes, 'classic attestation layer'));
+    } catch {
+      continue; // not a DSSE envelope: never the verified one
+    }
+    if (candidate?.payload === envelope.payload && sameSignatures(candidate.signatures, envelope.signatures)) {
+      matching.push(layer);
+    }
+  }
+  if (matching.length !== 1) {
+    throw new Error(`${ociRef} tag ${tag} carries ${matching.length} attestation layers holding the verified provenance envelope; exactly one is required`);
+  }
+  const annotations = matching[0].annotations ?? {};
+  const certificatePem = annotations[CLASSIC_CERTIFICATE_ANNOTATION];
+  const rekorBundleText = annotations[CLASSIC_REKOR_BUNDLE_ANNOTATION];
+  if (typeof certificatePem !== 'string') {
+    throw new Error(`${ociRef} attestation layer ${matching[0].digest} carries no Fulcio certificate (${CLASSIC_CERTIFICATE_ANNOTATION})`);
+  }
+  if (typeof rekorBundleText !== 'string') {
+    throw new Error(`${ociRef} attestation layer ${matching[0].digest} carries no transparency log entry (${CLASSIC_REKOR_BUNDLE_ANNOTATION})`);
+  }
+  let certificateDer;
+  try {
+    certificateDer = new X509Certificate(certificatePem).raw;
+  } catch (error) {
+    throw new Error(`${ociRef} attestation layer ${matching[0].digest} certificate is not a PEM X.509 certificate: ${error.message}`);
+  }
+  let rekor;
+  let body;
+  try {
+    rekor = JSON.parse(rekorBundleText);
+    body = JSON.parse(Buffer.from(rekor.Payload.body, 'base64').toString('utf8'));
+  } catch {
+    throw new Error(`${ociRef} attestation layer ${matching[0].digest} transparency log entry is not a cosign Rekor bundle`);
+  }
+  const { Payload: payload, SignedEntryTimestamp: signedEntryTimestamp } = rekor;
+  if (
+    typeof signedEntryTimestamp !== 'string' ||
+    !Number.isSafeInteger(payload.logIndex) ||
+    !Number.isSafeInteger(payload.integratedTime) ||
+    typeof payload.logID !== 'string' ||
+    !/^[0-9a-f]{64}$/u.test(payload.logID) ||
+    typeof body?.kind !== 'string' ||
+    typeof body?.apiVersion !== 'string'
+  ) {
+    throw new Error(`${ociRef} attestation layer ${matching[0].digest} transparency log entry is not a cosign Rekor bundle`);
+  }
+  const bundle = {
+    mediaType: PROVENANCE_BUNDLE_MEDIA_TYPE,
+    verificationMaterial: {
+      x509CertificateChain: { certificates: [{ rawBytes: certificateDer.toString('base64') }] },
+      tlogEntries: [
+        {
+          logIndex: String(payload.logIndex),
+          logId: { keyId: Buffer.from(payload.logID, 'hex').toString('base64') },
+          kindVersion: { kind: body.kind, version: body.apiVersion },
+          integratedTime: String(payload.integratedTime),
+          inclusionPromise: { signedEntryTimestamp },
+          canonicalizedBody: payload.body,
+        },
+      ],
+    },
+    dsseEnvelope: envelope,
+  };
+  return Buffer.from(JSON.stringify(bundle), 'utf8');
+}
+
+/**
+ * The `<repository>@sha256:<hex>` a bundle reference names: a digest reference as it is, a tag reference resolved at
+ * the registry (the manifest the tag serves, its bytes verified against the digest the registry described).
+ */
+export async function bundleDigestRef({ clientFor, ociRef }) {
+  if (ociRef.includes('@')) {return ociRef;}
+  const colon = ociRef.lastIndexOf(':');
+  if (colon <= ociRef.lastIndexOf('/')) {
+    throw new Error(`bundle reference ${JSON.stringify(ociRef)} names neither a tag nor a digest`);
+  }
+  const name = ociRef.slice(0, colon);
+  const { authority, repository } = splitImageRef(name);
+  const { digest } = await clientFor(authority).getManifestByTag(repository, ociRef.slice(colon + 1));
+  return `${name}@${digest}`;
+}
+
+const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
+
+/**
+ * The cosign run of a registry verification: the trusted binary under a CLEAN environment (`COSIGN_ENV` and the
+ * operator's registry credential, HOME / DOCKER_CONFIG; no `SIGSTORE_*`, `COSIGN_*` or `TUF_*` of the operator is ever
+ * inherited). `run` takes `--offline --trusted-root <pinned>`; `runClassic` instead pins cosign's classic trust inputs
+ * to the keys derived from the same pinned root (`classicCosignTrustMaterial`), in a private directory removed after the
+ * run, with an empty private TUF_ROOT so no live TUF material is ever read.
+ */
+function registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env }) {
+  const root = validatePinnedTrustedRoot(policyRoot, policy);
+  const environment = {
+    ...COSIGN_ENV,
+    ...(env.HOME === undefined ? {} : { HOME: env.HOME }),
+    ...(env.DOCKER_CONFIG === undefined ? {} : { DOCKER_CONFIG: env.DOCKER_CONFIG }),
+  };
+  const exec = (command, args, runEnv) => {
+    try {
+      return execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], {
+        env: runEnv,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: REGISTRY_COSIGN_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
+    }
+  };
+  return {
+    trustArgs: ['--offline', '--trusted-root', root.path],
+    run: (command, args) => exec(command, args, environment),
+    runClassic(command, args) {
+      const material = classicCosignTrustMaterial(root.bytes);
+      const dir = mkdtempSync(join(tmpdir(), 'xema-cosign-trust-'));
+      try {
+        const file = (name, content) => {
+          const path = join(dir, name);
+          writeFileSync(path, content, { mode: 0o600, flag: 'wx' });
+          return path;
+        };
+        const tufRoot = join(dir, 'tuf');
+        mkdirSync(tufRoot, { mode: 0o700 });
+        return exec(command, ['--offline', ...args], {
+          ...environment,
+          SIGSTORE_ROOT_FILE: file('fulcio.pem', material.fulcioPem),
+          SIGSTORE_REKOR_PUBLIC_KEY: file('rekor.pub', material.rekorPem),
+          SIGSTORE_CT_LOG_PUBLIC_KEY_FILE: file('ctlog.pub', material.ctLogPem),
+          TUF_ROOT: tufRoot,
+        });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+/**
+ * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
+ * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
+ * commit, and the trusted cosign binary, both `--offline`: the tlog entry carried with the signature is verified, the
+ * tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ *
+ * Publishers write the CLASSIC cosign format (`sha256-<d>.sig` / `.att` tags; `cosign sign` / `cosign attest`), not
+ * referrer Sigstore bundles. `verify` takes the pinned trusted root as is (`--trusted-root`, classic or bundle form).
+ * cosign 2.6 `verify-attestation` takes `--trusted-root` only with `--new-bundle-format`, which finds no classic
+ * attestation, so it runs without either, against the Fulcio, Rekor v1 and CT keys derived from the SAME pinned root
+ * and passed in cosign's classic trust variables (`registryCosign().runClassic`). A publisher switching to referrer
+ * bundles is refused loudly (cosign then requires a trusted root), never verified against anything unpinned.
+ *
+ * @returns {{provenance: {statementBytes: Buffer, envelope: object}}} the provenance cosign verified
+ *   (`verifiedProvenanceOf`): signature first, then the attestation, then the statement from cosign's own output.
+ */
+export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const claims = certificateConstraintArgs(row, workflowSha);
+  cosign.run('verify', [...cosign.trustArgs, ...claims, ociRef]);
+  const output = cosign.runClassic('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...claims, ociRef]);
+  return { provenance: verifiedProvenanceOf(output, ociRef) };
+}
+
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/u;
+
+/**
+ * The commit the row's workflow signed the bundle artifact at, as cosign states it: `cosign verify` under the row's
+ * identity, issuer, workflow repository and ref (no commit: it is what is asked), and the `githubWorkflowSha` claim of
+ * every signature cosign verified. Exactly one commit is required; none, or two, is refused. The caller then holds the
+ * signature AND the provenance to that commit with `verifyBundleOnRegistry`.
+ */
+export function verifiedBundleSignerCommit({ trustedCosign, policy, policyRoot, row, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const output = cosign.run('verify', [...cosign.trustArgs, ...certificateIdentityArgs(row), '--output', 'json', ociRef]);
+  let verified;
+  try {
+    verified = JSON.parse(output);
+  } catch {
+    throw new Error(`cosign verify of ${ociRef} under row "${row.policyId}" printed no JSON list of verified signatures`);
+  }
+  const commits = [...new Set((Array.isArray(verified) ? verified : []).map((signature) => signature?.optional?.githubWorkflowSha))];
+  if (commits.length !== 1 || !WORKFLOW_SHA.test(String(commits[0]))) {
+    throw new Error(
+      `${ociRef} carries signatures by row "${row.policyId}" (${row.certificateIdentity}) stating ${commits.length} workflow commits ` +
+        `(${commits.map(String).join(', ')}); exactly one 40-hex commit is required`,
+    );
+  }
+  return commits[0];
+}

package/edition/third-party-certificate-extensions.mjs

@@ -0,0 +1,58 @@
+// (d) of the third-party checks: the Fulcio extensions of a bundle's leaf certificate, held to a source pin. Its own module
+// (it imports no evidence module) because admission in `image-evidence.mjs` and the pin verifier both use it.
+//
+// The runner rule (XEMA-2661) is ONE rule: the certificate's Runner Environment must equal the runner environment the pin
+// declares, and a pin that declares none declares `github-hosted`. So zero configuration refuses every self-hosted
+// signature, and a declaration only ever names the one runner kind its signer uses.
+//
+// Fulcio has no runner-label extension: a certificate cannot say WHICH self-hosted runner signed, and no code here reads
+// the workflow's `runs-on`. What this module proves for a self-hosted pin is only that the declared workflow (the trust
+// row's exact `<repository>/<workflow>@refs/heads/main` identity, at the pinned commit) ran AS the top-level workflow:
+// Build Signer URI (.9) and Build Config URI (.18) both equal that identity, so a reusable signing workflow called from
+// another workflow, which could hand it its `runs-on`, is refused. That the workflow runs on a dedicated signing runner
+// (`runs-on: signing`) is a HUMAN check: whoever writes the pin with `--runner-environment self-hosted` must read that
+// workflow at the pinned commit and verify it before running `repin-evidence-trust`.
+
+import {
+  FulcioBuildOid,
+  FulcioExtensionOid,
+  RunnerEnvironment,
+  readFulcioBuildIdentity,
+  readFulcioExtensionsFromBundle,
+} from './fulcio-certificate-extensions.mjs';
+
+/** The runner environment a pin holds its certificates to: its declared `runnerEnvironment`, else `github-hosted`. */
+export const declaredRunnerEnvironment = (source) => source.runnerEnvironment ?? RunnerEnvironment.GithubHosted;
+
+/**
+ * The leaf certificate of a parsed Sigstore `bundle` states the pinned repository id, owner id and the runner environment
+ * the pin declares (`declaredRunnerEnvironment`). When that is not `github-hosted`, its Build Signer URI and Build Config
+ * URI must both be `signerIdentity`, the exact certificate identity of the trust row the evidence verified under.
+ */
+export function assertCertificateExtensions({ bundle, source, signerIdentity, label }) {
+  if (typeof signerIdentity !== 'string' || signerIdentity.length === 0) {
+    throw new Error(`${label}: no signer identity to hold the certificate to`);
+  }
+  const read = readFulcioExtensionsFromBundle(bundle);
+  const runnerEnvironment = declaredRunnerEnvironment(source);
+  const runnerPinned = source.runnerEnvironment === undefined ? `runnerEnvironment undeclared, so ${RunnerEnvironment.GithubHosted}` : 'runnerEnvironment';
+  const expectations = [
+    [FulcioExtensionOid.SourceRepositoryIdentifier, 'Source Repository Identifier', read.sourceRepositoryIdentifier, source.repositoryId, 'repositoryId'],
+    [FulcioExtensionOid.SourceRepositoryOwnerIdentifier, 'Source Repository Owner Identifier', read.sourceRepositoryOwnerIdentifier, source.repositoryOwnerId, 'repositoryOwnerId'],
+    [FulcioExtensionOid.RunnerEnvironment, 'Runner Environment', read.runnerEnvironment, runnerEnvironment, runnerPinned],
+  ];
+  if (runnerEnvironment !== RunnerEnvironment.GithubHosted) {
+    const build = readFulcioBuildIdentity(bundle);
+    expectations.push(
+      [FulcioBuildOid.BuildSignerUri, 'Build Signer URI', build.buildSignerUri, signerIdentity, 'the declared signer workflow'],
+      [FulcioBuildOid.BuildConfigUri, 'Build Config URI', build.buildConfigUri, signerIdentity, 'the declared signer workflow, as the top-level workflow'],
+    );
+  }
+  for (const [oid, name, actual, expected, pinned] of expectations) {
+    if (actual !== expected) {
+      throw new Error(
+        `${label} certificate ${name} (${oid}) is ${JSON.stringify(actual)}, but the pin requires ${JSON.stringify(expected)} (${pinned})`,
+      );
+    }
+  }
+}

package/edition/third-party-image-pins.mjs

@@ -0,0 +1,41 @@
+// The pinned images of the third-party subjects of an images lock (XEMA-1611 design sections 3 and 4).
+//
+// A third-party subject's `contentHash` is the PUBLISHER'S `sourceTreeHash` (publisher-attested): it is never a registry
+// tag. Every seal, coverage and evidence-set path that serves such a subject goes to the pin instead: the image is read
+// BY the pin's `manifestDigest` and its evidence is the committed evidence the pin's `statementDigest` and `bundleDigest`
+// bind. This module is the one place a subject is joined to its pinned image.
+
+/** The `kind:id` key of an image subject, as the seal reports and the digest plans spell it. */
+export const imageSubjectKey = (subject) => `${subject.kind}:${subject.id}`;
+
+/**
+ * The pinned image of every third-party subject of `subjects`, by `kind:id`. A subject is third-party when its `repo` is a
+ * pinned third-party repository. Refuses a third-party subject the pin pins no image for, and one whose `imageRef` or
+ * `contentHash` is not the pin image's `imageRef` and `sourceTreeHash`.
+ *
+ * @param {{pins: {byRepository: (repository: string) => object|undefined}, subjects: readonly object[]}} request
+ * @returns {Map<string, object>}
+ */
+export function thirdPartyImagePins({ pins, subjects }) {
+  const pinned = new Map();
+  for (const subject of subjects) {
+    const pin = pins.byRepository(subject.repo);
+    if (pin === undefined) {continue;}
+    const key = imageSubjectKey(subject);
+    const image = pin.images.find((candidate) => candidate.subjectKind === subject.kind && candidate.subjectId === subject.id);
+    if (image === undefined) {
+      throw new Error(`${key} is a subject of the third-party repository "${subject.repo}" (source "${pin.name}"), but the pin pins no image for ${key}`);
+    }
+    if (subject.imageRef !== image.imageRef) {
+      throw new Error(`${key} (third-party source "${pin.name}") has imageRef ${subject.imageRef}, but the pin pins ${image.imageRef}`);
+    }
+    if (subject.contentHash !== image.sourceTreeHash) {
+      throw new Error(`${key} (third-party source "${pin.name}") has contentHash ${subject.contentHash}, but the pin's publisher-attested sourceTreeHash is ${image.sourceTreeHash}`);
+    }
+    pinned.set(key, image);
+  }
+  return pinned;
+}
+
+/** The `kind:id` -> manifestDigest map the platform verifier reads pinned subjects by. */
+export const pinnedManifestDigests = (pinnedImages) => new Map([...pinnedImages].map(([key, image]) => [key, image.manifestDigest]));

package/edition/third-party-pins-trusted.mjs

@@ -0,0 +1,24 @@
+// The data root's third-party source pins, read by a consumer that does not run the full evidence verification (the
+// develop and release seals): held to the evidence trust pin's record of the pin file's digest exactly as the verifiers
+// hold it (`assertPinnedThirdPartySourcePins`), so a pin file changed after the trust pin was last taken is refused.
+
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { assertPinnedThirdPartySourcePins, readEvidenceTrustPin } from './evidence-trust-pin.mjs';
+import { THIRD_PARTY_SOURCE_PINS_FILE, loadThirdPartySourcePins, thirdPartySourcePinsDigest } from './third-party-source-pins.mjs';
+
+/**
+ * @param {string} dataRoot
+ * @returns the loaded third-party source pins, or an empty set when the data root has none and declares no trust pin
+ */
+export function loadTrustedThirdPartySourcePins(dataRoot) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  if (declaration.policy === null) {
+    const digest = thirdPartySourcePinsDigest(dataRoot);
+    if (digest !== null) {
+      throw new Error(`the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE} (${digest}) but declares no evidenceTrustPolicy, so there is no trust pin to hold it to`);
+    }
+    return loadThirdPartySourcePins(dataRoot);
+  }
+  assertPinnedThirdPartySourcePins({ pin: readEvidenceTrustPin({ dataRoot, declaration }), dataRoot });
+  return loadThirdPartySourcePins(dataRoot);
+}

package/edition/third-party-producer-evidence.mjs

@@ -0,0 +1,76 @@
+// The producer record of one third-party image subject in an evidence set (XEMA-1611 design section 4).
+//
+// A first-party subject's evidence is read from the registry (the OCI referrer of `<imageRef>:<contentHash>`). A
+// third-party subject has no such tag: its `contentHash` is the publisher's attested `sourceTreeHash`. Its evidence is
+// the COMMITTED evidence of the data root (`evidence/sha256-<manifest hex>/producer-evidence.json` + statements/ +
+// bundles/) that its pin binds by `statementDigest` and `bundleDigest`. This reads that evidence, holds it to the pin
+// and to the subject, and returns the SAME record shape the first-party branch of `resolveProducerEvidence` builds.
+// It makes no registry call.
+
+import { canonicalJson, decodeExactUtf8, evidenceDirectoryForDigest, sha256Digest } from './image-evidence.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import { validateProducedBundle } from './produce-image-source-evidence.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { committedImageDescriptor } from './third-party-source-evidence.mjs';
+
+/** The bound committed evidence files are read at (the same as the first-party committed reads). */
+const MAX_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * @param {object} request
+ * @param {object} request.subject the third-party image subject (sealed or not)
+ * @param {object} request.pinImage its image in the third-party source pin
+ * @param {string} request.dataRoot the data root holding the committed evidence
+ * @param {object} request.schemas trusted kernel distribution schemas
+ * @param {object} request.expectedSource the canonical `predicate.source` the statement must attest
+ * @param {string} request.stem the producer's staging stem
+ */
+export function thirdPartyProducerRecord({ subject, pinImage, dataRoot, schemas, expectedSource, stem }) {
+  const key = `${subject.kind}:${subject.id}`;
+  const label = `third-party ${key} committed evidence`;
+  const descriptor = committedImageDescriptor({ image: pinImage, evidenceRoot: dataRoot, label });
+  const statementBytes = readBoundedNoFollowFile(dataRoot, descriptor.statementPath, `${label} statement`, MAX_EVIDENCE_FILE_BYTES).bytes;
+  const bundleBytes = readBoundedNoFollowFile(dataRoot, descriptor.bundlePath, `${label} bundle`, MAX_EVIDENCE_FILE_BYTES).bytes;
+  if (sha256Digest(statementBytes) !== pinImage.statementDigest) {
+    throw new Error(`${label}: the committed statement ${descriptor.statementPath} is ${sha256Digest(statementBytes)}, not the pin's statementDigest ${pinImage.statementDigest}`);
+  }
+  if (sha256Digest(bundleBytes) !== pinImage.bundleDigest) {
+    throw new Error(`${label}: the committed bundle ${descriptor.bundlePath} is ${sha256Digest(bundleBytes)}, not the pin's bundleDigest ${pinImage.bundleDigest}`);
+  }
+  validateProducedBundle(statementBytes, bundleBytes);
+  const statement = schemas.parseImageProducerStatement(JSON.parse(decodeExactUtf8(statementBytes, 'committed statement')));
+  if (canonicalJson(statement.predicate.source) !== canonicalJson(expectedSource)) {
+    throw new Error(`${label}: the committed statement attests another source than the one ${key} is locked at (${subject.repo}@${subject.sourceCommit}, publisher-attested source tree ${subject.contentHash})`);
+  }
+  const { artifact } = statement.predicate;
+  if (artifact.imageRepository !== subject.imageRef || statement.subject[0].name !== subject.imageRef) {
+    throw new Error(`${label}: it attests image "${artifact.imageRepository}" (statement subject "${statement.subject[0].name}"), not the locked "${subject.imageRef}"`);
+  }
+  if (`sha256:${statement.subject[0].digest.sha256}` !== artifact.manifestDigest) {
+    throw new Error(`${label}: its statement subject digest sha256:${statement.subject[0].digest.sha256} is not its artifact.manifestDigest ${artifact.manifestDigest}`);
+  }
+  if (artifact.manifestDigest !== pinImage.manifestDigest) {
+    throw new Error(`${label}: the committed statement attests manifest ${artifact.manifestDigest}, not the pin's manifestDigest ${pinImage.manifestDigest}`);
+  }
+  if (subject.imageDigest !== undefined && subject.imageDigest !== artifact.manifestDigest) {
+    throw new Error(`${label}: ${key} is sealed at ${subject.imageDigest}, but the committed statement attests manifest ${artifact.manifestDigest}`);
+  }
+  return {
+    stem,
+    subjectKind: subject.kind,
+    subjectId: subject.id,
+    imageRepository: subject.imageRef,
+    manifestDigest: artifact.manifestDigest,
+    statement,
+    sourceDirectory: evidenceDirectoryForDigest(pinImage.manifestDigest),
+    statementBytes,
+    bundleBytes,
+    evidence: {
+      statementPath: `producers/${stem}/statement.json`,
+      statementDigest: sha256Digest(statementBytes),
+      bundlePath: `producers/${stem}/bundle.sigstore.json`,
+      bundleDigest: sha256Digest(bundleBytes),
+      bundleMediaType: BUNDLE_MEDIA_TYPE,
+    },
+  };
+}

package/edition/third-party-source-check.mjs

@@ -0,0 +1,28 @@
+// `xema-edition index runtime-image-source --check-third-party` (XEMA-1611 design section 3, `--check`): re-run checks
+// (a) to (e) for every pin of `third-party-source-pins.json` from the COMMITTED evidence, offline. A data root with no
+// pin file has no third-party source and passes trivially (zero-config); a pin file that is present but wrong throws.
+
+import { loadThirdPartySourceContext } from './third-party-source-context.mjs';
+import { verifyThirdPartySourceEvidence } from './third-party-source-evidence.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import { assertThirdPartyUniqueness } from './third-party-source-uniqueness.mjs';
+
+/**
+ * @returns {Promise<{checked: number, absence: string|null}>}
+ */
+export async function checkThirdPartySourcePins({ dataRoot, schemas, cosignBinary, channel }) {
+  const pins = loadThirdPartySourcePins(dataRoot);
+  if (pins.sources.length === 0) {
+    return { checked: 0, absence: pins.absence };
+  }
+  const context = loadThirdPartySourceContext({ dataRoot, schemas, cosignBinary });
+  try {
+    assertThirdPartyUniqueness({ sources: pins.sources, ...context });
+    for (const source of pins.sources) {
+      verifyThirdPartySourceEvidence({ source, evidenceRoot: dataRoot, context, channel });
+    }
+  } finally {
+    context.dispose();
+  }
+  return { checked: pins.sources.length, absence: null };
+}

package/edition/third-party-source-context.mjs

@@ -0,0 +1,41 @@
+// What the third-party writer and `--check-third-party` verify a pin AGAINST: the data root's pinned trust policy, its
+// pinned kernel contract authority, its committed indexes and a cosign binary held to the policy's digest pins.
+// One loader, so the two cannot be given different trust.
+
+import { join } from 'node:path';
+
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { RUNTIME_IMAGE_SOURCE_INDEX_FILE, loadPinnedDeclaredTrustPolicy, readPinnedKernelContractAuthority } from './evidence-trust-pin.mjs';
+import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/**
+ * Load the verification context of `dataRoot`. Throws when the data root declares no evidence trust policy, when the
+ * policy or the third-party pin file is not the one the evidence trust pin records (review, then
+ * `xema-edition repin-evidence-trust`), or when the cosign binary is not one the policy pins.
+ *
+ * @returns {{policy, policyRoot, schemas, expectedContractAuthority, runtimeSourceIndex, biomeIndex, platformServiceIndex, trustedCosign, dispose: () => void}}
+ */
+export function loadThirdPartySourceContext({ dataRoot, schemas, cosignBinary }) {
+  if (cosignBinary === undefined) {
+    throw new Error('verifying a third-party source needs a cosign binary: pass --cosign <absolute path> (`dist-check` reads XEMA_COSIGN_BIN); it must be one the trust policy pins by digest');
+  }
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const policy = loadPinnedDeclaredTrustPolicy({ dataRoot, declaration, schemas });
+  const expectedContractAuthority = readPinnedKernelContractAuthority({ dataRoot, declaration, schemas });
+  const runtimeSourceIndex = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE)));
+  const biomeIndex = readStrictJsonFile(join(dataRoot, 'biome-index.json'));
+  const platformServiceIndex = readStrictJsonFile(join(dataRoot, 'platform-service-index.json'));
+  const trustedCosign = prepareTrustedCosignBinary({ cosignBinary, policy });
+  return {
+    policy,
+    policyRoot: dataRoot,
+    schemas,
+    expectedContractAuthority,
+    runtimeSourceIndex,
+    biomeIndex,
+    platformServiceIndex,
+    trustedCosign,
+    dispose: () => trustedCosign.dispose(),
+  };
+}