@mooncompany/uplink-chat 0.5.0

package/server/stt/faster-whisper.js

@@ -0,0 +1,72 @@
+/**
+ * Faster-Whisper STT Provider
+ * 
+ * Calls a local faster-whisper-server instance via its OpenAI-compatible API.
+ * User must run faster-whisper-server separately (e.g., via pip or Docker).
+ * No API key needed — it's a local service.
+ * 
+ * Server: https://github.com/fedirz/faster-whisper-server
+ * Install: pip install faster-whisper-server
+ * Run: faster-whisper-server --host 0.0.0.0 --port 8000
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Transcribe audio using a local Faster-Whisper server
+ * @param {string} audioPath - Path to the audio file
+ * @param {Object} config - Runtime config object
+ * @returns {Promise<string>} Transcribed text
+ */
+export async function transcribe(audioPath, config) {
+  const baseUrl = config.fasterWhisperUrl || process.env.FASTER_WHISPER_URL;
+  if (!baseUrl) {
+    throw new Error('Faster-Whisper server URL not configured');
+  }
+
+  // Normalize URL — remove trailing slash
+  const url = `${baseUrl.replace(/\/+$/, '')}/v1/audio/transcriptions`;
+
+  const audioBuffer = await fs.readFile(audioPath);
+  const ext = path.extname(audioPath).slice(1) || 'webm';
+  const blob = new Blob([audioBuffer], { type: `audio/${ext}` });
+
+  const formData = new FormData();
+  formData.append('file', blob, `audio.${ext}`);
+  formData.append('model', 'whisper-large-v3-turbo'); // faster-whisper-server ignores this if model is fixed
+  formData.append('language', 'en');
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      body: formData,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Faster-Whisper server error: ${response.status} - ${error}`);
+    }
+
+    const data = await response.json();
+    return data.text || '';
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    if (error.name === 'AbortError') {
+      throw new Error('Faster-Whisper request timed out (30s). Is the server running?');
+    }
+
+    if (error.code === 'ECONNREFUSED') {
+      throw new Error(`Faster-Whisper server not reachable at ${baseUrl}. Is it running?`);
+    }
+
+    throw error;
+  }
+}

package/server/stt/groq.js

@@ -0,0 +1,51 @@
+/**
+ * Groq STT Provider
+ * 
+ * Uses Groq's OpenAI-compatible Audio Transcriptions API.
+ * Requires a Groq API key. Free tier available.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+const GROQ_BASE_URL = 'https://api.groq.com/openai/v1/audio/transcriptions';
+
+/**
+ * Transcribe audio using Groq API
+ * @param {string} audioPath - Path to the audio file
+ * @param {Object} config - Runtime config object
+ * @returns {Promise<string>} Transcribed text
+ */
+export async function transcribe(audioPath, config) {
+  const apiKey = config.groqApiKey || process.env.GROQ_API_KEY;
+  if (!apiKey) {
+    throw new Error('Groq API key not configured');
+  }
+
+  const model = config.groqSttModel || 'whisper-large-v3-turbo';
+
+  const audioBuffer = await fs.readFile(audioPath);
+  const ext = path.extname(audioPath).slice(1) || 'webm';
+  const blob = new Blob([audioBuffer], { type: `audio/${ext}` });
+
+  const formData = new FormData();
+  formData.append('file', blob, `audio.${ext}`);
+  formData.append('model', model);
+  formData.append('language', 'en');
+
+  const response = await fetch(GROQ_BASE_URL, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Groq API error: ${response.status} - ${error}`);
+  }
+
+  const data = await response.json();
+  return data.text || '';
+}

package/server/stt/index.js

