@mooncompany/uplink-chat 0.5.0

package/server.js

@@ -0,0 +1,404 @@
+/**
+ * Uplink Server - Main entry point
+ * 
+ * Modular architecture:
+ * - server/config.js    - Environment variables and constants
+ * - server/middleware.js - Security headers, CSRF, rate limiting
+ * - server/utils.js     - Logging, fetch helpers, request tracking
+ * - server/tts.js       - ElevenLabs text-to-speech
+ * - server/chat.js      - AI chat functions (transcribe, chat, parallel TTS)
+ * - server/routes.js    - HTTP API endpoints
+ * - server/websocket/   - WebSocket real-time communication (split into submodules)
+ * - server/share.js     - Public share links
+ * - server/sync.js      - Encrypted cross-device sync
+ */
+
+import express from 'express';
+import http from 'http';
+import path from 'path';
+import fs from 'fs/promises';
+import { randomUUID } from 'crypto';
+
+// Server modules
+import { 
+  PORT, ROOT_DIR, TTS_VOICE_NAME as TTS_VOICE, WAKE_WORD,
+  AUDIO_DIR, UPLOADS_DIR, SHARES_DIR, SYNC_DIR,
+  AUDIO_MAX_AGE_MS, UPLOADS_MAX_AGE_MS,
+  MAX_CONCURRENT_REQUESTS, REQUEST_TIMEOUT
+} from './server/config.js';
+import { 
+  securityHeaders, corsMiddleware, csrfProtection, 
+  apiLimiter, jsonUtf8, noCache 
+} from './server/middleware.js';
+import { requireAuth, getAuthStatus, isAuthEnabled } from './server/middleware/auth.js';
+import { log, cleanupOldFiles } from './server/utils.js';
+import { setupRoutes, saveMessageToSync } from './server/routes.js';
+import { setupWebSocket, wsClients, broadcastToAll } from './server/websocket/index.js';
+import { setupShareRoutes } from './server/share.js';
+import { setupSyncRoutes } from './server/sync.js';
+import { generateTTS } from './server/chat.js';
+import { setupGatewayProxy } from './server/gateway-proxy.js';
+import { setupRealtimeRelay } from './server/realtime/index.js';
+import { setupAgentVoiceBridge } from './server/realtime/bridge.js';
+import { setupTailscaleHTTPS } from './server/tailscale-https.js';
+import { startUpdateChecker } from './server/update-checker.js';
+
+// ===========================================
+// CRASH DIAGNOSTICS
+// ===========================================
+process.on('uncaughtException', (err) => {
+  console.error('[CRASH] Uncaught exception:', err.message);
+  console.error(err.stack);
+  // H-15: Exit after logging — process is in undefined state after uncaught exception
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('[CRASH] Unhandled rejection at:', promise);
+  console.error('[CRASH] Reason:', reason);
+  process.exit(1);
+});
+
+process.on('exit', (code) => {
+  console.error(`[EXIT] Process exiting with code: ${code}`);
+});
+
+// ===========================================
+// REQUEST TRACKING
+// ===========================================
+const activeRequests = new Map();
+
+function canAcceptRequest() {
+  const now = Date.now();
+  for (const [id, req] of activeRequests) {
+    if (now - req.startedAt > REQUEST_TIMEOUT) {
+      log('warn', `Request ${id} timed out, removing from active`);
+      activeRequests.delete(id);
+    }
+  }
+  return activeRequests.size < MAX_CONCURRENT_REQUESTS;
+}
+
+function startRequest(type = 'unknown') {
+  const requestId = randomUUID();
+  activeRequests.set(requestId, { startedAt: Date.now(), type });
+  return requestId;
+}
+
+function endRequest(requestId) {
+  activeRequests.delete(requestId);
+}
+
+function isProcessing() {
+  return activeRequests.size > 0;
+}
+
+// Request helpers bundle for modules
+const requestHelpers = {
+  canAcceptRequest,
+  startRequest,
+  endRequest,
+  isProcessing,
+  activeRequests,
+  MAX_CONCURRENT_REQUESTS,
+  textToSpeech: generateTTS
+};
+
+// ===========================================
+// EXPRESS APP SETUP
+// ===========================================
+const app = express();
+// Only trust proxy headers when explicitly configured (behind a reverse proxy)
+// Without this, clients can spoof IPs via X-Forwarded-For to bypass rate limits
+if (process.env.TRUST_PROXY) {
+  app.set('trust proxy', process.env.TRUST_PROXY === 'true' ? 1 : process.env.TRUST_PROXY);
+}
+app.disable('x-powered-by');
+
+// CSP nonce middleware - generates unique nonce per request
+function cspNonceMiddleware(req, res, next) {
+  res.locals.nonce = randomUUID().replace(/-/g, '');
+  next();
+}
+
+// Middleware
+// Cache-clear endpoint (bypasses SW since it's under /api/)
+// SW version check — returns current CACHE_NAME so SW can self-update
+app.get('/api/sw-version', (req, res) => {
+  res.json({ version: 'uplink-v62' });
+});
+
+app.get('/api/clear-cache', (req, res) => {
+  res.send(`<!DOCTYPE html><html><head><title>Clear Cache</title></head>
+<body style="background:#111;color:#0f0;font-family:monospace;padding:2rem;">
+<h2>Clearing cache...</h2><pre id="log"></pre>
+<script>
+const log=document.getElementById('log');
+function p(m){log.textContent+=m+'\\n';}
+async function go(){
+  const r=await navigator.serviceWorker.getRegistrations();
+  p('Found '+r.length+' SW(s)');
+  for(const s of r){await s.unregister();p('Unregistered: '+s.scope);}
+  const k=await caches.keys();
+  p('Found '+k.length+' cache(s)');
+  for(const c of k){await caches.delete(c);p('Deleted: '+c);}
+  p('\\nDone! Redirecting in 2s...');
+  setTimeout(()=>window.location.href='/',2000);
+}
+go().catch(e=>p('Error: '+e.message));
+</script></body></html>`);
+});
+
+app.use(cspNonceMiddleware);  // Generate CSP nonce for every request
+app.use(securityHeaders);
+app.use(corsMiddleware);
+
+// Static asset caching with long-lived immutable cache headers
+// Cache JS and CSS for 1 year (they have cache-bust query strings in production)
+app.use('/js', express.static(path.join(ROOT_DIR, 'public', 'js'), {
+  maxAge: '1y',
+  immutable: true,
+  setHeaders: (res) => {
+    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+  }
+}));
+
+app.use('/css', express.static(path.join(ROOT_DIR, 'public', 'css'), {
+  maxAge: '1y',
+  immutable: true,
+  setHeaders: (res) => {
+    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+  }
+}));
+
+// Agent avatars - no cache (user-uploaded, can change anytime)
+app.use('/img/agents', express.static(path.join(ROOT_DIR, 'public', 'img', 'agents'), {
+  maxAge: 0,
+  setHeaders: (res) => {
+    res.setHeader('Cache-Control', 'no-cache, must-revalidate');
+  }
+}));
+
+// Images and other static assets - cache for 1 day (may change more frequently)
+app.use(express.static(path.join(ROOT_DIR, 'public'), {
+  index: false,
+  maxAge: '1d',
+  setHeaders: (res, filePath) => {
+    if (filePath.endsWith('.png') || filePath.endsWith('.jpg') || filePath.endsWith('.svg') || filePath.endsWith('.webp')) {
+      res.setHeader('Cache-Control', 'public, max-age=86400'); // 1 day
+    }
+  }
+}));
+
+// Apply no-cache to all other routes (HTML, API endpoints)
+app.use(noCache);
+
+// Serve uploaded images for chat history persistence
+app.use('/uploads', express.static(path.join(ROOT_DIR, 'uploads')));
+
+// Cache-bust version (change this to force client updates)
+const CACHE_BUST_VERSION = Date.now();
+console.log(`[Cache] Version: ${CACHE_BUST_VERSION}`);
+
+// Serve index.html with CSP nonce and cache-bust injected
+app.get('/', async (req, res) => {
+  try {
+    const indexPath = path.join(ROOT_DIR, 'public', 'index.html');
+    let html = await fs.readFile(indexPath, 'utf-8');
+    
+    // Inject nonce into all script tags (handles both <script> and <script src=...>)
+    const nonce = res.locals.nonce;
+    html = html.replace(/<script(\s|>)/g, `<script nonce="${nonce}"$1`);
+    
+    // Add cache-bust query string to JS and CSS files
+    html = html.replace(/\.js"/g, `.js?v=${CACHE_BUST_VERSION}"`);
+    html = html.replace(/\.css"/g, `.css?v=${CACHE_BUST_VERSION}"`);
+    
+    // Prevent caching of index.html
+    res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+    res.setHeader('Pragma', 'no-cache');
+    res.setHeader('Expires', '0');
+    res.setHeader('Surrogate-Control', 'no-store'); // Cloudflare
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.send(html);
+  } catch (error) {
+    console.error('[ERROR] Failed to serve index.html:', error);
+    res.status(500).send('Internal Server Error');
+  }
+});
+
+app.use(express.json());
+app.use(jsonUtf8);
+app.use(csrfProtection);
+app.use('/api/', apiLimiter);
+
+// Optional authentication middleware (defense-in-depth)
+// When UPLINK_AUTH_ENABLED=true, all /api routes require Bearer token
+// When disabled (default), routes work as normal for local/Tailscale deployments
+app.use('/api/', requireAuth);
+
+// ===========================================
+// CLEANUP TASKS
+// ===========================================
+async function runCleanup() {
+  await fs.mkdir(AUDIO_DIR, { recursive: true }).catch(err => log('warn', 'Failed to create audio dir:', err.message));
+  await fs.mkdir(UPLOADS_DIR, { recursive: true }).catch(err => log('warn', 'Failed to create uploads dir:', err.message));
+  await cleanupOldFiles(AUDIO_DIR, AUDIO_MAX_AGE_MS, ['.mp3']);
+  await cleanupOldFiles(UPLOADS_DIR, UPLOADS_MAX_AGE_MS);
+}
+
+// Run cleanup every 15 minutes
+setInterval(runCleanup, 15 * 60 * 1000);
+setTimeout(runCleanup, 10000);
+
+// ===========================================
+// ROUTES
+// ===========================================
+
+// Setup API routes
+setupRoutes(app, requestHelpers);
+
+// Setup share routes
+setupShareRoutes(app, SHARES_DIR);
+
+// Setup sync routes
+setupSyncRoutes(app, SYNC_DIR);
+
+// ===========================================
+// GLOBAL ERROR HANDLER (H-16: must be after all routes)
+// ===========================================
+app.use((err, req, res, next) => {
+  console.error('[ERROR]', err.stack || err.message || err);
+  const statusCode = err.statusCode || err.status || 500;
+  const message = process.env.NODE_ENV === 'production'
+    ? 'Internal server error'
+    : (err.message || 'Internal server error');
+  res.status(statusCode).json({ error: true, message });
+});
+
+// ===========================================
+// HTTP SERVER + WEBSOCKET
+// ===========================================
+const server = http.createServer(app);
+
+// Setup Gateway WebSocket Proxy FIRST (uses noServer mode, handles /gateway)
+setupGatewayProxy(server);
+
+// Setup Realtime Voice relay (uses noServer mode, handles /api/realtime)
+setupRealtimeRelay(server);
+
+// Setup Agent Voice Bridge (handles /api/realtime?mode=agent)
+setupAgentVoiceBridge(server);
+
+// Setup main WebSocket (uses server mode with path: '/ws')
+setupWebSocket(server, requestHelpers, saveMessageToSync);
+
+// ===========================================
+// START SERVER
+// ===========================================
+// Determine bind host: env var > config.json networkAccess > auth-based default
+let configNetworkAccess = false;
+try {
+  const { readFileSync } = await import('fs');
+  const configRaw = readFileSync(path.join(import.meta.dirname, 'config.json'), 'utf8');
+  configNetworkAccess = JSON.parse(configRaw).networkAccess === true;
+} catch { /* config not found or invalid */ }
+const BIND_HOST = process.env.UPLINK_HOST || (configNetworkAccess ? '0.0.0.0' : (isAuthEnabled() ? '0.0.0.0' : '127.0.0.1'));
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`[FATAL] Port ${PORT} is already in use`);
+    process.exit(1);
+  }
+});
+
+server.listen(PORT, BIND_HOST, () => {
+  const authStatus = getAuthStatus();
+  const bindAddress = server.address();
+  const isPublicBind = bindAddress.address === '0.0.0.0' || bindAddress.address === '::';
+  
+  console.log(`🛰️  Uplink server running at http://localhost:${PORT}`);
+  console.log(`   WebSocket: ws://localhost:${PORT}/ws`);
+  console.log(`   Gateway Proxy: ws://localhost:${PORT}/gateway`);
+  console.log(`   Bind: ${BIND_HOST}`);
+  console.log(`   Wake word: "${WAKE_WORD}" (hands-free mode)`);
+  console.log(`   TTS: ${TTS_VOICE} (ElevenLabs - Scouse legend)`);
+  console.log(`   Whisper: small model (better accuracy)`);
+  console.log(`   Press Space to talk, Esc to cancel`);
+  
+  // Auth status
+  if (authStatus.enabled) {
+    console.log(`\n🔒 Authentication: ENABLED (defense-in-depth)`);
+    console.log(`   Token configured: ${authStatus.tokenConfigured}`);
+    console.log(`   Token length: ${authStatus.tokenLength} chars (min: ${authStatus.minTokenLength})`);
+  } else {
+    console.log(`\n🔓 Authentication: DISABLED (local/Tailscale mode)`);
+    console.log(`   Set UPLINK_AUTH_ENABLED=true to enable auth middleware`);
+    if (BIND_HOST === '127.0.0.1') {
+      console.log(`   Bind: 127.0.0.1 (auth disabled — set UPLINK_HOST=0.0.0.0 or enable auth for remote access)`);
+    }
+  }
+  
+  // Start update checker (broadcasts to all WebSocket clients)
+  startUpdateChecker(server, (msg) => broadcastToAll(msg));
+
+  // Public exposure warning (GROUP C from audit findings)
+  if (isPublicBind && !authStatus.enabled) {
+    console.log(`\n⚠️  WARNING: Uplink is bound to all interfaces (${bindAddress.address}) without authentication!`);
+    console.log(`⚠️  This is NOT RECOMMENDED for public deployments.`);
+    console.log(`⚠️  For local/Tailscale use only, or enable authentication:`);
+    console.log(`⚠️    UPLINK_AUTH_ENABLED=true`);
+    console.log(`⚠️    UPLINK_AUTH_TOKEN=<your-long-random-token>`);
+  }
+});
+
+// ===========================================
+// TAILSCALE HTTPS (auto-detect, zero config)
+// ===========================================
+(async () => {
+  try {
+    const ts = await setupTailscaleHTTPS(app, {
+      onServer: (httpsServer, domain) => {
+        // Wire up the same WebSocket handlers on the HTTPS server
+        setupGatewayProxy(httpsServer);
+        setupRealtimeRelay(httpsServer);
+        setupAgentVoiceBridge(httpsServer);
+        setupWebSocket(httpsServer, requestHelpers, saveMessageToSync);
+      }
+    });
+    if (ts) {
+      console.log(`\n🔐 Tailscale HTTPS: ${ts.url}`);
+      console.log(`   Secure WebSocket: wss://${ts.domain}:${new URL(ts.url).port}/ws`);
+      console.log(`   Gateway Proxy: wss://${ts.domain}:${new URL(ts.url).port}/gateway`);
+      console.log(`   📱 Mobile mic/camera: ✅ enabled`);
+    }
+  } catch (err) {
+    console.warn('[Tailscale] HTTPS setup failed:', err.message);
+  }
+})();
+
+// ===========================================
+// GRACEFUL SHUTDOWN (H-14)
+// ===========================================
+let isShuttingDown = false;
+
+function gracefulShutdown(signal) {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+  console.log(`\n[SHUTDOWN] ${signal} received, closing server gracefully...`);
+
+  // Stop accepting new connections
+  server.close(() => {
+    console.log('[SHUTDOWN] HTTP server closed');
+    process.exit(0);
+  });
+
+  // Force exit after 10 seconds if graceful shutdown hangs
+  setTimeout(() => {
+    console.error('[SHUTDOWN] Forced exit after timeout');
+    process.exit(1);
+  }, 10000).unref();
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));

