@rubytech/create-realagent 1.0.615 → 1.0.616

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 — declarative brand-zone scope, deterministic recovery
 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.
+The brand declares its Cloudflare zones in `brand.json` (`cloudflare.zones`) at build time. Every tool refuses operations against hostnames whose registrable parent is not in that list — declared scope is authoritative. `cloudflare-setup` is the single onboarding orchestrator: a UI-driven state machine that prompts for tunnel/zone selections and admin/public addresses via rendered components (`single-select`, `tunnel-route-picker`). Tunnel names are unique per customer (derived from chosen admin label + domain) so multiple customers can coexist on a shared zone. The agent never synthesises subdomains from free text — every label comes from a component submission. Authentication is OAuth-only via `tunnel-login`; on first success the device records an `account-binding.json` so any later cert rotation under a different Cloudflare account is detected and refused. `cf-verify` is the non-mutating audit; `cf-rebuild` is the deterministic recovery.
 
 ## When to activate
 

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

@@ -0,0 +1,196 @@
+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",
+    cloudflare: { zones: ["maxy.bot"] },
+  });
+});
+
+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();
+  });
+});

package/payload/platform/plugins/cloudflare/mcp/__tests__/brand-load.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { _resetBrandCache, loadBrand } from "../src/lib/cloudflared.js";
+
+// loadBrand() reads PLATFORM_ROOT/config/brand.json. We point PLATFORM_ROOT at
+// a fresh tmpdir per test, write the brand.json shape we want, reset the
+// module-level cache, then assert load behaviour.
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "maxy-cf-brand-"));
+  process.env.PLATFORM_ROOT = tmpRoot;
+  _resetBrandCache();
+});
+
+afterEach(() => {
+  rmSync(tmpRoot, { recursive: true, force: true });
+  delete process.env.PLATFORM_ROOT;
+});
+
+function writeBrand(content: object): void {
+  const dir = join(tmpRoot, "config");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "brand.json"), JSON.stringify(content));
+}
+
+describe("loadBrand cloudflare.zones validation", () => {
+  it("loads when cloudflare.zones is present", () => {
+    writeBrand({
+      productName: "Maxy",
+      configDir: ".maxy",
+      cloudflare: { zones: ["maxy.bot", "maxy.chat"] },
+    });
+    const brand = loadBrand();
+    expect(brand.cloudflare.zones).toEqual(["maxy.bot", "maxy.chat"]);
+  });
+
+  it("hard-fails when cloudflare key is absent", () => {
+    writeBrand({ productName: "Maxy", configDir: ".maxy" });
+    expect(() => loadBrand()).toThrow(/cloudflare\.zones/);
+  });
+
+  it("hard-fails when cloudflare.zones is empty", () => {
+    writeBrand({
+      productName: "Maxy",
+      configDir: ".maxy",
+      cloudflare: { zones: [] },
+    });
+    expect(() => loadBrand()).toThrow(/cloudflare\.zones/);
+  });
+
+  it("hard-fails when cloudflare.zones is not an array", () => {
+    writeBrand({
+      productName: "Maxy",
+      configDir: ".maxy",
+      cloudflare: { zones: "maxy.bot" },
+    });
+    expect(() => loadBrand()).toThrow(/cloudflare\.zones/);
+  });
+
+  it("hard-fails when cloudflare.zones contains a non-string", () => {
+    writeBrand({
+      productName: "Maxy",
+      configDir: ".maxy",
+      cloudflare: { zones: ["maxy.bot", 42] },
+    });
+    expect(() => loadBrand()).toThrow(/invalid cloudflare\.zones entry/);
+  });
+
+  it("hard-fails when PLATFORM_ROOT is unset", () => {
+    delete process.env.PLATFORM_ROOT;
+    expect(() => loadBrand()).toThrow(/PLATFORM_ROOT/);
+  });
+
+  it("hard-fails when brand.json is absent at the configured path", () => {
+    expect(() => loadBrand()).toThrow(/brand\.json not found/);
+  });
+});

