@orkestrel/middleware 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1399 @@
+import { isBoolean, isFiniteNumber, isFunction, isRecord, isString } from "@orkestrel/contract";
+import { HTTPError, clearCookie, clientRateKey, computeBodyETag, 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
+/** Default minimum buffered body size (bytes) `createCompression` will compress. */
+var DEFAULT_COMPRESSION_THRESHOLD = 1024;
+/**
+* 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.
+*/
+var DEFAULT_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
+/** Default `X-Frame-Options` value `createSecurity` sets. */
+var DEFAULT_FRAME_OPTIONS = "DENY";
+/**
+* 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'";
+/** Default `Referrer-Policy` value `createSecurity` sets. */
+var DEFAULT_REFERRER_POLICY = "strict-origin-when-cross-origin";
+/** Default `Permissions-Policy` value `createSecurity` sets. */
+var DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=()";
+/** Default `Cross-Origin-Opener-Policy` value `createSecurity` sets. */
+var DEFAULT_COOP = "same-origin";
+/** Default `Cross-Origin-Resource-Policy` value `createSecurity` sets. */
+var DEFAULT_CORP = "same-origin";
+/** Default `Origin-Agent-Cluster` value `createSecurity` sets. */
+var DEFAULT_CLUSTER = "?1";
+/** Value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. */
+var DEFAULT_COEP = "require-corp";
+/** Value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. */
+var DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
+/** Default header `createSecurity` mints/echoes a request identifier into. */
+var DEFAULT_IDENTIFIER_HEADER = "x-request-id";
+/** Default methods `createCors` advertises on a preflight response. */
+var DEFAULT_CORS_METHODS = Object.freeze([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS"
+]);
+/** Default headers `createCors` advertises on a preflight response. */
+var DEFAULT_CORS_HEADERS = Object.freeze(["Content-Type", "Authorization"]);
+/** Default response status `createDeadline` returns when its deadline fires first. */
+var DEFAULT_DEADLINE_STATUS = 503;
+/** Default header `createBearer` reads the token from. */
+var DEFAULT_BEARER_HEADER = "authorization";
+/** Default scheme prefix `createBearer` strips before verification. */
+var DEFAULT_BEARER_SCHEME = "Bearer";
+/** Default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. */
+var DEFAULT_LIMITER_CAPACITY = 1e4;
+/** Default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. */
+var DEFAULT_SESSION_CAPACITY = 1e4;
+/** Default 429 body message `createLimiter` sends when a key is over budget. */
+var DEFAULT_LIMITER_MESSAGE = "rate limit exceeded";
+/** Default cookie name `createCookieTransport` writes the signed session id under. */
+var DEFAULT_SESSION_COOKIE = "session";
+/** Default header `createHeaderTransport` carries the session id in. */
+var DEFAULT_SESSION_HEADER = "session-id";
+/** Default signed-cookie name `createCSRF` writes the CSRF token under. */
+var DEFAULT_CSRF_COOKIE = "csrf";
+/** Default header `createCSRF` reads a mutating request's submitted token from. */
+var DEFAULT_CSRF_HEADER = "x-csrf-token";
+/** Default body field `createCSRF` falls back to reading a mutating request's submitted token from. */
+var DEFAULT_CSRF_FIELD = "_csrf";
+/** Default methods `createCSRF` treats as safe (mint instead of verify). */
+var DEFAULT_CSRF_SAFE_METHODS = Object.freeze([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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'
+* ```
+*/
+function resolveKey(state) {
+	if (state.token !== void 0) return `token:${state.token}`;
+	const ip = state.client?.ip ?? state.connection?.ip;
+	if (ip !== void 0) return `ip:${clientRateKey(ip)}`;
+	return "ip:unknown";
+}
+/**
+* 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'
+* ```
+*/
+function buildRetryAfter(resetAt, now) {
+	const seconds = Math.ceil((resetAt - now) / 1e3);
+	return String(Math.max(1, seconds));
+}
+/**
+* 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'
+* ```
+*/
+function buildRateLimitField(remaining, resetAt, now) {
+	return `"default";r=${remaining};t=${Math.max(1, Math.ceil((resetAt - now) / 1e3))}`;
+}
+/**
+* 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'
+* ```
+*/
+function buildRateLimitPolicyField(max, window) {
+	return `"default";q=${max};w=${Math.ceil(window / 1e3)}`;
+}
+/**
+* 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
+* ```
+*/
+function matchesTrustedEntry(address, entry) {
+	const slash = entry.indexOf("/");
+	if (slash === -1) return address === entry;
+	const network = entry.slice(0, slash);
+	const bits = Number(entry.slice(slash + 1));
+	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;
+	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;
+	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);
+}
+/**
+* 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'
+* ```
+*/
+function resolveForwardedFor(header, trust) {
+	if (header === void 0) return void 0;
+	const hops = header.split(",").map((hop) => hop.trim()).filter((hop) => hop.length > 0);
+	if (hops.length === 0) return void 0;
+	if ("proxies" in trust) {
+		const index = hops.length - trust.proxies - 1;
+		return index >= 0 ? hops[index] : void 0;
+	}
+	const rightmost = hops[hops.length - 1];
+	if (rightmost === void 0) return void 0;
+	if (!trust.trusted.some((entry) => matchesTrustedEntry(rightmost, entry))) return void 0;
+	for (let index = hops.length - 2; index >= 0; index -= 1) {
+		const hop = hops[index];
+		if (hop === void 0) return void 0;
+		if (!trust.trusted.some((entry) => matchesTrustedEntry(hop, entry))) return hop;
+	}
+}
+/**
+* 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
+* ```
+*/
+function detectEncodings(candidates) {
+	const supported = [];
+	for (const candidate of candidates) {
+		if (candidate === "identity") continue;
+		try {
+			if (new CompressionStream(candidate).readable) supported.push(candidate);
+		} catch {}
+	}
+	return supported;
+}
+/**
+* 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
+* ```
+*/
+function isBufferingIneligible(method, response, skipHeader) {
+	if (method === "HEAD") return true;
+	if (response.status === 204 || response.status === 304) return true;
+	if (response.body === null) return true;
+	const contentType = response.headers.get("content-type");
+	if (contentType !== null && contentType.toLowerCase().startsWith("text/event-stream")) return true;
+	if (response.headers.has(skipHeader)) return true;
+	return false;
+}
+/**
+* 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
+* ```
+*/
+function isCompressionNegotiated(encoding) {
+	return encoding !== void 0 && encoding !== "identity";
+}
+/**
+* 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
+* ```
+*/
+function resolveOptInHeader(value, fallback) {
+	if (value === true) return fallback;
+	if (value === false || value === void 0) return void 0;
+	return value;
+}
+/**
+* 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
+* ```
+*/
+function rebuildResponse(body, response, headers) {
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: headers ?? new Headers(response.headers)
+	});
+}
+/**
+* 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),
+* })
+* ```
+*/
+async function compressResponse(request, context, response, options) {
+	if (isBufferingIneligible(context.method, response, "content-encoding")) return response;
+	if (options.filter !== void 0 && !options.filter(request, response)) return response;
+	response.headers.set("vary", mergeVary(response.headers.get("vary") ?? void 0, "Accept-Encoding"));
+	const acceptEncoding = request.headers.get("accept-encoding");
+	if (acceptEncoding === null) return response;
+	const negotiated = negotiateEncoding(acceptEncoding, options.encodings);
+	if (!isCompressionNegotiated(negotiated)) return response;
+	const contentType = response.headers.get("content-type");
+	if (contentType === null || !isCompressibleType(contentType)) return response;
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null) {
+		const declared = Number(declaredLength);
+		if (Number.isFinite(declared) && declared < options.threshold) return response;
+	}
+	const buffer = await response.arrayBuffer();
+	if (buffer.byteLength < options.threshold) return rebuildResponse(buffer, response);
+	const compressed = await options.compress(new Uint8Array(buffer), negotiated);
+	const headers = new Headers(response.headers);
+	headers.set("content-encoding", negotiated);
+	headers.set("content-length", String(compressed.byteLength));
+	return rebuildResponse(compressed, response, headers);
+}
+/**
+* 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)
+* ```
+*/
+function transferSessionData(from, to) {
+	for (const [key, value] of from.data) to.data.set(key, value);
+}
+/**
+* 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
+* ```
+*/
+function isSession(value) {
+	if (!isRecord(value)) return false;
+	return isString(value.id) && value.data instanceof Map;
+}
+/**
+* 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
+* ```
+*/
+function isSessionControl(value) {
+	if (!isRecord(value)) return false;
+	return typeof value.regenerate === "function" && typeof value.destroy === "function";
+}
+/**
+* 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}
+*/
+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);
+}
+/**
+* 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
+* ```
+*/
+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;
+		for (const entry of entries) if (!isMultipartFile(entry)) return false;
+	}
+	for (const fieldValue of Object.values(value.fields)) if (!isString(fieldValue)) return false;
+	return true;
+}
+/**
+* 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
+* ```
+*/
+function isPreflight(method, headers) {
+	return method === "OPTIONS" && headers.has("access-control-request-method");
+}
+/**
+* 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' }
+* ```
+*/
+function buildClientInfo(ip) {
+	return { ip };
+}
+/**
+* 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
+* ```
+*/
+function equalsConstantTime(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let index = 0; index < a.length; index += 1) diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return diff === 0;
+}
+//#endregion
+//#region src/core/Session.ts
+/**
+* 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')
+* ```
+*/
+var Session = class {
+	id;
+	data;
+	constructor(id) {
+		this.id = id;
+		this.data = /* @__PURE__ */ new Map();
+	}
+};
+//#endregion
+//#region src/core/MemorySessionStore.ts
+/**
+* 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())
+* ```
+*/
+var MemorySessionStore = class {
+	#entries;
+	#ttl;
+	#lifetime;
+	#capacity;
+	#evict;
+	constructor(options) {
+		if (options?.ttl !== void 0 && !isFiniteNumber(options.ttl)) throw new TypeError("MemorySessionStore requires options.ttl to be a finite number when provided");
+		if (options?.ttl !== void 0 && options.ttl <= 0) throw new TypeError("MemorySessionStore requires options.ttl to be positive when provided");
+		if (options?.lifetime !== void 0 && !isFiniteNumber(options.lifetime)) throw new TypeError("MemorySessionStore requires options.lifetime to be a finite number when provided");
+		if (options?.lifetime !== void 0 && options.lifetime <= 0) throw new TypeError("MemorySessionStore requires options.lifetime to be positive when provided");
+		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?.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;
+		this.#lifetime = options?.lifetime;
+		this.#capacity = options?.capacity ?? 1e4;
+		this.#evict = options?.evict;
+	}
+	async get(id, now) {
+		const entry = this.#entries.get(id);
+		if (entry === void 0) return void 0;
+		if (this.#expired(entry, now)) {
+			this.#entries.delete(id);
+			this.#notify(id);
+			return;
+		}
+		entry.lastSeen = now;
+		return entry.session;
+	}
+	async set(id, session, now) {
+		const existing = this.#entries.get(id);
+		if (existing === void 0) this.#reserve(now);
+		const createdAt = existing?.createdAt ?? now;
+		this.#entries.delete(id);
+		this.#entries.set(id, {
+			session,
+			lastSeen: now,
+			createdAt
+		});
+	}
+	async delete(id) {
+		this.#entries.delete(id);
+	}
+	#expired(entry, now) {
+		if (this.#ttl !== void 0 && now - entry.lastSeen >= this.#ttl) return true;
+		if (this.#lifetime !== void 0 && now - entry.createdAt >= this.#lifetime) return true;
+		return false;
+	}
+	#reserve(now) {
+		if (this.#entries.size < this.#capacity) return;
+		for (const [id, entry] of this.#entries) if (this.#expired(entry, now)) {
+			this.#entries.delete(id);
+			this.#notify(id);
+		}
+		if (this.#entries.size >= this.#capacity) {
+			const oldest = this.#entries.keys().next().value;
+			if (oldest !== void 0) {
+				this.#entries.delete(oldest);
+				this.#notify(oldest);
+			}
+		}
+	}
+	#notify(id) {
+		if (this.#evict === void 0) return;
+		try {
+			this.#evict(id);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/core/middlewares.ts
+/**
+* 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 })
+* ```
+*/
+function createBoundary(options) {
+	if (options?.expose !== void 0 && !isBoolean(options.expose)) throw new TypeError("BoundaryOptions.expose must be a boolean when provided");
+	if (options?.report !== void 0 && !isFunction(options.report)) throw new TypeError("BoundaryOptions.report must be a function when provided");
+	const expose = options?.expose ?? false;
+	const report = options?.report;
+	return async (request, context, next) => {
+		try {
+			return await next();
+		} catch (error) {
+			if (report !== void 0) try {
+				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";
+			return new Response(message, { status: 500 });
+		}
+	};
+}
+/**
+* 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) })
+* ```
+*/
+function createTelemetry(options) {
+	if (!isFunction(options.record)) throw new TypeError("TelemetryOptions.record must be a function");
+	const record = options.record;
+	return async (request, context, next) => {
+		const start = Date.now();
+		let response;
+		try {
+			response = await next();
+			return response;
+		} finally {
+			const duration = Date.now() - start;
+			const status = response?.status ?? 500;
+			try {
+				record({
+					method: context.method,
+					pathname: context.url.pathname,
+					status,
+					duration
+				});
+			} catch {}
+		}
+	};
+}
+/**
+* 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 })
+* ```
+*/
+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");
+	const threshold = options?.threshold ?? 1024;
+	const encodings = detectEncodings(options?.encodings ?? DEFAULT_COMPRESSION_ENCODINGS);
+	const filter = options?.filter;
+	const compress = async (bytes, encoding) => {
+		const source = new Response(bytes).body;
+		if (source === null) return bytes;
+		const compressed = await new Response(source.pipeThrough(new CompressionStream(encoding))).arrayBuffer();
+		return new Uint8Array(compressed);
+	};
+	return async (request, context, next) => {
+		return compressResponse(request, context, await next(), {
+			threshold,
+			filter,
+			encodings,
+			compress
+		});
+	};
+}
+/**
+* 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 })
+* ```
+*/
+function createSecurity(options) {
+	if (options?.frame !== void 0 && options.frame !== false && options.frame !== "DENY" && options.frame !== "SAMEORIGIN") throw new TypeError("SecurityOptions.frame must be 'DENY', 'SAMEORIGIN', or false when provided");
+	if (options?.csp !== void 0 && options.csp !== false && !isString(options.csp)) throw new TypeError("SecurityOptions.csp must be a string or false when provided");
+	if (options?.referrer !== void 0 && options.referrer !== false && !isString(options.referrer)) throw new TypeError("SecurityOptions.referrer must be a string or false when provided");
+	if (options?.permissions !== void 0 && options.permissions !== false && !isString(options.permissions)) throw new TypeError("SecurityOptions.permissions must be a string or false when provided");
+	if (options?.coop !== void 0 && options.coop !== false && !isString(options.coop)) throw new TypeError("SecurityOptions.coop must be a string or false when provided");
+	if (options?.corp !== void 0 && options.corp !== false && !isString(options.corp)) throw new TypeError("SecurityOptions.corp must be a string or false when provided");
+	if (options?.cluster !== void 0 && options.cluster !== false && !isString(options.cluster)) throw new TypeError("SecurityOptions.cluster must be a string or false when provided");
+	if (options?.coep !== void 0 && !isBoolean(options.coep) && !isString(options.coep)) throw new TypeError("SecurityOptions.coep must be a string or boolean when provided");
+	if (options?.hsts !== void 0 && !isBoolean(options.hsts) && !isString(options.hsts)) throw new TypeError("SecurityOptions.hsts must be a string or boolean when provided");
+	if (options?.identifier !== void 0 && options.identifier !== false && !isRecord(options.identifier)) throw new TypeError("SecurityOptions.identifier must be an options bag or false when provided");
+	if (isRecord(options?.identifier) && options.identifier.trust !== void 0 && !isBoolean(options.identifier.trust)) throw new TypeError("SecurityOptions.identifier.trust must be a boolean when provided");
+	const frame = options?.frame;
+	const csp = options?.csp;
+	const referrer = options?.referrer;
+	const permissions = options?.permissions;
+	const coop = options?.coop;
+	const corp = options?.corp;
+	const cluster = options?.cluster;
+	const coep = options?.coep;
+	const hsts = options?.hsts;
+	const identifierOption = options?.identifier;
+	const identifierEnabled = identifierOption !== false;
+	const trust = isRecord(identifierOption) ? identifierOption.trust === true : false;
+	return async (request, context, next) => {
+		let identifier;
+		if (identifierEnabled) {
+			const incoming = request.headers.get(DEFAULT_IDENTIFIER_HEADER);
+			identifier = trust && incoming !== null && isValidRequestId(incoming) ? incoming : crypto.randomUUID();
+			context.state.identifier = identifier;
+		}
+		const response = await next();
+		response.headers.set("x-content-type-options", "nosniff");
+		const headerTable = [
+			["x-frame-options", resolveSecurityHeader(frame, DEFAULT_FRAME_OPTIONS)],
+			["content-security-policy", resolveSecurityHeader(csp, DEFAULT_CSP)],
+			["referrer-policy", resolveSecurityHeader(referrer, DEFAULT_REFERRER_POLICY)],
+			["permissions-policy", resolveSecurityHeader(permissions, DEFAULT_PERMISSIONS_POLICY)],
+			["cross-origin-opener-policy", resolveSecurityHeader(coop, DEFAULT_COOP)],
+			["cross-origin-resource-policy", resolveSecurityHeader(corp, DEFAULT_CORP)],
+			["origin-agent-cluster", resolveSecurityHeader(cluster, "?1")],
+			["cross-origin-embedder-policy", resolveOptInHeader(coep, DEFAULT_COEP)],
+			["strict-transport-security", resolveOptInHeader(hsts, DEFAULT_HSTS)]
+		];
+		for (const [name, value] of headerTable) if (value !== void 0) response.headers.set(name, value);
+		if (identifierEnabled && identifier !== void 0) response.headers.set(DEFAULT_IDENTIFIER_HEADER, identifier);
+		return response;
+	};
+}
+/**
+* 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'] })
+* ```
+*/
+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");
+	const origin = options?.origin ?? "*";
+	const methods = options?.methods ?? DEFAULT_CORS_METHODS;
+	const headers = options?.headers ?? DEFAULT_CORS_HEADERS;
+	const reflecting = Array.isArray(origin);
+	return async (request, context, next) => {
+		const requestOrigin = request.headers.get("origin") ?? void 0;
+		const allowOrigin = resolveOrigin(origin, requestOrigin);
+		if (isPreflight(context.method, request.headers)) {
+			const preflightHeaders = new Headers();
+			if (allowOrigin !== void 0) preflightHeaders.set("access-control-allow-origin", allowOrigin);
+			preflightHeaders.set("access-control-allow-methods", methods.join(", "));
+			preflightHeaders.set("access-control-allow-headers", headers.join(", "));
+			if (reflecting && allowOrigin !== void 0) preflightHeaders.set("vary", mergeVary(void 0, "Origin"));
+			return new Response(null, {
+				status: 204,
+				headers: preflightHeaders
+			});
+		}
+		const response = await next();
+		if (allowOrigin !== void 0) response.headers.set("access-control-allow-origin", allowOrigin);
+		if (reflecting && allowOrigin !== void 0) response.headers.set("vary", mergeVary(response.headers.get("vary") ?? void 0, "Origin"));
+		return response;
+	};
+}
+/**
+* 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 })
+* ```
+*/
+function createDeadline(options) {
+	if (!isFiniteNumber(options.ms) || options.ms <= 0) throw new TypeError("DeadlineOptions.ms must be a finite number");
+	if (options.status !== void 0 && !isFiniteNumber(options.status)) throw new TypeError("DeadlineOptions.status must be a finite number when provided");
+	const ms = options.ms;
+	const status = options.status ?? 503;
+	return async (request, context, next) => {
+		const timeout = createTimeout({ ms });
+		const linked = linkSignal(timeout.signal, request.signal);
+		timeout.start();
+		const downstream = next(new Request(request, { signal: linked }));
+		const deadline = new Promise((resolve) => {
+			timeout.signal.addEventListener("abort", () => resolve(new Response(null, { status })), { once: true });
+		});
+		let deadlineWon = false;
+		try {
+			return await Promise.race([downstream, deadline.then((response) => {
+				deadlineWon = true;
+				return response;
+			})]);
+		} finally {
+			timeout.clear();
+			downstream.then((response) => {
+				if (deadlineWon) response.body?.cancel().catch(() => {});
+			}).catch(() => {});
+		}
+	};
+}
+/**
+* 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 })
+* ```
+*/
+function createForwarded(options) {
+	const hasProxies = isRecord(options) && "proxies" in options;
+	const hasTrusted = isRecord(options) && "trusted" in 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");
+	} else {
+		const trusted = options.trusted;
+		if (!Array.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) => {
+		const ip = resolveForwardedFor(request.headers.get("x-forwarded-for") ?? void 0, trust) ?? context.state.connection?.ip;
+		context.state.client = buildClientInfo(ip);
+		return next();
+	};
+}
+/**
+* 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 })
+* ```
+*/
+function createETag(options) {
+	if (options?.weak !== void 0 && !isBoolean(options.weak)) throw new TypeError("ETagOptions.weak must be a boolean when provided");
+	const weak = options?.weak ?? true;
+	return async (request, context, next) => {
+		const response = await next();
+		if (context.method !== "GET" || response.status !== 200) return response;
+		if (isBufferingIneligible(context.method, response, "etag")) return response;
+		const buffer = await response.arrayBuffer();
+		const bytes = new Uint8Array(buffer);
+		const etag = await computeBodyETag(bytes, weak);
+		const ifNoneMatch = request.headers.get("if-none-match");
+		if (ifNoneMatch !== null && matchesETag(ifNoneMatch, etag)) {
+			const headers = new Headers(response.headers);
+			headers.set("etag", etag);
+			headers.delete("content-length");
+			return new Response(null, {
+				status: 304,
+				headers
+			});
+		}
+		const headers = new Headers(response.headers);
+		headers.set("etag", etag);
+		return rebuildResponse(bytes, response, headers);
+	};
+}
+/**
+* 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' })
+* ```
+*/
+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 (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;
+	const header = (options.header ?? "authorization").toLowerCase();
+	const scheme = options.scheme ?? "Bearer";
+	return async (request, context, next) => {
+		const raw = request.headers.get(header);
+		if (raw === null) throw new HTTPError(401, "missing token");
+		let candidate = raw;
+		if (scheme !== "") {
+			const prefix = `${scheme.toLowerCase()} `;
+			if (!raw.toLowerCase().startsWith(prefix)) throw new HTTPError(401, "missing token");
+			candidate = raw.slice(prefix.length);
+		}
+		const verified = await verifyToken(candidate, secret);
+		if (verified === void 0) throw new HTTPError(401, "invalid token");
+		context.state.token = verified;
+		return next();
+	};
+}
+/**
+* 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 })
+* ```
+*/
+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 (!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.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");
+	if (options.policy !== void 0 && !isBoolean(options.policy)) throw new TypeError("LimiterOptions.policy must be a boolean when provided");
+	if (options.evict !== void 0 && !isFunction(options.evict)) throw new TypeError("LimiterOptions.evict must be a function when provided");
+	const max = options.max;
+	const window = options.window;
+	const capacity = options.capacity ?? 1e4;
+	const deriveKey = options.key ?? ((context) => resolveKey(context.state));
+	const message = options.message ?? "rate limit exceeded";
+	const clock = options.clock ?? Date.now;
+	const policy = options.policy ?? false;
+	const evict = options.evict;
+	const notify = (evictedKey) => {
+		if (evict === void 0) return;
+		try {
+			evict(evictedKey);
+		} catch {}
+	};
+	const buckets = /* @__PURE__ */ new Map();
+	return async (request, context, next) => {
+		const key = deriveKey(context);
+		const now = clock();
+		let bucket = buckets.get(key);
+		if (bucket === void 0) {
+			if (buckets.size >= capacity) {
+				const oldest = buckets.keys().next().value;
+				if (oldest !== void 0) {
+					buckets.delete(oldest);
+					notify(oldest);
+				}
+			}
+			bucket = {
+				budget: createBudget({
+					max,
+					consume: (value) => value
+				}),
+				resetAt: now + window
+			};
+			buckets.set(key, bucket);
+		} else {
+			buckets.delete(key);
+			buckets.set(key, bucket);
+			if (now >= bucket.resetAt) {
+				bucket.budget.clear();
+				bucket.resetAt = now + window;
+			}
+		}
+		if (bucket.budget.exhausted) {
+			const headers = new Headers();
+			headers.set("retry-after", buildRetryAfter(bucket.resetAt, now));
+			if (policy) {
+				headers.set("ratelimit", buildRateLimitField(0, bucket.resetAt, now));
+				headers.set("ratelimit-policy", buildRateLimitPolicyField(max, window));
+			}
+			return new Response(message, {
+				status: 429,
+				headers
+			});
+		}
+		bucket.budget.consume(1);
+		return next();
+	};
+}
+/**
+* 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()
+* ```
+*/
+function createBody() {
+	return async (request, context, next) => {
+		const body = await context.body();
+		const contentType = request.headers.get("content-type");
+		if (contentType !== null && contentType.toLowerCase().startsWith("application/json") && body === void 0) throw new HTTPError(400, "invalid json");
+		return next();
+	};
+}
+/**
+* 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() })
+* ```
+*/
+function createSession(options) {
+	if (!isFunction(options.transport.read) || !isFunction(options.transport.write) || !isFunction(options.transport.clear)) throw new TypeError("SessionOptions.transport must implement SessionTransport");
+	if (options.store !== void 0 && (!isFunction(options.store.get) || !isFunction(options.store.set) || !isFunction(options.store.delete))) throw new TypeError("SessionOptions.store must implement SessionStoreInterface when provided");
+	if (options.ttl !== void 0 && !isFiniteNumber(options.ttl)) throw new TypeError("SessionOptions.ttl must be a finite number when provided");
+	if (options.lifetime !== void 0 && !isFiniteNumber(options.lifetime)) throw new TypeError("SessionOptions.lifetime must be a finite number when provided");
+	if (options.create !== void 0 && !isFunction(options.create)) throw new TypeError("SessionOptions.create must be a function when provided");
+	if (options.mint !== void 0 && !isFunction(options.mint)) throw new TypeError("SessionOptions.mint must be a function when provided");
+	if (options.require !== void 0 && !isBoolean(options.require)) throw new TypeError("SessionOptions.require must be a boolean when provided");
+	if (options.ends !== void 0 && !isBoolean(options.ends)) throw new TypeError("SessionOptions.ends must be a boolean when provided");
+	if (options.clock !== void 0 && !isFunction(options.clock)) throw new TypeError("SessionOptions.clock must be a function when provided");
+	const transport = options.transport;
+	const clock = options.clock ?? Date.now;
+	const store = options.store ?? new MemorySessionStore({
+		ttl: options.ttl,
+		lifetime: options.lifetime,
+		capacity: options.capacity,
+		evict: options.evict
+	});
+	const create = options.create ?? ((id) => new Session(id));
+	const mint = options.mint;
+	const requireSession = options.require ?? false;
+	const ends = options.ends ?? false;
+	return async (request, context, next) => {
+		const now = clock();
+		const encrypted = context.state.connection?.encrypted ?? false;
+		const incomingId = await transport.read(request);
+		let session = incomingId !== void 0 ? await store.get(incomingId, now) : void 0;
+		if (ends && context.method === "DELETE" && session !== void 0) {
+			await store.delete(session.id);
+			return new Response(null, { status: 204 });
+		}
+		let minted = false;
+		if (session === void 0) {
+			if (mint !== void 0 ? await mint(context) : true) {
+				const id = crypto.randomUUID();
+				session = create(id);
+				minted = true;
+			} else if (requireSession) throw new HTTPError(404, "session required");
+		}
+		let destroyed = false;
+		let regenerated;
+		const activeSession = session;
+		if (activeSession !== void 0) {
+			const control = {
+				regenerate() {
+					if (destroyed) return;
+					const newSession = create(crypto.randomUUID());
+					transferSessionData(activeSession, newSession);
+					regenerated = newSession;
+				},
+				destroy() {
+					destroyed = true;
+					regenerated = void 0;
+				}
+			};
+			context.state.session = activeSession;
+			context.state.control = control;
+		}
+		const response = await next();
+		if (activeSession !== void 0) if (destroyed) {
+			await store.delete(activeSession.id);
+			await transport.clear(response);
+		} else if (regenerated !== void 0) {
+			await store.set(regenerated.id, regenerated, clock());
+			await store.delete(activeSession.id);
+			await transport.write(response, regenerated.id, encrypted);
+		} else {
+			await store.set(activeSession.id, activeSession, clock());
+			if (minted) await transport.write(response, activeSession.id, encrypted);
+		}
+		return response;
+	};
+}
+/**
+* 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' })
+* ```
+*/
+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 (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");
+	const secret = options.secret;
+	const cookieName = options.cookie ?? "csrf";
+	const header = options.header ?? "x-csrf-token";
+	const field = options.field ?? "_csrf";
+	const safe = options.safe ?? DEFAULT_CSRF_SAFE_METHODS;
+	return async (request, context, next) => {
+		if (safe.includes(context.method)) {
+			const token = await signToken(context.state.session?.id ?? crypto.randomUUID(), { secret });
+			context.state.csrf = token;
+			const response = await next();
+			const secure = resolveSecure(void 0, context.state.connection?.encrypted ?? false);
+			await writeSignedCookie(response.headers, cookieName, token, secret, {
+				sameSite: "Strict",
+				httpOnly: false,
+				path: "/",
+				secure
+			});
+			return response;
+		}
+		const headerToken = request.headers.get(header);
+		let submitted;
+		if (headerToken !== null) submitted = headerToken;
+		else {
+			const body = await context.body();
+			if (isRecord(body) && isString(body[field])) submitted = body[field];
+		}
+		if (submitted === void 0) throw new HTTPError(403, "invalid csrf token");
+		const cookieToken = await readSignedCookie(request, cookieName, secret);
+		if (cookieToken === void 0 || !equalsConstantTime(cookieToken, submitted)) throw new HTTPError(403, "invalid csrf token");
+		const sessionId = context.state.session?.id;
+		if (sessionId !== void 0) {
+			if (await verifyToken(cookieToken, secret) !== sessionId) throw new HTTPError(403, "invalid csrf token");
+		}
+		return next();
+	};
+}
+//#endregion
+//#region src/core/factories.ts
+/**
+* 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' })
+* ```
+*/
+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 (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;
+	const cookie = options.cookie;
+	return {
+		read(request) {
+			return readSignedCookie(request, name, secret);
+		},
+		async write(response, id, encrypted) {
+			const secure = resolveSecure(cookie?.secure, encrypted);
+			await writeSignedCookie(response.headers, name, id, secret, {
+				...cookie,
+				secure
+			});
+		},
+		clear(response) {
+			clearCookie(response.headers, name, cookie);
+		}
+	};
+}
+/**
+* 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()
+* ```
+*/
+function createHeaderTransport(options) {
+	if (options?.header !== void 0 && !isString(options.header)) throw new TypeError("HeaderTransportOptions.header must be a string when provided");
+	const header = options?.header ?? "session-id";
+	return {
+		read(request) {
+			return request.headers.get(header) ?? void 0;
+		},
+		write(response, id) {
+			response.headers.set(header, id);
+		},
+		clear(response) {
+			response.headers.delete(header);
+		}
+	};
+}
+/**
+* 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 })
+* ```
+*/
+function createMemorySessionStore(options) {
+	return new MemorySessionStore(options);
+}
+//#endregion
+export { DEFAULT_BEARER_HEADER, DEFAULT_BEARER_SCHEME, DEFAULT_CLUSTER, DEFAULT_COEP, DEFAULT_COMPRESSION_ENCODINGS, DEFAULT_COMPRESSION_THRESHOLD, DEFAULT_COOP, DEFAULT_CORP, DEFAULT_CORS_HEADERS, DEFAULT_CORS_METHODS, DEFAULT_CSP, DEFAULT_CSRF_COOKIE, DEFAULT_CSRF_FIELD, DEFAULT_CSRF_HEADER, DEFAULT_CSRF_SAFE_METHODS, DEFAULT_DEADLINE_STATUS, DEFAULT_FRAME_OPTIONS, DEFAULT_HSTS, DEFAULT_IDENTIFIER_HEADER, DEFAULT_LIMITER_CAPACITY, DEFAULT_LIMITER_MESSAGE, DEFAULT_PERMISSIONS_POLICY, DEFAULT_REFERRER_POLICY, DEFAULT_SESSION_CAPACITY, DEFAULT_SESSION_COOKIE, DEFAULT_SESSION_HEADER, MemorySessionStore, Session, buildClientInfo, buildRateLimitField, buildRateLimitPolicyField, buildRetryAfter, compressResponse, createBearer, createBody, createBoundary, createCSRF, createCompression, createCookieTransport, createCors, createDeadline, createETag, createForwarded, createHeaderTransport, createLimiter, createMemorySessionStore, createSecurity, createSession, createTelemetry, detectEncodings, equalsConstantTime, isBufferingIneligible, isCompressionNegotiated, isMultipartBody, isMultipartFile, isPreflight, isSession, isSessionControl, matchesTrustedEntry, rebuildResponse, resolveForwardedFor, resolveKey, resolveOptInHeader, transferSessionData };
+
+//# sourceMappingURL=index.js.map