@bongos/core 1.19.103 → 1.19.104

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.103",
-  "core_contract": "1.19.103",
-  "source_commit": "4c26152f4ffe43100617e89d904852639f51a9dc",
+  "core_version": "1.19.104",
+  "core_contract": "1.19.104",
+  "source_commit": "3c2a0481a031c30a0afdd9294b2510373ffe960f",
   "source_ref": "HEAD",
-  "built_at": "2026-08-13T23:41:03.246Z",
+  "built_at": "2026-08-14T00:14:10.093Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 301,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1234,
+    "functional_verbatim": 1236,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1556,
-  "tree_sha256": "b559bea5c153dfcb5b4007dee090a97532674449005645ee1953761712bcf02a",
+  "file_count": 1558,
+  "tree_sha256": "8257863293fa7660b41b1617777db22fadd851349106de278c846a482dd31a66",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4147,12 +4147,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b3854f65fe8ad4aead3d08a87f9f2200d87e2b049aed77f7849d51f9aa6f6e5b"
+      "sha256": "ef0ed51dd00b72093c6deac7c061dc0fddf88b0135d2d1981c00d37cdb7a9345"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7467e0451b4fd162c287c7a5eceee8da746785a3da989bda154830ead5728f3d"
+      "sha256": "64f2fc25cfe4707562314bef85b1a22c3b3027e6b43d74644fd37fbc61daa539"
     },
     {
       "path": "public-docs/index.html",
@@ -5692,7 +5692,12 @@
     {
       "path": "src/bongos/serve-internal.js",
       "mode": "0000644",
-      "sha256": "693ef4dfd3619a2d999e6223de0e2d51b697cf4004c482b74f60b8cfb362a566"
+      "sha256": "c791369591627f89ff1755ea1d343159716b512e64f92286d27547209da88df7"
+    },
+    {
+      "path": "src/bongos/stealth-gate.js",
+      "mode": "0000644",
+      "sha256": "6ea72c90380663fac7ece7d97cd628792f3d68a2969a502c59addfcb83c2bcb4"
     },
     {
       "path": "src/bongos/uptime-poller.js",
@@ -5722,7 +5727,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "18be8d4886ea03a65a0cd5d817c811ca0496ea509df5716f416d985a5d682b84"
+      "sha256": "c8a86a1c119d7da3b4baf912eb2d228f83be18b07fbce6c104858a00027efbda"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7689,6 +7694,11 @@
       "mode": "0000644",
       "sha256": "aa1d79bb3f900097a911c8c6b3055debe4bb20bfe2c3d6c8c64cfd8d7688824e"
     },
+    {
+      "path": "tests/stealth_gate.mjs",
+      "mode": "0000644",
+      "sha256": "c4deafe658457e9f3c17a99f6ab2435e1b1c4d42d74d77304ba792458562e771"
+    },
     {
       "path": "tests/stop_refcheck.mjs",
       "mode": "0000644",

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.103",
+  "version": "1.19.104",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.103",
+      "version": "1.19.104",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.103",
+  "version": "1.19.104",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/serve-internal.js

@@ -45,6 +45,7 @@ const { buildInfo } = require('../build-info');
 const { buildDevboxDownloads } = require('../devbox-downloads');
 const { buildBongosDownloads } = require('../bongos-downloads');
 const { clientBranding, branding } = require('../branding');
+const { stealthGate } = require('./stealth-gate');
 const { clientModules, isModuleEnabled } = require('../modules');
 const { hallWidgetScripts, moduleWebSurfaces } = require('../module-loader/loader');
 const { resolveCoreRoot, resolveDocsRoot, resolveInstanceRoot } = require('../instance-config');
@@ -441,6 +442,16 @@ function mountInternalSurfaces(app) {
   // game routes too) — it records on res 'finish' regardless of which handler
   // answers. The /metrics scrape endpoint is access-gated (loopback Prometheus
   // or Bearer METRICS_TOKEN; see metrics.authorizeScrape).
+  // THE STEALTH GATE (task 1002775) mounts before anything it is meant to
+  // cover — a surface registered earlier would answer first and the gate would
+  // never run. Inert unless STEALTH_PASSWORD is set, so a vanilla instance is
+  // unaffected and pays only a closure call per request.
+  //
+  // It sits ABOVE the metrics middleware deliberately: a refused knock is still
+  // a request this instance served, and hiding gate 401s would make the traffic
+  // graph lie about how much attention an unannounced instance is getting.
+  app.use(stealthGate());
+
   app.use(metrics.httpMiddleware());
   app.get('/metrics', metrics.metricsHandler());
 

package/src/bongos/stealth-gate.js

@@ -0,0 +1,203 @@
+// src/bongos/stealth-gate.js — the pre-launch stealth gate (task 1002775).
+//
+// An instance that is built but not announced needs a door that is shut without
+// being broken. The proxy can do that with basic_auth, and task 1002774 did
+// exactly that to close an exposure quickly — but HTTP basic auth is per-ORIGIN,
+// so the apex, the hall and the status dashboard each prompt separately. Three
+// native browser dialogs, none of them able to say what the site is or why it is
+// asking. The owner asked for one password, entered once, good across the whole
+// domain for the session.
+//
+// So the gate lives in the app, where it can set a cookie the browser will send
+// to every subdomain:
+//
+//   - It is INERT unless STEALTH_PASSWORD is set. That is the portable default:
+//     a vanilla instance has no gate and needs no config to not have one.
+//   - The cookie is a SESSION cookie — no Max-Age, no Expires — because the
+//     owner explicitly did not want it to outlive the browser. That is also the
+//     safer default: nothing is written to disk to be found later.
+//   - It is scoped to the cookie apex, so ONE entry unlocks apex + www +
+//     builders + status. The apex and its host set come from the same branding
+//     key auth.js reads (domains.cookieDomain), so the gate and the session
+//     cookie cannot disagree about what "this domain" means.
+//   - The cookie carries an HMAC KEYED BY THE PASSWORD, never the password. No
+//     second secret to manage, and rotating the password invalidates every
+//     outstanding cookie for free.
+//
+// This is deliberately not an authorization system. It has no accounts, no
+// ranks, and it grants nothing: everything behind it still enforces its own
+// rank checks against the database (ADR 0016). It only decides whether a
+// stranger may SEE the instance at all, which is why one shared password is the
+// right primitive and why it must never be mistaken for sign-in.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const { branding } = require('../branding');
+
+const COOKIE = 'cb_stealth';
+const SUBMIT_PATH = '/__stealth';
+
+// Paths that must answer even to a stranger, each for its own reason:
+//   /api/*    the GitHub OAuth round trip has to complete, and a gated callback
+//             would break sign-in for the very people holding the password
+//   /healthz  external probes + the upgrade's post-restart health check
+//   /metrics  Prometheus, already access-gated on its own terms (loopback or
+//             bearer token) — double-gating it would break the scrape
+//   /version  the deploy pin check, a public commit sha
+const EXEMPT = [/^\/api\//, /^\/healthz$/, /^\/metrics$/, /^\/version$/, /^\/__stealth$/];
+
+function password() {
+  const p = process.env.STEALTH_PASSWORD;
+  return typeof p === 'string' && p.length ? p : null;
+}
+
+function enabled() { return password() !== null; }
+
+// The token a valid cookie must carry. Keyed by the password, so the password
+// itself never leaves the server and a rotation invalidates every cookie.
+function expectedToken() {
+  return crypto.createHmac('sha256', password()).update('stealth-v1').digest('hex');
+}
+
+function tokenMatches(raw) {
+  if (typeof raw !== 'string') return false;
+  const want = Buffer.from(expectedToken(), 'utf8');
+  const got = Buffer.from(raw, 'utf8');
+  // timingSafeEqual throws on a length mismatch, which is itself a comparison —
+  // check the length first so both branches cost the same shape
+  if (got.length !== want.length) return false;
+  return crypto.timingSafeEqual(got, want);
+}
+
+function cookieApex() {
+  try {
+    return String(branding().domains?.cookieDomain || '').replace(/^\./, '').toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function reqHost(req) {
+  const raw = req.headers['x-forwarded-host'] || req.headers['host'] || '';
+  return String(raw).toLowerCase().split(',')[0].trim().split(':')[0];
+}
+
+// Scope to the apex only on the hosts that actually share it — the same set
+// auth.js uses for the session cookie. Anywhere else (localhost, a preview host)
+// the cookie stays host-only, because a Domain= attribute for a domain you are
+// not on is simply rejected by the browser and would lock the operator out.
+function domainOpts(req) {
+  const apex = cookieApex();
+  if (!apex) return {};
+  const host = reqHost(req);
+  const shared = new Set([apex, 'www.' + apex, 'builders.' + apex, 'status.' + apex]);
+  return shared.has(host) ? { domain: '.' + apex } : {};
+}
+
+function readCookie(req, name) {
+  for (const part of String(req.headers.cookie || '').split(';')) {
+    const [k, ...v] = part.trim().split('=');
+    if (k === name && v.length) return decodeURIComponent(v.join('='));
+  }
+  return null;
+}
+
+function isExempt(path) {
+  return EXEMPT.some((re) => re.test(path));
+}
+
+// The form. Self-contained and token-free on purpose: it is served BEFORE the
+// visitor is allowed to see anything, so it must not pull the branding bundle,
+// the stylesheet, or any other asset that would leak the design of an
+// unannounced product to whoever knocks.
+function formHtml({ productName, wrong }) {
+  const name = String(productName || 'This instance').replace(/[<>&"]/g, '');
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex,nofollow">
+<title>${name}</title><style>
+:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;
+  font:500 15px/1.5 ui-rounded,"Quicksand",system-ui,-apple-system,"Segoe UI",sans-serif;
+  background:#f9d9a8;color:#2b170e}
+@media(prefers-color-scheme:dark){body{background:#150c06;color:#f4e6cd}}
+.box{width:min(380px,100%);text-align:center}
+.dots{display:flex;gap:10px;justify-content:center;margin-bottom:22px}
+.dots i{display:block;border-radius:50%;background:#ce4806}
+.dots i:first-child{width:38px;height:38px}
+.dots i:last-child{width:28px;height:28px;background:#855b3d;align-self:flex-end}
+h1{font-size:20px;font-weight:700;margin:0 0 6px}
+p{margin:0 0 20px;opacity:.72;font-size:14px}
+form{display:flex;gap:8px}
+input{flex:1;min-width:0;padding:11px 14px;border-radius:999px;border:1.5px solid rgba(206,72,6,.35);
+  background:rgba(255,255,255,.72);color:inherit;font:inherit}
+@media(prefers-color-scheme:dark){input{background:rgba(255,255,255,.08)}}
+input:focus{outline:2px solid #ce4806;outline-offset:1px}
+button{padding:11px 20px;border:0;border-radius:999px;background:#ce4806;color:#fff;
+  font:700 14px/1 inherit;cursor:pointer}
+.err{margin:14px 0 0;color:#b3261e;font-size:13.5px}
+@media(prefers-color-scheme:dark){.err{color:#ffb4a8}}
+</style></head><body><div class="box">
+<div class="dots"><i></i><i></i></div>
+<h1>${name}</h1>
+<p>Not open to the world yet. Enter the password to have a look.</p>
+<form method="POST" action="${SUBMIT_PATH}">
+  <input type="password" name="password" placeholder="Password" aria-label="Password" autofocus required>
+  <button type="submit">Enter</button>
+</form>
+${wrong ? '<p class="err">That password didn’t work.</p>' : ''}
+</div></body></html>`;
+}
+
+function productName() {
+  try { return branding().identity?.productName || 'This instance'; } catch { return 'This instance'; }
+}
+
+// Mounted FIRST, ahead of every other surface — a route registered earlier would
+// answer before the gate ever ran.
+function stealthGate() {
+  return function stealth(req, res, next) {
+    if (!enabled()) return next();
+
+    if (req.method === 'POST' && req.path === SUBMIT_PATH) {
+      // The form is urlencoded; body parsers mount later (and only on some
+      // routers), so read it here rather than depending on middleware order.
+      let body = '';
+      req.on('data', (c) => {
+        body += c;
+        if (body.length > 4096) req.destroy();   // a password is not a payload
+      });
+      req.on('end', () => {
+        const params = new URLSearchParams(body);
+        const given = params.get('password') || '';
+        const want = password();
+        const ok = given.length === want.length
+          && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
+        if (!ok) {
+          return res.status(401).type('html').send(formHtml({ productName: productName(), wrong: true }));
+        }
+        res.cookie(COOKIE, expectedToken(), {
+          httpOnly: true,
+          secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
+          sameSite: 'lax',
+          path: '/',
+          ...domainOpts(req),
+          // no maxAge/expires — a SESSION cookie, by the owner's choice
+        });
+        res.redirect(303, '/');
+      });
+      return undefined;
+    }
+
+    if (isExempt(req.path)) return next();
+    if (tokenMatches(readCookie(req, COOKIE))) return next();
+
+    // 401 rather than 200: this is an unauthenticated request being refused, and
+    // a crawler that ignores the noindex should still be told so.
+    return res.status(401).type('html').send(formHtml({ productName: productName(), wrong: false }));
+  };
+}
+
+module.exports = { stealthGate, enabled, isExempt, tokenMatches, expectedToken, COOKIE, SUBMIT_PATH };

package/src/module-api.js

@@ -633,8 +633,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.101 with no explicit bump. run 31753496152. (task 1002620)
 //   1.19.103 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.102 with no explicit bump. run 31754659965. (task 1002620)
+//   1.19.104 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.103 with no explicit bump. run 31756625919. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.103'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.104'; // CI auto-patch carrier (ADR 0161); 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');

package/tests/stealth_gate.mjs

@@ -0,0 +1,169 @@
+// tests/stealth_gate.mjs — the pre-launch stealth gate (task 1002775).
+//
+// A gate that is wrong in either direction is worse than no gate: too open and
+// the unannounced instance is readable; too closed and it locks out sign-in,
+// health probes, or the operator. These drive the REAL booted app, because the
+// gate's whole job is to sit in front of surfaces registered elsewhere — a unit
+// test of the middleware alone could not prove it was mounted early enough.
+//
+// Run:  node --test tests/stealth_gate.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const PASSWORD = 'a-test-password';
+process.env.STEALTH_PASSWORD = PASSWORD;   // set BEFORE the app is built
+
+const gate = require('../src/bongos/stealth-gate.js');
+const platformMod = require('../src/platform-server.js');
+
+let server, port;
+
+before(async () => {
+  server = http.createServer(platformMod.buildPlatformApp());
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(async () => {
+  await new Promise((r) => server.close(r));
+  delete process.env.STEALTH_PASSWORD;
+});
+
+function request(pathname, { method = 'GET', cookie, body } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      host: '127.0.0.1', port, path: pathname, method,
+      headers: {
+        host: '127.0.0.1',
+        ...(cookie ? { cookie } : {}),
+        ...(body ? { 'content-type': 'application/x-www-form-urlencoded', 'content-length': Buffer.byteLength(body) } : {}),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: data }));
+    });
+    req.on('error', reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+const validCookie = () => `${gate.COOKIE}=${gate.expectedToken()}`;
+
+test('a stranger gets the form, not the product', async () => {
+  const res = await request('/');
+  assert.equal(res.status, 401, 'a refused knock is a 401, not a 200');
+  assert.match(res.body, /type="password"/, 'the form must be usable');
+  assert.match(res.body, /noindex/, 'an unannounced instance must not be indexed');
+});
+
+test('the form leaks nothing about the product it is hiding', async () => {
+  const res = await request('/');
+  // it is served BEFORE the visitor may see anything, so it must not pull the
+  // stylesheet, the branding bundle, or any other asset that would show the
+  // design of an unannounced product to whoever knocks
+  assert.doesNotMatch(res.body, /cosmos\.css/);
+  assert.doesNotMatch(res.body, /__BRANDING__/);
+  assert.doesNotMatch(res.body, /<script/, 'no script at all on the gate page');
+});
+
+test('every human surface is gated, not just the front page', async () => {
+  // the old proxy lock covered '/' but not '/projects', so the hub leaked for
+  // the whole stealth period — that regression must be impossible here
+  for (const p of ['/', '/projects', '/create', '/builders', '/docs']) {
+    const res = await request(p);
+    assert.equal(res.status, 401, `${p} must be gated`);
+  }
+});
+
+test('the OAuth round trip and the probes stay open', async () => {
+  // gating these would lock out the very people holding the password, and blind
+  // the deploy's own health check
+  for (const p of ['/healthz', '/version']) {
+    const res = await request(p);
+    assert.notEqual(res.status, 401, `${p} must answer a stranger`);
+  }
+  // a DB-free API path: 404 from the router proves the request REACHED the API
+  // (i.e. the gate let it through) without needing a database in this suite
+  const api = await request('/api/bongos/__not-a-route');
+  assert.notEqual(api.status, 401, 'the OAuth/public API surface must not be gated');
+  assert.equal(api.status, 404, 'and it should reach the API router itself');
+});
+
+test('the right password opens it and sets a SESSION cookie', async () => {
+  const res = await request(gate.SUBMIT_PATH, {
+    method: 'POST',
+    body: new URLSearchParams({ password: PASSWORD }).toString(),
+  });
+  assert.equal(res.status, 303, 'a successful POST redirects rather than rendering');
+  const setCookie = String(res.headers['set-cookie'] || '');
+  assert.match(setCookie, new RegExp(gate.COOKIE));
+  assert.match(setCookie, /HttpOnly/i, 'script must not be able to read it');
+  assert.match(setCookie, /SameSite=Lax/i);
+  // the owner asked for session-only — no persistence to disk
+  assert.doesNotMatch(setCookie, /Max-Age/i, 'must not outlive the browser session');
+  assert.doesNotMatch(setCookie, /Expires/i);
+});
+
+test('the cookie never carries the password itself', async () => {
+  const res = await request(gate.SUBMIT_PATH, {
+    method: 'POST',
+    body: new URLSearchParams({ password: PASSWORD }).toString(),
+  });
+  const setCookie = String(res.headers['set-cookie'] || '');
+  assert.ok(!setCookie.includes(PASSWORD), 'the password must never reach the client');
+});
+
+test('a valid cookie gets the real page', async () => {
+  const res = await request('/', { cookie: validCookie() });
+  assert.equal(res.status, 200);
+  assert.doesNotMatch(res.body, /type="password"/, 'the gate must be out of the way now');
+});
+
+test('a wrong password is refused and says so', async () => {
+  const res = await request(gate.SUBMIT_PATH, {
+    method: 'POST',
+    body: new URLSearchParams({ password: 'not-it' }).toString(),
+  });
+  assert.equal(res.status, 401);
+  assert.match(res.body, /didn/, 'the visitor must be told it failed');
+  assert.ok(!String(res.headers['set-cookie'] || '').includes(gate.COOKIE), 'no cookie on failure');
+});
+
+test('a forged or stale cookie does not open it', async () => {
+  for (const bad of ['x', 'deadbeef', gate.expectedToken().slice(0, -1) + '0']) {
+    const res = await request('/', { cookie: `${gate.COOKIE}=${bad}` });
+    assert.equal(res.status, 401, `forged cookie ${bad.slice(0, 12)} must be refused`);
+  }
+});
+
+test('rotating the password invalidates outstanding cookies', async () => {
+  const old = validCookie();
+  process.env.STEALTH_PASSWORD = 'a-different-password';
+  const res = await request('/', { cookie: old });
+  process.env.STEALTH_PASSWORD = PASSWORD;
+  assert.equal(res.status, 401, 'the token is keyed by the password, so a rotation revokes');
+});
+
+test('an oversized POST body is dropped rather than buffered', async () => {
+  // a password is not a payload — the handler reads the body itself, so it must
+  // bound it or it is a trivial memory sink on an unauthenticated endpoint
+  const src = require('node:fs').readFileSync(
+    new URL('../src/bongos/stealth-gate.js', import.meta.url), 'utf8');
+  assert.match(src, /body\.length > \d+/, 'the body read must be bounded');
+  assert.match(src, /req\.destroy\(\)/);
+});
+
+test('the gate is inert when no password is configured', () => {
+  // the portable default: a vanilla instance has no gate and needs no config
+  // to not have one
+  delete process.env.STEALTH_PASSWORD;
+  assert.equal(gate.enabled(), false);
+  process.env.STEALTH_PASSWORD = PASSWORD;
+  assert.equal(gate.enabled(), true);
+});