@bongos/core 1.17.0

package/src/bongos/api-errors.js

@@ -0,0 +1,281 @@
+// src/bongos/api-errors.js — the API error CONTRACT (BONGOS-V1 goal 36 / task 1988, R01).
+//
+// One error shape, everywhere. Every API failure is reported as a single
+// documented envelope:
+//
+//     { "error": { "code": "task_not_found", "message": "…", "details": … } }
+//
+//   - code:    a stable, machine-readable slug a caller can switch on. The
+//              specific slug is PRESERVED (a caller keying on `task_not_found`
+//              keeps working); the taxonomy collapses codes by CATEGORY, it does
+//              not discard them.
+//   - message: human-readable, safe to surface. Never leaks internals unless a
+//              handler opts in (see R02's asyncHandler `message` flag).
+//   - details: optional structured payload (e.g. the validator's field errors).
+//
+// This module is the CONTRACT only — the pure registry + formatter + `ApiError`
+// class. It wires nothing into the running app and changes no behaviour on its
+// own: the central Express handler + `res.fail()` helper that USE it land in R02
+// (task 1989), and the ~219-handler sweep onto it lands in R04 (task 1991).
+// Until then nothing imports this, so importing it is a no-op at runtime.
+//
+// Why a registry (ADR 0116): an audit of the live surface found 352 distinct
+// ad-hoc `error:'…'` string literals across 400/401/403/404/409/413/422/429/
+// 500/502/503. A caller cannot write ONE error-handling path against 352
+// unrelated strings. The registry collapses them onto ~12 canonical CATEGORIES,
+// each with a default HTTP status and a `retriable` flag, via an explicit
+// OVERRIDES table for the exceptions plus a naming heuristic for the long tail.
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Canonical categories — the taxonomy the 352 codes collapse onto. Each has the
+// HTTP status a code in that category defaults to (a call site may still pass an
+// explicit status override — the sweep preserves each site's current status) and
+// whether a client may sensibly retry the same request unchanged.
+// ---------------------------------------------------------------------------
+const CATEGORIES = Object.freeze({
+  bad_request:        { status: 400, retriable: false, description: 'Malformed or invalid request (bad param, missing field, wrong type).' },
+  validation_failed:  { status: 400, retriable: false, description: 'Request failed spec/schema validation; `details` lists the field errors.' },
+  unauthenticated:    { status: 401, retriable: false, description: 'No valid session/credential presented.' },
+  forbidden:          { status: 403, retriable: false, description: 'Authenticated, but rank/ownership does not permit the action.' },
+  not_found:          { status: 404, retriable: false, description: 'The referenced resource does not exist.' },
+  conflict:           { status: 409, retriable: false, description: 'Request conflicts with current state (already exists, cycle, active claim, stale tip).' },
+  payload_too_large:  { status: 413, retriable: false, description: 'Request body/element exceeds the size limit.' },
+  unprocessable:      { status: 422, retriable: false, description: 'Well-formed but semantically unacceptable.' },
+  rate_limited:       { status: 429, retriable: true,  description: 'Too many requests / quota exhausted; back off and retry.' },
+  internal:           { status: 500, retriable: true,  description: 'Unexpected server error or a server-side operation that failed.' },
+  bad_gateway:        { status: 502, retriable: true,  description: 'An upstream dependency returned an invalid response.' },
+  unavailable:        { status: 503, retriable: true,  description: 'A required dependency/feature is not configured or is temporarily down.' },
+});
+
+const DEFAULT_CATEGORY = 'internal';
+
+// ---------------------------------------------------------------------------
+// OVERRIDES — codes whose category the naming heuristic below would get WRONG.
+// Everything the heuristic already classifies correctly is intentionally absent
+// (the heuristic is the registry's long tail; this table is only its exceptions).
+// ---------------------------------------------------------------------------
+const OVERRIDES = Object.freeze({
+  // --- auth: 401 (the heuristic can't tell these from generic bad input) ---
+  unauthenticated: 'unauthenticated',
+  cookie_required: 'unauthenticated',
+  unknown_or_expired: 'unauthenticated',
+  box_scope: 'forbidden',
+
+  // --- forbidden: 403 (rank/ownership, not "missing" or "bad input") ---
+  forbidden: 'forbidden',
+  rank_forbidden: 'forbidden',
+  archon_approval_required: 'forbidden',
+  archon_required_for_protected_scope: 'forbidden',
+  metic_required_for_ownership: 'forbidden',
+  metic_required_for_protected_scope: 'forbidden',
+  not_owner: 'forbidden',
+  not_owner_or_manager: 'forbidden',
+  not_your_task: 'forbidden',
+  not_a_member: 'forbidden',
+  cannot_change_own_rank: 'forbidden',
+  cannot_change_own_status: 'forbidden',
+  cannot_demote: 'forbidden',
+  cannot_promote: 'forbidden',
+  owner_only_demotion: 'forbidden',
+  owner_role_fixed: 'forbidden',
+  karma_delta_not_allowed: 'forbidden',
+  above_rank_cap: 'forbidden',
+  not_bfg_principal: 'forbidden',
+  not_discord_bot_principal: 'forbidden',
+  bfg_cannot_write_self: 'forbidden',
+  bfg_write_disabled: 'forbidden',
+  target_is_system_principal: 'forbidden',
+  self_vote_forbidden: 'forbidden',
+  self_dep: 'conflict',
+  newcomer_must_ship_first: 'forbidden',
+  verify_attestation_required: 'forbidden',
+  multi_rung_promotion: 'conflict',
+
+  // --- conflict: 409 (state clash, not a missing resource) ---
+  cycle: 'conflict',
+  task_claimed: 'conflict',
+  task_has_active_claim: 'conflict',
+  session_already_has_active_claim: 'conflict',
+  vote_already_counted: 'conflict',
+  backup_already_running: 'conflict',
+  open_request_exists: 'conflict',
+  request_not_open: 'conflict',
+  pairing_busy: 'conflict',
+  busy: 'conflict',
+  tip_mismatch: 'conflict',
+  set_mismatch: 'conflict',
+  rescope_conflict: 'conflict',
+  role_change_conflict: 'conflict',
+  transfer_conflict: 'conflict',
+  criterion_exists: 'conflict',
+  version_exists: 'conflict',
+  version_closed: 'conflict',
+  discord_taken: 'conflict',
+  slug_taken: 'conflict',
+  parent_has_parent: 'conflict',
+  rank_unchanged: 'conflict',
+  cannot_abandon_shipped: 'conflict',
+  goal_not_open: 'conflict',
+  blocker_not_open: 'conflict',
+  pr_not_open: 'conflict',
+  criterion_version_mismatch: 'conflict',
+  goal_version_mismatch: 'conflict',
+  builder_id_mismatch: 'conflict',
+
+  // --- precondition read as conflict, not not_found ---
+  no_active_claim: 'conflict',
+  no_head_sha: 'conflict',
+  no_shipping_builder: 'conflict',
+  task_not_completed: 'conflict',
+  task_not_confirmed: 'conflict',
+  task_not_gradable: 'conflict',
+  task_not_votable: 'conflict',
+  not_approved: 'conflict',
+  not_archived: 'conflict',
+  not_inactive: 'conflict',
+  not_pending: 'conflict',
+  already_approved: 'conflict',
+  already_archived: 'conflict',
+  already_inactive: 'conflict',
+  already_member: 'conflict',
+  already_resolved: 'conflict',
+
+  // --- payload too large: 413 ---
+  bundle_too_large: 'payload_too_large',
+  batch_too_large: 'payload_too_large',
+  detail_payload_too_large: 'payload_too_large',
+  detail_element_too_large: 'payload_too_large',
+
+  // --- rate/quota: 429 ---
+  rate_limited: 'rate_limited',
+  quota_exceeded: 'rate_limited',
+  too_many_live_connections: 'rate_limited',
+
+  // --- unavailable: 503 (dependency/feature not wired) ---
+  auth_not_configured: 'unavailable',
+  push_unconfigured: 'unavailable',
+  publish_unconfigured: 'unavailable',
+  storage_not_configured: 'unavailable',
+  grading_unavailable: 'unavailable',
+  bot_unavailable: 'unavailable',
+  security_adr_not_provisioned: 'unavailable',
+  stage_gate_misconfigured: 'unavailable',
+
+  // --- validation ---
+  validation_failed: 'validation_failed',
+  schema_error: 'validation_failed',
+});
+
+// Suffix/prefix heuristic for the long tail. Order matters — first match wins.
+// These encode the naming conventions the audit surfaced across the 352 codes.
+const SUFFIX_RULES = [
+  [/_failed$/, 'internal'],
+  [/_error$/, 'internal'],
+  [/_not_found$/, 'not_found'],
+  [/_required$/, 'bad_request'],
+  [/_mismatch$/, 'bad_request'],
+  [/_too_large$/, 'payload_too_large'],
+  [/_too_long$/, 'bad_request'],
+  [/_taken$/, 'conflict'],
+  [/_exists$/, 'conflict'],
+  [/_conflict$/, 'conflict'],
+  [/_unconfigured$/, 'unavailable'],
+  [/_unavailable$/, 'unavailable'],
+];
+const PREFIX_RULES = [
+  [/^bad_/, 'bad_request'],
+  [/^invalid_/, 'bad_request'],
+  [/^must_be_/, 'bad_request'],
+  [/^not_a_/, 'bad_request'],
+  [/^unknown_/, 'bad_request'],
+  [/^duplicate_/, 'bad_request'],
+  [/^too_many_/, 'bad_request'],
+  [/^already_/, 'conflict'],
+];
+
+// classify(code) — the canonical CATEGORY for an error code. Pure + total: an
+// unrecognised code falls back to `internal` (500), the safe default (an
+// unexpected failure), never throwing. This is the registry's authoritative
+// classifier; the sweep (R04) and the middleware (R02) both call it.
+function classify(code) {
+  if (typeof code !== 'string' || !code) return DEFAULT_CATEGORY;
+  if (OVERRIDES[code]) return OVERRIDES[code];
+  for (const [re, cat] of SUFFIX_RULES) if (re.test(code)) return cat;
+  for (const [re, cat] of PREFIX_RULES) if (re.test(code)) return cat;
+  return DEFAULT_CATEGORY;
+}
+
+// statusForCode(code, override?) — the HTTP status for a code. An explicit
+// numeric override wins (call sites that already return, say, 422 keep it); else
+// the category's default status.
+function statusForCode(code, override) {
+  if (Number.isInteger(override)) return override;
+  const cat = CATEGORIES[classify(code)] || CATEGORIES[DEFAULT_CATEGORY];
+  return cat.status;
+}
+
+function categoryForCode(code) {
+  return classify(code);
+}
+
+function isRetriable(code) {
+  const cat = CATEGORIES[classify(code)] || CATEGORIES[DEFAULT_CATEGORY];
+  return !!cat.retriable;
+}
+
+// ---------------------------------------------------------------------------
+// ApiError — the throwable carrier of the contract. A handler `throw`s one and
+// the central middleware (R02) formats it into the envelope with the right
+// status. `status` and `message` are optional (derived from the registry).
+// ---------------------------------------------------------------------------
+class ApiError extends Error {
+  constructor(code, { status, message, details, cause } = {}) {
+    super(message || code);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = statusForCode(code, status);
+    this.category = classify(code);
+    if (details !== undefined) this.details = details;
+    if (cause !== undefined) this.cause = cause;
+    this.isApiError = true;
+  }
+}
+
+function isApiError(x) {
+  return !!x && (x instanceof ApiError || x.isApiError === true);
+}
+
+// envelope(codeOrError, message?, details?) — the pure formatter. Returns the
+// wire object `{ error: { code, message, details? } }`. Accepts a bare code
+// string, an ApiError, or any thrown value (which formats as an `internal`
+// envelope without leaking the raw message).
+function envelope(codeOrError, message, details) {
+  if (isApiError(codeOrError)) {
+    const e = codeOrError;
+    const out = { code: e.code, message: e.message || e.code };
+    if (e.details !== undefined) out.details = e.details;
+    return { error: out };
+  }
+  if (typeof codeOrError === 'string') {
+    const out = { code: codeOrError, message: message || codeOrError };
+    if (details !== undefined) out.details = details;
+    return { error: out };
+  }
+  // A raw thrown value — never leak it; report a generic internal envelope.
+  return { error: { code: 'internal_error', message: message || 'internal_error' } };
+}
+
+module.exports = {
+  CATEGORIES,
+  OVERRIDES,
+  DEFAULT_CATEGORY,
+  classify,
+  categoryForCode,
+  statusForCode,
+  isRetriable,
+  ApiError,
+  isApiError,
+  envelope,
+};

