@rubytech/create-realagent 1.0.615 → 1.0.617

package/payload/platform/plugins/cloudflare/mcp/dist/lib/cloudflared.js

@@ -23,6 +23,13 @@ export function loadBrand() {
     };
     return cachedBrand;
 }
+/**
+ * Test-only: reset the cached brand so a subsequent loadBrand() re-reads
+ * the manifest. Production code never calls this.
+ */
+export function _resetBrandCache() {
+    cachedBrand = null;
+}
 // ---------------------------------------------------------------------------
 // Binary detection (unchanged — cloudflared binary still needed for daemon)
 // ---------------------------------------------------------------------------
@@ -73,69 +80,118 @@ export function version() {
         return null;
     }
 }
-// ---------------------------------------------------------------------------
-// API token storage
-//
-// Stored under ~/{configDir}/cloudflare/ so each brand has its own token.
-// Functions (not consts) because loadBrand() requires PLATFORM_ROOT at runtime.
-// ---------------------------------------------------------------------------
-function tokenDir() {
+function bindingDir() {
     return join(homedir(), loadBrand().configDir, "cloudflare");
 }
-function tokenFile() {
-    return join(tokenDir(), "api-token");
+function bindingFile() {
+    return join(bindingDir(), "account-binding.json");
 }
-export function readToken() {
+export function readAccountBinding() {
     try {
-        const path = tokenFile();
+        const path = bindingFile();
         if (!existsSync(path))
             return null;
-        return JSON.parse(readFileSync(path, "utf-8"));
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof parsed?.accountId !== "string" || typeof parsed?.boundAt !== "string") {
+            console.error(`[cloudflare:binding] malformed account-binding.json at ${path} — treating as absent`);
+            return null;
+        }
+        return { accountId: parsed.accountId, boundAt: parsed.boundAt };
     }
-    catch {
+    catch (err) {
+        console.error(`[cloudflare:binding] failed to read ${bindingFile()}: ${err}`);
         return null;
     }
 }
-export function writeToken(apiToken, accountId) {
-    const dir = tokenDir();
+/**
+ * @internal — production code MUST go through `materializeBinding` so the
+ * source-of-truth lifecycle (fresh-login vs migration) is preserved and
+ * logged. This function is exported only so unit tests can pre-seed
+ * bindings without re-implementing the file format. A new tool handler
+ * that calls `writeAccountBinding` directly is a code-review block —
+ * silent overwrites mask account drift, defeating the four-step guard.
+ */
+export function writeAccountBinding(accountId) {
+    const dir = bindingDir();
     mkdirSync(dir, { recursive: true });
-    const data = { apiToken, accountId };
-    writeFileSync(join(dir, "api-token"), JSON.stringify(data), { mode: 0o600 });
-}
-export function hasToken() {
-    return readToken() !== null;
+    const binding = { accountId, boundAt: new Date().toISOString() };
+    writeFileSync(bindingFile(), JSON.stringify(binding, null, 2), { mode: 0o600 });
+    return binding;
 }
 /**
- * Returns the prefix of the stored API token (e.g. "cfut_" for cert-derived
- * tokens), or null if no token is stored. Used to distinguish cert-derived
- * tokens (limited scope) from user-created API tokens.
+ * Reset the binding by unlinking the file. Only force-reset paths
+ * (tunnel-login force=true, cf-rebuild after wrong-account detection)
+ * call this. Tools must never overwrite the binding on a write path —
+ * an overwrite would mask account drift, defeating the guard.
  */
-export function getTokenPrefix() {
-    const token = readToken();
-    if (!token)
-        return null;
-    // cfut_ is 5 chars; return up to 8 chars for other token prefixes
-    const prefix = token.apiToken.slice(0, 8);
-    return prefix || null;
+function resetAccountBinding() {
+    const path = bindingFile();
+    try {
+        unlinkSync(path);
+        console.error(`[cloudflare:binding] reset ${path}`);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        console.error(`[cloudflare:binding] failed to reset ${path}: ${err}`);
+        return false;
+    }
+}
+export function matchAccountZone(hostname, accountZones) {
+    const active = accountZones.filter((z) => z.status === "active").map((z) => z.name);
+    const lc = hostname.toLowerCase();
+    const candidates = active.filter((z) => lc === z.toLowerCase() || lc.endsWith("." + z.toLowerCase()));
+    if (candidates.length === 0) {
+        return { ok: false, matchedZone: null, accountZones: active };
+    }
+    candidates.sort((a, b) => b.length - a.length);
+    return { ok: true, matchedZone: candidates[0], accountZones: active };
+}
+export function logRefuse(detail) {
+    const brand = (() => {
+        try {
+            return loadBrand();
+        }
+        catch {
+            return null;
+        }
+    })();
+    const fields = {
+        reason: detail.reason,
+        brand: brand?.productName ?? "unknown",
+        accountZones: detail.fields.accountZones ?? null,
+        boundAccountId: detail.fields.boundAccountId ?? null,
+        certAccountId: detail.fields.certAccountId ?? null,
+        requestedDomain: detail.fields.requestedDomain ?? null,
+        requestedHostname: detail.fields.requestedHostname ?? null,
+        actualFqdn: detail.fields.actualFqdn ?? null,
+        tunnelId: detail.fields.tunnelId ?? null,
+    };
+    console.error(`[cloudflare:refuse] ${JSON.stringify(fields)}`);
 }
 /**
- * Delete the stored API token and cert.pem, enabling a fresh authentication
- * flow. Handles missing files (no-op) and permission errors (log + continue)
- * gracefully. Used by tunnel-login --force to break out of the dead-end
- * when the stored token has insufficient permissions.
- *
- * Dual-path cert deletion: cloudflared writes cert.pem to ~/.cloudflared/
- * regardless of --origincert, so a complete reset must unlink BOTH the
- * brand-specific path AND the legacy path. Without the legacy unlink,
- * findCert() would re-import the stale cert on the next read.
+ * Single recovery instruction. Every refusal instructs the same path:
+ * tunnel-login under the Cloudflare account that owns the target zone.
  */
+export function recoveryMessage() {
+    return (`Recovery: run tunnel-login while signed into the Cloudflare account that owns ` +
+        `the target zone. If you recently rotated the cert under a different account, ` +
+        `pass force=true to clear the existing cert.pem and account binding before ` +
+        `re-authenticating.`);
+}
+// ---------------------------------------------------------------------------
+// Reset auth — unlinks cert.pem (both paths) and the account binding
+//
+// Kill order matters: terminate any in-flight `cloudflared tunnel login`
+// process BEFORE deleting cert state, otherwise its browser handshake can
+// complete between our unlink and return, writing a fresh cert.pem to the
+// legacy path that findCert() would silently re-import on the next read.
+// Same pattern Task 531 closed; preserved here.
+// ---------------------------------------------------------------------------
 export function resetAuth() {
-    const result = { deletedToken: false, deletedCert: false };
-    // Kill any running login process BEFORE clearing cert/token state. Otherwise
-    // an in-flight `cloudflared tunnel login` could complete its browser handshake
-    // between our unlinks and return from resetAuth, writing a fresh cert.pem to
-    // the legacy path immediately after we just deleted it — and findCert would
-    // re-import it on the next read, defeating the reset entirely.
+    const result = { deletedCert: false, deletedBinding: false };
     const loginState = readLoginState();
     if (loginState?.pid && isProcessAlive(loginState.pid)) {
         try {
@@ -147,21 +203,6 @@ export function resetAuth() {
         }
     }
     clearLoginState();
-    const tf = tokenFile();
-    try {
-        unlinkSync(tf);
-        result.deletedToken = true;
-        console.error(`[tunnel-login] deleted: ${tf}`);
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT") {
-            // File already gone — no-op
-        }
-        else {
-            console.error(`[tunnel-login] failed to delete token file ${tf}: ${err}`);
-        }
-    }
     const cp = certPath();
     try {
         unlinkSync(cp);
@@ -191,6 +232,7 @@ export function resetAuth() {
             console.error(`[tunnel-login] failed to delete legacy cert.pem ${legacyCp}: ${err}`);
         }
     }
+    result.deletedBinding = resetAccountBinding();
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -280,80 +322,117 @@ export function parseCertPem() {
 }
 // ---------------------------------------------------------------------------
 // SDK client
+//
+// Two entry points: getClient() for mutating operations enforces the auth
+// pre-conditions (cert present, binding present, accountId-from-cert
+// matches binding) — uncircumventable for any code path that needs an SDK
+// instance. getReadOnlyClient() for cf-verify allows operating on an
+// unbound device so the audit can report MISSING artefacts without
+// throwing. Both rely on cert.pem as the single account identity source.
 // ---------------------------------------------------------------------------
-export function getClient() {
-    const token = readToken();
-    if (!token) {
-        throw new Error("No API token configured. Run cf-set-token to set one.");
+/** Wraps a structured RefusalDetail so call sites can branch on `reason`. */
+export class CloudflareRefusalError extends Error {
+    refusal;
+    constructor(detail) {
+        super(detail.message);
+        this.name = "CloudflareRefusalError";
+        this.refusal = detail;
     }
-    return {
-        client: new Cloudflare({ apiToken: token.apiToken }),
-        accountId: token.accountId,
-    };
 }
-export async function validateToken(apiToken) {
-    const client = new Cloudflare({ apiToken });
-    try {
-        // Try zones first — most accounts have at least one zone
-        const zones = await client.zones.list({ per_page: 1 });
-        const zone = zones.result?.[0];
-        if (zone) {
-            return {
-                valid: true,
-                accountId: zone.account.id ?? null,
-                accountName: zone.account.name ?? null,
-            };
-        }
-        // No zones — discover account ID via accounts.list() (works for new accounts)
-        const accounts = await client.accounts.list({ per_page: 1 });
-        const account = accounts.result?.[0];
-        if (account) {
-            return {
-                valid: true,
-                accountId: account.id ?? null,
-                accountName: account.name ?? null,
-            };
-        }
-        // Token is valid but no zones and no accounts discoverable
-        return {
-            valid: true,
-            accountId: null,
-            accountName: null,
-            error: "Token is valid but could not discover account ID — no zones or accounts found.",
+/**
+ * Build an SDK client for mutating operations. Throws CloudflareRefusalError
+ * with a structured `refusal` field if any auth pre-condition fails:
+ *   - cert.pem absent or unparseable                → unbound-device
+ *   - account-binding.json absent                   → unbound-device
+ *   - cert.pem accountId !== binding.accountId      → account-drift
+ *
+ * The refusal is logged with [cloudflare:refuse] before the throw, so the
+ * single greppable signal exists regardless of how the caller handles the
+ * exception.
+ */
+export function getClient() {
+    const creds = parseCertPem();
+    if (!creds) {
+        const detail = {
+            reason: "unbound-device",
+            message: `No cert.pem found — this device has not completed Cloudflare authentication. ` +
+                recoveryMessage(),
+            fields: { boundAccountId: readAccountBinding()?.accountId ?? null },
         };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes("Authentication")) {
-            return {
-                valid: false,
-                accountId: null,
-                accountName: null,
-                error: "Token rejected by Cloudflare — check that it is correct and has not expired.",
-            };
-        }
-        return {
-            valid: false,
-            accountId: null,
-            accountName: null,
-            error: msg,
+        logRefuse(detail);
+        throw new CloudflareRefusalError(detail);
+    }
+    const binding = readAccountBinding();
+    if (!binding) {
+        const detail = {
+            reason: "unbound-device",
+            message: `No account binding recorded — tunnel-login must complete a fresh authentication ` +
+                `to bind this device to a Cloudflare account before any other tool can run. ` +
+                recoveryMessage(),
+            fields: { certAccountId: creds.accountId },
+        };
+        logRefuse(detail);
+        throw new CloudflareRefusalError(detail);
+    }
+    if (creds.accountId !== binding.accountId) {
+        const detail = {
+            reason: "account-drift",
+            message: `cert.pem is bound to account ${creds.accountId}, but this device's recorded ` +
+                `binding is account ${binding.accountId}. The cert was rotated under a different ` +
+                `Cloudflare account since the binding was established. ` +
+                recoveryMessage(),
+            fields: {
+                boundAccountId: binding.accountId,
+                certAccountId: creds.accountId,
+            },
         };
+        logRefuse(detail);
+        throw new CloudflareRefusalError(detail);
     }
+    return {
+        client: new Cloudflare({ apiToken: creds.apiToken }),
+        accountId: binding.accountId,
+    };
 }
-export async function validateAuth() {
-    const token = readToken();
-    if (!token) {
-        return { hasToken: false, tokenValid: false };
-    }
-    try {
-        const client = new Cloudflare({ apiToken: token.apiToken });
-        await client.zones.list({ per_page: 1 });
-        return { hasToken: true, tokenValid: true };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { hasToken: true, tokenValid: false, error: msg };
-    }
+export function getReadOnlyClient() {
+    const creds = parseCertPem();
+    const binding = readAccountBinding();
+    const certAccountId = creds?.accountId ?? null;
+    const boundAccountId = binding?.accountId ?? null;
+    const client = creds ? new Cloudflare({ apiToken: creds.apiToken }) : null;
+    const bindingMatches = !!(creds && binding && creds.accountId === binding.accountId);
+    return { client, certAccountId, boundAccountId, bindingMatches };
+}
+export function validateAuth() {
+    const creds = parseCertPem();
+    const binding = readAccountBinding();
+    return {
+        hasCert: !!creds,
+        hasBinding: !!binding,
+        bound: !!(creds && binding && creds.accountId === binding.accountId),
+        certAccountId: creds?.accountId ?? null,
+        boundAccountId: binding?.accountId ?? null,
+    };
+}
+/**
+ * Establish the device-local account binding from cert.pem. Used by:
+ *   (1) tunnel-login fresh-success path — first time creds are derived
+ *   (2) migration path — when cert.pem exists from a prior install but no
+ *       binding has yet been written (silent materialization, since the
+ *       cert was already trust-established by the operator's prior login)
+ *
+ * Caller is responsible for declared-zone visibility validation BEFORE
+ * calling this — bindings should never be written to an account that
+ * doesn't own the brand's declared zones (Task 201 write-after-confirm).
+ */
+export function materializeBinding(source) {
+    const creds = parseCertPem();
+    if (!creds) {
+        throw new Error("Cannot materialize binding — cert.pem absent or unparseable");
+    }
+    const binding = writeAccountBinding(creds.accountId);
+    console.error(`[cloudflare:binding-materialized] source=${source} accountId=${creds.accountId} boundAt=${binding.boundAt}`);
+    return binding;
 }
 export async function listZones() {
     const { client } = getClient();
@@ -372,17 +451,6 @@ export async function listZones() {
     }
     return zones;
 }
-export function verifyZoneOnAccount(hostname, zones) {
-    const activeZones = zones.filter((z) => z.status === "active").map((z) => z.name);
-    const candidates = activeZones.filter((z) => hostname === z || hostname.endsWith(`.${z}`));
-    if (candidates.length > 0) {
-        candidates.sort((a, b) => b.length - a.length);
-        return { zone: candidates[0], missingParent: null, availableZones: activeZones };
-    }
-    const parts = hostname.split(".");
-    const missingParent = parts.length >= 2 ? parts.slice(-2).join(".") : hostname;
-    return { zone: null, missingParent, availableZones: activeZones };
-}
 export async function getZoneId(domain) {
     const { client } = getClient();
     const zones = await client.zones.list({ name: domain });
@@ -396,9 +464,6 @@ export async function getZoneId(domain) {
 }
 export async function createZone(domain) {
     const { client, accountId } = getClient();
-    if (!accountId) {
-        throw new Error("No account ID available. Re-run cf-set-token — the token must be re-validated to discover the account ID.");
-    }
     // Idempotent — check if zone already exists on this account
     const existing = await client.zones.list({ name: domain });
     const match = existing.result?.[0];
@@ -710,11 +775,11 @@ export async function createDnsRecord(zoneId, subdomain, tunnelId) {
     return { created: true, existing: false, updated: false };
 }
 // ---------------------------------------------------------------------------
-// CLI-based tunnel operations — fallback for cert-derived tokens (cfut_*)
+// CLI-based tunnel operations
 //
-// cert-derived tokens may lack SDK-level permissions for tunnel CRUD and
-// DNS management. The cloudflared CLI uses cert.pem directly, which carries
-// Argo Tunnel permissions sufficient for these operations.
+// `cloudflared` CLI uses cert.pem directly for tunnel CRUD and DNS management.
+// We use it (rather than the SDK) for tunnel-create / route-dns because the
+// cert-bound credential carries the Argo Tunnel permissions needed in one step.
 // ---------------------------------------------------------------------------
 export function createTunnelCli(name) {
     const bin = findBinary();
@@ -809,68 +874,121 @@ export function writeLocalConfig(tunnelId, credentialsPath, hostnames, port) {
     return configPath;
 }
 // ---------------------------------------------------------------------------
-// CLI-based DNS routing
+// CLI-based DNS routing — guarded by live account-zone check + post-flight
+//
+// `cloudflared tunnel route dns` resolves the target zone from cert.pem's
+// account. If the hostname's registrable parent zone is not on that account,
+// cloudflared silently writes a CNAME under a different zone (the original
+// joelsmalley.xyz wrong-routing bug). Defence in depth:
 //
-// cert-derived tokens lack Zone:DNS:Edit, so the SDK's createDnsRecord()
-// fails. `cloudflared tunnel route dns` uses the cert.pem directly, which
-// carries Argo Tunnel permissions sufficient for creating CNAME records
-// that point to the tunnel.
+//   (1) Live account-zone check: list the bound account's zones, refuse if
+//       hostname's registrable parent is not active on that account.
+//   (2) Post-flight FQDN assertion: the FQDN cloudflared wrote must equal
+//       the requested hostname. Mismatch → reverse-and-refuse.
 //
-// Pre-flight zone-account check: cloudflared resolves the target zone
-// from cert.pem's account and silently falls back to a sibling zone when
-// the hostname's parent zone is not present. verifyZoneOnAccount() is the
-// choke point that intercepts that failure class before the CLI call.
+// `getClient()` runs first to enforce auth pre-conditions.
 // ---------------------------------------------------------------------------
 export async function routeDnsCli(tunnelId, hostname) {
     const bin = findBinary();
     if (!bin)
         throw new Error("cloudflared is not installed");
+    const { client, accountId: boundAccountId } = getClient();
+    // (1) Live account-zone check.
+    const accountZones = await listZones();
+    const scope = matchAccountZone(hostname, accountZones);
+    if (!scope.ok) {
+        const detail = {
+            reason: "scope-mismatch",
+            message: `Cannot route ${hostname} — no active zone on the bound Cloudflare account ` +
+                `owns this hostname's registrable parent. Active zones on this account: ` +
+                `${scope.accountZones.join(", ") || "none"}. Add the parent zone to the account ` +
+                `(cf-add-zone or via the Cloudflare dashboard), or pick a hostname under one ` +
+                `of the existing zones.`,
+            fields: {
+                requestedHostname: hostname,
+                accountZones: scope.accountZones,
+            },
+        };
+        logRefuse(detail);
+        throw new CloudflareRefusalError(detail);
+    }
     const cert = findCert();
     if (!cert)
-        throw new Error("No cert.pem found — run tunnel-login first");
-    const zones = await listZones();
-    const match = verifyZoneOnAccount(hostname, zones);
-    console.error(`[tunnel-route-dns] zone-check hostname=${hostname} matchedZone=${match.zone ?? "none"} availableZones=${JSON.stringify(match.availableZones)}`);
-    if (!match.zone) {
-        const availableList = match.availableZones.length > 0
-            ? match.availableZones.join(", ")
-            : "none";
-        throw new Error(`Cannot route ${hostname} to a tunnel — the zone that owns this hostname is not on the Cloudflare account bound to this device. ` +
-            `Best guess at missing zone: "${match.missingParent}" (derived from the last two labels of ${hostname}; for multi-label TLDs such as .co.uk the real zone may be longer). ` +
-            `Available zones on this account: ${availableList}. ` +
-            `Recovery: run tunnel-login while signed into the Cloudflare account that owns the zone for ${hostname}. ` +
-            `This rebinds cert.pem to the correct account. Do not use cf-set-token with a token from a different account — zone routing uses cert.pem, not the API token.`);
-    }
+        throw new Error("No cert.pem found — getClient() should have refused first");
+    let output;
     try {
-        const output = execFileSync(bin, ["tunnel", "--origincert", cert, "route", "dns", "--overwrite-dns", tunnelId, hostname], { encoding: "utf-8", timeout: 30000 });
-        // Parse the CNAME name cloudflared actually created from its INF line:
-        // "INF Added CNAME <fqdn> which will route to this tunnel ..."
-        // Log a diagnostic when the parse fails so a silent format drift cannot
-        // mask a wrong-zone routing (which would otherwise defeat the warning
-        // branch in tunnel-create's result line). Falling back to the input
-        // hostname is safe because the pre-flight above guarantees zone match.
-        const fqdnMatch = output.match(/Added CNAME\s+(\S+?)\s+which will route/);
-        let fqdn;
-        if (fqdnMatch) {
-            fqdn = fqdnMatch[1];
-        }
-        else {
-            console.error(`[tunnel-route-dns] WARNING: could not parse CNAME FQDN from cloudflared output — format may have changed. Using input hostname. Output: ${output.trim()}`);
-            fqdn = hostname;
-        }
-        console.error(`[tunnel-route-dns] CLI: routed ${hostname} → tunnel ${tunnelId} (overwrite) fqdn=${fqdn} zone=${match.zone}`);
-        return { created: true, output: output.trim(), fqdn, zone: match.zone };
+        output = execFileSync(bin, ["tunnel", "--origincert", cert, "route", "dns", "--overwrite-dns", tunnelId, hostname], { encoding: "utf-8", timeout: 30000 });
     }
     catch (err) {
         const msg = err instanceof Error ? err.stderr ?? err.message : String(err);
-        // With --overwrite-dns this path should not trigger for CNAME conflicts.
-        // If it fires, log the full error so the cause is diagnosable.
         if (typeof msg === "string" && msg.includes("already exists")) {
             console.error(`[tunnel-route-dns] WARNING: ${hostname} "already exists" despite --overwrite-dns: ${msg}`);
-            return { created: false, output: msg, fqdn: hostname, zone: match.zone };
+            return { created: false, output: msg, fqdn: hostname, zone: scope.matchedZone };
         }
         throw new Error(`cloudflared tunnel route dns failed: ${msg}`);
     }
+    // (2) Post-flight FQDN assertion.
+    const fqdnMatch = output.match(/Added CNAME\s+(\S+?)\s+which will route/);
+    if (!fqdnMatch) {
+        console.error(`[tunnel-route-dns] WARNING: could not parse CNAME FQDN from cloudflared output — format may have changed. Output: ${output.trim()}`);
+        return {
+            created: true,
+            output: output.trim(),
+            fqdn: hostname,
+            zone: scope.matchedZone,
+        };
+    }
+    const actualFqdn = fqdnMatch[1];
+    if (actualFqdn !== hostname) {
+        // cloudflared wrote a CNAME under a different FQDN than requested —
+        // somehow the live-zone check passed but the routing landed elsewhere.
+        // Log evidence, attempt to delete the wrong CNAME, refuse.
+        console.error(`[cloudflare:post-flight-mismatch] ${JSON.stringify({
+            requestedHostname: hostname,
+            actualFqdn,
+            tunnelId,
+            boundAccountId,
+        })}`);
+        let cleanupResult = "failed";
+        try {
+            const owningZone = accountZones.find((z) => actualFqdn === z.name || actualFqdn.endsWith("." + z.name));
+            if (owningZone) {
+                const records = await client.dns.records.list({
+                    zone_id: owningZone.id,
+                    name: { exact: actualFqdn },
+                    type: "CNAME",
+                });
+                for (const r of records.result ?? []) {
+                    if (r.id)
+                        await client.dns.records.delete(r.id, { zone_id: owningZone.id });
+                }
+                cleanupResult = "ok";
+            }
+        }
+        catch (cleanupErr) {
+            console.error(`[cloudflare:post-flight-cleanup] error: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+        }
+        console.error(`[cloudflare:post-flight-cleanup] ${JSON.stringify({
+            requestedHostname: hostname,
+            actualFqdn,
+            result: cleanupResult,
+        })}`);
+        const detail = {
+            reason: "post-flight-fqdn-mismatch",
+            message: `cloudflared wrote the CNAME under ${actualFqdn} instead of the requested ${hostname}. ` +
+                `Cleanup ${cleanupResult === "ok" ? "succeeded" : "failed"}. Re-run cf-rebuild to reconcile.`,
+            fields: {
+                requestedHostname: hostname,
+                actualFqdn,
+                tunnelId,
+                boundAccountId,
+            },
+        };
+        logRefuse(detail);
+        throw new CloudflareRefusalError(detail);
+    }
+    console.error(`[tunnel-route-dns] CLI: routed ${hostname} → tunnel ${tunnelId} (overwrite) fqdn=${actualFqdn} zone=${scope.matchedZone}`);
+    return { created: true, output: output.trim(), fqdn: actualFqdn, zone: scope.matchedZone };
 }
 // ---------------------------------------------------------------------------
 // tunnel login — spawn `cloudflared tunnel login` and capture the auth URL
@@ -1103,8 +1221,8 @@ export function getPersistedHostnames() {
     }
     return [];
 }
-export async function getStatus(domain) {
-    const auth = await validateAuth();
+export function getStatus(domain) {
+    const auth = validateAuth();
     const state = readState();
     const running = state !== null && isProcessAlive(state.pid);
     const effectiveDomain = domain ?? state?.domain ?? null;
@@ -1112,10 +1230,11 @@ export async function getStatus(domain) {
     return {
         installed: isInstalled(),
         version: version(),
-        hasCert: hasCert(),
-        hasToken: auth.hasToken,
-        tokenValid: auth.tokenValid,
-        authError: auth.error ?? null,
+        hasCert: auth.hasCert,
+        hasBinding: auth.hasBinding,
+        bound: auth.bound,
+        certAccountId: auth.certAccountId,
+        boundAccountId: auth.boundAccountId,
         running,
         pid: running ? state.pid : null,
         tunnelId: state?.tunnelId ?? null,
@@ -1194,4 +1313,313 @@ export function stopTunnel() {
     // Preserve tunnel identity, clear process lifecycle
     writeState({ ...state, pid: null, startedAt: null });
 }
+/**
+ * cf-verify: read everything, classify nothing as good or bad. The agent
+ * decides what to keep based on what the user is establishing now.
+ *
+ * "Orphans" are simply account-side things the device's current
+ * tunnel.state + alias-domains.json don't reference. They may be pollution
+ * from a previous setup, or may belong to other devices on the same
+ * account — the agent surfaces them and the user decides.
+ */
+export async function cfVerifyCore() {
+    const brand = loadBrand();
+    console.error(`[cloudflare:verify-start] ${JSON.stringify({ brand: brand.productName })}`);
+    const device = readDeviceSnapshot();
+    const ro = getReadOnlyClient();
+    let account = null;
+    if (ro.client && ro.certAccountId) {
+        try {
+            const [zones, tunnels] = await Promise.all([
+                listZonesViaClient(ro.client),
+                listTunnelsViaClient(ro.client, ro.certAccountId),
+            ]);
+            const cnames = [];
+            for (const z of zones) {
+                if (z.status !== "active")
+                    continue;
+                try {
+                    const recs = await listCnamesUnderZone(ro.client, z.id);
+                    for (const r of recs) {
+                        cnames.push({ zone: z.name, recordId: r.id, name: r.name, content: r.content });
+                    }
+                }
+                catch (err) {
+                    console.error(`[cloudflare:verify] failed to list CNAMEs under ${z.name}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            account = {
+                accountId: ro.certAccountId,
+                zones: zones.map((z) => ({ id: z.id, name: z.name, status: z.status })),
+                tunnels: tunnels.map((t) => ({ id: t.id, name: t.name })),
+                cnames,
+            };
+        }
+        catch (err) {
+            console.error(`[cloudflare:verify] account read failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const orphans = computeOrphans(account, device);
+    console.error(`[cloudflare:verify-complete] ${JSON.stringify({
+        brand: brand.productName,
+        orphanTunnels: orphans.tunnels.length,
+        orphanCnames: orphans.cnames.length,
+        orphanZones: orphans.zones.length,
+    })}`);
+    return { brand: brand.productName, device, account, orphans };
+}
+function readDeviceSnapshot() {
+    const auth = validateAuth();
+    const state = readState();
+    const aliases = [...loadAliasDomains()];
+    return {
+        certPath: certPath(),
+        certPresent: auth.hasCert,
+        bindingPath: bindingFile(),
+        bindingPresent: auth.hasBinding,
+        bindingMatchesCert: auth.bound,
+        certAccountId: auth.certAccountId,
+        boundAccountId: auth.boundAccountId,
+        tunnelStatePath: statePath(),
+        tunnelState: state,
+        configYmlPath: state?.configPath ?? null,
+        configYmlPresent: !!(state?.configPath && existsSync(state.configPath)),
+        aliasDomains: aliases,
+    };
+}
+function computeOrphans(account, device) {
+    if (!account)
+        return { tunnels: [], cnames: [], zones: [] };
+    const intendedTunnelId = device.tunnelState?.tunnelId ?? null;
+    const intendedHostnames = new Set();
+    if (device.tunnelState?.adminHostname)
+        intendedHostnames.add(device.tunnelState.adminHostname.toLowerCase());
+    if (device.tunnelState?.publicHostname)
+        intendedHostnames.add(device.tunnelState.publicHostname.toLowerCase());
+    for (const a of device.aliasDomains)
+        intendedHostnames.add(a.toLowerCase());
+    // Zones the intended hostnames live under — those are "in use".
+    const inUseZones = new Set();
+    for (const h of intendedHostnames) {
+        for (const z of account.zones) {
+            if (h === z.name.toLowerCase() || h.endsWith("." + z.name.toLowerCase())) {
+                inUseZones.add(z.name.toLowerCase());
+                break;
+            }
+        }
+    }
+    const orphanTunnels = account.tunnels.filter((t) => t.id !== intendedTunnelId);
+    const orphanCnames = account.cnames.filter((c) => !intendedHostnames.has(c.name.toLowerCase()));
+    const orphanZones = account.zones.filter((z) => !inUseZones.has(z.name.toLowerCase()));
+    return { tunnels: orphanTunnels, cnames: orphanCnames, zones: orphanZones };
+}
+async function listZonesViaClient(client) {
+    const zones = [];
+    for await (const zone of client.zones.list()) {
+        zones.push({
+            id: zone.id,
+            name: zone.name,
+            status: zone.status ?? "unknown",
+            nameservers: zone.name_servers ?? [],
+            account: { id: zone.account.id ?? "", name: zone.account.name ?? "" },
+        });
+    }
+    return zones;
+}
+async function listTunnelsViaClient(client, accountId) {
+    const summaries = [];
+    const result = await client.zeroTrust.tunnels.cloudflared.list({
+        account_id: accountId,
+        is_deleted: false,
+    });
+    for (const t of result.result ?? []) {
+        if (!t.id || !t.name)
+            continue;
+        summaries.push({ id: t.id, name: t.name, createdAt: t.created_at ?? null });
+    }
+    return summaries;
+}
+async function listCnamesUnderZone(client, zoneId) {
+    const out = [];
+    for await (const rec of client.dns.records.list({ zone_id: zoneId, type: "CNAME" })) {
+        if (!rec.id || !rec.name)
+            continue;
+        out.push({ id: rec.id, name: rec.name, content: rec.content ?? "" });
+    }
+    return out;
+}
+export async function cfRebuildCore(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const brand = loadBrand();
+    console.error(`[cloudflare:rebuild-start] ${JSON.stringify({ brand: brand.productName, dryRun })}`);
+    // Auth gate. We need a client to mutate the account.
+    let client;
+    let accountId;
+    try {
+        const c = getClient();
+        client = c.client;
+        accountId = c.accountId;
+    }
+    catch (err) {
+        if (err instanceof CloudflareRefusalError) {
+            return {
+                brand: brand.productName,
+                dryRun,
+                preserve: { zones: [], tunnelIds: [], cnames: null },
+                actions: [],
+                halted: true,
+                haltReason: err.refusal.message,
+            };
+        }
+        throw err;
+    }
+    // Snapshot the account before mutating.
+    const verify = await cfVerifyCore();
+    if (!verify.account) {
+        return {
+            brand: brand.productName,
+            dryRun,
+            preserve: { zones: [], tunnelIds: [], cnames: null },
+            actions: [],
+            halted: true,
+            haltReason: "Could not read account state (cf-verify returned no account snapshot).",
+        };
+    }
+    // Resolve the preserve set. Defaults from the device's intended state.
+    const intendedTunnelId = verify.device.tunnelState?.tunnelId ?? null;
+    const intendedHostnames = [];
+    if (verify.device.tunnelState?.adminHostname)
+        intendedHostnames.push(verify.device.tunnelState.adminHostname);
+    if (verify.device.tunnelState?.publicHostname)
+        intendedHostnames.push(verify.device.tunnelState.publicHostname);
+    for (const a of verify.device.aliasDomains)
+        intendedHostnames.push(a);
+    const inferredZones = new Set();
+    for (const h of intendedHostnames) {
+        const lc = h.toLowerCase();
+        for (const z of verify.account.zones) {
+            if (lc === z.name.toLowerCase() || lc.endsWith("." + z.name.toLowerCase())) {
+                inferredZones.add(z.name);
+                break;
+            }
+        }
+    }
+    const preserveZones = (opts.preserve?.zones ?? [...inferredZones]).map((s) => s.toLowerCase());
+    const preserveTunnelIds = opts.preserve?.tunnelIds ?? (intendedTunnelId ? [intendedTunnelId] : []);
+    const preserveCnames = opts.preserve?.cnames
+        ? opts.preserve.cnames.map((c) => ({ zone: c.zone.toLowerCase(), name: c.name.toLowerCase() }))
+        : null;
+    const actions = [];
+    // (a) Delete tunnels not in preserve.
+    for (const t of verify.account.tunnels) {
+        if (preserveTunnelIds.includes(t.id))
+            continue;
+        const action = {
+            op: "delete-tunnel",
+            type: "tunnel",
+            id: t.id,
+            name: t.name,
+            result: dryRun ? "planned" : "ok",
+        };
+        if (!dryRun) {
+            try {
+                await client.zeroTrust.tunnels.cloudflared.delete(t.id, { account_id: accountId });
+            }
+            catch (err) {
+                action.result = "failed";
+                action.detail = err instanceof Error ? err.message : String(err);
+            }
+        }
+        console.error(`[cloudflare:rebuild-discard] ${JSON.stringify({ type: "tunnel", id: t.id, name: t.name, planned: dryRun, result: action.result })}`);
+        actions.push(action);
+    }
+    // (b) Delete CNAMEs not in preserve.
+    // If preserve.cnames is set, ONLY those exact records survive.
+    // Otherwise: any CNAME under a preserved zone is preserved.
+    for (const c of verify.account.cnames) {
+        const zoneLc = c.zone.toLowerCase();
+        const nameLc = c.name.toLowerCase();
+        let keep = false;
+        if (preserveCnames) {
+            keep = preserveCnames.some((p) => p.zone === zoneLc && p.name === nameLc);
+        }
+        else {
+            keep = preserveZones.includes(zoneLc);
+        }
+        if (keep)
+            continue;
+        const action = {
+            op: "delete-cname",
+            type: "cname",
+            id: c.recordId,
+            name: c.name,
+            result: dryRun ? "planned" : "ok",
+            detail: `${c.name} → ${c.content} under zone ${c.zone}`,
+        };
+        if (!dryRun) {
+            const zoneRec = verify.account.zones.find((z) => z.name.toLowerCase() === zoneLc);
+            if (!zoneRec) {
+                action.result = "failed";
+                action.detail = `zone ${c.zone} not found in snapshot`;
+            }
+            else {
+                try {
+                    await client.dns.records.delete(c.recordId, { zone_id: zoneRec.id });
+                }
+                catch (err) {
+                    action.result = "failed";
+                    action.detail = err instanceof Error ? err.message : String(err);
+                }
+            }
+        }
+        console.error(`[cloudflare:rebuild-discard] ${JSON.stringify({ type: "cname", id: c.recordId, name: c.name, zone: c.zone, planned: dryRun, result: action.result })}`);
+        actions.push(action);
+    }
+    // (c) Delete zones not in preserve.
+    for (const z of verify.account.zones) {
+        if (preserveZones.includes(z.name.toLowerCase()))
+            continue;
+        const action = {
+            op: "delete-zone",
+            type: "zone",
+            id: z.id,
+            name: z.name,
+            result: dryRun ? "planned" : "ok",
+        };
+        if (!dryRun) {
+            try {
+                await client.zones.delete({ zone_id: z.id });
+            }
+            catch (err) {
+                // Zone deletion may fail (permissions, registrar lock). Surface but
+                // do not halt — orphan zones are informational, not blocking.
+                action.result = "failed";
+                action.detail = err instanceof Error ? err.message : String(err);
+            }
+        }
+        console.error(`[cloudflare:rebuild-discard] ${JSON.stringify({ type: "zone", id: z.id, name: z.name, planned: dryRun, result: action.result })}`);
+        actions.push(action);
+    }
+    let finalVerify;
+    if (!dryRun) {
+        finalVerify = await cfVerifyCore();
+    }
+    console.error(`[cloudflare:rebuild-complete] ${JSON.stringify({
+        brand: brand.productName,
+        dryRun,
+        actionCount: actions.length,
+    })}`);
+    return {
+        brand: brand.productName,
+        dryRun,
+        preserve: {
+            zones: preserveZones,
+            tunnelIds: preserveTunnelIds,
+            cnames: preserveCnames,
+        },
+        actions,
+        finalVerify,
+        halted: false,
+    };
+}
 //# sourceMappingURL=cloudflared.js.map