@bongos/core 1.17.0

package/modules/dev-box/box-access.js

@@ -0,0 +1,275 @@
+// src/bongos/box-access.js — rank-gated SOURCE access for the per-builder dev box
+// (ADR 0031 §6 + open-question §9.2, task #600). Builds on #598's box lifecycle.
+//
+// THE DECISION #598 RECORDED, #600 ENFORCES
+// -----------------------------------------
+// #598 stamps a box with a `scope` ('starter' | 'full') and the `provisioned_rank`
+// at provision time, but injects NO GitHub credential — the cloud-init "logs
+// guidance rather than cloning, and #600 wires the scoped credential." This module
+// is that enforcement: it decides, on the builder's LIVE rank, whether a box may
+// reach source at all and WHICH surface it may materialize, and it drives the
+// offboarding clawback (revoke rank → de-provision box → source gone).
+//
+// THE MODEL (ADR 0016 extended from "writes are gated" to "source is gated")
+// --------------------------------------------------------------------------
+// A box holds NO permanent baked credential. At boot — and on a refresh cron —
+// the box calls GET /api/gds/box/source-access authenticated as the builder. The
+// GDS reads the builder's LIVE rank+status (their machine cannot forge it) and
+// either DENIES (403 → the box scrubs its credential + clone) or returns a
+// scope-appropriate clone spec plus a short-lived, operator-supplied credential
+// (src/bongos/box-credential.js; the secret lives in the prod ENV, never the repo —
+// ADR 0022). Because the check is live and per-fetch, revocation is INSTANT at the
+// credential layer: demote/deactivate a builder and their next refresh 403s, even
+// before the droplet teardown (the async cleanup) runs.
+//
+// THE HONEST LIMIT (recorded in ADR 0031 §6, preserved here)
+// ----------------------------------------------------------
+// Git cannot sub-path-scope a single private repo: any read credential for the
+// repo can, in principle, read all of it, and sparse-checkout is client-side. So
+// the 'starter' surface is DEFENSE-IN-DEPTH + AUDIT + REVOCATION, NOT insider-proof
+// DRM. A 'starter' box is issued the starter credential and told to sparse-checkout
+// only the safe surface; an authorized builder who fights the tooling could still
+// over-reach. The real day-one protection is (a) full-repo credentials are gated to
+// graduation and (b) every grant/denial is audited. A hard boundary would require a
+// physically separate starter repo — supported via the provider's STARTER_REPO_URL
+// override, left as an operator choice (see box-credential.js).
+
+const {
+  DEFAULT_PROVISION_FLOOR,
+  rankMeetsBoxFloor,
+  boxScopeForRank,
+  getBoxByBuilderId,
+  recordEvent,
+} = require('./boxes');
+
+// ---------------------------------------------------------------------------
+// PURE: the scoped surface catalog
+// ---------------------------------------------------------------------------
+
+// The repo surface a 'starter' (Xenos/Thetes) box may sparse-checkout — the
+// "first tasks on a scoped surface" of ADR 0031 §9.2: the art pipeline,
+// docs/design records, the public status surface, the curiosity inbox, and
+// .devcontainer so the box can build its environment — PLUS the builder WORKFLOW
+// TOOLING (#818-followup): the /builder-* skills (.claude), the GDS CLI (scripts),
+// and the GDS lib those scripts require (src/bongos + cone-mode pulls the src/*.js
+// root files like src/db.js). Without that tooling a newcomer's box can't run
+// /builder-start|claim|ship — the whole point of being on the box.
+//
+// SANDBOX-FOR-EVERYONE (ADR 0052, task #1001 — Lars, 2026-06-13): the PRODUCT/game
+// code is now in the starter scope too — `src/world`, `src/rooms`, and the
+// `public/` game client — so EVERY box (not just Metic+ full-clone boxes) can run
+// the live sandbox (sandbox-<login>.amazonprimea.com, ADR 0044). The box serves
+// the game from a GAME-ONLY entry (src/preview-server.js) that never mounts
+// /api/gds, so the privacy boundary that matters for a PUBLIC sandbox URL is the
+// RUNTIME (what the box process exposes), NOT source exclusion. That is consistent
+// with the rest of this list: newcomers already hold the build-tooling source
+// (scripts, .claude, src/bongos — no secrets), so adding the game source changes no
+// secret posture. The locked decision (#1001) leaves the broader source-tightening
+// (idea #213) deferred and out of scope.
+//
+// STILL EXCLUDES `migrations/` — a degraded-DB preview needs no schema, and the
+// migrations are the build-pipeline internal that idea #213 would tighten. No DB
+// runs on the box anyway (ADR 0044 §1), so the game preview never reads it.
+//
+// Paths are git cone-mode sparse-checkout entries. ONLY directories — cone mode
+// rejects a file path ("'<file>' is not a directory") which aborts the whole
+// `git sparse-checkout set`. Top-level files (CLAUDE.md, README.md, package.json,
+// server.js, generative-ideas.md, …) are included AUTOMATICALLY by cone mode, so
+// they need not (and must not) be listed here. Cone mode also includes the direct
+// files of every ancestor directory — so listing src/bongos (or src/world, src/rooms)
+// pulls src/*.js root files like src/db.js + src/seats.js, which the game rooms
+// require.
+const STARTER_SPARSE_PATHS = [
+  // status surface moved to modules/status-ui/ in BV1.R84 (was public-status/).
+  '.devcontainer', 'art', 'docs', 'modules/status-ui',
+  '.claude', 'scripts', 'src/bongos',
+  // The product/game runtime so the box can serve the live sandbox (ADR 0052).
+  // The game-only entry (src/preview-server.js) registers WorldRoom + QueueRoom
+  // from src/rooms and renders src/world + the public/ client; none of it mounts
+  // /api/gds. `public/` is the game client (NOT modules/hall-ui/public/, the hall
+  // surface carved in BV1.R85, which stays out of a starter box).
+  'src/world', 'src/rooms', 'public',
+  // infra/ carries the box's own bring-up scripts (box-heartbeat.sh,
+  // box-report-terminal.sh, the terminal + game-preview units) that
+  // box-source-fetch installs post-clone. Without it the heartbeat cron never
+  // installs, so claude_active is never reported, first_connected_at is never
+  // stamped, and the "Connect to thy dev box" onboarding step never ticks. No
+  // secrets live in infra/ (ADR 0022).
+  'infra',
+];
+
+// States in which a box is (or is becoming) a running droplet that can actually
+// hold a clone. The source credential is issued ONLY to a builder whose box is in
+// one of these — a stolen token used OFF a live box, or a builder with no / parked /
+// destroyed box, gets no credential. Defense-in-depth on top of the rank gate, and
+// it aligns the model: "the BOX holds the credential", so there must be a live box.
+const SOURCE_HOLDING_STATES = ['active', 'provisioning', 'waking'];
+function boxCanHoldSource(state) {
+  return SOURCE_HOLDING_STATES.includes(state);
+}
+
+// What a given scope is allowed to materialize. Fail-closed: any unknown/missing
+// scope collapses to 'starter' (least privilege), never to 'full'.
+function cloneSpecForScope(scope) {
+  if (scope === 'full') {
+    return { scope: 'full', mode: 'full', sparsePaths: null };
+  }
+  return { scope: 'starter', mode: 'sparse', sparsePaths: [...STARTER_SPARSE_PATHS] };
+}
+
+// ---------------------------------------------------------------------------
+// PURE: the per-fetch access decision (consumed by GET /box/source-access)
+// ---------------------------------------------------------------------------
+
+// Decide what source access a builder gets RIGHT NOW. The route reads the live
+// rank+status from the DB and passes them in; this stays pure + unit-tested so the
+// route and any future caller enforce the SAME rule. The scope is derived from the
+// LIVE rank (not the box's stored scope), so a just-graduated builder gets 'full'
+// on their very next fetch — before the slower box reconcile flips the stored column.
+//
+// Returns one of:
+//   { allowed:false, reason:'BUILDER_INACTIVE' }
+//   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
+//   { allowed:true,  scope, spec }
+function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR } = {}) {
+  if (status && status !== 'active') {
+    return { allowed: false, reason: 'BUILDER_INACTIVE' };
+  }
+  if (!rankMeetsBoxFloor(rank, floor)) {
+    return {
+      allowed: false,
+      reason: 'INSUFFICIENT_RANK',
+      required: floor,
+      actual: rank ?? null,
+    };
+  }
+  const scope = boxScopeForRank(rank);
+  return { allowed: true, scope, spec: cloneSpecForScope(scope) };
+}
+
+// ---------------------------------------------------------------------------
+// PURE: the clawback / reconcile decision (consumed by `box.js reconcile`)
+// ---------------------------------------------------------------------------
+
+// Given a box's CURRENT stored scope+state and the builder's LIVE rank+status,
+// what must the control plane do TO THE BOX ITSELF? (The credential layer is
+// already gated live on every fetch; this is the slower droplet-level cleanup.)
+//
+//   - no box (state none/destroyed)                 → 'none'   (nothing to do)
+//   - builder inactive, or rank below the floor      → 'deprovision'
+//        (the clawback: revoke rank → de-provision box → source access gone)
+//   - stored 'full' but live rank no longer Metic+   → 'deprovision'
+//        (a full box already holds the crown jewels on disk — it cannot be safely
+//         "downgraded" in place; destroy it, a fresh starter box can be provisioned)
+//   - stored 'starter' but live rank is now Metic+   → 'rescope' to 'full'
+//        (graduation: the next source-access fetch returns the full spec; the box
+//         re-clones on its refresh)
+//   - otherwise                                      → 'none'   (in sync)
+function reconcileSourceAccess({ boxScope, boxState, rank, status, floor = DEFAULT_PROVISION_FLOOR } = {}) {
+  const hasBox = boxState && boxState !== 'none' && boxState !== 'destroyed';
+  if (!hasBox) return { action: 'none', reason: 'no-box' };
+
+  if (status && status !== 'active') {
+    return { action: 'deprovision', reason: 'builder-inactive' };
+  }
+  if (!rankMeetsBoxFloor(rank, floor)) {
+    return { action: 'deprovision', reason: 'below-floor' };
+  }
+
+  const liveScope = boxScopeForRank(rank);
+  if (boxScope === 'full' && liveScope !== 'full') {
+    return { action: 'deprovision', reason: 'scope-downgrade-needs-fresh-box' };
+  }
+  if (boxScope === 'starter' && liveScope === 'full') {
+    return { action: 'rescope', reason: 'graduation', newScope: 'full' };
+  }
+  return { action: 'none', reason: 'in-sync' };
+}
+
+// ---------------------------------------------------------------------------
+// DB helpers (async; take the pg pool or a client)
+// ---------------------------------------------------------------------------
+
+// Roster of every box that currently has compute/snapshot state, joined to the
+// builder's LIVE rank+status — the input to `box.js reconcile`. Excludes 'none'
+// and 'destroyed' (nothing to reconcile). Distinct from boxes.listBoxes() because
+// reconcile MUST see `status` (a deactivated builder keeps rank='xenos' but
+// status='inactive', and the clawback turns on status, not just rank).
+async function listBoxesForReconcile(db) {
+  const { rows } = await db.query(
+    `SELECT bb.*, b.github_login, b.display_name, b.rank, b.status
+       FROM builder_boxes bb
+       JOIN builders b ON b.id = bb.builder_id
+      WHERE bb.state NOT IN ('none', 'destroyed')
+      ORDER BY bb.updated_at DESC
+      LIMIT 1000`
+  );
+  return rows;
+}
+
+// Append a source-access audit row to box_events (event vocabulary extends the
+// #598 set with: source_grant | source_deny | source_reconcile | source_rescope).
+// Thin wrapper over boxes.recordEvent so callers share ONE audit path.
+async function recordSourceEvent(db, { box, builderId, event, detail, actor }) {
+  await recordEvent(db, {
+    boxId: box.id,
+    builderId: builderId ?? box.builder_id ?? null,
+    event,
+    detail: detail ?? null,
+    actor: actor ?? null,
+  });
+}
+
+// Best-effort post-commit hook called by setBuilderRank / deactivateBuilder. Reads
+// the builder's box (if any) + the just-written live rank/status, computes the
+// reconcile action, and — when one is needed — writes a 'source_reconcile' audit
+// row so an operator (and `box.js reconcile`) has an immediate, queryable signal
+// that this rank/status change requires a box action. NEVER THROWS: it runs on its
+// own connection AFTER the rank-change transaction has committed, so a failure here
+// can never roll back the rank change (mirrors the fire-and-forget Discord broadcast).
+//
+// It does NOT itself touch DigitalOcean — the web process must never shell out to
+// the DO API (routes/box.js design); the actual deprovision/rescope is the control-
+// plane CLI's job. This is the signal + the audit trail, not the teardown.
+async function flagBoxReconcileForBuilder(db, builderId, { rank, status, floor = DEFAULT_PROVISION_FLOOR, actor = 'rank-change' } = {}) {
+  try {
+    const box = await getBoxByBuilderId(db, builderId);
+    if (!box) return { action: 'none', reason: 'no-box' };
+    const decision = reconcileSourceAccess({
+      boxScope: box.scope,
+      boxState: box.state,
+      rank,
+      status,
+      floor,
+    });
+    if (decision.action === 'none') return decision;
+    await recordSourceEvent(db, {
+      box,
+      builderId,
+      event: 'source_reconcile',
+      detail: `${decision.action}: ${decision.reason} (live rank=${rank ?? 'unknown'}, status=${status ?? 'unknown'})`,
+      actor,
+    });
+    return decision;
+  } catch (err) {
+    // Swallow — the rank change already committed; this is best-effort audit.
+    // eslint-disable-next-line no-console
+    console.error('[gds] flagBoxReconcileForBuilder (non-fatal)', err && err.message ? err.message : err);
+    return { action: 'error', reason: err && err.message ? err.message : String(err) };
+  }
+}
+
+module.exports = {
+  // pure — surface catalog
+  STARTER_SPARSE_PATHS,
+  SOURCE_HOLDING_STATES,
+  boxCanHoldSource,
+  cloneSpecForScope,
+  // pure — decisions
+  decideSourceAccess,
+  reconcileSourceAccess,
+  // db
+  listBoxesForReconcile,
+  recordSourceEvent,
+  flagBoxReconcileForBuilder,
+};

