@orkestrel/middleware 0.0.18 → 0.0.19

package/dist/src/server/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_server = require("@orkestrel/server");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
@@ -7,37 +8,51 @@ let node_zlib = require("node:zlib");
 let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
 let node_os = require("node:os");
-let _orkestrel_server = require("@orkestrel/server");
 let _src_core = require("../core/index.cjs");
 //#region src/server/constants.ts
-/** The HTTP status `createMultipart` renders for each {@link MultipartReason}. */
-var MULTIPART_REASON_STATUS = Object.freeze({
+/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+var MULTIPART_STATUS = Object.freeze({
 	limit: 413,
 	malformed: 400,
 	rejected: 415
 });
-/** `createStatic`'s default directory-index filename. */
+/**
+* Holds the `Symbol.for` brand {@link MultipartError} carries so
+* {@link isMultipartError} recognizes an instance across duplicate copies of
+* this package — a registry symbol rather than a module-local `Symbol()`,
+* which would mint an unequal symbol per copy.
+*/
+var MULTIPART_ERROR_BRAND = Symbol.for("@orkestrel/middleware.MultipartError");
+/** Names `createStatic`'s default directory-index filename. */
 var DEFAULT_STATIC_INDEX = "index.html";
-/** `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `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. */
+/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+var DEFAULT_STATIC_DOTFILES = "ignore";
+/**
+* Lists the content-codings the node face's `createCompression` offers — the two
+* `node:zlib` guarantees on every Node runtime, so this face never
+* feature-detects.
+*/
+var NODE_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
+/** Names 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. */
+/** Holds `createMultipart`'s default per-file byte-size cap. */
+var DEFAULT_MULTIPART_FILE_SIZE = 10485760;
+/** Holds `createMultipart`'s default maximum file-part count. */
+var DEFAULT_MULTIPART_FILE_COUNT = 10;
+/** Holds `createMultipart`'s default per-field byte-size cap. */
+var DEFAULT_MULTIPART_FIELD_SIZE = 65536;
+/** Holds `createMultipart`'s default maximum field-part count. */
+var DEFAULT_MULTIPART_FIELD_COUNT = 100;
+/** Holds `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. */
+/** Holds 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. */
+/** Holds 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
+* Lists the 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([
@@ -64,7 +79,7 @@ var RESERVED_DEVICE_NAMES = Object.freeze(/* @__PURE__ */ new Set([
 	"LPT8",
 	"LPT9"
 ]));
-/** File-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. */
+/** Holds the 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",
@@ -90,15 +105,18 @@ var EXTENSION_TYPES = Object.freeze({
 //#endregion
 //#region src/server/errors.ts
 /**
-* An error `createMultipart` throws when a streamed multipart request fails
+* Represents 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}.
+* Extends the peer `HTTPError`, which already publishes the `status`,
+* `context`, and brand members every fleet error of this shape carries, and
+* adds the machine-readable `code` axis a caller narrows on. `status` is
+* derived from `code` through {@link MULTIPART_STATUS} (limit → 413, malformed →
+* 400, rejected → 415), so `createBoundary` — or any other `isHTTPError`-aware
+* renderer — maps it without knowing this face's error type. Narrow a caught
+* value to the richer type with {@link isMultipartError}.
 *
 * @example
 * ```ts
@@ -107,29 +125,26 @@ var EXTENSION_TYPES = Object.freeze({
 * 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;
-		if (context !== void 0) this.context = context;
-		Object.defineProperty(this, Symbol.for("@orkestrel/middleware.MultipartError"), { value: true });
+var MultipartError = class extends _orkestrel_server.HTTPError {
+	code;
+	[MULTIPART_ERROR_BRAND] = true;
+	constructor(code, message, context) {
+		super(MULTIPART_STATUS[code], message, context);
+		this.name = "MultipartError";
+		this.code = code;
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link MultipartError}.
+* Narrows 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'`).
+* carrying {@link MULTIPART_ERROR_BRAND}, a numeric `status`, and a `code`
+* in the parser's {@link MultipartErrorCode} set (`'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}
+* @returns True if `value` is a {@link MultipartError}; false otherwise
 *
 * @example
 * ```ts
@@ -138,233 +153,29 @@ var MultipartError = class extends Error {
 * try {
 * 	await parse(request)
 * } catch (error) {
-* 	if (isMultipartError(error)) console.log(error.status, error.reason)
+* 	if (isMultipartError(error)) console.log(error.status, error.code)
 * }
 * ```
 */
 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 (!(MULTIPART_ERROR_BRAND in value)) return false;
+	if (!("status" in value) || !("code" in value)) return false;
 	if (typeof value.status !== "number") return false;
-	if (value.reason !== "limit" && value.reason !== "malformed" && value.reason !== "rejected") return false;
+	if (value.code !== "limit" && value.code !== "malformed" && value.code !== "rejected") return false;
 	return true;
 }
 //#endregion
