ingenium 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Buffer as Buffer$1 } from 'node:buffer';
 import * as node_http from 'node:http';
-import { IncomingHttpHeaders, Server as Server$1 } from 'node:http';
+import { IncomingHttpHeaders, IncomingMessage, Server as Server$1 } from 'node:http';
 import { Readable } from 'node:stream';
 import { KeyObject } from 'node:crypto';
 import { WebSocket as WebSocket$1 } from 'ws';
@@ -2202,7 +2202,9 @@ type CorsOriginFn = (origin: string, ctx: IngeniumContext) => boolean | string |
 /**
  * Spec for the `origin` option.
  *
- * - `boolean` — `true` reflects any request `Origin`; `false` disables CORS.
+ * - `boolean` — `true` reflects any request `Origin` (but never the literal
+ *   `"null"`, and rejected at construction when `credentials: true`); `false`
+ *   disables CORS.
  * - `'*'` — wildcard: `Access-Control-Allow-Origin: *`.
  * - any other `string` — exact match against the request's `Origin`.
  * - `string[]` — allowlist; matched exactly.
@@ -2234,8 +2236,9 @@ interface CorsOptions {
     exposedHeaders?: string[];
     /**
      * If `true`, sets `Access-Control-Allow-Credentials: true`.
-     * Incompatible with `origin: '*'` — throws at construction time.
-     * Default: `false`.
+     * Incompatible with `origin: '*'` and `origin: true` — both throw at
+     * construction time, because reflecting credentials to an unrestricted set of
+     * origins lets any site read authenticated responses. Default: `false`.
      */
     credentials?: boolean;
     /**
@@ -2498,7 +2501,12 @@ interface CsrfCookieOptions {
     domain?: string;
     /** SameSite policy. Default `'lax'`. */
     sameSite?: 'lax' | 'strict' | 'none';
-    /** Mark cookie Secure. Default `false`; set `true` behind TLS. */
+    /**
+     * Mark cookie Secure. **Default `true`** so the CSRF cookie is never sent
+     * over plaintext HTTP where a network attacker could read it and forge the
+     * double-submit header. Override to `false` only for local HTTP development;
+     * doing so emits a dev-mode warning.
+     */
     secure?: boolean;
     /**
      * Mark cookie HttpOnly. **Default `false`** — clients must read the cookie
@@ -2521,6 +2529,22 @@ interface CsrfOptions {
     storage?: CsrfStorage;
     /** Cookie options when `storage === 'cookie'`. */
     cookie?: CsrfCookieOptions;
+    /**
+     * Bind a cookie-mode token to a per-session/per-user identifier (e.g. a
+     * session id or authenticated user id derived from `ctx`).
+     *
+     * Without binding, a signed double-submit token is only proven to have been
+     * minted by *this server* — any token the server ever issued is globally
+     * valid for any user, so a leaked or shared token defeats the protection.
+     * When this returns a stable value, the token is HMAC'd over
+     * `raw + '.' + binding` and the binding is re-verified on unsafe requests,
+     * so a token minted for one session cannot be replayed against another.
+     *
+     * Returning `undefined` (e.g. before login) falls back to plain
+     * double-submit and emits a dev-mode warning. Has no effect in session
+     * storage mode, where the session id already authenticates the binding.
+     */
+    sessionBinding?: (ctx: IngeniumContext) => string | undefined;
     /** Methods that bypass validation. Default `['GET', 'HEAD', 'OPTIONS', 'TRACE']`. */
     ignoreMethods?: readonly string[];
     /**
@@ -2773,6 +2797,8 @@ type JwtVerifyError = {
     error: 'bad_signature';
 } | {
     error: 'expired';
+} | {
+    error: 'missing_exp';
 } | {
     error: 'not_yet_valid';
 } | {
@@ -2832,6 +2858,17 @@ interface JwtOptions<T = Record<string, unknown>> {
     maxAgeSeconds?: number;
     /** Leeway for `nbf` / `exp` checks, in seconds. Default `5`. */
     clockSkewSeconds?: number;
