@bongos/core 1.17.3 → 1.18.3

package/src/bongos/routes/auth.js

@@ -93,6 +93,13 @@ const DISCORD_STATE_COOKIE = 'gds_discord_state';
 // flow can land a builder back on the subdomain they started from (#726). Set
 // at /auth/web/start, consumed + cleared at the callback. Defaults to /builders.
 const RETURN_COOKIE = 'gds_return';
+// Short-lived cookie marking that THIS sign-in opted into repo access (the
+// onboarding wizard's `?repos=1`). Set at /auth/web/start, read at the callback so
+// it captures + persists the returned GitHub token — and cleared there. Scoping
+// capture to an explicit intent cookie (not just "the granted scope happens to
+// include repo") means an ordinary hall sign-in never stores a token, even for a
+// user who previously granted the broader scope (task 1002099 / ADR 0143).
+const REPOS_COOKIE = 'gds_oauth_repos';
 
 // The apex domain the instance is served under, read from the instance branding
 // pack's cookieDomain (".amazonprimea.com" → "amazonprimea.com",
@@ -245,10 +252,47 @@ module.exports = function buildAuthRouter() {
     }
   });
 
+  // POST /auth/device/exchange — CLI federation (ADR 0141 §1). The CLI ran the
+  // device flow against the HUB and got a hub-signed assertion; it presents it here.
+  // The instance verifies the Ed25519 signature OFFLINE against the provisioned hub
+  // public key (aud must equal this instance's client_id, unexpired), then runs the
+  // instance's OWN admission gate + upsertBuilder + createSession(source='cli') and
+  // returns the existing { token, builder }. Only reachable when auth.idp is set.
+  //
+  // rank: public — an auth-establishment endpoint; the hub-signed assertion IS the
+  //   bearer and is cryptographically verified before any session is minted.
+  router.post('/auth/device/exchange', async (req, res) => {
+    if (!auth.idpConfigured()) {
+      return res.fail('idp_not_configured', 503);
+    }
+    if (validateOrRespond(req, res, {
+      assertion: { required: true, type: 'string', maxLength: 4096 },
+    })) return;
+    try {
+      const { token, builder } = await auth.completeDeviceExchange({
+        assertion: req.body.assertion,
+        userAgent: req.headers['user-agent'],
+      });
+      res.json({ token, builder });
+    } catch (err) {
+      // Mirror the device/poll admission surface so the CLI prints the same
+      // "ask an Archon to invite you" path.
+      if (err && err.code === 'NOT_APPROVED') {
+        return res.status(403).json({ state: 'not_approved', error: 'not_approved' });
+      }
+      // A bad / expired / forged / wrong-audience assertion is an auth failure (401),
+      // not a server error — never mint a session for it.
+      console.error('[gds] /auth/device/exchange', err);
+      res.fail('invalid_assertion', { status: 401, message: String(err.message || 'invalid assertion').slice(0, 160) });
+    }
+  });
+
   // /auth/web — browser flow (used by the /builders page).
   // rank: public — entry into the GitHub OAuth handshake.
   router.get('/auth/web/start', (req, res) => {
-    if (!auth.authConfigured()) {
+    // Either direct-GitHub creds OR platform-IdP federation must be configured
+    // (ADR 0141 §1) — a federated instance has no GitHub app of its own.
+    if (!auth.authConfigured() && !auth.idpConfigured()) {
       return res.status(503).type('text/plain').send('auth not configured');
     }
     const state = crypto.randomBytes(16).toString('hex');
@@ -281,12 +325,32 @@ module.exports = function buildAuthRouter() {
         ...sessionCookieDomainOpts(req),
       });
     }
-    res.redirect(auth.buildAuthorizeUrl(state, redirectUri));
+    // Opt-in repo access (task 1002099 / ADR 0143): the onboarding wizard passes
+    // ?repos=1 so it can list/create the user's repos. Remember the intent in a
+    // short-lived cookie (same recipe as the state cookie) and request the broader
+    // scope on the direct-GitHub leg. Absent the flag this is a no-op — hall + CLI
+    // sign-ins stay identity-only.
+    const wantsRepos = req.query.repos === '1' || req.query.repos === 'true';
+    if (wantsRepos) {
+      res.cookie(REPOS_COOKIE, '1', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+        maxAge: 10 * 60 * 1000,
+        ...sessionCookieDomainOpts(req),
+      });
+    }
+    // Federate through the hub when configured (ADR 0141 §1); otherwise the direct
+    // GitHub authorize, carrying the repo-scope opt-in. Same CSRF state cookie either
+    // way — the callback validates it identically, so the hub leg is CSRF-protected too.
+    res.redirect(auth.idpConfigured()
+      ? auth.buildIdpAuthorizeUrl(state, redirectUri)
+      : auth.buildAuthorizeUrl(state, redirectUri, { repos: wantsRepos }));
   });
 
   // rank: public — OAuth callback; the state cookie + code are the bearer.
   router.get('/auth/web/callback', async (req, res) => {
-    if (!auth.authConfigured()) {
+    if (!auth.authConfigured() && !auth.idpConfigured()) {
       return res.status(503).type('text/plain').send('auth not configured');
     }
     const expectedState = parseCookie(req, STATE_COOKIE) || parseCookie(req, STATE_COOKIE_LEGACY);
@@ -304,14 +368,19 @@ module.exports = function buildAuthRouter() {
       ));
     }
     try {
-      // Must match the PINNED redirect_uri used at /auth/web/start (#734) — the
-      // GitHub token exchange requires an exact string match.
+      // Must match the PINNED redirect_uri used at /auth/web/start (#734) — both
+      // the GitHub token exchange and the hub /sso/token redemption require an
+      // exact string match against the value sent at authorize time.
       const redirectUri = `${WEB_REDIRECT_ORIGIN}/api/gds/auth/web/callback`;
-      const { token, expiresAt } = await auth.completeWebFlow({
-        code,
-        redirectUri,
-        userAgent: req.headers['user-agent'],
-      });
+      // Did THIS sign-in opt into repo access? (the wizard's ?repos=1 intent cookie)
+      const wantsRepos = parseCookie(req, REPOS_COOKIE) === '1';
+      // Federated (hub) vs direct-GitHub — same downstream: admission gate,
+      // upsertBuilder, createSession, gds_session cookie (ADR 0141 §1). The direct
+      // leg additionally captures the opt-in repo token (task 1002099 / ADR 0143);
+      // the hub leg has no direct GitHub token, so the wizard degrades to manual entry.
+      const { token, expiresAt, builder, githubToken, githubScope } = auth.idpConfigured()
+        ? await auth.completeIdpFlow({ code, redirectUri, userAgent: req.headers['user-agent'] })
+        : await auth.completeWebFlow({ code, redirectUri, userAgent: req.headers['user-agent'], captureRepoToken: wantsRepos });
       res.cookie(SESSION_COOKIE, token, {
         httpOnly: true,
         sameSite: 'lax',
@@ -322,15 +391,28 @@ module.exports = function buildAuthRouter() {
         // amazonprimea.com + builders. + status. (#726); host-only elsewhere.
         ...sessionCookieDomainOpts(req),
       });
+      // Persist the wizard's repo token (task 1002099 / ADR 0143): encrypted at rest,
+      // short-TTL, keyed to the builder — the repo picker/creator reads it back over
+      // the next few minutes. Gated on secret-box being configured (upsertGithubToken
+      // no-ops when it isn't). Best-effort: a capture failure must NEVER break sign-in.
+      if (wantsRepos && githubToken) {
+        try {
+          await db.upsertGithubToken({ builderId: builder.id, token: githubToken, scope: githubScope });
+        } catch (e) {
+          console.error('[gds] web/callback: repo-token capture failed (non-blocking):', e.message);
+        }
+      }
       // The state cookie is apex-scoped now (#734) — clear it with the same
       // domain or the browser keeps it. Clear the host-only form too for any
-      // cookie set before this change.
+      // cookie set before this change. Clear the repos-intent cookie the same way.
       const domainOpts = sessionCookieDomainOpts(req);
       res.clearCookie(STATE_COOKIE);
       res.clearCookie(STATE_COOKIE_LEGACY);
+      res.clearCookie(REPOS_COOKIE);
       if (domainOpts.domain) {
         res.clearCookie(STATE_COOKIE, domainOpts);
         res.clearCookie(STATE_COOKIE_LEGACY, domainOpts);
+        res.clearCookie(REPOS_COOKIE, domainOpts);
       }
       // Land back where sign-in began if a validated return target was stashed
       // (e.g. the builders subdomain bounced through here); else the hall.

package/src/bongos/routes/github.js

@@ -0,0 +1,90 @@
+// src/bongos/routes/github.js — GitHub repo list/create for the signed-in user, the
+// server half of the onboarding wizard's repo picker (adopt) + auto-create (fresh).
+// Task 1002099 / ADR 0143.
+//
+// These act on the user's OWN GitHub identity, so they live in core auth alongside
+// the sign-in flow that captured the token — not the provisioning module (whose
+// charter holds no tokens / calls no cloud API, ADR 0111 §2). They read the
+// short-lived, secret-box-encrypted `public_repo` token the web callback stored
+// (db.js github_oauth_tokens). Two "please reconnect / fall back" signals the wizard
+// branches on:
+//   • no stored token           → repo_scope_required (403)  → prompt a repos sign-in
+//   • secret-box unconfigured   → github_repos_unavailable (503) → manual repo entry
+// Both are behind requireBuilder + the router-wide rate-limit middleware.
+
+const express = require('express');
+const auth = require('../auth');
+const db = require('../db');
+const secretBox = require('../secret-box');
+const { listUserRepos, createUserRepo } = require('../github-repos');
+const { validateOrRespond } = require('./_helpers');
+
+// GitHub repo names: 1–100 chars of [A-Za-z0-9._-]. We validate strictly for a clean
+// 400; anything GitHub still rejects surfaces as the 422→409 name_taken path.
+const REPO_NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+// Resolve the caller's stored repo token, or send the right failure and return null.
+// Centralizes the 503-vs-403 decision both endpoints share.
+async function resolveRepoToken(req, res) {
+  if (!secretBox.isConfigured()) {
+    res.fail('github_repos_unavailable', { status: 503, message: 'Repo access is not configured on this server. Enter the repository manually.' });
+    return null;
+  }
+  const row = await db.getGithubToken({ builderId: req.builder.id });
+  if (!row) {
+    res.fail('repo_scope_required', { status: 403, message: 'Grant repository access to list or create repos.' });
+    return null;
+  }
+  return row.token;
+}
+
+module.exports = function buildGithubRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — acts only on the caller's OWN GitHub identity (the token
+  // they granted). No rank gate beyond being a signed-in builder.
+  router.get('/github/repos', auth.requireBuilder, async (req, res) => {
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      const q = typeof req.query.q === 'string' ? req.query.q.slice(0, 100) : '';
+      const repos = await listUserRepos(token, { q });
+      res.json({ repos });
+    } catch (err) {
+      if (err && err.status === 401) {
+        // The stored token was revoked/expired GitHub-side — drop it and re-prompt.
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to list your repos.' });
+      }
+      console.error('[gds] GET /github/repos', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not be reached. Try again, or enter the repository manually.' });
+    }
+  });
+
+  // rank: any-builder — creates a repo in the caller's OWN account.
+  router.post('/github/repos', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { name: { required: true, type: 'string', maxLength: 100 } })) return;
+    const name = String((req.body && req.body.name) || '').trim();
+    if (!REPO_NAME_RE.test(name)) {
+      return res.fail('bad_repo_name', { status: 400, message: 'Repository names use letters, numbers, and . _ - (1–100 chars).' });
+    }
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      const repo = await createUserRepo(token, { name });
+      res.status(201).json({ repo });
+    } catch (err) {
+      if (err && err.code === 'name_taken') {
+        return res.fail('name_taken', { status: 409, message: 'You already have a repository with that name. Pick another, or adopt the existing one.' });
+      }
+      if (err && err.status === 401) {
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to create the repo.' });
+      }
+      console.error('[gds] POST /github/repos', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not create the repo. Try again, or create it manually.' });
+    }
+  });
+
+  return router;
+};

