squad-openclaw 2026.2.1906 → 2026.2.2001

package/README.md

@@ -11,7 +11,7 @@ OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity regis
 | `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 |
+| 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,10 +95,23 @@ 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.
+
 ## SQL Query Tool
 
 The `sql_query` tool provides restricted SQLite access: