@bongos/core 1.19.158 → 1.19.159

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.158",
+  "version": "1.19.159",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.158",
+      "version": "1.19.159",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.158",
+  "version": "1.19.159",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/route-rank-check.js

@@ -414,6 +414,7 @@ const MODULE_EXPECTED_RANKS = {
     'POST /governance/roles': 'perm:governance.manage',
     'PUT /governance/roles/:roleKey/permissions/:permissionKey': 'perm:governance.manage',
     'DELETE /governance/roles/:roleKey/permissions/:permissionKey': 'perm:governance.manage',
+    'POST /governance/roles/:roleKey/reset': 'perm:governance.manage',
     'POST /governance/assignments': 'perm:governance.manage',
     'DELETE /governance/assignments/:builderId/:roleKey': 'perm:governance.manage',
   },

package/src/module-api.js

@@ -743,8 +743,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.156 with no explicit bump. run 31958139486. (task 1002620)
 //   1.19.158 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.157 with no explicit bump. run 31958753412. (task 1002620)
+//   1.19.159 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.158 with no explicit bump. run 31958999646. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.158'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.159'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/governance_abuse_matrix.mjs

@@ -63,9 +63,19 @@ const SYSTEM_KEYS = catalog.systemKeys();
 const SEEDED_ROLES = catalog.RANK_ORDER; // xenos/thetes/metic/archon
 
 // The keys whose enforcement lives OUTSIDE the app entirely (git pre-push hook,
-// grader pre-pass, post-push main audit, credential placement — ADR 0043). The
-// task names deploy + protected-path; infra.ssh is the same substrate class.
-const SUBSTRATE_KEYS = ['deploy.push_main', 'path.protected.modify', 'infra.ssh'];
+// grader pre-pass, post-push main audit, credential placement — ADR 0043). Read
+// from the CATALOG since ADR 0172 made the class data: enumerating rather than
+// listing means a fourth substrate key is covered by every vector below the day it
+// lands. The three named ones are asserted present so the marker can't be quietly
+// dropped from a row and take the coverage with it.
+const SUBSTRATE_KEYS = catalog.substrateKeys();
+const NAMED_SUBSTRATE = ['deploy.push_main', 'path.protected.modify', 'infra.ssh'];
+
+// The rank-roles ADR 0172 made editable — everything below the top of the ladder.
+const EDITABLE_RANK_ROLES = catalog.RANK_ORDER.filter((r) => r !== 'archon');
+// The in-app Archon powers: system, but a real route reads them, so they CAN be
+// delegated to a rank-role. Derived as system-minus-substrate-minus-principal.
+const OWNER_POWERS = SYSTEM_KEYS.filter((k) => !catalog.isSubstrate(k) && !catalog.isPrincipalKey(k));
 
 // ===========================================================================
 // The matrix rows — sanity on what is being enumerated
