squad-openclaw 2026.2.1906 → 2026.2.2002

package/README.md

@@ -10,8 +10,8 @@ OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity regis
 | `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 | Connects outbound to `relay.squad.ceo` for remote browser access |
+| `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 | **Disabled by default (opt-in).** Connects outbound to `relay.squad.ceo` for remote browser access |
 
 ## Security Model
 
@@ -66,11 +66,13 @@ These files/directories cannot be written to, even if they fall within `allowedR
 
 ## 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**. It must be explicitly enabled by setting `relay.enabled: true` in the plugin configuration. No outbound network connections are made unless the operator opts in.
+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
 
@@ -93,17 +95,48 @@ The relay-client's device identity must be **explicitly approved by the operator
 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** — only injected into local `localhost:18789` WebSocket connections
+- 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.
+
+## 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.
+
+**Authentication chain for relay access:** Browser JWT → relay claim token → operator-approved device pairing → operator auth token (localhost only). All four must be valid for a `tools.invoke` call to reach the gateway.
+
 ## 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/`
+- **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 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