@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/develop-engine-image.mjs

@@ -0,0 +1,97 @@
+// develop-engine-image — the engine image the catalogue-free customer resolve's vendor step records, found and proven
+// (develop-catalogue-free-vendor.mjs, the official lane). The channel lane's vendor resolve is handed its engine by
+// digest (`--engine-image`) and proves nothing.
+//
+// The edition's engine is the one the deploy repository's CI published for EXACTLY the deploy commit the snapshot pins
+// (tag `sha-<12 hex>`, keyless signature by a `workflow_run` follower of a green push CI). The tag only finds the digest.
+// The signature is checked offline against the pinned trust root through the CLI's one cosign path (pinned-cosign.mjs)
+// with the publisher's EXACT identity, issuer, workflow repository and ref (cosign-certificate-constraints.mjs); never a
+// pattern. A follower runs the default branch's copy of the workflow, so the certificate's own workflow commit is not the
+// built one: the built commit is bound by the signed annotations commit=<40 hex> and branch=develop.
+// The digest is what the edition records.
+
+import { RefusalError } from './collected-refusals.mjs';
+import { certificateIdentityArgs } from './cosign-certificate-constraints.mjs';
+import { assertEngineImage } from './edition-artifact.mjs';
+import { assertPublisher, publisherIdentity } from './edition-publisher.mjs';
+import { deployPinKey } from './pin-source.mjs';
+import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { isNotPublishedYet } from './seal-image-digests.mjs';
+import { GITHUB_ACTIONS_OIDC_ISSUER } from './third-party-source-evidence.mjs';
+
+const COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+const TAG_PREFIX = 'sha-';
+const TAG_COMMIT_LENGTH = 12;
+const DEVELOP_BRANCH = 'develop';
+const STDERR_TAIL_BYTES = 800;
+
+/** The tag xema-deploy CI gives the engine it publishes for `deploySha`. */
+export const engineTagOf = (deploySha) => `${TAG_PREFIX}${deploySha.slice(0, TAG_COMMIT_LENGTH)}`;
+
+const IDENTITY_PATTERN = /^https:\/\/github\.com\/([^/@]+\/[^/@]+)\/(\.github\/workflows\/[^/@]+)@(.+)$/;
+
+/**
+ * The signer an exact certificate identity `https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>` names, held to
+ * the publisher grammar of edition-contract.json (so no pattern, no wildcard).
+ */
+export function engineSignerOf(identity) {
+  const match = typeof identity === 'string' ? IDENTITY_PATTERN.exec(identity) : null;
+  if (match === null) {
+    throw new RefusalError(`--engine-signer must be the exact certificate identity https://github.com/<owner>/<name>/.github/workflows/<file>@<ref>; got ${JSON.stringify(identity)}`);
+  }
+  const publisher = assertPublisher({ repository: match[1], workflow: match[2], ref: match[3] }, '--engine-signer');
+  return { certificateIdentity: publisherIdentity(publisher), oidcIssuer: GITHUB_ACTIONS_OIDC_ISSUER, githubWorkflow: { repository: publisher.repository, ref: publisher.ref } };
+}
+
+const tail = (text) => String(text).trim().slice(-STDERR_TAIL_BYTES);
+
+/**
+ * @param {object} request
+ * @param {Record<string, string>} request.pins the snapshot's pins; the xema-deploy commit is read from them
+ * @param {{repository: string, signer: string}} request.engine the engine repository and the signer's exact certificate identity
+ * @param {string} request.cosignBinary absolute path of cosign
+ * @param {object} request.env the environment the registry credentials are named in
+ * @param {object} [request.pinned] withPinnedCosign's injections (tests)
+ * @returns {Promise<string>} `<repository>@sha256:<digest>`
+ */
+export async function resolveDevelopEngineImage({ pins, engine, cosignBinary, env, pinned = {} }) {
+  const deploySha = pins[deployPinKey()];
+  if (typeof deploySha !== 'string' || !COMMIT_PATTERN.test(deploySha)) {
+    throw new RefusalError(`the pin ${deployPinKey()} is ${JSON.stringify(deploySha)}, not a 40-hex commit`);
+  }
+  const { repository } = engine;
+  const signer = engineSignerOf(engine.signer);
+  const tag = engineTagOf(deploySha);
+  const { authority, repository: path } = splitImageRef(repository);
+  return withPinnedCosign({ cosignBinary, env, ...pinned }, async ({ runCosign, cosignEnvFor, clientFor, trustedRootPath }) => {
+    let digest;
+    try {
+      digest = (await clientFor(authority).getManifestByTag(path, tag)).digest;
+    } catch (error) {
+      if (!isNotPublishedYet(error)) {throw error;}
+      throw new RefusalError(
+        `no engine ${repository}:${tag} for the ${deployPinKey()} commit ${deploySha}. The deploy repository's CI publishes one for a green push to develop or main, ` +
+          'or a CI dispatch at that branch; a commit pushed with GITHUB_TOKEN has none until CI is dispatched. ' +
+          `Dispatch that CI at develop, or pin ${deployPinKey()} to a commit that has an engine.`,
+      );
+    }
+    const image = `${repository}@${digest}`;
+    const result = await runCosign(
+      [
+        'verify', '--offline', '--trusted-root', trustedRootPath,
+        ...certificateIdentityArgs(signer),
+        '-a', `commit=${deploySha}`, '-a', `branch=${DEVELOP_BRANCH}`,
+        image,
+      ],
+      cosignEnvironment(cosignEnvFor, authority),
+    );
+    if (result.code !== 0) {
+      throw new RefusalError(
+        `${image} (${tag}) is not signed by the engine signer ${signer.certificateIdentity} with commit=${deploySha} branch=${DEVELOP_BRANCH}; ` +
+          `refusing it as this edition's engine (cosign exit ${result.code}): ${tail(result.stderr)}`,
+      );
+    }
+    return assertEngineImage(image);
+  });
+}