@@ -0,0 +1,196 @@
+/**
+ * STT Module - Speech-to-Text provider abstraction
+ * 
+ * Reads runtime config to determine which STT provider to use,
+ * then delegates to the appropriate provider module.
+ * 
+ * Providers:
+ *   - openai: OpenAI Whisper API (requires OpenAI API key)
+ *   - groq: Groq API (requires Groq API key, free tier available)
+ *   - faster-whisper: Local faster-whisper-server (requires running server)
+ *   - none: STT disabled
+ */
+
+import { loadConfig } from '../runtime-config.js';
+import { transcribe as openaiTranscribe } from './openai.js';
+import { transcribe as groqTranscribe } from './groq.js';
+import { transcribe as fasterWhisperTranscribe } from './faster-whisper.js';
+import { createLogger } from '../logger.js';
+
+const log = createLogger('STT');
+
+/**
+ * Resolve the effective STT provider.
+ * If sttProvider is 'none' but openaiApiKey exists, auto-detect to 'openai' (backward compat).
+ * @param {Object} config - Runtime config
+ * @returns {string} Effective provider name
+ */
+function resolveProvider(config) {
+  const provider = config.sttProvider;
+
+  // Explicit provider set — use it
+  if (provider && provider !== 'none') {
+    return provider;
+  }
+
+  // Auto-detect: if openaiApiKey is available and no provider explicitly set, use OpenAI
+  if (config.openaiApiKey || process.env.OPENAI_API_KEY) {
+    return 'openai';
+  }
+
+  return 'none';
+}
+
+/**
+ * Transcribe audio using the configured STT provider
+ * @param {string} audioPath - Path to the audio file
+ * @returns {Promise<string>} Transcribed text, or empty string on error
+ */
+export async function transcribe(audioPath) {
+  const config = await loadConfig();
+  const provider = resolveProvider(config);
+
+  if (provider === 'none') {
+    log.warn('No STT provider configured. Set one in Settings → Voice & STT.');
+    return '';
+  }
+
+  try {
+    let text = '';
+
+    switch (provider) {
+      case 'openai':
+        text = await openaiTranscribe(audioPath, config);
+        break;
+      case 'groq':
+        text = await groqTranscribe(audioPath, config);
+        break;
+      case 'faster-whisper':
+        text = await fasterWhisperTranscribe(audioPath, config);
+        break;
+      default:
+        log.error(`Unknown provider: ${provider}`);
+        return '';
+    }
+
+    log.debug(`[${provider}] Transcribed: "${text}"`);
+    return text;
+  } catch (error) {
+    log.error(`[${provider}] Transcription error:`, error.message);
+    return '';
+  }
+}
+
+/**
+ * Detect if a local Faster-Whisper server is running at localhost:8000
+ * @returns {Promise<{fasterWhisperAvailable: boolean}>}
+ */
+export async function detectLocalSTT() {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+    const resp = await fetch('http://localhost:8000/health', {
+      signal: controller.signal,
+    }).catch(() => null);
+    clearTimeout(timeoutId);
+
+    if (resp) {
+      return { fasterWhisperAvailable: true };
+    }
+
+    // Some servers don't have /health, try root
+    const controller2 = new AbortController();
+    const timeoutId2 = setTimeout(() => controller2.abort(), 2000);
+    const resp2 = await fetch('http://localhost:8000', {
+      signal: controller2.signal,
+    }).catch(() => null);
+    clearTimeout(timeoutId2);
+
+    return { fasterWhisperAvailable: !!resp2 };
+  } catch {
+    return { fasterWhisperAvailable: false };
+  }
+}
+
+/**
+ * Test the current STT configuration
+ * Verifies the provider is reachable and properly configured.
+ * @param {string} [audioPath] - Optional audio file to test with
+ * @returns {Promise<{success: boolean, provider: string, transcription?: string, error?: string}>}
+ */
+export async function testSTT(audioPath) {
+  const config = await loadConfig();
+  const provider = resolveProvider(config);
+
+  if (provider === 'none') {
+    return { success: false, provider: 'none', error: 'No STT provider configured' };
+  }
+
+  // If no audio file provided, just validate config
+  if (!audioPath) {
+    try {
+      switch (provider) {
+        case 'openai': {
+          const key = config.openaiApiKey || process.env.OPENAI_API_KEY;
+          if (!key) return { success: false, provider, error: 'OpenAI API key not set' };
+          return { success: true, provider, message: 'OpenAI API key is configured' };
+        }
+        case 'groq': {
+          const key = config.groqApiKey || process.env.GROQ_API_KEY;
+          if (!key) return { success: false, provider, error: 'Groq API key not set' };
+          return { success: true, provider, message: 'Groq API key is configured' };
+        }
+        case 'faster-whisper': {
+          const url = config.fasterWhisperUrl || process.env.FASTER_WHISPER_URL;
+          if (!url) return { success: false, provider, error: 'Faster-Whisper server URL not set' };
+          // Try to reach the server
+          try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const resp = await fetch(`${url.replace(/\/+$/, '')}/health`, {
+              signal: controller.signal,
+            }).catch(() => null);
+            clearTimeout(timeoutId);
+            // Some servers don't have /health, so any response is fine
+            if (resp) {
+              return { success: true, provider, message: `Faster-Whisper server reachable at ${url}` };
+            }
+            // Try just connecting
+            const controller2 = new AbortController();
+            const timeoutId2 = setTimeout(() => controller2.abort(), 5000);
+            const resp2 = await fetch(url.replace(/\/+$/, ''), {
+              signal: controller2.signal,
+            }).catch(() => null);
+            clearTimeout(timeoutId2);
+            if (resp2) {
+              return { success: true, provider, message: `Faster-Whisper server reachable at ${url}` };
+            }
+            return { success: false, provider, error: `Cannot reach Faster-Whisper server at ${url}` };
+          } catch {
+            return { success: false, provider, error: `Cannot reach Faster-Whisper server at ${url}` };
+          }
+        }
+        default:
+          return { success: false, provider, error: `Unknown provider: ${provider}` };
+      }
+    } catch (error) {
+      return { success: false, provider, error: error.message };
+    }
+  }
+
+  // Test with actual audio file
+  try {
+    const text = await transcribe(audioPath);
+    return {
+      success: true,
+      provider,
+      transcription: text,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      provider,
+      error: error.message,
+    };
+  }
+}