package/payload/platform/plugins/cloudflare/mcp/__tests__/manifest-scope.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { matchManifestZone } from "../src/lib/cloudflared.js";
+
+// Pure function — no fs, no network. Tests the registrable-parent suffix-match
+// against an explicit declared-zone list. The whole point of declarative zones
+// is that we never need a PSL lookup or a "last two labels" heuristic.
+
+describe("matchManifestZone", () => {
+  const zones = ["maxy.bot", "maxy.chat", "example.co.uk"];
+
+  it("matches a hostname whose registrable parent is in the zone list", () => {
+    const r = matchManifestZone("admin.maxy.bot", zones);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("maxy.bot");
+  });
+
+  it("matches the zone itself (no subdomain)", () => {
+    const r = matchManifestZone("maxy.bot", zones);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("maxy.bot");
+  });
+
+  it("matches deeper subdomains", () => {
+    const r = matchManifestZone("foo.bar.maxy.bot", zones);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("maxy.bot");
+  });
+
+  it("matches case-insensitively", () => {
+    const r = matchManifestZone("Admin.MAXY.BOT", zones);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("maxy.bot");
+  });
+
+  it("refuses hostnames outside the zone list", () => {
+    const r = matchManifestZone("admin.example.org", zones);
+    expect(r.ok).toBe(false);
+    expect(r.matchedZone).toBeNull();
+    expect(r.declaredZones).toEqual(zones);
+  });
+
+  it("does not partial-match — admin.notmaxy.bot must not match maxy.bot", () => {
+    // The leading-dot boundary is what prevents this.
+    const r = matchManifestZone("admin.notmaxy.bot", zones);
+    expect(r.ok).toBe(false);
+  });
+
+  it("handles multi-label TLDs (.co.uk) when declared", () => {
+    const r = matchManifestZone("admin.example.co.uk", zones);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("example.co.uk");
+  });
+
+  it("prefers the longest match when zones overlap", () => {
+    const overlap = ["bot", "maxy.bot"];
+    const r = matchManifestZone("admin.maxy.bot", overlap);
+    expect(r.ok).toBe(true);
+    expect(r.matchedZone).toBe("maxy.bot");
+  });
+
+  it("refuses against an empty zone list", () => {
+    const r = matchManifestZone("admin.maxy.bot", []);
+    expect(r.ok).toBe(false);
+  });
+});

package/payload/platform/plugins/cloudflare/mcp/__tests__/verify-scenario-0.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  _resetBrandCache,
+  cfVerifyCore,
+  liveScopeContext,
+} from "../src/lib/cloudflared.js";
+
+// Scenario 0 (per task spec): fresh install — no cert.pem, no binding,
+// no tunnels, no config.yml. cf-verify must return zero OUT-OF-SCOPE,
+// every declared zone tagged MISSING, no throws. Proves the audit runs
+// before any login completes.
+
+let tmpRoot: string;
+let homeRoot: string;
+let originalHome: string | undefined;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "maxy-cf-verify-"));
+  homeRoot = mkdtempSync(join(tmpdir(), "maxy-cf-home-"));
+  originalHome = process.env.HOME;
+  process.env.HOME = homeRoot;
+  process.env.PLATFORM_ROOT = tmpRoot;
+  _resetBrandCache();
+  const cfg = join(tmpRoot, "config");
+  mkdirSync(cfg, { recursive: true });
+  writeFileSync(
+    join(cfg, "brand.json"),
+    JSON.stringify({
+      productName: "Maxy",
+      configDir: ".maxy",
+      cloudflare: { zones: ["b.test", "c.test"] },
+    }),
+  );
+});
+
+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("cfVerifyCore — Scenario 0 (fresh install, no login)", () => {
+  it("runs without throwing and reports everything as MISSING", async () => {
+    const ctx = liveScopeContext();
+    const report = await cfVerifyCore(ctx);
+
+    expect(report.brand).toBe("Maxy");
+    expect(report.declaredZones).toEqual(["b.test", "c.test"]);
+    expect(report.bindingPresent).toBe(false);
+    expect(report.bindingMatchesCert).toBe(false);
+    expect(report.certPresent).toBe(false);
+
+    // No OUT-OF-SCOPE artefacts on a clean fresh device.
+    expect(report.counts.outOfScope).toBe(0);
+
+    // Cert, binding, tunnel.state, and each declared zone all MISSING.
+    const missingTypes = report.artefacts
+      .filter((a) => a.tag === "missing")
+      .map((a) => a.type);
+    expect(missingTypes).toContain("cert.pem");
+    expect(missingTypes).toContain("binding");
+    expect(missingTypes).toContain("tunnel.state");
+    expect(missingTypes.filter((t) => t === "declared-zone").length).toBe(2);
+  });
+});

