@rubytech/create-realagent 1.0.615 → 1.0.617

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -1,12 +1,13 @@
 ---
 name: cloudflare
-description: Cloudflare Tunnel setup and management via official Cloudflare SDK
+description: Cloudflare Tunnel setup and management — bound account is the universe, agent owns it absolutely
 tools:
   - cloudflare-setup
-  - cf-set-token
   - cf-add-zone
-  - tunnel-login
   - cf-zone-status
+  - cf-verify
+  - cf-rebuild
+  - tunnel-login
   - tunnel-status
   - tunnel-install
   - tunnel-create
@@ -18,7 +19,7 @@ tools:
 
 # Cloudflare Tunnel Setup
 
-Guides through setting up a Cloudflare Tunnel so customers can reach this assistant via a custom domain (e.g., `chat.mybusiness.com`). `cloudflare-setup` is the single orchestrator — a UI-driven state machine that prompts the user for tunnel/zone selections and admin/public addresses via rendered components (`single-select`, `tunnel-route-picker`). Tunnel names are unique per customer (derived from the chosen admin label + domain) so multiple customers can coexist on a shared zone like `maxy.bot`. The agent never synthesises subdomains from free text — every label comes from a component submission. Auth via `tunnel-login` (one-click OAuth) or `cf-set-token` (paste token). Browser-specialist is navigation-only — no dashboard forms.
+Each installation has its own Cloudflare account, owned by the user, accessed via `cert.pem` from `tunnel-login` (OAuth — the only auth path). The bound account is the entire universe of routable zones; the agent has absolute authority over it (add, delete, restructure). Anything on the account that doesn't belong to the user's current intended state is junk — `cf-rebuild` deletes it. `cloudflare-setup` is the onboarding orchestrator: a UI-driven state machine that surfaces what's on the account, asks the user to pick a domain and subdomains, then creates the tunnel. `cf-verify` is the non-mutating audit (account state + device state + orphans). The device records `account-binding.json` on first login so cert rotation under a different account is detected and refused — that's the only inherited identity check.
 
 ## When to activate
 

package/payload/platform/plugins/cloudflare/mcp/__tests__/auth-binding.test.ts

