balda 0.0.63 → 0.0.65

package/lib/index.d.cts

@@ -136,6 +136,17 @@ type StaticPluginOptions = {
      * @example "/assets" or "/public"
      */
     path: string;
+    /**
+     * Policy for dotfiles (files starting with `.`).
+     * - "ignore": return 404 (default)
+     * - "deny": return 403
+     * - "allow": serve normally
+     */
+    dotfiles?: "ignore" | "deny" | "allow";
+    /**
+     * Allow following symlinks. Disabled by default for security.
+     */
+    followSymlinks?: boolean;
 };
 type FileAllowedMimeType = "text/html" | "text/css" | "application/javascript" | "application/typescript" | "text/jsx" | "text/tsx" | "application/json" | "application/xml" | "application/yaml" | "text/csv" | "text/plain" | "text/markdown" | "image/png" | "image/jpeg" | "image/gif" | "image/svg+xml" | "image/x-icon" | "image/webp" | "image/avif" | "image/bmp" | "image/tiff" | "image/heic" | "image/heif" | "video/mp4" | "video/webm" | "video/x-msvideo" | "video/quicktime" | "video/x-matroska" | "video/x-ms-wmv" | "video/x-flv" | "video/x-m4v" | "video/mpeg" | "video/3gpp" | "audio/mpeg" | "audio/wav" | "audio/ogg" | "audio/flac" | "audio/aac" | "audio/mp4" | "audio/x-ms-wma" | "audio/opus" | "audio/midi" | "font/woff" | "font/woff2" | "font/ttf" | "font/otf" | "application/vnd.ms-fontobject" | "application/pdf" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.oasis.opendocument.text" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.presentation" | "application/rtf" | "application/epub+zip" | "application/zip" | "application/x-tar" | "application/gzip" | "application/x-bzip2" | "application/x-xz" | "application/vnd.rar" | "application/x-7z-compressed" | "application/wasm" | "application/manifest+json" | "text/calendar" | "text/vcard" | "application/sql" | "application/x-sh" | "application/x-msdos-program" | "application/x-msdownload" | "application/octet-stream" | "application/x-iso9660-image" | "application/x-apple-diskimage" | "application/vnd.android.package-archive" | "application/java-archive" | "application/x-shockwave-flash";
 
@@ -182,6 +193,118 @@ type FilePluginOptions = {
     allowedMimeTypes?: (FileAllowedMimeType | (string & {}))[];
 };
 
