spck 0.3.1

package/dist/proxy/chunking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Message Chunking Utility
+ *
+ * Handles chunking of large payloads to avoid Socket.IO buffer limits
+ * Chunks messages over 800kB into smaller pieces with reassembly metadata
+ */
+export interface ChunkMetadata {
+    type: 'chunk';
+    chunkId: string;
+    index: number;
+    total: number;
+    originalEvent: string;
+    data: any;
+}
+export interface ChunkedMessage {
+    needsChunking: boolean;
+    chunks?: ChunkMetadata[];
+    originalMessage?: any;
+}
+/**
+ * Check if a message needs chunking
+ */
+export declare function needsChunking(data: any): boolean;
+/**
+ * Chunk a large message into smaller pieces
+ */
+export declare function chunkMessage(event: string, data: any): ChunkMetadata[];
+/**
+ * Chunk reassembler (for client side)
+ */
+export declare class ChunkReassembler {
+    private chunks;
+    private totalChunks;
+    private originalEvents;
+    /**
+     * Add a chunk and check if message is complete
+     * @returns Reassembled data if complete, null otherwise
+     */
+    addChunk(chunk: ChunkMetadata): {
+        complete: boolean;
+        event?: string;
+        data?: any;
+    };
+    /**
+     * Reassemble chunks into original message
+     */
+    private reassemble;
+    /**
+     * Clean up stale chunks (older than 30 seconds)
+     */
+    cleanup(_maxAge?: number): void;
+}
+//# sourceMappingURL=chunking.d.ts.map

package/dist/proxy/chunking.js