package/src/bongos/api-path-404.js

@@ -0,0 +1,67 @@
+// api-path-404.js — recognize GDS-API-shaped request paths that missed the API
+// mount, so the server-level 404 can answer with a JSON body + a corrective hint
+// instead of the HTML island page. V4.R14 / #952 (criterion: machine-room-
+// ergonomics — self-describing errors).
+//
+// WHY: a caller that forgets the prefix (curl /tasks) or drops the /api segment
+// (/bongos/tasks, /gds/tasks) used to fall through to public/404.html. A
+// programmatic client then did `JSON.parse('<!doctype html>…')` and got a
+// confusing secondary fault instead of a clear "you missed the mount" message.
+//
+// Prefix-aware (task 1919): the canonical mount is API_PREFIX (/api/bongos) and
+// every LEGACY_API_PREFIXES entry (/api/gds) is a permanent alias — a path already
+// under ANY of them is a genuine miss (no rewrite helps); a mis-prefixed path is
+// steered to the CANONICAL prefix. Sourced from the single api-prefix.js constant
+// so it can't drift from the actual mounts.
+//
+// Pure (no express, no I/O) so it is unit-tested directly (tests/api_path_404.mjs).
+
+const { API_PREFIX, LEGACY_API_PREFIXES } = require('./api-prefix');
+
+const ALL_PREFIXES = [API_PREFIX, ...LEGACY_API_PREFIXES]; // e.g. ['/api/bongos', '/api/gds']
+
+// GDS resource roots a caller commonly hits WITHOUT the /api/<name> prefix. Kept to
+// names that do NOT collide with game/hall/static paths (/, /vendor/*, /builders/*,
+// /downloads/*, /atlas-*, /healthz, /version, world assets).
+const GDS_ROOTS = [
+  'tasks', 'claims', 'me', 'versions', 'inbox', 'blockers', 'sessions',
+  'learnings', 'security', 'memory', 'grade', 'grades', 'cost', 'costs',
+  'leaderboard', 'achievements', 'idea', 'ideas',
+];
+const ROOT_RE = new RegExp('^/(' + GDS_ROOTS.join('|') + ')(/|$)');
+const API_RE = /^\/api(\/|$)/;
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// The bare second segment of each mount (/bongos, /gds), for callers that dropped
+// the /api — e.g. `/bongos/tasks` or `/gds/tasks`.
+const SEGMENTS = ALL_PREFIXES.map((p) => p.replace(/^\/api/, '')); // ['/bongos', '/gds']
+const SEGMENT_RE = new RegExp('^(' + SEGMENTS.map(esc).join('|') + ')(/|$)');
+// A path already correctly under one of the live mounts (canonical or alias).
+const ALREADY_MOUNTED_RE = new RegExp('^(' + ALL_PREFIXES.map(esc).join('|') + ')(/|$)');
+
+// Does this path look like a GDS API call (vs a game/hall/static request)?
+function isApiShapedPath(p) {
+  const s = String(p || '');
+  return API_RE.test(s) || SEGMENT_RE.test(s) || ROOT_RE.test(s);
+}
+
+// The corrected path under the CANONICAL mount, or null when the path is ALREADY
+// under a live mount (canonical or a legacy alias) — a genuine miss (the resource
+// family exists, the specific route does not; no rewrite would help).
+function apiPathHint(p) {
+  const s = String(p || '');
+  if (ALREADY_MOUNTED_RE.test(s)) return null;
+  if (API_RE.test(s)) return API_PREFIX + s.slice(4); // /api/x        → /api/bongos/x
+  if (SEGMENT_RE.test(s)) return '/api' + s;           // /gds/x,/bongos/x → /api/gds/x (valid alias)
+  return API_PREFIX + s;                                // /tasks        → /api/bongos/tasks
+}
+
+// Build the JSON 404 body for an API-shaped miss (used by server.js).
+function apiNotFoundBody(p) {
+  const suggested = apiPathHint(p);
+  const alias = LEGACY_API_PREFIXES.length ? ` (legacy alias ${LEGACY_API_PREFIXES.join(', ')})` : '';
+  return suggested
+    ? { error: 'not_found', message: `No such route. The GDS API is mounted at ${API_PREFIX}${alias} — did you mean ${suggested}? See /docs for the full API reference.`, hint: suggested, docs: '/docs' }
+    : { error: 'not_found', message: `No such GDS API route under ${API_PREFIX}${alias}. See /docs for the full API reference.`, docs: '/docs' };
+}
+
+module.exports = { isApiShapedPath, apiPathHint, apiNotFoundBody, GDS_ROOTS };

