spck 0.3.1

package/dist/services/TerminalService.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Terminal service - manages PTY sessions with xterm-headless
+ */
+import { AuthenticatedSocket } from '../types.js';
+export declare class TerminalService {
+    private getSocket;
+    private maxTerminals;
+    private maxBufferedLines;
+    private rootPath;
+    private sessions;
+    private activeTerminalId;
+    constructor(getSocket: () => AuthenticatedSocket, maxTerminals?: number, maxBufferedLines?: number, rootPath?: string);
+    /**
+     * Get UID from socket with fallback
+     */
+    private getUid;
+    /**
+     * Handle terminal RPC methods
+     */
+    handle(method: string, params: any): Promise<any>;
+    /**
+     * Create new terminal session
+     */
+    private create;
+    /**
+     * Destroy terminal session
+     */
+    private destroy;
+    /**
+     * Activate terminal (start streaming)
+     */
+    private activate;
+    /**
+     * Send input to terminal
+     */
+    private send;
+    /**
+     * Resize terminal
+     */
+    private resize;
+    /**
+     * Refresh terminal buffer
+     */
+    private refresh;
+    /**
+     * List terminals for current user
+     */
+    private list;
+    /**
+     * Send buffer refresh notification
+     */
+    private sendBufferRefresh;
+    /**
+     * Generate unique terminal ID
+     */
+    private generateId;
+    /**
+     * Cleanup all terminals
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=TerminalService.d.ts.map

package/dist/services/TerminalService.js

@@ -0,0 +1,337 @@
+/**
+ * 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 { ErrorCode, createRPCError } from '../types.js';
+import { logTerminalRead, logTerminalWrite } from '../utils/logger.js';
+const { Terminal: XtermHeadless } = XtermHeadlessModule;
+const { SerializeAddon } = SerializeAddonModule;
+// Hard limit on terminal buffer size to prevent memory exhaustion (DoS)
+const MAX_BUFFER_LINES_HARD_LIMIT = 50000;
+export class TerminalService {
+    constructor(getSocket, maxTerminals = 10, maxBufferedLines = 10000, rootPath = process.cwd()) {
+        this.getSocket = getSocket;
+        this.maxTerminals = maxTerminals;
+        this.maxBufferedLines = maxBufferedLines;
+        this.rootPath = rootPath;
+        this.sessions = new Map();
+        this.activeTerminalId = null;
+        // 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
+     */
+    getUid() {
+        return this.getSocket().data?.uid || 'unknown';
+    }
+    /**
+     * Handle terminal RPC methods
+     */
+    async handle(method, params) {
+        const uid = this.getUid();
+        let result;
+        let error;
+        // 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) {
+            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
+     */
+    async create(params) {
+        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;
+        try {
+            ptyProcess = pty.spawn(shell, [], {
+                name: 'xterm-256color',
+                cols: params.cols || 80,
+                rows: params.rows || 24,
+                cwd: this.rootPath,
+                env: process.env,
+            });
+        }
+        catch (error) {
+            // 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
+     */
+    async destroy(params) {
+        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)
+     */
+    async activate(params) {
+        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
+     */
+    async send(params) {
+        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
+     */
+    async resize(params) {
+        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
+     */
+    async refresh(params) {
+        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
+     */
+    async list() {
+        const uid = this.getUid();
+        return Array.from(this.sessions.values())
+            .filter((s) => s.uid === uid)
+            .map((s) => s.id);
+    }
+    /**
+     * Send buffer refresh notification
+     */
+    async sendBufferRefresh(terminalId) {
+        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
+     */
+    generateId() {
+        return `term-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Cleanup all terminals
+     */
+    cleanup() {
+        for (const session of this.sessions.values()) {
+            if (!session.exited) {
+                session.pty.kill();
+            }
+        }
+        this.sessions.clear();
+    }
+}
+//# sourceMappingURL=TerminalService.js.map

package/dist/services/__tests__/BrowserProxyService.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BrowserProxyService.test.d.ts.map

package/dist/services/__tests__/BrowserProxyService.test.js

@@ -0,0 +1,145 @@
+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) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(handler);
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            resolve({ port, close: () => new Promise((res) => server.close(() => res())) });
+        });
+        server.on('error', reject);
+    });
+}
+function makeParams(overrides = {}) {
+    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' } };
+}
+describe('BrowserProxyService', () => {
+    let service;
+    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 = {};
+        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(() => { });
+        try {
+            vi.spyOn(service, 'fetch').mockImplementation((...args) => {
+                const url = args[0];
+                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();
+        }
+    });
+});
+//# sourceMappingURL=BrowserProxyService.test.js.map

package/dist/services/__tests__/FilesystemService.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=FilesystemService.test.d.ts.map