z-shield 0.1.0 → 0.1.2

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNextClientIp = exports.withNextShield = exports.createNextShield = exports.sanitizeMethod = exports.sanitizeRoute = exports.sanitizeString = exports.stripAnsi = exports.Logger = exports.parseDuration = exports.canonicalizeIpv6 = exports.normalizeIp = exports.isValidIp = exports.BlockManager = exports.Detector = exports.RateLimiter = exports.DEFAULT_CONFIG = exports.resolveConfig = exports.safelyEndResponse = exports.isRouteExcluded = exports.extractClientIp = exports.createMiddleware = void 0;
+exports.createShield = createShield;
+const middleware_1 = require("./middleware");
+Object.defineProperty(exports, "createMiddleware", { enumerable: true, get: function () { return middleware_1.createMiddleware; } });
+Object.defineProperty(exports, "extractClientIp", { enumerable: true, get: function () { return middleware_1.extractClientIp; } });
+Object.defineProperty(exports, "isRouteExcluded", { enumerable: true, get: function () { return middleware_1.isRouteExcluded; } });
+Object.defineProperty(exports, "safelyEndResponse", { enumerable: true, get: function () { return middleware_1.safelyEndResponse; } });
+const next_1 = require("./next");
+Object.defineProperty(exports, "createNextShield", { enumerable: true, get: function () { return next_1.createNextShield; } });
+Object.defineProperty(exports, "withNextShield", { enumerable: true, get: function () { return next_1.withNextShield; } });
+Object.defineProperty(exports, "extractNextClientIp", { enumerable: true, get: function () { return next_1.extractNextClientIp; } });
+const config_1 = require("./config");
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_CONFIG; } });
+const rate_limiter_1 = require("./rate-limiter");
+Object.defineProperty(exports, "RateLimiter", { enumerable: true, get: function () { return rate_limiter_1.RateLimiter; } });
+const detector_1 = require("./detector");
+Object.defineProperty(exports, "Detector", { enumerable: true, get: function () { return detector_1.Detector; } });
+const block_manager_1 = require("./block-manager");
+Object.defineProperty(exports, "BlockManager", { enumerable: true, get: function () { return block_manager_1.BlockManager; } });
+Object.defineProperty(exports, "isValidIp", { enumerable: true, get: function () { return block_manager_1.isValidIp; } });
+Object.defineProperty(exports, "normalizeIp", { enumerable: true, get: function () { return block_manager_1.normalizeIp; } });
+Object.defineProperty(exports, "canonicalizeIpv6", { enumerable: true, get: function () { return block_manager_1.canonicalizeIpv6; } });
+Object.defineProperty(exports, "parseDuration", { enumerable: true, get: function () { return block_manager_1.parseDuration; } });
+const logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+Object.defineProperty(exports, "stripAnsi", { enumerable: true, get: function () { return logger_1.stripAnsi; } });
+Object.defineProperty(exports, "sanitizeString", { enumerable: true, get: function () { return logger_1.sanitizeString; } });
+Object.defineProperty(exports, "sanitizeRoute", { enumerable: true, get: function () { return logger_1.sanitizeRoute; } });
+Object.defineProperty(exports, "sanitizeMethod", { enumerable: true, get: function () { return logger_1.sanitizeMethod; } });
+/**
+ * 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 options - Custom configuration options
+ * @returns Z-Shield instance with middleware, managers, logger, and programmatic methods
+ */
+function createShield(options = {}) {
+    const config = (0, config_1.resolveConfig)(options);
+    const rateLimiter = new rate_limiter_1.RateLimiter(config);
+    const detector = new detector_1.Detector({ rateLimiter, config });
+    const blockManager = new block_manager_1.BlockManager(config);
+    const logger = new logger_1.Logger(config);
+    const middleware = (0, middleware_1.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);
+            void 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) {
+                void 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()
+    };
+}
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,6CAAqG;iGAA5F,6BAAgB;gGAAE,4BAAe;gGAAE,4BAAe;kGAAE,8BAAiB;AAC9E,iCAA+E;iGAAtE,uBAAgB;+FAAE,qBAAc;oGAAE,0BAAmB;AAC9D,qCAAyD;8FAAhD,sBAAa;+FAAE,uBAAc;AACtC,iDAA6C;4FAApC,0BAAW;AACpB,yCAAsC;yFAA7B,mBAAQ;AACjB,mDAAwH;6FAA/G,4BAAY;0FAAE,yBAAS;4FAAE,2BAAW;iGAAE,gCAAgB;8FAAE,6BAAa;AAC9E,qCAA4F;uFAAnF,eAAM;0FAAE,kBAAS;+FAAE,uBAAc;8FAAE,sBAAa;+FAAE,uBAAc;AASzE;;;;;;;;;;;;;;;GAeG;AACH,sBAA6B,OAAO,GAAmC,EAAE;IACvE,MAAM,MAAM,GAAG,IAAA,sBAAa,EAAC,OAAO,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,IAAI,0BAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,mBAAQ,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,4BAAY,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,MAAM,CAAC,CAAC;IAElC,MAAM,UAAU,GAAG,IAAA,6BAAgB,EAAC,MAAM,EAAE;QAC1C,WAAW;QACX,QAAQ;QACR,YAAY;QACZ,MAAM;KACP,CAAC,CAAC;IAEH,OAAO;QACL,UAAU;QACV,MAAM;QACN,WAAW;QACX,QAAQ;QACR,YAAY;QACZ,MAAM;QAEN,qDAAqD;QACrD,KAAK,EAAE,CAAC,EAAU,EAAE,QAA0B,EAAE,MAAe,EAAe,EAAE;YAC9E,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YACxD,KAAK,MAAM,CAAC,GAAG,CAAC;gBACd,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,MAAM;gBAChB,EAAE;gBACF,MAAM,EAAE,UAAU;gBAClB,KAAK,EAAE,cAAc;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,OAAO,EAAE,CAAC,EAAU,EAAW,EAAE;YAC/B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,MAAM,CAAC,GAAG,CAAC;oBACd,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,IAAI,EAAE,gBAAgB;oBACtB,QAAQ,EAAE,MAAM;oBAChB,EAAE;oBACF,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,gBAAgB;oBACvB,MAAM,EAAE,0BAA0B;oBAClC,MAAM,EAAE,WAAW;iBACpB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,SAAS,EAAE,CAAC,EAAU,EAAW,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9D,YAAY,EAAE,CAAC,EAAU,EAAoB,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7E,UAAU,EAAE,GAAgB,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE;QACxD,KAAK,EAAE,GAAkB,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC3C,CAAC;AACJ,CAAC;AA2BD,0CAAwB","sourcesContent":["import { createMiddleware, extractClientIp, isRouteExcluded, safelyEndResponse } from './middleware';\nimport { createNextShield, withNextShield, extractNextClientIp } from './next';\nimport { resolveConfig, DEFAULT_CONFIG } from './config';\nimport { RateLimiter } from './rate-limiter';\nimport { Detector } from './detector';\nimport { BlockManager, isValidIp, normalizeIp, canonicalizeIpv6, parseDuration, type BlockInfo } from './block-manager';\nimport { Logger, stripAnsi, sanitizeString, sanitizeRoute, sanitizeMethod } from './logger';\nimport type {\n  ZShieldConfig,\n  ZShieldOptions,\n  BlockRecord,\n  ZShieldInstance,\n  ZShieldFullInstance\n} from './types';\n\n/**\n * Main factory function for initializing Z-Shield.\n *\n * Usage in Express:\n *   const { createShield } = require('z-shield');\n *   const shield = createShield({ mode: 'protect', maxRequests: 50 });\n *   app.use(shield.middleware);\n *\n * Programmatic Block API:\n *   shield.block('198.51.100.1', '10m', 'Manual administrative block');\n *   shield.unblock('198.51.100.1');\n *   shield.isBlocked('198.51.100.1');\n *\n * @param options - Custom configuration options\n * @returns Z-Shield instance with middleware, managers, logger, and programmatic methods\n */\nexport function createShield(options: ZShieldOptions | ZShieldConfig = {}): ZShieldInstance {\n  const config = resolveConfig(options);\n  const rateLimiter = new RateLimiter(config);\n  const detector = new Detector({ rateLimiter, config });\n  const blockManager = new BlockManager(config);\n  const logger = new Logger(config);\n\n  const middleware = createMiddleware(config, {\n    rateLimiter,\n    detector,\n    blockManager,\n    logger\n  });\n\n  return {\n    middleware,\n    config,\n    rateLimiter,\n    detector,\n    blockManager,\n    logger,\n\n    // Programmatic Block API with security event logging\n    block: (ip: string, duration?: string | number, reason?: string): BlockRecord => {\n      const result = blockManager.block(ip, duration, reason);\n      void logger.log({\n        appName: config.appName,\n        type: 'manual_block',\n        severity: 'info',\n        ip,\n        method: 'INTERNAL',\n        route: '/admin/block',\n        reason: result.reason,\n        action: 'blocked'\n      });\n      return result;\n    },\n\n    unblock: (ip: string): boolean => {\n      const result = blockManager.unblock(ip);\n      if (result) {\n        void logger.log({\n          appName: config.appName,\n          type: 'manual_unblock',\n          severity: 'info',\n          ip,\n          method: 'INTERNAL',\n          route: '/admin/unblock',\n          reason: 'Manual unblock requested',\n          action: 'unblocked'\n        });\n      }\n      return result;\n    },\n\n    isBlocked: (ip: string): boolean => blockManager.isBlocked(ip),\n    getBlockInfo: (ip: string): BlockInfo | null => blockManager.getBlockInfo(ip),\n    listBlocks: (): BlockInfo[] => blockManager.listBlocks(),\n    flush: (): Promise<void> => logger.flush()\n  };\n}\n\nexport {\n  createMiddleware,\n  extractClientIp,\n  isRouteExcluded,\n  safelyEndResponse,\n  resolveConfig,\n  DEFAULT_CONFIG,\n  RateLimiter,\n  Detector,\n  BlockManager,\n  isValidIp,\n  normalizeIp,\n  canonicalizeIpv6,\n  parseDuration,\n  Logger,\n  stripAnsi,\n  sanitizeString,\n  sanitizeRoute,\n  sanitizeMethod,\n  createNextShield,\n  withNextShield,\n  extractNextClientIp\n};\n\nexport type { BlockInfo, ZShieldInstance, ZShieldFullInstance };\nexport * from './types';\n\n"]}

package/dist/logger.d.ts

@@ -0,0 +1,141 @@
+import type { ZShieldConfig, ZShieldOptions } from './types';
+export interface LoggerOptions {
+    appName?: string;
+    logDir?: string;
+    logFilename?: string;
+    maxLogSizeBytes?: number;
+    maxLogFiles?: number;
+    maxLogQueueSize?: number;
+    maxQueueSize?: number;
+    onLogError?: ((err: Error, event: Record<string, unknown>) => void) | null;
+}
+export interface FormattedSecurityEvent {
+    timestamp: string;
+    appName: string;
+    type: string;
+    severity: string;
+    ip: string;
+    method: string;
+    route: string;
+    reason: string;
+    action: string;
+}
+/**
+ * Strips ANSI terminal escape codes from untrusted strings to prevent terminal injection.
+ * Removes CSI color/control sequences, OSC title/hyperlink sequences, and escape codes.
+ *
+ * @param str - Untrusted string
+ * @returns Clean string without ANSI escapes
+ */
+export declare function stripAnsi(str: string): string;
+/**
+ * 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 - Untrusted candidate value
+ * @param maxLength - Maximum permitted length
+ * @returns Sanitized string
+ */
+export declare function sanitizeString(val: unknown, maxLength?: number): string;
+/**
+ * Sanitizes HTTP route paths.
+ * @param route - Untrusted route string
+ * @param maxLength - Maximum permitted length
+ * @returns Sanitized route
+ */
+export declare function sanitizeRoute(route: unknown, maxLength?: number): string;
+/**
+ * Sanitizes HTTP methods.
+ * @param method - Untrusted method string
+ * @returns Sanitized uppercase HTTP method
+ */
+export declare function sanitizeMethod(method: unknown): string;
+/**
+ * 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.
+ * - Bounded Queue: Strictly caps pending in-memory write operations to prevent memory exhaustion under attack.
+ * - 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.
+ */
+export declare class Logger {
+    readonly appName: string;
+    readonly logDir: string;
+    readonly logFilename: string;
+    readonly filePath: string;
+    readonly maxLogSizeBytes: number;
+    readonly maxLogFiles: number;
+    readonly maxQueueSize: number;
+    readonly onLogError: ((err: Error, event: Record<string, unknown>) => void) | null;
+    private _writeQueue;
+    private _dirEnsured;
+    private _pendingWrites;
+    private _droppedEvents;
+    /**
+     * @param config - Logger options or resolved Z-Shield configuration
+     */
+    constructor(config?: LoggerOptions | ZShieldConfig | ZShieldOptions);
+    /**
+     * Returns the count of currently queued or executing asynchronous write operations.
+     */
+    get pendingWrites(): number;
+    /**
+     * Returns the cumulative count of log events dropped due to write queue overload.
+     */
+    get droppedEvents(): number;
+    /**
+     * Formats and sanitizes a security event into a validated schema.
+     * Deliberately omits request bodies, authorization headers, cookies, and tokens.
+     *
+     * @param rawEvent - Raw event object
+     * @returns Validated security event
+     */
+    formatEvent(rawEvent?: Record<string, unknown>): FormattedSecurityEvent;
+    /**
+     * Safely logs a security event asynchronously.
+     * Resolves to true if write succeeded, or false if it failed or was dropped due to queue overload.
+     *
+     * @param rawEvent - Raw event data
+     * @returns True if write succeeded, false otherwise
+     */
+    log(rawEvent: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Waits for all currently queued asynchronous log writes to complete.
+     * Useful for deterministic testing, graceful shutdowns, and process exit handlers.
+     */
+    flush(): Promise<void>;
+    /**
+     * Internal write operation executed within the sequential queue.
+     *
+     * @param rawEvent - Raw event to serialize and write
+     */
+    private _writeEvent;
+    /**
+     * Ensures the target log directory exists.
+     */
+    private _ensureDir;
+    /**
+     * Checks file size and rotates log files if size exceeds maxLogSizeBytes.
+     */
+    private _rotateIfNeeded;
+    /**
+     * Safely handles write and filesystem failures without crashing the application.
+     *
+     * @param err - Encountered error
+     * @param rawEvent - Raw event data attempted to be written
+     */
+    private _handleError;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/logger.js

@@ -0,0 +1,347 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+exports.stripAnsi = stripAnsi;
+exports.sanitizeString = sanitizeString;
+exports.sanitizeRoute = sanitizeRoute;
+exports.sanitizeMethod = sanitizeMethod;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const ANSI_REGEX = /[\u001B\u009B](?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
+/**
+ * Strips ANSI terminal escape codes from untrusted strings to prevent terminal injection.
+ * Removes CSI color/control sequences, OSC title/hyperlink sequences, and escape codes.
+ *
+ * @param str - Untrusted string
+ * @returns Clean string without ANSI escapes
+ */
+function stripAnsi(str) {
+    if (typeof str !== 'string') {
+        return '';
+    }
+    return str.replace(ANSI_REGEX, '');
+}
+/**
+ * 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 - Untrusted candidate value
+ * @param maxLength - Maximum permitted length
+ * @returns Sanitized 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 - Untrusted route string
+ * @param maxLength - Maximum permitted length
+ * @returns Sanitized route
+ */
+function sanitizeRoute(route, maxLength = 500) {
+    if (!route || typeof route !== 'string') {
+        return '/';
+    }
+    let clean = route.split(/[\r\n]/)[0] ?? '';
+    clean = stripAnsi(clean);
+    // 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, '').trim();
+    if (!clean.startsWith('/')) {
+        clean = '/' + clean;
+    }
+    return clean.slice(0, maxLength) || '/';
+}
+/**
+ * Sanitizes HTTP methods.
+ * @param method - Untrusted method string
+ * @returns Sanitized uppercase HTTP method
+ */
+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.
+ * - Bounded Queue: Strictly caps pending in-memory write operations to prevent memory exhaustion under attack.
+ * - 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 {
+    appName;
+    logDir;
+    logFilename;
+    filePath;
+    maxLogSizeBytes;
+    maxLogFiles;
+    maxQueueSize;
+    onLogError;
+    _writeQueue;
+    _dirEnsured;
+    _pendingWrites;
+    _droppedEvents;
+    /**
+     * @param config - Logger options or resolved Z-Shield configuration
+     */
+    constructor(config = {}) {
+        this.appName = config.appName || 'default-app';
+        this.logDir = node_path_1.default.resolve(config.logDir || node_path_1.default.join(process.cwd(), '.z-shield-logs'));
+        this.logFilename = config.logFilename || 'events.jsonl';
+        this.filePath = node_path_1.default.join(this.logDir, this.logFilename);
+        this.maxLogSizeBytes = config.maxLogSizeBytes || 5 * 1024 * 1024; // 5MB
+        this.maxLogFiles = typeof config.maxLogFiles === 'number' ? config.maxLogFiles : 5;
+        const rawQueueLimit = config.maxLogQueueSize ??
+            config.maxQueueSize;
+        this.maxQueueSize =
+            typeof rawQueueLimit === 'number' && Number.isInteger(rawQueueLimit) && rawQueueLimit > 0
+                ? rawQueueLimit
+                : 1000;
+        this.onLogError = typeof config.onLogError === 'function' ? config.onLogError : null;
+        this._writeQueue = Promise.resolve();
+        this._dirEnsured = false;
+        this._pendingWrites = 0;
+        this._droppedEvents = 0;
+    }
+    /**
+     * Returns the count of currently queued or executing asynchronous write operations.
+     */
+    get pendingWrites() {
+        return this._pendingWrites;
+    }
+    /**
+     * Returns the cumulative count of log events dropped due to write queue overload.
+     */
+    get droppedEvents() {
+        return this._droppedEvents;
+    }
+    /**
+     * Formats and sanitizes a security event into a validated schema.
+     * Deliberately omits request bodies, authorization headers, cookies, and tokens.
+     *
+     * @param rawEvent - Raw event object
+     * @returns Validated security event
+     */
+    formatEvent(rawEvent = {}) {
+        const rawTimestamp = rawEvent.timestamp;
+        const now = typeof rawTimestamp === 'string' || typeof rawTimestamp === 'number'
+            ? new Date(rawTimestamp)
+            : new Date();
+        const timestamp = isNaN(now.getTime()) ? new Date().toISOString() : now.toISOString();
+        const allowedSeverities = ['info', 'warning', 'critical'];
+        const rawSeverity = typeof rawEvent.severity === 'string' ? rawEvent.severity : '';
+        const severity = allowedSeverities.includes(rawSeverity) ? rawSeverity : 'warning';
+        const allowedActions = ['blocked', 'warned', 'allowed', 'unblocked'];
+        const rawAction = typeof rawEvent.action === 'string' ? rawEvent.action : '';
+        const action = allowedActions.includes(rawAction) ? rawAction : '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 or was dropped due to queue overload.
+     *
+     * @param rawEvent - Raw event data
+     * @returns True if write succeeded, false otherwise
+     */
+    log(rawEvent) {
+        if (this._pendingWrites >= this.maxQueueSize) {
+            this._droppedEvents++;
+            if (this.onLogError) {
+                try {
+                    this.onLogError(new Error(`[Z-Shield Logger]: Write queue capacity of ${this.maxQueueSize} reached. Event dropped.`), rawEvent);
+                }
+                catch {
+                    // Prevent user callback exceptions from propagating or crashing
+                }
+            }
+            else if (this._droppedEvents === 1 || this._droppedEvents % 1000 === 0) {
+                console.error(`[Z-Shield Logger Warning]: Write queue capacity of ${this.maxQueueSize} reached. ${this._droppedEvents} event(s) dropped.`);
+            }
+            return Promise.resolve(false);
+        }
+        this._pendingWrites++;
+        return new Promise((resolve) => {
+            this._writeQueue = this._writeQueue
+                .then(() => this._writeEvent(rawEvent))
+                .then(() => {
+                this._pendingWrites--;
+                resolve(true);
+            })
+                .catch((err) => {
+                this._pendingWrites--;
+                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.
+     */
+    async flush() {
+        await this._writeQueue;
+    }
+    /**
+     * Internal write operation executed within the sequential queue.
+     *
+     * @param rawEvent - Raw event to serialize and write
+     */
+    async _writeEvent(rawEvent) {
+        const event = this.formatEvent(rawEvent);
+        await this._ensureDir();
+        await this._rotateIfNeeded();
+        const line = JSON.stringify(event) + '\n';
+        try {
+            await node_fs_1.default.promises.appendFile(this.filePath, line, { encoding: 'utf8', flag: 'a' });
+        }
+        catch (err) {
+            // Self-healing recovery: if directory was removed externally right before write,
+            // recreate directory and retry appending once before throwing.
+            if (err.code === 'ENOENT') {
+                this._dirEnsured = false;
+                await node_fs_1.default.promises.mkdir(this.logDir, { recursive: true });
+                this._dirEnsured = true;
+                await node_fs_1.default.promises.appendFile(this.filePath, line, { encoding: 'utf8', flag: 'a' });
+                return;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Ensures the target log directory exists.
+     */
+    async _ensureDir() {
+        if (!this._dirEnsured || !node_fs_1.default.existsSync(this.logDir)) {
+            await node_fs_1.default.promises.mkdir(this.logDir, { recursive: true });
+            this._dirEnsured = true;
+        }
+    }
+    /**
+     * Checks file size and rotates log files if size exceeds maxLogSizeBytes.
+     */
+    async _rotateIfNeeded() {
+        try {
+            const stats = await node_fs_1.default.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 } = node_path_1.default.parse(this.logFilename);
+        // If maxLogFiles is 0, simply remove the current file
+        if (this.maxLogFiles === 0) {
+            try {
+                await node_fs_1.default.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 = node_path_1.default.join(this.logDir, `${name}.${i}${ext}`);
+            if (i === this.maxLogFiles) {
+                try {
+                    await node_fs_1.default.promises.unlink(currentRotated);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+            }
+            else {
+                const nextRotated = node_path_1.default.join(this.logDir, `${name}.${i + 1}${ext}`);
+                try {
+                    await node_fs_1.default.promises.rename(currentRotated, nextRotated);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+            }
+        }
+        // Move current events.jsonl to events.1.jsonl
+        const firstRotated = node_path_1.default.join(this.logDir, `${name}.1${ext}`);
+        try {
+            await node_fs_1.default.promises.rename(this.filePath, firstRotated);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    /**
+     * Safely handles write and filesystem failures without crashing the application.
+     *
+     * @param err - Encountered error
+     * @param rawEvent - Raw event data attempted to be written
+     */
+    _handleError(err, rawEvent) {
+        // If the directory was deleted externally while running, reset _dirEnsured so the next
+        // write attempt will automatically recreate the directory instead of failing permanently.
+        this._dirEnsured = false;
+        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}`);
+        }
+    }
+}
+exports.Logger = Logger;
+//# sourceMappingURL=logger.js.map