cipher-shield 1.0.0

package/src/core/blacklistMem.js

@@ -0,0 +1,510 @@
+/**
+ * In-Memory IP Blacklist Manager v2.1
+ *
+ * High-performance IP blacklist system with automatic expiry, cleanup,
+ * and threat intelligence tracking. Optimized for concurrent access
+ * patterns typical in web security middleware.
+ *
+ * Features:
+ * - Automatic entry expiration to prevent memory leaks
+ * - Background cleanup to maintain performance
+ * - Threat categorization and statistics
+ * - Memory-efficient data structures
+ * - Thread-safe operations for concurrent requests
+ *
+ * @module blacklistMem
+ * @version 1.0.0
+ * @author Omindu Dissanayaka
+ * @license MIT
+ */
+
+const EventEmitter = require('events');
+
+/**
+ * Default configuration constants with security limits
+ * @readonly
+ */
+const DEFAULT_CONFIG = Object.freeze({
+  BLACKLIST_EXPIRY: 3600000,
+  CLEANUP_INTERVAL: 300000,
+  MAX_ENTRIES: 10000,
+  MAX_ENTRIES_PER_IP: 5,
+  CLEANUP_BATCH_SIZE: 100,
+  ENTRY_SIZE_LIMIT: 1000
+});
+
+/**
+ * Blacklist entry structure
+ * @typedef {Object} BlacklistEntry
+ * @property {string} reason - Reason for blacklisting
+ * @property {number} timestamp - When the IP was blacklisted
+ * @property {number} hits - Number of times this IP triggered security
+ * @property {string} category - Threat category (e.g., 'ghost_route', 'ai_threat')
+ */
+
+/**
+ * Internal blacklist storage using Map for O(1) lookups with mutex protection
+ * @private
+ * @type {Map<string, BlacklistEntry>}
+ */
+const blacklist = new Map();
+
+/**
+ * Mutex for thread-safe operations
+ * @private
+ * @type {boolean}
+ */
+let blacklistMutex = false;
+
+/**
+ * Executes operation with mutex protection to prevent race conditions
+ * @private
+ * @param {Function} operation - Operation to execute safely
+ * @returns {*} Result of the operation
+ */
+function withMutex(operation) {
+  while (blacklistMutex) {
+  }
+
+  blacklistMutex = true;
+  try {
+    return operation();
+  } finally {
+    blacklistMutex = false;
+  }
+}
+
+/**
+ * Statistics tracking
+ * @private
+ */
+let stats = {
+  totalAdded: 0,
+  totalExpired: 0,
+  totalRemoved: 0,
+  peakSize: 0,
+  lastCleanup: Date.now()
+};
+
+/**
+ * Background cleanup timer
+ * @private
+ * @type {NodeJS.Timeout|null}
+ */
+let cleanupTimer = null;
+
+/**
+ * Event emitter for monitoring blacklist events
+ * @private
+ */
+const events = new EventEmitter();
+
+/**
+ * Starts the automatic background cleanup process
+ *
+ * Runs periodic cleanup to remove expired entries and maintain performance.
+ * Cleanup happens in batches to avoid blocking the event loop.
+ *
+ * @private
+ * @returns {void}
+ */
+function startBackgroundCleanup() {
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+  }
+
+  cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    const expired = [];
+    let processed = 0;
+
+    for (const [ip, entry] of blacklist.entries()) {
+      if (processed >= DEFAULT_CONFIG.CLEANUP_BATCH_SIZE) break;
+
+      if (now - entry.timestamp > DEFAULT_CONFIG.BLACKLIST_EXPIRY) {
+        expired.push(ip);
+        processed++;
+      }
+    }
+
+    expired.forEach(ip => {
+      blacklist.delete(ip);
+      stats.totalExpired++;
+    });
+
+    stats.lastCleanup = now;
+    stats.peakSize = Math.max(stats.peakSize, blacklist.size);
+
+    if (expired.length > 0 && process.env.NODE_ENV === 'development') {
+      console.log(`[BLACKLIST] Cleaned up ${expired.length} expired entries`);
+    }
+
+  }, DEFAULT_CONFIG.CLEANUP_INTERVAL);
+
+  cleanupTimer.unref();
+}
+
+/**
+ * Stops the background cleanup process
+ *
+ * @private
+ * @returns {void}
+ */
+function stopBackgroundCleanup() {
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}
+
+/**
+ * Initializes the blacklist system
+ *
+ * Sets up background cleanup and prepares the system for operation.
+ * Should be called during application startup.
+ *
+ * @function initialize
+ * @returns {void}
+ *
+ * @example
+ * ```javascript
+ * const blacklistMem = require('./blacklistMem');
+ * blacklistMem.initialize();
+ * ```
+ */
+function initialize() {
+  blacklist.clear();
+
+  stats = {
+    totalAdded: 0,
+    totalExpired: 0,
+    totalRemoved: 0,
+    peakSize: 0,
+    lastCleanup: Date.now()
+  };
+
+  startBackgroundCleanup();
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log('[BLACKLIST] Initialized with background cleanup');
+  }
+}
+
+/**
+ * Adds an IP address to the blacklist with reason tracking
+ *
+ * Automatically prevents duplicate entries and updates hit counts.
+ * Enforces maximum entry limits to prevent memory exhaustion.
+ *
+ * @function add
+ * @param {string} ip - IP address to blacklist
+ * @param {string} reason - Reason for blacklisting (e.g., 'ghost_route_access', 'ai_high_threat')
+ * @returns {boolean} True if IP was added/updated, false if at capacity limit
+ *
+ * @example
+ * ```javascript
+ * blacklistMem.add('192.168.1.100', 'ghost_route_access');
+ * blacklistMem.add('10.0.0.1', 'ai_high_threat');
+ * ```
+ */
+function add(ip, reason = 'unknown') {
+  return withMutex(() => {
+    if (!ip || typeof ip !== 'string') {
+      return false;
+    }
+
+    if (!isValidIP(ip)) {
+      return false;
+    }
+
+    const sanitizedReason = sanitizeReason(reason);
+
+    if (blacklist.size >= DEFAULT_CONFIG.MAX_ENTRIES) {
+      if (process.env.NODE_ENV === 'development') {
+        console.warn(`[BLACKLIST] At capacity limit (${DEFAULT_CONFIG.MAX_ENTRIES}), cannot add ${ip}`);
+      }
+      return false;
+    }
+
+    const now = Date.now();
+    const existing = blacklist.get(ip);
+
+    if (existing) {
+      if (existing.hits >= DEFAULT_CONFIG.MAX_ENTRIES_PER_IP) {
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(`[BLACKLIST] IP ${ip} has reached max entries (${DEFAULT_CONFIG.MAX_ENTRIES_PER_IP})`);
+        }
+        return false;
+      }
+
+      existing.hits = (existing.hits || 1) + 1;
+      existing.timestamp = now;
+      existing.lastReason = sanitizedReason;
+    } else {
+      blacklist.set(ip, {
+        reason: sanitizedReason,
+        timestamp: now,
+        hits: 1,
+        category: categorizeReason(sanitizedReason)
+      });
+
+      stats.totalAdded++;
+    }
+
+    events.emit('added', { ip, reason: sanitizedReason, existing: !!existing });
+
+    return true;
+  });
+}
+
+/**
+ * Validates IP address format
+ * @private
+ * @param {string} ip - IP address to validate
+ * @returns {boolean} True if valid IP format
+ */
+function isValidIP(ip) {
+  const ipv4Regex = /^(\d{1,3}\.){3}\d{1,3}$/;
+  return ipv4Regex.test(ip) || ip === 'unknown';
+}
+
+/**
+ * Sanitizes blacklist reason to prevent injection and limit size
+ * @private
+ * @param {string} reason - Raw reason string
+ * @returns {string} Sanitized reason
+ */
+function sanitizeReason(reason) {
+  if (!reason || typeof reason !== 'string') {
+    return 'unknown';
+  }
+
+  return reason.substring(0, DEFAULT_CONFIG.ENTRY_SIZE_LIMIT)
+               .replace(/[<>'"&]/g, '')
+               .trim();
+}
+
+/**
+ * Categorizes blacklist reasons for better threat intelligence
+ *
+ * @private
+ * @param {string} reason - The blacklist reason
+ * @returns {string} Threat category
+ */
+function categorizeReason(reason) {
+  if (reason.includes('ghost')) return 'ghost_route';
+  if (reason.includes('ai')) return 'ai_detected';
+  if (reason.includes('aes') || reason.includes('decrypt')) return 'encryption_attack';
+  if (reason.includes('shadow')) return 'timing_attack';
+  return 'other';
+}
+
+/**
+ * Checks if an IP address is currently blacklisted
+ *
+ * Performs automatic cleanup of expired entries during lookup.
+ * This lazy cleanup approach minimizes background processing.
+ *
+ * @function isBlacklisted
+ * @param {string} ip - IP address to check
+ * @returns {boolean} True if IP is blacklisted and not expired
+ *
+ * @example
+ * ```javascript
+ * if (blacklistMem.isBlacklisted('192.168.1.100')) {
+ *   // Apply shadow ban or blocking
+ * }
+ * ```
+ */
+function isBlacklisted(ip) {
+  return withMutex(() => {
+    if (!ip || !blacklist.has(ip)) {
+      return false;
+    }
+
+    const entry = blacklist.get(ip);
+    const age = Date.now() - entry.timestamp;
+
+    if (age > DEFAULT_CONFIG.BLACKLIST_EXPIRY) {
+      blacklist.delete(ip);
+      stats.totalExpired++;
+
+      if (process.env.NODE_ENV === 'development') {
+        console.log(`[BLACKLIST] Expired entry removed: ${ip}`);
+      }
+
+      return false;
+    }
+
+    return true;
+  });
+}
+
+/**
+ * Removes an IP address from the blacklist
+ *
+ * @function remove
+ * @param {string} ip - IP address to remove
+ * @returns {boolean} True if IP was removed, false if not found
+ *
+ * @example
+ * ```javascript
+ * const removed = blacklistMem.remove('192.168.1.100');
+ * console.log(removed ? 'IP removed' : 'IP not found');
+ * ```
+ */
+function remove(ip) {
+  const existed = blacklist.delete(ip);
+
+  if (existed) {
+    stats.totalRemoved++;
+    events.emit('removed', { ip });
+  }
+
+  return existed;
+}
+
+/**
+ * Retrieves all current blacklist entries
+ *
+ * Returns a snapshot of current entries with metadata.
+ * Note: This creates a new array, so avoid calling frequently in hot paths.
+ *
+ * @function getAll
+ * @returns {Array<BlacklistEntry & {ip: string}>} Array of blacklist entries
+ *
+ * @example
+ * ```javascript
+ * const entries = blacklistMem.getAll();
+ * console.log(`Blacklisted IPs: ${entries.length}`);
+ * ```
+ */
+function getAll() {
+  const result = [];
+
+  for (const [ip, entry] of blacklist.entries()) {
+    result.push({
+      ip,
+      ...entry
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Retrieves detailed statistics about blacklist operations
+ *
+ * @function getStats
+ * @returns {Object} Blacklist statistics
+ * @property {number} size - Current number of entries
+ * @property {number} totalAdded - Total IPs ever added
+ * @property {number} totalExpired - Total IPs expired
+ * @property {number} totalRemoved - Total IPs manually removed
+ * @property {number} peakSize - Maximum size reached
+ * @property {number} lastCleanup - Timestamp of last cleanup
+ *
+ * @example
+ * ```javascript
+ * const stats = blacklistMem.getStats();
+ * console.log(`Current size: ${stats.size}, Peak: ${stats.peakSize}`);
+ * ```
+ */
+function getStats() {
+  return {
+    size: blacklist.size,
+    ...stats,
+    config: DEFAULT_CONFIG
+  };
+}
+
+/**
+ * Clears all blacklist entries
+ *
+ * Emergency function to reset the blacklist. Use with caution.
+ *
+ * @function clear
+ * @returns {number} Number of entries cleared
+ *
+ * @example
+ * ```javascript
+ * const cleared = blacklistMem.clear();
+ * console.log(`Cleared ${cleared} entries`);
+ * ```
+ */
+function clear() {
+  const previousSize = blacklist.size;
+  blacklist.clear();
+
+  stats.peakSize = 0;
+  stats.lastCleanup = Date.now();
+
+  events.emit('cleared', { previousSize });
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[BLACKLIST] Cleared ${previousSize} entries`);
+  }
+
+  return previousSize;
+}
+
+/**
+ * Gets the current number of blacklisted IPs
+ *
+ * More efficient than getAll().length for size checks.
+ *
+ * @function size
+ * @returns {number} Current blacklist size
+ */
+function size() {
+  return blacklist.size;
+}
+
+/**
+ * Checks if the blacklist contains a specific IP
+ *
+ * Similar to isBlacklisted() but doesn't perform expiry checks.
+ *
+ * @function has
+ * @param {string} ip - IP address to check
+ * @returns {boolean} True if IP exists in blacklist (may be expired)
+ */
+function has(ip) {
+  return blacklist.has(ip);
+}
+
+/**
+ * Gets detailed information about a specific blacklisted IP
+ *
+ * @function getEntry
+ * @param {string} ip - IP address to query
+ * @returns {BlacklistEntry|null} Entry details or null if not found/expired
+ */
+function getEntry(ip) {
+  if (!isBlacklisted(ip)) {
+    return null;
+  }
+
+  return { ...blacklist.get(ip) };
+}
+
+initialize();
+
+process.on('exit', stopBackgroundCleanup);
+process.on('SIGINT', stopBackgroundCleanup);
+process.on('SIGTERM', stopBackgroundCleanup);
+
+module.exports = {
+  initialize,
+  add,
+  isBlacklisted,
+  remove,
+  getAll,
+  getStats,
+  clear,
+  size,
+  has,
+  getEntry,
+  events, // For advanced monitoring
+  DEFAULT_CONFIG
+};