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.
This commit is contained in:
Yaojia Wang
2026-07-02 06:10:16 +02:00
parent e4c327e25e
commit 2af57e6686
326 changed files with 40877 additions and 0 deletions

105
relay-web/src/dashboard.ts Normal file
View File

@@ -0,0 +1,105 @@
/**
* T5 (v0.9) — dashboard host list with `●online/offline/draining/revoked` status.
*
* Renders `api.listHosts()` as cards (subdomain, status dot, last_seen, an "open" action routing to
* the terminal view for that host_id) and polls for live `●online` flips. The UI reflects
* server-authorized hosts only — there is NO input path to name a foreign host_id (INV1/INV3
* defense-in-depth; the real gate is server-side). A `revoked` host is non-interactive (INV12 UI).
*
* All dynamic text is set via `textContent` (never `innerHTML`) — XSS discipline.
*/
import type { ApiClient } from './api-client'
import type { HostRecord, HostStatus } from './api-schemas'
import { ApiError } from './errors'
const DEFAULT_POLL_MS = 5000
export interface Dashboard {
refresh(): Promise<void>
dispose(): void
}
export interface DashboardOpts {
readonly pollMs?: number
/** Routes to the terminal view for a host; injected so the module owns no navigation policy. */
readonly onOpen?: (hostId: string) => void
}
/** Statuses that must NOT expose an "open" action in the UI (INV12 defense-in-depth). */
const NON_INTERACTIVE: ReadonlySet<HostStatus> = new Set<HostStatus>(['revoked'])
function buildCard(host: HostRecord, opts: DashboardOpts): HTMLElement {
const card = document.createElement('div')
card.className = 'host-card'
card.dataset['hostId'] = host.hostId
card.dataset['status'] = host.status
const dot = document.createElement('span')
dot.className = `status-dot status-${host.status}`
dot.setAttribute('aria-label', host.status)
dot.textContent = '●'
const name = document.createElement('span')
name.className = 'host-subdomain'
name.textContent = host.subdomain
const seen = document.createElement('span')
seen.className = 'host-last-seen'
seen.textContent = host.lastSeen
card.append(dot, name, seen)
if (NON_INTERACTIVE.has(host.status)) {
const blocked = document.createElement('span')
blocked.className = 'host-blocked'
blocked.textContent = 'revoked'
card.append(blocked)
} else {
const open = document.createElement('button')
open.className = 'host-open'
open.type = 'button'
open.textContent = 'open'
open.addEventListener('click', () => opts.onOpen?.(host.hostId))
card.append(open)
}
return card
}
export function mountDashboard(root: HTMLElement, api: ApiClient, opts: DashboardOpts = {}): Dashboard {
const pollMs = opts.pollMs ?? DEFAULT_POLL_MS
const list = document.createElement('div')
list.className = 'host-list'
const banner = document.createElement('p')
banner.className = 'dashboard-error'
banner.setAttribute('role', 'alert')
root.append(banner, list)
let timer: ReturnType<typeof setInterval> | null = null
let disposed = false
async function refresh(): Promise<void> {
try {
const hosts = await api.listHosts()
if (disposed) return
banner.textContent = ''
list.replaceChildren(...hosts.map((h) => buildCard(h, opts)))
} catch (err) {
if (disposed) return
// Zod drift or a rejection surfaces as a banner; polling continues (never renders undefined).
banner.textContent =
err instanceof ApiError ? `Could not load hosts (${err.kind}).` : 'Could not load hosts.'
}
}
void refresh()
timer = setInterval(() => void refresh(), pollMs)
return {
refresh,
dispose(): void {
disposed = true
if (timer) clearInterval(timer)
},
}
}