@mooncompany/uplink-chat 0.5.0

package/utils/html-escape.js

@@ -0,0 +1,84 @@
+/**
+ * HTML Escape Utility (Server-side)
+ * Single source of truth for HTML escaping on the server
+ */
+
+// HTML entity map for escaping
+const HTML_ENTITIES = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+  '/': '&#x2F;',
+  '`': '&#x60;',
+  '=': '&#x3D;'
+};
+
+/**
+ * Escape HTML special characters to prevent XSS
+ * 
+ * @param {string} str - The string to escape
+ * @returns {string} - Escaped string safe for HTML insertion
+ */
+export function escapeHtml(str) {
+  if (typeof str !== 'string') {
+    return '';
+  }
+  return str.replace(/[&<>"'`=/]/g, char => HTML_ENTITIES[char]);
+}
+
+/**
+ * Escape HTML and convert newlines to <br> tags
+ * 
+ * @param {string} str - The string to escape
+ * @returns {string} - Escaped string with line breaks
+ */
+export function escapeHtmlWithBreaks(str) {
+  return escapeHtml(str).replace(/\n/g, '<br>');
+}
+
+/**
+ * Escape a string for safe insertion into JavaScript
+ * Use when embedding strings in inline <script> tags
+ * 
+ * @param {string} str - The string to escape
+ * @returns {string} - Escaped string safe for JS context
+ */
+export function escapeForJS(str) {
+  if (typeof str !== 'string') {
+    return '';
+  }
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/<\/script>/gi, '<\\/script>');
+}
+
+/**
+ * Escape a string for safe use in HTML attributes
+ * 
+ * @param {string} str - The string to escape
+ * @returns {string} - Escaped string safe for attribute values
+ */
+export function escapeAttribute(str) {
+  if (typeof str !== 'string') {
+    return '';
+  }
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export default {
+  escapeHtml,
+  escapeHtmlWithBreaks,
+  escapeForJS,
+  escapeAttribute
+};

package/utils/id-sanitize.js

@@ -0,0 +1,94 @@
+/**
+ * ID Sanitization Utility
+ * Validates and sanitizes identifiers to prevent injection attacks
+ */
+
+/**
+ * Sanitize an ID string (alphanumeric + hyphen/underscore only)
+ * @param {string} id - Raw ID
+ * @param {number} maxLength - Maximum allowed length (default 64)
+ * @returns {string} - Sanitized ID
+ */
+export function sanitizeId(id, maxLength = 64) {
+  if (typeof id !== 'string') return '';
+  return id.replace(/[^a-zA-Z0-9_-]/g, '').substring(0, maxLength);
+}
+
+/**
+ * Sanitize a satellite ID
+ * @param {string} id - Raw satellite ID
+ * @returns {string} - Sanitized satellite ID (default 'main' if invalid)
+ */
+export function sanitizeSatelliteId(id) {
+  const sanitized = sanitizeId(id, 32);
+  return sanitized || 'main';
+}
+
+/**
+ * Sanitize a share ID (alphanumeric only, max 12 chars)
+ * @param {string} id - Raw share ID
+ * @returns {{ valid: boolean, sanitized: string, error: string|null }}
+ */
+export function sanitizeShareId(id) {
+  if (typeof id !== 'string' || !id) {
+    return { valid: false, sanitized: '', error: 'shareId must be a non-empty string' };
+  }
+  const sanitized = id.replace(/[^a-zA-Z0-9]/g, '').substring(0, 12);
+  if (!sanitized) {
+    return { valid: false, sanitized: '', error: 'shareId contains no valid characters' };
+  }
+  return { valid: true, sanitized, error: null };
+}
+
+/**
+ * Sanitize a session user string
+ * @param {string} user - Raw session user
+ * @returns {string} - Sanitized session user
+ */
+export function sanitizeSessionUser(user) {
+  if (typeof user !== 'string') return '';
+  // Allow alphanumeric, hyphen, underscore, colon (for satellite suffix)
+  return user.replace(/[^a-zA-Z0-9_:-]/g, '').substring(0, 64);
+}
+
+/**
+ * Validate that an ID matches expected format
+ * @param {string} id - ID to validate
+ * @param {RegExp} pattern - Pattern to match
+ * @returns {boolean} - True if valid
+ */
+export function isValidId(id, pattern = /^[a-zA-Z0-9_-]+$/) {
+  return typeof id === 'string' && pattern.test(id);
+}
+
+/**
+ * Sanitize a sync ID (alphanumeric + hyphen, max 64 chars)
+ * @param {string} id - Raw sync ID
+ * @returns {{ valid: boolean, sanitized: string, error: string|null }}
+ */
+export function sanitizeSyncId(id) {
+  if (typeof id !== 'string' || !id) {
+    return { valid: false, sanitized: '', error: 'syncId must be a non-empty string' };
+  }
+  const sanitized = id.replace(/[^a-zA-Z0-9-]/g, '').substring(0, 64);
+  if (!sanitized) {
+    return { valid: false, sanitized: '', error: 'syncId contains no valid characters' };
+  }
+  return { valid: true, sanitized, error: null };
+}
+
+/**
+ * Parse a numeric parameter with bounds checking
+ * @param {any} value - Value to parse
+ * @param {number} defaultVal - Default value if invalid
+ * @param {number} min - Minimum allowed value
+ * @param {number} max - Maximum allowed value
+ * @returns {number} - Parsed and bounded number
+ */
+export function parseNumericParam(value, defaultVal = 0, min = 0, max = Infinity) {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) return defaultVal;
+  return Math.min(Math.max(parsed, min), max);
+}
+
+export default { sanitizeId, sanitizeSatelliteId, sanitizeShareId, sanitizeSessionUser, isValidId, sanitizeSyncId, parseNumericParam };

package/utils/response.js

@@ -0,0 +1,130 @@
+/**
+ * Standardized Response Utilities
+ * Ensures consistent API responses
+ */
+
+import { sanitizeErrorMessage, createErrorResponse, AppError } from './errors.js';
+
+/**
+ * Send a success response
+ * @param {Response} res - Express response
+ * @param {Object} data - Response data
+ * @param {number} statusCode - HTTP status code (default 200)
+ */
+export function sendSuccess(res, data = {}, statusCode = 200) {
+  res.status(statusCode).json({
+    ok: true,
+    ...data
+  });
+}
+
+/**
+ * Send an error response (sanitized)
+ * @param {Response} res - Express response
+ * @param {Error|string} error - Error or message
+ * @param {number} statusCode - HTTP status code (default 500)
+ */
+export function sendError(res, error, statusCode = 500) {
+  // If it's an AppError, use its status code
+  if (error instanceof AppError) {
+    statusCode = error.statusCode;
+  }
+  
+  const message = error instanceof Error 
+    ? sanitizeErrorMessage(error)
+    : String(error);
+  
+  res.status(statusCode).json({
+    error: true,
+    message,
+    ...(error instanceof AppError && { code: error.code })
+  });
+}
+
+/**
+ * Send a validation error (400)
+ * @param {Response} res - Express response
+ * @param {string} message - Error message
+ */
+export function sendValidationError(res, message = 'Invalid input') {
+  sendError(res, message, 400);
+}
+
+/**
+ * Send an authentication error (401)
+ * @param {Response} res - Express response
+ * @param {string} message - Error message
+ */
+export function sendAuthError(res, message = 'Authentication required') {
+  sendError(res, message, 401);
+}
+
+/**
+ * Send a forbidden error (403)
+ * @param {Response} res - Express response
+ * @param {string} message - Error message
+ */
+export function sendForbiddenError(res, message = 'Access denied') {
+  sendError(res, message, 403);
+}
+
+/**
+ * Send a not found error (404)
+ * @param {Response} res - Express response
+ * @param {string} message - Error message
+ */
+export function sendNotFoundError(res, message = 'Resource not found') {
+  sendError(res, message, 404);
+}
+
+/**
+ * Send a rate limit error (429)
+ * @param {Response} res - Express response
+ * @param {string} message - Error message
+ */
+export function sendRateLimitError(res, message = 'Too many requests') {
+  sendError(res, message, 429);
+}
+
+/**
+ * Send a server error (500) - always sanitized
+ * @param {Response} res - Express response
+ * @param {Error} error - Original error (will be sanitized)
+ */
+export function sendServerError(res, error) {
+  sendError(res, error, 500);
+}
+
+/**
+ * Express error handler middleware
+ */
+export function errorHandler(err, req, res, next) {
+  // Log the actual error for debugging
+  console.error('[Error]', err);
+  
+  // Send sanitized response
+  const statusCode = err instanceof AppError ? err.statusCode : 500;
+  sendError(res, err, statusCode);
+}
+
+/**
+ * Wrap async route handlers to catch promise rejections
+ */
+export function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+export default {
+  sendSuccess,
+  sendError,
+  sendValidationError,
+  sendAuthError,
+  sendForbiddenError,
+  sendNotFoundError,
+  sendRateLimitError,
+  sendServerError,
+  errorHandler,
+  asyncHandler
+};

package/utils/with-retry.js

@@ -0,0 +1,105 @@
+/**
+ * Retry Helper Utility (Server-side)
+ * Unified retry logic with exponential backoff
+ * 
+ * Previously duplicated in:
+ * - server/utils.js (simple signature)
+ * - server/chat.js (options object signature)
+ * 
+ * This version supports both calling conventions for backward compatibility.
+ */
+
+/**
+ * Simple logger fallback
+ */
+function logWarn(...args) {
+  console.warn('[withRetry]', ...args);
+}
+
+/**
+ * Execute a function with automatic retry on failure
+ * Uses exponential backoff between retries
+ * 
+ * Supports two calling conventions:
+ * 1. withRetry(fn, maxRetries, delay) - simple
+ * 2. withRetry(fn, { maxRetries, baseDelayMs, maxDelayMs }) - options object
+ * 
+ * @param {Function} fn - The async function to retry
+ * @param {number|Object} optionsOrMaxRetries - Options object or max retries number
+ * @param {number} delayArg - Base delay (only used if second arg is a number)
+ * @returns {Promise<any>} - The result of the function
+ * @throws {Error} - The last error if all retries fail
+ */
+export async function withRetry(fn, optionsOrMaxRetries = 3, delayArg = 1000) {
+  // Normalize arguments - support both calling conventions
+  let maxRetries, baseDelayMs, maxDelayMs;
+  
+  if (typeof optionsOrMaxRetries === 'object') {
+    // Options object style: withRetry(fn, { maxRetries, baseDelayMs, maxDelayMs })
+    maxRetries = optionsOrMaxRetries.maxRetries ?? 3;
+    baseDelayMs = optionsOrMaxRetries.baseDelayMs ?? 1000;
+    maxDelayMs = optionsOrMaxRetries.maxDelayMs ?? 10000;
+  } else {
+    // Simple style: withRetry(fn, maxRetries, delay)
+    maxRetries = optionsOrMaxRetries;
+    baseDelayMs = delayArg;
+    maxDelayMs = delayArg * Math.pow(2, maxRetries); // Calculate reasonable max
+  }
+  
+  let lastError;
+  
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      
+      if (attempt < maxRetries - 1) {
+        // Calculate delay with exponential backoff, capped at maxDelayMs
+        const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+        
+        logWarn(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms: ${err.message}`);
+        
+        await sleep(delay);
+      }
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Sleep for a specified duration
+ * 
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Create a configured retry function with preset options
+ * Useful when you want consistent retry behavior across multiple calls
+ * 
+ * @param {Object} options - Default retry options
+ * @returns {Function} - Configured retry function
+ */
+export function createRetrier(options = {}) {
+  const defaults = {
+    maxRetries: options.maxRetries ?? 3,
+    baseDelayMs: options.baseDelayMs ?? 1000,
+    maxDelayMs: options.maxDelayMs ?? 10000,
+    ...options
+  };
+  
+  return (fn, overrides = {}) => {
+    return withRetry(fn, { ...defaults, ...overrides });
+  };
+}
+
+export default {
+  withRetry,
+  sleep,
+  createRetrier
+};