@bongos/core 1.19.332 → 1.19.334

package/src/bongos/auth-admission.js

@@ -0,0 +1,264 @@
+// src/bongos/auth-admission.js — who is allowed IN: the membership kind reported
+// to the hub, the activity rollup, open enrollment, the first-time admission
+// block, first-admin seating and the rank-role sync.
+//
+// membershipKind lives here rather than with the config readers because it calls
+// firstAdminLogin() — putting it the other side of the seam would need a cycle.
+//
+// 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 {
+  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 { loadIdpConfig } = require('./auth-config.js');
+
+function membershipKind({ githubLogin } = {}) {
+  const fa = firstAdminLogin();
+  if (fa && String(githubLogin || '').toLowerCase() === fa.toLowerCase()) return 'owner';
+  return 'member';
+}
+
+// Best-effort server-to-server membership check-in to the hub (ADR 0141 §3): "this
+// github_id builds on project <client_id>, coarse membership <membership_kind>".
+//
+// BOTH SPELLINGS GO ON THE WIRE FOR THE WINDOW (task 1003090). The receiver is the
+// HUB, a different instance on its own upgrade schedule: send only the new field and
+// an un-upgraded hub silently defaults every membership to non-owner (it would drop
+// the owner flag); send only the legacy field and an upgraded hub keeps translating
+// forever. Sending both is what makes the two ends independent — the removal task
+// drops `role` once the hub is past the window. Runs on every
+// FEDERATED sign-in (the only sign-ins a federated instance has) so a CLI-only
+// project still appears in the builder's My Projects with no hub browser session.
+// Fire-and-forget + fully swallowed: a hub outage must NEVER fail a sign-in (mirrors
+// the onboarding stage tick). No-op on a self-hosted instance (idp unset).
+async function reportMembershipCheckIn({ githubId, githubLogin, displayName, avatarUrl }) {
+  const idp = loadIdpConfig();
+  if (!idp) return;
+  const kind = membershipKind({ githubLogin });
+  try {
+    await fetch(`${idp.origin}/api/gds/sso/membership/check-in`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      body: JSON.stringify({
+        client_id: idp.clientId,
+        client_secret: idp.clientSecret,
+        github_id: githubId,
+        github_login: githubLogin,
+        display_name: displayName ?? null,
+        avatar_url: avatarUrl ?? null,
+        membership_kind: kind,
+        // LEGACY (cross-version window): 'member' → 'builder' for an un-upgraded hub.
+        role: kind === 'member' ? 'builder' : kind,
+      }),
+    });
+  } catch (err) {
+    console.log('[auth] hub membership check-in failed (non-blocking):', err.message);
+  }
+}
+
+// Best-effort cross-project activity rollup to the hub (ADR 0141 §4): report this
+// builder's descriptive talent snapshot (credits, ships, karma, rank, disciplines)
+// for the internal scouting directory. Fires on every federated sign-in ("on key
+// events"); true periodic reporting is a follow-up. Fully swallowed + no-op when
+// not federated — never fails a sign-in.
+async function reportActivityRollup({ builderId, githubId }) {
+  const idp = loadIdpConfig();
+  if (!idp) return;
+  try {
+    // Snapshot the builder's talent signals directly from the DB (auth.js is a
+    // kernel file — it uses pool, never a non-kernel domain module like metrics.js).
+    const b = await pool.query(
+      'SELECT total_credits, karma, rank, preferred_disciplines FROM builders WHERE id = $1',
+      [builderId],
+    );
+    if (!b.rows[0]) return;
+    const shipped = await pool.query('SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1', [builderId]);
+    const row = b.rows[0];
+    await fetch(`${idp.origin}/api/gds/sso/activity/rollup`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      body: JSON.stringify({
+        client_id: idp.clientId,
+        client_secret: idp.clientSecret,
+        github_id: githubId,
+        credits: Number(row.total_credits) || 0,
+        tasks_shipped: shipped.rows[0] ? shipped.rows[0].n : 0,
+        karma: Number(row.karma) || 0,
+        rank: row.rank || null,
+        disciplines: Array.isArray(row.preferred_disciplines) ? row.preferred_disciplines : [],
+      }),
+    });
+  } catch (err) {
+    console.log('[auth] hub activity rollup failed (non-blocking):', err.message);
+  }
+}
+
+// Admission posture (SR-19 / task #1000). BOTH enrollment paths — the web hall
+// sign-in (completeWebFlow) and the CLI device flow (pollDeviceFlow) — are
+// "invite-gated by default": a FIRST-TIME GitHub account is admitted only if an
+// 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;
+}
+
+// webAdmissionStatus — "would this login get in RIGHT NOW, and is it worth
+// waiting?" (task 1002097). Backs the waiting page that replaced the red
+// "not approved" dead-end a firstAdmin hits during the bootstrap window.
+//
+// `admitted` deliberately mirrors firstTimeAdmissionBlocked's own terms —
+// member OR open-enrollment OR invited OR configured-firstAdmin — so the probe
+// can never say "come in" while the real gate says otherwise. It reads state;
+// it decides nothing. firstTimeAdmissionBlocked remains the one gate both flows
+// call (SR-19); if that logic changes, this must change with it.
+// tests/web_admission_status.mjs sweeps the input space asserting the two agree.
+//
+// `expectedSoon` is the broader "keep polling" signal: admitted, or waiting on
+// an Archon (pending), or the configured firstAdmin whose instance is still
+// booting. A visitor who is none of these is a genuine stranger and gets the
+// existing request-access page rather than a spinner that never resolves.
+//
+// NB the onboarding module's public GET /access-requests/status (used by the
+// CLI) reports member|invited|pending|none but knows nothing about the
+// firstAdmin bypass or open enrollment — so it reports the OWNER as 'none'
+// forever. That is exactly why this auth-domain probe exists.
+async function webAdmissionStatus(login) {
+  const name = String(login || '').trim();
+  if (!name) return { admitted: false, expectedSoon: false };
+
+  const fa = firstAdminLogin();
+  const isFirstAdmin = !!fa && name.toLowerCase() === fa.toLowerCase();
+
+  let state = { member: false, invited: false, pending: false };
+  try {
+    state = await accessStateByLogin(name);
+  } catch (err) {
+    // A DB hiccup must not turn the waiting page into a false "you're in".
+    // Fail closed on `admitted`; still let a firstAdmin keep polling, since
+    // that is the bootstrap window this page exists for.
+    console.error('[auth] webAdmissionStatus', err);
+    return { admitted: false, expectedSoon: isFirstAdmin };
+  }
+
+  const admitted = state.member || openEnrollmentEnabled() || state.invited || isFirstAdmin;
+  return { admitted, expectedSoon: admitted || state.pending || isFirstAdmin };
+}
+
+// First-admin bootstrap (R62 / task 1201, ADR 0062). The configured firstAdmin
+// login — an install-time env override (<PREFIX>_FIRST_ADMIN, incl. legacy) wins,
+// else branding.firstAdmin. Empty/unset (the vanilla starter) means "no one is
+// 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;
+}
+
+// safeSyncRankRole — give a builder the seeded rank-role matching their rank at
+// REGISTRATION (BV1.R95b, ADR 0151). governance_002's builder→role backfill is
+// run-once, so before this every builder admitted after that migration had no role
+// row at all and resolved to the EMPTY permission set — denied on every gated route.
+//
+// Called at each sign-in rather than only on first insert, and deliberately so: the
+// call is idempotent (two SELECTs and no write once the role already matches), it
+// also covers the rank write maybeSeatFirstAdmin just made (the firstAdmin bootstrap
+// flips xenos→archon outside any transaction), and it quietly repairs a builder whose
+// assignment drifted for any other reason.
+//
+// Resolved through the `government.rankSync` kernel port — auth.js is a KERNEL_FILE
+// and may not require a module (ADR 0083 / ADR 0091 §1). Runs on the pool: there is
+// no surrounding transaction here, unlike the two rank-change paths, which pass their
+// own client so the rotation is atomic with the rank write.
+//
+// BEST-EFFORT: a governance hiccup must never fail a sign-in, and the failure mode is
+// fail-closed anyway — no role means zero permissions, never extra ones.
+async function safeSyncRankRole(builder) {
+  if (!builder || builder.id == null) return;
+  try {
+    await seams.resolveOptional('government.rankSync')
+      ?.syncRank(null, { builderId: builder.id, rank: builder.rank });
+  } catch (err) {
+    console.error('[auth] rank-role sync failed (non-fatal):', err.message);
+  }
+}
+
+
+module.exports = {
+  firstAdminLogin,
+  firstTimeAdmissionBlocked,
+  maybeSeatFirstAdmin,
+  membershipKind,
+  openEnrollmentEnabled,
+  reportActivityRollup,
+  reportMembershipCheckIn,
+  safeSyncRankRole,
+  webAdmissionStatus,
+};

