@nifrajs/middleware 3.3.0 → 4.0.0

package/src/cors.ts

@@ -1,5 +1,8 @@
 import { withResponseObserver } from "@nifrajs/core/response-observer"
-import type { Middleware } from "@nifrajs/core/server"
+import type { Middleware, NodeRequestContext, NodeResponseContext } from "@nifrajs/core/server"
+import { setNodeHeader } from "./_utils.ts"
+
+const BUN_NATIVE_REQUEST_SAFE = Symbol.for("@nifrajs/core/bun-native-request-safe")
 
 export interface CorsOptions {
   /** Allowed origin(s): `"*"`, an exact origin, a list, or a predicate. Default `"*"`. */
@@ -38,6 +41,31 @@ function resolveAllowOrigin(
   return option === requestOrigin ? requestOrigin : null
 }
 
+function nodeHeader(
+  headers: Readonly<Record<string, string | readonly string[]>> | undefined,
+  name: string,
+  headersAreLowercase: boolean | undefined,
+): string | null {
+  if (headers === undefined) return null
+  const direct = headers[name]
+  if (direct !== undefined) return typeof direct === "string" ? direct : direct.join(", ")
+  if (headersAreLowercase) return null
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== name) continue
+    const value = headers[key]
+    return value === undefined ? null : typeof value === "string" ? value : value.join(", ")
+  }
+  return null
+}
+
+function varyOnOrigin(value: string | null): string {
+  if (value === null || value.trim() === "") return "Origin"
+  const fields = value.split(",").map((field) => field.trim())
+  // `Vary: *` is the complete field value, not one member of a list.
+  if (fields.includes("*")) return "*"
+  return fields.some((field) => field.toLowerCase() === "origin") ? value : `${value}, Origin`
+}
+
 /**
  * CORS as a {@link Middleware}. Preflight (`OPTIONS` + `Access-Control-Request-Method`)
  * short-circuits to `204` via `onRequest`; the origin/credentials headers are added in
@@ -59,7 +87,7 @@ export function cors(options: CorsOptions = {}): Middleware {
   const exposedHeaders = options.exposedHeaders?.join(", ")
   const maxAge = options.maxAge
 
-  return withResponseObserver({
+  const middleware = withResponseObserver({
     name: "cors",
     onRequest(req) {
       const isPreflight =
@@ -86,15 +114,31 @@ export function cors(options: CorsOptions = {}): Middleware {
       return new Response(null, { status: 204, headers })
     },
     onResponseHeaders(headers, req) {
+      // Any policy other than `*` makes the answer depend on the request's Origin - including the
+      // answer that omits Allow-Origin. Without `Vary` on that one, a shared cache stores the
+      // header-less response and replays it to an allowed origin, breaking CORS for everyone.
+      if (origin !== "*") {
+        headers.set("vary", varyOnOrigin(headers.get("vary")))
+      }
       const allowOrigin = resolveAllowOrigin(origin, req.header("origin"))
       if (allowOrigin === null) return
       headers.set("access-control-allow-origin", allowOrigin)
-      if (allowOrigin !== "*") {
-        const vary = headers.get("vary")
-        headers.set("vary", vary === null || vary === "" ? "Origin" : `${vary}, Origin`)
-      }
       if (credentials) headers.set("access-control-allow-credentials", "true")
       if (exposedHeaders !== undefined) headers.set("access-control-expose-headers", exposedHeaders)
     },
-  })
+    onNodeResponseHeaders(response: NodeResponseContext, req: NodeRequestContext) {
+      if (origin !== "*") {
+        const vary = nodeHeader(response.headers, "vary", response.headersAreLowercase)
+        setNodeHeader(response, "vary", varyOnOrigin(vary))
+      }
+      const allowOrigin = resolveAllowOrigin(origin, req.header("origin"))
+      if (allowOrigin === null) return
+      setNodeHeader(response, "access-control-allow-origin", allowOrigin)
+      if (credentials) setNodeHeader(response, "access-control-allow-credentials", "true")
+      if (exposedHeaders !== undefined)
+        setNodeHeader(response, "access-control-expose-headers", exposedHeaders)
+    },
+  } satisfies Middleware)
+  Object.defineProperty(middleware, BUN_NATIVE_REQUEST_SAFE, { value: true })
+  return middleware
 }

package/src/csrf.ts

@@ -1,7 +1,8 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { METHODS, type Middleware } from "@nifrajs/core/server"
+import { isSameOriginRequest, METHODS, type Middleware } from "@nifrajs/core/server"
 import {
   base64UrlEncode,
+  guardName,
   hmacSha256,
   jsonError,
   parseCookies,
@@ -35,9 +36,27 @@ export interface CsrfOptions {
   readonly cookie?: string
   /** Header carrying the same signed token. Default `"x-csrf-token"`. */
   readonly header?: string
