@bongos/core 1.18.0 → 1.18.18

package/src/bongos/permission-path-check.js

@@ -9,8 +9,8 @@
 // permission-sensitive path" a DETECTABLE, GATEABLE event — exactly the way
 // route-rank-check.js makes "an ungated write route" detectable.
 //
-// This module is PURE and dependency-free (no fs, no pg, no network) so it can
-// run in three places with identical logic:
+// This module is PURE and dependency-free (no pg, no network, no require of any
+// other repo module) so it can run in three places with identical logic:
 //   1. the LOCAL pre-push git hook (scripts/gds/hooks/pre-push.js) — fast,
 //      cooperative, blocks the honest builder before the push leaves the box;
 //   2. the GRADER pre-pass (modules/grading/grader.js) — folds a finding into the panel
@@ -25,6 +25,9 @@
 
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
+
 // Rank → tier. MUST mirror REQUIRES_RANK_TIER in src/bongos/db.js. We keep a LOCAL
 // copy (not an import) so this module stays dependency-free for the client-side
 // pre-push hook; tests/permission_path.mjs asserts the two never drift (the
@@ -32,87 +35,82 @@
 // reintroduce here).
 const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
 
-// The floor: a builder must be at least this tier to touch a protected path.
-// metic(3) = the first "trusted working rank" (scope/trust grants begin here).
-// xenos(1) and thetes(2) are below it — sandbox + graduated-newcomer.
-const MIN_TIER = RANK_TIER.metic; // 3
-
-// Permission-sensitive paths. A diff from a sub-Metic builder that touches ANY
-// of these is a blocker. Glob rules (see globToRegExp): a trailing '/' matches
-// the whole subtree; '**' matches across '/'; '*' matches within one segment.
+// ── the protected-surface REGISTRY (BV1.R101, ADR 0151 §4) ──────────────────
+//
+// GOVERNANCE OWNS THE DATA; THE SUBSTRATE STAYS THE ENFORCER. Which paths are
+// protected, at what rank floor, mapped to which `system: true` catalog
+// permission, is governance-owned data in
+// modules/governance/protected-surfaces.json — no longer a constant baked into
+// this file. Re-mapping a floor there is a POLICY edit. It cannot move
+// enforcement into the app: the three layers above (git pre-push hook, grader
+// pre-pass, post-push main audit) plus gate-review.js and the goal-scope check
+// read the registry out of band — no DB, no server, no HTTP — and remain the
+// authority (ADR 0043). Making the request path the enforcer is the exact
+// regression this task exists to prevent.
+//
+// WHY A REPO FILE AND NOT A DB QUERY: the enforcers run where there is no
+// database and no server (a git hook on a laptop, a CI job). The registry's
+// canonical form must therefore be SYNCHRONOUSLY loadable from the checkout. A
+// DB-backed override belongs to the governance tab, layered on top — never a
+// dependency of the hook.
+//
+// WHY `fs` AND NOT `require`: ADR 0083's one-way rule forbids core from
+// require-ing a MODULE's code (a module's behavior + enable/disable state must
+// never be something the kernel depends on), and scripts/gds/fitness.js enforces
+// that on `require` edges. This is not code — it is a static declarative data
+// file that ships inside the core package next to this file (modules/ ships with
+// @bongos/core, ADR 0108 §1). The sibling trust primitive route-rank-check.js
+// already reads modules/*/routes/*.js off disk the same way, to rank-gate them.
+// Code still flows ONE way only: modules/governance/protected-surfaces.js →
+// src/module-api.js → this matcher. Nothing in core requires the module.
 //
