@zudojs/security 1.0.1 → 1.2.0

package/dist/rateLimit/rateLimit.core.d.ts

@@ -7,8 +7,13 @@ import type { RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitRes
 /**
  * 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 declare function defaultKeyGenerator(request: RateLimitRequest): string;
 /**
@@ -63,34 +68,4 @@ export declare function createRateLimiter(config: RateLimiterOptions): {
     /** Number of keys currently tracked. */
     readonly size: number;
 };
-/** Options controlling how far forwarding headers are trusted. */
-export interface ClientIpOptions {
-    /**
-     * Number of reverse proxies you operate in front of this service.
-     *
-     * `X-Forwarded-For` is appended to by every hop, so the entries closest to
-     * the right are the ones your own infrastructure added. With `trustProxy: 1`
-     * the last entry is used, with `2` the second-to-last, and so on. Entries to
-     * the left of your proxies were supplied by the client and are ignored.
-     *
-     * Defaults to `0`: no forwarding header is trusted at all.
-     */
-    readonly trustProxy?: number;
-    /** The connection's remote address, used when no header is trusted. */
-    readonly remoteAddress?: string;
-}
-/**
- * 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 declare function extractClientIp(headers: Record<string, string | string[] | undefined>, options?: ClientIpOptions): string;
 //# sourceMappingURL=rateLimit.core.d.ts.map

package/dist/rateLimit/rateLimit.core.js

@@ -3,6 +3,7 @@
  *
  * 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. */
@@ -14,12 +15,18 @@ 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.
  *
@@ -81,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;
@@ -191,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.
@@ -203,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;
@@ -229,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.d.ts

@@ -27,6 +27,12 @@ export declare function fullyDecodeUri(value: string): {
  * Operates on the fully decoded form, and treats a backslash as a separator
  * because Windows and some proxies do.
  *
+ * RFC 3986 lets a path segment carry parameters after a `;`, and Tomcat,
+ * Jetty and several reverse-proxy pairings strip them before resolving the
+ * path — so `/a/..;/b` names the same resource as `/a/../b`. Each segment is
+ * therefore also tested with its parameters removed. The raw segment is still
+ * tested first, so nothing that was a traversal stops being one.
+ *
  * @param path - The path to inspect.
  * @returns True when a `..` segment is present.
  */

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. */
@@ -96,6 +97,12 @@ function decodeOnce(value) {
  * Operates on the fully decoded form, and treats a backslash as a separator
  * because Windows and some proxies do.
  *
+ * RFC 3986 lets a path segment carry parameters after a `;`, and Tomcat,
+ * Jetty and several reverse-proxy pairings strip them before resolving the
+ * path — so `/a/..;/b` names the same resource as `/a/../b`. Each segment is
+ * therefore also tested with its parameters removed. The raw segment is still
+ * tested first, so nothing that was a traversal stops being one.
+ *
  * @param path - The path to inspect.
  * @returns True when a `..` segment is present.
  */
@@ -103,9 +110,17 @@ export function containsTraversal(path) {
     const { decoded, truncated } = fullyDecodeUri(path);
     if (truncated)
         return true;
-    return decoded
-        .split(/[/\\]/)
-        .some((segment) => segment === ".." || segment === "...");
+    return decoded.split(/[/\\]/).some((segment) => {
+        if (isTraversalSegment(segment))
+            return true;
+        const parameterStart = segment.indexOf(";");
+        return (parameterStart !== -1 &&
+            isTraversalSegment(segment.slice(0, parameterStart)));
+    });
+}
+/** True for the segments a path resolver walks upward on. */
+function isTraversalSegment(segment) {
+    return segment === ".." || segment === "...";
 }
 /**
  * Validates a URL against security configuration.
@@ -301,36 +316,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,6 +1,6 @@
 {
   "name": "@zudojs/security",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
   "author": {
@@ -24,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/constants": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",