@nifrajs/core 5.8.0 → 5.10.0

package/src/manifest.ts

@@ -1,6 +1,7 @@
 /** Deterministic, signed route manifest: contract × assurance × capabilities × classification. */
 
 import type { AssuranceReport } from "./assurance.ts"
+import { canonicalJson } from "./canonical-json.ts"
 import type { CapabilityAssuranceReport } from "./capabilities.ts"
 import {
   type DataClassification,
@@ -15,6 +16,8 @@ import {
 } from "./diff.ts"
 import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "./evidence.ts"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { hasControlCharacter } from "./internal/control-character.ts"
+import { sha256Hex } from "./internal/hex.ts"
 
 export interface NifraManifestAssurance {
   readonly rule?: string
@@ -70,35 +73,6 @@ export interface BuildNifraManifestInput {
 
 const encoder = new TextEncoder()
 
-function hasControlCharacter(value: string): boolean {
-  for (let index = 0; index < value.length; index++) {
-    const code = value.charCodeAt(index)
-    if (code <= 31 || code === 127) return true
-  }
-  return false
-}
-
-function canonicalValue(value: unknown): string {
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return JSON.stringify(value)
-  }
-  if (typeof value === "number") {
-    if (!Number.isFinite(value))
-      throw new TypeError("nifra manifest cannot encode non-finite numbers")
-    return JSON.stringify(value)
-  }
-  if (Array.isArray(value)) return `[${value.map((item) => canonicalValue(item)).join(",")}]`
-  if (typeof value === "object") {
-    const record = value as Readonly<Record<string, unknown>>
-    return `{${Object.keys(record)
-      .filter((key) => record[key] !== undefined)
-      .sort()
-      .map((key) => `${JSON.stringify(key)}:${canonicalValue(record[key])}`)
-      .join(",")}}`
-  }
-  throw new TypeError(`nifra manifest cannot encode ${typeof value}`)
-}
-
 function manifestBody(manifest: Pick<NifraManifest, "manifestVersion" | "routes">): {
   readonly manifestVersion: 1
   readonly routes: readonly NifraManifestRoute[]
@@ -110,17 +84,17 @@ function manifestBody(manifest: Pick<NifraManifest, "manifestVersion" | "routes"
 export function canonicalManifest(
   manifest: Pick<NifraManifest, "manifestVersion" | "routes">,
 ): string {
-  return canonicalValue(manifestBody(manifest))
+  return canonicalJson(manifestBody(manifest))
 }
 
 /** Byte-stable artifact serialization (including `contentHash`). */
 export function serializeNifraManifest(manifest: NifraManifest): string {
-  return canonicalValue(manifest)
+  return canonicalJson(manifest)
 }
 
 /** Byte-stable serialization for the detached signature sidecar. */
 export function serializeNifraManifestSignature(signature: NifraManifestSignature): string {
-  return canonicalValue(signature)
+  return canonicalJson(signature)
 }
 
 /** Parse the detached sidecar before selecting its operator-controlled public key. */
@@ -163,11 +137,6 @@ export function parseNifraManifestSignature(
   return Object.freeze(candidate as NifraManifestSignature)
 }
 
-async function sha256Hex(value: string): Promise<string> {
-  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)))
-  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")
-}
-
 const routeKey = (method: string, path: string): string => `${method.toUpperCase()}\n${path}`
 const sortedStrings = (values: Iterable<string>): readonly string[] =>
   Object.freeze([...new Set(values)].sort())
@@ -255,7 +224,10 @@ export async function buildNifraManifest(input: BuildNifraManifestInput): Promis
 function base64Url(bytes: Uint8Array): string {
   let binary = ""
   for (const byte of bytes) binary += String.fromCharCode(byte)
-  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "")
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/={1,2}$/, "")
 }
 
 function fromBase64Url(value: string): Uint8Array<ArrayBuffer> {

package/src/open-resolved.ts

@@ -0,0 +1,64 @@
+import { constants as FS } from "node:fs"
+import { type FileHandle, open, readlink, realpath, stat } from "node:fs/promises"
+
+// Darwin's open(2) flag refusing a symlink in ANY component; `O_NOFOLLOW` covers only the last one.
+const O_NOFOLLOW_ANY = 0x20000000
+// Deno's node:fs rejects flags it does not know with EINVAL; the first refusal turns the flag off.
+let noFollowAny: boolean | undefined
+
+/**
+ * Open a name `realpath` already resolved, refusing it when any component became a symlink since.
+ * A local writer inside the served tree can swap an intermediate directory for a link after the
+ * containment check; `O_NOFOLLOW` alone would follow it. Darwin refuses such a path in the kernel;
+ * Linux reads back the name the descriptor holds. Elsewhere, Windows included, no file API can open
+ * without following a middle link or name an open descriptor's path, so the check in
+ * {@link opensAt} is a platform limit: it narrows the race to repeated swaps but cannot close it.
+ */
+export async function openResolved(realFile: string): Promise<FileHandle> {
+  // Read per open, not at load: this module can sit in a client bundle graph, where `process` is
+  // undefined.
+  if (noFollowAny ?? process.platform === "darwin") {
+    try {
+      return await open(realFile, FS.O_RDONLY | O_NOFOLLOW_ANY)
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EINVAL")) throw error
+      noFollowAny = false
+    }
+  }
+  const handle = await open(realFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+  try {
+    if (await opensAt(handle, realFile)) return handle
+  } catch {}
+  await handle.close()
+  throw Object.assign(new Error(`${realFile} moved while it was opened`), { code: "ELOOP" })
+}
+
+/** Whether `handle` is the file at `realFile` with no symlink in its path. */
+export async function opensAt(
+  handle: Pick<FileHandle, "fd" | "stat">,
+  realFile: string,
+): Promise<boolean> {
+  try {
+    return (await readlink(`/proc/self/fd/${handle.fd}`)) === realFile
+  } catch {
+    return sameFileAt(handle, realFile)
+  }
+}
+
+/**
+ * {@link opensAt} where no descriptor's path can be read. Exported for its test, which runs it on
+ * every host.
+ */
+export async function sameFileAt(
+  handle: Pick<FileHandle, "stat">,
+  realFile: string,
+): Promise<boolean> {
+  // One step after another, so passing takes a swap back and a swap again between steps: the name
+  // resolves to itself, then to the opened file, then to itself again. Identities are compared as
+  // bigints because a Windows file index can exceed 2^53.
+  if ((await realpath(realFile)) !== realFile) return false
+  const opened = await handle.stat({ bigint: true })
+  const named = await stat(realFile, { bigint: true })
+  if (opened.dev !== named.dev || opened.ino !== named.ino) return false
+  return (await realpath(realFile)) === realFile
+}

package/src/range.ts

@@ -104,7 +104,7 @@ export function parseByteRange(value: string | null, size: number): ByteRangeRes
   if (value.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
   const single = parseSingleRange(value, size)
   if (single !== undefined) return single
-  const match = /^bytes\s*=\s*(.+)$/i.exec(value)
+  const match = /^bytes\s*=\s*(\S.*)$/i.exec(value)
   if (match === null) return { kind: "none" }
   const source = match[1]!
   let separators = 0

package/src/router/path-codec.ts

@@ -0,0 +1,93 @@
+// One URL path segment, encoded and decoded. Every place that spells a value into a path calls this
+// module, so a link, a prerendered file, a client request and a public asset agree on one spelling.
+
+const HEX = "0123456789ABCDEF"
+
+const UNRESERVED = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+
+function rawTable(chars: string): Uint8Array {
+  const table = new Uint8Array(128)
+  for (let i = 0; i < chars.length; i++) table[chars.charCodeAt(i)] = 1
+  return table
+}
+
+// RFC 3986 `pchar` minus `;`: the unreserved set, the sub-delimiters, `:` and `@`. `;` delimits path
+// parameters (RFC 3986 section 3.3) and servlet containers strip them; `[`, `]` and `|` are not valid in
+// a path at all and Tomcat rejects them unencoded by default.
+const CANONICAL = /* @__PURE__ */ rawTable(`${UNRESERVED}!$&'()*+,:=@`)
+
+// What a browser leaves as written in a path: the canonical set plus `;`, `[`, `]` and `|`.
+const BROWSER = /* @__PURE__ */ rawTable(`${UNRESERVED}!$&'()*+,:=@;[]|`)
+
+function encodeNonAscii(run: string): string {
+  try {
+    return encodeURIComponent(run)
+  } catch {
+    throw new RangeError("[nifra/core] a path segment cannot hold a lone surrogate")
+  }
+}
+
+function encodeWith(raw: Uint8Array, value: string): string {
+  if (value === "." || value === "..") {
+    throw new RangeError(
+      `[nifra/core] a path segment cannot be ${JSON.stringify(value)}: every spelling of it is a dot segment to a URL parser`,
+    )
+  }
+  const length = value.length
+  let out = ""
+  let start = 0
+  let i = 0
+  while (i < length) {
+    const code = value.charCodeAt(i)
+    if (code < 128 && raw[code] === 1) {
+      i++
+      continue
+    }
+    out += value.slice(start, i)
+    if (code < 128) {
+      out += `%${HEX[code >> 4]}${HEX[code & 15]}`
+      i++
+    } else {
+      let end = i + 1
+      while (end < length && value.charCodeAt(end) >= 128) end++
+      out += encodeNonAscii(value.slice(i, end))
+      i = end
+    }
+    start = i
+  }
+  return start === 0 ? value : out + value.slice(start)
+}
+
+/**
+ * `value` as one path segment. Left as written: letters, digits, the at sign and `- . _ ~ ! $ & ' ( ) * + , : =`.
+ * Everything else is percent-encoded, UTF-8 and upper-case hex, including `; [ ] | / ? # % \`.
+ *
+ * Throws a `RangeError` for a value that no segment can carry: exactly `.` or `..` (a URL parser reads
+ * `%2E` and `%2E%2E` as dot segments too) and a lone surrogate (substituting U+FFFD would map distinct
+ * values to one URL). The empty string is returned as is; a caller that cannot use it checks for it.
+ */
+export function encodePathSegment(value: string): string {
+  return encodeWith(CANONICAL, value)
+}
+
+/**
+ * `value` as a browser spells it in a request URL: {@link encodePathSegment} with `; [ ] |` left as
+ * written. Used for one thing, registering a public file under the spelling its page links request;
+ * it differs from the canonical form on those four characters only.
+ */
+export function browserPathSegment(value: string): string {
+  return encodeWith(BROWSER, value)
+}
+
+/**
+ * `raw` with its percent-escapes decoded, or `undefined` when one is malformed. The inverse of
+ * {@link encodePathSegment} and of {@link browserPathSegment}; a segment in any other spelling decodes
+ * too. What a malformed escape means is the caller's policy.
+ */
+export function decodePathSegment(raw: string): string | undefined {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return undefined
+  }
+}

package/src/router/pattern.ts

@@ -1,4 +1,8 @@
 import { RouteConfigError } from "../errors.ts"
+import { encodePathSegment } from "./path-codec.ts"
+
+export { browserPathSegment, decodePathSegment, encodePathSegment } from "./path-codec.ts"
+export { isSameOriginPath } from "./same-origin-path.ts"
 
 const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"])
@@ -649,6 +653,129 @@ export function decodeRouteParams(raw: Record<string, string>): Record<string, s
   return out ?? raw
 }
 
+export type FilledRoutePath =
+  | { readonly ok: true; readonly path: string }
+  | {
+      readonly ok: false
+      /** Params the pattern names that `params` leaves out or holds as the empty string. */
+      readonly missing: readonly string[]
+      /** Params whose value cannot be carried or would be split differently by this pattern. */
+      readonly invalid: readonly string[]
+    }
+
+/**
+ * The path `pattern` names for `params`, every value spelled by {@link encodePathSegment}. A wildcard
+ * value is split on `/` and each part encoded, empty parts dropped; a `.` or `..` part is invalid, as
+ * a whole-segment value is. Nothing is thrown for a bad value: the caller decides what a missing or
+ * invalid param means. A param inside a mixed segment is invalid when its value holds the literal that ends it (`name` = `a.b` in
+ * `:name.:ext`), or when it touches the next param and encodes to more than one character, because the
+ * router would split it differently. A param's constraint (`:id{[0-9]+}`) is not checked here.
+ */
+export function fillRoutePath(
+  pattern: string | CompiledRoutePattern,
+  params: Readonly<Record<string, string | undefined>>,
+): FilledRoutePath {
+  const compiled = typeof pattern === "string" ? compileRoutePattern(pattern) : pattern
+  // Built as one string, with the two problem lists made only when a param is bad: a path that fills
+  // allocates nothing else.
+  let path = ""
+  let missing: string[] | undefined
+  let invalid: string[] | undefined
+  const segments = compiled.segments
+  for (let s = 0; s < segments.length; s++) {
+    const segment = segments[s]!
+    if (segment.kind === "static") {
+      path += `/${segment.value}`
+    } else if (segment.kind === "param") {
+      const value = fillValue(params, segment.name)
+      if (value === undefined) {
+        missing = noted(missing, segment.name)
+        path += "/"
+        continue
+      }
+      const encoded = spell(value)
+      if (encoded === undefined) invalid = noted(invalid, segment.name)
+      path += `/${encoded ?? ""}`
+    } else if (segment.kind === "wildcard") {
+      const value = fillValue(params, segment.name)
+      let joined = ""
+      let any = false
+      if (value !== undefined) {
+        for (const piece of value.split("/")) {
+          if (piece === "") continue
+          const encoded = spell(piece)
+          if (encoded === undefined) invalid = noted(invalid, segment.name)
+          joined += any ? `/${encoded ?? ""}` : (encoded ?? "")
+          any = true
+        }
+      }
+      if (!any) missing = noted(missing, segment.name)
+      path += `/${joined}`
+    } else {
+      let text = ""
+      const shape = segment.parts
+      for (let i = 0; i < shape.length; i++) {
+        const part = shape[i]!
+        if (part.t === "lit") {
+          text += part.v
+          continue
+        }
+        const value = fillValue(params, part.name)
+        if (value === undefined) {
+          missing = noted(missing, part.name)
+          continue
+        }
+        const encoded = spell(value)
+        if (encoded === undefined) {
+          invalid = noted(invalid, part.name)
+          continue
+        }
+        // matchMixedSegment ends a parameter at the first occurrence of the literal after it, one
+        // character in or later. A value holding that literal earlier would come back as different
+        // params. A literal in the last place is the segment's tail, which is anchored to its end.
+        const next = shape[i + 1]
+        // With no separating literal the matcher gives this parameter exactly one raw character.
+        // Splitting a percent-escape here would also make the captured parameters malformed.
+        if (next?.t === "param" && encoded.length !== 1) invalid = noted(invalid, part.name)
+        else if (next?.t === "lit" && shape[i + 2] !== undefined) {
+          if ((encoded + next.v).indexOf(next.v, 1) !== encoded.length)
+            invalid = noted(invalid, part.name)
+        }
+        text += encoded
+      }
+      path += `/${text}`
+    }
+  }
+  return missing !== undefined || invalid !== undefined
+    ? { ok: false, missing: missing ?? [], invalid: invalid ?? [] }
+    : { ok: true, path: path === "" ? "/" : path }
+}
+
+/** A param's value when it is a non-empty string the caller gave, not one inherited from the prototype. */
+function fillValue(
+  params: Readonly<Record<string, string | undefined>>,
+  name: string,
+): string | undefined {
+  const value = Object.hasOwn(params, name) ? params[name] : undefined
+  return typeof value === "string" && value !== "" ? value : undefined
+}
+
+/** `value` spelled as one path segment, or undefined when no segment can carry it. */
+function spell(value: string): string | undefined {
+  try {
+    return encodePathSegment(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** `list` with `name` in it once, made when there was none. */
+function noted(list: string[] | undefined, name: string): string[] {
+  if (list === undefined) return [name]
+  if (!list.includes(name)) list.push(name)
+  return list
+}
+
 /** Match one compiled pattern and return decoded captures. The caller decides cross-pattern order. */
 export function matchRoutePattern(
   compiled: CompiledRoutePattern,

package/src/router/same-origin-path.ts

@@ -0,0 +1,36 @@
+/**
+ * Is `value` a destination that stays on this origin?
+ *
+ * True only for an absolute path: one leading `/`, never `//` (protocol-relative → another origin),
+ * and free of any character a URL parser turns into an origin escape. A leading `/` alone is not
+ * enough: under a special scheme `\` parses as `/`, and tab/CR/LF are STRIPPED before parsing, so
+ * `/\evil.example` and `/<TAB>/evil.example` both resolve to the external host `evil.example` while
+ * passing a `//` test. Rejecting CR/LF here also keeps a validated destination out of the
+ * response-splitting sink it usually flows into.
+ *
+ * One implementation, because every caller is the same open-redirect gate: `redirect()` and
+ * `rawHref()` in `@nifrajs/web`, the `redirectTo` of the `@nifrajs/auth` and `@nifrajs/better-auth` guards. Three
+ * copies of a security predicate is three chances for one of them to be hardened alone.
+ *
+ * It answers about a PATH, not a URL: an absolute `https://this.host/x` is false even for the
+ * current origin, because the whole point is that the value never got to name a host.
+ *
+ * It sits in a leaf with no imports, so browser code (`rawHref` in `@nifrajs/web`) can use it without
+ * the server entry; `@nifrajs/core/server` and `@nifrajs/core/pattern` both export it.
+ */
+export function isSameOriginPath(value: string): boolean {
+  if (!value.startsWith("/") || value.startsWith("//")) return false
+  // Scanned by character code rather than matched by regex: no control characters have to be written
+  // into a pattern, and the check is a single pass over a short string.
+  for (let i = 1; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code === 0x5c /* \ */ || code <= 0x1f || code === 0x7f) return false
+  }
+  // `/.//host` and `/a/..//host` (or their `%2e` forms) resolve to the path `//host`, which any
+  // relative reference later built from that path - a client router's redirect - reads as a host.
+  // A path-absolute reference against a valid base always parses, so this cannot throw.
+  return (
+    !(value.includes(".") || value.includes("%")) ||
+    !new URL(value, "http://n.invalid").pathname.startsWith("//")
+  )
+}

package/src/serve-static.ts

@@ -0,0 +1,227 @@
+/**
+ * `serveStatic()` for Bun's `listen({ static })`: files on disk under URL prefixes, with the same
+ * mounts `@nifrajs/node` and `@nifrajs/deno` take. Which request a mount takes and how it answers is
+ * `./static-file.ts`; this module only reads the file, through node:fs, which Bun runs natively.
+ *
+ * A subpath rather than part of `listen()`, so an app that serves no files bundles no file reader.
+ */
+import { createHash } from "node:crypto"
+import { type FileHandle, realpath } from "node:fs/promises"
+import { isAbsolute, relative, resolve, sep } from "node:path"
+import { Readable } from "node:stream"
+import { fileURLToPath } from "node:url"
+import { openResolved } from "./open-resolved.ts"
+import { parseByteRange } from "./range.ts"
+import { pathnameOf } from "./server/http.ts"
+import {
+  CONTENT_SNAPSHOT_MAX,
+  contentTags,
+  isHiddenPath,
+  matchStatic,
+  planStatic,
+  type ServeStaticOptions,
+  type StaticMount,
+  staticMountsOf,
+} from "./static-file.ts"
+
+export type { HashedFiles, ServeStaticOptions } from "./static-file.ts"
+export { IMMUTABLE, ONE_DAY } from "./static-file.ts"
+
+// Bun.serve drops the declared length of any stream body and sends it chunked, and a Bun.file body
+// would need this descriptor open for a send nothing reports the end of. So on Bun a body up to 1 MiB
+// is read whole: a slow client then holds ~1 MB, against ~0.6 MB through Bun's stream sink.
+const BUFFERED_BODY_MAX = typeof Bun === "undefined" ? CONTENT_SNAPSHOT_MAX : 1024 * 1024
+
+// One per process: the tag of a file served from any mount is remembered by its real path.
+const TAGS = contentTags(createHash)
+
+function rootOf(dir: string | URL): string {
+  return resolve(typeof dir === "string" ? dir : fileURLToPath(dir))
+}
+
+/** The host of an absolute URL, as `new URL(url).host` would give it, without parsing the rest. */
+function hostOf(url: string): string {
+  const start = url.indexOf("//") + 2
+  let end = start
+  while (end < url.length) {
+    const code = url.charCodeAt(end)
+    if (code === 47 /* '/' */ || code === 63 /* '?' */ || code === 35 /* '#' */) break
+    end++
+  }
+  return url.slice(start, end)
+}
+
+function refusalOf(status: 400 | 403 | 404): Response {
+  return new Response(status === 400 ? "Bad Request" : status === 403 ? "Forbidden" : "Not Found", {
+    status,
+  })
+}
+
+/** `length` bytes of `handle` from `start`; fewer when the file shrank since its stat. */
+async function readPinned(
+  handle: FileHandle,
+  start: number,
+  length: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const bytes = new Uint8Array(length)
+  let offset = 0
+  while (offset < length) {
+    const { bytesRead } = await handle.read(bytes, offset, length - offset, start + offset)
+    if (bytesRead === 0) break
+    offset += bytesRead
+  }
+  return offset === length ? bytes : bytes.subarray(0, offset)
+}
+
+interface BunMount extends StaticMount {
+  /** The directory's real path, resolved on first use and again after a miss, so one made later serves. */
+  realRoot: Promise<string | undefined> | undefined
+}
+
+/**
+ * The answer for `rel` under `mount`, or `undefined` when the mount falls through on a file it cannot
+ * serve.
+ */
+async function readStatic(
+  mount: BunMount,
+  rel: string,
+  immutable: boolean,
+  request: Request,
+): Promise<Response | undefined> {
+  const missing = (status: 403 | 404 = 404): Response | undefined =>
+    mount.fallthrough ? undefined : refusalOf(status)
+  const file = resolve(mount.root, rel)
+  // A drive or root in the decoded name (`C:/x` on Windows) leaves the directory without a `..`.
+  const contained = relative(mount.root, file)
+  if (contained.startsWith("..") || isAbsolute(contained)) return missing(403)
+  // Containment is checked on the RESOLVED name and that name is what opens, so a link swapped inside
+  // the tree after the check cannot redirect the read; openResolved refuses a name that gained a link.
+  mount.realRoot ??= realpath(mount.root).catch(() => undefined)
+  const [realRoot, realFile] = await Promise.all([
+    mount.realRoot,
+    realpath(file).catch(() => undefined),
+  ])
+  if (realRoot === undefined) mount.realRoot = undefined
+  if (
+    realRoot === undefined ||
+    realFile === undefined ||
+    (realFile !== realRoot && !realFile.startsWith(realRoot + sep))
+  ) {
+    return missing()
+  }
+  // A visible name linking to a dotfile inside the directory answers as a missing file does.
+  if (
+    mount.denyDotfiles &&
+    realFile !== realRoot &&
+    isHiddenPath(realFile.slice(realRoot.length + 1))
+  ) {
+    return missing()
+  }
+  let handle: FileHandle | undefined
+  try {
+    try {
+      handle = await openResolved(realFile)
+    } catch {
+      return missing()
+    }
+    const opened = handle
+    const stat = await opened.stat()
+    if (!stat.isFile()) return missing()
+    const method = request.method === "HEAD" ? "HEAD" : "GET"
+    let whole: Uint8Array<ArrayBuffer> | undefined
+    const plan = await planStatic(
+      mount,
+      immutable,
+      { method, header: (name) => request.headers.get(name) },
+      {
+        path: realFile,
+        version: stat,
+        readWhole: async () => {
+          whole = await readPinned(opened, 0, stat.size)
+          return whole
+        },
+        restat: () => opened.stat(),
+        tags: TAGS,
+        parseRange: parseByteRange,
+      },
+    )
+    if (!plan.body) return new Response(null, { status: plan.status, headers: plan.headers })
+    const { start, length, headers } = plan
+    if (length <= BUFFERED_BODY_MAX) {
+      const body =
+        whole === undefined
+          ? await readPinned(opened, start, length)
+          : whole.subarray(start, start + length)
+      headers["content-length"] = String(body.byteLength)
+      return new Response(body, { status: plan.status, headers })
+    }
+    const stream = opened.createReadStream({ start, end: start + length - 1 })
+    // createReadStream owns closing the descriptor after EOF or abort.
+    handle = undefined
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: node:stream/web's ReadableStream is the global one on Bun; only the declarations differ.
+    const body = Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>
+    return new Response(body, { status: plan.status, headers })
+  } catch {
+    // Unreadable under the prefix: a 404 (not an SSR 404 page), unless the mount falls through.
+    return missing()
+  } finally {
+    try {
+      await handle?.close()
+    } catch {
+      // A close that fails changes nothing about the answer already chosen.
+    }
+  }
+}
+
+function serveFrom(
+  mounts: readonly BunMount[],
+  from: number,
+  request: Request,
+  path: string,
+  host: () => string,
+): Promise<Response | undefined> | undefined {
+  for (let i = from; i < mounts.length; i++) {
+    const mount = mounts[i]
+    if (mount === undefined) break
+    const matched = matchStatic(mount, path, host)
+    if (matched === "pass") continue
+    // matchStatic passes what a falling-through mount refuses, so a status here is always answered.
+    if ("status" in matched) return Promise.resolve(refusalOf(matched.status))
+    return readStatic(mount, matched.rel, matched.immutable, request).then(
+      (response) => response ?? serveFrom(mounts, i + 1, request, path, host),
+    )
+  }
+  return undefined
+}
+
+/**
+ * The `static` handler for files on disk, for Bun's `listen()`: each mount serves a directory under a
+ * URL prefix, and the first mount whose prefix (and `files`, when set) takes a GET or HEAD path
+ * answers it. A request no mount takes returns `undefined` synchronously and reaches the app. The
+ * same mounts work with `@nifrajs/node`'s and `@nifrajs/deno`'s `serveStatic`.
+ *
+ * Files up to 256 KiB carry a strong `ETag` from the exact bytes served. Larger files stream with no
+ * tag and a weak date, so an `If-Range` gets the whole file rather than a range spliced from two
+ * versions.
+ *
+ * @example
+ * ```ts
+ * import { serveStatic } from "@nifrajs/core/serve-static"
+ *
+ * app.listen(3000, { static: serveStatic({ dir: new URL("./assets/", import.meta.url) }) })
+ * ```
+ */
+export function serveStatic(
+  mounts: ServeStaticOptions | readonly ServeStaticOptions[],
+): (request: Request) => Promise<Response | undefined> | undefined {
+  const states: readonly BunMount[] = staticMountsOf(mounts, rootOf).map((mount) => ({
+    ...mount,
+    realRoot: undefined,
+  }))
+  return (request) => {
+    const method = request.method
+    if (method !== "GET" && method !== "HEAD") return undefined
+    const url = request.url
+    return serveFrom(states, 0, request, pathnameOf(url), () => hostOf(url))
+  }
+}