+    /**
+     * Require a numeric `exp` claim. Default `true`.
+     *
+     * Why default-on: a token that omits `exp` (or carries a non-numeric one)
+     * would otherwise verify forever — a stolen token never stops working. We
+     * refuse those by default and only relax it for callers who deliberately
+     * issue non-expiring tokens (set this to `false`). Either way a present
+     * `exp`/`nbf`/`iat` that is not a finite number is treated as malformed, not
+     * silently skipped.
+     */
+    requireExp?: boolean;
     /**
      * If `true` (default), missing tokens raise `IngeniumUnauthorizedError`.
      * If `false`, missing tokens just call `next()` with no `ctx.jwt`.
@@ -2861,6 +2898,17 @@ interface JwtOptions<T = Record<string, unknown>> {
     _payload?: T;
 }
 
+/**
+ * 500 — the configured algorithm allowlist and the supplied key material are
+ * from different families (an HMAC alg paired with an asymmetric PEM / public
+ * key, or vice versa). Allowing this is the canonical algorithm-confusion
+ * footgun: an attacker forges `HS256` tokens using the server's *public* key
+ * as the HMAC secret. We refuse the configuration at construction time so the
+ * mistake surfaces at boot, not as a silent auth bypass.
+ */
+declare class IngeniumJwtKeyAlgMismatchError extends IngeniumError {
+    constructor(message: string);
+}
 /**
  * Bearer-token JWT verification middleware.
  *
@@ -3496,6 +3544,11 @@ interface VerifyOptions {
     issuer?: string | readonly string[];
     maxAgeSeconds?: number;
     clockSkewSeconds?: number;
+    /**
+     * Require a finite numeric `exp`. Default `true` — a token without an
+     * expiry would otherwise verify forever (see middleware `requireExp`).
+     */
+    requireExp?: boolean;
     /** Override "now" for deterministic tests. Returns seconds since epoch. */
     nowSeconds?: () => number;
 }
@@ -3658,7 +3711,20 @@ interface SessionCookieOptions {
     httpOnly?: boolean;
     /** Cookie `SameSite` attribute. @default 'lax' */
     sameSite?: 'lax' | 'strict' | 'none';
-    /** Cookie `Secure` attribute. @default false */
+    /**
+     * Cookie `Secure` attribute.
+     *
+     * When left undefined, {@link sessionMiddleware} resolves it safely: ON in
+     * production (`NODE_ENV==='production'`) so the cookie cannot ride plaintext
+     * HTTP, OFF in dev so `http://localhost` keeps working. Set `false`
+     * explicitly to opt out in production (emits a dev warning), or `true` to
+     * force it on in every environment.
+     *
+     * Note: the raw {@link serializeCookie} helper still treats `undefined` as
+     * off — only the middleware applies the environment-aware default.
+     *
+     * @default undefined (production → Secure, dev → not Secure)
+     */
     secure?: boolean;
 }
 /** Options accepted by {@link sessionMiddleware}. */
