@zudojs/security 0.1.0 → 1.0.0

package/dist/csrf/csrf.core.js

@@ -2,8 +2,23 @@
  * @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 { createHash, randomBytes } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 /** Default token expiration (1 hour). */
 const DEFAULT_EXPIRATION = 3600;
 /** Default cookie name for CSRF token. */
@@ -14,34 +29,82 @@ const DEFAULT_HEADER_NAME = "x-csrf-token";
 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.
+ *
+ * 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 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 " +
+            `${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 ` +
+            `${MIN_CSRF_SECRET_LENGTH}. The signature is HMAC-SHA256, so a shorter ` +
+            'secret adds no strength. Generate one with randomBytes(32).toString("hex").');
+    }
+}
+/**
+ * Computes the token signature.
+ *
+ * HMAC-SHA256 rather than `sha256(payload + secret)`: the plain-hash form is a
+ * secret-suffix construction with no security proof, and truncating it to 64
+ * bits leaves far too little margin.
+ */
+function sign(secret, expiresAt, random, sessionId) {
+    return createHmac("sha256", secret)
+        .update(`${expiresAt}:${random}:${sessionId}`)
+        .digest("hex");
+}
+/** Constant-time string comparison that does not leak length via early exit. */
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length) {
+        // Still burn a comparison so the timing profile does not distinguish a
+        // length mismatch from a content mismatch.
+        timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
 /**
  * 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 function generateCsrfToken(secret, expiration) {
-    const ttl = expiration ?? DEFAULT_EXPIRATION;
+export function generateCsrfToken(secret, options) {
+    assertUsableSecret(secret);
+    const opts = typeof options === "number" ? { expiration: options } : (options ?? {});
+    const ttl = opts.expiration ?? DEFAULT_EXPIRATION;
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+        throw new RangeError(`CSRF expiration must be positive, got: ${ttl}`);
+    }
     const expiresAt = Math.floor(Date.now() / 1000) + ttl;
     const random = randomBytes(16).toString("hex");
-    const payload = `${expiresAt}:${random}`;
-    const signature = createHash("sha256")
-        .update(`${payload}:${secret}`)
-        .digest("hex")
-        .slice(0, 16);
-    return `${payload}:${signature}`;
+    const signature = sign(secret, expiresAt, random, opts.sessionId ?? "");
+    return `${expiresAt}:${random}:${signature}`;
 }
 /**
  * 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 function validateCsrfToken(token, secret, expiration) {
-    const ttl = expiration ?? DEFAULT_EXPIRATION;
+export function validateCsrfToken(token, secret, options) {
+    const opts = typeof options === "number" ? { expiration: options } : (options ?? {});
+    const maxTtl = opts.expiration ?? DEFAULT_EXPIRATION;
     const parts = token.split(":");
     if (parts.length !== 3) {
         return false;
@@ -50,30 +113,50 @@ export function validateCsrfToken(token, secret, expiration) {
     if (!expiresAtStr || !random || !providedSignature) {
         return false;
     }
-    const expiresAt = parseInt(expiresAtStr, 10);
-    if (isNaN(expiresAt)) {
+    if (!/^\d+$/.test(expiresAtStr)) {
+        return false;
+    }
+    const expiresAt = Number(expiresAtStr);
+    if (!Number.isSafeInteger(expiresAt)) {
         return false;
     }
-    // Check expiration
     const now = Math.floor(Date.now() / 1000);
+    // Expired.
     if (now > expiresAt) {
         return false;
     }
-    // Verify signature
-    const payload = `${expiresAt}:${random}`;
-    const expectedSignature = createHash("sha256")
-        .update(`${payload}:${secret}`)
-        .digest("hex")
-        .slice(0, 16);
-    // Constant-time comparison
-    if (providedSignature.length !== expectedSignature.length) {
+    // Issued with a longer lifetime than this caller is willing to honour. The
+    // expiry is inside the signed payload, so it cannot be forged — but a token
+    // minted with a ten-year TTL should not be accepted by a route that expects
+    // one hour.
+    if (expiresAt - now > maxTtl) {
         return false;
     }
-    let result = 0;
-    for (let i = 0; i < providedSignature.length; i++) {
-        result |= providedSignature.charCodeAt(i) ^ expectedSignature.charCodeAt(i);
+    const expectedSignature = sign(secret, expiresAt, random, opts.sessionId ?? "");
+    return safeEqual(providedSignature, expectedSignature);
+}
+/**
+ * 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 function verifyDoubleSubmit(cookieToken, requestToken, secret, options) {
+    if (!cookieToken || !requestToken) {
+        return false;
+    }
+    if (!safeEqual(cookieToken, requestToken)) {
+        return false;
     }
-    return result === 0;
+    return validateCsrfToken(cookieToken, secret, options);
 }
 /**
  * Checks if a request method requires CSRF protection.
@@ -92,13 +175,22 @@ export function requiresCsrfProtection(method, config) {
 /**
  * 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.
  */
 export function extractCsrfTokenFromHeaders(headers, headerName) {
-    const name = headerName ?? DEFAULT_HEADER_NAME;
-    const value = headers[name];
+    const name = (headerName ?? DEFAULT_HEADER_NAME).toLowerCase();
+    let value;
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === name) {
+            value = headers[key];
+            break;
+        }
+    }
     if (typeof value === "string") {
         return value;
     }
