@bongos/core 1.19.1016 → 1.19.1018

package/tests/community_search_route.mjs

@@ -0,0 +1,385 @@
+// tests/community_search_route.mjs
+//
+// Guards GET /community/search — the PUBLIC builder search (D4,
+// docs/specs/bongos-v1-community-tab.md; task 1002979). DB-free: a fake pool
+// asserts the REAL query text literally contains the shared predicates
+// (accountVisibleSql('pa') / rollupVisibleSql('pa2'), read from
+// account-visibility.js — never re-implemented), so deleting either predicate
+// from builder-search.js fails THIS test, not just the separate structural
+// guard. The fake's own row-matching (which rows pass) is then a fixture
+// simulation layered on top, applying the same JS-twin predicates to decide
+// what the query WOULD return — it is not, on its own, proof of the SQL, and
+// isn't presented as such; the predicate-presence assertions above are what
+// actually pins the SQL.
+//
+// What this pins, in order:
+//   1. the pure helpers (clampLimit/clampOffset/escapeLikePrefix) — no DB.
+//   2. the D4 matrix, end to end through the real router + real domain fn:
+//      - a hide_stats account is findable BY NAME (name-only search).
+//      - the SAME account drops out of a DISCIPLINE-filtered search (a
+//        discipline is rollup-derived, and hide_stats suppresses the rollup).
+//      - private and provisional accounts never appear, filtered or not.
+//      - a plain active+public account is findable by name and by its real
+//        discipline, and absent under a discipline it does not hold.
+//   3. input validation (400 on missing/too-short/oversized q, oversized
+//      discipline), the 500 path, the rate limiter, and the response shape
+//      (github_id never crosses, MAX_OFFSET clamp echoed in `page`).
+//
+// Run:  node tests/community_search_route.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.error(`  FAIL ${name}\n       ${e.message}`); }
+}
+
+// ---- pure helpers ----------------------------------------------------------
+
+const builderSearch = require('../modules/platform-identity/builder-search.js');
+
+await t('clampLimit: default, clamp to MAX_LIMIT, ignore garbage', () => {
+  assert.equal(builderSearch.clampLimit(undefined), builderSearch.DEFAULT_LIMIT);
+  assert.equal(builderSearch.clampLimit('not a number'), builderSearch.DEFAULT_LIMIT);
+  assert.equal(builderSearch.clampLimit(0), builderSearch.DEFAULT_LIMIT);
+  assert.equal(builderSearch.clampLimit(-5), builderSearch.DEFAULT_LIMIT);
+  assert.equal(builderSearch.clampLimit(5), 5);
+  assert.equal(builderSearch.clampLimit(9999), builderSearch.MAX_LIMIT);
+});
+
+await t('clampOffset: default 0, ignore negatives/garbage', () => {
+  assert.equal(builderSearch.clampOffset(undefined), 0);
+  assert.equal(builderSearch.clampOffset(-1), 0);
+  assert.equal(builderSearch.clampOffset('nope'), 0);
+  assert.equal(builderSearch.clampOffset(40), 40);
+});
+
+await t('escapeLikePrefix: escapes %, _ and backslash so a query cannot widen its own prefix', () => {
+  assert.equal(builderSearch.escapeLikePrefix('50%'), '50\\%');
+  assert.equal(builderSearch.escapeLikePrefix('a_b'), 'a\\_b');
+  assert.equal(builderSearch.escapeLikePrefix('a\\b'), 'a\\\\b');
+  assert.equal(builderSearch.escapeLikePrefix('plain'), 'plain');
+});
+
+await t('clampOffset: capped at MAX_OFFSET (deep pagination on a public route is a free scan-and-discard knob)', () => {
+  assert.equal(builderSearch.clampOffset(builderSearch.MAX_OFFSET), builderSearch.MAX_OFFSET);
+  assert.equal(builderSearch.clampOffset(builderSearch.MAX_OFFSET + 1), builderSearch.MAX_OFFSET);
+  assert.equal(builderSearch.clampOffset(999999999), builderSearch.MAX_OFFSET);
+});
+
+await t('the fuzzy trigram leg case-folds BOTH sides (a bug class: pg_trgm % is case-sensitive, unlike ILIKE)', () => {
+  // Static, source-level pin — the fake pool below cannot reproduce Postgres's
+  // real case sensitivity, so this is the guard that actually catches a
+  // regression to the raw (unlowered) form the bug report named.
+  const fs = require('fs');
+  const src = fs.readFileSync(require.resolve('../modules/platform-identity/builder-search.js'), 'utf8');
+  assert.match(src, /lower\(pa\.handle\) % lower\(\$1\)/, 'the handle fuzzy leg must compare lower() on both sides');
+  assert.match(src, /lower\(pa\.display_name\) % lower\(\$1\)/, 'the display_name fuzzy leg must compare lower() on both sides');
+  assert.ok(!src.includes('pa.handle % $1'), 'the raw (unlowered) form must not reappear');
+  assert.ok(!src.includes('pa.display_name % $1'), 'the raw (unlowered) form must not reappear');
+});
+
+// ---- fake engine ------------------------------------------------------------
+//
+// Reads the SAME predicates the module reads — imported from
+// account-visibility.js, never restated — so this test cannot pass by
+// agreeing with a hand-rolled copy of the rule under proof.
+const {
+  isAccountVisible, isRollupVisible, accountVisibleSql, rollupVisibleSql,
+} = require('../modules/platform-identity/account-visibility.js');
+
+const ACCEPTED_AT = '2026-08-29T00:00:00.000Z';
+
+// One row per matrix cell D4 names, plus a plain control.
+const ACCOUNTS = [
+  // active + public + NOT hidden — the plain control.
+  { github_id: '100', handle: 'plain-vis', github_login: 'plainvis', display_name: 'Plain Visible',
+    avatar_url: null, profile_state: 'active', terms_accepted_at: ACCEPTED_AT, account_visibility: 'public', hide_stats: false,
+    disciplines: ['engineer'] },
+  // active + public + HIDDEN — findable by name, not by discipline.
+  { github_id: '101', handle: 'hidden-builder', github_login: 'hiddenbuilder', display_name: 'Hidden Builder',
+    avatar_url: null, profile_state: 'active', terms_accepted_at: ACCEPTED_AT, account_visibility: 'public', hide_stats: true,
+    disciplines: ['artist'] },
+  // active + PRIVATE — absent entirely, findable or not.
+  { github_id: '102', handle: 'private-builder', github_login: 'privatebuilder', display_name: 'Private Builder',
+    avatar_url: null, profile_state: 'active', terms_accepted_at: ACCEPTED_AT, account_visibility: 'private', hide_stats: false,
+    disciplines: ['engineer'] },
+  // PROVISIONAL — absent entirely.
+  { github_id: '103', handle: 'provisional-builder', github_login: 'provbuilder', display_name: 'Provisional Builder',
+    avatar_url: null, profile_state: 'provisional', terms_accepted_at: null, account_visibility: 'public', hide_stats: false,
+    disciplines: ['engineer'] },
+  // active + public + NOT hidden, but 'octocat' sits mid-handle — a query for
+  // it is NOT a prefix match, so this fixture exercises the FUZZY (`%`) leg
+  // specifically, not the LIKE prefix leg.
+  { github_id: '104', handle: 'jax-octocat', github_login: 'jaxoctocat', display_name: 'Jax Octocat',
+    avatar_url: null, profile_state: 'active', terms_accepted_at: ACCEPTED_AT, account_visibility: 'public', hide_stats: false,
+    disciplines: ['ui'] },
+];
+
+const engine = {
+  calls: [],
+  query: async (text, params = []) => {
+    const sql = String(text);
+    engine.calls.push({ sql, params });
+    if (engine.throwOnQuery) throw engine.throwOnQuery;
+    assert.match(sql, /WITH matches AS/, 'the query shape moved — update this fake alongside it');
+    assert.match(sql, /platform_identity_builder_project_activity/, 'the discipline CTE moved — update this fake alongside it');
+    // THE load-bearing assertions (the code-review finding this test now
+    // closes): the REAL statement text must literally contain the shared
+    // predicates, not merely SOME predicate — deleting accountVisibleSql from
+    // the 'matches' CTE, or rollupVisibleSql from the 'disc' CTE, fails HERE,
+    // independent of the fixture simulation below and independent of
+    // tests/effective_visibility_predicate.mjs's function-body-level check.
+    assert.ok(sql.includes(accountVisibleSql('pa')),
+      "the 'matches' CTE must join accountVisibleSql('pa') — the NAME-match existence floor");
+    assert.ok(sql.includes(rollupVisibleSql('pa2')),
+      "the 'disc' CTE must join rollupVisibleSql('pa2') — the DISCIPLINE-match rollup floor");
+
+    const [rawQ, likePattern, discipline, limit, offset] = params;
+    const q = String(rawQ || '').toLowerCase();
+    const like = String(likePattern || '').replace(/\\(.)/g, '$1').replace(/%$/, '').toLowerCase();
+
+    // The NAME predicate: real accountVisibleSql via its JS twin, applied to
+    // the fixture — never a hand-rolled restatement.
+    let rows = ACCOUNTS.filter(isAccountVisible).filter((a) => {
+      const handle = a.handle.toLowerCase();
+      const name = (a.display_name || '').toLowerCase();
+      return handle.startsWith(like) || name.startsWith(like) || handle.includes(q) || name.includes(q);
+    });
+
+    // The DISCIPLINE predicate: rollup-derived, so it floors on isRollupVisible
+    // (existence AND NOT hidden) exactly as the disc CTE's EXISTS clause does.
+    const disciplinesFor = (a) => (isRollupVisible(a) ? a.disciplines : null);
+
+    if (discipline) {
+      rows = rows.filter((a) => {
+        const d = disciplinesFor(a);
+        return Array.isArray(d) && d.includes(discipline);
+      });
+    }
+
+    const shaped = rows
+      .sort((a, b) => (a.handle.toLowerCase() === q ? -1 : b.handle.toLowerCase() === q ? 1 : 0))
+      .slice(offset, offset + limit)
+      .map((a) => ({
+        handle: a.handle,
+        github_login: a.github_login,
+        display_name: a.display_name,
+        avatar_url: a.avatar_url,
+        disciplines: disciplinesFor(a),
+      }));
+    return { rows: shaped };
+  },
+};
+
+// Pin the module doorway (ADR 0083) BEFORE the route loads, so its pool is the
+// fake engine above and its auth-adjacent exports satisfy the router factory.
+const moduleApiPath = require.resolve('../src/module-api.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: {
+    pool: engine,
+    corsPublicGet: () => (_req, _res, next) => next(),
+    logger: () => ({ error: () => {}, info: () => {}, warn: () => {} }),
+  },
+};
+
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildCommunitySearchRoutes = require('../modules/platform-identity/routes/community-search.js');
+
+function buildApp() {
+  const app = express();
+  app.use(attachFail);
+  app.use('/api/bongos', buildCommunitySearchRoutes());
+  return app;
+}
+
+function listen(app) {
+  return new Promise((resolve) => {
+    const server = app.listen(0, '127.0.0.1', () => resolve({ server, port: server.address().port }));
+  });
+}
+
+function get(port, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, method: 'GET', path }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null; try { json = JSON.parse(text); } catch (_) {}
+        resolve({ status: res.statusCode, json, text, headers: res.headers });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+const { server, port } = await listen(buildApp());
+
+// ---- D4 matrix, end to end --------------------------------------------------
+
+await t('name-only search finds the plain visible account', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=plain-vis');
+  assert.equal(r.status, 200);
+  const logins = r.json.results.map((x) => x.github_login);
+  assert.ok(logins.includes('plainvis'), 'the plain control must be found');
+});
+
+await t('a hide_stats account IS findable by NAME (D4: hiding removes the rollup, not the page)', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=hidden-builder');
+  assert.equal(r.status, 200);
+  const hit = r.json.results.find((x) => x.github_login === 'hiddenbuilder');
+  assert.ok(hit, 'the hidden account must still be found by name');
+  assert.equal(hit.disciplines, null, 'but its disciplines never attach — the rollup stays suppressed');
+});
+
+await t('the SAME hide_stats account drops out of a DISCIPLINE-filtered search', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=hidden-builder&discipline=artist');
+  assert.equal(r.status, 200);
+  const hit = r.json.results.find((x) => x.github_login === 'hiddenbuilder');
+  assert.ok(!hit, 'a discipline filter must exclude the hidden account even though it genuinely holds that discipline');
+});
+
+await t('a private account never appears — by name or by its real discipline', async () => {
+  const byName = await get(port, '/api/bongos/community/search?q=private-builder');
+  assert.ok(!byName.json.results.some((x) => x.github_login === 'privatebuilder'));
+  const byDiscipline = await get(port, '/api/bongos/community/search?q=private&discipline=engineer');
+  assert.ok(!byDiscipline.json.results.some((x) => x.github_login === 'privatebuilder'));
+});
+
+await t('a provisional account never appears', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=provisional-builder');
+  assert.ok(!r.json.results.some((x) => x.github_login === 'provbuilder'));
+});
+
+await t('a case-differing, NON-PREFIX query hits the fuzzy leg (not just the LIKE prefix leg)', async () => {
+  // 'OCTOCAT' is upper-case and is NOT a prefix of 'jax-octocat' — only the
+  // trigram `%` leg (never the prefix LIKE leg) can find it.
+  const r = await get(port, '/api/bongos/community/search?q=OCTOCAT');
+  assert.equal(r.status, 200);
+  const hit = r.json.results.find((x) => x.github_login === 'jaxoctocat');
+  assert.ok(hit, 'a case-differing, non-prefix query must still find it via the fuzzy leg');
+});
+
+await t('the plain visible account IS found under its real discipline, and ABSENT under another', async () => {
+  const hit = await get(port, '/api/bongos/community/search?q=plain-vis&discipline=engineer');
+  assert.ok(hit.json.results.some((x) => x.github_login === 'plainvis'), 'engineer is its real discipline');
+  const miss = await get(port, '/api/bongos/community/search?q=plain-vis&discipline=artist');
+  assert.ok(!miss.json.results.some((x) => x.github_login === 'plainvis'), 'artist is not its discipline');
+});
+
+await t('github_id never crosses the wire', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=plain-vis');
+  assert.ok(!r.text.includes('github_id'), 'the internal join key must not appear in the response');
+  assert.ok(!r.text.includes('"100"') && !r.text.includes('"101"'));
+});
+
+// ---- validation --------------------------------------------------------------
+
+await t('missing q → 400 bad_request', async () => {
+  const r = await get(port, '/api/bongos/community/search');
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'bad_request');
+});
+
+await t('blank q → 400 bad_request', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=%20%20');
+  assert.equal(r.status, 400);
+});
+
+await t('too-short q → 400 query_too_short', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=a');
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'query_too_short');
+});
+
+await t('oversized q → 400 query_too_long', async () => {
+  const long = 'a'.repeat(builderSearch.MAX_QUERY_CHARS + 1);
+  const r = await get(port, `/api/bongos/community/search?q=${long}`);
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'query_too_long');
+});
+
+await t('oversized discipline → 400 discipline_too_long', async () => {
+  const long = 'a'.repeat(builderSearch.MAX_DISCIPLINE_CHARS + 1);
+  const r = await get(port, `/api/bongos/community/search?q=plain&discipline=${long}`);
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'discipline_too_long');
+});
+
+await t('response is Cache-Control: no-store (hide must beat the cache, ADR 0171 D5)', async () => {
+  const r = await get(port, '/api/bongos/community/search?q=plain-vis');
+  assert.equal(r.headers['cache-control'], 'no-store');
+});
+
+await t('page.offset echoes the MAX_OFFSET clamp through the real route', async () => {
+  const r = await get(port, `/api/bongos/community/search?q=plain-vis&offset=${builderSearch.MAX_OFFSET + 5000}`);
+  assert.equal(r.status, 200);
+  assert.equal(r.json.page.offset, builderSearch.MAX_OFFSET, 'the route must echo the CLAMPED offset, not the raw query param');
+});
+
+await t('a query engine failure → 500 search_failed (never a leaked stack/500 HTML page)', async () => {
+  engine.throwOnQuery = new Error('DO-NOT-LEAK-connection string or stack detail');
+  try {
+    const r = await get(port, '/api/bongos/community/search?q=plain-vis');
+    assert.equal(r.status, 500);
+    assert.equal(r.json.error.code, 'search_failed');
+    assert.ok(!r.text.includes('DO-NOT-LEAK'), 'the raw error message must not reach the response body');
+  } finally {
+    engine.throwOnQuery = null;
+  }
+});
+
+// ---- rate limit -------------------------------------------------------------
+
+await t('searchReadRateLimit: allows up to the cap, then 429s with Retry-After', () => {
+  const { searchReadRateLimit, READ_RATE_LIMIT } = buildCommunitySearchRoutes._internals;
+  const mkRes = () => {
+    const r = { _status: 200, _json: null, _headers: {} };
+    r.set = (k, v) => { r._headers[k] = v; return r; };
+    r.status = (s) => { r._status = s; return r; };
+    r.json = (j) => { r._json = j; return r; };
+    attachFail({}, r, () => {}); // installs res.fail() as the router does
+    return r;
+  };
+  const req = { ip: '203.0.113.77' }; // a unique test IP so the module Map bucket is clean
+  let allowed = 0;
+  for (let i = 0; i < READ_RATE_LIMIT; i++) {
+    const res = mkRes();
+    let nexted = false;
+    searchReadRateLimit(req, res, () => { nexted = true; });
+    if (nexted) allowed++;
+  }
+  assert.equal(allowed, READ_RATE_LIMIT, 'every call up to the cap must pass through');
+  const res = mkRes();
+  let nexted = false;
+  searchReadRateLimit(req, res, () => { nexted = true; });
+  assert.equal(nexted, false, 'the over-cap call must NOT call next()');
+  assert.equal(res._status, 429);
+  assert.equal(res._json.error.code, 'rate_limited');
+  assert.ok(res._headers['Retry-After'], 'a Retry-After header is set');
+});
+
+await t('searchReadRateLimit keys on the request IP only — one caller cannot throttle another', () => {
+  const { searchReadRateLimit, READ_RATE_LIMIT } = buildCommunitySearchRoutes._internals;
+  const mkRes = () => ({ set() { return this; }, status() { return this; }, json() { return this; } });
+  const reqA = { ip: '203.0.113.78' };
+  for (let i = 0; i < READ_RATE_LIMIT; i++) searchReadRateLimit(reqA, mkRes(), () => {});
+  let nexted = false;
+  searchReadRateLimit({ ip: '203.0.113.79' }, mkRes(), () => { nexted = true; });
+  assert.equal(nexted, true, 'a different IP is not affected by another IP hitting the cap');
+});
+
+server.close();
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/effective_visibility_predicate.mjs

