@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/source-closure.mjs

@@ -0,0 +1,115 @@
+#!/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> --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,
+    // 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/store-publisher-trust.mjs

@@ -0,0 +1,40 @@
+// The Store publishers a vendor edition's data root trusts: read from
+// `store-publisher-identities.json` and written to the lock as
+// `storePublisherTrust`. The kernel lock schema is the ONE validator (non-empty,
+// sorted by anchorKey, unique, https issuer, no refs/pull/); it runs at the
+// resolver's `parseUnsealedDistributionLock` step, so nothing here re-checks it.
+
+import { existsSync } from 'node:fs';
+
+import { storePublisherIdentitiesPath } from './edition-workspace.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/** The data root's trusted Store publishers, or `undefined` when it holds no such file. */
+export function readStorePublisherTrust() {
+  const path = storePublisherIdentitiesPath();
+  if (!existsSync(path)) {return undefined;}
+  const document = readStrictJsonFile(path);
+  if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error(`${path}: must be a JSON object`);
+  }
+  const unknown = Object.keys(document).filter((key) => key !== 'schemaVersion' && key !== 'publishers');
+  if (unknown.length > 0) {
+    throw new Error(`${path}: unknown top-level key ${unknown.map((key) => JSON.stringify(key)).join(', ')}`);
+  }
+  if (document.schemaVersion === 1) {
+    throw new Error(
+      `${path}: schemaVersion 1 states no signer; move the file to schemaVersion 2 (\`oidcIssuer\` and \`identity\` per anchor)`,
+    );
+  }
+  if (document.schemaVersion !== 2) {
+    throw new Error(`${path}: schemaVersion must be 2, got ${JSON.stringify(document.schemaVersion)}`);
+  }
+  const { publishers } = document;
+  if (!Array.isArray(publishers) || publishers.some((row) => row === null || typeof row !== 'object' || Array.isArray(row))) {
+    throw new Error(`${path}: publishers must be an array of objects`);
+  }
+  // Only `sourceRepositories` (vendor-ops' key) is dropped; every other key reaches the kernel's
+  // strict schema unchanged, so a stray or misspelt key is refused there, never dropped here.
+  return publishers.map(({ sourceRepositories: _vendorOps, ...row }) => row);
+}
+

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/third-party-admission.mjs

