openclaw-cloudflare 0.2.1 → 0.3.1

package/README.md

@@ -1,28 +1,37 @@
 # openclaw-cloudflare
 
-Cloudflare integration plugin for [OpenClaw](https://github.com/openclaw/openclaw). Provides Cloudflare Tunnel and Access support, with room for future Cloudflare features (Workers, R2, KV, etc.).
+Cloudflare Access JWT verification plugin for [OpenClaw](https://github.com/openclaw/openclaw). Verifies `Cf-Access-Jwt-Assertion` headers and sets identity headers for authenticated requests.
 
-## Installation
+Assumes `cloudflared` is already running externally (Docker sidecar, systemd, Cloudflare's own connector, etc.).
+
+## Setup Guide
+
+### Step 1 — Install the plugin
 
 ```bash
 openclaw plugins install openclaw-cloudflare
 ```
 
-## Configuration
+### Step 2 — Set up Cloudflare Access
+
+1. In the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com/) → **Access > Applications** → **Add an application**
+2. Choose **Self-hosted**
+3. Set the **Application domain** to the hostname pointing at your OpenClaw gateway (e.g. `openclaw.example.com`)
+4. Configure the identity providers and policies (who is allowed to access)
+5. Note your **Team domain** — visible at **Settings > Custom Pages** or in the URL: `https://<team>.cloudflareaccess.com`
 
-Add to your `openclaw.json`:
+### Step 3 — Configure the plugin
+
+Add to your `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "plugins": {
     "entries": {
-      "cloudflare": {
+      "openclaw-cloudflare": {
         "config": {
-          "tunnel": {
-            "mode": "managed",
-            "tunnelToken": "your-tunnel-token",
-            "teamDomain": "myteam",
-            "audience": "optional-aud-tag"
+          "access": {
+            "teamDomain": "myteam"
           }
         }
       }
@@ -31,113 +40,126 @@ Add to your `openclaw.json`:
 }
 ```
 
-## Modes
 
-### `off` (default)
+### Step 4 — Start OpenClaw
 
-Cloudflare integration is disabled.
+```bash
+openclaw gateway --force
+```
 
-### `managed`
+The plugin will verify Cloudflare Access JWTs on every incoming request and set `x-openclaw-user-email` for authenticated users.
 
-OpenClaw spawns and manages a `cloudflared` tunnel process automatically.
+---
 
-**Requirements:**
-- A pre-configured tunnel token from the Cloudflare Zero Trust dashboard
+## Running cloudflared on your VM
 
-> **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.
+This plugin only handles JWT verification — you need `cloudflared` running on the VM to route traffic through Cloudflare. Here's how to set it up as a persistent system service so it starts automatically.
 
-**Setup:**
+### 1 — Create a tunnel in the Cloudflare dashboard
 
-1. In the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com/), create a tunnel under **Networks > Tunnels**
-2. Add a public hostname pointing to your OpenClaw gateway (e.g., `openclaw.example.com` → `http://localhost:3000`)
-3. Create an Access Application under **Access > Applications** for the hostname
-4. Copy the tunnel token and configure it:
+1. Go to [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) → **Networks > Tunnels** → **Create a tunnel**
+2. Choose **Cloudflared**, name it (e.g. `my-openclaw`), click **Save tunnel**
+3. Under **Public Hostnames**, add a hostname pointing to your OpenClaw gateway:
+   - Subdomain + domain: e.g. `openclaw.example.com`
+   - Service: `HTTP` → `localhost:18789` (OpenClaw's default port)
+4. Copy the **tunnel token** shown on the connector install page
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "cloudflare": {
-        "config": {
-          "tunnel": {
-            "mode": "managed",
-            "tunnelToken": "eyJhIjoiYWNj...",
-            "teamDomain": "myteam"
-          }
-        }
-      }
-    }
-  }
-}
+### 2 — Install cloudflared
+
+**Debian/Ubuntu:**
+```bash
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
+sudo dpkg -i cloudflared.deb
+```
+
+**RHEL/Fedora:**
+```bash
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-x86_64.rpm -o cloudflared.rpm
+sudo rpm -i cloudflared.rpm
 ```
 