+type SessionStore = {
+    get: (sid: string) => Promise<Record<string, any> | undefined>;
+    set: (sid: string, value: Record<string, any>, ttlSeconds?: number) => Promise<void>;
+    destroy: (sid: string) => Promise<void>;
+};
+type SessionOptions = {
+    /** Cookie name used for session id */
+    name?: string;
+    /**
+     * Secret for signing the session cookie (sets `signed: true` on the session cookie).
+     * Requires `cookie({ sign: true, secret })` with the same secret.
+     */
+    secret?: string;
+    /** TTL seconds for session */
+    ttl?: number;
+    /** Custom store, default is in-memory */
+    store?: SessionStore;
+    /** Whether to set HttpOnly secure flags */
+    cookie?: {
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "Strict" | "Lax" | "None";
+        domain?: string;
+    };
+};
+
+/**
+ * Cookie options for setting cookies
+ */
+type CookieOptions = {
+    /**
+     * Domain for the cookie.
+     * ⚠️ Must not contain CR, LF, semicolons, or other control chars.
+     */
+    domain?: string;
+    /**
+     * Path for the cookie.
+     * ⚠️ Must not contain CR, LF, or semicolons.
+     */
+    path?: string;
+    /**
+     * Expiration date for the cookie.
+     * ⚠️ Will throw if the Date is invalid (NaN getTime).
+     */
+    expires?: Date;
+    /**
+     * Max age in seconds for the cookie. Must be a non-negative integer.
+     * Falsy values (including 0) are only skipped if undefined;
+     * pass maxAge: 0 to immediately expire.
+     */
+    maxAge?: number;
+    /**
+     * Whether the cookie is secure (HTTPS only)
+     * @default true
+     *
+     * ⚠️ Must be `true` when `sameSite` is `"None"`.
+     */
+    secure?: boolean;
+    /**
+     * Whether the cookie is HTTP only (prevents JavaScript access)
+     * @default true
+     */
+    httpOnly?: boolean;
+    /**
+     * SameSite attribute for the cookie
+     *
+     * - "Strict": Most secure, cookie not sent on cross-site requests
+     * - "Lax": Balanced, cookie sent on top-level navigation
+     * - "None": Least secure, requires secure=true
+     *
+     * ⚠️ "None" requires `secure: true`; combination is rejected at runtime.
+     */
+    sameSite?: "Strict" | "Lax" | "None";
+    /**
+     * Whether this individual cookie should be signed.
+     * The middleware must have `sign: true` and a `secret` set for this to work.
+     * Overrides the global `sign` option for this cookie only.
+     */
+    signed?: boolean;
+    /**
+     * Priority for the cookie
+     */
+    priority?: "Low" | "Medium" | "High";
+};
+/**
+ * Options for the cookie middleware
+ */
+type CookieMiddlewareOptions = {
+    /**
+     * Secret key(s) for signing cookies.
+     * - Provide a single string for static signing.
+     * - Provide an array for key rotation: signing uses `secret[0]`,
+     *   verification accepts any entry in the array.
+     * Required when `sign` is enabled.
+     */
+    secret?: string | string[];
+    /**
+     * Default options applied to all cookies set via `res.cookie()`.
+     */
+    defaults?: CookieOptions;
+    /**
+     * Whether to enable cookie parsing (defaults to true)
+     */
+    parse?: boolean;
+    /**
+     * Whether to enable cookie signing by default for all cookies (defaults to false).
+     * Individual cookies can override this via `CookieOptions.signed`.
+     */
+    sign?: boolean;
+};
+
 /**
  * The request object with type-safe path parameters.
  * This is the main object that is passed to the handler function.
@@ -349,6 +472,8 @@ declare class Request<Params extends Record<string, string> = Record<string, str
     file(fieldName: string): FormFile | null;
     get cookies(): Record<string, string>;
     set cookies(value: Record<string, string>);
+    get signedCookies(): Record<string, string>;
+    set signedCookies(value: Record<string, string>);
     /**
      * Returns cookies when the cookie middleware has populated them, otherwise undefined.
      * Useful for compatibility layers that should not throw when cookies are unavailable.
@@ -366,6 +491,36 @@ declare class Request<Params extends Record<string, string> = Record<string, str
      * @timeout middleware is required
      */
     timeout?: boolean;
+    /**
+     * Session dirty tracking - true if session was modified and needs to be saved.
+     * @internal
+     */
+    _sessionDirty: boolean;
+    /**
+     * Session ID for the current request.
+     * @internal
+     */
+    _sessionId?: string;
+    /**
+     * Session TTL in seconds.
+     * @internal
+     */
+    _sessionTtl?: number;
+    /**
+     * Session store instance.
+     * @internal
+     */
+    _sessionStore?: SessionStore;
+    /**
+     * Session cookie name.
+     * @internal
+     */
+    _sessionCookieName?: string;
+    /**
+     * Session cookie defaults.
+     * @internal
+     */
+    _sessionCookieDefaults?: CookieOptions;
     get session(): Record<string, any> | undefined;
     set session(value: Record<string, any> | undefined);
     /**
@@ -380,6 +535,7 @@ declare class Request<Params extends Record<string, string> = Record<string, str
      */
     private static readonly _throwSaveSession;
     private static readonly _throwDestroySession;
+    private static readonly _throwRegenerateSession;
     /**
      * Save the current session data.
      * @cookie middleware is required
@@ -394,6 +550,14 @@ declare class Request<Params extends Record<string, string> = Record<string, str
      * @throws Error if session middleware is not registered
      */
     destroySession: () => Promise<void>;
+    /**
+     * Regenerate the session: invalidates the old session ID and issues a new one.
+     * Call this after authentication to prevent session fixation attacks.
+     * @cookie middleware is required
+     * @session middleware is required
+     * @throws Error if session middleware is not registered
+     */
+    regenerateSession: () => Promise<void>;
     get ip(): string | undefined;
     set ip(value: string | undefined);
     /**
@@ -497,7 +661,7 @@ declare class Request<Params extends Record<string, string> = Record<string, str
      * Sets a lazy IP extractor for Bun runtime.
      * @internal
      */
