@orkestrel/middleware 0.0.1

package/dist/src/server/index.js

@@ -0,0 +1,1180 @@
+import { createReadStream } from "node:fs";
+import { chmod, copyFile, mkdtemp, open, readFile, realpath, rename, stat, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isFiniteNumber, isFunction, isRecord, isString } from "@orkestrel/contract";
+import { HTTPError, isDangerousKey, matchesETag, parseRange } from "@orkestrel/server";
+import { DEFAULT_COMPRESSION_THRESHOLD, compressResponse } from "../core/index.js";
+import { deflate, gzip } from "node:zlib";
+import { promisify } from "node:util";
+//#region src/server/constants.ts
+/** The HTTP status `createMultipart` renders for each {@link MultipartReason}. */
+var MULTIPART_REASON_STATUS = Object.freeze({
+	limit: 413,
+	malformed: 400,
+	rejected: 415
+});
+/** `createStatic`'s default directory-index filename. */
+var DEFAULT_STATIC_INDEX = "index.html";
+/** `createStatic`'s `fallback: true` default excluded path prefix. */
+var DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
+/** The MIME type served when a file extension has no known mapping. */
+var DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** `createMultipart`'s default per-file byte-size cap. */
+var DEFAULT_MULTIPART_FILE = 10485760;
+/** `createMultipart`'s default maximum file-part count. */
+var DEFAULT_MULTIPART_FILES = 10;
+/** `createMultipart`'s default per-field byte-size cap. */
+var DEFAULT_MULTIPART_FIELD = 65536;
+/** `createMultipart`'s default maximum field-part count. */
+var DEFAULT_MULTIPART_FIELDS = 100;
+/** `createMultipart`'s default combined request-body byte-size cap. */
+var DEFAULT_MULTIPART_TOTAL = 52428800;
+/** The maximum bytes a single multipart part's header block may occupy before it is malformed. */
+var MULTIPART_MAX_HEADER_BLOCK = 16384;
+/** The maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+var MULTIPART_MAX_PREAMBLE = 65536;
+/**
+* Windows reserved device-name stems (CVE-2025-27210) — matched
+* case-insensitively against the segment's stem (before its first `.`).
+*/
+var RESERVED_DEVICE_NAMES = Object.freeze(/* @__PURE__ */ new Set([
+	"CON",
+	"PRN",
+	"AUX",
+	"NUL",
+	"COM1",
+	"COM2",
+	"COM3",
+	"COM4",
+	"COM5",
+	"COM6",
+	"COM7",
+	"COM8",
+	"COM9",
+	"LPT1",
+	"LPT2",
+	"LPT3",
+	"LPT4",
+	"LPT5",
+	"LPT6",
+	"LPT7",
+	"LPT8",
+	"LPT9"
+]));
+/** File-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. */
+var EXTENSION_TYPES = Object.freeze({
+	".html": "text/html; charset=utf-8",
+	".htm": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".xml": "application/xml; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".ico": "image/x-icon",
+	".pdf": "application/pdf",
+	".zip": "application/zip",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".wasm": "application/wasm"
+});
+//#endregion
+//#region src/server/errors.ts
+/**
+* An error `createMultipart` throws when a streamed multipart request fails
+* a mid-stream limit, is structurally malformed, or has a file whose sniffed
+* bytes are rejected by the configured `allowed` MIME list.
+*
+* @remarks
+* Carries the HTTP `status` derived from `reason` (limit → 413, malformed →
+* 400, rejected → 415) and an optional `context` record. Rendered by
+* `createBoundary` like any other `HTTPError`-shaped throw. Narrow a caught
+* value with {@link isMultipartError}.
+*
+* @example
+* ```ts
+* import { MultipartError } from '@orkestrel/middleware/server'
+*
+* throw new MultipartError('limit', 'too many files')
+* ```
+*/
+var MultipartError = class extends Error {
+	status;
+	reason;
+	context;
+	constructor(reason, message, context) {
+		super(message);
+		this.status = MULTIPART_REASON_STATUS[reason];
+		this.reason = reason;
+		this.context = context;
+		Object.defineProperty(this, Symbol.for("@orkestrel/middleware.MultipartError"), { value: true });
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link MultipartError}.
+*
+* @remarks
+* Structural, not `instanceof` — tests that `value` is a non-null object
+* carrying the module-scope brand, a numeric `status`, and a `reason` in the
+* parser's set of reason strings (`'limit' | 'malformed' | 'rejected'`).
+* Total: never throws, returns `false` for any off-shape input.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link MultipartError}
+*
+* @example
+* ```ts
+* import { isMultipartError } from '@orkestrel/middleware/server'
+*
+* try {
+* 	await parse(request)
+* } catch (error) {
+* 	if (isMultipartError(error)) console.log(error.status, error.reason)
+* }
+* ```
+*/
+function isMultipartError(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!(Symbol.for("@orkestrel/middleware.MultipartError") in value)) return false;
+	if (!("status" in value) || !("reason" in value)) return false;
+	if (typeof value.status !== "number") return false;
+	if (value.reason !== "limit" && value.reason !== "malformed" && value.reason !== "rejected") return false;
+	return true;
+}
+//#endregion
+//#region src/server/helpers.ts
+/**
+* Whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+* boundary — the shared under-path test `resolveStaticPath`'s prefix strip
+* and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
+* '/api'` matches `/api` and `/api/x` but never `/apifoo`.
+*
+* @param pathname - The request pathname to test
+* @param prefix - The path prefix to test against
+* @returns `true` when `pathname` equals `prefix` or starts with `prefix` + `/`
+*
+* @example
+* ```ts
+* isUnderPath('/api/x', '/api') // true
+* isUnderPath('/apifoo', '/api') // false
+* ```
+*/
+function isUnderPath(pathname, prefix) {
+	if (pathname === prefix) return true;
+	const boundary = prefix.endsWith("/") ? prefix : `${prefix}/`;
+	return pathname.startsWith(boundary);
+}
+/**
+* Whether `child` is `parent` itself or lies inside it on-disk — the
+* FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
+* output (never to a URL pathname — that is {@link isUnderPath}'s job).
+*
+* @remarks
+* Argument order is `(child, parent)` — deliberately the OPPOSITE conceptual
+* order from {@link isUnderPath}`(pathname, prefix)`, so a call site cannot
+* casually swap one predicate in for the other. Built on `path.relative`,
+* this is separator-correct on both POSIX (`/`) and win32 (`\`) — unlike a
+* hardcoded `${parent}/` boundary check, which silently fails to match every
+* realpath on Windows — and case-folds on win32 because `path.relative` does.
+*
+* @param child - The absolute on-disk path to test
+* @param parent - The absolute on-disk directory it must lie under
+* @returns `true` when `child` equals `parent` or resolves inside it
+*
+* @example
+* ```ts
+* isContainedPath('/srv/public/a.html', '/srv/public') // true
+* isContainedPath('/srv/other/a.html', '/srv/public') // false
+* ```
+*/
+function isContainedPath(child, parent) {
+	if (child === parent) return true;
+	const rel = relative(parent, child);
+	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+* Resolve a request pathname to an on-disk path UNDER `root`, or `undefined`
+* when it cannot — the traversal guard, EXACT algorithm and order (PROPOSAL
+* §4.14): strip `prefix` on a segment boundary → `decodeURIComponent` (a
+* malformed escape refuses, never throws) → reject a NUL byte → strip the
+* leading path separator FIRST (so a leading `..` survives `normalize` as a
+* genuine climbing segment) → `normalize` → refuse any Windows reserved-
+* device-name segment ({@link isReservedDeviceName}) → `resolve` and require
+* the result under `root`.
+*
+* @param root - The absolute root directory every result must resolve under
+* @param prefix - An optional URL path prefix stripped on a segment boundary
+* @param pathname - The raw request pathname
+* @returns The resolved absolute path under `root`, or `undefined` when the
+* request does not resolve (out of prefix, malformed escape, NUL byte,
+* reserved device name, or an attempted escape from `root`)
+*
+* @example
+* ```ts
+* resolveStaticPath('/srv/public', '/api', '/api/../../etc/passwd') // undefined
+* ```
+*/
+function resolveStaticPath(root, prefix, pathname) {
+	let remainder = pathname;
+	if (prefix !== void 0) {
+		if (!isUnderPath(pathname, prefix)) return void 0;
+		remainder = pathname === prefix ? "/" : pathname.slice(prefix.length);
+	}
+	let decoded;
+	try {
+		decoded = decodeURIComponent(remainder);
+	} catch {
+		return;
+	}
+	if (decoded.includes("\0")) return void 0;
+	const normalized = normalize(decoded.replace(/^[/\\]+/, ""));
+	const segments = normalized.split(/[/\\]+/).filter((segment) => segment.length > 0);
+	for (const segment of segments) if (isReservedDeviceName(segment)) return void 0;
+	const resolved = resolve(root, normalized);
+	if (resolved === root || resolved.startsWith(`${root}${sep}`)) return resolved;
+}
+/**
+* Whether a path segment is a Windows reserved device name (CVE-2025-27210).
+*
+* @remarks
+* Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
+* and spaces (Windows drops them), takes the STEM before the first `.`,
+* upper-cases it, and tests it against {@link RESERVED_DEVICE_NAMES}
+* (`CON PRN AUX NUL COM1-9 LPT1-9`) — an exact-stem match only, so
+* `console.js` and `nullable.css` are never flagged.
+*
+* @param segment - One path segment (no separators)
+* @returns `true` when `segment` names a reserved device
+*
+* @example
+* ```ts
+* isReservedDeviceName('NUL.json') // true
+* isReservedDeviceName('nullable.css') // false
+* isReservedDeviceName('CON¹') // true
+* ```
+*/
+function isReservedDeviceName(segment) {
+	const stem = segment.replace(/[¹²³]/g, (digit) => digit === "¹" ? "1" : digit === "²" ? "2" : "3").replace(/[. ]+$/, "").split(".")[0];
+	if (stem === void 0 || stem.length === 0) return false;
+	return RESERVED_DEVICE_NAMES.has(stem.toUpperCase());
+}
+/**
+* Whether a relative path (already resolved under a static root) has any
+* segment starting with `.` — a dotfile or dot-directory.
+*
+* @param relativePath - A path relative to the static root
+* @returns `true` when any segment starts with `.`
+*
+* @example
+* ```ts
+* isDotfilePath('.env') // true
+* isDotfilePath('a/.git/config') // true
+* ```
+*/
+function isDotfilePath(relativePath) {
+	return relativePath.split(/[/\\]+/).some((segment) => segment.startsWith("."));
+}
+/**
+* Look up the MIME type for a static file path by its extension.
+*
+* @param pathname - The file's path (only its extension is read)
+* @returns The mapped MIME type, or {@link DEFAULT_CONTENT_TYPE} when unknown
+*
+* @example
+* ```ts
+* lookupContentType('/a/b.css') // 'text/css; charset=utf-8'
+* ```
+*/
+function lookupContentType(pathname) {
+	return EXTENSION_TYPES[extname(pathname).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+* Compute a static file's weak ETag from its size and modification time.
+*
+* @param size - The file's byte size
+* @param mtimeMs - The file's modification time in milliseconds
+* @returns A weak entity-tag `W/"<size>-<floor(mtimeMs)>"`
+*
+* @example
+* ```ts
+* computeFileETag(1024, 1700000000123.4) // 'W/"1024-1700000000123"'
+* ```
+*/
+function computeFileETag(size, mtimeMs) {
+	return `W/"${size}-${Math.floor(mtimeMs)}"`;
+}
+/**
+* Sniff a MIME type from a file's leading bytes against a small magic-byte
+* table (jpeg, png, gif87a/89a, webp, pdf, zip) — the SNIFF-AUTHORITATIVE
+* signal `createMultipart`'s type validation rests on, never the declared
+* `Content-Type`.
+*
+* @param head - The file's first bytes (16 is sufficient for every signature)
+* @returns The detected MIME type, or `undefined` when no signature matches
+*
+* @example
+* ```ts
+* detectMIME(Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) // 'image/png'
+* ```
+*/
+function detectMIME(head) {
+	function matches(signature, offset = 0) {
+		if (head.length < offset + signature.length) return false;
+		for (let index = 0; index < signature.length; index += 1) if (head[offset + index] !== signature[index]) return false;
+		return true;
+	}
+	if (matches([
+		255,
+		216,
+		255
+	])) return "image/jpeg";
+	if (matches([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) return "image/png";
+	if (matches([
+		71,
+		73,
+		70,
+		56,
+		55,
+		97
+	])) return "image/gif";
+	if (matches([
+		71,
+		73,
+		70,
+		56,
+		57,
+		97
+	])) return "image/gif";
+	if (matches([
+		82,
+		73,
+		70,
+		70
+	]) && matches([
+		87,
+		69,
+		66,
+		80
+	], 8)) return "image/webp";
+	if (matches([
+		37,
+		80,
+		68,
+		70,
+		45
+	])) return "application/pdf";
+	if (matches([
+		80,
+		75,
+		3,
+		4
+	]) || matches([
+		80,
+		75,
+		5,
+		6
+	]) || matches([
+		80,
+		75,
+		7,
+		8
+	])) return "application/zip";
+}
+/**
+* Extract the `boundary` parameter from a `Content-Type` header, or
+* `undefined` when the request is not `multipart/form-data`.
+*
+* @param contentType - The request's `Content-Type` header value, if present
+* @returns The multipart boundary token, or `undefined` for a non-multipart
+* (or malformed/boundary-less) content type
+*
+* @example
+* ```ts
+* multipartBoundary('multipart/form-data; boundary=abc123') // 'abc123'
+* multipartBoundary('application/json') // undefined
+* ```
+*/
+function multipartBoundary(contentType) {
+	if (contentType === null) return void 0;
+	const [type, ...params] = contentType.split(";").map((part) => part.trim());
+	if (type === void 0 || type.toLowerCase() !== "multipart/form-data") return void 0;
+	for (const param of params) {
+		const equals = param.indexOf("=");
+		if (equals === -1) continue;
+		if (param.slice(0, equals).trim().toLowerCase() !== "boundary") continue;
+		let value = param.slice(equals + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") && value.length >= 2) value = value.slice(1, -1);
+		return value.length > 0 ? value : void 0;
+	}
+}
+/**
+* Resolve `createMultipart`'s effective {@link MultipartLimits}, applying
+* every documented default.
+*
+* @param limits - The caller's partial limits
+* @returns The fully-resolved limits
+*/
+function resolveMultipartLimits(limits) {
+	return {
+		file: limits?.file ?? 10485760,
+		files: limits?.files ?? 10,
+		field: limits?.field ?? 65536,
+		fields: limits?.fields ?? 100,
+		total: limits?.total ?? 52428800
+	};
+}
+/**
+* Memoized `Promise` for `parseMultipartRequest`'s lazily-created default
+* staging directory — created once per process via {@link resolveDefaultDirectory}.
+*/
+var defaultDirectory;
+/**
+* Resolve `parseMultipartRequest`'s default staging directory when the
+* caller did not configure one — a process-owned directory created ONCE
+* (lazily, memoized across calls) via `mkdtemp` under `os.tmpdir()` and
+* locked to mode `0o700`.
+*
+* @returns The absolute path of the process-owned staging directory
+*
+* @example
+* ```ts
+* const directory = await resolveDefaultDirectory()
+* ```
+*/
+function resolveDefaultDirectory() {
+	if (defaultDirectory === void 0) defaultDirectory = (async () => {
+		const path = await mkdtemp(join(tmpdir(), "orkestrel-multipart-"));
+		await chmod(path, 448);
+		return path;
+	})();
+	return defaultDirectory;
+}
+/**
+* Parse one multipart part's raw header block into its `name` (from
+* `Content-Disposition`), optional `filename`, and optional `Content-Type`.
+*
+* @param block - The raw header block for one multipart part (before the
+* terminating blank line)
+* @returns The parsed `name`, `filename`, and `contentType` (each
+* `undefined` when absent)
+*
+* @example
+* ```ts
+* parsePartHeaders('Content-Disposition: form-data; name="title"')
+* // { name: 'title', filename: undefined, contentType: undefined }
+* ```
+*/
+function parsePartHeaders(block) {
+	let name;
+	let filename;
+	let contentType;
+	for (const line of block.split("\r\n")) {
+		const colon = line.indexOf(":");
+		if (colon === -1) continue;
+		const key = line.slice(0, colon).trim().toLowerCase();
+		const value = line.slice(colon + 1).trim();
+		if (key === "content-disposition") {
+			const nameMatch = /;\s*name="([^"]*)"/.exec(value);
+			const filenameMatch = /;\s*filename="([^"]*)"/.exec(value);
+			if (nameMatch !== null) name = nameMatch[1];
+			if (filenameMatch !== null) filename = filenameMatch[1];
+		} else if (key === "content-type") contentType = value;
+	}
+	return {
+		name,
+		filename,
+		contentType
+	};
+}
+/**
+* Stream-parse a `multipart/form-data` request into its files and fields —
+* the mid-stream state machine `createMultipart` drives (PROPOSAL §4.15).
+*
+* @remarks
+* Reads `request.body` chunk by chunk via its `ReadableStream` reader —
+* NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
+* the instant it is exceeded (reading stops, every already-staged temp file
+* is deleted, throws {@link MultipartError} with reason `'limit'`). Each file
+* part streams to `join(directory, randomUUID())` — the client's declared
+* filename is METADATA ONLY, never a path component. A field OR file part
+* named `__proto__` / `constructor` / `prototype` is silently skipped and
+* never keyed onto the returned {@link MultipartBody} (a skipped file's
+* staged temp file is unlinked immediately, since it can never be
+* referenced). A file part with an empty declared filename (`filename=""`)
+* AND a zero-byte body — the browser convention for an unselected optional
+* `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
+* never counted against the `files` limit, and it never runs the `allowed`
+* check. A malformed
+* structure (missing/unterminated boundary, nameless part, an oversized
+* header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
+* the first boundary) throws with reason `'malformed'`. A file is accepted
+* against the configured `allowed` MIME list iff its SNIFFED bytes detect a
+* type present in the list — sniff-authoritative, independent of whether the
+* declared `Content-Type` matches (that agreement is exposed separately as
+* `validated`); otherwise throws with reason `'rejected'`. A
+* request abort mid-upload triggers the same fail-closed cleanup as a limit
+* breach. Returns `undefined` for a non-multipart request (untouched).
+*
+* @param request - The incoming multipart request
+* @param options - See {@link MultipartOptions}
+* @returns The parsed {@link MultipartBody}, or `undefined` when the request
+* is not `multipart/form-data`
+* @throws {MultipartError} On any limit breach, malformed structure, or
+* rejected file type
+*
+* @example
+* ```ts
+* const body = await parseMultipartRequest(request, { allowed: ['image/png'] })
+* ```
+*/
+async function parseMultipartRequest(request, options = {}) {
+	const boundary = multipartBoundary(request.headers.get("content-type"));
+	if (boundary === void 0) return void 0;
+	if (request.body === null) throw new MultipartError("malformed", "multipart request has no body");
+	const limits = resolveMultipartLimits(options.limits);
+	const allowed = options.allowed;
+	const directory = options.directory ?? await resolveDefaultDirectory();
+	const staged = [];
+	const files = Object.create(null);
+	const fields = Object.create(null);
+	let fileCount = 0;
+	let fieldCount = 0;
+	let totalBytes = 0;
+	let aborted = false;
+	async function cleanup() {
+		for (const path of staged) try {
+			await unlink(path);
+		} catch {}
+	}
+	const reader = request.body.getReader();
+	let buffer = Buffer.alloc(0);
+	let ended = false;
+	const onAbort = () => {
+		aborted = true;
+	};
+	request.signal.addEventListener("abort", onAbort);
+	async function pull() {
+		if (aborted || request.signal.aborted) throw new MultipartError("malformed", "request aborted mid-upload");
+		if (ended) return false;
+		const { done, value } = await reader.read();
+		if (done) {
+			ended = true;
+			return false;
+		}
+		totalBytes += value.byteLength;
+		if (totalBytes > limits.total) throw new MultipartError("limit", "multipart body exceeds total limit");
+		buffer = Buffer.concat([buffer, Buffer.from(value.buffer, value.byteOffset, value.byteLength)]);
+		return true;
+	}
+	try {
+		const openMarker = Buffer.from(`--${boundary}`);
+		let preambleScanned = 0;
+		let index = buffer.indexOf(openMarker);
+		while (index === -1) {
+			const carry = openMarker.length - 1;
+			if (buffer.length > carry) {
+				const drop = buffer.length - carry;
+				preambleScanned += drop;
+				if (preambleScanned > 65536) throw new MultipartError("malformed", "multipart preamble too large");
+				buffer = buffer.subarray(drop);
+			}
+			if (!await pull()) throw new MultipartError("malformed", "missing multipart boundary");
+			index = buffer.indexOf(openMarker);
+		}
+		buffer = buffer.subarray(index + openMarker.length);
+		for (;;) {
+			while (buffer.length < 2) if (!await pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
+			if (buffer[0] === 45 && buffer[1] === 45) break;
+			if (buffer[0] !== 13 || buffer[1] !== 10) throw new MultipartError("malformed", "malformed multipart boundary");
+			buffer = buffer.subarray(2);
+			let headerEnd = buffer.indexOf("\r\n\r\n");
+			while (headerEnd === -1) {
+				if (buffer.length > 16384) throw new MultipartError("malformed", "multipart header block too large");
+				if (!await pull()) throw new MultipartError("malformed", "unterminated multipart part headers");
+				headerEnd = buffer.indexOf("\r\n\r\n");
+			}
+			const headerBlock = buffer.subarray(0, headerEnd).toString("utf8");
+			buffer = buffer.subarray(headerEnd + 4);
+			const { name, filename, contentType } = parsePartHeaders(headerBlock);
+			if (name === void 0) throw new MultipartError("malformed", "multipart part missing name");
+			const partDelimiter = Buffer.from(`\r\n--${boundary}`);
+			if (filename !== void 0) {
+				if (filename !== "") {
+					fileCount += 1;
+					if (fileCount > limits.files) throw new MultipartError("limit", "too many multipart files");
+				}
+				const path = join(directory, randomUUID());
+				staged.push(path);
+				const handle = await open(path, "w", 384);
+				let size = 0;
+				let head = Buffer.alloc(0);
+				try {
+					for (;;) {
+						const boundaryIndex = buffer.indexOf(partDelimiter);
+						if (boundaryIndex === -1) {
+							const safeLength = Math.max(0, buffer.length - (partDelimiter.length - 1));
+							if (safeLength > 0) {
+								const chunk = buffer.subarray(0, safeLength);
+								size += chunk.length;
+								if (size > limits.file) throw new MultipartError("limit", "multipart file exceeds size limit");
+								if (head.length < 16) head = Buffer.concat([head, chunk.subarray(0, 16 - head.length)]);
+								await handle.write(chunk);
+								buffer = buffer.subarray(safeLength);
+							}
+							if (!await pull()) throw new MultipartError("malformed", "unterminated multipart file part");
+							continue;
+						}
+						const chunk = buffer.subarray(0, boundaryIndex);
+						size += chunk.length;
+						if (size > limits.file) throw new MultipartError("limit", "multipart file exceeds size limit");
+						if (head.length < 16) head = Buffer.concat([head, chunk.subarray(0, 16 - head.length)]);
+						await handle.write(chunk);
+						buffer = buffer.subarray(boundaryIndex + 2);
+						break;
+					}
+				} finally {
+					await handle.close();
+				}
+				if (filename === "" && size === 0) {
+					await unlink(path);
+					staged.splice(staged.indexOf(path), 1);
+				} else {
+					if (filename === "") {
+						fileCount += 1;
+						if (fileCount > limits.files) throw new MultipartError("limit", "too many multipart files");
+					}
+					const detected = detectMIME(head);
+					const declared = contentType ?? "application/octet-stream";
+					const validated = detected !== void 0 && detected === declared;
+					if (allowed !== void 0) {
+						if (!(detected !== void 0 && allowed.includes(detected))) throw new MultipartError("rejected", "multipart file failed type validation");
+					}
+					if (isDangerousKey(name)) {
+						await unlink(path);
+						staged.splice(staged.indexOf(path), 1);
+					} else {
+						const record = createUploadedFile({
+							field: name,
+							name: filename,
+							size,
+							mime: detected ?? declared,
+							validated,
+							status: "staged",
+							path
+						});
+						const existing = files[name];
+						if (existing === void 0) files[name] = [record];
+						else existing.push(record);
+					}
+				}
+			} else {
+				fieldCount += 1;
+				if (fieldCount > limits.fields) throw new MultipartError("limit", "too many multipart fields");
+				let value = Buffer.alloc(0);
+				for (;;) {
+					const boundaryIndex = buffer.indexOf(partDelimiter);
+					if (boundaryIndex === -1) {
+						const safeLength = Math.max(0, buffer.length - (partDelimiter.length - 1));
+						if (safeLength > 0) {
+							value = Buffer.concat([value, buffer.subarray(0, safeLength)]);
+							if (value.length > limits.field) throw new MultipartError("limit", "multipart field exceeds size limit");
+							buffer = buffer.subarray(safeLength);
+						}
+						if (!await pull()) throw new MultipartError("malformed", "unterminated multipart field part");
+						continue;
+					}
+					value = Buffer.concat([value, buffer.subarray(0, boundaryIndex)]);
+					if (value.length > limits.field) throw new MultipartError("limit", "multipart field exceeds size limit");
+					buffer = buffer.subarray(boundaryIndex + 2);
+					break;
+				}
+				if (!isDangerousKey(name)) fields[name] = value.toString("utf8");
+			}
+			while (buffer.length < openMarker.length) if (!await pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
+			buffer = buffer.subarray(openMarker.length);
+		}
+	} catch (error) {
+		await cleanup();
+		await reader.cancel().catch(() => {});
+		throw error;
+	} finally {
+		request.signal.removeEventListener("abort", onAbort);
+		if (!ended) await reader.cancel().catch(() => {});
+	}
+	return {
+		files: Object.freeze(files),
+		fields: Object.freeze(fields)
+	};
+}
+/**
+* Build a frozen {@link UploadedFileInterface} record.
+*
+* @param input - Every field of the record
+* @returns A frozen {@link UploadedFileInterface}
+*
+* @example
+* ```ts
+* createUploadedFile({ field: 'avatar', name: 'a.png', size: 1024, mime: 'image/png', validated: true, status: 'staged', path: '/tmp/x' })
+* ```
+*/
+function createUploadedFile(input) {
+	return Object.freeze({ ...input });
+}
+/**
+* Best-effort unlink every still-`'staged'` file in a parsed
+* {@link MultipartBody} — the fail-closed cleanup `createMultipart` runs when
+* its downstream handler throws, mirroring `parseMultipartRequest`'s own
+* cleanup pattern (a missing file is already gone; failures are swallowed).
+*
+* @param body - The parsed multipart body to clean up
+* @returns A promise that resolves once every staged file has been attempted
+*
+* @example
+* ```ts
+* await unlinkStagedFiles(body)
+* ```
+*/
+async function unlinkStagedFiles(body) {
+	for (const records of Object.values(body.files)) for (const file of records) {
+		if (file.status !== "staged") continue;
+		try {
+			await unlink(file.path);
+		} catch {}
+	}
+}
+/**
+* Adapt a `node:fs` read stream over `path` (or an already-open
+* `FileHandle`) into a DOM-compatible `ReadableStream<Uint8Array>` — the
+* single shared node↔web stream bridge every static-file and uploaded-file
+* response body routes through.
+*
+* @remarks
+* PULL-driven, not push-driven: the underlying node stream's async iterator
+* is only advanced (`iterator.next()`) from inside `pull(controller)`, which
+* the web `ReadableStream` invokes exactly when its internal queue has room
+* for more data. Exactly one disk chunk is read and enqueued per `pull` —
+* never more — so a slow or stalled consumer (a stalled HTTP connection)
+* simply stops triggering `pull` calls and the source stops reading ahead;
+* this is genuine consumer backpressure, not the "naturally backpressured"
+* `for await`/`enqueue` pattern (which does not block on a slow consumer at
+* all, since `enqueue` returns synchronously). The controller is closed on
+* iterator completion and errored (never thrown into the process) on a
+* mid-stream read failure. Cancelling the returned `ReadableStream` (e.g. the
+* consumer aborts the response) calls the iterator's `return()`, which
+* destroys the underlying node read stream so the file descriptor is
+* released. When `path` is a `FileHandle`, `FileHandle.createReadStream`'s
+* default `autoClose` closes the handle on every terminal path (end, error,
+* or `destroy()` via the iterator's `return()`) — the caller never needs a
+* separate `handle.close()` for a handle passed here.
+*
+* @param source - The absolute on-disk file path to stream, or an already-open
+* `FileHandle` (e.g. one already `fstat`'d so the served bytes match the
+* headers computed from that same `fstat`)
+* @param range - An optional inclusive byte range (`start`/`end`, both
+* 0-indexed and inclusive, matching `node:fs`'s `createReadStream` options)
+* @returns A `ReadableStream<Uint8Array>` valid as a fetch `BodyInit`
+*
+* @example
+* ```ts
+* new Response(streamFile('/srv/public/index.html'))
+* ```
+*/
+function streamFile(source, range) {
+	const iterator = (typeof source === "string" ? range === void 0 ? createReadStream(source) : createReadStream(source, {
+		start: range.start,
+		end: range.end
+	}) : range === void 0 ? source.createReadStream() : source.createReadStream({
+		start: range.start,
+		end: range.end
+	}))[Symbol.asyncIterator]();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const { done, value } = await iterator.next();
+				if (done) {
+					controller.close();
+					return;
+				}
+				if (!(value instanceof Uint8Array)) {
+					await iterator.return?.();
+					controller.error(/* @__PURE__ */ new TypeError("streamFile: read stream yielded a non-Uint8Array chunk"));
+					return;
+				}
+				controller.enqueue(value);
+			} catch (error) {
+				await iterator.return?.();
+				controller.error(error);
+			}
+		},
+		async cancel() {
+			await iterator.return?.();
+		}
+	});
+}
+/**
+* Open a staged/moved uploaded file as a web `ReadableStream`.
+*
+* @param file - The {@link UploadedFileInterface} record to stream
+* @returns A `ReadableStream<Uint8Array>` over the file's current on-disk path
+*
+* @example
+* ```ts
+* new Response(streamUploadedFile(file))
+* ```
+*/
+function streamUploadedFile(file) {
+	return streamFile(file.path);
+}
+/**
+* Read a staged/moved uploaded file's full contents into memory.
+*
+* @param file - The {@link UploadedFileInterface} record to read
+* @returns The file's bytes
+*
+* @example
+* ```ts
+* const bytes = await readUploadedFile(file)
+* ```
+*/
+async function readUploadedFile(file) {
+	return readFile(file.path);
+}
+/**
+* Move a staged uploaded file to its final `destination`.
+*
+* @remarks
+* Attempts a `rename` first; on a cross-device error (`EXDEV`) falls back to
+* `copyFile` + `unlink`. Returns a new frozen record with `status: 'moved'`
+* and `path: destination` — the input record is never mutated.
+*
+* @param file - The {@link UploadedFileInterface} record to move
+* @param destination - The final on-disk path
+* @returns A new {@link UploadedFileInterface} record reflecting the move
+*
+* @example
+* ```ts
+* const moved = await moveUploadedFile(file, '/var/uploads/final.png')
+* ```
+*/
+async function moveUploadedFile(file, destination) {
+	try {
+		await rename(file.path, destination);
+	} catch (error) {
+		if (isRecord(error) && error.code === "EXDEV") {
+			await copyFile(file.path, destination);
+			await unlink(file.path);
+		} else throw error;
+	}
+	return createUploadedFile({
+		field: file.field,
+		name: file.name,
+		size: file.size,
+		mime: file.mime,
+		validated: file.validated,
+		status: "moved",
+		path: destination
+	});
+}
+//#endregion
+//#region src/server/middlewares.ts
+/**
+* Serve static files from `options.root` over `node:fs` — the node-bound
+* static-file battery (PROPOSAL §4.14).
+*
+* @remarks
+* Containment is enforced on CANONICAL paths, not merely the lexically
+* resolved one: `options.root` is canonicalized once (memoized) and every
+* request's candidate path is re-canonicalized (`fs.realpath`) before it is
+* served, so a symlink whose target escapes `root` is refused (falls through
+* to `next()`) even though the lexical path resolved inside `root`. A
+* symlink that resolves to a target still INSIDE `root` is unaffected and
+* still serves normally. A dangling symlink (`realpath` throws `ENOENT`) or
+* any other `realpath` failure is treated as a miss — this battery never
+* throws or 500s on a symlink surprise. On a streamed response (a 200 or 206
+* that carries a file body), the open `FileHandle` is owned by the
+* `Response` body and is released only once that body is fully read or
+* cancelled — Node HTTP servers do this automatically when sending the
+* response, but a caller that holds an unread `Response` (e.g. in a test)
+* must cancel its body to release the handle promptly.
+*
+* @typeParam TState - The consumer's opaque per-request state type
+* @param options - See {@link StaticOptions}
+* @returns A `MiddlewareHandler<TState>`
+* @throws {TypeError} When `options.root` is not a non-empty string
+*
+* @example
+* ```ts
+* import { createStatic } from '@orkestrel/middleware/server'
+*
+* const serveFiles = createStatic({ root: '/srv/public', fallback: true })
+* ```
+*/
+function createStatic(options) {
+	if (!isString(options.root) || options.root.length === 0) throw new TypeError("createStatic requires options.root to be a non-empty string");
+	const root = resolve(options.root);
+	const index = options.index ?? "index.html";
+	const dotfiles = options.dotfiles ?? "ignore";
+	const useETag = options.etag ?? true;
+	const fallback = options.fallback === true ? { exclude: DEFAULT_STATIC_FALLBACK_EXCLUDE } : options.fallback === false || options.fallback === void 0 ? void 0 : { exclude: options.fallback.exclude ?? "/api" };
+	let canonicalRootPromise;
+	function canonicalRoot() {
+		if (canonicalRootPromise === void 0) canonicalRootPromise = realpath(root);
+		return canonicalRootPromise;
+	}
+	return async (request, context, next) => {
+		if (context.method !== "GET" && context.method !== "HEAD") return next();
+		const target = resolveStaticPath(root, options.prefix, context.url.pathname);
+		if (target === void 0) return next();
+		const relativePath = relative(root, target);
+		if (relativePath.length > 0 && isDotfilePath(relativePath)) {
+			if (dotfiles === "deny") throw new HTTPError(403, "forbidden");
+			if (dotfiles === "ignore") return next();
+		}
+		let resolvedPath;
+		try {
+			const [rootReal, targetReal] = await Promise.all([canonicalRoot(), realpath(target)]);
+			if (!isContainedPath(targetReal, rootReal)) return next();
+			resolvedPath = targetReal;
+		} catch {
+			return trySpaFallback();
+		}
+		let directoryInfo;
+		try {
+			directoryInfo = await stat(resolvedPath);
+		} catch {
+			return trySpaFallback();
+		}
+		if (directoryInfo.isDirectory()) {
+			resolvedPath = join(resolvedPath, index);
+			try {
+				const [rootReal, indexReal] = await Promise.all([canonicalRoot(), realpath(resolvedPath)]);
+				if (!isContainedPath(indexReal, rootReal)) return trySpaFallback();
+				resolvedPath = indexReal;
+			} catch {
+				return trySpaFallback();
+			}
+		}
+		let handle;
+		try {
+			handle = await open(resolvedPath, "r");
+		} catch {
+			return trySpaFallback();
+		}
+		let info;
+		try {
+			info = await handle.stat();
+		} catch {
+			await handle.close();
+			return trySpaFallback();
+		}
+		if (!info.isFile()) {
+			await handle.close();
+			return trySpaFallback();
+		}
+		let streaming = false;
+		try {
+			const headers = new Headers({
+				"content-type": lookupContentType(resolvedPath),
+				"accept-ranges": "bytes"
+			});
+			if (options.cache !== void 0) headers.set("cache-control", `max-age=${options.cache}`);
+			if (useETag) {
+				const etag = computeFileETag(info.size, info.mtimeMs);
+				headers.set("etag", etag);
+				const ifNoneMatch = request.headers.get("if-none-match");
+				if (ifNoneMatch !== null && matchesETag(ifNoneMatch, etag)) {
+					await handle.close();
+					return new Response(null, {
+						status: 304,
+						headers
+					});
+				}
+			}
+			if (context.method === "HEAD") {
+				await handle.close();
+				headers.set("content-length", String(info.size));
+				return new Response(null, {
+					status: 200,
+					headers
+				});
+			}
+			const rangeHeader = request.headers.get("range");
+			const range = parseRange(rangeHeader === null ? void 0 : rangeHeader, info.size);
+			if (range === void 0) {
+				headers.set("content-length", String(info.size));
+				const body = streamFile(handle);
+				streaming = true;
+				return new Response(body, {
+					status: 200,
+					headers
+				});
+			}
+			if (!range.satisfiable) {
+				await handle.close();
+				headers.set("content-range", `bytes */${info.size}`);
+				return new Response(null, {
+					status: 416,
+					headers
+				});
+			}
+			headers.set("content-range", `bytes ${range.start}-${range.end}/${info.size}`);
+			headers.set("content-length", String(range.end - range.start + 1));
+			const body = streamFile(handle, {
+				start: range.start,
+				end: range.end
+			});
+			streaming = true;
+			return new Response(body, {
+				status: 206,
+				headers
+			});
+		} catch (error) {
+			if (!streaming) await handle.close().catch(() => {});
+			throw error;
+		}
+		function trySpaFallback() {
+			if (fallback === void 0) return next();
+			if (context.method !== "GET") return next();
+			if (extname(context.url.pathname) !== "") return next();
+			const accept = request.headers.get("accept") ?? "";
+			if (!accept.includes("text/html") && !accept.includes("*/*")) return next();
+			if (isUnderPath(context.url.pathname, fallback.exclude)) return next();
+			const shellPath = join(root, index);
+			return Promise.all([canonicalRoot(), realpath(shellPath)]).then(([rootReal, shellReal]) => {
+				if (!isContainedPath(shellReal, rootReal)) return next();
+				return open(shellReal, "r").then((shellHandle) => {
+					let shellStreaming = false;
+					try {
+						const body = streamFile(shellHandle);
+						shellStreaming = true;
+						return new Response(body, {
+							status: 200,
+							headers: new Headers({ "content-type": lookupContentType(shellReal) })
+						});
+					} catch (error) {
+						if (!shellStreaming) shellHandle.close().catch(() => {});
+						throw error;
+					}
+				});
+			}).catch(() => next());
+		}
+	};
+}
+/**
+* Parse a streamed `multipart/form-data` request body and stash its
+* {@link MultipartBody} on `context.state.multipart` — the node-bound
+* streaming multipart battery (PROPOSAL §4.15, ruling C).
+*
+* @remarks
+* A non-multipart request passes through untouched. Consumes `request.body`
+* as a stream — `context.body()` must not be called for a request this
+* battery has processed (the underlying stream is exhausted). Every
+* {@link MultipartError} this battery's parser throws is re-thrown as an
+* {@link HTTPError} carrying the same status/message, so `createBoundary`
+* (or any HTTPError-aware renderer) maps it correctly without depending on
+* this node face's error type. Fail-closed on the DOWNSTREAM handler too: if
+* `next()` throws, every still-`'staged'` uploaded file is unlinked
+* (best-effort) before the error is re-thrown, so an unhandled downstream
+* failure never leaks temp files. A normal return leaves staged files
+* untouched — the downstream handler owns moving/reading them.
+*
+* @typeParam TState - The consumer's state type, extending {@link MultipartState}
+* @param options - See {@link MultipartOptions}
+* @returns A `MiddlewareHandler<TState>`
+* @throws {HTTPError} When the underlying parse throws a {@link MultipartError}
+* (limit breach → 413, malformed structure → 400, rejected file type → 415)
+*
+* @example
+* ```ts
+* import { createMultipart } from '@orkestrel/middleware/server'
+*
+* const uploads = createMultipart({ allowed: ['image/png', 'image/jpeg'] })
+* ```
+*/
+function createMultipart(options = {}) {
+	return async (request, context, next) => {
+		let body;
+		try {
+			body = await parseMultipartRequest(request, options);
+		} catch (error) {
+			if (isMultipartError(error)) throw new HTTPError(error.status, error.message, error.context);
+			throw error;
+		}
+		if (body === void 0) return next();
+		context.state.multipart = body;
+		try {
+			return await next();
+		} catch (error) {
+			await unlinkStagedFiles(body);
+			throw error;
+		}
+	};
+}
+/**
+* Compress response bodies via `node:zlib` — the node-bound sibling of the
+* core face's `CompressionStream`-feature-detected `createCompression`,
+* guaranteed available on any Node runtime rather than dependent on the
+* WHATWG `CompressionStream` global (PROPOSAL §4.3, ruling J). Ships as a
+* SEPARATE package entry point (`@orkestrel/middleware/server`) from the core
+* face's `createCompression`, so the shared name is unambiguous per
+* consumer import path (ruling H).
+*
+* @remarks
+* Peer-type limitation (same one U1 recorded on the core face): the shipped
+* `@orkestrel/server` `Encoding` union is `'gzip' | 'deflate' | 'identity'`
+* — it does not include `'br'`, so this battery cannot honestly type or
+* negotiate a guaranteed brotli coding despite `node:zlib` shipping
+* `brotliCompress`. It guarantees `gzip`/`deflate` via `node:zlib` (never
+* feature-detected — always available) and negotiates only those.
+*
+* @typeParam TState - The consumer's opaque per-request state type
+* @param options - See {@link NodeCompressionOptions}
+* @returns A `MiddlewareHandler<TState>`
+* @throws {TypeError} When `options.threshold` is provided and is not a
+* finite number, or `options.filter` is provided and is not a function
+*
+* @example
+* ```ts
+* import { createCompression } from '@orkestrel/middleware/server'
+*
+* const compress = createCompression({ threshold: 512 })
+* ```
+*/
+function createCompression(options) {
+	if (options?.threshold !== void 0 && !isFiniteNumber(options.threshold)) throw new TypeError("NodeCompressionOptions.threshold must be a finite number when provided");
+	if (options?.filter !== void 0 && !isFunction(options.filter)) throw new TypeError("NodeCompressionOptions.filter must be a function when provided");
+	const threshold = options?.threshold ?? DEFAULT_COMPRESSION_THRESHOLD;
+	const filter = options?.filter;
+	const encodings = ["gzip", "deflate"];
+	const gzipAsync = promisify(gzip);
+	const deflateAsync = promisify(deflate);
+	return async (request, context, next) => {
+		return compressResponse(request, context, await next(), {
+			threshold,
+			filter,
+			encodings,
+			compress: async (bytes, encoding) => encoding === "gzip" ? gzipAsync(bytes) : deflateAsync(bytes)
+		});
+	};
+}
+//#endregion
+export { DEFAULT_CONTENT_TYPE, DEFAULT_MULTIPART_FIELD, DEFAULT_MULTIPART_FIELDS, DEFAULT_MULTIPART_FILE, DEFAULT_MULTIPART_FILES, DEFAULT_MULTIPART_TOTAL, DEFAULT_STATIC_FALLBACK_EXCLUDE, DEFAULT_STATIC_INDEX, EXTENSION_TYPES, MULTIPART_MAX_HEADER_BLOCK, MULTIPART_MAX_PREAMBLE, MULTIPART_REASON_STATUS, MultipartError, RESERVED_DEVICE_NAMES, computeFileETag, createCompression, createMultipart, createStatic, createUploadedFile, detectMIME, isContainedPath, isDotfilePath, isMultipartError, isReservedDeviceName, isUnderPath, lookupContentType, moveUploadedFile, multipartBoundary, parseMultipartRequest, parsePartHeaders, readUploadedFile, resolveDefaultDirectory, resolveMultipartLimits, resolveStaticPath, streamFile, streamUploadedFile, unlinkStagedFiles };
+
+//# sourceMappingURL=index.js.map