@bongos/core 1.18.0 → 1.18.18

package/src/bongos/routes/auth.js

@@ -80,6 +80,78 @@ function renderAuthErrorPage(heading, detail, opts = {}) {
 </body></html>`;
 }
 
+// renderAccessPendingPage — the calm "hang tight" page shown instead of the red
+// dead-end when admission is plausibly imminent (task 1002097): the configured
+// firstAdmin during the bootstrap window, or a login with a pending request.
+//
+// It polls GET /auth/web/admission-status and, the moment the answer flips to
+// admitted, sends the visitor back through /auth/web/start for a FRESH sign-in.
+// A fresh start is required, not optional: the OAuth code that brought them
+// here is already spent, so re-running the callback would fail on state
+// mismatch. The owner chose auto-walk-in, hence no button to click.
+//
+// Branding resolves defensively, exactly as renderAuthErrorPage does — a
+// branding hiccup must degrade to neutral copy, never crash the page.
+function renderAccessPendingPage(login) {
+  const worldName = (() => { try { return branding().identity?.worldName || 'The city'; } catch { return 'The city'; } })();
+  const epigraph = (() => { try { return branding().copy?.authError?.epigraph || '— access —'; } catch { return '— access —'; } })();
+  // The probe takes the login as a query param; everything interpolated into
+  // the page is escaped, and the JS reads it from a data- attribute rather than
+  // being built by string concatenation into a script body.
+  const safeLogin = escapeHtml(String(login || ''));
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(worldName)} — confirming access</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@500;700&family=EB+Garamond:ital,wght@0,400;0,500&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="/builders/style.css">
+</head><body>
+<header class="hall">
+  <p class="hall__epigraph">${escapeHtml(epigraph)}</p>
+  <h1>Confirming your access</h1>
+  <p class="hall__sub">Hang tight — this usually takes a few seconds.</p>
+</header>
+<main>
+  <section class="scroll">
+    <div class="landing" id="pending" data-login="${safeLogin}">
+      <p>We're checking your access now. You'll be signed in automatically as soon as it clears — no need to refresh.</p>
+      <p class="landing__note" id="pending-note">Checking…</p>
+    </div>
+  </section>
+</main>
+<script>
+(function () {
+  var el = document.getElementById('pending');
+  var note = document.getElementById('pending-note');
+  var login = el ? el.getAttribute('data-login') : '';
+  var EVERY_MS = 3000;
+  var GIVE_UP_MS = 5 * 60 * 1000;
+  var started = Date.now();
+
+  function land() { window.location.href = '/api/gds/auth/web/start'; }
+
+  function tick() {
+    if (Date.now() - started > GIVE_UP_MS) {
+      note.textContent = 'Still waiting on approval. You can leave this page open, or try signing in again later.';
+      return;
+    }
+    fetch('/api/gds/auth/web/admission-status?login=' + encodeURIComponent(login), { credentials: 'omit' })
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (j) {
+        if (j && j.admitted) { land(); return; }
+        setTimeout(tick, EVERY_MS);
+      })
+      .catch(function () { setTimeout(tick, EVERY_MS); });
+  }
+  setTimeout(tick, EVERY_MS);
+})();
+</script>
+</body></html>`;
+}
+
 // Cookie names. The web flow writes the new `gds_session` (+ `gds_oauth_state`)
 // names; both flows accept either the new or the legacy `pms_session` /
 // `pms_oauth_state` cookies on read so a builder mid-flow doesn't have to
@@ -93,6 +165,13 @@ const DISCORD_STATE_COOKIE = 'gds_discord_state';
 // flow can land a builder back on the subdomain they started from (#726). Set
 // at /auth/web/start, consumed + cleared at the callback. Defaults to /builders.
 const RETURN_COOKIE = 'gds_return';