-    setBunIpExtractor(req: globalThis.Request, server: any): void;
+    setBunIpExtractor(_req: globalThis.Request, server: any): void;
     /**
      * Sets a lazy IP extractor for Deno runtime.
      * @internal
@@ -1103,81 +1267,6 @@ type OpenIdConnectOptions = {
  */
 declare const controller: (path?: string, swaggerOptions?: SwaggerRouteOptions) => (target: any) => void;
 
-/**
- * Cookie options for setting cookies
- */
-type CookieOptions = {
-    /**
-     * Domain for the cookie
-     */
-    domain?: string;
-    /**
-     * Path for the cookie
-     */
-    path?: string;
-    /**
-     * Expiration date for the cookie
-     */
-    expires?: Date;
-    /**
-     * Max age in seconds for the cookie
-     */
-    maxAge?: number;
-    /**
-     * Whether the cookie is secure (HTTPS only)
-     * @default true
-     *
-     * ⚠️ Should be `true` in production to prevent transmission over HTTP
-     */
-    secure?: boolean;
-    /**
-     * Whether the cookie is HTTP only (prevents JavaScript access)
-     * @default true
-     *
-     * ✅ Recommended: `true` to prevent XSS attacks
-     */
-    httpOnly?: boolean;
-    /**
-     * SameSite attribute for the cookie
-     *
-     * - "Strict": Most secure, cookie not sent on cross-site requests
-     * - "Lax": Balanced, cookie sent on top-level navigation
-     * - "None": Least secure, requires secure=true
-     *
-     * ✅ Recommended: "Strict" for auth cookies
-     */
-    sameSite?: "Strict" | "Lax" | "None";
-    /**
-     * Whether the cookie should be signed
-     */
-    signed?: boolean;
-    /**
-     * Priority for the cookie
-     */
-    priority?: "Low" | "Medium" | "High";
-};
-/**
- * Options for the cookie middleware
- */
-type CookieMiddlewareOptions = {
-    /**
-     * Secret key for signing cookies (required if using signed cookies)
-     */
-    secret?: string;
-    /**
-     * Default options for all cookies set by this middleware
-     */
-    defaults?: CookieOptions;
-    /**
-     * Whether to enable cookie parsing (defaults to true)
-     */
-    parse?: boolean;
-    /**
-     * Whether to enable cookie signing (defaults to false)
-     */
-    sign?: boolean;
-};
-
 /**
  * The response object with per-status-code type-safe response bodies.
  * When response schemas are provided (e.g. via the `responses` route option), each shorthand
@@ -1200,6 +1289,12 @@ declare class Response$1<TResponseMap extends Record<number, any> = Record<numbe
      * The headers of the response
      */
     headers: Record<string, string>;
+    /**
+     * Accumulated Set-Cookie header values.
+     * Stored separately so each cookie is emitted as its own Set-Cookie header.
+     * @internal
+     */
+    cookieHeaders: string[];
     /**
      * The body of the response
      */
@@ -1211,7 +1306,9 @@ declare class Response$1<TResponseMap extends Record<number, any> = Record<numbe
      */
     setRouteResponseSchemas(schemas?: Record<number, RequestSchema>): void;
     /**
-     * Set a header for the response
+     * Set a header for the response.
+     * Set-Cookie values are accumulated as separate headers (RFC 6265 compliance).
+     * Throws if key or value contains CR or LF characters (header injection prevention).
      */
     setHeader(key: string, value: string): this;
     /**
@@ -1227,6 +1324,8 @@ declare class Response$1<TResponseMap extends Record<number, any> = Record<numbe
      * Send a response with the given body without any content type or encoding (as is), status defaults to 200
      */
     raw(body: any): void;
+    /** @internal — used by compression middleware to replace the body after async transformation */
+    setBodyDirect(body: any): void;
     /**
      * Send a response with the given text, status defaults to 200
      */
@@ -1657,6 +1756,7 @@ declare class MockResponse<T = any> {
     statusCode(): number;
     headers(): Record<string, string>;
     cookies(): Record<string, string>;
+    rawCookieHeaders(): string[];
     assertStatus(status: number): this;
     assertHeader(header: string, value: string): this;
     assertHeaderExists(header: string): this;
@@ -1695,6 +1795,12 @@ declare class NativeFs {
         isSymbolicLink: boolean;
         size: number;
     }>;
+    lstat(path: string): Promise<{
+        isDirectory: boolean;
+        isFile: boolean;
+        isSymbolicLink: boolean;
+        size: number;
+    }>;
     unlink(path: string): Promise<void>;
     streamFile(path: string): Promise<ReadableStream>;
     readdir(path: string): Promise<string[]>;
@@ -2004,9 +2110,6 @@ interface ValidationErrorHandlerOptions<T extends RequestSchema = RequestSchema>
     map?: (error: SerializedValidationError, req: Request) => ValidatedData<T> | Promise<ValidatedData<T>>;
 }
 
