@zudojs/security 1.1.0 → 1.3.0

package/README.md

@@ -155,14 +155,23 @@ Two patterns, both on the same HMAC-SHA256 token. Bind the token to a session
 wherever you have one — an unbound token is valid for every user.
 
 The shortest correct version binds your configuration once. `secret` must be at
-least 32 characters — the signature is HMAC-SHA256, so a shorter one adds no
-strength:
+least 32 characters (`MIN_CSRF_SECRET_LENGTH`) — the signature is HMAC-SHA256,
+so a shorter one adds no strength. Read it from the environment and refuse to
+start without it. Never write `process.env.CSRF_SECRET ?? "some-string"`: a
+hard-coded fallback is a secret anyone can read in your source, and a short
+one throws at the first call. Generate one with
+`node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))'`.
 
 ```typescript
-import { createCsrfProtection } from "@zudojs/security";
+import { createCsrfProtection, MIN_CSRF_SECRET_LENGTH } from "@zudojs/security";
+
+const secret = process.env.CSRF_SECRET;
+if (!secret || secret.length < MIN_CSRF_SECRET_LENGTH) {
+  throw new Error(`CSRF_SECRET must be set to at least ${MIN_CSRF_SECRET_LENGTH} characters`);
+}
 
 const csrf = createCsrfProtection({
-  secret: process.env.CSRF_SECRET, // >= 32 chars
+  secret,
   cookieName: "app_csrf",
   headerName: "x-app-csrf",
   expiration: 3600,
@@ -210,10 +219,16 @@ if (requiresCsrfProtection(request.method)) {
 }
 ```
 
-`validateCsrfToken` and `verifyDoubleSubmit` hold the secret to the same
-32-character minimum as `generateCsrfToken`, and throw `ConfigurationError`
-otherwise — a verifier given `process.env.CSRF_SECRET ?? ""` used to accept
-tokens signed with an empty key.
+**What returns `false` and what throws.** `csrf.verify`, `verifyDoubleSubmit`
+and `validateCsrfToken` return `false` for anything wrong with the request: a
+missing, malformed, non-string, forged, expired or mismatched token, a token
+bound to another session, or a request with no method (treated as needing
+protection). They throw `ConfigurationError` only for a configuration mistake:
+a secret shorter than 32 characters — the same minimum `generateCsrfToken`
+enforces, so a verifier given `process.env.CSRF_SECRET ?? ""` cannot accept
+tokens signed with an empty key — or an empty or invalid `methods` list. A
+throw from a CSRF check therefore means "fix your configuration", never "this
+request is bad".
 
 The cookie is `Secure` and `HttpOnly` by default, which suits the synchroniser
 token pattern where the server renders the token into the page. For the
@@ -269,6 +284,13 @@ could never apply to it.
 an unsafe name, attribute, `Max-Age` or `Expires` throws. `SameSite=None` and
 `Partitioned` require `Secure`.
 
+`Domain` must be a hostname — labels of letters, digits and hyphens separated
+by dots, with an optional leading dot (`example.com`, `.example.com`) — and
+anything else (spaces, colons, backslashes, empty labels) throws
+`ValidationError`. `Path` may not contain a control character, `;` or `,`.
+Previously only a real CR, LF, NUL, `;` or `,` was refused, so the literal text
+`a\r\nX-Evil: 1` was written into `Domain=` unchanged.
+
 `parseCookieHeader` validates on the way in too. A name that is not an RFC 6265
 token, or a value carrying a control character, is reported in `errors` and
 kept out of `cookies` — it used to check only length, so a malformed cookie

package/dist/cookie/cookie.attribute.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/security — Cookie attribute validation
+ *
+ * `Domain` and `Path` end up verbatim inside a `Set-Cookie` header, so each is
+ * held to a grammar rather than to a deny-list of a few characters. A
+ * deny-list of real CR/LF let through the literal text `a\r\nX-Evil: 1`
+ * (backslashes, spaces and a colon), which reaches any code that later
+ * unescapes or re-emits the header.
+ */
+/**
+ * Validates a cookie `Domain` attribute as a hostname: labels of
+ * `[A-Za-z0-9-]` separated by dots, with an optional leading dot.
+ *
+ * @param domain - The Domain value.
+ * @throws {ValidationError} for anything else — spaces, colons, backslashes,
+ *   control characters, empty labels, or an over-long name.
+ */
+export declare function assertCookieDomain(domain: string): void;
+/**
+ * Validates a cookie `Path` attribute.
+ *
+ * @param path - The Path value.
+ * @throws {ValidationError} when it contains a control character, DEL, `;`
+ *   or `,`.
+ */
+export declare function assertCookiePath(path: string): void;
+//# sourceMappingURL=cookie.attribute.d.ts.map