-// Scope rationale: the rank/permission/ship-grade/deploy machinery, DB schema
-// migrations, the server route + middleware layer that carries the gates, and
-// the trust-boundary documentation. Game/art/UI/docs work — what newcomers
-// actually build — is deliberately NOT here. Metic+ is unaffected entirely.
-const PROTECTED_GLOBS = [
-  // --- the rank ladder + authorization machinery ---
-  'src/bongos/auth.js',                 // requireBuilder / requireRank definitions
-  'src/bongos/db.js',                   // rank tiers, REQUIRES_RANK_TIER, the CASE niels edited
-  'src/bongos/route-rank-check.js',     // the route-gate auditor
-  'src/bongos/permission-path-check.js',// THIS gate (self-protect)
-  'src/bongos/middleware/',             // audit + any auth middleware
-  'src/bongos/routes/',                 // routes carry the requireRank gates
-  'modules/lifecycle/routes/',       // BV1.R86: the lifecycle routes (tasks/claims/versions/goals/deps/done-when/gate-approvals) carved out of src/bongos/routes/ — the gates follow the routes
-  'src/bongos/routes.js',               // #863-followup: the route MOUNT table (a new ungated route lands here)
-  'server.js',                       // #863-followup: the Express/Colyseus entrypoint — wires every router + host routing
-  // --- rank-gated source/box access (the crown-jewels clone decision) ---
-  // These moved into the dev-box module (BV1.R43, ADR 0083) but stay protected:
-  // they decide who gets a full source clone + mint the credential, sensitive by
-  // nature wherever they live. (routes/box.js's rank gates are covered separately
-  // by the route-rank fitness check, which scans modules/*/routes/.)
-  'modules/dev-box/boxes.js',        // #863-followup: boxScopeForRank / provision floor — decides who gets a full source clone
-  'modules/dev-box/box-access.js',   // #863-followup: decideSourceAccess (rank → starter|full source)
-  'modules/dev-box/box-credential.js', // #863-followup: mints the box source credential
-  // --- the ship / grade / deploy pipeline ---
-  'modules/grading/grader.js',       // BV1.R73: grading carved to modules/grading/ — the protected glob follows the file
-  'modules/grading/grader-workers/', // #863-followup: the adversarial panel (Narc/Hacker/Quality/Efficiency) — blunting these blunts the gate
-  'modules/grading/grader-rubric.json', // task 1139 (ADR 0058): the grader's scoring rubric — blunting it blunts the grade gate
-  'scripts/gds/ship.js',
-  'scripts/gds/confirm.js',
-  'scripts/gds/merge-mode.js',
-  'scripts/gds/ci-grade.js',         // task 1143 (ADR 0058): CI grade-gate driver — steers the grade check
-  'scripts/gds/grade-smoke.js',      // task 1143 (ADR 0058): grade-smoke driver
-  'scripts/gds/conductor-dispatch.js',// task 1143 (ADR 0058): mid-flight grader dispatch
-  'scripts/gds/main-audit.js',       // the post-push audit (self-protect)
-  'scripts/gds/push-main.js',        // the sanctioned main-push (carries the override)
-  'scripts/gds/run-unit-tests.js',   // task 1139 (ADR 0058): the unit-gate test SELECTOR — muting tests here blunts the CI gate
-  'scripts/gds/gate-review.js',      // task 1139 (ADR 0058): the automatic gatekeeper itself (self-protect)
-  'scripts/gds/setup.js',            // /builder-setup — installs the pre-push hook
-  'scripts/gds/install-git-hooks.js',// the hook installer (self-protect)
-  'scripts/gds/hooks/',              // the git hooks themselves (self-protect)
-  'scripts/gds/cli-lib.js',          // session/token + apiCall the gate relies on
-  'scripts/migrate.sh',              // #863-followup: applies migrations on deploy
-  'scripts/deploy/',                 // task 1139 (ADR 0058): the deploy scripts run on the droplet at deploy
-  // BV1.R86: the ship-pipeline libs carved to modules/lifecycle/ — the protected
-  // globs follow the files (the grading-carve precedent above). github-push is the
-  // server-mediated branch publish (ADR 0055); conflict-resolve/publish-reconciler
-  // self-heal + land merges; merge-lock/ship-preflight serialize + preflight a ship.
-  'modules/lifecycle/merge-lock.js',
-  'modules/lifecycle/ship-preflight.js',
-  'modules/lifecycle/github-push.js',
-  'modules/lifecycle/conflict-resolve.js',
-  'modules/lifecycle/publish-reconciler.js',
-  // --- schema: migrations are never newcomer work ---
-  'migrations/',
-  // --- the deploy substrate ---
-  'infra/',
-  '.github/',                        // #863-followup: CI workflows (deploy-prod.yml, grade gate, secrets-scan) are the pipeline
-  'CODEOWNERS',                      // task 1139 (ADR 0058): the code-owner gate list itself
-  'config/deploy.json',              // task 1139 (ADR 0058): the laptop/ci/bypass deploy switch
-  'package.json',                    // #863-followup: npm scripts + prepare/lifecycle hooks run during install/CI
-  'package-lock.json',               // task 1143 (ADR 0058): the resolved supply chain npm ci installs on the droplet
-  // --- the hooks the gate is DELIVERED through (self-protect Layer 1) ---
-  '.husky/',                         // #863-followup: pre-push (this gate) + pre-commit (secrets guard)
-  // --- the trust-boundary documentation + methodology core ---
-  'docs/canonical-permissions.md',
-  'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
-  'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md', // #863-followup: this fix's own ADR
-  'CLAUDE.md',
-  // --- local automation that could weaken a gate ---
-  '.claude/hooks/',
-  '.claude/settings.json',
-];
+// FAIL-CLOSED: a missing/empty/malformed registry THROWS. It never degrades to
+// "nothing is protected" — an unreadable registry is a broken install, not an
+// opted-out module.
+//
+// Resolved from __dirname (this file is <coreRoot>/src/bongos/) rather than via
+// instance-config so the load keeps zero repo imports and works in a bare git
+// hook.
+const REGISTRY_PATH = path.join(__dirname, '..', '..', 'modules', 'governance', 'protected-surfaces.json');
+
+function loadRegistry(file) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`protected-surface registry unreadable at ${file}: ${e.message}. Refusing to run with an empty protected set (ADR 0043).`);
+  }
+  const surfaces = Array.isArray(raw && raw.surfaces) ? raw.surfaces : null;
+  if (!surfaces || surfaces.length === 0) {
+    throw new Error(`protected-surface registry ${file} declares no surfaces. Refusing to run with an empty protected set (ADR 0043).`);
+  }
+  const defaultFloor = raw.floor;
+  const defaultPermission = raw.permission;
+  return Object.freeze(surfaces.map((s) => {
+    const glob = s && s.glob;
+    const floor = (s && s.floor) || defaultFloor;
+    const permission = (s && s.permission) || defaultPermission;
+    if (typeof glob !== 'string' || !glob) throw new Error(`protected-surface registry ${file}: a surface is missing 'glob'`);
+    if (!RANK_TIER[floor]) throw new Error(`protected-surface registry ${file}: surface "${glob}" has an unknown floor "${floor}"`);
+    if (typeof permission !== 'string' || !permission) throw new Error(`protected-surface registry ${file}: surface "${glob}" maps to no permission`);
+    return Object.freeze({ glob, floor, permission, group: (s && s.group) || null, why: (s && s.why) || null });
+  }));
+}
+
+// The registry as loaded: [{ glob, floor, permission, group, why }] in file order.
+const PROTECTED_SURFACES = loadRegistry(REGISTRY_PATH);
+
+// The glob list, DERIVED from the registry. Kept as an export because it is the
+// long-standing single source every consumer already reads (module-scope-map,
+// gate-review, publish-manifest, search-ingest-md, sequence) — those keep
+// working unchanged and are now registry-backed by construction.
+const PROTECTED_GLOBS = PROTECTED_SURFACES.map((s) => s.glob);
+
+// The floor a builder must clear to touch a protected path, DERIVED from the
+// registry (the lowest floor any surface declares — 'metic' today). Exported
+// because main-audit.js and modules/lifecycle/routes/tasks.js gate on it; the
+// per-surface floor below is what actually decides a hit.
+const MIN_TIER = Math.min(...PROTECTED_SURFACES.map((s) => RANK_TIER[s.floor]));
 
 const SPECIALTY =
   'deterministic: a builder below Metic must not modify rank / permission / ship-grade / deploy / migration surfaces (ADR 0016, SEC #863)';
