@bongos/core 1.18.0 → 1.18.18

package/tests/governance_session_scope.mjs

@@ -0,0 +1,434 @@
+// tests/governance_session_scope.mjs — session-scopes as a first-class axis
+// (BV1.R99, ADR 0151 §3; the model behind ADR 0053). DB-free.
+//
+// A session-scope is capability attached to the TOKEN, not to the builder: a
+// dev-box session is baked onto a machine OUTSIDE the ADR 0016 trust boundary
+// (#919/SR#2), so it must stay limited even when its builder is an Archon.
+//
+// THE PROPERTY UNDER TEST IS "A SCOPE CAN ONLY EVER NARROW", and it fails in two
+// opposite directions, so both are proven separately:
+//   • UNION INSTEAD OF INTERSECTION ⇒ a box token ESCALATES. Proven by C1/C2 (the
+//     scope names a key the roles do not confer, and the answer must still be
+//     empty) and structurally by B4 (for every input, the narrowed set is a SUBSET
+//     of the unnarrowed role answer — a union cannot satisfy a subset assertion).
+//   • NO DENY-BY-DEFAULT ⇒ an unlisted permission LEAKS. Proven by D1/D2 (a builder
+//     holding the ENTIRE catalog resolves, on a box session, to a hand-written
+//     expected list — not to whatever the registry happens to say).
+//
+// ORACLE DISCIPLINE. A test whose two sides read the same source of truth passes
+// while proving nothing, so nothing load-bearing here is driven by the registry:
+//   • the Archon-box assertions name Archon powers LITERALLY (builder.rank.set,
+//     governance.manage, deploy.push_main …) and cross-check them against `floor`
+//     run through auth.rankMeetsThreshold — the REAL production rank gate, a
+//     pre-R99 oracle;
+//   • the deny-by-default assertions pin a hand-written expected set, so widening
+//     the registry reds this file instead of silently agreeing with it;
+//   • the subset property (B4) is checked against resolver.effectivePermissions —
+//     the unchanged R95 role answer.
+//
+// End-to-end reachability through the real requireBuilder chain lives in
+// tests/box_scope_session.mjs (the #919 regression guard, unchanged in substance by
+// R99); section G here adds the one case that file cannot express — a session
+// source the registry does not declare at all.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GOV = path.join(ROOT, 'modules', 'governance');
+
+// auth.js destructures lookupSession at load, so the stub must be installed before
+// ANYTHING pulls auth.js in (src/module-api does, via the governance route file).
+const dbKernel = require(path.join(ROOT, 'src', 'bongos', 'db-kernel.js'));
+let nextSession = null;
+dbKernel.lookupSession = async () => nextSession;
+
+const auth = require(path.join(ROOT, 'src', 'bongos', 'auth.js'));
+const catalog = require(path.join(GOV, 'catalog.js'));
+const resolver = require(path.join(GOV, 'resolver.js'));
+const db = require(path.join(GOV, 'db.js'));
+const scopes = require(path.join(GOV, 'session-scopes.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+
+const { permissionKeys, seedForRank, RANK_ORDER, byKey } = catalog;
+const { narrowToSessionScope, resolveSessionPermissions, effectivePermissions } = resolver;
+
+const ME = 42;
+const EVERYTHING = permissionKeys();
+
+// What a box session is EXPECTED to be able to do — written by hand, deliberately
+// NOT read from the registry. Widening the registry must red this file.
+const EXPECTED_BOX_SCOPE = ['box.manage.own'];
+
+// Archon powers, named literally. If a box session ever resolves one of these the
+// #919 containment is gone.
+const ARCHON_POWERS = [
+  'builder.rank.set', 'governance.manage', 'deploy.push_main', 'version.close',
+  'task.confirm.grade_bypass', 'path.protected.modify', 'infra.ssh',
+  'builder.roster.read', 'claim.release.any', 'memory.read.any', 'audit_log.read',
+];
+// Metic powers, named literally — the working rank's authority a box token must
+// not inherit either.
+const METIC_POWERS = ['idea.triage', 'task.create', 'task.edit', 'goal.create', 'box.source.full'];
+
+// Stub the ONE DB read the resolver makes, so the composition is exercised
+// end-to-end without Postgres (the tests/governance_ownership_scope.mjs pattern).
+const realGetPermissionKeys = db.getPermissionKeysForBuilder;
+async function holding(keys, fn) {
+  db.getPermissionKeysForBuilder = async () => keys;
+  try {
+    return await fn();
+  } finally {
+    db.getPermissionKeysForBuilder = realGetPermissionKeys;
+  }
+}
+
+function fakeRes() {
+  const res = {
+    _status: null,
+    _json: null,
+    status(code) { this._status = code; return this; },
+    json(body) { this._json = body; return this; },
+  };
+  attachFail({}, res, () => {});
+  return res;
+}
+
+// ═══ A — the axis is explicit, well-formed data, and BOTH loaders agree ════════
+
+test('A1: every scope declares unscoped XOR a permissions allow-list, over a real source', () => {
+  assert.ok(scopes.SESSION_SCOPES.length >= 2, 'expected at least an unscoped and a scoped source');
+  for (const scope of scopes.SESSION_SCOPES) {
+    assert.ok(scope.source === null || (typeof scope.source === 'string' && scope.source.length > 0),
+      `a scope's source must be a non-empty string or null, saw ${JSON.stringify(scope.source)}`);
+    assert.notEqual(scope.unscoped, scope.permissions.length > 0,
+      `${scope.source}: a scope either narrows nothing or names what it allows — never both/neither`);
+    assert.ok(Object.isFrozen(scope) && Object.isFrozen(scope.permissions));
+  }
+});
+
+test('A2: every allow-listed key is a real, operational, non-principal catalog key', () => {
+  for (const scope of scopes.SESSION_SCOPES) {
+    for (const key of scope.permissions) {
+      const permission = byKey(key);
+      assert.ok(permission, `${scope.source} allows "${key}", which the catalog does not define`);
+      assert.equal(catalog.isPrincipalKey(key), false,
+        `${scope.source} allows a machine-principal key — the identity axis never composes with a session scope`);
+      assert.equal(permission.system, false,
+        `${scope.source} allows a system:true key — a scoped token lives outside the trust boundary`);
+    }
+  }
+});
+
+test('A3: the kernel and the governance module read the SAME registry, identically', () => {
+  // The kernel loads it with fs (ADR 0083's one-way rule) while the module requires
+  // it as a sibling, so the two normalizations are the thing that could drift.
+  assert.deepEqual(auth.SESSION_SCOPES.map((s) => ({ ...s, permissions: [...s.permissions] })),
+    scopes.SESSION_SCOPES.map((s) => ({ ...s, permissions: [...s.permissions] })));
+  for (const source of scopes.sources()) {
+    assert.deepEqual(auth.sessionScopeFor(source), scopes.scopeFor(source));
+  }
+});
+
+test('A4: the declared box scope is exactly the hand-written expectation', () => {
+  // The pin that makes the deny-by-default tests below meaningful: widening the
+  // registry must be a conscious edit here, not a silent agreement.
+  assert.deepEqual([...scopes.allowedKeys('box')], EXPECTED_BOX_SCOPE);
+  assert.equal(scopes.isScoped('box'), true);
+  assert.equal(scopes.isScoped('cli'), false);
+  assert.equal(scopes.isScoped('web'), false);
+});
+
+// ═══ B — THE key test: a box session of an ARCHON ═════════════════════════════
+
+test('B1: an ARCHON on a box session resolves ONLY the allow-list, not Archon powers', async () => {
+  await holding(seedForRank('archon'), async () => {
+    const viaBox = await resolveSessionPermissions(ME, 'box');
+    assert.deepEqual([...viaBox], EXPECTED_BOX_SCOPE,
+      'a box token must carry the scope\'s allow-list and nothing else, however senior its builder');
+    for (const key of [...ARCHON_POWERS, ...METIC_POWERS]) {
+      assert.equal(viaBox.includes(key), false, `a box session reached ${key} — the #919 containment is gone`);
+    }
+  });
+});
+
+test('B2: the same builder on a CLI session DOES hold those powers (the test is not vacuous)', async () => {
+  await holding(seedForRank('archon'), async () => {
+    const viaCli = await resolveSessionPermissions(ME, 'cli');
+    for (const key of [...ARCHON_POWERS, ...METIC_POWERS]) {
+      assert.ok(viaCli.includes(key), `an Archon's CLI session must still hold ${key} — B1 would prove nothing otherwise`);
+    }
+    assert.ok(viaCli.length > EXPECTED_BOX_SCOPE.length + 10,
+      'the box scope must be dramatically smaller than the builder\'s real authority');
+  });
+});
+
+test('B3: EVERY seeded rank collapses to the same box scope — rank buys nothing on a box token', () => {
+  // Independent oracle: `floor` (an R94 field) through auth.rankMeetsThreshold, the
+  // REAL production rank gate. Anything the rank gate would admit for archon but not
+  // for xenos is rank-bought authority, and none of it may survive a box session.
+  const rankBought = catalog.PERMISSIONS
+    .filter((p) => p.floor !== null && auth.rankMeetsThreshold('archon', [p.floor]) && !auth.rankMeetsThreshold('xenos', [p.floor]))
+    .map((p) => p.key);
+  assert.ok(rankBought.length >= 30, `expected the archon/metic/thetes tiers, saw ${rankBought.length}`);
+  for (const rank of RANK_ORDER) {
+    const viaBox = narrowToSessionScope(seedForRank(rank), 'box');
+    for (const key of rankBought) {
+      assert.equal(viaBox.includes(key), false, `${rank}'s box session reached rank-bought ${key}`);
+    }
+  }
+  // ...and every rank's box session is identical, because the scope — not the rank —
+  // is what decides.
+  const perRank = RANK_ORDER.map((r) => [...narrowToSessionScope(seedForRank(r), 'box')]);
+  for (const resolved of perRank) assert.deepEqual(resolved, perRank[0]);
+});
+
+test('B4: for EVERY source and EVERY input, narrowing returns a SUBSET of the role answer', () => {
+  // The structural statement of "can only narrow", against the unchanged R95 role
+  // answer. A union cannot satisfy a subset assertion, so this is the property that
+  // makes widening inexpressible rather than merely unintended.
+  const inputs = [
+    EVERYTHING, [], ['idea.triage'], ['box.manage.own'], seedForRank('xenos'),
+    seedForRank('thetes'), seedForRank('metic'), seedForRank('archon'),
+    ['not.a.real.permission'], ['principal.bfg', 'box.manage.own'],
+  ];
+  for (const source of [...scopes.sources(), 'ghost', undefined]) {
+    for (const input of inputs) {
+      const base = new Set(effectivePermissions(input));
+      for (const key of narrowToSessionScope(input, source)) {
+        assert.ok(base.has(key),
+          `source ${JSON.stringify(source)}: narrowing produced "${key}", which the roles never conferred — this is a WIDENING`);
+      }
+    }
+  }
+});
+
+// ═══ C — intersection, NOT union: the scope cannot grant ══════════════════════
+
+test('C1: a session-scope cannot grant a permission the builder\'s roles lack', async () => {
+  // The scope names box.manage.own; this builder holds everything EXCEPT it. A
+  // union would hand it over; an intersection must return nothing.
+  const withoutTheKey = EVERYTHING.filter((k) => !EXPECTED_BOX_SCOPE.includes(k));
+  await holding(withoutTheKey, async () => {
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'box')], [],
+      'the scope GRANTED a key the roles do not confer — this is a union, not an intersection');
+  });
+});
+
+test('C2: a builder with no roles at all gets nothing from any scope', async () => {
+  await holding([], async () => {
+    for (const source of [...scopes.sources(), 'ghost']) {
+      assert.deepEqual([...await resolveSessionPermissions(ME, source)], [],
+        `source ${JSON.stringify(source)}: an empty role set must stay empty — a scope is not a grant`);
+    }
+  });
+});
+
+test('C3: a null/blank builder resolves to nothing on every source', async () => {
+  for (const builderId of [null, undefined, '']) {
+    for (const source of scopes.sources()) {
+      assert.deepEqual([...await resolveSessionPermissions(builderId, source)], []);
+    }
+  }
+});
+
+// ═══ D — deny-by-default: an unlisted permission is denied ════════════════════
+
+test('D1: holding the ENTIRE catalog, a box session still resolves only the allow-list', async () => {
+  await holding(EVERYTHING, async () => {
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'box')], EXPECTED_BOX_SCOPE,
+      'an unlisted permission leaked through — the allow-list is not deny-by-default');
+  });
+});
+
+test('D2: every catalog key outside the allow-list is denied on a box session', () => {
+  const resolved = new Set(narrowToSessionScope(EVERYTHING, 'box'));
+  const listed = new Set(EXPECTED_BOX_SCOPE);
+  const leaked = [...resolved].filter((k) => !listed.has(k));
+  assert.deepEqual(leaked, [], `these unlisted permissions survived a box session: ${leaked.join(', ')}`);
+  // and the coverage is real — the catalog is far bigger than the allow-list
+  assert.ok(EVERYTHING.length > EXPECTED_BOX_SCOPE.length + 50,
+    'the catalog should dwarf the box allow-list, or D1/D2 assert almost nothing');
+});
+
+test('D3: route reachability is deny-by-default too — a route that declares nothing is out of reach', () => {
+  assert.equal(auth.sessionScopeAdmits('box', undefined), false, 'a route with no declaration must deny a box session');
+  assert.equal(auth.sessionScopeAdmits('box', []), false, 'an empty declaration is not an opt-in');
+  assert.equal(auth.sessionScopeAdmits('box', ['idea.triage']), false, 'a declaration outside the allow-list must deny');
+  assert.equal(auth.sessionScopeAdmits('box', [...EXPECTED_BOX_SCOPE, 'idea.triage']), false,
+    'every declared capability must be inside the scope — one unlisted key denies the whole route');
+  assert.equal(auth.sessionScopeAdmits('box', EXPECTED_BOX_SCOPE), true);
+});
+
+// ═══ E — an unknown key on an allow-list is refused, and inert if it got through ══
+
+test('E1: an unknown, system, or principal key on an allow-list is REJECTED at load', () => {
+  // Exercises the SHIPPED assertion (the module exports the validator it runs on
+  // its own data), not a re-implementation of it.
+  const scoped = (permissions) => [scopes.normalizeScope({ source: 'box', permissions })];
+  assert.throws(() => scopes.validateAgainstCatalog(scoped(['not.a.real.permission'])),
+    /which the permission catalog does not define/);
+  assert.throws(() => scopes.validateAgainstCatalog(scoped(['principal.bfg'])),
+    /machine-principal permission/);
+  assert.throws(() => scopes.validateAgainstCatalog(scoped(['deploy.push_main'])),
+    /system:true permission/);
+  assert.throws(() => scopes.validateAgainstCatalog([scopes.normalizeScope({ source: 'box', unscoped: true, permissions: ['box.manage.own'] })]),
+    /never both\/neither/);
+  assert.throws(() => scopes.validateAgainstCatalog([scopes.normalizeScope({ source: 'box' })]),
+    /never both\/neither/);
+  // the real registry passes its own validator (the fixtures above are not the
+  // only thing keeping this green)
+  assert.doesNotThrow(() => scopes.validateAgainstCatalog(scopes.SESSION_SCOPES));
+});
+
+test('E2: the kernel loader refuses a malformed registry rather than defaulting to unscoped', () => {
+  assert.throws(() => auth.parseSessionScopes({}), /declares no session scopes/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [] }), /declares no session scopes/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [{ source: 'box' }] }), /never both\/neither/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [{ source: 'box', unscoped: true, permissions: ['x'] }] }), /never both\/neither/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [{ source: 7, unscoped: true }] }), /non-empty session source string/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [{ source: 'box', permissions: [42] }] }), /non-string permission key/);
+  assert.throws(() => auth.parseSessionScopes({ scopes: [{ source: 'cli', unscoped: true }, { source: 'cli', unscoped: true }] }), /duplicate session source/);
+});
+
+test('E3: an unknown key that somehow reached an allow-list grants nothing', () => {
+  // Defence in depth behind E1: the intersection is taken against the CATALOG-
+  // FILTERED role answer, so a key the catalog does not define can never appear on
+  // both sides — it is inert as well as refused.
+  const stub = { source: 'x', label: null, unscoped: false, permissions: Object.freeze(['not.a.real.permission']) };
+  const held = effectivePermissions([...EVERYTHING, 'not.a.real.permission']);
+  assert.equal(held.includes('not.a.real.permission'), false, 'the role answer already drops unknown keys');
+  assert.deepEqual(held.filter((k) => stub.permissions.includes(k)), [],
+    'an unknown allow-list key cannot survive the intersection');
+});
+
+// ═══ F — a normal CLI/web session is unaffected ═══════════════════════════════
+
+test('F1: an unscoped session resolves EXACTLY the builder\'s role answer, for every rank', async () => {
+  for (const rank of RANK_ORDER) {
+    const roles = seedForRank(rank);
+    for (const source of ['cli', 'web', null, undefined]) {
+      assert.deepEqual([...narrowToSessionScope(roles, source)], [...effectivePermissions(roles)],
+        `${rank} on ${JSON.stringify(source)}: an unscoped session must narrow NOTHING`);
+    }
+  }
+  await holding(seedForRank('metic'), async () => {
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'cli')],
+      [...await resolver.resolveBuilderPermissions(ME)]);
+  });
+});
+
+test('F2: an unscoped session reaches every route, declared or not', () => {
+  for (const source of ['cli', 'web', null, undefined]) {
+    assert.equal(auth.sessionScopeAdmits(source, undefined), true);
+    assert.equal(auth.sessionScopeAdmits(source, []), true);
+    assert.equal(auth.sessionScopeAdmits(source, ['box.manage.own']), true);
+    assert.equal(auth.sessionScopeAdmits(source, ['governance.manage']), true);
+  }
+});
+
+// ═══ G — an unrecognised session source denies ════════════════════════════════
+
+test('G1: an unrecognised source resolves to NOTHING and reaches NO route', async () => {
+  const unrecognised = ['ghost', 'BOX', 'Box', 'box ', ' cli', 'admin', 0, 1, {}, [], true, false, NaN];
+  await holding(EVERYTHING, async () => {
+    for (const source of unrecognised) {
+      assert.equal(auth.sessionScopeFor(source), null, `${String(source)} must not resolve to a scope`);
+      assert.deepEqual([...await resolveSessionPermissions(ME, source)], [],
+        `${String(source)} must resolve to no authority at all, never to "full"`);
+      assert.equal(auth.sessionScopeAdmits(source, ['box.manage.own']), false);
+      assert.equal(auth.sessionScopeAdmits(source, undefined), false);
+    }
+  });
+});
+
+test('G2: requireBuilder DENIES a session whose source the registry does not declare', async () => {
+  nextSession = { builder_id: 3, github_login: 'ghost', rank: 'archon', status: 'active', source: 'ghost' };
+  const req = { headers: { authorization: 'Bearer ghosttoken' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requireBuilder(req, res, () => { nexted = true; });
+  assert.equal(nexted, false, 'an unclassifiable session must never be treated as unscoped');
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'box_scope');
+  // ...and it stays denied even on a route that opted in, because the DENIAL is the
+  // session's, not the route's.
+  const optedIn = { headers: { authorization: 'Bearer ghosttoken' } };
+  auth.allowBoxScope(optedIn, fakeRes(), () => {});
+  const res2 = fakeRes();
+  let nexted2 = false;
+  await auth.requireBuilder(optedIn, res2, () => { nexted2 = true; });
+  assert.equal(nexted2, false);
+  assert.equal(res2._status, 403);
+  nextSession = null;
+});
+
+// ═══ H — the earlier axes are undisturbed ════════════════════════════════════
+
+test('H1: R95/R98/R100 invariants still hold — the role answer is untouched', async () => {
+  // R99 composes ON TOP of effectivePermissions; widening INSIDE it would red
+  // tests/governance_parity.mjs Parts A and C.
+  assert.deepEqual(effectivePermissions(['principal.bfg', 'box.manage.own']), ['box.manage.own']);
+  assert.deepEqual(effectivePermissions(['idea.triage', 'not.a.real.permission']), ['idea.triage']);
+  for (const rank of RANK_ORDER) {
+    assert.deepEqual([...effectivePermissions(seedForRank(rank))].sort(),
+      [...seedForRank(rank)].filter((k) => !catalog.isPrincipalKey(k)).sort());
+  }
+  await holding(EVERYTHING, async () => {
+    // principals are still the other axis
+    assert.deepEqual([...resolver.resolvePrincipalPermissions('bfg')], ['principal.bfg']);
+    assert.deepEqual([...resolver.resolvePrincipalPermissions(null)], []);
+    // ownership is still a conjunction the plain resolve refuses to answer
+    assert.equal(await resolver.builderHasPermissions(ME, ['box.manage.own']), false);
+    assert.equal(await resolver.authorizeOwned(ME, 'box.manage.own', { ownerId: 99 }), false);
+    assert.equal(await resolver.authorizeOwned(ME, 'box.manage.own', { ownerId: ME }), true);
+  });
+});
+
+test('H2: a box session narrows to an OWNERSHIP-SCOPED key, which still is not an unconditional grant', async () => {
+  // The two axes compose without either swallowing the other: the session-scope
+  // says WHICH keys survive; the ownership axis still demands the row be yours.
+  await holding(seedForRank('archon'), async () => {
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'box')], ['box.manage.own']);
+    assert.equal(await resolver.authorizeOwned(ME, 'box.manage.own', { ownerId: 99 }), false,
+      'surviving the session scope must not turn .own into an unconditional grant');
+    // the cross-owner escalation an Archon holds by role is NOT in the box scope
+    assert.equal(narrowToSessionScope(seedForRank('archon'), 'box').includes('box.fleet.manage'), false);
+  });
+});
+
+test('H3: the resolve is still per-request and frozen — no memoised session authority', async () => {
+  let calls = 0;
+  let keys = ['box.manage.own'];
+  db.getPermissionKeysForBuilder = async () => { calls += 1; return keys; };
+  try {
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'box')], ['box.manage.own']);
+    keys = [];
+    assert.deepEqual([...await resolveSessionPermissions(ME, 'box')], []);
+    assert.equal(calls, 2, 'a revoked grant must take effect on the very next resolve (ADR 0016)');
+  } finally {
+    db.getPermissionKeysForBuilder = realGetPermissionKeys;
+  }
+  assert.ok(Object.isFrozen(narrowToSessionScope(EVERYTHING, 'box')));
+  assert.ok(Object.isFrozen(narrowToSessionScope(EVERYTHING, 'ghost')));
+});
+
+// ═══ I — the ONE governance port carries the axis ════════════════════════════
+
+test('I1: the session-scope axis lands on the single governance port', () => {
+  const { governancePort } = require(path.join(GOV, 'routes', 'governance.js'));
+  for (const name of ['resolveSessionPermissions', 'narrowToSessionScope', 'sessionScopeFor', 'listSessionScopes']) {
+    assert.equal(typeof governancePort[name], 'function', `the port must expose ${name}`);
+  }
+  // still the same one object port the earlier slices registered
+  for (const name of ['resolveBuilderPermissions', 'resolvePrincipalPermissions', 'authorizeOwned']) {
+    assert.equal(typeof governancePort[name], 'function');
+  }
+  assert.deepEqual([...governancePort.sessionScopeFor('box').permissions], EXPECTED_BOX_SCOPE);
+  assert.equal(governancePort.sessionScopeFor('ghost'), null);
+  assert.deepEqual([...governancePort.narrowToSessionScope(seedForRank('archon'), 'box')], EXPECTED_BOX_SCOPE);
+  assert.ok(governancePort.listSessionScopes().length >= 2);
+});

