@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/protocol.md

@@ -0,0 +1,267 @@
+---
+summary: "Gateway WebSocket protocol: handshake, frames, versioning"
+read_when:
+  - Implementing or updating gateway WS clients
+  - Debugging protocol mismatches or connect failures
+  - Regenerating protocol schema/models
+title: "Gateway Protocol"
+---
+
+# Gateway protocol (WebSocket)
+
+The Gateway WS protocol is the **single control plane + node transport** for
+QuantumClaw. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
+nodes) connect over WebSocket and declare their **role** + **scope** at
+handshake time.
+
+## Transport
+
+- WebSocket, text frames with JSON payloads.
+- First frame **must** be a `connect` request.
+
+## Handshake (connect)
+
+Gateway → Client (pre-connect challenge):
+
+```json
+{
+  "type": "event",
+  "event": "connect.challenge",
+  "payload": { "nonce": "…", "ts": 1737264000000 }
+}
+```
+
+Client → Gateway:
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "cli",
+      "version": "1.2.3",
+      "platform": "macos",
+      "mode": "operator"
+    },
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"],
+    "caps": [],
+    "commands": [],
+    "permissions": {},
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "quantumclaw-cli/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+Gateway → Client:
+
+```json
+{
+  "type": "res",
+  "id": "…",
+  "ok": true,
+  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
+}
+```
+
+When a device token is issued, `hello-ok` also includes:
+
+```json
+{
+  "auth": {
+    "deviceToken": "…",
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"]
+  }
+}
+```
+
+### Node example
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "ios-node",
+      "version": "1.2.3",
+      "platform": "ios",
+      "mode": "node"
+    },
+    "role": "node",
+    "scopes": [],
+    "caps": ["camera", "canvas", "screen", "location", "voice"],
+    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
+    "permissions": { "camera.capture": true, "screen.record": false },
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "quantumclaw-ios/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+## Framing
+
+- **Request**: `{type:"req", id, method, params}`
+- **Response**: `{type:"res", id, ok, payload|error}`
+- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
+
+Side-effecting methods require **idempotency keys** (see schema).
+
+## Roles + scopes
+
+### Roles
+
+- `operator` = control plane client (CLI/UI/automation).
+- `node` = capability host (camera/screen/canvas/system.run).
+
+### Scopes (operator)
+
+Common scopes:
+
+- `operator.read`
+- `operator.write`
+- `operator.admin`
+- `operator.approvals`
+- `operator.pairing`
+
+Method scope is only the first gate. Some slash commands reached through
+`chat.send` apply stricter command-level checks on top. For example, persistent
+`/config set` and `/config unset` writes require `operator.admin`.
+
+### Caps/commands/permissions (node)
+
+Nodes declare capability claims at connect time:
+
+- `caps`: high-level capability categories.
+- `commands`: command allowlist for invoke.
+- `permissions`: granular toggles (e.g. `screen.record`, `camera.capture`).
+
+The Gateway treats these as **claims** and enforces server-side allowlists.
+
+## Presence
+
+- `system-presence` returns entries keyed by device identity.
+- Presence entries include `deviceId`, `roles`, and `scopes` so UIs can show a single row per device
+  even when it connects as both **operator** and **node**.
+
+### Node helper methods
+
+- Nodes may call `skills.bins` to fetch the current list of skill executables
+  for auto-allow checks.
+
+### Operator helper methods
+
+- Operators may call `tools.catalog` (`operator.read`) to fetch the runtime tool catalog for an
+  agent. The response includes grouped tools and provenance metadata:
+  - `source`: `core` or `plugin`
+  - `pluginId`: plugin owner when `source="plugin"`
+  - `optional`: whether a plugin tool is optional
+
+## Exec approvals
+
+- When an exec request needs approval, the gateway broadcasts `exec.approval.requested`.
+- Operator clients resolve by calling `exec.approval.resolve` (requires `operator.approvals` scope).
+- For `host=node`, `exec.approval.request` must include `systemRunPlan` (canonical `argv`/`cwd`/`rawCommand`/session metadata). Requests missing `systemRunPlan` are rejected.
+
+## Versioning
+
+- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
+- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.
+- Schemas + models are generated from TypeBox definitions:
+  - `pnpm protocol:gen`
+  - `pnpm protocol:gen:swift`
+  - `pnpm protocol:check`
+
+## Auth
+
+- If `QUANTUMCLAW_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
+  must match or the socket is closed.
+- After pairing, the Gateway issues a **device token** scoped to the connection
+  role + scopes. It is returned in `hello-ok.auth.deviceToken` and should be
+  persisted by the client for future connects.
+- Device tokens can be rotated/revoked via `device.token.rotate` and
+  `device.token.revoke` (requires `operator.pairing` scope).
+- Auth failures include `error.details.code` plus recovery hints:
+  - `error.details.canRetryWithDeviceToken` (boolean)
+  - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
+- Client behavior for `AUTH_TOKEN_MISMATCH`:
+  - Trusted clients may attempt one bounded retry with a cached per-device token.
+  - If that retry fails, clients should stop automatic reconnect loops and surface operator action guidance.
+
+## Device identity + pairing
+
+- Nodes should include a stable device identity (`device.id`) derived from a
+  keypair fingerprint.
+- Gateways issue tokens per device + role.
+- Pairing approvals are required for new device IDs unless local auto-approval
+  is enabled.
+- **Local** connects include loopback and the gateway host’s own tailnet address
+  (so same‑host tailnet binds can still auto‑approve).
+- All WS clients must include `device` identity during `connect` (operator + node).
+  Control UI can omit it only in these modes:
+  - `gateway.controlUi.allowInsecureAuth=true` for localhost-only insecure HTTP compatibility.
+  - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, severe security downgrade).
+- All connections must sign the server-provided `connect.challenge` nonce.
+
+### Device auth migration diagnostics
+
+For legacy clients that still use pre-challenge signing behavior, `connect` now returns
+`DEVICE_AUTH_*` detail codes under `error.details.code` with a stable `error.details.reason`.
+
+Common migration failures:
+
+| Message                     | details.code                     | details.reason           | Meaning                                            |
+| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
+| `device nonce required`     | `DEVICE_AUTH_NONCE_REQUIRED`     | `device-nonce-missing`   | Client omitted `device.nonce` (or sent blank).     |
+| `device nonce mismatch`     | `DEVICE_AUTH_NONCE_MISMATCH`     | `device-nonce-mismatch`  | Client signed with a stale/wrong nonce.            |
+| `device signature invalid`  | `DEVICE_AUTH_SIGNATURE_INVALID`  | `device-signature`       | Signature payload does not match v2 payload.       |
+| `device signature expired`  | `DEVICE_AUTH_SIGNATURE_EXPIRED`  | `device-signature-stale` | Signed timestamp is outside allowed skew.          |
+| `device identity mismatch`  | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch`     | `device.id` does not match public key fingerprint. |
+| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key`      | Public key format/canonicalization failed.         |
+
+Migration target:
+
+- Always wait for `connect.challenge`.
+- Sign the v2 payload that includes the server nonce.
+- Send the same nonce in `connect.params.device.nonce`.
+- Preferred signature payload is `v3`, which binds `platform` and `deviceFamily`
+  in addition to device/client/role/scopes/token/nonce fields.
+- Legacy `v2` signatures remain accepted for compatibility, but paired-device
+  metadata pinning still controls command policy on reconnect.
+
+## TLS + pinning
+
+- TLS is supported for WS connections.
+- Clients may optionally pin the gateway cert fingerprint (see `gateway.tls`
+  config plus `gateway.remote.tlsFingerprint` or CLI `--tls-fingerprint`).
+
+## Scope
+
+This protocol exposes the **full gateway API** (status, channels, models, chat,
+agent, sessions, nodes, approvals, etc.). The exact surface is defined by the
+TypeBox schemas in `src/gateway/protocol/schema.ts`.

package/docs/gateway/remote-gateway-readme.md

@@ -0,0 +1,158 @@
+---
+summary: "SSH tunnel setup for QuantumClaw.app connecting to a remote gateway"
+read_when: "Connecting the macOS app to a remote gateway over SSH"
+title: "Remote Gateway Setup"
+---
+
+# Running QuantumClaw.app with a Remote Gateway
+
+QuantumClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
+
+## Overview
+
+```mermaid
+flowchart TB
+    subgraph Client["Client Machine"]
+        direction TB
+        A["QuantumClaw.app"]
+        B["ws://127.0.0.1:18789\n(local port)"]
+        T["SSH Tunnel"]
+
+        A --> B
+        B --> T
+    end
+    subgraph Remote["Remote Machine"]
+        direction TB
+        C["Gateway WebSocket"]
+        D["ws://127.0.0.1:18789"]
+
+        C --> D
+    end
+    T --> C
+```
+
+## Quick Setup
+
+### Step 1: Add SSH Config
+
+Edit `~/.ssh/config` and add:
+
+```ssh
+Host remote-gateway
+    HostName <REMOTE_IP>          # e.g., 172.27.187.184
+    User <REMOTE_USER>            # e.g., jefferson
+    LocalForward 18789 127.0.0.1:18789
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
+
+### Step 2: Copy SSH Key
+
+Copy your public key to the remote machine (enter password once):
+
+```bash
+ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
+```
+
+### Step 3: Set Gateway Token
+
+```bash
+launchctl setenv QUANTUMCLAW_GATEWAY_TOKEN "<your-token>"
+```
+
+### Step 4: Start SSH Tunnel
+
+```bash
+ssh -N remote-gateway &
+```
+
+### Step 5: Restart QuantumClaw.app
+
+```bash
+# Quit QuantumClaw.app (⌘Q), then reopen:
+open /path/to/QuantumClaw.app
+```
+
+The app will now connect to the remote gateway through the SSH tunnel.
+
+---
+
+## Auto-Start Tunnel on Login
+
+To have the SSH tunnel start automatically when you log in, create a Launch Agent.
+
+### Create the PLIST file
+
+Save this as `~/Library/LaunchAgents/ai.quantumclaw.ssh-tunnel.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.quantumclaw.ssh-tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/ssh</string>
+        <string>-N</string>
+        <string>remote-gateway</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### Load the Launch Agent
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.quantumclaw.ssh-tunnel.plist
+```
+
+The tunnel will now:
+
+- Start automatically when you log in
+- Restart if it crashes
+- Keep running in the background
+
+Legacy note: remove any leftover `com.quantumclaw.ssh-tunnel` LaunchAgent if present.
+
+---
+
+## Troubleshooting
+
+**Check if tunnel is running:**
+
+```bash
+ps aux | grep "ssh -N remote-gateway" | grep -v grep
+lsof -i :18789
+```
+
+**Restart the tunnel:**
+
+```bash
+launchctl kickstart -k gui/$UID/ai.quantumclaw.ssh-tunnel
+```
+
+**Stop the tunnel:**
+
+```bash
+launchctl bootout gui/$UID/ai.quantumclaw.ssh-tunnel
+```
+
+---
+
+## How It Works
+
+| Component                            | What It Does                                                 |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789               |
+| `ssh -N`                             | SSH without executing remote commands (just port forwarding) |
+| `KeepAlive`                          | Automatically restarts tunnel if it crashes                  |
+| `RunAtLoad`                          | Starts tunnel when the agent loads                           |
+
+QuantumClaw.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.

