@zudojs/security 1.1.0 → 1.2.0

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

@@ -193,7 +193,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

@@ -38,6 +38,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) {
@@ -176,6 +203,7 @@ 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;
     }
@@ -272,10 +300,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;

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/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.2.0",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
   "author": {
@@ -24,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/constants": "1.1.0"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/constants": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",