squad-openclaw 2026.2.1905 → 2026.2.1906

package/README.md

@@ -0,0 +1,139 @@
+# 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 | 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 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.
+
+### 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** — only injected into local `localhost:18789` WebSocket connections
+- 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
+
+## 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

package/dist/index.js

@@ -280,10 +280,13 @@ function registryList(type) {
   if (!type) return all;
   return all.filter((e) => e.type === type);
 }
-var IDENTITY_NAME_RE = /\*\*Name:\*\*\s*\n\s*(.+?)(?=\n|$)/;
+var IDENTITY_NAME_RE = /\*\*Name:\*\*\s*\n?\s*(.+?)(?=\n|$)/;
 function parseIdentityName(content) {
   const match = content.match(IDENTITY_NAME_RE);
-  return match?.[1]?.trim() || null;
+  const name = match?.[1]?.trim();
+  if (!name) return null;
+  if (/^_\(.+\)_$/.test(name)) return null;
+  return name;
 }
 function scanAgents(configDir) {
   const now = Date.now();
@@ -639,6 +642,9 @@ function isSensitivePath(resolvedPath) {
       return true;
     }
   }
+  if (path3.dirname(resolvedPath) === OPENCLAW_DIR && resolvedPath.endsWith(".bak")) {
+    return true;
+  }
   return false;
 }
 var OPENCLAW_JSON_FILENAME = "openclaw.json";
