@linkshell/gateway 0.5.3 → 0.6.0

package/src/relay.ts

@@ -1,669 +1,484 @@
-import type WebSocket from "ws";
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import type { Duplex } from "node:stream";
+import WebSocket, { WebSocketServer } from "ws";
 import {
-  agentV2MessageRoute,
-  isProtocolVersionCompatible,
-  parseEnvelope,
-  parseTypedPayload,
-  protocolMessageSchemas,
-  serializeEnvelope,
-  createEnvelope,
-} from "@linkshell/protocol";
-import type { Envelope, ProtocolMessageType } from "@linkshell/protocol";
-import { ZodError } from "zod";
-import type { SessionManager, ConnectedDevice } from "./sessions.js";
-import {
-  handleTunnelResponse,
-  handleTunnelWsData,
-  handleTunnelWsClose,
-} from "./tunnel.js";
-
-export function handleSocketMessage(
-  socket: WebSocket,
-  raw: string,
-  role: "host" | "client",
-  sessionId: string,
-  deviceId: string,
-  sessions: SessionManager,
-): void {
-  let envelope: Envelope;
-  try {
-    envelope = parseEnvelope(raw);
-  } catch {
-    sendSessionError(socket, sessionId, "invalid_message", "Failed to parse envelope");
-    return;
-  }
-
-  if (envelope.sessionId !== sessionId) {
-    sendSessionError(
-      socket,
-      sessionId,
-      "invalid_message",
-      "Envelope sessionId does not match connection sessionId",
-    );
-    return;
-  }
-
-  const session = sessions.get(sessionId);
-  if (!session) {
-    sendSessionError(socket, sessionId, "session_not_found", "Session not found");
-    return;
-  }
+  clientFrameSchema,
+  gatewayChallengeMessage,
+  idOf,
+  RELAY_PATH,
+  verifySignature,
+  type DeviceEntry,
+  type MachineEntry,
+  type PeerRole,
+  type RelayEvents,
+  type ServerFrame,
+} from "@linkshell/wire";
+import type { VerifyToken } from "./accounts.js";
+import { GatewayStore, type PeerRecord } from "./store.js";
 
-  try {
-    if (shouldValidatePayloadAtGateway(envelope.type)) {
-      envelope = {
-        ...envelope,
-        payload: parseTypedPayload(envelope.type, envelope.payload),
-      };
-    }
-
-    if (role === "host") {
-      handleHostMessage(envelope, session, sessions);
-    } else {
-      handleClientMessage(envelope, socket, session, deviceId, sessions);
-    }
-  } catch (error) {
-    if (error instanceof ZodError) {
-      sendSessionError(
-        socket,
-        sessionId,
-        "invalid_message",
-        error.errors[0]?.message ?? "Invalid message payload",
-      );
-      return;
-    }
-    sendSessionError(socket, sessionId, "invalid_message", "Failed to handle message");
-  }
+export interface GatewayOptions {
+  port: number;
+  host?: string;
+  databasePath: string;
+  /** Validates account tokens; without it, accounts are off and only pairing works. */
+  verifyToken?: VerifyToken;
+  log?: (message: string) => void;
+  /** Called with every frame the gateway routes, for tests that check it only sees ciphertext. */
+  onRouted?: (frame: string) => void;
+  pairingTtlMs?: number;
+  heartbeatMs?: number;
+  /**
+   * Final say on a connecting peer, after its key (and token, if any) checked
+   * out: return a message to refuse it. The official gateway uses this to
+   * require a subscription for computers.
+   */
+  admit?: (peer: { role: PeerRole; userId?: string }) => Promise<string | undefined>;
+  /**
+   * How much may wait to be written to one peer before the gateway stops
+   * reading from whoever is sending to it (default 4 MB), and how long a peer
+   * may stay that far behind before it is dropped (default 60 s).
+   */
+  maxBufferedBytes?: number;
+  stalledPeerMs?: number;
 }
 
