@nifrajs/middleware 0.1.0-alpha.1

package/src/cache-control.ts

@@ -0,0 +1,45 @@
+import { definePlugin } from "@nifrajs/core"
+
+export interface CacheControlOptions {
+  /** Methods whose responses get the header. Default `["GET", "HEAD"]`. */
+  readonly methods?: readonly string[]
+  /** Predicate over the response status. Default: 2xx only. */
+  readonly status?: (status: number) => boolean
+  /** When `true` (default), don't overwrite a `Cache-Control` the handler already set. */
+  readonly respectExisting?: boolean
+}
+
+/**
+ * Set a `Cache-Control` header on matching responses. `value` is either a fixed directive string or a
+ * function of the request (return `undefined` to leave a response untouched — e.g. cache by path).
+ * Defaults to `GET`/`HEAD` + 2xx, and never clobbers a `Cache-Control` the handler set itself.
+ *
+ * ```ts
+ * app.use(cacheControl("public, max-age=3600, stale-while-revalidate=60"))
+ * // or per-path:
+ * app.use(cacheControl((req) =>
+ *   new URL(req.url).pathname.startsWith("/assets/") ? "public, max-age=31536000, immutable" : undefined,
+ * ))
+ * ```
+ */
+export function cacheControl(
+  value: string | ((request: Request) => string | undefined),
+  options: CacheControlOptions = {},
+) {
+  const methods = new Set((options.methods ?? ["GET", "HEAD"]).map((m) => m.toUpperCase()))
+  const statusOk = options.status ?? ((status: number) => status >= 200 && status < 300)
+  const respectExisting = options.respectExisting !== false
+  const resolve = typeof value === "function" ? value : () => value
+  return definePlugin("cacheControl", (app) =>
+    app.onResponse((res, req) => {
+      if (!methods.has(req.method)) return res
+      if (!statusOk(res.status)) return res
+      if (respectExisting && res.headers.has("cache-control")) return res
+      const directive = resolve(req)
+      if (directive === undefined) return res
+      const headers = new Headers(res.headers)
+      headers.set("cache-control", directive)
+      return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+    }),
+  )
+}

package/src/cache.ts

