z-shield 0.1.1 → 0.1.2

package/src/middleware.js

@@ -1,288 +0,0 @@
-'use strict';
-
-const { resolveConfig } = require('./config');
-const { RateLimiter } = require('./rate-limiter');
-const { Detector } = require('./detector');
-const { BlockManager, isValidIp, normalizeIp } = require('./block-manager');
-const { Logger } = require('./logger');
-
-/**
- * Safely extracts the client's IP address and normalizes IPv4 and IPv6 representations.
- *
- * Security Note:
- * An attacker can easily send spoofed headers like `X-Forwarded-For: 1.2.3.4`.
- * Therefore, we NEVER inspect `X-Forwarded-For` directly unless `trustProxy` is true
- * AND Express itself has verified it through its own `trust proxy` configuration.
- *
- * @param {import('express').Request} req - The incoming Express request object
- * @param {boolean} trustProxy - Whether proxy headers are explicitly trusted
- * @returns {string} The normalized client IP address
- */
-function extractClientIp(req, trustProxy) {
-  let ip = '';
-
-  if (trustProxy && typeof req.ip === 'string' && req.ip.length > 0) {
-    ip = req.ip;
-  } else if (req.socket && typeof req.socket.remoteAddress === 'string') {
-    ip = req.socket.remoteAddress;
-  } else if (req.connection && typeof req.connection.remoteAddress === 'string') {
-    ip = req.connection.remoteAddress;
-  }
-
-  return normalizeIp(ip);
-}
-
-/**
- * Determines whether a given request path matches any of the excluded route patterns.
- * Respects path-segment boundaries so that excluding '/health' matches '/health' or '/health/live'
- * but does NOT match '/health-admin' or '/healthcare'.
- * Also normalizes trailing slashes and ignores query strings and fragments.
- *
- * @param {string} requestPath - The incoming request path (or raw url)
- * @param {string[]} excludeRoutes - Configured excluded route prefixes
- * @returns {boolean}
- */
-function isRouteExcluded(requestPath, excludeRoutes) {
-  if (!Array.isArray(excludeRoutes) || excludeRoutes.length === 0) {
-    return false;
-  }
-
-  // Strip query string and fragment if present (e.g. from req.url)
-  const cleanPath = (requestPath || '/').split('?')[0].split('#')[0];
-
-  return excludeRoutes.some((route) => {
-    if (typeof route !== 'string' || route.length === 0) {
-      return false;
-    }
-
-    if (route === '/') {
-      return cleanPath === '/';
-    }
-
-    // Strip trailing slash from route prefix for normalized segment comparison
-    const normalizedPrefix = route.endsWith('/') ? route.slice(0, -1) : route;
-
-    // Exact match (e.g. '/health' === '/health' or '/status' === '/status')
-    if (cleanPath === normalizedPrefix) {
-      return true;
-    }
-
-    // Sub-path segment match (e.g. '/health/check'.startsWith('/health/'))
-    if (cleanPath.startsWith(normalizedPrefix + '/')) {
-      return true;
-    }
-
-    return false;
-  });
-}
-
-/**
- * Sets a response header only if headers have not already been sent to the client.
- *
- * @param {import('express').Response} res
- * @param {string} name
- * @param {string} value
- */
-function safeSetHeader(res, name, value) {
-  if (res && !res.headersSent && typeof res.setHeader === 'function') {
-    res.setHeader(name, value);
-  }
-}
-
-/**
- * Safely terminates an open HTTP response without calling next() or setting headers.
- * Used when a blocked request in protect mode already had its headers committed upstream.
- *
- * @param {import('express').Response} res
- */
-function safelyEndResponse(res) {
-  if (res && !res.writableEnded && typeof res.end === 'function') {
-    res.end();
-  }
-}
-
-/**
- * Factory function to create the Z-Shield Express middleware.
- *
- * @param {Object} [options={}] - Custom configuration options
- * @param {Object} [dependencies={}] - Injected dependencies (useful for testing)
- * @param {RateLimiter} [dependencies.rateLimiter]
- * @param {Detector} [dependencies.detector]
- * @param {BlockManager} [dependencies.blockManager]
- * @param {Logger} [dependencies.logger]
- * @returns {Function} Express middleware function: (req, res, next) => void
- */
-function createMiddleware(options = {}, dependencies = {}) {
-  const config = resolveConfig(options);
-  const rateLimiter = dependencies.rateLimiter || new RateLimiter(config);
-  const detector = dependencies.detector || new Detector({ rateLimiter, config });
-  const blockManager = dependencies.blockManager || new BlockManager(config);
-  const logger = dependencies.logger || new Logger(config);
-
-  return function zShieldMiddleware(req, res, next) {
-    try {
-      const clientIp = extractClientIp(req, config.trustProxy);
-      const rawPath = (typeof req.path === 'string' && req.path.length > 0)
-        ? req.path
-        : (req.url || '/');
-      const requestPath = rawPath.split('?')[0].split('#')[0] || '/';
-      const requestMethod = req.method || 'GET';
-      const now = Date.now();
-
-      // Check if this route is in the exclusion list (respecting segment boundaries)
-      const isExcluded = isRouteExcluded(requestPath, config.excludeRoutes);
-
-      if (isExcluded) {
-        req.zShield = {
-          ip: clientIp,
-          mode: config.mode,
-          appName: config.appName,
-          isExcluded: true,
-          startTime: now,
-          detection: null,
-          blocked: false
-        };
-        safeSetHeader(res, 'X-Z-Shield-Protected', '1');
-        safeSetHeader(res, 'X-Z-Shield-Mode', config.mode);
-        return next();
-      }
-
-      // Step 1: Check active temporary blocks
-      const isIpBlocked = blockManager.isBlocked(clientIp, now);
-
-      if (isIpBlocked) {
-        const blockInfo = blockManager.getBlockInfo(clientIp, now);
-        const retryAfterSeconds = Math.max(1, Math.ceil(blockInfo.remainingMs / 1000));
-        const action = config.mode === 'protect' ? 'blocked' : 'warned';
-
-        // Log the security event asynchronously
-        const logPromise = logger.log({
-          appName: config.appName,
-          type: 'blocked_ip',
-          severity: 'warning',
-          ip: clientIp,
-          method: requestMethod,
-          route: requestPath,
-          reason: blockInfo.reason,
-          action
-        });
-
-        req.zShield = {
-          ip: clientIp,
-          mode: config.mode,
-          appName: config.appName,
-          isExcluded: false,
-          startTime: now,
-          detection: null,
-          blocked: true,
-          blockReason: blockInfo.reason,
-          logPromise
-        };
-
-        safeSetHeader(res, 'X-Z-Shield-Protected', '1');
-        safeSetHeader(res, 'X-Z-Shield-Mode', config.mode);
-        safeSetHeader(res, 'X-Z-Shield-Blocked', '1');
-        safeSetHeader(res, 'X-Z-Shield-Reason', blockInfo.reason);
-        safeSetHeader(res, 'Retry-After', String(retryAfterSeconds));
-
-        if (config.mode === 'protect') {
-          if (!res.headersSent) {
-            return res.status(429).json({
-              error: 'Too Many Requests',
-              message: 'Your IP address has been temporarily blocked due to suspicious activity.',
-              retryAfter: retryAfterSeconds
-            });
-          }
-          // If headers were already committed upstream, we cannot send 429.
-          // Safely terminate the open response without calling next().
-          safelyEndResponse(res);
-          return;
-        }
-
-        // Monitor mode: mark warning header, but allow request through
-        safeSetHeader(res, 'X-Z-Shield-Suspicious', '1');
-        return next();
-      }
-
-      // Step 2: Rate limit tracking and abuse detection
-      const detection = detector.check(clientIp, req, now);
-
-      let logPromise = null;
-      if (detection.isSuspicious) {
-        const action = config.mode === 'protect' ? 'blocked' : 'warned';
-        logPromise = logger.log({
-          appName: config.appName,
-          type: detection.type || 'rate_limit',
-          severity: detection.severity || 'warning',
-          ip: clientIp,
-          method: requestMethod,
-          route: requestPath,
-          reason: detection.reason,
-          action
-        });
-      }
-
-      req.zShield = {
-        ip: clientIp,
-        mode: config.mode,
-        appName: config.appName,
-        isExcluded: false,
-        startTime: now,
-        detection,
-        blocked: false,
-        logPromise
-      };
-
-      // Set informative headers
-      safeSetHeader(res, 'X-Z-Shield-Protected', '1');
-      safeSetHeader(res, 'X-Z-Shield-Mode', config.mode);
-      safeSetHeader(res, 'X-RateLimit-Limit', String(config.maxRequests));
-      safeSetHeader(res, 'X-RateLimit-Remaining', String(detection.remaining));
-      safeSetHeader(res, 'X-RateLimit-Reset', String(Math.ceil(detection.resetTime / 1000)));
-
-      if (detection.isSuspicious) {
-        safeSetHeader(res, 'X-Z-Shield-Suspicious', '1');
-        safeSetHeader(res, 'X-Z-Shield-Reason', detection.reason);
-
-        if (config.mode === 'protect') {
-          // If autoBlock is enabled and IP is valid, add to block manager.
-          // Unknown or invalid IPs must not be passed to blockManager.block()
-          // as that would throw a TypeError and cause an unexpected HTTP 500.
-          if (config.autoBlock && isValidIp(clientIp)) {
-            blockManager.block(clientIp, config.blockDurationMs, detection.reason, now);
-          }
-
-          const retryAfterSeconds = Math.max(1, Math.ceil((detection.resetTime - now) / 1000));
-          safeSetHeader(res, 'Retry-After', String(retryAfterSeconds));
-
-          if (!res.headersSent) {
-            return res.status(429).json({
-              error: 'Too Many Requests',
-              message: 'Request threshold exceeded. Please try again later.',
-              retryAfter: retryAfterSeconds
-            });
-          }
-          // If headers were already committed upstream, we cannot send 429.
-          // Safely terminate the open response without calling next().
-          safelyEndResponse(res);
-          return;
-        }
-      }
-
-      // In monitor mode or normal traffic in protect mode: allow through
-      return next();
-    } catch (err) {
-      // If an unexpected error occurs in middleware execution, pass it safely to Express
-      // error handling without crashing the entire Node.js server process.
-      return next(err);
-    }
-  };
-}
-
-module.exports = {
-  createMiddleware,
-  extractClientIp,
-  isRouteExcluded,
-  normalizeIp,
-  safelyEndResponse
-};

