@zudojs/security 1.0.0 → 1.1.0

package/dist/rateLimit/rateLimit.core.js

@@ -3,21 +3,30 @@
  *
  * Implements sliding window rate limiting to prevent abuse.
  */
+import { createIpKeyGenerator, ipRateLimitKey } from "./rateLimit.clientKey.js";
 /** Default window: 1 minute. */
 const DEFAULT_WINDOW_MS = 60_000;
 /** Default rate limit message. */
 const DEFAULT_MESSAGE = "Too many requests";
 /** Default cap on tracked keys before least-recently-seen eviction. */
 const DEFAULT_MAX_KEYS = 100_000;
+/** Largest delay `setInterval` honours without overflowing to 1 ms. */
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 /**
  * Default key generator using IP address.
  *
+ * The port is stripped, IPv4-mapped IPv6 is keyed as IPv4, and IPv6 is
+ * bucketed by /64 (see {@link createIpKeyGenerator} for another prefix).
+ *
  * @param request - The rate limit request.
  * @returns The rate limit key.
+ * @throws {ConfigurationError} when `request.ip` is missing or not an IP
+ *   address; requests used to share a single `"unknown"` bucket.
  */
 export function defaultKeyGenerator(request) {
-    return request.ip ?? "unknown";
+    return ipKeyGenerator(request);
 }
+const ipKeyGenerator = createIpKeyGenerator();
 /**
  * Default handler when rate limit is exceeded.
  *
@@ -79,6 +88,8 @@ export function createRateLimiter(config) {
     }
     const store = new Map();
     const keyGenerator = config.keyGenerator ?? defaultKeyGenerator;
+    /** Lets `reset`/`getCount` take a raw address under the default keys. */
+    const storeKey = (key) => config.keyGenerator || store.has(key) ? key : (ipRateLimitKey(key) ?? key);
     // `config.message` was declared and documented but never read: the default
     // handler always emitted the built-in string.
     const message = config.message ?? DEFAULT_MESSAGE;
@@ -88,8 +99,11 @@ export function createRateLimiter(config) {
         });
     const skip = config.skip;
     const maxKeys = config.maxKeys ?? DEFAULT_MAX_KEYS;