package/edition/develop-freeze.mjs

@@ -0,0 +1,304 @@
+// develop-freeze — freeze the develop branches into one snapshot of pins.
+//
+// Resolves `refs/heads/develop` ONCE per distinct repository URL, applies the
+// caller's per-key overrides (an override wins and is never looked up), and
+// returns the pins. After this, NOTHING reads a branch: every later step takes
+// the pins. Two phases, because the declared sources are only known once the
+// edition's chain can be read from the checked-out editions root:
+//
+//   freezeGraph    the graph repositories, the data root, the kernel, the deploy checkout, the editions root
+//   freezeSources  one pin per `sources[]` entry the chain declares
+//
+// With `memberPins` (a select-records selection) the members are pinned at the selected build records instead; the one
+// declared exception, a member that keeps its current resolution, is pinned at its develop head.
+//
+// `resolveHead({ name, url })` is the one network seam (default: `git ls-remote` through
+// git-source-auth: the data root's token only for a repository under its
+// `sourceRepositoryUrlPrefix`, no credential for any other, never argv).
+
+import { execFileSync } from 'node:child_process';
+
+import { canonicalPublicHttpsRepositoryUrl } from './canonical-repository-url.mjs';
+import { currentResolutionOf } from './develop-current-resolution.mjs';
+import { developGraphMembers } from './develop-graph.mjs';
+import { EditionChannel } from './edition-channel.mjs';
+import { assertCanonicalSourceUrl, assertSourceDeclaresNoCredential, isUnderSourcePrefix, withSourceGitEnv } from './git-source-auth.mjs';
+import { assertKernelShaAllowed, isKernelFromMember, KernelPinSourceError } from './kernel-pin-source.mjs';
+import {
+  dataPinKey,
+  EDITIONS_ROOT_PIN_KEY,
+  kernelPinKey,
+  SnapshotPinNamespace,
+  deployPinKey,
+  snapshotPinNamespace,
+  sortedSnapshotPins,
+  sourceNameOfPinKey,
+  sourcePinKey,
+} from './pin-source.mjs';
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+
+/** The ref namespaces a freeze may resolve a ref in. */
+export const RefKind = Object.freeze({ Branch: 'branch', Tag: 'tag' });
+
+const REF_PREFIX = Object.freeze({ [RefKind.Branch]: 'refs/heads/', [RefKind.Tag]: 'refs/tags/' });
+const PEELED_SUFFIX = '^{}';
+
+/**
+ * What each channel freezes a source at. A develop edition freezes the head of the `develop` BRANCH of every
+ * repository; a release edition freezes each source at the ref its definition declares, a branch or a tag.
+ */
+const FREEZE_REF_KINDS = Object.freeze({
+  [EditionChannel.Develop]: Object.freeze([RefKind.Branch]),
+  [EditionChannel.Release]: Object.freeze([RefKind.Branch, RefKind.Tag]),
+});
+
+/**
+ * The commit `ref` names in one source `{ name, url }`, by `git ls-remote <url> <refs/heads/ref | refs/tags/ref |
+ * refs/tags/ref^{}>` (only the namespaces the channel freezes at). A tag resolves to its peeled commit when it is annotated.
+ * Throws naming the repository when the ref is absent, or when it is both a branch and a tag. The source is held and its
+ * git environment built by `withSourceGitEnv`: the workspace credential reaches only a repository under `sourceRepositoryUrlPrefix`.
+ */
+export function lsRemoteRef(source, ref, { channel, workspace, env = process.env, runGit = execFileSync }) {
+  const kinds = FREEZE_REF_KINDS[channel];
+  if (kinds === undefined) {throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);}
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new Error(`source "${source.name}" declares no ref; a ${channel} edition cannot be frozen without one`);
+  }
+  const names = kinds.flatMap((kind) => (kind === RefKind.Tag ? [`${REF_PREFIX[kind]}${ref}`, `${REF_PREFIX[kind]}${ref}${PEELED_SUFFIX}`] : [`${REF_PREFIX[kind]}${ref}`]));
+  const output = withSourceGitEnv(source, { workspace, env }, (gitEnv) =>
+    runGit('git', ['ls-remote', source.url, ...names], {
+      env: gitEnv,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }),
+  ).trim();
+  const served = new Map();
+  for (const line of output.split('\n')) {
+    const [sha, name] = line.trim().split(/\s+/);
+    if (names.includes(name)) {
+      if (!SHA_PATTERN.test(sha ?? '')) {throw new Error(`${source.url}: git ls-remote answered ${JSON.stringify(line)} for ${name}`);}
+      served.set(name, sha);
+    }
+  }
+  const branch = served.get(`${REF_PREFIX[RefKind.Branch]}${ref}`);
+  const tagName = `${REF_PREFIX[RefKind.Tag]}${ref}`;
+  const tag = served.get(`${tagName}${PEELED_SUFFIX}`) ?? served.get(tagName);
+  if (branch !== undefined && tag !== undefined) {
+    throw new Error(`${source.url}: ${JSON.stringify(ref)} is both a branch and a tag; a ${channel} edition cannot be frozen at an ambiguous ref`);
+  }
+  const commit = branch ?? tag;
+  if (commit === undefined) {
+    throw new Error(`${source.url} has no ${kinds.map((kind) => `${REF_PREFIX[kind]}${ref}`).join(' or ')}; a ${channel} edition cannot be frozen without it`);
+  }
+  return commit;
+}
+
+/** A resolver that asks `resolveHead` at most once per distinct URL and ref; it takes the source `{ name, url, ref? }`. */
+function memoizedHeads(resolveHead) {
+  const heads = new Map();
+  return (source) => {
+    const key = JSON.stringify([source.url, source.ref]);
+    if (!heads.has(key)) {heads.set(key, resolveHead(source));}
+    return heads.get(key);
+  };
+}
+
+/**
+ * The pins input selects WHICH inputs a snapshot resolves, never which tooling
+ * code runs: the distributions plane that executes is the dispatching ref's own
+ * checkout, so an override for its pin key is refused outright (even one equal
+ * to that checkout), naming the key.
+ */
+export function assertNoToolingOverride(overrides) {
+  if (overrides[dataPinKey()] !== undefined) {
+    throw new Error(
+      `pins override "${dataPinKey()}" is refused: it would select the tooling code this run executes. ` +
+        'The distributions plane is always the dispatching ref\'s own checkout; pins choose inputs, never tooling.',
+    );
+  }
+}
+
+function assertOverrides(overrides, allowed) {
+  for (const [key, sha] of Object.entries(overrides)) {
+    const namespace = snapshotPinNamespace(key);
+    if (!allowed.has(namespace)) {continue;} // another phase's pin
+    if (typeof sha !== 'string' || !SHA_PATTERN.test(sha)) {
+      throw new Error(`override for "${key}" is not a 40-hex commit SHA: ${JSON.stringify(sha)}`);
+    }
+  }
+}
+
+/** The member pins name exactly the graph minus the current-resolution members; a missing or extra member is refused by name. */
+function assertMemberPinsAreTheGraph(memberPins, members) {
+  const current = new Set(Object.keys(currentResolutionOf(members)));
+  const expected = members.map(({ repo }) => repo).filter((repo) => !current.has(repo));
+  const missing = expected.filter((repo) => !Object.hasOwn(memberPins, repo));
+  const extra = Object.keys(memberPins).filter((repo) => !expected.includes(repo));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new Error(`--member-pins must pin exactly the develop graph minus ${JSON.stringify([...current])}: missing ${JSON.stringify(missing)}, extra ${JSON.stringify(extra)}`);
+  }
+}
+
+const GRAPH_PHASE = new Set([
+  SnapshotPinNamespace.Graph,
+  SnapshotPinNamespace.Distributions,
+  SnapshotPinNamespace.Kernel,
+  SnapshotPinNamespace.ChartSource,
+  SnapshotPinNamespace.EditionsRoot,
+]);
+const SOURCE_PHASE = new Set([SnapshotPinNamespace.Source]);
+
+/** A repository the workflow checked out is pinned at what it checked out; an override may only agree. */
+function assertCheckedOutPin({ key, sha, flag, what, overrides }) {
+  if (!SHA_PATTERN.test(sha ?? '')) {
+    throw new Error(`${flag} is not a 40-hex commit SHA: ${JSON.stringify(sha)}`);
+  }
+  if (overrides[key] !== undefined && overrides[key] !== sha) {
+    throw new Error(`override for "${key}" is ${overrides[key]}, but ${what} is checked out at ${sha}`);
+  }
+}
+
+/**
+ * @param {object} request
+ * @param {string} request.dataSha the commit the data root checkout is at
+ * @param {string} request.channel the edition channel; it decides where the kernel pin comes from (kernel-pin-source.mjs)
+ * @param {string} [request.kernelSha] release only: the commit the kernel checkout is at (refused on develop with KernelPinSourceError)
+ * @param {string} [request.kernelMember] develop only: the repo handle of the member whose checkout holds the kernel; the kernel pin is that member's pin
+ * @param {string} request.deploySha the commit the deploy checkout is at
+ * @param {string} [request.editionsRootUrl] https URL of the editions root; absent = this repository
+ * @param {Record<string, string>} [request.memberPins] the graph members' pins from a selection (`--member-pins`): exactly the
+ *   graph minus the members that keep their current resolution (develop-current-resolution.mjs), which are pinned at their
+ *   develop head; refused together with overrides
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source; runs for ALL graph sources before the first head
+ */
+export function freezeGraph({
+  channel,
+  dataSha,
+  kernelSha,
+  kernelMember,
+  deploySha,
+  editionsRootUrl,
+  overrides = {},
+  memberPins,
+  resolveHead,
+  holdSource,
+}) {
+  if (memberPins !== undefined && Object.keys(overrides).length > 0) {
+    throw new Error('--member-pins and --overrides are exclusive: the member pins are the selected build records, never overridden');
+  }
+  assertNoToolingOverride(overrides);
+  assertOverrides(overrides, GRAPH_PHASE);
+  const head = memoizedHeads(resolveHead);
+  // The develop graph is the data root's first-party repositories (develop-graph.mjs), never the release pins.
+  const members = developGraphMembers();
+  const graph = new Set(members.map((member) => member.repo));
+  for (const [key] of Object.entries(overrides)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Graph && !graph.has(key)) {
+      throw new Error(`override names "${key}", which is not a repository in the graph`);
+    }
+  }
+  if (memberPins !== undefined) {assertMemberPinsAreTheGraph(memberPins, members);}
+  const fromMember = isKernelFromMember(channel);
+  assertKernelShaAllowed(channel, kernelSha);
+  if (fromMember && !graph.has(kernelMember)) {
+    throw new KernelPinSourceError(`the kernel member ${JSON.stringify(kernelMember)} is not a repository in the graph`);
+  }
+  const checkedOut = [
+    { key: dataPinKey(), sha: dataSha, flag: '--data-sha', what: 'the data root checkout' },
+    ...(fromMember ? [] : [{ key: kernelPinKey(), sha: kernelSha, flag: '--kernel-sha', what: 'the kernel checkout' }]),
+    { key: deployPinKey(), sha: deploySha, flag: '--deploy-sha', what: 'the deploy checkout' },
+  ];
+  for (const { key, sha, flag, what } of checkedOut) {assertCheckedOutPin({ key, sha, flag, what, overrides });}
+  const toResolve = members.map((member) => ({ name: member.repo, url: member.repositoryUrl }));
+  if (editionsRootUrl !== undefined) {
+    toResolve.push({ name: EDITIONS_ROOT_PIN_KEY, url: canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url') });
+  }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of toResolve) {holdSource(source);}
+  if (editionsRootUrl === undefined && overrides[EDITIONS_ROOT_PIN_KEY] !== undefined) {
+    throw new Error(`override names "${EDITIONS_ROOT_PIN_KEY}", but the editions root is this repository`);
+  }
+  const pins = Object.fromEntries(checkedOut.map(({ key, sha }) => [key, sha]));
+  for (const member of members) {
+    pins[member.repo] = overrides[member.repo] ?? memberPins?.[member.repo] ?? head({ name: member.repo, url: member.repositoryUrl });
+  }
+  if (fromMember) {
+    // The kernel is built from the member's checkout, so its pin is the member's: equal by construction.
+    assertCheckedOutPin({ key: kernelPinKey(), sha: pins[kernelMember], flag: kernelMember, what: `the kernel member ${kernelMember} checkout`, overrides });
+    pins[kernelPinKey()] = pins[kernelMember];
+  }
+  if (editionsRootUrl !== undefined) {
+    const url = canonicalPublicHttpsRepositoryUrl(editionsRootUrl, '--editions-root-url');
+    pins[EDITIONS_ROOT_PIN_KEY] = overrides[EDITIONS_ROOT_PIN_KEY] ?? head({ name: EDITIONS_ROOT_PIN_KEY, url });
+  }
+  return sortedSnapshotPins(pins);
+}
+
+/**
+ * @param {object} request
+ * @param {Record<string,string>} request.pins the graph phase's pins
+ * @param {object[]} request.declaredSources every `sources[]` entry in the chain (`{ name, url, ... }`)
+ * @param {(source: {name: string, url: string}) => void} request.holdSource the hold of one source (`holdSource` of git-source-auth with the workspace and env); runs for ALL sources before the first head
+ */
+export function freezeSources({ pins, declaredSources, overrides = {}, resolveHead, holdSource }) {
+  assertOverrides(overrides, SOURCE_PHASE);
+  const head = memoizedHeads(resolveHead);
+  const sourceByName = new Map();
+  for (const source of declaredSources) {
+    const known = sourceByName.get(source.name);
+    if (known !== undefined && known.url !== source.url) {
+      throw new Error(`source "${source.name}" is declared at two URLs (${known.url}, ${source.url})`);
+    }
+    sourceByName.set(source.name, source);
+  }
+  for (const key of Object.keys(overrides)) {
+    if (snapshotPinNamespace(key) === SnapshotPinNamespace.Source && !sourceByName.has(sourceNameOfPinKey(key))) {
+      throw new Error(`override names "${key}", but the chain declares no such source`);
+    }
+  }
+  // Every source is held before the first head is asked: a refusal of the last leaves no git call behind.
+  for (const source of sourceByName.values()) {holdSource(source);}
+  const frozen = { ...pins };
+  for (const [name, source] of sourceByName) {
+    frozen[sourcePinKey(name)] = overrides[sourcePinKey(name)] ?? head(source);
+  }
+  return sortedSnapshotPins(frozen);
+}
+
+/**
+ * The declared source URLs a customer freeze may ask, held BEFORE any network call: the token of the
+ * run (EVIDENCE_REPOSITORIES_TOKEN) is sent to the origin of each URL, so a URL is refused unless it is
+ * a canonical public HTTPS repository URL written in its canonical form and lies under the workspace's
+ * `sourceRepositoryUrlPrefix`. A definition that merely names another origin never receives the token.
+ */
+export function assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix) {
+  if (typeof sourceRepositoryUrlPrefix !== 'string' || sourceRepositoryUrlPrefix.length === 0) {
+    throw new Error('a customer freeze takes the workspace\'s sourceRepositoryUrlPrefix');
+  }
+  for (const source of sources) {
+    assertSourceDeclaresNoCredential(source);
+    const canonical = assertCanonicalSourceUrl(source);
+    const context = `source "${source.name}" url`;
+    if (!isUnderSourcePrefix(canonical, sourceRepositoryUrlPrefix)) {
+      throw new Error(
+        `${context} ${JSON.stringify(source.url)} is not under the workspace's sourceRepositoryUrlPrefix ${sourceRepositoryUrlPrefix}: ` +
+          'the source token is sent only to repositories under that prefix',
+      );
+    }
+  }
+}
+
+/**
+ * The pins of a CUSTOMER edition: exactly one `sources/<name>` commit per source its definition declares,
+ * each the head of refs/heads/develop of that source's repository, resolved once. Every URL is held by
+ * `assertCustomerSourceUrls` before the first head is asked.
+ */
+export function freezeCustomerSources({ definition, resolveHead, holdSource, sourceRepositoryUrlPrefix }) {
+  const sources = definition?.sources ?? [];
+  if (!Array.isArray(sources) || sources.some((source) => typeof source?.name !== 'string' || typeof source?.url !== 'string')) {
+    throw new Error('the definition\'s sources must be an array of {name, url}');
+  }
+  assertCustomerSourceUrls(sources, sourceRepositoryUrlPrefix);
+  return freezeSources({ pins: {}, declaredSources: sources, resolveHead, holdSource });
+}