openclaw-cloudflare 0.1.0

package/src/tunnel/cloudflared.ts

@@ -0,0 +1,209 @@
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+
+type ExecResult = { stdout: string; stderr: string };
+type ExecFn = (cmd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<ExecResult>;
+
+/** Simple execFile wrapper to avoid depending on openclaw core's runExec. */
+function defaultExec(cmd: string, args: string[], opts?: { timeoutMs?: number }): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: opts?.timeoutMs ?? 5000 }, (err, stdout, stderr) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve({ stdout, stderr });
+      }
+    });
+  });
+}
+
+/**
+ * Locate the cloudflared binary using multiple strategies:
+ * 1. Environment override (for testing)
+ * 2. PATH lookup (via `which`)
+ * 3. Known install paths
+ */
+export async function findCloudflaredBinary(
+  exec: ExecFn = defaultExec,
+): Promise<string | null> {
+  const forced = process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY?.trim();
+  if (forced) {
+    return forced;
+  }
+
+  const checkBinary = async (path: string): Promise<boolean> => {
+    if (!path || !existsSync(path)) {
+      return false;
+    }
+    try {
+      await exec(path, ["--version"], { timeoutMs: 3000 });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  // Strategy 1: which command
+  try {
+    const { stdout } = await exec("which", ["cloudflared"]);
+    const fromPath = stdout.trim();
+    if (fromPath && (await checkBinary(fromPath))) {
+      return fromPath;
+    }
+  } catch {
+    // which failed, continue
+  }
+
+  // Strategy 2: Known install paths
+  const knownPaths = [
+    "/usr/local/bin/cloudflared",
+    "/usr/bin/cloudflared",
+    "/opt/homebrew/bin/cloudflared",
+  ];
+  for (const candidate of knownPaths) {
+    if (await checkBinary(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+let cachedCloudflaredBinary: string | null = null;
+
+export async function getCloudflaredBinary(exec: ExecFn = defaultExec): Promise<string> {
+  const forced = process.env.OPENCLAW_TEST_CLOUDFLARED_BINARY?.trim();
+  if (forced) {
+    cachedCloudflaredBinary = forced;
+    return forced;
+  }
+  if (cachedCloudflaredBinary) {
+    return cachedCloudflaredBinary;
+  }
+  cachedCloudflaredBinary = await findCloudflaredBinary(exec);
+  return cachedCloudflaredBinary ?? "cloudflared";
+}
+
+export type CloudflaredTunnel = {
+  /** Connector ID parsed from cloudflared output, if available. */
+  connectorId: string | null;
+  pid: number | null;
+  stderr: string[];
+  stop: () => Promise<void>;
+};
+
+/**
+ * Start a cloudflared tunnel process using a pre-configured tunnel token.
+ *
+ * The token encodes the tunnel UUID, account tag, and tunnel secret — cloudflared
+ * connects to the Cloudflare edge and routes traffic to the local origin.
+ */
+export async function startCloudflaredTunnel(opts: {
+  token: string;
+  timeoutMs?: number;
+  exec?: ExecFn;
+}): Promise<CloudflaredTunnel> {
+  const exec = opts.exec ?? defaultExec;
+  const bin = await getCloudflaredBinary(exec);
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const stderr: string[] = [];
+
+  // Pass the token via TUNNEL_TOKEN env var rather than --token CLI arg
+  // to avoid leaking the secret in `ps` output.
+  const args = ["tunnel", "run"];
+  const child: ChildProcess = spawn(bin, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, TUNNEL_TOKEN: opts.token },
+  });
+
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+
+  let connectorId: string | null = null;
+
+  const collectOutput = (stream: NodeJS.ReadableStream | null) => {
+    stream?.on("data", (chunk: string) => {
+      const lines = String(chunk)
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+      stderr.push(...lines);
+
+      // Parse connector ID from cloudflared output
+      for (const line of lines) {
+        const match = line.match(/Registered tunnel connection\s+connectorID=([a-f0-9-]+)/i);
+        if (match) {
+          connectorId = match[1];
+        }
+      }
+    });
+  };
+
+  collectOutput(child.stdout);
+  collectOutput(child.stderr);
+
+  const stop = async () => {
+    if (child.killed) {
+      return;
+    }
+    child.kill("SIGTERM");
+    await new Promise<void>((resolve) => {
+      const t = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } finally {
+          resolve();
+        }
+      }, 1500);
+      child.once("exit", () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  };
+
+  // Wait for the tunnel to register at least one connection, or timeout.
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      new Promise<void>((resolve) => {
+        const check = setInterval(() => {
+          if (connectorId) {
+            clearInterval(check);
+            resolve();
+          }
+        }, 100);
+        // Clean up interval on process exit
+        child.once("exit", () => clearInterval(check));
+      }),
+      new Promise<void>((_, reject) => {
+        timeoutHandle = setTimeout(
+          () => reject(new Error("cloudflared tunnel did not register within timeout")),
+          timeoutMs,
+        );
+      }),
+      new Promise<void>((_, reject) => {
+        child.once("exit", (code, signal) => {
+          reject(
+            new Error(
+              `cloudflared exited before tunnel registered (${code ?? "null"}${signal ? `/${signal}` : ""})`,
+            ),
+          );
+        });
+      }),
+    ]);
+  } catch (err) {
+    await stop();
+    const suffix = stderr.length > 0 ? `\n${stderr.join("\n")}` : "";
+    throw new Error(`${err instanceof Error ? err.message : String(err)}${suffix}`, { cause: err });
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+
+  return {
+    connectorId,
+    pid: typeof child.pid === "number" ? child.pid : null,
+    stderr,
+    stop,
+  };
+}

package/src/tunnel/exposure.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+const startCloudflaredTunnelMock = vi.fn();
+vi.mock("./cloudflared.js", () => ({
+  startCloudflaredTunnel: (...args: unknown[]) => startCloudflaredTunnelMock(...args),
+}));
+
+function createMockLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+}
+
+describe("startGatewayCloudflareExposure", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    startCloudflaredTunnelMock.mockReset();
+  });
+
+  it("returns null when mode is off", async () => {
+    const { startGatewayCloudflareExposure } = await import("./exposure.js");
+    const log = createMockLogger();
+
+    const result = await startGatewayCloudflareExposure({
+      cloudflareMode: "off",
+      logCloudflare: log,
+    });
+
+    expect(result).toBeNull();
+    expect(log.info).not.toHaveBeenCalled();
+    expect(log.error).not.toHaveBeenCalled();
+  });
+
+  it("returns null and logs info in access-only mode", async () => {
+    const { startGatewayCloudflareExposure } = await import("./exposure.js");
+    const log = createMockLogger();
+
+    const result = await startGatewayCloudflareExposure({
+      cloudflareMode: "access-only",
+      logCloudflare: log,
+    });
+
+    expect(result).toBeNull();
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringContaining("access-only mode"),
+    );
+  });
+
+  it("returns null and logs error in managed mode without token", async () => {
+    const { startGatewayCloudflareExposure } = await import("./exposure.js");
+    const log = createMockLogger();
+
+    const result = await startGatewayCloudflareExposure({
+      cloudflareMode: "managed",
+      logCloudflare: log,
+    });
+
+    expect(result).toBeNull();
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining("no tunnel token provided"),
+    );
+  });
+
+  it("starts tunnel and returns stop function in managed mode", async () => {
+    const stopFn = vi.fn();
+    startCloudflaredTunnelMock.mockResolvedValue({
+      connectorId: "abc-123",
+      pid: 9999,
+      stderr: [],
+      stop: stopFn,
+    });
+
+    const { startGatewayCloudflareExposure } = await import("./exposure.js");
+    const log = createMockLogger();
+
+    const result = await startGatewayCloudflareExposure({
+      cloudflareMode: "managed",
+      tunnelToken: "test-token",
+      logCloudflare: log,
+    });
+
+    expect(result).toBe(stopFn);
+    expect(startCloudflaredTunnelMock).toHaveBeenCalledWith({
+      token: "test-token",
+      timeoutMs: 30_000,
+    });
+    expect(log.info).toHaveBeenCalledWith(
+      expect.stringContaining("connectorId=abc-123"),
+    );
+  });
+
+  it("returns null and logs error when tunnel start fails", async () => {
+    startCloudflaredTunnelMock.mockRejectedValue(new Error("connection refused"));
+
+    const { startGatewayCloudflareExposure } = await import("./exposure.js");
+    const log = createMockLogger();
+
+    const result = await startGatewayCloudflareExposure({
+      cloudflareMode: "managed",
+      tunnelToken: "bad-token",
+      logCloudflare: log,
+    });
+
+    expect(result).toBeNull();
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining("connection refused"),
+    );
+  });
+});

