@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/pin-source.mjs

@@ -0,0 +1,242 @@
+// pin-source — where the resolver reads each first-party repository's commit.
+//
+// PUBLISHED (the default, and the only behaviour before this module): the
+// committed `runtime-image-source-index.json#repositoryPins`, untouched.
+//
+// SNAPSHOT: one frozen map of pins, replacing the published ones for ONE
+// in-memory resolution (the develop pipeline resolves a whole edition from it).
+// Nothing is written back to the index, and there is NO fallback: a repo in the
+// graph that the snapshot does not name is refused, never read from the
+// published pin. This module owns the SHAPE of that map: a flat object whose
+// keys live in six closed namespaces and whose values are exact 40-hex SHAs.
+//
+//   repos/<x> | submodules/<x>        every repository of the develop graph (the
+//                                     data root's firstPartySources, develop-graph.mjs),
+//                                     no more, no fewer
+//   <pinRoles.data>                   the commit of the data root checkout (editions and indices)
+//   <pinRoles.kernel>                 the commit of the kernel the authorization lock is sealed
+//                                     with (may match repos/<x>, but is NOT in the graph)
+//   <pinRoles.deploy>                 the commit of the chart tree the chart-set lock digests
+//   editions-root                     the commit of the editions root checkout; present
+//                                     only when that root is NOT this repository
+//   sources/<name>                    one per `sources[]` entry declared in the chain
+
+import { developGraphMembers } from './develop-graph.mjs';
+import { workspaceSection } from './edition-config.mjs';
+import { VENDOR_MEMBER_PIN_PATTERN } from './edition-constants.mjs';
+import { compareStrings } from './lib.mjs';
+import { PinRole } from './workspace-sections.mjs';
+
+export const PinSourceKind = Object.freeze({
+  Published: 'published',
+  Snapshot: 'snapshot',
+});
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+export const SnapshotPinNamespace = Object.freeze({
+  Graph: 'graph',
+  Distributions: 'distributions',
+  Kernel: 'kernel',
+  ChartSource: 'chart-source',
+  EditionsRoot: 'editions-root',
+  Source: 'source',
+});
+
+// The three checked-out roles a snapshot pins (data, kernel, deploy) are a closed
+// set the library defines; the repository key each is pinned under is the data
+// root's (`pinRoles` in edition-workspace.json), so a repository rename never
+// needs a library release. `editions-root` is not a repository key but a
+// protocol key of its own.
+export const EDITIONS_ROOT_PIN_KEY = 'editions-root';
+
+const pinKeyOf = (role) => workspaceSection('pinRoles', 'a snapshot pin')[role];
+
+export const dataPinKey = () => pinKeyOf(PinRole.Data);
+export const kernelPinKey = () => pinKeyOf(PinRole.Kernel);
+export const deployPinKey = () => pinKeyOf(PinRole.Deploy);
+const SOURCE_PIN_PREFIX = 'sources/';
+// A graph pin key is a vendor member pin key: the pattern is the edition contract's (customerForms.vendorMemberPinPattern).
+const GRAPH_PIN_PATTERN = VENDOR_MEMBER_PIN_PATTERN;
+
+/** The snapshot key of one declared `sources[]` entry. */
+export function sourcePinKey(name) {
+  return `${SOURCE_PIN_PREFIX}${name}`;
+}
+
+/** The `sources[].name` a Source-namespace key pins. */
+export function sourceNameOfPinKey(key) {
+  return key.slice(SOURCE_PIN_PREFIX.length);
+}
+
+/** Whether `key` is the snapshot key of a declared source (`sources/<name>`); pure, it reads no workspace section. */
+export function isSourcePinKey(key) {
+  return key.startsWith(SOURCE_PIN_PREFIX) && key.length > SOURCE_PIN_PREFIX.length;
+}
+
+/** Which closed namespace a snapshot key belongs to; refuses a key in none. */
+export function snapshotPinNamespace(key) {
+  if (key === dataPinKey()) {return SnapshotPinNamespace.Distributions;}
+  if (key === kernelPinKey()) {return SnapshotPinNamespace.Kernel;}
+  if (key === deployPinKey()) {return SnapshotPinNamespace.ChartSource;}
+  if (key === EDITIONS_ROOT_PIN_KEY) {return SnapshotPinNamespace.EditionsRoot;}
+  if (isSourcePinKey(key)) {
+    return SnapshotPinNamespace.Source;
+  }
+  if (GRAPH_PIN_PATTERN.test(key)) {return SnapshotPinNamespace.Graph;}
+  throw new Error(
+    `snapshot pin key "${key}" is in no namespace; expected a graph repository (repos/<x> or ` +
+      `submodules/<x>), "${dataPinKey()}", "${kernelPinKey()}", "${deployPinKey()}", "${EDITIONS_ROOT_PIN_KEY}" or "${SOURCE_PIN_PREFIX}<name>"`,
+  );
+}
+
+function assertPinsObject(pins) {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    throw new Error('snapshot pins must be an object mapping key -> 40-hex commit');
+  }
+}
+
+function assertExactShas(pins) {
+  for (const [key, sha] of Object.entries(pins)) {
+    if (typeof sha !== 'string' || !SHA_PATTERN.test(sha)) {
+      throw new Error(
+        `snapshot pin for "${key}" is not a 40-hex commit SHA: ${JSON.stringify(sha)}`,
+      );
+    }
+  }
+}
+
+function graphPinsOf(pins) {
+  return Object.fromEntries(
+    Object.entries(pins).filter(([key]) => snapshotPinNamespace(key) === SnapshotPinNamespace.Graph),
+  );
+}
+
+/**
+ * Validate a COMPLETE snapshot against the develop graph and the composed
+ * chain. `declaredSourceNames` are the `sources[].name` entries the chain
+ * declares; `editionsRootExternal` is whether the editions root is another
+ * repository. Every refusal names the offending key; nothing falls back to a
+ * published pin.
+ */
+export function validateSnapshotPins(
+  pins,
+  { declaredSourceNames, editionsRootExternal },
+) {
+  assertPinsObject(pins);
+  assertExactShas(pins);
+  for (const key of Object.keys(pins)) {snapshotPinNamespace(key);}
+  checkGraphPins(developGraphMembers(), pins);
+  for (const [key, what] of [
+    [dataPinKey(), 'the commit of the data root checkout'],
+    [kernelPinKey(), 'the commit of the kernel the authorization lock is sealed with'],
+    [deployPinKey(), 'the commit of the chart tree the chart-set lock digests'],
+  ]) {
+    if (!(key in pins)) {throw new Error(`snapshot is missing "${key}", ${what}`);}
+  }
+  if (editionsRootExternal && !(EDITIONS_ROOT_PIN_KEY in pins)) {
+    throw new Error(`snapshot is missing "${EDITIONS_ROOT_PIN_KEY}": the editions root is not this repository`);
+  }
+  if (!editionsRootExternal && EDITIONS_ROOT_PIN_KEY in pins) {
+    throw new Error(`snapshot names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
+  }
+  const declared = new Set(declaredSourceNames);
+  for (const name of declared) {
+    if (!(sourcePinKey(name) in pins)) {
+      throw new Error(`snapshot is missing "${sourcePinKey(name)}": the chain declares source "${name}"`);
+    }
+  }
+  for (const key of Object.keys(pins)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !declared.has(sourceNameOfPinKey(key))) {
+      throw new Error(`snapshot names "${key}", but the chain declares no source "${sourceNameOfPinKey(key)}"`);
+    }
+  }
+}
+
+/** The pins sorted by key: the one canonical order, shared by the hash and the artifact. */
+export function sortedSnapshotPins(pins) {
+  assertPinsObject(pins);
+  return Object.fromEntries(Object.entries(pins).sort(([a], [b]) => compareStrings(a, b)));
+}
+
+/** A declared source with its ref replaced by the snapshot pin; identity under a published pin source. */
+export function pinnedSource(source, pinSource = PUBLISHED_PIN_SOURCE) {
+  if (pinSource?.kind !== PinSourceKind.Snapshot) {return source;}
+  const key = sourcePinKey(source.name);
+  const ref = pinSource.pins[key];
+  if (ref === undefined) {
+    throw new Error(`snapshot has no pin "${key}" for the declared source "${source.name}"; there is no fallback to its declared ref`);
+  }
+  return { ...source, ref };
+}
+
+export const PUBLISHED_PIN_SOURCE = Object.freeze({ kind: PinSourceKind.Published });
+
+/** @param {Record<string,string>} pins repo -> 40-hex commit */
+export function snapshotPinSource(pins) {
+  return Object.freeze({ kind: PinSourceKind.Snapshot, pins });
+}
+
+/**
+ * Apply a pin source to a parsed runtime image source index. Published returns
+ * the SAME object (inert, byte for byte). Snapshot returns a copy whose
+ * `repositoryPins` are the DEVELOP GRAPH (develop-graph.mjs) at the snapshot
+ * SHAs: the committed index's own pins are not read, so a first-party
+ * repository no release pins yet is in it, and a pinned one that is not
+ * first-party is not.
+ */
+export function applyPinSource(runtimeSourceIndex, pinSource = PUBLISHED_PIN_SOURCE) {
+  switch (pinSource?.kind) {
+    case PinSourceKind.Published:
+      return runtimeSourceIndex;
+    case PinSourceKind.Snapshot:
+      return applySnapshot(runtimeSourceIndex, pinSource.pins);
+    default:
+      throw new Error(
+        `unknown pin source kind ${JSON.stringify(pinSource?.kind)}; expected ` +
+          `${Object.values(PinSourceKind).join(' | ')}`,
+      );
+  }
+}
+
+function checkGraphPins(graph, pins) {
+  const graphRepos = new Set(graph.map((pin) => pin.repo));
+  for (const repo of Object.keys(graphPinsOf(pins))) {
+    if (!graphRepos.has(repo)) {
+      throw new Error(`snapshot names "${repo}", which is not a repository in the graph`);
+    }
+  }
+  const missing = [...graphRepos].filter((repo) => !(repo in pins));
+  if (missing.length > 0) {
+    throw new Error(
+      `snapshot is missing ${missing.length} repositor${missing.length === 1 ? 'y' : 'ies'} ` +
+        `in the graph: ${missing.join(', ')}. There is no fallback to the published pin.`,
+    );
+  }
+}
+
+function applySnapshot(runtimeSourceIndex, pins) {
+  assertPinsObject(pins);
+  assertExactShas(pins);
+  for (const key of Object.keys(pins)) {snapshotPinNamespace(key);}
+  const graph = developGraphMembers();
+  checkGraphPins(graph, pins);
+  return {
+    ...runtimeSourceIndex,
+    repositoryPins: graph.map(({ repo, repositoryUrl }) => ({
+      repo,
+      repositoryUrl,
+      // A develop snapshot pins every repository at its develop head, so that one
+      // SHA is both the built commit (image axis, `sourceCommit`) and the source
+      // tip (`vendoredSourceCommit`): the image pin lagging the source tip cannot
+      // arise, and the snapshot is "one frozen snapshot of pins and nothing else".
+      // Fusing both axes is the rule `effectiveRepositoryPins` and
+      // `createExactCommitSourceAuthority` already apply for an exact commit.
+      // The COMMITTED index keeps the axes apart (release channel): see
+      // `source-authority.mjs#publishedSourceTip` and
+      // `build-runtime-image-source-index.mjs#repositoryIdentity`.
+      sourceCommit: pins[repo],
+      vendoredSourceCommit: pins[repo],
+    })),
+  };
+}