package/server/stt/openai.js

@@ -0,0 +1,49 @@
+/**
+ * OpenAI Whisper STT Provider
+ * 
+ * Uses the OpenAI Audio Transcriptions API.
+ * Requires an OpenAI API key.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Transcribe audio using OpenAI Whisper API
+ * @param {string} audioPath - Path to the audio file
+ * @param {Object} config - Runtime config object
+ * @returns {Promise<string>} Transcribed text
+ */
+export async function transcribe(audioPath, config) {
+  const apiKey = config.openaiApiKey || process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error('OpenAI API key not configured');
+  }
+
+  const model = config.openaiSttModel || 'whisper-1';
+
+  const audioBuffer = await fs.readFile(audioPath);
+  const ext = path.extname(audioPath).slice(1) || 'webm';
+  const blob = new Blob([audioBuffer], { type: `audio/${ext}` });
+
+  const formData = new FormData();
+  formData.append('file', blob, `audio.${ext}`);
+  formData.append('model', model);
+  formData.append('language', 'en');
+
+  const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`OpenAI Whisper API error: ${response.status} - ${error}`);
+  }
+
+  const data = await response.json();
+  return data.text || '';
+}

package/server/sync.js

@@ -0,0 +1,244 @@
+/**
+ * Sync Module - Encrypted cross-device sync
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import lockfile from 'proper-lockfile';
+import { log } from './utils.js';
+import { sanitizeSyncId } from '../utils/id-sanitize.js';
+import { sendSuccess, sendError, sendNotFoundError } from '../utils/response.js';
+import { verifyBearerToken } from './middleware.js';
+
+// Maximum sync data size: 10MB (encrypted data can be large)
+const MAX_SYNC_SIZE_BYTES = 10 * 1024 * 1024;
+// Sync data TTL: 30 days of inactivity
+const SYNC_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+// Minimum encryption key length (base64-encoded 256-bit key)
+const MIN_ENCRYPTION_KEY_LENGTH = 32;
+
+/**
+ * Validate encrypted data structure
+ * Checks that the data appears to be properly encrypted (not plaintext)
+ * @param {any} encryptedData - The encrypted data payload
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateEncryptedData(encryptedData) {
+  if (!encryptedData) {
+    return { valid: false, error: 'encryptedData required' };
+  }
+
+  // If it's a string, check it looks like encrypted data (base64 or similar)
+  if (typeof encryptedData === 'string') {
+    // Encrypted data should be reasonably long (at least 32 chars for IV + some ciphertext)
+    if (encryptedData.length < MIN_ENCRYPTION_KEY_LENGTH) {
+      return { valid: false, error: 'encryptedData appears too short to be properly encrypted' };
+    }
+    return { valid: true };
+  }
+
+  // If it's an object, check for expected encryption fields
+  if (typeof encryptedData === 'object') {
+    // Common encrypted data structure: { iv, ciphertext } or { encrypted, nonce }
+    const hasIv = encryptedData.iv && typeof encryptedData.iv === 'string';
+    const hasCiphertext = encryptedData.ciphertext && typeof encryptedData.ciphertext === 'string';
+    const hasEncrypted = encryptedData.encrypted && typeof encryptedData.encrypted === 'string';
+    const hasNonce = encryptedData.nonce && typeof encryptedData.nonce === 'string';
+
+    if ((hasIv && hasCiphertext) || (hasEncrypted && hasNonce) || hasEncrypted) {
+      return { valid: true };
+    }
+
+    // Also accept raw encrypted string in object
+    if (encryptedData.data && typeof encryptedData.data === 'string') {
+      return { valid: true };
+    }
+
+    return { valid: false, error: 'encryptedData missing required encryption fields (iv/ciphertext or encrypted/nonce)' };
+  }
+
+  return { valid: false, error: 'encryptedData must be a string or object' };
+}
+
+/**
+ * Cleanup old sync files that haven't been accessed in SYNC_TTL_MS
+ * @param {string} syncDir - Directory containing sync files
+ */
+async function cleanupOldSyncFiles(syncDir) {
+  try {
+    const files = await fs.readdir(syncDir);
+    const now = Date.now();
+    let cleaned = 0;
+    
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      
+      const filePath = path.join(syncDir, file);
+      try {
+        const stat = await fs.stat(filePath);
+        const age = now - stat.mtimeMs;
+        
+        if (age > SYNC_TTL_MS) {
+          await fs.unlink(filePath);
+          cleaned++;
+          log('debug', `[Sync] Cleaned up stale sync file: ${file}`);
+        }
+      } catch (statError) {
+        // Skip files we can't stat
+      }
+    }
+    
+    if (cleaned > 0) {
+      log('info', `[Sync] Cleaned up ${cleaned} stale sync files`);
+    }
+  } catch (cleanupError) {
+    log('error', '[Sync] Cleanup error:', cleanupError.message);
+  }
+}
+
+/**
+ * Middleware to validate Content-Length before receiving body
+ * @param {number} maxSize - Maximum allowed body size in bytes
+ */
+function validateContentLength(maxSize) {
+  return (req, res, next) => {
+    const contentLength = parseInt(req.get('Content-Length') || '0', 10);
+    
+    if (contentLength > maxSize) {
+      log('warn', `[Sync] Rejected request: Content-Length ${contentLength} exceeds max ${maxSize}`);
+      return sendError(res, `Request too large (max ${maxSize / 1024 / 1024}MB)`, 413);
+    }
+    
+    next();
+  };
+}
+
+/**
+ * Setup sync routes
+ * @param {Express} app - Express app instance
+ * @param {string} syncDir - Directory to store sync data
+ */
+export function setupSyncRoutes(app, syncDir) {
+  // Ensure sync directory exists
+  fs.mkdir(syncDir, { recursive: true }).catch(() => {});
+  
+  // Run cleanup on startup and every 24 hours
+  cleanupOldSyncFiles(syncDir);
+  setInterval(() => cleanupOldSyncFiles(syncDir), 24 * 60 * 60 * 1000);
+
+  // Push encrypted history to server
+  app.post('/api/sync/push', verifyBearerToken, validateContentLength(MAX_SYNC_SIZE_BYTES), async (req, res) => {
+    try {
+      const { syncId, encryptedData, timestamp } = req.body;
+
+      // Validate syncId using centralized utility
+      const syncIdResult = sanitizeSyncId(syncId);
+      if (!syncIdResult.valid) {
+        return sendError(res, syncIdResult.error, 400);
+      }
+      const safeSyncId = syncIdResult.sanitized;
+      
+      // Validate encrypted data structure
+      const encryptionResult = validateEncryptedData(encryptedData);
+      if (!encryptionResult.valid) {
+        return sendError(res, encryptionResult.error, 400);
+      }
+      
+      // Double-check size limit (defense in depth - body parser may have already limited)
+      const dataSize = typeof encryptedData === 'string'
+        ? encryptedData.length
+        : JSON.stringify(encryptedData).length;
+      if (dataSize > MAX_SYNC_SIZE_BYTES) {
+        log('warn', `[Sync] Rejected push: size ${(dataSize / 1024 / 1024).toFixed(2)}MB exceeds limit`);
+        return sendError(res, `Sync data too large (max ${MAX_SYNC_SIZE_BYTES / 1024 / 1024}MB)`, 413);
+      }
+      
+      const syncFile = path.join(syncDir, `${safeSyncId}.json`);
+      
+      // Use atomic write with file locking to prevent concurrent write corruption
+      let release;
+      try {
+        // Create file if it doesn't exist (needed for lockfile)
+        try {
+          await fs.access(syncFile);
+        } catch {
+          await fs.writeFile(syncFile, JSON.stringify({ encryptedData: null, timestamp: 0, updatedAt: Date.now() }));
+        }
+        
+        release = await lockfile.lock(syncFile, {
+          retries: { retries: 5, minTimeout: 50, maxTimeout: 500 }
+        });
+        
+        await fs.writeFile(syncFile, JSON.stringify({
+          encryptedData,
+          timestamp: timestamp || Date.now(),
+          updatedAt: Date.now()
+        }, null, 2));
+        
+        log('debug', `[Sync] Pushed data for syncId: ${safeSyncId.substring(0, 8)}...`);
+        return sendSuccess(res, { timestamp: Date.now() });
+      } finally {
+        if (release) {
+          await release();
+        }
+      }
+    } catch (pushError) {
+      log('error', '[Sync] Push error:', pushError.message);
+      return sendError(res, 'Sync push failed', 500);
+    }
+  });
+
+  // Pull encrypted history from server
+  app.get('/api/sync/pull', verifyBearerToken, async (req, res) => {
+    try {
+      const { syncId } = req.query;
+      
+      // Validate syncId using centralized utility
+      const syncIdResult = sanitizeSyncId(syncId);
+      if (!syncIdResult.valid) {
+        return sendError(res, syncIdResult.error, 400);
+      }
+      const safeSyncId = syncIdResult.sanitized;
+
+      const syncFile = path.join(syncDir, `${safeSyncId}.json`);
+
+      try {
+        const fileContent = await fs.readFile(syncFile, 'utf8');
+        const syncData = JSON.parse(fileContent);
+        return sendSuccess(res, syncData);
+      } catch (readError) {
+        return sendNotFoundError(res, 'No sync data found');
+      }
+    } catch (pullError) {
+      log('error', '[Sync] Pull error:', pullError.message);
+      return sendError(res, 'Sync pull failed', 500);
+    }
+  });
+
+  // Check if sync data exists
+  app.get('/api/sync/check', verifyBearerToken, async (req, res) => {
+    try {
+      const { syncId } = req.query;
+      
+      // Validate syncId using centralized utility
+      const syncIdResult = sanitizeSyncId(syncId);
+      if (!syncIdResult.valid) {
+        return sendError(res, syncIdResult.error, 400);
+      }
+      const safeSyncId = syncIdResult.sanitized;
+
+      const syncFile = path.join(syncDir, `${safeSyncId}.json`);
+
+      try {
+        const stat = await fs.stat(syncFile);
+        return sendSuccess(res, { exists: true, updatedAt: stat.mtimeMs });
+      } catch (statError) {
+        return sendSuccess(res, { exists: false });
+      }
+    } catch (checkError) {
+      return sendError(res, 'Sync check failed', 500);
+    }
+  });
+}
+
+export default { setupSyncRoutes };