@orkestrel/middleware 0.0.1

package/dist/src/server/index.d.cts

@@ -0,0 +1,729 @@
+import { FileHandle } from 'node:fs/promises';
+import { MiddlewareHandler } from '@orkestrel/server';
+import { MultipartBody } from '../core/index.ts';
+import { MultipartFile } from '../core/index.ts';
+import { MultipartState } from '../core/index.ts';
+
+/**
+ * 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"'
+ * ```
+ */
+export declare function computeFileETag(size: number, mtimeMs: number): string;
+
+/**
+ * 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 })
+ * ```
+ */
+export declare function createCompression<TState>(options?: NodeCompressionOptions): MiddlewareHandler<TState>;
+
+/**
+ * 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'] })
+ * ```
+ */
+export declare function createMultipart<TState extends MultipartState>(options?: MultipartOptions): MiddlewareHandler<TState>;
+
+/**
+ * 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 })
+ * ```
+ */
+export declare function createStatic<TState>(options: StaticOptions): MiddlewareHandler<TState>;
+
+/**
+ * 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' })
+ * ```
+ */
+export declare function createUploadedFile(input: UploadedFileInput): UploadedFileInterface;
+
+/** The MIME type served when a file extension has no known mapping. */
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+
+/** `createMultipart`'s default per-field byte-size cap. */
+export declare const DEFAULT_MULTIPART_FIELD = 65536;
+
+/** `createMultipart`'s default maximum field-part count. */
+export declare const DEFAULT_MULTIPART_FIELDS = 100;
+
+/** `createMultipart`'s default per-file byte-size cap. */
+export declare const DEFAULT_MULTIPART_FILE = 10485760;
+
+/** `createMultipart`'s default maximum file-part count. */
+export declare const DEFAULT_MULTIPART_FILES = 10;
+
+/** `createMultipart`'s default combined request-body byte-size cap. */
+export declare const DEFAULT_MULTIPART_TOTAL = 52428800;
+
+/** `createStatic`'s `fallback: true` default excluded path prefix. */
+export declare const DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
+
+/** `createStatic`'s default directory-index filename. */
+export declare const DEFAULT_STATIC_INDEX = "index.html";
+
+/**
+ * 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'
+ * ```
+ */
+export declare function detectMIME(head: Uint8Array): string | undefined;
+
+/** File-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. */
+export declare const EXTENSION_TYPES: Readonly<Record<string, string>>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isContainedPath(child: string, parent: string): boolean;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isDotfilePath(relativePath: string): boolean;
+
+/**
+ * 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)
+ * }
+ * ```
+ */
+export declare function isMultipartError(value: unknown): value is MultipartError;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isReservedDeviceName(segment: string): boolean;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isUnderPath(pathname: string, prefix: string): boolean;
+
+/**
+ * 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'
+ * ```
+ */
+export declare function lookupContentType(pathname: string): string;
+
+/**
+ * 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')
+ * ```
+ */
+export declare function moveUploadedFile(file: UploadedFileInterface, destination: string): Promise<UploadedFileInterface>;
+
+/** The maximum bytes a single multipart part's header block may occupy before it is malformed. */
+export declare const MULTIPART_MAX_HEADER_BLOCK = 16384;
+
+/** The maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+export declare const MULTIPART_MAX_PREAMBLE = 65536;
+
+/** The HTTP status `createMultipart` renders for each {@link MultipartReason}. */
+export declare const MULTIPART_REASON_STATUS: Readonly<Record<MultipartReason, number>>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function multipartBoundary(contentType: string | null): string | undefined;
+
+/**
+ * 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')
+ * ```
+ */
+export declare class MultipartError extends Error {
+    readonly status: number;
+    readonly reason: MultipartReason;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(reason: MultipartReason, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * Per-category size/count caps `createMultipart` enforces MID-STREAM.
+ *
+ * @remarks
+ * - `file` — the maximum size in bytes of one uploaded file; defaults to
+ *   {@link DEFAULT_MULTIPART_FILE}.
+ * - `files` — the maximum number of file parts; defaults to
+ *   {@link DEFAULT_MULTIPART_FILES}.
+ * - `field` — the maximum size in bytes of one text field; defaults to
+ *   {@link DEFAULT_MULTIPART_FIELD}.
+ * - `fields` — the maximum number of text field parts; defaults to
+ *   {@link DEFAULT_MULTIPART_FIELDS}.
+ * - `total` — the maximum combined byte size of the whole request body;
+ *   defaults to {@link DEFAULT_MULTIPART_TOTAL}.
+ */
+export declare interface MultipartLimits {
+    readonly file?: number;
+    readonly files?: number;
+    readonly field?: number;
+    readonly fields?: number;
+    readonly total?: number;
+}
+
+/**
+ * Options for `createMultipart` — node `fs`/`os`/`crypto`-backed streaming
+ * multipart upload parsing.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `limits` — see {@link MultipartLimits}.
+ * - `allowed` — a MIME allow-list validated against SNIFFED (not merely
+ *   declared) bytes; an empty array allows nothing. Omitted ⇒ no type
+ *   rejection.
+ * - `directory` — the directory staged files are written to; defaults to
+ *   `os.tmpdir()`.
+ */
+export declare interface MultipartOptions {
+    readonly limits?: MultipartLimits;
+    readonly allowed?: readonly string[];
+    readonly directory?: string;
+}
+
+/**
+ * Why `createMultipart` rejected a request — the axis {@link MultipartError}
+ * maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400,
+ * `'rejected'` → 415.
+ */
+export declare type MultipartReason = 'limit' | 'malformed' | 'rejected';
+
+/**
+ * Options for the node face's `createCompression` — `node:zlib`-backed
+ * response compression.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `threshold` — the minimum buffered body size (bytes) worth compressing;
+ *   defaults to {@link DEFAULT_COMPRESSION_THRESHOLD}.
+ * - `filter` — an additional predicate a response must pass before
+ *   compression is attempted; defaults to always-allow. `encodings` is fixed
+ *   to `['gzip', 'deflate']` and is not configurable (see the peer `Encoding`
+ *   type limitation documented on `createCompression`).
+ */
+export declare interface NodeCompressionOptions {
+    readonly threshold?: number;
+    readonly filter?: (request: Request, response: Response) => boolean;
+}
+
+/**
+ * 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'] })
+ * ```
+ */
+export declare function parseMultipartRequest(request: Request, options?: MultipartOptions): Promise<MultipartBody | undefined>;
+
+/**
+ * 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 }
+ * ```
+ */
+export declare function parsePartHeaders(block: string): PartHeaders;
+
+/**
+ * One multipart part's parsed header block — `parsePartHeaders`'s return
+ * shape.
+ *
+ * @remarks
+ * - `name` — the `Content-Disposition` `name` parameter, or `undefined` when absent.
+ * - `filename` — the `Content-Disposition` `filename` parameter, or `undefined` when absent.
+ * - `contentType` — the part's declared `Content-Type` header value, or `undefined` when absent.
+ */
+export declare interface PartHeaders {
+    readonly name: string | undefined;
+    readonly filename: string | undefined;
+    readonly contentType: string | undefined;
+}
+
+/**
+ * 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)
+ * ```
+ */
+export declare function readUploadedFile(file: UploadedFileInterface): Promise<Uint8Array>;
+
+/**
+ * Windows reserved device-name stems (CVE-2025-27210) — matched
+ * case-insensitively against the segment's stem (before its first `.`).
+ */
+export declare const RESERVED_DEVICE_NAMES: ReadonlySet<string>;
+
+/**
+ * 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()
+ * ```
+ */
+export declare function resolveDefaultDirectory(): Promise<string>;
+
+/**
+ * Resolve `createMultipart`'s effective {@link MultipartLimits}, applying
+ * every documented default.
+ *
+ * @param limits - The caller's partial limits
+ * @returns The fully-resolved limits
+ */
+export declare function resolveMultipartLimits(limits: MultipartLimits | undefined): Required<MultipartLimits>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function resolveStaticPath(root: string, prefix: string | undefined, pathname: string): string | undefined;
+
+/**
+ * Options for `createStatic` — node `fs`-backed static file serving.
+ *
+ * @param options - See fields below
+ * @remarks
+ * - `root` — the directory every request resolves under, resolved once at
+ *   construction. REQUIRED.
+ * - `prefix` — a URL path prefix stripped (on a segment boundary) before
+ *   resolving under `root`.
+ * - `index` — the filename served for a directory hit; defaults to
+ *   {@link DEFAULT_STATIC_INDEX}.
+ * - `dotfiles` — the policy for a path with a dotfile segment: `'ignore'`
+ *   (default, falls through to `next()`), `'deny'` (403), or `'allow'`
+ *   (serves it).
+ * - `cache` — `Cache-Control: max-age=<cache>` in seconds, when set.
+ * - `etag` — whether to compute and honor a weak file `ETag`; defaults to `true`.
+ * - `fallback` — SPA fallback: `false` (default, off), `true` (on, excluding
+ *   {@link DEFAULT_STATIC_FALLBACK_EXCLUDE}), or `{ exclude }` for a custom
+ *   excluded prefix.
+ */
+export declare interface StaticOptions {
+    readonly root: string;
+    readonly prefix?: string;
+    readonly index?: string;
+    readonly dotfiles?: 'ignore' | 'deny' | 'allow';
+    readonly cache?: number;
+    readonly etag?: boolean;
+    readonly fallback?: boolean | {
+        readonly exclude?: string;
+    };
+}
+
+/**
+ * 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'))
+ * ```
+ */
+export declare function streamFile(source: string | FileHandle, range?: {
+    readonly start: number;
+    readonly end: number;
+}): ReadableStream<Uint8Array>;
+
+/**
+ * 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))
+ * ```
+ */
+export declare function streamUploadedFile(file: UploadedFileInterface): ReadableStream<Uint8Array>;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function unlinkStagedFiles(body: MultipartBody): Promise<void>;
+
+/**
+ * The full field set `createUploadedFile` needs to build an
+ * {@link UploadedFileInterface} record.
+ *
+ * @remarks
+ * - `field` — the multipart field name the file was submitted under.
+ * - `name` — the client-declared filename (metadata only).
+ * - `size` — the file's byte size.
+ * - `mime` — the sniffed MIME type.
+ * - `validated` — `true` when the sniffed type matches the declared `Content-Type`.
+ * - `status` — see {@link UploadStatus}.
+ * - `path` — the file's current on-disk path.
+ */
+export declare interface UploadedFileInput {
+    readonly field: string;
+    readonly name: string;
+    readonly size: number;
+    readonly mime: string;
+    readonly validated: boolean;
+    readonly status: UploadStatus;
+    readonly path: string;
+}
+
+/**
+ * One uploaded file's post-parse record — the node-bound, richer sibling of
+ * the pure core's {@link MultipartFile} (identical fields, `status` narrowed
+ * to {@link UploadStatus}). Structurally assignable into {@link MultipartFile}
+ * so a `createMultipart`-built {@link MultipartBody} satisfies the shared
+ * core shape.
+ *
+ * @remarks
+ * - `field` — the multipart field name the file was submitted under.
+ * - `name` — the client-declared filename (METADATA ONLY — never used to
+ *   build a filesystem path).
+ * - `size` — the file's byte size.
+ * - `mime` — the SNIFFED (magic-byte-detected) MIME type.
+ * - `validated` — `true` when the sniffed type matches the declared
+ *   `Content-Type`.
+ * - `status` — see {@link UploadStatus}.
+ * - `path` — the file's current on-disk path.
+ */
+export declare interface UploadedFileInterface extends Omit<MultipartFile, 'status'> {
+    readonly status: UploadStatus;
+}
+
+/**
+ * The lifecycle stage of one staged upload's temp file.
+ *
+ * @remarks
+ * `'staged'` — written to the configured temp directory under a random name,
+ * not yet moved. `'moved'` — relocated by `moveUploadedFile` to its final path.
+ */
+export declare type UploadStatus = 'staged' | 'moved';
+
+export { }