@c9up/ream 0.2.13 → 0.2.15

package/src/index.ts

@@ -101,7 +101,7 @@ export { default as SessionMiddleware } from './session/SessionMiddleware.js'
 
 export type { BodyParserConfig } from './bodyparser/BodyParserMiddleware.js'
 export { default as BodyParserMiddleware } from './bodyparser/BodyParserMiddleware.js'
-export type { FileValidationOptions } from './bodyparser/MultipartFile.js'
+export type { FileValidationOptions, MimeType } from './bodyparser/MultipartFile.js'
 export { MultipartFile } from './bodyparser/MultipartFile.js'
 
 // ─── JSON-RPC ───────────────────────────────────────────────
@@ -254,7 +254,7 @@ export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignito
 // ─── Providers ──────────────────────────────────────────────
 
 export { errors } from './errors/aggregate.js'
-export type { AppContext, ProviderContract } from './Provider.js'
+export type { AppContext, ConfigReader, ProviderContract } from './Provider.js'
 export { Provider } from './Provider.js'
 export type {
   AuthenticatorName,
@@ -378,4 +378,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.13'
+export const VERSION = '0.2.15'

package/src/native/generated.ts

@@ -87,8 +87,14 @@ export declare class HyperServer {
    * the safe default for a dev machine.
    */
   constructor(port?: number | undefined | null, host?: string | undefined | null)
-  /** Register the request handler. Callback receives JSON request string, must return JSON response string. */
-  onRequest(callback: (request: string) => Promise<string> | string): void
+  /**
+   * Register the request handler.
+   *
+   * The request arrives as an OBJECT (`serde_json::Value` → `JsObject`) and
+   * the handler answers with a `NapiResponse` object — not the JSON strings
+   * this comment described until the boundary stopped carrying them.
+   */
+  onRequest(callback: (request: Record<string, unknown>) => Promise<NapiResponse>): void
   /**
    * Configure the trusted-proxy CIDR list used by `request.ip` resolution.
    * Must be called BEFORE `listen()`. Empty list = legacy permissive mode
@@ -155,12 +161,10 @@ export declare class HyperServer {
    */
   writeStreamBytes(streamId: string, chunk: Uint8Array): Promise<boolean>
   /**
-  * Close a stream from the server side. The matching response body
-  * finishes cleanly (hyper writes the final chunk + `0
-  
-  ` for
-  * HTTP/1.1 chunked encoding). Idempotent.
-  */
+   * Close a stream from the server side. The matching response body
+   * finishes cleanly (hyper writes the final chunk + `0\r\n\r\n` for
+   * HTTP/1.1 chunked encoding). Idempotent.
+   */
   closeStream(streamId: string): Promise<boolean>
   /**
    * Install a one-shot callback fired the moment the matching stream

package/src/openapi/OpenApiGenerator.ts

@@ -170,9 +170,9 @@ export class OpenApiGenerator {
     }
 
     if (route.validators.length > 0 && ['post', 'put', 'patch'].includes(method)) {
-      const validatorName = route.validators[0]
-      const schema = this.#runeSchemas.get(validatorName)
-      if (schema) {
+      const [validatorName] = route.validators
+      const schema = validatorName === undefined ? undefined : this.#runeSchemas.get(validatorName)
+      if (schema && validatorName !== undefined) {
         operation.requestBody = {
           required: true,
           content: { 'application/json': { schema: this.#runeToJsonSchema(schema) } },
@@ -197,7 +197,9 @@ export class OpenApiGenerator {
   /** Extract parameter names from path. */
   #extractPathParams(path: string): string[] {
     const matches = path.matchAll(/:(\w+)\??/g)
-    return [...matches].map((m) => m[1])
+    // Group 1 is required by the pattern, so every match carries it; the
+    // filter is how that is stated instead of asserted.
+    return [...matches].map((m) => m[1]).filter((name) => name !== undefined)
   }
 
   /** Generate a summary from route metadata. */

package/src/router/Router.ts

@@ -25,7 +25,16 @@ export interface SignedUrlOptions {
 
 // ─── Types ──────────────────────────────────────────────────
 
-export type RouteHandlerFunction = (ctx: HttpContext) => Promise<void> | void
+/**
+ * A route handler. Whatever it returns is awaited and dropped — the response
+ * is written through `ctx.response`.
+ *
+ * `unknown`, not `Promise<void> | void`: a bare `void` return type accepts a
+ * function returning anything, but a UNION containing it does not, so
+ * `router.get('/x', () => 'ok')` was a type error for returning a value the
+ * kernel already ignores.
+ */
+export type RouteHandlerFunction = (ctx: HttpContext) => unknown
 
 /**
  * Controller tuple: [ControllerClass, 'methodName'].
@@ -267,7 +276,13 @@ export class RouteBuilder extends Macroable {
 
   /** The primary definition — accessors read from it (all verbs share pattern/name). */
   #primary(): RouteDefinition {
-    return this.#routes[0]
+    const [first] = this.#routes
+    if (first === undefined) {
+      // A route is constructed with at least one verb, so this cannot happen —
+      // and this is where that is stated rather than asserted past.
+      throw new Error('Route has no definitions')
+    }
+    return first
   }
 
   /** Name this route (for URL generation and redirects). */
@@ -1557,9 +1572,13 @@ function matchPath(pattern: string, actual: string): MatchedParams | null {
     const params: MatchedParams = {}
     for (let i = 0; i < wildcardIdx; i++) {
       const part = patternParts[i]
+      const actual = actualParts[i]
+      // Both are read out of arrays whose length was checked above; naming
+      // them is what turns that check into something the compiler shares.
+      if (part === undefined || actual === undefined) return null
       if (part.startsWith(':')) {
-        params[part.substring(1)] = safeDecodeURIComponent(actualParts[i])
-      } else if (part !== actualParts[i]) {
+        params[part.substring(1)] = safeDecodeURIComponent(actual)
+      } else if (part !== actual) {
         return null
       }
     }
@@ -1579,22 +1598,22 @@ function matchPath(pattern: string, actual: string): MatchedParams | null {
 
   const params: MatchedParams = {}
 
-  for (let i = 0; i < patternParts.length; i++) {
-    const part = patternParts[i]
+  for (const [i, part] of patternParts.entries()) {
     const isOptional = part.endsWith('?')
+    const actual = actualParts[i]
 
     if (part.startsWith(':')) {
       const paramName = isOptional ? part.slice(1, -1) : part.substring(1)
-      if (i < actualParts.length) {
+      if (actual !== undefined) {
         // Percent-decode the captured segment (query strings already are) so
         // `/users/Jos%C3%A9` yields `José` and matchers test the real value.
         // safeDecode falls back to the raw segment on malformed input.
-        params[paramName] = safeDecodeURIComponent(actualParts[i])
+        params[paramName] = safeDecodeURIComponent(actual)
       }
       // Optional param with no actual part — skip (param not set)
-    } else if (i < actualParts.length && part !== actualParts[i]) {
+    } else if (actual !== undefined && part !== actual) {
       return null
-    } else if (i >= actualParts.length && !isOptional) {
+    } else if (actual === undefined && !isOptional) {
       return null
     }
   }
@@ -1612,7 +1631,8 @@ function matchPath(pattern: string, actual: string): MatchedParams | null {
  * Comparing them verbatim sends that request to a fallback, or to a 404.
  */
 function matchDomain(pattern: string, host: string): boolean {
-  const actualHost = host.split(':')[0].toLowerCase() // strip port
+  const [hostname = ''] = host.split(':') // strip port
+  const actualHost = hostname.toLowerCase()
   const wanted = pattern.toLowerCase()
   if (wanted === actualHost) return true
   if (wanted.startsWith('*.')) {

package/src/rpc/RpcRouter.ts

@@ -30,7 +30,7 @@ export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown>
  * the shared `'middleware'` registry, and `validator:<name>` schemas.
  */
 interface RpcContainer {
-  make<T>(target: new (...args: unknown[]) => T): Promise<T>
+  make<T>(target: abstract new (...args: never[]) => T): Promise<T>
   resolve<T>(token: string): Promise<T>
   has(token: string): boolean
 }
@@ -151,11 +151,21 @@ export class RpcRouter {
     return new RpcMethodBuilder(def)
   }
 
-  /** Register methods from a controller — auto-registers all public methods. */
-  namespace(
-    prefix: string,
-    controller: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>,
-  ): void {
+  /**
+   * Register methods from a controller — auto-registers all public methods.
+   *
+   * The parameter used to demand
+   * `new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>`,
+   * which NO real controller satisfies: a class with any non-method property
+   * fails the `Record`, and a method declared `bump(): number` fails the
+   * `unknown[]` parameters, which are compared contravariantly. So the
+   * documented call — `rpc.namespace('task', TaskController)` — did not
+   * typecheck, and nothing noticed because the tests were outside `tsc`.
+   *
+   * Any class, then. The body already checks that what it found is callable
+   * and names the method when it is not.
+   */
+  namespace(prefix: string, controller: abstract new (...args: never[]) => object): void {
     const proto = controller.prototype
     const methods = Object.getOwnPropertyNames(proto).filter(
       (m) => m !== 'constructor' && typeof proto[m] === 'function',
@@ -164,8 +174,18 @@ export class RpcRouter {
       this.method(`${prefix}.${methodName}`, async (ctx, params) => {
         // Resolve through the container on every call (fresh DI per request,
         // like GraphQLEngine), falling back to a bare `new` when unset.
-        const instance = this.#container ? await this.#container.make(controller) : new controller()
-        return instance[methodName](ctx, params)
+        // `Reflect.construct`, not `new controller()`: the token may be an
+        // abstract class, which the runtime builds happily and `new` refuses.
+        const instance: object = this.#container
+          ? await this.#container.make(controller)
+          : Reflect.construct(controller, [])
+        const handler = Reflect.get(instance, methodName)
+        if (typeof handler !== 'function') {
+          throw new Error(
+            `RPC method '${prefix}.${methodName}' is not a function on ${controller.name}`,
+          )
+        }
+        return handler.call(instance, ctx, params)
       })
     }
   }
@@ -199,6 +219,16 @@ export class RpcRouter {
 
     // Batch support (max 50 to prevent DoS)
     if (Array.isArray(body)) {
+      // §6: "If the batch rpc call itself fails to be recognized as an valid
+      // JSON or as an Array with at least one value, the response from the
+      // Server MUST be a single Response object." An empty batch answered with
+      // 204 No Content, which is what this replies when every call in a batch
+      // was a notification — so a client that sent nothing was told its calls
+      // had run.
+      if (body.length === 0) {
+        ctx.response.status(200).json(rpcError(-32600, 'Invalid Request', null))
+        return
+      }
       if (body.length > 50) {
         ctx.response.status(400).json(rpcError(-32600, 'Batch too large (max 50)', null))
         return

package/src/scheduler/Schedule.ts

@@ -90,7 +90,14 @@ export function Schedule(cronExpr: string): MethodDecorator {
  * none). Returns a shallow copy so callers cannot mutate the stored
  * metadata by accident.
  */
-export function getScheduleMetadata(target: Constructor): ScheduleMetadata[] {
+/**
+ * `abstract new`, not `Constructor`: reading metadata off a class never
+ * constructs it, and the service registry holds abstract ones too since a
+ * contextual binding binds against an abstract base.
+ */
+export function getScheduleMetadata(
+  target: abstract new (...args: never[]) => unknown,
+): ScheduleMetadata[] {
   const stored: ScheduleMetadata[] = Reflect.getOwnMetadata(SCHEDULE_METADATA_KEY, target) ?? []
   return [...stored]
 }

package/src/security/CookieSigner.ts

@@ -225,12 +225,22 @@ export class CookieSigner {
   }
 
   decrypt<T = string>(encrypted: string, purpose?: string): T | null {
-    const parts = encrypted.split('.')
-    if (parts.length !== 3) return null
+    // Destructured rather than indexed, and `extra` is what keeps the old
+    // length check honest: three names bind on a four-part string too, so the
+    // fourth has to be looked at to reject it.
+    const [ivPart, dataPart, tagPart, extra] = encrypted.split('.')
+    if (
+      ivPart === undefined ||
+      dataPart === undefined ||
+      tagPart === undefined ||
+      extra !== undefined
+    ) {
+      return null
+    }
     try {
-      const iv = Buffer.from(parts[0], 'base64url')
-      const data = Buffer.from(parts[1], 'base64url')
-      const tag = Buffer.from(parts[2], 'base64url')
+      const iv = Buffer.from(ivPart, 'base64url')
+      const data = Buffer.from(dataPart, 'base64url')
+      const tag = Buffer.from(tagPart, 'base64url')
       const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
       decipher.setAuthTag(tag)
       const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')

package/src/security/SignedUrl.ts

@@ -55,8 +55,9 @@ function parseExpiry(value: string | number): number {
   if (typeof value === 'number') return value
   const match = value.match(/^(\d+)(s|m|h|d)$/)
   if (!match) return 3600
-  const num = parseInt(match[1], 10)
-  switch (match[2]) {
+  const [, digits, unit] = match
+  const num = parseInt(digits ?? '0', 10)
+  switch (unit) {
     case 's':
       return num
     case 'm':

package/src/session/drivers/DatabaseDriver.ts

@@ -8,10 +8,28 @@ import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
  * app's own wrapper.
  */
 export interface SessionDbConnection {
-  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  /**
+   * Rows, as rows: `Record<string, unknown>`, not a shape the caller names.
+   *
+   * `query<T>` let this driver ASSERT what a SELECT returned — a promise the
+   * database never made and the connection cannot keep. It also made the
+   * interface unimplementable by anything but a real driver: a generic method
+   * must work for every `T`, so no fake could satisfy it, and this file's tests
+   * sat outside the typecheck because of it.
+   *
+   * The columns are read through {@link textColumn} below instead, which is
+   * what a row from a database deserves.
+   */
+  query(sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>
   execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>
 }
 
+/** A column that must be text to be usable, or `null`. */
+function textColumn(row: Record<string, unknown>, name: string): string | null {
+  const value = row[name]
+  return typeof value === 'string' ? value : null
+}
+
 export interface DatabaseDriverOptions {
   connection: SessionDbConnection
   /** Table holding the sessions. Default `sessions`. */
@@ -71,17 +89,20 @@ export class DatabaseDriver implements SessionDriverWithTagging {
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
-    const rows = await this.#db.query<{ data: string; expires_at: number | string }>(
-      `SELECT data, expires_at FROM ${this.#table} WHERE id = ?`,
-      [sessionId],
-    )
+    const rows = await this.#db.query(`SELECT data, expires_at FROM ${this.#table} WHERE id = ?`, [
+      sessionId,
+    ])
     const row = rows[0]
     if (!row) return null
     if (Number(row.expires_at) < Date.now()) {
       await this.destroy(sessionId)
       return null
     }
-    return parseData(row.data)
+    const data = textColumn(row, 'data')
+    // A row whose payload is not text is not a session — the same outcome as a
+    // row that will not parse.
+    if (data === null) return null
+    return parseData(data)
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
@@ -157,11 +178,18 @@ export class DatabaseDriver implements SessionDriverWithTagging {
 
   /** Every non-expired session this user holds — their active devices. */
   async tagged(userId: string | number): Promise<TaggedSession[]> {
-    const rows = await this.#db.query<{ id: string; data: string }>(
+    const rows = await this.#db.query(
       `SELECT id, data FROM ${this.#table} WHERE user_id = ? AND expires_at >= ?`,
       [String(userId), Date.now()],
     )
-    return rows.map((row) => ({ id: row.id, data: parseData(row.data) }))
+    const sessions: TaggedSession[] = []
+    for (const row of rows) {
+      const id = textColumn(row, 'id')
+      const data = textColumn(row, 'data')
+      if (id === null || data === null) continue
+      sessions.push({ id, data: parseData(data) })
+    }
+    return sessions
   }
 
   /** Delete every expired row — for a scheduled job, since nothing else does. */

package/src/session/drivers/RedisDriver.ts

@@ -67,11 +67,19 @@ export class RedisDriver implements SessionDriverWithTagging {
     }
     if (!this.#pending) {
       const resolver = this.#source
-      this.#pending = Promise.resolve(resolver()).then((client) => {
-        this.#resolved = client
-        this.#pending = undefined
-        return client
-      })
+      // `finally`, not the success path: clearing it only on success left a
+      // REJECTED promise in the slot, and every later call returned that same
+      // rejection. One refused connection at boot — Redis still starting, a
+      // network blip — and the driver never tried again for the life of the
+      // process. Bay and echo already clear it this way.
+      this.#pending = Promise.resolve(resolver())
+        .then((client) => {
+          this.#resolved = client
+          return client
+        })
+        .finally(() => {
+          this.#pending = undefined
+        })
     }
     return this.#pending
   }

package/src/storage/StaticMiddleware.ts

@@ -9,10 +9,13 @@
  * @implements MISS-25
  */
 
-import { createHash } from 'node:crypto'
 import * as fs from 'node:fs'
+import type { FileHandle } from 'node:fs/promises'
+import * as fsp from 'node:fs/promises'
 import * as path from 'node:path'
+import { matchesIfNoneMatch, statTag } from '../http/etag.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import { contentType } from '../http/mime.js'
 
 export interface StaticConfig {
   /** Root directory to serve files from. */
@@ -51,32 +54,6 @@ const DEFAULT_EXTENSIONS = [
   '.zip',
 ]
 
-const MIME_TYPES: Record<string, string> = {
-  '.html': 'text/html',
-  '.css': 'text/css',
-  '.js': 'application/javascript',
-  '.json': 'application/json',
-  '.xml': 'application/xml',
-  '.txt': 'text/plain',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.webp': 'image/webp',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.eot': 'application/vnd.ms-fontobject',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mp3': 'audio/mpeg',
-  '.ogg': 'audio/ogg',
-  '.pdf': 'application/pdf',
-  '.zip': 'application/zip',
-}
-
 export class StaticMiddleware {
   #root: string
   #prefix: string
@@ -95,46 +72,65 @@ export class StaticMiddleware {
       return next()
     }
 
-    const resolved = this.#resolveServableFile(ctx.request.path())
+    const resolved = await this.#openServableFile(ctx.request.path())
     if (!resolved) return next()
-    const { realFilePath, ext, stat } = resolved
-
-    const etag = createHash('md5').update(`${stat.size}-${stat.mtimeMs}`).digest('hex')
-
-    // ETag check — 304 Not Modified
-    const ifNoneMatch = ctx.request.header('if-none-match')
-    if (ifNoneMatch === etag) {
-      ctx.response.status(304)
-      return
-    }
+    const { handle, ext, stat } = resolved
 
-    const mime = MIME_TYPES[ext] ?? 'application/octet-stream'
-    ctx.response.header('Content-Type', mime)
-    ctx.response.header('Content-Length', String(stat.size))
-    ctx.response.header('Cache-Control', `public, max-age=${this.#maxAge}`)
-    ctx.response.header('ETag', etag)
-
-    if (ctx.request.method() === 'HEAD') {
+    // The handle is ours until the read stream takes it; every path that does
+    // not hand it over closes it, or the process leaks a descriptor per 304.
+    let owned = true
+    try {
+      const etag = statTag(stat)
+
+      if (matchesIfNoneMatch(ctx.request.header('if-none-match'), etag)) {
+        ctx.response.status(304)
+        return
+      }
+
+      // One table for the whole package (`src/http/mime.ts`), generated from
+      // mime-db. A second hand-written one here is how `.js` came to be
+      // served as `application/javascript` from one code path and
+      // `text/javascript` from the other.
+      ctx.response.header('Content-Type', contentType(ext) || 'application/octet-stream')
+      ctx.response.header('Content-Length', String(stat.size))
+      ctx.response.header('Cache-Control', `public, max-age=${this.#maxAge}`)
+      ctx.response.header('ETag', etag)
+
+      if (ctx.request.method() === 'HEAD') {
+        ctx.response.status(200)
+        return
+      }
+
+      // Streamed, not read whole.
+      //
+      // `readFileSync` stalled the event loop for EVERY concurrent request
+      // while one client asked for a file, and the allowed extensions include
+      // `.mp4`, `.zip` and `.pdf` — so one large asset became every other
+      // request's latency, and each request allocated the file again. The
+      // stream applies backpressure and holds one chunk at a time.
+      //
+      // The read stream owns the handle from here and closes it at end.
       ctx.response.status(200)
-      return
+      owned = false
+      await ctx.response.stream(handle.createReadStream())
+    } finally {
+      if (owned) await handle.close().catch(() => {})
     }
-
-    // Send the raw Buffer — `content.toString()` would interpret PNG /
-    // PDF / ZIP bytes as UTF-8 and replace any byte the encoding can't
-    // round-trip (anything in the surrogate range, plus invalid
-    // sequences) with U+FFFD.
-    const content = fs.readFileSync(realFilePath)
-    ctx.response.status(200).sendBuffer(content)
   }
 
   /**
-   * Resolve a request path to a real, in-root, existing file, or `null` when it
-   * is not servable (wrong prefix/extension, outside the root, missing, or a
-   * symlink escaping the root). Returning `null` tells `handle` to call `next()`.
+   * Open a request path as a real, in-root, regular file, or answer `null`
+   * when it is not servable (wrong prefix/extension, outside the root,
+   * missing, or a symlink escaping the root). `null` tells `handle` to call
+   * `next()`.
+   *
+   * The file is OPENED here rather than merely checked, and its metadata read
+   * from the descriptor: what gets served is then the same file that passed
+   * the checks, which a path re-read after the fact cannot promise.
    */
-  #resolveServableFile(
+  async #openServableFile(
     reqPath: string,
-  ): { realFilePath: string; ext: string; stat: fs.Stats } | null {
+  ): Promise<{ handle: FileHandle; ext: string; stat: fs.Stats } | null> {
     // Match only when the prefix is followed by `/` or end-of-path —
     // otherwise `/staticx/foo.js` would be intercepted when the configured
     // prefix is `/static`, hijacking unrelated routes.
@@ -152,7 +148,7 @@ export class StaticMiddleware {
     // Two containment checks. The first uses `path.sep` to reject sibling
     // directories with a shared prefix (`/var/www-static-secret` slipping
     // past a guard for `/var/www-static`). The second resolves symlinks
-    // via realpathSync so a symlink planted inside the root cannot point
+    // via realpath so a symlink planted inside the root cannot point
     // outside it. We do realpath AFTER the lexical check so a non-existent
     // path returns `next()` rather than throwing.
     const rootWithSep = this.#root.endsWith(path.sep) ? this.#root : this.#root + path.sep
@@ -160,15 +156,11 @@ export class StaticMiddleware {
       return null
     }
 
-    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
-      return null
-    }
-
     let realFilePath: string
     let realRoot: string
     try {
-      realFilePath = fs.realpathSync(filePath)
-      realRoot = fs.realpathSync(this.#root)
+      realFilePath = await fsp.realpath(filePath)
+      realRoot = await fsp.realpath(this.#root)
     } catch {
       return null
     }
@@ -177,6 +169,29 @@ export class StaticMiddleware {
       return null
     }
 
-    return { realFilePath, ext, stat: fs.statSync(realFilePath) }
+    // O_NOFOLLOW closes the window the checks above leave open: between
+    // `realpath` and the read, the last path component can be replaced by a
+    // symlink pointing anywhere, and a read by name follows it. Refusing to
+    // follow a link at open time makes that swap fail the open instead of
+    // serving a file outside the root. A parent directory swapped in the same
+    // window is not covered — that needs openat(), which Node does not expose.
+    let handle: FileHandle
+    try {
+      handle = await fsp.open(realFilePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+    } catch {
+      return null
+    }
+
+    try {
+      const stat = await handle.stat()
+      if (!stat.isFile()) {
+        await handle.close()
+        return null
+      }
+      return { handle, ext, stat }
+    } catch {
+      await handle.close().catch(() => {})
+      return null
+    }
   }
 }

package/src/testing/ApiResponse.ts

@@ -149,15 +149,14 @@ function parseMultipartResponse(
     // Trim the trailing CRLF before the next boundary.
     let content = part.subarray(headerEnd + 4)
     if (content.subarray(-2).toString('binary') === '\r\n') content = content.subarray(0, -2)
-    const nameMatch = headerText.match(/name="([^"]*)"/i)
-    if (!nameMatch) continue
-    const name = nameMatch[1]
-    const fileMatch = headerText.match(/filename="([^"]*)"/i)
-    if (fileMatch) {
+    const [, name] = headerText.match(/name="([^"]*)"/i) ?? []
+    if (name === undefined) continue
+    const [, filename] = headerText.match(/filename="([^"]*)"/i) ?? []
+    if (filename !== undefined) {
       const typeMatch = headerText.match(/content-type:\s*([^\r\n]+)/i)
       files[name] = {
         fieldName: name,
-        filename: fileMatch[1],
+        filename,
         type: typeMatch?.[1]?.trim() ?? 'application/octet-stream',
         size: content.length,
         content,
@@ -355,8 +354,8 @@ export class ApiResponse {
   /** Charset from `Content-Type`, if any — helix `charset()`. */
   charset(): string | undefined {
     const ct = this.#raw.headers['content-type'] ?? ''
-    const m = ct.match(/charset=([^;]+)/i)
-    return m ? m[1].trim() : undefined
+    const [, charset] = ct.match(/charset=([^;]+)/i) ?? []
+    return charset?.trim()
   }
 
   /** All response cookies, parsed from `Set-Cookie` — helix `cookies()`. */
@@ -380,8 +379,8 @@ export class ApiResponse {
     if (!link) return {}
     const out: Record<string, string> = {}
     for (const part of link.split(',')) {
-      const m = part.match(/<([^>]+)>\s*;\s*rel="?([^";]+)"?/)
-      if (m) out[m[2]] = m[1]
+      const [, url, rel] = part.match(/<([^>]+)>\s*;\s*rel="?([^";]+)"?/) ?? []
+      if (url !== undefined && rel !== undefined) out[rel] = url
     }
     return out
   }