openclaw-cloudflare 0.1.0

package/.changeset/README.md

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

@@ -0,0 +1,11 @@
+{
+  "$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

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

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

@@ -0,0 +1,39 @@
+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/README.md

@@ -0,0 +1,142 @@
+# 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.).
+
+## Installation
+
+```bash
+openclaw plugins install openclaw-cloudflare
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cloudflare": {
+        "config": {
+          "tunnel": {
+            "mode": "managed",
+            "tunnelToken": "your-tunnel-token",
+            "teamDomain": "myteam",
+            "audience": "optional-aud-tag"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Modes
+
+### `off` (default)
+
+Cloudflare integration is disabled.
+
+### `managed`
+
+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
+
+**Setup:**
+
+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:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cloudflare": {
+        "config": {
+          "tunnel": {
+            "mode": "managed",
+            "tunnelToken": "eyJhIjoiYWNj...",
+            "teamDomain": "myteam"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Or via environment variable:
+
+```bash
+export OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN="eyJhIjoiYWNj..."
+```
+
+### `access-only`
+
+Use when `cloudflared` is managed externally (e.g., Docker sidecar, systemd service). The plugin only handles Cloudflare Access JWT verification.
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "cloudflare": {
+        "config": {
+          "tunnel": {
+            "mode": "access-only",
+            "teamDomain": "myteam",
+            "audience": "aud-tag-from-access-app"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Docker Compose example** (external cloudflared):
+
+```yaml
+services:
+  openclaw:
+    image: openclaw:latest
+    # ...
+
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    command: tunnel run
+    environment:
+      TUNNEL_TOKEN: "eyJhIjoiYWNj..."
+```
+
+## Authentication
+
+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
+
+Supported algorithms: RS256, ES256 (via Node.js WebCrypto).
+
+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 |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENCLAW_CLOUDFLARE_TUNNEL_TOKEN` | Tunnel token (alternative to config) |
+| `OPENCLAW_TEST_CLOUDFLARED_BINARY` | Override cloudflared binary path (testing) |

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "openclaw-cloudflare",
+  "version": "0.1.0",
+  "description": "Cloudflare integration plugin for OpenClaw (Tunnel, Access, and more)",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "openclaw": {
+    "extensions": ["./src/index.ts"],
+    "install": {
+      "npmSpec": "openclaw-cloudflare",
+      "defaultChoice": "npm"
+    }
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "cloudflare",
+    "cloudflare-tunnel",
+    "cloudflare-access",
+    "zero-trust"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/G4brym/openclaw-plugin-cloudflare.git"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "license": "MIT"
+}