@nifrajs/web 0.1.0-alpha.1

package/src/islands.ts

@@ -0,0 +1,121 @@
+/**
+ * @nifrajs/web/islands — the framework-agnostic islands client runtime.
+ *
+ * An "island" is a server-rendered `<nifra-island>` element whose interactivity is mounted by a small
+ * **plain-DOM** enhancer instead of a framework runtime. On a route that opts out of full-document
+ * hydration (`export const hydrate = false`), the page ships **zero** framework JS; only the island
+ * bundle (this runtime + your enhancers) loads. This variant ships ~99% less client JS than full
+ * React hydration on a mostly-static page — the framework runtime is the cost, and islands skip it
+ * entirely here.
+ *
+ * Server side: render the marker with `@nifrajs/web-react`'s `<Island>` (or any framework's host element
+ * `<nifra-island data-id data-strategy data-props>`). Props are JSON-encoded inline in `data-props`
+ * (attribute-escaped by the framework) — no central registry, so concurrent SSR renders never share
+ * state. Client side: bundle one entry that calls `mountIslands({ <id>: enhancer })` and load it via
+ * the route's `islandScripts`.
+ */
+
+/** When an island's enhancer runs. Default `load`. */
+export type IslandStrategy = "load" | "idle" | "visible"
+
+/** Optional teardown an enhancer returns (remove listeners/observers); run on `dispose()`. */
+export type IslandCleanup = () => void
+
+/**
+ * Enhances one island element with its (typed) props. Return a cleanup function to tear down on
+ * `dispose()` (listeners, observers) — optional; an enhancer with nothing to clean up returns nothing.
+ * The `void` member is the no-cleanup case, the same shape as React's `EffectCallback`.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: `void` = "no cleanup returned", like React's EffectCallback — cleanup is optional.
+export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandCleanup | void
+
+const NOOP = (): void => {}
+
+/** Parse an island's inline `data-props` JSON; malformed/absent → `undefined` (never throws). */
+function readProps(el: HTMLElement): unknown {
+  const raw = el.dataset.props
+  if (raw === undefined || raw === "") return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/** Run `run` per the island's strategy; returns a disposer that cancels a not-yet-fired trigger. */
+function whenStrategy(el: HTMLElement, strategy: IslandStrategy, run: () => void): () => void {
+  if (strategy === "idle") {
+    const ric = globalThis.requestIdleCallback
+    if (ric === undefined) {
+      const t = setTimeout(run, 1)
+      return () => clearTimeout(t)
+    }
+    const handle = ric(run)
+    return () => globalThis.cancelIdleCallback?.(handle)
+  }
+  if (strategy === "visible") {
+    // No IntersectionObserver (old engine / SSR smoke) → degrade to immediate, never skip the island.
+    if (typeof IntersectionObserver === "undefined") {
+      run()
+      return NOOP
+    }
+    const io = new IntersectionObserver((entries, obs) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          obs.disconnect()
+          run()
+          return
+        }
+      }
+    })
+    io.observe(el)
+    return () => io.disconnect()
+  }
+  // "load" (and any unknown value) → run immediately on mount.
+  run()
+  return NOOP
+}
+
+/**
+ * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
+ * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
+ * inert SSR HTML (forward-compatible). An enhancer that throws is isolated — it never blocks the
+ * others (each island is independent). Returns a disposer that cancels pending triggers and runs every
+ * enhancer's cleanup (call it on soft-nav teardown; harmless if your app never navigates).
+ */
+export function mountIslands(
+  enhancers: Readonly<Record<string, IslandEnhancer>>,
+  options: { readonly root?: ParentNode } = {},
+): () => void {
+  const root = options.root ?? document
+  const disposers: Array<() => void> = []
+  for (const el of root.querySelectorAll<HTMLElement>("nifra-island[data-id]")) {
+    const id = el.dataset.id
+    if (id === undefined) continue
+    const enhancer = enhancers[id]
+    if (enhancer === undefined) continue // no enhancer for this id → leave it as inert SSR markup
+    const props = readProps(el)
+    const strategyAttr = el.dataset.strategy
+    const strategy: IslandStrategy =
+      strategyAttr === "idle" || strategyAttr === "visible" ? strategyAttr : "load"
+    const run = (): void => {
+      try {
+        const cleanup = enhancer(el, props)
+        if (typeof cleanup === "function") disposers.push(cleanup)
+      } catch (err) {
+        // One island's failure must not take down the others; surface it without throwing.
+        console.error(`[nifra/islands] enhancer "${id}" failed:`, err)
+      }
+    }
+    disposers.push(whenStrategy(el, strategy, run))
+  }
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        // best-effort teardown — a failing cleanup must not block the rest
+      }
+    }
+  }
+}

