@zudojs/security 0.0.1 → 1.0.0

package/README.md

@@ -10,24 +10,267 @@ npm install @zudojs/security
 
 ## Quick Start
 
+These are **functions, not middleware**. They compute answers and header values;
+wiring them into a request pipeline is the caller's job, which keeps the package
+framework-agnostic.
+
+```typescript
+import {
+  createRateLimiter,
+  extractClientIp,
+  retryAfterSeconds,
+  generateSimpleHeaders,
+  generateSecurityHeaders,
+} from "@zudojs/security";
+
+const limiter = createRateLimiter({ windowMs: 60_000, max: 100 });
+
+function handle(request, response) {
+  // Forwarding headers are only trusted when you say how many proxies you run.
+  const ip = extractClientIp(request.headers, {
+    trustProxy: 1,
+    remoteAddress: request.socket.remoteAddress,
+  });
+
+  const limit = limiter.check({ ip });
+  if (!limit.allowed) {
+    // `resetAt` is a Date; `Retry-After` is a whole number of seconds.
+    return respond(429, { retryAfter: retryAfterSeconds(limit) });
+  }
+
+  const headers = {
+    ...generateSecurityHeaders(),
+    ...generateSimpleHeaders(request.headers.origin, {
+      origin: ["https://example.com"],
+      credentials: true,
+    }),
+  };
+
+  return respond(200, body, headers);
+}
+```
+
+## Rate limiting
+
+A genuine sliding window: each check prunes entries older than `windowMs` and
+decides against what remains, so a client cannot spend a full allowance either
+side of a fixed boundary. Only allowed requests consume an allowance slot, so a
+client being limited cannot grow its own bucket.
+
+```typescript
+const limiter = createRateLimiter({
+  windowMs: 60_000,
+  max: 100,
+  maxKeys: 100_000, // LRU-evicted ceiling on tracked keys
+});
+
+const ip = "203.0.113.7";
+
+limiter.check({ ip }); // { allowed, remaining, resetAt: Date, total }
+limiter.getCount(ip);
+limiter.reset(ip);
+limiter.destroy(); // clears the cleanup timer
+```
+
+`middleware` fills a response for you, and the default handler now derives
+`Retry-After` from the decision rather than emitting a fixed `60`. It also
+honours `message`:
+
+```typescript
+const limiter = createRateLimiter({
+  windowMs: 3_600_000,
+  max: 10,
+  message: "Hourly quota exhausted.",
+});
+
+const response = { statusCode: 200, headers: {} as Record<string, string> };
+const result = limiter.middleware({ ip }, response);
+// response.headers["Retry-After"]  → seconds until the window frees up
+// response.headers["X-RateLimit-Limit"], ["X-RateLimit-Remaining"], ["X-RateLimit-Reset"]
+// response.body                    → { error: { code, message: "Hourly quota exhausted." } }
+```
+
+A custom `handler` receives the same decision as a third argument, so it can do
+the arithmetic too. Two-parameter handlers written against the previous
+signature still work.
+
+**`extractClientIp` does not trust `X-Forwarded-For` by default.** Any client can
+send that header, so taking its leftmost entry hands the caller control of their
+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.
+
+## CORS
+
 ```typescript
-import { createRateLimiter, cors, securityHeaders } from "@zudojs/security";
+import {
+  generatePreflightHeaders,
+  generateSimpleHeaders,
+} from "@zudojs/security";
 
-const limiter = createRateLimiter({ windowMs: 60000, max: 100 });
+const config = { origin: ["https://app.example.com"], credentials: true };
 
-app.use(limiter);
-app.use(cors({ origin: "https://example.com" }));
-app.use(securityHeaders());
+// `Access-Control-Request-Headers` is a comma-separated list; split it
+// yourself — the package takes a `string[]`, not the raw header.
+const requested = (request.headers["access-control-request-headers"] ?? "")
+  .split(",")
+  .map((h) => h.trim())
+  .filter((h) => h.length > 0);
+
+// Preflight — optionally validating what the browser asked for.
+generatePreflightHeaders(request.headers.origin, config, {
+  method: request.headers["access-control-request-method"],
+  headers: requested,
+});
 ```
 
