@xemahq/xema 0.59.1 → 0.60.1

package/edition/pin-source.mjs

@@ -1,242 +0,0 @@
-// 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

@@ -1,70 +0,0 @@
-// 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. Shared by the build-record verifier (develop-record-verify.mjs)
-// and the edition seal (edition-seal.mjs), so there is one copy of this trust path.
-
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { basicAuthParts, defaultRunCosign } from './develop-coverage-readers.mjs';
-import { dataRoot } from './edition-workspace.mjs';
-import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
-import { COSIGN_ENV, prepareTrustedCosignBinary, validatePinnedTrustedRoot } from './image-evidence.mjs';
-import { loadRegistryCredentialDeclarations, resolveRegistryCredential } from './registry-credentials.mjs';
-import { assertPreparedExecutable } from './trusted-executable.mjs';
-import { registryClientsFor } from './verify-image-platforms.mjs';
-
-/**
- * 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 declarations = clientsOverride === undefined ? loadRegistryCredentialDeclarations(dataRoot()) : null;
-    const clients = new Map();
-    const clientFor = (authority) => {
-      if (clientsOverride !== undefined) {return clientsOverride(authority);}
-      if (!clients.has(authority)) {
-        clients.set(authority, registryClientsFor([{ imageRef: `${authority}/x` }], { declarations, env }).get(authority));
-      }
-      return clients.get(authority);
-    };
-    // 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) });