z-shield 0.1.0 → 0.1.2

package/src/config.js

@@ -1,165 +0,0 @@
-'use strict';
-
-const path = require('node:path');
-
-/**
- * Default configuration values for Z-Shield.
- * Designed with conservative, safe defaults.
- */
-const DEFAULT_CONFIG = {
-  // Unique identifier for the host application (useful when multiple apps share a server)
-  appName: 'default-app',
-
-  // Mode: 'monitor' (detect and log only) or 'protect' (enforce 429 and temporary blocks)
-  mode: 'monitor',
-
-  // Time window for tracking requests in milliseconds (default: 60,000ms = 1 minute)
-  windowMs: 60 * 1000,
-
-  // Maximum allowed requests from a single IP within the windowMs
-  maxRequests: 100,
-
-  // Directory where JSONL security event logs will be stored
-  logDir: path.resolve(process.cwd(), '.z-shield-logs'),
-
-  // Whether to trust reverse-proxy IP headers (e.g., X-Forwarded-For)
-  // CRITICAL: Must be false by default to prevent client IP spoofing attacks
-  trustProxy: false,
-
-  // Array of route prefixes that bypass abuse tracking (e.g. internal health checks)
-  excludeRoutes: ['/health', '/favicon.ico'],
-
-  // Maximum number of distinct client IPs to track in memory simultaneously
-  // Protects against Memory Exhaustion DoS attacks
-  maxTrackedIps: 10000,
-
-  // Duration in milliseconds for temporary IP blocks (default: 15 minutes)
-  blockDurationMs: 15 * 60 * 1000,
-
-  // Maximum number of blocked IPs to keep in memory simultaneously
-  maxBlockedIps: 5000,
-
-  // Whether exceeding rate limit in protect mode automatically triggers a temporary block
-  autoBlock: false,
-
-  // Filename for the active JSON Lines log file
-  logFilename: 'events.jsonl',
-
-  // Maximum size in bytes before rotating the log file (default: 5MB)
-  maxLogSizeBytes: 5 * 1024 * 1024,
-
-  // Maximum number of rotated log files to retain
-  maxLogFiles: 5,
-
-  // Optional custom error callback: (err, event) => void
-  onLogError: null
-};
-
-/**
- * Validates user-provided options and merges them with defaults.
- * Throws clear, helpful errors if an invalid option is passed.
- *
- * @param {Object} [userConfig={}] - Custom configuration provided by the developer
- * @returns {Readonly<Object>} Validated and frozen configuration object
- */
-function resolveConfig(userConfig = {}) {
-  if (userConfig === null || typeof userConfig !== 'object' || Array.isArray(userConfig)) {
-    throw new TypeError('[Z-Shield] Configuration must be a plain object.');
-  }
-
-  const config = { ...DEFAULT_CONFIG, ...userConfig };
-
-  // Validate appName
-  if (typeof config.appName !== 'string' || config.appName.trim().length === 0) {
-    throw new TypeError('[Z-Shield] "appName" must be a non-empty string.');
-  }
-  // Prevent directory traversal characters in appName (e.g., "../hacker")
-  if (!/^[a-zA-Z0-9_-]+$/.test(config.appName)) {
-    throw new Error('[Z-Shield] "appName" can only contain letters, numbers, dashes, and underscores.');
-  }
-
-  // Validate mode
-  if (config.mode !== 'monitor' && config.mode !== 'protect') {
-    throw new Error(`[Z-Shield] Invalid mode "${config.mode}". Mode must be either "monitor" or "protect".`);
-  }
-
-  // Validate windowMs
-  if (typeof config.windowMs !== 'number' || !Number.isFinite(config.windowMs) || config.windowMs <= 0) {
-    throw new TypeError('[Z-Shield] "windowMs" must be a positive number in milliseconds.');
-  }
-
-  // Validate maxRequests
-  if (typeof config.maxRequests !== 'number' || !Number.isInteger(config.maxRequests) || config.maxRequests <= 0) {
-    throw new TypeError('[Z-Shield] "maxRequests" must be a positive integer.');
-  }
-
-  // Validate logDir
-  if (typeof config.logDir !== 'string' || config.logDir.trim().length === 0) {
-    throw new TypeError('[Z-Shield] "logDir" must be a non-empty string path.');
-  }
-
-  // Validate trustProxy
-  if (typeof config.trustProxy !== 'boolean') {
-    throw new TypeError('[Z-Shield] "trustProxy" must be a boolean (true or false).');
-  }
-
-  // Validate excludeRoutes
-  if (!Array.isArray(config.excludeRoutes) || !config.excludeRoutes.every(r => typeof r === 'string')) {
-    throw new TypeError('[Z-Shield] "excludeRoutes" must be an array of string route prefixes.');
-  }
-
-  // Validate maxTrackedIps
-  if (typeof config.maxTrackedIps !== 'number' || !Number.isInteger(config.maxTrackedIps) || config.maxTrackedIps <= 0) {
-    throw new TypeError('[Z-Shield] "maxTrackedIps" must be a positive integer.');
-  }
-
-  // Validate blockDurationMs
-  if (typeof config.blockDurationMs !== 'number' || !Number.isFinite(config.blockDurationMs) || config.blockDurationMs <= 0) {
-    throw new TypeError('[Z-Shield] "blockDurationMs" must be a positive number in milliseconds.');
-  }
-
-  // Validate maxBlockedIps
-  if (typeof config.maxBlockedIps !== 'number' || !Number.isInteger(config.maxBlockedIps) || config.maxBlockedIps <= 0) {
-    throw new TypeError('[Z-Shield] "maxBlockedIps" must be a positive integer.');
-  }
-
-  // Validate autoBlock
-  if (typeof config.autoBlock !== 'boolean') {
-    throw new TypeError('[Z-Shield] "autoBlock" must be a boolean (true or false).');
-  }
-
-  // Validate logFilename
-  if (typeof config.logFilename !== 'string' || config.logFilename.trim().length === 0) {
-    throw new TypeError('[Z-Shield] "logFilename" must be a non-empty string.');
-  }
-  if (!/^[a-zA-Z0-9._-]+$/.test(config.logFilename) || config.logFilename.includes('..')) {
-    throw new Error('[Z-Shield] "logFilename" must be a safe filename without path traversal characters.');
-  }
-
-  // Validate maxLogSizeBytes
-  if (typeof config.maxLogSizeBytes !== 'number' || !Number.isInteger(config.maxLogSizeBytes) || config.maxLogSizeBytes <= 0) {
-    throw new TypeError('[Z-Shield] "maxLogSizeBytes" must be a positive integer.');
-  }
-
-  // Validate maxLogFiles
-  if (typeof config.maxLogFiles !== 'number' || !Number.isInteger(config.maxLogFiles) || config.maxLogFiles < 0) {
-    throw new TypeError('[Z-Shield] "maxLogFiles" must be a non-negative integer.');
-  }
-
-  // Validate onLogError
-  if (config.onLogError !== null && typeof config.onLogError !== 'function') {
-    throw new TypeError('[Z-Shield] "onLogError" must be null or a function.');
-  }
-
-  // Freeze the object so application code cannot accidentally mutate it at runtime
-  return Object.freeze({
-    ...config,
-    logDir: path.resolve(config.logDir),
-    excludeRoutes: Object.freeze([...config.excludeRoutes])
-  });
-}
-
-module.exports = {
-  DEFAULT_CONFIG,
-  resolveConfig
-};