-    // Cleanup old entries periodically. Bounded so a very short window does not
-    // schedule a near-continuous timer.
+    // Cleanup old entries periodically. Bounded below so a very short window
+    // does not schedule a near-continuous timer, and above because Node stores
+    // timer delays as a signed 32-bit integer: a delay past 2^31 - 1 ms (about
+    // 24.8 days) is silently replaced with 1 ms, so a month-long window used to
+    // sweep the whole store a thousand times a second.
     const cleanupInterval = setInterval(() => {
         const cutoff = Date.now() - config.windowMs;
         for (const [key, entry] of store) {
@@ -97,7 +111,7 @@ export function createRateLimiter(config) {
                 store.delete(key);
             }
         }
-    }, Math.max(config.windowMs, 1_000));
+    }, Math.min(Math.max(config.windowMs, 1_000), MAX_TIMER_DELAY_MS));
     // Allow cleanup to not keep process alive
     if (cleanupInterval.unref) {
         cleanupInterval.unref();
@@ -107,16 +121,20 @@ export function createRateLimiter(config) {
      *
      * Without this, a caller rotating the key (a spoofed forwarding header, a
      * per-request identifier) grows the map without limit between sweeps.
+     *
+     * The store is kept in recency order — `check` re-inserts an entry on every
+     * hit — so the oldest key is always the first one iterated and eviction is
+     * O(1). It used to copy and sort the whole map on every new key past the
+     * cap, which turned the defence against key rotation into an O(n log n)
+     * cost per rotated request: the attack it was meant to bound became the
+     * cheapest way to burn the CPU.
      */
     function evictIfNeeded() {
-        if (store.size <= maxKeys)
-            return;
-        const entries = [...store.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen);
-        const excess = store.size - maxKeys;
-        for (let i = 0; i < excess; i++) {
-            const entry = entries[i];
-            if (entry)
-                store.delete(entry[0]);
+        while (store.size > maxKeys) {
+            const oldest = store.keys().next();
+            if (oldest.done)
+                break;
+            store.delete(oldest.value);
         }
     }
     /**
@@ -141,6 +159,11 @@ export function createRateLimiter(config) {
             store.set(key, entry);
             evictIfNeeded();
         }
+        else {
+            // Move to the most-recent end so eviction order stays least-recent-first.
+            store.delete(key);
+            store.set(key, entry);
+        }
         // Prune everything that has slid out of the window.
         const timestamps = entry.timestamps.filter((t) => t > windowStart);
         entry.lastSeen = now;
@@ -177,7 +200,7 @@ export function createRateLimiter(config) {
      * Resets the rate limit for a specific key.
      */
     function reset(key) {
-        store.delete(key);
+        store.delete(storeKey(key));
     }
     /**
      * Clears all rate limit data.
@@ -189,7 +212,7 @@ export function createRateLimiter(config) {
      * Gets the current count for a key.
      */
     function getCount(key) {
-        const entry = store.get(key);
+        const entry = store.get(storeKey(key));
         if (!entry)
             return 0;
         const windowStart = Date.now() - config.windowMs;
@@ -215,74 +238,4 @@ export function createRateLimiter(config) {
         },
     };
 }
-/**
- * Extracts the client IP from request headers.
- *
- * **Forwarding headers are not trusted by default.** Any client can send
- * `X-Forwarded-For`, so taking its leftmost entry — the historical behaviour —
- * hands the caller control of their own rate-limit bucket, and rotating it
- * defeats the limiter entirely. Pass `trustProxy` set to the number of proxies
- * you actually run, together with the socket's `remoteAddress`.
- *
- * @param headers - Request headers.
- * @param options - Proxy trust configuration.
- * @returns The client IP address, or "unknown".
- */
-export function extractClientIp(headers, options) {
-    const trustProxy = options?.trustProxy ?? 0;
-    const fallback = options?.remoteAddress ?? "unknown";
-    if (trustProxy <= 0) {
-        return fallback;
-    }
-    const raw = lookupHeader(headers, "x-forwarded-for");
-    if (raw !== undefined) {
-        const chain = raw
-            .split(",")
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0);
-        // Walk in from the right: index 0 from the end is the address our own
-        // outermost proxy observed, and each additional trusted hop steps left.
-        const index = chain.length - trustProxy;
-        const candidate = chain[Math.max(0, index)];
-        if (candidate && isPlausibleIp(candidate)) {
-            return candidate;
-        }
-    }
-    const realIp = lookupHeader(headers, "x-real-ip");
-    if (realIp !== undefined && isPlausibleIp(realIp.trim())) {
-        return realIp.trim();
-    }
-    return fallback;
-}
-/** Case-insensitive header lookup that flattens repeated fields. */
-function lookupHeader(headers, name) {
-    for (const key of Object.keys(headers)) {
-        if (key.toLowerCase() !== name)
-            continue;
-        const value = headers[key];
-        if (typeof value === "string")
-            return value;
-        if (Array.isArray(value) && value.length > 0)
-            return value.join(",");
-    }
-    return undefined;
-}
-/**
- * Rejects values that are not addresses at all.
- *
- * A forwarding header is text, and a hostname or arbitrary string in it would
- * otherwise become a rate-limit key of the attacker's choosing.
- */
-function isPlausibleIp(value) {
-    const host = value.startsWith("[")
-        ? value.slice(1, value.indexOf("]") === -1 ? undefined : value.indexOf("]"))
-        : value.split(":").length > 2
-            ? value
-            : (value.split(":")[0] ?? value);
-    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) {
-        return host.split(".").every((octet) => Number(octet) <= 255);
-    }
-    // Any hex-and-colon string is accepted as an IPv6 candidate.
-    return /^[0-9a-fA-F:]+$/.test(host) && host.includes(":");
-}
 //# sourceMappingURL=rateLimit.core.js.map

