openclaw-cloudflare 0.1.0 → 0.3.0

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

@@ -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`
+
+### Step 3 — Configure the plugin
 
-Add to your `openclaw.json`:
+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,112 +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:**
-- `cloudflared` binary installed and in PATH (or at a known location)
-- A pre-configured tunnel token from the Cloudflare Zero Trust dashboard
+## Running cloudflared on your VM
 
-**Setup:**
+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.
 
-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 — Create a tunnel in the Cloudflare dashboard
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "cloudflare": {
-        "config": {
-          "tunnel": {
-            "mode": "managed",
-            "tunnelToken": "eyJhIjoiYWNj...",
-            "teamDomain": "myteam"
-          }
-        }
-      }
-    }
-  }
-}
+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
+
+### 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
 ```
 
-Or via environment variable:
+**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
+```
 
+**ARM64:**
 ```bash
-export OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN="eyJhIjoiYWNj..."
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64 -o cloudflared
+sudo install -m 755 cloudflared /usr/local/bin/cloudflared
 ```
 
-### `access-only`
+**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
+sudo cloudflared service install <your-tunnel-token>
+```
+
+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

@@ -4,16 +4,10 @@
     "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.1.0",
+  "version": "0.3.0",
   "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,8 +42,13 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/G4brym/openclaw-plugin-cloudflare.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,16 +1,11 @@
 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 {
@@ -20,88 +15,39 @@ export default {
   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-plugin-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