-/**
- * The server class that is used to create and manage the server
- */
 declare class Server<H extends NodeHttpClient = NodeHttpClient> implements ServerInterface {
     #private;
     readonly _brand: "BaldaServer";
@@ -2220,7 +2323,7 @@ declare class MockServer {
 interface JsonOptions {
     /**
      * The maximum size of the JSON body in bytes.
-     * If the body is larger than this limit, the request will be rejected.
+     * Enforced at the stream level — not reliant on Content-Length header.
      * Default: 100kb
      */
     sizeLimit?: `${number}mb` | `${number}kb`;
@@ -2237,6 +2340,17 @@ interface JsonOptions {
         status?: number;
         message?: string;
     };
+    /**
+     * Maximum nesting depth of parsed JSON. Protects against stack-overflow via deeply-nested objects.
+     * Default: 32
+     */
+    maxDepth?: number;
+    /**
+     * Maximum total number of object keys across all nesting levels.
+     * Protects against hash-flooding / CPU DoS via huge key counts.
+     * Default: 10000
+     */
+    maxKeys?: number;
 }
 
 /**
@@ -2290,34 +2404,48 @@ type CompressionOptions = {
      * Default: common compressible types (text, json, xml, javascript, etc.)
      */
     filter?: RegExp[];
+    /**
+     * Optional predicate to opt out of compression for specific requests/responses.
+     * Return true to skip compression (e.g. for sensitive endpoints to mitigate BREACH).
+     */
+    skipFor?: (req: Request, res: Response$1) => boolean;
 };
 
 type CorsMethods = "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH" | "HEAD";
 /**
- * Options for CORS middleware, similar to Express.js
+ * Options for CORS middleware.
+ *
+ * ⚠️ SECURITY NOTES:
+ * - `origin` is required. The old insecure `'*'` default has been removed.
+ * - `origin: '*'` combined with `credentials: true` throws at construction.
+ * - Regex origins: ensure patterns are anchored (^ and $) to prevent suffix-match bypasses.
+ *   Prefer an explicit string allowlist over regex.
  */
 type CorsOptions = {
     /**
      * Configures the Access-Control-Allow-Origin CORS header.
      *
-     * ⚠️ WARNING: The default value '*' allows ALL origins, which is insecure for production.
+     * - `'*'` — allow all origins (only for truly public APIs, cannot be used with credentials)
+     * - `'https://example.com'` — exact single origin
+     * - `['https://a.com', 'https://b.com']` — explicit allowlist (recommended for production)
+     * - `/^https:\/\/[a-z]+\.example\.com$/` — anchored regex (use with caution)
      *
-     * For production, explicitly set allowed origins:
-     * - Single origin: 'https://example.com'
-     * - Multiple origins: ['https://example.com', 'https://app.example.com']
-     * - Pattern matching: /^https:\/\/.*\.example\.com$/
-     *
-     * Defaults to '*' (allows all origins) - only suitable for development/public APIs.
+     * ⚠️ Regex patterns must be fully anchored. An unanchored pattern like
+     * `/example\.com/` matches `https://evil.com/?x=example.com`.
      */
-    origin?: string | RegExp | (string | RegExp)[];
+    origin: string | RegExp | (string | RegExp)[];
     /**
-     * Configures the Access-Control-Allow-Methods CORS header. Defaults to 'GET,HEAD,PUT,PATCH,POST,DELETE'.
+     * Configures the Access-Control-Allow-Methods CORS header.
+     * Defaults to 'GET, HEAD, PUT, PATCH, POST, DELETE'.
      */
     methods?: CorsMethods[] | string;
     /**
-     * Configures the Access-Control-Allow-Headers CORS header. Defaults to allowing all requested headers.
-     * When omitted, Balda echoes `Access-Control-Request-Headers` on preflight requests.
-     * Set this explicitly to override that default behavior.
+     * Configures the Access-Control-Allow-Headers CORS header.
+     * Defaults to `['Content-Type', 'Accept', 'Authorization']`.
+     *
+     * ⚠️ The old behavior of reflecting `Access-Control-Request-Headers` verbatim
+     * has been removed — that allowed clients to bless arbitrary headers.
+     * Set this explicitly to the headers your API actually needs.
      */
     allowedHeaders?: string[] | string;
     /**
@@ -2326,10 +2454,13 @@ type CorsOptions = {
     exposedHeaders?: string[] | string;
     /**
      * Configures the Access-Control-Allow-Credentials CORS header. Defaults to false.
+     *
+     * ⚠️ Cannot be `true` when `origin` is `'*'`.
      */
     credentials?: boolean;
     /**
      * Configures the Access-Control-Max-Age CORS header. Defaults to undefined (not sent).
+     * Recommended maximum: 600 seconds for sensitive endpoints.
      */
     maxAge?: number;
     /**
@@ -2337,9 +2468,15 @@ type CorsOptions = {
      */
     preflightContinue?: boolean;
     /**
-     * Provides a status code to use for successful OPTIONS requests, if preflightContinue is false. Defaults to 204.
+     * Provides a status code to use for successful OPTIONS requests, if preflightContinue is false.
+     * Defaults to 204.
      */
     optionsSuccessStatus?: number;
+    /**
+     * Allow the special `null` origin (sent by sandboxed iframes and file:// pages).
+     * Defaults to false. Only enable if you explicitly need to support these contexts.
+     */
+    allowNullOrigin?: boolean;
 };
 
 type ExpressRouter = IRouter;
@@ -2359,12 +2496,36 @@ interface HelmetOptions {
     };
     contentTypeOptions?: boolean;
     ieNoOpen?: boolean;
+    /**
+     * Controls the legacy X-XSS-Protection header.
+     * Modern guidance is to omit this header (set to false).
+     * @default false
+     * @deprecated Use Content-Security-Policy instead.
+     */
+    xssLegacyHeader?: boolean;
+    /** @deprecated Use xssLegacyHeader instead. */
     xssFilter?: boolean;
     referrerPolicy?: false | string;
     crossOriginResourcePolicy?: false | string;
     crossOriginOpenerPolicy?: false | string;
     crossOriginEmbedderPolicy?: false | string;
+    /**
+     * Content-Security-Policy header value.
+     * Set to `false` to disable.
+     * @default "default-src 'self'"
+     */
     contentSecurityPolicy?: false | string;
+    /**
+     * Permissions-Policy header value.
+     * Set to `false` to disable.
+     * @default "camera=(), microphone=(), geolocation=()"
+     */
+    permissionsPolicy?: false | string;
+    /**
+     * Emit `Origin-Agent-Cluster: ?1` header to opt in to origin-keyed agent clusters.
+     * @default true
+     */
+    originAgentCluster?: boolean;
 }
 
 type LoggerOptions = Parameters<typeof pino$1>[0];