+`Vary: Origin` is emitted whenever the allowed origin is reflected (array, regex
+or predicate), including on rejection — without it a shared cache can serve one
+origin's `Access-Control-Allow-Origin` to another. A wildcard origin combined
+with `credentials` throws, since browsers reject that pairing outright.
+
+## CSRF
+
+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:
+
+```typescript
+import { createCsrfProtection } from "@zudojs/security";
+
+const csrf = createCsrfProtection({
+  secret: process.env.CSRF_SECRET, // >= 32 chars
+  cookieName: "app_csrf",
+  headerName: "x-app-csrf",
+  expiration: 3600,
+});
+
+// Issue
+const { token, setCookie } = csrf.issue({ sessionId });
+setHeader("Set-Cookie", setCookie);
+
+// Verify — safe to call on every request; safe methods return true.
+if (!csrf.verify(
+  { method: request.method, headers: request.headers, cookieHeader: request.headers.cookie },
+  { sessionId },
+)) {
+  return respond(403);
+}
+```
+
+The same thing with the primitives, if you would rather hold the pieces:
+
+```typescript
+import {
+  generateCsrfToken,
+  generateCsrfCookie,
+  verifyDoubleSubmit,
+  extractCsrfTokenFromCookies,
+  extractCsrfTokenFromHeaders,
+  requiresCsrfProtection,
+} from "@zudojs/security";
+
+// Issue
+const token = generateCsrfToken(secret, { sessionId, expiration: 3600 });
+setHeader("Set-Cookie", generateCsrfCookie(token));
+
+// Verify
+if (requiresCsrfProtection(request.method)) {
+  const ok = verifyDoubleSubmit(
+    extractCsrfTokenFromCookies(request.headers.cookie ?? ""),
+    extractCsrfTokenFromHeaders(request.headers),
+    secret,
+    { sessionId },
+  );
+  if (!ok) return respond(403);
+}
+```
+
+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
+`httpOnly: false`, and accept that XSS on the origin can then read the token.
+
+## URLs and SSRF
+
+```typescript
+import {
+  isSafeUrl,
+  isPrivateHostname,
+  validateRequestTarget,
+} from "@zudojs/security";
+
+isSafeUrl("http://169.254.169.254/"); // false — cloud metadata
+isSafeUrl("http://[::ffff:127.0.0.1]/"); // false — v4-mapped loopback
+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`.
+
+**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
+outbound requests that must be safe, resolve the hostname yourself, run
+`isPrivateHostname` against the resolved address, and connect to that address.
+
+`validateRequestTarget` rejects CR and LF — literal or percent-encoded — and
+detects traversal by decoding to a fixed point rather than pattern-matching
+encoded forms. It also enforces `maxLength` and rejects invalid percent
+encoding; a single trailing `%` used to abort decoding altogether, so
+`/a/%2e%2e/etc/passwd%` and `/a%0d%0aX-Evil:1%` were both reported valid.
+
+It takes a `RequestTargetConfig` rather than the full `UrlValidationConfig`: a
+request target is origin-form and carries no scheme, so `allowedProtocols`
+could never apply to it.
+
+## Cookies
+
+`serializeCookie` validates before it writes: the value is percent-encoded, and
+an unsafe name, attribute, `Max-Age` or `Expires` throws. `SameSite=None` and
+`Partitioned` require `Secure`.
+
+`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
+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.
+
+```typescript
+createSecureCookie("sid", value, { maxAge: 3600 });
+// sid=…; Max-Age=3600; Secure; HttpOnly; SameSite=Lax
+```
+
+## Input sanitization
+
+```typescript
+import { sanitizeObject, detectThreats, escapeHtml } from "@zudojs/security";
+
+sanitizeObject(payload, { maxDepth: 32 }); // cycle-safe, arrays stay arrays
+detectThreats(input); // ordered: SQL_INJECTION, XSS, NULL_BYTE, CONTROL_CHARACTERS
+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.
+`escapeHtml` covers element text and quoted attribute values; unquoted
+attributes, `<script>` bodies and URL positions need their own encoding.
+
 ## Features
 
-- Input validation and sanitization
-- CORS configuration
-- CSRF token generation and validation
-- Rate limiting with sliding window
-- Security headers (CSP, HSTS, X-Frame-Options, etc.)
-- URL normalization and SSRF protection
+- Sliding-window rate limiting with proxy-aware client IP extraction
+- CORS with `Vary: Origin` and wildcard/credentials validation
+- CSRF tokens: HMAC-SHA256, session-bound, constant-time double-submit
+- URL validation, traversal detection and SSRF range checks
+- Cookie parsing and injection-safe serialization
+- Header validation, CRLF stripping and opt-in hop-by-hop rejection
+- Body size limits, `Content-Length` validation and request-smuggling framing checks
+- Security headers with a restrictive default CSP and HSTS
 
 ## Use Cases
 

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

@@ -12,7 +12,19 @@ export declare const DEFAULT_BODY_LIMITS: BodyLimitPresets;
  * @param contentLength - The Content-Length header value.
  * @returns An error message if invalid, or undefined.
  */
