@orkestrel/middleware 0.0.19 → 0.0.21

package/dist/src/core/index.js

@@ -1,15 +1,15 @@
-import { integerShape, isBoolean, isFiniteNumber, isFunction, isRecord, isString, jsonShape, stringShape } from "@orkestrel/contract";
+import { integerShape, isArray, isBoolean, isError, isFiniteNumber, isFunction, isInstance, isInteger, isNumber, isObject, isRecord, isString, jsonShape, stringShape } from "@orkestrel/contract";
 import { HTTPError, clearCookie, computeBodyETag, computeClientKey, isCompressibleType, isHTTPError, isValidRequestId, matchesETag, mergeVary, negotiateEncoding, readSignedCookie, resolveOrigin, resolveSecure, resolveSecurityHeader, signToken, verifyToken, writeSignedCookie } from "@orkestrel/server";
 import { linkSignal } from "@orkestrel/abort";
 import { createBudget } from "@orkestrel/budget";
 import { createTimeout } from "@orkestrel/timeout";
 //#region src/core/constants.ts
-/** Holds the default minimum buffered body size (bytes) `createCompression` will compress. */
+/** Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. */
 var DEFAULT_COMPRESSION_THRESHOLD = 1024;
 /**
-* 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
@@ -19,28 +19,29 @@ var DEFAULT_COMPRESSION_THRESHOLD = 1024;
 * admits; a node-face brotli variant, if one ships, extends this list there.
 */
 var DEFAULT_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
-/** Holds the default `X-Frame-Options` value `createSecurity` sets. */
+/** Holds `'DENY'`, the default `X-Frame-Options` value `createSecurity` sets. */
 var DEFAULT_FRAME_OPTIONS = "DENY";
 /**
-* 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.
 */
 var DEFAULT_CSP = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'; form-action 'self'";
-/** Holds the default `Referrer-Policy` value `createSecurity` sets. */
+/** Holds `'strict-origin-when-cross-origin'`, the default `Referrer-Policy` value `createSecurity` sets. */
 var DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
-/** Holds the default `Permissions-Policy` value `createSecurity` sets. */
+/** Holds `'camera=(), microphone=(), geolocation=()'`, the default `Permissions-Policy` value `createSecurity` sets. */
 var DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
-/** Holds the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+/** Holds `'same-origin'`, the default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
 var 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. */
 var DEFAULT_CORP = "same-origin";
