@xemahq/xema 0.59.1 → 0.60.1

package/edition/producer-evidence-bundle.mjs

@@ -1,201 +0,0 @@
-import { readFileSync, statSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
-
-
-import {
-  canonicalJson,
-  decodeExactUtf8,
-  sha256Digest,
-} from './image-evidence.mjs';
-import {
-  BUNDLE_MEDIA_TYPE,
-  validateProducedBundle,
-} from './produce-image-source-evidence.mjs';
-import { PRODUCER_EVIDENCE_INDEX_FILE } from './producer-evidence-index-file.mjs';
-
-export { PRODUCER_EVIDENCE_INDEX_FILE };
-export const PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE =
-  'application/vnd.xema.image-source-evidence.index.v1+json';
-export const PRODUCER_STATEMENT_MEDIA_TYPE = 'application/vnd.in-toto+json';
-export const MAX_PRODUCER_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
-
-function assertRelativeArtifactPath(value, label) {
-  if (
-    typeof value !== 'string' ||
-    value.length === 0 ||
-    value.startsWith('/') ||
-    value.split('/').some((part) => !part || part === '.' || part === '..')
-  ) {
-    throw new Error(`${label} is not a contained relative path`);
-  }
-  return value;
-}
-
-function readBounded(root, relativePath, label) {
-  const safePath = assertRelativeArtifactPath(relativePath, label);
-  const path = join(root, safePath);
-  const stat = statSync(path);
-  if (!stat.isFile() || stat.size > MAX_PRODUCER_EVIDENCE_FILE_BYTES) {
-    throw new Error(
-      `${label} must be a regular file no larger than ${MAX_PRODUCER_EVIDENCE_FILE_BYTES} bytes`,
-    );
-  }
-  return readFileSync(path);
-}
-
-/**
- * Fields that identify the immutable build are stable. producerRun identifies
- * one signing execution and intentionally changes on every retry/refresh.
- */
-export function stableProducerStatementBinding(statement) {
-  const { producerRun: _producerRun, ...predicate } = statement.predicate;
-  return {
-    _type: statement._type,
-    subject: statement.subject,
-    predicateType: statement.predicateType,
-    predicate,
-  };
-}
-
-export function producerStatementMatchesInput(statement, expectedStatement) {
-  return (
-    canonicalJson(stableProducerStatementBinding(statement)) ===
-    canonicalJson(stableProducerStatementBinding(expectedStatement))
-  );
-}
-
-/**
- * The RAW `predicate.contractAuthority.sourceCommit` of every statement a
- * producer evidence directory carries, read BEFORE any schema parse: the parse
- * is bound to one kernel authority, so deciding whose authority a statement
- * speaks under cannot go through it. A statement that states no string commit
- * contributes nothing here; the strict parse refuses it later.
- */
-export function readRawStatementAuthorityCommits({ directory }) {
-  const index = JSON.parse(
-    decodeExactUtf8(
-      readBounded(directory, PRODUCER_EVIDENCE_INDEX_FILE, 'producer evidence index'),
-      'producer evidence index',
-    ),
-  );
-  if (!Array.isArray(index?.producerEvidence)) {
-    throw new Error('producer evidence index is not non-empty schemaVersion 1');
-  }
-  const commits = new Set();
-  for (const entry of index.producerEvidence) {
-    const statement = JSON.parse(
-      decodeExactUtf8(
-        readBounded(directory, entry?.evidence?.statementPath, 'producer statement'),
-        'producer statement',
-      ),
-    );
-    const commit = statement?.predicate?.contractAuthority?.sourceCommit;
-    if (typeof commit === 'string') {commits.add(commit);}
-  }
-  return commits;
-}
-
-/**
- * Evidence bytes that do not match the digests that describe them: a tampering
- * signal. It is never an invalid-but-skippable referrer; it fails closed.
- */
-export class EvidenceIntegrityError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'EvidenceIntegrityError';
-  }
-}
-
-/** Read and structurally validate one producer evidence directory. */
-export function readProducerEvidenceDirectory({ directory, schemas }) {
-  if (!isAbsolute(directory)) {
-    throw new Error('producer evidence directory must be absolute');
-  }
-  if (!schemas?.parseImageProducerStatement) {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
-  const indexBytes = readBounded(
-    directory,
-    PRODUCER_EVIDENCE_INDEX_FILE,
-    'producer evidence index',
-  );
-  let index;
-  try {
-    index = JSON.parse(decodeExactUtf8(indexBytes, 'producer evidence index'));
-  } catch (error) {
-    throw new Error(`producer evidence index is not exact UTF-8 JSON: ${error.message}`);
-  }
-  if (
-    index?.schemaVersion !== 1 ||
-    !Array.isArray(index.producerEvidence) ||
-    index.producerEvidence.length === 0
-  ) {
-    throw new Error('producer evidence index is not non-empty schemaVersion 1');
-  }
-
-  const seen = new Set();
-  const records = [];
-  for (const entry of index.producerEvidence) {
-    const key = `${entry?.subjectKind}:${entry?.subjectId}`;
-    if (
-      typeof entry?.subjectKind !== 'string' ||
-      typeof entry?.subjectId !== 'string' ||
-      entry.evidence === null ||
-      typeof entry.evidence !== 'object' ||
-      seen.has(key)
-    ) {
-      throw new Error(`producer evidence index has a malformed or duplicate entry ${key}`);
-    }
-    seen.add(key);
-    const descriptor = entry.evidence;
-    const statementBytes = readBounded(
-      directory,
-      descriptor.statementPath,
-      `${key} statement`,
-    );
-    const bundleBytes = readBounded(
-      directory,
-      descriptor.bundlePath,
-      `${key} bundle`,
-    );
-    if (
-      descriptor.bundleMediaType !== BUNDLE_MEDIA_TYPE ||
-      sha256Digest(statementBytes) !== descriptor.statementDigest ||
-      sha256Digest(bundleBytes) !== descriptor.bundleDigest
-    ) {
-      throw new EvidenceIntegrityError(`${key} artifacts do not match their descriptor`);
-    }
-    validateProducedBundle(statementBytes, bundleBytes);
-    const statement = schemas.parseImageProducerStatement(
-      JSON.parse(decodeExactUtf8(statementBytes, `${key} statement`)),
-    );
-    if (
-      statement.predicate.source.kind !== entry.subjectKind ||
-      statement.predicate.source.id !== entry.subjectId
-    ) {
-      throw new Error(`${key} index identity does not match its signed statement`);
-    }
-    records.push({
-      key,
-      entry,
-      descriptor,
-      statement,
-      statementBytes,
-      bundleBytes,
-    });
-  }
-  return { index, indexBytes, records };
-}
-
-export function producerEvidenceLayerFiles(records) {
-  return [
-    {
-      path: PRODUCER_EVIDENCE_INDEX_FILE,
-      mediaType: PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE,
-    },
-    ...records.flatMap(({ descriptor }) => [
-      { path: descriptor.statementPath, mediaType: PRODUCER_STATEMENT_MEDIA_TYPE },
-      { path: descriptor.bundlePath, mediaType: BUNDLE_MEDIA_TYPE },
-    ]),
-  ];
-}

package/edition/producer-evidence-index-file.mjs

@@ -1,4 +0,0 @@
-// The file name of a producer evidence directory's index. Its own module because the evidence verifier bundle needs it and must
-// not import a producer entry (every module of a bundle shares one `import.meta.url`, so a producer's entry guard would run
-// inside the verifier).
-export const PRODUCER_EVIDENCE_INDEX_FILE = 'producer-evidence.json';

package/edition/record-refused.mjs

@@ -1,12 +0,0 @@
-// record-refused — the refusal class of `select-records`: the data says no (a record is missing, unsigned,
-// contradicts its tag, or its commit is not the develop line). Leaf module, so the ancestry check and the
-// selection can both subclass it. A registry, cosign or git that could not answer is a plain Error instead.
-
-export class RecordRefused extends Error {
-  /** `context` labels the verb the refusal surfaces in (select-records by default, `follow` for its sources). */
-  constructor(repo, message, context = 'select-records') {
-    super(`${context}: ${repo}: ${message}`);
-    this.name = 'RecordRefused';
-    this.repo = repo;
-  }
-}

package/edition/registry-credentials.mjs

@@ -1,225 +0,0 @@
-// Registry credential DECLARATIONS and image-reference parsing.
-//
-// This module owns the committed `image-registry-credentials.json` contract:
-// which registry authorities may be read, whether each is read anonymously or
-// with a credential taken from a NAMED environment variable, and how an image
-// reference splits into authority and repository. It performs no I/O against a
-// registry; `oras.mjs` owns the transport.
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { dataRoot } from './edition-workspace.mjs';
-import { isCanonicalRegistryAuthority } from './lib.mjs';
-
-export const REGISTRY_CREDENTIALS_FILE = 'image-registry-credentials.json';
-
-/**
- * Closed set. `anonymous` means "this registry is deliberately read without a
- * credential"; `authenticated` means "a credential is mandatory". There is no
- * third state, and in particular no "try authenticated, fall back to
- * anonymous" — that fallback is exactly how a private registry silently
- * degrades into an unverifiable one.
- */
-const REGISTRY_ACCESS_MODES = Object.freeze(['anonymous', 'authenticated']);
-
-
-export const OCI_INDEX_MEDIA_TYPES = Object.freeze([
-  'application/vnd.oci.image.index.v1+json',
-  'application/vnd.docker.distribution.manifest.list.v2+json',
-]);
-
-export const OCI_MANIFEST_MEDIA_TYPES = Object.freeze([
-  'application/vnd.oci.image.manifest.v1+json',
-  'application/vnd.docker.distribution.manifest.v2+json',
-]);
-
-const ENV_VAR_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
-
-// Docker Hub is the one registry whose wire authority is not its reference
-// authority (`docker.io` resolves to `registry-1.docker.io`, and single-segment
-// repositories are implicitly `library/*`). Implementing that rewrite silently
-// would make one registry behave differently from every other. Refuse instead.
-const AUTHORITIES_REQUIRING_EXPLICIT_REWRITE = new Set([
-  'docker.io',
-  'index.docker.io',
-  'registry.hub.docker.com',
-]);
-
-/**
- * Split `registry.example.com/acme/service` into its registry authority and repository
- * path. The image lock already guarantees the shape; this re-derives it rather
- * than trusting a caller-supplied split.
- */
-export function splitImageRef(imageRef) {
-  if (typeof imageRef !== 'string' || imageRef.length === 0) {
-    throw new Error('image reference must be a non-empty string');
-  }
-  const slash = imageRef.indexOf('/');
-  if (slash <= 0 || slash === imageRef.length - 1) {
-    throw new Error(
-      `image reference "${imageRef}" has no registry authority and repository path`,
-    );
-  }
-  const authority = imageRef.slice(0, slash);
-  const repository = imageRef.slice(slash + 1);
-  if (!isCanonicalRegistryAuthority(authority)) {
-    throw new Error(
-      `image reference "${imageRef}" does not start with a canonical registry authority`,
-    );
-  }
-  return { authority, repository };
-}
-
-export function assertCredentialDeclaration(entry, index) {
-  const label = `${REGISTRY_CREDENTIALS_FILE} registries[${index}]`;
-  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-    throw new Error(`${label} must be an object`);
-  }
-  if (
-    typeof entry.authority !== 'string' ||
-    !isCanonicalRegistryAuthority(entry.authority)
-  ) {
-    throw new Error(`${label}.authority must be a canonical registry authority`);
-  }
-  if (!REGISTRY_ACCESS_MODES.includes(entry.access)) {
-    throw new Error(
-      `${label}.access must be one of ${REGISTRY_ACCESS_MODES.join(', ')}`,
-    );
-  }
-  const keys = Object.keys(entry).sort().join(',');
-  if (entry.access === 'authenticated') {
-    if (keys !== 'access,authTokenEnv,authority,username') {
-      throw new Error(
-        `${label} must declare exactly access, authTokenEnv, authority, username`,
-      );
-    }
-    if (!ENV_VAR_NAME_PATTERN.test(entry.authTokenEnv)) {
-      throw new Error(
-        `${label}.authTokenEnv must be an UPPER_SNAKE environment variable NAME (never an inlined secret)`,
-      );
-    }
-    if (typeof entry.username !== 'string' || entry.username.length === 0) {
-      throw new Error(`${label}.username must be a non-empty string`);
-    }
-  } else if (keys !== 'access,authority') {
-    throw new Error(`${label} must declare exactly access and authority`);
-  }
-  return entry;
-}
-
-/**
- * Read the committed registry credential DECLARATION. The file names
- * environment variables; it never contains a secret. See
- * `.claude/rules/biome-sources.md` constraint C2.
- */
-export function loadRegistryCredentialDeclarations(
-  distributionsRoot = dataRoot(),
-) {
-  const path = join(distributionsRoot, REGISTRY_CREDENTIALS_FILE);
-  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 },
-    );
-  }
-  return parseRegistryCredentialDeclarations(text, REGISTRY_CREDENTIALS_FILE);
-}
-
-/**
- * A registry credential declaration file the CALLER names, in the same strict
- * schema: a third-party publisher states its own registries this way
- * (`evidence assemble-third-party-input --registry-credentials <file>`). A
- * missing file is refused; there is no default declaration.
- */
-export function loadRegistryCredentialDeclarationsFile(path) {
-  let text;
-  try {
-    text = readFileSync(path, 'utf8');
-  } catch (error) {
-    if (error?.code !== 'ENOENT') {throw error;}
-    throw new Error(`the registry credential declaration ${path} does not exist`, { cause: error });
-  }
-  return parseRegistryCredentialDeclarations(text, path);
-}
-
-/** The declarations of one credential declaration file's text, strict schema v1, by authority. */
-function parseRegistryCredentialDeclarations(text, label) {
-  const raw = JSON.parse(text);
-  const keys = Object.keys(raw ?? {}).sort().join(',');
-  if (
-    typeof raw !== 'object' ||
-    raw === null ||
-    Array.isArray(raw) ||
-    raw.schemaVersion !== 1 ||
-    !Array.isArray(raw.registries) ||
-    (keys !== 'registries,schemaVersion' &&
-      keys !== '$comment,registries,schemaVersion') ||
-    ('$comment' in raw &&
-      (!Array.isArray(raw.$comment) ||
-        raw.$comment.some((line) => typeof line !== 'string')))
-  ) {
-    throw new Error(`${label} is not strict schema v1`);
-  }
-  const byAuthority = new Map();
-  for (const [index, entry] of raw.registries.entries()) {
-    assertCredentialDeclaration(entry, index);
-    if (byAuthority.has(entry.authority)) {
-      throw new Error(
-        `${label} declares "${entry.authority}" more than once`,
-      );
-    }
-    byAuthority.set(entry.authority, entry);
-  }
-  return byAuthority;
-}
-
-/**
- * Resolve a declared authority to the credential it will actually use.
- *
- * A NAMED-but-unset environment variable FAILS FAST. It must never fall
- * through to an unauthenticated request: that is how a 403 on a private
- * package turns into "the platform is missing" instead of "your token is
- * missing".
- */
-export function resolveRegistryCredential({
-  authority,
-  declarations,
-  env = process.env,
-}) {
-  const declaration = declarations.get(authority);
-  if (!declaration) {
-    throw new Error(
-      `registry "${authority}" has no entry in ${REGISTRY_CREDENTIALS_FILE}; ` +
-        'declare it with access "anonymous" or "authenticated" before reading from it',
-    );
-  }
-  if (AUTHORITIES_REQUIRING_EXPLICIT_REWRITE.has(authority)) {
-    throw new Error(
-      `registry "${authority}" needs a documented authority/repository rewrite that this client deliberately does not perform`,
-    );
-  }
-  if (declaration.access === 'anonymous') {
-    return { authority, access: 'anonymous', basicAuth: null };
-  }
-  const token = env[declaration.authTokenEnv];
-  if (typeof token !== 'string' || token.length === 0) {
-    throw new Error(
-      `registry "${authority}" requires a pull credential in $${declaration.authTokenEnv}, ` +
-        'and that variable is unset or empty. Export a token with read:packages ' +
-        'scope for this registry; an unauthenticated read is NOT attempted, because ' +
-        'a 403 on a private package is indistinguishable from a missing image.',
-    );
-  }
-  return {
-    authority,
-    access: 'authenticated',
-    basicAuth: Buffer.from(`${declaration.username}:${token}`, 'utf8').toString(
-      'base64',
-    ),
-  };
-}

