@xemahq/xema 0.25.1 → 0.27.0

package/edition/kernel-contract-authority.mjs

@@ -0,0 +1,443 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { kernelRepoDir } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+
+const GIT_ENV = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_NO_REPLACE_OBJECTS: '1',
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_PAGER: 'cat',
+  LC_ALL: 'C',
+  PATH: '/usr/bin:/bin',
+});
+const GIT_SAFE_CONFIG = Object.freeze([
+  '-c',
+  'core.fsmonitor=false',
+  '-c',
+  'core.hooksPath=/dev/null',
+  '-c',
+  'core.attributesFile=/dev/null',
+  '--no-pager',
+]);
+const GIT_TREE_RECORD_PATTERN =
+  /^(100644|100755|120000|160000) (blob|commit) ([a-f0-9]{40,64})\t(.+)$/;
+
+function git(repositoryDirectory, args, encoding = 'utf8') {
+  return execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, ...args],
+    {
+      encoding,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: GIT_ENV,
+    },
+  );
+}
+
+function exactHeadCommit(repositoryDirectory) {
+  const commit = git(repositoryDirectory, [
+    'rev-parse',
+    '--verify',
+    'HEAD^{commit}',
+  ]).trim();
+  if (!COMMIT_PATTERN.test(commit)) {
+    throw new Error('kernel contract repository HEAD is not an exact commit');
+  }
+  return commit;
+}
+
+/** True when `ancestor` is reachable from `descendant`. Never throws. */
+function isAncestor(repositoryDirectory, ancestor, descendant) {
+  try {
+    git(repositoryDirectory, ['merge-base', '--is-ancestor', ancestor, descendant]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function assertCommitExists(repositoryDirectory, sourceCommit) {
+  if (!COMMIT_PATTERN.test(sourceCommit)) {
+    throw new Error(
+      `kernel contract authority has invalid source commit "${String(sourceCommit)}"`,
+    );
+  }
+  try {
+    git(repositoryDirectory, ['cat-file', '-e', `${sourceCommit}^{commit}`]);
+  } catch {
+    throw new Error(
+      `kernel contract authority commit ${sourceCommit} is absent from the local Git object database`,
+    );
+  }
+}
+
+function exactOrigin(repositoryDirectory, schemas) {
+  const origin = git(repositoryDirectory, [
+    'remote',
+    'get-url',
+    'origin',
+  ]).trim();
+  if (origin !== schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL) {
+    throw new Error(
+      `kernel contract repository origin must be exactly ${schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL}`,
+    );
+  }
+  return origin;
+}
+
+const GIT_MAX_BUFFER = 1024 * 1024 * 1024;
+
+/**
+ * The blob record of every tree entry at `sourceCommit`, by path: ONE
+ * `ls-tree -r`, however many authority sources there are. A path absent from
+ * the map is absent from the commit or is not a blob.
+ */
+function gitTreeAtCommit(repositoryDirectory, sourceCommit) {
+  const records = execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, 'ls-tree', '-r', '-z', sourceCommit],
+    { encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], env: GIT_ENV, maxBuffer: GIT_MAX_BUFFER },
+  )
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  const tree = new Map();
+  for (const record of records) {
+    const match = GIT_TREE_RECORD_PATTERN.exec(record);
+    if (match) {tree.set(match[4], { mode: match[1], type: match[2], objectId: match[3] });}
+  }
+  return tree;
+}
+
+function missingSource(expectedPath) {
+  return new Error(
+    `kernel contract authority source "${expectedPath}" is missing or is not an exact Git blob`,
+  );
+}
+
+/**
+ * `{path, mode, objectId}` of each of `paths` at `sourceCommit`, in order.
+ * Refuses a path that is missing or is not a blob.
+ */
+function gitBlobRecordsAtCommit(repositoryDirectory, sourceCommit, paths) {
+  const tree = gitTreeAtCommit(repositoryDirectory, sourceCommit);
+  return paths.map((path) => {
+    const entry = tree.get(path);
+    if (entry === undefined || entry.type !== 'blob') {throw missingSource(path);}
+    return { path, mode: entry.mode, objectId: entry.objectId };
+  });
+}
+
+/**
+ * {@link gitBlobRecordsAtCommit} with each blob's exact bytes, read by ONE
+ * `cat-file --batch` and matched to the object id it was asked for.
+ */
+function gitBlobsAtCommit(repositoryDirectory, sourceCommit, paths) {
+  const records = gitBlobRecordsAtCommit(repositoryDirectory, sourceCommit, paths);
+  if (records.length === 0) {return [];}
+  const output = execFileSync(
+    '/usr/bin/git',
+    [...GIT_SAFE_CONFIG, '-C', repositoryDirectory, 'cat-file', '--batch'],
+    {
+      input: Buffer.from(records.map((record) => `${record.objectId}\n`).join(''), 'utf8'),
+      encoding: 'buffer',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: GIT_ENV,
+      maxBuffer: GIT_MAX_BUFFER,
+    },
+  );
+  let offset = 0;
+  const sources = records.map((record) => {
+    const headerEnd = output.indexOf(0x0a, offset);
+    const header = headerEnd === -1 ? '' : output.subarray(offset, headerEnd).toString('utf8');
+    const match = /^([a-f0-9]{40,64}) blob (0|[1-9][0-9]*)$/.exec(header);
+    if (!match || match[1] !== record.objectId) {throw missingSource(record.path);}
+    const size = Number(match[2]);
+    const start = headerEnd + 1;
+    if (!Number.isSafeInteger(size) || start + size >= output.length || output[start + size] !== 0x0a) {
+      throw missingSource(record.path);
+    }
+    offset = start + size + 1;
+    return { ...record, blob: Buffer.from(output.subarray(start, start + size)) };
+  });
+  if (offset !== output.length) {
+    throw new Error('kernel contract authority sources: git returned more than was asked for');
+  }
+  return sources;
+}
+
+function exactAuthorityJson(value) {
+  return JSON.stringify(value);
+}
+
+export function assertKernelContractAuthorityEqual(actual, expected, label) {
+  if (exactAuthorityJson(actual) !== exactAuthorityJson(expected)) {
+    throw new Error(
+      `${label} does not exactly match kernel contract authority`,
+    );
+  }
+  return actual;
+}
+
+export async function readKernelContractAuthorityAtCommit({
+  repositoryDirectory = kernelRepoDir(),
+  sourceCommit,
+  schemas,
+}) {
+  if (!schemas) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  exactOrigin(repositoryDirectory, schemas);
+  assertCommitExists(repositoryDirectory, sourceCommit);
+  const sources = gitBlobsAtCommit(
+    repositoryDirectory,
+    sourceCommit,
+    schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+  );
+  const contentDigest =
+    await schemas.computeKernelContractAuthorityContentDigest(sources);
+  return {
+    schemaVersion: 1,
+    generatorIdentity: schemas.XEMA_KERNEL_CONTRACT_AUTHORITY_GENERATOR,
+    repositoryUrl: schemas.XEMA_KERNEL_CONTRACT_REPOSITORY_URL,
+    sourceCommit,
+    sourcePaths: [...schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS],
+    contentHashAlgorithm:
+      schemas.KernelContractContentHashAlgorithm.LengthFramedGitPathModeBlobV1,
+    contentDigest,
+  };
+}
+
+export function assertExactCleanKernelContractCheckout({
+  repositoryDirectory = kernelRepoDir(),
+  sourceCommit,
+  schemas,
+}) {
+  exactOrigin(repositoryDirectory, schemas);
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head !== sourceCommit) {
+    throw new Error(
+      `kernel contract repository HEAD ${head} does not match authority commit ${sourceCommit}`,
+    );
+  }
+  const status = git(
+    repositoryDirectory,
+    ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+    'buffer',
+  );
+  if (status.byteLength !== 0) {
+    throw new Error(
+      'kernel contract repository must be exactly clean for trusted generation',
+    );
+  }
+  const tracked = git(repositoryDirectory, ['ls-files', '-v', '-z'], 'buffer')
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  const hidden = tracked.find((record) => !record.startsWith('H '));
+  if (hidden) {
+    throw new Error(
+      `kernel contract repository has skip-worktree, assume-unchanged, or unexpected index state: ${hidden.slice(2)}`,
+    );
+  }
+  // ONE index listing and ONE batched blob read for the whole source set.
+  const indexByPath = new Map();
+  for (const record of git(repositoryDirectory, ['ls-files', '--stage', '-v', '-z'], 'buffer')
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean)) {
+    const path = record.slice(record.indexOf('\t') + 1);
+    indexByPath.set(path, [...(indexByPath.get(path) ?? []), record]);
+  }
+  const committed = new Map(
+    gitBlobsAtCommit(
+      repositoryDirectory,
+      sourceCommit,
+      schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS,
+    ).map((source) => [source.path, source]),
+  );
+  for (const path of schemas.XEMA_KERNEL_CONTRACT_SOURCE_PATHS) {
+    const indexRecords = indexByPath.get(path) ?? [];
+    const indexMatch =
+      indexRecords.length === 1
+        ? /^H (100644) ([a-f0-9]{40,64}) 0\t(.+)$/.exec(indexRecords[0])
+        : null;
+    if (!indexMatch || indexMatch[3] !== path) {
+      throw new Error(
+        `kernel contract source has hidden flags or unexpected index state: ${path}`,
+      );
+    }
+    const source = committed.get(path);
+    const worktreePath = join(repositoryDirectory, path);
+    const stats = lstatSync(worktreePath);
+    if (
+      source.mode !== schemas.XEMA_KERNEL_CONTRACT_SOURCE_MODE ||
+      source.objectId !== indexMatch[2] ||
+      !stats.isFile() ||
+      stats.isSymbolicLink() ||
+      (stats.mode & 0o777) !== 0o644 ||
+      !readFileSync(worktreePath).equals(source.blob)
+    ) {
+      throw new Error(
+        `kernel contract source does not exactly match its committed Git mode/blob: ${path}`,
+      );
+    }
+  }
+  return head;
+}
+
+export async function buildTrustedKernelContractAuthority({
+  repositoryDirectory = kernelRepoDir(),
+  schemas,
+}) {
+  const sourceCommit = exactHeadCommit(repositoryDirectory);
+  assertExactCleanKernelContractCheckout({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  const authority = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  assertExactCleanKernelContractCheckout({
+    repositoryDirectory,
+    sourceCommit,
+    schemas,
+  });
+  return authority;
+}
+
+/**
+ * Is the pinned authority on the kernel history we ship — and has the kernel's
+ * contract surface moved since it?
+ *
+ * THIS USED TO REFUSE ON ANY CONTENT DRIFT, and that made the image-contract
+ * pin an input every kernel commit could invalidate. Measured 2026-10-01:
+ * `dist-check` was red with "the kernel contract surface CHANGED" because
+ * kernel `a348e71` added one member, `ComposedProcess`, to
+ * `RuntimeImageSubjectKind` — a kind no committed image lock carries and this
+ * repository never mints. The printed remedy, `xema edition index runtime-image-source
+ * --repin-contract-authority`, rewrites `contractAuthority` in EVERY `images.lock.json`,
+ * which changes each lock's `normalizedImageLockDigest` (bound by the signed
+ * completeness statement) and orphans every signed producer statement (whose
+ * `predicate.contractAuthority` must equal the pin). Nine sealed editions, plus
+ * every customer edition minted under the same pin, would have lost their
+ * evidence for a change that altered no image. The same would follow from a
+ * new export in `distribution/index.ts`, which is one of the authority's
+ * source paths and is touched by every distribution-contract addition.
+ *
+ * Owner ruling, 2026-10-01: an unrelated change must not force historical
+ * editions to re-resolve or re-seal their image lists unless IMAGE SEMANTICS
+ * changed. The pin is a DELIBERATE image-contract version, advanced by the
+ * repin transaction when an edition needs semantics the pinned contract cannot
+ * describe — never by kernel HEAD moving underneath it.
+ *
+ * So this now REFUSES only what is a defect:
+ *   - a pin that is not an ancestor of kernel HEAD (a different history — see
+ *     below), and
+ *   - (in the caller) a pin whose recorded digest does not re-derive from its
+ *     own commit's blobs.
+ * Drift is RETURNED as the list of moved source paths, and the caller reports
+ * it. It is not silent: it is printed on every check, naming each path.
+ *
+ * What keeps a stale pin from LYING about an image lock: the standalone
+ * verifier is built from kernel source that descends from the pin and strict-
+ * parses every image lock and producer statement, and producer evidence is
+ * refused unless its signed `contractAuthority` equals the pin. A lock that
+ * used semantics newer than the pin therefore fails closed at verification,
+ * loudly — and that is the moment a repin is genuinely owed.
+ *
+ * The pin must still be an ancestor of HEAD. A pin on a different history is
+ * not "behind", it is unrelated, and recomputing a digest across a fork would
+ * compare content from a branch nobody is shipping.
+ */
+async function assessAuthorityLineage({ authority, repositoryDirectory, schemas }) {
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head === authority.sourceCommit) {return { head, changedPaths: [] };}
+
+  if (!isAncestor(repositoryDirectory, authority.sourceCommit, head)) {
+    throw new Error(
+      `kernel contract authority commit ${authority.sourceCommit} is not an ancestor of kernel HEAD ` +
+        `${head}. The pin is on a different history (a force push, or a checkout of another branch), ` +
+        'so it cannot be compared by content — repin deliberately against the history you intend to ship.',
+    );
+  }
+
+  const atHead = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit: head,
+    schemas,
+  });
+  if (atHead.contentDigest === authority.contentDigest) {
+    return { head, changedPaths: [] };
+  }
+
+  const changedPaths = [];
+  const pinned = gitBlobRecordsAtCommit(repositoryDirectory, authority.sourceCommit, authority.sourcePaths);
+  const current = gitBlobRecordsAtCommit(repositoryDirectory, head, authority.sourcePaths);
+  for (const [index, path] of authority.sourcePaths.entries()) {
+    if (pinned[index].objectId !== current[index].objectId) {changedPaths.push(path);}
+  }
+  return { head, changedPaths };
+}
+
+/** One line naming the drift, for callers that report it. */
+export function describeKernelContractAuthorityDrift({ authority, head, changedPaths }) {
+  return (
+    `kernel contract authority ${authority.sourceCommit} is behind kernel HEAD ${head}: ` +
+    `${changedPaths.length} contract source path(s) moved (${changedPaths.join(', ')}). ` +
+    'This is NOT a refusal — image locks stay pinned to the contract they were minted ' +
+    'under. Repin (`xema edition index runtime-image-source --repin-contract-authority`) only ' +
+    'when an edition needs image semantics the pinned contract cannot describe; that ' +
+    'repin re-binds every edition\'s image evidence.'
+  );
+}
+
+export async function validateKernelContractAuthorityFromGit({
+  authority,
+  repositoryDirectory = kernelRepoDir(),
+  schemas,
+  requireHeadMatch = true,
+  requireCleanCheckout = false,
+  // Called with `{ authority, head, changedPaths }` when the pin is an ancestor
+  // of HEAD but the contract surface has moved since it. Reporting, never
+  // refusing — see `assessAuthorityLineage`.
+  onDrift = () => {},
+}) {
+  if (!authority || typeof authority !== 'object') {
+    throw new Error('kernel contract authority is required');
+  }
+  if (requireHeadMatch) {
+    const { head, changedPaths } = await assessAuthorityLineage({
+      authority,
+      repositoryDirectory,
+      schemas,
+    });
+    if (changedPaths.length > 0) {onDrift({ authority, head, changedPaths });}
+  }
+  if (requireCleanCheckout) {
+    assertExactCleanKernelContractCheckout({
+      repositoryDirectory,
+      sourceCommit: authority.sourceCommit,
+      schemas,
+    });
+  }
+  const expected = await readKernelContractAuthorityAtCommit({
+    repositoryDirectory,
+    sourceCommit: authority.sourceCommit,
+    schemas,
+  });
+  assertKernelContractAuthorityEqual(
+    authority,
+    expected,
+    'runtime image source index',
+  );
+  return authority;
+}