@bongos/core 1.19.789 → 1.19.790

package/tests/core_upgrade_door.mjs

@@ -0,0 +1,408 @@
+// tests/core_upgrade_door.mjs — the owner's deploy door (task 1003159, ADR 0293).
+//
+// WHAT IS ACTUALLY AT RISK HERE. Enrolling the control plane as a row in
+// provisioning_instances is what gives the deploy door something to point at —
+// `provisioning_intents.instance_id` is NOT NULL, so an intent must name a row.
+// The same row makes 'teardown' a button that would destroy the platform from
+// inside the platform's own UI. `intentAllowedForShape` is the single place that
+// decides, and these cases are what keep it honest.
+//
+// The guard is an ALLOW-list on purpose (ADR 0293 D2). A deny-list of today's
+// destructive actions would silently admit tomorrow's, and the failure direction
+// of "admitted by omission" is the platform deleting itself.
+//
+// Run:  node tests/core_upgrade_door.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const P = require('../modules/provisioning/provisioning.js');
+// The guard is its own module, and callers import it DIRECTLY rather than through
+// provisioning.js: that file sits on the oversized-file ratchet at its ceiling, so a
+// re-export there costs a line the build will not give back. Importing the thing
+// itself is also the honest shape - the guard is not provisioning's to own.
+const G = require('../modules/provisioning/control-plane-guard.js');
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+const read = (...p) => readFileSync(join(repoRoot, ...p), 'utf8');
+
+let passed = 0;
+let failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+console.log('\nthe vocabulary:');
+
+await t('core-upgrade is a queueable intent action', () => {
+  assert.ok(P.INTENT_ACTIONS.includes('core-upgrade'));
+});
+
+await t('control-plane is a hosting shape', () => {
+  assert.ok(P.HOSTING_SHAPES.includes('control-plane'));
+});
+
+await t('the shape and the action both reach the DB constraints', () => {
+  // The JS list and the CHECK are two spellings of one vocabulary; a widening that
+  // lands in only one of them fails at insert time, in production, on the first
+  // real use. (The bug class task 1003913 shipped a fix for, in another file.)
+  const mig = read('modules', 'provisioning', 'migrations', 'provisioning_018_core_upgrade_intent.sql')
+    .replace(/^\s*--.*$/gm, ' ').replace(/\s+/g, ' ');
+  assert.match(mig, /CHECK \(action IN \([^)]*'core-upgrade'\)\)/, 'the intents CHECK admits the new action');
+  assert.match(mig, /CHECK \(hosting_shape IN \([^)]*'control-plane'\)\)/, 'the instances CHECK admits the new shape');
+  for (const a of P.INTENT_ACTIONS) {
+    assert.ok(mig.includes(`'${a}'`), `the widened CHECK must still carry '${a}' — a rewrite drops what it forgets`);
+  }
+});
+
+console.log('\nthe guard — what may be aimed at the platform itself:');
+
+await t('TEARDOWN IS REFUSED on the control-plane row', () => {
+  // The case this whole file exists for.
+  assert.equal(G.intentAllowedForShape('teardown', 'control-plane'), false);
+});
+
+await t('every action not explicitly allowed is refused on the self row', () => {
+  const allowed = new Set(G.CONTROL_PLANE_ACTIONS);
+  for (const a of P.INTENT_ACTIONS) {
+    assert.equal(
+      G.intentAllowedForShape(a, 'control-plane'),
+      allowed.has(a),
+      `'${a}' on the control-plane row must be ${allowed.has(a) ? 'allowed' : 'refused'}`,
+    );
+  }
+});
+
+await t('the allow-list is exactly the two acts that cannot destroy the box', () => {
+  // Pinned by NAME so widening it is a deliberate edit someone has to argue for,
+  // not a side effect of adding an action to INTENT_ACTIONS.
+  assert.deepEqual([...G.CONTROL_PLANE_ACTIONS].sort(), ['core-upgrade', 'restart']);
+});
+
+await t('an ordinary instance is untouched by the guard', () => {
+  for (const shape of ['co-tenant', 'dedicated', 'standalone']) {
+    for (const a of P.INTENT_ACTIONS) {
+      assert.equal(G.intentAllowedForShape(a, shape), true, `${a}/${shape} must be unaffected`);
+    }
+  }
+});
+
+await t('an UNKNOWN shape is treated as ordinary, not as the control plane', () => {
+  // Deliberate: the guard protects one specific row. Failing closed on every
+  // unrecognised shape would break provisioning for a shape added later without
+  // touching this list, and that is a bigger blast radius than the thing guarded.
+  assert.equal(G.intentAllowedForShape('teardown', 'something-new'), true);
+  assert.equal(G.intentAllowedForShape('teardown', undefined), true);
+  assert.equal(G.intentAllowedForShape('teardown', null), true);
+});
+
+console.log('\nat most one self row:');
+
+await t('the migration makes a second control-plane row impossible', () => {
+  // Two self rows would make "which one is me?" a question with no answer, and the
+  // door would point at whichever the query returned first.
+  const mig = read('modules', 'provisioning', 'migrations', 'provisioning_018_core_upgrade_intent.sql')
+    .replace(/\s+/g, ' ');
+  assert.match(mig, /CREATE UNIQUE INDEX IF NOT EXISTS provisioning_instances_one_control_plane_idx/);
+  assert.match(mig, /WHERE hosting_shape = 'control-plane'/, 'partial, so it constrains only the self row');
+});
+
+console.log('\nthe ledger records WHO (ADR 0293 D5):');
+
+await t('core_241 adds an actor and a source, and binds the door to naming one', () => {
+  const mig = read('migrations', 'core_241_core_upgrades_actor.sql')
+    .replace(/^\s*--.*$/gm, ' ').replace(/\s+/g, ' ');
+  assert.match(mig, /ADD COLUMN IF NOT EXISTS requested_by_builder_id bigint REFERENCES builders\(id\) ON DELETE SET NULL/);
+  assert.match(mig, /source IS NULL OR source IN \('shell', 'owner-control'\)/);
+  assert.match(
+    mig,
+    /source IS DISTINCT FROM 'owner-control' OR requested_by_builder_id IS NOT NULL/,
+    'an upgrade through the DOOR must name its actor',
+  );
+  assert.match(mig, /NOT VALID/, 'without scanning history that predates the concept');
+});
+
+await t('the actor column is NULLABLE — the shell path must keep working', () => {
+  const mig = read('migrations', 'core_241_core_upgrades_actor.sql');
+  assert.doesNotMatch(
+    mig.replace(/^\s*--.*$/gm, ''),
+    /requested_by_builder_id bigint[^;]*NOT NULL/,
+    'a human at a shell has no builder to attribute; this column is not a gate on the CLI path',
+  );
+});
+
+const CU = require('../modules/provisioning/core-upgrade.js');
+
+const ACTIVE = Object.freeze({ id: 7, slug: 'cloudbongos', status: 'active', hosting_shape: 'control-plane', owner_builder_id: 3, core_version: '1.19.754' });
+
+console.log('\nwhat the door refuses, before anything is queued:');
+
+await t('a version that is not three numbers is refused', () => {
+  for (const bad of ['latest', '1.19', 'v1.19.757', '1.19.757-rc1', '', '  ', 'DROP TABLE']) {
+    const f = CU.coreUpgradeFault(ACTIVE, bad);
+    assert.ok(f, `'${bad}' must be refused`);
+    assert.equal(f.code, 'bad_target_version', `'${bad}'`);
+    assert.equal(f.status, 400);
+  }
+});
+
+await t('a well-formed version is admitted', () => {
+  assert.equal(CU.coreUpgradeFault(ACTIVE, '1.19.757'), null);
+});
+
+await t('the version ALREADY running is refused rather than restarting to change nothing', () => {
+  const f = CU.coreUpgradeFault(ACTIVE, '1.19.754', '1.19.754');
+  assert.ok(f);
+  assert.equal(f.code, 'already_on_version');
+  assert.match(f.message, /already runs core 1\.19\.754/);
+});
+
+await t('an instance that is not ACTIVE has no settled pin to move', () => {
+  for (const status of ['provisioning', 'tearing_down', 'torn_down', 'error']) {
+    const f = CU.coreUpgradeFault({ ...ACTIVE, status }, '1.19.757');
+    assert.ok(f, status);
+    assert.equal(f.code, 'not_upgradable', status);
+  }
+});
+
+await t('a shape the platform does not manage is refused, and that check runs FIRST', () => {
+  // Ordering matters: the shape check protects the platform, the others protect
+  // the caller from a mistake. A dedicated droplet has no runner exec path, so
+  // queueing would be the F16 lie — a request that never lands.
+  //
+  // NB the shape refusal here is UPGRADE_SHAPES alone. This test used to be named
+  // for the self-row guard running first, which it never exercised — see the
+  // vacuity case below for why that call is not made at all.
+  const f = CU.coreUpgradeFault({ ...ACTIVE, hosting_shape: 'dedicated', status: 'torn_down' }, 'nonsense');
+  assert.ok(f);
+  assert.equal(f.code, 'core_upgrade_unavailable',
+    'the shape refusal wins over the state and format ones');
+  // And a dedicated droplet is refused even when everything else is perfect —
+  // the runner has no exec path to it, so queueing would be accepted and never land.
+  const clean = CU.coreUpgradeFault({ ...ACTIVE, hosting_shape: 'dedicated' }, '1.19.757');
+  assert.ok(clean, 'a dedicated droplet is refused on shape alone');
+  assert.equal(clean.code, 'core_upgrade_unavailable');
+});
+
+await t('no refusal message promises a duration (ADR 0190 §7)', () => {
+  const messages = [
+    CU.coreUpgradeFault({ ...ACTIVE, hosting_shape: 'dedicated' }, '1.19.757'),
+    CU.coreUpgradeFault({ ...ACTIVE, hosting_shape: 'control-plane', status: 'provisioning' }, '1.19.757'),
+    CU.coreUpgradeFault({ ...ACTIVE, status: 'torn_down' }, '1.19.757'),
+    CU.coreUpgradeFault(ACTIVE, 'latest'),
+    CU.coreUpgradeFault(ACTIVE, '1.19.754', '1.19.754'),
+  ].map((f) => f.message);
+  for (const m of messages) {
+    assert.doesNotMatch(m, /\b(minute|second|hour|shortly|soon)\b/i, m);
+  }
+});
+
+console.log('\nthe gate — the DONE-WHEN clause:');
+
+await t('A NON-ARCHON IS REFUSED: the route gates on core.pin.move, an archon-floor system atom', () => {
+  // The task's explicit DONE-WHEN. Asserted at the DECLARATION rather than by
+  // driving express, because the gate IS the middleware list: a handler test would
+  // pass just as happily with the gate deleted.
+  // Comments stripped FIRST: the route's own header names requireRank to explain
+  // why it is not used, and a raw-text scan reads that prose as the forbidden call.
+  // Exactly the defect filed as task 1003832 against government_require_permission.
+  const route = read('modules', 'provisioning', 'routes', 'core-upgrade.js')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/^\s*\/\/.*$/gm, ' ')
+    .replace(/\s+/g, ' ');
+  assert.match(route, /api\.requirePermission\('core\.pin\.move'\)/, 'the atom gates the route');
+  assert.match(route, /api\.requireBuilder/, 'and an anonymous caller never reaches it');
+  assert.doesNotMatch(route, /requireRank/, 'BV1.R105: a modules/*/routes gate is an atom, never a rank');
+
+  const catalog = read('modules', 'government', 'catalog.js');
+  const entry = catalog.split('\n').find((l) => l.includes("key: 'core.pin.move'"));
+  assert.ok(entry, 'the atom is in the catalog');
+  assert.match(entry, /floor: 'archon'/, 'archon floor — deploy is a hard gate the owner holds');
+  assert.match(entry, /system: true/,
+    'system:true is what makes it UN-DELEGATABLE: the catalog invariant forbids granting a system key to metic');
+});
+
+await t('the grant migration gives it to archon and to NOBODY else', () => {
+  const mig = read('modules', 'government', 'migrations', 'government_014_core_pin_move.sql')
+    .replace(/^\s*--.*$/gm, ' ');
+  assert.match(mig, /SELECT 'archon', unnest\(ARRAY\[\s*'core\.pin\.move'/);
+  assert.doesNotMatch(mig, /SELECT 'metic'/, 'no metic grant — the absence is the point');
+});
+
+console.log('\nthe web tier only ASKS (ADR 0111 §2 / ADR 0293 D1):');
+
+await t('nothing in the door shells out, escalates, or reaches the control plane', () => {
+  // The rule that makes a stolen builder token unable to deploy. Asserted over both
+  // web-tier files, comments stripped so prose describing the runner is not read as
+  // the web tier doing it.
+  for (const f of [['modules', 'provisioning', 'core-upgrade.js'], ['modules', 'provisioning', 'routes', 'core-upgrade.js']]) {
+    const code = read(...f)
+      .replace(/\/\*[\s\S]*?\*\//g, ' ')
+      .replace(/^\s*\/\/.*$/gm, ' ');
+    for (const forbidden of ['child_process', 'spawnSync', 'execSync', 'sudo ', 'ssh ']) {
+      assert.ok(!code.includes(forbidden), `${f.join('/')} must not reference ${forbidden}`);
+    }
+  }
+});
+
+await t('the handler queues an intent carrying the TARGET, and records the actor', async () => {
+  const calls = [];
+  const provisioning = {
+    getInstanceById: async () => ACTIVE,
+    enqueueIntent: async (_db, id, action, requestedBy, targetVersion) => {
+      calls.push({ id, action, requestedBy, targetVersion });
+      return { intent: { id: 1, action, state: 'pending', target_version: targetVersion }, created: true };
+    },
+    recordEvent: async (_db, e) => { calls.push({ event: e.event, actor: e.actor }); },
+  };
+  const handler = CU.makeCoreUpgradeHandler({
+    provisioning, pool: {}, parseId: () => 7,
+    validateOrRespond: () => false, log: { error() {} },
+  });
+  let body = null;
+  const res = { json: (b) => { body = b; return res; }, fail: (code, o) => { body = { code, ...o }; return res; } };
+  await handler({ builder: { id: 42 }, params: { id: '7' }, body: { to: '1.19.757' } }, res);
+
+  const enqueued = calls.find((c) => c.action === 'core-upgrade');
+  assert.ok(enqueued, 'an intent was queued');
+  assert.equal(enqueued.targetVersion, '1.19.757', 'carrying the version the owner confirmed');
+  assert.equal(enqueued.requestedBy, 'api:archon:42', 'attributed to the caller');
+  assert.ok(calls.some((c) => c.event === 'core-upgrade' && c.actor === 'api:archon:42'), 'and audited');
+  assert.equal(body.queued, true);
+  assert.equal(body.target_version, '1.19.757');
+  assert.doesNotMatch(body.message, /\b(minute|second|hour)\b/i, 'no duration is promised');
+});
+
+await t('a SECOND request conflicts rather than reporting the first as done', async () => {
+  // Unlike a duplicate restart, which IS the thing asked for. This one names a
+  // target, and the open intent may name a different one — reporting that as
+  // success would tell the owner their version is coming when another is.
+  const provisioning = {
+    getInstanceById: async () => ACTIVE,
+    enqueueIntent: async () => ({ intent: { action: 'core-upgrade', state: 'running', target_version: '1.19.756' }, created: false }),
+    recordEvent: async () => {},
+  };
+  const handler = CU.makeCoreUpgradeHandler({
+    provisioning, pool: {}, parseId: () => 7,
+    validateOrRespond: () => false, log: { error() {} },
+  });
+  let body = null;
+  const res = { json: (b) => { body = b; return res; }, fail: (code, o) => { body = { code, ...o }; return res; } };
+  await handler({ builder: { id: 42 }, params: { id: '7' }, body: { to: '1.19.757' } }, res);
+  assert.equal(body.code, 'intent_conflict');
+  assert.equal(body.status, 409);
+  assert.equal(body.details.target_version, '1.19.756', 'and it names the target already in flight');
+});
+
+await t('the handler does NOT read a core_version column, because there is none', () => {
+  // The first cut passed `inst.core_version || null`, which is always undefined —
+  // so the already-on-version refusal was unreachable from the route while reading
+  // as a live guard. Pinned from both ends: the schema has no such column, and the
+  // handler does not name it.
+  const migs = ['provisioning_001_tables.sql', 'provisioning_018_core_upgrade_intent.sql']
+    .map((f) => read('modules', 'provisioning', 'migrations', f)).join('\n');
+  assert.doesNotMatch(migs, /core_version/, 'no migration adds the column');
+  const code = read('modules', 'provisioning', 'core-upgrade.js')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/^\s*\/\/.*$/gm, ' ');
+  assert.doesNotMatch(code, /inst\.core_version/, 'and the handler does not pretend to read it');
+});
+
+await t('THE SELF-ROW GUARD IS VACUOUS FOR THIS ACTION, so neither door half may call it as a gate', () => {
+  // The failure this pins is a guard that reads as present and can never fire —
+  // the third instance of that shape on this one task. `intentAllowedForShape`
+  // answers TRUE for 'core-upgrade' against every shape there is: for a tenant
+  // shape unconditionally, and for the control plane because the action is
+  // permanently on CONTROL_PLANE_ACTIONS. A reader scanning either file would
+  // reasonably believe two gates stood there; only one ever did.
+  for (const shape of [...P.HOSTING_SHAPES, 'something-new', undefined, null]) {
+    assert.equal(G.intentAllowedForShape('core-upgrade', shape), true,
+      `the guard cannot refuse core-upgrade for shape '${shape}' — so calling it as a gate is dead code`);
+  }
+  // Neither half of the door may name it. If a later edit puts it back, this fails
+  // and points at the sentence above rather than at a mystery.
+  for (const f of [['modules', 'provisioning', 'core-upgrade.js'], ['scripts', 'gds', 'provision-core-upgrade.js']]) {
+    const src = read(...f).replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/^\s*\/\/.*$/gm, ' ');
+    assert.ok(!/intentAllowedForShape\s*\(/.test(src),
+      `${f.join('/')} must not call intentAllowedForShape — it can only ever return true here`);
+  }
+});
+
+console.log('\nthe preview — step one of the two-step (ADR 0293 D4):');
+
+const previewInst = { id: 7, slug: 'cloudbongos', hosting_shape: 'control-plane' };
+
+await t('a box behind a published version reads as behind, and names what it would move to', () => {
+  const p = CU.previewFromSnapshot(previewInst,
+    { served_version: '1.19.758', available: ['1.19.758', '1.19.762'], recommended: '1.19.762', observed_at: '2026-09-16T10:00:00Z' }, null);
+  assert.equal(p.served_version, '1.19.758');
+  assert.equal(p.recommended_version, '1.19.762');
+  assert.equal(p.behind, true);
+  assert.equal(p.reading, 'ok');
+  assert.equal(p.observed_at, '2026-09-16T10:00:00Z', 'the age of the reading is part of the answer, never hidden');
+});
+
+await t('a box already on the newest is NOT behind, and offers nothing', () => {
+  const p = CU.previewFromSnapshot(previewInst,
+    { served_version: '1.19.762', available: ['1.19.762'], recommended: '1.19.762', observed_at: 'x' }, null);
+  assert.equal(p.behind, false);
+});
+
+await t('A BOX THAT DID NOT ANSWER IS "no_answer", NEVER a confident "up to date"', () => {
+  // The failure this pins: collapsing an unread box into `behind:false` renders as
+  // "nothing to deploy" over a box whose version nobody actually knows.
+  const p = CU.previewFromSnapshot(previewInst,
+    { served_version: null, available: ['1.19.762'], recommended: null, observed_at: 'x' }, null);
+  assert.equal(p.reading, 'no_answer');
+  assert.equal(p.served_version, null);
+  assert.equal(p.behind, false);
+});
+
+await t('no snapshot at all reports observed_at:null rather than a confident-looking empty reading', () => {
+  const p = CU.previewFromSnapshot(previewInst, undefined, null);
+  assert.equal(p.observed_at, null);
+  assert.equal(p.reading, 'no_answer');
+  assert.equal(p.available_count, 0);
+});
+
+await t('an open intent is surfaced with its target, so the page can say what is already running', () => {
+  const p = CU.previewFromSnapshot(previewInst, { served_version: '1.19.758', available: [], recommended: null },
+    { action: 'core-upgrade', state: 'running', target_version: '1.19.762' });
+  assert.deepEqual(p.open_intent, { action: 'core-upgrade', state: 'running', target_version: '1.19.762' });
+});
+
+console.log('\nthe deploy page is gated on the same atom as its routes:');
+
+await t('the page gate, the preview and the move all check core.pin.move — the shell can never drift wider than the button', () => {
+  const routes = read('modules', 'provisioning', 'routes', 'core-upgrade.js');
+  const gates = routes.match(/requirePermission\('([^']+)'\)/g) || [];
+  assert.ok(gates.length >= 3, 'all three routes carry a gate');
+  for (const g of gates) assert.match(g, /core\.pin\.move/, `every gate on this router is the same atom: ${g}`);
+  const auth = read('src', 'bongos', 'auth.js');
+  assert.match(auth, /requireCorePinPage: Object\.freeze\(\{ permission: 'core\.pin\.move'/, 'and the page gate is the same key');
+  const serve = read('src', 'bongos', 'serve-internal.js');
+  assert.match(serve, /const DEPLOY_PAGE_RE = \/\^\\\/builders\\\/deploy/, 'the page is matched');
+  assert.match(serve, /DEPLOY_PAGE_RE\.test\(norm\)\) \{\s*\n\s*return gdsAuth\.requireCorePinPage/, 'and dispatched to that gate');
+});
+
+await t('THE DEPLOY PAGE NEVER COMPUTES A VERSION COMPARISON — every number on it is a reading the server handed it', () => {
+  // The failure this pins is subtle and expensive: a page that decides for itself
+  // whether the box is behind will, one release later, disagree with the runner that
+  // actually performs the move — on the screen the owner trusts most.
+  const js = read('modules', 'hall-ui', 'public', 'deploy.js')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/^\s*\/\/.*$/gm, ' ');
+  assert.ok(!/localeCompare|semver|\.split\('\.'\)/.test(js), 'no version arithmetic on the client');
+  assert.ok(!/\bconst\s+\w*VERSION\w*\s*=\s*'/.test(js), 'no version literal baked into the page');
+  assert.match(js, /p\.recommended_version/, 'it sends the version the SERVER named');
+  assert.match(js, /p\.behind/, 'and asks the server whether there is anything to do');
+});
+
+console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);