@xemahq/xema 0.40.3 → 0.41.0

package/edition/catalogue-evidence.mjs

@@ -0,0 +1,225 @@
+// catalogue-evidence — the catalogue's signed E4 evidence, verified BEFORE the catalogue is read.
+//
+// A release catalogue is the ceiling of everything resolved against it, so its bytes are not parsed, and not even
+// fetched, until the E4 statement over its digest, catalogue layer and lock layer has been verified against the evidence
+// trust policy of the CALLER'S OWN data root (never the vendor's). The statement is an `oras attach` referrer of the
+// edition artifact digest (`EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE`): two layers, `statement.json` (in-toto) and
+// `bundle.sigstore.json` (the Sigstore bundle), and the exact commit of the signing workflow as an annotation.
+//
+// The verification is ONE seam, `verifyCatalogueEvidenceReferrer`, and it is done by the data root's PINNED built
+// verifier (`catalogue-evidence verify`, verify-catalogue-evidence.mjs): there is no second verifier. The only
+// kernel-dependent parts of the judgement are the policy schema (parseSigstoreOfflineTrustPolicy) and the
+// predicate-type/channel constants; before the catalogue's kernel is adopted (kernel-package.mjs) there is no kernel
+// package to load them from, so they come from the pinned bundle's own embedded kernel. The library never judges the
+// statement itself: it checks the referrer's layout, hands the two blobs to the bundle (only after the bundle's digests
+// equal the data-root pin; otherwise CatalogueVerifierNotPinnedError, before anything is spawned) and reads its verdict.
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
+import { assertPinnedVerifier, readEvidenceTrustPin } from './evidence-trust-pin.mjs';
+import { EvidenceTrustRequiredError } from './evidence-trust-policy.mjs';
+import { EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE } from './oci-image-source-evidence.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+
+const TITLE = 'org.opencontainers.image.title';
+/** The titles of the two layers of an E4 referrer, the in-toto statement's media type and the annotation naming the signing workflow commit. */
+export const CATALOGUE_EVIDENCE_STATEMENT_TITLE = 'statement.json';
+export const CATALOGUE_EVIDENCE_BUNDLE_TITLE = 'bundle.sigstore.json';
+export const CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE = 'application/vnd.in-toto+json';
+export const CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION = 'dev.xema.evidence.signer-workflow-sha';
+/** The variables the pinned verifier bundle is launched with (it refuses NODE_OPTIONS, NODE_PATH, DYLD_*, LD_*, GIT_*). */
+export const VERIFIER_LAUNCH_ENV_KEYS = Object.freeze(['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ']);
+const STATEMENT_MAX_BYTES = 2 * 1024 * 1024;
+const BUNDLE_MAX_BYTES = 16 * 1024 * 1024;
+const SPAWN_TIMEOUT_MS = 120_000;
+const COMMIT = /^[a-f0-9]{40}$/;
+const sha256Of = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+
+/** No E4 referrer is attached to the artifact: the catalogue has no signed evidence at all. */
+export class CatalogueEvidenceMissingError extends Error {
+  constructor(ref) {
+    super(
+      `${ref} carries no ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} referrer: its catalogue has no signed edition evidence (E4), ` +
+        'so it is refused before it is read',
+    );
+    this.name = 'CatalogueEvidenceMissingError';
+  }
+}
+
+/** An E4 referrer exists but does not verify against the caller's evidence trust policy. */
+export class CatalogueEvidenceNotVerifiedError extends Error {
+  constructor(ref, reason) {
+    super(`${ref}: the catalogue's edition evidence (E4) is not verified: ${reason}; the catalogue is refused before it is read`);
+    this.name = 'CatalogueEvidenceNotVerifiedError';
+  }
+}
+
+/** The built verifier is not the one the data root pins (or is missing): nothing is spawned. */
+export class CatalogueVerifierNotPinnedError extends Error {
+  constructor(reason) {
+    super(`the catalogue's edition evidence (E4) cannot be verified: this CLI's built evidence verifier is not the one the data root pins: ${reason}`);
+    this.name = 'CatalogueVerifierNotPinnedError';
+  }
+}
+
+/** The pinned built verifier's bundle path, after the data root's pin of it held; refuses before anything is spawned. */
+function pinnedVerifierBundle(locateVerifier) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  if (declaration.policy === null) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+  try {
+    const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
+    assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
+    return { bundlePath: locateVerifier().bundlePath, root };
+  } catch (error) {
+    throw new CatalogueVerifierNotPinnedError(error.message);
+  }
+}
+
+function launchEnvironment(source = process.env) {
+  const reduced = {};
+  for (const key of VERIFIER_LAUNCH_ENV_KEYS) {
+    if (source[key] !== undefined) {reduced[key] = source[key];}
+  }
+  return reduced;
+}
+
+function runVerifier({ spawn, bundlePath, args }) {
+  return spawn(process.execPath, [bundlePath, 'catalogue-evidence', ...args], {
+    encoding: 'utf8',
+    env: launchEnvironment(),
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: 1024 * 1024,
+  });
+}
+
+const stderrOf = (result) => String(result.stderr ?? '').trim() || (result.error ? result.error.message : `exit ${String(result.status)}`);
+
+/**
+ * Before any registry call: the caller's data root declares a policy, the built verifier is the one the pin records, and
+ * the policy is ARMED on `channel` with the E4 row required (the one arming rule, judged by the pinned bundle with its own
+ * kernel). Throws EvidenceTrustRequiredError for no policy / not armed, CatalogueVerifierNotPinnedError for a verifier the
+ * pin does not record.
+ *
+ * @param {{ channel: string, locateVerifier?: Function, spawn?: Function }} options
+ */
+export function assertCatalogueConsumerArmed({ channel, locateVerifier = locateBuiltVerifier, spawn = spawnSync }) {
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const result = runVerifier({ spawn, bundlePath, args: ['arming', '--channel', channel, '--data-root', root] });
+  if (result.status === 0) {return;}
+  const stderr = stderrOf(result);
+  if (stderr.includes('EVIDENCE_TRUST_REQUIRED_UNARMED')) {
+    throw new EvidenceTrustRequiredError(root, `declares a policy that is not armed on the ${channel} channel for a catalogue consumer (${stderr})`);
+  }
+  throw new CatalogueEvidenceNotVerifiedError(`the ${channel} catalogue`, `the arming check failed: ${stderr}`);
+}
+
+function layerOf(layers, title, mediaType, ref) {
+  const found = layers.filter((layer) => layer?.annotations?.[TITLE] === title);
+  if (found.length !== 1 || found[0].mediaType !== mediaType || typeof found[0].digest !== 'string') {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `the referrer must carry exactly one ${title} layer of media type ${mediaType}`);
+  }
+  return found[0];
+}
+
+async function readReferrerLayers({ client, repository, referrer, manifestDigest, ref }) {
+  const manifest = await client.getManifestByDigest(repository, referrer.digest);
+  const document = manifest.document ?? {};
+  if (document.artifactType !== EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is not a ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} artifact`);
+  }
+  if (document.subject?.digest !== manifestDigest) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is a referrer of ${String(document.subject?.digest)}, not of ${manifestDigest}`);
+  }
+  const layers = Array.isArray(document.layers) ? document.layers : [];
+  if (layers.length !== 2) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} must carry exactly two layers (${CATALOGUE_EVIDENCE_STATEMENT_TITLE}, ${CATALOGUE_EVIDENCE_BUNDLE_TITLE}), it carries ${layers.length}`);
+  }
+  const statement = layerOf(layers, CATALOGUE_EVIDENCE_STATEMENT_TITLE, CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE, ref);
+  const bundle = layerOf(layers, CATALOGUE_EVIDENCE_BUNDLE_TITLE, BUNDLE_MEDIA_TYPE, ref);
+  const workflowSha = document.annotations?.[CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION];
+  if (typeof workflowSha !== 'string' || !COMMIT.test(workflowSha)) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} states no 40-hex ${CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION} annotation`);
+  }
+  return { statement, bundle, workflowSha };
+}
+
+/**
+ * The seam. Hold one E4 referrer to the caller's policy and to the exact catalogue and lock layers: read its two layers
+ * (bounded) into a private temporary directory and have the PINNED built verifier judge them. Throws when it does not
+ * verify, returns when it does. The verifier's pin is re-checked here, before anything is spawned.
+ *
+ * @param {{ ref: string, client: object, repository: string, referrer: object, channel: string, offeringId: string, manifestDigest: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign: string, locateVerifier?: Function, spawn?: Function }} subject
+ */
+export async function verifyCatalogueEvidenceReferrer({
+  ref,
+  client,
+  repository,
+  referrer,
+  channel,
+  offeringId,
+  manifestDigest,
+  catalogueLayerDigest,
+  lockLayerDigest,
+  cosign,
+  locateVerifier = locateBuiltVerifier,
+  spawn = spawnSync,
+}) {
+  if (typeof cosign !== 'string' || !cosign.startsWith('/')) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, 'a release catalogue is verified with a cosign binary: pass --cosign <absolute path>');
+  }
+  const layers = await readReferrerLayers({ client, repository, referrer, manifestDigest, ref });
+  const statementBytes = await client.getBlob(repository, layers.statement.digest, STATEMENT_MAX_BYTES);
+  const bundleBytes = await client.getBlob(repository, layers.bundle.digest, BUNDLE_MAX_BYTES);
+  if (sha256Of(statementBytes) !== layers.statement.digest || sha256Of(bundleBytes) !== layers.bundle.digest) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, 'a referrer layer does not hash to its digest');
+  }
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const evidenceRoot = mkdtempSync(join(tmpdir(), 'xema-catalogue-evidence-'));
+  try {
+    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_STATEMENT_TITLE), statementBytes, { flag: 'wx', mode: 0o600 });
+    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_BUNDLE_TITLE), bundleBytes, { flag: 'wx', mode: 0o600 });
+    const result = runVerifier({
+      spawn,
+      bundlePath,
+      args: [
+        'verify',
+        '--channel', channel,
+        '--data-root', root,
+        '--evidence-root', evidenceRoot,
+        '--statement-digest', layers.statement.digest,
+        '--bundle-digest', layers.bundle.digest,
+        '--workflow-sha', layers.workflowSha,
+        '--offering-id', offeringId,
+        '--subject-digest', manifestDigest,
+        '--catalogue-layer-digest', catalogueLayerDigest,
+        '--lock-layer-digest', lockLayerDigest,
+        '--cosign', cosign,
+      ],
+    });
+    if (result.status !== 0) {throw new CatalogueEvidenceNotVerifiedError(ref, stderrOf(result));}
+  } finally {
+    rmSync(evidenceRoot, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Verify the catalogue's E4 evidence from the registry, before any catalogue byte is fetched or parsed.
+ *
+ * @param {{ client: object, ref: string, repository: string, manifestDigest: string, channel: string, offeringId: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign?: string, locateVerifier?: Function, verifyReferrer?: Function }} options
+ */
+export async function verifyCatalogueEvidence({ client, ref, repository, manifestDigest, channel, offeringId, catalogueLayerDigest, lockLayerDigest, cosign, locateVerifier, verifyReferrer = verifyCatalogueEvidenceReferrer }) {
+  const listed = await client.listReferrers(repository, manifestDigest, EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
+  const referrers = listed.filter((descriptor) => descriptor?.artifactType === EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
+  if (referrers.length === 0) {throw new CatalogueEvidenceMissingError(ref);}
+  for (const referrer of referrers) {
+    await verifyReferrer({ ref, client, repository, referrer, channel, offeringId, manifestDigest, catalogueLayerDigest, lockLayerDigest, cosign, ...(locateVerifier === undefined ? {} : { locateVerifier }) });
+  }
+}

package/edition/catalogue-fetch.mjs

@@ -13,9 +13,10 @@
 
 import { Buffer } from 'node:buffer';
 
+import { verifyCatalogueEvidence } from './catalogue-evidence.mjs';
 import { CATALOGUE_FILE, CatalogueError, parseCatalogue } from './catalogue.mjs';
 import { parseEditionRepository } from './edition-artifact.mjs';
-import { EDITION_ARTIFACT_TYPE } from './edition-constants.mjs';
+import { EDITION_ARTIFACT_TYPE, EditionChannel, EditionLockFile } from './edition-constants.mjs';
 import { OrasRegistry } from './oras.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
 
@@ -55,8 +56,23 @@ export function catalogueCredential({ authority, username, tokenEnv, env = proce
   return { authority, access: 'authenticated', basicAuth: Buffer.from(`${username}:${token}`, 'utf8').toString('base64') };
 }
 
-/** Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. `client` is injectable for tests. */
-export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client }) {
+/** The one layer of `manifest` titled `title`; an offering artifact carries exactly one of each. */
+export function layerTitled(manifest, title, ref) {
+  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === title);
+  if (layers.length !== 1) {
+    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${title}; an offering artifact carries exactly one`);
+  }
+  return layers[0];
+}
+
+/**
+ * Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. A RELEASE catalogue is read
+ * only after its E4 evidence verified against the caller's own evidence trust policy (catalogue-evidence.mjs): the
+ * verification precedes the blob fetch and the parse, so an unverified catalogue is never read. It is done by the data
+ * root's pinned built verifier, with the absolute `cosign` the caller names. `client` and `verifyEvidence` are injectable
+ * for tests.
+ */
+export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client, cosign, locateVerifier, verifyEvidence = verifyCatalogueEvidence }) {
   const { authority, repository, digest, edition } = parseCatalogueRef(ref);
   if (edition.channel !== channel) {
     throw new CatalogueError(
@@ -69,11 +85,22 @@ export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = p
   if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
     throw new CatalogueError(`${ref} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
   }
-  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === CATALOGUE_FILE);
-  if (layers.length !== 1) {
-    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${CATALOGUE_FILE}; an offering artifact carries exactly one`);
+  const catalogueLayer = layerTitled(manifest, CATALOGUE_FILE, ref);
+  if (channel === EditionChannel.Release) {
+    await verifyEvidence({
+      client: registry,
+      ref,
+      repository,
+      manifestDigest: digest,
+      channel,
+      offeringId: edition.distributionId,
+      cosign,
+      locateVerifier,
+      catalogueLayerDigest: catalogueLayer.digest,
+      lockLayerDigest: layerTitled(manifest, EditionLockFile.Distribution, ref).digest,
+    });
   }
-  const bytes = await registry.getBlob(repository, layers[0].digest, CATALOGUE_MAX_BYTES);
+  const bytes = await registry.getBlob(repository, catalogueLayer.digest, CATALOGUE_MAX_BYTES);
   let document;
   try {
     document = JSON.parse(bytes.toString('utf8'));
@@ -81,6 +108,12 @@ export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = p
     throw new CatalogueError(`${ref}: ${CATALOGUE_FILE} is not JSON: ${error.message}`);
   }
   const catalogue = parseCatalogue(document);
+  if (catalogue.offeringId !== edition.distributionId) {
+    throw new CatalogueError(
+      `${ref}: ${CATALOGUE_FILE} is the catalogue of offering ${catalogue.offeringId}, but it was fetched from the repository of offering ${edition.distributionId}; ` +
+        'an artifact whose stated offering differs from its repository is refused',
+    );
+  }
   if (catalogue.channel !== edition.channel) {
     throw new CatalogueError(
       `${ref}: ${CATALOGUE_FILE} states channel ${catalogue.channel}, but it was fetched from the ${edition.channel} repository ${authority}/${repository}; ` +