@bongos/core 1.18.0 → 1.18.3

package/scripts/gds/upgrade.js

@@ -295,6 +295,91 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// ---- integrity-pin verification (task 1002216 / audit H8, finding F1) --------
+// The packager (package-core.js) computes tree_sha256 = canonicalTreeHash over the
+// redacted core files (+ the two synthesized files) and records it, the per-file
+// hashes, AND the exact tarball bytes' sha256 in a side-car manifest — stating a
+// consumer "verifies an install by recomputing it from the unpacked tree." Until now
+// nothing on the CONSUME side did: `bongos upgrade` compared only the version STRING,
+// so a corrupted / truncated / swapped tarball whose package.json still read the target
+// version installed silently — the R88-class failure this goal exists to prevent.
+// The three functions below close that gap: recompute the pin over the INSTALLED tree
+// and assert it equals the TRUSTED reference manifest.
+
+// Read + parse a manifest JSON; null on any failure (missing / unparseable).
+function readManifest(file, fsImpl = fs) {
+  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Resolve the trusted reference pin for this bump:
+//   • VENDORED — the committed side-car `vendor/<artifact>-<v>.manifest.json` (carries
+//     tree_sha256 + files[] + the exact tarball.sha256). It lives OUTSIDE the tarball
+//     (version-controlled in the consumer repo), so it detects a swapped/corrupted
+//     tarball. This is the strong reference.
+//   • REGISTRY / no side-car — the inner manifest `<core>/.bongos-core.json` that ships
+//     INSIDE the package (tree_sha256 + files[], no tarball.*). Self-referential (a full
+//     swap regenerates it too), so it is a self-consistency check backing npm's own
+//     registry integrity rather than an independent one — flagged `strong:false`.
+function resolveReferenceManifest({ instanceDir, coreDir, targetVersion }, fsImpl = fs) {
+  const sidecarPath = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.manifest.json`);
+  const sidecar = readManifest(sidecarPath, fsImpl);
+  if (sidecar && sidecar.tree_sha256) {
+    const tgz = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.tgz`);
+    return { manifest: sidecar, tgzPath: fsImpl.existsSync(tgz) ? tgz : null, source: 'vendored side-car manifest', strong: true };
+  }
+  const inner = readManifest(path.join(coreDir, '.bongos-core.json'), fsImpl);
+  if (inner && inner.tree_sha256) return { manifest: inner, tgzPath: null, source: 'installed inner manifest', strong: false };
+  return { manifest: null, tgzPath: null, source: null, strong: false };
+}
+
+// Recompute the integrity pin over the installed core tree and compare to `referenceManifest`.
+// Reuses the PACKAGER's exact hash functions (canonicalTreeHash / sha256hex) so the consume-side
+// recompute can never drift from the produce-side pin. Returns { ran, ok, checks, problems };
+// ran=false ⇒ the manifest carried no pin to check against.
+function verifyInstalledPin({ coreDir, referenceManifest, tgzPath }, deps = {}) {
+  const fsImpl = deps.fs || fs;
+  const pc = deps.packageCore || require('./package-core');
+  const checks = [];
+  const problems = [];
+  if (!referenceManifest || !referenceManifest.tree_sha256) return { ran: false, ok: false, checks, problems };
+
+  // (a) exact tarball bytes (vendored path only) — the strongest single check: the bytes
+  //     npm actually installs, hashed and compared to the externally-held pin.
+  const tb = referenceManifest.tarball;
+  if (tgzPath && tb && tb.sha256 && fsImpl.existsSync(tgzPath)) {
+    const got = pc.sha256hex(fsImpl.readFileSync(tgzPath));
+    const ok = got === tb.sha256;
+    checks.push({ name: 'tarball.sha256', ok });
+    if (!ok) problems.push(`vendored tarball bytes sha256 ${got.slice(0, 12)}… ≠ pinned ${String(tb.sha256).slice(0, 12)}…`);
+  }
+
+  // (b) installed tree — recompute each pinned file's sha256 from the unpacked tree, rebuild
+  //     the canonical tree hash (using the manifest's already-canonical modes), assert equality.
+  //     Catches partial extraction, post-install corruption, or a registry package that diverged.
+  const files = Array.isArray(referenceManifest.files) ? referenceManifest.files : [];
+  if (files.length) {
+    const recomputed = [];
+    let missing = 0, changed = 0;
+    for (const f of files) {
+      const abs = path.join(coreDir, ...String(f.path).split('/')); // POSIX manifest path → native
+      let buf;
+      try { buf = fsImpl.readFileSync(abs); } catch { missing++; problems.push(`missing installed file: ${f.path}`); continue; }
+      const sha = pc.sha256hex(buf);
+      if (sha !== f.sha256) { changed++; problems.push(`content mismatch: ${f.path}`); }
+      recomputed.push({ path: f.path, mode: f.mode, sha256: sha });
+    }
+    const treeHash = pc.canonicalTreeHash(recomputed);
+    const ok = missing === 0 && changed === 0 && treeHash === referenceManifest.tree_sha256;
+    checks.push({ name: 'tree_sha256', ok, missing, changed, file_count: files.length });
+    if (!ok && missing === 0 && changed === 0) {
+      problems.push(`recomputed tree_sha256 ${treeHash.slice(0, 12)}… ≠ pinned ${String(referenceManifest.tree_sha256).slice(0, 12)}…`);
+    }
+  }
+
+  const ran = checks.length > 0;
+  return { ran, ok: ran && problems.length === 0, checks, problems };
+}
+
 // Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
 // error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
 // snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
