@zudojs/security 1.0.1 → 1.2.0

package/dist/csrf/csrf.core.js

@@ -19,6 +19,7 @@
  * token minted for one user validates for every other user.
  */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { ConfigurationError } from "@zudojs/errors";
 /** Default token expiration (1 hour). */
 const DEFAULT_EXPIRATION = 3600;
 /** Default cookie name for CSRF token. */
@@ -37,14 +38,41 @@ const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
  * the only check, which accepted a one-character secret in silence.
  */
 export const MIN_CSRF_SECRET_LENGTH = 32;
+/**
+ * Rejects a `methods` list that cannot protect anything.
+ *
+ * `methods.some(…)` over an empty list is always `false`, and `verify()`
+ * answers `true` for a method that needs no protection — so `methods: []`
+ * turned CSRF off for every request without an error or a warning. A list
+ * built from configuration (`process.env.CSRF_METHODS?.split(",") ?? []`) is
+ * empty exactly when the configuration is missing. An empty list is a
+ * configuration error, not a blanket grant; omit `methods` for the defaults.
+ */
+function assertUsableMethods(methods) {
+    if (methods === undefined)
+        return;
+    if (!Array.isArray(methods)) {
+        throw new ConfigurationError("CSRF methods must be an array of HTTP method names, " +
+            "or omitted for the defaults (POST, PUT, PATCH, DELETE).");
+    }
+    if (methods.length === 0) {
+        throw new ConfigurationError("CSRF methods cannot be empty: an empty list protects no request at " +
+            "all. Omit `methods` for the defaults (POST, PUT, PATCH, DELETE).");
+    }
+    for (const method of methods) {
+        if (typeof method !== "string" || method.trim().length === 0) {
+            throw new ConfigurationError("CSRF methods must be non-empty HTTP method names.");
+        }
+    }
+}
 /** Rejects a secret too short to be worth signing with. */
 function assertUsableSecret(secret) {
-    if (secret.length === 0) {
-        throw new Error("CSRF secret cannot be empty: pass a random string of at least " +
+    if (typeof secret !== "string" || secret.length === 0) {
+        throw new ConfigurationError("CSRF secret cannot be empty: pass a random string of at least " +
             `${MIN_CSRF_SECRET_LENGTH} characters, e.g. randomBytes(32).toString("hex")`);
     }
     if (secret.length < MIN_CSRF_SECRET_LENGTH) {
-        throw new Error(`CSRF secret is too short: got ${secret.length} characters, expected at least ` +
+        throw new ConfigurationError(`CSRF secret is too short: got ${secret.length} characters, expected at least ` +
             `${MIN_CSRF_SECRET_LENGTH}. The signature is HMAC-SHA256, so a shorter ` +
             'secret adds no strength. Generate one with randomBytes(32).toString("hex").');
     }
@@ -101,10 +129,18 @@ export function generateCsrfToken(secret, options) {
  * @param options - Maximum lifetime and session binding, or a bare expiration
  *   in seconds for backwards compatibility.
  * @returns True if the token is valid, unexpired, and bound to this session.
+ * @throws {ConfigurationError} when the secret is empty or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH}, exactly as `generateCsrfToken` does.
  */
 export function validateCsrfToken(token, secret, options) {
+    // Same bar as `generateCsrfToken`: a verifier configured with
+    // `process.env.CSRF_SECRET ?? ""` otherwise accepted tokens anyone can sign
+    // with an empty HMAC key.
+    assertUsableSecret(secret);
     const opts = typeof options === "number" ? { expiration: options } : (options ?? {});
     const maxTtl = opts.expiration ?? DEFAULT_EXPIRATION;
+    if (typeof token !== "string")
+        return false;
     const parts = token.split(":");
     if (parts.length !== 3) {
         return false;
@@ -150,6 +186,7 @@ export function validateCsrfToken(token, secret, options) {
  * @returns True when the request carries a matching, valid token.
  */
 export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
+    assertUsableSecret(secret);
     if (!cookieToken || !requestToken) {
         return false;
     }
@@ -166,11 +203,16 @@ export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
  * @returns True if CSRF protection is required.
  */
 export function requiresCsrfProtection(method, config) {
+    assertUsableMethods(config?.methods);
     if (SAFE_METHODS.includes(method.toUpperCase())) {
         return false;
     }
+    // HTTP methods are case-sensitive on the wire but configured by hand;
+    // comparing a lower-case `methods: ["post"]` against the upper-cased
+    // request method used to protect nothing, silently.
+    const upper = method.toUpperCase();
     const methods = config?.methods ?? DEFAULT_METHODS;
-    return methods.includes(method.toUpperCase());
+    return methods.some((m) => String(m).toUpperCase() === upper);
 }
 /**
  * Extracts the CSRF token from request headers.
@@ -257,11 +299,13 @@ export function generateCsrfCookie(token, config) {
  *
  * @param config - Secret, lifetime, cookie/header names, protected methods.
  * @returns Protection bound to that configuration.
- * @throws {Error} when the secret is missing or shorter than
- *   {@link MIN_CSRF_SECRET_LENGTH}.
+ * @throws {ConfigurationError} when the secret is missing or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH}, or when `methods` is present but empty,
+ *   not an array, or contains a non-method entry.
  */
 export function createCsrfProtection(config) {
     assertUsableSecret(config.secret);
+    assertUsableMethods(config.methods);
     const expiration = config.expiration ?? DEFAULT_EXPIRATION;
     const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
     const headerName = config.headerName ?? DEFAULT_HEADER_NAME;

package/dist/headers/headers.core.js

@@ -4,6 +4,7 @@
  * Generates security-related HTTP response headers with secure defaults.
  */
 import { randomBytes } from "node:crypto";
+import { ConfigurationError } from "@zudojs/errors";
 /** Security header names. */
 export const SECURITY_HEADER_NAMES = {
     CONTENT_SECURITY_POLICY: "Content-Security-Policy",
@@ -58,7 +59,7 @@ export function generateSecurityHeaders(config) {
     if (config) {
         for (const [key, value] of Object.entries(config)) {
             if (typeof value === "string" && /[\r\n\x00]/.test(value)) {
-                throw new Error(`Security header "${key}" contains CRLF or null bytes (injection risk)`);
+                throw new ConfigurationError(`Security header "${key}" contains CRLF or null bytes (injection risk)`);
             }
         }
     }

package/dist/index.d.ts

@@ -31,17 +31,17 @@
 export type { HeaderSecurityConfig, HeaderValidationResult, BodyLimitConfig, BodyLimitPresets, UrlValidationConfig, UrlValidationResult, CookieSecurityConfig, ParsedCookie, CorsConfig, CsrfConfig, RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult, SecurityHeadersConfig, InputSanitizationConfig, } from "./types/security.type.js";
 export { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from "./types/security.type.js";
 export { validateHeaderName, validateHeaderValue, validateHeaders, sanitizeHeaderValue, isHopByHopHeader, } from "./header/index.js";
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url/index.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, expandIpv6, embeddedIpv4, isNonPublicIpv6Range, } from "./url/index.js";
 export type { RequestTargetConfig } from "./url/index.js";
 export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body/index.js";
-export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie/index.js";
+export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie/index.js";
 export type { CorsHeaders } from "./cors/index.js";
 export { isOriginAllowed, generatePreflightHeaders, generateSimpleHeaders, isMethodAllowed, getDisallowedHeaders, } from "./cors/index.js";
 export { cors } from "./cors/cors.namespace.js";
 export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf/index.js";
 export type { CsrfTokenOptions, CsrfCookieOptions, CsrfProtection, CsrfProtectionOptions, IssuedCsrfToken, CsrfVerifiableRequest, } from "./csrf/index.js";
-export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
-export type { RateLimiterOptions, ClientIpOptions } from "./rateLimit/index.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, createIpKeyGenerator, ipRateLimitKey, parseClientIp, DEFAULT_IPV6_PREFIX_LENGTH, } from "./rateLimit/index.js";
+export type { RateLimiterOptions, ClientIpOptions, IpKeyOptions, } from "./rateLimit/index.js";
 export { rateLimit } from "./rateLimit/rateLimit.namespace.js";
 export { SECURITY_HEADER_NAMES } from "./headers/index.js";
 export { generateSecurityHeaders, getMissingSecurityHeaders, generateCspNonce, validateCspDirective, } from "./headers/index.js";

package/dist/index.js

@@ -32,17 +32,17 @@ export { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from
 /* ─── Header Security ────────────────────────────────────────────────────── */
 export { validateHeaderName, validateHeaderValue, validateHeaders, sanitizeHeaderValue, isHopByHopHeader, } from "./header/index.js";
 /* ─── URL Validation ─────────────────────────────────────────────────────── */
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url/index.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, expandIpv6, embeddedIpv4, isNonPublicIpv6Range, } from "./url/index.js";
 /* ─── Body Validation ────────────────────────────────────────────────────── */
 export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body/index.js";
 /* ─── Cookie Security ────────────────────────────────────────────────────── */
-export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie/index.js";
+export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie/index.js";
 export { isOriginAllowed, generatePreflightHeaders, generateSimpleHeaders, isMethodAllowed, getDisallowedHeaders, } from "./cors/index.js";
 export { cors } from "./cors/cors.namespace.js";
 /* ─── CSRF ───────────────────────────────────────────────────────────────── */
 export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf/index.js";
 /* ─── Rate Limiting ──────────────────────────────────────────────────────── */
-export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, createIpKeyGenerator, ipRateLimitKey, parseClientIp, DEFAULT_IPV6_PREFIX_LENGTH, } from "./rateLimit/index.js";
 export { rateLimit } from "./rateLimit/rateLimit.namespace.js";
 /* ─── Security Headers ───────────────────────────────────────────────────── */
 export { SECURITY_HEADER_NAMES } from "./headers/index.js";

package/dist/input/input.core.d.ts

@@ -46,6 +46,8 @@ export declare function sanitizeString(input: string, config?: InputSanitization
  * @param obj - The object to sanitize.
  * @param config - Optional sanitization configuration.
  * @returns The sanitized object.
+ * @throws {ConfigurationError} when `config.maxDepth` is present but is not
+ *   an integer of 1 or more.
  */
 export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T, config?: InputSanitizationConfig): T;
 /**

package/dist/input/input.core.js

@@ -3,7 +3,9 @@
  *
  * Sanitizes user input against common attack patterns.
  */
+import { ConfigurationError } from "@zudojs/errors";
 import { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from "../types/security.type.js";
+import { containsObfuscatedScheme, decodeHtmlEntities } from "./input.decode.js";
 /**
  * Null byte and control character patterns.
  *
@@ -39,7 +41,15 @@ export function containsSqlInjection(input) {
  * @returns True if XSS patterns are detected.
  */
 export function containsXss(input) {
-    return XSS_PATTERNS.some((pattern) => pattern.test(input));
+    if (XSS_PATTERNS.some((pattern) => pattern.test(input)))
+        return true;
+    // Entity-encoded payloads (`javascript:`, `javascript:`,
+    // `java	script:`) are decoded by the browser but not by a regex.
+    const decoded = decodeHtmlEntities(input);
+    if (decoded !== input && XSS_PATTERNS.some((pattern) => pattern.test(decoded))) {
+        return true;
+    }
+    return containsObfuscatedScheme(decoded);
 }
 /**
  * Checks if a string contains prototype pollution keys.
@@ -155,11 +165,34 @@ function isPlainObject(value) {
  * @param obj - The object to sanitize.
  * @param config - Optional sanitization configuration.
  * @returns The sanitized object.
+ * @throws {ConfigurationError} when `config.maxDepth` is present but is not
+ *   an integer of 1 or more.
  */
 export function sanitizeObject(obj, config) {
     const maxDepth = config?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    assertUsableMaxDepth(config?.maxDepth);
     return sanitizeValue(obj, config, new WeakSet(), 0, maxDepth);
 }
+/**
+ * Rejects a `maxDepth` that cannot describe a depth the caller wants kept.
+ *
+ * The guard runs before the object is entered, so `maxDepth: 0` discarded the
+ * argument itself and returned `undefined` under a non-optional `T` — every
+ * field read off the result then threw at a call site TypeScript had told was
+ * safe. `Number(process.env.MAX_DEPTH)` with the variable unset is the same
+ * shape of mistake as the body limit's `NaN`.
+ *
+ * @throws {ConfigurationError} when `maxDepth` is present but is not an
+ *   integer of 1 or more.
+ */
+function assertUsableMaxDepth(maxDepth) {
+    if (maxDepth === undefined)
+        return;
+    if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+        throw new ConfigurationError("Input sanitization maxDepth must be an integer of 1 or more, got: " +
+            String(maxDepth));
+    }
+}
 /**
  * Validates that a string contains only safe characters.
  *

package/dist/input/input.decode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @zudojs/security — HTML entity decoding for the XSS heuristic.
+ *
+ * Browsers decode character references in attribute values before they
+ * interpret a URL, and they drop tabs and newlines inside a scheme. A regex
+ * run over the raw text therefore missed `javascript:`,
+ * `javascript:`, `javascript:` and `java	script:`.
+ */
+/**
+ * Decodes numeric (`j`, `j`, with or without the trailing `;`)
+ * and the relevant named character references, repeatedly, up to three
+ * rounds.
+ *
+ * @param input - Raw text.
+ * @returns The decoded text (unchanged when it holds no references).
+ */
+export declare function decodeHtmlEntities(input: string): string;
+/**
+ * True when a script-capable URL scheme appears once whitespace and control
+ * characters are removed, as a browser removes them when parsing a URL.
+ *
+ * @param decoded - Text that has already been entity-decoded.
+ */
+export declare function containsObfuscatedScheme(decoded: string): boolean;
+//# sourceMappingURL=input.decode.d.ts.map

package/dist/input/input.decode.js

@@ -0,0 +1,72 @@
+/**
+ * @zudojs/security — HTML entity decoding for the XSS heuristic.
+ *
+ * Browsers decode character references in attribute values before they
+ * interpret a URL, and they drop tabs and newlines inside a scheme. A regex
+ * run over the raw text therefore missed `javascript:`,
+ * `javascript:`, `javascript:` and `java	script:`.
+ */
+/** Named references that matter for smuggling a scheme or a tag. */
+const NAMED_ENTITIES = Object.freeze({
+    colon: ":",
+    tab: "\t",
+    newline: "\n",
+    lpar: "(",
+    rpar: ")",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    amp: "&",
+    sol: "/",
+    bsol: "\\",
+    period: ".",
+    equals: "=",
+    nbsp: " ",
+});
+/** Rounds of decoding, so `&amp;#106;` is unwrapped too. */
+const MAX_ROUNDS = 3;
+const ENTITY_PATTERN = /&(?:#(\d{1,8})|#[xX]([0-9a-fA-F]{1,6})|([a-zA-Z]{2,10}));?/g;
+function decodeOnce(input) {
+    return input.replace(ENTITY_PATTERN, (match, dec, hex, name) => {
+        const code = dec !== undefined
+            ? Number.parseInt(dec, 10)
+            : hex !== undefined
+                ? Number.parseInt(hex, 16)
+                : undefined;
+        if (code !== undefined) {
+            return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
+        }
+        const named = name === undefined ? undefined : NAMED_ENTITIES[name.toLowerCase()];
+        return named ?? match;
+    });
+}
+/**
+ * Decodes numeric (`&#106;`, `&#x6a;`, with or without the trailing `;`)
+ * and the relevant named character references, repeatedly, up to three
+ * rounds.
+ *
+ * @param input - Raw text.
+ * @returns The decoded text (unchanged when it holds no references).
+ */
+export function decodeHtmlEntities(input) {
+    let current = input;
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+        const next = decodeOnce(current);
+        if (next === current)
+            break;
+        current = next;
+    }
+    return current;
+}
+/**
+ * True when a script-capable URL scheme appears once whitespace and control
+ * characters are removed, as a browser removes them when parsing a URL.
+ *
+ * @param decoded - Text that has already been entity-decoded.
+ */
+export function containsObfuscatedScheme(decoded) {
+    const compact = decoded.replace(/[\u0000- \u007f- ]+/g, "");
+    return /(?:javascript|vbscript|livescript):|data:text\/html/i.test(compact);
+}
+//# sourceMappingURL=input.decode.js.map

package/dist/rateLimit/index.d.ts

@@ -1,6 +1,13 @@
 /**
  * @zudojs/security — Rate Limiting Barrel
+ *
+ * Sliding-window limiter, client address extraction, and IP-derived
+ * rate-limit keys (port-stripped, IPv6 bucketed by prefix).
  */
-export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
-export type { RateLimiterOptions, ClientIpOptions } from "./rateLimit.core.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, } from "./rateLimit.core.js";
+export type { RateLimiterOptions } from "./rateLimit.core.js";
+export { extractClientIp } from "./rateLimit.clientIp.js";
+export type { ClientIpOptions } from "./rateLimit.clientIp.js";
+export { createIpKeyGenerator, ipRateLimitKey, parseClientIp, DEFAULT_IPV6_PREFIX_LENGTH, } from "./rateLimit.clientKey.js";
+export type { IpKeyOptions } from "./rateLimit.clientKey.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rateLimit/index.js

@@ -1,5 +1,10 @@
 /**
  * @zudojs/security — Rate Limiting Barrel
+ *
+ * Sliding-window limiter, client address extraction, and IP-derived
+ * rate-limit keys (port-stripped, IPv6 bucketed by prefix).
  */
-export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, } from "./rateLimit.core.js";
+export { extractClientIp } from "./rateLimit.clientIp.js";
+export { createIpKeyGenerator, ipRateLimitKey, parseClientIp, DEFAULT_IPV6_PREFIX_LENGTH, } from "./rateLimit.clientKey.js";
 //# sourceMappingURL=index.js.map

package/dist/rateLimit/rateLimit.clientIp.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @zudojs/security — Client address extraction from forwarding headers.
+ */
+/** 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`.
+ *
+ * The returned address has any port and IPv6 brackets removed: some proxies
+ * append `client-ip:port`, and returning that verbatim gave every new TCP
+ * source port its own rate-limit bucket. Values that are not IP addresses
+ * are ignored.
+ *
+ * @param headers - Request headers.
+ * @param options - Proxy trust configuration.
+ * @returns The client IP address, or "unknown". Note that the default
+ *   rate-limit key generator refuses `"unknown"`; pass `remoteAddress`.
+ */
+export declare function extractClientIp(headers: Record<string, string | string[] | undefined>, options?: ClientIpOptions): string;
+//# sourceMappingURL=rateLimit.clientIp.d.ts.map

package/dist/rateLimit/rateLimit.clientIp.js

@@ -0,0 +1,71 @@
+/**
+ * @zudojs/security — Client address extraction from forwarding headers.
+ */
+import { parseClientIp } from "./rateLimit.clientKey.js";
+/**
+ * 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`.
+ *
+ * The returned address has any port and IPv6 brackets removed: some proxies
+ * append `client-ip:port`, and returning that verbatim gave every new TCP
+ * source port its own rate-limit bucket. Values that are not IP addresses
+ * are ignored.
+ *
+ * @param headers - Request headers.
+ * @param options - Proxy trust configuration.
+ * @returns The client IP address, or "unknown". Note that the default
+ *   rate-limit key generator refuses `"unknown"`; pass `remoteAddress`.
+ */
+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;
+        // A chain shorter than the configured hop count did not pass through all
+        // of the proxies whose entries make it trustworthy — a request entering
+        // at an inner hop, or one a client shortened on purpose. Clamping the
+        // index to 0 landed on the entry the client wrote, handing them their own
+        // rate-limit bucket; there is nothing trustworthy to read here, so the
+        // header is skipped entirely.
+        if (index >= 0) {
+            const candidate = chain[index];
+            const ip = candidate === undefined ? undefined : parseClientIp(candidate);
+            if (ip !== undefined)
+                return ip;
+        }
+    }
+    const realIp = lookupHeader(headers, "x-real-ip");
+    const ip = realIp === undefined ? undefined : parseClientIp(realIp);
+    if (ip !== undefined)
+        return ip;
+    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;
+}
+//# sourceMappingURL=rateLimit.clientIp.js.map

package/dist/rateLimit/rateLimit.clientKey.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @zudojs/security — Rate-limit keys derived from client addresses.
+ *
+ * An address is only a useful bucket if one client cannot cheaply become
+ * many. Two things made that cheap: a `host:port` string (some proxies
+ * append the client's source port to `X-Forwarded-For`), which gave every
+ * new TCP connection its own bucket, and full /128 IPv6 keys, which let any
+ * host rotate through the 2^64 addresses of its own /64.
+ */
+import type { RateLimitRequest } from "../types/security.type.js";
+/** Default IPv6 prefix a single client is bucketed by. */
+export declare const DEFAULT_IPV6_PREFIX_LENGTH = 64;
+/** Options for {@link createIpKeyGenerator} and {@link ipRateLimitKey}. */
+export interface IpKeyOptions {
+    /**
+     * IPv6 prefix length, in bits, that counts as one client (default: 64,
+     * the smallest allocation an end site normally receives). 128 keys every
+     * address separately.
+     */
+    readonly ipv6PrefixLength?: number;
+}
+/**
+ * Parses an address as it appears in a forwarding header or socket, with
+ * any port and IPv6 brackets or zone id removed.
+ *
+ * Accepts `1.2.3.4`, `1.2.3.4:5678`, `2001:db8::1`, `[2001:db8::1]` and
+ * `[2001:db8::1]:443`.
+ *
+ * @returns The bare address, or `undefined` if the value is not an IP.
+ */
+export declare function parseClientIp(value: string): string | undefined;
+/**
+ * The rate-limit key for a client address: IPv4 as-is (port stripped),
+ * IPv4-mapped IPv6 as its IPv4 address, and other IPv6 addresses truncated
+ * to their `ipv6PrefixLength` network, e.g. `2001:db8:0:1:0:0:0:0/64`.
+ *
+ * @returns The key, or `undefined` when `value` is not an IP address.
+ */
+export declare function ipRateLimitKey(value: string, options?: IpKeyOptions): string | undefined;
+/**
+ * Creates a key generator that buckets requests by `request.ip`.
+ *
+ * Throws a `ConfigurationError` when `request.ip` is missing or is not an IP
+ * address (including the `"unknown"` placeholder `extractClientIp` returns).
+ * Keying such requests under one shared `"unknown"` bucket let a single
+ * client starve every other client whose address was not available.
+ *
+ * @throws {RangeError} when `ipv6PrefixLength` is not an integer in 1–128.
+ */
+export declare function createIpKeyGenerator(options?: IpKeyOptions): (request: RateLimitRequest) => string;
+//# sourceMappingURL=rateLimit.clientKey.d.ts.map

package/dist/rateLimit/rateLimit.clientKey.js

@@ -0,0 +1,104 @@
+/**
+ * @zudojs/security — Rate-limit keys derived from client addresses.
+ *
+ * An address is only a useful bucket if one client cannot cheaply become
+ * many. Two things made that cheap: a `host:port` string (some proxies
+ * append the client's source port to `X-Forwarded-For`), which gave every
+ * new TCP connection its own bucket, and full /128 IPv6 keys, which let any
+ * host rotate through the 2^64 addresses of its own /64.
+ */
+import { isIPv4, isIPv6 } from "node:net";
+import { ConfigurationError } from "@zudojs/errors";
+import { expandIpv6 } from "../url/url.ipv6.js";
+/** Default IPv6 prefix a single client is bucketed by. */
+export const DEFAULT_IPV6_PREFIX_LENGTH = 64;
+/**
+ * Parses an address as it appears in a forwarding header or socket, with
+ * any port and IPv6 brackets or zone id removed.
+ *
+ * Accepts `1.2.3.4`, `1.2.3.4:5678`, `2001:db8::1`, `[2001:db8::1]` and
+ * `[2001:db8::1]:443`.
+ *
+ * @returns The bare address, or `undefined` if the value is not an IP.
+ */
+export function parseClientIp(value) {
+    const raw = value.trim();
+    let host = raw;
+    if (raw.startsWith("[")) {
+        const close = raw.indexOf("]");
+        if (close === -1)
+            return undefined;
+        const rest = raw.slice(close + 1);
+        if (rest !== "" && !/^:\d{1,5}$/.test(rest))
+            return undefined;
+        host = raw.slice(1, close);
+    }
+    else if (raw.split(":").length === 2) {
+        const [address, port] = raw.split(":");
+        if (!/^\d{1,5}$/.test(port ?? ""))
+            return undefined;
+        host = address ?? "";
+    }
+    const zone = host.indexOf("%");
+    if (zone !== -1)
+        host = host.slice(0, zone);
+    if (isIPv4(host))
+        return host;
+    if (isIPv6(host))
+        return host.toLowerCase();
+    return undefined;
+}
+/**
+ * The rate-limit key for a client address: IPv4 as-is (port stripped),
+ * IPv4-mapped IPv6 as its IPv4 address, and other IPv6 addresses truncated
+ * to their `ipv6PrefixLength` network, e.g. `2001:db8:0:1:0:0:0:0/64`.
+ *
+ * @returns The key, or `undefined` when `value` is not an IP address.
+ */
+export function ipRateLimitKey(value, options) {
+    const prefix = options?.ipv6PrefixLength ?? DEFAULT_IPV6_PREFIX_LENGTH;
+    const ip = parseClientIp(value);
+    if (ip === undefined)
+        return undefined;
+    if (isIPv4(ip))
+        return ip;
+    const groups = expandIpv6(ip);
+    if (!groups)
+        return undefined;
+    if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff) {
+        const [a = 0, b = 0] = groups.slice(6);
+        return `${a >> 8}.${a & 255}.${b >> 8}.${b & 255}`;
+    }
+    const masked = groups.map((group, index) => {
+        const bits = Math.min(16, Math.max(0, prefix - index * 16));
+        return bits === 0 ? 0 : group & ((0xffff << (16 - bits)) & 0xffff);
+    });
+    return `${masked.map((g) => g.toString(16)).join(":")}/${prefix}`;
+}
+/**
+ * Creates a key generator that buckets requests by `request.ip`.
+ *
+ * Throws a `ConfigurationError` when `request.ip` is missing or is not an IP
+ * address (including the `"unknown"` placeholder `extractClientIp` returns).
+ * Keying such requests under one shared `"unknown"` bucket let a single
+ * client starve every other client whose address was not available.
+ *
+ * @throws {RangeError} when `ipv6PrefixLength` is not an integer in 1–128.
+ */
+export function createIpKeyGenerator(options) {
+    const prefix = options?.ipv6PrefixLength ?? DEFAULT_IPV6_PREFIX_LENGTH;
+    if (!Number.isInteger(prefix) || prefix < 1 || prefix > 128) {
+        throw new RangeError(`ipv6PrefixLength must be an integer in 1-128, got: ${prefix}`);
+    }
+    return (request) => {
+        const key = typeof request.ip === "string"
+            ? ipRateLimitKey(request.ip, { ipv6PrefixLength: prefix })
+            : undefined;
+        if (key === undefined) {
+            throw new ConfigurationError("Rate limiting by IP needs RateLimitRequest.ip to be a client address; " +
+                "pass the socket's remoteAddress (or extractClientIp with it), or supply a keyGenerator.");
+        }
+        return key;
+    };
+}
+//# sourceMappingURL=rateLimit.clientKey.js.map