squad-openclaw 2026.2.1905 → 2026.2.2001

package/README.md

@@ -0,0 +1,154 @@
+# 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 |
+| `tools.invoke` | RPC-based tool invocation for relay mode (WebSocket) |
+| Cloud relay client | **Disabled by default (opt-in).** Connects outbound to `relay.squad.ceo` for remote browser access |
+
+## 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.
+
+### 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/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 SPA 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: Write Protection (hardcoded, non-configurable)
+
+These files/directories cannot be written to, even if they fall within `allowedRoots`:
+
+- `~/.openclaw/openclaw.json` — operator configuration (read-only with redaction)
+- `~/.openclaw/squad-ceo-data/squad-relay.json` — relay device private key
+- All blocked directories above (credentials, devices, identity)
+- All `.bak` files at `~/.openclaw/` top level
+
+## Relay Security
+
+> **The cloud relay is DISABLED by default. No outbound connections are made unless the operator explicitly sets `relay.enabled: true`.** Installing this plugin alone does NOT create any network surface — the relay code is never executed until opted in.
+
+The cloud relay enables remote browser access to the gateway through `relay.squad.ceo`.
+
+### Opt-in Only
+
+The relay is **disabled by default** (`relay.enabled` defaults to `false`). The plugin entry point checks this flag **before** calling `startRelayClient()` — if the flag is not set or is `false`, no relay code runs, no WebSocket is opened, and no connection metadata is sent anywhere. The operator must explicitly enable it by setting `relay.enabled: true` in the plugin configuration.
+
+### Authentication
+
+- **Browser to Relay:** JWT authentication (email/password or Google OAuth)
+- **Relay to Gateway:** Single-use claim token (24h expiry) for first connection, stored room ID for reconnection
+- Claim tokens are generated per-user during setup — **not** open access
+
+### Device Pairing
+
+The relay-client's device identity must be **explicitly approved by the operator** before it can proxy user connections to the gateway. The plugin does **not** auto-pair or self-approve. During the onboarding flow, the AI guides the user through reading the device identity and confirming 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
+- **Status:** Implemented in the plugin. Currently disabled at the relay level (Durable Object) due to multi-tab session safety. When per-session E2E is enabled at the relay, the plugin is already hardened.
+
+### Operator Token
+
+The relay-client reads `gateway.auth.token` from `~/.openclaw/openclaw.json` via direct `fs.readFileSync`. This is intentional and safe:
+
+- The relay-client runs **server-side, in the gateway's own process** — equivalent to the gateway reading its own config
+- The token is **never sent to the relay server or the browser** — it is only injected into **local** `localhost:18789` WebSocket connections on the same machine
+- The token is **never exposed through the filesystem tool API** — `gateway.auth.*` is redacted in `filesystem.ts`
+- Direct file read is used because the plugin config API doesn't expose the full gateway config
+
+**Token flow (important for security auditing):**
+
+```
+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)
+```
+
+The relay server only sees the outer `relay.forward` envelope. It **never** receives the modified request containing the token. The token injection happens entirely within the relay-client process, and the modified message is sent over a **local loopback** connection to the gateway. A compromised relay server cannot intercept the operator token because it never traverses the relay — it only exists on the `localhost:18789` path.
+
+## SQL Query Tool
+
+The `sql_query` tool provides restricted SQLite access:
+
+- **Path restriction:** Database files must be within `~/.openclaw/squad-ceo-data/`
+- **No shell:** Uses `execFile` (not `exec`) — arguments are passed as an argv array, preventing command injection
+- **No arbitrary commands:** Only `sqlite3` is executed
+
+## 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 |
+|---|---|---|---|
+| `relay.enabled` | `boolean` | `false` | Enable cloud relay. Opt-in required. |
+| `relay.url` | `string` | `wss://relay.squad.ceo` | Cloud relay WebSocket URL |
+| `fs.allowedRoots` | `string[]` | `["~/.openclaw"]` | Restrict filesystem operations to these directories |
+
+## 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
+
+## License
+
+MIT