@soleri/core 2.10.0 → 2.11.0

package/src/transport/token-auth.ts

@@ -0,0 +1,96 @@
+/**
+ * Token Authentication — bearer token generation, validation, and persistence.
+ *
+ * Uses constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks.
+ * Token priority: {AGENT_ID}_HTTP_TOKEN env > ~/.{agentId}/http-token file.
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Generate a 32-byte hex token (64 characters). */
+export function generateToken(): string {
+  return randomBytes(32).toString('hex');
+}
+
+/**
+ * Load token with priority: env var > file.
+ * The env var name is derived from the agentId: MY_AGENT_HTTP_TOKEN.
+ */
+export function loadToken(agentId: string): string | undefined {
+  // Environment variable takes priority
+  const envKey = `${agentId.replace(/-/g, '_').toUpperCase()}_HTTP_TOKEN`;
+  const envToken = process.env[envKey];
+  if (envToken && envToken.trim().length > 0) {
+    return envToken.trim();
+  }
+
+  // Fall back to file
+  const tokenFile = join(homedir(), `.${agentId}`, 'http-token');
+  try {
+    if (existsSync(tokenFile)) {
+      const fileToken = readFileSync(tokenFile, 'utf-8').trim();
+      if (fileToken.length > 0) return fileToken;
+    }
+  } catch {
+    // File read failed
+  }
+
+  return undefined;
+}
+
+/** Save token to ~/.{agentId}/http-token with 0600 permissions. */
+export function saveToken(agentId: string, token: string): void {
+  const dir = join(homedir(), `.${agentId}`);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'http-token'), token, { mode: 0o600 });
+}
+
+/** Load existing token or generate and save a new one. */
+export function getOrGenerateToken(agentId: string): string {
+  const existing = loadToken(agentId);
+  if (existing) return existing;
+  const token = generateToken();
+  saveToken(agentId, token);
+  return token;
+}
+
+/**
+ * Constant-time bearer token validation.
+ * Returns true if the Authorization header contains a valid Bearer token.
+ */
+export function validateBearerToken(authHeader: string | undefined, expected: string): boolean {
+  if (!authHeader || !authHeader.startsWith('Bearer ')) return false;
+
+  const provided = authHeader.slice(7);
+  const expectedBuf = Buffer.from(expected, 'utf-8');
+  const providedBuf = Buffer.from(provided, 'utf-8');
+
+  if (expectedBuf.length !== providedBuf.length) {
+    // Compare against self to avoid timing leak on length mismatch
+    timingSafeEqual(expectedBuf, expectedBuf);
+    return false;
+  }
+
+  return timingSafeEqual(providedBuf, expectedBuf);
+}
+
+/**
+ * Validate an incoming HTTP request's bearer token.
+ * Returns true if valid, sends 401 and returns false if not.
+ */
+export function authenticateRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  expectedToken: string,
+): boolean {
+  const authHeader = req.headers.authorization;
+  if (validateBearerToken(authHeader, expectedToken)) return true;
+
+  res.writeHead(401, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Unauthorized' }));
+  return false;
+}

package/src/transport/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Transport Types — configuration for HTTP/SSE transport layer.
+ */
+
+/** Supported transport modes */
+export type TransportMode = 'stdio' | 'http' | 'ws' | 'lsp';
+
+/** HTTP transport configuration */
+export interface HttpTransportConfig {
+  /** Port to listen on (default: 3100) */
+  port: number;
+  /** Host to bind to (default: 127.0.0.1) */
+  host: string;
+  /** CORS allowed origins (empty = no CORS headers) */
+  corsOrigins: string[];
+  /** Bearer token for authentication */
+  authToken: string;
+  /** Session TTL in milliseconds (default: 3600000 = 1 hour). 0 to disable. */
+  sessionTTL?: number;
+  /** Session reaper interval in milliseconds (default: 60000 = 1 minute) */
+  reaperInterval?: number;
+  /** Rate limit: max requests per window (default: 100) */
+  rateLimit?: number;
+  /** Rate limit window in milliseconds (default: 60000 = 1 minute) */
+  rateLimitWindow?: number;
+}
+
+/** WebSocket transport configuration */
+export interface WsTransportConfig {
+  /** Bearer token for authentication (validated on upgrade) */
+  authToken: string;
+  /** Heartbeat interval in ms (default: 30000). 0 to disable. */
+  heartbeatInterval?: number;
+  /** Max message size in bytes (default: 1MB) */
+  maxMessageSize?: number;
+  /** Session TTL in milliseconds (default: 3600000 = 1 hour). 0 to disable. */
+  sessionTTL?: number;
+  /** Session reaper interval in milliseconds (default: 60000 = 1 minute) */
+  reaperInterval?: number;
+}
+
+/** LSP transport configuration */
+export interface LspTransportConfig {
+  /** Agent capabilities to expose as LSP features */
+  capabilities?: LspCapabilities;
+}
+
+/** Which agent features to expose via LSP */
+export interface LspCapabilities {
+  /** Expose vault search as completions (default: true) */
+  completions?: boolean;
+  /** Expose quality gate violations as diagnostics (default: true) */
+  diagnostics?: boolean;
+  /** Expose pattern documentation as hover (default: true) */
+  hover?: boolean;
+  /** Expose agent ops as code actions (default: false) */
+  codeActions?: boolean;
+}
+
+/** Combined transport configuration */
+export interface TransportConfig {
+  mode: TransportMode;
+  http?: HttpTransportConfig;
+  ws?: WsTransportConfig;
+  lsp?: LspTransportConfig;
+}

package/src/transport/ws-server.ts

@@ -0,0 +1,415 @@
+/**
+ * WebSocket MCP Server — RFC 6455 implementation using only node:http + node:crypto.
+ *
+ * Provides bidirectional JSON-RPC 2.0 communication over WebSocket.
+ * Can run standalone or share an HTTP server with HttpMcpServer via upgrade handler.
+ *
+ * Features:
+ *   - RFC 6455 handshake (Sec-WebSocket-Key / Accept)
+ *   - Text frame encode/decode (opcode 0x1) with masking support
+ *   - Ping/pong heartbeat (configurable interval, default 30s)
+ *   - Bearer token auth on upgrade request
+ *   - Session management via shared SessionManager
+ *   - Max message size enforcement (default 1MB)
+ *   - Clean close handshake (opcode 0x8)
+ */
+
+import { createHash } from 'node:crypto';
+import { createServer, type Server, type IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { WsTransportConfig } from './types.js';
+import { validateBearerToken } from './token-auth.js';
+import { SessionManager, type Session } from './session-manager.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** RFC 6455 magic GUID for Sec-WebSocket-Accept */
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-5AB5A4085CE3';
+
+const DEFAULT_HEARTBEAT_MS = 30_000;
+const DEFAULT_MAX_MESSAGE_SIZE = 1_048_576; // 1 MB
+
+// Frame opcodes
+const OPCODE_TEXT = 0x01;
+const OPCODE_CLOSE = 0x08;
+const OPCODE_PING = 0x09;
+const OPCODE_PONG = 0x0a;
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface WsConnection {
+  /** Session associated with this connection */
+  session: Session;
+  /** The underlying TCP socket */
+  socket: Duplex;
+  /** Whether the connection is alive (for heartbeat) */
+  alive: boolean;
+}
+
+export interface WsServerCallbacks {
+  /** Called when a new WebSocket connection is established. Must create session. */
+  onConnect: (conn: WsConnection) => Promise<void>;
+  /** Called when a text message is received. */
+  onMessage: (conn: WsConnection, data: unknown) => Promise<void>;
+  /** Called when a connection is closed. */
+  onClose: (conn: WsConnection) => void;
+  /** Optional: called on errors. */
+  onError?: (conn: WsConnection, error: Error) => void;
+}
+
+export interface WsServerStats {
+  connections: number;
+  uptime: number;
+}
+
+// =============================================================================
+// WEBSOCKET SERVER
+// =============================================================================
+
+export class WsMcpServer {
+  private server: Server | undefined;
+  private ownServer = false; // true if we created the server ourselves
+  private sessions: SessionManager;
+  private config: WsTransportConfig;
+  private callbacks: WsServerCallbacks;
+  private connections = new Map<string, WsConnection>();
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  private startedAt = 0;
+
+  constructor(config: WsTransportConfig, callbacks: WsServerCallbacks) {
+    this.config = config;
+    this.callbacks = callbacks;
+    this.sessions = new SessionManager({
+      ttl: config.sessionTTL,
+      reaperInterval: config.reaperInterval,
+    });
+  }
+
+  /** Get the session manager. */
+  get sessionManager(): SessionManager {
+    return this.sessions;
+  }
+
+  /**
+   * Attach to an existing HTTP server as an upgrade handler.
+   * Call this instead of start() when sharing a server with HttpMcpServer.
+   */
+  attachTo(server: Server): void {
+    this.startedAt = Date.now();
+    this.server = server;
+    this.ownServer = false;
+    server.on('upgrade', (req, socket, head) => {
+      this.handleUpgrade(req, socket, head);
+    });
+    this.sessions.startReaper();
+    this.startHeartbeat();
+  }
+
+  /** Start a standalone WebSocket server. */
+  async start(port: number, host = '127.0.0.1'): Promise<void> {
+    this.startedAt = Date.now();
+    this.server = createServer((_req, res) => {
+      res.writeHead(426, { 'Content-Type': 'text/plain' });
+      res.end('Upgrade Required');
+    });
+    this.ownServer = true;
+
+    this.server.on('upgrade', (req, socket, head) => {
+      this.handleUpgrade(req, socket, head);
+    });
+
+    await new Promise<void>((resolve) => {
+      this.server!.listen(port, host, () => resolve());
+    });
+
+    this.sessions.startReaper();
+    this.startHeartbeat();
+  }
+
+  /** Stop the server and close all connections. */
+  async stop(): Promise<void> {
+    this.stopHeartbeat();
+    this.sessions.close();
+
+    // Close all WebSocket connections
+    for (const conn of this.connections.values()) {
+      this.sendClose(conn.socket, 1001, 'Server shutting down');
+      conn.socket.destroy();
+    }
+    this.connections.clear();
+
+    if (this.ownServer && this.server) {
+      await new Promise<void>((resolve, reject) => {
+        this.server!.close((err) => (err ? reject(err) : resolve()));
+      });
+      this.server = undefined;
+    }
+  }
+
+  /** Get server stats. */
+  getStats(): WsServerStats {
+    return {
+      connections: this.connections.size,
+      uptime: this.startedAt > 0 ? Date.now() - this.startedAt : 0,
+    };
+  }
+
+  /** Send a text message to a specific connection. */
+  send(sessionId: string, data: unknown): boolean {
+    const conn = this.connections.get(sessionId);
+    if (!conn) return false;
+    this.sendText(conn.socket, JSON.stringify(data));
+    return true;
+  }
+
+  /** Broadcast a text message to all connections. */
+  broadcast(data: unknown): number {
+    const text = JSON.stringify(data);
+    let count = 0;
+    for (const conn of this.connections.values()) {
+      this.sendText(conn.socket, text);
+      count++;
+    }
+    return count;
+  }
+
+  // ─── Upgrade Handling ──────────────────────────────────────────────
+
+  private handleUpgrade(req: IncomingMessage, socket: Duplex, _head: Buffer): void {
+    // Validate WebSocket upgrade headers
+    const upgradeHeader = req.headers.upgrade;
+    if (!upgradeHeader || upgradeHeader.toLowerCase() !== 'websocket') {
+      socket.destroy();
+      return;
+    }
+
+    const wsKey = req.headers['sec-websocket-key'];
+    if (!wsKey) {
+      socket.destroy();
+      return;
+    }
+
+    // Auth: extract token from query string or Authorization header
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    const queryToken = url.searchParams.get('token');
+    const authHeader = req.headers.authorization;
+    const tokenValid = queryToken
+      ? queryToken === this.config.authToken
+      : validateBearerToken(authHeader, this.config.authToken);
+
+    if (!tokenValid) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+
+    // Complete WebSocket handshake
+    const acceptKey = createHash('sha1')
+      .update(wsKey + WS_MAGIC)
+      .digest('base64');
+
+    const sessionId = this.sessions.generateId();
+
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\n' +
+        'Upgrade: websocket\r\n' +
+        'Connection: Upgrade\r\n' +
+        `Sec-WebSocket-Accept: ${acceptKey}\r\n` +
+        `mcp-session-id: ${sessionId}\r\n` +
+        '\r\n',
+    );
+
+    // Create session and connection
+    const session = this.sessions.add(sessionId, socket, null);
+    const conn: WsConnection = { session, socket, alive: true };
+    this.connections.set(sessionId, conn);
+
+    // Set up frame reader
+    const maxSize = this.config.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE;
+    let buffer = Buffer.alloc(0);
+
+    socket.on('data', (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+
+      // Process all complete frames in the buffer
+      while (buffer.length >= 2) {
+        const frame = this.parseFrame(buffer);
+        if (!frame) break; // incomplete frame
+
+        buffer = buffer.subarray(frame.totalLength);
+
+        if (frame.opcode === OPCODE_TEXT) {
+          if (frame.payload.length > maxSize) {
+            this.sendClose(socket, 1009, 'Message too large');
+            socket.destroy();
+            return;
+          }
+          const text = frame.payload.toString('utf-8');
+          try {
+            const parsed: unknown = JSON.parse(text);
+            this.callbacks.onMessage(conn, parsed).catch((err) => {
+              this.callbacks.onError?.(conn, err instanceof Error ? err : new Error(String(err)));
+            });
+          } catch {
+            // Invalid JSON — ignore or notify
+            this.callbacks.onError?.(conn, new Error('Invalid JSON received'));
+          }
+        } else if (frame.opcode === OPCODE_PING) {
+          this.sendPong(socket, frame.payload);
+        } else if (frame.opcode === OPCODE_PONG) {
+          conn.alive = true;
+        } else if (frame.opcode === OPCODE_CLOSE) {
+          this.sendClose(socket, 1000, '');
+          socket.destroy();
+        }
+      }
+    });
+
+    // Cleanup on disconnect — guard against double-fire from close+end+error
+    let cleaned = false;
+    const cleanup = (err?: Error) => {
+      if (cleaned) return;
+      cleaned = true;
+      this.connections.delete(sessionId);
+      this.sessions.remove(sessionId);
+      if (err) this.callbacks.onError?.(conn, err);
+      this.callbacks.onClose(conn);
+    };
+
+    socket.on('close', () => cleanup());
+    socket.on('end', () => cleanup());
+    socket.on('error', (err) => cleanup(err));
+
+    // Notify callback
+    this.callbacks.onConnect(conn).catch((err) => {
+      this.callbacks.onError?.(conn, err instanceof Error ? err : new Error(String(err)));
+    });
+  }
+
+  // ─── Frame Parsing (RFC 6455) ──────────────────────────────────────
+
+  private parseFrame(buf: Buffer): { opcode: number; payload: Buffer; totalLength: number } | null {
+    if (buf.length < 2) return null;
+
+    const opcode = buf[0] & 0x0f;
+    const masked = (buf[1] & 0x80) !== 0;
+    let payloadLength = buf[1] & 0x7f;
+    let offset = 2;
+
+    if (payloadLength === 126) {
+      if (buf.length < 4) return null;
+      payloadLength = buf.readUInt16BE(2);
+      offset = 4;
+    } else if (payloadLength === 127) {
+      if (buf.length < 10) return null;
+      // Read as 64-bit, but JS numbers are limited to 2^53
+      payloadLength = Number(buf.readBigUInt64BE(2));
+      offset = 10;
+    }
+
+    const maskSize = masked ? 4 : 0;
+    const totalLength = offset + maskSize + payloadLength;
+    if (buf.length < totalLength) return null;
+
+    let payload: Buffer;
+    if (masked) {
+      const mask = buf.subarray(offset, offset + 4);
+      payload = Buffer.alloc(payloadLength);
+      for (let i = 0; i < payloadLength; i++) {
+        payload[i] = buf[offset + 4 + i] ^ mask[i & 3];
+      }
+    } else {
+      payload = buf.subarray(offset, offset + payloadLength);
+    }
+
+    return { opcode, payload, totalLength };
+  }
+
+  // ─── Frame Encoding ────────────────────────────────────────────────
+
+  private encodeFrame(opcode: number, payload: Buffer): Buffer {
+    const len = payload.length;
+    let header: Buffer;
+
+    if (len < 126) {
+      header = Buffer.alloc(2);
+      header[0] = 0x80 | opcode; // FIN + opcode
+      header[1] = len;
+    } else if (len < 65536) {
+      header = Buffer.alloc(4);
+      header[0] = 0x80 | opcode;
+      header[1] = 126;
+      header.writeUInt16BE(len, 2);
+    } else {
+      header = Buffer.alloc(10);
+      header[0] = 0x80 | opcode;
+      header[1] = 127;
+      header.writeBigUInt64BE(BigInt(len), 2);
+    }
+
+    return Buffer.concat([header, payload]);
+  }
+
+  private sendText(socket: Duplex, text: string): void {
+    const payload = Buffer.from(text, 'utf-8');
+    const frame = this.encodeFrame(OPCODE_TEXT, payload);
+    socket.write(frame);
+  }
+
+  private sendPong(socket: Duplex, payload: Buffer): void {
+    const frame = this.encodeFrame(OPCODE_PONG, payload);
+    socket.write(frame);
+  }
+
+  private sendClose(socket: Duplex, code: number, reason: string): void {
+    const reasonBuf = Buffer.from(reason, 'utf-8');
+    const payload = Buffer.alloc(2 + reasonBuf.length);
+    payload.writeUInt16BE(code, 0);
+    reasonBuf.copy(payload, 2);
+    const frame = this.encodeFrame(OPCODE_CLOSE, payload);
+    socket.write(frame);
+  }
+
+  // ─── Heartbeat ─────────────────────────────────────────────────────
+
+  private startHeartbeat(): void {
+    const interval = this.config.heartbeatInterval ?? DEFAULT_HEARTBEAT_MS;
+    if (interval <= 0) return;
+
+    this.heartbeatTimer = setInterval(() => {
+      for (const [id, conn] of this.connections) {
+        if (!conn.alive) {
+          // No pong received since last ping — dead connection
+          this.sendClose(conn.socket, 1001, 'Heartbeat timeout');
+          conn.socket.destroy();
+          this.connections.delete(id);
+          this.sessions.remove(id);
+          this.callbacks.onClose(conn);
+          continue;
+        }
+        conn.alive = false;
+        const ping = this.encodeFrame(OPCODE_PING, Buffer.alloc(0));
+        conn.socket.write(ping);
+      }
+    }, interval);
+
+    if (
+      this.heartbeatTimer &&
+      typeof this.heartbeatTimer === 'object' &&
+      'unref' in this.heartbeatTimer
+    ) {
+      (this.heartbeatTimer as NodeJS.Timeout).unref();
+    }
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+  }
+}