package/edition/release-catalogue.mjs

@@ -1,47 +0,0 @@
-// release-catalogue — the catalogue of a RELEASE offering, from its committed, sealed locks.
-
-import { biomeSourceTreeIds } from './biome-content.mjs';
-import { buildCatalogue } from './catalogue.mjs';
-import { EditionChannel } from './edition-constants.mjs';
-import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import { kernelPackageDir } from './edition-workspace.mjs';
-import { kernelPackageOfAuthority } from './kernel-package.mjs';
-import { loadKernelDistributionSchemas } from './lib.mjs';
-import { loadEditionManifest } from './resolve-distribution.mjs';
-import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
-import { createPinnedSourceAuthority } from './source-authority.mjs';
-
-/** The catalogue of release offering `id`, from the committed locks (`locks` as `readCommittedEdition` returns them). */
-export async function releaseCatalogue(id, locks, { fetchKernelTarball } = {}) {
-  const schemas = await loadKernelDistributionSchemas();
-  // The EDITION's indexes and pins: a held repository is catalogued at the held commit.
-  const pinned = await editionPinnedInputs(id, { schemas });
-  const authority = createPinnedSourceAuthority({ pins: pinned.repositoryPins });
-  // The WRITER of the catalogue's tree ids: the real `git rev-parse <commit>:<path>` of every biome.
-  const sourceTreeIds = await biomeSourceTreeIds({
-    schemas,
-    lock: locks.distributionLock,
-    imageLock: locks.imageLock,
-    locate: sourceTreeLocator(externalSourceTrees(locks.distributionLock)),
-    vendoredCommit: (repo) => authority.vendoredSourceCommitForRepository(repo),
-  });
-  const { contractAuthority } = pinned.runtimeImageSourceIndex;
-  return buildCatalogue({
-    sourceTreeIds,
-    offeringId: id,
-    channel: EditionChannel.Release,
-    distributionLock: locks.distributionLock,
-    imageLock: locks.imageLock,
-    chartSetLock: locks.chartSetLock,
-    biomeIndex: pinned.biomeIndex,
-    platformServiceIndex: pinned.platformServiceIndex,
-    contractAuthority,
-    kernel: await kernelPackageOfAuthority({
-      kernelPackageDir: kernelPackageDir(),
-      contractAuthority,
-      ...(fetchKernelTarball === undefined ? {} : { fetchTarball: fetchKernelTarball }),
-    }),
-    leaf: loadEditionManifest(schemas.parseDistribution, id),
-  });
-}
-

package/edition/release-channel-guard.mjs

@@ -1,108 +0,0 @@
-#!/usr/bin/env node
-// release-channel-guard — release tooling's content assertions over an editions
-// tree.
-//
-// No check here reads a channel label, a schema name or a file name to decide
-// what an edition IS: admission rests on the cosign signature of the artifact's
-// manifest digest, and the descriptor's `provenance.channel` is a record, never
-// a gate. What stays is what the BYTES must satisfy: a release images lock names
-// release repositories only, and a release lock set is whole (the companion
-// chart-set lock beside the distribution and authorization locks).
-//
-//   node release-channel-guard.mjs <checkout-dir>
-//     refuses if any edition directory under <checkout-dir> breaks either.
-
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-import { isDevelopImageRef } from './develop-image-coordinate.mjs';
-import { EDITION_CHART_SET_FILE, assertRosteredChartSetLock } from './edition-chart-set.mjs';
-import { EditionLockFile } from './edition-constants.mjs';
-import { isEntryModule } from './edition-workspace.mjs';
-
-/** Throws when `value` (a parsed JSON document) names a develop image repository. `where` names it in the refusal. */
-export function assertReleaseContent(value, where) {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {return;}
-  const developSubject = (value.subjects ?? []).find((subject) => isDevelopImageRef(subject?.imageRef));
-  if (developSubject) {
-    throw new Error(
-      `${where} names the develop image repository ${developSubject.imageRef} (subject ${developSubject.kind}:${developSubject.id}); ` +
-        'a release lock names release repositories only',
-    );
-  }
-  // A chart-set lock (one with a roster of publishers) carries content coordinates only.
-  if (Array.isArray(value.publishers)) {
-    assertRosteredChartSetLock(value, where);
-  }
-}
-
-/** Throws when an edition directory holds a lock naming a develop image repository, or a release lock without its companions. */
-export function assertReleaseEditionTree(dir) {
-  for (const file of [EditionLockFile.Distribution, EditionLockFile.Images, EditionLockFile.Authorization, EditionLockFile.ChartSet]) {
-    const path = join(dir, file);
-    if (existsSync(path)) {assertReleaseContent(JSON.parse(readFileSync(path, 'utf8')), path);}
-  }
-  assertReleaseLockSet(dir);
-}
-
-/**
- * The release lock set. A directory holding the distribution or the
- * authorization lock must hold the whole set, including the `chart-set.lock.json`
- * the release writes with them and hashes into the edition's coordinate, so a
- * lock copied alone into an edition directory is refused.
- *
- * What this guarantees is PRESENCE, not binding: the companion chart-set lock
- * must exist beside the locks. It does not check that the set's locks agree
- * with one another or with a recorded digest (nothing records one: the release
- * envelope does not carry a lock-set digest), so it is not "hash-bound" and
- * must not be described as such.
- */
-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 = heldReleaseLocks(dir);
-  if (held.length === 0) {return;}
-  const missing = RELEASE_COMPANION_FILES.filter((file) => !existsSync(join(dir, file)));
-  if (missing.length > 0) {
-    throw new Error(
-      `${dir} holds ${held.join(' and ')} but not ${missing.join(' and ')}: a release edition carries its locks as one set, ` +
-        'so a lock without its companions is not a release edition. ' +
-        'Resolve the edition whole, or remove the stray lock.',
-    );
-  }
-}
-
-/** The guard over every direct subdirectory of a checkout (each is an edition or holds none). */
-export function assertReleaseCheckout(root) {
-  let checked = 0;
-  for (const entry of readdirSync(root).sort()) {
-    if (entry.startsWith('.') || entry === 'node_modules') {continue;}
-    const dir = join(root, entry);
-    if (!statSync(dir).isDirectory()) {continue;}
-    assertReleaseEditionTree(dir);
-    checked += 1;
-  }
-  return checked;
-}
-
-if (isEntryModule(import.meta.url)) {
-  try {
-    const [root, ...rest] = process.argv.slice(2);
-    if (!root || rest.length > 0) {throw new Error('usage: node release-channel-guard.mjs <checkout-dir>');}
-    const checked = assertReleaseCheckout(resolve(root));
-    console.log(`[release-channel-guard] ${checked} directories hold no develop content.`);
-  } catch (error) {
-    console.error(`[release-channel-guard] ${error.message}`);
-    process.exit(1);
-  }
-}