@mooncompany/uplink-chat 0.5.0

package/server/gateway-proxy.js

@@ -0,0 +1,318 @@
+/**
+ * Gateway WebSocket Proxy - Forwards client connections to OpenClaw Gateway
+ * 
+ * This module creates a WebSocket endpoint at /ws/gateway that proxies
+ * connections to the local OpenClaw Gateway, enabling browser clients to
+ * communicate directly with the Gateway.
+ */
+
+import { WebSocketServer, WebSocket } from 'ws';
+import { log } from './utils.js';
+import { ALLOWED_ORIGINS } from './config.js';
+
+// Default Gateway WebSocket URL
+const GATEWAY_PROXY_TARGET = process.env.GATEWAY_PROXY_TARGET || 'ws://localhost:18789/ws';
+
+// Connection limits
+const MAX_PROXY_CONNECTIONS = 10;
+const MAX_CONNECTIONS_PER_IP = 5;
+const ipConnectionCounts = new Map(); // ip -> count
+
+// Track connected proxy clients for sync broadcasts
+const proxyClients = new Map(); // clientId -> { ws, gatewayWs }
+
+/**
+ * Verify if the origin is allowed for proxy connections
+ * Checks localhost, 127.0.0.1, *.ts.net, and ALLOWED_ORIGINS
+ * @param {string|undefined} origin - Origin header value
+ * @returns {boolean} - True if origin is allowed
+ */
+function verifyProxyOrigin(origin) {
+  // NOTE: Unlike /ws (which rejects null origins per L-02), the proxy ALLOWS null origins.
+  // This is intentional: non-browser WS clients (Node.js, curl, server-side tools) don't send
+  // Origin headers, and the Gateway itself validates the forwarded Bearer token.
+  // The /ws endpoint is browser-only, so rejecting null there prevents non-browser abuse.
+  // Here, the proxy serves both browser and non-browser clients.
+  if (!origin) return true;
+
+  try {
+    const url = new URL(origin);
+    const hostname = url.hostname;
+
+    // Allow localhost and loopback
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+      return true;
+    }
+
+    // Allow Tailscale domains (*.ts.net)
+    if (hostname.endsWith('.ts.net')) {
+      return true;
+    }
+
+    // Check configured ALLOWED_ORIGINS
+    if (ALLOWED_ORIGINS && ALLOWED_ORIGINS.includes(origin)) {
+      return true;
+    }
+  } catch (e) {
+    // Invalid origin URL
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Sets up the Gateway WebSocket proxy on path /gateway
+ * Uses noServer mode to avoid conflicts with other WebSocket servers
+ * @param {http.Server} server - HTTP server instance
+ */
+export function setupGatewayProxy(server) {
+  const wss = new WebSocketServer({ noServer: true });
+  
+  // Handle upgrade requests for /gateway path
+  server.on('upgrade', (request, socket, head) => {
+    const { pathname } = new URL(request.url, `http://${request.headers.host}`);
+    log('debug', `[Gateway Proxy] Upgrade request for: ${pathname}`);
+    
+    if (pathname === '/gateway') {
+      log('debug', '[Gateway Proxy] Handling /gateway upgrade');
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        log('debug', '[Gateway Proxy] Upgrade complete, emitting connection');
+        wss.emit('connection', ws, request);
+      });
+    }
+    // Don't handle other paths - let other WebSocket servers handle them
+  });
+
+  wss.on('connection', (clientWs, req) => {
+    const clientIp = req.socket.remoteAddress;
+    const clientId = `proxy-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Origin validation
+    const origin = req.headers.origin;
+    if (!verifyProxyOrigin(origin)) {
+      log('warn', `[Gateway Proxy] Rejected connection from ${clientIp} — invalid origin: ${origin}`);
+      clientWs.close(1008, 'Origin not allowed');
+      return;
+    }
+
+    // Global connection limit
+    if (proxyClients.size >= MAX_PROXY_CONNECTIONS) {
+      log('warn', `[Gateway Proxy] Rejected connection from ${clientIp} — max connections reached (${MAX_PROXY_CONNECTIONS})`);
+      clientWs.close(1013, 'Too many connections');
+      return;
+    }
+
+    // Per-IP connection limit
+    const currentIpCount = ipConnectionCounts.get(clientIp) || 0;
+    if (currentIpCount >= MAX_CONNECTIONS_PER_IP) {
+      log('warn', `[Gateway Proxy] Rejected connection from ${clientIp} — per-IP limit reached (${MAX_CONNECTIONS_PER_IP})`);
+      clientWs.close(1013, 'Too many connections from this IP');
+      return;
+    }
+    ipConnectionCounts.set(clientIp, currentIpCount + 1);
+
+    log('info', `[Gateway Proxy] Client connected from ${clientIp} (${clientId})`);
+
+    // Get auth token from query param (browser WS can't set headers) or Authorization header
+    // NOTE (M-37 / C-04): Token in query string is INTENTIONAL for browser WebSocket compatibility.
+    // Browser WebSocket API cannot set custom headers, so we accept ?token= query param.
+    // The proxy correctly forwards this as Authorization: Bearer header to the Gateway.
+    // Risk is minimal on local/Tailscale networks (no proxy/CDN logging query strings).
+    // This is the same pattern used by OpenClaw's own browser clients.
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const queryToken = url.searchParams.get('token');
+    const authHeader = req.headers.authorization;
+    const token = queryToken || (authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : authHeader);
+
+    // Create connection options for the Gateway
+    const gatewayOptions = {};
+    if (token) {
+      // Forward token as proper Bearer header to Gateway (Gateway validates it)
+      gatewayOptions.headers = {
+        'Authorization': `Bearer ${token}`
+      };
+    }
+
+    // Create outbound connection to Gateway
+    let gatewayWs;
+    try {
+      gatewayWs = new WebSocket(GATEWAY_PROXY_TARGET, gatewayOptions);
+    } catch (err) {
+      log('error', '[Gateway Proxy] Failed to create Gateway connection:', err.message);
+      clientWs.close(1011, 'Failed to connect to Gateway');
+      return;
+    }
+
+    let clientClosed = false;
+    let gatewayClosed = false;
+
+    // Forward messages from client to Gateway
+    clientWs.on('message', (data) => {
+      if (gatewayWs.readyState === WebSocket.OPEN) {
+        try {
+          gatewayWs.send(data);
+        } catch (err) {
+          log('error', '[Gateway Proxy] Error forwarding to Gateway:', err.message);
+        }
+      }
+    });
+
+    // Forward messages from Gateway to client
+    gatewayWs.on('message', (data) => {
+      if (clientWs.readyState === WebSocket.OPEN) {
+        try {
+          clientWs.send(data);
+        } catch (err) {
+          log('error', '[Gateway Proxy] Error forwarding to client:', err.message);
+        }
+      }
+    });
+
+    // Handle client close
+    clientWs.on('close', (code, reason) => {
+      clientClosed = true;
+      log('info', `[Gateway Proxy] Client disconnected (code: ${code})`);
+      proxyClients.delete(clientId);
+      // Decrement per-IP connection count
+      const count = ipConnectionCounts.get(clientIp) || 1;
+      if (count <= 1) {
+        ipConnectionCounts.delete(clientIp);
+      } else {
+        ipConnectionCounts.set(clientIp, count - 1);
+      }
+      if (!gatewayClosed && gatewayWs.readyState === WebSocket.OPEN) {
+        gatewayWs.close();
+      }
+    });
+
+    // Handle Gateway close
+    gatewayWs.on('close', (code, reason) => {
+      gatewayClosed = true;
+      log('info', `[Gateway Proxy] Gateway disconnected (code: ${code})`);
+      if (!clientClosed && clientWs.readyState === WebSocket.OPEN) {
+        clientWs.close();
+      }
+    });
+
+    // Handle client errors
+    clientWs.on('error', (err) => {
+      log('error', '[Gateway Proxy] Client error:', err.message);
+      if (!gatewayClosed && gatewayWs.readyState === WebSocket.OPEN) {
+        gatewayWs.close();
+      }
+    });
+
+    // Handle Gateway errors
+    gatewayWs.on('error', (err) => {
+      log('error', '[Gateway Proxy] Gateway error:', err.message);
+      // Send error to client if still connected
+      if (clientWs.readyState === WebSocket.OPEN) {
+        try {
+          clientWs.send(JSON.stringify({
+            type: 'error',
+            error: 'Gateway connection error: ' + err.message
+          }));
+        } catch (e) {
+          // Ignore send errors
+        }
+        clientWs.close(1011, 'Gateway connection error');
+      }
+    });
+
+    // Handle Gateway connection open
+    gatewayWs.on('open', () => {
+      log('debug', '[Gateway Proxy] Connected to Gateway');
+      // Track client for sync broadcasts
+      proxyClients.set(clientId, { ws: clientWs, gatewayWs, lastActivity: Date.now() });
+    });
+
+    // Keepalive ping/pong to prevent proxy timeouts (Tailscale, etc.)
+    const keepaliveInterval = setInterval(() => {
+      if (clientWs.readyState === WebSocket.OPEN) {
+        try {
+          clientWs.ping();
+        } catch (err) {
+          log('warn', '[Gateway Proxy] Ping failed:', err.message);
+        }
+      }
+      if (gatewayWs.readyState === WebSocket.OPEN) {
+        try {
+          gatewayWs.ping();
+        } catch (err) {
+          log('warn', '[Gateway Proxy] Gateway ping failed:', err.message);
+        }
+      }
+    }, 15000); // 15 seconds
+
+    // Clean up interval on close
+    const cleanupKeepalive = () => {
+      clearInterval(keepaliveInterval);
+    };
+    clientWs.on('close', cleanupKeepalive);
+    gatewayWs.on('close', cleanupKeepalive);
+  });
+  
+  // Clean up on close (add to existing close handlers above)
+  wss.on('close', () => {
+    proxyClients.clear();
+  });
+
+  log('info', `[Gateway Proxy] WebSocket proxy ready at /gateway -> ${GATEWAY_PROXY_TARGET}`);
+  return wss;
+}
+
+/**
+ * Broadcast a message to all Gateway proxy clients
+ * Used for cross-device sync to reach mobile clients
+ * @param {Object|string} message - Message to send
+ * @returns {{ sent: number, failed: number }}
+ */
+export function broadcastToProxyClients(message) {
+  const data = typeof message === 'string' ? message : JSON.stringify(message);
+  let sent = 0;
+  let failed = 0;
+  
+  log('info', `[Gateway Proxy] Broadcasting to ${proxyClients.size} proxy clients`);
+  
+  for (const [clientId, { ws }] of proxyClients) {
+    try {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+        sent++;
+        log('debug', `[Gateway Proxy] Sent to ${clientId}`);
+      } else {
+        log('warn', `[Gateway Proxy] Client ${clientId} not open (state: ${ws.readyState})`);
+      }
+    } catch (err) {
+      failed++;
+      log('warn', `[Gateway Proxy] Broadcast failed for ${clientId}: ${err.message}`);
+    }
+  }
+  
+  log('info', `[Gateway Proxy] Broadcast complete: ${sent} sent, ${failed} failed`);
+  
+  return { sent, failed };
+}
+
+/**
+ * Get count of connected proxy clients
+ */
+export function getProxyClientCount() {
+  return proxyClients.size;
+}
+
+/**
+ * Get proxy client info for debugging
+ */
+export function getProxyClientInfo() {
+  const clients = [];
+  for (const [clientId, { ws }] of proxyClients) {
+    clients.push({
+      id: clientId,
+      readyState: ws.readyState,
+      readyStateLabel: ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'][ws.readyState] || 'UNKNOWN'
+    });
+  }
+  return { count: proxyClients.size, clients };
+}

package/server/index.js

@@ -0,0 +1,22 @@
+/**
+ * Uplink Server Modules
+ * 
+ * This directory contains extracted modules from the main server.js
+ * to improve maintainability and separation of concerns.
+ * 
+ * Module Structure:
+ * - utils.js    - Common utilities (logging, fetch, cleanup, SSRF prevention)
+ * - tts.js      - ElevenLabs TTS (configurable voice)
+ * - share.js    - Public share links for conversations
+ * - sync.js     - Encrypted cross-device sync
+ * 
+ * Future extractions (still in server.js):
+ * - chat.js     - Chat endpoints (voice and text)
+ * - webhooks.js - External webhook integrations
+ * - websocket.js - WebSocket handling
+ */
+
+export * from './utils.js';
+export * from './tts.js';
+export { setupShareRoutes } from './share.js';
+export { setupSyncRoutes } from './sync.js';

package/server/logger.js

@@ -0,0 +1,89 @@
+/**
+ * Structured logger for Uplink
+ * 
+ * Usage:
+ *   import { createLogger } from './logger.js';
+ *   const log = createLogger('my-module');
+ *   
+ *   log.debug('verbose debugging info', { data });
+ *   log.info('normal operational message');
+ *   log.warn('something fishy', error);
+ *   log.error('something broke', error);
+ * 
+ * Environment:
+ *   LOG_LEVEL=debug|info|warn|error|silent (default: info)
+ */
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+const COLORS = {
+  debug: '\x1b[36m',   // Cyan
+  info: '\x1b[32m',    // Green
+  warn: '\x1b[33m',    // Yellow
+  error: '\x1b[31m',   // Red
+  reset: '\x1b[0m',
+  gray: '\x1b[90m',
+};
+
+const currentLevel = LOG_LEVELS[process.env.LOG_LEVEL?.toLowerCase()] ?? LOG_LEVELS.info;
+
+function timestamp() {
+  return new Date().toISOString();
+}
+
+function formatArgs(args) {
+  return args.map(arg => {
+    if (arg instanceof Error) {
+      return arg.stack || arg.message;
+    }
+    if (typeof arg === 'object' && arg !== null) {
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return String(arg);
+      }
+    }
+    return String(arg);
+  }).join(' ');
+}
+
+function writeLog(level, module, ...args) {
+  const levelNum = LOG_LEVELS[level];
+  if (levelNum < currentLevel) return;
+
+  const ts = timestamp();
+  const color = COLORS[level];
+  const reset = COLORS.reset;
+  const gray = COLORS.gray;
+
+  const prefix = `${gray}${ts}${reset} ${color}[${level.toUpperCase()}]${reset} [${module}]`;
+  const message = formatArgs(args);
+
+  const consoleFn = level === 'error' ? console.error :
+                    level === 'warn' ? console.warn :
+                    console.log;
+
+  consoleFn(`${prefix} ${message}`);
+}
+
+/**
+ * Create a logger instance for a module
+ * @param {string} moduleName 
+ */
+export function createLogger(moduleName) {
+  return {
+    debug: (...args) => writeLog('debug', moduleName, ...args),
+    info: (...args) => writeLog('info', moduleName, ...args),
+    warn: (...args) => writeLog('warn', moduleName, ...args),
+    error: (...args) => writeLog('error', moduleName, ...args),
+  };
+}
+
+/** Global default logger */
+export const logger = createLogger('app');

package/server/middleware/auth.js

@@ -0,0 +1,188 @@
+/**
+ * Authentication Middleware - Optional Defense-in-Depth
+ * 
+ * DESIGN NOTES (per OpenClaw docs):
+ * - OpenClaw is "loopback first" — auth is defense-in-depth, not mandatory for local deployments
+ * - Uplink is a STANDALONE app that connects to Gateway as an operator client
+ * - This middleware is OPT-IN via UPLINK_AUTH_ENABLED environment variable
+ * - When disabled (default), all routes work as today
+ * - When enabled, routes require valid Bearer token in Authorization header
+ * 
+ * USAGE:
+ *   import { requireAuth } from './middleware/auth.js';
+ *   app.use('/api', requireAuth);  // Protects all /api routes
+ * 
+ * CONFIGURATION:
+ *   UPLINK_AUTH_ENABLED=true      Enable auth middleware
+ *   UPLINK_AUTH_TOKEN=your-secret  Required Bearer token (must be long/random)
+ * 
+ * When auth is enabled:
+ *   - HTTP requests must include: Authorization: Bearer <token>
+ *   - WebSocket connections must include token in query param or first message
+ *   - set_user command validates user matches authenticated identity
+ */
+
+import crypto from 'crypto';
+import { log } from '../utils.js';
+import { createLogger } from '../logger.js';
+
+const authLog = createLogger('auth');
+
+// Auth configuration from environment
+const AUTH_ENABLED = process.env.UPLINK_AUTH_ENABLED === 'true';
+const AUTH_TOKEN = process.env.UPLINK_AUTH_TOKEN || '';
+
+// Minimum token length for security (prevent weak tokens)
+const MIN_TOKEN_LENGTH = 32;
+
+// Validate configuration on startup
+if (AUTH_ENABLED) {
+  if (!AUTH_TOKEN) {
+    authLog.error('⚠️  UPLINK_AUTH_ENABLED=true but UPLINK_AUTH_TOKEN is not set!');
+    authLog.error('⚠️  Authentication will fail for all requests.');
+    authLog.error('⚠️  Set UPLINK_AUTH_TOKEN to a long random string (min 32 chars).');
+  } else if (AUTH_TOKEN.length < MIN_TOKEN_LENGTH) {
+    authLog.warn(`⚠️  UPLINK_AUTH_TOKEN is only ${AUTH_TOKEN.length} chars (min recommended: ${MIN_TOKEN_LENGTH})`);
+    authLog.warn('⚠️  Consider using a longer, more secure token.');
+  } else {
+    authLog.info('✅ Uplink authentication enabled');
+    authLog.info(`Token length: ${AUTH_TOKEN.length} characters`);
+  }
+}
+
+/**
+ * Extract Bearer token from Authorization header
+ * @param {Request} req - Express request object
+ * @returns {string|null} - Extracted token or null if not found
+ */
+function extractBearerToken(req) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader) return null;
+  
+  if (authHeader.startsWith('Bearer ')) {
+    return authHeader.slice(7); // Remove 'Bearer ' prefix
+  }
+  
+  return null;
+}
+
+/**
+ * Verify if provided token matches configured token
+ * Uses constant-time comparison to prevent timing attacks
+ * @param {string} providedToken - Token from request
+ * @returns {boolean} - True if token is valid
+ */
+function verifyToken(providedToken) {
+  if (!providedToken || !AUTH_TOKEN) return false;
+  const providedBuf = Buffer.from(String(providedToken));
+  const expectedBuf = Buffer.from(AUTH_TOKEN);
+  if (providedBuf.length !== expectedBuf.length) return false;
+  return crypto.timingSafeEqual(providedBuf, expectedBuf);
+}
+
+/**
+ * Authentication middleware for HTTP routes
+ * 
+ * When auth is disabled: passes through all requests
+ * When auth is enabled: requires valid Bearer token
+ * 
+ * @param {Request} req - Express request
+ * @param {Response} res - Express response
+ * @param {Function} next - Next middleware
+ */
+export function requireAuth(req, res, next) {
+  // Auth disabled - passthrough
+  if (!AUTH_ENABLED) {
+    return next();
+  }
+
+  // Extract and verify token
+  const token = extractBearerToken(req);
+  
+  if (!token) {
+    log('warn', `[Auth] Unauthorized request to ${req.path} - no token provided`);
+    return res.status(401).json({
+      error: true,
+      message: 'Authentication required. Include Authorization: Bearer <token> header.',
+      code: 'UNAUTHORIZED'
+    });
+  }
+
+  if (!verifyToken(token)) {
+    log('warn', `[Auth] Invalid token for ${req.path}`);
+    return res.status(401).json({
+      error: true,
+      message: 'Invalid authentication token.',
+      code: 'INVALID_TOKEN'
+    });
+  }
+
+  // Token valid - proceed
+  next();
+}
+
+/**
+ * Verify WebSocket token (from query param or upgrade request)
+ * 
+ * @param {string|null} token - Token from query param or Authorization header
+ * @returns {boolean} - True if auth is disabled OR token is valid
+ */
+export function verifyWebSocketToken(token) {
+  // Auth disabled - allow all connections
+  if (!AUTH_ENABLED) {
+    return true;
+  }
+
+  // Auth enabled - require valid token
+  return verifyToken(token);
+}
+
+/**
+ * Validate set_user command when auth is enabled
+ * Prevents session impersonation by ensuring user can only set their own identity
+ * 
+ * @param {string} requestedUser - User identity being set
+ * @param {string|null} authenticatedUser - User from auth token (if auth enabled)
+ * @returns {boolean} - True if allowed
+ */
+export function validateSetUser(requestedUser, authenticatedUser = null) {
+  // Auth disabled - allow any user (backward compatible)
+  if (!AUTH_ENABLED) {
+    return true;
+  }
+
+  // Auth enabled - must match authenticated identity
+  // For now, we derive authenticatedUser from session context
+  // In future, could embed user identity in JWT token
+  
+  // TODO: When JWT tokens are implemented, decode token to get user identity
+  // For now, we simply require that auth is present (token was validated)
+  // and trust the user identity from session context
+  
+  // This is a placeholder - full implementation would:
+  // 1. Use JWT tokens with embedded user claims
+  // 2. Validate requestedUser matches token.sub or token.user
+  
+  return true; // Allow for now, will enhance with JWT in future
+}
+
+/**
+ * Check if authentication is enabled
+ * Useful for conditional logic in other modules
+ */
+export function isAuthEnabled() {
+  return AUTH_ENABLED;
+}
+
+/**
+ * Get redacted auth status for logging/debugging
+ */
+export function getAuthStatus() {
+  return {
+    enabled: AUTH_ENABLED,
+    tokenConfigured: AUTH_TOKEN.length > 0,
+    tokenLength: AUTH_TOKEN.length,
+    minTokenLength: MIN_TOKEN_LENGTH,
+    secure: AUTH_ENABLED && AUTH_TOKEN.length >= MIN_TOKEN_LENGTH
+  };
+}