@linkshell/gateway 0.4.2 → 0.4.4

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 {
@@ -26,6 +27,7 @@ import {
 } from "./tunnel.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
@@ -45,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;
@@ -65,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();
@@ -80,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(
@@ -90,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();
@@ -104,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 {
@@ -159,6 +226,22 @@ const server = createServer(async (req, res) => {
   }
 });
 
+// API path prefixes that must NEVER be served the SPA / handled as a web route.
+// Everything else (incl. "/", client-side views) may fall through to the web UI,
+// which must be reachable BEFORE the AUTH_REQUIRED guard so users can load the
+// login page and authenticate in the first place.
+function isApiPath(pathname: string): boolean {
+  return (
+    pathname === "/healthz" ||
+    pathname === "/sessions" ||
+    pathname.startsWith("/sessions/") ||
+    pathname === "/pairings" ||
+    pathname.startsWith("/pairings/") ||
+    pathname.startsWith("/agent/") ||
+    pathname.startsWith("/tunnel/")
+  );
+}
+
 async function handleRequest(
   req: IncomingMessage,
   res: ServerResponse,
@@ -276,6 +359,14 @@ async function handleRequest(
     return;
   }
 
+  // Web UI (public): serve the built SPA + its static assets BEFORE the
+  // AUTH_REQUIRED guard, so the login page itself is reachable on a premium
+  // gateway. Only non-API GET/HEAD requests are eligible; API routes above and
+  // below are matched explicitly and never reach here as web routes.
+  if ((method === "GET" || method === "HEAD") && !isApiPath(url.pathname)) {
+    if (await serveWeb(req, res)) return;
+  }
+
   // Auth check for premium gateway (skip healthz, /sessions/mine, tunnel)
   if (AUTH_REQUIRED) {
     const authResult = await requireAuth(req, res);
@@ -291,9 +382,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;
@@ -305,7 +400,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 });
@@ -385,6 +497,13 @@ async function handleRequest(
     return;
   }
 
+  // Web UI fallback: any remaining non-API GET (these are authenticated on a
+  // premium gateway) falls back to the SPA. API-shaped paths that matched no
+  // route 404 properly instead of being masked by the SPA shell.
+  if ((method === "GET" || method === "HEAD") && !isApiPath(url.pathname)) {
+    if (await serveWeb(req, res)) return;
+  }
+
   json(res, 404, { error: "not_found" });
 }
 
@@ -518,6 +637,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 =
@@ -590,11 +727,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) => {
@@ -664,6 +811,7 @@ function shutdown() {
   sessionManager.destroy();
   pairingManager.destroy();
   tokenManager.destroy();
+  hostAuthManager.destroy();
   server.close(() => {
     process.stdout.write("[gateway] stopped\n");
     process.exit(0);
@@ -736,6 +884,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,6 +1,7 @@
 import type WebSocket from "ws";
 import {
   agentV2MessageRoute,
+  isProtocolVersionCompatible,
   parseEnvelope,
   parseTypedPayload,
   protocolMessageSchemas,
@@ -117,6 +118,16 @@ function handleHostMessage(
     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,
@@ -355,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();
   }
 

package/src/static-web.ts

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import { stat, readFile } from "node:fs/promises";
+import { resolve, join, extname, normalize } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+// Serves the built web-dashboard SPA from the gateway, so a single deployment
+// (and single origin) hosts both the API/WebSocket and the UI. The web is
+// optional: if WEB_DIST doesn't exist (e.g. local dev using the Vite dev
+// server), the gateway runs API-only and this is a no-op.
+
+const WEB_DIST = process.env.WEB_DIST ?? resolve(process.cwd(), "web");
+const hasWeb = existsSync(join(WEB_DIST, "index.html"));
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".map": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+export function webEnabled(): boolean {
+  return hasWeb;
+}
+
+export function webDistPath(): string {
+  return WEB_DIST;
+}
+
+/**
+ * Try to serve a GET/HEAD request from the web dist. Returns true if handled.
+ * Place AFTER all API routes so it never shadows them. Unmatched non-asset
+ * paths fall back to index.html (SPA client-side routing).
+ */
+export async function serveWeb(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (!hasWeb) return false;
+  if (req.method !== "GET" && req.method !== "HEAD") return false;
+
+  const url = new URL(req.url ?? "/", "http://localhost");
+  let pathname = decodeURIComponent(url.pathname);
+
+  // Path-traversal guard: normalize, then confine to WEB_DIST.
+  const candidate = resolve(WEB_DIST, "." + normalize(pathname));
+  const inRoot = candidate === WEB_DIST || candidate.startsWith(WEB_DIST + "/");
+
+  let filePath: string | null = null;
+  if (inRoot && pathname !== "/") {
+    try {
+      const s = await stat(candidate);
+      if (s.isFile()) filePath = candidate;
+    } catch {
+      // not a real file
+    }
+  }
+
+  // SPA fallback: serve index.html for "/" and for any path without a file
+  // extension (a client-side route). Missing assets (with an extension) 404.
+  if (!filePath) {
+    if (pathname === "/" || extname(pathname) === "") {
+      filePath = join(WEB_DIST, "index.html");
+    } else {
+      return false; // let the caller 404 the missing asset
+    }
+  }
+
+  try {
+    const ext = extname(filePath).toLowerCase();
+    const type = CONTENT_TYPES[ext] ?? "application/octet-stream";
+    res.setHeader("Content-Type", type);
+    // Hashed assets (Vite emits content-hashed filenames) can cache hard;
+    // index.html must never be cached so deploys take effect immediately.
+    if (filePath.endsWith("index.html")) {
+      res.setHeader("Cache-Control", "no-cache");
+    } else {
+      res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+    }
+    if (req.method === "HEAD") {
+      res.writeHead(200);
+      res.end();
+      return true;
+    }
+    const body = await readFile(filePath);
+    res.writeHead(200);
+    res.end(body);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/tunnel.ts

@@ -154,7 +154,7 @@ export async function handleTunnelRequest(
   const cookieToken = tokenOwns ? token : authJwt;
   if (cookieToken) {
     const cookieVal = encodeURIComponent(`${sessionId}:${port}:${cookieToken}`);
-    res.setHeader("Set-Cookie", `lsh_tunnel=${cookieVal}; Path=/; HttpOnly; SameSite=Lax`);
+    res.setHeader("Set-Cookie", `lsh_tunnel=${cookieVal}; Path=/; HttpOnly; Secure; SameSite=Lax`);
   }
 
   // Validate session & host