@soleri/core 9.0.4 → 9.3.0

package/src/transport/session-manager.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Session Manager Tests — session CRUD, expiry, and reaping.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { SessionManager } from './session-manager.js';
+
+describe('SessionManager', () => {
+  let manager: SessionManager;
+
+  beforeEach(() => {
+    manager = new SessionManager();
+  });
+
+  afterEach(() => {
+    manager.close();
+  });
+
+  describe('generateId', () => {
+    it('returns a UUID string', () => {
+      const id = manager.generateId();
+      expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    });
+
+    it('generates unique IDs', () => {
+      const ids = new Set(Array.from({ length: 10 }, () => manager.generateId()));
+      expect(ids.size).toBe(10);
+    });
+  });
+
+  describe('add / get / remove', () => {
+    it('adds and retrieves a session', () => {
+      const session = manager.add('s1', 'transport', 'server');
+      expect(session.id).toBe('s1');
+      expect(session.transport).toBe('transport');
+      expect(session.server).toBe('server');
+      expect(session.createdAt).toBeGreaterThan(0);
+      expect(manager.get('s1')).toBe(session);
+    });
+
+    it('returns undefined for missing session', () => {
+      expect(manager.get('nonexistent')).toBeUndefined();
+    });
+
+    it('removes a session', () => {
+      manager.add('s1', null, null);
+      expect(manager.remove('s1')).toBe(true);
+      expect(manager.get('s1')).toBeUndefined();
+    });
+
+    it('returns false when removing nonexistent session', () => {
+      expect(manager.remove('nope')).toBe(false);
+    });
+  });
+
+  describe('size', () => {
+    it('starts at zero', () => {
+      expect(manager.size).toBe(0);
+    });
+
+    it('reflects additions and removals', () => {
+      manager.add('s1', null, null);
+      manager.add('s2', null, null);
+      expect(manager.size).toBe(2);
+      manager.remove('s1');
+      expect(manager.size).toBe(1);
+    });
+  });
+
+  describe('listIds', () => {
+    it('returns all session IDs', () => {
+      manager.add('a', null, null);
+      manager.add('b', null, null);
+      const ids = manager.listIds();
+      expect(ids).toContain('a');
+      expect(ids).toContain('b');
+      expect(ids).toHaveLength(2);
+    });
+  });
+
+  describe('close', () => {
+    it('clears all sessions and stops reaper', () => {
+      manager.add('s1', null, null);
+      manager.add('s2', null, null);
+      manager.startReaper();
+      manager.close();
+      expect(manager.size).toBe(0);
+    });
+  });
+
+  describe('reaper', () => {
+    it('does not start when ttl is 0', () => {
+      const m = new SessionManager({ ttl: 0 });
+      m.startReaper();
+      m.add('s1', null, null);
+      // No timer should be running - just verify it doesn't throw
+      m.close();
+    });
+
+    it('reaps expired sessions', async () => {
+      const onReap = vi.fn();
+      const m = new SessionManager({ ttl: 30, reaperInterval: 20, onReap });
+      m.add('s1', null, null);
+      m.startReaper();
+
+      await new Promise((r) => setTimeout(r, 80));
+      expect(m.size).toBe(0);
+      expect(onReap).toHaveBeenCalledTimes(1);
+      expect(onReap.mock.calls[0][0].id).toBe('s1');
+      m.close();
+    });
+
+    it('keeps fresh sessions alive', async () => {
+      const m = new SessionManager({ ttl: 200, reaperInterval: 20 });
+      m.add('s1', null, null);
+      m.startReaper();
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(m.size).toBe(1);
+      m.close();
+    });
+
+    it('stopReaper prevents further reaping', () => {
+      const m = new SessionManager({ ttl: 50, reaperInterval: 20 });
+      m.startReaper();
+      m.stopReaper();
+      m.add('s1', null, null);
+      // Session should remain because reaper is stopped
+      expect(m.size).toBe(1);
+      m.close();
+    });
+  });
+});

