@xemahq/xema 0.27.0 → 0.29.0

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.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -51,6 +51,7 @@
     "@nestjs/platform-express": "^11.1.28",
     "@xemahq/biome-sdk": "^18.1.0",
     "@xemahq/biome-supply-chain": "^0.5.0",
+    "@xemahq/distribution-source-hash": "^0.3.0",
     "@xemahq/dsl": "^0.23.0",
     "@xemahq/identity-client": "^0.16.0",
     "@xemahq/contracts": "^0.76.0",
@@ -68,7 +69,6 @@
     "@types/jest": "^30.0.0",
     "@types/node": "25.2.3",
     "@xemahq/biome-host-api-client": "^0.3.31",
-    "@xemahq/distribution-source-hash": "^0.3.0",
     "@xemahq/eslint-config": "^0.9.2",
     "esbuild": "0.28.2",
     "eslint": "^9.39.4",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:15b541996401a23867e6e902df97718dd508235377acf51ed81d915fd136d8d8"
+    "sourceDigest": "sha256:a0dc6a3fdb7cce15b031dcd04476f19924d13d36924070b1527af1fa613b258e"
   }
 }