z-shield 0.1.0 → 0.1.2

package/dist/rate-limiter.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+const block_manager_1 = 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 {
+    windowMs;
+    maxRequests;
+    maxTrackedIps;
+    records;
+    /**
+     * @param options - Limiter options or resolved configuration
+     */
+    constructor(options = {}) {
+        this.windowMs = options.windowMs || 60000;
+        this.maxRequests = options.maxRequests || 100;
+        this.maxTrackedIps = options.maxTrackedIps || 10000;
+        this.records = new Map();
+    }
+    /**
+     * Records an incoming request from an IP address.
+     *
+     * @param ip - Client IP address
+     * @param now - Current timestamp (injectable for testing)
+     * @returns Current rate limit status
+     */
+    record(ip, now = Date.now()) {
+        const cleanIp = (0, block_manager_1.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 = undefined;
+        }
+        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 ip - Client IP address
+     * @param now - Current timestamp
+     * @returns Current rate limit status
+     */
+    get(ip, now = Date.now()) {
+        const cleanIp = (0, block_manager_1.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 ip - Client IP address
+     */
+    reset(ip) {
+        const cleanIp = (0, block_manager_1.normalizeIp)(ip);
+        this.records.delete(cleanIp);
+    }
+    /**
+     * Clears all tracked IP records from memory.
+     */
+    clear() {
+        this.records.clear();
+    }
+    /**
+     * Number of IPs currently stored in memory.
+     */
+    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 now - Current timestamp
+     * @returns 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.
+     * Evicts the least recently used entry to strictly uphold memory bound.
+     *
+     * @param _now - Current timestamp
+     */
+    _evictOldest(_now) {
+        const iterator = this.records.keys();
+        const firstKey = iterator.next().value;
+        if (firstKey !== undefined) {
+            this.records.delete(firstKey);
+        }
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizeIp } from './block-manager';\nimport type { RateLimitStatus, ZShieldConfig, ZShieldOptions } from './types';\n\nexport interface RateLimiterOptions {\n  windowMs?: number;\n  maxRequests?: number;\n  maxTrackedIps?: number;\n}\n\ninterface CounterEntry {\n  count: number;\n  resetTime: number;\n}\n\n/**\n * RateLimiter - Bounded In-Memory Request Counter\n *\n * Algorithm: Fixed Window with Per-IP Dynamic Reset Time\n * - On an IP's first request, we establish a time window (now -> now + windowMs).\n * - Every subsequent request within the window increments the counter.\n * - When the window expires, the counter resets to 1 with a new window.\n *\n * Memory Protection (DoS defense):\n * - JavaScript's Map preserves insertion order.\n * - By deleting and re-setting accessed keys, the Map functions as an LRU (Least Recently Used) cache.\n * - If the number of tracked IPs reaches `maxTrackedIps`, we evict the oldest entry.\n *   This ensures memory consumption is strictly bounded and cannot crash the Node.js process.\n */\nexport class RateLimiter {\n  readonly windowMs: number;\n  readonly maxRequests: number;\n  readonly maxTrackedIps: number;\n  private readonly records: Map<string, CounterEntry>;\n\n  /**\n   * @param options - Limiter options or resolved configuration\n   */\n  constructor(options: RateLimiterOptions | ZShieldConfig | ZShieldOptions = {}) {\n    this.windowMs = options.windowMs || 60000;\n    this.maxRequests = options.maxRequests || 100;\n    this.maxTrackedIps = options.maxTrackedIps || 10000;\n\n    this.records = new Map<string, CounterEntry>();\n  }\n\n  /**\n   * Records an incoming request from an IP address.\n   *\n   * @param ip - Client IP address\n   * @param now - Current timestamp (injectable for testing)\n   * @returns Current rate limit status\n   */\n  record(ip: string, now: number = Date.now()): RateLimitStatus {\n    const cleanIp = normalizeIp(ip);\n\n    let entry = this.records.get(cleanIp);\n\n    // If an existing entry has expired, treat it as a fresh window\n    if (entry && now >= entry.resetTime) {\n      entry = undefined;\n    }\n\n    if (entry) {\n      // Existing active window: increment count\n      entry.count += 1;\n\n      // Refresh LRU order: delete and re-set so this IP is marked as most recently used\n      this.records.delete(cleanIp);\n      this.records.set(cleanIp, entry);\n    } else {\n      // New window or expired window: only evict if adding a NEW IP at capacity\n      if (!this.records.has(cleanIp) && this.records.size >= this.maxTrackedIps) {\n        this._evictOldest(now);\n      }\n\n      entry = {\n        count: 1,\n        resetTime: now + this.windowMs\n      };\n\n      // Delete first to ensure refreshed LRU order in Map\n      this.records.delete(cleanIp);\n      this.records.set(cleanIp, entry);\n    }\n\n    const remaining = Math.max(0, this.maxRequests - entry.count);\n    const isExceeded = entry.count > this.maxRequests;\n\n    return {\n      count: entry.count,\n      remaining,\n      resetTime: entry.resetTime,\n      isExceeded\n    };\n  }\n\n  /**\n   * Inspects current status for an IP without incrementing its counter.\n   *\n   * @param ip - Client IP address\n   * @param now - Current timestamp\n   * @returns Current rate limit status\n   */\n  get(ip: string, now: number = Date.now()): RateLimitStatus {\n    const cleanIp = normalizeIp(ip);\n    const entry = this.records.get(cleanIp);\n\n    if (!entry || now >= entry.resetTime) {\n      return {\n        count: 0,\n        remaining: this.maxRequests,\n        resetTime: now + this.windowMs,\n        isExceeded: false\n      };\n    }\n\n    return {\n      count: entry.count,\n      remaining: Math.max(0, this.maxRequests - entry.count),\n      resetTime: entry.resetTime,\n      isExceeded: entry.count > this.maxRequests\n    };\n  }\n\n  /**\n   * Resets counter for a specific IP.\n   * @param ip - Client IP address\n   */\n  reset(ip: string): void {\n    const cleanIp = normalizeIp(ip);\n    this.records.delete(cleanIp);\n  }\n\n  /**\n   * Clears all tracked IP records from memory.\n   */\n  clear(): void {\n    this.records.clear();\n  }\n\n  /**\n   * Number of IPs currently stored in memory.\n   */\n  get size(): number {\n    return this.records.size;\n  }\n\n  /**\n   * Scans and removes any expired counters from memory.\n   * Because Map maintains insertion order, oldest entries are checked first.\n   *\n   * @param now - Current timestamp\n   * @returns Count of removed expired entries\n   */\n  pruneExpired(now: number = Date.now()): number {\n    let pruned = 0;\n    for (const [ip, entry] of this.records.entries()) {\n      if (now >= entry.resetTime) {\n        this.records.delete(ip);\n        pruned++;\n      }\n    }\n    return pruned;\n  }\n\n  /**\n   * Evicts the oldest entry to maintain bounded memory.\n   * Evicts the least recently used entry to strictly uphold memory bound.\n   *\n   * @param _now - Current timestamp\n   */\n  private _evictOldest(_now: number): void {\n    const iterator = this.records.keys();\n    const firstKey = iterator.next().value;\n\n    if (firstKey !== undefined) {\n      this.records.delete(firstKey);\n    }\n  }\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Z-Shield Core Type Definitions
+ */
+import type { RateLimiter } from './rate-limiter';
+import type { Detector } from './detector';
+import type { BlockManager, BlockInfo } from './block-manager';
+import type { Logger } from './logger';
+export type ZShieldMode = 'monitor' | 'protect';
+export interface ZShieldOptions {
+    mode?: ZShieldMode;
+    windowMs?: number;
+    maxRequests?: number;
+    maxTrackedIps?: number;
+    autoBlock?: boolean;
+    blockDurationMs?: number;
+    blockDuration?: string | number;
+    maxBlockedIps?: number;
+    trustProxy?: boolean;
+    logDir?: string;
+    logFilename?: string;
+    appName?: string;
+    excludeRoutes?: string[] | readonly string[];
+    maxLogSizeBytes?: number;
+    maxLogFiles?: number;
+    maxLogQueueSize?: number;
+    onLogError?: ((err: Error, event: Record<string, unknown>) => void) | null;
+}
+export interface ZShieldConfig {
+    readonly mode: ZShieldMode;
+    readonly windowMs: number;
+    readonly maxRequests: number;
+    readonly maxTrackedIps: number;
+    readonly autoBlock: boolean;
+    readonly blockDurationMs: number;
+    readonly blockDuration?: string | number;
+    readonly maxBlockedIps: number;
+    readonly trustProxy: boolean;
+    readonly logDir: string;
+    readonly logFilename: string;
+    readonly appName: string;
+    readonly excludeRoutes: readonly string[];
+    readonly maxLogSizeBytes: number;
+    readonly maxLogFiles: number;
+    readonly maxLogQueueSize: number;
+    readonly onLogError: ((err: Error, event: Record<string, unknown>) => void) | null;
+}
+export interface RateLimitStatus {
+    count: number;
+    remaining: number;
+    resetTime: number;
+    isExceeded: boolean;
+}
+export interface BlockRecord {
+    ip: string;
+    blockedAt: number;
+    expiresAt: number;
+    reason: string;
+    durationMs: number;
+}
+export type { BlockInfo } from './block-manager';
+export type SecurityEventType = 'rate_limit' | 'manual_block' | 'manual_unblock' | 'suspicious_activity' | string;
+export type SecurityEventAction = 'blocked' | 'warning' | 'audit' | 'unblocked' | string;
+export interface SecurityEvent {
+    timestamp: string;
+    appName: string;
+    ip: string;
+    type: SecurityEventType;
+    action: SecurityEventAction;
+    route?: string;
+    method?: string;
+    reason?: string;
+    details?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface DetectionResult {
+    status: 'normal' | 'suspicious' | 'blocked';
+    reason?: string;
+    rateLimitStatus: RateLimitStatus;
+    isBlocked: boolean;
+}
+/**
+ * Structural types for Express-compatible HTTP requests and responses.
+ * These types do not require installing @types/express in consumer projects.
+ */
+export interface ExpressLikeRequest {
+    ip?: string;
+    url?: string;
+    path?: string;
+    method?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    headers?: Record<string, string | string[] | undefined>;
+    zShield?: {
+        ip: string;
+        mode: string;
+        appName: string;
+        isExcluded: boolean;
+        startTime: number;
+        detection: unknown;
+        blocked: boolean;
+        blockReason?: string;
+        logPromise?: Promise<boolean> | null;
+    };
+}
+export interface ExpressLikeResponse {
+    headersSent?: boolean;
+    writableEnded?: boolean;
+    setHeader?(name: string, value: string): void;
+    status?(code: number): this | ExpressLikeResponse;
+    json?(body: unknown): void;
+    end?(): void;
+}
+export type ExpressLikeNextFunction = (err?: unknown) => void;
+export type ExpressMiddleware<Req = ExpressLikeRequest, Res = ExpressLikeResponse, Next = ExpressLikeNextFunction> = (req: Req, res: Res, next: Next) => void;
+export interface ZShieldInstance {
+    readonly middleware: ExpressMiddleware;
+    readonly config: ZShieldConfig;
+    readonly rateLimiter: RateLimiter;
+    readonly detector: Detector;
+    readonly blockManager: BlockManager;
+    readonly logger: Logger;
+    block: (ip: string, duration?: string | number, reason?: string) => BlockRecord;
+    unblock: (ip: string) => boolean;
+    isBlocked: (ip: string) => boolean;
+    getBlockInfo: (ip: string) => BlockInfo | null;
+    listBlocks: () => BlockInfo[];
+    flush: () => Promise<void>;
+}
+export type ZShieldFullInstance = ZShieldInstance;
+/**
+ * Structural type for Web-standard or Next.js requests.
+ */
+export interface NextLikeRequest {
+    url?: string;
+    method?: string;
+    headers?: Headers | Record<string, string | string[] | undefined> | {
+        get(name: string): string | null;
+    };
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+export type NextClientIpStrategy = 'x-forwarded-for' | 'x-real-ip' | 'nginx' | 'cf-connecting-ip' | 'cloudflare' | 'true-client-ip' | 'akamai';
+export type NextClientIpExtractor = (request: Request | NextLikeRequest) => string | null | undefined;
+export interface NextShieldOptions extends ZShieldOptions {
+    /**
+     * Explicit client IP extraction strategy or custom callback function.
+     *
+     * To safely extract client IPs behind a reverse proxy, explicitly specify your
+     * trusted deployment proxy strategy or provide a custom extraction callback:
+     * - 'cloudflare' | 'cf-connecting-ip': Trusts only the CF-Connecting-IP header.
+     * - 'nginx' | 'x-real-ip': Trusts only the X-Real-IP header.
+     * - 'akamai' | 'true-client-ip': Trusts only the True-Client-IP header.
+     * - 'x-forwarded-for': Trusts the first valid IP in X-Forwarded-For.
+     * - Custom function: `(req) => string | null | undefined`
+     */
+    getIp?: NextClientIpStrategy | NextClientIpExtractor;
+    /**
+     * Optional custom 429 response builder.
+     */
+    customBlockResponse?: (info: {
+        reason: string;
+        retryAfter: number;
+        clientIp: string;
+    }) => Response;
+}
+export interface NextShieldCheckResult {
+    blocked: boolean;
+    isExcluded: boolean;
+    clientIp: string;
+    headers: Record<string, string>;
+    response?: Response;
+    detection?: {
+        isSuspicious: boolean;
+        count: number;
+        remaining: number;
+        resetTime: number;
+        reason: string | null;
+    };
+}
+export type NextRouteHandler<TContext = unknown> = (request: Request, context?: TContext) => Promise<Response> | Response;
+export interface NextShieldInstance {
+    readonly config: ZShieldConfig;
+    readonly rateLimiter: RateLimiter;
+    readonly detector: Detector;
+    readonly blockManager: BlockManager;
+    readonly logger: Logger;
+    check: (request: Request | NextLikeRequest) => Promise<NextShieldCheckResult>;
+    protect: <TContext = unknown>(handler: (request: Request, context?: TContext) => Promise<Response> | Response) => (request: Request, context?: TContext) => Promise<Response>;
+    block: (ip: string, duration?: string | number, reason?: string) => BlockRecord;
+    unblock: (ip: string) => boolean;
+    isBlocked: (ip: string) => boolean;
+    getBlockInfo: (ip: string) => BlockInfo | null;
+    listBlocks: () => BlockInfo[];
+    flush: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Z-Shield Core Type Definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG","sourcesContent":["/**\n * Z-Shield Core Type Definitions\n */\n\nimport type { RateLimiter } from './rate-limiter';\nimport type { Detector } from './detector';\nimport type { BlockManager, BlockInfo } from './block-manager';\nimport type { Logger } from './logger';\n\nexport type ZShieldMode = 'monitor' | 'protect';\n\nexport interface ZShieldOptions {\n  mode?: ZShieldMode;\n  windowMs?: number;\n  maxRequests?: number;\n  maxTrackedIps?: number;\n  autoBlock?: boolean;\n  blockDurationMs?: number;\n  blockDuration?: string | number;\n  maxBlockedIps?: number;\n  trustProxy?: boolean;\n  logDir?: string;\n  logFilename?: string;\n  appName?: string;\n  excludeRoutes?: string[] | readonly string[];\n  maxLogSizeBytes?: number;\n  maxLogFiles?: number;\n  maxLogQueueSize?: number;\n  onLogError?: ((err: Error, event: Record<string, unknown>) => void) | null;\n}\n\nexport interface ZShieldConfig {\n  readonly mode: ZShieldMode;\n  readonly windowMs: number;\n  readonly maxRequests: number;\n  readonly maxTrackedIps: number;\n  readonly autoBlock: boolean;\n  readonly blockDurationMs: number;\n  readonly blockDuration?: string | number;\n  readonly maxBlockedIps: number;\n  readonly trustProxy: boolean;\n  readonly logDir: string;\n  readonly logFilename: string;\n  readonly appName: string;\n  readonly excludeRoutes: readonly string[];\n  readonly maxLogSizeBytes: number;\n  readonly maxLogFiles: number;\n  readonly maxLogQueueSize: number;\n  readonly onLogError: ((err: Error, event: Record<string, unknown>) => void) | null;\n}\n\nexport interface RateLimitStatus {\n  count: number;\n  remaining: number;\n  resetTime: number;\n  isExceeded: boolean;\n}\n\nexport interface BlockRecord {\n  ip: string;\n  blockedAt: number;\n  expiresAt: number;\n  reason: string;\n  durationMs: number;\n}\n\nexport type { BlockInfo } from './block-manager';\n\nexport type SecurityEventType =\n  | 'rate_limit'\n  | 'manual_block'\n  | 'manual_unblock'\n  | 'suspicious_activity'\n  | string;\n\nexport type SecurityEventAction =\n  | 'blocked'\n  | 'warning'\n  | 'audit'\n  | 'unblocked'\n  | string;\n\nexport interface SecurityEvent {\n  timestamp: string;\n  appName: string;\n  ip: string;\n  type: SecurityEventType;\n  action: SecurityEventAction;\n  route?: string;\n  method?: string;\n  reason?: string;\n  details?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\nexport interface DetectionResult {\n  status: 'normal' | 'suspicious' | 'blocked';\n  reason?: string;\n  rateLimitStatus: RateLimitStatus;\n  isBlocked: boolean;\n}\n\n/**\n * Structural types for Express-compatible HTTP requests and responses.\n * These types do not require installing @types/express in consumer projects.\n */\nexport interface ExpressLikeRequest {\n  ip?: string;\n  url?: string;\n  path?: string;\n  method?: string;\n  socket?: { remoteAddress?: string };\n  headers?: Record<string, string | string[] | undefined>;\n  zShield?: {\n    ip: string;\n    mode: string;\n    appName: string;\n    isExcluded: boolean;\n    startTime: number;\n    detection: unknown;\n    blocked: boolean;\n    blockReason?: string;\n    logPromise?: Promise<boolean> | null;\n  };\n}\n\nexport interface ExpressLikeResponse {\n  headersSent?: boolean;\n  writableEnded?: boolean;\n  setHeader?(name: string, value: string): void;\n  status?(code: number): this | ExpressLikeResponse;\n  json?(body: unknown): void;\n  end?(): void;\n}\n\nexport type ExpressLikeNextFunction = (err?: unknown) => void;\n\nexport type ExpressMiddleware<\n  Req = ExpressLikeRequest,\n  Res = ExpressLikeResponse,\n  Next = ExpressLikeNextFunction\n> = (req: Req, res: Res, next: Next) => void;\n\nexport interface ZShieldInstance {\n  readonly middleware: ExpressMiddleware;\n  readonly config: ZShieldConfig;\n  readonly rateLimiter: RateLimiter;\n  readonly detector: Detector;\n  readonly blockManager: BlockManager;\n  readonly logger: Logger;\n  block: (ip: string, duration?: string | number, reason?: string) => BlockRecord;\n  unblock: (ip: string) => boolean;\n  isBlocked: (ip: string) => boolean;\n  getBlockInfo: (ip: string) => BlockInfo | null;\n  listBlocks: () => BlockInfo[];\n  flush: () => Promise<void>;\n}\n\nexport type ZShieldFullInstance = ZShieldInstance;\n\n/**\n * Structural type for Web-standard or Next.js requests.\n */\nexport interface NextLikeRequest {\n  url?: string;\n  method?: string;\n  headers?: Headers | Record<string, string | string[] | undefined> | { get(name: string): string | null };\n  ip?: string;\n  socket?: { remoteAddress?: string };\n}\n\nexport type NextClientIpStrategy =\n  | 'x-forwarded-for'\n  | 'x-real-ip'\n  | 'nginx'\n  | 'cf-connecting-ip'\n  | 'cloudflare'\n  | 'true-client-ip'\n  | 'akamai';\n\nexport type NextClientIpExtractor = (\n  request: Request | NextLikeRequest\n) => string | null | undefined;\n\nexport interface NextShieldOptions extends ZShieldOptions {\n  /**\n   * Explicit client IP extraction strategy or custom callback function.\n   *\n   * To safely extract client IPs behind a reverse proxy, explicitly specify your\n   * trusted deployment proxy strategy or provide a custom extraction callback:\n   * - 'cloudflare' | 'cf-connecting-ip': Trusts only the CF-Connecting-IP header.\n   * - 'nginx' | 'x-real-ip': Trusts only the X-Real-IP header.\n   * - 'akamai' | 'true-client-ip': Trusts only the True-Client-IP header.\n   * - 'x-forwarded-for': Trusts the first valid IP in X-Forwarded-For.\n   * - Custom function: `(req) => string | null | undefined`\n   */\n  getIp?: NextClientIpStrategy | NextClientIpExtractor;\n\n  /**\n   * Optional custom 429 response builder.\n   */\n  customBlockResponse?: (info: { reason: string; retryAfter: number; clientIp: string }) => Response;\n}\n\nexport interface NextShieldCheckResult {\n  blocked: boolean;\n  isExcluded: boolean;\n  clientIp: string;\n  headers: Record<string, string>;\n  response?: Response;\n  detection?: {\n    isSuspicious: boolean;\n    count: number;\n    remaining: number;\n    resetTime: number;\n    reason: string | null;\n  };\n}\n\nexport type NextRouteHandler<TContext = unknown> = (\n  request: Request,\n  context?: TContext\n) => Promise<Response> | Response;\n\nexport interface NextShieldInstance {\n  readonly config: ZShieldConfig;\n  readonly rateLimiter: RateLimiter;\n  readonly detector: Detector;\n  readonly blockManager: BlockManager;\n  readonly logger: Logger;\n  check: (request: Request | NextLikeRequest) => Promise<NextShieldCheckResult>;\n  protect: <TContext = unknown>(\n    handler: (request: Request, context?: TContext) => Promise<Response> | Response\n  ) => (request: Request, context?: TContext) => Promise<Response>;\n  block: (ip: string, duration?: string | number, reason?: string) => BlockRecord;\n  unblock: (ip: string) => boolean;\n  isBlocked: (ip: string) => boolean;\n  getBlockInfo: (ip: string) => BlockInfo | null;\n  listBlocks: () => BlockInfo[];\n  flush: () => Promise<void>;\n}\n"]}

package/next.d.ts

@@ -0,0 +1 @@
+export * from './dist/next';

package/next.js

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('./dist/next.js');

package/package.json

@@ -1,13 +1,37 @@
 {
   "name": "z-shield",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "API abuse detection, rate limiting, and temporary IP blocking middleware for Node.js and Express",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "next": [
+        "dist/next.d.ts"
+      ]
+    }
+  },
   "bin": {
-    "z-shield": "src/cli.js"
+    "z-shield": "dist/cli.js"
   },
   "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
     "test": "node --test test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
     "start": "node examples/express-app.js"
   },
   "repository": {
@@ -29,13 +53,18 @@
   "author": "zeesu-royalist (https://zeesu-royalist.vercel.app)",
   "license": "MIT",
   "files": [
-    "src",
+    "dist",
+    "next.js",
+    "next.d.ts",
     "README.md",
     "LICENSE",
     "SECURITY.md"
   ],
   "devDependencies": {
-    "express": "^4.21.2"
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.5",
+    "express": "^4.21.2",
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18.0.0"