spck 0.3.1

package/dist/proxy/ProxySocketWrapper.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ProxySocketWrapper - Emulates AuthenticatedSocket for proxy mode
+ * Routes socket.emit() calls through ProxyClient.sendToClient()
+ */
+/**
+ * Lightweight socket wrapper for proxy mode
+ * Provides the minimal interface needed by services (duck typing)
+ */
+export declare class ProxySocketWrapper {
+    private connectionId;
+    private sendFn;
+    data: {
+        uid: string;
+        deviceId: string;
+    };
+    broadcast: {
+        emit: (event: string, data?: any) => boolean;
+    };
+    private eventListeners;
+    constructor(connectionId: string, userId: string, sendFn: (connectionId: string, event: string, data: any) => void, deviceId: string);
+    /**
+     * Emit event to client via proxy
+     * This is the main method used by services to send data back to clients
+     */
+    emit(event: string, data?: any): boolean;
+    /**
+     * Get connection ID
+     */
+    get id(): string;
+    /**
+     * Event handling methods
+     * These store listeners that are triggered when messages arrive from the client
+     */
+    on(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener?: (...args: any[]) => void): this;
+    removeAllListeners(event?: string): this;
+    /**
+     * Trigger event listeners (called by ProxyClient when messages arrive)
+     */
+    triggerEvent(event: string, ...args: any[]): void;
+}
+//# sourceMappingURL=ProxySocketWrapper.d.ts.map

package/dist/proxy/ProxySocketWrapper.js

@@ -0,0 +1,98 @@
+/**
+ * ProxySocketWrapper - Emulates AuthenticatedSocket for proxy mode
+ * Routes socket.emit() calls through ProxyClient.sendToClient()
+ */
+/**
+ * Lightweight socket wrapper for proxy mode
+ * Provides the minimal interface needed by services (duck typing)
+ */
+export class ProxySocketWrapper {
+    constructor(connectionId, userId, sendFn, deviceId) {
+        this.connectionId = connectionId;
+        this.sendFn = sendFn;
+        this.eventListeners = new Map();
+        // Set up data property to match AuthenticatedSocket
+        // uid = CLI user ID (from Firebase), deviceId = mobile device ID
+        this.data = { uid: userId, deviceId };
+        // Set up broadcast - in proxy mode, just send to the single connected client
+        this.broadcast = {
+            emit: (event, data) => {
+                return this.emit(event, data);
+            }
+        };
+    }
+    /**
+     * Emit event to client via proxy
+     * This is the main method used by services to send data back to clients
+     */
+    emit(event, data) {
+        // Send through proxy client
+        this.sendFn(this.connectionId, event, data || {});
+        return true; // Return true to match socket.io API
+    }
+    /**
+     * Get connection ID
+     */
+    get id() {
+        return this.connectionId;
+    }
+    /**
+     * Event handling methods
+     * These store listeners that are triggered when messages arrive from the client
+     */
+    on(event, listener) {
+        if (!this.eventListeners.has(event)) {
+            this.eventListeners.set(event, new Set());
+        }
+        this.eventListeners.get(event).add(listener);
+        return this;
+    }
+    once(event, listener) {
+        const onceWrapper = (...args) => {
+            this.off(event, onceWrapper);
+            listener(...args);
+        };
+        return this.on(event, onceWrapper);
+    }
+    off(event, listener) {
+        if (!listener) {
+            // Remove all listeners for this event
+            this.eventListeners.delete(event);
+            return this;
+        }
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                this.eventListeners.delete(event);
+            }
+        }
+        return this;
+    }
+    removeAllListeners(event) {
+        if (event) {
+            this.eventListeners.delete(event);
+        }
+        else {
+            this.eventListeners.clear();
+        }
+        return this;
+    }
+    /**
+     * Trigger event listeners (called by ProxyClient when messages arrive)
+     */
+    triggerEvent(event, ...args) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.forEach(listener => {
+                try {
+                    listener(...args);
+                }
+                catch (error) {
+                    console.error(`Error in event listener for '${event}':`, error);
+                }
+            });
+        }
+    }
+}
+//# sourceMappingURL=ProxySocketWrapper.js.map

package/dist/proxy/__tests__/ProxyClient.test.d.ts

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

package/dist/proxy/__tests__/ProxyClient.test.js