package/src/bongos/routes/instance.js

@@ -32,7 +32,7 @@ const { corsPublicGet, asyncHandler } = require('./_helpers');
 const { clientBranding } = require('../../branding');
 const { clientModules, isModuleEnabled } = require('../../modules');
 const { loadRepoInfo } = require('../repo-info');
-const { authConfigured, openEnrollmentEnabled } = require('../auth');
+const { authConfigured, openEnrollmentEnabled, loadIdpConfig } = require('../auth');
 const { RANK_TIER } = require('../permission-path-check');
 
 // The manifest format id — bumped when the SHAPE changes so a CLI can detect a
@@ -59,6 +59,7 @@ function buildInstanceManifest({
   authConfigured: authOk,
   openEnrollment,
   devBoxEnabled,
+  idp = null,
 } = {}) {
   const b = branding || {};
   const rankLabels = b.rankLabels || {};
@@ -89,8 +90,15 @@ function buildInstanceManifest({
     ranks,
     repo: repoOut,
     auth: {
-      methods: authOk ? AUTH_METHODS.slice() : [],
-      configured: !!authOk,
+      // Sign-in works when the instance has its OWN GitHub app (authOk) OR it
+      // federates through the hub (idp) — a hosted instance has no app of its own.
+      methods: (authOk || idp) ? AUTH_METHODS.slice() : [],
+      configured: !!authOk || !!idp,
+      // Federation hint (ADR 0141 §1): present only when this instance federates.
+      // origin + client_id are PUBLIC (like an OAuth client_id); the client SECRET
+      // is never projected here. The CLI reads this to route device-flow + web
+      // sign-in through the hub instead of expecting a local GitHub app.
+      idp: idp || null,
     },
     admission: { policy: openEnrollment ? 'open' : 'invite-only' },
     devBox: { available: !!devBoxEnabled },
@@ -109,6 +117,7 @@ module.exports = function buildInstanceRouter() {
   // err.message if branding/modules fail to resolve (misconfigured instance) —
   // never leaks internals.
   router.get('/instance', asyncHandler('GET /instance', (_req, res) => {
+    const idpCfg = loadIdpConfig();
     res.json(buildInstanceManifest({
       branding: clientBranding(),
       modules: clientModules(),
@@ -117,6 +126,9 @@ module.exports = function buildInstanceRouter() {
       authConfigured: authConfigured(),
       openEnrollment: openEnrollmentEnabled(),
       devBoxEnabled: isModuleEnabled('dev-box'),
+      // Project OUT the client secret — the manifest is public; only origin +
+      // client_id (both public) advertise federation.
+      idp: idpCfg ? { origin: idpCfg.origin, client_id: idpCfg.clientId } : null,
     }));
   }, { message: false, errorCode: 'instance_manifest_failed' }));
 

package/src/bongos/routes.js

@@ -20,6 +20,7 @@ const express = require('express');
 const buildHealthzRouter = require('./routes/healthz');
 const buildInstanceRouter = require('./routes/instance');
 const buildAuthRouter = require('./routes/auth');
+const buildGithubRouter = require('./routes/github');
 const buildMeRouter = require('./routes/me');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
@@ -116,6 +117,7 @@ function buildGdsRouter() {
   router.use(buildHealthzRouter());
   router.use(buildInstanceRouter());
   router.use(buildAuthRouter());
+  router.use(buildGithubRouter());
   router.use(buildMeRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now

package/src/branding.js

@@ -44,6 +44,11 @@ const ENV_OVERRIDES = [
   ['OAUTH_ORIGIN', ['domains', 'oauthOrigin']],
   ['PROVISIONING_ORIGIN', ['domains', 'provisioningOrigin']],
   ['COOKIE_DOMAIN', ['domains', 'cookieDomain']],
+  // Cross-site identity federation flip (ADR 0141 §4). Provisioning sets
+  // <PREFIX>_AUTH_IDP=true per hosted instance (config/branding.neutral.json ships
+  // idp:false), so a co-tenant instance sharing the neutral pack still federates
+  // individually. 'bool'-coerced below — auth.js idpEnabled() reads it as strict === true.
+  ['AUTH_IDP', ['auth', 'idp'], 'bool'],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -69,6 +74,12 @@ function deepFreeze(o) {
   return o;
 }
 
+// This is the ONE structured host-identity contract. Project context (vision/world/visual-style
+// prose in docs/project-context.md) is deliberately PROSE-ONLY — there is no parallel resolver for
+// it, because nothing in the platform reads project context as data; it is written for agents to
+// read. If a host value must be CODE-READ, add it HERE (branding), not a new project-context
+// resolver. Decided in ADR 0142 (audit H11 / task 1002224).
+//
 // Pure resolver — all inputs injected, so tests drive it with zero I/O.
 function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
   // structuredClone so the merged result shares no nested references with the
@@ -76,9 +87,13 @@ function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
   // the caller's input objects (deepMerge shallow-copies only the top level).
   const resolved = structuredClone(deepMerge(neutral, instance));
   const prefix = resolved.envPrefix || 'CLOUDBONGOS';
-  for (const [suffix, p] of ENV_OVERRIDES) {
+  for (const [suffix, p, coerce] of ENV_OVERRIDES) {
     const v = env[`${prefix}_${suffix}`];
-    if (v !== undefined && v !== '') setPath(resolved, p, v);
+    if (v === undefined || v === '') continue;
+    // Most overrides are string-valued (origins, cookie domain) and set verbatim. A
+    // 'bool'-tagged override (auth.idp) coerces the env string to a real boolean —
+    // idpEnabled() checks `=== true`, so an uncoerced "true" would never federate.
+    setPath(resolved, p, coerce === 'bool' ? /^(1|true|yes|on)$/i.test(String(v)) : v);
   }
   const missing = REQUIRED.filter((p) => {
     const v = getPath(resolved, p);

package/src/instance-config.js

@@ -50,6 +50,21 @@ function envPrefix(b = safeBrand()) {
   return b.envPrefix || FALLBACK_ENV_PREFIX;
 }
 
+// The default API base the CLI targets when there is no <PREFIX>_API_BASE env
+// override AND no logged-in session api_base — i.e. the last-resort fallback.
+// Resolves to THIS instance's own publicOrigin from the branding pack (OTB →
+// https://amazonprimea.com, vanilla → http://localhost:3000), so the portable
+// core never hard-codes another instance's URL (task 1002201 — pre-ADR-0139 the
+// literal 'https://amazonprimea.com' was baked into cli-lib, sending every
+// unconfigured consumer at the founder's game box). Single source of truth: every
+// CLI base resolution routes through here. Last-resort http://localhost:3000 when
+// branding can't be read at all — a local dev origin, never a foreign prod, so an
+// unconfigured raw CLI fails safe rather than acting against someone else's DB.
+function defaultApiBase(b = safeBrand()) {
+  const origin = b && b.domains && b.domains.publicOrigin;
+  return (typeof origin === 'string' && origin.trim()) || 'http://localhost:3000';
+}
+
 // Absolute path to the instance config dir — the WRITE target and first read.
 function configHome(b = safeBrand()) {
   return path.join(os.homedir(), '.config', configDirName(b));
@@ -186,6 +201,7 @@ module.exports = {
   LEGACY_ENV_PREFIXES,
   configDirName,
   envPrefix,
+  defaultApiBase,
   configHome,
   configReadDirs,
   configPath,

package/src/module-api.js

@@ -199,8 +199,46 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         plus a THROWAWAY `updateCanary` marker removed in the phase-E follow-up. A
 //         backwards-compatible additive change with no API removal is exactly semver
 //         PATCH. Every `^1.x` / `^1.17` module pin is satisfied by 1.17.2.
+// 1.17.3 — task 2183 (R89 cutover prereq): republish so the packaged core carries the
+//         F6 migrate.sh fix (task 2180). Post-split, `scripts/migrate.sh` cd'd into the
+//         installed @bongos/core package before resolving the instance root, so a literal
+//         `npm run migrate` read the core's VANILLA module config and SILENTLY skipped
+//         every host + flag-gated module migration (rehearsal: 115 rows, no game schema;
+//         from the instance cwd, 121). 2180 fixed the script to resolve INSTANCE_ROOT from
+//         the invocation cwd (INIT_CWD/$PWD → the instance's bongos.config.json) and added
+//         a DB-free `--print-roots` regression guard. Published 1.17.2 PREDATES 2180, so a
+//         consumer pinning 1.17.2 would still skip host migrations — hence a PATCH republish
+//         at the F6-inclusive main. A functional-file bug fix with no doorway export change
+//         is exactly semver PATCH. Every `^1.x` / `^1.17` module pin is satisfied by 1.17.3.
+// 1.18.0 — task 2190 (R89 follow-up): first version cut from the cloud-bongos AUTHORITATIVE
+//         source repo. Re-seeds the standalone core (which had frozen at the 2026-07-03
+//         v1.14.0 extraction while core dev continued inside amazonprimea through 1.17.3)
+//         from amazonprimea's last-with-core commit 345494f2. Content is 1.17.3 PLUS the
+//         builders'-hall UI redesign (developed in amazonprimea as tasks 2171/2172/2173/2184) that
+//         post-dates the published 1.17.3 tarball — a new user-facing feature set with no
+//         doorway export removal, so semver MINOR. NOT yet published to npm (that is the
+//         follow-on release task); amazonprimea still runs the vendored 1.17.3.
+// 1.18.1 — go-live cut deployed to cloudbongos.com (owner-directed, 2026-07-14). Rolling
+//         1.18.0 content PLUS the onboarding GitHub repo picker + auto-create (task 1002099,
+//         ADR 0143 — core auth: opt-in public_repo scope, encrypted short-TTL token store,
+//         GET/POST /github/repos) and the goal 1000041 cross-project hub features
+//         (platform-identity module, ADR 0141). Adds no doorway export → semver PATCH.
+// 1.18.2 — go-live cut for cloudbongos.com (owner-directed, 2026-07-14). Rolling 1.18.1
+//         content PLUS the /create onboarding repo-picker rendering fix (task 1002228):
+//         the Home step's `hidden` attribute was defeated by author display rules
+//         (.field/.row2), so the adopt-picker / fresh-name / manual sub-panels all showed
+//         at once, and #ghConnect never appeared (toggled via `hidden` instead of its .on
+//         class). A CSS/markup-only fix in public-landing/create.html. No doorway export
+//         change → semver PATCH.
+// 1.18.3 — package-core .gitignore pin fix (task 1002229, idea 1000543). `npm install` never
+//         materializes .gitignore/.npmignore/.npmrc into an installed package, but package-core
+//         pinned a tracked .gitignore in tree_sha256 → every vendored `bongos upgrade` pin-verify
+//         failed with `missing installed file: .gitignore` and auto-rolled-back (the workaround
+//         was --skip-pin-verify, which the unattended auto-upgrade subscription cannot pass).
+//         package-core now drops npm-stripped files from the manifest + pin so it describes exactly
+//         what npm installs. Build-tool fix, no doorway export change → semver PATCH.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.17.2'; // see the changelog above — 1.17.2 is the task-2148 canary upgrade-proof bump (adds /version coreVersion; no doorway export change)
+const CORE_VERSION = '1.18.3'; // package-core pin honesty for vendored upgrades (task 1002229 / idea 1000543); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -226,6 +264,15 @@ module.exports = {
   //     tokens. A module's own bootstrap routes flag themselves; everything else
   //     stays closed to box tokens (the ADR 0016 trust boundary).
   allowBoxScope: auth.allowBoxScope,
+  // resolveSession(req) — resolve the request to a live session row (or null)
+  //     WITHOUT the 401-or-pass behaviour of requireBuilder. A module route that
+  //     must make its own auth decision — e.g. a browser page that REDIRECTS to
+  //     sign-in on a missing session rather than returning JSON 401 (the
+  //     platform-identity /sso/authorize leg, ADR 0141) — needs the raw resolve.
+  //     Returns the same shape lookupSession does (builder_id, github_id,
+  //     github_login, display_name, avatar_url, rank, source, status); rank is
+  //     still never an authority a module should trust for cross-instance identity.
+  resolveSession: (...a) => auth.resolveSession(...a),
 
   // --- data — the shared Postgres pool. A module owns its namespaced tables
   //     (<key>_*) via its own migrations (BV1.R46); it reaches them through this.

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,
+  );
+});