@xemahq/xema 0.25.1 → 0.27.0

package/edition/edition-workspace.mjs

@@ -0,0 +1,176 @@
+// The edition library's roots: every directory the tooling reads from is stated
+// by the entry, once, through `configureEditionWorkspace`. Nothing is derived
+// from where this file sits, and no root has a default: a getter on a root the
+// entry did not state throws, naming the flag that states it.
+
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const WorkspaceRoot = Object.freeze({
+  Data: 'dataRoot',
+  Editions: 'editionsRoot',
+  Sources: 'sourcesRoot',
+  Kernel: 'kernelPackageDir',
+  Deploy: 'deployRoot',
+  Cache: 'cacheDir',
+  SourceHash: 'sourceHashPackageDir',
+});
+
+export const WORKSPACE_FLAGS = Object.freeze({
+  [WorkspaceRoot.Data]: '--data-root',
+  [WorkspaceRoot.Editions]: '--editions-root',
+  [WorkspaceRoot.Sources]: '--sources-root',
+  [WorkspaceRoot.Kernel]: '--kernel',
+  [WorkspaceRoot.Deploy]: '--deploy-root',
+  [WorkspaceRoot.Cache]: '--cache-dir',
+  [WorkspaceRoot.SourceHash]: '--source-hash',
+});
+
+const ROOT_MEANING = Object.freeze({
+  [WorkspaceRoot.Data]:
+    'the directory holding the catalogue indices and the trust policy',
+  [WorkspaceRoot.Editions]:
+    'the directory holding <edition-id>/ definitions and locks',
+  [WorkspaceRoot.Sources]:
+    'the directory holding source checkouts at repos/<r> and submodules/<r>',
+  [WorkspaceRoot.Kernel]: 'the BUILT kernel-contracts package directory',
+  [WorkspaceRoot.Deploy]: 'the deploy (chart tree) checkout',
+  [WorkspaceRoot.Cache]: 'a writable directory for fetched artifacts',
+  [WorkspaceRoot.SourceHash]:
+    'the BUILT distribution-source-hash package directory (the source-tree and image-input hash implementation)',
+});
+
+const KERNEL_PACKAGE_SUBPATH = ['packages', 'kernel', 'kernel-contracts'];
+
+let configured = Object.freeze({});
+
+function assertDirectory(name, value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${name} must be a non-empty directory path`);
+  }
+  const path = resolve(value);
+  if (!existsSync(path) || !statSync(path).isDirectory()) {
+    throw new Error(`${name} ${path} is not an existing directory`);
+  }
+  return path;
+}
+
+/**
+ * State the roots. Only the roots a caller passes are configured; the rest stay
+ * unset and throw when read. Replaces any previous configuration.
+ */
+export function configureEditionWorkspace(roots) {
+  const next = {};
+  for (const name of Object.values(WorkspaceRoot)) {
+    if (roots[name] !== undefined) {next[name] = assertDirectory(name, roots[name]);}
+  }
+  for (const name of Object.keys(roots)) {
+    if (!Object.values(WorkspaceRoot).includes(name)) {
+      throw new Error(`unknown workspace root "${name}"`);
+    }
+  }
+  configured = Object.freeze(next);
+  return configured;
+}
+
+function root(name) {
+  const value = configured[name];
+  if (value === undefined) {
+    throw new Error(
+      `the edition workspace has no ${name} (${ROOT_MEANING[name]}); state it with ${WORKSPACE_FLAGS[name]} <dir>`,
+    );
+  }
+  return value;
+}
+
+export const dataRoot = () => root(WorkspaceRoot.Data);
+export const editionsRoot = () => root(WorkspaceRoot.Editions);
+export const sourcesRoot = () => root(WorkspaceRoot.Sources);
+export const kernelPackageDir = () => root(WorkspaceRoot.Kernel);
+export const deployRoot = () => root(WorkspaceRoot.Deploy);
+export const cacheDir = () => root(WorkspaceRoot.Cache);
+export const sourceHashPackageDir = () => root(WorkspaceRoot.SourceHash);
+
+/** A source checkout at its aggregator-relative path, e.g. `repos/xema-base`. */
+export const sourcePath = (repo) => join(sourcesRoot(), repo);
+
+/** The kernel-contracts checkout the built package directory sits in. */
+export function kernelRepoDir() {
+  return resolve(kernelPackageDir(), ...KERNEL_PACKAGE_SUBPATH.map(() => '..'));
+}
+
+/** A built subpath of the kernel package, e.g. `dist/distribution/index.js`. */
+export const kernelDistPath = (...segments) =>
+  join(kernelPackageDir(), 'dist', ...segments);
+
+export const biomeIndexPath = () => join(dataRoot(), 'biome-index.json');
+export const platformServiceIndexPath = () =>
+  join(dataRoot(), 'platform-service-index.json');
+export const runtimeImageSourceIndexPath = () =>
+  join(dataRoot(), 'runtime-image-source-index.json');
+
+/**
+ * Parse the workspace flags out of an argv (both `--flag v` and `--flag=v`),
+ * configure the roots, and return the remaining argv. `needs` names the roots
+ * the entry requires: a missing one is refused here, before any work.
+ */
+export function configureEditionWorkspaceFromArgv(argv, needs) {
+  const byFlag = new Map(
+    Object.entries(WORKSPACE_FLAGS).map(([name, flag]) => [flag, name]),
+  );
+  const roots = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg?.indexOf('=') ?? -1;
+    const flag = eq > 0 ? arg.slice(0, eq) : arg;
+    const name = byFlag.get(flag);
+    if (name === undefined) {
+      rest.push(arg);
+      continue;
+    }
+    const value = eq > 0 ? arg.slice(eq + 1) : argv[(i += 1)];
+    if (typeof value !== 'string' || value.length === 0 || value.startsWith('--')) {
+      throw new Error(`${flag} requires a directory path`);
+    }
+    roots[name] = value;
+  }
+  for (const name of needs) {
+    if (roots[name] === undefined) {
+      throw new Error(
+        `${WORKSPACE_FLAGS[name]} <dir> is required (${ROOT_MEANING[name]})`,
+      );
+    }
+  }
+  configureEditionWorkspace(roots);
+  return rest;
+}
+
+/** The roots configured so far, as the object `configureEditionWorkspace` takes. */
+export const configuredWorkspace = () => ({ ...configured });
+
+/** The flags that re-state the configured roots, for a child entry process. */
+export function workspaceArgv() {
+  return Object.entries(configured).flatMap(([name, value]) => [
+    WORKSPACE_FLAGS[name],
+    value,
+  ]);
+}
+
+/** True when `moduleUrl` is the script node was started with. */
+export function isEntryModule(moduleUrl) {
+  return (
+    typeof process.argv[1] === 'string' &&
+    pathToFileURL(realpathSync(process.argv[1])).href === moduleUrl
+  );
+}
+
+/**
+ * The entry's one call: configure the roots from `process.argv` and remove the
+ * root flags from it, so the entry's own parser sees only its own arguments.
+ */
+export function configureEditionWorkspaceFromProcess(needs) {
+  const rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs);
+  process.argv.splice(2, process.argv.length - 2, ...rest);
+}

package/edition/evidence-checkout.mjs

@@ -0,0 +1,418 @@
+// Grades the checkouts the evidence verifier reads from: the data root and the
+// editions root. Each is judged to ONE standard — a trusted git binary, a
+// location no other user can write, an exact HEAD commit, every file the
+// verifier reads bound byte-for-byte to its HEAD blob, and no untrusted change
+// anywhere in the repository (the commit is what the completeness signature
+// binds to, so a checkout that is not exactly that commit is not that commit).
+//
+// Nothing here knows where this module sits: the verifier's own integrity is
+// bound by the data-root pin of its bundle (`evidence-trust-policy.mjs`), not by
+// a checkout of its source.
+
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import {
+  assertPreparedExecutable,
+  exactExecutableOutput,
+  prepareRootOwnedPinnedExecutable,
+} from './trusted-executable.mjs';
+
+const GIT_VERSION_PATTERN = /^git version (\d+\.\d+\.\d+)(?: .*)?\n?$/;
+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',
+]);
+
+/**
+ * The largest output one git call here may return. Node's default `maxBuffer`
+ * is 1 MiB, and a graded file can be larger (the Sigstore trusted root is up to
+ * 8 MiB); with the default the verifier could not bind it to its HEAD blob and
+ * would fail with `spawnSync git ENOBUFS`, which names neither the file nor the
+ * limit. 64 MiB is a bound, not a hope: far above any file graded here and far
+ * below anything that would matter to the host.
+ */
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+function git(trustedGit, directory, args, encoding = 'utf8') {
+  const gitBinary = assertPreparedExecutable(trustedGit, 'git');
+  const output = execFileSync(
+    gitBinary,
+    [...GIT_SAFE_CONFIG, '-C', directory, ...args],
+    {
+      encoding,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: GIT_ENV,
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+    },
+  );
+  assertPreparedExecutable(trustedGit, 'git');
+  return output;
+}
+
+export function prepareTrustedGitBinary({ gitBinary, policy }) {
+  return prepareRootOwnedPinnedExecutable({
+    executablePath: gitBinary,
+    trustedDigests: policy.trustedGitBinaryDigests,
+    label: 'git',
+    verifyVersion(privateBinary) {
+      const output = exactExecutableOutput(privateBinary, ['--version'], {
+        env: GIT_ENV,
+        timeout: 10_000,
+      });
+      const match = GIT_VERSION_PATTERN.exec(output);
+      if (!match) {
+        throw new Error('Git version output is not exact');
+      }
+      if (match[1] !== policy.gitVersion) {
+        throw new Error(
+          `Git version does not match pinned ${policy.gitVersion}`,
+        );
+      }
+    },
+  });
+}
+
+function assertContained(root, candidate, label, within) {
+  const rel = relative(root, candidate);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${label} is outside ${within}`);
+  }
+}
+
+/**
+ * `path` and every ancestor up to `/` must be owned by root or the current user
+ * and not group/world writable. The refusal names the offending directory, its
+ * mode and its owner: the fault is almost always one specific ancestor, and the
+ * reader cannot otherwise tell which, nor whether it failed on ownership or on
+ * the write bits.
+ */
+export function assertProtectedPathAncestry(path, label) {
+  const currentUid =
+    typeof process.getuid === 'function' ? process.getuid() : undefined;
+  let current = realpathSync(path);
+  while (true) {
+    const stats = lstatSync(current);
+    const foreignOwner =
+      currentUid !== undefined && stats.uid !== 0 && stats.uid !== currentUid;
+    const groupOrWorldWritable = (stats.mode & 0o022) !== 0;
+    if (foreignOwner || groupOrWorldWritable) {
+      throw new Error(
+        `${label} and every ancestor must be verifier/root-owned and not group/world writable — ` +
+          `${current} is ${foreignOwner ? `owned by uid ${stats.uid} (running as uid ${currentUid})` : `mode ${(stats.mode & 0o7777).toString(8).padStart(4, '0')}`}`,
+      );
+    }
+    if (current === '/') {break;}
+    current = dirname(current);
+  }
+}
+
+function dirtyPaths(trustedGit, repositoryRoot) {
+  const records = git(
+    trustedGit,
+    repositoryRoot,
+    ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+    'buffer',
+  )
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  const entries = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    const status = record.slice(0, 2);
+    entries.push({ status, path: record.slice(3) });
+    if (status[0] === 'R' || status[0] === 'C') {
+      entries.push({ status, path: records[index + 1] });
+      index += 1;
+    }
+  }
+  return entries;
+}
+
+function assertSafeWorktreeFile(path, expectedMode, label) {
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error(`${label} must be a no-follow regular file`);
+  }
+  if (typeof process.getuid === 'function' && stats.uid !== process.getuid()) {
+    throw new Error(`${label} is not owned by the current user`);
+  }
+  const actualMode = stats.mode & 0o777;
+  if (actualMode !== expectedMode || (actualMode & 0o022) !== 0) {
+    throw new Error(
+      `${label} must have exact mode ${expectedMode.toString(8)}`,
+    );
+  }
+}
+
+function parseTreeRecord(record, expectedPath, label) {
+  const match = /^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/.exec(record);
+  if (!match || match[3] !== expectedPath) {
+    throw new Error(
+      `${label} "${expectedPath}" is absent or has an untrusted HEAD mode`,
+    );
+  }
+  return { mode: match[1], objectId: match[2] };
+}
+
+function assertNormalIndexFlags(trustedGit, repositoryRoot, path, label) {
+  const tagged = git(
+    trustedGit,
+    repositoryRoot,
+    ['ls-files', '--stage', '-v', '-z', '--', path],
+    'buffer',
+  )
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  if (tagged.length !== 1 || !tagged[0].startsWith('H ')) {
+    throw new Error(
+      `${label} "${path}" has skip-worktree, assume-unchanged, or unexpected index state`,
+    );
+  }
+  const debug = git(trustedGit, repositoryRoot, [
+    'ls-files',
+    '--debug',
+    '--',
+    path,
+  ]);
+  const flags = /\bflags:\s+(\d+)\s*$/m.exec(debug);
+  if (!flags || flags[1] !== '0') {
+    throw new Error(`${label} "${path}" has non-zero Git index flags`);
+  }
+}
+
+/**
+ * `path` is a repository-root-relative POSIX path. It must be exactly one HEAD
+ * blob, carry no index flags, and match its HEAD bytes and mode in the working
+ * tree. `label` names what the path IS in every refusal, so a reader can tell
+ * which checkout refused.
+ */
+function assertHeadBoundPath(trustedGit, repositoryRoot, path, label) {
+  const records = git(
+    trustedGit,
+    repositoryRoot,
+    ['ls-tree', '-z', 'HEAD', '--', path],
+    'buffer',
+  )
+    .toString('utf8')
+    .split('\0')
+    .filter(Boolean);
+  if (records.length !== 1) {
+    throw new Error(`${label} "${path}" is not one exact HEAD blob`);
+  }
+  const { mode, objectId } = parseTreeRecord(records[0], path, label);
+  assertNormalIndexFlags(trustedGit, repositoryRoot, path, label);
+
+  const absolutePath = resolve(repositoryRoot, path);
+  assertContained(
+    repositoryRoot,
+    absolutePath,
+    `${label} "${path}"`,
+    `the checkout ${repositoryRoot}`,
+  );
+  assertSafeWorktreeFile(
+    absolutePath,
+    mode === '100755' ? 0o755 : 0o644,
+    `${label} "${path}"`,
+  );
+  const headBytes = git(
+    trustedGit,
+    repositoryRoot,
+    ['cat-file', 'blob', objectId],
+    'buffer',
+  );
+  if (!readFileSync(absolutePath).equals(headBytes)) {
+    throw new Error(`${label} "${path}" does not match its HEAD blob`);
+  }
+}
+
+/**
+ * Locate the Git checkout a root sits in. Locating it is separate from judging
+ * it — see {@link assertTrustedCheckoutLocation}.
+ */
+export function locateCheckout({ root, trustedGit, label }) {
+  assertPreparedExecutable(trustedGit, 'git');
+  let repositoryRoot;
+  try {
+    repositoryRoot = realpathSync(
+      git(trustedGit, root, ['rev-parse', '--show-toplevel']).trim(),
+    );
+  } catch {
+    throw new Error(`${label} verification requires a trusted Git checkout`);
+  }
+  const gitDirectory = realpathSync(
+    git(trustedGit, repositoryRoot, ['rev-parse', '--absolute-git-dir']).trim(),
+  );
+  return { repositoryRoot, gitDirectory };
+}
+
+/**
+ * WHERE the checkout is: no ancestor may be writable by anyone but its owner or
+ * root, or another local process could swap the inputs between verification and
+ * use.
+ *
+ * This is a property of the MACHINE, not of the repository's contents, and the
+ * two are deliberately separately callable and separately tested: fused, every
+ * content test depended on the ambient environment (a runner whose `/home/<user>`
+ * is 0777 failed them all) and this rule, the one with real security weight, had
+ * no direct test. There is deliberately NO option to skip it in
+ * {@link gradeTrustedCheckout}.
+ */
+export function assertTrustedCheckoutLocation(
+  { repositoryRoot, gitDirectory },
+  label,
+) {
+  assertProtectedPathAncestry(repositoryRoot, `${label} checkout`);
+  assertProtectedPathAncestry(gitDirectory, `${label} Git directory`);
+}
+
+/**
+ * WHAT the checkout contains: an exact HEAD, every required path bound to its
+ * HEAD blob, and no untrusted working-tree change anywhere in the repository.
+ *
+ * `requirements` are `{root, label, requiredPaths}`: each `root` sits anywhere
+ * inside `repositoryRoot` and each required path is relative to its root, so it
+ * is re-rooted to the repository before git is asked. A path that resolves
+ * outside its root is refused BY NAME before git runs.
+ */
+export function verifyCheckoutContents({
+  repositoryRoot,
+  requirements,
+  trustedGit,
+  expectedCommit,
+}) {
+  const commit = git(trustedGit, repositoryRoot, [
+    'rev-parse',
+    '--verify',
+    'HEAD^{commit}',
+  ]).trim();
+  if (!COMMIT_PATTERN.test(commit)) {
+    throw new Error(`${repositoryRoot} HEAD is not an exact Git commit`);
+  }
+  if (expectedCommit !== undefined && commit !== expectedCommit) {
+    throw new Error(`${repositoryRoot} HEAD changed during verification`);
+  }
+  for (const { root, label, requiredPaths } of requirements) {
+    if (requiredPaths.length === 0) {
+      throw new Error(
+        `the ${label} checkout is graded for at least one path; none was named`,
+      );
+    }
+    for (const requiredPath of requiredPaths) {
+      const absolutePath = resolve(root, requiredPath);
+      assertContained(
+        root,
+        absolutePath,
+        `${label} path "${requiredPath}"`,
+        `the ${label} ${root}`,
+      );
+      assertHeadBoundPath(
+        trustedGit,
+        repositoryRoot,
+        relative(repositoryRoot, absolutePath).split(sep).join('/'),
+        label,
+      );
+    }
+  }
+  const unexpected = dirtyPaths(trustedGit, repositoryRoot).map(
+    (entry) => `${entry.status} ${entry.path}`,
+  );
+  if (unexpected.length > 0) {
+    throw new Error(
+      `checkout ${repositoryRoot} has untrusted source changes: ${unexpected.join(', ')}`,
+    );
+  }
+  return { repositoryRoot, commit };
+}
+
+/**
+ * Locate, judge the location of, and grade the contents of the checkout one
+ * root sits in. `root` and `requiredPaths` are as in {@link verifyCheckoutContents}.
+ */
+export function gradeTrustedCheckout({
+  root,
+  requiredPaths,
+  label,
+  trustedGit,
+  expectedCommit,
+}) {
+  const canonicalRoot = realpathSync(root);
+  const location = locateCheckout({ root: canonicalRoot, trustedGit, label });
+  assertTrustedCheckoutLocation(location, label);
+  return verifyCheckoutContents({
+    repositoryRoot: location.repositoryRoot,
+    requirements: [{ root: canonicalRoot, label, requiredPaths }],
+    trustedGit,
+    expectedCommit,
+  });
+}
+
+/**
+ * Grade several roots, each repository ONCE: roots in the same repository are
+ * graded together under one HEAD and one clean-tree check. Returns a Map from
+ * each (canonical) root to `{repositoryRoot, commit}`. `expected` is an earlier
+ * result of this function; passing it demands every HEAD is unchanged.
+ */
+export function gradeTrustedCheckouts({ grades, trustedGit, expected }) {
+  const byRepository = new Map();
+  for (const { root, label, requiredPaths } of grades) {
+    const canonicalRoot = realpathSync(root);
+    const location = locateCheckout({ root: canonicalRoot, trustedGit, label });
+    const group = byRepository.get(location.repositoryRoot) ?? {
+      location,
+      labels: [],
+      requirements: [],
+    };
+    group.labels.push(label);
+    group.requirements.push({ root: canonicalRoot, label, requiredPaths });
+    byRepository.set(location.repositoryRoot, group);
+  }
+  const result = new Map();
+  for (const [repositoryRoot, group] of byRepository) {
+    assertTrustedCheckoutLocation(group.location, group.labels.join(' + '));
+    const graded = verifyCheckoutContents({
+      repositoryRoot,
+      requirements: group.requirements,
+      trustedGit,
+      expectedCommit: expected?.get(group.requirements[0].root)?.commit,
+    });
+    for (const { root } of group.requirements) {
+      result.set(root, graded);
+    }
+  }
+  return result;
+}
+
+/**
+ * A verifier input (the evidence tree, the replay state) must live outside every
+ * graded checkout: a path inside one is graded as source, not as input.
+ */
+export function assertExternalInput(repositoryRoots, path, label) {
+  const canonical = realpathSync(path);
+  for (const repositoryRoot of repositoryRoots) {
+    const rel = relative(repositoryRoot, canonical);
+    if (rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..')) {
+      throw new Error(`${label} must be outside the checkout ${repositoryRoot}`);
+    }
+  }
+  return canonical;
+}

package/edition/evidence-grammars.mjs

@@ -0,0 +1,16 @@
+// The lexical grammars the evidence plane checks, declared once. The kernel
+// states the same shapes inside its schemas (`@xemahq/contracts` distribution
+// schemas keep them module-private and export no pattern), so the evidence
+// plane has no kernel export to import; this is the ONE CLI declaration every
+// evidence module reads.
+
+/** A full 40-hex lowercase git commit. */
+export const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+/** 64 lowercase hex digits, no algorithm prefix. */
+export const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+/** An OCI/sigstore content digest: `sha256:` and 64 lowercase hex digits. */
+export const SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+/** `owner/repository` of a GitHub repository. */
+export const GITHUB_REPOSITORY_PATTERN = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
+/** A GitHub branch or tag ref. */
+export const GITHUB_REF_PATTERN = /^refs\/(?:heads|tags)\/.+$/;