secure-api-guard 0.0.0-stage → 1.0.0

package/src/security/apiKey.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Hash an API key using the specified algorithm (default: sha256).
+ *
+ * @param {string} rawKey - Plaintext API key.
+ * @param {string} [algorithm='sha256'] - Hashing algorithm.
+ * @returns {string} Hex-encoded hash.
+ */
+function hashApiKey(rawKey, algorithm = 'sha256') {
+  if (typeof rawKey !== 'string' || !rawKey) {
+    throw new Error('API key must be a non-empty string.');
+  }
+  return crypto.createHash(algorithm).update(rawKey, 'utf8').digest('hex');
+}
+
+/**
+ * Generate a cryptographically secure random API key.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.prefix='sag_'] - Key prefix (e.g. 'sag_live_', 'sag_test_').
+ * @param {number} [options.bytes=32] - Number of random bytes.
+ * @param {string} [options.algorithm='sha256'] - Hash algorithm for returned hash.
+ * @returns {{ key: string, hash: string, prefix: string }}
+ */
+function generateApiKey(options = {}) {
+  const prefix = options.prefix || 'sag_';
+  const byteLength = options.bytes && options.bytes >= 16 ? options.bytes : 32;
+  const algorithm = options.algorithm || 'sha256';
+
+  const randomPart = crypto.randomBytes(byteLength).toString('base64url');
+  const key = `${prefix}${randomPart}`;
+  const hash = hashApiKey(key, algorithm);
+
+  return {
+    key,
+    hash,
+    prefix
+  };
+}
+
+/**
+ * Constant-time comparison between two hashes to prevent timing attacks.
+ *
+ * @param {string} a - First hash hex string.
+ * @param {string} b - Second hash hex string.
+ * @returns {boolean} True if hashes match.
+ */
+function secureCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+
+  if (bufA.length !== bufB.length) {
+    // Constant time dummy comparison to avoid leaking length differences
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Check if a key record is expired.
+ *
+ * @param {Object} keyRecord
+ * @param {Date|string|number} [keyRecord.expiresAt]
+ * @returns {boolean}
+ */
+function isKeyExpired(keyRecord) {
+  if (!keyRecord || !keyRecord.expiresAt) {
+    return false;
+  }
+
+  const expiresTime = new Date(keyRecord.expiresAt).getTime();
+  if (isNaN(expiresTime)) {
+    return false;
+  }
+
+  return Date.now() > expiresTime;
+}
+
+module.exports = {
+  hashApiKey,
+  generateApiKey,
+  secureCompare,
+  isKeyExpired
+};
+

package/src/security/detector.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * High-confidence threat detection signatures.
+ *
+ * NOTE: Pattern matching is an auxiliary defense-in-depth heuristic, NOT a replacement
+ * for parameterized SQL queries, context-aware output encoding, or rigorous input validation.
+ */
+const DEFAULT_THREAT_PATTERNS = [
+  {
+    id: 'PATH_TRAVERSAL',
+    name: 'Directory / Path Traversal Attack',
+    pattern: /(?:\.\.[/\\]|[/\\]\.\.|\.\.%2f|%2e%2e%2f|%2e%2e\/|\.\.%5c|%2e%2e%5c)/i,
+    severity: 'high'
+  },
+  {
+    id: 'NULL_BYTE_INJECTION',
+    name: 'Null Byte Injection',
+    pattern: /(?:\x00|%00|\\0)/i,
+    severity: 'high'
+  },
+  {
+    id: 'COMMAND_INJECTION',
+    name: 'Suspicious Shell Command Injection',
+    pattern: /(?:;\s*(?:cat|chmod|curl|wget|rm|bash|sh|whoami|nc|netcat|powershell)\b|\|\s*(?:bash|sh|curl|wget|powershell)\b|`\s*(?:cat|curl|wget|rm|bash|sh|whoami)\s*`|\$\(\s*(?:cat|curl|wget|rm|bash|sh|whoami)\s*\))/i,
+    severity: 'high'
+  },
+  {
+    id: 'SCRIPT_TAG_INJECTION',
+    name: 'Suspicious Inline Script / JavaScript Scheme',
+    pattern: /(?:<\s*script\b[^>]*>|javascript\s*:\s*(?:alert|document|window|location|eval|prompt)\b|data\s*:\s*text\/html)/i,
+    severity: 'medium'
+  },
+  {
+    id: 'PROTOTYPE_POLLUTION',
+    name: 'Prototype Pollution Attempt',
+    pattern: /(?:__proto__|constructor\s*\[\s*['"]?prototype['"]?\s*\]|prototype\s*\.\s*constructor)/i,
+    severity: 'high'
+  },
+  {
+    id: 'SSTI_INJECTION',
+    name: 'Suspicious Template Injection (SSTI)',
+    pattern: /(?:\{\{\s*(?:constructor|process|require|mainModule|__proto__)\s*\}\}|<%\s*=\s*(?:process|require)\s*%>)/i,
+    severity: 'high'
+  }
+];
+
+/**
+ * Recursively inspects values in strings, arrays, or objects for threat signatures.
+ *
+ * @param {any} value - Value to inspect.
+ * @param {Array<Object>} rules - Compiled threat rules.
+ * @param {string} [currentPath=''] - Current object path for error reporting.
+ * @param {string[]} [whitelistedKeys=[]] - Keys to skip inspection.
+ * @param {Set<any>} [seen] - Visited objects to prevent infinite loops.
+ * @returns {Array<{ ruleId: string, ruleName: string, path: string, snippet: string, severity: string }>}
+ */
+function scanValue(value, rules, currentPath = '', whitelistedKeys = [], seen = new Set()) {
+  const matches = [];
+
+  if (value === null || value === undefined) {
+    return matches;
+  }
+
+  if (seen.has(value)) {
+    return matches;
+  }
+
+  // Handle strings
+  if (typeof value === 'string') {
+    for (const rule of rules) {
+      if (typeof rule.pattern === 'function') {
+        const customMatch = rule.pattern(value, currentPath);
+        if (customMatch) {
+          matches.push({
+            ruleId: rule.id || 'CUSTOM_RULE',
+            ruleName: rule.name || 'Custom Threat Rule',
+            path: currentPath,
+            snippet: value.length > 80 ? `${value.substring(0, 80)}...` : value,
+            severity: rule.severity || 'medium'
+          });
+        }
+      } else if (rule.pattern instanceof RegExp) {
+        if (rule.pattern.test(value)) {
+          matches.push({
+            ruleId: rule.id,
+            ruleName: rule.name,
+            path: currentPath,
+            snippet: value.length > 80 ? `${value.substring(0, 80)}...` : value,
+            severity: rule.severity
+          });
+        }
+      }
+    }
+    return matches;
+  }
+
+  // Handle Arrays
+  if (Array.isArray(value)) {
+    seen.add(value);
+    for (let i = 0; i < value.length; i++) {
+      const arrayPath = currentPath ? `${currentPath}[${i}]` : `[${i}]`;
+      matches.push(...scanValue(value[i], rules, arrayPath, whitelistedKeys, seen));
+    }
+    return matches;
+  }
+
+  // Handle Objects
+  if (typeof value === 'object') {
+    seen.add(value);
+
+    // Get all own property names including non-enumerable or __proto__
+    const propNames = Object.getOwnPropertyNames(value);
+    for (const propName of propNames) {
+      for (const rule of rules) {
+        if (rule.pattern instanceof RegExp && rule.pattern.test(propName)) {
+          matches.push({
+            ruleId: rule.id,
+            ruleName: rule.name,
+            path: currentPath ? `${currentPath}.${propName}` : propName,
+            snippet: `Key name: ${propName}`,
+            severity: rule.severity
+          });
+        }
+      }
+    }
+
+    // Check if prototype was directly manipulated
+    try {
+      const proto = Object.getPrototypeOf(value);
+      if (proto && proto !== Object.prototype && proto.constructor !== Object && typeof proto === 'object') {
+        matches.push({
+          ruleId: 'PROTOTYPE_POLLUTION',
+          ruleName: 'Prototype Pollution Attempt',
+          path: currentPath ? `${currentPath}.__proto__` : '__proto__',
+          snippet: 'Object has non-standard prototype',
+          severity: 'high'
+        });
+      }
+    } catch {
+      // Ignore prototype check failures on odd object types
+    }
+
+    for (const [key, val] of Object.entries(value)) {
+      // Check if key is whitelisted
+      if (whitelistedKeys.includes(key.toLowerCase())) {
+        continue;
+      }
+
+      const childPath = currentPath ? `${currentPath}.${key}` : key;
+      matches.push(...scanValue(val, rules, childPath, whitelistedKeys, seen));
+    }
+  }
+
+  return matches;
+}
+
+module.exports = {
+  DEFAULT_THREAT_PATTERNS,
+  scanValue
+};

package/src/security/ipAddress.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const ipaddr = require('ipaddr.js');
+
+/**
+ * Normalizes an IP string into a standard ipaddr.IPv4 or ipaddr.IPv6 object.
+ * Converts IPv4-mapped IPv6 (e.g. ::ffff:192.168.1.1) to pure IPv4.
+ *
+ * @param {string} ipString
+ * @returns {ipaddr.IPv4|ipaddr.IPv6|null}
+ */
+function parseIp(ipString) {
+  if (typeof ipString !== 'string') {
+    return null;
+  }
+
+  const clean = ipString.trim();
+  if (!clean) {
+    return null;
+  }
+
+  try {
+    let parsed = ipaddr.parse(clean);
+    // Convert IPv4-mapped IPv6 to pure IPv4
+    if (parsed.kind() === 'ipv6' && parsed.isIPv4MappedAddress()) {
+      parsed = parsed.toIPv4Address();
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parses an IP rule which can be a single IP or CIDR range.
+ *
+ * @param {string} ruleString
+ * @returns {{ type: 'cidr'|'ip', parsed: ipaddr.IPv4|ipaddr.IPv6|Array<any> } | null}
+ */
+function parseRule(ruleString) {
+  if (typeof ruleString !== 'string') {
+    return null;
+  }
+
+  const trimmed = ruleString.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  // Check if CIDR notation
+  if (trimmed.includes('/')) {
+    try {
+      const cidr = ipaddr.parseCIDR(trimmed);
+      return { type: 'cidr', parsed: cidr, raw: trimmed };
+    } catch {
+      return null;
+    }
+  }
+
+  // Single IP
+  const parsedIp = parseIp(trimmed);
+  if (parsedIp) {
+    return { type: 'ip', parsed: parsedIp, raw: trimmed };
+  }
+
+  return null;
+}
+
+/**
+ * Checks if a given IP address matches a compiled rule.
+ *
+ * @param {ipaddr.IPv4|ipaddr.IPv6} clientIp
+ * @param {Object} rule
+ * @returns {boolean}
+ */
+function matchesRule(clientIp, rule) {
+  if (!clientIp || !rule) {
+    return false;
+  }
+
+  if (rule.type === 'ip') {
+    return clientIp.toString() === rule.parsed.toString();
+  }
+
+  if (rule.type === 'cidr') {
+    try {
+      return clientIp.match(rule.parsed);
+    } catch {
+      // Kind mismatch (e.g. matching IPv6 client against IPv4 CIDR)
+      return false;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a client IP matches any rule in an array of rules.
+ *
+ * @param {string} clientIpStr
+ * @param {Array<Object>} compiledRules
+ * @returns {boolean}
+ */
+function isIpInRules(clientIpStr, compiledRules) {
+  const parsedClient = parseIp(clientIpStr);
+  if (!parsedClient) {
+    return false;
+  }
+
+  for (const rule of compiledRules) {
+    if (matchesRule(parsedClient, rule)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Compiles a list of IP and CIDR rule strings into parsed rule objects.
+ *
+ * @param {string[]} ruleStrings
+ * @returns {Array<Object>}
+ */
+function compileRules(ruleStrings = []) {
+  if (!Array.isArray(ruleStrings)) {
+    return [];
+  }
+
+  return ruleStrings
+    .map((r) => parseRule(r))
+    .filter((r) => r !== null);
+}
+
+/**
+ * Safely extracts client IP according to proxy configuration.
+ * Never blindly trusts X-Forwarded-For unless explicitly configured.
+ *
+ * @param {import('express').Request} req
+ * @param {Object} [options]
+ * @param {boolean|string[]|number|Function} [options.trustProxy=false]
+ * @returns {string} Extracted client IP
+ */
+function getClientIp(req, options = {}) {
+  const trustProxy = options.trustProxy !== undefined ? options.trustProxy : false;
+
+  // Custom function
+  if (typeof options.getIp === 'function') {
+    return options.getIp(req);
+  }
+
+  const directIp = (req.socket && req.socket.remoteAddress) ||
+    (req.connection && req.connection.remoteAddress) ||
+    '127.0.0.1';
+
+  if (!trustProxy) {
+    // When trustProxy is disabled, ONLY use direct socket address
+    const parsed = parseIp(directIp);
+    return parsed ? parsed.toString() : directIp;
+  }
+
+  // If trustProxy is boolean true, rely on express req.ip if available
+  if (trustProxy === true) {
+    if (req.ip) {
+      const parsed = parseIp(req.ip);
+      return parsed ? parsed.toString() : req.ip;
+    }
+  }
+
+  // If X-Forwarded-For is present and proxy is trusted
+  const xForwardedFor = req.headers && req.headers['x-forwarded-for'];
+  if (xForwardedFor) {
+    const rawList = Array.isArray(xForwardedFor) ? xForwardedFor.join(',') : xForwardedFor;
+    const ips = rawList.split(',').map((s) => s.trim()).filter(Boolean);
+
+    if (ips.length > 0) {
+      if (typeof trustProxy === 'number') {
+        // Trust specified number of hops from the right
+        const index = Math.max(0, ips.length - trustProxy);
+        const targetIp = ips[index] || directIp;
+        const parsed = parseIp(targetIp);
+        return parsed ? parsed.toString() : targetIp;
+      }
+
+      if (Array.isArray(trustProxy)) {
+        // Trust only if directIp is in the trusted proxy list
+        const trustedRules = compileRules(trustProxy);
+        if (isIpInRules(directIp, trustedRules)) {
+          // Find first untrusted IP walking backwards from right to left
+          for (let i = ips.length - 1; i >= 0; i--) {
+            if (!isIpInRules(ips[i], trustedRules)) {
+              const parsed = parseIp(ips[i]);
+              return parsed ? parsed.toString() : ips[i];
+            }
+          }
+          // All are trusted; return the leftmost
+          const parsed = parseIp(ips[0]);
+          return parsed ? parsed.toString() : ips[0];
+        } else {
+          // Direct connection is not a trusted proxy! Reject X-Forwarded-For header spoofing
+          const parsed = parseIp(directIp);
+          return parsed ? parsed.toString() : directIp;
+        }
+      }
+
+      // Boolean true fallback: take the first valid IP
+      const parsed = parseIp(ips[0]);
+      return parsed ? parsed.toString() : ips[0];
+    }
+  }
+
+  const parsed = parseIp(directIp);
+  return parsed ? parsed.toString() : directIp;
+}
+
+module.exports = {
+  parseIp,
+  parseRule,
+  matchesRule,
+  isIpInRules,
+  compileRules,
+  getClientIp
+};
+

package/src/stores/memoryStore.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * In-memory store for rate limiting with automatic background cleanup.
+ */
+class MemoryStore {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.windowMs=60000] - Window duration in milliseconds.
+   * @param {number} [options.cleanupIntervalMs=60000] - How often expired keys are purged.
+   */
+  constructor(options = {}) {
+    this.windowMs = options.windowMs || 60000;
+    this.hits = new Map();
+
+    const cleanupMs = options.cleanupIntervalMs || Math.min(this.windowMs, 60000);
+    this.interval = setInterval(() => this.cleanup(), cleanupMs);
+    // Unref so the cleanup interval does not block Node process exit
+    if (this.interval.unref) {
+      this.interval.unref();
+    }
+  }
+
+  /**
+   * Called by express-rate-limit with middleware options.
+   * @param {Object} options
+   */
+  init(options) {
+    if (options && options.windowMs) {
+      this.windowMs = options.windowMs;
+    }
+  }
+
+  /**
+   * Purge expired rate limit entries.
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, record] of this.hits.entries()) {
+      if (record.resetTime <= now) {
+        this.hits.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Increment hits for a key.
+   *
+   * @param {string} key
+   * @returns {Promise<{ totalHits: number, resetTime: Date }>}
+   */
+  async increment(key) {
+    const now = Date.now();
+    let record = this.hits.get(key);
+
+    if (!record || record.resetTime <= now) {
+      record = {
+        totalHits: 1,
+        resetTime: now + this.windowMs
+      };
+      this.hits.set(key, record);
+    } else {
+      record.totalHits += 1;
+    }
+
+    return {
+      totalHits: record.totalHits,
+      resetTime: new Date(record.resetTime)
+    };
+  }
+
+  /**
+   * Decrement hits for a key.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async decrement(key) {
+    const record = this.hits.get(key);
+    if (record && record.totalHits > 0) {
+      record.totalHits -= 1;
+    }
+  }
+
+  /**
+   * Reset hits for a single key.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async resetKey(key) {
+    this.hits.delete(key);
+  }
+
+  /**
+   * Reset all keys in memory.
+   *
+   * @returns {Promise<void>}
+   */
+  async resetAll() {
+    this.hits.clear();
+  }
+
+  /**
+   * Retrieve current hits for a key without incrementing.
+   *
+   * @param {string} key
+   * @returns {Promise<{ totalHits: number, resetTime: Date } | undefined>}
+   */
+  async get(key) {
+    const record = this.hits.get(key);
+    if (!record || record.resetTime <= Date.now()) {
+      return undefined;
+    }
+    return {
+      totalHits: record.totalHits,
+      resetTime: new Date(record.resetTime)
+    };
+  }
+
+  /**
+   * Clean up timer on teardown.
+   */
+  shutdown() {
+    if (this.interval) {
+      clearInterval(this.interval);
+    }
+    this.hits.clear();
+  }
+}
+
+module.exports = {
+  MemoryStore
+};
+