-export declare function validateContentLength(contentLength: string | undefined): string | undefined;
+export declare function validateContentLength(contentLength: string | undefined, maxSize?: number): string | undefined;
+/**
+ * Validates the framing headers of a request.
+ *
+ * A message carrying both `Content-Length` and `Transfer-Encoding`, or more
+ * than one distinct `Content-Length`, is ambiguous: two servers in a chain can
+ * disagree about where the body ends. RFC 9112 requires rejecting it.
+ *
+ * @param headers - Request headers.
+ * @param maxSize - Optional maximum allowed Content-Length in bytes.
+ * @returns An error message if the framing is unsafe, or undefined.
+ */
+export declare function validateBodyFraming(headers: Record<string, string | string[] | undefined>, maxSize?: number): string | undefined;
 /**
  * Validates that a body size is within the allowed limit.
  *
@@ -22,14 +34,33 @@ export declare function validateContentLength(contentLength: string | undefined)
  * @returns An error message if too large, or undefined.
  */
 export declare function validateBodySize(actualSize: number, maxSize?: number, contentType?: string): string | undefined;
+/**
+ * Parses a Content-Type header into its bare media type.
+ *
+ * Strips parameters (`; charset=utf-8`, `; boundary=…`) and lowercases, so
+ * routing decisions see `application/json` rather than the raw header.
+ *
+ * @param contentType - The Content-Type header value.
+ * @returns The lowercased media type, or undefined when absent or malformed.
+ */
+export declare function parseMediaType(contentType: string | undefined): string | undefined;
 /**
  * Gets the appropriate body limit for a given content type.
  *
+ * Routing is on the parsed media type, not on substrings of the raw header:
+ * a client that sends `application/x-notjson` does not get the JSON limit.
+ *
+ * Note that a form post cannot be recognised as an authentication request from
+ * its Content-Type — auth endpoints send exactly the same media type as any
+ * other form. Pass `purpose: "auth"` on those routes to select the tighter
+ * limit; otherwise a login form is bounded only by the upload limit.
+ *
  * @param contentType - The Content-Type header value.
  * @param presetLimits - Optional custom preset limits.
+ * @param purpose - Optional explicit route purpose, overriding type-based routing.
  * @returns The maximum body size in bytes.
  */
-export declare function getBodyLimitForContentType(contentType: string | undefined, presetLimits?: Partial<BodyLimitPresets>): number;
+export declare function getBodyLimitForContentType(contentType: string | undefined, presetLimits?: Partial<BodyLimitPresets>, purpose?: keyof BodyLimitPresets): number;
 /**
  * Validates a body limit configuration.
  *
@@ -37,6 +68,23 @@ export declare function getBodyLimitForContentType(contentType: string | undefin
  * @returns An error message if invalid, or undefined.
  */
 export declare function validateBodyLimitConfig(config: BodyLimitConfig): string | undefined;
+/**
+ * Resolves the body limit that applies to a content type from a rule list.
+ *
+ * This is the implementation of `BodyLimitConfig.contentTypes`, which was
+ * declared as *"Content types that use this limit (if empty, applies to all)"*
+ * and had no reader anywhere in the package — so the field could be filled in
+ * and would never change a single decision.
+ *
+ * A rule naming the content type wins over a catch-all, whatever the order in
+ * the array, so a general default can sit alongside specific overrides.
+ *
+ * @param contentType - The raw `Content-Type` header value.
+ * @param rules - Limit rules, each optionally scoped to content types.
+ * @param fallback - Limit to use when no rule applies.
+ * @returns The maximum body size in bytes.
+ */
+export declare function resolveBodyLimit(contentType: string | undefined, rules: readonly BodyLimitConfig[], fallback?: number): number;
 /**
  * Creates a body size checker function for use in middleware.
  *

package/dist/body/body.core.js

@@ -22,20 +22,70 @@ const DEFAULT_MAX_BODY_SIZE = 1_048_576;
  * @param contentLength - The Content-Length header value.
  * @returns An error message if invalid, or undefined.
  */
