@xemahq/xema 0.47.1 → 0.49.0

package/edition/build-runtime-image-source-index.mjs

@@ -26,6 +26,8 @@ import {
   serializeJson,
   sha256Hex,
 } from './lib.mjs';
+import { createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { disposeRegistrySessions } from './oras.mjs';
 import {
   platformServiceRuntimeBindings,
 } from './platform-service-source-authority.mjs';
@@ -36,6 +38,15 @@ import {
   parseSourceModeArgs,
 } from './source-authority.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
+import { checkThirdPartySourcePins } from './third-party-source-check.mjs';
+import { loadThirdPartySourceContext } from './third-party-source-context.mjs';
+import {
+  CHECK_THIRD_PARTY_FLAG,
+  THIRD_PARTY_FLAG,
+  THIRD_PARTY_WRITER_USAGE,
+  takeThirdPartyFlags,
+} from './third-party-source-flags.mjs';
+import { commitThirdPartySourceWrite, planThirdPartySourceWrite } from './third-party-source-writer.mjs';
 
 if (isEntryModule(import.meta.url)) {
   configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
@@ -398,6 +409,18 @@ export function mergeProducerWorkflowPins(committedPins, statedPins) {
   return [...merged.values()].sort((left, right) => compareStrings(left.repository, right.repository));
 }
 
+/**
+ * The committed index with one producer workflow pin merged in by `mergeProducerWorkflowPins`: what the third-party
+ * writer adds (`{repository, workflowCommit: sourceCommit}`). Every repository pin and subject is kept exactly: a
+ * third-party repository is not an index repository, so nothing about it can be re-resolved.
+ */
+export function indexWithProducerWorkflowPin({ committedIndex, pin }) {
+  return {
+    ...committedIndex,
+    producerWorkflowPins: mergeProducerWorkflowPins(committedIndex.producerWorkflowPins, [pin]),
+  };
+}
+
 const PRODUCER_WORKFLOW_PIN_FLAG = '--producer-workflow-pin';
 
 /**
@@ -972,12 +995,38 @@ const USAGE =
   '--repin-contract-authority --kernel-commit <40-hex-commit>) ' +
   '[--source published|workspace] [--kernel-root <absolute-checkout>] ' +
   '[--repo <repository> [--at <40-hex-commit>]] [--producer-workflow-pin <owner/repo>=<40-hex-commit> ...] ' +
-  '(--trusted-write on a data root with no committed contract authority also requires --kernel-commit)';
+  '(--trusted-write on a data root with no committed contract authority also requires --kernel-commit)\n' +
+  `       build-runtime-image-source-index.mjs --trusted-write ${THIRD_PARTY_WRITER_USAGE}\n` +
+  `       build-runtime-image-source-index.mjs ${CHECK_THIRD_PARTY_FLAG} [--cosign <absolute cosign path>]`;
+
+/** `--trusted-write --third-party <name>`: verify one third-party source and commit its pin, evidence and producer workflow pin. */
+async function writeThirdPartySource({ schemas, writer, cosignBinary, kernelRoot }) {
+  const context = loadThirdPartySourceContext({ dataRoot: dataRoot(), schemas, cosignBinary });
+  try {
+    const plan = await planThirdPartySourceWrite({
+      request: writer,
+      context,
+      clientFor: createRegistryClientResolver({ dataRoot: dataRoot() }),
+      dataRoot: dataRoot(),
+      withProducerWorkflowPin: indexWithProducerWorkflowPin,
+    });
+    await validateRuntimeImageSourceIndex(plan.candidateIndex, schemas, { kernelRoot });
+    const next = commitThirdPartySourceWrite({
+      dataRoot: dataRoot(),
+      plan,
+      indexPath: runtimeImageSourceIndexPath(),
+      indexText: serializeJson(plan.candidateIndex),
+    });
+    console.log(`[runtime-image-source-index] ${next}`);
+  } finally {
+    context.dispose();
+    disposeRegistrySessions();
+  }
+}
 
 async function main() {
-  const { kernelRoot, remaining: afterKernelRootFlag } = parseKernelRoot(
-    process.argv.slice(2),
-  );
+  const { writer, cosignBinary, remaining: afterThirdPartyFlags } = takeThirdPartyFlags(process.argv.slice(2));
+  const { kernelRoot, remaining: afterKernelRootFlag } = parseKernelRoot(afterThirdPartyFlags);
   const { kernelCommit, remaining: afterKernelRoot } = parseKernelCommit(afterKernelRootFlag);
   const { producerWorkflowPins, remaining: afterWorkflowPins } = parseProducerWorkflowPinFlags(afterKernelRoot);
   const { repoScope, remaining: afterRepoScope } = parseRepoScope(afterWorkflowPins);
@@ -989,15 +1038,40 @@ async function main() {
   const [flag] = remaining;
   if (
     remaining.length !== 1 ||
-    !['--check', '--check-sources', '--trusted-write', REPIN_FLAG].includes(flag)
+    ![CHECK_THIRD_PARTY_FLAG, '--check', '--check-sources', '--trusted-write', REPIN_FLAG].includes(flag)
   ) {
     throw new Error(USAGE);
   }
+  if (cosignBinary !== undefined && writer === undefined && flag !== CHECK_THIRD_PARTY_FLAG) {
+    throw new Error(`--cosign belongs to ${THIRD_PARTY_FLAG} or ${CHECK_THIRD_PARTY_FLAG}: ${flag} runs no cosign\n${USAGE}`);
+  }
   if (kernelCommit !== undefined && ![REPIN_FLAG, '--trusted-write'].includes(flag)) {
     throw new Error(`${KERNEL_COMMIT_FLAG} states the commit of a new contract authority: ${flag} chooses none\n${USAGE}`);
   }
   assertProducerWorkflowPinsWritten(producerWorkflowPins, flag, USAGE);
   const schemas = await loadKernelDistributionSchemas();
+  if (flag === CHECK_THIRD_PARTY_FLAG) {
+    if (repoScope !== undefined || exactCommit !== undefined || kernelCommit !== undefined) {
+      throw new Error(`${CHECK_THIRD_PARTY_FLAG} re-verifies the committed third-party pins only: it takes no --repo, --at or ${KERNEL_COMMIT_FLAG}`);
+    }
+    const { checked } = await checkThirdPartySourcePins({ dataRoot: dataRoot(), schemas, cosignBinary });
+    console.log(
+      checked === 0
+        ? '[runtime-image-source-index] no third-party source is pinned in this data root'
+        : `[runtime-image-source-index] third-party source check passed for ${checked} pinned source(s)`,
+    );
+    return;
+  }
+  if (writer !== undefined) {
+    if (flag !== '--trusted-write') {
+      throw new Error(`${THIRD_PARTY_FLAG} writes a pin: it takes --trusted-write\n${USAGE}`);
+    }
+    if (repoScope !== undefined || exactCommit !== undefined || kernelCommit !== undefined || producerWorkflowPins.length > 0) {
+      throw new Error(`${THIRD_PARTY_FLAG} writes one third-party pin: it takes no --repo, --at, ${KERNEL_COMMIT_FLAG} or ${PRODUCER_WORKFLOW_PIN_FLAG}`);
+    }
+    await writeThirdPartySource({ schemas, writer, cosignBinary, kernelRoot });
+    return;
+  }
   if (flag === REPIN_FLAG) {
     if (repoScope !== undefined || exactCommit !== undefined) {
       throw new Error(`${REPIN_FLAG} replaces the contract authority only: it takes no --repo or --at`);

package/edition/canonical-evidence-json.mjs

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

package/edition/catalogue-evidence.mjs

@@ -69,11 +69,14 @@ export class CatalogueVerifierNotPinnedError extends Error {
   }
 }
 
+/** The edition a catalogue-consumer refusal names: the customer edition of `channel` that reads the catalogue. */
+const catalogueConsumer = (channel) => ({ edition: `${channel} edition`, channel });
+
 /** The pinned built verifier's bundle path, after the data root's pin of it held; refuses before anything is spawned. */
-function pinnedVerifierBundle(locateVerifier) {
+function pinnedVerifierBundle(locateVerifier, channel) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
-  if (declaration.policy === null) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+  if (declaration.policy === null) {throw new EvidenceTrustRequiredError(root, 'declares no policy', catalogueConsumer(channel));}
   try {
     const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
     assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
@@ -111,12 +114,12 @@ const stderrOf = (result) => String(result.stderr ?? '').trim() || (result.error
  * @param {{ channel: string, locateVerifier?: Function, spawn?: Function }} options
  */
 export function assertCatalogueConsumerArmed({ channel, locateVerifier = locateBuiltVerifier, spawn = spawnSync }) {
-  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier, channel);
   const result = runVerifier({ spawn, bundlePath, args: ['arming', '--channel', channel, '--data-root', root] });
   if (result.status === 0) {return;}
   const stderr = stderrOf(result);
   if (stderr.includes('EVIDENCE_TRUST_REQUIRED_UNARMED')) {
-    throw new EvidenceTrustRequiredError(root, `declares a policy that is not armed on the ${channel} channel for a catalogue consumer (${stderr})`);
+    throw new EvidenceTrustRequiredError(root, `declares a policy that is not armed on the ${channel} channel for a catalogue consumer (${stderr})`, catalogueConsumer(channel));
   }
   throw new CatalogueEvidenceNotVerifiedError(`the ${channel} catalogue`, `the arming check failed: ${stderr}`);
 }
@@ -181,7 +184,7 @@ export async function verifyCatalogueEvidenceReferrer({
   if (sha256Of(statementBytes) !== layers.statement.digest || sha256Of(bundleBytes) !== layers.bundle.digest) {
     throw new CatalogueEvidenceNotVerifiedError(ref, 'a referrer layer does not hash to its digest');
   }
-  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier, channel);
   const evidenceRoot = mkdtempSync(join(tmpdir(), 'xema-catalogue-evidence-'));
   try {
     writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_STATEMENT_TITLE), statementBytes, { flag: 'wx', mode: 0o600 });

package/edition/customer-edition-verbs.mjs

@@ -25,7 +25,7 @@ import { isDevelopImageRef } from './develop-image-coordinate.mjs';
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { LOCAL_WORKFLOW, assertEngineImage, assertExistingArtifactMatches, snapshotEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
-import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, EditionChannel, EditionKind, EditionLockFile } from './edition-constants.mjs';
 import { channelImageRef, sealImageSubjects } from './edition-image-seal.mjs';
 import { WorkspaceRoot } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
@@ -219,6 +219,12 @@ const COMMANDS = Object.freeze({
     switches: [],
     required: ['--branch', '--registry', '--cosign', '--out'],
   },
+  'verify-image-record': {
+    positional: false,
+    values: ['--image', '--producer', '--registry', '--cosign'],
+    switches: [],
+    required: ['--image', '--producer', '--registry', '--cosign'],
+  },
   'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
   'choose-kernel': { positional: false, values: ['--kernel-pin', '--out'], switches: [], required: ['--out'] },
   'check-existing': {
@@ -360,7 +366,7 @@ async function resolveCustomer(channel, options, env) {
     sourceImages,
     env,
   });
-  const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel, consumesCatalogue: true });
+  const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel, consumesCatalogue: true });
   const target = snapshotEditionTarget(channel, id, pins, { registry: options['--registry'], engineImage: options['--engine-image'], sourceImages });
   // A release edition is admitted only sealed: every image names the digest the registry serves. (A develop edition is not held to it today.)
   if (channel === EditionChannel.Release) {assertSealedImageLock(resolved.imageLock, `the images lock of "${id}"`);}
@@ -393,7 +399,7 @@ export async function checkExistingCustomer(channel, options, env, { adopt = ado
     artifactDir: resolve(options['--artifact']),
     distributionId: frame.id,
     channel,
-    evidenceTrustPolicy: await descriptorEvidenceTrust({ channel, locateVerifier, consumesCatalogue: true }),
+    evidenceTrustPolicy: await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel, locateVerifier, consumesCatalogue: true }),
     pins: frame.pins,
     engineImage: options['--engine-image'],
     catalogueDigest: frame.catalogueDigest,

package/edition/develop-coverage-run.mjs

@@ -9,6 +9,7 @@ import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition
 import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
 import { prepareTrustedCosignBinary } from './image-evidence.mjs';
 import { readPinnedContractAuthority } from './produce-image-source-evidence.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
 
 const stderrProgress = (line) => process.stderr.write(`${line}\n`);
 
@@ -37,7 +38,7 @@ export async function runDevelopCoverage({
     progress(`[coverage] image content hashes computed (${imageLock.subjects.length} subjects)`);
     const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, expectedContractAuthority: readPinnedContractAuthority({ dataRoot, schemas }), dataRoot, env, ...readerOptions });
     try {
-      const report = await collectCoverage({ distributionId: id, subjects: imageLock.subjects, policy, readers, progress });
+      const report = await collectCoverage({ distributionId: id, subjects: imageLock.subjects, policy, readers, thirdPartyPins: loadThirdPartySourcePins(dataRoot), progress });
       write(json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageTable(report));
       return coverageExitCode(report);
     } finally {

package/edition/develop-coverage.mjs

@@ -11,6 +11,8 @@ import { AttestationStatus, COVERED_VERDICTS, DEVELOP_EVIDENCE_CHANNEL, DEVELOP_
 import { developImageRef } from './develop-image-coordinate.mjs';
 import { policyCandidates } from './image-evidence.mjs';
 import { mapWithConcurrency } from './map-with-concurrency.mjs';
+import { imageSubjectKey, thirdPartyImagePins } from './third-party-image-pins.mjs';
+import { attestedContentHash } from './third-party-subjects.mjs';
 
 /** In flight at once, as `develop resolve` probes. */
 export const COVERAGE_CONCURRENCY = 6;
@@ -32,9 +34,18 @@ export const expectedService = (subject) => subject.id;
  * @param {object[]} request.subjects the images lock subjects (release refs, unsealed), contentHash = F
  * @param {object} request.policy the pinned trust policy (rows are filtered per develop repository)
  * @param {{ developDigest: Function, readAttestation: Function, readSignatures: Function }} request.readers
+ * @param {{byRepository: (repository: string) => object|undefined}} [request.thirdPartyPins] the data root's third-party
+ *   source pins: a subject of a pinned repository is not built by the develop lane, so it is no coverage subject
  * @param {(line: string) => void} [request.progress]
  */
-export async function collectCoverage({ distributionId, subjects, policy, readers, concurrency = COVERAGE_CONCURRENCY, progress = () => {} }) {
+export async function collectCoverage({ distributionId, subjects: lockSubjects, policy, readers, thirdPartyPins = undefined, concurrency = COVERAGE_CONCURRENCY, progress = () => {} }) {
+  const pinnedImages = thirdPartyPins === undefined ? new Map() : thirdPartyImagePins({ pins: thirdPartyPins, subjects: lockSubjects });
+  const subjects = lockSubjects.filter((subject) => !pinnedImages.has(imageSubjectKey(subject)));
+  for (const subject of lockSubjects.filter((candidate) => pinnedImages.has(imageSubjectKey(candidate)))) {
+    progress(
+      `[coverage] third-party ${imageSubjectKey(subject)} ${subject.imageRef}@${pinnedImages.get(imageSubjectKey(subject)).manifestDigest} ${attestedContentHash(subject)}, not a develop coverage subject`,
+    );
+  }
   const rows = await mapWithConcurrency(subjects, concurrency, async (subject) => {
     const developSubject = { ...subject, imageRef: developImageRef(subject.imageRef) };
     const digest = await readers.developDigest(developSubject);

package/edition/develop-edition-resolve.mjs

@@ -16,13 +16,14 @@ import { createDevelopImageProbe } from './develop-image-probe.mjs';
 import { assertFrozenCheckouts, buildSnapshotInputs } from './develop-snapshot-inputs.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { sealImages } from './edition-image-seal.mjs';
-import { kernelPackageDir } from './edition-workspace.mjs';
+import { dataRoot, kernelPackageDir } from './edition-workspace.mjs';
 import { kernelPackageOfAuthority } from './kernel-package.mjs';
 import { loadKernelDistributionSchemas } from './lib.mjs';
 import { deployPinKey } from './pin-source.mjs';
 import { composeAuthorizationBase, resolveDistributionWithIndex } from './resolve-distribution.mjs';
 import { externalSourceTrees, resolveImages, sourceTreeLocator } from './resolve-images.mjs';
 import { createPinnedSourceAuthority } from './source-authority.mjs';
+import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
 
 /**
  * The steps the resolve runs, named so a test can stand in for the ones that
@@ -83,7 +84,7 @@ export async function resolveDevelopEdition({ id, pins, env = process.env, sealO
   phase(`image content hashes computed (${imageLock.subjects.length} subjects)`);
   await probe.settle();
   phase('every develop image is present');
-  const sealedImageLock = await steps.sealImages({ channel: EditionChannel.Develop, imageLock, env, progress, ...sealOptions });
+  const sealedImageLock = await steps.sealImages({ channel: EditionChannel.Develop, imageLock, env, progress, thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot()), ...sealOptions });
   phase('images sealed');
   // The unsealed lock becomes the one v5 grammar only here, once the images it
   // owns are sealed: each biomeContentHash is recomputed from the frozen sources.

package/edition/develop-edition.mjs

@@ -45,6 +45,14 @@
 //       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
 //       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
 //       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
+//   verify-image-record --image <name>@sha256:<digest> --producer <owner/repo> --registry <root> --cosign <absolute-path>
+//       whether an authenticated develop build record of the producer lists exactly this image name and digest: the
+//       producer's records are read newest run first and verified as select-records verifies them (shared core); a record of a
+//       workflow other than the producer's `.github/workflows/ci.yaml` is skipped, and the newest ci.yaml record that lists the image answers.
+//       Prints { image, digest, producer, commit }: commit is that of the newest verified ci.yaml record (by run number, then attempt)
+//       that lists the digest; it can be an older commit when a later run targeted it, which is safe because the digest binds the bytes.
+//       Refuses (exit 1) when no ci.yaml record lists the image, the record
+//       names another producer, or cosign refuses the identity. Takes the roots `resolve` takes.
 //   select-records --branch develop --registry <root> --cosign <absolute-path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]
 //       for every develop-graph member, take the newest build record the data root's record workflow signed for
 //       the branch (<root>/build-records/<name>, verified offline by digest against the pinned trusted root, as
@@ -91,8 +99,9 @@ import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
 import { runSelectRecords } from './develop-select-records.mjs';
+import { runVerifyImageRecord } from './develop-verify-image-record.mjs';
 import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
-import { EditionChannel } from './edition-constants.mjs';
+import { EditionChannel, EditionKind } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir } from './edition-workspace.mjs';
 import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
 import { assertKernelCommitSupported, chooseKernelCommit } from './kernel-protocol-choice.mjs';
@@ -154,7 +163,7 @@ async function run(argv, env) {
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
       const target = developEditionTarget(id, pins, { registry: options['--registry'], engineImage: options['--engine-image'] });
-      const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Develop });
+      const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop });
       const { catalogue, ...resolved } = await resolveDevelopEdition({ id, pins, env });
       const outDir = resolve(options['--out']);
       writeEditionArtifact({
@@ -182,13 +191,16 @@ async function run(argv, env) {
     case 'select-records':
       await runSelectRecords({ options, env });
       return;
+    case 'verify-image-record':
+      await runVerifyImageRecord({ options, env });
+      return;
     case 'check-existing': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       assertExistingArtifactMatches({
         artifactDir: resolve(options['--artifact']),
         distributionId: id,
         channel: EditionChannel.Develop,
-        evidenceTrustPolicy: await descriptorEvidenceTrust({ channel: EditionChannel.Develop }),
+        evidenceTrustPolicy: await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop }),
         pins: readStrictJsonFile(options['--pins']),
         engineImage: options['--engine-image'],
       });

package/edition/develop-record-verify.mjs

@@ -0,0 +1,216 @@
+// develop-record-verify — the verify core of a signed build record, shared by `develop select-records` and
+// `develop verify-image-record`.
+//
+// A record is trusted only after cosign verified it, offline against the pinned trusted root, as signed by the
+// data root's `record-build.yaml` at `refs/heads/<branch>`, called by the member's own repository at the
+// record's own commit; the record must also name that member as its producer, its own branch and its own tag.
+// Both verbs read records through `loadVerifiedRecord`: there is one copy of this logic.
+//
+// Two failure classes: `RecordRefused` (the record is missing, or cosign or the record itself says no) and a
+// plain Error (the registry or cosign could not answer), which the operator retries rather than reads.
+
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
+import { RecordRefused } from './record-refused.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+
+/** The repository segment, under the registry root, that holds a member's build records. */
+export const BUILD_RECORDS_SEGMENT = 'build-records';
+export const RECORD_SIGNER_WORKFLOW = '.github/workflows/record-build.yaml';
+export const RECORD_SIGNER_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+/** The branches a record signer is declared for, each with the ref the record workflow runs at. */
+const RECORD_SIGNER_REFS = Object.freeze({ develop: 'refs/heads/develop' });
+/**
+ * A cosign exit whose stderr shows the registry was not reached before any verdict. Only this, a cosign that
+ * could not run, and a timeout are operational; every other non-zero exit of `cosign verify` is a verdict.
+ */
+const COSIGN_TRANSPORT_FAILURE = /dial tcp|i\/o timeout|connection (refused|reset)|no such host|TLS handshake timeout|context deadline exceeded/i;
+
+/** The record's producer is a kind this CLI has no claims for: a closed set, never guessed at. */
+export class UnknownBuildRecordProducerError extends RecordRefused {
+  constructor(repo, kind) {
+    super(repo, `the record's producer kind ${JSON.stringify(kind)} is not one select-records can verify`);
+    this.name = 'UnknownBuildRecordProducerError';
+  }
+}
+
+export class DataRootRepositoryUndeclaredError extends Error {
+  constructor() {
+    super('edition-workspace.json declares no dataRootRepositoryUrl; select-records cannot name the record signer');
+    this.name = 'DataRootRepositoryUndeclaredError';
+  }
+}
+
+export class KernelLacksBuildRecordSchemaError extends Error {
+  constructor(missing) {
+    super(`the kernel's distribution module does not export ${missing.join(', ')}; select-records needs a kernel with the build-record contract`);
+    this.name = 'KernelLacksBuildRecordSchemaError';
+  }
+}
+
+/** The data root's `owner/name`, from the workspace declaration; refused by name when it declares none. */
+export function declaredDataRootRepositoryUrl() {
+  const url = editionWorkspaceConfig().dataRootRepositoryUrl;
+  if (url === undefined) {throw new DataRootRepositoryUndeclaredError();}
+  return url;
+}
+
+/** The kernel's build-record exports, refused as a set when any is absent. */
+export function requireBuildRecordKernel(schemas) {
+  const names = ['BUILD_RECORD_MEDIA_TYPE', 'BuildRecordSchema', 'buildRecordTag', 'parseBuildRecordTag', 'compareBuildRecordRuns'];
+  const missing = names.filter((name) => schemas?.[name] === undefined);
+  if (missing.length > 0 || typeof schemas.BuildRecordSchema?.safeParse !== 'function') {
+    throw new KernelLacksBuildRecordSchemaError(missing.length > 0 ? missing : ['a BuildRecordSchema with safeParse']);
+  }
+  return schemas;
+}
+
+/** The ref and data-root repository a branch's records are signed by; refused before any network call. */
+export function recordSignerOrigin({ branch, dataRootRepositoryUrl }) {
+  const ref = Object.hasOwn(RECORD_SIGNER_REFS, branch) ? RECORD_SIGNER_REFS[branch] : undefined;
+  if (ref === undefined) {throw new Error(`no record signer declared for branch ${branch}`);}
+  if (dataRootRepositoryUrl === undefined) {throw new DataRootRepositoryUndeclaredError();}
+  const dataRepository = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(dataRootRepositoryUrl, 'dataRootRepositoryUrl'), 'dataRootRepositoryUrl');
+  return { ref, dataRepository };
+}
+
+/**
+ * The signer of the branch's records: the data root's record workflow at the branch, as the certificate states
+ * it, with the repository that CALLED the workflow (the member) as the workflow-repository claim.
+ */
+export function recordSigner({ branch, dataRootRepositoryUrl, memberRepositoryUrl }) {
+  const { ref, dataRepository } = recordSignerOrigin({ branch, dataRootRepositoryUrl });
+  const member = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(memberRepositoryUrl, 'repositoryUrl'), 'repositoryUrl');
+  return {
+    certificateIdentity: `https://github.com/${dataRepository}/${RECORD_SIGNER_WORKFLOW}@${ref}`,
+    oidcIssuer: RECORD_SIGNER_OIDC_ISSUER,
+    githubWorkflow: { repository: member, ref },
+    memberRepository: member,
+  };
+}
+
+/**
+ * What a record's producer says, read through the ONE switch over its kind: the repository that called the
+ * record workflow (the cosign caller claim, held equal to the member's) and the run the snapshot names.
+ */
+export function producerClaims({ record, repo, memberRepository }) {
+  switch (record.producer?.kind) {
+    case 'github-actions': {
+      const { repository, runNumber, runAttempt } = record.producer;
+      if (repository !== memberRepository) {throw new RecordRefused(repo, `record is produced by repository ${repository}, not ${memberRepository}`);}
+      return { repository, snapshot: `${runNumber}.${runAttempt}` };
+    }
+    default:
+      throw new UnknownBuildRecordProducerError(repo, record.producer?.kind);
+  }
+}
+
+/** Run one registry client call; ONLY a failure of the client itself is "the registry did not answer". */
+async function fromRegistry(repo, what, call) {
+  try {
+    return await call();
+  } catch (error) {
+    throw new Error(`select-records: ${repo}: the registry did not answer for ${what}: ${error.message}`);
+  }
+}
+
+/** Read one record by its tag: manifest by digest, its single layer, parsed against the kernel's schema. */
+async function readRecord({ kernel, client, repository, repo, tag }) {
+  const served = await fromRegistry(repo, `${repository}:${tag}`, () => client.getManifestByTag(repository, tag));
+  const manifest = await fromRegistry(repo, `${repository}@${served.digest}`, () => client.getManifestByDigest(repository, served.digest));
+  const layers = manifest.document.layers;
+  if (!Array.isArray(layers) || layers.length !== 1) {
+    throw new RecordRefused(repo, `record ${tag} has ${Array.isArray(layers) ? layers.length : 'no'} layers, not exactly one`);
+  }
+  const [layer] = layers;
+  if (layer.mediaType !== kernel.BUILD_RECORD_MEDIA_TYPE) {
+    throw new RecordRefused(repo, `record ${tag} layer media type is ${JSON.stringify(layer.mediaType)}, not ${kernel.BUILD_RECORD_MEDIA_TYPE}`);
+  }
+  const bytes = await fromRegistry(repo, `${repository}@${layer.digest}`, () => client.getBlob(repository, layer.digest));
+  let document;
+  try {
+    document = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new RecordRefused(repo, `record ${tag} is not JSON: ${error.message}`);
+  }
+  const parsed = kernel.BuildRecordSchema.safeParse(document);
+  if (!parsed.success) {throw new RecordRefused(repo, `record ${tag} does not parse as a build record: ${parsed.error.message}`);}
+  return { record: parsed.data, digest: served.digest };
+}
+
+/** The tag's record, verified by digest against the constrained signer, then held to its own repo, branch and tag. */
+export async function loadVerifiedRecord({ kernel, client, runCosign, cosignEnv, trustedRootPath, repository, member, branch, dataRootRepositoryUrl, tag }) {
+  const repo = member.repo;
+  const { record, digest } = await readRecord({ kernel, client, repository, repo, tag });
+  const signer = recordSigner({ branch, dataRootRepositoryUrl, memberRepositoryUrl: member.repositoryUrl });
+  const { repository: callerRepository, snapshot } = producerClaims({ record, repo, memberRepository: signer.memberRepository });
+  signer.githubWorkflow.repository = callerRepository;
+  const ref = `${repository}@${digest}`;
+  const args = ['verify', '--offline', '--trusted-root', trustedRootPath, ...certificateConstraintArgs(signer, record.commit), ref];
+  let result;
+  try {
+    result = await runCosign(args, cosignEnv);
+  } catch (error) {
+    // no numeric exit code: cosign did not run (spawn failure) or did not answer (timeout, kill signal)
+    throw new Error(`select-records: ${repo}: cosign could not run for ${ref}: ${error.message}`);
+  }
+  if (result.code !== 0) {
+    if (COSIGN_TRANSPORT_FAILURE.test(result.stderr)) {
+      throw new Error(`select-records: ${repo}: cosign could not reach the registry for ${ref} (exit ${result.code}): ${result.stderr.trim()}`);
+    }
+    throw new RecordRefused(repo, `cosign refused record ${tag} (${digest}) as signed by ${signer.certificateIdentity} (exit ${result.code}): ${result.stderr.trim()}`);
+  }
+  if (record.branch !== branch) {throw new RecordRefused(repo, `record ${tag} is for branch ${record.branch}, not ${branch}`);}
+  if (kernel.buildRecordTag(record) !== tag) {throw new RecordRefused(repo, `record tagged ${tag} says it is ${kernel.buildRecordTag(record)}`);}
+  return { record, snapshot };
+}
+
+
+/** The registry repository that holds a member's build records. */
+export function recordsRepositoryOf(registry, member) {
+  return `${registry}/${BUILD_RECORDS_SEGMENT}/${member.repo.split('/').at(-1)}`;
+}
+
+/**
+ * Every record tag a member published for `branch`, newest run first, with the registry client of its authority.
+ * Refused when none was ever published; a registry that did not answer is a plain Error.
+ */
+export async function listBuildRecordRuns({ kernel, clientFor, registry, member, branch }) {
+  const repository = recordsRepositoryOf(registry, member);
+  const { authority } = splitImageRef(repository);
+  const client = clientFor(authority);
+  let tags;
+  try {
+    tags = await client.listTags(repository);
+  } catch (error) {
+    if (isNotPublishedYet(error)) {throw new RecordRefused(member.repo, `${repository} does not exist: no build record was ever published`);}
+    throw new Error(`select-records: ${member.repo}: the registry did not answer for ${repository} tags: ${error.message}`);
+  }
+  const runs = tags
+    .map((tag) => ({ tag, run: kernel.parseBuildRecordTag(tag, branch) }))
+    .filter(({ run }) => run !== undefined)
+    .sort((a, b) => kernel.compareBuildRecordRuns(b.run, a.run));
+  if (runs.length === 0) {throw new RecordRefused(member.repo, `${repository} has no build record for branch ${branch}`);}
+  return { repository, authority, client, runs };
+}
+
+/**
+ * Prepare everything record verification needs (the declared pinned policy, the trusted cosign, the pinned trusted
+ * root, the registry clients and their credentials), hand it to `use`, and dispose of it. The injections are
+ * replaced by tests.
+ */
+export async function withRecordVerifier({ cosignBinary, env, loadKernel = loadKernelDistributionSchemas, ...pinned }, use) {
+  const dataRootRepositoryUrl = declaredDataRootRepositoryUrl();
+  return withPinnedCosign(
+    { cosignBinary, env, ...pinned, afterPolicy: async () => ({ kernel: requireBuildRecordKernel(await loadKernel()) }) },
+    ({ kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }) => use({ dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath }),
+  );
+}
+
+/** The environment cosign runs with for one authority: the pinned base plus its declared credential (pinned-cosign.mjs). */
+export { cosignEnvironment };