-Or via environment variable:
+**ARM64:**
+```bash
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64 -o cloudflared
+sudo install -m 755 cloudflared /usr/local/bin/cloudflared
+```
+
+**macOS:**
+```bash
+brew install cloudflare/cloudflare/cloudflared
+```
+
+### 3 — Install as a system service
+
+**Linux:**
+```bash
+sudo cloudflared service install <your-tunnel-token>
+sudo systemctl enable cloudflared
+sudo systemctl start cloudflared
+```
+
+Verify it's running:
+```bash
+sudo systemctl status cloudflared
+```
 
+**macOS:**
 ```bash
-export OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN="eyJhIjoiYWNj..."
+sudo cloudflared service install <your-tunnel-token>
 ```
 
-### `access-only`
+This registers a launchd plist that starts cloudflared automatically on boot.
 
-Use when `cloudflared` is managed externally (e.g., Docker sidecar, systemd service). The plugin only handles Cloudflare Access JWT verification.
+Once the tunnel is active, all traffic arriving at your public hostname passes through Cloudflare Access — and this plugin verifies the resulting JWTs on each request.
+
+---
+
+## OpenClaw gateway configuration
+
+With `cloudflared` running on the same machine, the gateway only needs to be reachable on loopback. Configure `~/.openclaw/openclaw.json` to bind locally, trust the local proxy, and delegate authentication to the identity headers this plugin sets:
 
 ```json
 {
-  "plugins": {
-    "entries": {
-      "cloudflare": {
-        "config": {
-          "tunnel": {
-            "mode": "access-only",
-            "teamDomain": "myteam",
-            "audience": "aud-tag-from-access-app"
-          }
-        }
+  "gateway": {
+    "bind": "loopback",
+    "trustedProxies": ["127.0.0.1"],
+    "auth": {
+      "mode": "trusted-proxy",
+      "trustedProxy": {
+        "userHeader": "x-openclaw-user-email"
       }
     }
   }
 }
 ```
 
-**Docker Compose example** (external cloudflared):
-
-```yaml
-services:
-  openclaw:
-    image: openclaw:latest
-    # ...
+| Field | Value | Why |
+|-------|-------|-----|
+| `gateway.bind` | `"loopback"` | cloudflared connects to OpenClaw locally — no need to expose to LAN |
+| `gateway.trustedProxies` | `["127.0.0.1"]` | Only trust identity headers from cloudflared running on the same host |
+| `gateway.auth.mode` | `"trusted-proxy"` | Delegate authentication to this plugin instead of using a password/token |
+| `gateway.auth.trustedProxy.userHeader` | `"x-openclaw-user-email"` | This plugin sets this header after verifying the Cloudflare Access JWT |
 
-  cloudflared:
-    image: cloudflare/cloudflared:latest
-    command: tunnel run
-    environment:
-      TUNNEL_TOKEN: "eyJhIjoiYWNj..."
-```
+---
 
-## Authentication
+## How it works
 
 When a request arrives with a `Cf-Access-Jwt-Assertion` header, the plugin:
 
 1. Verifies the JWT signature against Cloudflare's JWKS endpoint (`https://<teamDomain>.cloudflareaccess.com/cdn-cgi/access/certs`)
-2. Validates issuer, expiry, and audience (if configured)
-3. Sets `x-openclaw-user-email` and `x-openclaw-auth-source` headers for downstream auth
+2. Validates issuer, expiry, and audience (if `audience` is configured)
+3. Sets `x-openclaw-user-email` and `x-openclaw-auth-source: cloudflare-access` headers for downstream use
 
-Supported algorithms: RS256, ES256 (via Node.js WebCrypto).
+Identity headers are always stripped from incoming requests before verification to prevent spoofing.
 
-JWKS keys are cached for 10 minutes with automatic refresh on key rotation.
+Supported algorithms: RS256, ES256 (via Node.js WebCrypto, no external deps). JWKS keys are cached for 10 minutes with automatic refresh on key rotation.
 
