@zudojs/security 1.3.0 → 1.3.1

package/README.md

@@ -219,6 +219,14 @@ if (requiresCsrfProtection(request.method)) {
 }
 ```
 
+**Which methods skip the check.** Only GET, HEAD, OPTIONS and TRACE, matched
+exactly after upper-casing (no trimming). Every other method is verified —
+including an empty, padded or unknown one (`""`, `" "`, `"POST "`, `"FOO"`),
+and CONNECT. A configured `methods` list can exempt a *standard* method it
+leaves out (`methods: ["DELETE"]` exempts POST), never an unknown or malformed
+one. Before 1.3.1 any method not in the list skipped the check, so
+`csrf.verify({ method: "FOO" })` returned `true` with no token at all.
+
 **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
@@ -228,7 +236,8 @@ 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".
+request is bad". `createCsrfProtection` and `generateCsrfCookie` also throw
+`ValidationError` for a cookie `path` that breaks the `Path` rules below.
 
 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
@@ -287,7 +296,12 @@ an unsafe name, attribute, `Max-Age` or `Expires` throws. `SameSite=None` and
 `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 `,`.
+`ValidationError`. `Path` must be printable ASCII (0x20–0x7E) with no `;` or
+`,`: a control character or any non-ASCII character (`"/ä"`) throws —
+percent-encode it instead (`"/%C3%A4"`). This is RFC 6265's `path-value`
+(any US-ASCII character except controls and `;`) plus the `,` this package has
+always refused; space is inside that grammar, so `"/a b"` is accepted.
+Before 1.3.1 non-ASCII was accepted.
 Previously only a real CR, LF, NUL, `;` or `,` was refused, so the literal text
 `a\r\nX-Evil: 1` was written into `Domain=` unchanged.
 

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

@@ -20,8 +20,9 @@ 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 `,`.
+ * @throws {ValidationError} when it contains a character outside printable
+ *   ASCII (0x20–0x7E: a control character, DEL or any non-ASCII character),
+ *   `;` or `,`. Space is allowed, as RFC 6265 allows it.
  */
 export declare function assertCookiePath(path: string): void;
 //# sourceMappingURL=cookie.attribute.d.ts.map

package/dist/cookie/cookie.attribute.js

@@ -15,11 +15,16 @@ 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
+ * Characters never allowed in `Path`: anything outside printable ASCII
+ * (controls, CR and LF included, DEL, and every non-ASCII character), `;`
+ * which would end the attribute, and `,` which some parsers split
  * `Set-Cookie` on.
+ *
+ * RFC 6265 §4.1.1 defines `path-value` as any CHAR (US-ASCII) except CTLs
+ * or `;`, so non-ASCII such as `"/ä"` is outside the grammar — percent-encode
+ * it (`"/%C3%A4"`). Space (0x20) is inside the grammar and stays allowed.
  */
-const PATH_UNSAFE = /[\x00-\x1F\x7F;,]/;
+const PATH_UNSAFE = /[^\x20-\x7E]|[;,]/;
 /**
  * Validates a cookie `Domain` attribute as a hostname: labels of
  * `[A-Za-z0-9-]` separated by dots, with an optional leading dot.
@@ -44,13 +49,15 @@ export function assertCookieDomain(domain) {
  * Validates a cookie `Path` attribute.
  *
  * @param path - The Path value.
- * @throws {ValidationError} when it contains a control character, DEL, `;`
- *   or `,`.
+ * @throws {ValidationError} when it contains a character outside printable
+ *   ASCII (0x20–0x7E: a control character, DEL or any non-ASCII character),
+ *   `;` or `,`. Space is allowed, as RFC 6265 allows it.
  */
 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)}`);
+        throw new ValidationError(`Cookie Path contains invalid characters (injection risk): only ` +
+            `printable ASCII is allowed (percent-encode anything else), and ";" ` +
+            `and "," are not, got ${JSON.stringify(path)}`);
     }
 }
 //# sourceMappingURL=cookie.attribute.js.map

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

@@ -100,6 +100,15 @@ export declare function verifyDoubleSubmit(cookieToken: string | undefined, requ
  *
  * @param method - The HTTP method.
  * @param config - Optional CSRF configuration.
+ * The rule fails closed. A method skips the check only when, after
+ * upper-casing and with no trimming, it is exactly one of the safe methods
+ * (GET, HEAD, OPTIONS, TRACE) or — when `methods` is configured — a standard
+ * HTTP method the configured list deliberately leaves out (`methods:
+ * ["DELETE"]` exempts POST). Anything else — an empty or padded string
+ * (`""`, `"POST "`), an unknown method (`"FOO"`), CONNECT under the default
+ * list — requires protection. Before 1.3.1 every method not in `methods`
+ * skipped the check, so `""` and `"FOO"` passed `verify()` with no token.
+ *
  * @returns True if CSRF protection is required. A missing or non-string
  *   method is treated as requiring it, so a malformed request fails closed.
  */
@@ -155,6 +164,8 @@ export interface CsrfCookieOptions extends Omit<CsrfConfig, "secret"> {
  * @param token - The CSRF token to store.
  * @param config - Optional CSRF and cookie configuration.
  * @returns The Set-Cookie header value.
+ * @throws {ValidationError} when `path` breaks the cookie `Path` rules
+ *   (see `serializeCookie`).
  */
 export declare function generateCsrfCookie(token: string, config?: Partial<CsrfCookieOptions>): string;
 /** Cookie-shaping options for {@link createCsrfProtection}. */
@@ -216,6 +227,7 @@ export interface CsrfProtection {
  * @throws {ConfigurationError} when the secret is missing or shorter than
  *   {@link MIN_CSRF_SECRET_LENGTH}, or when `methods` is present but empty,
  *   not an array, or contains a non-method entry.
+ * @throws {ValidationError} when `path` breaks the cookie `Path` rules.
  */
 export declare function createCsrfProtection(config: CsrfProtectionOptions): CsrfProtection;
 //# sourceMappingURL=csrf.core.d.ts.map

package/dist/csrf/csrf.core.js

@@ -35,17 +35,17 @@
  * ```
  */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { HTTP_METHODS } from "@zudojs/constants";
 import { ConfigurationError } from "@zudojs/errors";
