@nifrajs/middleware 1.6.0 → 1.11.0

package/src/admission.ts

@@ -0,0 +1,329 @@
+import type { AdmissionController, AdmissionDecision } from "@nifrajs/core"
+
+/**
+ * Adaptive capacity admission. Rate limiting bounds request *frequency* and `@nifrajs/budget` bounds
+ * request *duration*; neither stops a healthy instance from accepting more *concurrent* work than it
+ * can finish. This gate admits on live capacity evidence — in-flight count + event-loop lag — briefly
+ * queues at the edge, and sheds the rest with `429` + `Retry-After`, so p99 stays bounded under load
+ * instead of collapsing.
+ *
+ * Public mechanics (in-flight + loop lag) know nothing about tenants. An application-supplied {@link AdmissionPolicy}
+ * hook layers tenant priority and reserved capacity on top without leaking
+ * those concerns into the OSS core.
+ *
+ * Wire it as the server's `admission` option (NOT an `onRequest` hook — a hook disables the native
+ * route table). Off by default: when unset, the request path is untouched.
+ */
+
+export type ShedReason = "inflight" | "loop-lag" | "queue-timeout" | "policy" | "cancelled"
+
+/** Pure capacity evidence handed to the policy hook. The mechanics never invent tenant concepts. */
+export interface AdmissionEvidence {
+  readonly inFlight: number
+  readonly maxInFlight: number
+  readonly lagMs: number
+  readonly maxLagMs: number
+  readonly queued: number
+}
+
+/**
+ * Application-supplied admission policy. Return a decision to override the default mechanics
+ * for this request, or `undefined` to defer to them. `admit` may draw from reserved headroom above
+ * `maxInFlight`; `shed` forces rejection.
+ */
+export type AdmissionPolicy = (
+  req: Request,
+  evidence: AdmissionEvidence,
+) => { decision: "admit" | "shed"; retryAfterSec?: number } | undefined
+
+export interface AdmissionOptions {
+  /** Max requests running concurrently before the gate queues or sheds. */
+  readonly maxInFlight: number
+  /** Event-loop lag ceiling (ms); above it, shed even when slots are free (protects p99). Default ∞. */
+  readonly maxLagMs?: number
+  /** How many requests may briefly wait for a slot before shedding. `0` (default) never queues. */
+  readonly maxQueue?: number
+  /** How long a queued request waits for a slot before shedding. Default 50ms. */
+  readonly queueTimeoutMs?: number
+  /** Reserved slots ABOVE `maxInFlight` that only a policy `admit` may draw from. Default 0. */
+  readonly reservedForPolicy?: number
+  /** Base `Retry-After`, in seconds, for shed responses. Default 1. */
+  readonly baseRetryAfterSec?: number
+  /**
+   * Live event-loop lag source, in ms. Pass {@link createEventLoopLagSampler} to sample the real loop;
+   * default `() => 0` disables lag-based shedding (in-flight only).
+   */
+  readonly lagMs?: () => number
+  readonly policy?: AdmissionPolicy
+  /** Test seam for deterministic queue timeouts; defaults to real timers. */
+  readonly setTimer?: (fn: () => void, ms: number) => { cancel(): void }
+}
+
+export interface AdmissionSnapshot {
+  readonly inFlight: number
+  readonly queued: number
+  readonly fastPathAdmits: number
+  readonly slowPathEntries: number
+  readonly everQueued: number
+  readonly shed: number
+}
+
+export interface AdmissionControllerHandle extends AdmissionController {
+  /** Point-in-time counters for observability (otel gauges/counters). */
+  snapshot(): AdmissionSnapshot
+}
+
+interface Waiter {
+  settled: boolean
+  transfer(): void
+  shed(): void
+  cancel(): void
+  cleanup(): void
+  timer: { cancel(): void }
+}
+
+const OVERLOADED_BODY = JSON.stringify({ ok: false, error: "overloaded" })
+
+/** The slice of a `perf_hooks` event-loop-delay histogram the sampler needs. */
+export interface LoopDelayHistogram {
+  enable(): void
+  reset(): void
+  readonly mean: number
+}
+
+/**
+ * Acquires a loop-delay histogram for a resolution, or `undefined` when the runtime has none. This is
+ * an optional test/runtime seam; the default sampler is a portable timer-drift monitor.
+ */
+export type LoopDelayMonitor = (resolutionMs: number) => LoopDelayHistogram | undefined
+
+/** Shared no-op sampler — the fallback when an explicitly supplied monitor has no histogram. */
+const NO_LAG: () => number = () => 0
+
+/**
+ * Event-loop-lag sampler. By default it measures timer drift using only Web/JS runtime primitives, so
+ * it works under Node ESM, Bun, Deno, and workers without a hidden CommonJS `require` fallback. An
+ * injected histogram remains available for deterministic tests or a runtime-native monitor. Each read
+ * returns recent mean lag and resets the sampling window.
+ */
+export function createEventLoopLagSampler(
+  resolutionMs = 20,
+  monitor?: LoopDelayMonitor,
+): () => number {
+  if (!Number.isFinite(resolutionMs) || resolutionMs <= 0) {
+    throw new RangeError("admission: resolutionMs must be a finite positive number")
+  }
+  if (monitor === undefined) {
+    let expected = performance.now() + resolutionMs
+    let totalLagMs = 0
+    let samples = 0
+    const timer = setInterval(() => {
+      const now = performance.now()
+      totalLagMs += Math.max(0, now - expected)
+      samples++
+      // Reset from `now` so one long stall is measured once instead of as a train of catch-up ticks.
+      expected = now + resolutionMs
+    }, resolutionMs)
+    // A metrics sampler must never keep a Node/Bun process alive by itself. Browser/Deno numeric timer
+    // handles simply do not expose `unref`.
+    ;(timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.()
+    return () => {
+      const mean = samples === 0 ? 0 : totalLagMs / samples
+      totalLagMs = 0
+      samples = 0
+      return Number.isFinite(mean) ? mean : 0
+    }
+  }
+  let histogram: LoopDelayHistogram | undefined
+  try {
+    histogram = monitor(resolutionMs)
+  } catch {
+    return NO_LAG
+  }
+  if (histogram === undefined) return NO_LAG
+  histogram.enable()
+  return () => {
+    const meanNs = histogram.mean
+    histogram.reset()
+    return Number.isFinite(meanNs) ? Math.max(0, meanNs / 1e6 - resolutionMs) : 0
+  }
+}
+
+/**
+ * Build a capacity-admission controller. Pass the returned handle as the server's `admission` option.
+ */
+export function createAdmissionController(options: AdmissionOptions): AdmissionControllerHandle {
+  const maxInFlight = options.maxInFlight
+  if (!Number.isInteger(maxInFlight) || maxInFlight < 1) {
+    throw new Error("admission: maxInFlight must be a positive integer")
+  }
+  const maxLagMs = options.maxLagMs ?? Number.POSITIVE_INFINITY
+  if (Number.isNaN(maxLagMs) || maxLagMs < 0) {
+    throw new Error("admission: maxLagMs must be a non-negative number")
+  }
+  const maxQueue = options.maxQueue ?? 0
+  if (!Number.isInteger(maxQueue) || maxQueue < 0) {
+    throw new Error("admission: maxQueue must be a non-negative integer")
+  }
+  const queueTimeoutMs = options.queueTimeoutMs ?? 50
+  const reserved = options.reservedForPolicy ?? 0
+  const baseRetryAfterSec = options.baseRetryAfterSec ?? 1
+  if (!Number.isFinite(queueTimeoutMs) || queueTimeoutMs < 0) {
+    throw new Error("admission: queueTimeoutMs must be a finite non-negative number")
+  }
+  if (!Number.isInteger(reserved) || reserved < 0) {
+    throw new Error("admission: reservedForPolicy must be a non-negative integer")
+  }
+  if (!Number.isFinite(baseRetryAfterSec) || baseRetryAfterSec <= 0) {
+    throw new Error("admission: baseRetryAfterSec must be a finite positive number")
+  }
+  const lagMs = options.lagMs ?? (() => 0)
+  const policy = options.policy
+  const setTimer =
+    options.setTimer ??
+    ((fn, ms) => {
+      const id = setTimeout(fn, ms)
+      return { cancel: () => clearTimeout(id) }
+    })
+
+  let inFlight = 0
+  const queue: Waiter[] = []
+  const stats = { fastPathAdmits: 0, slowPathEntries: 0, everQueued: 0, shed: 0 }
+
+  const shedResponse = (
+    reason: ShedReason,
+    retryAfterSec = baseRetryAfterSec,
+  ): AdmissionDecision => {
+    const retry =
+      Number.isFinite(retryAfterSec) && retryAfterSec >= 0 ? retryAfterSec : baseRetryAfterSec
+    stats.shed++
+    return {
+      admitted: false,
+      response: new Response(OVERLOADED_BODY, {
+        status: 429,
+        headers: {
+          "content-type": "application/json",
+          "retry-after": String(Math.max(1, Math.ceil(retry))),
+          "x-nifra-shed-reason": reason,
+        },
+      }),
+    }
+  }
+
+  const cancelledResponse = (): AdmissionDecision => ({
+    admitted: false,
+    response: new Response(JSON.stringify({ ok: false, error: "request_cancelled" }), {
+      status: 499,
+      headers: {
+        "content-type": "application/json",
+        "x-nifra-shed-reason": "cancelled",
+      },
+    }),
+  })
+
+  // A release handle over an already-occupied slot. Decrement first, then transfer only when total
+  // occupancy is below the public limit. This matters when policy traffic occupies reserved headroom:
+  // releasing a reserved slot must NOT hand that capacity to an ordinary queued request.
+  const makeHandle = (): AdmissionDecision => {
+    let released = false
+    return {
+      admitted: true,
+      release() {
+        if (released) return
+        released = true
+        inFlight--
+        while (inFlight < maxInFlight && queue.length > 0) {
+          const next = queue.shift() as Waiter
+          if (next.settled) continue
+          next.settled = true
+          next.cleanup()
+          inFlight++
+          next.transfer()
+          return
+        }
+      },
+    }
+  }
+
+  /** Take a brand-new slot (fast path, policy admit, reserved headroom). */
+  const occupy = (): AdmissionDecision => {
+    inFlight++
+    return makeHandle()
+  }
+
+  function admit(req: Request): AdmissionDecision | Promise<AdmissionDecision> {
+    const measuredLag = lagMs()
+    // Invalid capacity evidence must not silently turn protection off.
+    const lag =
+      Number.isFinite(measuredLag) && measuredLag >= 0 ? measuredLag : Number.POSITIVE_INFINITY
+    const evidence: AdmissionEvidence = {
+      inFlight,
+      maxInFlight,
+      lagMs: lag,
+      maxLagMs,
+      queued: queue.length,
+    }
+
+    // Policy hook first: may force-admit (reserved headroom) or force-shed.
+    if (policy !== undefined) {
+      const verdict = policy(req, evidence)
+      if (verdict?.decision === "shed")
+        return shedResponse("policy", verdict.retryAfterSec ?? baseRetryAfterSec)
+      if (verdict?.decision === "admit") {
+        return inFlight < maxInFlight + reserved ? occupy() : shedResponse("policy")
+      }
+    }
+
+    // Loop-lag shed: the box is behind on the event loop — reject regardless of slot count.
+    if (lag > maxLagMs) return shedResponse("loop-lag")
+
+    // FAST PATH (O(1)): a slot is free and lag is fine. No timer, no queue, no extra await.
+    if (inFlight < maxInFlight) {
+      stats.fastPathAdmits++
+      return occupy()
+    }
+
+    // SLOW PATH: saturated. Briefly queue, else shed.
+    stats.slowPathEntries++
+    if (maxQueue <= 0 || queue.length >= maxQueue) return shedResponse("inflight")
+    stats.everQueued++
+    return new Promise<AdmissionDecision>((resolve) => {
+      const remove = (waiter: Waiter): void => {
+        const i = queue.indexOf(waiter)
+        if (i >= 0) queue.splice(i, 1)
+      }
+      const waiter: Waiter = {
+        settled: false,
+        transfer: () => resolve(makeHandle()),
+        shed: () => resolve(shedResponse("queue-timeout")),
+        cancel: () => resolve(cancelledResponse()),
+        cleanup: () => {
+          waiter.timer.cancel()
+          req.signal.removeEventListener("abort", onAbort)
+        },
+        timer: setTimer(() => {
+          if (waiter.settled) return
+          waiter.settled = true
+          remove(waiter)
+          waiter.cleanup()
+          waiter.shed()
+        }, queueTimeoutMs),
+      }
+      const onAbort = (): void => {
+        if (waiter.settled) return
+        waiter.settled = true
+        remove(waiter)
+        waiter.cleanup()
+        waiter.cancel()
+      }
+      queue.push(waiter)
+      req.signal.addEventListener("abort", onAbort, { once: true })
+      if (req.signal.aborted) onAbort()
+    })
+  }
+
+  return {
+    admit,
+    snapshot: () => ({ inFlight, queued: queue.length, ...stats }),
+  }
+}

package/src/basic-auth.ts

@@ -1,4 +1,5 @@
 import { definePlugin, type NifraPlugin } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import {
   decodeBase64,
   jsonError,
@@ -98,7 +99,14 @@ export function basicAuth<P>(
       return optional ? undefined : reject(realm)
     }),
   )
