@bongos/core 1.18.0 → 1.18.18

package/src/bongos/db-kernel.js

@@ -183,6 +183,32 @@ async function hasInvitedAccessRequest(login) {
   return rows.length > 0;
 }
 
+// accessStateByLogin — the three admission-relevant facts about a github login,
+// in ONE round trip: is there already a builder row (member), has an Archon
+// approved them (invited), are they waiting on one (pending). Case-insensitive
+// throughout, matching hasInvitedAccessRequest above.
+//
+// This exists for the "confirming access" waiting page (task 1002097): the page
+// polls a probe that must distinguish "admission is imminent" from "genuine
+// stranger", and doing that with three separate helpers would mean three
+// queries per poll per visitor. It reports FACTS ONLY — the admission DECISION
+// stays in auth.firstTimeAdmissionBlocked, which is the single gate both flows
+// share (SR-19). Nothing here grants access.
+async function accessStateByLogin(login) {
+  const { rows } = await pool.query(
+    `SELECT
+       EXISTS (SELECT 1 FROM builders
+                WHERE lower(github_login) = lower($1))                        AS member,
+       EXISTS (SELECT 1 FROM access_requests
+                WHERE lower(github_login) = lower($1) AND status = 'invited') AS invited,
+       EXISTS (SELECT 1 FROM access_requests
+                WHERE lower(github_login) = lower($1) AND status = 'pending') AS pending`,
+    [login]
+  );
+  const r = rows[0] || {};
+  return { member: !!r.member, invited: !!r.invited, pending: !!r.pending };
+}
+
 // --- Auth sessions (kernel: the builder_sessions token store auth.js drives) ----
 
 // SESSION_TTL_MS — session TTL on create/refresh. Centralized so the migration's
@@ -247,6 +273,7 @@ module.exports = {
   seatFirstAdminIfUnclaimed,
   getBuilderByGithubId,
   hasInvitedAccessRequest,
+  accessStateByLogin,
   createSession,
   lookupSession,
 };

package/src/bongos/db.js

@@ -25,6 +25,7 @@
 // grade-count SQL runs on both sides of the kernel↔module line — keep in sync.
 
 const { pool } = require('./pool');
+const secretBox = require('./secret-box');
 // Module seam (ADR 0083 / BV1.R43). The rank/status-change paths EMIT
 // `builder.box-reconcile-needed` AFTER COMMIT (best-effort) so the dev-box module
 // can reconcile a droplet a demotion/graduation implies — never a direct require
