secure-api-guard 0.0.0-stage → 1.0.0

package/src/config/defaults.js

@@ -0,0 +1,98 @@
+'use strict';
+
+module.exports = {
+  rateLimiter: {
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 100,
+    statusCode: 429,
+    message: 'Too many requests, please try again later.',
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    store: 'memory'
+  },
+
+  apiKeyAuth: {
+    headerName: 'x-api-key',
+    queryParam: null, // by default, disallow API key in query strings (security best practice)
+    allowBearer: true, // allow Authorization: Bearer <key>
+    hashAlgorithm: 'sha256',
+    statusCode: 401,
+    message: 'Unauthorized: Invalid or missing API key.',
+    forbiddenStatusCode: 403,
+    forbiddenMessage: 'Forbidden: API key has expired or has been revoked.'
+  },
+
+  ipFilter: {
+    mode: 'blocklist', // 'allowlist' | 'blocklist'
+    allowlist: [],
+    blocklist: [],
+    trustProxy: false,
+    statusCode: 403,
+    message: 'Forbidden: Access denied for your IP address.'
+  },
+
+  requestSize: {
+    maxSize: '1mb',
+    statusCode: 413,
+    message: 'Payload Too Large: Request body exceeds maximum allowed size.'
+  },
+
+  securityHeaders: {
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        baseUri: ["'self'"],
+        fontSrc: ["'self'", 'https:', 'data:'],
+        formAction: ["'self'"],
+        frameAncestors: ["'self'"],
+        imgSrc: ["'self'", 'data:'],
+        objectSrc: ["'none'"],
+        scriptSrc: ["'self'"],
+        scriptSrcAttr: ["'none'"],
+        styleSrc: ["'self'", 'https:', "'unsafe-inline'"],
+        upgradeInsecureRequests: []
+      }
+    },
+    crossOriginEmbedderPolicy: false,
+    crossOriginOpenerPolicy: { policy: 'same-origin' },
+    crossOriginResourcePolicy: { policy: 'same-origin' },
+    dnsPrefetchControl: { allow: false },
+    frameguard: { action: 'deny' },
+    hidePoweredBy: true,
+    hsts: {
+      maxAge: 31536000, // 1 year
+      includeSubDomains: true,
+      preload: true
+    },
+    ieNoOpen: true,
+    noSniff: true,
+    originAgentCluster: true,
+    permittedCrossDomainPolicies: { permittedPolicies: 'none' },
+    referrerPolicy: { policy: 'no-referrer' },
+    xssFilter: true
+  },
+
+  requestValidator: {
+    statusCode: 400,
+    message: 'Validation failed: Invalid request parameters.'
+  },
+
+  threatDetector: {
+    action: 'reject', // 'reject' | 'log' | 'pass'
+    statusCode: 403,
+    message: 'Forbidden: Suspicious request pattern detected.',
+    inspectUrl: true,
+    inspectQuery: true,
+    inspectBody: true,
+    inspectHeaders: false,
+    whitelistedPaths: [],
+    customRules: []
+  },
+
+  logger: {
+    enabled: true,
+    level: 'warn',
+    redactFields: []
+  }
+};
+