@@ -2419,6 +2580,12 @@ type MethodOverrideOptions = {
      * Default: 'X-HTTP-Method-Override'
      */
     header?: string;
+    /**
+     * Disable the cross-site Origin/Referer check.
+     * ⚠️ Only set to true if you have an independent CSRF defense in place.
+     * Default: false (check is enabled)
+     */
+    disableCsrfCheck?: boolean;
 };
 
 type StorageStrategy = "memory" | "custom";
@@ -2443,6 +2610,11 @@ type BaseRateLimiterOptions = {
      * @default "memory"
      */
     storageStrategy?: StorageStrategy;
+    /**
+     * When storage throws, return 429 (fail closed) instead of allowing the request (fail open).
+     * @default false
+     */
+    failClosed?: boolean;
 };
 /**
  * Key Strategy
@@ -2481,9 +2653,26 @@ type MemoryStorageStrategy = {
      * @default 60000
      */
     windowMs?: number;
+    /**
+     * Maximum number of unique keys to track. When full, the oldest key is evicted.
+     * Protects against memory exhaustion from attacker-controlled key cardinality.
+     * @default 100000
+     */
+    maxKeys?: number;
 };
 /**
- * Custom Storage Strategy
+ * Atomic increment result returned by custom storage.
+ */
+type IncrementResult = {
+    /** Current request count for this key in the active window */
+    count: number;
+    /** Unix timestamp (ms) when the current window resets */
+    resetAt: number;
+};
+/**
+ * Custom Storage Strategy.
+ * Must implement an atomic increment that initialises a new fixed window on first call
+ * or after window expiry.
  */
 type CustomStorageStrategy = {
     /**
@@ -2491,13 +2680,11 @@ type CustomStorageStrategy = {
      */
     type: "custom";
     /**
-     * Set a value in the storage
-     */
-    set: (key: string, value: any) => Promise<void>;
-    /**
-     * Get a value from the storage
+     * Atomically increment the counter for `key` within a `windowMs`-wide fixed window.
+     * Should create a new window if none exists or the current one has expired.
+     * Returns the updated count and the window's reset timestamp.
      */
-    get: (key: string) => Promise<any>;
+    increment: (key: string, windowMs: number) => Promise<IncrementResult>;
 };
 type StorageOptions$1 = MemoryStorageStrategy | CustomStorageStrategy;
 /**
@@ -2505,30 +2692,6 @@ type StorageOptions$1 = MemoryStorageStrategy | CustomStorageStrategy;
  */
 type RateLimiterKeyOptions = IpRateLimiterOptions | CustomRateLimiterOptions;
 
