spck 0.3.1

package/src/services/TerminalService.ts

@@ -0,0 +1,413 @@
+/**
+ * Terminal service - manages PTY sessions with xterm-headless
+ */
+
+import * as pty from 'node-pty';
+import XtermHeadlessModule from '@xterm/headless';
+import SerializeAddonModule from '@xterm/addon-serialize';
+import defaultShell from 'default-shell';
+import { AuthenticatedSocket, ErrorCode, createRPCError } from '../types.js';
+import { logTerminalRead, logTerminalWrite } from '../utils/logger.js';
+
+const { Terminal: XtermHeadless } = XtermHeadlessModule as any;
+const { SerializeAddon } = SerializeAddonModule as any;
+
+// Hard limit on terminal buffer size to prevent memory exhaustion (DoS)
+const MAX_BUFFER_LINES_HARD_LIMIT = 50000;
+
+interface TerminalSession {
+  id: string;
+  pty: pty.IPty;
+  xterm: any;
+  serializeAddon: any;
+  cols: number;
+  rows: number;
+  exited: boolean;
+  exitCode?: number;
+  uid: string;
+  pendingWrites: number; // Track number of pending write operations
+}
+
+export class TerminalService {
+  private sessions: Map<string, TerminalSession> = new Map();
+  private activeTerminalId: string | null = null;
+
+  constructor(
+    private getSocket: () => AuthenticatedSocket,
+    private maxTerminals: number = 10,
+    private maxBufferedLines: number = 10000,
+    private rootPath: string = process.cwd()
+  ) {
+    // Enforce hard limit on buffer size to prevent memory exhaustion
+    if (this.maxBufferedLines > MAX_BUFFER_LINES_HARD_LIMIT) {
+      console.warn(
+        `Terminal buffer size ${this.maxBufferedLines} exceeds hard limit ${MAX_BUFFER_LINES_HARD_LIMIT}. ` +
+        `Capping at ${MAX_BUFFER_LINES_HARD_LIMIT} lines.`
+      );
+      this.maxBufferedLines = MAX_BUFFER_LINES_HARD_LIMIT;
+    }
+  }
+
+  /**
+   * Get UID from socket with fallback
+   */
+  private getUid(): string {
+    return this.getSocket().data?.uid || 'unknown';
+  }
+
+  /**
+   * Handle terminal RPC methods
+   */
+  async handle(method: string, params: any): Promise<any> {
+    const uid = this.getUid();
+    let result: any;
+    let error: any;
+
+    // Define read and write operations
+    const readOps = ['list', 'refresh'];
+    const writeOps = ['create', 'destroy', 'activate', 'send', 'resize'];
+
+    try {
+      switch (method) {
+        case 'create':
+          result = await this.create(params);
+          logTerminalWrite(method, params, uid, true, undefined, { terminalId: result });
+          return result;
+        case 'destroy':
+          result = await this.destroy(params);
+          logTerminalWrite(method, params, uid, true);
+          return result;
+        case 'activate':
+          result = await this.activate(params);
+          logTerminalWrite(method, params, uid, true);
+          return result;
+        case 'send':
+          result = await this.send(params);
+          logTerminalWrite(method, params, uid, true);
+          return result;
+        case 'resize':
+          result = await this.resize(params);
+          logTerminalWrite(method, params, uid, true);
+          return result;
+        case 'refresh':
+          result = await this.refresh(params);
+          logTerminalRead(method, params, uid, true);
+          return result;
+        case 'list':
+          result = await this.list();
+          logTerminalRead(method, params, uid, true, undefined, { count: result.length });
+          return result;
+        default:
+          throw createRPCError(ErrorCode.METHOD_NOT_FOUND, `Method not found: terminal.${method}`);
+      }
+    } catch (err: any) {
+      error = err;
+      // Log error based on operation type
+      if (readOps.includes(method)) {
+        logTerminalRead(method, params, uid, false, error);
+      } else if (writeOps.includes(method)) {
+        logTerminalWrite(method, params, uid, false, error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Create new terminal session
+   */
+  private async create(params: { cols: number; rows: number }): Promise<string> {
+    const uid = this.getUid();
+
+    // Check terminal limit
+    const userTerminals = Array.from(this.sessions.values()).filter((s) => s.uid === uid);
+
+    if (userTerminals.length >= this.maxTerminals) {
+      throw createRPCError(
+        ErrorCode.TERMINAL_LIMIT_EXCEEDED,
+        `Terminal limit exceeded (max ${this.maxTerminals})`
+      );
+    }
+
+    const terminalId = this.generateId();
+
+    // Get default shell for the platform
+    const shell = defaultShell;
+
+    // Spawn PTY process
+    let ptyProcess: pty.IPty;
+    try {
+      ptyProcess = pty.spawn(shell, [], {
+        name: 'xterm-256color',
+        cols: params.cols || 80,
+        rows: params.rows || 24,
+        cwd: this.rootPath,
+        env: process.env,
+      });
+    } catch (error: any) {
+      // Log full error details server-side for debugging
+      console.error('Failed to spawn terminal:', {
+        error: error.message,
+        shell,
+        cwd: this.rootPath,
+        stack: error.stack,
+      });
+
+      // Send sanitized error to client (no system paths or stack traces)
+      throw createRPCError(
+        ErrorCode.INTERNAL_ERROR,
+        'Failed to spawn terminal. Please check that the shell is available and the working directory is accessible.'
+      );
+    }
+
+    // Create headless xterm for buffer management
+    const xterm = new XtermHeadless({
+      cols: params.cols || 80,
+      rows: params.rows || 24,
+      // Enforce hard limit as defense in depth (should already be capped in constructor)
+      scrollback: Math.min(this.maxBufferedLines, MAX_BUFFER_LINES_HARD_LIMIT),
+      allowProposedApi: true
+    });
+
+    const serializeAddon = new SerializeAddon();
+    xterm.loadAddon(serializeAddon);
+
+    // Connect PTY to xterm buffer
+    ptyProcess.onData((data) => {
+      const session = this.sessions.get(terminalId);
+      if (session) {
+        // Track pending write
+        session.pendingWrites++;
+
+        // Write to xterm with callback
+        xterm.write(data, () => {
+          // Decrement pending writes when complete
+          if (session.pendingWrites > 0) {
+            session.pendingWrites--;
+          }
+        });
+      }
+
+      // If this is the active terminal, stream to client
+      if (this.activeTerminalId === terminalId) {
+        this.getSocket().emit('rpc', {
+          jsonrpc: '2.0',
+          method: 'terminal.output',
+          params: { terminalId, data },
+        });
+      }
+    });
+
+    // Handle process exit
+    ptyProcess.onExit(({ exitCode }) => {
+      const session = this.sessions.get(terminalId);
+      if (session) {
+        session.exited = true;
+        session.exitCode = exitCode;
+
+        // Notify client
+        this.getSocket().emit('rpc', {
+          jsonrpc: '2.0',
+          method: 'terminal.exited',
+          params: { terminalId, exitCode },
+        });
+      }
+    });
+
+    // Store session
+    this.sessions.set(terminalId, {
+      id: terminalId,
+      pty: ptyProcess,
+      xterm,
+      serializeAddon,
+      cols: params.cols || 80,
+      rows: params.rows || 24,
+      exited: false,
+      uid,
+      pendingWrites: 0,
+    });
+
+    // Send initial buffer
+    await this.sendBufferRefresh(terminalId);
+
+    return terminalId;
+  }
+
+  /**
+   * Destroy terminal session
+   */
+  private async destroy(params: { terminalId: string }): Promise<void> {
+    const session = this.sessions.get(params.terminalId);
+    if (!session) {
+      throw createRPCError(ErrorCode.TERMINAL_NOT_FOUND, 'Terminal not found');
+    }
+
+    // Verify ownership
+    if (session.uid !== this.getUid()) {
+      throw createRPCError(ErrorCode.PERMISSION_DENIED, 'Permission denied');
+    }
+
+    // Kill PTY process if still running
+    if (!session.exited) {
+      session.pty.kill();
+    }
+
+    // Clean up
+    this.sessions.delete(params.terminalId);
+
+    if (this.activeTerminalId === params.terminalId) {
+      this.activeTerminalId = null;
+    }
+  }
+
+  /**
+   * Activate terminal (start streaming)
+   */
+  private async activate(params: { terminalId: string }): Promise<void> {
+    const session = this.sessions.get(params.terminalId);
+    if (!session) {
+      throw createRPCError(ErrorCode.TERMINAL_NOT_FOUND, 'Terminal not found');
+    }
+
+    // Verify ownership
+    if (session.uid !== this.getUid()) {
+      throw createRPCError(ErrorCode.PERMISSION_DENIED, 'Permission denied');
+    }
+
+    // Update active terminal
+    this.activeTerminalId = params.terminalId;
+
+    // Send full buffer refresh
+    await this.sendBufferRefresh(params.terminalId);
+  }
+
+  /**
+   * Send input to terminal
+   */
+  private async send(params: { terminalId: string; data: string }): Promise<void> {
+    const session = this.sessions.get(params.terminalId);
+    if (!session) {
+      throw createRPCError(ErrorCode.TERMINAL_NOT_FOUND, 'Terminal not found');
+    }
+
+    // Verify ownership
+    if (session.uid !== this.getUid()) {
+      throw createRPCError(ErrorCode.PERMISSION_DENIED, 'Permission denied');
+    }
+
+    if (session.exited) {
+      throw createRPCError(
+        ErrorCode.TERMINAL_PROCESS_EXITED,
+        'Terminal process has exited'
+      );
+    }
+
+    // Write to PTY
+    session.pty.write(params.data);
+  }
+
+  /**
+   * Resize terminal
+   */
+  private async resize(params: { terminalId: string; cols: number; rows: number }): Promise<void> {
+    const session = this.sessions.get(params.terminalId);
+    if (!session) {
+      throw createRPCError(ErrorCode.TERMINAL_NOT_FOUND, 'Terminal not found');
+    }
+
+    // Verify ownership
+    if (session.uid !== this.getUid()) {
+      throw createRPCError(ErrorCode.PERMISSION_DENIED, 'Permission denied');
+    }
+
+    // Resize PTY
+    session.pty.resize(params.cols, params.rows);
+
+    // Resize xterm buffer
+    session.xterm.resize(params.cols, params.rows);
+
+    // Update session
+    session.cols = params.cols;
+    session.rows = params.rows;
+  }
+
+  /**
+   * Refresh terminal buffer
+   */
+  private async refresh(params: { terminalId: string }): Promise<void> {
+    const session = this.sessions.get(params.terminalId);
+    if (!session) {
+      throw createRPCError(ErrorCode.TERMINAL_NOT_FOUND, 'Terminal not found');
+    }
+
+    // Verify ownership
+    if (session.uid !== this.getUid()) {
+      throw createRPCError(ErrorCode.PERMISSION_DENIED, 'Permission denied');
+    }
+
+    await this.sendBufferRefresh(params.terminalId);
+  }
+
+  /**
+   * List terminals for current user
+   */
+  private async list(): Promise<string[]> {
+    const uid = this.getUid();
+    return Array.from(this.sessions.values())
+      .filter((s) => s.uid === uid)
+      .map((s) => s.id);
+  }
+
+  /**
+   * Send buffer refresh notification
+   */
+  private async sendBufferRefresh(terminalId: string): Promise<void> {
+    const session = this.sessions.get(terminalId);
+    if (!session) return;
+
+    // Wait for pending writes to complete
+    const waitForWrites = async () => {
+      const maxWaitTime = 5000; // 5 seconds max
+      const checkInterval = 10; // Check every 10ms
+      let elapsed = 0;
+
+      while (session.pendingWrites > 0 && elapsed < maxWaitTime) {
+        await new Promise(resolve => setTimeout(resolve, checkInterval));
+        elapsed += checkInterval;
+      }
+
+      if (elapsed >= maxWaitTime) {
+        console.warn(`Timeout waiting for pending writes (${session.pendingWrites} remaining)`);
+      }
+    };
+
+    await waitForWrites();
+
+    // Serialize xterm buffer
+    const buffer = session.serializeAddon.serialize();
+    // Send to client
+    this.getSocket().emit('rpc', {
+      jsonrpc: '2.0',
+      method: 'terminal.bufferRefresh',
+      params: { terminalId, buffer },
+    });
+  }
+
+  /**
+   * Generate unique terminal ID
+   */
+  private generateId(): string {
+    return `term-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Cleanup all terminals
+   */
+  cleanup(): void {
+    for (const session of this.sessions.values()) {
+      if (!session.exited) {
+        session.pty.kill();
+      }
+    }
+    this.sessions.clear();
+  }
+}

package/src/services/__tests__/BrowserProxyService.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+/**
+ * Tests for BrowserProxyService edge cases
+ */
+
+import http from 'http';
+import { BrowserProxyService } from '../BrowserProxyService.js';
+import { ErrorCode } from '../../types.js';
+
+function makeService() {
+  return new BrowserProxyService();
+}
+
+function startServer(handler: http.RequestListener): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(handler);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number };
+      resolve({ port, close: () => new Promise<void>((res) => server.close(() => res())) });
+    });
+    server.on('error', reject);
+  });
+}
+
+function makeParams(overrides: Record<string, any> = {}) {
+  return { requestId: 'req-1', url: 'http://localhost:3000/', method: 'GET', headers: {}, body: null, ...overrides };
+}
+
+function makeSocket(deviceId = 'test-device-1') {
+  return { data: { deviceId, uid: 'test-user' } } as any;
+}
+
+describe('BrowserProxyService', () => {
+  let service: BrowserProxyService;
+  beforeEach(() => { service = makeService(); });
+
+  it('rejects unknown RPC methods', async () => {
+    await expect(service.handle('unknown', makeParams(), makeSocket())).rejects.toMatchObject({ code: ErrorCode.METHOD_NOT_FOUND });
+  });
+
+  it.each([
+    ['non-localhost hostname', 'http://example.com/'],
+    ['internal IP',           'http://192.168.1.1:3000/'],
+    ['0.0.0.0',               'http://0.0.0.0:3000/'],
+  ])('rejects %s', async (_label, url) => {
+    await expect(service.handle('request', makeParams({ url }), makeSocket())).rejects.toMatchObject({ code: ErrorCode.PERMISSION_DENIED });
+  });
+
+  it.each([
+    ['malformed URL', 'not-a-url',              ErrorCode.INVALID_PARAMS],
+    ['port 0',        'http://localhost:0/',     ErrorCode.INVALID_PARAMS],
+    ['port > 65535',  'http://localhost:99999/', ErrorCode.INVALID_PARAMS],
+    ['TRACE method',  'http://localhost:3000/',  ErrorCode.INVALID_PARAMS],
+  ])('rejects %s', async (_label, urlOrMethod, code) => {
+    const isMethod = _label.includes('method');
+    await expect(
+      service.handle('request', makeParams(isMethod ? { method: 'TRACE' } : { url: urlOrMethod }), makeSocket())
+    ).rejects.toMatchObject({ code });
+  });
+
+  it('forwards POST body bytes and returns base64-encoded response', async () => {
+    let receivedBody = '';
+    const srv = await startServer((req, res) => {
+      req.on('data', (c) => { receivedBody += c.toString(); });
+      req.on('end', () => { res.writeHead(200); res.end('pong'); });
+    });
+    try {
+      const result = await service.handle('request', makeParams({
+        url: `http://localhost:${srv.port}/`,
+        method: 'POST',
+        body: Array.from(Buffer.from('ping')),
+      }), makeSocket());
+      expect(receivedBody).toBe('ping');
+      expect(result.bodyEncoding).toBe('base64');
+      expect(Buffer.from(result.body, 'base64').toString()).toBe('pong');
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it('correctly encodes binary response body', async () => {
+    const binary = Buffer.from([0x00, 0x01, 0xff, 0xfe]);
+    const srv = await startServer((_req, res) => { res.writeHead(200); res.end(binary); });
+    try {
+      const result = await service.handle('request', makeParams({ url: `http://localhost:${srv.port}/` }), makeSocket());
+      expect(Buffer.from(result.body, 'base64')).toEqual(binary);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it('strips hop-by-hop headers and forwards custom headers', async () => {
+    let received: http.IncomingHttpHeaders = {};
+    const srv = await startServer((req, res) => { received = req.headers; res.writeHead(200); res.end(); });
+    try {
+      await service.handle('request', makeParams({
+        url: `http://localhost:${srv.port}/`,
+        headers: { 'transfer-encoding': 'chunked', 'upgrade': 'websocket', 'x-custom': 'yes' },
+      }), makeSocket());
+      expect(received['transfer-encoding']).toBeUndefined();
+      expect(received['upgrade']).toBeUndefined();
+      expect(received['x-custom']).toBe('yes');
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it('rejects with INTERNAL_ERROR on ECONNREFUSED', async () => {
+    await expect(
+      service.handle('request', makeParams({ url: 'http://localhost:19999/' }), makeSocket())
+    ).rejects.toMatchObject({ code: ErrorCode.INTERNAL_ERROR });
+  });
+
+  it('rejects with OPERATION_TIMEOUT when server hangs', async () => {
+    const srv = await startServer(() => { /* hang */ });
+    try {
+      vi.spyOn(service as any, 'fetch').mockImplementation((...args: unknown[]) => {
+        const url = args[0] as URL;
+        return new Promise((_res, reject) => {
+          const req = http.request({ hostname: url.hostname, port: url.port, path: '/', timeout: 50 });
+          req.on('timeout', () => { req.destroy(); reject({ code: ErrorCode.OPERATION_TIMEOUT, message: 'timed out' }); });
+          req.on('error', reject);
+          req.end();
+        });
+      });
+      await expect(service.handle('request', makeParams({ url: `http://localhost:${srv.port}/` }), makeSocket()))
+        .rejects.toMatchObject({ code: ErrorCode.OPERATION_TIMEOUT });
+    } finally {
+      vi.restoreAllMocks();
+      await srv.close();
+    }
+  });
+
+  it('rejects responses exceeding 10 MB', async () => {
+    const srv = await startServer((_req, res) => {
+      res.writeHead(200);
+      const chunk = Buffer.alloc(1024 * 1024);
+      let sent = 0;
+      const write = () => {
+        while (sent < 11) {
+          if (!res.write(chunk)) { res.once('drain', write); return; }
+          sent++;
+        }
+        res.end();
+      };
+      write();
+    });
+    try {
+      await expect(service.handle('request', makeParams({ url: `http://localhost:${srv.port}/` }), makeSocket()))
+        .rejects.toMatchObject({ code: ErrorCode.INTERNAL_ERROR });
+    } finally {
+      await srv.close();
+    }
+  });
+});