@bongos/core 1.17.0

package/src/bongos/auth.js

@@ -0,0 +1,979 @@
+// GDS auth (renamed from PMS in V3.R01).
+//
+// Two flows that produce the same `builder_sessions` row:
+//
+// - Device Flow (CLI):
+//     1. POST /api/gds/auth/device/start
+//          → { user_code, verification_uri, device_code, interval, expires_in }
+//          The CLI shows user_code to the user and asks them to open
+//          verification_uri in a browser.
+//     2. CLI polls POST /api/gds/auth/device/poll { device_code }
+//          → 'pending' | 'slow_down' | 'expired' | 'denied' |
+//            { token, builder: {...} }
+//
+// - Web Flow (browser):
+//     1. GET /builders/auth/github → 302 to github.com/login/oauth/authorize
+//     2. GET /builders/auth/github/callback?code=... → exchanges, sets cookie, 302 /builders
+//
+// Both flows hit GitHub's `GET /user` to learn the GitHub user id+login,
+// then upsert into `builders` and create a `builder_sessions` row.
+//
+// Credentials:
+//   GDS_GITHUB_CLIENT_ID / GDS_GITHUB_CLIENT_SECRET in env (systemd EnvironmentFile).
+//   Back-compat: also accepts the legacy PMS_GITHUB_CLIENT_ID / PMS_GITHUB_CLIENT_SECRET
+//   names so the droplet's EnvironmentFile rename can lag the code deploy.
+//   Local-dev fallback: ~/.config/otb/gds-github.json (or legacy pms-github.json).
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Identity/auth/admission + the rank vocabulary are KERNEL primitives — auth.js is
+// a KERNEL_FILE, so it resolves them from ./db-kernel, never the ./db domain residue
+// (ADR 0102, finishing ADR 0091 §1). db.js re-exports the same names for its other
+// callers, so nothing downstream changed.
+const {
+  upsertBuilder,
+  seatFirstAdminIfUnclaimed,
+  createSession,
+  lookupSession,
+  getBuilderById,
+  getBuilderByGithubId,
+  hasInvitedAccessRequest,
+  RANKS,
+} = require('./db-kernel');
+const { pool } = require('./pool');
+// The onboarding state machine carved into modules/onboarding/ (BV1.R81 / ADR
+// 0093 §1). The auth callbacks mark `auth_complete` through the `onboarding`
+// kernel port — never a direct require of a module. Default-on (present in prod);
+// the optional `?.` degrades to a no-op when the module is off (the stage tick is
+// best-effort anyway).
+const seams = require('../module-seams');
+const ic = require('../instance-config');
+const { branding, userAgent } = require('../branding');
+
+const SCOPE = 'read:user';
+
+// 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
+// moving this to Redis or a tiny `device_flows` table.
+const deviceFlows = new Map();
+
+function loadGithubCreds() {
+  // Resolve the configured instance prefix first (CLOUDBONGOS_ on a fresh
+  // instance, OTB_ on this one), then the legacy GDS_/PMS_ names — so the
+  // droplet's EnvironmentFile rename can lag the code deploy without breaking
+  // auth (R61 / task 1200).
+  const clientId = ic.resolveEnv('GITHUB_CLIENT_ID');
+  const clientSecret = ic.resolveEnv('GITHUB_CLIENT_SECRET');
+  if (clientId && clientSecret) {
+    return { client_id: clientId, client_secret: clientSecret };
+  }
+  // Local-dev fallback: try the new filename first, then the legacy one — each
+  // across the configured config dir and the legacy ~/.config/otb dir.
+  for (const name of ['gds-github.json', 'pms-github.json']) {
+    try {
+      const raw = ic.readConfigFileSync(name);
+      if (raw) {
+        const creds = JSON.parse(raw);
+        if (creds.client_id && creds.client_secret) return creds;
+      }
+    } catch (_) {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+function authConfigured() {
+  return !!loadGithubCreds();
+}
+
+// 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
+// Archon marked their access_request 'invited'. An EXISTING builder (a row
+// already exists for their github_id) ALWAYS passes — the gate never locks out
+// someone already enrolled.
+//
+// OTB_OPEN_XENOS_ENROLLMENT is the escape-hatch: set it truthy ('1' or 'true')
+// to restore fully-open self-enrollment (anyone with a GitHub account becomes a
+// Xenos) WITHOUT a code change, for an owner who deliberately wants open
+// enrollment. Default (unset/anything-else) = invite required. See ADR 0050.
+function openEnrollmentEnabled() {
+  const v = ic.resolveEnv('OPEN_XENOS_ENROLLMENT');
+  return v === '1' || v === 'true';
+}
+
+// PURE admission decision shared by both flows so they CANNOT drift (SR-19).
+// Returns true when a first-time account must be blocked. `existing` is the
+// builder row (or null) from getBuilderByGithubId; `approved` is the result of
+// hasInvitedAccessRequest. Blocks only when: not already a builder AND open
+// enrollment is off AND not invite-approved. Exported for direct unit testing.
+function firstTimeAdmissionBlocked({ existing, approved, login }) {
+  if (existing || openEnrollmentEnabled() || approved) return false;
+  // The configured firstAdmin is always admitted on a fresh instance so the
+  // bootstrap (maybeSeatFirstAdmin) can seat them as the first Archon — the owner
+  // must not be gated out of their own new instance when no Archon exists yet to
+  // approve them (the chicken-and-egg R62 / ADR 0062 §6 left open).
+  // seatFirstAdminIfUnclaimed is race-safe and only fires while NO Archon exists,
+  // so this never escalates an account on an established instance; it only lets
+  // the configured owner login through admission.
+  const fa = firstAdminLogin();
+  if (fa && String(login || '').toLowerCase() === fa.toLowerCase()) return false;
+  return true;
+}
+
+// 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
+// auto-seated"; the owner sets it when scaffolding the instance. Trimmed; '' → null.
+function firstAdminLogin() {
+  let login = ic.resolveEnv('FIRST_ADMIN');
+  if (login === undefined) {
+    try { login = branding().firstAdmin; } catch { login = undefined; }
+  }
+  login = (login || '').trim();
+  return login || null;
+}
+
+// Seat the configured firstAdmin as Archon at their first enrollment, but only
+// while NO Archon exists yet (the db guard is atomic + race-safe, so this can
+// never escalate an account once an owner exists). Best-effort: a bootstrap
+// hiccup must never fail the sign-in. Returns the builder, with rank updated to
+// 'archon' on the returned object if this call seated it.
+async function maybeSeatFirstAdmin(builder) {
+  const configured = firstAdminLogin();
+  if (!configured || !builder || builder.rank === 'archon') return builder;
+  if (String(builder.github_login || '').toLowerCase() !== configured.toLowerCase()) return builder;
+  try {
+    const seated = await seatFirstAdminIfUnclaimed(builder.id, builder.github_login);
+    if (seated) {
+      console.log(`[auth] first-admin bootstrap: seated ${builder.github_login} as Archon (configured firstAdmin, no prior Archon).`);
+      return { ...builder, rank: 'archon' };
+    }
+  } catch (err) {
+    console.error('[auth] first-admin bootstrap failed (non-fatal):', err.message);
+  }
+  return builder;
+}
+
+function newSessionToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+// -------------------------------------------------------------------------
+// GitHub helpers
+// -------------------------------------------------------------------------
+
+async function fetchGithubUser(accessToken) {
+  const res = await fetch('https://api.github.com/user', {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'User-Agent': userAgent(),
+      Accept: 'application/vnd.github+json',
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`GitHub /user failed (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+
+async function exchangeCodeForToken(code, redirectUri) {
+  const creds = loadGithubCreds();
+  if (!creds) throw new Error('GitHub OAuth credentials not configured');
+  const res = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: creds.client_id,
+      client_secret: creds.client_secret,
+      code,
+      redirect_uri: redirectUri,
+    }).toString(),
+  });
+  const data = await res.json();
+  if (data.error) throw new Error(`GitHub token exchange: ${data.error_description || data.error}`);
+  return data.access_token;
+}
+
+// -------------------------------------------------------------------------
+// Device Flow (CLI)
+// -------------------------------------------------------------------------
+
+async function startDeviceFlow() {
+  const creds = loadGithubCreds();
+  if (!creds) throw new Error('GitHub OAuth credentials not configured');
+  const res = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({ client_id: creds.client_id, scope: SCOPE }).toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`device/code failed (${res.status}): ${text}`);
+  }
+  const data = await res.json();
+  // data: { device_code, user_code, verification_uri, expires_in, interval }
+  deviceFlows.set(data.device_code, {
+    interval: data.interval || 5,
+    expires_at: Date.now() + data.expires_in * 1000,
+    last_polled_at: 0,
+  });
+  // Reap expired flows (cheap)
+  for (const [k, v] of deviceFlows) {
+    if (v.expires_at < Date.now()) deviceFlows.delete(k);
+  }
+  return {
+    device_code: data.device_code,
+    user_code: data.user_code,
+    verification_uri: data.verification_uri,
+    expires_in: data.expires_in,
+    interval: data.interval || 5,
+  };
+}
+
+async function pollDeviceFlow(deviceCode, userAgent) {
+  const flow = deviceFlows.get(deviceCode);
+  if (!flow) return { state: 'expired' };
+  if (flow.expires_at < Date.now()) {
+    deviceFlows.delete(deviceCode);
+    return { state: 'expired' };
+  }
+  // Server-side throttling: GitHub returns slow_down if we hammer; we
+  // also enforce the interval client-to-server.
+  const now = Date.now();
+  if (now - flow.last_polled_at < flow.interval * 1000) {
+    return { state: 'slow_down', interval: flow.interval };
+  }
+  flow.last_polled_at = now;
+
+  const creds = loadGithubCreds();
+  const res = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: creds.client_id,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    }).toString(),
+  });
+  const data = await res.json();
+  if (data.error === 'authorization_pending') return { state: 'pending' };
+  if (data.error === 'slow_down') {
+    flow.interval = (flow.interval || 5) + 5;
+    return { state: 'slow_down', interval: flow.interval };
+  }
+  if (data.error === 'expired_token') {
+    deviceFlows.delete(deviceCode);
+    return { state: 'expired' };
+  }
+  if (data.error === 'access_denied') {
+    deviceFlows.delete(deviceCode);
+    return { state: 'denied' };
+  }
+  if (data.access_token) {
+    deviceFlows.delete(deviceCode);
+    const ghUser = await fetchGithubUser(data.access_token);
+    // Admission gate (SR-19 / task #1000): mirror completeWebFlow EXACTLY. The
+    // CLI device flow used to call upsertBuilder unconditionally, so any GitHub
+    // account could self-enroll as a Xenos + mint a CLI session with no Archon
+    // approval — contradicting the "Archon admission is the only gate" rule. Now
+    // a FIRST-TIME account (no existing builder row for this github_id) is
+    // admitted only if open enrollment is on OR an Archon marked their
+    // access_request 'invited'. An EXISTING builder ALWAYS passes, so an approved
+    // builder can never be locked out of CLI enrollment. See ADR 0050.
+    const existing = await getBuilderByGithubId(ghUser.id);
+    // Only consult the access_request table for a genuine first-timer (and only
+    // when open enrollment is off) — an existing builder short-circuits to
+    // ALWAYS-pass, matching completeWebFlow's `if (!existing)` lookup.
+    if (!existing && !openEnrollmentEnabled()) {
+      const approved = await hasInvitedAccessRequest(ghUser.login);
+      if (firstTimeAdmissionBlocked({ existing, approved, login: ghUser.login })) {
+        const err = new Error('not_approved');
+        err.code = 'NOT_APPROVED';
+        throw err;
+      }
+    }
+    let builder = await upsertBuilder({
+      githubId: ghUser.id,
+      githubLogin: ghUser.login,
+      displayName: ghUser.name || ghUser.login,
+      avatarUrl: ghUser.avatar_url,
+    });
+    builder = await maybeSeatFirstAdmin(builder);
+    const token = newSessionToken();
+    await createSession({
+      builderId: builder.id,
+      token,
+      source: 'cli',
+      userAgent: userAgent ?? null,
+      // CLI tokens have no expiry (manually revocable). Web tokens expire.
+      expiresAt: null,
+    });
+    // V3.R75 (#294): tick the onboarding state machine. Best-effort — auth
+    // success must NOT fail because the onboarding plumbing tripped.
+    await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+    return { state: 'ok', token, builder };
+  }
+  return { state: 'pending' };
+}
+
+// -------------------------------------------------------------------------
+// Web Flow (browser)
+// -------------------------------------------------------------------------
+
+function buildAuthorizeUrl(state, redirectUri) {
+  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);
+  u.searchParams.set('state', state);
+  return u.toString();
+}
+
+async function completeWebFlow({ code, redirectUri, userAgent }) {
+  const accessToken = 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
+  // Archon (their access_request marked 'invited') before a builder row is
+  // created. This Archon approval is the ONLY gate — newcomers build on hosted
+  // dev boxes, so there is no GitHub repo-access / collaborator check anywhere
+  // (2026-06-07). Established builders (a row already exists for this github_id)
+  // always pass — this only blocks NEW first-time entries.
+  //
+  // SR-19 / task #1000 (2026-06-13): the CLI device flow (pollDeviceFlow,
+  // /builder-setup) is now gated the SAME way — it previously called
+  // upsertBuilder unconditionally, letting any GitHub account self-enroll as a
+  // Xenos with no Archon approval. Both paths share firstTimeAdmissionBlocked()
+  // so they cannot drift. An owner who wants fully-open self-enrollment sets
+  // OTB_OPEN_XENOS_ENROLLMENT truthy (no code change); default = invite required.
+  // See ADR 0050.
+  const existing = await getBuilderByGithubId(ghUser.id);
+  if (!existing && !openEnrollmentEnabled()) {
+    const approved = await hasInvitedAccessRequest(ghUser.login);
+    // Pass `login` so the configured-firstAdmin bypass (firstTimeAdmissionBlocked
+    // L124-125) fires on WEB sign-in too — without it the founding owner is gated
+    // out of their own fresh instance at "The Gate is Closed", a chicken-and-egg
+    // since no Archon exists yet to approve them. The device flow (pollDeviceFlow,
+    // ~L305) already passes login; this keeps the two paths from drifting (SR-19).
+    if (firstTimeAdmissionBlocked({ existing, approved, login: ghUser.login })) {
+      const err = new Error('not_approved');
+      err.code = 'NOT_APPROVED';
+      throw err;
+    }
+  }
+  let builder = await upsertBuilder({
+    githubId: ghUser.id,
+    githubLogin: ghUser.login,
+    displayName: ghUser.name || ghUser.login,
+    avatarUrl: ghUser.avatar_url,
+  });
+  builder = await maybeSeatFirstAdmin(builder);
+  const token = newSessionToken();
+  // Web sessions expire after 30 days; the user re-auths on the page
+  // when the cookie expires.
+  const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+  await createSession({
+    builderId: builder.id,
+    token,
+    source: 'web',
+    userAgent: userAgent ?? null,
+    expiresAt,
+  });
+  // V3.R75 (#294): tick the onboarding state machine. Best-effort.
+  await seams.resolveOptional('onboarding')?.safeMarkStage(pool, builder.id, 'auth_complete', builder);
+  return { token, builder, expiresAt };
+}
+
+// -------------------------------------------------------------------------
+// Discord OAuth (account-linking — Phase 3 F2, ADR 0033 §2)
+// -------------------------------------------------------------------------
+// Links a Discord account to an ALREADY-AUTHENTICATED builder. Client creds
+// come from env (DISCORD_CLIENT_ID / DISCORD_CLIENT_SECRET) or, for local dev,
+// ~/.config/otb/discord-bot.json — same env-first-then-file shape as GitHub.
+// scope=identify (the Discord user id, for the link) + guilds.join (so the
+// server can drop the just-linked builder straight into the guild — the
+// "link-first auto-join" onboarding gate, F7/ADR 0033: a builder approves the
+// link BEFORE entering, so their rank role is already correct on arrival; there
+// is no invite link to share or leak). guilds.join is only USABLE alongside the
+// bot adding the member, and only if the bot holds CREATE_INSTANT_INVITE — see
+// addDiscordGuildMember + docs/discord/role-sync.md. The pure helpers
+// (discordAuthorizeUrl, isValidDiscordUserId) are exported for unit testing
+// without creds or network.
+const DISCORD_SCOPE = 'identify guilds.join';
+
+function loadDiscordCreds() {
+  const clientId = process.env.DISCORD_CLIENT_ID;
+  const clientSecret = process.env.DISCORD_CLIENT_SECRET;
+  if (clientId && clientSecret) return { client_id: clientId, client_secret: clientSecret };
+  try {
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    if (raw) {
+      const creds = JSON.parse(raw);
+      if (creds.client_id && creds.client_secret) {
+        return { client_id: creds.client_id, client_secret: creds.client_secret };
+      }
+    }
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+function discordConfigured() {
+  return !!loadDiscordCreds();
+}
+
+// Bot token loader (Phase 3 F3, ADR 0033 §F3). The bot authenticates to the
+// Discord GATEWAY with a bot token — distinct from the OAuth client_id/secret
+// used for account-linking (F2). Same env-first-then-file shape as everything
+// else: env DISCORD_BOT_TOKEN wins (the systemd path ADR 0022 prefers for the
+// always-on droplet process), else the bot_token field of the local
+// ~/.config/otb/discord-bot.json file (already on the droplet, mode 600). The
+// token is a secret — never log it, never return it anywhere user-facing.
+function loadDiscordBotToken() {
+  const envToken = process.env.DISCORD_BOT_TOKEN;
+  if (envToken) return envToken;
+  try {
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    if (raw) {
+      const creds = JSON.parse(raw);
+      if (creds.bot_token) return creds.bot_token;
+    }
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+function discordBotConfigured() {
+  return !!loadDiscordBotToken();
+}
+
+// PURE — build the Discord authorize URL (testable without creds/network).
+function discordAuthorizeUrl(clientId, state, redirectUri) {
+  const u = new URL('https://discord.com/api/oauth2/authorize');
+  u.searchParams.set('client_id', clientId);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('scope', DISCORD_SCOPE);
+  u.searchParams.set('state', state);
+  return u.toString();
+}
+
+function buildDiscordAuthorizeUrl(state, redirectUri) {
+  const creds = loadDiscordCreds();
+  if (!creds) throw new Error('Discord OAuth credentials not configured');
+  return discordAuthorizeUrl(creds.client_id, state, redirectUri);
+}
+
+async function exchangeDiscordCode(code, redirectUri) {
+  const creds = loadDiscordCreds();
+  if (!creds) throw new Error('Discord OAuth credentials not configured');
+  const res = await fetch('https://discord.com/api/oauth2/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: creds.client_id,
+      client_secret: creds.client_secret,
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+    }).toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Discord token exchange failed (${res.status}): ${text}`);
+  }
+  const data = await res.json();
+  return data.access_token;
+}
+
+async function fetchDiscordUser(accessToken) {
+  const res = await fetch('https://discord.com/api/users/@me', {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Discord /users/@me failed (${res.status}): ${text}`);
+  }
+  return res.json(); // { id, username, ... }
+}
+
+// Kick a member from the guild when they unlink their Discord account (F7
+// follow-up). Uses the bot token only — no user OAuth needed for a kick.
+// Requires the bot to hold Kick Members. Returns { removed: true } on 204
+// (success) or { removed: false, reason } when the member wasn't in the guild
+// (404) or the bot lacks permission (403) — both non-fatal for an unlink.
+// Throws on unexpected errors so the caller can log; unlink itself must still
+// succeed even if the kick can't.
+async function removeDiscordGuildMember({ guildId, discordUserId }) {
+  const botToken = loadDiscordBotToken();
+  if (!botToken) throw new Error('Discord bot token not configured');
+  if (!guildId) throw new Error('Discord guild id not configured');
+  const res = await fetch(`https://discord.com/api/guilds/${guildId}/members/${discordUserId}`, {
+    method: 'DELETE',
+    headers: { Authorization: `Bot ${botToken}` },
+  });
+  if (res.status === 204) return { removed: true };
+  if (res.status === 404) return { removed: false, reason: 'not_in_guild' };
+  if (res.status === 403) return { removed: false, reason: 'missing_permission' };
+  const text = await res.text();
+  throw new Error(`Discord guild remove failed (${res.status}): ${text}`);
+}
+
+// PURE — a Discord user id is a numeric snowflake (17–20 digits). Reject
+// anything else BEFORE it reaches db.linkDiscord (F1 Hacker advisory).
+function isValidDiscordUserId(id) {
+  return typeof id === 'string' && /^\d{17,20}$/.test(id);
+}
+
+// Add the just-linked builder straight into the guild (F7, ADR 0033 — the
+// "link-first auto-join" gate). Uses the user's own OAuth access token (granted
+// via the guilds.join scope) together with the BOT token — Discord's add-member
+// endpoint requires both: the user consent (access_token) and a bot with the
+// CREATE_INSTANT_INVITE permission. `roleIds` are applied at add-time so the
+// member's rank badge is present the instant they arrive (Discord only honors
+// the roles array when CREATING the membership — for an already-present member
+// it 204s and ignores them, which is why the callback also runs syncBuilderRole
+// belt-and-braces). Returns { added } — 201 = newly added, 204 = already a
+// member. Throws on any other status so the caller can log; auto-join is
+// best-effort and must never break the link itself.
+async function addDiscordGuildMember({ guildId, discordUserId, accessToken, roleIds }) {
+  const botToken = loadDiscordBotToken();
+  if (!botToken) throw new Error('Discord bot token not configured');
+  if (!guildId) throw new Error('Discord guild id not configured');
+  const res = await fetch(`https://discord.com/api/guilds/${guildId}/members/${discordUserId}`, {
+    method: 'PUT',
+    headers: { Authorization: `Bot ${botToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ access_token: accessToken, roles: Array.isArray(roleIds) ? roleIds : [] }),
+  });
+  if (res.status === 201 || res.status === 204) return { added: res.status === 201 };
+  const text = await res.text();
+  throw new Error(`Discord guild add failed (${res.status}): ${text}`);
+}
+
+// -------------------------------------------------------------------------
+// Express middleware: authenticate by Bearer token (CLI) or gds_session cookie
+// (web). Legacy pms_session cookie still accepted on read so a builder mid-
+// session at the V3.R01 rollout doesn't have to re-auth.
+// -------------------------------------------------------------------------
+
+// Collect EVERY candidate auth token on the request, in priority order, with
+// duplicates removed. A browser can legitimately carry MORE THAN ONE
+// gds_session cookie: a host-only one (set on amazonprimea.com before the
+// #726/#734 apex-scoping rollout) AND the current apex-scoped one
+// (.amazonprimea.com). The browser sends both in the Cookie header. We must try
+// them ALL — picking only the first (as the old single-value extractToken did)
+// meant a stale/expired duplicate could shadow the live session and 401 the
+// builder (hit on the Discord link callback for builder 25). Order: Bearer
+// (CLI) first, then every gds_session value in header order, then legacy
+// pms_session — so a valid current session always wins over a stale one.
+// SECURITY (#871): cap the number of distinct candidate tokens we will try per
+// request. resolveSession does ONE DB lookup per candidate, so an attacker who
+// stuffs the Cookie header with dozens of gds_session=<junk> values could force
+// dozens of DB round-trips per request (amplification / DoS) even while
+// unauthenticated. A legitimate browser carries at most a Bearer + a couple of
+// gds_session cookies (host-only + apex during the #734 rollout) + one legacy
+// pms_session, so a small cap never hurts a real client.
+const MAX_AUTH_TOKEN_CANDIDATES = 6;
+
+function extractTokens(req) {
+  const out = [];
+  const push = (t) => {
+    if (t && out.length < MAX_AUTH_TOKEN_CANDIDATES && !out.includes(t)) out.push(t);
+  };
+  const auth = req.headers['authorization'] || '';
+  const m = /^Bearer\s+([a-zA-Z0-9]+)$/.exec(auth);
+  if (m) push(m[1]);
+  // Cookie parsing: minimal, no dep. Prefer new name, fall back to legacy.
+  const cookieHeader = req.headers['cookie'] || '';
+  const legacy = [];
+  for (const part of cookieHeader.split(';')) {
+    const idx = part.indexOf('=');
+    if (idx < 0) continue;
+    const k = part.slice(0, idx).trim();
+    const v = part.slice(idx + 1).trim();
+    if (k === 'gds_session' && v) push(v);
+    else if (k === 'pms_session' && v) legacy.push(v);
+  }
+  for (const v of legacy) push(v);
+  return out;
+}
+
+// Resolve the request to a live session by trying every candidate token until
+// one maps to a non-revoked, unexpired session. Returns null if none do.
+async function resolveSession(req) {
+  for (const token of extractTokens(req)) {
+    const session = await lookupSession(token);
+    if (session) return session;
+  }
+  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();
+}
+
+async function requireBuilder(req, res, next) {
+  const session = await resolveSession(req);
+  if (!session) {
+    res.fail('unauthenticated', 401);
+    return;
+  }
+  // SECURITY (#871): a deactivated/offboarded builder must not retain API access
+  // even if a live (unrevoked) session token survives. deactivateBuilder now
+  // revokes sessions on exit, but this is the belt-and-braces hot-path gate that
+  // also closes any session minted before that fix (and the never-expiring CLI
+  // tokens). Deny ONLY on the known 'inactive' status — never on a missing/
+  // unknown value — so an active builder can never be locked out by this check.
+  // status is read fresh per request via lookupSession (never cached), so a
+  // later reactivation takes effect on the builder's very next request.
+  if (session.status === 'inactive') {
+    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.' });
+    return;
+  }
+  // Anthropic-identity pin — REMOVED (task 1039, idea 258). This used to 403
+  // `identity_mismatch` when a linked builder's CLI echoed an X-Anthropic-User
+  // header that differed from the stored anthropic_user_id (V3.R10 #235, C3).
+  // It is gone because:
+  //   - The drachmae reward values work at a UNIFORM server-side list price
+  //     (ADR 0054), NOT against each builder's own Anthropic account, so there
+  //     is no economic reason to bind a session to one Anthropic identity —
+  //     attribution is simply the GDS session-token holder.
+  //   - The pin locked a linked builder out of their OWN session the moment
+  //     they used a second Claude account; multi-account is fine.
+  //   - It was attestation, not strong auth — an attacker bypasses it by
+  //     omitting the header — so it added friction with no real security value.
+  // anthropic_email / anthropic_user_id are still captured at link time as
+  // optional cosmetic attribution; they are no longer an auth boundary, and the
+  // X-Anthropic-User header is no longer read here.
+  req.gdsSession = session;
+  req.builder = {
+    id: session.builder_id,
+    github_id: session.github_id,
+    github_login: session.github_login,
+    display_name: session.display_name,
+    avatar_url: session.avatar_url,
+    total_credits: session.total_credits,
+    status: session.status ?? null,
+    // rank is the single source of authority (ADR 0016). Read fresh from the
+    // DB on every request via lookupSession — never cached, never from the
+    // token — so demotion takes effect on the builder's very next request.
+    rank: session.rank,
+    // system_role identifies a non-human service principal (NULL for every
+    // human builder). The BFG cross-builder write gate (requireBfgPrincipal)
+    // keys on this EXACT value — never on rank — so an Archon token cannot
+    // reach the write path (ADR 0026 §6C). Read fresh per request like rank.
+    system_role: session.system_role ?? null,
+  };
+  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)
+// and also falls back to Referer, so this is belt-and-braces for navigations
+// where Referer may be stripped. Returns '' if the host can't be determined.
+function signInWithReturn(req) {
+  const base = '/api/gds/auth/web/start';
+  const proto = req.headers['x-forwarded-proto'] || (req.secure ? 'https' : 'http');
+  const host = req.headers['x-forwarded-host'] || req.headers['host'];
+  if (!host) return base;
+  return `${base}?return=${encodeURIComponent(`${proto}://${host}${req.originalUrl}`)}`;
+}
+
+async function requireBuilderPage(req, res, next) {
+  try {
+    const session = await resolveSession(req);
+    if (!session) {
+      res.redirect(302, signInWithReturn(req));
+      return;
+    }
+    next();
+  } 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));
+  }
+}
+
+// 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) {
+  try {
+    const session = await resolveSession(req);
+    if (!session) {
+      res.redirect(302, signInWithReturn(req));
+      return;
+    }
+    if (session.rank !== 'archon') {
+      res.redirect(302, '/builders');
+      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] requireArchonPage lookup failed', err);
+    res.redirect(302, signInWithReturn(req));
+  }
+}
+
+// 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.
+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));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route-gate inventory (V3.R06 #231) — the canonical "who can call what" list.
+// Derived from ADR 0016's fail-closed rule: privileged routes that mutate
+// SHARED plan/scope state default to archon; review/triage routes go to
+// metic+archon (#360); routes scoped to a builder's OWN work/contributions
+// stay open to any authenticated builder (a Xenos additionally limited to
+// xenos_claimable tasks at claim time). Reads + auth/identity are never gated.
+//
+//   archon-only (requireRank('archon')) — ratification / scope / infra:
+//     POST   /tasks                         create work
+//     PATCH  /tasks/:id                      edit work (incl. xenos_claimable)
+//     POST   /tasks/:id/promote              backlog→ready
+//     POST/PUT/DELETE /tasks/:id/dependencies  reshape the dep graph
+//     POST   /tasks/:id/confirm              grader-bypass override
+//     POST   /done-when/:id/{satisfy,unsatisfy}  version scope
+//     PATCH  /builders/:id/rank, /builders/:id/status  rank/exit (Archon-only)
+//
+//   metic+archon (requireRank('metic','archon')) — the approved working rank's
+//   review/triage powers, per criterion C2 (#360 / ADR 0018):
+//     PATCH  /inbox/:id                      idea triage (promote/discard/merge)
+//     POST   /blockers/:id/resolve           unblocks tasks (blocker review)
+//     POST   /blockers/:id/link              blocker review
+//
+//   open to any AUTHENTICATED builder (requireBuilder only) — own work, BUT a
+//   Xenos can only CLAIM tasks flagged xenos_claimable (gated in db.claimTask /
+//   claimTasksBatch, #360). Contributions:
+//     POST   /claims, /claims/batch, /claims/:id/resolve   claim + ship own work
+//     POST   /tasks/:id/ship, /tasks/:id/grade             own ship flow
+//     POST   /cost                          log cost on own claim
+//     POST   /learnings                     capture a learning
+//     POST   /blockers                      FILE a blocker
+//     POST   /inbox                         FILE an idea
+//     POST   /session/optimize              pick own next work
+//     POST   /sessions                      upload own session digest (6D.1)
+//     POST   /auth/logout                   own session
+//
+//   reads / public / auth: GET *, /healthz, /public/*, /auth/device|web/*.
+//
+// Three ranks are LIVE (#360 / ADR 0018): archon, metic, xenos (default).
+// Fail-closed rule stands: a NEW privileged mutating route defaults to
+// requireRank('archon') until a lower rank is explicitly granted. The periodic
+// auditor (#265 / V3.R45) mechanically asserts no privileged mutating route is
+// left without a rank gate.
+// ---------------------------------------------------------------------------
+
+// requireRank(...allowed) — authorization middleware (V3.R05 #106; made
+// threshold-based in #591).
+//
+// Runs AFTER requireBuilder, so req.builder.rank is the live DB value. 403s
+// with a structured body if the builder's rank is below the gate. This is the
+// enforcement point of the trust boundary documented in ADR 0016: the server
+// checks a value the builder's machine cannot write.
+//
+// THRESHOLD, not exact-match (#591). The rank ladder (db.RANKS) is hierarchical
+// — lower index = higher authority (olympian … archon … metic … helot). The old
+// gate authorized by exact set membership (`allowedSet.has(actual)`), which
+// silently denied every rank ABOVE the listed one: a builder promoted to a
+// "divine" rank (olympian/hermes/oracle/demigod — documented as above-the-system,
+// strictly above archon) FAILED requireRank('archon') and lost all archon-gated
+// authority instead of inheriting it. We now admit any rank AT-OR-ABOVE the
+// lowest-authority rank named in `allowed`. So requireRank('archon') admits
+// archon and every divine rank above it; requireRank('metic','archon') admits
+// metic, archon, and everything above — and still blocks thetes/xenos. The
+// `required` field in the 403 body keeps reporting the literal allow-list so the
+// route's intent (and existing clients) read unchanged.
+//
+// Fail-closed (matches the posture of xenosClaimAllowed/#510): an actual rank
+// not in RANKS (unknown / typo / legacy / null) is denied, and a misconfigured
+// gate whose allowed ranks are ALL unknown denies everyone.
+//
+// Usage: router.post('/tasks', auth.requireBuilder, auth.requireRank('archon'), handler)
+function rankMeetsThreshold(actual, allowed) {
+  const actualIdx = RANKS.indexOf(actual);
+  if (actualIdx === -1) return false; // unknown/missing actual rank → fail closed
+  // The gate's floor is the LOWEST-authority (largest-index) rank in `allowed`;
+  // unknown allowed ranks are ignored so a typo can't silently widen the gate.
+  const floorIdx = allowed.reduce((max, r) => {
+    const i = RANKS.indexOf(r);
+    return i === -1 ? max : Math.max(max, i);
+  }, -1);
+  if (floorIdx === -1) return false; // no valid allowed rank → fail closed
+  return actualIdx <= floorIdx; // at or above the floor
+}
+
+function requireRank(...allowed) {
+  return function rankGate(req, res, next) {
+    const actual = req.builder && req.builder.rank;
+    if (!rankMeetsThreshold(actual, allowed)) {
+      res.fail('rank_forbidden', 403, { required: [...allowed], actual: actual ?? null });
+      return;
+    }
+    next();
+  };
+}
+
+// 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
+// service principal, so the gate checks the EXACT identity (system_role='bfg'),
+// which only the BFG principal's `builders` row carries. An Archon token — or
+// any rank-escalated / stolen token — has system_role=NULL and is rejected with
+// 403. This is the enforcement the ADR demands ("gate on the exact principal
+// identity, not on rank... an Archon token must be rejected"), not prose intent.
+// Pure + exported so the gate behavior is unit-tested directly.
+function requireBfgPrincipal(req, res, next) {
+  const role = req.builder && req.builder.system_role;
+  if (role !== 'bfg') {
+    res.fail('not_bfg_principal', 403);
+    return;
+  }
+  next();
+}
+
+// requireDiscordBot — the identity gate for the Discord bot service principal
+// (Discord Phase 3, ADR 0033 §1). Like requireBfgPrincipal, this is an IDENTITY
+// gate, NOT a rank gate: it keys on the EXACT system_role='discord_bot', which
+// only the bot principal's `builders` row carries. An Archon token — or any
+// rank-escalated / stolen human token — has system_role=NULL and is rejected
+// (403); so is a DIFFERENT system principal (the BFG). The bot is trusted ONLY
+// to assert a self-linked Discord→builder mapping; every endpoint behind this
+// gate still re-checks the linked builder's LIVE rank before any write, so a
+// Discord reaction can never escalate past what that builder may already do.
+function requireDiscordBot(req, res, next) {
+  const role = req.builder && req.builder.system_role;
+  if (role !== 'discord_bot') {
+    res.fail('not_discord_bot_principal', 403);
+    return;
+  }
+  next();
+}
+
+module.exports = {
+  authConfigured,
+  openEnrollmentEnabled,
+  firstTimeAdmissionBlocked,
+  firstAdminLogin,
+  maybeSeatFirstAdmin,
+  startDeviceFlow,
+  pollDeviceFlow,
+  buildAuthorizeUrl,
+  completeWebFlow,
+  extractTokens,
+  resolveSession,
+  allowBoxScope,
+  requireBuilder,
+  requireBuilderPage,
+  requireArchonPage,
+  requireNonXenosPage,
+  requireRank,
+  rankMeetsThreshold,
+  requireBfgPrincipal,
+  requireDiscordBot,
+  // Discord OAuth (account-linking — Phase 3 F2, ADR 0033)
+  loadDiscordCreds,
+  discordConfigured,
+  loadDiscordBotToken,
+  discordBotConfigured,
+  discordAuthorizeUrl,
+  buildDiscordAuthorizeUrl,
+  exchangeDiscordCode,
+  fetchDiscordUser,
+  isValidDiscordUserId,
+  addDiscordGuildMember,
+  removeDiscordGuildMember,
+};