@nifrajs/middleware 4.0.2 → 5.1.0

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,11 +1,18 @@
 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
  * tap) with the same `Idempotency-Key` gets the **first** response replayed instead of the side effect
- * running twice (double-charge, double-publish). Runs in `onRequest` (before the handler), so a replay
- * or an in-flight collision short-circuits before any mutation.
+ * running twice (double-charge, double-publish). The key is claimed in `onRequest`, so an in-flight
+ * collision short-circuits before any mutation; a replay waits for `beforeHandle`, so a credential
+ * revoked since the first request gets the route's current auth answer, not the stored response.
+ * That needs the route declared after `.use(idempotency())` - `beforeHandle` is order-scoped.
  *
  * Pair it with a DB uniqueness constraint - this stops the *retry*, the constraint is the source of
  * truth for genuinely-concurrent distinct requests. Production MUST use a shared {@link IdempotencyStore}
@@ -19,6 +26,12 @@ export interface IdempotencyRecord {
   readonly headers: ReadonlyArray<readonly [string, string]>
   /** Response body, base64-encoded. */
   readonly body: string
+  /**
+   * The response came from a route this middleware's `beforeHandle` covers, so a retry is replayed
+   * from there - after the route's authentication, validation and earlier guards accept it again. A
+   * record without it (a route declared before `.use(idempotency())`) is replayed in `onRequest`.
+   */
+  readonly recheck?: boolean
 }
 
 export type IdempotencyClaim =
@@ -192,8 +205,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 +234,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 {
@@ -364,6 +387,20 @@ function replay(record: IdempotencyRecord): Response {
   return new Response(body === null ? null : body.slice(), { status: record.status, headers })
 }
 
+/** The request `onRequest` recorded in `map`, walking back past a later hook's replacement of it
+ * (methodOverride, a transport codec). */
+function recordedRequest<T>(
+  map: WeakMap<Request, T>,
+  req: Request,
+): readonly [Request, T] | undefined {
+  for (let current: Request | undefined = req; current !== undefined; ) {
+    const found = map.get(current)
+    if (found !== undefined) return [current, found]
+    current = replacedRequestOf(current)
+  }
+  return undefined
+}
+
 const DEFAULT_PRINCIPAL_HEADERS = ["authorization", "cookie", "x-api-key"] as const
 
 /** SHA-256 of the caller's credential headers, base64url. Only the digest ever becomes part of a store
@@ -440,7 +477,13 @@ 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 }
+  >()
+  // Replays held for `beforeHandle`, and fresh claims whose route `beforeHandle` reached.
+  const deferred = new WeakMap<Request, IdempotencyRecord>()
+  const rechecked = new WeakSet<Request>()
 
   const middleware: Middleware = {
     name: "idempotency",
@@ -461,7 +504,11 @@ export function idempotency(options: IdempotencyOptions): Middleware {
           headers: { "content-type": "application/json", "retry-after": "1" },
         })
       }
-      if (claim.state === "replay") return replay(claim.record)
+      if (claim.state === "replay") {
+        if (claim.record.recheck !== true) return replay(claim.record)
+        deferred.set(req, claim.record)
+        return undefined
+      }
       if (claim.state === "in_flight") {
         return new Response(JSON.stringify({ ok: false, error: "idempotency_in_progress" }), {
           status: 409,
@@ -472,21 +519,31 @@ 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) {
-      // A later onRequest hook (methodOverride, a transport codec) may have replaced the request
-      // this one claimed; walk back to it.
-      let claimedReq: Request | undefined = req
-      let claim = claimed.get(req)
-      while (claim === undefined && claimedReq !== undefined) {
-        claimedReq = replacedRequestOf(claimedReq)
-        if (claimedReq !== undefined) claim = claimed.get(claimedReq)
+    beforeHandle(context) {
+      // Authentication and validation have accepted this retry; only now is the stored answer its own.
+      const held = recordedRequest(deferred, context.req)
+      if (held !== undefined) {
+        deferred.delete(held[0])
+        return replay(held[1])
       }
-      if (claim === undefined || claimedReq === undefined) return res // not a claimed request
+      const fresh = recordedRequest(claimed, context.req)
+      if (fresh !== undefined) rechecked.add(fresh[0])
+      return undefined
+    },
+    async onResponse(res, req) {
+      const found = recordedRequest(claimed, req)
+      if (found === undefined) return res // not a claimed request
+      const [claimedReq, claim] = found
       claimed.delete(claimedReq)
-      if (!shouldCache(res)) {
+      if (
+        !shouldCache(res) ||
+        (claim.anonymous && (isAuthenticatedRequest(req) || isAuthenticatedRequest(claimedReq)))
+      ) {
         await store.release(claim.key, claim.reservation)
         return res
       }
@@ -507,7 +564,7 @@ export function idempotency(options: IdempotencyOptions): Middleware {
       await store.complete(
         claim.key,
         claim.reservation,
-        { status: res.status, headers, body: toBase64(bytes) },
+        { status: res.status, headers, body: toBase64(bytes), recheck: rechecked.has(claimedReq) },
         ttlMs,
       )
       return captured.response

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"

package/src/jwt.ts

@@ -4,6 +4,8 @@ import {
   base64UrlDecode,
   bearerToken,
   guardName,
+  type HeaderGet,
+  installAuthGuard,
   jsonError,
   type MaybePromise,
   parseCookies,
@@ -88,12 +90,27 @@ export interface JwksOptions {
   readonly fetch?: typeof fetch
   readonly cacheMs?: number
   /**
-   * Extra time to keep using the last successful key set when refresh fails.
-   * Defaults to one cache window; set `0` to fail closed immediately on refresh errors.
+   * Extra time to keep using the last successful key set past `cacheMs`. Inside it a request is
+   * answered from that set at once while one refresh runs behind it, so a slow or failing identity
+   * provider holds no request. Defaults to one cache window; set `0` to wait for every refresh and
+   * fail closed on refresh errors.
    */
   readonly staleMs?: number
   readonly timeoutMs?: number
   readonly maxBytes?: number
+  /**
+   * Least time (ms) between the refreshes a token with a `kid` the cached set lacks may start, so a
+   * newly rotated key is picked up without made-up `kid`s turning every request into a fetch.
+   * Default 30 s.
+   */
+  readonly cooldownMs?: number
+  /**
+   * Least time (ms) between fetches after one that failed or returned no keys. Inside it a request
+   * that needs the set gets that outcome again at once (the same error, or no key) instead of
+   * waiting up to `timeoutMs` on a fetch of its own, so an identity provider outage does not hold
+   * every request. Default 5 s; `0` fetches again for every such request.
+   */
+  readonly failureCooldownMs?: number
 }
 
 const HASH: Record<JwtAlgorithm, "SHA-256" | "SHA-384" | "SHA-512"> = {
@@ -300,15 +317,19 @@ export async function tryVerifyJwt<C extends JwtClaims = JwtClaims>(
   }
 }
 
