@zudojs/security 1.2.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;

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";
@@ -183,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)) {
@@ -200,10 +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;
     }
@@ -226,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) {
@@ -236,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;
@@ -250,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)
@@ -331,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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/security",
-  "version": "1.2.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.2.0",
-    "@zudojs/constants": "1.1.1"
+    "@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"
   },