@@ -0,0 +1,277 @@
+import type { Middleware } from "@nifrajs/core"
+import type { MaybePromise } from "./_utils.ts"
+
+export interface CachedResponse {
+  readonly status: number
+  readonly statusText: string
+  readonly headers: readonly [string, string][]
+  readonly body: Uint8Array
+  readonly expiresAt: number
+  readonly storedAt: number
+}
+
+export interface ResponseCacheStore {
+  get(key: string): MaybePromise<CachedResponse | undefined>
+  set(key: string, response: CachedResponse): MaybePromise<void>
+  delete?(key: string): MaybePromise<void>
+}
+
+export interface MemoryResponseCacheOptions {
+  /** Maximum entries retained. Default `1000`. Oldest entries are evicted first. */
+  readonly maxEntries?: number
+  /** Allow in-process cache in production. Off by default because it is per-instance. */
+  readonly allowInProduction?: boolean
+}
+
+export class MemoryResponseCache implements ResponseCacheStore {
+  private readonly entries = new Map<string, CachedResponse>()
+  private readonly maxEntries: number
+
+  constructor(options: MemoryResponseCacheOptions = {}) {
+    const env = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV
+    if (options.allowInProduction !== true && env === "production") {
+      throw new Error(
+        "MemoryResponseCache is per-instance and unsafe in production. Use a shared cache store, " +
+          "or pass { allowInProduction: true } for a single-instance deploy.",
+      )
+    }
+    this.maxEntries = options.maxEntries ?? 1000
+    if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
+      throw new Error("MemoryResponseCache: maxEntries must be a positive integer")
+    }
+  }
+
+  get(key: string): CachedResponse | undefined {
+    const entry = this.entries.get(key)
+    if (entry === undefined) return undefined
+    if (Date.now() >= entry.expiresAt) {
+      this.entries.delete(key)
+      return undefined
+    }
+    return entry
+  }
+
+  set(key: string, response: CachedResponse): void {
+    if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next().value
+      if (oldest !== undefined) this.entries.delete(oldest)
+    }
+    this.entries.set(key, response)
+  }
+
+  delete(key: string): void {
+    this.entries.delete(key)
+  }
+}
+
+export interface CacheOptions {
+  readonly store: ResponseCacheStore
+  /** Time to live in milliseconds. */
+  readonly ttlMs: number
+  /** Methods cached. Default `["GET", "HEAD"]`. */
+  readonly methods?: readonly string[]
+  /** Status predicate. Default: `200` only. */
+  readonly status?: (status: number) => boolean
+  /** Header names included in the cache key and emitted in `Vary`. */
+  readonly vary?: readonly string[]
+  /** Custom cache key. Receives the normalized `vary` headers through the request itself. */
+  readonly key?: (request: Request) => string
+  /** Maximum response bytes to store. Default `1_000_000`. Larger responses pass through. */
+  readonly maxBytes?: number
+  /** Respect request `Cache-Control: no-cache/no-store`. Default `true`. */
+  readonly respectRequestCacheControl?: boolean
+  /** Respect response `Cache-Control: private/no-store`. Default `true`. */
+  readonly respectResponseCacheControl?: boolean
+  /** Cache responses with `Set-Cookie`. Default `false`. */
+  readonly cacheSetCookie?: boolean
+  /** Response header for cache status. Default `"x-nifra-cache"`; set `false` to disable. */
+  readonly cacheStatusHeader?: string | false
+}
+
+function parseLength(value: string | null): number | undefined {
+  if (value === null) return undefined
+  if (!/^(?:0|[1-9]\d*)$/.test(value)) return undefined
+  return Number(value)
+}
+
+function cacheControlHas(headers: Headers, names: readonly string[]): boolean {
+  const value = headers.get("cache-control")
+  if (value === null) return false
+  const parts = value
+    .toLowerCase()
+    .split(",")
+    .map((part) => part.trim().split("=", 1)[0])
+  return names.some((name) => parts.includes(name))
+}
+
+function appendVary(headers: Headers, vary: readonly string[]): void {
+  if (vary.length === 0) return
+  const existing = headers
+    .get("vary")
+    ?.split(",")
+    .map((v) => v.trim().toLowerCase())
+  const seen = new Set(existing ?? [])
+  const additions: string[] = []
+  for (const header of vary) {
+    const normalized = header.toLowerCase()
+    if (!seen.has(normalized)) {
+      seen.add(normalized)
+      additions.push(header)
+    }
+  }
+  if (additions.length === 0) return
+  const current = headers.get("vary")
+  headers.set(
+    "vary",
+    current === null ? additions.join(", ") : `${current}, ${additions.join(", ")}`,
+  )
+}
+
+function defaultKey(req: Request, vary: readonly string[]): string {
+  let key = `${req.method.toUpperCase()} ${req.url}`
+  for (const header of vary) key += `\n${header.toLowerCase()}:${req.headers.get(header) ?? ""}`
+  return key
+}
+
+async function readBytesCapped(res: Response, maxBytes: number): Promise<Uint8Array | null> {
+  const body = res.clone().body
+  if (body === null) return new Uint8Array()
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {
+        const out = new Uint8Array(total)
+        let offset = 0
+        for (const chunk of chunks) {
+          out.set(chunk, offset)
+          offset += chunk.byteLength
+        }
+        return out
+      }
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+  } catch {
+    return null
+  }
+}
+
+function withStatusHeader(
+  res: Response,
+  header: string | false,
+  status: "HIT" | "MISS" | "BYPASS",
+): Response {
+  if (header === false) return res
+  const headers = new Headers(res.headers)
+  headers.set(header, status)
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+}
+
+/**
+ * Full response cache for small, cacheable responses. Use a shared `store` in production. The
+ * middleware honors `Cache-Control` by default, avoids `Set-Cookie`, caps stored bytes, emits `Age`,
+ * and keeps `Vary` headers aligned with the cache key.
+ */
+export function cache(options: CacheOptions): Middleware {
+  const { store } = options
+  const ttlMs = options.ttlMs
+  if (!Number.isInteger(ttlMs) || ttlMs < 1)
+    throw new Error("cache: ttlMs must be a positive integer")
+  const methods = new Set((options.methods ?? ["GET", "HEAD"]).map((m) => m.toUpperCase()))
+  const statusOk = options.status ?? ((status: number) => status === 200)
+  const vary = options.vary ?? []
+  const keyOf = options.key ?? ((req: Request) => defaultKey(req, vary))
+  const maxBytes = options.maxBytes ?? 1_000_000
+  if (!Number.isInteger(maxBytes) || maxBytes < 0) {
+    throw new Error("cache: maxBytes must be a non-negative integer")
+  }
+  const respectRequestCacheControl = options.respectRequestCacheControl !== false
+  const respectResponseCacheControl = options.respectResponseCacheControl !== false
+  const cacheSetCookie = options.cacheSetCookie === true
+  const cacheStatusHeader =
+    options.cacheStatusHeader === undefined ? "x-nifra-cache" : options.cacheStatusHeader
+  if (cacheStatusHeader !== false && cacheStatusHeader.trim() === "") {
+    throw new Error("cache: cacheStatusHeader is empty")
+  }
+  const hits = new WeakSet<Request>()
+
+  return {
+    name: "cache",
+    async onRequest(req) {
+      if (!methods.has(req.method.toUpperCase())) return undefined
+      if (respectRequestCacheControl && cacheControlHas(req.headers, ["no-cache", "no-store"])) {
+        return undefined
+      }
+      const key = keyOf(req)
+      const entry = await store.get(key)
+      if (entry === undefined) return undefined
+      if (Date.now() >= entry.expiresAt) {
+        await store.delete?.(key)
+        return undefined
+      }
+      hits.add(req)
+      const headers = new Headers([...entry.headers])
+      headers.set("age", String(Math.max(0, Math.floor((Date.now() - entry.storedAt) / 1000))))
+      if (cacheStatusHeader !== false) headers.set(cacheStatusHeader, "HIT")
+      return new Response(req.method === "HEAD" ? null : entry.body.slice(), {
+        status: entry.status,
+        statusText: entry.statusText,
+        headers,
+      })
+    },
+    async onResponse(res, req) {
+      if (hits.has(req)) {
+        hits.delete(req)
+        return res
+      }
+      if (!methods.has(req.method.toUpperCase())) return res
+      if (!statusOk(res.status)) return res
+      if (respectRequestCacheControl && cacheControlHas(req.headers, ["no-store"])) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      }
+      if (respectResponseCacheControl && cacheControlHas(res.headers, ["private", "no-store"])) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      }
+      if (!cacheSetCookie && res.headers.has("set-cookie")) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      }
+      const declared = parseLength(res.headers.get("content-length"))
+      if (declared !== undefined && declared > maxBytes) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      }
+      const body = await readBytesCapped(res, maxBytes)
+      if (body === null) return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+
+      const headers = new Headers(res.headers)
+      headers.delete("age")
+      if (cacheStatusHeader !== false) headers.delete(cacheStatusHeader)
+      appendVary(headers, vary)
+      const now = Date.now()
+      await store.set(keyOf(req), {
+        status: res.status,
+        statusText: res.statusText,
+        headers: [...headers.entries()],
+        body,
+        expiresAt: now + ttlMs,
+        storedAt: now,
+      })
+      const outgoing = new Headers(res.headers)
+      appendVary(outgoing, vary)
+      if (cacheStatusHeader !== false) outgoing.set(cacheStatusHeader, "MISS")
+      return new Response(res.body, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: outgoing,
+      })
+    },
+  }
+}
+
+export const responseCache = cache

