@xemahq/xema 0.55.0 → 0.56.0

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

@@ -4,7 +4,7 @@
 
 import { execFileSync } from 'node:child_process';
 
-import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { certificateConstraintArgs, certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
 import { COSIGN_ENV, decodeExactUtf8, sha256Digest, validatePinnedTrustedRoot } from './image-evidence.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
 import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
@@ -119,29 +119,85 @@ export async function fetchBundleProvenance({ clientFor, ociRef }) {
   return found[0];
 }
 
-const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
-
 /**
- * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
- * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
- * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
- * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ * The `<repository>@sha256:<hex>` a bundle reference names: a digest reference as it is, a tag reference resolved at
+ * the registry (the manifest the tag serves, its bytes verified against the digest the registry described).
  */
-export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+export async function bundleDigestRef({ clientFor, ociRef }) {
+  if (ociRef.includes('@')) {return ociRef;}
+  const colon = ociRef.lastIndexOf(':');
+  if (colon <= ociRef.lastIndexOf('/')) {
+    throw new Error(`bundle reference ${JSON.stringify(ociRef)} names neither a tag nor a digest`);
+  }
+  const name = ociRef.slice(0, colon);
+  const { authority, repository } = splitImageRef(name);
+  const { digest } = await clientFor(authority).getManifestByTag(repository, ociRef.slice(colon + 1));
+  return `${name}@${digest}`;
+}
+
+const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
+
+/** The cosign run of a registry verification: the trusted binary, the operator's registry credential (HOME / DOCKER_CONFIG). */
+function registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env }) {
   const root = validatePinnedTrustedRoot(policyRoot, policy);
-  const common = ['--offline', '--trusted-root', root.path, ...certificateConstraintArgs(row, workflowSha)];
   const environment = {
     ...COSIGN_ENV,
     ...(env.HOME === undefined ? {} : { HOME: env.HOME }),
     ...(env.DOCKER_CONFIG === undefined ? {} : { DOCKER_CONFIG: env.DOCKER_CONFIG }),
   };
-  const run = (command, args) => {
-    try {
-      execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], { env: environment, stdio: ['ignore', 'ignore', 'pipe'], timeout: REGISTRY_COSIGN_TIMEOUT_MS });
-    } catch (error) {
-      throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
-    }
+  return {
+    trustArgs: ['--offline', '--trusted-root', root.path],
+    run(command, args) {
+      try {
+        return execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], {
+          env: environment,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: REGISTRY_COSIGN_TIMEOUT_MS,
+        });
+      } catch (error) {
+        throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
+      }
+    },
   };
-  run('verify', [...common, ociRef]);
-  run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}
+
+/**
+ * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
+ * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
+ * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
+ * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ */
+export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const common = [...cosign.trustArgs, ...certificateConstraintArgs(row, workflowSha)];
+  cosign.run('verify', [...common, ociRef]);
+  cosign.run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}
+
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/u;
+
+/**
+ * The commit the row's workflow signed the bundle artifact at, as cosign states it: `cosign verify` under the row's
+ * identity, issuer, workflow repository and ref (no commit: it is what is asked), and the `githubWorkflowSha` claim of
+ * every signature cosign verified. Exactly one commit is required; none, or two, is refused. The caller then holds the
+ * signature AND the provenance to that commit with `verifyBundleOnRegistry`.
+ */
+export function verifiedBundleSignerCommit({ trustedCosign, policy, policyRoot, row, ociRef, env = process.env }) {
+  const cosign = registryCosign({ trustedCosign, policy, policyRoot, row, ociRef, env });
+  const output = cosign.run('verify', [...cosign.trustArgs, ...certificateIdentityArgs(row), '--output', 'json', ociRef]);
+  let verified;
+  try {
+    verified = JSON.parse(output);
+  } catch {
+    throw new Error(`cosign verify of ${ociRef} under row "${row.policyId}" printed no JSON list of verified signatures`);
+  }
+  const commits = [...new Set((Array.isArray(verified) ? verified : []).map((signature) => signature?.optional?.githubWorkflowSha))];
+  if (commits.length !== 1 || !WORKFLOW_SHA.test(String(commits[0]))) {
+    throw new Error(
+      `${ociRef} carries signatures by row "${row.policyId}" (${row.certificateIdentity}) stating ${commits.length} workflow commits ` +
+        `(${commits.map(String).join(', ')}); exactly one 40-hex commit is required`,
+    );
+  }
+  return commits[0];
 }

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

