@ystemsrx/cfshare 0.1.0

package/index.ts

@@ -0,0 +1,15 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { registerCfshareTools } from "./src/tools.js";
+
+const plugin = {
+  id: "cfshare",
+  name: "CFShare",
+  description: "Cloudflare Quick Tunnel wrapper for secure temporary sharing",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    registerCfshareTools(api);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,65 @@
+{
+  "id": "cfshare",
+  "name": "CFShare",
+  "description": "Secure Cloudflare Quick Tunnel wrapper for temporary port and file exposure",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "stateDir": { "type": "string" },
+      "cloudflaredPath": { "type": "string" },
+      "policyFile": { "type": "string" },
+      "ignoreFile": { "type": "string" },
+      "defaultTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
+      "maxTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 604800 },
+      "defaultExposePortAccess": { "type": "string", "enum": ["token", "basic", "none"] },
+      "defaultExposeFilesAccess": { "type": "string", "enum": ["token", "basic", "none"] },
+      "blockedPorts": {
+        "type": "array",
+        "items": { "type": "integer", "minimum": 1, "maximum": 65535 }
+      },
+      "allowedPathRoots": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "tunnel": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "edgeIpVersion": { "type": "string", "enum": ["4", "6", "auto"] },
+          "protocol": { "type": "string", "enum": ["http2", "quic", "auto"] }
+        }
+      },
+      "rateLimit": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "windowMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 },
+          "maxRequests": { "type": "integer", "minimum": 1, "maximum": 100000 }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "cloudflaredPath": {
+      "label": "cloudflared Path",
+      "placeholder": "cloudflared",
+      "help": "Binary name or absolute path"
+    },
+    "stateDir": {
+      "label": "State Directory",
+      "placeholder": "~/.openclaw/cfshare",
+      "advanced": true
+    },
+    "defaultTtlSeconds": {
+      "label": "Default TTL (seconds)",
+      "help": "Default expiration for new exposures"
+    },
+    "maxTtlSeconds": {
+      "label": "Max TTL (seconds)",
+      "help": "Upper TTL limit enforced by policy"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ystemsrx/cfshare",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw plugin to safely expose local ports/files via Cloudflare Quick Tunnel",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "skills",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "cloudflared",
+    "cloudflare",
+    "tunnel",
+    "file-share"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@ystemsrx/cfshare",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "ignore": "^7.0.5",
+    "mime-types": "^3.0.1",
+    "yazl": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/skills/cfshare/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: cfshare
+description: Expose local services, ports, files, or directories as temporary public HTTPS links via Cloudflare Quick Tunnel. Use for sharing local services, sending downloadable files, previewing content, etc.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "☁️",
+        "skillKey": "cfshare",
+        "requires":
+          {
+            "bins": ["cloudflared"],
+            "config": ["plugins.entries.cfshare.enabled"],
+          },
+      },
+  }
+---
+
+# CFShare — Cloudflare Quick Tunnel Exposure
+
+Expose local services, ports, files, or directories as temporary public `https://*.trycloudflare.com` links.
+
+---
+
+## Standard Workflow
+
+1. **`env_check()`** — Always call first to verify `cloudflared` is available and see current policy defaults.
+2. **Create exposure:**
+   - Have a running local service? → `expose_port(port, opts?)`
+   - Need to share/preview files or directories? → `expose_files(paths, opts?)`
+3. **After creation succeeds:** Present `public_url` and `expires_at` to the user. Remind them to call `exposure_stop` when finished.
+4. **Inspect / monitor:** `exposure_get(id)` with optional `probe_public: true` to verify end-to-end reachability.
+5. **Troubleshoot:** `exposure_logs(id)` when something goes wrong.
+6. **Cleanup:** `exposure_stop(id)` or `exposure_stop(id="all")`.
+
+---
+
+## Tool Reference
+
+### 1. `env_check`
+
+Check that `cloudflared` is installed, resolve its version, and return effective policy defaults.
+
+---
+
+### 2. `expose_port`
+
+Expose an already-running local service via Cloudflare Quick Tunnel. The tool probes `127.0.0.1:<port>` before proceeding and rejects blocked ports.
+
+**Errors:** `"invalid port"`, `"port blocked by policy: <N>"`, `"local service is not reachable on 127.0.0.1:<N>"`.
+
+---
+
+### 3. `expose_files`
+
+Copy files/directories into a temporary workspace, start a read-only static file server, and tunnel it publicly.
+
+**File Serving Behavior**
+
+Mode: normal
+
+- Single file → served directly at the root URL.
+- Multiple files or a directory → displayed in an intuitive file explorer interface.
+
+Mode: zip
+
+- All files are packaged into a ZIP archive.
+
+**Presentation**
+
+- Default behaviors: download | preview | raw
+- Behavior can be overridden via query parameters.
+  - download → forces browser file save.
+  - preview → renders inline (images, PDF, Markdown, audio/video, HTML, text, etc.).
+  - raw → serves original content without any wrapper.
+- If a file type is not previewable, preview automatically falls back to raw, then to download.
+
+---
+
+### 4. `exposure_list`
+
+List all tracked sessions (both active and recently-stopped within-process).
+
+---
+
+### 5. `exposure_get`
+
+Get detailed information about one or more sessions. Supports three selection modes (mutually exclusive input shapes via union schema):
+
+---
+
+### 6. `exposure_stop`
+
+Stop one, several, or all exposures. Terminates cloudflared process, shuts down origin/proxy servers, and deletes temporary workspace files.
+
+---
+
+### 7. `exposure_logs`
+
+Fetch merged logs from cloudflared tunnel and origin server components.
+
+---
+
+### 8. `maintenance`
+
+Lifecycle management operations.
+
+**Action details:**
+
+- **`start_guard`** — Start the TTL expiration reaper (runs periodically; usually auto-started).
+- **`run_gc`** — Clean up orphaned workspace directories and stale processes not tracked by any active session.
+- **`set_policy`** — Persist a policy change to disk and reload. Requires at least one of `opts.policy` or `opts.ignore_patterns`.
+
+---
+
+### 9. `audit_query`
+
+Search audit event log.
+
+---
+
+### 10. `audit_export`
+
+Export filtered audit events to a local JSONL file.
+
+---
+
+## Security & Policy Defaults
+
+Policy priority (highest wins): **policy JSON file** > **plugin config** > **built-in defaults**.
+
+---
+
+## Response Behavior Rules
+
+When presenting results to the user, the LLM **must**:
+
+1. **Always display `public_url` and `expires_at`** after creating an exposure.
+2. **Present timestamps** in the user’s local time zone using a human-readable format (`yyyy-mm-dd HH:MM:SS`). Never include timezone indicators or raw ISO strings.
+3. **Warn** when `access` mode is `"none"` — the link is publicly accessible without authentication.
+4. **Include cleanup instructions** — include `exposure_stop` guidance after successful sharing.
+5. **On error**, suggest `exposure_logs(id)` for diagnostics.
+6. **For security** — if user intent is ambiguous or potentially sensitive, request confirmation before creating exposure.