@zudojs/security 1.0.0 → 1.1.0

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.js

@@ -4,6 +4,7 @@
  * Sanitizes user input against common attack patterns.
  */
 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 +40,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.

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,63 @@
+/**
+ * @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;
+        const candidate = chain[Math.max(0, 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

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