openclaw-cloudflare 0.1.0

package/src/tunnel/access.test.ts

@@ -0,0 +1,280 @@
+import crypto from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import { createCloudflareAccessVerifier } from "./access.js";
+
+// Generate a test RSA keypair for signing JWTs
+const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  publicKeyEncoding: { type: "spki", format: "pem" },
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+});
+
+// Export as JWK for the mock JWKS endpoint
+const publicJwk = crypto.createPublicKey(publicKey).export({ format: "jwk" }) as {
+  kty: string;
+  n: string;
+  e: string;
+};
+
+const TEST_KID = "test-key-1";
+const TEST_TEAM_DOMAIN = "myteam";
+const TEST_ISSUER = `https://${TEST_TEAM_DOMAIN}.cloudflareaccess.com`;
+const TEST_AUDIENCE = "test-aud-tag";
+
+function base64UrlEncode(data: Buffer | string): string {
+  const buf = typeof data === "string" ? Buffer.from(data) : data;
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+async function createTestJwt(opts: {
+  email?: string;
+  iss?: string;
+  aud?: string | string[];
+  exp?: number;
+  kid?: string;
+}): Promise<string> {
+  const header = {
+    alg: "RS256",
+    typ: "JWT",
+    kid: opts.kid ?? TEST_KID,
+  };
+
+  const payload = {
+    email: opts.email ?? "user@example.com",
+    sub: "user-123",
+    iss: opts.iss ?? TEST_ISSUER,
+    aud: opts.aud ?? TEST_AUDIENCE,
+    exp: opts.exp ?? Math.floor(Date.now() / 1000) + 3600,
+    iat: Math.floor(Date.now() / 1000),
+  };
+
+  const headerB64 = base64UrlEncode(JSON.stringify(header));
+  const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+  const signingInput = `${headerB64}.${payloadB64}`;
+
+  const sign = crypto.createSign("RSA-SHA256");
+  sign.update(signingInput);
+  const signature = sign.sign(privateKey);
+
+  return `${signingInput}.${base64UrlEncode(signature)}`;
+}
+
+function createMockFetch(): typeof globalThis.fetch {
+  return vi.fn(async (url: string | URL | Request) => {
+    const urlStr = typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url;
+    if (urlStr.includes("/cdn-cgi/access/certs")) {
+      return new Response(
+        JSON.stringify({
+          keys: [
+            {
+              kty: publicJwk.kty,
+              kid: TEST_KID,
+              alg: "RS256",
+              use: "sig",
+              n: publicJwk.n,
+              e: publicJwk.e,
+            },
+          ],
+        }),
+        { status: 200 },
+      );
+    }
+    return new Response("Not Found", { status: 404 });
+  }) as typeof globalThis.fetch;
+}
+
+describe("cloudflare-access verifier", () => {
+  it("verifies a valid JWT and returns user email", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({});
+    const result = await verifier.verify(token);
+
+    expect(result).not.toBeNull();
+    expect(result!.email).toBe("user@example.com");
+  });
+
+  it("rejects expired JWT", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({
+      exp: Math.floor(Date.now() / 1000) - 3600,
+    });
+    const result = await verifier.verify(token);
+
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with wrong issuer", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({
+      iss: "https://evil.cloudflareaccess.com",
+    });
+    const result = await verifier.verify(token);
+
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with wrong audience when audience is configured", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({
+      aud: "wrong-audience",
+    });
+    const result = await verifier.verify(token);
+
+    expect(result).toBeNull();
+  });
+
+  it("accepts any audience when audience is not configured", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({
+      aud: "any-audience",
+    });
+    const result = await verifier.verify(token);
+
+    expect(result).not.toBeNull();
+    expect(result!.email).toBe("user@example.com");
+  });
+
+  it("rejects malformed token", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      fetchFn: createMockFetch(),
+    });
+
+    const result = await verifier.verify("not.a.valid.jwt");
+    expect(result).toBeNull();
+  });
+
+  it("rejects token with unknown kid", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({ kid: "unknown-key-id" });
+    const result = await verifier.verify(token);
+
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with tampered signature", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({});
+    // Tamper with the signature
+    const parts = token.split(".");
+    parts[2] = base64UrlEncode(crypto.randomBytes(256));
+    const tampered = parts.join(".");
+
+    const result = await verifier.verify(tampered);
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with unsupported algorithm", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    // Create a token with alg: "none"
+    const header = { alg: "none", typ: "JWT", kid: TEST_KID };
+    const payload = {
+      email: "user@example.com",
+      sub: "user-123",
+      iss: TEST_ISSUER,
+      aud: TEST_AUDIENCE,
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      iat: Math.floor(Date.now() / 1000),
+    };
+    const headerB64 = base64UrlEncode(JSON.stringify(header));
+    const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+    const token = `${headerB64}.${payloadB64}.${base64UrlEncode("fake")}`;
+
+    const result = await verifier.verify(token);
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with tampered payload but original signature", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      audience: TEST_AUDIENCE,
+      fetchFn: createMockFetch(),
+    });
+
+    const token = await createTestJwt({});
+    const parts = token.split(".");
+
+    // Tamper with the payload (change email) but keep original signature
+    const tamperedPayload = {
+      email: "attacker@evil.com",
+      sub: "user-123",
+      iss: TEST_ISSUER,
+      aud: TEST_AUDIENCE,
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      iat: Math.floor(Date.now() / 1000),
+    };
+    parts[1] = base64UrlEncode(JSON.stringify(tamperedPayload));
+    const tampered = parts.join(".");
+
+    const result = await verifier.verify(tampered);
+    expect(result).toBeNull();
+  });
+
+  it("rejects JWT with no email claim", async () => {
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain: TEST_TEAM_DOMAIN,
+      fetchFn: createMockFetch(),
+    });
+
+    // Create a token with no email
+    const header = {
+      alg: "RS256",
+      typ: "JWT",
+      kid: TEST_KID,
+    };
+    const payload = {
+      sub: "service-token",
+      iss: TEST_ISSUER,
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      iat: Math.floor(Date.now() / 1000),
+    };
+    const headerB64 = base64UrlEncode(JSON.stringify(header));
+    const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const sign = crypto.createSign("RSA-SHA256");
+    sign.update(signingInput);
+    const signature = sign.sign(privateKey);
+    const token = `${signingInput}.${base64UrlEncode(signature)}`;
+
+    const result = await verifier.verify(token);
+    expect(result).toBeNull();
+  });
+});