package/modules/dev-box/box-credential.js

@@ -0,0 +1,94 @@
+// src/bongos/box-credential.js — source-access credential PROVIDER (ADR 0031 §6, #600).
+//
+// A dev box holds NO permanent baked credential. It fetches a scope-appropriate
+// one from the GDS at boot/refresh (GET /box/source-access). This module is the
+// seam for "where that credential comes from", so the route never hardcodes a
+// secret and a future GitHub-App / fine-grained-PAT minter can slot in without
+// touching the route or the access decision.
+//
+// ADR 0022 (no secrets in the repo): the credential material lives in the PROD
+// ENVIRONMENT, never in this file or any committed file. When the env is unset the
+// provider returns { configured:false } and the route returns a spec with
+// credential:null + operator guidance — exactly the inert posture #598 ships with
+// (BOX_REPO_URL unset → the cloud-init logs guidance instead of cloning).
+//
+// DEFAULT PROVIDER: env-backed static tokens (operator-supplied), one per scope.
+//   BOX_SOURCE_REPO_URL          git remote the box clones (https://github.com/<org>/<repo>.git)
+//   BOX_SOURCE_FULL_TOKEN        credential a 'full' box embeds in the clone URL
+//   BOX_SOURCE_STARTER_TOKEN     credential a 'starter' box embeds (may equal full;
+//                                the SCOPE is then enforced by sparse-checkout + audit)
+//   BOX_SOURCE_STARTER_REPO_URL  OPTIONAL separate repo for the starter surface — set
+//                                this to make 'starter' a HARD boundary (a physically
+//                                separate repo that cannot read the crown jewels) rather
+//                                than the default sparse-checkout defense-in-depth
+//   BOX_SOURCE_TOKEN_TTL_SECONDS advisory TTL surfaced to the box so it re-fetches
+//                                (and thus re-checks live rank — where revocation bites);
+//                                default 3600 (1h)
+//
+// The env-static token is a STOPGAP: a static token is not truly short-lived, so
+// central revocation for it relies on the box's refresh cron re-fetching, getting a
+// 403 once the builder is demoted, and scrubbing the local credential+clone
+// (infra/box-source-fetch.sh does this). A minting provider that returns genuinely
+// short-lived tokens is the intended upgrade; the { expiresAt } field already models it.
+
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+
+// Build the env-backed provider. Injectable env (for tests) defaulting to
+// process.env. Returns { issue(scope, ctx) } where issue() is pure w.r.t. the
+// captured env snapshot (no I/O), returning the credential descriptor for a scope.
+function makeEnvCredentialProvider(env = process.env) {
+  const ttl = (() => {
+    const v = env.BOX_SOURCE_TOKEN_TTL_SECONDS;
+    const n = v == null || v === '' ? DEFAULT_TOKEN_TTL_SECONDS : Number(v);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TOKEN_TTL_SECONDS;
+  })();
+
+  function issue(scope /* 'starter' | 'full' */, { nowMs } = {}) {
+    const fullUrl = env.BOX_SOURCE_REPO_URL || null;
+    const starterUrl = env.BOX_SOURCE_STARTER_REPO_URL || fullUrl;
+    const repoUrl = scope === 'full' ? fullUrl : starterUrl;
+    const token = scope === 'full'
+      ? (env.BOX_SOURCE_FULL_TOKEN || null)
+      : (env.BOX_SOURCE_STARTER_TOKEN || env.BOX_SOURCE_FULL_TOKEN || null);
+
+    if (!repoUrl || !token) {
+      return {
+        configured: false,
+        scope,
+        repoUrl: repoUrl || null,
+        token: null,
+        expiresAt: null,
+        // A separate starter repo means the boundary is HARD (not just sparse).
+        separateStarterRepo: scope !== 'full' && !!env.BOX_SOURCE_STARTER_REPO_URL,
+        guidance:
+          'source-access credential not configured — set BOX_SOURCE_REPO_URL and ' +
+          (scope === 'full' ? 'BOX_SOURCE_FULL_TOKEN' : 'BOX_SOURCE_STARTER_TOKEN (or BOX_SOURCE_FULL_TOKEN)') +
+          ' in the prod env (never the repo — ADR 0022).',
+      };
+    }
+    // expiresAt is advisory for the env-static token (the token itself does not
+    // expire); it tells the box WHEN to re-fetch, which re-checks live rank.
+    const base = Number.isFinite(nowMs) ? nowMs : null;
+    return {
+      configured: true,
+      scope,
+      repoUrl,
+      token,
+      ttlSeconds: ttl,
+      expiresAt: base != null ? new Date(base + ttl * 1000).toISOString() : null,
+      separateStarterRepo: scope !== 'full' && !!env.BOX_SOURCE_STARTER_REPO_URL,
+      guidance: null,
+    };
+  }
+
+  return { issue };
+}
+
+// The process-default provider (reads the live process.env).
+const defaultProvider = makeEnvCredentialProvider();
+
+module.exports = {
+  DEFAULT_TOKEN_TTL_SECONDS,
+  makeEnvCredentialProvider,
+  defaultProvider,
+};