package/src/detector.js

@@ -1,88 +0,0 @@
-'use strict';
-
-/**
- * Detector - Evaluates incoming requests and detects abuse patterns.
- *
- * In Phase 2, this evaluates whether a client IP has exceeded the
- * maximum request threshold within the configured time window.
- */
-class Detector {
-  /**
-   * @param {Object} options
-   * @param {import('./rate-limiter').RateLimiter} options.rateLimiter - The rate-limiter instance
-   * @param {Object} options.config - The resolved Z-Shield configuration
-   */
-  constructor({ rateLimiter, config }) {
-    if (!rateLimiter) {
-      throw new TypeError('[Z-Shield] Detector requires a RateLimiter instance.');
-    }
-    if (!config) {
-      throw new TypeError('[Z-Shield] Detector requires a resolved config object.');
-    }
-
-    this.rateLimiter = rateLimiter;
-    this.config = config;
-  }
-
-  /**
-   * Checks an incoming request against detection rules.
-   *
-   * @param {string} ip - Client IP address
-   * @param {import('express').Request} [req={}] - Express request object
-   * @param {number} [now=Date.now()] - Timestamp
-   * @returns {Object} Detection evaluation result
-   */
-  check(ip, req = {}, now = Date.now()) {
-    const status = this.rateLimiter.record(ip, now);
-
-    if (status.isExceeded) {
-      const windowSeconds = Math.round(this.config.windowMs / 1000);
-      return {
-        isSuspicious: true,
-        type: 'rate_limit',
-        severity: 'warning',
-        reason: `Request threshold exceeded (${status.count}/${this.config.maxRequests} in ${windowSeconds}s)`,
-        count: status.count,
-        maxRequests: this.config.maxRequests,
-        remaining: status.remaining,
-        resetTime: status.resetTime,
-        timestamp: new Date(now).toISOString()
-      };
-    }
-
-    return {
-      isSuspicious: false,
-      type: 'normal',
-      severity: 'info',
-      reason: null,
-      count: status.count,
-      maxRequests: this.config.maxRequests,
-      remaining: status.remaining,
-      resetTime: status.resetTime,
-      timestamp: new Date(now).toISOString()
-    };
-  }
-
-  /**
-   * Inspects current status without incrementing counters.
-   *
-   * @param {string} ip
-   * @param {number} [now=Date.now()]
-   * @returns {Object}
-   */
-  inspect(ip, now = Date.now()) {
-    const status = this.rateLimiter.get(ip, now);
-
-    return {
-      isSuspicious: status.isExceeded,
-      count: status.count,
-      maxRequests: this.config.maxRequests,
-      remaining: status.remaining,
-      resetTime: status.resetTime
-    };
-  }
-}
-
-module.exports = {
-  Detector
-};

