@nifrajs/middleware 2.10.0 → 2.12.0

package/src/csrf.ts

@@ -11,9 +11,26 @@ import {
   verifyHmacSha256,
 } from "./_utils.ts"
 
+/**
+ * An HMAC secret, or a rotation list of them. With a list, the **first** secret signs new tokens
+ * and any listed secret verifies - rotate by prepending the new secret and dropping the old one
+ * once outstanding tokens have expired. Every entry must meet the 32-byte floor; an empty list
+ * throws.
+ */
+export type CsrfSecret = string | Uint8Array | ReadonlyArray<string | Uint8Array>
+
+/** Normalize to derived keys, validating every entry's 32-byte floor up front (fail loud at
+ * construction, not on the first request that happens to reach an old secret). */
+function csrfKeys(secret: CsrfSecret): ReadonlyArray<Uint8Array> {
+  const list: ReadonlyArray<string | Uint8Array> =
+    typeof secret === "string" || secret instanceof Uint8Array ? [secret] : secret
+  if (list.length === 0) throw new Error("csrf: secret list cannot be empty")
+  return list.map((s) => secretBytes(s, "csrf"))
+}
+
 export interface CsrfOptions {
-  /** HMAC secret. Must be at least 32 bytes. */
-  readonly secret: string | Uint8Array
+  /** HMAC secret (≥ 32 bytes), or a rotation list - see {@link CsrfSecret}. */
+  readonly secret: CsrfSecret
   /** Cookie carrying the signed token. Default `"csrf-token"`. */
   readonly cookie?: string
   /** Header carrying the same signed token. Default `"x-csrf-token"`. */
@@ -46,11 +63,8 @@ function originAllowed(req: Request, origins: Set<string> | undefined): boolean
   }
 }
 
