@bongos/core 1.18.3 → 1.18.18

package/tests/governance_ownership_scope.mjs

@@ -0,0 +1,410 @@
+// tests/governance_ownership_scope.mjs — ownership-scoped permissions
+// ("act on OWN X") as a first-class axis (BV1.R100, ADR 0151 §3). DB-free.
+//
+// The thing being proved is a CONJUNCTION. `box.manage.own` is not a grant that
+// happens to be named "own" — it is half a decision:
+//
+//   1. the ROLE fact  — the builder holds the key (resolved from the DB, uncached);
+//   2. the OWNER fact — the concrete row is theirs (a REQUEST-scoped fact the
+//                       resolver structurally cannot know: it is handed a builder
+//                       id, never a box).
+//
+// The security failure mode this file exists to catch is (2) quietly disappearing,
+// leaving `.own` as an unconditional grant — i.e. `X.manage.own` silently becoming
+// `X.manage.any`. So the load-bearing tests are: `.own` never implies `.any`, and a
+// builder holding EVERY permission in the catalog still cannot touch a row that
+// belongs to someone else.
+//
+// ORACLE DISCIPLINE. A test whose two sides read the same field cannot fail — a bad
+// value moves both together. So the "own ≠ any" assertions are driven by `floor`
+// (a PRE-R100 field) run through auth.rankMeetsThreshold (the REAL production rank
+// gate). The new `scope`/`resource` fields are used only to ENUMERATE which pairs
+// to check, never to decide whether a pair is separated.
+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 resolver = require(path.join(GOV, 'resolver.js'));
+const db = require(path.join(GOV, 'db.js'));
+const auth = require(path.join(ROOT, 'src', 'bongos', 'auth.js'));
+
+const {
+  PERMISSIONS, RANK_ORDER, RANK_ROLE_SEED, RESOURCE_FAMILIES, permissionKeys, byKey,
+  scopeOf, resourceOf, isOwnershipScoped, isCrossOwner, ownershipScopedKeys, crossOwnerKeys,
+  crossOwnerKeysFor, isPrincipalKey, seedForRank,
+} = catalog;
+const {
+  sameOwner, authorizeOwned, authorizeOwnedOrAny, builderHasPermissions, effectivePermissions,
+} = resolver;
+
+const ME = 42;
+const SOMEONE_ELSE = 99;
+
+// Stub the ONE DB read the resolver makes, so the ownership logic is exercised
+// end-to-end without Postgres. resolver.js looks the method up on the db module
+// object at call time, so replacing it here bites the real code path.
+const realGetPermissionKeys = db.getPermissionKeysForBuilder;
+async function holding(keys, fn) {
+  db.getPermissionKeysForBuilder = async () => keys;
+  try {
+    return await fn();
+  } finally {
+    db.getPermissionKeysForBuilder = realGetPermissionKeys;
+  }
+}
+const EVERYTHING = permissionKeys();
+
+// Families with BOTH sides declared — the pairs "own must not imply any" is about.
+const PAIRED = Object.entries(RESOURCE_FAMILIES).filter(([, f]) => f.own.length && f.any.length);
+
+// ═══ A — the axis is explicit, well-formed catalog DATA ═══════════════════════
+
+test('A1: scope and resource come together, with a valid scope and a real rank floor', () => {
+  // byKey() returns the NORMALIZED record (absent scope/resource read back as
+  // null), the same shape R98's principal axis normalizes to.
+  for (const p of permissionKeys().map(byKey)) {
+    assert.equal(p.scope === null, p.resource === null,
+      `${p.key}: an ownership scope is always scoped OVER a named resource`);
+    if (p.scope === null) continue;
+    assert.ok(['own', 'any'].includes(p.scope), `${p.key}: invalid scope "${p.scope}"`);
+    assert.equal(typeof p.resource, 'string');
+    assert.ok(p.resource.length > 0, `${p.key}: empty resource family`);
+    assert.notEqual(p.floor, null,
+      `${p.key}: the ownership axis narrows a ROLE permission — it never composes with an identity`);
+    assert.equal(isPrincipalKey(p.key), false, `${p.key}: a principal has no owner axis`);
+  }
+});
+
+test('A2: every ".own"-suffixed key DECLARES scope own — the namespace never outruns the data', () => {
+  const suffixed = PERMISSIONS.filter((p) => p.key.endsWith('.own'));
+  assert.ok(suffixed.length >= 4, `expected the own-scoped keys, saw ${suffixed.length}`);
+  for (const p of suffixed) {
+    assert.equal(p.scope, 'own', `${p.key} looks ownership-scoped but does not declare it`);
+  }
+  // ...and the converse is deliberately NOT asserted: `me.wandering.set` is
+  // own-scoped with no suffix, and `task.claim.any` ends in `.any` while meaning
+  // "any task in the pool", not "any owner's resource". Suffix inference would get
+  // both wrong — which is the whole reason the axis is data.
+  assert.equal(scopeOf('me.wandering.set'), 'own');
+  assert.equal(scopeOf('task.claim.any'), null, 'task.claim.any is a POOL filter, not an owner scope');
+  assert.equal(isCrossOwner('task.claim.any'), false);
+});
+
+test('A3: the modelled families are the ones the ownership sweep names', () => {
+  assert.deepEqual(Object.keys(RESOURCE_FAMILIES).sort(),
+    ['box', 'builder_prefs', 'claim', 'credential', 'goal', 'memory']);
+  assert.deepEqual([...ownershipScopedKeys()].sort(),
+    ['box.manage.own', 'credential.manage.own', 'goal.manage.own', 'me.wandering.set', 'memory.manage.own', 'task.act.own']);
+  // The cross-owner side is NOT derivable from spelling: box's is `box.fleet.manage`.
+  assert.deepEqual([...crossOwnerKeys()].sort(),
+    ['box.fleet.manage', 'claim.release.any', 'memory.read.any']);
+  assert.deepEqual(crossOwnerKeysFor('task.act.own'), ['claim.release.any']);
+  assert.deepEqual(crossOwnerKeysFor('box.manage.own'), ['box.fleet.manage']);
+  // Some resources have NO cross-owner form by design — nobody manages another
+  // builder's credential, Archon included.
+  assert.deepEqual(crossOwnerKeysFor('credential.manage.own'), []);
+  assert.deepEqual(crossOwnerKeysFor('nope.not.a.key'), []);
+});
+
+test('A4: RESOURCE_FAMILIES is frozen and agrees with each row it lists', () => {
+  assert.ok(Object.isFrozen(RESOURCE_FAMILIES));
+  for (const [resource, fam] of Object.entries(RESOURCE_FAMILIES)) {
+    assert.ok(Object.isFrozen(fam) && Object.isFrozen(fam.own) && Object.isFrozen(fam.any));
+    for (const key of fam.own) {
+      assert.equal(resourceOf(key), resource);
+      assert.equal(scopeOf(key), 'own');
+    }
+    for (const key of fam.any) {
+      assert.equal(resourceOf(key), resource);
+      assert.equal(scopeOf(key), 'any');
+    }
+    assert.ok(fam.own.length > 0, `${resource}: a cross-owner key with no own counterpart is a mis-declaration`);
+  }
+});
+
+// ═══ B — `.own` does NOT imply `.any` (oracle: floors × the real rank gate) ════
+
+test('B1: for every paired family some rank reaches its OWN row but not everyone else\'s', () => {
+  assert.ok(PAIRED.length >= 3, `expected the box/claim/memory pairs, saw ${PAIRED.length}`);
+  for (const [resource, fam] of PAIRED) {
+    for (const ownKey of fam.own) {
+      for (const anyKey of fam.any) {
+        // Independent oracle: the floors (a pre-R100 field) run through the REAL
+        // production threshold function. A separation asserted this way cannot be
+        // faked by anything R100 added.
+        const separating = RANK_ORDER.filter((rank) =>
+          auth.rankMeetsThreshold(rank, [byKey(ownKey).floor]) &&
+          !auth.rankMeetsThreshold(rank, [byKey(anyKey).floor]));
+        assert.ok(separating.length > 0,
+          `${resource}: ${ownKey} and ${anyKey} are held by exactly the same ranks — "own" collapses into "any"`);
+      }
+    }
+  }
+});
+
+test('B2: the seed grants the own key to ranks it withholds the cross-owner key from', () => {
+  for (const [resource, fam] of PAIRED) {
+    for (const ownKey of fam.own) {
+      const ownOnly = RANK_ORDER.filter((r) => RANK_ROLE_SEED[r].includes(ownKey) && !fam.any.some((a) => RANK_ROLE_SEED[r].includes(a)));
+      assert.ok(ownOnly.length > 0, `${resource}: no rank holds ${ownKey} without also holding ${fam.any.join('/')}`);
+    }
+  }
+  // The concrete claim, spelled out: a xenos may act on their own claim and their
+  // own box; they may not release another builder's claim or close another's box.
+  assert.ok(RANK_ROLE_SEED.xenos.includes('task.act.own'));
+  assert.ok(!RANK_ROLE_SEED.xenos.includes('claim.release.any'));
+  assert.ok(RANK_ROLE_SEED.xenos.includes('box.manage.own'));
+  assert.ok(!RANK_ROLE_SEED.xenos.includes('box.fleet.manage'));
+});
+
+test('B3: cross-owner authority is never CHEAPER than own-only authority', () => {
+  for (const [resource, fam] of PAIRED) {
+    for (const anyKey of fam.any) {
+      for (const ownKey of fam.own) {
+        assert.ok(RANK_ORDER.indexOf(byKey(anyKey).floor) >= RANK_ORDER.indexOf(byKey(ownKey).floor),
+          `${resource}: ${anyKey} sits below ${ownKey} — reaching every owner must not be easier than reaching your own`);
+      }
+    }
+  }
+});
+
+// ═══ C — THE key test: `.own` still fails against someone else's row ══════════
+
+test('C1: holding EVERY permission in the catalog still cannot reach another builder\'s row', async () => {
+  // The degradation this whole axis exists to prevent. Even maximal role authority
+  // supplies only fact (1); fact (2) is false, so the answer must be no.
+  await holding(EVERYTHING, async () => {
+    for (const key of ownershipScopedKeys()) {
+      assert.equal(await authorizeOwned(ME, key, { ownerId: SOMEONE_ELSE }), false,
+        `${key} admitted against another builder's row — ".own" has degraded into an unconditional grant`);
+    }
+  });
+});
+
+test('C2: the same key on the caller\'s OWN row admits — but only while they hold it', async () => {
+  await holding(EVERYTHING, async () => {
+    for (const key of ownershipScopedKeys()) {
+      assert.equal(await authorizeOwned(ME, key, { ownerId: ME }), true, `${key} on own row`);
+    }
+  });
+  // Owning the row is not authority either — the conjunction cuts both ways.
+  await holding([], async () => {
+    for (const key of ownershipScopedKeys()) {
+      assert.equal(await authorizeOwned(ME, key, { ownerId: ME }), false,
+        `${key} admitted without the grant — owning a row is not a permission`);
+    }
+  });
+});
+
+test('C3: no owner supplied = no admit, however the caller spells the omission', async () => {
+  // The structural bit: `ownerId` is not an option, it is the second half of the
+  // question. A handler that forgets it gets a denial, never a pass-through.
+  await holding(EVERYTHING, async () => {
+    for (const context of [undefined, null, {}, { ownerId: null }, { ownerId: undefined }, { ownerId: '' }, { ownerId: {} }, { ownerId: [] }, { ownerId: true }, { ownerId: NaN }]) {
+      assert.equal(await authorizeOwned(ME, 'box.manage.own', context), false,
+        `an unidentifiable owner (${JSON.stringify(context)}) must deny`);
+    }
+  });
+});
+
+test('C4: authorizeOwned is the OWN entry point only — other keys fail closed', async () => {
+  await holding(EVERYTHING, async () => {
+    // A cross-owner key is not an ownership-scoped one; it has its own answer via
+    // the plain resolve, and must not acquire a second, owner-shaped route in.
+    assert.equal(await authorizeOwned(ME, 'claim.release.any', { ownerId: ME }), false);
+    // Nor an unscoped operational key, a system key, a principal key, or a typo.
+    assert.equal(await authorizeOwned(ME, 'idea.triage', { ownerId: ME }), false);
+    assert.equal(await authorizeOwned(ME, 'deploy.push_main', { ownerId: ME }), false);
+    assert.equal(await authorizeOwned(ME, 'principal.bfg', { ownerId: ME }), false);
+    assert.equal(await authorizeOwned(ME, 'nope.not.a.key', { ownerId: ME }), false);
+    // A blank actor cannot own anything, even matching a blank owner.
+    assert.equal(await authorizeOwned(null, 'box.manage.own', { ownerId: null }), false);
+    assert.equal(await authorizeOwned('', 'box.manage.own', { ownerId: '' }), false);
+  });
+});
+
+test('C5: builderHasPermissions REFUSES an ownership-scoped key rather than answering half of it', async () => {
+  await holding(EVERYTHING, async () => {
+    for (const key of ownershipScopedKeys()) {
+      assert.equal(await builderHasPermissions(ME, [key]), false,
+        `${key}: "do you hold it" has no unconditional answer — the caller wants authorizeOwned()`);
+    }
+    // One own key poisons the whole AND-list; unscoped keys still answer normally.
+    assert.equal(await builderHasPermissions(ME, ['idea.triage', 'box.manage.own']), false);
+    assert.equal(await builderHasPermissions(ME, ['idea.triage', 'cost.log']), true);
+    assert.equal(await builderHasPermissions(ME, ['claim.release.any']), true);
+  });
+});
+
+// ═══ D — `.any` DOES reach another builder's resource ═════════════════════════
+
+test('D1: the cross-owner key reaches a row the caller does not own', async () => {
+  await holding(['task.act.own', 'claim.release.any'], async () => {
+    assert.equal(await authorizeOwnedOrAny(ME, 'task.act.own', { ownerId: SOMEONE_ELSE }), true,
+      'claim.release.any is exactly the authority to act on someone else\'s claim');
+    assert.equal(await authorizeOwnedOrAny(ME, 'task.act.own', { ownerId: ME }), true);
+  });
+  await holding(['memory.manage.own', 'memory.read.any'], async () => {
+    assert.equal(await authorizeOwnedOrAny(ME, 'memory.manage.own', { ownerId: SOMEONE_ELSE }), true);
+  });
+  await holding(['box.manage.own', 'box.fleet.manage'], async () => {
+    assert.equal(await authorizeOwnedOrAny(ME, 'box.manage.own', { ownerId: SOMEONE_ELSE }), true);
+  });
+});
+
+test('D2: holding only the OWN key never reaches someone else, in either entry point', async () => {
+  for (const [, fam] of PAIRED) {
+    for (const ownKey of fam.own) {
+      await holding([ownKey], async () => {
+        assert.equal(await authorizeOwnedOrAny(ME, ownKey, { ownerId: SOMEONE_ELSE }), false,
+          `${ownKey} alone must not reach another owner's row`);
+        assert.equal(await authorizeOwnedOrAny(ME, ownKey, { ownerId: ME }), true);
+      });
+    }
+  }
+});
+
+test('D3: a family with no cross-owner form has no escalation, even at maximal authority', async () => {
+  await holding(EVERYTHING, async () => {
+    for (const key of ['credential.manage.own', 'me.wandering.set', 'goal.manage.own']) {
+      assert.equal(await authorizeOwnedOrAny(ME, key, { ownerId: SOMEONE_ELSE }), false,
+        `${key} has no declared cross-owner counterpart — nothing may escalate past it`);
+    }
+    // and the entry point still refuses a non-own key
+    assert.equal(await authorizeOwnedOrAny(ME, 'claim.release.any', { ownerId: ME }), false);
+    assert.equal(await authorizeOwnedOrAny(ME, 'nope.not.a.key', { ownerId: ME }), false);
+  });
+});
+
+// ═══ E — the owner comparison itself ══════════════════════════════════════════
+
+test('E1: sameOwner matches scalar ids across the number/string boundary, nothing else', () => {
+  // Postgres hands bigints back as strings while JS code carries them as numbers,
+  // so 7 and '7' are the same owner.
+  assert.equal(sameOwner(7, '7'), true);
+  assert.equal(sameOwner('7', 7), true);
+  assert.equal(sameOwner(7n, '7'), true);
+  assert.equal(sameOwner(7, 7), true);
+  assert.equal(sameOwner('abc', 'abc'), true);
+  assert.equal(sameOwner(7, 8), false);
+  assert.equal(sameOwner('7', '07'), false);
+});
+
+test('E2: nothing without a scalar identity ever matches — including two of the same', () => {
+  const noIdentity = [null, undefined, '', {}, [], true, false, NaN, Infinity, -Infinity, () => {}];
+  for (const v of noIdentity) {
+    assert.equal(sameOwner(v, 7), false, `${String(v)} must not match a real id`);
+    assert.equal(sameOwner(7, v), false, `${String(v)} must not match a real id`);
+    assert.equal(sameOwner(v, v), false, `two unidentifiable values must not "match" each other (${String(v)})`);
+  }
+  // No trimming, no case-folding: normalizing harder than the data warrants is how
+  // a comparison quietly widens.
+  assert.equal(sameOwner(' 7', 7), false);
+  assert.equal(sameOwner('7 ', '7'), false);
+  assert.equal(sameOwner('ABC', 'abc'), false);
+  // type confusion via toString/valueOf gets no purchase
+  assert.equal(sameOwner({ toString: () => '7' }, 7), false);
+  assert.equal(sameOwner([7], 7), false);
+});
+
+// ═══ F — the load-time invariants actually throw ══════════════════════════════
+// Proven by loading a MUTATED COPY of the real catalog, so what is under test is
+// the shipped assertion block, not a re-implementation of it.
+
+function loadMutatedCatalog(label, mutate) {
+  const source = fs.readFileSync(path.join(GOV, 'catalog.js'), 'utf8');
+  const mutated = mutate(source);
+  assert.notEqual(mutated, source, `${label}: the fixture mutation did not apply — the test would be vacuous`);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gov-catalog-'));
+  const file = path.join(dir, 'catalog.js');
+  fs.writeFileSync(file, mutated);
+  try {
+    require(file);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('F1: a ".own" key that lost its declared scope throws at module load', () => {
+  assert.throws(
+    () => loadMutatedCatalog('missing scope', (s) => s.replace(
+      `{ key: 'box.manage.own', system: false, floor: 'xenos', scope: 'own', resource: 'box',`,
+      `{ key: 'box.manage.own', system: false, floor: 'xenos',`)),
+    /does not declare scope/,
+  );
+});
+
+test('F2: an ownership scope with no resource family throws at module load', () => {
+  assert.throws(
+    () => loadMutatedCatalog('scope without resource', (s) => s.replace(
+      `scope: 'own', resource: 'box',`, `scope: 'own',`)),
+    /scope and resource must come together/,
+  );
+});
+
+test('F3: a cross-owner key cheaper than its own-scoped counterpart throws at module load', () => {
+  assert.throws(
+    () => loadMutatedCatalog('inverted floors', (s) => s.replace(
+      `  { key: 'goal.manage.own',`,
+      `  { key: 'goal.manage.any', system: false, floor: 'xenos', scope: 'any', resource: 'goal', guards: 'fixture' },\n  { key: 'goal.manage.own',`)),
+    /must never be cheaper than own-only/,
+  );
+});
+
+test('F4: a cross-owner key with no ownership-scoped counterpart throws at module load', () => {
+  assert.throws(
+    () => loadMutatedCatalog('lone any', (s) => s.replace(
+      `  { key: 'goal.manage.own',`,
+      `  { key: 'widget.manage.any', system: false, floor: 'archon', scope: 'any', resource: 'widget', guards: 'fixture' },\n  { key: 'goal.manage.own',`)),
+    /with no ownership-scoped counterpart/,
+  );
+});
+
+// ═══ G — the R94/R95/R98 invariants this slice must not have disturbed ════════
+
+test('G1: the seed is still floor-derived and cumulative — the ownership axis adds no grants', () => {
+  for (const rank of RANK_ORDER) {
+    const held = new Set(RANK_ROLE_SEED[rank]);
+    const tier = RANK_ORDER.indexOf(rank);
+    for (const p of PERMISSIONS) {
+      assert.equal(held.has(p.key), p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier,
+        `${rank} vs ${p.key}: scope must not touch the floor derivation`);
+    }
+    assert.deepEqual([...seedForRank(rank)].sort(), [...RANK_ROLE_SEED[rank]].sort());
+  }
+});
+
+test('G2: the role resolve is untouched — own-scoped keys still resolve, principals still drop', () => {
+  // Deliberate: resolveBuilderPermissions stays the raw ROLE-axis answer, which is
+  // what R103's parity proof pins. Ownership narrows at the DECISION, not by
+  // deleting the key from the resolved set.
+  const resolved = effectivePermissions(EVERYTHING);
+  for (const key of ownershipScopedKeys()) {
+    assert.ok(resolved.includes(key), `${key} must still resolve — parity depends on it`);
+  }
+  assert.deepEqual(effectivePermissions(['principal.bfg', 'box.manage.own']), ['box.manage.own']);
+  assert.deepEqual(effectivePermissions(['idea.triage', 'not.a.real.permission']), ['idea.triage']);
+  assert.deepEqual(effectivePermissions([]), []);
+  assert.ok(Object.isFrozen(resolved));
+});
+
+test('G3: the kernel port carries the ownership axis on the ONE governance port', () => {
+  const { governancePort } = require(path.join(GOV, 'routes', 'governance.js'));
+  for (const name of ['authorizeOwned', 'authorizeOwnedOrAny', 'sameOwner', 'isOwnershipScoped', 'crossOwnerKeysFor']) {
+    assert.equal(typeof governancePort[name], 'function', `the port must expose ${name}`);
+  }
+  // still the same one object port the earlier slices registered
+  assert.equal(typeof governancePort.resolveBuilderPermissions, 'function');
+  assert.equal(typeof governancePort.resolvePrincipalPermissions, 'function');
+  assert.equal(governancePort.isOwnershipScoped('box.manage.own'), true);
+  assert.equal(governancePort.isOwnershipScoped('claim.release.any'), false);
+  assert.equal(governancePort.isOwnershipScoped('nope.not.a.key'), false);
+});