spck 0.3.1

package/src/connection/firebase-auth.ts

@@ -0,0 +1,504 @@
+/**
+ * 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 * as http from 'http';
+import * as crypto from 'crypto';
+import jwt from 'jsonwebtoken';
+import open from 'open';
+import qrcode from 'qrcode-terminal';
+import { FirebaseCredentials, StoredCredentials } from '../types.js';
+import { saveCredentials } from '../config/credentials.js';
+import { logAuth } from '../utils/logger.js';
+import { t } from '../i18n/index.js';
+import { fetchServerList, selectBestServer, isValidDomain } from '../config/server-selection.js';
+
+const AUTH_TIMEOUT = 10 * 60 * 1000; // 10 minutes
+const FIREBASE_AUTH_BASE_URL = 'https://spck.io/auth';
+
+// Module-level references to allow aborting auth from outside (e.g., SIGINT handler)
+let _authAbortController: AbortController | null = null;
+let _authCallbackServer: http.Server | null = null;
+
+/**
+ * Abort any in-progress authentication (e.g., on SIGINT).
+ * Cancels the pending fetch and closes the local callback server.
+ */
+export function abortCurrentAuth(): void {
+  _authAbortController?.abort();
+  _authCallbackServer?.close();
+  _authAbortController = null;
+  _authCallbackServer = null;
+}
+
+/**
+ * Find an available port for the local callback server
+ */
+async function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+
+    server.listen(0, () => {
+      const address = server.address();
+      const port = typeof address === 'string' ? 0 : address?.port || 0;
+
+      server.close(() => {
+        resolve(port);
+      });
+    });
+
+    server.on('error', reject);
+  });
+}
+
+interface TokenResult {
+  token: string;
+  refreshToken: string;
+}
+
+/**
+ * Long-poll proxy server for token (manual flow).
+ * The server holds the connection open until the browser posts the token (up to 30s),
+ * then returns 202 on timeout so we reconnect immediately — minimal round-trips.
+ */
+async function pollServerForToken(serverUrl: string, code: string, signal: AbortSignal): Promise<TokenResult | null> {
+  while (!signal.aborted) {
+    try {
+      const response = await fetch(`https://${serverUrl}/api/auth/token/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+        signal
+      });
+
+      if (response.status === 202) {
+        // Server hold timed out — reconnect immediately (no sleep needed)
+        continue;
+      }
+
+      if (!response.ok) {
+        // Brief pause on unexpected errors before retrying
+        await new Promise(resolve => setTimeout(resolve, 3000));
+        continue;
+      }
+
+      const result = await response.json();
+      if (result.idToken && result.refreshToken) {
+        return { token: result.idToken, refreshToken: result.refreshToken };
+      }
+
+      // Unexpected successful response without tokens — brief pause
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } catch (error: any) {
+      if (error.name === 'AbortError') return null;
+      // Network error — wait before retrying
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse POST body from request
+ */
+function parsePostBody(req: http.IncomingMessage): Promise<Record<string, string>> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk.toString(); });
+    req.on('end', () => {
+      try {
+        // Try JSON first
+        if (req.headers['content-type']?.includes('application/json')) {
+          resolve(JSON.parse(body));
+        } else {
+          // Parse URL-encoded form data
+          const params = new URLSearchParams(body);
+          const result: Record<string, string> = {};
+          params.forEach((value, key) => { result[key] = value; });
+          resolve(result);
+        }
+      } catch (e) {
+        reject(e);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Authenticate with Firebase using secure local callback server
+ * Token is received via POST to prevent exposure in URLs
+ */
+export async function authenticateWithFirebase(): Promise<FirebaseCredentials> {
+  console.log('\n=== ' + t('auth.title') + ' ===\n');
+
+  // 1. Select best proxy server
+  const servers = await fetchServerList();
+  const { server: selectedServer } = await selectBestServer(servers);
+  const proxyServerUrl = selectedServer.url;
+
+  if (!isValidDomain(proxyServerUrl)) {
+    throw new Error(`Untrusted proxy server domain: ${proxyServerUrl}`);
+  }
+
+  // 2. Start local HTTP server
+  const port = await getAvailablePort();
+  console.log(t('auth.startingCallback', { port: String(port) }));
+
+  const callbackServer = http.createServer();
+
+  await new Promise<void>(resolve => {
+    callbackServer.listen(port, () => resolve());
+  });
+
+  const redirectUrl = `http://localhost:${port}/callback`;
+
+  // 3. Generate code for both browser and manual flows
+  const code = crypto.randomBytes(32).toString('hex');
+
+  // 4. Build auth URLs
+  // Browser flow: localhost callback
+  const browserUrl = new URL(FIREBASE_AUTH_BASE_URL);
+  browserUrl.searchParams.set('redirect', redirectUrl);
+  browserUrl.searchParams.set('state', code);
+
+  // Manual flow: proxy server relay (server param is hostname only, https:// is assumed)
+  const manualUrl = new URL(FIREBASE_AUTH_BASE_URL);
+  manualUrl.searchParams.set('code', code);
+  manualUrl.searchParams.set('server', proxyServerUrl);
+
+  // 5. Open browser (primary method)
+  console.log(t('auth.openingBrowser') + '\n');
+
+  try {
+    await open(browserUrl.toString());
+  } catch (error: any) {
+    console.warn('⚠️  ' + t('auth.couldNotOpenBrowser', { message: error.message }) + '\n');
+  }
+
+  // 6. Display fallback method
+  console.log(t('auth.manualAuthHint') + '\n');
+
+  // Display QR code
+  qrcode.generate(manualUrl.toString(), { small: true });
+
+  console.log('\n' + t('auth.visitUrl', { url: manualUrl.toString() }) + '\n');
+  console.log(t('auth.waiting') + '\n');
+
+  // 7. Wait for authentication from either source (browser or manual)
+  const abortController = new AbortController();
+  _authAbortController = abortController;
+  _authCallbackServer = callbackServer;
+
+  const result = await new Promise<FirebaseCredentials>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      abortController.abort();
+      callbackServer.close();
+      reject(new Error('Authentication timeout after 10 minutes'));
+    }, AUTH_TIMEOUT);
+
+    // Start polling server API (manual flow)
+    const serverPolling = pollServerForToken(proxyServerUrl, code, abortController.signal).then(token => {
+      if (token) {
+        abortController.abort();
+        callbackServer.close();
+        return token;
+      }
+      return null;
+    });
+
+    // Handle localhost callback (browser flow)
+    callbackServer.on('request', async (req, res) => {
+      // Add CORS headers for POST requests from browser
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      // Handle preflight
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // Only handle callback path
+      if (!req.url || !req.url.startsWith('/callback')) {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      // Parse request parameters
+      let receivedState: string | null = null;
+      let token: string | null = null;
+      let refreshToken: string | null = null;
+      let error: string | null = null;
+
+      try {
+        if (req.method === 'POST') {
+          const body = await parsePostBody(req);
+          receivedState = body.state || null;
+          token = body.token || null;
+          refreshToken = body.refreshToken || null;
+          error = body.error || null;
+        } else {
+          const url = new URL(req.url, `http://localhost:${port}`);
+          receivedState = url.searchParams.get('state');
+          token = url.searchParams.get('token');
+          refreshToken = url.searchParams.get('refreshToken');
+          error = url.searchParams.get('error');
+        }
+      } catch (parseError: any) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: 'Failed to parse request' }));
+        reject(new Error(`Failed to parse request: ${parseError.message}`));
+        return;
+      }
+
+      // Verify state/code (CSRF protection)
+      if (receivedState !== code) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: 'Invalid state parameter' }));
+        reject(new Error('Invalid state parameter'));
+        return;
+      }
+
+      // Check for error
+      if (error) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error }));
+        reject(new Error(error));
+        return;
+      }
+
+      // Check for token
+      if (!token) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: 'No token received' }));
+        reject(new Error('No token received'));
+        return;
+      }
+
+      // Check for refresh token BEFORE decoding
+      if (!refreshToken) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: 'No refresh token received' }));
+        reject(new Error('No refresh token received'));
+        return;
+      }
+
+      // Decode and validate token
+      let decoded: any;
+      try {
+        decoded = jwt.decode(token);
+
+        if (!decoded || typeof decoded === 'string') {
+          throw new Error('Invalid token format');
+        }
+
+        if (!decoded.sub && !decoded.uid) {
+          throw new Error('Token missing user ID');
+        }
+
+        if (!decoded.exp) {
+          throw new Error('Token missing expiry');
+        }
+      } catch (decodeError: any) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: `Invalid token: ${decodeError.message}` }));
+        reject(new Error(`Invalid token: ${decodeError.message}`));
+        return;
+      }
+
+      // All validations passed - send success response
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ success: true }));
+
+      // Clean up and resolve
+      clearTimeout(timeout);
+      abortController.abort(); // Stop server polling
+
+      const credentials: FirebaseCredentials = {
+        firebaseToken: token,
+        firebaseTokenExpiry: decoded.exp * 1000,
+        refreshToken,
+        userId: decoded.sub || decoded.uid
+      };
+
+      resolve(credentials);
+    });
+
+    callbackServer.on('error', (error) => {
+      clearTimeout(timeout);
+      abortController.abort();
+      reject(error);
+    });
+
+    // Handle server polling result (manual flow)
+    serverPolling.then(result => {
+      if (!result) return; // Aborted or timed out
+
+      try {
+        const { token, refreshToken } = result;
+
+        // Decode token to get userId and expiry
+        const decoded: any = jwt.decode(token);
+
+        if (!decoded || typeof decoded === 'string') {
+          throw new Error('Invalid token format');
+        }
+
+        if (!decoded.sub && !decoded.uid) {
+          throw new Error('Token missing user ID');
+        }
+
+        if (!decoded.exp) {
+          throw new Error('Token missing expiry');
+        }
+
+        clearTimeout(timeout);
+
+        const credentials: FirebaseCredentials = {
+          firebaseToken: token,
+          firebaseTokenExpiry: decoded.exp * 1000,
+          refreshToken,
+          userId: decoded.sub || decoded.uid
+        };
+
+        resolve(credentials);
+      } catch (error: any) {
+        reject(new Error(`Invalid token from server: ${error.message}`));
+      }
+    }).catch(error => {
+      clearTimeout(timeout);
+      abortController.abort();
+      callbackServer.close();
+      reject(error);
+    });
+  });
+
+  // 8. Close server and clear module-level references
+  callbackServer.close();
+  _authAbortController = null;
+  _authCallbackServer = null;
+
+  // 9. Save credentials
+  saveCredentials(result);
+
+  logAuth('firebase_auth_success', {
+    userId: result.userId,
+    method: 'firebase'
+  });
+
+  console.log('✅ ' + t('auth.success'));
+  console.log('   ' + t('auth.userId', { userId: result.userId }) + '\n');
+
+  return result;
+}
+
+// Firebase API key for token refresh
+const FIREBASE_API_KEY = 'AIzaSyCFgtHhWiM-EdFBdiDw9ISHfcGOqbV3OCU';
+
+/**
+ * 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 async function refreshFirebaseToken(storedCredentials: StoredCredentials): Promise<FirebaseCredentials> {
+  if (!storedCredentials.refreshToken) {
+    console.log('⚠️  ' + t('auth.noRefreshToken'));
+    return authenticateWithFirebase();
+  }
+
+  try {
+    const response = await fetch(
+      `https://securetoken.googleapis.com/v1/token?key=${FIREBASE_API_KEY}`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        body: `grant_type=refresh_token&refresh_token=${encodeURIComponent(storedCredentials.refreshToken)}`
+      }
+    );
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      const errorMessage = errorData.error?.message || `HTTP ${response.status}`;
+
+      // Handle specific Firebase errors
+      if (errorMessage === 'TOKEN_EXPIRED' || errorMessage === 'INVALID_REFRESH_TOKEN') {
+        logAuth('token_refresh_failed', {
+          userId: storedCredentials.userId,
+          reason: errorMessage
+        }, 'warn');
+        console.log('⚠️  ' + t('auth.refreshTokenExpired'));
+        return authenticateWithFirebase();
+      }
+
+      throw new Error(`Token refresh failed: ${errorMessage}`);
+    }
+
+    const data = await response.json();
+
+    // Firebase returns: id_token, refresh_token, expires_in, token_type, user_id
+    const newToken = data.id_token;
+    const newRefreshToken = data.refresh_token;
+    const parsedExpiresIn = parseInt(data.expires_in, 10);
+    const expiresIn = isNaN(parsedExpiresIn) ? 3600 : parsedExpiresIn; // Default 1 hour
+    const userId = data.user_id;
+
+    if (!newToken) {
+      throw new Error('No ID token in refresh response');
+    }
+
+    // Build full credentials with fresh ID token
+    const fullCredentials: FirebaseCredentials = {
+      firebaseToken: newToken,
+      firebaseTokenExpiry: Date.now() + (expiresIn * 1000),
+      refreshToken: newRefreshToken || storedCredentials.refreshToken,
+      userId: userId || storedCredentials.userId
+    };
+
+    // Save only refreshToken + userId to disk (not the ephemeral ID token)
+    saveCredentials({
+      refreshToken: fullCredentials.refreshToken,
+      userId: fullCredentials.userId,
+      proxyServerUrl: storedCredentials.proxyServerUrl
+    });
+
+    return fullCredentials;
+  } catch (error: any) {
+    logAuth('token_refresh_error', {
+      userId: storedCredentials.userId,
+      error: error.message
+    }, 'error');
+    console.error(t('auth.tokenRefreshError', { message: error.message }));
+    console.log('⚠️  ' + t('auth.tokenRefreshFailed'));
+    return authenticateWithFirebase();
+  }
+}
+
+/**
+ * Get a valid Firebase ID token by refreshing from stored credentials
+ * Always generates a fresh ID token using the refresh token
+ */
+export async function getValidFirebaseToken(storedCredentials: StoredCredentials): Promise<FirebaseCredentials> {
+  console.log('🔄 ' + t('auth.generatingToken'));
+  return refreshFirebaseToken(storedCredentials);
+}

