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.

agent/test/tunnel.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  decodeMuxFrame,
+  encodeMuxFrame,
+  encodeOpen,
+  encodeGoaway,
+  type MuxFrameHeader,
+  type MuxOpen,
+} from 'relay-contracts'
+import { holdTunnel, dataHeader } from '../src/transport/tunnel.js'
+import { FakeWs } from './fixtures/fakes.js'
+
+const OPEN: MuxOpen = {
+  streamId: 5,
+  subdomain: 'host-42',
+  requestPath: '/term?join=abc',
+  originHeader: 'https://host-42.term.example.com',
+  remoteAddrHash: 'deadbeef',
+  capabilityTokenRef: 'jti-1',
+}
+
+function openFrame(open: MuxOpen): Uint8Array {
+  const payload = encodeOpen(open)
+  const header: MuxFrameHeader = {
+    version: 1,
+    type: 'open',
+    fin: false,
+    rst: false,
+    streamId: open.streamId,
+    payloadLen: payload.length,
+  }
+  return encodeMuxFrame(header, payload)
+}
+
+function stubHandlers() {
+  return {
+    handleOpen: vi.fn(),
+    handleData: vi.fn(),
+    handleClose: vi.fn(),
+  }
+}
+const stubHb = { onPing: vi.fn(), onPong: vi.fn() }
+
+describe('Tunnel (T7, §4.1)', () => {
+  it('round-trips a frame and yields decoded header+payload via onFrame', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const seen: Array<{ h: MuxFrameHeader; p: Uint8Array }> = []
+    tunnel.onFrame((h, p) => seen.push({ h, p }))
+    ws.emitMessage(openFrame(OPEN))
+    expect(seen).toHaveLength(1)
+    expect(seen[0]!.h.type).toBe('open')
+    expect(seen[0]!.h.streamId).toBe(5)
+  })
+
+  it('dispatches OPEN/DATA to the router', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const handlers = stubHandlers()
+    tunnel.dispatchTo(handlers, stubHb)
+    ws.emitMessage(openFrame(OPEN))
+    expect(handlers.handleOpen).toHaveBeenCalledOnce()
+    const data = new Uint8Array([1, 2, 3])
+    ws.emitMessage(encodeMuxFrame(dataHeader(5, 3), data))
+    expect(handlers.handleData).toHaveBeenCalledWith(5, expect.any(Uint8Array))
+  })
+
+  it('INV11: DATA payload passes through opaque (no parsing)', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const handlers = stubHandlers()
+    tunnel.dispatchTo(handlers, stubHb)
+    const opaque = new Uint8Array([0x1b, 0x5b, 0x33, 0x31, 0x6d]) // looks like an ANSI seq
+    ws.emitMessage(encodeMuxFrame(dataHeader(7, opaque.length), opaque))
+    const forwarded = handlers.handleData.mock.calls[0]![1] as Uint8Array
+    expect(Buffer.from(forwarded).equals(Buffer.from(opaque))).toBe(true)
+  })
+
+  it('drains after inbound GOAWAY: no new OPEN accepted', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const handlers = stubHandlers()
+    tunnel.dispatchTo(handlers, stubHb)
+    const goaway = encodeGoaway(0, 'operatorDrain')
+    ws.emitMessage(
+      encodeMuxFrame(
+        { version: 1, type: 'goaway', fin: false, rst: false, streamId: 0, payloadLen: goaway.length },
+        goaway,
+      ),
+    )
+    ws.emitMessage(openFrame({ ...OPEN, streamId: 9 }))
+    expect(handlers.handleOpen).not.toHaveBeenCalled()
+    // and it RST'd the refused stream
+    const last = decodeMuxFrame(ws.sent.at(-1)!)
+    expect(last.header.type).toBe('close')
+    expect(last.header.rst).toBe(true)
+  })
+
+  it('malformed framing does not crash the tunnel', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    tunnel.dispatchTo(stubHandlers(), stubHb)
+    expect(() => ws.emitMessage(new Uint8Array([0, 1, 2]))).not.toThrow()
+  })
+
+  it('dispatches CLOSE→handleClose and PONG→heartbeat.onPong', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const handlers = stubHandlers()
+    const hb = { onPing: vi.fn(), onPong: vi.fn() }
+    tunnel.dispatchTo(handlers, hb)
+    ws.emitMessage(
+      encodeMuxFrame({ version: 1, type: 'close', fin: false, rst: true, streamId: 5, payloadLen: 0 }, new Uint8Array(0)),
+    )
+    expect(handlers.handleClose).toHaveBeenCalledWith(5, true)
+    ws.emitMessage(
+      encodeMuxFrame({ version: 1, type: 'pong', fin: false, rst: false, streamId: 0, payloadLen: 2 }, new Uint8Array([1, 2])),
+    )
+    expect(hb.onPong).toHaveBeenCalledOnce()
+  })
+
+  it('send/goAway/sendRst/close emit well-formed frames', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    tunnel.send(dataHeader(3, 2), new Uint8Array([9, 9]))
+    expect(decodeMuxFrame(ws.sent.at(-1)!).header.type).toBe('data')
+    tunnel.goAway(3, 'shutdown')
+    expect(decodeMuxFrame(ws.sent.at(-1)!).header.type).toBe('goaway')
+    tunnel.sendRst(3)
+    const rst = decodeMuxFrame(ws.sent.at(-1)!)
+    expect(rst.header.type).toBe('close')
+    expect(rst.header.rst).toBe(true)
+    tunnel.close()
+    expect(ws.closed).toBe(true)
+  })
+
+  it('windowUpdate frames are dispatched without disturbing the stream handlers', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const handlers = stubHandlers()
+    tunnel.dispatchTo(handlers, stubHb)
+    ws.emitMessage(
+      encodeMuxFrame({ version: 1, type: 'windowUpdate', fin: false, rst: false, streamId: 1, payloadLen: 4 }, new Uint8Array([0, 0, 0, 5])),
+    )
+    expect(handlers.handleData).not.toHaveBeenCalled()
+  })
+
+  it('onGoAway surfaces the frozen reason', () => {
+    const ws = new FakeWs()
+    const tunnel = holdTunnel(ws)
+    const reasons: string[] = []
+    tunnel.onGoAway((r) => reasons.push(r))
+    const goaway = encodeGoaway(3, 'revoked')
+    ws.emitMessage(
+      encodeMuxFrame(
+        { version: 1, type: 'goaway', fin: false, rst: false, streamId: 0, payloadLen: goaway.length },
+        goaway,
+      ),
+    )
+    expect(reasons).toEqual(['revoked'])
+  })
+})