squad-openclaw 2026.2.2209 → 2026.2.2703

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity registry, filesystem tools, SQL queries, version management, and Tailnet internal routes for secure onboarding helpers.
 
 ## Features
 
@@ -10,9 +10,9 @@ 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 |
-| `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) |
+| `tools.invoke` | RPC-based tool invocation over gateway methods — **only invokes this plugin's own tools**, each with its own security restrictions (see below) |
+| `squad.plugin.status`, `squad.plugin.recover`, `squad.plugin.disable` | Plugin safety-state RPC control (status, recovery, manual disable) |
+| `/squad-internal/health`, `/squad-internal/plugin/*`, `/squad-internal/pairing/*` | Tailnet internal health, safety-state, and pairing routes with origin/Tailnet checks |
 
 ## State Directory Resolution
 
@@ -78,7 +78,7 @@ These directories are **completely blocked** from all filesystem operations (rea
 
 | Path | Reason |
 |---|---|
-| `~/.openclaw/squad-ceo-data/relay/squad-relay.json` | Contains ed25519 private key for relay device identity |
+| `~/.openclaw/squad-ceo-data/relay/squad-relay.json` | Legacy relay-state material from older transport flows (blocked to prevent accidental secret disclosure) |
 | `~/.openclaw/*.bak` | Backup files at the top level contain unredacted config (tokens, keys) that would bypass redaction |
 
 ### Layer 2: Redacted Files (hardcoded, non-configurable)
@@ -107,17 +107,10 @@ Operators can customize via the `fs.allowedRoots` config option.
 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
+- `~/.openclaw/squad-ceo-data/relay/squad-relay.json` — legacy relay-state secret file (blocked)
 - 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:
@@ -133,127 +126,79 @@ On plugin startup, Squad runs an internal migration harness. Current migration b
 
 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()`.
+## Plugin Safety State (Kill Switch + Quarantine)
 
-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.
+The plugin persists runtime safety state in:
 
-For local testing, the relay endpoint can be overridden with environment variables:
+- `~/.openclaw/squad-ceo-data/safety/plugin-state.json`
 
-- `OPENCLAW_SQUAD_RELAY_URL` (preferred)
-- `SQUAD_RELAY_URL` (fallback)
+State values:
 
-If neither is set, the plugin uses the production default `wss://relay.squad.ceo`.
+- `ACTIVE`
+- `DISABLED_MANUAL`
+- `QUARANTINED_AUTO`
 
-### How the Relay Connection Works
+Behavior:
 
-```
-┌──────────────┐        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:
+- If disabled/quarantined, plugin methods return typed errors (`PLUGIN_DISABLED` / `PLUGIN_QUARANTINED`) instead of crashing startup/runtime.
+- Quarantine auto-expires after a cooldown window and transitions back to `ACTIVE`.
+- Environment kill switch overrides persisted state and is authoritative.
 
-| 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:
+Environment controls:
 
-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.
+- `SQUAD_PLUGIN_DISABLED=1` — force disable plugin
+- `SQUAD_PLUGIN_DISABLE_REASON="..."` — optional operator-facing reason
+- `SQUAD_PLUGIN_FAILURE_THRESHOLD` — failures before auto-quarantine (default `3`)
+- `SQUAD_PLUGIN_FAILURE_WINDOW_MS` — failure counting window (default `300000`)
+- `SQUAD_PLUGIN_QUARANTINE_MS` — quarantine duration (default `600000`)
 
-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.
+Recovery paths:
 
-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.
+- RPC: `openclaw gateway call squad.plugin.recover --json`
+- HTTP (Tailnet): `POST /squad-internal/plugin/recover`
+- If env kill switch is active, unset `SQUAD_PLUGIN_DISABLED` and restart gateway.
 
-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.
+## Tailnet Pairing and Locator Security
 
-```
-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 active onboarding path is Tailnet-direct and gateway-owned:
 
-**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.
+- Browser connects directly to `wss://<gateway>.ts.net`
+- OpenClaw gateway enforces pairing approval state
+- Relay service is used for account auth and locator metadata only
 
-### Device Identity and Auto-Pairing
+### Pairing Model (Current)
 
-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:
+Pairing does **not** rely on plugin-owned approval state:
 
-- **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)
+1. Browser receives gateway `connect.challenge`
+2. Browser signs challenge with its per-browser device key
+3. Browser sends native `connect` request
+4. If unpaired, gateway returns pairing-required error (with `requestId` when available)
+5. UI shows `openclaw devices approve <requestId>`
+6. UI polls reconnect automatically in the background until approved
 
-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:
+This means approval is native to gateway pairing and not stored in plugin-local state.
 
-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
+### Plugin Route Security (`/squad-internal/pairing/*`)
 
-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.
+Pairing helper routes enforce:
 
-### E2E Encryption
+- Allowed browser origin (`SQUAD_ALLOWED_ORIGINS` or built-in defaults)
+- Tailnet context (Tailnet headers/hostname checks)
+- Browser proof (device ID/public key/signature/nonce/signedAt) on pairing request creation
+- Nonce freshness and per-device/IP rate limits
 
-- **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.
+### Pairing Helper Routes (Compatibility)
 
-### Authentication Chain Summary
+`/squad-internal/pairing/request` and `/squad-internal/pairing/status` are still present for compatibility, but the current SPA pairing flow no longer depends on them as primary path.
 
-For a browser user's RPC call to reach the gateway through the relay, **all of the following must be valid:**
+### Legacy Relay-State File Handling
 
-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)
+`~/.openclaw/squad-ceo-data/relay/squad-relay.json` is still blocked by filesystem security rules to protect historical secrets from older relay transport versions.
 
 ## 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**:
+The `tools.invoke` gateway method allows the browser to call plugin tools over WebSocket transport when direct HTTP tool calls are unavailable. This is **not** a generic RPC gateway — it is scoped exclusively to the tools registered by **this plugin**:
 
 | Tool | What it can access | Restrictions |
 |---|---|---|
@@ -291,7 +236,7 @@ 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. |
+| `fs.allowedRoots` | `string[]` | `[resolved OpenClaw state dir]` | Restrict filesystem operations to these directories. Hardcoded blocks on `credentials/`, `devices/`, `identity/`, legacy `relay/squad-relay.json`, and `.bak` files always apply regardless. |
 
 ## Source Code
 
@@ -300,9 +245,9 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 - **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
+  - `src/http-routes.ts` — Tailnet internal routes and browser-proof validation
+  - `src/shared-api.ts` — gateway method + tool registration boundaries
+  - `src/relay-client.ts`, `src/device-keys.ts`, `src/e2e-crypto.ts` — legacy relay transport components retained in repository but not in the active Tailnet-direct setup path
 
 ## License