@bongos/core 1.18.3 → 1.18.18

package/src/bongos/auth.js

@@ -41,6 +41,7 @@ const {
   getBuilderById,
   getBuilderByGithubId,
   hasInvitedAccessRequest,
+  accessStateByLogin,
   RANKS,
 } = require('./db-kernel');
 const { pool } = require('./pool');
@@ -250,6 +251,48 @@ function firstTimeAdmissionBlocked({ existing, approved, login }) {
   return true;
 }
 
+// webAdmissionStatus — "would this login get in RIGHT NOW, and is it worth
+// waiting?" (task 1002097). Backs the waiting page that replaced the red
+// "not approved" dead-end a firstAdmin hits during the bootstrap window.
+//
+// `admitted` deliberately mirrors firstTimeAdmissionBlocked's own terms —
+// member OR open-enrollment OR invited OR configured-firstAdmin — so the probe
+// can never say "come in" while the real gate says otherwise. It reads state;
+// it decides nothing. firstTimeAdmissionBlocked remains the one gate both flows
+// call (SR-19); if that logic changes, this must change with it.
+// tests/web_admission_status.mjs sweeps the input space asserting the two agree.
+//
+// `expectedSoon` is the broader "keep polling" signal: admitted, or waiting on
+// an Archon (pending), or the configured firstAdmin whose instance is still
+// booting. A visitor who is none of these is a genuine stranger and gets the
+// existing request-access page rather than a spinner that never resolves.
+//
+// NB the onboarding module's public GET /access-requests/status (used by the
+// CLI) reports member|invited|pending|none but knows nothing about the
+// firstAdmin bypass or open enrollment — so it reports the OWNER as 'none'
+// forever. That is exactly why this auth-domain probe exists.
+async function webAdmissionStatus(login) {
+  const name = String(login || '').trim();
+  if (!name) return { admitted: false, expectedSoon: false };
+
+  const fa = firstAdminLogin();
+  const isFirstAdmin = !!fa && name.toLowerCase() === fa.toLowerCase();
+
+  let state = { member: false, invited: false, pending: false };
+  try {
+    state = await accessStateByLogin(name);
+  } catch (err) {
+    // A DB hiccup must not turn the waiting page into a false "you're in".
+    // Fail closed on `admitted`; still let a firstAdmin keep polling, since
+    // that is the bootstrap window this page exists for.
+    console.error('[auth] webAdmissionStatus', err);
+    return { admitted: false, expectedSoon: isFirstAdmin };
+  }
+
+  const admitted = state.member || openEnrollmentEnabled() || state.invited || isFirstAdmin;
+  return { admitted, expectedSoon: admitted || state.pending || isFirstAdmin };
+}
+
 // First-admin bootstrap (R62 / task 1201, ADR 0062). The configured firstAdmin
 // login — an install-time env override (<PREFIX>_FIRST_ADMIN, incl. legacy) wins,
 // else branding.firstAdmin. Empty/unset (the vanilla starter) means "no one is
@@ -284,6 +327,34 @@ async function maybeSeatFirstAdmin(builder) {
   return builder;
 }
 
+// safeSyncRankRole — give a builder the seeded rank-role matching their rank at
+// REGISTRATION (BV1.R95b, ADR 0151). governance_002's builder→role backfill is
+// run-once, so before this every builder admitted after that migration had no role
+// row at all and resolved to the EMPTY permission set — denied on every gated route.
+//
+// Called at each sign-in rather than only on first insert, and deliberately so: the
+// call is idempotent (two SELECTs and no write once the role already matches), it
+// also covers the rank write maybeSeatFirstAdmin just made (the firstAdmin bootstrap
+// flips xenos→archon outside any transaction), and it quietly repairs a builder whose
+// assignment drifted for any other reason.
+//
+// Resolved through the `governance.roleSync` kernel port — auth.js is a KERNEL_FILE
+// and may not require a module (ADR 0083 / ADR 0091 §1). Runs on the pool: there is
+// no surrounding transaction here, unlike the two rank-change paths, which pass their
+// own client so the rotation is atomic with the rank write.
+//
+// BEST-EFFORT: a governance hiccup must never fail a sign-in, and the failure mode is
+// fail-closed anyway — no role means zero permissions, never extra ones.
+async function safeSyncRankRole(builder) {
+  if (!builder || builder.id == null) return;
+  try {
+    await seams.resolveOptional('governance.roleSync')
+      ?.syncRankRole(null, { builderId: builder.id, rank: builder.rank });
+  } catch (err) {
+    console.error('[auth] rank-role sync failed (non-fatal):', err.message);
+  }
+}
+
 function newSessionToken() {
   return crypto.randomBytes(32).toString('hex');
 }
