@bongos/core 1.19.332 → 1.19.334

package/src/bongos/auth-github.js

@@ -0,0 +1,336 @@
+// src/bongos/auth-github.js — the GitHub OAuth flows: session-token minting, the
+// user fetch, the code exchange, the CLI device flow and the web flow.
+//
+// Carved out of src/bongos/auth.js by task 1003206 (goal 1000079, the R03 plan)
+// to bring the kernel identity file under the 1,500-line ratchet. This is the
+// highest-risk file in the carve, so the move is STRICTLY structural: bodies
+// unchanged, auth.js requires every name back, and the middleware surface
+// (requireBuilder / requireRank / requirePermission / the page gates) never left.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const {
+  upsertBuilder,
+  seatFirstAdminIfUnclaimed,
+  createSession,
+  lookupSession,
+  getBuilderById,
+  getBuilderByGithubId,
+  hasInvitedAccessRequest,
+  accessStateByLogin,
+  RANKS,
+} = require('./db-kernel');
+const { pool } = require('./pool');
+const seams = require('../module-seams');
+const { branding, userAgent } = require('../branding');
+const { firstTimeAdmissionBlocked, maybeSeatFirstAdmin, openEnrollmentEnabled, safeSyncRankRole } = require('./auth-admission.js');
+const { SCOPE, deviceFlows, loadGithubCreds, scopeForWebFlow } = require('./auth-config.js');
+
+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 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 || '' };
+}
+
+// -------------------------------------------------------------------------
+// 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();
+  // GitHub returns HTTP 200 with an { error, error_description } body for OAuth-App
+  // misconfig — most often device_flow_disabled (Device Flow not enabled on the App)
+  // or incorrect_client_credentials. res.ok is TRUE there, so without this the missing
+  // device_code silently produced a broken flow / an opaque 500 (the 2026-07-08 demo
+  // login failure). Mirror the token-exchange guard (data.error, above); task 2126.
+  if (data.error) {
+    // device_flow_disabled is self-inflicted + common: GitHub defaults Device Flow OFF on new
+    // Apps and the one-click manifest can't enable it (task 2129). Make the CLI error self-
+    // service by naming the right settings surface. We hold only client_id here (not the app
+    // slug — that lives on the control plane), so we can't build /settings/apps/<slug>; but the
+    // id PREFIX distinguishes a GitHub App (Iv*) from an OAuth App (Ov*), which picks the right
+    // listing to open.
+    let hint = '';
+    if (data.error === 'device_flow_disabled') {
+      const where = /^Iv/i.test(creds.client_id || '')
+        ? 'https://github.com/settings/apps (org-owned apps: https://github.com/organizations/<org>/settings/apps)'
+        : 'https://github.com/settings/developers';
+      hint = ` — terminal sign-in needs Device Flow enabled on the app: open ${where}, open your app, check "Enable Device Flow", and save. Web sign-in is unaffected.`;
+    }
+    throw new Error(`GitHub rejected device-flow start: ${data.error}${data.error_description ? ` — ${data.error_description}` : ''}${hint}`);
+  }
+  if (!data.device_code) {
+    throw new Error('GitHub device/code returned no device_code (unexpected response shape).');
+  }
+  // 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);
+    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: 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, { 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);
+  // `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, 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
+  // 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';
+      // 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;
+    }
+  }
+  let builder = await upsertBuilder({
+    githubId: ghUser.id,
+    githubLogin: ghUser.login,
+    displayName: ghUser.name || ghUser.login,
+    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.
+  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);
+  // 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.
+
+module.exports = {
+  buildAuthorizeUrl,
+  completeWebFlow,
+  fetchGithubUser,
+  newSessionToken,
+  pollDeviceFlow,
+  startDeviceFlow,
+};

package/src/bongos/auth-idp.js

@@ -0,0 +1,330 @@
+// src/bongos/auth-idp.js — federated sign-in against the identity hub: the IdP
+// authorize/exchange flow, hub assertion + back-channel logout verification with
+// their replay guards, and the device exchange that rides an assertion.
+//
+// Carved out of src/bongos/auth.js by task 1003206 (goal 1000079, the R03 plan)
+// to bring the kernel identity file under the 1,500-line ratchet. This is the
+// highest-risk file in the carve, so the move is STRICTLY structural: bodies
+// unchanged, auth.js requires every name back, and the middleware surface
+// (requireBuilder / requireRank / requirePermission / the page gates) never left.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const {
+  upsertBuilder,
+  seatFirstAdminIfUnclaimed,
+  createSession,
+  lookupSession,
+  getBuilderById,
+  getBuilderByGithubId,
+  hasInvitedAccessRequest,
+  accessStateByLogin,
+  RANKS,
+} = require('./db-kernel');
+const { pool } = require('./pool');
+const seams = require('../module-seams');
+const ic = require('../instance-config');
+const { branding, userAgent } = require('../branding');
+const { firstTimeAdmissionBlocked, maybeSeatFirstAdmin, openEnrollmentEnabled, reportActivityRollup, reportMembershipCheckIn, safeSyncRankRole } = require('./auth-admission.js');
+const { loadIdpConfig } = require('./auth-config.js');
+const { newSessionToken } = require('./auth-github.js');
+
+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. The rollup is CHAINED after the check-in (ADR 0171 D7):
+  // the hub now requires a membership row before accepting activity, so a first
+  // sign-in's rollup must not race its own check-in. Both swallow all errors, so
+  // the chain never rejects and the sign-in never waits on it.
+  // Both helpers are async (always return a promise) and swallow their own
+  // errors; the .catch is belt-and-braces so this floating chain can never
+  // surface an unhandledRejection even if a future edit lets one throw.
+  reportMembershipCheckIn({ githubId: ghId, githubLogin: ghLogin, displayName: identity.display_name, avatarUrl: identity.avatar_url })
+    .then(() => reportActivityRollup({ builderId: builder.id, githubId: ghId }))
+    .catch(() => {});
+  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. Rollup chained after check-in (ADR 0171 D7): the hub's
+  // membership requirement must not race a first sign-in; both swallow errors.
+  // Async + self-swallowing helpers; .catch is belt-and-braces (see web flow).
+  reportMembershipCheckIn({ githubId: ghId, githubLogin: ghLogin, displayName: payload.display_name, avatarUrl: payload.avatar_url })
+    .then(() => reportActivityRollup({ builderId: builder.id, githubId: ghId }))
+    .catch(() => {});
+  return { token, builder };
+}
+
+// -------------------------------------------------------------------------
+// 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.
+
+module.exports = {
+  buildIdpAuthorizeUrl,
+  completeDeviceExchange,
+  completeIdpFlow,
+  exchangeIdpCode,
+  idpAuthorizeUrl,
+  loadHubPublicKey,
+  logoutTokenJtiSeenAndRecord,
+  verifyHubAssertion,
+  verifyHubLogoutToken,
+};