@bongos/core 1.17.0

package/src/bongos/routes/security.js

@@ -0,0 +1,207 @@
+// src/bongos/routes/security.js — security-the-PROPERTY surfaces (kernel side).
+//
+// What stays here (02-module-map §5 — security-the-PROPERTY, NOT the feature):
+//   • GET /security/adr — the full security ADR (Metic+), read off the droplet.
+//   • GET/POST /security/docs — the Archon-only exploit-detail engagement-report
+//     store (backed by the core db.js security_docs queries, task 991).
+//
+// The FEATURE half — the red-team / vulnerability reports + bounty intake &
+// adjudication (V3.R63-R66 / #282-285) — carved out to modules/security/ in
+// BV1.R79 (ADR 0093 §1); the loader mounts modules/security/routes/reports.js,
+// and core's /public/bounty-table resolves the `security` kernel port it
+// registers (no core require of the module).
+//
+// The public ADR stub lives in docs/adr/0020-security-model-public-stub.md; the
+// *real* document lives at the path named by env GDS_SECURITY_ADR_PATH on the
+// droplet (NOT in the repo) so the most attacker-useful document doesn't get
+// committed to a public surface. See ADR 0020 for the reasoning.
+
+const express = require('express');
+const fs = require('node:fs/promises');
+const auth = require('../auth');
+const db = require('../db');
+const { validateOrRespond } = require('./_helpers');
+
+// Slug shape for security_docs (task 991): lowercase kebab, 1–128 chars. Used to
+// validate POST /security/docs and to safely interpolate :slug into the GET.
+const SECURITY_DOC_SLUG_RE = /^[a-z0-9-]{1,128}$/;
+
+// content_md is a full-report store, NOT a task/report field — so it gets its
+// own explicit large cap, deliberately well above LIMITS.DESCRIPTION (50k). A
+// dated engagement report runs tens of KB; 2 MB leaves generous headroom while
+// still bounding a runaway upload.
+const SECURITY_DOC_CONTENT_MAX = 2_000_000;
+
+// Where the full ADR is expected to live on the droplet. Configurable so dev /
+// staging can point at a different file; the recommended prod path is
+// /etc/amazonprimea/security-adr.md (chmod 600, owned by the deploy user).
+function adrPath() {
+  return (process.env.GDS_SECURITY_ADR_PATH || '').trim() || null;
+}
+
+// Read the full ADR off disk. Returns { adr_md, source, fetched_at } on
+// success, or null if the env var isn't set or the file isn't readable.
+// Errors are swallowed (and console.error'd) — a missing/unreadable file
+// surfaces to the caller as a 404, not a 500, because file-not-found is the
+// expected unprovisioned state, not an internal failure. We DO distinguish
+// "env not set" (configuration bug) from "file unreadable" (probably perms /
+// not yet provisioned) in the hint string returned to the caller.
+async function readFullAdr() {
+  const p = adrPath();
+  if (!p) {
+    return { ok: false, reason: 'env_not_set' };
+  }
+  try {
+    const buf = await fs.readFile(p, 'utf8');
+    return {
+      ok: true,
+      payload: {
+        adr_md: buf,
+        source: p,
+        fetched_at: new Date().toISOString(),
+      },
+    };
+  } catch (err) {
+    // Treat ENOENT, EACCES, etc. uniformly — the caller (Metic+) doesn't need
+    // to debug the droplet's filesystem from the API response. Log details
+    // server-side for the operator.
+    console.error('[gds] /security/adr read failed:', err.code || err.message);
+    return { ok: false, reason: 'file_unreadable', code: err.code || null };
+  }
+}
+
+module.exports = function buildSecurityRouter() {
+  const router = express.Router();
+
+  // GET /api/gds/security/adr
+  //
+  // Metic+ only. Returns the full security ADR as { adr_md, source,
+  // fetched_at } when the file is provisioned; otherwise 404 with a
+  // structured hint. The rank gate runs BEFORE the file-existence check so a
+  // Xenos sees 403 regardless of whether the document is provisioned — we
+  // don't want existence-or-not to leak below the rank line.
+  //
+  // rank: metic+archon — trust-tier access to the threat model + defenses
+  // inventory (ADR 0020).
+  router.get(
+    '/security/adr',
+    auth.requireBuilder,
+    auth.requireRank('metic', 'archon'),
+    async (_req, res) => {
+      const result = await readFullAdr();
+      if (result.ok) {
+        // No caching — the full ADR is the live document; treating it as
+        // cacheable would invite a stale-defense problem after a defense
+        // update. Cost is trivial (one disk read per Metic request).
+        res.set('Cache-Control', 'no-store');
+        return res.json(result.payload);
+      }
+      const hint =
+        result.reason === 'env_not_set'
+          ? 'GDS_SECURITY_ADR_PATH is unset on the server; an Archon must provision the file and the env var.'
+          : 'GDS_SECURITY_ADR_PATH is set but the file is unreadable (missing, wrong perms, or wrong path).';
+      return res.fail('security_adr_not_provisioned', 404, { reason: result.reason, hint });
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // Security engagement docs — Archon-only document store (task 991).
+  //
+  // The DATED security engagement reports (exploit detail — full repro,
+  // evidence, the attacker cookbook) are served from the DB, NOT committed to
+  // the git clone: the repo is cloned in full onto every Metic+ dev box
+  // (threat-model §6.3 / ADR 0020), so a committed exploit report is an
+  // attacker cookbook on every box. The SAFE conceptual docs (threat-model.md,
+  // the README) stay in docs/security/; only the dated reports live here, and
+  // ALL three routes are requireRank('archon') because they serve exploit
+  // detail. Content is uploaded by the director via the POST route after
+  // deploy — no exploit content ever touches the repo.
+  // -----------------------------------------------------------------------
+
+  // GET /api/gds/security/docs — list doc METADATA (no content).
+  //
+  // rank: archon — index of exploit-detail engagement reports.
+  router.get('/security/docs',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    async (_req, res) => {
+      try {
+        const docs = await db.listSecurityDocs();
+        res.set('Cache-Control', 'no-store');
+        res.json({ docs });
+      } catch (err) {
+        console.error('[gds] GET /security/docs', err);
+        res.fail('list_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  // GET /api/gds/security/docs/:slug — one doc WITH content, or 404.
+  //
+  // rank: archon — reads the full exploit-detail report body.
+  router.get('/security/docs/:slug',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    async (req, res) => {
+      const slug = String(req.params.slug || '');
+      if (!SECURITY_DOC_SLUG_RE.test(slug)) {
+        return res.fail('bad_slug', 400, { pattern: SECURITY_DOC_SLUG_RE.source });
+      }
+      try {
+        const doc = await db.getSecurityDoc(slug);
+        if (!doc) {
+          return res.fail('security_doc_not_found', 404, { slug });
+        }
+        res.set('Cache-Control', 'no-store');
+        res.json({
+          doc: {
+            slug: doc.slug,
+            title: doc.title,
+            content_md: doc.content_md,
+            updated_at: doc.updated_at,
+          },
+        });
+      } catch (err) {
+        console.error('[gds] GET /security/docs/:slug', err);
+        res.fail('get_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  // POST /api/gds/security/docs — upsert a doc by slug. The director uploads
+  // each dated engagement report here after deploy.
+  //
+  // Body: { slug, title, content_md }. content_md uses a large explicit cap
+  // (full reports), NOT the small LIMITS.DESCRIPTION. Returns 201 + the row.
+  //
+  // rank: archon — writes exploit-detail report bodies.
+  router.post('/security/docs',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        slug:       { required: true, type: 'string', maxLength: 128, minLength: 1 },
+        title:      { required: true, type: 'string', maxLength: 200, minLength: 1 },
+        content_md: { required: true, type: 'string', maxLength: SECURITY_DOC_CONTENT_MAX, minLength: 1 },
+      })) return;
+      const { slug, title, content_md: contentMd } = req.body || {};
+      // Slug needs the exact kebab shape on top of the length check — the
+      // length-only validator above can't express the character class.
+      if (!SECURITY_DOC_SLUG_RE.test(slug)) {
+        return res.fail('bad_slug', 400, { pattern: SECURITY_DOC_SLUG_RE.source });
+      }
+      try {
+        const row = await db.upsertSecurityDoc({ slug, title, contentMd });
+        res.status(201).json({ ok: true, doc: row });
+      } catch (err) {
+        console.error('[gds] POST /security/docs', err);
+        res.fail('upsert_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  return router;
+};
+
+// Exposed for the test suite — pure helpers, no router state.
+module.exports._internals = { adrPath, readFullAdr };

package/src/bongos/routes.js

@@ -0,0 +1,166 @@
+// GDS HTTP routes — mounted at /api/bongos (canonical) + /api/gds (permanent
+// alias); serve-internal.js dual-mounts this router at both (src/bongos/api-prefix.js).
+// Historical: the older /api/pms surface was removed in V3.R01-followup (#308) — it
+// now 404s (not a redirect).
+//
+// This file is a thin mounter. Each feature owns its own sub-router under
+// src/bongos/routes/. Adding a new feature = create one new file there + add one
+// line below. That's the whole point: keep routes.js conflict-free across
+// parallel branches.
+//
+// Three logical groups:
+//   - /auth/*   — GitHub Device Flow (CLI) + Authorization Code (web)
+//   - /me, /tasks/*, /claims/*, /cost/*, /credits/*, ...  — authenticated CLI/web ops
+//   - /public/* — read-only, no auth, for status.amazonprimea.com
+//
+// All JSON. Same Express app as the game server.
+
+const express = require('express');
+
+const buildHealthzRouter = require('./routes/healthz');
+const buildInstanceRouter = require('./routes/instance');
+const buildAuthRouter = require('./routes/auth');
+const buildMeRouter = require('./routes/me');
+const buildBuildersRouter = require('./routes/builders');
+// The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
+// dependencies · gate-approvals · analytics) carved into modules/lifecycle/
+// (BV1.R86 / ADR 0093 §1,§3); moduleLoader.mountModuleRoutes (below) mounts them
+// via the lifecycle module's route factories — no core require. The `/tasks/:id/
+// publish-branch` body-parser bypass below STAYS (the route carries its own larger
+// express.json, exactly like memory's /memory/sync — the moved route mounts AFTER
+// the global parser middleware runs, so the by-path skip still fires).
+// cost + leaderboard routes carved into modules/economy/ (BV1.R77 / ADR 0093
+// §1-2); moduleLoader.mountModuleRoutes (below) mounts them now — no core require.
+// autonomy precheck route carved into modules/autonomy/ (BV1.R83 / ADR 0093 §1);
+// moduleLoader.mountModuleRoutes (below) mounts it now — no core require.
+// inbox + blockers routes carved into modules/ideas/ (BV1.R78 / ADR 0093 §1);
+// memory/search/learnings routes carved into modules/memory/ (BV1.R72 / ADR 0091
+// §2); moduleLoader.mountModuleRoutes (below) mounts both now — no core require.
+const buildOptimizerRouter = require('./routes/optimizer');
+const buildBackupRouter = require('./routes/backup');
+const buildPublicRouter = require('./routes/public');
+const buildAuditLogRouter = require('./routes/audit-log');
+// security router: now the PROPERTY half only (/security/adr + /security/docs).
+// The red-team-reports + bounty FEATURE carved to modules/security/ (BV1.R79 /
+// ADR 0093 §1); moduleLoader.mountModuleRoutes (below) mounts those — no core
+// require. (02-module-map §5: security-the-property stays kernel.)
+const buildSecurityRouter = require('./routes/security');
+// The hall "Modules" tab (ADR 0107 §9, task 1776) — list/enable/disable +
+// the submit-for-review front door. Core (not module-owned): it manages
+// EVERY module's enablement, including modules it must not import.
+const buildModulesRouter = require('./routes/modules');
+// The access-request ADMISSION routes carved to modules/onboarding/ (BV1.R81 /
+// ADR 0093 §1); moduleLoader.mountModuleRoutes (below) mounts them via the
+// onboarding module's route factory — no core require.
+// The session-records data plane (POST /sessions + the BFG search/deep-dive)
+// carved to modules/sessions/ (BV1.R82 / ADR 0093 §1); moduleLoader.mountModuleRoutes
+// (below) mounts it via the sessions module's route factory — no core require.
+// The `/sessions` global-parser bypass below STAYS (the module router carries
+// its own larger express.json, exactly like memory's /memory/sync).
+const buildLiveRouter = require('./routes/live');
+const buildLlmCacheRouter = require('./routes/llm-cache');
+const { isModuleEnabled } = require('../modules');
+const moduleLoader = require('../module-loader/loader');
+const { auditMiddleware } = require('./middleware/audit');
+const { rateLimitMiddleware } = require('./middleware/rate-limit');
+const { attachFail, errorEnvelopeHandler } = require('./middleware/error-envelope');
+
+function buildGdsRouter() {
+  const router = express.Router();
+  // Global JSON body parser, 64 KB — the right cap for every GDS write EXCEPT
+  // memory sync (#274), whose body batches up to 1 MB markdown files. We skip
+  // that one path here so the memory router's own larger express.json (in
+  // routes/memory.js) is the only parser that runs for it; every other route
+  // keeps the tight 64 KB cap. Without this skip the global parser would 413
+  // a large memory-sync body before the route-scoped parser could see it.
+  const globalJson = express.json({ limit: '64kb' });
+  router.use((req, res, next) => {
+    // These paths carry larger bodies (memory markdown batches; session digests
+    // — 6D.1 / ADR 0027; server-mediated branch publish bundles — ADR 0055) and
+    // mount their OWN express.json in their routers. Skip the tight global cap so
+    // it doesn't 413 the body before the route parser runs. The publish path
+    // carries a dynamic :id, so it's matched by pattern, not equality.
+    if (
+      req.path === '/memory/sync' ||
+      req.path === '/sessions' ||
+      req.path === '/llm-cache/store' ||
+      /^\/tasks\/\d+\/publish-branch$/.test(req.path)
+    ) return next();
+    return globalJson(req, res, next);
+  });
+
+  // Audit middleware (V3.R35 #256) — attaches a res 'finish' hook so every
+  // authenticated POST/PATCH/PUT/DELETE under /api/gds is recorded in
+  // audit_log AFTER the response is sent. It cannot fail the request: throws
+  // are caught, DB errors are swallowed, and it never mutates req/res in a
+  // way downstream handlers can see. Mounted BEFORE the feature routers so
+  // the hook is attached early; the actual write fires only on 'finish'.
+  //
+  // Order matters: audit runs first (attaches the finish hook), then rate-
+  // limit decides allow/deny. A 429 still fires the audit hook on 'finish',
+  // so the forensic record of throttled attempts is intact (pairs with R36).
+  // Error-envelope decorator (BV1 R02 / task 1989 / ADR 0116) — hangs
+  // res.fail(code, status?, details?) on every response so handlers emit the
+  // one canonical envelope. Mounted before the feature routers so all of them
+  // (and the trailing error handler) can rely on it. Adds a method; touches no
+  // existing response — the R04 sweep migrates handlers onto it incrementally.
+  router.use(attachFail);
+
+  router.use(auditMiddleware());
+
+  // Rate-limit middleware (V3.R34 #255) — sliding-window in-memory limiter.
+  // 30 writes/min per IP, 60 writes/min per session. Reads uncapped.
+  // 429 + Retry-After + X-RateLimit-* headers on trip.
+  router.use(rateLimitMiddleware);
+
+  router.use(buildHealthzRouter());
+  router.use(buildInstanceRouter());
+  router.use(buildAuthRouter());
+  router.use(buildMeRouter());
+  router.use(buildBuildersRouter());
+  // tasks · claims · versions · done-when · goals · dependencies · analytics now
+  // mount via moduleLoader.mountModuleRoutes below (lifecycle module, BV1.R86) —
+  // BEFORE the public router, so their paths are byte-identical.
+  router.use(buildOptimizerRouter());
+  router.use(buildBackupRouter());
+  router.use(buildAuditLogRouter());
+  router.use(buildSecurityRouter());
+  router.use(buildModulesRouter());
+  // access-requests (admission) is now mounted by the onboarding module via
+  // moduleLoader.mountModuleRoutes below (BV1.R81) — still BEFORE the public
+  // router, so its paths are byte-identical. The /sessions data plane is
+  // likewise mounted by the sessions module (BV1.R82) via mountModuleRoutes.
+  // R55 (task 1194 / ADR 0069): the hall's live-update SSE channel. Mounted
+  // UNCONDITIONALLY (not module-gated) — it replaces the Colyseus builders_hall
+  // room so the hall refreshes live on a game-less Cloud Bongos boot, which is
+  // core to every instance, not an OTB feature.
+  router.use(buildLiveRouter());
+  // Feature-module-gated mounts (R54, task 1193, ADR 0062 §4). Off on a vanilla
+  // instance; ON for OTB via config/modules.json so prod is unchanged. dev-box,
+  // art-pipeline, and discord (with its bug-attachments route) have all graduated
+  // into real modules (modules/<key>/) — they are discovered + mounted by
+  // moduleLoader.mountModuleRoutes below, not here (BV1.R43 / R48 / R47 / R72).
+  // gate-approvals likewise moved to the lifecycle module (BV1.R86).
+  router.use(buildLlmCacheRouter());
+
+  // Loader-mounted module routers (ADR 0083 / BV1.R41). Discovers + mounts every
+  // ENABLED module under modules/*/ behind the kernel's audit + rate-limit (already
+  // applied above); each module's route factory self-gates per route (enforced by
+  // the route-rank fitness check, BV1.R44). No-op until a module is moved into
+  // modules/ — so OTB is byte-identical today. Mounted BEFORE the public router so
+  // the public catch-all prefixes can't shadow a module's routes.
+  moduleLoader.mountModuleRoutes(router, { isEnabled: isModuleEnabled });
+
+  router.use(buildPublicRouter());
+
+  // Central error handler (BV1 R02 / task 1989 / ADR 0116) — MUST be last, after
+  // every feature + module router. The safety net: a thrown ApiError, any
+  // next(err), and body-parser failures (malformed JSON / oversized body) all
+  // come out as the R01 envelope instead of Express's default error page. A
+  // handler that already responded is untouched (res.headersSent short-circuits).
+  router.use(errorEnvelopeHandler);
+
+  return router;
+}
+
+module.exports = { buildGdsRouter };

package/src/bongos/secret-box.js

@@ -0,0 +1,177 @@
+// src/bongos/secret-box.js — small AES-256-GCM box for per-builder secrets at rest.
+//
+// First (and only) consumer today: the per-builder Gemini key (task 1013 / ADR
+// 0071). The key is stored ENCRYPTED on `builders.gemini_key_enc`; the master
+// key lives ONLY in server env (BUILDER_SECRET_KEY) — never in the DB and never
+// in the repo — so a database dump alone cannot decrypt anything. This is the
+// containment for the one new risk pragmatic BYOK introduces (the server holding
+// N builder keys so it can sync them down to each builder's own box).
+//
+// Master key resolution mirrors loadSharedGeminiKey() in art-key.js / the Discord
+// loaders in auth.js — env wins, else a local 0600 file for dev:
+//   1. process.env.BUILDER_SECRET_KEY            (systemd EnvironmentFile on the droplet)
+//   2. ~/.config/otb/builder-secret.key          (single-line key, local dev / operator)
+// The value is 32 bytes encoded as 64 hex chars OR base64 (standard or url). A
+// value of any other decoded length is treated as "not configured" (logged once)
+// so a malformed secret fails CLOSED — set/decrypt is disabled, never weak.
+//
+// Blob format (a single opaque string stored in one text column):
+//   v1.<iv_b64url>.<tag_b64url>.<ciphertext_b64url>
+// iv = 12 random bytes (GCM standard); tag = 16-byte GCM auth tag. The version
+// prefix lets us rotate the scheme later without guessing.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const ic = require('../instance-config');
+
+const VERSION = 'v1';
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+
+// The operator-file source (source #2 in loadMasterKey). On the prod droplet
+// this is where the productized provisioning (task 1398) writes the generated
+// master key — beside the other instance-config state, surviving restarts.
+// Routed through instance-config (R61 / task 1200) so the write path is EXACTLY
+// what loadMasterKey() reads via ic.readConfigFileSync, and so a non-OTB instance
+// uses its own configured dir rather than a hard-coded ~/.config/otb.
+function masterKeyFile() {
+  return ic.configPath('builder-secret.key');
+}
+
+let _warnedBadKey = false;
+
+// Decode a 32-byte master key from hex or base64. Returns a Buffer or null.
+function decodeMasterKey(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const s = raw.trim();
+  if (!s) return null;
+  // 64 hex chars → 32 bytes.
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return Buffer.from(s, 'hex');
+  // Otherwise try base64 / base64url.
+  try {
+    const buf = Buffer.from(s, 'base64');
+    if (buf.length === KEY_BYTES) return buf;
+  } catch (_) { /* fall through */ }
+  return null;
+}
+
+// Load the master key from env, then the local operator file. Returns Buffer|null.
+function loadMasterKey() {
+  const fromEnv = decodeMasterKey(process.env.BUILDER_SECRET_KEY);
+  if (fromEnv) return fromEnv;
+  // A set-but-malformed env value is an operator mistake worth one loud line —
+  // but we still fail closed (return null) rather than fall back to something weak.
+  if (process.env.BUILDER_SECRET_KEY && !_warnedBadKey) {
+    _warnedBadKey = true;
+    console.error('[gds] BUILDER_SECRET_KEY is set but is not a 32-byte hex/base64 value — secret storage disabled until fixed.');
+  }
+  try {
+    const raw = ic.readConfigFileSync('builder-secret.key');
+    const fromFile = raw && decodeMasterKey(raw);
+    if (fromFile) return fromFile;
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+// Is the server able to encrypt/decrypt? (i.e. is a valid master key present?)
+// The set-key route 503s when this is false, so the feature stays dark until an
+// operator provisions BUILDER_SECRET_KEY — exactly the shared-key rollout shape.
+function isConfigured() {
+  return !!loadMasterKey();
+}
+
+// provisionMasterKey — generate + persist a master key so the per-builder key
+// feature can turn on WITHOUT a human hand-editing prod secrets (task 1398, the
+// productized fix for blocker 41). The server generates 32 crypto-random bytes
+// and writes them (hex) to the operator file as 0600.
+//
+// SAFETY — this MUST be idempotent and MUST NEVER overwrite an existing key: the
+// master key decrypts every stored builder secret, so regenerating it would brick
+// them all. So:
+//   1. If a valid key already resolves (env or file) → no-op, report it.
+//   2. Otherwise create the file with the `wx` flag (exclusive): if a file is
+//      already present (even a malformed one) the write fails EEXIST and we
+//      REFUSE rather than clobber — that case needs an operator, not a silent
+//      overwrite.
+// `opts` (file/env) exist only so the unit test can drive it against a temp path
+// without touching the real ~/.config/otb; production calls it with no args.
+function provisionMasterKey(opts = {}) {
+  const file = opts.file || masterKeyFile();
+  const env = opts.env !== undefined ? opts.env : process.env.BUILDER_SECRET_KEY;
+  if (decodeMasterKey(env)) return { ok: true, created: false, reason: 'already_configured_env' };
+  try {
+    if (decodeMasterKey(fs.readFileSync(file, 'utf8'))) {
+      return { ok: true, created: false, reason: 'already_configured_file' };
+    }
+  } catch (_) { /* no readable file yet — fall through to create */ }
+
+  const key = crypto.randomBytes(KEY_BYTES).toString('hex'); // 64 hex chars = 32 bytes
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${key}\n`, { flag: 'wx', mode: 0o600 }); // wx = fail if it exists
+  } catch (e) {
+    if (e && e.code === 'EEXIST') {
+      // A file is already there but didn't decode as a valid key. Do NOT clobber
+      // it — it may be a real key our process just can't read. Operator must look.
+      return { ok: false, error: 'key_file_exists_but_invalid' };
+    }
+    return { ok: false, error: (e && (e.code || e.message)) || 'write_failed' };
+  }
+  try { fs.chmodSync(file, 0o600); } catch (_) { /* best-effort tighten */ }
+  return { ok: true, created: true };
+}
+
+function b64url(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromB64url(str) {
+  return Buffer.from(str.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+
+// Encrypt a UTF-8 plaintext → the opaque "v1.iv.tag.ct" blob. Throws if the
+// master key isn't configured (callers gate on isConfigured() first).
+function encrypt(plaintext) {
+  if (typeof plaintext !== 'string' || plaintext.length === 0) {
+    throw new Error('secret-box.encrypt: plaintext must be a non-empty string');
+  }
+  const key = loadMasterKey();
+  if (!key) throw new Error('secret-box: master key not configured');
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [VERSION, b64url(iv), b64url(tag), b64url(ct)].join('.');
+}
+
+// Decrypt a blob produced by encrypt() → the UTF-8 plaintext. Throws on a bad
+// format, a missing master key, or a failed auth tag (tamper / wrong key).
+function decrypt(blob) {
+  if (typeof blob !== 'string' || !blob) throw new Error('secret-box.decrypt: empty blob');
+  const parts = blob.split('.');
+  if (parts.length !== 4 || parts[0] !== VERSION) {
+    throw new Error('secret-box.decrypt: unrecognized blob format');
+  }
+  const key = loadMasterKey();
+  if (!key) throw new Error('secret-box: master key not configured');
+  const iv = fromB64url(parts[1]);
+  const tag = fromB64url(parts[2]);
+  const ct = fromB64url(parts[3]);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  const out = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return out.toString('utf8');
+}
+
+module.exports = {
+  VERSION,
+  masterKeyFile,
+  isConfigured,
+  provisionMasterKey,
+  encrypt,
+  decrypt,
+  // exported for tests
+  decodeMasterKey,
+};

package/src/bongos/sensitive-surfaces.js

@@ -0,0 +1,30 @@
+// MAS — single source of truth for the security-relevant file surfaces the
+// system watches. Used by BOTH the Conductor hook (.claude/hooks/conductor.js,
+// to decide when to dispatch the Hacker) and the dispatcher CLI
+// (scripts/gds/conductor-dispatch.js, for `auto` specialist selection).
+//
+// Defined ONCE here so the two can't drift — the Phase 4 dogfood (#439) had
+// the Hacker AND Quality workers independently flag that the set was
+// hand-copied into both files, and that a drift would silently suppress
+// auto-dispatch for a newly-unrecognized surface. This module removes that
+// whole class of bug.
+//
+// Matched against repo-relative POSIX paths.
+
+const SENSITIVE_SURFACES = [
+  { re: /^migrations\//, label: 'migrations/' },
+  { re: /^src\/bongos\/routes\//, label: 'src/bongos/routes/' },
+  { re: /(^|\/)auth\.js$/, label: 'auth' },
+  { re: /(^|\/)server\.js$/, label: 'server.js' },
+  { re: /(^|\/)Caddyfile$/, label: 'Caddyfile' },
+  // This file itself: editing the security-surface definitions IS a
+  // security-relevant change, so a change here self-triggers a Hacker review
+  // (the panel flagged on #439 that the defs file was conspicuously absent).
+  { re: /(^|\/)sensitive-surfaces\.js$/, label: 'security-surface-defs' },
+];
+
+function isSensitive(file) {
+  return SENSITIVE_SURFACES.some((s) => s.re.test(file));
+}
+
+module.exports = { SENSITIVE_SURFACES, isSensitive };