@@ -129,21 +221,87 @@ export function extractCsrfTokenFromCookies(cookieHeader, cookieName) {
     return cookie?.value || undefined;
 }
 /**
- * Generates Set-Cookie header for CSRF token.
+ * 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 function generateCsrfCookie(token, config) {
     const name = config?.cookieName ?? DEFAULT_COOKIE_NAME;
     const ttl = config?.expiration ?? DEFAULT_EXPIRATION;
-    return [
-        `${name}=${token}`,
-        "Path=/",
-        "HttpOnly",
-        "SameSite=Strict",
-        `Max-Age=${ttl}`,
-    ].join("; ");
+    const httpOnly = config?.httpOnly ?? true;
+    const secure = config?.secure ?? true;
+    const path = config?.path ?? "/";
+    const parts = [`${name}=${token}`, `Path=${path}`];
+    if (httpOnly) {
+        parts.push("HttpOnly");
+    }
+    if (secure) {
+        parts.push("Secure");
+    }
+    parts.push("SameSite=Strict", `Max-Age=${ttl}`);
+    return parts.join("; ");
+}
+/**
+ * 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 function createCsrfProtection(config) {
+    assertUsableSecret(config.secret);
+    const expiration = config.expiration ?? DEFAULT_EXPIRATION;
+    const cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+    const headerName = config.headerName ?? DEFAULT_HEADER_NAME;
+    return {
+        issue(options) {
+            const token = generateCsrfToken(config.secret, {
+                expiration,
+                ...(options?.sessionId !== undefined
+                    ? { sessionId: options.sessionId }
+                    : {}),
+            });
+            return {
+                token,
+                setCookie: generateCsrfCookie(token, {
+                    cookieName,
+                    expiration,
+                    ...(config.httpOnly !== undefined
+                        ? { httpOnly: config.httpOnly }
+                        : {}),
+                    ...(config.secure !== undefined ? { secure: config.secure } : {}),
+                    ...(config.path !== undefined ? { path: config.path } : {}),
+                }),
+            };
+        },
+        verify(request, options) {
+            if (!requiresCsrfProtection(request.method, config)) {
+                return true;
+            }
+            const cookieToken = extractCsrfTokenFromCookies(request.cookieHeader ?? "", cookieName);
+            const requestToken = extractCsrfTokenFromHeaders(request.headers ?? {}, headerName);
+            return verifyDoubleSubmit(cookieToken, requestToken, config.secret, {
+                expiration,
+                ...(options?.sessionId !== undefined
+                    ? { sessionId: options.sessionId }
+                    : {}),
+            });
+        },
+        requiresProtection(method) {
+            return requiresCsrfProtection(method, config);
+        },
+    };
 }
 //# sourceMappingURL=csrf.core.js.map

package/dist/csrf/index.d.ts

@@ -1,5 +1,6 @@
 /**
  * @zudojs/security — CSRF Protection Barrel
  */