@@ -3762,8 +3828,10 @@ interface SessionStore {
  * - HMAC-SHA-256 over the session id, base64url-encoded; verified with
  *   `timingSafeEqual`.
  * - 144-bit (18-byte) random ids.
- * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. Set `secure: true`
- *   behind TLS to enable `Secure`.
+ * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. `Secure` defaults ON in
+ *   production (`NODE_ENV==='production'`) and OFF in dev so http://localhost
+ *   keeps working; set `cookie.secure: false` to force it off in production
+ *   (a dev warning fires), or `true` to force it on everywhere.
  * - Tampered or unknown cookies silently issue a fresh session — never an
  *   error response, since this is an attacker-influenced surface.
  */
@@ -3810,12 +3878,40 @@ type WebSocket = WebSocket$1;
  * are not meaningful for WS handlers (the upgrade has already happened).
  */
 type WebSocketHandler = (socket: WebSocket$1, ctx: IngeniumContext) => void | Promise<void>;
+/**
+ * Custom Origin verifier. Receives the request's `Origin` header (or
+ * `undefined` when absent, e.g. a non-browser client) plus the raw upgrade
+ * request. Return `true` to allow the upgrade, `false` to reject it with a
+ * `403` handshake.
+ */
+type WebSocketOriginVerifier = (origin: string | undefined, req: IncomingMessage) => boolean;
+/**
+ * Origin allowlist policy for a WebSocket upgrade. WS handlers run OUTSIDE the
+ * normal middleware pipeline, so the only built-in defense against
+ * Cross-Site WebSocket Hijacking (CSWSH) is this option — browsers attach the
+ * victim's cookies to cross-origin upgrades, so without an Origin check any
+ * external page can open an authenticated socket.
+ *
+ * - `true` — same-origin only: the `Origin` host must equal the request `Host`.
+ * - `string` / `string[]` — exact `Origin` allowlist (compared verbatim).
+ * - function — custom predicate (see {@link WebSocketOriginVerifier}).
+ *
+ * Omitting the option preserves backward compatibility (no enforcement) but
+ * emits a one-time dev warning, because the safe default for a browser-facing
+ * socket is to restrict origins.
+ */
+type WebSocketOriginOption = boolean | string | string[] | WebSocketOriginVerifier;
 /** Per-handler options forwarded to `WebSocketServer({ noServer: true, ... })`. */
 interface WebSocketHandlerOptions {
     /** Max payload size (bytes) for incoming frames. */
     maxPayload?: number;
     /** Enable permessage-deflate. Defaults to false (matches `ws` default). */
     perMessageDeflate?: boolean;
+    /**
+     * Origin allowlist for the upgrade handshake — the built-in CSWSH defense.
+     * See {@link WebSocketOriginOption} for semantics and why it matters.
+     */
+    origin?: WebSocketOriginOption;
 }
 /** Bag passed to integrators (advanced). */
 interface WsIntegrator {
@@ -4259,4 +4355,4 @@ declare const ingenium: IngeniumFactory & {
     openapiHandler: typeof openapiHandler;
 };
 
-export { type ApiKeyLogger, type ApiKeyOptions, type ApiKeyValidator, type CachedResponse, type CloseOptions, type ComposedHandler, type CookieGetOptions, type CookieSetOptions, type CorsOptions, type CorsOrigin, type CorsOriginFn, type CronHandler, type CronMatch, type CronOptions, CronRegistry, type CsrfCookieOptions, type CsrfOptions, type CsrfStorage, type CsrfValueReader, type Decorator, DecoratorRegistry, type EagerDecorator, type EnableWebSocketsOptions, type ExtractParams, type FailedJob, type FormatHandlers, type FormattableCtx, type ForwardedInfo, type GenerateOpenApiOptions, HTTP_METHODS, type HeaderBag, type Hooks, HooksRegistry, Http2Adapter, type Http2AdapterOptions, Http2cAdapter, type HttpMethod, IdempotencyMemoryStore, type IdempotencyOptions, type IdempotencyStore, IngeniumApp, type IngeniumAppOptions, IngeniumBadRequestError, IngeniumBody, IngeniumContext, IngeniumContextPool, type IngeniumCookies, IngeniumCronJob, IngeniumCsrfError, IngeniumError, type IngeniumErrorHandler, IngeniumHaltError, type IngeniumHandler, IngeniumHeaderInjectionError, IngeniumMethodNotAllowedError, type IngeniumMiddleware, IngeniumNotFoundError, IngeniumPayloadTooLargeError, type IngeniumPlugin, type IngeniumQuery, IngeniumQueue, IngeniumTimeoutError, IngeniumUnauthorizedError, IngeniumUnserializableError, IngeniumValidationError, type InjectRequest, type InjectResponse, type JobHandle, type JsonEtagCtx, type JsonEtagOptions, type JwtAlgorithm, type JwtHeader, type JwtKey, type JwtLogger, type JwtOptions, type JwtSecret, type JwtSecretResolver, type JwtTokenReader, type JwtVerified, type LazyDecorator, type ListeningServer, type MatchMiss, type MatchResult, MemoryQueueStore, type MultipartFile, type MultipartOptions, type MultipartResult, type NegotiableCtx, NodeAdapter, type OnComposeHook, type OnErrorHook, type OnRequestHook, type OnResponseHook, type OnRouteHook, type Components as OpenApiComponents, type Info as OpenApiInfo, type Response as OpenApiResponse, type Schema as OpenApiSchema, type SecurityRequirement as OpenApiSecurityRequirement, type SecurityScheme as OpenApiSecurityScheme, type Server as OpenApiServer, type OpenApiSpec, type Tag as OpenApiTag, type Operation, type Parameter, type ParseSchema, type ParsedAccept, type PathItem, type PluginTarget, type ProblemDetails, type ProblemDetailsOptions, type QueueOptions, QueueRegistry, type QueueStore, type QueueWorker, MemoryStore$1 as RateLimitMemoryStore, type RateLimitOptions, type RateLimitStore, type RegisteredQueue, type RegistrationEvent, type RequestBody, type ResponseBody, type RetryPolicy, RouteBuilder, type RouteDescriptor, type RouteOptions, Router, RouterTrie, type SafeJsonStringifyOptions, type SafeParseSchema, ScopedApp, type Session, type SessionCookieOptions, MemoryStore as SessionMemoryStore, type SessionOptions, type SessionStore, type ShutdownOptions, type SseEvent, type SseStream, type StandardFailureResult, type StandardIssue, type StandardPathSegment, type StandardResult, type StandardSchemaV1, type StandardSchemaV1Props, type StandardSuccessResult, type StaticOptions, type Transport, type TransportHooks, TrieNode, type TrustProxy, type WebSocket, type WebSocketHandler, type WebSocketHandlerOptions, type WsIntegrator, WsNodeAdapter, type WsRegistrar, _resetDefaultApp, accepts, acceptsCharsets, acceptsEncodings, acceptsLanguages, after, apiKeyMiddleware, before, clearJwksCache, compose, composeWithHandler, computeEtag, corsMiddleware as cors_, createWebSocketRegistrar, csrfMiddleware, ingenium as default, defaultApp, del as delete, enableWebSockets, expandShorthand, fetchJwks, formatResponse, generateOpenApi, get, gracefulShutdown, head, idempotencyMiddleware, ingenium, isFresh, isStandardSchema, jwtMiddleware, listen, nextFireFrom, onError, openapiHandler, options, parseAcceptHeader, parseCronSpec, patch, peerHasWs, post, problemDetailsMiddleware, put, rateLimit, resolveForwarded, respondJsonWithEtag, safeJsonStringify, selectBest, sessionMiddleware, sortByPreference, sse, startKeepAlive, staticMiddleware as static_, toProblemDetails, use, verifyJwt };
+export { type ApiKeyLogger, type ApiKeyOptions, type ApiKeyValidator, type CachedResponse, type CloseOptions, type ComposedHandler, type CookieGetOptions, type CookieSetOptions, type CorsOptions, type CorsOrigin, type CorsOriginFn, type CronHandler, type CronMatch, type CronOptions, CronRegistry, type CsrfCookieOptions, type CsrfOptions, type CsrfStorage, type CsrfValueReader, type Decorator, DecoratorRegistry, type EagerDecorator, type EnableWebSocketsOptions, type ExtractParams, type FailedJob, type FormatHandlers, type FormattableCtx, type ForwardedInfo, type GenerateOpenApiOptions, HTTP_METHODS, type HeaderBag, type Hooks, HooksRegistry, Http2Adapter, type Http2AdapterOptions, Http2cAdapter, type HttpMethod, IdempotencyMemoryStore, type IdempotencyOptions, type IdempotencyStore, IngeniumApp, type IngeniumAppOptions, IngeniumBadRequestError, IngeniumBody, IngeniumContext, IngeniumContextPool, type IngeniumCookies, IngeniumCronJob, IngeniumCsrfError, IngeniumError, type IngeniumErrorHandler, IngeniumHaltError, type IngeniumHandler, IngeniumHeaderInjectionError, IngeniumJwtKeyAlgMismatchError, IngeniumMethodNotAllowedError, type IngeniumMiddleware, IngeniumNotFoundError, IngeniumPayloadTooLargeError, type IngeniumPlugin, type IngeniumQuery, IngeniumQueue, IngeniumTimeoutError, IngeniumUnauthorizedError, IngeniumUnserializableError, IngeniumValidationError, type InjectRequest, type InjectResponse, type JobHandle, type JsonEtagCtx, type JsonEtagOptions, type JwtAlgorithm, type JwtHeader, type JwtKey, type JwtLogger, type JwtOptions, type JwtSecret, type JwtSecretResolver, type JwtTokenReader, type JwtVerified, type LazyDecorator, type ListeningServer, type MatchMiss, type MatchResult, MemoryQueueStore, type MultipartFile, type MultipartOptions, type MultipartResult, type NegotiableCtx, NodeAdapter, type OnComposeHook, type OnErrorHook, type OnRequestHook, type OnResponseHook, type OnRouteHook, type Components as OpenApiComponents, type Info as OpenApiInfo, type Response as OpenApiResponse, type Schema as OpenApiSchema, type SecurityRequirement as OpenApiSecurityRequirement, type SecurityScheme as OpenApiSecurityScheme, type Server as OpenApiServer, type OpenApiSpec, type Tag as OpenApiTag, type Operation, type Parameter, type ParseSchema, type ParsedAccept, type PathItem, type PluginTarget, type ProblemDetails, type ProblemDetailsOptions, type QueueOptions, QueueRegistry, type QueueStore, type QueueWorker, MemoryStore$1 as RateLimitMemoryStore, type RateLimitOptions, type RateLimitStore, type RegisteredQueue, type RegistrationEvent, type RequestBody, type ResponseBody, type RetryPolicy, RouteBuilder, type RouteDescriptor, type RouteOptions, Router, RouterTrie, type SafeJsonStringifyOptions, type SafeParseSchema, ScopedApp, type Session, type SessionCookieOptions, MemoryStore as SessionMemoryStore, type SessionOptions, type SessionStore, type ShutdownOptions, type SseEvent, type SseStream, type StandardFailureResult, type StandardIssue, type StandardPathSegment, type StandardResult, type StandardSchemaV1, type StandardSchemaV1Props, type StandardSuccessResult, type StaticOptions, type Transport, type TransportHooks, TrieNode, type TrustProxy, type WebSocket, type WebSocketHandler, type WebSocketHandlerOptions, type WsIntegrator, WsNodeAdapter, type WsRegistrar, _resetDefaultApp, accepts, acceptsCharsets, acceptsEncodings, acceptsLanguages, after, apiKeyMiddleware, before, clearJwksCache, compose, composeWithHandler, computeEtag, corsMiddleware as cors_, createWebSocketRegistrar, csrfMiddleware, ingenium as default, defaultApp, del as delete, enableWebSockets, expandShorthand, fetchJwks, formatResponse, generateOpenApi, get, gracefulShutdown, head, idempotencyMiddleware, ingenium, isFresh, isStandardSchema, jwtMiddleware, listen, nextFireFrom, onError, openapiHandler, options, parseAcceptHeader, parseCronSpec, patch, peerHasWs, post, problemDetailsMiddleware, put, rateLimit, resolveForwarded, respondJsonWithEtag, safeJsonStringify, selectBest, sessionMiddleware, sortByPreference, sse, startKeepAlive, staticMiddleware as static_, toProblemDetails, use, verifyJwt };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Buffer as Buffer$1 } from 'node:buffer';
 import * as node_http from 'node:http';
-import { IncomingHttpHeaders, Server as Server$1 } from 'node:http';
+import { IncomingHttpHeaders, IncomingMessage, Server as Server$1 } from 'node:http';
 import { Readable } from 'node:stream';
 import { KeyObject } from 'node:crypto';
 import { WebSocket as WebSocket$1 } from 'ws';
@@ -2202,7 +2202,9 @@ type CorsOriginFn = (origin: string, ctx: IngeniumContext) => boolean | string |
 /**
  * Spec for the `origin` option.
  *
- * - `boolean` — `true` reflects any request `Origin`; `false` disables CORS.
+ * - `boolean` — `true` reflects any request `Origin` (but never the literal
+ *   `"null"`, and rejected at construction when `credentials: true`); `false`
+ *   disables CORS.
  * - `'*'` — wildcard: `Access-Control-Allow-Origin: *`.
  * - any other `string` — exact match against the request's `Origin`.
  * - `string[]` — allowlist; matched exactly.
@@ -2234,8 +2236,9 @@ interface CorsOptions {
     exposedHeaders?: string[];
     /**
      * If `true`, sets `Access-Control-Allow-Credentials: true`.
-     * Incompatible with `origin: '*'` — throws at construction time.
-     * Default: `false`.
+     * Incompatible with `origin: '*'` and `origin: true` — both throw at
+     * construction time, because reflecting credentials to an unrestricted set of
+     * origins lets any site read authenticated responses. Default: `false`.
      */
     credentials?: boolean;
     /**
@@ -2498,7 +2501,12 @@ interface CsrfCookieOptions {
     domain?: string;
     /** SameSite policy. Default `'lax'`. */
     sameSite?: 'lax' | 'strict' | 'none';
-    /** Mark cookie Secure. Default `false`; set `true` behind TLS. */
+    /**
+     * Mark cookie Secure. **Default `true`** so the CSRF cookie is never sent
+     * over plaintext HTTP where a network attacker could read it and forge the
+     * double-submit header. Override to `false` only for local HTTP development;
+     * doing so emits a dev-mode warning.
+     */
     secure?: boolean;
     /**
      * Mark cookie HttpOnly. **Default `false`** — clients must read the cookie
@@ -2521,6 +2529,22 @@ interface CsrfOptions {
     storage?: CsrfStorage;
     /** Cookie options when `storage === 'cookie'`. */
     cookie?: CsrfCookieOptions;
+    /**
+     * Bind a cookie-mode token to a per-session/per-user identifier (e.g. a
+     * session id or authenticated user id derived from `ctx`).
+     *
+     * Without binding, a signed double-submit token is only proven to have been
+     * minted by *this server* — any token the server ever issued is globally
+     * valid for any user, so a leaked or shared token defeats the protection.
+     * When this returns a stable value, the token is HMAC'd over
+     * `raw + '.' + binding` and the binding is re-verified on unsafe requests,
+     * so a token minted for one session cannot be replayed against another.
+     *
+     * Returning `undefined` (e.g. before login) falls back to plain
+     * double-submit and emits a dev-mode warning. Has no effect in session
+     * storage mode, where the session id already authenticates the binding.
+     */
+    sessionBinding?: (ctx: IngeniumContext) => string | undefined;
     /** Methods that bypass validation. Default `['GET', 'HEAD', 'OPTIONS', 'TRACE']`. */
     ignoreMethods?: readonly string[];
     /**
@@ -2773,6 +2797,8 @@ type JwtVerifyError = {
     error: 'bad_signature';
 } | {
     error: 'expired';
+} | {
+    error: 'missing_exp';
 } | {
     error: 'not_yet_valid';
 } | {
@@ -2832,6 +2858,17 @@ interface JwtOptions<T = Record<string, unknown>> {
     maxAgeSeconds?: number;
     /** Leeway for `nbf` / `exp` checks, in seconds. Default `5`. */
     clockSkewSeconds?: number;
+    /**
+     * Require a numeric `exp` claim. Default `true`.
+     *
+     * Why default-on: a token that omits `exp` (or carries a non-numeric one)
+     * would otherwise verify forever — a stolen token never stops working. We
+     * refuse those by default and only relax it for callers who deliberately
+     * issue non-expiring tokens (set this to `false`). Either way a present
+     * `exp`/`nbf`/`iat` that is not a finite number is treated as malformed, not
+     * silently skipped.
+     */
+    requireExp?: boolean;
     /**
      * If `true` (default), missing tokens raise `IngeniumUnauthorizedError`.
      * If `false`, missing tokens just call `next()` with no `ctx.jwt`.
@@ -2861,6 +2898,17 @@ interface JwtOptions<T = Record<string, unknown>> {
     _payload?: T;
 }
 
+/**
+ * 500 — the configured algorithm allowlist and the supplied key material are
+ * from different families (an HMAC alg paired with an asymmetric PEM / public
+ * key, or vice versa). Allowing this is the canonical algorithm-confusion
+ * footgun: an attacker forges `HS256` tokens using the server's *public* key
+ * as the HMAC secret. We refuse the configuration at construction time so the
+ * mistake surfaces at boot, not as a silent auth bypass.
+ */
+declare class IngeniumJwtKeyAlgMismatchError extends IngeniumError {
+    constructor(message: string);
+}
 /**
  * Bearer-token JWT verification middleware.
  *
@@ -3496,6 +3544,11 @@ interface VerifyOptions {
     issuer?: string | readonly string[];
     maxAgeSeconds?: number;
     clockSkewSeconds?: number;
+    /**
+     * Require a finite numeric `exp`. Default `true` — a token without an
+     * expiry would otherwise verify forever (see middleware `requireExp`).
+     */
+    requireExp?: boolean;
     /** Override "now" for deterministic tests. Returns seconds since epoch. */
     nowSeconds?: () => number;
 }