package/dist/cookie/cookie.attribute.js

@@ -0,0 +1,56 @@
+/**
+ * @zudojs/security — Cookie attribute validation
+ *
+ * `Domain` and `Path` end up verbatim inside a `Set-Cookie` header, so each is
+ * held to a grammar rather than to a deny-list of a few characters. A
+ * deny-list of real CR/LF let through the literal text `a\r\nX-Evil: 1`
+ * (backslashes, spaces and a colon), which reaches any code that later
+ * unescapes or re-emits the header.
+ */
+import { ValidationError } from "@zudojs/errors";
+/** One hostname label: 1–63 letters, digits or hyphens. */
+const LABEL = "[A-Za-z0-9-]{1,63}";
+/** A hostname with an optional leading dot: `example.com`, `.example.com`. */
+const DOMAIN_PATTERN = new RegExp(`^\\.?${LABEL}(?:\\.${LABEL})*$`);
+/** Longest hostname DNS allows, excluding the optional leading dot. */
+const MAX_DOMAIN_LENGTH = 253;
+/**
+ * Characters never allowed in `Path`: controls (CR and LF included), DEL,
+ * `;` which would end the attribute, and `,` which some parsers split
+ * `Set-Cookie` on.
+ */
+const PATH_UNSAFE = /[\x00-\x1F\x7F;,]/;
+/**
+ * Validates a cookie `Domain` attribute as a hostname: labels of
+ * `[A-Za-z0-9-]` separated by dots, with an optional leading dot.
+ *
+ * @param domain - The Domain value.
+ * @throws {ValidationError} for anything else — spaces, colons, backslashes,
+ *   control characters, empty labels, or an over-long name.
+ */
+export function assertCookieDomain(domain) {
+    const bare = typeof domain === "string" && domain.startsWith(".")
+        ? domain.slice(1)
+        : domain;
+    if (typeof domain !== "string" ||
+        !DOMAIN_PATTERN.test(domain) ||
+        bare.length > MAX_DOMAIN_LENGTH) {
+        throw new ValidationError(`Cookie Domain contains invalid characters (injection risk): it must be ` +
+            `a hostname (letters, digits, hyphens and dots, optionally with a ` +
+            `leading dot), got ${JSON.stringify(domain)}`);
+    }
+}
+/**
+ * Validates a cookie `Path` attribute.
+ *
+ * @param path - The Path value.
+ * @throws {ValidationError} when it contains a control character, DEL, `;`
+ *   or `,`.
+ */
+export function assertCookiePath(path) {
+    if (typeof path !== "string" || PATH_UNSAFE.test(path)) {
+        throw new ValidationError(`Cookie Path contains invalid characters (injection risk): control ` +
+            `characters, ";" and "," are not allowed, got ${JSON.stringify(path)}`);
+    }
+}
+//# sourceMappingURL=cookie.attribute.js.map

package/dist/cookie/cookie.core.js