package/src/config/validateConfig.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const bytes = require('bytes');
+const { ConfigurationError } = require('../utils/errors');
+
+/**
+ * Validate Rate Limiter configuration options.
+ *
+ * @param {Object} options
+ */
+function validateRateLimiterConfig(options = {}) {
+  if (options.windowMs !== undefined) {
+    if (typeof options.windowMs !== 'number' || !Number.isFinite(options.windowMs) || options.windowMs <= 0) {
+      throw new ConfigurationError('RateLimiter: "windowMs" must be a positive number of milliseconds.');
+    }
+  }
+
+  const max = options.maxRequests !== undefined ? options.maxRequests : options.max;
+  if (max !== undefined) {
+    if (typeof max !== 'number' || !Number.isFinite(max) || max < 0) {
+      throw new ConfigurationError('RateLimiter: "maxRequests" (or "max") must be a non-negative number.');
+    }
+  }
+
+  if (options.statusCode !== undefined) {
+    if (typeof options.statusCode !== 'number' || options.statusCode < 100 || options.statusCode > 599) {
+      throw new ConfigurationError('RateLimiter: "statusCode" must be a valid HTTP status code between 100 and 599.');
+    }
+  }
+
+  if (options.keyGenerator !== undefined && typeof options.keyGenerator !== 'function') {
+    throw new ConfigurationError('RateLimiter: "keyGenerator" must be a function.');
+  }
+
+  if (options.skip !== undefined && typeof options.skip !== 'function') {
+    throw new ConfigurationError('RateLimiter: "skip" must be a function.');
+  }
+}
+
+/**
+ * Validate API Key Auth configuration options.
+ *
+ * @param {Object} options
+ */
+function validateApiKeyAuthConfig(options = {}) {
+  if (options.headerName !== undefined) {
+    if (typeof options.headerName !== 'string' || options.headerName.trim().length === 0) {
+      throw new ConfigurationError('ApiKeyAuth: "headerName" must be a non-empty string.');
+    }
+  }
+
+  if (options.queryParam !== undefined && options.queryParam !== null) {
+    if (typeof options.queryParam !== 'string' || options.queryParam.trim().length === 0) {
+      throw new ConfigurationError('ApiKeyAuth: "queryParam" must be a non-empty string or null.');
+    }
+  }
+
+  if (options.keys !== undefined) {
+    if (!Array.isArray(options.keys) && typeof options.keys !== 'object') {
+      throw new ConfigurationError('ApiKeyAuth: "keys" must be an array or object.');
+    }
+  }
+
+  if (options.getKey !== undefined && typeof options.getKey !== 'function') {
+    throw new ConfigurationError('ApiKeyAuth: "getKey" must be a function.');
+  }
+
+  if (options.verifyKey !== undefined && typeof options.verifyKey !== 'function') {
+    throw new ConfigurationError('ApiKeyAuth: "verifyKey" must be a function.');
+  }
+}
+
+/**
+ * Validate IP Filter configuration options.
+ *
+ * @param {Object} options
+ */
+function validateIpFilterConfig(options = {}) {
+  if (options.mode !== undefined) {
+    if (options.mode !== 'allowlist' && options.mode !== 'blocklist') {
+      throw new ConfigurationError('IpFilter: "mode" must be either "allowlist" or "blocklist".');
+    }
+  }
+
+  if (options.allowlist !== undefined && !Array.isArray(options.allowlist)) {
+    throw new ConfigurationError('IpFilter: "allowlist" must be an array of IP strings or CIDR notations.');
+  }
+
+  if (options.blocklist !== undefined && !Array.isArray(options.blocklist)) {
+    throw new ConfigurationError('IpFilter: "blocklist" must be an array of IP strings or CIDR notations.');
+  }
+
+  if (options.getIp !== undefined && typeof options.getIp !== 'function') {
+    throw new ConfigurationError('IpFilter: "getIp" must be a function.');
+  }
+}
+
+/**
+ * Validate Request Size configuration options.
+ *
+ * @param {Object} options
+ */
+function validateRequestSizeConfig(options = {}) {
+  if (options.maxSize !== undefined) {
+    if (typeof options.maxSize === 'string') {
+      const parsed = bytes.parse(options.maxSize);
+      if (parsed === null || parsed <= 0) {
+        throw new ConfigurationError(`RequestSize: "maxSize" string "${options.maxSize}" cannot be parsed into a valid byte limit.`);
+      }
+    } else if (typeof options.maxSize === 'number') {
+      if (!Number.isFinite(options.maxSize) || options.maxSize <= 0) {
+        throw new ConfigurationError('RequestSize: "maxSize" number must be greater than 0 bytes.');
+      }
+    } else {
+      throw new ConfigurationError('RequestSize: "maxSize" must be a number of bytes or a valid byte string (e.g. "1mb", "500kb").');
+    }
+  }
+}
+
+/**
+ * Validate Threat Detector configuration options.
+ *
+ * @param {Object} options
+ */
+function validateThreatDetectorConfig(options = {}) {
+  if (options.action !== undefined) {
+    if (!['reject', 'log', 'pass'].includes(options.action)) {
+      throw new ConfigurationError('ThreatDetector: "action" must be "reject", "log", or "pass".');
+    }
+  }
+
+  if (options.customRules !== undefined && !Array.isArray(options.customRules)) {
+    throw new ConfigurationError('ThreatDetector: "customRules" must be an array of rule objects or functions.');
+  }
+
+  if (options.whitelistedPaths !== undefined && !Array.isArray(options.whitelistedPaths)) {
+    throw new ConfigurationError('ThreatDetector: "whitelistedPaths" must be an array of strings or RegExps.');
+  }
+}
+
+module.exports = {
+  validateRateLimiterConfig,
+  validateApiKeyAuthConfig,
+  validateIpFilterConfig,
+  validateRequestSizeConfig,
+  validateThreatDetectorConfig
+};
+