-export function validateContentLength(contentLength) {
+export function validateContentLength(contentLength, maxSize) {
     if (contentLength === undefined) {
         return undefined; // No Content-Length is fine (chunked transfer)
     }
-    const parsed = parseInt(contentLength, 10);
-    if (isNaN(parsed)) {
+    // RFC 9110: Content-Length is 1*DIGIT and nothing else. `parseInt` would
+    // accept "100abc" as 100 and "1e10" as 1 — a length the origin and any
+    // intermediary could disagree about, which is how requests get smuggled.
+    if (!/^\d+$/.test(contentLength)) {
         return `Content-Length is not a valid number: ${contentLength}`;
     }
-    if (parsed < 0) {
-        return `Content-Length cannot be negative: ${parsed}`;
-    }
+    const parsed = Number(contentLength);
     if (!Number.isSafeInteger(parsed)) {
         return `Content-Length is not a safe integer: ${contentLength}`;
     }
+    if (maxSize !== undefined && parsed > maxSize) {
+        return `Content-Length ${parsed} exceeds maximum ${maxSize} bytes`;
+    }
+    return undefined;
+}
+/**
+ * Validates the framing headers of a request.
+ *
+ * A message carrying both `Content-Length` and `Transfer-Encoding`, or more
+ * than one distinct `Content-Length`, is ambiguous: two servers in a chain can
+ * disagree about where the body ends. RFC 9112 requires rejecting it.
+ *
+ * @param headers - Request headers.
+ * @param maxSize - Optional maximum allowed Content-Length in bytes.
+ * @returns An error message if the framing is unsafe, or undefined.
+ */
+export function validateBodyFraming(headers, maxSize) {
+    const lookup = new Map(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const contentLength = lookup.get("content-length");
+    const transferEncoding = lookup.get("transfer-encoding");
+    if (contentLength !== undefined && transferEncoding !== undefined) {
+        return "Request specifies both Content-Length and Transfer-Encoding (request smuggling risk)";
+    }
+    if (Array.isArray(contentLength)) {
+        const distinct = new Set(contentLength.map((v) => v.trim()));
+        if (distinct.size > 1) {
+            return `Request specifies conflicting Content-Length values: ${[...distinct].join(", ")}`;
+        }
+        return validateContentLength(contentLength[0], maxSize);
+    }
+    if (typeof contentLength === "string") {
+        // A single header field may still carry a comma-separated list.
+        if (contentLength.includes(",")) {
+            const distinct = new Set(contentLength.split(",").map((v) => v.trim()));
+            if (distinct.size > 1) {
+                return `Request specifies conflicting Content-Length values: ${[...distinct].join(", ")}`;
+            }
+            return validateContentLength([...distinct][0], maxSize);
+        }
+        return validateContentLength(contentLength, maxSize);
+    }
+    if (typeof transferEncoding === "string") {
+        const encodings = transferEncoding
+            .toLowerCase()
+            .split(",")
+            .map((e) => e.trim());
+        if (encodings.length > 0 && encodings[encodings.length - 1] !== "chunked") {
+            return `Transfer-Encoding must end with "chunked", got: ${transferEncoding}`;
+        }
+    }
     return undefined;
 }
 /**
@@ -54,34 +104,70 @@ export function validateBodySize(actualSize, maxSize, contentType) {
     }
     return undefined;
 }
+/**
+ * Parses a Content-Type header into its bare media type.
+ *
+ * Strips parameters (`; charset=utf-8`, `; boundary=…`) and lowercases, so
+ * routing decisions see `application/json` rather than the raw header.
+ *
+ * @param contentType - The Content-Type header value.
+ * @returns The lowercased media type, or undefined when absent or malformed.
+ */
+export function parseMediaType(contentType) {
+    if (!contentType)
+        return undefined;
+    const bare = contentType.split(";")[0]?.trim().toLowerCase();
+    return bare && bare.includes("/") ? bare : undefined;
+}
 /**
  * Gets the appropriate body limit for a given content type.
  *
+ * Routing is on the parsed media type, not on substrings of the raw header:
+ * a client that sends `application/x-notjson` does not get the JSON limit.
+ *
+ * Note that a form post cannot be recognised as an authentication request from
+ * its Content-Type — auth endpoints send exactly the same media type as any
+ * other form. Pass `purpose: "auth"` on those routes to select the tighter
+ * limit; otherwise a login form is bounded only by the upload limit.
+ *
  * @param contentType - The Content-Type header value.
  * @param presetLimits - Optional custom preset limits.
+ * @param purpose - Optional explicit route purpose, overriding type-based routing.
  * @returns The maximum body size in bytes.
  */
-export function getBodyLimitForContentType(contentType, presetLimits) {
+export function getBodyLimitForContentType(contentType, presetLimits, purpose) {
     const limits = { ...DEFAULT_BODY_LIMITS, ...presetLimits };
-    if (!contentType) {
+    if (purpose !== undefined) {
+        return limits[purpose];
+    }
+    const type = parseMediaType(contentType);
+    if (!type) {
         return limits.json;
     }
-    const type = contentType.toLowerCase();
-    if (type.includes("json")) {
+    const [group = "", subtype = ""] = type.split("/");
+    // Structured-syntax suffixes: application/vnd.api+json, image/svg+xml, …
+    const suffix = subtype.includes("+")
+        ? subtype.slice(subtype.lastIndexOf("+") + 1)
+        : undefined;
+    if (subtype === "json" || suffix === "json") {
         return limits.json;
     }
-    if (type.includes("x-www-form-urlencoded") || type.includes("multipart")) {
-        // Check if it's likely an auth form
-        if (type.includes("login") || type.includes("auth")) {
-            return limits.auth;
-        }
-        return limits.upload;
+    if (subtype === "xml" || suffix === "xml") {
+        return limits.webhook;
     }
-    if (type.includes("octet-stream")) {
+    if (type === "application/x-www-form-urlencoded") {
+        // Urlencoded forms carry field data, not files — the JSON limit fits far
+        // better than the 100 MB upload limit a login form used to receive.
+        return limits.json;
+    }
+    if (group === "multipart") {
         return limits.upload;
     }
-    if (type.includes("xml")) {
-        return limits.webhook;
+    if (type === "application/octet-stream" ||
+        group === "image" ||
+        group === "video" ||
+        group === "audio") {
+        return limits.upload;
     }
     return limits.json;
 }
@@ -99,8 +185,53 @@ export function validateBodyLimitConfig(config) {
         // 1GB
         return `Body limit maxSize ${config.maxSize} exceeds maximum allowed (1GB)`;
     }
+    // `contentTypes` used to be declared and never looked at, here or anywhere.
+    // An entry that is not a media type would silently never match, so it is
+    // reported rather than ignored.
+    if (config.contentTypes) {
+        for (const entry of config.contentTypes) {
+            if (parseMediaType(entry) === undefined) {
+                return `Body limit contentTypes entry is not a media type: "${entry}" (expected e.g. "application/json")`;
+            }
+        }
+    }
     return undefined;
 }
+/**
+ * Resolves the body limit that applies to a content type from a rule list.
+ *
+ * This is the implementation of `BodyLimitConfig.contentTypes`, which was
+ * declared as *"Content types that use this limit (if empty, applies to all)"*
+ * and had no reader anywhere in the package — so the field could be filled in
+ * and would never change a single decision.
+ *
+ * A rule naming the content type wins over a catch-all, whatever the order in
+ * the array, so a general default can sit alongside specific overrides.
+ *
+ * @param contentType - The raw `Content-Type` header value.
+ * @param rules - Limit rules, each optionally scoped to content types.
+ * @param fallback - Limit to use when no rule applies.
+ * @returns The maximum body size in bytes.
+ */
+export function resolveBodyLimit(contentType, rules, fallback = DEFAULT_MAX_BODY_SIZE) {
+    const type = parseMediaType(contentType);
+    if (type !== undefined) {
+        for (const rule of rules) {
+            const scoped = rule.contentTypes;
+            if (!scoped || scoped.length === 0)
+                continue;
+            if (scoped.some((entry) => parseMediaType(entry) === type)) {
+                return rule.maxSize;
+            }
+        }
+    }
+    for (const rule of rules) {
+        if (!rule.contentTypes || rule.contentTypes.length === 0) {
+            return rule.maxSize;
+        }
+    }
+    return fallback;
+}
 /**
  * Creates a body size checker function for use in middleware.
  *

package/dist/body/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — Body Validation Barrel
  */
-export { DEFAULT_BODY_LIMITS, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, createBodySizeChecker, } from "./body.core.js";
+export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/body/index.js

@@ -1,5 +1,5 @@
 /**
  * @zudojs/security — Body Validation Barrel
  */
-export { DEFAULT_BODY_LIMITS, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, createBodySizeChecker, } from "./body.core.js";
+export { DEFAULT_BODY_LIMITS, parseMediaType, validateBodyFraming, validateContentLength, validateBodySize, getBodyLimitForContentType, validateBodyLimitConfig, resolveBodyLimit, createBodySizeChecker, } from "./body.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -18,9 +18,16 @@ export declare function parseCookieHeader(cookieHeader: string, config?: CookieS
 /**
  * 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 declare function serializeCookie(cookie: ParsedCookie, config?: CookieSecurityConfig): string;
 /**
@@ -31,6 +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.
  */
 export declare function createSecureCookie(name: string, value: string, options?: Partial<Omit<ParsedCookie, "name" | "value">>, config?: CookieSecurityConfig): string;
 /**
@@ -50,6 +58,10 @@ 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`.
+ *
  * @param cookieHeader - The raw Cookie header.
  * @param sensitiveNames - Names of cookies to strip (case-insensitive).
  * @returns The cleaned cookie header.