-function isProtocolMessageType(type: string): type is ProtocolMessageType {
-  return Object.prototype.hasOwnProperty.call(protocolMessageSchemas, type);
+interface Peer {
+  record: PeerRecord;
+  socket: WebSocket;
+  email?: string;
+  /** Not being read: a peer it sends to can't keep up. */
+  held?: boolean;
 }
 
-function shouldValidatePayloadAtGateway(type: string): type is ProtocolMessageType {
-  if (agentV2MessageRoute(type) !== null) return false;
-  return isProtocolMessageType(type);
+interface Offer {
+  code: string;
+  machineId: string;
+  expiresAt: number;
+  attempts: number;
 }
 
-function sendSessionError(
-  socket: WebSocket,
-  sessionId: string,
-  code: string,
-  message: string,
-): void {
-  if (socket.readyState !== socket.OPEN) return;
-  socket.send(
-    serializeEnvelope(
-      createEnvelope({
-        type: "session.error",
-        sessionId,
-        payload: { code, message },
-      }),
-    ),
-  );
+class RelayError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
 }
 
-type AgentConversationLike = {
-  id: string;
-  status?: string;
-  provider?: string;
-  title?: string;
-  lastMessagePreview?: string;
-  lastActivityAt?: number;
-  usage?: {
-    inputTokens?: number;
-    outputTokens?: number;
-    cacheReadTokens?: number;
-    totalTokens?: number;
-    contextWindow?: number;
-    totalCostUsd?: number;
-  };
-};
-
-function truncateDetail(text: string, max = 72): string {
-  const line = text.replace(/\s+/g, " ").trim();
-  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
-}
+const AUTH_TIMEOUT_MS = 10_000;
+const PAIR_DECISION_MS = 30_000;
+const MAX_CLAIM_ATTEMPTS = 8;
 
-function commandOrPathFromToolInput(toolInput?: string): { command?: string; path?: string } {
-  if (!toolInput) return {};
-  try {
-    const parsed = JSON.parse(toolInput) as Record<string, unknown>;
-    if (parsed && typeof parsed === "object") {
-      return {
-        command: typeof parsed.command === "string" ? parsed.command : undefined,
-        path: typeof parsed.path === "string"
-          ? parsed.path
-          : typeof parsed.file_path === "string"
-            ? parsed.file_path
-            : undefined,
-      };
-    }
-  } catch {
-    const match = toolInput.match(/\$\s+([^\n]+)/);
-    if (match?.[1]) return { command: match[1].trim() };
+/**
+ * Gateway v2: authenticates peers by key, routes their end-to-end encrypted
+ * frames to peers they may reach (paired, or same account), and brokers
+ * pairing. It has no way to read what it routes.
+ */
+export class Gateway {
+  readonly store: GatewayStore;
+  private server?: Server;
+  private readonly peers = new Map<string, Peer>();
+  private readonly offers = new Map<string, Offer>();
+  private readonly decisions = new Map<string, { machineId: string; resolve: (accept: boolean) => void }>();
+  private readonly claimTimes = new Map<string, number[]>();
+  private heartbeat?: ReturnType<typeof setInterval>;
+  /** Sockets that answered the last ping. */
+  private readonly alive = new WeakSet<WebSocket>();
+  private stopped = false;
+  private readonly log: (message: string) => void;
+
+  constructor(private readonly options: GatewayOptions) {
+    this.store = new GatewayStore(options.databasePath);
+    this.log = options.log ?? ((message) => process.stderr.write(`${new Date().toISOString()} [gateway] ${message}\n`));
   }
-  return {};
-}
 
-/** List-line for a live permission request: "运行命令 · pnpm test". */
-function permissionAttentionDetail(p: {
-  toolName?: string;
-  toolInput?: string;
-  context?: string;
-}): string | undefined {
-  const { command, path } = commandOrPathFromToolInput(p.toolInput);
-  const name = (p.toolName ?? "").toLowerCase();
-  if (command) {
-    return truncateDetail(
-      /bash|shell|command/.test(name) || !p.toolName
-        ? `运行命令 · ${command}`
-        : `${p.toolName} · ${command}`,
-    );
+  private readonly wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: 48 * 1024 * 1024 });
+
+  /** Runs on its own port. */
+  async start(): Promise<number> {
+    const server = createServer((request, response) => {
+      if (request.url === "/healthz") {
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify({ ok: true, peers: this.peers.size }));
+        return;
+      }
+      response.writeHead(404);
+      response.end();
+    });
+    server.on("upgrade", (request: IncomingMessage, socket, head) => {
+      if (!request.url?.startsWith(RELAY_PATH)) {
+        socket.destroy();
+        return;
+      }
+      this.handleUpgrade(request, socket, head);
+    });
+    this.server = server;
+    await new Promise<void>((resolve) => server.listen(this.options.port, this.options.host ?? "0.0.0.0", resolve));
+    this.attach();
+    const address = server.address();
+    return typeof address === "object" && address ? address.port : this.options.port;
   }
-  if (path) {
-    const leaf = path.split("/").filter(Boolean).pop() ?? path;
-    if (/write|edit|multiedit/.test(name)) return truncateDetail(`改文件 · ${leaf}`);
-    if (/(^|_)read(_|$)|readfile/.test(name)) return truncateDetail(`读取 · ${leaf}`);
-    return truncateDetail(`${p.toolName || "文件"} · ${leaf}`);
+
+  /**
+   * Runs inside another HTTP server, which passes it upgrades for
+   * `RELAY_PATH` through `handleUpgrade`.
+   */
+  attach(): void {
+    if (this.heartbeat) return;
+    this.heartbeat = setInterval(() => this.sweep(), this.options.heartbeatMs ?? 30_000);
+    this.heartbeat.unref();
   }
-  if (p.context?.trim()) return truncateDetail(p.context.trim());
-  if (p.toolName) return truncateDetail(`需要授权 · ${p.toolName}`);
-  return undefined;
-}
 
-function conversationAttentionDetail(
-  conversation: AgentConversationLike | undefined,
-  status: string | undefined,
-  current?: { agentStatus?: string; agentDetail?: string },
-): string | null | undefined {
-  if (status === "waiting_permission") {
-    if (current?.agentStatus === "waiting_permission" && current.agentDetail) return undefined;
-    return conversation?.lastMessagePreview;
+  handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): void {
+    this.wss.handleUpgrade(request, socket, head, (ws) => this.accept(ws));
   }
-  if (status === "running" || status === "error") {
-    return conversation?.lastMessagePreview ?? null;
+
+  get connected(): number {
+    return this.peers.size;
   }
-  return status ? null : undefined;
-}
 
-function pickConversationSummary(
-  conversations: AgentConversationLike[],
-  activeConversationId?: string,
-): AgentConversationLike | undefined {
-  const active = conversations.find((c) => c.id === activeConversationId);
-  if (active) return active;
-  const waiting = conversations.find((c) => c.status === "waiting_permission");
-  if (waiting) return waiting;
-  const running = conversations.find((c) => c.status === "running");
-  if (running) return running;
-  return [...conversations].sort((a, b) => (b.lastActivityAt ?? 0) - (a.lastActivityAt ?? 0))[0];
-}
+  /** Bytes accepted from senders and not yet written to their receivers. */
+  get bufferedBytes(): number {
+    let total = 0;
+    for (const peer of this.peers.values()) total += peer.socket.bufferedAmount;
+    return total;
+  }
 
-function aggregateAgentStatus(conversations: AgentConversationLike[], fallback?: string): string | undefined {
-  if (conversations.some((c) => c.status === "waiting_permission")) return "waiting_permission";
-  if (conversations.some((c) => c.status === "running")) return "running";
-  return fallback;
-}
+  /** Drops connections that didn't answer the previous ping, pings the rest. */
+  private sweep(): void {
+    for (const peer of this.peers.values()) {
+      // A held peer isn't read, so its pong can't arrive; it is checked again once released.
+      if (peer.held) continue;
+      if (!this.alive.has(peer.socket)) {
+        peer.socket.terminate();
+        continue;
+      }
+      this.alive.delete(peer.socket);
+      peer.socket.ping();
+    }
+  }
 
-function agentStatusFromTerminalPhase(phase: string): string | undefined {
-  switch (phase) {
-    case "thinking":
-    case "tool_use":
-    case "outputting":
-      return "running";
-    case "waiting":
-      return "waiting_permission";
-    case "idle":
-      return "idle";
-    case "error":
-      return "error";
-    default:
-      return undefined;
+  async stop(): Promise<void> {
+    this.stopped = true;
+    clearInterval(this.heartbeat);
+    for (const peer of this.peers.values()) peer.socket.terminate();
+    await new Promise<void>((resolve) => (this.server ? this.server.close(() => resolve()) : resolve()));
+    this.store.close();
   }
-}
 
-function terminalStatusTitle(payload: { phase: string; toolName?: string; summary?: string }): string {
-  if (payload.toolName) return `外部终端 · ${payload.toolName}`;
-  if (payload.summary) return `外部终端 · ${payload.summary}`;
-  return "外部终端";
-}
+  // ── connection ────────────────────────────────────────────────────
 
-function shouldPromoteTerminalStatus(status: string, current?: string): boolean {
-  if (status !== "idle") return true;
-  return current !== "running" && current !== "waiting_permission";
-}
+  private accept(socket: WebSocket): void {
+    this.alive.add(socket);
+    socket.on("pong", () => this.alive.add(socket));
+    const nonce = randomBytes(32).toString("base64url");
+    let peer: Peer | undefined;
+    const send = (frame: ServerFrame) => {
+      if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(frame));
+    };
+    const timer = setTimeout(() => {
+      if (!peer) socket.close(4001, "auth timeout");
+    }, AUTH_TIMEOUT_MS);
+    send({ t: "challenge", nonce });
 
-function cacheAgentEnvelope(envelope: Envelope, sessions: SessionManager): void {
-  try {
-    if (envelope.type === "agent.v2.conversation.list.result") {
-      const p = parseTypedPayload("agent.v2.conversation.list.result", envelope.payload);
-      const picked = pickConversationSummary(p.conversations);
-      const status = aggregateAgentStatus(p.conversations, picked?.status ?? "idle");
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status,
-        provider: picked?.provider,
-        conversationId: picked?.id,
-        title: picked?.title,
-        detail: conversationAttentionDetail(picked, status, sessions.get(envelope.sessionId)),
-        lastActivity: picked?.lastActivityAt ?? Date.now(),
-        usage: picked?.usage ?? null,
-      });
-      return;
-    }
-    if (envelope.type === "agent.v2.conversation.opened") {
-      const p = parseTypedPayload("agent.v2.conversation.opened", envelope.payload);
-      const conversation = p.conversation;
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status: conversation.status,
-        provider: conversation.provider,
-        conversationId: conversation.id,
-        title: conversation.title,
-        detail: conversationAttentionDetail(conversation, conversation.status, sessions.get(envelope.sessionId)),
-        lastActivity: conversation.lastActivityAt ?? Date.now(),
-        usage: conversation.usage ?? null,
-      });
-      return;
-    }
-    if (envelope.type === "agent.v2.snapshot") {
-      const p = parseTypedPayload("agent.v2.snapshot", envelope.payload);
-      const picked = pickConversationSummary(p.conversations, p.activeConversationId);
-      const status = aggregateAgentStatus(p.conversations, picked?.status ?? "idle");
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status,
-        provider: picked?.provider,
-        conversationId: picked?.id ?? p.activeConversationId,
-        title: picked?.title,
-        detail: conversationAttentionDetail(picked, status, sessions.get(envelope.sessionId)),
-        lastActivity: picked?.lastActivityAt ?? Date.now(),
-        usage: picked?.usage ?? null,
-      });
-      return;
-    }
-    if (envelope.type === "agent.v2.event") {
-      const p = parseTypedPayload("agent.v2.event", envelope.payload);
-      const current = sessions.get(envelope.sessionId);
-      if (p.conversation) {
-        sessions.cacheAgentSummary(envelope.sessionId, {
-          status: p.conversation.status,
-          provider: p.conversation.provider,
-          conversationId: p.conversation.id,
-          title: p.conversation.title,
-          detail: conversationAttentionDetail(p.conversation, p.conversation.status, current),
-          lastActivity: p.conversation.lastActivityAt,
-          usage: p.conversation.usage ?? null,
-        });
-      } else if (p.patch?.status) {
-        sessions.cacheAgentSummary(envelope.sessionId, {
-          status: p.patch.status,
-          conversationId: p.conversationId,
-          detail: conversationAttentionDetail(undefined, p.patch.status, current),
-          lastActivity: Date.now(),
-        });
+    socket.on("message", async (data) => {
+      let parsed;
+      try {
+        parsed = clientFrameSchema.safeParse(JSON.parse(data.toString()));
+      } catch {
+        parsed = undefined;
       }
-      return;
-    }
-    if (envelope.type === "agent.v2.permission.request") {
-      const p = parseTypedPayload("agent.v2.permission.request", envelope.payload);
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status: "waiting_permission",
-        conversationId: p.conversationId,
-        detail: permissionAttentionDetail(p),
-        lastActivity: Date.now(),
-      });
-      return;
-    }
-    if (envelope.type === "agent.snapshot") {
-      const p = parseTypedPayload("agent.snapshot", envelope.payload);
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status: p.status,
-        conversationId: p.agentSessionId,
-        lastActivity: Date.now(),
-      });
-      return;
-    }
-    if (envelope.type === "agent.update") {
-      const p = parseTypedPayload("agent.update", envelope.payload);
-      if (p.status) {
-        sessions.cacheAgentSummary(envelope.sessionId, {
-          status: p.status,
-          conversationId: p.agentSessionId,
-          lastActivity: Date.now(),
-        });
+      if (!parsed?.success) {
+        send({ t: "error", code: "bad_frame", message: "unreadable frame" });
+        return;
       }
-      return;
-    }
-    if (envelope.type === "agent.permission.request") {
-      const p = parseTypedPayload("agent.permission.request", envelope.payload);
-      sessions.cacheAgentSummary(envelope.sessionId, {
-        status: "waiting_permission",
-        conversationId: p.agentSessionId,
-        detail: permissionAttentionDetail(p),
-        lastActivity: Date.now(),
-      });
-      return;
-    }
-    if (envelope.type === "terminal.status") {
-      const p = parseTypedPayload("terminal.status", envelope.payload);
-      const status = agentStatusFromTerminalPhase(p.phase);
-      const currentStatus = sessions.get(envelope.sessionId)?.agentStatus;
-      if (status && shouldPromoteTerminalStatus(status, currentStatus)) {
-        sessions.cacheAgentSummary(envelope.sessionId, {
-          status,
-          provider: p.provider ?? null,
-          conversationId: null,
-          title: terminalStatusTitle(p),
-          lastActivity: Date.now(),
-        });
+      const frame = parsed.data;
+      if (!peer) {
+        if (frame.t !== "auth") {
+          socket.close(4001, "auth first");
+          return;
+        }
+        try {
+          peer = await this.authenticate(frame, nonce, socket);
+        } catch (error) {
+          const code = error instanceof RelayError ? error.code : "auth_failed";
+          send({ t: "error", code, message: error instanceof Error ? error.message : String(error) });
+          socket.close(4001, code);
+          return;
+        }
+        clearTimeout(timer);
+        send({ t: "ready", userId: peer.record.userId, email: peer.email });
+        this.announce(peer.record, true);
+        return;
+      }
+      switch (frame.t) {
+        case "ping":
+          send({ t: "pong" });
+          return;
+        case "to":
+          this.route(peer, frame.to, frame.d);
+          return;
+        case "req":
+          try {
+            const result = await this.handle(peer, frame.method, (frame.params ?? {}) as Record<string, unknown>);
+            send({ t: "res", id: frame.id, result });
+          } catch (error) {
+            const code = error instanceof RelayError ? error.code : "internal";
+            send({ t: "res", id: frame.id, error: { code, message: error instanceof Error ? error.message : String(error) } });
+          }
+          return;
+        case "auth":
+          return;
       }
-      return;
+    });
+
+    socket.on("close", () => {
+      clearTimeout(timer);
+      if (this.stopped || !peer || this.peers.get(peer.record.id)?.socket !== socket) return;
+      this.peers.delete(peer.record.id);
+      this.store.touch(peer.record.id);
+      this.announce(peer.record, false);
+    });
+  }
+
+  private async authenticate(frame: Extract<import("@linkshell/wire").ClientFrame, { t: "auth" }>, nonce: string, socket: WebSocket) {
+    const { identity, role } = frame;
+    if (idOf(identity.signKey) !== identity.id) throw new RelayError("bad_identity", "id doesn't match key");
+    if (!verifySignature(identity.signKey, gatewayChallengeMessage(nonce), frame.signature)) {
+      throw new RelayError("bad_signature", "signature check failed");
     }
-    if (envelope.type === "agent.v2.usage.report") {
-      // Cache the full usage report on the session so the session-list page
-      // (HTTP /sessions) can show summary cards without a WebSocket connection.
-      const session = sessions.get(envelope.sessionId);
-      if (session) session.agentUsageReport = envelope.payload;
-      return;
+    const existing = this.store.peer(identity.id);
+    if (existing && existing.role !== role) throw new RelayError("bad_identity", "this key is registered with another role");
+    let userId: string | undefined;
+    let email: string | undefined;
+    if (frame.token) {
+      if (!this.options.verifyToken) throw new RelayError("accounts_disabled", "this gateway doesn't support accounts");
+      const account = await this.options.verifyToken(frame.token);
+      if (!account) throw new RelayError("token_invalid", "account token is invalid or expired");
+      userId = account.userId;
+      email = account.email;
     }
-  } catch {
-    // Agent summaries are best-effort; never block relay on a status parse.
+    const refusal = await this.options.admit?.({ role: role as PeerRole, userId });
+    if (refusal) throw new RelayError("not_admitted", refusal);
+    const record: PeerRecord = {
+      id: identity.id,
+      role: role as PeerRole,
+      signKey: identity.signKey,
+      boxKey: identity.boxKey,
+      name: frame.name,
+      platform: frame.platform,
+      userId,
+      lastSeen: Date.now(),
+    };
+    this.store.upsertPeer(record);
+    const previous = this.peers.get(record.id);
+    const peer: Peer = { record, socket, email };
+    this.peers.set(record.id, peer);
+    // One live connection per identity: the newest wins.
+    previous?.socket.close(4000, "replaced by a newer connection");
+    this.log(`${role} ${record.id.slice(0, 8)} "${record.name}" online${userId ? " (account)" : ""}`);
+    return peer;
   }
-}
 
