@bongos/core 1.17.3 → 1.18.3

package/src/bongos/auth.js

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

package/src/bongos/db.js

@@ -25,6 +25,7 @@
 // grade-count SQL runs on both sides of the kernel↔module line — keep in sync.
 
 const { pool } = require('./pool');
+const secretBox = require('./secret-box');
 // Module seam (ADR 0083 / BV1.R43). The rank/status-change paths EMIT
 // `builder.box-reconcile-needed` AFTER COMMIT (best-effort) so the dev-box module
 // can reconcile a droplet a demotion/graduation implies — never a direct require
@@ -205,6 +206,68 @@ async function updateBuilderDisciplines(builderId, disciplines) {
 // { enc: null, ... } when no key is set.
 
 
+// ---- GitHub OAuth repo token, encrypted at rest (core_192 / task 1002099) ----
+//
+// The onboarding wizard (public-landing/create.html) opts into `public_repo` at
+// sign-in so it can list + create the user's repos. That user-to-server GitHub
+// token is held here BRIEFLY: encrypted with secret-box (master key in server env
+// only — the plaintext never touches the DB) and given a short TTL (one wizard
+// sitting), read back by the repo picker/creator, then deleted on use. It is the
+// auth system's OWN handshake token (distinct from a feature's third-party key
+// like the art module's Gemini key, ADR 0102), so it lives in core auth. secret-box
+// is the gate: with no master key configured we NEVER store a plaintext token —
+// capture no-ops and the wizard degrades to manual repo entry (ADR 0143).
+const GITHUB_TOKEN_TTL_MS = 60 * 60 * 1000; // 1h — one wizard sitting.
+
+// Store (or replace) the builder's GitHub repo token. `token` is the raw
+// user-to-server access token; it is encrypted here so the plaintext never touches
+// the DB. No-ops when secret-box is unconfigured (returns { stored:false }).
+async function upsertGithubToken({ builderId, token, scope = null, ttlMs = GITHUB_TOKEN_TTL_MS, p = pool }) {
+  if (!secretBox.isConfigured()) return { stored: false };
+  const enc = secretBox.encrypt(token);
+  const expiresAt = new Date(Date.now() + ttlMs);
+  await p.query(
+    `INSERT INTO github_oauth_tokens (builder_id, token_enc, scope, created_at, expires_at)
+       VALUES ($1, $2, $3, now(), $4)
+     ON CONFLICT (builder_id) DO UPDATE
+       SET token_enc = EXCLUDED.token_enc, scope = EXCLUDED.scope,
+           created_at = now(), expires_at = EXCLUDED.expires_at`,
+    [builderId, enc, scope, expiresAt],
+  );
+  return { stored: true, expires_at: expiresAt };
+}
+
+// Read + decrypt the builder's GitHub token, or null when there is none, it has
+// expired, or secret-box is unconfigured. Lazily deletes an expired row so the
+// table self-cleans without a cron (mirrors the deviceFlows reaping in auth.js).
+// The 503-vs-403 distinction the endpoint needs is made by the endpoint checking
+// secretBox.isConfigured() itself before calling this.
+async function getGithubToken({ builderId, p = pool }) {
+  if (!secretBox.isConfigured()) return null;
+  const { rows } = await p.query(
+    `SELECT token_enc, scope, expires_at FROM github_oauth_tokens WHERE builder_id = $1`,
+    [builderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (new Date(row.expires_at).getTime() <= Date.now()) {
+    await p.query(`DELETE FROM github_oauth_tokens WHERE builder_id = $1`, [builderId]).catch(() => {});
+    return null;
+  }
+  let token;
+  try { token = secretBox.decrypt(row.token_enc); }
+  catch { return null; } // a blob that won't decrypt (e.g. rotated master key) reads as "none".
+  return { token, scope: row.scope, expires_at: row.expires_at };
+}
+
+// Delete the builder's token (called after the wizard's terminal enqueue, and on
+// expiry). Best-effort; safe to call when nothing is stored.
+async function deleteGithubToken({ builderId, p = pool }) {
+  await p.query(`DELETE FROM github_oauth_tokens WHERE builder_id = $1`, [builderId]);
+  return { deleted: true };
+}
+
+
 // leaderboard() carved into modules/economy/credits.js (BV1.R77 / ADR 0093 §1-2).
 // Core read routes resolve it via the `reward` kernel port.
 
@@ -908,4 +971,7 @@ module.exports = {
   upsertSecurityDoc,
   getSecurityDoc,
   listSecurityDocs,
+  upsertGithubToken,
+  getGithubToken,
+  deleteGithubToken,
 };

package/src/bongos/github-repos.js

@@ -0,0 +1,93 @@
+// GitHub repo list/create on behalf of the signed-in user — the server half of the
+// onboarding wizard's repo picker (adopt) + auto-create (fresh). Task 1002099 / ADR 0143.
+//
+// Raw `fetch` against GitHub's REST API (the house style — see auth.js
+// fetchGithubUser; no octokit dependency). The user-to-server token these take is
+// the `public_repo`-scoped token the web callback captured and stored (db.js
+// github_oauth_tokens); callers pass the decrypted token in, this module never
+// touches storage. `fetchImpl` is injectable so tests can drive it with a mock and
+// never hit the network.
+
+const { userAgent } = require('../branding');
+
+const GH_API = 'https://api.github.com';
+const PER_PAGE = 100;
+// Up to 300 most-recently-updated OWNED repos — plenty to back a picker for the vast
+// majority of accounts, and a hard bound so a power user can't make us page forever
+// (v1 cap; the picker filters this set client-and-server-side by substring).
+const MAX_PAGES = 3;
+
+class GithubApiError extends Error {
+  constructor(message, { status, code } = {}) {
+    super(message);
+    this.name = 'GithubApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function ghHeaders(token, extra = {}) {
+  return {
+    Authorization: `Bearer ${token}`,
+    'User-Agent': userAgent(),
+    Accept: 'application/vnd.github+json',
+    ...extra,
+  };
+}
+
+// List the signed-in user's OWN repos (affiliation=owner so `full_name` is always
+// `login/repo` and the org-OAuth-policy complexity is out of scope for v1),
+// most-recently-updated first, optionally filtered by a case-insensitive substring
+// `q` on the full name. Returns [{ full_name, name, owner, private }].
+async function listUserRepos(token, { q = '', fetchImpl = fetch } = {}) {
+  const out = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const url = `${GH_API}/user/repos?per_page=${PER_PAGE}&page=${page}&sort=updated&affiliation=owner`;
+    const res = await fetchImpl(url, { headers: ghHeaders(token) });
+    if (res.status === 401) {
+      throw new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
+    }
+    if (!res.ok) {
+      throw new GithubApiError(`GitHub /user/repos failed (${res.status})`, { status: res.status, code: 'github_error' });
+    }
+    const rows = await res.json();
+    if (!Array.isArray(rows) || rows.length === 0) break;
+    for (const r of rows) {
+      out.push({
+        full_name: r.full_name,
+        name: r.name,
+        owner: r.owner && r.owner.login,
+        private: !!r.private,
+      });
+    }
+    if (rows.length < PER_PAGE) break;
+  }
+  const needle = String(q || '').trim().toLowerCase();
+  return needle ? out.filter((r) => String(r.full_name).toLowerCase().includes(needle)) : out;
+}
+
+// Create an EMPTY repo in the signed-in user's personal account. auto_init:false =
+// no README/first commit (exactly the "leave it completely empty" the manual step
+// demanded); private:false because we hold only `public_repo`. Returns
+// { full_name, html_url }. A 422 (name already exists / invalid) becomes a typed
+// `name_taken` error the route maps to a friendly 409 rather than an opaque 500.
+async function createUserRepo(token, { name, fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(`${GH_API}/user/repos`, {
+    method: 'POST',
+    headers: ghHeaders(token, { 'Content-Type': 'application/json' }),
+    body: JSON.stringify({ name, private: false, auto_init: false }),
+  });
+  if (res.status === 201) {
+    const r = await res.json();
+    return { full_name: r.full_name, html_url: r.html_url };
+  }
+  if (res.status === 401) {
+    throw new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
+  }
+  if (res.status === 422) {
+    throw new GithubApiError('A repository with that name already exists on your account', { status: 422, code: 'name_taken' });
+  }
+  throw new GithubApiError(`GitHub create-repo failed (${res.status})`, { status: res.status, code: 'github_error' });
+}
+
+module.exports = { listUserRepos, createUserRepo, GithubApiError, MAX_PAGES };