4runr-os 2.10.85 → 2.10.86

package/apps/os-server/src/middleware/correlationId.ts

@@ -0,0 +1,56 @@
+/**
+ * Correlation ID middleware
+ * Adds a unique correlation ID to each request for tracing.
+ * Operator guide: docs/GATEWAY-CORRELATION-M5.md
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { randomUUID } from 'crypto';
+
+/** Max length for inbound `X-Correlation-ID` (avoids log/buffer/header bloat). */
+export const MAX_CORRELATION_ID_LENGTH = 128;
+
+/**
+ * Resolve correlation ID from inbound header or generate a new UUID.
+ */
+export function resolveCorrelationId(
+  header: string | string[] | undefined
+): string {
+  const raw = header;
+  const headerId = Array.isArray(raw) ? raw[0] : raw;
+  const trimmed = typeof headerId === 'string' ? headerId.trim() : '';
+  if (
+    trimmed.length > 0 &&
+    trimmed.length <= MAX_CORRELATION_ID_LENGTH
+  ) {
+    return trimmed;
+  }
+  return randomUUID();
+}
+
+/**
+ * Add correlation ID to request
+ * Extracts from X-Correlation-ID header or generates new one
+ */
+export async function addCorrelationId(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const correlationId = resolveCorrelationId(
+    request.headers['x-correlation-id']
+  );
+  
+  // Attach to request for use in handlers
+  (request as any).correlationId = correlationId;
+  
+  // Add to response headers for client tracing
+  reply.header('X-Correlation-ID', correlationId);
+}
+
+/**
+ * Get correlation ID from request
+ */
+export function getCorrelationId(request: FastifyRequest): string | undefined {
+  return (request as any).correlationId;
+}
+

package/apps/os-server/src/middleware/ddos-protection.ts