package/src/bongos/api-prefix.js

@@ -0,0 +1,38 @@
+'use strict';
+// api-prefix.js — the SINGLE source of truth for the GDS API mount prefix.
+//
+// Introduced in task 1918 (BONGOS-V1) as the "chokepoint" the API surface was
+// missing: the prefix used to be a bare '/api/gds' literal duplicated in ~1,158
+// places. Everything that needs to know the canonical API base — the OpenAPI
+// generator (scripts/gds/gen-api-docs.js), the machine-discovery endpoint, and
+// the served docs site — reads it from here.
+//
+// The URL rename (Part B / B1, task 1919) flipped the canonical here: the API is
+// now served at '/api/bongos', and '/api/gds' stays mounted FOREVER as a silent
+// alias (LEGACY_API_PREFIXES). "Forever" is deliberate — shipped Dev Box desktop
+// binaries, the separately-hosted status-dashboard mirror, and live dev boxes all
+// call '/api/gds' and can't be force-updated. serve-internal.js mounts the router
+// + discovery index at API_PREFIX and every LEGACY_API_PREFIXES entry.
+const API_PREFIX = '/api/bongos';
+
+// Prefixes the server ALSO answers on, for callers pinned to the previous path.
+// Never remove '/api/gds' — the alias is permanent (see above).
+const LEGACY_API_PREFIXES = ['/api/gds'];
+
+// API versioning (BV1 R06 / task 1993 / ADR 0117). The explicit CONTRACT version
+// is a path segment after the prefix: '/api/bongos/v1'. This is distinct from the
+// package semver (OpenAPI info.version). The unversioned API_PREFIX + every
+// LEGACY_API_PREFIXES entry are PERMANENT aliases PINNED TO v1 — an unversioned
+// path never silently jumps a major, so a future /v2 reaches only opted-in
+// callers. Today's surface is v1; when v2 ships it mounts at '/api/bongos/v2' and
+// the aliases stay on v1.
+const API_VERSION = 'v1';
+const VERSIONED_API_PREFIX = `${API_PREFIX}/${API_VERSION}`; // '/api/bongos/v1'
+
+// Every prefix the router mounts on, MOST-SPECIFIC FIRST so the versioned prefix
+// wins over the bare one (Express matches a mount when the path STARTS WITH it —
+// '/api/bongos' is a prefix of '/api/bongos/v1/tasks', so the versioned mount must
+// be registered first or the bare mount would swallow /v1 requests).
+const ALL_API_PREFIXES = [VERSIONED_API_PREFIX, API_PREFIX, ...LEGACY_API_PREFIXES];
+
+module.exports = { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_API_PREFIXES };

