@bongos/core 1.18.3 → 1.18.19

package/modules/platform-identity/routes/sso.js

@@ -0,0 +1,402 @@
+// modules/platform-identity/routes/sso.js — the hub SSO login-handoff surface
+// (ADR 0141 §1/§2, task #1002106). Two endpoints:
+//
+//   GET  /sso/authorize — the browser leg. Gated on a LIVE HUB SESSION (resolved
+//                         inline; bounces to the hub's own sign-in when absent).
+//                         Validates the client + redirect_uri, mints a single-use
+//                         code, and 302s back to the instance's redirect_uri.
+//   POST /sso/token     — the server-to-server leg. Authenticated by client_id +
+//                         client_secret (constant-time). Atomically redeems the
+//                         code and returns IDENTITY ONLY — never a rank.
+//
+// Reaches core ONLY through the doorway (src/module-api.js, the one-way rule,
+// ADR 0083); requires this module's own platform-identity.js (same package),
+// never a sibling module.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+const hubKeys = require('../hub-keys');
+const hubDevice = require('../hub-device');
+
+const { pool, validateOrRespond, resolveSession } = api;
+
+// Minimal standalone error page for the browser leg (no template engine / deps).
+// The /sso/authorize failures are pre-redirect (bad client / bad redirect_uri), so
+// we must render our OWN page rather than bounce to an unvalidated URI.
+function errorPage(detail) {
+  const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">`
+    + `<meta name="viewport" content="width=device-width, initial-scale=1">`
+    + `<title>Sign-in handoff failed</title></head><body>`
+    + `<h1>Sign-in handoff failed</h1><p>${esc(detail)}</p>`
+    + `<p>This link came from a project trying to sign you in through Cloud Bongos. `
+    + `If it keeps happening, the project's sign-in may be misconfigured.</p></body></html>`;
+}
+
+// --- Federated single-logout fan-out (ADR 0144, task 1002238) --------------
+// When a builder signs out of the HUB, core emits a `builder.logout` seam event;
+// this module (enabled only on the hub) reacts by sending a hub-signed logout
+// token to every federated project the builder entered, so each revokes its own
+// local session too. Back-channel (server-to-server) so sign-out sticks even if
+// the browser closes the tab, and doesn't depend on third-party-cookie rules.
+
+const SLO_TIMEOUT_MS = 4000; // per-instance notify budget — a slow/down project must never wedge the sweep
+
+// Registered once (guarded against a route rebuild, e.g. in tests) at first mount.
+let _logoutListenerOff = null;
+
+// POST one hub-signed logout token to a single federated instance, bounded by a
+// short timeout. NEVER throws (the caller runs it under Promise.allSettled + this
+// try/catch), so one unreachable project can't sink the others.
+async function notifyInstanceLogout(membership, githubId) {
+  const origin = String(membership.project_origin).replace(/\/+$/, '');
+  try {
+    const token = hubKeys.mintHubLogoutToken({ clientId: membership.client_id, githubId });
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), SLO_TIMEOUT_MS);
+    try {
+      const resp = await fetch(`${origin}/api/gds/auth/backchannel-logout`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ logout_token: token }),
+        signal: ac.signal,
+      });
+      if (!resp.ok) console.warn(`[platform-identity] SLO: ${origin} returned ${resp.status}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    console.warn(`[platform-identity] SLO: notifying ${origin} failed (non-blocking):`, err && err.message ? err.message : err);
+  }
+}
+
+// Fan a back-channel logout out to every federated project the builder entered.
+// Runs off a fire-and-forget event, so it MUST NOT throw (a floating rejection
+// would be an unhandledRejection). Over-notifying is safe: an instance with no
+// live session for the builder just revokes nothing (idempotent). Uses the
+// builder's known memberships as the entered-instance list (ADR 0141 §3 rows) —
+// the task's sanctioned V1 signal; a precise per-session entry ledger is a follow-up.
+async function fanOutBackchannelLogout(githubId) {
+  try {
+    if (githubId == null) return;
+    // Only the hub mints logout tokens; no signing key ⇒ not the hub ⇒ nothing to do
+    // (defense-in-depth beyond the module being hub-only).
+    if (!hubKeys.hubSigningConfigured()) return;
+    const memberships = await pi.listMembershipsForAccount(githubId, { pool });
+    const targets = (memberships || []).filter((m) => m.project_origin && m.client_id);
+    await Promise.allSettled(targets.map((m) => notifyInstanceLogout(m, githubId)));
+  } catch (err) {
+    console.error('[platform-identity] SLO fan-out failed (non-blocking):', err && err.message ? err.message : err);
+  }
+}
+
+module.exports = function ssoRoutes() {
+  const router = express.Router();
+
+  // Wire the federated single-logout fan-out to core's `builder.logout` event,
+  // once. The handler is deliberately fire-and-forget (fanOut self-isolates), so
+  // the hub's own /auth/logout returns immediately and the sweep runs server-side.
+  if (!_logoutListenerOff) {
+    _logoutListenerOff = api.on('builder.logout', ({ githubId }) => { fanOutBackchannelLogout(githubId); });
+  }
+
+  // GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg.
+  //
+  // rank: public — this is an authentication entry point, not an authorization
+  //   surface. It is gated on a LIVE HUB SESSION (resolved inline via
+  //   resolveSession; a missing session 302s to the hub's own web sign-in and
+  //   returns here), NOT on a builder RANK. It mints identity-only codes.
+  router.get('/sso/authorize', async (req, res) => {
+    const clientId = String(req.query.client_id || '');
+    const redirectUri = String(req.query.redirect_uri || '');
+    const state = req.query.state != null ? String(req.query.state) : '';
+
+    if (!clientId || !redirectUri) {
+      return res.status(400).type('text/html').send(errorPage('Missing client_id or redirect_uri.'));
+    }
+    // Bound the query params (the POST leg validates via validateOrRespond; GET
+    // params are read raw, so cap them here). An oversized value is never useful
+    // and only amplifies work / the reflected Location header.
+    if (clientId.length > 200 || redirectUri.length > 2048 || state.length > 512) {
+      return res.status(400).type('text/html').send(errorPage('A sign-in parameter was too long.'));
+    }
+    // Validate the client + redirect_uri BEFORE doing anything else, and never
+    // redirect to an unvalidated URI (open-redirect guard, ADR 0141 §2 #3).
+    let client;
+    try {
+      client = await pi.getClient(clientId, { pool });
+    } catch (err) {
+      console.error('[platform-identity] /sso/authorize getClient', err);
+      return res.status(500).type('text/html').send(errorPage('Internal error resolving the project.'));
+    }
+    if (!client || client.status !== 'active') {
+      return res.status(400).type('text/html').send(errorPage('Unknown or suspended project (client_id).'));
+    }
+    if (!pi.redirectUriAllowed(client, redirectUri)) {
+      return res.status(400).type('text/html').send(errorPage('The redirect_uri is not registered for this project.'));
+    }
+
+    // Gate on a live hub session; bounce to the hub's own sign-in if absent, then
+    // return here to complete. safeReturnTo on the web flow validates the relative
+    // return path, so req.originalUrl (same-host, relative) is accepted.
+    //
+    // resolveSession is the RAW resolver (so we can redirect rather than 401), so it
+    // does NOT apply requireBuilder's deny gates — we must. sessionUsableForFederation
+    // rejects a deactivated account, a dev-box-scoped token (outside the ADR 0016
+    // trust boundary), and service principals: none may mint a federated identity code.
+    let session;
+    try {
+      session = await resolveSession(req);
+    } catch (err) {
+      console.error('[platform-identity] /sso/authorize resolveSession', err);
+      return res.status(500).type('text/html').send(errorPage('Internal error checking your hub session.'));
+    }
+    const usable = pi.sessionUsableForFederation(session);
+    if (!usable.ok) {
+      if (usable.reason === 'no_session') {
+        return res.redirect(302, `/api/gds/auth/web/start?return=${encodeURIComponent(req.originalUrl)}`);
+      }
+      const msg = usable.reason === 'inactive'
+        ? 'This account is no longer active. Ask an Archon on the hub if you believe this is an error.'
+        : usable.reason === 'box_scope'
+          ? 'A dev-box session cannot be used for cross-project sign-in. Sign in from a browser or run /builder-reauth.'
+          : 'This session type cannot be used for cross-project sign-in.';
+      return res.status(403).type('text/html').send(errorPage(msg));
+    }
+
+    // A live hub session — record/refresh the platform account and mint a
+    // single-use code bound to (client_id, github_id, redirect_uri).
+    try {
+      await pi.upsertAccount({
+        githubId: session.github_id,
+        githubLogin: session.github_login,
+        displayName: session.display_name,
+        avatarUrl: session.avatar_url,
+      }, { pool });
+      const code = await pi.mintAuthCode({
+        clientId,
+        githubId: session.github_id,
+        githubLogin: session.github_login,
+        displayName: session.display_name,
+        avatarUrl: session.avatar_url,
+        redirectUri,
+      }, { pool });
+      const u = new URL(redirectUri);
+      u.searchParams.set('code', code);
+      if (state) u.searchParams.set('state', state);
+      return res.redirect(302, u.toString());
+    } catch (err) {
+      console.error('[platform-identity] /sso/authorize mint', err);
+      return res.status(500).type('text/html').send(errorPage('Could not complete the sign-in handoff.'));
+    }
+  });
+
+  // POST /sso/token — server-to-server code redemption.
+  //
+  // rank: public — authenticated by client_id + client_secret (constant-time hash
+  //   compare in clientSecretValid), NOT a builder session/rank. This is the
+  //   confidential-client leg; the instance calls it from its server, never the
+  //   browser. Returns IDENTITY ONLY (github_id, login, display_name, avatar_url).
+  router.post('/sso/token', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+      code: { required: true, type: 'string', maxLength: 512 },
+      redirect_uri: { required: true, type: 'string', maxLength: 2048 },
+    })) return;
+
+    const { client_id, client_secret, code, redirect_uri } = req.body || {};
+    try {
+      const client = await pi.getClient(client_id, { pool });
+      // ALWAYS run the constant-work secret check (clientSecretValid hashes +
+      // constant-time-compares against a decoy when the client is missing), so an
+      // unknown/suspended client_id is timing-indistinguishable from a wrong secret.
+      // Then fold in the active check. One generic invalid_client for every failure.
+      const secretOk = pi.clientSecretValid(client, client_secret);
+      const active = !!client && client.status === 'active';
+      if (!active || !secretOk) {
+        return res.fail('invalid_client', 401);
+      }
+      // Atomic single-use redeem, bound to this client.
+      const identity = await pi.redeemAuthCode({ code, clientId: client_id }, { pool });
+      if (!identity) {
+        return res.fail('invalid_grant', 400);
+      }
+      // The redeem is also bound to the redirect_uri the code was minted against.
+      if (identity.redirect_uri !== redirect_uri) {
+        return res.fail('invalid_grant', 400);
+      }
+      // IDENTITY ONLY — never a rank, credits, or a session token (ADR 0016 / 0141).
+      return res.json({
+        github_id: Number(identity.github_id),
+        github_login: identity.github_login,
+        display_name: identity.display_name,
+        avatar_url: identity.avatar_url,
+      });
+    } catch (err) {
+      console.error('[platform-identity] POST /sso/token', err);
+      return res.fail('token_exchange_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). An
+  // instance provisioned WITHOUT the key in env can fetch it here; the value is
+  // public by design (it only VERIFIES assertions, never signs).
+  //
+  // rank: public — a public key is not a secret; no auth needed.
+  router.get('/sso/pubkey', (_req, res) => {
+    const publicKeyB64 = hubKeys.hubPublicKeyB64();
+    if (!publicKeyB64) return res.fail('idp_signing_unconfigured', 503);
+    res.json({ alg: 'EdDSA', format: 'spki-der-base64', public_key_b64: publicKeyB64 });
+  });
+
+  // POST /sso/device/start — begin CLI federation. The client is resolved from the
+  // USER-TYPED instance ORIGIN via the registry (getClientByOrigin) and BOUND to the
+  // device flow — the CLI never names the audience. This closes the confused-deputy
+  // where a malicious instance manifest could steer the mint at a victim client_id
+  // (ADR 0141 §1 security fix). Runs the GitHub device flow against the HUB's app and
+  // returns the codes. Identity is established as a platform ACCOUNT at poll time —
+  // never a hub-builder session (ADR 0141: identity federated, authority local).
+  //
+  // rank: public — an authentication entry point; the origin is public, and the
+  //   poll's GitHub approval is the real gate.
+  router.post('/sso/device/start', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      origin: { required: true, type: 'string', maxLength: 512 },
+    })) return;
+    if (!hubKeys.hubSigningConfigured() || !hubDevice.hubDeviceConfigured()) {
+      return res.fail('idp_signing_unconfigured', 503);
+    }
+    try {
+      // Resolve the client from the user-typed origin — NOT from any client_id the
+      // caller supplies. An unregistered origin has no client → refuse (correct default).
+      const client = await pi.getClientByOrigin(req.body.origin, { pool });
+      if (!client || client.status !== 'active') return res.fail('invalid_client', 401);
+      const out = await hubDevice.startHubGithubDevice(client.client_id);
+      res.json(out);
+    } catch (err) {
+      console.error('[platform-identity] /sso/device/start', err);
+      res.fail('device_start_failed', { status: 502, message: String(err.message || 'error').slice(0, 200) });
+    }
+  });
+
+  // POST /sso/device/poll — poll the hub device flow. On GitHub approval, upsert the
+  // platform account and mint an audience-scoped EdDSA assertion for the client that
+  // was BOUND at start (from the origin) — the poll takes NO client_id, so the CLI
+  // cannot influence the audience. Returns the SAME poll states as the core device
+  // flow, plus { state:'ok', assertion } on success.
+  //
+  // rank: public — the device_code (GitHub's) is the bearer; the assertion carries
+  //   identity ONLY and is useless to anyone but the origin-bound client (aud-scoped).
+  router.post('/sso/device/poll', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      device_code: { required: true, type: 'string', maxLength: 512 },
+    })) return;
+    if (!hubKeys.hubSigningConfigured() || !hubDevice.hubDeviceConfigured()) {
+      return res.fail('idp_signing_unconfigured', 503);
+    }
+    try {
+      const out = await hubDevice.pollHubGithubDevice(req.body.device_code);
+      if (out.state !== 'ok') return res.json(out); // pending | slow_down | expired | denied
+      if (!out.client_id) return res.fail('device_poll_failed', { status: 500, message: 'internal error' });
+      const id = out.identity;
+      await pi.upsertAccount({
+        githubId: id.github_id,
+        githubLogin: id.github_login,
+        displayName: id.display_name,
+        avatarUrl: id.avatar_url,
+      }, { pool });
+      const assertion = hubKeys.mintHubAssertion({
+        clientId: out.client_id, // BOUND at start from the origin — not caller-supplied
+        githubId: id.github_id,
+        githubLogin: id.github_login,
+        displayName: id.display_name,
+        avatarUrl: id.avatar_url,
+      });
+      res.json({ state: 'ok', assertion });
+    } catch (err) {
+      console.error('[platform-identity] /sso/device/poll', err);
+      res.fail('device_poll_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /sso/membership/check-in — a federated instance reports, on every sign-in,
+  // that a builder builds on its project (ADR 0141 §3). Server-to-server, authed by
+  // client_id + client_secret (same constant-time check as /sso/token). Upserts the
+  // account (so a CLI-only builder still appears in My Projects) + the membership
+  // with a COARSE role. The client_id is taken from the AUTHENTICATED client — the
+  // caller cannot report membership for a project it doesn't hold the secret for.
+  //
+  // rank: public — authenticated by client_id + client_secret, not a builder rank.
+  router.post('/sso/membership/check-in', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+      github_id: { required: true },
+      github_login: { required: true, type: 'string', maxLength: 200 },
+      display_name: { type: 'string', maxLength: 400 },
+      avatar_url: { type: 'string', maxLength: 2048 },
+      role: { type: 'string', maxLength: 16 },
+    })) return;
+    const { client_id, client_secret, github_id, github_login, display_name, avatar_url, role } = req.body || {};
+    try {
+      const client = await pi.getClient(client_id, { pool });
+      if (!client || client.status !== 'active' || !pi.clientSecretValid(client, client_secret)) {
+        return res.fail('invalid_client', 401);
+      }
+      // Upsert the account first so a CLI-only builder is known to the hub, then the
+      // membership — keyed to the AUTHENTICATED client_id, never a caller-named one.
+      await pi.upsertAccount({ githubId: github_id, githubLogin: github_login, displayName: display_name, avatarUrl: avatar_url }, { pool });
+      await pi.upsertMembership({ clientId: client_id, githubId: github_id, role: role || 'builder' }, { pool });
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[platform-identity] /sso/membership/check-in', err);
+      res.fail('checkin_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /sso/activity/rollup — a federated instance reports a builder's activity
+  // snapshot (ADR 0141 §4). Server-to-server, client_id+client_secret auth. Keyed to
+  // the AUTHENTICATED client_id. Descriptive analytics for the Archon-only scouting
+  // view — never authority.
+  //
+  // rank: public — authenticated by client_id + client_secret, not a builder rank.
+  router.post('/sso/activity/rollup', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+      github_id: { required: true },
+      credits: { type: 'number' },
+      tasks_shipped: { type: 'number' },
+      karma: { type: 'number' },
+      rank: { type: 'string', maxLength: 32 },
+      disciplines: {},
+    })) return;
+    const b = req.body || {};
+    try {
+      const client = await pi.getClient(b.client_id, { pool });
+      if (!client || client.status !== 'active' || !pi.clientSecretValid(client, b.client_secret)) {
+        return res.fail('invalid_client', 401);
+      }
+      await pi.upsertActivity({
+        clientId: b.client_id,
+        githubId: b.github_id,
+        credits: b.credits,
+        tasksShipped: b.tasks_shipped,
+        karma: b.karma,
+        rank: b.rank || null,
+        disciplines: Array.isArray(b.disciplines) ? b.disciplines : [],
+      }, { pool });
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[platform-identity] /sso/activity/rollup', err);
+      res.fail('rollup_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};