+  /**
+   * Form field that may carry the token when the header is absent, so a plain HTML `<form>` (no
+   * script to set a header) can submit - e.g. `field: "_csrf"` with
+   * `<input type="hidden" name="_csrf" value="...">`. Read from `application/x-www-form-urlencoded`
+   * and `multipart/form-data` bodies only, through a clone, so the handler still reads the body.
+   * Unset (default), only the header is accepted.
+   *
+   * A cross-site form can set any field but never a custom header, so keep `checkOrigin` on with a
+   * field: the Origin check is what stops a site that can plant a cookie on your domain (a sibling
+   * subdomain) from pairing it with a matching field.
+   */
+  readonly field?: string
+  /**
+   * Largest body scanned for {@link field}, in bytes. Default 64 KiB. A bigger form (a file upload)
+   * fails closed - send the header, or raise this for that app.
+   */
+  readonly fieldMaxBytes?: number
   /** Unsafe methods to protect. Default: every method except GET/HEAD/OPTIONS/TRACE. */
   readonly methods?: readonly string[]
-  /** Allowed request origins. Default: same-origin derived from the request URL. */
+  /** Allowed request origins. Default: same host as the request URL, where an `https:` Origin may
+   * reach an `http:` URL (what a TLS-terminating proxy looks like from the server). */
   readonly origins?: readonly string[]
   /** Check Origin/Referer on protected requests. Default true. */
   readonly checkOrigin?: boolean
@@ -49,20 +68,95 @@ function protectedMethod(method: string, configured: Set<string> | undefined): b
   return configured !== undefined ? configured.has(method) : !SAFE_METHODS.has(method)
 }
 
+/**
+ * An explicit allowlist compares exact origins. The same-origin default goes through core's
+ * {@link isSameOriginRequest} instead of comparing against `new URL(req.url).origin`: behind a
+ * TLS-terminating proxy the request URL says `http:` while the browser reports `https:`, and an exact
+ * compare rejected every protected request there.
+ */
 function originAllowed(req: Request, origins: Set<string> | undefined): boolean {
-  const allowed = origins ?? new Set([new URL(req.url).origin])
+  const allows = (candidate: string): boolean =>
+    origins !== undefined ? origins.has(candidate) : isSameOriginRequest(candidate, req)
   const origin = req.headers.get("origin")
-  if (origin !== null) return allowed.has(origin)
+  if (origin !== null) return allows(origin)
 
   const referer = req.headers.get("referer")
   if (referer === null) return false
   try {
-    return allowed.has(new URL(referer).origin)
+    return allows(new URL(referer).origin)
   } catch {
     return false
   }
 }
 
+function mediaEssence(contentType: string): string {
+  const semi = contentType.indexOf(";")
+  return (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase()
+}
+
+/** Up to `maxBytes` of a request clone, or `null` when it is longer (or fails mid-read). */
+async function readAtMost(req: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer> | null> {
+  const body = req.clone().body
+  if (body === null) return null
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > maxBytes) {
+        // A clone tees the request: cancel both branches on terminal rejection, without waiting
+        // for the unread branch or an upstream cleanup promise that may never settle.
+        void Promise.allSettled([reader.cancel(), req.body?.cancel()])
+        return null
+      }
+      chunks.push(value)
+    }
+  } catch {
+    return null
+  } finally {
+    reader.releaseLock()
+  }
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+/**
+ * The token a form body carries in `field`, read from a clone so the handler keeps the original body.
+ * Anything unexpected - another media type, an oversized or unreadable body, a file part under the
+ * field's name - yields `null`, which the caller treats as a missing token.
+ */
+async function formFieldToken(
+  req: Request,
+  field: string,
+  maxBytes: number,
+): Promise<string | null> {
+  if (req.body === null) return null
+  const contentType = req.headers.get("content-type") ?? ""
+  const essence = mediaEssence(contentType)
+  const urlencoded = essence === "application/x-www-form-urlencoded"
+  if (!urlencoded && essence !== "multipart/form-data") return null
+  const declared = req.headers.get("content-length")
+  if (declared !== null && !(Number(declared) <= maxBytes)) return null
+  const bytes = await readAtMost(req, maxBytes)
+  if (bytes === null) return null
+  try {
+    if (urlencoded) return new URLSearchParams(new TextDecoder().decode(bytes)).get(field)
+    const form = await new Response(bytes, { headers: { "content-type": contentType } }).formData()
+    const value = form.get(field)
+    return typeof value === "string" ? value : null
+  } catch {
+    return null
+  }
+}
+
 export async function createCsrfToken(secret: CsrfSecret, nonce?: string): Promise<string> {
   const key = csrfKeys(secret)[0] as Uint8Array
   const tokenNonce = nonce ?? base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)))
