@bongos/core 1.19.1072 → 1.19.1074

package/scripts/gds/cf-tunnel.js

@@ -1,558 +0,0 @@
-// scripts/gds/cf-tunnel.js — a thin Cloudflare API client for the box terminal's
-// NAMED tunnel (#771, ADR 0038 Part B). A control-plane (operator-CLI) network
-// client; moved here from modules/dev-box/ alongside do-api.js so the control
-// plane owns the network clients and the shared http-api-client (task #1943).
-//
-// The control-plane half of the "named tunnel" production upgrade. #760 shipped
-// the BOX-side cloudflared-run.sh that already runs a named tunnel when
-// BOX_TUNNEL_TOKEN + BOX_TERMINAL_HOSTNAME are present in /etc/otb/box.env. This
-// module is how scripts/gds/box.js MAKES those exist: it creates (or reuses) a
-// remotely-managed Cloudflare Tunnel per builder, points its ingress at the box's
-// localhost ttyd (127.0.0.1:7681), routes a stable DNS CNAME
-// (term-<login>.example.com → <tunnel-id>.cfargotunnel.com), and hands
-// back the connector token to bake into the box. Teardown deletes the tunnel +
-// the DNS record.
-//
-// Design mirrors src/bongos/do-api.js exactly so the box subsystem has ONE shape for
-// every external API:
-//   - Injectable transport (`fetchImpl`) so tests assert request shape with a
-//     fake fetch and never touch the network.
-//   - `dryRun` mode (the CLI DEFAULT): NO request is sent; each method logs what
-//     it WOULD do and returns a synthetic `{ dryRun: true, ... }` so box.js's
-//     control flow runs end-to-end against a throwaway plan.
-//   - Live mode requires a token + accountId; the constructor throws clearly if
-//     asked to run live without them — it never silently no-ops a real call.
-//
-// SECURITY: the Cloudflare API token (Account:Cloudflare Tunnel:Edit +
-// Zone:DNS:Edit) lives ONLY on the control plane (the prod droplet's box.env),
-// exactly where DO_API_TOKEN lives — never on the internet-facing web tier. A
-// web-tier compromise can never create or delete a tunnel. The per-builder
-// connector token this returns is baked into the box's cloud-init (same exposure
-// as the SSH keys already baked there) and only authorizes running THAT tunnel,
-// whose only target is the basic-auth-protected localhost ttyd.
-
-const { JsonHttpApi, makeApiError } = require('./http-api-client');
-
-const CF_API_BASE = 'https://api.cloudflare.com/client/v4';
-const CFARGO_SUFFIX = 'cfargotunnel.com';
-const TTYD_SERVICE = 'http://127.0.0.1:7681';
-// The box's own `node server.js` (ADR 0044). A SECOND ingress route on the same
-// per-builder named tunnel exposes the live game preview at game-<login>.<apex>.
-const GAME_SERVICE = 'http://127.0.0.1:3000';
-
-// SECURITY (#919, security_reports SR#11): the apex gds_session cookie
-// (Domain=.example.com) is sent by the browser to every subdomain, including
-// the box-fronting term-<login> (ttyd) and sandbox-<login> (game preview) hosts —
-// so the builder's FULL hall bearer rides the tunnel onto the box, which is OUTSIDE
-// the ADR 0016 trust boundary. We must NOT narrow the apex cookie (the #726 SSO
-// across builders.example.com needs it), so instead a zone Transform Rule
-// removes the Cookie REQUEST header at the Cloudflare edge — before the request
-// enters the tunnel — for exactly the box subdomains. ttyd uses basic-auth and the
-// sandbox serves the game, so neither needs the cookie. Cloudflare permits REMOVE
-// (not set/modify) of the Cookie request header via Transform Rules.
-const COOKIE_STRIP_PHASE = 'http_request_late_transform';
-const COOKIE_STRIP_RULE_DESC = 'otb-919 strip Cookie on box subdomains (term-*/sandbox-*) — SR#11';
-// Zone-scoped ruleset ⇒ http.host is always within example.com, so the prefix
-// match precisely targets the per-builder box hosts and nothing else.
-const COOKIE_STRIP_EXPRESSION = 'starts_with(http.host, "term-") or starts_with(http.host, "sandbox-")';
-
-// #1065 — Cloudflare's DEFAULT 4h Browser Cache TTL rewrites the box origin's
-// no-store on the sandbox hosts, serving multi-hour-stale game code. A zone Cache
-// Rule scoped to sandbox-* bypasses the edge cache + respects the origin headers
-// there, WITHOUT touching the zone-wide TTL prod (the apex) relies on. Like the
-// cookie-strip rule, this needs the CF token to carry zone "Cache Rules" (Account
-// Rulesets) edit scope; callers run it best-effort so a missing scope warns.
-const CACHE_BYPASS_PHASE = 'http_request_cache_settings';
-const CACHE_BYPASS_RULE_DESC = 'otb-1065 bypass cache on sandbox preview hosts (sandbox-*) — keep prod cached';
-// Sandbox preview only. NOT term-* (ttyd, not cached) and NEVER the apex.
-const CACHE_BYPASS_EXPRESSION = 'starts_with(http.host, "sandbox-")';
-
-// FORCE IPv4 egress. The Cloudflare API token is IP-locked to the control-plane
-// droplet's IPv4 (least privilege, mirroring box-dns-cloudflare.sh's `curl -4`).
-// The droplet ALSO has IPv6 egress, and Node's fetch will happily dial Cloudflare
-// over IPv6 — whose source address is NOT on the token's allow-list, so Cloudflare
-// rejects it as an "Authentication error" (verified live under #771). undici's
-// Agent with connect.family=4 pins IPv4. Memoized; degrades to undefined (default
-// dispatcher) if undici can't be required, so a non-IP-locked token still works.
-let _ipv4Dispatcher;
-let _ipv4Tried = false;
-function ipv4Dispatcher() {
-  if (_ipv4Tried) return _ipv4Dispatcher;
-  _ipv4Tried = true;
-  try {
-    // eslint-disable-next-line global-require
-    const { Agent } = require('undici');
-    _ipv4Dispatcher = new Agent({ connect: { family: 4 } });
-  } catch { _ipv4Dispatcher = undefined; }
-  return _ipv4Dispatcher;
-}
-
-const CfApiError = makeApiError('CfApiError', 'CF_API_ERROR');
-
-// The Cloudflare token permission each ruleset phase is gated behind, named exactly
-// as it reads in the dashboard's token editor so the guidance is click-followable.
-const RULESET_PHASE_PERMISSION = {
-  [COOKIE_STRIP_PHASE]: 'Transform Rules',
-  [CACHE_BYPASS_PHASE]: 'Cache Rules',
-};
-
-// The one fix for every not-readable verdict: widen the token. Both edit scopes are
-// named because provisioning applies BOTH ruleset legs (cookie-strip + cache-bypass)
-// and an operator in the token editor should add them in one pass.
-function rulesetScopeGuidance(zone) {
-  return `Widen CLOUDFLARE_API_TOKEN on the control plane: Cloudflare dashboard → My Profile → API Tokens → `
-    + `edit the token → Permissions → add "Zone → Transform Rules → Edit" (the ADR 0053 cookie-strip) and `
-    + `"Zone → Cache Rules → Edit" (the sandbox cache bypass) → Zone Resources → Include → Specific zone → ${zone} `
-    + `→ Continue → Save. Only the account owner can do this. Until then, apply the rule by hand in the dashboard `
-    + `(see docs/recipes/builder-box-lifecycle.md).`;
-}
-
-// PURE. Given the outcome of the READ-ONLY phase-entrypoint probe (HTTP status +
-// parsed Cloudflare JSON), say what we actually know about the token's scope.
-//
-// HONESTY — THIS IS A NEGATIVE DETECTOR, NOT A POSITIVE ONE. The probe is a GET, so
-// a 200 proves the token can READ the phase entrypoint; it does NOT prove the token
-// can EDIT it. Cloudflare exposes no read-only way to prove edit scope — only the
-// real PUT does. So:
-//   - 401/403  → DEFINITIVELY no scope. This is the actionable case the preflight
-//                exists to catch, and the only verdict we assert about the token.
-//   - 200/404  → readable. Edit scope stays UNPROVEN until the rule PUT runs.
-//   - anything else → inconclusive, reported as not-readable so the operator is
-//                warned rather than falsely reassured.
-// The field is named `readable` and never `editable` for exactly this reason, and no
-// verdict here may render as "scope confirmed".
-function classifyRulesetScope({ status, body, phase, zone }) {
-  const z = String(zone || '');
-  const perm = RULESET_PHASE_PERMISSION[phase] || 'Transform Rules';
-  if (status === 401 || status === 403) {
-    return {
-      readable: false,
-      reason: `Cloudflare refused to read the "${phase}" ruleset on ${z} (HTTP ${status}) — the token definitively lacks zone "${perm}" scope there`,
-      guidance: rulesetScopeGuidance(z),
-    };
-  }
-  // A zone with no rules in this phase yet has no entrypoint ruleset. That is a
-  // legitimate empty state (ensureCookieStripRule's PUT creates it), not a denial.
-  if (status === 404) {
-    return {
-      readable: true,
-      reason: `the "${phase}" phase has no entrypoint ruleset on ${z} yet (HTTP 404) — readable; edit scope is NOT proven until the rule is applied`,
-      guidance: '',
-    };
-  }
-  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 {
-      readable: false,
-      reason: `the "${phase}" ruleset probe on ${z} failed and is inconclusive (HTTP ${status}${errs ? `: ${errs}` : ''})`,
-      guidance: `Re-run once network/Cloudflare recovers. If it keeps failing, ${rulesetScopeGuidance(z)}`,
-    };
-  }
-  return {
-    readable: true,
-    reason: `the token can READ the "${phase}" ruleset on ${z} — edit scope is NOT proven until the rule is applied`,
-    guidance: '',
-  };
-}
-
-// Read-only preflight for a zone ruleset phase. Does its OWN raw fetch rather than
-// routing through CfTunnelApi._req, because _req THROWS on failure and is dry-run
-// gated — a preflight must return a verdict (never throw) and must run on the
-// dry-run path too. Mirrors provision.js's checkDnsTokenScope.
-//
-// Deliberately does NOT use `GET /user/tokens/verify`: an IP-locked token answers
-// "Invalid API Token" there even when it is valid (docs/recipes/builder-box-
-// lifecycle.md). Probe the real operation instead.
-//
-// Returns { zone, phase, readable, reason, guidance[, zoneId] }. Never throws.
-async function checkRulesetScope({
-  zone, phase = COOKIE_STRIP_PHASE, token = process.env.CLOUDFLARE_API_TOKEN,
-  fetchImpl, zoneId = null, dispatcher,
-} = {}) {
-  const base = { zone, phase };
-  if (!zone) return { ...base, readable: false, reason: 'no Cloudflare zone given', guidance: 'set CLOUDFLARE_ZONE on the control plane' };
-  if (!token) {
-    return { ...base, readable: false, reason: `no CLOUDFLARE_API_TOKEN configured`,
-      guidance: `Set CLOUDFLARE_API_TOKEN in the control-plane box.env. ${rulesetScopeGuidance(zone)}` };
-  }
-  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
-  if (!doFetch) return { ...base, readable: false, reason: 'no fetch implementation available', guidance: 'run on a Node with global fetch, or inject fetchImpl' };
-  const init = { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' } };
-  if (dispatcher !== undefined) init.dispatcher = dispatcher;
-  else { const d = ipv4Dispatcher(); if (d) init.dispatcher = d; }
-
-  let id = zoneId;
-  if (!id) {
-    let res;
-    try {
-      res = await doFetch(`${CF_API_BASE}/zones?name=${encodeURIComponent(zone)}`, init);
-    } catch (e) {
-      return { ...base, readable: false, reason: `Cloudflare zone lookup failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
-    }
-    const body = await res.json().catch(() => null);
-    const match = (body && Array.isArray(body.result) ? body.result : []).find((r) => r && r.id);
-    if (!match) {
-      const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
-      return { ...base, readable: false,
-        reason: `could not resolve zone "${zone}" (HTTP ${res.status}${errs ? `: ${errs}` : ''})`,
-        guidance: `Check that CLOUDFLARE_API_TOKEN is valid and its Zone Resources include ${zone}. ${rulesetScopeGuidance(zone)}` };
-    }
-    id = match.id;
-  }
-
-  let status = 0; let bodyJson = null;
-  try {
-    const res = await doFetch(`${CF_API_BASE}/zones/${id}/rulesets/phases/${phase}/entrypoint`, init);
-    status = res.status;
-    bodyJson = await res.json().catch(() => null);
-  } catch (e) {
-    return { ...base, zoneId: id, readable: false, reason: `Cloudflare ruleset probe failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
-  }
-  return { ...base, zoneId: id, ...classifyRulesetScope({ status, body: bodyJson, phase, zone }) };
-}
-
-// Deterministic per-builder names so teardown can find what provision created
-// WITHOUT persisting an id in the DB (no migration): the tunnel name and the DNS
-// hostname are both pure functions of the login.
-function tunnelName(login) { return `otb-term-${login}`; }
-function terminalHostname(login, zone) { return `term-${login}.${zone}`; }
-// The live game preview host (ADR 0044) — the builder's "sandbox". One label
-// under the apex (same zone as the terminal host) so free Universal SSL covers
-// it — see the #771 lesson that forced an apex one-label host over `dev.*`.
-function previewHostname(login, zone) { return `sandbox-${login}.${zone}`; }
-
-class CfTunnelApi extends JsonHttpApi {
-  // opts: { token, accountId, dryRun=true, fetchImpl=globalThis.fetch, base, log }
-  constructor(opts = {}) {
-    super(opts, { base: CF_API_BASE, logTag: 'CF', ErrorClass: CfApiError });
-    this.accountId = opts.accountId || null;
-    // Pin IPv4 for the live token (see ipv4Dispatcher). Overridable/null-able for
-    // tests; a fake fetchImpl simply ignores the extra `dispatcher` option.
-    this.dispatcher = opts.dispatcher !== undefined ? opts.dispatcher : ipv4Dispatcher();
-    if (!this.dryRun) {
-      if (!this.token) {
-        throw new CfApiError(
-          'live Cloudflare call requested but no API token is set — ' +
-          'set CLOUDFLARE_API_TOKEN (Tunnel + DNS scope) or run without --apply (dry-run)'
-        );
-      }
-      if (!this.accountId) {
-        throw new CfApiError('live Cloudflare tunnel call requested but CLOUDFLARE_ACCOUNT_ID is not set');
-      }
-      if (typeof this.fetchImpl !== 'function') {
-        throw new CfApiError('no fetch implementation available for live mode');
-      }
-    }
-  }
-
-  // CfTunnelApi pins the IPv4 dispatcher on every live request (its token is
-  // IP-locked, #771) and treats the Cloudflare {success:false} envelope as a
-  // failure, not just a non-2xx status. The dry-run/live skeleton itself (and the
-  // envelope's {result} passthrough) is inherited from JsonHttpApi.
-  requestInit() { return { dispatcher: this.dispatcher }; }
-
-  detectError(res, json) {
-    if (!res.ok || (json && json.success === false)) {
-      const errs = json && Array.isArray(json.errors) ? json.errors.map((e) => e.message || e.code).join('; ') : '';
-      return errs || `HTTP ${res.status}`;
-    }
-    return null;
-  }
-
-  // ---- tunnels (account-scoped) ---------------------------------------------
-
-  // Find a non-deleted tunnel by exact name. Returns the tunnel object or null.
-  async findTunnelByName(name) {
-    const r = await this._req('GET', `/accounts/${this.accountId}/cfd_tunnel?name=${encodeURIComponent(name)}&is_deleted=false`, null, {
-      dryRunResult: { result: [] },
-    });
-    const list = (r && r.result) || [];
-    return list.find((tn) => tn.name === name) || null;
-  }
-
-  // Create a remotely-managed tunnel (config_src: 'cloudflare' so the ingress is
-  // set via the API, not a config file on the box). Returns the tunnel object.
-  async createTunnel(name) {
-    const r = await this._req('POST', `/accounts/${this.accountId}/cfd_tunnel`, { name, config_src: 'cloudflare' }, {
-      dryRunResult: { result: { id: `dryrun-tunnel-${name}`, name } },
-    });
-    return (r && r.result) || null;
-  }
-
-  // Find-or-create. Idempotent: re-provisioning a builder reuses their tunnel.
-  async ensureTunnel(name) {
-    const existing = await this.findTunnelByName(name);
-    if (existing) { this.log(`reusing tunnel ${existing.id} (${name})`); return { tunnel: existing, created: false }; }
-    const tunnel = await this.createTunnel(name);
-    this.log(`created tunnel ${tunnel && tunnel.id} (${name})`);
-    return { tunnel, created: true };
-  }
-
-  // The connector token (the BOX_TUNNEL_TOKEN the box runs cloudflared with).
-  async getTunnelToken(tunnelId) {
-    const r = await this._req('GET', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/token`, null, {
-      dryRunResult: { result: `dryrun-token-${tunnelId}` },
-    });
-    return (r && r.result) || null;
-  }
-
-  // Point the tunnel's ingress at the box's localhost ttyd, with a 404 catch-all.
-  // `extraRoutes` ([{ hostname, service }, ...]) adds further hostname→service
-  // rules on the SAME connector — e.g. the ADR 0044 game preview at
-  // sandbox-<login>.<apex> → 127.0.0.1:3000 — inserted before the catch-all. A
-  // Cloudflare named tunnel routes by hostname, so each route needs its own
-  // proxied DNS CNAME (see ensureNamedTunnel).
-  async putConfiguration(tunnelId, { hostname, service = TTYD_SERVICE, extraRoutes = [] } = {}) {
-    const ingress = [{ hostname, service }, ...extraRoutes, { service: 'http_status:404' }];
-    const config = { ingress };
-    return this._req('PUT', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/configurations`, { config }, {
-      dryRunResult: { result: { config } },
-    });
-  }
-
-  // Best-effort: drop any live connector connections so the tunnel can be deleted
-  // (CF refuses to delete a tunnel with active connections). The droplet is
-  // already gone by teardown time, so this is usually a no-op.
-  async cleanupConnections(tunnelId) {
-    return this._req('DELETE', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/connections`, null, {
-      dryRunResult: { result: {} },
-    });
-  }
-
-  async deleteTunnel(tunnelId) {
-    return this._req('DELETE', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}`, null, {
-      dryRunResult: { result: { id: tunnelId } },
-    });
-  }
-
-  // ---- DNS (zone-scoped) -----------------------------------------------------
-
-  async getZoneId(zone) {
-    const r = await this._req('GET', `/zones?name=${encodeURIComponent(zone)}`, null, {
-      dryRunResult: { result: [{ id: `dryrun-zone-${zone}` }] },
-    });
-    const z = ((r && r.result) || [])[0];
-    if (!z || !z.id) throw new CfApiError(`Cloudflare zone '${zone}' not found, or the token lacks access to it`);
-    return z.id;
-  }
-
-  async findDnsRecord(zoneId, name) {
-    const r = await this._req('GET', `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(name)}`, null, {
-      dryRunResult: { result: [] },
-    });
-    const lower = name.toLowerCase();
-    return (((r && r.result) || []).find((rec) => rec.name.toLowerCase() === lower)) || null;
-  }
-
-  // Upsert the proxied CNAME that fronts the tunnel. proxied:true is required for
-  // a *.cfargotunnel.com target (the orange-cloud is what routes to the tunnel).
-  async upsertDnsRoute({ zoneId, name, tunnelId }) {
-    const body = { type: 'CNAME', name, content: `${tunnelId}.${CFARGO_SUFFIX}`, proxied: true, ttl: 1 };
-    const existing = await this.findDnsRecord(zoneId, name);
-    if (existing) {
-      return this._req('PUT', `/zones/${zoneId}/dns_records/${existing.id}`, body, {
-        dryRunResult: { result: { id: existing.id, ...body } },
-      });
-    }
-    return this._req('POST', `/zones/${zoneId}/dns_records`, body, {
-      dryRunResult: { result: { id: `dryrun-dns-${name}`, ...body } },
-    });
-  }
-
-  async deleteDnsRoute({ zoneId, name }) {
-    const existing = await this.findDnsRecord(zoneId, name);
-    if (!existing) return { result: null, missing: true };
-    return this._req('DELETE', `/zones/${zoneId}/dns_records/${existing.id}`, null, {
-      dryRunResult: { result: { id: existing.id } },
-    });
-  }
-
-  // ---- edge cookie strip (zone-scoped Transform Rule, #919 / SR#11) ----------
-
-  // Ensure the zone's request-header Transform Rule that REMOVES the Cookie header
-  // on the box subdomains (term-*/sandbox-*). Idempotent and NON-DESTRUCTIVE: it
-  // reads the phase entrypoint ruleset, preserves every OTHER transform rule, drops
-  // any prior copy of ours (matched by description), and PUTs the merged set. One
-  // wildcard-prefix rule covers every builder's box, so this only needs to land
-  // ONCE — but re-running on each provision self-heals a deleted rule. Requires the
-  // CF token to carry zone "Transform Rules" (Account Rulesets) edit scope; callers
-  // run it best-effort so a missing scope warns but never blocks box provisioning.
-  async ensureCookieStripRule({ zone }) {
-    const zoneId = await this.getZoneId(zone);
-    const phasePath = `/zones/${zoneId}/rulesets/phases/${COOKIE_STRIP_PHASE}/entrypoint`;
-    // Read the current entrypoint ruleset. A zone with no transform rules yet has
-    // no entrypoint (404) — fine, the PUT below creates it.
-    let existing = [];
-    try {
-      const got = await this._req('GET', phasePath, null, { dryRunResult: { result: { rules: [] } } });
-      const rules = got && got.result && got.result.rules;
-      existing = Array.isArray(rules) ? rules : [];
-    } catch (e) {
-      if (e.status && e.status !== 404) throw e;
-    }
-    const ourRule = {
-      action: 'rewrite',
-      action_parameters: { headers: { Cookie: { operation: 'remove' } } },
-      expression: COOKIE_STRIP_EXPRESSION,
-      description: COOKIE_STRIP_RULE_DESC,
-      enabled: true,
-    };
-    // Preserve other rules, dropping CF-managed read-only fields (id/version/
-    // last_updated) that a PUT rejects; keep a caller-set `ref` if present.
-    const preserved = existing
-      .filter((r) => r && r.description !== COOKIE_STRIP_RULE_DESC)
-      .map((r) => ({
-        action: r.action,
-        action_parameters: r.action_parameters,
-        expression: r.expression,
-        description: r.description,
-        enabled: r.enabled !== false,
-        ...(r.ref ? { ref: r.ref } : {}),
-      }));
-    const rules = [...preserved, ourRule];
-    return this._req('PUT', phasePath, { rules }, { dryRunResult: { result: { rules } } });
-  }
-
-  // ---- edge cache bypass on the sandbox hosts (zone Cache Rule, #1065) --------
-
-  // Ensure the zone Cache Rule that BYPASSES Cloudflare caching for the sandbox
-  // preview hosts (sandbox-*), so the box origin's no-store (#1065 part 1) is
-  // honored and the 4h Browser Cache TTL stops serving stale game code. Idempotent
-  // + NON-DESTRUCTIVE (mirrors ensureCookieStripRule): read the cache-phase
-  // entrypoint ruleset, preserve every OTHER cache rule, drop any prior copy of
-  // ours by description, PUT the merged set. Scoped strictly to sandbox-* via the
-  // host expression so prod (the apex) caching is UNTOUCHED. Requires the CF token
-  // to carry zone "Cache Rules" (Account Rulesets) edit scope; callers run it
-  // best-effort so a missing scope warns but never blocks provisioning.
-  async ensureCacheBypassRule({ zone }) {
-    const zoneId = await this.getZoneId(zone);
-    const phasePath = `/zones/${zoneId}/rulesets/phases/${CACHE_BYPASS_PHASE}/entrypoint`;
-    let existing = [];
-    try {
-      const got = await this._req('GET', phasePath, null, { dryRunResult: { result: { rules: [] } } });
-      const rules = got && got.result && got.result.rules;
-      existing = Array.isArray(rules) ? rules : [];
-    } catch (e) {
-      if (e.status && e.status !== 404) throw e;
-    }
-    const ourRule = {
-      action: 'set_cache_settings',
-      action_parameters: {
-        cache: false, // do not cache on the edge
-        // Even if a future tweak re-enables caching, honor the box origin's
-        // no-store and never override its browser TTL.
-        browser_ttl: { mode: 'respect_origin' },
-      },
-      expression: CACHE_BYPASS_EXPRESSION,
-      description: CACHE_BYPASS_RULE_DESC,
-      enabled: true,
-    };
-    const preserved = existing
-      .filter((r) => r && r.description !== CACHE_BYPASS_RULE_DESC)
-      .map((r) => ({
-        action: r.action,
-        action_parameters: r.action_parameters,
-        expression: r.expression,
-        description: r.description,
-        enabled: r.enabled !== false,
-        ...(r.ref ? { ref: r.ref } : {}),
-      }));
-    const rules = [...preserved, ourRule];
-    return this._req('PUT', phasePath, { rules }, { dryRunResult: { result: { rules } } });
-  }
-
-  // ---- high-level compose ----------------------------------------------------
-
-  // Create-or-reuse everything the box needs for a stable named tunnel and return
-  // the values to bake into /etc/otb/box.env. Idempotent end-to-end.
-  async ensureNamedTunnel({ login, zone, terminalZone }) {
-    const name = tunnelName(login);
-    const hostname = terminalHostname(login, terminalZone);
-    // The ADR 0044 live game preview rides the SAME tunnel as a second ingress
-    // route + its own proxied CNAME.
-    const previewHost = previewHostname(login, terminalZone);
-    const { tunnel, created } = await this.ensureTunnel(name);
-    const tunnelId = tunnel && tunnel.id;
-    await this.putConfiguration(tunnelId, {
-      hostname,
-      extraRoutes: [{ hostname: previewHost, service: GAME_SERVICE }],
-    });
-    const token = await this.getTunnelToken(tunnelId);
-    const zoneId = await this.getZoneId(zone);
-    await this.upsertDnsRoute({ zoneId, name: hostname, tunnelId });
-    await this.upsertDnsRoute({ zoneId, name: previewHost, tunnelId });
-    // Both edge-rule legs are BEST-EFFORT and report their outcome STRUCTURALLY so
-    // the caller can surface a failure in its summary instead of leaving it buried
-    // in a mid-run log line (task 1002511). `applied` is false in dry-run because
-    // nothing WAS applied — these are security/caching controls, and a plan must
-    // never read as though the rule is in place.
-    const edgeRules = {
-      cookieStrip: { applied: false, error: null },
-      cacheBypass: { applied: false, error: null },
-    };
-    // SECURITY (#919 / SR#11): strip the apex cookie at the edge for the box
-    // subdomains. A CF token without Transform Rules scope must not block
-    // provisioning (the box still works; the rule is defense-in-depth). Warn
-    // loudly so the operator adds the scope or applies the rule once by hand.
-    try {
-      await this.ensureCookieStripRule({ zone });
-      edgeRules.cookieStrip.applied = !this.dryRun;
-    } catch (e) {
-      edgeRules.cookieStrip.error = e.message;
-      this.log(`⚠ #919 cookie-strip Transform Rule NOT applied (${e.message}) — add zone "Transform Rules" scope to CLOUDFLARE_API_TOKEN or apply it once in the CF dashboard (ADR 0053)`);
-    }
-    // #1065: stop Cloudflare's 4h Browser Cache TTL from serving stale sandbox
-    // game code. A CF token without Cache-Rules scope must not block provisioning.
-    // Warn loudly so the operator adds the scope or applies the rule once by hand
-    // (operator blocker, like the cookie-strip rule).
-    try {
-      await this.ensureCacheBypassRule({ zone });
-      edgeRules.cacheBypass.applied = !this.dryRun;
-    } catch (e) {
-      edgeRules.cacheBypass.error = e.message;
-      this.log(`⚠ #1065 sandbox cache-bypass Cache Rule NOT applied (${e.message}) — add zone "Cache Rules" (Account Rulesets) scope to CLOUDFLARE_API_TOKEN or add it once in the CF dashboard`);
-    }
-    return { tunnelId, token, hostname, previewHostname: previewHost, created, edgeRules };
-  }
-
-  // Tear down the per-builder tunnel + its DNS route. Best-effort: each leg is
-  // independent so a missing tunnel still cleans the DNS and vice versa. Returns a
-  // summary the caller can log. Never throws (so deprovision always completes).
-  async teardownNamedTunnel({ login, zone, terminalZone }) {
-    const out = { tunnelDeleted: false, dnsDeleted: false, previewDnsDeleted: false, errors: [] };
-    const name = tunnelName(login);
-    const hostname = terminalHostname(login, terminalZone);
-    const previewHost = previewHostname(login, terminalZone);
-    try {
-      const zoneId = await this.getZoneId(zone);
-      const res = await this.deleteDnsRoute({ zoneId, name: hostname });
-      out.dnsDeleted = !(res && res.missing);
-      // The ADR 0044 preview CNAME shares the tunnel; drop it too (best-effort,
-      // independent leg so a missing record never blocks teardown).
-      try {
-        const pres = await this.deleteDnsRoute({ zoneId, name: previewHost });
-        out.previewDnsDeleted = !(pres && pres.missing);
-      } catch (e) { out.errors.push(`preview-dns: ${e.message}`); }
-    } catch (e) { out.errors.push(`dns: ${e.message}`); }
-    try {
-      const tunnel = await this.findTunnelByName(name);
-      if (tunnel && tunnel.id) {
-        await this.cleanupConnections(tunnel.id).catch(() => {});
-        await this.deleteTunnel(tunnel.id);
-        out.tunnelDeleted = true;
-      }
-    } catch (e) { out.errors.push(`tunnel: ${e.message}`); }
-    return out;
-  }
-}
-
-module.exports = {
-  CfTunnelApi, CfApiError, CF_API_BASE, CFARGO_SUFFIX, TTYD_SERVICE, GAME_SERVICE,
-  tunnelName, terminalHostname, previewHostname,
-  // #1065: the sandbox edge cache-bypass rule constants, exported for the test.
-  CACHE_BYPASS_PHASE, CACHE_BYPASS_RULE_DESC, CACHE_BYPASS_EXPRESSION,
-  // #919 / SR#11: the cookie-strip rule constants + the read-only scope preflight
-  // box.js runs before any droplet spend (task 1002511).
-  COOKIE_STRIP_PHASE, COOKIE_STRIP_RULE_DESC, COOKIE_STRIP_EXPRESSION,
-  classifyRulesetScope, checkRulesetScope,
-};