@@ -0,0 +1,118 @@
+// Admission of third-party image subjects (XEMA-1611 design section 4), beside `externalSourceRepositoryPins` and
+// `verifyDistributionImageEvidenceSet` of `image-evidence.mjs`. Pure over data: the pins come from the data root's
+// `third-party-source-pins.json` (held to the evidence trust pin by the entry), the statement and bundle from a
+// descriptor `verifySigstoreEvidenceDescriptor` has just verified.
+
+import { assertCertificateExtensions } from './third-party-certificate-extensions.mjs';
+
+/** The declared source kind that names a third-party pin. */
+const OCI_SOURCE_KIND = 'oci';
+const FIRST_PARTY_LAYOUT_PREFIX = /^(?:repos|submodules)\//u;
+
+const repositoryPathOf = (repositoryUrl) => new URL(repositoryUrl).pathname.replace(/^\//u, '').replace(/\.git$/u, '');
+
+/**
+ * The repository pins of the edition's declared OCI sources, derived from their third-party source pins:
+ * `repo` (the pinned `owner/name`), `repositoryUrl` and `sourceCommit`. Every declared OCI source must be pinned (a
+ * missing or empty pin file refuses, with the loader's reason), and the pin must not collide with an index pin or a git
+ * source, nor sit under the first-party layout (`repos/`, `submodules/`). A declared source that ships no image yields no
+ * pin; every subject of a source must agree on the pinned commit.
+ *
+ * @returns {Map<string, {repo: string, repositoryUrl: string, sourceCommit: string}>}
+ */
+export function thirdPartySourceRepositoryPins({ distribution, imageLock, repositoryPins, thirdPartyPins }) {
+  const sources = distribution.sources ?? [];
+  const derived = new Map();
+  for (const source of sources) {
+    if (source.kind !== OCI_SOURCE_KIND) {continue;}
+    const pin = thirdPartyPins.byName(source.name);
+    if (pin === undefined) {
+      throw new Error(
+        `edition source "${source.name}" is kind "${OCI_SOURCE_KIND}", but ${thirdPartyPins.reason ?? `the data root's third-party source pins hold no pin named "${source.name}"`}`,
+      );
+    }
+    if (FIRST_PARTY_LAYOUT_PREFIX.test(pin.repository)) {
+      throw new Error(`third-party source "${pin.name}" pins repository "${pin.repository}", which is under the first-party layout (repos/ or submodules/)`);
+    }
+    if (repositoryPins.has(pin.repository)) {
+      throw new Error(`third-party source "${pin.name}" repository "${pin.repository}" shadows a repository pin the runtime image source index already commits`);
+    }
+    const shadowed = sources.find((candidate) => candidate.kind === 'git' && (candidate.name === pin.repository || candidate.name === pin.name));
+    if (shadowed !== undefined) {
+      throw new Error(`third-party source "${pin.name}" (${pin.repository}) collides with the git source "${shadowed.name}" of the same edition`);
+    }
+    const subjects = imageLock.subjects.filter((subject) => subject.repo === pin.repository);
+    if (subjects.length === 0) {continue;}
+    const wrong = subjects.filter((subject) => subject.sourceCommit !== pin.sourceCommit);
+    if (wrong.length > 0) {
+      throw new Error(
+        `third-party source "${pin.name}" is pinned at ${pin.sourceCommit}, but images.lock.json builds ${wrong.map((subject) => `${subject.kind}:${subject.id}`).join(', ')} at ${[...new Set(wrong.map((subject) => subject.sourceCommit))].join(', ')}`,
+      );
+    }
+    derived.set(pin.repository, { repo: pin.repository, repositoryUrl: pin.repositoryUrl, sourceCommit: pin.sourceCommit });
+  }
+  return derived;
+}
+
+/** The pins behind `thirdPartySourceRepositoryPins`, by repository. */
+export const thirdPartySourcesByRepository = (derived, thirdPartyPins) =>
+  new Map([...derived.keys()].map((repo) => [repo, thirdPartyPins.byRepository(repo)]));
+
+/**
+ * The ONE trust-policy row of `rows` (the `channel` image-source rows whose imageRepositories list `imageRef`): none, or
+ * several, is refused. The pin writer, `--check-third-party` and resolve-time admission hold a third-party image to it.
+ */
+export function soleImageSignerRow({ rows, imageRef, channel, label }) {
+  if (rows.length !== 1) {
+    throw new Error(
+      `${label}: ${rows.length} ${channel} trust policy rows list ${imageRef} in their imageRepositories for image-source evidence; exactly one is required`,
+    );
+  }
+  return rows[0];
+}
+
+/**
+ * What a third-party subject must satisfy beyond a first-party one, after its evidence has verified:
+ *  * [d9-1] the signing row's workflow repository, the subject's `repo` and the path of the predicate's
+ *    `source.repositoryUrl` are one repository;
+ *  * the subject is the pinned image (reference, content hash, sealed digest when sealed);
+ *  * `imageRows` (the rows of the verification channel listing the image) hold exactly one row, the one the pin names
+ *    for that image (`policyId`), and the evidence verified under it, signing the pinned `producerWorkflow`: another
+ *    row listing the image, of the same repository or not, is refused. The bundle is held to
+ *    `bundle.signerPolicyId` by the bundle signer selection (`locked-bundle-signer.mjs`);
+ *  * (d) the leaf certificate states the pinned repository id, owner id and the runner environment the pin declares
+ *    (`assertCertificateExtensions`: github-hosted unless the pin declares self-hosted, which also holds the build URIs).
+ */
+export function assertThirdPartySubjectAdmission({ subject, source, statement, identityPolicy, imageRows, channel, bundle }) {
+  const label = `third-party subject "${subject.kind}:${subject.id}" (source "${source.name}")`;
+  const claimedRepository = repositoryPathOf(statement.predicate.source.repositoryUrl);
+  const signerRepository = identityPolicy.githubWorkflow.repository;
+  if (signerRepository !== subject.repo || claimedRepository !== subject.repo) {
+    throw new Error(
+      `${label}: the signing row's workflow repository (${signerRepository}), the subject repo (${subject.repo}) and the predicate source.repositoryUrl repository (${claimedRepository}) must be one repository`,
+    );
+  }
+  const image = source.images.find((candidate) => candidate.subjectKind === subject.kind && candidate.subjectId === subject.id);
+  if (image === undefined) {
+    throw new Error(`${label}: the pin pins no image for it`);
+  }
+  const sole = soleImageSignerRow({ rows: imageRows, imageRef: subject.imageRef, channel, label });
+  if (sole.policyId !== image.policyId) {
+    throw new Error(`${label}: the one ${channel} row listing ${subject.imageRef} is "${sole.policyId}", but the pin names row "${image.policyId}"`);
+  }
+  if (identityPolicy.policyId !== image.policyId || identityPolicy.githubWorkflow.path !== image.producerWorkflow) {
+    throw new Error(
+      `${label}: its evidence verified under row "${identityPolicy.policyId}" (workflow ${identityPolicy.githubWorkflow.path}), but the pin holds it to row "${image.policyId}" (workflow ${image.producerWorkflow})`,
+    );
+  }
+  if (subject.imageRef !== image.imageRef) {
+    throw new Error(`${label}: images.lock.json names ${subject.imageRef}, but the pin pins ${image.imageRef}`);
+  }
+  if (subject.contentHash !== image.sourceTreeHash) {
+    throw new Error(`${label}: images.lock.json has contentHash ${subject.contentHash}, but the pin records sourceTreeHash ${image.sourceTreeHash}`);
+  }
+  if (subject.imageDigest !== undefined && subject.imageDigest !== image.manifestDigest) {
+    throw new Error(`${label}: images.lock.json seals ${subject.imageDigest}, but the pin records manifestDigest ${image.manifestDigest}`);
+  }
+  assertCertificateExtensions({ bundle, source, signerIdentity: identityPolicy.certificateIdentity, label });
+}