secure-api-guard 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secure-api-guard",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Production-ready, battle-tested security middleware suite for Node.js and Express applications",
   "main": "src/index.js",
   "types": "src/types/index.d.ts",

package/src/config/validateConfig.js

@@ -3,6 +3,12 @@
 const bytes = require('bytes');
 const { ConfigurationError } = require('../utils/errors');
 
+function assertFunction(fn, name) {
+  if (fn !== undefined && typeof fn !== 'function') {
+    throw new ConfigurationError(`${name} must be a function.`);
+  }
+}
+
 /**
  * Validate Rate Limiter configuration options.
  *
@@ -28,13 +34,8 @@ function validateRateLimiterConfig(options = {}) {
     }
   }
 
-  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.');
-  }
+  assertFunction(options.keyGenerator, 'RateLimiter: "keyGenerator"');
+  assertFunction(options.skip, 'RateLimiter: "skip"');
 }
 
 /**
@@ -55,19 +56,12 @@ function validateApiKeyAuthConfig(options = {}) {
     }
   }
 
-  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.keys !== undefined && !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.');
-  }
+  assertFunction(options.getKey, 'ApiKeyAuth: "getKey"');
+  assertFunction(options.verifyKey, 'ApiKeyAuth: "verifyKey"');
 }
 
 /**
@@ -76,10 +70,8 @@ function validateApiKeyAuthConfig(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.mode !== undefined && 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)) {
@@ -90,9 +82,7 @@ function validateIpFilterConfig(options = {}) {
     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.');
-  }
+  assertFunction(options.getIp, 'IpFilter: "getIp"');
 }
 
 /**
@@ -123,10 +113,8 @@ function validateRequestSizeConfig(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.action !== undefined && !['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)) {

package/src/index.js

@@ -19,6 +19,7 @@ const {
 
 const {
   parseIp,
+  formatIp,
   parseRule,
   matchesRule,
   isIpInRules,
@@ -94,6 +95,7 @@ module.exports = {
   isKeyExpired,
 
   parseIp,
+  formatIp,
   parseRule,
   matchesRule,
   isIpInRules,

package/src/middleware/apiKeyAuth.js

@@ -100,6 +100,37 @@ function createApiKeyAuth(userOptions = {}) {
     }).filter(Boolean);
   }
 
+  function authorizeKey(keyRecord, req, res, next) {
+    if (isKeyExpired(keyRecord)) {
+      logger.warn('API_KEY_EXPIRED', `API key ${keyRecord.id || ''} has expired`, { req });
+      const error = new ForbiddenError(options.forbiddenMessage);
+      return sendSecurityResponse(req, res, error, options.forbiddenStatusCode, options.handler);
+    }
+
+    if (options.requiredPermissions && options.requiredPermissions.length > 0) {
+      const keyPermissions = Array.isArray(keyRecord.permissions) ? keyRecord.permissions : [];
+      const hasAll = options.requiredPermissions.every((perm) => keyPermissions.includes(perm));
+
+      if (!hasAll) {
+        logger.warn('API_KEY_INSUFFICIENT_PERMISSIONS', `API key ${keyRecord.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);
+      }
+    }
+
+    req.apiKey = {
+      id: keyRecord.id || 'custom',
+      name: keyRecord.name,
+      permissions: keyRecord.permissions || [],
+      metadata: keyRecord.metadata || {}
+    };
+
+    return next();
+  }
+
   return async function apiKeyAuthMiddleware(req, res, next) {
     const rawKey = extractApiKey(req, options);
 
@@ -120,26 +151,13 @@ function createApiKeyAuth(userOptions = {}) {
         }
 
         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();
+        return authorizeKey(keyInfo, req, res, next);
       }
 
-      // Compute hash of incoming key
+      // 2. Hash lookup
       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) {
@@ -149,7 +167,6 @@ function createApiKeyAuth(userOptions = {}) {
           }
         }
       } else {
-        // 3. Search precomputed static keys using constant-time comparison
         for (const candidate of precomputedKeys) {
           if (candidate.hash && secureCompare(incomingHash, candidate.hash)) {
             matchedRecord = candidate;
@@ -164,37 +181,7 @@ function createApiKeyAuth(userOptions = {}) {
         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();
+      return authorizeKey(matchedRecord, req, res, next);
     } catch (err) {
       logger.error('API_KEY_AUTH_ERROR', `Internal error during API key verification: ${err.message}`, { req });
       return next(err);

package/src/middleware/rateLimiter.js

@@ -3,26 +3,13 @@
 const rateLimit = require('express-rate-limit');
 const defaults = require('../config/defaults');
 const { validateRateLimiterConfig } = require('../config/validateConfig');
+const { formatIp } = require('../security/ipAddress');
 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.
  *
@@ -31,7 +18,7 @@ function normalizeIp(ip) {
  */
 function defaultKeyGenerator(req) {
   const rawIp = req.ip || (req.socket && req.socket.remoteAddress) || '127.0.0.1';
-  return normalizeIp(rawIp);
+  return formatIp(rawIp);
 }
 
 /**

package/src/middleware/requestSize.js

@@ -71,6 +71,16 @@ function createRequestSize(userOptions = {}) {
 
   const logger = options.logger || defaultLogger;
 
+  function rejectOversized(req, res, details) {
+    logger.warn('REQUEST_SIZE_EXCEEDED', `Payload exceeded size limit (${maxBytes} bytes)`, {
+      req,
+      details
+    });
+    res.setHeader('Connection', 'close');
+    const error = new PayloadTooLargeError(options.message, details);
+    return sendSecurityResponse(req, res, error, options.statusCode, options.handler);
+  }
+
   return function requestSizeMiddleware(req, res, next) {
     // 1. Inspect Content-Length header
     const { length: contentLength, error: headerError } = parseContentLength(req);
@@ -82,32 +92,18 @@ function createRequestSize(userOptions = {}) {
     }
 
     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);
+      return rejectOversized(req, res, { contentLength, maxBytes });
     }
 
     // 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');
-        }
+        const estimatedSize = Buffer.isBuffer(req.body)
+          ? req.body.length
+          : 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);
+          return rejectOversized(req, res, { estimatedSize, maxBytes });
         }
       } catch {
         // Ignore serialization failure; proceed to streaming check
@@ -130,14 +126,7 @@ function createRequestSize(userOptions = {}) {
               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);
+              rejectOversized(req, res, { receivedBytes, maxBytes });
               return false;
             }
           }

package/src/middleware/requestValidator.js

@@ -58,20 +58,15 @@ async function validateTarget(schema, data, target) {
   }
 
   // 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) };
+  const parseFn = typeof schema.safeParseAsync === 'function'
+    ? schema.safeParseAsync.bind(schema)
+    : (typeof schema.safeParse === 'function' ? schema.safeParse.bind(schema) : null);
+
+  if (parseFn) {
+    const result = await parseFn(data);
+    return result.success
+      ? { success: true, data: result.data }
+      : { success: false, issues: formatIssues(result.error.issues, target) };
   }
 
   // 3. Fallback for schema with parse() method

package/src/middleware/threatDetector.js

@@ -46,13 +46,11 @@ function createThreatDetector(userOptions = {}) {
 
     // 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 isWhitelisted = options.whitelistedPaths.some((p) =>
+        typeof p === 'string' ? (currentPath === p || currentPath.startsWith(p)) : (p instanceof RegExp && p.test(currentPath))
+      );
+      if (isWhitelisted) {
+        return next();
       }
     }
 

package/src/security/apiKey.js

@@ -78,11 +78,7 @@ function isKeyExpired(keyRecord) {
   }
 
   const expiresTime = new Date(keyRecord.expiresAt).getTime();
-  if (isNaN(expiresTime)) {
-    return false;
-  }
-
-  return Date.now() > expiresTime;
+  return !Number.isNaN(expiresTime) && Date.now() > expiresTime;
 }
 
 module.exports = {

package/src/security/detector.js

@@ -45,6 +45,36 @@ const DEFAULT_THREAT_PATTERNS = [
   }
 ];
 
+/**
+ * Evaluates a threat rule against a string value.
+ *
+ * @param {Object} rule
+ * @param {string} value
+ * @param {string} path
+ * @param {string} [snippetPrefix]
+ * @returns {Object|null}
+ */
+function matchRule(rule, value, path, snippetPrefix) {
+  let matched = false;
+  if (typeof rule.pattern === 'function') {
+    matched = Boolean(rule.pattern(value, path));
+  } else if (rule.pattern instanceof RegExp) {
+    matched = rule.pattern.test(value);
+  }
+
+  if (matched) {
+    const raw = snippetPrefix ? `${snippetPrefix}: ${value}` : value;
+    return {
+      ruleId: rule.id || 'CUSTOM_RULE',
+      ruleName: rule.name || 'Custom Threat Rule',
+      path,
+      snippet: raw.length > 80 ? `${raw.substring(0, 80)}...` : raw,
+      severity: rule.severity || 'medium'
+    };
+  }
+  return null;
+}
+
 /**
  * Recursively inspects values in strings, arrays, or objects for threat signatures.
  *
@@ -58,39 +88,15 @@ const DEFAULT_THREAT_PATTERNS = [
 function scanValue(value, rules, currentPath = '', whitelistedKeys = [], seen = new Set()) {
   const matches = [];
 
-  if (value === null || value === undefined) {
-    return matches;
-  }
-
-  if (seen.has(value)) {
+  if (value === null || value === undefined || 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
-          });
-        }
-      }
+      const match = matchRule(rule, value, currentPath);
+      if (match) matches.push(match);
     }
     return matches;
   }
@@ -112,16 +118,10 @@ function scanValue(value, rules, currentPath = '', whitelistedKeys = [], seen =
     // Get all own property names including non-enumerable or __proto__
     const propNames = Object.getOwnPropertyNames(value);
     for (const propName of propNames) {
+      const keyPath = currentPath ? `${currentPath}.${propName}` : propName;
       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
-          });
-        }
+        const match = matchRule(rule, propName, keyPath, 'Key name');
+        if (match) matches.push(match);
       }
     }
 
@@ -142,11 +142,9 @@ function scanValue(value, rules, currentPath = '', whitelistedKeys = [], seen =
     }
 
     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));
     }

package/src/security/ipAddress.js

@@ -132,6 +132,18 @@ function compileRules(ruleStrings = []) {
     .filter((r) => r !== null);
 }
 
+/**
+ * Formats an IP string into its canonical parsed representation or original string.
+ *
+ * @param {string} ip
+ * @returns {string}
+ */
+function formatIp(ip) {
+  if (!ip) return '127.0.0.1';
+  const parsed = parseIp(ip);
+  return parsed ? parsed.toString() : ip;
+}
+
 /**
  * Safely extracts client IP according to proxy configuration.
  * Never blindly trusts X-Forwarded-For unless explicitly configured.
@@ -144,7 +156,7 @@ function compileRules(ruleStrings = []) {
 function getClientIp(req, options = {}) {
   const trustProxy = options.trustProxy !== undefined ? options.trustProxy : false;
 
-  // Custom function
+  // Custom extractor function
   if (typeof options.getIp === 'function') {
     return options.getIp(req);
   }
@@ -154,20 +166,14 @@ function getClientIp(req, options = {}) {
     '127.0.0.1';
 
   if (!trustProxy) {
-    // When trustProxy is disabled, ONLY use direct socket address
-    const parsed = parseIp(directIp);
-    return parsed ? parsed.toString() : directIp;
+    return formatIp(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 trustProxy is boolean true, prefer express req.ip if set
+  if (trustProxy === true && req.ip) {
+    return formatIp(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;
@@ -175,46 +181,35 @@ function getClientIp(req, options = {}) {
 
     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;
+        return formatIp(ips[index] || directIp);
       }
 
       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
+          // Walk backwards to find first untrusted IP
           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];
+              return formatIp(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;
+          return formatIp(ips[0]);
         }
+        // Direct socket is not a trusted proxy: ignore spoofed header
+        return formatIp(directIp);
       }
 
-      // Boolean true fallback: take the first valid IP
-      const parsed = parseIp(ips[0]);
-      return parsed ? parsed.toString() : ips[0];
+      return formatIp(ips[0]);
     }
   }
 
-  const parsed = parseIp(directIp);
-  return parsed ? parsed.toString() : directIp;
+  return formatIp(directIp);
 }
 
 module.exports = {
   parseIp,
+  formatIp,
   parseRule,
   matchesRule,
   isIpInRules,

package/src/stores/redisStore.js

@@ -39,6 +39,7 @@ class RedisStore {
     this.windowMs = options.windowMs || 60000;
     this.passOnConnectionError = options.passOnConnectionError !== false;
     this.logger = options.logger || defaultLogger;
+    this._evalMode = null;
   }
 
   /**
@@ -70,24 +71,30 @@ class RedisStore {
   async _evalLua(key, windowMs) {
     const fullKey = this._prefixKey(key);
 
-    // Node-redis v4+ client.eval syntax
-    if (typeof this.client.eval === 'function') {
-      try {
-        // Attempt node-redis v4 object parameters
-        const res = await this.client.eval(LUA_INCR_SCRIPT, {
-          keys: [fullKey],
-          arguments: [String(windowMs)]
-        });
-        return res;
-      } catch (err) {
-        // If node-redis object parameter syntax failed, try ioredis positional syntax:
-        // eval(script, numkeys, key1, ..., arg1, ...)
-        const res = await this.client.eval(LUA_INCR_SCRIPT, 1, fullKey, String(windowMs));
-        return res;
-      }
+    if (typeof this.client.eval !== 'function') {
+      throw new Error('Provided Redis client does not support eval command.');
+    }
+
+    if (this._evalMode === 'node-redis') {
+      return this.client.eval(LUA_INCR_SCRIPT, { keys: [fullKey], arguments: [String(windowMs)] });
+    }
+    if (this._evalMode === 'ioredis') {
+      return this.client.eval(LUA_INCR_SCRIPT, 1, fullKey, String(windowMs));
     }
 
-    throw new Error('Provided Redis client does not support eval command.');
+    // Auto-detect client signature on first execution
+    try {
+      const res = await this.client.eval(LUA_INCR_SCRIPT, {
+        keys: [fullKey],
+        arguments: [String(windowMs)]
+      });
+      this._evalMode = 'node-redis';
+      return res;
+    } catch {
+      const res = await this.client.eval(LUA_INCR_SCRIPT, 1, fullKey, String(windowMs));
+      this._evalMode = 'ioredis';
+      return res;
+    }
   }
 
   /**

package/src/types/index.d.ts

@@ -213,6 +213,7 @@ export interface IpFilterOptions {
 export function ipFilter(options?: IpFilterOptions): RequestHandler;
 export function createIpFilter(options?: IpFilterOptions): RequestHandler;
 export function parseIp(ipString: string): any;
+export function formatIp(ipString: string): string;
 export function parseRule(ruleString: string): any;
 export function matchesRule(clientIp: any, rule: any): boolean;
 export function isIpInRules(clientIpStr: string, compiledRules: any[]): boolean;

package/src/utils/logger.js

@@ -182,22 +182,8 @@ class SecurityLogger {
 
     const formatted = `[secure-api-guard] [${event.timestamp}] [${event.level}] [${event.eventType}] ${event.message} (reqId=${event.requestId}, ip=${event.ip})`;
 
-    switch (level) {
-      case 'error':
-        console.error(formatted, event.details);
-        break;
-      case 'warn':
-        console.warn(formatted, event.details);
-        break;
-      case 'info':
-        console.info(formatted, event.details);
-        break;
-      case 'debug':
-        console.debug(formatted, event.details);
-        break;
-      default:
-        console.log(formatted, event.details);
-    }
+    const logFn = typeof console[level] === 'function' ? console[level] : console.log;
+    logFn(formatted, event.details);
   }
 
   debug(eventType, message, context) {