@linkshell/gateway 0.5.2 → 0.6.0

package/dist/gateway/src/relay.js

@@ -1,561 +1,434 @@
-import { agentV2MessageRoute, isProtocolVersionCompatible, parseEnvelope, parseTypedPayload, protocolMessageSchemas, serializeEnvelope, createEnvelope, } from "@linkshell/protocol";
-import { ZodError } from "zod";
-import { handleTunnelResponse, handleTunnelWsData, handleTunnelWsClose, } from "./tunnel.js";
-export function handleSocketMessage(socket, raw, role, sessionId, deviceId, sessions) {
-    let envelope;
-    try {
-        envelope = parseEnvelope(raw);
+import { createServer } from "node:http";
+import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import WebSocket, { WebSocketServer } from "ws";
+import { clientFrameSchema, gatewayChallengeMessage, idOf, RELAY_PATH, verifySignature, } from "@linkshell/wire";
+import { GatewayStore } from "./store.js";
+class RelayError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
     }
-    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;
+}
+const AUTH_TIMEOUT_MS = 10_000;
+const PAIR_DECISION_MS = 30_000;
+const MAX_CLAIM_ATTEMPTS = 8;
+/**
+ * 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 {
+    options;
+    store;
+    server;
+    peers = new Map();
+    offers = new Map();
+    decisions = new Map();
+    claimTimes = new Map();
+    heartbeat;
+    /** Sockets that answered the last ping. */
+    alive = new WeakSet();
+    stopped = false;
+    log;
+    constructor(options) {
+        this.options = options;
+        this.store = new GatewayStore(options.databasePath);
+        this.log = options.log ?? ((message) => process.stderr.write(`${new Date().toISOString()} [gateway] ${message}\n`));
     }
-    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);
-        }
+    wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: 48 * 1024 * 1024 });
+    /** Runs on its own port. */
+    async start() {
+        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, socket, head) => {
+            if (!request.url?.startsWith(RELAY_PATH)) {
+                socket.destroy();
+                return;
+            }
+            this.handleUpgrade(request, socket, head);
+        });
+        this.server = server;
+        await new Promise((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;
     }
-    catch (error) {
-        if (error instanceof ZodError) {
-            sendSessionError(socket, sessionId, "invalid_message", error.errors[0]?.message ?? "Invalid message payload");
+    /**
+     * Runs inside another HTTP server, which passes it upgrades for
+     * `RELAY_PATH` through `handleUpgrade`.
+     */
+    attach() {
+        if (this.heartbeat)
             return;
-        }
-        sendSessionError(socket, sessionId, "invalid_message", "Failed to handle message");
+        this.heartbeat = setInterval(() => this.sweep(), this.options.heartbeatMs ?? 30_000);
+        this.heartbeat.unref();
     }
-}
-function isProtocolMessageType(type) {
-    return Object.prototype.hasOwnProperty.call(protocolMessageSchemas, type);
-}
-function shouldValidatePayloadAtGateway(type) {
-    if (agentV2MessageRoute(type) !== null)
-        return false;
-    return isProtocolMessageType(type);
-}
-function sendSessionError(socket, sessionId, code, message) {
-    if (socket.readyState !== socket.OPEN)
-        return;
-    socket.send(serializeEnvelope(createEnvelope({
-        type: "session.error",
-        sessionId,
-        payload: { code, message },
-    })));
-}
-function truncateDetail(text, max = 72) {
-    const line = text.replace(/\s+/g, " ").trim();
-    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
-}
-function commandOrPathFromToolInput(toolInput) {
-    if (!toolInput)
-        return {};
-    try {
-        const parsed = JSON.parse(toolInput);
-        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() };
+    handleUpgrade(request, socket, head) {
+        this.wss.handleUpgrade(request, socket, head, (ws) => this.accept(ws));
     }
-    return {};
-}
-/** List-line for a live permission request: "运行命令 · pnpm test". */
-function permissionAttentionDetail(p) {
-    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}`);
+    get connected() {
+        return this.peers.size;
     }
-    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}`);
+    /** Bytes accepted from senders and not yet written to their receivers. */
+    get bufferedBytes() {
+        let total = 0;
+        for (const peer of this.peers.values())
+            total += peer.socket.bufferedAmount;
+        return total;
     }
-    if (p.context?.trim())
-        return truncateDetail(p.context.trim());
-    if (p.toolName)
-        return truncateDetail(`需要授权 · ${p.toolName}`);
-    return undefined;
-}
-function conversationAttentionDetail(conversation, status, current) {
-    if (status === "waiting_permission") {
-        if (current?.agentStatus === "waiting_permission" && current.agentDetail)
-            return undefined;
-        return conversation?.lastMessagePreview;
+    /** Drops connections that didn't answer the previous ping, pings the rest. */
+    sweep() {
+        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();
+        }
     }
-    if (status === "running" || status === "error") {
-        return conversation?.lastMessagePreview ?? null;
+    async stop() {
+        this.stopped = true;
+        clearInterval(this.heartbeat);
+        for (const peer of this.peers.values())
+            peer.socket.terminate();
+        await new Promise((resolve) => (this.server ? this.server.close(() => resolve()) : resolve()));
+        this.store.close();
     }
-    return status ? null : undefined;
-}
-function pickConversationSummary(conversations, activeConversationId) {
-    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];
-}
-function aggregateAgentStatus(conversations, fallback) {
-    if (conversations.some((c) => c.status === "waiting_permission"))
-        return "waiting_permission";
-    if (conversations.some((c) => c.status === "running"))
-        return "running";
-    return fallback;
-}
-function agentStatusFromTerminalPhase(phase) {
-    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;
-    }
-}
-function terminalStatusTitle(payload) {
-    if (payload.toolName)
-        return `外部终端 · ${payload.toolName}`;
-    if (payload.summary)
-        return `外部终端 · ${payload.summary}`;
-    return "外部终端";
-}
-function shouldPromoteTerminalStatus(status, current) {
-    if (status !== "idle")
-        return true;
-    return current !== "running" && current !== "waiting_permission";
-}
-function cacheAgentEnvelope(envelope, sessions) {
-    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,
-                });
+    // ── connection ────────────────────────────────────────────────────
+    accept(socket) {
+        this.alive.add(socket);
+        socket.on("pong", () => this.alive.add(socket));
+        const nonce = randomBytes(32).toString("base64url");
+        let peer;
+        const send = (frame) => {
+            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 });
+        socket.on("message", async (data) => {
+            let parsed;
+            try {
+                parsed = clientFrameSchema.safeParse(JSON.parse(data.toString()));
             }
-            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(),
-                });
+            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;
             }
