@zudojs/security 1.0.1 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Security primitives for input validation, header security, CORS, CSRF protection, rate limiting, and security headers.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-security](https://zudojs.oyinlola.site/docs/packages-security) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-security.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -100,6 +106,20 @@ own rate-limit bucket. Set `trustProxy` to the number of proxies you actually
 operate; entries are then read in from the right, and everything to the left of
 your own hops is ignored.
 
+The address it returns has any port and IPv6 brackets removed (some proxies
+append `client-ip:port`, which used to give every TCP connection its own
+bucket). The default key generator then keys IPv4 as-is, IPv4-mapped IPv6 as
+IPv4, and other IPv6 by its **/64**, so one host cannot rotate through its own
+prefix. Use `createIpKeyGenerator({ ipv6PrefixLength })` for another prefix,
+and `ipRateLimitKey(ip)` to compute the key yourself; `getCount(ip)` and
+`reset(ip)` accept the raw address.
+
+**The default key generator throws a `ConfigurationError` when `ip` is
+missing or is not an address** (including the `"unknown"` placeholder
+`extractClientIp` returns when it has nothing to go on). Those requests used
+to share one `"unknown"` bucket, so one client could starve everyone else.
+Always pass `remoteAddress`, or supply your own `keyGenerator`.
+
 ## CORS
 
 ```typescript
@@ -153,6 +173,7 @@ const { token, setCookie } = csrf.issue({ sessionId });
 setHeader("Set-Cookie", setCookie);
 
 // Verify — safe to call on every request; safe methods return true.
+// `methods` (default POST, PUT, PATCH, DELETE) is matched case-insensitively.
 if (!csrf.verify(
   { method: request.method, headers: request.headers, cookieHeader: request.headers.cookie },
   { sessionId },
@@ -189,6 +210,11 @@ 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.
+
 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
 double-submit pattern — where client script reads the cookie back — pass
@@ -209,8 +235,18 @@ isSafeUrl("gopher://internal/"); // false — protocol not allowlisted
 ```
 
 Addresses are range-checked numerically (127/8, 10/8, 172.16/12, 192.168/16,
-169.254/16, 100.64/10, 0/8, `::1`, `fc00::/7`, `fe80::/10`), and only `http:`
-and `https:` are permitted unless you widen `allowedProtocols`.
+169.254/16, 100.64/10, 0/8, `::1`, `fc00::/7`, `fe80::/10`, `fec0::/10`,
+`ff00::/8`), and only `http:` and `https:` are permitted unless you widen
+`allowedProtocols`. IPv6 forms that embed an IPv4 address — `::a.b.c.d`,
+`::ffff:a.b.c.d`, `::ffff:0:a.b.c.d`, NAT64 `64:ff9b::/96` and 6to4
+`2002::/16` — are judged as that IPv4 address, whatever spelling the URL
+parser gives them; the local-use NAT64 prefix `64:ff9b:1::/48` is refused.
+
+The building blocks are exported for other guards: `expandIpv6(address)`
+returns the eight 16-bit groups (or `undefined`), `embeddedIpv4(groups)`
+returns the embedded IPv4 octets for the forms above (or `undefined`), and
+`isNonPublicIpv6Range(groups)` is `true` for `fc00::/7`, `fe80::/10`,
+`fec0::/10`, `ff00::/8` and `64:ff9b:1::/48`.
 
 **This cannot stop DNS rebinding.** A public hostname may resolve to a private
 address, and may resolve differently between the check and the connection. For
@@ -240,6 +276,13 @@ reached the caller with `errors: []`. Values are otherwise accepted leniently
 (spaces, commas and quoted-string wrappers are common in the wild); use
 `validateCookieValue` where you want the strict `cookie-octet` rule.
 