@@ -142,31 +140,54 @@ function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-const COMPILED = PROTECTED_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
+const COMPILED = PROTECTED_SURFACES.map((s) => ({ ...s, re: globToRegExp(s.glob) }));
 
 // Normalize a path the way git reports it (forward slashes, no leading ./).
 function normalize(p) {
   return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim();
 }
 
-// Which of `files` are permission-sensitive? Returns [{ file, glob }].
+// Which of `files` are permission-sensitive? Returns
+// [{ file, glob, floor, permission }] — floor + permission come straight from the
+// registry entry that matched, so a governance re-map flows through every caller.
 function matchProtected(files) {
   const out = [];
   for (const raw of files || []) {
     const f = normalize(raw);
     if (!f) continue;
     const hit = COMPILED.find((c) => c.re.test(f));
-    if (hit) out.push({ file: f, glob: hit.glob });
+    if (hit) out.push({ file: f, glob: hit.glob, floor: hit.floor, permission: hit.permission });
   }
   return out;
 }
 
+// The registry entry governing `file`, or null when the path is unprotected.
+function surfaceFor(file) {
+  const f = normalize(file);
+  const hit = f ? COMPILED.find((c) => c.re.test(f)) : null;
+  return hit ? { glob: hit.glob, floor: hit.floor, permission: hit.permission, group: hit.group, why: hit.why } : null;
+}
+
+// The rank floor governing `file` ('metic' today), or null when unprotected.
+function floorFor(file) {
+  const s = surfaceFor(file);
+  return s ? s.floor : null;
+}
+
+// The system:true catalog permission `file` maps to, or null when unprotected.
+function permissionFor(file) {
+  const s = surfaceFor(file);
+  return s ? s.permission : null;
+}
+
 function tierOf(rank) {
   return RANK_TIER[rank] ?? null; // null = unknown rank
 }
 