-/** Holds the default `Origin-Agent-Cluster` value `createSecurity` sets. */
+/** Holds `'?1'`, the default `Origin-Agent-Cluster` value `createSecurity` sets. */
 var 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`. */
 var DEFAULT_COEP = "require-corp";
-/** 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`. */
 var 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. */
 var DEFAULT_IDENTIFIER_HEADER = "x-request-id";
 /** Lists the default methods `createCors` advertises on a preflight response. */
 var DEFAULT_CORS_METHODS = Object.freeze([
@@ -53,29 +54,29 @@ var DEFAULT_CORS_METHODS = Object.freeze([
 ]);
 /** Lists the default headers `createCors` advertises on a preflight response. */
 var DEFAULT_CORS_HEADERS = Object.freeze(["Content-Type", "Authorization"]);
-/** 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. */
 var DEFAULT_DEADLINE_STATUS = 503;
-/** Names the default header `createBearer` reads the token from. */
+/** Names `'authorization'`, the default header `createBearer` reads the token from. */
 var DEFAULT_BEARER_HEADER = "authorization";
-/** Names the default scheme prefix `createBearer` strips before verification. */
+/** Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. */
 var DEFAULT_BEARER_SCHEME = "Bearer";
-/** 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. */
 var DEFAULT_LIMITER_CAPACITY = 1e4;
-/** 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. */
 var DEFAULT_SESSION_CAPACITY = 1e4;
-/** 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. */
 var DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
-/** Names the default cookie `createCookieTransport` writes the signed session id under. */
+/** Names `'session'`, the default cookie `createCookieTransport` writes the signed session id under. */
 var 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. */
 var DEFAULT_SESSION_HEADER = "session-id";
-/** Names the default signed cookie `createCSRF` writes the CSRF token under. */
+/** Names `'csrf'`, the default signed cookie `createCSRF` writes the CSRF token under. */
 var DEFAULT_CSRF_COOKIE = "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. */
 var DEFAULT_CSRF_HEADER = "x-csrf-token";
-/** 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. */
 var DEFAULT_CSRF_FIELD = "_csrf";
-/** 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). */
 var DEFAULT_CSRF_SAFE_METHODS = Object.freeze([
 	"GET",
 	"HEAD",
@@ -174,7 +175,7 @@ function buildRateLimitPolicyField(max, window) {
 * 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.
@@ -197,24 +198,24 @@ function matchesTrustedEntry(address, entry) {
 	const networkParts = network.split(".");
 	const addressParts = address.split(".");
 	if (networkParts.length !== 4 || addressParts.length !== 4) return false;
-	if (!Number.isInteger(bits) || bits < 8 || bits > 32) return false;
+	if (!isInteger(bits) || bits < 8 || bits > 32) return false;
 	const networkOctets = networkParts.map(Number);
 	const addressOctets = addressParts.map(Number);
-	if (networkOctets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) return false;
-	if (addressOctets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) return false;
+	if (networkOctets.some((value) => !isInteger(value) || value < 0 || value > 255)) return false;
+	if (addressOctets.some((value) => !isInteger(value) || value < 0 || value > 255)) return false;
 	const networkInt = (networkOctets[0] ?? 0) << 24 | (networkOctets[1] ?? 0) << 16 | (networkOctets[2] ?? 0) << 8 | (networkOctets[3] ?? 0);
 	const addressInt = (addressOctets[0] ?? 0) << 24 | (addressOctets[1] ?? 0) << 16 | (addressOctets[2] ?? 0) << 8 | (addressOctets[3] ?? 0);
 	const mask = bits === 32 ? -1 : ~((1 << 32 - bits) - 1);
 	return (networkInt & mask) === (addressInt & mask);
 }
 /**
-* 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
@@ -224,7 +225,7 @@ function matchesTrustedEntry(address, entry) {
 * 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
@@ -298,16 +299,17 @@ async function compressBytes(bytes, encoding) {
 	return new Uint8Array(compressed);
 }
 /**
-* 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
@@ -346,7 +348,7 @@ function isCompressionNegotiated(encoding) {
 }
 /**
 * 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.
 *
@@ -400,7 +402,7 @@ function rebuildResponse(body, response, headers) {
 * 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
@@ -435,7 +437,7 @@ async function compressResponse(request, context, response, options) {
 	const declaredLength = response.headers.get("content-length");
 	if (declaredLength !== null) {
 		const declared = Number(declaredLength);
-		if (Number.isFinite(declared) && declared < options.threshold) return response;
+		if (isFiniteNumber(declared) && declared < options.threshold) return response;
 	}
 	const buffer = await response.arrayBuffer();
 	if (buffer.byteLength < options.threshold) return rebuildResponse(buffer, response);
@@ -462,7 +464,7 @@ function transferSessionState(from, to) {
 	for (const [key, value] of from.state) to.set(key, value);
 }
 /**
-* 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
@@ -569,7 +571,7 @@ function validateSessionLimits(limits) {
 * @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).
 *
@@ -592,8 +594,8 @@ function snapshotSession(session) {
 * 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
@@ -605,14 +607,14 @@ function snapshotSession(session) {
 * ```
 */
 function isSession(value) {
-	if (typeof value !== "object" || value === null) return false;
+	if (!isObject(value)) return false;
 	const id = Reflect.get(value, "id");
 	const state = Reflect.get(value, "state");
-	if (!isString(id) || !(state instanceof Map)) return false;
+	if (!isString(id) || !isInstance(state, Map)) return false;
 	const set = Reflect.get(value, "set");
 	const remove = Reflect.get(value, "delete");
 	const clear = Reflect.get(value, "clear");
-	return typeof set === "function" && typeof remove === "function" && typeof clear === "function";
+	return isFunction(set) && isFunction(remove) && isFunction(clear);
 }
 /**
 * Determines whether a value implements {@link SessionControlInterface} — a
@@ -628,7 +630,7 @@ function isSession(value) {
 */
 function isSessionControl(value) {
 	if (!isRecord(value)) return false;
-	return typeof value.regenerate === "function" && typeof value.destroy === "function";
+	return isFunction(value.regenerate) && isFunction(value.destroy);
 }
 /**
 * Determines whether a value is one staged {@link MultipartFile} record — a
@@ -652,7 +654,7 @@ function isSessionControl(value) {
 */
 function isMultipartFile(value) {
 	if (!isRecord(value)) return false;
-	return isString(value.field) && isString(value.name) && typeof value.size === "number" && isString(value.mime) && typeof value.validated === "boolean" && isString(value.status) && isString(value.path);
+	return isString(value.field) && isString(value.name) && isNumber(value.size) && isString(value.mime) && isBoolean(value.validated) && isString(value.status) && isString(value.path);
 }
 /**
 * Determines whether a value implements {@link MultipartBody} — a total
@@ -671,7 +673,7 @@ function isMultipartBody(value) {
 	if (!isRecord(value)) return false;
 	if (!isRecord(value.files) || !isRecord(value.fields)) return false;
 	for (const entries of Object.values(value.files)) {
-		if (!Array.isArray(entries)) return false;
+		if (!isArray(entries)) return false;
 		for (const entry of entries) if (!isMultipartFile(entry)) return false;
 	}
 	for (const fieldValue of Object.values(value.fields)) if (!isString(fieldValue)) return false;
@@ -681,7 +683,7 @@ function isMultipartBody(value) {
 //#region src/core/shapers.ts
 /**
 * 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.
 *
@@ -760,7 +762,7 @@ var Session = class {
 * @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.
@@ -788,7 +790,7 @@ var MemorySessionStore = class {
 	#evict;
 	constructor(options) {
 		validateSessionLimits(options);
-		if (options?.capacity !== void 0 && (!isFiniteNumber(options.capacity) || !Number.isInteger(options.capacity) || options.capacity <= 0)) throw new TypeError("MemorySessionStore requires options.capacity to be a positive integer when provided");
+		if (options?.capacity !== void 0 && (!isInteger(options.capacity) || options.capacity <= 0)) throw new TypeError("MemorySessionStore requires options.capacity to be a positive integer when provided");
 		if (options?.evict !== void 0 && !isFunction(options.evict)) throw new TypeError("MemorySessionStore requires options.evict to be a function when provided");
 		this.#entries = /* @__PURE__ */ new Map();
 		this.#ttl = options?.ttl;
@@ -875,7 +877,7 @@ var MemorySessionStore = class {
 * {@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`,
@@ -945,9 +947,20 @@ var DatabaseSessionStore = class {
 * @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 })
+* })
 * ```
 */
 function createBoundary(options) {
@@ -963,7 +976,7 @@ function createBoundary(options) {
 				report(error);
 			} catch {}
 			if (isHTTPError(error)) return new Response(error.message, { status: error.status });
-			const message = expose ? error instanceof Error ? error.message : String(error) : "internal server error";
+			const message = expose ? isError(error) ? error.message : String(error) : "internal server error";
 			return new Response(message, { status: 500 });
 		}
 	};
@@ -1022,7 +1035,7 @@ function createTelemetry(options) {
 function createCompression(options) {
 	if (options?.threshold !== void 0 && (!isFiniteNumber(options.threshold) || options.threshold < 0)) throw new TypeError("CompressionOptions.threshold must be a finite number when provided");
 	if (options?.filter !== void 0 && !isFunction(options.filter)) throw new TypeError("CompressionOptions.filter must be a function when provided");
-	if (options?.encodings !== void 0 && !Array.isArray(options.encodings)) throw new TypeError("CompressionOptions.encodings must be an array when provided");
+	if (options?.encodings !== void 0 && !isArray(options.encodings)) throw new TypeError("CompressionOptions.encodings must be an array when provided");
 	const threshold = options?.threshold ?? 1024;
 	const encodings = detectEncodings(options?.encodings ?? DEFAULT_COMPRESSION_ENCODINGS);
 	const filter = options?.filter;
@@ -1036,7 +1049,8 @@ function createCompression(options) {
 	};
 }
 /**
-* 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}
@@ -1098,7 +1112,8 @@ function createSecurity(options) {
 	};
 }
 /**
-* 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}
@@ -1111,13 +1126,13 @@ function createSecurity(options) {
 * ```
 */
 function createCors(options) {
-	if (options?.origin !== void 0 && !isString(options.origin) && !Array.isArray(options.origin)) throw new TypeError("CorsOptions.origin must be a string or string array when provided");
-	if (options?.methods !== void 0 && !Array.isArray(options.methods)) throw new TypeError("CorsOptions.methods must be an array when provided");
-	if (options?.headers !== void 0 && !Array.isArray(options.headers)) throw new TypeError("CorsOptions.headers must be an array when provided");
+	if (options?.origin !== void 0 && !isString(options.origin) && !isArray(options.origin)) throw new TypeError("CorsOptions.origin must be a string or string array when provided");
+	if (options?.methods !== void 0 && !isArray(options.methods)) throw new TypeError("CorsOptions.methods must be an array when provided");
+	if (options?.headers !== void 0 && !isArray(options.headers)) throw new TypeError("CorsOptions.headers must be an array when provided");
 	const origin = options?.origin ?? "*";
 	const methods = options?.methods ?? DEFAULT_CORS_METHODS;
 	const headers = options?.headers ?? DEFAULT_CORS_HEADERS;
-	const reflecting = Array.isArray(origin);
+	const reflecting = isArray(origin);
 	return async (request, context, next) => {
 		const requestOrigin = request.headers.get("origin") ?? void 0;
 		const allowOrigin = resolveOrigin(origin, requestOrigin);
@@ -1147,7 +1162,7 @@ function createCors(options) {
 * @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).
 *
@@ -1184,7 +1199,8 @@ function createDeadline(options) {
 	};
 }
 /**
-* 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}
@@ -1202,10 +1218,10 @@ function createForwarded(options) {
 	if (!isRecord(options) || hasProxies === hasTrusted) throw new TypeError("ForwardedOptions requires exactly one of proxies or trusted");
 	if (hasProxies) {
 		const proxies = options.proxies;
-		if (!isFiniteNumber(proxies) || !Number.isInteger(proxies) || proxies < 1) throw new TypeError("ForwardedOptions.proxies must be a positive integer");
+		if (!isInteger(proxies) || proxies < 1) throw new TypeError("ForwardedOptions.proxies must be a positive integer");
 	} else {
 		const trusted = options.trusted;
-		if (!Array.isArray(trusted)) throw new TypeError("ForwardedOptions.trusted must be an array when provided");
+		if (!isArray(trusted)) throw new TypeError("ForwardedOptions.trusted must be an array when provided");
 	}
 	const trust = hasProxies ? { proxies: options.proxies } : { trusted: options.trusted };
 	return async (request, context, next) => {
@@ -1215,7 +1231,7 @@ function createForwarded(options) {
 	};
 }
 /**
-* 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}
@@ -1253,7 +1269,8 @@ function createETag(options) {
 	};
 }
 /**
-* 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}
@@ -1267,7 +1284,7 @@ function createETag(options) {
 * ```
 */
 function createBearer(options) {
-	if (!isString(options.secret) && (!Array.isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("BearerOptions.secret must be a string or string array");
+	if (!isString(options.secret) && (!isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("BearerOptions.secret must be a string or string array");
 	if (options.header !== void 0 && !isString(options.header)) throw new TypeError("BearerOptions.header must be a string when provided");
 	if (options.scheme !== void 0 && !isString(options.scheme)) throw new TypeError("BearerOptions.scheme must be a string when provided");
 	const secret = options.secret;
@@ -1289,7 +1306,8 @@ function createBearer(options) {
 	};
 }
 /**
-* 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}
@@ -1302,9 +1320,9 @@ function createBearer(options) {
 * ```
 */
 function createLimiter(options) {
-	if (!isFiniteNumber(options.max) || !Number.isInteger(options.max) || options.max <= 0) throw new TypeError("LimiterOptions.max must be a positive integer");
+	if (!isInteger(options.max) || options.max <= 0) throw new TypeError("LimiterOptions.max must be a positive integer");
 	if (!isFiniteNumber(options.window) || options.window <= 0) throw new TypeError("LimiterOptions.window must be a positive finite number");
-	if (options.capacity !== void 0 && (!isFiniteNumber(options.capacity) || !Number.isInteger(options.capacity) || options.capacity <= 0)) throw new TypeError("LimiterOptions.capacity must be a positive integer when provided");
+	if (options.capacity !== void 0 && (!isInteger(options.capacity) || options.capacity <= 0)) throw new TypeError("LimiterOptions.capacity must be a positive integer when provided");
 	if (options.key !== void 0 && !isFunction(options.key)) throw new TypeError("LimiterOptions.key must be a function when provided");
 	if (options.message !== void 0 && !isString(options.message)) throw new TypeError("LimiterOptions.message must be a string when provided");
 	if (options.clock !== void 0 && !isFunction(options.clock)) throw new TypeError("LimiterOptions.clock must be a function when provided");
@@ -1378,7 +1396,7 @@ function createLimiter(options) {
 * 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
@@ -1494,11 +1512,11 @@ function createSession(options) {
 * ```
 */
 function createCSRF(options) {
-	if (!isString(options.secret) && (!Array.isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("CSRFOptions.secret must be a string or string array");
+	if (!isString(options.secret) && (!isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("CSRFOptions.secret must be a string or string array");
 	if (options.cookie !== void 0 && !isString(options.cookie)) throw new TypeError("CSRFOptions.cookie must be a string when provided");
 	if (options.header !== void 0 && !isString(options.header)) throw new TypeError("CSRFOptions.header must be a string when provided");
 	if (options.field !== void 0 && !isString(options.field)) throw new TypeError("CSRFOptions.field must be a string when provided");
-	if (options.safe !== void 0 && !Array.isArray(options.safe)) throw new TypeError("CSRFOptions.safe must be an array when provided");
+	if (options.safe !== void 0 && !isArray(options.safe)) throw new TypeError("CSRFOptions.safe must be an array when provided");
 	const secret = options.secret;
 	const cookieName = options.cookie ?? "csrf";
 	const header = options.header ?? "x-csrf-token";
@@ -1537,8 +1555,8 @@ function createCSRF(options) {
 	};
 }
 /**
-* 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`
@@ -1551,15 +1569,15 @@ function createCSRF(options) {
 * ```
 */
 function only(paths, handler) {
-	const matches = new Set(typeof paths === "string" ? [paths] : paths);
+	const matches = new Set(isString(paths) ? [paths] : paths);
 	return async (request, context, next) => {
 		if (matches.has(context.url.pathname)) return handler(request, context, next);
 		return next();
 	};
 }
 /**
-* 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`
@@ -1572,7 +1590,7 @@ function only(paths, handler) {
 * ```
 */
 function except(paths, handler) {
-	const matches = new Set(typeof paths === "string" ? [paths] : paths);
+	const matches = new Set(isString(paths) ? [paths] : paths);
 	return async (request, context, next) => {
 		if (matches.has(context.url.pathname)) return next();
 		return handler(request, context, next);
@@ -1594,7 +1612,7 @@ function except(paths, handler) {
 * ```
 */
 function createCookieTransport(options) {
-	if (!isString(options.secret) && (!Array.isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("CookieTransportOptions.secret must be a string or string array");
+	if (!isString(options.secret) && (!isArray(options.secret) || !options.secret.every(isString))) throw new TypeError("CookieTransportOptions.secret must be a string or string array");
 	if (options.name !== void 0 && !isString(options.name)) throw new TypeError("CookieTransportOptions.name must be a string when provided");
 	const name = options.name ?? "session";
 	const secret = options.secret;