package/src/rate-limiter.js

@@ -1,186 +0,0 @@
-'use strict';
-
-const { normalizeIp } = require('./block-manager');
-
-/**
- * RateLimiter - Bounded In-Memory Request Counter
- *
- * Algorithm: Fixed Window with Per-IP Dynamic Reset Time
- * - On an IP's first request, we establish a time window (now -> now + windowMs).
- * - Every subsequent request within the window increments the counter.
- * - When the window expires, the counter resets to 1 with a new window.
- *
- * Memory Protection (DoS defense):
- * - JavaScript's Map preserves insertion order.
- * - By deleting and re-setting accessed keys, the Map functions as an LRU (Least Recently Used) cache.
- * - If the number of tracked IPs reaches `maxTrackedIps`, we evict the oldest entry.
- *   This ensures memory consumption is strictly bounded and cannot crash the Node.js process.
- */
-class RateLimiter {
-  /**
-   * @param {Object} options
-   * @param {number} [options.windowMs=60000] - Window length in milliseconds
-   * @param {number} [options.maxRequests=100] - Max allowed requests per window
-   * @param {number} [options.maxTrackedIps=10000] - Maximum unique IPs tracked in memory
-   */
-  constructor(options = {}) {
-    this.windowMs = options.windowMs || 60000;
-    this.maxRequests = options.maxRequests || 100;
-    this.maxTrackedIps = options.maxTrackedIps || 10000;
-
-    /** @type {Map<string, { count: number, resetTime: number }>} */
-    this.records = new Map();
-  }
-
-  /**
-   * Records an incoming request from an IP address.
-   *
-   * @param {string} ip - Client IP address
-   * @param {number} [now=Date.now()] - Current timestamp (injectable for testing)
-   * @returns {{ count: number, remaining: number, resetTime: number, isExceeded: boolean }}
-   */
-  record(ip, now = Date.now()) {
-    const cleanIp = normalizeIp(ip);
-
-    let entry = this.records.get(cleanIp);
-
-    // If an existing entry has expired, treat it as a fresh window
-    if (entry && now >= entry.resetTime) {
-      entry = null;
-    }
-
-    if (entry) {
-      // Existing active window: increment count
-      entry.count += 1;
-
-      // Refresh LRU order: delete and re-set so this IP is marked as most recently used
-      this.records.delete(cleanIp);
-      this.records.set(cleanIp, entry);
-    } else {
-      // New window or expired window: only evict if adding a NEW IP at capacity
-      if (!this.records.has(cleanIp) && this.records.size >= this.maxTrackedIps) {
-        this._evictOldest(now);
-      }
-
-      entry = {
-        count: 1,
-        resetTime: now + this.windowMs
-      };
-
-      // Delete first to ensure refreshed LRU order in Map
-      this.records.delete(cleanIp);
-      this.records.set(cleanIp, entry);
-    }
-
-    const remaining = Math.max(0, this.maxRequests - entry.count);
-    const isExceeded = entry.count > this.maxRequests;
-
-    return {
-      count: entry.count,
-      remaining,
-      resetTime: entry.resetTime,
-      isExceeded
-    };
-  }
-
-  /**
-   * Inspects current status for an IP without incrementing its counter.
-   *
-   * @param {string} ip
-   * @param {number} [now=Date.now()]
-   * @returns {{ count: number, remaining: number, resetTime: number, isExceeded: boolean }}
-   */
-  get(ip, now = Date.now()) {
-    const cleanIp = normalizeIp(ip);
-    const entry = this.records.get(cleanIp);
-
-    if (!entry || now >= entry.resetTime) {
-      return {
-        count: 0,
-        remaining: this.maxRequests,
-        resetTime: now + this.windowMs,
-        isExceeded: false
-      };
-    }
-
-    return {
-      count: entry.count,
-      remaining: Math.max(0, this.maxRequests - entry.count),
-      resetTime: entry.resetTime,
-      isExceeded: entry.count > this.maxRequests
-    };
-  }
-
-  /**
-   * Resets counter for a specific IP.
-   * @param {string} ip
-   */
-  reset(ip) {
-    const cleanIp = normalizeIp(ip);
-    this.records.delete(cleanIp);
-  }
-
-  /**
-   * Clears all tracked IP records from memory.
-   */
-  clear() {
-    this.records.clear();
-  }
-
-  /**
-   * Number of IPs currently stored in memory.
-   * @returns {number}
-   */
-  get size() {
-    return this.records.size;
-  }
-
-  /**
-   * Scans and removes any expired counters from memory.
-   * Because Map maintains insertion order, oldest entries are checked first.
-   *
-   * @param {number} [now=Date.now()]
-   * @returns {number} Count of removed expired entries
-   */
-  pruneExpired(now = Date.now()) {
-    let pruned = 0;
-    for (const [ip, entry] of this.records.entries()) {
-      if (now >= entry.resetTime) {
-        this.records.delete(ip);
-        pruned++;
-      }
-    }
-    return pruned;
-  }
-
-  /**
-   * Evicts the oldest entry to maintain bounded memory.
-   * Prefers to evict an expired entry first; if none are expired, evicts the LRU entry.
-   *
-   * @private
-   * @param {number} now
-   */
-  _evictOldest(now) {
-    const iterator = this.records.entries();
-    const first = iterator.next().value;
-
-    if (!first) {
-      return;
-    }
-
-    const [oldestIp, oldestEntry] = first;
-
-    // If oldest is already expired, delete it
-    if (now >= oldestEntry.resetTime) {
-      this.records.delete(oldestIp);
-      return;
-    }
-
-    // Otherwise evict least recently used entry to strictly uphold memory bound
-    this.records.delete(oldestIp);
-  }
-}
-
-module.exports = {
-  RateLimiter
-};