package/src/index.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// Middlewares
+const { rateLimiter, createRateLimiter, defaultKeyGenerator } = require('./middleware/rateLimiter');
+const { apiKeyAuth, createApiKeyAuth, extractApiKey } = require('./middleware/apiKeyAuth');
+const { ipFilter, createIpFilter } = require('./middleware/ipFilter');
+const { requestSize, createRequestSize, parseContentLength } = require('./middleware/requestSize');
+const { securityHeaders, createSecurityHeaders } = require('./middleware/securityHeaders');
+const { requestValidator, createRequestValidator, formatIssues } = require('./middleware/requestValidator');
+const { threatDetector, createThreatDetector } = require('./middleware/threatDetector');
+
+// Security Utilities
+const {
+  hashApiKey,
+  generateApiKey,
+  secureCompare,
+  isKeyExpired
+} = require('./security/apiKey');
+
+const {
+  parseIp,
+  parseRule,
+  matchesRule,
+  isIpInRules,
+  compileRules,
+  getClientIp
+} = require('./security/ipAddress');
+
+const {
+  DEFAULT_THREAT_PATTERNS,
+  scanValue
+} = require('./security/detector');
+
+// Stores
+const { MemoryStore } = require('./stores/memoryStore');
+const { RedisStore } = require('./stores/redisStore');
+
+// Configuration
+const defaults = require('./config/defaults');
+const validateConfig = require('./config/validateConfig');
+
+// Utilities and Errors
+const {
+  SecurityError,
+  RateLimitError,
+  AuthenticationError,
+  ForbiddenError,
+  PayloadTooLargeError,
+  ValidationError,
+  ThreatDetectedError,
+  ConfigurationError
+} = require('./utils/errors');
+
+const { sendSecurityResponse } = require('./utils/response');
+const {
+  SecurityLogger,
+  defaultLogger,
+  redact,
+  getRequestId,
+  DEFAULT_SENSITIVE_KEYS
+} = require('./utils/logger');
+
+module.exports = {
+  // Primary Middlewares
+  rateLimiter,
+  createRateLimiter,
+  defaultKeyGenerator,
+
+  apiKeyAuth,
+  createApiKeyAuth,
+  extractApiKey,
+
+  ipFilter,
+  createIpFilter,
+
+  requestSize,
+  createRequestSize,
+  parseContentLength,
+
+  securityHeaders,
+  createSecurityHeaders,
+
+  requestValidator,
+  createRequestValidator,
+  formatIssues,
+
+  threatDetector,
+  createThreatDetector,
+
+  // Security Helpers
+  generateApiKey,
+  hashApiKey,
+  secureCompare,
+  isKeyExpired,
+
+  parseIp,
+  parseRule,
+  matchesRule,
+  isIpInRules,
+  compileRules,
+  getClientIp,
+
+  DEFAULT_THREAT_PATTERNS,
+  scanValue,
+
+  // Stores
+  MemoryStore,
+  RedisStore,
+
+  // Configuration
+  defaults,
+  validateConfig,
+
+  // Errors
+  SecurityError,
+  RateLimitError,
+  AuthenticationError,
+  ForbiddenError,
+  PayloadTooLargeError,
+  ValidationError,
+  ThreatDetectedError,
+  ConfigurationError,
+
+  // Utilities
+  sendSecurityResponse,
+  SecurityLogger,
+  defaultLogger,
+  redact,
+  getRequestId,
+  DEFAULT_SENSITIVE_KEYS
+};
+

