@nifrajs/middleware 2.1.0 → 2.3.0

package/dist/openapi.js

@@ -1,5 +1,5 @@
 import { definePlugin } from "@nifrajs/core/server";
-// The OpenAPI generator only — `@nifrajs/schema/openapi` is pure (no TypeBox runtime), so the openapi()
+// The OpenAPI generator only - `@nifrajs/schema/openapi` is pure (no TypeBox runtime), so the openapi()
 // plugin gets full `t`-schema introspection without pulling the `t` builder into every consumer.
 import { toOpenAPI } from "@nifrajs/schema/openapi";
 /**
@@ -55,10 +55,10 @@ function scalarPage(specUrl, title, cdn) {
 </html>`;
 }
 /**
- * Serve an OpenAPI 3.1 document (a structural subset — see {@link buildOpenApiDocument}) at
+ * Serve an OpenAPI 3.1 document (a structural subset - see {@link buildOpenApiDocument}) at
  * `options.path` (default `/openapi.json`), generated from the app's registered routes. Generation is
  * **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.
+ * 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`,
@@ -76,7 +76,7 @@ export function openapi(options = {}) {
     let uiCached;
     return definePlugin("openapi", (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.
+        // routes lazily, at request time - so all routes exist regardless of where the plugin sits.
         app.register("GET", docPath, undefined, () => {
             cached ??= JSON.stringify(buildOpenApiDocument(app.routes(), {
                 ...options,

package/dist/pretty-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pretty-json.d.ts","sourceRoot":"","sources":["../src/pretty-json.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAC7D;AAqCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,kIA0CzD"}
+{"version":3,"file":"pretty-json.d.ts","sourceRoot":"","sources":["../src/pretty-json.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAC7D;AA6FD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,kIAgDzD"}

package/dist/pretty-json.js

@@ -10,29 +10,75 @@ function parseLength(value) {
         return undefined;
     return Number(value);
 }
-async function readTextCapped(res, maxBytes) {
-    const body = res.clone().body;
+/** Re-emit the bytes already pulled, then the untouched remainder of the same reader. */
+function replayFrom(res, chunks, reader) {
+    const stream = new ReadableStream({
+        start(controller) {
+            for (const chunk of chunks)
+                controller.enqueue(chunk);
+        },
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                // No value and not done cannot happen for a byte stream, but it means the same thing here:
+                // there is nothing further to emit.
+                if (done || value === undefined)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            }
+            catch (error) {
+                // The upstream body failed; surface that to the client rather than truncating silently.
+                controller.error(error);
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+    return new Response(stream, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers,
+    });
+}
+/**
+ * Read up to `maxBytes` of a response, without disturbing it when the answer is "pass through".
+ *
+ * `Response.clone()` is the obvious way to peek and is a trap here. Cancelling the clone's reader once
+ * the cap is exceeded also stalls the ORIGINAL body in Bun, so an oversized streamed response hung the
+ * client instead of passing through - a hang, from a middleware whose entire job is cosmetic. (A clone
+ * read to completion is fine; only the cancel breaks it, which is why every buffered case passed and
+ * only a streamed one failed.) Abandoning the clone rather than cancelling it trades the hang for
+ * buffering the whole oversized body, which is the exact cost the cap exists to avoid.
+ *
+ * So the body is read directly and, when it proves too large, replayed: the bytes already pulled are
+ * re-emitted ahead of the rest of the same reader. No tee, nothing buffered past the cap, and the
+ * response the client receives is byte-for-byte the one the handler produced.
+ */
+async function peekText(res, maxBytes) {
+    const body = res.body;
     if (body === null)
-        return null;
+        return { response: res };
     const reader = body.getReader();
-    const decoder = new TextDecoder();
+    const chunks = [];
     let total = 0;
-    let text = "";
     try {
         while (true) {
             const { done, value } = await reader.read();
-            if (done)
-                return text + decoder.decode();
-            total += value.byteLength;
-            if (total > maxBytes) {
-                await reader.cancel();
-                return null;
+            if (done) {
+                const decoder = new TextDecoder();
+                let text = "";
+                for (const chunk of chunks)
+                    text += decoder.decode(chunk, { stream: true });
+                return { text: text + decoder.decode() };
             }
-            text += decoder.decode(value, { stream: true });
+            chunks.push(value);
+            total += value.byteLength;
+            if (total > maxBytes)
+                return { response: replayFrom(res, chunks, reader) };
         }
     }
     catch {
-        return null;
+        return { response: replayFrom(res, chunks, reader) };
     }
 }
 /**
@@ -66,15 +112,21 @@ export function prettyJson(options = {}) {
         const declared = parseLength(res.headers.get("content-length"));
         if (declared !== undefined && declared > maxBytes)
             return res;
-        const text = await readTextCapped(res, maxBytes);
-        if (text === null)
-            return res;
+        const peeked = await peekText(res, maxBytes);
+        if ("response" in peeked)
+            return peeked.response;
         let parsed;
         try {
-            parsed = JSON.parse(text);
+            parsed = JSON.parse(peeked.text);
         }
         catch {
-            return res;
+            // The body was read to decide that, so `res` can no longer be returned as-is. Rebuild it from
+            // the text: re-encoding UTF-8 reproduces the original bytes, so `content-length` still holds.
+            return new Response(peeked.text, {
+                status: res.status,
+                statusText: res.statusText,
+                headers: res.headers,
+            });
         }
         const headers = new Headers(res.headers);
         headers.delete("content-length");

package/dist/pretty-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"pretty-json.js","sourceRoot":"","sources":["../src/pretty-json.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pretty-json.js","sourceRoot":"","sources":["../src/pretty-json.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.d.ts

@@ -7,14 +7,14 @@ export interface RateLimitResult {
 }
 /**
  * Counter backend. Production deploys MUST use a shared store (Redis, etc.) so the
- * limit holds across instances — that's a user dependency, not ours, hence the
+ * limit holds across instances - that's a user dependency, not ours, hence the
  * interface. {@link MemoryStore} is for dev / single-instance only.
  */
 export interface RateLimitStore {
     hit(key: string, windowMs: number): Promise<RateLimitResult>;
 }
 export interface MemoryStoreOptions {
-    /** Allow the in-memory store in production. Off by default — a per-instance limiter is unsafe across instances. */
+    /** Allow the in-memory store in production. Off by default - a per-instance limiter is unsafe across instances. */
     readonly allowInProduction?: boolean;
     /** Hard cap on tracked client keys; expired keys are evicted first, then oldest active keys. Default `100_000`.
      * Bounds memory against an unbounded key space (bot scans, per-IP buckets). */
@@ -28,8 +28,8 @@ export interface MemoryStoreOptions {
  * Bounded against unbounded growth: expired windows are swept lazily (amortized, at most once per
  * `sweepIntervalMs`) and the key set is hard-capped at `maxKeys` (expired keys are evicted first,
  * then oldest active keys).
- * Without this, expired entries for keys never seen again — and the unbounded key space of a bot scan
- * — would accumulate in the map forever and OOM a single-instance deploy.
+ * Without this, expired entries for keys never seen again - and the unbounded key space of a bot scan
+ * - would accumulate in the map forever and OOM a single-instance deploy.
  */
 export declare class MemoryStore implements RateLimitStore {
     private readonly windows;
@@ -37,7 +37,7 @@ export declare class MemoryStore implements RateLimitStore {
     private readonly sweepIntervalMs;
     private lastSweep;
     private evictionScans;
-    /** Cumulative entries inspected by the eviction scan since construction — an eviction-pressure
+    /** Cumulative entries inspected by the eviction scan since construction - an eviction-pressure
      * gauge. The bounded scan keeps this ~O(1) per over-cap insert (≤ {@link MAX_EVICTION_SCAN}); a
      * regressed full O(n) sweep would make it ~maxKeys per insert (what the regression test asserts). */
     get evictionScanCount(): number;
@@ -58,13 +58,13 @@ export interface RateLimitOptions {
      * Default `0`.
      *
      * The default key reads the client IP from `X-Forwarded-For` as the address your **edge** proxy
-     * observed — the entry `trustedProxies` from the right (1 proxy → the rightmost hop; 2 → the
+     * observed - the entry `trustedProxies` from the right (1 proxy → the rightmost hop; 2 → the
      * second-from-right; …). Your proxies append on the right, so a client can only inject fake hops on
      * the *left*, which this skips → not spoofable when `trustedProxies` matches your topology.
      *
      * ⚠️ With the default `0`, `X-Forwarded-For` is treated as fully client-controlled and **ignored**.
      * Reading the
-     * *first* XFF hop — the old behavior — let any client mint a fresh bucket per request and defeat the
+     * *first* XFF hop - the old behavior - let any client mint a fresh bucket per request and defeat the
      * limiter. Set `trustedProxies` (only safe behind a proxy you control that appends XFF), configure a
      * trusted single-IP {@link header}, or supply a custom {@link key} (e.g. an authenticated user id).
      */
@@ -77,7 +77,7 @@ export interface RateLimitOptions {
      */
     readonly allowGlobalKey?: boolean;
     /**
-     * Bucket key for a request. Overrides the default XFF-based key entirely — set this for accurate
+     * Bucket key for a request. Overrides the default XFF-based key entirely - set this for accurate
      * per-client limiting (e.g. an authenticated user id, or a header your proxy sets). A `Middleware`
      * can't see the socket IP (that needs the server instance).
      */

package/dist/rate-limit.js

@@ -1,7 +1,7 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance";
 /** Max entries scanned (oldest-first) per eviction looking for an expired victim before falling back
  * to evicting the oldest-inserted. Bounds eviction to O(1) per insertion instead of a full O(n) sweep
- * under a distinct-key flood — the abuse the key cap defends against. */
+ * under a distinct-key flood - the abuse the key cap defends against. */
 const MAX_EVICTION_SCAN = 64;
 /**
  * In-process fixed-window store. Refuses to run in production unless explicitly allowed.
@@ -9,8 +9,8 @@ const MAX_EVICTION_SCAN = 64;
  * Bounded against unbounded growth: expired windows are swept lazily (amortized, at most once per
  * `sweepIntervalMs`) and the key set is hard-capped at `maxKeys` (expired keys are evicted first,
  * then oldest active keys).
- * Without this, expired entries for keys never seen again — and the unbounded key space of a bot scan
- * — would accumulate in the map forever and OOM a single-instance deploy.
+ * Without this, expired entries for keys never seen again - and the unbounded key space of a bot scan
+ * - would accumulate in the map forever and OOM a single-instance deploy.
  */
 export class MemoryStore {
     windows = new Map();
@@ -18,7 +18,7 @@ export class MemoryStore {
     sweepIntervalMs;
     lastSweep = 0;
     evictionScans = 0;
-    /** Cumulative entries inspected by the eviction scan since construction — an eviction-pressure
+    /** Cumulative entries inspected by the eviction scan since construction - an eviction-pressure
      * gauge. The bounded scan keeps this ~O(1) per over-cap insert (≤ {@link MAX_EVICTION_SCAN}); a
      * regressed full O(n) sweep would make it ~maxKeys per insert (what the regression test asserts). */
     get evictionScanCount() {
@@ -65,7 +65,7 @@ export class MemoryStore {
         if (this.windows.size <= this.maxKeys)
             return;
         // Prefer evicting an expired window over an active user's, but bound the work. A full sweep on
-        // every insertion is O(n)/request under a distinct-key flood — the exact abuse the cap defends
+        // every insertion is O(n)/request under a distinct-key flood - the exact abuse the cap defends
         // against. Scan only a small fixed budget (oldest-first, where expired entries cluster) for a
         // victim; if none is found, evict the oldest-inserted (O(1)). Expired entries beyond the budget
         // are still reclaimed by the amortized sweep in `hit`.

package/dist/request-id.d.ts

@@ -7,7 +7,7 @@ export interface RequestIdOptions {
 /**
  * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
  * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
- * threaded by `derive`), and echoes it on the response header. Idempotent — applying it twice is a
+ * threaded by `derive`), and echoes it on the response header. Idempotent - applying it twice is a
  * no-op.
  *
  * ```ts

package/dist/request-id.js

@@ -2,7 +2,7 @@ import { definePlugin } from "@nifrajs/core/server";
 /**
  * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
  * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
- * threaded by `derive`), and echoes it on the response header. Idempotent — applying it twice is a
+ * threaded by `derive`), and echoes it on the response header. Idempotent - applying it twice is a
  * no-op.
  *
  * ```ts

package/dist/security-headers.d.ts

@@ -1,6 +1,6 @@
 import type { Middleware } from "@nifrajs/core/server";
 export interface SecurityHeadersOptions {
-    /** `Strict-Transport-Security`. Off by default — opt in once you're sure you're HTTPS-only. */
+    /** `Strict-Transport-Security`. Off by default - opt in once you're sure you're HTTPS-only. */
     readonly hsts?: {
         readonly maxAge: number;
         readonly includeSubDomains?: boolean;

package/dist/security-headers.js

@@ -22,7 +22,7 @@ export function securityHeaders(options = {}) {
     return withRouteAssurance({
         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).
+        // (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);

package/dist/token-auth.d.ts

@@ -1,7 +1,7 @@
 import { type NifraPlugin } from "@nifrajs/core/server";
 type MaybePromise<T> = T | Promise<T>;
 /**
- * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` — it rejects unauthorized
+ * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` - it rejects unauthorized
  * requests to **routes defined after it** with `401` (unless `optional`). Read the verified principal
  * inside a handler/loader via {@link AuthPlugin.principal} (nullable) or
  * {@link AuthPlugin.requirePrincipal} (throws `401` when absent). The principal is verified once per
@@ -24,7 +24,7 @@ export type AuthPlugin<P> = NifraPlugin & {
 };
 export interface BearerOptions<P> {
     /** Verify a bearer token → a principal (truthy) or `null`/`undefined` (rejected). May be async
-     * (DB/JWT lookup). For a constant-secret comparison, use a constant-time compare — never `===`. */
+     * (DB/JWT lookup). For a constant-secret comparison, use a constant-time compare - never `===`. */
     readonly verify: (token: string) => MaybePromise<P | null | undefined>;
     /** When `true`, requests without a valid token pass through (`principal` is `null`) instead of `401`. */
     readonly optional?: boolean;
@@ -34,7 +34,7 @@ export interface BearerOptions<P> {
 /**
  * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
  * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
- * verified principal is read via the returned instance — see {@link AuthPlugin}.
+ * verified principal is read via the returned instance - see {@link AuthPlugin}.
  */
 export declare function bearer<P>(options: BearerOptions<P>): AuthPlugin<P>;
 export interface ApiKeyVerifyOptions<P> {
@@ -53,11 +53,11 @@ export interface ApiKeyStaticOptions {
 }
 /**
  * API-key authentication via a header (default `x-api-key`). Two forms:
- * - `apiKey({ keys })` — a fixed key set, compared in **constant time**; the matched key is the principal.
- * - `apiKey({ verify })` — custom (e.g. DB-backed) verification returning a typed principal.
+ * - `apiKey({ keys })` - a fixed key set, compared in **constant time**; the matched key is the principal.
+ * - `apiKey({ verify })` - custom (e.g. DB-backed) verification returning a typed principal.
  *
  * Rejects missing/invalid keys with `401` (unless `optional`). Read the principal via the returned
- * instance — see {@link AuthPlugin}.
+ * instance - see {@link AuthPlugin}.
  */
 export declare function apiKey(options: ApiKeyStaticOptions): AuthPlugin<string>;
 export declare function apiKey<P>(options: ApiKeyVerifyOptions<P>): AuthPlugin<P>;

package/dist/token-auth.js

@@ -9,11 +9,11 @@ function createTokenAuth(config) {
     });
     const plugin = definePlugin(config.name, (app) => app.beforeHandle(async (c) => {
         const token = config.extract(c.req);
-        // Empty string is treated as "no credential" — never passed to verify.
+        // Empty string is treated as "no credential" - never passed to verify.
         const principal = token !== undefined && token !== "" ? await config.verify(token) : null;
         if (principal !== null && principal !== undefined) {
             store.set(c.req, principal);
-            return undefined; // authorized — continue to the handler
+            return undefined; // authorized - continue to the handler
         }
         return config.optional ? undefined : reject(); // 401 short-circuits (skips the handler)
     }));
@@ -37,7 +37,7 @@ function createTokenAuth(config) {
 /**
  * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
  * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
- * verified principal is read via the returned instance — see {@link AuthPlugin}.
+ * verified principal is read via the returned instance - see {@link AuthPlugin}.
  */
 export function bearer(options) {
     const realm = options.realm ?? "api";
@@ -69,7 +69,7 @@ function timingSafeEqualBytes(a, b) {
 /**
  * Build a constant-time verifier for a fixed key set. Each valid key is hashed once (SHA-256, fixed
  * 32 bytes); per request the candidate is hashed and compared against every digest **without early
- * exit**, so timing depends only on the (public) key count — never on the secret value or which key
+ * exit**, so timing depends only on the (public) key count - never on the secret value or which key
  * matched. Portable across all runtimes via WebCrypto.
  */
 function staticKeyVerify(keys) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/middleware",
-  "version": "2.1.0",
-  "description": "Composable middleware for nifra — auth, CSRF, JWT/JWKS, IP restriction, CORS, body limits, response cache, timing, and operational helpers.",
+  "version": "2.3.0",
+  "description": "Composable middleware for nifra - auth, CSRF, JWT/JWKS, IP restriction, CORS, body limits, response cache, timing, and operational helpers.",
   "keywords": [
     "bun",
     "typescript",
@@ -46,10 +46,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/schema": "2.1.0"
+    "@nifrajs/schema": "2.3.0"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.1.0"
+    "@nifrajs/core": "^2.3.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*",

package/src/_utils.ts

@@ -144,12 +144,12 @@ export async function verifyHmacSha256(
 
 /**
  * Apply header mutations to a response, in place when possible. Framework-built responses
- * (`new Response`, `Response.json`) have mutable headers across every runtime — so the common path
+ * (`new Response`, `Response.json`) have mutable headers across every runtime - so the common path
  * mutates `res` directly and returns it, allocating nothing. Only an *immutable*-headers response
- * (`Response.redirect()`/`Response.error()`, or a proxied `fetch()` response on Node/Deno/workerd —
+ * (`Response.redirect()`/`Response.error()`, or a proxied `fetch()` response on Node/Deno/workerd -
  * never on Bun) makes `.set`/`.append` throw; that path clones into a fresh `Headers` + `Response`,
  * exactly the old always-clone behavior. `apply` runs once either way (immutability is all-or-nothing
- * — the first mutation throws before any partial change), so a mutation chain is safe to pass.
+ * - the first mutation throws before any partial change), so a mutation chain is safe to pass.
  */
 export function withHeaders(res: Response, apply: (headers: Headers) => void): Response {
   try {

package/src/admission.ts

@@ -3,7 +3,7 @@ import type { AdmissionController, AdmissionDecision } from "@nifrajs/core/serve
 /**
  * Adaptive capacity admission. Rate limiting bounds request *frequency* and `@nifrajs/core/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
+ * 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.
  *
@@ -11,7 +11,7 @@ import type { AdmissionController, AdmissionDecision } from "@nifrajs/core/serve
  * 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
+ * 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.
  */
 
@@ -97,7 +97,7 @@ export interface LoopDelayHistogram {
  */
 export type LoopDelayMonitor = (resolutionMs: number) => LoopDelayHistogram | undefined
 
-/** Shared no-op sampler — the fallback when an explicitly supplied monitor has no histogram. */
+/** Shared no-op sampler - the fallback when an explicitly supplied monitor has no histogram. */
 const NO_LAG: () => number = () => 0
 
 /**
@@ -274,7 +274,7 @@ export function createAdmissionController(options: AdmissionOptions): AdmissionC
       }
     }
 
-    // Loop-lag shed: the box is behind on the event loop — reject regardless of slot count.
+    // 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.

package/src/cache-control.ts

@@ -11,7 +11,7 @@ export interface CacheControlOptions {
 
 /**
  * Set a `Cache-Control` header on matching responses. `value` is either a fixed directive string or a
- * function of the request (return `undefined` to leave a response untouched — e.g. cache by path).
+ * function of the request (return `undefined` to leave a response untouched - e.g. cache by path).
  * Defaults to `GET`/`HEAD` + 2xx, and never clobbers a `Cache-Control` the handler set itself.
  *
  * ```ts

package/src/cache.ts

@@ -249,7 +249,7 @@ export function cache(options: CacheOptions): Middleware {
         return withStatusHeader(res, cacheStatusHeader, "BYPASS")
       }
       // Shared-cache safety (RFC 9111 §3.5): never store a response to an authenticated request
-      // (Authorization or Cookie) unless it's explicitly public — otherwise a personalized 200 leaks
+      // (Authorization or Cookie) unless it's explicitly public - otherwise a personalized 200 leaks
       // across users. Opt in with `cacheAuthenticated: true` for a route that's the same for everyone.
       if (
         !cacheAuthenticated &&

package/src/compression.ts

@@ -44,7 +44,7 @@ const gzipHeaders = (source: Headers): Headers => {
  *
  * The body is **peeked** up to `threshold` bytes to enforce the size floor: a response that ends below
  * the threshold is sent uncompressed (gzip's ~20-byte overhead would enlarge it), and only larger
- * bodies are compressed — the buffered prefix is replayed and the remainder streamed. (Runtimes rarely
+ * bodies are compressed - the buffered prefix is replayed and the remainder streamed. (Runtimes rarely
  * set `Content-Length` on a constructed `Response`, so the header alone can't gate this.)
  *
  * Skips: clients that don't accept gzip, already-encoded responses, bodyless responses (204/304/HEAD),
@@ -61,7 +61,7 @@ export function compression(options: CompressionOptions = {}) {
   return definePlugin("compression", (app) =>
     app.onResponse(async (res, req) => {
       const body = res.body
-      if (body === null) return res // 204/304/HEAD — nothing to compress
+      if (body === null) return res // 204/304/HEAD - nothing to compress
       if (!(req.headers.get("accept-encoding") ?? "").toLowerCase().includes("gzip")) return res
       if (res.headers.has("content-encoding")) return res // already encoded
       if (res.status === 206 || res.headers.has("content-range")) return res // ranges pass through
@@ -77,7 +77,7 @@ export function compression(options: CompressionOptions = {}) {
       while (total < threshold) {
         const { done, value } = await reader.read()
         if (done) {
-          // Body ended below the threshold — too small to be worth gzipping. Emit as-is.
+          // Body ended below the threshold - too small to be worth gzipping. Emit as-is.
           return new Response(concat(buffered, total), {
             status: res.status,
             statusText: res.statusText,
@@ -87,7 +87,7 @@ export function compression(options: CompressionOptions = {}) {
         buffered.push(value)
         total += value.byteLength
       }
-      // Over the threshold: replay the buffered prefix, then stream the rest — all through gzip.
+      // Over the threshold: replay the buffered prefix, then stream the rest - all through gzip.
       // (No explicit generic: it lets the chunk type infer from the non-shared reader so the stream
       // matches `CompressionStream`'s `Uint8Array` typing.)
       const source = new ReadableStream({

package/src/cors.ts

@@ -43,7 +43,7 @@ function resolveAllowOrigin(
  * short-circuits to `204` via `onRequest`; the origin/credentials headers are added in
  * `onResponse`, so they also land on errors, 404s, and the preflight itself.
  *
- * Throws at construction if `credentials: true` is paired with `origin: "*"` — the
+ * Throws at construction if `credentials: true` is paired with `origin: "*"` - the
  * browser rejects that combination, so we fail loud instead of shipping dead CORS.
  */
 export function cors(options: CorsOptions = {}): Middleware {
@@ -51,7 +51,7 @@ export function cors(options: CorsOptions = {}): Middleware {
   const credentials = options.credentials ?? false
   if (credentials && origin === "*") {
     throw new Error(
-      'cors: `credentials: true` cannot be combined with `origin: "*"` — list explicit origin(s).',
+      'cors: `credentials: true` cannot be combined with `origin: "*"` - list explicit origin(s).',
     )
   }
   const methods = (options.methods ?? DEFAULT_METHODS).join(", ")

package/src/durable-command.ts

@@ -0,0 +1,62 @@
+import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
+import {
+  attachCapabilityJournal,
+  type CapabilityExecutionJournal,
+} from "@nifrajs/core/capabilities"
+import { definePlugin, type NifraPlugin } from "@nifrajs/core/server"
+
+export interface DurableCommandOptions {
+  /** Where effect transitions are recorded. `createDurableEffectJournal` from
+   * `@nifrajs/core/durable-execution` is the one this is built for; any implementation of the seam
+   * works, and a memory-backed one is a test double, not a durable command. */
+  readonly journal: CapabilityExecutionJournal
+}
+
+/**
+ * Journal every capability effect on the routes below it, and declare the evidence that says so.
+ *
+ * A capability defined `idempotency: "durable"` requires `nifra.durable-command` evidence, and until
+ * this adapter existed nothing in the framework produced it. The only way to satisfy the tier was to
+ * write `assurance: ["nifra.durable-command"]` on the route - an assertion with nothing behind it,
+ * wrong in both directions: a route that genuinely journals its effects but omits the string fails
+ * `nifra check`, and a route that journals nothing but includes it passes.
+ *
+ * The evidence is a by-product here rather than a claim. Installing the adapter puts the journal on
+ * the request, so `executeCapability` records intent before an effect runs and exactly one terminal
+ * outcome after - which is what the tier is asking about. A call that passes its own `journal` still
+ * uses that one.
+ *
+ *     const commands = durableCommand({ journal: createDurableEffectJournal({ store }) })
+ *     const app = server().use(commands).post("/charge", { capabilities: ["billing.charge"] }, …)
+ *
+ * `beforeHandle` is order-scoped, like the auth plugins: routes registered before `.use(...)` are not
+ * covered, and the `subsequent` scope on the evidence says the same thing to `nifra check`.
+ *
+ * Note what this does NOT claim. Response replay (`schema.idempotency`) is a different guarantee and
+ * deliberately never proves this one: replaying a stored response after a crash mid-effect does not
+ * make the effect exactly-once, and the journal is what survives the crash.
+ */
+export function durableCommand(options: DurableCommandOptions): NifraPlugin {
+  const journal = options.journal
+  if (journal === null || typeof journal !== "object") {
+    throw new TypeError("durableCommand: journal must be a CapabilityExecutionJournal")
+  }
+  for (const method of ["intent", "executing", "committed", "failed"] as const) {
+    if (typeof journal[method] !== "function") {
+      // Fail at wiring time. A journal missing a transition would otherwise surface as a mid-effect
+      // TypeError on the first write in production, with the evidence already declared.
+      throw new TypeError(`durableCommand: journal.${method} must be a function`)
+    }
+  }
+  const plugin = definePlugin("nifra:durable-command", (app) =>
+    app.beforeHandle((c: object) => {
+      attachCapabilityJournal(c, journal)
+      return undefined
+    }),
+  )
+  return withRouteAssurance(plugin, {
+    id: NIFRA_ASSURANCE.DURABLE_COMMAND,
+    source: "durable-command",
+    scope: "subsequent",
+  })
+}