package/src/connection/hmac.ts

@@ -0,0 +1,139 @@
+/**
+ * HMAC message signing validation with replay attack prevention
+ */
+
+import * as crypto from 'crypto';
+import { JSONRPCRequest, ErrorCode, createRPCError } from '../types.js';
+
+/**
+ * Nonce tracking to prevent replay attacks
+ * Stores nonces with their expiry timestamps
+ */
+const seenNonces = new Map<string, number>();
+
+/**
+ * Clean up expired nonces from the tracking map
+ */
+function cleanExpiredNonces(): void {
+  const now = Date.now();
+  for (const [nonce, expiry] of seenNonces.entries()) {
+    if (expiry < now) {
+      seenNonces.delete(nonce);
+    }
+  }
+}
+
+/**
+ * Get statistics about nonce tracking (for testing/monitoring)
+ */
+export function getNonceStats(): { total: number; active: number } {
+  const now = Date.now();
+  let active = 0;
+  for (const expiry of seenNonces.values()) {
+    if (expiry >= now) {
+      active++;
+    }
+  }
+  return { total: seenNonces.size, active };
+}
+
+/**
+ * Clear all tracked nonces (for testing)
+ */
+export function clearNonces(): void {
+  seenNonces.clear();
+}
+
+/**
+ * Validate HMAC signature on JSON-RPC request
+ */
+export function validateHMAC(message: JSONRPCRequest, signingKey: string): boolean {
+  if (!message.hmac || !message.timestamp) {
+    return false;
+  }
+
+  // Reconstruct the message that was signed (must match client's _computeHMAC)
+  // Client uses: const { timestamp, hmac, ...rest } = request
+  // So we need to include all fields except timestamp and hmac
+  const payload: any = {
+    jsonrpc: message.jsonrpc,
+    method: message.method,
+    params: message.params,
+    id: message.id,
+    nonce: message.nonce
+  };
+
+  // Include deviceId if present (client includes it)
+  if ('deviceId' in message) {
+    payload.deviceId = (message as any).deviceId;
+  }
+
+  const messageToSign = message.timestamp + JSON.stringify(payload);
+
+  // Compute HMAC
+  const expectedHmac = crypto
+    .createHmac('sha256', signingKey)
+    .update(messageToSign)
+    .digest('hex');
+
+  // Check lengths match before constant-time comparison
+  if (message.hmac.length !== expectedHmac.length) {
+    return false;
+  }
+
+  // Compare with provided HMAC (constant-time comparison)
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(message.hmac),
+      Buffer.from(expectedHmac)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate HMAC or throw error
+ */
+export function requireValidHMAC(message: JSONRPCRequest, signingKey: string): void {
+  if (!validateHMAC(message, signingKey)) {
+    throw createRPCError(
+      ErrorCode.HMAC_VALIDATION_FAILED,
+      'HMAC validation failed - message signature invalid or missing'
+    );
+  }
+
+  // Check timestamp is recent (within 2 minutes)
+  if (message.timestamp) {
+    const now = Date.now();
+    const age = now - message.timestamp;
+    const maxAge = 2 * 60 * 1000; // 2 minutes (reduced from 5 to mitigate replay attacks)
+
+    if (age > maxAge || age < -60000) {
+      // Allow 1 minute clock skew
+      throw createRPCError(
+        ErrorCode.HMAC_VALIDATION_FAILED,
+        'Message timestamp too old or invalid',
+        { timestamp: message.timestamp, serverTime: now }
+      );
+    }
+  }
+
+  // Check nonce to prevent replay attacks
+  if (seenNonces.has(message.nonce)) {
+    throw createRPCError(
+      ErrorCode.HMAC_VALIDATION_FAILED,
+      'Duplicate nonce detected - possible replay attack',
+      { nonce: message.nonce }
+    );
+  }
+
+  // Store nonce with expiry (2 minutes from now)
+  const maxAge = 2 * 60 * 1000;
+  seenNonces.set(message.nonce, Date.now() + maxAge);
+
+  // Clean up expired nonces periodically
+  if (seenNonces.size > 1000) {
+    cleanExpiredNonces();
+  }
+}