@bongos/core 1.18.0 → 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');
@@ -55,6 +56,20 @@ const { branding, userAgent } = require('../branding');
 
 const SCOPE = 'read:user';
 
+// Web-flow OAuth scope. Identity (`read:user`) is all the builders'-hall sign-in
+// and the CLI Device Flow ever need. The onboarding wizard
+// (public-landing/create.html), however, lists + creates the signed-in user's own
+// GitHub repos (task 1002099) — which `read:user` cannot do — so it OPTS IN to a
+// broader scope. We add `public_repo`, NOT the all-or-nothing `repo`: it still
+// lists/creates PUBLIC repos (the norm for open-source Cloud Bongos instances)
+// but shows a far gentler consent screen and shrinks the blast radius of the
+// token we then persist (ADR 0143). Only the wizard passes { repos:true }; every
+// other sign-in stays identity-only. Pure + exported so the exact scope string
+// (a security-critical value) is unit-testable.
+function scopeForWebFlow({ repos = false } = {}) {
+  return repos ? `${SCOPE} public_repo` : SCOPE;
+}
+
 // In-memory map of device_code → { interval, expires_at, last_polled_at, github_creds }
 // Device flow is ephemeral; restart of the Node process invalidates pending flows
 // (the user just re-runs the setup skill). Acceptable for V1 — scaling up means
@@ -91,6 +106,116 @@ function authConfigured() {
   return !!loadGithubCreds();
 }
 