@@ -390,6 +475,18 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ✓ pre-flight: ${mods.note}`);
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
+  // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
+  //     brings the new core live via a managed restart (--service / --restart-cmd) MUST confirm it
+  //     actually serves — an upgrade that can't be health-checked can't be reported as a success.
+  //     Enforced here in PRE-FLIGHT, before anything is mutated, so there is nothing to roll back:
+  //     if this bump will restart the service and the check isn't explicitly opted out, a
+  //     --health-url is required. (No managed restart ⇒ nothing is brought live here ⇒ the check
+  //     does not apply; the operator restarts + verifies separately.)
+  const willRestart = !!(opts.service || opts.restartCmd);
+  if (!dryRun && opts.healthCheck !== false && willRestart && !opts.healthUrl) {
+    return { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service, but no --health-url was given.\n  Pass --health-url <url> to confirm the new core serves after restart, or --no-health-check to explicitly skip the confirmation.' };
+  }
+
   // 2. bump the pin. Two mutually exclusive core sources (ADR 0134, task 2090):
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
@@ -429,6 +526,38 @@ async function runUpgrade(opts, deps = {}) {
   }
   log('  ✓ npm install');
 
+  // 3b. verify the integrity pin (audit H8 / task 1002216, finding F1). Recompute tree_sha256 over
+  //     the freshly-installed core (+ the exact vendored tarball bytes) and assert it matches the
+  //     TRUSTED reference manifest — the pin the packager produced but the consume side never
+  //     re-checked. Runs BEFORE migrate so a corrupted core can never touch the DB. A MISMATCH is
+  //     fatal → rollback (like an install/migrate failure). A MISSING reference (no side-car AND no
+  //     inner manifest) can't be verified: a warning by default, fatal only with --require-pin.
+  if (!opts.skipPinVerify) {
+    const coreDir = path.join(instanceDir, 'node_modules', CORE_PKG);
+    const ref = (deps.resolveReferenceManifest || resolveReferenceManifest)({ instanceDir, coreDir, targetVersion }, fsImpl);
+    if (!ref.manifest) {
+      const msg = `integrity pin: no reference manifest (looked for vendor/${ARTIFACT}-${targetVersion}.manifest.json and ${CORE_PKG}/.bongos-core.json) — cannot verify this install`;
+      if (opts.requirePin) {
+        const error = `${msg} (--require-pin)`;
+        if (rollbackOnFailure && snapshot) { const rb = await doRollback('integrity pin unverifiable (--require-pin)'); return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb }; }
+        return { ok: false, error, fromVersion };
+      }
+      err(`  ! ${msg} — pass --require-pin to treat this as fatal.`);
+    } else {
+      const pin = (deps.verifyInstalledPin || verifyInstalledPin)({ coreDir, referenceManifest: ref.manifest, tgzPath: ref.tgzPath }, deps);
+      if (!pin.ok) {
+        const detail = pin.problems.slice(0, 6).join('; ') + (pin.problems.length > 6 ? `; +${pin.problems.length - 6} more` : '');
+        const error = `integrity pin MISMATCH (${ref.source}) — installed core does not match its pin: ${detail}`;
+        if (rollbackOnFailure && snapshot) {
+          const rb = await doRollback('integrity pin mismatch');
+          return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+        }
+        return { ok: false, error, fromVersion };
+      }
+      log(`  ✓ integrity pin verified (${pin.checks.map((c) => c.name).join(' + ')}) against the ${ref.source}${ref.strong ? '' : ' — self-consistency check; npm registry integrity is the primary guard'}`);
+    }
+  } else log('  • integrity-pin verify skipped (--skip-pin-verify)');
+
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
     const mig = runMigrate(instanceDir, run);
@@ -472,11 +601,17 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ${versionOk ? '✓' : '!'} installed core version: ${installed || '(unknown)'}${versionOk ? '' : ` (expected ${targetVersion})`}`);
 
   let healthOk = null;
