@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/provision-disconnect.js

@@ -0,0 +1,88 @@
+'use strict';
+// provision-disconnect.js — "Disconnect from Bongos entirely": the runner leg (task 1003249,
+// ADR 0290).
+//
+// WHY. A teardown deliberately KEEPS a project's database, dumps and address (ADR 0181), so
+// taking a project offline is always reversible. The owner asked for a separate, truer delete.
+// This is it, and it is the exception ADR 0181 names: owner-initiated only, behind a typed-name
+// confirm the route checks server-side (modules/provisioning/routes/disconnect.js).
+//
+// ORDER IS THE SAFETY PROPERTY. The teardown runs first (units stopped, Caddy block gone, DNS
+// parked, deploy key revoked). Then the erase. Then the catalog, membership and client rows
+// leave the map. The provisioning row is deleted LAST, and only when everything before it
+// succeeded: the row is what lets the runner retry, so a failure anywhere leaves the row intact
+// (an erase or forget failure returns a retryable { ok:false }; a teardown throw propagates).
+// Deleting the row is what releases the name (slug UNIQUE), the port (allocatePort reads every
+// row) and the address (the next standup UPSERTs it).
+//
+// The GitHub repository is never touched, and neither is the GitHub App the owner registered for
+// sign-in — GitHub offers no API to delete an App; the manage page tells the owner where it is.
+
+const path = require('node:path');
+const { CONFIG } = require('./provision-config.js');
+const { dbName, instanceDbRole, instanceStateDir, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const { webEnvPath } = require('./provision-units.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+const { catalogOriginForInstance, ownerGithubIdForInstance } = require('../../modules/provisioning/catalog-bridge.js');
+const { deleteInstance } = require('../../modules/provisioning/disconnect.js');
+
+// The dump filename db-backup-nightly.sh writes — <db>-YYYY-MM-DDTHHMMSSZ.sql.gz — matched
+// EXACTLY, as the nightly prune's DUMP_GLOB does (task 1003948): a looser `<db>-*.sql.gz` would
+// let a project named `test` erase `test-nk`'s dumps. PURE.
+function dumpGlob(inst) {
+  const d = '[0-9]';
+  return `${dbName(inst)}-${d.repeat(4)}-${d.repeat(2)}-${d.repeat(2)}T${d.repeat(6)}Z.sql.gz`;
+}
+
+// The erase, in order: the database before the role that owns it; the dumps; the env dir and
+// state dir; the per-project checkout (standalone only — a co-tenant runs from the shared one);
+// the unix account last, idempotently. Every path derives from a slug the caller has already
+// validated. PURE.
+function eraseCommands(inst, { privileged = false } = {}) {
+  const sudo = privileged ? 'sudo ' : '';
+  const asPg = (cmd) => (privileged ? `sudo -u postgres ${cmd}` : cmd);
+  const user = instanceUser(inst);
+  const cmds = [
+    asPg(`dropdb --if-exists --force ${dbName(inst)}`),
+    asPg(`psql -v ON_ERROR_STOP=1 -d postgres -c 'DROP ROLE IF EXISTS "${instanceDbRole(inst)}"'`),
+    `${sudo}find ${CONFIG.backupDir} -maxdepth 1 -type f -name '${dumpGlob(inst)}' -delete`,
+    `${sudo}rm -rf ${path.posix.dirname(webEnvPath(inst))} ${instanceStateDir(inst)}`,
+  ];
+  if (inst.hosting_shape === 'cloud-host') cmds.push(`${sudo}rm -rf ${standaloneRoot(inst)}`);
+  cmds.push(`if id -u ${user} >/dev/null 2>&1; then ${sudo}userdel ${user}; fi`);
+  return cmds;
+}
+
+async function disconnectInstance(inst, deps) {
+  const { db, exec, log, apply, privileged } = deps;
+  // Every rm -rf below is built from the slug, so it is re-validated here rather than trusted.
+  if (!inst || !isValidSlug(inst.slug)) return { ok: false, error: `refusing to disconnect: invalid slug ${JSON.stringify(inst && inst.slug)}` };
+  log(`disconnect ${inst.slug} (status=${inst.status})`);
+  // A teardown returns ok or throws; a throw ends the run here, before anything is erased.
+  await teardownInstance(inst, deps);
+
+  const boxExec = inst.hosting_shape === 'cloud-host' ? (deps.controlExec || exec) : exec;
+  for (const cmd of eraseCommands(inst, { privileged })) {
+    try { boxExec(cmd); }
+    catch (e) { return { ok: false, error: `erase step failed (${cmd.split(' ').slice(0, 3).join(' ')}): ${(e && e.message) || e}` }; }
+  }
+
+  const origin = catalogOriginForInstance(inst);
+  if (origin && deps.projectCatalog) {
+    if (apply) {
+      try {
+        const ownerGithubId = await ownerGithubIdForInstance(db, inst);
+        const gone = await deps.projectCatalog.forgetOwnedProject({ clientId: inst.slug, origin, ownerGithubId }, { pool: db });
+        log(`  catalog: removed ${gone.project} project row, ${gone.client} client, ${gone.memberships} membership(s)`);
+      } catch (e) { return { ok: false, error: `catalog forget failed: ${(e && e.message) || e}` }; }
+    } else log(`  would remove ${origin} from the catalog`);
+  }
+
+  if (!apply) { log(`  would delete the provisioning row for ${inst.slug}`); return { ok: true }; }
+  await deleteInstance(db, inst.id);
+  log(`  ✓ ${inst.slug} disconnected — row deleted; name, port and address released`);
+  return { ok: true };
+}
+
+module.exports = { disconnectInstance, eraseCommands, dumpGlob };

package/scripts/bongos/provision-github-setup.js

@@ -0,0 +1,168 @@
+'use strict';
+// scripts/bongos/provision-github-setup.js — the control-plane runner's check of the two
+// GitHub steps a founder finishes ON GITHUB after the app exists: "Install it on your repo"
+// and "Command-line sign-in is on" (task 1004649; the checklist is derived in
+// modules/provisioning/github-setup.js).
+//
+// WHY THE RUNNER. Only the runner holds the app's credentials (it placed them in the
+// project's chmod-600 web.env; ADR 0111 §2 / ADR 0133 — the web tier never sees a secret).
+// The setup_url redirect GitHub sends after an install carries an installation_id, but
+// GitHub's own docs warn it can be spoofed, so a tick needs GitHub's answer to a question
+// asked with the app's own key:
+//   install — GET /repos/{owner}/{repo}/installation, authenticated as the app (a JWT
+//             signed with its private key). 200 with an id = installed on THIS repo.
+//   device  — POST github.com/login/device/code with the app's client id. GitHub answers a
+//             device code when device flow is on and `device_flow_disabled` when it is off.
+//             The unused code simply expires; nothing is signed in. GitHub has NO manifest
+//             field and NO API that turns device flow on (spike, task 1004649), so this
+//             only ever OBSERVES the founder's own tick on GitHub.
+// A verified fact is recorded once as a provisioning_events row; the checklist reads it.
+//
+// BOUNDED. Only attempts that settled within VERIFY_WINDOW_MS, or whose install was
+// reported or a check requested within it, are checked, at most SWEEP_LIMIT per tick — so
+// a finished or abandoned project costs nothing, and "Pick up where it stopped" / "Check
+// again" on the project page re-opens the window (task 1004652).
+// SIGN-IN, TOO (task 1004652). An attempt that stopped because the project did not confirm
+// sign-in in time ('error' with the app's keys placed) is re-asked on each tick in the
+// window, with the keys already placed: when the project now answers auth_configured the
+// attempt becomes 'done' — the same app, never a second one.
+// Secrets: web.env is read on the box, parsed in memory, and only NAMES ever reach a log.
+
+const crypto = require('node:crypto');
+const { webEnvPath } = require('./provision-units.js');
+const { SETUP_EVENTS, VERIFY_WINDOW_MS, githubSetupFacts, targetRepo } = require('../../modules/provisioning/github-setup.js');
+const { parseHealthzAuth } = require('./oauth-secret.js');
+
+const SWEEP_LIMIT = 20;
+const UA = 'cloud-bongos-provisioner';
+
+function b64url(input) {
+  return Buffer.from(input).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// An app JWT (RS256, 9 minutes, iat backdated for skew) — GitHub's app authentication.
+function appJwt({ appId, pem, nowSec = Math.floor(Date.now() / 1000) }) {
+  const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const body = b64url(JSON.stringify({ iat: nowSec - 60, exp: nowSec + 9 * 60, iss: String(appId) }));
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(`${head}.${body}`);
+  signer.end();
+  return `${head}.${body}.${b64url(signer.sign(pem))}`;
+}
+
+// The app's id, private key and client id out of a web.env body. The pem is stored as one
+// line with literal \n (provision-units.js webEnvBody); the client id under the pack's
+// prefix, which this does not need to know. Missing pieces are null. PURE.
+function appCredsFromEnv(body) {
+  const val = (re) => { const m = String(body || '').match(re); return m ? m[1].trim() : null; };
+  const pemLine = val(/^GITHUB_APP_PRIVATE_KEY=(.+)$/m);
+  return {
+    appId: val(/^GITHUB_APP_ID=(\d+)\s*$/m),
+    pem: pemLine ? pemLine.replace(/\\n/g, '\n') : null,
+    clientId: val(/^[A-Z0-9_]+_GITHUB_CLIENT_ID=(\S+)\s*$/m),
+  };
+}
+
+// Is the app installed on owner/repo? true · false (404: the app is real, not installed
+// there) · null (cannot tell — any other answer, or no network).
+async function installedOnRepo({ appId, pem, repo, fetchImpl = globalThis.fetch }) {
+  try {
+    const res = await fetchImpl(`https://api.github.com/repos/${repo}/installation`, {
+      headers: { Authorization: `Bearer ${appJwt({ appId, pem })}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': UA },
+    });
+    if (res.status === 404) return false;
+    if (!res.ok) return null;
+    const j = await res.json().catch(() => null);
+    return !!(j && j.id != null);
+  } catch (_) { return null; }
+}
+
+// Does GitHub accept a device-flow start for this client id? true · false
+// (device_flow_disabled) · null (any other answer — never read as "off").
+async function deviceFlowOn({ clientId, fetchImpl = globalThis.fetch }) {
+  try {
+    const res = await fetchImpl('https://github.com/login/device/code', {
+      method: 'POST',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': UA },
+      body: `client_id=${encodeURIComponent(clientId)}`,
+    });
+    const j = await res.json().catch(() => null);
+    if (j && j.device_code) return true;
+    if (j && /device_flow_disabled/.test(String(j.error || ''))) return false;
+    return null;
+  } catch (_) { return null; }
+}
+
+// The attempts worth checking this tick: each instance's LATEST attempt, past the
+// credential placement (an app id recorded), settled or reported within the window.
+async function attemptsToVerify(db) {
+  const windowSec = Math.round(VERIFY_WINDOW_MS / 1000);
+  const { rows } = await db.query(
+    `WITH latest AS (
+       SELECT DISTINCT ON (instance_id) * FROM provisioning_oauth_manifests ORDER BY instance_id, created_at DESC)
+     SELECT l.id, l.instance_id, l.created_at, l.requested_by, l.status, i.slug, i.port, i.target_ref, i.hosting_shape, i.status AS instance_status
+       FROM latest l JOIN provisioning_instances i ON i.id = l.instance_id
+      WHERE l.app_id IS NOT NULL AND l.status IN ('done', 'error') AND i.status = 'active'
+        AND (l.updated_at > now() - ($1 * interval '1 second')
+             OR EXISTS (SELECT 1 FROM provisioning_events e WHERE e.instance_id = l.instance_id
+                         AND e.event = ANY($2) AND e.created_at > now() - ($1 * interval '1 second')))
+      ORDER BY l.updated_at DESC LIMIT ${SWEEP_LIMIT}`,
+    [windowSec, [SETUP_EVENTS.installReported, SETUP_EVENTS.checkRequested]]);
+  return rows;
+}
+
+// Does the project answer that sign-in is configured? The project's JSON health read
+// (the same probe as provision.js authHealthzCmd — the root /healthz says a plain "ok").
+function signInAnswers(r, boxExec) {
+  const out = boxExec(`curl -sS --max-time 5 http://127.0.0.1:${r.port}/api/bongos/healthz`, { allowFail: true });
+  return parseHealthzAuth(out && out.stdout).authConfigured === true;
+}
+
+// One tick: for every attempt in the window, check whatever is not verified yet and record
+// what GitHub confirmed. Returns { checked, installed, deviceFlow }.
+async function verifyGithubAppSetups(deps) {
+  const { db, provisioning, log, apply } = deps;
+  const out = { checked: 0, installed: 0, deviceFlow: 0, signIn: 0 };
+  const rows = await attemptsToVerify(db);
+  if (!apply) {
+    for (const r of rows) log(`  would check the GitHub install + device flow for ${r.slug} (manifest #${r.id})`);
+    return out;
+  }
+  for (const r of rows) {
+    const facts = await githubSetupFacts(db, r.instance_id, r.created_at);
+    const signInStopped = r.status === 'error';
+    if (facts.installedAt && facts.deviceFlowAt && !signInStopped) continue;
+    const onControlBox = r.hosting_shape === 'cloud-host' || r.hosting_shape === 'control-plane';
+    const boxExec = onControlBox ? (deps.controlExec || deps.exec) : deps.exec;
+    if (signInStopped && signInAnswers(r, boxExec)) {
+      await provisioning.resolveOAuthManifest(db, r.id, 'done', { github_code: null });
+      await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: 'oauth-manifest-done',
+        detail: 'sign-in confirmed on a later check, with the app already made', actor: 'runner' }).catch(() => {});
+      out.signIn++; log(`  ✓ ${r.slug}: sign-in now confirmed`);
+    }
+    if (facts.installedAt && facts.deviceFlowAt) { out.checked++; continue; }
+    const read = boxExec(`${deps.privileged ? 'sudo ' : ''}cat ${webEnvPath(r)}`, { allowFail: true });
+    const creds = appCredsFromEnv(read && read.stdout);
+    out.checked++;
+    const repo = targetRepo(r);
+    const fetchImpl = deps.fetchImpl;
+    if (!facts.installedAt && creds.appId && creds.pem && repo) {
+      if (await installedOnRepo({ appId: creds.appId, pem: creds.pem, repo, fetchImpl })) {
+        await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: SETUP_EVENTS.installed,
+          detail: `the GitHub app is installed on ${repo} (checked with the app's own key)`, actor: 'runner' });
+        out.installed++; log(`  ✓ ${r.slug}: GitHub app installed on ${repo}`);
+      }
+    }
+    if (!facts.deviceFlowAt && creds.clientId) {
+      if (await deviceFlowOn({ clientId: creds.clientId, fetchImpl })) {
+        await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: SETUP_EVENTS.deviceFlow,
+          detail: 'command-line sign-in (device flow) is on for the GitHub app', actor: 'runner' });
+        out.deviceFlow++; log(`  ✓ ${r.slug}: command-line sign-in is on`);
+      }
+    }
+  }
+  if (out.checked) log(`github-setup — checked=${out.checked} installed=${out.installed} device-flow=${out.deviceFlow} sign-in=${out.signIn}`);
+  return out;
+}
+
+module.exports = { appJwt, appCredsFromEnv, installedOnRepo, deviceFlowOn, attemptsToVerify, verifyGithubAppSetups, SWEEP_LIMIT };

package/scripts/bongos/provision-net.js

@@ -0,0 +1,357 @@
+// scripts/bongos/provision-net.js — how an instance becomes reachable: federation
+// with the identity hub, Cloudflare zone/DNS resolution and token scope, the
+// Caddy site block, and the healthz probe.
+//
+// Carved out of scripts/bongos/provision.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring the control-plane CLI under the 1,500-line ratchet.
+// A STRUCTURAL move: bodies unchanged, provision.js requires every name back, so
+// the intent runner and its unit templates behave exactly as before.
+
+'use strict';
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { CONFIG } = require('./provision-config.js');
+const { federationHubOrigin, provisionedEnvPrefix } = require('./provision-units.js'); // lives beside the hub-upgrade address it also feeds (task 1004608)
+
+// Whether provisioning should federate this instance's sign-in through the hub.
+//
+// THIS GATE DECIDES A CREDENTIAL, NOT CATALOG MEMBERSHIP (task 1003576, ADR 0246). It used
+// to decide both by accident — federateInstance was the only writer of the hub catalog — so
+// a `standalone` project could never appear on the public map. That hop now runs at every
+// provisioning write (modules/provisioning/catalog-bridge.js → the `project.catalog` port),
+// for every hosting shape. What survives here is the narrow question this gate is actually
+// about: whose web.env does the platform write, and therefore who can hold a client secret.
+// Dormant-by-default: true ONLY when the control plane is hub-configured (the
+// platform-identity module is present, a signing key is loadable, AND a hub origin
+// resolves), the instance is a CO-TENANT (the mothership-hosted shape whose web.env is
+// written locally — a `standalone` is owner-hosted and keeps its own GitHub app, the
+// self-hosted path), and it has a public domain
+// (the origin the hub binds the CLI mint audience to — the #1002108 account-takeover
+// fix). Returns { federate, reason } so the caller can log WHY it skipped. PURE-ish
+// (reads env + the injected module handles; no DB, no I/O).
+function shouldFederate(inst, deps) {
+  const { platformIdentity, hubKeys } = deps;
+  if (!platformIdentity || !hubKeys) return { federate: false, reason: 'platform-identity module not present (control plane is not the hub)' };
+  if (!hubKeys.hubSigningConfigured()) return { federate: false, reason: 'hub signing key not configured (<PREFIX>_HUB_SIGNING_KEY unset)' };
+  if (!federationHubOrigin()) return { federate: false, reason: 'hub origin not resolvable (set PROVISION_HUB_ORIGIN or <PREFIX>_PUBLIC_ORIGIN)' };
+  if (inst.hosting_shape !== 'co-tenant') return { federate: false, reason: `${inst.hosting_shape} keeps its own GitHub app (not the co-tenant hosted path)` };
+  if (!inst.domain) return { federate: false, reason: 'no domain yet — federation needs the instance public origin' };
+  return { federate: true, reason: null };
+}
+
+// Register this hosted instance as an sso_clients row on the HUB (fresh per-client
+// secret) and return the federation block to bake into its web.env (ADR 0141 §4).
+// SECURITY: `origin` MUST be the instance's EXACT public origin — the hub binds the
+// CLI-federation mint audience to it (the #1002108 fix), so a mismatch would break
+// device sign-in (and a wrong origin would be a takeover vector). client_id is the
+// (unique, DNS-safe) slug, so a re-provision rotates the SAME row's secret via
+// registerClient's ON CONFLICT rather than orphaning a client. redirect_uri lists both
+// callback prefixes the core may emit (/api/bongos is what auth.js builds today) so the
+// hub's exact-match allow-list accepts the browser leg. --apply gates the real hub
+// write; dry-run returns a placeholder block (so webEnvBody can still be composed) + logs.
+async function federateInstance(inst, deps) {
+  const { db, platformIdentity, hubKeys, log, apply } = deps;
+  const origin = `https://${inst.domain}`;
+  const clientId = inst.slug;
+  const hubOrigin = federationHubOrigin();
+  const hubPublicKey = hubKeys.hubPublicKeyB64();
+  if (!hubPublicKey) throw new Error('hub signing key is set but unreadable — cannot derive HUB_PUBLIC_KEY');
+  const redirectUris = [
+    `${origin}/api/gds/auth/web/callback`,
+    `${origin}/api/bongos/auth/web/callback`,
+  ];
+  if (!apply) {
+    log(`  [federate] would register client '${clientId}' on the hub (origin ${origin}) + write ${provisionedEnvPrefix()}_HUB_* + AUTH_IDP into web.env`);
+    return { hubOrigin, clientId, clientSecret: '0'.repeat(43), hubPublicKey };
+  }
+  const clientSecret = crypto.randomBytes(32).toString('base64url');
+  // Best-effort owner github_id — nice for the hub catalog's ownership link, but
+  // nullable in registerClient, so a lookup miss must never fail the provision.
+  let ownerGithubId = null;
+  try {
+    const { rows } = await db.query('SELECT github_id FROM builders WHERE id = $1', [inst.owner_builder_id]);
+    ownerGithubId = rows[0] ? rows[0].github_id : null;
+  } catch { /* non-fatal */ }
+  await platformIdentity.registerClient(
+    // type + description: the owner's answers ride the instance row from the
+    // create form (tasks 1002772 / 1002334) and land on the catalog row here —
+    // never guessed. description is half the publish gate (ADR 0182 D4), so a
+    // project that described itself at creation is publishable the moment it
+    // federates; one that skipped the optional step passes null and stays dark
+    // matter until it fills the answer in.
+    { clientId, secret: clientSecret, name: inst.slug, redirectUris, origin, ownerGithubId, type: inst.type, description: inst.description },
+    { pool: db },
+  );
+  log(`  [federate] registered client '${clientId}' on the hub (origin ${origin})`);
+  return { hubOrigin, clientId, clientSecret, hubPublicKey };
+}
+
+// The Cloudflare zone a hostname's A record lives in. Cloudflare zones are
+// registrable domains, which for the common case is the last two DNS labels
+// (mercury.example.com → example.com; apex example.com → example.com). Multi-part
+// public suffixes (foo.co.uk) are NOT special-cased here — set CLOUDFLARE_ZONE in
+// the control-plane box.env to override (box-dns-cloudflare.sh honours it). PURE.
+function zoneForDomain(domain) {
+  const d = String(domain || '').trim().toLowerCase().replace(/\.$/, '');
+  if (!d) return '';
+  const labels = d.split('.').filter(Boolean);
+  return labels.length <= 2 ? labels.join('.') : labels.slice(-2).join('.');
+}
+
+// The env a DNS UPSERT invocation of infra/box-dns-cloudflare.sh needs for a
+// PROVISIONED host: the hostname, the target public IP (the A-record content), the
+// zone the record lives in, and whether Cloudflare proxies it.
+//   • proxied=false (default) is LOAD-BEARING for a CO-TENANT host: it uses
+//     Caddy on-demand ACME (Let's Encrypt), whose challenge must reach Caddy directly —
+//     Cloudflare proxy ON would intercept :80/:443 at the edge and the challenge would
+//     silently fail (ADR 0003 / docs/recipes/ops-gotchas.md). Do NOT proxy those.
+//   • proxied=true for a STANDALONE host (task 2077): it runs control-plane-local under
+//     the *.cloudbongos.com wildcard Cloudflare Origin cert, so on-demand ACME never
+//     fires (a matching cert already exists) and proxied=false would serve that origin
+//     cert — untrusted to direct clients. Proxying lets the CF edge present a public cert
+//     (origin cert valid behind Full-strict) AND hides the control-plane IP.
+// An explicit `zone` wins over the derived one (for a multi-part-suffix domain). PURE.
+function dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {}) {
+  return {
+    BOX_HOSTNAME: inst.domain,
+    BOX_IP: publicIp,
+    CLOUDFLARE_ZONE: zone || zoneForDomain(inst.domain),
+    BOX_PROXIED: proxied ? '1' : '0',
+  };
+}
+
+// The RFC 5737 TEST-NET-1 sentinel a released hostname is parked at (task
+// 1003237, first proven in task 1234). 192.0.2.1 is reserved for documentation and is
+// GUARANTEED never routable, so a name parked here can never dial platform
+// infra or a recycled address.
+const DNS_BLACKHOLE_IP = '192.0.2.1';
+
+// The env a RELEASE invocation of the DNS hook needs: the abandoned hostname,
+// parked at the blackhole sentinel. A re-point (task 1003237) leaves the old
+// address UPSERTed at the platform's IP for a project that no longer answers
+// there — the ADR 0181 §2 leak — and this is how the runner lets it go.
+//
+// REPOINT, not delete (task 1234): deleting a name
+// opens an NXDOMAIN window that resolvers negative-cache for the zone's SOA
+// neg-TTL (~30 min, not editable), so a client that queried mid-gap stays
+// broken long after. A name that always resolves — to a guaranteed-dead host —
+// has nothing to negative-cache. It also needs only the UPSERT contract every
+// BOX_DNS_HOOK implements, so no hook grows a new mode for this.
+//
+// proxied=0: a parked record must never ride the Cloudflare edge, which would
+// answer for it. Takes a bare `hostname` rather than an instance — the whole
+// point is that the row has already moved on. PURE.
+function dnsReleaseEnv(hostname, { zone } = {}) {
+  return {
+    BOX_HOSTNAME: hostname,
+    BOX_IP: DNS_BLACKHOLE_IP,
+    CLOUDFLARE_ZONE: zone || zoneForDomain(hostname),
+    BOX_PROXIED: '0',
+  };
+}
+
+// ── DNS token-scope PREFLIGHT (task 1980) ────────────────────────────────────
+// Onboarding a NEW project on a domain the control-plane's Cloudflare token does NOT
+// cover fails LATE: the DNS UPSERT (step 5) errors mid-provision (the Emersonian
+// standup — the token only covered the platform's original zone, so the new project's
+// record couldn't be created until it was widened MID-FLOW). This preflight detects
+// "the configured token can't reach the project's zone" UP FRONT, before the
+// connect-address step, and GUIDES the fix — instead of a half-done provision. It is
+// READ-ONLY (a CF `GET /zones?name=<zone>`); it never mutates DNS.
+const CF_API_BASE = process.env.CLOUDFLARE_API_BASE || 'https://api.cloudflare.com/client/v4';
+
+// PURE: given the outcome of `GET /zones?name=<zone>` (HTTP status + parsed JSON) and
+// the target zone, decide whether the token can MANAGE that zone, with actionable
+// guidance when it can't. Exported + unit-tested with no network.
+function classifyZoneScope({ status, body, zone }) {
+  const z = String(zone || '');
+  if (status === 401 || status === 403) {
+    return { reachable: false, reason: `Cloudflare rejected the token (HTTP ${status})`,
+      guidance: `The DNS token is invalid or lacks Zone:Read. Set CLOUDFLARE_API_TOKEN in the control-plane box.env to a token scoped to include ${z} (Zone:DNS:Edit + Zone:Read).` };
+  }
+  if (status !== 200 || !body || body.success !== true) {
+    const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
+    return { reachable: false, reason: `Cloudflare zone lookup failed (HTTP ${status}${errs ? `: ${errs}` : ''})`,
+      guidance: `Check CLOUDFLARE_API_TOKEN + network from the control plane, then retry.` };
+  }
+  const result = Array.isArray(body.result) ? body.result : [];
+  const match = result.find((r) => r && r.name === z);
+  if (!match) {
+    return { reachable: false, reason: `the token authenticated, but zone "${z}" is not in its scope`,
+      guidance: `Widen the Cloudflare API token to include ${z}: CF dashboard → My Profile → API Tokens → edit the token → Zone Resources → Include → ${z} (or use an account-scoped token). If ${z} is a multi-part public suffix (e.g. foo.co.uk), set CLOUDFLARE_ZONE explicitly in the control-plane box.env.` };
+  }
+  return { reachable: true, reason: `token can manage zone "${z}" (id ${match.id})`, zoneId: match.id };
+}
+
+// Query Cloudflare for the domain's zone with the configured token. Injectable
+// `token`/`fetchImpl` for tests. Returns { zone, reachable, reason, guidance[, zoneId] }.
+// A missing token/fetch/domain is reported as not-reachable-with-guidance — it never
+// throws for a config gap (the caller decides whether to hard-fail).
+async function checkDnsTokenScope(domain, { token = process.env.CLOUDFLARE_API_TOKEN, zoneOverride = process.env.CLOUDFLARE_ZONE, fetchImpl } = {}) {
+  const zone = zoneOverride || zoneForDomain(domain);
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!zone) return { zone, reachable: false, reason: 'no domain given', guidance: 'provide a domain before the address step' };
+  if (!token) return { zone, reachable: false, reason: 'no CLOUDFLARE_API_TOKEN configured', guidance: `Set CLOUDFLARE_API_TOKEN (Zone:DNS:Edit on ${zone}) in the control-plane box.env before provisioning DNS for ${domain}.` };
+  if (!doFetch) return { zone, reachable: false, reason: 'no fetch available', guidance: 'run on a Node with global fetch, or inject fetchImpl' };
+  let status = 0; let bodyJson = null;
+  try {
+    const res = await doFetch(`${CF_API_BASE}/zones?name=${encodeURIComponent(zone)}`, {
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    });
+    status = res.status;
+    bodyJson = await res.json().catch(() => null);
+  } catch (e) {
+    return { zone, reachable: false, reason: `Cloudflare request failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
+  }
+  return { zone, ...classifyZoneScope({ status, body: bodyJson, zone }) };
+}
+
+// A Caddy reverse-proxy site block for the instance's domain → its local port.
+// TLS = on-demand ACME (P4, ADR 0111 §4): Caddy fetches a Let's Encrypt cert for
+// this host LAZILY, on the first TLS handshake — no manual Cloudflare Origin-Cert
+// console step (the least-automated leg). It is GATED by the global
+// `on_demand_tls { ask … }` allow-list in infra/Caddyfile (→ /api/bongos/
+// provisioning/tls-check), so Caddy only mints a cert for a host this module
+// actually provisioned — never an arbitrary SNI. The A record is proxied=false
+// (dnsUpsertEnv) so the challenge reaches Caddy. No domain → a comment
+// (bring-your-own-domain is deferred per-instance, ADR 0111 §4).
+function caddyBlock(inst) {
+  if (!inst.domain) {
+    return `# ${inst.slug}: no domain yet (bring-your-own-domain pending) — reachable on 127.0.0.1:${inst.port}\n`;
+  }
+  return `${inst.domain} {
+	tls {
+		on_demand
+	}
+	reverse_proxy 127.0.0.1:${inst.port}
+}
+`;
+}
+function caddySnippetPath(inst, { snippetDir = CONFIG.caddySnippetDir } = {}) {
+  return path.posix.join(snippetDir, `${inst.slug}.caddy`);
+}
+// Does the base Caddyfile carry what a provisioned domain needs (task 1002860, ADR 0303)?
+// Read from Caddy's RESOLVED config, not the file's text, so the answer holds whatever form
+// the operator wrote it in: an `ask` (2.7) or a `permission` module (2.8+), an absolute or
+// relative import, directives split across imported files. `requireHost` asks whether the
+// domain is served, which only a written snippet can make true. Returns the operator
+// instruction, or null when wired.
+function caddyWiringGap(adaptedJson, { domain, requireHost = false, caddyfile = CONFIG.caddyfile, snippetDir = CONFIG.caddySnippetDir } = {}) {
+  let apps;
+  try { apps = JSON.parse(adaptedJson).apps || {}; } catch (_) {
+    return `could not read Caddy's resolved config ('caddy adapt --config ${caddyfile}' printed no JSON)`;
+  }
+  const onDemand = apps.tls && apps.tls.automation && apps.tls.automation.on_demand;
+  if (!JSON.stringify(onDemand || {}).includes('/provisioning/tls-check')) {
+    return `${caddyfile} has no on_demand_tls ask for the provisioning tls-check, so no provisioned domain can get a certificate — add 'on_demand_tls { ask <platform origin>/api/bongos/provisioning/tls-check }' to its global options block and reload Caddy`;
+  }
+  if (requireHost && !JSON.stringify(apps.http || {}).includes(JSON.stringify(domain))) {
+    return `${caddyfile} does not import ${snippetDir}/*.caddy, so Caddy will never serve ${domain} — add 'import ${snippetDir}/*.caddy' at the top level of ${caddyfile} and reload Caddy`;
+  }
+  return null;
+}
+// `caddy adapt` reads config files only: no privilege, no certificate keys, no running server.
+function checkCaddyWiring(exec, opts = {}) {
+  const caddyfile = opts.caddyfile || CONFIG.caddyfile;
+  let res;
+  try { res = exec(`caddy adapt --config ${caddyfile} --adapter caddyfile`); } catch (e) {
+    const why = String((e && (e.stderr || e.message)) || e).trim().slice(0, 200);
+    return `'caddy adapt --config ${caddyfile}' failed (${why}) — the base Caddyfile must load before a site is added to it`;
+  }
+  return caddyWiringGap(res && res.stdout, { ...opts, caddyfile });
+}
+// Can this plane give a child instance a front door AT ALL? (task 1004017)
+//
+// ADR 0303 asks whether a box's Caddy is wired right. This is the question BEFORE it: the
+// self-host image installs no caddy binary and runs unprivileged, so step 6's snippet write
+// and `systemctl reload caddy` cannot work there. The 0303 preflight is gated on inst.domain,
+// so a DOMAINLESS child skipped it entirely and died on the write — a hard error on attempt
+// one, not the pending-retry a refusal earns. Probed, not configured: a plane either answers
+// `caddy version` or it does not. Same cheap-read posture as checkCaddyWiring — no privilege,
+// no config, no running server.
+// A MISSING BINARY is the only failure that proves there is no proxy. Under remote exec
+// boxExec is `ssh <host> bash -s`, which throws on a transport blip too — and diagnosing a
+// briefly-unreachable co-hosting box as "this platform has no proxy, provision elsewhere"
+// would be a confident wrong answer, the thing this check exists to stop. ssh reports its
+// OWN failures as 255 and otherwise propagates the remote command's status, so 127 still
+// means "no caddy" across the hop. cmd.exe says 9009 and words it differently.
+const NO_CADDY_BINARY = /command not found|not recognized as an internal|No such file or directory/i;
+function ingressPlaneGap(exec, { caddyfile = CONFIG.caddyfile } = {}) {
+  try { exec('caddy version'); return null; } catch (e) {
+    const why = String((e && (e.stderr || e.message)) || e).trim().slice(0, 200);
+    const status = e && e.status;
+    if (status !== 127 && status !== 9009 && !NO_CADDY_BINARY.test(why)) {
+      return `could not confirm a reverse proxy on this plane: 'caddy version' failed (${why}). Provisioning writes a Caddy site snippet for every child instance, so it refuses rather than assume — re-run once the box answers.`;
+    }
+    return `this plane has no reverse proxy, so a child instance would have no front door: 'caddy version' failed (${why}). Provision from a host that runs Caddy — a plane with no proxy cannot serve a child, and ${caddyfile} is not something provisioning will create.`;
+  }
+}
+// The preflight around ingressPlaneGap: the narration its sibling preflights already carry,
+// including the dry-run line without which the plan prints step 6's Caddy write as though it
+// will work. Returns the refusal, or null to proceed. Lives here rather than inline at the two
+// call sites to keep provision.js under its 1,500-line ratchet.
+function ingressPreflight({ exec, apply, log, probe = ingressPlaneGap, before = 'writing any Caddy config' }) {
+  if (!apply) { log(`  [preflight] would probe the plane for a reverse proxy before ${before}`); return null; }
+  const missing = probe(exec);
+  if (missing) return `Ingress preflight failed: ${missing}`;
+  log('  [preflight] the plane serves a reverse proxy ✓');
+  return null;
+}
+function healthzCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/healthz`;
+}
+
+// The instance manifest, read over loopback — the identity companion to healthzCmd (task 1003740).
+function identityCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/api/bongos/instance`;
+}
+
+// Does a freshly provisioned instance report ITSELF, or the platform it is hosted on?
+//
+// WHY THIS EXISTS. Provisioning used to pin every instance's branding pack to the shared neutral
+// starter (see provision-units.js), a leftover from the co-tenant model that shared one checkout. Under
+// ADR 0108 each instance has its own, and src/branding.js's ENV_OVERRIDES carry domains but never
+// identity.productName — so every hosted instance served "Cloud Bongos" as its own name for
+// months, greeting newcomers with the wrong project at sign-in. Nothing looked.
+//
+// PURE so it is testable without a box: takes the parsed manifest and returns a verdict.
+// Deliberately a WARNING, not a failure — an owner may legitimately name a project after the
+// platform, and provisioning must not refuse a working instance over a name.
+function identityVerdict({ manifest, slug, neutralName }) {
+  const name = manifest && (manifest.name || (manifest.brand && manifest.brand.identity && manifest.brand.identity.productName));
+  if (!name) return { ok: null, reason: 'no name in manifest' };
+  // The bug's exact shape: the instance answers with the neutral pack's name while its slug says
+  // it is somebody else. A project genuinely called that keeps its name and only trips when the
+  // slug matches too — in which case it is not the bug.
+  if (neutralName && name === neutralName && slug && slug !== neutralName) {
+    return { ok: false, name, reason: `serves the platform default name "${name}" instead of its own` };
+  }
+  return { ok: true, name };
+}
+
+// ---------------------------------------------------------------------------
+// The injectable executor. dry-run → log-only; --apply → child_process.
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  CF_API_BASE,
+  DNS_BLACKHOLE_IP,
+  caddyBlock,
+  caddySnippetPath,
+  caddyWiringGap,
+  checkCaddyWiring,
+  checkDnsTokenScope,
+  classifyZoneScope,
+  dnsReleaseEnv,
+  dnsUpsertEnv,
+  federateInstance,
+  federationHubOrigin,
+  healthzCmd,
+  identityCmd,
+  identityVerdict,
+  ingressPlaneGap,
+  ingressPreflight,
+  shouldFederate,
+  zoneForDomain,
+};