package/src/combine.ts

@@ -0,0 +1,24 @@
+import { definePlugin, type Middleware, type NifraPlugin } from "@nifrajs/core"
+
+export type Composable = Middleware | NifraPlugin
+
+function applyAll(app: Parameters<NifraPlugin>[0], items: readonly Composable[]) {
+  let current = app
+  for (const item of items) {
+    // The public `use` overload accepts both shapes; this helper intentionally preserves runtime
+    // composition while leaving advanced context type threading to direct `.use(...)` chains.
+    current = current.use(item as never)
+  }
+  return current
+}
+
+/** Compose middleware/plugins into one reusable bundle. Individual named plugins still dedupe. */
+export function combine(...items: readonly Composable[]): NifraPlugin {
+  return ((app) => applyAll(app, items)) as NifraPlugin
+}
+
+/** Compose middleware/plugins into one idempotent named bundle. */
+export function namedCombine(name: string, ...items: readonly Composable[]): NifraPlugin {
+  if (name.trim() === "") throw new Error("namedCombine: name is empty")
+  return definePlugin(name, (app) => applyAll(app, items))
+}

package/src/compression.ts

@@ -0,0 +1,111 @@
+import { definePlugin } from "@nifrajs/core"
+
+export interface CompressionOptions {
+  /** Don't compress bodies smaller than this many bytes. Default `1024`. Enforced by peeking the body
+   * (see below) since runtimes rarely expose `Content-Length` on a constructed `Response`. */
+  readonly threshold?: number
+  /** Decide whether a `Content-Type` is worth compressing. Default: text, JSON/+json, JS, XML/+xml,
+   * NDJSON, wasm, SVG. Already-compressed media (images, video, archives) is skipped. */
+  readonly compressible?: (contentType: string) => boolean
+}
+
+// Text-like payloads benefit from gzip; binary media (images/video/archives) is already compressed.
+const COMPRESSIBLE =
+  /^(?:text\/|application\/(?:json|[\w.-]+\+json|javascript|xml|[\w.-]+\+xml|wasm|x-ndjson)|image\/svg\+xml)/i
+
+const defaultCompressible = (contentType: string): boolean => COMPRESSIBLE.test(contentType)
+
+const concat = (chunks: readonly Uint8Array[], total: number): Uint8Array => {
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+const gzipHeaders = (source: Headers): Headers => {
+  const headers = new Headers(source)
+  headers.set("content-encoding", "gzip")
+  headers.delete("content-length") // compressed length is unknown up front → chunked
+  const vary = headers.get("vary")
+  if (vary === null) headers.set("vary", "Accept-Encoding")
+  else if (!vary.toLowerCase().split(",").includes("accept-encoding"))
+    headers.set("vary", `${vary}, Accept-Encoding`)
+  return headers
+}
+
+/**
+ * Transparently **gzip** responses when the client sends `Accept-Encoding: gzip` and the body is a
+ * compressible type larger than `threshold`. Uses the Web-standard `CompressionStream` (streaming, no
+ * full-body buffering), so it runs on every nifra runtime including the edge. gzip is the one encoding
+ * `CompressionStream` guarantees everywhere; brotli isn't part of the standard, so it's not offered.
+ *
+ * The body is **peeked** up to `threshold` bytes to enforce the size floor: a response that ends below
+ * the threshold is sent uncompressed (gzip's ~20-byte overhead would enlarge it), and only larger
+ * bodies are compressed — the buffered prefix is replayed and the remainder streamed. (Runtimes rarely
+ * set `Content-Length` on a constructed `Response`, so the header alone can't gate this.)
+ *
+ * Skips: clients that don't accept gzip, already-encoded responses, bodyless responses (204/304/HEAD),
+ * `Range` responses (206 / `Content-Range`), `Cache-Control: no-transform`, and non-compressible types.
+ * Adds `Vary: Accept-Encoding`.
+ *
+ * ```ts
+ * app.use(compression())
+ * ```
+ */
+export function compression(options: CompressionOptions = {}) {
+  const threshold = options.threshold ?? 1024
+  const isCompressible = options.compressible ?? defaultCompressible
+  return definePlugin("compression", (app) =>
+    app.onResponse(async (res, req) => {
+      const body = res.body
+      if (body === null) return res // 204/304/HEAD — nothing to compress
+      if (!(req.headers.get("accept-encoding") ?? "").toLowerCase().includes("gzip")) return res
+      if (res.headers.has("content-encoding")) return res // already encoded
+      if (res.status === 206 || res.headers.has("content-range")) return res // ranges pass through
+      if ((res.headers.get("cache-control") ?? "").includes("no-transform")) return res
+      if (!isCompressible(res.headers.get("content-type") ?? "")) return res
+      const declared = res.headers.get("content-length")
+      if (declared !== null && Number(declared) < threshold) return res // fast path when length is known
+
+      // Peek up to `threshold` bytes to decide whether compressing is worth it.
+      const reader = body.getReader()
+      const buffered: Uint8Array[] = []
+      let total = 0
+      while (total < threshold) {
+        const { done, value } = await reader.read()
+        if (done) {
+          // Body ended below the threshold — too small to be worth gzipping. Emit as-is.
+          return new Response(concat(buffered, total), {
+            status: res.status,
+            statusText: res.statusText,
+            headers: res.headers,
+          })
+        }
+        buffered.push(value)
+        total += value.byteLength
+      }
+      // Over the threshold: replay the buffered prefix, then stream the rest — all through gzip.
+      // (No explicit generic: it lets the chunk type infer from the non-shared reader so the stream
+      // matches `CompressionStream`'s `Uint8Array` typing.)
+      const source = new ReadableStream({
+        start(controller) {
+          for (const chunk of buffered) controller.enqueue(chunk)
+        },
+        async pull(controller) {
+          const { done, value } = await reader.read()
+          if (done) controller.close()
+          else controller.enqueue(value)
+        },
+        cancel: (reason) => reader.cancel(reason),
+      })
+      return new Response(source.pipeThrough(new CompressionStream("gzip")), {
+        status: res.status,
+        statusText: res.statusText,
+        headers: gzipHeaders(res.headers),
+      })
+    }),
+  )
+}

package/src/context-storage.ts

@@ -0,0 +1,36 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { Context, Middleware } from "@nifrajs/core"
+
+const storage = new AsyncLocalStorage<Context>()
+
+/**
+ * Store the current nifra `Context` in `AsyncLocalStorage` for helpers that run away from the handler
+ * argument, e.g. repository/logger functions called deep in the stack.
+ *
+ * Import from `@nifrajs/middleware/context-storage` so ordinary `@nifrajs/middleware` imports stay
+ * node-compat-free on edge runtimes. The runtime must support `node:async_hooks` AsyncLocalStorage.
+ */
+export function contextStorage(): Middleware {
+  return {
+    name: "context-storage",
+    around(context, next) {
+      return storage.run(context, next)
+    },
+  }
+}
+
+/** Return the current request context, or throw when no context-storage wrapper is active. */
+export function getContext<C extends Context = Context>(): C {
+  const context = tryGetContext<C>()
+  if (context === undefined) {
+    throw new Error(
+      "contextStorage: no active context. Add app.use(contextStorage()) before the route and call getContext() during that request.",
+    )
+  }
+  return context
+}
+
+/** Return the current request context, or `undefined` outside a context-storage request. */
+export function tryGetContext<C extends Context = Context>(): C | undefined {
+  return storage.getStore() as C | undefined
+}

package/src/cors.ts

@@ -0,0 +1,90 @@
+import type { Middleware } from "@nifrajs/core"
+import { withHeaders } from "./_utils.ts"
+
+export interface CorsOptions {
+  /** Allowed origin(s): `"*"`, an exact origin, a list, or a predicate. Default `"*"`. */
+  readonly origin?: string | ReadonlyArray<string> | ((origin: string) => boolean)
+  /** Methods advertised in the preflight response. Default the common verbs. */
+  readonly methods?: ReadonlyArray<string>
+  /** Headers allowed on the actual request. Default: reflect the preflight's requested headers. */
+  readonly allowedHeaders?: ReadonlyArray<string>
+  /** Response headers exposed to the browser. */
+  readonly exposedHeaders?: ReadonlyArray<string>
+  /** Allow credentials (cookies / `Authorization`). Cannot be combined with `origin: "*"`. Default false. */
+  readonly credentials?: boolean
+  /** Preflight cache duration, in seconds. */
+  readonly maxAge?: number
+}
+
+const DEFAULT_METHODS: ReadonlyArray<string> = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+]
+
+/** Resolve the `Access-Control-Allow-Origin` value for a request, or `null` to omit it. */
+function resolveAllowOrigin(
+  option: NonNullable<CorsOptions["origin"]>,
+  requestOrigin: string | null,
+): string | null {
+  if (option === "*") return "*"
+  if (requestOrigin === null) return null
+  if (typeof option === "function") return option(requestOrigin) ? requestOrigin : null
+  if (Array.isArray(option)) return option.includes(requestOrigin) ? requestOrigin : null
+  return option === requestOrigin ? requestOrigin : null
+}
+
+/**
+ * CORS as a {@link Middleware}. Preflight (`OPTIONS` + `Access-Control-Request-Method`)
+ * short-circuits to `204` via `onRequest`; the origin/credentials headers are added in
+ * `onResponse`, so they also land on errors, 404s, and the preflight itself.
+ *
+ * Throws at construction if `credentials: true` is paired with `origin: "*"` — the
+ * browser rejects that combination, so we fail loud instead of shipping dead CORS.
+ */
+export function cors(options: CorsOptions = {}): Middleware {
+  const origin = options.origin ?? "*"
+  const credentials = options.credentials ?? false
+  if (credentials && origin === "*") {
+    throw new Error(
+      'cors: `credentials: true` cannot be combined with `origin: "*"` — list explicit origin(s).',
+    )
+  }
+  const methods = (options.methods ?? DEFAULT_METHODS).join(", ")
+  const allowedHeaders = options.allowedHeaders?.join(", ")
+  const exposedHeaders = options.exposedHeaders?.join(", ")
+  const maxAge = options.maxAge
+
+  return {
+    name: "cors",
+    onRequest(req) {
+      const isPreflight =
+        req.method === "OPTIONS" && req.headers.has("access-control-request-method")
+      if (!isPreflight) return undefined
+      const headers = new Headers()
+      headers.set("Access-Control-Allow-Methods", methods)
+      const requested = allowedHeaders ?? req.headers.get("access-control-request-headers")
+      if (requested) headers.set("Access-Control-Allow-Headers", requested)
+      if (maxAge !== undefined) headers.set("Access-Control-Max-Age", String(maxAge))
+      // Allow-Origin / Allow-Credentials are added by onResponse (runs on every response).
+      return new Response(null, { status: 204, headers })
+    },
+    onResponse(res, req) {
+      const allowOrigin = resolveAllowOrigin(origin, req.headers.get("origin"))
+      if (allowOrigin === null) return res
+      // Mutate in place on the common (mutable-headers) response; clone only for an immutable one.
+      return withHeaders(res, (headers) => {
+        headers.set("Access-Control-Allow-Origin", allowOrigin)
+        if (allowOrigin !== "*") headers.append("Vary", "Origin")
+        if (credentials) headers.set("Access-Control-Allow-Credentials", "true")
+        if (exposedHeaders !== undefined) {
+          headers.set("Access-Control-Expose-Headers", exposedHeaders)
+        }
+      })
+    },
+  }
+}