-  if (opts.healthUrl) {
+  if (opts.healthCheck === false) {
+    log('  • post-restart health check skipped (--no-health-check) — success is NOT confirmed against a live endpoint.');
+  } else if (opts.healthUrl) {
     const h = await pollHealth(opts.healthUrl, deps);
     healthOk = h.ok;
     if (h.ok) log(`  ✓ health ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (ready after ${h.attempts} tries)` : ''}`);
     else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
+  } else {
+    // Reachable only when NO managed restart happened (pre-flight requires a URL when one will):
+    // the new core is installed on disk, but nothing was brought live here to health-check.
+    log('  • no managed restart + no --health-url — new core installed but not confirmed serving; restart the instance + health-check it to complete the bump.');
   }
 
   // A failed post-restart health check means the new core is serving broken — auto-revert (task
@@ -514,6 +649,9 @@ function parseArgs(argv) {
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+    skipPinVerify: hasFlag('--skip-pin-verify', argv), // task 1002216: opt out of the post-install integrity-pin check
+    requirePin: hasFlag('--require-pin', argv), // task 1002216: a MISSING reference manifest becomes fatal (not just a warning)
+    healthCheck: !hasFlag('--no-health-check', argv), // task 1002222: post-restart health check is ON by default (finding F5/H9)
     rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
   };
 }
@@ -533,16 +671,19 @@ async function main(argv = process.argv.slice(2)) {
       '  --instance <dir>     consumer instance root (default: cwd)',
       '  --service <unit>     systemd unit to restart after applying',
       '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
-      '  --health-url <url>   poll after restart (~30s) until 2xx; still-failing is a warning',
+      '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
+      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves)',
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
-      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/migrate/health check (default: auto-rollback ON)',
+      '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
+      '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
+      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
-      'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
-      'On a failure after the pin moves (install/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
+      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify.',
+      'On a failure after the pin moves (install/pin-verify/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -560,6 +701,7 @@ module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
+  readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };
 

package/scripts/migrate.sh

@@ -110,6 +110,16 @@ apply_migration() {
     >/dev/null
 }
 
+# --- Forward-safety notice (task 1002223 / audit H10) ---------------------
+# `bongos upgrade` auto-rollback reverts the code pin but NOT the DB — safe only if core migrations
+# are forward-safe (the PREVIOUS code still runs on the new schema). Surface — never block — any
+# UNACKNOWLEDGED forward-unsafe core migration so an operator knows a rollback past it would strand
+# old code on new schema. Fail-closed enforcement is the unit gate (tests/migrations_forward_safe.mjs);
+# here it is advisory (`|| true`) so a lint hiccup can NEVER break a deploy.
+if [ -f "$CORE_ROOT/scripts/gds/lint-migrations.js" ]; then
+  node "$CORE_ROOT/scripts/gds/lint-migrations.js" --warn --dir "$CORE_ROOT/migrations" || true
+fi
+
 # Build the ordered migration list and apply it as ONE numeric sequence by
 # filename stem, regardless of directory:
 #   $CORE_ROOT/migrations/*.sql              — core: schema + platform-universal seeds (EVERY instance).

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,