@orkestrel/middleware 0.0.19 → 0.0.20

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

@@ -1,14 +1,14 @@
-import { Connection } from '@orkestrel/server';
-import { CookieOptions } from '@orkestrel/server';
-import { Encoding } from '@orkestrel/server';
-import { Guard } from '@orkestrel/contract';
+import type { Connection } from '@orkestrel/server';
+import type { CookieOptions } from '@orkestrel/server';
+import type { Encoding } from '@orkestrel/server';
+import type { Guard } from '@orkestrel/contract';
 import { JSONShape } from '@orkestrel/contract';
-import { MiddlewareContext } from '@orkestrel/server';
-import { MiddlewareHandler } from '@orkestrel/server';
+import type { MiddlewareContext } from '@orkestrel/server';
+import type { MiddlewareHandler } from '@orkestrel/server';
 import { NumberShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
-import { TableInterface } from '@orkestrel/database';
-import { TokenSecret } from '@orkestrel/server';
+import type { TableInterface } from '@orkestrel/database';
+import type { TokenSecret } from '@orkestrel/server';
 
 /**
  * Configures `createBearer` — bearer-token authentication.
@@ -18,9 +18,9 @@ import { TokenSecret } from '@orkestrel/server';
  *   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.
+ * - `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;
@@ -171,7 +171,7 @@ export declare function compressBytes(bytes: Uint8Array<ArrayBuffer>, encoding:
  * - `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
+ *   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
@@ -194,7 +194,7 @@ export declare interface CompressionOptions {
  * 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
+ * numeric `Content-Length` below `options.threshold` (avoids buffering a
  * body known too small to be worth compressing) → buffer through
  * `response.arrayBuffer()` → a threshold passthrough when the buffered size
  * is still below `options.threshold` → `options.compress` → set
@@ -282,7 +282,8 @@ export declare interface CorsOptions {
 }
 
 /**
- * Creates the bearer-token authentication battery.
+ * Creates the bearer-token authentication battery — reads the token from its header and
+ * verifies it with `verifyToken`.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}
  * @param options - See {@link BearerOptions}
@@ -310,7 +311,7 @@ export declare function createBearer<TState extends BearerState>(options: Bearer
  * The shipped `MiddlewareContext.body()` is a parameterless, server-owned
  * cache (`ServerOptions.limit` governs its size cap) — this battery carries
  * no `limit`/`decompression` options. `state.body` is
- * stashed from the SAME awaited call the 400 check reads — `context.body()`
+ * stashed from the same awaited call the 400 check reads — `context.body()`
  * is never invoked twice.
  *
  * @example
@@ -329,9 +330,20 @@ export declare function createBody<TState extends BodyState = BodyState>(): Midd
  * @returns A `MiddlewareHandler<TState>`
  * @throws {TypeError} When `options.expose` or `options.report` is malformed
  *
- * @example
+ * @example Mount a battery
  * ```ts
+ * import { createBoundary, createSecurity } from '@orkestrel/middleware'
+ * import type { IdentifierState } from '@orkestrel/middleware'
+ * import { compose } from '@orkestrel/server'
+ *
+ * interface State extends IdentifierState {}
+ *
  * const boundary = createBoundary({ expose: false })
+ * const security = createSecurity({ hsts: true })
+ *
+ * const handle = compose<State>([boundary, security], async (_request, context) => {
+ * 	return Response.json({ identifier: context.state.identifier })
+ * })
  * ```
  */
 export declare function createBoundary<TState>(options?: BoundaryOptions): MiddlewareHandler<TState>;
@@ -368,7 +380,8 @@ export declare function createCompression<TState>(options?: CompressionOptions):
 export declare function createCookieTransport(options: CookieTransportOptions): SessionTransportInterface;
 
 /**
- * Creates the Cross-Origin Resource Sharing battery.
+ * Creates the Cross-Origin Resource Sharing battery — answers a preflight itself, and
+ * reflects an allow-listed origin or serves the configured wildcard.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param options - See {@link CorsOptions}
@@ -433,7 +446,7 @@ export declare function createDatabaseSessionStore<S extends SessionInterface =
  * @throws {TypeError} When `options.ms` or `options.status` is malformed
  *
  * @remarks
- * MUST sit OUTSIDE `createBody` in the chain — it reconstructs the inbound
+ * Mount this battery 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 (for example by `createBody`'s cached read).
  *
@@ -445,7 +458,7 @@ export declare function createDatabaseSessionStore<S extends SessionInterface =
 export declare function createDeadline<TState>(options: DeadlineOptions): MiddlewareHandler<TState>;
 
 /**
- * Creates the dynamic response `ETag` + conditional GET battery.
+ * Creates the dynamic response `ETag` + conditional GET battery (RFC 7232).
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param options - See {@link ETagOptions}
@@ -460,7 +473,8 @@ export declare function createDeadline<TState>(options: DeadlineOptions): Middle
 export declare function createETag<TState>(options?: ETagOptions): MiddlewareHandler<TState>;
 
 /**
- * Creates the trusted-proxy client-IP resolver battery.
+ * Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past
+ * the hops its options declare trusted.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link ClientState} and {@link ConnectionState}
  * @param options - See {@link ForwardedOptions}
@@ -490,7 +504,8 @@ export declare function createForwarded<TState extends ClientState & ConnectionS
 export declare function createHeaderTransport(options?: HeaderTransportOptions): SessionTransportInterface;
 
 /**
- * Creates the fixed-window rate-limiting battery.
+ * Creates the fixed-window rate-limiting battery — checks a key's budget before
+ * consuming it, so one window admits exactly `max` requests.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link BearerState}, {@link ClientState}, and {@link ConnectionState}
  * @param options - See {@link LimiterOptions}
@@ -540,7 +555,8 @@ export declare function createMemorySessionStore<S extends SessionInterface>(opt
 export declare function createRestoredSession(value: unknown): Session | undefined;
 
 /**
- * Creates the security-headers + request-identifier battery.
+ * Creates the security-headers + request-identifier battery — sets each documented
+ * header default, and mints or echoes a request identifier.
  *
  * @typeParam TState - The consumer's opaque per-request state type, must carry {@link IdentifierState}
  * @param options - See {@link SecurityOptions}
@@ -638,7 +654,7 @@ export declare interface CSRFState {
  * {@link MemorySessionStore}. `delete` of an absent id is a no-op (the
  * table's `remove` contract).
  *
- * A malformed-snapshot or failed-guard `undefined` LEAVES the row in place —
+ * A malformed-snapshot or failed-guard `undefined` leaves the row in place —
  * unlike the expired path, which removes it. This is deliberate: a
  * caller-contextual guard may reject a session that is still perfectly
  * valid for another flow reading the same table (a differently-shaped `S`,
@@ -676,22 +692,22 @@ export declare interface DeadlineOptions {
     readonly status?: number;
 }
 
-/** Names the default header `createBearer` reads the token from. */
+/** Names `'authorization'`, the default header `createBearer` reads the token from. */
 export declare const DEFAULT_BEARER_HEADER = "authorization";
 
-/** Names the default scheme prefix `createBearer` strips before verification. */
+/** Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. */
 export declare const DEFAULT_BEARER_SCHEME = "Bearer";
 
-/** Holds the default `Origin-Agent-Cluster` value `createSecurity` sets. */
+/** Holds `'?1'`, the default `Origin-Agent-Cluster` value `createSecurity` sets. */
 export declare const DEFAULT_CLUSTER = "?1";
 
-/** Holds the value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
+/** Holds `'require-corp'`, the value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
 export declare const DEFAULT_COEP = "require-corp";
 
 /**
- * Lists the default content-codings `createCompression` offers, in preference order —
- * intersected at construction with what the runtime's `CompressionStream`
- * actually supports.
+ * Lists `['gzip', 'deflate']`, the 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
@@ -702,13 +718,13 @@ export declare const DEFAULT_COEP = "require-corp";
  */
 export declare const DEFAULT_COMPRESSION_ENCODINGS: readonly Encoding[];
 
-/** Holds the default minimum buffered body size (bytes) `createCompression` will compress. */
+/** Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. */
 export declare const DEFAULT_COMPRESSION_THRESHOLD = 1024;
 
-/** Holds the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+/** Holds `'same-origin'`, the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_COOP = "same-origin";
 
-/** Holds the default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
+/** Holds `'same-origin'`, the default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_CORP = "same-origin";
 
 /** Lists the default headers `createCors` advertises on a preflight response. */
@@ -718,54 +734,55 @@ export declare const DEFAULT_CORS_HEADERS: readonly string[];
 export declare const DEFAULT_CORS_METHODS: readonly string[];
 
 /**
- * Holds the default `Content-Security-Policy` value `createSecurity` sets — a custom
- * `csp` option REPLACES this wholesale, never merges.
+ * Holds `"default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'"`,
+ * the 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'";
 
-/** Names the default signed cookie `createCSRF` writes the CSRF token under. */
+/** Names `'csrf'`, the default signed cookie `createCSRF` writes the CSRF token under. */
 export declare const DEFAULT_CSRF_COOKIE = "csrf";
 
-/** Names the default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
+/** Names `'_csrf'`, the default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
 export declare const DEFAULT_CSRF_FIELD = "_csrf";
 
-/** Names the default header `createCSRF` reads a mutating request's submitted token from. */
+/** Names `'x-csrf-token'`, the default header `createCSRF` reads a mutating request's submitted token from. */
 export declare const DEFAULT_CSRF_HEADER = "x-csrf-token";
 
-/** Lists the default methods `createCSRF` treats as safe (mint instead of verify). */
+/** Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). */
 export declare const DEFAULT_CSRF_SAFE_METHODS: readonly string[];
 
-/** Holds the default response status `createDeadline` returns when its deadline fires first. */
+/** Holds `503`, the default response status `createDeadline` returns when its deadline fires first. */
 export declare const DEFAULT_DEADLINE_STATUS = 503;
 
-/** Holds the default `X-Frame-Options` value `createSecurity` sets. */
+/** Holds `'DENY'`, the default `X-Frame-Options` value `createSecurity` sets. */
 export declare const DEFAULT_FRAME_OPTIONS = "DENY";
 
-/** Holds the value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
+/** Holds `'max-age=31536000; includeSubDomains'`, the value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
 export declare const DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
 
-/** Names the default header `createSecurity` mints/echoes a request identifier into. */
+/** Names `'x-request-id'`, the default header `createSecurity` mints or echoes a request identifier into. */
 export declare const DEFAULT_IDENTIFIER_HEADER = "x-request-id";
 
-/** Holds the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
+/** Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
 export declare const DEFAULT_LIMITER_CAPACITY = 10000;
 
-/** Holds the default 429 body message `createLimiter` sends when a key is over budget. */
+/** Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. */
 export declare const DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
 
-/** Holds the default `Permissions-Policy` value `createSecurity` sets. */
+/** Holds `'camera=(), microphone=(), geolocation=()'`, the default `Permissions-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
 
-/** Holds the default `Referrer-Policy` value `createSecurity` sets. */
+/** Holds `'strict-origin-when-cross-origin'`, the default `Referrer-Policy` value `createSecurity` sets. */
 export declare const DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
 
-/** Holds the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
+/** Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
 export declare const DEFAULT_SESSION_CAPACITY = 10000;
 
-/** Names the default cookie `createCookieTransport` writes the signed session id under. */
+/** Names `'session'`, the default cookie `createCookieTransport` writes the signed session id under. */
 export declare const DEFAULT_SESSION_COOKIE = "session";
 
-/** Names the default header `createHeaderTransport` carries the session id in. */
+/** Names `'session-id'`, the default header `createHeaderTransport` carries the session id in. */
 export declare const DEFAULT_SESSION_HEADER = "session-id";
 
 /**
@@ -823,8 +840,8 @@ export declare interface ETagOptions {
 }
 
 /**
- * Scopes a battery to run everywhere EXCEPT a set of exact pathnames — there
- * it steps aside through `next()`.
+ * Scopes a battery to every pathname outside a set of exact ones — on that set it
+ * steps aside through `next()`.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
@@ -842,8 +859,8 @@ export declare function except<TState>(paths: string | readonly string[], handle
  * Configures `createForwarded` — the trusted-proxy client-IP resolver.
  *
  * @remarks
- * Construction requires EXACTLY ONE of the two forms (a `TypeError` guards
- * both-set and neither-set):
+ * Construction requires either `proxies` or `trusted`, never both and never
+ * neither (a `TypeError` guards each):
  * - `proxies` — trust exactly this many hops from the right of
  *   `X-Forwarded-For` / `Forwarded`.
  * - `trusted` — trust every hop matching one of these CIDR entries.
@@ -874,16 +891,17 @@ export declare interface IdentifierState {
 }
 
 /**
- * Checks whether a response is eligible for the compression/ETag buffering pipeline
+ * Checks whether a response must skip the compression and ETag buffering pipeline
  * — the shared cheap-skip predicate both batteries apply before ever touching
- * `response.arrayBuffer()`.
+ * `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or
+ * otherwise bodyless response, an `event-stream` response, and a response
+ * already carrying the header the caller is about to set.
  *
  * @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`, for example `Content-Encoding` for compression, `ETag` for the
- * ETag battery).
+ * Buffering an `event-stream` response would hang the connection, so SSE skips
+ * whatever its size. `skipHeader` is the header whose presence already answers
+ * the question — `Content-Encoding` for compression, `ETag` for the ETag
+ * battery.
  *
  * @param method - The request's HTTP method
  * @param response - The candidate response
@@ -950,7 +968,7 @@ export declare function isMultipartBody(value: unknown): value is MultipartBody;
 export declare function isMultipartFile(value: unknown): value is MultipartFile;
 
 /**
- * Determines whether a request is a CORS PREFLIGHT — an `OPTIONS` request
+ * Determines whether a request is a CORS preflight — an `OPTIONS` request
  * carrying an `Access-Control-Request-Method` header.
  *
  * @param method - The request's HTTP method
@@ -968,8 +986,8 @@ export declare function isPreflight(method: string, headers: Headers): boolean;
  * Determines whether a value implements {@link SessionInterface} — a total
  * structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`,
  * and `clear` mutators. Prototype-agnostic — accepts a plain object, a
- * null-prototype object, AND a class instance (a real `Session`), since a
- * restored/stored session is routinely a class instance, not a literal.
+ * null-prototype object, and a class instance (a real `Session`), because a
+ * restored or stored session is routinely a class instance rather than a literal.
  *
  * @param value - The candidate value
  * @returns True if `value` is shaped like a {@link SessionInterface}; false otherwise
@@ -1041,7 +1059,7 @@ export declare interface LimiterOptions<TState = unknown> {
  * never claims full CIDR generality beyond IPv4.
  *
  * @remarks
- * An IPv6 `trusted` roster entry is compared as an EXACT string — it must be
+ * 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.
@@ -1068,7 +1086,7 @@ export declare function matchesTrustedEntry(address: string, entry: string): boo
  * @remarks
  * `get` evicts a session whose idle time (`now - seen >= ttl`) or
  * absolute lifetime (`now - created >= lifetime`) has elapsed — the
- * lifetime check fires EVEN IF the session was continuously touched, since
+ * lifetime check fires even if the session was continuously touched, because
  * `created` is stamped once at the first `set` and preserved across every
  * later re-`set` of the same id. A live read touches `seen`. `delete` of
  * an absent id is a no-op.
@@ -1162,8 +1180,8 @@ export declare interface MultipartState {
 }
 
 /**
- * Scopes a battery to run ONLY on a set of exact pathnames — elsewhere it
- * steps aside through `next()`.
+ * Scopes a battery to a set of exact pathnames and nowhere else — outside that set
+ * it steps aside through `next()`.
  *
  * @typeParam TState - The consumer's opaque per-request state type
  * @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
@@ -1197,13 +1215,13 @@ export declare function only<TState>(paths: string | readonly string[], handler:
 export declare function rebuildResponse(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]): Response;
 
 /**
- * Walks `X-Forwarded-For` right-to-left and resolves the first UNTRUSTED hop
+ * Walks `X-Forwarded-For` right-to-left and resolves 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
+ * 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
@@ -1213,7 +1231,7 @@ export declare function rebuildResponse(body: ConstructorParameters<typeof Respo
  * socket peer).
  *
  * @param header - The raw `X-Forwarded-For` header value (comma-separated hops), if present
- * @param trust - The {@link ForwardedOptions} form in force — a trusted hop COUNT or a `trusted` CIDR/exact roster
+ * @param trust - The {@link ForwardedOptions} form in force — a trusted hop count or a `trusted` CIDR/exact roster
  * @returns The first untrusted hop address, or `undefined` when none qualifies
  *
  * @example
@@ -1249,7 +1267,7 @@ export declare function resolveKey(state: BearerState & ClientState & Connection
 
 /**
  * Resolves an opt-in, value-bearing security header — `string | boolean`
- * (default OFF, `true` uses the secure default), the shape `createSecurity`'s
+ * (off by default, `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.
  *
@@ -1293,11 +1311,11 @@ export declare type SecurityIdentifierOptions = {
  * - `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
+ * - `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
+ * - `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
+ * - `identifier` — {@link SecurityIdentifierOptions}; on by default (mints
  *   and stashes {@link IdentifierState}).
  */
 export declare interface SecurityOptions {
@@ -1343,7 +1361,7 @@ export declare class Session implements SessionInterface {
 
 /**
  * Holds the `@orkestrel/database` column shape for a
- * {@link import('./types.js').SessionRow} table — pass as-is to
+ * {@link import('./types.js').SessionRow} table. Pass it as-is to
  * `createDatabase({ tables: { sessions: sessionColumns } })` so an app
  * declaring a durable session table never hand-writes the shape.
  *
@@ -1373,13 +1391,15 @@ export declare const sessionColumns: {
  * session itself — the OWASP anti-fixation / logout primitives.
  *
  * @remarks
- * `regenerate` and `destroy` record intent SYNCHRONOUSLY when called; the
+ * `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 `state` over, and invalidates the old id.
  */
 export declare interface SessionControlInterface {
+    /** Mints a fresh id, carries the session's `state` over, and invalidates the old id. */
     regenerate(): void;
+    /** Ends the session — deletes it from the store and clears its transport. */
     destroy(): void;
 }
 
@@ -1437,8 +1457,21 @@ export declare function sessionExpired(cursors: SessionCursors, now: number, lim
 export declare interface SessionInterface {
     readonly id: string;
     readonly state: ReadonlyMap<string, unknown>;
+    /**
+     * Writes one key's value into the session's state.
+     *
+     * @param key - The state key to write
+     * @param value - The value to store under `key`
+     */
     set(key: string, value: unknown): void;
+    /**
+     * Removes one key from the session's state.
+     *
+     * @param key - The state key to remove
+     * @returns True when the session held `key`; false otherwise
+     */
     delete(key: string): boolean;
+    /** Empties the state, leaving the session and its id alive. */
     clear(): void;
 }
 
@@ -1469,10 +1502,10 @@ export declare interface SessionLimits {
  *   `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
+ * - `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
+ * - `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.
@@ -1566,8 +1599,28 @@ export declare interface SessionState {
  * constructed with.
  */
 export declare interface SessionStoreInterface<S extends SessionInterface> {
+    /**
+     * Reads a session by id, applying the idle and absolute expiry against `now`.
+     *
+     * @param id - The session id to read
+     * @param now - The caller's clock reading the expiry is measured against
+     * @returns The stored session, or `undefined` when it is absent or expired
+     */
     get(id: string, now: number): Promise<S | undefined>;
+    /**
+     * Persists a session under its own `id`, refreshing its idle window.
+     *
+     * @param session - The session to persist, keyed by its own `id`
+     * @param now - The caller's clock reading stamped as the session's `seen`
+     * @returns A promise that resolves once the session is stored
+     */
     set(session: S, now: number): Promise<void>;
+    /**
+     * Removes a session by id — a no-op on an absent id, never throws.
+     *
+     * @param id - The session id to remove
+     * @returns A promise that resolves once the id is absent from the store
+     */
     delete(id: string): Promise<void>;
 }
 
@@ -1577,7 +1630,7 @@ export declare interface SessionStoreInterface<S extends SessionInterface> {
  *
  * @remarks
  * `read` is total (a malformed/tampered credential resolves `undefined`,
- * never throws). `write` and `clear` mutate the RETURNED `Response` on the
+ * 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
@@ -1586,8 +1639,24 @@ export declare interface SessionStoreInterface<S extends SessionInterface> {
  * without re-deriving connection facts itself.
  */
 export declare interface SessionTransportInterface {
+    /**
+     * Reads the incoming session id from the request — `undefined` on any failure.
+     *
+     * @param request - The inbound request the credential travels on
+     * @returns The session id, or `undefined` when none is present or readable
+     */
     read(request: Request): string | undefined | Promise<string | undefined>;
+    /**
+     * Writes a freshly minted or regenerated session id onto the response, together with
+     * the request's encrypted-transport fact.
+     *
+     * @param response - The outgoing response the credential is written onto
+     * @param id - The session id carried to the client
+     * @param encrypted - Whether the request arrived over an encrypted transport
+     * @returns Nothing, or a promise that resolves once the credential is written
+     */
     write(response: Response, id: string, encrypted: boolean): void | Promise<void>;
+    /** Clears the transport's credential on `destroy()`. */
     clear(response: Response): void;
 }
 
@@ -1602,7 +1671,7 @@ export declare interface SessionTransportInterface {
  * @remarks
  * `state` is built on a null-prototype object (`Object.create(null)`), never
  * a `{}` literal — a session key literally named `__proto__` must round-trip
- * as an OWN enumerable property instead of hitting `Object.prototype`'s
+ * as an own enumerable property instead of hitting `Object.prototype`'s
  * `__proto__` accessor (which would silently drop the entry and risk
  * polluting the shared prototype).
  *