@xemahq/xema 0.28.0 → 0.29.0

package/edition/edition-contract-parse.mjs

@@ -0,0 +1,52 @@
+// edition-contract-parse — the strict parse of edition-contract.json. A consumer
+// that vendors the contract holds it to this same shape: a contract that is not
+// v2, or lacks `repositories`, or names a channel this CLI does not know, is
+// refused rather than read with a default.
+
+import { EditionChannel } from './edition-channel.mjs';
+
+export const EDITION_CONTRACT_SCHEMA = 'xema.edition-contract/v2';
+
+const SEGMENT = /^[a-z0-9][a-z0-9.-]*$/;
+
+/** The strict parse of the contract; returns it unchanged. */
+export function parseEditionContract(contract) {
+  if (contract === null || typeof contract !== 'object' || Array.isArray(contract)) {
+    throw new Error('edition-contract.json must be a JSON object');
+  }
+  if (contract.schema !== EDITION_CONTRACT_SCHEMA) {
+    throw new Error(`edition-contract.json: schema is ${JSON.stringify(contract.schema)}, expected ${JSON.stringify(EDITION_CONTRACT_SCHEMA)}`);
+  }
+  if (typeof contract.vendoring !== 'string' || contract.vendoring === '') {
+    throw new Error('edition-contract.json: "vendoring" must be the non-empty statement of how a consumer vendors this file');
+  }
+  if (typeof contract.repositoryPrefix !== 'string' || contract.repositoryPrefix === '') {
+    throw new Error('edition-contract.json: "repositoryPrefix" must be a non-empty string');
+  }
+  const repositories = contract.repositories;
+  if (repositories === null || typeof repositories !== 'object' || Array.isArray(repositories)) {
+    throw new Error('edition-contract.json has no "repositories": the namespace segment of each channel is read from it and nowhere else');
+  }
+  const channels = Object.values(EditionChannel);
+  const keys = Object.keys(repositories);
+  const unknown = keys.filter((key) => !channels.includes(key));
+  if (unknown.length > 0 || keys.length !== channels.length) {
+    throw new Error(
+      `edition-contract.json: "repositories" is exactly one entry per channel (${channels.join(' | ')}); ` +
+        (unknown.length > 0 ? `unknown channel ${unknown.map((key) => JSON.stringify(key)).join(', ')}` : `got ${keys.join(', ') || 'none'}`),
+    );
+  }
+  const segments = new Set();
+  for (const channel of channels) {
+    const entry = repositories[channel];
+    const entryKeys = entry !== null && typeof entry === 'object' && !Array.isArray(entry) ? Object.keys(entry) : [];
+    if (entryKeys.join() !== 'namespaceSegment' || typeof entry.namespaceSegment !== 'string' || !SEGMENT.test(entry.namespaceSegment)) {
+      throw new Error(`edition-contract.json: repositories.${channel} is exactly {namespaceSegment}, one lowercase path segment`);
+    }
+    segments.add(entry.namespaceSegment);
+  }
+  if (segments.size !== channels.length) {
+    throw new Error('edition-contract.json: the channels\' namespace segments must differ');
+  }
+  return contract;
+}

package/edition/edition-contract.json

