openclaw-cloudflare 0.1.0 → 0.2.1

package/.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-  "changelog": ["@changesets/changelog-github", { "repo": "G4brym/openclaw-plugin-cloudflare" }],
+  "changelog": ["@changesets/changelog-github", { "repo": "G4brym/openclaw-cloudflare" }],
   "commit": false,
   "fixed": [],
   "linked": [],

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# openclaw-cloudflare
+
+## 0.2.1
+
+### Patch Changes
+
+- [#4](https://github.com/G4brym/openclaw-cloudflare/pull/4) [`a363c11`](https://github.com/G4brym/openclaw-cloudflare/commit/a363c119aa808284762306a529e0572496735684) Thanks [@G4brym](https://github.com/G4brym)! - Add MIT LICENSE file
+
+## 0.2.0
+
+### Minor Changes
+
+- [#1](https://github.com/G4brym/openclaw-cloudflare/pull/1) [`cea0045`](https://github.com/G4brym/openclaw-cloudflare/commit/cea00459c619b0f75b51bc21d31f4f428c970cd3) Thanks [@G4brym](https://github.com/G4brym)! - Auto-install cloudflared binary when not found in managed mode
+
+### Patch Changes
+
+- [#2](https://github.com/G4brym/openclaw-cloudflare/pull/2) [`f395045`](https://github.com/G4brym/openclaw-cloudflare/commit/f395045742bb31c55c0d4d953f8c79f5fb7ac478) Thanks [@G4brym](https://github.com/G4brym)! - Update GitHub repository references to match renamed repo

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenClaw plugin that integrates Cloudflare Tunnel and Cloudflare Access. It spawns/manages a `cloudflared` process for tunnel mode and verifies Cloudflare Access JWTs to identify users. Published to npm as `openclaw-cloudflare`.
+
+## Commands
+
+- **Run all tests:** `npm test` (runs `vitest run`)
+- **Run a single test file:** `npx vitest run src/tunnel/access.test.ts`
+- **Run tests matching a name:** `npx vitest run -t "pattern"`
+- **Typecheck:** `npm run typecheck` (runs `tsc --noEmit`)
+
+## Architecture
+
+ES module TypeScript project (`"type": "module"`) with no build/bundle step for development — the entry point is `./src/index.ts` directly.
+
+### Module Layers
+
+```
+src/index.ts              Plugin interface — exports {id, name, register()}
+                          register() receives OpenClaw API (logger, registerService, registerHttpHandler)
+                          Validates config, wires service + HTTP handler
+
+src/tunnel/exposure.ts    Orchestration — routes to correct mode (off / managed / access-only)
+                          Returns a stop function or null
+
+src/tunnel/cloudflared.ts Process management — finds/installs binary, spawns `cloudflared tunnel run`
+                          Binary auto-install downloads from GitHub to ~/.openclaw/bin/
+                          Passes token via TUNNEL_TOKEN env var (not CLI args)
+                          Waits for connector registration on stderr, with timeout
+
+src/tunnel/access.ts      JWT verification — JWKS fetching with 10min cache, RS256/ES256
+                          Uses Node.js WebCrypto (no external crypto deps)
+                          Returns {email} or null on failure (never throws)
+```
+
+### Plugin Registration Flow
+
+1. `register(api)` validates config and exits early if mode is `"off"`
+2. Registers a **service** (`cloudflare-tunnel`) that on `start()`:
+   - Creates a JWT verifier if `teamDomain` is configured
+   - Calls `startGatewayCloudflareExposure()` which spawns cloudflared in managed mode
+3. Registers an **HTTP handler** that on every request:
+   - Strips `x-openclaw-user-email` and `x-openclaw-auth-source` headers (anti-spoofing)
+   - If verifier exists, reads `Cf-Access-Jwt-Assertion` header, verifies JWT, sets identity headers
+
+### Key Design Patterns
+
+- **Dependency injection everywhere** — logger, exec functions, fetch are all injected, making every module fully testable with mocks
+- **Graceful degradation** — functions return null instead of throwing; errors are logged and the plugin continues
+- **Anti-spoofing** — identity headers are always stripped before verification, then re-set only after successful JWT validation
+
+## Configuration
+
+Three modes configured via `tunnel.mode`:
+- `"off"` (default) — plugin does nothing
+- `"managed"` — spawns cloudflared, requires `tunnelToken` (config or `OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN` env var)
+- `"access-only"` — JWT verification only, expects external cloudflared
+
+Config schema is defined in `openclaw.plugin.json`.
+
+## Workflow
+
+The `main` branch is protected. All code changes must go through a pull request — never commit directly to main.
+
+## Versioning and Releases
+
+Uses [changesets](https://github.com/changesets/changesets). PRs to main require a changeset file (enforced by CI). Merging a changeset to main triggers automated npm publish via GitHub Actions with OIDC provenance.
+
+**Every PR to main must include a changeset.** Add one with `npx changeset` or manually create a file in `.changeset/` with this format:
+
+```md
+---
+"openclaw-cloudflare": patch  # or minor/major
+---
+
+Description of the change
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gabriel Massadas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -42,9 +42,10 @@ Cloudflare integration is disabled.
 OpenClaw spawns and manages a `cloudflared` tunnel process automatically.
 
 **Requirements:**
-- `cloudflared` binary installed and in PATH (or at a known location)
 - A pre-configured tunnel token from the Cloudflare Zero Trust dashboard
 
+> **Auto-install:** If `cloudflared` is not found in PATH or known locations, the plugin automatically downloads the latest release from GitHub to `~/.openclaw/bin/cloudflared`. No manual installation required.
+
 **Setup:**
 
 1. In the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com/), create a tunnel under **Networks > Tunnels**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-cloudflare",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Cloudflare integration plugin for OpenClaw (Tunnel, Access, and more)",
   "type": "module",
   "exports": {
@@ -24,7 +24,9 @@
     "vitest": "^3.0.0"
   },
   "openclaw": {
-    "extensions": ["./src/index.ts"],
+    "extensions": [
+      "./src/index.ts"
+    ],
     "install": {
       "npmSpec": "openclaw-cloudflare",
       "defaultChoice": "npm"
@@ -40,7 +42,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/G4brym/openclaw-plugin-cloudflare.git"
+    "url": "git+https://github.com/G4brym/openclaw-cloudflare.git"
   },
   "publishConfig": {
     "provenance": true,

package/src/tunnel/cloudflared.test.ts

@@ -1,11 +1,12 @@
 import type { ChildProcess } from "node:child_process";
 import type { Readable } from "node:stream";
-import { describe, expect, it, vi, beforeEach } from "vitest";
+import { afterEach, describe, expect, it, vi, beforeEach } from "vitest";
 
-// Mock spawn
+// Mock spawn and execFile (promisified via util.promisify)
 const spawnMock = vi.fn();
+const execFileMock = vi.fn();
 vi.mock("node:child_process", () => ({
-  execFile: vi.fn(),
+  execFile: (...args: unknown[]) => execFileMock(...args),
   spawn: (...args: unknown[]) => spawnMock(...args),
 }));
 
@@ -15,6 +16,25 @@ vi.mock("node:fs", () => ({
   existsSync: (p: string) => existsSyncMock(p),
 }));
 
+// Mock fs/promises
+const mkdirMock = vi.fn().mockResolvedValue(undefined);
+const writeFileMock = vi.fn().mockResolvedValue(undefined);
+const chmodMock = vi.fn().mockResolvedValue(undefined);
+const unlinkMock = vi.fn().mockResolvedValue(undefined);
+vi.mock("node:fs/promises", () => ({
+  mkdir: (...args: unknown[]) => mkdirMock(...args),
+  writeFile: (...args: unknown[]) => writeFileMock(...args),
+  chmod: (...args: unknown[]) => chmodMock(...args),
+  unlink: (...args: unknown[]) => unlinkMock(...args),
+}));
+
+// Mock os.homedir
+const homedirMock = vi.fn(() => "/home/testuser");
+vi.mock("node:os", () => ({
+  default: { homedir: () => homedirMock() },
+  homedir: () => homedirMock(),
+}));
+
 // Shared exec mock for findCloudflaredBinary
 const execMock = vi.fn();
 
@@ -70,6 +90,134 @@ describe("findCloudflaredBinary", () => {
     const result = await findCloudflaredBinary(execMock);
     expect(result).toBeNull();
   });
+
+  it("finds cloudflared in ~/.openclaw/bin", async () => {
+    const openclawBinPath = "/home/testuser/.openclaw/bin/cloudflared";
+    execMock.mockImplementation((cmd: string, _args: string[]) => {
+      if (cmd === "which") {
+        return Promise.reject(new Error("not found"));
+      }
+      return Promise.resolve({ stdout: "cloudflared version 2024.1.0\n", stderr: "" });
+    });
+    existsSyncMock.mockImplementation((p: string) => p === openclawBinPath);
+
+    const { findCloudflaredBinary } = await import("./cloudflared.js");
+    const result = await findCloudflaredBinary(execMock);
+    expect(result).toBe(openclawBinPath);
+  });
+});
+
+describe("installCloudflared", () => {
+  const originalPlatform = process.platform;
+  const originalArch = process.arch;
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.restoreAllMocks();
+    mkdirMock.mockResolvedValue(undefined);
+    writeFileMock.mockResolvedValue(undefined);
+    chmodMock.mockResolvedValue(undefined);
+    unlinkMock.mockResolvedValue(undefined);
+    homedirMock.mockReturnValue("/home/testuser");
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, "platform", { value: originalPlatform });
+    Object.defineProperty(process, "arch", { value: originalArch });
+  });
+
+  it("downloads and installs linux binary", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    Object.defineProperty(process, "arch", { value: "x64" });
+
+    const binaryData = new Uint8Array([1, 2, 3]);
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(binaryData.buffer),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { installCloudflared } = await import("./cloudflared.js");
+    const logger = { info: vi.fn() };
+    const result = await installCloudflared(logger);
+
+    expect(result).toBe("/home/testuser/.openclaw/bin/cloudflared");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64",
+      { redirect: "follow" },
+    );
+    expect(mkdirMock).toHaveBeenCalledWith("/home/testuser/.openclaw/bin", { recursive: true });
+    expect(writeFileMock).toHaveBeenCalledWith(
+      "/home/testuser/.openclaw/bin/cloudflared",
+      expect.any(Uint8Array),
+    );
+    expect(chmodMock).toHaveBeenCalledWith("/home/testuser/.openclaw/bin/cloudflared", 0o755);
+    expect(logger.info).toHaveBeenCalledTimes(2);
+
+    vi.unstubAllGlobals();
+  });
+
+  it("downloads and extracts macOS tgz", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin" });
+    Object.defineProperty(process, "arch", { value: "arm64" });
+
+    // Make execFile (used by promisify) call the callback immediately.
+    // promisify looks for the last function argument as the callback.
+    execFileMock.mockImplementation((...args: unknown[]) => {
+      const cb = args[args.length - 1];
+      if (typeof cb === "function") (cb as (err: Error | null, stdout: string, stderr: string) => void)(null, "", "");
+    });
+
+    const binaryData = new Uint8Array([1, 2, 3]);
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(binaryData.buffer),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { installCloudflared } = await import("./cloudflared.js");
+    const logger = { info: vi.fn() };
+    const result = await installCloudflared(logger);
+
+    expect(result).toBe("/home/testuser/.openclaw/bin/cloudflared");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz",
+      { redirect: "follow" },
+    );
+    // tgz should be written, tar extracted, then tgz deleted
+    expect(writeFileMock).toHaveBeenCalledWith(
+      "/home/testuser/.openclaw/bin/cloudflared.tgz",
+      expect.any(Uint8Array),
+    );
+    expect(unlinkMock).toHaveBeenCalledWith("/home/testuser/.openclaw/bin/cloudflared.tgz");
+    expect(chmodMock).toHaveBeenCalledWith("/home/testuser/.openclaw/bin/cloudflared", 0o755);
+
+    vi.unstubAllGlobals();
+  });
+
+  it("throws on unsupported platform", async () => {
+    Object.defineProperty(process, "platform", { value: "win32" });
+    Object.defineProperty(process, "arch", { value: "x64" });
+
+    const { installCloudflared } = await import("./cloudflared.js");
+    await expect(installCloudflared()).rejects.toThrow(/Unsupported platform/);
+  });
+
+  it("throws on download failure", async () => {
+    Object.defineProperty(process, "platform", { value: "linux" });
+    Object.defineProperty(process, "arch", { value: "x64" });
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { installCloudflared } = await import("./cloudflared.js");
+    await expect(installCloudflared()).rejects.toThrow(/Failed to download cloudflared: HTTP 404/);
+
+    vi.unstubAllGlobals();
+  });
 });
 
 describe("startCloudflaredTunnel", () => {

package/src/tunnel/cloudflared.ts

@@ -1,5 +1,11 @@
 import { execFile, spawn, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
+import { chmod, mkdir, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFilePromise = promisify(execFile);
 
 type ExecResult = { stdout: string; stderr: string };
 type ExecFn = (cmd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<ExecResult>;
@@ -56,6 +62,7 @@ export async function findCloudflaredBinary(
 
   // Strategy 2: Known install paths
   const knownPaths = [
+    path.join(os.homedir(), ".openclaw", "bin", "cloudflared"),
     "/usr/local/bin/cloudflared",
     "/usr/bin/cloudflared",
     "/opt/homebrew/bin/cloudflared",
@@ -69,6 +76,59 @@ export async function findCloudflaredBinary(
   return null;
 }
 
+/**
+ * Download and install the cloudflared binary from GitHub releases to ~/.openclaw/bin/.
+ */
+export async function installCloudflared(logger?: {
+  info: (msg: string) => void;
+}): Promise<string> {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const archMap: Record<string, string> = {
+    x64: "amd64",
+    arm64: "arm64",
+    arm: "arm",
+    ia32: "386",
+  };
+  const cfArch = archMap[arch];
+  if (!cfArch) throw new Error(`Unsupported architecture: ${arch}`);
+
+  let filename: string;
+  if (platform === "linux") {
+    filename = `cloudflared-linux-${cfArch}`;
+  } else if (platform === "darwin") {
+    filename = `cloudflared-darwin-${cfArch}.tgz`;
+  } else {
+    throw new Error(`Unsupported platform for auto-install: ${platform}`);
+  }
+
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${filename}`;
+
+  const installDir = path.join(os.homedir(), ".openclaw", "bin");
+  await mkdir(installDir, { recursive: true });
+  const installPath = path.join(installDir, "cloudflared");
+
+  logger?.info(`cloudflared not found, downloading from ${url}...`);
+
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`Failed to download cloudflared: HTTP ${res.status}`);
+  const data = new Uint8Array(await res.arrayBuffer());
+
+  if (platform === "darwin") {
+    const tgzPath = installPath + ".tgz";
+    await writeFile(tgzPath, data);
+    await execFilePromise("tar", ["-xzf", tgzPath, "-C", installDir]);
+    await unlink(tgzPath);
+  } else {
+    await writeFile(installPath, data);
+  }
+
+  await chmod(installPath, 0o755);
+  logger?.info(`cloudflared installed to ${installPath}`);
+  return installPath;
+}
+
 let cachedCloudflaredBinary: string | null = null;
 
 export async function getCloudflaredBinary(exec: ExecFn = defaultExec): Promise<string> {
@@ -102,9 +162,13 @@ export async function startCloudflaredTunnel(opts: {
   token: string;
   timeoutMs?: number;
   exec?: ExecFn;
+  logger?: { info: (msg: string) => void };
 }): Promise<CloudflaredTunnel> {
   const exec = opts.exec ?? defaultExec;
-  const bin = await getCloudflaredBinary(exec);
+  let bin = await findCloudflaredBinary(exec);
+  if (!bin) {
+    bin = await installCloudflared(opts.logger);
+  }
   const timeoutMs = opts.timeoutMs ?? 30_000;
   const stderr: string[] = [];
 

package/src/tunnel/exposure.test.ts

@@ -86,6 +86,7 @@ describe("startGatewayCloudflareExposure", () => {
     expect(startCloudflaredTunnelMock).toHaveBeenCalledWith({
       token: "test-token",
       timeoutMs: 30_000,
+      logger: log,
     });
     expect(log.info).toHaveBeenCalledWith(
       expect.stringContaining("connectorId=abc-123"),

package/src/tunnel/exposure.ts

@@ -30,6 +30,7 @@ export async function startGatewayCloudflareExposure(params: {
     const tunnel = await startCloudflaredTunnel({
       token: params.tunnelToken,
       timeoutMs: 30_000,
+      logger: params.logCloudflare,
     });
     params.logCloudflare.info(
       `managed tunnel running (connectorId=${tunnel.connectorId ?? "unknown"}, pid=${tunnel.pid ?? "unknown"})`,