@@ -205,6 +206,68 @@ async function updateBuilderDisciplines(builderId, disciplines) {
 // { enc: null, ... } when no key is set.
 
 
+// ---- GitHub OAuth repo token, encrypted at rest (core_192 / task 1002099) ----
+//
+// The onboarding wizard (public-landing/create.html) opts into `public_repo` at
+// sign-in so it can list + create the user's repos. That user-to-server GitHub
+// token is held here BRIEFLY: encrypted with secret-box (master key in server env
+// only — the plaintext never touches the DB) and given a short TTL (one wizard
+// sitting), read back by the repo picker/creator, then deleted on use. It is the
+// auth system's OWN handshake token (distinct from a feature's third-party key
+// like the art module's Gemini key, ADR 0102), so it lives in core auth. secret-box
+// is the gate: with no master key configured we NEVER store a plaintext token —
+// capture no-ops and the wizard degrades to manual repo entry (ADR 0143).
+const GITHUB_TOKEN_TTL_MS = 60 * 60 * 1000; // 1h — one wizard sitting.
+
+// Store (or replace) the builder's GitHub repo token. `token` is the raw
+// user-to-server access token; it is encrypted here so the plaintext never touches
+// the DB. No-ops when secret-box is unconfigured (returns { stored:false }).
+async function upsertGithubToken({ builderId, token, scope = null, ttlMs = GITHUB_TOKEN_TTL_MS, p = pool }) {
+  if (!secretBox.isConfigured()) return { stored: false };
+  const enc = secretBox.encrypt(token);
+  const expiresAt = new Date(Date.now() + ttlMs);
+  await p.query(
+    `INSERT INTO github_oauth_tokens (builder_id, token_enc, scope, created_at, expires_at)
+       VALUES ($1, $2, $3, now(), $4)
+     ON CONFLICT (builder_id) DO UPDATE
+       SET token_enc = EXCLUDED.token_enc, scope = EXCLUDED.scope,
+           created_at = now(), expires_at = EXCLUDED.expires_at`,
+    [builderId, enc, scope, expiresAt],
+  );
+  return { stored: true, expires_at: expiresAt };
+}
+
+// Read + decrypt the builder's GitHub token, or null when there is none, it has
+// expired, or secret-box is unconfigured. Lazily deletes an expired row so the
+// table self-cleans without a cron (mirrors the deviceFlows reaping in auth.js).
+// The 503-vs-403 distinction the endpoint needs is made by the endpoint checking
+// secretBox.isConfigured() itself before calling this.
+async function getGithubToken({ builderId, p = pool }) {
+  if (!secretBox.isConfigured()) return null;
+  const { rows } = await p.query(
+    `SELECT token_enc, scope, expires_at FROM github_oauth_tokens WHERE builder_id = $1`,
+    [builderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  if (new Date(row.expires_at).getTime() <= Date.now()) {
+    await p.query(`DELETE FROM github_oauth_tokens WHERE builder_id = $1`, [builderId]).catch(() => {});
+    return null;
+  }
+  let token;
+  try { token = secretBox.decrypt(row.token_enc); }
+  catch { return null; } // a blob that won't decrypt (e.g. rotated master key) reads as "none".
+  return { token, scope: row.scope, expires_at: row.expires_at };
+}
+
+// Delete the builder's token (called after the wizard's terminal enqueue, and on
+// expiry). Best-effort; safe to call when nothing is stored.
+async function deleteGithubToken({ builderId, p = pool }) {
+  await p.query(`DELETE FROM github_oauth_tokens WHERE builder_id = $1`, [builderId]);
+  return { deleted: true };
+}
+
+
 // leaderboard() carved into modules/economy/credits.js (BV1.R77 / ADR 0093 §1-2).
 // Core read routes resolve it via the `reward` kernel port.
 
@@ -235,6 +298,15 @@ async function updateBuilderDisciplines(builderId, disciplines) {
 // shipped." Pure decision helper is exported so tests/rank_gate.mjs can exercise
 // the threshold without a DB.
 
+// REQUIRES_RANK_TIER — the canonical rank → tier (1-based) map: the rank "brain".
+// MUST stay byte-identical to permission-path-check.js RANK_TIER and
+// modules/lifecycle/db.js REQUIRES_RANK_TIER (tests/permission_path.mjs guards the
+// drift; gate-review.js + diagram-facts.js parse this literal by regex, so keep it
+// an inline object literal). Restores the binding the LIVE_RANK_LADDER carve
+// (ADR 0102) left dangling — both singleRungPromotionError below and the
+// db.REQUIRES_RANK_TIER export depend on it.
+const REQUIRES_RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
+
 function singleRungPromotionError(oldRank, newRank) {
   const a = REQUIRES_RANK_TIER[oldRank];
   const b = REQUIRES_RANK_TIER[newRank];
@@ -267,6 +339,24 @@ function singleRungPromotionError(oldRank, newRank) {
 // has nothing to collide on, so it's returned unchanged. Pure + exported so
 // tests can exercise it without a DB; claimTask calls it inside the txn.
 
+// syncGovernanceRankRole — keep governance_builder_roles in step with builders.rank
+// (BV1.R95b, ADR 0151). Resolved through the `governance.roleSync` kernel port and
+// run on the CALLER's transaction client, so the role rotation is atomic with the
+// rank write beside it. Core never requires modules/governance/ (ADR 0083).
+//
+// A missing port means the governance module is disabled, and skipping is the
+// fail-closed answer: the builder then holds no role and resolves to ZERO
+// permissions. Admitting anything here would make disabling a module a privilege
+// escalation — the same call requirePermission() makes on a missing port.
+//
+// TWINNED with modules/lifecycle/db.js (the boundary-forced _applyRankChangeTx
+// duplication, ADR 0091 §2) — keep the two in sync.
+async function syncGovernanceRankRole(client, builderId, rank) {
+  const roleSync = seams.resolveOptional('governance.roleSync');
+  if (!roleSync || typeof roleSync.syncRankRole !== 'function') return null;
+  return roleSync.syncRankRole(client, { builderId, rank });
+}
+
 async function _applyRankChangeTx(client, { builderId, newRank, actorBuilderId, reasonNote = null, enforceSingleRungPromotion = false }) {
   const { rows } = await client.query(
     `SELECT id, rank, status FROM builders WHERE id = $1 FOR UPDATE`,
@@ -291,6 +381,17 @@ async function _applyRankChangeTx(client, { builderId, newRank, actorBuilderId,
     [builderId, newRank]
   );
 
+  // BV1.R95b — rotate the seeded rank-role IN THIS TRANSACTION. A DEMOTION removes
+  // the higher role rather than merely adding the lower one; without that, a demoted
+  // Archon keeps resolving Archon permissions (the ADR 0016 freshness promise broken
+  // one layer beneath the uncached resolver).
+  //
+  // Deliberately NOT wrapped in try/catch. If the rotation cannot be written the rank
+  // write must roll back with it: a committed rank change whose role rotation failed
+  // IS the privilege-retention bug, just with a smaller window. Refusing leaves the
+  // builder consistently at their OLD rank, which the actor can retry.
+  await syncGovernanceRankRole(client, builderId, newRank);
+
   // V3.R28 / #249 — ceremony delta. Promotion (moving UP the ladder = lower
   // index in RANKS) earns +5; demotion is audit-only (0).
   const oldIdx = RANKS.indexOf(oldRank);
@@ -897,6 +998,7 @@ module.exports = {
   SESSION_TTL_MS,
   LIVE_RANK_LADDER,
   singleRungPromotionError,
+  REQUIRES_RANK_TIER,
   recentKarmaForBuilder,
   karmaDelta30d,
   insertAuditLog,
@@ -908,4 +1010,7 @@ module.exports = {
   upsertSecurityDoc,
   getSecurityDoc,
   listSecurityDocs,
+  upsertGithubToken,
+  getGithubToken,
+  deleteGithubToken,
 };

package/src/bongos/github-repos.js

@@ -0,0 +1,93 @@
+// GitHub repo list/create on behalf of the signed-in user — the server half of the
+// onboarding wizard's repo picker (adopt) + auto-create (fresh). Task 1002099 / ADR 0143.
+//
+// Raw `fetch` against GitHub's REST API (the house style — see auth.js
+// fetchGithubUser; no octokit dependency). The user-to-server token these take is
+// the `public_repo`-scoped token the web callback captured and stored (db.js
+// github_oauth_tokens); callers pass the decrypted token in, this module never
+// touches storage. `fetchImpl` is injectable so tests can drive it with a mock and
+// never hit the network.
+
+const { userAgent } = require('../branding');
+
+const GH_API = 'https://api.github.com';
+const PER_PAGE = 100;
+// Up to 300 most-recently-updated OWNED repos — plenty to back a picker for the vast
+// majority of accounts, and a hard bound so a power user can't make us page forever
+// (v1 cap; the picker filters this set client-and-server-side by substring).
+const MAX_PAGES = 3;
+
+class GithubApiError extends Error {
+  constructor(message, { status, code } = {}) {
+    super(message);
+    this.name = 'GithubApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function ghHeaders(token, extra = {}) {
+  return {
+    Authorization: `Bearer ${token}`,
+    'User-Agent': userAgent(),
+    Accept: 'application/vnd.github+json',
+    ...extra,
+  };
+}
+
+// List the signed-in user's OWN repos (affiliation=owner so `full_name` is always
+// `login/repo` and the org-OAuth-policy complexity is out of scope for v1),
+// most-recently-updated first, optionally filtered by a case-insensitive substring
+// `q` on the full name. Returns [{ full_name, name, owner, private }].
+async function listUserRepos(token, { q = '', fetchImpl = fetch } = {}) {
+  const out = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const url = `${GH_API}/user/repos?per_page=${PER_PAGE}&page=${page}&sort=updated&affiliation=owner`;
+    const res = await fetchImpl(url, { headers: ghHeaders(token) });
+    if (res.status === 401) {
+      throw new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
+    }
+    if (!res.ok) {
+      throw new GithubApiError(`GitHub /user/repos failed (${res.status})`, { status: res.status, code: 'github_error' });
+    }
+    const rows = await res.json();
+    if (!Array.isArray(rows) || rows.length === 0) break;
+    for (const r of rows) {
+      out.push({
+        full_name: r.full_name,
+        name: r.name,
+        owner: r.owner && r.owner.login,
+        private: !!r.private,
+      });
+    }
+    if (rows.length < PER_PAGE) break;
+  }
+  const needle = String(q || '').trim().toLowerCase();
+  return needle ? out.filter((r) => String(r.full_name).toLowerCase().includes(needle)) : out;
+}
+
+// Create an EMPTY repo in the signed-in user's personal account. auto_init:false =
+// no README/first commit (exactly the "leave it completely empty" the manual step
+// demanded); private:false because we hold only `public_repo`. Returns
+// { full_name, html_url }. A 422 (name already exists / invalid) becomes a typed
+// `name_taken` error the route maps to a friendly 409 rather than an opaque 500.
+async function createUserRepo(token, { name, fetchImpl = fetch } = {}) {
+  const res = await fetchImpl(`${GH_API}/user/repos`, {
+    method: 'POST',
+    headers: ghHeaders(token, { 'Content-Type': 'application/json' }),
+    body: JSON.stringify({ name, private: false, auto_init: false }),
+  });
+  if (res.status === 201) {
+    const r = await res.json();
+    return { full_name: r.full_name, html_url: r.html_url };
+  }
+  if (res.status === 401) {
+    throw new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
+  }
+  if (res.status === 422) {
+    throw new GithubApiError('A repository with that name already exists on your account', { status: 422, code: 'name_taken' });
+  }
+  throw new GithubApiError(`GitHub create-repo failed (${res.status})`, { status: res.status, code: 'github_error' });
+}
+
+module.exports = { listUserRepos, createUserRepo, GithubApiError, MAX_PAGES };

package/src/bongos/module-scope-map.js

@@ -166,6 +166,18 @@ const MODULE_GLOBS = {
     // to the kernel key (02-module-map §5).
     'modules/security/',
   ],
+  // --- configurable roles & permissions: the permission resolver, catalog, and
+  //     requirePermission gate (BV1 goal 1000030, ADR 0151). A core default:true
+  //     module. `protected` DERIVES true — its 'modules/governance/' glob is in
+  //     PROTECTED_GLOBS (the authz core) — so creating a goal scoped to governance is
+  //     Archon-only (BV1.R57 / POST /goals). The config globs are the per-instance
+  //     role templates (R96), listed here as goal territory; the module code lands in
+  //     R93+ (the carve precedes the feature — ADR 0086 §4). Written as exact paths,
+  //     not 'config/governance*.json' — the touches convention has no wildcards. ---
+  governance: [
+    'modules/governance/',
+    'config/governance.json', 'config/governance.neutral.json',
+  ],
   // --- the two web surfaces ---
   // BV1.R85: hall-UI graduated to modules/hall-ui/ — public-builders/ moved to
   // modules/hall-ui/public/ and is now a loader-discovered web-surface module
@@ -194,7 +206,21 @@ const MODULE_GLOBS = {
     // core/CLI-side under scripts/discord/.
     'scripts/discord/', 'modules/discord/',
   ],
-  'dev-box': ['modules/dev-box/', 'devbox-app/'],
+  // --- per-builder cloud dev boxes (DO droplets + Cloudflare tunnels), the sandbox
+  //     preview, server-mediated branch publish. First module carved to modules/dev-box/
+  //     (BV1.R43 — ADR 0083). Like the lifecycle/onboarding CLIs, the dev-box OPERATOR +
+  //     connect commands travel with the domain but stay under scripts/gds/: box.js (the
+  //     DO/CF provisioning control plane), box-auth-check, box-connect-lib, and the box
+  //     smoke test. Listing them here so a `dev-box`-scoped goal's wall covers the box
+  //     provisioning / bring-up work (BV1.R91, goal 1000051 C2), not just modules/dev-box/.
+  //     The box BRING-UP scripts (infra/box-*.sh — box-source-fetch, heartbeat, terminal
+  //     units) are INSTANCE-VENDORED (ADR 0144; not tracked in core), so they are not
+  //     listed here yet — they come under this key when de-vendored (task 1002243).
+  'dev-box': [
+    'modules/dev-box/', 'devbox-app/',
+    'scripts/gds/box.js', 'scripts/gds/box-auth-check.js', 'scripts/gds/box-connect-lib.js',
+    'scripts/gds/smoke-box.sh',
+  ],
 };
 
 // A glob set is protected iff it overlaps the imported PROTECTED_GLOBS — the one