@@ -770,7 +776,8 @@ function filterSensitiveEntries(entries) {
   });
 }
 function registerFilesystemTools(api) {
-  const allowedRoots = api.pluginConfig?.["fs.allowedRoots"] ?? [];
+  const DEFAULT_ALLOWED_ROOTS = ["~/.openclaw"];
+  const allowedRoots = api.pluginConfig?.["fs.allowedRoots"] ?? DEFAULT_ALLOWED_ROOTS;
   api.registerTool({
     name: "fs_read",
     label: "Read File",
@@ -1319,38 +1326,21 @@ function loadOrCreateRelayDeviceKeys() {
   console.log(`[relay-client] Generated relay device identity: ${deviceId.substring(0, 12)}...`);
   return keys;
 }
-function ensureDevicePaired(keys, operatorToken) {
+function writeDeviceInfoFile(keys) {
   const stateDir = process.env.OPENCLAW_STATE_DIR || path6.join(os.homedir(), ".openclaw");
-  const pairedPath = path6.join(stateDir, "devices", "paired.json");
-  let paired = {};
-  try {
-    paired = JSON.parse(fs6.readFileSync(pairedPath, "utf-8"));
-  } catch {
-  }
-  if (paired[keys.deviceId]) return false;
-  const now = Date.now();
-  const scopes = ["operator.admin", "operator.approvals", "operator.pairing"];
-  paired[keys.deviceId] = {
+  const infoPath = path6.join(stateDir, "squad-ceo-data", "relay-device-info.json");
+  const info = {
     deviceId: keys.deviceId,
     publicKey: keys.publicKey,
+    displayName: "squad-relay",
     platform: process.platform,
-    clientId: "cli",
-    clientMode: "backend",
-    role: "operator",
-    roles: ["operator"],
-    scopes,
-    tokens: operatorToken ? {
-      operator: { token: operatorToken, role: "operator", scopes, createdAtMs: now, lastUsedAtMs: now }
-    } : {},
-    createdAtMs: now,
-    approvedAtMs: now,
-    displayName: "squad-relay"
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  const dir = path6.dirname(pairedPath);
-  if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
-  fs6.writeFileSync(pairedPath, JSON.stringify(paired, null, 2), { mode: 384 });
-  console.log(`[relay-client] Device pairing entry created in paired.json`);
-  return true;
+  try {
+    fs6.writeFileSync(infoPath, JSON.stringify(info, null, 2));
+  } catch (err2) {
+    console.error("[relay-client] Failed to write relay-device-info.json:", err2);
+  }
 }
 function signDeviceIdentity(keys, clientId, clientMode, role, scopes, token, challengeNonce) {
   const signedAtMs = Date.now();
@@ -1391,11 +1381,8 @@ var RelayClient = class {
     };
     this.pendingClaimToken = this.config.roomId ? null : this.config.claimToken;
     this.deviceKeys = loadOrCreateRelayDeviceKeys();
-    const newEntry = ensureDevicePaired(this.deviceKeys, this.config.operatorToken);
-    if (newEntry) {
-      console.log("[relay-client] New device pairing entry created \u2014 restarting gateway to reload pairing store...");
-      setTimeout(() => process.exit(0), 2e3);
-    }
+    writeDeviceInfoFile(this.deviceKeys);
+    console.log(`[relay-client] Device ID: ${this.deviceKeys.deviceId}`);
   }
   /** Start connecting to the relay */
   start() {
@@ -1687,7 +1674,16 @@ var RelayClient = class {
       }
     });
     localWs.on("close", (code, reason) => {
-      console.log(`[relay-client] Local WS for user ${userId} closed: ${code} ${reason.toString()}`);
+      const reasonStr = reason.toString();
+      console.log(`[relay-client] Local WS for user ${userId} closed: ${code} ${reasonStr}`);
+      if (code === 1008) {
+        console.error(
+          `[relay-client] Device not paired with gateway. To approve, run on the gateway machine:
+  openclaw devices approve
+Or follow the onboarding instructions in the Squad web app.
+Device ID: ${this.deviceKeys.deviceId}`
+        );
+      }
       const current = this.userConnections.get(userId);
       if (current && current.localWs === localWs) {
         this.userConnections.delete(userId);
@@ -1743,8 +1739,8 @@ var RelayClient = class {
         const encrypted = conn.e2e.encrypt(JSON.stringify(msg));
         innerMsg = { _e2e: true, ...encrypted };
       } catch (err2) {
-        console.error(`[relay-client] E2E encrypt error for ${userId}:`, err2);
-        innerMsg = msg;
+        console.error(`[relay-client] E2E encrypt failed for ${userId} \u2014 dropping message:`, err2);
+        return;
       }
     }
     this.sendToRelay({
@@ -1807,8 +1803,8 @@ var RelayClient = class {
           const encrypted = conn.e2e.encrypt(JSON.stringify(msg));
           innerMsg = { _e2e: true, ...encrypted };
         } catch (err2) {
-          console.error(`[relay-client] E2E encrypt error for broadcast to ${userId}:`, err2);
-          innerMsg = msg;
+          console.error(`[relay-client] E2E encrypt failed for broadcast to ${userId} \u2014 skipping:`, err2);
+          continue;
         }
       }
       this.sendToRelay({
@@ -1887,7 +1883,7 @@ function squadAppPlugin(api) {
       }
     }
   );
-  const relayEnabled = api.pluginConfig?.["relay.enabled"] ?? true;
+  const relayEnabled = api.pluginConfig?.["relay.enabled"] ?? false;
   if (relayEnabled) {
     const relayUrl = api.pluginConfig?.["relay.url"] || "wss://relay.squad.ceo";
     startRelayClient(api, relayUrl);

package/openclaw.plugin.json

@@ -9,12 +9,13 @@
       "fs.allowedRoots": {
         "type": "array",
         "items": { "type": "string" },
-        "description": "Restrict fs_read/fs_write/fs_list/fs_delete/fs_rename to these directories. Empty or omitted = allow all."
+        "default": ["~/.openclaw"],
+        "description": "Restrict filesystem operations to these directories. Defaults to [\"~/.openclaw\"]. Hardcoded blocks on credentials/, devices/, identity/, squad-relay.json, and .bak files always apply."
       },
       "relay.enabled": {
         "type": "boolean",
-        "default": true,
-        "description": "Enable cloud relay for remote browser access. Enabled by default."
+        "default": false,
+        "description": "Enable cloud relay for remote browser access. Disabled by default — opt-in required."
       },
       "relay.url": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-openclaw",
-  "version": "2026.2.1905",
+  "version": "2026.2.1906",
   "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,9 +16,11 @@
       "./dist/index.js"
     ]
   },
+  "license": "MIT",
   "files": [
     "dist/",
-    "openclaw.plugin.json"
+    "openclaw.plugin.json",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",