@nifrajs/middleware 3.5.0 → 4.0.0

package/src/ip-restriction.ts

@@ -1,97 +1,49 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import type { Middleware } from "@nifrajs/core/server"
-import { jsonError, type MaybePromise } from "./_utils.ts"
+import type { Middleware, Platform } from "@nifrajs/core/server"
+import { type ParsedIp, parseIp } from "./_ip.ts"
+import { guardName, jsonError, type MaybePromise } from "./_utils.ts"
 
 export type IpMatcher = string | ((ip: string, request: Request) => MaybePromise<boolean>)
 
 export interface IpRestrictionOptions {
   readonly allow?: readonly IpMatcher[]
   readonly deny?: readonly IpMatcher[]
-  /** Preferred extraction hook when the adapter/app knows the peer address. */
-  readonly clientIp?: (request: Request) => MaybePromise<string | null | undefined>
-  /** Trusted proxy count for `X-Forwarded-For` extraction. Default: 0, so XFF is ignored. */
+  /**
+   * Custom extraction hook. Without it (and without `trustedProxies`/`header`), the caller is
+   * `platform.clientIp`: the socket peer, or the app's `clientIp` trust declaration applied to it.
+   */
+  readonly clientIp?: (
+    request: Request,
+    platform?: Platform,
+  ) => MaybePromise<string | null | undefined>
+  /** Trusted proxy count for `X-Forwarded-For` extraction. Default: 0, so XFF is ignored. Prefer the
+   * app-level `server({ clientIp: { trustedHops } })` declaration, which the default honors. */
   readonly trustedProxies?: number
   /** Exact trusted single-IP header, e.g. an infra-set `x-real-ip`. Not used unless configured. */
   readonly header?: string
   readonly error?: string
 }
 
-interface ParsedIp {
-  readonly version: 4 | 6
-  readonly value: bigint
-}
-
 interface Range {
   readonly version: 4 | 6
   readonly network: bigint
   readonly mask: bigint
 }
 
-function parseIPv4(input: string): bigint | null {
-  const parts = input.split(".")
-  if (parts.length !== 4) return null
-  let out = 0n
-  for (const part of parts) {
-    if (!/^\d{1,3}$/.test(part)) return null
-    const n = Number(part)
-    if (n > 255) return null
-    out = (out << 8n) | BigInt(n)
-  }
-  return out
-}
-
-function parseIPv6(input: string): bigint | null {
-  if (input.includes("%")) return null
-  let source = input.toLowerCase()
-  if (source.includes(".")) {
-    const lastColon = source.lastIndexOf(":")
-    if (lastColon < 0) return null
-    const ipv4 = parseIPv4(source.slice(lastColon + 1))
-    if (ipv4 === null) return null
-    const hi = Number((ipv4 >> 16n) & 0xffffn).toString(16)
-    const lo = Number(ipv4 & 0xffffn).toString(16)
-    source = `${source.slice(0, lastColon)}:${hi}:${lo}`
-  }
-
-  const halves = source.split("::")
-  if (halves.length > 2) return null
-  const left = halves[0] === "" ? [] : halves[0]!.split(":")
-  const right = halves.length === 1 || halves[1] === "" ? [] : halves[1]!.split(":")
-  const groups = [...left, ...right]
-  if (groups.some((g) => !/^[0-9a-f]{1,4}$/.test(g))) return null
-
-  const missing = 8 - groups.length
-  if (halves.length === 1) {
-    if (missing !== 0) return null
-  } else if (missing < 1) return null
-
-  const expanded =
-    halves.length === 1
-      ? groups
-      : [...left, ...Array.from({ length: missing }, () => "0"), ...right]
-  let out = 0n
-  for (const group of expanded) out = (out << 16n) | BigInt(Number.parseInt(group, 16))
-  return out
-}
-
-function parseIp(input: string): ParsedIp | null {
-  const trimmed = input.trim()
-  const unbracketed =
-    trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed
-  const v4 = parseIPv4(unbracketed)
-  if (v4 !== null) return { version: 4, value: v4 }
-  const v6 = parseIPv6(unbracketed)
-  return v6 === null ? null : { version: 6, value: v6 }
-}
-
 function parseRange(input: string): Range {
   const slash = input.indexOf("/")
   const address = slash < 0 ? input : input.slice(0, slash)
   const ip = parseIp(address)
   if (ip === null) throw new Error(`ipRestriction: invalid IP/CIDR ${JSON.stringify(input)}`)
   const bits = ip.version === 4 ? 32 : 128
+  // `::ffff:10.0.0.0/104` is matched as IPv4, so its prefix counts past the 96 mapping bits.
+  const mapped = ip.version === 4 && address.includes(":") ? 96 : 0
   const prefix =
-    slash < 0 ? bits : /^\d+$/.test(input.slice(slash + 1)) ? Number(input.slice(slash + 1)) : -1
+    slash < 0
+      ? bits
+      : /^\d+$/.test(input.slice(slash + 1))
+        ? Number(input.slice(slash + 1)) - mapped
+        : -1
   if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits) {
     throw new Error(`ipRestriction: invalid CIDR prefix ${JSON.stringify(input)}`)
   }