@@ -0,0 +1,195 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  CloudflareRefusalError,
+  _resetBrandCache,
+  getClient,
+  getReadOnlyClient,
+  readAccountBinding,
+  validateAuth,
+  writeAccountBinding,
+} from "../src/lib/cloudflared.js";
+
+// Tests for the auth pre-conditions that getClient() enforces. We don't mock
+// the Cloudflare SDK here — we only ever exercise the gate, not the SDK call.
+// The gate throws CloudflareRefusalError BEFORE constructing the client, so
+// no network is touched.
+
+let tmpRoot: string;
+let homeRoot: string;
+let originalHome: string | undefined;
+
+function writeBrand(content: object): void {
+  const dir = join(tmpRoot, "config");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "brand.json"), JSON.stringify(content));
+}
+
+function writeCertPem(accountId: string, apiToken: string): void {
+  const certDir = join(homeRoot, ".maxy", "cloudflared");
+  mkdirSync(certDir, { recursive: true });
+  const tokenJson = JSON.stringify({ APIToken: apiToken, AccountTag: accountId });
+  const b64 = Buffer.from(tokenJson, "utf-8").toString("base64");
+  const pem = `dummy-private-key
+-----BEGIN ARGO TUNNEL TOKEN-----
+${b64}
+-----END ARGO TUNNEL TOKEN-----
+`;
+  writeFileSync(join(certDir, "cert.pem"), pem);
+}
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "maxy-cf-auth-"));
+  homeRoot = mkdtempSync(join(tmpdir(), "maxy-cf-home-"));
+  originalHome = process.env.HOME;
+  process.env.HOME = homeRoot;
+  process.env.PLATFORM_ROOT = tmpRoot;
+  _resetBrandCache();
+  writeBrand({
+    productName: "Maxy",
+    configDir: ".maxy",
+  });
+});
+
+afterEach(() => {
+  if (originalHome !== undefined) process.env.HOME = originalHome;
+  else delete process.env.HOME;
+  delete process.env.PLATFORM_ROOT;
+  rmSync(tmpRoot, { recursive: true, force: true });
+  rmSync(homeRoot, { recursive: true, force: true });
+});
+
+describe("validateAuth — pure read of cert + binding state", () => {
+  it("reports nothing on a fresh install", () => {
+    const auth = validateAuth();
+    expect(auth.hasCert).toBe(false);
+    expect(auth.hasBinding).toBe(false);
+    expect(auth.bound).toBe(false);
+    expect(auth.certAccountId).toBeNull();
+    expect(auth.boundAccountId).toBeNull();
+  });
+
+  it("reports cert when present, no binding", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    const auth = validateAuth();
+    expect(auth.hasCert).toBe(true);
+    expect(auth.hasBinding).toBe(false);
+    expect(auth.bound).toBe(false);
+    expect(auth.certAccountId).toBe("acct-X");
+  });
+
+  it("reports bound when cert + binding agree", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-X");
+    const auth = validateAuth();
+    expect(auth.bound).toBe(true);
+    expect(auth.certAccountId).toBe("acct-X");
+    expect(auth.boundAccountId).toBe("acct-X");
+  });
+
+  it("reports drift when cert and binding disagree", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-Y");
+    const auth = validateAuth();
+    expect(auth.hasCert).toBe(true);
+    expect(auth.hasBinding).toBe(true);
+    expect(auth.bound).toBe(false);
+    expect(auth.certAccountId).toBe("acct-X");
+    expect(auth.boundAccountId).toBe("acct-Y");
+  });
+});
+
+describe("getClient — refuses uncircumventably on auth failures", () => {
+  it("refuses unbound-device when cert is absent", () => {
+    expect(() => getClient()).toThrow(CloudflareRefusalError);
+    try {
+      getClient();
+    } catch (err) {
+      expect((err as CloudflareRefusalError).refusal.reason).toBe("unbound-device");
+    }
+  });
+
+  it("refuses unbound-device when cert exists but no binding", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    try {
+      getClient();
+      throw new Error("expected refusal");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudflareRefusalError);
+      expect((err as CloudflareRefusalError).refusal.reason).toBe("unbound-device");
+    }
+  });
+
+  it("refuses account-drift when cert and binding disagree", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-Y");
+    try {
+      getClient();
+      throw new Error("expected refusal");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CloudflareRefusalError);
+      const refusal = (err as CloudflareRefusalError).refusal;
+      expect(refusal.reason).toBe("account-drift");
+      expect(refusal.fields.certAccountId).toBe("acct-X");
+      expect(refusal.fields.boundAccountId).toBe("acct-Y");
+    }
+  });
+
+  it("succeeds when cert + binding agree", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-X");
+    const { accountId } = getClient();
+    expect(accountId).toBe("acct-X");
+  });
+});
+
+describe("getReadOnlyClient — never throws, surfaces partial state", () => {
+  it("returns nulls on fresh install", () => {
+    const ro = getReadOnlyClient();
+    expect(ro.client).toBeNull();
+    expect(ro.certAccountId).toBeNull();
+    expect(ro.boundAccountId).toBeNull();
+    expect(ro.bindingMatches).toBe(false);
+  });
+
+  it("returns cert info when cert exists, no binding", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    const ro = getReadOnlyClient();
+    expect(ro.client).not.toBeNull();
+    expect(ro.certAccountId).toBe("acct-X");
+    expect(ro.boundAccountId).toBeNull();
+    expect(ro.bindingMatches).toBe(false);
+  });
+
+  it("reports bindingMatches when cert + binding agree", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-X");
+    const ro = getReadOnlyClient();
+    expect(ro.bindingMatches).toBe(true);
+  });
+
+  it("reports bindingMatches=false on drift but still returns client + ids", () => {
+    writeCertPem("acct-X", "cfut_dummy");
+    writeAccountBinding("acct-Y");
+    const ro = getReadOnlyClient();
+    expect(ro.client).not.toBeNull();
+    expect(ro.certAccountId).toBe("acct-X");
+    expect(ro.boundAccountId).toBe("acct-Y");
+    expect(ro.bindingMatches).toBe(false);
+  });
+});
+
+describe("account-binding write/read round-trip", () => {
+  it("persists accountId and a parseable boundAt", () => {
+    writeAccountBinding("acct-Z");
+    const binding = readAccountBinding();
+    expect(binding?.accountId).toBe("acct-Z");
+    expect(binding?.boundAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it("returns null when no binding file exists", () => {
+    expect(readAccountBinding()).toBeNull();
+  });
+});