@rubytech/create-realagent 1.0.615 → 1.0.616

package/payload/platform/plugins/cloudflare/mcp/dist/index.js

@@ -12,134 +12,80 @@ const server = new McpServer({
     version: "0.2.0",
 });
 // ===================================================================
-// Token management
+// Authentication — cert.pem only
+//
+// The plugin recognises exactly one CF account identity: the one
+// cert.pem was bound to via OAuth. `tunnel-login` is the only auth
+// path; the binding written on success is the device's record of
+// which account it currently speaks to.
 // ===================================================================
-server.tool("cf-set-token", "Set the Cloudflare API token. Validates the token against the Cloudflare API, discovers the account ID, and persists both to ~/{configDir}/cloudflare/api-token. Required scopes: Zone:DNS:Edit, Account:Cloudflare Tunnel:Edit, Zone:Zone:Edit.", {
-    token: z
-        .string()
-        .describe("The Cloudflare API token to store"),
-}, async ({ token }) => {
-    const trimmed = token.trim();
-    if (!trimmed) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "No token provided. Paste an existing Cloudflare API token as the token argument. If the user does not have a token, use tunnel-login instead — it handles authentication automatically.",
-                },
-            ],
-            isError: true,
-        };
-    }
-    try {
-        const result = await cloudflared.validateToken(trimmed);
-        if (!result.valid) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Token validation failed: ${result.error}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-        if (!result.accountId) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `${result.error}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-        cloudflared.writeToken(trimmed, result.accountId);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `API token validated and saved.\n\n  Account: ${result.accountName ?? result.accountId}\n  Token stored: ~/{configDir}/cloudflare/api-token (mode 0600)\n\nReady for tunnel operations.`,
-                },
-            ],
-        };
-    }
-    catch (err) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Token validation failed: ${err instanceof Error ? err.message : String(err)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
-server.tool("tunnel-login", "Authenticate with Cloudflare via `cloudflared tunnel login`. Three phases: (1) if already authenticated, reports status; (2) if cert.pem exists, derives API credentials; (3) if no cert.pem, spawns login process and returns auth URL. Detects existing login processes — safe to call repeatedly without spawning duplicates. Pass force=true to delete stored credentials and restart authentication (use when the current token has insufficient permissions).", {
+server.tool("tunnel-login", "Authenticate with Cloudflare via `cloudflared tunnel login`. Three phases: (1) if cert.pem exists and matches the recorded account binding, reports status; (2) if cert.pem exists but no binding has been recorded, materializes the binding from the cert (migration path); (3) if no cert.pem, spawns login process and returns the auth URL. Detects existing login processes — safe to call repeatedly without spawning duplicates. Pass force=true to delete cert.pem (both brand-specific and legacy paths) and account-binding.json before re-authenticating — required when switching Cloudflare accounts.", {
     force: z
         .boolean()
         .optional()
-        .describe("Delete stored API token and cert.pem before re-authenticating. Use when the current token lacks permissions for the needed operation (e.g. cfut_* cert-derived tokens that cannot manage zones)."),
+        .describe("Delete cert.pem (brand path + legacy ~/.cloudflared/cert.pem) and account-binding.json before re-authenticating. Required when switching Cloudflare accounts (e.g. after the prior account was scrubbed or the cert was rotated under a different account)."),
 }, async ({ force }) => {
     try {
-        // Force: delete stored credentials and restart from scratch
+        // Force: delete cert.pem (both paths) and binding before restarting
         if (force) {
-            console.error("[tunnel-login] force=true — deleting stored token and cert.pem before re-auth");
+            console.error("[tunnel-login] force=true — clearing cert.pem and account binding before re-auth");
             cloudflared.resetAuth();
         }
-        // Phase: Already authenticated
-        const auth = await cloudflared.validateAuth();
-        if (auth.hasToken && auth.tokenValid) {
-            console.error("[tunnel-login] short-circuit: hasToken=true tokenValid=true — returning 'already authenticated'");
+        const auth = cloudflared.validateAuth();
+        // Phase: Already bound — cert + binding present and accountIds agree
+        if (auth.bound) {
+            console.error(`[tunnel-login] short-circuit: cert and binding agree on account ${auth.boundAccountId}`);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Already authenticated. API token is valid.\n\nTo re-authenticate with different permissions, call tunnel-login with force=true. This deletes the stored credentials and restarts the authentication flow.`,
+                        text: `Already authenticated. cert.pem and account binding agree on account ${auth.boundAccountId}.\n\nTo switch Cloudflare accounts, call tunnel-login with force=true. This deletes cert.pem (both paths) and the account binding, then restarts the authentication flow.`,
                     },
                 ],
             };
         }