package/src/transport/token-auth.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Token Auth Tests — token generation, validation, persistence, and request auth.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  generateToken,
+  validateBearerToken,
+  authenticateRequest,
+  loadToken,
+} from './token-auth.js';
+
+describe('generateToken', () => {
+  it('returns a 64-character hex string', () => {
+    const token = generateToken();
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('generates unique tokens', () => {
+    const tokens = new Set(Array.from({ length: 10 }, () => generateToken()));
+    expect(tokens.size).toBe(10);
+  });
+});
+
+describe('validateBearerToken', () => {
+  const expected = 'secret-token-123';
+
+  it('returns true for valid bearer token', () => {
+    expect(validateBearerToken('Bearer secret-token-123', expected)).toBe(true);
+  });
+
+  it('returns false for missing header', () => {
+    expect(validateBearerToken(undefined, expected)).toBe(false);
+  });
+
+  it('returns false for wrong prefix', () => {
+    expect(validateBearerToken('Basic secret-token-123', expected)).toBe(false);
+  });
+
+  it('returns false for wrong token', () => {
+    expect(validateBearerToken('Bearer wrong-token', expected)).toBe(false);
+  });
+
+  it('returns false for empty string', () => {
+    expect(validateBearerToken('', expected)).toBe(false);
+  });
+
+  it('returns false for length mismatch', () => {
+    expect(validateBearerToken('Bearer short', expected)).toBe(false);
+  });
+});
+
+describe('authenticateRequest', () => {
+  const token = 'test-token';
+
+  function makeReq(authorization?: string) {
+    return { headers: { authorization } } as unknown;
+  }
+
+  function makeRes() {
+    const res: Record<string, unknown> = {
+      writeHead: vi.fn().mockReturnThis(),
+      end: vi.fn(),
+    };
+    return res;
+  }
+
+  it('returns true for valid auth', () => {
+    const result = authenticateRequest(makeReq(`Bearer ${token}`), makeRes(), token);
+    expect(result).toBe(true);
+  });
+
+  it('returns false and sends 401 for invalid auth', () => {
+    const res = makeRes();
+    const result = authenticateRequest(makeReq('Bearer wrong'), res, token);
+    expect(result).toBe(false);
+    expect(res.writeHead).toHaveBeenCalledWith(401, { 'Content-Type': 'application/json' });
+    expect(res.end).toHaveBeenCalled();
+  });
+
+  it('returns false when no auth header present', () => {
+    const res = makeRes();
+    const result = authenticateRequest(makeReq(), res, token);
+    expect(result).toBe(false);
+    expect(res.writeHead).toHaveBeenCalledWith(401, expect.any(Object));
+  });
+});
+
+describe('loadToken / saveToken / getOrGenerateToken', () => {
+  let tmpDir: string;
+  const _agentId = 'test-agent';
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'token-auth-test-'));
+    // Override homedir by setting the env and using a custom agent path
+    vi.stubEnv('TEST_AGENT_HTTP_TOKEN', '');
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('loadToken returns undefined when no env or file exists', () => {
+    const result = loadToken('nonexistent-agent-xyz');
+    expect(result).toBeUndefined();
+  });
+
+  it('loadToken reads from environment variable', () => {
+    vi.stubEnv('MY_AGENT_HTTP_TOKEN', 'env-token-value');
+    const result = loadToken('my-agent');
+    expect(result).toBe('env-token-value');
+  });
+
+  it('loadToken trims whitespace from env var', () => {
+    vi.stubEnv('MY_AGENT_HTTP_TOKEN', '  trimmed-token  ');
+    const result = loadToken('my-agent');
+    expect(result).toBe('trimmed-token');
+  });
+
+  it('loadToken returns undefined for empty env var', () => {
+    vi.stubEnv('MY_AGENT_HTTP_TOKEN', '   ');
+    const result = loadToken('my-agent');
+    // Falls through to file-based lookup
+    expect(result === undefined || typeof result === 'string').toBe(true);
+  });
+
+  it('generateToken produces different tokens each call', () => {
+    const t1 = generateToken();
+    const t2 = generateToken();
+    expect(t1).not.toBe(t2);
+  });
+});

package/src/transport/ws-server.test.ts

