squad-selfhost-web 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# squad-selfhost-web
+
+Self-host adapter plugin that mounts Squad as a parallel OpenClaw control UI.
+
+- UI mount path: `/squad`
+- Internal API: `/squad-internal/*`
+- Coexists with OpenClaw Control UI at its configured base path
+
+## Security model
+
+In self-host mode, Squad runs entirely on the user's server and browser origin.
+
+- No bridge flow
+- No relay flow
+- No outbound connection to Squad cloud services
+
+### Isolation guarantee
+
+The web bundle is mounted and executed inside the OpenClaw server context. The browser talks
+only to same-origin internal endpoints (`/squad-internal/*`). There is no connection to
+external control planes for runtime operations.
+
+## External request policy (explicit)
+
+By design, the self-hosted bundle is isolated. It only performs external requests in two
+explicitly user-triggered cases:
+
+1. License validation/check via Lemon Squeezy
+   - Host: `api.lemonsqueezy.com`
+2. Bundle/plugin version check via npm registry
+   - Host: `registry.npmjs.org`
+
+Outside those two user-triggered actions, runtime operations stay internal to your server and
+same-origin browser session.
+
+## Self-verification (SSH / server level)
+
+If you want to verify isolation yourself, run these checks on the host where OpenClaw is running.
+
+### 1) Identify the OpenClaw gateway process
+
+```bash
+ps aux | grep -E "openclaw|gateway|node" | grep -v grep
+```
+
+Pick the PID of the active gateway process.
+
+### 2) Inspect established outbound sockets for that PID
+
+```bash
+PID=<gateway_pid>
+sudo lsof -nP -a -p "$PID" -iTCP -sTCP:ESTABLISHED
+```
+
+Live watch:
+
+```bash
+watch -n 1 'sudo lsof -nP -a -p '"$PID"' -iTCP -sTCP:ESTABLISHED'
+```
+
+Expected behavior:
+- During normal in-app operations: no external hosts required
+- When user explicitly triggers license/version checks: connections may appear to:
+  - `api.lemonsqueezy.com`
+  - `registry.npmjs.org`
+
+### 3) Trace new connect syscalls from that PID (Linux, if `bpftrace` is available)
+
+```bash
+PID=<gateway_pid>
+sudo bpftrace -e 'tracepoint:syscalls:sys_enter_connect /pid == '$PID'/ { printf("connect pid=%d comm=%s\\n", pid, comm); }'
+```
+
+This confirms when the process initiates outbound connections in real time.
+
+### 4) Optional packet-level check
+
+```bash
+sudo tcpdump -i any -nn host api.lemonsqueezy.com or host registry.npmjs.org
+```
+
+Run this while triggering each explicit action to confirm only expected external egress.
+
+## About "path-level" isolation checks
+
+At OS network level, egress is process/socket based, not HTTP-route based. That means you cannot
+reliably filter outbound traffic by `/squad` path in kernel tools alone. The practical approach is:
+
+1. Correlate inbound `/squad` usage via gateway/web logs.
+2. Correlate outbound sockets/connect events by gateway PID (commands above).
+3. Validate that outbound destinations match only the two approved hosts when user-triggered.
+
+## Install
+
+```bash
+openclaw plugins install squad-selfhost-web
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare function squadSelfhostWebPlugin(api: any): void;
+
+export { squadSelfhostWebPlugin as default };