package/src/csrf.ts

@@ -0,0 +1,102 @@
+import type { Middleware } from "@nifrajs/core"
+import {
+  base64UrlEncode,
+  hmacSha256,
+  jsonError,
+  parseCookies,
+  SAFE_METHODS,
+  secretBytes,
+  timingSafeEqualString,
+  verifyHmacSha256,
+} from "./_utils.ts"
+
+export interface CsrfOptions {
+  /** HMAC secret. Must be at least 32 bytes. */
+  readonly secret: string | Uint8Array
+  /** Cookie carrying the signed token. Default `"csrf-token"`. */
+  readonly cookie?: string
+  /** Header carrying the same signed token. Default `"x-csrf-token"`. */
+  readonly header?: string
+  /** 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. */
+  readonly origins?: readonly string[]
+  /** Check Origin/Referer on protected requests. Default true. */
+  readonly checkOrigin?: boolean
+}
+
+const TOKEN_PREFIX = "v1"
+
+function protectedMethod(method: string, configured: Set<string> | undefined): boolean {
+  return configured !== undefined ? configured.has(method) : !SAFE_METHODS.has(method)
+}
+
+function originAllowed(req: Request, origins: Set<string> | undefined): boolean {
+  const allowed = origins ?? new Set([new URL(req.url).origin])
+  const origin = req.headers.get("origin")
+  if (origin !== null) return allowed.has(origin)
+
+  const referer = req.headers.get("referer")
+  if (referer === null) return false
+  try {
+    return allowed.has(new URL(referer).origin)
+  } catch {
+    return false
+  }
+}
+
+export async function createCsrfToken(
+  secret: string | Uint8Array,
+  nonce?: string,
+): Promise<string> {
+  const key = secretBytes(secret, "csrf")
+  const tokenNonce = nonce ?? base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)))
+  if (!/^[A-Za-z0-9_-]{22,}$/.test(tokenNonce)) {
+    throw new Error("csrf: nonce must be base64url-like and at least 22 characters")
+  }
+  const payload = `${TOKEN_PREFIX}.${tokenNonce}`
+  return `${payload}.${await hmacSha256(payload, key)}`
+}
+
+export async function verifyCsrfToken(
+  token: string,
+  secret: string | Uint8Array,
+): Promise<boolean> {
+  const key = secretBytes(secret, "csrf")
+  const parts = token.split(".")
+  if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX || parts[1] === "" || parts[2] === "") {
+    return false
+  }
+  const [prefix, nonce, signature] = parts as [string, string, string]
+  return verifyHmacSha256(`${prefix}.${nonce}`, signature, key)
+}
+
+/**
+ * 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.
+ */
+export function csrf(options: CsrfOptions): Middleware {
+  const key = secretBytes(options.secret, "csrf")
+  const cookie = options.cookie ?? "csrf-token"
+  const header = (options.header ?? "x-csrf-token").toLowerCase()
+  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
+
+  return {
+    name: "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))) {
+        return jsonError(403, "csrf_failed")
+      }
+      return (await verifyCsrfToken(cookieToken, key)) ? undefined : jsonError(403, "csrf_failed")
+    },
+  }
+}