@zudojs/security 0.0.1 → 1.0.0

package/dist/cookie/cookie.core.js

@@ -9,6 +9,26 @@ const MAX_COOKIE_HEADER_SIZE = 4096;
 const MAX_COOKIE_COUNT = 50;
 /** Maximum individual cookie size. */
 const MAX_COOKIE_SIZE = 1024;
+/**
+ * RFC 6265 cookie-name grammar: a `token` as defined by RFC 9110.
+ *
+ * Separators (`()<>@,;:\"/[]?={}`), whitespace, and control characters are all
+ * excluded — several of them would otherwise let a name close the name/value
+ * pair early and inject an attribute.
+ */
+const COOKIE_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * RFC 6265 cookie-octet: US-ASCII excluding controls, whitespace, double
+ * 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.
+ */
+const COOKIE_VALUE_CONTROL_CHARS = /[\x00-\x1F\x7F]/;
 /**
  * Parses a raw cookie header string into individual cookies.
  *
@@ -42,8 +62,23 @@ export function parseCookieHeader(cookieHeader, config) {
         }
         const name = part.slice(0, eqIndex).trim();
         const value = part.slice(eqIndex + 1).trim();
-        if (name.length === 0) {
-            errors.push(`Cookie ${i}: empty cookie name`);
+        // The read path used to check length and nothing else, so a cookie whose
+        // name the package's own `validateCookieName` rejects — one carrying a
+        // separator, whitespace or a control character — still landed in
+        // `result.cookies` with `errors: []`. Names are unambiguous: RFC 6265
+        // defines them as a token, and anything else is malformed framing.
+        const nameError = validateCookieName(name);
+        if (nameError) {
+            errors.push(`Cookie ${i}: ${nameError}`);
+            continue;
+        }
+        // Values are deliberately checked less strictly than `validateCookieValue`
+        // does on the write path: real-world servers emit values containing
+        // spaces, commas and quoted-string wrappers, and rejecting those here
+        // would drop legitimate traffic. Control characters have no such excuse —
+        // a CR or LF in a value reflected back into a header splits the response.
+        if (COOKIE_VALUE_CONTROL_CHARS.test(value)) {
+            errors.push(`Cookie "${name}": value contains control characters`);
             continue;
         }
         if (Buffer.byteLength(value, "utf8") > maxSize) {
@@ -57,26 +92,64 @@ export function parseCookieHeader(cookieHeader, config) {
 /**
  * Serializes a parsed cookie into a Set-Cookie header value.
  *
+ * The name, value, and every attribute are validated before being written: a
+ * value carrying a CRLF would split the response, and one carrying a `;` would
+ * append attributes the caller never asked for. Values are percent-encoded by
+ * default so ordinary text (spaces, commas, non-ASCII) round-trips safely
+ * through {@link parseCookieHeader}.
+ *
  * @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.
  */
 export function serializeCookie(cookie, config) {
-    const parts = [`${cookie.name}=${cookie.value}`];
+    const nameError = validateCookieName(cookie.name);
+    if (nameError) {
+        throw new Error(`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.
+    const encodedValue = COOKIE_VALUE_PATTERN.test(cookie.value)
+        ? cookie.value
+        : encodeURIComponent(cookie.value);
+    const valueError = validateCookieValue(encodedValue);
+    if (valueError) {
+        throw new Error(`Cannot serialize cookie "${cookie.name}": ${valueError}`);
+    }
+    const parts = [`${cookie.name}=${encodedValue}`];
     if (cookie.path) {
+        assertSafeAttribute("Path", cookie.path);
         parts.push(`Path=${cookie.path}`);
     }
     if (cookie.domain) {
+        assertSafeAttribute("Domain", cookie.domain);
         parts.push(`Domain=${cookie.domain}`);
     }
     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}`);
+        }
         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`);
+        }
         parts.push(`Expires=${cookie.expires.toUTCString()}`);
     }
     // Apply security defaults from config
     const secure = cookie.secure ?? config?.secure ?? true;
+    const sameSite = cookie.sameSite ?? config?.sameSite ?? "lax";
+    // 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`);
+    }
+    // Partitioned (CHIPS) likewise requires Secure.
+    if (cookie.partitioned && !secure) {
+        throw new Error(`Cannot serialize cookie "${cookie.name}": Partitioned requires the Secure attribute`);
+    }
     if (secure) {
         parts.push("Secure");
     }