package/payload/platform/plugins/cloudflare/mcp/__tests__/verify-scenario-B.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  _resetBrandCache,
+  cfVerifyCore,
+  writeAccountBinding,
+  type ScopeContext,
+} from "../src/lib/cloudflared.js";
+
+// Scenario B (per task spec): stale tunnel state. Brand declares
+// cloudflare.zones=["b.test"]. cert.pem and binding agree on account Y.
+// But tunnel.state references a deleted tunnel, config.yml names a
+// hostname under a zone NOT in declared scope, and alias-domains.json
+// has an entry for removed.test (also out of scope).
+//
+// We bypass the SDK (no live calls) by passing a ScopeContext with
+// client=null. The local-artefact analysis runs in full; the account-side
+// analysis surfaces declared zones as MISSING (no client = nothing to
+// enumerate), which is correct behaviour for this audit-only test.
+
+let tmpRoot: string;
+let homeRoot: string;
+let originalHome: string | undefined;
+const CONFIG_DIR = ".maxy";
+
+function home(...p: string[]): string {
+  return join(homeRoot, ...p);
+}
+
+function writeCertPem(accountId: string, apiToken: string): void {
+  const certDir = home(CONFIG_DIR, "cloudflared");
+  mkdirSync(certDir, { recursive: true });
+  const tokenJson = JSON.stringify({ APIToken: apiToken, AccountTag: accountId });
+  const b64 = Buffer.from(tokenJson, "utf-8").toString("base64");
+  const pem = `-----BEGIN ARGO TUNNEL TOKEN-----
+${b64}
+-----END ARGO TUNNEL TOKEN-----
+`;
+  writeFileSync(join(certDir, "cert.pem"), pem);
+}
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "maxy-cf-verifyB-"));
+  homeRoot = mkdtempSync(join(tmpdir(), "maxy-cf-home-"));
+  originalHome = process.env.HOME;
+  process.env.HOME = homeRoot;
+  process.env.PLATFORM_ROOT = tmpRoot;
+  _resetBrandCache();
+  const cfg = join(tmpRoot, "config");
+  mkdirSync(cfg, { recursive: true });
+  writeFileSync(
+    join(cfg, "brand.json"),
+    JSON.stringify({
+      productName: "Maxy",
+      configDir: CONFIG_DIR,
+      cloudflare: { zones: ["b.test"] },
+    }),
+  );
+});
+
+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("cfVerifyCore — Scenario B (stale tunnel state)", () => {
+  it("tags out-of-scope local artefacts even without a live SDK client", async () => {
+    writeCertPem("acct-Y", "cfut_dummy");
+    writeAccountBinding("acct-Y");
+
+    // Stale tunnel.state pointing at a deleted tunnel + off-scope hostname.
+    const cloudflaredDir = home(CONFIG_DIR, "cloudflared");
+    mkdirSync(cloudflaredDir, { recursive: true });
+    const configYmlPath = join(cloudflaredDir, "config.yml");
+    writeFileSync(configYmlPath, "tunnel: stale\n");
+    writeFileSync(
+      join(cloudflaredDir, "tunnel.state"),
+      JSON.stringify({
+        tunnelId: "stale-tunnel-id",
+        tunnelName: "stale",
+        domain: "removed.test", // NOT in brand.cloudflare.zones
+        configPath: configYmlPath,
+        credentialsPath: join(cloudflaredDir, "stale-tunnel-id.json"),
+        adminHostname: "admin.removed.test", // off-scope
+        publicHostname: null,
+        pid: null,
+        startedAt: null,
+      }),
+    );
+
+    // alias-domains entry for an off-scope hostname.
+    writeFileSync(
+      home(CONFIG_DIR, "alias-domains.json"),
+      JSON.stringify(["removed.test"]),
+    );
+
+    // Bypass the SDK — pass a ScopeContext with client=null. The audit
+    // tags every declared zone as MISSING (cannot enumerate without
+    // client) but completes the local-artefact analysis in full.
+    const ctx: ScopeContext = {
+      declaredZones: ["b.test"],
+      binding: { accountId: "acct-Y", boundAt: new Date().toISOString() },
+      client: null,
+    };
+    const report = await cfVerifyCore(ctx);
+
+    const tunnelState = report.artefacts.find((a) => a.type === "tunnel.state");
+    expect(tunnelState?.tag).toBe("out-of-scope");
+    expect(tunnelState?.reason).toContain("hostnames outside declared scope");
+
+    const aliasEntry = report.artefacts.find(
+      (a) => a.type === "alias-domain" && a.id === "removed.test",
+    );
+    expect(aliasEntry?.tag).toBe("out-of-scope");
+
+    // Counts: at least the two out-of-scope local artefacts identified above.
+    expect(report.counts.outOfScope).toBeGreaterThanOrEqual(2);
+  });
+});