@bongos/core 1.18.3 → 1.18.18

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

@@ -10,10 +10,12 @@
 // must classify to a KNOWN rank — instead of diffing against a frozen snapshot
 // (the old canonical-routes.json approach, which cried false drift whenever the
 // route set legitimately grew). Classification is STRUCTURAL: a route is gated
-// when its middleware chain carries requireRank/requireBuilder, OR it bears an
-// explicit `rank:` annotation. So an intentionally-public route is fine — it
-// just has to SAY so. A route the parser cannot classify ('unknown') means the
-// system can't verify it's protected, which is a finding:
+// when its middleware chain carries requireRank/requireBuilder/requirePermission.
+// A `rank:` annotation is NOT a gate — it is how an intentionally-PUBLIC route
+// SAYS so (`rank: public`). A comment claiming a privileged rank over a route with
+// no middleware certifies nothing, and is a finding of its own (BV1.R109d). A route
+// the parser cannot classify ('unknown') means the system can't verify it's
+// protected, which is likewise a finding:
 //   - write method (POST/PUT/PATCH/DELETE) → 'blocker' → hard FAIL on its own.
 //   - read method (GET) → 'major' → 'concerns'; the Hacker adjudicates intent.
 //
@@ -42,6 +44,128 @@ const KNOWN_RANKS = new Set(['public', 'any-builder', 'metic+archon', 'archon',
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 const SPECIALTY = 'deterministic: every src/bongos/routes/ route must classify to a known rank (ADR 0016)';
 
+// ── permission gates (BV1.R97/R109, ADR 0151) ────────────────────────────────
+//
+// A migrated route gates on PERMISSION ATOMS — auth.requirePermission('backup.manage')
+// — instead of a rank. `requirePermission` must mount AFTER `requireBuilder`, so before
+// this arm existed a migrated route fell through to the requireBuilder branch and
+// classified 'any-builder': a downgrade that reads as legitimate. To classify it
+// honestly the auditor needs each atom's rank FLOOR (the rank that holds it under
+// governance's compat seed), which is declared exactly once — in
+// modules/governance/catalog.js. There is deliberately NO second permission→rank table
+// here; a second list is a list that drifts.
+//
+// READ AS DATA, NOT require()d. ADR 0083's one-way rule forbids core from importing a
+// MODULE's code (scripts/gds/fitness.js enforces it on require edges) and this file is
+// core, so we parse the catalog's `floor:` declarations out of its SOURCE — the same
+// technique this file already applies to modules/*/routes/*.js, and the posture the
+// sibling trust primitive permission-path-check.js takes with
+// modules/governance/protected-surfaces.json. Like those, it runs with no DB, no
+// server and no module loader, so it works inside a git hook.
+//
+// LAZY + FAIL-CLOSED. Loaded on first use, so an instance whose routes carry no
+// permission gate and no permission pin never reads it. An unreadable or empty catalog
+// THROWS rather than degrading to "every atom is unknown"; an atom the catalog does not
+// define classifies 'unknown', which hard-fails a write route.
+const CATALOG_PATH = path.join(MODULES_DIR, 'governance', 'catalog.js');
+// low → high authority. Mirrors catalog.js RANK_ORDER; the parse below rejects any
+// floor outside it, so a divergence surfaces as 'unknown' (loud) rather than as trust.
+const PERMISSION_RANK_ORDER = ['xenos', 'thetes', 'metic', 'archon'];
+// A permission floor → the rank LABEL this auditor speaks. The vocabulary has no
+// 'thetes' tier (requireRank('xenos') has always collapsed to 'any-builder' too), so
+// both sub-Metic floors read 'any-builder': the label may UNDER-report strictness,
+// never over-report it.
+const FLOOR_LABEL = { xenos: 'any-builder', thetes: 'any-builder', metic: 'metic+archon', archon: 'archon' };
+// How strict each label is, for combining a permission gate with a rank gate that sits
+// on the same route (they AND, so the stricter one is the route's real floor).
+const LABEL_STRICTNESS = { public: 0, 'any-builder': 1, 'metic+archon': 2, archon: 3, 'bfg-principal': 4 };
+// A pin value written in permission terms: 'perm:<key>[,<key>…]' (see EXPECTED_RANKS).
+const PERM_PIN_PREFIX = 'perm:';
+
+// key → floor ('xenos'|'thetes'|'metic'|'archon'|null) from the catalog SOURCE. One
+// catalog entry per line is the shape catalog.js has and its own load-time invariants
+// keep; an entry this misses simply never resolves, which fails closed.
+function parsePermissionFloors(text) {
+  const floors = new Map();
+  for (const line of String(text).split('\n')) {
+    const k = /\bkey:\s*'([^']+)'/.exec(line);
+    if (!k) continue;
+    const f = /\bfloor:\s*(?:'([a-z]+)'|null)/.exec(line);
+    if (!f) continue;
+    floors.set(k[1], f[1] || null); // f[1] undefined ⇒ floor: null ⇒ a machine principal
+  }
+  return floors;
+}
+
+let _floorsCache = null;
+function permissionFloors(catalogPath = CATALOG_PATH) {
+  const cacheable = catalogPath === CATALOG_PATH; // an explicit path (tests) is never cached
+  if (cacheable && _floorsCache) return _floorsCache;
+  let text;
+  try {
+    text = fs.readFileSync(catalogPath, 'utf8');
+  } catch (e) {
+    throw new Error(`permission catalog unreadable at ${catalogPath}: ${e.message}. `
+      + 'Refusing to classify permission gates with no floor data (ADR 0151).');
+  }
+  const floors = parsePermissionFloors(text);
+  if (floors.size === 0) {
+    throw new Error(`permission catalog ${catalogPath} declares no permissions. `
+      + 'Refusing to classify permission gates against an empty catalog (ADR 0151).');
+  }
+  if (cacheable) _floorsCache = floors;
+  return floors;
+}
+
+// The effective rank label of a requirePermission(...) gate, or 'unknown'.
+//
+// AND semantics (auth.requirePermission holds EVERY named atom), so the gate's floor is
+// the STRICTEST floor among them. Fail-closed to 'unknown' — never to a rank — for:
+//   • no atoms named (a mis-authored gate; requirePermission() 403s everyone anyway)
+//   • an atom the catalog does not define (typo, renamed, deleted): it grants nothing,
+//     so treating it as "gated" would be the exact silent hole this arm exists to close
+//   • a PRINCIPAL atom (floor null — held by no rank-role, only by an exact
+//     builders.system_role). A route wanting one must use requireBfgPrincipal.
+function rankForPermissions(keys, floors = permissionFloors()) {
+  if (!Array.isArray(keys) || keys.length === 0) return 'unknown';
+  let strictest = -1;
+  for (const key of keys) {
+    if (!floors.has(key)) return 'unknown';
+    const idx = PERMISSION_RANK_ORDER.indexOf(floors.get(key)); // null/unknown floor → -1
+    if (idx === -1) return 'unknown';
+    if (idx > strictest) strictest = idx;
+  }
+  return FLOOR_LABEL[PERMISSION_RANK_ORDER[strictest]];
+}
+
+// ── how a guard is REFERENCED in a route's argument list (BV1.R109d) ─────────
+//
+// Core routes call the guards through a namespace (`auth.requireBuilder`); a module
+// reaches the same guards through the published doorway, and may either namespace them
+// (`api.requireBuilder`) or DESTRUCTURE them — `const { requireBuilder } = api` — and
+// pass BARE identifiers. Recognising only the namespaced spelling made 11 correctly
+// gated module routes (modules/platform-identity/routes/*) invisible to the middleware
+// arm; they survived only because their `rank:` comment happened to tell the truth.
+//
+// The bare form is honoured ONLY in ARGUMENT POSITION (directly after `(` or `,`), so
+// the identifier appearing in prose — or inside a `function` handler's body, which the
+// `=> {` truncation below does not cut away — can never be mistaken for a gate.
+const GATE_REF = String.raw`(?:(?:auth|api)\.|[(,]\s*)`;
+const RE_RANK_XENOS = new RegExp(`${GATE_REF}requireRank\\(\\s*['"]xenos['"]`);
+const RE_RANK_METIC_ARCHON = new RegExp(`${GATE_REF}requireRank\\(\\s*['"]metic['"]\\s*,\\s*['"]archon['"]\\s*\\)`);
+const RE_RANK_ARCHON = new RegExp(`${GATE_REF}requireRank\\(\\s*['"]archon['"]\\s*\\)`);
+const RE_BFG_PRINCIPAL = new RegExp(`${GATE_REF}requireBfgPrincipal`);
+const RE_REQUIRE_BUILDER = new RegExp(`${GATE_REF}requireBuilder`);
+const RE_REQUIRE_PERMISSION = new RegExp(`${GATE_REF}requirePermission\\(([^)]*)\\)`);
+
+// The permission atoms a route's middleware list names, or null when it carries no
+// permission gate. `[]` (an empty gate) is DISTINCT from null and resolves 'unknown'.
+function permissionKeysIn(tail) {
+  const m = RE_REQUIRE_PERMISSION.exec(tail);
+  if (!m) return null;
+  return [...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]);
+}
+
 // Expected-rank allowlist for KNOWN privileged routes (#999, red-team residual).
 // The base invariant above only checks a route classifies to SOME known rank —
 // so an accidental DOWNGRADE (an Archon-only route silently dropped to
