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.

control-plane/src/registry/accounts.ts

@@ -0,0 +1,63 @@
+/**
+ * T3 — account registry (immutable, INV8). `createAccount` writes a version-1 snapshot;
+ * `setAccountStatus` performs the atomic append-version + pointer-swap (prior snapshot stays
+ * readable from `versions()`). Never mutates a lifecycle field in place.
+ */
+import type { AccountRecord, AccountStatus } from '../model/records.js'
+import type { AccountStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import type { PlanTier } from 'relay-contracts'
+import { newUuid, nowIso } from '../util/ids.js'
+
+export interface AccountRegistry {
+  createAccount(plan: PlanTier): Promise<AccountRecord>
+  getAccount(accountId: string): Promise<AccountRecord | null>
+  setAccountStatus(accountId: string, status: AccountStatus): Promise<AccountRecord>
+}
+
+export interface AccountRegistryDeps {
+  readonly accounts: AccountStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createAccountRegistry(deps: AccountRegistryDeps): AccountRegistry {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  return {
+    async createAccount(plan) {
+      const rec: AccountRecord = {
+        accountId: newUuid(), // unguessable, never recycled (INV1 precondition)
+        plan,
+        createdAt: nowIso(),
+        status: 'active',
+      }
+      await deps.accounts.insert(rec)
+      await audit.writeAuditEvent({
+        action: 'account.create',
+        principalId: actor,
+        accountId: rec.accountId,
+        hostId: null,
+        ts: rec.createdAt,
+        meta: { plan },
+      })
+      return rec
+    },
+    async getAccount(accountId) {
+      return deps.accounts.get(accountId)
+    },
+    async setAccountStatus(accountId, status) {
+      const next = await deps.accounts.swapStatus(accountId, status, actor) // NEW snapshot, atomic swap
+      await audit.writeAuditEvent({
+        action: status === 'suspended' ? 'account.suspend' : 'manage',
+        principalId: actor,
+        accountId,
+        hostId: null,
+        ts: nowIso(),
+        meta: { status },
+      })
+      return next
+    },
+  }
+}

control-plane/src/registry/hosts.ts

@@ -0,0 +1,103 @@
+/**
+ * T4 — host registry: the ownership source of truth (INV1). A host is resolvable ONLY via
+ * `hostId`/`subdomain` bound to an account — there is NO raw address/port/hostname resolution
+ * path in this module. `ownsHost` is the deny-by-default ownership predicate (INV1/INV6). DB
+ * stores only the PUBLIC Ed25519 key (INV4). Status changes are versioned snapshots (INV8).
+ */
+import type { HostRecord, HostStatus } from '../model/records.js'
+import type { HostStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { newUuid, nowIso } from '../util/ids.js'
+import { fingerprint } from '../ca/fingerprint.js'
+
+export interface BindHostInput {
+  readonly accountId: string
+  readonly subdomain: string
+  readonly agentPubkey: Uint8Array
+  readonly enrollFpr: string
+}
+
+export interface HostRegistry {
+  bindHost(input: BindHostInput): Promise<HostRecord>
+  getHost(hostId: string): Promise<HostRecord | null>
+  getHostBySubdomain(subdomain: string): Promise<HostRecord | null>
+  listHosts(accountId: string): Promise<readonly HostRecord[]>
+  setHostStatus(hostId: string, status: HostStatus): Promise<HostRecord>
+  ownsHost(accountId: string, hostId: string): Promise<boolean>
+  touchLastSeen(hostId: string): Promise<void>
+}
+
+export interface HostRegistryDeps {
+  readonly hosts: HostStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createHostRegistry(deps: HostRegistryDeps): HostRegistry {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  return {
+    async bindHost(input) {
+      // enroll_fpr MUST be the fingerprint of the presented pubkey (defence-in-depth: recompute).
+      const expectedFpr = fingerprint(input.agentPubkey)
+      if (input.enrollFpr !== expectedFpr) {
+        throw new Error('enrollFpr does not match agentPubkey fingerprint')
+      }
+      const rec: HostRecord = {
+        hostId: newUuid(), // unguessable UUIDv4, never recycled (INV1)
+        accountId: input.accountId,
+        subdomain: input.subdomain,
+        // Defensive copy → fresh ArrayBuffer-backed array (immutability + TS6 variance). PUBLIC key only (INV4).
+        agentPubkey: new Uint8Array(input.agentPubkey),
+        enrollFpr: input.enrollFpr,
+        status: 'offline',
+        lastSeen: nowIso(),
+        createdAt: nowIso(),
+        revokedAt: null,
+      }
+      await deps.hosts.insert(rec)
+      await audit.writeAuditEvent({
+        action: 'host.bind',
+        principalId: actor,
+        accountId: input.accountId,
+        hostId: rec.hostId,
+        ts: rec.createdAt,
+        meta: { subdomain: input.subdomain, enrollFpr: input.enrollFpr },
+      })
+      return rec
+    },
+    async getHost(hostId) {
+      return deps.hosts.get(hostId)
+    },
+    async getHostBySubdomain(subdomain) {
+      return deps.hosts.getBySubdomain(subdomain)
+    },
+    async listHosts(accountId) {
+      return deps.hosts.listByAccount(accountId) // ownership-scoped
+    },
+    async setHostStatus(hostId, status) {
+      const revokedAt = status === 'revoked' ? nowIso() : null
+      const next = await deps.hosts.swapStatus(hostId, status, revokedAt, actor)
+      if (status === 'revoked') {
+        await audit.writeAuditEvent({
+          action: 'host.revoke',
+          principalId: actor,
+          accountId: next.accountId,
+          hostId,
+          ts: nowIso(),
+          meta: { status },
+        })
+      }
+      return next
+    },
+    async ownsHost(accountId, hostId) {
+      const host = await deps.hosts.get(hostId)
+      // Deny-by-default: unknown host or account mismatch ⇒ false (INV1/INV6).
+      return host !== null && host.accountId === accountId
+    },
+    async touchLastSeen(hostId) {
+      await deps.hosts.touchLastSeen(hostId, nowIso()) // advisory, not versioned (INV7)
+    },
+  }
+}

control-plane/src/registry/sessions.ts

@@ -0,0 +1,49 @@
+/**
+ * T5 — session registry. `account_id` is DENORMALIZED from the host at write time — NEVER
+ * supplied by the caller/client (INV3) — giving an O(1) deny-by-default authz fact for reattach
+ * (INV6). `sessionAccount` returns that server-derived owner; it never echoes a client value.
+ */
+import type { SessionRecord } from '../model/records.js'
+import type { HostStore, SessionStore } from '../store/ports.js'
+import { nowIso } from '../util/ids.js'
+
+export interface RecordSessionInput {
+  readonly sessionId: string
+  readonly hostId: string
+}
+
+export interface SessionRegistry {
+  recordSession(input: RecordSessionInput): Promise<SessionRecord>
+  getSession(sessionId: string): Promise<SessionRecord | null>
+  sessionAccount(sessionId: string): Promise<string | null>
+}
+
+export interface SessionRegistryDeps {
+  readonly sessions: SessionStore
+  readonly hosts: HostStore
+}
+
+export function createSessionRegistry(deps: SessionRegistryDeps): SessionRegistry {
+  return {
+    async recordSession(input) {
+      const host = await deps.hosts.get(input.hostId)
+      if (host === null) throw new Error('cannot record session for unknown host')
+      const rec: SessionRecord = {
+        sessionId: input.sessionId,
+        hostId: input.hostId,
+        accountId: host.accountId, // derived from the host — caller cannot influence (INV3)
+        createdAt: nowIso(),
+        lastAttachAt: nowIso(),
+      }
+      await deps.sessions.insert(rec)
+      return rec
+    },
+    async getSession(sessionId) {
+      return deps.sessions.get(sessionId)
+    },
+    async sessionAccount(sessionId) {
+      const s = await deps.sessions.get(sessionId)
+      return s?.accountId ?? null // O(1) authz fact; server-derived, never client-supplied
+    },
+  }
+}