-        // Phase: cert.pem exists — derive credentials
-        if (cloudflared.hasCert()) {
+        // Phase: cert.pem exists — derive credentials and either materialize
+        // or reconcile the binding.
+        if (auth.hasCert) {
             const creds = cloudflared.parseCertPem();
             if (!creds) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `cert.pem exists but could not extract API credentials from it. The file format may have changed.\n\nFallback: ask the user to paste an existing connection key and use cf-set-token to store it.`,
+                            text: `cert.pem exists but could not extract API credentials from it. The file format may have changed.\n\nRecovery: run tunnel-login with force=true to clear cert.pem and re-authenticate.`,
                         },
                     ],
                     isError: true,
                 };
             }
-            // Validate the cert-derived token
-            const validation = await cloudflared.validateToken(creds.apiToken);
-            if (!validation.valid) {
+            // Migration path: cert exists, no binding yet — silently materialize
+            // (the operator already trusted this cert by completing the prior
+            // OAuth flow; we don't re-confirm).
+            if (!auth.hasBinding) {
+                const binding = cloudflared.materializeBinding("migration");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Account binding materialized from existing cert.pem.\n\n  Account: ${binding.accountId}\n  Bound at: ${binding.boundAt}\n\nReady for tunnel operations.`,
+                        },
+                    ],
+                };
+            }
+            // Drift: cert says account X, binding says account Y — refuse with
+            // recovery instruction (force=true will clear both).
+            if (auth.certAccountId !== auth.boundAccountId) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `cert.pem credentials were extracted but the token was rejected by Cloudflare: ${validation.error}\n\nFallback: ask the user to paste an existing connection key and use cf-set-token to store it.`,
+                            text: `cert.pem is bound to account ${auth.certAccountId} but the recorded binding is account ${auth.boundAccountId}. The cert was rotated under a different Cloudflare account since the binding was established.\n\n${cloudflared.recoveryMessage()}`,
                         },
                     ],
                     isError: true,
                 };
             }
-            // Use the account ID from validation (more reliable) or fall back to cert
-            const accountId = validation.accountId ?? creds.accountId;
-            cloudflared.writeToken(creds.apiToken, accountId);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Credentials derived from cert.pem and validated.\n\n  Account: ${validation.accountName ?? accountId}\n  Token stored: ~/{configDir}/cloudflare/api-token (mode 0600)\n\nReady for tunnel operations.`,
-                    },
-                ],
-            };
         }
         // Phase: Login process already running — wait for authorization
         const activeLogin = cloudflared.getActiveLogin();
@@ -225,19 +171,27 @@ server.tool("cf-zone-status", "List all zones (domains) on the Cloudflare accoun
         };
     }
 });