package/src/middleware/apiKeyAuth.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const defaults = require('../config/defaults');
+const { validateApiKeyAuthConfig } = require('../config/validateConfig');
+const { hashApiKey, secureCompare, isKeyExpired } = require('../security/apiKey');
+const { AuthenticationError, ForbiddenError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Extracts API key from request headers or query parameters.
+ *
+ * @param {import('express').Request} req
+ * @param {Object} options
+ * @returns {string|null}
+ */
+function extractApiKey(req, options) {
+  const headerName = options.headerName.toLowerCase();
+
+  // 1. Direct header match
+  if (req.headers && req.headers[headerName]) {
+    const val = req.headers[headerName];
+    return Array.isArray(val) ? val[0].trim() : String(val).trim();
+  }
+
+  // 2. Authorization header (Bearer or Api-Key)
+  if (options.allowBearer && req.headers && req.headers.authorization) {
+    const authHeader = String(req.headers.authorization).trim();
+    const bearerMatch = authHeader.match(/^(?:Bearer|Api-Key)\s+(.+)$/i);
+    if (bearerMatch) {
+      return bearerMatch[1].trim();
+    }
+  }
+
+  // 3. Query parameter (only if explicitly enabled)
+  if (options.queryParam && req.query && req.query[options.queryParam]) {
+    const qVal = req.query[options.queryParam];
+    return Array.isArray(qVal) ? qVal[0].trim() : String(qVal).trim();
+  }
+
+  return null;
+}
+
+/**
+ * Creates API key authentication middleware.
+ *
+ * @param {Object} [userOptions]
+ * @param {string} [userOptions.headerName='x-api-key'] - Header name to check.
+ * @param {string|null} [userOptions.queryParam=null] - Query parameter name (if allowed).
+ * @param {boolean} [userOptions.allowBearer=true] - Allow Authorization: Bearer <key>.
+ * @param {string} [userOptions.hashAlgorithm='sha256'] - Hash algorithm.
+ * @param {Array<string|Object>} [userOptions.keys] - List of keys or key objects.
+ * @param {Function} [userOptions.getKey] - Async function (hash, req) => keyRecord.
+ * @param {Function} [userOptions.verifyKey] - Custom async verification function (rawKey, req).
+ * @param {string[]} [userOptions.requiredPermissions] - Optional permissions required for this route.
+ * @param {number} [userOptions.statusCode=401] - Status code for authentication failure.
+ * @param {number} [userOptions.forbiddenStatusCode=403] - Status code for expired/forbidden key.
+ * @param {string} [userOptions.message] - Custom error message for invalid key.
+ * @param {string} [userOptions.forbiddenMessage] - Custom error message for expired/forbidden key.
+ * @param {Function} [userOptions.handler] - Custom response handler.
+ * @param {import('../utils/logger').SecurityLogger} [userOptions.logger] - Logger instance.
+ * @returns {import('express').RequestHandler}
+ */
+function createApiKeyAuth(userOptions = {}) {
+  validateApiKeyAuthConfig(userOptions);
+
+  const options = {
+    ...defaults.apiKeyAuth,
+    ...userOptions
+  };
+
+  const logger = options.logger || defaultLogger;
+
+  // Pre-process keys if static list provided
+  // Stored format: array of { hash, id, name, expiresAt, permissions, metadata }
+  let precomputedKeys = [];
+  if (Array.isArray(options.keys)) {
+    precomputedKeys = options.keys.map((item, idx) => {
+      if (typeof item === 'string') {
+        // Assume raw string key provided; hash it
+        return {
+          id: `key_${idx + 1}`,
+          hash: hashApiKey(item, options.hashAlgorithm),
+          expiresAt: null,
+          permissions: []
+        };
+      } else if (typeof item === 'object' && item !== null) {
+        // If already hashed (item.hash), use it; otherwise hash item.key
+        const hash = item.hash || (item.key ? hashApiKey(item.key, options.hashAlgorithm) : null);
+        return {
+          id: item.id || `key_${idx + 1}`,
+          name: item.name,
+          hash,
+          expiresAt: item.expiresAt || null,
+          permissions: Array.isArray(item.permissions) ? item.permissions : [],
+          metadata: item.metadata || {}
+        };
+      }
+      return null;
+    }).filter(Boolean);
+  }
+
+  return async function apiKeyAuthMiddleware(req, res, next) {
+    const rawKey = extractApiKey(req, options);
+
+    if (!rawKey) {
+      logger.warn('API_KEY_AUTH_FAILED', 'API key missing in request', { req });
+      const error = new AuthenticationError(options.message);
+      return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+    }
+
+    try {
+      // 1. Custom verify function
+      if (typeof options.verifyKey === 'function') {
+        const verifyResult = await options.verifyKey(rawKey, req);
+        if (!verifyResult) {
+          logger.warn('API_KEY_AUTH_FAILED', 'API key verification rejected by verifyKey', { req });
+          const error = new AuthenticationError(options.message);
+          return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+        }
+
+        const keyInfo = typeof verifyResult === 'object' ? verifyResult : {};
+        if (isKeyExpired(keyInfo)) {
+          logger.warn('API_KEY_EXPIRED', `API key ${keyInfo.id || ''} has expired`, { req });
+          const error = new ForbiddenError(options.forbiddenMessage);
+          return sendSecurityResponse(req, res, error, options.forbiddenStatusCode, options.handler);
+        }
+
+        req.apiKey = {
+          id: keyInfo.id || 'custom',
+          name: keyInfo.name,
+          permissions: keyInfo.permissions || [],
+          metadata: keyInfo.metadata || {}
+        };
+        return next();
+      }
+
+      // Compute hash of incoming key
+      const incomingHash = hashApiKey(rawKey, options.hashAlgorithm);
+      let matchedRecord = null;
+
+      // 2. Custom getKey lookup function
+      if (typeof options.getKey === 'function') {
+        const retrieved = await options.getKey(incomingHash, req);
+        if (retrieved) {
+          const storedHash = retrieved.hash || (retrieved.key ? hashApiKey(retrieved.key, options.hashAlgorithm) : null);
+          if (storedHash && secureCompare(incomingHash, storedHash)) {
+            matchedRecord = retrieved;
+          }
+        }
+      } else {
+        // 3. Search precomputed static keys using constant-time comparison
+        for (const candidate of precomputedKeys) {
+          if (candidate.hash && secureCompare(incomingHash, candidate.hash)) {
+            matchedRecord = candidate;
+            break;
+          }
+        }
+      }
+
+      if (!matchedRecord) {
+        logger.warn('API_KEY_AUTH_FAILED', 'Invalid API key provided', { req });
+        const error = new AuthenticationError(options.message);
+        return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+      }
+
+      // Check expiration
+      if (isKeyExpired(matchedRecord)) {
+        logger.warn('API_KEY_EXPIRED', `API key ${matchedRecord.id || ''} has expired`, { req });
+        const error = new ForbiddenError(options.forbiddenMessage);
+        return sendSecurityResponse(req, res, error, options.forbiddenStatusCode, options.handler);
+      }
+
+      // Check permissions if required
+      if (options.requiredPermissions && options.requiredPermissions.length > 0) {
+        const keyPermissions = Array.isArray(matchedRecord.permissions) ? matchedRecord.permissions : [];
+        const hasAllPermissions = options.requiredPermissions.every((perm) => keyPermissions.includes(perm));
+
+        if (!hasAllPermissions) {
+          logger.warn('API_KEY_INSUFFICIENT_PERMISSIONS', `API key ${matchedRecord.id} lacks required permissions`, {
+            req,
+            details: { required: options.requiredPermissions, actual: keyPermissions }
+          });
+          const error = new ForbiddenError('Forbidden: Insufficient permissions for this API resource.');
+          return sendSecurityResponse(req, res, error, options.forbiddenStatusCode, options.handler);
+        }
+      }
+
+      // Attach sanitized key record (NEVER the plaintext key or raw hash)
+      req.apiKey = {
+        id: matchedRecord.id,
+        name: matchedRecord.name,
+        permissions: matchedRecord.permissions || [],
+        metadata: matchedRecord.metadata || {}
+      };
+
+      return next();
+    } catch (err) {
+      logger.error('API_KEY_AUTH_ERROR', `Internal error during API key verification: ${err.message}`, { req });
+      return next(err);
+    }
+  };
+}
+
+module.exports = {
+  apiKeyAuth: createApiKeyAuth,
+  createApiKeyAuth,
+  extractApiKey
+};
+

package/src/middleware/ipFilter.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const defaults = require('../config/defaults');
+const { validateIpFilterConfig } = require('../config/validateConfig');
+const { compileRules, isIpInRules, getClientIp } = require('../security/ipAddress');
+const { ForbiddenError } = require('../utils/errors');
+const { sendSecurityResponse } = require('../utils/response');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * Creates IP filtering middleware for Express.
+ *
+ * @param {Object} [userOptions]
+ * @param {'allowlist'|'blocklist'} [userOptions.mode='blocklist']
+ * @param {string[]} [userOptions.allowlist=[]] - Array of IPs or CIDRs to allow.
+ * @param {string[]} [userOptions.blocklist=[]] - Array of IPs or CIDRs to block.
+ * @param {boolean|string[]|number} [userOptions.trustProxy=false] - Proxy trusting strategy.
+ * @param {Function} [userOptions.getIp] - Custom IP extraction function.
+ * @param {number} [userOptions.statusCode=403] - Status code on rejection.
+ * @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 createIpFilter(userOptions = {}) {
+  validateIpFilterConfig(userOptions);
+
+  const options = {
+    ...defaults.ipFilter,
+    ...userOptions
+  };
+
+  const logger = options.logger || defaultLogger;
+
+  // Pre-compile IP and CIDR rules once at initialization
+  const compiledAllowlist = compileRules(options.allowlist);
+  const compiledBlocklist = compileRules(options.blocklist);
+
+  return function ipFilterMiddleware(req, res, next) {
+    const clientIp = getClientIp(req, options);
+
+    if (options.mode === 'allowlist') {
+      const allowed = isIpInRules(clientIp, compiledAllowlist);
+      if (!allowed) {
+        logger.warn('IP_ACCESS_DENIED', `IP ${clientIp} not in allowlist`, {
+          req,
+          ip: clientIp,
+          details: { mode: 'allowlist' }
+        });
+        const error = new ForbiddenError(options.message);
+        return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+      }
+    } else {
+      // Default: blocklist mode
+      const blocked = isIpInRules(clientIp, compiledBlocklist);
+      if (blocked) {
+        logger.warn('IP_BLOCKED', `IP ${clientIp} is blocklisted`, {
+          req,
+          ip: clientIp,
+          details: { mode: 'blocklist' }
+        });
+        const error = new ForbiddenError(options.message);
+        return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+      }
+    }
+
+    // Attach verified client IP to request for downstream handlers
+    req.clientIp = clientIp;
+    return next();
+  };
+}
+
+module.exports = {
+  ipFilter: createIpFilter,
+  createIpFilter
+};
+