@bongos/core 1.19.1017 → 1.19.1018

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1017",
+  "version": "1.19.1018",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/auth-idp.js

@@ -29,6 +29,7 @@ const { branding, userAgent } = require('../branding');
 const { firstTimeAdmissionBlocked, maybeSeatFirstAdmin, openEnrollmentEnabled, reportActivityRollup, reportMembershipCheckIn, safeSyncRankRole } = require('./auth-admission.js');
 const { loadIdpConfig } = require('./auth-config.js');
 const { newSessionToken } = require('./auth-github.js');
+const log = require('./logger').logger.child({ src: 'auth-idp' });
 
 function idpAuthorizeUrl(origin, clientId, state, redirectUri) {
   const u = new URL(`${String(origin).replace(/\/+$/, '')}/api/bongos/sso/authorize`);
@@ -149,32 +150,38 @@ function loadHubPublicKey() {
   }
 }
 
-// Verify a hub-signed assertion (the compact-JWT format minted by the hub's
-// platform-identity/hub-keys.js — kept in lockstep across the core<->module
-// boundary, ADR 0091 §2). Verifies the Ed25519 signature FIRST (against the given
-// public key), then the issuer, audience (must equal THIS instance's client_id),
-// and expiry. The verify algorithm is HARDCODED to Ed25519 (`crypto.verify(null,…)`)
-// regardless of the header's `alg` field, so there is no algorithm-confusion attack.
-// Returns the validated payload, or throws. Pure over its inputs (testable).
-function verifyHubAssertion(token, { publicKey, clientId, nowMs = Date.now() } = {}) {
+// verifyHubToken — the envelope every hub token shares (hub-keys.js signHubToken,
+// lockstep across the boundary, ADR 0091 §2): Ed25519 signature FIRST, alg hardcoded
+// so there is no algorithm confusion, then issuer, audience (when given) and expiry.
+// Which KIND of token it is, each verifier below decides from the claims.
+function verifyHubToken(token, { publicKey, clientId, nowMs = Date.now(), label }) {
   if (!publicKey) throw new Error('hub public key not configured');
   const parts = String(token || '').split('.');
-  if (parts.length !== 3) throw new Error('malformed assertion');
+  if (parts.length !== 3) throw new Error(`malformed ${label}`);
   const [h, p, s] = parts;
   let header;
   try { header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8')); }
-  catch { throw new Error('malformed assertion header'); }
-  if (!header || header.alg !== 'EdDSA') throw new Error('unexpected assertion alg');
+  catch { throw new Error(`malformed ${label} header`); }
+  if (!header || header.alg !== 'EdDSA') throw new Error(`unexpected ${label} alg`);
   // Signature over the exact `header.payload` bytes — verify BEFORE trusting claims.
   const ok = crypto.verify(null, Buffer.from(`${h}.${p}`, 'utf8'), publicKey, Buffer.from(s, 'base64url'));
-  if (!ok) throw new Error('assertion signature invalid');
+  if (!ok) throw new Error(`${label} signature invalid`);
   let payload;
   try { payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8')); }
-  catch { throw new Error('malformed assertion payload'); }
-  if (payload.iss !== HUB_ASSERTION_ISSUER) throw new Error('unexpected assertion issuer');
-  if (clientId != null && String(payload.aud) !== String(clientId)) throw new Error('assertion audience mismatch');
-  if (typeof payload.exp !== 'number' || payload.exp < Math.floor(nowMs / 1000)) throw new Error('assertion expired');
+  catch { throw new Error(`malformed ${label} payload`); }
+  if (payload.iss !== HUB_ASSERTION_ISSUER) throw new Error(`unexpected ${label} issuer`);
+  if (clientId != null && String(payload.aud) !== String(clientId)) throw new Error(`${label} audience mismatch`);
+  if (typeof payload.exp !== 'number' || payload.exp < Math.floor(nowMs / 1000)) throw new Error(`${label} expired`);
+  return payload;
+}
+
+// Verify a hub-signed LOGIN assertion: the envelope, identity, and NO `purpose` —
+// any purpose, not a list, so no identity-bearing token kind can pass as a device
+// sign-in (ADR 0208 D2, ADR 0333 D2).
+function verifyHubAssertion(token, { publicKey, clientId, nowMs = Date.now() } = {}) {
+  const payload = verifyHubToken(token, { publicKey, clientId, nowMs, label: 'assertion' });
   if (payload.sub == null || !payload.github_login) throw new Error('assertion missing identity');
+  if (Object.prototype.hasOwnProperty.call(payload, 'purpose')) throw new Error('assertion carries a purpose — not a login assertion');
   return payload;
 }
 
@@ -195,41 +202,46 @@ const HUB_LOGOUT_PURPOSE = 'backchannel-logout';
 // github_login (rejected by verifyHubAssertion). Returns the validated payload
 // ({ sub: github_id, ... }) or throws. Pure over its inputs (testable, no I/O).
 function verifyHubLogoutToken(token, { publicKey, clientId, nowMs = Date.now() } = {}) {
-  if (!publicKey) throw new Error('hub public key not configured');
-  const parts = String(token || '').split('.');
-  if (parts.length !== 3) throw new Error('malformed logout token');
-  const [h, p, s] = parts;
-  let header;
-  try { header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8')); }
-  catch { throw new Error('malformed logout token header'); }
-  if (!header || header.alg !== 'EdDSA') throw new Error('unexpected logout token alg');
-  // Signature over the exact `header.payload` bytes — verify BEFORE trusting claims.
-  const ok = crypto.verify(null, Buffer.from(`${h}.${p}`, 'utf8'), publicKey, Buffer.from(s, 'base64url'));
-  if (!ok) throw new Error('logout token signature invalid');
-  let payload;
-  try { payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8')); }
-  catch { throw new Error('malformed logout token payload'); }
-  if (payload.iss !== HUB_ASSERTION_ISSUER) throw new Error('unexpected logout token issuer');
-  if (clientId != null && String(payload.aud) !== String(clientId)) throw new Error('logout token audience mismatch');
-  if (typeof payload.exp !== 'number' || payload.exp < Math.floor(nowMs / 1000)) throw new Error('logout token expired');
+  const payload = verifyHubToken(token, { publicKey, clientId, nowMs, label: 'logout token' });
   if (payload.purpose !== HUB_LOGOUT_PURPOSE) throw new Error('not a back-channel logout token');
   if (payload.sub == null) throw new Error('logout token missing subject');
   return payload;
 }
 
+// The purpose marker on a hub APPLICATION VOUCH — lockstep with hub-keys.js.
+const HUB_APPLICATION_PURPOSE = 'application';
+
+// Verify a hub-signed APPLICATION VOUCH (ADR 0333): purpose 'application', identity
+// (sub + applicant_login), and — stricter than its siblings — a required audience
+// (the envelope skips the check without one) and a jti (single use needs one).
+function verifyHubApplicationVouch(token, { publicKey, clientId, nowMs = Date.now() } = {}) {
+  if (clientId == null || clientId === '') throw new Error('application vouch audience not configured');
+  const payload = verifyHubToken(token, { publicKey, clientId, nowMs, label: 'application vouch' });
+  if (payload.purpose !== HUB_APPLICATION_PURPOSE) throw new Error('not an application vouch');
+  if (payload.sub == null || !payload.applicant_login) throw new Error('application vouch missing identity');
+  if (!payload.jti) throw new Error('application vouch missing jti');
+  return payload;
+}
+
+// jtiStore — a single-use jti register. One per token kind, so no two kinds share
+// dedupe state; entries expire with their token. In-memory per process.
+function jtiStore() {
+  const seen = new Map(); // jti -> expiry ms
+  return function seenAndRecord(jti, expSeconds, nowMs = Date.now()) {
+    for (const [k, exp] of seen) if (exp < nowMs) seen.delete(k);
+    if (!jti) return false; // no jti → cannot dedupe (aud + TTL remain the guards)
+    if (seen.has(jti)) return true;
+    seen.set(jti, expSeconds ? expSeconds * 1000 : nowMs + 120000);
+    return false;
+  };
+}
+
 // Anti-replay for CLI assertions (ADR 0141 §1, defense-in-depth on top of the
 // aud-scoping fix): a jti may be exchanged ONCE. In-memory per process, TTL = the
 // assertion's own expiry, so a captured assertion can't be replayed into multiple
 // sessions even inside its ~120s life. A restart clears it — acceptable given the
 // short window and that the aud binding is the primary control.
-const _seenAssertionJti = new Map(); // jti -> expiry ms
-function _assertionJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
-  for (const [k, exp] of _seenAssertionJti) if (exp < nowMs) _seenAssertionJti.delete(k);
-  if (!jti) return false; // no jti → cannot dedupe (aud + TTL remain the guards)
-  if (_seenAssertionJti.has(jti)) return true;
-  _seenAssertionJti.set(jti, expSeconds ? expSeconds * 1000 : nowMs + 120000);
-  return false;
-}
+const _assertionJtiSeenAndRecord = jtiStore();
 
 // Anti-replay for back-channel LOGOUT tokens (task 1002238, symmetric with the CLI
 // assertion path above). Honor a logout token's jti ONCE: the FIRST use revokes,
@@ -241,13 +253,43 @@ function _assertionJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
 // share dedupe state. In-memory per process; a restart clears it (acceptable — the
 // window is short and the aud binding is the primary control). Exported for the
 // route (routes/auth.js) since the DB revoke lives there, not in the kernel.
-const _seenLogoutJti = new Map(); // jti -> expiry ms
-function logoutTokenJtiSeenAndRecord(jti, expSeconds, nowMs = Date.now()) {
-  for (const [k, exp] of _seenLogoutJti) if (exp < nowMs) _seenLogoutJti.delete(k);
-  if (!jti) return false; // no jti → cannot dedupe (aud + TTL remain the guards)
-  if (_seenLogoutJti.has(jti)) return true;
-  _seenLogoutJti.set(jti, expSeconds ? expSeconds * 1000 : nowMs + 120000);
-  return false;
+const logoutTokenJtiSeenAndRecord = jtiStore();
+
+// Anti-replay for APPLICATION VOUCHES — chosen, not inherited (ADR 0333 D3): one
+// vouch vouches one application.
+const vouchJtiSeenAndRecord = jtiStore();
+
+// The hub's handle charset (platform-identity.js normalizeHandle — boundary-forced
+// mirror, pinned by tests/idp_device_exchange.mjs). Anything else is stored as null.
+const HUB_HANDLE_RE = /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/;
+
+// applicationVouchIdentity — { githubId, handle } from a verified, unspent vouch that
+// names the request's own login, else null; never throws. Null is never a refusal
+// (ADR 0201 D2.3): the route writes the unvouched row. Key + audience injected.
+function applicationVouchIdentity(token, { githubLogin, publicKey, clientId, nowMs = Date.now() } = {}) {
+  if (!token || !publicKey || !clientId) return null;
+  let payload;
+  try {
+    payload = verifyHubApplicationVouch(token, { publicKey, clientId, nowMs });
+  } catch (err) {
+    log.info({ reason: err.message }, 'application vouch not accepted — the request is written unvouched');
+    return null;
+  }
+  // The body's login is a string anyone may type: a vouch for another account is no vouch.
+  if (String(payload.applicant_login).toLowerCase() !== String(githubLogin || '').toLowerCase()) return null;
+  if (vouchJtiSeenAndRecord(payload.jti, payload.exp, nowMs)) return null;
+  return {
+    githubId: String(payload.sub),
+    handle: typeof payload.handle === 'string' && HUB_HANDLE_RE.test(payload.handle) ? payload.handle : null,
+  };
+}
+
+// readApplicationVouch — the doorway port: supplies THIS instance's hub key and
+// client_id itself, so a module can neither swap the key nor re-address the check.
+function readApplicationVouch(token, { githubLogin } = {}) {
+  if (!token) return null;
+  const idp = loadIdpConfig();
+  return applicationVouchIdentity(token, { githubLogin, publicKey: idp && loadHubPublicKey(), clientId: idp && idp.clientId });
 }
 
 // Complete a CLI federation exchange: verify the hub assertion, then run the SAME
@@ -318,6 +360,7 @@ async function completeDeviceExchange({ assertion, userAgent: ua }) {
 // without creds or network.
 
 module.exports = {
+  applicationVouchIdentity,
   buildIdpAuthorizeUrl,
   completeDeviceExchange,
   completeIdpFlow,
@@ -325,6 +368,8 @@ module.exports = {
   idpAuthorizeUrl,
   loadHubPublicKey,
   logoutTokenJtiSeenAndRecord,
+  readApplicationVouch,
+  verifyHubApplicationVouch,
   verifyHubAssertion,
   verifyHubLogoutToken,
 };

package/src/bongos/auth.js

@@ -57,7 +57,7 @@ const { branding, userAgent } = require('../branding');
 const { SCOPE, authConfigured, grantedScopeCoversRepos, idpConfigured, idpEnabled, loadIdpConfig, scopeForWebFlow } = require('./auth-config.js');
 const { firstAdminLogin, firstTimeAdmissionBlocked, instanceNeedsFirstAdmin, joinabilityMode, maybeSeatFirstAdmin, membershipKind, openEnrollmentEnabled, readApplicantProfileFromHub, webAdmissionStatus } = require('./auth-admission.js');
 const { buildAuthorizeUrl, completeWebFlow, pollDeviceFlow, startDeviceFlow } = require('./auth-github.js');
-const { buildIdpAuthorizeUrl, completeDeviceExchange, completeIdpFlow, idpAuthorizeUrl, loadHubPublicKey, logoutTokenJtiSeenAndRecord, verifyHubAssertion, verifyHubLogoutToken } = require('./auth-idp.js');
+const { buildIdpAuthorizeUrl, completeDeviceExchange, completeIdpFlow, idpAuthorizeUrl, loadHubPublicKey, logoutTokenJtiSeenAndRecord, readApplicationVouch, verifyHubAssertion, verifyHubLogoutToken } = require('./auth-idp.js');
 const { addDiscordGuildMember, buildDiscordAuthorizeUrl, discordAuthorizeUrl, discordBotConfigured, discordConfigured, exchangeDiscordCode, fetchDiscordUser, isValidDiscordUserId, loadDiscordBotToken, loadDiscordCreds, removeDiscordGuildMember } = require('./auth-discord.js');
 
 const MAX_AUTH_TOKEN_CANDIDATES = 6;
@@ -901,6 +901,7 @@ module.exports = {
   openEnrollmentEnabled,
   joinabilityMode,
   readApplicantProfileFromHub,
+  readApplicationVouch,
   firstTimeAdmissionBlocked,
   instanceNeedsFirstAdmin,
   webAdmissionStatus,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.1017'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1018'; // 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');
@@ -346,6 +346,12 @@ module.exports = {
   //     re-address it. Fails soft to null on every error, so a hub outage costs
   //     the profile block and never the queue.
   get readApplicantProfileFromHub() { return require('./bongos/auth').readApplicantProfileFromHub; },
+  // readApplicationVouch(token, { githubLogin }) — the write-side twin (task
+  //     1002285, ADR 0201 D2): verify the hub's application vouch on a public
+  //     access request → { githubId, handle } or null. Core supplies this
+  //     instance's hub key and client_id itself, so a module can neither
+  //     substitute a key nor re-address the check. Null is never a refusal.
+  get readApplicationVouch() { return require('./bongos/auth').readApplicationVouch; },
   // userAgent — the instance's HTTP User-Agent string (branding-derived). The
   // carved lifecycle module's github-push.js stamps every GitHub API request with
   // it instead of reaching into src/branding.js directly (BV1.R86).

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
 // ===========================================================================