@@ -66,31 +66,56 @@ export function parseProvenanceStatement(value) {
 const readEvidenceFile = (root, path, label, maxBytes) => readBoundedNoFollowFile(root, path, label, maxBytes);
 
 /**
- * The trust-policy row `policyId` names, held to everything a third-party signer row must be: one row, the release
- * channel signed from refs/heads/main, the GitHub Actions issuer, the exact identity of its own workflow, and the
- * pinned repository and workflow. Throws naming the row and the field.
+ * A keyless signer row of `channel`, held to everything such a row must be: the channel signed from that channel's ref, the
+ * GitHub Actions issuer and the exact identity of its own workflow. Throws naming the row and the field.
  */
-export function thirdPartySignerRow({ policy, policyId, source, schemas, label }) {
-  const rows = policy.policies.filter((row) => row.policyId === policyId);
-  if (rows.length !== 1) {
-    throw new Error(`${label}: the trust policy has ${rows.length} rows with policyId "${policyId}"; exactly one is required`);
-  }
-  const [row] = rows;
-  const ref = schemas.EVIDENCE_CHANNEL_REFS[THIRD_PARTY_EVIDENCE_CHANNEL];
-  if (row.channel !== THIRD_PARTY_EVIDENCE_CHANNEL || row.githubWorkflow?.ref !== ref) {
+export function assertChannelSignerRow({ row, channel, schemas, label }) {
+  const ref = schemas.EVIDENCE_CHANNEL_REFS[channel];
+  if (row.channel !== channel || row.githubWorkflow?.ref !== ref) {
     throw new Error(
-      `${label}: row "${policyId}" is not a ${THIRD_PARTY_EVIDENCE_CHANNEL} row signed from ${ref} ` +
+      `${label}: row "${row.policyId}" is not a ${channel} row signed from ${ref} ` +
         `(channel ${JSON.stringify(row.channel)}, ref ${JSON.stringify(row.githubWorkflow?.ref)})`,
     );
   }
   if (row.oidcIssuer !== GITHUB_ACTIONS_OIDC_ISSUER) {
-    throw new Error(`${label}: row "${policyId}" oidcIssuer ${JSON.stringify(row.oidcIssuer)} is not ${GITHUB_ACTIONS_OIDC_ISSUER}`);
+    throw new Error(`${label}: row "${row.policyId}" oidcIssuer ${JSON.stringify(row.oidcIssuer)} is not ${GITHUB_ACTIONS_OIDC_ISSUER}`);
   }
   const { repository, path } = row.githubWorkflow;
   const identity = `https://github.com/${repository}/${path}@${ref}`;
   if (row.certificateIdentity !== identity) {
-    throw new Error(`${label}: row "${policyId}" certificateIdentity ${JSON.stringify(row.certificateIdentity)} is not the exact workflow identity ${identity}`);
+    throw new Error(`${label}: row "${row.policyId}" certificateIdentity ${JSON.stringify(row.certificateIdentity)} is not the exact workflow identity ${identity}`);
   }
+  return row;
+}
+
+/**
+ * The ONE `channel` row that signs the SLSA provenance of `repository`'s biome bundles, held to `assertChannelSignerRow`.
+ * None, or several, is refused naming the repository and the channel.
+ */
+export function bundleSignerRowFor({ policy, repository, channel, schemas, label }) {
+  const rows = policy.policies.filter(
+    (row) => row.channel === channel && row.predicateTypes?.includes(SLSA_PROVENANCE_V1) && row.githubWorkflow?.repository === repository,
+  );
+  if (rows.length !== 1) {
+    throw new Error(
+      `${label}: the trust policy has ${rows.length} ${channel} rows authorizing ${SLSA_PROVENANCE_V1} for ${repository}; exactly one bundle-signer row is required`,
+    );
+  }
+  return assertChannelSignerRow({ row: rows[0], channel, schemas, label });
+}
+
+/**
+ * The trust-policy row `policyId` names, held to everything a third-party signer row must be: one row, the release
+ * channel signed from refs/heads/main, the GitHub Actions issuer, the exact identity of its own workflow, and the
+ * pinned repository and workflow. Throws naming the row and the field.
+ */
+export function thirdPartySignerRow({ policy, policyId, source, schemas, label }) {
+  const rows = policy.policies.filter((row) => row.policyId === policyId);
+  if (rows.length !== 1) {
+    throw new Error(`${label}: the trust policy has ${rows.length} rows with policyId "${policyId}"; exactly one is required`);
+  }
+  const row = assertChannelSignerRow({ row: rows[0], channel: THIRD_PARTY_EVIDENCE_CHANNEL, schemas, label });
+  const { repository, path } = row.githubWorkflow;
   if (repository !== source.repository) {
     throw new Error(`${label}: row "${policyId}" signs for ${repository}, but the source is pinned to ${source.repository}`);
   }

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

@@ -16,8 +16,8 @@ import { bundleImageNames, fetchBundleManifest, fetchBundleProvenance, verifyBun
 import {
   PROVENANCE_BUNDLE_FILE,
   PROVENANCE_STATEMENT_FILE,
-  SLSA_PROVENANCE_V1,
   THIRD_PARTY_EVIDENCE_CHANNEL,
+  bundleSignerRowFor,
   digestOfOciRef,
   provenanceDirectoryForDigest,
   thirdPartySignerRow,
@@ -28,22 +28,6 @@ import { assertThirdPartyUniqueness } from './third-party-source-uniqueness.mjs'
 
 const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
 
-/** The one release-channel row that signs the biome bundle's provenance for `repository`. */
-function bundleSignerRow(policy, repository) {
-  const rows = policy.policies.filter(
-    (row) =>
-      row.channel === THIRD_PARTY_EVIDENCE_CHANNEL &&
-      row.predicateTypes.includes(SLSA_PROVENANCE_V1) &&
-      row.githubWorkflow?.repository === repository,
-  );
-  if (rows.length !== 1) {
-    throw new Error(
-      `the trust policy has ${rows.length} ${THIRD_PARTY_EVIDENCE_CHANNEL} rows authorizing ${SLSA_PROVENANCE_V1} for ${repository}; exactly one bundle-signer row is required`,
-    );
-  }
-  return rows[0];
-}
-
 /** The one release-channel row whose imageRepositories lists `imageRef`. */
 function imageSignerRow(policy, schemas, imageRef) {
   const rows = policyCandidates(policy, schemas.IMAGE_PRODUCER_PREDICATE_TYPE, THIRD_PARTY_EVIDENCE_CHANNEL, imageRef);
@@ -116,7 +100,7 @@ async function collectImage({ image, request, context, clientFor, services }) {
 export async function planThirdPartySourceWrite({ request, context, clientFor, withProducerWorkflowPin, dataRoot, verifyOnRegistry = verifyBundleOnRegistry }) {
   const { policy, schemas } = context;
   const repositoryUrl = `https://github.com/${request.repository}`;
-  const row = bundleSignerRow(policy, request.repository);
+  const row = bundleSignerRowFor({ policy, repository: request.repository, channel: THIRD_PARTY_EVIDENCE_CHANNEL, schemas, label: `third-party source "${request.name}" bundle signer` });
   const workflowPath = 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, producerWorkflow: { path: workflowPath } }, schemas, label: `third-party source "${request.name}" bundle signer` });

package/edition/trust-policy-arming.mjs

@@ -38,6 +38,13 @@
 // 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',
@@ -81,8 +88,11 @@ export function assessTrustPolicyArming(policy, schemas, channel, { consumesCata
       stages.push(['edition-catalogue', schemas.EDITION_CATALOGUE_PREDICATE_TYPE]);
     }
   }
-  const onChannel = policy.policies.filter((candidate) => candidate.channel === channel);
-  const authorized = stages.filter(([, predicateType]) => onChannel.some((candidate) => candidate.predicateTypes.includes(predicateType)));
+  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(
@@ -120,12 +130,13 @@ export function assessTrustPolicyArming(policy, schemas, channel, { consumesCata
     policy.policies.length === 0 &&
     policy.trustedCosignBinaryDigests.length === 0 &&
     policy.trustedGitBinaryDigests.length === 0;
-  // The channel states nothing while another channel does: its signers and the
-  // binary pins are that channel's arming, not half of this one's.
-  const anotherChannelOnly = onChannel.length === 0 && policy.policies.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 || anotherChannelOnly
+    : bootstrap || noStageRow
       ? TrustPolicyArmingState.UNARMED
       : TrustPolicyArmingState.PARTIAL;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -100,6 +100,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:c63c5439e820edd884875355490af818610cba7dce1d21eb8a7649438716b795"
+    "sourceDigest": "sha256:80acaaf576705b4a71ecd5e67794fea62c6fc834652a2830bbd03a2d855d2409"
   }
 }