package/src/tunnel/exposure.ts

@@ -0,0 +1,44 @@
+import { startCloudflaredTunnel } from "./cloudflared.js";
+
+export async function startGatewayCloudflareExposure(params: {
+  cloudflareMode: "off" | "managed" | "access-only";
+  tunnelToken?: string;
+  logCloudflare: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}): Promise<(() => Promise<void>) | null> {
+  if (params.cloudflareMode === "off") {
+    return null;
+  }
+
+  if (params.cloudflareMode === "access-only") {
+    params.logCloudflare.info(
+      "access-only mode: Cloudflare Access JWT verification active (external cloudflared expected)",
+    );
+    return null;
+  }
+
+  // managed mode — spawn cloudflared tunnel run
+  if (!params.tunnelToken) {
+    params.logCloudflare.error("managed mode: no tunnel token provided, skipping tunnel start");
+    return null;
+  }
+
+  try {
+    const tunnel = await startCloudflaredTunnel({
+      token: params.tunnelToken,
+      timeoutMs: 30_000,
+    });
+    params.logCloudflare.info(
+      `managed tunnel running (connectorId=${tunnel.connectorId ?? "unknown"}, pid=${tunnel.pid ?? "unknown"})`,
+    );
+    return tunnel.stop;
+  } catch (err) {
+    params.logCloudflare.error(
+      `managed tunnel failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+  },
+});