@@ -1,7 +1,16 @@
 {
-  "schema": "xema.edition-contract/v1",
+  "schema": "xema.edition-contract/v2",
+  "vendoring": "This file is the single source of the edition artifact coordinates and names. A consumer vendors it BYTE-IDENTICAL from a stated xema-cli commit and never edits it. It reads both repository namespace segments (repositories.<channel>.namespaceSegment) and the repository prefix (repositoryPrefix) only from this file, and refuses a contract that has no `repositories`.",
   "artifactType": "application/vnd.xema.edition.v1+json",
   "repositoryPrefix": "xema-edition-",
+  "repositories": {
+    "release": {
+      "namespaceSegment": "editions"
+    },
+    "develop": {
+      "namespaceSegment": "develop-editions"
+    }
+  },
   "descriptorFile": "xema-edition.json",
   "descriptorSchema": "xema.edition/v1",
   "locks": [

package/edition/edition-workspace.mjs

@@ -14,7 +14,6 @@ export const WorkspaceRoot = Object.freeze({
   Kernel: 'kernelPackageDir',
   Deploy: 'deployRoot',
   Cache: 'cacheDir',
-  SourceHash: 'sourceHashPackageDir',
 });
 
 export const WORKSPACE_FLAGS = Object.freeze({
@@ -24,7 +23,6 @@ export const WORKSPACE_FLAGS = Object.freeze({
   [WorkspaceRoot.Kernel]: '--kernel',
   [WorkspaceRoot.Deploy]: '--deploy-root',
   [WorkspaceRoot.Cache]: '--cache-dir',
-  [WorkspaceRoot.SourceHash]: '--source-hash',
 });
 
 const ROOT_MEANING = Object.freeze({
@@ -37,8 +35,6 @@ const ROOT_MEANING = Object.freeze({
   [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'];
@@ -90,7 +86,6 @@ 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);
@@ -113,9 +108,11 @@ export const runtimeImageSourceIndexPath = () =>
 /**
  * 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.
+ * the entry requires: a missing one is refused here, before any work. With
+ * `refuseOthers` a root flag whose root `needs` does not name is refused too
+ * (a customer verb takes only the roots it needs).
  */
-export function configureEditionWorkspaceFromArgv(argv, needs) {
+export function configureEditionWorkspaceFromArgv(argv, needs, { refuseOthers = false } = {}) {
   const byFlag = new Map(
     Object.entries(WORKSPACE_FLAGS).map(([name, flag]) => [flag, name]),
   );
@@ -130,6 +127,11 @@ export function configureEditionWorkspaceFromArgv(argv, needs) {
       rest.push(arg);
       continue;
     }
+    if (refuseOthers && !needs.includes(name)) {
+      throw new Error(
+        `${flag} is not a root this command takes (it takes: ${needs.length === 0 ? 'no root' : needs.map((root) => WORKSPACE_FLAGS[root]).join(' ')})`,
+      );
+    }
     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`);
@@ -169,11 +171,12 @@ export function isEntryModule(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.
+ * `options` are those of `configureEditionWorkspaceFromArgv`.
  */
-export function configureEditionWorkspaceFromProcess(needs) {
+export function configureEditionWorkspaceFromProcess(needs, options) {
   let rest;
   try {
-    rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs);
+    rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs, options);
   } catch (error) {
     // An entry calls this before it has a `main` to catch anything: a missing
     // or malformed root is the operator's mistake, answered with the roots the

package/edition/evidence-trust-policy.mjs

@@ -133,6 +133,32 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
   return { policy, policyDigest };
 }
 
+/**
+ * The arming of the data root's declared policy on `channel`, loaded and pinned
+ * exactly as `descriptorEvidenceTrust` and the check load it: `{ declared, state,
+ * unmet }`. A data root that declares no policy is `unarmed` with `declared:
+ * false` and one unmet entry; a declared policy that does not hold to its pin
+ * (digest, verifier) throws. Nothing is written.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ */
+export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier }) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  const schemas = await loadKernelDistributionSchemas();
+  assertArmingChannel(schemas, channel);
+  if (declaration.policy === null) {
+    return {
+      declared: false,
+      state: TrustPolicyArmingState.UNARMED,
+      unmet: [`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy`],
+    };
+  }
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  return { declared: true, state, unmet };
+}
+
 /** What a develop edition says, once, when it is written or checked without an armed develop channel. */
 export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed, evidence is not signature-verified';
 

package/edition/external-source-walk.mjs

@@ -82,8 +82,9 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { readBiomeAuthorizationModuleAt } from './authorization-base.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
 import { cacheDir } from './edition-workspace.mjs';
-import { gitAuthEnv } from './git-source-auth.mjs';
+import { holdSource, withSourceGitEnv } from './git-source-auth.mjs';
 import {
   BIOME_GENERATED_INDEX_FILENAME,
   loadKernelBiomeContracts,
@@ -114,48 +115,24 @@ const EXACT_COMMIT = /^[a-f0-9]{40}$/;
  */
 const EXTERNAL_SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist']);
 
-function git(directory, args, env = process.env) {
-  return execFileSync('git', ['-C', directory, ...args], {
+function git(directory, args, env = process.env, exec = execFileSync) {
+  return exec('git', ['-C', directory, ...args], {
     encoding: 'utf8',
     env,
     stdio: ['ignore', 'pipe', 'pipe'],
   }).trim();
 }
 
-/**
- * Environment for a git call against one declared source.
- *
- * `authTokenEnv` NAMES an environment variable; the token is never inlined in
- * the manifest (`CredentialFreeGitUrlSchema` refuses a URL carrying userinfo).
- * A declared-but-unset variable is REFUSED rather than falling back to the
- * ambient credential helper: a source that states it needs a credential and
- * silently resolves without one has resolved as somebody else, and the commit
- * it pins would be whatever that other identity can see.
- */
-export function gitEnvForSource(source, env = process.env) {
-  const base = { ...env, GIT_TERMINAL_PROMPT: '0' };
-  if (source.authTokenEnv === undefined) {return base;}
-  const token = env[source.authTokenEnv];
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new Error(
-      `source "${source.name}" declares authTokenEnv "${source.authTokenEnv}", but that ` +
-        'environment variable is unset or empty. Refusing to fall back to the ambient git ' +
-        'credential helper: a declared credential that silently resolves as another identity ' +
-        'would pin whatever commit that identity can see.',
-    );
-  }
-  return gitAuthEnv(source.url, source.authUsername, token, base);
-}
-
 /**
  * Resolve a declared ref to an exact commit AT THE REMOTE.
  *
  * A moving branch may DISCOVER an upgrade candidate; it must never be the
  * IDENTITY of a released member. This is the only place a ref becomes a commit,
  * and everything downstream — the checkout, the manifest reads, the lock —
- * carries the commit.
+ * carries the commit. `gitEnv` is the environment `withSourceGitEnv` computed for
+ * this source; `exec` is the spawn seam.
  */
-export function resolveRemoteCommit(source, env = process.env) {
+function resolveRemoteCommit(source, gitEnv, exec = execFileSync) {
   const ref = source.ref ?? 'HEAD';
   // AN EXACT COMMIT IS ALREADY THE ANSWER, and it must not be sent to
   // `ls-remote`, which matches REFS and would find nothing for a raw sha —
@@ -171,9 +148,9 @@ export function resolveRemoteCommit(source, env = process.env) {
   if (EXACT_COMMIT.test(ref)) {return ref;}
   let out;
   try {
-    out = execFileSync('git', ['ls-remote', '--exit-code', source.url, ref], {
+    out = exec('git', ['ls-remote', '--exit-code', source.url, ref], {
       encoding: 'utf8',
-      env: gitEnvForSource(source, env),
+      env: gitEnv,
       stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
   } catch (error) {
@@ -213,35 +190,38 @@ export function materializeGitSource({
   source,
   cacheRoot = externalSourceCacheDir(),
   env = process.env,
+  workspace = editionWorkspaceConfig(),
+  exec = execFileSync,
 }) {
-  const gitEnv = gitEnvForSource(source, env);
-  const commit = resolveRemoteCommit(source, env);
-  const directory = join(cacheRoot, source.name);
-  if (!existsSync(join(directory, '.git'))) {
-    mkdirSync(directory, { recursive: true });
-    execFileSync('git', ['init', '--quiet', directory], { env: gitEnv });
-    git(directory, ['remote', 'add', 'origin', source.url], gitEnv);
-  } else {
-    // The cache is keyed by the DECLARED name, so a renamed or moved source
-    // reuses it: fetch from where the declaration says the source lives NOW.
-    git(directory, ['remote', 'set-url', 'origin', source.url], gitEnv);
-  }
-  const have = (() => {
-    try {
-      return git(directory, ['cat-file', '-e', `${commit}^{commit}`], gitEnv) === '';
-    } catch {
-      return false;
+  return withSourceGitEnv(source, { workspace, env }, (gitEnv) => {
+    const commit = resolveRemoteCommit(source, gitEnv, exec);
+    const directory = join(cacheRoot, source.name);
+    if (!existsSync(join(directory, '.git'))) {
+      mkdirSync(directory, { recursive: true });
+      exec('git', ['init', '--quiet', directory], { env: gitEnv });
+      git(directory, ['remote', 'add', 'origin', source.url], gitEnv, exec);
+    } else {
+      // The cache is keyed by the DECLARED name, so a renamed or moved source
+      // reuses it: fetch from where the declaration says the source lives NOW.
+      git(directory, ['remote', 'set-url', 'origin', source.url], gitEnv, exec);
     }
-  })();
-  if (!have) {
-    execFileSync(
-      'git',
-      ['-C', directory, 'fetch', '--quiet', '--depth=1', 'origin', commit],
-      { env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] },
-    );
-  }
-  git(directory, ['checkout', '--quiet', '--detach', commit], gitEnv);
-  return { directory, commit: pinExternalSourceCommit({ name: source.name, directory, commit }) };
+    const have = (() => {
+      try {
+        return git(directory, ['cat-file', '-e', `${commit}^{commit}`], gitEnv, exec) === '';
+      } catch {
+        return false;
+      }
+    })();
+    if (!have) {
+      exec(
+        'git',
+        ['-C', directory, 'fetch', '--quiet', '--depth=1', 'origin', commit],
+        { env: gitEnv, stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+    }
+    git(directory, ['checkout', '--quiet', '--detach', commit], gitEnv, exec);
+    return { directory, commit: pinExternalSourceCommit({ name: source.name, directory, commit }) };
+  });
 }
 
 /**
@@ -407,7 +387,8 @@ function lockedSourceRecord(source, commit) {
  * Walk every declared source for one edition.
  *
  * Returns the stamped index entries and the `LockedBiomeSource` record per
- * source name. `materialize` is injectable so the contract suite can drive a
+ * source name. `workspace` (default: the configured data root) supplies the one source credential.
+ * `materialize` is injectable so the contract suite can drive a
  * real local git repository instead of reaching the network — the walk under
  * test is then the real one, not a fixture of it.
  */
@@ -415,9 +396,12 @@ export async function walkDeclaredSources({
   sources = [],
   materialize = materializeGitSource,
   env = process.env,
+  workspace = undefined,
 } = {}) {
   const entries = [];
   const sourceRecords = new Map();
+  // Every source is held (kind, then credential and URL) before the first is materialised.
+  const heldWorkspace = sources.length === 0 ? undefined : (workspace ?? editionWorkspaceConfig());
   for (const source of sources) {
     if (source.kind !== 'git') {
       throw new Error(
@@ -428,7 +412,10 @@ export async function walkDeclaredSources({
           'revision. Refusing rather than resolving.',
       );
     }
-    const { directory, commit } = materialize({ source, env });
+    holdSource(source, heldWorkspace, env);
+  }
+  for (const source of sources) {
+    const { directory, commit } = materialize({ source, env, workspace: heldWorkspace });
     if (!EXACT_COMMIT.test(String(commit))) {
       throw new Error(
         `source "${source.name}": walk produced commit "${commit}", which is not exact 40-hex`,

package/edition/git-source-auth.mjs

@@ -1,13 +1,18 @@
 // git-source-auth — the ONE place the edition library turns a read token into git
 // authentication for a repository URL, shared by every script that fetches or
-// lists a repository (first-party sources and a customer's own git source alike).
+// lists a repository (first-party and customer sources alike).
 //
 // The credential reaches git through GIT_CONFIG_* environment variables, never
 // argv, a file or a clone's config, and it is scoped to the ORIGIN of the URL it
 // is for: `http.<origin>/.extraHeader` is applied by git only to URLs under that
-// origin, so the token is not sent to any other host, nor to a host a redirect
-// leads to. For a first-party source pass `sourceRepositoryUrlPrefix` (from
-// edition-workspace.json); for a customer git source pass its own url.
+// origin, and redirects are not followed for a credentialed fetch. Source
+// credentials are declared only by the data root's edition-workspace.json
+// (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`), the token comes from
+// SOURCE_READ_TOKEN_ENV, and `holdSource` / `withSourceGitEnv` are the hold and the
+// environment every network git call on a source passes: a definition never names
+// a credential, a URL outside the prefix is fetched with none, and git runs
+// isolated from the user's own git configuration (global and system config,
+// ~/.netrc, credential helpers, URL rewrites).
 //
 // Why this is not `gitEnvWithAuth` of the CLI's runtime (src/runtime/sources/kinds/git.ts):
 // the edition library is plain ESM that `node` runs straight from this directory
@@ -16,37 +21,111 @@
 // on purpose (Basic `<declared username>:<token>`, `Authorization` header, origin
 // scope; the username is a required argument, never a built-in default), so there is exactly ONE implementation per runtime.
 
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { canonicalPublicHttpsRepositoryUrl } from './lib.mjs';
+
+/** The fixed environment variable holding the source read token. */
+export const SOURCE_READ_TOKEN_ENV = 'EVIDENCE_REPOSITORIES_TOKEN';
+
+/** Whether `canonicalUrl` names a repository under the workspace's `sourceRepositoryUrlPrefix`. */
+export function isUnderSourcePrefix(canonicalUrl, prefix) {
+  return canonicalUrl.startsWith(prefix) && canonicalUrl.length > prefix.length;
+}
+
+/** A definition does not declare source credentials; the data root does. */
+export function assertSourceDeclaresNoCredential(source) {
+  for (const key of ['authTokenEnv', 'authUsername']) {
+    if (source[key] !== undefined) {
+      throw new Error(
+        `source "${source.name}" declares "${key}". A definition does not declare source credentials; ` +
+          'the data root\'s edition-workspace.json does (`sourceRepositoryUrlPrefix` + `sourceAuthUsername`, ' +
+          `token from ${SOURCE_READ_TOKEN_ENV}). Remove the key.`,
+      );
+    }
+  }
+}
+
+/** The source's url, which must already be written in its canonical public https form. */
+export function assertCanonicalSourceUrl(source) {
+  const context = `source "${source.name}" url`;
+  const canonical = canonicalPublicHttpsRepositoryUrl(source.url, context);
+  if (canonical !== source.url) {
+    throw new Error(`${context} ${JSON.stringify(source.url)} is not in its canonical form (${canonical})`);
+  }
+  return canonical;
+}
+
+const INHERITED_GIT_VARIABLES = /^(GIT_CONFIG_(COUNT|KEY_\d+|VALUE_\d+|PARAMETERS|GLOBAL|NOSYSTEM)|GIT_ASKPASS|SSH_ASKPASS|GIT_SSL_NO_VERIFY|HOME|XDG_CONFIG_HOME)$/;
+
 /**
- * `base` plus the GIT_CONFIG_* header that authenticates git against `url`'s
- * origin as `username` with `token`. A token that cannot be applied is refused: an empty
- * token, or a URL that is not an absolute https URL with a host. There is no
- * fall-back to the ambient credential helper.
+ * THE HOLD, pure: refuses a source that declares a credential or whose URL is not canonical, and
+ * decides whether the workspace credential covers it. A covered source needs the token in
+ * SOURCE_READ_TOKEN_ENV (unset is refused, never replaced by an ambient credential). Spawns nothing.
  */
-export function gitAuthEnv(url, username, token, base = process.env) {
+export function holdSource(source, workspace, env = process.env) {
+  assertSourceDeclaresNoCredential(source);
+  const url = assertCanonicalSourceUrl(source);
+  if (!isUnderSourcePrefix(url, workspace.sourceRepositoryUrlPrefix)) {return { url, credential: null };}
+  const token = env[SOURCE_READ_TOKEN_ENV];
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new Error(
+      `source "${source.name}" is under the workspace's sourceRepositoryUrlPrefix ${workspace.sourceRepositoryUrlPrefix}, ` +
+        `which needs a read token, but ${SOURCE_READ_TOKEN_ENV} is unset or empty`,
+    );
+  }
+  const username = workspace.sourceAuthUsername;
   if (typeof username !== 'string' || username.length === 0 || username.includes(':')) {
     throw new Error(
-      `a git username is required to authenticate git against ${String(url)} (non-empty, no ":"); ` +
-        'it is declared, never defaulted: `sourceAuthUsername` in edition-workspace.json for first-party sources, ' +
-        'the source\'s own `authUsername` for a customer git source',
+      `a git username is required to authenticate git against ${url} (non-empty, no ":"); ` +
+        'it is declared, never defaulted: `sourceAuthUsername` in edition-workspace.json',
     );
   }
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new Error(`a read token is required to authenticate git against ${String(url)}`);
+  return { url, credential: { origin: new URL(url).origin, username, token } };
+}
+
+function isolatedGitEnv({ credential }, env, home) {
+  const base = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!INHERITED_GIT_VARIABLES.test(key)) {base[key] = value;}
   }
-  let origin;
-  try {
-    const parsed = new URL(url);
-    if (parsed.protocol !== 'https:' || parsed.hostname === '') {throw new Error('not an https URL with a host');}
-    origin = parsed.origin;
-  } catch {
-    throw new Error(`cannot scope a git credential to "${String(url)}": it is not an absolute https URL with a host`);
+  const entries = [
+    ['credential.helper', ''],
+    ['http.extraHeader', ''],
+  ];
+  if (credential !== null) {
+    const basic = Buffer.from(`${credential.username}:${credential.token}`, 'utf8').toString('base64');
+    entries.push(['http.followRedirects', 'false'], [`http.${credential.origin}/.extraHeader`, `Authorization: Basic ${basic}`]);
   }
-  const credential = Buffer.from(`${username}:${token}`, 'utf8').toString('base64');
+  const config = { GIT_CONFIG_COUNT: String(entries.length) };
+  entries.forEach(([key, value], index) => {
+    config[`GIT_CONFIG_KEY_${index}`] = key;
+    config[`GIT_CONFIG_VALUE_${index}`] = value;
+  });
   return {
     ...base,
-    GIT_CONFIG_COUNT: '1',
-    GIT_CONFIG_KEY_0: `http.${origin}/.extraHeader`,
-    GIT_CONFIG_VALUE_0: `Authorization: Basic ${credential}`,
+    ...config,
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_NOSYSTEM: '1',
+    HOME: home,
+    XDG_CONFIG_HOME: home,
     GIT_TERMINAL_PROMPT: '0',
   };
 }
+
+/**
+ * Run `fn(gitEnv)` with the git environment for one declared source; the hold comes first, before
+ * anything is created or spawned. The environment points HOME at an empty directory that exists
+ * only for the duration of `fn`.
+ */
+export function withSourceGitEnv(source, { workspace, env = process.env }, fn) {
+  const decision = holdSource(source, workspace, env);
+  const home = mkdtempSync(join(tmpdir(), 'xema-git-home-'));
+  try {
+    return fn(isolatedGitEnv(decision, env, home));
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+}

package/edition/image-evidence.mjs

@@ -600,17 +600,27 @@ function assertEvidenceChannel(channel) {
 }
 
 /**
- * The signers a policy authorizes for one predicate on ONE channel. Producer
- * evidence is further bound to the exact image repository the subject's
- * imageRef names (no prefix match).
+ * The policy rows that authorize `predicateType` on `channel`: a filter on the
+ * row's `channel` and `predicateTypes`, and, when `imageRepository` is given
+ * (producer evidence), on the row's `imageRepositories` holding that exact
+ * repository (no prefix match). It reads no certificate and proves nothing by
+ * itself.
  *
- * A signer belongs to one channel: the kernel policy schema, which every policy
- * this plane loads is parsed by, holds a row's `githubWorkflow.ref` to the ref
- * of its channel (`EVIDENCE_CHANNEL_REFS`) and its `certificateIdentity` to
- * that ref, so no signer can be authorized on two channels. The signature
- * therefore authenticates the channel: an edition descriptor that states the
- * other channel selects signers whose certificates the evidence does not carry,
- * or none at all.
+ * What ties a row to its channel is the kernel policy schema the policy was
+ * parsed by: a row's `githubWorkflow.ref` must be the ref of its `channel`
+ * (`EVIDENCE_CHANNEL_REFS`) and its `certificateIdentity` must be exactly
+ * `https://github.com/<repository>/<path>@<ref>`. One ROW is therefore one
+ * channel; the same workflow file may still be authorized on both channels, as
+ * two rows naming the two refs. The caller then runs cosign once per returned
+ * row with that row's `certificateIdentity`, `oidcIssuer`, workflow repository
+ * and ref (and the exact workflow commit), so evidence signed from the other
+ * channel's ref matches no row selected here and fails verification; an
+ * edition that states a channel with no row for the predicate is refused
+ * before cosign runs ("authorizes no signer").
+ *
+ * The channel an edition DESCRIPTOR states is unauthenticated input: it only
+ * selects which policy rows are tried; what authenticates a channel is the
+ * certificate matching a row of that channel.
  */
 function policyCandidates(policy, predicateType, channel, imageRepository) {
   return policy.policies.filter(

package/edition/kernel-contract-authority.mjs

@@ -291,11 +291,33 @@ export function assertExactCleanKernelContractCheckout({
   return head;
 }
 
+/** The flag by which a caller STATES the kernel commit a new contract authority is taken from. */
+export const KERNEL_COMMIT_FLAG = '--kernel-commit';
+
+/**
+ * The contract authority of the kernel checkout, held to the commit the caller
+ * STATES. A clean checkout at the kernel's origin URL proves only which
+ * repository the directory claims to be, never which commit somebody meant to
+ * pin: `kernelCommit` is that decision, it is required, and the checkout's HEAD
+ * must equal it. It is the `sourceCommit` the authority records.
+ */
 export async function buildTrustedKernelContractAuthority({
   repositoryDirectory = kernelRepoDir(),
   schemas,
+  kernelCommit,
 }) {
-  const sourceCommit = exactHeadCommit(repositoryDirectory);
+  if (typeof kernelCommit !== 'string' || !COMMIT_PATTERN.test(kernelCommit)) {
+    throw new Error(
+      `${KERNEL_COMMIT_FLAG} <40-hex> is required: a new kernel contract authority is pinned to the commit the caller states, never to whatever the checkout happens to hold`,
+    );
+  }
+  const head = exactHeadCommit(repositoryDirectory);
+  if (head !== kernelCommit) {
+    throw new Error(
+      `kernel contract repository HEAD ${head} is not the stated ${KERNEL_COMMIT_FLAG} ${kernelCommit}: check out the stated commit, or state the commit you mean to pin`,
+    );
+  }
+  const sourceCommit = kernelCommit;
   assertExactCleanKernelContractCheckout({
     repositoryDirectory,
     sourceCommit,