-type SessionStore = {
-    get: (sid: string) => Promise<Record<string, any> | undefined>;
-    set: (sid: string, value: Record<string, any>, ttlSeconds?: number) => Promise<void>;
-    destroy: (sid: string) => Promise<void>;
-};
-type SessionOptions = {
-    /** Cookie name used for session id */
-    name?: string;
-    /** Secret used to sign session id (optional, for future) */
-    secret?: string;
-    /** TTL seconds for session */
-    ttl?: number;
-    /** Custom store, default is in-memory */
-    store?: SessionStore;
-    /** Whether to set HttpOnly secure flags */
-    cookie?: {
-        path?: string;
-        httpOnly?: boolean;
-        secure?: boolean;
-        sameSite?: "Strict" | "Lax" | "None";
-        domain?: string;
-    };
-};
-
 /**
  * Swagger plugin that serves the swagger UI and JSON specification, by default the UI will be available at /docs and the JSON specification at /docs/json
  * @warning The json specification is always available at /${globalOptions.path}/json
@@ -2542,12 +2705,26 @@ type TimeoutOptions = {
 };
 
 type TrustProxyOptions = {
-    /** Enable using X-Forwarded-* headers to determine client IP */
-    trust?: boolean;
-    /** Header name to read the client IP chain from */
+    /**
+     * Allowlist of trusted proxy IPs (exact match or IPv4 CIDR notation).
+     * The direct peer's socket IP must appear in this list before any
+     * X-Forwarded-For header is consumed.
+     *
+     * @example ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '127.0.0.1']
+     */
+    trustedProxies: string[];
+    /**
+     * Number of trusted proxy hops in the X-Forwarded-For chain (counted from the right).
+     * With hops = 1, the client IP is the last entry in the XFF list.
+     * With hops = 2, the client IP is the second-to-last entry.
+     * @default 1
+     */
+    hops?: number;
+    /**
+     * Header name to read the client IP chain from.
+     * @default "x-forwarded-for"
+     */
     header?: string;
-    /** Select which IP from the chain to use: 'first' (client) or 'last' (closest proxy) */
-    hop?: "first" | "last";
 };
 
 declare class PolicyManager<T extends Record<string, PolicyProvider>> {
@@ -3223,6 +3400,23 @@ declare const validate: {
     }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 };
 