-server.tool("cf-add-zone", "Add a domain to the Cloudflare account via the official API. Returns the zone status and assigned nameservers. Idempotent — returns existing zone info if the domain is already on the account. Requires a valid API token with Zone:Zone:Edit scope (set via cf-set-token).", {
+server.tool("cf-add-zone", "Add a declared brand zone to the Cloudflare account via the official API. The domain MUST appear in this brand's `cloudflare.zones` manifest entry — the tool refuses domains outside that scope. Idempotent: returns existing zone info if already on the account. Requires a successful tunnel-login (cert.pem + account-binding.json present and matching).", {
     domain: z
         .string()
-        .describe("The bare domain to add (e.g. 'mybusiness.com'). Must be a registrable domain, not a subdomain."),
+        .describe("Registrable domain to add. Must already be declared in brand.json `cloudflare.zones`."),
 }, async ({ domain }) => {
-    if (!cloudflared.hasToken()) {
+    // Manifest-scope guard: the brand's declared zones are the only zones
+    // the plugin will create. Refusing here also covers the typo case
+    // (operator typed "maxy.bo" instead of "maxy.bot").
+    const brand = cloudflared.loadBrand();
+    const scope = cloudflared.matchManifestZone(domain, brand.cloudflare.zones);
+    if (!scope.ok || scope.matchedZone !== domain) {
+        const detail = {
+            reason: "scope-mismatch",
+            message: `cf-add-zone refuses ${domain} — it is not in this brand's declared zones ` +
+                `(${brand.cloudflare.zones.join(", ")}). Add the zone to brand.json and republish, ` +
+                `or use one of the declared zones.`,
+            fields: { requestedDomain: domain, manifestZones: brand.cloudflare.zones },
+        };
+        cloudflared.logRefuse(detail);
         return {
-            content: [
-                {
-                    type: "text",
-                    text: "No API token configured. Run cf-set-token first.",
-                },
-            ],
+            content: [{ type: "text", text: detail.message }],
             isError: true,
         };
     }
@@ -264,35 +218,23 @@ server.tool("cf-add-zone", "Add a domain to the Cloudflare account via the offic
         };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[cf-add-zone] failed for ${domain}: ${msg}`);
-        // Detect scope/permission errors and guide the user
-        const lower = msg.toLowerCase();
-        if (lower.includes("403") || lower.includes("permission") || lower.includes("forbidden")) {
-            const tokenPrefix = cloudflared.getTokenPrefix();
-            const isCertDerived = tokenPrefix?.startsWith("cfut_") ?? false;
-            console.error(`[cf-add-zone] permission denied for ${domain} — token prefix=${tokenPrefix ?? "unknown"} (${isCertDerived ? "cert-derived, limited scope" : "API token"})`);
-            const scopeExplanation = isCertDerived
-                ? "The current token was derived from cloudflared's cert.pem (cfut_* prefix). Cert-derived tokens carry Zone:Zone:Read but NOT Zone:Zone:Edit — they cannot create zones or manage DNS. This is a Cloudflare limitation, not a configuration error."
-                : "The current API token does not have the Zone:Zone:Edit scope required to add domains.";
-            const recoveryNote = isCertDerived
-                ? "\n\nDo NOT re-run tunnel-login — it produces the same cert-derived token with the same limited scope."
-                : "\n\nAlternatively, call tunnel-login with force=true to re-authenticate and derive new credentials.";
+        // Refusal-shaped errors thrown by getClient() carry structured detail —
+        // surface them as agent-facing refusals with the same single recovery path.
+        if (err instanceof cloudflared.CloudflareRefusalError) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Zone creation failed — insufficient permissions.\n\n${scopeExplanation}\n\nRecovery options:\n  1. Use cf-set-token with a user-created API token that has these scopes: Zone:Zone:Edit, Zone:DNS:Edit, Account:Cloudflare Tunnel:Edit. The user can create one at dash.cloudflare.com → My Profile → API Tokens.\n  2. Add the domain directly through the Cloudflare dashboard in the VNC browser.${recoveryNote}`,
-                    },
-                ],
+                content: [{ type: "text", text: err.refusal.message }],
                 isError: true,
             };
         }
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[cf-add-zone] failed for ${domain}: ${msg}`);
         return {
             content: [
                 {
                     type: "text",
-                    text: `Zone creation failed: ${msg}`,
+                    text: `Zone creation failed: ${msg}\n\n` +
+                        `If this looks like a permissions error, the cert.pem account may not own ` +
+                        `this brand's zones. ${cloudflared.recoveryMessage()}`,
                 },
             ],
             isError: true,
