@bongos/core 1.18.3 → 1.18.18

package/tests/devbox_installer_brand.mjs

@@ -0,0 +1,232 @@
+// tests/devbox_installer_brand.mjs — the Dev Box installer's BUILD INPUTS are
+// branding-driven and match what the generator produces (task 1002512).
+//
+// The app is built separately from the server (ADR 0045), so its brand is baked
+// in at BUILD time by modules/dev-box/app/scripts/gen-brand.js reading the
+// instance branding pack (ADR 0145). Three artifacts are COMMITTED —
+// src/brand.generated.json, renderer/theme.generated.css, electron-builder.yml —
+// and until now nothing checked that they still equal the generator's output.
+// A hand-edit to electron-builder.yml (the template's own "edit THIS file, never
+// the generated one") survived silently until the next unrelated regeneration
+// quietly reverted it, and a stale committed artifact means CI ships an installer
+// whose appId / product name / artifact filenames are not what the pack says.
+//
+// PURE by construction: it calls the exported builders and NEVER main(), so a run
+// writes nothing and cannot dirty the tree. That is also why gen-brand.js gained
+// a `require.main === module` guard — importing it used to rewrite all three files.
+//
+// EOL: electron-builder.yml and theme.generated.css are CRLF on a default Windows
+// checkout while the generator emits LF. Comparisons go through gen-freshness.js's
+// sameContent() — a raw byte compare is red forever on Windows and green in Linux
+// CI, the worst kind of gate.
+//
+// Regex/line based on the YAML (like tests/devbox_artifact_gate.mjs) — the repo
+// declares no YAML parser. DB-free, no network. Run: node --test tests/devbox_installer_brand.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const APP_DIR = path.join(ROOT, 'modules', 'dev-box', 'app');
+
+const { sameContent } = require(path.join(ROOT, 'scripts', 'gds', 'gen-freshness.js'));
+const genBrand = require(path.join(APP_DIR, 'scripts', 'gen-brand.js'));
+const { buildBrand, buildThemeCss, renderElectronBuilder } = genBrand;
+
+const neutral = JSON.parse(fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8'));
+const read = (...p) => fs.readFileSync(path.join(APP_DIR, ...p), 'utf8');
+
+const ORIGIN_ENV = ['DEVBOX_PUBLIC_ORIGIN', 'DEVBOX_BUILDERS_ORIGIN'];
+
+// buildBrand reads the origin env vars at CALL time, so a developer's stray
+// export would otherwise fake a drift failure. Run fn with a known env.
+function withEnv(overrides, fn) {
+  const saved = Object.fromEntries(ORIGIN_ENV.map((k) => [k, process.env[k]]));
+  try {
+    for (const k of ORIGIN_ENV) {
+      if (overrides[k] === undefined) delete process.env[k];
+      else process.env[k] = overrides[k];
+    }
+    return fn();
+  } finally {
+    for (const k of ORIGIN_ENV) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  }
+}
+
+// The committed artifacts are the NEUTRAL (env-free) build — that is what a
+// release build re-renders over, so this is the expectation to compare against.
+const neutralBrand = () => withEnv({}, () => buildBrand(neutral));
+
+// A YAML value by key at any indent, first match wins (no parser in the repo deps).
+function yamlValue(yml, key) {
+  const m = new RegExp(`^\\s*${key}:\\s*(.+?)\\s*$`, 'm').exec(yml);
+  return m ? m[1] : null;
+}
+
+// Comment lines carry rationale prose that names the tokens on purpose (the
+// template header says "@@TOKENS@@ are substituted") — scan the config only.
+function settingsOnly(yml) {
+  return yml.split(/\r?\n/).filter((l) => !/^\s*#/.test(l)).join('\n');
+}
+
+// ── (a) drift gate: committed build inputs === generator output ────────────────
+
+test('committed brand.generated.json is what the generator produces from the pack', () => {
+  assert.deepEqual(JSON.parse(read('src', 'brand.generated.json')), neutralBrand(),
+    'src/brand.generated.json is stale — run `npm run gen-brand` in modules/dev-box/app and commit');
+});
+
+test('committed theme.generated.css is what the generator produces from the pack', () => {
+  assert.ok(sameContent(read('renderer', 'theme.generated.css'), buildThemeCss(neutral)),
+    'renderer/theme.generated.css is stale — run `npm run gen-brand` and commit');
+});
+
+test('committed electron-builder.yml is what the template renders to', () => {
+  assert.ok(sameContent(read('electron-builder.yml'), renderElectronBuilder(neutralBrand())),
+    'electron-builder.yml was hand-edited or is stale — edit electron-builder.tmpl.yml, ' +
+    'run `npm run gen-brand`, and commit the rendered file');
+});
+
+// ── (b) installer identity, read out of the RENDERED yml ──────────────────────
+
+test('the rendered installer declares the pack identity and no leftover token', () => {
+  const brand = neutralBrand();
+  const yml = renderElectronBuilder(brand);
+  assert.equal(yamlValue(yml, 'appId'), brand.APP_ID);
+  assert.equal(yamlValue(yml, 'appId'), 'com.cloudbongos.devbox');
+  assert.equal(yamlValue(yml, 'productName'), 'Cloud Bongos Dev Box');
+  assert.ok((yamlValue(yml, 'copyright') || '').length > 0, 'copyright must not render empty');
+  assert.doesNotMatch(settingsOnly(yml), /@@[A-Z_]+@@/,
+    'an unsubstituted @@TOKEN@@ reached the rendered config');
+});
+
+test('every installer filename carries the slug, the version and the arch', () => {
+  const { PRODUCT_SLUG } = neutralBrand();
+  const yml = renderElectronBuilder(neutralBrand());
+  const names = [...yml.matchAll(/^\s*artifactName:\s*(.+?)\s*$/gm)].map(([, v]) => v);
+  assert.ok(names.length >= 3, `expected mac + dmg + nsis artifactName, found ${names.length}`);
+  for (const name of names) {
+    assert.ok(name.startsWith(PRODUCT_SLUG), `artifactName "${name}" does not start with the brand slug`);
+    assert.match(name, /\$\{version\}/, `artifactName "${name}" has no \${version}`);
+    // #908: an arch-less name makes the x64 and arm64 builds collide on one file.
+    assert.match(name, /\$\{arch\}/, `artifactName "${name}" has no \${arch} — two arches would collide`);
+  }
+  assert.ok(names.some((n) => /-Setup-/.test(n)), 'the NSIS installer name must be distinguishable');
+});
+
+test('the Windows target still builds both arches', () => {
+  const yml = renderElectronBuilder(neutralBrand());
+  const winBlock = yml.slice(yml.indexOf('\nwin:'));
+  const arch = /arch:\s*\[([^\]]+)\]/.exec(winBlock);
+  assert.ok(arch, 'win target declares no arch list');
+  const arches = arch[1].split(',').map((s) => s.trim());
+  for (const a of ['x64', 'arm64']) assert.ok(arches.includes(a), `win arch list is missing ${a}`);
+});
+
+// ── (c) one source rebrands — the ADR 0145 promise, mechanized ────────────────
+
+test('a different pack produces a different installer with no Cloud Bongos left in it', () => {
+  const pack = {
+    identity: { worldName: 'Kettle Drum', company: { name: 'Kettle Drum Co' } },
+    domains: { publicOrigin: 'https://kettle.example' },
+    configDir: 'kettle',
+    theme: { ui: { colors: { bg: '#101010' } } },
+  };
+  const brand = withEnv({}, () => buildBrand(pack));
+  assert.equal(brand.APP_ID, 'com.kettledrum.devbox');
+  assert.equal(brand.PRODUCT_NAME, 'Kettle Drum Dev Box');
+  assert.equal(brand.PRODUCT_SLUG, 'Kettle-Drum-Dev-Box');
+  assert.equal(brand.CONFIG_DIR, 'kettle');
+  assert.equal(brand.BG_COLOR, '#101010');
+  assert.equal(brand.COPYRIGHT, '© Kettle Drum Co');
+  const HOST_BRAND = /cloud ?bongos/i;
+  assert.doesNotMatch(JSON.stringify(brand), HOST_BRAND, 'a host pack still carries Cloud Bongos strings');
+  assert.doesNotMatch(settingsOnly(renderElectronBuilder(brand)), HOST_BRAND,
+    'the rendered installer config still names Cloud Bongos on a host pack');
+});
+
+// ── (d) origins are a build input ─────────────────────────────────────────────
+
+test('the release origin env beats the pack', () => {
+  const brand = withEnv({
+    DEVBOX_PUBLIC_ORIGIN: 'https://cloudbongos.example',
+    DEVBOX_BUILDERS_ORIGIN: 'https://builders.cloudbongos.example',
+  }, () => buildBrand(neutral));
+  assert.equal(brand.PUBLIC_ORIGIN, 'https://cloudbongos.example');
+  assert.equal(brand.BUILDERS_ORIGIN, 'https://builders.cloudbongos.example');
+});
+
+test('with no env the pack origins are used, and buildersOrigin falls back to publicOrigin', () => {
+  const fromPack = withEnv({}, () => buildBrand(neutral));
+  assert.equal(fromPack.PUBLIC_ORIGIN, neutral.domains.publicOrigin);
+  assert.equal(fromPack.BUILDERS_ORIGIN, neutral.domains.buildersOrigin);
+
+  const noBuilders = withEnv({}, () => buildBrand({ domains: { publicOrigin: 'https://only.example' } }));
+  assert.equal(noBuilders.BUILDERS_ORIGIN, 'https://only.example',
+    'a pack without buildersOrigin must fall back to publicOrigin, not to localhost');
+});
+
+test('the COMMITTED artifact is the neutral localhost build — no host origin is checked in', () => {
+  const committed = JSON.parse(read('src', 'brand.generated.json'));
+  for (const key of ['PUBLIC_ORIGIN', 'BUILDERS_ORIGIN']) {
+    assert.match(committed[key], /^http:\/\/localhost(:\d+)?$/,
+      `${key} in the committed brand.generated.json is a host origin — a release build sets it via env`);
+  }
+});
+
+// ── (e) CI passes the origins through ─────────────────────────────────────────
+
+test('both build jobs pass the origin repo variables into the build', () => {
+  const wf = fs.readFileSync(path.join(ROOT, '.github', 'workflows', 'build-devbox-app.yml'), 'utf8');
+  const lines = wf.split(/\r?\n/);
+  const jobStarts = lines.reduce((acc, l, i) => (/^ {2}[a-z0-9-]+:\s*$/.test(l) ? [...acc, i] : acc), []);
+  function jobBlock(name) {
+    const at = lines.findIndex((l) => l === `  ${name}:`);
+    assert.ok(at >= 0, `workflow has no ${name} job`);
+    const end = jobStarts.find((i) => i > at) ?? lines.length;
+    return lines.slice(at, end).join('\n');
+  }
+  for (const job of ['build-mac', 'build-win']) {
+    const block = jobBlock(job);
+    for (const v of ORIGIN_ENV) {
+      assert.match(block, new RegExp(`${v}:\\s*\\$\\{\\{\\s*vars\\.${v}\\s*\\}\\}`),
+        `${job} does not pass ${v} from repo variables — the release build would pair against localhost`);
+    }
+  }
+});
+
+// ── (f) published names are names the builder can emit ────────────────────────
+
+test('the published asset filenames match what electron-builder will emit', () => {
+  // INSTANCE-ONLY config (publish-manifest.js INSTANCE_EXCLUDE) — absent in the
+  // core checkout, so this is a guarded cross-check, never a hard require.
+  const cfgPath = path.join(ROOT, 'config', 'devbox-app.json');
+  if (!fs.existsSync(cfgPath)) {
+    console.log('    (skipped: config/devbox-app.json is instance-only and absent in this checkout)');
+    return;
+  }
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  const yml = renderElectronBuilder(neutralBrand());
+  const nsis = yamlValue(yml.slice(yml.indexOf('\nnsis:')), 'artifactName');
+  const mac = yamlValue(yml.slice(yml.indexOf('\ndmg:')), 'artifactName');
+  for (const [key, filename] of Object.entries(cfg.assets || {})) {
+    const m = /^(mac|win)-(\S+)$/.exec(key);
+    if (!m) continue;
+    const [, platform, arch] = m;
+    const pattern = platform === 'mac' ? mac : nsis;
+    const expected = pattern
+      .replace(/\$\{version\}/g, cfg.version)
+      .replace(/\$\{arch\}/g, arch)
+      .replace(/\$\{ext\}/g, platform === 'mac' ? 'dmg' : 'exe');
+    assert.equal(filename, expected,
+      `config/devbox-app.json assets["${key}"] names a file electron-builder will not produce`);
+  }
+});

package/tests/devbox_key_register.mjs

@@ -0,0 +1,234 @@
+// tests/devbox_key_register.mjs — the Dev Box app's SSH-key registration and
+// known_hosts replacement (task 1002509).
+//
+// Two user-visible defects are pinned here:
+//   1. Key registration was ONE un-retried POST whose rejection was logged and
+//      dropped. A flaky network at sign-in left the builder with no key in the
+//      box's authorized_keys and nothing ever tried again — every connect refused.
+//      registerKeyWithVerify retries, then VERIFIES against the server's own list,
+//      because a 201 is not proof.
+//   2. mergeKnownHosts only matched plain `host` / `host,ip` field-1 values, so a
+//      HASHED entry (`|1|salt|hash` — HashKnownHosts is on by default on Debian/
+//      Ubuntu) survived a "replace" and the stale line kept winning: "Host denied
+//      (verification failed)".
+//
+// It requires the app source directly (node builtins only — no Electron, no
+// network, no fs): the app is a separately-packaged subproject whose own
+// test/unit.mjs is NOT part of the root unit gate, so the gate lives here.
+//
+// Run:  node tests/devbox_key_register.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  registerKeyWithVerify,
+  sshFingerprintSha256,
+  publicKeyFingerprint,
+  mergeKnownHosts,
+  knownHostsLineMatchesHost,
+  reportedKeysAreStale,
+} = require('../modules/dev-box/app/src/ssh-setup.js');
+const boxOnboard = require('../modules/dev-box/box-onboard.js');
+const boxes = require('../modules/dev-box/boxes.js');
+
+// A REAL ed25519 public key (the same fixture tests/box_host_keys.mjs uses).
+const ED = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPCoIEgcBiGqM2Rd0rgfw0d7rHccvbpSe3vsSN7brif/';
+const ED_BODY = ED.split(' ')[1];
+const HOST = 'box-alice.dev.example.com';
+
+// --- fingerprint parity with the server ------------------------------------
+
+test('sshFingerprintSha256 matches the server-side implementation byte for byte', () => {
+  const mine = sshFingerprintSha256(ED_BODY);
+  assert.match(mine, /^SHA256:[A-Za-z0-9+/]+$/, 'SHA256: prefix, no base64 padding');
+  assert.equal(mine, boxOnboard.sshFingerprintSha256(ED_BODY),
+    'the app must compute the SAME fingerprint the GDS stores, or verification can never match');
+});
+
+test('publicKeyFingerprint ignores the comment and rejects a non-key line', () => {
+  assert.equal(publicKeyFingerprint(`${ED} someone@laptop`), sshFingerprintSha256(ED_BODY));
+  assert.equal(publicKeyFingerprint(ED), sshFingerprintSha256(ED_BODY));
+  assert.equal(publicKeyFingerprint('ssh-ed25519'), null);
+  assert.equal(publicKeyFingerprint(''), null);
+  assert.equal(publicKeyFingerprint(null), null);
+});
+
+// --- registerKeyWithVerify -------------------------------------------------
+
+const FP = sshFingerprintSha256(ED_BODY);
+
+// Fake clock: records every backoff so a test can prove the retry actually waited.
+function fakeSleep() {
+  const waits = [];
+  const fn = async (ms) => { waits.push(ms); };
+  fn.waits = waits;
+  return fn;
+}
+
+test('registration verified on the first attempt', async () => {
+  const calls = [];
+  const sleep = fakeSleep();
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    label: 'devbox-app test',
+    registerKey: async (pk, label) => { calls.push([pk, label]); },
+    listKeys: async () => ({ keys: [{ fingerprint: FP }] }),
+    sleep,
+  });
+  assert.deepEqual(r, { ok: true, fingerprint: FP, verified: true, attempts: 1, reason: 'registered_verified' });
+  assert.equal(calls.length, 1, 'one POST');
+  assert.deepEqual(calls[0], [ED, 'devbox-app test']);
+  assert.deepEqual(sleep.waits, [], 'no backoff on a clean run');
+});
+
+test('a transient failure is RETRIED with backoff, not dropped', async () => {
+  let n = 0;
+  const sleep = fakeSleep();
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => { n += 1; if (n < 3) throw new Error('socket hang up'); },
+    listKeys: async () => ({ keys: [{ fingerprint: FP }] }),
+    sleep,
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.attempts, 3, 'kept trying instead of giving up on the first error');
+  assert.deepEqual(sleep.waits, [1000, 2000], 'backed off 1s then 2s between attempts');
+});
+
+test('a 201 that did NOT land is reported as verify_failed, not success', async () => {
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => ({ ok: true }),
+    listKeys: async () => ({ keys: [] }),
+    sleep: fakeSleep(),
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.verified, false);
+  assert.equal(r.reason, 'verify_failed');
+  assert.equal(r.fingerprint, FP);
+});
+
+test('every attempt failing returns register_failed and never throws', async () => {
+  const sleep = fakeSleep();
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => { throw new Error('HTTP 500'); },
+    listKeys: async () => ({ keys: [] }),
+    sleep,
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'register_failed');
+  assert.equal(r.attempts, 3);
+  assert.deepEqual(sleep.waits, [1000, 2000], 'exhausted the budget before conceding');
+  assert.match(r.detail, /HTTP 500/);
+});
+
+test('a key already on the account verifies even when the POST keeps failing', async () => {
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => { throw new Error('offline'); },
+    listKeys: async () => ({ keys: [{ fingerprint: FP }] }),
+    sleep: fakeSleep(),
+  });
+  assert.equal(r.ok, true, 'presence on the server is the goal; the POST is only the means');
+  assert.equal(r.reason, 'registered_verified');
+});
+
+test('an unreadable key list is list_failed — never a false green', async () => {
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => ({ ok: true }),
+    listKeys: async () => { throw new Error('HTTP 401'); },
+    sleep: fakeSleep(),
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'list_failed');
+  assert.equal(r.verified, false);
+});
+
+test('a bare array from listKeys is accepted too', async () => {
+  const r = await registerKeyWithVerify({
+    publicKey: ED,
+    registerKey: async () => ({ ok: true }),
+    listKeys: async () => [{ fingerprint: FP }],
+    sleep: fakeSleep(),
+  });
+  assert.equal(r.ok, true);
+});
+
+// --- hashed known_hosts ----------------------------------------------------
+
+// Build the hashed field-1 OpenSSH writes for `host`: |1|<b64 salt>|<b64 HMAC-SHA1>.
+function hashedField(host, saltBytes = crypto.randomBytes(20)) {
+  const hash = crypto.createHmac('sha1', saltBytes).update(host).digest('base64');
+  return `|1|${saltBytes.toString('base64')}|${hash}`;
+}
+
+test('mergeKnownHosts drops a HASHED line for the host and keeps one for another host', () => {
+  const mine = `${hashedField(HOST)} ssh-ed25519 STALEKEY`;
+  const other = `${hashedField('unrelated.example.com')} ssh-ed25519 OTHERKEY`;
+  const out = mergeKnownHosts(`${mine}\n${other}\n`, HOST, [`${HOST} ${ED}`]);
+  assert.ok(!out.includes('STALEKEY'), 'the hashed entry for this host is REPLACED, not appended beside');
+  assert.ok(out.includes('OTHERKEY'), 'another host stays put');
+  assert.ok(out.includes(`${HOST} ${ED}`), 'the fresh key is written');
+});
+
+test('mergeKnownHosts still handles plain and host,ip entries, and keeps comments', () => {
+  const existing = [
+    '# my known hosts',
+    `${HOST} ssh-ed25519 STALE1`,
+    `${HOST},203.0.113.9 ssh-ed25519 STALE2`,
+    'other.example.com ssh-ed25519 KEEPME',
+  ].join('\n');
+  const out = mergeKnownHosts(existing, HOST, [`${HOST} ${ED}`]);
+  assert.ok(out.startsWith('# my known hosts'), 'comments survive');
+  assert.ok(!out.includes('STALE1'));
+  assert.ok(!out.includes('STALE2'), 'a host,ip entry names this host too');
+  assert.ok(out.includes('KEEPME'));
+});
+
+test('mergeKnownHosts is idempotent — a re-pin does not accumulate', () => {
+  const first = mergeKnownHosts('', HOST, [`${HOST} ${ED}`]);
+  const second = mergeKnownHosts(first, HOST, [`${HOST} ${ED}`]);
+  assert.equal(second, first);
+  assert.equal(second.split('\n').filter((l) => l.trim()).length, 1);
+});
+
+test('knownHostsLineMatchesHost: hashed match, wrong host, junk salt, comments', () => {
+  const salt = crypto.randomBytes(20);
+  assert.equal(knownHostsLineMatchesHost(`${hashedField(HOST, salt)} ssh-ed25519 K`, HOST), true);
+  assert.equal(knownHostsLineMatchesHost(`${hashedField(HOST, salt)} ssh-ed25519 K`, 'nope.example.com'), false);
+  assert.equal(knownHostsLineMatchesHost('|1||  ssh-ed25519 K', HOST), false, 'malformed hashed field never matches');
+  assert.equal(knownHostsLineMatchesHost(`# ${HOST}`, HOST), false, 'comments are not host lines');
+  assert.equal(knownHostsLineMatchesHost('', HOST), false);
+  assert.equal(knownHostsLineMatchesHost(`${HOST} ssh-ed25519 K`, ''), false, 'no hostname → match nothing');
+});
+
+// --- host-key staleness ----------------------------------------------------
+
+test('reportedKeysAreStale agrees with the server-side boxes.hostKeysAreStale', () => {
+  const cases = [
+    { hostKeysAt: '2026-07-01T10:00:00Z', activeSince: '2026-07-01T09:00:00Z' }, // fresh
+    { hostKeysAt: '2026-07-01T08:00:00Z', activeSince: '2026-07-01T09:00:00Z' }, // rebuilt since
+    { hostKeysAt: null, activeSince: '2026-07-01T09:00:00Z' },
+    { hostKeysAt: '2026-07-01T10:00:00Z', activeSince: null },
+    { hostKeysAt: null, activeSince: null },
+    { hostKeysAt: 'not-a-date', activeSince: '2026-07-01T09:00:00Z' },
+  ];
+  const expected = [false, true, true, true, true, true];
+  for (const [i, c] of cases.entries()) {
+    assert.equal(reportedKeysAreStale(c), expected[i], `app helper, case ${i}: ${JSON.stringify(c)}`);
+    assert.equal(boxes.hostKeysAreStale(c), expected[i], `server helper, case ${i}: ${JSON.stringify(c)}`);
+  }
+});
+
+test('hostKeysAreStale accepts Date objects and an equal timestamp is fresh', () => {
+  const t = new Date('2026-07-01T09:00:00Z');
+  assert.equal(boxes.hostKeysAreStale({ hostKeysAt: t, activeSince: t }), false);
+  assert.equal(reportedKeysAreStale({ hostKeysAt: t, activeSince: t }), false);
+  assert.equal(boxes.hostKeysAreStale({ hostKeysAt: new Date('2026-07-01T08:59:59Z'), activeSince: t }), true);
+});