-            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 ?? {}));
+                        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;
+            }
+        });
+        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);
+        });
+    }
+    async authenticate(frame, nonce, socket) {
+        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;
+        let email;
+        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;
         }
+        const refusal = await this.options.admit?.({ role: role, userId });
+        if (refusal)
+            throw new RelayError("not_admitted", refusal);
+        const record = {
+            id: identity.id,
+            role: role,
+            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 = { 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;
     }
-    catch {
-        // Agent summaries are best-effort; never block relay on a status parse.
+    // ── routing ───────────────────────────────────────────────────────
+    route(from, to, data) {
+        const via = this.store.route(from.record.id, to);
+        const target = this.peers.get(to);
+        const undeliverable = (reason) => from.socket.send(JSON.stringify({ t: "undeliverable", to, reason }));
+        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,
+        });
+        this.options.onRouted?.(frame);
+        target.socket.send(frame);
+        this.holdWhileBehind(from, target);
     }
-}
-function handleHostMessage(envelope, session, sessions) {
-    if (agentV2MessageRoute(envelope.type) === "host_to_client") {
-        cacheAgentEnvelope(envelope, sessions);
-        sessions.bufferAgentEnvelope(session.id, envelope);
-        broadcastToClients(session, envelope);
-        return;
-    }
-    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`);
-            }
-            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);
+    /**
+     * 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.
+     */
+    holdWhileBehind(from, target) {
+        const limit = this.options.maxBufferedBytes ?? 4 * 1024 * 1024;
+        if (from.held || target.socket.bufferedAmount <= limit)
             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;
+        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();
+            }
+            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, socket, session, deviceId, sessions) {
-    const requireController = () => {
-        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;
+    event(peerId, name, data) {
+        const peer = this.peers.get(peerId);
+        if (peer?.socket.readyState === WebSocket.OPEN)
+            peer.socket.send(JSON.stringify({ t: "event", name, data }));
     }
-    if (agentRoute === "client_read") {
-        sendToHost(session, envelope);
-        return;
+    /** Tells everyone who can reach `record` that it came or went. */
+    announce(record, online) {
+        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;
-                socket.send(serializeEnvelope(createEnvelope({
-                    type: "terminal.output",
-                    sessionId: session.id,
-                    terminalId: msg.terminalId,
-                    seq: msg.seq,
-                    payload: { ...payload, isReplay: true },
-                })));
+    machineEntry(peer, via) {
+        return {
+            id: peer.id,
+            signKey: peer.signKey,
+            boxKey: peer.boxKey,
+            name: peer.name,
+            platform: peer.platform,
+            online: this.peers.has(peer.id),
+            via,
+        };
+    }
+    deviceEntry(peer, pairedAt) {
+        return { id: peer.id, signKey: peer.signKey, boxKey: peer.boxKey, name: peer.name, online: this.peers.has(peer.id), pairedAt };
+    }
+    // ── control methods ───────────────────────────────────────────────
+    async handle(peer, method, params) {
+        const role = peer.record.role;
+        const need = (wanted) => {
+            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;
+                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 };
+            }
+            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 {};
             }
-            // Replay last terminal.status for each terminal
-            const statusReplay = sessions.getStatusReplay(session.id);
-            for (const statusMsg of statusReplay) {
-                socket.send(serializeEnvelope(statusMsg));
+            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 {};
             }
-            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,
-                        machineId: session.machineId,
-                    },
+            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");
                 }
-                : envelope);
-            break;
+                return {};
+            }
+            default:
+                throw new RelayError("unknown_method", `unknown method ${method}`);
         }
-        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;
+    }
+    async claim(device, params) {
+        // 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]);
+        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");
         }
-        case "control.release": {
-            sessions.releaseControl(session.id, deviceId);
-            const releaseMsg = createEnvelope({
-                type: "control.release",
-                sessionId: session.id,
-                payload: { deviceId },
+        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");
+        // The machine checks the proof (it holds the QR secret) and decides.
+        const requestId = randomUUID();
+        const accepted = await new Promise((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,
             });
-            broadcastToClients(session, releaseMsg);
-            sendToHost(session, releaseMsg);
-            break;
+        });
+        if (!accepted) {
+            this.event(machine.record.id, "pair.done", { requestId, accepted: false });
+            throw new RelayError("pairing_refused", "the computer refused this pairing");
         }
-        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, envelope) {
-    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);
-    }
-}
-/** Replay the last agent snapshot + recent host→client agent envelopes. */
-export function replayAgentToSocket(socket, sessionId, sessions) {
-    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));
-    }
-}
-function sendToHost(session, envelope) {
-    if (session.host &&
-        session.host.socket.readyState === session.host.socket.OPEN) {
-        session.host.socket.send(serializeEnvelope(envelope));
+        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") };
     }
 }
 //# sourceMappingURL=relay.js.map