@bongos/core 1.19.332 → 1.19.333

package/scripts/gds/provision-config.js

@@ -0,0 +1,204 @@
+// scripts/gds/provision-config.js — the provisioner's CONFIG block, its env
+// readers and the lazy dependency loader. Extracted FIRST so every other piece
+// can share it without requiring provision.js back (the split must stay a DAG).
+//
+// 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.
+
+'use strict';
+
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The verified OAuth-cred placement helpers (task 1979) — reused by the GitHub App
+// Manifest flow (task 2080) to VALIDATE the creds GitHub returns before writing them
+// and to PARSE the post-restart /healthz auth_configured probe. A sibling script; a
+// plain require (its require.main guard means importing it runs no CLI).
+const oauthSecret = require('./oauth-secret');
+
+// The registry-install gates + env-fed .npmrc (ADR 0134, task 2090). Lets the
+// standalone scaffold OPT IN to pulling the PRIVATE @bongos/core from the npm
+// registry (PROVISION_CORE_FROM_REGISTRY=1) instead of vendoring a tarball, with a
+// fail-soft fallback to the vendored path when no NPM_TOKEN is present.
+const { registryCoreRequested, hasNpmToken } = require('./npmrc');
+
+// The HTTP User-Agent the manifest conversion stamps its GitHub call with (GitHub
+// requires a UA). Overridable so a fork can identify itself; not secret.
+const MANIFEST_UA = process.env.PROVISION_GITHUB_UA || 'cloudbongos-provisioner';
+
+// The running core version (no caret) — for naming the vendored tarball the standalone
+// scaffold pins. Fail-soft (a partial checkout returns null; the scaffold then errors
+// with guidance rather than pinning a `…-null.tgz`). Mirrors init.js coreVersionSafe().
+function coreVersionSafe() {
+  try { return require(path.join(REPO_ROOT, 'src/module-api')).CORE_VERSION; } catch { return null; }
+}
+
+function numEnv(name, dflt) {
+  const v = process.env[name];
+  if (v == null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+// A boolean env flag: '1'/'true'/'yes'/'on' (case-insensitive) → true, else false.
+function boolEnv(name) {
+  return /^(1|true|yes|on)$/i.test(String(process.env[name] || '').trim());
+}
+function hasFlag(args, name) { return args.includes(name); }
+
+const CONFIG = {
+  // The port range a CO-TENANT instance process binds on the shared box. 3000 (OTB)
+  // and 3002 (cloudbongos.com) are taken; new co-tenant instances start at 3003.
+  portBase: numEnv('PROVISION_PORT_BASE', 3003),
+  reservedPorts: (process.env.PROVISION_RESERVED_PORTS || '3000,3001,3002')
+    .split(',').map((s) => Number(s.trim())).filter(Number.isFinite),
+  // Where a per-instance secrets file lives: /etc/<slug>/web.env (the standup
+  // runbook's /etc/cloudbongos/web.env shape). chmod 600, OUTSIDE the repo.
+  etcBase: process.env.PROVISION_ETC_BASE || '/etc',
+  // The dir holding per-instance Caddy site snippets. Each instance gets its OWN
+  // <slug>.caddy file (idempotent overwrite, no fragile append to a shared file);
+  // the main Caddyfile carries a one-time `import <dir>/*.caddy` (operator setup).
+  caddySnippetDir: process.env.PROVISION_CADDY_SNIPPET_DIR || '/etc/caddy/sites',
+  // Where nightly pg_dump backups land (db-backup-nightly.sh's GDS_BACKUP_DIR
+  // default). Shared across co-tenant instances on one box — dumps are named
+  // `<db>-<ts>.sql.gz`, so each instance's files + retention prune stay scoped to
+  // its own DB. Owned by the app user, mode 0750. (task 2213, productizes 2210.)
+  backupDir: process.env.PROVISION_BACKUP_DIR || '/var/backups/gds',
+  // Dedicated-droplet defaults (only used for hosting_shape='dedicated').
+  region: process.env.PROVISION_REGION || 'nyc3',
+  baseImage: process.env.PROVISION_BASE_IMAGE || 'ubuntu-24-04-x64',
+  tag: process.env.PROVISION_TAG || 'cloudbongos-instance',
+  doToken: process.env.DO_API_TOKEN || null,
+  sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
+  // The Cloudflare DNS hook (the SAME infra/box-dns-cloudflare.sh box.js uses).
+  // P4 (#1945) formalizes the UPSERT: point the instance's domain at the target
+  // public IP (below), in the domain's OWN Cloudflare zone, proxied=false (see
+  // dnsUpsertEnv). No hook configured → DNS is skipped (a co-tenant instance is
+  // still reachable by IP; TLS then can't be issued until DNS lands).
+  dnsHook: process.env.BOX_DNS_HOOK || null,
+  // This box's PUBLIC IP — the A-record target for a CO-TENANT instance's domain.
+  // Set in the control-plane /etc/<inst>/box.env (never the web tier). A dedicated
+  // instance instead points its A record at the freshly-created droplet's IP. Under
+  // remote-exec (PROVISION_REMOTE_HOST) this is the CO-HOSTING box's IP — where the
+  // co-tenant actually runs (ADR 0130).
+  publicIp: process.env.PROVISION_PUBLIC_IP || process.env.BOX_PUBLIC_IP || null,
+  // The CONTROL PLANE's OWN public IP — the A-record target for a STANDALONE instance
+  // (task 2074). A standalone runs control-plane-LOCAL (its scaffolded repo dir lives
+  // here, not on the remote co-hosting box), so its domain must point at THIS box, not
+  // at publicIp (which, under remote-exec, is the co-hosting box). Only needed when
+  // remote-exec splits the two boxes; all-local (no remoteHost) falls back to publicIp
+  // since the control plane and the run box are then the same machine.
+  controlPlaneIp: process.env.PROVISION_CONTROL_PLANE_IP || null,
+  // Parent dir for a STANDALONE instance's OWN repo checkout (hosting_shape='standalone',
+  // ADR 0108): each lives at <standaloneBase>/<slug> with @bongos/core installed as
+  // an npm dep. Distinct from co-tenant (which shares THIS control-plane checkout).
+  standaloneBase: process.env.PROVISION_STANDALONE_BASE || '/srv/cloudbongos',
+  // ── Privilege escalation (task 2066, ADR 0128) ───────────────────────────
+  // The intent runner runs as a NON-root user (provision-intent-runner.service:
+  // User=lars) that holds passwordless sudo. That user cannot itself write under
+  // /etc, reload systemd/Caddy, or peer-auth to Postgres as a superuser — so the
+  // runbook steps below FAIL as bare commands (the goal-35 blocker). With
+  // PROVISION_SUDO=1 (alias PROVISION_PRIVILEGED=1) the privileged steps escalate:
+  //   • /etc writes         → temp file (lars-writable) + `sudo install -D -m <mode>`
+  //   • systemctl / rm /etc  → `sudo …`
+  //   • createdb / migrate   → `sudo -u postgres …` (postgres peer-auths as the PG
+  //     superuser — the Ubuntu default — so it never needs `lars` to be a PG role)
+  // OFF (default) preserves the run-as-root / test / co-tenant-legacy behavior
+  // (bare commands, direct fs writes), so nothing outside a sudo context changes.
+  // Dry-run ALWAYS logs the exact command either way. NB: the runner unit must NOT
+  // set NoNewPrivileges=true — it blocks sudo (see infra/provision-intent-runner.service).
+  privileged: boolEnv('PROVISION_SUDO') || boolEnv('PROVISION_PRIVILEGED'),
+  // ── Remote orchestration over SSH (task 2065, ADR 0130) ──────────────────
+  // The token-separation endgame (ADR 0126): run this runner ON the token-holding
+  // control-plane box, and have it drive co-tenant workloads that still LIVE on the
+  // co-hosting box over SSH — so the co-hosting box can hold ZERO cloud tokens.
+  // When PROVISION_REMOTE_HOST is set, the BOX-MUTATING steps (createdb, migrate,
+  // /etc writes, systemctl, Caddy, healthz) run on that host over `ssh`; the
+  // TOKEN step (the Cloudflare DNS hook) + the standalone repo scaffold STAY local
+  // on the control plane, where the token + the packaging tools live. UNSET
+  // (default) = every step runs locally, byte-identical to today.
+  remoteHost: process.env.PROVISION_REMOTE_HOST || null,
+  // The co-hosting box's checkout dir — the remote migrate's cwd. NO baked-in default
+  // (task 1002756: the founder-pinned path was an identity leak, and a silent wrong
+  // cwd aims mutating SSH steps at a dir that may not exist); remote mode requires it
+  // explicitly (guarded at the makeExec call), local mode never reads it.
+  remoteCwd: process.env.PROVISION_REMOTE_CHECKOUT || null,
+  // ssh options for the control-plane → co-hosting hop. BatchMode so a missing key
+  // fails fast (never hangs on a prompt); accept-new pins the host key on first
+  // connect (the operator can pre-seed known_hosts for strict pinning).
+  sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
+};
+
+// task 1002757 — the provisioner's git identity resolves from the instance's own
+// apex (env → bot@<apex> → neutral), never the hub's address hardcoded.
+const { provisionerBotEmail } = require('./instance-apex');
+
+const MAX_INTENT_ATTEMPTS = numEnv('PROVISION_INTENT_MAX_ATTEMPTS', 3);
+
+// Manifest-placement verification budget (task 1002720 / QA-walk F23): a child
+// instance is a full Node boot away from reporting auth_configured=true, and the
+// old 10×1s poll routinely lost that race — recording a failure for a setup that
+// succeeded, then burning the SINGLE-USE manifest code on the retry. ~3 min of
+// patience; the poll runs after the intent loop, so it delays nothing.
+const MANIFEST_VERIFY_TRIES = numEnv('PROVISION_MANIFEST_VERIFY_TRIES', 90);
+const MANIFEST_VERIFY_INTERVAL_MS = numEnv('PROVISION_MANIFEST_VERIFY_INTERVAL_MS', 2000);
+
+// ---------------------------------------------------------------------------
+// Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
+// ---------------------------------------------------------------------------
+let _deps;
+function loadDeps() {
+  if (_deps) return _deps;
+  // eslint-disable-next-line global-require
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  // eslint-disable-next-line global-require
+  const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning'));
+  // eslint-disable-next-line global-require
+  const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
+  // Cross-site identity (ADR 0141 §4, task #1002109). Resolve the hub-side module by a
+  // VARIABLE key, gated on isModuleEnabled — the module-loader's own dynamic-dispatch
+  // pattern (the run-unit-tests.js precedent), NOT a static 'modules/platform-identity/'
+  // literal that would couple this publishable core file to an instance-EXCLUDED module
+  // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
+  // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
+  // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
+  let platformIdentity = null, hubKeys = null;
+  const PI_KEY = 'platform-identity';
+  let piEnabled = false;
+  try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
+  if (piEnabled) {
+    const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
+    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
+    catch { platformIdentity = null; hubKeys = null; }
+  }
+  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
+  return _deps;
+}
+
+// ---------------------------------------------------------------------------
+// PURE step-command generators (exported for tests). Each returns the exact shell
+// command a runbook step runs. Kept pure so local exec (co-tenant) and the
+// dedicated droplet's cloud-init both build from ONE source of truth.
+// ---------------------------------------------------------------------------
+
+// A slug is validated DNS/db-safe upstream (provisioning.isValidSlug), so it is
+// already shell-safe (only [a-z0-9-]). We still never interpolate untrusted text.
+
+module.exports = {
+  CONFIG,
+  MANIFEST_UA,
+  MANIFEST_VERIFY_INTERVAL_MS,
+  MANIFEST_VERIFY_TRIES,
+  MAX_INTENT_ATTEMPTS,
+  REPO_ROOT,
+  coreVersionSafe,
+  hasFlag,
+  hasNpmToken,
+  loadDeps,
+  numEnv,
+  oauthSecret,
+  provisionerBotEmail,
+  registryCoreRequested,
+};

package/scripts/gds/provision-net.js

@@ -0,0 +1,221 @@
+// 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.
+
+'use strict';
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { CONFIG } = require('./provision-config.js');
+const { provisionedEnvPrefix } = require('./provision-units.js');
+
+function federationHubOrigin() {
+  const explicit = process.env.PROVISION_HUB_ORIGIN;
+  if (explicit) return String(explicit).replace(/\/+$/, '');
+  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
+  return own ? String(own).replace(/\/+$/, '') : null;
+}
+
+// Whether provisioning should federate this instance's sign-in through the hub.
+// 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; a `dedicated` droplet has no local web.env write yet, same gap the
+// ADR 0133 manifest flow leaves — see placeManifestCreds), 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/gds 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: the owner's declaration rides the instance row from the create
+    // wizard (task 1002772) and lands on the catalog row here — never guessed.
+    { clientId, secret: clientSecret, name: inst.slug, redirectUris, origin, ownerGithubId, type: inst.type },
+    { 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/dedicated 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',
+  };
+}
+
+// ── 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`);
+}
+function healthzCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/healthz`;
+}
+
+// ---------------------------------------------------------------------------
+// The injectable executor. dry-run → log-only; --apply → child_process.
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  CF_API_BASE,
+  caddyBlock,
+  caddySnippetPath,
+  checkDnsTokenScope,
+  classifyZoneScope,
+  dnsUpsertEnv,
+  federateInstance,
+  federationHubOrigin,
+  healthzCmd,
+  shouldFederate,
+  zoneForDomain,
+};