@zudojs/security 0.0.1 → 1.0.0

package/dist/input/input.core.js

@@ -4,13 +4,28 @@
  * Sanitizes user input against common attack patterns.
  */
 import { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from "../types/security.type.js";
-/** Null byte pattern. */
-const NULL_BYTE_PATTERN = /\x00/g;
-/** Control character pattern (except tab, newline, carriage return). */
-const CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/**
+ * Null byte and control character patterns.
+ *
+ * Two variants of each: the plain form is used with {@link RegExp.test}, the
+ * `g` form only with {@link String.replace}. A global regex keeps `lastIndex`
+ * between `test` calls and resumes from there on the next one, so sharing a
+ * single `/g` pattern across both uses makes the test report `false` for input
+ * it matched moments earlier.
+ */
+const NULL_BYTE_PATTERN = /\x00/;
+const NULL_BYTE_PATTERN_GLOBAL = /\x00/g;
+/** Control characters, excluding tab, newline, and carriage return. */
+const CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+const CONTROL_CHAR_PATTERN_GLOBAL = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/** Default maximum recursion depth for {@link sanitizeObject}. */
+const DEFAULT_MAX_DEPTH = 32;
 /**
  * Checks if a string contains SQL injection patterns.
  *
+ * A heuristic with a high false-positive rate on ordinary prose — never the
+ * only defence against injection. Parameterise your queries.
+ *
  * @param input - The string to check.
  * @returns True if SQL injection patterns are detected.
  */
@@ -46,10 +61,15 @@ export function sanitizeString(input, config) {
     let sanitized = input;
     // Strip null bytes
     if (config?.stripNullBytes !== false) {
-        sanitized = sanitized.replace(NULL_BYTE_PATTERN, "");
+        sanitized = sanitized.replace(NULL_BYTE_PATTERN_GLOBAL, "");
     }
     // Strip control characters
-    sanitized = sanitized.replace(CONTROL_CHAR_PATTERN, "");
+    sanitized = sanitized.replace(CONTROL_CHAR_PATTERN_GLOBAL, "");
+    // Normalize Unicode — collapses visually identical sequences so that
+    // downstream comparisons and length checks see one canonical form.
+    if (config?.normalizeUnicode) {
+        sanitized = sanitized.normalize("NFC");
+    }
     // Truncate if max length configured
     if (config?.maxStringLength && sanitized.length > config.maxStringLength) {
         sanitized = sanitized.slice(0, config.maxStringLength);
@@ -61,41 +81,84 @@ export function sanitizeString(input, config) {
     return sanitized;
 }
 /**
- * Sanitizes an object by recursively cleaning its values.
+ * Sanitizes a value of any shape, recursing into arrays and plain objects.
  *
- * @param obj - The object to sanitize.
- * @param config - Optional sanitization configuration.
- * @returns The sanitized object.
+ * Arrays stay arrays at every level, cycles are detected and replaced with
+ * `undefined` rather than overflowing the stack, and recursion stops at
+ * `config.maxDepth`.
  */
-export function sanitizeObject(obj, config) {
-    const sanitized = { ...obj };
-    for (const [key, value] of Object.entries(sanitized)) {
-        // Check for prototype pollution keys
-        if (config?.preventPrototypePollution !== false) {
-            if (containsPrototypePollution(key)) {
-                delete sanitized[key];
-                continue;
-            }
+function sanitizeValue(value, config, seen, depth, maxDepth) {
+    if (typeof value === "string") {
+        return sanitizeString(value, config);
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    if (depth >= maxDepth) {
+        return undefined;
+    }
+    // A repeat visit means a cycle: recursing would never terminate.
+    if (seen.has(value)) {
+        return undefined;
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => sanitizeValue(item, config, seen, depth + 1, maxDepth));
         }
-        // Sanitize string values
-        if (typeof value === "string") {
-            sanitized[key] = sanitizeString(value, config);
+        // Anything with its own semantics (Date, Map, RegExp, class instances) is
+        // passed through untouched — spreading it would silently turn it into a
+        // plain object and lose that behaviour.
+        if (!isPlainObject(value)) {
+            return value;
         }
-        else if (typeof value === "object" && value !== null) {
-            // Recursively sanitize nested objects
-            if (Array.isArray(value)) {
-                sanitized[key] = value.map((item) => typeof item === "object" && item !== null
-                    ? sanitizeObject(item, config)
-                    : typeof item === "string"
-                        ? sanitizeString(item, config)
-                        : item);
-            }
-            else {
-                sanitized[key] = sanitizeObject(value, config);
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (config?.preventPrototypePollution !== false &&
+                containsPrototypePollution(key)) {
+                continue;
             }
+            // `result[key] = …` does not create an own property for `__proto__`:
+            // it calls the inherited setter and replaces the result's prototype, so
+            // the attacker's fields resolve on the returned object while
+            // `Object.keys` shows nothing. That is exactly what happened whenever a
+            // caller set `preventPrototypePollution: false`, which is documented as
+            // "keep these keys as data", not "let them reassign a prototype".
+            // `defineProperty` always creates a real own property.
+            Object.defineProperty(result, key, {
+                value: sanitizeValue(child, config, seen, depth + 1, maxDepth),
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
         }
+        return result;
     }
-    return sanitized;
+    finally {
+        // Leaving this branch: a sibling may legitimately reference the same
+        // object without that being a cycle.
+        seen.delete(value);
+    }
+}
+/** True when the value is a plain object (`{}` or `Object.create(null)`). */
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+/**
+ * Sanitizes an object by recursively cleaning its values.
+ *
+ * Cycles and over-deep structures are handled: a repeated reference or a
+ * branch past `config.maxDepth` (default 32) becomes `undefined` instead of
+ * exhausting the stack.
+ *
+ * @param obj - The object to sanitize.
+ * @param config - Optional sanitization configuration.
+ * @returns The sanitized object.
+ */
+export function sanitizeObject(obj, config) {
+    const maxDepth = config?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    return sanitizeValue(obj, config, new WeakSet(), 0, maxDepth);
 }
 /**
  * Validates that a string contains only safe characters.
@@ -113,12 +176,23 @@ export function isSafeString(input, allowedPattern) {
     if (CONTROL_CHAR_PATTERN.test(input)) {
         return false;
     }
-    // Check custom pattern
-    if (allowedPattern && !allowedPattern.test(input)) {
+    // Check custom pattern. A caller-supplied `g`/`y` regex carries `lastIndex`
+    // between calls, so it is normalised before use.
+    if (allowedPattern && !withoutStickyFlags(allowedPattern).test(input)) {
         return false;
     }
     return true;
 }
+/**
+ * Returns an equivalent regex with the `g` and `y` flags removed.
+ *
+ * Both flags make `test` stateful via `lastIndex`; for a one-shot boolean
+ * check they only introduce order-dependent results.
+ */
+export function withoutStickyFlags(pattern) {
+    const flags = pattern.flags.replace(/[gy]/g, "");
+    return flags === pattern.flags ? pattern : new RegExp(pattern.source, flags);
+}
 /**
  * Checks for common attack patterns in a string.
  *
@@ -144,6 +218,11 @@ export function detectThreats(input) {
 /**
  * HTML-escapes a string to prevent XSS.
  *
+ * Escapes the five characters that matter in element text and quoted attribute
+ * values. It does not make a string safe for an unquoted attribute, inside a
+ * `<script>` or `<style>` block, or in a URL position — those contexts need
+ * their own encoding.
+ *
  * @param input - The string to escape.
  * @returns The escaped string.
  */
@@ -154,12 +233,21 @@ export function escapeHtml(input) {
         ">": "&gt;",
         '"': "&quot;",
         "'": "&#39;",
+        "`": "&#96;",
     };
-    return input.replace(/[&<>"']/g, (char) => map[char] ?? char);
+    return input.replace(/[&<>"'`]/g, (char) => map[char] ?? char);
 }
 /**
  * Strips HTML tags from a string.
  *
+ * This removes tag syntax; it is **not** an HTML sanitizer. The result is safe
+ * to treat as plain text, but must still be escaped with {@link escapeHtml}
+ * before being inserted back into a document — use a dedicated sanitizer if
+ * you need to keep markup.
+ *
+ * An unterminated `<` consumes the remainder of the input, which is the safe
+ * direction: a truncated tag never survives into the output.
+ *
  * @param input - The string to strip.
  * @returns The string with HTML tags removed.
  */

package/dist/rateLimit/index.d.ts

@@ -1,5 +1,6 @@
 /**
  * @zudojs/security — Rate Limiting Barrel
  */
-export { defaultKeyGenerator, defaultHandler, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
+export type { RateLimiterOptions, ClientIpOptions } from "./rateLimit.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rateLimit/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — Rate Limiting Barrel
  */
-export { defaultKeyGenerator, defaultHandler, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -3,7 +3,7 @@
  *
  * Implements sliding window rate limiting to prevent abuse.
  */
-import type { RateLimitConfig, RateLimitRequest, RateLimitResult } from "../types/security.type.js";
+import type { RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult } from "../types/security.type.js";
 /**
  * Default key generator using IP address.
  *
@@ -14,38 +14,83 @@ export declare function defaultKeyGenerator(request: RateLimitRequest): string;
 /**
  * Default handler when rate limit is exceeded.
  *
+ * `Retry-After` is derived from the decision that caused the rejection. It used
+ * to be the string `"60"` regardless of configuration, so a limiter with an
+ * hour-long window told every client to come back in a minute — and they did,
+ * to another rejection.
+ *
  * @param _request - The rate limit request.
  * @param response - The rate limit response to modify.
+ * @param result - The decision being rejected, used for `Retry-After`.
+ * @param message - The message to return, from `RateLimitConfig.message`.
  */
 export declare function defaultHandler(_request: RateLimitRequest, response: {
     statusCode: number;
     headers: Record<string, string>;
     body?: string;
-}): void;
+}, result?: RateLimitResult, message?: string): void;
+/**
+ * Whole seconds until the window frees up, as `Retry-After` requires.
+ *
+ * `RateLimitResult.resetAt` is a `Date`; putting it into a header or a JSON
+ * body directly yields an ISO string or an object where an integer count of
+ * seconds is expected. At least 1, never fractional, so a client never reads
+ * `Retry-After: 0` and retries instantly.
+ */
+export declare function retryAfterSeconds(result?: Pick<RateLimitResult, "resetAt">, now?: number): number;
+/** Extra options accepted by {@link createRateLimiter}. */
+export interface RateLimiterOptions extends RateLimitConfig {
+    /** Maximum number of distinct keys to track (default: 100,000). */
+    readonly maxKeys?: number;
+}
 /**
  * Creates an in-memory rate limiter.
  *
+ * The window genuinely slides: each check prunes timestamps older than
+ * `windowMs` and decides against what remains, so a client cannot spend a full
+ * allowance either side of a fixed boundary and get `2 × max` back to back.
+ *
  * @param config - Rate limit configuration.
  * @returns A function that checks rate limits.
  */
-export declare function createRateLimiter(config: RateLimitConfig): {
+export declare function createRateLimiter(config: RateLimiterOptions): {
     check: (request: RateLimitRequest) => RateLimitResult;
-    middleware: (request: RateLimitRequest, response?: {
-        statusCode: number;
-        headers: Record<string, string>;
-        body?: string;
-    }) => RateLimitResult;
+    middleware: (request: RateLimitRequest, response?: RateLimitResponse) => RateLimitResult;
     reset: (key: string) => void;
     clear: () => void;
     getCount: (key: string) => number;
     destroy: () => void;
+    /** 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.
- * Used as a default key generator.
+ *
+ * **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.
- * @returns The client IP address.
+ * @param options - Proxy trust configuration.
+ * @returns The client IP address, or "unknown".
  */
-export declare function extractClientIp(headers: Record<string, string | string[] | undefined>): string;
+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,12 +3,12 @@
  *
  * Implements sliding window rate limiting to prevent abuse.
  */
-/** Default rate limit: 100 requests per minute. */
-const DEFAULT_MAX = 100;
 /** 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;
 /**
  * Default key generator using IP address.
  *
@@ -21,44 +21,104 @@ export function defaultKeyGenerator(request) {
 /**
  * Default handler when rate limit is exceeded.
  *
+ * `Retry-After` is derived from the decision that caused the rejection. It used
+ * to be the string `"60"` regardless of configuration, so a limiter with an
+ * hour-long window told every client to come back in a minute — and they did,
+ * to another rejection.
+ *
  * @param _request - The rate limit request.
  * @param response - The rate limit response to modify.
+ * @param result - The decision being rejected, used for `Retry-After`.
+ * @param message - The message to return, from `RateLimitConfig.message`.
  */
-export function defaultHandler(_request, response) {
+export function defaultHandler(_request, response, result, message = DEFAULT_MESSAGE) {
     response.statusCode = 429;
-    response.headers["Retry-After"] = "60";
-    response.headers["X-RateLimit-Remaining"] = "0";
+    response.headers["Retry-After"] = String(retryAfterSeconds(result));
+    response.headers["X-RateLimit-Remaining"] = String(result?.remaining ?? 0);
+    if (result) {
+        response.headers["X-RateLimit-Limit"] = String(result.total);
+        response.headers["X-RateLimit-Reset"] = String(Math.ceil(result.resetAt.getTime() / 1000));
+    }
     response.body = JSON.stringify({
         error: {
             code: "RATE_LIMIT_EXCEEDED",
-            message: DEFAULT_MESSAGE,
+            message,
         },
     });
 }
+/**
+ * Whole seconds until the window frees up, as `Retry-After` requires.
+ *
+ * `RateLimitResult.resetAt` is a `Date`; putting it into a header or a JSON
+ * body directly yields an ISO string or an object where an integer count of
+ * seconds is expected. At least 1, never fractional, so a client never reads
+ * `Retry-After: 0` and retries instantly.
+ */
+export function retryAfterSeconds(result, now = Date.now()) {
+    if (!result)
+        return Math.ceil(DEFAULT_WINDOW_MS / 1000);
+    const deltaMs = result.resetAt.getTime() - now;
+    return Math.max(1, Math.ceil(deltaMs / 1000));
+}
 /**
  * Creates an in-memory rate limiter.
  *
+ * The window genuinely slides: each check prunes timestamps older than
+ * `windowMs` and decides against what remains, so a client cannot spend a full
+ * allowance either side of a fixed boundary and get `2 × max` back to back.
+ *
  * @param config - Rate limit configuration.
  * @returns A function that checks rate limits.
  */
 export function createRateLimiter(config) {
+    if (!Number.isFinite(config.max) || config.max < 1) {
+        throw new RangeError(`Rate limit max must be a positive number, got: ${config.max}`);
+    }
+    if (!Number.isFinite(config.windowMs) || config.windowMs < 1) {
+        throw new RangeError(`Rate limit windowMs must be a positive number, got: ${config.windowMs}`);
+    }
     const store = new Map();
     const keyGenerator = config.keyGenerator ?? defaultKeyGenerator;
-    const handler = config.handler;
+    // `config.message` was declared and documented but never read: the default
+    // handler always emitted the built-in string.
+    const message = config.message ?? DEFAULT_MESSAGE;
+    const handler = config.handler ??
+        ((request, response, result) => {
+            defaultHandler(request, response, result, message);
+        });
     const skip = config.skip;
-    // Cleanup old entries periodically
+    const maxKeys = config.maxKeys ?? DEFAULT_MAX_KEYS;
+    // Cleanup old entries periodically. Bounded so a very short window does not
+    // schedule a near-continuous timer.
     const cleanupInterval = setInterval(() => {
-        const now = Date.now();
+        const cutoff = Date.now() - config.windowMs;
         for (const [key, entry] of store) {
-            if (now - entry.windowStart > config.windowMs * 2) {
+            if (entry.lastSeen <= cutoff) {
                 store.delete(key);
             }
         }
-    }, config.windowMs);
+    }, Math.max(config.windowMs, 1_000));
     // Allow cleanup to not keep process alive
     if (cleanupInterval.unref) {
         cleanupInterval.unref();
     }
+    /**
+     * Evicts the least-recently-seen keys once the store exceeds its cap.
+     *
+     * Without this, a caller rotating the key (a spoofed forwarding header, a
+     * per-request identifier) grows the map without limit between sweeps.
+     */
+    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]);
+        }
+    }
     /**
      * Checks if a request is allowed and updates the counter.
      */
@@ -76,24 +136,30 @@ export function createRateLimiter(config) {
         const now = Date.now();
         const windowStart = now - config.windowMs;
         let entry = store.get(key);
-        if (!entry || now - entry.windowStart >= config.windowMs) {
-            // New window
-            entry = { timestamps: [now], windowStart: now };
+        if (!entry) {
+            entry = { timestamps: [], lastSeen: now };
             store.set(key, entry);
+            evictIfNeeded();
         }
-        else {
-            // Existing window — remove expired timestamps
-            const validTimestamps = entry.timestamps.filter((t) => t > windowStart);
-            validTimestamps.push(now);
-            entry = { timestamps: validTimestamps, windowStart: entry.windowStart };
-            store.set(key, entry);
+        // Prune everything that has slid out of the window.
+        const timestamps = entry.timestamps.filter((t) => t > windowStart);
+        entry.lastSeen = now;
+        const allowed = timestamps.length < config.max;
+        // Only an allowed request consumes an allowance slot. Recording denied
+        // requests too would let a client already over the limit keep growing its
+        // own bucket, so the cost of an attack would scale with the attack.
+        if (allowed) {
+            timestamps.push(now);
         }
-        const remaining = Math.max(0, config.max - entry.timestamps.length);
-        const allowed = entry.timestamps.length <= config.max;
+        entry.timestamps = timestamps;
+        const remaining = Math.max(0, config.max - timestamps.length);
+        // The window frees up when its oldest surviving request ages out.
+        const oldest = timestamps[0];
+        const resetAt = new Date((oldest ?? now) + config.windowMs);
         return {
             allowed,
             remaining,
-            resetAt: new Date(entry.windowStart + config.windowMs),
+            resetAt,
             total: config.max,
         };
     }
@@ -102,8 +168,8 @@ export function createRateLimiter(config) {
      */
     function middleware(request, response) {
         const result = check(request);
-        if (!result.allowed && response && handler) {
-            handler(request, response);
+        if (!result.allowed && response) {
+            handler(request, response, result);
         }
         return result;
     }
@@ -126,8 +192,7 @@ export function createRateLimiter(config) {
         const entry = store.get(key);
         if (!entry)
             return 0;
-        const now = Date.now();
-        const windowStart = now - config.windowMs;
+        const windowStart = Date.now() - config.windowMs;
         return entry.timestamps.filter((t) => t > windowStart).length;
     }
     /**
@@ -144,32 +209,80 @@ export function createRateLimiter(config) {
         clear,
         getCount,
         destroy,
+        /** Number of keys currently tracked. */
+        get size() {
+            return store.size;
+        },
     };
 }
 /**
  * Extracts the client IP from request headers.
- * Used as a default key generator.
+ *
+ * **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.
- * @returns The client IP address.
+ * @param options - Proxy trust configuration.
+ * @returns The client IP address, or "unknown".
  */
-export function extractClientIp(headers) {
-    // X-Forwarded-For (first entry)
-    const forwarded = headers["x-forwarded-for"];
-    if (typeof forwarded === "string") {
-        const first = forwarded.split(",")[0]?.trim();
-        if (first)
-            return first;
-    }
-    if (Array.isArray(forwarded) && forwarded.length > 0) {
-        const first = forwarded[0]?.split(",")[0]?.trim();
-        if (first)
-            return first;
-    }
-    // X-Real-IP
-    const realIp = headers["x-real-ip"];
-    if (typeof realIp === "string")
-        return realIp;
-    return "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,10 +3,11 @@
  *
  * Convenience namespace for rate limiting utilities.
  */
-import { defaultKeyGenerator, defaultHandler, createRateLimiter, extractClientIp } from "./rateLimit.core.js";
+import { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp } from "./rateLimit.core.js";
 export declare const rateLimit: {
     defaultKeyGenerator: typeof defaultKeyGenerator;
     defaultHandler: typeof defaultHandler;
+    retryAfterSeconds: typeof retryAfterSeconds;
     createRateLimiter: typeof createRateLimiter;
     extractClientIp: typeof extractClientIp;
 };

package/dist/rateLimit/rateLimit.namespace.js

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