-## Configuration Reference
+---
 
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `tunnel.mode` | `"off" \| "managed" \| "access-only"` | `"off"` | Operation mode |
-| `tunnel.tunnelToken` | `string` | — | Tunnel token (managed mode) |
-| `tunnel.teamDomain` | `string` | — | Team domain for `<team>.cloudflareaccess.com` |
-| `tunnel.audience` | `string` | — | Optional AUD tag for stricter JWT validation |
+## Configuration Reference
 
-## Environment Variables
+| Key | Type | Description |
+|-----|------|-------------|
+| `access.teamDomain` | `string` | Team domain for `<team>.cloudflareaccess.com` (required to enable) |
+| `access.audience` | `string` | Optional AUD tag for stricter JWT validation |
 
-| Variable | Description |
-|----------|-------------|
-| `OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN` | Tunnel token (alternative to config) |
-| `OPENCLAW_TEST_CLOUDFLARED_BINARY` | Override cloudflared binary path (testing) |

package/openclaw.plugin.json

@@ -1,19 +1,13 @@
 {
-  "id": "cloudflare",
+  "id": "openclaw-cloudflare",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "tunnel": {
+      "access": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "mode": {
-            "type": "string",
-            "enum": ["off", "managed", "access-only"],
-            "default": "off"
-          },
-          "tunnelToken": { "type": "string" },
           "teamDomain": { "type": "string" },
           "audience": { "type": "string" }
         }
@@ -21,17 +15,12 @@
     }
   },
   "uiHints": {
-    "tunnel.tunnelToken": {
-      "label": "Tunnel Token",
-      "sensitive": true,
-      "help": "Token from Cloudflare Zero Trust dashboard (managed mode)"
-    },
-    "tunnel.teamDomain": {
+    "access.teamDomain": {
       "label": "Team Domain",
       "placeholder": "myteam",
       "help": "Team domain for myteam.cloudflareaccess.com"
     },
-    "tunnel.audience": {
+    "access.audience": {
       "label": "Application Audience (AUD)",
       "help": "Optional AUD tag for stricter JWT validation",
       "advanced": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-cloudflare",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Cloudflare integration plugin for OpenClaw (Tunnel, Access, and more)",
   "type": "module",
   "exports": {
@@ -44,6 +44,11 @@
     "type": "git",
     "url": "git+https://github.com/G4brym/openclaw-cloudflare.git"
   },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "openclaw.plugin.json"
+  ],
   "publishConfig": {
     "provenance": true,
     "access": "public"

package/src/index.ts

@@ -1,107 +1,53 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { createCloudflareAccessVerifier, type CloudflareAccessVerifier } from "./tunnel/access.js";
-import { startGatewayCloudflareExposure } from "./tunnel/exposure.js";
-
-type TunnelConfig = {
-  mode?: "off" | "managed" | "access-only";
-  tunnelToken?: string;
-  teamDomain?: string;
-  audience?: string;
-};
+import { createCloudflareAccessVerifier } from "./tunnel/access.js";
 
 type PluginConfig = {
-  tunnel?: TunnelConfig;
+  access?: {
+    teamDomain?: string;
+    audience?: string;
+  };
 };
 
 export default {
-  id: "cloudflare",
+  id: "openclaw-cloudflare",
   name: "Cloudflare",
 
   register(api: {
     pluginConfig?: PluginConfig;
     logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
-    registerService(service: { id: string; start: () => Promise<void>; stop: () => Promise<void> }): void;
     registerHttpHandler(handler: (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean): void;
   }) {
-    const config = api.pluginConfig?.tunnel;
-    const mode = config?.mode ?? "off";
-    if (mode === "off") return;
-
-    const tunnelToken =
-      config?.tunnelToken ?? process.env.OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN;
+    const config = api.pluginConfig?.access;
     const teamDomain = config?.teamDomain;
 
-    // Validate config
-    if (mode === "managed" && !tunnelToken) {
-      api.logger.error(
-        "[cloudflare] managed mode requires tunnelToken config or OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN env var",
-      );
+    if (!teamDomain) {
+      api.logger.warn("[cloudflare] no teamDomain configured — plugin disabled");
       return;
     }
-    if (teamDomain === undefined) {
-      api.logger.warn(
-        "[cloudflare] no teamDomain configured — JWT verification will be skipped",
-      );
-    }
 
-    let verifier: CloudflareAccessVerifier | null = null;
-    let stopTunnel: (() => Promise<void>) | null = null;
-
-    // Register background service for tunnel lifecycle
-    api.registerService({
-      id: "cloudflare-tunnel",
-      async start() {
-        // Create JWT verifier if teamDomain is set
-        if (teamDomain) {
-          verifier = createCloudflareAccessVerifier({
-            teamDomain,
-            audience: config?.audience,
-          });
-          api.logger.info(
-            `[cloudflare] Access JWT verifier active for ${teamDomain}.cloudflareaccess.com`,
-          );
-        }
-
-        // Start tunnel exposure (managed mode)
-        stopTunnel = await startGatewayCloudflareExposure({
-          cloudflareMode: mode,
-          tunnelToken,
-          logCloudflare: {
-            info: (msg) => api.logger.info(`[cloudflare] ${msg}`),
-            warn: (msg) => api.logger.warn(`[cloudflare] ${msg}`),
-            error: (msg) => api.logger.error(`[cloudflare] ${msg}`),
-          },
-        });
-      },
-      async stop() {
-        if (stopTunnel) {
-          await stopTunnel();
-          stopTunnel = null;
-        }
-        verifier = null;
-      },
+    const verifier = createCloudflareAccessVerifier({
+      teamDomain,
+      audience: config.audience,
     });
 
-    // Register HTTP handler for JWT auth
+    api.logger.info(`[cloudflare] Access JWT verifier active for ${teamDomain}.cloudflareaccess.com`);
+
     api.registerHttpHandler(async (req: IncomingMessage, _res: ServerResponse) => {
       // Always strip identity headers to prevent spoofing from untrusted clients
       delete req.headers["x-openclaw-user-email"];
       delete req.headers["x-openclaw-auth-source"];
 
-      if (!verifier) return false;
-
       const jwtHeader = req.headers["cf-access-jwt-assertion"];
       const token = Array.isArray(jwtHeader) ? jwtHeader[0] : jwtHeader;
       if (!token) return false;
 
       const user = await verifier.verify(token);
       if (user) {
-        // Set identity headers for gateway auth flow
         req.headers["x-openclaw-user-email"] = user.email;
         req.headers["x-openclaw-auth-source"] = "cloudflare-access";
       }
 
-      return false; // don't consume the request
+      return false;
     });
   },
 };

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-  "changelog": ["@changesets/changelog-github", { "repo": "G4brym/openclaw-cloudflare" }],
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.github/workflows/changeset-check.yml

@@ -1,25 +0,0 @@
-name: Changeset Check
-
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  check:
-    name: Check for changeset
-    runs-on: ubuntu-latest
-    # Skip on the "Version Packages" PR itself — it has no changeset by design
-    if: github.head_ref != 'changeset-release/main'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - run: npm ci
-
-      - run: npx changeset status --since=origin/main

package/.github/workflows/ci.yml

@@ -1,25 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    name: Test & Typecheck
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - run: npm ci
-
-      - run: npm run typecheck
-
-      - run: npm test

package/.github/workflows/release.yml

@@ -1,39 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: npm
-          registry-url: https://registry.npmjs.org
-
-      - run: npm ci
-
-      - name: Create Release PR or Publish to npm
-        uses: changesets/action@v1
-        with:
-          publish: npm run release
-          version: npm run version
-          commit: "chore: version packages"
-          title: "chore: version packages"
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_CONFIG_PROVENANCE: true

package/CHANGELOG.md

@@ -1,17 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
-# 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
-```