package/src/isr.ts

@@ -0,0 +1,461 @@
+/**
+ * ISR (Incremental Static Regeneration). A caching layer that sits ABOVE the agnostic SSR
+ * handler: it stores a rendered `Response` keyed by URL and serves it with stale-while-revalidate
+ * freshness, so dynamic pages get static-like speed and revalidate in the background. Agnostic to the
+ * UI framework (it caches bytes), coupled to the runtime only through this pluggable {@link CacheStore}.
+ *
+ * This module is the store primitive; the SWR wrapper (`withISR`) builds on it next.
+ */
+import { isDraftEnabled } from "./draft.ts"
+
+/** A cached SSR response — the bytes + metadata a {@link CacheStore} persists. */
+export interface CachedResponse {
+  /** The rendered document (UTF-8 HTML, fully buffered). */
+  readonly body: string
+  readonly status: number
+  /** Response headers to replay (e.g. `content-type`). */
+  readonly headers: Readonly<Record<string, string>>
+  /** When this entry was stored, via the injected clock (ms epoch). */
+  readonly storedAt: number
+  /** Freshness window (ms): `now - storedAt >= revalidate` ⇒ stale (serve it, regenerate behind it). */
+  readonly revalidate: number
+}
+
+/**
+ * Pluggable ISR cache backend. **Production deploys MUST use a shared/durable store** (Workers KV,
+ * Redis, the platform Cache API) so cached pages *and* revalidation hold across instances;
+ * {@link MemoryCacheStore} is dev / single-instance only. Implementations are async so a network store
+ * (KV/Redis) fits the same interface.
+ */
+export interface CacheStore {
+  /** The cached entry for `key`, or `undefined` on a miss. */
+  get(key: string): Promise<CachedResponse | undefined>
+  /** Store (or overwrite) the entry for `key`. */
+  set(key: string, value: CachedResponse): Promise<void>
+  /** Drop `key` (on-demand revalidation / purge). A no-op if absent. */
+  delete(key: string): Promise<void>
+}
+
+export interface MemoryCacheStoreOptions {
+  /** Allow the in-memory store in production. Off by default — per-instance caching means revalidation
+   * won't propagate across instances and each instance caches separately. */
+  readonly allowInProduction?: boolean
+  /** Hard cap on entries; the least-recently-used is evicted past it (default 500). */
+  readonly max?: number
+}
+
+/**
+ * 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
+ * read or write bumps the entry, so the least-recently-used evicts past `max` (a hot, frequently-read
+ * page survives a burst of new pages).
+ */
+export class MemoryCacheStore implements CacheStore {
+  private readonly cache = new Map<string, CachedResponse>()
+  private readonly max: number
+
+  constructor(options: MemoryCacheStoreOptions = {}) {
+    const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production"
+    if (options.allowInProduction !== true && isProd) {
+      throw new Error(
+        "[nifra/web] MemoryCacheStore is per-instance and unsafe in production (each instance caches " +
+          "separately, and on-demand revalidation won't propagate). Use a shared store (Workers KV, " +
+          "Redis, the Cache API), or pass { allowInProduction: true } for a single-instance deploy.",
+      )
+    }
+    this.max = options.max ?? 500
+  }
+
+  get(key: string): Promise<CachedResponse | undefined> {
+    const value = this.cache.get(key)
+    // LRU: a read bumps the entry to the tail so the bounded evict drops the LEAST-RECENTLY-USED,
+    // not the oldest-written — otherwise a burst of new pages would evict a hot, frequently-read one.
+    if (value !== undefined) {
+      this.cache.delete(key)
+      this.cache.set(key, value)
+    }
+    return Promise.resolve(value)
+  }
+
+  set(key: string, value: CachedResponse): Promise<void> {
+    this.cache.delete(key) // re-insert at the tail so Map order tracks recency (with get) for the LRU evict
+    this.cache.set(key, value)
+    while (this.cache.size > this.max) {
+      const oldest = this.cache.keys().next().value
+      if (oldest === undefined) break
+      this.cache.delete(oldest)
+    }
+    return Promise.resolve()
+  }
+
+  delete(key: string): Promise<void> {
+    this.cache.delete(key)
+    return Promise.resolve()
+  }
+}
+
+/**
+ * Minimal structural shape of a Cloudflare Workers **KV namespace** binding — just the three methods
+ * {@link KVCacheStore} uses. Structural (not a dependency on `@cloudflare/workers-types`) so any
+ * KV-like binding satisfies it and tests can pass an in-memory double.
+ */
+export interface KVNamespaceLike {
+  /** Read a stored string value, or `null` on a miss (Cloudflare's `KVNamespace.get(key)` default). */
+  get(key: string): Promise<string | null>
+  /** Write a string value, optionally with a TTL (**seconds**). */
+  put(key: string, value: string, options?: { readonly expirationTtl?: number }): Promise<void>
+  /** Delete a key (a no-op if absent). */
+  delete(key: string): Promise<void>
+}
+
+export interface KVCacheStoreOptions {
+  /**
+   * GC backstop (**seconds**) written as the KV entry's `expirationTtl`, so abandoned entries
+   * eventually evict. MUST exceed your longest `revalidate` window — otherwise KV expiry turns a
+   * stale-while-revalidate into a *blocking* miss (the entry vanishes instead of being served stale
+   * while it regenerates) — and be ≥ 60 (Cloudflare KV's minimum). Omit ⇒ entries persist until
+   * overwritten on regeneration or purged via `revalidateEndpoint`.
+   */
+  readonly expirationTtl?: number
+}
+
+/**
+ * Structural validation of a KV-read value before it's trusted as a {@link CachedResponse}. The store
+ * is a trust boundary (version skew across a deploy, corruption, tampering), so a malformed entry is
+ * treated as a miss (the page re-renders + overwrites it) rather than served as a broken response.
+ */
+const isCachedResponse = (value: unknown): value is CachedResponse => {
+  if (typeof value !== "object" || value === null) return false
+  const v = value as Record<string, unknown>
+  if (
+    typeof v.body !== "string" ||
+    typeof v.status !== "number" ||
+    typeof v.storedAt !== "number" ||
+    typeof v.revalidate !== "number" ||
+    typeof v.headers !== "object" ||
+    v.headers === null
+  ) {
+    return false
+  }
+  for (const headerValue of Object.values(v.headers as Record<string, unknown>)) {
+    if (typeof headerValue !== "string") return false
+  }
+  return true
+}
+
+/**
+ * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
+ * 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)`.
+ */
+export class KVCacheStore implements CacheStore {
+  private readonly kv: KVNamespaceLike
+  private readonly putOptions: { readonly expirationTtl?: number } | undefined
+
+  constructor(kv: KVNamespaceLike, options: KVCacheStoreOptions = {}) {
+    if (options.expirationTtl !== undefined && options.expirationTtl < 60) {
+      throw new Error(
+        "[nifra/web] KVCacheStore expirationTtl must be >= 60 (Cloudflare KV's minimum), and should " +
+          "exceed your longest `revalidate` window so stale-while-revalidate isn't turned into a " +
+          "blocking miss by KV expiry.",
+      )
+    }
+    this.kv = kv
+    // 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
+  }
+
+  async get(key: string): Promise<CachedResponse | undefined> {
+    const raw = await this.kv.get(key)
+    if (raw === null) return undefined
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch {
+      // A corrupt (non-JSON) entry: treat as a miss so the page re-renders; the next set overwrites it.
+      return undefined
+    }
+    return isCachedResponse(parsed) ? parsed : undefined
+  }
+
+  async set(key: string, value: CachedResponse): Promise<void> {
+    await this.kv.put(key, JSON.stringify(value), this.putOptions)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key)
+  }
+}
+
+/** Minimal platform shape `withISR` needs — just `waitUntil` (edge runtimes extend the response
+ * lifetime so background regeneration finishes). Off-edge it's absent and regen runs fire-and-forget. */
+export interface ISRPlatform {
+  readonly waitUntil?: (promise: Promise<unknown>) => void
+}
+
+/** The app `withISR` wraps — anything with a `fetch(req, platform?)` (a `createWebApp` result). */
+export interface ISRApp {
+  fetch(req: Request, platform?: ISRPlatform): Response | Promise<Response>
+}
+
+/** Response header marking how an ISR response was served: a cache `hit` (fresh), `stale` (served +
+ * regenerating behind it), or `miss` (rendered now + stored). Useful for debugging + tests. */
+export const ISR_STATUS_HEADER = "x-nifra-isr"
+
+/**
+ * Response header a route uses to advertise its ISR freshness (**seconds**) to a {@link withISR}
+ * wrapper — `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
+ * from the action-revalidation `x-nifra-revalidate` header (a CSV path list the *client* parses to
+ * refetch): this one is an integer TTL the *wrapper* reads, so the two channels never alias.
+ */
+export const ISR_REVALIDATE_HEADER = "x-nifra-isr-revalidate"
+
+export interface ISROptions {
+  readonly store: CacheStore
+  /** 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). */
+  readonly revalidate: number
+  /** Monotonic clock (ms) — injected for testability; production passes `() => Date.now()`. */
+  readonly now: () => number
+  /** Cache key for a request. Default: `origin + pathname + search` 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). */
+  readonly key?: (req: Request) => string | null
+  /** Draft/preview secret (the same one given to `createWebApp({ draftSecret })` + `enableDraft`). When
+   * set, a request carrying a valid signed draft cookie **bypasses the cache** — editors always render
+   * fresh, and a draft render is never written to the store (it can't poison the public cache). */
+  readonly draftSecret?: string
+}
+
+const defaultKey = (req: Request): string => {
+  const url = new URL(req.url)
+  return url.origin + url.pathname + url.search
+}
+
+/** ISR caches a full-document SSR response: a `GET` (not a data-mode soft-nav fetch), `200`, `text/html`.
+ * Assets, data-mode GETs, redirects, and errors pass through uncached. */
+const cacheControlHas = (headers: Headers, names: readonly string[]): boolean => {
+  const value = headers.get("cache-control")
+  if (value === null) return false
+  const directives = value
+    .toLowerCase()
+    .split(",")
+    .map((part) => part.trim().split("=", 1)[0])
+  return names.some((name) => directives.includes(name))
+}
+
+const hasSetCookie = (headers: Headers): boolean =>
+  headers.has("set-cookie") || (headers.getSetCookie?.().length ?? 0) > 0
+
+const requestCarriesPrivateState = (req: Request): boolean =>
+  req.headers.has("authorization") || req.headers.has("cookie")
+
+const responseIsExplicitlyPublic = (res: Response): boolean =>
+  cacheControlHas(res.headers, ["public"])
+
+const isCacheablePage = (req: Request, res: Response): boolean => {
+  if (req.method !== "GET") return false
+  if (req.headers.get("x-nifra-data") !== null) 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
+  if (cacheControlHas(res.headers, ["private", "no-store"])) return false
+  // Cookie/Authorization requests often personalize HTML without setting a new cookie. Cache them only
+  // when the route explicitly declares the response public.
+  if (requestCarriesPrivateState(req) && !responseIsExplicitlyPublic(res)) return false
+  return true
+}
+
+const CACHEABLE_RESPONSE_HEADERS = new Set([
+  "cache-control",
+  "content-language",
+  "content-type",
+  "etag",
+  "last-modified",
+  "link",
+])
+
+const headersOf = (res: Response): Record<string, string> => {
+  const out: Record<string, string> = {}
+  res.headers.forEach((value, key) => {
+    if (CACHEABLE_RESPONSE_HEADERS.has(key)) out[key] = value
+  })
+  return out
+}
+
+const responseFrom = (entry: CachedResponse, status: "hit" | "stale"): Response =>
+  new Response(entry.body, {
+    status: entry.status,
+    headers: { ...sanitizeCachedHeaders(entry.headers), [ISR_STATUS_HEADER]: status },
+  })
+
+function sanitizeCachedHeaders(headers: Readonly<Record<string, string>>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers)) {
+    const normalized = key.toLowerCase()
+    if (CACHEABLE_RESPONSE_HEADERS.has(normalized)) out[normalized] = value
+  }
+  return out
+}
+
+/**
+ * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
+ * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
+ * (`platform.waitUntil` on edge), or rendered + stored on a miss. Framework-agnostic (it caches the
+ * rendered bytes). Returns a `fetch(req, platform?)` handler — hand it to `Bun.serve`/the Workers
+ * `export default`, etc. Regeneration is single-flight per key (no stampede on a hot stale page).
+ *
+ * Each route's freshness comes from the `revalidate` header the app sets (per-route
+ * `export const revalidate`), falling back to `options.revalidate`. Only full-document `text/html`
+ * GET 200s are cached; everything else (assets, data-mode GETs, redirects, errors) passes through.
+ */
+export function withISR(
+  app: ISRApp,
+  options: ISROptions,
+): (req: Request, platform?: ISRPlatform) => Promise<Response> {
+  const { store, now } = options
+  const keyOf = options.key ?? defaultKey
+  const draftSecret = options.draftSecret
+  const regenerating = new Set<string>()
+
+  // Per-page TTL (ms): the app's `x-nifra-isr-revalidate` header (seconds) if present, else the default.
+  const ttlMs = (res: Response): number => {
+    const header = res.headers.get(ISR_REVALIDATE_HEADER)
+    const seconds = header === null ? options.revalidate : Number(header)
+    return (Number.isFinite(seconds) ? seconds : options.revalidate) * 1000
+  }
+
+  const render = async (
+    req: Request,
+    platform: ISRPlatform | undefined,
+    key: string,
+  ): Promise<Response> => {
+    const res = await app.fetch(req, platform)
+    if (!isCacheablePage(req, res)) return res
+    const body = await res.text()
+    const entry: CachedResponse = {
+      body,
+      status: res.status,
+      headers: headersOf(res),
+      storedAt: now(),
+      revalidate: ttlMs(res),
+    }
+    await store.set(key, entry)
+    return new Response(body, {
+      status: res.status,
+      headers: { ...entry.headers, [ISR_STATUS_HEADER]: "miss" },
+    })
+  }
+
+  // Background regeneration (single-flight per key) — a failed regen keeps the stale entry; the next
+  // stale hit retries. Never throws (it runs detached / under waitUntil).
+  const regenerate = async (
+    req: Request,
+    platform: ISRPlatform | undefined,
+    key: string,
+  ): Promise<void> => {
+    if (regenerating.has(key)) return
+    regenerating.add(key)
+    try {
+      const res = await app.fetch(req, platform)
+      if (isCacheablePage(req, res)) {
+        await store.set(key, {
+          body: await res.text(),
+          status: res.status,
+          headers: headersOf(res),
+          storedAt: now(),
+          revalidate: ttlMs(res),
+        })
+      } else {
+        await res.body?.cancel()
+      }
+    } catch {
+      // keep the stale entry; a later request retries the regeneration
+    } finally {
+      regenerating.delete(key)
+    }
+  }
+
+  return async (req, platform) => {
+    const key = req.method === "GET" ? keyOf(req) : null
+    if (key === null) return app.fetch(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 app.fetch(req, platform)
+    }
+
+    const hit = await store.get(key)
+    if (hit !== undefined) {
+      if (now() - hit.storedAt < hit.revalidate) return responseFrom(hit, "hit")
+      // Stale: serve it now, regenerate behind it (waitUntil keeps the edge worker alive for the regen).
+      const task = regenerate(req, platform, key)
+      if (typeof platform?.waitUntil === "function") platform.waitUntil(task)
+      else void task.catch(() => {})
+      return responseFrom(hit, "stale")
+    }
+    return render(req, platform, key)
+  }
+}
+
+const jsonError = (status: number, error: string): Response =>
+  Response.json({ ok: false, error }, { status })
+
+/** Constant-time string equality (XOR-accumulate, no early exit). A length mismatch returns `false`
+ * up front — the length isn't the secret, and different-length buffers can't be compared in constant
+ * time anyway. Used to check the on-demand revalidation token without leaking it via timing. */
+function timingSafeEqual(a: string, b: string): boolean {
+  const enc = new TextEncoder()
+  const ba = enc.encode(a)
+  const bb = enc.encode(b)
+  if (ba.length !== bb.length) return false
+  let diff = 0
+  for (let i = 0; i < ba.length; i++) diff |= (ba[i] as number) ^ (bb[i] as number)
+  return diff === 0
+}
+
+export interface RevalidateEndpointOptions {
+  readonly store: CacheStore
+  /** Shared secret; the request's token must match it (constant-time). */
+  readonly secret: string
+  /** Header carrying the secret. Default `x-nifra-revalidate-token`. */
+  readonly tokenHeader?: string
+  /** Map a to-purge path → its cache key — MUST match the `withISR` `key` fn. The default uses the
+   * revalidation request's origin plus the purged path, matching `withISR`'s default host-aware key. */
+  readonly key?: (path: string, req: Request) => string
+}
+
+/**
+ * An **on-demand revalidation** (purge) endpoint — a `fetch` handler that drops a path's cached entry
+ * so the next request re-renders. `POST` with the secret in the token header and the path as `?path=`
+ * or a JSON `{ "path": "/blog/x" }` body. The token is checked in **constant time** (wrong/missing →
+ * `401`); a missing/relative path → `400`; non-POST → `405`. Mount it on a nifra route, e.g.
+ * `app.post("/__nifra/revalidate", (c) => handler(c.req))`.
+ */
+export function revalidateEndpoint(
+  options: RevalidateEndpointOptions,
+): (req: Request) => Promise<Response> {
+  const tokenHeader = options.tokenHeader ?? "x-nifra-revalidate-token"
+  const keyOf = options.key ?? ((path: string, req: Request) => new URL(req.url).origin + path)
+  return async (req) => {
+    if (req.method !== "POST") return jsonError(405, "method_not_allowed")
+    if (!timingSafeEqual(req.headers.get(tokenHeader) ?? "", options.secret)) {
+      return jsonError(401, "unauthorized")
+    }
+    let path = new URL(req.url).searchParams.get("path")
+    if (path === null) {
+      const body: unknown = await req.json().catch(() => null)
+      const candidate =
+        typeof body === "object" && body !== null ? (body as { path?: unknown }).path : undefined
+      path = typeof candidate === "string" ? candidate : null
+    }
+    if (path === null || !path.startsWith("/")) return jsonError(400, "invalid_path")
+    await options.store.delete(keyOf(path, req))
+    return Response.json({ revalidated: path })
+  }
+}