package/tests/governance_vanilla_boot.mjs

@@ -0,0 +1,203 @@
+// tests/governance_vanilla_boot.mjs — the VANILLA BOOT proof (BV1.R102, ADR 0151).
+//
+// The core/host split only holds if a FRESH instance — one that has never been
+// branded, with no config/governance.json on disk and no rows in
+// governance_builder_roles — comes up sane, anonymous, and powerless. This file is
+// that proof. It is deliberately scoped to what R96's tests/governance_config.mjs
+// does NOT cover: that file pins the config CONTRACT (precedence, per-field merge,
+// the three fail-closed strips) driven by INJECTED fixtures; this one boots the real
+// thing off disk and asserts the three vanilla properties:
+//
+//   (a) SANE DEFAULTS       — the four seeded rank-roles resolve with usable labels
+//                             and descriptions from the neutral pack alone; an absent
+//                             instance pack is the NORMAL case, not an error.
+//   (b) NO HOST IDENTITY    — the neutral pack names no host brand, and the CI gate
+//                             that keeps it that way is real rather than a no-op.
+//   (c) BOUNDARY INTACT     — config cannot confer authority on a vanilla boot. The
+//                             grants the four rank-roles hold come from catalog
+//                             FLOORS materialised by governance_002; the file
+//                             contributes exactly nothing, even if someone poisons it.
+//
+// (c) is the half that matters most. A vanilla instance that came up with a role
+// holding `deploy.push_main` because a config file said so is the catastrophic
+// outcome ADR 0016 exists to rule out, and this file is what would go red.
+//
+// DB-free throughout: the config layer is pure + disk, and the grant side is asserted
+// against catalog.RANK_ROLE_SEED (code) rather than a live join. Crucially the two
+// sides read DIFFERENT sources — the seed side reads catalog.js, the config side
+// reads the neutral pack's raw bytes — so a change to either one moves only one side
+// and the assertion goes red.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GOV = path.join(ROOT, 'modules', 'governance');
+const catalog = require(path.join(GOV, 'catalog.js'));
+const { loadGovernanceConfig, resolveGovernanceConfig, NEUTRAL_PATH, INSTANCE_PATH } = require(path.join(GOV, 'config.js'));
+const { effectivePermissions, resolveBuilderPermissions } = require(path.join(GOV, 'resolver.js'));
+const fitness = require(path.join(ROOT, 'scripts', 'gds', 'fitness.js'));
+const { envPrefix } = require(path.join(ROOT, 'src', 'instance-config'));
+
+// Every precedence test injects exactly the env it asserts on — an ambient
+// <PREFIX>_GOVERNANCE_ROLE_LABELS in the runner's shell must not reach the boot.
+const NO_ENV = {};
+const NEUTRAL_TEXT = fs.readFileSync(NEUTRAL_PATH, 'utf8');
+
+// The vanilla boot, exactly as a fresh instance performs it: real neutral pack on
+// disk, no instance pack, no env.
+const vanilla = () => loadGovernanceConfig({ env: NO_ENV });
+// Everything config hands the boot, flattened — the ONLY authority a file could
+// possibly contribute.
+const configUnion = (cfg) => [...new Set(Object.values(cfg.roles).flatMap((r) => r.permissions))].sort();
+
+// Runs `fn(dir)` against a scratch dir, always cleaned up. Nothing under it exists
+// until the test writes it, so `path.join(dir, 'absent.json')` is a genuine ENOENT.
+const withScratchDir = (fn) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gov-vanilla-'));
+  try { fn(dir); } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+};
+
+// ── (a) sane defaults ───────────────────────────────────────────────────────────
+
+test('a fresh instance boots the four rank-roles with usable labels and descriptions', () => {
+  assert.equal(fs.existsSync(INSTANCE_PATH), false, 'fixture guard: this checkout IS the vanilla case (no instance pack)');
+  const out = vanilla();
+  assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+  for (const rank of catalog.RANK_ORDER) {
+    const role = out.roles[rank];
+    assert.equal(role.seeded, true, `${rank} must boot as a SEEDED rank-role, not a custom one`);
+    assert.ok(role.label && role.label !== rank, `${rank} must carry a human label from the neutral pack, got "${role.label}"`);
+    assert.ok(role.description.length > 10, `${rank} must carry a usable description, got "${role.description}"`);
+  }
+});
+
+test('a core with NO config packs at all still boots four roles rather than none', () => {
+  // The extreme vanilla: not just a missing instance pack but a missing neutral one
+  // too. governance_002 seeds the four rank-roles unconditionally, so the display
+  // set must never shrink below them — a boot that dropped `archon` would leave the
+  // instance with grants no template describes.
+  withScratchDir((dir) => {
+    const out = loadGovernanceConfig({
+      neutralPath: path.join(dir, 'absent-neutral.json'),
+      instancePath: path.join(dir, 'absent-instance.json'),
+      env: NO_ENV,
+    });
+    assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+    for (const rank of catalog.RANK_ORDER) assert.equal(out.roles[rank].label, rank, 'a role with no template falls back to its canonical rank name');
+  });
+});
+
+test('a malformed config pack fails LOUD — it never degrades into a silent grant', () => {
+  // Documents the loader's real behaviour: readJson() returns null only for ENOENT,
+  // so a syntactically broken pack throws. That is fail-CLOSED (no authority is
+  // produced), which is the property this proof cares about — but it does contradict
+  // the loader's own header note ("the loader fails to sane defaults rather than
+  // throwing"). Reported as a doc/behaviour mismatch in the R102 handoff, not fixed
+  // here: turning a corrupt authority-adjacent file into a silent fallback is a
+  // decision, not a typo.
+  withScratchDir((dir) => {
+    const broken = path.join(dir, 'broken.json');
+    fs.writeFileSync(broken, '{ not json');
+    assert.throws(() => loadGovernanceConfig({ instancePath: broken, env: NO_ENV }), SyntaxError);
+    assert.throws(() => loadGovernanceConfig({ neutralPath: broken, env: NO_ENV }), SyntaxError);
+  });
+});
+
+// ── (b) no host identity ────────────────────────────────────────────────────────
+
+test('the CI gate over neutral config packs is green, and it actually covers governance', () => {
+  // .json is outside fitness's IDENTITY_SCAN_EXTS (js/html/css), so Check 15 never
+  // opens a config pack. Check 15b (added by this task) is the guard; assert it is
+  // both green AND non-empty, so a future refactor that stops finding the packs
+  // cannot pass by scanning nothing.
+  const r = fitness.checkNeutralConfigsNoHostIdentity();
+  assert.equal(r.hardFail, false, 'neutral packs leak a host brand:\n' + r.violations.join('\n'));
+  assert.match(r.note, /^[1-9]\d* core-shipped/, 'the check must actually find packs to scan: ' + r.note);
+  assert.ok(fs.existsSync(NEUTRAL_PATH), 'governance.neutral.json must ship — it is what a vanilla instance boots from');
+});
+
+test('the identity guard is not a no-op — a planted host brand in the neutral pack is caught', () => {
+  // The mutation test, kept permanent. Both host literals fitness knows about must
+  // trip it, in the exact file this task is about.
+  for (const brand of ['Off the Boats', 'amazonprimea.com']) {
+    const poisoned = NEUTRAL_TEXT.replace('"roles"', `"instance": "${brand}",\n  "roles"`);
+    const found = fitness.scanPromptIdentity('config/governance.neutral.json', poisoned, '.json');
+    assert.ok(found.length >= 1, `a "${brand}" literal in the neutral pack must be caught`);
+  }
+  assert.deepEqual(fitness.scanPromptIdentity('config/governance.neutral.json', NEUTRAL_TEXT, '.json'), [], 'the real pack is clean');
+});
+
+// ── (c) the trust boundary on a vanilla boot ────────────────────────────────────
+
+test('a vanilla boot grants ZERO permissions through config', () => {
+  // The single most important line in this file. Whatever the neutral pack says, the
+  // authority a fresh instance derives FROM A FILE is the empty set.
+  const out = vanilla();
+  assert.deepEqual(configUnion(out), [], 'config contributed authority to a vanilla boot');
+  for (const key of catalog.systemKeys()) {
+    for (const role of Object.values(out.roles)) {
+      assert.ok(!role.permissions.includes(key), `vanilla boot handed role "${role.key}" the system permission "${key}"`);
+    }
+  }
+});
+
+test("a vanilla boot's config union survives the resolver as nothing", () => {
+  // Crosses the two layers: even if a caller took everything config produced and fed
+  // it to the grant path as if it were DB rows, the resolver yields no authority.
+  assert.deepEqual(effectivePermissions(configUnion(vanilla())), []);
+});
+
+test('the rank-roles’ grants derive from catalog floors, never from the neutral pack', () => {
+  // The two sides read DIFFERENT sources on purpose: the seed side is catalog.js
+  // (code), the file side is the pack's raw bytes. Moving either one moves one side
+  // only, so this cannot pass vacuously.
+  for (const rank of catalog.RANK_ORDER) {
+    assert.ok(catalog.RANK_ROLE_SEED[rank].length > 0, `${rank} must hold a floor-derived grant set`);
+  }
+  assert.ok(catalog.RANK_ROLE_SEED.archon.includes('deploy.push_main'), 'fixture guard: archon holds the seed’s system power');
+  assert.ok(!catalog.RANK_ROLE_SEED.xenos.includes('deploy.push_main'), 'fixture guard: the floors are a real ladder');
+  for (const key of catalog.permissionKeys()) {
+    assert.ok(!NEUTRAL_TEXT.includes(key), `the neutral pack names the permission "${key}" — grants belong to governance_002's floors, never to a file`);
+  }
+});
+
+test('a POISONED neutral pack still cannot grant on a vanilla boot', () => {
+  // The adversarial vanilla. R96 proved the three strips against an INSTANCE pack;
+  // the neutral pack is the one the core itself ships, so a compromised or careless
+  // edit to it is the vanilla-boot threat. A seeded role may be relabelled and never
+  // re-granted; a custom template may hold operational keys and never a system one.
+  const poisoned = JSON.parse(NEUTRAL_TEXT);
+  for (const rank of catalog.RANK_ORDER) poisoned.roles[rank].permissions = [...catalog.permissionKeys()];
+  poisoned.roles.superuser = { label: 'Superuser', permissions: [...catalog.permissionKeys()] };
+  const out = resolveGovernanceConfig({ neutral: poisoned, env: NO_ENV });
+  for (const rank of catalog.RANK_ORDER) {
+    assert.deepEqual(out.roles[rank].permissions, [], `a poisoned neutral pack re-granted the seeded role "${rank}"`);
+  }
+  for (const key of catalog.systemKeys()) {
+    assert.ok(!out.roles.superuser.permissions.includes(key), `a neutral-pack template smuggled the system permission "${key}"`);
+  }
+  assert.deepEqual(out.roles.superuser.permissions, [...catalog.grantableKeys()].sort(), 'operational keys are all a template may ever propose');
+});
+
+test('the env layer cannot widen authority on a vanilla boot', () => {
+  const env = { [`${envPrefix()}_GOVERNANCE_ROLE_LABELS`]: 'archon=Owner' };
+  const out = loadGovernanceConfig({ env });
+  assert.equal(out.roles.archon.label, 'Owner', 'env may relabel');
+  assert.deepEqual(configUnion(out), [], 'env must never add a permission');
+});
+
+test('a fresh instance with no role rows resolves every builder to the empty set', () => {
+  // A vanilla governance_builder_roles table is empty, so the grant side of the
+  // resolve returns nothing — and an unidentified caller short-circuits before the
+  // DB is touched at all. Both are the fail-closed default the boundary rests on.
+  assert.deepEqual(effectivePermissions([]), []);
+  return Promise.all([null, undefined, ''].map(async (id) => {
+    assert.deepEqual(await resolveBuilderPermissions(id), []);
+  }));
+});