-  return Object.assign(plugin, {
+  const instrumented = optional
+    ? plugin
+    : withRouteAssurance(plugin, {
+        id: NIFRA_ASSURANCE.AUTHENTICATED,
+        source: "basicAuth",
+        scope: "subsequent",
+      })
+  return Object.assign(instrumented, {
     principal: (request: Request): P | string | null => store.get(request) ?? null,
     requirePrincipal: (request: Request): P | string => {
       const principal = store.get(request)

package/src/body-limit.ts

@@ -1,4 +1,5 @@
-import type { Middleware } from "@nifrajs/core"
+import { METHODS, type Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { jsonError, SAFE_METHODS } from "./_utils.ts"
 
 export interface BodyLimitOptions {
@@ -35,7 +36,7 @@ export function bodyLimit(options: BodyLimitOptions): Middleware {
   const error = options.error ?? "payload_too_large"
   const allowLengthless = options.allowLengthless === true
 
-  return {
+  const middleware: Middleware = {
     name: "body-limit",
     onRequest(req) {
       if (methods !== undefined ? !methods.has(req.method) : SAFE_METHODS.has(req.method)) {
@@ -50,4 +51,16 @@ export function bodyLimit(options: BodyLimitOptions): Middleware {
       return undefined
     },
   }
+  // Lengthless bodies are deliberately allowed in this mode, so claiming BODY_BOUNDED for the
+  // whole route would be false. The middleware still enforces declared Content-Length at runtime.
+  if (allowLengthless) return middleware
+  return withRouteAssurance(middleware, {
+    id: NIFRA_ASSURANCE.BODY_BOUNDED,
+    source: "body-limit",
+    scope: "global",
+    methods:
+      options.methods === undefined
+        ? ["POST", "PUT", "PATCH", "DELETE"]
+        : METHODS.filter((method) => methods?.has(method)),
+  })
 }

package/src/csrf.ts

@@ -1,4 +1,5 @@
-import type { Middleware } from "@nifrajs/core"
+import { METHODS, type Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import {
   base64UrlEncode,
   hmacSha256,
@@ -84,7 +85,7 @@ export function csrf(options: CsrfOptions): Middleware {
   const origins = options.origins !== undefined ? new Set(options.origins) : undefined
   const checkOrigin = options.checkOrigin !== false
 
-  return {
+  const middleware: Middleware = {
     name: "csrf",
     async onRequest(req) {
       if (!protectedMethod(req.method, methods)) return undefined
@@ -99,4 +100,15 @@ export function csrf(options: CsrfOptions): Middleware {
       return (await verifyCsrfToken(cookieToken, key)) ? undefined : jsonError(403, "csrf_failed")
     },
   }
+  return withRouteAssurance(middleware, {
+    id: NIFRA_ASSURANCE.CSRF,
+    source: "csrf",
+    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)),
+  })
 }

package/src/idempotency.ts

@@ -1,4 +1,5 @@
-import type { Middleware } from "@nifrajs/core"
+import { METHODS, type Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 
 /**
  * Idempotency keys for unsafe requests — a client retrying a `POST` (dropped connection, impatient
@@ -280,7 +281,7 @@ export function idempotency(options: IdempotencyOptions): Middleware {
   const keyOf = options.key ?? defaultIdempotencyKey
   const claimed = new WeakMap<Request, string>()
 
-  return {
+  const middleware: Middleware = {
     name: "idempotency",
     async onRequest(req) {
       if (!methods.has(req.method.toUpperCase())) return undefined
@@ -326,4 +327,10 @@ export function idempotency(options: IdempotencyOptions): Middleware {
       return captured.response
     },
   }
+  return withRouteAssurance(middleware, {
+    id: NIFRA_ASSURANCE.IDEMPOTENCY_KEY,
+    source: "idempotency",
+    scope: "global",
+    methods: METHODS.filter((method) => methods.has(method)),
+  })
 }

package/src/index.ts

@@ -6,6 +6,18 @@
  * `c.requestId` into the handler context.
  */
 
+export {
+  type AdmissionControllerHandle,
+  type AdmissionEvidence,
+  type AdmissionOptions,
+  type AdmissionPolicy,
+  type AdmissionSnapshot,
+  createAdmissionController,
+  createEventLoopLagSampler,
+  type LoopDelayHistogram,
+  type LoopDelayMonitor,
+  type ShedReason,
+} from "./admission.ts"
 export {
   type BasicAuthPlugin,
   type BasicAuthStaticOptions,

package/src/ip-restriction.ts

@@ -1,4 +1,5 @@
 import type { Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { jsonError, type MaybePromise } from "./_utils.ts"
 
 export type IpMatcher = string | ((ip: string, request: Request) => MaybePromise<boolean>)
@@ -170,18 +171,28 @@ export function ipRestriction(options: IpRestrictionOptions): Middleware {
   }
   const error = options.error ?? "ip_forbidden"
 
-  return {
-    name: "ip-restriction",
-    async onRequest(req) {
-      const ipText = await resolveClientIp(req, options)
-      if (ipText === null) return jsonError(403, error)
-      const ip = parseIp(ipText)
-      if (ip === null) return jsonError(403, error)
-      if (await matches(ipText, ip, deny, req)) return jsonError(403, error)
-      if (allow.ranges.length + allow.fns.length > 0 && !(await matches(ipText, ip, allow, req))) {
-        return jsonError(403, error)
-      }
-      return undefined
+  return withRouteAssurance<Middleware>(
+    {
+      name: "ip-restriction",
+      async onRequest(req) {
+        const ipText = await resolveClientIp(req, options)
+        if (ipText === null) return jsonError(403, error)
+        const ip = parseIp(ipText)
+        if (ip === null) return jsonError(403, error)
+        if (await matches(ipText, ip, deny, req)) return jsonError(403, error)
+        if (
+          allow.ranges.length + allow.fns.length > 0 &&
+          !(await matches(ipText, ip, allow, req))
+        ) {
+          return jsonError(403, error)
+        }
+        return undefined
+      },
     },
-  }
+    {
+      id: NIFRA_ASSURANCE.IP_RESTRICTED,
+      source: "ip-restriction",
+      scope: "global",
+    },
+  )
 }

package/src/jwt.ts

@@ -1,4 +1,5 @@
 import { definePlugin, type NifraPlugin } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import {
   base64UrlDecode,
   jsonError,
@@ -318,7 +319,14 @@ export function jwt<C extends JwtClaims = JwtClaims>(options: JwtOptions): JwtPl
       }
     }),
   )
-  return Object.assign(plugin, {
+  const instrumented = optional
+    ? plugin
+    : withRouteAssurance(plugin, {
+        id: NIFRA_ASSURANCE.AUTHENTICATED,
+        source: "jwt",
+        scope: "subsequent",
+      })
+  return Object.assign(instrumented, {
     claims: (request: Request): C | null => store.get(request) ?? null,
     requireClaims: (request: Request): C => {
       const claims = store.get(request)

package/src/rate-limit.ts

@@ -1,4 +1,5 @@
 import type { Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 
 export interface RateLimitResult {
   /** Hits recorded in the current window, including this one. */
@@ -216,7 +217,7 @@ export function rateLimit(options: RateLimitOptions): Middleware {
     options.key ?? ((req: Request) => defaultKey(req, trustedProxies, header, allowGlobalKey))
   const quota = new WeakMap<Request, { remaining: number; resetSeconds: number }>()
 
-  return {
+  const middleware: Middleware = {
     name: "rate-limit",
     async onRequest(req) {
       const key = keyOf(req)
@@ -245,4 +246,9 @@ export function rateLimit(options: RateLimitOptions): Middleware {
       return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
     },
   }
+  return withRouteAssurance(middleware, {
+    id: NIFRA_ASSURANCE.RATE_LIMITED,
+    source: "rate-limit",
+    scope: "global",
+  })
 }

package/src/security-headers.ts

@@ -1,4 +1,5 @@
 import type { Middleware } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { withHeaders } from "./_utils.ts"
 
 export interface SecurityHeadersOptions {
@@ -35,17 +36,24 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
     hstsValue = parts.join("; ")
   }
 
-  return {
-    name: "security-headers",
-    // Mutate in place on the common (mutable-headers) response; clone only for an immutable one
-    // (see withHeaders — the old always-clone was ~3% of a realistic request).
-    onResponse: (res) =>
-      withHeaders(res, (headers) => {
-        headers.set("X-Content-Type-Options", "nosniff")
-        headers.set("X-Frame-Options", frameOptions)
-        headers.set("Referrer-Policy", referrerPolicy)
-        if (hstsValue !== undefined) headers.set("Strict-Transport-Security", hstsValue)
-        if (csp !== undefined) headers.set("Content-Security-Policy", csp)
-      }),
-  }
+  return withRouteAssurance<Middleware>(
+    {
+      name: "security-headers",
+      // Mutate in place on the common (mutable-headers) response; clone only for an immutable one
+      // (see withHeaders — the old always-clone was ~3% of a realistic request).
+      onResponse: (res) =>
+        withHeaders(res, (headers) => {
+          headers.set("X-Content-Type-Options", "nosniff")
+          headers.set("X-Frame-Options", frameOptions)
+          headers.set("Referrer-Policy", referrerPolicy)
+          if (hstsValue !== undefined) headers.set("Strict-Transport-Security", hstsValue)
+          if (csp !== undefined) headers.set("Content-Security-Policy", csp)
+        }),
+    },
+    {
+      id: NIFRA_ASSURANCE.SECURITY_HEADERS,
+      source: "security-headers",
+      scope: "global",
+    },
+  )
 }

package/src/token-auth.ts

@@ -1,4 +1,5 @@
 import { definePlugin, type NifraPlugin } from "@nifrajs/core"
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -59,7 +60,14 @@ function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
       return config.optional ? undefined : reject() // 401 short-circuits (skips the handler)
     }),
   )
-  return Object.assign(plugin, {
+  const instrumented = config.optional
+    ? plugin
+    : withRouteAssurance(plugin, {
+        id: NIFRA_ASSURANCE.AUTHENTICATED,
+        source: config.name,
+        scope: "subsequent",
+      })
+  return Object.assign(instrumented, {
     principal: (request: Request): P | null => store.get(request) ?? null,
     requirePrincipal: (request: Request): P => {
       const principal = store.get(request)