web-terminal/docs/EXPLORE_REMOTE_ACCESS.md

Using web-terminal off your LAN — exploration

Exploration only (not a committed plan). Produced by a multi-agent research pass (codebase-fit + security-bar verified against the repo; approach-landscape + relay-design synthesized). The crux is auth, not transport.

1. Why a bridge/rendezvous is needed (the NAT reality)

The host sits behind NAT — very likely CGNAT — so it has no public inbound reachability: nothing on the internet can open a connection to it, and you can't reliably port-forward through carrier-grade NAT. The fix is always the same shape: the host makes an outbound connection to an always-reachable middle point, your remote device connects to that same middle point, and it splices the two together. That "middle point" is your bridge. The only real question is who runs it — you (self-hosted relay / VPS) or a product built for this (Tailscale coordination+DERP, Cloudflare Tunnel). All three solve NAT identically via an outbound dial; they differ enormously in how much security-critical code you end up owning.

2. The real headline: off-LAN makes AUTH mandatory

The app today has zero authentication, by design. It hands a full interactive shell to anyone who can reach the port. On the LAN that's fine — the attacker must already be on your trusted WiFi, and Origin validation blocks the one browser attack (CSWSH). The moment the port is reachable off-LAN, "already on my WiFi" evaporates and the attacker becomes the entire internet plus bots that scan every new hostname within minutes. An unauthenticated shell reachable publicly is remote-code-execution-as-a-service — game over on the first hit.

Auth was an explicit v0.1 non-goal (TECH_DOC §7, CLAUDE.md). Off-LAN changes that decision, independent of transport. Two accepted-on-LAN risks become unacceptable:

• No auth anywhere in src/ — only Origin checks, rate-limiters, VAPID push secrets exist.
• Unauthenticated info-leak endpoints — /sessions, /live-sessions, /live-sessions/:id/preview, /projects have no Origin guard by design (src/server.ts:246-250). /sessions returns Claude cwds + first ~120 chars of prompts + resumable session UUIDs; the preview route streams live screen contents. World-readable the instant a port is exposed.

Origin validation is not authentication. A public hostname is guessable; anyone who loads your real URL passes the Origin check. Keep it (still the CSWSH defense) but it gates no attacker who just visits the URL. isOriginAllowed (src/http/origin.ts:22-53) matches scheme+host+port strictly, default-denies undefined.

Frame the work as: "add an auth/identity layer in front of the shell." Transport is secondary — and the best transports hand you that auth layer for free.

3. Options spectrum

Option	Reachability	Who runs the middle	Auth story	Setup	Cost	Code changes
Tailscale tailnet ⭐ RECOMMENDED	Your enrolled devices only; port invisible to internet	Tailscale coord; traffic E2E WireGuard	Device enrollment (SSO-backed) — strong, built-in	Low	Free tier	None — just add the MagicDNS origin to ALLOWED_ORIGINS
Tailscale Funnel	Public HTTPS URL (anyone with link)	Tailscale edge	None — public ingress → back to needing app-auth	Low	Free	Whitelist origin + build app-auth
Cloudflare Tunnel + Access ⭐ (for a public URL)	Public HTTPS URL gated by SSO	Cloudflare edge (terminates TLS → sees bytes)	Real SSO at edge (email OTP / Google / GitHub / TOTP)	Low-Med	Free (≤50 users)	Whitelist origin; verify CF-Access-Jwt-Assertion
Self-hosted relay (your mental model)	Whatever you allow	You (TLS, auth, uptime, abuse)	You build all of it	High	Small VPS	Whitelist origin + app-auth + relay must enforce Origin
Naked port-forward ❌ DO NOT	Public IP	You + router	App-auth on bare internet	Med	Highest risk	Violates CLAUDE.md "never port-forward"

RECOMMENDED default: Tailscale. Already the deployment CLAUDE.md/TECH_DOC §7 names; solves auth + encryption + NAT in one; adds zero security code to a byte-shuttle designed to have none; the internet can't even see the port to scan it. Config-only (ALLOWED_ORIGINS merge at src/config.ts:214-223).

