@bongos/core 1.19.1017 → 1.19.1019

package/tests/application_echo.mjs

@@ -31,6 +31,7 @@
 import assert from 'node:assert/strict';
 import { test, before, after } from 'node:test';
 import http from 'node:http';
+import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 
 // ESM import so the knip ratchet credits the constant this file consumes
@@ -103,6 +104,8 @@ let echoes = [];
 let memberships = [];
 let echoFails = false;
 let statements = [];
+let account = null;
+let accountFails = false;
 
 function seed() {
   const now = Date.now();
@@ -126,6 +129,12 @@ function seed() {
   ];
   echoFails = false;
   statements = [];
+  // An account that has cleared the consent floor: active, and the platform
+  // terms accepted (account-visibility.js isAccountActive).
+  account = { github_id: ME, github_login: 'octo', handle: 'octo-h', profile_state: 'active', terms_accepted_at: now - 9 * DAY, account_visibility: 'public', hide_stats: false };
+  accountFails = false;
+  hubSigningKeyB64 = null;
+  relayed = null;
 }
 const echo = (clientId) => echoes.find((e) => e.github_id === ME && e.client_id === clientId);
 
@@ -198,6 +207,13 @@ const pool = {
       return { rows: c ? [c] : [] };
     }
 
+    // getAccount — the relay's one read of the applicant's own account, to decide
+    // whether their handle may ride the vouch (task 1002285).
+    if (/FROM platform_identity_accounts WHERE github_id = \$1$/.test(sql)) {
+      if (accountFails) throw new Error('accounts table is on fire');
+      return { rows: account && String(params[0]) === String(ME) ? [account] : [] };
+    }
+
     if (/FROM platform_identity_project_memberships m/.test(sql)) {
       m = /WHERE (.+?) ORDER BY/.exec(sql);
       // The pending exclusion is MODELLED, not stripped. It used to be deleted
@@ -254,11 +270,21 @@ require.cache[statsPath] = {
   exports: { getProjectStats: async () => ({}) },
 };
 
+// The hub's signing key is read from env on every mint, so a test can switch the
+// hub between "provisioned" and "never provisioned" by setting this one value.
+// Generated here rather than by hub-keys.js, which must first load AFTER the
+// doorway stub below (it binds resolveEnv when it is required).
+const HUB_KEYPAIR = crypto.generateKeyPairSync('ed25519');
+const HUB_SIGNING_KEY_B64 = HUB_KEYPAIR.privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64');
+const hubPublicKey = HUB_KEYPAIR.publicKey;
+let hubSigningKeyB64 = null;
+
 const apiPath = require.resolve('../src/module-api.js');
 const realApi = require(apiPath);
 require.cache[apiPath].exports = {
   ...realApi,
   pool,
+  resolveEnv: (suffix) => (suffix === 'HUB_SIGNING_KEY' ? hubSigningKeyB64 : realApi.resolveEnv(suffix)),
   logger: () => ({ error() {}, warn() {}, info() {}, debug() {} }),
   requireBuilder: (req, _res, next) => {
     req.builder = { id: 1, github_id: ME, github_login: 'octo', display_name: 'Octo' };
@@ -272,9 +298,11 @@ const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
 // The project's own admission surface, scripted. This is the only thing that
 // decides whether an application happened.
 let relay = { status: 201, body: { ok: true } };
+let relayed = null; // the last request the relay sent the project — url + init
 const realFetch = globalThis.fetch;
-globalThis.fetch = async (url) => {
+globalThis.fetch = async (url, init) => {
   if (String(url).endsWith('/api/bongos/access-requests')) {
+    relayed = { url: String(url), init };
     if (relay === null) throw new Error('connection refused');
     return { status: relay.status, json: async () => relay.body };
   }
@@ -386,6 +414,77 @@ test('a failed echo write never turns a filed application into a reported failur
   assert.equal(r.json.status, 'requested');
 });
 
+// ── the vouch the relay carries (R09, task 1002285; ADR 0201 D2) ─────────────
+// The ECHO above is what authorizes the project's later profile read
+// (applicationBacksProfileRead); the VOUCH is what tells the project whose
+// profile to ask for. The relay is the only minter of either, which is why the
+// two are written by this one route and a vouch never arrives without an echo.
+
+const VOUCH_HEADER = 'X-Bongos-Platform-Assertion';
+const { verifyHubApplicationVouch } = require('../src/bongos/auth-idp.js');
+const relayedVouch = () => {
+  const headers = relayed && relayed.init && relayed.init.headers;
+  return headers ? headers[VOUCH_HEADER] : undefined;
+};
+
+test('a provisioned hub relays a vouch the TARGET project verifies: this account, this project', async () => {
+  seed();
+  echoes = echoes.filter((e) => e.client_id !== 'proj-open');
+  hubSigningKeyB64 = HUB_SIGNING_KEY_B64;
+  relay = { status: 201, body: { ok: true } };
+  const r = await join('please');
+  assert.equal(r.json.status, 'requested');
+  const p = verifyHubApplicationVouch(relayedVouch(), { publicKey: hubPublicKey, clientId: 'proj-open' });
+  assert.equal(p.sub, String(ME), 'the hub session’s own account — never a body field');
+  assert.equal(p.applicant_login, 'octo', 'the same login the relayed body names, which the project checks');
+  assert.equal(p.handle, 'octo-h');
+  assert.throws(() => verifyHubApplicationVouch(relayedVouch(), { publicKey: hubPublicKey, clientId: 'proj-other' }), /audience/,
+    'audience-scoped to the project it was relayed to');
+  assert.ok(echo('proj-open'), 'and the echo the profile read is gated on was written by the same relay');
+});
+
+test('a handle rides only past the consent floor — a provisional or no-terms account vouches with none', async () => {
+  for (const unconsented of [{ profile_state: 'provisional' }, { terms_accepted_at: null }]) {
+    seed();
+    hubSigningKeyB64 = HUB_SIGNING_KEY_B64;
+    account = { ...account, ...unconsented };
+    relay = { status: 201, body: { ok: true } };
+    await join();
+    const p = verifyHubApplicationVouch(relayedVouch(), { publicKey: hubPublicKey, clientId: 'proj-open' });
+    assert.equal(p.sub, String(ME), 'the identity is still vouched — it comes from the session, not the account row');
+    assert.equal(p.handle, null, `${JSON.stringify(unconsented)} discloses no handle, as on every other surface (ADR 0260 D2)`);
+  }
+});
+
+test('a PRIVATE account still vouches its handle — applying is the consent, as for the D3 sliver', async () => {
+  seed();
+  hubSigningKeyB64 = HUB_SIGNING_KEY_B64;
+  account = { ...account, account_visibility: 'private', hide_stats: true };
+  await join();
+  const p = verifyHubApplicationVouch(relayedVouch(), { publicKey: hubPublicKey, clientId: 'proj-open' });
+  assert.equal(p.handle, 'octo-h', 'the applicant view shows a private applicant’s handle too; the vouch shows no more');
+});
+
+test('a failed account read still relays, vouched, with no handle — the application never waits on it', async () => {
+  seed();
+  hubSigningKeyB64 = HUB_SIGNING_KEY_B64;
+  accountFails = true;
+  relay = { status: 201, body: { ok: true } };
+  const r = await join();
+  assert.equal(r.json.status, 'requested');
+  const p = verifyHubApplicationVouch(relayedVouch(), { publicKey: hubPublicKey, clientId: 'proj-open' });
+  assert.equal(p.handle, null);
+});
+
+test('a hub that never provisioned a signing key relays exactly as before: no header, no account read', async () => {
+  seed();
+  relay = { status: 201, body: { ok: true } };
+  const r = await join();
+  assert.equal(r.json.status, 'requested');
+  assert.equal(relayedVouch(), undefined, 'the project then writes the unvouched row it always wrote');
+  assert.ok(!statements.some((s) => /platform_identity_accounts/.test(s.sql)), 'nothing is read for a vouch that cannot be minted');
+});
+
 // ── the read-back ────────────────────────────────────────────────────────────
 
 test('GET /my-projects reports what was applied to and when — and no status', async () => {

package/tests/application_lifecycle.mjs

@@ -43,6 +43,7 @@
 import assert from 'node:assert/strict';
 import { test, before, after } from 'node:test';
 import http from 'node:http';
+import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -111,6 +112,7 @@ function predicateFor(rawWhere, params) {
   }
   if ((m = /\b(?:ar\.)?status = \$(\d+)\b/.exec(where))) { const v = p(m[1]); tests.push((r) => r.status === v); eat(); }
   if ((m = /\b(?:ar\.)?status = '(\w+)'/.exec(where))) { const v = m[1]; tests.push((r) => r.status === v); eat(); }
+  if ((m = /\bapplicant_github_id IS NULL\b/.exec(where))) { tests.push((r) => r.applicant_github_id == null); eat(); }
 
   for (const ph of rawWhere.matchAll(/\$(\d+)/g)) {
     if (!consumed.has(ph[1])) {
@@ -163,9 +165,12 @@ const pool = {
     // The public write. The partial unique index on lower(github_login) WHERE
     // status='pending' is modelled for real, so a duplicate application raises a
     // genuine 23505 and the route's "re-applying is not an error" branch is
-    // reached the way Postgres would reach it.
-    if (/^INSERT INTO access_requests \(github_login, display_name, note\)/.test(sql)) {
-      const [login, displayName, note] = params;
+    // reached the way Postgres would reach it. The column list and VALUES are
+    // matched EXACTLY and each value lands from its own placeholder, so the three
+    // vouch columns cannot be reordered or dropped from the real statement with
+    // every test still green (task 1002285).
+    if (/^INSERT INTO access_requests \(github_login, display_name, note, applicant_github_id, applicant_handle, vouched_at\) VALUES \(\$1, \$2, \$3, \$4, \$5, \$6\) RETURNING/.test(sql)) {
+      const [login, displayName, note, applicantGithubId, applicantHandle, vouchedAt] = params;
       if (rows.some((r) => r.status === 'pending' && String(r.github_login).toLowerCase() === String(login).toLowerCase())) {
         const err = new Error('duplicate key value violates unique constraint "uniq_access_requests_open_per_login"');
         err.code = '23505';
@@ -173,7 +178,8 @@ const pool = {
       }
       const fresh = {
         id: nextId++, github_login: login, display_name: displayName, note, status: 'pending',
-        applicant_github_id: null, vouched_at: null, resolved_by_builder_id: null, resolved_at: null,
+        applicant_github_id: applicantGithubId, applicant_handle: applicantHandle, vouched_at: vouchedAt,
+        resolved_by_builder_id: null, resolved_at: null,
         created_at: Date.now(),
       };
       rows.push(fresh);
@@ -188,12 +194,25 @@ const pool = {
           id: r.id, github_login: r.github_login, display_name: r.display_name, note: r.note,
           status: r.status, created_at: r.created_at, resolved_at: r.resolved_at,
           applicant_github_id: r.applicant_github_id, vouched_at: r.vouched_at,
+          // Returned only when the real SELECT names it, so the queue test below
+          // proves the route reads the column rather than that this fake invents it.
+          ...(/\bar\.applicant_handle\b/.test(sql) ? { applicant_handle: r.applicant_handle ?? null } : {}),
           vouched: r.applicant_github_id !== null,
           resolved_by_login: null,
         })),
       };
     }
 
+    // A vouched re-application taking over an unvouched pending row (ADR 0333 D4).
+    // The SET list is matched exactly, like the resolve's below.
+    if ((m = /^UPDATE access_requests SET display_name = \$2, note = \$3, applicant_github_id = \$4, applicant_handle = \$5, vouched_at = \$6 WHERE (.+?)$/.exec(sql))) {
+      const hit = rows.filter(predicateFor(m[1], params));
+      for (const r of hit) {
+        [r.display_name, r.note, r.applicant_github_id, r.applicant_handle, r.vouched_at] = params.slice(1, 6);
+      }
+      return { rows: [], rowCount: hit.length };
+    }
+
     // The resolve — one UPDATE, one WHERE, and that WHERE is the whole rule.
     // The SET list is matched EXACTLY, not as `.*?`: the fake applies its effect
     // from JS, so a `.*?` would let `resolved_by_builder_id = $2` be deleted from
@@ -237,6 +256,20 @@ require.cache[broadcastPath] = {
   exports: { postMemberApprovalRequest: async () => ({ posted: false, skipped: 'test' }) },
 };
 
+// The hub's side of the vouch, for real: a generated Ed25519 keypair, the real
+// minter, and the real verifier behind the doorway port — only the key and this
+// project's client id are injected, since a test process has no hub config.
+// Required (not imported) so it loads AFTER the ./pool stub above: an ESM import
+// is hoisted, and auth-idp → db-kernel would capture the real pool first.
+const { applicationVouchIdentity } = require('../src/bongos/auth-idp.js');
+const hubKeys = require('../modules/platform-identity/hub-keys.js');
+const HUB_KEYS = hubKeys.generateHubKeypair();
+const hubSigningKey = crypto.createPrivateKey({ key: Buffer.from(HUB_KEYS.privateKeyB64, 'base64'), format: 'der', type: 'pkcs8' });
+const hubPublicKey = crypto.createPublicKey({ key: Buffer.from(HUB_KEYS.publicKeyB64, 'base64'), format: 'der', type: 'spki' });
+const SELF_CLIENT_ID = 'proj-self';
+const vouchFor = (githubLogin, { githubId = 7001, handle = 'newcomer-h', clientId = SELF_CLIENT_ID, nowMs } = {}) =>
+  hubKeys.mintHubApplicationVouch({ clientId, githubId, githubLogin, handle }, { signingKey: hubSigningKey, nowMs });
+
 const apiPath = require.resolve('../src/module-api.js');
 const realApi = require(apiPath);
 const seams = require('../src/module-seams.js');
@@ -257,6 +290,8 @@ require.cache[apiPath].exports = {
   requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'owner' }; next(); },
   // requirePermission is NOT stubbed: realApi's own gate is used, so the denial
   // below is the production denial.
+  readApplicationVouch: (token, { githubLogin } = {}) =>
+    applicationVouchIdentity(token, { githubLogin, publicKey: hubPublicKey, clientId: SELF_CLIENT_ID }),
 };
 
 seams._reset();
@@ -282,12 +317,12 @@ before(async () => {
 });
 after(async () => { await new Promise((r) => server.close(r)); });
 
-function call(method, pathname, body) {
+function call(method, pathname, body, extraHeaders = {}) {
   return new Promise((resolve, reject) => {
     const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
     const req = http.request({
       host: '127.0.0.1', port, method, path: pathname,
-      headers: payload ? { 'content-type': 'application/json', 'content-length': payload.length } : {},
+      headers: { ...(payload ? { 'content-type': 'application/json', 'content-length': payload.length } : {}), ...extraHeaders },
     }, (res) => {
       const chunks = [];
       res.on('data', (c) => chunks.push(c));
@@ -383,6 +418,110 @@ test('apply: an already-approved login is told to sign in, and nothing is writte
   assert.equal(JSON.stringify(rows), before);
 });
 
+// ===========================================================================
+// The vouch WRITER (R09, task 1002285; ADR 0201 D2) — the hub's relay carries a
+// signed application vouch in a HEADER, and the row lands vouched only when it
+// verifies here AND names the very login the body names.
+// ===========================================================================
+
+const VOUCH_HEADER = 'X-Bongos-Platform-Assertion';
+const applyAs = (login, headers = {}) =>
+  call('POST', '/api/gds/access-requests', { github_login: login, display_name: 'New', note: 'hello (via platform My Projects)' }, headers);
+const landed = (login) => rows.find((x) => x.github_login === login);
+
+test('apply with a verified hub vouch: the row lands VOUCHED — github id, handle and when, together', async () => {
+  reset();
+  const r = await applyAs('Newcomer', { [VOUCH_HEADER]: vouchFor('newcomer') });
+  assert.equal(r.status, 201);
+  const row = landed('Newcomer');
+  assert.equal(row.applicant_github_id, '7001', 'the hub’s own account id, as text to join builders.github_id');
+  assert.equal(row.applicant_handle, 'newcomer-h', 'the handle rides with the identity it belongs to (ADR 0201 D2.6)');
+  assert.ok(row.vouched_at, 'and when it was verified, written in the same statement');
+  assert.equal(row.status, 'pending', 'a vouch files an application — it decides nothing');
+  assert.equal(await dbKernel.hasInvitedAccessRequest('Newcomer'), false,
+    'a vouch written by the REAL writer still admits nobody (ADR 0016)');
+});
+
+test('apply: the vouch columns are written together or not at all', async () => {
+  reset();
+  await applyAs('Newcomer', { [VOUCH_HEADER]: vouchFor('newcomer') });
+  await applyAs('plain');
+  for (const row of [landed('Newcomer'), landed('plain')]) {
+    const set = [row.applicant_github_id, row.applicant_handle, row.vouched_at].map((v) => v != null);
+    assert.ok(set.every(Boolean) || set.every((v) => !v), `mixed vouch columns on @${row.github_login}: ${JSON.stringify(set)}`);
+  }
+});
+
+test('apply: a vouch for a DIFFERENT account than the body names lands the row unvouched', async () => {
+  reset();
+  const r = await applyAs('victim', { [VOUCH_HEADER]: vouchFor('attacker') });
+  assert.equal(r.status, 201, 'never a refusal (D2.3) — the row is simply the one this project always had');
+  assert.equal(landed('victim').applicant_github_id, null,
+    'otherwise any vouch could be stapled to a request naming a well-known builder');
+  assert.equal(landed('victim').applicant_handle, null);
+});
+
+test('apply: a forged, expired, foreign or garbage vouch is never a refusal — it lands unvouched (D2.3)', async () => {
+  const otherKey = crypto.generateKeyPairSync('ed25519').privateKey;
+  const bad = {
+    garbage: 'not.a.vouch',
+    expired: vouchFor('newcomer', { nowMs: Date.now() - 10 * 60 * 1000 }),
+    'another project’s': vouchFor('newcomer', { clientId: 'proj-elsewhere' }),
+    forged: hubKeys.mintHubApplicationVouch({ clientId: SELF_CLIENT_ID, githubId: 7001, githubLogin: 'newcomer' }, { signingKey: otherKey }),
+    'a login assertion': hubKeys.mintHubAssertion({ clientId: SELF_CLIENT_ID, githubId: 7001, githubLogin: 'newcomer' }, { signingKey: hubSigningKey }),
+  };
+  for (const [kind, token] of Object.entries(bad)) {
+    reset();
+    const r = await applyAs('Newcomer', { [VOUCH_HEADER]: token });
+    assert.equal(r.status, 201, `${kind}: an attacker must not be able to make applications fail by sending garbage`);
+    assert.equal(landed('Newcomer').applicant_github_id, null, `${kind} vouch must not vouch`);
+  }
+});
+
+test('apply: one vouch vouches ONE application — the same header replayed lands unvouched', async () => {
+  reset();
+  const token = vouchFor('newcomer');
+  await applyAs('Newcomer', { [VOUCH_HEADER]: token });
+  rows = rows.filter((x) => x.github_login !== 'Newcomer'); // free the open-row index for the replay
+  await applyAs('Newcomer', { [VOUCH_HEADER]: token });
+  assert.equal(landed('Newcomer').applicant_github_id, null, 'the replay carried a spent jti');
+});
+
+test('a vouched re-application takes over an UNVOUCHED pending row for its own login — name and note too', async () => {
+  reset();
+  // ada's pending row is unvouched: filed off the landing page, or by anyone typing her login.
+  const r = await applyAs('ada', { [VOUCH_HEADER]: vouchFor('ada', { githubId: 8001, handle: 'ada-h' }) });
+  assert.equal(r.status, 200);
+  assert.equal(r.json.already_pending, true, 'still one open request — the index holds');
+  assert.equal(rows.filter((x) => x.github_login === 'ada').length, 1);
+  assert.equal(row(1).applicant_github_id, '8001', 'a row someone else filed under the login cannot pre-empt the real applicant');
+  assert.equal(row(1).applicant_handle, 'ada-h');
+  assert.ok(row(1).vouched_at);
+  assert.equal(row(1).display_name, 'New', 'and the words beside "Identity vouched" are now the vouched applicant’s own');
+  assert.match(row(1).note, /via platform My Projects/);
+  assert.equal(row(1).status, 'pending', 'and it decides nothing');
+});
+
+test('a re-application never re-stamps an ALREADY vouched row, and an unvouched one changes nothing', async () => {
+  reset();
+  const bo = { ...row(2) };
+  await applyAs('bo', { [VOUCH_HEADER]: vouchFor('bo', { githubId: 9999 }) });
+  assert.deepEqual(row(2), bo, 'the first vouch stands');
+  const ada = { ...row(1) };
+  await applyAs('ada');
+  assert.deepEqual(row(1), ada, 'an unvouched re-apply is the idempotent success it always was');
+});
+
+test('list-pending: the queue carries the handle the vouch brought, beside the vouch mark', async () => {
+  reset();
+  await applyAs('Newcomer', { [VOUCH_HEADER]: vouchFor('newcomer') });
+  const r = await call('GET', '/api/gds/access-requests');
+  const got = r.json.requests.find((x) => x.github_login === 'Newcomer');
+  assert.equal(got.vouched, true);
+  assert.equal(got.applicant_handle, 'newcomer-h');
+  assert.equal(r.json.requests.find((x) => x.github_login === 'ada').applicant_handle, null, 'an unvouched row has no handle');
+});
+
 // ===========================================================================
 // The queue — and the vouched/unvouched distinction it must carry
 // ===========================================================================

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);

package/tests/module_api.mjs

@@ -47,6 +47,7 @@ const PUBLISHED_SURFACE = [
   'projectJoinDoor', // added by task 1002331 (ADR 0182 D6 / ADR 0247): the COMPOSED join/apply door — visibility × join grant × joinability, one answer, so a module reading a single knob cannot re-open a door the other two closed
   'artistGate', // added by task 1003575 (ADR 0241): the artist gate — off | advisory | strict, plus the pure verdict helpers over it. Two modules ask it two different questions ("file this review?" and "does an open one hold the deploy?") and both must resolve the knob through this one reader, never branding().project
   'readApplicantProfileFromHub', // added by task 1002972 (privacy spec D7): the reviewer queue's LIVE per-render read of one applicant's hub profile view. NARROW by design — the underlying call is authenticated with this instance's hub client secret, and loadIdpConfig stays OFF the doorway so no module ever holds the credential that speaks for the whole project
+  'readApplicationVouch', // added by task 1002285 (ADR 0201 D2): the public access-request write's check of the hub's application vouch. NARROW for the same reason — core supplies the hub key and this instance's client_id, so a module passes a token and a login and can neither swap the key nor re-address the audience
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'isModuleEnabled', // task 1003881: is ANOTHER module present? onboarding's Discord approve/decline control is only actionable when the `discord` module's reaction handler is loaded, so the posting half has to be able to ask
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',