+// Short-lived cookie marking that THIS sign-in opted into repo access (the
+// onboarding wizard's `?repos=1`). Set at /auth/web/start, read at the callback so
+// it captures + persists the returned GitHub token — and cleared there. Scoping
+// capture to an explicit intent cookie (not just "the granted scope happens to
+// include repo") means an ordinary hall sign-in never stores a token, even for a
+// user who previously granted the broader scope (task 1002099 / ADR 0143).
+const REPOS_COOKIE = 'gds_oauth_repos';
 
 // The apex domain the instance is served under, read from the instance branding
 // pack's cookieDomain (".amazonprimea.com" → "amazonprimea.com",
@@ -182,6 +261,27 @@ function configuredOAuthOrigin() {
   }
 }
 
+// The post-sign-in landing used when no explicit ?return= / same-apex Referer
+// was stashed for this sign-in. Configurable per instance via
+// branding.landing.postLogin (env override <PREFIX>_POST_LOGIN_LANDING) so a
+// platform-home instance can land visitors on its OWN front door —
+// cloudbongos.com sets it to /gate/ (the orbs) so a visitor who signs in from
+// the orbs returns to the orbs, never auto-redirected into the builders' hall
+// (task 1002240). Every other instance keeps the portable default '/builders':
+// the hall always exists, a /gate/ orbs site does not. The configured value is
+// run through the SAME open-redirect allowlist as ?return= (safeReturnTo), so a
+// misconfigured landing can never become an open redirect; anything unsafe or
+// absent falls back to '/builders'. Takes an optional resolved pack so the pure
+// path is unit-testable without disk I/O (mirrors clientBranding()).
+function postLoginLanding(brand) {
+  try {
+    const b = brand || branding();
+    return safeReturnTo(b.landing?.postLogin) || '/builders';
+  } catch {
+    return '/builders';
+  }
+}
+
 // The OAuth redirect_uri must be a FIXED, registered origin — never derived from
 // the request's x-forwarded-host (spoofable; F2 Hacker finding). Configured via
 // env, falling back to the configured canonical public origin, so an injected host
@@ -245,10 +345,47 @@ module.exports = function buildAuthRouter() {
     }
   });
 
