@bongos/core 1.18.0 → 1.18.3

package/tests/branding.mjs

@@ -19,12 +19,15 @@ const NEUTRAL = {
   envPrefix: 'CLOUDBONGOS',
 };
 
-const OTB = {
-  identity: { productName: 'Off the Boats', worldName: 'Amazonprimea', company: { name: 'Hermeslines', site: 'https://hermeslines.com' } },
-  llmProjectName: 'Off the Boats',
-  domains: { publicOrigin: 'https://amazonprimea.com', cookieDomain: '.amazonprimea.com' },
-  currency: { label: 'drachmae' },
-  envPrefix: 'OTB',
+// A GENERIC sample instance pack — exercises the resolver's override/merge/precedence logic
+// without baking any real instance's identity into the (published) test. (task 1002219 / audit H5:
+// swept the former customer-1 sample — Off the Boats / amazonprimea / Hermeslines — to neutral.)
+const SAMPLE = {
+  identity: { productName: 'Acme Rockets', worldName: 'Acme', company: { name: 'Acme Corp', site: 'https://acme.example' } },
+  llmProjectName: 'Acme Rockets',
+  domains: { publicOrigin: 'https://acme.example', cookieDomain: '.acme.example' },
+  currency: { label: 'tokens' },
+  envPrefix: 'ACME',
 };
 
 test('neutral starter resolves to the plain identity (no host leak)', () => {
@@ -34,33 +37,33 @@ test('neutral starter resolves to the plain identity (no host leak)', () => {
 });
 
 test('instance config overrides the neutral starter, deep-merged', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB });
-  assert.equal(b.identity.worldName, 'Amazonprimea');
-  assert.equal(b.identity.company.name, 'Hermeslines');
-  assert.equal(b.domains.cookieDomain, '.amazonprimea.com');
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE });
+  assert.equal(b.identity.worldName, 'Acme');
+  assert.equal(b.identity.company.name, 'Acme Corp');
+  assert.equal(b.domains.cookieDomain, '.acme.example');
   // a field present only in neutral survives the merge:
   assert.equal(b.domains.buildersOrigin, 'http://localhost:3000');
 });
 
 test('env override beats instance config (precedence)', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PUBLIC_ORIGIN: 'https://staging.example.com' } });
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PUBLIC_ORIGIN: 'https://staging.example.com' } });
   assert.equal(b.domains.publicOrigin, 'https://staging.example.com');
 });
 
 test('env override is ignored when empty', () => {
-  const b = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PUBLIC_ORIGIN: '' } });
-  assert.equal(b.domains.publicOrigin, 'https://amazonprimea.com');
+  const b = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PUBLIC_ORIGIN: '' } });
+  assert.equal(b.domains.publicOrigin, 'https://acme.example');
 });
 
 test('provisioningOrigin: optional, passes through config, env-overridable (task 2101)', () => {
   // Not required — unset resolves to undefined, and callers fall back to publicOrigin.
-  assert.equal(resolveBranding({ neutral: NEUTRAL, instance: OTB }).domains.provisioningOrigin, undefined);
+  assert.equal(resolveBranding({ neutral: NEUTRAL, instance: SAMPLE }).domains.provisioningOrigin, undefined);
   // Set in the instance pack, it survives the deep-merge.
-  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...OTB, domains: { ...OTB.domains, provisioningOrigin: 'https://get.cloudbongos.com' } } });
-  assert.equal(inst.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+  const inst = resolveBranding({ neutral: NEUTRAL, instance: { ...SAMPLE, domains: { ...SAMPLE.domains, provisioningOrigin: 'https://get.acme.example' } } });
+  assert.equal(inst.domains.provisioningOrigin, 'https://get.acme.example');
   // And <PREFIX>_PROVISIONING_ORIGIN beats config (same precedence as the other origins).
-  const env = resolveBranding({ neutral: NEUTRAL, instance: OTB, env: { OTB_PROVISIONING_ORIGIN: 'https://get.cloudbongos.com' } });
-  assert.equal(env.domains.provisioningOrigin, 'https://get.cloudbongos.com');
+  const env = resolveBranding({ neutral: NEUTRAL, instance: SAMPLE, env: { ACME_PROVISIONING_ORIGIN: 'https://get.acme.example' } });
+  assert.equal(env.domains.provisioningOrigin, 'https://get.acme.example');
 });
 
 test('missing required field throws', () => {
@@ -80,16 +83,19 @@ test('deepMerge does not mutate its inputs', () => {
   assert.deepEqual(out, { a: { x: 1, y: 2 } });
 });
 
-test('the committed neutral + OTB packs load and resolve (this repo = customer 1)', () => {
+test('the committed neutral pack loads + resolves to the neutral identity (the trunk carries no instance branding.json)', () => {
+  // The neutral trunk ships config/branding.neutral.json only — no config/branding.json — so
+  // loadBranding resolves to the plain Cloud Bongos identity (task 1002219 / audit H5: this used to
+  // assert the customer-1 OTB identity, stale since the amazonprimea→cloudbongos rebrand, ADR 0139/0140).
   const b = loadBranding({ env: {} });
-  assert.equal(b.identity.productName, 'Off the Boats');
-  assert.ok(b.domains.publicOrigin.startsWith('https://amazonprimea.com'));
-  assert.equal(b.identity.worldName, 'Amazonprimea');
+  assert.equal(b.identity.productName, 'Cloud Bongos');
+  assert.equal(b.identity.worldName, 'Cloud Bongos');
+  assert.ok(b.domains.publicOrigin.startsWith('http://localhost'));
 });
 
 test('resolveBranding does not freeze its input objects (no shared refs)', () => {
   const neutral = structuredClone(NEUTRAL);
-  const instance = structuredClone(OTB);
+  const instance = structuredClone(SAMPLE);
   resolveBranding({ neutral, instance });
   assert.equal(Object.isFrozen(neutral), false);
   assert.equal(Object.isFrozen(neutral.domains), false);

package/tests/github_repos_helpers.mjs

@@ -0,0 +1,91 @@
+// tests/github_repos_helpers.mjs — DB-free unit tests for the onboarding repo
+// picker's pure/near-pure pieces (task 1002099 / ADR 0141):
+//   • auth.scopeForWebFlow — the security-critical scope string
+//   • github-repos listUserRepos/createUserRepo — with a mock fetch (no network)
+//   • routes/auth.safeReturnTo — regression: the ?repos change didn't weaken the
+//     open-redirect guard.
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const auth = require(path.join(ROOT, 'src/bongos/auth.js'));
+const routesAuth = require(path.join(ROOT, 'src/bongos/routes/auth.js'));
+const gh = require(path.join(ROOT, 'src/bongos/github-repos.js'));
+
+test('scopeForWebFlow: identity-only by default, adds public_repo ONLY when repos=true', () => {
+  assert.equal(auth.scopeForWebFlow(), 'read:user');
+  assert.equal(auth.scopeForWebFlow({ repos: false }), 'read:user');
+  assert.equal(auth.scopeForWebFlow({ repos: true }), 'read:user public_repo');
+  // Never the all-or-nothing `repo` scope (ADR 0141) — public_repo only.
+  assert.ok(!auth.scopeForWebFlow({ repos: true }).split(' ').includes('repo'));
+});
+
+test('safeReturnTo still guards after the ?repos change: relative ok, cross-origin/protocol-relative blocked', () => {
+  assert.equal(routesAuth.safeReturnTo('/create'), '/create');
+  assert.equal(routesAuth.safeReturnTo('https://evil.example/steal'), null);
+  assert.equal(routesAuth.safeReturnTo('//evil.example'), null);
+  assert.equal(routesAuth.safeReturnTo('/create?x=1'), '/create?x=1'); // a query on the return itself is fine
+});
+
+// ---- github-repos helpers driven by a mock fetch ----
+function res(status, body) {
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  };
+}
+
+test('listUserRepos: requests affiliation=owner, maps rows, filters by q', async () => {
+  let calledUrl = '';
+  const fetchImpl = async (url) => {
+    calledUrl = url;
+    return res(200, [
+      { full_name: 'me/mercury', name: 'mercury', owner: { login: 'me' }, private: false },
+      { full_name: 'me/venus', name: 'venus', owner: { login: 'me' }, private: true },
+    ]);
+  };
+  const all = await gh.listUserRepos('tok', { fetchImpl });
+  assert.match(calledUrl, /affiliation=owner/);
+  assert.match(calledUrl, /per_page=100/);
+  assert.deepEqual(all.map((r) => r.full_name), ['me/mercury', 'me/venus']);
+  assert.equal(all[0].owner, 'me');
+  assert.equal(all[1].private, true);
+  const filtered = await gh.listUserRepos('tok', { q: 'MERC', fetchImpl }); // case-insensitive
+  assert.deepEqual(filtered.map((r) => r.full_name), ['me/mercury']);
+});
+
+test('listUserRepos: 401 → typed github_unauthorized', async () => {
+  const fetchImpl = async () => res(401, { message: 'Bad credentials' });
+  await assert.rejects(
+    () => gh.listUserRepos('tok', { fetchImpl }),
+    (e) => e.code === 'github_unauthorized' && e.status === 401,
+  );
+});
+
+test('createUserRepo: sends auto_init:false + private:false, returns full_name/html_url', async () => {
+  let sentBody = null;
+  const fetchImpl = async (url, init) => {
+    sentBody = JSON.parse(init.body);
+    return res(201, { full_name: 'me/mercury', html_url: 'https://github.com/me/mercury' });
+  };
+  const out = await gh.createUserRepo('tok', { name: 'mercury', fetchImpl });
+  assert.equal(sentBody.auto_init, false, 'empty repo — no README/first commit');
+  assert.equal(sentBody.private, false, 'public_repo scope → public');
+  assert.equal(sentBody.name, 'mercury');
+  assert.deepEqual(out, { full_name: 'me/mercury', html_url: 'https://github.com/me/mercury' });
+});
+
+test('createUserRepo: 422 → typed name_taken (the route maps this to a friendly 409)', async () => {
+  const fetchImpl = async () => res(422, { message: 'name already exists on this account' });
+  await assert.rejects(
+    () => gh.createUserRepo('tok', { name: 'dup', fetchImpl }),
+    (e) => e.code === 'name_taken' && e.status === 422,
+  );
+});

package/tests/github_token_store.mjs

@@ -0,0 +1,121 @@
+// tests/github_token_store.mjs — DB-free tests for the encrypted repo-token store
+// and the /github/repos gating (task 1002099 / ADR 0141). No real Postgres: db
+// helpers take an injectable pool `p`; no real GitHub: the route's 503/403 branches
+// don't reach GitHub. secret-box reads BUILDER_SECRET_KEY fresh each call, so we set
+// a valid key up front and toggle it per test.
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// A valid 32-byte key (64 hex chars) BEFORE requiring the modules — secret-box configured.
+process.env.BUILDER_SECRET_KEY = 'ab'.repeat(32);
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const db = require(path.join(ROOT, 'src/bongos/db.js'));
+const secretBox = require(path.join(ROOT, 'src/bongos/secret-box.js'));
+const buildGithubRouter = require(path.join(ROOT, 'src/bongos/routes/github.js'));
+const { attachFail } = require(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+
+// Mock pool: records every query, returns programmed rows for SELECTs.
+function mockPool(selectRows) {
+  const calls = [];
+  return {
+    calls,
+    query: async (text, params) => {
+      calls.push({ text, params });
+      return { rows: /^\s*SELECT/i.test(text) ? (selectRows || []) : [] };
+    },
+  };
+}
+
+test('secret-box is configured for this test file', () => {
+  assert.equal(secretBox.isConfigured(), true);
+});
+
+test('upsertGithubToken: stores an ENCRYPTED blob (never plaintext) + a future expires_at', async () => {
+  const p = mockPool();
+  const out = await db.upsertGithubToken({ builderId: 7, token: 'ghs_secret', scope: 'read:user public_repo', p });
+  assert.equal(out.stored, true);
+  const insert = p.calls.find((c) => /INSERT INTO github_oauth_tokens/i.test(c.text));
+  assert.ok(insert, 'issued an INSERT');
+  const enc = insert.params[1];
+  assert.notEqual(enc, 'ghs_secret', 'the plaintext token must never be stored');
+  assert.equal(secretBox.decrypt(enc), 'ghs_secret', 'the stored blob round-trips back to the token');
+  const expiresAt = insert.params[3];
+  assert.ok(expiresAt instanceof Date && expiresAt.getTime() > Date.now(), 'has a future expires_at');
+});
+
+test('getGithubToken: decrypts a live (unexpired) row', async () => {
+  const enc = secretBox.encrypt('ghs_live');
+  const p = mockPool([{ token_enc: enc, scope: 'x', expires_at: new Date(Date.now() + 60_000) }]);
+  const row = await db.getGithubToken({ builderId: 7, p });
+  assert.equal(row.token, 'ghs_live');
+});
+
+test('getGithubToken: an EXPIRED row returns null AND is swept (DELETE issued)', async () => {
+  const enc = secretBox.encrypt('ghs_old');
+  const p = mockPool([{ token_enc: enc, scope: 'x', expires_at: new Date(Date.now() - 60_000) }]);
+  const row = await db.getGithubToken({ builderId: 7, p });
+  assert.equal(row, null);
+  assert.ok(p.calls.some((c) => /DELETE FROM github_oauth_tokens/i.test(c.text)), 'lazily swept the expired row');
+});
+
+test('secret-box UNCONFIGURED: upsert no-ops (no plaintext ever written), get returns null', async () => {
+  const saved = process.env.BUILDER_SECRET_KEY;
+  delete process.env.BUILDER_SECRET_KEY;
+  try {
+    const p = mockPool();
+    const out = await db.upsertGithubToken({ builderId: 7, token: 'ghs_secret', p });
+    assert.equal(out.stored, false);
+    assert.equal(p.calls.length, 0, 'no query issued when secret-box is off');
+    assert.equal(await db.getGithubToken({ builderId: 7, p }), null);
+  } finally {
+    process.env.BUILDER_SECRET_KEY = saved;
+  }
+});
+
+// ---- route gating: the 503 / 403 signals the wizard branches on ----
+function fakeRes() {
+  const res = { _status: 200, _body: null };
+  res.status = (c) => { res._status = c; return res; };
+  res.json = (b) => { res._body = b; return res; };
+  attachFail({}, res, () => {}); // installs res.fail exactly as the router does
+  return res;
+}
+function finalHandler(router, method, pth) {
+  const layer = router.stack.find((l) => l.route && l.route.path === pth && l.route.methods[method]);
+  const stack = layer.route.stack;
+  return stack[stack.length - 1].handle; // the handler after requireBuilder
+}
+
+test('GET /github/repos → 503 github_repos_unavailable when secret-box is unconfigured', async () => {
+  const saved = process.env.BUILDER_SECRET_KEY;
+  delete process.env.BUILDER_SECRET_KEY;
+  try {
+    const handler = finalHandler(buildGithubRouter(), 'get', '/github/repos');
+    const res = fakeRes();
+    await handler({ builder: { id: 1 }, query: {} }, res);
+    assert.equal(res._status, 503);
+    assert.equal(res._body.error.code, 'github_repos_unavailable');
+  } finally {
+    process.env.BUILDER_SECRET_KEY = saved;
+  }
+});
+
+test('GET /github/repos → 403 repo_scope_required when configured but no stored token', async () => {
+  const orig = db.getGithubToken;
+  db.getGithubToken = async () => null; // configured, but this builder never granted repo access
+  try {
+    const handler = finalHandler(buildGithubRouter(), 'get', '/github/repos');
+    const res = fakeRes();
+    await handler({ builder: { id: 1 }, query: {} }, res);
+    assert.equal(res._status, 403);
+    assert.equal(res._body.error.code, 'repo_scope_required');
+  } finally {
+    db.getGithubToken = orig;
+  }
+});

package/tests/idp_device_exchange.mjs

@@ -0,0 +1,105 @@
+// tests/idp_device_exchange.mjs
+//
+// CLI federation crypto (ADR 0141 §1, task #1002108): the hub mints an Ed25519
+// assertion (modules/platform-identity/hub-keys.js) and the instance verifies it
+// OFFLINE (src/bongos/auth.js verifyHubAssertion). The two live across the
+// core<->module boundary and cannot share code, so this test drives a REAL
+// mint→verify roundtrip with a generated keypair and then tries to break it:
+// tamper, wrong audience, expiry, wrong key, algorithm-confusion, malformed.
+// DB-free + network-free.
+//
+// Run:  node tests/idp_device_exchange.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import crypto from 'node:crypto';
+
+const require = createRequire(import.meta.url);
+const auth = require('../src/bongos/auth.js');
+const hubKeys = require('../modules/platform-identity/hub-keys.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+// A hub keypair (base64 DER), as generateHubKeypair produces for env placement.
+const { privateKeyB64, publicKeyB64 } = hubKeys.generateHubKeypair();
+const signingKey = crypto.createPrivateKey({ key: Buffer.from(privateKeyB64, 'base64'), format: 'der', type: 'pkcs8' });
+const publicKey = crypto.createPublicKey({ key: Buffer.from(publicKeyB64, 'base64'), format: 'der', type: 'spki' });
+
+function mint(overrides = {}, opts = {}) {
+  return hubKeys.mintHubAssertion(
+    { clientId: 'client-x', githubId: 42, githubLogin: 'octo', displayName: 'Octo', avatarUrl: 'a', ...overrides },
+    { signingKey, ...opts },
+  );
+}
+
+console.log('hub assertion mint → instance verify (roundtrip):');
+
+t('a valid assertion verifies, and carries IDENTITY ONLY (no rank)', () => {
+  const p = auth.verifyHubAssertion(mint(), { publicKey, clientId: 'client-x' });
+  assert.equal(p.sub, '42');
+  assert.equal(p.github_login, 'octo');
+  assert.equal(p.aud, 'client-x');
+  assert.equal(p.iss, 'cloudbongos-hub');
+  assert.equal(p.rank, undefined, 'assertion must never carry a rank');
+  assert.equal(p.credits, undefined);
+});
+
+console.log('\nadversarial — every one of these MUST be rejected:');
+
+t('wrong audience (a code for client A cannot sign you into client B)', () => {
+  assert.throws(() => auth.verifyHubAssertion(mint(), { publicKey, clientId: 'other-client' }), /audience/);
+});
+
+t('expired assertion (minted 10 min ago; TTL is ~120s)', () => {
+  const stale = mint({}, { nowMs: Date.now() - 10 * 60 * 1000 });
+  assert.throws(() => auth.verifyHubAssertion(stale, { publicKey, clientId: 'client-x' }), /expired/);
+});
+
+t('tampered payload (escalate sub to another github_id) fails the signature', () => {
+  const [h, p, s] = mint().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(() => auth.verifyHubAssertion(forged, { publicKey, clientId: 'client-x' }), /signature/);
+});
+
+t('a different signing key is rejected (one instance cannot forge for another)', () => {
+  const otherPub = crypto.generateKeyPairSync('ed25519').publicKey;
+  assert.throws(() => auth.verifyHubAssertion(mint(), { publicKey: otherPub, clientId: 'client-x' }), /signature/);
+});
+
+t('algorithm-confusion (header alg swapped to "none") is rejected', () => {
+  const [h, p, s] = mint().split('.');
+  const hdr = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'));
+  hdr.alg = 'none';
+  const forged = `${Buffer.from(JSON.stringify(hdr)).toString('base64url')}.${p}.${s}`;
+  assert.throws(() => auth.verifyHubAssertion(forged, { publicKey, clientId: 'client-x' }), /alg|signature/);
+});
+
+t('malformed / empty tokens are rejected', () => {
+  assert.throws(() => auth.verifyHubAssertion('not-a-jwt', { publicKey, clientId: 'client-x' }), /malformed/);
+  assert.throws(() => auth.verifyHubAssertion('', { publicKey, clientId: 'client-x' }), /malformed/);
+  assert.throws(() => auth.verifyHubAssertion('a.b.c.d', { publicKey, clientId: 'client-x' }), /malformed/);
+});
+
+t('a missing public key never verifies (fail closed)', () => {
+  assert.throws(() => auth.verifyHubAssertion(mint(), { publicKey: null, clientId: 'client-x' }), /public key/);
+});
+
+t('mintHubAssertion refuses without a signing key', () => {
+  assert.throws(() => hubKeys.mintHubAssertion({ clientId: 'c', githubId: 1, githubLogin: 'x' }, {}), /signing key/);
+});
+
+t('generateHubKeypair yields distinct keypairs', () => {
+  const a = hubKeys.generateHubKeypair();
+  const b = hubKeys.generateHubKeypair();
+  assert.notEqual(a.privateKeyB64, b.privateKeyB64);
+  assert.notEqual(a.publicKeyB64, b.publicKeyB64);
+});
+
+console.log(`\nidp_device_exchange: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/idp_federation.mjs

@@ -0,0 +1,100 @@
+// tests/idp_federation.mjs
+//
+// Instance-side platform-IdP federation (ADR 0141 §1, task #1002107): when
+// auth.idp is set, web sign-in federates through the Cloud Bongos hub instead of
+// github.com. DB-free + network-free — tests the pure authorize-URL builder and
+// the DORMANCY invariant (federation stays OFF, so the direct-GitHub path is
+// unchanged, unless the branding auth.idp flag is explicitly true). The identity→
+// admission→session logic is the SAME shared primitives completeWebFlow uses
+// (firstTimeAdmissionBlocked/upsertBuilder/createSession — covered elsewhere), so
+// it can't drift; the network exchange (exchangeIdpCode) is an integration path.
+//
+// Run:  node tests/idp_federation.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const auth = require('../src/bongos/auth.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+console.log('idpAuthorizeUrl (pure hub authorize-URL builder):');
+
+t('builds the hub /sso/authorize URL with client_id, redirect_uri, state', () => {
+  const url = auth.idpAuthorizeUrl('https://cloudbongos.com', 'client-abc', 'st8', 'https://proj.example.com/api/gds/auth/web/callback');
+  const u = new URL(url);
+  assert.equal(u.origin, 'https://cloudbongos.com');
+  assert.equal(u.pathname, '/api/gds/sso/authorize');
+  assert.equal(u.searchParams.get('client_id'), 'client-abc');
+  assert.equal(u.searchParams.get('redirect_uri'), 'https://proj.example.com/api/gds/auth/web/callback');
+  assert.equal(u.searchParams.get('state'), 'st8');
+});
+
+t('trims a trailing slash on the hub origin', () => {
+  const url = auth.idpAuthorizeUrl('https://cloudbongos.com/', 'c', 's', 'https://p/cb');
+  assert.equal(new URL(url).pathname, '/api/gds/sso/authorize');
+  assert.ok(!url.includes('com//api'), 'no double slash between origin and path');
+});
+
+t('percent-encodes redirect_uri + state (no query injection)', () => {
+  const url = auth.idpAuthorizeUrl('https://hub', 'c', 'a&b=evil', 'https://p/cb?x=1');
+  const u = new URL(url);
+  // The raw string must not let an injected &b=evil become its own param.
+  assert.equal(u.searchParams.get('state'), 'a&b=evil');
+  assert.equal(u.searchParams.get('redirect_uri'), 'https://p/cb?x=1');
+  assert.equal(u.searchParams.get('b'), null);
+});
+
+console.log('\ndormancy invariant (federation OFF by default → direct-GitHub fallback):');
+
+// The neutral branding pack ships auth.idp=false, and this repo has no
+// config/branding.json, so idp is off. Even with the hub env creds present,
+// idpConfigured() must stay false — the branding flag is the gate, so a stray env
+// var can never silently flip a self-hosted instance into federation.
+function withHubEnv(fn) {
+  const keys = ['CLOUDBONGOS_HUB_ORIGIN', 'CLOUDBONGOS_HUB_CLIENT_ID', 'CLOUDBONGOS_HUB_CLIENT_SECRET'];
+  const prev = keys.map((k) => [k, process.env[k]]);
+  process.env.CLOUDBONGOS_HUB_ORIGIN = 'https://cloudbongos.com';
+  process.env.CLOUDBONGOS_HUB_CLIENT_ID = 'client-abc';
+  process.env.CLOUDBONGOS_HUB_CLIENT_SECRET = 'x'.repeat(64);
+  try { fn(); }
+  finally { for (const [k, v] of prev) { if (v === undefined) delete process.env[k]; else process.env[k] = v; } }
+}
+
+t('idpConfigured() is false by default even with hub env present (flag gates it)', () => {
+  withHubEnv(() => {
+    assert.equal(auth.idpConfigured(), false);
+    assert.equal(auth.loadIdpConfig(), null);
+    assert.equal(auth.idpEnabled(), false);
+  });
+});
+
+t('buildIdpAuthorizeUrl throws when the IdP is not configured (never silently misroutes)', () => {
+  withHubEnv(() => {
+    assert.throws(() => auth.buildIdpAuthorizeUrl('s', 'https://p/cb'), /not configured/);
+  });
+});
+
+console.log('\nmembership check-in role (§3 — coarse, never a rank):');
+
+t('membershipRole is builder by default, owner for the configured firstAdmin', () => {
+  const prev = process.env.CLOUDBONGOS_FIRST_ADMIN;
+  process.env.CLOUDBONGOS_FIRST_ADMIN = 'ownerlogin';
+  try {
+    assert.equal(auth.membershipRole({ githubLogin: 'ownerlogin' }), 'owner');
+    assert.equal(auth.membershipRole({ githubLogin: 'OwnerLogin' }), 'owner', 'case-insensitive');
+    assert.equal(auth.membershipRole({ githubLogin: 'someone-else' }), 'builder');
+    assert.equal(auth.membershipRole({}), 'builder');
+  } finally {
+    if (prev === undefined) delete process.env.CLOUDBONGOS_FIRST_ADMIN;
+    else process.env.CLOUDBONGOS_FIRST_ADMIN = prev;
+  }
+});
+
+console.log(`\nidp_federation: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/migrations_forward_safe.mjs

@@ -0,0 +1,86 @@
+// tests/migrations_forward_safe.mjs
+//
+// task 1002223 / audit H10 (finding F6) — the FAIL-CLOSED forward-safety gate for core migrations.
+// `bongos upgrade` auto-rollback reverts the code pin but NOT the DB, so a core migration must be
+// forward-safe (old code still runs on the new schema) — or explicitly acknowledge the exception
+// with a `-- forward-unsafe: <reason>` pragma. This runs in the DB-free unit gate every PR: add a
+// DROP COLUMN / RENAME / ALTER TYPE without the pragma and this REDs, long before a field rollback
+// strands old code on new schema. (The migrate.sh notice is advisory; THIS is the enforcement.)
+//
+// Run:  node tests/migrations_forward_safe.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const lint = require('../scripts/gds/lint-migrations.js');
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- THE GATE: the committed core migrations must be forward-safe (or acknowledged) ----
+t('core migrations: zero UNACKNOWLEDGED forward-unsafe operations', () => {
+  const { violations, acknowledged, scanned } = lint.scanMigrationsDir(join(REPO_ROOT, 'migrations'));
+  assert.ok(scanned > 0, 'expected to scan some core migrations');
+  assert.equal(violations.length, 0,
+    `unacknowledged forward-unsafe migration(s): ${violations.map((v) => `${v.file} [${v.unsafe.join(',')}]`).join('; ')}\n`
+    + '        Add a top-of-file `-- forward-unsafe: <reason>` comment if the operation is intentional + safe here.');
+  // sanity: the two known historical exceptions stay acknowledged (not silently dropped)
+  assert.ok(acknowledged.some((a) => a.file.startsWith('039_')), 'expected 039 to remain an acknowledged exception');
+  assert.ok(acknowledged.some((a) => a.file.startsWith('102_')), 'expected 102 to remain an acknowledged exception');
+});
+
+// ---- the scanner classifies operations correctly ----
+t('scanMigrationSql: flags each genuinely forward-unsafe operation', () => {
+  const cases = {
+    'drop-table': 'DROP TABLE widgets;',
+    'drop-column': 'ALTER TABLE t DROP COLUMN c;',
+    'rename-column': 'ALTER TABLE t RENAME COLUMN a TO b;',
+    'rename-table': 'ALTER TABLE t RENAME TO t2;',
+    'alter-column-type': 'ALTER TABLE t ALTER COLUMN c TYPE bigint;',
+    'set-not-null': 'ALTER TABLE t ALTER COLUMN c SET NOT NULL;',
+  };
+  for (const [expected, sql] of Object.entries(cases)) {
+    const r = lint.scanMigrationSql(sql);
+    assert.ok(r.unsafe.includes(expected), `expected ${expected} for: ${sql} — got ${JSON.stringify(r.unsafe)}`);
+  }
+});
+
+t('scanMigrationSql: does NOT flag additive / recreate-in-place operations', () => {
+  const safe = [
+    'CREATE TABLE t (id int);',
+    'ALTER TABLE t ADD COLUMN c text;',
+    'CREATE INDEX idx ON t (c);',
+    'DROP INDEX IF EXISTS idx; CREATE INDEX idx ON t (c);',       // recreate-in-place
+    'DROP TRIGGER IF EXISTS trg ON t; CREATE TRIGGER trg BEFORE INSERT ON t ...;',
+    'CREATE OR REPLACE VIEW v AS SELECT 1;',
+    'DROP VIEW IF EXISTS v; CREATE VIEW v AS SELECT 1;',
+    'DROP FUNCTION IF EXISTS f(); CREATE FUNCTION f() RETURNS void ...;',
+    "INSERT INTO t (id) VALUES (1);",
+  ];
+  for (const sql of safe) {
+    const r = lint.scanMigrationSql(sql);
+    assert.equal(r.unsafe.length, 0, `false positive on safe SQL: ${sql} — got ${JSON.stringify(r.unsafe)}`);
+  }
+});
+
+t('scanMigrationSql: the acknowledgement pragma flips an unsafe op to acknowledged', () => {
+  const r = lint.scanMigrationSql('-- forward-unsafe: intentional, two-step deploy\nALTER TABLE t DROP COLUMN c;');
+  assert.ok(r.unsafe.includes('drop-column'));
+  assert.equal(r.acknowledged, true);
+  assert.match(r.ackReason, /two-step/);
+});
+
+t('scanMigrationSql: an unsafe keyword only inside a comment does NOT count', () => {
+  const r = lint.scanMigrationSql('-- this migration does NOT drop table anything\nCREATE TABLE t (id int);');
+  assert.equal(r.unsafe.length, 0, `comment text must not trip the scan — got ${JSON.stringify(r.unsafe)}`);
+});
+
+console.log(`\nmigrations_forward_safe: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/module_api.mjs

@@ -20,7 +20,7 @@ const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
 // was added; no enabled module at its pinned coreVersion lost a capability.
 const PUBLISHED_SURFACE = [
   'CORE_VERSION',
-  'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope',
+  'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope', 'resolveSession',
   'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
   'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
   'routeRankCheck', 'permissionPathCheck', // BV1.R73: kernel trust classifiers (1.6.0)