+import { assertCookiePath } from "../cookie/cookie.attribute.js";
 /** Default token expiration (1 hour). */
 const DEFAULT_EXPIRATION = 3600;
 /** Default cookie name for CSRF token. */
 const DEFAULT_COOKIE_NAME = "_csrf";
 /** Default header name for CSRF token. */
 const DEFAULT_HEADER_NAME = "x-csrf-token";
-/** Methods that require CSRF protection. */
+/** Methods that never require CSRF protection (RFC 9110 safe methods). */
 const SAFE_METHODS = ["GET", "HEAD", "OPTIONS", "TRACE"];
-/** Default methods that require CSRF protection. */
-const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
 /**
  * Minimum accepted secret length, in characters.
  *
@@ -225,6 +225,15 @@ export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
  *
  * @param method - The HTTP method.
  * @param config - Optional CSRF configuration.
+ * The rule fails closed. A method skips the check only when, after
+ * upper-casing and with no trimming, it is exactly one of the safe methods
+ * (GET, HEAD, OPTIONS, TRACE) or — when `methods` is configured — a standard
+ * HTTP method the configured list deliberately leaves out (`methods:
+ * ["DELETE"]` exempts POST). Anything else — an empty or padded string
+ * (`""`, `"POST "`), an unknown method (`"FOO"`), CONNECT under the default
+ * list — requires protection. Before 1.3.1 every method not in `methods`
+ * skipped the check, so `""` and `"FOO"` passed `verify()` with no token.
+ *
  * @returns True if CSRF protection is required. A missing or non-string
  *   method is treated as requiring it, so a malformed request fails closed.
  */
@@ -233,15 +242,21 @@ export function requiresCsrfProtection(method, config) {
     if (typeof method !== "string") {
         return true;
     }
-    if (SAFE_METHODS.includes(method.toUpperCase())) {
-        return false;
-    }
     // HTTP methods are case-sensitive on the wire but configured by hand;
     // comparing a lower-case `methods: ["post"]` against the upper-cased
     // request method used to protect nothing, silently.
     const upper = method.toUpperCase();
-    const methods = config?.methods ?? DEFAULT_METHODS;
-    return methods.some((m) => String(m).toUpperCase() === upper);
+    if (SAFE_METHODS.includes(upper)) {
+        return false;
+    }
+    const configured = config?.methods;
+    if (configured === undefined) {
+        return true;
+    }
+    if (configured.some((m) => String(m).toUpperCase() === upper)) {
+        return true;
+    }
+    return !HTTP_METHODS.has(upper);
 }
 /**
  * Extracts the CSRF token from request headers.
@@ -301,6 +316,8 @@ export function extractCsrfTokenFromCookies(cookieHeader, cookieName) {
  * @param token - The CSRF token to store.
  * @param config - Optional CSRF and cookie configuration.
  * @returns The Set-Cookie header value.
+ * @throws {ValidationError} when `path` breaks the cookie `Path` rules
+ *   (see `serializeCookie`).
  */
 export function generateCsrfCookie(token, config) {
     const name = config?.cookieName ?? DEFAULT_COOKIE_NAME;
@@ -308,6 +325,7 @@ export function generateCsrfCookie(token, config) {
     const httpOnly = config?.httpOnly ?? true;
     const secure = config?.secure ?? true;
     const path = config?.path ?? "/";
+    assertCookiePath(path);
     const parts = [`${name}=${token}`, `Path=${path}`];
     if (httpOnly) {
         parts.push("HttpOnly");
@@ -335,10 +353,13 @@ export function generateCsrfCookie(token, config) {
  * @throws {ConfigurationError} when the secret is missing or shorter than
  *   {@link MIN_CSRF_SECRET_LENGTH}, or when `methods` is present but empty,
  *   not an array, or contains a non-method entry.
+ * @throws {ValidationError} when `path` breaks the cookie `Path` rules.
  */
 export function createCsrfProtection(config) {
     assertUsableSecret(config.secret);
     assertUsableMethods(config.methods);
+    if (config.path !== undefined)
+        assertCookiePath(config.path);
     const expiration = config.expiration ?? DEFAULT_EXPIRATION;
     const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
     const headerName = config.headerName ?? DEFAULT_HEADER_NAME;

package/dist/types/security.type.d.ts

@@ -114,7 +114,13 @@ export interface CsrfConfig {
     readonly cookieName?: string;
     /** Header name for the CSRF token. */
     readonly headerName?: string;
-    /** Methods that require CSRF protection. */
+    /**
+     * Methods that require CSRF protection (default: POST, PUT, PATCH, DELETE).
+     *
+     * GET, HEAD, OPTIONS and TRACE never require it. A standard HTTP method
+     * left out of this list is exempt; an unknown, empty or malformed method
+     * always requires protection, whatever this list says.
+     */
     readonly methods?: readonly string[];
 }
 /** Configuration for rate limiting. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/security",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.",
   "license": "MIT",
   "author": {