@@ -0,0 +1,297 @@
+/**
+ * WebSocket MCP Server Tests — handshake, messaging, heartbeat, lifecycle.
+ *
+ * Tests the WsMcpServer using a real localhost server but no external connections.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createHash } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import { connect } from 'node:net';
+import { WsMcpServer, type WsServerCallbacks } from './ws-server.js';
+
+const AUTH_TOKEN = 'ws-test-token';
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-5AB5A4085CE3';
+
+function defaultCallbacks(): WsServerCallbacks {
+  return {
+    onConnect: vi.fn(async () => {}),
+    onMessage: vi.fn(async () => {}),
+    onClose: vi.fn(),
+    onError: vi.fn(),
+  };
+}
+
+/** Build a raw WebSocket upgrade request */
+function buildUpgradeRequest(opts?: { token?: string; key?: string; path?: string }): string {
+  const key = opts?.key ?? 'dGhlIHNhbXBsZSBub25jZQ==';
+  const token = opts?.token ?? AUTH_TOKEN;
+  const path = opts?.path ?? `/?token=${token}`;
+  return [
+    `GET ${path} HTTP/1.1`,
+    'Host: localhost',
+    'Upgrade: websocket',
+    'Connection: Upgrade',
+    `Sec-WebSocket-Key: ${key}`,
+    'Sec-WebSocket-Version: 13',
+    '',
+    '',
+  ].join('\r\n');
+}
+
+/** Encode a WebSocket text frame (unmasked, for reading) / masked for sending to server */
+function encodeTextFrame(text: string, masked = true): Buffer {
+  const payload = Buffer.from(text, 'utf-8');
+  const len = payload.length;
+  let header: Buffer;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = 0x81; // FIN + TEXT
+    header[1] = masked ? len | 0x80 : len;
+  } else {
+    header = Buffer.alloc(4);
+    header[0] = 0x81;
+    header[1] = masked ? 126 | 0x80 : 126;
+    header.writeUInt16BE(len, 2);
+  }
+
+  if (masked) {
+    const mask = Buffer.from([0x12, 0x34, 0x56, 0x78]);
+    const maskedPayload = Buffer.alloc(payload.length);
+    for (let i = 0; i < payload.length; i++) {
+      maskedPayload[i] = payload[i] ^ mask[i & 3];
+    }
+    return Buffer.concat([header, mask, maskedPayload]);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+describe('WsMcpServer', () => {
+  let server: WsMcpServer;
+  let callbacks: WsServerCallbacks;
+
+  beforeEach(() => {
+    callbacks = defaultCallbacks();
+    server = new WsMcpServer(
+      { authToken: AUTH_TOKEN, heartbeatInterval: 0, sessionTTL: 0 },
+      callbacks,
+    );
+  });
+
+  afterEach(async () => {
+    // The WsMcpServer.stop() can hang when the underlying HTTP server
+    // waits for upgraded WebSocket connections to drain. Force-destroy.
+    const httpServer = (server as unknown).server as Server | undefined;
+    if (httpServer) {
+      // Force immediate close of all tracked sockets
+      for (const conn of ((server as unknown).connections as Map<string, unknown>)?.values() ??
+        []) {
+        conn.socket?.destroy();
+      }
+      ((server as unknown).connections as Map<string, unknown>)?.clear();
+      // Close with a force-destroy fallback
+      await Promise.race([
+        server.stop(),
+        new Promise<void>((resolve) => {
+          setTimeout(() => {
+            httpServer.closeAllConnections?.();
+            httpServer.close(() => {});
+            (server as unknown).server = undefined;
+            resolve();
+          }, 200);
+        }),
+      ]);
+    } else {
+      await server.stop().catch(() => {});
+    }
+  });
+
+  describe('construction', () => {
+    it('exposes sessionManager', () => {
+      expect(server.sessionManager).toBeDefined();
+      expect(server.sessionManager.size).toBe(0);
+    });
+
+    it('reports zero stats before start', () => {
+      const stats = server.getStats();
+      expect(stats.connections).toBe(0);
+      expect(stats.uptime).toBe(0);
+    });
+  });
+
+  describe('standalone start / stop', () => {
+    it('starts and stops without error', async () => {
+      await server.start(0);
+      expect(server.getStats().uptime).toBeGreaterThanOrEqual(0);
+      await server.stop();
+    });
+
+    it('stop is idempotent', async () => {
+      await server.start(0);
+      await server.stop();
+      await server.stop();
+    });
+  });
+
+  describe('attachTo', () => {
+    it('attaches to an existing HTTP server', async () => {
+      const httpServer = createServer();
+      await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve));
+
+      const wsServer = new WsMcpServer(
+        { authToken: AUTH_TOKEN, heartbeatInterval: 0, sessionTTL: 0 },
+        callbacks,
+      );
+      wsServer.attachTo(httpServer);
+      expect(wsServer.getStats().uptime).toBeGreaterThanOrEqual(0);
+
+      await wsServer.stop();
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      });
+    });
+  });
+
+  describe('WebSocket handshake', () => {
+    it('completes handshake with valid token', async () => {
+      await server.start(0);
+      const addr = (server as unknown).server?.address();
+      if (!addr || typeof addr === 'string') return;
+
+      const wsKey = 'dGhlIHNhbXBsZSBub25jZQ==';
+      const expectedAccept = createHash('sha1')
+        .update(wsKey + WS_MAGIC)
+        .digest('base64');
+
+      const socket = connect(addr.port, '127.0.0.1');
+      await new Promise<void>((resolve) => socket.on('connect', resolve));
+
+      socket.write(buildUpgradeRequest({ key: wsKey }));
+
+      const response = await new Promise<string>((resolve) => {
+        socket.once('data', (data) => resolve(data.toString()));
+      });
+
+      expect(response).toContain('101 Switching Protocols');
+      expect(response).toContain(`Sec-WebSocket-Accept: ${expectedAccept}`);
+      expect(response).toContain('mcp-session-id:');
+
+      // Wait for onConnect callback
+      await new Promise((r) => setTimeout(r, 50));
+      expect(callbacks.onConnect).toHaveBeenCalled();
+
+      socket.destroy();
+    });
+
+    it('rejects connection with invalid token', async () => {
+      await server.start(0);
+      const addr = (server as unknown).server?.address();
+      if (!addr || typeof addr === 'string') return;
+
+      const socket = connect(addr.port, '127.0.0.1');
+      await new Promise<void>((resolve) => socket.on('connect', resolve));
+
+      socket.write(buildUpgradeRequest({ token: 'wrong-token' }));
+
+      const response = await new Promise<string>((resolve) => {
+        socket.once('data', (data) => resolve(data.toString()));
+      });
+
+      expect(response).toContain('401');
+      socket.destroy();
+    });
+
+    it('supports Authorization header auth', async () => {
+      await server.start(0);
+      const addr = (server as unknown).server?.address();
+      if (!addr || typeof addr === 'string') return;
+
+      const socket = connect(addr.port, '127.0.0.1');
+      await new Promise<void>((resolve) => socket.on('connect', resolve));
+
+      const request = [
+        'GET / HTTP/1.1',
+        'Host: localhost',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==',
+        'Sec-WebSocket-Version: 13',
+        `Authorization: Bearer ${AUTH_TOKEN}`,
+        '',
+        '',
+      ].join('\r\n');
+
+      socket.write(request);
+
+      const response = await new Promise<string>((resolve) => {
+        socket.once('data', (data) => resolve(data.toString()));
+      });
+
+      expect(response).toContain('101 Switching Protocols');
+      socket.destroy();
+    });
+  });
+
+  describe('send / broadcast', () => {
+    it('send returns false for unknown session', () => {
+      expect(server.send('nonexistent', { test: true })).toBe(false);
+    });
+
+    it('broadcast returns 0 with no connections', () => {
+      expect(server.broadcast({ test: true })).toBe(0);
+    });
+  });
+
+  describe('message handling', () => {
+    it('calls onMessage for valid JSON text frames', async () => {
+      await server.start(0);
+      const addr = (server as unknown).server?.address();
+      if (!addr || typeof addr === 'string') return;
+
+      const socket = connect(addr.port, '127.0.0.1');
+      await new Promise<void>((resolve) => socket.on('connect', resolve));
+      socket.write(buildUpgradeRequest());
+
+      // Wait for handshake
+      await new Promise<string>((resolve) => {
+        socket.once('data', (data) => resolve(data.toString()));
+      });
+
+      // Wait for onConnect
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Send a masked text frame
+      const frame = encodeTextFrame(JSON.stringify({ method: 'test' }));
+      socket.write(frame);
+
+      await new Promise((r) => setTimeout(r, 100));
+      expect(callbacks.onMessage).toHaveBeenCalled();
+
+      socket.destroy();
+    });
+  });
+
+  describe('cleanup on stop', () => {
+    it('cleans up connections when server stops', async () => {
+      await server.start(0);
+      const addr = (server as unknown).server?.address();
+      if (!addr || typeof addr === 'string') return;
+
+      const socket = connect(addr.port, '127.0.0.1');
+      await new Promise<void>((resolve) => socket.on('connect', resolve));
+      socket.write(buildUpgradeRequest());
+      await new Promise<string>((resolve) => {
+        socket.once('data', (data) => resolve(data.toString()));
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(server.getStats().connections).toBe(1);
+
+      // server.stop() closes all connections and destroys sockets
+      socket.destroy();
+      await new Promise((r) => setTimeout(r, 50));
+    });
+  });
+});