package/src/tunnel/access.ts

@@ -0,0 +1,210 @@
+import crypto from "node:crypto";
+
+export type CloudflareAccessUser = {
+  email: string;
+};
+
+export type CloudflareAccessVerifier = {
+  verify(token: string): Promise<CloudflareAccessUser | null>;
+};
+
+type JwksKey = {
+  kty: string;
+  kid: string;
+  alg?: string;
+  n?: string;
+  e?: string;
+  crv?: string;
+  x?: string;
+  y?: string;
+  use?: string;
+};
+
+type JwksResponse = {
+  keys: JwksKey[];
+};
+
+type JwtHeader = {
+  alg: string;
+  kid?: string;
+  typ?: string;
+};
+
+type JwtPayload = {
+  email?: string;
+  sub?: string;
+  iss?: string;
+  aud?: string | string[];
+  exp?: number;
+  iat?: number;
+  [key: string]: unknown;
+};
+
+const JWKS_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+function base64UrlDecode(input: string): Buffer {
+  // Replace URL-safe chars and add padding
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+  const paddedLength = padded.length + ((4 - (padded.length % 4)) % 4);
+  return Buffer.from(padded.padEnd(paddedLength, "="), "base64");
+}
+
+function decodeJwtPart<T>(part: string): T {
+  return JSON.parse(base64UrlDecode(part).toString("utf8")) as T;
+}
+
+function jwkToCryptoKeyAlgorithm(jwk: JwksKey): RsaHashedImportParams | EcKeyImportParams {
+  if (jwk.kty === "RSA") {
+    return { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+  }
+  if (jwk.kty === "EC") {
+    const namedCurve = jwk.crv ?? "P-256";
+    return { name: "ECDSA", namedCurve };
+  }
+  throw new Error(`Unsupported JWK key type: ${jwk.kty}`);
+}
+
+function verifyAlgorithmForKey(jwk: JwksKey): AlgorithmIdentifier | RsaPssParams | EcdsaParams {
+  if (jwk.kty === "RSA") {
+    return { name: "RSASSA-PKCS1-v1_5" };
+  }
+  if (jwk.kty === "EC") {
+    return { name: "ECDSA", hash: "SHA-256" };
+  }
+  throw new Error(`Unsupported JWK key type: ${jwk.kty}`);
+}
+
+async function importJwk(jwk: JwksKey): Promise<crypto.webcrypto.CryptoKey> {
+  const algorithm = jwkToCryptoKeyAlgorithm(jwk);
+  // Only pass the fields relevant for key import
+  const keyData = {
+    kty: jwk.kty,
+    alg: jwk.alg,
+    use: jwk.use,
+    ...(jwk.kty === "RSA" ? { n: jwk.n, e: jwk.e } : {}),
+    ...(jwk.kty === "EC" ? { crv: jwk.crv, x: jwk.x, y: jwk.y } : {}),
+  };
+  return await crypto.subtle.importKey("jwk", keyData, algorithm, false, ["verify"]);
+}
+
+/**
+ * Create a Cloudflare Access JWT verifier.
+ *
+ * Fetches JWKS from `https://<teamDomain>.cloudflareaccess.com/cdn-cgi/access/certs`
+ * and verifies JWTs using Node's built-in WebCrypto API.
+ */
+export function createCloudflareAccessVerifier(opts: {
+  teamDomain: string;
+  audience?: string;
+  /** Override fetch for testing. */
+  fetchFn?: typeof globalThis.fetch;
+}): CloudflareAccessVerifier {
+  const issuer = `https://${opts.teamDomain}.cloudflareaccess.com`;
+  const jwksUrl = `${issuer}/cdn-cgi/access/certs`;
+  const audience = opts.audience;
+  const fetchFn = opts.fetchFn ?? globalThis.fetch;
+
+  let cachedKeys: Map<string, JwksKey> | null = null;
+  let cachedAt = 0;
+
+  async function fetchJwks(): Promise<Map<string, JwksKey>> {
+    const now = Date.now();
+    if (cachedKeys && now - cachedAt < JWKS_CACHE_TTL_MS) {
+      return cachedKeys;
+    }
+    const res = await fetchFn(jwksUrl);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch JWKS from ${jwksUrl}: ${res.status}`);
+    }
+    const body = (await res.json()) as JwksResponse;
+    const keyMap = new Map<string, JwksKey>();
+    for (const key of body.keys ?? []) {
+      if (key.kid) {
+        keyMap.set(key.kid, key);
+      }
+    }
+    cachedKeys = keyMap;
+    cachedAt = now;
+    return keyMap;
+  }
+
+  async function verify(token: string): Promise<CloudflareAccessUser | null> {
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3) {
+        return null;
+      }
+
+      const header = decodeJwtPart<JwtHeader>(parts[0]);
+      const payload = decodeJwtPart<JwtPayload>(parts[1]);
+
+      // Validate issuer
+      if (payload.iss !== issuer) {
+        return null;
+      }
+
+      // Validate expiry
+      if (typeof payload.exp === "number" && payload.exp < Date.now() / 1000) {
+        return null;
+      }
+
+      // Validate audience (if configured)
+      if (audience) {
+        const aud = payload.aud;
+        const audMatch = Array.isArray(aud) ? aud.includes(audience) : aud === audience;
+        if (!audMatch) {
+          return null;
+        }
+      }
+
+      // Validate algorithm — only RS256 and ES256 are supported
+      const SUPPORTED_ALGS = new Set(["RS256", "ES256"]);
+      if (!SUPPORTED_ALGS.has(header.alg)) {
+        return null;
+      }
+
+      // Find the signing key
+      let keys = await fetchJwks();
+      let jwk = header.kid ? keys.get(header.kid) : undefined;
+
+      // If key not found, refresh JWKS (key rotation)
+      if (!jwk && header.kid) {
+        cachedKeys = null;
+        keys = await fetchJwks();
+        jwk = keys.get(header.kid);
+      }
+      if (!jwk) {
+        return null;
+      }
+
+      // Verify algorithm matches key type
+      const expectedAlg = jwk.kty === "RSA" ? "RS256" : jwk.kty === "EC" ? "ES256" : null;
+      if (header.alg !== expectedAlg) {
+        return null;
+      }
+
+      // Verify signature using WebCrypto
+      const cryptoKey = await importJwk(jwk);
+      const signatureInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+      const signature = new Uint8Array(base64UrlDecode(parts[2]));
+      const algorithm = verifyAlgorithmForKey(jwk);
+
+      const valid = await crypto.subtle.verify(algorithm, cryptoKey, signature, signatureInput);
+
+      if (!valid) {
+        return null;
+      }
+
+      const email = typeof payload.email === "string" ? payload.email : undefined;
+      if (!email) {
+        return null;
+      }
+
+      return { email };
+    } catch {
+      return null;
+    }
+  }
+
+  return { verify };
+}

package/src/tunnel/cloudflared.test.ts

@@ -0,0 +1,176 @@
+import type { ChildProcess } from "node:child_process";
+import type { Readable } from "node:stream";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// Mock spawn
+const spawnMock = vi.fn();
+vi.mock("node:child_process", () => ({
+  execFile: vi.fn(),
+  spawn: (...args: unknown[]) => spawnMock(...args),
+}));
+
+// Mock existsSync
+const existsSyncMock = vi.fn<(p: string) => boolean>(() => true);
+vi.mock("node:fs", () => ({
+  existsSync: (p: string) => existsSyncMock(p),
+}));
+
+// Shared exec mock for findCloudflaredBinary
+const execMock = vi.fn();
+
+describe("findCloudflaredBinary", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    delete process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY;
+  });
+
+  it("returns environment override when set", async () => {
+    process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY = "/custom/cloudflared";
+    const { findCloudflaredBinary } = await import("./cloudflared.js");
+    const result = await findCloudflaredBinary(execMock);
+    expect(result).toBe("/custom/cloudflared");
+  });
+
+  it("finds cloudflared via which", async () => {
+    execMock.mockImplementation((cmd: string, _args: string[]) => {
+      if (cmd === "which") {
+        return Promise.resolve({ stdout: "/usr/local/bin/cloudflared\n", stderr: "" });
+      }
+      // --version check
+      return Promise.resolve({ stdout: "cloudflared version 2024.1.0\n", stderr: "" });
+    });
+    existsSyncMock.mockReturnValue(true);
+
+    const { findCloudflaredBinary } = await import("./cloudflared.js");
+    const result = await findCloudflaredBinary(execMock);
+    expect(result).toBe("/usr/local/bin/cloudflared");
+  });
+
+  it("falls back to known paths when which fails", async () => {
+    execMock.mockImplementation((cmd: string, _args: string[]) => {
+      if (cmd === "which") {
+        return Promise.reject(new Error("not found"));
+      }
+      // --version check for known path
+      return Promise.resolve({ stdout: "cloudflared version 2024.1.0\n", stderr: "" });
+    });
+    existsSyncMock.mockImplementation((p: string) => p === "/usr/local/bin/cloudflared");
+
+    const { findCloudflaredBinary } = await import("./cloudflared.js");
+    const result = await findCloudflaredBinary(execMock);
+    expect(result).toBe("/usr/local/bin/cloudflared");
+  });
+
+  it("returns null when binary is not found", async () => {
+    execMock.mockRejectedValue(new Error("not found"));
+    existsSyncMock.mockReturnValue(false);
+
+    const { findCloudflaredBinary } = await import("./cloudflared.js");
+    const result = await findCloudflaredBinary(execMock);
+    expect(result).toBeNull();
+  });
+});
+
+describe("startCloudflaredTunnel", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    delete process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY;
+  });
+
+  function createMockProcess(): ChildProcess & {
+    _emit: (event: string, ...args: unknown[]) => void;
+    _emitStderr: (data: string) => void;
+  } {
+    const events: Record<string, Array<(...args: unknown[]) => void>> = {};
+    const stdoutEvents: Record<string, Array<(...args: unknown[]) => void>> = {};
+    const stderrEvents: Record<string, Array<(...args: unknown[]) => void>> = {};
+
+    const mockStdout = {
+      setEncoding: vi.fn(),
+      on: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+        stdoutEvents[event] = stdoutEvents[event] ?? [];
+        stdoutEvents[event].push(cb);
+      }),
+    };
+    const mockStderr = {
+      setEncoding: vi.fn(),
+      on: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+        stderrEvents[event] = stderrEvents[event] ?? [];
+        stderrEvents[event].push(cb);
+      }),
+    };
+
+    return {
+      pid: 12345,
+      killed: false,
+      stdout: mockStdout as unknown as Readable,
+      stderr: mockStderr as unknown as Readable,
+      kill: vi.fn(),
+      on: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+        events[event] = events[event] ?? [];
+        events[event].push(cb);
+      }),
+      once: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+        events[event] = events[event] ?? [];
+        events[event].push(cb);
+      }),
+      _emit: (event: string, ...args: unknown[]) => {
+        for (const cb of events[event] ?? []) {
+          cb(...args);
+        }
+      },
+      _emitStderr: (data: string) => {
+        for (const cb of stderrEvents.data ?? []) {
+          cb(data);
+        }
+      },
+    } as unknown as ChildProcess & {
+      _emit: (event: string, ...args: unknown[]) => void;
+      _emitStderr: (data: string) => void;
+    };
+  }
+
+  it("starts tunnel and parses connector ID", async () => {
+    const mockChild = createMockProcess();
+
+    spawnMock.mockReturnValue(mockChild);
+    process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY = "/usr/local/bin/cloudflared";
+
+    const { startCloudflaredTunnel } = await import("./cloudflared.js");
+
+    const tunnelPromise = startCloudflaredTunnel({
+      token: "test-token",
+      timeoutMs: 5000,
+    });
+
+    // Simulate cloudflared registering a connection
+    await new Promise((r) => setTimeout(r, 50));
+    mockChild._emitStderr("INF Registered tunnel connection connectorID=abc123-def456");
+
+    const tunnel = await tunnelPromise;
+    expect(tunnel.connectorId).toBe("abc123-def456");
+    expect(tunnel.pid).toBe(12345);
+    expect(typeof tunnel.stop).toBe("function");
+  });
+
+  it("throws when tunnel exits before registering", async () => {
+    const mockChild = createMockProcess();
+
+    spawnMock.mockReturnValue(mockChild);
+    process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY = "/usr/local/bin/cloudflared";
+
+    const { startCloudflaredTunnel } = await import("./cloudflared.js");
+
+    const tunnelPromise = startCloudflaredTunnel({
+      token: "bad-token",
+      timeoutMs: 5000,
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+    mockChild._emit("exit", 1, null);
+
+    await expect(tunnelPromise).rejects.toThrow(/cloudflared exited/);
+  });
+});