@xemahq/xema 0.26.0 → 0.27.0

package/edition/authorization-base.mjs

@@ -0,0 +1,347 @@
+// authorization-base — the edition's composed AUTHORIZATION BASE (plan
+// `biome-declared-authorization.md` §2.3 steps 3–7, §11 step 4).
+//
+// An edition's base is the platform modules the KERNEL ships (`xema_core`,
+// `xema_capability`, `xema_sharing`) plus every authorization module the
+// edition's biomes ship. This file:
+//
+//   1. reads each biome's module FROM ITS PINNED SOURCE into the biome index
+//      (`readBiomeAuthorizationModuleAt`), so the sealer composes the exact
+//      bytes the biome bundle signs;
+//   2. composes with the KERNEL composer — `composeAuthorizationBase` from
+//      `@xemahq/contracts/authorization-module/server`, loaded from the
+//      edition's pinned, built kernel — never a local re-implementation;
+//   3. runs every composed `.fga.yaml` (platform and biome) with the standard
+//      `fga model test`, from the composition root the composer describes —
+//      one failure refuses the edition;
+//   4. seals `authorization.lock.json` beside `distribution.lock.json`: the
+//      `modelHash` authorization-api adopts, the model, the platform
+//      generation it was composed for, and the module provenance.
+//
+// The platform generation is the pinned kernel's own declared
+// `PLATFORM_GENERATION` integer (kernel `platform-generation` subpath), read
+// from the built kernel and never written down here.
+//
+// A pinned kernel that does not ship the composer has no authorization plane
+// to seal: the resolver retires any lock, and dist-check refuses a committed
+// lock that kernel cannot reproduce. Once the pin carries the composer, every
+// edition seals — the platform modules always compose.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+
+/** Where a biome keeps its module, relative to its manifest directory (plan §2.1). */
+export const AUTHORIZATION_MODULE_DIRECTORY = 'authorization';
+export const AUTHORIZATION_ENVELOPE_FILENAME = 'envelope.json';
+export const AUTHORIZATION_LOCK_FILENAME = 'authorization.lock.json';
+export const AUTHORIZATION_LOCK_SCHEMA_VERSION = 1;
+
+/**
+ * The OpenFGA CLI the sealer tests with, EXACTLY. 0.8.1 embeds
+ * openfga/openfga v1.21.0 (github) (its go.mod), the server version every
+ * installation runs (xema-infra-services chart 0.3.15) — so a sealed test ran
+ * against the same engine that will answer in production.
+ */
+export const FGA_CLI_VERSION = '0.8.1';
+/** The environment variable naming the `fga` binary the sealer runs. */
+export const FGA_CLI_ENV = 'XEMA_FGA_CLI';
+
+/**
+ * Read a biome's authorization module at a commit, or `null` when the biome
+ * ships none. The shape is the kernel's
+ * `AuthorizationModuleContributionManifest`: `{ envelope, moduleFiles,
+ * testFile }` — the envelope plus the CONTENTS of every file it names.
+ *
+ * `readText(repoRelativePath)` returns a file's text at the pinned commit, or
+ * `null` when it does not exist there. A present envelope naming an absent
+ * file is a refusal, never a partial module. The envelope itself is validated
+ * by the kernel composer, not here.
+ */
+export function readBiomeAuthorizationModuleAt(manifestDirectory, readText, rel) {
+  const base = `${manifestDirectory}/${AUTHORIZATION_MODULE_DIRECTORY}`;
+  const envelopeText = readText(`${base}/${AUTHORIZATION_ENVELOPE_FILENAME}`);
+  if (envelopeText === null) {return null;}
+  let envelope;
+  try {
+    envelope = JSON.parse(envelopeText);
+  } catch (err) {
+    throw new Error(`${rel}: ${base}/${AUTHORIZATION_ENVELOPE_FILENAME} is not JSON: ${err.message}`);
+  }
+  const files = Array.isArray(envelope?.files) ? envelope.files : null;
+  if (!files || files.length === 0 || typeof envelope.tests !== 'string') {
+    throw new Error(
+      `${rel}: ${base}/${AUTHORIZATION_ENVELOPE_FILENAME} must name its module files ("files") ` +
+        'and its REQUIRED OpenFGA test file ("tests").',
+    );
+  }
+  const read = (name) => {
+    const contents = readText(`${base}/${name}`);
+    if (contents === null) {
+      throw new Error(`${rel}: the authorization envelope names ${base}/${name}, which does not exist at the pinned commit.`);
+    }
+    return { name, contents };
+  };
+  return {
+    envelope,
+    moduleFiles: [...files].sort().map(read),
+    testFile: read(envelope.tests),
+  };
+}
+
+/**
+ * The composer's `AuthorizationModuleInput[]` for an edition: one per selected
+ * biome that ships a module, sorted by id. Built with the KERNEL's own two
+ * helpers, never by hand:
+ *
+ *   manifest = stampAuthorizationModuleContribution(source, signedBiome)
+ *   input    = authorizationModuleInputFromContribution({ owner, manifest })
+ *
+ * The sealer reads modules from the biome index rather than through
+ * contribution-sync, so it is the sealer that stamps: `signedBiome` (tier,
+ * declared biome dependencies, service names) was derived from the pinned
+ * `xema-biome.json` when the index was built, and the owner is the lock's
+ * signed id and version. A pinned kernel without the composer cannot stamp,
+ * so an edition carrying a module under such a pin is refused.
+ */
+export function editionAuthorizationModuleInputs(lockBiomes, indexById, kernel) {
+  const inputs = [];
+  for (const { id, version } of lockBiomes) {
+    const entry = indexById.get(id);
+    if (!entry) {throw new Error(`edition biome "${id}" is missing from the biome index`);}
+    if (!entry.authorizationModule) {continue;}
+    if (kernel === null) {
+      throw new Error(
+        `edition biome "${id}" ships an authorization module, but the pinned kernel ships no composer to stamp or compose it.`,
+      );
+    }
+    const { source, signedBiome } = entry.authorizationModule;
+    const manifest = kernel.stampAuthorizationModuleContribution(source, signedBiome);
+    inputs.push(kernel.authorizationModuleInputFromContribution({ owner: { id, version }, manifest }));
+  }
+  return inputs.sort((x, y) => (x.signedBiomeId < y.signedBiomeId ? -1 : x.signedBiomeId > y.signedBiomeId ? 1 : 0));
+}
+
+/**
+ * The pinned kernel's authorization composer, or `null` when that kernel does
+ * not ship one (its built `authorization-module/server` subpath is absent).
+ * An ABSENT subpath is a fact about the pin; a PRESENT one that fails to load
+ * or lacks the export is an error.
+ *
+ * The platform generation is the kernel's declared `PLATFORM_GENERATION`
+ * integer, validated by the kernel's own `PlatformGenerationSchema`. It is NOT
+ * the package version: an additive kernel release does not move it.
+ */
+export async function loadKernelAuthorizationComposer({ kernelPackageDir }) {
+  assertKernelEditionProtocol(kernelPackageDir);
+  const serverDist = join(kernelPackageDir, 'dist', 'authorization-module', 'server', 'index.js');
+  if (!existsSync(serverDist)) {return null;}
+  let server;
+  let contribution;
+  let generation;
+  try {
+    server = await import(`file://${serverDist}`);
+    contribution = await import(`file://${join(kernelPackageDir, 'dist', 'authorization-module', 'index.js')}`);
+    generation = await import(`file://${join(kernelPackageDir, 'dist', 'platform-generation', 'index.js')}`);
+  } catch (err) {
+    throw new Error(`Cannot load the pinned kernel's authorization composer from ${serverDist}: ${err.message}`);
+  }
+  for (const [mod, name] of [
+    [server, 'composeAuthorizationBase'],
+    [server, 'authorizationModuleInputFromContribution'],
+    [contribution, 'stampAuthorizationModuleContribution'],
+  ]) {
+    if (typeof mod[name] !== 'function') {
+      throw new Error(`the pinned kernel's authorization-module subpaths do not export ${name}.`);
+    }
+  }
+  const parsed = generation.PlatformGenerationSchema?.safeParse?.(generation.PLATFORM_GENERATION);
+  if (!parsed?.success) {
+    throw new Error(
+      "the pinned kernel's platform-generation subpath does not export a valid PLATFORM_GENERATION " +
+        `(a positive integer validated by PlatformGenerationSchema); got ${JSON.stringify(generation.PLATFORM_GENERATION)}.`,
+    );
+  }
+  return {
+    composeAuthorizationBase: server.composeAuthorizationBase,
+    authorizationModuleInputFromContribution: server.authorizationModuleInputFromContribution,
+    stampAuthorizationModuleContribution: contribution.stampAuthorizationModuleContribution,
+    currentPlatformGeneration: parsed.data,
+    kernelPackageDir,
+  };
+}
+
+/** The `adopted` input the composer diffs against: the committed lock, if any. */
+export function adoptedFromLock(lock) {
+  if (!lock) {return undefined;}
+  return {
+    model: lock.model,
+    modules: Object.fromEntries(
+      lock.modules.map((m) => [m.namespace, { moduleVersion: m.moduleVersion, contentHash: m.contentHash }]),
+    ),
+  };
+}
+
+/** Compose an edition's base; a refusal names the edition and every violation. */
+export function composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted }) {
+  try {
+    return kernel.composeAuthorizationBase({
+      modules: inputs,
+      currentPlatformGeneration: kernel.currentPlatformGeneration,
+      ...(adopted ? { adopted } : {}),
+    });
+  } catch (err) {
+    if (Array.isArray(err?.violations)) {
+      throw new Error(`${distributionId}: the authorization base was REFUSED by the kernel composer.\n${err.message}`);
+    }
+    throw err;
+  }
+}
+
+/** The lock body for a composed base. Deterministic: no timestamp. */
+export function authorizationLockOf(distributionId, kernel, composed) {
+  return {
+    schemaVersion: AUTHORIZATION_LOCK_SCHEMA_VERSION,
+    distributionId,
+    platformGeneration: kernel.currentPlatformGeneration,
+    modelHash: composed.modelHash,
+    modelBytes: composed.modelBytes,
+    testedWith: `openfga/cli v${FGA_CLI_VERSION}`,
+    modules: composed.modules.map((m) => ({
+      namespace: m.namespace,
+      moduleVersion: m.moduleVersion,
+      contentHash: m.contentHash,
+      signedBiomeVersion: m.signedBiomeVersion,
+    })),
+    parentImplementers: [...composed.parentImplementers],
+    model: composed.model,
+  };
+}
+
+/** Resolve and verify the pinned `fga` CLI. */
+export function resolveFgaCli(env = process.env) {
+  const bin = env[FGA_CLI_ENV];
+  if (!bin) {
+    throw new Error(
+      `sealing an authorization base runs \`fga model test\`, and ${FGA_CLI_ENV} is unset. ` +
+        `Point it at the openfga/cli v${FGA_CLI_VERSION} binary.`,
+    );
+  }
+  const out = execFileSync(bin, ['version'], { encoding: 'utf8' });
+  const match = /v`?(\d+\.\d+\.\d+)`?/.exec(out);
+  if (!match || match[1] !== FGA_CLI_VERSION) {
+    throw new Error(`${FGA_CLI_ENV}=${bin} reports "${out.trim()}"; the sealer requires exactly v${FGA_CLI_VERSION}.`);
+  }
+  return bin;
+}
+
+/**
+ * Run every composed `.fga.yaml` with the real CLI, from the composition root:
+ * the composer's `files` (the filled templates, the biome files and `fga.mod`)
+ * and `testFiles` are written at their composed names, and each test runs
+ * with that root as its working directory.
+ */
+export function fgaComposedModelTestRunner(bin) {
+  return (composed) => {
+    const root = mkdtempSync(join(tmpdir(), 'xema-authz-seal-'));
+    try {
+      for (const f of [...composed.files, ...composed.testFiles]) {
+        mkdirSync(dirname(join(root, f.name)), { recursive: true });
+        writeFileSync(join(root, f.name), f.contents);
+      }
+      if (composed.testFiles.length === 0) {
+        throw new Error('the composed base carries no test file — every module ships one, the platform modules included.');
+      }
+      for (const t of composed.testFiles) {
+        try {
+          execFileSync(bin, ['model', 'test', '--tests', t.name], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        } catch (err) {
+          throw new Error(
+            `${t.owner}: ${t.name} FAILED against the composed edition base:\n` +
+              `${String(err.stdout ?? '').trim()}\n${String(err.stderr ?? '').trim()}`,
+          );
+        }
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  };
+}
+
+/** Compose, test, describe. `runTests` is the `fga model test` runner. */
+export function sealEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, runTests }) {
+  const composed = composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted });
+  runTests(composed);
+  return authorizationLockOf(distributionId, kernel, composed);
+}
+
+/** Outcome of the committed-vs-recomposed authorization lock comparison. */
+export const AuthorizationLockCheck = Object.freeze({
+  GREEN: 'green',
+  MISSING: 'missing',
+  STALE: 'stale',
+  NOT_SEALABLE: 'not-sealable',
+});
+
+/**
+ * Is the committed `authorization.lock.json` what this edition composes NOW?
+ * Recomposes with the committed lock as `adopted` (so an undeclared
+ * incompatible change, a reused module version or a downgrade is refused
+ * exactly as the sealer would refuse it) and compares the whole lock. The
+ * tests are not re-run: an equal `modelHash` is the model the sealer tested.
+ */
+export function checkAuthorizationLockCurrent({ distributionId, committed, inputs, kernel, serialize }) {
+  if (kernel === null) {
+    return committed === null ? AuthorizationLockCheck.GREEN : AuthorizationLockCheck.NOT_SEALABLE;
+  }
+  if (committed === null) {return AuthorizationLockCheck.MISSING;}
+  const composed = composeEditionAuthorizationBase({
+    distributionId,
+    inputs,
+    kernel,
+    adopted: adoptedFromLock(committed),
+  });
+  return serialize(authorizationLockOf(distributionId, kernel, composed)) === serialize(committed)
+    ? AuthorizationLockCheck.GREEN
+    : AuthorizationLockCheck.STALE;
+}
+
+/**
+ * dist-check's authorization-currency verdict for ONE edition: the committed
+ * `authorization.lock.json` against a fresh composition over the edition's
+ * lock biomes, looked up in the index that lock was RESOLVED FROM (platform
+ * entries plus the edition's source-walked ones). Returns an
+ * `AuthorizationLockCheck` member; throws on a refusal.
+ */
+export function checkEditionAuthorizationLock({ distributionId, editionDir, lockBiomes, index, kernel, serialize }) {
+  if (!Array.isArray(index)) {
+    throw new Error(`${distributionId}: the authorization check needs the index the lock was resolved from.`);
+  }
+  return checkAuthorizationLockCurrent({
+    distributionId,
+    committed: readAuthorizationLock(editionDir),
+    inputs: editionAuthorizationModuleInputs(lockBiomes, new Map(index.map((e) => [e.id, e])), kernel),
+    kernel,
+    serialize,
+  });
+}
+
+/** Read an edition's committed authorization lock, or `null`. */
+export function readAuthorizationLock(editionDir) {
+  const path = join(editionDir, AUTHORIZATION_LOCK_FILENAME);
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+/** Write (or retire) an edition's authorization lock. */
+export function writeAuthorizationLock(editionDir, lock, serialize) {
+  const path = join(editionDir, AUTHORIZATION_LOCK_FILENAME);
+  if (lock === null) {
+    if (existsSync(path)) {rmSync(path);}
+    return null;
+  }
+  writeFileSync(path, serialize(lock));
+  return path;
+}

package/edition/biome-content.mjs

@@ -0,0 +1,268 @@
+// biome-content — the content address of every biome a distribution lock ships.
+//
+// A sealed (v5) lock carries, per biome, `biomeContentHash`: the kernel's
+// `computeBiomeContentHash` over THREE facts the lock itself cannot vouch for:
+//
+//   * the biome's source manifest hash, recomputed from the manifest AT the
+//     pinned commit (`computeBiomeSourceManifestHash`);
+//   * the git tree object id of the biome directory at that commit
+//     (`git rev-parse <commit>:<path>`);
+//   * the sorted image subject digests of the images the biome owns, from the
+//     SEALED images lock.
+//
+// The kernel cannot recompute any of them ("sealed" is only a field), so the
+// producer of the seal AND every verifier recompute from the sources and REFUSE
+// a mismatch, naming the biome. Nothing here assembles a v5 lock: the unsealed
+// document goes to the kernel's `sealDistributionLock` together with the hashes
+// computed below.
+
+import { execFileSync } from 'node:child_process';
+import { relative, sep } from 'node:path';
+
+import { readGitJsonAtCommit } from './lib.mjs';
+
+/** A biome whose recomputed content hash is not the lock's, or whose inputs cannot be recomputed. */
+export class BiomeContentHashError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'BiomeContentHashError';
+  }
+}
+
+/**
+ * The commit a biome's content is pinned at. A biome that ships images (or a web
+ * bundle) is pinned where its images lock row is; a declared source at its
+ * locked commit; a content-only first-party biome at the vendored-source pin
+ * (`vendoredCommit(repo)`), the axis its manifest hash was read on.
+ */
+function pinnedCommit({ biome, imageLock, ownerKinds, vendoredCommit }) {
+  if (biome.source !== undefined) {return biome.source.commit;}
+  const owned = imageLock.subjects.filter((subject) =>
+    subject.owners.some((owner) => owner.kind === ownerKinds.Biome && owner.biomeId === biome.id),
+  );
+  const commits = new Set(owned.map((subject) => subject.sourceCommit));
+  if (commits.size > 1) {
+    throw new BiomeContentHashError(`biome "${biome.id}": its images pin ${commits.size} different commits`);
+  }
+  if (commits.size === 1) {return [...commits][0];}
+  const web = imageLock.webBiomes.find((row) => row.biomeId === biome.id);
+  if (web !== undefined) {return web.sourceCommit;}
+  return vendoredCommit(biome.repo);
+}
+
+function treeId({ parseGitTreeId, repoDirectory, commit, repoRelativePath }) {
+  const object = repoRelativePath === '.' ? `${commit}^{tree}` : `${commit}:${repoRelativePath}`;
+  const out = execFileSync('git', ['-C', repoDirectory, 'rev-parse', '--verify', object], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return parseGitTreeId(out.trim());
+}
+
+/** The sorted `sha256:` subject digests of the images `biome` owns; an unsealed row is refused. */
+function imageSubjectDigests({ biome, imageLock, ownerKinds, parseOciDigest }) {
+  return imageLock.subjects
+    .filter((subject) => subject.owners.some((owner) => owner.kind === ownerKinds.Biome && owner.biomeId === biome.id))
+    .map((subject) => {
+      if (subject.imageDigest === undefined) {
+        throw new BiomeContentHashError(
+          `biome "${biome.id}": image ${subject.kind}:${subject.id} is not sealed (no imageDigest); seal the images lock first`,
+        );
+      }
+      return parseOciDigest(subject.imageDigest);
+    });
+}
+
+function ownedSubjects(imageLock, ownerKinds, biomeId) {
+  return imageLock.subjects.filter((subject) =>
+    subject.owners.some((owner) => owner.kind === ownerKinds.Biome && owner.biomeId === biomeId),
+  );
+}
+
+/** The biome's `xema-biome.json` AT the commit its content is pinned at, read from the source checkout `locate` names. */
+function readPinnedManifest({ biome, commit, locate }) {
+  const { dir: repoDirectory, base } = locate(biome.repo);
+  const repoRelativePath = relative(repoDirectory, `${base}${sep}${biome.path}`).split(sep).join('/') || '.';
+  const manifestPath = repoRelativePath === '.' ? 'xema-biome.json' : `${repoRelativePath}/xema-biome.json`;
+  return { repoDirectory, repoRelativePath, manifestPath, manifest: readGitJsonAtCommit(repoDirectory, manifestPath, commit) };
+}
+
+/**
+ * The manifest at the pinned commit, held to the lock: its hash, by the kernel's
+ * `computeBiomeSourceManifestHash`, is the lock's `sourceManifestHash`, or the biome is
+ * refused. The ONE comparison, for the seal, the verify step and `biome-manifests`.
+ */
+async function readLockedManifest({ schemas, biome, commit, locate }) {
+  const pinned = readPinnedManifest({ biome, commit, locate });
+  const sourceManifestHash = await schemas.computeBiomeSourceManifestHash(pinned.manifest);
+  if (sourceManifestHash !== biome.sourceManifestHash) {
+    throw new BiomeContentHashError(
+      `biome "${biome.id}": the manifest at ${biome.repo}@${commit}:${pinned.manifestPath} hashes to ${sourceManifestHash}, ` +
+        `not the lock's sourceManifestHash ${biome.sourceManifestHash}`,
+    );
+  }
+  return { ...pinned, sourceManifestHash };
+}
+
+/**
+ * The pinned `xema-biome.json` of every biome of a lock, read exactly as the seal
+ * and the verify step read it, sorted by biome id: `[{ id, repo, sourceCommit, manifest }]`.
+ * A manifest that cannot be read at its pinned commit, or that is not the manifest
+ * the lock names (`sourceManifestHash`), is refused, naming the biome.
+ */
+export async function pinnedBiomeManifests({ schemas, lock, imageLock, locate, vendoredCommit }) {
+  const ownerKinds = schemas.RuntimeImageOwnerKind;
+  const manifests = [];
+  for (const biome of [...lock.biomes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+    const sourceCommit = pinnedCommit({ biome, imageLock, ownerKinds, vendoredCommit });
+    let manifest;
+    try {
+      ({ manifest } = await readLockedManifest({ schemas, biome, commit: sourceCommit, locate }));
+    } catch (error) {
+      if (error instanceof BiomeContentHashError) {throw error;}
+      throw new BiomeContentHashError(`biome "${biome.id}": its manifest at ${biome.repo}@${sourceCommit} cannot be read: ${error.message}`);
+    }
+    manifests.push({ id: biome.id, repo: biome.repo, sourceCommit, manifest });
+  }
+  return manifests;
+}
+
+/** The three facts of a biome recomputed from a checkout of its source at the pinned commit. */
+async function sourceFacts({ schemas, biome, imageLock, locate, vendoredCommit }) {
+  const ownerKinds = schemas.RuntimeImageOwnerKind;
+  const commit = pinnedCommit({ biome, imageLock, ownerKinds, vendoredCommit });
+  const { repoDirectory, repoRelativePath, sourceManifestHash } = await readLockedManifest({ schemas, biome, commit, locate });
+  return {
+    sourceManifestHash,
+    sourceTreeId: treeId({ parseGitTreeId: schemas.parseGitTreeId, repoDirectory, commit, repoRelativePath }),
+    imageSubjectDigests: imageSubjectDigests({ biome, imageLock, ownerKinds, parseOciDigest: schemas.parseOciDigest }),
+  };
+}
+
+const CATALOGUE_AUTHORITY_NOTE =
+  "the vendor biome's source tree id is an INPUT taken on the catalogue's authority; it is not re-derived " +
+  'from a checkout (the customer has none), so this is not a verification of the vendor source';
+
+/**
+ * The three facts of a VENDOR biome in a customer edition. The customer holds no
+ * checkout of the vendor source, so, on the catalogue's authority (and ONLY
+ * there): the tree id is the catalogue's `sourceTreeIds[biome]`, and the
+ * manifest hash is the catalogue row's. Everything the customer CAN check is
+ * checked: the lock's manifest hash equals the row's, and the image digests the
+ * customer's images lock carries for the biome equal the catalogue's. A biome
+ * the catalogue does not carry, or carries without a tree id, is refused.
+ */
+async function catalogueFacts({ schemas, biome, imageLock, catalogue }) {
+  const ownerKinds = schemas.RuntimeImageOwnerKind;
+  const row = catalogue.biomes.find((candidate) => candidate.id === biome.id);
+  if (row === undefined) {
+    throw new BiomeContentHashError(`vendor biome "${biome.id}" is absent from catalogue "${catalogue.offeringId}"; ${CATALOGUE_AUTHORITY_NOTE}`);
+  }
+  const treeIdText = catalogue.sourceTreeIds?.[biome.id];
+  if (treeIdText === undefined) {
+    throw new BiomeContentHashError(`catalogue "${catalogue.offeringId}" carries no source tree id for vendor biome "${biome.id}"; ${CATALOGUE_AUTHORITY_NOTE}`);
+  }
+  if (row.sourceManifestHash !== biome.sourceManifestHash) {
+    throw new BiomeContentHashError(
+      `vendor biome "${biome.id}": the lock's sourceManifestHash ${biome.sourceManifestHash} is not the catalogue row's ${row.sourceManifestHash}`,
+    );
+  }
+  const own = imageSubjectDigests({ biome, imageLock, ownerKinds, parseOciDigest: schemas.parseOciDigest });
+  const offered = ownedSubjects({ subjects: catalogue.images.subjects }, ownerKinds, biome.id)
+    .map((subject) => schemas.parseOciDigest(subject.imageDigest));
+  if (JSON.stringify([...own].sort()) !== JSON.stringify([...offered].sort())) {
+    throw new BiomeContentHashError(
+      `vendor biome "${biome.id}": its image digests in the images lock differ from the catalogue's (${[...own].sort().join(',')} vs ${[...offered].sort().join(',')})`,
+    );
+  }
+  return {
+    sourceManifestHash: schemas.parseBiomeSourceManifestHash(row.sourceManifestHash),
+    sourceTreeId: schemas.parseGitTreeId(treeIdText),
+    imageSubjectDigests: own,
+  };
+}
+
+/**
+ * Customer mode: the lock must say which catalogue produced its hashes, and it must be
+ * the catalogue supplied. A lock without `catalogueDigest`, or with another one, was not
+ * resolved against this catalogue, so its hashes cannot be checked on this catalogue's authority.
+ */
+function assertLockNamesCatalogue({ lock, catalogue, catalogueDigest }) {
+  if (catalogueDigest === undefined) {
+    throw new BiomeContentHashError(`customer mode needs the digest of catalogue "${catalogue.offeringId}"`);
+  }
+  if (lock.catalogueDigest === undefined) {
+    throw new BiomeContentHashError(
+      `distribution "${lock.distributionId}": the lock carries no catalogueDigest, so it was not resolved against a catalogue; supplied catalogue ${catalogueDigest}`,
+    );
+  }
+  if (lock.catalogueDigest !== catalogueDigest) {
+    throw new BiomeContentHashError(
+      `distribution "${lock.distributionId}": the lock was resolved against catalogue ${lock.catalogueDigest}, not the supplied ${catalogueDigest}`,
+    );
+  }
+}
+
+/**
+ * Recompute every biome's `biomeContentHash`.
+ *
+ * @param {object} request
+ * @param {object} request.schemas the kernel distribution schemas (`loadKernelDistributionSchemas`)
+ * @param {object} request.lock the unsealed or sealed distribution lock
+ * @param {object} request.imageLock the SEALED images lock
+ * @param {(repo: string) => {dir: string, base: string}} request.locate repo handle -> checkout
+ * @param {(repo: string) => string} request.vendoredCommit the vendored-source pin of a first-party repo
+ * @param {object} [request.catalogue] customer mode: the digest-pinned catalogue vendor biomes are taken from
+ * @param {string} [request.catalogueDigest] customer mode: the digest of that catalogue; the lock must carry the same one
+ * @returns {Promise<Map<string, string>>} biome id -> BiomeContentHash
+ */
+export async function computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest }) {
+  if (catalogue !== undefined) {assertLockNamesCatalogue({ lock, catalogue, catalogueDigest });}
+  const hashes = new Map();
+  for (const biome of lock.biomes) {
+    const facts =
+      catalogue !== undefined && biome.source === undefined
+        ? await catalogueFacts({ schemas, biome, imageLock, catalogue })
+        : await sourceFacts({ schemas, biome, imageLock, locate, vendoredCommit });
+    hashes.set(biome.id, await schemas.computeBiomeContentHash(facts));
+  }
+  return hashes;
+}
+
+/**
+ * The git tree id of every biome of a VENDOR offering at its pinned commit, as
+ * the catalogue publishes them: `{ [biomeId]: GitTreeId }`, sorted by id.
+ * THIS is the writer's source of the catalogue's `sourceTreeIds` (callers:
+ * release-catalogue.mjs `releaseCatalogue`, develop-edition-resolve.mjs).
+ */
+export async function biomeSourceTreeIds({ schemas, lock, imageLock, locate, vendoredCommit }) {
+  const ids = {};
+  for (const biome of [...lock.biomes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+    ids[biome.id] = (await sourceFacts({ schemas, biome, imageLock, locate, vendoredCommit })).sourceTreeId;
+  }
+  return ids;
+}
+
+/** Seal: the unsealed lock + the recomputed hashes -> the kernel's `sealDistributionLock`. */
+export async function sealLock({ schemas, unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest }) {
+  const hashes = await computeBiomeContentHashes({ schemas, lock: unsealed, imageLock, locate, vendoredCommit, catalogue, catalogueDigest });
+  return schemas.sealDistributionLock(unsealed, hashes);
+}
+
+/**
+ * Verify: recompute every biome's hash and REFUSE a mismatch, naming the biome.
+ * The lock's own field is never trusted; a missing or extra biome is a mismatch.
+ */
+export async function verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest }) {
+  const expected = await computeBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest });
+  const mismatched = lock.biomes
+    .filter((biome) => biome.biomeContentHash !== expected.get(biome.id))
+    .map((biome) => `${biome.id} (lock ${String(biome.biomeContentHash)}, recomputed ${expected.get(biome.id)})`);
+  if (mismatched.length > 0) {
+    throw new BiomeContentHashError(
+      `distribution "${lock.distributionId}": biomeContentHash does not match its inputs for ${mismatched.join('; ')}` +
+        (catalogue === undefined ? '' : `; ${CATALOGUE_AUTHORITY_NOTE}`),
+    );
+  }
+  return expected;
+}