@@ -3658,7 +3711,20 @@ interface SessionCookieOptions {
     httpOnly?: boolean;
     /** Cookie `SameSite` attribute. @default 'lax' */
     sameSite?: 'lax' | 'strict' | 'none';
-    /** Cookie `Secure` attribute. @default false */
+    /**
+     * Cookie `Secure` attribute.
+     *
+     * When left undefined, {@link sessionMiddleware} resolves it safely: ON in
+     * production (`NODE_ENV==='production'`) so the cookie cannot ride plaintext
+     * HTTP, OFF in dev so `http://localhost` keeps working. Set `false`
+     * explicitly to opt out in production (emits a dev warning), or `true` to
+     * force it on in every environment.
+     *
+     * Note: the raw {@link serializeCookie} helper still treats `undefined` as
+     * off — only the middleware applies the environment-aware default.
+     *
+     * @default undefined (production → Secure, dev → not Secure)
+     */
     secure?: boolean;
 }
 /** Options accepted by {@link sessionMiddleware}. */
@@ -3762,8 +3828,10 @@ interface SessionStore {
  * - HMAC-SHA-256 over the session id, base64url-encoded; verified with
  *   `timingSafeEqual`.
  * - 144-bit (18-byte) random ids.
- * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. Set `secure: true`
- *   behind TLS to enable `Secure`.
+ * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. `Secure` defaults ON in
+ *   production (`NODE_ENV==='production'`) and OFF in dev so http://localhost
+ *   keeps working; set `cookie.secure: false` to force it off in production
+ *   (a dev warning fires), or `true` to force it on everywhere.
  * - Tampered or unknown cookies silently issue a fresh session — never an
  *   error response, since this is an attacker-influenced surface.
  */
@@ -3810,12 +3878,40 @@ type WebSocket = WebSocket$1;
  * are not meaningful for WS handlers (the upgrade has already happened).
  */
 type WebSocketHandler = (socket: WebSocket$1, ctx: IngeniumContext) => void | Promise<void>;
+/**
+ * Custom Origin verifier. Receives the request's `Origin` header (or
+ * `undefined` when absent, e.g. a non-browser client) plus the raw upgrade
+ * request. Return `true` to allow the upgrade, `false` to reject it with a
+ * `403` handshake.
+ */
+type WebSocketOriginVerifier = (origin: string | undefined, req: IncomingMessage) => boolean;
+/**
+ * Origin allowlist policy for a WebSocket upgrade. WS handlers run OUTSIDE the
+ * normal middleware pipeline, so the only built-in defense against
+ * Cross-Site WebSocket Hijacking (CSWSH) is this option — browsers attach the
+ * victim's cookies to cross-origin upgrades, so without an Origin check any
+ * external page can open an authenticated socket.
+ *
+ * - `true` — same-origin only: the `Origin` host must equal the request `Host`.
+ * - `string` / `string[]` — exact `Origin` allowlist (compared verbatim).
+ * - function — custom predicate (see {@link WebSocketOriginVerifier}).
+ *
+ * Omitting the option preserves backward compatibility (no enforcement) but
+ * emits a one-time dev warning, because the safe default for a browser-facing
+ * socket is to restrict origins.
+ */
+type WebSocketOriginOption = boolean | string | string[] | WebSocketOriginVerifier;
 /** Per-handler options forwarded to `WebSocketServer({ noServer: true, ... })`. */
 interface WebSocketHandlerOptions {
     /** Max payload size (bytes) for incoming frames. */
     maxPayload?: number;
     /** Enable permessage-deflate. Defaults to false (matches `ws` default). */
     perMessageDeflate?: boolean;
+    /**
+     * Origin allowlist for the upgrade handshake — the built-in CSWSH defense.
+     * See {@link WebSocketOriginOption} for semantics and why it matters.
+     */
+    origin?: WebSocketOriginOption;
 }
 /** Bag passed to integrators (advanced). */
 interface WsIntegrator {
@@ -4259,4 +4355,4 @@ declare const ingenium: IngeniumFactory & {
     openapiHandler: typeof openapiHandler;
 };
 
-export { type ApiKeyLogger, type ApiKeyOptions, type ApiKeyValidator, type CachedResponse, type CloseOptions, type ComposedHandler, type CookieGetOptions, type CookieSetOptions, type CorsOptions, type CorsOrigin, type CorsOriginFn, type CronHandler, type CronMatch, type CronOptions, CronRegistry, type CsrfCookieOptions, type CsrfOptions, type CsrfStorage, type CsrfValueReader, type Decorator, DecoratorRegistry, type EagerDecorator, type EnableWebSocketsOptions, type ExtractParams, type FailedJob, type FormatHandlers, type FormattableCtx, type ForwardedInfo, type GenerateOpenApiOptions, HTTP_METHODS, type HeaderBag, type Hooks, HooksRegistry, Http2Adapter, type Http2AdapterOptions, Http2cAdapter, type HttpMethod, IdempotencyMemoryStore, type IdempotencyOptions, type IdempotencyStore, IngeniumApp, type IngeniumAppOptions, IngeniumBadRequestError, IngeniumBody, IngeniumContext, IngeniumContextPool, type IngeniumCookies, IngeniumCronJob, IngeniumCsrfError, IngeniumError, type IngeniumErrorHandler, IngeniumHaltError, type IngeniumHandler, IngeniumHeaderInjectionError, IngeniumMethodNotAllowedError, type IngeniumMiddleware, IngeniumNotFoundError, IngeniumPayloadTooLargeError, type IngeniumPlugin, type IngeniumQuery, IngeniumQueue, IngeniumTimeoutError, IngeniumUnauthorizedError, IngeniumUnserializableError, IngeniumValidationError, type InjectRequest, type InjectResponse, type JobHandle, type JsonEtagCtx, type JsonEtagOptions, type JwtAlgorithm, type JwtHeader, type JwtKey, type JwtLogger, type JwtOptions, type JwtSecret, type JwtSecretResolver, type JwtTokenReader, type JwtVerified, type LazyDecorator, type ListeningServer, type MatchMiss, type MatchResult, MemoryQueueStore, type MultipartFile, type MultipartOptions, type MultipartResult, type NegotiableCtx, NodeAdapter, type OnComposeHook, type OnErrorHook, type OnRequestHook, type OnResponseHook, type OnRouteHook, type Components as OpenApiComponents, type Info as OpenApiInfo, type Response as OpenApiResponse, type Schema as OpenApiSchema, type SecurityRequirement as OpenApiSecurityRequirement, type SecurityScheme as OpenApiSecurityScheme, type Server as OpenApiServer, type OpenApiSpec, type Tag as OpenApiTag, type Operation, type Parameter, type ParseSchema, type ParsedAccept, type PathItem, type PluginTarget, type ProblemDetails, type ProblemDetailsOptions, type QueueOptions, QueueRegistry, type QueueStore, type QueueWorker, MemoryStore$1 as RateLimitMemoryStore, type RateLimitOptions, type RateLimitStore, type RegisteredQueue, type RegistrationEvent, type RequestBody, type ResponseBody, type RetryPolicy, RouteBuilder, type RouteDescriptor, type RouteOptions, Router, RouterTrie, type SafeJsonStringifyOptions, type SafeParseSchema, ScopedApp, type Session, type SessionCookieOptions, MemoryStore as SessionMemoryStore, type SessionOptions, type SessionStore, type ShutdownOptions, type SseEvent, type SseStream, type StandardFailureResult, type StandardIssue, type StandardPathSegment, type StandardResult, type StandardSchemaV1, type StandardSchemaV1Props, type StandardSuccessResult, type StaticOptions, type Transport, type TransportHooks, TrieNode, type TrustProxy, type WebSocket, type WebSocketHandler, type WebSocketHandlerOptions, type WsIntegrator, WsNodeAdapter, type WsRegistrar, _resetDefaultApp, accepts, acceptsCharsets, acceptsEncodings, acceptsLanguages, after, apiKeyMiddleware, before, clearJwksCache, compose, composeWithHandler, computeEtag, corsMiddleware as cors_, createWebSocketRegistrar, csrfMiddleware, ingenium as default, defaultApp, del as delete, enableWebSockets, expandShorthand, fetchJwks, formatResponse, generateOpenApi, get, gracefulShutdown, head, idempotencyMiddleware, ingenium, isFresh, isStandardSchema, jwtMiddleware, listen, nextFireFrom, onError, openapiHandler, options, parseAcceptHeader, parseCronSpec, patch, peerHasWs, post, problemDetailsMiddleware, put, rateLimit, resolveForwarded, respondJsonWithEtag, safeJsonStringify, selectBest, sessionMiddleware, sortByPreference, sse, startKeepAlive, staticMiddleware as static_, toProblemDetails, use, verifyJwt };
+export { type ApiKeyLogger, type ApiKeyOptions, type ApiKeyValidator, type CachedResponse, type CloseOptions, type ComposedHandler, type CookieGetOptions, type CookieSetOptions, type CorsOptions, type CorsOrigin, type CorsOriginFn, type CronHandler, type CronMatch, type CronOptions, CronRegistry, type CsrfCookieOptions, type CsrfOptions, type CsrfStorage, type CsrfValueReader, type Decorator, DecoratorRegistry, type EagerDecorator, type EnableWebSocketsOptions, type ExtractParams, type FailedJob, type FormatHandlers, type FormattableCtx, type ForwardedInfo, type GenerateOpenApiOptions, HTTP_METHODS, type HeaderBag, type Hooks, HooksRegistry, Http2Adapter, type Http2AdapterOptions, Http2cAdapter, type HttpMethod, IdempotencyMemoryStore, type IdempotencyOptions, type IdempotencyStore, IngeniumApp, type IngeniumAppOptions, IngeniumBadRequestError, IngeniumBody, IngeniumContext, IngeniumContextPool, type IngeniumCookies, IngeniumCronJob, IngeniumCsrfError, IngeniumError, type IngeniumErrorHandler, IngeniumHaltError, type IngeniumHandler, IngeniumHeaderInjectionError, IngeniumJwtKeyAlgMismatchError, IngeniumMethodNotAllowedError, type IngeniumMiddleware, IngeniumNotFoundError, IngeniumPayloadTooLargeError, type IngeniumPlugin, type IngeniumQuery, IngeniumQueue, IngeniumTimeoutError, IngeniumUnauthorizedError, IngeniumUnserializableError, IngeniumValidationError, type InjectRequest, type InjectResponse, type JobHandle, type JsonEtagCtx, type JsonEtagOptions, type JwtAlgorithm, type JwtHeader, type JwtKey, type JwtLogger, type JwtOptions, type JwtSecret, type JwtSecretResolver, type JwtTokenReader, type JwtVerified, type LazyDecorator, type ListeningServer, type MatchMiss, type MatchResult, MemoryQueueStore, type MultipartFile, type MultipartOptions, type MultipartResult, type NegotiableCtx, NodeAdapter, type OnComposeHook, type OnErrorHook, type OnRequestHook, type OnResponseHook, type OnRouteHook, type Components as OpenApiComponents, type Info as OpenApiInfo, type Response as OpenApiResponse, type Schema as OpenApiSchema, type SecurityRequirement as OpenApiSecurityRequirement, type SecurityScheme as OpenApiSecurityScheme, type Server as OpenApiServer, type OpenApiSpec, type Tag as OpenApiTag, type Operation, type Parameter, type ParseSchema, type ParsedAccept, type PathItem, type PluginTarget, type ProblemDetails, type ProblemDetailsOptions, type QueueOptions, QueueRegistry, type QueueStore, type QueueWorker, MemoryStore$1 as RateLimitMemoryStore, type RateLimitOptions, type RateLimitStore, type RegisteredQueue, type RegistrationEvent, type RequestBody, type ResponseBody, type RetryPolicy, RouteBuilder, type RouteDescriptor, type RouteOptions, Router, RouterTrie, type SafeJsonStringifyOptions, type SafeParseSchema, ScopedApp, type Session, type SessionCookieOptions, MemoryStore as SessionMemoryStore, type SessionOptions, type SessionStore, type ShutdownOptions, type SseEvent, type SseStream, type StandardFailureResult, type StandardIssue, type StandardPathSegment, type StandardResult, type StandardSchemaV1, type StandardSchemaV1Props, type StandardSuccessResult, type StaticOptions, type Transport, type TransportHooks, TrieNode, type TrustProxy, type WebSocket, type WebSocketHandler, type WebSocketHandlerOptions, type WsIntegrator, WsNodeAdapter, type WsRegistrar, _resetDefaultApp, accepts, acceptsCharsets, acceptsEncodings, acceptsLanguages, after, apiKeyMiddleware, before, clearJwksCache, compose, composeWithHandler, computeEtag, corsMiddleware as cors_, createWebSocketRegistrar, csrfMiddleware, ingenium as default, defaultApp, del as delete, enableWebSockets, expandShorthand, fetchJwks, formatResponse, generateOpenApi, get, gracefulShutdown, head, idempotencyMiddleware, ingenium, isFresh, isStandardSchema, jwtMiddleware, listen, nextFireFrom, onError, openapiHandler, options, parseAcceptHeader, parseCronSpec, patch, peerHasWs, post, problemDetailsMiddleware, put, rateLimit, resolveForwarded, respondJsonWithEtag, safeJsonStringify, selectBest, sessionMiddleware, sortByPreference, sse, startKeepAlive, staticMiddleware as static_, toProblemDetails, use, verifyJwt };