@@ -467,6 +538,7 @@ async function pollDeviceFlow(deviceCode, userAgent) {
       avatarUrl: ghUser.avatar_url,
     });
     builder = await maybeSeatFirstAdmin(builder);
+    await safeSyncRankRole(builder); // BV1.R95b — the seeded rank-role must exist from the first sign-in
     const token = newSessionToken();
     await createSession({
       builderId: builder.id,
@@ -530,6 +602,13 @@ async function completeWebFlow({ code, redirectUri, userAgent, captureRepoToken
     if (firstTimeAdmissionBlocked({ existing, approved, login: ghUser.login })) {
       const err = new Error('not_approved');
       err.code = 'NOT_APPROVED';
+      // Carry the login so the route can tell an imminent admission (the
+      // configured firstAdmin mid-bootstrap, or someone with a pending request)
+      // from a genuine stranger, and show the "confirming access" waiting page
+      // instead of a red dead-end (task 1002097). Attaching it here — rather
+      // than re-deriving it in the route — keeps the login the gate actually
+      // judged. It is NOT a decision: the route re-checks via webAdmissionStatus.
+      err.login = ghUser.login;
       throw err;
     }
   }
@@ -540,6 +619,7 @@ async function completeWebFlow({ code, redirectUri, userAgent, captureRepoToken
     avatarUrl: ghUser.avatar_url,
   });
   builder = await maybeSeatFirstAdmin(builder);
+  await safeSyncRankRole(builder); // BV1.R95b — the seeded rank-role must exist from the first sign-in
   const token = newSessionToken();
   // Web sessions expire after 30 days; the user re-auths on the page
   // when the cookie expires.
@@ -644,6 +724,7 @@ async function completeIdpFlow({ code, redirectUri, userAgent: ua }) {
     avatarUrl: identity.avatar_url,
   });
   builder = await maybeSeatFirstAdmin(builder);
+  await safeSyncRankRole(builder); // BV1.R95b — the seeded rank-role must exist from the first sign-in
   const token = newSessionToken();
   const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
   await createSession({
@@ -712,6 +793,45 @@ function verifyHubAssertion(token, { publicKey, clientId, nowMs = Date.now() } =
   return payload;
 }
 
+// The purpose marker on a hub back-channel logout token — kept in lockstep with
+// the hub minter (platform-identity/hub-keys.js LOGOUT_PURPOSE) across the
+// boundary (ADR 0091 §2). Task 1002238.
+const HUB_LOGOUT_PURPOSE = 'backchannel-logout';
+
+// Verify a hub-signed BACK-CHANNEL LOGOUT token (ADR 0144, task 1002238) — the
+// logout sibling of verifyHubAssertion, same compact-EdDSA-JWT envelope, kept in
+// lockstep with the hub minter (hub-keys.js mintHubLogoutToken). Verifies the
+// Ed25519 signature FIRST (alg HARDCODED to Ed25519 regardless of the header, so
+// no algorithm-confusion), then issuer, audience (must equal THIS instance's
+// client_id, so a token minted for another project can't be replayed here),
+// expiry, and that purpose === 'backchannel-logout'. Requiring `purpose` is what
+// makes login assertions and logout tokens mutually non-interchangeable: a login
+// assertion has no purpose (rejected here), and a logout token has no
+// github_login (rejected by verifyHubAssertion). Returns the validated payload
+// ({ sub: github_id, ... }) or throws. Pure over its inputs (testable, no I/O).
+function verifyHubLogoutToken(token, { publicKey, clientId, nowMs = Date.now() } = {}) {
+  if (!publicKey) throw new Error('hub public key not configured');
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) throw new Error('malformed logout token');
+  const [h, p, s] = parts;
+  let header;
+  try { header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8')); }
+  catch { throw new Error('malformed logout token header'); }
+  if (!header || header.alg !== 'EdDSA') throw new Error('unexpected logout token alg');
+  // Signature over the exact `header.payload` bytes — verify BEFORE trusting claims.
+  const ok = crypto.verify(null, Buffer.from(`${h}.${p}`, 'utf8'), publicKey, Buffer.from(s, 'base64url'));
+  if (!ok) throw new Error('logout token signature invalid');
+  let payload;
+  try { payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8')); }
+  catch { throw new Error('malformed logout token payload'); }
+  if (payload.iss !== HUB_ASSERTION_ISSUER) throw new Error('unexpected logout token issuer');
+  if (clientId != null && String(payload.aud) !== String(clientId)) throw new Error('logout token audience mismatch');
+  if (typeof payload.exp !== 'number' || payload.exp < Math.floor(nowMs / 1000)) throw new Error('logout token expired');
+  if (payload.purpose !== HUB_LOGOUT_PURPOSE) throw new Error('not a back-channel logout token');
+  if (payload.sub == null) throw new Error('logout token missing subject');
+  return payload;
+}
+
 // Anti-replay for CLI assertions (ADR 0141 §1, defense-in-depth on top of the
 // aud-scoping fix): a jti may be exchanged ONCE. In-memory per process, TTL = the
 // assertion's own expiry, so a captured assertion can't be replayed into multiple
@@ -726,6 +846,25 @@ function _assertionJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
   return false;
 }
 
+// Anti-replay for back-channel LOGOUT tokens (task 1002238, symmetric with the CLI
+// assertion path above). Honor a logout token's jti ONCE: the FIRST use revokes,
+// a replay within the ~120s TTL is a no-op. Without this, a captured token stays a
+// repeatable "log this builder out" primitive for its whole life — it would keep
+// killing sessions the builder legitimately creates AFTER the token was minted
+// (the one non-idempotent replay effect; revoking already-dead sessions is
+// otherwise harmless). Separate map from assertions so the two token types never
+// share dedupe state. In-memory per process; a restart clears it (acceptable — the
+// window is short and the aud binding is the primary control). Exported for the
+// route (routes/auth.js) since the DB revoke lives there, not in the kernel.
+const _seenLogoutJti = new Map(); // jti -> expiry ms
+function logoutTokenJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
+  for (const [k, exp] of _seenLogoutJti) if (exp < nowMs) _seenLogoutJti.delete(k);
+  if (!jti) return false; // no jti → cannot dedupe (aud + TTL remain the guards)
+  if (_seenLogoutJti.has(jti)) return true;
+  _seenLogoutJti.set(jti, expSeconds ? expSeconds * 1000 : nowMs + 120000);
+  return false;
+}
+
 // Complete a CLI federation exchange: verify the hub assertion, then run the SAME
 // admission gate + upsertBuilder + createSession(source='cli') as the direct device
 // flow (pollDeviceFlow). Only the identity SOURCE differs. Returns { token, builder }.
@@ -757,6 +896,7 @@ async function completeDeviceExchange({ assertion, userAgent: ua }) {
     avatarUrl: payload.avatar_url,
   });
   builder = await maybeSeatFirstAdmin(builder);
+  await safeSyncRankRole(builder); // BV1.R95b — the seeded rank-role must exist from the first sign-in
   const token = newSessionToken();
   await createSession({
     builderId: builder.id,
@@ -994,18 +1134,134 @@ async function resolveSession(req) {
   return null;
 }
 
-// SECURITY (#919): opt-in marker for the handful of dev-box bootstrap routes a
-// box-scoped session (source='box') is permitted to reach. Mount it BEFORE
-// requireBuilder on those routes; it only flags the request, and requireBuilder's
-// deny-by-default box-scope gate reads the flag. A route WITHOUT this middleware
-// rejects a box session, so this allow-list IS the complete box surface and any
-// new route is denied to boxes automatically (fail closed). No-op for cli/web
-// sessions — requireBuilder only consults the flag when source === 'box'.
-function allowBoxScope(req, _res, next) {
-  req.allowBoxScope = true;
-  next();
+// ── SESSION-SCOPES — capability attached to the TOKEN (BV1.R99, ADR 0151 §3) ──
+//
+// A session's SCOPE is orthogonal to its builder's roles: a dev-box session
+// (source='box') is baked onto a machine OUTSIDE the ADR 0016 trust boundary
+// (#919/SR#2, ADR 0053), so it must stay limited even when its builder is an
+// Archon. Before R99 that was an ad-hoc boolean (`req.allowBoxScope`) plus a
+// hardcoded `source === 'box'` test; it is now an explicit, declared model.
+//
+// A SESSION-SCOPE CAN ONLY EVER NARROW. Effective authority is (what the builder's
+// roles confer) ∩ (what this session's scope allows), with the allow-list
+// DENY-BY-DEFAULT. The intersection itself lives in the governance resolver
+// (resolveSessionPermissions — the composed answer the tab and permission gates
+// read); THIS file carries its route-reachability projection: "is this route
+// inside the session's scope at all". That projection is deliberately the ROLE-FREE
+// half — folding the builder's roles in here would change who can reach the
+// bootstrap routes (a builder on a rank with no seeded governance role resolves to
+// zero permissions by design — see tests/governance_parity.mjs Part D), and R99 is
+// a behaviour-identical remodelling of the #919 gate, not a re-gating of it.
+//
+// GOVERNANCE OWNS THE POLICY, THE KERNEL STAYS THE ENFORCER. The declaration is
+// governance-owned data in modules/governance/session-scopes.json, validated
+// against the permission catalog at load by modules/governance/session-scopes.js.
+// Core reads it as DATA with fs — never `require` (ADR 0083's one-way rule: a
+// module's code and enable/disable state must never be something the kernel
+// depends on). The sibling trust primitive permission-path-check.js reads the
+// protected-surface registry exactly this way (R101). Reading it statically rather
+// than through the `governance` kernel port is the deliberate call: a request must
+// not need a module to be mounted to stay deny-by-default, and the alternative
+// fails badly in both directions — denying on an absent port would take every
+// cli/web session down, admitting would hand a box token full authority.
+//
+// FAIL-CLOSED both ways: an unreadable or malformed registry THROWS (it never
+// degrades to "every session is unscoped"), and a session whose `source` the
+// registry does not declare is DENIED rather than defaulting to full authority. A
+// null/absent source is a DECLARED row (rows minted before migration 090 added the
+// column, which predate the 'box' source existing), not an implicit default.
+const SESSION_SCOPE_REGISTRY_PATH = path.join(__dirname, '..', '..', 'modules', 'governance', 'session-scopes.json');
+
+// Pure: validate + normalize the parsed registry. Split from the file read so the
+// shipped assertions are what the tests exercise. `label` identifies the file in
+// the error text (the fs wrapper passes the path).
+function parseSessionScopes(raw, label = 'session-scope registry') {
+  const rows = Array.isArray(raw && raw.scopes) ? raw.scopes : null;
+  if (!rows || rows.length === 0) {
+    throw new Error(`${label} declares no session scopes. Refusing to run with no session-scope model (ADR 0053/0151).`);
+  }
+  const bySource = new Map();
+  for (const row of rows) {
+    const source = row && row.source !== undefined ? row.source : null;
+    if (source !== null && (typeof source !== 'string' || !source)) {
+      throw new Error(`${label}: every scope needs a non-empty session source string, or null for the legacy sourceless row`);
+    }
+    if (bySource.has(source)) throw new Error(`${label}: duplicate session source "${source}"`);
+    const unscoped = !!(row && row.unscoped === true);
+    const permissions = row && Array.isArray(row.permissions) ? [...row.permissions] : [];
+    // unscoped XOR an allow-list. Both would be ambiguous (does it narrow?);
+    // neither would be a scope that can never admit anything — an authoring slip
+    // either way, and both must fail loud rather than pick a default.
+    if (unscoped === (permissions.length > 0)) {
+      throw new Error(`${label}: "${source}" must declare EITHER unscoped:true OR a non-empty permissions allow-list, never both/neither`);
+    }
+    if (permissions.some((key) => typeof key !== 'string' || !key)) {
+      throw new Error(`${label}: "${source}" lists a non-string permission key`);
+    }
+    bySource.set(source, Object.freeze({
+      source,
+      label: row && typeof row.label === 'string' ? row.label : null,
+      unscoped,
+      permissions: Object.freeze(permissions),
+    }));
+  }
+  return bySource;
+}
+
+function loadSessionScopes(file) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`session-scope registry unreadable at ${file}: ${e.message}. Refusing to run with no session-scope model (ADR 0053/0151).`);
+  }
+  return parseSessionScopes(raw, `session-scope registry ${file}`);
+}
+
+const _sessionScopes = loadSessionScopes(SESSION_SCOPE_REGISTRY_PATH);
+const SESSION_SCOPES = Object.freeze([..._sessionScopes.values()]);
+
+// The scope a session's `source` declares, or null when the registry does not
+// declare it (⇒ deny; never "full").
+function sessionScopeFor(source) {
+  const key = source === undefined ? null : source;
+  if (key !== null && typeof key !== 'string') return null;
+  return _sessionScopes.get(key) || null;
+}
+
+// Route reachability, deny-by-default. An unscoped session reaches everything its
+// builder's gates admit; a SCOPED session reaches only a route that declared
+// capability its allow-list names — so a route that declares nothing (every route
+// that has not opted in, including any added later) is out of reach.
+function scopeCovers(scope, declared) {
+  if (!scope) return false; // unrecognised source
+  if (scope.unscoped) return true;
+  const needs = Array.isArray(declared) ? declared : [];
+  return needs.length > 0 && needs.every((key) => scope.permissions.includes(key));
+}
+function sessionScopeAdmits(source, declared) {
+  return scopeCovers(sessionScopeFor(source), declared);
 }
 
+// The route-side DECLARATION: "reaching this route needs these capabilities from
+// the session's scope." Mount it BEFORE requireBuilder. Inert for an unscoped
+// session — requireBuilder compares the declaration only against a narrowing scope.
+function sessionScope(...keys) {
+  const needs = Object.freeze([...keys]);
+  return function declareSessionScope(req, _res, next) {
+    req.sessionScopeNeeds = needs;
+    next();
+  };
+}
+
+// The dev-box bootstrap declaration (#919) — the name modules/dev-box mounts
+// through the plugin API (docs/modules-contract.md 1.2.0), kept as the module-
+// facing spelling. It is no longer a bare boolean: it declares the box scope's OWN
+// allow-list, read from the registry, so the declaration cannot drift from the
+// scope it declares. If the registry stopped declaring a box scope it would
+// declare nothing and every box session would be denied — fail closed.
+const allowBoxScope = sessionScope(...((sessionScopeFor('box') || { permissions: [] }).permissions));
+
 async function requireBuilder(req, res, next) {
   const session = await resolveSession(req);
   if (!session) {
@@ -1024,18 +1280,25 @@ async function requireBuilder(req, res, next) {
     res.fail('builder_inactive', 403);
     return;
   }
-  // SECURITY (#919, SR#2): box-scoped sessions are DENY-BY-DEFAULT. The dev-box
-  // provisioner (scripts/gds/box.js) bakes a session into cloud-init so the box can
-  // bootstrap (#818 — box-source-fetch clones the rank-scoped repo before
-  // /builder-setup exists). That token lives ON the box, which is OUTSIDE the ADR
-  // 0016 trust boundary, so it must NOT carry the builder's full authority. A
-  // source='box' session may reach ONLY the routes that opted in via allowBoxScope
-  // (the 4 endpoints the on-box crons call — see routes/box.js); EVERY other route
-  // (all of /tasks, /me, the rest of /box …) fails closed here, including any route
-  // added later. A builder who wants to do real work FROM the box runs
-  // /builder-reauth, minting a normal cli/web session (no box scope) like any laptop.
-  if (session.source === 'box' && !req.allowBoxScope) {
-    res.fail('box_scope', { status: 403, message: 'This is a box-scoped session; it may only call dev-box bootstrap endpoints.' });
+  // SECURITY (#919, SR#2): SESSION-SCOPE, deny-by-default. The dev-box provisioner
+  // (scripts/gds/box.js) bakes a session into cloud-init so the box can bootstrap
+  // (#818 — box-source-fetch clones the rank-scoped repo before /builder-setup
+  // exists). That token lives ON the box, which is OUTSIDE the ADR 0016 trust
+  // boundary, so it must NOT carry the builder's full authority. Since R99 the rule
+  // is DATA (the session-scope registry above), not a hardcoded source test: a
+  // narrowing session reaches ONLY a route that declared capability its allow-list
+  // names, so EVERY other route (all of /tasks, /me, the rest of /box …) fails
+  // closed here, including any route added later; and a source the registry does not
+  // declare at all is denied rather than treated as unscoped. A builder who wants to
+  // do real work FROM the box runs /builder-reauth, minting a normal cli/web session.
+  const scope = sessionScopeFor(session.source);
+  if (!scopeCovers(scope, req.sessionScopeNeeds)) {
+    res.fail('box_scope', {
+      status: 403,
+      message: scope
+        ? 'This is a box-scoped session; it may only call dev-box bootstrap endpoints.'
+        : 'This session carries an unrecognised scope and may not call authenticated endpoints.',
+    });
     return;
   }
   // Anthropic-identity pin — REMOVED (task 1039, idea 258). This used to 403
@@ -1075,17 +1338,6 @@ async function requireBuilder(req, res, next) {
   next();
 }
 
-// Page-level sign-in gate for the authenticated /builders HTML surface and its
-// content assets (#488). Same identity check as requireBuilder — token from the
-// gds_session cookie (or legacy pms_session / Bearer), looked up fresh against
-// builder_sessions — but on failure it REDIRECTS the browser into the web
-// sign-in flow (302 → /api/gds/auth/web/start) instead of returning a JSON 401,
-// because these requests are page navigations and asset loads, not API calls.
-//
-// This is the *actual* access control for the citizen primer + system-maps:
-// server.js mounts it ahead of the static handlers so an unauthenticated
-// request is bounced before the file is ever served (curl-proof, JS-disabled-
-// proof). The client-side link-hiding in builders.js is only cosmetic UX.
 // Build a `?return=<absolute current URL>` for a page-gate sign-in redirect
 // (#734) so a builder bounced into sign-in from the builders subdomain lands
 // back on the page they wanted. The web flow validates it (open-redirect guard)
@@ -1099,87 +1351,114 @@ function signInWithReturn(req) {
   return `${base}?return=${encodeURIComponent(`${proto}://${host}${req.originalUrl}`)}`;
 }
 
-async function requireBuilderPage(req, res, next) {
+// ── the three PAGE GATES (BV1.R107, ADR 0151) ────────────────────────────────
+//
+// A page gate is the *actual* access control for an HTML surface and its content
+// assets (#488): serve-internal.js mounts it ahead of the static handlers, so an
+// unauthorized request is bounced before the file is ever served (curl-proof,
+// JS-disabled-proof). The client-side link-hiding in the hall is cosmetic UX.
+//
+// Each gate asks TWO questions, in order:
+//   1. IDENTITY  — is there a live session? (token from the gds_session cookie /
+//      legacy pms_session / Bearer, looked up fresh against builder_sessions).
+//      No → 302 into the web sign-in flow.
+//   2. AUTHORITY — does the builder HOLD the page's catalog permission, resolved
+//      per request through the `governance` port exactly as requirePermission
+//      does? No → 302 to an UNGATED hall page.
+//
+// They REDIRECT rather than res.fail() because these are page navigations and
+// asset loads, not API calls — a JSON 403 renders as a blank error body in the
+// browser instead of sending the visitor somewhere they can act.
+//
+// R107 replaced each gate's hand-rolled rank test with the catalog key sitting at
+// that gate's EXISTING rank floor, so the audience is unchanged over the four live
+// ranks (catalog.RANK_ORDER):
+//   requireBuilderPage   was "any session"        floor xenos  → page.view.public
+//   requireNonXenosPage  was rank !== 'xenos'     floor thetes → page.view.builder
+//   requireArchonPage    was rank === 'archon'    floor archon → page.view.governance
+// The one accepted divergence is the one governance_002 already documents
+// (tests/governance_parity.mjs Part D): a builder on a reserved/divine rank holds
+// no seeded role, so they now fail a page gate a bare rank test would have
+// admitted. That is a TIGHTENING, never a widening.
+//
+// `deniedTo` is NEVER the sign-in flow. A visitor on that branch already HAS a
+// session, so bouncing them into sign-in returns them to the same gate — an
+// infinite loop. Every destination below is an ungated hall page:
+//   - /builders          the hall home. A signed-in non-Archon IS a citizen, just
+//                        not the Ruling Hand, so send them home.
+//   - /builders/not-ready the friendly notice for the orientation reading rooms;
+//                        it shows the rank ladder and a way back to the hall.
+const PAGE_GATES = Object.freeze({
+  requireBuilderPage: Object.freeze({ permission: 'page.view.public', deniedTo: '/builders' }),
+  requireNonXenosPage: Object.freeze({ permission: 'page.view.builder', deniedTo: '/builders/not-ready' }),
+  requireArchonPage: Object.freeze({ permission: 'page.view.governance', deniedTo: '/builders' }),
+});
+
+// A builder's effective permission set, or NULL when authority cannot be
+// ESTABLISHED (the `governance` port is absent or malformed, or the resolver
+// threw). Every caller must read null as a DENIAL: admitting when the authority
+// system is missing would make disabling a module a privilege escalation — the
+// inversion ADR 0016 exists to prevent. Resolved per request, never memoised.
+async function resolveHeldPermissions(builderId) {
+  if (builderId === null || builderId === undefined || builderId === '') return null;
+  const governance = seams.resolveOptional('governance');
+  if (!governance || typeof governance.resolveBuilderPermissions !== 'function') return null;
   try {
-    const session = await resolveSession(req);
-    if (!session) {
-      res.redirect(302, signInWithReturn(req));
-      return;
-    }
-    next();
+    return new Set((await governance.resolveBuilderPermissions(builderId)) || []);
   } catch (err) {
-    // Fail CLOSED: if the session lookup itself errors (e.g. DB blip), send the
-    // visitor to sign-in rather than leaking the gated page. The content the
-    // gate protects is the priority here, not availability.
-    console.error('[gds] requireBuilderPage lookup failed', err);
-    res.redirect(302, signInWithReturn(req));
+    console.error('[gds] permission resolve failed', err);
+    return null;
   }
 }
 
-// requireArchonPage — page-level Archon gate for the /watch monitoring surface
-// (#726). Same identity resolution as requireBuilderPage, but additionally
-// checks the LIVE rank from the session lookup:
-//   - no session            → 302 into the web sign-in flow (page navigation)
-//   - signed in, not Archon  → 302 back to the hall (/builders) — they ARE a
-//                              citizen, just not the Ruling Hand; bouncing to
-//                              sign-in would loop, so send them home instead.
-//   - Archon                 → next()
-// This is defense-in-depth: every data endpoint the page calls is ALSO
-// requireRank('archon') server-side, so no cross-builder data can leak even if
-// this gate were bypassed. But it keeps a non-Archon from ever seeing the page
-// shell, honoring "only Archons have access".
-async function requireArchonPage(req, res, next) {
+async function runPageGate(name, req, res, next) {
+  const { permission, deniedTo } = PAGE_GATES[name];
+  let session;
   try {
-    const session = await resolveSession(req);
-    if (!session) {
-      res.redirect(302, signInWithReturn(req));
-      return;
-    }
-    if (session.rank !== 'archon') {
-      res.redirect(302, '/builders');
-      return;
-    }
-    next();
+    session = await resolveSession(req);
   } catch (err) {
-    // Fail CLOSED — a lookup error sends the visitor to sign-in rather than
-    // leaking the gated page shell.
-    console.error('[gds] requireArchonPage lookup failed', err);
+    // Fail CLOSED: a session-lookup blip sends the visitor to sign-in rather than
+    // leaking the gated page. The content the gate protects is the priority, not
+    // availability — and at this point we cannot tell whether they were signed in.
+    console.error(`[gds] ${name} lookup failed`, err);
+    res.redirect(302, signInWithReturn(req));
+    return;
+  }
+  if (!session) {
     res.redirect(302, signInWithReturn(req));
+    return;
+  }
+  const held = await resolveHeldPermissions(session.builder_id);
+  if (held === null || !held.has(permission)) {
+    res.redirect(302, deniedTo);
+    return;
   }
+  next();
+}
+
+// The authenticated /builders HTML surface — the Work Board, Roadmap, Goals, the
+// task-detail page, the Repo Atlas, the Dev Box pair page and Settings. A Xenos IS
+// allowed (page.view.public floors at xenos); an unauthenticated visitor is bounced
+// into sign-in rather than served the page shell.
+async function requireBuilderPage(req, res, next) {
+  return runPageGate('requireBuilderPage', req, res, next);
 }
 
-// requireNonXenosPage — page-level gate for the orientation reading rooms (the
-// citizen's primer, the system-maps/diagrams) that #766 closed to newcomers
-// and #770 enforces at the URL. A Xenos's path is action-only — find work,
-// claim, ship three — so these pages are reserved for graduated citizens
-// (Thetes+). Same identity resolution as requireBuilderPage, plus a live-rank
-// check:
-//   - no session  → 302 into the web sign-in flow (page navigation)
-//   - Xenos        → 302 to /builders/not-ready — they ARE a citizen, just not
-//                    ready for the reading rooms; the not-ready page offers the
-//                    rank ladder + a way back to the hall. Bouncing to sign-in
-//                    would loop, so send them to the friendly notice.
-//   - Thetes+      → next()
-// Defense-in-depth: this is the curl-proof / no-JS-proof gate. The link-hiding
-// in builders.js is only cosmetic.
+// The /watch monitoring surface, the /harbor dev-box page and the /gate page
+// (#726, idea 257, task 1179) — Archon-only. Defense-in-depth: every data endpoint
+// these pages call is independently gated server-side, so no cross-builder data
+// leaks even if this gate were bypassed; it keeps a non-Archon from ever seeing
+// the page shell.
+async function requireArchonPage(req, res, next) {
+  return runPageGate('requireArchonPage', req, res, next);
+}
+
+// The orientation reading rooms (the citizen's primer, the system-maps/diagrams)
+// that #766 closed to newcomers and #770 enforces at the URL. A Xenos's path is
+// action-only — find work, claim, ship three — so these pages are reserved for
+// graduated citizens (Thetes+).
 async function requireNonXenosPage(req, res, next) {
-  try {
-    const session = await resolveSession(req);
-    if (!session) {
-      res.redirect(302, signInWithReturn(req));
-      return;
-    }
-    if (session.rank === 'xenos') {
-      res.redirect(302, '/builders/not-ready');
-      return;
-    }
-    next();
-  } catch (err) {
-    // Fail CLOSED — a lookup error sends the visitor to sign-in rather than
-    // leaking the gated page shell.
-    console.error('[gds] requireNonXenosPage lookup failed', err);
-    res.redirect(302, signInWithReturn(req));
-  }
+  return runPageGate('requireNonXenosPage', req, res, next);
 }
 
 // ---------------------------------------------------------------------------
@@ -1277,6 +1556,63 @@ function requireRank(...allowed) {
   };
 }
 
+// requirePermission(...perms) — the PERMISSION gate (ADR 0151, BV1.R97).
+//
+// The permissions-as-atom sibling of requireRank. Instead of asking "is this
+// builder's rank at-or-above a floor", it asks "does this builder HOLD these
+// permission atoms", resolved from the roles they hold. R93's compat seed derives
+// the four rank-roles from each permission's `floor`, so on day one the two gates
+// are EQUIVALENT — requirePermission('idea.triage') admits exactly who
+// requireRank('metic','archon') admits. R104-R107 migrate the ~81 existing call
+// sites; requireRank itself is untouched and keeps working throughout.
+//
+// AND, not OR — every named permission must be held. requireRank(...allowed) is
+// OR-ish only because its arguments are points on ONE ladder (the gate's floor is
+// the lowest of them); unordered atoms have no such ordering to collapse. The
+// governance port's builderHasPermissions() already reads "holds EVERY one", and
+// AND is the stricter, less surprising reading of requirePermission('a','b'): a
+// gate naming two authorities demands both. A genuine "either of these" gate
+// should be spelled as its own permission key, not smuggled into the gate's arity.
+//
+// FAIL-CLOSED at every branch — 403, never an admit:
+//   • no req.builder (gate mounted without requireBuilder)   → 403
+//   • no perms named (a mis-authored gate)                   → 403
+//   • the `governance` port is not registered (module off)   → 403
+//   • the resolver throws (DB blip)                          → 403
+// The port-absent branch is the deliberate one. `governance` is a core-domain,
+// default:true module, so its absence means authority cannot be ESTABLISHED —
+// and admitting on "the authority system is missing" would make disabling a
+// module a privilege escalation, the exact inversion ADR 0016 exists to prevent.
+// A misconfigured instance loses its gated routes; it never gives them away.
+// (Hence resolveOptional + an explicit 403 rather than seams.resolve()'s throw,
+// which would surface as a 500 and read as an outage instead of a denial.)
+//
+// UNCACHED — resolved on the request that needs it, exactly as requireRank reads
+// the live rank. No memo here and none in resolver.js (ADR 0016).
+//
+// The 403 body mirrors requireRank's: `required` is the literal permission list
+// the gate names, and `held` is the subset of THOSE the builder actually holds —
+// or null when the set could not be resolved at all (the requireRank `actual ??
+// null` analogue). Reporting only the intersection explains the denial without
+// dumping the builder's entire permission set into an error body.
+//
+// Usage: router.post('/roles', auth.requireBuilder, auth.requirePermission('governance.manage'), handler)
+function requirePermission(...perms) {
+  const required = Object.freeze([...perms]);
+  return async function permissionGate(req, res, next) {
+    const deny = (held) => res.fail('permission_forbidden', 403, { required, held });
+    const builderId = req.builder && req.builder.id;
+    if (!builderId) return deny(null);
+    if (required.length === 0) return deny(null);
+    // Shared with the page gates (R107): null = authority could not be established
+    // (no port / malformed port / a throwing resolver) and is always a denial.
+    const held = await resolveHeldPermissions(builderId);
+    if (held === null) return deny(null);
+    if (required.every((key) => held.has(key))) return next();
+    return deny(required.filter((key) => held.has(key)));
+  };
+}
+
 // requireBfgPrincipal — the identity gate for the cross-builder memory WRITE
 // path (ADR 0026 §6C / task #446). Runs AFTER requireBuilder. This is
 // DELIBERATELY NOT a rank gate: the trust-boundary exception is bound to ONE
@@ -1320,6 +1656,7 @@ module.exports = {
   idpConfigured,
   openEnrollmentEnabled,
   firstTimeAdmissionBlocked,
+  webAdmissionStatus,
   firstAdminLogin,
   maybeSeatFirstAdmin,
   startDeviceFlow,
@@ -1332,17 +1669,25 @@ module.exports = {
   completeIdpFlow,
   loadHubPublicKey,
   verifyHubAssertion,
+  verifyHubLogoutToken,
+  logoutTokenJtiSeenAndRecord,
   completeDeviceExchange,
   membershipRole,
   extractTokens,
   resolveSession,
   allowBoxScope,
+  sessionScope,
+  sessionScopeFor,
+  sessionScopeAdmits,
+  parseSessionScopes,
+  SESSION_SCOPES,
   requireBuilder,
   requireBuilderPage,
   requireArchonPage,
   requireNonXenosPage,
   requireRank,
   rankMeetsThreshold,
+  requirePermission,
   requireBfgPrincipal,
   requireDiscordBot,
   // Discord OAuth (account-linking — Phase 3 F2, ADR 0033)