@@ -0,0 +1,127 @@
+/**
+ * Message Chunking Utility
+ *
+ * Handles chunking of large payloads to avoid Socket.IO buffer limits
+ * Chunks messages over 800kB into smaller pieces with reassembly metadata
+ */
+const CHUNK_SIZE = 800 * 1024; // 800kB
+const CHUNK_THRESHOLD = 800 * 1024; // Start chunking at 800kB
+/**
+ * Check if a message needs chunking
+ */
+export function needsChunking(data) {
+    const size = estimateSize(data);
+    return size > CHUNK_THRESHOLD;
+}
+/**
+ * Chunk a large message into smaller pieces
+ */
+export function chunkMessage(event, data) {
+    // Serialize the data
+    const serialized = JSON.stringify(data);
+    const totalBytes = Buffer.byteLength(serialized, 'utf8');
+    // Calculate number of chunks needed
+    const numChunks = Math.ceil(totalBytes / CHUNK_SIZE);
+    // Generate unique chunk ID
+    const chunkId = generateChunkId();
+    // Split into chunks
+    const chunks = [];
+    let offset = 0;
+    for (let i = 0; i < numChunks; i++) {
+        const chunkData = serialized.slice(offset, offset + CHUNK_SIZE);
+        offset += CHUNK_SIZE;
+        chunks.push({
+            type: 'chunk',
+            chunkId,
+            index: i,
+            total: numChunks,
+            originalEvent: event,
+            data: chunkData,
+        });
+    }
+    return chunks;
+}
+/**
+ * Estimate size of an object in bytes
+ */
+function estimateSize(obj) {
+    const serialized = JSON.stringify(obj);
+    return Buffer.byteLength(serialized, 'utf8');
+}
+/**
+ * Generate unique chunk ID
+ */
+function generateChunkId() {
+    return `chunk_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Chunk reassembler (for client side)
+ */
+export class ChunkReassembler {
+    constructor() {
+        this.chunks = new Map();
+        this.totalChunks = new Map();
+        this.originalEvents = new Map();
+    }
+    /**
+     * Add a chunk and check if message is complete
+     * @returns Reassembled data if complete, null otherwise
+     */
+    addChunk(chunk) {
+        const { chunkId, index, total, originalEvent, data } = chunk;
+        // Initialize chunk storage for this chunkId
+        if (!this.chunks.has(chunkId)) {
+            this.chunks.set(chunkId, new Map());
+            this.totalChunks.set(chunkId, total);
+            this.originalEvents.set(chunkId, originalEvent);
+        }
+        // Store this chunk
+        const chunkMap = this.chunks.get(chunkId);
+        chunkMap.set(index, data);
+        // Check if we have all chunks
+        const expectedTotal = this.totalChunks.get(chunkId);
+        if (chunkMap.size === expectedTotal) {
+            // Reassemble message
+            const reassembled = this.reassemble(chunkId);
+            // Clean up
+            this.chunks.delete(chunkId);
+            this.totalChunks.delete(chunkId);
+            this.originalEvents.delete(chunkId);
+            return {
+                complete: true,
+                event: originalEvent,
+                data: reassembled,
+            };
+        }
+        return { complete: false };
+    }
+    /**
+     * Reassemble chunks into original message
+     */
+    reassemble(chunkId) {
+        const chunkMap = this.chunks.get(chunkId);
+        const total = this.totalChunks.get(chunkId);
+        // Concatenate chunks in order
+        let reassembled = '';
+        for (let i = 0; i < total; i++) {
+            const chunk = chunkMap.get(i);
+            if (!chunk) {
+                throw new Error(`Missing chunk ${i} for chunkId ${chunkId}`);
+            }
+            reassembled += chunk;
+        }
+        // Parse back to object
+        return JSON.parse(reassembled);
+    }
+    /**
+     * Clean up stale chunks (older than 30 seconds)
+     */
+    cleanup(_maxAge = 30000) {
+        // Note: This is a simple implementation that clears all chunks
+        // A more sophisticated version could track timestamps
+        this.chunks.clear();
+        this.totalChunks.clear();
+        this.originalEvents.clear();
+    }
+}
+//# sourceMappingURL=chunking.js.map

package/dist/proxy/handshake-validation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Handshake validation utilities
+ * Provides timestamp validation for replay attack prevention
+ */
+/**
+ * Validate timestamp from client handshake message
+ * Prevents replay attacks by ensuring messages are recent
+ *
+ * @param timestamp - Unix timestamp in milliseconds from client message
+ * @param options - Validation options
+ * @returns Validation result with error message if invalid
+ */
+export declare function validateHandshakeTimestamp(timestamp: number, options?: {
+    maxAge?: number;
+    clockSkewTolerance?: number;
+    now?: number;
+}): {
+    valid: boolean;
+    error?: string;
+};
+//# sourceMappingURL=handshake-validation.d.ts.map

package/dist/proxy/handshake-validation.js

@@ -0,0 +1,49 @@
+/**
+ * Handshake validation utilities
+ * Provides timestamp validation for replay attack prevention
+ */
+/**
+ * Validate timestamp from client handshake message
+ * Prevents replay attacks by ensuring messages are recent
+ *
+ * @param timestamp - Unix timestamp in milliseconds from client message
+ * @param options - Validation options
+ * @returns Validation result with error message if invalid
+ */
+export function validateHandshakeTimestamp(timestamp, options = {}) {
+    const { maxAge = 60 * 1000, // 1 minute default
+    clockSkewTolerance = 60 * 1000, // 1 minute default
+    now = Date.now(), } = options;
+    // Validate timestamp is a number
+    if (typeof timestamp !== 'number' || !isFinite(timestamp)) {
+        return {
+            valid: false,
+            error: 'Invalid timestamp format',
+        };
+    }
+    // Validate timestamp is positive
+    if (timestamp <= 0) {
+        return {
+            valid: false,
+            error: 'Timestamp must be positive',
+        };
+    }
+    // Calculate age
+    const age = now - timestamp;
+    // Check if message is too old
+    if (age > maxAge) {
+        return {
+            valid: false,
+            error: `Message too old (age: ${Math.floor(age / 1000)}s, max: ${Math.floor(maxAge / 1000)}s)`,
+        };
+    }
+    // Check if timestamp is too far in the future (clock skew)
+    if (age < -clockSkewTolerance) {
+        return {
+            valid: false,
+            error: `Timestamp too far in future (skew: ${Math.floor(-age / 1000)}s, max: ${Math.floor(clockSkewTolerance / 1000)}s)`,
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=handshake-validation.js.map

package/dist/rpc/__tests__/router.test.d.ts

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

package/dist/rpc/__tests__/router.test.js

@@ -0,0 +1,262 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+/**
+ * Tests for JSON-RPC Router
+ */
+// Mock xterm headless modules BEFORE importing TerminalService
+vi.mock('@xterm/headless', () => ({
+    default: { Terminal: vi.fn() },
+    Terminal: vi.fn(),
+}));
+vi.mock('@xterm/addon-serialize', () => ({
+    default: { SerializeAddon: vi.fn() },
+    SerializeAddon: vi.fn(),
+}));
+import * as crypto from 'crypto';
+import { RPCRouter } from '../router.js';
+import { ErrorCode, createRPCError } from '../../types.js';
+import { FilesystemService } from '../../services/FilesystemService.js';
+import { GitService } from '../../services/GitService.js';
+import { TerminalService } from '../../services/TerminalService.js';
+/**
+ * Helper function to create a valid JSONRPCRequest with HMAC and nonce
+ */
+function createRequest(method, params, id) {
+    const timestamp = Date.now();
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const signingKey = 'test-key';
+    const payload = {
+        jsonrpc: '2.0',
+        method,
+        params,
+        id,
+        nonce,
+    };
+    const messageToSign = timestamp + JSON.stringify(payload);
+    const hmac = crypto
+        .createHmac('sha256', signingKey)
+        .update(messageToSign)
+        .digest('hex');
+    return {
+        ...payload,
+        timestamp,
+        hmac,
+        nonce,
+    };
+}
+// Mock services
+vi.mock('../../services/FilesystemService', () => {
+    const MockFS = vi.fn();
+    MockFS.prototype.handle = vi.fn();
+    return { FilesystemService: MockFS };
+});
+vi.mock('../../services/GitService', () => {
+    const MockGit = vi.fn();
+    MockGit.prototype.handle = vi.fn();
+    return { GitService: MockGit };
+});
+vi.mock('../../services/TerminalService', () => {
+    const MockTerm = vi.fn();
+    MockTerm.prototype.handle = vi.fn();
+    MockTerm.prototype.cleanup = vi.fn();
+    return { TerminalService: MockTerm };
+});
+const MockFilesystemService = FilesystemService;
+const MockGitService = GitService;
+const MockTerminalService = TerminalService;
+describe('RPCRouter', () => {
+    let mockSocket;
+    let mockFsHandle;
+    let mockGitHandle;
+    let mockTerminalHandle;
+    beforeEach(() => {
+        mockSocket = {
+            id: 'test-socket-id',
+            data: {
+                uid: 'test-user-123',
+            },
+            emit: vi.fn(),
+            on: vi.fn(),
+            off: vi.fn(),
+            broadcast: {
+                emit: vi.fn(),
+            },
+        };
+        // Clear all mocks
+        vi.clearAllMocks();
+        // Clear router state between tests
+        RPCRouter.terminalServices = new Map();
+        RPCRouter.currentSockets = new Map();
+        // Set up default mock implementations
+        mockFsHandle = vi.fn().mockResolvedValue({ success: true });
+        mockGitHandle = vi.fn().mockResolvedValue({ success: true });
+        mockTerminalHandle = vi.fn().mockResolvedValue('term-123');
+        // Mock the service prototypes
+        MockFilesystemService.prototype.handle = mockFsHandle;
+        MockGitService.prototype.handle = mockGitHandle;
+        // Create mock instance for terminal service that will be returned by constructor
+        // Use a single tracked cleanup function across all instances
+        const mockCleanupFn = vi.fn();
+        MockTerminalService.mockImplementation(() => ({
+            handle: mockTerminalHandle,
+            cleanup: mockCleanupFn,
+        }));
+        // Initialize router
+        RPCRouter.initialize('/test/root', {
+            filesystem: { maxFileSize: '100MB', watchIgnorePatterns: [] },
+        }, {
+            git: true,
+            ripgrep: true,
+        });
+    });
+    describe('Route Method Parsing', () => {
+        it('should parse method correctly for fs service', async () => {
+            await RPCRouter.route(createRequest('fs.readFile', { path: '/test.txt' }, 1), mockSocket);
+            expect(mockFsHandle).toHaveBeenCalledWith('readFile', { path: '/test.txt' }, mockSocket);
+        });
+        it('should parse method correctly for git service', async () => {
+            await RPCRouter.route(createRequest('git.log', { dir: '/project' }, 2), mockSocket);
+            expect(mockGitHandle).toHaveBeenCalledWith('log', { dir: '/project' }, mockSocket);
+        });
+        it('should parse method correctly for terminal service', async () => {
+            await RPCRouter.route(createRequest('terminal.create', { cols: 80, rows: 24 }, 3), mockSocket);
+            expect(mockTerminalHandle).toHaveBeenCalledWith('create', { cols: 80, rows: 24 });
+        });
+        it('should throw error for invalid method format', async () => {
+            await expect(RPCRouter.route(createRequest('invalidmethod', {}, 4), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.INVALID_REQUEST,
+                message: expect.stringContaining('Invalid method format'),
+            });
+        });
+        it('should throw error for unknown service', async () => {
+            await expect(RPCRouter.route(createRequest('unknown.method', {}, 5), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.METHOD_NOT_FOUND,
+                message: expect.stringContaining('Unknown service'),
+            });
+        });
+    });
+    describe('Service Routing', () => {
+        it('should route to FilesystemService', async () => {
+            const mockResult = { content: 'file contents' };
+            mockFsHandle.mockResolvedValueOnce(mockResult);
+            const result = await RPCRouter.route(createRequest('fs.readFile', { path: '/test.txt', encoding: 'utf8' }, 10), mockSocket);
+            expect(result).toEqual(mockResult);
+            expect(mockFsHandle).toHaveBeenCalledTimes(1);
+        });
+        it('should route to GitService', async () => {
+            const mockResult = { oid: 'abc123', commit: {} };
+            mockGitHandle.mockResolvedValueOnce(mockResult);
+            const result = await RPCRouter.route(createRequest('git.readCommit', { dir: '/project', oid: 'abc123' }, 11), mockSocket);
+            expect(result).toEqual(mockResult);
+            expect(mockGitHandle).toHaveBeenCalledTimes(1);
+        });
+        it('should route to TerminalService', async () => {
+            const result = await RPCRouter.route(createRequest('terminal.create', { cols: 120, rows: 30 }, 12), mockSocket);
+            // Should return the default mock result
+            expect(result).toEqual('term-123');
+            expect(mockTerminalHandle).toHaveBeenCalledTimes(1);
+        });
+        it('should create separate terminal services per device', async () => {
+            const socket1 = { ...mockSocket, id: 'socket-1', data: { uid: 'user-1', deviceId: 'device-1' } };
+            const socket2 = { ...mockSocket, id: 'socket-2', data: { uid: 'user-2', deviceId: 'device-2' } };
+            const result1 = await RPCRouter.route(createRequest('terminal.create', {}, 1), socket1);
+            const result2 = await RPCRouter.route(createRequest('terminal.create', {}, 2), socket2);
+            // Both should succeed (indicating separate services were created)
+            expect(result1).toBeTruthy();
+            expect(result2).toBeTruthy();
+            expect(mockTerminalHandle).toHaveBeenCalledTimes(2);
+        });
+        it('should reuse terminal service for same device', async () => {
+            const socket1 = { ...mockSocket, id: 'socket-1', data: { uid: 'user-same', deviceId: 'device-same' } };
+            const socket2 = { ...mockSocket, id: 'socket-2', data: { uid: 'user-same', deviceId: 'device-same' } };
+            const result1 = await RPCRouter.route(createRequest('terminal.create', {}, 1), socket1);
+            const result2 = await RPCRouter.route(createRequest('terminal.create', {}, 2), socket2);
+            // Both should succeed using the same service instance
+            expect(result1).toBeTruthy();
+            expect(result2).toBeTruthy();
+            expect(mockTerminalHandle).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('Error Handling', () => {
+        it('should re-throw RPC errors from services', async () => {
+            const rpcError = createRPCError(ErrorCode.FILE_NOT_FOUND, 'File not found');
+            mockFsHandle.mockRejectedValueOnce(rpcError);
+            await expect(RPCRouter.route(createRequest('fs.readFile', { path: '/missing.txt' }, 20), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.FILE_NOT_FOUND,
+                message: 'File not found',
+            });
+        });
+        it('should wrap non-RPC errors in internal error', async () => {
+            const genericError = new Error('Something went wrong');
+            mockFsHandle.mockRejectedValueOnce(genericError);
+            await expect(RPCRouter.route(createRequest('fs.readFile', { path: '/test.txt' }, 21), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.INTERNAL_ERROR,
+                message: expect.stringContaining('Internal error'),
+            });
+        });
+        it('should include method name in wrapped errors', async () => {
+            const genericError = new Error('Unexpected error');
+            mockGitHandle.mockRejectedValueOnce(genericError);
+            await expect(RPCRouter.route(createRequest('git.commit', { dir: '/project', message: 'test' }, 22), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.INTERNAL_ERROR,
+                data: {
+                    method: 'git.commit',
+                    originalError: expect.any(String),
+                },
+            });
+        });
+    });
+    describe('Terminal Service Cleanup', () => {
+        it('should cleanup terminal service on disconnect', async () => {
+            // Setup a mock cleanup function that will be tracked
+            const mockCleanup = vi.fn();
+            // Create a new mock instance with cleanup
+            const mockServiceWithCleanup = {
+                handle: mockTerminalHandle,
+                cleanup: mockCleanup,
+            };
+            // Override the mock to return our instance
+            MockTerminalService.mockImplementationOnce(() => mockServiceWithCleanup);
+            // Create a terminal service - this will instantiate the mock
+            await RPCRouter.route(createRequest('terminal.create', {}, 1), mockSocket);
+            // Now cleanup - this should call the cleanup method
+            RPCRouter.cleanupTerminalService(mockSocket);
+            expect(mockCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should handle cleanup when no terminal service exists', () => {
+            const otherSocket = { ...mockSocket, data: { uid: 'different-user', deviceId: 'different-device' } };
+            expect(() => {
+                RPCRouter.cleanupTerminalService(otherSocket);
+            }).not.toThrow();
+        });
+    });
+    describe('Edge Cases', () => {
+        it('should handle method with multiple dots', async () => {
+            // Method "fs.some.deep.method" splits into service="fs", methodName="some.deep.method"
+            // Only the first dot is used to separate service from method; sub-namespaces are preserved
+            const result = await RPCRouter.route(createRequest('fs.some.deep.method', {}, 30), mockSocket);
+            // Should route to fs service with the full sub-method "some.deep.method"
+            expect(mockFsHandle).toHaveBeenCalledWith('some.deep.method', {}, mockSocket);
+            expect(result).toEqual({ success: true });
+        });
+        it('should handle empty method name', async () => {
+            await expect(RPCRouter.route(createRequest('', {}, 31), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.INVALID_REQUEST,
+            });
+        });
+        it('should handle method with only service name', async () => {
+            await expect(RPCRouter.route(createRequest('fs.', {}, 32), mockSocket)).rejects.toMatchObject({
+                code: ErrorCode.INVALID_REQUEST,
+            });
+        });
+        it('should handle undefined params', async () => {
+            const result = await RPCRouter.route(createRequest('fs.stat', undefined, 33), mockSocket);
+            expect(mockFsHandle).toHaveBeenCalledWith('stat', undefined, mockSocket);
+            expect(result).toEqual({ success: true });
+        });
+        it('should handle requests with no id', async () => {
+            const result = await RPCRouter.route(createRequest('fs.stat', { path: '/test.txt' }), mockSocket);
+            expect(result).toEqual({ success: true });
+        });
+    });
+});
+//# sourceMappingURL=router.test.js.map

package/dist/rpc/router.d.ts

@@ -0,0 +1,37 @@
+/**
+ * JSON-RPC 2.0 request router
+ */
+import { AuthenticatedSocket, JSONRPCRequest, ToolDetectionResult } from '../types.js';
+export declare class RPCRouter {
+    private static filesystemService;
+    private static gitService;
+    private static searchService;
+    private static terminalServices;
+    private static currentSockets;
+    private static browserProxyService;
+    private static rootPath;
+    private static tools;
+    private static terminalEnabled;
+    private static browserProxyEnabled;
+    /**
+     * Initialize services
+     */
+    static initialize(rootPath: string, config: any, tools: ToolDetectionResult): void;
+    /**
+     * Parse file size string to bytes
+     */
+    private static parseFileSize;
+    /**
+     * Get or create terminal service for socket
+     */
+    private static getTerminalService;
+    /**
+     * Route JSON-RPC request to appropriate service
+     */
+    static route(message: JSONRPCRequest, socket: AuthenticatedSocket): Promise<any>;
+    /**
+     * Cleanup terminal service for socket
+     */
+    static cleanupTerminalService(socket: AuthenticatedSocket): void;
+}
+//# sourceMappingURL=router.d.ts.map