spck 0.3.1

package/dist/connection/__tests__/hmac.test.js

@@ -0,0 +1,372 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+/**
+ * Tests for HMAC message signing validation
+ */
+import * as crypto from 'crypto';
+import { validateHMAC, requireValidHMAC, clearNonces, getNonceStats } from '../hmac.js';
+import { ErrorCode } from '../../types.js';
+describe('HMAC Validation', () => {
+    const signingKey = 'test-signing-key-12345';
+    // Clear nonces before each test
+    beforeEach(() => {
+        clearNonces();
+    });
+    function createSignedMessage(method, params, timestamp, customHmac, nonce, deviceId) {
+        const ts = timestamp || Date.now();
+        const nonceValue = nonce || crypto.randomBytes(16).toString('hex');
+        const payload = {
+            jsonrpc: '2.0',
+            method,
+            params,
+            id: 1,
+            nonce: nonceValue,
+        };
+        // Include deviceId if provided (must be in payload for HMAC calculation)
+        if (deviceId) {
+            payload.deviceId = deviceId;
+        }
+        const messageToSign = ts + JSON.stringify(payload);
+        const hmac = customHmac ||
+            crypto.createHmac('sha256', signingKey).update(messageToSign).digest('hex');
+        return {
+            ...payload,
+            timestamp: ts,
+            hmac,
+            nonce: nonceValue,
+        };
+    }
+    describe('validateHMAC', () => {
+        it('should validate correctly signed message', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should reject message with invalid HMAC', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, Date.now(), 'invalid-hmac-signature');
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should reject message with missing HMAC', () => {
+            const message = {
+                jsonrpc: '2.0',
+                method: 'fs.readFile',
+                params: { path: '/test.txt' },
+                id: 1,
+                timestamp: Date.now(),
+                nonce: crypto.randomBytes(16).toString('hex'),
+                // hmac intentionally missing
+            };
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should reject message with missing timestamp', () => {
+            const message = {
+                jsonrpc: '2.0',
+                method: 'fs.readFile',
+                params: { path: '/test.txt' },
+                id: 1,
+                hmac: 'some-hmac',
+                nonce: crypto.randomBytes(16).toString('hex'),
+                // timestamp intentionally missing
+            };
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should reject message signed with wrong key', () => {
+            const wrongKey = 'different-signing-key';
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const payload = {
+                jsonrpc: '2.0',
+                method: 'fs.readFile',
+                params: { path: '/test.txt' },
+                id: 1,
+                nonce,
+            };
+            const timestamp = Date.now();
+            const messageToSign = timestamp + JSON.stringify(payload);
+            const hmac = crypto
+                .createHmac('sha256', wrongKey)
+                .update(messageToSign)
+                .digest('hex');
+            const message = {
+                ...payload,
+                timestamp,
+                hmac,
+                nonce,
+            };
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should reject message with tampered params', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            // Tamper with params after signing
+            message.params = { path: '/tampered.txt' };
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should reject message with tampered method', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            // Tamper with method after signing
+            message.method = 'fs.deleteFile';
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should validate message with deviceId', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, undefined, 'device-123');
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should reject message when deviceId is tampered', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, undefined, 'device-123');
+            // Tamper with deviceId after signing
+            message.deviceId = 'device-456';
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should use constant-time comparison for HMAC', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            // Measure time for correct HMAC
+            const startCorrect = process.hrtime.bigint();
+            validateHMAC(message, signingKey);
+            const correctTime = process.hrtime.bigint() - startCorrect;
+            // Measure time for incorrect HMAC (same length)
+            message.hmac = 'a'.repeat(message.hmac.length);
+            const startIncorrect = process.hrtime.bigint();
+            validateHMAC(message, signingKey);
+            const incorrectTime = process.hrtime.bigint() - startIncorrect;
+            // Time difference should be minimal (constant-time comparison)
+            // Allow up to 10x difference for timing variance
+            const timeDiff = Number(incorrectTime - correctTime);
+            const avgTime = Number((correctTime + incorrectTime) / BigInt(2));
+            const relativeDiff = Math.abs(timeDiff) / avgTime;
+            expect(relativeDiff).toBeLessThan(10);
+        });
+    });
+    describe('requireValidHMAC', () => {
+        it('should pass for valid HMAC', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+        });
+        it('should throw error for invalid HMAC', () => {
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, Date.now(), 'invalid-hmac');
+            expect(() => requireValidHMAC(message, signingKey)).toThrow(expect.objectContaining({
+                code: ErrorCode.HMAC_VALIDATION_FAILED,
+                message: expect.stringContaining('HMAC validation failed'),
+            }));
+        });
+        it('should reject message with old timestamp', () => {
+            const threeMinutesAgo = Date.now() - 3 * 60 * 1000;
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, threeMinutesAgo);
+            expect(() => requireValidHMAC(message, signingKey)).toThrow(expect.objectContaining({
+                code: ErrorCode.HMAC_VALIDATION_FAILED,
+                message: expect.stringContaining('timestamp too old'),
+            }));
+        });
+        it('should accept message within 2 minute window', () => {
+            const oneMinuteAgo = Date.now() - 1 * 60 * 1000;
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, oneMinuteAgo);
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+        });
+        it('should allow 1 minute clock skew for future timestamps', () => {
+            const thirtySecondsInFuture = Date.now() + 30 * 1000;
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, thirtySecondsInFuture);
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+        });
+        it('should reject timestamp more than 1 minute in future', () => {
+            const twoMinutesInFuture = Date.now() + 2 * 60 * 1000;
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, twoMinutesInFuture);
+            expect(() => requireValidHMAC(message, signingKey)).toThrow(expect.objectContaining({
+                code: ErrorCode.HMAC_VALIDATION_FAILED,
+                message: expect.stringContaining('timestamp too old or invalid'),
+            }));
+        });
+        it('should include timestamp details in error', () => {
+            const threeMinutesAgo = Date.now() - 3 * 60 * 1000;
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, threeMinutesAgo);
+            try {
+                requireValidHMAC(message, signingKey);
+                expect.unreachable('Should have thrown error');
+            }
+            catch (error) {
+                expect(error.data).toMatchObject({
+                    timestamp: threeMinutesAgo,
+                    serverTime: expect.any(Number),
+                });
+            }
+        });
+    });
+    describe('Edge Cases', () => {
+        it('should handle empty params', () => {
+            const message = createSignedMessage('terminal.create', {});
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should handle params with special characters', () => {
+            const message = createSignedMessage('fs.writeFile', {
+                path: '/test.txt',
+                content: 'Special chars: 你好 émojis 🚀',
+            });
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should handle params with nested objects', () => {
+            const message = createSignedMessage('git.commit', {
+                dir: '/project',
+                message: 'Test commit',
+                author: {
+                    name: 'Test User',
+                    email: 'test@example.com',
+                    timestamp: 1234567890,
+                },
+            });
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should handle params with arrays', () => {
+            const message = createSignedMessage('git.add', {
+                dir: '/project',
+                filepaths: ['file1.txt', 'file2.txt', 'file3.txt'],
+            });
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should handle very long signing keys', () => {
+            const longKey = 'x'.repeat(1000);
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' });
+            // Re-sign with long key
+            const payload = {
+                jsonrpc: message.jsonrpc,
+                method: message.method,
+                params: message.params,
+                id: message.id,
+                nonce: message.nonce,
+            };
+            const messageToSign = message.timestamp + JSON.stringify(payload);
+            message.hmac = crypto
+                .createHmac('sha256', longKey)
+                .update(messageToSign)
+                .digest('hex');
+            const isValid = validateHMAC(message, longKey);
+            expect(isValid).toBe(true);
+        });
+    });
+    describe('Replay Attack Prevention', () => {
+        it('should accept message with nonce on first use', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+        });
+        it('should reject duplicate nonce (replay attack)', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            // First use should succeed
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+            // Second use should fail (replay attack)
+            const replayMessage = createSignedMessage('fs.readFile', { path: '/test.txt' }, message.timestamp, undefined, nonce);
+            expect(() => requireValidHMAC(replayMessage, signingKey)).toThrow(expect.objectContaining({
+                code: ErrorCode.HMAC_VALIDATION_FAILED,
+                message: expect.stringContaining('Duplicate nonce'),
+            }));
+        });
+        it('should include nonce in error data when rejecting replay', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            // First use
+            requireValidHMAC(message, signingKey);
+            // Second use (replay)
+            const replayMessage = createSignedMessage('fs.readFile', { path: '/test.txt' }, message.timestamp, undefined, nonce);
+            try {
+                requireValidHMAC(replayMessage, signingKey);
+                expect.unreachable('Should have thrown error');
+            }
+            catch (error) {
+                expect(error.data).toMatchObject({
+                    nonce: nonce,
+                });
+            }
+        });
+        it('should accept different nonces', () => {
+            const nonce1 = crypto.randomBytes(16).toString('hex');
+            const nonce2 = crypto.randomBytes(16).toString('hex');
+            const message1 = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce1);
+            const message2 = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce2);
+            expect(() => requireValidHMAC(message1, signingKey)).not.toThrow();
+            expect(() => requireValidHMAC(message2, signingKey)).not.toThrow();
+        });
+        it('should validate nonce signature correctly', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(true);
+        });
+        it('should reject message with tampered nonce', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            // Tamper with nonce after signing
+            message.nonce = crypto.randomBytes(16).toString('hex');
+            const isValid = validateHMAC(message, signingKey);
+            expect(isValid).toBe(false);
+        });
+        it('should track nonce statistics correctly', () => {
+            clearNonces();
+            const nonce1 = crypto.randomBytes(16).toString('hex');
+            const nonce2 = crypto.randomBytes(16).toString('hex');
+            const message1 = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce1);
+            const message2 = createSignedMessage('fs.writeFile', { path: '/test.txt' }, undefined, undefined, nonce2);
+            requireValidHMAC(message1, signingKey);
+            requireValidHMAC(message2, signingKey);
+            const stats = getNonceStats();
+            expect(stats.total).toBe(2);
+            expect(stats.active).toBe(2);
+        });
+        it('should prevent replay flood attack', () => {
+            const nonce = crypto.randomBytes(16).toString('hex');
+            const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+            // First request succeeds
+            expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+            // Flood with replays (all should fail)
+            for (let i = 0; i < 10; i++) {
+                const replayMessage = createSignedMessage('fs.readFile', { path: '/test.txt' }, message.timestamp, undefined, nonce);
+                expect(() => requireValidHMAC(replayMessage, signingKey)).toThrow(expect.objectContaining({
+                    code: ErrorCode.HMAC_VALIDATION_FAILED,
+                    message: expect.stringContaining('Duplicate nonce'),
+                }));
+            }
+        });
+        it('should handle concurrent requests with different nonces', () => {
+            const nonces = Array.from({ length: 100 }, () => crypto.randomBytes(16).toString('hex'));
+            // All should succeed (different nonces)
+            for (const nonce of nonces) {
+                const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+                expect(() => requireValidHMAC(message, signingKey)).not.toThrow();
+            }
+            const stats = getNonceStats();
+            expect(stats.total).toBe(100);
+            expect(stats.active).toBe(100);
+        });
+        it('should clean up nonces when map grows too large', () => {
+            clearNonces();
+            // Add old nonces (expired)
+            const oldTimestamp = Date.now() - 3 * 60 * 1000; // 3 minutes ago
+            for (let i = 0; i < 5; i++) {
+                const nonce = `old-nonce-${i}`;
+                const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, oldTimestamp, undefined, nonce);
+                // These will fail due to old timestamp, but that's ok for this test
+                try {
+                    requireValidHMAC(message, signingKey);
+                }
+                catch { }
+            }
+            // Add many new nonces to trigger cleanup
+            for (let i = 0; i < 10001; i++) {
+                const nonce = `new-nonce-${i}`;
+                const message = createSignedMessage('fs.readFile', { path: '/test.txt' }, undefined, undefined, nonce);
+                requireValidHMAC(message, signingKey);
+            }
+            // Emergency cleanup should have been triggered
+            const stats = getNonceStats();
+            expect(stats.active).toBeLessThanOrEqual(10001);
+        });
+    });
+});
+//# sourceMappingURL=hmac.test.js.map