package/src/bongos/auth-config.js

@@ -0,0 +1,151 @@
+// src/bongos/auth-config.js — what identity providers are configured and which
+// OAuth scopes to ask for: GitHub creds + scope selection and the hub IdP config.
+//
+// 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 ic = require('../instance-config');
+const { branding, userAgent } = require('../branding');
+
+const SCOPE = 'read:user';
+
+// The repo-acting scope the onboarding wizard opts into. `repo`, NOT `public_repo`.
+//
+// ADR 0143 §1 originally chose `public_repo` precisely to avoid the all-or-nothing
+// `repo`, and named its own reversal path: "revisit to `repo` only if private
+// support is needed". It is needed. `public_repo` grants write to PUBLIC repos
+// only, so ADOPTING an existing PRIVATE repo dies at the provisioner's scaffold
+// push with GitHub 403 "Write access to repository not granted" — observed live on
+// a private repo of the owner's. ADR 0155 takes the reversal at the owner's
+// explicit call, accepting the cost it names: a token we persist can now write to
+// EVERY repo the user owns, not just their public ones.
+const REPO_SCOPE = 'repo';
+
+// Web-flow OAuth scope. Identity (`read:user`) is all the builders'-hall sign-in
+// and the CLI Device Flow ever need. The onboarding wizard
+// (public-landing/create.html), however, lists + creates + is pushed to by the
+// provisioner on the signed-in user's own GitHub repos (task 1002099) — which
+// `read:user` cannot do — so it OPTS IN to REPO_SCOPE. Only the wizard passes
+// { repos:true }; every other sign-in stays identity-only. Pure + exported so the
+// exact scope string (a security-critical value) is unit-testable.
+function scopeForWebFlow({ repos = false } = {}) {
+  return repos ? `${SCOPE} ${REPO_SCOPE}` : SCOPE;
+}
+
+// Does a scope string GitHub ACTUALLY GRANTED still satisfy the repo surfaces?
+//
+// WHY THIS EXISTS. Widening scopeForWebFlow does NOT upgrade tokens already in
+// `github_oauth_tokens` — a row minted before ADR 0155 carries `public_repo`, which
+// is enough to list and create PUBLIC repos. So every wizard call would still 200
+// while silently omitting the user's PRIVATE repos from the picker, and the failure
+// would resurface far downstream at the provisioner's push. Callers check this and
+// re-prompt (repo_scope_required) instead of degrading quietly.
+//
+// GitHub returns granted scopes comma-separated in its own order (e.g.
+// "public_repo,read:user"), so parse rather than substring-match — `public_repo`
+// CONTAINS "repo" and a naive match would accept exactly the stale token this
+// guards against. `repo` implies `public_repo`, so `repo` alone is sufficient.
+function grantedScopeCoversRepos(granted) {
+  return String(granted || '')
+    .split(/[,\s]+/)
+    .map((s) => s.trim())
+    .includes(REPO_SCOPE);
+}
+
+// In-memory map of device_code → { interval, expires_at, last_polled_at, github_creds }
+// Device flow is ephemeral; restart of the Node process invalidates pending flows
+// (the user just re-runs the setup skill). Acceptable for V1 — scaling up means
+// 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();
+}
+
+// -------------------------------------------------------------------------
+// Platform IdP federation (ADR 0141 §1) — when enabled, the instance's web +
+// CLI sign-in federate through the Cloud Bongos hub instead of talking to GitHub
+// directly. Identity is federated; authority is NOT — the instance still runs its
+// OWN admission gate + upsertBuilder + createSession, so the hub only answers
+// "who is this GitHub user" (ADR 0016). Direct-GitHub (auth.idp unset) stays the
+// unchanged fallback for self-hosted instances.
+// -------------------------------------------------------------------------
+
+// The switch is the branding auth.idp flag (committed, non-secret). Fail-soft to
+// false so a branding hiccup degrades to the direct-GitHub path rather than
+// breaking sign-in.
+function idpEnabled() {
+  try { return branding().auth?.idp === true; } catch { return false; }
+}
+
+// Resolve the hub federation config. The switch is the flag above; the hub origin
+// + client credentials come from ENV (<PREFIX>_HUB_ORIGIN / _HUB_CLIENT_ID /
+// _HUB_CLIENT_SECRET) — never a committed file, so the secret stays out of the
+// branding pack (mirrors loadGithubCreds's env-first posture). Provisioning
+// (ADR 0141 §4) writes these into the instance web.env. Returns null unless the
+// flag is on AND all three resolve → callers fall back to direct GitHub.
+function loadIdpConfig() {
+  if (!idpEnabled()) return null;
+  const origin = ic.resolveEnv('HUB_ORIGIN');
+  const clientId = ic.resolveEnv('HUB_CLIENT_ID');
+  const clientSecret = ic.resolveEnv('HUB_CLIENT_SECRET');
+  if (origin && clientId && clientSecret) {
+    return { origin: String(origin).replace(/\/+$/, ''), clientId, clientSecret };
+  }
+  return null;
+}
+
+function idpConfigured() {
+  return !!loadIdpConfig();
+}
+
+// The COARSE membership role to report to the hub (ADR 0141 §3) — owner if this
+// builder is the instance's configured firstAdmin, else a plain member. NEVER a rank.
+//
+// 'member', not 'builder' (task 1003090, ADR 0177 §"the fifth use"): ADR 0174 reserves
+// `role` — and the craft name 'Builder' — for Artist / Ideator / Builder, so the coarse
+// project membership says what it means. The legacy spelling still goes on the wire for
+// the cross-version window; see reportMembershipCheckIn.
+
+module.exports = {
+  SCOPE,
+  authConfigured,
+  deviceFlows,
+  grantedScopeCoversRepos,
+  idpConfigured,
+  idpEnabled,
+  loadGithubCreds,
+  loadIdpConfig,
+  scopeForWebFlow,
+};

package/src/bongos/auth-discord.js

@@ -0,0 +1,198 @@
+// src/bongos/auth-discord.js — the Discord OAuth link and guild membership calls.
+//
+// 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 ic = require('../instance-config');
+
+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.
+
+module.exports = {
+  addDiscordGuildMember,
+  buildDiscordAuthorizeUrl,
+  discordAuthorizeUrl,
+  discordBotConfigured,
+  discordConfigured,
+  exchangeDiscordCode,
+  fetchDiscordUser,
+  isValidDiscordUserId,
+  loadDiscordBotToken,
+  loadDiscordCreds,
+  removeDiscordGuildMember,
+};