@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/verify-image-evidence.mjs

@@ -0,0 +1,493 @@
+// The evidence verifier. This module is the ENTRY of the verifier bundle
+// (`scripts/build-evidence-verifier.mjs` -> dist/edition/verify-image-evidence
+// .bundle.mjs); `xema-edition verify-evidence` runs that built file, never this
+// source. Run as the bundle it refuses, before it trusts anything, unless:
+//
+//   * its launch environment carries no NODE_OPTIONS/NODE_PATH/DYLD_*/LD_*/GIT_*;
+//   * its own file and provenance hash to the digests the data root PINS, and
+//     its install path and every ancestor are not group/world writable or
+//     foreign-owned;
+//   * the kernel `--kernel` states declares, as data, exactly the edition
+//     protocol compiled into the bundle, and this CLI supports it;
+//   * the data root and the editions root are clean git checkouts at an exact
+//     HEAD with every file read from them bound to its HEAD blob.
+//
+// A second mode, `catalogue-evidence arming|verify` (verify-catalogue-evidence.mjs), judges a release catalogue's E4
+// statement for a customer before the catalogue's kernel is adopted; it is selected by the first argument.
+//
+// usage: verify-image-evidence <distributionId> --evidence-root <dir>
+//   --descriptor <absolute-path> --state <absolute-path> --cosign <absolute-path> --git <absolute-path>
+//   [--evidence-set <relative-path>] --data-root <dir> --editions-root <dir>
+//   --kernel <dir>
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { parseEditionDescriptor } from './edition-artifact.mjs';
+import { EditionChannel, assertEditionChannel } from './edition-channel.mjs';
+import { editionWorkspaceConfig, resetEditionWorkspaceConfig } from './edition-config.mjs';
+import { assertKernelSpeaksBundledProtocol } from './edition-protocol.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  dataRoot,
+  editionsRoot,
+  isEntryModule,
+  kernelPackageDir,
+} from './edition-workspace.mjs';
+import {
+  assertExternalInput,
+  gradeTrustedCheckouts,
+  prepareTrustedGitBinary,
+} from './evidence-checkout.mjs';
+import {
+  RUNTIME_IMAGE_SOURCE_INDEX_FILE,
+  assertPinnedKernelContractAuthority,
+  assertPinnedPolicy,
+  assertPinnedThirdPartySourcePins,
+  assertPinnedVerifier,
+  readStatedKernelContractAuthority,
+  loadDeclaredTrustPolicy,
+  readEvidenceTrustPin,
+  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,
+  verifyDistributionImageEvidenceSet,
+  verifyImageDeliveryEntitlement,
+} from './image-evidence.mjs';
+import {
+  assertSanitizedOperatorEnvironment,
+  readRunningVerifier,
+} from './verifier-binding.mjs';
+import { isVerifierDigestPinned } from './verifier-digest-pin.mjs';
+import { loadVerifierKernelSchemas } from './verifier-kernel-schemas.mjs';
+import {
+  CATALOGUE_EVIDENCE_MODE,
+  runCatalogueEvidenceEntry,
+} from './verify-catalogue-evidence.mjs';
+
+const USAGE =
+  'usage: verify-image-evidence <distributionId> --evidence-root <dir> --descriptor <absolute-path> --state <absolute-path> ' +
+  '--cosign <absolute-path> --git <absolute-path> [--channel <develop|release>] [--evidence-set <relative-path>] [--json] ' +
+  '[--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) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function parseArgs(args) {
+  const [distributionId, ...withJson] = args;
+  const jsonFlags = withJson.filter((arg) => arg === '--json').length;
+  if (jsonFlags > 1) {throw new Error('--json was given twice');}
+  const rest = withJson.filter((arg) => arg !== '--json');
+  try {
+    assertCanonicalDistributionId(distributionId);
+  } catch {
+    throw new Error(USAGE);
+  }
+  const options = {
+    distributionId,
+    evidenceRoot: null,
+    evidenceSetPath: 'evidence-set.json',
+    json: jsonFlags === 1,
+    descriptorPath: null,
+    channel: EditionChannel.Release,
+    statePath: null,
+    cosignBinary: null,
+    gitBinary: null,
+    entitlementDescriptorPath: null,
+    entitlementWorkflowSha: null,
+    customerId: null,
+    mode: null,
+    targetRegistry: null,
+  };
+  const seen = new Set();
+  for (let index = 0; index < rest.length; index += 2) {
+    const flag = rest[index];
+    const value = requireOptionValue(rest, index, flag);
+    if (seen.has(flag)) {throw new Error(`${flag} was given twice`);}
+    seen.add(flag);
+    if (flag === '--evidence-root') {options.evidenceRoot = value;}
+    else if (flag === '--evidence-set') {options.evidenceSetPath = value;}
+    else if (flag === '--descriptor') {options.descriptorPath = value;}
+    else if (flag === '--channel') {assertEditionChannel(value); options.channel = value;}
+    else if (flag === '--state') {options.statePath = value;}
+    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;}
+    else {throw new Error(`unknown option "${flag}"`);}
+  }
+  if (!options.evidenceRoot) {
+    throw new Error('--evidence-root is required');
+  }
+  for (const [flag, value] of [
+    ['--descriptor', options.descriptorPath],
+    ['--state', options.statePath],
+    ['--cosign', options.cosignBinary],
+    ['--git', options.gitBinary],
+  ]) {
+    if (!value || !isAbsolute(value)) {
+      throw new Error(`${flag} is required and must be an absolute path`);
+    }
+  }
+  // An entitlement is verified whole or not at all: the descriptor names the
+  // 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],
+  ];
+  const stated = entitlementFlags.filter(([, value]) => value !== null);
+  if (stated.length !== 0 && stated.length !== entitlementFlags.length) {
+    throw new Error(
+      `${entitlementFlags.map(([flag]) => flag).join(', ')} are given together or not at all`,
+    );
+  }
+  if (stated.length === 0 && options.targetRegistry !== null) {
+    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');
+  }
+  return options;
+}
+
+/**
+ * The channel the descriptor states (compared with the invoked channel, never trusted as it): the descriptor's
+ * `provenance.channel`, mapped to the kernel's evidence channel. The descriptor
+ * must be the one of the requested distribution; an unmapped channel is refused.
+ */
+/** The descriptor states a channel other than the one verification was invoked on: nothing is verified. */
+export class EvidenceChannelMismatchError extends Error {
+  constructor({ invoked, descriptor }) {
+    super(`verification was invoked on the ${invoked} channel but --descriptor states the ${descriptor} channel; pass --channel ${descriptor} to verify a ${descriptor} edition`);
+    this.name = 'EvidenceChannelMismatchError';
+  }
+}
+
+function readEvidenceChannel({ descriptorPath, distributionId, schemas }) {
+  const descriptor = parseEditionDescriptor(JSON.parse(readFileSync(descriptorPath, 'utf8')));
+  if (descriptor.distributionId !== distributionId) {
+    throw new Error(
+      `--descriptor is the descriptor of "${descriptor.distributionId}", not of the requested distribution "${distributionId}"`,
+    );
+  }
+  const channel = EVIDENCE_CHANNEL_OF_EDITION_CHANNEL[descriptor.provenance.channel];
+  if (channel === undefined || !schemas.EVIDENCE_CHANNELS.includes(channel)) {
+    throw new Error(
+      `the descriptor channel "${descriptor.provenance.channel}" maps to no kernel evidence channel`,
+    );
+  }
+  return channel;
+}
+
+export const EDITION_EVIDENCE_VERIFICATION_SCHEMA = 'xema.edition-evidence-verification/v1';
+
+/**
+ * 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
+    .map((producer) => {
+      const statement = verified.producerStatements.get(`${producer.subjectKind}\0${producer.subjectId}`);
+      return {
+        predicateType: statement.predicateType,
+        subject: statement.subject[0].name,
+        statementDigest: producer.evidence.statementDigest,
+      };
+    })
+    .sort((left, right) => (left.subject < right.subject ? -1 : left.subject > right.subject ? 1 : 0));
+  const statements = [
+    ...producers,
+    {
+      predicateType: verified.completenessStatement.predicateType,
+      subject: verified.completenessStatement.subject[0].name,
+      statementDigest: evidenceSet.completeness.statementDigest,
+    },
+  ];
+  if (verified.entitlementStatement !== null) {
+    statements.push({
+      predicateType: verified.entitlementStatement.predicateType,
+      subject: verified.entitlementStatement.subject[0].name,
+      statementDigest: entitlementDescriptor.statementDigest,
+    });
+  }
+  return {
+    schema: EDITION_EVIDENCE_VERIFICATION_SCHEMA,
+    distributionId,
+    channel,
+    verifierPinned: isVerifierDigestPinned(channel),
+    releaseSequence: verified.completenessStatement.predicate.releaseSequence,
+    statements,
+  };
+}
+
+/**
+ * The declared policy, held to the data-root pin of both the policy and THIS
+ * running verifier. Read from the working tree: it is read twice, before the
+ * checkouts are graded (the policy names the git binary that grades them) and
+ * after, and the two readings must be the same policy.
+ */
+function readTrustAnchors({ schemas, running, channel }) {
+  resetEditionWorkspaceConfig();
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  if (declaration.policy === null) {
+    throw new Error(
+      `${dataRoot()} declares no evidenceTrustPolicy in edition-workspace.json; there is no policy to verify against`,
+    );
+  }
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({
+    dataRoot: dataRoot(),
+    declaration,
+    schemas,
+  });
+  const pin = readEvidenceTrustPin({ dataRoot: dataRoot(), declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: dataRoot() });
+  assertPinnedVerifier({ pin, actual: verifierDigests(running), channel });
+  // The authority the producer statements are held to is read from the data
+  // root's index downstream; it is the pinned one, or nothing is verified.
+  assertPinnedKernelContractAuthority({
+    pin,
+    authority: readStatedKernelContractAuthority({ dataRoot: dataRoot(), schemas }),
+    label: RUNTIME_IMAGE_SOURCE_INDEX_FILE,
+  });
+  return { declaration, policy, policyDigest };
+}
+
+/**
+ * Verify the evidence for one edition. `bundlePath` is the running bundle
+ * (`process.argv[1]` when run as one).
+ */
+export async function verifyEvidence({ argv, env, bundlePath }) {
+  assertSanitizedOperatorEnvironment(env);
+  const options = parseArgs(
+    configureEditionWorkspaceFromArgv(argv, [
+      WorkspaceRoot.Data,
+      WorkspaceRoot.Editions,
+      WorkspaceRoot.Kernel,
+    ]),
+  );
+  const evidenceRoot = realpathSync(options.evidenceRoot);
+  const running = readRunningVerifier(bundlePath);
+  const { schemas, editionProtocol } = await loadVerifierKernelSchemas();
+  assertKernelSpeaksBundledProtocol({
+    kernelPackageDir: kernelPackageDir(),
+    bundled: editionProtocol,
+  });
+  // The channel is the invoker's (`--channel`, release when absent), never the descriptor's: the descriptor is the data
+  // under verification and must not choose its own trust level (whether the verifier's digests are pinned).
+  const channel = options.channel;
+  const descriptorChannel = readEvidenceChannel({
+    descriptorPath: options.descriptorPath,
+    distributionId: options.distributionId,
+    schemas,
+  });
+  if (descriptorChannel !== channel) {
+    throw new EvidenceChannelMismatchError({ invoked: channel, descriptor: descriptorChannel });
+  }
+  const first = readTrustAnchors({ schemas, running, channel });
+  const trustedGit = prepareTrustedGitBinary({
+    gitBinary: options.gitBinary,
+    policy: first.policy,
+  });
+  try {
+    const grades = [
+      {
+        root: dataRoot(),
+        label: 'data root',
+        requiredPaths: [
+          ...DATA_ROOT_FILES,
+          first.declaration.policy,
+          first.declaration.pin,
+          first.policy.trustedRootPath,
+        ],
+      },
+      {
+        root: editionsRoot(),
+        label: 'editions root',
+        requiredPaths: [
+          'distribution.lock.json',
+          'images.lock.json',
+          'xema-distribution.json',
+        ].map((file) => `${options.distributionId}/${file}`),
+      },
+    ];
+    const graded = gradeTrustedCheckouts({ grades, trustedGit });
+    const repositoryRoots = new Set(
+      [...graded.values()].map((checkout) => checkout.repositoryRoot),
+    );
+    // Now that the files are bound to HEAD, the policy and pin read above must
+    // be the ones that were graded.
+    const anchors = readTrustAnchors({ schemas, running, channel });
+    if (anchors.policyDigest !== first.policyDigest) {
+      throw new Error('the trust policy changed while the checkouts were graded');
+    }
+    assertExternalInput(repositoryRoots, evidenceRoot, 'evidence root');
+    assertExternalInput(repositoryRoots, options.statePath, 'replay state');
+    assertExternalInput(repositoryRoots, options.descriptorPath, 'edition descriptor');
+    const releaseSourceCommit = graded.get(realpathSync(editionsRoot())).commit;
+    const assertCheckoutsUnchanged = () =>
+      gradeTrustedCheckouts({ grades, trustedGit, expected: graded });
+    const evidenceSet = schemas.parseDistributionImageEvidenceSet(
+      readCanonicalJsonFromRoot(
+        evidenceRoot,
+        options.evidenceSetPath,
+        'distribution image evidence set',
+      ),
+    );
+    const policyDigest = trustPolicyDigest(anchors.policy);
+    const { verified } = await verifyAndAdvanceReplayState({
+      statePath: options.statePath,
+      distributionId: options.distributionId,
+      trustPolicyDigest: policyDigest,
+      parseReplayState: schemas.parseDistributionImageReplayState,
+      verify: async () => {
+        assertCheckoutsUnchanged();
+        const result = await verifyDistributionImageEvidenceSet({
+          distributionId: options.distributionId,
+          channel,
+          dataRoot: dataRoot(),
+          editionsRoot: editionsRoot(),
+          evidenceRoot,
+          evidenceSet,
+          policy: anchors.policy,
+          policyRoot: dataRoot(),
+          now: new Date(),
+          expectedReleaseSourceCommit: releaseSourceCommit,
+          cosignBinary: options.cosignBinary,
+          schemas,
+        });
+        const entitlement =
+          options.entitlementDescriptorPath === null
+            ? null
+            : 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: entitlementEvidenceRoot(evidenceRoot, options.entitlementDescriptorPath),
+                descriptor: entitlementDescriptor,
+                policy: anchors.policy,
+                policyRoot: dataRoot(),
+                completenessStatementDigest: result.completenessStatementDigest,
+                customerId: options.customerId,
+                distributionId: options.distributionId,
+                distributionLock: result.distributionLock,
+                channel,
+                mode: options.mode,
+                targetRegistry: options.targetRegistry,
+                now: new Date(),
+                // 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,
+                cosignBinary: options.cosignBinary,
+                schemas,
+              });
+        assertCheckoutsUnchanged();
+        return { ...result, entitlementStatement, entitlementDescriptor };
+      },
+    });
+    // With --json the human text goes to stderr and stdout carries the one document.
+    (options.json ? process.stderr : process.stdout).write(
+      `verified ${verified.producerStatements.size} image producers and distribution completeness for ` +
+        `"${options.distributionId}" at release sequence ` +
+        `${verified.completenessStatement.predicate.releaseSequence}\n` +
+        `edition read from ${editionsRoot()} at editions checkout commit ${releaseSourceCommit}\n` +
+        (verified.entitlementStatement === null
+          ? ''
+          : `verified the delivery entitlement of "${options.customerId}" (${options.mode})\n`),
+    );
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify(
+          evidenceVerificationDocument({
+            distributionId: options.distributionId,
+            channel,
+            evidenceSet,
+            verified,
+            entitlementDescriptor: verified.entitlementDescriptor,
+          }),
+          null,
+          2,
+        )}\n`,
+      );
+    }
+  } finally {
+    trustedGit.dispose();
+  }
+}
+
+if (isEntryModule(import.meta.url) && process.argv[2] === CATALOGUE_EVIDENCE_MODE) {
+  // The customer's pre-adoption mode: the E4 statement of a catalogue, judged with this bundle's own embedded kernel.
+  await runCatalogueEvidenceEntry({
+    argv: process.argv.slice(2),
+    env: process.env,
+    bundlePath: process.argv[1],
+  });
+} else if (isEntryModule(import.meta.url)) {
+  await verifyEvidence({
+    argv: process.argv.slice(2),
+    env: process.env,
+    bundlePath: process.argv[1],
+  }).catch((error) => {
+    // A named refusal (e.g. EditionProtocolMismatchError) is printed with its name.
+    const named = error.name && error.name !== 'Error' ? `${error.name}: ` : '';
+    console.error(`verify-image-evidence: ${named}${error.message}`);
+    process.exitCode = 1;
+  });
+}