squad-openclaw 2026.2.2702 → 2026.2.2704

package/README.md

@@ -1,18 +1,35 @@
 # 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, locked-down filesystem tools, agent setup wrappers, plugin safety controls, and Tailnet internal routes for onboarding helpers.
 
 ## Features
 
-| Tool / Method | Description |
+| Tool / Method / Endpoint | 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) |
+| `squad.agents.add` | Plugin wrapper for creating agent scaffolding (workspace seed files, sessions skeleton, and config list entry) |
+| `squad.version.check` | Plugin version reporting |
+| `squad.questions.validate-envelope` | HUMAN_INPUT_REQUIRED envelope validation |
+| `tools.invoke`, `tools.list`, `squad.layout.get` | Core plugin RPC entrypoints for tool invocation/listing and gateway layout metadata |
+| `squad.plugin.status`, `squad.plugin.recover`, `squad.plugin.disable` | Plugin safety-state RPC control (status, recovery, manual disable) |
+| `GET /squad-internal/health` | Tailnet internal health + pairing capability metadata |
+| `GET /squad-internal/plugin/status` | Tailnet internal plugin safety-state status |
+| `POST /squad-internal/plugin/recover`, `POST /squad-internal/plugin/disable` | Tailnet internal plugin safety-state controls |
+| `POST /squad-internal/pairing/request`, `GET /squad-internal/pairing/status` | Tailnet internal pairing helper routes with origin/Tailnet/browser-proof checks |
+
+## Internal Endpoint Reference
+
+All `/squad-internal/*` routes enforce Tailnet context and origin checks. CORS preflight (`OPTIONS`) is handled for these routes.
+
+| Route | Method | Purpose |
+|---|---|---|
+| `/squad-internal/health` | `GET` | Returns plugin safety snapshot and pairing capability hints |
+| `/squad-internal/plugin/status` | `GET` | Returns current plugin safety state |
+| `/squad-internal/plugin/recover` | `POST` | Recovers plugin safety state back to active (unless env kill-switch is set) |
+| `/squad-internal/plugin/disable` | `POST` | Manually disables plugin safety state |
+| `/squad-internal/pairing/request` | `POST` | Creates pairing request via gateway-native pairing methods (`node/devices/device.pair.request`) |
+| `/squad-internal/pairing/status` | `GET` | Resolves pairing status via gateway-native status methods (`node/devices/device.pair.status/get`) |
 
 ## State Directory Resolution
 
@@ -78,7 +95,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)
@@ -102,22 +119,15 @@ Filesystem operations are restricted to configured root directories. By default,
 
 Operators can customize via the `fs.allowedRoots` config option.
 
-### Layer 4: Filesystem Write Protection + Surgical Gateway Mutations
+### Layer 4: Filesystem Write Protection
 
 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,148 +143,100 @@ 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()`.
-
-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.
+## Plugin Safety State (Kill Switch + Quarantine)
 
-For local testing, the relay endpoint can be overridden with environment variables:
+The plugin persists runtime safety state in:
 
-- `OPENCLAW_SQUAD_RELAY_URL` (preferred)
-- `SQUAD_RELAY_URL` (fallback)
+- `~/.openclaw/squad-ceo-data/safety/plugin-state.json`
 
-If neither is set, the plugin uses the production default `wss://relay.squad.ceo`.
+State values:
 
-### How the Relay Connection Works
+- `ACTIVE`
+- `DISABLED_MANUAL`
+- `QUARANTINED_AUTO`
 
-```
-┌──────────────┐        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) │
-                                                                                     └──────────────────┘
-```
+Behavior:
 
-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.
+- 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.
 
-### What Data Crosses the Network (relay.squad.ceo)
+Environment controls:
 
-The relay server is a message router. Here is exactly what it sees and does not see:
+- `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`)
 
-| 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 |
+Recovery paths:
 
-### Operator Token — Never Leaves the Server
+- 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.
 
-The operator token (`gateway.auth.token` in `~/.openclaw/openclaw.json`) is the most sensitive credential. Here is exactly how it flows:
+## Tailnet Pairing and Locator Security
 
-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.
+The active onboarding path is Tailnet-direct and gateway-owned:
 
-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.
+- 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
 
-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.
+### Pairing Model (Current)
 
-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.
+Pairing does **not** rely on plugin-owned approval state:
 
-```
-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)
-```
+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
 
-**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.
+This means approval is native to gateway pairing and not stored in plugin-local state.
 
-### Device Identity and Auto-Pairing
+### Plugin Route Security (`/squad-internal/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:
+Pairing helper routes enforce:
 
-- **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)
+- 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
 
-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:
+### Pairing Helper Routes (Compatibility)
 
-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
+`/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.
 
-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.
+`POST /squad-internal/pairing/request` expects browser proof fields:
 
-### E2E Encryption
+- `deviceId`
+- `publicKey` (Ed25519) **or** `publicKeyJwk` (P-256)
+- `signature`
+- `nonce`
+- `signedAt`
 
-- **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.
+`GET /squad-internal/pairing/status` expects:
 
-### Authentication Chain Summary
+- `requestId` query param
+- `deviceId` query param
 
-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 |
 |---|---|---|
 | `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:
@@ -291,7 +253,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
 
@@ -299,10 +261,10 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 - **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
+  - `src/agents.ts` — wrapper for agent setup (workspace/session skeleton + config entry update)
+  - `src/http-routes.ts` — Tailnet internal routes and browser-proof validation
+  - `src/shared-api.ts` — gateway method + tool registration boundaries
+  - `src/plugin-safety-gateway.ts`, `src/plugin-safety-state.ts` — plugin safety-state control and persistence
 
 ## License