@xemahq/xema 0.26.0 → 0.27.0

package/edition/built-verifier.mjs

@@ -0,0 +1,55 @@
+// Where this CLI's built evidence verifier sits. The verifier is ONE bundle,
+// built at CLI build time from the CLI's own sources and its locked
+// dependencies, and shipped in the npm tarball beside a provenance record.
+//
+// The package directory is the one place the library derives a location from
+// where it sits: the bundle is a property of the installed CLI, not of any
+// workspace root. Callers that need another location (tests) pass it.
+
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { verifierDigests } from './evidence-trust-pin.mjs';
+import {
+  VERIFIER_BUNDLE_FILE,
+  VERIFIER_DIST_SUBPATH,
+  VERIFIER_PROVENANCE_FILE,
+} from './verifier-files.mjs';
+
+const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The built verifier's two files under `packageDir` (this package by default). */
+export function locateBuiltVerifier(packageDir = PACKAGE_DIR) {
+  const directory = join(packageDir, ...VERIFIER_DIST_SUBPATH);
+  return Object.freeze({
+    bundlePath: join(directory, VERIFIER_BUNDLE_FILE),
+    provenancePath: join(directory, VERIFIER_PROVENANCE_FILE),
+  });
+}
+
+/**
+ * The digests of the built verifier a pin records. A missing file is refused,
+ * naming the path - never skipped.
+ */
+export function readBuiltVerifierDigests(locateVerifier = locateBuiltVerifier) {
+  const { bundlePath, provenancePath } = locateVerifier();
+  for (const path of [bundlePath, provenancePath]) {
+    let regular = false;
+    try {
+      regular = lstatSync(path).isFile();
+    } catch (error) {
+      if (error.code !== 'ENOENT') {throw error;}
+    }
+    if (!regular) {
+      throw new Error(
+        `this CLI's built evidence verifier is missing: ${path} is not a regular file ` +
+          `(it is produced by the package build)`,
+      );
+    }
+  }
+  return verifierDigests({
+    bundleBytes: readFileSync(bundlePath),
+    provenanceBytes: readFileSync(provenancePath),
+  });
+}

