@xemahq/xema 0.27.0 → 0.29.0

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-delivery-entitlement-descriptor.mjs

@@ -0,0 +1,106 @@
+// `entitlement.json`: the file `xema edition evidence statement entitlement
+// accept` writes beside the signed statement, and the ONE reader of it
+// (`verify-evidence --entitlement`). Writer and reader share this module so the
+// shape is stated once.
+//
+// Every field but `evidence` is an UNAUTHENTICATED convenience for the operator
+// and for `verify-evidence`'s early refusals: the signed statement stays the
+// authority (`validateEntitlementStatementBinding`). The file names no workflow
+// SHA: the commit the entitlement's certificate is held to is stated by the
+// caller of the verifier (`--entitlement-workflow-sha`), never by the evidence.
+
+import { dirname, join } from 'node:path';
+
+export const ENTITLEMENT_DESCRIPTOR_FILE = 'entitlement.json';
+export const ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION = 2;
+
+const ENTITLEMENT_DESCRIPTOR_KEYS = Object.freeze([
+  'schemaVersion',
+  'distributionId',
+  'customerId',
+  'mode',
+  'targetRegistry',
+  'idempotencyKey',
+  'distributionStatementDigest',
+  'evidence',
+]);
+
+/** The document `accept` writes. `evidence` is the kernel Sigstore evidence descriptor of the signed statement. */
+export function entitlementDescriptorDocument({
+  distributionId,
+  customerId,
+  mode,
+  targetRegistry,
+  idempotencyKey,
+  distributionStatementDigest,
+  evidence,
+}) {
+  return {
+    schemaVersion: ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION,
+    distributionId,
+    customerId,
+    mode,
+    targetRegistry,
+    idempotencyKey,
+    distributionStatementDigest,
+    evidence,
+  };
+}
+
+/**
+ * Parse an `entitlement.json`: exactly the keys `accept` writes, at the one
+ * schema version, with `evidence` parsed by the kernel's Sigstore evidence
+ * descriptor schema. Any other shape is refused.
+ */
+export function parseEntitlementDescriptorDocument(raw, schemas) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} must be a JSON object`);
+  }
+  if (raw.schemaVersion !== ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} has schemaVersion ${JSON.stringify(raw.schemaVersion)}; ` +
+        `this verifier reads schemaVersion ${ENTITLEMENT_DESCRIPTOR_SCHEMA_VERSION} only (accept the entitlement again with this CLI)`,
+    );
+  }
+  const keys = Object.keys(raw).sort();
+  const expected = [...ENTITLEMENT_DESCRIPTOR_KEYS].sort();
+  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+    throw new Error(
+      `${ENTITLEMENT_DESCRIPTOR_FILE} must hold exactly the keys ${ENTITLEMENT_DESCRIPTOR_KEYS.join(', ')}; it holds ${keys.join(', ')}`,
+    );
+  }
+  for (const key of ['distributionId', 'customerId', 'mode', 'idempotencyKey', 'distributionStatementDigest']) {
+    if (typeof raw[key] !== 'string' || raw[key] === '') {
+      throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "${key}" must be a non-empty string`);
+    }
+  }
+  if (raw.targetRegistry !== null && (typeof raw.targetRegistry !== 'string' || raw.targetRegistry === '')) {
+    throw new Error(`${ENTITLEMENT_DESCRIPTOR_FILE} "targetRegistry" must be null or a non-empty string`);
+  }
+  return { ...raw, evidence: schemas.SigstoreEvidenceDescriptorSchema.parse(raw.evidence) };
+}
+
+/**
+ * Refuse an `entitlement.json` that states another request than the one being
+ * verified. `expected` holds the caller's flags and the completeness statement
+ * digest the verifier has just verified.
+ */
+export function assertEntitlementDescriptorStates(document, expected) {
+  for (const key of ['distributionId', 'customerId', 'mode', 'targetRegistry', 'distributionStatementDigest']) {
+    if (document[key] !== expected[key]) {
+      throw new Error(
+        `${ENTITLEMENT_DESCRIPTOR_FILE} states ${key} ${JSON.stringify(document[key])}, ` +
+          `not the ${JSON.stringify(expected[key])} this verification was asked for`,
+      );
+    }
+  }
+}
+
+/**
+ * The evidence descriptor's paths are relative to the directory `accept` sealed
+ * (the one holding `entitlement.json`), which lies inside the evidence root the
+ * descriptor file itself was read from.
+ */
+export function entitlementEvidenceRoot(evidenceRoot, entitlementDescriptorPath) {
+  return dirname(join(evidenceRoot, entitlementDescriptorPath));
+}

package/edition/image-evidence.mjs

@@ -600,9 +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.
+ *
+ * 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,

package/edition/lib.mjs

@@ -24,7 +24,6 @@ import {
   kernelDistPath,
   kernelPackageDir,
   kernelRepoDir,
-  sourceHashPackageDir,
   sourcePath,
 } from './edition-workspace.mjs';
 import { SHA256_HEX_PATTERN } from './evidence-grammars.mjs';
@@ -149,38 +148,28 @@ export const BIOME_WORKLOAD_KINDS = new Set(['service', 'runtime-component']);
 export const DEFAULT_BIOME_WORKLOAD_KIND = 'service';
 
 /**
- * The BUILT `@xemahq/distribution-source-hash` package (CJS dist), loaded from
- * the directory the entry states with `--source-hash`.
+ * The `@xemahq/distribution-source-hash` package (CJS dist), a caret (0.x minor-locked)
+ * dependency of the CLI, loaded by name on first use.
  *
  * That package is the SINGLE owner of `xema-source-tree-sha256-v2` — the same
  * implementation every producing repository's CI uses to derive the
  * `<contentHash>` release tag. This tooling must never carry a second copy: a
  * divergence would put a lock and its images at coordinates that silently
- * disagree. It is NOT an npm dependency of the CLI: the evidence verifier never
- * hashes a source tree, so its bundle must not reach this package; only the
- * entries that resolve, build, index or seal state the root.
+ * disagree. The evidence verifier never hashes a source tree, so its bundle
+ * does not reach this package; only the entries that resolve, build, index or
+ * seal load it.
  */
 const requireFromLib = createRequire(import.meta.url);
 
-const loadedSourceHash = new Map();
+let loadedSourceHash;
 
 function distributionSourceHash() {
-  const directory = sourceHashPackageDir();
-  const known = loadedSourceHash.get(directory);
-  if (known) {return known;}
-  let mod;
-  try {
-    mod = createRequire(join(directory, 'package.json'))(directory);
-  } catch (err) {
-    throw new Error(
-      `Cannot load the built distribution-source-hash package from ${directory}. ` +
-        `Build it first (\`pnpm install --frozen-lockfile && pnpm run build\` in its workspace). ` +
-        `Underlying error: ${err.message}`,
-    );
+  if (loadedSourceHash === undefined) {
+    const mod = requireFromLib('@xemahq/distribution-source-hash');
+    assertSourceHashMatchesKernel(mod);
+    loadedSourceHash = mod;
   }
-  assertSourceHashMatchesKernel(mod);
-  loadedSourceHash.set(directory, mod);
-  return mod;
+  return loadedSourceHash;
 }
 
 /**
@@ -214,9 +203,9 @@ function requireAlgorithmMember(enumObject, enumName, member) {
   const value = enumObject?.[member];
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(
-      `Built @xemahq/distribution-source-hash does not declare ` +
+      `@xemahq/distribution-source-hash does not declare ` +
         `${enumName}.${member}. The installed package is `+
-        `stale or the member was renamed; raise the @xemahq/distribution-source-hash range and, if the `+
+        `stale or the member was renamed; change the pinned @xemahq/distribution-source-hash version and, if the `+
         `rename was deliberate, move every reader in the same change.`,
     );
   }
@@ -722,6 +711,7 @@ export async function loadKernelDistributionSchemas() {
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
+    SigstoreEvidenceDescriptorSchema,
     parsePlatformServiceSourceIndex,
     parseRuntimeImageSourceIndex,
     resolveRuntimeImagePlatforms,
@@ -798,6 +788,7 @@ export async function loadKernelDistributionSchemas() {
     typeof parseDistributionImageEvidenceSet !== 'function' ||
     typeof parseDistributionImageReplayState !== 'function' ||
     typeof parseSigstoreOfflineTrustPolicy !== 'function' ||
+    typeof SigstoreEvidenceDescriptorSchema?.parse !== 'function' ||
     typeof parsePlatformServiceSourceIndex !== 'function' ||
     typeof parseRuntimeImageSourceIndex !== 'function' ||
     typeof resolveRuntimeImagePlatforms !== 'function' ||
@@ -892,6 +883,7 @@ export async function loadKernelDistributionSchemas() {
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
+    SigstoreEvidenceDescriptorSchema,
     parsePlatformServiceSourceIndex,
     parseRuntimeImageSourceIndex,
     resolveRuntimeImagePlatforms,

package/edition/oras.mjs

@@ -173,7 +173,7 @@ function assertOrasVersion(bin, home) {
 /**
  * The oras digests the configured data root trusts: `trustedOrasBinaryDigests`
  * of its evidence-trust pin. `null` when the data root declares no evidence
- * trust at all (`evidenceTrustPolicy: {"required": false}` with no policy):
+ * trust at all (`evidenceTrustPolicy: null`):
  * such a data root has no reviewed pin to hold a binary to.
  */
 export function configuredOrasTrust() {

package/edition/pin-source.mjs

@@ -65,13 +65,18 @@ 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 (key.startsWith(SOURCE_PIN_PREFIX) && key.length > SOURCE_PIN_PREFIX.length) {
+  if (isSourcePinKey(key)) {
     return SnapshotPinNamespace.Source;
   }
   if (GRAPH_PIN_PATTERN.test(key)) {return SnapshotPinNamespace.Graph;}

package/edition/produce-image-delivery-entitlement-evidence.mjs

@@ -28,6 +28,7 @@ import {
   dataRoot,
   isEntryModule,
 } from './edition-workspace.mjs';
+import { ENTITLEMENT_DESCRIPTOR_FILE, entitlementDescriptorDocument } from './image-delivery-entitlement-descriptor.mjs';
 import { canonicalJsonBytes, readCanonicalJsonFromRoot } from './image-evidence.mjs';
 import { serializeJson } from './lib.mjs';
 import { githubWorkflowSigner } from './produce-distribution-completeness-evidence.mjs';
@@ -38,7 +39,6 @@ import {
 } from './produce-image-source-evidence.mjs';
 import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
 
-const ENTITLEMENT_DESCRIPTOR_FILE = 'entitlement.json';
 const ENTITLEMENT_STATEMENT_PATH = 'entitlement/statement.json';
 const ENTITLEMENT_BUNDLE_PATH = 'entitlement/bundle.sigstore.json';
 
@@ -176,17 +176,17 @@ export function acceptImageDeliveryEntitlementEvidence(options) {
       const descriptor = acceptSignedEvidenceStatement({ ...signing, sealingRoot: sealing, runCosign });
       writeFileSync(
         join(sealing, ENTITLEMENT_DESCRIPTOR_FILE),
-        canonicalJsonBytes({
-          schemaVersion: 1,
-          distributionId: options.distributionId,
-          customerId: options.customerId,
-          mode: options.mode,
-          targetRegistry: options.targetRegistry,
-          idempotencyKey: options.idempotencyKey,
-          distributionStatementDigest: completenessStatementDigest,
-          signingWorkflowSha: options.signingWorkflowSha,
-          evidence: descriptor,
-        }),
+        canonicalJsonBytes(
+          entitlementDescriptorDocument({
+            distributionId: options.distributionId,
+            customerId: options.customerId,
+            mode: options.mode,
+            targetRegistry: options.targetRegistry,
+            idempotencyKey: options.idempotencyKey,
+            distributionStatementDigest: completenessStatementDigest,
+            evidence: descriptor,
+          }),
+        ),
         { flag: 'wx', mode: 0o644 },
       );
       return { outputDirectory, statement, descriptor, completenessStatementDigest };

package/edition/registry-credentials.mjs

@@ -117,7 +117,17 @@ export function loadRegistryCredentialDeclarations(
   distributionsRoot = dataRoot(),
 ) {
   const path = join(distributionsRoot, REGISTRY_CREDENTIALS_FILE);
-  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {throw error;}
+    throw new Error(
+      `${REGISTRY_CREDENTIALS_FILE} does not exist in ${distributionsRoot}: the editions root declares the registry credentials its images are verified with`,
+      { cause: error },
+    );
+  }
+  const raw = JSON.parse(text);
   const keys = Object.keys(raw ?? {}).sort().join(',');
   if (
     typeof raw !== 'object' ||

package/edition/release-channel-guard.mjs

@@ -60,8 +60,18 @@ export function assertReleaseEditionTree(dir) {
  */
 export const RELEASE_COMPANION_FILES = Object.freeze([EDITION_CHART_SET_FILE]);
 
+/**
+ * The release locks an edition directory holds (the distribution and the
+ * authorization lock). A directory holding either IS a release edition: a
+ * develop resolve writes nothing into an editions tree, so a lock committed
+ * there was written by the release resolve.
+ */
+export function heldReleaseLocks(dir) {
+  return [EditionLockFile.Distribution, EditionLockFile.Authorization].filter((file) => existsSync(join(dir, file)));
+}
+
 function assertReleaseLockSet(dir) {
-  const held = [EditionLockFile.Distribution, EditionLockFile.Authorization].filter((file) => existsSync(join(dir, file)));
+  const held = heldReleaseLocks(dir);
   if (held.length === 0) {return;}
   const missing = RELEASE_COMPANION_FILES.filter((file) => !existsSync(join(dir, file)));
   if (missing.length > 0) {

package/edition/release-edition-artifact.mjs

@@ -2,12 +2,12 @@
 // release-edition-artifact — write the OCI artifact of a RELEASE edition from
 // the committed, sealed locks of the editions root.
 //
-//   artifact <id> --channel release --registry <namespace> --coordinate <tag>
+//   artifact <id> --channel release --registry <root> --coordinate <tag>
 //            --engine-image <repository>@sha256:<digest> --out <dir> [--local]
 //
 // The artifact has the layout of every edition (edition-artifact.mjs): the
 // descriptor plus the four locks and the offering's catalogue.json, written to <dir>, and the target
-// `<registry>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
+// `<root>/<release namespace segment>/xema-edition-<id>:<coordinate>` is printed. The workflow pushes
 // <dir> with oras and signs the manifest DIGEST with cosign; the tag is for
 // humans. A lock set that is not sealed is refused: an unsealed images lock names
 // no image digests, so nothing could be admitted against it.
@@ -128,13 +128,12 @@ export async function readCommittedEdition(id, root = editionsRoot()) {
 
 async function run(argv, env) {
   const { id, options } = parseReleaseArtifactArgs(argv);
-  const target = editionTarget(id, options['--registry'], options['--coordinate']);
+  const target = editionTarget(id, options['--registry'], EditionChannel.Release, options['--coordinate']);
   const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
   const locks = await readCommittedEdition(id);
+  // Refuses (EvidenceTrustRequiredError) unless the policy is ARMED on the
+  // release channel: a release artifact is never written not-armed.
   const evidenceTrustPolicy = await descriptorEvidenceTrust({ channel: EditionChannel.Release });
-  if (evidenceTrustPolicy === 'not-armed') {
-    console.warn('[edition-artifact] evidence trust policy: NOT ARMED — the descriptor records not-armed.');
-  }
   const outDir = resolve(options['--out']);
   writeEditionArtifact({
     outDir,