@orkestrel/middleware 0.0.19 → 0.0.20

package/README.md

@@ -1,12 +1,19 @@
 # @orkestrel/middleware
 
-Batteries for the `@orkestrel/server` middleware seam — the frozen
-`MiddlewareHandler<TState>` / `compose` contract and its substrate ship
-policy-free; this package supplies the policies the server deliberately does
-not: boundary rendering, telemetry, compression, security headers, CORS,
-deadlines, trusted-proxy client facts, ETag, bearer auth, rate limiting, body
-parsing, sessions, CSRF, static files, and multipart uploads — each a typed
-`options => MiddlewareHandler<TState>` factory over the shipped seam.
+> Batteries for the `@orkestrel/server` middleware seam:
+> `create{Noun}(options) => MiddlewareHandler<TState>` factories for error
+> boundaries, telemetry, compression, security headers, CORS, deadlines,
+> trusted-proxy client facts, ETag, bearer authentication, rate limiting, body
+> parsing, sessions, and CSRF in the fetch-native core, plus in-memory assets,
+> static files, streaming multipart uploads, and a `node:zlib` compression
+> sibling in the node face.
+
+Mount the batteries your threat model needs over the `compose` seam: each one
+closes over its guarded options and returns a `MiddlewareHandler<TState>`, and
+its position in the chain decides what it can see. Read
+[`guides/middleware.md`](guides/middleware.md) for the ordering doctrine and
+the security acceptance bar before you fix an order. Part of the `@orkestrel`
+line.
 
 ## Install
 
@@ -40,10 +47,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
 ```
 
 Each battery is a typed `options => MiddlewareHandler<TState>` factory that composes with
-the others through the frozen `@orkestrel/server` seam — mount boundary, telemetry,
-compression, security headers, CORS, rate limiting, sessions (with `MemorySessionStore` or
-`DatabaseSessionStore` over `@orkestrel/database`), CSRF, static files, and multipart uploads
-in any combination, scoped with `only()` / `except()` where needed.
+the others through the frozen `@orkestrel/server` seam, in any combination, scoped with
+`only()` and `except()` where needed.
 
 ## Guides
 

package/dist/src/core/index.cjs

@@ -5,12 +5,12 @@ let _orkestrel_abort = require("@orkestrel/abort");
 let _orkestrel_budget = require("@orkestrel/budget");
 let _orkestrel_timeout = require("@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
@@ -20,28 +20,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([
@@ -54,29 +55,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",
@@ -175,7 +176,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.
@@ -209,13 +210,13 @@ function matchesTrustedEntry(address, entry) {
 	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
@@ -225,7 +226,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
@@ -299,16 +300,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
@@ -347,7 +349,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.
 *
@@ -401,7 +403,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
@@ -463,7 +465,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
@@ -570,7 +572,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).
 *
@@ -593,8 +595,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
@@ -682,7 +684,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.
 *
@@ -761,7 +763,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.
@@ -876,7 +878,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`,
@@ -946,9 +948,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) {
@@ -1037,7 +1050,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}
@@ -1099,7 +1113,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}
@@ -1148,7 +1163,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).
 *
@@ -1185,7 +1200,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}
@@ -1216,7 +1232,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}
@@ -1254,7 +1270,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}
@@ -1290,7 +1307,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}
@@ -1379,7 +1397,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
@@ -1538,8 +1556,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`
@@ -1559,8 +1577,8 @@ function only(paths, handler) {
 	};
 }
 /**
-* 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`