z-shield 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # 🛡️ Z-Shield
 
-> Lightweight, zero-dependency API abuse detection, rate limiting, and security event logging toolkit for Node.js and Express backends.
+> Lightweight, zero-dependency API abuse detection, rate limiting, and security event logging toolkit for Node.js and Express backends by Zeesu Royalist.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org)
@@ -15,6 +15,7 @@
   - [What Z-Shield Does NOT Do](#what-z-shield-does-not-do)
 - [Requirements & Installation](#requirements--installation)
 - [Quick Start: Express Integration](#quick-start-express-integration)
+- [Quick Start: Next.js App Router Integration](#quick-start-nextjs-app-router-integration)
 - [Monitor Mode vs. Protect Mode](#monitor-mode-vs-protect-mode)
 - [Configuration Reference](#configuration-reference)
 - [Rate Limiting & HTTP Headers](#rate-limiting--http-headers)
@@ -114,6 +115,51 @@ app.listen(3000, () => {
 
 ---
 
+## Quick Start: Next.js App Router Integration
+
+Z-Shield provides native compatibility for Next.js App Router route handlers (`app/api/.../route.ts`) using Web-standard `Request` and `Response` objects.
+
+```typescript
+// app/api/protected/route.ts
+import { withNextShield } from 'z-shield';
+
+// CRITICAL: Z-Shield requires the Node.js runtime for file-based event logging.
+// It cannot run in the Edge runtime.
+export const runtime = 'nodejs';
+
+export const GET = withNextShield(
+  async (request: Request) => {
+    return Response.json({
+      success: true,
+      message: 'Access granted to protected Next.js API route'
+    });
+  },
+  {
+    mode: 'protect',
+    maxRequests: 50,
+    windowMs: 60000,
+    // Enable trustProxy and select your trusted reverse-proxy strategy
+    trustProxy: true,
+    getIp: 'cloudflare', // 'cloudflare' | 'x-real-ip' | 'x-forwarded-for' | 'akamai' | (req) => ...
+    appName: 'my-nextjs-app'
+  }
+);
+```
+
+### Next.js Architectural Notes
+- **Node.js Runtime Requirement**: Z-Shield relies on Node.js filesystem APIs for non-blocking JSONL event logging and `node:net` for strict IP validation. Always declare `export const runtime = 'nodejs';`.
+- **Trusted Proxies & `getIp` Strategy**:
+  When deploying behind reverse proxies, set `trustProxy: true` AND explicitly specify your provider's extraction strategy using `getIp`:
+  - `'cloudflare'` / `'cf-connecting-ip'`: Inspects only `CF-Connecting-IP`.
+  - `'nginx'` / `'x-real-ip'`: Inspects only `X-Real-IP`.
+  - `'akamai'` / `'true-client-ip'`: Inspects only `True-Client-IP`.
+  - `'x-forwarded-for'`: Inspects the first valid IP from `X-Forwarded-For` (requires outermost reverse proxy to strip or sanitize client-provided headers).
+  - Custom function: `getIp: (req) => string | null | undefined`.
+  *Fail-Safe Behavior*: If `trustProxy: true` is configured without specifying a `getIp` strategy, Z-Shield strictly refuses to guess across foreign proxy headers and safely falls back to `'unknown'` (or direct TCP socket if available). Unconfigured reverse-proxy headers and unverified platform properties are never trusted.
+- **Process-Local Memory in Serverless**: Rate limit counters and temporary IP blocks are stored in-memory per Node.js process (bounded by LRU). In serverless environments, each active instance tracks traffic locally.
+
+---
+
 ## Monitor Mode vs. Protect Mode
 
 Z-Shield provides two operational modes:
@@ -172,12 +218,16 @@ const shield = createShield({
   autoBlock: false,
 
   // Whether to trust reverse-proxy headers (e.g. X-Forwarded-For)
-  // WARNING: Set to true only if behind a verified reverse proxy
+  // WARNING: Set to true only if behind a verified reverse proxy.
+  // In Next.js App Router, also pair with 'getIp' strategy (e.g. 'cloudflare', 'nginx', 'x-forwarded-for')
   trustProxy: false,
 
   // Array of route prefixes that bypass tracking
   excludeRoutes: ['/health', '/favicon.ico'],
 
+  // Maximum number of pending asynchronous log writes allowed in memory before dropping
+  maxLogQueueSize: 1000,
+
   // Optional custom error callback for failed log writes: (err, event) => void
   onLogError: null
 });
@@ -300,13 +350,31 @@ npx z-shield block 198.51.100.1 --duration 10m
 npx z-shield unblock 198.51.100.1
 ```
 
+### Log Directory Resolution & Environment Variables
+By default, the CLI looks for logs in `.z-shield-logs/events.jsonl` in your current working directory. You can customize the log directory using either the CLI flag or environment variable:
+
+1. **CLI Flag (`--log-dir`)** (Highest precedence):
+   ```bash
+   npx z-shield status --log-dir /var/log/my-app
+   npx z-shield logs --log-dir /var/log/my-app
+   ```
+2. **Environment Variable (`Z_SHIELD_LOG_DIR`)** (Second precedence):
+   ```bash
+   export Z_SHIELD_LOG_DIR=/var/log/my-app
+   npx z-shield status
+   ```
+3. **Default Location** (Fallback):
+   `./.z-shield-logs/events.jsonl`
+
+When no log file is found, the CLI prints a helpful status message with the checked path and guidance on how to run your application or specify custom paths.
+
 ### Process-Local Architecture Notice
-Z-Shield stores active IP counters and temporary blocks **in server memory (RAM)** inside your Express application process.
+Z-Shield stores active IP counters and temporary blocks **in server memory (RAM)** inside your Express or Next.js application process.
 
-Because the CLI runs in an independent Node.js process, it cannot reach into your Express application's memory heap to alter active blocks. When you execute `npx z-shield block`, the CLI:
+Because the CLI runs in an independent Node.js process, it cannot reach into your running application's memory heap to alter active in-memory counters. When you execute `npx z-shield block`, the CLI:
 1. Validates the IP and duration.
-2. Writes an audit entry to `.z-shield-logs/events.jsonl`.
-3. Displays the exact JavaScript snippet to invoke inside your Express code (`shield.block(...)`).
+2. Writes an audit entry to the active security log file.
+3. Displays the exact programmatic snippet to invoke inside your application code (`shield.block(...)`).
 
 ---
 
@@ -336,6 +404,55 @@ const shield = createShield({
 app.use(shield.middleware);
 ```
 
+### Next.js Client IP Extraction & Reverse Proxy Requirements
+In Next.js App Router route handlers, standard Web `Request` objects do not carry Node.js TCP sockets. Z-Shield enforces the following security model:
+
+1. **`trustProxy: false` (Default)**:
+   - Untrusted reverse-proxy headers (`X-Forwarded-For`, `X-Real-IP`, `CF-Connecting-IP`, `True-Client-IP`, etc.) and unverified platform properties are strictly ignored to prevent client IP spoofing attacks.
+   - If a direct Node.js TCP socket is available (`req.socket.remoteAddress`), it is used.
+   - **Deployment Limitation**: In environments without a direct TCP socket (e.g. serverless functions without trusted proxies), safe client IP identification cannot be guaranteed, and Z-Shield safely falls back to `'unknown'`.
+
+2. **`trustProxy: true`**:
+   - To prevent forged header injection across reverse proxies (e.g. an attacker sending `CF-Connecting-IP` to an Nginx server that passes unmanaged headers through), Z-Shield **strictly requires selecting an explicit trusted proxy strategy via `getIp`** (or providing a custom function):
+     - `'cloudflare'` | `'cf-connecting-ip'`: Inspects only `CF-Connecting-IP` and strictly ignores all other proxy headers.
+     - `'nginx'` | `'x-real-ip'`: Inspects only `X-Real-IP` and strictly ignores all other proxy headers.
+     - `'akamai'` | `'true-client-ip'`: Inspects only `True-Client-IP` and strictly ignores all other proxy headers.
+     - `'x-forwarded-for'`: Inspects only `X-Forwarded-For`, parsing candidates and taking the first valid IP.
+     - Custom extractor: `(req: Request) => string | null | undefined`.
+   - **Crucial Reverse-Proxy Requirement**: When using `'x-forwarded-for'` with an appending reverse proxy (such as default Nginx `$proxy_add_x_forwarded_for`), your edge proxy **MUST** strip client-supplied `X-Forwarded-For` headers at network ingress; otherwise, an attacker can prepend a forged IP. If your proxy cannot strip incoming headers, configure `'x-real-ip'` or provide a custom `getIp` function.
+   - **Fail-Safe Behavior**: If `trustProxy: true` is configured without specifying `getIp`, Z-Shield strictly refuses to guess which header is authentic, and safely falls back to `'unknown'` (or direct TCP socket if available). Unconfigured reverse-proxy headers and unverified platform properties are never trusted.
+
+> [!WARNING]
+> **CRITICAL: The Serverless `'unknown'` Shared Bucket Trap**
+>
+> In serverless environments (Vercel Serverless Functions, AWS Lambda, Cloudflare Pages), requests arrive without an underlying direct Node.js TCP socket.
+>
+> If you leave `trustProxy: false` (or set `trustProxy: true` without a valid `getIp`), all incoming client IPs evaluate to `'unknown'`. Consequently, **all global visitors share one single rate-limit counter**. If `maxRequests` is exceeded or `autoBlock: true` triggers on `'unknown'`, **EVERY visitor worldwide will receive HTTP 429**, causing a self-inflicted Denial of Service (DoS) of your entire serverless API.
+>
+> **Remedy**: Always set `trustProxy: true` and specify the `getIp` strategy matching your hosting infrastructure:
+>
+> ```typescript
+> // Vercel: Vercel edge strips/sanitizes X-Forwarded-For at ingress
+> getIp: 'x-forwarded-for' // or 'x-real-ip'
+>
+> // Cloudflare: When application is strictly behind Cloudflare
+> getIp: 'cloudflare' // strictly inspects CF-Connecting-IP
+>
+> // AWS CloudFront / ALB:
+> getIp: (req) => req.headers.get('cloudfront-viewer-address')?.split(':')[0]
+>   || req.headers.get('x-forwarded-for')?.split(',')[0]?.trim()
+>
+> // Nginx Reverse Proxy (configured with proxy_set_header X-Real-IP $remote_addr):
+> getIp: 'nginx' // strictly inspects X-Real-IP
+> ```
+
+> [!CAUTION]
+> **Proxy Headers Are Trustworthy ONLY When Your Infrastructure Sanitizes Them**
+>
+> **No single proxy strategy is safe for every hosting provider!** HTTP headers (`CF-Connecting-IP`, `X-Real-IP`, `X-Forwarded-For`, `True-Client-IP`) are untrusted client metadata unless your hosting proxy explicitly sets or sanitizes them.
+>
+> Never configure a strategy that does not match your actual ingress infrastructure (e.g. configuring `getIp: 'cloudflare'` on AWS or Bare Metal without Cloudflare allows anyone on the internet to send a forged `CF-Connecting-IP` header). Furthermore, always ensure direct origin access is firewalled so traffic cannot bypass your proxy.
+
 ---
 
 ## Known Limitations

package/dist/block-manager.d.ts

@@ -0,0 +1,134 @@
+import type { BlockRecord, ZShieldConfig, ZShieldOptions } from './types';
+export interface BlockManagerOptions {
+    blockDurationMs?: number;
+    maxBlockedIps?: number;
+}
+export interface BlockInfo {
+    ip: string;
+    blockedAt: number;
+    expiresAt: number;
+    remainingMs: number;
+    reason: string;
+}
+/**
+ * Canonicalizes an IPv6 address string according to RFC 5952.
+ * - Parses 16-bit hextets
+ * - Handles embedded IPv4 in IPv6 (including IPv4-mapped IPv6)
+ * - Normalizes loopback ('::1' and '0:0:0:0:0:0:0:1') to '127.0.0.1'
+ * - Normalizes IPv4-mapped addresses to standard IPv4
+ * - Compresses the longest run of 2 or more zeros with '::' (first run on tie)
+ * - Lowers all hexadecimal characters and removes leading zeros in each field
+ *
+ * @param ip - Valid IPv6 address string
+ * @returns Canonicalized representation
+ */
+export declare function canonicalizeIpv6(ip: string): string;
+/**
+ * Normalizes an IP address for consistent comparison across IPv4 and IPv6.
+ * - Trims whitespace
+ * - Canonicalizes IPv6 addresses according to RFC 5952 (zero compression, lowercase)
+ * - Unmaps all IPv4-mapped IPv6 variations (e.g. '::ffff:192.168.1.1' -> '192.168.1.1')
+ * - Normalizes all IPv6 loopback variants ('::1', '0:0:0:0:0:0:0:1') to '127.0.0.1'
+ * - Preserves invalid strings without converting them into fake valid IPs
+ *
+ * @param ip - Raw client IP candidate
+ * @returns Normalized IP or 'unknown'
+ */
+export declare function normalizeIp(ip: unknown): string;
+/**
+ * Validates whether an IP address is a valid IPv4 or IPv6 string.
+ * Uses Node.js built-in net.isIP (returns 4 for IPv4, 6 for IPv6, 0 for invalid).
+ *
+ * @param ip - IP candidate string
+ * @returns True if valid IPv4 or IPv6
+ */
+export declare function isValidIp(ip: unknown): boolean;
+/**
+ * Parses block duration into milliseconds.
+ * Supports numbers (milliseconds) or human-readable strings ('30s', '10m', '1h', '2d').
+ *
+ * @param duration - Numeric ms or formatted string
+ * @returns Duration in milliseconds
+ */
+export declare function parseDuration(duration: number | string): number;
+/**
+ * BlockManager - In-Memory Temporary IP Block Management
+ *
+ * Characteristics:
+ * - Process-Local: Blocks are held in RAM. They do NOT survive server restarts.
+ * - Automatic Expiry: Block entries are checked against their expiration timestamp.
+ * - Bounded Memory: Uses LRU eviction when `maxBlockedIps` is reached to prevent memory exhaustion.
+ * - No Background Timers: Uses passive/lazy expiration on access to keep Node.js event loop idle.
+ */
+export declare class BlockManager {
+    readonly defaultDurationMs: number;
+    readonly maxBlockedIps: number;
+    private readonly blocks;
+    /**
+     * @param options - Block manager options or resolved config
+     */
+    constructor(options?: BlockManagerOptions | ZShieldConfig | ZShieldOptions);
+    /**
+     * Temporarily blocks an IP address.
+     *
+     * @param ip - Valid IPv4 or IPv6 address
+     * @param duration - Duration in ms or string ('10m')
+     * @param reason - Reason for block
+     * @param now - Current timestamp (injectable for testing)
+     * @returns Created block record
+     */
+    block(ip: string, duration?: number | string, reason?: string, now?: number): BlockRecord;
+    /**
+     * Manually unblocks an IP address.
+     *
+     * @param ip - Client IP
+     * @returns True if IP was unblocked, false if it was not blocked
+     */
+    unblock(ip: string): boolean;
+    /**
+     * Checks whether an IP address is currently blocked.
+     * Expired blocks are lazily pruned.
+     *
+     * @param ip - Client IP
+     * @param now - Current timestamp
+     * @returns True if actively blocked
+     */
+    isBlocked(ip: string | undefined | null, now?: number): boolean;
+    /**
+     * Retrieves active block details for an IP, or null if not blocked/expired.
+     *
+     * @param ip - Client IP
+     * @param now - Current timestamp
+     * @returns Block information or null
+     */
+    getBlockInfo(ip: string, now?: number): BlockInfo | null;
+    /**
+     * Returns a list of all currently active blocked IPs.
+     *
+     * @param now - Current timestamp
+     * @returns Array of active block records
+     */
+    listBlocks(now?: number): BlockInfo[];
+    /**
+     * Scans and purges any expired blocks from memory.
+     *
+     * @param now - Current timestamp
+     * @returns Number of purged blocks
+     */
+    pruneExpired(now?: number): number;
+    /**
+     * Clears all blocks from memory.
+     */
+    clear(): void;
+    /**
+     * Number of IPs currently stored in memory.
+     */
+    get size(): number;
+    /**
+     * Evicts the oldest entry to strictly uphold maxBlockedIps limit.
+     *
+     * @param _now - Current timestamp
+     */
+    private _evictOldest;
+}
+//# sourceMappingURL=block-manager.d.ts.map

package/dist/block-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-manager.d.ts","sourceRoot":"","sources":["../src/block-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CA4HnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CA8B/C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAM9C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAwC/D;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD;;OAEG;IACH,YAAY,OAAO,GAAE,mBAAmB,GAAG,aAAa,GAAG,cAAmB,EAK7E;IAED;;;;;;;;OAQG;IACH,KAAK,CACH,EAAE,EAAE,MAAM,EACV,QAAQ,GAAE,MAAM,GAAG,MAA+B,EAClD,MAAM,GAAE,MAA+B,EACvC,GAAG,GAAE,MAAmB,GACvB,WAAW,CA8Bb;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK3B;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAmB1E;IAED;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,SAAS,GAAG,IAAI,CAkBnE;IAED;;;;;OAKG;IACH,UAAU,CAAC,GAAG,GAAE,MAAmB,GAAG,SAAS,EAAE,CAahD;IAED;;;;;OAKG;IACH,YAAY,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAS7C;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAQrB"}