@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/provision-disconnect.js

@@ -1,88 +1,6 @@
+// scripts/gds/provision-disconnect.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-disconnect.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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 };
+require('../bongos/forwarder.js').forward(module, 'provision-disconnect.js');

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

@@ -1,168 +1,6 @@
+// scripts/gds/provision-github-setup.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-github-setup.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// scripts/gds/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 };
+require('../bongos/forwarder.js').forward(module, 'provision-github-setup.js');

package/scripts/gds/provision-net.js

@@ -1,357 +1,6 @@
-// scripts/gds/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/gds/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.
-
+// scripts/gds/provision-net.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-net.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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,
-};
+require('../bongos/forwarder.js').forward(module, 'provision-net.js');