@xemahq/xema 0.27.0 → 0.28.0

package/edition/image-delivery-entitlement-descriptor.mjs

@@ -0,0 +1,106 @@
+// `entitlement.json`: the file `xema edition evidence statement entitlement
+// accept` writes beside the signed statement, and the ONE reader of it
+// (`verify-evidence --entitlement`). Writer and reader share this module so the
+// shape is stated once.
+//
+// Every field but `evidence` is an UNAUTHENTICATED convenience for the operator
+// and for `verify-evidence`'s early refusals: the signed statement stays the
+// authority (`validateEntitlementStatementBinding`). The file names no workflow
+// SHA: the commit the entitlement's certificate is held to is stated by the
+// caller of the verifier (`--entitlement-workflow-sha`), never by the evidence.
+
+import { dirname, join } from 'node:path';
+
+export const ENTITLEMENT_DESCRIPTOR_FILE = 'entitlement.json';
+export const ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION = 2;
+
+const ENTITLEMENT_DESCRIPTOR_KEYS = Object.freeze([
+  'schemaVersion',
+  'distributionId',
+  'customerId',
+  'mode',
+  'targetRegistry',
+  'idempotencyKey',
+  'distributionStatementDigest',
+  'evidence',
+]);
+
+/** The document `accept` writes. `evidence` is the kernel Sigstore evidence descriptor of the signed statement. */
+export function entitlementDescriptorDocument({
+  distributionId,
+  customerId,
+  mode,
+  targetRegistry,
+  idempotencyKey,
+  distributionStatementDigest,
+  evidence,
+}) {
+  return {
+    schemaVersion: ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION,
+    distributionId,
+    customerId,
+    mode,
+    targetRegistry,
+    idempotencyKey,
+    distributionStatementDigest,
+    evidence,
+  };
+}
+
+/**
+ * Parse an `entitlement.json`: exactly the keys `accept` writes, at the one
+ * schema version, with `evidence` parsed by the kernel's Sigstore evidence
+ * descriptor schema. Any other shape is refused.
+ */
+export function parseEntitlementDescriptorDocument(raw, schemas) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} must be a JSON object`);
+  }
+  if (raw.schemaVersion !== ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} has schemaVersion ${JSON.stringify(raw.schemaVersion)}; ` +
+        `this verifier reads schemaVersion ${ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION} only (accept the entitlement again with this CLI)`,
+    );
+  }
+  const keys = Object.keys(raw).sort();
+  const expected = [...ENTITLEMENT_DESCRIPTOR_KEYS].sort();
+  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} must hold exactly the keys ${ENTITLEMENT_DESCRIPTOR_KEYS.join(', ')}; it holds ${keys.join(', ')}`,
+    );
+  }
+  for (const key of ['distributionId', 'customerId', 'mode', 'idempotencyKey', 'distributionStatementDigest']) {
+    if (typeof raw[key] !== 'string' || raw[key] === '') {
+      throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "${key}" must be a non-empty string`);
+    }
+  }
+  if (raw.targetRegistry !== null && (typeof raw.targetRegistry !== 'string' || raw.targetRegistry === '')) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "targetRegistry" must be null or a non-empty string`);
+  }
+  return { ...raw, evidence: schemas.SigstoreEvidenceDescriptorSchema.parse(raw.evidence) };
+}
+
+/**
+ * Refuse an `entitlement.json` that states another request than the one being
+ * verified. `expected` holds the caller's flags and the completeness statement
+ * digest the verifier has just verified.
+ */
+export function assertEntitlementDescriptorStates(document, expected) {
+  for (const key of ['distributionId', 'customerId', 'mode', 'targetRegistry', 'distributionStatementDigest']) {
+    if (document[key] !== expected[key]) {
+      throw new Error(
+        `${ENTITLEMENT_DESCRIPTOR_FILE} states ${key} ${JSON.stringify(document[key])}, ` +
+          `not the ${JSON.stringify(expected[key])} this verification was asked for`,
+      );
+    }
+  }
+}
+
+/**
+ * The evidence descriptor's paths are relative to the directory `accept` sealed
+ * (the one holding `entitlement.json`), which lies inside the evidence root the
+ * descriptor file itself was read from.
+ */
+export function entitlementEvidenceRoot(evidenceRoot, entitlementDescriptorPath) {
+  return dirname(join(evidenceRoot, entitlementDescriptorPath));
+}

package/edition/image-evidence.mjs

@@ -603,6 +603,14 @@ function assertEvidenceChannel(channel) {
  * The signers a policy authorizes for one predicate on ONE channel. Producer
  * evidence is further bound to the exact image repository the subject's
  * imageRef names (no prefix match).
+ *
+ * A signer belongs to one channel: the kernel policy schema, which every policy
+ * this plane loads is parsed by, holds a row's `githubWorkflow.ref` to the ref
+ * of its channel (`EVIDENCE_CHANNEL_REFS`) and its `certificateIdentity` to
+ * that ref, so no signer can be authorized on two channels. The signature
+ * therefore authenticates the channel: an edition descriptor that states the
+ * other channel selects signers whose certificates the evidence does not carry,
+ * or none at all.
  */
 function policyCandidates(policy, predicateType, channel, imageRepository) {
   return policy.policies.filter(

package/edition/lib.mjs

@@ -722,6 +722,7 @@ export async function loadKernelDistributionSchemas() {
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
+    SigstoreEvidenceDescriptorSchema,
     parsePlatformServiceSourceIndex,
     parseRuntimeImageSourceIndex,
     resolveRuntimeImagePlatforms,
@@ -798,6 +799,7 @@ export async function loadKernelDistributionSchemas() {
     typeof parseDistributionImageEvidenceSet !== 'function' ||
     typeof parseDistributionImageReplayState !== 'function' ||
     typeof parseSigstoreOfflineTrustPolicy !== 'function' ||
+    typeof SigstoreEvidenceDescriptorSchema?.parse !== 'function' ||
     typeof parsePlatformServiceSourceIndex !== 'function' ||
     typeof parseRuntimeImageSourceIndex !== 'function' ||
     typeof resolveRuntimeImagePlatforms !== 'function' ||
@@ -892,6 +894,7 @@ export async function loadKernelDistributionSchemas() {
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
+    SigstoreEvidenceDescriptorSchema,
     parsePlatformServiceSourceIndex,
     parseRuntimeImageSourceIndex,
     resolveRuntimeImagePlatforms,

package/edition/oras.mjs

@@ -173,7 +173,7 @@ function assertOrasVersion(bin, home) {
 /**
  * The oras digests the configured data root trusts: `trustedOrasBinaryDigests`
  * of its evidence-trust pin. `null` when the data root declares no evidence
- * trust at all (`evidenceTrustPolicy: {"required": false}` with no policy):
+ * trust at all (`evidenceTrustPolicy: null`):
  * such a data root has no reviewed pin to hold a binary to.
  */
 export function configuredOrasTrust() {

package/edition/produce-image-delivery-entitlement-evidence.mjs

@@ -28,6 +28,7 @@ import {
   dataRoot,
   isEntryModule,
 } from './edition-workspace.mjs';
+import { ENTITLEMENT_DESCRIPTOR_FILE, entitlementDescriptorDocument } from './image-delivery-entitlement-descriptor.mjs';
 import { canonicalJsonBytes, readCanonicalJsonFromRoot } from './image-evidence.mjs';
 import { serializeJson } from './lib.mjs';
 import { githubWorkflowSigner } from './produce-distribution-completeness-evidence.mjs';
@@ -38,7 +39,6 @@ import {
 } from './produce-image-source-evidence.mjs';
 import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
 
-const ENTITLEMENT_DESCRIPTOR_FILE = 'entitlement.json';
 const ENTITLEMENT_STATEMENT_PATH = 'entitlement/statement.json';
 const ENTITLEMENT_BUNDLE_PATH = 'entitlement/bundle.sigstore.json';
 
@@ -176,17 +176,17 @@ export function acceptImageDeliveryEntitlementEvidence(options) {
       const descriptor = acceptSignedEvidenceStatement({ ...signing, sealingRoot: sealing, runCosign });
       writeFileSync(
         join(sealing, ENTITLEMENT_DESCRIPTOR_FILE),
-        canonicalJsonBytes({
-          schemaVersion: 1,
-          distributionId: options.distributionId,
-          customerId: options.customerId,
-          mode: options.mode,
-          targetRegistry: options.targetRegistry,
-          idempotencyKey: options.idempotencyKey,
-          distributionStatementDigest: completenessStatementDigest,
-          signingWorkflowSha: options.signingWorkflowSha,
-          evidence: descriptor,
-        }),
+        canonicalJsonBytes(
+          entitlementDescriptorDocument({
+            distributionId: options.distributionId,
+            customerId: options.customerId,
+            mode: options.mode,
+            targetRegistry: options.targetRegistry,
+            idempotencyKey: options.idempotencyKey,
+            distributionStatementDigest: completenessStatementDigest,
+            evidence: descriptor,
+          }),
+        ),
         { flag: 'wx', mode: 0o644 },
       );
       return { outputDirectory, statement, descriptor, completenessStatementDigest };

package/edition/release-channel-guard.mjs

@@ -60,8 +60,18 @@ export function assertReleaseEditionTree(dir) {
  */
 export const RELEASE_COMPANION_FILES = Object.freeze([EDITION_CHART_SET_FILE]);
 
+/**
+ * The release locks an edition directory holds (the distribution and the
+ * authorization lock). A directory holding either IS a release edition: a
+ * develop resolve writes nothing into an editions tree, so a lock committed
+ * there was written by the release resolve.
+ */
+export function heldReleaseLocks(dir) {
+  return [EditionLockFile.Distribution, EditionLockFile.Authorization].filter((file) => existsSync(join(dir, file)));
+}
+
 function assertReleaseLockSet(dir) {
-  const held = [EditionLockFile.Distribution, EditionLockFile.Authorization].filter((file) => existsSync(join(dir, file)));
+  const held = heldReleaseLocks(dir);
   if (held.length === 0) {return;}
   const missing = RELEASE_COMPANION_FILES.filter((file) => !existsSync(join(dir, file)));
   if (missing.length > 0) {

package/edition/release-edition-artifact.mjs

@@ -131,10 +131,9 @@ async function run(argv, env) {
   const target = editionTarget(id, options['--registry'], options['--coordinate']);
   const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
   const locks = await readCommittedEdition(id);
+  // Refuses (EvidenceTrustRequiredError) unless the policy is ARMED on the
+  // release channel: a release artifact is never written not-armed.
   const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Release });
-  if (evidenceTrustPolicy === 'not-armed') {
-    console.warn('[edition-artifact] evidence trust policy: NOT ARMED — the descriptor records not-armed.');
-  }
   const outDir = resolve(options['--out']);
   writeEditionArtifact({
     outDir,

package/edition/verify-image-evidence.mjs

@@ -49,6 +49,11 @@ import {
   trustPolicyDigest,
   verifierDigests,
 } from './evidence-trust-pin.mjs';
+import {
+  assertEntitlementDescriptorStates,
+  entitlementEvidenceRoot,
+  parseEntitlementDescriptorDocument,
+} from './image-delivery-entitlement-descriptor.mjs';
 import { verifyAndAdvanceReplayState } from './image-evidence-replay-state.mjs';
 import {
   readCanonicalJsonFromRoot,
@@ -64,13 +69,14 @@ import { loadVerifierKernelSchemas } from './verifier-kernel-schemas.mjs';
 const USAGE =
   'usage: verify-image-evidence <distributionId> --evidence-root <dir> --descriptor <absolute-path> --state <absolute-path> ' +
   '--cosign <absolute-path> --git <absolute-path> [--evidence-set <relative-path>] [--json] ' +
-  '[--entitlement <relative-path> --customer <id> --mode <mode> [--target-registry <registry>]] ' +
+  '[--entitlement <relative-path> --entitlement-workflow-sha <40-hex git sha> --customer <id> --mode <mode> [--target-registry <registry>]] ' +
   '--data-root <dir> --editions-root <dir> --kernel <dir>';
 // The edition channel -> the kernel's evidence channel, stated once and explicitly.
 const EVIDENCE_CHANNEL_OF_EDITION_CHANNEL = Object.freeze({
   [EditionChannel.Release]: 'release',
   [EditionChannel.Develop]: 'develop',
 });
+const GIT_COMMIT_SHA = /^[a-f0-9]{40}$/;
 const DATA_ROOT_FILES = Object.freeze(['edition-workspace.json', 'runtime-image-source-index.json']);
 
 function requireOptionValue(args, index, flag) {
@@ -101,6 +107,7 @@ function parseArgs(args) {
     cosignBinary: null,
     gitBinary: null,
     entitlementDescriptorPath: null,
+    entitlementWorkflowSha: null,
     customerId: null,
     mode: null,
     targetRegistry: null,
@@ -118,6 +125,7 @@ function parseArgs(args) {
     else if (flag === '--cosign') {options.cosignBinary = value;}
     else if (flag === '--git') {options.gitBinary = value;}
     else if (flag === '--entitlement') {options.entitlementDescriptorPath = value;}
+    else if (flag === '--entitlement-workflow-sha') {options.entitlementWorkflowSha = value;}
     else if (flag === '--customer') {options.customerId = value;}
     else if (flag === '--mode') {options.mode = value;}
     else if (flag === '--target-registry') {options.targetRegistry = value;}
@@ -137,9 +145,12 @@ function parseArgs(args) {
     }
   }
   // An entitlement is verified whole or not at all: the descriptor names the
-  // signed statement, and the customer and mode are what it must be bound to.
+  // signed statement, the workflow SHA is the exact commit its certificate is
+  // held to (stated by the caller, never read from the evidence), and the
+  // customer and mode are what it must be bound to.
   const entitlementFlags = [
     ['--entitlement', options.entitlementDescriptorPath],
+    ['--entitlement-workflow-sha', options.entitlementWorkflowSha],
     ['--customer', options.customerId],
     ['--mode', options.mode],
   ];
@@ -150,7 +161,10 @@ function parseArgs(args) {
     );
   }
   if (stated.length === 0 && options.targetRegistry !== null) {
-    throw new Error('--target-registry needs --entitlement, --customer and --mode');
+    throw new Error('--target-registry needs --entitlement, --entitlement-workflow-sha, --customer and --mode');
+  }
+  if (options.entitlementWorkflowSha !== null && !GIT_COMMIT_SHA.test(options.entitlementWorkflowSha)) {
+    throw new Error('--entitlement-workflow-sha must be a 40-character lowercase hexadecimal git commit SHA');
   }
   if (options.entitlementDescriptorPath !== null && isAbsolute(options.entitlementDescriptorPath)) {
     throw new Error('--entitlement must be an evidence-root-relative path');
@@ -185,6 +199,7 @@ export const EDITION_EVIDENCE_VERIFICATION_SCHEMA = 'xema.edition-evidence-verif
  * What `--json` prints once the evidence is verified: the channel it was verified
  * on, the release sequence it proved, and the statementDigest (the digest of the verified in-toto statement, not of the image) of every statement verified
  * (producers by subject, then completeness, then the entitlement if one was asked for).
+ * `entitlementDescriptor` is the Sigstore evidence descriptor `entitlement.json` holds.
  */
 export function evidenceVerificationDocument({ distributionId, channel, evidenceSet, verified, entitlementDescriptor }) {
   const producers = evidenceSet.producerEvidence
@@ -350,19 +365,32 @@ export async function verifyEvidence({ argv, env, bundlePath }) {
           cosignBinary: options.cosignBinary,
           schemas,
         });
-        const entitlementDescriptor =
+        const entitlement =
           options.entitlementDescriptorPath === null
             ? null
-            : readCanonicalJsonFromRoot(
-                evidenceRoot,
-                options.entitlementDescriptorPath,
-                'delivery entitlement evidence descriptor',
+            : parseEntitlementDescriptorDocument(
+                readCanonicalJsonFromRoot(
+                  evidenceRoot,
+                  options.entitlementDescriptorPath,
+                  'delivery entitlement descriptor',
+                ),
+                schemas,
               );
+        if (entitlement !== null) {
+          assertEntitlementDescriptorStates(entitlement, {
+            distributionId: options.distributionId,
+            customerId: options.customerId,
+            mode: options.mode,
+            targetRegistry: options.targetRegistry,
+            distributionStatementDigest: result.completenessStatementDigest,
+          });
+        }
+        const entitlementDescriptor = entitlement === null ? null : entitlement.evidence;
         const entitlementStatement =
           entitlementDescriptor === null
             ? null
             : await verifyImageDeliveryEntitlement({
-                evidenceRoot,
+                evidenceRoot: entitlementEvidenceRoot(evidenceRoot, options.entitlementDescriptorPath),
                 descriptor: entitlementDescriptor,
                 policy: anchors.policy,
                 policyRoot: dataRoot(),
@@ -373,9 +401,9 @@ export async function verifyEvidence({ argv, env, bundlePath }) {
                 mode: options.mode,
                 targetRegistry: options.targetRegistry,
                 now: new Date(),
-                // The entitlement predicate carries no producer run, so there
-                // is no workflow SHA to demand and none is invented.
-                expectedWorkflowSha: undefined,
+                // The entitlement predicate carries no producer run: the commit
+                // its certificate is held to is the caller's statement.
+                expectedWorkflowSha: options.entitlementWorkflowSha,
                 // A nonce spent by a producer or completeness statement of
                 // this release cannot be reused by its entitlement.
                 consumedNonces: result.verifiedNonces,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:15b541996401a23867e6e902df97718dd508235377acf51ed81d915fd136d8d8"
+    "sourceDigest": "sha256:c33104cb26add433525e6447c931da38c0fc51a552b7f61f59b293734aeeb23c"
   }
 }