@bongos/core 1.17.0

package/src/bongos/routes/auth.js

@@ -0,0 +1,755 @@
+const express = require('express');
+const crypto = require('node:crypto');
+
+const auth = require('../auth');
+const db = require('../db');
+const { pairStore } = require('../app-pair');
+const { publicOrigin, parseCookie, validateOrRespond } = require('./_helpers');
+const { branding } = require('../../branding');
+const seams = require('../../module-seams');
+
+function escapeHtml(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+// Render a small standalone HTML page in the builders' hall palette. Used for
+// OAuth error branches so the visitor sees something coherent rather than a
+// text/plain trace. Kept inline (no template engine) so it has no runtime deps.
+// opts (all optional):
+//   subtitle — replaces the default header sub-line
+//   cta      — { href, label } for the primary button (default: retry sign-in)
+//   note     — replaces the default troubleshooting footnote
+function renderAuthErrorPage(heading, detail, opts = {}) {
+  // Every fixed string on this page — the tab-title suffix, epigraph, page
+  // heading, sub-line, and retry button — is owned by the instance branding
+  // pack (config/branding.json `copy.authError`) so a non-OTB instance renders
+  // its OWN words, never OTB lore, on cloudbongos.com and beyond (ADR 0062 §3;
+  // task 1439 / idea #351). It is resolved defensively — a branding hiccup
+  // falls back to neutral copy rather than crashing the error page, mirroring
+  // the worldName pattern below. `authError` is server-only (rendered here), so
+  // it is deliberately NOT part of the clientBranding allow-list. Callers may
+  // still override the sub-line / cta / note per error branch via `opts`.
+  const AUTH_ERROR_FALLBACK = {
+    titleSuffix: 'sign-in failed',
+    epigraph: '— access —',
+    heading: 'Sign-in failed',
+    subtitle: "The sign-in didn't complete. Try again, or contact the owner.",
+    ctaLabel: 'Try signing in again',
+  };
+  const copy = (() => {
+    try { return { ...AUTH_ERROR_FALLBACK, ...(branding().copy?.authError || {}) }; }
+    catch { return AUTH_ERROR_FALLBACK; }
+  })();
+  const subtitle = opts.subtitle || copy.subtitle;
+  const cta = opts.cta || { href: '/api/gds/auth/web/start', label: copy.ctaLabel };
+  const note = opts.note || "If this keeps happening, the GitHub OAuth app's authorized callback URL may be misconfigured. See docs/recipes/ops-gotchas.md (GitHub OAuth section).";
+  // The instance name in the tab title comes from the branding pack, never a
+  // hardcoded host brand — a non-OTB instance sees its own name (ADR 0062 §3).
+  const worldName = (() => { try { return branding().identity?.worldName || 'The city'; } catch { return 'The city'; } })();
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(worldName)} — ${escapeHtml(copy.titleSuffix)}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@500;700&family=EB+Garamond:ital,wght@0,400;0,500&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="/builders/style.css">
+</head><body>
+<header class="hall">
+  <p class="hall__epigraph">${escapeHtml(copy.epigraph)}</p>
+  <h1>${escapeHtml(copy.heading)}</h1>
+  <p class="hall__sub">${escapeHtml(subtitle)}</p>
+</header>
+<main>
+  <section class="scroll">
+    <div class="landing">
+      <div class="landing__error">
+        <p class="landing__error-h">${escapeHtml(heading)}</p>
+        <p>${escapeHtml(detail)}</p>
+      </div>
+      <p class="landing__cta">
+        <a class="landing__btn" href="${escapeHtml(cta.href)}">${escapeHtml(cta.label)}</a>
+      </p>
+      <p class="landing__note">${escapeHtml(note)}</p>
+    </div>
+  </section>
+</main>
+</body></html>`;
+}
+
+// Cookie names. The web flow writes the new `gds_session` (+ `gds_oauth_state`)
+// names; both flows accept either the new or the legacy `pms_session` /
+// `pms_oauth_state` cookies on read so a builder mid-flow doesn't have to
+// re-auth at the rename rollout.
+const SESSION_COOKIE = 'gds_session';
+const SESSION_COOKIE_LEGACY = 'pms_session';
+const STATE_COOKIE = 'gds_oauth_state';
+const STATE_COOKIE_LEGACY = 'pms_oauth_state';
+const DISCORD_STATE_COOKIE = 'gds_discord_state';
+// Short-lived cookie carrying a validated post-sign-in return URL so the web
+// flow can land a builder back on the subdomain they started from (#726). Set
+// at /auth/web/start, consumed + cleared at the callback. Defaults to /builders.
+const RETURN_COOKIE = 'gds_return';
+
+// The apex domain the instance is served under, read from the instance branding
+// pack's cookieDomain (".amazonprimea.com" → "amazonprimea.com",
+// ".cloudbongos.com" → "cloudbongos.com"). The session + OAuth-state cookies are
+// scoped to ".<apex>" so a single sign-in is shared across every subdomain
+// (apex, builders., status.) — the enabler for the dedicated builders subdomain
+// (#726). MUST come from config, not a hardcoded literal: a hardcoded
+// "amazonprimea.com" made every OTHER instance (e.g. cloudbongos.com) set a
+// cookie for the wrong domain, which the browser drops → the OAuth state cookie
+// never persisted → "state mismatch / the gate is closed" (ADR 0062 §3/§5: domains
+// woven into auth, config swaps must not widen cookie scope). Each instance scopes
+// its OWN apex; neither can set the other's cookie. An instance with no
+// cookieDomain (localhost dev, a misconfigured pack) → "" → host-only cookies
+// everywhere (fail-safe, never cross-host). Resolved once at module load (the
+// brand is a per-process singleton).
+function configuredCookieApex() {
+  try {
+    return String(branding().domains?.cookieDomain || '').replace(/^\./, '').toLowerCase();
+  } catch {
+    return '';
+  }
+}
+const COOKIE_APEX = configuredCookieApex();
+
+// Reqest host, lowercased, port-stripped. x-forwarded-host wins behind the proxy.
+function reqHost(req) {
+  const raw = req.headers['x-forwarded-host'] || req.headers['host'] || '';
+  return String(raw).toLowerCase().split(',')[0].trim().split(':')[0];
+}
+
+// The production-facing hosts that share one sign-in. Deliberately enumerated
+// (not "any *.amazonprimea.com") so staging.amazonprimea.com — a SEPARATE
+// process + DB on :3001 — keeps a host-only cookie and never bleeds an
+// apex-scoped token into prod (or vice versa).
+// When COOKIE_APEX is "" (localhost / no configured cookieDomain) the set is
+// EMPTY → every host gets a host-only cookie (never a "." + "" = ".<empty>" leak).
+const APEX_COOKIE_HOSTS = new Set(
+  COOKIE_APEX
+    ? [COOKIE_APEX, 'www.' + COOKIE_APEX, 'builders.' + COOKIE_APEX, 'status.' + COOKIE_APEX]
+    : []
+);
+
+// Cookie attributes that vary by host. On the production-facing hosts the
+// session cookie is scoped to the apex so it crosses subdomains (the enabler
+// for builders.amazonprimea.com, #726); everywhere else (localhost, staging)
+// it stays host-only. Returns a spread-able object.
+function sessionCookieDomainOpts(req) {
+  if (APEX_COOKIE_HOSTS.has(reqHost(req))) {
+    return { domain: '.' + COOKIE_APEX };
+  }
+  return {};
+}
+
+// Validate a caller-supplied post-sign-in return target. Accept ONLY:
+//   - a relative path beginning with a single '/' (not '//', no backslash), or
+//   - an absolute https URL whose host is the apex or a *.amazonprimea.com sub.
+// Anything else (other origins, javascript:, protocol-relative) → null, so the
+// caller falls back to the safe default. This is an open-redirect guard.
+function safeReturnTo(raw) {
+  if (!raw || typeof raw !== 'string' || raw.length > 512) return null;
+  // Relative path — must start with exactly one slash and no backslash.
+  if (raw.startsWith('/')) {
+    if (raw.startsWith('//') || raw.includes('\\')) return null;
+    return raw;
+  }
+  let u;
+  try { u = new URL(raw); } catch { return null; }
+  if (u.protocol !== 'https:') return null;
+  const h = u.hostname.toLowerCase();
+  if (h === COOKIE_APEX || h.endsWith('.' + COOKIE_APEX)) return u.toString();
+  return null;
+}
+
+// The canonical sign-in origin, read from the instance branding pack (oauthOrigin,
+// else publicOrigin) so a non-OTB Cloud Bongos instance pins its OAuth redirects to
+// ITS OWN apex instead of a hardcoded "amazonprimea.com" (ADR 0062 §3/§5; the
+// branding contract). The fixed GDS_PUBLIC_ORIGIN env knob still wins for
+// dev/staging (auth.js's documented FIXED env name, not a <PREFIX>_ one). Resolved
+// once at module load; falls back to '' if branding fails, which leaves the env knob
+// as the sole source rather than baking in a host brand.
+function configuredOAuthOrigin() {
+  try {
+    const d = branding().domains || {};
+    return String(d.oauthOrigin || d.publicOrigin || '');
+  } catch {
+    return '';
+  }
+}
+
+// The OAuth redirect_uri must be a FIXED, registered origin — never derived from
+// the request's x-forwarded-host (spoofable; F2 Hacker finding). Configured via
+// env, falling back to the configured canonical public origin, so an injected host
+// cannot rewrite the redirect and Discord's URI registration is not the SOLE backstop.
+const DISCORD_REDIRECT_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || configuredOAuthOrigin();
+const DISCORD_REDIRECT_URI = `${DISCORD_REDIRECT_ORIGIN}/api/gds/auth/discord/callback`;
+
+// The GitHub web-OAuth redirect_uri origin (#734). PINNED to the canonical
+// public origin (same env knob as Discord), never the request host — GitHub
+// matches redirect_uri against the app's single registered callback host, so a
+// sign-in started on a builders.* subdomain must still use the apex.
+const WEB_REDIRECT_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || configuredOAuthOrigin();
+
+module.exports = function buildAuthRouter() {
+  const router = express.Router();
+
+  // /auth/device — CLI flow
+  // rank: public — auth flow itself; identity establishment, not authorization.
+  router.post('/auth/device/start', async (_req, res) => {
+    if (!auth.authConfigured()) {
+      return res.fail('auth_not_configured', { status: 503, message: 'GitHub OAuth App credentials missing on the server. See blockers/blockers.md#github-oauth-app.' });
+    }
+    try {
+      const out = await auth.startDeviceFlow();
+      res.json(out);
+    } catch (err) {
+      console.error('[gds] device/start', err);
+      res.fail('device_start_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: public — auth flow; the device code itself is the bearer.
+  router.post('/auth/device/poll', async (req, res) => {
+    if (!auth.authConfigured()) {
+      return res.fail('auth_not_configured', 503);
+    }
+    if (validateOrRespond(req, res, {
+      device_code: { required: true, type: 'string', maxLength: 256 },
+    })) return;
+    const { device_code: deviceCode } = req.body || {};
+    if (!deviceCode) return res.fail('device_code_required', 400);
+    try {
+      const out = await auth.pollDeviceFlow(deviceCode, req.headers['user-agent']);
+      res.json(out);
+    } catch (err) {
+      // Admission gate (SR-19 / task #1000): a first-time GitHub account that
+      // hasn't been approved by an Archon can't self-enroll via the CLI device
+      // flow either (mirrors the web /auth/web/callback NOT_APPROVED branch).
+      // Return a structured 403 with state:'not_approved' so setup.js can print a
+      // friendly "ask an Archon to invite you" message instead of a raw error.
+      if (err && err.code === 'NOT_APPROVED') {
+        return res.status(403).json({ state: 'not_approved', error: 'not_approved' });
+      }
+      console.error('[gds] device/poll', err);
+      res.fail('device_poll_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // /auth/web — browser flow (used by the /builders page).
+  // rank: public — entry into the GitHub OAuth handshake.
+  router.get('/auth/web/start', (req, res) => {
+    if (!auth.authConfigured()) {
+      return res.status(503).type('text/plain').send('auth not configured');
+    }
+    const state = crypto.randomBytes(16).toString('hex');
+    // redirect_uri is PINNED to the canonical origin (#734) — never derived from
+    // the request host. GitHub only knows the apex callback, so a sign-in begun
+    // on builders.amazonprimea.com must still hand GitHub the apex redirect_uri
+    // or GitHub rejects it. Same posture the Discord flow already uses.
+    const redirectUri = `${WEB_REDIRECT_ORIGIN}/api/gds/auth/web/callback`;
+    res.cookie(STATE_COOKIE, state, {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+      maxAge: 10 * 60 * 1000,
+      // Apex-scoped (#734) so the state survives the host switch: start may run
+      // on the subdomain but the callback always lands on the apex.
+      ...sessionCookieDomainOpts(req),
+    });
+    // Post-sign-in return target (#726/#734): an explicit ?return= wins (set by
+    // the page gates); otherwise fall back to the Referer (the page that kicked
+    // off sign-in), so the dozens of client 401 redirects land a builder back
+    // where they were with no per-call-site change. Both go through the
+    // open-redirect allowlist (relative path or *.amazonprimea.com https).
+    const returnTo = safeReturnTo(req.query.return) || safeReturnTo(req.headers.referer);
+    if (returnTo) {
+      res.cookie(RETURN_COOKIE, returnTo, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+        maxAge: 10 * 60 * 1000,
+        ...sessionCookieDomainOpts(req),
+      });
+    }
+    res.redirect(auth.buildAuthorizeUrl(state, redirectUri));
+  });
+
+  // rank: public — OAuth callback; the state cookie + code are the bearer.
+  router.get('/auth/web/callback', async (req, res) => {
+    if (!auth.authConfigured()) {
+      return res.status(503).type('text/plain').send('auth not configured');
+    }
+    const expectedState = parseCookie(req, STATE_COOKIE) || parseCookie(req, STATE_COOKIE_LEGACY);
+    const { state, code, error } = req.query;
+    if (error) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'GitHub refused the handshake',
+        `GitHub returned the error code "${error}". This usually means the OAuth app's authorized callback URL doesn't include this server's /api/gds/auth/web/callback path.`,
+      ));
+    }
+    if (!code || !state || state !== expectedState) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'State mismatch',
+        'The handshake-cookie did not match the state GitHub returned. This usually means the sign-in took too long (cookie expired after 10 minutes) or the request crossed an origin boundary. Start over and the gate will open.',
+      ));
+    }
+    try {
+      // Must match the PINNED redirect_uri used at /auth/web/start (#734) — the
+      // GitHub token exchange requires an exact string match.
+      const redirectUri = `${WEB_REDIRECT_ORIGIN}/api/gds/auth/web/callback`;
+      const { token, expiresAt } = await auth.completeWebFlow({
+        code,
+        redirectUri,
+        userAgent: req.headers['user-agent'],
+      });
+      res.cookie(SESSION_COOKIE, token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+        path: '/',
+        expires: expiresAt,
+        // Apex-scoped on the production hosts so one sign-in spans
+        // amazonprimea.com + builders. + status. (#726); host-only elsewhere.
+        ...sessionCookieDomainOpts(req),
+      });
+      // The state cookie is apex-scoped now (#734) — clear it with the same
+      // domain or the browser keeps it. Clear the host-only form too for any
+      // cookie set before this change.
+      const domainOpts = sessionCookieDomainOpts(req);
+      res.clearCookie(STATE_COOKIE);
+      res.clearCookie(STATE_COOKIE_LEGACY);
+      if (domainOpts.domain) {
+        res.clearCookie(STATE_COOKIE, domainOpts);
+        res.clearCookie(STATE_COOKIE_LEGACY, domainOpts);
+      }
+      // Land back where sign-in began if a validated return target was stashed
+      // (e.g. the builders subdomain bounced through here); else the hall.
+      const returnTo = safeReturnTo(parseCookie(req, RETURN_COOKIE));
+      res.clearCookie(RETURN_COOKIE, domainOpts);
+      res.redirect(returnTo || '/builders');
+    } catch (err) {
+      // Approval gate (2026-05-30): a first-time GitHub account that hasn't been
+      // approved by an Archon can't enter. Send them to the hall to request
+      // access rather than dead-ending on a generic error.
+      if (err && err.code === 'NOT_APPROVED') {
+        return res.status(403).type('text/html').send(renderAuthErrorPage(
+          'This account is not approved yet',
+          'Signing in with GitHub is only for builders an Archon has already approved. If you are new, request access at the builders’ hall — an Archon will approve you, then this sign-in will let you in. If you were just approved, the Archon may still need to mark you invited; give it a moment and try again.',
+          {
+            subtitle: 'Sign-in is for approved builders. New here? Request access first.',
+            cta: { href: '/builders', label: 'Go to the hall & request access' },
+            note: 'Already approved and still blocked? Ask the Archon to confirm your request was marked “invited.”',
+          },
+        ));
+      }
+      console.error('[gds] web/callback', err);
+      res.status(500).type('text/html').send(renderAuthErrorPage(
+        'The handshake threw an error',
+        `The server tried to exchange the auth code for a session and something went wrong: ${err.message}. Try again; if it persists, the Archon must investigate the server logs.`,
+      ));
+    }
+  });
+
+  // /auth/discord — account-linking OAuth (Phase 3 F2, ADR 0033 §2). Links a
+  // Discord account to the ALREADY-AUTHENTICATED builder (gds_session cookie):
+  // the link is self-asserted by the builder, never invented by the bot. Inert
+  // (503) until the server has Discord client creds. Mirrors the GitHub web
+  // flow's CSRF-state discipline above — a hard requirement (ADR 0033 §2).
+  // rank: any-builder — links to your OWN identity; no rank gate.
+  router.get('/auth/discord/start', auth.requireBuilder, (req, res) => {
+    if (!auth.discordConfigured()) {
+      return res.status(503).type('text/plain').send('Discord linking not configured on this server yet.');
+    }
+    const state = crypto.randomBytes(16).toString('hex');
+    const redirectUri = DISCORD_REDIRECT_URI;
+    res.cookie(DISCORD_STATE_COOKIE, state, {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+      maxAge: 10 * 60 * 1000,
+      // Apex-scoped (#734 parity) so the state survives the host switch: the
+      // link may start on builders.amazonprimea.com but DISCORD_REDIRECT_URI
+      // always lands the callback on the apex. A host-only cookie would be
+      // dropped on the hop and the state check would fail ("Link handshake
+      // expired"). Mirrors the GitHub web-flow state cookie above.
+      ...sessionCookieDomainOpts(req),
+    });
+    res.redirect(auth.buildDiscordAuthorizeUrl(state, redirectUri));
+  });
+
+  // rank: any-builder — completes the link to the caller's own identity.
+  router.get('/auth/discord/callback', auth.requireBuilder, async (req, res) => {
+    if (!auth.discordConfigured()) {
+      return res.status(503).type('text/plain').send('Discord linking not configured on this server yet.');
+    }
+    const expectedState = parseCookie(req, DISCORD_STATE_COOKIE);
+    const { state, code, error } = req.query;
+    // The state cookie is apex-scoped now (#734 parity) — clear it with the
+    // same domain or the browser keeps it. Clear the host-only form too for any
+    // cookie set before this change.
+    const stateDomainOpts = sessionCookieDomainOpts(req);
+    res.clearCookie(DISCORD_STATE_COOKIE);
+    if (stateDomainOpts.domain) res.clearCookie(DISCORD_STATE_COOKIE, stateDomainOpts);
+    // CSRF FIRST: validate the state cookie against the state Discord echoes
+    // back BEFORE trusting any other param (including Discord's `error`). A
+    // forged callback with no valid state — even one carrying `?error=...` — is
+    // rejected here, so it can't surface an attacker-chosen message or burn a
+    // mid-flow builder's link. Without this a forged callback could otherwise
+    // link an attacker's Discord to this builder (ADR 0033 §2).
+    if (!state || state !== expectedState) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'Link handshake expired',
+        'The link-cookie did not match what Discord returned (the sign-in may have taken too long, or crossed an origin). Start over from the hall.',
+        { cta: { href: '/builders', label: 'Back to the hall' } },
+      ));
+    }
+    if (error) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'Discord refused the link',
+        `Discord returned "${error}". Try linking again from the builders' hall.`,
+        { cta: { href: '/builders', label: 'Back to the hall' } },
+      ));
+    }
+    if (!code) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'Link handshake incomplete',
+        'Discord did not return an authorization code. Start over from the hall.',
+        { cta: { href: '/builders', label: 'Back to the hall' } },
+      ));
+    }
+    try {
+      const redirectUri = DISCORD_REDIRECT_URI;
+      const accessToken = await auth.exchangeDiscordCode(code, redirectUri);
+      const dUser = await auth.fetchDiscordUser(accessToken);
+      // Validate the snowflake BEFORE touching the DB (F1 Hacker advisory): a
+      // malformed/oversized id never enters discord_links.
+      if (!auth.isValidDiscordUserId(dUser && dUser.id)) {
+        return res.status(400).type('text/html').send(renderAuthErrorPage(
+          'Could not read your Discord identity',
+          'Discord did not return a valid account id. Try again from the hall.',
+          { cta: { href: '/builders', label: 'Back to the hall' } },
+        ));
+      }
+      const result = await db.linkDiscord({ builderId: req.builder.id, discordUserId: dUser.id });
+      if (!result.ok && result.error === 'discord_taken') {
+        return res.status(409).type('text/html').send(renderAuthErrorPage(
+          'That Discord account is already linked',
+          'This Discord account is linked to a different builder. Unlink it there first, or link a different Discord account.',
+          { cta: { href: '/builders', label: 'Back to the hall' } },
+        ));
+      }
+      // F7 auto-join (ADR 0033 — the link-first onboarding gate): now that the
+      // builder has self-asserted this Discord account, drop them straight into
+      // the guild with their rank role set at add-time, so the role is correct
+      // the instant they arrive (no invite link to share or leak). Best-effort:
+      // the link must succeed even if the bot is off / lacks CREATE_INSTANT_INVITE
+      // / can't reach Discord. We await so a failure can fall through to a
+      // graceful message, but never let it throw past here.
+      // The guild + rank-role to apply at add-time come from the discord module
+      // through the kernel seam (ADR 0083 / BV1.R47 — no core→module import);
+      // degrades to { guildId: null } when discord is off, so the join just skips.
+      const joinSpec = await seams.resolveOptional(
+        'discord.guildJoinSpec', async () => ({ guildId: null, roleIds: [] }),
+      )(req.builder.rank);
+      let joined = false;
+      if (joinSpec.guildId && auth.discordBotConfigured()) {
+        try {
+          await auth.addDiscordGuildMember({
+            guildId: joinSpec.guildId,
+            discordUserId: dUser.id,
+            accessToken,
+            roleIds: joinSpec.roleIds,
+          });
+          joined = true;
+        } catch (e) {
+          console.log('[gds] discord auto-join failed (non-blocking):', e.message);
+        }
+      }
+      // F5 role-sync belt-and-braces (ADR 0033 §4): set/repair the rank-role even
+      // if auto-join 204'd an already-present member (whose add-time roles Discord
+      // ignores) or the add step was skipped. Emitted to the discord module's
+      // listener; fire-and-forget.
+      seams.emit('builder.role-sync-needed', { builderId: req.builder.id });
+      // #731: the Discord connect card lives on /builders/settings now, so the
+      // callback returns there (settings.js surfaces the ?discord= toast).
+      res.redirect(joined ? '/builders/settings?discord=joined' : '/builders/settings?discord=linked');
+    } catch (err) {
+      console.error('[gds] discord/callback', err);
+      res.status(500).type('text/html').send(renderAuthErrorPage(
+        'The Discord link threw an error',
+        'Linking failed unexpectedly. Try again; if it persists, the Archon must check the server logs.',
+        { cta: { href: '/builders', label: 'Back to the hall' } },
+      ));
+    }
+  });
+
+  // rank: any-builder — unlink your OWN Discord. JSON (called from the hall UI).
+  // F7 follow-up: also kicks the builder from the guild so they can't remain in
+  // the server without a linked account. The kick is best-effort — the unlink
+  // always succeeds even if the bot lacks Kick Members or the member already left.
+  router.post('/auth/discord/unlink', auth.requireBuilder, async (req, res) => {
+    try {
+      // Read the discord_user_id BEFORE deleting the link — we need it for the kick.
+      const link = await db.getDiscordLink(req.builder.id);
+      const removed = await db.unlinkDiscord(req.builder.id);
+      if (link && auth.discordBotConfigured()) {
+        const { guildId } = await seams.resolveOptional(
+          'discord.guildJoinSpec', async () => ({ guildId: null }),
+        )(null);
+        if (guildId) {
+          auth.removeDiscordGuildMember({ guildId, discordUserId: link.discord_user_id })
+            .then((r) => console.log(`[gds] discord unlink kick: ${r.removed ? 'removed' : r.reason}`))
+            .catch((e) => console.log('[gds] discord unlink kick failed (non-blocking):', e.message));
+        }
+      }
+      res.json({ ok: true, unlinked: removed });
+    } catch (err) {
+      console.error('[gds] discord/unlink', err);
+      res.fail('unlink_failed', 500);
+    }
+  });
+
+  // rank: any-builder — own session, no rank gate (a Xenos can log themselves out).
+  router.post('/auth/logout', auth.requireBuilder, async (req, res) => {
+    const token = (req.headers['authorization'] || '').replace(/^Bearer\s+/, '')
+      || parseCookie(req, SESSION_COOKIE)
+      || parseCookie(req, SESSION_COOKIE_LEGACY);
+    if (token) await db.revokeSession(token);
+    // Clear BOTH the host-only form (older sessions) and the apex-scoped form
+    // (#726) — a clearCookie only matches the cookie whose domain attribute it
+    // names, so sign-out on a production host must target the apex domain too.
+    res.clearCookie(SESSION_COOKIE);
+    res.clearCookie(SESSION_COOKIE_LEGACY);
+    const domainOpts = sessionCookieDomainOpts(req);
+    if (domainOpts.domain) {
+      res.clearCookie(SESSION_COOKIE, domainOpts);
+      res.clearCookie(SESSION_COOKIE_LEGACY, domainOpts);
+    }
+    res.json({ ok: true });
+  });
+
+  // POST /auth/cli-token/issue — V3.R91 / #401. Issue a fresh CLI bearer for
+  // the requesting builder, gated on a WEB COOKIE session (not a bearer). The
+  // browser already proves identity via the gds_session cookie; this endpoint
+  // mints a separate cli-source session row the builder can paste into
+  // ~/.config/otb/gds-session.json via scripts/gds/paste-token.js. Replaces
+  // the ~30-60s Device Flow when the CLI bearer has expired.
+  //
+  // rank: any-builder (own identity only) — no rank gate.
+  // auth source restriction: cookie ONLY. A bearer cannot mint a new bearer
+  // (a leaked CLI token shouldn't be able to extend its own lifetime; the
+  // httpOnly browser cookie is the harder-to-steal credential).
+  router.post('/auth/cli-token/issue', auth.requireBuilder, async (req, res) => {
+    const cookieToken = parseCookie(req, SESSION_COOKIE) || parseCookie(req, SESSION_COOKIE_LEGACY);
+    if (!cookieToken) {
+      // Name the instance's own sign-in host (from the branding pack), not a
+      // hardcoded "amazonprimea.com" (ADR 0062 §3/§5).
+      const signInHost = configuredOAuthOrigin().replace(/^https?:\/\//, '').split('/')[0] || 'the sign-in page';
+      return res.fail('cookie_required', { status: 403, message: `This endpoint mints CLI bearers from an authenticated browser session. Sign in at ${signInHost} first; bearer-only requests are rejected so a leaked CLI token cannot mint replacements for itself.` });
+    }
+    try {
+      const token = crypto.randomBytes(32).toString('hex');
+      const row = await db.createSession({
+        builderId: req.builder.id,
+        token,
+        // source must be 'cli' | 'web' (003_pms.sql CHECK). The route name in
+        // audit_log distinguishes portal-reissue from Device Flow tokens.
+        source: 'cli',
+        userAgent: req.headers['user-agent'] ?? null,
+        // expiresAt: null → createSession applies SESSION_TTL_MS (24h after V3.R90).
+        expiresAt: null,
+      });
+      res.json({
+        ok: true,
+        token,
+        expires_at: row.expires_at,
+        builder_login: req.builder.github_login,
+        paste_command: `node scripts/gds/paste-token.js ${token}`,
+      });
+    } catch (err) {
+      console.error('[gds] POST /auth/cli-token/issue', err);
+      res.fail('issue_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /auth/revoke — V3.R38 / #259. Archon-only. Kill a SINGLE session by
+  // its primary-key id. Used for surgical lockouts (e.g. a compromised CLI on
+  // a known builder's laptop) without disturbing that builder's other sessions.
+  // Body: { session_id: <bigint> }. Response: { ok, revoked: 0|1 }.
+  // rank: archon — kills an arbitrary session; can lock other builders out.
+  router.post('/auth/revoke', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, { session_id: {} })) return;  // bigint as number or string; validated below
+    const sessionId = req.body && req.body.session_id;
+    if (sessionId === undefined || sessionId === null) {
+      return res.fail('session_id_required', 400);
+    }
+    // Accept bigint as string or number; validate it parses cleanly.
+    const id = Number(sessionId);
+    if (!Number.isInteger(id) || id <= 0) {
+      return res.fail('bad_session_id', 400);
+    }
+    try {
+      const revoked = await db.revokeSessionById(id);
+      res.json({ ok: true, revoked });
+    } catch (err) {
+      console.error('[gds] POST /auth/revoke', err);
+      res.fail('revoke_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /auth/revoke-all — V3.R38 / #259. Archon-only. Kill EVERY active
+  // session for a given builder. Used at demotion (auto-called from
+  // setBuilderRank when newRank moves down the ladder — C7 rank-change-near-
+  // instant) and as a manual operator hammer.
+  // Body: { builder_id: <bigint> }. Response: { ok, revoked: <count> }.
+  // rank: archon — same authority as PATCH /builders/:id/rank.
+  router.post('/auth/revoke-all', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, { builder_id: {} })) return;  // bigint as number or string; validated below
+    const builderId = req.body && req.body.builder_id;
+    if (builderId === undefined || builderId === null) {
+      return res.fail('builder_id_required', 400);
+    }
+    const id = Number(builderId);
+    if (!Number.isInteger(id) || id <= 0) {
+      return res.fail('bad_builder_id', 400);
+    }
+    try {
+      const revoked = await db.revokeAllSessionsForBuilder(id);
+      res.json({ ok: true, revoked });
+    } catch (err) {
+      console.error('[gds] POST /auth/revoke-all', err);
+      res.fail('revoke_all_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // /auth/app-pair — browser-clicks-only sign-in for the Dev Box desktop app
+  // (#904, ADR 0045). The app starts a pairing, opens the browser at
+  // /builders/pair?code=…, the signed-in builder clicks ONE Approve button,
+  // and the app collects a freshly-minted source='cli' session over its own
+  // secret poll channel. Design + threat model in src/bongos/app-pair.js.
+  //
+  // Route order note: the two PUBLIC routes here sit so no requireBuilder/
+  // requireRank from a NEIGHBORING declaration falls inside route-rank-check's
+  // 20-line look-ahead — the deterministic auditor must classify them from
+  // their own `rank:` annotations, not a false middleware hit.
+
+  // rank: public — starts a pairing; returns opaque codes only, no identity.
+  router.post('/auth/app-pair/start', (req, res) => {
+    if (validateOrRespond(req, res, {
+      device_name: { type: 'string', maxLength: 80 },
+      platform: { type: 'string', maxLength: 20 },
+    })) return;
+    const body = req.body || {};
+    const out = pairStore.start({ deviceName: body.device_name, platform: body.platform });
+    if (out.error === 'busy') {
+      return res.fail('pairing_busy', { status: 429, message: 'Too many pairings in flight. Try again in a few minutes.' });
+    }
+    // The approve-page URL is PINNED to the canonical public origin (same
+    // posture as the OAuth redirect_uris above) — never derived from the
+    // request host, so a spoofed Host header can't point the app's browser
+    // hand-off at a look-alike approve page.
+    const verifyPath = `/builders/pair?code=${out.pairCode}`;
+    res.status(201).json({
+      pair_code: out.pairCode,
+      poll_token: out.pollToken,
+      verify_path: verifyPath,
+      verify_url: `${WEB_REDIRECT_ORIGIN}${verifyPath}`,
+      expires_in: out.expiresIn,
+      interval: out.interval,
+    });
+  });
+
+  // rank: any-builder — read-only: what the approve page shows BEFORE the
+  // click (device name/platform for the given code). Unknown and expired are
+  // indistinguishable (404) so the code space can't be probed for liveness.
+  router.get('/auth/app-pair/info', auth.requireBuilder, (req, res) => {
+    const info = pairStore.info(req.query.code);
+    if (!info) return res.fail('unknown_or_expired', 404);
+    res.json({
+      pair_code: info.pairCode,
+      device_name: info.deviceName,
+      platform: info.platform,
+      status: info.status,
+    });
+  });
+
+  // rank: any-builder (own identity only) — approving signs the app in AS THE
+  // APPROVER. Cookie-gated exactly like /auth/cli-token/issue above: a leaked
+  // CLI bearer must not be able to approve pairings and mint itself siblings;
+  // only the httpOnly browser cookie — the click in the hall — can.
+  router.post('/auth/app-pair/approve', auth.requireBuilder, async (req, res) => {
+    const cookieToken = parseCookie(req, SESSION_COOKIE) || parseCookie(req, SESSION_COOKIE_LEGACY);
+    if (!cookieToken) {
+      return res.fail('cookie_required', { status: 403, message: 'Pairings are approved from an authenticated browser session in the builders’ hall, not from a bearer token.' });
+    }
+    if (validateOrRespond(req, res, {
+      pair_code: { required: true, type: 'string', maxLength: 32 },
+    })) return;
+    try {
+      const token = crypto.randomBytes(32).toString('hex');
+      const row = await db.createSession({
+        builderId: req.builder.id,
+        token,
+        source: 'cli', // 003_pms.sql CHECK; the app is a CLI-class bearer client
+        userAgent: `devbox-app pair (${req.headers['user-agent'] ?? 'unknown'})`,
+        expiresAt: null, // createSession applies the 24h refresh-on-use TTL
+      });
+      const out = pairStore.approve((req.body || {}).pair_code, {
+        token,
+        expires_at: row.expires_at,
+        builder: {
+          id: req.builder.id,
+          github_login: req.builder.github_login,
+          display_name: req.builder.display_name,
+          rank: req.builder.rank,
+        },
+      });
+      if (!out.ok) {
+        // The pairing was gone or already approved — revoke the session we
+        // just minted so an orphaned token never outlives this branch.
+        await db.revokeSession(token);
+        return out.error === 'already_approved'
+          ? res.fail('already_approved', 409)
+          : res.fail('unknown_or_expired', 404);
+      }
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[gds] POST /auth/app-pair/approve', err);
+      res.fail('approve_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: public — poll with the secret poll_token; the token IS the bearer
+  // (mirrors /auth/device/poll, where the device_code is the bearer). Kept
+  // LAST in this router so route-rank-check's look-ahead window stays clear
+  // of any neighboring gated declaration (see the block comment above).
+  router.post('/auth/app-pair/poll', (req, res) => {
+    if (validateOrRespond(req, res, {
+      poll_token: { required: true, type: 'string', maxLength: 128 },
+    })) return;
+    const out = pairStore.poll((req.body || {}).poll_token);
+    if (out.status === 'approved') {
+      return res.json({ status: 'approved', ...out.grant });
+    }
+    res.json(out.status === 'pending'
+      ? { status: 'pending', interval: out.interval }
+      : { status: 'expired' });
+  });
+
+  return router;
+};
+
+// Exposed for unit tests (#726). These are pure host/URL helpers — the
+// open-redirect guard on the post-sign-in return target and the cross-subdomain
+// cookie-domain decision — worth locking down independently of a running server.
+module.exports.safeReturnTo = safeReturnTo;
+module.exports.sessionCookieDomainOpts = sessionCookieDomainOpts;
+module.exports.reqHost = reqHost;
+// The auth-error page renderer (task 1439): pure over the branding pack, so a
+// test can prove every visible string is brand-owned (no OTB lore baked in).
+module.exports.renderAuthErrorPage = renderAuthErrorPage;