+`stripSensitiveCookies(header)` removes a cookie when a sensitive word appears
+anywhere in its name as a whole word (split on `.`, `-`, `_` and camelCase,
+after dropping a `__Host-`/`__Secure-` prefix). The defaults
+(`DEFAULT_SENSITIVE_COOKIE_NAMES`) cover `session`, `sid`, `token`, `auth`,
+`jwt`, `csrf` and the framework defaults `connect.sid`, `PHPSESSID` and
+`JSESSIONID`; `theme` or `sidebar` survive.
+
 ```typescript
 createSecureCookie("sid", value, { maxAge: 3600 });
 // sid=…; Max-Age=3600; Secure; HttpOnly; SameSite=Lax
@@ -255,9 +298,17 @@ detectThreats(input); // ordered: SQL_INJECTION, XSS, NULL_BYTE, CONTROL_CHARACT
 escapeHtml(text);
 ```
 
-`detectThreats` and `containsSqlInjection` are heuristics with a high
-false-positive rate on ordinary prose — useful for logging and alerting, never a
-substitute for parameterised queries or contextual output encoding.
+`detectThreats`, `containsSqlInjection` and `containsXss` are heuristics with a
+high false-positive rate on ordinary prose — useful for logging and alerting,
+never a substitute for parameterised queries or contextual output encoding.
+`containsXss` decodes HTML character references (`jav&#x61;script:`,
+`javascript&colon;`) and ignores whitespace inside a scheme before matching.
+
+Body limits must be finite numbers above zero: `validateBodySize`,
+`validateContentLength` and `createBodySizeChecker` throw `ConfigurationError`
+for `NaN` (what `Number(process.env.BODY_LIMIT)` gives when the variable is
+unset), and `validateBodyLimitConfig` reports it — a `NaN` limit used to allow
+any body.
 `escapeHtml` covers element text and quoted attribute values; unquoted
 attributes, `<script>` bodies and URL positions need their own encoding.
 

package/dist/body/body.core.d.ts

@@ -10,7 +10,10 @@ export declare const DEFAULT_BODY_LIMITS: BodyLimitPresets;
  * Validates the Content-Length header value.
  *
  * @param contentLength - The Content-Length header value.
+ * @param maxSize - Optional maximum in bytes.
  * @returns An error message if invalid, or undefined.