-function tokenFromRequest(req: Request, header: string, cookie: string | undefined): string | null {
-  const headerValue = req.headers.get(header)
+function tokenFromHeaders(
+  get: HeaderGet,
+  header: string,
+  cookie: string | undefined,
+): string | null {
+  const headerValue = get(header)
   if (headerValue !== null) {
     if (header === "authorization") {
       return bearerToken(headerValue)
     }
     return headerValue.trim() || null
   }
-  return cookie === undefined ? null : (parseCookies(req.headers.get("cookie"))[cookie] ?? null)
+  return cookie === undefined ? null : (parseCookies(get("cookie"))[cookie] ?? null)
 }
 
 function challenge(realm: string): string {
@@ -327,17 +348,23 @@ export function jwt<C extends JwtClaims = JwtClaims>(options: JwtOptions): JwtPl
   const store = new WeakMap<Request, C>()
 
   const plugin = defineIdentityPlugin(guardName("jwt"), (app) =>
-    app.beforeHandle(async (c: { readonly req: Request }) => {
-      const token = tokenFromRequest(c.req, header, options.cookie)
-      if (token === null) return optional ? undefined : reject(realm)
-      try {
-        const verified = await verifyJwt<C>(token, options)
-        store.set(c.req, verified.claims)
-        return undefined
-      } catch {
-        return optional ? undefined : reject(realm)
-      }
-    }),
+    installAuthGuard(
+      app,
+      "jwt",
+      optional,
+      store,
+      async (get) => {
+        const token = tokenFromHeaders(get, header, options.cookie)
+        if (token === null) return null
+        try {
+          return (await verifyJwt<C>(token, options)).claims
+        } catch {
+          // A token that fails verification is no credential: a 401, never a 503.
+          return null
+        }
+      },
+      () => reject(realm),
+    ),
   )
   const instrumented = optional
     ? plugin
@@ -429,6 +456,12 @@ export function jwks(options: JwksOptions): JwtKeyResolver {
   const staleMs = options.staleMs ?? cacheMs
   const timeoutMs = options.timeoutMs ?? 5_000
   const maxBytes = options.maxBytes ?? 65_536
+  const cooldownMs = options.cooldownMs ?? 30_000
+  const failureCooldownMs = options.failureCooldownMs ?? 5_000
+  if (!Number.isFinite(cooldownMs) || cooldownMs < 0)
+    throw new Error("jwks: cooldownMs must be non-negative")
+  if (!Number.isFinite(failureCooldownMs) || failureCooldownMs < 0)
+    throw new Error("jwks: failureCooldownMs must be non-negative")
   if (!Number.isFinite(cacheMs) || cacheMs < 0)
     throw new Error("jwks: cacheMs must be non-negative")
   if (!Number.isFinite(staleMs) || staleMs < 0)
@@ -440,30 +473,69 @@ export function jwks(options: JwksOptions): JwtKeyResolver {
   }
   let cached: readonly JwkKey[] = []
   let cachedAt = 0
+  let refreshedAt = Number.NEGATIVE_INFINITY
   let pending: Promise<readonly JwkKey[]> | undefined
+  // When the last fetch failed or returned no keys, and its error (none for an empty set).
+  let failedAt = Number.NEGATIVE_INFINITY
+  let failure: { readonly error: unknown } | undefined
+
+  const refresh = (): Promise<readonly JwkKey[]> => {
+    if (pending === undefined) {
+      refreshedAt = Date.now()
+      pending = fetchJwks({ url, fetch: fetcher, timeoutMs, maxBytes })
+        .then(
+          (keys) => {
+            cached = keys
+            cachedAt = Date.now()
+            failedAt = keys.length === 0 ? cachedAt : Number.NEGATIVE_INFINITY
+            failure = undefined
+            return keys
+          },
+          (error: unknown) => {
+            failedAt = Date.now()
+            failure = { error }
+            throw error
+          },
+        )
+        .finally(() => {
+          pending = undefined
+        })
+    }
+    return pending
+  }
 
-  const load = async (): Promise<readonly JwkKey[]> => {
-    const now = Date.now()
-    if (cached.length > 0 && now - cachedAt < cacheMs) return cached
-    pending ??= fetchJwks({ url, fetch: fetcher, timeoutMs, maxBytes }).finally(() => {
-      pending = undefined
-    })
-    try {
-      cached = await pending
-      cachedAt = Date.now()
-      return cached
-    } catch (error) {
-      if (cached.length > 0 && staleMs > 0 && Date.now() - cachedAt < cacheMs + staleMs) {
-        return cached
-      }
-      throw error
+  const coolingDown = (): boolean =>
+    pending === undefined && Date.now() - failedAt < failureCooldownMs
+
+  const load = (): Promise<readonly JwkKey[]> => {
+    const age = Date.now() - cachedAt
+    if (cached.length > 0 && age < cacheMs) return Promise.resolve(cached)
+    if (cached.length > 0 && age < cacheMs + staleMs) {
+      if (!coolingDown()) refresh().catch(() => {})
+      return Promise.resolve(cached)
+    }
+    if (coolingDown()) {
+      return failure === undefined ? Promise.resolve(cached) : Promise.reject(failure.error)
     }
+    return refresh()
   }
 
   return async (header) => {
-    if (typeof header.kid !== "string" || header.kid === "") return null
-    const keys = await load()
+    const kid = header.kid
+    if (typeof kid !== "string" || kid === "") return null
     const alg = header.alg as JwtAlgorithm
-    return keys.find((key) => key.kid === header.kid && validateJwkForAlg(key, alg, header.kid))
+    const find = (keys: readonly JwkKey[]): JwkKey | undefined =>
+      keys.find((key) => key.kid === kid && validateJwkForAlg(key, alg, kid))
+    const found = find(await load())
+    if (found !== undefined) return found
+    // A kid the set lacks may be a key the provider just rotated in.
+    if (coolingDown() || (pending === undefined && Date.now() - refreshedAt < cooldownMs)) {
+      return undefined
+    }
+    try {
+      return find(await refresh())
+    } catch {
+      return undefined
+    }
   }
 }

package/src/language.ts

@@ -81,6 +81,15 @@ export function pickLanguage<const L extends readonly string[]>(
   return { language: defaultLanguage, matched: "default" }
 }
 
+/** `value` naming each of `names` once; `Vary: *` already covers every request header. */
+function varyOn(value: string | null, names: readonly string[]): string {
+  if (value === null || value.trim() === "") return names.join(", ")
+  const fields = value.split(",").map((field) => field.trim().toLowerCase())
+  if (fields.includes("*")) return value
+  const missing = names.filter((name) => !fields.includes(name.toLowerCase()))
+  return missing.length === 0 ? value : `${value}, ${missing.join(", ")}`
+}
+
 /**
  * Derives `c.language` from `Accept-Language` and emits `Content-Language` by default.
  *
@@ -114,6 +123,8 @@ export function language<const L extends readonly string[]>(
         .use(
           withResponseObserver<Middleware>({
             onResponseHeaders(headers, req) {
+              // The language is chosen from Accept-Language, so a shared cache must key on it.
+              headers.set("vary", varyOn(headers.get("vary"), ["Accept-Language"]))
               if (!emitHeader) return
               if (headers.has("content-language")) return
               const match = pickLanguage(req.header("accept-language"), supported, defaultLanguage)

package/src/openapi.ts

@@ -11,7 +11,12 @@ export interface RouteLike {
   // `| undefined` (not just `?`) so a core `RouteDescriptor` - whose `schema` is a *required*
   // `RouteSchema | undefined` - is assignable under `exactOptionalPropertyTypes`.
   readonly schema?:
-    | { readonly body?: unknown; readonly query?: unknown; readonly response?: unknown }
+    | {
+        readonly body?: unknown
+        readonly query?: unknown
+        readonly response?: unknown
+        readonly sse?: unknown
+      }
     | undefined
 }
 
@@ -40,11 +45,23 @@ export interface OpenApiUiOptions {
   readonly path?: string
   /** Page title. Defaults to `info.title`. */
   readonly title?: string
-  /** The Scalar script URL (loaded from a CDN). Default jsDelivr's `@scalar/api-reference`. */
+  /**
+   * The Scalar script URL. Default: `@scalar/api-reference` 1.72.1's standalone build on jsDelivr,
+   * pinned by {@link integrity}. Point it at a copy you serve yourself (no third-party origin to
+   * allow in a `script-src` policy, nothing to trust but your own deploy).
+   */
   readonly cdn?: string
+  /**
+   * The script's Subresource Integrity hash (`sha384-...`), which makes the browser refuse a script
+   * whose bytes differ. Default: the default build's hash when `cdn` is unset, none when it is set.
+   * Pass the hash of your own copy, or `false` to send none.
+   */
+  readonly integrity?: string | false
 }
 
 export interface OpenApiOptions {
+  /** The OpenAPI version to declare. `"3.2.0"` describes each SSE event with the standard `itemSchema`. */
+  readonly openapiVersion?: "3.1.0" | "3.2.0"
   readonly info?: OpenApiInfo
   readonly servers?: readonly OpenApiServer[]
   /** Tag definitions (top-level `tags`). Reference them from an operation via `operations`. */
@@ -91,6 +108,7 @@ export function buildOpenApiDocument(
   // and the shim only satisfies it structurally.
   const appShim = { routes: () => included } as unknown as Parameters<typeof toOpenAPI>[0]
   return toOpenAPI(appShim, {
+    ...(options.openapiVersion !== undefined ? { openapiVersion: options.openapiVersion } : {}),
     title: options.info?.title ?? "nifra API",
     version: options.info?.version ?? "0.0.0",
     ...(options.info?.description !== undefined ? { description: options.info.description } : {}),
@@ -102,16 +120,34 @@ export function buildOpenApiDocument(
   }) as unknown as Record<string, unknown>
 }
 
-const SCALAR_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+// An exact version, so the page always loads the bytes SCALAR_INTEGRITY names: a bare package URL
+// follows `latest`, and anyone who can publish to it could run script on the API's own origin.
+const SCALAR_CDN =
+  "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js"
+// SHA-384 of that file, the same from the npm tarball (checked against its registry integrity) and
+// from jsDelivr. Bump both together.
+const SCALAR_INTEGRITY = "sha384-U11tb2XnKvmwt8RlTvnwUnYgrN+ur4Xyh9htLhjajWNR/Oyl5AX5DEz00qRmlrmK"
+
+// Named per call, so a second, differently configured instance applies instead of being deduped.
+let instances = 0
 
 /**
  * Minimal HTML that mounts the Scalar API reference against a spec URL. The interpolated values are
  * dev-provided config (not request input), but they're still escaped so a stray quote or `<` can't
  * break the markup.
  */
-function scalarPage(specUrl: string, title: string, cdn: string): string {
+function scalarPage(
+  specUrl: string,
+  title: string,
+  cdn: string,
+  integrity: string | undefined,
+): string {
   const attr = (s: string): string => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;")
   const text = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;")
+  // SRI on a cross-origin script needs a CORS fetch; without a hash, a plain fetch keeps a copy
+  // served without CORS headers loading.
+  const pinned =
+    integrity === undefined ? "" : ` integrity="${attr(integrity)}" crossorigin="anonymous"`
   return `<!doctype html>
 <html>
   <head>
@@ -121,7 +157,7 @@ function scalarPage(specUrl: string, title: string, cdn: string): string {
   </head>
   <body>
     <script id="api-reference" data-url="${attr(specUrl)}"></script>
-    <script src="${attr(cdn)}"></script>
+    <script src="${attr(cdn)}"${pinned}></script>
   </body>
 </html>`
 }
@@ -132,9 +168,11 @@ function scalarPage(specUrl: string, title: string, cdn: string): string {
  * **lazy + memoized**: it reads `app.routes()` on the first request, by which point every route is
  * registered - so the plugin's own position in the chain doesn't matter.
  *
- * Pass `ui: true` (or `ui: { path, title, cdn }`) to also serve a Scalar API-reference page (default
- * `/reference`) that renders the spec. The page loads Scalar from a CDN; pin/self-host via `ui.cdn`,
- * and remember to allow that origin if you ship a `script-src` Content-Security-Policy.
+ * Pass `ui: true` (or `ui: { path, title, cdn, integrity }`) to also serve a Scalar API-reference page
+ * (default `/reference`) that renders the spec. By default the page loads an exact Scalar version from
+ * jsDelivr with a Subresource Integrity hash, so a changed file is refused rather than run on your
+ * origin. Self-host it via `ui.cdn` (with your copy's `ui.integrity`), and allow the script's origin if
+ * you ship a `script-src` Content-Security-Policy.
  *
  * ```ts
  * app.use(openapi({ info: { title: "My API", version: "1.0.0" }, ui: true }))
@@ -149,7 +187,7 @@ export function openapi(options: OpenApiOptions = {}): IdentityPlugin {
   let uiCached: string | undefined
   // A router plugin: it serves the spec (and optionally the UI page) as a side effect and returns the
   // app type-unchanged, so every route declared after `.use(openapi())` keeps its types.
-  return defineRouterPlugin("openapi", (app) => {
+  return defineRouterPlugin(`openapi#${++instances}`, (app) => {
     // Capture `app` (the same mutable builder every later `.get()`/`.post()` registers on) and read its
     // routes lazily, at request time - so all routes exist regardless of where the plugin sits.
     app.register("GET", docPath, undefined, () => {
@@ -166,8 +204,12 @@ export function openapi(options: OpenApiOptions = {}): IdentityPlugin {
     if (ui !== undefined && uiPath !== undefined) {
       const title = ui.title ?? options.info?.title ?? "nifra API"
       const cdn = ui.cdn ?? SCALAR_CDN
+      const integrity =
+        ui.integrity === false
+          ? undefined
+          : (ui.integrity ?? (ui.cdn === undefined ? SCALAR_INTEGRITY : undefined))
       app.register("GET", uiPath, undefined, () => {
-        uiCached ??= scalarPage(docPath, title, cdn)
+        uiCached ??= scalarPage(docPath, title, cdn, integrity)
         return new Response(uiCached, { headers: { "content-type": "text/html; charset=utf-8" } })
       })
     }