package/edition/pinned-cosign.mjs

@@ -0,0 +1,86 @@
+// pinned-cosign — the one way this CLI runs `cosign verify`: the caller's absolute cosign, held to the
+// cosign digest the data root's pinned evidence trust policy names; the policy's pinned Sigstore trusted
+// root written to a private scratch file for `--offline --trusted-root`; and cosign's registry credential
+// taken from the SAME declaration oras uses, in its environment, never argv. Every injection exists for
+// tests; the defaults are the real readers. Used by the official lane only (the edition seal, edition-seal.mjs, and
+// the catalogue-free resolve's engine proof, develop-engine-image.mjs), so there is one copy of this trust path. The
+// develop dev lane runs no cosign.
+
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
+import { COSIGN_ENV, prepareTrustedCosignBinary, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { registryClientFactory } from './registry-client-factory.mjs';
+import { resolveRegistryCredential } from './registry-credentials.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+
+const execFileAsync = promisify(execFile);
+// One external call to cosign; it reads a registry. A run that exceeds it fails naming the subject, never a verdict.
+const COSIGN_CALL_TIMEOUT_MS = 60_000;
+const COSIGN_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+/** Run cosign once; resolves `{code, stdout, stderr}` for a cosign exit, throws when cosign could not run at all. */
+function defaultRunCosign(cosignPath, args, env) {
+  return execFileAsync(cosignPath, args, { env, timeout: COSIGN_CALL_TIMEOUT_MS, maxBuffer: COSIGN_MAX_OUTPUT_BYTES }).then(
+    ({ stdout }) => ({ code: 0, stdout, stderr: '' }),
+    (error) => {
+      if (typeof error.code === 'number') {return { code: error.code, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };}
+      throw error;
+    },
+  );
+}
+
+/** The username and password of a resolved basic-auth registry credential. */
+function basicAuthParts(credential) {
+  const decoded = Buffer.from(credential.basicAuth, 'base64').toString('utf8');
+  const colon = decoded.indexOf(':');
+  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
+}
+
+/**
+ * Run `use({ policy, runCosign, cosignEnvFor, clientFor, trustedRootPath, ...prepared })` with a pinned cosign.
+ * `afterPolicy()` runs after the policy is loaded and before cosign is prepared; what it returns is spread into
+ * the argument of `use`. The scratch trusted root and the prepared cosign are disposed whatever `use` does.
+ */
+export async function withPinnedCosign({
+  cosignBinary,
+  env,
+  loadPolicy = loadDeclaredPinnedPolicy,
+  prepareCosign = prepareTrustedCosignBinary,
+  trustedRootBytes = (root, pinnedPolicy) => validatePinnedTrustedRoot(root, pinnedPolicy).bytes,
+  cosignPathOf = (handle) => assertPreparedExecutable(handle, 'cosign'),
+  runCosign: injectedRunCosign,
+  clientsOverride,
+  afterPolicy = async () => ({}),
+}, use) {
+  const { policy, dataRoot: policyRoot } = await loadPolicy();
+  const prepared = await afterPolicy();
+  const trustedCosign = prepareCosign({ cosignBinary, policy });
+  const cosignPath = cosignPathOf(trustedCosign);
+  const runCosign = injectedRunCosign ?? ((args, cosignEnv) => defaultRunCosign(cosignPath, args, cosignEnv));
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-pinned-cosign-'));
+  try {
+    const trustedRootPath = join(scratch, 'trusted-root.json');
+    writeFileSync(trustedRootPath, trustedRootBytes(policyRoot, policy), { flag: 'wx', mode: 0o600 });
+    const { clientFor, declarations } = registryClientFactory({ clientsOverride, env });
+    // cosign gets the SAME declared credential oras uses, in its environment, never argv.
+    const cosignEnvFor = (authority) => {
+      if (clientsOverride !== undefined) {return {};}
+      const credential = resolveRegistryCredential({ authority, declarations, env });
+      if (credential.access === 'anonymous') {return {};}
+      const { username, password } = basicAuthParts(credential);
+      return { COSIGN_REGISTRY_USERNAME: username, COSIGN_REGISTRY_PASSWORD: password };
+    };
+    return await use({ ...prepared, policy, runCosign, cosignEnvFor, clientFor, trustedRootPath });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+    trustedCosign.dispose();
+  }
+}
+
+/** The environment cosign runs with for one authority: the pinned base plus its declared credential. */
+export const cosignEnvironment = (cosignEnvFor, authority) => ({ ...COSIGN_ENV, ...cosignEnvFor(authority) });