2af57e6686
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.
54 lines
3.0 KiB
Markdown
54 lines
3.0 KiB
Markdown
# 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).
|