@linkshell/gateway 0.5.3 → 0.6.1

package/src/embedded.ts

@@ -1,526 +0,0 @@
-import { createServer } from "node:http";
-import type { IncomingMessage, ServerResponse, Server } from "node:http";
-import { randomUUID } from "node:crypto";
-import { WebSocketServer } from "ws";
-import type WebSocket from "ws";
-import {
-  createEnvelope,
-  serializeEnvelope,
-  PROTOCOL_VERSION,
-} from "@linkshell/protocol";
-import { z, ZodError } from "zod";
-import { SessionManager } from "./sessions.js";
-import { PairingManager } from "./pairings.js";
-import { TokenManager } from "./tokens.js";
-import { handleSocketMessage, replayAgentToSocket } from "./relay.js";
-import { PresenceHub, startPresenceWatcher } from "./presence.js";
-import {
-  parseTunnelPath,
-  parseTunnelCookie,
-  shouldUseTunnelCookieFallback,
-  handleTunnelRequest,
-  handleTunnelWsUpgrade,
-  cleanupSessionTunnels,
-} from "./tunnel.js";
-import { serveWeb, serveWebAsset, webEnabled, webDistPath } from "./static-web.js";
-
-export interface EmbeddedGatewayOptions {
-  port?: number;
-  logLevel?: "debug" | "info" | "warn" | "error";
-  silent?: boolean;
-  /**
-   * Also serve the v2 relay (end-to-end encrypted, at /v2/connect), keeping its
-   * pairings in SQLite here. Needs Node.js 22.13+ (node:sqlite).
-   */
-  relayDataPath?: string;
-}
-
-export interface EmbeddedGateway {
-  port: number;
-  httpUrl: string;
-  wsUrl: string;
-  close: () => Promise<void>;
-}
-
-const PING_INTERVAL = 20_000;
-const MAX_BODY_SIZE = 4096;
-const MAX_WS_MESSAGE_SIZE = 50 * 1024 * 1024; // 50MB (supports base64 image uploads)
-
-const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
-
-const createPairingBody = z.object({ sessionId: z.string().optional() });
-const claimPairingBody = z.object({
-  pairingCode: z.string().length(6),
-  deviceToken: z.string().min(1).optional(),
-});
-
-class BodyTooLargeError extends Error {}
-
-function json(res: ServerResponse, status: number, body: unknown): void {
-  res.writeHead(status, {
-    "content-type": "application/json",
-    "access-control-allow-origin": "*",
-    "access-control-allow-methods": "GET, POST, OPTIONS",
-    "access-control-allow-headers": "Content-Type, Authorization",
-  });
-  res.end(JSON.stringify(body));
-}
-
-async function readJson(req: IncomingMessage): Promise<unknown> {
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of req) {
-    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buf.length;
-    if (size > MAX_BODY_SIZE) throw new BodyTooLargeError();
-    chunks.push(buf);
-  }
-  if (chunks.length === 0) return {};
-  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-}
-
-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";
-}
-
-function extractBearerToken(req: IncomingMessage): string | null {
-  const auth = req.headers.authorization;
-  if (!auth) return null;
-  const match = auth.match(/^Bearer\s+(.+)$/i);
-  return match?.[1] ?? null;
-}
-
-/**
- * Start an embedded gateway. Returns a handle to get URLs and close it.
- * Used by CLI when no external --gateway is provided.
- */
-export async function startEmbeddedGateway(
-  options: EmbeddedGatewayOptions = {},
-): Promise<EmbeddedGateway> {
-  const targetPort = options.port ?? 0; // 0 = random available port
-  const logLevel = options.logLevel ?? "warn";
-  const silent = options.silent ?? false;
-
-  function log(level: "debug" | "info" | "warn" | "error", msg: string): void {
-    if (silent) return;
-    if (LOG_LEVELS[level] >= LOG_LEVELS[logLevel]) {
-      process.stderr.write(`[gateway:${level}] ${msg}\n`);
-    }
-  }
-
-  const sessionManager = new SessionManager();
-  const pairingManager = new PairingManager();
-  const tokenManager = new TokenManager();
-  const presenceHub = new PresenceHub();
-  sessionManager.onPresenceChange = (session) => presenceHub.notify(session);
-
-  const server = createServer(async (req, res) => {
-    if (req.method === "OPTIONS") {
-      res.writeHead(204, {
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, POST, OPTIONS",
-        "access-control-allow-headers": "Content-Type, Authorization",
-        "access-control-max-age": "86400",
-      });
-      res.end();
-      return;
-    }
-
-    try {
-      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-      const method = req.method ?? "GET";
-
-      if (method === "GET" && url.pathname === "/healthz") {
-        json(res, 200, { ok: true });
-        return;
-      }
-
-      if (method === "POST" && url.pathname === "/pairings") {
-        const body = createPairingBody.parse(await readJson(req));
-        const record = pairingManager.create(body.sessionId);
-        json(res, 201, {
-          sessionId: record.sessionId,
-          pairingCode: record.pairingCode,
-          expiresAt: new Date(record.expiresAt).toISOString(),
-        });
-        return;
-      }
-
-      if (method === "POST" && url.pathname === "/pairings/claim") {
-        const body = claimPairingBody.parse(await readJson(req));
-        const result = pairingManager.claim(body.pairingCode);
-        if ("error" in result) {
-          json(res, result.status, { error: result.error });
-          return;
-        }
-        const token = tokenManager.register(body.deviceToken);
-        tokenManager.bind(token, result.sessionId);
-        json(res, 200, { sessionId: result.sessionId, deviceToken: token });
-        return;
-      }
-
-      if (method === "GET" && url.pathname === "/sessions") {
-        const token = extractBearerToken(req);
-        if (!token || !tokenManager.validate(token)) {
-          json(res, 401, {
-            error: "unauthorized",
-            message: "Valid device token required",
-          });
-          return;
-        }
-        const allowedIds = tokenManager.getSessionIds(token);
-        const sessions = sessionManager
-          .listActive()
-          .filter((s) => allowedIds.has(s.id))
-          .map((s) => sessionManager.getSummary(s.id))
-          .filter(Boolean);
-        json(res, 200, { sessions });
-        return;
-      }
-
-      const sessionMatch = url.pathname.match(/^\/sessions\/([^/]+)$/);
-      if (method === "GET" && sessionMatch) {
-        const token = extractBearerToken(req);
-        const targetId = sessionMatch[1]!;
-        if (!token || !tokenManager.owns(token, targetId)) {
-          json(res, 401, {
-            error: "unauthorized",
-            message: "Valid device token required",
-          });
-          return;
-        }
-        const summary = sessionManager.getSummary(targetId);
-        if (!summary) {
-          json(res, 404, { error: "session_not_found" });
-          return;
-        }
-        json(res, 200, summary);
-        return;
-      }
-
-      const pairingMatch = url.pathname.match(/^\/pairings\/(\d{6})\/status$/);
-      if (method === "GET" && pairingMatch) {
-        const result = pairingManager.getStatus(pairingMatch[1]!);
-        if ("error" in result) {
-          json(res, result.httpStatus, { error: result.error });
-          return;
-        }
-        json(res, 200, result);
-        return;
-      }
-
-      // Tunnel HTTP proxy (explicit path)
-      const tunnelParsed = parseTunnelPath(url.pathname);
-      if (tunnelParsed) {
-        await handleTunnelRequest(req, res, sessionManager, tokenManager, tunnelParsed, url);
-        return;
-      }
-
-      // Serve the gateway's OWN built web assets (no SPA fallback) before the
-      // tunnel cookie fallback, so a real asset like /assets/index-xxx.js is
-      // served locally instead of being proxied via a stale tunnel cookie.
-      if (await serveWebAsset(req, res)) return;
-
-      // Tunnel fallback: cookie-based routing for sub-resources (e.g. /_next/static/...)
-      const tunnelCookie = parseTunnelCookie(req);
-      if (tunnelCookie && shouldUseTunnelCookieFallback(req, url.pathname, (pathname) =>
-        pathname === "/healthz" ||
-        pathname === "/sessions" ||
-        pathname.startsWith("/sessions/") ||
-        pathname === "/pairings" ||
-        pathname.startsWith("/pairings/") ||
-        pathname.startsWith("/agent/") ||
-        pathname.startsWith("/tunnel/")
-      )) {
-        const fallbackParsed = {
-          sessionId: tunnelCookie.sessionId,
-          port: tunnelCookie.port,
-          path: url.pathname,
-        };
-        await handleTunnelRequest(req, res, sessionManager, tokenManager, fallbackParsed, url, tunnelCookie.token);
-        return;
-      }
-
-      // Web SPA: last GET fallback, after every API route, so it never shadows
-      // them. Serves index.html for "/" and client-side routes; a no-op (false)
-      // when no web dist is bundled (e.g. an API-only embedded gateway).
-      if (await serveWeb(req, res)) return;
-
-      json(res, 404, { error: "not_found" });
-    } catch (err) {
-      if (err instanceof ZodError) {
-        json(res, 400, {
-          error: "invalid_message",
-          message: err.errors[0]?.message ?? "Validation failed",
-        });
-      } else if (err instanceof BodyTooLargeError) {
-        json(res, 413, {
-          error: "body_too_large",
-          message: "Request body exceeds limit",
-        });
-      } else if (err instanceof SyntaxError) {
-        json(res, 400, { error: "invalid_json", message: "Malformed JSON" });
-      } else {
-        log("error", `unhandled: ${err}`);
-        json(res, 500, {
-          error: "internal_error",
-          message: "Internal server error",
-        });
-      }
-    }
-  });
-
-  const wss = new WebSocketServer({
-    noServer: true,
-    maxPayload: MAX_WS_MESSAGE_SIZE,
-  });
-
-  // Loaded on demand: v1 users on older Node never touch node:sqlite.
-  const relay = options.relayDataPath ? await startRelay(options.relayDataPath, log) : undefined;
-
-  server.on("upgrade", (request, socket, head) => {
-    const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
-
-    if (relay && url.pathname === relay.path) {
-      relay.gateway.handleUpgrade(request, socket, head);
-      return;
-    }
-
-    // Tunnel WebSocket upgrade (for HMR etc.)
-    const tunnelParsed = parseTunnelPath(url.pathname);
-    if (tunnelParsed) {
-      const tunnelCookie = parseTunnelCookie(request);
-      const cookieToken = tunnelCookie?.sessionId === tunnelParsed.sessionId && tunnelCookie.port === tunnelParsed.port
-        ? tunnelCookie.token
-        : undefined;
-      wss.handleUpgrade(request, socket, head, (ws) => {
-        handleTunnelWsUpgrade(ws, tunnelParsed, url, sessionManager, tokenManager, cookieToken);
-      });
-      return;
-    }
-
-    // Tunnel WS fallback via cookie (for HMR paths like /_next/webpack-hmr)
-    const tunnelCookie = parseTunnelCookie(request);
-    if (tunnelCookie && shouldUseTunnelCookieFallback(request, url.pathname, (pathname) => pathname === "/ws")) {
-      const fallbackParsed = {
-        sessionId: tunnelCookie.sessionId,
-        port: tunnelCookie.port,
-        path: url.pathname,
-      };
-      wss.handleUpgrade(request, socket, head, (ws) => {
-        handleTunnelWsUpgrade(ws, fallbackParsed, url, sessionManager, tokenManager, tunnelCookie.token);
-      });
-      return;
-    }
-
-    if (url.pathname !== "/ws") {
-      socket.destroy();
-      return;
-    }
-    wss.handleUpgrade(request, socket, head, (ws) => {
-      wss.emit("connection", ws, request, url);
-    });
-  });
-
-  wss.on(
-    "connection",
-    (socket: WebSocket, _request: IncomingMessage, url: URL) => {
-      const sessionId = url.searchParams.get("sessionId");
-      const role = url.searchParams.get("role") as "host" | "client" | "watcher" | null;
-
-      if (role === "watcher") {
-        const token = url.searchParams.get("token");
-        if (!token || !tokenManager.validate(token)) {
-          socket.close(4001, "unauthorized");
-          return;
-        }
-        startPresenceWatcher({
-          socket,
-          sessions: sessionManager,
-          hub: presenceHub,
-          sessionIds: () => tokenManager.getSessionIds(token),
-          pingIntervalMs: PING_INTERVAL,
-        });
-        return;
-      }
-
-      if (!sessionId || !role || (role !== "host" && role !== "client")) {
-        socket.close(1008, "missing sessionId or role");
-        return;
-      }
-
-      const deviceId = url.searchParams.get("deviceId") ?? randomUUID();
-
-      if (role === "client") {
-        const token = url.searchParams.get("token");
-        if (!token || !tokenManager.owns(token, sessionId)) {
-          socket.close(4001, "unauthorized");
-          return;
-        }
-      }
-
-      const device = { socket, role, deviceId, connectedAt: Date.now() };
-
-      if (role === "host") {
-        const existingSession = sessionManager.get(sessionId);
-        const isReconnect =
-          existingSession &&
-          existingSession.clients.size > 0 &&
-          existingSession.state === "host_disconnected";
-        sessionManager.setHost(sessionId, device);
-        if (isReconnect) {
-          const notification = serializeEnvelope(
-            createEnvelope({
-              type: "session.host_reconnected",
-              sessionId,
-              payload: {},
-            }),
-          );
-          for (const [, client] of existingSession.clients) {
-            if (client.socket.readyState === client.socket.OPEN)
-              client.socket.send(notification);
-          }
-        }
-      } else {
-        sessionManager.addClient(sessionId, device);
-      }
-
-      socket.send(
-        serializeEnvelope(
-          createEnvelope({
-            type: "session.connect",
-            sessionId,
-            payload: {
-              role,
-              clientName: deviceId,
-              protocolVersion: PROTOCOL_VERSION,
-            },
-          }),
-        ),
-      );
-
-      if (role === "client") {
-        replayAgentToSocket(socket, sessionId, sessionManager);
-      }
-
-      // Ping/pong for liveness — terminate sockets that stop answering pings.
-      const liveSocket = socket as WebSocket & { isAlive?: boolean };
-      liveSocket.isAlive = true;
-      socket.on("pong", () => {
-        liveSocket.isAlive = true;
-      });
-      const pingTimer = setInterval(() => {
-        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) => {
-        try {
-          handleSocketMessage(
-            socket,
-            data.toString(),
-            role,
-            sessionId,
-            deviceId,
-            sessionManager,
-          );
-        } catch (err) {
-          log("error", `unhandled websocket message error for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
-          if (socket.readyState === socket.OPEN) {
-            socket.send(
-              serializeEnvelope(
-                createEnvelope({
-                  type: "session.error",
-                  sessionId,
-                  payload: {
-                    code: "invalid_message",
-                    message: "Failed to handle message",
-                  },
-                }),
-              ),
-            );
-          }
-        }
-      });
-
-      socket.on("close", () => {
-        clearInterval(pingTimer);
-        if (role === "host") {
-          const result = sessionManager.removeHost(sessionId);
-          if (result) {
-            const notification = serializeEnvelope(
-              createEnvelope({
-                type: "session.host_disconnected",
-                sessionId,
-                payload: { reason: "host connection closed" },
-              }),
-            );
-            for (const [, client] of result.clients) {
-              if (client.socket.readyState === client.socket.OPEN)
-                client.socket.send(notification);
-            }
-          }
-        } else {
-          sessionManager.removeClient(sessionId, deviceId);
-        }
-      });
-
-      socket.on("error", () => {});
-    },
-  );
-
-  return new Promise<EmbeddedGateway>((resolve, reject) => {
-    server.on("error", reject);
-    server.listen(targetPort, () => {
-      const addr = server.address();
-      const actualPort =
-        typeof addr === "object" && addr ? addr.port : targetPort;
-      log("info", `embedded gateway on port ${actualPort}`);
-      // Surface whether the bundled web SPA was found — the in-app WebView loads
-      // this gateway's "/", so a missing dist means a blank screen. Makes the
-      // LAN/self-hosted "WebView is blank" failure mode diagnosable from logs.
-      if (webEnabled()) {
-        log("info", `web UI served from ${webDistPath()}`);
-      } else {
-        log("warn", `web UI not bundled (WEB_DIST=${webDistPath()} has no index.html) — in-app agent console will be blank`);
-      }
-      resolve({
-        port: actualPort,
-        httpUrl: `http://127.0.0.1:${actualPort}`,
-        wsUrl: `ws://127.0.0.1:${actualPort}/ws`,
-        close: () =>
-          new Promise<void>((res) => {
-            wss.clients.forEach((ws) => ws.close(1001, "shutting down"));
-            sessionManager.destroy();
-            pairingManager.destroy();
-            tokenManager.destroy();
-            void relay?.gateway.stop();
-            server.close(() => res());
-          }),
-      });
-    });
-  });
-}
-
-async function startRelay(databasePath: string, log: (level: "debug" | "info" | "warn" | "error", message: string) => void) {
-  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-  if (major < 22 || (major === 22 && minor < 13)) {
-    log("warn", `v2 relay needs Node.js 22.13+ (this is ${process.version}); serving v1 only`);
-    return undefined;
-  }
-  const { mkdirSync } = await import("node:fs");
-  const { dirname } = await import("node:path");
-  const [{ Gateway }, { RELAY_PATH }] = await Promise.all([import("@linkshell/gateway-v2"), import("@linkshell/wire")]);
-  mkdirSync(dirname(databasePath), { recursive: true });
-  const gateway = new Gateway({ port: 0, databasePath, log: (message) => log("info", `[relay] ${message}`) });
-  gateway.attach();
-  log("info", `v2 relay on ${RELAY_PATH}`);
-  return { gateway, path: RELAY_PATH };
-}

package/src/host-auth.ts

@@ -1,88 +0,0 @@
-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?.();
-  }
-
-  /** Mint a fresh host token to hand to the CLI at pairing creation.
-   *
-   *  Deliberately does NOT create a binding yet: the binding is established
-   *  trust-on-first-use when the host first connects WITH this token (see
-   *  `adopt`). This keeps the gateway backward-compatible with older CLIs that
-   *  don't send a host token at all — they simply never create a binding and
-   *  are allowed as legacy hosts, instead of being locked out by an eager
-   *  binding they can't satisfy. The legitimate host connects milliseconds
-   *  after pairing, so the trust-on-first-use window is negligible. */
-  issue(_sessionId: string): string {
-    return randomUUID();
-  }
-
-  /** 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);
-  }
-}