# 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).