@bongos/core 1.19.419 → 1.19.420

package/src/bongos/middleware/rate-limit.js

@@ -1,7 +1,9 @@
 // src/bongos/middleware/rate-limit.js — V3.R34 (#255).
 //
-// Two sliding-window in-memory limiters that protect write methods on
-// /api/gds/*. Read methods (GET, HEAD, OPTIONS) bypass entirely.
+// Four sliding-window in-memory limiters. The first two are the GLOBAL pair and
+// protect write methods on /api/gds/* only — read methods (GET, HEAD, OPTIONS)
+// bypass them entirely; #3 and #4 are mounted per-surface to close exactly that
+// gap where an unauthenticated READ is itself the abuse.
 //
 //   1. Per-IP limiter      — 30 writes / 60s. Anchors on req.ip (which honors
 //                            'trust proxy' in server.js so Cloudflare's
@@ -32,6 +34,22 @@
 //                            server.js sets 'trust proxy', so req.ip is the end
 //                            user, not Cloudflare's single origin IP.
 //
+//   4. Account-existence limiter — 120 reads / 60s per IP, spent from ONE bucket
+//                            by BOTH routes that answer "does this GitHub login
+//                            have an account here?": the onboarding module's
+//                            GET /access-requests/status (the richer
+//                            member|invited|pending|dismissed|none) and core's
+//                            GET /auth/web/admission-status (its boolean twin).
+//                            Task 1003339 / ADR 0209. They are ONE oracle read
+//                            two ways, so they share one budget — give each its
+//                            own and an enumerator just alternates between them
+//                            for double the rate. Both are unauthenticated by
+//                            design (a would-be builder is outside the system),
+//                            so the per-IP budget is the only ceiling there is.
+//                            120/min clears the honest pollers with wide margin —
+//                            the access-pending page polls every 3s (20/min) —
+//                            while capping a scraper at ~2 logins/s.
+//
 // Any limiter tripping → 429 with Retry-After (seconds rounded up to the
 // nearest whole second). Audit middleware still fires on a write 429 — the row
 // in audit_log is forensic value for "who tried too hard." (Reads are never
@@ -54,11 +72,16 @@ const PER_SESSION_WINDOW_MS = 60 * 1000;
 const PER_SESSION_LIMIT     = 60;
 const PUBLIC_READ_WINDOW_MS = 60 * 1000;
 const PUBLIC_READ_LIMIT     = 120;
+const ACCOUNT_EXISTENCE_WINDOW_MS = 60 * 1000;
+const ACCOUNT_EXISTENCE_LIMIT     = 120;
 const SWEEP_MS              = 5 * 60 * 1000;
 
 const ipBuckets         = new Map();
 const sessionBuckets    = new Map();
 const publicReadBuckets = new Map();
+// ONE bucket map for limiter #4 — both account-existence probes key into it, so
+// the budget is genuinely shared rather than merely identically configured.
+const accountExistenceBuckets = new Map();
 
 const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
 // HEAD is metered too: Express runs the GET handler (incl. the DB query) for a
@@ -105,6 +128,10 @@ function sweep() {
     pruneAndCount(arr, now, PUBLIC_READ_WINDOW_MS);
     if (arr.length === 0) publicReadBuckets.delete(k);
   }
+  for (const [k, arr] of accountExistenceBuckets) {
+    pruneAndCount(arr, now, ACCOUNT_EXISTENCE_WINDOW_MS);
+    if (arr.length === 0) accountExistenceBuckets.delete(k);
+  }
 }
 
 // Schedule the sweep. unref() so it doesn't keep the process alive during
@@ -182,9 +209,46 @@ function publicReadRateLimitMiddleware(req, res, next) {
   next();
 }
 
