@nxtedition/nxt-undici 7.4.1 → 7.4.3

package/lib/interceptor/cache.js

@@ -1,18 +1,142 @@
 import undici from '@nxtedition/undici'
+import { stringify } from 'fast-querystring'
 import {
   DecoratorHandler,
-  getFastNow,
   isStream,
   parseCacheControl,
   parseContentRange,
+  parseHeaders,
+  parseHttpDate,
 } from '../utils.js'
+import { isHopByHop } from './proxy.js'
 import { SqliteCacheStore } from '../sqlite-cache-store.js'
 
 let DEFAULT_STORE = null
 const DEFAULT_MAX_ENTRY_SIZE = 128 * 1024
-const DEFAULT_MAX_ENTRY_TTL = 30 * 24 * 3600
+const DEFAULT_MAX_ENTRY_TTL = 30 * 24 * 3600 // seconds
+// RFC 8246 'immutable' has no lifetime of its own; this is the customary
+// 1-year default, capped by maxEntryTTL below.
+const IMMUTABLE_LIFETIME = 31556952 // seconds
 const NOOP = () => {}
 
+/**
+ * Explicit (or opt-in heuristic) freshness lifetime in seconds, or null when
+ * the response carries no usable expiration information. RFC 9111 §4.2.1
+ * priority for a shared cache: s-maxage > max-age > Expires. immutable
+ * (RFC 8246) and the opt-in heuristics only apply when no explicit lifetime
+ * is present. `explicit` marks origin-provided expiration — required for the
+ * stale-on-arrival store-and-revalidate path (never keep heuristically-stale
+ * content around for revalidation).
+ *
+ * @returns {{ lifetime: number, explicit: boolean } | null}
+ */
+function determineLifetime(
+  statusCode,
+  headers,
+  cacheControlDirectives,
+  { heuristic, defaultTTL },
+  now,
+) {
+  const explicit = cacheControlDirectives['s-maxage'] ?? cacheControlDirectives['max-age']
+  if (explicit != null) {
+    return { lifetime: explicit, explicit: true }
+  }
+
+  if (headers.expires != null) {
+    // RFC 9111 §5.3: an invalid Expires (notably `Expires: 0`) means already
+    // expired — the parse failure must surface as lifetime 0, not fall through
+    // to heuristics. Arrays (duplicated, potentially conflicting Expires field
+    // lines) are treated the same way.
+    const expires = typeof headers.expires === 'string' ? parseHttpDate(headers.expires) : undefined
+    if (!expires) {
+      return { lifetime: 0, explicit: true }
+    }
+    const date = typeof headers.date === 'string' ? parseHttpDate(headers.date) : undefined
+    return {
+      lifetime: Math.floor((expires.getTime() - (date ? date.getTime() : now)) / 1000),
+      explicit: true,
+    }
+  }
+
+  if (cacheControlDirectives.immutable) {
+    return { lifetime: IMMUTABLE_LIFETIME, explicit: false }
+  }
+
+  // Heuristic freshness and defaultTTL are per-request client opt-ins and
+  // deliberately restricted to plain 200s — heuristically extending 206/307
+  // would cache partials and temporary redirects without origin consent.
+  if (statusCode === 200) {
+    if (heuristic && typeof headers['last-modified'] === 'string') {
+      // RFC 9111 §4.2.2 suggested heuristic: 10% of time since Last-Modified.
+      // §4.2.2 forbids heuristics when an explicit expiration exists; Expires
+      // was handled (including the invalid form) above, so this is reached
+      // only when none does.
+      const lastModified = parseHttpDate(headers['last-modified'])
+      if (lastModified && lastModified.getTime() < now) {
+        return { lifetime: Math.floor((now - lastModified.getTime()) / 10 / 1000), explicit: false }
+      }
+    }
+    if (typeof defaultTTL === 'number' && defaultTTL > 0) {
+      return { lifetime: defaultTTL, explicit: false }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Corrected initial age in whole seconds per RFC 9111 §4.2.3 (simplified):
+ * the larger of the Age header and the apparent age (receipt time minus the
+ * origin Date). A response relayed through intermediaries that don't add Age
+ * would otherwise get an over-extended TTL and be served stale.
+ */
+function determineAge(headers, now) {
+  const rawAge = headers.age
+  // A duplicated Age header arrives as an array; take the first value.
+  const rawAgeValue = Array.isArray(rawAge) ? rawAge[0] : rawAge
+  // RFC 9111 §5.1 Age is delta-seconds (1*DIGIT): require a pure integer so a
+  // malformed value like "5junk" isn't parseInt-coerced to 5 and used to
+  // backdate cachedAt / extend staleness.
+  const age =
+    typeof rawAgeValue === 'string' && /^\d+$/.test(rawAgeValue.trim())
+      ? parseInt(rawAgeValue, 10)
+      : 0
+  const date = typeof headers.date === 'string' ? parseHttpDate(headers.date) : undefined
+  const apparentAge = date ? Math.max(0, Math.floor((now - date.getTime()) / 1000)) : 0
+  return Math.max(age, apparentAge)
+}
+
+/**
+ * Computes the entry's absolute times, or null when it shouldn't be stored.
+ *
+ * cachedAt is backdated by the corrected initial age so all downstream age
+ * math (served Age header, freshness checks) reduces to `now - cachedAt`; the
+ * origin Age header is stripped before storing to match.
+ *
+ * This cache does not retain entries past freshness for revalidation, so
+ * deleteAt == staleAt: an entry is dropped by the store as soon as it goes
+ * stale, and the read path never serves a stale entry. (The staleAt column
+ * exists for forward compatibility with revalidation.) Everything is capped
+ * by maxEntryTTL, measured from the (backdated) cachedAt.
+ */
+function computeEntryTimes(lifetime, age, maxEntryTTL, now) {
+  if (!Number.isFinite(lifetime)) {
+    return null
+  }
+
+  const freshness = Math.min(lifetime, maxEntryTTL) // seconds
+  if (freshness - age <= 0) {
+    // Stale on arrival — not worth storing.
+    return null
+  }
+
+  const cachedAt = now - age * 1000
+  const staleAt = cachedAt + freshness * 1000
+  const deleteAt = staleAt
+
+  return { cachedAt, staleAt, deleteAt }
+}
+
 class CacheHandler extends DecoratorHandler {
   #key
   #value
@@ -20,8 +144,10 @@ class CacheHandler extends DecoratorHandler {
   #logger
   #maxEntrySize
   #maxEntryTTL
+  #heuristic
+  #defaultTTL
 
-  constructor(key, { store, logger, handler, maxEntrySize, maxEntryTTL }) {
+  constructor(key, { store, logger, handler, maxEntrySize, maxEntryTTL, heuristic, defaultTTL }) {
     super(handler)
 
     this.#key = key
@@ -30,6 +156,8 @@ class CacheHandler extends DecoratorHandler {
     this.#store = store
     this.#maxEntrySize = maxEntrySize ?? store.maxEntrySize ?? DEFAULT_MAX_ENTRY_SIZE
     this.#maxEntryTTL = maxEntryTTL ?? store.maxEntryTTL ?? DEFAULT_MAX_ENTRY_TTL
+    this.#heuristic = heuristic ?? false
+    this.#defaultTTL = defaultTTL ?? null
   }
 
   onConnect(abort) {
@@ -94,11 +222,30 @@ class CacheHandler extends DecoratorHandler {
 
     const cacheControlDirectives = parseCacheControl(headers['cache-control']) ?? {}
 
-    if (this.#key.headers.authorization && !cacheControlDirectives.public) {
-      return super.onHeaders(statusCode, headers, resume)
+    // RFC 9111 §3.5: a shared cache may store a response to a request with
+    // Authorization only when the response explicitly allows it: public,
+    // s-maxage, or must-revalidate (safe because such entries are never
+    // served stale without successful revalidation). Must stay in lockstep
+    // with the serve-side gate in the interceptor below. A duplicated
+    // (array) authorization header is refused outright.
+    const authorization = this.#key.headers.authorization
+    if (authorization != null) {
+      if (
+        typeof authorization !== 'string' ||
+        !(
+          cacheControlDirectives.public === true ||
+          cacheControlDirectives['s-maxage'] != null ||
+          cacheControlDirectives['must-revalidate'] === true
+        )
+      ) {
+        return super.onHeaders(statusCode, headers, resume)
+      }
     }
 
-    if (cacheControlDirectives.private || cacheControlDirectives['no-store']) {
+    // Unqualified private forbids shared-cache storage entirely; the
+    // qualified form (private="field") only forbids storing the listed
+    // fields, which are stripped below (RFC 9111 §5.2.2.7).
+    if (cacheControlDirectives['no-store'] || cacheControlDirectives.private === true) {
       return super.onHeaders(statusCode, headers, resume)
     }
 
@@ -113,15 +260,21 @@ class CacheHandler extends DecoratorHandler {
     if (
       cacheControlDirectives['must-revalidate'] ||
       cacheControlDirectives['proxy-revalidate'] ||
-      cacheControlDirectives['stale-while-revalidate'] ||
-      cacheControlDirectives['stale-if-error'] ||
-      cacheControlDirectives['no-cache']
+      cacheControlDirectives['stale-while-revalidate'] != null ||
+      cacheControlDirectives['stale-if-error'] != null ||
+      cacheControlDirectives['no-cache'] === true
     ) {
-      // TODO (fix): Support all cache control directives...
+      // These directives require origin revalidation, which this cache does
+      // not yet perform — so the responses are not stored (a follow-up adds
+      // conditional revalidation and turns these into stored-and-validated
+      // entries).
       return super.onHeaders(statusCode, headers, resume)
     }
 
-    const vary = {}
+    // Null prototype: selector names come from the response Vary header and
+    // request header names are caller-controlled — on a plain `{}` a
+    // `__proto__` key would hit the prototype setter and be silently dropped.
+    const vary = Object.create(null)
     if (headers.vary) {
       if (typeof headers.vary !== 'string') {
         return super.onHeaders(statusCode, headers, resume)
@@ -141,20 +294,23 @@ class CacheHandler extends DecoratorHandler {
       }
     }
 
-    const ttl = cacheControlDirectives.immutable
-      ? 31556952
-      : Number(cacheControlDirectives['s-maxage'] ?? cacheControlDirectives['max-age'])
-    if (!ttl || !Number.isFinite(ttl) || ttl <= 0) {
+    const now = Date.now()
+
+    const lifetimeInfo = determineLifetime(
+      statusCode,
+      headers,
+      cacheControlDirectives,
+      { heuristic: this.#heuristic, defaultTTL: this.#defaultTTL },
+      now,
+    )
+    if (lifetimeInfo == null) {
       return super.onHeaders(statusCode, headers, resume)
     }
 
-    // RFC 9111 §4.2.3: a response relayed by an upstream/shared cache may
-    // already be partway through its freshness lifetime. Subtract the
-    // advertised Age so we don't over-extend the TTL and serve stale content.
-    const age = Number(headers.age)
-    const lifetime = Math.min(ttl, this.#maxEntryTTL) - (Number.isFinite(age) && age > 0 ? age : 0)
-    if (lifetime <= 0) {
-      // Already stale on arrival — not worth caching.
+    const etag = typeof headers.etag === 'string' && isEtagUsable(headers.etag) ? headers.etag : ''
+    const age = determineAge(headers, now)
+    const times = computeEntryTimes(lifetimeInfo.lifetime, age, this.#maxEntryTTL, now)
+    if (times == null) {
       return super.onHeaders(statusCode, headers, resume)
     }
 
@@ -166,19 +322,70 @@ class CacheHandler extends DecoratorHandler {
     const end = contentRange ? contentRange.end : this.#key.method === 'HEAD' ? 0 : contentLength
 
     if (end == null || end - start <= this.#maxEntrySize) {
-      const cachedAt = Date.now()
+      // Snapshot the headers: the same object is delivered downstream to the
+      // caller (request() resolves with it before the body finishes), and the
+      // entry isn't serialized to the store until onComplete. Without a copy,
+      // any mutation the caller makes to res.headers while the body streams
+      // would be persisted into the shared cache and replayed to every later
+      // request. parseHeaders values are strings or string arrays, so a
+      // one-level copy with array values sliced is a full snapshot. Use
+      // Object.keys so only own enumerable header fields are copied — never
+      // inherited properties from the prototype chain. Null prototype: on a
+      // plain `{}` a header literally named `__proto__` would hit the
+      // Object.prototype setter instead of becoming a data property (silent
+      // drop / prototype-pollution vector).
+      //
+      // Stripped while copying (RFC 9111 §3.1): hop-by-hop fields, fields
+      // listed in the Connection header, fields named by qualified
+      // no-cache=/private= directives (§5.2.2.4/§5.2.2.7), and Age — cachedAt
+      // is backdated by the corrected initial age, so the served Age is fully
+      // recomputed and a stored Age would double-count.
+      const excludedHeaders = new Set(['age'])
+      const connection = headers.connection
+      if (typeof connection === 'string') {
+        for (const name of connection.split(',')) {
+          excludedHeaders.add(name.trim().toLowerCase())
+        }
+      } else if (Array.isArray(connection)) {
+        for (const line of connection) {
+          for (const name of `${line}`.split(',')) {
+            excludedHeaders.add(name.trim().toLowerCase())
+          }
+        }
+      }
+      if (Array.isArray(cacheControlDirectives['no-cache'])) {
+        for (const name of cacheControlDirectives['no-cache']) {
+          excludedHeaders.add(name)
+        }
+      }
+      if (Array.isArray(cacheControlDirectives.private)) {
+        for (const name of cacheControlDirectives.private) {
+          excludedHeaders.add(name)
+        }
+      }
+
+      const storedHeaders = Object.create(null)
+      for (const name of Object.keys(headers)) {
+        if (isHopByHop(name) || excludedHeaders.has(name.toLowerCase())) {
+          continue
+        }
+        const val = headers[name]
+        storedHeaders[name] = Array.isArray(val) ? val.slice() : val
+      }
+
       this.#value = {
         body: [],
         start,
         end,
-        deleteAt: cachedAt + lifetime * 1e3,
+        cachedAt: times.cachedAt,
+        staleAt: times.staleAt,
+        deleteAt: times.deleteAt,
         statusCode,
         statusMessage: '',
-        headers,
+        headers: storedHeaders,
         cacheControlDirectives,
-        etag: isEtagUsable(headers.etag) ? headers.etag : '',
+        etag,
         vary,
-        cachedAt,
         // Handler state.
         size: 0,
       }
@@ -220,95 +427,270 @@ class CacheHandler extends DecoratorHandler {
   }
 }
 
-export default () => (dispatch) => (opts, handler) => {
-  if (!opts.cache || opts.upgrade) {
-    return dispatch(opts, handler)
+/**
+ * RFC 9111 §4.4: a non-error response to an unsafe method invalidates the
+ * stored entries for the target URI and any same-origin Location /
+ * Content-Location URIs (undici PR #5514). Cross-origin targets are skipped —
+ * honoring an attacker-influenced Location against another origin's entries
+ * would be a cache-poisoning vector.
+ */
+class InvalidationHandler extends DecoratorHandler {
+  #key
+  #store
+  #logger
+
+  constructor(key, { store, logger, handler }) {
+    super(handler)
+    this.#key = key
+    this.#store = store
+    this.#logger = logger
   }
 
-  if (opts.method !== 'GET' && opts.method !== 'HEAD') {
-    return dispatch(opts, handler)
+  onHeaders(statusCode, headers, resume) {
+    if (statusCode >= 200 && statusCode <= 399) {
+      // Invalidation failures must never break the actual response. Deletes
+      // are idempotent, so a retry re-driving onHeaders is harmless.
+      try {
+        this.#invalidate(headers)
+      } catch (err) {
+        if (err.message === 'database is locked') {
+          this.#logger?.debug({ err }, 'failed to invalidate cache entry')
+        } else {
+          this.#logger?.error({ err }, 'failed to invalidate cache entry')
+        }
+      }
+    }
+    return super.onHeaders(statusCode, headers, resume)
   }
 
-  const rawCacheControl = opts?.headers?.['cache-control']
-  const cacheControlDirectives = parseCacheControl(rawCacheControl) ?? {}
-  // cache-control-parser does not recognise 'only-if-cached', so check the raw string.
-  const onlyIfCached =
-    typeof rawCacheControl === 'string' && rawCacheControl.includes('only-if-cached')
+  #invalidate(headers) {
+    this.#store.delete(this.#key)
 
-  // RFC 9111 Section 5.4: Pragma: no-cache should be treated as
-  // Cache-Control: no-cache when Cache-Control is absent.
-  if (rawCacheControl == null && opts?.headers?.pragma === 'no-cache') {
-    cacheControlDirectives['no-cache'] = true
-  }
+    const invalidated = new Set([this.#key.path])
+    let base
+    for (const name of ['location', 'content-location']) {
+      let value = headers[name]
+      if (Array.isArray(value)) {
+        value = value[0]
+      }
+      if (typeof value !== 'string' || value === '') {
+        continue
+      }
 
-  if (cacheControlDirectives['no-transform']) {
-    // Do nothing. We don't transform requests...
-  }
+      base ??= new URL(this.#key.path, this.#key.origin)
+      let target
+      try {
+        target = new URL(value, base)
+      } catch {
+        continue
+      }
+      if (target.origin !== base.origin) {
+        continue
+      }
 
-  if (
-    // != null: 'max-age=0' parses to 0 (falsy) but still demands revalidation.
-    cacheControlDirectives['max-age'] != null ||
-    cacheControlDirectives['no-cache'] ||
-    cacheControlDirectives['stale-if-error'] != null ||
-    // cache-control-parser does not recognise 'max-stale'/'min-fresh', so
-    // check the raw string like we do for 'only-if-cached'.
-    (typeof rawCacheControl === 'string' &&
-      (rawCacheControl.includes('max-stale') || rawCacheControl.includes('min-fresh')))
-  ) {
-    // TODO (fix): Support all cache control directives...
-    return dispatch(opts, handler)
+      const path = target.pathname + target.search
+      if (!invalidated.has(path)) {
+        invalidated.add(path)
+        this.#store.delete({ ...this.#key, path })
+      }
+    }
   }
+}
 
-  const store =
-    opts.cache.store ?? (DEFAULT_STORE ??= new SqliteCacheStore({ location: ':memory:' }))
+function getStore(opts) {
+  return opts.cache.store ?? (DEFAULT_STORE ??= new SqliteCacheStore({ location: ':memory:' }))
+}
 
-  // TODO (fix): enable range requests
+function tryGetEntry(store, key, logger) {
+  try {
+    return store.get(key)
+  } catch (err) {
+    if (err.message === 'database is locked') {
+      // Database is busy. We don't bother trying again...
+      logger?.debug({ err }, 'failed to get cache entry')
+    } else {
+      logger?.error({ err }, 'failed to get cache entry')
+    }
+  }
+}
 
+/**
+ * Builds the cache key shared by the get and set paths.
+ */
+function makeKey(opts) {
   // Build the key the same way for lookups and stores: makeCacheKey
   // stringifies the origin (e.g. URL objects), so using raw opts on the get
   // path while the set path normalizes would make the cache permanently miss.
-  const key = undici.util.cache.makeCacheKey(opts)
+  // The flat name/value array form of opts.headers (legal at the undici
+  // client level) makes makeCacheKey throw — normalize it through
+  // parseHeaders first (which also lowercases the names). Header names are
+  // caller-controlled, so parse into a null-prototype target: a `__proto__`
+  // name on a plain `{}` would hit the Object.prototype setter instead of
+  // becoming a data property.
+  const key = undici.util.cache.makeCacheKey(
+    Array.isArray(opts.headers)
+      ? { ...opts, headers: parseHeaders(opts.headers, Object.create(null)) }
+      : opts,
+  )
 
   // makeCacheKey preserves request header names verbatim. Vary selector names
-  // are lowercased (in onHeaders and matchesValue), so lowercase the key's
+  // are lowercased (in CacheHandler and matchesValue), so lowercase the key's
   // header names once here — the same key feeds both the get and set paths, so
   // this keeps Vary matching symmetric even when a caller supplies non-lowercase
   // header names (the standalone interceptors.cache() composition; the wrapped
   // pipeline already normalizes). A fresh object avoids mutating opts.headers.
+  // Header names are caller-controlled, so build a null-prototype map (a
+  // `__proto__` key on a plain object would silently overwrite the prototype
+  // instead of setting a property) and copy own keys only.
   if (key.headers && typeof key.headers === 'object') {
-    const lower = {}
-    for (const name in key.headers) {
+    const lower = Object.create(null)
+    for (const name of Object.keys(key.headers)) {
       lower[name.toLowerCase()] = key.headers[name]
     }
     key.headers = lower
   }
 
-  let entry
-  try {
-    entry = store.get(key)
-  } catch (err) {
-    if (err.message === 'database is locked') {
-      // Database is busy. We don't bother trying again...
-      opts.logger?.debug({ err }, 'failed to get cache entry')
-    } else {
-      opts.logger?.error({ err }, 'failed to get cache entry')
+  // The vendored makeCacheKey ignores opts.query. The wrapped pipeline is
+  // immune (the query interceptor rewrites path before the cache sees it),
+  // but a standalone interceptors.cache() composition would silently collide
+  // distinct query strings onto one entry and serve the wrong response
+  // (undici issue #4209 / PR #5081) — fold the query into the key path.
+  if (
+    opts.query &&
+    typeof key.path === 'string' &&
+    !key.path.includes('?') &&
+    !key.path.includes('#')
+  ) {
+    const qs = stringify(opts.query)
+    if (qs) {
+      key.path = `${key.path || '/'}?${qs}`
     }
   }
 
-  // RFC 9111 Section 3.5: A shared cache must not use a cached response to a
-  // request with Authorization unless the response includes a public directive.
-  if (entry && opts.headers?.authorization && !entry.cacheControlDirectives?.public) {
-    entry = undefined
+  return key
+}
+
+function cacheOptsOf(opts) {
+  return {
+    maxEntrySize: opts.cache.maxEntrySize,
+    maxEntryTTL: opts.cache.maxEntryTTL,
+    heuristic: opts.cache.heuristic,
+    defaultTTL: opts.cache.defaultTTL,
+  }
+}
+
+export default () => (dispatch) => (opts, handler) => {
+  if (!opts.cache || opts.upgrade) {
+    return dispatch(opts, handler)
   }
 
-  // RFC 9110 Section 13: Evaluate conditional request headers against cached entry.
+  if (opts.method !== 'GET' && opts.method !== 'HEAD') {
+    // RFC 9110 §9.2.1: OPTIONS and TRACE are safe — never cached, but they
+    // must not invalidate either. Every other method (POST/PUT/DELETE/...)
+    // invalidates the target URI on a non-error response (RFC 9111 §4.4).
+    if (opts.method === 'OPTIONS' || opts.method === 'TRACE') {
+      return dispatch(opts, handler)
+    }
+
+    const store = getStore(opts)
+    if (typeof store.delete !== 'function') {
+      // User-supplied store without invalidation support.
+      return dispatch(opts, handler)
+    }
+
+    return dispatch(
+      opts,
+      new InvalidationHandler(makeKey(opts), { store, logger: opts.logger, handler }),
+    )
+  }
+
+  // TODO (fix): enable range requests
+
+  const key = makeKey(opts)
+
+  // All request-directive and conditional-header guards below MUST read from
+  // the lowercased key.headers, not raw opts.headers — otherwise a caller
+  // supplying capitalized names (e.g. `Authorization`, `Cache-Control` via the
+  // standalone composition) would silently skip the guards while the store
+  // side (CacheHandler) reads the lowercased form, e.g. serving a non-public
+  // cached response to an authorized request (RFC 9111 §3.5).
+  const headers = key.headers ?? {}
+
+  const rawCacheControl = headers['cache-control']
+  const requestCacheControl = parseCacheControl(rawCacheControl) ?? {}
+
+  // RFC 9111 Section 5.4: Pragma: no-cache should be treated as
+  // Cache-Control: no-cache when Cache-Control is absent.
+  if (rawCacheControl == null && headers.pragma === 'no-cache') {
+    requestCacheControl['no-cache'] = true
+  }
+
+  if (requestCacheControl['no-transform']) {
+    // Do nothing. We don't transform requests...
+  }
+
+  const onlyIfCached = requestCacheControl['only-if-cached'] === true
+  const store = getStore(opts)
+
+  let entry = tryGetEntry(store, key, opts.logger)
+
+  // RFC 9111 §3.5 serve-side authorization gate: a shared cache must not
+  // reuse a stored response for a request with Authorization unless the
+  // response allowed it (public, s-maxage or must-revalidate — the mirror of
+  // the store-side gate in CacheHandler; both sites must stay in lockstep).
+  if (entry && headers.authorization != null) {
+    const directives = entry.cacheControlDirectives
+    if (
+      typeof headers.authorization !== 'string' ||
+      !(
+        directives?.public === true ||
+        directives?.['s-maxage'] != null ||
+        directives?.['must-revalidate'] === true
+      )
+    ) {
+      entry = undefined
+    }
+  }
+
+  const cacheHandler = () =>
+    new CacheHandler(key, {
+      ...cacheOptsOf(opts),
+      store,
+      logger: opts.logger,
+      handler,
+    })
+
+  // Request Cache-Control directives that this cache does not evaluate locally
+  // (a follow-up adds conditional revalidation and local evaluation) cause a
+  // bypass to the origin. These constrain REUSE of a stored response, not the
+  // storage of a fresh one — so the bypass still writes the origin response
+  // back through CacheHandler for later callers (undici PR #5510), unless the
+  // request's own no-store forbids storing. only-if-cached is the exception:
+  // it forbids contacting the origin, so it is handled from the cache below
+  // instead of bypassing.
+  const bypass =
+    !onlyIfCached &&
+    // != null: 'max-age=0' parses to 0 (falsy) but still demands revalidation.
+    (requestCacheControl['max-age'] != null ||
+      requestCacheControl['no-cache'] === true ||
+      requestCacheControl['stale-if-error'] != null ||
+      requestCacheControl['max-stale'] != null ||
+      requestCacheControl['min-fresh'] != null)
+
+  if (bypass) {
+    return dispatch(opts, requestCacheControl['no-store'] ? handler : cacheHandler())
+  }
+
+  // RFC 9110 Section 13: evaluate conditional request headers against the
+  // cached entry. The store only returns entries that are still fresh
+  // (deleteAt === staleAt), so a returned entry is always servable.
   // typeof guards: duplicated conditional headers arrive as arrays — treat
   // them as non-matching and bypass to origin rather than crashing.
-  if (entry && opts.headers?.['if-none-match']) {
+  if (entry && headers['if-none-match']) {
     if (
-      typeof opts.headers['if-none-match'] === 'string' &&
+      typeof headers['if-none-match'] === 'string' &&
       entry.etag &&
-      weakMatch(opts.headers['if-none-match'], entry.etag)
+      weakMatch(headers['if-none-match'], entry.etag)
     ) {
       return serveFromCache(
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
@@ -318,12 +700,12 @@ export default () => (dispatch) => (opts, handler) => {
     }
     // Etag didn't match — bypass to origin.
     entry = undefined
-  } else if (entry && opts.headers?.['if-modified-since']) {
+  } else if (entry && headers['if-modified-since']) {
     const lastModified = entry.headers?.['last-modified']
     if (
-      typeof opts.headers['if-modified-since'] === 'string' &&
+      typeof headers['if-modified-since'] === 'string' &&
       lastModified &&
-      new Date(lastModified) <= new Date(opts.headers['if-modified-since'])
+      new Date(lastModified) <= new Date(headers['if-modified-since'])
     ) {
       return serveFromCache(
         { statusCode: 304, headers: entry.headers, cachedAt: entry.cachedAt },
@@ -335,30 +717,19 @@ export default () => (dispatch) => (opts, handler) => {
     entry = undefined
   }
 
-  if (
-    opts.headers?.['if-match'] ||
-    opts.headers?.['if-unmodified-since'] ||
-    opts.headers?.['if-range']
-  ) {
+  if (headers['if-match'] || headers['if-unmodified-since'] || headers['if-range']) {
     // TODO (fix): evaluate these conditional headers against cached entry.
     return dispatch(opts, handler)
   }
 
   if (!entry && !onlyIfCached) {
-    return dispatch(
-      opts,
-      cacheControlDirectives['no-store']
-        ? handler
-        : new CacheHandler(key, {
-            maxEntrySize: opts.cache.maxEntrySize,
-            maxEntryTTL: opts.cache.maxEntryTTL,
-            store,
-            logger: opts.logger,
-            handler,
-          }),
-    )
+    // A miss keeps the CacheHandler write-back unless the request's no-store
+    // forbids storing.
+    return dispatch(opts, requestCacheControl['no-store'] ? handler : cacheHandler())
   }
 
+  // A hit (fresh, per the store) is served; only-if-cached with no usable
+  // entry yields 504 (RFC 9111 §5.2.1.7).
   return serveFromCache(entry ?? { statusCode: 504 }, opts, handler)
 }
 
@@ -367,13 +738,13 @@ function serveFromCache(entry, opts, handler) {
 
   let headers = entry.headers
   if (entry.cachedAt != null) {
-    // RFC 9111 §5.1: every response served from cache must carry an Age header
-    // reflecting time spent in this cache plus any age it arrived with —
-    // otherwise downstream caches treat it as fresh-from-origin.
-    // getFastNow has 1s resolution — Age is whole seconds, so that's enough.
-    const residentAge = Math.max(0, Math.floor((getFastNow() - entry.cachedAt) / 1000))
-    const originAge = Number(headers?.age)
-    const age = Number.isFinite(originAge) && originAge > 0 ? originAge + residentAge : residentAge
+    // RFC 9111 §5.1: every response served from cache must carry an Age
+    // header. cachedAt is backdated by the corrected initial age at store
+    // time (§4.2.3) and the origin's Age header is stripped, so resident time
+    // IS the response's age — no origin-Age addition. Date.now(), not
+    // getFastNow(): the lagging clock would understate a relayed response's
+    // initial age by up to a second.
+    const age = Math.max(0, Math.floor((Date.now() - entry.cachedAt) / 1000))
     headers = { ...headers, age: `${age}` }
   }