+type VariantHandler<TInput, TOutput, TCtx = unknown> = (input: TInput, ctx?: TCtx) => TOutput | Promise<TOutput>;
+interface VariantConfig<TInput = unknown, TCtx = unknown> {
+    handler: VariantHandler<TInput, unknown, TCtx>;
+    schema?: RequestSchema;
+}
+interface SerializerBuilder<TInput, TDeclaredVariants extends string, TVariantMap extends Record<string, unknown>, TCtx = unknown> {
+    defineVariant<const TName extends string, TSchema extends RequestSchema>(name: TName, schema: TSchema, handler: (input: TInput, ctx?: TCtx) => ValidatedData<TSchema> | Promise<ValidatedData<TSchema>>): SerializerBuilder<TInput, TDeclaredVariants | TName, TVariantMap & Record<TName, ValidatedData<TSchema>>, TCtx>;
+    defineVariant<const TName extends string, TOutput>(name: TName, handler: (input: TInput, ctx?: TCtx) => TOutput | Promise<TOutput>): SerializerBuilder<TInput, TDeclaredVariants | TName, TVariantMap & Record<TName, TOutput>, TCtx>;
+    useVariant<TName extends TDeclaredVariants>(name: TName, data: TInput, options?: {
+        ctx?: TCtx;
+        validate?: boolean;
+    }): Promise<TVariantMap[TName]>;
+}
+
+declare function serializer<TSchema extends RequestSchema, TCtx extends RequestSchema | undefined = undefined>(inputSchema: TSchema, ctxSchema?: TCtx): SerializerBuilder<ValidatedData<TSchema>, never, {}, TCtx extends RequestSchema ? ValidatedData<TCtx> : unknown>;
+declare function serializer<TInput = unknown, TCtx = unknown>(): SerializerBuilder<TInput, never, {}, TCtx>;
+
 /**
  * Base class for cron jobs with logger instance
  * @example
@@ -4678,43 +4872,42 @@ declare abstract class BasePlugin {
 }
 
 /**
- * Compression middleware for gzip compression of response bodies
+ * Compression middleware for gzip compression of response bodies.
+ *
+ * Uses async gzip to avoid blocking the event loop on large payloads.
+ * Always emits `Vary: Accept-Encoding` to prevent cache poisoning.
+ *
+ * BREACH/CRIME note: if an endpoint reflects user-controlled data in a compressed
+ * response, use `skipFor` to opt that route out of compression.
  *
  * @param options Compression middleware options
  */
 declare const compression: (options?: CompressionOptions) => ServerRouteMiddleware;
 
 /**
- * Cookie middleware for parsing and setting cookies, must be used in order to use the cookie methods on the request and response objects
- *
- * @param options Cookie middleware options
+ * Cookie middleware for parsing and setting cookies.
+ * Must be used before any handler that accesses `req.cookies` or `req.signedCookies`.
  */
 declare const cookie: (options?: CookieMiddlewareOptions) => TypedMiddleware<{
     cookies: Record<string, string>;
+    signedCookies: Record<string, string>;
 }>;
 
 /**
  * CORS plugin
  *
- * ⚠️ SECURITY WARNING: By default, this plugin allows ALL origins ('*').
- * For production environments, explicitly configure allowed origins.
- *
- * @param options CORS options (all optional). Omitted options keep Balda's defaults,
- * including default methods and echoing `Access-Control-Request-Headers` on preflight
- * requests unless `allowedHeaders` is explicitly overridden.
+ * ⚠️ SECURITY: `origin` is now required. The old wildcard default has been removed.
+ * Using `origin: "*"` with `credentials: true` throws at construction.
  *
  * @example
- * // Development (permissive)
- * cors()
+ * // Explicit allowlist (production)
+ * cors({ origin: ['https://example.com', 'https://app.example.com'] })
  *
  * @example
- * // Production (secure)
- * cors({
- *   origin: ['https://example.com', 'https://app.example.com'],
- *   credentials: true
- * })
+ * // Public API (no credentials)
+ * cors({ origin: '*' })
  */
-declare const cors: (options?: CorsOptions) => ServerRouteMiddleware;
+declare const cors: (options: CorsOptions) => ServerRouteMiddleware;
 
 /**
  * Converts an Express middleware to a Balda middleware
@@ -4765,18 +4958,23 @@ declare const helmet: (options?: HelmetOptions) => ServerRouteMiddleware;
 declare const log: (options?: LogOptions) => ServerRouteMiddleware;
 
 /**
- * Method override middleware for supporting HTTP verbs like PUT/DELETE in clients that don't support them
+ * Method override middleware for supporting HTTP verbs like PUT/DELETE in clients that don't support them.
+ *
+ * ⚠️ CSRF risk: overriding to state-changing methods (PUT, PATCH, DELETE) via a browser form
+ * can bypass CSRF protections. This middleware rejects cross-site requests by default
+ * (based on Origin / Referer vs. Host). Disable with `disableCsrfCheck: true` only when
+ * you have an independent CSRF defense layer.
  *
  * @param options Method override middleware options
  */
 declare const methodOverride: (options?: MethodOverrideOptions) => ServerRouteMiddleware;
 
 /**
- * Rate limiter plugin
- * Rate limiter is a plugin that limits the number of requests to a resource.
- * It can be used to protect a resource from abuse.
- * @param keyOptions Rate limiter key options, tells the middleware how to retrieve the key from the request in to discriminate what to rate limit (all optional, defaults to ip)
- * @param storageOptions Rate limiter storage options, tells the middleware how to store the rate limit data (all optional, defaults to memory)
+ * Rate limiter plugin.
+ * Uses a fixed-window, atomic-increment counter keyed on IP or a custom value.
+ *
+ * @param keyOptions  How to derive the rate-limit key from the request.
+ * @param storageOptions  Where to store counters (in-memory or custom atomic store).
  */
 declare const rateLimiter: (keyOptions?: RateLimiterKeyOptions, storageOptions?: StorageOptions$1) => ServerRouteMiddleware;
 