-export { generateCsrfToken, validateCsrfToken, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, } from "./csrf.core.js";
+export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf.core.js";
+export type { CsrfTokenOptions, CsrfCookieOptions, CsrfProtection, CsrfProtectionOptions, IssuedCsrfToken, CsrfVerifiableRequest, } from "./csrf.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/csrf/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — CSRF Protection Barrel
  */
-export { generateCsrfToken, validateCsrfToken, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, } from "./csrf.core.js";
+export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf.core.js";
 //# sourceMappingURL=index.js.map

package/dist/header/header.core.js

@@ -22,9 +22,14 @@ const DEFAULT_BLOCKED_HEADERS = [
  */
 const CRLF_PATTERN = /[\r\n]/;
 /**
- * Null byte pattern.
+ * Null byte patterns.
+ *
+ * The plain form is for {@link RegExp.test}; the `g` form is for
+ * {@link String.replace}, which without the flag would strip only the first
+ * occurrence.
  */
 const NULL_BYTE_PATTERN = /\x00/;
+const NULL_BYTE_PATTERN_GLOBAL = /\x00/g;
 /**
  * Validates a single header name.
  *
@@ -101,16 +106,23 @@ export function validateHeaders(headers, config) {
             errors.push(nameError);
             continue;
         }
+        if (config?.blockHopByHop === true && isHopByHopHeader(name)) {
+            errors.push(`Header "${name}" is hop-by-hop and must not be forwarded (RFC 9110 s7.6.1)`);
+            continue;
+        }
         // Validate values (may be array for Set-Cookie, etc.)
         const values = Array.isArray(value) ? value : [value];
         for (const v of values) {
+            // Size is accumulated whether or not the value is otherwise valid.
+            // Skipping invalid values under-counted exactly the headers most likely
+            // to breach `maxTotalSize`, so an oversized header could evade the total
+            // bound by also being malformed.
+            totalSize +=
+                Buffer.byteLength(name, "utf8") + Buffer.byteLength(v, "utf8");
             const valueError = validateHeaderValue(name, v, config);
             if (valueError) {
                 errors.push(valueError);
-                continue;
             }
-            totalSize +=
-                Buffer.byteLength(name, "utf8") + Buffer.byteLength(v, "utf8");
         }
     }
     // Check total size
@@ -131,7 +143,7 @@ export function validateHeaders(headers, config) {
  */
 export function sanitizeHeaderValue(value) {
     // Strip null bytes
-    let sanitized = value.replace(NULL_BYTE_PATTERN, "");
+    let sanitized = value.replace(NULL_BYTE_PATTERN_GLOBAL, "");
     // Strip CRLF (strip both \r and \n)
     sanitized = sanitized.replace(/[\r\n]/g, "");
     return sanitized.length > 0 ? sanitized : undefined;
@@ -148,6 +160,7 @@ export function isHopByHopHeader(name) {
         "keep-alive",
         "proxy-authenticate",
         "proxy-authorization",
+        "proxy-connection",
         "te",
         "trailer",
         "transfer-encoding",

package/dist/headers/headers.core.js

@@ -3,6 +3,7 @@
  *
  * Generates security-related HTTP response headers with secure defaults.
  */
+import { randomBytes } from "node:crypto";
 /** Security header names. */
 export const SECURITY_HEADER_NAMES = {
     CONTENT_SECURITY_POLICY: "Content-Security-Policy",
@@ -16,15 +17,33 @@ export const SECURITY_HEADER_NAMES = {
     OPENER_POLICY: "Cross-Origin-Opener-Policy",
     RESOURCE_POLICY: "Cross-Origin-Resource-Policy",
 };
+/**
+ * Default Content-Security-Policy.
+ *
+ * Deliberately restrictive: no scripts, styles, or frames from anywhere, and
+ * no plugin content. An app that serves a UI must replace this — the point of
+ * the default is that a service which forgets to set one is still locked down.
+ */
+const DEFAULT_CSP = "default-src 'self'; script-src 'self'; style-src 'self'; " +
+    "img-src 'self' data:; object-src 'none'; frame-ancestors 'none'; " +
+    "base-uri 'self'; form-action 'self'";
+/** Default HSTS: two years, all subdomains, preload-eligible. */
+const DEFAULT_HSTS = "max-age=63072000; includeSubDomains; preload";
+/** Default Permissions-Policy: deny the high-risk capabilities. */
+const DEFAULT_PERMISSIONS_POLICY = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), " +
+    "magnetometer=(), microphone=(), payment=(), usb=()";
 /** Default security headers. */
 const DEFAULT_HEADERS = {
     [SECURITY_HEADER_NAMES.CONTENT_TYPE_OPTIONS]: "nosniff",
     [SECURITY_HEADER_NAMES.FRAME_OPTIONS]: "DENY",
-    [SECURITY_HEADER_NAMES.XSS_PROTECTION]: "1; mode=block",
+    [SECURITY_HEADER_NAMES.XSS_PROTECTION]: "0",
     [SECURITY_HEADER_NAMES.REFERRER_POLICY]: "strict-origin-when-cross-origin",
     [SECURITY_HEADER_NAMES.DNS_PREFETCH_CONTROL]: "off",
     [SECURITY_HEADER_NAMES.OPENER_POLICY]: "same-origin",
     [SECURITY_HEADER_NAMES.RESOURCE_POLICY]: "same-origin",
+    [SECURITY_HEADER_NAMES.CONTENT_SECURITY_POLICY]: DEFAULT_CSP,
+    [SECURITY_HEADER_NAMES.HSTS]: DEFAULT_HSTS,
+    [SECURITY_HEADER_NAMES.PERMISSIONS_POLICY]: DEFAULT_PERMISSIONS_POLICY,
 };
 /**
  * Generates security headers with secure defaults.
@@ -34,6 +53,15 @@ const DEFAULT_HEADERS = {
  */
 export function generateSecurityHeaders(config) {
     const headers = { ...DEFAULT_HEADERS };
+    // Config values end up verbatim in a response header, so a stray CRLF here
+    // would split the response exactly as an attacker-supplied one would.
+    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)`);
+            }
+        }
+    }
     if (config?.contentSecurityPolicy) {
         headers[SECURITY_HEADER_NAMES.CONTENT_SECURITY_POLICY] =
             config.contentSecurityPolicy;
@@ -93,8 +121,10 @@ export function getMissingSecurityHeaders(headers) {
  * @returns The base64-encoded nonce.
  */
 export function generateCspNonce(nonceLength) {
-    const { randomBytes } = require("node:crypto");
     const length = nonceLength ?? 16;
+    if (!Number.isInteger(length) || length < 16) {
+        throw new RangeError(`CSP nonce length must be an integer of at least 16 bytes, got: ${length}`);
+    }
     return randomBytes(length).toString("base64");
 }
 /**
@@ -118,7 +148,9 @@ export function validateCspDirective(directive) {
     if (directive.includes("'unsafe-hashes'")) {
         warnings.push("unsafe-hashes weakens CSP");
     }
-    // Return first warning as info (not error)
-    return warnings.length > 0 ? warnings[0] : undefined;
+    // Every warning, not just the first. A policy carrying all three used to
+    // report only `unsafe-inline`, so fixing that one made the function fall
+    // silent while `unsafe-eval` and `unsafe-hashes` were still in place.
+    return warnings.length > 0 ? warnings.join("; ") : undefined;
 }
 //# sourceMappingURL=headers.core.js.map

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  *
  * @example
  * ```ts
- * import { validateHeaders, validateUrl, generateSecurityHeaders } from '@zudojs/security';
+ * import { validateHeaders, validateRequestTarget, generateSecurityHeaders } from '@zudojs/security';
  *
  * // Validate request headers
  * const result = validateHeaders(request.headers);
@@ -17,8 +17,10 @@
  *   throw new Error(result.errors.join(', '));
  * }
  *
- * // Validate URL
- * const urlResult = validateUrl(request.url);
+ * // Validate the request target. Node's `request.url` is origin-form
+ * // ("/users?page=1"), which has no scheme — `validateUrl` needs an absolute
+ * // URL and reports every such target as malformed.
+ * const targetResult = validateRequestTarget(request.url);
  *
  * // Add security headers
  * const headers = generateSecurityHeaders();
@@ -26,19 +28,22 @@
  *
  * @packageDocumentation
  */
-export type { HeaderSecurityConfig, HeaderValidationResult, BodyLimitConfig, BodyLimitPresets, UrlValidationConfig, UrlValidationResult, CookieSecurityConfig, ParsedCookie, CorsConfig, CsrfConfig, RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult, SecurityHeadersConfig, RequestValidationConfig, InputSanitizationConfig, } from "./types/security.type.js";
+export type { HeaderSecurityConfig, HeaderValidationResult, BodyLimitConfig, BodyLimitPresets, UrlValidationConfig, UrlValidationResult, CookieSecurityConfig, ParsedCookie, CorsConfig, CsrfConfig, RateLimitConfig, RateLimitRequest, RateLimitResponse, RateLimitResult, SecurityHeadersConfig, InputSanitizationConfig, } from "./types/security.type.js";
 export { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from "./types/security.type.js";
 export { validateHeaderName, validateHeaderValue, validateHeaders, sanitizeHeaderValue, isHopByHopHeader, } from "./header/index.js";
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, } from "./url/index.js";
-export { DEFAULT_BODY_LIMITS, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, createBodySizeChecker, } from "./body/index.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url/index.js";
+export type { RequestTargetConfig } from "./url/index.js";
+export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body/index.js";
 export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie/index.js";
 export type { CorsHeaders } from "./cors/index.js";
 export { isOriginAllowed, generatePreflightHeaders, generateSimpleHeaders, isMethodAllowed, getDisallowedHeaders, } from "./cors/index.js";
 export { cors } from "./cors/cors.namespace.js";
-export { generateCsrfToken, validateCsrfToken, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, } from "./csrf/index.js";
-export { defaultKeyGenerator, defaultHandler, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
+export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf/index.js";
+export type { CsrfTokenOptions, CsrfCookieOptions, CsrfProtection, CsrfProtectionOptions, IssuedCsrfToken, CsrfVerifiableRequest, } from "./csrf/index.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
+export type { RateLimiterOptions, ClientIpOptions } from "./rateLimit/index.js";
 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, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -9,7 +9,7 @@
  *
  * @example
  * ```ts
- * import { validateHeaders, validateUrl, generateSecurityHeaders } from '@zudojs/security';
+ * import { validateHeaders, validateRequestTarget, generateSecurityHeaders } from '@zudojs/security';
  *
  * // Validate request headers
  * const result = validateHeaders(request.headers);
@@ -17,8 +17,10 @@
  *   throw new Error(result.errors.join(', '));
  * }
  *
- * // Validate URL
- * const urlResult = validateUrl(request.url);
+ * // Validate the request target. Node's `request.url` is origin-form
+ * // ("/users?page=1"), which has no scheme — `validateUrl` needs an absolute
+ * // URL and reports every such target as malformed.
+ * const targetResult = validateRequestTarget(request.url);
  *
  * // Add security headers
  * const headers = generateSecurityHeaders();
@@ -30,21 +32,21 @@ export { PROTOTYPE_POLLUTION_KEYS, SQL_INJECTION_PATTERNS, XSS_PATTERNS, } from
 /* ─── Header Security ────────────────────────────────────────────────────── */
 export { validateHeaderName, validateHeaderValue, validateHeaders, sanitizeHeaderValue, isHopByHopHeader, } from "./header/index.js";
 /* ─── URL Validation ─────────────────────────────────────────────────────── */
-export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, } from "./url/index.js";
+export { validateUrl, normalizePath, validateRequestTarget, isSafeUrl, isPrivateHostname, containsTraversal, fullyDecodeUri, } from "./url/index.js";
 /* ─── Body Validation ────────────────────────────────────────────────────── */
-export { DEFAULT_BODY_LIMITS, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, createBodySizeChecker, } from "./body/index.js";
+export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body/index.js";
 /* ─── Cookie Security ────────────────────────────────────────────────────── */
 export { parseCookieHeader, serializeCookie, createSecureCookie, validateCookieName, validateCookieValue, stripSensitiveCookies, } from "./cookie/index.js";
 export { isOriginAllowed, generatePreflightHeaders, generateSimpleHeaders, isMethodAllowed, getDisallowedHeaders, } from "./cors/index.js";
 export { cors } from "./cors/cors.namespace.js";
 /* ─── CSRF ───────────────────────────────────────────────────────────────── */
-export { generateCsrfToken, validateCsrfToken, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, } from "./csrf/index.js";
+export { generateCsrfToken, validateCsrfToken, verifyDoubleSubmit, requiresCsrfProtection, extractCsrfTokenFromHeaders, extractCsrfTokenFromCookies, generateCsrfCookie, createCsrfProtection, MIN_CSRF_SECRET_LENGTH, } from "./csrf/index.js";
 /* ─── Rate Limiting ──────────────────────────────────────────────────────── */
-export { defaultKeyGenerator, defaultHandler, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
+export { defaultKeyGenerator, defaultHandler, retryAfterSeconds, createRateLimiter, extractClientIp, } from "./rateLimit/index.js";
 export { rateLimit } from "./rateLimit/rateLimit.namespace.js";
 /* ─── Security Headers ───────────────────────────────────────────────────── */
 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, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input/index.js";
 //# sourceMappingURL=index.js.map

package/dist/input/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — Input Sanitization Barrel
  */
-export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/input/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — Input Sanitization Barrel
  */
-export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
+export { containsSqlInjection, containsXss, containsPrototypePollution, sanitizeString, sanitizeObject, isSafeString, withoutStickyFlags, detectThreats, escapeHtml, stripHtml, } from "./input.core.js";
 //# sourceMappingURL=index.js.map

package/dist/input/input.core.d.ts

@@ -7,6 +7,9 @@ import type { InputSanitizationConfig } from "../types/security.type.js";
 /**
  * Checks if a string contains SQL injection patterns.
  *
+ * A heuristic with a high false-positive rate on ordinary prose — never the
+ * only defence against injection. Parameterise your queries.
+ *
  * @param input - The string to check.
  * @returns True if SQL injection patterns are detected.
  */
@@ -36,6 +39,10 @@ export declare function sanitizeString(input: string, config?: InputSanitization
 /**
  * Sanitizes an object by recursively cleaning its values.
  *
+ * Cycles and over-deep structures are handled: a repeated reference or a
+ * branch past `config.maxDepth` (default 32) becomes `undefined` instead of
+ * exhausting the stack.
+ *
  * @param obj - The object to sanitize.
  * @param config - Optional sanitization configuration.
  * @returns The sanitized object.
@@ -49,6 +56,13 @@ export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T
  * @returns True if the string is safe.
  */
 export declare function isSafeString(input: string, allowedPattern?: RegExp): boolean;
+/**
+ * Returns an equivalent regex with the `g` and `y` flags removed.
+ *
+ * Both flags make `test` stateful via `lastIndex`; for a one-shot boolean
+ * check they only introduce order-dependent results.
+ */
+export declare function withoutStickyFlags(pattern: RegExp): RegExp;
 /**
  * Checks for common attack patterns in a string.
  *
@@ -59,6 +73,11 @@ export declare function detectThreats(input: string): string[];
 /**
  * HTML-escapes a string to prevent XSS.
  *
+ * Escapes the five characters that matter in element text and quoted attribute
+ * values. It does not make a string safe for an unquoted attribute, inside a
+ * `<script>` or `<style>` block, or in a URL position — those contexts need
+ * their own encoding.
+ *
  * @param input - The string to escape.
  * @returns The escaped string.
  */
@@ -66,6 +85,14 @@ export declare function escapeHtml(input: string): string;
 /**
  * Strips HTML tags from a string.
  *
+ * This removes tag syntax; it is **not** an HTML sanitizer. The result is safe
+ * to treat as plain text, but must still be escaped with {@link escapeHtml}
+ * before being inserted back into a document — use a dedicated sanitizer if
+ * you need to keep markup.
+ *
+ * An unterminated `<` consumes the remainder of the input, which is the safe
+ * direction: a truncated tag never survives into the output.
+ *
  * @param input - The string to strip.
  * @returns The string with HTML tags removed.
  */