@orkestrel/middleware 0.0.1

package/dist/src/core/index.d.cts

@@ -0,0 +1,1339 @@
+import { ConnectionInfo } from '@orkestrel/server';
+import { CookieOptions } from '@orkestrel/server';
+import { Encoding } from '@orkestrel/server';
+import { MiddlewareContext } from '@orkestrel/server';
+import { MiddlewareHandler } from '@orkestrel/server';
+import { TokenSecret } from '@orkestrel/server';
+
+/**
+ * Options for `createBearer` — bearer-token authentication.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `secret` — the {@link TokenSecret} `verifyToken` checks the extracted
+ *   token against (rotation-aware).
+ * - `header` — the header the token is read from; defaults to
+ *   {@link DEFAULT_BEARER_HEADER}.
+ * - `scheme` — the scheme prefix stripped before verification (case-
+ *   insensitive); defaults to {@link DEFAULT_BEARER_SCHEME}. An empty string
+ *   means the whole header value is the raw token.
+ */
+export declare interface BearerOptions {
+    readonly secret: TokenSecret;
+    readonly header?: string;
+    readonly scheme?: string;
+}
+
+/**
+ * The bearer-authentication state slice `createBearer` stashes on
+ * `context.state` once a token verifies.
+ *
+ * @remarks
+ * `token` is optional-mutable: absent until `createBearer` runs, then
+ * written in place — the pattern every stateful battery's slice follows so a
+ * consumer intersects only the slices it mounts into its own `TState`.
+ */
+export declare interface BearerState {
+    token?: string;
+}
+
+/**
+ * Options for `createBoundary` — the outermost error-rendering battery.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `expose` — when `true`, a non-`HTTPError` throw's `error.message` is
+ *   surfaced in the 500 body instead of a generic message. Defaults to
+ *   `false` (nothing leaks).
+ * - `report` — an optional fire-and-forget sink invoked with every caught
+ *   error; its own throw is swallowed and can never alter the response.
+ */
+export declare interface BoundaryOptions {
+    readonly expose?: boolean;
+    readonly report?: (error: unknown) => void;
+}
+
+/**
+ * A parsed client-info fact for {@link ClientInfo} — a leaf shaping helper
+ * `createForwarded` uses to build its stashed slice.
+ *
+ * @param ip - The resolved client IP, if any
+ * @returns The {@link ClientInfo} slice value
+ *
+ * @example
+ * ```ts
+ * buildClientInfo('203.0.113.7') // { ip: '203.0.113.7' }
+ * ```
+ */
+export declare function buildClientInfo(ip: string | undefined): ClientInfo;
+
+/**
+ * Build the draft `RateLimit` structured header field (ruling I) — emitted
+ * only when `createLimiter`'s `policy` option is `true`.
+ *
+ * @param remaining - The requests still admitted this window
+ * @param resetAt - The window reset instant (same clock unit as `now`)
+ * @param now - The current instant
+ * @returns The `RateLimit` header value
+ *
+ * @example
+ * ```ts
+ * buildRateLimitField(4, 1_500, 1_000) // '"default";r=4;t=1'
+ * ```
+ */
+export declare function buildRateLimitField(remaining: number, resetAt: number, now: number): string;
+
+/**
+ * Build the draft `RateLimit-Policy` structured header field (ruling I) —
+ * emitted only when `createLimiter`'s `policy` option is `true`.
+ *
+ * @param max - The window's admitted request count
+ * @param window - The window length in milliseconds
+ * @returns The `RateLimit-Policy` header value
+ *
+ * @example
+ * ```ts
+ * buildRateLimitPolicyField(10, 60_000) // '"default";q=10;w=60'
+ * ```
+ */
+export declare function buildRateLimitPolicyField(max: number, window: number): string;
+
+/**
+ * Build the `Retry-After` header value — whole seconds until a window reset,
+ * floored at a minimum of `1` (ruling I).
+ *
+ * @param resetAt - The window reset instant (same clock unit as `now`)
+ * @param now - The current instant
+ * @returns The `Retry-After` value in whole seconds, minimum `1`
+ *
+ * @example
+ * ```ts
+ * buildRetryAfter(1_500, 1_000) // '1'
+ * ```
+ */
+export declare function buildRetryAfter(resetAt: number, now: number): string;
+
+/**
+ * The resolved client connection facts `createForwarded` stashes.
+ *
+ * @remarks
+ * `ip` is the first untrusted address walking `X-Forwarded-For` /
+ * `Forwarded` right-to-left past the configured trusted hops, falling back
+ * to the socket peer when no proxy hop qualifies.
+ */
+export declare interface ClientInfo {
+    readonly ip?: string;
+}
+
+/**
+ * The client-facts state slice `createForwarded` stashes.
+ */
+export declare interface ClientState {
+    client?: ClientInfo;
+}
+
+/**
+ * Options for `createCompression` — response-body compression.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `threshold` — the minimum buffered body size (bytes) worth compressing;
+ *   defaults to {@link DEFAULT_COMPRESSION_THRESHOLD}.
+ * - `encodings` — the codings offered, in preference order, intersected at
+ *   CONSTRUCTION with what the runtime's `CompressionStream` actually
+ *   supports; defaults to {@link DEFAULT_COMPRESSION_ENCODINGS}.
+ * - `filter` — an optional per-response opt-out predicate (the BREACH
+ *   posture escape hatch); a response the predicate declines is never
+ *   buffered or compressed. Defaults to always allowing.
+ */
+export declare interface CompressionOptions {
+    readonly threshold?: number;
+    readonly encodings?: readonly Encoding[];
+    readonly filter?: (request: Request, response: Response) => boolean;
+}
+
+/**
+ * The shared negotiate → skip → threshold → compress → header-set skeleton
+ * both faces' `createCompression` batteries compose — response-body
+ * compression over a caller-supplied set of feature-detected codings.
+ *
+ * @remarks
+ * Decision order: {@link isBufferingIneligible} → `options.filter` → stamp
+ * `Vary: Accept-Encoding` (every negotiation-eligible response carries it,
+ * even when a later skip declines to compress) → `negotiateEncoding` over
+ * `options.encodings` → {@link isCompressionNegotiated} → `isCompressibleType`
+ * on `Content-Type` → a fast skip when the response already carries a
+ * numeric `Content-Length` BELOW `options.threshold` (avoids buffering a
+ * body known too small to be worth compressing) → buffer via
+ * `response.arrayBuffer()` → a threshold passthrough when the buffered size
+ * is still below `options.threshold` → `options.compress` → set
+ * `Content-Encoding` and a fresh `Content-Length` via {@link rebuildResponse}.
+ * Returns `response` unchanged (aside from the `Vary` stamp) on any skip.
+ *
+ * @param request - The inbound `Request` (read for `Accept-Encoding`)
+ * @param context - The `MiddlewareContext` (read for `context.method`)
+ * @param response - The downstream `Response` to consider compressing
+ * @param options - The threshold, optional filter, offered encodings, and the runtime's `compress` primitive
+ * @returns The original `response` when skipped, or a new compressed `Response`
+ *
+ * @example
+ * ```ts
+ * await compressResponse(request, context, response, {
+ * 	threshold: 1024,
+ * 	encodings: ['gzip'],
+ * 	compress: async (bytes, encoding) => gzip(bytes),
+ * })
+ * ```
+ */
+export declare function compressResponse(request: Request, context: MiddlewareContext<unknown>, response: Response, options: {
+    readonly threshold: number;
+    readonly filter?: (request: Request, response: Response) => boolean;
+    readonly encodings: readonly Encoding[];
+    readonly compress: (bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>) => Promise<Uint8Array<ArrayBuffer>>;
+}): Promise<Response>;
+
+/**
+ * The connection-facts state slice `createLimiter`'s default key derivation
+ * falls back to when neither {@link BearerState} nor {@link ClientState} is
+ * present — the raw socket peer surfaced on `context.state` by the server's
+ * `state` option.
+ */
+export declare interface ConnectionState {
+    readonly connection?: ConnectionInfo;
+}
+
+/**
+ * Options for `createCookieTransport` — the signed-cookie {@link SessionTransport}.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `name` — the cookie name; defaults to {@link DEFAULT_SESSION_COOKIE}.
+ * - `secret` — the {@link TokenSecret} the session id is signed with (`signToken`).
+ * - `cookie` — extra {@link CookieOptions} attributes; `Max-Age` is derived
+ *   from `SessionOptions.ttl` unless overridden here.
+ */
+export declare interface CookieTransportOptions {
+    readonly name?: string;
+    readonly secret: TokenSecret;
+    readonly cookie?: CookieOptions;
+}
+
+/**
+ * Options for `createCors` — Cross-Origin Resource Sharing.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `origin` — the allowed origin(s): `'*'` (default), a single origin
+ *   string, or an allow-list `readonly string[]` (reflects the request
+ *   `Origin` when it matches, and merges `Vary: Origin`). The literal
+ *   `Origin: null` is never reflected even when `'null'` is allow-listed.
+ * - `methods` — the methods advertised on a preflight; defaults to {@link DEFAULT_CORS_METHODS}.
+ * - `headers` — the headers advertised on a preflight; defaults to {@link DEFAULT_CORS_HEADERS}.
+ */
+export declare interface CorsOptions {
+    readonly origin?: string | readonly string[];
+    readonly methods?: readonly string[];
+    readonly headers?: readonly string[];
+}
+
+/**
+ * Bearer-token authentication battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}
+ * @param options - See {@link BearerOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ * @throws {HTTPError} `401` when the token is missing, invalid, or expired
+ *
+ * @example
+ * ```ts
+ * const bearer = createBearer({ secret: 'shh' })
+ * ```
+ */
+export declare function createBearer<TState extends BearerState>(options: BearerOptions): MiddlewareHandler<TState>;
+
+/**
+ * The body-driving battery — eagerly awaits the cached `context.body()` so
+ * its throws (or a malformed-JSON `undefined`) surface before the handler runs.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {HTTPError} `400` when the request declares `application/json` and the body resolves `undefined`
+ *
+ * @remarks
+ * The shipped `MiddlewareContext.body()` is a parameterless, server-owned
+ * cache (`ServerOptions.limit` governs its size cap) — this battery carries
+ * no `limit`/`decompression` options (a deliberate break from the deleted old
+ * `createBodyParser` surface, which configured them itself).
+ *
+ * @example
+ * ```ts
+ * const body = createBody()
+ * ```
+ */
+export declare function createBody<TState>(): MiddlewareHandler<TState>;
+
+/**
+ * The outermost error-rendering battery — catches a downstream throw and
+ * renders it as a `Response`.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link BoundaryOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When `options.expose` or `options.report` is malformed
+ *
+ * @example
+ * ```ts
+ * const boundary = createBoundary({ expose: false })
+ * ```
+ */
+export declare function createBoundary<TState>(options?: BoundaryOptions): MiddlewareHandler<TState>;
+
+/**
+ * Response-body compression — negotiates and compresses a buffered response
+ * body over the runtime's feature-detected `CompressionStream` codings.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link CompressionOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When `options.threshold` or `options.filter` is malformed
+ *
+ * @example
+ * ```ts
+ * const compression = createCompression({ threshold: 1024 })
+ * ```
+ */
+export declare function createCompression<TState>(options?: CompressionOptions): MiddlewareHandler<TState>;
+
+/**
+ * Create a signed-cookie {@link SessionTransport} — the session id travels as
+ * a `signToken`-signed cookie value.
+ *
+ * @param options - See {@link CookieTransportOptions}
+ * @returns A {@link SessionTransport}
+ * @throws {TypeError} When `options.secret` or `options.name` is malformed
+ *
+ * @example
+ * ```ts
+ * const transport = createCookieTransport({ secret: 'shh' })
+ * ```
+ */
+export declare function createCookieTransport(options: CookieTransportOptions): SessionTransport;
+
+/**
+ * Cross-Origin Resource Sharing battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link CorsOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ *
+ * @example
+ * ```ts
+ * const cors = createCors({ origin: ['https://app.example'] })
+ * ```
+ */
+export declare function createCors<TState>(options?: CorsOptions): MiddlewareHandler<TState>;
+
+/**
+ * Session-bound double-submit CSRF protection battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link CSRFState}, {@link SessionState}, and {@link ConnectionState}
+ * @param options - See {@link CSRFOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ * @throws {HTTPError} `403` when the submitted token is missing, mismatched, or bound to a different session
+ *
+ * @example
+ * ```ts
+ * const csrf = createCSRF({ secret: 'shh' })
+ * ```
+ */
+export declare function createCSRF<TState extends CSRFState & SessionState & ConnectionState>(options: CSRFOptions): MiddlewareHandler<TState>;
+
+/**
+ * The application-level per-request deadline battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link DeadlineOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When `options.ms` or `options.status` is malformed
+ *
+ * @remarks
+ * MUST sit OUTSIDE `createBody` in the chain — it reconstructs the inbound
+ * `Request` (to link its `signal` to the deadline `signal`), which throws if
+ * the body was already consumed upstream (e.g. by `createBody`'s cached read).
+ *
+ * @example
+ * ```ts
+ * const deadline = createDeadline({ ms: 5_000 })
+ * ```
+ */
+export declare function createDeadline<TState>(options: DeadlineOptions): MiddlewareHandler<TState>;
+
+/**
+ * Dynamic response `ETag` + conditional GET battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link ETagOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When `options.weak` is not a boolean
+ *
+ * @example
+ * ```ts
+ * const etag = createETag({ weak: true })
+ * ```
+ */
+export declare function createETag<TState>(options?: ETagOptions): MiddlewareHandler<TState>;
+
+/**
+ * The trusted-proxy client-IP resolver battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link ClientState} and {@link ConnectionState}
+ * @param options - See {@link ForwardedOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When neither or both of `proxies`/`trusted` are provided, or either is malformed
+ *
+ * @example
+ * ```ts
+ * const forwarded = createForwarded({ proxies: 1 })
+ * ```
+ */
+export declare function createForwarded<TState extends ClientState & ConnectionState>(options: ForwardedOptions): MiddlewareHandler<TState>;
+
+/**
+ * Create a bare-header {@link SessionTransport} — the session id travels
+ * verbatim in a request/response header.
+ *
+ * @param options - See {@link HeaderTransportOptions}
+ * @returns A {@link SessionTransport}
+ * @throws {TypeError} When `options.header` is malformed
+ *
+ * @example
+ * ```ts
+ * const transport = createHeaderTransport()
+ * ```
+ */
+export declare function createHeaderTransport(options?: HeaderTransportOptions): SessionTransport;
+
+/**
+ * Fixed-window rate-limiting battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}, {@link ClientState}, and {@link ConnectionState}
+ * @param options - See {@link LimiterOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ *
+ * @example
+ * ```ts
+ * const limiter = createLimiter({ max: 100, window: 60_000 })
+ * ```
+ */
+export declare function createLimiter<TState extends BearerState & ClientState & ConnectionState>(options: LimiterOptions<TState>): MiddlewareHandler<TState>;
+
+/**
+ * Create the default in-process {@link SessionStoreInterface} — a `Map`-backed
+ * store enforcing an idle timeout and an absolute lifetime.
+ *
+ * @typeParam S - The session data payload type
+ * @param options - See {@link MemorySessionStoreOptions}
+ * @returns A {@link SessionStoreInterface}
+ * @throws {TypeError} When `options.ttl` or `options.lifetime` is malformed
+ *
+ * @remarks
+ * The {@link Session} entity is the `create` option's default value factory
+ * for `createSession` and deliberately ships WITHOUT its own `create*`
+ * factory — the name `createSession` belongs to the battery, not this class.
+ *
+ * @example
+ * ```ts
+ * const store = createMemorySessionStore({ ttl: 60_000 })
+ * ```
+ */
+export declare function createMemorySessionStore<S>(options?: MemorySessionStoreOptions): SessionStoreInterface<S>;
+
+/**
+ * Security-headers + request-identifier battery.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link IdentifierState}
+ * @param options - See {@link SecurityOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ *
+ * @example
+ * ```ts
+ * const security = createSecurity({ hsts: true })
+ * ```
+ */
+export declare function createSecurity<TState extends IdentifierState>(options?: SecurityOptions): MiddlewareHandler<TState>;
+
+/**
+ * The generic session battery — resolves, mints, and persists a session
+ * across the request, with a mid-handler `regenerate`/`destroy` control handle.
+ *
+ * @typeParam S - The session entity type the store persists (must implement {@link SessionInterface})
+ * @typeParam TState - The consumer's opaque per-request state type, must carry {@link SessionState} and {@link ConnectionState}
+ * @param options - See {@link SessionOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When any option is malformed
+ * @throws {HTTPError} `404` when `require` is set and no session resolves or mints
+ *
+ * @example
+ * ```ts
+ * const session = createSession({ transport: createHeaderTransport() })
+ * ```
+ */
+export declare function createSession<S extends SessionInterface = SessionInterface, TState extends SessionState & ConnectionState = SessionState & ConnectionState>(options: SessionOptions<S, TState>): MiddlewareHandler<TState>;
+
+/**
+ * The access-log/timing seam — records one {@link TelemetryEntry} per request
+ * after the response settles.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param options - See {@link TelemetryOptions}
+ * @returns A `MiddlewareHandler<TState>`
+ * @throws {TypeError} When `options.record` is not a function
+ *
+ * @example
+ * ```ts
+ * const telemetry = createTelemetry({ record: (entry) => console.log(entry) })
+ * ```
+ */
+export declare function createTelemetry<TState>(options: TelemetryOptions): MiddlewareHandler<TState>;
+
+/**
+ * Options for `createCSRF` — session-bound double-submit CSRF protection.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `secret` — the {@link TokenSecret} the CSRF token is signed with.
+ * - `cookie` — the signed-cookie name; defaults to {@link DEFAULT_CSRF_COOKIE}.
+ * - `header` — the header a mutating request submits its token in; defaults
+ *   to {@link DEFAULT_CSRF_HEADER}.
+ * - `field` — the body field a mutating request may submit its token in
+ *   instead of the header (requires `createBody` ahead for form posts);
+ *   defaults to {@link DEFAULT_CSRF_FIELD}.
+ * - `safe` — the methods that mint instead of verify; defaults to
+ *   {@link DEFAULT_CSRF_SAFE_METHODS}.
+ */
+export declare interface CSRFOptions {
+    readonly secret: TokenSecret;
+    readonly cookie?: string;
+    readonly header?: string;
+    readonly field?: string;
+    readonly safe?: readonly string[];
+}
+
+/**
+ * The CSRF state slice `createCSRF` stashes — the raw token a safe-method
+ * response exposes for a subsequent mutating request to submit back.
+ */
+export declare interface CSRFState {
+    csrf?: string;
+}
+
+/**
+ * Options for `createDeadline` — the application-level per-request deadline.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `ms` — the deadline in milliseconds, armed via `@orkestrel/timeout` and
+ *   linked to the request's `signal` via `@orkestrel/abort`'s `linkSignal`.
+ * - `status` — the response status returned when the deadline fires before
+ *   the downstream chain settles; defaults to {@link DEFAULT_DEADLINE_STATUS}.
+ */
+export declare interface DeadlineOptions {
+    readonly ms: number;
+    readonly status?: number;
+}
+
+/** Default header `createBearer` reads the token from. */
+export declare const DEFAULT_BEARER_HEADER = "authorization";
+
+/** Default scheme prefix `createBearer` strips before verification. */
+export declare const DEFAULT_BEARER_SCHEME = "Bearer";
+
+/** Default `Origin-Agent-Cluster` value `createSecurity` sets. */
+export declare const DEFAULT_CLUSTER = "?1";
+
+/** Value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
+export declare const DEFAULT_COEP = "require-corp";
+
+/**
+ * Default content-codings `createCompression` offers, in preference order —
+ * intersected at construction with what the runtime's `CompressionStream`
+ * actually supports.
+ *
+ * @remarks
+ * The shipped `@orkestrel/server` peer's {@link Encoding} union is
+ * `'gzip' | 'deflate' | 'identity'` — it does not include `'br'` (see the
+ * deviation recorded against this constant in the build report). This
+ * default therefore offers every non-`identity` coding the peer's type
+ * admits; a node-face brotli variant, if one ships, extends this list there.
+ */
+export declare const DEFAULT_COMPRESSION_ENCODINGS: readonly Encoding[];
+
+/** Default minimum buffered body size (bytes) `createCompression` will compress. */
+export declare const DEFAULT_COMPRESSION_THRESHOLD = 1024;
+
+/** Default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+export declare const DEFAULT_COOP = "same-origin";
+
+/** Default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
+export declare const DEFAULT_CORP = "same-origin";
+
+/** Default headers `createCors` advertises on a preflight response. */
+export declare const DEFAULT_CORS_HEADERS: readonly string[];
+
+/** Default methods `createCors` advertises on a preflight response. */
+export declare const DEFAULT_CORS_METHODS: readonly string[];
+
+/**
+ * Default `Content-Security-Policy` value `createSecurity` sets — a custom
+ * `csp` option REPLACES this wholesale, never merges.
+ */
+export declare const DEFAULT_CSP = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'";
+
+/** Default signed-cookie name `createCSRF` writes the CSRF token under. */
+export declare const DEFAULT_CSRF_COOKIE = "csrf";
+
+/** Default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
+export declare const DEFAULT_CSRF_FIELD = "_csrf";
+
+/** Default header `createCSRF` reads a mutating request's submitted token from. */
+export declare const DEFAULT_CSRF_HEADER = "x-csrf-token";
+
+/** Default methods `createCSRF` treats as safe (mint instead of verify). */
+export declare const DEFAULT_CSRF_SAFE_METHODS: readonly string[];
+
+/** Default response status `createDeadline` returns when its deadline fires first. */
+export declare const DEFAULT_DEADLINE_STATUS = 503;
+
+/** Default `X-Frame-Options` value `createSecurity` sets. */
+export declare const DEFAULT_FRAME_OPTIONS = "DENY";
+
+/** Value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
+export declare const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
+
+/** Default header `createSecurity` mints/echoes a request identifier into. */
+export declare const DEFAULT_IDENTIFIER_HEADER = "x-request-id";
+
+/** Default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
+export declare const DEFAULT_LIMITER_CAPACITY = 10000;
+
+/** Default 429 body message `createLimiter` sends when a key is over budget. */
+export declare const DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
+
+/** Default `Permissions-Policy` value `createSecurity` sets. */
+export declare const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
+
+/** Default `Referrer-Policy` value `createSecurity` sets. */
+export declare const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
+
+/** Default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
+export declare const DEFAULT_SESSION_CAPACITY = 10000;
+
+/** Default cookie name `createCookieTransport` writes the signed session id under. */
+export declare const DEFAULT_SESSION_COOKIE = "session";
+
+/** Default header `createHeaderTransport` carries the session id in. */
+export declare const DEFAULT_SESSION_HEADER = "session-id";
+
+/**
+ * Feature-detect which of `candidates` the runtime's `CompressionStream`
+ * actually supports — `createCompression`'s construction-time intersection
+ * (ruling J).
+ *
+ * @remarks
+ * Probes each candidate with `new CompressionStream(candidate)` inside a
+ * `try`/`catch`; a coding the runtime rejects is dropped silently. `identity`
+ * is never probed (it has no `CompressionStream` coding and is always
+ * implicitly acceptable to negotiation).
+ *
+ * @param candidates - The codings to probe, in preference order
+ * @returns The subset of `candidates` the runtime's `CompressionStream` supports, in order
+ *
+ * @example
+ * ```ts
+ * detectEncodings(['gzip', 'deflate']) // ['gzip', 'deflate'] on a runtime with both
+ * ```
+ */
+export declare function detectEncodings(candidates: readonly Encoding[]): readonly Encoding[];
+
+/**
+ * Constant-time string equality — `createCSRF`'s double-submit token
+ * comparison, avoiding a timing oracle on the submitted-vs-cookie match.
+ *
+ * @remarks
+ * Length-guarded XOR-accumulate over char codes: a length mismatch short
+ * circuits (safe — the lengths of two independently-generated tokens are
+ * not a useful timing signal), but once lengths match every character is
+ * compared with no early return, so a per-character mismatch never affects
+ * how long the comparison takes.
+ *
+ * @param a - The first string
+ * @param b - The second string
+ * @returns `true` when `a` and `b` are exactly equal
+ *
+ * @example
+ * ```ts
+ * equalsConstantTime('abc', 'abc') // true
+ * equalsConstantTime('abc', 'abd') // false
+ * ```
+ */
+export declare function equalsConstantTime(a: string, b: string): boolean;
+
+/**
+ * Options for `createETag` — dynamic response ETag + conditional GET.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `weak` — mint a weak `W/"…"` ETag (default `true`) or a strong `"…"` one
+ *   (`false`).
+ */
+export declare interface ETagOptions {
+    readonly weak?: boolean;
+}
+
+/**
+ * Options for `createForwarded` — the trusted-proxy client-IP resolver.
+ *
+ * @param options - See fields below
+ * @remarks
+ * Construction requires EXACTLY ONE of the two forms (a `TypeError` guards
+ * both-set and neither-set):
+ * - `proxies` — trust exactly this many hops from the right of
+ *   `X-Forwarded-For` / `Forwarded`.
+ * - `trusted` — trust every hop matching one of these CIDR entries.
+ */
+export declare type ForwardedOptions = {
+    readonly proxies: number;
+} | {
+    readonly trusted: readonly string[];
+};
+
+/**
+ * Options for `createHeaderTransport` — the bare-header {@link SessionTransport}.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `header` — the header carrying the session id; defaults to
+ *   {@link DEFAULT_SESSION_HEADER}.
+ */
+export declare interface HeaderTransportOptions {
+    readonly header?: string;
+}
+
+/**
+ * The request-identifier state slice `createSecurity` stashes when its
+ * `identifier` option is enabled.
+ */
+export declare interface IdentifierState {
+    identifier?: string;
+}
+
+/**
+ * Whether a response is eligible for the compression/ETag buffering pipeline
+ * (ruling J) — the shared cheap-skip predicate both batteries apply before
+ * ever touching `response.arrayBuffer()`.
+ *
+ * @remarks
+ * Skips a `HEAD` request, a `204`/`304` or otherwise bodyless response, an
+ * `event-stream` response (SSE — buffering would hang the connection), and a
+ * response that already carries the header the caller is about to set
+ * (`skipHeader`, e.g. `Content-Encoding` for compression, `ETag` for the
+ * ETag battery).
+ *
+ * @param method - The request's HTTP method
+ * @param response - The candidate response
+ * @param skipHeader - The response header whose presence means "already handled"
+ * @returns `true` when the response should be left untouched
+ *
+ * @example
+ * ```ts
+ * isBufferingIneligible('GET', new Response(null, { status: 204 }), 'content-encoding') // true
+ * ```
+ */
+export declare function isBufferingIneligible(method: string, response: Response, skipHeader: string): boolean;
+
+/**
+ * Whether a negotiated `Accept-Encoding` outcome is worth acting on —
+ * `createCompression`'s negotiation-eligibility half of ruling J's skip list.
+ *
+ * @param encoding - The negotiated coding, or `undefined` when negotiation failed
+ * @returns `true` when `encoding` names an actionable, non-`identity` coding
+ *
+ * @example
+ * ```ts
+ * isCompressionNegotiated('gzip') // true
+ * isCompressionNegotiated(undefined) // false
+ * ```
+ */
+export declare function isCompressionNegotiated(encoding: Encoding | undefined): encoding is Exclude<Encoding, 'identity'>;
+
+/**
+ * Determine whether a value implements {@link MultipartBody} — a total
+ * structural guard (§14): `files` keyed by field name to arrays of
+ * {@link MultipartFile}, and a `fields` string record.
+ *
+ * @param value - The candidate value
+ * @returns `true` when `value` is shaped like a {@link MultipartBody}
+ *
+ * @example
+ * ```ts
+ * isMultipartBody({ files: {}, fields: { name: 'a' } }) // true
+ * ```
+ */
+export declare function isMultipartBody(value: unknown): value is MultipartBody;
+
+/**
+ * Determine whether a value is one staged {@link MultipartFile} record — a
+ * total structural guard (§14) checking every required field's shape.
+ *
+ * @param value - The candidate value
+ * @returns `true` when `value` is shaped like a {@link MultipartFile}
+ */
+export declare function isMultipartFile(value: unknown): value is MultipartFile;
+
+/**
+ * Determine whether a request is a CORS PREFLIGHT — an `OPTIONS` request
+ * carrying an `Access-Control-Request-Method` header.
+ *
+ * @param method - The request's HTTP method
+ * @param headers - The request's `Headers`
+ * @returns `true` when the request is a CORS preflight `createCors` must answer
+ *
+ * @example
+ * ```ts
+ * isPreflight('OPTIONS', new Headers({ 'access-control-request-method': 'POST' })) // true
+ * ```
+ */
+export declare function isPreflight(method: string, headers: Headers): boolean;
+
+/**
+ * Determine whether a value implements {@link SessionInterface} — a total
+ * structural guard (§14): an `id` string plus a `data` `Map`.
+ *
+ * @param value - The candidate value
+ * @returns `true` when `value` is shaped like a {@link SessionInterface}
+ *
+ * @example
+ * ```ts
+ * isSession({ id: 'a', data: new Map() }) // true
+ * ```
+ */
+export declare function isSession(value: unknown): value is SessionInterface;
+
+/**
+ * Determine whether a value implements {@link SessionControlInterface} — a
+ * total structural guard (§14): callable `regenerate` and `destroy`.
+ *
+ * @param value - The candidate value
+ * @returns `true` when `value` is shaped like a {@link SessionControlInterface}
+ *
+ * @example
+ * ```ts
+ * isSessionControl({ regenerate() {}, destroy() {} }) // true
+ * ```
+ */
+export declare function isSessionControl(value: unknown): value is SessionControlInterface;
+
+/**
+ * Options for `createLimiter` — fixed-window rate limiting.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type `key` reads
+ * @param options - See fields below
+ * @remarks
+ * - `max` — the number of requests admitted per key per `window`.
+ * - `window` — the window length in milliseconds.
+ * - `capacity` — the maximum number of distinct keys tracked before the
+ *   least-recently-used key is evicted (true LRU — every access, not just
+ *   insertion, refreshes recency); defaults to {@link DEFAULT_LIMITER_CAPACITY}.
+ * - `key` — derives the bucket key from the request; defaults to the
+ *   bearer-token-then-client-IP idiom (see the battery's guide).
+ * - `message` — the 429 body message; defaults to {@link DEFAULT_LIMITER_MESSAGE}.
+ * - `clock` — the injected time source for all window math; defaults to `Date.now`.
+ * - `policy` — when `true`, also emits the draft `RateLimit`/`RateLimit-Policy`
+ *   structured header fields; defaults to `false`. `Retry-After` always ships.
+ * - `evict` — invoked with a bucket's key when it is evicted for capacity;
+ *   its own throw is swallowed and can never fail the request. It is a
+ *   notification sink only — it must never call back into the limiter
+ *   (no re-entrant reads/writes); mutations during eviction are unsupported.
+ */
+export declare interface LimiterOptions<TState = unknown> {
+    readonly max: number;
+    readonly window: number;
+    readonly capacity?: number;
+    readonly key?: (context: MiddlewareContext<TState>) => string;
+    readonly message?: string;
+    readonly clock?: () => number;
+    readonly policy?: boolean;
+    readonly evict?: (key: string) => void;
+}
+
+/**
+ * Whether a candidate address is a bare (non-CIDR) trusted-hop match — an
+ * exact string match, or a simple prefix-CIDR match for IPv4 (`/8`–`/32`).
+ * An IPv6 entry matches by exact string only — there is no IPv6 CIDR
+ * support.
+ *
+ * @remarks
+ * Supports exact addresses and dotted-decimal IPv4 CIDR (`10.0.0.0/8`
+ * through `/32`) verbatim. An IPv6 entry is matched by exact string only
+ * (no CIDR expansion) — documented as the supported subset; `createForwarded`
+ * never claims full CIDR generality beyond IPv4.
+ *
+ * @remarks
+ * An IPv6 `trusted` roster entry is compared as an EXACT string — it must be
+ * supplied in canonical form (no zero-compression normalization, no case
+ * folding) by the caller; this function performs no IPv6 normalization of
+ * its own.
+ *
+ * @param address - The candidate hop address
+ * @param entry - One `trusted` roster entry — an exact address or an IPv4 CIDR
+ * @returns `true` when `address` is covered by `entry`
+ *
+ * @example
+ * ```ts
+ * matchesTrustedEntry('10.1.2.3', '10.0.0.0/8') // true
+ * matchesTrustedEntry('192.168.1.1', '10.0.0.0/8') // false
+ * ```
+ */
+export declare function matchesTrustedEntry(address: string, entry: string): boolean;
+
+/**
+ * The default in-process {@link SessionStoreInterface} — a `Map`-backed store
+ * enforcing both an idle timeout and an absolute lifetime, with lazy
+ * (read-time) eviction, a bounded capacity, and no background timers.
+ *
+ * @typeParam S - The session data payload type
+ *
+ * @remarks
+ * `get` evicts a session whose idle time (`now - lastSeen >= ttl`) or
+ * absolute lifetime (`now - createdAt >= lifetime`) has elapsed — the
+ * lifetime check fires EVEN IF the session was continuously touched, since
+ * `createdAt` is stamped once at the first `set` and preserved across every
+ * later re-`set` of the same id. A live read touches `lastSeen`. `delete` of
+ * an absent id is a no-op.
+ *
+ * Capacity is enforced as least-recently-used **by last write**: `set`
+ * refreshes an id's recency (deleting then re-inserting so the Map's
+ * iteration tail is the most-recently-written id). Inserting a brand-new id
+ * once the store is at `capacity` first prunes expired entries; if the store
+ * is still full, the least-recently-written id (the Map's head) is evicted.
+ * `options.evict` — when provided — is invoked (throw-isolated) with the id
+ * on every eviction the store's own policy performs (a capacity eviction or
+ * an expired-entry prune), but never for an explicit `delete`.
+ *
+ * @example
+ * ```ts
+ * const store = new MemorySessionStore({ ttl: 60_000, lifetime: 3_600_000 })
+ * await store.set('abc', { userId: 'u_1' }, Date.now())
+ * ```
+ */
+export declare class MemorySessionStore<S> implements SessionStoreInterface<S> {
+    #private;
+    constructor(options?: MemorySessionStoreOptions);
+    get(id: string, now: number): Promise<S | undefined>;
+    set(id: string, session: S, now: number): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Options for `createMemorySessionStore` — the default in-process {@link SessionStoreInterface}.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `ttl` — the idle timeout in milliseconds (lazy eviction on `get`).
+ * - `lifetime` — the absolute lifetime in milliseconds from first `set`
+ *   (evicts even a continuously-touched session).
+ * - `capacity` — the maximum number of distinct session ids tracked before
+ *   the least-recently-written id is evicted (LRU by last write — every
+ *   `set` refreshes an id's recency); defaults to {@link DEFAULT_SESSION_CAPACITY}.
+ * - `evict` — invoked with a session id when it is evicted by the store's
+ *   own policy (a capacity eviction or an expired-entry prune) — never for
+ *   an explicit `delete`. Its own throw is swallowed. It is a notification
+ *   sink only — it must never call back into the store (no re-entrant
+ *   `get`/`set`); mutations during eviction are unsupported.
+ */
+export declare interface MemorySessionStoreOptions {
+    readonly ttl?: number;
+    readonly lifetime?: number;
+    readonly capacity?: number;
+    readonly evict?: (id: string) => void;
+}
+
+/**
+ * The parsed multipart request body `createMultipart` stashes — files keyed
+ * by their field name, plus every plain text field.
+ */
+export declare interface MultipartBody {
+    readonly files: Readonly<Record<string, readonly MultipartFile[]>>;
+    readonly fields: Readonly<Record<string, string>>;
+}
+
+/**
+ * One staged multipart upload's public record — the shape the node-face
+ * `createMultipart` battery (`@orkestrel/middleware/server`) produces per
+ * uploaded file.
+ *
+ * @remarks
+ * Declared here rather than in the node-bound server surface so the
+ * fetch/string-pure {@link MultipartState} slice — referenced by any
+ * environment narrowing `context.state` — never depends on the node face.
+ * The server's concrete `UploadedFileInterface` is structurally compatible
+ * with this shape.
+ */
+export declare interface MultipartFile {
+    readonly field: string;
+    readonly name: string;
+    readonly size: number;
+    readonly mime: string;
+    readonly validated: boolean;
+    readonly status: string;
+    readonly path: string;
+}
+
+/**
+ * The multipart state slice `createMultipart` stashes.
+ *
+ * @remarks
+ * Present only once `createMultipart` has fully parsed a multipart request.
+ * After it runs, `context.body()` must not be called for that request — the
+ * multipart battery consumes `request.body` as a stream, so the seam's
+ * cached body has nothing left to read.
+ */
+export declare interface MultipartState {
+    multipart?: MultipartBody;
+}
+
+/**
+ * Rebuild a `Response` around a replacement body while preserving its
+ * status/statusText — the buffered-response reconstruction shared by the
+ * compression and ETag batteries after they have consumed
+ * `response.arrayBuffer()`.
+ *
+ * @param body - The replacement body (already-buffered bytes, or `null`)
+ * @param response - The original response whose status/statusText/headers are preserved
+ * @param headers - The headers to apply; defaults to a fresh copy of `response.headers`
+ * @returns A new `Response` carrying `body` with `response`'s status/statusText
+ *
+ * @example
+ * ```ts
+ * rebuildResponse(bytes, response) // same status/statusText, response's headers copied
+ * rebuildResponse(bytes, response, headers) // explicit replacement headers
+ * ```
+ */
+export declare function rebuildResponse(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]): Response;
+
+/**
+ * Walk `X-Forwarded-For` right-to-left and resolve the first UNTRUSTED hop
+ * address — `createForwarded`'s core algorithm.
+ *
+ * @remarks
+ * Parses `X-Forwarded-For` only. With `proxies` set, trusts exactly that
+ * many hops counted from the right (the closest to this server) and returns
+ * the next one left of them; with `trusted` set, trusts every CONSECUTIVE
+ * hop from the right that matches one of the roster
+ * ({@link matchesTrustedEntry}) and returns the first hop that does not. If
+ * the rightmost hop (the immediate sender) does not match the roster, the
+ * whole header is untrustworthy and this returns `undefined` rather than
+ * returning any client-supplied hop value. When every hop is trusted, or the
+ * header is absent/empty, returns `undefined` (the caller falls back to the
+ * socket peer).
+ *
+ * @param header - The raw `X-Forwarded-For` header value (comma-separated hops), if present
+ * @param trust - Either a trusted hop COUNT or a `trusted` CIDR/exact roster
+ * @returns The first untrusted hop address, or `undefined` when none qualifies
+ *
+ * @example
+ * ```ts
+ * resolveForwardedFor('203.0.113.7, 10.0.0.1', { proxies: 1 }) // '203.0.113.7'
+ * ```
+ */
+export declare function resolveForwardedFor(header: string | undefined, trust: {
+    readonly proxies: number;
+} | {
+    readonly trusted: readonly string[];
+}): string | undefined;
+
+/**
+ * Derive `createLimiter`'s default rate-limit bucket key from a request's
+ * resolved identity facts.
+ *
+ * @remarks
+ * Prefers a verified bearer token ({@link BearerState.token}) as
+ * `token:<value>`; else a resolved client IP ({@link ClientState.client.ip},
+ * set when `createForwarded` is mounted) or the raw socket peer
+ * ({@link ConnectionState.connection.ip}) collapsed via `clientRateKey`
+ * (IPv6 to its `/64` network) as `ip:<key>`; else the literal `ip:unknown`.
+ * Never reads `X-Forwarded-For` itself — that trust decision belongs solely
+ * to `createForwarded`.
+ *
+ * @param state - The slices `createLimiter`'s default key may read
+ * @returns The bucket key for the request
+ *
+ * @example
+ * ```ts
+ * resolveKey({ token: 'abc' }) // 'token:abc'
+ * resolveKey({ client: { ip: '2001:db8::1' } }) // 'ip:2001:db8:0:0::/64'
+ * ```
+ */
+export declare function resolveKey(state: BearerState & ClientState & ConnectionState): string;
+
+/**
+ * Resolve an opt-in, value-bearing security header — `string | boolean`
+ * (default OFF, `true` uses the secure default), the shape `createSecurity`'s
+ * `coep`/`hsts` options use, distinct from the plain value-or-`false` shape
+ * `resolveSecurityHeader` (the peer substrate) handles.
+ *
+ * @param value - The option value — a `string` override, `true` for the secure default, or `false`/`undefined` to omit
+ * @param fallback - The secure-default value used when `value` is `true`
+ * @returns The header value to set, or `undefined` to omit the header
+ *
+ * @example
+ * ```ts
+ * resolveOptInHeader(true, 'require-corp') // 'require-corp'
+ * resolveOptInHeader(undefined, 'require-corp') // undefined — omitted
+ * ```
+ */
+export declare function resolveOptInHeader(value: string | boolean | undefined, fallback: string): string | undefined;
+
+/**
+ * `createSecurity`'s `identifier` sub-option — request-id minting/echo
+ * policy, or `false` to disable the feature entirely.
+ *
+ * @remarks
+ * - `trust` — when `true`, an incoming `X-Request-ID` that passes {@link
+ *   import('@orkestrel/server').isValidRequestId} is echoed back instead of
+ *   replaced by a fresh mint. Defaults to `false` (always mint).
+ */
+export declare type SecurityIdentifierOptions = {
+    readonly trust?: boolean;
+} | false;
+
+/**
+ * Options for `createSecurity` — the security-headers + request-id battery.
+ *
+ * @param options - See fields below
+ * @remarks
+ * Every header option is `string | false` (a custom value replaces the
+ * default wholesale, `false` omits the header) unless noted; unset uses the
+ * documented default. `X-Content-Type-Options: nosniff` is unconditional and
+ * has no option.
+ * - `frame` — `X-Frame-Options`; `'DENY' | 'SAMEORIGIN' | false`, default `'DENY'`.
+ * - `csp` — `Content-Security-Policy`; default {@link DEFAULT_CSP}.
+ * - `referrer` — `Referrer-Policy`; default {@link DEFAULT_REFERRER_POLICY}.
+ * - `permissions` — `Permissions-Policy`; default {@link DEFAULT_PERMISSIONS_POLICY}.
+ * - `coop` — `Cross-Origin-Opener-Policy`; default {@link DEFAULT_COOP}.
+ * - `corp` — `Cross-Origin-Resource-Policy`; default {@link DEFAULT_CORP}.
+ * - `cluster` — `Origin-Agent-Cluster`; default {@link DEFAULT_CLUSTER}.
+ * - `coep` — `Cross-Origin-Embedder-Policy`; `string | boolean`, OFF by
+ *   default (opt-in, breaks cross-origin subresources); `true` → {@link DEFAULT_COEP}.
+ * - `hsts` — `Strict-Transport-Security`; `string | boolean`, OFF by default
+ *   (opt-in, destructive if misconfigured); `true` → {@link DEFAULT_HSTS}.
+ * - `identifier` — {@link SecurityIdentifierOptions}; ON by default (mints
+ *   and stashes {@link IdentifierState}).
+ */
+export declare interface SecurityOptions {
+    readonly frame?: 'DENY' | 'SAMEORIGIN' | false;
+    readonly csp?: string | false;
+    readonly referrer?: string | false;
+    readonly permissions?: string | false;
+    readonly coop?: string | false;
+    readonly corp?: string | false;
+    readonly cluster?: string | false;
+    readonly coep?: string | boolean;
+    readonly hsts?: string | boolean;
+    readonly identifier?: SecurityIdentifierOptions;
+}
+
+/**
+ * A server-managed session's default entity — the `create` option's default
+ * value factory for `createSession` (ruling G: `Session` ships WITHOUT a
+ * `createSession` factory of its own, since that name belongs to the
+ * battery).
+ *
+ * @remarks
+ * `data` is a live, mutable `Map` a handler reads/writes directly;
+ * `createSession` persists it to the configured store on the way out.
+ *
+ * @example
+ * ```ts
+ * const session = new Session('abc123')
+ * session.data.set('userId', 'u_1')
+ * ```
+ */
+export declare class Session implements SessionInterface {
+    readonly id: string;
+    readonly data: Map<string, unknown>;
+    constructor(id: string);
+}
+
+/**
+ * The mid-handler control handle `createSession` stashes alongside the
+ * session itself — the OWASP anti-fixation / logout primitives.
+ *
+ * @remarks
+ * `regenerate` and `destroy` record intent SYNCHRONOUSLY when called; the
+ * store I/O and transport write happen after the handler's `next()` returns
+ * (`destroy` supersedes a prior `regenerate`). `regenerate` mints a new id,
+ * carries the session's `data` over, and invalidates the old id.
+ */
+export declare interface SessionControlInterface {
+    regenerate(): void;
+    destroy(): void;
+}
+
+/**
+ * A server-managed session's public surface — an id and its mutable data bag.
+ *
+ * @remarks
+ * `data` is a live `Map` a handler reads/writes directly; `createSession`
+ * persists it to the configured {@link SessionStoreInterface} on the way out.
+ */
+export declare interface SessionInterface {
+    readonly id: string;
+    readonly data: Map<string, unknown>;
+}
+
+/**
+ * Options for `createSession` — the generic session battery.
+ *
+ * @typeParam S - The session data payload type `create` produces
+ * @typeParam TState - The consumer's opaque per-request state type `mint` reads
+ * @param options - See fields below
+ * @remarks
+ * - `transport` — the {@link SessionTransport} (`createCookieTransport(...)`,
+ *   `createHeaderTransport(...)`, or a custom one).
+ * - `store` — the {@link SessionStoreInterface}; defaults to
+ *   `createMemorySessionStore({ ttl, lifetime, capacity, evict })`.
+ * - `ttl` — the idle timeout in milliseconds.
+ * - `lifetime` — the absolute session lifetime in milliseconds from mint.
+ * - `capacity` — the maximum number of distinct session ids the DEFAULT
+ *   memory store tracks before LRU eviction; ignored when `store` is
+ *   provided. Defaults to {@link DEFAULT_SESSION_CAPACITY}.
+ * - `evict` — invoked with a session id evicted by the DEFAULT memory
+ *   store's own policy; ignored when `store` is provided. It is a
+ *   notification sink only — it must never call back into the store
+ *   (no re-entrant `get`/`set`); mutations during eviction are unsupported.
+ * - `create` — builds a fresh session's public entity from a minted id;
+ *   defaults to `new Session(id)`.
+ * - `mint` — decides whether to auto-mint a session when none resolves;
+ *   defaults to always minting (auto-session).
+ * - `require` — when `true`, a request that resolves no session and does not
+ *   mint one renders a 404 instead of proceeding sessionless. Defaults to `false`.
+ * - `ends` — when `true`, a `DELETE` request carrying a valid session id
+ *   deletes the session and short-circuits with `204`. Defaults to `false`.
+ * - `clock` — the injected time source fed to the store; defaults to `Date.now`.
+ */
+export declare interface SessionOptions<S, TState = unknown> {
+    readonly transport: SessionTransport;
+    readonly store?: SessionStoreInterface<S>;
+    readonly ttl?: number;
+    readonly lifetime?: number;
+    readonly capacity?: number;
+    readonly evict?: (id: string) => void;
+    readonly create?: (id: string) => S;
+    readonly mint?: (context: MiddlewareContext<TState>) => boolean | Promise<boolean>;
+    readonly require?: boolean;
+    readonly ends?: boolean;
+    readonly clock?: () => number;
+}
+
+/**
+ * The session state slice `createSession` stashes.
+ *
+ * @remarks
+ * `session` is present whenever a request resolves or mints a session;
+ * `control` is present whenever `session` is (the handle to act on it).
+ */
+export declare interface SessionState {
+    session?: SessionInterface;
+    control?: SessionControlInterface;
+}
+
+/**
+ * The pluggable session persistence seam `createSession`'s `store` option
+ * implements — a point-access store (AGENTS §5) keyed by session id.
+ *
+ * @typeParam S - The session data payload type
+ * @remarks
+ * Every primitive is async and takes a trailing `now` clock reading (the
+ * same seam `createSession`'s `clock` option feeds) so a store can apply its
+ * own idle/absolute expiry against the caller's injected time rather than
+ * its own wall clock. `delete` of an absent id is a no-op, never throws.
+ */
+export declare interface SessionStoreInterface<S> {
+    get(id: string, now: number): Promise<S | undefined>;
+    set(id: string, session: S, now: number): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * The transport seam `createSession`'s `transport` option implements — how a
+ * session id travels to and from the client (a signed cookie, a header, …).
+ *
+ * @remarks
+ * `read` is total (a malformed/tampered credential resolves `undefined`,
+ * never throws). `write` and `clear` mutate the RETURNED `Response` on the
+ * way out — the returning onion makes "before send" automatic. `write` is
+ * called only when a session is freshly minted or regenerated; `clear` is
+ * called on `destroy()`. `write`'s `encrypted` flag is the request's resolved
+ * transport security (derived from `context.url.protocol`) so a cookie
+ * transport can resolve its own `Secure` attribute via `resolveSecure`
+ * without re-deriving connection facts itself.
+ */
+export declare interface SessionTransport {
+    read(request: Request): string | undefined | Promise<string | undefined>;
+    write(response: Response, id: string, encrypted: boolean): void | Promise<void>;
+    clear(response: Response): void;
+}
+
+/**
+ * One access-log-style entry `createTelemetry` records after a response
+ * settles — the access-log/timing seam's payload shape.
+ *
+ * @remarks
+ * - `method` — the request's HTTP verb.
+ * - `pathname` — the request URL's pathname.
+ * - `status` — the response's final status (the boundary-mapped status when
+ *   a downstream throw was rendered by `createBoundary`).
+ * - `duration` — the wall-clock time in milliseconds the whole onion took
+ *   beneath `createTelemetry`.
+ */
+export declare interface TelemetryEntry {
+    readonly method: string;
+    readonly pathname: string;
+    readonly status: number;
+    readonly duration: number;
+}
+
+/**
+ * Options for `createTelemetry` — the request timing/access-log seam.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `record` — invoked once per request with the settled {@link
+ *   TelemetryEntry}; its own throw is swallowed so a broken sink can never
+ *   fail the response.
+ */
+export declare interface TelemetryOptions {
+    readonly record: (entry: TelemetryEntry) => void;
+}
+
+/**
+ * Copy every entry of one session's `data` into another — the regenerate
+ * data-carry `createSession`'s `control.regenerate()` applies (ruling D).
+ *
+ * @param from - The source session whose `data` is copied
+ * @param to - The destination session `data` is copied into
+ *
+ * @example
+ * ```ts
+ * transferSessionData(oldSession, newSession)
+ * ```
+ */
+export declare function transferSessionData(from: SessionInterface, to: SessionInterface): void;
+
+export { }