@nifrajs/middleware 4.0.2 → 5.0.0

package/src/basic-auth.ts

@@ -3,6 +3,7 @@ import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 import {
   decodeBase64,
   guardName,
+  installAuthGuard,
   jsonError,
   type MaybePromise,
   quotedHeaderValue,
@@ -39,9 +40,9 @@ function reject(realm: string): Response {
   return jsonError(401, "unauthorized", { "www-authenticate": challenge(realm) })
 }
 
-function credentials(request: Request): { username: string; password: string } | null {
-  const header = request.headers.get("authorization")
-  if (header?.startsWith("Basic ") !== true) return null
+function credentials(header: string | null): { username: string; password: string } | null {
+  // The auth-scheme is case-insensitive (RFC 9110 section 11.1): `basic` and `BASIC` are Basic too.
+  if (header == null || header.slice(0, 6).toLowerCase() !== "basic ") return null
   const raw = decodeBase64(header.slice(6).trim())
   if (raw === null) return null
   let decoded: string
@@ -89,16 +90,17 @@ export function basicAuth<P>(
       : staticVerifier(options.username, options.password, options.principal ?? options.username)
 
   const plugin = defineIdentityPlugin(guardName("basicAuth"), (app) =>
-    app.beforeHandle(async (c: { readonly req: Request }) => {
-      const parsed = credentials(c.req)
-      const principal =
-        parsed === null ? null : await (await verifyPromise)(parsed.username, parsed.password)
-      if (principal !== null && principal !== undefined) {
-        store.set(c.req, principal)
-        return undefined
-      }
-      return optional ? undefined : reject(realm)
-    }),
+    installAuthGuard(
+      app,
+      "basicAuth",
+      optional,
+      store,
+      async (header) => {
+        const parsed = credentials(header("authorization"))
+        return parsed === null ? null : (await verifyPromise)(parsed.username, parsed.password)
+      },
+      () => reject(realm),
+    ),
   )
   const instrumented = optional
     ? plugin

package/src/cache-control.ts

@@ -11,6 +11,9 @@ export interface CacheControlOptions {
   readonly respectExisting?: boolean
 }
 
+// Named per call, so a second, differently configured instance applies instead of being deduped.
+let instances = 0
+
 /**
  * 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).
@@ -31,7 +34,7 @@ export function cacheControl(
   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
-  return defineRouterPlugin("cacheControl", (app) => {
+  return defineRouterPlugin(`cacheControl#${++instances}`, (app) => {
     // A fixed directive needs nothing from the request beyond the method, so it ships as one
     // portable header hook. A dynamic directive's resolver takes a real `Request`, which only the
     // Web response walk carries - it keeps the full `onResponse` contract (and its cost).
@@ -51,7 +54,7 @@ export function cacheControl(
               if (respectExisting && res.headers.has("cache-control")) return res
               const directive = value(req)
               if (directive === undefined) return res
-              return withHeaders(res, (headers) => headers.set("cache-control", directive))
+              return withHeaders(res, (headers) => headers.set("cache-control", directive), req)
             },
           }
     return app.use(middleware)

package/src/cache.ts

@@ -1,4 +1,4 @@
-import type { Middleware } from "@nifrajs/core/server"
+import { isAuthenticatedRequest, type Middleware } from "@nifrajs/core/server"
 import { type MaybePromise, withHeaders } from "./_utils.ts"
 
 export interface CachedResponse {
@@ -66,7 +66,7 @@ export class MemoryResponseCache implements ResponseCacheStore {
 
 export interface CacheOptions {
   readonly store: ResponseCacheStore
-  /** Time to live in milliseconds. */
+  /** Maximum time to live in milliseconds; response freshness can shorten it. */
   readonly ttlMs: number
   /** Methods cached. Default `["GET", "HEAD"]`. */
   readonly methods?: readonly string[]
@@ -80,7 +80,8 @@ export interface CacheOptions {
   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`. */
+  /** Respect response private/no-store/no-cache and max-age/s-maxage freshness. Default `true`.
+   * Responses requiring validation bypass this cache, which has no revalidation transport. */
   readonly respectResponseCacheControl?: boolean
   /** Cache responses with `Set-Cookie`. Default `false`. */
   readonly cacheSetCookie?: boolean
@@ -89,7 +90,9 @@ export interface CacheOptions {
    * personalized response (RFC 9111 §3.5), or it would be replayed to other users. Leave this off unless
    * the cached route is genuinely the same for every caller. */
   readonly cacheAuthenticated?: boolean
-  /** Credential headers that make a request private. Defaults to Authorization, Cookie, and x-api-key. */
+  /** Credential headers that make a request private. Defaults to Authorization, Cookie, and x-api-key.
+   * A response to a request an authentication stage accepted (or an integration marked with
+   * `markAuthenticatedRequest`) is treated as private too, whichever header carried the credential. */
   readonly authenticatedHeaders?: readonly string[]
   /** Response header for cache status. Default `"x-nifra-cache"`; set `false` to disable. */
   readonly cacheStatusHeader?: string | false
@@ -107,10 +110,30 @@ function cacheControlHas(headers: Headers, names: readonly string[]): boolean {
   const parts = value
     .toLowerCase()
     .split(",")
-    .map((part) => part.trim().split("=", 1)[0])
+    .map((part) => part.trim().split("=", 1)[0]?.trim())
   return names.some((name) => parts.includes(name))
 }
 
+function responseLifetimeMs(headers: Headers, ttlMs: number): number {
+  if (cacheControlHas(headers, ["private", "no-store", "no-cache"])) return 0
+  const directives = headers.get("cache-control")?.split(",") ?? []
+  // This is a shared cache: s-maxage takes precedence over max-age. Ambiguous freshness is stale.
+  for (const name of ["s-maxage", "max-age"]) {
+    const matches = directives.filter(
+      (part) => part.trim().split("=", 1)[0]?.trim().toLowerCase() === name,
+    )
+    if (matches.length === 0) continue
+    if (matches.length !== 1) return 0
+    const raw = matches[0]?.slice(matches[0].indexOf("=") + 1).trim() ?? ""
+    const value = raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw
+    const seconds = parseLength(value)
+    if (seconds === undefined || !Number.isFinite(seconds)) return 0
+    const age = parseLength(headers.get("age")) ?? 0
+    return Math.min(ttlMs, Math.max(0, seconds - age) * 1000)
+  }
+  return ttlMs
+}
+
 function appendVary(headers: Headers, vary: readonly string[]): void {
   if (vary.length === 0) return
   const existing = headers
@@ -257,9 +280,10 @@ function withStatusHeader(
   res: Response,
   header: string | false,
   status: "HIT" | "MISS" | "BYPASS",
+  request?: Request,
 ): Response {
   if (header === false) return res
-  return withHeaders(res, (headers) => headers.set(header, status))
+  return withHeaders(res, (headers) => headers.set(header, status), request)
 }
 
 /**
@@ -308,25 +332,33 @@ export function cache(options: CacheOptions): Middleware {
       requestKeys.set(req, key)
       const entry = await store.get(key)
       if (entry === undefined) return undefined
+      const cachedHeaders = new Headers([...entry.headers])
       // Never replay a personalized entry before route-scoped authentication runs. Public entries
       // remain eligible (and are explicitly marked by their response Cache-Control metadata).
       if (
         !cacheAuthenticated &&
         hasAuthentication(req) &&
-        !cacheControlHas(new Headers(entry.headers as Array<[string, string]>), [
-          "public",
-          "s-maxage",
-        ])
+        !cacheControlHas(cachedHeaders, ["public", "s-maxage"])
       ) {
         return undefined
       }
-      if (Date.now() >= entry.expiresAt) {
+      const lifetimeMs = respectResponseCacheControl
+        ? responseLifetimeMs(cachedHeaders, ttlMs)
+        : ttlMs
+      if (
+        lifetimeMs === 0 ||
+        Date.now() >= Math.min(entry.expiresAt, entry.storedAt + lifetimeMs)
+      ) {
         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))))
+      const headers = cachedHeaders
+      const age = parseLength(headers.get("age")) ?? 0
+      headers.set(
+        "age",
+        String(age + 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,
@@ -343,46 +375,54 @@ export function cache(options: CacheOptions): Middleware {
       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")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
-      if (respectResponseCacheControl && cacheControlHas(res.headers, ["private", "no-store"])) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      const lifetimeMs = respectResponseCacheControl
+        ? responseLifetimeMs(res.headers, ttlMs)
+        : ttlMs
+      if (lifetimeMs === 0) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       if (!cacheSetCookie && res.headers.has("set-cookie")) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       // A response-declared Vary must be represented in the lookup key. If the caller did not opt
       // those request headers into `vary`, bypass storage instead of replaying one representation to
       // another request. `Vary: *` is never cacheable by a shared cache.
       if (!responseVaryMatchesKey(res.headers, vary)) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       // Shared-cache safety (RFC 9111 §3.5): never store a response to an authenticated request
-      // (Authorization or Cookie) unless it's explicitly public - otherwise a personalized 200 leaks
-      // across users. Opt in with `cacheAuthenticated: true` for a route that's the same for everyone.
+      // unless it's explicitly public - otherwise a personalized 200 leaks across users. A credential
+      // header outside `authenticatedHeaders` is caught by the authentication stage that accepted it,
+      // because a hit is served before that stage runs. Opt in with `cacheAuthenticated: true` for a
+      // route that's the same for everyone.
       if (
         !cacheAuthenticated &&
-        hasAuthentication(req) &&
+        (hasAuthentication(req) || isAuthenticatedRequest(req)) &&
         !cacheControlHas(res.headers, ["public", "s-maxage"])
       ) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       const declared = parseLength(res.headers.get("content-length"))
       if (declared !== undefined && declared > maxBytes) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
+      const storedAt = Date.now()
       const captured = await readBytesCapped(res, maxBytes)
       if (!("bytes" in captured)) {
-        return withStatusHeader(captured.response, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(captured.response, cacheStatusHeader, "BYPASS", req)
       }
       const body = captured.bytes
       const capturedResponse = captured.response
+      const expiresAt = storedAt + lifetimeMs
+      if (Date.now() >= expiresAt) {
+        return withStatusHeader(capturedResponse, cacheStatusHeader, "BYPASS", req)
+      }
 
       const headers = new Headers(capturedResponse.headers)
-      headers.delete("age")
       if (cacheStatusHeader !== false) headers.delete(cacheStatusHeader)
       appendVary(headers, vary)
-      const now = Date.now()
       const key = requestKeys.get(req) ?? keyOf(req)
       requestKeys.delete(req)
       await store.set(key, {
@@ -390,8 +430,8 @@ export function cache(options: CacheOptions): Middleware {
         statusText: res.statusText,
         headers: [...headers.entries()],
         body,
-        expiresAt: now + ttlMs,
-        storedAt: now,
+        expiresAt,
+        storedAt,
       })
       const outgoing = new Headers(capturedResponse.headers)
       appendVary(outgoing, vary)

package/src/compression.ts

@@ -179,10 +179,90 @@ async function compressRawBody(
     },
     cancel: (reason) => reader.cancel(reason),
   })
-  return new Response(source.pipeThrough(new CompressionStream("gzip")), {
-    status: response.status,
-    statusText: response.statusText,
-    headers: gzipHeaders(response.headers),
+  const zlib = zlibModule()
+  return new Response(
+    zlib === undefined
+      ? source.pipeThrough(new CompressionStream("gzip"))
+      : syncFlushedGzip(zlib, source),
+    {
+      status: response.status,
+      statusText: response.statusText,
+      headers: gzipHeaders(response.headers),
+    },
+  )
+}
+
+interface GzipStream {
+  write(chunk: Uint8Array): boolean
+  flush(kind: number, callback: () => void): void
+  end(): void
+  destroy(): void
+  on(event: "data", listener: (chunk: Uint8Array) => void): unknown
+  once(event: "end" | "error", listener: (error?: unknown) => void): unknown
+}
+
+interface Zlib {
+  createGzip(): GzipStream
+  readonly constants: { readonly Z_SYNC_FLUSH: number }
+}
+
+const isZlib = (value: unknown): value is Zlib =>
+  typeof value === "object" &&
+  value !== null &&
+  "createGzip" in value &&
+  typeof value.createGzip === "function" &&
+  "constants" in value &&
+  typeof value.constants === "object" &&
+  value.constants !== null &&
+  "Z_SYNC_FLUSH" in value.constants
+
+let zlibLookup: { readonly zlib: Zlib | undefined } | undefined
+
+function zlibModule(): Zlib | undefined {
+  if (zlibLookup !== undefined) return zlibLookup.zlib
+  let zlib: Zlib | undefined
+  try {
+    const proc: unknown = Reflect.get(globalThis, "process")
+    const load: unknown =
+      typeof proc === "object" && proc !== null ? Reflect.get(proc, "getBuiltinModule") : undefined
+    const module: unknown = typeof load === "function" ? load.call(proc, "node:zlib") : undefined
+    if (isZlib(module)) zlib = module
+  } catch {}
+  zlibLookup = { zlib }
+  return zlib
+}
+
+/** `CompressionStream` holds deflate output until its window fills or the input closes, so a
+ * streamed shell would not reach the client until the whole page did. A sync flush after each
+ * upstream chunk emits what that chunk compressed to, at the cost of a few bytes per flush. */
+function syncFlushedGzip(
+  zlib: Zlib,
+  source: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const reader = source.getReader()
+  const gzip = zlib.createGzip()
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      gzip.on("data", (chunk) => controller.enqueue(chunk))
+      gzip.once("error", (error) => controller.error(error))
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read()
+      if (done) {
+        await new Promise((resolve) => {
+          gzip.once("end", resolve)
+          gzip.end()
+        })
+        controller.close()
+        return
+      }
+      gzip.write(value)
+      await new Promise<void>((resolve) => gzip.flush(zlib.constants.Z_SYNC_FLUSH, resolve))
+    },
+    cancel(reason) {
+      gzip.destroy()
+      return reader.cancel(reason)
+    },
   })
 }
 

package/src/conditional.ts

@@ -55,10 +55,14 @@ export function conditionalResponse(
   if (response.status < 200 || response.status >= 300) return response
   if (!isFresh(request, options)) {
     if (options.etag === undefined && modified === undefined) return response
-    return withHeaders(response, (headers) => {
-      if (options.etag !== undefined) headers.set("etag", options.etag)
-      if (modified !== undefined) headers.set("last-modified", modified)
-    })
+    return withHeaders(
+      response,
+      (headers) => {
+        if (options.etag !== undefined) headers.set("etag", options.etag)
+        if (modified !== undefined) headers.set("last-modified", modified)
+      },
+      request,
+    )
   }
   const headers = new Headers(response.headers)
   if (options.etag !== undefined) headers.set("etag", options.etag)

package/src/content-negotiation.ts

@@ -37,7 +37,9 @@ function parseMediaType(value: string, qDefault = 1): ParsedMediaType | undefine
   if (slash <= 0 || slash === media.length - 1) return undefined
   const type = media.slice(0, slash)
   const subtype = media.slice(slash + 1)
-  if (!/^[\w!#$&^_.+-]+$/.test(type) || !/^[\w!#$&^_.+*-]+$/.test(subtype)) return undefined
+  // `*/*` is the one legal type wildcard; `*/json` names no media range.
+  const typeOk = type === "*" ? subtype === "*" : /^[\w!#$&^_.+-]+$/.test(type)
+  if (!typeOk || !/^[\w!#$&^_.+*-]+$/.test(subtype)) return undefined
 
   let q = qDefault
   const parameters = new Map<string, string>()

package/src/csrf.ts

@@ -1,5 +1,6 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { isSameOriginRequest, METHODS, type Middleware } from "@nifrajs/core/server"
+import { isRegistrableMethod } from "@nifrajs/core/methods"
+import { isSameOriginRequest, type Middleware } from "@nifrajs/core/server"
 import {
   base64UrlEncode,
   guardName,
@@ -78,6 +79,10 @@ function originAllowed(req: Request, origins: Set<string> | undefined): boolean
   const allows = (candidate: string): boolean =>
     origins !== undefined ? origins.has(candidate) : isSameOriginRequest(candidate, req)
   const origin = req.headers.get("origin")
+  // Under `Referrer-Policy: no-referrer` a browser sends a same-origin form POST with `Origin: null`;
+  // its own `Sec-Fetch-Site` still says same-origin, and page script can set neither header.
+  if (origin === "null" && origins === undefined)
+    return req.headers.get("sec-fetch-site") === "same-origin"
   if (origin !== null) return allows(origin)
 
   const referer = req.headers.get("referer")
@@ -170,7 +175,7 @@ export async function createCsrfToken(secret: CsrfSecret, nonce?: string): Promi
 export async function verifyCsrfToken(token: string, secret: CsrfSecret): Promise<boolean> {
   const keys = csrfKeys(secret)
   const parts = token.split(".")
-  // @nifra-gate-reviewed: TOKEN_PREFIX is a public, non-secret format tag; this equality is a shape
+  // nifra-expect NF-S002: TOKEN_PREFIX is a public, non-secret format tag; this equality is a shape
   // check that short-circuits malformed input. The secret comparison is the constant-time
   // verifyHmacSha256 over the signature below.
   if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX || parts[1] === "" || parts[2] === "") {
@@ -230,9 +235,8 @@ export function csrf(options: CsrfOptions): Middleware {
     scope: "global",
     // Middleware may intentionally mention methods the Nifra router does not expose (for example
     // TRACE). Keep runtime behavior unchanged, but publish evidence only for registerable routes.
-    methods:
-      options.methods === undefined
-        ? ["POST", "PUT", "PATCH", "DELETE"]
-        : METHODS.filter((method) => methods?.has(method)),
+    ...(methods === undefined
+      ? { exceptMethods: [...SAFE_METHODS].filter(isRegistrableMethod) }
+      : { methods: [...methods].filter(isRegistrableMethod) }),
   })
 }

package/src/healthcheck.ts

@@ -14,6 +14,9 @@ export interface HealthcheckOptions {
 
 const noStore = { "cache-control": "no-store" } as const
 
+// Named per call, so a second, differently configured instance applies instead of being deduped.
+let instances = 0
+
 /**
  * Register **liveness** (`/health`) and **readiness** (`/ready`) endpoints. Liveness is a flat `200`
  * (the process is serving). Readiness runs each `check` and returns `200 { status: "ok", checks }`
@@ -34,7 +37,7 @@ export function healthcheck(options: HealthcheckOptions = {}): IdentityPlugin {
   // 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) => {
+  return defineRouterPlugin(`healthcheck#${++instances}`, (app) => {
     app.register("GET", path, undefined, () =>
       Response.json({ status: "ok" }, { headers: noStore }),
     )

package/src/idempotency.ts

@@ -1,5 +1,10 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { METHODS, type Middleware, replacedRequestOf } from "@nifrajs/core/server"
+import {
+  isAuthenticatedRequest,
+  METHODS,
+  type Middleware,
+  replacedRequestOf,
+} from "@nifrajs/core/server"
 
 /**
  * Idempotency keys for unsafe requests - a client retrying a `POST` (dropped connection, impatient
@@ -192,8 +197,11 @@ export interface IdempotencyOptions {
   readonly maxBytes?: number
   /**
    * 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.
+   * 408, 409, 425, and 429, and the request rejections 400, 404, 405, 413, 414, 415, 422 and 431.
+   * Like a transient 5xx, those say the operation did not run: replaying one would refuse every
+   * retry under that key until it expired, and storing a rejection lets a caller fill the store
+   * with keys sent to a route that does not exist. A handler that answers 400 or 422 after a side
+   * effect should supply its own predicate.
    */
   readonly shouldCache?: (response: Response) => boolean
   /**
@@ -218,12 +226,19 @@ export interface IdempotencyOptions {
    * 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.
+   *
+   * A request that carries none of these headers is keyed as anonymous. If an authentication stage
+   * then accepts it (a credential in another header), its response is not stored: under the
+   * anonymous key any caller presenting the same `Idempotency-Key` would be replayed it. Add that
+   * header here to dedupe such requests.
    */
   readonly principalHeaders?: readonly string[]
 }
 
 const DEFAULT_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const
-const NOT_THE_OPERATIONS_ANSWER = new Set([401, 403, 408, 409, 425, 429])
+const NOT_THE_OPERATIONS_ANSWER = new Set([
+  400, 401, 403, 404, 405, 408, 409, 413, 414, 415, 422, 425, 429, 431,
+])
 const DAY_MS = 24 * 60 * 60 * 1000
 
 function assertPositiveTtl(value: number, name: string): void {
@@ -440,7 +455,10 @@ 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, { readonly key: string; readonly reservation: string }>()
+  const claimed = new WeakMap<
+    Request,
+    { readonly key: string; readonly reservation: string; readonly anonymous: boolean }
+  >()
 
   const middleware: Middleware = {
     name: "idempotency",
@@ -472,7 +490,9 @@ export function idempotency(options: IdempotencyOptions): Middleware {
         })
       }
       if (claim.state !== "new") return undefined
-      claimed.set(req, { key, reservation: claim.reservation })
+      const anonymous =
+        custom === undefined && principalHeaders.every((name) => req.headers.get(name) === null)
+      claimed.set(req, { key, reservation: claim.reservation, anonymous })
       return undefined
     },
     async onResponse(res, req) {
@@ -486,7 +506,10 @@ export function idempotency(options: IdempotencyOptions): Middleware {
       }
       if (claim === undefined || claimedReq === undefined) return res // not a claimed request
       claimed.delete(claimedReq)
-      if (!shouldCache(res)) {
+      if (
+        !shouldCache(res) ||
+        (claim.anonymous && (isAuthenticatedRequest(req) || isAuthenticatedRequest(claimedReq)))
+      ) {
         await store.release(claim.key, claim.reservation)
         return res
       }

package/src/index.ts

@@ -127,7 +127,10 @@ export {
   type RateLimitOptions,
   type RateLimitResult,
   type RateLimitStore,
+  type RateLimitTier,
+  type RateLimitTiersOptions,
   rateLimit,
+  rateLimitTiers,
 } from "./rate-limit.ts"
 export { type RequestIdOptions, requestId } from "./request-id.ts"
 export { type SecurityHeadersOptions, securityHeaders } from "./security-headers.ts"