squad-openclaw 2026.2.16 → 2026.2.27

package/README.md

@@ -0,0 +1,309 @@
+# squad-openclaw
+
+OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity registry, filesystem tools, SQL queries, version management, and a cloud relay client for remote browser access.
+
+## Features
+
+| Tool / Method | Description |
+|---|---|
+| `entity_list`, `entity_search`, `entity_sync` | In-memory entity registry with filesystem watching (agents, skills, plugins, tools, media) |
+| `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | Remote filesystem access for browser clients (subject to security restrictions below) |
+| `sql_query` | Restricted SQLite query tool — `sqlite3` only, scoped to `~/.openclaw/squad-ceo-data/` |
+| `squad.version.check`, `squad.version.update` | Plugin version management and self-update |
+| `squad.agents.set-identity`, `squad.agents.patch-config` | Gateway-native, surgical agent config updates (identity/tools/skills/default/model only) |
+| `tools.invoke` | RPC-based tool invocation for relay mode — **only invokes this plugin's own tools**, each with its own security restrictions (see below) |
+| Cloud relay client | Connects outbound to `relay.squad.ceo` for remote browser access. **Only activates when a claim token or room ID exists** (see Relay Security below) |
+
+## State Directory Resolution
+
+All paths in this plugin (and throughout this README) that reference `~/.openclaw` resolve via environment override when set. This supports Docker and other containerized deployments where the OpenClaw data directory may not be at the default location.
+
+Resolution priority:
+
+1. `OPENCLAW_STATE_DIR` (canonical)
+2. `OPENCLAW_DIR` (compat alias)
+3. `os.homedir() + "/.openclaw"` (default)
+
+| Environment | Typical path | How it's resolved |
+|---|---|---|
+| Standard install | `~/.openclaw` | Default — `os.homedir() + "/.openclaw"` |
+| Docker | `/data/.openclaw` | `OPENCLAW_STATE_DIR=/data/.openclaw` (or `OPENCLAW_DIR=/data/.openclaw`) |
+| Custom / NAS | `/mnt/data/.openclaw` | `OPENCLAW_STATE_DIR=/mnt/data/.openclaw` |
+
+**This variable only controls where the plugin looks for OpenClaw's own data directory.** It does not grant the plugin access to the parent directory or any other part of the filesystem. All security restrictions (blocked directories, allowed roots, write protection) are enforced relative to the resolved state directory — not the filesystem root.
+
+The resolution logic lives in a single shared module ([`src/paths.ts`](src/paths.ts)) imported by every file that needs the state directory path.
+
+### Docker Workspace Mapping
+
+If your container mounts the real workspace outside the OpenClaw state directory (for example, `/data/workspace`), create a symlink so OpenClaw-compatible tools can still resolve `.../.openclaw/workspace`:
+
+```bash
+mkdir -p /data/.openclaw /data/workspace
+ln -sfn /data/workspace /data/.openclaw/workspace
+```
+
+Then start your gateway/server with explicit env vars (useful when `.env` is not loaded):
+
+```bash
+PORT=3334 \
+OPENCLAW_STATE_DIR=/data/.openclaw \
+OPENCLAW_DIR=/data/.openclaw \
+node server.js
+```
+
+Quick verification:
+
+```bash
+ls -ld /data/.openclaw /data/.openclaw/workspace /data/workspace /data/.openclaw/openclaw.json
+```
+
+## Security Model
+
+This plugin enforces a **defense-in-depth** security model with four independent layers. All security rules are hard-coded and non-configurable (except `allowedRoots`) so they can be verified by reading the source code. The bundle is intentionally **not minified** to allow security auditing of the distributed code.
+
+> **Note:** Throughout this section, `~/.openclaw` refers to the resolved state directory (see above). In Docker or custom installs, substitute the actual path set by `OPENCLAW_STATE_DIR`.
+
+### Layer 1: Blocked Directories (hardcoded, non-configurable)
+
+These directories are **completely blocked** from all filesystem operations (read, write, list, delete, rename):
+
+| Path | Contents |
+|---|---|
+| `~/.openclaw/credentials/` | OAuth tokens, API keys |
+| `~/.openclaw/devices/` | Device pairing secrets, private keys |
+| `~/.openclaw/identity/` | Operator identity material |
+
+### Layer 1b: Blocked Files (hardcoded, non-configurable)
+
+| Path | Reason |
+|---|---|
+| `~/.openclaw/squad-ceo-data/relay/squad-relay.json` | Contains ed25519 private key for relay device identity |
+| `~/.openclaw/*.bak` | Backup files at the top level contain unredacted config (tokens, keys) that would bypass redaction |
+
+### Layer 2: Redacted Files (hardcoded, non-configurable)
+
+`~/.openclaw/openclaw.json` is **readable** but with sensitive fields replaced with `"[REDACTED]"` before returning to clients:
+
+- `channels.*.botToken` — channel bot tokens
+- `gateway.auth.*` — all auth keys
+- `gateway.token` — legacy token location
+- `gateway.remote.token` — legacy remote token
+
+### Layer 3: Allowed Roots (configurable, defaults to `~/.openclaw`)
+
+Filesystem operations are restricted to configured root directories. By default, only `~/.openclaw/` is accessible — covering all application needs:
+
+- `~/.openclaw/squad-ceo-data/` — entity databases, data files
+- `~/.openclaw/media/` — asset uploads
+- `~/.openclaw/workspace*/` — agent workspaces
+- `~/.openclaw/skills/` — skill definitions
+- `~/.openclaw/extensions/` — plugin manifests
+
+Operators can customize via the `fs.allowedRoots` config option.
+
+### Layer 4: Filesystem Write Protection + Surgical Gateway Mutations
+
+These files/directories cannot be written via filesystem tools (`fs_write`, `fs_rename`, etc.), even if they fall within `allowedRoots`:
+
+- `~/.openclaw/openclaw.json` — operator configuration (tool-level read-only with redaction)
+- `~/.openclaw/squad-ceo-data/relay/squad-relay.json` — relay device private key
+- All blocked directories above (credentials, devices, identity)
+- All `.bak` files at `~/.openclaw/` top level
+
+For agent editing UX, this plugin also exposes **whitelisted gateway RPC mutators** that call `config.get` + `config.patch` inside the gateway process (single-writer path):
+
+- `squad.agents.set-identity` — writes only `agents.list[].identity.{name,emoji,theme}`
+- `squad.agents.patch-config` — writes only `agents.list[].{tools,skills,default,model}`
+
+These methods do **not** permit arbitrary file writes and do not expose credentials. They are intentionally narrow so the UI can update agent metadata safely without direct `openclaw.json` filesystem writes.
+
+### Startup Config Migration (one-time, localized)
+
+On plugin startup, Squad runs an internal migration harness. Current migration behavior:
+
+- Checks `~/.openclaw/squad-ceo-data/migrations.json` for completed migration IDs.
+- If `001-enable-main-subagent-access` is not recorded, applies a **localized** `config.patch` that sets only:
+  - `agents.defaults.maxConcurrent = 4`
+  - `agents.defaults.subagents.maxConcurrent = 8`
+  - `agents.list[id=main].identity.name = "Pepper"`
+  - `agents.list[id=main].tools.allow = ["*"]`
+  - `agents.list[id=main].subagents.allowAgents = ["*"]`
+- Records completion in `~/.openclaw/squad-ceo-data/migrations.json`.
+
+This migration is designed to run once. If an operator later changes these values manually, the plugin does not overwrite them again because the migration is already marked complete.
+
+## Relay Security
+
+The cloud relay enables remote browser access to the gateway through `relay.squad.ceo`. This section explains the full architecture for security reviewers.
+
+### When Does the Relay Activate?
+
+The relay client **only activates** when the relay state file (`~/.openclaw/squad-ceo-data/relay/squad-relay.json`) contains a `claimToken` or `roomId`. This file does not exist by default — it is created when the user runs the onboarding prompt from the Squad web app:
+
+```bash
+mkdir -p ~/.openclaw/squad-ceo-data/relay && \
+echo '{"claimToken":"<token>"}' > ~/.openclaw/squad-ceo-data/relay/squad-relay.json
+```
+
+**If this file does not exist or contains neither key, no relay code runs, no WebSocket is opened, and no connection is made to any external server.** The plugin's entry point (`index.ts`) checks this before calling `startRelayClient()`.
+
+The claim token is a short-lived, single-use code generated by the relay server for the authenticated user. It links this gateway to the user's Squad account. Once consumed, the relay returns a `roomId` for future reconnections, and the claim token is no longer needed.
+
+For local testing, the relay endpoint can be overridden with environment variables:
+
+- `OPENCLAW_SQUAD_RELAY_URL` (preferred)
+- `SQUAD_RELAY_URL` (fallback)
+
+If neither is set, the plugin uses the production default `wss://relay.squad.ceo`.
+
+### How the Relay Connection Works
+
+```
+┌──────────────┐        JWT auth         ┌──────────────────┐       outbound WS        ┌────────────────┐
+│  Browser SPA │ ◄──────────────────────► │  relay.squad.ceo │ ◄────────────────────────► │  relay-client  │
+│ (squad.ceo)  │   (wss://.../user)       │  (CF Worker + DO)│   (wss://.../gw)          │  (this plugin) │
+└──────────────┘                          └──────────────────┘                           └───────┬────────┘
+                                                                                                │
+                                                                              per-user local WS │
+                                                                              (ws://127.0.0.1:  │
+                                                                                      18789)    │
+                                                                                                ▼
+                                                                                     ┌──────────────────┐
+                                                                                     │ OpenClaw Gateway  │
+                                                                                     │  (localhost only) │
+                                                                                     └──────────────────┘
+```
+
+1. **Browser → Relay:** The user authenticates with JWT (email/password or Google OAuth). The browser connects via WebSocket to the relay.
+2. **Relay-client → Relay:** The plugin opens an outbound WebSocket to `relay.squad.ceo` using the claim token (first connect) or stored room ID (reconnect). This is the **only** outbound connection the plugin makes.
+3. **Relay-client → Gateway:** For each browser user, the relay-client opens a **separate local WebSocket** to `ws://127.0.0.1:18789` (the gateway's loopback port). Each user gets an isolated session — the gateway sees them as individual clients.
+
+### What Data Crosses the Network (relay.squad.ceo)
+
+The relay server is a message router. Here is exactly what it sees and does not see:
+
+| Data | Crosses relay? | Notes |
+|---|---|---|
+| Relay protocol envelopes (`relay.forward`, `relay.hello`, etc.) | **Yes** | Routing metadata only |
+| User ID (for message routing) | **Yes** | The relay routes by userId |
+| Gateway device ID and public key | **Yes** | Sent in `relay.hello` for identification |
+| Inner messages (gateway ↔ browser) | **Yes, but opaque** | Wrapped inside `relay.forward` envelopes |
+| **Operator auth token** | **NEVER** | Injected into the local WS connect request **after** the relay boundary (see below) |
+| **Device identity signature** | **NEVER** | Added to the local WS connect handshake only |
+| **Gateway connect handshake params** | **NEVER** | The `connect` request with auth + device identity is sent to `localhost:18789`, not the relay |
+| **Plaintext RPC payloads** (when E2E active) | **NEVER** | E2E encrypts before relay; relay sees ciphertext only |
+
+### Operator Token — Never Leaves the Server
+
+The operator token (`gateway.auth.token` in `~/.openclaw/openclaw.json`) is the most sensitive credential. Here is exactly how it flows:
+
+1. **Read:** The relay-client reads the token from `~/.openclaw/openclaw.json` via `fs.readFileSync` at startup. This is equivalent to the gateway reading its own config — the plugin runs in the gateway's process.
+
+2. **Stored:** The token is held in memory (`this.config.operatorToken`) for the lifetime of the relay-client. It is **never written** to any file, log, or external service.
+
+3. **Used:** When a browser user's `connect` request arrives from the relay, the relay-client **injects** the operator token into the request **in memory**, then sends the modified request to `ws://127.0.0.1:18789` (localhost only). The relay server never sees this injection — it only sees the outer `relay.forward` envelope.
+
+4. **Protected via filesystem API:** The token is redacted from `~/.openclaw/openclaw.json` when read through this plugin's `fs_read` tool (`gateway.auth.*` → `"[REDACTED]"`). Remote clients (browser, agents) cannot read the token through any tool this plugin provides.
+
+```
+Browser ──[connect request]──► relay.squad.ceo ──[relay.forward]──► relay-client
+                                                                        │
+                               Token is injected HERE, in memory,       │
+                               into the connect request.                │
+                                                                        ▼
+                               relay-client ──[modified request]──► localhost:18789 (gateway)
+```
+
+**A compromised relay server cannot intercept the operator token** because the token is injected after the relay boundary — it only exists on the `localhost:18789` path between the relay-client and the gateway, both running on the same machine.
+
+### Device Identity and Auto-Pairing
+
+The relay-client generates an ed25519 keypair on first run (`device-keys.ts`). The device identity is used to sign the `connect` handshake to the local gateway using the v2 signature protocol:
+
+- **Signature payload:** `v2|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce` (pipe-delimited)
+- **deviceId:** SHA-256 fingerprint of the ed25519 public key (hex, 64 chars)
+- **publicKey:** base64url-encoded ed25519 public key (no padding)
+
+The gateway **auto-pairs** devices that connect with a valid operator token and a correctly signed device identity. No manual `openclaw devices approve` step is required. The authorization chain is:
+
+1. The **user** authenticates with the Squad web app (JWT via email/password or Google OAuth)
+2. The user generates a **claim token** (short-lived, single-use) and gives it to the gateway via the onboarding prompt
+3. The plugin starts the relay-client, which connects to the relay with the claim token
+4. When a browser user connects, the relay-client signs the connect handshake with its device key and the operator token
+5. The gateway validates the signature and auto-pairs the device
+
+The claim token is the user's explicit consent to link their gateway to their Squad account. The operator token is the proof of authorization on the gateway side. Together, they form a two-sided trust chain without requiring manual device approval.
+
+### E2E Encryption
+
+- **Protocol:** ECDH (P-256) key exchange + AES-256-GCM message encryption
+- **No plaintext fallback:** If encryption fails after E2E is established, messages are **dropped** — never sent as plaintext. This is enforced in both `routeFromGateway()` and `broadcastToUsers()`.
+- **Status:** Implemented in the plugin. Currently disabled at the relay level (Durable Object) due to multi-tab session safety — the relay blocks E2E key exchange to prevent mismatched keys across tabs. When per-session E2E is enabled at the relay, the plugin is already hardened.
+
+### Authentication Chain Summary
+
+For a browser user's RPC call to reach the gateway through the relay, **all of the following must be valid:**
+
+1. **Browser JWT** — user authenticated with relay.squad.ceo
+2. **Relay pairing** — user's account is paired with this gateway's Durable Object (via claim token)
+3. **Relay-client connected** — plugin's outbound WS to relay is alive
+4. **Gateway connect handshake** — relay-client's device identity + operator token accepted by local gateway
+5. **Tool-level security** — each tool enforces its own restrictions (blocked dirs, redaction, write protection, SQL path limits)
+
+## Remote Tool Invocation (`tools.invoke`)
+
+The `tools.invoke` gateway method allows the browser to call plugin tools over WebSocket (used in relay mode where there is no HTTP path). This is **not** a generic RPC gateway — it is scoped exclusively to the tools registered by **this plugin**:
+
+| Tool | What it can access | Restrictions |
+|---|---|---|
+| `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | `~/.openclaw/` only | All 4 security layers apply (blocked dirs, blocked files, redaction, allowed roots, write protection) |
+| `sql_query` | `~/.openclaw/squad-ceo-data/*.db` only | sqlite3 only, no shell, no command injection (see below) |
+| `entity_list`, `entity_search`, `entity_sync` | In-memory entity index | Read-only metadata (names, types, paths) |
+| `squad.version.check`, `squad.version.update` | npm registry | Read-only check + controlled `npm install` |
+
+It **cannot** invoke gateway core tools (`exec`, `bash`, `read`, `write`, `web_fetch`, etc.) — only the tools this plugin registers via `api.registerTool()`. Every invoked tool enforces its own security restrictions independently — `tools.invoke` is just a transport layer, not a privilege escalation.
+
+## SQL Query Tool
+
+> **`sql_query` can only access the plugin's own application data** in `~/.openclaw/squad-ceo-data/`. It cannot read or modify any other files on the system — not system databases, not user documents, not gateway configuration.
+
+The `sql_query` tool provides restricted SQLite access:
+
+- **Path restriction:** Database files must be within `~/.openclaw/squad-ceo-data/` — the plugin's own data directory containing entity registries and application state. Paths outside this directory are rejected before any query is executed.
+- **No shell:** Uses `execFile` (not `exec`) — arguments are passed as an argv array, preventing command injection
+- **No arbitrary commands:** Only `sqlite3` is executed — no other binary can be invoked through this tool
+- **Data scope:** The databases in `squad-ceo-data/` contain only Squad application data (entity metadata, search indexes, user preferences). No credentials, tokens, or gateway configuration is stored in these databases.
+
+## Build Transparency
+
+The build configuration (`tsup.config.ts`) is optimized for security auditing:
+
+| Setting | Value | Reason |
+|---|---|---|
+| `minify` | `false` | Unminified bundle for human/AI security review |
+| `sourcemap` | `false` | No internal path exposure |
+| `treeshake` | `false` | All code preserved for complete auditing |
+
+## Configuration
+
+Configure in your gateway's `openclaw.json` under the plugin section:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `fs.allowedRoots` | `string[]` | `[resolved OpenClaw state dir]` | Restrict filesystem operations to these directories. Hardcoded blocks on `credentials/`, `devices/`, `identity/`, `relay/squad-relay.json`, and `.bak` files always apply regardless. |
+
+## Source Code
+
+- **Repository:** [github.com/WorldBrain/squad](https://github.com/WorldBrain/squad)
+- **Plugin directory:** `extensions/squad-openclaw/`
+- **Security-critical files:**
+  - `src/filesystem.ts` — path blocking, redaction, write protection
+  - `src/sql.ts` — restricted SQL execution
+  - `src/relay-client.ts` — relay authentication, E2E encryption, device identity, operator token handling
+  - `src/device-keys.ts` — ed25519 key generation, device identity management
+  - `src/e2e-crypto.ts` — ECDH key exchange, AES-256-GCM encryption
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,11 +1,3 @@
-/**
- * squad-openclaw — OpenClaw gateway plugin for Squad
- *
- * Provides:
- *   - Entity registry with FTS and vector search (entity_*)
- *   - Filesystem tools for remote clients (fs_read, fs_write, fs_list)
- *   - Version check and self-update gateway methods (squad.version.*)
- */
 declare function squadAppPlugin(api: any): void;
 
 export { squadAppPlugin as default };