package/edition/catalogue-edition.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// catalogue-edition — write the catalogue of a RELEASE offering from its committed, sealed locks.
+//
+//   catalogue <id> --out <dir>
+//
+// Writes <dir>/catalogue.json (catalogue.mjs). `xema edition artifact` writes the
+// same file into the offering artifact; this verb is for inspecting it or
+// publishing it on its own.
+
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { writeCatalogue } from './catalogue.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromProcess,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { releaseCatalogue } from './release-catalogue.mjs';
+import { readCommittedEdition } from './release-edition-artifact.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
+}
+
+/** `{ id, out }` of `catalogue <distribution-id> --out <dir>`; anything else is the usage error. */
+export function parseCatalogueArgs(argv) {
+  const [command, id, flag, out, ...extra] = argv;
+  if (command !== 'catalogue' || id === undefined || flag !== '--out' || out === undefined || out.startsWith('--') || extra.length > 0) {
+    throw new Error('usage: catalogue <distribution-id> --out <dir>');
+  }
+  assertCanonicalDistributionId(id);
+  return { id, out };
+}
+
+async function run(argv) {
+  const { id, out } = parseCatalogueArgs(argv);
+  const dir = resolve(out);
+  mkdirSync(dir, { recursive: true });
+  console.log(writeCatalogue(dir, await releaseCatalogue(id, await readCommittedEdition(id))));
+}
+
+if (isEntryModule(import.meta.url)) {
+  run(process.argv.slice(2)).catch((error) => {
+    console.error(`[edition-catalogue] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/catalogue-fetch.mjs

@@ -0,0 +1,64 @@
+// catalogue-fetch — read the catalogue layer of an offering artifact, by digest.
+//
+// The reference is `oci://<registry>/<repository>@sha256:<digest>`: a tag is
+// refused, because a catalogue is pinned, not followed. The manifest and the
+// layer are fetched with the one OCI client (`oras.mjs`, the pinned oras), which verifies that
+// every body hashes to the digest it was asked for. Credentials are named by
+// environment variable (never inlined): `--catalogue-username` with
+// `--catalogue-token-env`, or neither for an anonymous read.
+
+import { Buffer } from 'node:buffer';
+
+import { CATALOGUE_FILE, CatalogueError, parseCatalogue } from './catalogue.mjs';
+import { EDITION_ARTIFACT_TYPE } from './edition-constants.mjs';
+import { OrasRegistry } from './oras.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+
+const REF = /^oci:\/\/([^@]+)@(sha256:[a-f0-9]{64})$/;
+const CATALOGUE_MAX_BYTES = 32 * 1024 * 1024;
+const TITLE = 'org.opencontainers.image.title';
+
+/** `{ authority, repository, digest }` of an `oci://<repository>@sha256:<digest>` reference; a tag is refused. */
+export function parseCatalogueRef(ref) {
+  const match = REF.exec(String(ref));
+  if (match === null) {
+    throw new CatalogueError(`--catalogue ${JSON.stringify(ref)} is not oci://<registry>/<repository>@sha256:<64 hex>: a catalogue is pinned by digest, never by tag`);
+  }
+  const { authority, repository } = splitImageRef(match[1]);
+  return { authority, repository, digest: match[2] };
+}
+
+/** The credential the client needs: named by env var, or anonymous. */
+export function catalogueCredential({ authority, username, tokenEnv, env = process.env }) {
+  if ((username === undefined) !== (tokenEnv === undefined)) {
+    throw new CatalogueError('--catalogue-username and --catalogue-token-env go together (or neither, for an anonymous read)');
+  }
+  if (tokenEnv === undefined) {return { authority, access: 'anonymous', basicAuth: null };}
+  const token = env[tokenEnv];
+  if (typeof token !== 'string' || token.length === 0) {
+    throw new CatalogueError(`--catalogue-token-env names ${tokenEnv}, which is unset or empty`);
+  }
+  return { authority, access: 'authenticated', basicAuth: Buffer.from(`${username}:${token}`, 'utf8').toString('base64') };
+}
+
+/** Fetch and strictly parse the catalogue of the artifact at `ref`. `client` is injectable for tests. */
+export async function fetchCatalogue({ ref, username, tokenEnv, env = process.env, client }) {
+  const { authority, repository, digest } = parseCatalogueRef(ref);
+  const registry = client ?? new OrasRegistry({ credential: catalogueCredential({ authority, username, tokenEnv, env }) });
+  const manifest = await registry.getManifestByDigest(repository, digest);
+  if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
+    throw new CatalogueError(`${ref} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
+  }
+  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === CATALOGUE_FILE);
+  if (layers.length !== 1) {
+    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${CATALOGUE_FILE}; an offering artifact carries exactly one`);
+  }
+  const bytes = await registry.getBlob(repository, layers[0].digest, CATALOGUE_MAX_BYTES);
+  let document;
+  try {
+    document = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new CatalogueError(`${ref}: ${CATALOGUE_FILE} is not JSON: ${error.message}`);
+  }
+  return { catalogue: parseCatalogue(document), digest };
+}

package/edition/catalogue.mjs

@@ -0,0 +1,135 @@
+// catalogue — what an offering's edition artifact offers to a customer edition.
+//
+// `catalogue.json` is one more titled layer of an offering's edition artifact
+// (edition-artifact.mjs): the availability, pins, image digests, chart-set and
+// declared ceiling of the offering, and NOTHING that can add a component. A
+// customer edition is resolved against it (resolve-customer-edition.mjs) by the
+// digest of the artifact that carries it.
+//
+// `channel` is provenance only: no reader branches on it.
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EDITION_OFFERING_LAYERS, EditionChannel } from './edition-constants.mjs';
+import { serializeJson } from './lib.mjs';
+
+export const CATALOGUE_FILE = EDITION_OFFERING_LAYERS.catalogue;
+export const CATALOGUE_SCHEMA = 'xema.edition-catalogue/v1';
+
+const TOP_KEYS = ['schema', 'offeringId', 'channel', 'biomes', 'sourceTreeIds', 'platformServices', 'images', 'chartSet', 'contractAuthority', 'ceiling'];
+const IMAGES_KEYS = ['sourceHashAlgorithm', 'subjects', 'platformServiceBindings', 'webBiomes'];
+const CEILING_KEYS = ['trustPolicy', 'trustCeiling'];
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const GIT_TREE_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+export class CatalogueError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CatalogueError';
+  }
+}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function exactKeys(value, keys, where) {
+  if (!isObject(value) || Object.keys(value).sort().join() !== [...keys].sort().join()) {
+    throw new CatalogueError(`${where} must be exactly {${keys.join(', ')}}`);
+  }
+}
+
+/** The strict parse of a catalogue: exact keys, closed vocabularies, every image row sealed. Returns it unchanged. */
+export function parseCatalogue(value) {
+  exactKeys(value, TOP_KEYS, CATALOGUE_FILE);
+  if (value.schema !== CATALOGUE_SCHEMA) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: schema is ${JSON.stringify(value.schema)}, expected ${JSON.stringify(CATALOGUE_SCHEMA)}`);
+  }
+  assertCanonicalDistributionId(value.offeringId);
+  if (!Object.values(EditionChannel).includes(value.channel)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: channel must be one of ${Object.values(EditionChannel).join(' | ')}`);
+  }
+  if (!Array.isArray(value.biomes) || value.biomes.some((row) => !isObject(row) || typeof row.id !== 'string')) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: biomes must be an array of biome-index rows`);
+  }
+  // `sourceTreeIds` is the vendor's git tree id of each biome at its pinned commit. A customer holds no
+  // checkout of the vendor source, so it takes these ON THIS CATALOGUE'S AUTHORITY (biome-content.mjs).
+  if (!isObject(value.sourceTreeIds)) {throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds must map each biome id to its git tree id`);}
+  const rowIds = value.biomes.map((row) => row.id).sort();
+  const treeIdKeys = Object.keys(value.sourceTreeIds).sort();
+  if (JSON.stringify(rowIds) !== JSON.stringify(treeIdKeys)) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds must name exactly the biomes of \`biomes\` (biomes: ${rowIds.join(',')}; tree ids: ${treeIdKeys.join(',')})`);
+  }
+  for (const [biomeId, treeId] of Object.entries(value.sourceTreeIds)) {
+    if (!GIT_TREE_ID.test(String(treeId))) {throw new CatalogueError(`${CATALOGUE_FILE}: sourceTreeIds.${biomeId} is not a git tree id (40 or 64 lowercase hex)`);}
+  }
+  if (!Array.isArray(value.platformServices) || value.platformServices.some((row) => !isObject(row) || typeof row.name !== 'string')) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: platformServices must be an array of platform-service-index rows`);
+  }
+  exactKeys(value.images, IMAGES_KEYS, `${CATALOGUE_FILE} images`);
+  for (const key of IMAGES_KEYS.slice(1)) {
+    if (!Array.isArray(value.images[key])) {throw new CatalogueError(`${CATALOGUE_FILE}: images.${key} must be an array`);}
+  }
+  const unsealed = value.images.subjects.filter((subject) => !DIGEST.test(String(subject?.imageDigest)));
+  if (unsealed.length > 0) {
+    throw new CatalogueError(`${CATALOGUE_FILE}: ${unsealed.length} image rows carry no imageDigest (first: ${unsealed[0]?.kind}:${unsealed[0]?.id}); a catalogue offers sealed images only`);
+  }
+  if (!isObject(value.chartSet)) {throw new CatalogueError(`${CATALOGUE_FILE}: chartSet must be the offering's chart-set lock`);}
+  if (!isObject(value.contractAuthority)) {throw new CatalogueError(`${CATALOGUE_FILE}: contractAuthority must be the runtime image source index's authority`);}
+  exactKeys(value.ceiling, CEILING_KEYS, `${CATALOGUE_FILE} ceiling`);
+  return value;
+}
+
+/**
+ * The catalogue of one resolved offering. Biome and platform-service rows are
+ * exactly those the offering's distribution lock ships (an offering that draws
+ * from a declared source is not a vendor offering and is refused).
+ */
+export function buildCatalogue({
+  offeringId,
+  channel,
+  distributionLock,
+  imageLock,
+  chartSetLock,
+  biomeIndex,
+  platformServiceIndex,
+  contractAuthority,
+  leaf,
+  sourceTreeIds,
+}) {
+  const sourced = distributionLock.biomes.filter((biome) => biome.source !== undefined);
+  if (sourced.length > 0) {
+    throw new CatalogueError(`offering "${offeringId}" draws ${sourced.map((b) => b.id).join(', ')} from a declared source; only a vendor offering publishes a catalogue`);
+  }
+  const shippedBiomes = new Set(distributionLock.biomes.map((biome) => biome.id));
+  const shippedServices = new Set(distributionLock.platformServices.map((service) => service.name));
+  const biomes = biomeIndex.filter((row) => shippedBiomes.has(row.id));
+  const missing = [...shippedBiomes].filter((id) => !biomes.some((row) => row.id === id));
+  if (missing.length > 0) {throw new CatalogueError(`offering "${offeringId}": the biome index has no row for ${missing.join(', ')}`);}
+  const platformServices = platformServiceIndex.services.filter((row) => shippedServices.has(row.name));
+  return parseCatalogue({
+    schema: CATALOGUE_SCHEMA,
+    offeringId,
+    channel,
+    biomes: [...biomes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+    sourceTreeIds,
+    platformServices: [...platformServices].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+    images: {
+      sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
+      subjects: imageLock.subjects,
+      platformServiceBindings: imageLock.platformServiceBindings,
+      webBiomes: imageLock.webBiomes,
+    },
+    chartSet: chartSetLock,
+    contractAuthority,
+    ceiling: { trustPolicy: leaf?.trustPolicy ?? null, trustCeiling: leaf?.trustCeiling ?? null },
+  });
+}
+
+/** Write `catalogue.json` into an artifact directory (deterministic serialization); returns its path. */
+export function writeCatalogue(outDir, catalogue) {
+  parseCatalogue(catalogue);
+  const path = join(outDir, CATALOGUE_FILE);
+  writeFileSync(path, serializeJson(catalogue));
+  return path;
+}

package/edition/chart-set-source-commit.mjs

@@ -0,0 +1,92 @@
+// `xema edition chart-set source-commit` - the commit each chart-set publisher
+// closed its LOCKED set at.
+//
+// The publisher stamps its index chart with `xema.dev/chart-set-source-sha`
+// next to `xema.dev/chart-set-charts`. This verb reads that stamp from the index
+// chart at the version the committed fleet `chart-set.lock.json` pins, and
+// prints one JSON document. It refuses, printing nothing, when the stamp is
+// absent or is not a 40-hex commit, or when the index's roster is not the one
+// the lock records for that publisher: the commit it would name would then be
+// the commit of a different set than the locked one.
+
+import { EditionChannel } from './edition-channel.mjs';
+import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import { serializeJson } from './lib.mjs';
+import {
+  CHART_SET_LOCK_FILE,
+  INDEX_ROSTER_ANNOTATION,
+  chartRegistryClient,
+  chartSetLockPath,
+  indexAnnotations,
+  parseIndexRoster,
+  readLock,
+} from './resolve-chart-set.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+}
+
+export const CHART_SET_SOURCE_SCHEMA = 'xema.edition-chart-set-source/v1';
+export const INDEX_SOURCE_ANNOTATION = 'xema.dev/chart-set-source-sha';
+
+/** Why the index's roster is not the lock's roster for the publisher, or null when they are the same set. */
+function rosterDifference(lockCharts, indexRoster) {
+  const names = [...new Set([...Object.keys(lockCharts), ...Object.keys(indexRoster)])].sort();
+  for (const name of names) {
+    const locked = lockCharts[name];
+    const indexed = indexRoster[name];
+    if (locked === undefined) {return `the index carries ${name}, which the lock does not`;}
+    if (indexed === undefined) {return `the lock records ${name}, which the index does not carry`;}
+    if (locked.version !== indexed.version) {
+      return `${name} is ${indexed.version} in the index and ${locked.version} in the lock`;
+    }
+    if (indexed.digest !== undefined && indexed.digest !== locked.digest) {
+      return `${name}:${locked.version} is ${indexed.digest} in the index and ${locked.digest} in the lock`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The source-commit document for every publisher of `lock`, read through
+ * `client` (the chart registry client). Throws on the first refusal.
+ */
+export async function chartSetSourceCommits({ client, lock }) {
+  const publishers = [];
+  for (const { index, repo, version, charts } of lock.publishers) {
+    const label = `${index}@${version}`;
+    const annotations = await indexAnnotations(client, index, version);
+    const difference = rosterDifference(charts, parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], label));
+    if (difference !== null) {
+      throw new Error(`${label}: the index roster is not the set ${CHART_SET_LOCK_FILE} locks (${difference}), so its source commit is not the locked set's`);
+    }
+    const sourceCommit = annotations[INDEX_SOURCE_ANNOTATION];
+    if (typeof sourceCommit !== 'string' || !COMMIT_PATTERN.test(sourceCommit)) {
+      throw new Error(`${label} carries no ${INDEX_SOURCE_ANNOTATION} that is a 40 lowercase hex commit (got ${JSON.stringify(sourceCommit)})`);
+    }
+    publishers.push({ index, repo, version, sourceCommit });
+  }
+  return { schema: CHART_SET_SOURCE_SCHEMA, publishers };
+}
+
+async function main(argv) {
+  if (argv.length > 0) {
+    throw new Error(`unexpected argument "${argv[0]}"; usage: xema edition chart-set source-commit --data-root <dir> --kernel <dir>`);
+  }
+  const lock = readLock();
+  if (lock === null) {
+    throw new Error(`${chartSetLockPath()} is missing or is not JSON: run 'xema edition chart-set resolve' first`);
+  }
+  assertRosteredChartSetLock(lock, CHART_SET_LOCK_FILE, EditionChannel.Release);
+  const document = await chartSetSourceCommits({ client: chartRegistryClient(), lock });
+  process.stdout.write(serializeJson(document));
+}
+
+if (isEntryModule(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`chart-set source-commit: ${error.message}\n`);
+    process.exit(1);
+  });
+}