z-shield 0.1.1 → 0.1.2

package/dist/next.js

@@ -0,0 +1,486 @@
+"use strict";
+/**
+ * Next.js App Router Compatibility Adapter for Z-Shield.
+ *
+ * Provides Web-standard Request and Response security middleware for Next.js App Router
+ * route handlers (e.g. app/api/.../route.ts).
+ *
+ * Runtime requirement: Node.js runtime (`export const runtime = 'nodejs';`).
+ * State note: In-memory rate limiting and blocking state is process-local.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNextClientIp = extractNextClientIp;
+exports.createNextShield = createNextShield;
+exports.withNextShield = withNextShield;
+const config_1 = require("./config");
+const rate_limiter_1 = require("./rate-limiter");
+const detector_1 = require("./detector");
+const block_manager_1 = require("./block-manager");
+const logger_1 = require("./logger");
+const middleware_1 = require("./middleware");
+/**
+ * Reads a header value from standard Headers or a plain object map.
+ */
+function getHeader(request, name) {
+    if (!request || !request.headers) {
+        return null;
+    }
+    if (typeof request.headers.get === 'function') {
+        return request.headers.get(name);
+    }
+    const headersObj = request.headers;
+    const lowerName = name.toLowerCase();
+    let val = headersObj[name] ?? headersObj[lowerName];
+    if (val === undefined) {
+        for (const key of Object.keys(headersObj)) {
+            if (key.toLowerCase() === lowerName) {
+                val = headersObj[key];
+                break;
+            }
+        }
+    }
+    if (Array.isArray(val)) {
+        return val[0] ?? null;
+    }
+    return typeof val === 'string' ? val : null;
+}
+/**
+ * Extracts and normalizes the client IP address from a Web-standard or Next.js Request.
+ *
+ * Security Model:
+ * 1. When `trustProxy` is false:
+ *    - All reverse-proxy headers (X-Forwarded-For, X-Real-IP, CF-Connecting-IP, etc.)
+ *      and unverified platform properties are strictly ignored to prevent client IP spoofing attacks.
+ *    - Only a verified Node.js TCP socket remote address (`socket.remoteAddress`) or an
+ *      explicitly provided custom extractor function is accepted.
+ *    - In environments without a direct TCP socket (e.g. serverless Web Requests without a trusted proxy),
+ *      safe client IP identification cannot be guaranteed, and this function safely falls back to 'unknown'.
+ *
+ * 2. When `trustProxy` is true:
+ *    - To prevent forged header injection across reverse proxies (e.g. an attacker sending CF-Connecting-IP
+ *      to an Nginx server that does not strip it), Z-Shield strictly requires selecting an explicit trusted
+ *      strategy via `getIp` or providing 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 (requires outer proxy header stripping).
+ *      - Custom function: `(req) => string | null | undefined`
+ *    - If `trustProxy` is true but no extraction strategy or custom function is configured,
+ *      Z-Shield strictly refuses to guess across foreign proxy headers, and falls back safely to 'unknown'
+ *      (or socket.remoteAddress if available).
+ *
+ * @param request - Incoming Web Request or NextLikeRequest
+ * @param trustProxy - Whether reverse proxy headers are trusted
+ * @param extractorOrStrategy - Trusted IP strategy name or custom extractor function
+ * @returns Normalized client IP address or 'unknown'
+ */
+function extractNextClientIp(request, trustProxy, extractorOrStrategy) {
+    // 1. Custom extractor callback function takes precedence if provided by developer
+    if (typeof extractorOrStrategy === 'function') {
+        try {
+            const customIp = extractorOrStrategy(request);
+            if (typeof customIp === 'string' && customIp.trim().length > 0) {
+                const trimmed = customIp.trim();
+                if ((0, block_manager_1.isValidIp)(trimmed)) {
+                    return (0, block_manager_1.normalizeIp)(trimmed);
+                }
+            }
+        }
+        catch {
+            // Gracefully fall through on extractor errors
+        }
+        return 'unknown';
+    }
+    const reqWithIp = request;
+    // 2. When trustProxy is false:
+    // Strictly ignore all reverse-proxy headers (X-Forwarded-For, X-Real-IP, etc.)
+    // and unverified platform headers to prevent client IP spoofing attacks.
+    if (!trustProxy) {
+        if (typeof reqWithIp.socket?.remoteAddress === 'string' && reqWithIp.socket.remoteAddress.length > 0) {
+            return (0, block_manager_1.normalizeIp)(reqWithIp.socket.remoteAddress);
+        }
+        // If no direct TCP socket is available (e.g. serverless Web Request without trusted proxy),
+        // safe client IP identification cannot be guaranteed. Fallback to 'unknown'.
+        return 'unknown';
+    }
+    // 3. When trustProxy is true:
+    // An explicit trusted IP extraction strategy must be selected.
+    // Z-Shield strictly refuses to guess across foreign proxy headers to prevent
+    // forged header injection attacks (e.g. sending CF-Connecting-IP to an Nginx server).
+    if (typeof extractorOrStrategy === 'string') {
+        const strategy = extractorOrStrategy.toLowerCase().trim();
+        if (strategy === 'cf-connecting-ip' || strategy === 'cloudflare') {
+            const cfIp = getHeader(request, 'cf-connecting-ip');
+            if (cfIp) {
+                const candidate = cfIp.trim();
+                if ((0, block_manager_1.isValidIp)(candidate)) {
+                    return (0, block_manager_1.normalizeIp)(candidate);
+                }
+            }
+            return 'unknown';
+        }
+        if (strategy === 'x-real-ip' || strategy === 'nginx') {
+            const xRealIp = getHeader(request, 'x-real-ip');
+            if (xRealIp) {
+                const candidate = xRealIp.trim();
+                if ((0, block_manager_1.isValidIp)(candidate)) {
+                    return (0, block_manager_1.normalizeIp)(candidate);
+                }
+            }
+            return 'unknown';
+        }
+        if (strategy === 'true-client-ip' || strategy === 'akamai') {
+            const trueIp = getHeader(request, 'true-client-ip');
+            if (trueIp) {
+                const candidate = trueIp.trim();
+                if ((0, block_manager_1.isValidIp)(candidate)) {
+                    return (0, block_manager_1.normalizeIp)(candidate);
+                }
+            }
+            return 'unknown';
+        }
+        if (strategy === 'x-forwarded-for') {
+            const xff = getHeader(request, 'x-forwarded-for');
+            if (xff) {
+                const candidates = xff.split(',').map(s => s.trim()).filter(Boolean);
+                for (const candidate of candidates) {
+                    if ((0, block_manager_1.isValidIp)(candidate)) {
+                        return (0, block_manager_1.normalizeIp)(candidate);
+                    }
+                }
+            }
+            return 'unknown';
+        }
+    }
+    // 4. Fallback if no strategy matched or no proxy header was trusted:
+    // If a direct TCP socket is available, return it; otherwise fail safely to 'unknown'.
+    if (typeof reqWithIp.socket?.remoteAddress === 'string' && reqWithIp.socket.remoteAddress.length > 0) {
+        return (0, block_manager_1.normalizeIp)(reqWithIp.socket.remoteAddress);
+    }
+    return 'unknown';
+}
+/**
+ * Extracts pathname from a request URL safely.
+ */
+function extractRequestPath(request) {
+    if (!request.url) {
+        return '/';
+    }
+    try {
+        const parsed = new URL(request.url, 'http://localhost');
+        return parsed.pathname;
+    }
+    catch {
+        return (request.url.split('?')[0] ?? '').split('#')[0] || '/';
+    }
+}
+/**
+ * Merges rate-limiting headers into an existing Web Response.
+ */
+function mergeResponseHeaders(response, headersToMerge) {
+    if (!response) {
+        return response;
+    }
+    try {
+        for (const [key, value] of Object.entries(headersToMerge)) {
+            response.headers.set(key, value);
+        }
+        return response;
+    }
+    catch {
+        const newHeaders = new Headers(response.headers);
+        for (const [key, value] of Object.entries(headersToMerge)) {
+            newHeaders.set(key, value);
+        }
+        const nullBodyStatuses = [101, 204, 205, 304];
+        const body = nullBodyStatuses.includes(response.status)
+            ? null
+            : response.body;
+        return new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: newHeaders
+        });
+    }
+}
+/**
+ * Creates standard HTTP 429 response when a request is blocked.
+ */
+function createBlockedResponse(retryAfter, reason, extraHeaders, customBuilder, clientIp) {
+    if (typeof customBuilder === 'function') {
+        try {
+            return customBuilder({
+                reason,
+                retryAfter,
+                clientIp: clientIp || 'unknown'
+            });
+        }
+        catch {
+            // Fallback to standard response if custom builder throws
+        }
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+        'Retry-After': String(retryAfter),
+        'X-Z-Shield-Blocked': '1',
+        ...extraHeaders
+    };
+    const body = {
+        error: 'Too Many Requests',
+        message: reason,
+        retryAfter
+    };
+    return new Response(JSON.stringify(body), {
+        status: 429,
+        headers
+    });
+}
+/**
+ * Checks if the passed object is an existing ZShieldInstance.
+ */
+function isZShieldInstance(val) {
+    return (typeof val === 'object' &&
+        val !== null &&
+        'rateLimiter' in val &&
+        'detector' in val &&
+        'blockManager' in val &&
+        'logger' in val &&
+        'config' in val);
+}
+/**
+ * Factory for creating a Next.js App Router shield instance.
+ *
+ * Usage:
+ *   import { createNextShield } from 'z-shield';
+ *   const shield = createNextShield({ mode: 'protect', maxRequests: 50 });
+ *
+ *   export const GET = shield.protect(async (request) => {
+ *     return Response.json({ message: 'Hello from protected API' });
+ *   });
+ *
+ * @param optionsOrInstance - Configuration options or existing ZShieldInstance
+ * @returns NextShieldInstance
+ */
+function createNextShield(optionsOrInstance, adapterOptions) {
+    let config;
+    let rateLimiter;
+    let detector;
+    let blockManager;
+    let logger;
+    let customGetIp;
+    let customBlockResponse;
+    if (isZShieldInstance(optionsOrInstance)) {
+        config = optionsOrInstance.config;
+        rateLimiter = optionsOrInstance.rateLimiter;
+        detector = optionsOrInstance.detector;
+        blockManager = optionsOrInstance.blockManager;
+        logger = optionsOrInstance.logger;
+        if (adapterOptions?.getIp) {
+            customGetIp = adapterOptions.getIp;
+        }
+        if (adapterOptions?.customBlockResponse) {
+            customBlockResponse = adapterOptions.customBlockResponse;
+        }
+    }
+    else {
+        const opts = optionsOrInstance || {};
+        config = (0, config_1.resolveConfig)(opts);
+        rateLimiter = new rate_limiter_1.RateLimiter(config);
+        detector = new detector_1.Detector({ rateLimiter, config });
+        blockManager = new block_manager_1.BlockManager(config);
+        logger = new logger_1.Logger(config);
+        if ('getIp' in opts && (typeof opts.getIp === 'function' || typeof opts.getIp === 'string')) {
+            customGetIp = opts.getIp;
+        }
+        if ('customBlockResponse' in opts && typeof opts.customBlockResponse === 'function') {
+            customBlockResponse = opts.customBlockResponse;
+        }
+    }
+    const check = async (request) => {
+        const pathname = extractRequestPath(request);
+        const method = (request.method || 'GET').toUpperCase();
+        const now = Date.now();
+        // 1. Route exclusion check
+        if ((0, middleware_1.isRouteExcluded)(pathname, config.excludeRoutes)) {
+            return {
+                blocked: false,
+                isExcluded: true,
+                clientIp: '',
+                headers: {}
+            };
+        }
+        // 2. Client IP extraction
+        const clientIp = extractNextClientIp(request, config.trustProxy, customGetIp);
+        // 3. BlockManager check
+        const isIpBlocked = blockManager.isBlocked(clientIp, now);
+        if (isIpBlocked) {
+            const blockInfo = blockManager.getBlockInfo(clientIp, now);
+            const reason = blockInfo ? blockInfo.reason : 'Administrative block';
+            const remainingMs = blockInfo ? blockInfo.remainingMs : 0;
+            const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
+            const action = config.mode === 'protect' ? 'blocked' : 'warned';
+            void logger.log({
+                appName: config.appName,
+                type: 'blocked_ip',
+                severity: 'warning',
+                ip: clientIp,
+                method,
+                route: pathname,
+                reason,
+                action
+            });
+            const headers = {
+                'X-Z-Shield-Protected': '1',
+                'X-Z-Shield-Mode': config.mode,
+                'X-Z-Shield-Blocked': '1',
+                'X-Z-Shield-Reason': reason,
+                'Retry-After': String(retryAfterSeconds)
+            };
+            if (config.mode === 'protect') {
+                const blockedResponse = createBlockedResponse(retryAfterSeconds, 'Your IP address has been temporarily blocked due to suspicious activity.', headers, customBlockResponse, clientIp);
+                return {
+                    blocked: true,
+                    isExcluded: false,
+                    clientIp,
+                    headers,
+                    response: blockedResponse
+                };
+            }
+            // Monitor mode: mark warning header and allow request through
+            headers['X-Z-Shield-Suspicious'] = '1';
+            return {
+                blocked: false,
+                isExcluded: false,
+                clientIp,
+                headers
+            };
+        }
+        // 4. Rate Limiting assessment via Detector
+        const detection = detector.check(clientIp, request, now);
+        const rateLimitHeaders = {
+            'X-Z-Shield-Protected': '1',
+            'X-Z-Shield-Mode': config.mode,
+            'X-RateLimit-Limit': String(config.maxRequests),
+            'X-RateLimit-Remaining': String(detection.remaining),
+            'X-RateLimit-Reset': String(Math.ceil(detection.resetTime / 1000))
+        };
+        if (detection.isSuspicious) {
+            const action = config.mode === 'protect' ? 'blocked' : 'warned';
+            void logger.log({
+                appName: config.appName,
+                type: detection.type || 'rate_limit',
+                severity: detection.severity || 'warning',
+                ip: clientIp,
+                method,
+                route: pathname,
+                reason: detection.reason || 'Threshold exceeded',
+                action
+            });
+            rateLimitHeaders['X-Z-Shield-Suspicious'] = '1';
+            rateLimitHeaders['X-Z-Shield-Reason'] = detection.reason || 'Threshold exceeded';
+            if (config.mode === 'protect') {
+                if (config.autoBlock && (0, block_manager_1.isValidIp)(clientIp)) {
+                    blockManager.block(clientIp, config.blockDurationMs, detection.reason || 'Threshold exceeded', now);
+                }
+                const retryAfterSeconds = Math.max(1, Math.ceil((detection.resetTime - now) / 1000));
+                rateLimitHeaders['Retry-After'] = String(retryAfterSeconds);
+                rateLimitHeaders['X-Z-Shield-Blocked'] = '1';
+                const blockedResponse = createBlockedResponse(retryAfterSeconds, 'Rate limit exceeded. Please wait before retrying.', rateLimitHeaders, customBlockResponse, clientIp);
+                return {
+                    blocked: true,
+                    isExcluded: false,
+                    clientIp,
+                    detection,
+                    headers: rateLimitHeaders,
+                    response: blockedResponse
+                };
+            }
+        }
+        // 5. Allowed / normal request
+        return {
+            blocked: false,
+            isExcluded: false,
+            clientIp,
+            detection,
+            headers: rateLimitHeaders
+        };
+    };
+    const protect = (handler) => {
+        return async (request, context) => {
+            const checkResult = await check(request);
+            if (checkResult.blocked && checkResult.response) {
+                return checkResult.response;
+            }
+            const response = await handler(request, context);
+            if (checkResult.isExcluded || Object.keys(checkResult.headers).length === 0) {
+                return response;
+            }
+            return mergeResponseHeaders(response, checkResult.headers);
+        };
+    };
+    return {
+        config,
+        rateLimiter,
+        detector,
+        blockManager,
+        logger,
+        check,
+        protect,
+        // Programmatic Block API
+        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()
+    };
+}
+/**
+ * Higher-order function wrapping a Next.js App Router route handler with Z-Shield protection.
+ *
+ * Usage:
+ *   import { withNextShield } from 'z-shield';
+ *
+ *   export const GET = withNextShield(async (req) => {
+ *     return Response.json({ ok: true });
+ *   }, { mode: 'protect', maxRequests: 50 });
+ *
+ * @param handler - Next.js Route Handler function
+ * @param options - Z-Shield configuration options or existing shield instance
+ * @returns Wrapped route handler
+ */
+function withNextShield(handler, options, adapterOptions) {
+    const shield = options && 'protect' in options
+        ? options
+        : createNextShield(options, adapterOptions);
+    return shield.protect(handler);
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Next.js App Router Compatibility Adapter for Z-Shield.\n *\n * Provides Web-standard Request and Response security middleware for Next.js App Router\n * route handlers (e.g. app/api/.../route.ts).\n *\n * Runtime requirement: Node.js runtime (`export const runtime = 'nodejs';`).\n * State note: In-memory rate limiting and blocking state is process-local.\n */\n\nimport { resolveConfig } from './config';\nimport { RateLimiter } from './rate-limiter';\nimport { Detector } from './detector';\nimport { BlockManager, isValidIp, normalizeIp, type BlockInfo } from './block-manager';\nimport { Logger } from './logger';\nimport { isRouteExcluded } from './middleware';\nimport type {\n  ZShieldConfig,\n  BlockRecord,\n  ZShieldInstance,\n  NextLikeRequest,\n  NextShieldOptions,\n  NextShieldCheckResult,\n  NextShieldInstance,\n  NextRouteHandler,\n  NextClientIpStrategy,\n  NextClientIpExtractor\n} from './types';\n\n/**\n * Reads a header value from standard Headers or a plain object map.\n */\nfunction getHeader(request: Request | NextLikeRequest, name: string): string | null {\n  if (!request || !request.headers) {\n    return null;\n  }\n  if (typeof (request.headers as Headers).get === 'function') {\n    return (request.headers as Headers).get(name);\n  }\n  const headersObj = request.headers as Record<string, string | string[] | undefined>;\n  const lowerName = name.toLowerCase();\n  let val = headersObj[name] ?? headersObj[lowerName];\n  if (val === undefined) {\n    for (const key of Object.keys(headersObj)) {\n      if (key.toLowerCase() === lowerName) {\n        val = headersObj[key];\n        break;\n      }\n    }\n  }\n  if (Array.isArray(val)) {\n    return val[0] ?? null;\n  }\n  return typeof val === 'string' ? val : null;\n}\n\n/**\n * Extracts and normalizes the client IP address from a Web-standard or Next.js Request.\n *\n * Security Model:\n * 1. When `trustProxy` is false:\n *    - All reverse-proxy headers (X-Forwarded-For, X-Real-IP, CF-Connecting-IP, etc.)\n *      and unverified platform properties are strictly ignored to prevent client IP spoofing attacks.\n *    - Only a verified Node.js TCP socket remote address (`socket.remoteAddress`) or an\n *      explicitly provided custom extractor function is accepted.\n *    - In environments without a direct TCP socket (e.g. serverless Web Requests without a trusted proxy),\n *      safe client IP identification cannot be guaranteed, and this function safely falls back to 'unknown'.\n *\n * 2. When `trustProxy` is true:\n *    - To prevent forged header injection across reverse proxies (e.g. an attacker sending CF-Connecting-IP\n *      to an Nginx server that does not strip it), Z-Shield strictly requires selecting an explicit trusted\n *      strategy via `getIp` or providing 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 (requires outer proxy header stripping).\n *      - Custom function: `(req) => string | null | undefined`\n *    - If `trustProxy` is true but no extraction strategy or custom function is configured,\n *      Z-Shield strictly refuses to guess across foreign proxy headers, and falls back safely to 'unknown'\n *      (or socket.remoteAddress if available).\n *\n * @param request - Incoming Web Request or NextLikeRequest\n * @param trustProxy - Whether reverse proxy headers are trusted\n * @param extractorOrStrategy - Trusted IP strategy name or custom extractor function\n * @returns Normalized client IP address or 'unknown'\n */\nexport function extractNextClientIp(\n  request: Request | NextLikeRequest,\n  trustProxy: boolean,\n  extractorOrStrategy?: NextClientIpExtractor | NextClientIpStrategy\n): string {\n  // 1. Custom extractor callback function takes precedence if provided by developer\n  if (typeof extractorOrStrategy === 'function') {\n    try {\n      const customIp = extractorOrStrategy(request);\n      if (typeof customIp === 'string' && customIp.trim().length > 0) {\n        const trimmed = customIp.trim();\n        if (isValidIp(trimmed)) {\n          return normalizeIp(trimmed);\n        }\n      }\n    } catch {\n      // Gracefully fall through on extractor errors\n    }\n    return 'unknown';\n  }\n\n  const reqWithIp = request as { ip?: unknown; socket?: { remoteAddress?: unknown } };\n\n  // 2. When trustProxy is false:\n  // Strictly ignore all reverse-proxy headers (X-Forwarded-For, X-Real-IP, etc.)\n  // and unverified platform headers to prevent client IP spoofing attacks.\n  if (!trustProxy) {\n    if (typeof reqWithIp.socket?.remoteAddress === 'string' && reqWithIp.socket.remoteAddress.length > 0) {\n      return normalizeIp(reqWithIp.socket.remoteAddress);\n    }\n    // If no direct TCP socket is available (e.g. serverless Web Request without trusted proxy),\n    // safe client IP identification cannot be guaranteed. Fallback to 'unknown'.\n    return 'unknown';\n  }\n\n  // 3. When trustProxy is true:\n  // An explicit trusted IP extraction strategy must be selected.\n  // Z-Shield strictly refuses to guess across foreign proxy headers to prevent\n  // forged header injection attacks (e.g. sending CF-Connecting-IP to an Nginx server).\n  if (typeof extractorOrStrategy === 'string') {\n    const strategy = extractorOrStrategy.toLowerCase().trim();\n\n    if (strategy === 'cf-connecting-ip' || strategy === 'cloudflare') {\n      const cfIp = getHeader(request, 'cf-connecting-ip');\n      if (cfIp) {\n        const candidate = cfIp.trim();\n        if (isValidIp(candidate)) {\n          return normalizeIp(candidate);\n        }\n      }\n      return 'unknown';\n    }\n\n    if (strategy === 'x-real-ip' || strategy === 'nginx') {\n      const xRealIp = getHeader(request, 'x-real-ip');\n      if (xRealIp) {\n        const candidate = xRealIp.trim();\n        if (isValidIp(candidate)) {\n          return normalizeIp(candidate);\n        }\n      }\n      return 'unknown';\n    }\n\n    if (strategy === 'true-client-ip' || strategy === 'akamai') {\n      const trueIp = getHeader(request, 'true-client-ip');\n      if (trueIp) {\n        const candidate = trueIp.trim();\n        if (isValidIp(candidate)) {\n          return normalizeIp(candidate);\n        }\n      }\n      return 'unknown';\n    }\n\n    if (strategy === 'x-forwarded-for') {\n      const xff = getHeader(request, 'x-forwarded-for');\n      if (xff) {\n        const candidates = xff.split(',').map(s => s.trim()).filter(Boolean);\n        for (const candidate of candidates) {\n          if (isValidIp(candidate)) {\n            return normalizeIp(candidate);\n          }\n        }\n      }\n      return 'unknown';\n    }\n  }\n\n  // 4. Fallback if no strategy matched or no proxy header was trusted:\n  // If a direct TCP socket is available, return it; otherwise fail safely to 'unknown'.\n  if (typeof reqWithIp.socket?.remoteAddress === 'string' && reqWithIp.socket.remoteAddress.length > 0) {\n    return normalizeIp(reqWithIp.socket.remoteAddress);\n  }\n\n  return 'unknown';\n}\n\n/**\n * Extracts pathname from a request URL safely.\n */\nfunction extractRequestPath(request: Request | NextLikeRequest): string {\n  if (!request.url) {\n    return '/';\n  }\n  try {\n    const parsed = new URL(request.url, 'http://localhost');\n    return parsed.pathname;\n  } catch {\n    return (request.url.split('?')[0] ?? '').split('#')[0] || '/';\n  }\n}\n\n/**\n * Merges rate-limiting headers into an existing Web Response.\n */\nfunction mergeResponseHeaders(\n  response: Response,\n  headersToMerge: Record<string, string>\n): Response {\n  if (!response) {\n    return response;\n  }\n\n  try {\n    for (const [key, value] of Object.entries(headersToMerge)) {\n      response.headers.set(key, value);\n    }\n    return response;\n  } catch {\n    const newHeaders = new Headers(response.headers);\n    for (const [key, value] of Object.entries(headersToMerge)) {\n      newHeaders.set(key, value);\n    }\n\n    const nullBodyStatuses = [101, 204, 205, 304];\n    const body =\n      nullBodyStatuses.includes(response.status)\n        ? null\n        : response.body;\n\n    return new Response(body, {\n      status: response.status,\n      statusText: response.statusText,\n      headers: newHeaders\n    });\n  }\n}\n\n/**\n * Creates standard HTTP 429 response when a request is blocked.\n */\nfunction createBlockedResponse(\n  retryAfter: number,\n  reason: string,\n  extraHeaders?: Record<string, string>,\n  customBuilder?: (info: { reason: string; retryAfter: number; clientIp: string }) => Response,\n  clientIp?: string\n): Response {\n  if (typeof customBuilder === 'function') {\n    try {\n      return customBuilder({\n        reason,\n        retryAfter,\n        clientIp: clientIp || 'unknown'\n      });\n    } catch {\n      // Fallback to standard response if custom builder throws\n    }\n  }\n\n  const headers: Record<string, string> = {\n    'Content-Type': 'application/json',\n    'Retry-After': String(retryAfter),\n    'X-Z-Shield-Blocked': '1',\n    ...extraHeaders\n  };\n\n  const body = {\n    error: 'Too Many Requests',\n    message: reason,\n    retryAfter\n  };\n\n  return new Response(JSON.stringify(body), {\n    status: 429,\n    headers\n  });\n}\n\n/**\n * Checks if the passed object is an existing ZShieldInstance.\n */\nfunction isZShieldInstance(val: unknown): val is ZShieldInstance {\n  return (\n    typeof val === 'object' &&\n    val !== null &&\n    'rateLimiter' in val &&\n    'detector' in val &&\n    'blockManager' in val &&\n    'logger' in val &&\n    'config' in val\n  );\n}\n\n/**\n * Factory for creating a Next.js App Router shield instance.\n *\n * Usage:\n *   import { createNextShield } from 'z-shield';\n *   const shield = createNextShield({ mode: 'protect', maxRequests: 50 });\n *\n *   export const GET = shield.protect(async (request) => {\n *     return Response.json({ message: 'Hello from protected API' });\n *   });\n *\n * @param optionsOrInstance - Configuration options or existing ZShieldInstance\n * @returns NextShieldInstance\n */\nexport function createNextShield(\n  optionsOrInstance?: NextShieldOptions | ZShieldConfig | ZShieldInstance,\n  adapterOptions?: NextShieldOptions\n): NextShieldInstance {\n  let config: ZShieldConfig;\n  let rateLimiter: RateLimiter;\n  let detector: Detector;\n  let blockManager: BlockManager;\n  let logger: Logger;\n  let customGetIp: NextClientIpExtractor | NextClientIpStrategy | undefined;\n  let customBlockResponse:\n    | ((info: { reason: string; retryAfter: number; clientIp: string }) => Response)\n    | undefined;\n\n  if (isZShieldInstance(optionsOrInstance)) {\n    config = optionsOrInstance.config;\n    rateLimiter = optionsOrInstance.rateLimiter;\n    detector = optionsOrInstance.detector;\n    blockManager = optionsOrInstance.blockManager;\n    logger = optionsOrInstance.logger;\n    if (adapterOptions?.getIp) {\n      customGetIp = adapterOptions.getIp;\n    }\n    if (adapterOptions?.customBlockResponse) {\n      customBlockResponse = adapterOptions.customBlockResponse;\n    }\n  } else {\n    const opts = optionsOrInstance || {};\n    config = resolveConfig(opts);\n    rateLimiter = new RateLimiter(config);\n    detector = new Detector({ rateLimiter, config });\n    blockManager = new BlockManager(config);\n    logger = new Logger(config);\n    if ('getIp' in opts && (typeof opts.getIp === 'function' || typeof opts.getIp === 'string')) {\n      customGetIp = opts.getIp;\n    }\n    if ('customBlockResponse' in opts && typeof opts.customBlockResponse === 'function') {\n      customBlockResponse = opts.customBlockResponse;\n    }\n  }\n\n  const check = async (\n    request: Request | NextLikeRequest\n  ): Promise<NextShieldCheckResult> => {\n    const pathname = extractRequestPath(request);\n    const method = (request.method || 'GET').toUpperCase();\n    const now = Date.now();\n\n    // 1. Route exclusion check\n    if (isRouteExcluded(pathname, config.excludeRoutes)) {\n      return {\n        blocked: false,\n        isExcluded: true,\n        clientIp: '',\n        headers: {}\n      };\n    }\n\n    // 2. Client IP extraction\n    const clientIp = extractNextClientIp(request, config.trustProxy, customGetIp);\n\n    // 3. BlockManager check\n    const isIpBlocked = blockManager.isBlocked(clientIp, now);\n    if (isIpBlocked) {\n      const blockInfo = blockManager.getBlockInfo(clientIp, now);\n      const reason = blockInfo ? blockInfo.reason : 'Administrative block';\n      const remainingMs = blockInfo ? blockInfo.remainingMs : 0;\n      const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));\n      const action = config.mode === 'protect' ? 'blocked' : 'warned';\n\n      void logger.log({\n        appName: config.appName,\n        type: 'blocked_ip',\n        severity: 'warning',\n        ip: clientIp,\n        method,\n        route: pathname,\n        reason,\n        action\n      });\n\n      const headers: Record<string, string> = {\n        'X-Z-Shield-Protected': '1',\n        'X-Z-Shield-Mode': config.mode,\n        'X-Z-Shield-Blocked': '1',\n        'X-Z-Shield-Reason': reason,\n        'Retry-After': String(retryAfterSeconds)\n      };\n\n      if (config.mode === 'protect') {\n        const blockedResponse = createBlockedResponse(\n          retryAfterSeconds,\n          'Your IP address has been temporarily blocked due to suspicious activity.',\n          headers,\n          customBlockResponse,\n          clientIp\n        );\n        return {\n          blocked: true,\n          isExcluded: false,\n          clientIp,\n          headers,\n          response: blockedResponse\n        };\n      }\n\n      // Monitor mode: mark warning header and allow request through\n      headers['X-Z-Shield-Suspicious'] = '1';\n      return {\n        blocked: false,\n        isExcluded: false,\n        clientIp,\n        headers\n      };\n    }\n\n    // 4. Rate Limiting assessment via Detector\n    const detection = detector.check(clientIp, request, now);\n    const rateLimitHeaders: Record<string, string> = {\n      'X-Z-Shield-Protected': '1',\n      'X-Z-Shield-Mode': config.mode,\n      'X-RateLimit-Limit': String(config.maxRequests),\n      'X-RateLimit-Remaining': String(detection.remaining),\n      'X-RateLimit-Reset': String(Math.ceil(detection.resetTime / 1000))\n    };\n\n    if (detection.isSuspicious) {\n      const action = config.mode === 'protect' ? 'blocked' : 'warned';\n      void logger.log({\n        appName: config.appName,\n        type: detection.type || 'rate_limit',\n        severity: detection.severity || 'warning',\n        ip: clientIp,\n        method,\n        route: pathname,\n        reason: detection.reason || 'Threshold exceeded',\n        action\n      });\n\n      rateLimitHeaders['X-Z-Shield-Suspicious'] = '1';\n      rateLimitHeaders['X-Z-Shield-Reason'] = detection.reason || 'Threshold exceeded';\n\n      if (config.mode === 'protect') {\n        if (config.autoBlock && isValidIp(clientIp)) {\n          blockManager.block(clientIp, config.blockDurationMs, detection.reason || 'Threshold exceeded', now);\n        }\n\n        const retryAfterSeconds = Math.max(1, Math.ceil((detection.resetTime - now) / 1000));\n        rateLimitHeaders['Retry-After'] = String(retryAfterSeconds);\n        rateLimitHeaders['X-Z-Shield-Blocked'] = '1';\n\n        const blockedResponse = createBlockedResponse(\n          retryAfterSeconds,\n          'Rate limit exceeded. Please wait before retrying.',\n          rateLimitHeaders,\n          customBlockResponse,\n          clientIp\n        );\n\n        return {\n          blocked: true,\n          isExcluded: false,\n          clientIp,\n          detection,\n          headers: rateLimitHeaders,\n          response: blockedResponse\n        };\n      }\n    }\n\n    // 5. Allowed / normal request\n    return {\n      blocked: false,\n      isExcluded: false,\n      clientIp,\n      detection,\n      headers: rateLimitHeaders\n    };\n  };\n\n  const protect = <TContext = unknown>(\n    handler: (request: Request, context?: TContext) => Promise<Response> | Response\n  ): ((request: Request, context?: TContext) => Promise<Response>) => {\n    return async (request: Request, context?: TContext): Promise<Response> => {\n      const checkResult = await check(request);\n\n      if (checkResult.blocked && checkResult.response) {\n        return checkResult.response;\n      }\n\n      const response = await handler(request, context);\n\n      if (checkResult.isExcluded || Object.keys(checkResult.headers).length === 0) {\n        return response;\n      }\n\n      return mergeResponseHeaders(response, checkResult.headers);\n    };\n  };\n\n  return {\n    config,\n    rateLimiter,\n    detector,\n    blockManager,\n    logger,\n    check,\n    protect,\n\n    // Programmatic Block API\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\n/**\n * Higher-order function wrapping a Next.js App Router route handler with Z-Shield protection.\n *\n * Usage:\n *   import { withNextShield } from 'z-shield';\n *\n *   export const GET = withNextShield(async (req) => {\n *     return Response.json({ ok: true });\n *   }, { mode: 'protect', maxRequests: 50 });\n *\n * @param handler - Next.js Route Handler function\n * @param options - Z-Shield configuration options or existing shield instance\n * @returns Wrapped route handler\n */\nexport function withNextShield<TContext = unknown>(\n  handler: (request: Request, context?: TContext) => Promise<Response> | Response,\n  options?: NextShieldOptions | ZShieldConfig | NextShieldInstance | ZShieldInstance,\n  adapterOptions?: NextShieldOptions\n): (request: Request, context?: TContext) => Promise<Response> {\n  const shield =\n    options && 'protect' in options\n      ? (options as NextShieldInstance)\n      : createNextShield(\n          options as NextShieldOptions | ZShieldConfig | ZShieldInstance | undefined,\n          adapterOptions\n        );\n\n  return shield.protect(handler);\n}\n\nexport type {\n  NextShieldOptions,\n  NextShieldCheckResult,\n  NextShieldInstance,\n  NextRouteHandler,\n  NextClientIpStrategy,\n  NextClientIpExtractor,\n  NextLikeRequest\n};\n\n"]}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,75 @@
+import type { RateLimitStatus, ZShieldConfig, ZShieldOptions } from './types';
+export interface RateLimiterOptions {
+    windowMs?: number;
+    maxRequests?: number;
+    maxTrackedIps?: number;
+}
+/**
+ * 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.
+ */
+export declare class RateLimiter {
+    readonly windowMs: number;
+    readonly maxRequests: number;
+    readonly maxTrackedIps: number;
+    private readonly records;
+    /**
+     * @param options - Limiter options or resolved configuration
+     */
+    constructor(options?: RateLimiterOptions | ZShieldConfig | ZShieldOptions);
+    /**
+     * 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: string, now?: number): RateLimitStatus;
+    /**
+     * 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: string, now?: number): RateLimitStatus;
+    /**
+     * Resets counter for a specific IP.
+     * @param ip - Client IP address
+     */
+    reset(ip: string): void;
+    /**
+     * Clears all tracked IP records from memory.
+     */
+    clear(): void;
+    /**
+     * Number of IPs currently stored in memory.
+     */
+    get size(): number;
+    /**
+     * 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?: number): number;
+    /**
+     * Evicts the oldest entry to maintain bounded memory.
+     * Evicts the least recently used entry to strictly uphold memory bound.
+     *
+     * @param _now - Current timestamp
+     */
+    private _evictOldest;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD;;OAEG;IACH,YAAY,OAAO,GAAE,kBAAkB,GAAG,aAAa,GAAG,cAAmB,EAM5E;IAED;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe,CA0C5D;IAED;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe,CAmBzD;IAED;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAGtB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAS7C;IAED;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAQrB"}