@@ -79,6 +79,7 @@ import {
   isRecruiterDiscoverable,
   recruiterReachSql,
   scoutingListableSql,
+  scoutingNameOnlySql,
   recruiterSliverVisibleSql,
   isRecruiterSliverVisible,
 } from '../modules/platform-identity/account-visibility.js';
@@ -353,8 +354,11 @@ function accountStatements(code) {
  * That is a decision recorded in the owner file and asserted above — not a
  * reader quietly dropping a term, which is what this regex would otherwise let
  * through unnoticed.
+ * scoutingNameOnlySql (task 1002291) is the directory's second tier: it floors on
+ * existence like every public answer, but it admits HIDDEN accounts, so it is
+ * pinned below to one reader that selects identity columns and nothing else.
  */
-const ADOPTS = /\b(?:accountVisibleSql|accountActiveSql|rollupVisibleSql|scoutingListableSql|recruiterSliverVisibleSql|isAccountVisible|isAccountActive|isRollupVisible|isRecruiterSliverVisible)\s*\(/;
+const ADOPTS = /\b(?:accountVisibleSql|accountActiveSql|rollupVisibleSql|scoutingListableSql|scoutingNameOnlySql|recruiterSliverVisibleSql|isAccountVisible|isAccountActive|isRollupVisible|isRecruiterSliverVisible)\s*\(/;
 
 // ===========================================================================
 // Self-tests — the machinery is the guard, so it gets proved too.
@@ -458,12 +462,36 @@ t('scoutingListableSql is COMPOSED from the rollup AND the reach halves (task 10
     + 'leaderboards join rollupVisibleSql and the opt-out must not empty them');
 });
 
+t('scoutingNameOnlySql is the directory\'s SECOND tier: existence AND hidden AND reach (task 1002291)', () => {
+  // Privacy spec D2, the "active · public · hide_stats" row's recruiter column:
+  // "listed name-only (if not opted out)". Hide decides the SHAPE of a directory
+  // row, the reach axis decides whether there is a row at all.
+  for (const alias of ['pa', undefined]) {
+    const tier = scoutingNameOnlySql(alias);
+    assert.ok(tier.includes(accountVisibleSql(alias)),
+      'it floors on EXISTENCE like every public read — a private account is never listed, not even by name');
+    assert.ok(tier.includes(recruiterReachSql(alias)),
+      'and on reach: opting out removes a hidden builder from the directory too');
+    assert.match(tier, new RegExp(`AND ${alias ? `${alias}\\.` : ''}hide_stats\\)`),
+      'and admits exactly the HIDDEN accounts — the ones the ranked tier leaves out');
+    assert.doesNotMatch(tier, /NOT (?:\w+\.)?hide_stats/, 'never the unhidden ones, or a builder would be listed twice');
+  }
+  // The two tiers PARTITION the reachable, visible accounts: they differ in the
+  // hide term and in nothing else, so no builder can fall between them or sit
+  // in both.
+  const ranked = scoutingListableSql('pa').replace('AND NOT pa.hide_stats)', 'AND <HIDE>)');
+  const named = scoutingNameOnlySql('pa').replace('AND pa.hide_stats)', 'AND <HIDE>)');
+  assert.ok(ranked.includes('<HIDE>') && named.includes('<HIDE>'), 'both tiers carry the hide term where it is expected');
+  assert.equal(named, ranked, 'the name-only tier is the ranked predicate with the hide term flipped — nothing more');
+});
+
 t('the alias is the one interpolated thing, and every builder refuses a non-identifier', () => {
   const inject = "pa; DROP TABLE platform_identity_accounts --";
   assert.throws(() => accountVisibleSql(inject), /bare SQL identifier/);
   assert.throws(() => rollupVisibleSql(inject), /bare SQL identifier/);
   assert.throws(() => recruiterReachSql(inject), /bare SQL identifier/);
   assert.throws(() => scoutingListableSql(inject), /bare SQL identifier/);
+  assert.throws(() => scoutingNameOnlySql(inject), /bare SQL identifier/);
 });
 
 t('the JS ports answer exactly what the SQL asks, row for row', () => {
@@ -697,6 +725,26 @@ t('the EXISTENCE-LESS predicate has exactly one reader, and it is the sliver (ta
     'the pre-accept predicate is the recruiting sliver\'s alone — every other read must floor on the existence axis');
 });
 
+t('the NAME-ONLY tier has exactly one reader, and it selects identity and nothing else (task 1002291)', () => {
+  // scoutingNameOnlySql admits HIDDEN accounts by design. Joined by a read that
+  // returned a number, it would hand out exactly the record hide_stats withholds,
+  // while looking adopted to the classification rule above. So the predicate is
+  // pinned to its one reader, and that reader's statement to three identity
+  // columns and no rollup table.
+  const readers = scanned
+    .filter((f) => f.rel !== PREDICATE_OWNER && /\bscoutingNameOnlySql\s*\(/.test(f.code))
+    .map((f) => f.rel);
+  assert.deepEqual(readers, ['modules/platform-identity/scouting-name-only.js'],
+    'the name-only tier is the recruiting directory\'s alone');
+  const reader = scanned.find((f) => f.rel === readers[0]);
+  const statements = accountStatements(reader.code);
+  assert.equal(statements.length, 1, 'one statement');
+  assert.match(statements[0].sql, /^SELECT github_login, display_name, avatar_url FROM platform_identity_accounts WHERE /,
+    'selecting the three identity columns a hidden builder\'s public page already shows — never an id, a count or a date');
+  assert.doesNotMatch(reader.code, /platform_identity_builder_project_activity/,
+    'and never touching the rollup table: presence in this tier must not depend on activity, or it would say who has built');
+});
+
 t('getPublicProfileExtras gates on the shared JS port (its SQL carries no predicate to join)', () => {
   const pi = scanned.find((f) => f.rel === 'modules/platform-identity/platform-identity.js');
   const span = functionSpans(pi.code).find((s) => s.name === 'getPublicProfileExtras');

package/tests/idp_device_exchange.mjs

@@ -13,6 +13,9 @@
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import crypto from 'node:crypto';
+// ESM import so the knip ratchet credits these test-facing exports (a
+// createRequire() import does not credit a CJS export).
+import { applicationVouchIdentity, verifyHubApplicationVouch } from '../src/bongos/auth-idp.js';
 
 const require = createRequire(import.meta.url);
 const auth = require('../src/bongos/auth.js');
@@ -194,5 +197,176 @@ t('a logout jti is fresh on first use, seen on replay, and evicted after expiry'
   assert.equal(auth.logoutTokenJtiSeenAndRecord(undefined, exp, now), false, 'missing jti is never "seen"');
 });
 
+// --- Application vouch (ADR 0201 D2, ADR 0208 D2, task 1002285) -------------
+// The hub's join relay carries a THIRD token kind to the target project: an
+// application vouch — identity AND purpose 'application'. ADR 0208 D2 found the
+// hole this closes: verifyHubAssertion never looked at `purpose`, so any
+// identity payload verified AS A LOGIN, and a captured vouch would have been
+// replayable into POST /auth/device/exchange as a device sign-in.
+
+function mintVouch(overrides = {}, opts = {}) {
+  return hubKeys.mintHubApplicationVouch(
+    { clientId: 'client-x', githubId: 42, githubLogin: 'octo', handle: 'octo', ...overrides },
+    { signingKey, ...opts },
+  );
+}
+
+// Sign an ARBITRARY payload with the real hub key — the only way to ask "what
+// does a verifier do with a shape no minter emits today?", which is exactly the
+// window ADR 0208 D2 says to close.
+function signRaw(payload) {
+  const b64u = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
+  const input = `${b64u({ alg: 'EdDSA', typ: 'JWT' })}.${b64u(payload)}`;
+  return `${input}.${crypto.sign(null, Buffer.from(input), signingKey).toString('base64url')}`;
+}
+const nowS = () => Math.floor(Date.now() / 1000);
+
+console.log('\nhub application vouch mint → instance verify (roundtrip):');
+
+t('a valid vouch verifies, carrying identity + purpose + handle and NO rank', () => {
+  const p = verifyHubApplicationVouch(mintVouch(), { publicKey, clientId: 'client-x' });
+  assert.equal(p.sub, '42');
+  assert.equal(p.applicant_login, 'octo');
+  assert.equal(p.github_login, undefined,
+    'the login rides as applicant_login: every login verifier any core ever shipped demands github_login, '
+    + 'so a core that predates the purpose refusal still cannot take a vouch as a device sign-in');
+  assert.equal(p.handle, 'octo');
+  assert.equal(p.purpose, 'application');
+  assert.equal(p.aud, 'client-x');
+  assert.ok(p.jti, 'a vouch always carries a jti — single use is chosen, not optional');
+  assert.equal(p.rank, undefined, 'a vouch is identity, never authority (ADR 0016)');
+  assert.equal(p.display_name, undefined, 'and not the login assertion’s profile fields either');
+});
+
+console.log('\nadversarial (vouch) — every one of these MUST be rejected:');
+
+t('wrong audience (a vouch for project A cannot vouch at project B)', () => {
+  assert.throws(() => verifyHubApplicationVouch(mintVouch(), { publicKey, clientId: 'other-client' }), /audience/);
+});
+
+t('NO audience configured never verifies — the envelope would otherwise skip the aud check', () => {
+  assert.throws(() => verifyHubApplicationVouch(mintVouch(), { publicKey, clientId: null }), /audience/);
+});
+
+t('expired vouch (minted 10 min ago; TTL is ~120s)', () => {
+  const stale = mintVouch({}, { nowMs: Date.now() - 10 * 60 * 1000 });
+  assert.throws(() => verifyHubApplicationVouch(stale, { publicKey, clientId: 'client-x' }), /expired/);
+});
+
+t('tampered payload (swap sub to another github_id) fails the signature', () => {
+  const [h, p, s] = mintVouch().split('.');
+  const payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8'));
+  payload.sub = '999';
+  const forged = `${h}.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.${s}`;
+  assert.throws(() => verifyHubApplicationVouch(forged, { publicKey, clientId: 'client-x' }), /signature/);
+});
+
+t('a different signing key, alg "none", malformed and a missing public key are all rejected', () => {
+  const otherPub = crypto.generateKeyPairSync('ed25519').publicKey;
+  assert.throws(() => verifyHubApplicationVouch(mintVouch(), { publicKey: otherPub, clientId: 'client-x' }), /signature/);
+  const [h, p, s] = mintVouch().split('.');
+  const hdr = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'));
+  hdr.alg = 'none';
+  const confused = `${Buffer.from(JSON.stringify(hdr)).toString('base64url')}.${p}.${s}`;
+  assert.throws(() => verifyHubApplicationVouch(confused, { publicKey, clientId: 'client-x' }), /alg|signature/);
+  assert.throws(() => verifyHubApplicationVouch('not-a-jwt', { publicKey, clientId: 'client-x' }), /malformed/);
+  assert.throws(() => verifyHubApplicationVouch(mintVouch(), { publicKey: null, clientId: 'client-x' }), /public key/);
+});
+
+t('a vouch with no jti is rejected — one vouch, one application needs something to count', () => {
+  const noJti = signRaw({ iss: 'cloudbongos-hub', aud: 'client-x', sub: '42', applicant_login: 'octo', purpose: 'application', iat: nowS(), exp: nowS() + 60 });
+  assert.throws(() => verifyHubApplicationVouch(noJti, { publicKey, clientId: 'client-x' }), /jti/);
+});
+
+t('a vouch with no applicant identity is rejected by the verifier itself, not only by the login match', () => {
+  for (const drop of ['sub', 'applicant_login']) {
+    const claims = { iss: 'cloudbongos-hub', aud: 'client-x', sub: '42', applicant_login: 'octo', purpose: 'application', iat: nowS(), exp: nowS() + 60, jti: `no-${drop}` };
+    delete claims[drop];
+    assert.throws(() => verifyHubApplicationVouch(signRaw(claims), { publicKey, clientId: 'client-x' }), /identity/, `missing ${drop}`);
+  }
+});
+
+t('mintHubApplicationVouch refuses without a signing key', () => {
+  assert.throws(() => hubKeys.mintHubApplicationVouch({ clientId: 'c', githubId: 1, githubLogin: 'x' }, {}), /signing key/);
+});
+
+console.log('\nlogin / logout / vouch are mutually NON-interchangeable:');
+
+t('an APPLICATION VOUCH is NOT accepted as a login assertion — the replay ADR 0208 D2 found open', () => {
+  assert.throws(() => auth.verifyHubAssertion(mintVouch(), { publicKey, clientId: 'client-x' }), /identity|purpose/);
+  // And the purpose refusal holds on its own: a vouch-shaped token that ALSO carried
+  // github_login (the shape a bolted-on purpose would have produced) still fails.
+  const both = signRaw({ iss: 'cloudbongos-hub', aud: 'client-x', sub: '42', github_login: 'octo', applicant_login: 'octo', purpose: 'application', iat: nowS(), exp: nowS() + 60, jti: 'both' });
+  assert.throws(() => auth.verifyHubAssertion(both, { publicKey, clientId: 'client-x' }), /purpose/);
+});
+
+t('verifyHubAssertion refuses ANY purpose on an identity payload, not only this one', () => {
+  for (const purpose of ['application', 'anything', '', null]) {
+    const token = signRaw({ iss: 'cloudbongos-hub', aud: 'client-x', sub: '42', github_login: 'octo', purpose, iat: nowS(), exp: nowS() + 60, jti: `p-${purpose}` });
+    assert.throws(() => auth.verifyHubAssertion(token, { publicKey, clientId: 'client-x' }), /purpose/,
+      `purpose=${JSON.stringify(purpose)} must not verify as a login`);
+  }
+});
+
+t('a LOGIN assertion is NOT accepted as an application vouch (no purpose)', () => {
+  assert.throws(() => verifyHubApplicationVouch(mint(), { publicKey, clientId: 'client-x' }), /application vouch/);
+});
+
+t('a LOGOUT token is NOT accepted as an application vouch, nor a vouch as a logout', () => {
+  assert.throws(() => verifyHubApplicationVouch(mintLogout(), { publicKey, clientId: 'client-x' }), /application vouch/);
+  assert.throws(() => auth.verifyHubLogoutToken(mintVouch(), { publicKey, clientId: 'client-x' }), /logout/);
+});
+
+console.log('\napplicationVouchIdentity — what a project may take from a vouch:');
+
+const vouchOpts = (githubLogin, extra = {}) => ({ githubLogin, publicKey, clientId: 'client-x', ...extra });
+
+t('a vouch for the login on the request yields its github id and handle (login case-insensitive)', () => {
+  assert.deepEqual(applicationVouchIdentity(mintVouch(), vouchOpts('Octo')), { githubId: '42', handle: 'octo' });
+});
+
+t('a vouch naming a DIFFERENT account than the request is no vouch at all', () => {
+  assert.equal(applicationVouchIdentity(mintVouch(), vouchOpts('someone-else')), null,
+    'otherwise one account’s vouch could be stapled to a request naming another');
+});
+
+t('one vouch vouches ONE application — the same token twice is vouched once', () => {
+  const token = mintVouch();
+  assert.ok(applicationVouchIdentity(token, vouchOpts('octo')));
+  assert.equal(applicationVouchIdentity(token, vouchOpts('octo')), null, 'the replay is unvouched');
+});
+
+t('an instance with no hub public key or no client id vouches nothing', () => {
+  assert.equal(applicationVouchIdentity(mintVouch(), vouchOpts('octo', { publicKey: null })), null);
+  assert.equal(applicationVouchIdentity(mintVouch(), vouchOpts('octo', { clientId: null })), null);
+});
+
+t('absent, garbage, forged and login-shaped tokens are null — never a throw', () => {
+  for (const token of [undefined, null, '', 'garbage', mint(), mintLogout()]) {
+    assert.equal(applicationVouchIdentity(token, vouchOpts('octo')), null);
+  }
+});
+
+t('LOCKSTEP: every handle the hub can hold survives the instance’s check, and nothing else does', () => {
+  // normalizeHandle is the hub's own rule (platform-identity.js); the instance keeps a
+  // boundary-forced mirror of it. Drive both over the same inputs so a change to
+  // either side that the other does not follow reds here, instead of handles
+  // silently arriving as null.
+  const { normalizeHandle } = require('../modules/platform-identity/platform-identity.js');
+  const inputs = ['octo', 'a', '9', 'a-b', 'builder-123456', 'x'.repeat(39), 'x'.repeat(40), '-a', 'a-', 'a_b', 'A', 'o.o', ''];
+  for (const raw of inputs) {
+    const hubHolds = normalizeHandle(raw) === raw;
+    const got = applicationVouchIdentity(mintVouch({ handle: raw }), vouchOpts('octo'));
+    assert.equal(got.handle, hubHolds ? raw : null, `handle ${JSON.stringify(raw)}: hub holds=${hubHolds}`);
+  }
+});
+
+t('a handle outside the canonical charset rides as null — the identity still stands', () => {
+  for (const handle of ['<b>octo</b>', 'Octo Cat', 'x'.repeat(60), 42, null]) {
+    assert.deepEqual(applicationVouchIdentity(mintVouch({ handle }), vouchOpts('octo')), { githubId: '42', handle: null },
+      `handle=${JSON.stringify(handle)}`);
+  }
+});
+
 console.log(`\nidp_device_exchange: ${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);