@xemahq/xema 0.26.0 → 0.28.0

package/edition/source-closure.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// `xema edition source-closure`: the source tree hash of one directory of a
+// source repository at an exact commit, with its workspace-package closure.
+//
+// usage: xema edition source-closure --repo <repo> --path <dir> --commit <40 hex> --sources-root <dir> --source-hash <dir> --kernel <dir>
+//
+// These are the facts a content coordinate is derived from. A consumer frames
+// them into its own coordinate; it never reads a git tree, a workspace graph
+// or a lockfile itself. `--path` is relative to the repository (`.` for its
+// root). The hashes are the ones the image content hash is built from, so a
+// coordinate derived from them moves exactly when the built bytes can move.
+
+import { join } from 'node:path';
+
+import { parseEvidenceCliFlags } from './distribution-evidence-set.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  isEntryModule,
+  sourcesRoot,
+} from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import {
+  compareStrings,
+  gitCommitTreeIndex,
+  hashGitSourceTree,
+  serializeJson,
+  workspaceClosure,
+  workspacePackagesAtCommit,
+} from './lib.mjs';
+
+/** The tree hash algorithm of every hash this verb prints. */
+export const SOURCE_CLOSURE_TREE_ALGORITHM = 'xema-source-tree-sha256-v2';
+const LOCKFILE_PATH = 'pnpm-lock.yaml';
+
+function assertContainedDirectory(directory) {
+  if (
+    typeof directory !== 'string' ||
+    directory.length === 0 ||
+    directory.startsWith('/') ||
+    (directory !== '.' && directory.split('/').some((part) => part === '' || part === '.' || part === '..'))
+  ) {
+    throw new Error(`--path "${String(directory)}" is not a directory inside the repository`);
+  }
+  return directory;
+}
+
+/**
+ * The closure of `directory` in `repoDir` at `commit`. `lockfileBlobId` is the
+ * repository lockfile's blob when the directory is buildable (it has a
+ * `package.json`), and `null` when it is not; a buildable directory in a
+ * repository with no lockfile is refused, because its build would resolve
+ * dependencies unpinned.
+ */
+export function readSourceClosure({ repoDir, repo, directory, commit }) {
+  if (!COMMIT_PATTERN.test(commit ?? '')) {
+    throw new Error(`--commit must be an exact 40-hex commit (got ${JSON.stringify(commit ?? null)})`);
+  }
+  assertContainedDirectory(directory);
+  const tree = gitCommitTreeIndex(repoDir, commit);
+  const graph = workspacePackagesAtCommit(repoDir, commit, tree);
+  const buildable = tree.isFile(directory === '.' ? 'package.json' : `${directory}/package.json`);
+  const lockfileBlobId = buildable ? tree.blobId(LOCKFILE_PATH) : undefined;
+  if (buildable && lockfileBlobId === undefined) {
+    throw new Error(
+      `${repo}:${directory} has a package.json but ${repo} has no ${LOCKFILE_PATH} at ${commit.slice(0, 12)}`,
+    );
+  }
+  return {
+    schemaVersion: 1,
+    repo,
+    directory,
+    commit,
+    treeAlgorithm: SOURCE_CLOSURE_TREE_ALGORITHM,
+    treeHash: hashGitSourceTree(repoDir, directory, commit, SOURCE_CLOSURE_TREE_ALGORITHM),
+    buildable,
+    lockfileBlobId: lockfileBlobId ?? null,
+    closure: [...workspaceClosure(directory, graph, commit)].sort(compareStrings).map((member) => ({
+      directory: member,
+      treeHash: hashGitSourceTree(repoDir, member, commit, SOURCE_CLOSURE_TREE_ALGORITHM),
+    })),
+  };
+}
+
+function main() {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Sources,
+    WorkspaceRoot.SourceHash,
+    // The hash implementation is held to the kernel it was built for.
+    WorkspaceRoot.Kernel,
+  ]);
+  const flags = parseEvidenceCliFlags(rest, { single: ['repo', 'path', 'commit'] });
+  const repo = flags.require('repo');
+  if (repo.startsWith('/') || repo.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    throw new Error(`--repo "${repo}" is not a repository under the sources root`);
+  }
+  process.stdout.write(
+    serializeJson(
+      readSourceClosure({
+        repoDir: join(sourcesRoot(), repo),
+        repo,
+        directory: flags.require('path'),
+        commit: flags.require('commit'),
+      }),
+    ),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`[source-closure] ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/edition/strict-json.mjs

@@ -0,0 +1,121 @@
+/**
+ * The ONE strict JSON reader for authored inputs of the distribution plane.
+ *
+ * `JSON.parse` resolves a duplicated object key by silently keeping the LAST
+ * occurrence. For an authored manifest that is a declaration being deleted
+ * with no signal: `xema-biome.json` once carried two `resources` keys inside
+ * one component, every reader dropped the first, the sealed lock never
+ * admitted the Redis namespace it declared, and the service crashlooped in a
+ * deployment on `redis-namespace-not-declared`. Nothing between the author and
+ * the cluster could say so, because every reader agreed on the wrong answer.
+ *
+ * So a duplicate key is REFUSED here, naming the file, the JSON pointer of the
+ * object and the key. There is deliberately no lenient mode and no "last wins"
+ * option: two values for one key is an authoring error with no correct reading.
+ *
+ * Node builtins only, so it runs from a bare checkout. The sibling
+ * implementation for the biome authoring toolchain is `strict-json.ts` in
+ * `@xemahq/biome-sdk` (xema-biome-sdk, `packages/sdks/biome-sdk/src/builder/lib/`);
+ * the two repositories share no package this could live in without a publish,
+ * so each holds one copy. Change both together.
+ */
+import { readFileSync } from 'node:fs';
+
+/** A JSON object declared the same key more than once. */
+export class DuplicateJsonKeyError extends Error {
+  /**
+   * @param {string} source  file path (or other handle) of the document
+   * @param {string} pointer RFC 6901 pointer of the OBJECT holding the key ("" = root)
+   * @param {string} key     the duplicated key, after escape decoding
+   */
+  constructor(source, pointer, key) {
+    super(
+      `${source}: duplicate key ${JSON.stringify(key)} in the object at JSON pointer ` +
+        `${JSON.stringify(pointer)}${pointer === '' ? ' (the document root)' : ''}. ` +
+        `JSON.parse would silently keep the last occurrence and drop the other; ` +
+        `merge the two declarations into one key.`,
+    );
+    this.name = 'DuplicateJsonKeyError';
+    this.code = 'DUPLICATE_JSON_KEY';
+    this.source = source;
+    this.pointer = pointer;
+    this.key = key;
+  }
+}
+
+function pointerSegment(segment) {
+  return String(segment).replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+/**
+ * Scan a document `JSON.parse` has ALREADY accepted for duplicated keys.
+ *
+ * Because the grammar is known to be valid, the scan only has to tell a string
+ * from structure: a `{`, `[`, `,` or `"` inside a string is never structural,
+ * and a string is left only at an unescaped `"`. Keys are compared after
+ * escape decoding (`"a"` and `"a"` are the same key to every reader).
+ */
+function assertNoDuplicateKeys(text, source) {
+  /** @type {Array<{object: boolean, pointer: string, keys: Set<string>, expectKey: boolean, key: string, index: number}>} */
+  const stack = [];
+  const childPointer = () => {
+    const top = stack.at(-1);
+    if (!top) {return '';}
+    return `${top.pointer}/${pointerSegment(top.object ? top.key : top.index)}`;
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '"') {
+      const start = i;
+      i += 1;
+      while (text[i] !== '"') {i += text[i] === '\\' ? 2 : 1;}
+      const top = stack.at(-1);
+      if (top?.object && top.expectKey) {
+        const key = JSON.parse(text.slice(start, i + 1));
+        if (top.keys.has(key)) {
+          throw new DuplicateJsonKeyError(source, top.pointer, key);
+        }
+        top.keys.add(key);
+        top.key = key;
+        top.expectKey = false;
+      }
+    } else if (char === '{' || char === '[') {
+      stack.push({
+        object: char === '{',
+        pointer: childPointer(),
+        keys: new Set(),
+        expectKey: char === '{',
+        key: '',
+        index: 0,
+      });
+    } else if (char === '}' || char === ']') {
+      stack.pop();
+    } else if (char === ',') {
+      const top = stack.at(-1);
+      if (top.object) {top.expectKey = true;}
+      else {top.index += 1;}
+    }
+  }
+}
+
+/**
+ * Parse JSON text, refusing a duplicated object key anywhere in the document.
+ * `source` names the document in every error.
+ */
+export function parseStrictJson(text, source) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${source}: invalid JSON: ${error.message}`, {
+      cause: error,
+    });
+  }
+  assertNoDuplicateKeys(text, source);
+  return value;
+}
+
+/** Read and strictly parse a JSON file from the working tree. */
+export function readStrictJsonFile(path) {
+  return parseStrictJson(readFileSync(path, 'utf8'), path);
+}

package/edition/string-order.mjs

@@ -0,0 +1,5 @@
+/** Stable, locale-independent string comparator (code-point order). */
+export function compareStrings(a, b) {
+  if (a === b) {return 0;}
+  return a < b ? -1 : 1;
+}

package/edition/trust-policy-arming.mjs

@@ -0,0 +1,120 @@
+// Arming assertion for the offline Sigstore trust policy.
+//
+// The policy a data root declares (`evidenceTrustPolicy`) is schema-valid while
+// authorizing nobody: `policies`, `trustedCosignBinaryDigests` and
+// `trustedGitBinaryDigests` all default to `[]` and the zod schema has no
+// `.min(1)` on any of them. So the file parses green while the delivery plane
+// remains deliberately disabled. That is a valid bootstrap state only while all
+// three authority collections are empty. A partially populated policy is
+// neither disabled nor usable and must fail `xema edition check`; delivery
+// itself always requires the fully armed state.
+//
+// It is deliberately not a lint of taste. Each requirement below names a place
+// where an empty list makes verification impossible, not merely weaker:
+//
+//   policies[]                  -> `image-evidence.mjs` throws "offline trust
+//                                 policy authorizes no signer for <predicate>
+//                                 on channel <channel>" before any cosign call.
+//   trustedCosignBinaryDigests  -> `trusted-executable.mjs` compares the cosign
+//                                 binary digest with `[].includes(...)`, which
+//                                 is false for every possible binary.
+//   trustedGitBinaryDigests     -> same, for the git binary that pins the
+//                                 graded checkouts.
+//
+// The three predicate types are checked separately because a policy can be
+// non-empty and still be unarmed for a stage: the verifier resolves candidates
+// per predicate type, so authorizing only the producer identity leaves the
+// completeness and entitlement stages throwing the same "authorizes no signer"
+// at delivery time - armed-looking, and inert exactly where it matters.
+//
+// ARMING IS JUDGED FOR ONE CHANNEL: the channel of the edition being checked,
+// sealed or verified. A release verification is only ever satisfied by a
+// release signer and a develop one by a develop signer, so the signers of one
+// channel neither arm nor disarm the other: a policy that authorizes the three
+// stages on the release channel and pins both binaries is ARMED for a release
+// edition whatever it says about develop.
+
+export const TrustPolicyArmingState = Object.freeze({
+  ARMED: 'armed',
+  UNARMED: 'unarmed',
+  PARTIAL: 'partial',
+});
+
+/** Arming has no channel-less answer: `channel` is one of the kernel's evidence channels. */
+export function assertArmingChannel(schemas, channel) {
+  if (!schemas.EVIDENCE_CHANNELS.includes(channel)) {
+    throw new Error(
+      `trust-policy arming is judged for one channel; got ${JSON.stringify(channel)}, expected ${schemas.EVIDENCE_CHANNELS.join(' | ')}`,
+    );
+  }
+}
+
+/**
+ * Assess whether a parsed trust policy can authorize anything on `channel`.
+ *
+ * Returns `{ state, armed, unmet }`. `unmet` is empty exactly when `armed` is
+ * true. `unarmed` means the channel has no signer at all in a policy that is
+ * otherwise coherent: the exact, explicit bootstrap state where every authority
+ * collection is empty, or a policy whose signers all belong to another channel.
+ * Anything else that is not armed is `partial`. Each unmet entry names the
+ * field and what makes verification impossible, so the failure is actionable
+ * without reading the verifier.
+ */
+export function assessTrustPolicyArming(policy, schemas, channel) {
+  assertArmingChannel(schemas, channel);
+  const unmet = [];
+  const stages = [
+    ['image-producer', schemas.IMAGE_PRODUCER_PREDICATE_TYPE],
+    ['distribution-completeness', schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE],
+    ['delivery-entitlement', schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE],
+  ];
+  const onChannel = policy.policies.filter((candidate) => candidate.channel === channel);
+  const authorized = stages.filter(([, predicateType]) => onChannel.some((candidate) => candidate.predicateTypes.includes(predicateType)));
+
+  if (policy.policies.length === 0) {
+    unmet.push(
+      'policies[] is empty — no signer identity is authorized, so ' +
+        'verifySigstoreEvidenceDescriptor throws "offline trust policy ' +
+        'authorizes no signer" for every predicate before reading any bundle.',
+    );
+  } else {
+    for (const [stage, predicateType] of stages.filter((candidate) => !authorized.includes(candidate))) {
+      unmet.push(
+        `no policy authorizes the ${stage} predicate ${predicateType} on channel "${channel}" — ` +
+          `that stage of a ${channel} delivery would still throw "authorizes no signer" ` +
+          'while the policy reads as armed.',
+      );
+    }
+  }
+
+  if (policy.trustedCosignBinaryDigests.length === 0) {
+    unmet.push(
+      'trustedCosignBinaryDigests[] is empty — prepareDigestPinnedExecutable ' +
+        'tests membership with [].includes(digest), which is false for every ' +
+        'cosign binary, so no evidence can be verified on any host.',
+    );
+  }
+
+  if (policy.trustedGitBinaryDigests.length === 0) {
+    unmet.push(
+      'trustedGitBinaryDigests[] is empty — the same membership test rejects ' +
+        'every git binary, so no verified release checkout can be established.',
+    );
+  }
+
+  const armed = unmet.length === 0;
+  const bootstrap =
+    policy.policies.length === 0 &&
+    policy.trustedCosignBinaryDigests.length === 0 &&
+    policy.trustedGitBinaryDigests.length === 0;
+  // The channel states nothing while another channel does: its signers and the
+  // binary pins are that channel's arming, not half of this one's.
+  const anotherChannelOnly = onChannel.length === 0 && policy.policies.length > 0;
+  const state = armed
+    ? TrustPolicyArmingState.ARMED
+    : bootstrap || anotherChannelOnly
+      ? TrustPolicyArmingState.UNARMED
+      : TrustPolicyArmingState.PARTIAL;
+
+  return { state, armed, unmet };
+}

package/edition/trusted-executable.mjs

@@ -0,0 +1,166 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  constants as fsConstants,
+  fsyncSync,
+  lstatSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+
+const PREPARED_EXECUTABLES = new WeakMap();
+
+function sha256Digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function validatePreparedExecutable(record, label) {
+  const stats = lstatSync(record.path);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error(
+      `prepared trusted ${label} must be a no-follow regular file`,
+    );
+  }
+  if (record.kind === 'root-owned') {
+    for (const field of ['dev', 'ino', 'uid', 'mode', 'size']) {
+      if (stats[field] !== record.snapshot[field]) {
+        throw new Error(`prepared trusted ${label} file identity changed`);
+      }
+    }
+    let current = record.path;
+    while (true) {
+      const currentStats = lstatSync(current);
+      if (currentStats.uid !== 0 || (currentStats.mode & 0o022) !== 0) {
+        throw new Error(
+          `${label} and every ancestor must be root-owned and not group/world writable`,
+        );
+      }
+      if (current === '/') {break;}
+      current = dirname(current);
+    }
+    if ((stats.mode & 0o777) !== 0o755) {
+      throw new Error(`prepared trusted ${label} must have exact mode 0755`);
+    }
+  }
+  if (sha256Digest(readFileSync(record.path)) !== record.digest) {
+    throw new Error(`prepared trusted ${label} bytes changed`);
+  }
+}
+
+export function prepareDigestPinnedExecutable({
+  executablePath,
+  trustedDigests,
+  label,
+  verifyVersion,
+}) {
+  if (!isAbsolute(executablePath)) {
+    throw new Error(`${label} executable path must be absolute`);
+  }
+  const sourceStats = lstatSync(executablePath);
+  if (!sourceStats.isFile() || sourceStats.isSymbolicLink()) {
+    throw new Error(`${label} executable must be a no-follow regular file`);
+  }
+  const bytes = readFileSync(executablePath);
+  const digest = sha256Digest(bytes);
+  if (!trustedDigests.includes(digest)) {
+    throw new Error(
+      `${label} executable digest ${digest} is not trusted by policy`,
+    );
+  }
+  const directory = mkdtempSync(join(tmpdir(), `xema-trusted-${label}-`));
+  const privatePath = join(directory, basename(executablePath));
+  try {
+    let descriptor;
+    try {
+      descriptor = openSync(
+        privatePath,
+        fsConstants.O_CREAT |
+          fsConstants.O_EXCL |
+          fsConstants.O_WRONLY |
+          fsConstants.O_NOFOLLOW,
+        0o500,
+      );
+      writeFileSync(descriptor, bytes);
+      fsyncSync(descriptor);
+    } finally {
+      if (descriptor !== undefined) {closeSync(descriptor);}
+    }
+    verifyVersion(privatePath);
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  const handle = {
+    path: privatePath,
+    dispose() {
+      rmSync(directory, { recursive: true, force: true });
+    },
+  };
+  PREPARED_EXECUTABLES.set(handle, {
+    kind: 'private-copy',
+    path: privatePath,
+    digest,
+  });
+  return handle;
+}
+
+export function prepareRootOwnedPinnedExecutable({
+  executablePath,
+  trustedDigests,
+  label,
+  verifyVersion,
+}) {
+  if (!isAbsolute(executablePath)) {
+    throw new Error(`${label} executable path must be absolute`);
+  }
+  const initialStats = lstatSync(executablePath);
+  if (!initialStats.isFile() || initialStats.isSymbolicLink()) {
+    throw new Error(`${label} executable must be a no-follow regular file`);
+  }
+  const handle = { path: executablePath, dispose() {} };
+  const record = {
+    kind: 'root-owned',
+    path: executablePath,
+    digest: sha256Digest(readFileSync(executablePath)),
+    snapshot: {
+      dev: initialStats.dev,
+      ino: initialStats.ino,
+      uid: initialStats.uid,
+      mode: initialStats.mode,
+      size: initialStats.size,
+    },
+  };
+  PREPARED_EXECUTABLES.set(handle, record);
+  validatePreparedExecutable(record, label);
+  if (!trustedDigests.includes(record.digest)) {
+    throw new Error(
+      `${label} executable digest ${record.digest} is not trusted by policy`,
+    );
+  }
+  verifyVersion(executablePath);
+  validatePreparedExecutable(record, label);
+  return handle;
+}
+
+export function assertPreparedExecutable(handle, label) {
+  const record = PREPARED_EXECUTABLES.get(handle);
+  if (!record) {
+    throw new Error(`a prepared trusted ${label} executable is required`);
+  }
+  validatePreparedExecutable(record, label);
+  return record.path;
+}
+
+export function exactExecutableOutput(path, args, options = {}) {
+  return execFileSync(path, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+  });
+}

package/edition/verifier-binding.mjs

@@ -0,0 +1,45 @@
+// What the running evidence verifier is held to before it trusts anything:
+// a clean launch environment, an install nobody else can write, and the
+// data-root pin of its own bytes. (The kernel the workspace states is held to
+// the bundled edition protocol by `edition-protocol.mjs`.)
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { assertProtectedPathAncestry } from './evidence-checkout.mjs';
+import { VERIFIER_PROVENANCE_FILE } from './verifier-files.mjs';
+import { parseVerifierProvenance } from './verifier-provenance.mjs';
+
+/** The launch environment carries no variable that changes what code runs. */
+export function assertSanitizedOperatorEnvironment(env) {
+  for (const key of Object.keys(env)) {
+    if (
+      key === 'NODE_OPTIONS' ||
+      key === 'NODE_PATH' ||
+      key.startsWith('DYLD_') ||
+      key.startsWith('LD_') ||
+      key.startsWith('GIT_')
+    ) {
+      throw new Error(
+        `trusted verifier launch refuses inherited control variable ${key}`,
+      );
+    }
+  }
+}
+
+/**
+ * The verifier file that is running (the realpath of `bundlePath`) and its
+ * provenance beside it, after refusing an install anyone else can write or
+ * that a foreign user owns, and a provenance that does not describe this
+ * bundle. Returns the bytes the pin is compared with.
+ */
+export function readRunningVerifier(bundlePath) {
+  const realBundle = realpathSync(bundlePath);
+  assertProtectedPathAncestry(realBundle, 'the evidence verifier install');
+  const bundleBytes = readFileSync(realBundle);
+  const provenanceBytes = readFileSync(
+    join(dirname(realBundle), VERIFIER_PROVENANCE_FILE),
+  );
+  parseVerifierProvenance({ provenanceBytes, bundleBytes });
+  return { bundleBytes, provenanceBytes };
+}

package/edition/verifier-files.mjs

@@ -0,0 +1,8 @@
+// The names and place of the built evidence verifier. Pure constants, shared by
+// the build, the gate and the verifier itself (which is bundled and so must not
+// derive anything from where it sits).
+
+export const VERIFIER_BUNDLE_FILE = 'verify-image-evidence.bundle.mjs';
+export const VERIFIER_PROVENANCE_FILE =
+  'verify-image-evidence.bundle.provenance.json';
+export const VERIFIER_DIST_SUBPATH = Object.freeze(['dist', 'edition']);

package/edition/verifier-kernel-schemas.mjs

@@ -0,0 +1,22 @@
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { kernelPackageDir } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+
+/**
+ * The ONE place the evidence verifier obtains the kernel distribution schemas,
+ * and the edition protocol they implement.
+ *
+ * From source it loads the built kernel the workspace states with `--kernel`,
+ * whose protocol is then trivially the stated one. The verifier build
+ * (`scripts/build-evidence-verifier.mjs`) replaces this module with the
+ * `@xemahq/contracts` distribution schemas and edition protocol identity
+ * bundled from the CLI's own dependency, so the bundle never executes a schema
+ * from outside itself; the entry then holds `--kernel`'s declared protocol
+ * equal to the bundled one.
+ */
+export async function loadVerifierKernelSchemas() {
+  return {
+    schemas: await loadKernelDistributionSchemas(),
+    editionProtocol: assertKernelEditionProtocol(kernelPackageDir()),
+  };
+}

package/edition/verifier-provenance.mjs

@@ -0,0 +1,64 @@
+// The provenance record written beside the evidence verifier bundle, and the
+// one reader of it. The build writes it (`scripts/build-evidence-verifier.mjs`);
+// the data root pins its digest beside the bundle's.
+//
+// Deterministic by construction: no timestamps, no host paths. Every bundled
+// input is {package, version, path relative to ITS package root, sha256}, so the
+// record does not depend on how the dependencies were installed.
+
+import { sha256Digest } from './image-evidence.mjs';
+import { compareStrings } from './string-order.mjs';
+
+export const VERIFIER_PROVENANCE_SCHEMA_VERSION = 1;
+
+const PROVENANCE_KEYS = Object.freeze([
+  'artifactSha256',
+  'esbuild',
+  'inputs',
+  'schemaVersion',
+]);
+const INPUT_KEYS = Object.freeze(['package', 'path', 'sha256', 'version']);
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+const exactKeys = (value, keys) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  Object.keys(value).sort().join() === keys.join();
+
+/** Total order of inputs: package, then path. */
+export const compareProvenanceInputs = (a, b) =>
+  compareStrings(a.package, b.package) || compareStrings(a.path, b.path);
+
+/** Parse provenance bytes strictly, binding them to the bundle they describe. */
+export function parseVerifierProvenance({ provenanceBytes, bundleBytes }) {
+  const provenance = JSON.parse(provenanceBytes.toString('utf8'));
+  if (
+    !exactKeys(provenance, PROVENANCE_KEYS) ||
+    provenance.schemaVersion !== VERIFIER_PROVENANCE_SCHEMA_VERSION ||
+    !exactKeys(provenance.esbuild, ['version']) ||
+    typeof provenance.esbuild.version !== 'string' ||
+    !Array.isArray(provenance.inputs) ||
+    provenance.inputs.length === 0
+  ) {
+    throw new Error('verifier provenance has an invalid structure');
+  }
+  provenance.inputs.forEach((input, index) => {
+    if (
+      !exactKeys(input, INPUT_KEYS) ||
+      INPUT_KEYS.some((key) => typeof input[key] !== 'string' || input[key] === '') ||
+      !SHA256_DIGEST.test(input.sha256) ||
+      input.path.startsWith('/') ||
+      input.path.split('/').includes('..') ||
+      (index > 0 && compareProvenanceInputs(provenance.inputs[index - 1], input) >= 0)
+    ) {
+      throw new Error(
+        `verifier provenance input ${index} is malformed or out of order`,
+      );
+    }
+  });
+  if (provenance.artifactSha256 !== sha256Digest(bundleBytes)) {
+    throw new Error('verifier provenance does not describe this bundle');
+  }
+  return provenance;
+}