@@ -0,0 +1,318 @@
+/**
+ * DDoS Protection Middleware
+ * Enhanced rate limiting with IP blocking, fingerprinting, and distributed limits.
+ * Operator guide: docs/GATEWAY-DDOS-RATE-M4.md (internet-facing deploys, probe exemptions, strict vs global layers).
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { createLogger } from '@4runr/shared';
+import crypto from 'crypto';
+
+const logger = createLogger('Gateway:DDOS:Protection');
+
+interface RequestFingerprint {
+  ip: string;
+  userAgent: string;
+  fingerprint: string;
+  count: number;
+  firstSeen: number;
+  lastSeen: number;
+  blocked: boolean;
+  blockedUntil?: number;
+}
+
+interface IPBlock {
+  ip: string;
+  blockedAt: number;
+  blockedUntil: number;
+  reason: string;
+  requestCount: number;
+}
+
+// In-memory stores (in production, use Redis)
+const requestFingerprints = new Map<string, RequestFingerprint>();
+const ipBlocks = new Map<string, IPBlock>();
+const rateLimitBuckets = new Map<string, { count: number; resetAt: number }>();
+
+// Configuration
+const CONFIG = {
+  // Rate limits
+  MAX_REQUESTS_PER_MINUTE: 100,
+  MAX_REQUESTS_PER_SECOND: 20,
+  MAX_CONCURRENT_REQUESTS: 50,
+
+  // Blocking thresholds
+  BLOCK_THRESHOLD_REQUESTS: 200, // Block after 200 requests in short time
+  BLOCK_DURATION_MS: 15 * 60 * 1000, // 15 minutes
+  BLOCK_THRESHOLD_FAILURES: 10, // Block after 10 failed auth attempts
+
+  // Cleanup
+  CLEANUP_INTERVAL_MS: 60 * 1000, // 1 minute
+  FINGERPRINT_TTL_MS: 60 * 60 * 1000, // 1 hour
+};
+
+/**
+ * Generate request fingerprint
+ */
+function generateFingerprint(request: FastifyRequest): string {
+  const ip = getClientIP(request);
+  const userAgent = request.headers['user-agent'] || 'unknown';
+  const accept = request.headers['accept'] || '';
+  const acceptLanguage = request.headers['accept-language'] || '';
+  
+  const data = `${ip}:${userAgent}:${accept}:${acceptLanguage}`;
+  return crypto.createHash('sha256').update(data).digest('hex').substring(0, 16);
+}
+
+function isLoopbackIP(ip: string): boolean {
+  const n = ip.toLowerCase();
+  return (
+    n === '127.0.0.1' ||
+    n === '::1' ||
+    n === '::ffff:127.0.0.1' ||
+    n === 'localhost'
+  );
+}
+
+/** Local dev + smoke tests: loopback is not DDoS-blocked unless explicitly disabled. */
+function loopbackExemptFromDdos(): boolean {
+  if (process.env['DDOS_LOOPBACK_EXEMPT'] === 'false') return false;
+  return process.env['NODE_ENV'] !== 'production';
+}
+
+/**
+ * Get client IP address
+ */
+function getClientIP(request: FastifyRequest): string {
+  const forwarded = request.headers['x-forwarded-for'];
+  if (forwarded) {
+    const forwardedStr = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    if (forwardedStr) {
+      const ips = forwardedStr.split(',');
+      return ips[0]?.trim() || 'unknown';
+    }
+  }
+  const realIp = request.headers['x-real-ip'];
+  const realIpStr = Array.isArray(realIp) ? realIp[0] : realIp;
+  return request.ip || realIpStr || 'unknown';
+}
+
+/**
+ * Check if IP is blocked
+ */
+function isIPBlocked(ip: string): boolean {
+  const block = ipBlocks.get(ip);
+  if (!block) return false;
+
+  if (Date.now() > block.blockedUntil) {
+    // Block expired
+    ipBlocks.delete(ip);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Block an IP address
+ */
+function blockIP(ip: string, reason: string, requestCount: number = 0): void {
+  const blockedUntil = Date.now() + CONFIG.BLOCK_DURATION_MS;
+  ipBlocks.set(ip, {
+    ip,
+    blockedAt: Date.now(),
+    blockedUntil,
+    reason,
+    requestCount
+  });
+
+  logger.warn('IP blocked', { ip, reason, blockedUntil: new Date(blockedUntil) });
+}
+
+/**
+ * Check rate limits
+ */
+function checkRateLimit(fingerprint: string, ip: string): { allowed: boolean; reason?: string } {
+  const now = Date.now();
+  const minuteKey = `minute:${fingerprint}:${Math.floor(now / 60000)}`;
+  const secondKey = `second:${fingerprint}:${Math.floor(now / 1000)}`;
+
+  // Check per-minute limit
+  let minuteBucket = rateLimitBuckets.get(minuteKey);
+  if (!minuteBucket || now >= minuteBucket.resetAt) {
+    minuteBucket = { count: 0, resetAt: now + 60000 };
+    rateLimitBuckets.set(minuteKey, minuteBucket);
+  }
+  minuteBucket.count++;
+
+  if (minuteBucket.count > CONFIG.MAX_REQUESTS_PER_MINUTE) {
+    blockIP(ip, 'rate_limit_exceeded', minuteBucket.count);
+    return { allowed: false, reason: 'Rate limit exceeded (per minute)' };
+  }
+
+  // Check per-second limit
+  let secondBucket = rateLimitBuckets.get(secondKey);
+  if (!secondBucket || now >= secondBucket.resetAt) {
+    secondBucket = { count: 0, resetAt: now + 1000 };
+    rateLimitBuckets.set(secondKey, secondBucket);
+  }
+  secondBucket.count++;
+
+  if (secondBucket.count > CONFIG.MAX_REQUESTS_PER_SECOND) {
+    blockIP(ip, 'rate_limit_exceeded', secondBucket.count);
+    return { allowed: false, reason: 'Rate limit exceeded (per second)' };
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Track request fingerprint
+ */
+function trackFingerprint(fingerprint: string, ip: string, userAgent: string): void {
+  const now = Date.now();
+  const existing = requestFingerprints.get(fingerprint);
+
+  if (existing) {
+    existing.count++;
+    existing.lastSeen = now;
+
+    // Check if suspicious (too many requests)
+    if (existing.count > CONFIG.BLOCK_THRESHOLD_REQUESTS) {
+      if (!existing.blocked) {
+        existing.blocked = true;
+        existing.blockedUntil = now + CONFIG.BLOCK_DURATION_MS;
+        blockIP(ip, 'suspicious_activity', existing.count);
+      }
+    }
+  } else {
+    requestFingerprints.set(fingerprint, {
+      ip,
+      userAgent,
+      fingerprint,
+      count: 1,
+      firstSeen: now,
+      lastSeen: now,
+      blocked: false
+    });
+  }
+}
+
+/**
+ * Cleanup old entries
+ */
+function cleanup(): void {
+  const now = Date.now();
+
+  // Cleanup fingerprints
+  for (const [key, fp] of requestFingerprints.entries()) {
+    if (now - fp.lastSeen > CONFIG.FINGERPRINT_TTL_MS) {
+      requestFingerprints.delete(key);
+    }
+  }
+
+  // Cleanup expired IP blocks
+  for (const [ip, block] of ipBlocks.entries()) {
+    if (now > block.blockedUntil) {
+      ipBlocks.delete(ip);
+    }
+  }
+
+  // Cleanup old rate limit buckets
+  for (const [key, bucket] of rateLimitBuckets.entries()) {
+    if (now >= bucket.resetAt) {
+      rateLimitBuckets.delete(key);
+    }
+  }
+}
+
+// Start cleanup interval
+setInterval(cleanup, CONFIG.CLEANUP_INTERVAL_MS);
+
+/** Lightweight probes used by CLI/TUI, load balancers, and Prometheus — must not trip per-second limits. */
+function isProbeExemptPath(method: string, rawUrl: string): boolean {
+  if (method !== 'GET') return false;
+  const path = (rawUrl.split('?')[0] || '').toLowerCase();
+  return path === '/health' || path === '/ready' || path === '/metrics';
+}
+
+/**
+ * DDoS Protection Middleware
+ */
+export async function ddosProtection(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  if (isProbeExemptPath(request.method, request.url)) {
+    return;
+  }
+
+  const ip = getClientIP(request);
+  if (loopbackExemptFromDdos() && isLoopbackIP(ip)) {
+    return;
+  }
+
+  const userAgent = request.headers['user-agent'] || 'unknown';
+
+  // Check if IP is blocked
+  if (isIPBlocked(ip)) {
+    const block = ipBlocks.get(ip)!;
+    const retryAfter = Math.ceil((block.blockedUntil - Date.now()) / 1000);
+    
+    reply.status(429).send({
+      error: 'ip_blocked',
+      message: 'IP address is temporarily blocked',
+      reason: block.reason,
+      retry_after: retryAfter,
+      blocked_until: new Date(block.blockedUntil).toISOString()
+    });
+    return;
+  }
+
+  // Generate fingerprint
+  const fingerprint = generateFingerprint(request);
+
+  // Check rate limits
+  const rateLimitCheck = checkRateLimit(fingerprint, ip);
+  if (!rateLimitCheck.allowed) {
+    reply.status(429).send({
+      error: 'rate_limited',
+      message: rateLimitCheck.reason || 'Too many requests'
+    });
+    return;
+  }
+
+  // Track fingerprint
+  trackFingerprint(fingerprint, ip, userAgent);
+
+  // Check if fingerprint is blocked
+  const fp = requestFingerprints.get(fingerprint);
+  if (fp?.blocked && fp.blockedUntil && Date.now() < fp.blockedUntil) {
+    reply.status(429).send({
+      error: 'suspicious_activity',
+      message: 'Request pattern flagged as suspicious'
+    });
+    return;
+  }
+
+  // Attach fingerprint to request for logging
+  (request as any).ddosFingerprint = fingerprint;
+  (request as any).clientIP = ip;
+}
+
+/**
+ * Get DDoS protection stats (for monitoring)
+ */
+export function getDDoSStats() {
+  return {
+    blockedIPs: ipBlocks.size,
+    trackedFingerprints: requestFingerprints.size,
+    activeRateLimitBuckets: rateLimitBuckets.size,
+    blockedIPsList: Array.from(ipBlocks.values()).map(b => ({
+      ip: b.ip,
+      reason: b.reason,
+      blockedUntil: new Date(b.blockedUntil).toISOString()
+    }))
+  };
+}
+

package/apps/os-server/src/middleware/log-capture.ts

@@ -0,0 +1,92 @@
+/**
+ * Log capture middleware for monitoring log buffer (Portal `/api/monitoring/logs`).
+ * Intercepts logger calls and feeds them to the monitoring ring buffer.
+ *
+ * Skips `memoryLogger` (no `getCorrelationId`; uses its own `getLogs()` buffer).
+ */
+
+import { addMonitoringLog } from '../routes/monitoring.js';
+
+const MONITORING_WRAPPED = '__monitoringWrapped';
+
+/**
+ * Wrap a logger to capture log entries for monitoring.
+ * Idempotent: already-wrapped loggers are returned unchanged.
+ */
+export function wrapLoggerForMonitoring(logger: any): any {
+  if (!logger || typeof logger.info !== 'function') {
+    return logger;
+  }
+  if (logger[MONITORING_WRAPPED]) {
+    return logger;
+  }
+  // memoryLogger: separate in-memory buffer for no-persistence mode — do not duplicate
+  if (typeof logger.getLogs === 'function') {
+    return logger;
+  }
+
+  const originalInfo = logger.info.bind(logger);
+  const originalWarn = logger.warn.bind(logger);
+  const originalError = logger.error.bind(logger);
+  const originalDebug = logger.debug?.bind(logger);
+
+  const resolveCorrelationId = (
+    data?: Record<string, unknown>
+  ): string | undefined => {
+    if (data && typeof data['correlationId'] === 'string') {
+      return data['correlationId'];
+    }
+    if (typeof logger.getCorrelationId === 'function') {
+      return logger.getCorrelationId();
+    }
+    return undefined;
+  };
+
+  const logContext =
+    typeof logger.getComponent === 'function'
+      ? logger.getComponent()
+      : typeof logger.prefix === 'string'
+        ? logger.prefix
+        : 'Gateway';
+
+  const capture = (
+    level: 'info' | 'warn' | 'error' | 'debug',
+    message: string,
+    data?: Record<string, unknown>
+  ) => {
+    const correlationId = resolveCorrelationId(data);
+    addMonitoringLog({
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      context: logContext,
+      ...(correlationId && { correlationId }),
+      ...(data && { data }),
+    });
+  };
+
+  logger.info = (message: string, data?: Record<string, unknown>) => {
+    capture('info', message, data);
+    return originalInfo(message, data);
+  };
+
+  logger.warn = (message: string, data?: Record<string, unknown>) => {
+    capture('warn', message, data);
+    return originalWarn(message, data);
+  };
+
+  logger.error = (message: string, data?: Record<string, unknown>) => {
+    capture('error', message, data);
+    return originalError(message, data);
+  };
+
+  if (originalDebug) {
+    logger.debug = (message: string, data?: Record<string, unknown>) => {
+      capture('debug', message, data);
+      return originalDebug(message, data);
+    };
+  }
+
+  logger[MONITORING_WRAPPED] = true;
+  return logger;
+}

package/apps/os-server/src/middleware/security.ts

@@ -0,0 +1,222 @@
+/**
+ * Security middleware for Fastify
+ * Adds security headers, removes version information, and validates secrets.
+ * Operator guide: docs/GATEWAY-SECRETS-M3.md
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { env, createLogger } from '@4runr/shared';
+import { isMemoryMode } from '../config/persistence.js';
+import { signingSecretProductionError } from '../security/agent-token.js';
+
+const logger = createLogger('Gateway:Security');
+
+/** Must match `redis-credentials-store.ts` */
+const DEFAULT_DEV_ENCRYPTION_KEY = 'default-dev-key-change-in-production';
+
+const INSECURE_SECRET_SUBSTRINGS = [
+  'secret',
+  'change-me',
+  'change-in-production',
+  'test-secret',
+  'default-dev',
+  'jwt-secret',
+];
+
+export type SecretsValidationResult = {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+};
+
+function looksInsecure(value: string): boolean {
+  const lower = value.toLowerCase();
+  return INSECURE_SECRET_SUBSTRINGS.some((p) => lower.includes(p));
+}
+
+function validateKekBase64(): string | null {
+  const b64 = process.env['KEK_BASE64'];
+  if (!b64?.trim()) {
+    return 'KEK_BASE64 is required in production when using encrypted credentials (MFA, tool credentials, envelope crypto)';
+  }
+  try {
+    const buf = Buffer.from(b64, 'base64');
+    if (buf.length < 32) {
+      return 'KEK_BASE64 must decode to at least 32 bytes (use e.g. openssl rand -base64 32)';
+    }
+  } catch {
+    return 'KEK_BASE64 must be valid base64';
+  }
+  return null;
+}
+
+function validateSigningSecret(): string | null {
+  return signingSecretProductionError(process.env['SIGNING_SECRET']);
+}
+
+function validateEncryptionKey(): string | null {
+  const k = process.env['ENCRYPTION_KEY'] ?? env.ENCRYPTION_KEY;
+  if (!k || k.length < 32) {
+    return 'ENCRYPTION_KEY must be at least 32 characters in production (Redis AI provider credentials)';
+  }
+  if (k === DEFAULT_DEV_ENCRYPTION_KEY || looksInsecure(k)) {
+    return 'ENCRYPTION_KEY must not use the default dev value in production';
+  }
+  return null;
+}
+
+/**
+ * Set security headers on all responses
+ */
+export async function setSecurityHeaders(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  // Remove server version header (if present)
+  reply.removeHeader('X-Powered-By');
+  reply.removeHeader('Server');
+
+  // Content Security Policy
+  reply.header(
+    'Content-Security-Policy',
+    "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' ws: wss:; frame-ancestors 'none';"
+  );
+
+  // Strict Transport Security (HSTS) - only if HTTPS
+  if (request.protocol === 'https' || request.headers['x-forwarded-proto'] === 'https') {
+    reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+  }
+
+  // X-Content-Type-Options
+  reply.header('X-Content-Type-Options', 'nosniff');
+
+  // X-Frame-Options
+  reply.header('X-Frame-Options', 'DENY');
+
+  // X-XSS-Protection
+  reply.header('X-XSS-Protection', '1; mode=block');
+
+  // Referrer Policy
+  reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+  // Permissions Policy (formerly Feature-Policy)
+  reply.header(
+    'Permissions-Policy',
+    'geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), speaker=()'
+  );
+
+  // Cross-Origin Embedder Policy
+  reply.header('Cross-Origin-Embedder-Policy', 'require-corp');
+
+  // Cross-Origin Opener Policy
+  reply.header('Cross-Origin-Opener-Policy', 'same-origin');
+
+  // Cross-Origin Resource Policy
+  reply.header('Cross-Origin-Resource-Policy', 'same-origin');
+
+  // Don't expose internal headers
+  reply.header('X-Gateway', '4Runr'); // Generic name, no version
+}
+
+/**
+ * Validate that required secrets are present and not default values.
+ * Aligns with runtime checks in `redis-credentials-store`, `mfa-storage`, and `tool-proxy`.
+ */
+export function validateSecrets(): SecretsValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const isProduction = process.env['NODE_ENV'] === 'production';
+  const memoryMode = isMemoryMode();
+  const authMode = process.env['AUTH_MODE'] ?? env.AUTH_MODE;
+  const authEnabled =
+    process.env['AUTH_ENABLED'] === undefined
+      ? env.AUTH_ENABLED
+      : process.env['AUTH_ENABLED'] === 'true';
+  const databaseUrl = process.env['DATABASE_URL'] ?? env.DATABASE_URL;
+  const jwtSecret = process.env['JWT_SECRET'] ?? env.JWT_SECRET;
+
+  if (isProduction && !memoryMode && !databaseUrl) {
+    errors.push('DATABASE_URL is required in production (unless GATEWAY_PERSISTENCE=memory)');
+  }
+
+  if ((authMode === 'jwt' || authMode === 'mixed') && !jwtSecret) {
+    if (isProduction) {
+      errors.push('JWT_SECRET is required when AUTH_MODE is jwt or mixed');
+    } else {
+      warnings.push('JWT_SECRET is not set; JWT auth will fail when AUTH_ENABLED=true');
+    }
+  }
+
+  if (jwtSecret) {
+    if (jwtSecret.length < 32) {
+      errors.push('JWT_SECRET is too short (minimum 32 characters)');
+    } else if (looksInsecure(jwtSecret)) {
+      errors.push('JWT_SECRET appears to use an insecure default value');
+    }
+  }
+
+  if (isProduction) {
+    const signingErr = validateSigningSecret();
+    if (signingErr) errors.push(signingErr);
+
+    if (!memoryMode) {
+      const encErr = validateEncryptionKey();
+      if (encErr) errors.push(encErr);
+
+      const kekErr = validateKekBase64();
+      if (kekErr) errors.push(kekErr);
+    } else {
+      warnings.push(
+        'GATEWAY_PERSISTENCE=memory: ENCRYPTION_KEY and KEK_BASE64 are not required at startup; MFA/tool credential encryption still requires KEK_BASE64 if those routes are used'
+      );
+    }
+
+    if (authEnabled && (authMode === 'api_key' || authMode === 'mixed')) {
+      if (!process.env['API_KEY'] && !process.env['API_KEYS']) {
+        warnings.push(
+          'No API_KEY/API_KEYS in environment; production api_key auth expects keys in the database or env'
+        );
+      }
+    }
+  } else {
+    if (!process.env['SIGNING_SECRET'] || process.env['SIGNING_SECRET'].length < 32) {
+      warnings.push('SIGNING_SECRET is unset or short; dev agent-token signing uses a default secret');
+    }
+    if (!memoryMode && !process.env['ENCRYPTION_KEY'] && !env.ENCRYPTION_KEY) {
+      warnings.push('ENCRYPTION_KEY is unset; Redis credential store will use a dev default outside production');
+    }
+    if (!process.env['KEK_BASE64']) {
+      warnings.push('KEK_BASE64 is unset; MFA and tool credentials store plaintext in non-production');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Log security validation on startup; refuse to start in production when invalid.
+ */
+export function logSecurityValidation(): void {
+  const validation = validateSecrets();
+
+  if (validation.warnings.length > 0) {
+    logger.warn('Security validation warnings', { warnings: validation.warnings });
+  }
+
+  if (!validation.valid) {
+    logger.error('Security validation failed', { errors: validation.errors });
+    if (process.env['NODE_ENV'] === 'production') {
+      throw new Error(
+        `Gateway refused to start: invalid secrets configuration — ${validation.errors.join('; ')}`
+      );
+    }
+    return;
+  }
+
+  logger.info('Security validation passed');
+}
+