package/src/update-check.ts

@@ -0,0 +1,111 @@
+/**
+ * Lightweight update notification — checks npm registry for newer @soleri/core.
+ *
+ * - Non-blocking: call without await, notifications appear in stderr
+ * - Rate-limited: at most once per 24 hours via cache file
+ * - Opt-out: set SOLERI_NO_UPDATE_CHECK=1
+ * - Zero dependencies: uses Node.js built-in fetch()
+ */
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { SOLERI_HOME, usedLegacyFallback } from './paths.js';
+
+const CACHE_FILE = join(SOLERI_HOME, 'update-check.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@soleri/core/latest';
+const FETCH_TIMEOUT_MS = 5_000;
+
+interface CacheEntry {
+  checkedAt: number;
+  latestVersion: string | null;
+}
+
+function readCache(): CacheEntry | null {
+  try {
+    if (!existsSync(CACHE_FILE)) return null;
+    return JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(entry: CacheEntry): void {
+  try {
+    mkdirSync(SOLERI_HOME, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(entry), 'utf-8');
+  } catch {
+    // Non-critical — skip silently
+  }
+}
+
+/**
+ * Simple semver comparison: returns true if b is newer than a.
+ * Handles x.y.z format only (no pre-release tags).
+ */
+function isNewer(current: string, latest: string): boolean {
+  const a = current.split('.').map(Number);
+  const b = latest.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((b[i] ?? 0) > (a[i] ?? 0)) return true;
+    if ((b[i] ?? 0) < (a[i] ?? 0)) return false;
+  }
+  return false;
+}
+
+/**
+ * Check for updates and emit stderr notifications.
+ * Call fire-and-forget (no await needed). Never throws.
+ */
+export async function checkForUpdate(agentId: string, currentVersion: string): Promise<void> {
+  // Opt-out via env var
+  if (process.env.SOLERI_NO_UPDATE_CHECK === '1') return;
+
+  const tag = '[soleri]';
+
+  // Migration notification (always check, regardless of rate limit)
+  if (usedLegacyFallback(agentId)) {
+    console.error(
+      `${tag} Migration available: run "soleri agent migrate ${agentId}" to consolidate data under ~/.soleri/`,
+    );
+  }
+
+  // Rate limit: skip if checked recently
+  const cache = readCache();
+  if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS) {
+    // Use cached result
+    if (cache.latestVersion && isNewer(currentVersion, cache.latestVersion)) {
+      console.error(
+        `${tag} Update available: @soleri/core ${currentVersion} → ${cache.latestVersion}`,
+      );
+      console.error(`${tag} Run: soleri agent update`);
+    }
+    return;
+  }
+
+  // Fetch latest version from npm
+  try {
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { Accept: 'application/json' },
+    });
+
+    if (!response.ok) {
+      writeCache({ checkedAt: Date.now(), latestVersion: null });
+      return;
+    }
+
+    const data = (await response.json()) as { version?: string };
+    const latestVersion = data.version ?? null;
+
+    writeCache({ checkedAt: Date.now(), latestVersion });
+
+    if (latestVersion && isNewer(currentVersion, latestVersion)) {
+      console.error(`${tag} Update available: @soleri/core ${currentVersion} → ${latestVersion}`);
+      console.error(`${tag} Run: soleri agent update`);
+    }
+  } catch {
+    // Network error, timeout, etc. — fail silently
+    writeCache({ checkedAt: Date.now(), latestVersion: null });
+  }
+}