Locking down Broker mode

[acreeger]

Threat model

• Broker compromise or snooping

• Message tampering/replay

• Unauthorized remote control

• Abuse (spam, flood, path traversal via params)

Core rules

1. • Prefer WebRTC data channel via the broker (TURN allowed). DTLS-SRTP gives E2E; the broker never terminates crypto.

   • If you must relay over WebSockets: add application-layer crypto (X25519 ECDH → symmetric AEAD like ChaCha20-Poly1305). The broker only sees ciphertext.

2. • Browser: normal user OAuth at hatchbox.ai.

   • Agent (hb server): long-lived device key from device-link flow (stored in OS keychain).

   • Handshake binds both: user id, device id, session id. Broker verifies the bind, but cannot decrypt.

3. • During connect, browser and agent run ECDH (ephemeral keys), derive session keys, and rotate them periodically (time or bytes).

   • The broker only forwards the signed ECDH messages.

4. • First time a new browser session requests relay access, the agent shows a local prompt; user must approve.

   • Store a short-lived “approved session” token (e.g., 30–60 min).

5. • Every RPC frame: action, args, session_id, nonce, timestamp, seq.

   • AEAD gives integrity; also enforce nonce uniqueness and timestamp skew.

6. • Fixed action enum (start, stop, status, logs, metadata).

   • Zod/JSON-schema validate all inputs; cap lengths, reject .. paths, no shell eval.

7. • Agent runs as non-admin, work confined to allowed directories, spawn child processes with scrubbed env.

8. • On broker: per account/device/message-type limits, total bytes/sec caps, connection quotas.

   • On agent: per session limits, log streaming backpressure, max body size.

9. • Server-side kill-switch: revoke device tokens and broker should refuse new sessions immediately.

   • Agent should also block further frames on revoked sessions.

10. Minimal broker data retention

• Store presence, routing info, and ephemeral session metadata only.

• No payload logging; short retention for connection logs (e.g., 7–14 days) without content.

Handshake (concise verision)

1. Browser (user logged in) asks broker to connect to device X.

2. Broker checks: same account, device online.

3. Broker relays signed ECDH offers between browser and agent.

4. Browser ↔ Agent derive session keys; agent prompts local user to approve.

5. On approval, broker begins dumb relay of encrypted frames.

Extra hardening (quick wins)

• Origin check on broker’s control plane (https://hatchbox.ai only).

• No cookies in control paths; header tokens only.

• TURN only if needed, otherwise direct peer (still E2E).

• SSRF guard inside agent for any outbound fetch/clone.

• Append-only audit on agent: who/what/when (no content).

What the broker must NOT do

• Terminate encryption, execute jobs, touch the filesystem, or store decrypted payloads.