+// -------------------------------------------------------------------------
+// Platform IdP federation (ADR 0141 §1) — when enabled, the instance's web +
+// CLI sign-in federate through the Cloud Bongos hub instead of talking to GitHub
+// directly. Identity is federated; authority is NOT — the instance still runs its
+// OWN admission gate + upsertBuilder + createSession, so the hub only answers
+// "who is this GitHub user" (ADR 0016). Direct-GitHub (auth.idp unset) stays the
+// unchanged fallback for self-hosted instances.
+// -------------------------------------------------------------------------
+
+// The switch is the branding auth.idp flag (committed, non-secret). Fail-soft to
+// false so a branding hiccup degrades to the direct-GitHub path rather than
+// breaking sign-in.
+function idpEnabled() {
+  try { return branding().auth?.idp === true; } catch { return false; }
+}
+
+// Resolve the hub federation config. The switch is the flag above; the hub origin
+// + client credentials come from ENV (<PREFIX>_HUB_ORIGIN / _HUB_CLIENT_ID /
+// _HUB_CLIENT_SECRET) — never a committed file, so the secret stays out of the
+// branding pack (mirrors loadGithubCreds's env-first posture). Provisioning
+// (ADR 0141 §4) writes these into the instance web.env. Returns null unless the
+// flag is on AND all three resolve → callers fall back to direct GitHub.
+function loadIdpConfig() {
+  if (!idpEnabled()) return null;
+  const origin = ic.resolveEnv('HUB_ORIGIN');
+  const clientId = ic.resolveEnv('HUB_CLIENT_ID');
+  const clientSecret = ic.resolveEnv('HUB_CLIENT_SECRET');
+  if (origin && clientId && clientSecret) {
+    return { origin: String(origin).replace(/\/+$/, ''), clientId, clientSecret };
+  }
+  return null;
+}
+
+function idpConfigured() {
+  return !!loadIdpConfig();
+}
+
+// The COARSE membership role to report to the hub (ADR 0141 §3) — owner if this
+// builder is the instance's configured firstAdmin, else builder. NEVER a rank.
+function membershipRole({ githubLogin } = {}) {
+  const fa = firstAdminLogin();
+  if (fa && String(githubLogin || '').toLowerCase() === fa.toLowerCase()) return 'owner';
+  return 'builder';
+}
+
+// Best-effort server-to-server membership check-in to the hub (ADR 0141 §3): "this
+// github_id builds on project <client_id>, coarse role <role>". Runs on every
+// FEDERATED sign-in (the only sign-ins a federated instance has) so a CLI-only
+// project still appears in the builder's My Projects with no hub browser session.
+// Fire-and-forget + fully swallowed: a hub outage must NEVER fail a sign-in (mirrors
+// the onboarding stage tick). No-op on a self-hosted instance (idp unset).
+async function reportMembershipCheckIn({ githubId, githubLogin, displayName, avatarUrl }) {
+  const idp = loadIdpConfig();
+  if (!idp) return;
+  try {
+    await fetch(`${idp.origin}/api/gds/sso/membership/check-in`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      body: JSON.stringify({
+        client_id: idp.clientId,
+        client_secret: idp.clientSecret,
+        github_id: githubId,
+        github_login: githubLogin,
+        display_name: displayName ?? null,
+        avatar_url: avatarUrl ?? null,
+        role: membershipRole({ githubLogin }),
+      }),
+    });
+  } catch (err) {
+    console.log('[auth] hub membership check-in failed (non-blocking):', err.message);
+  }
+}
+
+// Best-effort cross-project activity rollup to the hub (ADR 0141 §4): report this
+// builder's descriptive talent snapshot (credits, ships, karma, rank, disciplines)
+// for the internal scouting directory. Fires on every federated sign-in ("on key
+// events"); true periodic reporting is a follow-up. Fully swallowed + no-op when
+// not federated — never fails a sign-in.
+async function reportActivityRollup({ builderId, githubId }) {
+  const idp = loadIdpConfig();
+  if (!idp) return;
+  try {
+    // Snapshot the builder's talent signals directly from the DB (auth.js is a
+    // kernel file — it uses pool, never a non-kernel domain module like metrics.js).
+    const b = await pool.query(
+      'SELECT total_credits, karma, rank, preferred_disciplines FROM builders WHERE id = $1',
+      [builderId],
+    );
+    if (!b.rows[0]) return;
+    const shipped = await pool.query('SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1', [builderId]);
+    const row = b.rows[0];
+    await fetch(`${idp.origin}/api/gds/sso/activity/rollup`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      body: JSON.stringify({
+        client_id: idp.clientId,
+        client_secret: idp.clientSecret,
+        github_id: githubId,
+        credits: Number(row.total_credits) || 0,
+        tasks_shipped: shipped.rows[0] ? shipped.rows[0].n : 0,
+        karma: Number(row.karma) || 0,
+        rank: row.rank || null,
+        disciplines: Array.isArray(row.preferred_disciplines) ? row.preferred_disciplines : [],
+      }),
+    });
+  } catch (err) {
+    console.log('[auth] hub activity rollup failed (non-blocking):', err.message);
+  }
+}
+
 // Admission posture (SR-19 / task #1000). BOTH enrollment paths — the web hall
 // sign-in (completeWebFlow) and the CLI device flow (pollDeviceFlow) — are
 // "invite-gated by default": a FIRST-TIME GitHub account is admitted only if an
@@ -126,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
@@ -160,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');
 }
@@ -201,7 +396,11 @@ async function exchangeCodeForToken(code, redirectUri) {
   });
   const data = await res.json();
   if (data.error) throw new Error(`GitHub token exchange: ${data.error_description || data.error}`);
-  return data.access_token;
+  // Return the GRANTED scope alongside the token. GitHub echoes back the scopes
+  // the user actually consented to (space/comma-separated) — the caller checks it
+  // before persisting a repo-capable token, so a user who declined the broader
+  // consent never has one stored (task 1002099 / ADR 0143).
+  return { accessToken: data.access_token, scope: data.scope || '' };
 }
 
 // -------------------------------------------------------------------------