@@ -73,12 +83,15 @@ const SUBSTRATE_KEYS = ['deploy.push_main', 'path.protected.modify', 'infra.ssh'
 
 test('the matrix enumerates a non-empty system set including the named powers', () => {
   assert.ok(SYSTEM_KEYS.length > 0, 'no system keys — the matrix would be vacuous');
-  for (const k of SUBSTRATE_KEYS) {
+  for (const k of NAMED_SUBSTRATE) {
+    assert.ok(SUBSTRATE_KEYS.includes(k), `${k} must still carry substrate:true — dropping the marker would silently narrow every vector below`);
     assert.ok(SYSTEM_KEYS.includes(k), `${k} must be system:true`);
   }
   for (const k of SYSTEM_KEYS) {
-    assert.equal(catalog.isGrantable(k), false, `${k} must be non-grantable`);
+    assert.equal(catalog.isGrantable(k), false, `${k} must be non-grantable to a CUSTOM role`);
   }
+  assert.ok(OWNER_POWERS.length > 0, 'no in-app owner powers — V2c would be vacuous');
+  assert.ok(EDITABLE_RANK_ROLES.length > 0, 'no editable rank-roles — V2b/V2c would be vacuous');
 });
 
 test('every system permission floors at archon or is a principal (never seeded lower)', () => {
@@ -101,6 +114,7 @@ const stub = {
   createRole: async (a) => ({ role_key: a.roleKey, label: a.label, description: a.description ?? null, is_system: false, seeded_rank: null, created_by: a.createdBy, created_at: 't' }),
   grantRolePermission: async () => true,
   revokeRolePermission: async () => true,
+  resetRoleGrants: async ({ permissionKeys }) => permissionKeys.length,
   assignRole: async () => true,
   unassignRole: async () => true,
   listRolesWithGrants: async () => [],
@@ -162,15 +176,67 @@ test('V1: EVERY system permission is refused onto a custom role, before the db',
   }
 });
 
-test('V2: EVERY seeded rank-role refuses EVERY grant (system and operational alike)', async () => {
-  for (const role of SEEDED_ROLES) {
-    for (const k of [...SYSTEM_KEYS, 'idea.triage']) {
+// ADR 0172 split the old single V2 ("every seeded rank-role refuses every grant")
+// into three, because two thirds of that wall stayed and one third was deliberately
+// removed. Asserting the removed third is as important as asserting the kept ones:
+// it is what stops a later "tighten the governance routes" refactor from quietly
+// reinstating the wall the owner asked to take down.
+
+test('V2a: the ARCHON rank-role refuses EVERY write — grant, revoke and reset alike', async () => {
+  for (const k of [...SYSTEM_KEYS, 'idea.triage']) {
+    for (const method of ['PUT', 'DELETE']) {
+      const r = await call(method, `/governance/roles/archon/permissions/${k}`);
+      assert.equal(r.status, 403, `archon ← ${method} ${k} must be refused`);
+      assert.equal(r.json.error.code, 'archon_role_immutable', `archon ← ${method} ${k}`);
+      assert.equal(calls.filter(([c]) => c === 'grantRolePermission' || c === 'revokeRolePermission').length, 0);
+    }
+  }
+  const r = await call('POST', '/governance/roles/archon/reset');
+  assert.equal(r.status, 403, 'reset must not be a back door into the archon role');
+  assert.equal(r.json.error.code, 'archon_role_immutable');
+  assert.equal(calls.filter(([c]) => c === 'resetRoleGrants').length, 0);
+});
+
+test('V2b: EVERY editable rank-role still refuses every SUBSTRATE and PRINCIPAL key', async () => {
+  const neverGrantable = [...SUBSTRATE_KEYS, ...catalog.principalKeys()];
+  for (const role of EDITABLE_RANK_ROLES) {
+    for (const k of neverGrantable) {
+      const r = await call('PUT', `/governance/roles/${role}/permissions/${k}`);
+      assert.equal(r.status, 400, `${role} ← ${k} must be refused`);
+      assert.equal(r.json.error.code, 'permission_not_grantable', `${role} ← ${k}`);
+      assert.equal(calls.filter(([c]) => c === 'grantRolePermission').length, 0,
+        `${role} ← ${k}: the refusal must land BEFORE any db write`);
+    }
+  }
+});
+
+test('V2c: an editable rank-role ACCEPTS the in-app owner powers (the ADR 0172 lever)', async () => {
+  for (const role of EDITABLE_RANK_ROLES) {
+    for (const k of [...OWNER_POWERS, 'idea.triage']) {
       const r = await call('PUT', `/governance/roles/${role}/permissions/${k}`);
-      assert.equal(r.status, 403, `${role} ← ${k} must be refused`);
-      assert.equal(r.json.error.code, 'seeded_role_immutable', `${role} ← ${k}`);
-      assert.equal(calls.filter(([c]) => c === 'grantRolePermission').length, 0);
+      assert.equal(r.status, 200, `${role} ← ${k} must be ACCEPTED — this delegation is the owner's decision (ADR 0172)`);
+      assert.equal(calls.filter(([c]) => c === 'grantRolePermission').length, 1, `${role} ← ${k} must reach the db`);
+    }
+  }
+});
+
+test('V2d: reset restores the CATALOG seed, never anything wider', async () => {
+  for (const role of EDITABLE_RANK_ROLES) {
+    const r = await call('POST', `/governance/roles/${role}/reset`);
+    assert.equal(r.status, 200, `${role} must be resettable`);
+    const [, args] = calls.find(([c]) => c === 'resetRoleGrants');
+    assert.deepEqual([...args.permissionKeys].sort(), [...catalog.seedForRank(role)].sort(),
+      `${role} reset must write exactly the floor-derived seed`);
+    for (const k of args.permissionKeys) {
+      assert.equal(catalog.isSystem(k), false, `${role} reset wrote system key ${k} — reset must never widen`);
     }
   }
+  // A custom role has no catalog default, so reset is refused rather than silently
+  // clearing its grants (which would be a destructive verb wearing a restore's name).
+  const r = await call('POST', '/governance/roles/custom-role/reset');
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'role_has_no_default');
+  assert.equal(calls.filter(([c]) => c === 'resetRoleGrants').length, 0);
 });
 
 test('V3: EVERY seeded rank-role refuses assignment (rank is the only writer — R95b)', async () => {
@@ -213,6 +279,7 @@ test('V5: a caller without governance.manage cannot reach ANY write vector at al
     ['POST', '/governance/roles', { role_key: 'x-role', label: 'X' }],
     ['PUT', '/governance/roles/custom-role/permissions/deploy.push_main', undefined],
     ['DELETE', '/governance/roles/custom-role/permissions/idea.triage', undefined],
+    ['POST', '/governance/roles/metic/reset', undefined],
     ['POST', '/governance/assignments', { builder_id: 7, role_key: 'custom-role' }],
     ['DELETE', '/governance/assignments/7/custom-role', undefined],
   ]) {

package/tests/governance_catalog.mjs

@@ -46,6 +46,57 @@ test('isGrantable: operational→true, system→false, unknown→false', () => {
   assert.equal(isSystem('nope.not.a.key'), null); // unknown → null (caller fails closed)
 });
 
+// ── the substrate axis + per-role grantability (ADR 0172) ────────────────────
+
+test('substrate keys are the out-of-band three, and each implies system + archon floor', () => {
+  const sub = cat.substrateKeys();
+  assert.deepEqual([...sub].sort(), ['deploy.push_main', 'infra.ssh', 'path.protected.modify']);
+  for (const k of sub) {
+    assert.equal(cat.isSubstrate(k), true);
+    assert.equal(isSystem(k), true, `${k} must be system:true`);
+    assert.equal(byKey(k).floor, 'archon', `${k} must floor at archon`);
+    assert.equal(byKey(k).principal, null, `${k} must not also be a principal key`);
+  }
+  assert.equal(cat.isSubstrate('governance.manage'), false, 'an in-app archon power is not substrate');
+  assert.equal(cat.isSubstrate('nope.not.a.key'), false, 'unknown fails closed');
+});
+
+test('isGrantableTo: a sub-Archon rank-role takes owner powers, a custom role does not', () => {
+  const metic = { is_system: true, seeded_rank: 'metic' };
+  const archon = { is_system: true, seeded_rank: 'archon' };
+  const custom = { is_system: false, seeded_rank: null };
+
+  // The widening: an in-app archon power reaches a rank-role, never a custom one.
+  for (const k of ['governance.manage', 'builder.rank.set', 'version.close']) {
+    assert.equal(cat.isGrantableTo(k, metic), true, `${k} → metic rank-role`);
+    assert.equal(cat.isGrantableTo(k, custom), false, `${k} → custom role must stay refused`);
+  }
+  // Operational keys reach both.
+  assert.equal(cat.isGrantableTo('idea.triage', metic), true);
+  assert.equal(cat.isGrantableTo('idea.triage', custom), true);
+  // The two walls that did NOT move.
+  for (const k of [...cat.substrateKeys(), ...cat.principalKeys()]) {
+    assert.equal(cat.isGrantableTo(k, metic), false, `${k} must stay non-grantable to every role`);
+    assert.equal(cat.isGrantableTo(k, custom), false, `${k} must stay non-grantable to every role`);
+  }
+  // The Archon role takes nothing — it already holds everything, and that
+  // immutability is what makes lockout unreachable from the tab.
+  for (const k of permissionKeys()) {
+    assert.equal(cat.isGrantableTo(k, archon), false, `${k} → archon role must be refused`);
+  }
+});
+
+test('isGrantableTo fails closed on every unrecognised input', () => {
+  assert.equal(cat.isGrantableTo('idea.triage', null), false);
+  assert.equal(cat.isGrantableTo('idea.triage', undefined), false);
+  assert.equal(cat.isGrantableTo('idea.triage', 'metic'), false, 'a bare string is not a role row');
+  assert.equal(cat.isGrantableTo('nope.not.a.key', { is_system: true, seeded_rank: 'metic' }), false);
+  // A system role claiming a rank the ladder does not define resolves to nothing
+  // rather than to "not archon, therefore editable".
+  assert.equal(cat.isGrantableTo('idea.triage', { is_system: true, seeded_rank: 'wizard' }), false);
+  assert.equal(cat.isGrantableTo('idea.triage', { is_system: true, seeded_rank: null }), false);
+});
+
 test('the four rank-roles exist; seed keys all reference real permissions', () => {
   assert.deepEqual(Object.keys(RANK_ROLE_SEED).sort(), [...RANK_ORDER].sort());
   const all = new Set(permissionKeys());

package/tests/governance_routes.mjs

@@ -11,11 +11,13 @@
 //
 //   2. Real in-process HTTP through the actual router: express app + the real
 //      requirePermission gate resolving a STUB `governance` port on the seam,
-//      db sibling monkeypatched by property. What matters (ADR 0151 §2):
-//      system permissions are rejected as NON-GRANTABLE server-side, seeded
-//      rank-roles are immutable through this API (their grants derive from
-//      floors; their assignment derives from rank — R95b), and every route
-//      denies without the `governance.manage` grant.
+//      db sibling monkeypatched by property. What matters (ADR 0151 §2, as
+//      amended by ADR 0172): a system permission is rejected as NON-GRANTABLE to
+//      a CUSTOM role; the three sub-Archon rank-roles ARE grant-editable (and the
+//      tests assert that, so a later tightening can't quietly re-close the owner's
+//      lever); the ARCHON rank-role and every SUBSTRATE key stay refused; rank-role
+//      ASSIGNMENT is still rank-derived (R95b); and every route denies without the
+//      `governance.manage` grant.
 //
 // Run:  node tests/governance_routes.mjs
 
@@ -55,6 +57,7 @@ test('the routes file declares the full R110 surface', () => {
     'POST /governance/roles',
     'PUT /governance/roles/:roleKey/permissions/:permissionKey',
     'DELETE /governance/roles/:roleKey/permissions/:permissionKey',
+    'POST /governance/roles/:roleKey/reset',
     'POST /governance/assignments',
     'DELETE /governance/assignments/:builderId/:roleKey',
   ];
@@ -98,10 +101,19 @@ const calls = [];
 const stub = {
   listRolesWithGrants: async () => [{ role_key: 'metic', label: 'Metic', description: null, is_system: true, seeded_rank: 'metic', created_by: null, created_at: 't', permissions: ['task.create'] }],
   listAssignments: async () => [{ builder_id: 7, github_login: 'x', display_name: 'X', rank: 'metic', role_key: 'metic', role_label: 'Metic', is_system: true, seeded_rank: 'metic', assigned_by: null, assigned_at: 't' }],
-  getRoleByKey: async (k) => (k === 'missing' ? null : { role_key: k, label: k, is_system: k === 'metic' || k === 'archon', seeded_rank: (k === 'metic' || k === 'archon') ? k : null }),
+  // Every rank name is a seeded rank-role; anything else is a custom one. Keyed off
+  // the catalog's ladder rather than a hand-listed pair, so a rank added to
+  // RANK_ORDER is exercised here instead of quietly falling through as "custom".
+  getRoleByKey: async (k) => (k === 'missing' ? null : {
+    role_key: k,
+    label: k,
+    is_system: catalog.RANK_ORDER.includes(k),
+    seeded_rank: catalog.RANK_ORDER.includes(k) ? k : null,
+  }),
   createRole: async (a) => ({ role_key: a.roleKey, label: a.label, description: a.description ?? null, is_system: false, seeded_rank: null, created_by: a.createdBy, created_at: 't' }),
   grantRolePermission: async () => true,
   revokeRolePermission: async () => true,
+  resetRoleGrants: async ({ permissionKeys }) => permissionKeys.length,
   assignRole: async () => true,
   unassignRole: async () => true,
 };
@@ -259,10 +271,37 @@ test('PUT grant: an unknown permission fails closed', async () => {
   assert.equal(r.json.error.code, 'unknown_permission');
 });
 
-test('PUT grant: a seeded rank-role is immutable (grants derive from floors)', async () => {
+test('PUT grant: a sub-Archon rank-role is EDITABLE (ADR 0172)', async () => {
   const r = await call('PUT', '/governance/roles/metic/permissions/idea.triage');
+  assert.equal(r.status, 200);
+  const c = calls.find(([k]) => k === 'grantRolePermission');
+  assert.deepEqual(c[1], { roleKey: 'metic', permissionKey: 'idea.triage' });
+});
+
+test('PUT grant: an in-app owner power CAN go to a rank-role but never to a custom one', async () => {
+  const rank = await call('PUT', '/governance/roles/metic/permissions/builder.rank.set');
+  assert.equal(rank.status, 200, 'the owner may delegate an in-app Archon power to a rank');
+  const custom = await call('PUT', '/governance/roles/triage-helper/permissions/builder.rank.set');
+  assert.equal(custom.status, 400, 'a custom role keeps the R110 wall');
+  assert.equal(custom.json.error.code, 'permission_not_grantable');
+});
+
+test('PUT grant: a SUBSTRATE key is refused even on a rank-role (it would confer nothing)', async () => {
+  for (const key of ['deploy.push_main', 'path.protected.modify', 'infra.ssh']) {
+    const r = await call('PUT', `/governance/roles/metic/permissions/${key}`);
+    assert.equal(r.status, 400, `${key} must be refused`);
+    assert.equal(r.json.error.code, 'permission_not_grantable');
+    assert.match(r.json.error.details.reason || '', /substrate/i,
+      'the refusal must name the substrate wall, not the custom-role one — the two are a policy choice apart');
+    assert.equal(calls.filter(([k]) => k === 'grantRolePermission').length, 0);
+  }
+});
+
+test('PUT grant: the ARCHON rank-role stays immutable (the lockout guard)', async () => {
+  const r = await call('PUT', '/governance/roles/archon/permissions/idea.triage');
   assert.equal(r.status, 403);
-  assert.equal(r.json.error.code, 'seeded_role_immutable');
+  assert.equal(r.json.error.code, 'archon_role_immutable');
+  assert.equal(calls.filter(([k]) => k === 'grantRolePermission').length, 0);
 });
 
 test('PUT grant: an unknown role 404s', async () => {
@@ -278,10 +317,31 @@ test('DELETE grant revokes without consulting the catalog (stale keys stay remov
   assert.deepEqual(c[1], { roleKey: 'triage-helper', permissionKey: 'some.retired.key' });
 });
 
-test('DELETE grant on a seeded rank-role is refused like the PUT', async () => {
-  const r = await call('DELETE', '/governance/roles/archon/permissions/idea.triage');
-  assert.equal(r.status, 403);
-  assert.equal(r.json.error.code, 'seeded_role_immutable');
+test('DELETE grant: revocable on a sub-Archon rank-role, refused on the Archon one', async () => {
+  const metic = await call('DELETE', '/governance/roles/metic/permissions/idea.triage');
+  assert.equal(metic.status, 200, 'taking a permission away from a rank is the other half of editable');
+
+  const archon = await call('DELETE', '/governance/roles/archon/permissions/idea.triage');
+  assert.equal(archon.status, 403);
+  assert.equal(archon.json.error.code, 'archon_role_immutable');
+  assert.equal(calls.filter(([k]) => k === 'revokeRolePermission').length, 0);
+});
+
+// --- reset (ADR 0172) --------------------------------------------------------
+
+test('POST reset: a rank-role goes back to its floor-derived catalog seed', async () => {
+  const r = await call('POST', '/governance/roles/thetes/reset');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.seeded_rank, 'thetes');
+  const c = calls.find(([k]) => k === 'resetRoleGrants');
+  assert.deepEqual([...c[1].permissionKeys].sort(), [...catalog.seedForRank('thetes')].sort());
+});
+
+test('POST reset: refused on a custom role (no catalog default to return to)', async () => {
+  const r = await call('POST', '/governance/roles/triage-helper/reset');
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'role_has_no_default');
+  assert.equal(calls.filter(([k]) => k === 'resetRoleGrants').length, 0);
 });
 
 // --- assignments -------------------------------------------------------------