kai/web-terminal
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
web-terminal/term-relay/frp-scaffold
History
Yaojia Wang 2af57e6686 feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web) 
Multi-tenant reverse-tunnel service ("ngrok for Claude Code" with E2E): a
host-agent dials OUT to an operator-run relay; external devices reach the host
THROUGH the relay, routed by per-tenant subdomain, forwarding ciphertext only
(the relay never sees plaintext). Lets a customer reach their own self-hosted
web-terminal from anywhere with zero networking setup.

Packages — all tsc-strict + vitest green (656 tests), cross-package integration verified:
- relay-contracts: frozen shared contracts (mux frame codec, data model,
  capability token, E2E envelope, pairing) — the src/types.ts analog
- term-relay:   native WS mux + stateless data plane (subdomain routing, ciphertext forward)
- agent:        host-agent (pairing, per-host Ed25519 + mTLS dial-out, forwards to 127.0.0.1:3000)
- control-plane: accounts/hosts registry, pairing-code flow, routing table, provisioning
- relay-e2e:    browser<->agent E2E (X25519 ECDH through relay, AEAD, anti-replay, recoverable replay key)
- relay-auth:   Passkey/WebAuthn, capability tokens, per-host certs, deny-by-default tenant isolation
- relay-web:    browser login + Web Crypto E2E + client-side preview rendering

Security invariants INV1-15 enforced; cross-tenant isolation CI tripwire live
(.github/workflows/relay-tripwire.yml). Design + implementation-level plans in
docs/PLAN_RELAY_*.md and docs/EXPLORE_RELAY_SERVICE.md.

NOTE: generated autonomously per the reviewed plans. The security-critical
packages (relay-e2e, relay-auth) REQUIRE expert security audit before any real
deployment — passing tests prove self-consistency, not resistance to attackers.
Base app (src/, public/) unchanged; concurrent desktop work left uncommitted.
2026-07-02 06:10:16 +02:00
..
frps.toml
feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web)
2026-07-02 06:10:16 +02:00
plugin-hook.ts
feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web)
2026-07-02 06:10:16 +02:00
README.md
feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web)
2026-07-02 06:10:16 +02:00

README.md

frp scaffold — v0.8 MVP transport (café-demo runbook)

The v0.8 stepping-stone transport for the rendezvous-relay: a single-node frps on a VPS with wildcard-subdomain vhost routing, so a phone browser can open alice.term.<domain> and land in the laptop's shell with no router/VPN/static-IP configured. This is deliberately temporary — v0.9 replaces it with the native §4.1 WS mux (see Retirement below).

Pieces

Piece File Role
frps config frps.toml wildcard *.term.<domain> vhost + edge auth plugin
server-plugin shim plugin-hook.ts delegates Login/NewProxy/NewUserConn to P3 (no tenancy logic)
agent (frpc) wrap P2 agent/ dials out, wraps ws://127.0.0.1:3000
control-plane authz P3 control-plane/ owns the deny-by-default decision

Runbook (one VPS)

  1. Wildcard DNS — *.term.<domain> → the VPS public IP (an A/AAAA record on the wildcard).
  2. Wildcard TLS — LetsEncrypt DNS-01 for *.term.<domain> (or put Cloudflare in front and terminate TLS there — M6 scheme-following is preserved end-to-end either way).
  3. frps — run with frps.toml; set subdomainHost = <BASE_DOMAIN>, vhostHTTPSPort = 443.
  4. Edge auth — start the plugin-hook.ts HTTP shim on 127.0.0.1:9001; point it at P3's authz endpoint. Every Login/NewProxy/NewUserConn is deny-by-default (INDEX v0.8 shared-token gate — a KNOWN temporary shortcut).
  5. Agent — on the laptop, run the P2 frpc-wrapped agent; it registers subdomain alice and proxies to the local web-terminal ws://127.0.0.1:3000.
  6. Demo — from a phone browser open alice.term.<domain>, pass the clientToken gate, and you are in the laptop shell.

Confirm (acceptance)

  • A relay-node restart does NOT kill the running shell — the PTY survives on the laptop (base-app PTY≠WS decoupling, INV7).
  • A foreign-Origin page cannot open the WS (CSWSH retained at the edge).
  • All 212 base-app tests still pass (npm test in the repo root) — the relay is a layer underneath the existing WebSocket; it does not modify src/.

Retirement → native §4.1 mux (v0.9)

This scaffold is a swap, not a rewrite. Each frp piece maps 1:1 onto a native-mux task:

v0.8 frp piece v0.9 native replacement
frp yamux stream multiplexing §4.1 mux frame codec + MuxSession (T2/T6)
frp subdomain vhost routing extractSubdomain + RouteResolver (T7)
frp login/NewUserConn plugin authorizeUpgrade thin adapter → P5 onUpgrade (T8)
frp shared clientToken/agentToken capability tokens (P5) + mTLS agent listener (T9)
frp opaque TCP/WS forwarding opaque byte splice in relay-node (T10, INV2/INV11)

Because both speak subdomain routing + opaque byte forwarding, ciphertext (P4's E2EEnvelope) drops into DATA frames without reshaping anything (INV2). Even in v0.8, no terminal bytes are parsed — frp forwards opaque streams (INV11).