@@ -114,10 +66,20 @@ function xForwardedClient(req: Request, trustedProxies: number): string | null {
 
 async function resolveClientIp(
   req: Request,
+  platform: Platform | undefined,
   options: IpRestrictionOptions,
 ): Promise<string | null> {
-  const custom = await options.clientIp?.(req)
+  const custom = await options.clientIp?.(req, platform)
   if (custom !== undefined && custom !== null) return custom
+  // Explicit proxy options fail closed on their own: falling back to the socket peer there would
+  // judge the proxy's address whenever the forwarded header went missing.
+  if (
+    options.clientIp === undefined &&
+    (options.trustedProxies ?? 0) === 0 &&
+    options.header === undefined
+  ) {
+    return platform?.clientIp || null
+  }
   const fromXff = xForwardedClient(req, options.trustedProxies ?? 0)
   if (fromXff !== null) return fromXff
   if (options.header !== undefined) {
@@ -152,9 +114,10 @@ async function matches(
 }
 
 /**
- * IP allow/deny middleware. It fails closed when no trustworthy client IP can be derived. Configure
- * `clientIp`, `trustedProxies`, or a trusted single-IP `header`; unconfigured X-Forwarded-For is never
- * trusted.
+ * IP allow/deny middleware. It fails closed when no trustworthy client IP can be derived. By default the
+ * caller is the server-resolved `platform.clientIp` (socket peer, or the app's `clientIp` trust
+ * declaration); `clientIp`, `trustedProxies`, or a trusted single-IP `header` override it. Unconfigured
+ * X-Forwarded-For is never trusted.
  */
 export function ipRestriction(options: IpRestrictionOptions): Middleware {
   const trustedProxies = options.trustedProxies ?? 0
@@ -173,9 +136,9 @@ export function ipRestriction(options: IpRestrictionOptions): Middleware {
 
   return withRouteAssurance<Middleware>(
     {
-      name: "ip-restriction",
-      async onRequest(req) {
-        const ipText = await resolveClientIp(req, options)
+      name: guardName("ip-restriction"),
+      async onRequest(req, platform) {
+        const ipText = await resolveClientIp(req, platform, options)
         if (ipText === null) return jsonError(403, error)
         const ip = parseIp(ipText)
         if (ip === null) return jsonError(403, error)

package/src/jwt.ts

@@ -2,6 +2,8 @@ import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 import {
   base64UrlDecode,
+  bearerToken,
+  guardName,
   jsonError,
   type MaybePromise,
   parseCookies,
@@ -302,7 +304,7 @@ function tokenFromRequest(req: Request, header: string, cookie: string | undefin
   const headerValue = req.headers.get(header)
   if (headerValue !== null) {
     if (header === "authorization") {
-      return headerValue.startsWith("Bearer ") ? headerValue.slice(7).trim() || null : null
+      return bearerToken(headerValue)
     }
     return headerValue.trim() || null
   }
@@ -324,7 +326,7 @@ export function jwt<C extends JwtClaims = JwtClaims>(options: JwtOptions): JwtPl
   const header = (options.header ?? "authorization").toLowerCase()
   const store = new WeakMap<Request, C>()
 
-  const plugin = defineIdentityPlugin("jwt", (app) =>
+  const plugin = defineIdentityPlugin(guardName("jwt"), (app) =>
     app.beforeHandle(async (c: { readonly req: Request }) => {
       const token = tokenFromRequest(c.req, header, options.cookie)
       if (token === null) return optional ? undefined : reject(realm)

package/src/language.ts

@@ -19,11 +19,15 @@ interface Range {
   readonly order: number
 }
 
+// A browser sends a handful of ranges. The header is client-controlled, and every range costs a
+// sort slot and a scan of the supported list, so only the first ones are read.
+const MAX_RANGES = 32
+
 function parseAcceptLanguage(header: string | null): Range[] {
   if (header === null) return []
   const ranges: Range[] = []
   let order = 0
-  for (const part of header.split(",")) {
+  for (const part of header.split(",", MAX_RANGES)) {
     const pieces = part.split(";").map((p) => p.trim())
     const tag = (pieces[0] ?? "").toLowerCase()
     if (tag === "") continue

package/src/multipart.ts

@@ -27,6 +27,9 @@ export interface MultipartResponseOptions {
 
 const TEXT = new TextEncoder()
 const BOUNDARY = /^[A-Za-z0-9'()+_,./:=? -]{1,70}$/
+// The boundary characters that are also header tokens. The rest - `( ) , / : = ?` and space - are
+// delimiters in a Content-Type parameter, so a boundary holding one must be sent quoted.
+const TOKEN_BOUNDARY = /^[A-Za-z0-9'+_.-]+$/
 
 interface ActiveReader {
   current: ReadableStreamDefaultReader<Uint8Array> | undefined
@@ -161,6 +164,8 @@ export function multipartResponse(
   })
   return new Response(stream, {
     status: options.status ?? 200,
-    headers: { "content-type": `multipart/${subtype}; boundary=${boundary}` },
+    headers: {
+      "content-type": `multipart/${subtype}; boundary=${TOKEN_BOUNDARY.test(boundary) ? boundary : `"${boundary}"`}`,
+    },
   })
 }

package/src/pretty-json.ts

@@ -89,6 +89,57 @@ async function peekText(res: Response, maxBytes: number): Promise<Peeked> {
   }
 }
 
+/**
+ * Re-indent JSON text the way `JSON.stringify(value, null, spaces)` lays it out, without turning it
+ * into values: every string and number is copied as written. A parse/stringify round trip rounds an
+ * integer past 2^53 (`12345678901234567890` came back `12345678901234567000`), turns `1e400` into
+ * `null`, and rewrites escapes. `text` must already be known-valid JSON.
+ */
+function reindentJson(text: string, spaces: number): string {
+  const unit = " ".repeat(spaces)
+  const pretty = spaces > 0
+  let out = ""
+  let depth = 0
+  const nextSignificant = (from: number): number => {
+    let at = from
+    while (at < text.length && isJsonWhitespace(text.charCodeAt(at))) at++
+    return at
+  }
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    if (isJsonWhitespace(code)) continue
+    if (code === 34 /* " */) {
+      let end = i + 1
+      while (text.charCodeAt(end) !== 34) end += text.charCodeAt(end) === 92 /* \ */ ? 2 : 1
+      out += text.slice(i, end + 1)
+      i = end
+    } else if (code === 123 /* { */ || code === 91 /* [ */) {
+      const close = nextSignificant(i + 1)
+      if (text.charCodeAt(close) === code + 2) {
+        out += code === 123 ? "{}" : "[]"
+        i = close
+      } else {
+        depth++
+        out += pretty ? `${text[i]}\n${unit.repeat(depth)}` : text[i]
+      }
+    } else if (code === 125 /* } */ || code === 93 /* ] */) {
+      depth--
+      out += pretty ? `\n${unit.repeat(depth)}${text[i]}` : text[i]
+    } else if (code === 44 /* , */) {
+      out += pretty ? `,\n${unit.repeat(depth)}` : ","
+    } else if (code === 58 /* : */) {
+      out += pretty ? ": " : ":"
+    } else {
+      out += text[i]
+    }
+  }
+  return out
+}
+
+function isJsonWhitespace(code: number): boolean {
+  return code === 32 || code === 9 || code === 10 || code === 13
+}
+
 function requestView(request: Request): NodeRequestContext {
   return { method: request.method, url: request.url, header: (name) => request.headers.get(name) }
 }
@@ -129,13 +180,12 @@ export function prettyJson(options: PrettyJsonOptions = {}) {
           ) {
             return undefined
           }
-          let parsed: unknown
           try {
-            parsed = JSON.parse(text)
+            JSON.parse(text)
           } catch {
             return undefined
           }
-          return `${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`
+          return `${reindentJson(text, spaces)}${newline ? "\n" : ""}`
         },
         onResponseRaw(response, req) {
           if (!isEnabled(requestView(req))) return response
@@ -172,11 +222,10 @@ async function prettyRawResponse(
 ): Promise<Response> {
   const peeked = await peekText(response, maxBytes)
   if ("response" in peeked) return peeked.response
-  let parsed: unknown
   try {
-    parsed = JSON.parse(peeked.text)
+    JSON.parse(peeked.text)
   } catch {
-    return new Response(peeked.bytes, {
+    return new Response(peeked.bytes.slice(), {
       status: response.status,
       statusText: response.statusText,
       headers: response.headers,
@@ -184,7 +233,7 @@ async function prettyRawResponse(
   }
   const headers = new Headers(response.headers)
   headers.delete("content-length")
-  return new Response(`${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`, {
+  return new Response(`${reindentJson(peeked.text, spaces)}${newline ? "\n" : ""}`, {
     status: response.status,
     statusText: response.statusText,
     headers,

package/src/problem-details.ts

@@ -176,12 +176,19 @@ export function problemDetails(options: ProblemDetailsOptions = {}) {
           return JSON.stringify(document)
         },
         async onResponseRaw(response, req) {
+          // Only a JSON body can hold the envelope, so nothing else is read: reading waits for the
+          // body to arrive, which an error page streamed in pieces - or a stream that never ends -
+          // would turn into a held-back or hung response.
+          const contentType = response.headers.get("content-type")
+          const declared = Number(response.headers.get("content-length") ?? 0)
           if (
             response.status < 400 ||
             response.status >= 600 ||
             response.body === null ||
             response.headers.has("content-encoding") ||
-            isAlreadyProblemDetails(response.headers.get("content-type"))
+            contentType === null ||
+            !JSON_TYPE.test(contentType) ||
+            declared > maxBytes
           ) {
             return response
           }

package/src/range.ts

@@ -62,11 +62,14 @@ function ifRangeMatches(value: string | null, options: RangeResponseOptions): bo
   if (value === null) return true
   const item = value.trim()
   if (options.etag !== undefined) return !item.startsWith("W/") && item === options.etag
+  // A date validator must match Last-Modified exactly (RFC 9110 section 13.1.5), not merely be later:
+  // a representation replaced by one with an older timestamp would otherwise splice foreign bytes
+  // into a resumed download.
   if (options.lastModified === undefined) return false
   const time = Date.parse(item)
   return (
     Number.isFinite(time) &&
-    Math.floor(time / 1000) >= Math.floor(options.lastModified.getTime() / 1000)
+    Math.floor(time / 1000) === Math.floor(options.lastModified.getTime() / 1000)
   )
 }
 
@@ -91,8 +94,8 @@ function shouldReturnNotModified(request: Request, options: RangeResponseOptions
   )
 }
 
-function responseBody(bytes: Uint8Array, request: Request): Uint8Array | null {
-  return request.method === "HEAD" ? null : bytes
+function responseBody(bytes: Uint8Array, request: Request): Uint8Array<ArrayBuffer> | null {
+  return request.method === "HEAD" ? null : new Uint8Array(bytes)
 }
 
 function multipartBytes(

package/src/rate-limit.ts

@@ -1,6 +1,12 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import type { Middleware, NodeRequestContext, NodeResponseContext } from "@nifrajs/core/server"
-import { setNodeHeader, withHeaders } from "./_utils.ts"
+import type {
+  Middleware,
+  NodeRequestContext,
+  NodeResponseContext,
+  Platform,
+} from "@nifrajs/core/server"
+import { ipBucket } from "./_ip.ts"
+import { guardName, setNodeHeader, withHeaders } from "./_utils.ts"
 
 export interface RateLimitResult {
   /** Hits recorded in the current window, including this one. */
@@ -130,7 +136,8 @@ export interface RateLimitOptions {
   readonly windowMs: number
   /**
    * How many trusted reverse proxies sit in front of the app and append to `X-Forwarded-For`.
-   * Default `0`.
+   * Default `0`. Prefer the app-level `server({ clientIp: { trustedHops } })` declaration, which the
+   * default key already honors; this option is for a limiter that must read XFF on its own.
    *
    * The default key reads the client IP from `X-Forwarded-For` as the address your **edge** proxy
    * observed - the entry `trustedProxies` from the right (1 proxy → the rightmost hop; 2 → the
@@ -140,34 +147,45 @@ export interface RateLimitOptions {
    * ⚠️ With the default `0`, `X-Forwarded-For` is treated as fully client-controlled and **ignored**.
    * Reading the
    * *first* XFF hop - the old behavior - let any client mint a fresh bucket per request and defeat the
-   * limiter. Set `trustedProxies` (only safe behind a proxy you control that appends XFF), configure a
-   * trusted single-IP {@link header}, or supply a custom {@link key} (e.g. an authenticated user id).
+   * limiter.
    */
   readonly trustedProxies?: number
   /** Exact trusted single-IP header, e.g. an infra-set `x-real-ip`. Not read unless configured. */
   readonly header?: string
   /**
-   * Allow one shared bucket when no per-request key can be derived. Off by default because it lets one
-   * client consume the quota for everyone. Enable only for intentional global throttles.
+   * One shared bucket for every request that {@link header}/{@link trustedProxies} cannot key. Off by
+   * default because it lets one client consume the quota for everyone. Enable only for intentional
+   * global throttles; with neither `header` nor `trustedProxies` set, every request shares the bucket.
    */
   readonly allowGlobalKey?: boolean
   /**
-   * Bucket key for a request. Overrides the default XFF-based key entirely - set this for accurate
-   * per-client limiting (e.g. an authenticated user id, or a header your proxy sets). A `Middleware`
-   * can't see the socket IP (that needs the server instance).
+   * Bucket key for a request. Overrides the default key entirely - e.g. an authenticated user id.
+   * `platform.clientIp` is the caller the app's `clientIp` trust declaration derived (the socket peer
+   * when none is declared).
    */
-  readonly key?: (req: Request) => string
+  readonly key?: (req: Request, platform?: Platform) => string
 }
 
+/**
+ * The default bucket key. With nothing configured it is the caller IP the server resolved into
+ * `platform.clientIp` - the raw socket peer, or the app's `clientIp` trust declaration applied to the
+ * forwarding chain. `null` (no adapter-observed peer, e.g. a synthetic `app.fetch`) fails closed.
+ * Every IP-derived key goes through {@link ipBucket}: an IPv6 caller counts by its /64.
+ */
 function defaultKey(
   req: Request,
+  platform: Platform | undefined,
   trustedProxies: number,
   header: string | undefined,
   allowGlobalKey: boolean,
 ): string | null {
+  if (header === undefined && trustedProxies === 0 && !allowGlobalKey) {
+    const peer = platform?.clientIp
+    return peer ? ipBucket(peer) : null
+  }
   if (header !== undefined) {
     const ip = req.headers.get(header)
-    if (ip !== null && ip.trim() !== "") return ip.trim()
+    if (ip !== null && ip.trim() !== "") return ipBucket(ip.trim())
   }
   if (trustedProxies > 0) {
     const xff = req.headers.get("x-forwarded-for")
@@ -177,7 +195,7 @@ function defaultKey(
       // proxy observed = the real client. A client can only prepend fakes further left, which this
       // index skips. A chain shorter than `trustedProxies` (misconfig) → undefined → fall through.
       const ip = parts[parts.length - trustedProxies]?.trim()
-      if (ip !== undefined && ip !== "") return ip
+      if (ip !== undefined && ip !== "") return ipBucket(ip)
     }
   }
   // No trusted proxy (or XFF absent/too-short): XFF isn't trustworthy, so don't derive a per-client key
@@ -188,20 +206,25 @@ function defaultKey(
 /** {@link defaultKey} against the allocation-light native request view - same logic, same order. */
 function nativeKey(
   req: NodeRequestContext,
+  platform: Platform | undefined,
   trustedProxies: number,
   header: string | undefined,
   allowGlobalKey: boolean,
 ): string | null {
+  if (header === undefined && trustedProxies === 0 && !allowGlobalKey) {
+    const peer = platform?.clientIp
+    return peer ? ipBucket(peer) : null
+  }
   if (header !== undefined) {
     const ip = req.header(header)
-    if (ip !== null && ip.trim() !== "") return ip.trim()
+    if (ip !== null && ip.trim() !== "") return ipBucket(ip.trim())
   }
   if (trustedProxies > 0) {
     const xff = req.header("x-forwarded-for")
     if (xff !== null) {
       const parts = xff.split(",")
       const ip = parts[parts.length - trustedProxies]?.trim()
-      if (ip !== undefined && ip !== "") return ip
+      if (ip !== undefined && ip !== "") return ipBucket(ip)
     }
   }
   return allowGlobalKey ? "global" : null
@@ -226,18 +249,10 @@ export function rateLimit(options: RateLimitOptions): Middleware {
   const header = options.header?.trim().toLowerCase()
   if (header !== undefined && header.trim() === "") throw new Error("rateLimit: header is empty")
   const allowGlobalKey = options.allowGlobalKey === true
-  if (
-    options.key === undefined &&
-    header === undefined &&
-    trustedProxies === 0 &&
-    !allowGlobalKey
-  ) {
-    throw new Error(
-      "rateLimit: configure key, header, or trustedProxies; pass allowGlobalKey: true only for an intentional shared bucket",
-    )
-  }
   const keyOf =
-    options.key ?? ((req: Request) => defaultKey(req, trustedProxies, header, allowGlobalKey))
+    options.key ??
+    ((req: Request, platform?: Platform) =>
+      defaultKey(req, platform, trustedProxies, header, allowGlobalKey))
   const quota = new WeakMap<Request, { remaining: number; resetSeconds: number }>()
   // State for the Node twins, keyed by the NodeRequestContext identity (the same object is passed
   // to the request and response twins - the core identity contract that replaces `Request` keying).
@@ -270,9 +285,9 @@ export function rateLimit(options: RateLimitOptions): Middleware {
   }
 
   const middleware: Middleware = {
-    name: "rate-limit",
-    async onRequest(req) {
-      const outcome = await hitStore(keyOf(req))
+    name: guardName("rate-limit"),
+    async onRequest(req, platform) {
+      const outcome = await hitStore(keyOf(req, platform))
       if (outcome instanceof Response) return outcome
       quota.set(req, outcome.info)
       return outcome.reject
@@ -291,8 +306,10 @@ export function rateLimit(options: RateLimitOptions): Middleware {
     // takes a real `Request`, which is exactly the object the native lane avoids building.
     ...(options.key === undefined
       ? {
-          onNodeRequest: async (req: NodeRequestContext) => {
-            const outcome = await hitStore(nativeKey(req, trustedProxies, header, allowGlobalKey))
+          onNodeRequest: async (req: NodeRequestContext, platform?: Platform) => {
+            const outcome = await hitStore(
+              nativeKey(req, platform, trustedProxies, header, allowGlobalKey),
+            )
             if (outcome instanceof Response) return outcome
             nativeQuota.set(req, outcome.info)
             return outcome.reject

package/src/request-id.ts

@@ -4,10 +4,19 @@ import { setNodeHeader, withHeaders } from "./_utils.ts"
 export interface RequestIdOptions {
   /** Header read for an inbound id (trace propagation) + echoed on the response. Default `"x-request-id"`. */
   readonly header?: string
-  /** Generate an id when the inbound header is absent. Default `crypto.randomUUID()`. */
+  /** Generate an id when the inbound header is absent or not accepted. Default `crypto.randomUUID()`. */
   readonly generate?: () => string
+  /**
+   * Whether an inbound id is used. The id is client-supplied and lands in logs, traces, and the
+   * response, so the default accepts 1-200 visible ASCII characters - no spaces, no control
+   * characters (a terminal escape sequence), no unbounded length. A refused id is replaced by a
+   * generated one.
+   */
+  readonly accept?: (id: string) => boolean
 }
 
+const INBOUND_ID = /^[\x21-\x7e]{1,200}$/
+
 /**
  * A {@link defineContextPlugin} plugin that gives every request a stable id: it reuses an inbound
  * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
@@ -29,6 +38,9 @@ export function requestId(options: RequestIdOptions = {}): ContextPlugin<{ reque
   // the response twin's "already echoed?" probe and the derive's write must agree on it.
   const wireHeader = header.toLowerCase()
   const generate = options.generate ?? (() => crypto.randomUUID())
+  const acceptable = options.accept ?? ((id: string) => INBOUND_ID.test(id))
+  const inboundOf = (id: string | null): string | null =>
+    id !== null && acceptable(id) ? id : null
   // Web-lane derive-to-response pairing for GENERATED ids (an inbound one is re-readable from the
   // request in onResponse). Entries are deleted in onResponse; a Node-lane derive also writes here
   // but its id travels via the `c.set` write into the outcome record, and the weakly-held entry is
@@ -52,7 +64,7 @@ export function requestId(options: RequestIdOptions = {}): ContextPlugin<{ reque
           if (res.headers.get(header) !== null) return res
           // The id the derive generated; else the inbound header, then a fresh id - so a response
           // no derive saw (a 404, an earlier middleware's short-circuit) is still covered.
-          const echo = id ?? req.headers.get(header) ?? generate()
+          const echo = id ?? inboundOf(req.headers.get(header)) ?? generate()
           return withHeaders(res, (headers) => {
             headers.set(header, echo)
           })
@@ -62,7 +74,7 @@ export function requestId(options: RequestIdOptions = {}): ContextPlugin<{ reque
           // exactly this one record-property check. Anything the derive never saw - a 404, a native
           // short-circuit - gets the inbound id or a fresh one here.
           if (res.headers?.[wireHeader] !== undefined) return
-          setNodeHeader(res, wireHeader, req.header(header) ?? generate())
+          setNodeHeader(res, wireHeader, inboundOf(req.header(header)) ?? generate())
         },
       })
       .derive((c) => {
@@ -72,7 +84,7 @@ export function requestId(options: RequestIdOptions = {}): ContextPlugin<{ reque
         // carries it into a framework-rendered result on every lane - on Node-direct, into the
         // outcome record, where the response twin sees it as already echoed. Header and
         // `c.requestId` are therefore the same value everywhere with a single generation.
-        const inbound = c.header(header)
+        const inbound = inboundOf(c.header(header))
         const id = inbound ?? generate()
         if (inbound === null) ids.set(c.req, id)
         c.set.headers[wireHeader] = id

package/src/security-headers.ts

@@ -36,6 +36,10 @@ export interface SecurityHeadersOptions {
  * Every value is fixed at construction, so these are declared statically rather than written by a
  * response hook: an app whose response middleware is only this keeps the fused native lanes. A route
  * that sets one of these names itself keeps its own value.
+ *
+ * A group can apply its own configuration over the app's: `group.use(securityHeaders({ ... }))`
+ * replaces the app's value of each header it sets, on the group's routes only. Applying the same
+ * configuration twice is a no-op.
  */
 export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
   const frameOptions = options.frameOptions ?? "DENY"
@@ -72,7 +76,9 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
 
   return withRouteAssurance<Middleware>(
     {
-      name: "security-headers",
+      // The configuration is part of the name: the same one applied twice dedupes, while a group's
+      // different configuration applies over its parent's instead of being skipped as a repeat.
+      name: `security-headers:${JSON.stringify(declared)}`,
       responseHeaders: declared,
     },
     {

package/src/token-auth.ts

@@ -1,5 +1,6 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
+import { bearerToken, guardName } from "./_utils.ts"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -48,7 +49,7 @@ function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
         headers: config.challenge !== undefined ? { "www-authenticate": config.challenge } : {},
       },
     )
-  const plugin = defineIdentityPlugin(config.name, (app) =>
+  const plugin = defineIdentityPlugin(guardName(config.name), (app) =>
     app.beforeHandle(async (c: { readonly req: Request }) => {
       const token = config.extract(c.req)
       // Empty string is treated as "no credential" - never passed to verify.
@@ -96,10 +97,7 @@ export function bearer<P>(options: BearerOptions<P>): AuthPlugin<P> {
   const realm = options.realm ?? "api"
   return createTokenAuth({
     name: "bearer",
-    extract: (request) => {
-      const header = request.headers.get("authorization")
-      return header?.startsWith("Bearer ") === true ? header.slice(7).trim() : undefined
-    },
+    extract: (request) => bearerToken(request.headers.get("authorization")) ?? undefined,
     verify: options.verify,
     optional: options.optional === true,
     challenge: `Bearer realm="${realm}"`,