@@ -84,13 +157,18 @@ export function serializeCookie(cookie, config) {
     if (httpOnly) {
         parts.push("HttpOnly");
     }
-    const sameSite = cookie.sameSite ?? config?.sameSite ?? "lax";
     parts.push(`SameSite=${sameSite.charAt(0).toUpperCase() + sameSite.slice(1)}`);
     if (cookie.partitioned) {
         parts.push("Partitioned");
     }
     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 Error(`Cookie ${attribute} contains invalid characters (injection risk): ${JSON.stringify(value)}`);
+    }
+}
 /**
  * Creates a Set-Cookie header value with secure defaults.
  *
@@ -99,6 +177,7 @@ export function serializeCookie(cookie, config) {
  * @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.
  */
 export function createSecureCookie(name, value, options, config) {
     return serializeCookie({ name, value, ...options }, config);
@@ -116,8 +195,8 @@ export function validateCookieName(name) {
     if (name.length > 256) {
         return `Cookie name exceeds maximum length of 256: ${name.length}`;
     }
-    // RFC 6265: cookie name cannot contain certain characters
-    if (/[\s,;=]/.test(name)) {
+    // RFC 6265: cookie-name is a token — no separators, whitespace, or controls.
+    if (!COOKIE_NAME_PATTERN.test(name)) {
         return `Cookie name contains invalid characters: ${name}`;
     }
     return undefined;
@@ -133,15 +212,23 @@ export function validateCookieValue(value) {
     if (value.includes(";")) {
         return "Cookie value cannot contain semicolons";
     }
-    // Check for control characters
+    // Check for control characters, CR and LF included
     if (/[\x00-\x1F\x7F]/.test(value)) {
         return "Cookie value contains control characters";
     }
+    // Remaining cookie-octet exclusions: whitespace, quote, comma, backslash.
+    if (/[\s",\\]/.test(value)) {
+        return "Cookie value contains characters that must be percent-encoded";
+    }
     return 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`.
+ *
  * @param cookieHeader - The raw Cookie header.
  * @param sensitiveNames - Names of cookies to strip (case-insensitive).
  * @returns The cleaned cookie header.
@@ -156,7 +243,10 @@ export function stripSensitiveCookies(cookieHeader, sensitiveNames = ["session",
         if (eqIndex === -1)
             return false;
         const name = pair.slice(0, eqIndex).trim().toLowerCase();
-        return !lowerSensitive.includes(name);
+        return !lowerSensitive.some((sensitive) => name === sensitive ||
+            name.startsWith(`${sensitive}_`) ||
+            name.startsWith(`${sensitive}-`) ||
+            name.startsWith(`${sensitive}.`));
     })
         .join("; ");
 }

package/dist/cors/cors.core.d.ts

@@ -14,6 +14,7 @@ export interface CorsHeaders {
     "Access-Control-Expose-Headers"?: string;
     "Access-Control-Allow-Credentials"?: string;
     "Access-Control-Max-Age"?: string;
+    Vary?: string;
 }
 /**
  * Checks if a request origin is allowed.
@@ -28,9 +29,15 @@ export declare function isOriginAllowed(origin: string | undefined, config: Cors
  *
  * @param requestOrigin - The request Origin header.
  * @param config - CORS configuration.
+ * @param request - Optional preflight request details. When supplied, the
+ *   requested method and headers are validated and an unacceptable preflight
+ *   returns no CORS headers at all.
  * @returns CORS headers to set on the response.
  */
-export declare function generatePreflightHeaders(requestOrigin: string | undefined, config: CorsConfig): CorsHeaders;
+export declare function generatePreflightHeaders(requestOrigin: string | undefined, config: CorsConfig, request?: {
+    readonly method?: string;
+    readonly headers?: readonly string[];
+}): CorsHeaders;
 /**
  * Generates CORS headers for a simple request.
  *

package/dist/cors/cors.core.js

@@ -3,6 +3,7 @@
  *
  * Validates and generates CORS headers for cross-origin requests.
  */
+import { withoutStickyFlags } from "../input/input.core.js";
 /** Default CORS configuration (restrictive). */
 const DEFAULT_CORS_CONFIG = {
     origin: undefined,
@@ -12,6 +13,23 @@ const DEFAULT_CORS_CONFIG = {
     credentials: false,
     maxAge: 86400,
 };
+/**
+ * Rejects a configuration that pairs a wildcard origin with credentials.
+ *
+ * Browsers refuse the combination outright, so shipping it is not a leak so
+ * much as a policy that silently never works. Failing here turns a confusing
+ * runtime symptom into a startup error.
+ */
+function assertConfigCoherent(config) {
+    if (!config.credentials)
+        return;
+    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 ("*"). ' +
+            "Enumerate the allowed origins, or supply a function or RegExp.");
+    }
+}
 /**
  * Checks if a request origin is allowed.
  *
@@ -20,6 +38,7 @@ const DEFAULT_CORS_CONFIG = {
  * @returns The allowed origin value, or undefined if not allowed.
  */
 export function isOriginAllowed(origin, config) {
+    assertConfigCoherent(config);
     if (!origin) {
         return undefined;
     }
@@ -32,9 +51,10 @@ export function isOriginAllowed(origin, config) {
     if (typeof allowedOrigin === "function") {
         return allowedOrigin(origin) ? origin : undefined;
     }
-    // Regex check
+    // Regex check. A `g` or `y` flag would make `test` stateful via `lastIndex`,
+    // so the same origin would alternate between allowed and denied.
     if (allowedOrigin instanceof RegExp) {
-        return allowedOrigin.test(origin) ? origin : undefined;
+        return withoutStickyFlags(allowedOrigin).test(origin) ? origin : undefined;
     }
     // String check
     if (typeof allowedOrigin === "string") {
@@ -56,23 +76,57 @@ export function isOriginAllowed(origin, config) {
     }
     return undefined;
 }
+/**
+ * True when the allow-origin value depends on the request's Origin header.
+ *
+ * A reflected value must be accompanied by `Vary: Origin`, or a shared cache
+ * will hand one origin's response — and its `Access-Control-Allow-Origin` — to
+ * a different origin.
+ */
+function isReflected(config) {
+    const origin = config.origin;
+    if (origin === undefined)
+        return false;
+    if (origin === "*")
+        return false;
+    // A single literal string always produces the same header; everything else
+    // (array, RegExp, predicate) varies with the request.
+    return typeof origin !== "string";
+}
 /**
  * Generates CORS headers for a preflight request.
  *
  * @param requestOrigin - The request Origin header.
  * @param config - CORS configuration.
+ * @param request - Optional preflight request details. When supplied, the
+ *   requested method and headers are validated and an unacceptable preflight
+ *   returns no CORS headers at all.
  * @returns CORS headers to set on the response.
  */
-export function generatePreflightHeaders(requestOrigin, config) {
+export function generatePreflightHeaders(requestOrigin, config, request) {
     const headers = {};
-    const allowedOrigin = isOriginAllowed(requestOrigin, config);
-    if (allowedOrigin) {
-        headers["Access-Control-Allow-Origin"] = allowedOrigin;
+    // Vary is set even when the origin is rejected: the decision itself depends
+    // on the Origin header, so the negative response is equally uncacheable
+    // across origins.
+    if (isReflected(config)) {
+        headers.Vary = "Origin";
     }
-    else {
+    const allowedOrigin = isOriginAllowed(requestOrigin, config);
+    if (!allowedOrigin) {
         // No matching origin — don't set CORS headers
         return headers;
     }
+    // Reject the preflight outright when it asks for something not permitted,
+    // rather than answering with a policy the browser will then enforce against.
+    if (request?.method !== undefined &&
+        !isMethodAllowed(request.method, config)) {
+        return headers;
+    }
+    if (request?.headers !== undefined &&
+        getDisallowedHeaders([...request.headers], config).length > 0) {
+        return headers;
+    }
+    headers["Access-Control-Allow-Origin"] = allowedOrigin;
     const methods = config.methods ?? DEFAULT_CORS_CONFIG.methods;
     headers["Access-Control-Allow-Methods"] = methods.join(", ");
     const allowedHeaders = config.allowedHeaders ?? DEFAULT_CORS_CONFIG.allowedHeaders;
@@ -93,6 +147,9 @@ export function generatePreflightHeaders(requestOrigin, config) {
  */
 export function generateSimpleHeaders(requestOrigin, config) {
     const headers = {};
+    if (isReflected(config)) {
+        headers.Vary = "Origin";
+    }
     const allowedOrigin = isOriginAllowed(requestOrigin, config);
     if (allowedOrigin) {
         headers["Access-Control-Allow-Origin"] = allowedOrigin;
@@ -115,7 +172,7 @@ export function generateSimpleHeaders(requestOrigin, config) {
  */
 export function isMethodAllowed(method, config) {
     const allowedMethods = config.methods ?? DEFAULT_CORS_CONFIG.methods;
-    return allowedMethods.includes(method.toUpperCase());
+    return allowedMethods.some((allowed) => allowed.toUpperCase() === method.toUpperCase());
 }
 /**
  * Validates that all requested headers are allowed.
@@ -126,6 +183,6 @@ export function isMethodAllowed(method, config) {
  */
 export function getDisallowedHeaders(headers, config) {
     const allowedHeaders = new Set((config.allowedHeaders ?? DEFAULT_CORS_CONFIG.allowedHeaders).map((h) => h.toLowerCase()));
-    return headers.filter((h) => !allowedHeaders.has(h.toLowerCase()));
+    return headers.filter((h) => !allowedHeaders.has(h.trim().toLowerCase()));
 }
 //# sourceMappingURL=cors.core.js.map

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

@@ -2,25 +2,78 @@
  * @zudojs/security — CSRF Protection
  *
  * Generates and validates CSRF tokens for state-changing requests.
+ *
+ * Two patterns are supported, both built on the same signed token:
+ *
+ * - **Synchroniser token** (recommended). The server stores the token in an
+ *   `HttpOnly` cookie via {@link generateCsrfCookie} and renders the same
+ *   token into the page or form. The browser returns it in a header or field,
+ *   and {@link verifyDoubleSubmit} compares the two. Script on the page never
+ *   needs to read the cookie, so `HttpOnly` stays on.
+ * - **Double-submit cookie.** Client-side script reads the cookie and echoes
+ *   it into a header. This requires `httpOnly: false` on the cookie — pass it
+ *   explicitly, and understand that any XSS on the origin can then read the
+ *   token.
+ *
+ * Bind the token to a session wherever you have one: without `sessionId`, a
+ * token minted for one user validates for every other user.
  */
 import type { CsrfConfig } from "../types/security.type.js";
+/**
+ * Minimum accepted secret length, in characters.
+ *
+ * The signature is HMAC-SHA256, so a secret shorter than the 32-byte output
+ * adds no strength beyond its own length. `"CSRF secret cannot be empty"` was
+ * the only check, which accepted a one-character secret in silence.
+ */
+export declare const MIN_CSRF_SECRET_LENGTH = 32;
+/** Options accepted by token generation and validation. */
+export interface CsrfTokenOptions {
+    /** Token lifetime in seconds (default: 3600). */
+    readonly expiration?: number;
+    /**
+     * Session identifier to bind the token to.
+     *
+     * Strongly recommended: an unbound token is valid for every user, so an
+     * attacker can mint one with their own session and replay it against a
+     * victim's.
+     */
+    readonly sessionId?: string;
+}
 /**
  * Generates a cryptographically secure CSRF token.
  *
  * @param secret - The secret key for HMAC generation.
- * @param expiration - Optional expiration in seconds (default: 3600).
- * @returns The CSRF token string.
+ * @param options - Expiration and session binding, or a bare expiration in
+ *   seconds for backwards compatibility.
+ * @returns The CSRF token string, in the form `expiresAt:random:signature`.
  */
-export declare function generateCsrfToken(secret: string, expiration?: number): string;
+export declare function generateCsrfToken(secret: string, options?: number | CsrfTokenOptions): string;
 /**
  * Validates a CSRF token.
  *
  * @param token - The CSRF token to validate.
  * @param secret - The secret key for verification.
- * @param expiration - Optional expiration in seconds (default: 3600).
- * @returns True if the token is valid and not expired.
+ * @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.
+ */
+export declare function validateCsrfToken(token: string, secret: string, options?: number | CsrfTokenOptions): boolean;
+/**
+ * Verifies a state-changing request under the double-submit / synchroniser
+ * token pattern.
+ *
+ * Both tokens must be present, identical, and individually valid. Comparing
+ * the two alone is not enough — an attacker who can set a cookie on the origin
+ * could otherwise supply a matching pair of their own.
+ *
+ * @param cookieToken - Token taken from the CSRF cookie.
+ * @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.
  */
-export declare function validateCsrfToken(token: string, secret: string, expiration?: number): boolean;
+export declare function verifyDoubleSubmit(cookieToken: string | undefined, requestToken: string | undefined, secret: string, options?: number | CsrfTokenOptions): boolean;
 /**
  * Checks if a request method requires CSRF protection.
  *
@@ -32,6 +85,9 @@ export declare function requiresCsrfProtection(method: string, config?: CsrfConf
 /**
  * Extracts the CSRF token from request headers.
  *
+ * Lookup is case-insensitive: HTTP header names are, and a raw header bag is
+ * not guaranteed to arrive lowercased.
+ *
  * @param headers - Request headers.
  * @param headerName - The header name to look for.
  * @returns The CSRF token, or undefined.
@@ -46,11 +102,96 @@ export declare function extractCsrfTokenFromHeaders(headers: Record<string, stri
  */
 export declare function extractCsrfTokenFromCookies(cookieHeader: string, cookieName?: string): string | undefined;
 /**
- * Generates Set-Cookie header for CSRF token.
+ * Options for the CSRF cookie.
+ *
+ * `secret` is deliberately omitted: this function never reads one, and
+ * inheriting the whole of {@link CsrfConfig} made a *required* secret part of
+ * the declared shape of a call that has no use for it.
+ */
+export interface CsrfCookieOptions extends Omit<CsrfConfig, "secret"> {
+    /**
+     * Whether to set `HttpOnly` (default: true).
+     *
+     * Keep it on for the synchroniser-token pattern, where the server renders
+     * the token into the page. Set it to `false` only for the double-submit
+     * pattern, where client script must read the cookie back.
+     */
+    readonly httpOnly?: boolean;
+    /**
+     * Whether to set `Secure` (default: true).
+     *
+     * Only turn this off for local development over plain HTTP. Without it the
+     * token is readable by anyone on the network path.
+     */
+    readonly secure?: boolean;
+    /** Cookie path (default: "/"). */
+    readonly path?: string;
+}
+/**
+ * Generates a Set-Cookie header for a CSRF token.
  *
  * @param token - The CSRF token to store.
- * @param config - Optional CSRF configuration.
+ * @param config - Optional CSRF and cookie configuration.
  * @returns The Set-Cookie header value.
  */
-export declare function generateCsrfCookie(token: string, config?: CsrfConfig): string;
+export declare function generateCsrfCookie(token: string, config?: Partial<CsrfCookieOptions>): string;
+/** Cookie-shaping options for {@link createCsrfProtection}. */
+export interface CsrfProtectionOptions extends CsrfConfig {
+    /** Whether to set `HttpOnly` on the cookie (default: true). */
+    readonly httpOnly?: boolean;
+    /** Whether to set `Secure` on the cookie (default: true). */
+    readonly secure?: boolean;
+    /** Cookie path (default: "/"). */
+    readonly path?: string;
+}
+/** A CSRF token together with the `Set-Cookie` header that carries it. */
+export interface IssuedCsrfToken {
+    /** The token to render into the page or return to the client. */
+    readonly token: string;
+    /** The `Set-Cookie` header value. */
+    readonly setCookie: string;
+}
+/** The request fields {@link CsrfProtection.verify} needs. */
+export interface CsrfVerifiableRequest {
+    readonly method: string;
+    readonly headers?: Record<string, string | string[] | undefined>;
+    /** The raw `Cookie` header value. */
+    readonly cookieHeader?: string;
+}
+/** CSRF protection bound to one configuration. */
+export interface CsrfProtection {
+    /** Mint a token and the cookie that carries it. */
+    issue(options?: {
+        readonly sessionId?: string;
+    }): IssuedCsrfToken;
+    /**
+     * Verify a request under the double-submit pattern.
+     *
+     * Returns `true` for a method that does not require protection, so it can be
+     * called unconditionally.
+     */
+    verify(request: CsrfVerifiableRequest, options?: {
+        readonly sessionId?: string;
+    }): boolean;
+    /** Whether this method requires protection under the configured methods. */
+    requiresProtection(method: string): boolean;
+}
+/**
+ * Binds a {@link CsrfConfig} to the CSRF primitives.
+ *
+ * Every field of `CsrfConfig` was previously inert. `secret` — the one
+ * *required* field — was never read by anything: each function took the secret
+ * as a positional argument instead. `headerName` was likewise never read, so a
+ * caller who configured it still had `x-csrf-token` looked up. Reaching the
+ * configured names meant passing them again, by hand, at four separate call
+ * sites.
+ *
+ * This composes the existing functions; it introduces no new token format.
+ *
+ * @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
+ *   {@link MIN_CSRF_SECRET_LENGTH}.
+ */
+export declare function createCsrfProtection(config: CsrfProtectionOptions): CsrfProtection;
 //# sourceMappingURL=csrf.core.d.ts.map