package/utils/detect-tool-usage.js

@@ -0,0 +1,93 @@
+/**
+ * Tool Detection Utility (Server-side)
+ * Detects tool usage in AI response text
+ * 
+ * Previously duplicated in:
+ * - server/routes.js
+ * - server/websocket.js
+ */
+
+// Tool keyword mappings
+const TOOL_KEYWORDS = {
+  'Read': 'read',
+  'Write': 'write',
+  'Edit': 'edit',
+  'exec': 'exec',
+  'browser': 'browser',
+  'web_search': 'search',
+  'web_fetch': 'fetch',
+  'image': 'image',
+  'tts': 'tts',
+  'nodes': 'nodes',
+  'message': 'message',
+  'canvas': 'canvas'
+};
+
+/**
+ * Detect tool usage in AI response text
+ * Looks for <invoke name="ToolName"> patterns in the response
+ * 
+ * @param {string} text - The AI response text to analyze
+ * @returns {string[]} - Array of detected tool names (lowercase)
+ */
+export function detectToolUsage(text) {
+  if (typeof text !== 'string' || !text) {
+    return [];
+  }
+  
+  const tools = [];
+  
+  for (const [keyword, toolName] of Object.entries(TOOL_KEYWORDS)) {
+    const regex = new RegExp(`<invoke name="${keyword}"`, 'gi');
+    if (regex.test(text)) {
+      if (!tools.includes(toolName)) {
+        tools.push(toolName);
+      }
+    }
+  }
+  
+  return tools;
+}
+
+/**
+ * Check if a specific tool was used
+ * 
+ * @param {string} text - The AI response text
+ * @param {string} tool - The tool name to check for
+ * @returns {boolean} - True if the tool was detected
+ */
+export function wasToolUsed(text, tool) {
+  const detected = detectToolUsage(text);
+  return detected.includes(tool.toLowerCase());
+}
+
+/**
+ * Get all available tool names
+ * 
+ * @returns {string[]} - Array of all known tool names
+ */
+export function getAvailableTools() {
+  return Object.values(TOOL_KEYWORDS);
+}
+
+/**
+ * Get the keyword for a tool name
+ * 
+ * @param {string} toolName - The tool name (lowercase)
+ * @returns {string|null} - The keyword or null if not found
+ */
+export function getToolKeyword(toolName) {
+  for (const [keyword, name] of Object.entries(TOOL_KEYWORDS)) {
+    if (name === toolName.toLowerCase()) {
+      return keyword;
+    }
+  }
+  return null;
+}
+
+export default {
+  detectToolUsage,
+  wasToolUsed,
+  getAvailableTools,
+  getToolKeyword
+};

