@xemahq/edition-tooling 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,228 @@
+// The trusted writer of a third-party source pin (XEMA-1611 design section 3): `xema-edition index runtime-image-source
+// --trusted-write --third-party <name> ...`. It PLANS the write: reads the bundle and the evidence from the registry,
+// runs checks (a) to (e) on the exact bytes it would commit, and returns the files, the pin record and the candidate
+// index. `commitThirdPartySourceWrite` then writes them. The third-party repository is never cloned.
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { EvidenceSubjectKind, isAuthorityBound } from './authority-binding.mjs';
+import { REPIN_COMMAND } from './evidence-trust-pin.mjs';
+import { canonicalJsonBytes, evidenceDirectoryForDigest, sha256Digest } from './image-evidence.mjs';
+import { resolveImageSourceEvidenceReferrer } from './oci-image-source-evidence.mjs';
+import { PRODUCER_EVIDENCE_INDEX_FILE } from './producer-evidence-index-file.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { bundleImageNames, fetchBundleManifest, fetchClassicProvenanceBundle, verifyBundleOnRegistry } from './third-party-bundle-registry.mjs';
+import { declaredRunnerEnvironment } from './third-party-certificate-extensions.mjs';
+import {
+  PROVENANCE_BUNDLE_FILE,
+  PROVENANCE_STATEMENT_FILE,
+  THIRD_PARTY_EVIDENCE_CHANNEL,
+  bundleSignerRowFor,
+  digestOfOciRef,
+  provenanceDirectoryForDigest,
+  soleThirdPartyImageRow,
+  thirdPartySignerRow,
+  verifyThirdPartySourceEvidence,
+} from './third-party-source-evidence.mjs';
+import { THIRD_PARTY_SOURCE_PINS_FILE, THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION, loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import { assertThirdPartyUniqueness } from './third-party-source-uniqueness.mjs';
+
+const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+async function collectImage({ image, request, context, clientFor, services, channel }) {
+  const { schemas, expectedContractAuthority, policy } = context;
+  const label = `image ${image.imageRef}@${image.manifestDigest}`;
+  const row = soleThirdPartyImageRow({ policy, source: { repository: request.repository }, imageRef: image.imageRef, schemas, label });
+  const { authority } = splitImageRef(image.imageRef);
+  const skipped = [];
+  const evidence = await resolveImageSourceEvidenceReferrer({
+    client: clientFor(authority),
+    imageRepository: image.imageRef,
+    subjectDigest: image.manifestDigest,
+    schemas,
+    expectedContractAuthority,
+    authorityBound: isAuthorityBound(channel, EvidenceSubjectKind.ThirdParty),
+    onInvalidReferrer: (report) => skipped.push(`${report.artifactDigest}: ${report.reason}`),
+  });
+  if (evidence === null) {
+    throw new Error(`${label} has no valid image-source evidence referrer${skipped.length === 0 ? '' : ` (skipped: ${skipped.join('; ')})`}`);
+  }
+  if (evidence.records.length !== 1) {
+    throw new Error(`${label}: the evidence referrer carries ${evidence.records.length} statements; a third-party image has exactly one`);
+  }
+  const [record] = evidence.records;
+  const { source } = record.statement.predicate;
+  if (!services.has(source.id)) {
+    throw new Error(`${label}: its statement attests ${source.kind}:${source.id}, which is not an oci-image service of bundle ${request.bundleOciRef} (${[...services].join(', ')})`);
+  }
+  const directory = evidenceDirectoryForDigest(image.manifestDigest);
+  return {
+    pin: {
+      subjectKind: source.kind,
+      subjectId: source.id,
+      imageRef: image.imageRef,
+      manifestDigest: image.manifestDigest,
+      sourceTreeHash: source.sourceTreeHash,
+      sourceHashAlgorithm: source.sourceHashAlgorithm,
+      statementDigest: record.descriptor.statementDigest,
+      bundleDigest: record.descriptor.bundleDigest,
+      policyId: row.policyId,
+      producerWorkflow: row.githubWorkflow.path,
+    },
+    files: [
+      [`${directory}/${PRODUCER_EVIDENCE_INDEX_FILE}`, evidence.indexBytes],
+      [`${directory}/${record.descriptor.statementPath}`, record.statementBytes],
+      [`${directory}/${record.descriptor.bundlePath}`, record.bundleBytes],
+    ],
+  };
+}
+
+/**
+ * Plan the write of one third-party source. Throws on the first violated check; writes nothing to the data root.
+ *
+ * @param {object} options
+ * @param {{name, repository, repositoryId, repositoryOwnerId, sourceCommit, bundleOciRef, biomeId, runnerEnvironment?: 'self-hosted', images: {imageRef, manifestDigest}[]}} options.request
+ * @param {object} options.context `loadThirdPartySourceContext`
+ * @param {(authority: string) => object} options.clientFor the registry client of an authority
+ * @param {(request: {committedIndex: object, pin: {repository: string, workflowCommit: string}}) => object} options.withProducerWorkflowPin
+ *   the committed runtime image source index with the pin merged in, built by the index generator
+ * @param {string} options.dataRoot
+ * @param {string} options.channel the `EditionChannel` the pin is written for; develop does not hold a third-party statement to the contract authority
+ * @param {(options: object) => void} [options.verifyOnRegistry]
+ */
+export async function planThirdPartySourceWrite({ request, context, clientFor, withProducerWorkflowPin, dataRoot, channel, verifyOnRegistry = verifyBundleOnRegistry }) {
+  const { policy, schemas } = context;
+  const repositoryUrl = `https://github.com/${request.repository}`;
+  const row = bundleSignerRowFor({ policy, repository: request.repository, channel: THIRD_PARTY_EVIDENCE_CHANNEL, schemas, label: `third-party source "${request.name}" bundle signer` });
+  const signerWorkflow = row.githubWorkflow.path;
+  // The row must be exact (release channel, refs/heads/main, the GitHub issuer, its own workflow identity) before cosign runs.
+  thirdPartySignerRow({
+    policy,
+    policyId: row.policyId,
+    source: { repository: request.repository },
+    workflowPath: signerWorkflow,
+    schemas,
+    label: `third-party source "${request.name}" bundle signer`,
+  });
+
+  // (a) the bundle: the registry's signature, then its provenance attestation, under exactly this row; the provenance
+  // statement is the one cosign verified, never a registry read. Then the bundle bytes.
+  const { provenance: verifiedProvenance } = verifyOnRegistry({
+    trustedCosign: context.trustedCosign,
+    policy,
+    policyRoot: context.policyRoot,
+    row,
+    workflowSha: request.sourceCommit,
+    ociRef: request.bundleOciRef,
+  });
+  const { manifest } = await fetchBundleManifest({ clientFor, ociRef: request.bundleOciRef });
+  if (manifest?.xema?.id !== request.biomeId) {
+    throw new Error(`bundle ${request.bundleOciRef} declares xema.id ${JSON.stringify(manifest?.xema?.id)}, but --biome-id is ${JSON.stringify(request.biomeId)}`);
+  }
+  const sourceManifestHash = await schemas.computeBiomeSourceManifestHash(manifest);
+  const services = bundleImageNames(manifest);
+  // The verified envelope's certificate and tlog entry, as an offline-verifiable bundle; held below by the same offline
+  // verification `--check-third-party` repeats before a byte is committed.
+  const provenance = {
+    statementBytes: verifiedProvenance.statementBytes,
+    bundleBytes: await fetchClassicProvenanceBundle({ clientFor, ociRef: request.bundleOciRef, envelope: verifiedProvenance.envelope }),
+  };
+  const provenanceDirectory = provenanceDirectoryForDigest(digestOfOciRef(request.bundleOciRef));
+
+  // (b) each image's image-source/v2 evidence, as an OCI referrer of imageRef@digest.
+  const images = [];
+  const files = [
+    [`${provenanceDirectory}/${PROVENANCE_STATEMENT_FILE}`, provenance.statementBytes],
+    [`${provenanceDirectory}/${PROVENANCE_BUNDLE_FILE}`, provenance.bundleBytes],
+  ];
+  for (const image of request.images) {
+    const collected = await collectImage({ image, request, context, clientFor, services, channel });
+    images.push(collected.pin);
+    files.push(...collected.files);
+  }
+
+  const source = {
+    name: request.name,
+    repository: request.repository,
+    repositoryUrl,
+    repositoryId: request.repositoryId,
+    repositoryOwnerId: request.repositoryOwnerId,
+    sourceCommit: request.sourceCommit,
+    ...(request.runnerEnvironment === undefined ? {} : { runnerEnvironment: request.runnerEnvironment }),
+    bundle: {
+      ociRef: request.bundleOciRef,
+      biomeId: request.biomeId,
+      sourceManifestHash,
+      signerPolicyId: row.policyId,
+      signerWorkflow,
+      statementDigest: sha256Digest(provenance.statementBytes),
+      bundleDigest: sha256Digest(provenance.bundleBytes),
+    },
+    images: images.sort((left, right) => compare(left.imageRef, right.imageRef)),
+  };
+  const committed = loadThirdPartySourcePins(dataRoot).sources.filter((candidate) => candidate.name !== request.name);
+  const sources = [...committed, source].sort((left, right) => compare(left.name, right.name));
+
+  // (e) uniqueness, over the pins as they would be committed.
+  assertThirdPartyUniqueness({ sources, policy, runtimeSourceIndex: context.runtimeSourceIndex, biomeIndex: context.biomeIndex, platformServiceIndex: context.platformServiceIndex });
+
+  // (a) offline over the exact bytes to commit, (b) to (d): the very verification `--check-third-party` repeats.
+  const candidateIndex = schemas.parseRuntimeImageSourceIndex(
+    withProducerWorkflowPin({ committedIndex: context.runtimeSourceIndex, pin: { repository: request.repository, workflowCommit: request.sourceCommit } }),
+  );
+  const staging = mkdtempSync(join(tmpdir(), 'xema-third-party-write-'));
+  try {
+    for (const [path, bytes] of files) {
+      const target = join(staging, path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, bytes, { flag: 'wx' });
+    }
+    verifyThirdPartySourceEvidence({ source, evidenceRoot: staging, context: { ...context, runtimeSourceIndex: candidateIndex }, channel });
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  return { source, sources, files, candidateIndex };
+}
+
+function writeNewOrIdentical(dataRoot, path, bytes) {
+  const target = join(dataRoot, path);
+  try {
+    writeFileSync(target, bytes, { flag: 'wx', mode: 0o644 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') {throw error;}
+    if (!readFileSync(target).equals(bytes)) {
+      throw new Error(`${path} already exists with different bytes; evidence is content-addressed and is never overwritten`);
+    }
+  }
+}
+
+/**
+ * Write a planned source: the evidence files (content-addressed, never overwritten), then the pin file, then the
+ * index. The evidence trust pin is NOT repinned: reviewing the pin file and running `xema-edition repin-evidence-trust`
+ * is the intended next step, and until then the pin load refuses.
+ *
+ * @returns {string} the next step to print
+ */
+export function commitThirdPartySourceWrite({ dataRoot, plan, indexPath, indexText }) {
+  for (const [path, bytes] of plan.files) {
+    mkdirSync(dirname(join(dataRoot, path)), { recursive: true });
+    writeNewOrIdentical(dataRoot, path, bytes);
+  }
+  writeFileSync(
+    join(dataRoot, THIRD_PARTY_SOURCE_PINS_FILE),
+    canonicalJsonBytes({ schemaVersion: THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION, sources: plan.sources }),
+  );
+  writeFileSync(indexPath, indexText);
+  const runner = declaredRunnerEnvironment(plan.source);
+  const runnerDeclaration =
+    plan.source.runnerEnvironment === undefined
+      ? `runnerEnvironment ${runner} (undeclared)`
+      : `runnerEnvironment ${runner} (DECLARED: the reviewer must verify, at ${plan.source.sourceCommit}, that every signer workflow of ` +
+        `${plan.source.repository} pins runs-on to the dedicated signing runner label; no check here reads runs-on)`;
+  return (
+    `pinned third-party source "${plan.source.name}" (${plan.source.repository}@${plan.source.sourceCommit}, ${plan.source.images.length} image(s), ${runnerDeclaration}); ` +
+    `run \`${REPIN_COMMAND}\` after reviewing ${THIRD_PARTY_SOURCE_PINS_FILE}: the evidence trust pin does not yet record it, so the pin load refuses until then`
+  );
+}

package/edition/third-party-subjects.mjs

@@ -0,0 +1,128 @@
+// Third-party OCI biomes on the resolve side (XEMA-1611 design section 4).
+//
+// A biome from an organisation outside the vendor fleet reaches an edition as a lock row with NO `source` (the lock's
+// `LockedBiomeSource` is git-only), an OCI `bundleSource` and `origin: third-party`. That triple is the whole key; the
+// pin file (`third-party-source-pins.json`, written only by the trusted writer) is what the row is then held to. The
+// image subjects of such a row take `imageRef`, `sourceCommit` and `contentHash` from the pin and are never built,
+// hashed or probed by this plane: there is no checkout to hash.
+//
+// `contentHash` of such a subject is the PUBLISHER'S statement (`sourceTreeHash` of its image-source evidence), never
+// a hash this plane computed. It is therefore labelled `contentHash (publisher-attested)` wherever it is printed and
+// is not used as an image tag, a cache key or a reproducibility check by any path that serves third-party subjects.
+
+import { loadKernelBiomeContracts } from './lib.mjs';
+
+export const PUBLISHER_ATTESTED_LABEL = 'publisher-attested';
+
+export const OCI_BUNDLE_SOURCE_KIND = 'oci';
+
+const hasOciBundleSource = (row) => row.bundleSource?.kind === OCI_BUNDLE_SOURCE_KIND;
+const isThirdPartyOrigin = (row) => row.origin === loadKernelBiomeContracts().BiomeOrigin.ThirdParty;
+
+/**
+ * The lock key of a third-party OCI biome: no `source`, an OCI `bundleSource`, `origin: third-party`.
+ * A lock row and a walked index entry both carry these fields; an index entry's `source` is the walk's stamp, so it
+ * is dropped by the caller that tests an entry (`isThirdPartyOciEntry`).
+ */
+export const isThirdPartyOciRow = (row) => row.source === undefined && hasOciBundleSource(row) && isThirdPartyOrigin(row);
+
+/** A walked index entry that is a third-party OCI biome: its `source` is the walk's stamp, not a lock source. */
+export const isThirdPartyOciEntry = (entry) => hasOciBundleSource(entry) && isThirdPartyOrigin(entry);
+
+/**
+ * Refuse an OCI `bundleSource` on a row whose origin is not third-party: only a third-party biome is pulled from an OCI
+ * bundle by digest, so the vendor's origin on such a row would place an unevidenced bundle in the vendor's trust domain.
+ * A row drawn from a git `source` is not this key and carries no OCI `bundleSource` at all: resolve omits the manifest's
+ * (it names a release artifact not built from the pinned commit), and a lock stating one is refused (`locked-bundle-signer.mjs`).
+ */
+export function assertOciBundleSourceOrigin(row, label) {
+  if (row.source === undefined && hasOciBundleSource(row) && !isThirdPartyOrigin(row)) {
+    throw new Error(
+      `${label} carries an OCI bundleSource (${row.bundleSource.ociRef}) but its origin is "${row.origin}": an OCI ` +
+        `biome bundle is admitted only as origin "${loadKernelBiomeContracts().BiomeOrigin.ThirdParty}", with a pin of the data root's third-party source pins`,
+    );
+  }
+}
+
+/**
+ * The third-party source pin a third-party OCI row is held to, by the row's `repo` (the pinned repository). Refuses a
+ * row with no pin (naming why the data root has none when it has none), a pin for another biome, another bundle
+ * reference or another manifest hash, and a pin the distribution does not declare as an `oci` source of that name.
+ *
+ * @param {{row: object, declaredSources: readonly object[]|undefined, pins: {sources: readonly object[], reason: string|null, byRepository: (repository: string) => object|undefined}|undefined, label: string}} options
+ */
+export function thirdPartyPinForRow({ row, pins, declaredSources, label }) {
+  if (pins === undefined) {
+    throw new Error(`${label} is a third-party OCI biome, but this resolve was given no third-party source pins to hold it to`);
+  }
+  const pin = pins.byRepository(row.repo);
+  if (pin === undefined) {
+    throw new Error(
+      `${label} is a third-party OCI biome with neither a source nor a pin: ${pins.reason ?? `no third-party source pin names repository "${row.repo}"`}`,
+    );
+  }
+  if (row.id !== pin.bundle.biomeId) {
+    throw new Error(`${label} has biome id "${row.id}", but the third-party pin "${pin.name}" is for biome "${pin.bundle.biomeId}"`);
+  }
+  if (row.bundleSource.ociRef !== pin.bundle.ociRef) {
+    throw new Error(`${label} names bundle ${row.bundleSource.ociRef}, but the third-party pin "${pin.name}" pins ${pin.bundle.ociRef}`);
+  }
+  if (row.sourceManifestHash !== pin.bundle.sourceManifestHash) {
+    throw new Error(
+      `${label} has sourceManifestHash ${row.sourceManifestHash}, but the third-party pin "${pin.name}" pins ${pin.bundle.sourceManifestHash}`,
+    );
+  }
+  if (!Array.isArray(declaredSources) || !declaredSources.some((source) => source.kind === OCI_BUNDLE_SOURCE_KIND && source.name === pin.name)) {
+    throw new Error(`${label} is drawn from the third-party pin "${pin.name}", which the distribution does not declare as a sources[] entry of kind "${OCI_BUNDLE_SOURCE_KIND}"`);
+  }
+  return pin;
+}
+
+/**
+ * The image subjects of one third-party OCI row, from its pin and nothing else: one per service and runtime
+ * component the row ships (a worker that runs its sibling's image has none). Every pinned image must be one of them and
+ * every shipped image must be pinned, so the pin and the lock describe the same images.
+ *
+ * `contentHash` is the publisher's `sourceTreeHash` (publisher-attested); `sourceCommit` is the pin's.
+ */
+export function thirdPartySubjectCandidates({ row, pin, enums, requiredPlatforms, label }) {
+  if (row.target === 'web') {
+    throw new Error(`${label} is a third-party OCI biome with target "web": a bundled web biome of a third party is not admitted (it has no pinned image)`);
+  }
+  const sharedImageWorkers = new Set(Object.keys(row.workerImages ?? {}));
+  const wanted = [
+    ...(row.services ?? []).filter((service) => !sharedImageWorkers.has(service)).map((id) => [enums.RuntimeImageSubjectKind.Service, id]),
+    ...(row.runtimeComponents ?? []).map((id) => [enums.RuntimeImageSubjectKind.RuntimeComponent, id]),
+  ];
+  const byKey = new Map(pin.images.map((image) => [`${image.subjectKind}\0${image.subjectId}`, image]));
+  const used = new Set();
+  const candidates = wanted.map(([kind, id]) => {
+    const image = byKey.get(`${kind}\0${id}`);
+    if (image === undefined) {
+      throw new Error(`${label} ships ${kind} "${id}", which the third-party pin "${pin.name}" pins no image for`);
+    }
+    used.add(`${kind}\0${id}`);
+    return {
+      kind,
+      id,
+      imageRef: image.imageRef,
+      repo: row.repo,
+      path: row.path,
+      sourceCommit: pin.sourceCommit,
+      sourceManifestHash: row.sourceManifestHash,
+      requiredPlatforms,
+      owners: [{ kind: enums.RuntimeImageOwnerKind.Biome, biomeId: row.id }],
+      contentHash: image.sourceTreeHash,
+    };
+  });
+  const unused = [...byKey.keys()].filter((key) => !used.has(key));
+  if (unused.length > 0) {
+    throw new Error(
+      `the third-party pin "${pin.name}" pins image(s) ${unused.map((key) => key.replace('\0', ':')).join(', ')} that ${label} does not ship`,
+    );
+  }
+  return candidates;
+}
+
+/** A third-party subject's content hash, as every CLI output prints it. */
+export const attestedContentHash = (subject) => `contentHash (${PUBLISHER_ATTESTED_LABEL}) ${subject.contentHash}`;

package/edition/trust-policy-arming-verb.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// `xema-edition arming`: is the data root's declared evidence trust policy ARMED
+// on one channel?
+//
+// usage: xema-edition arming --channel <release|develop> --data-root <dir> --kernel <dir>
+// stdout: {"channel":"<channel>","state":"armed|unarmed|partial","unmet":["…"]}
+// exit:   0 only when the state is armed; 1 for any other state (each unmet
+//         entry on stderr) or a policy that does not hold to its pin; 2 for a
+//         usage error. A data root that declares no policy is `unarmed`.
+// It reads the policy the way `xema-edition check` does and never writes.
+
+import { EditionChannel, parseChannelArgs } from './edition-channel.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { assessDeclaredTrustPolicyArming } from './evidence-trust-policy.mjs';
+import { TrustPolicyArmingState } from './trust-policy-arming.mjs';
+
+export const ARMING_USAGE = `usage: xema-edition arming --channel <${Object.values(EditionChannel).join('|')}> --data-root <dir> --kernel <dir>`;
+
+/** The process exit codes of the verb. */
+export const ArmingExit = Object.freeze({ Armed: 0, NotArmed: 1, Usage: 2 });
+
+/**
+ * Judge the configured data root's policy on `channel`, writing the one JSON
+ * line to `stdout` and each unmet entry to `stderr`. Returns the exit code.
+ */
+export async function runArming({ channel, locateVerifier, stdout = process.stdout, stderr = process.stderr }) {
+  let verdict;
+  try {
+    verdict = await assessDeclaredTrustPolicyArming({ channel, locateVerifier });
+  } catch (error) {
+    stderr.write(`arming: ${error.message}\n`);
+    return ArmingExit.NotArmed;
+  }
+  const { state, unmet } = verdict;
+  stdout.write(`${JSON.stringify({ channel, state, unmet })}\n`);
+  if (state === TrustPolicyArmingState.ARMED) {return ArmingExit.Armed;}
+  for (const entry of unmet) {stderr.write(`${entry}\n`);}
+  return ArmingExit.NotArmed;
+}
+
+async function main() {
+  let channel;
+  try {
+    const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+    ({ channel } = parseChannelArgs(rest));
+  } catch (error) {
+    process.stderr.write(`arming: ${error.message}\n${ARMING_USAGE}\n`);
+    process.exitCode = ArmingExit.Usage;
+    return;
+  }
+  process.exitCode = await runArming({ channel });
+}
+
+if (isEntryModule(import.meta.url)) {
+  await main();
+}

package/edition/trust-policy-arming.mjs

@@ -0,0 +1,144 @@
+// Arming assertion for the offline Sigstore trust policy.
+//
+// The policy a data root declares (`evidenceTrustPolicy`) is schema-valid while
+// authorizing nobody: `policies`, `trustedCosignBinaryDigests` and
+// `trustedGitBinaryDigests` all default to `[]` and the zod schema has no
+// `.min(1)` on any of them. So the file parses green while the delivery plane
+// remains deliberately disabled. That is a valid bootstrap state only while all
+// three authority collections are empty. A partially populated policy is
+// neither disabled nor usable and must fail `xema-edition check`; delivery
+// itself always requires the fully armed state.
+//
+// It is deliberately not a lint of taste. Each requirement below names a place
+// where an empty list makes verification impossible, not merely weaker:
+//
+//   policies[]                  -> `image-evidence.mjs` throws "offline trust
+//                                 policy authorizes no signer for <predicate>
+//                                 on channel <channel>" before any cosign call.
+//   trustedCosignBinaryDigests  -> `trusted-executable.mjs` compares the cosign
+//                                 binary digest with `[].includes(...)`, which
+//                                 is false for every possible binary.
+//   trustedGitBinaryDigests     -> same, for the git binary that pins the
+//                                 graded checkouts.
+//
+// THE REQUIRED RELEASE ROWS ARE ONE RULE: the edition-catalogue (E4) predicate iff the edition consumes a catalogue
+// (`consumesCatalogue`: a customer edition does, a vendor edition does not), plus the image producer, distribution
+// completeness and delivery entitlement predicates. The same function judges the data root before the catalogue's
+// kernel is adopted (inside the pinned verifier bundle, with its own embedded kernel) and after it (descriptorEvidenceTrust).
+//
+// The three predicate types are checked separately because a policy can be
+// non-empty and still be unarmed for a stage: the verifier resolves candidates
+// per predicate type, so authorizing only the producer identity leaves the
+// completeness and entitlement stages throwing the same "authorizes no signer"
+// at delivery time - armed-looking, and inert exactly where it matters.
+//
+// ARMING IS JUDGED FOR ONE CHANNEL: the channel of the edition being checked,
+// sealed or verified. A release verification is only ever satisfied by a
+// release signer and a develop one by a develop signer, so the signers of one
+// channel neither arm nor disarm the other: a policy that authorizes the three
+// stages on the release channel and pins both binaries is ARMED for a release
+// edition whatever it says about develop.
+//
+// ONLY A STAGE ROW ARMS A CHANNEL: a row counts toward a channel's arming when it
+// authorizes one of the stage predicates judged here. A bundle-signer row (SLSA
+// provenance of a third-party bundle, e.g. the develop row of a git-sourced
+// biome) authorizes bundle verification and arms no stage, so a channel whose
+// only rows are bundle signers is UNARMED, exactly like a channel with no row.
+// One stage row on the channel still makes it PARTIAL until every stage is met.
+
+export const TrustPolicyArmingState = Object.freeze({
+  ARMED: 'armed',
+  UNARMED: 'unarmed',
+  PARTIAL: 'partial',
+});
+
+/** Arming has no channel-less answer: `channel` is one of the kernel's evidence channels. */
+export function assertArmingChannel(schemas, channel) {
+  if (!schemas.EVIDENCE_CHANNELS.includes(channel)) {
+    throw new Error(
+      `trust-policy arming is judged for one channel; got ${JSON.stringify(channel)}, expected ${schemas.EVIDENCE_CHANNELS.join(' | ')}`,
+    );
+  }
+}
+
+/**
+ * Assess whether a parsed trust policy can authorize anything on `channel`.
+ *
+ * Returns `{ state, armed, unmet }`. `unmet` is empty exactly when `armed` is
+ * true. `unarmed` means the channel has no signer at all in a policy that is
+ * otherwise coherent: the exact, explicit bootstrap state where every authority
+ * collection is empty, or a policy whose signers all belong to another channel.
+ * Anything else that is not armed is `partial`. Each unmet entry names the
+ * field and what makes verification impossible, so the failure is actionable
+ * without reading the verifier.
+ */
+export function assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue = false } = {}) {
+  assertArmingChannel(schemas, channel);
+  const unmet = [];
+  const stages = [
+    ['image-producer', schemas.IMAGE_PRODUCER_PREDICATE_TYPE],
+    ['distribution-completeness', schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE],
+    ['delivery-entitlement', schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE],
+  ];
+  if (consumesCatalogue) {
+    // A kernel that states no E4 predicate cannot arm a catalogue consumer: an unmet entry, never a skip.
+    if (typeof schemas.EDITION_CATALOGUE_PREDICATE_TYPE !== 'string') {
+      unmet.push('this kernel states no edition-catalogue predicate (EDITION_CATALOGUE_PREDICATE_TYPE), so a catalogue consumer cannot be armed against it.');
+    } else {
+      stages.push(['edition-catalogue', schemas.EDITION_CATALOGUE_PREDICATE_TYPE]);
+    }
+  }
+  const stagePredicateTypes = stages.map(([, predicateType]) => predicateType);
+  const stageRows = policy.policies.filter(
+    (candidate) => candidate.channel === channel && candidate.predicateTypes.some((predicateType) => stagePredicateTypes.includes(predicateType)),
+  );
+  const authorized = stages.filter(([, predicateType]) => stageRows.some((candidate) => candidate.predicateTypes.includes(predicateType)));
+
+  if (policy.policies.length === 0) {
+    unmet.push(
+      'policies[] is empty — no signer identity is authorized, so ' +
+        'verifySigstoreEvidenceDescriptor throws "offline trust policy ' +
+        'authorizes no signer" for every predicate before reading any bundle.',
+    );
+  } else {
+    for (const [stage, predicateType] of stages.filter((candidate) => !authorized.includes(candidate))) {
+      unmet.push(
+        `no policy authorizes the ${stage} predicate ${predicateType} on channel "${channel}" — ` +
+          `that stage of a ${channel} delivery would still throw "authorizes no signer" ` +
+          'while the policy reads as armed.',
+      );
+    }
+  }
+
+  if (policy.trustedCosignBinaryDigests.length === 0) {
+    unmet.push(
+      'trustedCosignBinaryDigests[] is empty — prepareDigestPinnedExecutable ' +
+        'tests membership with [].includes(digest), which is false for every ' +
+        'cosign binary, so no evidence can be verified on any host.',
+    );
+  }
+
+  if (policy.trustedGitBinaryDigests.length === 0) {
+    unmet.push(
+      'trustedGitBinaryDigests[] is empty — the same membership test rejects ' +
+        'every git binary, so no verified release checkout can be established.',
+    );
+  }
+
+  const armed = unmet.length === 0;
+  const bootstrap =
+    policy.policies.length === 0 &&
+    policy.trustedCosignBinaryDigests.length === 0 &&
+    policy.trustedGitBinaryDigests.length === 0;
+  // The channel has no stage row while the policy has rows (another channel's,
+  // or bundle signers): those rows and the binary pins are not half of this
+  // channel's arming.
+  const noStageRow = stageRows.length === 0 && policy.policies.length > 0;
+  const state = armed
+    ? TrustPolicyArmingState.ARMED
+    : bootstrap || noStageRow
+      ? TrustPolicyArmingState.UNARMED
+      : TrustPolicyArmingState.PARTIAL;
+
+  return { state, armed, unmet };
+}

package/edition/trust-policy-image-ownership.mjs

@@ -0,0 +1,85 @@
+// Who may name which image repository in the evidence trust policy (XEMA-1611 design section 3(e)).
+//
+// Checked when the declared policy is LOADED, so every consumer of the policy sees it:
+//   (a) an `imageRepositories` entry listed by rows whose `githubWorkflow.repository` OWNERS differ is
+//       refused: one repository, one publisher;
+//   (b) a row whose owner is not a first-party owner and that names a first-party namespace
+//       (`<registry>/<first-party owner>/<any>`) is refused.
+// First-party owners are the owners of the runtime-image-source index `repositoryPins` URLs, plus the kernel scope owner.
+
+import { KERNEL_PACKAGE_NAME } from './kernel-package.mjs';
+
+/**
+ * The vendor's publishing owner: the npm scope of the kernel package (`@<scope>/contracts`), read from the package name
+ * the CLI already pins, not written here. It is a first-party owner on purpose, beside the owners of the index's
+ * `repositoryPins`: the vendor publishes its kernel-scoped images under that owner, which no repository pin names, so
+ * without it a vendor row for them would be refused by rule (b) as a third party.
+ */
+export const KERNEL_SCOPE_OWNER = KERNEL_PACKAGE_NAME.replace(/^@/u, '').split('/')[0];
+
+/** The lowercase owners of the `repositoryPins[].repositoryUrl` entries of a parsed runtime image source index, plus the kernel scope owner. */
+export function firstPartyOwnersFromIndex(indexDocument) {
+  const pins = indexDocument?.repositoryPins;
+  if (!Array.isArray(pins)) {
+    throw new Error('runtime image source index has no repositoryPins array to derive the first-party owners from');
+  }
+  const owners = new Set([KERNEL_SCOPE_OWNER]);
+  for (const pin of pins) {
+    let url;
+    try {
+      url = new URL(pin?.repositoryUrl);
+    } catch {
+      throw new Error(`runtime image source index repositoryPins entry ${JSON.stringify(pin?.repo)} has no parsable repositoryUrl`);
+    }
+    const owner = url.pathname.split('/').filter(Boolean)[0];
+    if (owner === undefined) {
+      throw new Error(`runtime image source index repositoryUrl ${url.href} names no owner`);
+    }
+    owners.add(owner.toLowerCase());
+  }
+  return owners;
+}
+
+/**
+ * Whether an image repository sits in a first-party namespace: `<registry>/<first-party owner>/<any>`, an owner being
+ * one of `firstPartyOwners` (the data root's own, from `firstPartyOwnersFromIndex`). The registry is whatever the first
+ * path segment is; no registry or organisation is named here.
+ */
+export function isFirstPartyImageNamespace(imageRepository, firstPartyOwners) {
+  const segments = imageRepository.toLowerCase().split('/');
+  return segments.slice(1, -1).some((segment) => firstPartyOwners.has(segment));
+}
+
+const rowOwner = (row) => row.githubWorkflow?.repository?.split('/')[0]?.toLowerCase();
+
+/**
+ * Refuse a policy that breaks (a) or (b). `firstPartyOwners` is `null` when the data root has no runtime image source
+ * index (a customer data root): (b) cannot be judged there and is not applied; (a) always is.
+ *
+ * @param {{policy: {policies: object[]}, firstPartyOwners: Set<string>|null}} options
+ */
+export function assertTrustPolicyImageOwnership({ policy, firstPartyOwners }) {
+  const ownersByRepository = new Map();
+  for (const row of policy.policies) {
+    const owner = rowOwner(row);
+    if (owner === undefined || !Array.isArray(row.imageRepositories)) {
+      continue;
+    }
+    for (const imageRepository of row.imageRepositories) {
+      const seen = ownersByRepository.get(imageRepository);
+      if (seen !== undefined && seen.owner !== owner) {
+        throw new Error(
+          `evidence trust policy: image repository ${imageRepository} is listed by rows of two publishers ` +
+            `(${seen.policyId} owned by ${seen.owner}, ${row.policyId} owned by ${owner}); one image repository has one publisher`,
+        );
+      }
+      ownersByRepository.set(imageRepository, { owner, policyId: row.policyId });
+      if (firstPartyOwners !== null && !firstPartyOwners.has(owner) && isFirstPartyImageNamespace(imageRepository, firstPartyOwners)) {
+        throw new Error(
+          `evidence trust policy: row ${row.policyId} (owner ${owner}, not a first-party owner) names image repository ` +
+            `${imageRepository} in a first-party namespace (<registry>/<first-party owner>/<any>)`,
+        );
+      }
+    }
+  }
+}