If you insist on a self-hosted bridge: Cloudflare Tunnel and Tailscale are "the server in the middle," done correctly, with TLS/auth/DoS-protection you'd otherwise reinvent. Build your own only if you refuse both a VPN client and a third-party edge.

4. Minimum security bar (regardless of transport) — the crux

Every item must hold before any off-LAN exposure:

1. Auth in front of the shell — proxy identity (Tailscale/CF Access) or app-login. No unauthenticated path to the WS upgrade (src/server.ts:635).
2. TLS / wss on every off-LAN hop — no plaintext ws:// leaving the host (keystrokes carry passwords/API keys/Claude tokens). Frontend already picks wss on HTTPS (public/terminal-session.ts:44-47, the M6 fix) → a TLS-terminating proxy makes this automatic, no code change.
3. Keep Origin validation, whitelist the new hostname — as https://host with no :443 (isOriginAllowed compares .port strictly; standard ports parse to empty string, origin.ts:50). Forget it → every WS handshake 401s and every state-changing POST 403s.
4. No bare port-forward — outbound tunnel/overlay only.
5. Brute-force protection on the auth endpoint — reuse the per-IP sliding-window limiter (src/server.ts:104, e.g. 5/min/IP), crypto.timingSafeEqual (never ===), generic errors.
6. Secrets in env only, validated at startup, never hardcoded/logged (VAPID precedent); hash tokens at rest, file mode 0600 (src/push/subscription-store.ts:21); scrub logs (push-service.ts:148).
7. Auth audit log — login success/fail + IP + timestamp; every WS attach; every approve/reject.
8. Token/session expiry + revocation path.
9. Stay single-operator — this is "prove it's me/my device," NOT multi-tenant isolation.
10. Gate the info-leak endpoints off-LAN (src/server.ts:246-250).

Two gotchas that bite:

• Browsers can't set custom headers on a WS handshake. A WS token rides as a query param on the /term URL or an HttpOnly cookie validated in the upgrade handler. Query-string tokens leak via logs/history/Referer → prefer a cookie set by POST /login.
• POST /login needs the same requireAllowedOrigin CSRF guard (src/server.ts:332-341) as other state-changing routes.

5. If self-hosted relay: architecture sketch

Browser ──wss──▶  Relay (your VPS, public IP, TLS + auth)  ◀──persistent outbound wss── Host (web-terminal)
                          │  splices byte streams verbatim  │
        remote device            rendezvous / control            behind NAT/CGNAT

The host holds a persistent outbound WS/TCP control connection to the relay; a remote client connects (and authenticates at the relay); the relay multiplexes a channel and pipes /term frames byte-for-byte between the two.

Why the app survives unchanged: the session model is fully transport-agnostic. sessionId is client-generated and carried in the first attach frame (src/protocol.ts); PTY lifecycle is decoupled from WS lifecycle; ring-buffer replay and multi-client mirror operate on the byte stream after the handshake. A relay that forwards bytes verbatim is invisible to this layer. BIND_HOST=0.0.0.0 (src/config.ts:248) already accepts a co-located agent's loopback forward.

Relay-specific traps (why it earns "High" effort):

• The relay collapses the apparent client: req.socket.remoteAddress becomes the relay's IP, and unless the relay forwards the browser's real Origin verbatim, the check at src/server.ts:645-651 sees the relay's origin. So either the relay forwards the true Origin, or the relay itself becomes the CSWSH enforcement point. You can't have neither.
• You now own the relay's TLS, auth/pairing, abuse control, DoS protection, uptime.

Build-vs-reuse verdict: DON'T hand-roll. If you truly want self-hosted, put a proven reverse-tunnel between host and VPS — cloudflared (self-hostable), frp, or chisel — and terminate TLS + enforce auth at the VPS (Caddy/nginx + auth, or an identity proxy). A bespoke Node relay re-implements WebSocket multiplexing, framing, TLS, and auth for no benefit. Effort: reuse-a-tunnel ≈ a day of ops + the same app-auth as Option C; bespoke relay ≈ 1-2 weeks + an indefinite security-maintenance tail.