+ * @throws {ConfigurationError} when `maxSize` is given but is `NaN`,
+ *   infinite or not above 0.
  */
 export declare function validateContentLength(contentLength: string | undefined, maxSize?: number): string | undefined;
 /**
@@ -32,6 +35,8 @@ export declare function validateBodyFraming(headers: Record<string, string | str
  * @param maxSize - The maximum allowed size in bytes.
  * @param contentType - Optional content type for context in error messages.
  * @returns An error message if too large, or undefined.
+ * @throws {ConfigurationError} when `maxSize` is `NaN`, infinite or not
+ *   above 0 — it used to disable the check.
  */
 export declare function validateBodySize(actualSize: number, maxSize?: number, contentType?: string): string | undefined;
 /**
@@ -91,6 +96,7 @@ export declare function resolveBodyLimit(contentType: string | undefined, rules:
  * @param maxSize - The maximum body size in bytes.
  * @param contentType - Optional content type to check against.
  * @returns A function that checks if a size is within limits.
+ * @throws {ConfigurationError} when `maxSize` is not a finite number above 0.
  */
 export declare function createBodySizeChecker(maxSize: number, contentType?: string): (size: number) => {
     allowed: boolean;

package/dist/body/body.core.js

@@ -3,6 +3,7 @@
  *
  * Validates request body size and content type against configurable limits.
  */
+import { assertBodyLimit, isUsableBodyLimit } from "./body.guard.js";
 /** Default body limits for common use cases. */
 export const DEFAULT_BODY_LIMITS = {
     /** JSON API: 1MB */
@@ -20,7 +21,10 @@ const DEFAULT_MAX_BODY_SIZE = 1_048_576;
  * Validates the Content-Length header value.
  *
  * @param contentLength - The Content-Length header value.
+ * @param maxSize - Optional maximum in bytes.
  * @returns An error message if invalid, or undefined.
+ * @throws {ConfigurationError} when `maxSize` is given but is `NaN`,
+ *   infinite or not above 0.
  */
 export function validateContentLength(contentLength, maxSize) {
     if (contentLength === undefined) {
@@ -36,6 +40,8 @@ export function validateContentLength(contentLength, maxSize) {
     if (!Number.isSafeInteger(parsed)) {
         return `Content-Length is not a safe integer: ${contentLength}`;
     }
+    if (maxSize !== undefined)
+        assertBodyLimit(maxSize);
     if (maxSize !== undefined && parsed > maxSize) {
         return `Content-Length ${parsed} exceeds maximum ${maxSize} bytes`;
     }
@@ -101,9 +107,15 @@ export function validateBodyFraming(headers, maxSize) {
  * @param maxSize - The maximum allowed size in bytes.
  * @param contentType - Optional content type for context in error messages.
  * @returns An error message if too large, or undefined.
+ * @throws {ConfigurationError} when `maxSize` is `NaN`, infinite or not
+ *   above 0 — it used to disable the check.
  */
 export function validateBodySize(actualSize, maxSize, contentType) {
     const limit = maxSize ?? DEFAULT_MAX_BODY_SIZE;
+    assertBodyLimit(limit);
+    if (!Number.isFinite(actualSize) || actualSize < 0) {
+        return `Body size is not a valid byte count: ${actualSize}`;
+    }
     if (actualSize > limit) {
         const context = contentType ? ` for ${contentType}` : "";
         return `Body size ${actualSize} bytes exceeds maximum ${limit} bytes${context}`;
@@ -184,7 +196,7 @@ export function getBodyLimitForContentType(contentType, presetLimits, purpose) {
  * @returns An error message if invalid, or undefined.
  */
 export function validateBodyLimitConfig(config) {
-    if (config.maxSize <= 0) {
+    if (!isUsableBodyLimit(config.maxSize)) {
         return `Body limit maxSize must be positive, got: ${config.maxSize}`;
     }
     if (config.maxSize > 1_073_741_824) {
@@ -244,8 +256,10 @@ export function resolveBodyLimit(contentType, rules, fallback = DEFAULT_MAX_BODY
  * @param maxSize - The maximum body size in bytes.
  * @param contentType - Optional content type to check against.
  * @returns A function that checks if a size is within limits.
+ * @throws {ConfigurationError} when `maxSize` is not a finite number above 0.
  */
 export function createBodySizeChecker(maxSize, contentType) {
+    assertBodyLimit(maxSize);
     return (size) => {
         const error = validateBodySize(size, maxSize, contentType);
         return {

package/dist/body/body.guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @zudojs/security — Body limit guards.
+ */
+/**
+ * True when `value` is usable as a body size limit: a finite number above 0.
+ *
+ * `NaN` is the case that matters. `Number(process.env.BODY_LIMIT)` with the
+ * variable unset yields `NaN`, which slipped past `limit <= 0` and made every
+ * `size > limit` comparison false, so an unset limit allowed any body.
+ */
+export declare function isUsableBodyLimit(value: unknown): value is number;
+/**
+ * Throws unless `value` is a usable body size limit.
+ *
+ * @throws {ConfigurationError} when `value` is `NaN`, infinite, zero,
+ *   negative or not a number.
+ */
+export declare function assertBodyLimit(value: unknown, name?: string): asserts value is number;
+//# sourceMappingURL=body.guard.d.ts.map

package/dist/body/body.guard.js

@@ -0,0 +1,26 @@
+/**
+ * @zudojs/security — Body limit guards.
+ */
+import { ConfigurationError } from "@zudojs/errors";
+/**
+ * True when `value` is usable as a body size limit: a finite number above 0.
+ *
+ * `NaN` is the case that matters. `Number(process.env.BODY_LIMIT)` with the
+ * variable unset yields `NaN`, which slipped past `limit <= 0` and made every
+ * `size > limit` comparison false, so an unset limit allowed any body.
+ */
+export function isUsableBodyLimit(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+/**
+ * Throws unless `value` is a usable body size limit.
+ *
+ * @throws {ConfigurationError} when `value` is `NaN`, infinite, zero,
+ *   negative or not a number.
+ */
+export function assertBodyLimit(value, name = "maxSize") {
+    if (!isUsableBodyLimit(value)) {
+        throw new ConfigurationError(`Body limit ${name} must be a finite number of bytes above 0, got: ${String(value)}`);
+    }
+}
+//# sourceMappingURL=body.guard.js.map

package/dist/cookie/cookie.core.d.ts

@@ -27,7 +27,7 @@ export declare function parseCookieHeader(cookieHeader: string, config?: CookieS
  * @param cookie - The cookie to serialize.
  * @param config - Optional security configuration for defaults.
  * @returns The serialized Set-Cookie header value.
- * @throws {Error} when the name, value, or an attribute is unsafe.
+ * @throws {ValidationError} when the name, value, or an attribute is unsafe.
  */
 export declare function serializeCookie(cookie: ParsedCookie, config?: CookieSecurityConfig): string;
 /**
@@ -38,7 +38,7 @@ export declare function serializeCookie(cookie: ParsedCookie, config?: CookieSec
  * @param options - Optional cookie attributes.
  * @param config - Optional security configuration.
  * @returns The serialized Set-Cookie header value.
- * @throws {Error} when the name, value, or an attribute is unsafe.
+ * @throws {ValidationError} when the name, value, or an attribute is unsafe.
  */
 export declare function createSecureCookie(name: string, value: string, options?: Partial<Omit<ParsedCookie, "name" | "value">>, config?: CookieSecurityConfig): string;
 /**
@@ -58,12 +58,16 @@ export declare function validateCookieValue(value: string): string | undefined;
 /**
  * Strips security-sensitive cookies from a cookie header.
  *
- * Matching is on the whole name and on `name`-prefixed variants (`session`
- * also strips `session_id` and `session-token`), because the sensitive cookie
- * in a real deployment is rarely named exactly `session`.
+ * A cookie is stripped when any configured name appears in its name as a
+ * whole word (words are split on `.`, `-`, `_` and camelCase, after a
+ * `__Host-`/`__Secure-` prefix is dropped). So `session` strips `session`,
+ * `session_id`, `__Host-session` and `next-auth.session-token`, and the
+ * defaults also strip `connect.sid`, `PHPSESSID`, `access_token` and
+ * `refresh_token`, which the old prefix-only match let through.
  *
  * @param cookieHeader - The raw Cookie header.
- * @param sensitiveNames - Names of cookies to strip (case-insensitive).
+ * @param sensitiveNames - Names of cookies to strip (case-insensitive;
+ *   default {@link DEFAULT_SENSITIVE_COOKIE_NAMES}).
  * @returns The cleaned cookie header.
  */
 export declare function stripSensitiveCookies(cookieHeader: string, sensitiveNames?: readonly string[]): string;

package/dist/cookie/cookie.core.js

@@ -3,6 +3,8 @@
  *
  * Parses, validates, and serializes HTTP cookies with security best practices.
  */
+import { ValidationError } from "@zudojs/errors";
+import { DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie.sensitive.js";
 /** Maximum cookie header size (4KB). */
 const MAX_COOKIE_HEADER_SIZE = 4096;
 /** Maximum number of cookies. */
@@ -101,12 +103,12 @@ export function parseCookieHeader(cookieHeader, config) {
  * @param cookie - The cookie to serialize.
  * @param config - Optional security configuration for defaults.
  * @returns The serialized Set-Cookie header value.
- * @throws {Error} when the name, value, or an attribute is unsafe.
+ * @throws {ValidationError} when the name, value, or an attribute is unsafe.
  */
 export function serializeCookie(cookie, config) {
     const nameError = validateCookieName(cookie.name);
     if (nameError) {
-        throw new Error(`Cannot serialize cookie: ${nameError}`);
+        throw new ValidationError(`Cannot serialize cookie: ${nameError}`);
     }
     // Percent-encode unless the value is already a bare cookie-octet string, so
     // a caller that passes an encoded value does not get it double-encoded.
@@ -115,7 +117,7 @@ export function serializeCookie(cookie, config) {
         : encodeURIComponent(cookie.value);
     const valueError = validateCookieValue(encodedValue);
     if (valueError) {
-        throw new Error(`Cannot serialize cookie "${cookie.name}": ${valueError}`);
+        throw new ValidationError(`Cannot serialize cookie "${cookie.name}": ${valueError}`);
     }
     const parts = [`${cookie.name}=${encodedValue}`];
     if (cookie.path) {
@@ -128,13 +130,13 @@ export function serializeCookie(cookie, config) {
     }
     if (cookie.maxAge !== undefined) {
         if (!Number.isInteger(cookie.maxAge)) {
-            throw new Error(`Cannot serialize cookie "${cookie.name}": Max-Age must be an integer, got ${cookie.maxAge}`);
+            throw new ValidationError(`Cannot serialize cookie "${cookie.name}": Max-Age must be an integer, got ${cookie.maxAge}`);
         }
         parts.push(`Max-Age=${cookie.maxAge}`);
     }
     if (cookie.expires) {
         if (Number.isNaN(cookie.expires.getTime())) {
-            throw new Error(`Cannot serialize cookie "${cookie.name}": Expires is an invalid Date`);
+            throw new ValidationError(`Cannot serialize cookie "${cookie.name}": Expires is an invalid Date`);
         }
         parts.push(`Expires=${cookie.expires.toUTCString()}`);
     }
@@ -144,11 +146,11 @@ export function serializeCookie(cookie, config) {
     // SameSite=None is only honoured on a Secure cookie; without it browsers
     // reject the cookie outright, which fails as a silent loss of state.
     if (sameSite === "none" && !secure) {
-        throw new Error(`Cannot serialize cookie "${cookie.name}": SameSite=None requires the Secure attribute`);
+        throw new ValidationError(`Cannot serialize cookie "${cookie.name}": SameSite=None requires the Secure attribute`);
     }
     // Partitioned (CHIPS) likewise requires Secure.
     if (cookie.partitioned && !secure) {
-        throw new Error(`Cannot serialize cookie "${cookie.name}": Partitioned requires the Secure attribute`);
+        throw new ValidationError(`Cannot serialize cookie "${cookie.name}": Partitioned requires the Secure attribute`);
     }
     if (secure) {
         parts.push("Secure");
@@ -166,7 +168,7 @@ export function serializeCookie(cookie, config) {
 /** Throws when an attribute value could terminate the attribute or the header. */
 function assertSafeAttribute(attribute, value) {
     if (ATTRIBUTE_UNSAFE.test(value)) {
-        throw new Error(`Cookie ${attribute} contains invalid characters (injection risk): ${JSON.stringify(value)}`);
+        throw new ValidationError(`Cookie ${attribute} contains invalid characters (injection risk): ${JSON.stringify(value)}`);
     }
 }
 /**
@@ -177,7 +179,7 @@ function assertSafeAttribute(attribute, value) {
  * @param options - Optional cookie attributes.
  * @param config - Optional security configuration.
  * @returns The serialized Set-Cookie header value.
- * @throws {Error} when the name, value, or an attribute is unsafe.
+ * @throws {ValidationError} when the name, value, or an attribute is unsafe.
  */
 export function createSecureCookie(name, value, options, config) {
     return serializeCookie({ name, value, ...options }, config);
@@ -225,16 +227,19 @@ export function validateCookieValue(value) {
 /**
  * Strips security-sensitive cookies from a cookie header.
  *
- * Matching is on the whole name and on `name`-prefixed variants (`session`
- * also strips `session_id` and `session-token`), because the sensitive cookie
- * in a real deployment is rarely named exactly `session`.
+ * A cookie is stripped when any configured name appears in its name as a
+ * whole word (words are split on `.`, `-`, `_` and camelCase, after a
+ * `__Host-`/`__Secure-` prefix is dropped). So `session` strips `session`,
+ * `session_id`, `__Host-session` and `next-auth.session-token`, and the
+ * defaults also strip `connect.sid`, `PHPSESSID`, `access_token` and
+ * `refresh_token`, which the old prefix-only match let through.
  *
  * @param cookieHeader - The raw Cookie header.
- * @param sensitiveNames - Names of cookies to strip (case-insensitive).
+ * @param sensitiveNames - Names of cookies to strip (case-insensitive;
+ *   default {@link DEFAULT_SENSITIVE_COOKIE_NAMES}).
  * @returns The cleaned cookie header.
  */
-export function stripSensitiveCookies(cookieHeader, sensitiveNames = ["session", "token", "auth", "jwt"]) {
-    const lowerSensitive = sensitiveNames.map((n) => n.toLowerCase());
+export function stripSensitiveCookies(cookieHeader, sensitiveNames = DEFAULT_SENSITIVE_COOKIE_NAMES) {
     return cookieHeader
         .split(";")
         .map((pair) => pair.trim())
@@ -242,11 +247,8 @@ export function stripSensitiveCookies(cookieHeader, sensitiveNames = ["session",
         const eqIndex = pair.indexOf("=");
         if (eqIndex === -1)
             return false;
-        const name = pair.slice(0, eqIndex).trim().toLowerCase();
-        return !lowerSensitive.some((sensitive) => name === sensitive ||
-            name.startsWith(`${sensitive}_`) ||
-            name.startsWith(`${sensitive}-`) ||
-            name.startsWith(`${sensitive}.`));
+        const name = pair.slice(0, eqIndex).trim();
+        return !isSensitiveCookieName(name, sensitiveNames);
     })
         .join("; ");
 }

package/dist/cookie/cookie.sensitive.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/security — Sensitive cookie name matching.
+ */
+/**
+ * Default names treated as credentials by `stripSensitiveCookies`.
+ *
+ * Covers the generic words (`session`, `token`, `auth`, `jwt`, `csrf`) and
+ * the framework defaults that contain none of them: `connect.sid`
+ * (express-session), `PHPSESSID`, `JSESSIONID`, `ASP.NET_SessionId`.
+ */
+export declare const DEFAULT_SENSITIVE_COOKIE_NAMES: readonly string[];
+/**
+ * Splits a cookie name into lower-case words: `__Secure-next-auth.session-token`
+ * becomes `next auth session token`, `sessionId` becomes `session id`.
+ */
+export declare function cookieNameWords(name: string): string[];
+/**
+ * True when `sensitive` appears in the cookie name as a whole word or a
+ * run of whole words.
+ *
+ * Matching whole words anywhere in the name — not just as a prefix — is
+ * what catches `access_token`, `refresh_token` and `connect.sid`, and
+ * dropping the `__Host-`/`__Secure-` prefix first is what catches
+ * `__Host-session`. Word boundaries keep `theme` or `sidebar` from matching.
+ */
+export declare function isSensitiveCookieName(name: string, sensitiveNames?: readonly string[]): boolean;
+//# sourceMappingURL=cookie.sensitive.d.ts.map

package/dist/cookie/cookie.sensitive.js

@@ -0,0 +1,61 @@
+/**
+ * @zudojs/security — Sensitive cookie name matching.
+ */
+/**
+ * Default names treated as credentials by `stripSensitiveCookies`.
+ *
+ * Covers the generic words (`session`, `token`, `auth`, `jwt`, `csrf`) and
+ * the framework defaults that contain none of them: `connect.sid`
+ * (express-session), `PHPSESSID`, `JSESSIONID`, `ASP.NET_SessionId`.
+ */
+export const DEFAULT_SENSITIVE_COOKIE_NAMES = Object.freeze([
+    "session",
+    "sessionid",
+    "sess",
+    "sid",
+    "phpsessid",
+    "jsessionid",
+    "token",
+    "auth",
+    "jwt",
+    "csrf",
+    "xsrf",
+]);
+/** Cookie-name prefixes that carry no meaning of their own. */
+const COOKIE_PREFIX = /^__(host|secure)-/;
+/**
+ * Splits a cookie name into lower-case words: `__Secure-next-auth.session-token`
+ * becomes `next auth session token`, `sessionId` becomes `session id`.
+ */
+export function cookieNameWords(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .replace(COOKIE_PREFIX, "")
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 0);
+}
+/**
+ * True when `sensitive` appears in the cookie name as a whole word or a
+ * run of whole words.
+ *
+ * Matching whole words anywhere in the name — not just as a prefix — is
+ * what catches `access_token`, `refresh_token` and `connect.sid`, and
+ * dropping the `__Host-`/`__Secure-` prefix first is what catches
+ * `__Host-session`. Word boundaries keep `theme` or `sidebar` from matching.
+ */
+export function isSensitiveCookieName(name, sensitiveNames = DEFAULT_SENSITIVE_COOKIE_NAMES) {
+    const words = cookieNameWords(name);
+    return sensitiveNames.some((sensitive) => {
+        const needle = cookieNameWords(sensitive);
+        if (needle.length === 0)
+            return false;
+        for (let start = 0; start + needle.length <= words.length; start++) {
+            if (needle.every((word, offset) => words[start + offset] === word)) {
+                return true;
+            }
+        }
+        return false;
+    });
+}
+//# sourceMappingURL=cookie.sensitive.js.map

package/dist/cookie/index.d.ts

@@ -2,4 +2,5 @@
  * @zudojs/security — Cookie Security Barrel
  */
 export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie.core.js";
+export { DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie.sensitive.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cookie/index.js

@@ -2,4 +2,5 @@
  * @zudojs/security — Cookie Security Barrel
  */
 export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie.core.js";
+export { DEFAULT_SENSITIVE_COOKIE_NAMES, isSensitiveCookieName, } from "./cookie.sensitive.js";
 //# sourceMappingURL=index.js.map

package/dist/cors/cors.core.js

@@ -4,6 +4,7 @@
  * Validates and generates CORS headers for cross-origin requests.
  */
 import { withoutStickyFlags } from "../input/input.core.js";
+import { ConfigurationError } from "@zudojs/errors";
 /** Default CORS configuration (restrictive). */
 const DEFAULT_CORS_CONFIG = {
     origin: undefined,
@@ -26,7 +27,7 @@ function assertConfigCoherent(config) {
     const origin = config.origin;
     const hasWildcard = origin === "*" || (Array.isArray(origin) && origin.includes("*"));
     if (hasWildcard) {
-        throw new Error('CORS: credentials cannot be combined with a wildcard origin ("*"). ' +
+        throw new ConfigurationError('CORS: credentials cannot be combined with a wildcard origin ("*"). ' +
             "Enumerate the allowed origins, or supply a function or RegExp.");
     }
 }

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

@@ -57,6 +57,8 @@ export declare function generateCsrfToken(secret: string, options?: number | Csr
  * @param options - Maximum lifetime and session binding, or a bare expiration
  *   in seconds for backwards compatibility.
  * @returns True if the token is valid, unexpired, and bound to this session.
+ * @throws {ConfigurationError} when the secret is empty or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH}, exactly as `generateCsrfToken` does.
  */
 export declare function validateCsrfToken(token: string, secret: string, options?: number | CsrfTokenOptions): boolean;
 /**
@@ -190,7 +192,7 @@ export interface CsrfProtection {
  *
  * @param config - Secret, lifetime, cookie/header names, protected methods.
  * @returns Protection bound to that configuration.
- * @throws {Error} when the secret is missing or shorter than
+ * @throws {ConfigurationError} when the secret is missing or shorter than
  *   {@link MIN_CSRF_SECRET_LENGTH}.
  */
 export declare function createCsrfProtection(config: CsrfProtectionOptions): CsrfProtection;

package/dist/csrf/csrf.core.js

@@ -19,6 +19,7 @@
  * token minted for one user validates for every other user.
  */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { ConfigurationError } from "@zudojs/errors";
 /** Default token expiration (1 hour). */
 const DEFAULT_EXPIRATION = 3600;
 /** Default cookie name for CSRF token. */
@@ -39,12 +40,12 @@ const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
 export const MIN_CSRF_SECRET_LENGTH = 32;
 /** Rejects a secret too short to be worth signing with. */
 function assertUsableSecret(secret) {
-    if (secret.length === 0) {
-        throw new Error("CSRF secret cannot be empty: pass a random string of at least " +
+    if (typeof secret !== "string" || secret.length === 0) {
+        throw new ConfigurationError("CSRF secret cannot be empty: pass a random string of at least " +
             `${MIN_CSRF_SECRET_LENGTH} characters, e.g. randomBytes(32).toString("hex")`);
     }
     if (secret.length < MIN_CSRF_SECRET_LENGTH) {
-        throw new Error(`CSRF secret is too short: got ${secret.length} characters, expected at least ` +
+        throw new ConfigurationError(`CSRF secret is too short: got ${secret.length} characters, expected at least ` +
             `${MIN_CSRF_SECRET_LENGTH}. The signature is HMAC-SHA256, so a shorter ` +
             'secret adds no strength. Generate one with randomBytes(32).toString("hex").');
     }
@@ -101,10 +102,18 @@ export function generateCsrfToken(secret, options) {
  * @param options - Maximum lifetime and session binding, or a bare expiration
  *   in seconds for backwards compatibility.
  * @returns True if the token is valid, unexpired, and bound to this session.
+ * @throws {ConfigurationError} when the secret is empty or shorter than
+ *   {@link MIN_CSRF_SECRET_LENGTH}, exactly as `generateCsrfToken` does.
  */
 export function validateCsrfToken(token, secret, options) {
+    // Same bar as `generateCsrfToken`: a verifier configured with
+    // `process.env.CSRF_SECRET ?? ""` otherwise accepted tokens anyone can sign
+    // with an empty HMAC key.
+    assertUsableSecret(secret);
     const opts = typeof options === "number" ? { expiration: options } : (options ?? {});
     const maxTtl = opts.expiration ?? DEFAULT_EXPIRATION;
+    if (typeof token !== "string")
+        return false;
     const parts = token.split(":");
     if (parts.length !== 3) {
         return false;
@@ -150,6 +159,7 @@ export function validateCsrfToken(token, secret, options) {
  * @returns True when the request carries a matching, valid token.
  */
 export function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
+    assertUsableSecret(secret);
     if (!cookieToken || !requestToken) {
         return false;
     }
@@ -169,8 +179,12 @@ export function requiresCsrfProtection(method, config) {
     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.includes(method.toUpperCase());
+    return methods.some((m) => String(m).toUpperCase() === upper);
 }
 /**
  * Extracts the CSRF token from request headers.
@@ -257,7 +271,7 @@ export function generateCsrfCookie(token, config) {
  *
  * @param config - Secret, lifetime, cookie/header names, protected methods.
  * @returns Protection bound to that configuration.
- * @throws {Error} when the secret is missing or shorter than
+ * @throws {ConfigurationError} when the secret is missing or shorter than
  *   {@link MIN_CSRF_SECRET_LENGTH}.
  */
 export function createCsrfProtection(config) {

package/dist/headers/headers.core.js

@@ -4,6 +4,7 @@
  * Generates security-related HTTP response headers with secure defaults.
  */
 import { randomBytes } from "node:crypto";
+import { ConfigurationError } from "@zudojs/errors";
 /** Security header names. */
 export const SECURITY_HEADER_NAMES = {
     CONTENT_SECURITY_POLICY: "Content-Security-Policy",
@@ -58,7 +59,7 @@ export function generateSecurityHeaders(config) {
     if (config) {
         for (const [key, value] of Object.entries(config)) {
             if (typeof value === "string" && /[\r\n\x00]/.test(value)) {
-                throw new Error(`Security header "${key}" contains CRLF or null bytes (injection risk)`);
+                throw new ConfigurationError(`Security header "${key}" contains CRLF or null bytes (injection risk)`);
             }
         }
     }