@bongos/core 1.18.3 → 1.18.18

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

@@ -0,0 +1,531 @@
+// modules/platform-identity/platform-identity.js — the hub identity-provider
+// domain (ADR 0141 §1/§2, task #1002106). Platform accounts + the SSO client
+// registry + single-use authorization codes.
+//
+// THE ONE RULE (ADR 0016 / ADR 0141): this surface returns IDENTITY only —
+// github_id, github_login, display_name, avatar_url — and NEVER a rank, credits,
+// admission, or a session token. Authority is computed locally on each federated
+// instance; the hub only answers "who is this GitHub user".
+//
+// Reaches core only through the doorway (src/module-api.js). The pure helpers
+// (sha256hex, constantTimeEqualHex, clientSecretValid, redirectUriAllowed,
+// newOpaqueCode) are exported for DB-free unit testing.
+'use strict';
+
+const crypto = require('node:crypto');
+const api = require('../../src/module-api');
+
+const { pool: defaultPool } = api;
+
+// Default authorization-code lifetime — deliberately short (~60s). A code is a
+// bearer secret that travels through the browser; a tight TTL bounds the replay
+// window even before the single-use guard fires.
+const DEFAULT_CODE_TTL_MS = 60 * 1000;
+
+// -------------------------------------------------------------------------
+// Pure crypto helpers (no DB, no network — unit-tested directly)
+// -------------------------------------------------------------------------
+
+// SHA-256 hex of a string. Used to hash both the opaque authorization code and
+// the client secret at rest. Both inputs are high-entropy random values, so a
+// fast hash is appropriate (no password-dictionary surface); hashing-at-rest
+// means a DB read leak never exposes a live code or secret.
+function sha256hex(s) {
+  return crypto.createHash('sha256').update(String(s), 'utf8').digest('hex');
+}
+
+// Constant-time comparison of two hex digests. Length-checks first (digest
+// lengths are fixed and non-secret), then crypto.timingSafeEqual so a timing
+// side-channel can't reveal how many leading bytes of a guessed secret matched.
+function constantTimeEqualHex(a, b) {
+  const ba = Buffer.from(String(a), 'utf8');
+  const bb = Buffer.from(String(b), 'utf8');
+  if (ba.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+// A fresh opaque authorization code: 256 bits of CSPRNG, base64url (URL-safe so
+// it rides a redirect query string without escaping).
+function newOpaqueCode() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+// A fixed decoy hash so the "unknown client" / "suspended client" paths perform
+// the SAME hashing + constant-time compare as a real wrong-secret attempt. Without
+// this, JS short-circuits before the compare for a missing client, leaking a timing
+// oracle that distinguishes a registered client_id from an unregistered one — the
+// "never distinguishes no-such-client from wrong-secret" guarantee (ADR 0141 §2).
+// The decoy value is irrelevant; only that the work is identical on every path.
+const DECOY_SECRET_HASH = sha256hex('platform-identity::absent-client::decoy');
+
+// Does `presentedSecret` match the client's stored secret_hash? Constant-time, and
+// constant-WORK: it always hashes the presented secret and runs one timingSafeEqual
+// (against the real hash, or the decoy when the client is missing/secretless), then
+// fails closed unless there was a real client secret to match. Callers may look the
+// client up once and let this decide, with no client_id-enumeration timing oracle.
+function clientSecretValid(client, presentedSecret) {
+  const hasRealSecret = !!(client && typeof client.secret_hash === 'string' && client.secret_hash);
+  const target = hasRealSecret ? client.secret_hash : DECOY_SECRET_HASH;
+  const match = constantTimeEqualHex(target, sha256hex(presentedSecret));
+  return hasRealSecret && match;
+}
+
+// Decide whether a RESOLVED hub session may complete the SSO handoff. resolveSession
+// (the raw resolver the browser leg uses so it can redirect-to-sign-in rather than
+// 401) does NOT apply the deny gates requireBuilder does (src/bongos/auth.js) — so
+// this replicates them: a deactivated account (status 'inactive'), a dev-box-scoped
+// token (source 'box', which lives OUTSIDE the ADR 0016 trust boundary), and any
+// non-human service principal (system_role set) must NOT federate. Pure + exported
+// so the gate is unit-tested directly. Returns { ok, reason }.
+function sessionUsableForFederation(session) {
+  if (!session) return { ok: false, reason: 'no_session' };
+  if (session.status === 'inactive') return { ok: false, reason: 'inactive' };
+  if (session.source === 'box') return { ok: false, reason: 'box_scope' };
+  if (session.system_role) return { ok: false, reason: 'service_principal' };
+  return { ok: true, reason: null };
+}
+
+// Is `redirectUri` in this client's exact-match allow-list? The open-redirect
+// guard (ADR 0141 §2 invariant #3): a code is only ever handed to a URI the
+// client pre-registered, so a victim client's code can't be steered to an
+// attacker callback.
+function redirectUriAllowed(client, redirectUri) {
+  return !!client
+    && Array.isArray(client.redirect_uris)
+    && client.redirect_uris.includes(redirectUri);
+}
+
+// -------------------------------------------------------------------------
+// Accounts
+// -------------------------------------------------------------------------
+
+// Upsert the platform account for a GitHub identity (keyed on the stable
+// github_id). Called at /sso/authorize for the signed-in hub user. Identity only.
+async function upsertAccount({ githubId, githubLogin, displayName, avatarUrl }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_accounts (github_id, github_login, display_name, avatar_url)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (github_id) DO UPDATE SET
+       github_login = EXCLUDED.github_login,
+       display_name = EXCLUDED.display_name,
+       avatar_url   = EXCLUDED.avatar_url,
+       updated_at   = now()
+     RETURNING id, github_id, github_login, display_name, avatar_url`,
+    [githubId, githubLogin, displayName ?? null, avatarUrl ?? null],
+  );
+  return rows[0];
+}
+
+// Resolve the platform account for a github_login (for invitations by handle). A
+// login isn't a stable key (it can change), so this returns the most-recently-seen
+// account for that login, or null. Used only to map an invite's handle → github_id.
+async function getAccountByLogin(githubLogin, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT github_id, github_login, display_name, avatar_url
+       FROM platform_identity_accounts WHERE lower(github_login) = lower($1)
+      ORDER BY updated_at DESC LIMIT 1`,
+    [String(githubLogin || '')],
+  );
+  return rows[0] || null;
+}
+
+async function getAccount(githubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, github_id, github_login, display_name, avatar_url, created_at, updated_at
+       FROM platform_identity_accounts WHERE github_id = $1`,
+    [githubId],
+  );
+  return rows[0] || null;
+}
+
+// -------------------------------------------------------------------------
+// SSO client registry
+// -------------------------------------------------------------------------
+
+// Register (or rotate) a federated project as an SSO client. Provisioning
+// (task #1002109) calls this with a freshly generated secret; the plaintext is
+// hashed here and never stored. Upsert-on-client_id so re-provisioning rotates
+// the secret + redirect_uris without a duplicate row.
+async function registerClient({ clientId, secret, name, redirectUris, origin, ownerGithubId }, { pool = defaultPool } = {}) {
+  const secretHash = sha256hex(secret);
+  const uris = Array.isArray(redirectUris) ? redirectUris : [];
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_sso_clients
+       (client_id, secret_hash, name, redirect_uris, origin, owner_github_id)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     ON CONFLICT (client_id) DO UPDATE SET
+       secret_hash     = EXCLUDED.secret_hash,
+       name            = EXCLUDED.name,
+       redirect_uris   = EXCLUDED.redirect_uris,
+       origin          = EXCLUDED.origin,
+       owner_github_id = EXCLUDED.owner_github_id,
+       updated_at      = now()
+     RETURNING id, client_id, name, redirect_uris, origin, owner_github_id, status`,
+    [clientId, secretHash, name, uris, origin ?? null, ownerGithubId ?? null],
+  );
+  // Auto-catalogue the project (unfeatured) so it appears in the Archon curation
+  // list the moment it federates (ADR 0141 §5). Best-effort — a catalog hiccup must
+  // never fail client registration. Only when an origin is known.
+  if (origin) {
+    try { await upsertProject({ origin, name, ownerGithubId }, { pool }); }
+    catch (err) { console.error('[platform-identity] auto-catalogue failed (non-fatal):', err.message); }
+  }
+  return rows[0];
+}
+
+// Fetch a client by its public id, including secret_hash (for the constant-time
+// compare at /sso/token). Returns null when unknown.
+async function getClient(clientId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT client_id, secret_hash, name, redirect_uris, origin, owner_github_id, status
+       FROM platform_identity_sso_clients WHERE client_id = $1`,
+    [clientId],
+  );
+  return rows[0] || null;
+}
+
+// Resolve the ACTIVE client for a given instance origin. This is the authoritative
+// mapping the CLI device-flow mint uses (ADR 0141 §1 security fix): the assertion's
+// audience is derived from the USER-TYPED origin via this lookup, so a malicious
+// instance manifest cannot steer the mint at a victim client_id. Exact-match on the
+// normalized origin (trailing slashes trimmed). Returns null when no active client
+// is registered for that origin (→ federation refuses, the correct default).
+async function getClientByOrigin(origin, { pool = defaultPool } = {}) {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  if (!norm) return null;
+  const { rows } = await pool.query(
+    `SELECT client_id, secret_hash, name, redirect_uris, origin, owner_github_id, status
+       FROM platform_identity_sso_clients
+      WHERE origin = $1 AND status = 'active'
+      ORDER BY id ASC LIMIT 1`,
+    [norm],
+  );
+  return rows[0] || null;
+}
+
+// -------------------------------------------------------------------------
+// Projects catalog + Explore (ADR 0141 §5)
+// -------------------------------------------------------------------------
+
+// Upsert a catalog row (keyed by origin). Called when a client registers (so every
+// federated project is catalogued, unfeatured) and by the Archon create/curate route.
+// Never touches `featured` on update — that is Archon-only via setProjectFeatured.
+async function upsertProject({ origin, name, tagline, artUrl, ownerGithubId }, { pool = defaultPool } = {}) {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  if (!norm) throw new Error('project origin required');
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_projects (origin, name, tagline, art_url, owner_github_id)
+     VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (origin) DO UPDATE SET
+       name            = EXCLUDED.name,
+       tagline         = COALESCE(EXCLUDED.tagline, platform_identity_projects.tagline),
+       art_url         = COALESCE(EXCLUDED.art_url, platform_identity_projects.art_url),
+       owner_github_id = COALESCE(EXCLUDED.owner_github_id, platform_identity_projects.owner_github_id),
+       updated_at      = now()
+     RETURNING id, origin, name, tagline, art_url, owner_github_id, status, featured`,
+    [norm, name || norm, tagline ?? null, artUrl ?? null, ownerGithubId ?? null],
+  );
+  return rows[0];
+}
+
+async function getProject(id, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, origin, name, tagline, art_url, owner_github_id, status, featured
+       FROM platform_identity_projects WHERE id = $1`,
+    [id],
+  );
+  return rows[0] || null;
+}
+
+// The PUBLIC Explore listing — featured + active projects only, public projection
+// (no owner_github_id, no status). Newest first.
+async function listFeaturedProjects({ pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT origin, name, tagline, art_url
+       FROM platform_identity_projects
+      WHERE featured = true AND status = 'active'
+      ORDER BY updated_at DESC`,
+  );
+  return rows;
+}
+
+// The Archon curation list — every active project + its featured flag.
+async function listAllProjects({ pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, origin, name, tagline, art_url, owner_github_id, status, featured, updated_at
+       FROM platform_identity_projects
+      WHERE status = 'active'
+      ORDER BY featured DESC, updated_at DESC`,
+  );
+  return rows;
+}
+
+// Archon-only: flip the Explore feature flag on a catalog row.
+async function setProjectFeatured(id, featured, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_projects SET featured = $2, updated_at = now()
+      WHERE id = $1 RETURNING id, origin, name, featured, status`,
+    [id, !!featured],
+  );
+  return rows[0] || null;
+}
+
+// -------------------------------------------------------------------------
+// Project memberships (the cross-project directory — ADR 0141 §3)
+// -------------------------------------------------------------------------
+
+const MEMBERSHIP_ROLES = ['owner', 'builder', 'visitor', 'pending'];
+
+// Upsert a builder's membership in a project (keyed by the reporting client + the
+// builder's github_id). COARSE role only — never a rank. Refreshes last_active on
+// every check-in. Returns the row.
+async function upsertMembership({ clientId, githubId, role = 'builder' }, { pool = defaultPool } = {}) {
+  const r = MEMBERSHIP_ROLES.includes(role) ? role : 'builder';
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_project_memberships (client_id, github_id, role)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (client_id, github_id) DO UPDATE SET
+       role        = EXCLUDED.role,
+       last_active = now()
+     RETURNING id, client_id, github_id, role, joined_at, last_active`,
+    [clientId, githubId, r],
+  );
+  return rows[0];
+}
+
+// All memberships for one account, newest-active first, joined to the project's
+// display fields (name/origin from sso_clients). Powers "My Projects" (task #1002112).
+async function listMembershipsForAccount(githubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT m.client_id, m.role, m.joined_at, m.last_active,
+            c.name AS project_name, c.origin AS project_origin, c.owner_github_id
+       FROM platform_identity_project_memberships m
+       LEFT JOIN platform_identity_sso_clients c ON c.client_id = m.client_id
+      WHERE m.github_id = $1 AND m.role <> 'pending'
+      ORDER BY m.last_active DESC`,
+    [githubId],
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Invitations (ADR 0141 §5, task #1002115) — pre-seed a 'pending' membership
+// -------------------------------------------------------------------------
+
+// Invite a builder into a project they don't yet build on: pre-seed a 'pending'
+// membership. Does NOT clobber an existing membership (ON CONFLICT DO NOTHING) — a
+// current member is left as-is. Returns { invited:true, row } when a pending row was
+// created, or { invited:false, alreadyMember:true } when a membership already existed.
+async function inviteToProject({ clientId, githubId }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_project_memberships (client_id, github_id, role)
+     VALUES ($1, $2, 'pending')
+     ON CONFLICT (client_id, github_id) DO NOTHING
+     RETURNING id, client_id, github_id, role`,
+    [clientId, githubId],
+  );
+  if (rows[0]) return { invited: true, row: rows[0] };
+  return { invited: false, alreadyMember: true };
+}
+
+// The pending invitations for one account (joined to the project display fields).
+async function listPendingInvitesForAccount(githubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT m.client_id, m.joined_at AS invited_at,
+            c.name AS project_name, c.origin AS project_origin
+       FROM platform_identity_project_memberships m
+       LEFT JOIN platform_identity_sso_clients c ON c.client_id = m.client_id
+      WHERE m.github_id = $1 AND m.role = 'pending'
+      ORDER BY m.joined_at DESC`,
+    [githubId],
+  );
+  return rows;
+}
+
+// Resolve a pending invite for (client, builder): accept → flip to 'builder' (the
+// membership becomes real; the builder then signs into the project, whose own gate
+// still applies + whose check-in keeps it fresh); decline → delete the pending row.
+// Only ever touches a 'pending' row, so it can't downgrade or remove a real member.
+async function resolveInvite({ clientId, githubId, accept }, { pool = defaultPool } = {}) {
+  if (accept) {
+    const { rows } = await pool.query(
+      `UPDATE platform_identity_project_memberships SET role = 'builder', last_active = now()
+        WHERE client_id = $1 AND github_id = $2 AND role = 'pending'
+        RETURNING id`,
+      [clientId, githubId],
+    );
+    return { resolved: rows.length > 0, accepted: true };
+  }
+  const { rowCount } = await pool.query(
+    `DELETE FROM platform_identity_project_memberships
+      WHERE client_id = $1 AND github_id = $2 AND role = 'pending'`,
+    [clientId, githubId],
+  );
+  return { resolved: rowCount > 0, accepted: false };
+}
+
+// Self-service LEAVE (ADR 0141 §3): remove a builder's membership in a project. The
+// directory reflects the leave immediately; if the builder still actively builds on
+// that instance they re-appear on their next sign-in check-in (the instance holds
+// local authority). Returns the number of rows removed (0 or 1).
+async function removeMembership(clientId, githubId, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM platform_identity_project_memberships WHERE client_id = $1 AND github_id = $2`,
+    [clientId, githubId],
+  );
+  return rowCount;
+}
+
+async function setClientStatus(clientId, status, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_sso_clients SET status = $2, updated_at = now()
+      WHERE client_id = $1 RETURNING client_id, status`,
+    [clientId, status],
+  );
+  return rows[0] || null;
+}
+
+// -------------------------------------------------------------------------
+// Cross-project builder activity (the scouting data plane — ADR 0141 §4)
+// -------------------------------------------------------------------------
+
+// Upsert one project's rollup for one builder (keyed by client_id + github_id).
+// Descriptive analytics — never authority. Refreshes last_active on each report.
+async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped = 0, karma = 0, rank = null, disciplines = [] }, { pool = defaultPool } = {}) {
+  const disc = Array.isArray(disciplines) ? disciplines : [];
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_builder_project_activity
+       (client_id, github_id, credits, tasks_shipped, karma, rank_held, disciplines, last_active, updated_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, now(), now())
+     ON CONFLICT (client_id, github_id) DO UPDATE SET
+       credits = EXCLUDED.credits, tasks_shipped = EXCLUDED.tasks_shipped, karma = EXCLUDED.karma,
+       rank_held = EXCLUDED.rank_held, disciplines = EXCLUDED.disciplines,
+       last_active = now(), updated_at = now()
+     RETURNING id, client_id, github_id`,
+    [clientId, githubId, credits | 0, tasksShipped | 0, karma | 0, rank, disc],
+  );
+  return rows[0];
+}
+
+// The scouting rollup: one row PER BUILDER, aggregated across every project they
+// build on. Joined to the account for display. Ranked by total credits then ships —
+// a talent signal, NOT an authority. Powers the Archon-only scouting view (#1002114).
+async function listScoutingRollup({ limit = 100, pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT a.github_id,
+            acc.github_login, acc.display_name, acc.avatar_url,
+            count(*)::int                        AS project_count,
+            sum(a.credits)::int                  AS total_credits,
+            sum(a.tasks_shipped)::int            AS total_tasks_shipped,
+            sum(a.karma)::int                    AS total_karma,
+            max(a.last_active)                   AS last_active,
+            array_agg(DISTINCT d) FILTER (WHERE d IS NOT NULL) AS disciplines
+       FROM platform_identity_builder_project_activity a
+       LEFT JOIN platform_identity_accounts acc ON acc.github_id = a.github_id
+       LEFT JOIN LATERAL unnest(a.disciplines) AS d ON true
+      GROUP BY a.github_id, acc.github_login, acc.display_name, acc.avatar_url
+      ORDER BY total_credits DESC, total_tasks_shipped DESC
+      LIMIT $1`,
+    [limit],
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Authorization codes (single-use, short-lived, bound)
+// -------------------------------------------------------------------------
+
+// Mint a single-use authorization code bound to (client_id, github_id,
+// redirect_uri), carrying an identity snapshot. Stores only the code's hash;
+// returns the plaintext code (the only place it ever exists outside the browser).
+async function mintAuthCode(
+  { clientId, githubId, githubLogin, displayName, avatarUrl, redirectUri, ttlMs = DEFAULT_CODE_TTL_MS },
+  { pool = defaultPool } = {},
+) {
+  const code = newOpaqueCode();
+  const codeHash = sha256hex(code);
+  const expiresAt = new Date(Date.now() + ttlMs);
+  await pool.query(
+    `INSERT INTO platform_identity_auth_codes
+       (code_hash, client_id, github_id, redirect_uri, github_login, display_name, avatar_url, expires_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+    [codeHash, clientId, githubId, redirectUri, githubLogin, displayName ?? null, avatarUrl ?? null, expiresAt],
+  );
+  return code;
+}
+
+// Atomically redeem a code for a given client. Single-winner by construction: the
+// UPDATE ... WHERE consumed_at IS NULL ... RETURNING flips consumed_at in the same
+// statement, so two concurrent redeems can never both succeed. Also enforces the
+// client binding and the TTL. Returns the identity snapshot (+ the bound
+// redirect_uri, for the caller's redirect_uri match) or null on any miss.
+async function redeemAuthCode({ code, clientId }, { pool = defaultPool } = {}) {
+  const codeHash = sha256hex(code);
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_auth_codes
+        SET consumed_at = now()
+      WHERE code_hash = $1
+        AND client_id = $2
+        AND consumed_at IS NULL
+        AND expires_at > now()
+      RETURNING github_id, github_login, display_name, avatar_url, redirect_uri`,
+    [codeHash, clientId],
+  );
+  return rows[0] || null;
+}
+
+// TTL sweep of expired / consumed codes — the bound on table growth (wired as a
+// module poller, pollers/code-sweep.js, started only on the hub). Codes have a ~60s
+// TTL, so a 5-minute grace after expiry/consumption is ample slack for clock skew
+// while keeping the table to roughly the last few minutes of sign-in traffic even
+// under a burst of mints. Cheap; safe to call on a timer.
+async function sweepExpiredCodes({ pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM platform_identity_auth_codes
+      WHERE expires_at < now() - interval '5 minutes'
+         OR (consumed_at IS NOT NULL AND consumed_at < now() - interval '5 minutes')`,
+  );
+  return rowCount;
+}
+
+module.exports = {
+  DEFAULT_CODE_TTL_MS,
+  // pure helpers
+  sha256hex,
+  constantTimeEqualHex,
+  newOpaqueCode,
+  clientSecretValid,
+  redirectUriAllowed,
+  sessionUsableForFederation,
+  // accounts
+  upsertAccount,
+  getAccount,
+  getAccountByLogin,
+  // clients
+  registerClient,
+  getClient,
+  getClientByOrigin,
+  setClientStatus,
+  // projects catalog + Explore
+  upsertProject,
+  getProject,
+  listFeaturedProjects,
+  listAllProjects,
+  setProjectFeatured,
+  // memberships
+  MEMBERSHIP_ROLES,
+  upsertMembership,
+  listMembershipsForAccount,
+  removeMembership,
+  // invitations
+  inviteToProject,
+  listPendingInvitesForAccount,
+  resolveInvite,
+  // cross-project activity + scouting
+  upsertActivity,
+  listScoutingRollup,
+  // codes
+  mintAuthCode,
+  redeemAuthCode,
+  sweepExpiredCodes,
+};

package/modules/platform-identity/pollers/code-sweep.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// modules/platform-identity/pollers/code-sweep.js — the loader poller entry that
+// bounds platform_identity_auth_codes growth (ADR 0141 §2). Codes have a ~60s TTL;
+// each /sso/authorize mints one row, and without a sweep the table would grow
+// unbounded. The loader's startModulePollers requires THIS file and calls
+// start(deps) at boot / stop() at shutdown for the ENABLED module only (the hub) —
+// non-blocking + failure-isolated, so a sweep hiccup never touches sign-in.
+//
+// Mirrors the lifecycle publish-reconciler poller shape.
+
+const pi = require('../platform-identity');
+
+// Every 5 minutes — codes expire in ~60s and the sweep keeps a 5-minute grace, so
+// this cadence keeps the table to roughly the last few minutes of traffic.
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+let timer = null;
+
+async function sweepOnce(deps = {}) {
+  try {
+    const n = await pi.sweepExpiredCodes(deps.pool ? { pool: deps.pool } : {});
+    if (n > 0) console.log(`[platform-identity] code-sweep: pruned ${n} expired/consumed auth code(s)`);
+  } catch (err) {
+    // Best-effort: a sweep failure must never crash the process or block sign-in.
+    console.error('[platform-identity] code-sweep failed (non-fatal):', err && err.message);
+  }
+}
+
+module.exports = {
+  start: (deps = {}) => {
+    if (timer) return; // idempotent
+    // unref so the sweep timer never keeps the process alive on its own.
+    timer = setInterval(() => { sweepOnce(deps); }, SWEEP_INTERVAL_MS);
+    if (timer.unref) timer.unref();
+  },
+  stop: () => {
+    if (timer) { clearInterval(timer); timer = null; }
+  },
+  // exported for tests
+  sweepOnce,
+  SWEEP_INTERVAL_MS,
+};