package/dist/rateLimit/rateLimit.namespace.d.ts

@@ -3,7 +3,8 @@
  *
  * Convenience namespace for rate limiting utilities.
  */
-import { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp } from "./rateLimit.core.js";
+import { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter } from "./rateLimit.core.js";
+import { extractClientIp } from "./rateLimit.clientIp.js";
 export declare const rateLimit: {
     defaultKeyGenerator: typeof defaultKeyGenerator;
     defaultHandler: typeof defaultHandler;

package/dist/rateLimit/rateLimit.namespace.js

@@ -3,7 +3,8 @@
  *
  * Convenience namespace for rate limiting utilities.
  */
-import { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
+import { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, } from "./rateLimit.core.js";
+import { extractClientIp } from "./rateLimit.clientIp.js";
 export const rateLimit = {
     defaultKeyGenerator,
     defaultHandler,

package/dist/types/security.type.d.ts

@@ -207,7 +207,7 @@ export declare const PROTOTYPE_POLLUTION_KEYS: readonly ["__proto__", "construct
  *
  * Like {@link XSS_PATTERNS}, none carries the `g` flag — see the note there.
  */
-export declare const SQL_INJECTION_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+export declare const SQL_INJECTION_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
 /**
  * Common XSS patterns.
  *

package/dist/types/security.type.js

@@ -22,6 +22,9 @@ export const SQL_INJECTION_PATTERNS = [
     /(\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|EXEC|EXECUTE|UNION|FETCH|DECLARE|TRUNCATE|COMMENT|ALTER)\b)/i,
     /(--|#|\/\*|\*\/)/,
     /('\s*(OR|AND)\s*')/i,
+    /'\s*(OR|AND)\b/i,
+    /'\s*\|\|/,
+    /\b(PG_SLEEP|SLEEP|BENCHMARK)\s*\(|\bWAITFOR\s+DELAY\b/i,
     /(;\s*(DROP|DELETE|INSERT|UPDATE))/i,
 ];
 /**

package/dist/url/index.d.ts

@@ -3,4 +3,5 @@
  */
 export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url.core.js";
 export type { RequestTargetConfig } from "./url.core.js";
+export { expandIpv6, embeddedIpv4, isNonPublicIpv6Range, } from "./url.ipv6.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/url/index.js

@@ -2,4 +2,5 @@
  * @zudojs/security — URL Validation Barrel
  */
 export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url.core.js";
+export { expandIpv6, embeddedIpv4, isNonPublicIpv6Range, } from "./url.ipv6.js";
 //# sourceMappingURL=index.js.map

package/dist/url/url.core.js

@@ -4,6 +4,7 @@
  * Validates and normalizes URLs, prevents path traversal attacks,
  * and ensures request targets are safe.
  */
+import { embeddedIpv4, expandIpv6, isNonPublicIpv6Range, } from "./url.ipv6.js";
 /** Default maximum URL length. */
 const DEFAULT_MAX_URL_LENGTH = 2048;
 /** Default allowed protocols. */
@@ -301,36 +302,20 @@ function isPrivateIpv4(octets) {
 /**
  * True when an IPv6 hostname (already stripped of brackets) is private.
  *
- * Also unwraps IPv4-mapped and IPv4-compatible forms, so `::ffff:127.0.0.1`
- * is recognised as loopback rather than treated as an opaque v6 address.
+ * Every form that embeds an IPv4 address — IPv4-compatible `::a.b.c.d`,
+ * mapped `::ffff:a.b.c.d`, translated `::ffff:0:a.b.c.d`, NAT64
+ * `64:ff9b::a.b.c.d` and 6to4 `2002::/16` — is judged as that IPv4
+ * address, whichever spelling it arrives in (WHATWG serialises
+ * `[::127.0.0.1]` as `[::7f00:1]`). An unparseable literal fails closed.
  */
 function isPrivateIpv6(hostname) {
-    const host = hostname.toLowerCase();
-    if (host === "::1" || host === "::" || host === "::0")
+    const groups = expandIpv6(hostname);
+    if (!groups)
         return true;
-    // IPv4-mapped (::ffff:127.0.0.1) and IPv4-compatible (::127.0.0.1)
-    const mapped = /^::(?:ffff:)?(\d{1,3}(?:\.\d{1,3}){3})$/.exec(host);
-    if (mapped?.[1]) {
-        const octets = parseIpv4(mapped[1]);
-        return octets ? isPrivateIpv4(octets) : true;
-    }
-    // Hex-form IPv4-mapped: ::ffff:7f00:1
-    const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-    if (hexMapped?.[1] && hexMapped[2]) {
-        const high = parseInt(hexMapped[1], 16);
-        const low = parseInt(hexMapped[2], 16);
-        const octets = [high >> 8, high & 0xff, low >> 8, low & 0xff];
-        return isPrivateIpv4(octets);
-    }
-    const firstGroup = host.split(":")[0] ?? "";
-    const leading = parseInt(firstGroup.padEnd(4, "0"), 16);
-    // fc00::/7 unique local
-    if ((leading & 0xfe00) === 0xfc00)
-        return true;
-    // fe80::/10 link-local
-    if ((leading & 0xffc0) === 0xfe80)
-        return true;
-    return false;
+    const embedded = embeddedIpv4(groups);
+    if (embedded)
+        return isPrivateIpv4(embedded);
+    return isNonPublicIpv6Range(groups);
 }
 /**
  * Hostnames that resolve inside the local network or to a metadata service.

package/dist/url/url.ipv6.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @zudojs/security — IPv6 literal parsing and embedded-IPv4 extraction.
+ */
+/**
+ * Expands an IPv6 address into its eight 16-bit groups.
+ *
+ * Accepts the compressed (`::`), dotted-tail (`::ffff:1.2.3.4`) and zoned
+ * (`fe80::1%eth0`) forms.
+ *
+ * @returns The groups, or `undefined` for a non-IPv6 input.
+ */
+export declare function expandIpv6(address: string): number[] | undefined;
+/**
+ * The IPv4 address an IPv6 address stands for, when it is one of the
+ * embedding forms, so that it can be judged as that IPv4 address.
+ *
+ * - `::a.b.c.d` (IPv4-compatible, `::/96`, which also covers `::` and `::1`)
+ * - `::ffff:a.b.c.d` (IPv4-mapped, `::ffff:0:0/96`)
+ * - `::ffff:0:a.b.c.d` (IPv4-translated, `::ffff:0:0:0/96`)
+ * - `64:ff9b::a.b.c.d` (NAT64 well-known prefix, `64:ff9b::/96`)
+ * - `2002:aabb:ccdd::` (6to4, `2002::/16`)
+ *
+ * WHATWG URL parsing rewrites `[::127.0.0.1]` to `[::7f00:1]`, so matching
+ * on the dotted spelling (as the old regexes did) missed every one of these.
+ *
+ * @returns The four octets, or `undefined` when nothing is embedded.
+ */
+export declare function embeddedIpv4(groups: readonly number[]): number[] | undefined;
+/**
+ * True for IPv6 ranges that are never a public unicast destination:
+ * unique-local `fc00::/7`, link-local `fe80::/10`, deprecated site-local
+ * `fec0::/10`, multicast `ff00::/8`, and the local-use NAT64 prefix
+ * `64:ff9b:1::/48`, whose embedded address depends on local configuration.
+ */
+export declare function isNonPublicIpv6Range(groups: readonly number[]): boolean;
+//# sourceMappingURL=url.ipv6.d.ts.map

package/dist/url/url.ipv6.js

@@ -0,0 +1,88 @@
+/**
+ * @zudojs/security — IPv6 literal parsing and embedded-IPv4 extraction.
+ */
+import { isIPv6 } from "node:net";
+/**
+ * Expands an IPv6 address into its eight 16-bit groups.
+ *
+ * Accepts the compressed (`::`), dotted-tail (`::ffff:1.2.3.4`) and zoned
+ * (`fe80::1%eth0`) forms.
+ *
+ * @returns The groups, or `undefined` for a non-IPv6 input.
+ */
+export function expandIpv6(address) {
+    let text = address.toLowerCase();
+    const zone = text.indexOf("%");
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!isIPv6(text))
+        return undefined;
+    const lastColon = text.lastIndexOf(":");
+    const tail = text.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const o = tail.split(".").map(Number);
+        const hi = ((o[0] << 8) | o[1]).toString(16);
+        const lo = ((o[2] << 8) | o[3]).toString(16);
+        text = `${text.slice(0, lastColon + 1)}${hi}:${lo}`;
+    }
+    const [head = "", rest] = text.split("::");
+    const left = head === "" ? [] : head.split(":");
+    const right = rest === undefined || rest === "" ? [] : rest.split(":");
+    const fill = rest === undefined
+        ? []
+        : new Array(8 - left.length - right.length).fill("0");
+    return [...left, ...fill, ...right].map((group) => parseInt(group, 16));
+}
+function octetsOf(high, low) {
+    return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+/**
+ * The IPv4 address an IPv6 address stands for, when it is one of the
+ * embedding forms, so that it can be judged as that IPv4 address.
+ *
+ * - `::a.b.c.d` (IPv4-compatible, `::/96`, which also covers `::` and `::1`)
+ * - `::ffff:a.b.c.d` (IPv4-mapped, `::ffff:0:0/96`)
+ * - `::ffff:0:a.b.c.d` (IPv4-translated, `::ffff:0:0:0/96`)
+ * - `64:ff9b::a.b.c.d` (NAT64 well-known prefix, `64:ff9b::/96`)
+ * - `2002:aabb:ccdd::` (6to4, `2002::/16`)
+ *
+ * WHATWG URL parsing rewrites `[::127.0.0.1]` to `[::7f00:1]`, so matching
+ * on the dotted spelling (as the old regexes did) missed every one of these.
+ *
+ * @returns The four octets, or `undefined` when nothing is embedded.
+ */
+export function embeddedIpv4(groups) {
+    const [g0, g1, g2, g3, g4, g5, g6 = 0, g7 = 0] = groups;
+    const zeroTo = (end) => groups.slice(0, end).every((group) => group === 0);
+    if (zeroTo(6))
+        return octetsOf(g6, g7);
+    if (zeroTo(5) && g5 === 0xffff)
+        return octetsOf(g6, g7);
+    if (zeroTo(4) && g4 === 0xffff && g5 === 0)
+        return octetsOf(g6, g7);
+    if (g0 === 0x64 && g1 === 0xff9b && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
+        return octetsOf(g6, g7);
+    }
+    if (g0 === 0x2002)
+        return octetsOf(g1 ?? 0, g2 ?? 0);
+    return undefined;
+}
+/**
+ * True for IPv6 ranges that are never a public unicast destination:
+ * unique-local `fc00::/7`, link-local `fe80::/10`, deprecated site-local
+ * `fec0::/10`, multicast `ff00::/8`, and the local-use NAT64 prefix
+ * `64:ff9b:1::/48`, whose embedded address depends on local configuration.
+ */
+export function isNonPublicIpv6Range(groups) {
+    const g0 = groups[0] ?? 0;
+    if ((g0 & 0xfe00) === 0xfc00)
+        return true;
+    if ((g0 & 0xffc0) === 0xfe80)
+        return true;
+    if ((g0 & 0xffc0) === 0xfec0)
+        return true;
+    if ((g0 & 0xff00) === 0xff00)
+        return true;
+    return g0 === 0x64 && groups[1] === 0xff9b && groups[2] === 1;
+}
+//# sourceMappingURL=url.ipv6.js.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/security",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -20,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",