package/src/bongos/app-pair.js

@@ -0,0 +1,172 @@
+// src/bongos/app-pair.js — in-memory pairing store for the Dev Box desktop app
+// (#904, ADR 0045).
+//
+// The desktop app needs a browser-clicks-only sign-in (Lars's UI-first rule:
+// no terminal, no paste, no typing codes). GitHub's device flow makes the
+// builder hand-type an 8-char code; the web OAuth flow can't hand a token to a
+// local process (safeReturnTo deliberately rejects loopback targets). So the
+// app pairs against the GDS itself:
+//
+//   1. app   → POST /auth/app-pair/start            → { pair_code, poll_token }
+//   2. app   → opens the browser at /builders/pair?code=<pair_code>
+//   3. human → already signed into the hall (or signs in via the normal web
+//              flow) and clicks ONE Approve button
+//   4. server (at approve, cookie-gated like /auth/cli-token/issue) mints a
+//      source='cli' session and parks it on the pairing entry
+//   5. app   → POST /auth/app-pair/poll { poll_token } → { token } (ONCE)
+//
+// Two credentials with distinct trust:
+//   - pair_code  — short, human-visible, shown in the browser URL. It can only
+//     APPROVE (and only from an authenticated browser cookie session); it can
+//     never read the minted token.
+//   - poll_token — long, secret, never leaves the app↔server channel. It is
+//     the ONLY credential that can collect the minted session token, and the
+//     token is handed over exactly once, then the entry is destroyed.
+//
+// Storage is an in-memory Map, same posture as the GitHub device-flow's
+// pending map in src/bongos/auth.js — single Node process (ADR 0006), short TTL,
+// a restart simply voids in-flight pairings and the app retries. No migration,
+// no new table, nothing durable to leak.
+
+const crypto = require('node:crypto');
+
+// Unambiguous code alphabet (Crockford-ish: no 0/O, 1/I/L, U/V confusion).
+const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTWXYZ23456789';
+const CODE_GROUPS = 2;          // XXXX-XXXX
+const CODE_GROUP_LEN = 4;
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000;   // mirrors the OAuth state cookies
+const DEFAULT_MAX_PENDING = 500;         // memory cap; start() refuses beyond
+const POLL_INTERVAL_S = 5;               // suggested client poll cadence
+
+function randomPairCode() {
+  const groups = [];
+  for (let g = 0; g < CODE_GROUPS; g++) {
+    let s = '';
+    for (let i = 0; i < CODE_GROUP_LEN; i++) {
+      s += CODE_ALPHABET[crypto.randomInt(CODE_ALPHABET.length)];
+    }
+    groups.push(s);
+  }
+  return groups.join('-');
+}
+
+// Normalize what a human/browser hands back: trim, uppercase, drop spaces,
+// tolerate a missing dash.
+function normalizeCode(raw) {
+  if (typeof raw !== 'string') return null;
+  const s = raw.trim().toUpperCase().replace(/[\s-]+/g, '');
+  if (s.length !== CODE_GROUPS * CODE_GROUP_LEN) return null;
+  if (![...s].every((c) => CODE_ALPHABET.includes(c))) return null;
+  return `${s.slice(0, CODE_GROUP_LEN)}-${s.slice(CODE_GROUP_LEN)}`;
+}
+
+// createPairStore({ nowMs, ttlMs, maxPending }) — nowMs injectable for tests.
+function createPairStore(opts = {}) {
+  const nowMs = opts.nowMs || (() => Date.now());
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const maxPending = opts.maxPending ?? DEFAULT_MAX_PENDING;
+
+  const byCode = new Map();   // pair_code  → entry
+  const byPoll = new Map();   // poll_token → entry
+
+  function destroy(entry) {
+    byCode.delete(entry.pairCode);
+    byPoll.delete(entry.pollToken);
+  }
+
+  function expired(entry) {
+    return nowMs() >= entry.expiresAt;
+  }
+
+  // Lazy purge — called on every public op so the maps never accumulate.
+  function purge() {
+    for (const entry of byCode.values()) {
+      if (expired(entry)) destroy(entry);
+    }
+  }
+
+  return {
+    // → { pairCode, pollToken, expiresIn, interval } | { error: 'busy' }
+    start({ deviceName, platform } = {}) {
+      purge();
+      if (byCode.size >= maxPending) return { error: 'busy' };
+      let pairCode = randomPairCode();
+      while (byCode.has(pairCode)) pairCode = randomPairCode(); // vanishing odds
+      const entry = {
+        pairCode,
+        pollToken: crypto.randomBytes(32).toString('hex'),
+        deviceName: String(deviceName || 'Dev Box app').slice(0, 80),
+        platform: String(platform || 'unknown').slice(0, 20),
+        createdAt: nowMs(),
+        expiresAt: nowMs() + ttlMs,
+        status: 'pending',          // pending → approved (→ delivered = gone)
+        grant: null,                // set at approve: { token, builder, expires_at }
+      };
+      byCode.set(entry.pairCode, entry);
+      byPoll.set(entry.pollToken, entry);
+      return {
+        pairCode: entry.pairCode,
+        pollToken: entry.pollToken,
+        expiresIn: Math.floor(ttlMs / 1000),
+        interval: POLL_INTERVAL_S,
+      };
+    },
+
+    // What the approve page shows BEFORE the human clicks. null = unknown/expired
+    // (indistinguishable on purpose — no oracle for code guessing).
+    info(rawCode) {
+      purge();
+      const code = normalizeCode(rawCode);
+      const entry = code ? byCode.get(code) : null;
+      if (!entry || expired(entry)) return null;
+      return {
+        pairCode: entry.pairCode,
+        deviceName: entry.deviceName,
+        platform: entry.platform,
+        createdAt: entry.createdAt,
+        status: entry.status,
+      };
+    },
+
+    // Park the minted grant on a pending entry. The route mints the session
+    // (it holds req.builder); the store only records the handover.
+    // → { ok: true } | { error: 'not_found' | 'already_approved' }
+    approve(rawCode, grant) {
+      purge();
+      const code = normalizeCode(rawCode);
+      const entry = code ? byCode.get(code) : null;
+      if (!entry || expired(entry)) return { error: 'not_found' };
+      if (entry.status !== 'pending') return { error: 'already_approved' };
+      entry.status = 'approved';
+      entry.grant = grant;
+      return { ok: true };
+    },
+
+    // → { status: 'pending', interval }
+    // | { status: 'approved', grant }   (exactly once; entry destroyed)
+    // | { status: 'expired' }           (also for unknown poll tokens — no oracle)
+    poll(pollToken) {
+      purge();
+      const entry = typeof pollToken === 'string' ? byPoll.get(pollToken) : null;
+      if (!entry || expired(entry)) {
+        if (entry) destroy(entry);
+        return { status: 'expired' };
+      }
+      if (entry.status === 'approved') {
+        const grant = entry.grant;
+        destroy(entry); // one-shot delivery
+        return { status: 'approved', grant };
+      }
+      return { status: 'pending', interval: POLL_INTERVAL_S };
+    },
+
+    // test/ops introspection only
+    _size() { return byCode.size; },
+  };
+}
+
+// Singleton the routes use. Tests build their own stores with injected clocks.
+const pairStore = createPairStore();
+
+module.exports = { createPairStore, normalizeCode, pairStore };