@@ -0,0 +1,445 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+/**
+ * Tests for ProxyClient security - Handshake protocol and HMAC verification
+ *
+ * These tests verify the security fixes for:
+ * 1. Handshake bypass prevention (protocol_selected requires authentication)
+ * 2. User authentication enforcement when userAuthenticationEnabled is true
+ * 3. HMAC verification for all RPC requests
+ */
+import * as crypto from 'crypto';
+import { ErrorCode } from '../../types.js';
+// Mock dependencies
+vi.mock('socket.io-client', () => ({
+    io: vi.fn(() => mockSocket),
+}));
+vi.mock('qrcode-terminal', () => ({
+    default: { generate: vi.fn() },
+    generate: vi.fn(),
+}));
+vi.mock('../../connection/auth.js', () => ({
+    verifyFirebaseToken: vi.fn(),
+}));
+vi.mock('../../config/credentials.js', () => ({
+    saveConnectionSettings: vi.fn(),
+    loadConnectionSettings: vi.fn(),
+    isServerTokenExpired: vi.fn(),
+    loadGlobalConfig: vi.fn(() => ({ knownDeviceIds: [] })),
+    saveGlobalConfig: vi.fn(),
+}));
+vi.mock('../../rpc/router.js', () => ({
+    RPCRouter: {
+        initialize: vi.fn(),
+        route: vi.fn(),
+        cleanup: vi.fn(),
+    },
+}));
+vi.mock('../handshake-validation.js', () => ({
+    validateHandshakeTimestamp: vi.fn(() => ({ valid: true })),
+}));
+vi.mock('../../connection/hmac.js', () => ({
+    requireValidHMAC: vi.fn(),
+    validateHMAC: vi.fn(() => true),
+}));
+import { ProxyClient } from '../ProxyClient.js';
+import { requireValidHMAC } from '../../connection/hmac.js';
+import { RPCRouter } from '../../rpc/router.js';
+import { validateHandshakeTimestamp } from '../handshake-validation.js';
+import { io } from 'socket.io-client';
+import { loadGlobalConfig, saveGlobalConfig } from '../../config/credentials.js';
+const mockRequireValidHMAC = requireValidHMAC;
+const mockRPCRouter = RPCRouter;
+const mockValidateHandshakeTimestamp = validateHandshakeTimestamp;
+const mockLoadGlobalConfig = loadGlobalConfig;
+const mockSaveGlobalConfig = saveGlobalConfig;
+// Shared mock socket that all tests use
+let mockSocket;
+let eventHandlers;
+const TEST_SECRET = 'test-secret-key-12345678901234567890';
+const TEST_CLIENT_ID = 'test-client-id';
+/**
+ * Helper to trigger all handlers for an event
+ */
+async function triggerEvent(event, data) {
+    const handlers = eventHandlers[event] || [];
+    for (const handler of handlers) {
+        await handler(data);
+    }
+}
+/**
+ * Create HMAC-signed auth message
+ */
+function createAuthMessage(secret, clientId, deviceId = 'test-device-123') {
+    const timestamp = Date.now();
+    const nonce = Math.random().toString(36).substring(2);
+    const message = { type: 'auth', clientId, timestamp, nonce, deviceId };
+    const messageToSign = timestamp + JSON.stringify({ type: 'auth', clientId, nonce, deviceId });
+    const hmac = crypto.createHmac('sha256', secret).update(messageToSign).digest('hex');
+    return { ...message, hmac };
+}
+/**
+ * Create signed RPC message with HMAC
+ */
+function createSignedRPCMessage(secret, method, params, id = 1) {
+    const timestamp = Date.now();
+    const payload = { jsonrpc: '2.0', method, params, id };
+    const messageToSign = timestamp + JSON.stringify(payload);
+    const hmac = crypto.createHmac('sha256', secret).update(messageToSign).digest('hex');
+    return { ...payload, timestamp, hmac };
+}
+describe('ProxyClient Security', () => {
+    const defaultOptions = {
+        config: {
+            security: { userAuthenticationEnabled: false },
+            terminal: { enabled: true },
+            filesystem: { maxFileSize: '100MB', watchIgnorePatterns: [] },
+            rootPath: '/test/root',
+        },
+        firebaseToken: 'mock-firebase-token',
+        userId: 'test-user-123',
+        tools: {
+            node: { available: true, version: '18.0.0', path: '/usr/bin/node' },
+            git: { available: true, version: '2.39.0', path: '/usr/bin/git' },
+        },
+        existingConnectionSettings: {
+            serverToken: 'existing-server-token',
+            serverTokenExpiry: Date.now() + 86400000,
+            clientId: TEST_CLIENT_ID,
+            secret: TEST_SECRET,
+            userId: 'test-user-123',
+            connectedAt: Date.now(),
+        },
+        proxyServerUrl: 'cli-na-1.spck.io',
+    };
+    beforeEach(() => {
+        vi.clearAllMocks();
+        eventHandlers = {};
+        // Create fresh mock socket for each test
+        mockSocket = {
+            on: vi.fn((event, handler) => {
+                if (!eventHandlers[event])
+                    eventHandlers[event] = [];
+                eventHandlers[event].push(handler);
+            }),
+            once: vi.fn((event, handler) => {
+                if (!eventHandlers[event])
+                    eventHandlers[event] = [];
+                eventHandlers[event].push(handler);
+            }),
+            off: vi.fn(),
+            emit: vi.fn(),
+            disconnect: vi.fn(),
+            id: 'mock-socket-id',
+        };
+        // Update the io mock to return our fresh socket
+        io.mockReturnValue(mockSocket);
+        mockValidateHandshakeTimestamp.mockReturnValue({ valid: true });
+        mockRequireValidHMAC.mockImplementation(() => { });
+    });
+    /**
+     * Setup an authenticated client and return it
+     */
+    async function setupClient(options = defaultOptions) {
+        const client = new ProxyClient(options);
+        // Start connection (non-blocking)
+        client.connect().catch(() => { }); // Ignore connection errors in tests
+        // Wait for handlers to be set up
+        await new Promise(resolve => setImmediate(resolve));
+        // Trigger authenticated event
+        await triggerEvent('authenticated', {
+            clientId: TEST_CLIENT_ID,
+            token: 'mock-server-token',
+            expiresAt: Date.now() + 86400000,
+            userId: 'test-user-123',
+        });
+        await new Promise(resolve => setImmediate(resolve));
+        return client;
+    }
+    describe('Handshake Bypass Prevention', () => {
+        it('should reject protocol_selected from unauthenticated connection', async () => {
+            await setupClient();
+            // Client connects but doesn't authenticate
+            await triggerEvent('client_connecting', { connectionId: 'attacker-1' });
+            // Try to skip auth and send protocol_selected directly
+            await triggerEvent('client_message', {
+                connectionId: 'attacker-1',
+                data: { type: 'protocol_selected', version: 1 },
+            });
+            // Should receive error
+            expect(mockSocket.emit).toHaveBeenCalledWith('handshake', expect.objectContaining({
+                connectionId: 'attacker-1',
+                data: expect.objectContaining({
+                    type: 'error',
+                    code: 'not_authenticated',
+                }),
+            }));
+        });
+        it('should reject RPC from connection without completed handshake', async () => {
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'partial-1' });
+            // Authenticate but don't complete protocol selection
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'partial-1',
+                data: authMessage,
+            });
+            // Try to send RPC before completing handshake
+            const rpcMessage = createSignedRPCMessage(TEST_SECRET, 'terminal.list', {});
+            await triggerEvent('client_message', {
+                connectionId: 'partial-1',
+                data: rpcMessage,
+            });
+            // RPCRouter should NOT be called
+            expect(mockRPCRouter.route).not.toHaveBeenCalled();
+        });
+        it('should accept RPC after completed handshake', async () => {
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'valid-1' });
+            // Complete full handshake
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'valid-1',
+                data: authMessage,
+            });
+            await triggerEvent('client_message', {
+                connectionId: 'valid-1',
+                data: { type: 'protocol_selected', version: 1 },
+            });
+            // Now send RPC
+            mockRPCRouter.route.mockResolvedValue([]);
+            const rpcMessage = createSignedRPCMessage(TEST_SECRET, 'terminal.list', {});
+            await triggerEvent('client_message', {
+                connectionId: 'valid-1',
+                data: rpcMessage,
+            });
+            // RPCRouter should be called
+            expect(mockRPCRouter.route).toHaveBeenCalled();
+        });
+    });
+    describe('User Authentication Enforcement', () => {
+        it('should require user verification when enabled', async () => {
+            const optionsWithUserAuth = {
+                ...defaultOptions,
+                config: {
+                    ...defaultOptions.config,
+                    security: { userAuthenticationEnabled: true },
+                },
+            };
+            await setupClient(optionsWithUserAuth);
+            await triggerEvent('client_connecting', { connectionId: 'user-auth-1' });
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'user-auth-1',
+                data: authMessage,
+            });
+            // Should request user verification
+            expect(mockSocket.emit).toHaveBeenCalledWith('handshake', expect.objectContaining({
+                connectionId: 'user-auth-1',
+                data: expect.objectContaining({
+                    type: 'request_user_verification',
+                }),
+            }));
+        });
+        it('should reject protocol_selected when user verification required but not done', async () => {
+            const optionsWithUserAuth = {
+                ...defaultOptions,
+                config: {
+                    ...defaultOptions.config,
+                    security: { userAuthenticationEnabled: true },
+                },
+            };
+            await setupClient(optionsWithUserAuth);
+            await triggerEvent('client_connecting', { connectionId: 'skip-verify-1' });
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'skip-verify-1',
+                data: authMessage,
+            });
+            // Try to skip user verification
+            await triggerEvent('client_message', {
+                connectionId: 'skip-verify-1',
+                data: { type: 'protocol_selected', version: 1 },
+            });
+            // Should receive error
+            expect(mockSocket.emit).toHaveBeenCalledWith('handshake', expect.objectContaining({
+                connectionId: 'skip-verify-1',
+                data: expect.objectContaining({
+                    type: 'error',
+                    code: 'user_verification_required',
+                }),
+            }));
+        });
+    });
+    describe('HMAC Verification', () => {
+        it('should verify HMAC on all RPC requests', async () => {
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'hmac-1' });
+            // Complete handshake
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'hmac-1',
+                data: authMessage,
+            });
+            await triggerEvent('client_message', {
+                connectionId: 'hmac-1',
+                data: { type: 'protocol_selected', version: 1 },
+            });
+            // Send RPC
+            mockRPCRouter.route.mockResolvedValue({ result: 'ok' });
+            const rpcMessage = createSignedRPCMessage(TEST_SECRET, 'fs.readFile', { path: '/test.txt' });
+            await triggerEvent('client_message', {
+                connectionId: 'hmac-1',
+                data: rpcMessage,
+            });
+            // HMAC should be verified
+            expect(mockRequireValidHMAC).toHaveBeenCalledWith(expect.objectContaining({ method: 'fs.readFile' }), TEST_SECRET);
+        });
+        it('should reject RPC with invalid HMAC', async () => {
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'bad-hmac-1' });
+            // Complete handshake
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'bad-hmac-1',
+                data: authMessage,
+            });
+            await triggerEvent('client_message', {
+                connectionId: 'bad-hmac-1',
+                data: { type: 'protocol_selected', version: 1 },
+            });
+            // Mock HMAC to fail
+            mockRequireValidHMAC.mockImplementation(() => {
+                throw { code: ErrorCode.HMAC_VALIDATION_FAILED, message: 'HMAC validation failed' };
+            });
+            // Send RPC with bad HMAC
+            await triggerEvent('client_message', {
+                connectionId: 'bad-hmac-1',
+                data: {
+                    jsonrpc: '2.0',
+                    method: 'fs.readFile',
+                    params: { path: '/test.txt' },
+                    id: 1,
+                    timestamp: Date.now(),
+                    hmac: 'invalid-signature',
+                },
+            });
+            // Should return HMAC error
+            expect(mockSocket.emit).toHaveBeenCalledWith('rpc', expect.objectContaining({
+                connectionId: 'bad-hmac-1',
+                data: expect.objectContaining({
+                    jsonrpc: '2.0',
+                    error: expect.objectContaining({
+                        code: ErrorCode.HMAC_VALIDATION_FAILED,
+                    }),
+                    id: 1,
+                }),
+            }));
+            // RPCRouter should NOT be called
+            expect(mockRPCRouter.route).not.toHaveBeenCalled();
+        });
+    });
+    describe('Known Device ID Persistence', () => {
+        it('should initialize knownDeviceIds from loadGlobalConfig on construction', () => {
+            mockLoadGlobalConfig.mockReturnValue({ knownDeviceIds: ['persisted-device-1', 'persisted-device-2'] });
+            // Construction triggers loadGlobalConfig via the field initializer
+            new ProxyClient(defaultOptions);
+            expect(mockLoadGlobalConfig).toHaveBeenCalled();
+        });
+        it('should treat a device from global config as known (no saveGlobalConfig call)', async () => {
+            mockLoadGlobalConfig.mockReturnValue({ knownDeviceIds: ['test-device-123'] });
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'known-conn-1' });
+            // Use the pre-loaded device ID — no new-device path should fire
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'test-device-123');
+            await triggerEvent('client_message', { connectionId: 'known-conn-1', data: authMessage });
+            expect(mockSaveGlobalConfig).not.toHaveBeenCalled();
+        });
+        it('should save global config when a genuinely new device connects', async () => {
+            mockLoadGlobalConfig.mockReturnValue({ knownDeviceIds: [] });
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'new-conn-1' });
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'brand-new-device');
+            await triggerEvent('client_message', { connectionId: 'new-conn-1', data: authMessage });
+            expect(mockSaveGlobalConfig).toHaveBeenCalledWith(expect.objectContaining({ knownDeviceIds: expect.arrayContaining(['brand-new-device']) }));
+        });
+        it('should accumulate multiple new device IDs across connections', async () => {
+            mockLoadGlobalConfig.mockReturnValue({ knownDeviceIds: [] });
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'conn-a' });
+            await triggerEvent('client_message', {
+                connectionId: 'conn-a',
+                data: createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'device-alpha'),
+            });
+            await triggerEvent('client_connecting', { connectionId: 'conn-b' });
+            await triggerEvent('client_message', {
+                connectionId: 'conn-b',
+                data: createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'device-beta'),
+            });
+            expect(mockSaveGlobalConfig).toHaveBeenCalledTimes(2);
+            // Second call should include both devices
+            expect(mockSaveGlobalConfig).toHaveBeenLastCalledWith(expect.objectContaining({
+                knownDeviceIds: expect.arrayContaining(['device-alpha', 'device-beta']),
+            }));
+        });
+        it('should not save global config again when an already-seen device reconnects', async () => {
+            mockLoadGlobalConfig.mockReturnValue({ knownDeviceIds: [] });
+            await setupClient();
+            // First connection — new device
+            await triggerEvent('client_connecting', { connectionId: 'first-conn' });
+            await triggerEvent('client_message', {
+                connectionId: 'first-conn',
+                data: createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'recurring-device'),
+            });
+            mockSaveGlobalConfig.mockClear();
+            // Second connection — same device
+            await triggerEvent('client_connecting', { connectionId: 'second-conn' });
+            await triggerEvent('client_message', {
+                connectionId: 'second-conn',
+                data: createAuthMessage(TEST_SECRET, TEST_CLIENT_ID, 'recurring-device'),
+            });
+            expect(mockSaveGlobalConfig).not.toHaveBeenCalled();
+        });
+    });
+    describe('Auth HMAC Validation', () => {
+        it('should reject auth with invalid HMAC signature', async () => {
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'bad-hmac-auth-1' });
+            // Create auth message with wrong secret
+            const badAuthMessage = createAuthMessage('wrong-secret', TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'bad-hmac-auth-1',
+                data: badAuthMessage,
+            });
+            // Should reject
+            expect(mockSocket.emit).toHaveBeenCalledWith('handshake', expect.objectContaining({
+                connectionId: 'bad-hmac-auth-1',
+                data: expect.objectContaining({
+                    type: 'auth_result',
+                    success: false,
+                }),
+            }));
+        });
+        it('should reject auth with expired timestamp', async () => {
+            mockValidateHandshakeTimestamp.mockReturnValue({
+                valid: false,
+                error: 'Timestamp too old',
+            });
+            await setupClient();
+            await triggerEvent('client_connecting', { connectionId: 'old-ts-1' });
+            const authMessage = createAuthMessage(TEST_SECRET, TEST_CLIENT_ID);
+            await triggerEvent('client_message', {
+                connectionId: 'old-ts-1',
+                data: authMessage,
+            });
+            // Should reject
+            expect(mockSocket.emit).toHaveBeenCalledWith('handshake', expect.objectContaining({
+                connectionId: 'old-ts-1',
+                data: expect.objectContaining({
+                    type: 'auth_result',
+                    success: false,
+                }),
+            }));
+        });
+    });
+});
+//# sourceMappingURL=ProxyClient.test.js.map

package/dist/proxy/__tests__/ProxySocketWrapper.test.d.ts

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