@bongos/core 1.17.0

package/src/bongos/routes/instance.js

@@ -0,0 +1,129 @@
+// src/bongos/routes/instance.js — GET /api/gds/instance (V4.R82, task 1249, ADR 0062 / Cloud Bongos C8).
+//
+// The instance manifest: one public, pre-auth, read-only descriptor that a CLI
+// (`bongos login <url>`) fetches to configure ITSELF — the conda
+// "environment.yml" of a Cloud Bongos instance. It assembles, from sources that
+// already exist, the answer to "what is this instance, and what does it do?":
+//
+//   * name + brand          — the R53 branding contract (client-safe projection)
+//   * modules + disciplines  — the R54 feature-module flags
+//   * rank ladder            — the canonical live tiers + the instance's labels
+//   * repo binding           — the GitHub owner/repo for `--local` clones
+//   * auth methods           — how a stranger signs in (device-flow / web / app-pair)
+//   * admission policy        — invite-only vs open self-enrollment
+//   * dev-box availability    — whether the managed cloud-box backend is on
+//
+// WHY THIS EXISTS: GET /healthz returns only { ok, auth_configured } — too thin
+// for a CLI to brand + feature-gate itself (e.g. hide the `box` verb on an
+// instance that runs no dev-box module). This is the richer public descriptor
+// that gap calls for.
+//
+// SECURITY (no secrets / no topology): the manifest is assembled ONLY from
+// already-client-safe projections — clientBranding() (the documented allow-list
+// that excludes origins, db name, env prefix) and clientModules() (booleans) —
+// plus loadRepoInfo()'s owner/repo/branch, which is ALREADY published on the
+// open web by the primer's GitHub link rewriter. It exposes no cookie/OAuth
+// hosts, no DB name, no env prefix, no tokens. The assembler (buildInstanceManifest)
+// is PURE — all inputs injected — so a unit test proves the shape + the no-leak
+// guarantee with zero I/O (mirrors resolveBranding/resolveModules, ADR 0062 §3/§4).
+
+const express = require('express');
+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 { RANK_TIER } = require('../permission-path-check');
+
+// The manifest format id — bumped when the SHAPE changes so a CLI can detect a
+// too-new server. Deliberately neutral (no instance/platform identity literal).
+const MANIFEST_SCHEMA = 'instance-manifest/v1';
+
+// Supported sign-in methods. All require GitHub auth to be configured (the
+// server holds the OAuth client creds): device-flow = the CLI Device Flow;
+// web = the browsers' hall sign-in (completeWebFlow); app-pair = the Dev Box
+// desktop app's browser-clicks-only pairing (/auth/app-pair/*). All three mount
+// unconditionally in routes/auth.js, so configured-ness is the only gate.
+const AUTH_METHODS = ['device-flow', 'web', 'app-pair'];
+
+// buildInstanceManifest — PURE assembler. Every input is injected so this is
+// unit-testable without disk, DB, or git. Inputs are the CLIENT-SAFE projections
+// (branding = clientBranding() output, modules = clientModules() output), the
+// canonical rank-tier map, loadRepoInfo()'s result, and three booleans. Returns
+// the JSON body verbatim.
+function buildInstanceManifest({
+  branding,
+  modules,
+  rankTier = RANK_TIER,
+  repo,
+  authConfigured: authOk,
+  openEnrollment,
+  devBoxEnabled,
+} = {}) {
+  const b = branding || {};
+  const rankLabels = b.rankLabels || {};
+
+  // Ladder ordered entry→top from the tier map (single source of truth — mirrors
+  // RANK_TIER in permission-path-check.js / REQUIRES_RANK_TIER in db.js), labelled
+  // from the instance's brand. A rank with no configured label falls back to its key.
+  const ranks = Object.entries(rankTier || {})
+    .sort((a, c) => a[1] - c[1])
+    .map(([key, tier]) => ({ key, tier, label: rankLabels[key] || key }));
+
+  // Repo binding for `--local`: project to the public clone coordinates only.
+  // loadRepoInfo() returns { error } when neither git nor env resolves a remote.
+  const repoOut = repo && !repo.error
+    ? {
+        owner: repo.owner,
+        repo: repo.repo,
+        branch: repo.branch,
+        url: `https://github.com/${repo.owner}/${repo.repo}`,
+      }
+    : null;
+
+  return {
+    schema: MANIFEST_SCHEMA,
+    name: b.identity?.productName || '',
+    brand: b,
+    modules: modules || {},
+    ranks,
+    repo: repoOut,
+    auth: {
+      methods: authOk ? AUTH_METHODS.slice() : [],
+      configured: !!authOk,
+    },
+    admission: { policy: openEnrollment ? 'open' : 'invite-only' },
+    devBox: { available: !!devBoxEnabled },
+  };
+}
+
+module.exports = function buildInstanceRouter() {
+  const router = express.Router();
+
+  // CORS for the unauthenticated cross-origin read (same posture as /public/*
+  // and /healthz — a CLI / status page fetches this before any session exists).
+  router.use('/instance', corsPublicGet('/instance'));
+
+  // rank: public — the instance descriptor; pre-auth by design (a stranger
+  // fetches it to learn how to sign in). asyncHandler returns a 500 with no
+  // err.message if branding/modules fail to resolve (misconfigured instance) —
+  // never leaks internals.
+  router.get('/instance', asyncHandler('GET /instance', (_req, res) => {
+    res.json(buildInstanceManifest({
+      branding: clientBranding(),
+      modules: clientModules(),
+      rankTier: RANK_TIER,
+      repo: loadRepoInfo(),
+      authConfigured: authConfigured(),
+      openEnrollment: openEnrollmentEnabled(),
+      devBoxEnabled: isModuleEnabled('dev-box'),
+    }));
+  }, { message: false, errorCode: 'instance_manifest_failed' }));
+
+  return router;
+};
+
+// Exported for unit tests (the pure assembler) + the schema/auth constants.
+module.exports.buildInstanceManifest = buildInstanceManifest;
+module.exports.MANIFEST_SCHEMA = MANIFEST_SCHEMA;
+module.exports.AUTH_METHODS = AUTH_METHODS;