@@ -339,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,
@@ -360,19 +560,21 @@ async function pollDeviceFlow(deviceCode, userAgent) {
 // Web Flow (browser)
 // -------------------------------------------------------------------------
 
-function buildAuthorizeUrl(state, redirectUri) {
+function buildAuthorizeUrl(state, redirectUri, { repos = false } = {}) {
   const creds = loadGithubCreds();
   if (!creds) throw new Error('GitHub OAuth credentials not configured');
   const u = new URL('https://github.com/login/oauth/authorize');
   u.searchParams.set('client_id', creds.client_id);
   u.searchParams.set('redirect_uri', redirectUri);
-  u.searchParams.set('scope', SCOPE);
+  // `repos:true` (the onboarding wizard only) requests the broader repo scope; every
+  // other caller gets identity-only. scopeForWebFlow keeps that decision in one place.
+  u.searchParams.set('scope', scopeForWebFlow({ repos }));
   u.searchParams.set('state', state);
   return u.toString();
 }
 
-async function completeWebFlow({ code, redirectUri, userAgent }) {
-  const accessToken = await exchangeCodeForToken(code, redirectUri);
+async function completeWebFlow({ code, redirectUri, userAgent, captureRepoToken = false }) {
+  const { accessToken, scope: grantedScope } = await exchangeCodeForToken(code, redirectUri);
   const ghUser = await fetchGithubUser(accessToken);
   // Approval gate (2026-05-30): the web hall sign-in no longer admits anyone
   // with a GitHub account. A first-time visitor must have been approved by an
@@ -400,6 +602,13 @@ async function completeWebFlow({ code, redirectUri, userAgent }) {
     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;
     }
   }
@@ -410,6 +619,7 @@ async function completeWebFlow({ code, redirectUri, 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();
   // Web sessions expire after 30 days; the user re-auths on the page
   // when the cookie expires.
@@ -423,9 +633,285 @@ async function completeWebFlow({ code, redirectUri, userAgent }) {
   });
   // V3.R75 (#294): tick the onboarding state machine. Best-effort.
   await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+  // Wizard opt-in only (task 1002099 / ADR 0143): when the caller asked to capture
+  // repo access, hand the GitHub access token + granted scope back so the web
+  // callback can persist it (encrypted, short-TTL) for the repo picker/creator.
+  // auth.js stays kernel-clean — it never writes the token to the DB itself; the
+  // token is surfaced ONLY on this opt-in path, so an ordinary hall sign-in never
+  // even returns it.
+  const captured = captureRepoToken ? { githubToken: accessToken, githubScope: grantedScope } : {};
+  return { token, builder, expiresAt, ...captured };
+}
+
+// -------------------------------------------------------------------------
+// Platform IdP web flow (ADR 0141 §1) — the instance as an OAuth client of the hub
+// -------------------------------------------------------------------------
+
+// Build the hub's authorize URL. The instance redirects the browser here (instead
+// of github.com) at /auth/web/start when idpConfigured(). redirectUri is the
+// instance's OWN /auth/web/callback (registered in the hub's sso_clients allow-list
+// by provisioning); state is the same CSRF nonce the callback validates.
+// PURE — construct the hub authorize URL (testable without branding/env). Trailing
+// slashes on origin are trimmed so `https://hub/` and `https://hub` behave alike.
+function idpAuthorizeUrl(origin, clientId, state, redirectUri) {
+  const u = new URL(`${String(origin).replace(/\/+$/, '')}/api/gds/sso/authorize`);
+  u.searchParams.set('client_id', clientId);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('state', state);
+  return u.toString();
+}
+
+function buildIdpAuthorizeUrl(state, redirectUri) {
+  const idp = loadIdpConfig();
+  if (!idp) throw new Error('platform IdP not configured');
+  return idpAuthorizeUrl(idp.origin, idp.clientId, state, redirectUri);
+}
+
+// Server-to-server: redeem the hub authorization code for identity. Authenticates
+// with the instance's client_id + client_secret; the hub returns IDENTITY ONLY
+// (github_id, github_login, display_name, avatar_url) — never a rank (ADR 0141 §2).
+async function exchangeIdpCode({ code, redirectUri, idp }) {
+  const res = await fetch(`${idp.origin}/api/gds/sso/token`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'User-Agent': userAgent(),
+    },
+    body: JSON.stringify({
+      client_id: idp.clientId,
+      client_secret: idp.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`hub /sso/token failed (${res.status}): ${text.slice(0, 200)}`);
+  }
+  const data = await res.json();
+  if (!data || data.github_id == null) {
+    throw new Error('hub /sso/token returned no identity');
+  }
+  return data;
+}
+
+// Complete the instance web sign-in via the hub. Sources identity from the hub's
+// /sso/token, then runs the EXACT SAME admission gate + upsertBuilder +
+// maybeSeatFirstAdmin + createSession(source='web') as completeWebFlow — only the
+// identity SOURCE differs (the hub, not github.com). The shared PURE gate
+// (firstTimeAdmissionBlocked) is what keeps this path from drifting from the direct
+// path (SR-19). Returns the same { token, builder, expiresAt } shape.
+async function completeIdpFlow({ code, redirectUri, userAgent: ua }) {
+  const idp = loadIdpConfig();
+  if (!idp) throw new Error('platform IdP not configured');
+  const identity = await exchangeIdpCode({ code, redirectUri, idp });
+  const ghId = identity.github_id;
+  const ghLogin = identity.github_login;
+  const existing = await getBuilderByGithubId(ghId);
+  if (!existing && !openEnrollmentEnabled()) {
+    const approved = await hasInvitedAccessRequest(ghLogin);
+    if (firstTimeAdmissionBlocked({ existing, approved, login: ghLogin })) {
+      const err = new Error('not_approved');
+      err.code = 'NOT_APPROVED';
+      throw err;
+    }
+  }
+  let builder = await upsertBuilder({
+    githubId: ghId,
+    githubLogin: ghLogin,
+    displayName: identity.display_name || ghLogin,
+    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({
+    builderId: builder.id,
+    token,
+    source: 'web',
+    userAgent: ua ?? null,
+    expiresAt,
+  });
+  await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+  // Fire-and-forget hub membership check-in + activity rollup (ADR 0141 §3/§4) — federated web sign-in.
+  reportMembershipCheckIn({ githubId: ghId, githubLogin: ghLogin, displayName: identity.display_name, avatarUrl: identity.avatar_url });
+  reportActivityRollup({ builderId: builder.id, githubId: ghId });
   return { token, builder, expiresAt };
 }
 
+// -------------------------------------------------------------------------
+// Platform IdP CLI/device flow (ADR 0141 §1) — the instance verifies a hub-signed
+// assertion OFFLINE and mints its own cli session. The CLI runs the device flow
+// against the HUB (GitHub device codes can't cross apps), the hub signs an
+// audience-scoped Ed25519 assertion, and the instance verifies it here with the
+// hub's PUBLIC key (provisioned into env) — no instance->hub call at exchange time.
+// -------------------------------------------------------------------------
+
+const HUB_ASSERTION_ISSUER = 'cloudbongos-hub';
+
+// The hub's Ed25519 PUBLIC key (base64 of the SPKI DER), provisioned into the
+// instance env (<PREFIX>_HUB_PUBLIC_KEY). Returns a KeyObject or null.
+function loadHubPublicKey() {
+  const b64 = ic.resolveEnv('HUB_PUBLIC_KEY');
+  if (!b64) return null;
+  try {
+    return crypto.createPublicKey({ key: Buffer.from(String(b64), 'base64'), format: 'der', type: 'spki' });
+  } catch (err) {
+    console.error('[auth] HUB_PUBLIC_KEY is set but unreadable:', err.message);
+    return null;
+  }
+}
+
+// Verify a hub-signed assertion (the compact-JWT format minted by the hub's
+// platform-identity/hub-keys.js — kept in lockstep across the core<->module
+// boundary, ADR 0091 §2). Verifies the Ed25519 signature FIRST (against the given
+// public key), then the issuer, audience (must equal THIS instance's client_id),
+// and expiry. The verify algorithm is HARDCODED to Ed25519 (`crypto.verify(null,…)`)
+// regardless of the header's `alg` field, so there is no algorithm-confusion attack.
+// Returns the validated payload, or throws. Pure over its inputs (testable).
+function verifyHubAssertion(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 assertion');
+  const [h, p, s] = parts;
+  let header;
+  try { header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8')); }
+  catch { throw new Error('malformed assertion header'); }
+  if (!header || header.alg !== 'EdDSA') throw new Error('unexpected assertion 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('assertion signature invalid');
+  let payload;
+  try { payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8')); }
+  catch { throw new Error('malformed assertion payload'); }
+  if (payload.iss !== HUB_ASSERTION_ISSUER) throw new Error('unexpected assertion issuer');
+  if (clientId != null && String(payload.aud) !== String(clientId)) throw new Error('assertion audience mismatch');
+  if (typeof payload.exp !== 'number' || payload.exp < Math.floor(nowMs / 1000)) throw new Error('assertion expired');
+  if (payload.sub == null || !payload.github_login) throw new Error('assertion missing identity');
+  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
+// sessions even inside its ~120s life. A restart clears it — acceptable given the
+// short window and that the aud binding is the primary control.
+const _seenAssertionJti = new Map(); // jti -> expiry ms
+function _assertionJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
+  for (const [k, exp] of _seenAssertionJti) if (exp < nowMs) _seenAssertionJti.delete(k);
+  if (!jti) return false; // no jti → cannot dedupe (aud + TTL remain the guards)
+  if (_seenAssertionJti.has(jti)) return true;
+  _seenAssertionJti.set(jti, expSeconds ? expSeconds * 1000 : nowMs + 120000);
+  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 }.
+async function completeDeviceExchange({ assertion, userAgent: ua }) {
+  const idp = loadIdpConfig();
+  if (!idp) throw new Error('platform IdP not configured');
+  const publicKey = loadHubPublicKey();
+  if (!publicKey) throw new Error('hub public key not configured');
+  const payload = verifyHubAssertion(assertion, { publicKey, clientId: idp.clientId });
+  // Reject a replayed assertion (same jti) within its window.
+  if (_assertionJtiSeenAndRecord(payload.jti, payload.exp)) {
+    throw new Error('assertion already used');
+  }
+  const ghId = payload.sub;
+  const ghLogin = payload.github_login;
+  const existing = await getBuilderByGithubId(ghId);
+  if (!existing && !openEnrollmentEnabled()) {
+    const approved = await hasInvitedAccessRequest(ghLogin);
+    if (firstTimeAdmissionBlocked({ existing, approved, login: ghLogin })) {
+      const err = new Error('not_approved');
+      err.code = 'NOT_APPROVED';
+      throw err;
+    }
+  }
+  let builder = await upsertBuilder({
+    githubId: ghId,
+    githubLogin: ghLogin,
+    displayName: payload.display_name || ghLogin,
+    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,
+    token,
+    source: 'cli',
+    userAgent: ua ?? null,
+    expiresAt: null,
+  });
+  await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+  // Fire-and-forget hub membership check-in + activity rollup (ADR 0141 §3/§4) — federated CLI sign-in.
+  reportMembershipCheckIn({ githubId: ghId, githubLogin: ghLogin, displayName: payload.display_name, avatarUrl: payload.avatar_url });
+  reportActivityRollup({ builderId: builder.id, githubId: ghId });
+  return { token, builder };
+}
+
 // -------------------------------------------------------------------------
 // Discord OAuth (account-linking — Phase 3 F2, ADR 0033 §2)
 // -------------------------------------------------------------------------
@@ -648,17 +1134,133 @@ 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);
@@ -678,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
@@ -729,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)
@@ -753,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);
+}
+
+// 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);
 }
 
-// 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 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);
 }
 
 // ---------------------------------------------------------------------------
@@ -931,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
@@ -969,23 +1651,43 @@ function requireDiscordBot(req, res, next) {
 
 module.exports = {
   authConfigured,
+  idpEnabled,
+  loadIdpConfig,
+  idpConfigured,
   openEnrollmentEnabled,
   firstTimeAdmissionBlocked,
+  webAdmissionStatus,
   firstAdminLogin,
   maybeSeatFirstAdmin,
   startDeviceFlow,
   pollDeviceFlow,
   buildAuthorizeUrl,
+  scopeForWebFlow,
+  buildIdpAuthorizeUrl,
+  idpAuthorizeUrl,
   completeWebFlow,
+  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)