-function handleHostMessage(
-  envelope: Envelope,
-  session: ReturnType<SessionManager["get"]> & {},
-  sessions: SessionManager,
-): void {
-  if (agentV2MessageRoute(envelope.type) === "host_to_client") {
-    cacheAgentEnvelope(envelope, sessions);
-    sessions.bufferAgentEnvelope(session.id, envelope);
-    broadcastToClients(session, envelope);
-    return;
+  // ── routing ───────────────────────────────────────────────────────
+
+  private route(from: Peer, to: string, data: string): void {
+    const via = this.store.route(from.record.id, to);
+    const target = this.peers.get(to);
+    const undeliverable = (reason: string) =>
+      from.socket.send(JSON.stringify({ t: "undeliverable", to, reason } satisfies ServerFrame));
+    if (!via) return undeliverable("not_allowed");
+    if (!target) return undeliverable("offline");
+    const frame = JSON.stringify({
+      t: "from",
+      from: { id: from.record.id, signKey: from.record.signKey, boxKey: from.record.boxKey },
+      via,
+      d: data,
+    } satisfies ServerFrame);
+    this.options.onRouted?.(frame);
+    target.socket.send(frame);
+    this.holdWhileBehind(from, target);
   }
 
-  switch (envelope.type) {
-    case "session.connect": {
-      // Extract metadata from host's connect message
-      const p = parseTypedPayload("session.connect", envelope.payload);
-      // Non-breaking version negotiation: warn (never disconnect) when a host
-      // advertises an incompatible protocol version. CLI and app update
-      // independently, so an out-of-date peer must keep working in degraded
-      // mode rather than being rejected.
-      if (!isProtocolVersionCompatible(p.protocolVersion)) {
-        process.stderr.write(
-          `[gateway] host on session ${session.id} advertises protocol v${p.protocolVersion}, ` +
-          `which is older than the minimum compatible version — continuing in degraded mode\n`,
-        );
+  /**
+   * Backpressure. What a peer can't take yet would otherwise pile up here, in
+   * memory every user of this gateway shares: stop reading the sender instead,
+   * so the data waits on its side until the receiver catches up.
+   */
+  private holdWhileBehind(from: Peer, target: Peer): void {
+    const limit = this.options.maxBufferedBytes ?? 4 * 1024 * 1024;
+    if (from.held || target.socket.bufferedAmount <= limit) return;
+    from.held = true;
+    from.socket.pause();
+    const since = Date.now();
+    const timer = setInterval(() => {
+      const open = target.socket.readyState === WebSocket.OPEN;
+      if (open && target.socket.bufferedAmount > limit / 4) {
+        if (Date.now() - since < (this.options.stalledPeerMs ?? 60_000)) return;
+        this.log(`${target.record.role} ${target.record.id.slice(0, 8)} can't keep up; dropping it`);
+        target.socket.terminate();
       }
-      if (p.provider || p.machineId || p.hostname || p.platform || p.cwd || p.projectName) {
-        sessions.setMetadata(
-          session.id,
-          p.provider ?? undefined,
-          p.machineId ?? undefined,
-          p.hostname ?? undefined,
-          p.platform ?? undefined,
-          p.cwd ?? undefined,
-          p.projectName ?? undefined,
-        );
-      }
-      break;
-    }
-    case "terminal.output": {
-      sessions.bufferOutput(session.id, envelope);
-      broadcastToClients(session, envelope);
-      break;
-    }
-    case "terminal.exit": {
-      // Don't terminate session — other terminals may still be running
-      broadcastToClients(session, envelope);
-      break;
-    }
-    case "session.heartbeat":
-      break;
-    case "permission.decision.result": {
-      broadcastToClients(session, envelope);
-      break;
-    }
-    // Tunnel: host → gateway (not broadcast to clients)
-    case "tunnel.response": {
-      const p = parseTypedPayload("tunnel.response", envelope.payload);
-      handleTunnelResponse(p);
-      return;
-    }
-    case "tunnel.ws.data": {
-      const p = parseTypedPayload("tunnel.ws.data", envelope.payload);
-      handleTunnelWsData(p);
-      return;
-    }
-    case "tunnel.ws.close": {
-      const p = parseTypedPayload("tunnel.ws.close", envelope.payload);
-      handleTunnelWsClose(p);
-      return;
-    }
-    case "control.grant":
-    case "control.reject":
-      broadcastToClients(session, envelope);
-      break;
-    // Screen sharing: host → clients
-    case "screen.frame":
-    case "screen.status":
-    case "screen.offer":
-    case "screen.ice":
-    // Agent GUI: host → clients
-    case "agent.capabilities":
-    case "agent.update":
-    case "agent.permission.request":
-    case "agent.snapshot":
-      cacheAgentEnvelope(envelope, sessions);
-      broadcastToClients(session, envelope);
-      break;
-    // Multi-terminal: host → clients
-    case "terminal.spawned":
-    case "terminal.list":
-    case "terminal.browse.result":
-    case "terminal.file.read.result":
-      broadcastToClients(session, envelope);
-      break;
-    // Structured status from hooks
-    case "terminal.status":
-      cacheAgentEnvelope(envelope, sessions);
-      sessions.cacheStatus(session.id, envelope);
-      broadcastToClients(session, envelope);
-      break;
-    default:
-      broadcastToClients(session, envelope);
-      break;
+      clearInterval(timer);
+      from.held = false;
+      this.alive.add(from.socket);
+      if (from.socket.readyState === WebSocket.OPEN) from.socket.resume();
+    }, 20);
+    timer.unref();
   }
-}
 
-function handleClientMessage(
-  envelope: Envelope,
-  socket: WebSocket,
-  session: ReturnType<SessionManager["get"]> & {},
-  deviceId: string,
-  sessions: SessionManager,
-): void {
-  const requireController = (): boolean => {
-    if (session.controllerId === deviceId) return true;
-    socket.send(
-      serializeEnvelope(
-        createEnvelope({
-          type: "session.error",
-          sessionId: session.id,
-          payload: {
-            code: "control_conflict",
-            message: "Not the controller",
-          },
-        }),
-      ),
-    );
-    return false;
-  };
-
-  const agentRoute = agentV2MessageRoute(envelope.type);
-  if (agentRoute === "client_write") {
-    if (!requireController()) return;
-    sendToHost(session, envelope);
-    return;
+  private event<N extends keyof RelayEvents>(peerId: string, name: N, data: RelayEvents[N]): void {
+    const peer = this.peers.get(peerId);
+    if (peer?.socket.readyState === WebSocket.OPEN) peer.socket.send(JSON.stringify({ t: "event", name, data } satisfies ServerFrame));
   }
-  if (agentRoute === "client_read") {
-    sendToHost(session, envelope);
-    return;
+
+  /** Tells everyone who can reach `record` that it came or went. */
+  private announce(record: PeerRecord, online: boolean): void {
+    for (const { peer } of this.store.reachable(record.id)) this.event(peer.id, "presence", { id: record.id, online });
   }
 
-  switch (envelope.type) {
-    case "terminal.input": {
-      if (!requireController()) return;
-      sendToHost(session, envelope);
-      break;
-    }
-    case "terminal.resize": {
-      if (!requireController()) return;
-      sendToHost(session, envelope);
-      break;
-    }
-    case "session.ack": {
-      // Forward ACK to host
-      sendToHost(session, envelope);
-      break;
-    }
-    case "session.resume": {
-      const p = parseTypedPayload("session.resume", envelope.payload);
-      // Replay from gateway buffer first
-      const replay = sessions.getReplayFrom(
-        session.id,
-        p.lastAckedSeqByTerminal,
-        p.lastAckedSeq,
-      );
-      for (const msg of replay) {
-        const payload = msg.payload as Record<string, unknown>;
-        socket.send(
-          serializeEnvelope(
-            createEnvelope({
-              type: "terminal.output",
-              sessionId: session.id,
-              terminalId: msg.terminalId,
-              seq: msg.seq,
-              payload: { ...payload, isReplay: true },
-            }),
-          ),
-        );
+  private machineEntry(peer: PeerRecord, via: "paired" | "account"): MachineEntry {
+    return {
+      id: peer.id,
+      signKey: peer.signKey,
+      boxKey: peer.boxKey,
+      name: peer.name,
+      platform: peer.platform,
+      online: this.peers.has(peer.id),
+      via,
+    };
+  }
+
+  private deviceEntry(peer: PeerRecord, pairedAt?: number): DeviceEntry {
+    return { id: peer.id, signKey: peer.signKey, boxKey: peer.boxKey, name: peer.name, online: this.peers.has(peer.id), pairedAt };
+  }
+
+  // ── control methods ───────────────────────────────────────────────
+
+  private async handle(peer: Peer, method: string, params: Record<string, unknown>): Promise<unknown> {
+    const role = peer.record.role;
+    const need = (wanted: PeerRole) => {
+      if (role !== wanted) throw new RelayError("forbidden", `${method} is for ${wanted}s`);
+    };
+    switch (method) {
+      case "pair.offer": {
+        need("machine");
+        for (const [code, offer] of this.offers) if (offer.machineId === peer.record.id) this.offers.delete(code);
+        let code: string;
+        do code = String(randomInt(0, 1_000_000)).padStart(6, "0");
+        while (this.offers.has(code));
+        const expiresAt = Date.now() + (this.options.pairingTtlMs ?? 10 * 60_000);
+        this.offers.set(code, { code, machineId: peer.record.id, expiresAt, attempts: 0 });
+        return { code, expiresAt };
       }
-      // Replay last terminal.status for each terminal
-      const statusReplay = sessions.getStatusReplay(session.id);
-      for (const statusMsg of statusReplay) {
-        socket.send(serializeEnvelope(statusMsg));
+      case "pair.decide": {
+        need("machine");
+        const pending = this.decisions.get(String(params.requestId));
+        if (!pending || pending.machineId !== peer.record.id) throw new RelayError("not_found", "no such pairing request");
+        pending.resolve(params.accept === true);
+        return {};
       }
-      replayAgentToSocket(socket, session.id, sessions);
-      // Also forward resume to host so it can fill gaps beyond gateway buffer.
-      sendToHost(session, session.machineId
-        ? {
-            ...envelope,
-            payload: {
-              ...(envelope.payload as Record<string, unknown>),
-              machineId: session.machineId,
-            },
-          }
-        : envelope);
-      break;
-    }
-    case "control.claim": {
-      sessions.claimControl(session.id, deviceId);
-      const grantMsg = createEnvelope({
-        type: "control.grant",
-        sessionId: session.id,
-        payload: { deviceId },
-      });
-      // Broadcast to ALL clients so previous controller updates its state
-      broadcastToClients(session, grantMsg);
-      sendToHost(session, grantMsg);
-      break;
-    }
-    case "control.release": {
-      sessions.releaseControl(session.id, deviceId);
-      const releaseMsg = createEnvelope({
-        type: "control.release",
-        sessionId: session.id,
-        payload: { deviceId },
-      });
-      broadcastToClients(session, releaseMsg);
-      sendToHost(session, releaseMsg);
-      break;
+      case "pair.claim":
+        need("device");
+        return this.claim(peer, params);
+      case "machines.list":
+        need("device");
+        return {
+          machines: this.store
+            .reachable(peer.record.id)
+            .map(({ peer: machine, via }) => this.machineEntry(machine, via))
+            .sort((a, b) => Number(b.online) - Number(a.online) || a.name.localeCompare(b.name)),
+        };
+      case "machines.forget": {
+        need("device");
+        const machineId = String(params.machineId ?? "");
+        const unpaired = this.store.unlink(machineId, peer.record.id);
+        if (unpaired) this.event(machineId, "presence", { id: peer.record.id, online: false });
+        // A computer that is listed because it signed in to this account, and is gone (reinstalled,
+        // given away): taken off the account, so the list stops showing it. One that is connected
+        // stays: it is signed in right now, and would only be back at once.
+        const machine = this.store.peer(machineId);
+        const ours = machine?.role === "machine" && peer.record.userId !== undefined && machine.userId === peer.record.userId;
+        if (ours && !this.peers.has(machineId)) this.store.disown(machineId);
+        return {};
+      }
+      case "devices.list":
+        need("machine");
+        return {
+          devices: this.store.reachable(peer.record.id).map(({ peer: device, pairedAt }) => this.deviceEntry(device, pairedAt)),
+        };
+      case "devices.revoke": {
+        need("machine");
+        const deviceId = String(params.deviceId ?? "");
+        if (this.store.unlink(peer.record.id, deviceId)) {
+          this.event(deviceId, "machines.changed", {});
+          this.peers.get(deviceId)?.socket.close(4003, "unpaired");
+        }
+        return {};
+      }
+      default:
+        throw new RelayError("unknown_method", `unknown method ${method}`);
     }
-    case "session.heartbeat":
-      break;
-    // Screen sharing: client → host
-    case "screen.start":
-    case "screen.stop":
-    case "screen.answer":
-    case "screen.ice":
-    case "agent.session.new":
-    case "agent.session.load":
-    case "agent.prompt":
-    case "agent.cancel":
-    case "agent.permission.response":
-    // Multi-terminal write ops: client → host (require controller)
-    case "terminal.spawn":
-    case "terminal.kill":
-    case "terminal.mkdir":
-    case "file.upload":
-    case "permission.decision":
-      if (!requireController()) return;
-      sendToHost(session, envelope);
-      break;
-    // Read-only ops: any client may issue (no controller gate)
-    case "terminal.list":
-    case "terminal.browse":
-    case "terminal.file.read":
-    case "terminal.history.request":
-    case "agent.initialize":
-    case "agent.session.list":
-      sendToHost(session, envelope);
-      break;
-    default:
-      sendToHost(session, envelope);
-      break;
   }
-}
 
-/** Skip clients whose send buffer exceeds this, so one slow/stalled client
- *  can't grow gateway memory without bound (backpressure). */
-const MAX_CLIENT_BUFFER_BYTES = 8 * 1024 * 1024; // 8MB
-
-function broadcastToClients(
-  session: ReturnType<SessionManager["get"]> & {},
-  envelope: Envelope,
-): void {
-  const data = serializeEnvelope(envelope);
-  for (const [, client] of session.clients) {
-    if (client.socket.readyState !== client.socket.OPEN) continue;
-    if (client.socket.bufferedAmount > MAX_CLIENT_BUFFER_BYTES) continue;
-    client.socket.send(data);
-  }
-}
+  private async claim(device: Peer, params: Record<string, unknown>): Promise<{ machine: MachineEntry }> {
+    // Throttle guessing: a handful of claims per device per minute.
+    const now = Date.now();
+    const recent = (this.claimTimes.get(device.record.id) ?? []).filter((t) => now - t < 60_000);
+    if (recent.length >= 6) throw new RelayError("rate_limited", "too many pairing attempts, wait a minute");
+    this.claimTimes.set(device.record.id, [...recent, now]);
 
-/** Replay the last agent snapshot + recent host→client agent envelopes. */
-export function replayAgentToSocket(
-  socket: WebSocket,
-  sessionId: string,
-  sessions: SessionManager,
-): void {
-  if (socket.readyState !== socket.OPEN) return;
-  for (const envelope of sessions.getAgentReplay(sessionId)) {
-    if (socket.bufferedAmount > MAX_CLIENT_BUFFER_BYTES) break;
-    socket.send(serializeEnvelope(envelope));
-  }
-}
+    const code = typeof params.code === "string" ? params.code.replace(/\D/g, "") : undefined;
+    const machineId = typeof params.machineId === "string" ? params.machineId : undefined;
+    const offer = code
+      ? this.offers.get(code)
+      : [...this.offers.values()].find((candidate) => candidate.machineId === machineId);
+    if (!offer || offer.expiresAt < now) {
+      if (offer) this.offers.delete(offer.code);
+      throw new RelayError("pairing_expired", "this pairing code is wrong or has expired");
+    }
+    if (++offer.attempts > MAX_CLAIM_ATTEMPTS) {
+      this.offers.delete(offer.code);
+      throw new RelayError("pairing_expired", "too many attempts on this code; start pairing again");
+    }
+    const machine = this.peers.get(offer.machineId);
+    if (!machine) throw new RelayError("machine_offline", "the computer is offline");
 
-function sendToHost(
-  session: ReturnType<SessionManager["get"]> & {},
-  envelope: Envelope,
-): void {
-  if (
-    session.host &&
-    session.host.socket.readyState === session.host.socket.OPEN
-  ) {
-    session.host.socket.send(serializeEnvelope(envelope));
+    // The machine checks the proof (it holds the QR secret) and decides.
+    const requestId = randomUUID();
+    const accepted = await new Promise<boolean>((resolve) => {
+      const timer = setTimeout(() => {
+        this.decisions.delete(requestId);
+        resolve(false);
+      }, PAIR_DECISION_MS);
+      this.decisions.set(requestId, {
+        machineId: machine.record.id,
+        resolve: (accept) => {
+          clearTimeout(timer);
+          this.decisions.delete(requestId);
+          resolve(accept);
+        },
+      });
+      this.event(machine.record.id, "pair.request", {
+        requestId,
+        device: { id: device.record.id, signKey: device.record.signKey, boxKey: device.record.boxKey, name: device.record.name },
+        proof: String(params.proof ?? ""),
+        code: offer.code,
+      });
+    });
+    if (!accepted) {
+      this.event(machine.record.id, "pair.done", { requestId, accepted: false });
+      throw new RelayError("pairing_refused", "the computer refused this pairing");
+    }
+    this.offers.delete(offer.code);
+    this.store.link(machine.record.id, device.record.id);
+    this.event(machine.record.id, "pair.done", {
+      requestId,
+      accepted: true,
+      device: this.deviceEntry(device.record, Date.now()),
+    });
+    this.log(`paired device ${device.record.id.slice(0, 8)} with machine ${machine.record.id.slice(0, 8)}`);
+    return { machine: this.machineEntry(machine.record, "paired") };
   }
 }