@nifrajs/web 5.5.0 → 5.6.0

package/src/isr.ts

@@ -9,7 +9,21 @@
 import { isAuthenticatedRequest, writableResponse } from "@nifrajs/core/server"
 import { readBoundedBytes, TransportCodecError } from "@nifrajs/core/transport-codec"
 import { isDraftEnabled } from "./draft.ts"
+import {
+  type InvalidationReport,
+  type InvalidationTargets,
+  runInvalidation,
+  settleInvalidation,
+} from "./internal/invalidation.ts"
+import { INVALIDATION, type InvalidationHandoff } from "./internal/invalidation-contract.ts"
+import {
+  isStoreSecret,
+  MIN_STORE_SECRET_LENGTH,
+  type StoreSigner,
+  storeSigner,
+} from "./internal/store-signature.ts"
 import { assertTokenSecret, timingSafeEqual } from "./internal/timing-safe-equal.ts"
+import { SWAP_HEADER } from "./render-seam.ts"
 
 /** A cached SSR response - the bytes + metadata a {@link CacheStore} persists. */
 export interface CachedResponse {
@@ -48,7 +62,9 @@ export interface CacheStore {
    * The current point in this store's purge order. `withISR` takes one before each render and hands it
    * back as {@link CachedResponse.fence}, and `set` skips that entry when its key or one of its tags
    * was purged after the point. Without it, a purge that lands while a page renders is undone when the
-   * render stores the page it built from data read before the purge.
+   * render stores the page it built from data read before the purge. A store whose purges reach other
+   * instances late must also check on read, as {@link KVCacheStore} does: `set` there cannot see a
+   * purge that has not arrived yet.
    */
   readonly fence?: () => number | Promise<number>
 }
@@ -94,6 +110,10 @@ export function serializeISRTags(tags: readonly string[]): string | undefined {
 /** What a `revalidateTags` function is given: the URL and route params only, both already public. */
 export interface RevalidateTagsInput {
   readonly params: Readonly<Record<string, string>>
+  /**
+   * The request's URL. On a partially prerendered route and its shared holes, the shell's: the
+   * configured origin, the path and the declared variations, never the visitor's Host or other query.
+   */
   readonly url: URL
 }
 
@@ -144,6 +164,9 @@ export interface MemoryCacheStoreOptions {
   readonly max?: number
 }
 
+// Nothing outside this process can write these, so `withISR` keeps their pages unsigned.
+const inProcessStores = new WeakSet<CacheStore>()
+
 /**
  * In-process ISR cache. Refuses to run in production unless explicitly allowed (mirrors the
  * rate-limit `MemoryStore` - a per-instance cache is unsafe across instances). Bounded **LRU**: a
@@ -177,6 +200,7 @@ export class MemoryCacheStore implements CacheStore {
     if (!Number.isSafeInteger(this.max) || this.max <= 0) {
       throw new RangeError("[nifra/web] MemoryCacheStore max must be a positive safe integer")
     }
+    inProcessStores.add(this)
   }
 
   get(key: string): Promise<CachedResponse | undefined> {
@@ -360,25 +384,15 @@ const isCachedResponse = (value: unknown): value is CachedResponse => {
 }
 
 const KV_TAG_EPOCH_PREFIX = "__nifra_isr_tag_v1:"
-const KV_PURGED_AT = "__nifraPurgedAt"
-
-/** When a KV page key was purged, from the marker `delete` leaves; `-Infinity` for a page or nothing. */
-function kvPurgedAt(raw: string | null): number {
-  if (raw === null || !raw.includes(KV_PURGED_AT)) return Number.NEGATIVE_INFINITY
-  try {
-    const parsed: unknown = JSON.parse(raw)
-    if (typeof parsed === "object" && parsed !== null && KV_PURGED_AT in parsed) {
-      const at = parsed[KV_PURGED_AT]
-      if (typeof at === "number") return at
-    }
-  } catch {
-    // Not a marker.
-  }
-  return Number.NEGATIVE_INFINITY
-}
-
-/** When a tag epoch was written (`<time>:<uuid>`); an epoch from before epochs carried a time is older
- * than any render. */
+const KV_PATH_EPOCH_PREFIX = "__nifra_isr_path_v1:"
+const KV_PATH_DIGEST_PREFIX = "__nifra_isr_path_v1#"
+/** Cloudflare KV's key limit, in UTF-8 bytes. */
+const KV_KEY_LIMIT = 512
+/** How long (seconds) a path epoch outlives the store's `expirationTtl`. */
+const PATH_EPOCH_SLACK = 86_400
+
+/** When a tag or path epoch was written (`<time>:<uuid>`); an epoch from before epochs carried a time
+ * is older than any render. */
 function kvEpochTime(epoch: string): number {
   const at = epoch.indexOf(":")
   const time = at === -1 ? Number.NaN : Number(epoch.slice(0, at))
@@ -395,8 +409,10 @@ const kvClock = (): number => {
   return lastKvTime
 }
 
-type StoredTaggedResponse = CachedResponse & {
+type StoredResponse = CachedResponse & {
   readonly __nifraTagEpochs?: Readonly<Record<string, string>>
+  /** Absent while the path was never purged. */
+  readonly __nifraPathEpoch?: string
 }
 
 /**
@@ -404,7 +420,8 @@ type StoredTaggedResponse = CachedResponse & {
  * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
  * hold *across* worker instances (unlike the per-instance {@link MemoryCacheStore}). Entries serialize
  * to JSON; every read is validated before it's trusted (a malformed/version-skewed entry is treated as
- * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`.
+ * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`,
+ * and give `withISR` the `storeSecret` it signs these pages with.
  *
  * Cloudflare is the default, not a requirement: {@link KVNamespaceLike} is three structural methods,
  * so a Redis, Deno KV, or Upstash binding satisfies it (pass `minExpirationTtl` for their TTL floor).
@@ -414,6 +431,7 @@ type StoredTaggedResponse = CachedResponse & {
 export class KVCacheStore implements CacheStore {
   private readonly kv: KVNamespaceLike
   private readonly putOptions: { readonly expirationTtl?: number } | undefined
+  private readonly pathEpochOptions: { readonly expirationTtl?: number } | undefined
 
   constructor(kv: KVNamespaceLike, options: KVCacheStoreOptions = {}) {
     const floor = options.minExpirationTtl ?? 60
@@ -441,10 +459,17 @@ export class KVCacheStore implements CacheStore {
     // Precompute the put options object once: omit it entirely when no TTL (KV then never expires).
     this.putOptions =
       options.expirationTtl !== undefined ? { expirationTtl: options.expirationTtl } : undefined
+    // An expired path epoch would make pages stored under the one it replaced read as current again.
+    // Those were stored before the purge reached their location, so they expire within the TTL plus
+    // that delay; without a TTL they never expire, and neither may the epoch.
+    this.pathEpochOptions =
+      options.expirationTtl !== undefined
+        ? { expirationTtl: options.expirationTtl + PATH_EPOCH_SLACK }
+        : undefined
   }
 
   async get(key: string): Promise<CachedResponse | undefined> {
-    const raw = await this.kv.get(key)
+    const [raw, pathEpoch] = await Promise.all([this.kv.get(key), this.pathEpoch(key)])
     if (raw === null) return undefined
     let parsed: unknown
     try {
@@ -454,52 +479,65 @@ export class KVCacheStore implements CacheStore {
       return undefined
     }
     if (!isCachedResponse(parsed)) return undefined
-    const tags = normalizeTags(parsed.tags)
-    if (tags.length === 0) return parsed
-    const epochs = (parsed as StoredTaggedResponse).__nifraTagEpochs
+    const {
+      __nifraTagEpochs: epochs,
+      __nifraPathEpoch: storedPathEpoch,
+      ...value
+    } = parsed as StoredResponse
+    // A page another location stored before this path's purge reached it keeps the older epoch.
+    if ((storedPathEpoch ?? "0") !== pathEpoch) return undefined
+    const tags = normalizeTags(value.tags)
+    if (tags.length === 0) return value
     if (epochs === undefined) return undefined
     const current = await Promise.all(
       tags.map(async (tag) => [tag, (await this.kv.get(this.tagKey(tag))) ?? "0"] as const),
     )
     if (current.some(([tag, epoch]) => epochs[tag] !== epoch)) return undefined
-    const { __nifraTagEpochs: _ignored, ...value } = parsed as StoredTaggedResponse
     return value
   }
 
-  /** Wall-clock time, so purges on any instance order against it. KV is eventually consistent, so the
-   * fence holds only for purges this location has already seen. */
+  /** Wall-clock time, so purges on any instance order against it. KV is eventually consistent, so
+   * `set` refuses only purges this location has already seen; a page stored before a purge reached
+   * its location keeps the older epoch and reads as a miss once the purge arrives. */
   fence(): number {
     return kvClock()
   }
 
   async set(key: string, value: CachedResponse): Promise<void> {
     const { fence, ...entry } = value
-    if (fence !== undefined && kvPurgedAt(await this.kv.get(key)) > fence) return
     const tags = normalizeTags(entry.tags)
-    if (tags.length === 0) {
-      await this.kv.put(key, JSON.stringify(entry), this.putOptions)
-      return
-    }
-    const epochs = Object.fromEntries(
-      await Promise.all(
-        tags.map(async (tag) => [tag, (await this.kv.get(this.tagKey(tag))) ?? "0"] as const),
-      ),
-    )
-    if (fence !== undefined && Object.values(epochs).some((epoch) => kvEpochTime(epoch) > fence)) {
+    const [pathEpoch, ...tagEpochs] = await Promise.all([
+      this.pathEpoch(key),
+      ...tags.map(async (tag) => (await this.kv.get(this.tagKey(tag))) ?? "0"),
+    ])
+    if (
+      fence !== undefined &&
+      [pathEpoch, ...tagEpochs].some((epoch) => kvEpochTime(epoch) > fence)
+    ) {
       return
     }
-    const stored: StoredTaggedResponse = {
+    const stored: StoredResponse = {
       ...entry,
-      tags,
-      __nifraTagEpochs: epochs,
+      ...(tags.length === 0
+        ? {}
+        : {
+            tags,
+            __nifraTagEpochs: Object.fromEntries(tags.map((tag, at) => [tag, tagEpochs[at]!])),
+          }),
+      ...(pathEpoch === "0" ? {} : { __nifraPathEpoch: pathEpoch }),
     }
     await this.kv.put(key, JSON.stringify(stored), this.putOptions)
   }
 
-  /** Leaves a marker rather than removing the key, so `set` can refuse a render that began before
-   * the purge. The marker reads as a miss. */
+  /** Moves the path's epoch and leaves the page: a page stored under the old epoch reads as a miss,
+   * even one another location stored before this purge reached it, and `set` refuses a render begun
+   * before the purge. */
   async delete(key: string): Promise<void> {
-    await this.kv.put(key, JSON.stringify({ [KV_PURGED_AT]: kvClock() }), this.putOptions)
+    await this.kv.put(
+      await this.pathKey(key),
+      `${kvClock()}:${crypto.randomUUID()}`,
+      this.pathEpochOptions,
+    )
   }
 
   async invalidateTag(tag: string): Promise<void> {
@@ -513,6 +551,21 @@ export class KVCacheStore implements CacheStore {
   private tagKey(tag: string): string {
     return `${KV_TAG_EPOCH_PREFIX}${encodeURIComponent(tag)}`
   }
+
+  /** The page key under a prefix, or its digest when that would pass KV's key limit. */
+  private async pathKey(key: string): Promise<string> {
+    const named = `${KV_PATH_EPOCH_PREFIX}${key}`
+    // A UTF-16 unit is at most three UTF-8 bytes, so most keys skip the encode.
+    if (named.length * 3 <= KV_KEY_LIMIT) return named
+    const encoder = new TextEncoder()
+    if (encoder.encode(named).byteLength <= KV_KEY_LIMIT) return named
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(key)))
+    return `${KV_PATH_DIGEST_PREFIX}${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")}`
+  }
+
+  private async pathEpoch(key: string): Promise<string> {
+    return (await this.kv.get(await this.pathKey(key))) ?? "0"
+  }
 }
 
 /** Minimal platform shape `withISR` needs - just `waitUntil` (edge runtimes extend the response
@@ -564,6 +617,19 @@ export function withoutCacheChannel(res: Response): Response {
 
 export interface ISROptions {
   readonly store: CacheStore
+  /**
+   * Signs every page written to `store` and checks the signature on every read, so whoever else can
+   * write the store (another service on the same KV namespace, a leaked token) cannot hand visitors a
+   * page this app did not render. Required for every store but a {@link MemoryCacheStore}, whose
+   * pages never leave the process and stay unsigned. The same in every process, at least 32
+   * characters, and random: generate it, such as 32 random bytes as hex, since a guessable secret
+   * can be found from any signed page and then signs pages of its own. A page whose signature is
+   * missing or wrong reads as a miss and renders again, so a new secret only empties the cache. It
+   * cannot stop a store writer from deleting pages, or from putting back an older page this app
+   * stored for the same key. That page keeps its age: still within its freshness window, it is a hit
+   * until the window ends; past it, it serves stale and regenerates.
+   */
+  readonly storeSecret?: string
   /** Default freshness window (**seconds**) for a cached page; older ⇒ stale (served, regenerated
    * behind). A route overrides it per-page via `export const revalidate` (surfaced as the
    * `x-nifra-isr-revalidate` response header). */
@@ -574,7 +640,10 @@ export interface ISROptions {
    * so host-routed apps do not share entries across tenants. Return `null` to bypass the cache for
    * this request (it goes straight to the app, uncached). Replaces `query` entirely. Under the default
    * key a request carrying `Authorization` or a cookie outside `anonymousCookies` never reads the
-   * store; a custom key takes that decision over, so include whatever identifies the visitor in it. */
+   * store; a custom key takes that decision over, so include whatever identifies the visitor in it.
+   * An action's `revalidate(paths)` keys each path with the action request's own headers, so it purges
+   * the variant that client reads; a variant keyed on another header value (another language) is not
+   * reached - tag those pages and revalidate the tag. */
   readonly key?: (req: Request) => string | null
   /**
    * Cookie names that never change the page, such as a consent or analytics cookie. Under the default
@@ -597,10 +666,11 @@ export interface ISROptions {
    * fresh, and a draft render is never written to the store (it can't poison the public cache). */
   readonly draftSecret?: string
   /**
-   * Called when a store call fails: it throws, rejects, or outlives {@link storeTimeoutMs}. The request
-   * is served without the cache either way - a failed read is a miss, a failed write still returns the
-   * rendered page, a failed regeneration keeps the stale entry - so a store outage never changes a
-   * status. Default: one `console.error` line per operation per minute, never naming the cache key.
+   * Called when a store call fails: it throws, rejects, or outlives {@link storeTimeoutMs}, or (op
+   * `"verify"`) a page it returns fails its {@link storeSecret} signature check. The request is served
+   * without the cache either way - a failed read is a miss, a failed write still returns the rendered
+   * page, a failed regeneration keeps the stale entry - so a store outage never changes a status.
+   * Default: one `console.error` line per operation per minute, never naming the cache key.
    */
   readonly onStoreError?: (error: unknown, info: { readonly op: ISRStoreOp }) => void
   /**
@@ -608,12 +678,27 @@ export interface ISROptions {
    * the request; set it when the store is a network service.
    */
   readonly storeTimeoutMs?: number
+  /**
+   * Caches below the pages whose entries carry the same tags, such as a `@nifrajs/cache` holding loader
+   * data. An action's `revalidate(paths, data, { tags })` invalidates them first, then this store, then
+   * publishes to live pages, then purges `cdn`; a cache that fails stops the rest, so no client reloads
+   * stale data.
+   */
+  readonly dataCaches?: readonly { invalidateTag(tag: string): unknown }[]
+  /** A CDN an action's invalidation purges last (a `@nifrajs/web/cdn` provider). */
+  readonly cdn?: CdnPurgeTarget
+  /**
+   * An action's invalidation that still failed after its retries; the action's own answer never
+   * changes. Default: one `console.error` line naming the operation id and stage.
+   */
+  readonly onInvalidationError?: (report: InvalidationReport) => void
 }
 
 /** The store operation an {@link ISROptions.onStoreError} report is about. */
-export type ISRStoreOp = "get" | "set" | "delete" | "fence"
+export type ISRStoreOp = "get" | "set" | "delete" | "fence" | "verify"
 
 const STORE_FAILED = Symbol("nifra.isr.store-failed")
+const MAC_HEADER = "x-nifra-isr-mac"
 const STORE_REPORT_INTERVAL_MS = 60_000
 const STORE_REPORT_DETAIL_CHARS = 200
 
@@ -633,6 +718,79 @@ function storeErrorDetail(error: unknown, key: string): string {
     : redacted
 }
 
+/**
+ * What a page's MAC covers: everything a replay serves, plus the key, so a page copied to another key
+ * never verifies there. Header names and tags are sorted, since a store need not keep their order.
+ */
+function signedParts(key: string, entry: CachedResponse): readonly string[] {
+  const names = Object.keys(entry.headers)
+    .filter((name) => name !== MAC_HEADER)
+    .sort()
+  const headers = names.map((name) => [name, entry.headers[name]])
+  const tags = entry.tags === undefined ? [] : [...entry.tags].sort()
+  const meta = JSON.stringify([
+    1,
+    key,
+    entry.status,
+    entry.storedAt,
+    entry.revalidate,
+    headers,
+    tags,
+  ])
+  return [meta, entry.body]
+}
+
+async function signed(
+  signer: StoreSigner,
+  key: string,
+  entry: CachedResponse,
+): Promise<CachedResponse> {
+  const mac = await signer.sign(signedParts(key, entry))
+  return { ...entry, headers: { ...entry.headers, [MAC_HEADER]: mac } }
+}
+
+async function verified(signer: StoreSigner, key: string, entry: CachedResponse): Promise<boolean> {
+  try {
+    return await signer.verify(signedParts(key, entry), entry.headers[MAC_HEADER])
+  } catch {
+    // A store's own malformed record.
+    return false
+  }
+}
+
+function signerFor(store: CacheStore, secret: unknown): StoreSigner | undefined {
+  if (secret !== undefined && !isStoreSecret(secret)) {
+    throw new TypeError(
+      `[nifra/web] ISR storeSecret must be a string of at least ${MIN_STORE_SECRET_LENGTH} characters`,
+    )
+  }
+  if (inProcessStores.has(store)) return undefined
+  if (secret === undefined) {
+    throw new TypeError(
+      `[nifra/web] withISR needs storeSecret, at least ${MIN_STORE_SECRET_LENGTH} characters, to sign the pages it keeps in a store other processes can write. Only a MemoryCacheStore runs without one.`,
+    )
+  }
+  return storeSigner(secret)
+}
+
+// Headers only an action or a data request carries; a stored page is always a plain document GET.
+const ACTION_ONLY_HEADERS = [
+  "content-type",
+  "content-length",
+  "content-encoding",
+  "transfer-encoding",
+  "x-nifra-data",
+  "x-nifra-component",
+  SWAP_HEADER,
+]
+
+/** The document GET for `path` from the client that sent `req`: what a custom key sees on a read. */
+function documentGet(path: string, req: Request): Request {
+  const headers = new Headers(req.headers)
+  for (const name of ACTION_ONLY_HEADERS) headers.delete(name)
+  return new Request(originOf(req) + path, { headers })
+}
+
 /** `createWebApp`'s marker for how its documents meet a CSP (see `DOCUMENT_POLICY` in ./csp.ts). Read
  * through the global symbol registry so a cache wrapper never imports the CSP module. */
 const DOCUMENT_POLICY = Symbol.for("nifra.web.documentPolicy")
@@ -676,6 +834,32 @@ const requestKeyOf =
   (req: Request): string | null =>
     urlKey(new URL(req.url))
 
+/**
+ * The key of a request, and of a path on the request's origin. Under the default URL key a path needs
+ * no `Request`; a custom `key` is handed one.
+ */
+function cacheKeysOf(options: ISROptions): {
+  readonly request: (req: Request) => string | null
+  readonly path: (path: string, req: Request) => string | null
+} {
+  const custom = options.key
+  if (custom !== undefined) {
+    return { request: custom, path: (path, req) => custom(documentGet(path, req)) }
+  }
+  const urlKey = urlKeyOf(options.query)
+  return {
+    request: requestKeyOf(urlKey),
+    path: (path, req) => urlKey(new URL(originOf(req) + path)),
+  }
+}
+
+/** `req.url` up to its path, without a parse: the path joined to it is parsed as one URL anyway. */
+const originOf = (req: Request): string => {
+  const url = req.url
+  const end = url.indexOf("/", url.indexOf("//") + 2)
+  return end === -1 ? url : url.slice(0, end)
+}
+
 function assertRevalidate(value: number, name: string): void {
   if (!Number.isFinite(value) || value < 0) {
     throw new RangeError(`[nifra/web] ${name} must be a finite non-negative number`)
@@ -714,14 +898,13 @@ const requestCarriesPrivateState = (req: Request): boolean =>
 const responseIsExplicitlyPublic = (res: Response): boolean =>
   cacheControlHas(res.headers, ["public"])
 
-// `x-nifra-data` alone is not a variation the URL key misses: a navigation data request never reads
-// or writes the store, so every stored entry is the document.
+// Data and swap requests bypass both cache reads and writes, so these headers cannot vary stored HTML.
 const responseDeclaresVary = (res: Response): boolean => {
   const value = res.headers.get("vary")
   if (value === null) return false
   for (const part of value.split(",")) {
     const name = part.trim().toLowerCase()
-    if (name !== "" && name !== "x-nifra-data") return true
+    if (name !== "" && name !== "x-nifra-data" && name !== SWAP_HEADER) return true
   }
   return false
 }
@@ -729,13 +912,13 @@ const responseDeclaresVary = (res: Response): boolean => {
 /**
  * Whether `res` may be stored by a shared cache and served to anyone requesting `req`'s URL: a
  * full-document `GET` 200 `text/html` with no Set-Cookie, no `private`/`no-store`, no `Vary` beyond
- * the data header, and, for a request carrying a cookie or Authorization or accepted by an
+ * the data/swap headers, and, for a request carrying a cookie or Authorization or accepted by an
  * authentication stage, an explicit `public`.
  * The one rule both `withISR` and `@nifrajs/web/cdn` cache by.
  */
 export const isCacheablePage = (req: Request, res: Response): boolean => {
   if (req.method !== "GET") return false
-  if (req.headers.get("x-nifra-data") !== null) return false
+  if (req.headers.get("x-nifra-data") !== null || req.headers.has(SWAP_HEADER)) return false
   if (res.status !== 200) return false
   if (!(res.headers.get("content-type") ?? "").includes("text/html")) return false
   if (hasSetCookie(res.headers)) return false
@@ -842,6 +1025,11 @@ export function withISR(
 ): (req: Request, platform?: ISRPlatform) => Promise<Response> {
   const { store, now } = options
   assertRevalidate(options.revalidate, "revalidate")
+  const signer = signerFor(store, options.storeSecret)
+  const write = (key: string, entry: CachedResponse): Promise<void> =>
+    signer === undefined
+      ? store.set(key, entry)
+      : signed(signer, key, entry).then((value) => store.set(key, value))
   const storeTimeoutMs = options.storeTimeoutMs
   if (storeTimeoutMs !== undefined && !(Number.isFinite(storeTimeoutMs) && storeTimeoutMs > 0)) {
     throw new RangeError("[nifra/web] ISR storeTimeoutMs must be a positive finite number")
@@ -865,28 +1053,32 @@ export function withISR(
     }
   }
   // Runs one store call; a throw, a rejection or a timeout is reported and answered with STORE_FAILED.
+  const withinTimeout = async <T>(op: string, pending: Promise<T>): Promise<T> => {
+    if (storeTimeoutMs === undefined) return pending
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        const error = new Error(`ISR store ${op} exceeded storeTimeoutMs (${storeTimeoutMs} ms)`)
+        error.name = "TimeoutError"
+        reject(error)
+      }, storeTimeoutMs)
+    })
+    try {
+      return await Promise.race([pending, timeout])
+    } finally {
+      clearTimeout(timer)
+    }
+  }
   const attempt = async <T>(
     op: ISRStoreOp,
     key: string,
     call: () => Promise<T>,
   ): Promise<T | typeof STORE_FAILED> => {
-    let timer: ReturnType<typeof setTimeout> | undefined
     try {
-      const pending = call()
-      if (storeTimeoutMs === undefined) return await pending
-      const timeout = new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          const error = new Error(`ISR store ${op} exceeded storeTimeoutMs (${storeTimeoutMs} ms)`)
-          error.name = "TimeoutError"
-          reject(error)
-        }, storeTimeoutMs)
-      })
-      return await Promise.race([pending, timeout])
+      return await withinTimeout(op, call())
     } catch (error) {
       reportStoreError(op, key, error)
       return STORE_FAILED
-    } finally {
-      if (timer !== undefined) clearTimeout(timer)
     }
   }
   // A store without purge order, or one whose fence failed, stores the render unfenced.
@@ -896,7 +1088,8 @@ export function withISR(
     const taken = await attempt("fence", key, async () => fence.call(store))
     return taken === STORE_FAILED ? undefined : taken
   }
-  const keyOf = options.key ?? requestKeyOf(urlKeyOf(options.query))
+  const keys = cacheKeysOf(options)
+  const keyOf = keys.request
   const draftSecret = options.draftSecret
   const anonymousCookies = new Set(options.anonymousCookies ?? [])
   // A request whose cookies are all anonymous is judged for storage as if it carried none.
@@ -915,6 +1108,38 @@ export function withISR(
   }
   const regenerating = new Set<string>()
   openCacheChannel(app)
+  // This wrapper owns the app's invalidation pipeline from here on: an action's operation comes back
+  // by its request, and every stage runs in order before the action's answer leaves.
+  const handoff: unknown = Reflect.get(app, INVALIDATION)
+  const taken = isHandoff(handoff) ? handoff : undefined
+  // The pipeline's purges are bounded like every other store call; their failures reach its own report.
+  const invalidateTag = store.invalidateTag
+  const targets: InvalidationTargets = {
+    dataCaches: options.dataCaches,
+    store: {
+      delete: (key) => withinTimeout("delete", store.delete(key)),
+      invalidateTag:
+        invalidateTag === undefined
+          ? undefined
+          : (tag) => withinTimeout("invalidateTag", invalidateTag.call(store, tag)),
+    },
+    keyOf: keys.path,
+    publish: taken?.publish,
+    cdn: options.cdn,
+  }
+  const passThrough = async (
+    req: Request,
+    platform: ISRPlatform | undefined,
+  ): Promise<Response> => {
+    const res = withoutCacheChannel(await app.fetch(req, platform))
+    const op = taken?.take(req)
+    if (op !== undefined) {
+      await settleInvalidation(op, targets, req, platform, {
+        onError: options.onInvalidationError,
+      })
+    }
+    return res
+  }
   // An outer cache layer (`withCdn`) opens this wrapper's own channel: cached responses then carry how
   // much freshness they have left and their tags, so the CDN never holds a page longer than ISR would.
   let channelOpen = false
@@ -988,7 +1213,7 @@ export function withISR(
     }
     // A failed write still answers with the page, and still hands it to concurrent misses: whether it
     // may be shared was decided above, not by the store.
-    await attempt("set", key, () => store.set(key, entry))
+    await attempt("set", key, () => write(key, entry))
     stored?.(entry)
     return fresh(entry)
   }
@@ -1052,7 +1277,7 @@ export function withISR(
           ...(tags.length === 0 ? {} : { tags }),
           fence,
         }
-        await attempt("set", key, () => store.set(key, entry))
+        await attempt("set", key, () => write(key, entry))
       } else if (isInvalidationResponse(judged(req), res)) {
         // A withdrawal is authoritative. Keeping the old entry would make a withdrawn page stay
         // publicly visible forever, because every stale request would retry the same non-cacheable
@@ -1070,24 +1295,25 @@ export function withISR(
   }
 
   const handler = async (req: Request, platform?: ISRPlatform): Promise<Response> => {
-    // A data-mode soft-nav GET bypasses the cache entirely: entries are full HTML documents keyed
-    // by URL, and serving one to a loader-data fetch would hand the client HTML where it expects
-    // the loader payload. (The write path already refuses to cache data-mode responses.)
+    // A data-mode soft-nav GET or a slot swap bypasses the cache entirely: entries are full HTML
+    // documents keyed by URL, and serving one to either would hand the client a document where it
+    // expects the loader payload or one slot. (The write path already refuses both.)
     const privateRoute: unknown = Reflect.get(app, Symbol.for("nifra.web.private-route"))
     const ownsPrivate = typeof privateRoute === "function" && privateRoute(req) === true
     const key =
       req.method === "GET" &&
       req.headers.get("x-nifra-data") === null &&
       !req.headers.has("x-nifra-component") &&
+      !req.headers.has(SWAP_HEADER) &&
       !ownsPrivate
         ? keyOf(req)
         : null
-    if (key === null) return withoutCacheChannel(await app.fetch(req, platform))
+    if (key === null) return passThrough(req, platform)
 
     // Draft/preview: an editor (valid signed cookie) always renders fresh and is never cached, so
     // unpublished content can't leak into the public cache (and the editor isn't served a stale page).
     if (draftSecret !== undefined && (await isDraftEnabled(req, draftSecret))) {
-      return withoutCacheChannel(await app.fetch(req, platform))
+      return passThrough(req, platform)
     }
 
     // A cookie or Authorization request may be personalized: under the default key it never reads
@@ -1101,7 +1327,11 @@ export function withISR(
     }
 
     const read = personal ? undefined : await attempt("get", key, () => store.get(key))
-    const hit = read === STORE_FAILED ? undefined : read
+    let hit = read === STORE_FAILED ? undefined : read
+    if (hit !== undefined && signer !== undefined && !(await verified(signer, key, hit))) {
+      reportStoreError("verify", key, new Error("a stored page failed its signature check"))
+      hit = undefined
+    }
     if (hit !== undefined) {
       if (now() - hit.storedAt < hit.revalidate) return served(hit, "hit")
       // Stale: serve it now, regenerate behind it (waitUntil keeps the edge worker alive for the regen).
@@ -1123,6 +1353,9 @@ export function withISR(
 const jsonError = (status: number, error: string): Response =>
   Response.json({ ok: false, error }, { status })
 
+const isHandoff = (value: unknown): value is InvalidationHandoff =>
+  typeof value === "object" && value !== null && typeof Reflect.get(value, "take") === "function"
+
 /** What a CDN purge came to: sent and accepted, queued behind a rate limit or retry, or refused. */
 export interface CdnPurgeOutcome {
   readonly cdn: "accepted" | "queued" | "failed"
@@ -1172,6 +1405,11 @@ export interface RevalidateEndpointOptions {
    * page store is touched, so a retry purges everything again. Path purges do not reach them.
    */
   readonly dataCaches?: readonly { invalidateTag(tag: string): unknown }[]
+  /**
+   * The app's live runtime: a purge also tells live pages watching a purged tag to reload, after the
+   * caches and before the CDN. A publish that fails answers `502` with `origin: "done"`.
+   */
+  readonly live?: { publish(...keys: string[]): Promise<void> }
 }
 
 const stringList = (value: unknown): string[] | null | undefined => {
@@ -1263,47 +1501,51 @@ export function revalidateEndpoint(
       return jsonError(501, "tag_invalidation_not_supported")
     }
 
-    if (tags.length > 0 && options.dataCaches !== undefined) {
-      try {
-        for (const cache of options.dataCaches) {
-          for (const candidate of tags) await cache.invalidateTag(candidate)
-        }
-      } catch {
-        return Response.json(
-          { ok: false, error: "data_cache_invalidation_failed" },
-          { status: 500 },
-        )
-      }
-    }
-    for (const key of keys) await options.store.delete(key)
-    for (const candidate of tags) await invalidateTag?.call(options.store, candidate)
+    // The same pipeline an action's `revalidate()` runs: data caches, this store, live, then the CDN.
+    const live = options.live
+    const report = await runInvalidation(
+      { id: crypto.randomUUID(), paths, tags, keys: [] },
+      {
+        dataCaches: options.dataCaches,
+        store: options.store,
+        keyOf: (candidate) => keys[paths.indexOf(candidate)] ?? null,
+        publish: live === undefined ? undefined : (names) => live.publish(...names),
+        cdn: options.cdn,
+      },
+      req,
+      platform,
+    )
+    const stageOf = (stage: string) => report.stages.find((each) => each.stage === stage)
+    if (stageOf("data")?.ok === false) return jsonError(500, "data_cache_invalidation_failed")
+    if (stageOf("pages")?.ok === false) return jsonError(500, "page_store_invalidation_failed")
     const done =
       path !== null
         ? { revalidated: path }
         : tag !== null
           ? { revalidatedTag: tag }
           : { revalidated: paths, revalidatedTags: tags }
-    if (options.cdn === undefined) return Response.json(done)
-
-    let outcome: CdnPurgeOutcome
-    try {
-      outcome = await options.cdn.purge({ tags, paths }, platform)
-    } catch {
-      outcome = { cdn: "failed", retryable: true, error: "cdn_purge_threw" }
-    }
-    if (outcome.cdn === "failed") {
+    const published = stageOf("publish")
+    const cdn = stageOf("cdn")
+    if (cdn?.ok === false) {
       const failure: Record<string, unknown> = {
         ok: false,
         error: "cdn_purge_failed",
         origin: "done",
-        retryable: outcome.retryable,
+        retryable: cdn.retryable,
       }
-      if (outcome.error !== undefined) failure.reason = outcome.error
+      if (cdn.error !== undefined && cdn.error !== "cdn_failed") failure.reason = cdn.error
       return Response.json(failure, { status: 502 })
     }
+    if (published?.ok === false) {
+      return Response.json(
+        { ok: false, error: "live_publish_failed", origin: "done", retryable: true },
+        { status: 502 },
+      )
+    }
+    if (cdn === undefined) return Response.json(done)
     return Response.json(
-      { ...done, cdn: outcome.cdn },
-      { status: outcome.cdn === "queued" ? 202 : 200 },
+      { ...done, cdn: cdn.queued === true ? "queued" : "accepted" },
+      { status: cdn.queued === true ? 202 : 200 },
     )
   }
 }