@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/authorization-base.mjs

@@ -0,0 +1,357 @@
+// 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 { RefusalError } from './collected-refusals.mjs';
+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';
+
+/**
+ * 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 RefusalError(`${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 RefusalError(
+      `${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 RefusalError(`${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 RefusalError(`edition biome "${id}" is missing from the biome index`);}
+    if (!entry.authorizationModule) {continue;}
+    if (kernel === null) {
+      throw new RefusalError(
+        `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;
+  let distribution;
+  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')}`);
+    distribution = await import(`file://${join(kernelPackageDir, 'dist', 'distribution', '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'],
+    [distribution, 'parseAuthorizationLockReadView'],
+  ]) {
+    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,
+    parseAuthorizationLockReadView: distribution.parseAuthorizationLockReadView,
+    authorizationLockSchemaVersion: distribution.AUTHORIZATION_LOCK_SCHEMA_VERSION,
+    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, { contentHash: m.contentHash }]),
+    ),
+  };
+}
+
+/** Compose an edition's base; a refusal names the edition and every violation. */
+export function composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, biomeOrigins }) {
+  try {
+    return kernel.composeAuthorizationBase({
+      modules: inputs,
+      biomeOrigins,
+      currentPlatformGeneration: kernel.currentPlatformGeneration,
+      ...(adopted ? { adopted } : {}),
+    });
+  } catch (err) {
+    if (Array.isArray(err?.violations)) {
+      throw new RefusalError(`${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. It is read through the kernel's `parseAuthorizationLockReadView` before it is returned. */
+export function authorizationLockOf(distributionId, kernel, composed) {
+  const lock = {
+    schemaVersion: kernel.authorizationLockSchemaVersion,
+    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,
+      contentHash: m.contentHash,
+      signedBiomeVersion: m.signedBiomeVersion,
+    })),
+    parentImplementers: [...composed.parentImplementers],
+    model: composed.model,
+  };
+  kernel.parseAuthorizationLockReadView(lock);
+  return lock;
+}
+
+/** 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 RefusalError('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 RefusalError(
+            `${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, biomeOrigins, runTests }) {
+  const composed = composeEditionAuthorizationBase({ distributionId, inputs, kernel, adopted, biomeOrigins });
+  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 is refused exactly as the sealer would refuse it; a
+ * module's identity is its content hash, so changed content is a new identity
+ * and neither a reused version nor a downgrade exists) 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, biomeOrigins, serialize }) {
+  if (kernel === null) {
+    return committed === null ? AuthorizationLockCheck.GREEN : AuthorizationLockCheck.NOT_SEALABLE;
+  }
+  if (committed === null) {return AuthorizationLockCheck.MISSING;}
+  const composed = composeEditionAuthorizationBase({
+    distributionId,
+    inputs,
+    kernel,
+    biomeOrigins,
+    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, biomeOrigins, 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,
+    biomeOrigins,
+    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;
+}