package/src/bongos/routes/live.js

@@ -0,0 +1,125 @@
+// src/bongos/routes/live.js — the builders' hall live-update channel as
+// Server-Sent Events (R55, task 1194 / ADR 0069).
+//
+// Supersedes the Colyseus `builders_hall` room (ADR 0030 chose WebSocket purely
+// to reuse the game's existing Colyseus stack). A Cloud Bongos instance that
+// runs the GDS WITHOUT the game (src/platform-server.js) has no Colyseus in the
+// process, so the room — and therefore the hall's only live feature — was dead
+// there. SSE is the textbook fit for a receive-only dashboard (plain HTTP GET,
+// no client lib, native auto-reconnect in EventSource) and, living in the GDS
+// router, it mounts in BOTH entrypoints (server.js + platform-server.js), so the
+// hall refreshes itself on a game-less boot. ADR 0030 even notes SSE "was
+// initially built" and rejected only for the WS-reuse argument that R55 removes.
+//
+// The change-signal layer is UNCHANGED: this subscribes to the same pg NOTIFY
+// relay (live-channel.js) the room subscribed to, and emits the same opaque
+// `nudge` — NO row data, NOT even the relay's {table, op} (leaking internal
+// table names would be a schema-disclosure oracle; the hacker dispatch on #569).
+// The hall re-runs its authenticated per-panel fetches on any nudge, so the
+// empty signal costs nothing and access control stays where the data is.
+
+const express = require('express');
+const auth = require('../auth');
+const liveChannel = require('../live-channel');
+
+// SSE wire framing — pure + exported so a unit test can pin the format without
+// standing up HTTP. An event is `event: <name>` + one `data:` line, terminated
+// by a blank line. A line beginning with ':' is a comment the browser ignores
+// (used for the keep-alive heartbeat below).
+function frameEvent(event, data) {
+  return `event: ${event}\ndata: ${data}\n\n`;
+}
+
+// Heartbeat well under Cloudflare's ~100 s idle-connection timeout so a quiet
+// hall (no DB writes for a while) doesn't get its stream closed by the edge.
+const HEARTBEAT_MS = 25000;
+
+// Defense-in-depth per-IP concurrent-stream cap. requireBuilder already turns
+// away anonymous traffic and the payload leaks nothing (see header), so this
+// only stops a single signed-in client from opening unbounded long-lived
+// streams. Generous — a builder may legitimately keep several hall tabs open.
+// Kept INLINE (no import from src/rooms/) so the GDS live channel carries zero
+// game-code dependency, which is the whole point of R55.
+const MAX_CONN_PER_IP = 25;
+const connByIp = new Map();
+
+function openConn(ip) {
+  const n = connByIp.get(ip) || 0;
+  if (n >= MAX_CONN_PER_IP) return false;
+  connByIp.set(ip, n + 1);
+  return true;
+}
+function closeConn(ip) {
+  const n = (connByIp.get(ip) || 1) - 1;
+  if (n <= 0) connByIp.delete(ip);
+  else connByIp.set(ip, n);
+}
+
+// The SSE lifecycle, factored out of the route so it's unit-testable with a fake
+// req/res and an injected subscribe seam (no HTTP, no auth, deterministic).
+// deps.subscribe defaults to the real relay; deps.heartbeatMs is test-tunable.
+function streamLive(req, res, deps = {}) {
+  const subscribe = deps.subscribe || liveChannel.subscribe;
+  const heartbeatMs = deps.heartbeatMs || HEARTBEAT_MS;
+  const ip = req.ip || 'unknown';
+
+  if (!openConn(ip)) {
+    res.fail('too_many_live_connections', 429);
+    return;
+  }
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    // Defeat reverse-proxy response buffering (nginx/Caddy) so events flush.
+    'X-Accel-Buffering': 'no',
+  });
+  // Open the stream immediately with a comment so the client's `onopen` fires
+  // before the first nudge (and intermediaries see bytes right away).
+  res.write(': connected\n\n');
+  if (res.flushHeaders) res.flushHeaders();
+
+  const unsubscribe = subscribe(() => {
+    // Forward ONLY the bare signal — never the relay's {table, op}.
+    try { res.write(frameEvent('nudge', '{}')); } catch (_e) { /* closed */ }
+  });
+
+  const heartbeat = setInterval(() => {
+    try { res.write(': keep-alive\n\n'); } catch (_e) { /* closed */ }
+  }, heartbeatMs);
+  if (heartbeat.unref) heartbeat.unref();  // never keep the process alive
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    clearInterval(heartbeat);
+    unsubscribe();
+    closeConn(ip);
+  };
+  req.on('close', cleanup);
+  res.on('close', cleanup);
+}
+
+function buildLiveRouter() {
+  const router = express.Router();
+
+  // GET /api/gds/live — SSE stream of GDS state-change nudges for the hall.
+  // rank: any-builder — requireBuilder gates anonymous/abuse traffic (defense
+  // in depth; the payload leaks nothing). Mirrors the room's #983 signed-in
+  // gate. EventSource carries the gds_session cookie on this same-origin GET, so
+  // a signed-in viewer authenticates transparently. NOT module-gated: the hall's
+  // live refresh is core to every instance (the done-when is "live on a
+  // game-less boot"), so it mounts unconditionally in the GDS router.
+  router.get('/live', auth.requireBuilder, (req, res) => streamLive(req, res));
+
+  return router;
+}
+
+module.exports = buildLiveRouter;
+// Test/introspection seams (kept off the route surface).
+module.exports.frameEvent = frameEvent;
+module.exports.streamLive = streamLive;
+module.exports.MAX_CONN_PER_IP = MAX_CONN_PER_IP;
+module.exports._connByIp = connByIp;