@@ -4794,6 +4992,7 @@ declare const session: (options?: SessionOptions) => TypedMiddleware<{
     session: Record<string, any>;
     saveSession: () => Promise<void>;
     destroySession: () => Promise<void>;
+    regenerateSession: () => Promise<void>;
 }>;
 
 /**
@@ -4823,13 +5022,17 @@ declare const timeout: (options: TimeoutOptions) => TypedMiddleware<{
 }>;
 
 /**
- * Trust proxy plugin middleware, used to trust the proxy headers to get the client ip
- * @param options Trust proxy options (all optional)
- * @param options.trust Whether to trust the proxy headers
- * @param options.header The header name to read the client IP chain from
- * @param options.hop The hop to use to get the client IP
+ * Trust proxy middleware for consuming X-Forwarded-For headers safely.
+ *
+ * @example
+ * // Single reverse proxy at 10.0.0.1
+ * trustProxy({ trustedProxies: ['10.0.0.1'] })
+ *
+ * @example
+ * // Two proxy hops; proxies in a private subnet
+ * trustProxy({ trustedProxies: ['10.0.0.0/8'], hops: 2 })
  */
-declare const trustProxy: (options?: TrustProxyOptions) => ServerRouteMiddleware;
+declare const trustProxy: (options: TrustProxyOptions) => ServerRouteMiddleware;
 
 /**
  * Middleware to parse the body of the request. GET, DELETE and OPTIONS requests are not parsed. Used internally by the server. If no parser is set, the body will be parsed as raw array buffer.
@@ -5029,4 +5232,4 @@ declare enum CacheStatus {
  */
 declare const router: ClientRouter;
 
-export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, type BodyParserOptions, type BodylessMethodOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CacheMiddlewareOptions, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, DEFAULT_CACHE_OPTIONS, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, type GroupRouter, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferMiddlewareExtension, type InferMiddlewareExtensions, type InferResponseMap, type InferSchemaType, type InjectFunction, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, type PolicyErrorHandlerOptions, PolicyManager, type PolicyProvider, type PolicyRouteConfig, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, type SerializedValidationError, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerPlugin, type ServerPluginConfig, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StandardMethodOptions, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, type TypedMiddleware, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationErrorHandlerOptions, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bodyParser, bullmqQueue, cache, cacheMiddleware, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, cronUIInstance, cronUi, Server as default, defineMiddleware, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheService, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, initCacheService, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, resetCacheService, router, serialize, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };
+export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, type BodyParserOptions, type BodylessMethodOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CacheMiddlewareOptions, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, DEFAULT_CACHE_OPTIONS, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, type GroupRouter, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferMiddlewareExtension, type InferMiddlewareExtensions, type InferResponseMap, type InferSchemaType, type InjectFunction, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, type PolicyErrorHandlerOptions, PolicyManager, type PolicyProvider, type PolicyRouteConfig, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, type SerializedValidationError, type SerializerBuilder, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerPlugin, type ServerPluginConfig, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StandardMethodOptions, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, type TypedMiddleware, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationErrorHandlerOptions, type ValidationOptions, type VariantConfig, type VariantHandler, arg, asyncLocalStorage, asyncStorage, bodyParser, bullmqQueue, cache, cacheMiddleware, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, cronUIInstance, cronUi, Server as default, defineMiddleware, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheService, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, initCacheService, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, resetCacheService, router, serialize, serializer, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };