@bongos/core 1.19.1017 → 1.19.1019

package/modules/platform-identity/hub-keys.js

@@ -14,14 +14,18 @@
 // no PKI service.
 //
 // The assertion is a compact JWT (alg=EdDSA). The wire format is mirrored, by
-// necessity, in the instance-side verifier (src/bongos/auth.js verifyHubAssertion)
-// — the two sides live across the core<->module boundary and cannot share code
-// (ADR 0091 §2 boundary-forced duplication). Keep them in lockstep:
+// necessity, in the instance-side verifiers (src/bongos/auth-idp.js) — the two
+// sides live across the core<->module boundary and cannot share code (ADR 0091
+// §2 boundary-forced duplication). Keep them in lockstep:
 //   token = base64url(JSON(header)) "." base64url(JSON(payload)) "." base64url(sig)
 //   header  = { alg: "EdDSA", typ: "JWT" }
-//   payload = { iss:"cloudbongos-hub", aud:<client_id>, sub:<github_id>,
-//               github_login, display_name, avatar_url, iat, exp, jti }
+//   payload = { iss:"cloudbongos-hub", aud:<client_id>, sub:<github_id>, …, iat, exp, jti }
 //   sig     = Ed25519(privkey, utf8(`${b64u(header)}.${b64u(payload)}`))
+// Three token kinds share that envelope, and each verifier demands exactly what
+// the other two lack, so none is ever accepted as another:
+//   login assertion   … = github_login, display_name, avatar_url   (no purpose)
+//   logout token      … = purpose:'backchannel-logout'             (no identity)
+//   application vouch … = applicant_login, handle, purpose:'application'
 'use strict';
 
 const crypto = require('node:crypto');
@@ -75,24 +79,17 @@ function hubPublicKeyB64() {
   return pub.export({ type: 'spki', format: 'der' }).toString('base64');
 }
 
-// Mint an audience-scoped, short-lived EdDSA assertion for a federated client. The
-// payload carries IDENTITY ONLY (never a rank). `nowMs`/`jti` are injectable for
-// deterministic tests. Returns the compact token string.
-function mintHubAssertion(
-  { clientId, githubId, githubLogin, displayName, avatarUrl },
-  { signingKey, nowMs, jti } = {},
-) {
+// signHubToken — the ONE envelope every hub token is minted in: issuer, the
+// caller's claims, then iat/exp (~120s) and a fresh jti. The three minters below
+// differ only in the claims they pass. Throws when no signing key is configured.
+function signHubToken(claims, { signingKey, nowMs, jti } = {}) {
   const key = signingKey || loadHubSigningKey();
   if (!key) throw new Error('hub signing key not configured');
   const iat = Math.floor((nowMs ?? Date.now()) / 1000);
   const header = { alg: 'EdDSA', typ: 'JWT' };
   const payload = {
     iss: ISSUER,
-    aud: String(clientId),
-    sub: String(githubId),
-    github_login: githubLogin,
-    display_name: displayName ?? null,
-    avatar_url: avatarUrl ?? null,
+    ...claims,
     iat,
     exp: iat + Math.floor(ASSERTION_TTL_MS / 1000),
     jti: jti || crypto.randomBytes(12).toString('base64url'),
@@ -102,6 +99,22 @@ function mintHubAssertion(
   return `${signingInput}.${sig}`;
 }
 
+// Mint an audience-scoped, short-lived EdDSA assertion for a federated client. The
+// payload carries IDENTITY ONLY (never a rank). `nowMs`/`jti` are injectable for
+// deterministic tests. Returns the compact token string.
+function mintHubAssertion(
+  { clientId, githubId, githubLogin, displayName, avatarUrl },
+  opts = {},
+) {
+  return signHubToken({
+    aud: String(clientId),
+    sub: String(githubId),
+    github_login: githubLogin,
+    display_name: displayName ?? null,
+    avatar_url: avatarUrl ?? null,
+  }, opts);
+}
+
 // The purpose marker that distinguishes a back-channel LOGOUT token from a login
 // assertion. Both are hub-signed EdDSA JWTs, but a logout token carries `purpose`
 // + NO identity fields, and a login assertion carries identity + NO `purpose` —
@@ -119,23 +132,28 @@ const LOGOUT_PURPOSE = 'backchannel-logout';
 // Same asymmetric signing + ~120s TTL + aud-binding as mintHubAssertion, so a
 // token minted for one instance can't be replayed against another. nowMs/jti
 // injectable for deterministic tests.
-function mintHubLogoutToken({ clientId, githubId }, { signingKey, nowMs, jti } = {}) {
-  const key = signingKey || loadHubSigningKey();
-  if (!key) throw new Error('hub signing key not configured');
-  const iat = Math.floor((nowMs ?? Date.now()) / 1000);
-  const header = { alg: 'EdDSA', typ: 'JWT' };
-  const payload = {
-    iss: ISSUER,
+function mintHubLogoutToken({ clientId, githubId }, opts = {}) {
+  return signHubToken({ aud: String(clientId), sub: String(githubId), purpose: LOGOUT_PURPOSE }, opts);
+}
+
+// The purpose marker on an APPLICATION VOUCH — kept in lockstep with the instance
+// verifier (src/bongos/auth-idp.js HUB_APPLICATION_PURPOSE).
+const APPLICATION_PURPOSE = 'application';
+
+// Mint the APPLICATION VOUCH the join relay sends a project (ADR 0201 D2, ADR 0333):
+// "this request comes from this account" — identity + handle, never a rank or record.
+// The login rides as `applicant_login`, NOT `github_login`: every login verifier any
+// core ever shipped demands `github_login`, so even a core that predates the purpose
+// refusal cannot accept a vouch as a device sign-in. `handle` is null unless the
+// caller cleared the consent floor.
+function mintHubApplicationVouch({ clientId, githubId, githubLogin, handle }, opts = {}) {
+  return signHubToken({
     aud: String(clientId),
     sub: String(githubId),
-    purpose: LOGOUT_PURPOSE,
-    iat,
-    exp: iat + Math.floor(ASSERTION_TTL_MS / 1000),
-    jti: jti || crypto.randomBytes(12).toString('base64url'),
-  };
-  const signingInput = `${b64uJson(header)}.${b64uJson(payload)}`;
-  const sig = crypto.sign(null, Buffer.from(signingInput, 'utf8'), key).toString('base64url');
-  return `${signingInput}.${sig}`;
+    applicant_login: githubLogin,
+    handle: handle ?? null,
+    purpose: APPLICATION_PURPOSE,
+  }, opts);
 }
 
 module.exports = {
@@ -146,6 +164,7 @@ module.exports = {
   loadHubSigningKey,
   hubSigningConfigured,
   hubPublicKeyB64,
+  mintHubApplicationVouch,
   mintHubAssertion,
   mintHubLogoutToken,
 };

package/modules/platform-identity/routes/my-projects.js

@@ -25,6 +25,8 @@ const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const projectStats = require('../project-stats');
 const applicationEcho = require('../application-echo');
+const hubKeys = require('../hub-keys');
+const { isAccountActive } = require('../account-visibility');
 const { projectPublishability } = require('../publish-gate');
 
 const { pool, requireBuilder, validateOrRespond, userAgent } = api;
@@ -116,6 +118,35 @@ function relayApplicantName(displayName) {
   return name || null;
 }
 
+// Where the relay carries the vouch — mirrored by the project's public POST
+// (modules/onboarding/routes/access-requests.js; boundary-forced, ADR 0091 §2).
+const APPLICATION_VOUCH_HEADER = 'X-Bongos-Platform-Assertion';
+
+// applicationVouchHeaders — the signed vouch for the HUB SESSION's own account
+// (never a body field), as headers to add, or {} (ADR 0333). Best-effort, never a
+// gate. The handle rides only past isAccountActive — the floor the applicant view
+// itself applies, so the vouch shows no handle the reviewer's queue would not.
+async function applicationVouchHeaders(client, builder) {
+  const signingKey = hubKeys.loadHubSigningKey();
+  if (!signingKey || !pi.isNumericGithubId(builder.github_id)) return {};
+  let handle = null;
+  try {
+    const account = await pi.getAccount(builder.github_id, { pool });
+    if (account && isAccountActive(account)) handle = account.handle || null;
+  } catch (e) {
+    api.logger('platform-identity').warn(`vouch handle read failed, vouching without one (non-fatal): ${e && e.message}`);
+  }
+  try {
+    const vouch = hubKeys.mintHubApplicationVouch({
+      clientId: client.client_id, githubId: builder.github_id, githubLogin: builder.github_login, handle,
+    }, { signingKey });
+    return { [APPLICATION_VOUCH_HEADER]: vouch };
+  } catch (e) {
+    api.logger('platform-identity').warn(`application vouch mint failed, relaying unvouched (non-fatal): ${e && e.message}`);
+    return {};
+  }
+}
+
 module.exports = function myProjectsRoutes() {
   const router = express.Router();
 
@@ -202,10 +233,11 @@ module.exports = function myProjectsRoutes() {
       // the project decides (open-join, or request/invite per ADR 0112). We post to
       // the registry-trusted origin, never the caller's raw input.
       let outcome = null;
+      const vouchHeaders = await applicationVouchHeaders(client, req.builder);
       try {
         const r = await fetch(`${client.origin}/api/bongos/access-requests`, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent(), ...vouchHeaders },
           body: JSON.stringify({
             github_login: req.builder.github_login,
             display_name: relayApplicantName(req.builder.display_name),

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1017",
+  "version": "1.19.1019",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1017",
+      "version": "1.19.1019",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1017",
+  "version": "1.19.1019",
   "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/bongos/db.js

@@ -605,6 +605,12 @@ async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
         WHERE builder_id = $1 AND revoked_at IS NULL`,
       [builderId]
     );
+    // PRIVACY (task 1003338 / ADR 0332): scrub the stored GitHub OAuth repo
+    // token in the SAME transaction — github_oauth_tokens is core's own table
+    // (not module-owned), so it gets the direct treatment the session revoke
+    // above gets. deleteGithubToken is a plain DELETE; safe to call even when
+    // no row exists.
+    await deleteGithubToken({ builderId, p: client });
     return { updated, activeClaims };
   });
   // Source-access clawback (ADR 0031 §6 / #600): a deactivated builder loses
@@ -616,6 +622,16 @@ async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
   await seams.emitAsync('builder.box-reconcile-needed', {
     builderId, rank: 'xenos', status: 'inactive', actor: `builder-exit:builder#${actorBuilderId}`,
   });
+  // PRIVACY (task 1003338 / ADR 0332): teardown port for a MODULE-owned
+  // builder-keyed secret (today: art-pipeline's Gemini BYOK key,
+  // gemini_key_enc/last4/set_at — CRUD moved out of core under ADR 0102, so
+  // core does not touch those columns directly). Best-effort, same as
+  // box-reconcile-needed above: a module that stores such a secret listens
+  // for this event and clears its own store; on a vanilla instance (no
+  // listener registered) it is a no-op.
+  await seams.emitAsync('builder.secrets-scrub-needed', {
+    builderId, actor: `builder-exit:builder#${actorBuilderId}`,
+  });
   return {
     builder: updated[0],
     claims_released: activeClaims.map((c) => c.task_id),
@@ -646,6 +662,12 @@ async function reactivateBuilder({ builderId, actorBuilderId }) {
     // Rank is intentionally left at whatever it is (xenos after a deactivation):
     // an Archon re-promotes deliberately via PATCH /builders/:id/rank.
     //
+    // Same posture for the secrets deactivateBuilder scrubs (task 1003338 /
+    // ADR 0332): NEITHER the deleted github_oauth_tokens row NOR the
+    // module-owned Gemini BYOK key is restored here, deliberately. A
+    // returning builder re-enters their own key; do not "helpfully" resurrect
+    // a stored credential on reactivation.
+    //
     // REACTIVATION IS THE EXPOSURE (task 1003193). Rank does not move here, but
     // status flipping back to 'active' makes whatever seeded rank-role the builder
     // still holds live again — getActiveBuildersWithRank, builderHoldsRankActive,

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.1019'; // 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).