@@ -412,17 +354,6 @@ server.tool("tunnel-create", "Create a Cloudflare Tunnel and route DNS for the s
         .optional()
         .describe("Human-readable tunnel name (default: derived from domain)"),
 }, async ({ domain, adminSubdomain, publicSubdomain, tunnelName }) => {
-    if (!cloudflared.hasCert()) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "Not authenticated. Run tunnel-login first.",
-                },
-            ],
-            isError: true,
-        };
-    }
     // Validate: admin and public subdomains must differ
     if (publicSubdomain && adminSubdomain === publicSubdomain) {
         return {
@@ -443,28 +374,27 @@ server.tool("tunnel-create", "Create a Cloudflare Tunnel and route DNS for the s
         const publicHostname = publicSubdomain ? `${publicSubdomain}.${domain}` : null;
         const hostnames = publicHostname ? [adminHostname, publicHostname] : [adminHostname];
         console.error(`[tunnel-create] hostnames=${JSON.stringify(hostnames)} domain=${domain}`);
-        // Step 0: Zone-account pre-flight. cloudflared CLI routes DNS against
-        // cert.pem's account and silently falls back to a sibling zone if the
-        // target zone is absent. Two-layer check by design: (a) this early
-        // check fails fast before any Argo tunnel resource is created; (b) the
-        // authoritative choke-point check inside routeDnsCli guards all three
-        // callers including tunnel-add-hostname's CLI fallback. The duplicate
-        // listZones() call is intentional — the inner check is the guarantee,
-        // this outer check is the UX optimisation.
-        const accountZones = await cloudflared.listZones();
+        // Manifest-scope pre-flight: refuse before creating any tunnel resource
+        // when any requested hostname falls outside brand.cloudflare.zones.
+        // The authoritative scope check ALSO runs inside routeDnsCli (defence
+        // in depth), but failing fast here avoids creating an orphan tunnel.
+        // getClient() inside routeDnsCli additionally enforces auth pre-conditions
+        // (cert + binding + accountId match).
+        const brand = cloudflared.loadBrand();
         for (const h of hostnames) {
-            const match = cloudflared.verifyZoneOnAccount(h, accountZones);
-            if (!match.zone) {
-                const availableList = match.availableZones.length > 0
-                    ? match.availableZones.join(", ")
-                    : "none";
+            const scope = cloudflared.matchManifestZone(h, brand.cloudflare.zones);
+            if (!scope.ok) {
+                const detail = {
+                    reason: "scope-mismatch",
+                    message: `Cannot create tunnel for ${h} — its registrable parent is not in this brand's ` +
+                        `declared Cloudflare zones (${brand.cloudflare.zones.join(", ")}). ` +
+                        `Either pick a hostname inside the declared zones, or add the parent zone to ` +
+                        `brand.json and republish the brand package.`,
+                    fields: { requestedHostname: h, manifestZones: brand.cloudflare.zones },
+                };
+                cloudflared.logRefuse(detail);
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Cannot create tunnel for ${h} — the zone that owns this hostname is not on the Cloudflare account bound to this device.\n\n  Best guess at missing zone: "${match.missingParent}" (derived from the last two labels of ${h}; for multi-label TLDs such as .co.uk the real zone may be longer)\n  Available zones on this account: ${availableList}\n\nRecovery: run tunnel-login while signed into the Cloudflare account that owns the zone for ${h}. 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.`,
-                        },
-                    ],
+                    content: [{ type: "text", text: detail.message }],
                     isError: true,
                 };
             }
@@ -540,6 +470,12 @@ server.tool("tunnel-create", "Create a Cloudflare Tunnel and route DNS for the s
         };
     }
     catch (err) {
+        if (err instanceof cloudflared.CloudflareRefusalError) {
+            return {
+                content: [{ type: "text", text: err.refusal.message }],
+                isError: true,
+            };
+        }
         return {
             content: [
                 {
@@ -651,13 +587,17 @@ server.tool("tunnel-enable", "Start the Cloudflare Tunnel process. The tunnel mu
                 isError: true,
             };
         }
-        // GATE 3: cert.pem must exist
-        if (!cloudflared.hasCert()) {
+        // GATE 3: auth pre-conditions — cert + binding + accountId match.
+        // We use validateAuth (non-throwing) so we can produce a uniform
+        // refusal message regardless of which condition failed.
+        const enableAuth = cloudflared.validateAuth();
+        if (!enableAuth.bound) {
+            const missing = !enableAuth.hasCert ? "cert.pem" : !enableAuth.hasBinding ? "account binding" : "matching cert/binding";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `REFUSED: Not authenticated. Run tunnel-login first.`,
+                        text: `REFUSED: Cannot start tunnel — ${missing} is missing or mismatched. ${cloudflared.recoveryMessage()}`,
                     },
                 ],
                 isError: true,
@@ -757,6 +697,12 @@ server.tool("tunnel-enable", "Start the Cloudflare Tunnel process. The tunnel mu
         };
     }
     catch (err) {
+        if (err instanceof cloudflared.CloudflareRefusalError) {
+            return {
+                content: [{ type: "text", text: err.refusal.message }],
+                isError: true,
+            };
+        }
         return {
             content: [
                 {
@@ -800,45 +746,37 @@ server.tool("tunnel-add-hostname", "Add an alias hostname to an existing Cloudfl
         .string()
         .describe("The tunnel UUID. Get this from tunnel-status."),
 }, async ({ hostname, tunnelId }) => {
-    if (!cloudflared.hasToken()) {
+    // Manifest-scope guard: alias hostnames are bound by the same brand
+    // declaration as primary hostnames. routeDnsCli enforces this at the
+    // CLI boundary too; checking here gives the operator a fast refusal
+    // before any ingress mutation.
+    const aliasBrand = cloudflared.loadBrand();
+    const aliasScope = cloudflared.matchManifestZone(hostname, aliasBrand.cloudflare.zones);
+    if (!aliasScope.ok) {
+        const detail = {
+            reason: "scope-mismatch",
+            message: `Cannot add ${hostname} as an alias — its registrable parent is not in this brand's ` +
+                `declared Cloudflare zones (${aliasBrand.cloudflare.zones.join(", ")}). ` +
+                `Add the parent zone to brand.json and republish to make this alias routable.`,
+            fields: { requestedHostname: hostname, manifestZones: aliasBrand.cloudflare.zones },
+        };
+        cloudflared.logRefuse(detail);
         return {
-            content: [
-                {
-                    type: "text",
-                    text: "No API token configured. Run cf-set-token first.",
-                },
-            ],
+            content: [{ type: "text", text: detail.message }],
             isError: true,
         };
     }
     try {
-        // Step 1: Verify the alias domain's zone exists and is accessible
+        // Step 1: Resolve zoneId. getClient() inside getZoneId enforces
+        // cert + binding + accountId-match — refusal-shaped errors propagate
+        // through this catch block.
         const zoneId = await cloudflared.getZoneId(hostname);
         // Step 2: Add hostname to tunnel ingress (read-then-append)
         const ingress = await cloudflared.addHostnameToIngress(tunnelId, hostname);
-        // Step 3: Create CNAME in the alias domain's zone — SDK first, CLI fallback
-        let dns;
-        try {
-            dns = await cloudflared.createDnsRecord(zoneId, hostname, tunnelId);
-        }
-        catch (dnsErr) {
-            const dnsMsg = dnsErr instanceof Error ? dnsErr.message : String(dnsErr);
-            const isPermissionError = dnsMsg.toLowerCase().includes("403") ||
-                dnsMsg.toLowerCase().includes("permission") ||
-                dnsMsg.toLowerCase().includes("forbidden");
-            if (isPermissionError && cloudflared.hasCert()) {
-                console.error(`[tunnel-add-hostname] SDK DNS failed (${dnsMsg}), falling back to cloudflared CLI`);
-                const cliResult = await cloudflared.routeDnsCli(tunnelId, hostname);
-                dns = {
-                    created: cliResult.created,
-                    existing: !cliResult.created,
-                    updated: false,
-                };
-            }
-            else {
-                throw dnsErr;
-            }
-        }
+        // Step 3: Create CNAME via SDK. The cert-bound credential carries
+        // Zone:DNS:Edit for zones owned by the bound account. On any error,
+        // surface as failure — no fallback path remains.
+        const dns = await cloudflared.createDnsRecord(zoneId, hostname, tunnelId);
         // Step 4: Persist alias domain for web server recognition
         cloudflared.saveAliasDomain(hostname);
         // Build response
@@ -860,6 +798,12 @@ server.tool("tunnel-add-hostname", "Add an alias hostname to an existing Cloudfl
         };
     }
     catch (err) {
+        if (err instanceof cloudflared.CloudflareRefusalError) {
+            return {
+                content: [{ type: "text", text: err.refusal.message }],
+                isError: true,
+            };
+        }
         return {
             content: [
                 {
@@ -963,6 +907,59 @@ server.tool("dns-lookup", "Resolve DNS records for a hostname. Replaces dig/nslo
         };
     }
 });
+// ===================================================================
+// cf-verify / cf-rebuild — declarative audit + reconstruction
+// ===================================================================
+server.tool("cf-verify", "Audit every Cloudflare artefact relevant to this brand and return a structured report tagging each as IN-SCOPE, OUT-OF-SCOPE, or MISSING against `brand.cloudflare.zones` and the recorded account binding. Non-mutating. Runs in all states including fresh-install-before-login (reports everything as MISSING with no error). Use this to diagnose any Cloudflare misbehaviour before reaching for `cf-rebuild`.", {}, async () => {
+    try {
+        const report = await cloudflared.cfVerifyCore();
+        return {
+            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `cf-verify failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.tool("cf-rebuild", "Discard every OUT-OF-SCOPE Cloudflare artefact and deterministically reconstruct the declared state. Idempotent — running twice on a clean state is a no-op. Refuses to delete cert.pem when bound to the wrong account; instead halts with an actionable instruction to run tunnel-login force=true. Pass dryRun=true to plan without mutating.", {
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("If true, report what cf-rebuild WOULD do without performing any mutations. Use this to preview a rebuild before committing."),
+}, async ({ dryRun }) => {
+    try {
+        const report = await cloudflared.cfRebuildCore({ dryRun: dryRun ?? false });
+        return {
+            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+            isError: report.halted,
+        };
+    }
+    catch (err) {
+        if (err instanceof cloudflared.CloudflareRefusalError) {
+            return {
+                content: [{ type: "text", text: err.refusal.message }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `cf-rebuild failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 const LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 function sanitizedDomain(domain) {
     return domain.replace(/\./g, "-");
@@ -1015,32 +1012,32 @@ server.tool("cloudflare-setup", "Deterministic, UI-driven state machine for Clou
         }
         // ── Step 2: Authentication ──────────────────────────────────────
         log("checking authentication");
-        const auth = await cloudflared.validateAuth();
-        if (auth.hasToken && auth.tokenValid) {
-            log("authenticated — token valid");
+        const auth = cloudflared.validateAuth();
+        if (auth.bound) {
+            log(`authenticated — cert and binding agree on account ${auth.boundAccountId}`);
         }
-        else if (cloudflared.hasCert()) {
-            // cert.pem exists — derive credentials
-            log("cert.pem found — deriving credentials");
+        else if (auth.hasCert) {
+            // cert.pem exists — materialize binding (migration path) or surface
+            // drift if the binding disagrees with the cert.
             const creds = cloudflared.parseCertPem();
             if (!creds) {
                 log("cert.pem exists but could not extract credentials");
                 return result({
                     status: "error",
-                    message: "Found a Cloudflare certificate but could not extract credentials from it. Try signing in again — I'll clear the old certificate and start fresh.",
+                    message: "Found a Cloudflare certificate but could not extract credentials from it. Sign in again — I'll clear the old certificate and start fresh.",
                 });
             }
-            const validation = await cloudflared.validateToken(creds.apiToken);
-            if (!validation.valid) {
-                log(`cert-derived token rejected: ${validation.error}`);
+            if (!auth.hasBinding) {
+                const binding = cloudflared.materializeBinding("migration");
+                log(`materialized binding from existing cert — account ${binding.accountId}`);
+            }
+            else if (auth.certAccountId !== auth.boundAccountId) {
+                log(`account drift: cert=${auth.certAccountId} binding=${auth.boundAccountId}`);
                 return result({
                     status: "error",
-                    message: `The credentials from your Cloudflare certificate were rejected: ${validation.error}. Try signing in again.`,
+                    message: `Your Cloudflare certificate is bound to a different account than this device's recorded binding. ${cloudflared.recoveryMessage()}`,
                 });
             }
-            const accountId = validation.accountId ?? creds.accountId;
-            cloudflared.writeToken(creds.apiToken, accountId);
-            log(`credentials derived and stored — account: ${validation.accountName ?? accountId}`);
         }
         else {
             // No cert, no token — need login
@@ -1310,6 +1307,30 @@ server.tool("cloudflare-setup", "Deterministic, UI-driven state machine for Clou
         const adminHostname = `${resolvedAdminLabel}.${domain}`;
         const publicHostname = resolvedPublicLabel ? `${resolvedPublicLabel}.${domain}` : null;
         const hostnames = publicHostname ? [adminHostname, publicHostname] : [adminHostname];
+        // Manifest-scope pre-flight: domain came from live account state
+        // (zone selection, auto-only-active zone, or persisted state). The
+        // account may hold zones outside this brand's declared scope; refuse
+        // before creating any tunnel/state so we don't write orphan local
+        // state. routeDnsCli will refuse later anyway, but only after the
+        // tunnel is created and config.yml is written.
+        const setupBrand = cloudflared.loadBrand();
+        for (const h of hostnames) {
+            const scopeCheck = cloudflared.matchManifestZone(h, setupBrand.cloudflare.zones);
+            if (!scopeCheck.ok) {
+                const detail = {
+                    reason: "scope-mismatch",
+                    message: `Cannot set up ${h} — its registrable parent is not in this brand's declared ` +
+                        `Cloudflare zones (${setupBrand.cloudflare.zones.join(", ")}). ` +
+                        `The selected domain ${domain} is on the bound Cloudflare account but outside ` +
+                        `the brand's manifest. Either pick a domain inside the declared scope, or add ` +
+                        `${domain} to brand.json and republish.`,
+                    fields: { requestedHostname: h, requestedDomain: domain, manifestZones: setupBrand.cloudflare.zones },
+                };
+                cloudflared.logRefuse(detail);
+                log(`scope-mismatch: hostname=${h} not in declared zones`);
+                return result({ status: "error", message: detail.message });
+            }
+        }
         // ── Step 5: Resolve or create tunnel (idempotent on re-entry) ───
         let tunnelId = existingState?.tunnelId ?? null;
         let tunnelName = existingState?.tunnelName ?? null;