Minimal app changes for any relay/tunnel path:

• Whitelist the public origin via env merge — ALLOWED_ORIGINS=https://<name> (src/config.ts:214-223). Config only.
• Add the auth gate: HTTP middleware at src/server.ts:229 (before express.static :243) and a token/cookie check inside the upgrade handler right after the Origin check :646, before wss.handleUpgrade :654. Auth enforced before handleUpgrade → the post-handshake stream, ring-buffer replay, and multi-client mirror are never touched. All invariants intact.

6. Recommended path (phased) — v0.8

Phase 0 — Tailscale (do first; ship today). Install Tailscale on host + your devices; add the MagicDNS origin to ALLOWED_ORIGINS; optionally Tailscale Serve for TLS/wss.

• Code changes: none (config only). Outcome: "usable off-LAN from my own devices," fully solved, threat model kept honest (only enrolled devices reach the port). For most of the stated use case, you can stop here.

Phase 1 — Off-LAN safety rail (small). A REMOTE_MODE=1 flag (src/config.ts:245) that refuses to start unless TLS + an auth gate are configured, so LAN-only stays the safe default and off-LAN can't be enabled by accident. Move the info-leak read routes behind the gate when remote mode is on.

Phase 2 — App-level auth gate (needed for a public URL without SSO, i.e. Funnel/self-hosted relay; worthwhile as defense-in-depth behind CF Access):

• POST /login verifying an env secret with crypto.timingSafeEqual, rate-limited (src/server.ts:104), guarded by requireAllowedOrigin, setting an HttpOnly+Secure+SameSite=Strict cookie with expiry.
• Cookie validated in the upgrade handler at src/server.ts:646 (before handleUpgrade) and by an HTTP middleware at src/server.ts:229.
• New AUTH_TOKEN/session config in loadConfig. Start single shared token → per-device revocable tokens (hashed table + labels) if needed. Full TDD + brute-force + rotation tests.
• Code changes: Medium-High. This is the security-critical bit — why Phase 0 is so attractive.

Phase 3 (optional) — Public URL for un-enrollable devices. Prefer Cloudflare Tunnel + Access (SSO at edge, ≤50 users free) over a relay; verify CF-Access-Jwt-Assertion so a tunnel-bypass ≠ instant shell. Self-hosted relay only if you reject both a VPN client and Cloudflare (still needs Phase 2).

7. Decisions for the user

1. Whose devices? Only devices you own (→ Tailscale, zero code) — or a device you can't enroll (→ Cloudflare Tunnel + Access, or Funnel/relay + app-auth)? This one answer collapses most of the tree.
2. Delegate auth to an identity proxy, or build it in the app? Delegating adds no security-critical code to a byte-shuttle designed to have none (favored by KISS/YAGNI for a single operator).
3. Managed rendezvous vs self-hosted relay? Cloudflare/Tailscale are the middle server, with TLS/auth/abuse-control included. Self-hosting means owning all of that + uptime.
4. Trust the proxy with plaintext? Cloudflare terminates TLS at its edge (can see terminal bytes). Tailscale is end-to-end WireGuard — if you don't want a third party seeing keystrokes, Tailscale wins.
5. If app-auth is built: credential model? Single shared token (simplest) → per-device revocable tokens (real revocation) → SSO/TOTP (genuine 2FA). Pick the start and whether 2FA is in scope now.

Bottom line: the instinct ("I need a bridge") is half-right about NAT and wrong about building it — the bridge already exists as a product. Start with Tailscale (Phase 0, zero code); it solves NAT, TLS, and auth together and is already the project's recommended deployment. Reach for a public URL (Cloudflare Tunnel + Access) or a self-hosted relay only if you must open it on a device you can't enroll — and there, auth-before-handleUpgrade is non-negotiable.