@linkshell/gateway 0.4.1 → 0.4.3

package/src/host-auth.ts

@@ -0,0 +1,82 @@
+import { randomUUID, timingSafeEqual } from "node:crypto";
+
+const CLEANUP_INTERVAL = 5 * 60_000;
+const HOST_TOKEN_TTL = 7 * 24 * 60 * 60_000; // 7 days
+
+interface HostBinding {
+  sessionId: string;
+  hostToken: string;
+  lastUsedAt: number;
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+/**
+ * Binds a session to the secret host token issued when its pairing was created,
+ * so only the original host (the CLI that created the pairing) can connect as
+ * `role=host`. Without this, anyone who learns a sessionId could connect as host
+ * and capture every controller keystroke or inject terminal output.
+ *
+ * Kept separate from PairingManager because a host connection long outlives the
+ * pairing code's 10-minute TTL (and reconnects days later), so the binding needs
+ * its own longer lifetime.
+ */
+export class HostAuthManager {
+  private bindings = new Map<string, HostBinding>();
+  private cleanupTimer: ReturnType<typeof setInterval>;
+
+  constructor() {
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
+    this.cleanupTimer.unref?.();
+  }
+
+  /** Issue a fresh host token for a session (called at pairing creation). */
+  issue(sessionId: string): string {
+    const hostToken = randomUUID();
+    this.bindings.set(sessionId, { sessionId, hostToken, lastUsedAt: Date.now() });
+    return hostToken;
+  }
+
+  /** Trust-on-first-use: register a host-provided token when no binding exists
+   *  yet (e.g. after a gateway restart lost the in-memory binding). */
+  adopt(sessionId: string, hostToken: string): void {
+    this.bindings.set(sessionId, { sessionId, hostToken, lastUsedAt: Date.now() });
+  }
+
+  has(sessionId: string): boolean {
+    const binding = this.bindings.get(sessionId);
+    if (!binding) return false;
+    if (Date.now() - binding.lastUsedAt > HOST_TOKEN_TTL) {
+      this.bindings.delete(sessionId);
+      return false;
+    }
+    return true;
+  }
+
+  verify(sessionId: string, hostToken: string | undefined): boolean {
+    if (!hostToken) return false;
+    const binding = this.bindings.get(sessionId);
+    if (!binding) return false;
+    if (!safeEqual(binding.hostToken, hostToken)) return false;
+    binding.lastUsedAt = Date.now();
+    return true;
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [sessionId, binding] of this.bindings) {
+      if (now - binding.lastUsedAt > HOST_TOKEN_TTL) {
+        this.bindings.delete(sessionId);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupTimer);
+  }
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { z, ZodError } from "zod";
 import { SessionManager } from "./sessions.js";
 import { PairingManager } from "./pairings.js";
 import { TokenManager } from "./tokens.js";
+import { HostAuthManager } from "./host-auth.js";
 import { createSupabaseStateStore } from "./state-store.js";
 import { handleSocketMessage } from "./relay.js";
 import {
@@ -24,7 +25,9 @@ import {
   handleTunnelRequest,
   cleanupSessionTunnels,
 } from "./tunnel.js";
-import { AUTH_REQUIRED, requireAuth, checkWsAuth, validateRequest, checkSubscriptionByUserId } from "./auth-middleware.js";
+import { AUTH_REQUIRED, requireAuth, checkWsAuth, validateRequest, checkSubscriptionByUserId, canReadSessionDetail } from "./auth-middleware.js";
+import { setCors } from "./cors.js";
+import { serveWeb, webEnabled, webDistPath } from "./static-web.js";
 
 const port = Number(process.env.PORT ?? 8787);
 const logLevel = (process.env.LOG_LEVEL ?? "info") as
@@ -44,6 +47,7 @@ const stateStore = createSupabaseStateStore();
 const sessionManager = new SessionManager();
 const pairingManager = new PairingManager(stateStore);
 const tokenManager = new TokenManager(stateStore);
+const hostAuthManager = new HostAuthManager();
 await Promise.all([pairingManager.hydrate(), tokenManager.hydrate()]);
 
 const PING_INTERVAL = 20_000;
@@ -64,10 +68,18 @@ const WS_CONNECT_RATE_LIMIT_WINDOW_MS = Number(
 
 class RateLimiter {
   private hits = new Map<string, { count: number; resetAt: number }>();
+  private pruneTimer: ReturnType<typeof setInterval>;
   constructor(
     private maxHits: number,
     private windowMs: number,
-  ) {}
+  ) {
+    // Periodically evict expired windows so the map does not grow unbounded.
+    this.pruneTimer = setInterval(
+      () => this.prune(),
+      Math.max(windowMs, 60_000),
+    );
+    this.pruneTimer.unref?.();
+  }
 
   allow(key: string): boolean {
     const now = Date.now();
@@ -79,6 +91,17 @@ class RateLimiter {
     entry.count++;
     return entry.count <= this.maxHits;
   }
+
+  private prune(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.hits) {
+      if (now >= entry.resetAt) this.hits.delete(key);
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.pruneTimer);
+  }
 }
 
 const pairingLimiter = new RateLimiter(
@@ -89,6 +112,18 @@ const wsConnectLimiter = new RateLimiter(
   WS_CONNECT_RATE_LIMIT_MAX,
   WS_CONNECT_RATE_LIMIT_WINDOW_MS,
 );
+// Gateway-wide cap on failed pairing claims per window, independent of the
+// per-IP creation limiter — mitigates distributed pairing-code guessing.
+const CLAIM_FAILURE_RATE_LIMIT_MAX = Number(
+  process.env.CLAIM_FAILURE_RATE_LIMIT_MAX ?? 100,
+);
+const CLAIM_FAILURE_RATE_LIMIT_WINDOW_MS = Number(
+  process.env.CLAIM_FAILURE_RATE_LIMIT_WINDOW_MS ?? 60_000,
+);
+const claimFailureLimiter = new RateLimiter(
+  CLAIM_FAILURE_RATE_LIMIT_MAX,
+  CLAIM_FAILURE_RATE_LIMIT_WINDOW_MS,
+);
 
 function isLoopbackIp(ip: string): boolean {
   const normalized = ip.trim().toLowerCase();
@@ -103,10 +138,43 @@ function isRateLimitBypassed(ip: string): boolean {
   return isLoopbackIp(ip);
 }
 
+/**
+ * Trusted reverse proxies, parsed from TRUSTED_PROXIES (comma-separated IPs).
+ * X-Forwarded-For is only honored when the immediate peer
+ * (req.socket.remoteAddress) is one of these. Default empty = trust nobody,
+ * so the socket address is always used and the header cannot be spoofed.
+ * IPv6-mapped IPv4 (::ffff:1.2.3.4) is normalized to the bare IPv4 form.
+ */
+function normalizeIp(ip: string): string {
+  const t = ip.trim().toLowerCase();
+  if (t.startsWith("::ffff:")) return t.slice(7);
+  return t;
+}
+
+function parseTrustedProxies(): Set<string> {
+  const raw = process.env.TRUSTED_PROXIES ?? "";
+  const set = new Set<string>();
+  for (const part of raw.split(",")) {
+    const ip = normalizeIp(part);
+    if (ip) set.add(ip);
+  }
+  return set;
+}
+
+const TRUSTED_PROXIES = parseTrustedProxies();
+
 function getClientIp(req: IncomingMessage): string {
-  const forwarded = req.headers["x-forwarded-for"];
-  if (typeof forwarded === "string") return forwarded.split(",")[0]!.trim();
-  return req.socket.remoteAddress ?? "unknown";
+  const peer = req.socket.remoteAddress ?? "unknown";
+  // Only honor X-Forwarded-For when the direct peer is a configured proxy;
+  // otherwise the header is attacker-controlled and would defeat rate limits.
+  if (TRUSTED_PROXIES.has(normalizeIp(peer))) {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (typeof forwarded === "string") {
+      const first = forwarded.split(",")[0]?.trim();
+      if (first) return first;
+    }
+  }
+  return peer;
 }
 
 function extractBearerToken(req: IncomingMessage): string | null {
@@ -116,15 +184,6 @@ function extractBearerToken(req: IncomingMessage): string | null {
   return match?.[1] ?? null;
 }
 
-// ── CORS ────────────────────────────────────────────────────────────
-
-function setCors(res: ServerResponse): void {
-  res.setHeader("Access-Control-Allow-Origin", "*");
-  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
-  res.setHeader("Access-Control-Max-Age", "86400");
-}
-
 // ── HTTP API ────────────────────────────────────────────────────────
 
 const createPairingBody = z.object({ sessionId: z.string().optional() });
@@ -174,6 +233,7 @@ async function handleRequest(
   const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
   const method = req.method ?? "GET";
   const ip = getClientIp(req);
+  let authenticatedUserId: string | undefined;
 
   // Health check
   if (method === "GET" && url.pathname === "/healthz") {
@@ -188,6 +248,13 @@ async function handleRequest(
       json(res, 401, { error: "auth_required", message: "Authentication required" });
       return;
     }
+    if (AUTH_REQUIRED && !authResult.subscribed) {
+      json(res, 403, {
+        error: "subscription_required",
+        message: "Pro subscription required. Subscribe at https://itool.tech",
+      });
+      return;
+    }
     const sessions = sessionManager
       .listActive()
       .filter((s) => s.userId === authResult.userId)
@@ -209,6 +276,13 @@ async function handleRequest(
       json(res, 401, { error: "auth_required", message: "Authentication required" });
       return;
     }
+    if (AUTH_REQUIRED && !authResult.subscribed) {
+      json(res, 403, {
+        error: "subscription_required",
+        message: "Pro subscription required. Subscribe at https://itool.tech",
+      });
+      return;
+    }
     const session = sessionManager.get(sessionId);
     if (!session) {
       json(res, 404, { error: "not_found" });
@@ -273,6 +347,7 @@ async function handleRequest(
   if (AUTH_REQUIRED) {
     const authResult = await requireAuth(req, res);
     if (!authResult) return; // response already sent
+    authenticatedUserId = authResult.userId;
   }
 
   // Create pairing
@@ -283,9 +358,13 @@ async function handleRequest(
     }
     const body = createPairingBody.parse(await readJson(req));
     const record = pairingManager.create(body.sessionId);
+    // Issue a secret host token bound to this session. Only the CLI that
+    // created the pairing can later connect as role=host (see WS handler).
+    const hostToken = hostAuthManager.issue(record.sessionId);
     json(res, 201, {
       sessionId: record.sessionId,
       pairingCode: record.pairingCode,
+      hostToken,
       expiresAt: new Date(record.expiresAt).toISOString(),
     });
     return;
@@ -297,7 +376,24 @@ async function handleRequest(
       json(res, 429, { error: "rate_limited", message: "Too many requests" });
       return;
     }
+    // Gateway-wide cap on failed claims, independent of per-IP limiter, to
+    // blunt distributed brute-forcing across many source IPs.
+    if (!isRateLimitBypassed(ip) && !claimFailureLimiter.allow("global")) {
+      json(res, 429, { error: "rate_limited", message: "Too many failed claims" });
+      return;
+    }
     const body = claimPairingBody.parse(await readJson(req));
+    // Idempotent re-claim: if the requester's device token already owns the
+    // session this code maps to, re-issue success instead of erroring with
+    // already_claimed. Only a token that has PROVEN ownership takes this path,
+    // so it can't be used to bypass brute-force protection. This lets a browser
+    // that refreshes or re-enters its code reconnect smoothly.
+    const peeked = pairingManager.peek(body.pairingCode);
+    if (peeked && body.deviceToken && tokenManager.owns(body.deviceToken, peeked.sessionId)) {
+      tokenManager.bind(body.deviceToken, peeked.sessionId); // refresh lastUsedAt
+      json(res, 200, { sessionId: peeked.sessionId, deviceToken: body.deviceToken });
+      return;
+    }
     const result = pairingManager.claim(body.pairingCode);
     if ("error" in result) {
       json(res, result.status, { error: result.error });
@@ -342,7 +438,14 @@ async function handleRequest(
   if (method === "GET" && sessionMatch) {
     const token = extractBearerToken(req);
     const targetId = sessionMatch[1]!;
-    if (!token || !tokenManager.owns(token, targetId)) {
+    const session = sessionManager.get(targetId);
+    const tokenOwns = Boolean(token && tokenManager.owns(token, targetId));
+    if (!canReadSessionDetail({
+      authRequired: AUTH_REQUIRED,
+      authenticatedUserId,
+      sessionUserId: session?.userId,
+      tokenOwns,
+    })) {
       json(res, 401, {
         error: "unauthorized",
         message: "Valid device token required",
@@ -370,6 +473,10 @@ async function handleRequest(
     return;
   }
 
+  // Web UI: serve the built SPA for any unmatched GET (after all API routes, so
+  // it never shadows them). No-op when WEB_DIST isn't present (API-only mode).
+  if (await serveWeb(req, res)) return;
+
   json(res, 404, { error: "not_found" });
 }
 
@@ -503,6 +610,24 @@ wss.on(
     };
 
     if (role === "host") {
+      // Verify the host token issued when this session's pairing was created.
+      // Without this, anyone who learns a sessionId could connect as host and
+      // capture controller keystrokes or inject terminal output.
+      const hdr = _request.headers["x-linkshell-host-token"];
+      const providedHostToken = Array.isArray(hdr) ? hdr[0] : hdr;
+      if (hostAuthManager.has(sessionId)) {
+        if (!hostAuthManager.verify(sessionId, providedHostToken)) {
+          log("warn", `rejected host connect with bad host token for ${sessionId}`);
+          socket.close(4003, "host authentication failed");
+          return;
+        }
+      } else if (providedHostToken) {
+        // No binding yet (e.g. gateway restarted and lost in-memory state) —
+        // trust the first host token presented for this session.
+        hostAuthManager.adopt(sessionId, providedHostToken);
+      }
+      // else: legacy host without a token — allowed for backward compatibility.
+
       // Check if this is a reconnect (session already exists with clients)
       const existingSession = sessionManager.get(sessionId);
       const isReconnect =
@@ -575,11 +700,21 @@ wss.on(
       }
     }
 
-    // Ping/pong for liveness
+    // Ping/pong for liveness — terminate connections that stop responding
+    // to pings (dead/half-open sockets) instead of leaking them.
+    const liveSocket = socket as WebSocket & { isAlive?: boolean };
+    liveSocket.isAlive = true;
+    socket.on("pong", () => {
+      liveSocket.isAlive = true;
+    });
     const pingTimer = setInterval(() => {
-      if (socket.readyState === socket.OPEN) {
-        socket.ping();
+      if (socket.readyState !== socket.OPEN) return;
+      if (liveSocket.isAlive === false) {
+        socket.terminate();
+        return;
       }
+      liveSocket.isAlive = false;
+      socket.ping();
     }, PING_INTERVAL);
 
     socket.on("message", (data: WebSocket.RawData) => {
@@ -649,6 +784,7 @@ function shutdown() {
   sessionManager.destroy();
   pairingManager.destroy();
   tokenManager.destroy();
+  hostAuthManager.destroy();
   server.close(() => {
     process.stdout.write("[gateway] stopped\n");
     process.exit(0);
@@ -721,6 +857,11 @@ server.listen(port, () => {
   log("info", `LinkShell Gateway v0.1.0`);
   log("info", `listening on http://0.0.0.0:${port}`);
   log("info", `log level: ${logLevel}`);
+  if (webEnabled()) {
+    log("info", `web UI served from ${webDistPath()} (open http://0.0.0.0:${port}/)`);
+  } else {
+    log("info", `web UI not bundled (API-only); set WEB_DIST to enable`);
+  }
 });
 
 // ── Helpers ─────────────────────────────────────────────────────────

package/src/pairings.ts

@@ -6,10 +6,15 @@ export interface PairingRecord {
   pairingCode: string;
   expiresAt: number; // unix ms
   claimed: boolean;
+  failedAttempts: number; // failed claim attempts against this code
 }
 
 const PAIRING_TTL = Number(process.env.PAIRING_TTL_MS ?? 10 * 60_000); // 10 minutes
 const CLEANUP_INTERVAL = 60_000;
+// Invalidate a code after this many failed claim attempts to cap brute-forcing.
+const MAX_FAILED_CLAIM_ATTEMPTS = Number(
+  process.env.PAIRING_MAX_FAILED_ATTEMPTS ?? 5,
+);
 
 export class PairingManager {
   private pairings = new Map<string, PairingRecord>();
@@ -29,7 +34,8 @@ export class PairingManager {
           void this.store.deletePairing(record.pairingCode).catch(() => {});
           continue;
         }
-        this.pairings.set(record.pairingCode, record);
+        // Stored records predate the failedAttempts field; default it.
+        this.pairings.set(record.pairingCode, { ...record, failedAttempts: 0 });
       }
     } catch (err) {
       process.stderr.write(`[gateway] pairing store hydrate failed, using memory only: ${err}\n`);
@@ -44,6 +50,7 @@ export class PairingManager {
       pairingCode: code,
       expiresAt: Date.now() + PAIRING_TTL,
       claimed: false,
+      failedAttempts: 0,
     };
     this.pairings.set(code, record);
     this.persist(record);
@@ -61,6 +68,15 @@ export class PairingManager {
       return { error: "pairing_expired", status: 410 };
     }
     if (record.claimed) {
+      // Count repeated claim attempts on an existing code; once the cap is
+      // exceeded, invalidate it so it can no longer be targeted.
+      record.failedAttempts += 1;
+      if (record.failedAttempts >= MAX_FAILED_CLAIM_ATTEMPTS) {
+        this.pairings.delete(pairingCode);
+        void this.store?.deletePairing(pairingCode).catch(() => {});
+      } else {
+        this.persist(record);
+      }
       return { error: "pairing_already_claimed", status: 409 };
     }
     record.claimed = true;
@@ -68,6 +84,16 @@ export class PairingManager {
     return record;
   }
 
+  /** Look up a code's session without consuming an attempt or mutating state.
+   *  Lets the claim endpoint stay idempotent for a device that already owns the
+   *  mapped session (it re-issues instead of erroring with already_claimed). */
+  peek(pairingCode: string): { sessionId: string; claimed: boolean } | null {
+    const record = this.pairings.get(pairingCode);
+    if (!record) return null;
+    if (record.expiresAt < Date.now()) return null;
+    return { sessionId: record.sessionId, claimed: record.claimed };
+  }
+
   getStatus(pairingCode: string): { status: string; expiresAt: number; sessionId: string } | { error: string; httpStatus: number } {
     const record = this.pairings.get(pairingCode);
     if (!record) {

package/src/relay.ts

@@ -1,5 +1,7 @@
 import type WebSocket from "ws";
 import {
+  agentV2MessageRoute,
+  isProtocolVersionCompatible,
   parseEnvelope,
   parseTypedPayload,
   protocolMessageSchemas,
@@ -49,7 +51,7 @@ export function handleSocketMessage(
   }
 
   try {
-    if (isProtocolMessageType(envelope.type)) {
+    if (shouldValidatePayloadAtGateway(envelope.type)) {
       envelope = {
         ...envelope,
         payload: parseTypedPayload(envelope.type, envelope.payload),
@@ -79,6 +81,11 @@ function isProtocolMessageType(type: string): type is ProtocolMessageType {
   return Object.prototype.hasOwnProperty.call(protocolMessageSchemas, type);
 }
 
+function shouldValidatePayloadAtGateway(type: string): type is ProtocolMessageType {
+  if (agentV2MessageRoute(type) !== null) return false;
+  return isProtocolMessageType(type);
+}
+
 function sendSessionError(
   socket: WebSocket,
   sessionId: string,
@@ -102,10 +109,25 @@ function handleHostMessage(
   session: ReturnType<SessionManager["get"]> & {},
   sessions: SessionManager,
 ): void {
+  if (agentV2MessageRoute(envelope.type) === "host_to_client") {
+    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,
@@ -177,13 +199,6 @@ function handleHostMessage(
     case "agent.update":
     case "agent.permission.request":
     case "agent.snapshot":
-    case "agent.v2.capabilities":
-    case "agent.v2.conversation.opened":
-    case "agent.v2.conversation.list.result":
-    case "agent.v2.event":
-    case "agent.v2.snapshot":
-    case "agent.v2.permission.request":
-    case "agent.v2.notice":
     // Multi-terminal: host → clients
     case "terminal.spawned":
     case "terminal.list":
@@ -226,6 +241,17 @@ function handleClientMessage(
     return false;
   };
 
+  const agentRoute = agentV2MessageRoute(envelope.type);
+  if (agentRoute === "client_write") {
+    if (!requireController()) return;
+    sendToHost(session, envelope);
+    return;
+  }
+  if (agentRoute === "client_read") {
+    sendToHost(session, envelope);
+    return;
+  }
+
   switch (envelope.type) {
     case "terminal.input": {
       if (!requireController()) return;
@@ -316,12 +342,6 @@ function handleClientMessage(
     case "agent.prompt":
     case "agent.cancel":
     case "agent.permission.response":
-    case "agent.v2.conversation.open":
-    case "agent.v2.prompt":
-    case "agent.v2.command.execute":
-    case "agent.v2.cancel":
-    case "agent.v2.permission.respond":
-    case "agent.v2.structured_input.respond":
     // Multi-terminal write ops: client → host (require controller)
     case "terminal.spawn":
     case "terminal.kill":
@@ -338,9 +358,6 @@ function handleClientMessage(
     case "terminal.history.request":
     case "agent.initialize":
     case "agent.session.list":
-    case "agent.v2.capabilities.request":
-    case "agent.v2.conversation.list":
-    case "agent.v2.snapshot.request":
       sendToHost(session, envelope);
       break;
     default:
@@ -349,15 +366,19 @@ function handleClientMessage(
   }
 }
 
+/** 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) {
-      client.socket.send(data);
-    }
+    if (client.socket.readyState !== client.socket.OPEN) continue;
+    if (client.socket.bufferedAmount > MAX_CLIENT_BUFFER_BYTES) continue;
+    client.socket.send(data);
   }
 }
 

package/src/sessions.ts

@@ -19,6 +19,7 @@ export interface Session {
   lastActivity: number;
   createdAt: number;
   outputBuffers: Map<string, Envelope[]>; // keyed by terminalId
+  outputBufferBytes: Map<string, number>; // approx byte size per terminalId buffer
   lastStatusByTerminal: Map<string, Envelope>; // last terminal.status per terminal
   hostDisconnectedAt: number | undefined;
   // Metadata from host's session.connect
@@ -33,9 +34,21 @@ export interface Session {
 }
 
 const OUTPUT_BUFFER_CAPACITY = 200;
+const OUTPUT_BUFFER_MAX_BYTES = 8 * 1024 * 1024; // 8MB per terminal buffer
 const HOST_RECONNECT_WINDOW = 60_000; // 60s
 const CLEANUP_INTERVAL = 30_000;
 
+/** Approximate the wire byte size of an envelope for buffer accounting. */
+function approxEnvelopeBytes(envelope: Envelope): number {
+  const data = (envelope.payload as { data?: unknown } | undefined)?.data;
+  if (typeof data === "string") return data.length;
+  try {
+    return JSON.stringify(envelope).length;
+  } catch {
+    return 0;
+  }
+}
+
 export class SessionManager {
   private sessions = new Map<string, Session>();
   private cleanupTimer: ReturnType<typeof setInterval>;
@@ -56,6 +69,7 @@ export class SessionManager {
         lastActivity: Date.now(),
         createdAt: Date.now(),
         outputBuffers: new Map(),
+        outputBufferBytes: new Map(),
         lastStatusByTerminal: new Map(),
         hostDisconnectedAt: undefined,
         provider: undefined,
@@ -137,11 +151,20 @@ export class SessionManager {
     if (!buf) {
       buf = [];
       session.outputBuffers.set(tid, buf);
+      session.outputBufferBytes.set(tid, 0);
     }
     buf.push(envelope);
-    if (buf.length > OUTPUT_BUFFER_CAPACITY) {
-      buf.shift();
+    let bytes = (session.outputBufferBytes.get(tid) ?? 0) + approxEnvelopeBytes(envelope);
+    // Evict oldest until under BOTH the count cap and the byte cap, so a
+    // malicious/abnormal host can't pin unbounded memory via large frames.
+    while (
+      buf.length > OUTPUT_BUFFER_CAPACITY ||
+      (bytes > OUTPUT_BUFFER_MAX_BYTES && buf.length > 1)
+    ) {
+      const removed = buf.shift();
+      if (removed) bytes -= approxEnvelopeBytes(removed);
     }
+    session.outputBufferBytes.set(tid, Math.max(0, bytes));
     session.lastActivity = Date.now();
   }