@@ -5,6 +5,7 @@
  */
 import { ValidationError } from "@zudojs/errors";
 import { DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie.sensitive.js";
+import { assertCookieDomain, assertCookiePath } from "./cookie.attribute.js";
 /** Maximum cookie header size (4KB). */
 const MAX_COOKIE_HEADER_SIZE = 4096;
 /** Maximum number of cookies. */
@@ -24,8 +25,6 @@ const COOKIE_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
  * quote, comma, semicolon, and backslash.
  */
 const COOKIE_VALUE_PATTERN = /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*$/;
-/** Characters that must never reach an attribute value. */
-const ATTRIBUTE_UNSAFE = /[;,\r\n\x00]/;
 /**
  * Control characters that are never acceptable inside a parsed cookie value,
  * however lenient the rest of the read path is.
@@ -121,11 +120,11 @@ export function serializeCookie(cookie, config) {
     }
     const parts = [`${cookie.name}=${encodedValue}`];
     if (cookie.path) {
-        assertSafeAttribute("Path", cookie.path);
+        assertCookiePath(cookie.path);
         parts.push(`Path=${cookie.path}`);
     }
     if (cookie.domain) {
-        assertSafeAttribute("Domain", cookie.domain);
+        assertCookieDomain(cookie.domain);
         parts.push(`Domain=${cookie.domain}`);
     }
     if (cookie.maxAge !== undefined) {
@@ -165,12 +164,6 @@ export function serializeCookie(cookie, config) {
     }
     return parts.join("; ");
 }
-/** Throws when an attribute value could terminate the attribute or the header. */
-function assertSafeAttribute(attribute, value) {
-    if (ATTRIBUTE_UNSAFE.test(value)) {
-        throw new ValidationError(`Cookie ${attribute} contains invalid characters (injection risk): ${JSON.stringify(value)}`);
-    }
-}
 /**
  * Creates a Set-Cookie header value with secure defaults.
  *

package/dist/csrf/csrf.core.d.ts

@@ -17,6 +17,22 @@
  *
  * Bind the token to a session wherever you have one: without `sessionId`, a
  * token minted for one user validates for every other user.
+ *
+ * Error contract: the verifiers (`validateCsrfToken`, `verifyDoubleSubmit`,
+ * `CsrfProtection.verify`) return `false` for anything wrong with the
+ * *request* — a missing, malformed, non-string, forged, expired or
+ * mismatched token, or a request with no method. They throw
+ * `ConfigurationError` only for a *configuration* mistake: a secret shorter
+ * than {@link MIN_CSRF_SECRET_LENGTH} (32) characters, or an unusable
+ * `methods` list. Load the secret from the environment and refuse to start
+ * without it; never fall back to a hard-coded string:
+ *
+ * ```typescript
+ * const secret = process.env.CSRF_SECRET;
+ * if (!secret || secret.length < MIN_CSRF_SECRET_LENGTH) {
+ *   throw new Error("Set CSRF_SECRET to at least 32 random characters.");
+ * }
+ * ```
  */
 import type { CsrfConfig } from "../types/security.type.js";
 /**
@@ -73,7 +89,10 @@ export declare function validateCsrfToken(token: string, secret: string, options
  * @param requestToken - Token taken from the request header or form field.
  * @param secret - The secret key for verification.
  * @param options - Maximum lifetime and session binding.
- * @returns True when the request carries a matching, valid token.
+ * @returns True when the request carries a matching, valid token; `false`
+ *   for a missing, non-string, mismatched, forged or expired one.
+ * @throws {ConfigurationError} only when the secret is empty or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH} — a misconfiguration, never a bad token.
  */
 export declare function verifyDoubleSubmit(cookieToken: string | undefined, requestToken: string | undefined, secret: string, options?: number | CsrfTokenOptions): boolean;
 /**
@@ -81,7 +100,8 @@ export declare function verifyDoubleSubmit(cookieToken: string | undefined, requ
  *
  * @param method - The HTTP method.
  * @param config - Optional CSRF configuration.
- * @returns True if CSRF protection is required.
+ * @returns True if CSRF protection is required. A missing or non-string
+ *   method is treated as requiring it, so a malformed request fails closed.
  */
 export declare function requiresCsrfProtection(method: string, config?: CsrfConfig): boolean;
 /**
@@ -170,7 +190,8 @@ export interface CsrfProtection {
      * Verify a request under the double-submit pattern.
      *
      * Returns `true` for a method that does not require protection, so it can be
-     * called unconditionally.
+     * called unconditionally, and `false` — never a throw — for a request whose
+     * token is missing, malformed, forged, expired or for another session.
      */
     verify(request: CsrfVerifiableRequest, options?: {
         readonly sessionId?: string;
@@ -193,7 +214,8 @@ export interface CsrfProtection {
  * @param config - Secret, lifetime, cookie/header names, protected methods.
  * @returns Protection bound to that configuration.
  * @throws {ConfigurationError} when the secret is missing or shorter than
- *   {@link MIN_CSRF_SECRET_LENGTH}.
+ *   {@link MIN_CSRF_SECRET_LENGTH}, or when `methods` is present but empty,
+ *   not an array, or contains a non-method entry.
  */
 export declare function createCsrfProtection(config: CsrfProtectionOptions): CsrfProtection;
 //# sourceMappingURL=csrf.core.d.ts.map

package/dist/csrf/csrf.core.js

@@ -17,6 +17,22 @@
  *
  * Bind the token to a session wherever you have one: without `sessionId`, a
  * token minted for one user validates for every other user.
+ *
+ * Error contract: the verifiers (`validateCsrfToken`, `verifyDoubleSubmit`,
+ * `CsrfProtection.verify`) return `false` for anything wrong with the
+ * *request* — a missing, malformed, non-string, forged, expired or
+ * mismatched token, or a request with no method. They throw
+ * `ConfigurationError` only for a *configuration* mistake: a secret shorter
+ * than {@link MIN_CSRF_SECRET_LENGTH} (32) characters, or an unusable
+ * `methods` list. Load the secret from the environment and refuse to start
+ * without it; never fall back to a hard-coded string:
+ *
+ * ```typescript
+ * const secret = process.env.CSRF_SECRET;
+ * if (!secret || secret.length < MIN_CSRF_SECRET_LENGTH) {
+ *   throw new Error("Set CSRF_SECRET to at least 32 random characters.");
+ * }
+ * ```
  */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { ConfigurationError } from "@zudojs/errors";
@@ -38,6 +54,33 @@ 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 (typeof secret !== "string" || secret.length === 0) {
@@ -156,11 +199,20 @@ export function validateCsrfToken(token, secret, options) {
  * @param requestToken - Token taken from the request header or form field.
  * @param secret - The secret key for verification.
  * @param options - Maximum lifetime and session binding.
- * @returns True when the request carries a matching, valid token.
+ * @returns True when the request carries a matching, valid token; `false`
+ *   for a missing, non-string, mismatched, forged or expired one.
+ * @throws {ConfigurationError} only when the secret is empty or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH} — a misconfiguration, never a bad token.
  */
 export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
     assertUsableSecret(secret);
-    if (!cookieToken || !requestToken) {
+    // Both values come from the request. A non-string (a parsed-body number, an
+    // array from a header bag) used to reach `Buffer.from` and throw a
+    // TypeError out of a function whose contract is a boolean.
+    if (typeof cookieToken !== "string" ||
+        typeof requestToken !== "string" ||
+        cookieToken.length === 0 ||
+        requestToken.length === 0) {
         return false;
     }
     if (!safeEqual(cookieToken, requestToken)) {
@@ -173,9 +225,14 @@ export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
  *
  * @param method - The HTTP method.
  * @param config - Optional CSRF configuration.
- * @returns True if CSRF protection is required.
+ * @returns True if CSRF protection is required. A missing or non-string
+ *   method is treated as requiring it, so a malformed request fails closed.
  */
 export function requiresCsrfProtection(method, config) {
+    assertUsableMethods(config?.methods);
+    if (typeof method !== "string") {
+        return true;
+    }
     if (SAFE_METHODS.includes(method.toUpperCase())) {
         return false;
     }
@@ -198,6 +255,8 @@ export function requiresCsrfProtection(method, config) {
  */
 export function extractCsrfTokenFromHeaders(headers, headerName) {
     const name = (headerName ?? DEFAULT_HEADER_NAME).toLowerCase();
+    if (headers === null || typeof headers !== "object")
+        return undefined;
     let value;
     for (const key of Object.keys(headers)) {
         if (key.toLowerCase() === name) {
@@ -208,7 +267,7 @@ export function extractCsrfTokenFromHeaders(headers, headerName) {
     if (typeof value === "string") {
         return value;
     }
-    if (Array.isArray(value) && value.length > 0) {
+    if (Array.isArray(value) && typeof value[0] === "string") {
         return value[0];
     }
     return undefined;
@@ -222,6 +281,8 @@ export function extractCsrfTokenFromHeaders(headers, headerName) {
  */
 export function extractCsrfTokenFromCookies(cookieHeader, cookieName) {
     const name = cookieName ?? DEFAULT_COOKIE_NAME;
+    if (typeof cookieHeader !== "string")
+        return undefined;
     const cookies = cookieHeader.split(";").map((pair) => {
         const eqIndex = pair.indexOf("=");
         if (eqIndex === -1)
@@ -272,10 +333,12 @@ export function generateCsrfCookie(token, config) {
  * @param config - Secret, lifetime, cookie/header names, protected methods.
  * @returns Protection bound to that configuration.
  * @throws {ConfigurationError} when the secret is missing or shorter than
- *   {@link MIN_CSRF_SECRET_LENGTH}.
+ *   {@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;
@@ -301,6 +364,9 @@ export function createCsrfProtection(config) {
             };
         },
         verify(request, options) {
+            if (request === null || typeof request !== "object") {
+                return false;
+            }
             if (!requiresCsrfProtection(request.method, config)) {
                 return true;
             }

package/dist/index.d.ts

@@ -45,5 +45,5 @@ export type { RateLimiterOptions, ClientIpOptions, IpKeyOptions, } from "./rateL
 export { rateLimit } from "./rateLimit/rateLimit.namespace.js";
 export { SECURITY_HEADER_NAMES } from "./headers/index.js";
 export { generateSecurityHeaders, getMissingSecurityHeaders, generateCspNonce, validateCspDirective, } from "./headers/index.js";
-export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, findUnsafeKey, } from "./input/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -48,5 +48,5 @@ export { rateLimit } from "./rateLimit/rateLimit.namespace.js";
 export { SECURITY_HEADER_NAMES } from "./headers/index.js";
 export { generateSecurityHeaders, getMissingSecurityHeaders, generateCspNonce, validateCspDirective, } from "./headers/index.js";
 /* ─── Input Sanitization ─────────────────────────────────────────────────── */
-export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, findUnsafeKey, } from "./input/index.js";
 //# sourceMappingURL=index.js.map

package/dist/input/index.d.ts

@@ -2,4 +2,5 @@
  * @zudojs/security — Input Sanitization Barrel
  */
 export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
+export { findUnsafeKey } from "./input.unsafeKey.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/input/index.js

@@ -2,4 +2,5 @@
  * @zudojs/security — Input Sanitization Barrel
  */
 export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
+export { findUnsafeKey } from "./input.unsafeKey.js";
 //# sourceMappingURL=index.js.map

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,6 +3,7 @@
  *
  * 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";
 /**
@@ -164,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.unsafeKey.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deep detection of prototype-polluting keys in decoded, untrusted data
+ * (objects and arrays). `containsPrototypePollution` covers strings.
+ */
+/**
+ * Returns the first `__proto__`, `constructor` or `prototype` key found
+ * anywhere in `value`, or `undefined` when there is none.
+ *
+ * `JSON.parse` keeps such a key as an ordinary own property, so it reaches
+ * handlers intact; the moment one is copied with `Object.assign`, a
+ * `for…in` merge or a bracket assignment, it replaces the target's
+ * prototype. Transports refuse a frame that carries one rather than
+ * silently dropping it.
+ *
+ * Walks plain objects and arrays only, iteratively (no recursion limit)
+ * and cycle-safe, so it is safe on any decoded or in-process value.
+ */
+export declare function findUnsafeKey(value: unknown): string | undefined;
+//# sourceMappingURL=input.unsafeKey.d.ts.map

package/dist/input/input.unsafeKey.js

@@ -0,0 +1,61 @@
+/**
+ * Deep detection of prototype-polluting keys in decoded, untrusted data
+ * (objects and arrays). `containsPrototypePollution` covers strings.
+ */
+import { SCHEMA_FORBIDDEN_KEYS } from "@zudojs/constants";
+function isTraversable(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return true;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Returns the first `__proto__`, `constructor` or `prototype` key found
+ * anywhere in `value`, or `undefined` when there is none.
+ *
+ * `JSON.parse` keeps such a key as an ordinary own property, so it reaches
+ * handlers intact; the moment one is copied with `Object.assign`, a
+ * `for…in` merge or a bracket assignment, it replaces the target's
+ * prototype. Transports refuse a frame that carries one rather than
+ * silently dropping it.
+ *
+ * Walks plain objects and arrays only, iteratively (no recursion limit)
+ * and cycle-safe, so it is safe on any decoded or in-process value.
+ */
+export function findUnsafeKey(value) {
+    if (!isTraversable(value)) {
+        return undefined;
+    }
+    const seen = new WeakSet();
+    const pending = [value];
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (seen.has(node)) {
+            continue;
+        }
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const child of node) {
+                if (isTraversable(child)) {
+                    pending.push(child);
+                }
+            }
+            continue;
+        }
+        for (const key of Object.keys(node)) {
+            if (SCHEMA_FORBIDDEN_KEYS.has(key)) {
+                return key;
+            }
+            const child = node[key];
+            if (isTraversable(child)) {
+                pending.push(child);
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=input.unsafeKey.js.map

package/dist/rateLimit/rateLimit.clientIp.js

@@ -36,10 +36,18 @@ export function extractClientIp(headers, options) {
         // 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;
+        // 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);

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

@@ -97,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.
  */
@@ -104,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/security",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
   "author": {
@@ -24,13 +24,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/constants": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/constants": "1.1.2"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11",
-    "@types/node": "^26.4.1"
+    "vitest": "^5.0.1",
+    "@types/node": "^26.6.2"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -45,7 +45,7 @@
     "csrf",
     "rate-limiting"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-security",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },