@xemahq/xema 0.45.0 → 0.46.0

package/edition/develop-select-records.mjs

@@ -0,0 +1,365 @@
+// develop-select-records — the body of `xema edition develop select-records`.
+//
+// For every member of the develop graph, take the newest signed build record the data root's record workflow
+// published for the branch, and write the snapshot it names: the commit to pin, the run it came from, and the
+// images it built. 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.
+//
+// "Newest" is the newest COMMIT on develop, never the highest run: every record of the branch is read and
+// verified, the selected commit must equal or descend from every other record's commit (git ancestry, develop
+// fetched from the member), and among that commit's records (re-runs of it) the highest run and attempt wins.
+// With --published-pins <file> (a file this verb wrote; only .pins is read) a member's published commit is kept
+// when the records are not ahead of it, and a diverged one is refused; without it the rule applies among the
+// records only (part 07 passes the flag).
+//
+// Every failure is a hard refusal naming the repository, and nothing is written. Two 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.
+//
+// Rollback residual: anyone who can delete registry tags can remove newer records, and select-records then pins
+// the newest remaining valid one. The guard is deploy-latest's (part 07): its owner refuses a snapshot that goes
+// backwards. This verb checks nothing against current pins.
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { writeOnce } from './customer-edition-verbs.mjs';
+import { basicAuthParts, defaultRunCosign } from './develop-coverage-readers.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { PublishedRecordMissingError, newestCommitOnDevelop } from './develop-record-ancestry.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot } from './edition-workspace.mjs';
+import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
+import { COSIGN_ENV, prepareTrustedCosignBinary, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
+import { RecordRefused } from './record-refused.mjs';
+import { loadRegistryCredentialDeclarations, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+import { registryClientsFor } from './verify-image-platforms.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;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+/** 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. */
+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 };
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.branch
+ * @param {string} request.registry the registry root, e.g. `registry.example.com/acme`
+ * @param {string} [request.at] ISO-8601 UTC: the newest record completed at or before it
+ * @param {readonly {repo: string, repositoryUrl: string}[]} request.members
+ * @param {string|undefined} request.dataRootRepositoryUrl
+ * @param {object} request.kernel the kernel's distribution exports
+ * @param {(authority: string) => object} request.clientFor registry client of an authority
+ * @param {(args: string[], env: object) => Promise<{code: number, stdout: string, stderr: string}>} request.runCosign
+ * @param {(authority: string) => object} request.cosignEnvFor
+ * @param {string} request.trustedRootPath
+ * @param {Record<string, string>} [request.publishedPins] member repo -> the commit already published (--published-pins)
+ * @param {object} request.workspace the workspace config the source hold reads
+ * @param {object} request.env
+ * @param {Function} [request.runGit] replaced by tests
+ * @returns {Promise<{pins: object, snapshot: object, images: object[]}>}
+ */
+export async function selectRecords({ branch, registry, at, members, dataRootRepositoryUrl, kernel, clientFor, runCosign, cosignEnvFor, trustedRootPath, publishedPins, workspace, env, runGit }) {
+  requireBuildRecordKernel(kernel);
+  recordSignerOrigin({ branch, dataRootRepositoryUrl });
+  if (at !== undefined && (!ISO_UTC.test(at) || Number.isNaN(Date.parse(at)))) {
+    throw new Error(`--at must be an ISO-8601 UTC time (YYYY-MM-DDTHH:MM:SSZ); got ${JSON.stringify(at)}`);
+  }
+  const selected = [];
+  for (const member of members) {
+    const repository = `${registry}/${BUILD_RECORDS_SEGMENT}/${member.repo.split('/').at(-1)}`;
+    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}`);}
+    // EVERY candidate is read and verified; any that fails refuses the run. None is skipped.
+    const verified = [];
+    for (const { tag, run } of runs) {
+      const loaded = await loadVerifiedRecord({
+        kernel, client, runCosign, cosignEnv: { ...COSIGN_ENV, ...cosignEnvFor(authority) }, trustedRootPath,
+        repository, member, branch, dataRootRepositoryUrl, tag,
+      });
+      verified.push({ tag, run, ...loaded });
+    }
+    const eligible = at === undefined ? verified : verified.filter(({ record }) => Date.parse(record.completedAt) <= Date.parse(at));
+    if (eligible.length === 0) {throw new RecordRefused(member.repo, `no build record for branch ${branch} completed at or before ${at}`);}
+    const published = publishedPins?.[member.repo];
+    const commit = newestCommitOnDevelop({
+      member, candidates: eligible.map(({ record, tag }) => ({ commit: record.commit, tag })), published, workspace, env, runGit,
+    });
+    // records of one commit are re-runs of it: the highest run, then attempt
+    const ofCommitIn = (pool) => pool.filter(({ record }) => record.commit === commit).sort((a, b) => kernel.compareBuildRecordRuns(b.run, a.run));
+    // a kept published commit may be one --at left out of the eligible records: its own verified record stands
+    const ofCommit = ofCommitIn(eligible).length > 0 ? ofCommitIn(eligible) : ofCommitIn(verified);
+    if (ofCommit.length === 0) {throw new PublishedRecordMissingError(member.repo, commit);}
+    const chosen = ofCommit[0];
+    selected.push({ member, ...chosen });
+  }
+  return composeSelection(selected);
+}
+
+/** The snapshot a selection writes. A name built by two records is refused: an image has one builder. */
+export function composeSelection(selected) {
+  const pins = {};
+  const snapshot = {};
+  const owners = new Map();
+  const images = [];
+  for (const { member, record, snapshot: run } of selected) {
+    pins[member.repo] = record.commit;
+    snapshot[member.repo] = run;
+    for (const image of record.images) {
+      if (owners.has(image.name)) {
+        throw new RecordRefused(member.repo, `image ${image.name} is also built by ${owners.get(image.name)}; an image has one builder`);
+      }
+      owners.set(image.name, member.repo);
+      images.push({ name: image.name, digest: image.digest, contentHash: image.contentHash });
+    }
+  }
+  const sorted = (object) => Object.fromEntries(Object.entries(object).sort(([a], [b]) => compareStrings(a, b)));
+  return { pins: sorted(pins), snapshot: sorted(snapshot), images: images.sort((a, b) => compareStrings(a.name, b.name)) };
+}
+
+/** The `pins` of a file this verb wrote: member repo -> 40-hex commit. Nothing else of the file is read. */
+export function readPublishedPins(path) {
+  const document = readStrictJsonFile(path);
+  const { pins } = document ?? {};
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error(`--published-pins ${path} has no "pins" object`);
+  }
+  for (const [repo, commit] of Object.entries(pins)) {
+    if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/.test(commit)) {
+      throw new Error(`--published-pins ${path}: pin ${JSON.stringify(repo)} is not a 40-hex commit: ${JSON.stringify(commit)}`);
+    }
+  }
+  return pins;
+}
+
+/** The `select-records` verb. Writes `--out` once, only after every member was selected. */
+export async function runSelectRecords({
+  options,
+  env = process.env,
+  loadPolicy = loadDeclaredPinnedPolicy,
+  prepareCosign = prepareTrustedCosignBinary,
+  loadKernel = loadKernelDistributionSchemas,
+  trustedRootBytes = (root, pinnedPolicy) => validatePinnedTrustedRoot(root, pinnedPolicy).bytes,
+  cosignPathOf = (handle) => assertPreparedExecutable(handle, 'cosign'),
+  members = developGraphMembers(),
+  runCosign: injectedRunCosign,
+  clientsOverride,
+  runGit,
+  write = writeOnce,
+}) {
+  const dataRootRepositoryUrl = declaredDataRootRepositoryUrl();
+  const { policy, dataRoot: policyRoot } = await loadPolicy();
+  const kernel = requireBuildRecordKernel(await loadKernel());
+  const trustedCosign = prepareCosign({ cosignBinary: options['--cosign'], policy });
+  const cosignPath = cosignPathOf(trustedCosign);
+  const runCosign = injectedRunCosign ?? ((args, cosignEnv) => defaultRunCosign(cosignPath, args, cosignEnv));
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-select-records-'));
+  try {
+    const trustedRootPath = join(scratch, 'trusted-root.json');
+    writeFileSync(trustedRootPath, trustedRootBytes(policyRoot, policy), { flag: 'wx', mode: 0o600 });
+    const declarations = clientsOverride === undefined ? loadRegistryCredentialDeclarations(dataRoot()) : null;
+    const clients = new Map();
+    const clientFor = (authority) => {
+      if (clientsOverride !== undefined) {return clientsOverride(authority);}
+      if (!clients.has(authority)) {
+        clients.set(authority, registryClientsFor([{ imageRef: `${authority}/x` }], { declarations, env }).get(authority));
+      }
+      return clients.get(authority);
+    };
+    // cosign gets the SAME declared credential oras uses, in its environment, never argv.
+    const cosignEnvFor = (authority) => {
+      if (clientsOverride !== undefined) {return {};}
+      const credential = resolveRegistryCredential({ authority, declarations, env });
+      if (credential.access === 'anonymous') {return {};}
+      const { username, password } = basicAuthParts(credential);
+      return { COSIGN_REGISTRY_USERNAME: username, COSIGN_REGISTRY_PASSWORD: password };
+    };
+    const selection = await selectRecords({
+      branch: options['--branch'],
+      registry: options['--registry'],
+      at: options['--at'],
+      members,
+      dataRootRepositoryUrl,
+      kernel,
+      clientFor,
+      runCosign,
+      cosignEnvFor,
+      trustedRootPath,
+      publishedPins: options['--published-pins'] === undefined ? undefined : readPublishedPins(options['--published-pins']),
+      workspace: editionWorkspaceConfig(),
+      env,
+      runGit,
+    });
+    write(options['--out'], selection);
+    return selection;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+    trustedCosign.dispose();
+  }
+}

package/edition/distribution-evidence-set.mjs

@@ -61,7 +61,9 @@ import { compareStrings } from './lib.mjs';
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 import {
   createRegistryClientResolver,
+  describeInvalidReferrer,
   resolveImageSourceEvidenceReferrer,
+  writeInvalidReferrerReport,
 } from './oci-image-source-evidence.mjs';
 import { BUNDLE_MEDIA_TYPE, canonicalSignedBundleBytes, cosignVerifyAttestationArgs, validateProducedBundle } from './produce-image-source-evidence.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
@@ -494,12 +496,25 @@ export async function resolveProducerEvidence({
     const { authority, repository } = splitImageRef(subject.imageRef);
     const client = clientFor(authority);
     const image = await client.getManifestByTag(repository, subject.contentHash);
+    const invalidReferrers = [];
     const ociEvidence = await resolveImageSourceEvidenceReferrer({
       client,
       imageRepository: subject.imageRef,
       subjectDigest: image.digest,
       schemas,
+      expectedContractAuthority,
+      onInvalidReferrer: (skipped) => {
+        invalidReferrers.push(skipped);
+        writeInvalidReferrerReport(skipped);
+      },
     });
+    if (ociEvidence === null && invalidReferrers.length > 0) {
+      throw new Error(
+        `no valid OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +
+          `at ${subject.imageRef}@${image.digest}: ` +
+          invalidReferrers.map(describeInvalidReferrer).join('; '),
+      );
+    }
     if (ociEvidence === null) {
       throw new Error(
         `no OCI image-source evidence referrer exists for "${subject.kind}:${subject.id}" ` +

package/edition/edition-config.mjs

@@ -7,7 +7,7 @@
 
 import { join } from 'node:path';
 
-import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
 import { dataRoot } from './edition-workspace.mjs';
 import { isUnderSourcePrefix } from './git-source-auth.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
@@ -49,6 +49,7 @@ const KEYS = Object.freeze([
   'chartRegistry',
   'chartPublishers',
   'sourceRepositoryUrlPrefix',
+  'dataRootRepositoryUrl',
   'sourceAuthUsername',
   'evidenceTrustPolicy',
   ...Object.keys(SECTIONS),
@@ -187,6 +188,30 @@ function assertFirstPartyUrls(firstPartySources, prefix) {
   }
 }
 
+/**
+ * The OPTIONAL `dataRootRepositoryUrl`: where the data root itself lives, in the canonical public HTTPS form
+ * and under `sourceRepositoryUrlPrefix` like a first-party repository. It names the record signer
+ * (the data root's reusable workflows); a data root that does not declare it simply cannot be named as one.
+ */
+function optionalDataRootRepositoryUrl(document, prefix) {
+  if (document.dataRootRepositoryUrl === undefined) {return {};}
+  const where = `${EDITION_WORKSPACE_CONFIG_FILE}: "dataRootRepositoryUrl"`;
+  let canonical;
+  try {
+    canonical = canonicalPublicHttpsRepositoryUrl(document.dataRootRepositoryUrl, where);
+    repositoryOwnerName(canonical, where);
+  } catch (err) {
+    throw new EditionWorkspaceConfigError(err.message);
+  }
+  if (canonical !== document.dataRootRepositoryUrl) {
+    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(document.dataRootRepositoryUrl)} is not in its canonical form (${canonical})`);
+  }
+  if (!isUnderSourcePrefix(canonical, prefix)) {
+    throw new EditionWorkspaceConfigError(`${where} ${JSON.stringify(canonical)} is not under sourceRepositoryUrlPrefix ${prefix}`);
+  }
+  return { dataRootRepositoryUrl: canonical };
+}
+
 /** Validate a parsed config document; returns the frozen, typed config. */
 export function parseEditionWorkspaceConfig(document) {
   if (document === null || typeof document !== 'object' || Array.isArray(document)) {
@@ -210,6 +235,7 @@ export function parseEditionWorkspaceConfig(document) {
     imageRegistry: requireString(document, 'imageRegistry', IMAGE_REGISTRY, '<host>/<namespace> with no scheme or trailing slash'),
     ...optionalChartSet(document),
     sourceRepositoryUrlPrefix,
+    ...optionalDataRootRepositoryUrl(document, sourceRepositoryUrlPrefix),
     sourceAuthUsername: requireSourceAuthUsername(document),
     evidenceTrustPolicy: requireEvidenceTrustPolicy(document),
   });

package/edition/edition-protocol.mjs

@@ -28,7 +28,7 @@ import { realpathSync } from 'node:fs';
 
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 
-/** The edition protocols this library interprets: version -> content digest. v10..v20 grow the kernel
+/** The edition protocols this library interprets: version -> content digest. v10..v27 grow the kernel
  * source closure only (entry subpaths and hashing unchanged), so one library speaks every row. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 9, contentDigest: '7cd6d760e7e7caaec3634a08c739debbdeeeaac4f1bad6791246a12f4f248e37' }),
@@ -41,6 +41,13 @@ export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 16, contentDigest: '2e65c280a399304ebb438e4e9829bcb4688f36a3c6a5e8b35b679cf69c689f55' }),
   Object.freeze({ version: 19, contentDigest: '66dab3dcf18c3a587f073808cc91165cc513eabb237b35439ff6cfe2b312b127' }),
   Object.freeze({ version: 20, contentDigest: '22c0e4ba6ee2771e91516ea78806117b5e3e60b76e085b9a9b98e993c1de79f8' }),
+  Object.freeze({ version: 21, contentDigest: 'f6364cf4830dcd15f82fb316ec9c0f0c11ffbe45262d97d8621242117d02f2b8' }),
+  Object.freeze({ version: 22, contentDigest: '566a0c37ee8b25c22bb9a5979190508e479c87593790b4a9e481ab1db8f7bcd1' }),
+  Object.freeze({ version: 23, contentDigest: '96735bd71236b4d0a2cef8a59c4a8d4f6919c6b5e54654c4b2b01e22b9880e04' }),
+  Object.freeze({ version: 24, contentDigest: '6ae70f55db789f95e194f623525b30ffedc21478ec17d246336b9a2783b6c0db' }),
+  Object.freeze({ version: 25, contentDigest: '79916e652836c7f6c31a7284c083c4f11249c6f21ef0b1bf79efc9dc23684d4a' }),
+  Object.freeze({ version: 26, contentDigest: '8d1dcfca5c59ff7b5eee6ea84fec3d9d62a48f3260f4ddb27b6665c25056f968' }),
+  Object.freeze({ version: 27, contentDigest: 'd4807f6464508c1abb32f7de9754f2e1f12cd7f2be5fbf939b6a5175c01dd90b' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */

package/edition/image-evidence.mjs

@@ -17,6 +17,7 @@ import {
 } from 'node:path';
 import { TextDecoder } from 'node:util';
 
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
 import { assertCanonicalDistributionId } from './distribution-paths.mjs';
 import { effectiveRepositoryPins, manifestSourcePins } from './edition-source-pins.mjs';
 import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
@@ -804,21 +805,10 @@ export function verifySigstoreEvidenceDescriptor({
         verifiedTrustedRootPath,
         '--bundle',
         verifiedBundlePath,
-        '--certificate-identity',
-        candidate.certificateIdentity,
-        '--certificate-oidc-issuer',
-        candidate.oidcIssuer,
+        ...certificateConstraintArgs(candidate, verifiedWorkflowSha),
         '--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'],

package/edition/kernel-signer-kind.mjs

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module';
+
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { kernelDistPath, kernelPackageDir } from './edition-workspace.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * The kind of signer this library produces and verifies: a keyless OIDC
+ * certificate, `SignerKind.OidcCertificate` of the built kernel. The producer
+ * inputs and the trust-policy rows the evidence verbs handle carry it.
+ */
+export function oidcCertificateSignerKind() {
+  assertKernelEditionProtocol(kernelPackageDir());
+  const { SignerKind } = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  const kind = SignerKind?.OidcCertificate;
+  if (typeof kind !== 'string' || kind.length === 0) {
+    throw new Error(
+      `The built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} does not export SignerKind.OidcCertificate; rebuild the kernel checkout.`,
+    );
+  }
+  return kind;
+}