package/src/index.js

@@ -1,97 +0,0 @@
-'use strict';
-
-const { createMiddleware } = require('./middleware');
-const { resolveConfig, DEFAULT_CONFIG } = require('./config');
-const { RateLimiter } = require('./rate-limiter');
-const { Detector } = require('./detector');
-const { BlockManager } = require('./block-manager');
-const { Logger } = require('./logger');
-
-/**
- * Main factory function for initializing Z-Shield.
- *
- * Usage in Express:
- *   const { createShield } = require('z-shield');
- *   const shield = createShield({ mode: 'protect', maxRequests: 50 });
- *   app.use(shield.middleware);
- *
- * Programmatic Block API:
- *   shield.block('198.51.100.1', '10m', 'Manual administrative block');
- *   shield.unblock('198.51.100.1');
- *   shield.isBlocked('198.51.100.1');
- *
- * @param {Object} [options={}] - Custom configuration options
- * @returns {Object} Z-Shield instance with middleware, managers, logger, and programmatic methods
- */
-function createShield(options = {}) {
-  const config = resolveConfig(options);
-  const rateLimiter = new RateLimiter(config);
-  const detector = new Detector({ rateLimiter, config });
-  const blockManager = new BlockManager(config);
-  const logger = new Logger(config);
-
-  const middleware = createMiddleware(config, {
-    rateLimiter,
-    detector,
-    blockManager,
-    logger
-  });
-
-  return {
-    middleware,
-    config,
-    rateLimiter,
-    detector,
-    blockManager,
-    logger,
-
-    // Programmatic Block API with security event logging
-    block: (ip, duration, reason) => {
-      const result = blockManager.block(ip, duration, reason);
-      logger.log({
-        appName: config.appName,
-        type: 'manual_block',
-        severity: 'info',
-        ip,
-        method: 'INTERNAL',
-        route: '/admin/block',
-        reason: result.reason,
-        action: 'blocked'
-      });
-      return result;
-    },
-
-    unblock: (ip) => {
-      const result = blockManager.unblock(ip);
-      if (result) {
-        logger.log({
-          appName: config.appName,
-          type: 'manual_unblock',
-          severity: 'info',
-          ip,
-          method: 'INTERNAL',
-          route: '/admin/unblock',
-          reason: 'Manual unblock requested',
-          action: 'unblocked'
-        });
-      }
-      return result;
-    },
-
-    isBlocked: (ip) => blockManager.isBlocked(ip),
-    getBlockInfo: (ip) => blockManager.getBlockInfo(ip),
-    listBlocks: () => blockManager.listBlocks(),
-    flush: () => logger.flush()
-  };
-}
-
-module.exports = {
-  createShield,
-  createMiddleware,
-  resolveConfig,
-  DEFAULT_CONFIG,
-  RateLimiter,
-  Detector,
-  BlockManager,
-  Logger
-};

package/src/logger.js