package/tests/docs_openapi_route.mjs

@@ -0,0 +1,110 @@
+// tests/docs_openapi_route.mjs
+//
+// /docs/openapi.json is SELF-HEALING (task 1002200): it serves the committed
+// OpenAPI spec when present (instance repo → core package) and otherwise GENERATES
+// it in-process from the live route source. This guards both the happy path (the
+// route returns a valid 3.1 spec with CORS) and the fallback ladder
+// (resolveOpenapiJson prefers committed files, skips corrupt/missing ones, and
+// falls back to generation) — the exact failure that 404'd cloudbongos.com's /docs
+// (a pinned @bongos/core whose package shipped public-docs/ but not docs/api/).
+//
+// serve-internal is DB-free (the pg pool connects lazily), so we mount it on a
+// throwaway express app and hit the route over loopback — same pattern as
+// tests/client_bundle_route.mjs.
+//
+// Run:  node --test tests/docs_openapi_route.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { resolveOpenapiJson } = require('../src/bongos/serve-internal.js');
+
+async function withServer(fn) {
+  const express = require('express');
+  const { mountInternalSurfaces } = require('../src/bongos/serve-internal.js');
+  const app = express();
+  mountInternalSurfaces(app);
+  const server = await new Promise((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  try {
+    await fn(`http://127.0.0.1:${server.address().port}`);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+test('/docs/openapi.json serves a valid OpenAPI 3.1 spec with CORS', async () => {
+  await withServer(async (base) => {
+    const res = await fetch(base + '/docs/openapi.json');
+    assert.equal(res.status, 200);
+    assert.match(res.headers.get('content-type') || '', /application\/json/);
+    assert.equal(res.headers.get('access-control-allow-origin'), '*', 'spec is CORS-open for external tools');
+    const body = await res.text();
+    const spec = JSON.parse(body);
+    assert.equal(spec.openapi, '3.1.0');
+    assert.ok(spec.paths && Object.keys(spec.paths).length > 0, 'spec advertises paths');
+    assert.ok(spec.info && spec.info.title, 'spec carries an info.title');
+    // Zero behaviour change on a healthy deploy: when the committed spec is present
+    // (the common case) it is served verbatim — the committed file wins, generation
+    // is only the fallback tier.
+    const committed = fs.readFileSync(path.join(ROOT, 'docs/api/openapi.json'), 'utf8');
+    assert.equal(body, committed, 'served bytes equal the committed spec (committed file preferred over generation)');
+  });
+});
+
+test('/docs Redoc page points at the same-origin spec URL it now always serves', async () => {
+  await withServer(async (base) => {
+    const res = await fetch(base + '/docs');
+    assert.equal(res.status, 200);
+    const html = await res.text();
+    assert.match(html, /spec-url="\/docs\/openapi\.json"/, 'Redoc host page fetches /docs/openapi.json');
+  });
+});
+
+test('resolveOpenapiJson: serves the first committed candidate that parses', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openapi-'));
+  const first = path.join(dir, 'a.json');
+  const second = path.join(dir, 'b.json');
+  fs.writeFileSync(first, '{"openapi":"3.1.0","from":"a"}');
+  fs.writeFileSync(second, '{"openapi":"3.1.0","from":"b"}');
+  const out = resolveOpenapiJson({ candidates: [first, second], generate: () => 'GENERATED' });
+  assert.equal(JSON.parse(out).from, 'a', 'first existing candidate wins (instance repo before core package)');
+});
+
+test('resolveOpenapiJson: skips a missing candidate, then a corrupt one, then generates', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'openapi-'));
+  const corrupt = path.join(dir, 'corrupt.json');
+  fs.writeFileSync(corrupt, '{ this is not valid json ');
+  const out = resolveOpenapiJson({
+    candidates: [path.join(dir, 'missing.json'), corrupt],
+    generate: () => 'GENERATED',
+  });
+  assert.equal(out, 'GENERATED', 'a missing file and a corrupt file both fall through to generation');
+});
+
+test('resolveOpenapiJson: degrades to empty string (→ 404) instead of crashing', () => {
+  assert.equal(resolveOpenapiJson({ candidates: [], generate: () => '' }), '');
+  assert.equal(
+    resolveOpenapiJson({ candidates: ['/no/such/file.json'], generate() { throw new Error('boom'); } }),
+    '',
+    'a throwing generator degrades to 404, never takes down the route',
+  );
+});
+
+test('the in-process generation tier really yields a structurally valid spec', () => {
+  // This is the tier that heals a standalone/missing-file deploy: no file on disk,
+  // spec built from the live route source. Prove it produces a valid OpenAPI 3.1.
+  const gen = require('../scripts/gds/gen-api-docs.js');
+  const { spec } = gen.build();
+  assert.equal(spec.openapi, '3.1.0');
+  assert.ok(Object.keys(spec.paths).length > 0, 'generated spec advertises paths');
+  assert.equal(gen.validateOpenapi(spec).length, 0, 'generated spec is structurally valid OpenAPI 3.1');
+});