@xemahq/xema 0.26.0 → 0.28.0

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

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// The image delivery entitlement statement: one customer's entitlement to one
+// sealed evidence set.
+//
+//   xema edition evidence statement entitlement stage|accept …
+//
+// `stage` writes the canonical statement into a NEW staging directory and
+// prints the signing plan; the caller signs it (`cosign attest-blob`);
+// `accept` re-derives the statement from the same flags, refuses staged bytes
+// that differ, verifies the signed bundle with cosign against the declared
+// signer, writes `entitlement.json` and seals the output (built from the
+// re-derived files, never renamed from the staging). This module never signs and never requests an OIDC token.
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import {
+  acceptSignedEvidenceStatement,
+  assertPinnedCosignVersion,
+  buildImageDeliveryEntitlementStatement,
+  loadPinnedTrustPolicy,
+  parseEvidenceCliFlags,
+  stageEvidenceStatement,
+} from './distribution-evidence-set.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  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';
+import {
+  assertGitHubProducerContext,
+  createCosignVerifier,
+  loadProducerKernelSchemas,
+} from './produce-image-source-evidence.mjs';
+import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+
+const ENTITLEMENT_STATEMENT_PATH = 'entitlement/statement.json';
+const ENTITLEMENT_BUNDLE_PATH = 'entitlement/bundle.sigstore.json';
+
+/**
+ * Read the completeness statement digest of an ASSEMBLED evidence set.
+ *
+ * The set is parsed through the kernel schema first: an entitlement must never
+ * be issued against a document that the verifier would not accept as an
+ * evidence set in the first place.
+ */
+export function readCompletenessStatementDigest({
+  evidenceRoot,
+  distributionId,
+  schemas,
+  evidenceSetPath = 'evidence-set.json',
+}) {
+  const evidenceSet = schemas.parseDistributionImageEvidenceSet(
+    readCanonicalJsonFromRoot(
+      evidenceRoot,
+      evidenceSetPath,
+      'distribution image evidence set',
+    ),
+  );
+  if (evidenceSet.distributionId !== distributionId) {
+    throw new Error(
+      `evidence set "${evidenceSet.distributionId}" does not match requested distribution "${distributionId}"`,
+    );
+  }
+  return {
+    evidenceSet,
+    completenessStatementDigest: evidenceSet.completeness.statementDigest,
+  };
+}
+
+
+function deriveEntitlement(options) {
+  const { completenessStatementDigest } = readCompletenessStatementDigest({
+    evidenceRoot: options.evidenceRoot,
+    distributionId: options.distributionId,
+    schemas: options.schemas,
+  });
+  const statement = buildImageDeliveryEntitlementStatement({
+    distributionId: options.distributionId,
+    completenessStatementDigest,
+    customerId: options.customerId,
+    mode: options.mode,
+    targetRegistry: options.targetRegistry,
+    idempotencyKey: options.idempotencyKey,
+    runId: options.runId,
+    runAttempt: options.runAttempt,
+    issuedAt: options.issuedAt,
+    expiresAt: options.expiresAt,
+    maxTtlSeconds: options.policy.maxEntitlementTtlSeconds,
+    schemas: options.schemas,
+  });
+  return {
+    completenessStatementDigest,
+    statement,
+    signing: {
+      statement,
+      root: options.stagingDirectory,
+      statementPath: ENTITLEMENT_STATEMENT_PATH,
+      bundlePath: ENTITLEMENT_BUNDLE_PATH,
+      signer: options.signer,
+      certificateWorkflowSha: options.signingWorkflowSha,
+      predicateType: options.schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    },
+  };
+}
+
+/** Stage one customer's entitlement statement for signing. Returns the signing plan and the statement. */
+export function stageImageDeliveryEntitlementEvidence(options) {
+  const { stagingDirectory } = options;
+  if (typeof stagingDirectory !== 'string' || !isAbsolute(stagingDirectory)) {
+    throw new Error('the entitlement staging directory must be absolute');
+  }
+  if (existsSync(stagingDirectory)) {
+    throw new Error(`entitlement staging directory already exists: ${stagingDirectory}`);
+  }
+  assertGitHubProducerContext(
+    { signer: options.signer, producerWorkflowSha: options.signingWorkflowSha },
+    options.githubContext,
+  );
+  const { statement, signing } = deriveEntitlement(options);
+  mkdirSync(stagingDirectory, { recursive: true, mode: 0o700 });
+  try {
+    const plan = stageEvidenceStatement(signing);
+    return {
+      plan: {
+        ...plan,
+        kind: 'entitlement',
+        distributionId: options.distributionId,
+        customerId: options.customerId,
+      },
+      statement,
+    };
+  } catch (error) {
+    rmSync(stagingDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * Accept the signed entitlement bundle, write `entitlement.json` and seal
+ * `outputDirectory`. The output is BUILT from the re-derived statement and the
+ * canonicalized bundle, never renamed from the staging, which must hold exactly
+ * what stage recorded and does not outlive the accept.
+ */
+export function acceptImageDeliveryEntitlementEvidence(options) {
+  const { outputDirectory, stagingDirectory, readCosignVersion, runCosign } = options;
+  if (
+    typeof outputDirectory !== 'string' ||
+    !isAbsolute(outputDirectory) ||
+    typeof stagingDirectory !== 'string' ||
+    !isAbsolute(stagingDirectory)
+  ) {
+    throw new Error('the entitlement output and staging directories must be absolute');
+  }
+  if (typeof readCosignVersion !== 'function' || typeof runCosign !== 'function') {
+    throw new Error('cosign seams are required');
+  }
+  const sealing = reserveSealing(outputDirectory, 'entitlement');
+  return sealAccepted({
+    stagingDirectory,
+    sealing,
+    outputDirectory,
+    build: () => {
+      assertGitHubProducerContext(
+        { signer: options.signer, producerWorkflowSha: options.signingWorkflowSha },
+        options.githubContext,
+      );
+      assertPinnedCosignVersion(readCosignVersion(), options.policy?.cosignVersion);
+      const { completenessStatementDigest, statement, signing } = deriveEntitlement(options);
+      assertStagedExactly(stagingDirectory, [ENTITLEMENT_STATEMENT_PATH, ENTITLEMENT_BUNDLE_PATH]);
+      const descriptor = acceptSignedEvidenceStatement({ ...signing, sealingRoot: sealing, runCosign });
+      writeFileSync(
+        join(sealing, ENTITLEMENT_DESCRIPTOR_FILE),
+        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 };
+    },
+  });
+}
+
+function requireInteger(raw, label, { positive }) {
+  const value = Number(raw);
+  if (!/^\d+$/.test(String(raw)) || !Number.isSafeInteger(value) || (positive && value <= 0)) {
+    throw new Error(`--${label} must be a ${positive ? 'positive' : 'non-negative'} integer`);
+  }
+  return value;
+}
+
+const SHARED_FLAGS = Object.freeze([
+  'distribution',
+  'evidence-root',
+  'staging',
+  'customer',
+  'mode',
+  'target-registry',
+  'idempotency-key',
+  'run-id',
+  'run-attempt',
+  'issued-at',
+  'expires-at',
+  'signer-repository',
+  'signer-ref',
+  'signer-workflow-path',
+  'github-repository',
+  'github-ref',
+  'github-sha',
+  'github-workflow-ref',
+]);
+
+async function main() {
+  const [phase, ...args] = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Kernel,
+  ]);
+  if (phase !== 'stage' && phase !== 'accept') {
+    throw new Error('usage: xema edition evidence statement entitlement <stage|accept> …');
+  }
+  const flags = parseEvidenceCliFlags(args, {
+    single: phase === 'stage' ? SHARED_FLAGS : [...SHARED_FLAGS, 'output', 'cosign'],
+    repeated: [],
+  });
+  const { schemas } = await loadProducerKernelSchemas({ dataRoot: dataRoot() });
+  const githubSha = flags.require('github-sha');
+  const options = {
+    distributionId: flags.require('distribution'),
+    evidenceRoot: resolve(flags.require('evidence-root')),
+    stagingDirectory: resolve(flags.require('staging')),
+    schemas,
+    policy: loadPinnedTrustPolicy({ dataRoot: dataRoot(), schemas }),
+    signer: githubWorkflowSigner({
+      repository: flags.require('signer-repository'),
+      ref: flags.require('signer-ref'),
+      path: flags.require('signer-workflow-path'),
+    }),
+    githubContext: {
+      repository: flags.require('github-repository'),
+      ref: flags.require('github-ref'),
+      sha: githubSha,
+      workflowRef: flags.require('github-workflow-ref'),
+    },
+    signingWorkflowSha: githubSha,
+    customerId: flags.require('customer'),
+    mode: flags.require('mode'),
+    targetRegistry: flags.optional('target-registry') ?? null,
+    idempotencyKey: flags.require('idempotency-key'),
+    runId: flags.require('run-id'),
+    runAttempt: requireInteger(flags.require('run-attempt'), 'run-attempt', { positive: true }),
+    issuedAt: flags.require('issued-at'),
+    expiresAt: flags.require('expires-at'),
+  };
+  if (phase === 'stage') {
+    process.stdout.write(serializeJson(stageImageDeliveryEntitlementEvidence(options).plan));
+    return;
+  }
+  const result = acceptImageDeliveryEntitlementEvidence({
+    ...options,
+    outputDirectory: resolve(flags.require('output')),
+    ...createCosignVerifier(resolve(flags.require('cosign'))),
+  });
+  process.stdout.write(
+    serializeJson({
+      schemaVersion: 1,
+      kind: 'entitlement',
+      distributionId: options.distributionId,
+      customerId: options.customerId,
+      outputDirectory: result.outputDirectory,
+      completenessStatementDigest: result.completenessStatementDigest,
+      evidence: result.descriptor,
+    }),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[image-delivery-entitlement] ${error.message}`);
+    process.exitCode = 1;
+  });
+}