package/dist/connection/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Firebase JWT authentication with public key verification
+ */
+import { JWTPayload } from '../types.js';
+/**
+ * Verify Firebase JWT token
+ */
+export declare function verifyFirebaseToken(token: string, firebaseProjectId: string, allowedUids: string[]): Promise<JWTPayload>;
+/**
+ * Clear public keys cache (for testing)
+ */
+export declare function clearPublicKeysCache(): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/connection/auth.js

@@ -0,0 +1,91 @@
+/**
+ * Firebase JWT authentication with public key verification
+ */
+import jwt from 'jsonwebtoken';
+import fetch from 'node-fetch';
+import { ErrorCode, createRPCError } from '../types.js';
+const FIREBASE_KEYS_URL = 'https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com';
+let publicKeysCache = null;
+/**
+ * Fetch Firebase public keys with caching
+ */
+async function getFirebasePublicKeys() {
+    const now = Date.now();
+    // Return cached keys if still valid
+    if (publicKeysCache && publicKeysCache.expiresAt > now) {
+        return publicKeysCache.keys;
+    }
+    // Fetch new keys
+    const response = await fetch(FIREBASE_KEYS_URL);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch Firebase public keys: ${response.statusText}`);
+    }
+    const keys = await response.json();
+    // Parse cache-control header for expiration
+    const cacheControl = response.headers.get('cache-control');
+    let maxAge = 3600; // Default: 1 hour
+    if (cacheControl) {
+        const match = cacheControl.match(/max-age=(\d+)/);
+        if (match) {
+            maxAge = parseInt(match[1], 10);
+        }
+    }
+    // Cache the keys
+    publicKeysCache = {
+        keys,
+        expiresAt: now + maxAge * 1000,
+    };
+    return keys;
+}
+/**
+ * Verify Firebase JWT token
+ */
+export async function verifyFirebaseToken(token, firebaseProjectId, allowedUids) {
+    try {
+        // Fetch public keys
+        const publicKeys = await getFirebasePublicKeys();
+        // Decode token header to get kid
+        const decoded = jwt.decode(token, { complete: true });
+        if (!decoded || typeof decoded === 'string') {
+            throw createRPCError(ErrorCode.AUTHENTICATION_FAILED, 'Invalid token format');
+        }
+        const kid = decoded.header.kid;
+        if (!kid || !publicKeys[kid]) {
+            throw createRPCError(ErrorCode.AUTHENTICATION_FAILED, 'Invalid token key ID');
+        }
+        // Verify token signature and claims
+        const publicKey = publicKeys[kid];
+        const payload = jwt.verify(token, publicKey, {
+            algorithms: ['RS256'],
+            audience: firebaseProjectId,
+            issuer: `https://securetoken.google.com/${firebaseProjectId}`,
+        });
+        // Validate UID is in allowed list (if list is not empty)
+        if (allowedUids.length > 0 && !allowedUids.includes(payload.sub)) {
+            throw createRPCError(ErrorCode.UID_NOT_AUTHORIZED, `UID not authorized: ${payload.sub}`, { uid: payload.uid });
+        }
+        return payload;
+    }
+    catch (error) {
+        // Handle JWT errors
+        if (error.name === 'TokenExpiredError') {
+            throw createRPCError(ErrorCode.JWT_EXPIRED, 'JWT token expired', { expiredAt: error.expiredAt });
+        }
+        if (error.name === 'JsonWebTokenError') {
+            throw createRPCError(ErrorCode.AUTHENTICATION_FAILED, `JWT verification failed: ${error.message}`);
+        }
+        // Re-throw if already an RPC error
+        if (error.code && error.message) {
+            throw error;
+        }
+        // Generic error
+        throw createRPCError(ErrorCode.AUTHENTICATION_FAILED, `Authentication failed: ${error.message || 'Unknown error'}`);
+    }
+}
+/**
+ * Clear public keys cache (for testing)
+ */
+export function clearPublicKeysCache() {
+    publicKeysCache = null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/connection/firebase-auth.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Firebase authentication with local callback server
+ * Opens browser for OAuth flow, captures token via localhost POST
+ *
+ * Security features:
+ * - Token sent via POST body (not in URL) to prevent leaking via browser history/referrer
+ * - State parameter for CSRF protection
+ * - Localhost-only callback server
+ */
+import { FirebaseCredentials, StoredCredentials } from '../types.js';
+/**
+ * Abort any in-progress authentication (e.g., on SIGINT).
+ * Cancels the pending fetch and closes the local callback server.
+ */
+export declare function abortCurrentAuth(): void;
+/**
+ * Authenticate with Firebase using secure local callback server
+ * Token is received via POST to prevent exposure in URLs
+ */
+export declare function authenticateWithFirebase(): Promise<FirebaseCredentials>;
+/**
+ * Refresh Firebase ID token using refresh token
+ *
+ * Firebase Token Refresh Protocol:
+ * - Endpoint: https://securetoken.googleapis.com/v1/token?key={API_KEY}
+ * - Method: POST with application/x-www-form-urlencoded
+ * - Body: grant_type=refresh_token&refresh_token={REFRESH_TOKEN}
+ * - Response: { id_token, refresh_token, expires_in, token_type, user_id }
+ * - ID tokens expire after 1 hour (3600 seconds)
+ * - Refresh tokens are long-lived but can be revoked
+ *
+ * @see https://firebase.google.com/docs/reference/rest/auth#section-refresh-token
+ */
+export declare function refreshFirebaseToken(storedCredentials: StoredCredentials): Promise<FirebaseCredentials>;
+/**
+ * Get a valid Firebase ID token by refreshing from stored credentials
+ * Always generates a fresh ID token using the refresh token
+ */
+export declare function getValidFirebaseToken(storedCredentials: StoredCredentials): Promise<FirebaseCredentials>;
+//# sourceMappingURL=firebase-auth.d.ts.map