+  // POST /auth/device/exchange — CLI federation (ADR 0141 §1). The CLI ran the
+  // device flow against the HUB and got a hub-signed assertion; it presents it here.
+  // The instance verifies the Ed25519 signature OFFLINE against the provisioned hub
+  // public key (aud must equal this instance's client_id, unexpired), then runs the
+  // instance's OWN admission gate + upsertBuilder + createSession(source='cli') and
+  // returns the existing { token, builder }. Only reachable when auth.idp is set.
+  //
+  // rank: public — an auth-establishment endpoint; the hub-signed assertion IS the
+  //   bearer and is cryptographically verified before any session is minted.
+  router.post('/auth/device/exchange', async (req, res) => {
+    if (!auth.idpConfigured()) {
+      return res.fail('idp_not_configured', 503);
+    }
+    if (validateOrRespond(req, res, {
+      assertion: { required: true, type: 'string', maxLength: 4096 },
+    })) return;
+    try {
+      const { token, builder } = await auth.completeDeviceExchange({
+        assertion: req.body.assertion,
+        userAgent: req.headers['user-agent'],
+      });
+      res.json({ token, builder });
+    } catch (err) {
+      // Mirror the device/poll admission surface so the CLI prints the same
+      // "ask an Archon to invite you" path.
+      if (err && err.code === 'NOT_APPROVED') {
+        return res.status(403).json({ state: 'not_approved', error: 'not_approved' });
+      }
+      // A bad / expired / forged / wrong-audience assertion is an auth failure (401),
+      // not a server error — never mint a session for it.
+      console.error('[gds] /auth/device/exchange', err);
+      res.fail('invalid_assertion', { status: 401, message: String(err.message || 'invalid assertion').slice(0, 160) });
+    }
+  });
+
   // /auth/web — browser flow (used by the /builders page).
   // rank: public — entry into the GitHub OAuth handshake.
   router.get('/auth/web/start', (req, res) => {
-    if (!auth.authConfigured()) {
+    // Either direct-GitHub creds OR platform-IdP federation must be configured
+    // (ADR 0141 §1) — a federated instance has no GitHub app of its own.
+    if (!auth.authConfigured() && !auth.idpConfigured()) {
       return res.status(503).type('text/plain').send('auth not configured');
     }
     const state = crypto.randomBytes(16).toString('hex');
@@ -281,12 +418,75 @@ module.exports = function buildAuthRouter() {
         ...sessionCookieDomainOpts(req),
       });
     }
-    res.redirect(auth.buildAuthorizeUrl(state, redirectUri));
+    // Opt-in repo access (task 1002099 / ADR 0143): the onboarding wizard passes
+    // ?repos=1 so it can list/create the user's repos. Remember the intent in a
+    // short-lived cookie (same recipe as the state cookie) and request the broader
+    // scope on the direct-GitHub leg. Absent the flag this is a no-op — hall + CLI
+    // sign-ins stay identity-only.
+    const wantsRepos = req.query.repos === '1' || req.query.repos === 'true';
+    if (wantsRepos) {
+      res.cookie(REPOS_COOKIE, '1', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+        maxAge: 10 * 60 * 1000,
+        ...sessionCookieDomainOpts(req),
+      });
+    }
+    // Federate through the hub when configured (ADR 0141 §1); otherwise the direct
+    // GitHub authorize, carrying the repo-scope opt-in. Same CSRF state cookie either
+    // way — the callback validates it identically, so the hub leg is CSRF-protected too.
+    res.redirect(auth.idpConfigured()
+      ? auth.buildIdpAuthorizeUrl(state, redirectUri)
+      : auth.buildAuthorizeUrl(state, redirectUri, { repos: wantsRepos }));
+  });
+
+  // GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage
+  // polls (task 1002097). Answers ONE question: would this login be admitted
+  // right now? It mirrors the real gate via auth.webAdmissionStatus so the page
+  // can never invite someone in the gate would refuse.
+  //
+  // rank: public — it must be reachable by a visitor with no session (that is
+  //   the entire situation it exists for). It grants nothing: admission still
+  //   runs through the normal sign-in, and this only reads state.
+  //
+  // WHAT IT LEAKS, stated plainly (task 1002430 — an earlier version of this
+  // comment claimed the opposite and was wrong). Returning only a boolean does
+  // NOT make it non-enumerable: with open enrollment off, and for any login
+  // that is not the configured firstAdmin, `admitted:true` means that login is
+  // a member or has been invited. That reveals account existence to an
+  // unauthenticated caller. It is also NOT throttled — rateLimitMiddleware
+  // returns early for non-write methods, so GETs bypass it entirely; the page's
+  // 3s poll bounds the honest client, not an attacker.
+  //
+  // Why it is nonetheless not a new exposure: the onboarding module's
+  // GET /access-requests/status?github_login=X is ALREADY public and returns
+  // the strictly richer member|invited|pending|dismissed|none plus its own
+  // `admitted`. Anything derivable here is already derivable there, so this
+  // adds no net-new surface — and hardening only this route would accomplish
+  // nothing while that one stays open. Whether unauthenticated login-existence
+  // probing is acceptable at all is a real question, but it belongs to both
+  // routes together, not to a comment here.
+  //
+  // That endpoint is also why this one exists: it models neither the firstAdmin
+  // bypass nor open enrollment, so it reports the OWNER as 'none' forever —
+  // the exact case this page has to resolve.
+  router.get('/auth/web/admission-status', async (req, res) => {
+    const login = typeof req.query.login === 'string' ? req.query.login.slice(0, 100) : '';
+    if (!login) return res.json({ admitted: false });
+    try {
+      const { admitted } = await auth.webAdmissionStatus(login);
+      return res.json({ admitted: !!admitted });
+    } catch (err) {
+      // Fail closed and quietly — the page just keeps polling.
+      console.error('[gds] auth/web/admission-status', err);
+      return res.json({ admitted: false });
+    }
   });
 
   // rank: public — OAuth callback; the state cookie + code are the bearer.
   router.get('/auth/web/callback', async (req, res) => {
-    if (!auth.authConfigured()) {
+    if (!auth.authConfigured() && !auth.idpConfigured()) {
       return res.status(503).type('text/plain').send('auth not configured');
     }
     const expectedState = parseCookie(req, STATE_COOKIE) || parseCookie(req, STATE_COOKIE_LEGACY);
@@ -304,14 +504,19 @@ module.exports = function buildAuthRouter() {
       ));
     }
     try {
-      // Must match the PINNED redirect_uri used at /auth/web/start (#734) — the
-      // GitHub token exchange requires an exact string match.
+      // Must match the PINNED redirect_uri used at /auth/web/start (#734) — both
+      // the GitHub token exchange and the hub /sso/token redemption require an
+      // exact string match against the value sent at authorize time.
       const redirectUri = `${WEB_REDIRECT_ORIGIN}/api/gds/auth/web/callback`;
-      const { token, expiresAt } = await auth.completeWebFlow({
-        code,
-        redirectUri,
-        userAgent: req.headers['user-agent'],
-      });
+      // Did THIS sign-in opt into repo access? (the wizard's ?repos=1 intent cookie)
+      const wantsRepos = parseCookie(req, REPOS_COOKIE) === '1';
+      // Federated (hub) vs direct-GitHub — same downstream: admission gate,
+      // upsertBuilder, createSession, gds_session cookie (ADR 0141 §1). The direct
+      // leg additionally captures the opt-in repo token (task 1002099 / ADR 0143);
+      // the hub leg has no direct GitHub token, so the wizard degrades to manual entry.
+      const { token, expiresAt, builder, githubToken, githubScope } = auth.idpConfigured()
+        ? await auth.completeIdpFlow({ code, redirectUri, userAgent: req.headers['user-agent'] })
+        : await auth.completeWebFlow({ code, redirectUri, userAgent: req.headers['user-agent'], captureRepoToken: wantsRepos });
       res.cookie(SESSION_COOKIE, token, {
         httpOnly: true,
         sameSite: 'lax',
@@ -322,26 +527,61 @@ module.exports = function buildAuthRouter() {
         // amazonprimea.com + builders. + status. (#726); host-only elsewhere.
         ...sessionCookieDomainOpts(req),
       });
+      // Persist the wizard's repo token (task 1002099 / ADR 0143): encrypted at rest,
+      // short-TTL, keyed to the builder — the repo picker/creator reads it back over
+      // the next few minutes. Gated on secret-box being configured (upsertGithubToken
+      // no-ops when it isn't). Best-effort: a capture failure must NEVER break sign-in.
+      if (wantsRepos && githubToken) {
+        try {
+          await db.upsertGithubToken({ builderId: builder.id, token: githubToken, scope: githubScope });
+        } catch (e) {
+          console.error('[gds] web/callback: repo-token capture failed (non-blocking):', e.message);
+        }
+      }
       // The state cookie is apex-scoped now (#734) — clear it with the same
       // domain or the browser keeps it. Clear the host-only form too for any
-      // cookie set before this change.
+      // cookie set before this change. Clear the repos-intent cookie the same way.
       const domainOpts = sessionCookieDomainOpts(req);
       res.clearCookie(STATE_COOKIE);
       res.clearCookie(STATE_COOKIE_LEGACY);
+      res.clearCookie(REPOS_COOKIE);
       if (domainOpts.domain) {
         res.clearCookie(STATE_COOKIE, domainOpts);
         res.clearCookie(STATE_COOKIE_LEGACY, domainOpts);
+        res.clearCookie(REPOS_COOKIE, domainOpts);
       }
       // Land back where sign-in began if a validated return target was stashed
-      // (e.g. the builders subdomain bounced through here); else the hall.
+      // (e.g. the builders subdomain bounced through here); else the instance's
+      // configured post-login landing (default '/builders'; cloudbongos.com →
+      // /gate/, the orbs — task 1002240).
       const returnTo = safeReturnTo(parseCookie(req, RETURN_COOKIE));
       res.clearCookie(RETURN_COOKIE, domainOpts);
-      res.redirect(returnTo || '/builders');
+      res.redirect(returnTo || postLoginLanding());
     } catch (err) {
       // Approval gate (2026-05-30): a first-time GitHub account that hasn't been
       // approved by an Archon can't enter. Send them to the hall to request
       // access rather than dead-ending on a generic error.
       if (err && err.code === 'NOT_APPROVED') {
+        // task 1002097: a blocked sign-in is not always a rejection. On a fresh
+        // or just-restarted instance the configured firstAdmin lands here for a
+        // few seconds — before FIRST_ADMIN is loaded / the bootstrap finishes —
+        // and so does anyone whose access_request an Archon is about to mark
+        // invited. The red dead-end looked broken, and could not be retried:
+        // the OAuth code is single-use, so a reload throws "State mismatch"
+        // instead. For those two, show a calm waiting page that polls and walks
+        // them in by itself. Genuine strangers still get the request-access
+        // page below.
+        let expectedSoon = false;
+        try {
+          ({ expectedSoon } = await auth.webAdmissionStatus(err.login));
+        } catch (probeErr) {
+          // Never let the classifier turn a clean 403 into a 500 — fall through
+          // to the existing page, which is the safe answer for a stranger.
+          console.error('[gds] web/callback admission classify', probeErr);
+        }
+        if (expectedSoon) {
+          return res.status(202).type('text/html').send(renderAccessPendingPage(err.login));
+        }
         return res.status(403).type('text/html').send(renderAuthErrorPage(
           'This account is not approved yet',
           'Signing in with GitHub is only for builders an Archon has already approved. If you are new, request access at the builders’ hall — an Archon will approve you, then this sign-in will let you in. If you were just approved, the Archon may still need to mark you invited; give it a moment and try again.',
@@ -535,9 +775,67 @@ module.exports = function buildAuthRouter() {
       res.clearCookie(SESSION_COOKIE, domainOpts);
       res.clearCookie(SESSION_COOKIE_LEGACY, domainOpts);
     }
+    // Federated single-logout (ADR 0144, task 1002238): announce the logout so the
+    // hub (platform-identity, enabled only on cloudbongos.com) can fan a signed
+    // back-channel logout out to every federated project this builder entered. A
+    // fire-and-forget seam EMIT — zero listeners on a non-hub instance, so it's a
+    // no-op there; the fan-out is best-effort server-side and never blocks or fails
+    // this logout (the hub session is already revoked above).
+    seams.emit('builder.logout', {
+      builderId: req.builder.id,
+      githubId: req.builder.github_id,
+      githubLogin: req.builder.github_login,
+    });
     res.json({ ok: true });
   });
 
+  // POST /auth/backchannel-logout — the INSTANCE side of federated single-logout
+  // (ADR 0144, task 1002238). The hub POSTs a hub-signed logout token here when a
+  // builder signs out of the hub; we verify it and revoke ALL of that builder's
+  // local sessions, so one hub logout ends the session on every federated project.
+  //
+  // rank: public — the hub-signed EdDSA logout token IS the credential (like the
+  //   OAuth callback), NOT a builder session. Inert (404) on an instance that does
+  //   not federate through a hub (idp unset), so a self-hosted instance exposes no
+  //   new surface. Idempotent: an unknown/replayed subject just revokes nothing.
+  router.post('/auth/backchannel-logout', async (req, res) => {
+    const idp = auth.loadIdpConfig();
+    if (!idp) {
+      // Not a federated instance — indistinguishable from "no such route".
+      return res.status(404).type('text/plain').send('not found');
+    }
+    if (validateOrRespond(req, res, {
+      logout_token: { required: true, type: 'string', maxLength: 4096 },
+    })) return;
+    const publicKey = auth.loadHubPublicKey();
+    if (!publicKey) return res.fail('idp_unconfigured', { status: 503, message: 'hub public key not configured' });
+    let payload;
+    try {
+      payload = auth.verifyHubLogoutToken(req.body.logout_token, { publicKey, clientId: idp.clientId });
+    } catch (err) {
+      // A bad / expired / forged / wrong-audience token is an auth failure (401),
+      // never a server error — and never revokes anything.
+      return res.fail('invalid_logout_token', { status: 401, message: String(err.message || 'invalid logout token').slice(0, 160) });
+    }
+    // Anti-replay (defense-in-depth, symmetric with the CLI assertion path): honor
+    // a logout token's jti ONCE. A replay within the ~120s TTL is an idempotent
+    // no-op, so a captured token can't keep killing sessions the builder creates
+    // AFTER it was minted.
+    if (auth.logoutTokenJtiSeenAndRecord(payload.jti, payload.exp)) {
+      return res.json({ ok: true });
+    }
+    try {
+      const builder = await db.getBuilderByGithubId(payload.sub);
+      // Revoke ALL of this builder's local sessions (web + CLI) — the hub said sign
+      // them out. No-op + 200 if we don't know this builder (never leak existence).
+      if (builder) await db.revokeAllSessionsForBuilder(builder.id);
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[gds] /auth/backchannel-logout revoke', err);
+      res.fail('server_error', { status: 500, message: 'logout failed' });
+    }
+  });
+
   // POST /auth/cli-token/issue — V3.R91 / #401. Issue a fresh CLI bearer for
   // the requesting builder, gated on a WEB COOKIE session (not a bearer). The
   // browser already proves identity via the gds_session cookie; this endpoint
@@ -753,6 +1051,7 @@ module.exports = function buildAuthRouter() {
 // open-redirect guard on the post-sign-in return target and the cross-subdomain
 // cookie-domain decision — worth locking down independently of a running server.
 module.exports.safeReturnTo = safeReturnTo;
+module.exports.postLoginLanding = postLoginLanding;
 module.exports.sessionCookieDomainOpts = sessionCookieDomainOpts;
 module.exports.reqHost = reqHost;
 // The auth-error page renderer (task 1439): pure over the branding pack, so a

package/src/bongos/routes/backup.js

@@ -37,7 +37,39 @@ const BACKUP_SCRIPT = process.env.GDS_BACKUP_SCRIPT
 // In-memory guard: true while a trigger-initiated dump is running.
 let triggerRunning = false;
 
-function latestDump() {
+// A dump older than this counts as STALE. The nightly timer fires daily, so 36h
+// allows one missed run plus slack before we call it broken.
+const STALE_AFTER_HOURS = Number(process.env.GDS_BACKUP_STALE_HOURS) || 36;
+
+// parseDumpTimestamp — the dump filename stamp `YYYY-MM-DDTHHMMSSZ` is ALMOST
+// ISO-8601 but omits the time separators, so Date.parse rejects it. Re-insert
+// the colons and parse. Returns epoch ms, or null if it doesn't match.
+// Pure + exported so tests can pin it without touching the filesystem.
+function parseDumpTimestamp(stamp) {
+  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(String(stamp || ''));
+  if (!m) return null;
+  const ms = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}Z`);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+// dumpAgeHours — hours between a dump stamp and now. null when unparseable, so
+// callers can tell "cannot tell" apart from "fresh". Pure (now is injectable).
+function dumpAgeHours(stamp, nowMs = Date.now()) {
+  const ms = parseDumpTimestamp(stamp);
+  if (ms === null) return null;
+  return Math.max(0, (nowMs - ms) / 3_600_000);
+}
+
+// isStaleDump — fail LOUD on an unreadable/absent stamp. A dump we cannot date
+// must not read as healthy: that silence is exactly how the cloudbongos nightly
+// sat failed for 13 days (2026-07-15 → 07-28) with nothing noticing (1002479).
+function isStaleDump(stamp, nowMs = Date.now(), staleAfterHours = STALE_AFTER_HOURS) {
+  const age = dumpAgeHours(stamp, nowMs);
+  if (age === null) return true;
+  return age > staleAfterHours;
+}
+
+function latestDump(nowMs = Date.now()) {
   let files;
   try {
     files = fs.readdirSync(BACKUP_DIR);
@@ -54,7 +86,18 @@ function latestDump() {
   try { size_bytes = fs.statSync(full).size; } catch { /* ok */ }
   // Filename: <db>-<YYYY-MM-DDTHHMMSSZ>.sql.gz — extract timestamp from it.
   const ts = name.replace(`${DB_NAME}-`, '').replace('.sql.gz', '');
-  return { filename: name, timestamp: ts, size_bytes, count: dumps.length };
+  const age = dumpAgeHours(ts, nowMs);
+  return {
+    filename: name,
+    timestamp: ts,
+    size_bytes,
+    count: dumps.length,
+    // Staleness is reported, not just implied by the timestamp, so a consumer
+    // (CLI, dashboard, alert) can act on one boolean instead of re-deriving it.
+    age_hours: age === null ? null : Math.round(age * 10) / 10,
+    stale: isStaleDump(ts, nowMs),
+    stale_after_hours: STALE_AFTER_HOURS,
+  };
 }
 
 module.exports = function buildBackupRouter() {
@@ -68,6 +111,11 @@ module.exports = function buildBackupRouter() {
         backup_dir: BACKUP_DIR,
         db_name: DB_NAME,
         latest_dump: dump,
+        // Top-level too, so a consumer gets a health signal WITHOUT having to
+        // special-case latest_dump===null. No dump at all is the worst state,
+        // not a neutral one, so it reports stale.
+        stale: dump ? dump.stale : true,
+        age_hours: dump ? dump.age_hours : null,
         trigger_running: triggerRunning,
       });
     }));
@@ -102,3 +150,11 @@ module.exports = function buildBackupRouter() {
 
   return router;
 };
+
+// Pure helpers exported for tests (tests/backup_cli.mjs) — importing the real
+// implementations beats re-implementing them in the test, which is how a test
+// can pass while the shipped code is wrong.
+module.exports.parseDumpTimestamp = parseDumpTimestamp;
+module.exports.dumpAgeHours = dumpAgeHours;
+module.exports.isStaleDump = isStaleDump;
+module.exports.STALE_AFTER_HOURS = STALE_AFTER_HOURS;

package/src/bongos/routes/github.js

@@ -0,0 +1,90 @@
+// src/bongos/routes/github.js — GitHub repo list/create for the signed-in user, the
+// server half of the onboarding wizard's repo picker (adopt) + auto-create (fresh).
+// Task 1002099 / ADR 0143.
+//
+// These act on the user's OWN GitHub identity, so they live in core auth alongside
+// the sign-in flow that captured the token — not the provisioning module (whose
+// charter holds no tokens / calls no cloud API, ADR 0111 §2). They read the
+// short-lived, secret-box-encrypted `public_repo` token the web callback stored
+// (db.js github_oauth_tokens). Two "please reconnect / fall back" signals the wizard
+// branches on:
+//   • no stored token           → repo_scope_required (403)  → prompt a repos sign-in
+//   • secret-box unconfigured   → github_repos_unavailable (503) → manual repo entry
+// Both are behind requireBuilder + the router-wide rate-limit middleware.
+
+const express = require('express');
+const auth = require('../auth');
+const db = require('../db');
+const secretBox = require('../secret-box');
+const { listUserRepos, createUserRepo } = require('../github-repos');
+const { validateOrRespond } = require('./_helpers');
+
+// GitHub repo names: 1–100 chars of [A-Za-z0-9._-]. We validate strictly for a clean
+// 400; anything GitHub still rejects surfaces as the 422→409 name_taken path.
+const REPO_NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+// Resolve the caller's stored repo token, or send the right failure and return null.
+// Centralizes the 503-vs-403 decision both endpoints share.
+async function resolveRepoToken(req, res) {
+  if (!secretBox.isConfigured()) {
+    res.fail('github_repos_unavailable', { status: 503, message: 'Repo access is not configured on this server. Enter the repository manually.' });
+    return null;
+  }
+  const row = await db.getGithubToken({ builderId: req.builder.id });
+  if (!row) {
+    res.fail('repo_scope_required', { status: 403, message: 'Grant repository access to list or create repos.' });
+    return null;
+  }
+  return row.token;
+}
+
+module.exports = function buildGithubRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — acts only on the caller's OWN GitHub identity (the token
+  // they granted). No rank gate beyond being a signed-in builder.
+  router.get('/github/repos', auth.requireBuilder, async (req, res) => {
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      const q = typeof req.query.q === 'string' ? req.query.q.slice(0, 100) : '';
+      const repos = await listUserRepos(token, { q });
+      res.json({ repos });
+    } catch (err) {
+      if (err && err.status === 401) {
+        // The stored token was revoked/expired GitHub-side — drop it and re-prompt.
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to list your repos.' });
+      }
+      console.error('[gds] GET /github/repos', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not be reached. Try again, or enter the repository manually.' });
+    }
+  });
+
+  // rank: any-builder — creates a repo in the caller's OWN account.
+  router.post('/github/repos', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { name: { required: true, type: 'string', maxLength: 100 } })) return;
+    const name = String((req.body && req.body.name) || '').trim();
+    if (!REPO_NAME_RE.test(name)) {
+      return res.fail('bad_repo_name', { status: 400, message: 'Repository names use letters, numbers, and . _ - (1–100 chars).' });
+    }
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      const repo = await createUserRepo(token, { name });
+      res.status(201).json({ repo });
+    } catch (err) {
+      if (err && err.code === 'name_taken') {
+        return res.fail('name_taken', { status: 409, message: 'You already have a repository with that name. Pick another, or adopt the existing one.' });
+      }
+      if (err && err.status === 401) {
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to create the repo.' });
+      }
+      console.error('[gds] POST /github/repos', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not create the repo. Try again, or create it manually.' });
+    }
+  });
+
+  return router;
+};

package/src/bongos/routes/instance.js

@@ -32,7 +32,7 @@ const { corsPublicGet, asyncHandler } = require('./_helpers');
 const { clientBranding } = require('../../branding');
 const { clientModules, isModuleEnabled } = require('../../modules');
 const { loadRepoInfo } = require('../repo-info');
-const { authConfigured, openEnrollmentEnabled } = require('../auth');
+const { authConfigured, openEnrollmentEnabled, loadIdpConfig } = require('../auth');
 const { RANK_TIER } = require('../permission-path-check');
 
 // The manifest format id — bumped when the SHAPE changes so a CLI can detect a
@@ -59,6 +59,7 @@ function buildInstanceManifest({
   authConfigured: authOk,
   openEnrollment,
   devBoxEnabled,
+  idp = null,
 } = {}) {
   const b = branding || {};
   const rankLabels = b.rankLabels || {};
@@ -89,8 +90,15 @@ function buildInstanceManifest({
     ranks,
     repo: repoOut,
     auth: {
-      methods: authOk ? AUTH_METHODS.slice() : [],
-      configured: !!authOk,
+      // Sign-in works when the instance has its OWN GitHub app (authOk) OR it
+      // federates through the hub (idp) — a hosted instance has no app of its own.
+      methods: (authOk || idp) ? AUTH_METHODS.slice() : [],
+      configured: !!authOk || !!idp,
+      // Federation hint (ADR 0141 §1): present only when this instance federates.
+      // origin + client_id are PUBLIC (like an OAuth client_id); the client SECRET
+      // is never projected here. The CLI reads this to route device-flow + web
+      // sign-in through the hub instead of expecting a local GitHub app.
+      idp: idp || null,
     },
     admission: { policy: openEnrollment ? 'open' : 'invite-only' },
     devBox: { available: !!devBoxEnabled },
@@ -109,6 +117,7 @@ module.exports = function buildInstanceRouter() {
   // err.message if branding/modules fail to resolve (misconfigured instance) —
   // never leaks internals.
   router.get('/instance', asyncHandler('GET /instance', (_req, res) => {
+    const idpCfg = loadIdpConfig();
     res.json(buildInstanceManifest({
       branding: clientBranding(),
       modules: clientModules(),
@@ -117,6 +126,9 @@ module.exports = function buildInstanceRouter() {
       authConfigured: authConfigured(),
       openEnrollment: openEnrollmentEnabled(),
       devBoxEnabled: isModuleEnabled('dev-box'),
+      // Project OUT the client secret — the manifest is public; only origin +
+      // client_id (both public) advertise federation.
+      idp: idpCfg ? { origin: idpCfg.origin, client_id: idpCfg.clientId } : null,
     }));
   }, { message: false, errorCode: 'instance_manifest_failed' }));