+// perIpSlidingWindow(buckets, opts) — build a per-IP sliding-window middleware
+// over the given bucket map. Exists so a second route can spend from the SAME
+// budget as the first simply by mounting the same returned function; `scope`
+// names that budget in the 429 body + headers so a caller can tell which ceiling
+// it hit. Keyed on req.ip — the same real-client-IP resolution the write limiter
+// uses (Caddy forwards the client IP, server sets 'trust proxy').
+function perIpSlidingWindow(buckets, { limit, windowMs, scope }) {
+  return function slidingWindowRateLimit(req, res, next) {
+    const now = Date.now();
+    const ip = req.ip || req.socket?.remoteAddress || 'unknown';
+    let bucket = buckets.get(ip);
+    if (!bucket) { bucket = []; buckets.set(ip, bucket); }
+    if (pruneAndCount(bucket, now, windowMs) >= limit) {
+      const retryAfter = Math.max(1, Math.ceil((bucket[0] + windowMs - now) / 1000));
+      res.set('Retry-After', String(retryAfter));
+      res.set('X-RateLimit-Scope', scope);
+      res.set('X-RateLimit-Limit', String(limit));
+      res.set('X-RateLimit-Window-Seconds', String(windowMs / 1000));
+      return res.fail('rate_limited', 429, { scope, retry_after_seconds: retryAfter });
+    }
+    bucket.push(now);
+    return next();
+  };
+}
+
+// accountExistenceReadRateLimit — limiter #4 in the header. ONE instance, mounted
+// on both account-existence probes (core /auth/web/admission-status and the
+// onboarding module's /access-requests/status, which reaches it through the
+// doorway). Mounting the same function on both is what makes the budget shared:
+// exhausting it on either route closes the other for the rest of the window.
+const accountExistenceReadRateLimit = perIpSlidingWindow(accountExistenceBuckets, {
+  limit: ACCOUNT_EXISTENCE_LIMIT,
+  windowMs: ACCOUNT_EXISTENCE_WINDOW_MS,
+  scope: 'account-existence',
+});
+
 module.exports = {
   rateLimitMiddleware,
   publicReadRateLimitMiddleware,
+  accountExistenceReadRateLimit,
   // exported for tests + the security-baseline-check script
   PER_IP_WINDOW_MS,
   PER_IP_LIMIT,
@@ -192,4 +256,6 @@ module.exports = {
   PER_SESSION_LIMIT,
   PUBLIC_READ_WINDOW_MS,
   PUBLIC_READ_LIMIT,
+  ACCOUNT_EXISTENCE_WINDOW_MS,
+  ACCOUNT_EXISTENCE_LIMIT,
 };

package/src/bongos/routes/auth.js

@@ -34,6 +34,7 @@ const { reportActivityRollupForShippedTask } = require('../auth-admission.js');
 const db = require('../db');
 const { pairStore } = require('../app-pair');
 const { publicOrigin, parseCookie, validateOrRespond } = require('./_helpers');
+const { accountExistenceReadRateLimit } = require('../middleware/rate-limit');
 const { branding } = require('../../branding');
 const seams = require('../../module-seams');
 // task 1003208: structured logging — was console.*. A core file logs through
@@ -564,23 +565,29 @@ module.exports = function buildAuthRouter() {
   // 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.
+  // unauthenticated caller.
   //
-  // 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.
+  // IT IS NOW THROTTLED (task 1003339 / ADR 0209). It used to say "NOT
+  // throttled" here, and that was true: rateLimitMiddleware returns early for
+  // non-write methods, so GETs bypassed it entirely and the page's 3s poll
+  // bounded the honest client, not an attacker. accountExistenceReadRateLimit
+  // below is the ceiling — 120 reads/60s per IP, and the SAME instance is
+  // mounted on the onboarding module's GET /access-requests/status, which is
+  // this route's strictly richer twin (member|invited|pending|dismissed|none
+  // plus its own `admitted`). One budget across both, because they are one
+  // oracle: hardening either alone would accomplish nothing, and giving each its
+  // own budget would just let an enumerator alternate for double the rate.
+  //
+  // WHAT IS STILL OPEN and is deliberately NOT decided here: whether the answer
+  // itself should collapse, so a caller who is not the subject cannot tell
+  // pending/dismissed/none apart from a bare "not admitted". That changes what a
+  // real invited user sees during onboarding, so it is the owner's call — filed
+  // as a blocker against task 1003339, not settled by a comment in this file.
   //
   // 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) => {
+  router.get('/auth/web/admission-status', accountExistenceReadRateLimit, async (req, res) => {
     const login = typeof req.query.login === 'string' ? req.query.login.slice(0, 100) : '';
     if (!login) return res.json({ admitted: false });
     try {

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.419'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.420'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -131,6 +131,18 @@ module.exports = {
   // The ladder as the canonical 1-based rank → tier map (BV1.R108) — modules
   // derive tier comparisons from this instead of hand-copying the map.
   get RANK_TIER() { return require('./bongos/db-kernel').RANK_TIER; },
+  // accountExistenceReadRateLimit — the SHARED per-IP budget (120 reads/60s)
+  //     spent by every route that answers "does this login have an account
+  //     here?". A kernel trust primitive in the same sense the authz gates are:
+  //     the abuse ceiling on an unauthenticated read. It is one MIDDLEWARE
+  //     INSTANCE, not a factory, on purpose — core's /auth/web/admission-status
+  //     and the onboarding module's richer /access-requests/status are one
+  //     oracle read two ways, so they must spend from one bucket or an
+  //     enumerator alternates between them for double the rate (task 1003339,
+  //     ADR 0209). Vendoring a second copy in a module is the failure this
+  //     export exists to prevent.
+  accountExistenceReadRateLimit: require('./bongos/middleware/rate-limit').accountExistenceReadRateLimit,
+
   // --- per-builder secrets at rest (AES-256-GCM box) — a kernel trust
   //     primitive; the full secretBox object is exposed so a module can call
   //     isConfigured/encrypt/decrypt/provisionMasterKey without reaching core.

package/tests/account_existence_rate_limit.mjs

@@ -0,0 +1,375 @@
+// tests/account_existence_rate_limit.mjs — the account-existence oracle has a
+// ceiling, and it is ONE ceiling (task 1003339, goal 1000045; ADR 0209).
+//
+// The hole this pins shut: two PUBLIC routes answer "does this GitHub login have
+// an account here?" — the onboarding module's GET /access-requests/status (the
+// rich member|invited|pending|dismissed|none) and core's
+// GET /auth/web/admission-status (its boolean twin) — and neither was throttled.
+// The global limiter returns early for non-write methods, so every GET bypassed
+// it. Scripted at line rate, either route turns a list of GitHub usernames into a
+// membership roster: who builds here, and confirmation that a named person is
+// present. That is targeting data, and it is worth having for a phishing run.
+//
+// What is executed here, not asserted about:
+//
+//   1. COUNTING — the first ACCOUNT_EXISTENCE_LIMIT probes from one address pass
+//      and the next is refused, on BOTH routes, over real HTTP through the real
+//      routers.
+//   2. SHARING — the two routes spend from ONE budget. Exhaust it on the rich
+//      route and the boolean twin is closed too, and vice versa. This is the
+//      property that matters most and the easiest one to fake: two limiters
+//      configured 120/60s each look identical in a diff and hand an enumerator
+//      240/min. So it is proved by behaviour AND by object identity (§4).
+//   3. SLIDING — still refused 30s in, open again at 61s. Proved on the real
+//      mounted route by moving Date.now, not by testing a private helper.
+//   4. ISOLATION — the ceiling is per-IP, so one abuser cannot close the door on
+//      everybody else.
+//   5. CHEAPNESS — a refused probe issues no database query. The limiter runs
+//      ahead of the lookups, so the oracle is not also a free amplifier.
+//
+// MUTATION-CHECKED (the tests/own_session_revoke.mjs standard): remove
+// `accountExistenceReadRateLimit` from either route's mount and this file goes
+// red — §1's counting fails for that route and §2's sharing fails in both
+// directions. Replace the shared instance with a per-route copy and §2 fails
+// while §1 still passes, which is exactly the regression worth catching.
+//
+// DB-FREE. The fake pool below is a small in-memory builders/access_requests
+// pair that answers from the statement's OWN shape, so the 200s are real answers
+// and the query counter in §5 counts real intent. Everything above it is real:
+// the real doorway (src/module-api.js — the module gets the limiter through it,
+// which is the point), the real auth.webAdmissionStatus, the real routers, real
+// HTTP with the production 'trust proxy' setting.
+//
+// Run:  node tests/account_existence_rate_limit.mjs
+
+import { strict as assert } from 'node:assert';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// ESM `import`, not createRequire, ON PURPOSE: the knip dead-code ratchet does
+// not credit a CJS export reached through createRequire, so these three would
+// read as unused and regress the baseline. Safe to hoist above the pool pin
+// below — rate-limit.js has no requires of its own — and an ESM import of a CJS
+// module resolves through the same cache, so SHARED_LIMITER is the very object
+// auth.js and the doorway hold (which §4 asserts).
+import {
+  accountExistenceReadRateLimit as SHARED_LIMITER,
+  ACCOUNT_EXISTENCE_LIMIT as LIMIT,
+  ACCOUNT_EXISTENCE_WINDOW_MS as WINDOW_MS,
+} from '../src/bongos/middleware/rate-limit.js';
+
+const require = createRequire(import.meta.url);
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ===========================================================================
+// The in-memory tables + their statement interpreter
+// ===========================================================================
+
+// 'ada' is a member; 'bo' has an invite; 'cy' is still pending; everyone else is
+// a stranger. The 200-level answers below are therefore real route output, which
+// is what makes "the limiter refused before the lookup" (§5) meaningful.
+const builders = new Set(['ada']);
+const accessRequests = [
+  { github_login: 'bo', status: 'invited' },
+  { github_login: 'cy', status: 'pending' },
+  { github_login: 'dez', status: 'dismissed' },
+];
+
+let queries = [];
+const pool = {
+  query: async (text, params = []) => {
+    const sql = String(text).replace(/\s+/g, ' ').trim();
+    queries.push({ sql, params });
+    const login = String(params[0] ?? '').toLowerCase();
+    const req = accessRequests.filter((r) => r.github_login.toLowerCase() === login);
+
+    // db-kernel accessStateByLogin — the three-EXISTS probe behind
+    // auth.webAdmissionStatus. Recognised by its own projection.
+    if (/AS member/.test(sql)) {
+      return { rows: [{
+        member: builders.has(login),
+        invited: req.some((r) => r.status === 'invited'),
+        pending: req.some((r) => r.status === 'pending'),
+      }], rowCount: 1 };
+    }
+    if (/^SELECT 1 FROM builders/.test(sql)) {
+      return builders.has(login) ? { rows: [{ '?column?': 1 }], rowCount: 1 } : { rows: [], rowCount: 0 };
+    }
+    if (/FROM access_requests/.test(sql)) {
+      // The route prefers an 'invited' row, else the most recent.
+      const ordered = [...req].sort((a, b) => Number(b.status === 'invited') - Number(a.status === 'invited'));
+      return ordered.length ? { rows: [{ status: ordered[0].status }], rowCount: 1 } : { rows: [], rowCount: 0 };
+    }
+    throw new Error(`fake pool: unhandled statement — ${sql.slice(0, 90)}`);
+  },
+  on: () => {},
+};
+
+// Pin the fake pool BEFORE anything that reaches for a connection is loaded, so
+// the doorway, db-kernel and the routers all resolve to it and no real pg Pool
+// is ever built.
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = {
+  id: poolPath, filename: poolPath, loaded: true,
+  exports: { pool, instanceDbName: () => 'test' },
+};
+
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const api = require('../src/module-api.js');
+const buildAuthRouter = require('../src/bongos/routes/auth.js');
+const buildAccessRequestsRouter = require('../modules/onboarding/routes/access-requests.js');
+
+const RICH = (login) => `/api/gds/access-requests/status?github_login=${encodeURIComponent(login)}`;
+const BOOL = (login) => `/api/gds/auth/web/admission-status?login=${encodeURIComponent(login)}`;
+
+const authRouter = buildAuthRouter();
+const accessRouter = buildAccessRequestsRouter();
+
+const app = express();
+// Exactly what src/platform-server.js sets, so req.ip resolves from
+// X-Forwarded-For the same way it does behind the real proxy.
+app.set('trust proxy', 1);
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', accessRouter);
+app.use('/api/gds', authRouter);
+
+const server = app.listen(0, '127.0.0.1');
+await new Promise((r) => server.once('listening', r));
+const PORT = server.address().port;
+
+// node:http rather than fetch — §3 moves Date.now, and undici's connection
+// bookkeeping should not be dragged along for the ride.
+function call(path, ip) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      { host: '127.0.0.1', port: PORT, path, method: 'GET', headers: { 'x-forwarded-for': ip } },
+      (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => resolve({
+          status: res.statusCode,
+          headers: res.headers,
+          body: data ? JSON.parse(data) : null,
+        }));
+      }
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// Spend the whole budget for `ip`, asserting every probe was actually served.
+async function exhaust(ip, pathFor = RICH, login = 'ada') {
+  for (let i = 0; i < LIMIT; i++) {
+    const r = await call(pathFor(login), ip);
+    assert.equal(r.status, 200, `probe ${i + 1} of ${LIMIT} should still be inside the budget (got ${r.status})`);
+  }
+}
+
+// ===========================================================================
+// 1 — the ceiling exists, on both routes
+// ===========================================================================
+
+console.log('the ceiling exists — both probes stop answering:');
+
+await t(`the rich probe answers ${LIMIT} times from one address, then refuses`, async () => {
+  const ip = '10.0.0.1';
+  await exhaust(ip);
+  const over = await call(RICH('ada'), ip);
+  assert.equal(over.status, 429, `probe ${LIMIT + 1} must be refused`);
+});
+
+await t('the rich probe\'s refusal is the ADR 0116 envelope, and says which budget ran out', async () => {
+  const ip = '10.0.0.2';
+  await exhaust(ip);
+  const over = await call(RICH('ada'), ip);
+  assert.equal(over.body.error.code, 'rate_limited');
+  assert.equal(over.body.error.details.scope, 'account-existence',
+    'the two routes must name ONE budget — a per-route scope name would mean per-route buckets');
+  assert.equal(over.headers['x-ratelimit-scope'], 'account-existence');
+  assert.equal(over.headers['x-ratelimit-limit'], String(LIMIT));
+  const retry = Number(over.headers['retry-after']);
+  assert.ok(Number.isInteger(retry) && retry >= 1 && retry <= WINDOW_MS / 1000,
+    `Retry-After must be a whole number of seconds inside the window (got ${over.headers['retry-after']})`);
+  assert.equal(over.body.error.details.retry_after_seconds, retry, 'the body agrees with the header');
+});
+
+await t(`the boolean probe answers ${LIMIT} times from one address, then refuses`, async () => {
+  const ip = '10.0.0.3';
+  await exhaust(ip, BOOL);
+  const over = await call(BOOL('ada'), ip);
+  assert.equal(over.status, 429, `probe ${LIMIT + 1} must be refused`);
+  assert.equal(over.body.error.code, 'rate_limited');
+  assert.equal(over.body.error.details.scope, 'account-existence');
+});
+
+await t('under the ceiling both probes still answer truthfully — this is a cap, not a mute', async () => {
+  const ip = '10.0.0.4';
+  const member = await call(RICH('ada'), ip);
+  assert.deepEqual(member.body, { github_login: 'ada', status: 'member', admitted: true });
+  const invited = await call(RICH('bo'), ip);
+  assert.equal(invited.body.status, 'invited');
+  const stranger = await call(RICH('zzz'), ip);
+  assert.equal(stranger.body.status, 'none');
+  const bool = await call(BOOL('ada'), ip);
+  assert.deepEqual(bool.body, { admitted: true });
+  assert.equal((await call(BOOL('zzz'), ip)).body.admitted, false);
+});
+
+// ===========================================================================
+// 2 — ONE budget, not two. The property a copy-pasted limiter would lose.
+// ===========================================================================
+
+console.log('\none oracle, one budget — the routes cannot be alternated for double the rate:');
+
+await t('spending the budget on the rich probe closes the boolean twin as well', async () => {
+  const ip = '10.0.0.5';
+  await exhaust(ip, RICH);
+  const twin = await call(BOOL('ada'), ip);
+  assert.equal(twin.status, 429,
+    'the twin answers the same question — two separate 120/60s budgets would hand an enumerator 240/min');
+  assert.equal(twin.body.error.details.scope, 'account-existence');
+});
+
+await t('and in the other direction — spending it on the boolean twin closes the rich probe', async () => {
+  const ip = '10.0.0.6';
+  await exhaust(ip, BOOL);
+  const rich = await call(RICH('ada'), ip);
+  assert.equal(rich.status, 429);
+});
+
+await t('a budget spent half on each route still totals one budget', async () => {
+  const ip = '10.0.0.7';
+  for (let i = 0; i < LIMIT; i++) {
+    const r = await call(i % 2 === 0 ? RICH('ada') : BOOL('ada'), ip);
+    assert.equal(r.status, 200, `alternating probe ${i + 1} should still be inside the shared budget`);
+  }
+  assert.equal((await call(RICH('ada'), ip)).status, 429, 'alternating must not buy a single extra probe');
+  assert.equal((await call(BOOL('ada'), ip)).status, 429);
+});
+
+// ===========================================================================
+// 3 — the window slides, so the cap is a cap and not a permanent ban
+// ===========================================================================
+
+console.log('\nthe window slides — an exhausted address recovers, and not a moment early:');
+
+await t(`still refused part-way through the window, open again after ${WINDOW_MS / 1000}s`, async () => {
+  const ip = '10.0.0.8';
+  const realNow = Date.now;
+  try {
+    await exhaust(ip);
+    assert.equal((await call(RICH('ada'), ip)).status, 429, 'exhausted to begin with');
+
+    // Move the clock, not the limiter: this is the route that ships, with its
+    // real 60s window, being asked again later.
+    const t0 = realNow();
+    Date.now = () => t0 + WINDOW_MS / 2;
+    assert.equal((await call(RICH('ada'), ip)).status, 429,
+      'half a window later the timestamps are still inside it — a fixed-bucket reset would wrongly open here');
+
+    Date.now = () => t0 + WINDOW_MS + 1000;
+    const after = await call(RICH('ada'), ip);
+    assert.equal(after.status, 200, 'once the whole window has passed the budget is back');
+    assert.equal(after.body.status, 'member', 'and it is serving real answers again, not a cached 200');
+  } finally {
+    Date.now = realNow;
+  }
+});
+
+// ===========================================================================
+// 4 — per-IP, and structurally shared
+// ===========================================================================
+
+console.log('\nthe ceiling is per-address, and the sharing is structural:');
+
+await t('one exhausted address does not close the door on anybody else', async () => {
+  const noisy = '10.0.0.9';
+  const bystander = '10.0.0.10';
+  await exhaust(noisy);
+  assert.equal((await call(RICH('ada'), noisy)).status, 429);
+  const other = await call(RICH('ada'), bystander);
+  assert.equal(other.status, 200, 'a per-IP cap must not degenerate into a global kill switch');
+  assert.equal((await call(BOOL('ada'), bystander)).status, 200);
+});
+
+await t('both routes mount the very same middleware INSTANCE — sharing that cannot drift', () => {
+  const shared = SHARED_LIMITER;
+  assert.equal(typeof shared, 'function');
+  assert.equal(require('../src/bongos/middleware/rate-limit.js').accountExistenceReadRateLimit, shared,
+    'the ESM and CJS views of the middleware must be the same object, or this whole test proves nothing');
+  assert.equal(api.accountExistenceReadRateLimit, shared,
+    'the doorway must hand modules the same instance core uses, not a fresh one');
+
+  const handlers = (router, path) => {
+    const layer = router.stack.find((l) => l.route && l.route.path === path && l.route.methods.get);
+    assert.ok(layer, `${path} must be a declared GET route`);
+    return layer.route.stack.map((s) => s.handle);
+  };
+  assert.ok(handlers(accessRouter, '/access-requests/status').includes(shared),
+    'the onboarding probe must mount the shared limiter');
+  assert.ok(handlers(authRouter, '/auth/web/admission-status').includes(shared),
+    'the core probe must mount the shared limiter');
+});
+
+await t('neither route vendors its own sliding window — the copy-paste regression stays out', () => {
+  for (const rel of ['modules/onboarding/routes/access-requests.js', 'src/bongos/routes/auth.js']) {
+    const src = readFileSync(join(ROOT, rel), 'utf8');
+    assert.ok(!/RATE_(WINDOW|LIMIT)|readRateLimit\s*=|new Map\(\); \/\/ ip/.test(src),
+      `${rel} must reach the shared limiter, never vendor a second one`);
+  }
+  const onboarding = readFileSync(join(ROOT, 'modules/onboarding/routes/access-requests.js'), 'utf8');
+  assert.match(onboarding, /accountExistenceReadRateLimit\s*\}?\s*=\s*api/,
+    'the module reaches it through the published doorway (ADR 0083), not a deep core require');
+});
+
+// ===========================================================================
+// 5 — a refused probe is cheap, so the oracle is not also an amplifier
+// ===========================================================================
+
+console.log('\na refused probe costs nothing:');
+
+await t('the limiter runs ahead of the lookups — a 429 issues no query', async () => {
+  const ip = '10.0.0.11';
+  await exhaust(ip);
+  queries = [];
+  assert.equal((await call(RICH('ada'), ip)).status, 429);
+  assert.equal((await call(BOOL('ada'), ip)).status, 429);
+  assert.deepEqual(queries, [], 'a refused probe must not reach the database at all');
+});
+
+await t('an allowed probe DOES query — so the previous test is not vacuous', async () => {
+  queries = [];
+  await call(RICH('ada'), '10.0.0.12');
+  assert.ok(queries.length > 0, 'the 200 path really does hit the pool');
+});
+
+// ===========================================================================
+// 6 — the budget is sized for the honest callers it has to clear
+// ===========================================================================
+
+await t('the ceiling clears both honest pollers with room to spare', () => {
+  // renderAccessPendingPage polls the boolean probe every 3s; `bongos login`
+  // polls the rich one every 5s. A future tightening that cannot fit both,
+  // several times over, would break sign-in for a shared/NAT address.
+  const honestPerMinute = 60 / 3 + 60 / 5;
+  assert.ok(LIMIT >= honestPerMinute * 3,
+    `${LIMIT}/min must leave real margin over the ${honestPerMinute}/min the pollers need`);
+});
+
+// ===========================================================================
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/module_api.mjs

@@ -24,6 +24,7 @@ const PUBLISHED_SURFACE = [
   'requirePermission', // BV1.R105: the authority-atom gate module routes migrate onto (1.19.0; ADR 0151)
   'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
   'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
+  'accountExistenceReadRateLimit', // task 1003339 (ADR 0209): the shared per-IP budget both account-existence probes spend from — one instance, not a factory, so the budget is genuinely shared
   'routeRankCheck', 'permissionPathCheck', // BV1.R73: kernel trust classifiers (1.6.0)
   'repoInfo', 'moduleScopeMap', 'pathMatch', // BV1.R86: kernel repo-identity + scope-wall + touches-overlap for the carved lifecycle (1.12.0)
   'goalScopeCheck', // BV1.R60: kernel scope wall for the goal-authored-task create gate (1.13.0; ADR 0086 §3)

package/tests/onboard.mjs

@@ -31,6 +31,62 @@ test('onboardPlan is the canonical sequence: name+address first, the builders ha
   assert.ok(keys.indexOf('device-flow') < keys.indexOf('first-sign-in'), 'checkbox prompted before sign-in');
 });
 
+test('the OPTIONAL project-detail step sits in the canonical sequence, and optional means skippable (task 1002334)', () => {
+  const plan = ob.onboardPlan();
+  const keys = plan.map((s) => s.key);
+  const step = plan.find((s) => s.key === 'project-detail');
+  assert.ok(step, 'the interview is a real step in the sequence, not a wizard-only flourish');
+  assert.equal(keys.indexOf('project-detail'), keys.indexOf('name-address') + 1,
+    'it follows the name interview — the project is described before its repo and address are decided');
+  assert.equal(step.optional, true, 'the flag is what tells a form it may be walked past');
+  assert.equal(step.kind, 'auto',
+    "'auto' like name-address: the FORM collects it, so a done panel of outstanding human steps must not list it");
+  // one optional step keeps the flag meaningful; a second would need its own rule
+  assert.deepEqual(plan.filter((s) => s.optional).map((s) => s.key), ['project-detail']);
+  // and the adopt branch carries it identically — the sequence branches only at scaffold
+  assert.ok(ob.onboardPlan('adopt').some((s) => s.key === 'project-detail' && s.optional === true));
+});
+
+test('every form OFFERS the optional step and names what skipping costs — skill / CLI / wizard / route (task 1002334)', () => {
+  const { readFileSync } = require('node:fs');
+  const path = require('node:path');
+  const read = (rel) => readFileSync(path.join(import.meta.dirname, '..', rel), 'utf8');
+
+  // the skill — the source of truth for the sequence
+  const skill = read('.claude/skills/new-project/SKILL.md');
+  assert.match(skill, /OPTIONAL/, 'the canonical runbook marks the step optional');
+  assert.match(skill, /team_shape/, 'and names the answers that ride the request');
+  assert.match(skill, /dark matter/i, 'and states what skipping costs');
+
+  // the CLI form
+  const cli = read('scripts/gds/onboard.js');
+  assert.match(cli, /Press Enter to skip/, 'the terminal form offers the skip in the prompt itself');
+  assert.match(cli, /off the public map/, 'and says what a missing description means');
+
+  // the web form
+  const hub = read('public-landing/projects.html');
+  assert.match(hub, /id="panel-detail"/, 'the wizard ships the panel');
+  assert.match(hub, /id="skipDetail"/, 'with a skip control of its own');
+
+  // the route that receives it
+  const route = read('modules/provisioning/routes/provisioning.js');
+  assert.match(route, /description: \{ type: 'string', maxLength: provisioning\.DESCRIPTION_MAX \}/,
+    'the create route accepts the description');
+  assert.match(route, /\/provisioning\/instances\/:id\/detail/,
+    'and there is a way back, or "optional" would mean permanently unpublishable');
+});
+
+test('the answers the CLI collects are the same body the web form files (buildProjectDetail)', () => {
+  assert.deepEqual(ob.buildProjectDetail({ description: '  a   b ', teamShape: 'Community' }),
+    { description: 'a b', detail: { team_shape: 'community' } });
+  // a skip files nothing — absent means skipped, and an empty string would read
+  // to the publish gate as an answered-but-blank description
+  assert.deepEqual(ob.buildProjectDetail({}), {});
+  assert.deepEqual(ob.buildProjectDetail({ description: '   ', teamShape: '' }), {});
+  // an off-vocabulary answer is dropped, never guessed into a recommendation
+  assert.deepEqual(ob.buildProjectDetail({ teamShape: 'a big guild' }), {});
+});
+
 test('onboardPlan(adopt): same sequence + human steps, but the scaffold-leg labels branch (task 2046)', () => {
   const green = ob.onboardPlan();
   const adopt = ob.onboardPlan('adopt');