package/docs/gateway/remote.md

@@ -0,0 +1,153 @@
+---
+summary: "Remote access using SSH tunnels (Gateway WS) and tailnets"
+read_when:
+  - Running or troubleshooting remote gateway setups
+title: "Remote Access"
+---
+
+# Remote access (SSH, tunnels, and tailnets)
+
+This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
+
+- For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
+- For **nodes (iOS/Android and future devices)**: connect to the Gateway **WebSocket** (LAN/tailnet or SSH tunnel as needed).
+
+## The core idea
+
+- The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
+- For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
+
+## Common VPN/tailnet setups (where the agent lives)
+
+Think of the **Gateway host** as “where the agent lives.” It owns sessions, auth profiles, channels, and state.
+Your laptop/desktop (and nodes) connect to that host.
+
+### 1) Always-on Gateway in your tailnet (VPS or home server)
+
+Run the Gateway on a persistent host and reach it via **Tailscale** or SSH.
+
+- **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
+- **Fallback:** keep loopback + SSH tunnel from any machine that needs access.
+- **Examples:** [exe.dev](/install/exe-dev) (easy VM) or [Hetzner](/install/hetzner) (production VPS).
+
+This is ideal when your laptop sleeps often but you want the agent always-on.
+
+### 2) Home desktop runs the Gateway, laptop is remote control
+
+The laptop does **not** run the agent. It connects remotely:
+
+- Use the macOS app’s **Remote over SSH** mode (Settings → General → “QuantumClaw runs”).
+- The app opens and manages the tunnel, so WebChat + health checks “just work.”
+
+Runbook: [macOS remote access](/platforms/mac/remote).
+
+### 3) Laptop runs the Gateway, remote access from other machines
+
+Keep the Gateway local but expose it safely:
+
+- SSH tunnel to the laptop from other machines, or
+- Tailscale Serve the Control UI and keep the Gateway loopback-only.
+
+Guide: [Tailscale](/gateway/tailscale) and [Web overview](/web).
+
+## Command flow (what runs where)
+
+One gateway service owns state + channels. Nodes are peripherals.
+
+Flow example (Telegram → node):
+
+- Telegram message arrives at the **Gateway**.
+- Gateway runs the **agent** and decides whether to call a node tool.
+- Gateway calls the **node** over the Gateway WebSocket (`node.*` RPC).
+- Node returns the result; Gateway replies back out to Telegram.
+
+Notes:
+
+- **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
+- macOS app “node mode” is just a node client over the Gateway WebSocket.
+
+## SSH tunnel (CLI + tools)
+
+Create a local tunnel to the remote Gateway WS:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@host
+```
+
+With the tunnel up:
+
+- `quantumclaw health` and `quantumclaw status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
+- `quantumclaw gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
+
+Note: replace `18789` with your configured `gateway.port` (or `--port`/`QUANTUMCLAW_GATEWAY_PORT`).
+Note: when you pass `--url`, the CLI does not fall back to config or environment credentials.
+Include `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+## CLI remote defaults
+
+You can persist a remote target so CLI commands use it by default:
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://127.0.0.1:18789",
+      token: "your-token",
+    },
+  },
+}
+```
+
+When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
+
+## Credential precedence
+
+Gateway credential resolution follows one shared contract across call/probe/status paths and Discord exec-approval monitoring. Node-host uses the same base contract with one local-mode exception (it intentionally ignores `gateway.remote.*`):
+
+- Explicit credentials (`--token`, `--password`, or tool `gatewayToken`) always win on call paths that accept explicit auth.
+- URL override safety:
+  - CLI URL overrides (`--url`) never reuse implicit config/env credentials.
+  - Env URL overrides (`QUANTUMCLAW_GATEWAY_URL`) may use env credentials only (`QUANTUMCLAW_GATEWAY_TOKEN` / `QUANTUMCLAW_GATEWAY_PASSWORD`).
+- Local mode defaults:
+  - token: `QUANTUMCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (remote fallback applies only when local auth token input is unset)
+  - password: `QUANTUMCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (remote fallback applies only when local auth password input is unset)
+- Remote mode defaults:
+  - token: `gateway.remote.token` -> `QUANTUMCLAW_GATEWAY_TOKEN` -> `gateway.auth.token`
+  - password: `QUANTUMCLAW_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password`
+- Node-host local-mode exception: `gateway.remote.token` / `gateway.remote.password` are ignored.
+- Remote probe/status token checks are strict by default: they use `gateway.remote.token` only (no local token fallback) when targeting remote mode.
+- Legacy `CLAWDBOT_GATEWAY_*` env vars are only used by compatibility call paths; probe/status/auth resolution uses `QUANTUMCLAW_GATEWAY_*` only.
+
+## Chat UI over SSH
+
+WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
+
+- Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`.
+- On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.
+
+## macOS app "Remote over SSH"
+
+The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
+
+Runbook: [macOS remote access](/platforms/mac/remote).
+
+## Security rules (remote/VPN)
+
+Short version: **keep the Gateway loopback-only** unless you’re sure you need a bind.
+
+- **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure).
+- Plaintext `ws://` is loopback-only by default. For trusted private networks,
+  set `QUANTUMCLAW_ALLOW_INSECURE_PRIVATE_WS=1` on the client process as break-glass.
+- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use auth tokens/passwords.
+- `gateway.remote.token` / `.password` are client credential sources. They do **not** configure server auth by themselves.
+- Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
+- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
+- `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`.
+- **Tailscale Serve** can authenticate Control UI/WebSocket traffic via identity
+  headers when `gateway.auth.allowTailscale: true`; HTTP API endpoints still
+  require token/password auth. This tokenless flow assumes the gateway host is
+  trusted. Set it to `false` if you want tokens/passwords everywhere.
+- Treat browser control like operator access: tailnet-only + deliberate node pairing.
+
+Deep dive: [Security](/gateway/security).