@@ -1,279 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-/**
- * Strips ANSI terminal escape codes from untrusted strings to prevent terminal injection.
- * @param {string} str
- * @returns {string}
- */
-function stripAnsi(str) {
-  // Matches standard ANSI color and control escape sequences
-  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-}
-
-/**
- * Sanitizes an untrusted string to prevent Log Injection (CWE-117).
- * - Strips ANSI escapes
- * - Strips control characters (newlines \r, \n, null bytes, backspaces, tabs)
- * - Truncates to maxLength to prevent disk space exhaustion
- *
- * @param {*} val
- * @param {number} [maxLength=250]
- * @returns {string}
- */
-function sanitizeString(val, maxLength = 250) {
-  if (val === null || val === undefined) {
-    return '';
-  }
-  let str = String(val);
-  str = stripAnsi(str);
-  // Replace control characters (ASCII 0-31, 127) with a clean space
-  str = str.replace(/[\x00-\x1f\x7f]/g, ' ').trim();
-  // Collapse consecutive spaces
-  str = str.replace(/\s+/g, ' ');
-  return str.slice(0, maxLength);
-}
-
-/**
- * Sanitizes HTTP route paths.
- * @param {*} route
- * @param {number} [maxLength=500]
- * @returns {string}
- */
-function sanitizeRoute(route, maxLength = 500) {
-  if (!route || typeof route !== 'string') {
-    return '/';
-  }
-  let clean = stripAnsi(route);
-  // Strip query parameters and URL fragments to prevent credential leakage (CWE-532)
-  clean = clean.split('?')[0].split('#')[0];
-  // Remove dangerous control characters and newlines
-  clean = clean.replace(/[\x00-\x1f\x7f]/g, '');
-  if (!clean.startsWith('/')) {
-    clean = '/' + clean;
-  }
-  return clean.slice(0, maxLength);
-}
-
-/**
- * Sanitizes HTTP methods.
- * @param {*} method
- * @returns {string}
- */
-function sanitizeMethod(method) {
-  if (!method || typeof method !== 'string') {
-    return 'GET';
-  }
-  const clean = method.toUpperCase().replace(/[^A-Z]/g, '');
-  return clean.slice(0, 10) || 'GET';
-}
-
-/**
- * Logger - Safe, Persistent Local JSON Lines Security Event Logger
- *
- * Design Features:
- * - JSON Lines (.jsonl): Every event is on exactly one line ending in \n.
- * - Non-Blocking & Asynchronous: Uses node:fs/promises without blocking the event loop.
- * - Strict Sanitization: Eliminates Log Injection (CWE-117) by stripping newlines and ANSI escapes.
- * - Privacy-Preserving: Never logs passwords, cookies, authorization headers, or request bodies (CWE-532).
- * - Bounded Storage: Automatic log rotation and retention limits prevent disk space exhaustion.
- * - Resilient: Filesystem errors (ENOSPC, EACCES) are safely caught and will not crash the host app.
- * - Sequential Queue: Guarantees concurrency safety so simultaneous writes never corrupt files.
- *
- * Hosting Notice:
- * Logs are stored in local persistent storage. If deployed to ephemeral platforms
- * (e.g. basic Heroku dynos, AWS Lambda, or serverless containers without mounted volumes),
- * local log files may be lost upon container restart or redeployment.
- */
-class Logger {
-  /**
-   * @param {Object} [config={}] - Resolved Z-Shield configuration
-   */
-  constructor(config = {}) {
-    this.appName = config.appName || 'default-app';
-    this.logDir = path.resolve(config.logDir || path.join(process.cwd(), '.z-shield-logs'));
-    this.logFilename = config.logFilename || 'events.jsonl';
-    this.filePath = path.join(this.logDir, this.logFilename);
-    this.maxLogSizeBytes = config.maxLogSizeBytes || 5 * 1024 * 1024; // 5MB
-    this.maxLogFiles = typeof config.maxLogFiles === 'number' ? config.maxLogFiles : 5;
-    this.onLogError = typeof config.onLogError === 'function' ? config.onLogError : null;
-
-    this._writeQueue = Promise.resolve();
-    this._dirEnsured = false;
-  }
-
-  /**
-   * Formats and sanitizes a security event into a validated schema.
-   * Deliberately omits request bodies, authorization headers, cookies, and tokens.
-   *
-   * @param {Object} rawEvent
-   * @returns {Object} Validated security event
-   */
-  formatEvent(rawEvent = {}) {
-    const now = rawEvent.timestamp ? new Date(rawEvent.timestamp) : new Date();
-    const timestamp = isNaN(now.getTime()) ? new Date().toISOString() : now.toISOString();
-
-    const allowedSeverities = ['info', 'warning', 'critical'];
-    const severity = allowedSeverities.includes(rawEvent.severity) ? rawEvent.severity : 'warning';
-
-    const allowedActions = ['blocked', 'warned', 'allowed', 'unblocked'];
-    const action = allowedActions.includes(rawEvent.action) ? rawEvent.action : 'warned';
-
-    return {
-      timestamp,
-      appName: sanitizeString(rawEvent.appName || this.appName, 50),
-      type: sanitizeString(rawEvent.type || 'security_event', 30),
-      severity,
-      ip: sanitizeString(rawEvent.ip || 'unknown', 45),
-      method: sanitizeMethod(rawEvent.method),
-      route: sanitizeRoute(rawEvent.route),
-      reason: sanitizeString(rawEvent.reason || 'Unspecified security event', 300),
-      action
-    };
-  }
-
-  /**
-   * Safely logs a security event asynchronously.
-   * Resolves to true if write succeeded, or false if it failed.
-   *
-   * @param {Object} rawEvent
-   * @returns {Promise<boolean>}
-   */
-  log(rawEvent) {
-    return new Promise((resolve) => {
-      this._writeQueue = this._writeQueue
-        .then(() => this._writeEvent(rawEvent))
-        .then(() => resolve(true))
-        .catch((err) => {
-          this._handleError(err, rawEvent);
-          resolve(false);
-        });
-    });
-  }
-
-  /**
-   * Waits for all currently queued asynchronous log writes to complete.
-   * Useful for deterministic testing, graceful shutdowns, and process exit handlers.
-   *
-   * @returns {Promise<void>}
-   */
-  async flush() {
-    await this._writeQueue;
-  }
-
-  /**
-   * Internal write operation executed within the sequential queue.
-   *
-   * @private
-   * @param {Object} rawEvent
-   */
-  async _writeEvent(rawEvent) {
-    const event = this.formatEvent(rawEvent);
-    await this._ensureDir();
-    await this._rotateIfNeeded();
-
-    const line = JSON.stringify(event) + '\n';
-    await fs.promises.appendFile(this.filePath, line, { encoding: 'utf8', flag: 'a' });
-  }
-
-  /**
-   * Ensures the target log directory exists.
-   * @private
-   */
-  async _ensureDir() {
-    if (!this._dirEnsured) {
-      await fs.promises.mkdir(this.logDir, { recursive: true });
-      this._dirEnsured = true;
-    }
-  }
-
-  /**
-   * Checks file size and rotates log files if size exceeds maxLogSizeBytes.
-   * @private
-   */
-  async _rotateIfNeeded() {
-    try {
-      const stats = await fs.promises.stat(this.filePath);
-      if (stats.size < this.maxLogSizeBytes) {
-        return;
-      }
-    } catch (err) {
-      if (err.code === 'ENOENT') {
-        return; // File does not exist yet
-      }
-      throw err;
-    }
-
-    const { name, ext } = path.parse(this.logFilename);
-
-    // If maxLogFiles is 0, simply remove the current file
-    if (this.maxLogFiles === 0) {
-      try {
-        await fs.promises.unlink(this.filePath);
-      } catch (err) {
-        if (err.code !== 'ENOENT') throw err;
-      }
-      return;
-    }
-
-    // Shift existing rotated files:
-    // e.g. events.5.jsonl deleted (retention limit)
-    // events.4.jsonl -> events.5.jsonl
-    // events.1.jsonl -> events.2.jsonl
-    for (let i = this.maxLogFiles; i >= 1; i--) {
-      const currentRotated = path.join(this.logDir, `${name}.${i}${ext}`);
-      if (i === this.maxLogFiles) {
-        try {
-          await fs.promises.unlink(currentRotated);
-        } catch (err) {
-          if (err.code !== 'ENOENT') throw err;
-        }
-      } else {
-        const nextRotated = path.join(this.logDir, `${name}.${i + 1}${ext}`);
-        try {
-          await fs.promises.rename(currentRotated, nextRotated);
-        } catch (err) {
-          if (err.code !== 'ENOENT') throw err;
-        }
-      }
-    }
-
-    // Move current events.jsonl to events.1.jsonl
-    const firstRotated = path.join(this.logDir, `${name}.1${ext}`);
-    try {
-      await fs.promises.rename(this.filePath, firstRotated);
-    } catch (err) {
-      if (err.code !== 'ENOENT') throw err;
-    }
-  }
-
-  /**
-   * Safely handles write and filesystem failures without crashing the application.
-   *
-   * @private
-   * @param {Error} err
-   * @param {Object} rawEvent
-   */
-  _handleError(err, rawEvent) {
-    if (this.onLogError) {
-      try {
-        this.onLogError(err, rawEvent);
-      } catch {
-        // Prevent errors in the user's callback from crashing the app
-      }
-    } else {
-      // Print clear, non-fatal warning to stderr
-      console.error(`[Z-Shield Logger Warning]: Failed to write security event log: ${err.message}`);
-    }
-  }
-}
-
-module.exports = {
-  Logger,
-  sanitizeString,
-  sanitizeRoute,
-  sanitizeMethod,
-  stripAnsi
-};