-export async function createCsrfToken(
-  secret: string | Uint8Array,
-  nonce?: string,
-): Promise<string> {
-  const key = secretBytes(secret, "csrf")
+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)))
   if (!/^[A-Za-z0-9_-]{22,}$/.test(tokenNonce)) {
     throw new Error("csrf: nonce must be base64url-like and at least 22 characters")
@@ -59,17 +73,19 @@ export async function createCsrfToken(
   return `${payload}.${await hmacSha256(payload, key)}`
 }
 
-export async function verifyCsrfToken(
-  token: string,
-  secret: string | Uint8Array,
-): Promise<boolean> {
-  const key = secretBytes(secret, "csrf")
+export async function verifyCsrfToken(token: string, secret: CsrfSecret): Promise<boolean> {
+  const keys = csrfKeys(secret)
   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)
+  // Rotation: accept a token signed by any listed secret. Each comparison is constant-time; which
+  // generation matched is not attacker-meaningful, so the early exit between keys leaks nothing.
+  for (const key of keys) {
+    if (await verifyHmacSha256(`${prefix}.${nonce}`, signature, key)) return true
+  }
+  return false
 }
 
 /**
@@ -77,7 +93,7 @@ export async function verifyCsrfToken(
  * 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 keys = csrfKeys(options.secret)
   const cookie = options.cookie ?? "csrf-token"
   const header = (options.header ?? "x-csrf-token").toLowerCase()
   const methods =
@@ -97,7 +113,7 @@ export function csrf(options: CsrfOptions): Middleware {
       if (!(await timingSafeEqualString(cookieToken, headerToken))) {
         return jsonError(403, "csrf_failed")
       }
-      return (await verifyCsrfToken(cookieToken, key)) ? undefined : jsonError(403, "csrf_failed")
+      return (await verifyCsrfToken(cookieToken, keys)) ? undefined : jsonError(403, "csrf_failed")
     },
   }
   return withRouteAssurance(middleware, {

package/src/durable-command.ts

@@ -3,7 +3,7 @@ import {
   attachCapabilityJournal,
   type CapabilityExecutionJournal,
 } from "@nifrajs/core/capabilities"
-import { definePlugin, type NifraPlugin } from "@nifrajs/core/server"
+import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 
 export interface DurableCommandOptions {
   /** Where effect transitions are recorded. `createDurableEffectJournal` from
@@ -36,7 +36,7 @@ export interface DurableCommandOptions {
  * deliberately never proves this one: replaying a stored response after a crash mid-effect does not
  * make the effect exactly-once, and the journal is what survives the crash.
  */
-export function durableCommand(options: DurableCommandOptions): NifraPlugin {
+export function durableCommand(options: DurableCommandOptions): IdentityPlugin {
   const journal = options.journal
   if (journal === null || typeof journal !== "object") {
     throw new TypeError("durableCommand: journal must be a CapabilityExecutionJournal")
@@ -48,7 +48,7 @@ export function durableCommand(options: DurableCommandOptions): NifraPlugin {
       throw new TypeError(`durableCommand: journal.${method} must be a function`)
     }
   }
-  const plugin = definePlugin("nifra:durable-command", (app) =>
+  const plugin = defineIdentityPlugin("nifra:durable-command", (app) =>
     app.beforeHandle((c: object) => {
       attachCapabilityJournal(c, journal)
       return undefined

package/src/etag.ts

@@ -1,4 +1,4 @@
-import { definePlugin, type ResponseBodyReplacement } from "@nifrajs/core/server"
+import { defineRouterPlugin, type ResponseBodyReplacement } from "@nifrajs/core/server"
 
 /** 32-bit FNV-1a over bytes → hex. A fast, dependency-free content fingerprint for ETags - not crypto. */
 function fnv1a(bytes: Uint8Array): string {
@@ -92,7 +92,7 @@ function replayFrom(res: Response, chunks: readonly Uint8Array[], reader: ChunkR
 }
 
 /**
- * A {@link definePlugin} plugin that adds a content-hash `ETag` to `GET` `200` responses and returns
+ * A {@link defineRouterPlugin} plugin that adds a content-hash `ETag` to `GET` `200` responses and returns
  * **`304 Not Modified`** when the client's `If-None-Match` matches - saving bandwidth on unchanged
  * responses. Built on the portable `onResponseBody` tier: the hook receives the final
  * framework-serialized bytes on every runtime with nothing drained, so the middleware stays on
@@ -106,7 +106,7 @@ export function etag(options: ETagOptions = {}) {
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
     throw new Error("etag: maxBytes must be a non-negative safe integer")
   }
-  return definePlugin("etag", (app) =>
+  return defineRouterPlugin("etag", (app) =>
     app.use({
       onResponseBody(body, headers, req, status) {
         if (req.method !== "GET" || status !== 200) return undefined

package/src/healthcheck.ts

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { defineRouterPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -26,12 +26,15 @@ const noStore = { "cache-control": "no-store" } as const
  * app.use(healthcheck({ checks: { db: () => db.ping() } })).use(bearer({ verify }))
  * ```
  */
-export function healthcheck(options: HealthcheckOptions = {}) {
+export function healthcheck(options: HealthcheckOptions = {}): IdentityPlugin {
   const path = options.path ?? "/health"
   const readyPath = options.readyPath ?? "/ready"
   const checks = options.checks ?? {}
   const checkNames = Object.keys(checks)
-  return definePlugin("healthcheck", (app) => {
+  // A router plugin: the probes are registered as a side effect and the app comes back with its type
+  // unchanged, so routes declared after `.use(healthcheck())` keep theirs. The probes are deliberately
+  // absent from the caller's typed registry - they are operational endpoints, not part of the contract.
+  return defineRouterPlugin("healthcheck", (app) => {
     app.register("GET", path, undefined, () =>
       Response.json({ status: "ok" }, { headers: noStore }),
     )

package/src/idempotency.ts

@@ -47,15 +47,34 @@ export interface IdempotencyStore {
 export interface MemoryIdempotencyStoreOptions {
   /** Allow the in-memory store in production. Off by default - a per-instance store can't dedupe across instances. */
   readonly allowInProduction?: boolean
+  /** Maximum retained locks + records. Default `10_000`. */
+  readonly maxEntries?: number
+  /** Maximum key length in UTF-8 bytes. Default `1024`. */
+  readonly maxKeyBytes?: number
 }
 
 type Entry =
   | { readonly kind: "lock"; readonly expiresAt: number }
   | { readonly kind: "record"; readonly record: IdempotencyRecord; readonly expiresAt: number }
 
+const KEY_ENCODER = new TextEncoder()
+
+/**
+ * Thrown by a store that is full of entries none of which may be discarded. The middleware turns it
+ * into a `503` with `retry-after`; a store that can grow (Redis) never raises it.
+ */
+export class IdempotencyCapacityError extends Error {
+  constructor() {
+    super("idempotency store is at capacity")
+    this.name = "IdempotencyCapacityError"
+  }
+}
+
 /** In-process store. Refuses to run in production unless explicitly allowed (per-instance ⇒ no cross-instance dedupe). */
 export class MemoryIdempotencyStore implements IdempotencyStore {
   private readonly entries = new Map<string, Entry>()
+  private readonly maxEntries: number
+  private readonly maxKeyBytes: number
 
   constructor(options: MemoryIdempotencyStoreOptions = {}) {
     if (options.allowInProduction !== true && process.env.NODE_ENV === "production") {
@@ -64,11 +83,51 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
           "Use a shared store (e.g. Redis), or pass { allowInProduction: true } for a single-instance deploy.",
       )
     }
+    this.maxEntries = options.maxEntries ?? 10_000
+    this.maxKeyBytes = options.maxKeyBytes ?? 1024
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 1)
+      throw new RangeError("MemoryIdempotencyStore: maxEntries must be a positive safe integer")
+    if (!Number.isSafeInteger(this.maxKeyBytes) || this.maxKeyBytes < 1)
+      throw new RangeError("MemoryIdempotencyStore: maxKeyBytes must be a positive safe integer")
+  }
+
+  private validateKey(key: string): void {
+    if (KEY_ENCODER.encode(key).byteLength > this.maxKeyBytes)
+      throw new RangeError("MemoryIdempotencyStore: key is too large")
+  }
+
+  private maintain(now: number): void {
+    // Expiry cleanup is incremental so normal requests never scan the full map.
+    let checked = 0
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(key)
+      if (++checked >= 16) break
+    }
+  }
+
+  private reserve(key: string, entry: Entry): void {
+    if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      // The incremental sweep only samples, so pay for a full one before declaring the store full.
+      const now = Date.now()
+      for (const [existing, held] of this.entries) {
+        if (held.expiresAt <= now) this.entries.delete(existing)
+      }
+    }
+    if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      // Refuse rather than evict. Every entry here is either a lock on a request still running or a
+      // response another request is entitled to replay, so dropping one to make room hands out
+      // exactly the duplicate execution this store exists to prevent - and does it silently, under
+      // the load where it is most likely to matter. A 503 is the honest answer; raise `maxEntries`.
+      throw new IdempotencyCapacityError()
+    }
+    this.entries.set(key, entry)
   }
 
   begin(key: string, lockTtlMs: number): Promise<IdempotencyClaim> {
+    this.validateKey(key)
     assertPositiveTtl(lockTtlMs, "lockTtlMs")
     const now = Date.now()
+    this.maintain(now)
     const entry = this.entries.get(key)
     if (entry !== undefined && entry.expiresAt > now) {
       return Promise.resolve(
@@ -78,13 +137,14 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       )
     }
     // Free (or expired): take the lock. Synchronous Map write ⇒ atomic on a single instance.
-    this.entries.set(key, { kind: "lock", expiresAt: now + lockTtlMs })
+    this.reserve(key, { kind: "lock", expiresAt: now + lockTtlMs })
     return Promise.resolve({ state: "new" })
   }
 
   complete(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void> {
+    this.validateKey(key)
     assertPositiveTtl(ttlMs, "ttlMs")
-    this.entries.set(key, { kind: "record", record, expiresAt: Date.now() + ttlMs })
+    this.reserve(key, { kind: "record", record, expiresAt: Date.now() + ttlMs })
     return Promise.resolve()
   }
 
@@ -111,12 +171,29 @@ export interface IdempotencyOptions {
   /** Whether a response should be cached for replay. Default: status `< 500` (don't replay transient 5xx). */
   readonly shouldCache?: (response: Response) => boolean
   /**
-   * Derive the store key from the request. Default: the `header` value **scoped by method + path**, so the
-   * same key on a different endpoint can't collide. Return a **principal-scoped** key (e.g.
-   * `` `${userId}:${req.headers.get("idempotency-key")}` ``) so one user can't replay another's stored
-   * response on a shared key. Return `null`/`""` to skip dedupe for this request.
+   * Derive the store key from the request. Default: the `header` value scoped by method + path **and
+   * by a digest of the caller's credentials** (see `principalHeaders`), so neither a different
+   * endpoint nor a different caller can collide on one key. Return `null`/`""` to skip dedupe for
+   * this request.
+   *
+   * Supplying your own replaces that scoping entirely - a custom key MUST fold in the principal
+   * itself (e.g. `` `${userId}:${req.headers.get("idempotency-key")}` ``), or one user can replay
+   * another's stored response by guessing their key.
+   */
+  readonly key?: (req: Request, header: string) => string | null | Promise<string | null>
+  /**
+   * Headers whose values identify the caller. Their digest scopes the default key, so the same
+   * `Idempotency-Key` from two callers addresses two entries and neither can read the other's cached
+   * response. Defaults to Authorization, Cookie, and x-api-key. Only a digest is stored - a raw
+   * credential must never become a store key, which would put it in front of every Redis `KEYS` dump
+   * and slow-log line. Ignored when `key` is supplied.
+   *
+   * The digest covers the header value verbatim, so anything that varies between two requests from the
+   * same caller - a rotated bearer token, an analytics cookie appended mid-session - lands on a fresh
+   * key and the retry executes again. Narrow the list (or supply `key`) when the app has a stable
+   * principal id to scope by; that is strictly better than digesting a whole `Cookie` header.
    */
-  readonly key?: (req: Request, header: string) => string | null
+  readonly principalHeaders?: readonly string[]
 }
 
 const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const
@@ -258,23 +335,54 @@ function replay(record: IdempotencyRecord): Response {
   return new Response(bodyFor(fromBase64(record.body)), { status: record.status, headers })
 }
 
+const DEFAULT_PRINCIPAL_HEADERS = ["authorization", "cookie", "x-api-key"] as const
+
+/** SHA-256 of the caller's credential headers, base64url. Only the digest ever becomes part of a store
+ * key: a raw `Authorization` value used as a key would be printed by every Redis `KEYS` dump, slow-log
+ * line, and store-side metric that treats keys as non-sensitive. */
+async function principalDigest(req: Request, headers: readonly string[]): Promise<string | null> {
+  let material = ""
+  for (const name of headers) {
+    const value = req.headers.get(name)
+    // The header name is part of the material so `authorization: x` and `x-api-key: x` can't collide.
+    if (value !== null) material += `${name}:${value}\n`
+  }
+  if (material === "") return null // no credentials presented - an anonymous caller
+  const hash = await crypto.subtle.digest("SHA-256", KEY_ENCODER.encode(material))
+  return toBase64(new Uint8Array(hash)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+/**
+ * The default store key: the `header` value scoped by method + path (so the same key on a different
+ * endpoint can't collide) **and by a digest of the caller's credentials** (so one caller can't replay
+ * another's stored response by presenting their key). `null` when no key header is present - no dedupe.
+ */
+function defaultIdempotencyKey(
+  req: Request,
+  header: string,
+  principalHeaders: readonly string[],
+): Promise<string | null> | null {
+  const raw = req.headers.get(header)
+  if (raw === null || raw === "") return null
+  const scope = `${req.method.toUpperCase()} ${new URL(req.url).pathname}`
+  return principalDigest(req, principalHeaders).then(
+    (principal) => `${scope}\n${principal ?? "anon"}\n${raw}`,
+  )
+}
+
 /**
  * Idempotency-key middleware. Apply with `app.use(idempotency({ store }))`.
  *
+ * The store key is scoped by method + path **and** by a digest of the caller's credential headers, so
+ * a key one caller chose addresses only that caller's entry - presenting someone else's key replays
+ * nothing. See `principalHeaders`; a custom `key` replaces that scoping and must do it itself.
+ *
  * **`Set-Cookie` is intentionally not cached or replayed** - a cookie set on the first request is
  * 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.
  *
  * Caching buffers the response body, so apply this to JSON/API routes, not streaming SSR responses.
  */
-/** The default store key: the `header` value scoped by method + path, so the same key on a different
- * endpoint can't collide (cross-resource replay). `null` when no key header is present (no dedupe). */
-function defaultIdempotencyKey(req: Request, header: string): string | null {
-  const raw = req.headers.get(header)
-  if (raw === null || raw === "") return null
-  return `${req.method.toUpperCase()} ${new URL(req.url).pathname}\n${raw}`
-}
-
 export function idempotency(options: IdempotencyOptions): Middleware {
   const { store } = options
   const header = (options.header ?? "idempotency-key").toLowerCase()
@@ -288,16 +396,36 @@ export function idempotency(options: IdempotencyOptions): Middleware {
     throw new Error("idempotency: maxBytes must be a non-negative integer")
   }
   const shouldCache = options.shouldCache ?? ((res: Response) => res.status < 500)
-  const keyOf = options.key ?? defaultIdempotencyKey
+  const principalHeaders = (options.principalHeaders ?? DEFAULT_PRINCIPAL_HEADERS).map((name) =>
+    name.toLowerCase(),
+  )
+  const custom = options.key
+  const keyOf =
+    custom === undefined
+      ? (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 middleware: Middleware = {
     name: "idempotency",
     async onRequest(req) {
       if (!methods.has(req.method.toUpperCase())) return undefined
-      const key = keyOf(req, header)
+      const key = await keyOf(req)
       if (key === null || key === "") return undefined // opt-in per request - no key ⇒ no dedupe
-      const claim = await store.begin(key, lockTtlMs)
+      let claim: IdempotencyClaim
+      try {
+        claim = await store.begin(key, lockTtlMs)
+      } catch (err) {
+        // A full store can't tell a first request from a retry, and guessing either way is wrong:
+        // serving the request risks a duplicate side effect, replaying nothing risks losing one. Say
+        // so with a 503 the client is expected to retry, rather than a 500 that reads as a bug.
+        if (!(err instanceof IdempotencyCapacityError)) throw err
+        return new Response(JSON.stringify({ ok: false, error: "idempotency_unavailable" }), {
+          status: 503,
+          headers: { "content-type": "application/json", "retry-after": "1" },
+        })
+      }
       if (claim.state === "replay") return replay(claim.record)
       if (claim.state === "in_flight") {
         return new Response(JSON.stringify({ ok: false, error: "idempotency_in_progress" }), {

package/src/jwt.ts

@@ -1,5 +1,5 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { definePlugin, type NifraPlugin } from "@nifrajs/core/server"
+import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 import {
   base64UrlDecode,
   jsonError,
@@ -76,7 +76,7 @@ export interface JwtOptions extends VerifyJwtOptions {
   readonly cookie?: string
 }
 
-export type JwtPlugin<C extends JwtClaims = JwtClaims> = NifraPlugin & {
+export type JwtPlugin<C extends JwtClaims = JwtClaims> = IdentityPlugin & {
   claims(request: Request): C | null
   requireClaims(request: Request): C
 }
@@ -152,7 +152,25 @@ async function importKey(
   kid: string | undefined,
 ): Promise<CryptoKey> {
   const hash = HASH[alg]
-  if (key instanceof CryptoKey) return key
+  if (key instanceof CryptoKey) {
+    const algorithm = key.algorithm as {
+      readonly name: string
+      readonly hash?: { readonly name?: string }
+    }
+    const expectedName = HMAC_ALGS.has(alg) ? "HMAC" : "RSASSA-PKCS1-v1_5"
+    const expectedType = HMAC_ALGS.has(alg) ? "secret" : "public"
+    const actualHash =
+      "hash" in algorithm && typeof algorithm.hash === "object" ? algorithm.hash.name : undefined
+    if (
+      key.type !== expectedType ||
+      algorithm.name !== expectedName ||
+      actualHash !== hash ||
+      !key.usages.includes("verify")
+    ) {
+      throw jwtError("CryptoKey does not match the requested JWT algorithm")
+    }
+    return key
+  }
   if (typeof key === "string" || key instanceof Uint8Array) {
     if (!HMAC_ALGS.has(alg)) throw jwtError("symmetric key cannot verify an RSA token")
     return crypto.subtle.importKey("raw", secretBytes(key, "jwt"), { name: "HMAC", hash }, false, [
@@ -306,7 +324,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 = definePlugin("jwt", (app) =>
+  const plugin = defineIdentityPlugin("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

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { type ContextPlugin, defineContextPlugin } from "@nifrajs/core/server"
 
 export interface LanguageMatch {
   readonly language: string
@@ -78,8 +78,14 @@ export function pickLanguage<const L extends readonly string[]>(
 
 /**
  * Derives `c.language` from `Accept-Language` and emits `Content-Language` by default.
+ *
+ * Header-only by design. For the full detector - `?lang=` query parameter → cookie →
+ * `Accept-Language`, with optional cookie persistence - use `localeDetector()` from
+ * `@nifrajs/i18n/detector`; use one or the other, not both.
  */
-export function language<const L extends readonly string[]>(options: LanguageOptions<L>) {
+export function language<const L extends readonly string[]>(
+  options: LanguageOptions<L>,
+): ContextPlugin<{ language: L[number]; languageMatch: LanguageMatch }> {
   const { supported, defaultLanguage } = options
   if (supported.length === 0) throw new Error("language: supported must not be empty")
   if (!supported.includes(defaultLanguage)) {
@@ -90,19 +96,23 @@ export function language<const L extends readonly string[]>(options: LanguageOpt
   // instead of pairing state through a WeakMap - that is what lets the Node twin exist at all (it
   // has no `Request` identity to key on), keeps both hooks trivially identical, and lets the derive
   // read the header without materializing a Web `Request` on the Node adapter.
-  return definePlugin("language", (app) =>
-    app
-      .derive((c) => {
-        const match = pickLanguage(c.header("accept-language"), supported, defaultLanguage)
-        return { language: match.language, languageMatch: match }
-      })
-      .use({
-        onResponseHeaders(headers, req) {
-          if (!emitHeader) return
-          if (headers.has("content-language")) return
-          const match = pickLanguage(req.header("accept-language"), supported, defaultLanguage)
-          headers.set("content-language", match.language)
-        },
-      }),
+  return defineContextPlugin<{ language: L[number]; languageMatch: LanguageMatch }>(
+    "language",
+    (app) =>
+      app
+        .derive((c) => {
+          const match = pickLanguage(c.header("accept-language"), supported, defaultLanguage)
+          // `pickLanguage` only ever returns a member of `supported` (or `defaultLanguage`), so the
+          // narrower literal union is the honest type for handlers to switch on.
+          return { language: match.language as L[number], languageMatch: match }
+        })
+        .use({
+          onResponseHeaders(headers, req) {
+            if (!emitHeader) return
+            if (headers.has("content-language")) return
+            const match = pickLanguage(req.header("accept-language"), supported, defaultLanguage)
+            headers.set("content-language", match.language)
+          },
+        }),
   )
 }

package/src/logger.ts

@@ -1,4 +1,4 @@
-import { definePlugin, pathnameOf } from "@nifrajs/core/server"
+import { defineIdentityPlugin, type IdentityPlugin, pathnameOf } from "@nifrajs/core/server"
 
 /** Structured fields logged per request. */
 export interface RequestLogFields {
@@ -15,18 +15,22 @@ export interface LoggerOptions {
 }
 
 /**
- * A {@link definePlugin} plugin that logs one structured line per request - method, path, status,
- * and duration - via `onRequest`/`onResponse` (so it covers 404s and errors too). The start time is
- * paired to the request through a `WeakMap` (no per-request allocation leak). Idempotent.
+ * A {@link defineIdentityPlugin} plugin that logs one structured line per request - method, path,
+ * status, and duration - via `onRequest`/`onResponse` (so it covers 404s and errors too). The start
+ * time is paired to the request through a `WeakMap` (no per-request allocation leak). Idempotent.
+ *
+ * It adds no context and registers no routes, so it is type-identity: routes declared after
+ * `.use(logger())` keep their types. (Under `definePlugin` they would not - see that helper's
+ * FOOTGUN note.)
  */
-export function logger(options: LoggerOptions = {}) {
+export function logger(options: LoggerOptions = {}): IdentityPlugin {
   // A request logger's whole job is to log; the default writes JSON to stdout, routable via `log`.
   const sink = options.log ?? ((fields: RequestLogFields) => console.log(JSON.stringify(fields)))
   const starts = new WeakMap<Request, number>()
   // Twin-side starts, keyed by the NodeRequestContext identity (the same object reaches the request
   // and response twins), so Node logging never has to materialize a Web `Request`.
   const nativeStarts = new WeakMap<object, number>()
-  return definePlugin("logger", (app) =>
+  return defineIdentityPlugin("logger", (app) =>
     app.use({
       onRequest(req) {
         starts.set(req, performance.now())

package/src/method-override.ts

@@ -1,4 +1,4 @@
-import { definePlugin, METHODS, type Method } from "@nifrajs/core/server"
+import { defineRouterPlugin, METHODS, type Method } from "@nifrajs/core/server"
 import { jsonError } from "./_utils.ts"
 
 export interface MethodOverrideOptions {
@@ -54,7 +54,7 @@ export function methodOverride(options: MethodOverrideOptions = {}) {
   if (header !== false && header.trim() === "") throw new Error("methodOverride: header is empty")
   if (query !== false && query.trim() === "") throw new Error("methodOverride: query is empty")
 
-  return definePlugin("methodOverride", (app) =>
+  return defineRouterPlugin("methodOverride", (app) =>
     app.onRequest((req) => {
       if (!sourceMethods.has(req.method.toUpperCase())) return undefined
 

package/src/openapi.ts

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { defineRouterPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 // The OpenAPI generator only - `@nifrajs/schema/openapi` is pure (no TypeBox runtime), so the openapi()
 // plugin gets full `t`-schema introspection without pulling the `t` builder into every consumer.
 import { toOpenAPI } from "@nifrajs/schema/openapi"
@@ -140,14 +140,16 @@ function scalarPage(specUrl: string, title: string, cdn: string): string {
  * app.use(openapi({ info: { title: "My API", version: "1.0.0" }, ui: true }))
  * ```
  */
-export function openapi(options: OpenApiOptions = {}) {
+export function openapi(options: OpenApiOptions = {}): IdentityPlugin {
   const docPath = options.path ?? "/openapi.json"
   const ui: OpenApiUiOptions | undefined =
     options.ui === true ? {} : options.ui === false ? undefined : options.ui
   const uiPath = ui !== undefined ? (ui.path ?? "/reference") : undefined
   let cached: string | undefined
   let uiCached: string | undefined
-  return definePlugin("openapi", (app) => {
+  // A router plugin: it serves the spec (and optionally the UI page) as a side effect and returns the
+  // app type-unchanged, so every route declared after `.use(openapi())` keeps its types.
+  return defineRouterPlugin("openapi", (app) => {
     // Capture `app` (the same mutable builder every later `.get()`/`.post()` registers on) and read its
     // routes lazily, at request time - so all routes exist regardless of where the plugin sits.
     app.register("GET", docPath, undefined, () => {

package/src/pretty-json.ts

@@ -1,4 +1,4 @@
-import { definePlugin, type NodeRequestContext } from "@nifrajs/core/server"
+import { defineRouterPlugin, type NodeRequestContext } from "@nifrajs/core/server"
 
 export interface PrettyJsonOptions {
   /** JSON indentation spaces. Default `2`. */
@@ -113,7 +113,7 @@ export function prettyJson(options: PrettyJsonOptions = {}) {
 
   const decoder = new TextDecoder()
   const encoder = new TextEncoder()
-  return definePlugin("prettyJson", (app) =>
+  return defineRouterPlugin("prettyJson", (app) =>
     app.use({
       onResponseBody(body, headers, req) {
         if (!isEnabled(req)) return undefined

package/src/problem-details.ts

@@ -1,4 +1,4 @@
-import { definePlugin, pathnameOf } from "@nifrajs/core/server"
+import { defineRouterPlugin, pathnameOf } from "@nifrajs/core/server"
 
 const JSON_TYPE = /^(?:application\/json|[^/]+\/[^;]+\+json)(?:\s*;|$)/i
 const DEFAULT_MAX_BYTES = 64 * 1024
@@ -144,7 +144,7 @@ export function problemDetails(options: ProblemDetailsOptions = {}) {
   const instance = options.includeInstance === true
   const typeBase = options.typeBase
 
-  return definePlugin("problemDetails", (app) =>
+  return defineRouterPlugin("problemDetails", (app) =>
     app.use({
       onResponseBody(body, headers, req, status) {
         if (

package/src/rate-limit.ts

@@ -1,6 +1,6 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import type { Middleware, NodeRequestContext, NodeResponseContext } from "@nifrajs/core/server"
-import { withHeaders, withNodeHeaders } from "./_utils.ts"
+import { setNodeHeader, withHeaders } from "./_utils.ts"
 
 export interface RateLimitResult {
   /** Hits recorded in the current window, including this one. */
@@ -301,13 +301,11 @@ export function rateLimit(options: RateLimitOptions): Middleware {
             const info = nativeQuota.get(req)
             if (info === undefined) return
             nativeQuota.delete(req)
-            withNodeHeaders(res, (headers) => {
-              // Lowercase on purpose: the Web path's `Headers` lowercases names on the wire, so
-              // this is byte-identical output.
-              headers["ratelimit-limit"] = String(max)
-              headers["ratelimit-remaining"] = String(info.remaining)
-              headers["ratelimit-reset"] = String(info.resetSeconds)
-            })
+            // Lowercase on purpose: the Web path's `Headers` lowercases names on the wire, so this
+            // is byte-identical output.
+            setNodeHeader(res, "ratelimit-limit", String(max))
+            setNodeHeader(res, "ratelimit-remaining", String(info.remaining))
+            setNodeHeader(res, "ratelimit-reset", String(info.resetSeconds))
           },
         }
       : {}),