-// Is this rank below the protected-path floor? Unknown ranks are treated as
-// NOT-below here (no finding) — see checkPermissionPaths for why unknown must
+// Is this rank below the registry's LOWEST protected-path floor? A coarse
+// "could this rank be blocked by anything at all" test — main-audit.js uses it
+// after matchProtected has already established a hit. Unknown ranks are treated
+// as NOT-below here (no finding) — see checkPermissionPaths for why unknown must
 // fail OPEN at the grader layer (the authoritative audit, layer 3, owns the
 // unknown/dishonest case and reads the real rank from the DB).
 function isBelowFloor(rank) {
@@ -184,21 +205,26 @@ function isBelowFloor(rank) {
 // the layer that fails-closed on the dishonest path.
 function checkPermissionPaths({ changedFiles, builderRank } = {}) {
   const protectedHits = matchProtected(changedFiles);
-  const below = isBelowFloor(builderRank);
+  const tier = tierOf(builderRank);
   const findings = [];
-  if (below && protectedHits.length > 0) {
-    for (const h of protectedHits) {
-      findings.push({
-        severity: 'blocker',
-        file: h.file,
-        glob: h.glob,
-        summary:
-          `${h.file} is a permission-sensitive surface (matches \`${h.glob}\`). `
-          + `Builder rank '${builderRank}' is below Metic and may not modify the rank / permission / `
-          + `ship-grade / deploy / migration machinery (ADR 0016, SEC #863). `
-          + `If this change is genuinely needed, an Archon must own it.`,
-      });
-    }
+  for (const h of protectedHits) {
+    // Decided against the hit's OWN registry floor, not a global constant — that
+    // is what makes "the governance tab can re-map the floor" real. Every surface
+    // floors at 'metic' today, so this is identical to the previous global test.
+    if (tier === null || tier >= RANK_TIER[h.floor]) continue;
+    const floorLabel = h.floor.charAt(0).toUpperCase() + h.floor.slice(1);
+    findings.push({
+      severity: 'blocker',
+      file: h.file,
+      glob: h.glob,
+      floor: h.floor,
+      permission: h.permission,
+      summary:
+        `${h.file} is a permission-sensitive surface (matches \`${h.glob}\`). `
+        + `Builder rank '${builderRank}' is below ${floorLabel} and may not modify the rank / permission / `
+        + `ship-grade / deploy / migration machinery (ADR 0016, SEC #863). `
+        + `If this change is genuinely needed, an Archon must own it.`,
+    });
   }
   return {
     ok: findings.length === 0,
@@ -215,8 +241,11 @@ function checkPermissionPaths({ changedFiles, builderRank } = {}) {
 function toWorkerResult(result) {
   const verdict = result.hardFail ? 'fail' : 'pass';
   const n = result.findings.length;
+  // Floor label comes from the findings (registry data), not a hardcoded 'Metic'.
+  const floor = n > 0 ? result.findings[0].floor : null;
+  const floorLabel = floor ? floor.charAt(0).toUpperCase() + floor.slice(1) : 'the floor';
   const header = verdict === 'fail'
-    ? `Permission-Path — FAIL (rank '${result.builderRank}' below Metic touched ${n} protected path(s))`
+    ? `Permission-Path — FAIL (rank '${result.builderRank}' below ${floorLabel} touched ${n} protected path(s))`
     : `Permission-Path — PASS`;
   const body = result.findings.map((f) => `  [${f.severity}] ${f.file} — ${f.summary}`).join('\n');
   return {
@@ -238,9 +267,14 @@ module.exports = {
   RANK_TIER,
   MIN_TIER,
   PROTECTED_GLOBS,
+  PROTECTED_SURFACES,
+  REGISTRY_PATH,
   SPECIALTY,
   globToRegExp,
   matchProtected,
+  surfaceFor,
+  floorFor,
+  permissionFor,
   tierOf,
   isBelowFloor,
   checkPermissionPaths,

package/src/bongos/repo-info.js

@@ -44,26 +44,61 @@ function loadFromEnv() {
   return null;
 }
 
-function loadFromGit() {
+// The directory this file's package occupies: <root>/src/bongos -> <root>. In the core
+// dev checkout that is the repo root; installed, it is node_modules/@bongos/core.
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+
+// Same directory? Normalizes separator style (git prints POSIX separators even on
+// Windows) and surrounding whitespace, and matches the platform's case rules.
+function sameDir(a, b) {
+  if (!a || !b) return false;
+  const norm = (p) => {
+    const abs = path.resolve(String(p).trim());
+    return process.platform === 'win32' ? abs.toLowerCase() : abs;
+  };
+  return norm(a) === norm(b);
+}
+
+// Resolve the remote ONLY when this package IS the git repo, never a repo found by
+// walking up out of it.
+//
+// git discovery searches ANCESTORS of cwd. In the core dev checkout PACKAGE_ROOT is the
+// repo root, so `git remote get-url origin` answers correctly. But on a live instance
+// (ADR 0140) the hub runs from node_modules/@bongos/core, which is not a repo — so git
+// climbed out of the package, found the enclosing INSTANCE repo, and returned its origin.
+// That silently bound a DIFFERENT repo than the one the core publishes to, so every
+// publish call 404'd against a repo the builder had no access to.
+//
+// Anchor the answer: ask git for its toplevel first and require it to EQUAL the directory
+// we probed. If it differs, the repo is someone else's — return null so loadRepoInfo falls
+// through to the env pin (<PREFIX>_GITHUB_OWNER/_REPO) or to an explicit no_repo_info. An
+// error is strictly better than a wrong answer here: a misbind produces confident 404s
+// that are hard to trace, while the error is printed verbatim by the publish-reconciler's
+// boot line and names its own cure.
+function loadFromGit(deps = {}) {
+  const exec = deps.execSync || execSync;
+  const root = deps.packageRoot || PACKAGE_ROOT;
+  const opts = { cwd: root, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'pipe'] };
   try {
-    const remote = execSync('git remote get-url origin', {
-      cwd: path.resolve(__dirname, '..', '..'),
-      encoding: 'utf8',
-      timeout: 2000,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return parseRemote(remote);
+    const toplevel = exec('git rev-parse --show-toplevel', opts);
+    if (!sameDir(toplevel, root)) return null;
+    return parseRemote(exec('git remote get-url origin', opts));
   } catch (_) {
     return null;
   }
 }
 
-function loadRepoInfo() {
+// `deps` is the test seam (execSync / packageRoot); production calls this with no args.
+function loadRepoInfo(deps = {}) {
   if (cached) return cached;
   const branch = ic.resolveEnv('GITHUB_BRANCH') || 'main';
-  const parsed = loadFromEnv() || loadFromGit();
+  const parsed = loadFromEnv() || loadFromGit(deps);
   if (!parsed) {
-    cached = { error: 'no_repo_info', detail: 'git remote origin not parseable and <PREFIX>_GITHUB_OWNER/REPO unset' };
+    cached = {
+      error: 'no_repo_info',
+      detail:
+        'git remote origin not resolvable from this package (an installed core does not sit inside the repo it publishes to) and <PREFIX>_GITHUB_OWNER/REPO unset',
+    };
     return cached;
   }
   const base = `https://github.com/${parsed.owner}/${parsed.repo}`;
@@ -87,5 +122,6 @@ function _resetCacheForTests() {
 module.exports = {
   loadRepoInfo,
   parseRemote,
+  loadFromGit, // exported for unit tests — the anchor rule is the whole fix
   _resetCacheForTests,
 };