package/src/bongos/routes/llm-cache.js

@@ -0,0 +1,119 @@
+// src/bongos/routes/llm-cache.js — System 5 transport (task 1381): expose the
+// content-addressed LLM cache over HTTP so CLI/cron consumers on builder
+// machines (architect-audit, onboarding-analyze) reach the cache DB through the
+// GDS API. The in-process pool stays the droplet fast path; this router is the
+// fallback transport. Each endpoint maps 1:1 onto an llm-cache.js DB helper so
+// server logic is single-sourced — the route NEVER reimplements SQL.
+//
+// TRUST (the critical surface — see ADR 0080):
+//  - A STORE writes a result a later run REPLAYS at $0 and trusts, so it is a
+//    content-injection vector. Gate: Metic+ (xenos/thetes can never seed a
+//    replayed result; rank is read live per-request, no cache — ADR 0016).
+//  - task_type must be a registered idempotent producer; cache_key is sha256-
+//    shaped; owner_builder_id is pinned to the caller (never trusts the client).
+//  - scope_sha bounds blast radius: a poisoned entry is only ever replayed for
+//    the EXACT (prompt, model, task_type, git-tree) it was stored under.
+//  - There is intentionally NO /record-saving route. Booking a saving writes the
+//    PUBLIC cost ledger (cost_baseline), which per migration 124 must be a
+//    server-side-priced figure — NEVER a client dollar amount. recordSaving stays
+//    pool-only (llm-cache.js); off-server a hit is recorded (hit_count) but its $
+//    saving is booked only once a follow-up forwards token usage for server-side
+//    re-pricing. result_cost_usd accepted by /store is clamped + stored only as
+//    INFORMATIONAL metadata on the (internal) llm_cache row, never booked public.
+
+'use strict';
+
+const express = require('express');
+const auth = require('../auth');
+const cache = require('../llm-cache');
+const { validateOrRespond } = require('./_helpers');
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+// Server ceiling on a single cached run's stored (informational) cost. The figure
+// is NOT booked to the public ledger (see header), but clamp it anyway so a bad
+// client can't write an absurd number even into the internal row. Env-tunable.
+const MAX_CACHED_COST_USD = Number(process.env.OTB_LLM_CACHE_MAX_COST_USD) || 10;
+
+function badKey(res) { return res.fail('bad_cache_key', 400); }
+
+// task_type must be a registered normalizer — i.e. a known idempotent producer.
+function knownTaskType(t) {
+  return typeof t === 'string' && Object.prototype.hasOwnProperty.call(cache.NORMALIZERS, t);
+}
+
+// Clamp the stored (informational) cost: coerce, floor at 0, cap at the ceiling.
+function clampedCost(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.min(n, MAX_CACHED_COST_USD);
+}
+
+module.exports = function buildLlmCacheRouter() {
+  const router = express.Router();
+  // /store carries a full subagent stdout — larger than the global 64 KB cap.
+  // routes.js skips the global parser for this path so this 512 KB parser is the
+  // only one that runs for it.
+  const bigJson = express.json({ limit: '512kb' });
+
+  // POST /llm-cache/lookup — hit/miss + atomic hit_count bump. Best-effort:
+  // any DB error inside lookup() already returns null → we report a miss.
+  // rank: metic — only the same trust tier that can store may read a stored result.
+  router.post('/llm-cache/lookup', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    // Fields validated in depth below (HEX64 key / clamp); schema declares the
+    // accepted set so strict-mode rejects a typo'd extra field.
+    if (validateOrRespond(req, res, { cache_key: {}, tokens_saved_est: {} })) return;
+    const key = req.body && req.body.cache_key;
+    if (!HEX64.test(String(key || ''))) return badKey(res);
+    // Clamp both ends: tokens_saved_est is an internal cosmetic counter; cap it so
+    // one call can't write an absurd value (mirrors clampedCost for the $ figure).
+    const tokensSavedEst = Math.min(Math.max(0, Number(req.body.tokens_saved_est) || 0), 50_000_000);
+    try {
+      const result = await cache.lookup(key, { tokensSavedEst });
+      return res.json({ hit: !!result, result: result || null });
+    } catch (err) {
+      // lookup() swallows DB errors; this catch is belt-and-braces so a cache
+      // call can never 500 the caller. Report a miss.
+      console.error('[gds] POST /llm-cache/lookup', err);
+      return res.json({ hit: false, result: null });
+    }
+  });
+
+  // POST /llm-cache/store — upsert a freshly-produced result.
+  // rank: metic — a store seeds a result that a later run replays at $0 and trusts.
+  router.post('/llm-cache/store', auth.requireBuilder, auth.requireRank('metic', 'archon'), bigJson, async (req, res) => {
+    // spec.* is re-built server-side (below) so its inner fields need no top-level
+    // schema; declare the three top-level fields so strict-mode rejects extras.
+    if (validateOrRespond(req, res, { spec: {}, result_stdout: {}, result_cost_usd: {} })) return;
+    const spec = req.body && req.body.spec;
+    if (!spec || !HEX64.test(String(spec.key || ''))) return badKey(res);
+    if (!knownTaskType(spec.task_type)) return res.fail('unknown_task_type', 400);
+    const resultStdout = req.body.result_stdout;
+    if (typeof resultStdout !== 'string' || resultStdout.length === 0) {
+      return res.fail('result_stdout_required', 400);
+    }
+    const resultCostUsd = clampedCost(req.body.result_cost_usd);
+    // Re-build the spec server-side from its declared fields so a client cannot
+    // smuggle extra columns; owner_builder_id is pinned to the CALLER. scope_sha
+    // is NOT required to be hex — onboarding-analyze uses a session id, not a tree
+    // SHA — so it is only length-capped.
+    const safeSpec = {
+      key: spec.key,
+      prompt_hash: HEX64.test(String(spec.prompt_hash || '')) ? spec.prompt_hash : spec.key,
+      model: spec.model == null ? null : String(spec.model).slice(0, 128),
+      task_type: spec.task_type,
+      scope_sha: spec.scope_sha == null ? null : String(spec.scope_sha).slice(0, 256),
+      owner_builder_id: req.builder.id,
+      ttl_ms: spec.ttl_ms == null ? null : (Math.max(0, Number(spec.ttl_ms) || 0) || null),
+    };
+    try {
+      const stored = await cache.store(safeSpec, { resultStdout, resultCostUsd });
+      return res.json({ stored: !!stored, result_cost_usd: resultCostUsd });
+    } catch (err) {
+      console.error('[gds] POST /llm-cache/store', err);
+      return res.json({ stored: false });
+    }
+  });
+
+  return router;
+};