@@ -59,16 +183,23 @@ const SPECIALTY = 'deterministic: every src/bongos/routes/ route must classify t
 // downgrade-protection; routes not listed still get the base "must classify"
 // check. A key present here that no longer exists in the route set is itself a
 // finding (a privileged route was removed/renamed without updating this pin).
+//
+// A PIN VALUE IS EITHER A RANK LABEL OR AN AUTHORITY ATOM ('perm:<key>[,<key>]' —
+// BV1.R109, ADR 0151). Both forms are satisfied by BOTH gate spellings while
+// R104-R107 migrate `requireRank` call sites to `requirePermission`, so migrating a
+// pinned route no longer forces an edit here. Prefer the permission spelling for the
+// pins whose downgrade is a true authority breach: once governance grows CUSTOM roles
+// the ATOM, not the rank, is the authority, and a rank pin stops describing it.
 const EXPECTED_RANKS = {
   // builder authority — rank + lifecycle status mutation
-  'PATCH /builders/:id/rank': 'archon',
-  'PATCH /builders/:id/status': 'archon',
+  'PATCH /builders/:id/rank': 'perm:builder.rank.set',
+  'PATCH /builders/:id/status': 'perm:builder.status.set',
   // session revocation (kill another builder's / all sessions)
-  'POST /auth/revoke': 'archon',
-  'POST /auth/revoke-all': 'archon',
+  'POST /auth/revoke': 'perm:auth.session.revoke',
+  'POST /auth/revoke-all': 'perm:auth.session.revoke',
   // forensic surfaces
-  'GET /audit-log': 'archon',
-  'GET /builders/roster': 'archon',
+  'GET /audit-log': 'perm:audit_log.read',
+  'GET /builders/roster': 'perm:builder.roster.read',
   // deliberately any-builder (task 1877) — the invite-picker roster (Goals
   // invite control, task 1762) needs every active builder's identity, not just
   // /leaderboard's top-100-by-credits window. Pinned so an accidental
@@ -89,6 +220,10 @@ const EXPECTED_RANKS = {
   'GET /security/docs': 'archon',
   'GET /security/docs/:slug': 'archon',
   'POST /security/docs': 'archon',
+  // The full threat model + defenses inventory (ADR 0020). Same class as the docs
+  // pins above — a silent downgrade puts the defense inventory below the trust line.
+  // Newly VISIBLE in BV1.R109b (declared multi-line, so previously unpinnable).
+  'GET /security/adr': 'metic+archon',
 };
 
 // Module-scoped privileged-rank pins: a privileged route that lives in a FEATURE
@@ -100,6 +235,17 @@ const EXPECTED_RANKS = {
 // box-fleet routes moved here from EXPECTED_RANKS in BV1.R43 / task 1412 — the pins
 // follow the routes; the intent is unchanged: closing/blocking another builder's
 // paid infra, and reading the fleet/cost roster, stay archon-only.)
+//
+// The `ideas` / `memory` / `security` blocks were added in BV1.R109b: their routes are
+// declared multi-line and so were invisible to this auditor until it learned that form
+// — meaning they could never have been pinned. They are pinned by RANK, not by
+// `perm:` atom, deliberately: BV1.R104-R107 are migrating these very files to
+// requirePermission right now, and a rank pin is satisfied by EITHER spelling (a
+// permission gate resolves through the catalog into the same vocabulary), whereas an
+// atom pin would red the build if the migration picks a different atom than guessed.
+// The catalog already declares the atoms each will gate on — `security.report.file`
+// (metic), `security.report.adjudicate` / `idea.ratify` / `memory.read.any` (archon) —
+// so tightening these to `perm:` pins is a clean follow-up once R104-R107 have landed.
 const MODULE_EXPECTED_RANKS = {
   'dev-box': {
     'GET /boxes': 'archon',
@@ -112,10 +258,11 @@ const MODULE_EXPECTED_RANKS = {
   lifecycle: {
     // task authoring / promotion / abandonment. Create + promote re-ranked
     // Archon→Metic+ (ADR 0090): a Metic who can triage ideas may also seed + shape
-    // tasks. Abandon (terminal scope removal) stays Archon.
+    // tasks. Abandon followed (ADR 0152) — a Metic who may author work may retire
+    // it; /promote carries the abandoned→backlog undo at the same rank.
     'POST /tasks': 'metic+archon',
     'POST /tasks/:id/promote': 'metic+archon',
-    'POST /tasks/:id/abandon': 'archon',
+    'POST /tasks/:id/abandon': 'metic+archon',
     // override-request adjudication (lands credit + ship attribution).
     'GET /override-requests': 'archon',
     'POST /override-requests/:id/decide': 'archon',
@@ -185,25 +332,85 @@ const MODULE_EXPECTED_RANKS = {
     'POST /goals/:id/requests/:reqId/withdraw': 'any-builder',
     // criterion confirmation + goal auto-achieve (ADR 0086 §6) — the planner's close loop.
     'POST /done-when/:criterionId/satisfy': 'metic+archon',
-    // runtime criterion create (ADR 0105 gap fix, task 1874) — scope-truth write, Archon-only.
-    'POST /versions/:id/done-when': 'archon',
+    // runtime criterion create (ADR 0105 gap fix, task 1874) — re-ranked Archon→Metic+
+    // (ADR 0154) as the OPEN of the loop `satisfy` above closes. Not a bare widening:
+    // a non-Archon must name a goal they own or manage (authorizeCriterionCreate) on a
+    // planning/building version, so the in-handler wall is load-bearing — and an
+    // unauthorized caller is masked as bad_goal_id. Unsatisfy stays Archon.
+    'POST /versions/:id/done-when': 'metic+archon',
+    // ...and its inverse stays ARCHON. Un-flipping a CONFIRMED criterion rewrites
+    // shipped scope-truth; ADR 0154's whole safety argument is that the backward
+    // ratchet did not move with the create. Previously unpinned — pinned here so a
+    // silent downgrade reds the build (task 1002538).
+    'POST /done-when/:criterionId/unsatisfy': 'archon',
     // gate-surface PR approval from the hall (task 1179, ADR 0058 amendment) — the
     // approve route clears the gate-review hard floor; the list route exposes gate internals.
     'GET /gate-approvals': 'archon',
     'POST /gate-approvals/:pr/approve': 'archon',
   },
+  // Ratifying a criterion proposal WRITES scope-truth (it creates a done-when
+  // criterion). Metic+ may file the proposal; only the Archon may ratify it.
+  ideas: {
+    'POST /inbox/:id/ratify': 'archon',
+  },
+  // Cross-builder memory READS — the counterpart to the BFG cross-builder WRITE the
+  // KNOWN_RANKS note above already protects. A downgrade here breaks the memory
+  // isolation invariant: any builder could read every other builder's memory.
+  memory: {
+    'GET /memory/builders/:builderId/files': 'archon',
+    'GET /memory/builders/:builderId/file': 'archon',
+  },
+  // Vulnerability-report intake + adjudication. The four adjudication routes move a
+  // PAYOUT (confirm awards drachmae, dispute clears it), and the list route exposes
+  // every builder's exploit detail — the same "attacker cookbook" argument as the
+  // /security/docs pins. Intake is pinned 'metic+archon' rather than archon because it
+  // is DELIBERATELY Metic+ (the rank gate is the bounty noise-floor, V3.R63): the pin
+  // catches an accidental widening to Xenos as loudly as it catches a gate removal.
+  security: {
+    'POST /security/reports': 'metic+archon',
+    'GET /security/reports': 'archon',
+    'POST /security/reports/:id/confirm': 'archon',
+    'POST /security/reports/:id/dispute': 'archon',
+    'POST /security/reports/:id/fix': 'archon',
+    'POST /security/reports/:id/link-fix': 'archon',
+  },
 };
 
-// Classify one route's rank from the source lines and the declaration index.
+// The rank a route's RANK middleware implies, or null when it carries none.
+// Every spelling GATE_REF above accepts counts: namespaced (`auth.`/`api.`) or the
+// bare identifier a module gets by destructuring the doorway.
+function rankFromRankGate(tail) {
+  if (RE_RANK_XENOS.test(tail)) return 'any-builder';
+  if (RE_RANK_METIC_ARCHON.test(tail)) return 'metic+archon';
+  if (RE_RANK_ARCHON.test(tail)) return 'archon';
+  // Matched BEFORE the requireBuilder branch in THIS classifier's if-chain (not
+  // a statement about middleware execution order — the actual route chain runs
+  // requireBuilder → requireBfgPrincipal). The BFG write route carries both;
+  // requireBuilder authenticates, requireBfgPrincipal narrows to the one service
+  // principal, and the principal gate is the load-bearing one we want recorded.
+  if (RE_BFG_PRINCIPAL.test(tail)) return 'bfg-principal';
+  if (RE_REQUIRE_BUILDER.test(tail)) return 'any-builder';
+  return null;
+}
+
+// Classify one route's gate from the source lines and the declaration index.
+// Returns { rank, perms, via } — `perms` is the permission atoms the route names, or
+// null when it carries no permission gate; `via` is the PROVENANCE of the label:
+// 'middleware' (a real gate), 'annotation' (only a `rank:` comment), or null (neither).
 //   1. The middleware chain on the declaration line + next 20 lines (captures
-//      multi-line declarations) — requireRank/requireBuilder is authoritative.
+//      multi-line declarations) — requirePermission/requireRank/requireBuilder is
+//      authoritative.
 //   2. Otherwise a `rank:` annotation anywhere in the CONTIGUOUS comment block
 //      immediately above the declaration. Scanning the whole block (not a fixed
 //      5-line window) is the fix for routes like GET /public/repo-info, whose
 //      annotation sits atop a 6-line comment — just out of the old window.
 //   3. Neither → 'unknown'. An annotation whose value isn't a known rank (typo)
 //      is likewise 'unknown' — that surfaces the typo rather than trusting it.
-function classifyRank(lines, i) {
+//
+// `via` is what keeps a COMMENT from passing as a trust decision (BV1.R109d): callers
+// treat an 'annotation' label as a claim, not a verified gate. Only `rank: public` is
+// a claim a comment can honestly make on its own — asserting nothing is protected.
+function classifyGate(lines, i, { floors } = {}) {
   const window = lines.slice(i, i + 20).join('\n');
   // Only the route's own MIDDLEWARE LIST decides its rank — not its handler body.
   // The middleware are the args before the handler function; the handler opens
@@ -216,21 +423,22 @@ function classifyRank(lines, i) {
   // (e.g. a `function` handler), fall back to the full window — prior behaviour.
   const handlerAt = window.search(/=>\s*\{/);
   const tail = handlerAt === -1 ? window : window.slice(0, handlerAt);
-  // Accept BOTH prefixes: core routes gate via `auth.requireRank(...)`; a module
-  // route reaches the SAME guards through the published doorway as `api.requireRank(...)`
-  // (src/module-api re-exports requireRank/requireBuilder/requireBfgPrincipal). Without
-  // the `api.` arm a correctly-gated module write route would mis-classify as 'unknown'
-  // → a false blocker, and the moved dev-box routes (BV1.R43/M07) would never pass.
-  if (/(?:auth|api)\.requireRank\(\s*['"]xenos['"]/.test(tail)) return 'any-builder';
-  if (/(?:auth|api)\.requireRank\(\s*['"]metic['"]\s*,\s*['"]archon['"]\s*\)/.test(tail)) return 'metic+archon';
-  if (/(?:auth|api)\.requireRank\(\s*['"]archon['"]\s*\)/.test(tail)) return 'archon';
-  // Matched BEFORE the requireBuilder branch in THIS classifier's if-chain (not
-  // a statement about middleware execution order — the actual route chain runs
-  // requireBuilder → requireBfgPrincipal). The BFG write route carries both;
-  // requireBuilder authenticates, requireBfgPrincipal narrows to the one service
-  // principal, and the principal gate is the load-bearing one we want recorded.
-  if (/(?:auth|api)\.requireBfgPrincipal/.test(tail)) return 'bfg-principal';
-  if (/(?:auth|api)\.requireBuilder/.test(tail)) return 'any-builder';
+
+  const perms = permissionKeysIn(tail);
+  const byRank = rankFromRankGate(tail);
+  if (perms) {
+    const byPermission = rankForPermissions(perms, floors || permissionFloors());
+    // An unresolvable permission gate is 'unknown' EVEN THOUGH a requireBuilder sits
+    // beside it (every permission gate mounts after one). Deferring to that
+    // requireBuilder would let a typo'd atom — which grants nothing — read as
+    // 'any-builder', i.e. as gated. Fail closed and loud instead.
+    if (byPermission === 'unknown') return { rank: 'unknown', perms, via: 'middleware' };
+    // The two gate forms AND when a route carries both, so the stricter one is the
+    // route's real floor. Reporting the looser one would understate authority.
+    const stricter = byRank && LABEL_STRICTNESS[byRank] > LABEL_STRICTNESS[byPermission] ? byRank : byPermission;
+    return { rank: stricter, perms, via: 'middleware' };
+  }
+  if (byRank) return { rank: byRank, perms: null, via: 'middleware' };
 
   for (let j = i - 1; j >= 0; j--) {
     const line = lines[j];
@@ -243,24 +451,95 @@ function classifyRank(lines, i) {
       const c = /\brank:\s*([a-z]+(?:[+-][a-z]+)*)/i.exec(line);
       if (c) {
         const v = c[1].toLowerCase();
-        return KNOWN_RANKS.has(v) ? v : 'unknown';
+        // A typo is 'unknown' with NO provenance — there is nothing to trust here.
+        return KNOWN_RANKS.has(v)
+          ? { rank: v, perms: null, via: 'annotation' }
+          : { rank: 'unknown', perms: null, via: null };
       }
     }
   }
-  return 'unknown';
+  return { rank: 'unknown', perms: null, via: null };
+}
+
+// Back-compat scalar form (gen-api-docs + several tests call this directly).
+function classifyRank(lines, i, opts) {
+  return classifyGate(lines, i, opts).rank;
 }
 
-// Parse route declarations + ranks from a route file's source text. Pure
-// (no fs) so it's trivially testable. Returns [{ method, route, key, rank }].
-function classifyText(text) {
+// ── route-declaration scanning (BV1.R109b) ───────────────────────────────────
+//
+// A route declaration OPENS with `router.<method>(`. The path may sit on that same
+// line, or — for a long middleware chain — on the line below it:
+//
+//   router.get(
+//     '/security/adr',
+//     auth.requireBuilder,
+//     auth.requireRank('metic', 'archon'),
+//
+// Until BV1.R109b the scanner required method AND quoted path on ONE line, so a
+// multi-line declaration was never emitted: 10 real routes (6 of them writes,
+// 2 reading other builders' memory) were INVISIBLE to this auditor — never checked
+// for being ungated or downgraded, never pinned, never published by gen-api-docs.
+//
+// ROUTE_DECL_RE is therefore the CENSUS: every line it matches must resolve to
+// exactly one classified route. A declaration whose path cannot be resolved
+// statically is reported by checkRouteRanks (below) instead of being skipped —
+// fail-closed, because a route the auditor cannot even NAME is strictly less
+// verifiable than one whose gate it merely cannot classify.
+const ROUTE_DECL_RE = /^\s*router\.(get|post|patch|put|delete)\s*\(/;
+const ROUTE_DECL_SAME_LINE_RE = /^\s*router\.(get|post|patch|put|delete)\s*\(\s*['"]([^'"]+)['"]/;
+// A continuation line carrying the quoted path, then the comma before the middleware.
+const ROUTE_PATH_LINE_RE = /^\s*['"]([^'"]+)['"]\s*,/;
+// How far past a multi-line opener to look for the path. It is on the very next line
+// in every real case; the slack only tolerates an interleaved comment.
+const PATH_LOOKAHEAD = 5;
+
+// The literal path a declaration at line `i` names, or null when it is not statically
+// resolvable (a template literal, a variable, a computed path).
+function routePathAt(lines, i) {
+  const same = ROUTE_DECL_SAME_LINE_RE.exec(lines[i]);
+  if (same) return same[2];
+  // Multi-line form: nothing but whitespace/comment may follow the '(' …
+  const rest = lines[i].slice(lines[i].indexOf('(') + 1).trim();
+  if (rest !== '' && !rest.startsWith('//')) return null;
+  // … and the first content line below must open with the quoted path.
+  for (let j = i + 1; j < lines.length && j <= i + PATH_LOOKAHEAD; j++) {
+    const t = lines[j].trim();
+    if (t === '' || t.startsWith('//')) continue;
+    const m = ROUTE_PATH_LINE_RE.exec(lines[j]);
+    return m ? m[1] : null;
+  }
+  return null;
+}
+
+// Every `router.<method>(` declaration in a route file's source, in source order:
+// [{ method, route, line }] — `route` is null when the path did not resolve. This is
+// the single scanner BOTH consumers use (this auditor and gen-api-docs.js), so the
+// published API contract and the enforced gate list can never enumerate different
+// routes. There is deliberately no second declaration regex in gen-api-docs.
+function scanDeclarations(text) {
   const lines = String(text).split('\n');
   const out = [];
   for (let i = 0; i < lines.length; i++) {
-    const m = /^\s*router\.(get|post|patch|put|delete)\s*\(\s*['"]([^'"]+)['"]/.exec(lines[i]);
+    const m = ROUTE_DECL_RE.exec(lines[i]);
     if (!m) continue;
-    const method = m[1].toUpperCase();
-    const route = m[2];
-    out.push({ method, route, key: `${method} ${route}`, rank: classifyRank(lines, i) });
+    out.push({ method: m[1].toUpperCase(), route: routePathAt(lines, i), line: i });
+  }
+  return out;
+}
+
+// Parse route declarations + gates from a route file's source text. Pure (no fs
+// beyond the lazily-loaded permission catalog) so it's trivially testable.
+// Returns [{ method, route, key, rank, perms }].
+function classifyText(text, opts) {
+  const lines = String(text).split('\n');
+  const out = [];
+  for (const d of scanDeclarations(text)) {
+    if (d.route === null) continue; // surfaced as a finding by checkRouteRanks, not dropped
+    // classifyGate scans FROM the declaration line, so for a multi-line declaration the
+    // middleware (which sits below the path line) is inside its 20-line window, and its
+    // comment-block `rank:` scan still starts directly above the declaration.
+    out.push({ method: d.method, route: d.route, key: `${d.method} ${d.route}`, ...classifyGate(lines, d.line, opts) });
   }
   return out;
 }
@@ -290,6 +569,54 @@ function discoverRouteFiles({ routesDir = ROUTES_DIR, modulesDir = MODULES_DIR }
   return out;
 }
 
+// A pin value → { kind: 'rank', rank } | { kind: 'permission', perms[] }.
+// 'perm:a,b' names the AUTHORITY ATOMS the route must gate on; anything else is a
+// rank label (the pre-governance spelling, still valid).
+function parsePin(value) {
+  if (typeof value === 'string' && value.startsWith(PERM_PIN_PREFIX)) {
+    return {
+      kind: 'permission',
+      perms: value.slice(PERM_PIN_PREFIX.length).split(',').map((s) => s.trim()).filter(Boolean),
+    };
+  }
+  return { kind: 'rank', rank: value };
+}
+
+// Why route `r` fails its pin, or null when it satisfies it.
+//
+// EITHER GATE FORM SATISFIES A PIN — that is what makes the R104-R107 migration
+// window survivable. A rank pin is satisfied by whatever the route classifies to
+// (a requirePermission gate resolves through the catalog into the same vocabulary).
+// A permission pin is satisfied by the route naming exactly those atoms, OR — while
+// the route is still un-migrated — by carrying the rank gate those atoms' floor
+// resolves to. Neither direction lets a route drop below what the pin demands.
+function pinMismatch(expected, r) {
+  const pin = parsePin(expected);
+  // BV1.R109d — a pin is NEVER satisfied by an annotation. Pins exist for routes
+  // "whose downgrade would be a real authority breach", so satisfying one with a
+  // `// rank: archon` comment over a route carrying no middleware would let the
+  // deterministic alarm certify prose. Checked before the label comparisons below
+  // because the label itself is what the comment fabricates.
+  if (r.via === 'annotation') {
+    return `is pinned to '${expected}' but carries NO auth middleware — its rank comes only from a \`rank:\` comment, which certifies nothing`;
+  }
+  if (pin.kind === 'rank') {
+    return r.rank === pin.rank ? null : `classifies as '${r.rank}' but is pinned to '${pin.rank}'`;
+  }
+  const pinnedRank = rankForPermissions(pin.perms);
+  if (pinnedRank === 'unknown') {
+    return `is pinned to permission(s) '${pin.perms.join(', ')}' the governance catalog does not define`;
+  }
+  if (r.perms) {
+    const got = [...r.perms].sort().join(',');
+    const want = [...pin.perms].sort().join(',');
+    return got === want ? null : `gates on permission(s) '${got}' but is pinned to '${want}'`;
+  }
+  return r.rank === pinnedRank
+    ? null
+    : `classifies as '${r.rank}' but is pinned to permission(s) '${pin.perms.join(', ')}' (rank floor '${pinnedRank}')`;
+}
+
 // Walk every route file (core + modules) and assert the invariant. Returns:
 //   { ok, hardFail, routeCount, routes[], findings[] }
 // findings[]: { severity, file, route, method, rank, summary }
@@ -299,13 +626,34 @@ function checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {}) {
   // caller (or a hermetic test) may pass modulesDir explicitly to override.
   if (modulesDir === undefined) modulesDir = path.resolve(routesDir, '..', '..', '..', 'modules');
   const routes = [];
+  const unresolved = [];
   for (const { abs, rel } of discoverRouteFiles({ routesDir, modulesDir })) {
-    for (const r of classifyText(fs.readFileSync(abs, 'utf8'))) {
-      routes.push({ ...r, file: rel });
+    const text = fs.readFileSync(abs, 'utf8');
+    for (const r of classifyText(text)) routes.push({ ...r, file: rel });
+    for (const d of scanDeclarations(text)) {
+      if (d.route === null) unresolved.push({ ...d, file: rel });
     }
   }
 
   const findings = [];
+
+  // BV1.R109b — a declaration whose path this scanner cannot resolve is INVISIBLE to
+  // every check below, which is exactly the hole that hid 10 multi-line routes. Report
+  // it at the same severity as an unclassifiable gate: a write is a hard fail, a read
+  // is a concern the Hacker adjudicates.
+  for (const d of unresolved) {
+    const isWrite = WRITE_METHODS.has(d.method);
+    findings.push({
+      severity: isWrite ? 'blocker' : 'major',
+      file: d.file,
+      route: `${d.method} (unresolved ${d.file}:${d.line + 1})`,
+      method: d.method,
+      rank: '(unparsed)',
+      summary: `A router.${d.method.toLowerCase()}( declaration at ${d.file}:${d.line + 1} names a path this auditor cannot resolve statically, so the route is invisible to the rank check AND absent from the generated API contract. `
+        + 'Declare the path as a literal string — on the declaration line, or on the line directly below it.',
+    });
+  }
+
   for (const r of routes) {
     if (r.rank !== 'unknown') continue;
     const isWrite = WRITE_METHODS.has(r.method);
@@ -322,6 +670,28 @@ function checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {}) {
     });
   }
 
+  // BV1.R109d — a `rank:` COMMENT claiming a PRIVILEGED rank over a route that
+  // carries no auth middleware. `rank: public` is the annotation's legitimate use —
+  // it asserts nothing is protected, which a comment can honestly say. Any other
+  // value asserts a gate exists, and the annotation arm is reached ONLY when no
+  // middleware was found, so that assertion is false by construction. Left
+  // unchecked, such a route passed the ungated-write invariant AND every exact pin.
+  for (const r of routes) {
+    if (r.via !== 'annotation' || r.rank === 'public') continue;
+    const isWrite = WRITE_METHODS.has(r.method);
+    findings.push({
+      severity: isWrite ? 'blocker' : 'major',
+      file: r.file,
+      route: r.key,
+      method: r.method,
+      rank: r.rank,
+      summary: `${r.key} (${r.file}) claims \`rank: ${r.rank}\` in a comment but carries NO auth middleware — no requireRank, requirePermission, requireBuilder or principal gate. A comment cannot gate a route. `
+        + (isWrite
+          ? 'A privileged write route gated only by prose is a hard fail (ADR 0016): add the real middleware, or annotate `rank: public` if it is genuinely unauthenticated.'
+          : 'Add the real middleware, or annotate `rank: public` if it is genuinely unauthenticated.'),
+    });
+  }
+
   // #999 — EXACT-rank pin on known privileged routes. A downgrade (e.g. an
   // archon route silently dropped to any-builder) trips a 'blocker' here even
   // though the route still classifies to a *known* rank, which the loop above
@@ -354,19 +724,20 @@ function checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {}) {
         route: key,
         method: key.split(' ')[0],
         rank: '(missing)',
-        summary: `Privileged route ${key} is pinned to expect rank '${expected}' but is no longer present under src/bongos/routes/. `
+        summary: `Privileged route ${key} is pinned to expect '${expected}' but is no longer present under src/bongos/routes/. `
           + 'If it was intentionally removed/renamed, drop or update its entry in EXPECTED_RANKS; otherwise a protected route vanished.',
       });
       continue;
     }
-    if (r.rank !== expected) {
+    const mismatch = pinMismatch(expected, r);
+    if (mismatch) {
       findings.push({
         severity: 'blocker',
         file: r.file,
         route: r.key,
         method: r.method,
         rank: r.rank,
-        summary: `Privileged route ${r.key} (${r.file}) classifies as '${r.rank}' but is pinned to '${expected}'. `
+        summary: `Privileged route ${r.key} (${r.file}) ${mismatch}. `
           + 'This is a rank DOWNGRADE/CHANGE on a route that guards authority (ADR 0016). '
           + 'If the change is intentional, update EXPECTED_RANKS in route-rank-check.js in the same commit; otherwise restore the gate.',
       });
@@ -413,13 +784,25 @@ function toWorkerResult(result) {
 module.exports = {
   ROUTE_FILE_RE,
   MODULES_DIR,
+  CATALOG_PATH,
   KNOWN_RANKS,
   WRITE_METHODS,
   EXPECTED_RANKS,
   MODULE_EXPECTED_RANKS,
+  PERM_PIN_PREFIX,
+  PERMISSION_RANK_ORDER,
+  FLOOR_LABEL,
   SPECIALTY,
+  parsePermissionFloors,
+  permissionFloors,
+  permissionKeysIn,
+  rankForPermissions,
+  parsePin,
+  pinMismatch,
+  classifyGate,
   classifyRank,
   classifyText,
+  scanDeclarations,
   discoverRouteFiles,
   checkRouteRanks,
   toWorkerResult,

package/src/bongos/routes/_helpers.js

@@ -33,7 +33,18 @@ function parseCookie(req, name) {
   const cookieHeader = req.headers['cookie'] || '';
   for (const part of cookieHeader.split(';')) {
     const [k, v] = part.trim().split('=');
-    if (k === name && v) return v;
+    if (k === name && v) {
+      // Cookie values are percent-ENCODED on write (Express `res.cookie` defaults
+      // to encodeURIComponent), so decode symmetrically on read. Without this, a
+      // return path like "/create" arrives as "%2Fcreate": safeReturnTo() sees a
+      // value that doesn't start with "/", tries `new URL()`, throws, and returns
+      // null — so a post-login redirect silently falls through to the default
+      // landing instead of the requested page (task 1002241; also un-breaks the
+      // #726 subdomain-return, whose full https:// URLs were encoded too). No-op
+      // for every value without a %-escape (hex state/session tokens, "1"). Guard
+      // a malformed lone "%" by falling back to the raw value.
+      try { return decodeURIComponent(v); } catch { return v; }
+    }
   }
   return null;
 }