@@ -93,27 +187,38 @@ export async function verifyCsrfToken(token: string, secret: CsrfSecret): Promis
 
 /**
  * Signed double-submit CSRF protection. A protected request must carry the same signed token in a
- * cookie and a header, and must come from an allowed Origin/Referer unless `checkOrigin:false` is set.
+ * cookie and in a header (or, for a plain HTML form, the {@link CsrfOptions.field} form field), and
+ * must come from an allowed Origin/Referer unless `checkOrigin:false` is set.
  */
 export function csrf(options: CsrfOptions): Middleware {
   const keys = csrfKeys(options.secret)
   const cookie = options.cookie ?? "csrf-token"
   const header = (options.header ?? "x-csrf-token").toLowerCase()
+  const field = options.field
+  if (field !== undefined && field.trim() === "") throw new Error("csrf: field must not be empty")
+  const fieldMaxBytes = options.fieldMaxBytes ?? 64 * 1024
+  if (!Number.isInteger(fieldMaxBytes) || fieldMaxBytes < 1) {
+    throw new Error("csrf: fieldMaxBytes must be a positive integer")
+  }
   const methods =
     options.methods !== undefined ? new Set(options.methods.map((m) => m.toUpperCase())) : undefined
   const origins = options.origins !== undefined ? new Set(options.origins) : undefined
   const checkOrigin = options.checkOrigin !== false
 
   const middleware: Middleware = {
-    name: "csrf",
+    name: guardName("csrf"),
     async onRequest(req) {
       if (!protectedMethod(req.method, methods)) return undefined
       if (checkOrigin && !originAllowed(req, origins)) return jsonError(403, "csrf_failed")
 
       const cookieToken = parseCookies(req.headers.get("cookie"))[cookie]
-      const headerToken = req.headers.get(header)
-      if (cookieToken === undefined || headerToken === null) return jsonError(403, "csrf_failed")
-      if (!(await timingSafeEqualString(cookieToken, headerToken))) {
+      if (cookieToken === undefined) return jsonError(403, "csrf_failed")
+      // The header wins; the body is only read (from a clone) when a form had no way to set one.
+      const requestToken =
+        req.headers.get(header) ??
+        (field === undefined ? null : await formFieldToken(req, field, fieldMaxBytes))
+      if (requestToken === null) return jsonError(403, "csrf_failed")
+      if (!(await timingSafeEqualString(cookieToken, requestToken))) {
         return jsonError(403, "csrf_failed")
       }
       return (await verifyCsrfToken(cookieToken, keys)) ? undefined : jsonError(403, "csrf_failed")

package/src/etag.ts

@@ -137,6 +137,16 @@ export function etag(options: ETagOptions = {}) {
           if (req.method !== "GET" || response.status !== 200 || response.body === null) {
             return response
           }
+          // Hashing reads the body before any of it is sent. A stream meant to arrive as it is
+          // produced - an event stream, or one marked no-store or no-transform - passes through.
+          if (
+            /^text\/event-stream\b/i.test(response.headers.get("content-type") ?? "") ||
+            /(?:^|,)\s*(?:no-store|no-transform)\s*(?:,|$)/i.test(
+              response.headers.get("cache-control") ?? "",
+            )
+          ) {
+            return response
+          }
           const declared = response.headers.get("content-length")
           if (
             declared !== null &&
@@ -173,7 +183,7 @@ async function etagRawResponse(
   // The body was consumed and rebuilt from bytes. Re-derive framing at the serving adapter
   // instead of trusting a stale upstream declaration.
   headers.delete("content-length")
-  return new Response(read.bytes, {
+  return new Response(read.bytes.slice(), {
     status: response.status,
     statusText: response.statusText,
     headers,

package/src/idempotency.ts

@@ -1,5 +1,5 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { METHODS, type Middleware } from "@nifrajs/core/server"
+import { METHODS, type Middleware, replacedRequestOf } from "@nifrajs/core/server"
 
 /**
  * Idempotency keys for unsafe requests - a client retrying a `POST` (dropped connection, impatient
@@ -22,7 +22,7 @@ export interface IdempotencyRecord {
 }
 
 export type IdempotencyClaim =
-  | { readonly state: "new" }
+  | { readonly state: "new"; readonly reservation: string }
   | { readonly state: "in_flight" }
   | { readonly state: "replay"; readonly record: IdempotencyRecord }
 
@@ -38,10 +38,15 @@ export interface IdempotencyStore {
    * The in-flight lock expires after `lockTtlMs` so a crashed handler can't wedge the key forever.
    */
   begin(key: string, lockTtlMs: number): Promise<IdempotencyClaim>
-  /** Store the completed response and release the lock (kept for `ttlMs`). */
-  complete(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>
-  /** Release the lock without storing (handler errored / response not cacheable). */
-  release(key: string): Promise<void>
+  /** Store the completed response only when `reservation` still owns the lock (kept for `ttlMs`). */
+  complete(
+    key: string,
+    reservation: string,
+    record: IdempotencyRecord,
+    ttlMs: number,
+  ): Promise<boolean>
+  /** Release only the lock owned by `reservation` (handler errored / response not cacheable). */
+  release(key: string, reservation: string): Promise<boolean>
 }
 
 export interface MemoryIdempotencyStoreOptions {
@@ -54,7 +59,7 @@ export interface MemoryIdempotencyStoreOptions {
 }
 
 type Entry =
-  | { readonly kind: "lock"; readonly expiresAt: number }
+  | { readonly kind: "lock"; readonly reservation: string; readonly expiresAt: number }
   | { readonly kind: "record"; readonly record: IdempotencyRecord; readonly expiresAt: number }
 
 const KEY_ENCODER = new TextEncoder()
@@ -137,21 +142,38 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       )
     }
     // Free (or expired): take the lock. Synchronous Map write ⇒ atomic on a single instance.
-    this.reserve(key, { kind: "lock", expiresAt: now + lockTtlMs })
-    return Promise.resolve({ state: "new" })
+    const reservation = crypto.randomUUID()
+    this.reserve(key, { kind: "lock", reservation, expiresAt: now + lockTtlMs })
+    return Promise.resolve({ state: "new", reservation })
   }
 
-  complete(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void> {
+  complete(
+    key: string,
+    reservation: string,
+    record: IdempotencyRecord,
+    ttlMs: number,
+  ): Promise<boolean> {
     this.validateKey(key)
     assertPositiveTtl(ttlMs, "ttlMs")
-    this.reserve(key, { kind: "record", record, expiresAt: Date.now() + ttlMs })
-    return Promise.resolve()
+    const entry = this.entries.get(key)
+    if (entry === undefined || entry.kind !== "lock" || entry.reservation !== reservation) {
+      return Promise.resolve(false)
+    }
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key)
+      return Promise.resolve(false)
+    }
+    this.entries.set(key, { kind: "record", record, expiresAt: Date.now() + ttlMs })
+    return Promise.resolve(true)
   }
 
-  release(key: string): Promise<void> {
+  release(key: string, reservation: string): Promise<boolean> {
     const entry = this.entries.get(key)
-    if (entry !== undefined && entry.kind === "lock") this.entries.delete(key)
-    return Promise.resolve()
+    if (entry === undefined || entry.kind !== "lock" || entry.reservation !== reservation) {
+      return Promise.resolve(false)
+    }
+    this.entries.delete(key)
+    return Promise.resolve(true)
   }
 }
 
@@ -168,7 +190,11 @@ export interface IdempotencyOptions {
   readonly lockTtlMs?: number
   /** Max response bytes to cache. A larger response is returned but **not** stored. Default 1 MiB. */
   readonly maxBytes?: number
-  /** Whether a response should be cached for replay. Default: status `< 500` (don't replay transient 5xx). */
+  /**
+   * Whether a response should be cached for replay. Default: any status below 500 except 401, 403,
+   * 408, 409, 425, and 429. Those, like a transient 5xx, say the operation did not run; replaying one
+   * would refuse every retry under that key until it expired.
+   */
   readonly shouldCache?: (response: Response) => boolean
   /**
    * Derive the store key from the request. Default: the `header` value scoped by method + path **and
@@ -197,6 +223,7 @@ export interface IdempotencyOptions {
 }
 
 const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const
+const NOT_THE_OPERATIONS_ANSWER = new Set([401, 403, 408, 409, 425, 429])
 const DAY_MS = 24 * 60 * 60 * 1000
 
 function assertPositiveTtl(value: number, name: string): void {
@@ -250,7 +277,8 @@ function responseWithBody(
   res: Response,
   body: Uint8Array | ReadableStream<Uint8Array> | null,
 ): Response {
-  return new Response(body, {
+  const safeBody = body instanceof Uint8Array ? body.slice() : body
+  return new Response(safeBody, {
     status: res.status,
     statusText: res.statusText,
     headers: res.headers,
@@ -332,7 +360,8 @@ async function captureBody(
 function replay(record: IdempotencyRecord): Response {
   const headers = new Headers(record.headers as Array<[string, string]>)
   headers.set("idempotent-replayed", "true")
-  return new Response(bodyFor(fromBase64(record.body)), { status: record.status, headers })
+  const body = bodyFor(fromBase64(record.body))
+  return new Response(body === null ? null : body.slice(), { status: record.status, headers })
 }
 
 const DEFAULT_PRINCIPAL_HEADERS = ["authorization", "cookie", "x-api-key"] as const
@@ -381,6 +410,10 @@ function defaultIdempotencyKey(
  * session-specific, so replaying it to a different caller (key collision or abuse) would leak/fixate a
  * session. Cache the body + status + the rest of the headers; let auth cookies re-issue per request.
  *
+ * The key is not bound to the request body: a key reused with a different body replays the first
+ * answer. A route that needs that check declares `schema.idempotency`, which fingerprints the request
+ * and refuses a mismatched reuse with 409.
+ *
  * Caching buffers the response body, so apply this to JSON/API routes, not streaming SSR responses.
  */
 export function idempotency(options: IdempotencyOptions): Middleware {
@@ -395,7 +428,9 @@ export function idempotency(options: IdempotencyOptions): Middleware {
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
     throw new Error("idempotency: maxBytes must be a non-negative integer")
   }
-  const shouldCache = options.shouldCache ?? ((res: Response) => res.status < 500)
+  const shouldCache =
+    options.shouldCache ??
+    ((res: Response) => res.status < 500 && !NOT_THE_OPERATIONS_ANSWER.has(res.status))
   const principalHeaders = (options.principalHeaders ?? DEFAULT_PRINCIPAL_HEADERS).map((name) =>
     name.toLowerCase(),
   )
@@ -405,7 +440,7 @@ export function idempotency(options: IdempotencyOptions): Middleware {
       ? (req: Request): Promise<string | null> | null =>
           defaultIdempotencyKey(req, header, principalHeaders)
       : (req: Request): string | null | Promise<string | null> => custom(req, header)
-  const claimed = new WeakMap<Request, string>()
+  const claimed = new WeakMap<Request, { readonly key: string; readonly reservation: string }>()
 
   const middleware: Middleware = {
     name: "idempotency",
@@ -436,15 +471,23 @@ export function idempotency(options: IdempotencyOptions): Middleware {
           },
         })
       }
-      claimed.set(req, key)
+      if (claim.state !== "new") return undefined
+      claimed.set(req, { key, reservation: claim.reservation })
       return undefined
     },
     async onResponse(res, req) {
-      const key = claimed.get(req)
-      if (key === undefined) return res // not a claimed request (safe method / no key / a replay)
-      claimed.delete(req)
+      // A later onRequest hook (methodOverride, a transport codec) may have replaced the request
+      // this one claimed; walk back to it.
+      let claimedReq: Request | undefined = req
+      let claim = claimed.get(req)
+      while (claim === undefined && claimedReq !== undefined) {
+        claimedReq = replacedRequestOf(claimedReq)
+        if (claimedReq !== undefined) claim = claimed.get(claimedReq)
+      }
+      if (claim === undefined || claimedReq === undefined) return res // not a claimed request
+      claimed.delete(claimedReq)
       if (!shouldCache(res)) {
-        await store.release(key)
+        await store.release(claim.key, claim.reservation)
         return res
       }
       // Buffer the body (consumes `res`), so a fresh Response is returned in its place.
@@ -452,16 +495,21 @@ export function idempotency(options: IdempotencyOptions): Middleware {
       try {
         captured = await captureBody(res, maxBytes)
       } catch (err) {
-        await store.release(key)
+        await store.release(claim.key, claim.reservation)
         throw err
       }
       if (!("bytes" in captured)) {
-        await store.release(key) // too large to store - return it, but don't cache
+        await store.release(claim.key, claim.reservation) // too large to store - return it, but don't cache
         return captured.response
       }
       const bytes = captured.bytes
       const headers = [...captured.response.headers].filter(([name]) => name !== "set-cookie")
-      await store.complete(key, { status: res.status, headers, body: toBase64(bytes) }, ttlMs)
+      await store.complete(
+        claim.key,
+        claim.reservation,
+        { status: res.status, headers, body: toBase64(bytes) },
+        ttlMs,
+      )
       return captured.response
     },
   }