package/utils/errors.js

@@ -0,0 +1,158 @@
+/**
+ * Standardized Error Response Utility
+ * 
+ * All API errors should return:
+ * { error: true, message: "...", code: "ERROR_CODE" }
+ */
+
+// Error codes enum
+export const ErrorCodes = {
+  // Client errors (4xx)
+  BAD_REQUEST: 'BAD_REQUEST',
+  INVALID_INPUT: 'INVALID_INPUT',
+  MISSING_FIELD: 'MISSING_FIELD',
+  INVALID_FORMAT: 'INVALID_FORMAT',
+  INVALID_FILE_TYPE: 'INVALID_FILE_TYPE',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  RATE_LIMITED: 'RATE_LIMITED',
+  UPLOAD_FAILED: 'UPLOAD_FAILED',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  
+  // Server errors (5xx)
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  GATEWAY_ERROR: 'GATEWAY_ERROR',
+  TTS_ERROR: 'TTS_ERROR',
+  TRANSCRIPTION_ERROR: 'TRANSCRIPTION_ERROR',
+  CONFIG_ERROR: 'CONFIG_ERROR',
+  TIMEOUT: 'TIMEOUT',
+};
+
+/**
+ * Send a standardized error response
+ * @param {Response} res - Express response object
+ * @param {number} status - HTTP status code
+ * @param {string} message - Human-readable error message
+ * @param {string} code - Error code from ErrorCodes
+ */
+export function sendError(res, status, message, code = ErrorCodes.INTERNAL_ERROR) {
+  return res.status(status).json({
+    error: true,
+    message,
+    code,
+  });
+}
+
+/**
+ * Send a 400 Bad Request error
+ */
+export function badRequest(res, message, code = ErrorCodes.BAD_REQUEST) {
+  return sendError(res, 400, message, code);
+}
+
+/**
+ * Send a 401 Unauthorized error
+ */
+export function unauthorized(res, message = 'Unauthorized') {
+  return sendError(res, 401, message, ErrorCodes.UNAUTHORIZED);
+}
+
+/**
+ * Send a 403 Forbidden error
+ */
+export function forbidden(res, message = 'Forbidden') {
+  return sendError(res, 403, message, ErrorCodes.FORBIDDEN);
+}
+
+/**
+ * Send a 404 Not Found error
+ */
+export function notFound(res, message = 'Not found') {
+  return sendError(res, 404, message, ErrorCodes.NOT_FOUND);
+}
+
+/**
+ * Send a 429 Rate Limited error
+ */
+export function rateLimited(res, message = 'Too many requests. Please wait a moment.') {
+  return sendError(res, 429, message, ErrorCodes.RATE_LIMITED);
+}
+
+/**
+ * Send a 500 Internal Server Error
+ * Automatically sanitizes error messages in production
+ */
+export function internalError(res, message = 'Internal server error', code = ErrorCodes.INTERNAL_ERROR) {
+  // Sanitize error messages in production to avoid leaking implementation details
+  const sanitizedMessage = (process.env.NODE_ENV === 'production' && typeof message === 'string')
+    ? 'Internal server error'
+    : message;
+  return sendError(res, 500, sanitizedMessage, code);
+}
+
+/**
+ * Custom error class with status code and error code
+ */
+export class AppError extends Error {
+  constructor(message, statusCode = 500, code = ErrorCodes.INTERNAL_ERROR) {
+    super(message);
+    this.name = 'AppError';
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+}
+
+/**
+ * Sanitize error messages for client response
+ * Removes stack traces and sensitive info
+ * @param {Error} error - The error to sanitize
+ * @returns {string} - Safe error message
+ */
+export function sanitizeErrorMessage(error) {
+  if (error instanceof AppError) {
+    return error.message;
+  }
+  // For unknown errors, return generic message in production
+  if (process.env.NODE_ENV === 'production') {
+    return 'An unexpected error occurred';
+  }
+  return error.message || 'An unexpected error occurred';
+}
+
+/**
+ * Create a standardized error response object
+ * @param {string} message - Error message
+ * @param {string} code - Error code
+ * @returns {Object} - Error response object
+ */
+export function createErrorResponse(message, code = ErrorCodes.INTERNAL_ERROR) {
+  return {
+    error: true,
+    message,
+    code,
+  };
+}
+
+/**
+ * Alias for internalError (used by some modules)
+ */
+export const serverError = internalError;
+
+/**
+ * Namespace export for modules that import { errors }
+ */
+export const errors = {
+  ErrorCodes,
+  sendError,
+  badRequest,
+  unauthorized,
+  forbidden,
+  notFound,
+  rateLimited,
+  internalError,
+  serverError,
+  AppError,
+  sanitizeErrorMessage,
+  createErrorResponse,
+};