-//#region src/server/MultipartParser.ts
-var MultipartParser = class MultipartParser {
-	static #defaultDirectory;
-	#reader;
-	#signal;
-	#abort;
-	#boundary;
-	#limits;
-	#allowed;
-	#directory;
-	#staged = [];
-	#files = Object.create(null);
-	#fields = Object.create(null);
-	#buffer = Buffer.alloc(0);
-	#ended = false;
-	#fileCount = 0;
-	#fieldCount = 0;
-	#totalBytes = 0;
-	constructor(stream, signal, boundary, limits, allowed, directory) {
-		this.#reader = stream.getReader();
-		this.#signal = signal;
-		this.#abort = this.#wakeReader.bind(this);
-		this.#boundary = boundary;
-		this.#limits = limits;
-		this.#allowed = allowed;
-		this.#directory = directory;
-	}
-	static directory() {
-		if (MultipartParser.#defaultDirectory === void 0) MultipartParser.#defaultDirectory = MultipartParser.#createDirectory();
-		return MultipartParser.#defaultDirectory;
-	}
-	async parse() {
-		this.#signal.addEventListener("abort", this.#abort, { once: true });
-		try {
-			const openMarker = Buffer.from(`--${this.#boundary}`);
-			let preambleScanned = 0;
-			let index = this.#buffer.indexOf(openMarker);
-			while (index === -1) {
-				const carry = openMarker.length - 1;
-				if (this.#buffer.length > carry) {
-					const drop = this.#buffer.length - carry;
-					preambleScanned += drop;
-					if (preambleScanned > 65536) throw new MultipartError("malformed", "multipart preamble too large");
-					this.#buffer = this.#buffer.subarray(drop);
-				}
-				if (!await this.#pull()) throw new MultipartError("malformed", "missing multipart boundary");
-				index = this.#buffer.indexOf(openMarker);
-			}
-			if (preambleScanned + index > 65536) throw new MultipartError("malformed", "multipart preamble too large");
-			this.#buffer = this.#buffer.subarray(index + openMarker.length);
-			for (;;) {
-				while (this.#buffer.length < 2) if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
-				if (this.#buffer[0] === 45 && this.#buffer[1] === 45) break;
-				if (this.#buffer[0] !== 13 || this.#buffer[1] !== 10) throw new MultipartError("malformed", "malformed multipart boundary");
-				this.#buffer = this.#buffer.subarray(2);
-				let headerEnd = this.#buffer.indexOf("\r\n\r\n");
-				while (headerEnd === -1) {
-					if (this.#buffer.length > 16384) throw new MultipartError("malformed", "multipart header block too large");
-					if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart part headers");
-					headerEnd = this.#buffer.indexOf("\r\n\r\n");
-				}
-				if (headerEnd > 16384) throw new MultipartError("malformed", "multipart header block too large");
-				const headerBlock = this.#buffer.subarray(0, headerEnd).toString("utf8");
-				this.#buffer = this.#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--${this.#boundary}`);
-				if (filename !== void 0) {
-					if (filename !== "") {
-						this.#fileCount += 1;
-						if (this.#fileCount > this.#limits.files) throw new MultipartError("limit", "too many multipart files");
-					}
-					const path = (0, node_path.join)(this.#directory, (0, node_crypto.randomUUID)());
-					this.#staged.push(path);
-					const handle = await (0, node_fs_promises.open)(path, "w", 384);
-					let size = 0;
-					let head = Buffer.alloc(0);
-					try {
-						for (;;) {
-							const boundaryIndex = this.#buffer.indexOf(partDelimiter);
-							if (boundaryIndex === -1) {
-								const safeLength = Math.max(0, this.#buffer.length - (partDelimiter.length - 1));
-								if (safeLength > 0) {
-									const chunk = this.#buffer.subarray(0, safeLength);
-									size += chunk.length;
-									if (size > this.#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);
-									this.#buffer = this.#buffer.subarray(safeLength);
-								}
-								if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart file part");
-								continue;
-							}
-							const chunk = this.#buffer.subarray(0, boundaryIndex);
-							size += chunk.length;
-							if (size > this.#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);
-							this.#buffer = this.#buffer.subarray(boundaryIndex + 2);
-							break;
-						}
-					} finally {
-						await handle.close();
-					}
-					if (filename === "" && size === 0) {
-						await (0, node_fs_promises.unlink)(path);
-						this.#staged.splice(this.#staged.indexOf(path), 1);
-					} else {
-						if (filename === "") {
-							this.#fileCount += 1;
-							if (this.#fileCount > this.#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 (this.#allowed !== void 0) {
-							if (!(detected !== void 0 && this.#allowed.includes(detected))) throw new MultipartError("rejected", "multipart file failed type validation");
-						}
-						if ((0, _orkestrel_server.isDangerousKey)(name)) {
-							await (0, node_fs_promises.unlink)(path);
-							this.#staged.splice(this.#staged.indexOf(path), 1);
-						} else {
-							const record = createUploadedFile({
-								field: name,
-								name: filename,
-								size,
-								mime: detected ?? declared,
-								validated,
-								status: "staged",
-								path
-							});
-							const existing = this.#files[name];
-							if (existing === void 0) this.#files[name] = [record];
-							else existing.push(record);
-						}
-					}
-				} else {
-					this.#fieldCount += 1;
-					if (this.#fieldCount > this.#limits.fields) throw new MultipartError("limit", "too many multipart fields");
-					let value = Buffer.alloc(0);
-					for (;;) {
-						const boundaryIndex = this.#buffer.indexOf(partDelimiter);
-						if (boundaryIndex === -1) {
-							const safeLength = Math.max(0, this.#buffer.length - (partDelimiter.length - 1));
-							if (safeLength > 0) {
-								value = Buffer.concat([value, this.#buffer.subarray(0, safeLength)]);
-								if (value.length > this.#limits.field) throw new MultipartError("limit", "multipart field exceeds size limit");
-								this.#buffer = this.#buffer.subarray(safeLength);
-							}
-							if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart field part");
-							continue;
-						}
-						value = Buffer.concat([value, this.#buffer.subarray(0, boundaryIndex)]);
-						if (value.length > this.#limits.field) throw new MultipartError("limit", "multipart field exceeds size limit");
-						this.#buffer = this.#buffer.subarray(boundaryIndex + 2);
-						break;
-					}
-					if (!(0, _orkestrel_server.isDangerousKey)(name)) this.#fields[name] = value.toString("utf8");
-				}
-				while (this.#buffer.length < openMarker.length) if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
-				this.#buffer = this.#buffer.subarray(openMarker.length);
-			}
-		} catch (error) {
-			await this.#cleanup();
-			await this.#reader.cancel().catch(() => {});
-			throw error;
-		} finally {
-			this.#signal.removeEventListener("abort", this.#abort);
-			if (!this.#ended) await this.#reader.cancel().catch(() => {});
-		}
-		return {
-			files: Object.freeze(this.#files),
-			fields: Object.freeze(this.#fields)
-		};
-	}
-	static async #createDirectory() {
-		const path = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-multipart-"));
-		await (0, node_fs_promises.chmod)(path, 448);
-		return path;
-	}
-	async #cleanup() {
-		for (const path of this.#staged) try {
-			await (0, node_fs_promises.unlink)(path);
-		} catch {}
-	}
-	async #pull() {
-		if (this.#signal.aborted) throw new MultipartError("malformed", "request aborted mid-upload");
-		if (this.#ended) return false;
-		const { done, value } = await this.#reader.read();
-		if (this.#signal.aborted) throw new MultipartError("malformed", "request aborted mid-upload");
-		if (done) {
-			this.#ended = true;
-			return false;
-		}
-		this.#totalBytes += value.byteLength;
-		if (this.#totalBytes > this.#limits.total) throw new MultipartError("limit", "multipart body exceeds total limit");
-		this.#buffer = Buffer.concat([this.#buffer, Buffer.from(value.buffer, value.byteOffset, value.byteLength)]);
-		return true;
-	}
-	#wakeReader() {
-		this.#reader.cancel().catch(() => {});
-	}
-};
-//#endregion
 //#region src/server/helpers.ts
 /**
-* Whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+* Checks 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` + `/`
+* @returns True if `pathname` equals `prefix` or starts with `prefix` + `/`; false otherwise
 *
 * @example
 * ```ts
@@ -378,13 +189,19 @@ function isUnderPath(pathname, prefix) {
 	return pathname.startsWith(boundary);
 }
 /**
-* Resolve the fixed SPA shell path when a static-file miss is eligible for
+* Resolves the fixed SPA shell path when a static-file miss is eligible for
 * fallback.
 *
+* @remarks
+* `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+* defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
+* that answered `404` while its `GET` answered `200` would report a resource
+* the very next request serves.
+*
 * @param root - The configured static root
 * @param index - The configured shell filename
 * @param exclude - The URL prefix excluded from fallback
-* @param method - The request method
+* @param method - The request method; only `GET` and `HEAD` are eligible
 * @param pathname - The request pathname
 * @param accept - The request's `Accept` header value
 * @returns The fixed shell path, or `undefined` when fallback is ineligible
@@ -396,14 +213,14 @@ function isUnderPath(pathname, prefix) {
 * ```
 */
 function resolveStaticFallbackPath(root, index, exclude, method, pathname, accept) {
-	if (method !== "GET") return void 0;
+	if (method !== "GET" && method !== "HEAD") return void 0;
 	if ((0, node_path.extname)(pathname) !== "") return void 0;
 	if (!accept.includes("text/html") && !accept.includes("*/*")) return void 0;
 	if (isUnderPath(pathname, exclude)) return void 0;
 	return (0, node_path.join)(root, index);
 }
 /**
-* Whether `child` is `parent` itself or lies inside it on-disk — the
+* Checks 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).
 *
@@ -417,7 +234,7 @@ function resolveStaticFallbackPath(root, index, exclude, method, pathname, accep
 *
 * @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
+* @returns True if `child` equals `parent` or resolves inside it; false otherwise
 *
 * @example
 * ```ts
@@ -431,9 +248,9 @@ function isContainedPath(child, parent) {
 	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${node_path.sep}`) && !(0, node_path.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
+* Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+* when it cannot — the traversal guard, whose algorithm and order are exact:
+* 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-
@@ -470,10 +287,40 @@ function resolveStaticPath(root, prefix, pathname) {
 	const segments = normalized.split(/[/\\]+/).filter((segment) => segment.length > 0);
 	for (const segment of segments) if (isReservedDeviceName(segment)) return void 0;
 	const resolved = (0, node_path.resolve)(root, normalized);
-	if (resolved === root || resolved.startsWith(`${root}${node_path.sep}`)) return resolved;
+	return isContainedPath(resolved, root) ? resolved : void 0;
 }
 /**
-* Whether a path segment is a Windows reserved device name (CVE-2025-27210).
+* Canonicalizes `candidate` and returns it only when it lies inside `rootReal`
+* — the shared realpath-then-contain step `createStatic` applies to a
+* directory index and to its SPA shell.
+*
+* @remarks
+* Total: a `realpath` failure (a dangling symlink, a missing file, a
+* permission refusal) and an escape from `rootReal` both resolve `undefined`,
+* so a caller that treats those two outcomes identically needs no `try`. A
+* caller that must tell them apart keeps its own explicit branch instead.
+*
+* @param candidate - The on-disk path to canonicalize
+* @param rootReal - The already-canonical root the result must lie under
+* @returns The canonical path inside `rootReal`, or `undefined`
+*
+* @example
+* ```ts
+* await resolveContainedRealPath('/srv/public/index.html', '/srv/public')
+* // '/srv/public/index.html'
+* ```
+*/
+async function resolveContainedRealPath(candidate, rootReal) {
+	let real;
+	try {
+		real = await (0, node_fs_promises.realpath)(candidate);
+	} catch {
+		return;
+	}
+	return isContainedPath(real, rootReal) ? real : void 0;
+}
+/**
+* Checks whether a path segment is a Windows reserved device name (CVE-2025-27210).
 *
 * @remarks
 * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
@@ -483,7 +330,7 @@ function resolveStaticPath(root, prefix, pathname) {
 * `console.js` and `nullable.css` are never flagged.
 *
 * @param segment - One path segment (no separators)
-* @returns `true` when `segment` names a reserved device
+* @returns True if `segment` names a reserved device; false otherwise
 *
 * @example
 * ```ts
@@ -498,11 +345,11 @@ function isReservedDeviceName(segment) {
 	return RESERVED_DEVICE_NAMES.has(stem.toUpperCase());
 }
 /**
-* Whether a relative path (already resolved under a static root) has any
+* Checks 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 `.`
+* @returns True if any segment starts with `.`; false otherwise
 *
 * @example
 * ```ts
@@ -514,7 +361,7 @@ function isDotfilePath(relativePath) {
 	return relativePath.split(/[/\\]+/).some((segment) => segment.startsWith("."));
 }
 /**
-* Look up the MIME type for a static file path by its extension.
+* Looks 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
@@ -528,7 +375,7 @@ function lookupContentType(pathname) {
 	return EXTENSION_TYPES[(0, node_path.extname)(pathname).toLowerCase()] ?? "application/octet-stream";
 }
 /**
-* Compute a static file's weak ETag from its size and modification time.
+* Computes 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
@@ -543,7 +390,7 @@ function computeFileETag(size, mtimeMs) {
 	return `W/"${size}-${Math.floor(mtimeMs)}"`;
 }
 /**
-* Compress response bytes with Node's guaranteed zlib gzip/deflate codecs.
+* Compresses response bytes with Node's guaranteed zlib gzip/deflate codecs.
 *
 * @param bytes - The uncompressed response bytes
 * @param encoding - The negotiated actionable coding
@@ -560,10 +407,16 @@ async function compressNodeBytes(bytes, encoding) {
 	return Uint8Array.from(compressed);
 }
 /**
-* 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`.
+* Sniffs a MIME type from a file's leading bytes against a small magic-byte
+* table (jpeg, png, gif87a/89a, webp, pdf, zip).
+*
+* @remarks
+* `createMultipart`'s `allowed` check reads this signal alone and never the
+* declared `Content-Type`, so a file whose bytes match no signature can never
+* be placed on an `allowed` list. The record's `mime` field is a different
+* question: it falls back to the declared `Content-Type` (then to
+* {@link DEFAULT_CONTENT_TYPE}) when nothing sniffs, and its `validated` flag
+* reports whether the sniffed and declared types agreed.
 *
 * @param head - The file's first bytes (16 is sufficient for every signature)
 * @returns The detected MIME type, or `undefined` when no signature matches
@@ -641,12 +494,12 @@ function detectMIME(head) {
 	])) return "application/zip";
 }
 /**
-* Whether `bytes` contains `signature` at the requested offset.
+* Checks whether `bytes` contains `signature` at the requested offset.
 *
 * @param bytes - The bytes to inspect
 * @param signature - The exact byte sequence to match
 * @param offset - The starting byte offset, defaulting to zero
-* @returns `true` when the complete signature matches
+* @returns True if the complete signature matches; false otherwise
 *
 * @example
 * ```ts
@@ -659,7 +512,7 @@ function matchesBytes(bytes, signature, offset = 0) {
 	return true;
 }
 /**
-* Extract the `boundary` parameter from a `Content-Type` header, or
+* Extracts 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
@@ -668,11 +521,11 @@ function matchesBytes(bytes, signature, offset = 0) {
 *
 * @example
 * ```ts
-* multipartBoundary('multipart/form-data; boundary=abc123') // 'abc123'
-* multipartBoundary('application/json') // undefined
+* extractMultipartBoundary('multipart/form-data; boundary=abc123') // 'abc123'
+* extractMultipartBoundary('application/json') // undefined
 * ```
 */
-function multipartBoundary(contentType) {
+function extractMultipartBoundary(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;
@@ -686,56 +539,49 @@ function multipartBoundary(contentType) {
 	}
 }
 /**
-* Resolve `createMultipart`'s effective {@link MultipartLimits}, applying
-* every documented default.
+* Resolves `createMultipart`'s effective {@link MultipartLimits}, applying
+* every documented default to an omitted leaf.
 *
 * @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
-	};
-}
-/**
-* 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()
+* resolveMultipartLimits({ file: { size: 1_048_576 } })
 * ```
 */
-function resolveDefaultDirectory() {
-	return MultipartParser.directory();
+function resolveMultipartLimits(limits) {
+	return {
+		file: {
+			size: limits?.file?.size ?? 10485760,
+			count: limits?.file?.count ?? 10
+		},
+		field: {
+			size: limits?.field?.size ?? 65536,
+			count: limits?.field?.count ?? 100
+		},
+		total: limits?.total ?? 52428800
+	};
 }
 /**
-* Parse one multipart part's raw header block into its `name` (from
+* Parses 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)
+* @returns The parsed `name`, `filename`, and `mime` (each `undefined` when
+* absent)
 *
 * @example
 * ```ts
 * parsePartHeaders('Content-Disposition: form-data; name="title"')
-* // { name: 'title', filename: undefined, contentType: undefined }
+* // { name: 'title', filename: undefined, mime: undefined }
 * ```
 */
 function parsePartHeaders(block) {
 	let name;
 	let filename;
-	let contentType;
+	let mime;
 	for (const line of block.split("\r\n")) {
 		const colon = line.indexOf(":");
 		if (colon === -1) continue;
@@ -746,69 +592,19 @@ function parsePartHeaders(block) {
 			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;
+		} else if (key === "content-type") mime = value;
 	}
 	return {
 		name,
 		filename,
-		contentType
+		mime
 	};
 }
 /**
-* 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();
-	return new MultipartParser(request.body, request.signal, boundary, limits, allowed, directory).parse();
-}
-/**
-* Build a frozen {@link UploadedFileInterface} record.
+* Builds a frozen {@link UploadedFile} record.
 *
 * @param input - Every field of the record
-* @returns A frozen {@link UploadedFileInterface}
+* @returns A frozen {@link UploadedFile}
 *
 * @example
 * ```ts
@@ -819,7 +615,7 @@ function createUploadedFile(input) {
 	return Object.freeze({ ...input });
 }
 /**
-* Best-effort unlink every still-`'staged'` file in a parsed
+* Attempts to 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).
@@ -841,7 +637,7 @@ async function unlinkStagedFiles(body) {
 	}
 }
 /**
-* Adapt a `node:fs` read stream over `path` (or an already-open
+* Adapts a `node:fs` read stream over a file 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.
@@ -852,24 +648,23 @@ async function unlinkStagedFiles(body) {
 * 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;
+* 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
+* all, because `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
+* mid-stream read failure. Cancelling the returned `ReadableStream` (for
+* example 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
+* released. When `source` 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.
+* or `destroy()` through the iterator's `return()`) — the caller never needs a
+* separate `handle.close()` for a `FileHandle` passed as `source`.
 *
 * @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
+* `FileHandle` (for example 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)
+* @param range - An optional inclusive byte range; see {@link ByteRange}
 * @returns A `ReadableStream<Uint8Array>` valid as a fetch `BodyInit`
 *
 * @example
@@ -910,9 +705,9 @@ function streamFile(source, range) {
 	});
 }
 /**
-* Open a staged/moved uploaded file as a web `ReadableStream`.
+* Opens a staged/moved uploaded file as a web `ReadableStream`.
 *
-* @param file - The {@link UploadedFileInterface} record to stream
+* @param file - The {@link UploadedFile} record to stream
 * @returns A `ReadableStream<Uint8Array>` over the file's current on-disk path
 *
 * @example
@@ -924,9 +719,9 @@ function streamUploadedFile(file) {
 	return streamFile(file.path);
 }
 /**
-* Read a staged/moved uploaded file's full contents into memory.
+* Reads a staged/moved uploaded file's full contents into memory.
 *
-* @param file - The {@link UploadedFileInterface} record to read
+* @param file - The {@link UploadedFile} record to read
 * @returns The file's bytes
 *
 * @example
@@ -938,16 +733,18 @@ async function readUploadedFile(file) {
 	return (0, node_fs_promises.readFile)(file.path);
 }
 /**
-* Move a staged uploaded file to its final `destination`.
+* Moves 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.
+* and `path: destination` — the input record is never mutated. The suite
+* drives the `EXDEV` fallback only on a host whose device probe finds a
+* second filesystem, so a single-device host leaves that branch unproven.
 *
-* @param file - The {@link UploadedFileInterface} record to move
+* @param file - The {@link UploadedFile} record to move
 * @param destination - The final on-disk path
-* @returns A new {@link UploadedFileInterface} record reflecting the move
+* @returns A new {@link UploadedFile} record reflecting the move
 *
 * @example
 * ```ts
@@ -958,7 +755,7 @@ async function moveUploadedFile(file, destination) {
 	try {
 		await (0, node_fs_promises.rename)(file.path, destination);
 	} catch (error) {
-		if ((0, _orkestrel_contract.isRecord)(error) && error.code === "EXDEV") {
+		if ((0, _orkestrel_contract.isError)(error) && "code" in error && error.code === "EXDEV") {
 			await (0, node_fs_promises.copyFile)(file.path, destination);
 			await (0, node_fs_promises.unlink)(file.path);
 		} else throw error;
@@ -974,9 +771,267 @@ async function moveUploadedFile(file, destination) {
 	});
 }
 //#endregion
+//#region src/server/MultipartParser.ts
+var MultipartParser = class MultipartParser {
+	static #defaultDirectory;
+	#reader;
+	#signal;
+	#abort;
+	#boundary;
+	#limits;
+	#allowed;
+	#directory;
+	#staged = [];
+	#files = Object.create(null);
+	#fields = Object.create(null);
+	#buffer = Buffer.alloc(0);
+	#ended = false;
+	#fileCount = 0;
+	#fieldCount = 0;
+	#totalBytes = 0;
+	constructor(stream, signal, boundary, limits, allowed, directory) {
+		this.#reader = stream.getReader();
+		this.#signal = signal;
+		this.#abort = this.#wakeReader.bind(this);
+		this.#boundary = boundary;
+		this.#limits = limits;
+		this.#allowed = allowed;
+		this.#directory = directory;
+	}
+	static directory() {
+		if (MultipartParser.#defaultDirectory === void 0) MultipartParser.#defaultDirectory = MultipartParser.#createDirectory();
+		return MultipartParser.#defaultDirectory;
+	}
+	async parse() {
+		this.#signal.addEventListener("abort", this.#abort, { once: true });
+		try {
+			const openMarker = Buffer.from(`--${this.#boundary}`);
+			let preambleScanned = 0;
+			let index = this.#buffer.indexOf(openMarker);
+			while (index === -1) {
+				const carry = openMarker.length - 1;
+				if (this.#buffer.length > carry) {
+					const drop = this.#buffer.length - carry;
+					preambleScanned += drop;
+					if (preambleScanned > 65536) throw new MultipartError("malformed", "multipart preamble too large");
+					this.#buffer = this.#buffer.subarray(drop);
+				}
+				if (!await this.#pull()) throw new MultipartError("malformed", "missing multipart boundary");
+				index = this.#buffer.indexOf(openMarker);
+			}
+			if (preambleScanned + index > 65536) throw new MultipartError("malformed", "multipart preamble too large");
+			this.#buffer = this.#buffer.subarray(index + openMarker.length);
+			for (;;) {
+				while (this.#buffer.length < 2) if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
+				if (this.#buffer[0] === 45 && this.#buffer[1] === 45) break;
+				if (this.#buffer[0] !== 13 || this.#buffer[1] !== 10) throw new MultipartError("malformed", "malformed multipart boundary");
+				this.#buffer = this.#buffer.subarray(2);
+				let headerEnd = this.#buffer.indexOf("\r\n\r\n");
+				while (headerEnd === -1) {
+					if (this.#buffer.length > 16384) throw new MultipartError("malformed", "multipart header block too large");
+					if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart part headers");
+					headerEnd = this.#buffer.indexOf("\r\n\r\n");
+				}
+				if (headerEnd > 16384) throw new MultipartError("malformed", "multipart header block too large");
+				const headerBlock = this.#buffer.subarray(0, headerEnd).toString("utf8");
+				this.#buffer = this.#buffer.subarray(headerEnd + 4);
+				const { name, filename, mime } = parsePartHeaders(headerBlock);
+				if (name === void 0) throw new MultipartError("malformed", "multipart part missing name");
+				const partDelimiter = Buffer.from(`\r\n--${this.#boundary}`);
+				if (filename !== void 0) await this.#consumeFile(name, filename, mime, partDelimiter);
+				else await this.#consumeField(name, partDelimiter);
+				while (this.#buffer.length < openMarker.length) if (!await this.#pull()) throw new MultipartError("malformed", "unterminated multipart boundary");
+				this.#buffer = this.#buffer.subarray(openMarker.length);
+			}
+		} catch (error) {
+			await this.#cleanup();
+			await this.#reader.cancel().catch(() => {});
+			throw error;
+		} finally {
+			this.#signal.removeEventListener("abort", this.#abort);
+			if (!this.#ended) await this.#reader.cancel().catch(() => {});
+		}
+		const files = Object.create(null);
+		for (const [field, records] of Object.entries(this.#files)) files[field] = Object.freeze([...records]);
+		const fields = Object.assign(Object.create(null), this.#fields);
+		return {
+			files: Object.freeze(files),
+			fields: Object.freeze(fields)
+		};
+	}
+	async #consumeFile(name, filename, mime, delimiter) {
+		if (filename !== "") {
+			this.#fileCount += 1;
+			if (this.#fileCount > this.#limits.file.count) throw new MultipartError("limit", "too many multipart files");
+		}
+		const path = (0, node_path.join)(this.#directory, (0, node_crypto.randomUUID)());
+		this.#staged.push(path);
+		const handle = await (0, node_fs_promises.open)(path, "w", 384);
+		let size = 0;
+		let head = Buffer.alloc(0);
+		try {
+			await this.#scan(delimiter, "unterminated multipart file part", async (chunk) => {
+				size += chunk.length;
+				if (size > this.#limits.file.size) 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);
+			});
+		} finally {
+			await handle.close();
+		}
+		if (filename === "" && size === 0) {
+			await this.#discard(path);
+			return;
+		}
+		if (filename === "") {
+			this.#fileCount += 1;
+			if (this.#fileCount > this.#limits.file.count) throw new MultipartError("limit", "too many multipart files");
+		}
+		const detected = detectMIME(head);
+		const declared = mime ?? "application/octet-stream";
+		const validated = detected !== void 0 && detected === declared;
+		if (this.#allowed !== void 0) {
+			if (!(detected !== void 0 && this.#allowed.includes(detected))) throw new MultipartError("rejected", "multipart file failed type validation");
+		}
+		if ((0, _orkestrel_server.isDangerousKey)(name)) {
+			await this.#discard(path);
+			return;
+		}
+		const record = createUploadedFile({
+			field: name,
+			name: filename,
+			size,
+			mime: detected ?? declared,
+			validated,
+			status: "staged",
+			path
+		});
+		const existing = this.#files[name];
+		if (existing === void 0) this.#files[name] = [record];
+		else existing.push(record);
+	}
+	async #consumeField(name, delimiter) {
+		this.#fieldCount += 1;
+		if (this.#fieldCount > this.#limits.field.count) throw new MultipartError("limit", "too many multipart fields");
+		let value = Buffer.alloc(0);
+		await this.#scan(delimiter, "unterminated multipart field part", (chunk) => {
+			value = Buffer.concat([value, chunk]);
+			if (value.length > this.#limits.field.size) throw new MultipartError("limit", "multipart field exceeds size limit");
+		});
+		if (!(0, _orkestrel_server.isDangerousKey)(name)) this.#fields[name] = value.toString("utf8");
+	}
+	async #scan(delimiter, unterminated, sink) {
+		for (;;) {
+			const boundaryIndex = this.#buffer.indexOf(delimiter);
+			if (boundaryIndex === -1) {
+				const safeLength = Math.max(0, this.#buffer.length - (delimiter.length - 1));
+				if (safeLength > 0) {
+					await sink(this.#buffer.subarray(0, safeLength));
+					this.#buffer = this.#buffer.subarray(safeLength);
+				}
+				if (!await this.#pull()) throw new MultipartError("malformed", unterminated);
+				continue;
+			}
+			await sink(this.#buffer.subarray(0, boundaryIndex));
+			this.#buffer = this.#buffer.subarray(boundaryIndex + 2);
+			return;
+		}
+	}
+	async #discard(path) {
+		try {
+			await (0, node_fs_promises.unlink)(path);
+		} catch {}
+		const index = this.#staged.indexOf(path);
+		if (index !== -1) this.#staged.splice(index, 1);
+	}
+	static async #createDirectory() {
+		const path = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "orkestrel-multipart-"));
+		await (0, node_fs_promises.chmod)(path, 448);
+		return path;
+	}
+	async #cleanup() {
+		for (const path of this.#staged) try {
+			await (0, node_fs_promises.unlink)(path);
+		} catch {}
+	}
+	async #pull() {
+		if (this.#signal.aborted) throw new MultipartError("malformed", "request aborted mid-upload");
+		if (this.#ended) return false;
+		const { done, value } = await this.#reader.read();
+		if (this.#signal.aborted) throw new MultipartError("malformed", "request aborted mid-upload");
+		if (done) {
+			this.#ended = true;
+			return false;
+		}
+		this.#totalBytes += value.byteLength;
+		if (this.#totalBytes > this.#limits.total) throw new MultipartError("limit", "multipart body exceeds total limit");
+		this.#buffer = Buffer.concat([this.#buffer, Buffer.from(value.buffer, value.byteOffset, value.byteLength)]);
+		return true;
+	}
+	#wakeReader() {
+		this.#reader.cancel().catch(() => {});
+	}
+};
+//#endregion
+//#region src/server/parsers.ts
+/**
+* Stream-parses a `multipart/form-data` request into its files and fields —
+* the mid-stream state machine `createMultipart` drives.
+*
+* @remarks
+* Reads `request.body` chunk by chunk through 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 code `'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 `file.count` 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 code `'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 code `'rejected'`. A
+* request abort mid-upload triggers the same fail-closed cleanup as a limit
+* breach. Returns `undefined` for a non-multipart request (untouched).
+*
+* Staging defaults to a process-owned directory created ONCE (lazily,
+* memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
+* mode `0o700`; `options.directory` overrides it.
+*
+* @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 = extractMultipartBoundary(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 MultipartParser.directory();
+	return new MultipartParser(request.body, request.signal, boundary, limits, allowed, directory).parse();
+}
+//#endregion
 //#region src/server/middlewares.ts
 /**
-* Serve validated in-memory assets with identity/Brotli negotiation.
+* Serves validated in-memory assets with identity/Brotli negotiation.
 *
 * @remarks
 * Only `GET` and `HEAD` are served. `/` resolves to `index.html`. Every other
@@ -1069,8 +1124,8 @@ function createAssets(options) {
 	};
 }
 /**
-* Serve static files from `options.root` over `node:fs` — the node-bound
-* static-file battery (PROPOSAL §4.14).
+* Serves static files from `options.root` over `node:fs` — the node-bound
+* static-file battery.
 *
 * @remarks
 * Containment is enforced on CANONICAL paths, not merely the lexically
@@ -1085,7 +1140,7 @@ function createAssets(options) {
 * 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)
+* response, but a caller that holds an unread `Response` (for example in a test)
 * must cancel its body to release the handle promptly.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -1137,9 +1192,10 @@ function createStatic(options) {
 			resolvedPath = (0, node_path.join)(resolvedPath, index);
 			try {
 				if (canonicalRootPromise === void 0) canonicalRootPromise = (0, node_fs_promises.realpath)(root);
-				const [rootReal, indexReal] = await Promise.all([canonicalRootPromise, (0, node_fs_promises.realpath)(resolvedPath)]);
-				if (isContainedPath(indexReal, rootReal)) resolvedPath = indexReal;
-				else fallbackNeeded = true;
+				const rootReal = await canonicalRootPromise;
+				const indexReal = await resolveContainedRealPath(resolvedPath, rootReal);
+				if (indexReal === void 0) fallbackNeeded = true;
+				else resolvedPath = indexReal;
 			} catch {
 				fallbackNeeded = true;
 			}
@@ -1170,8 +1226,8 @@ function createStatic(options) {
 			let shellReal;
 			try {
 				if (canonicalRootPromise === void 0) canonicalRootPromise = (0, node_fs_promises.realpath)(root);
-				const [rootReal, candidate] = await Promise.all([canonicalRootPromise, (0, node_fs_promises.realpath)(shellPath)]);
-				if (!isContainedPath(candidate, rootReal)) return next();
+				const candidate = await resolveContainedRealPath(shellPath, await canonicalRootPromise);
+				if (candidate === void 0) return next();
 				shellReal = candidate;
 			} catch {
 				return next();
@@ -1182,16 +1238,20 @@ function createStatic(options) {
 			} catch {
 				return next();
 			}
+			let shellInfo;
 			try {
-				const body = streamFile(shellHandle);
-				return new Response(body, {
-					status: 200,
-					headers: new Headers({ "content-type": lookupContentType(shellReal) })
-				});
-			} catch (error) {
+				shellInfo = await shellHandle.stat();
+			} catch {
 				await shellHandle.close().catch(() => {});
-				throw error;
+				return next();
+			}
+			if (!shellInfo.isFile()) {
+				await shellHandle.close().catch(() => {});
+				return next();
 			}
+			resolvedPath = shellReal;
+			handle = shellHandle;
+			info = shellInfo;
 		}
 		if (handle === void 0 || info === void 0) return next();
 		let streaming = false;
@@ -1258,9 +1318,9 @@ function createStatic(options) {
 	};
 }
 /**
-* Parse a streamed `multipart/form-data` request body and stash its
+* Parses a streamed `multipart/form-data` request body and stashes its
 * {@link MultipartBody} on `context.state.multipart` — the node-bound
-* streaming multipart battery (PROPOSAL §4.15, ruling C).
+* streaming multipart battery.
 *
 * @remarks
 * A non-multipart request passes through untouched. Consumes `request.body`
@@ -1308,20 +1368,19 @@ function createMultipart(options = {}) {
 	};
 }
 /**
-* Compress response bodies via `node:zlib` — the node-bound sibling of the
-* core face's `CompressionStream`-feature-detected `createCompression`,
+* Compresses response bodies through `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).
+* WHATWG `CompressionStream` global. 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.
 *
 * @remarks
-* Peer-type limitation (same one U1 recorded on the core face): the shipped
+* Peer-type limitation, the same one the core face carries: 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
+* `brotliCompress`. It guarantees `gzip`/`deflate` through `node:zlib` (never
 * feature-detected — always available) and negotiates only those.
 *
 * @typeParam TState - The consumer's opaque per-request state type
@@ -1342,7 +1401,7 @@ function createCompression(options) {
 	if (options?.filter !== void 0 && !(0, _orkestrel_contract.isFunction)(options.filter)) throw new TypeError("NodeCompressionOptions.filter must be a function when provided");
 	const threshold = options?.threshold ?? _src_core.DEFAULT_COMPRESSION_THRESHOLD;
 	const filter = options?.filter;
-	const encodings = ["gzip", "deflate"];
+	const encodings = NODE_COMPRESSION_ENCODINGS;
 	return async (request, context, next) => {
 		const response = await next();
 		return (0, _src_core.compressResponse)(request, context, response, {
@@ -1355,18 +1414,21 @@ function createCompression(options) {
 }
 //#endregion
 exports.DEFAULT_CONTENT_TYPE = DEFAULT_CONTENT_TYPE;
-exports.DEFAULT_MULTIPART_FIELD = DEFAULT_MULTIPART_FIELD;
-exports.DEFAULT_MULTIPART_FIELDS = DEFAULT_MULTIPART_FIELDS;
-exports.DEFAULT_MULTIPART_FILE = DEFAULT_MULTIPART_FILE;
-exports.DEFAULT_MULTIPART_FILES = DEFAULT_MULTIPART_FILES;
+exports.DEFAULT_MULTIPART_FIELD_COUNT = DEFAULT_MULTIPART_FIELD_COUNT;
+exports.DEFAULT_MULTIPART_FIELD_SIZE = DEFAULT_MULTIPART_FIELD_SIZE;
+exports.DEFAULT_MULTIPART_FILE_COUNT = DEFAULT_MULTIPART_FILE_COUNT;
+exports.DEFAULT_MULTIPART_FILE_SIZE = DEFAULT_MULTIPART_FILE_SIZE;
 exports.DEFAULT_MULTIPART_TOTAL = DEFAULT_MULTIPART_TOTAL;
+exports.DEFAULT_STATIC_DOTFILES = DEFAULT_STATIC_DOTFILES;
 exports.DEFAULT_STATIC_FALLBACK_EXCLUDE = DEFAULT_STATIC_FALLBACK_EXCLUDE;
 exports.DEFAULT_STATIC_INDEX = DEFAULT_STATIC_INDEX;
 exports.EXTENSION_TYPES = EXTENSION_TYPES;
+exports.MULTIPART_ERROR_BRAND = MULTIPART_ERROR_BRAND;
 exports.MULTIPART_MAX_HEADER_BLOCK = MULTIPART_MAX_HEADER_BLOCK;
 exports.MULTIPART_MAX_PREAMBLE = MULTIPART_MAX_PREAMBLE;
-exports.MULTIPART_REASON_STATUS = MULTIPART_REASON_STATUS;
+exports.MULTIPART_STATUS = MULTIPART_STATUS;
 exports.MultipartError = MultipartError;
+exports.NODE_COMPRESSION_ENCODINGS = NODE_COMPRESSION_ENCODINGS;
 exports.RESERVED_DEVICE_NAMES = RESERVED_DEVICE_NAMES;
 exports.compressNodeBytes = compressNodeBytes;
 exports.computeFileETag = computeFileETag;
@@ -1376,6 +1438,7 @@ exports.createMultipart = createMultipart;
 exports.createStatic = createStatic;
 exports.createUploadedFile = createUploadedFile;
 exports.detectMIME = detectMIME;
+exports.extractMultipartBoundary = extractMultipartBoundary;
 exports.isContainedPath = isContainedPath;
 exports.isDotfilePath = isDotfilePath;
 exports.isMultipartError = isMultipartError;
@@ -1384,11 +1447,10 @@ exports.isUnderPath = isUnderPath;
 exports.lookupContentType = lookupContentType;
 exports.matchesBytes = matchesBytes;
 exports.moveUploadedFile = moveUploadedFile;
-exports.multipartBoundary = multipartBoundary;
 exports.parseMultipartRequest = parseMultipartRequest;
 exports.parsePartHeaders = parsePartHeaders;
 exports.readUploadedFile = readUploadedFile;
-exports.resolveDefaultDirectory = resolveDefaultDirectory;
+exports.resolveContainedRealPath = resolveContainedRealPath;
 exports.resolveMultipartLimits = resolveMultipartLimits;
 exports.resolveStaticFallbackPath = resolveStaticFallbackPath;
 exports.resolveStaticPath = resolveStaticPath;