secure-api-guard 0.0.0-stage → 1.0.0

package/src/middleware/rateLimiter.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const rateLimit = require('express-rate-limit');
+const defaults = require('../config/defaults');
+const { validateRateLimiterConfig } = require('../config/validateConfig');
+const { MemoryStore } = require('../stores/memoryStore');
+const { RedisStore } = require('../stores/redisStore');
+const { RateLimitError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Normalizes an IP address to avoid IPv4-mapped IPv6 duplicates.
+ *
+ * @param {string} ip
+ * @returns {string}
+ */
+function normalizeIp(ip) {
+  if (!ip) return '127.0.0.1';
+  if (ip.startsWith('::ffff:')) {
+    return ip.substring(7);
+  }
+  return ip;
+}
+
+/**
+ * Default key generator based on client IP.
+ *
+ * @param {import('express').Request} req
+ * @returns {string}
+ */
+function defaultKeyGenerator(req) {
+  const rawIp = req.ip || (req.socket && req.socket.remoteAddress) || '127.0.0.1';
+  return normalizeIp(rawIp);
+}
+
+/**
+ * Creates a rate limiter middleware for Express.
+ *
+ * @param {Object} [userOptions] - Rate limiter configuration options.
+ * @param {number} [userOptions.windowMs=900000] - Window duration in ms (15 mins default).
+ * @param {number} [userOptions.maxRequests=100] - Maximum requests allowed per window.
+ * @param {number} [userOptions.max] - Alias for maxRequests.
+ * @param {number} [userOptions.statusCode=429] - HTTP status code on limit exceed.
+ * @param {string} [userOptions.message] - Custom message on rate limit.
+ * @param {Function} [userOptions.keyGenerator] - Custom key generation function (req => string).
+ * @param {Function} [userOptions.skip] - Function to skip rate limiting (req => boolean).
+ * @param {any} [userOptions.store] - Store instance ('memory', 'redis', or custom Store).
+ * @param {any} [userOptions.redisClient] - Redis client if store is 'redis'.
+ * @param {Function} [userOptions.handler] - Custom error handler.
+ * @param {import('../utils/logger').SecurityLogger} [userOptions.logger] - Logger instance.
+ * @returns {import('express').RequestHandler}
+ */
+function createRateLimiter(userOptions = {}) {
+  validateRateLimiterConfig(userOptions);
+
+  const options = {
+    ...defaults.rateLimiter,
+    ...userOptions
+  };
+
+  const limit = options.maxRequests !== undefined ? options.maxRequests : (options.max !== undefined ? options.max : 100);
+  const logger = options.logger || defaultLogger;
+
+  // Resolve Store
+  let storeInstance;
+  if (options.store === 'redis' || (options.redisClient && !options.store)) {
+    if (!options.redisClient) {
+      throw new Error('RateLimiter: "redisClient" must be provided when store is "redis".');
+    }
+    storeInstance = new RedisStore({
+      client: options.redisClient,
+      windowMs: options.windowMs,
+      prefix: options.redisPrefix,
+      passOnConnectionError: options.passOnRedisError,
+      logger
+    });
+  } else if (typeof options.store === 'object' && options.store !== null) {
+    storeInstance = options.store;
+  } else {
+    // Default in-memory store
+    storeInstance = new MemoryStore({
+      windowMs: options.windowMs
+    });
+  }
+
+  const keyGenerator = options.keyGenerator || defaultKeyGenerator;
+
+  const limiterMiddleware = rateLimit({
+    windowMs: options.windowMs,
+    limit,
+    standardHeaders: options.standardHeaders,
+    legacyHeaders: options.legacyHeaders,
+    store: storeInstance,
+    keyGenerator: (req, res) => keyGenerator(req),
+    skip: options.skip || (() => false),
+    handler: (req, res, next, rateLimitOptions) => {
+      const clientKey = keyGenerator(req);
+      const retryAfterSeconds = Math.ceil(options.windowMs / 1000);
+
+      logger.warn('RATE_LIMIT_EXCEEDED', `Rate limit exceeded for client: ${clientKey}`, {
+        req,
+        ip: clientKey,
+        details: {
+          limit,
+          windowMs: options.windowMs,
+          retryAfter: retryAfterSeconds
+        }
+      });
+
+      const error = new RateLimitError(options.message, {
+        limit,
+        windowMs: options.windowMs,
+        retryAfter: retryAfterSeconds
+      });
+
+      sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+    }
+  });
+
+  return limiterMiddleware;
+}
+
+module.exports = {
+  rateLimiter: createRateLimiter,
+  createRateLimiter,
+  defaultKeyGenerator
+};
+

package/src/middleware/requestSize.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const bytes = require('bytes');
+const defaults = require('../config/defaults');
+const { validateRequestSizeConfig } = require('../config/validateConfig');
+const { PayloadTooLargeError, SecurityError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Parses and validates Content-Length header against HTTP smuggling / desync attacks.
+ *
+ * @param {import('express').Request} req
+ * @returns {{ length: number | null, error: string | null }}
+ */
+function parseContentLength(req) {
+  const rawHeader = req.headers && req.headers['content-length'];
+
+  if (rawHeader === undefined || rawHeader === null || rawHeader === '') {
+    return { length: null, error: null };
+  }
+
+  // Handle array of headers or comma-separated multiple values
+  const values = Array.isArray(rawHeader)
+    ? rawHeader
+    : String(rawHeader).split(',').map((v) => v.trim());
+
+  // Check for differing values in multiple headers (HTTP request smuggling risk)
+  const uniqueValues = new Set(values);
+  if (uniqueValues.size > 1) {
+    return {
+      length: null,
+      error: 'Conflicting Content-Length headers detected (possible HTTP smuggling).'
+    };
+  }
+
+  const lengthStr = values[0];
+  if (!/^\d+$/.test(lengthStr)) {
+    return {
+      length: null,
+      error: 'Malformed Content-Length header: must be a non-negative integer.'
+    };
+  }
+
+  const parsed = parseInt(lengthStr, 10);
+  return { length: parsed, error: null };
+}
+
+/**
+ * Creates request size limiting middleware.
+ *
+ * @param {Object} [userOptions]
+ * @param {string|number} [userOptions.maxSize='1mb'] - Max size in bytes or string ('1mb', '500kb').
+ * @param {number} [userOptions.statusCode=413] - HTTP status code on limit exceed.
+ * @param {string} [userOptions.message] - Custom error message.
+ * @param {Function} [userOptions.handler] - Custom response handler.
+ * @param {import('../utils/logger').SecurityLogger} [userOptions.logger] - Logger instance.
+ * @returns {import('express').RequestHandler}
+ */
+function createRequestSize(userOptions = {}) {
+  validateRequestSizeConfig(userOptions);
+
+  const options = {
+    ...defaults.requestSize,
+    ...userOptions
+  };
+
+  const maxBytes = typeof options.maxSize === 'number'
+    ? options.maxSize
+    : bytes.parse(options.maxSize) || 1048576; // default 1MB
+
+  const logger = options.logger || defaultLogger;
+
+  return function requestSizeMiddleware(req, res, next) {
+    // 1. Inspect Content-Length header
+    const { length: contentLength, error: headerError } = parseContentLength(req);
+
+    if (headerError) {
+      logger.warn('REQUEST_SIZE_HEADER_INVALID', headerError, { req });
+      const secError = new SecurityError(headerError, 400, 'BAD_REQUEST');
+      return sendSecurityResponse(req, res, secError, 400, options.handler);
+    }
+
+    if (contentLength !== null && contentLength > maxBytes) {
+      logger.warn('REQUEST_SIZE_EXCEEDED', `Content-Length (${contentLength}) exceeds limit (${maxBytes})`, {
+        req,
+        details: { contentLength, maxBytes }
+      });
+      res.setHeader('Connection', 'close');
+      const error = new PayloadTooLargeError(options.message, { contentLength, maxBytes });
+      return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+    }
+
+    // 2. Check if body is already parsed by upstream body parser
+    if (req.body && typeof req.body === 'object' && Object.keys(req.body).length > 0) {
+      try {
+        let estimatedSize = 0;
+        if (Buffer.isBuffer(req.body)) {
+          estimatedSize = req.body.length;
+        } else {
+          estimatedSize = Buffer.byteLength(JSON.stringify(req.body), 'utf8');
+        }
+
+        if (estimatedSize > maxBytes) {
+          logger.warn('REQUEST_SIZE_EXCEEDED', `Parsed body size (${estimatedSize}) exceeds limit (${maxBytes})`, {
+            req,
+            details: { estimatedSize, maxBytes }
+          });
+          const error = new PayloadTooLargeError(options.message, { estimatedSize, maxBytes });
+          return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+        }
+      } catch {
+        // Ignore serialization failure; proceed to streaming check
+      }
+    }
+
+    // 3. For unparsed streams or chunked transfer-encoding, monitor incoming chunks safely
+    let receivedBytes = 0;
+    let rejected = false;
+
+    const originalEmit = req.emit;
+    if (typeof originalEmit === 'function') {
+      req.emit = function (eventName, ...args) {
+        if (eventName === 'data' && !rejected) {
+          const chunk = args[0];
+          if (chunk) {
+            receivedBytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
+            if (receivedBytes > maxBytes) {
+              rejected = true;
+              if (typeof req.pause === 'function') {
+                req.pause();
+              }
+              logger.warn('REQUEST_SIZE_EXCEEDED', `Streamed body (${receivedBytes}) exceeded limit (${maxBytes})`, {
+                req,
+                details: { receivedBytes, maxBytes }
+              });
+
+              res.setHeader('Connection', 'close');
+              const error = new PayloadTooLargeError(options.message, { receivedBytes, maxBytes });
+              sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+              return false;
+            }
+          }
+        }
+        return originalEmit.apply(this, [eventName, ...args]);
+      };
+    }
+
+    return next();
+  };
+}
+
+module.exports = {
+  requestSize: createRequestSize,
+  createRequestSize,
+  parseContentLength
+};

package/src/middleware/requestValidator.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const defaults = require('../config/defaults');
+const { ValidationError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Formats validation issues into a clean, client-safe array of field-level errors.
+ *
+ * @param {Array<any>} rawIssues
+ * @param {'body'|'query'|'params'|'headers'} target
+ * @returns {Array<{ field: string, message: string, code?: string }>}
+ */
+function formatIssues(rawIssues = [], target) {
+  return rawIssues.map((issue) => {
+    let field = target;
+    if (issue.path && issue.path.length > 0) {
+      field = `${target}.${issue.path.join('.')}`;
+    } else if (issue.field) {
+      field = `${target}.${issue.field}`;
+    }
+
+    return {
+      field,
+      message: issue.message || 'Invalid value',
+      code: issue.code || 'INVALID_INPUT'
+    };
+  });
+}
+
+/**
+ * Validates a target object against a schema or validator function.
+ * Supports Zod schemas, Joi-like schemas, or custom functions.
+ *
+ * @param {any} schema - Validation schema or function.
+ * @param {any} data - Data to validate.
+ * @param {'body'|'query'|'params'|'headers'} target - Target name for error messages.
+ * @returns {Promise<{ success: boolean, data?: any, issues?: Array<any> }>}
+ */
+async function validateTarget(schema, data, target) {
+  if (!schema) {
+    return { success: true, data };
+  }
+
+  // 1. Custom function: (data) => boolean | { success, errors, data }
+  if (typeof schema === 'function' && !schema.safeParse && !schema.parse) {
+    try {
+      const res = await schema(data);
+      if (res === true || (res && res.success === true)) {
+        return { success: true, data: res.data !== undefined ? res.data : data };
+      }
+      const issues = res && res.errors ? res.errors : [{ message: 'Validation rule failed' }];
+      return { success: false, issues: formatIssues(issues, target) };
+    } catch (err) {
+      return { success: false, issues: [{ field: target, message: err.message, code: 'VALIDATION_ERROR' }] };
+    }
+  }
+
+  // 2. Zod schema: safeParseAsync or safeParse
+  if (typeof schema.safeParseAsync === 'function') {
+    const result = await schema.safeParseAsync(data);
+    if (result.success) {
+      return { success: true, data: result.data };
+    }
+    return { success: false, issues: formatIssues(result.error.issues, target) };
+  }
+
+  if (typeof schema.safeParse === 'function') {
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return { success: true, data: result.data };
+    }
+    return { success: false, issues: formatIssues(result.error.issues, target) };
+  }
+
+  // 3. Fallback for schema with parse() method
+  if (typeof schema.parse === 'function') {
+    try {
+      const parsedData = schema.parse(data);
+      return { success: true, data: parsedData };
+    } catch (err) {
+      const issues = err.issues || [{ message: err.message }];
+      return { success: false, issues: formatIssues(issues, target) };
+    }
+  }
+
+  throw new Error(`Unsupported schema format for ${target}. Must be a Zod schema or validator function.`);
+}
+
+/**
+ * Creates request validation middleware.
+ *
+ * @param {Object} schemas - Validation schemas.
+ * @param {any} [schemas.body] - Schema for req.body.
+ * @param {any} [schemas.query] - Schema for req.query.
+ * @param {any} [schemas.params] - Schema for req.params.
+ * @param {any} [schemas.headers] - Schema for req.headers.
+ * @param {Object} [userOptions]
+ * @param {boolean} [userOptions.assignToReq=false] - Whether to mutate req.body/req.query with parsed data (default false: store in req.validated).
+ * @param {number} [userOptions.statusCode=400] - Status code on failure.
+ * @param {string} [userOptions.message] - Custom error message.
+ * @param {Function} [userOptions.handler] - Custom error handler.
+ * @param {import('../utils/logger').SecurityLogger} [userOptions.logger] - Logger instance.
+ * @returns {import('express').RequestHandler}
+ */
+function createRequestValidator(schemas = {}, userOptions = {}) {
+  // If user passed a single Zod schema directly as first arg
+  let targetSchemas = schemas;
+  if (schemas && (typeof schemas.safeParse === 'function' || typeof schemas.safeParseAsync === 'function')) {
+    targetSchemas = { body: schemas };
+  }
+
+  const options = {
+    ...defaults.requestValidator,
+    ...userOptions
+  };
+
+  const logger = options.logger || defaultLogger;
+
+  return async function requestValidatorMiddleware(req, res, next) {
+    const targets = ['body', 'query', 'params', 'headers'];
+    const allIssues = [];
+    const validatedData = {};
+
+    for (const target of targets) {
+      const schema = targetSchemas[target];
+      if (schema) {
+        const dataToValidate = req[target] || {};
+        const result = await validateTarget(schema, dataToValidate, target);
+
+        if (!result.success) {
+          allIssues.push(...result.issues);
+        } else {
+          validatedData[target] = result.data;
+          if (options.assignToReq) {
+            req[target] = result.data;
+          }
+        }
+      }
+    }
+
+    if (allIssues.length > 0) {
+      logger.warn('REQUEST_VALIDATION_FAILED', `Validation failed for ${req.method} ${req.path}`, {
+        req,
+        details: { issues: allIssues }
+      });
+
+      const error = new ValidationError(options.message, { issues: allIssues });
+      return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+    }
+
+    // Attach validated data securely to req.validated
+    req.validated = {
+      ...req.validated,
+      ...validatedData
+    };
+
+    return next();
+  };
+}
+
+module.exports = {
+  requestValidator: createRequestValidator,
+  createRequestValidator,
+  formatIssues
+};
+

package/src/middleware/securityHeaders.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const helmet = require('helmet');
+const defaults = require('../config/defaults');
+
+/**
+ * Creates security headers middleware powered by Helmet with hardened API defaults.
+ *
+ * @param {Object} [userOptions]
+ * @param {boolean|Object} [userOptions.contentSecurityPolicy]
+ * @param {boolean|Object} [userOptions.hsts]
+ * @param {boolean|Object} [userOptions.frameguard]
+ * @param {boolean} [userOptions.noSniff]
+ * @param {boolean|Object} [userOptions.referrerPolicy]
+ * @param {boolean} [userOptions.noIndex=false] - Adds X-Robots-Tag: noindex, nofollow
+ * @param {boolean|string} [userOptions.permissionsPolicy=true] - Adds Permissions-Policy header
+ * @returns {import('express').RequestHandler}
+ */
+function createSecurityHeaders(userOptions = {}) {
+  const helmetOptions = {
+    ...defaults.securityHeaders,
+    ...userOptions
+  };
+
+  // Extract non-helmet custom options
+  const noIndex = userOptions.noIndex === true;
+  const permissionsPolicy = userOptions.permissionsPolicy !== undefined
+    ? userOptions.permissionsPolicy
+    : 'geolocation=(), camera=(), microphone=(), payment=()';
+
+  delete helmetOptions.noIndex;
+  delete helmetOptions.permissionsPolicy;
+
+  const helmetMiddleware = helmet(helmetOptions);
+
+  return function securityHeadersMiddleware(req, res, next) {
+    // 1. Apply Helmet standard headers
+    helmetMiddleware(req, res, (err) => {
+      if (err) return next(err);
+
+      // 2. Extra API security headers
+      if (noIndex) {
+        res.setHeader('X-Robots-Tag', 'noindex, nofollow, noarchive');
+      }
+
+      if (permissionsPolicy && typeof permissionsPolicy === 'string') {
+        res.setHeader('Permissions-Policy', permissionsPolicy);
+      }
+
+      return next();
+    });
+  };
+}
+
+module.exports = {
+  securityHeaders: createSecurityHeaders,
+  createSecurityHeaders
+};
+

package/src/middleware/threatDetector.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const defaults = require('../config/defaults');
+const { validateThreatDetectorConfig } = require('../config/validateConfig');
+const { DEFAULT_THREAT_PATTERNS, scanValue } = require('../security/detector');
+const { ThreatDetectedError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Creates threat detection middleware.
+ *
+ * @param {Object} [userOptions]
+ * @param {'reject'|'log'|'pass'} [userOptions.action='reject'] - Action on threat detection.
+ * @param {number} [userOptions.statusCode=403] - HTTP status code when rejected.
+ * @param {string} [userOptions.message] - Custom rejection message.
+ * @param {boolean} [userOptions.inspectUrl=true] - Inspect URL path.
+ * @param {boolean} [userOptions.inspectQuery=true] - Inspect query parameters.
+ * @param {boolean} [userOptions.inspectBody=true] - Inspect request body.
+ * @param {boolean} [userOptions.inspectHeaders=false] - Inspect headers (default false to prevent false positives).
+ * @param {Array<string|RegExp>} [userOptions.whitelistedPaths=[]] - Paths to bypass threat detection.
+ * @param {string[]} [userOptions.whitelistedKeys=[]] - Field names to bypass inspection.
+ * @param {Array<Object>} [userOptions.customRules=[]] - Custom threat rules.
+ * @param {Function} [userOptions.handler] - Custom response handler.
+ * @param {import('../utils/logger').SecurityLogger} [userOptions.logger] - Logger instance.
+ * @returns {import('express').RequestHandler}
+ */
+function createThreatDetector(userOptions = {}) {
+  validateThreatDetectorConfig(userOptions);
+
+  const options = {
+    ...defaults.threatDetector,
+    ...userOptions
+  };
+
+  const logger = options.logger || defaultLogger;
+  const allRules = [...DEFAULT_THREAT_PATTERNS, ...(options.customRules || [])];
+  const whitelistedKeys = (options.whitelistedKeys || []).map((k) => k.toLowerCase());
+
+  return function threatDetectorMiddleware(req, res, next) {
+    if (options.action === 'pass') {
+      return next();
+    }
+
+    const currentPath = req.originalUrl || req.path || req.url || '';
+
+    // Check whitelisted paths
+    if (options.whitelistedPaths && options.whitelistedPaths.length > 0) {
+      for (const whitePath of options.whitelistedPaths) {
+        if (typeof whitePath === 'string' && (currentPath === whitePath || currentPath.startsWith(whitePath))) {
+          return next();
+        }
+        if (whitePath instanceof RegExp && whitePath.test(currentPath)) {
+          return next();
+        }
+      }
+    }
+
+    const detectedThreats = [];
+
+    // 1. Inspect URL (path and raw query)
+    if (options.inspectUrl) {
+      let rawUrl = req.url || '';
+      try {
+        rawUrl = decodeURIComponent(rawUrl);
+      } catch {
+        // malformed URI encoding could itself be an attack vector
+        detectedThreats.push({
+          ruleId: 'MALFORMED_URI',
+          ruleName: 'Malformed URI Encoding',
+          path: 'url',
+          snippet: req.url,
+          severity: 'high'
+        });
+      }
+
+      if (rawUrl) {
+        detectedThreats.push(...scanValue(rawUrl, allRules, 'url', whitelistedKeys));
+      }
+    }
+
+    // 2. Inspect Query
+    if (options.inspectQuery && req.query && typeof req.query === 'object') {
+      detectedThreats.push(...scanValue(req.query, allRules, 'query', whitelistedKeys));
+    }
+
+    // 3. Inspect Body
+    if (options.inspectBody && req.body && typeof req.body === 'object') {
+      detectedThreats.push(...scanValue(req.body, allRules, 'body', whitelistedKeys));
+    }
+
+    // 4. Inspect Headers
+    if (options.inspectHeaders && req.headers && typeof req.headers === 'object') {
+      // Exclude standard headers that regularly contain symbols
+      const ignoredHeaders = ['user-agent', 'accept', 'cookie', 'host', 'authorization'];
+      const headersToScan = {};
+      for (const [k, v] of Object.entries(req.headers)) {
+        if (!ignoredHeaders.includes(k.toLowerCase())) {
+          headersToScan[k] = v;
+        }
+      }
+      detectedThreats.push(...scanValue(headersToScan, allRules, 'headers', whitelistedKeys));
+    }
+
+    if (detectedThreats.length > 0) {
+      req.detectedThreats = detectedThreats;
+
+      logger.warn('THREAT_DETECTED', `Threat patterns detected on ${req.method} ${currentPath}`, {
+        req,
+        details: {
+          threatCount: detectedThreats.length,
+          threats: detectedThreats.map((t) => ({ ruleId: t.ruleId, path: t.path, severity: t.severity }))
+        }
+      });
+
+      if (options.action === 'reject') {
+        const error = new ThreatDetectedError(options.message, options.statusCode, {
+          threats: detectedThreats.map((t) => ({ ruleId: t.ruleId, severity: t.severity }))
+        });
+        return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+      }
+    }
+
+    return next();
+  };
+}
+
+module.exports = {
+  threatDetector: createThreatDetector,
+  createThreatDetector
+};
+