@nifrajs/middleware 2.2.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/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.2.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.2.0"
+    "@nifrajs/schema": "2.3.0"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.2.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",
+  })
+}

package/src/etag.ts

@@ -1,6 +1,6 @@
 import { definePlugin } from "@nifrajs/core/server"
 
-/** 32-bit FNV-1a over bytes → hex. A fast, dependency-free content fingerprint for ETags — not crypto. */
+/** 32-bit FNV-1a over bytes → hex. A fast, dependency-free content fingerprint for ETags - not crypto. */
 function fnv1a(bytes: Uint8Array): string {
   let h = 0x811c9dc5
   for (let i = 0; i < bytes.length; i++) {
@@ -11,7 +11,7 @@ function fnv1a(bytes: Uint8Array): string {
 }
 
 export interface ETagOptions {
-  /** Emit a weak validator (`W/"…"`). Default `true` — it's a content hash, not a byte-for-byte promise. */
+  /** Emit a weak validator (`W/"…"`). Default `true` - it's a content hash, not a byte-for-byte promise. */
   readonly weak?: boolean
   /** Maximum response bytes to hash. Default `1_000_000`; larger responses pass through unchanged. */
   readonly maxBytes?: number
@@ -19,7 +19,7 @@ export interface ETagOptions {
 
 /**
  * A {@link definePlugin} plugin that adds a content-hash `ETag` to `GET` `200` responses and returns
- * **`304 Not Modified`** when the client's `If-None-Match` matches — saving bandwidth on unchanged
+ * **`304 Not Modified`** when the client's `If-None-Match` matches - saving bandwidth on unchanged
  * responses. It reads and rebuilds small bodies only; larger responses pass through unchanged.
  * Idempotent.
  */
@@ -40,7 +40,7 @@ export function etag(options: ETagOptions = {}) {
       const headers = new Headers(res.headers)
       headers.set("ETag", tag)
       if (matchesIfNoneMatch(req.headers.get("if-none-match"), tag)) {
-        // A 304 carries no body — drop the body-describing headers so strict intermediaries don't see a
+        // A 304 carries no body - drop the body-describing headers so strict intermediaries don't see a
         // null body with a non-zero Content-Length.
         headers.delete("content-length")
         headers.delete("content-type")

package/src/healthcheck.ts

@@ -3,9 +3,9 @@ import { definePlugin } from "@nifrajs/core/server"
 type MaybePromise<T> = T | Promise<T>
 
 export interface HealthcheckOptions {
-  /** Liveness path — always `200` while the process is up. Default `"/health"`. */
+  /** Liveness path - always `200` while the process is up. Default `"/health"`. */
   readonly path?: string
-  /** Readiness path — runs `checks`; `200` if all pass, `503` otherwise. Default `"/ready"`. */
+  /** Readiness path - runs `checks`; `200` if all pass, `503` otherwise. Default `"/ready"`. */
   readyPath?: string
   /** Readiness checks (DB ping, cache reachable, …). Each returns a boolean or throws; a throw counts
    * as failing. `/ready` reports each by name and is `200` only when all pass. */
@@ -38,7 +38,7 @@ export function healthcheck(options: HealthcheckOptions = {}) {
     app.register("GET", readyPath, undefined, async () => {
       const results: Record<string, boolean> = {}
       let ready = true
-      // Run checks concurrently; a throw (or false) marks that check — and the whole probe — not ready.
+      // Run checks concurrently; a throw (or false) marks that check - and the whole probe - not ready.
       await Promise.all(
         checkNames.map(async (name) => {
           try {

package/src/idempotency.ts

@@ -2,12 +2,12 @@ import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import { METHODS, type Middleware } from "@nifrajs/core/server"
 
 /**
- * Idempotency keys for unsafe requests — a client retrying a `POST` (dropped connection, impatient
+ * 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.
  *
- * Pair it with a DB uniqueness constraint — this stops the *retry*, the constraint is the source of
+ * 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}
  * (Redis, etc.) so the guarantee holds across instances; {@link MemoryIdempotencyStore} is dev-only.
  */
@@ -15,7 +15,7 @@ import { METHODS, type Middleware } from "@nifrajs/core/server"
 /** A captured response, replayed verbatim on a retry. Body is base64 (binary-safe + JSON-serializable). */
 export interface IdempotencyRecord {
   readonly status: number
-  /** Response headers, **excluding `Set-Cookie`** (cookies are session-specific — see {@link idempotency}). */
+  /** Response headers, **excluding `Set-Cookie`** (cookies are session-specific - see {@link idempotency}). */
   readonly headers: ReadonlyArray<readonly [string, string]>
   /** Response body, base64-encoded. */
   readonly body: string
@@ -45,7 +45,7 @@ export interface IdempotencyStore {
 }
 
 export interface MemoryIdempotencyStoreOptions {
-  /** Allow the in-memory store in production. Off by default — a per-instance store can't dedupe across instances. */
+  /** Allow the in-memory store in production. Off by default - a per-instance store can't dedupe across instances. */
   readonly allowInProduction?: boolean
 }
 
@@ -253,7 +253,7 @@ function replay(record: IdempotencyRecord): Response {
 /**
  * Idempotency-key middleware. Apply with `app.use(idempotency({ store }))`.
  *
- * **`Set-Cookie` is intentionally not cached or replayed** — a cookie set on the first request is
+ * **`Set-Cookie` is intentionally not cached or replayed** - a cookie set on the first request is
  * session-specific, so replaying it to a different caller (key collision or abuse) would leak/fixate a
  * session. Cache the body + status + the rest of the headers; let auth cookies re-issue per request.
  *
@@ -286,7 +286,7 @@ export function idempotency(options: IdempotencyOptions): Middleware {
     async onRequest(req) {
       if (!methods.has(req.method.toUpperCase())) return undefined
       const key = keyOf(req, header)
-      if (key === null || key === "") return undefined // opt-in per request — no key ⇒ no dedupe
+      if (key === null || key === "") return undefined // opt-in per request - no key ⇒ no dedupe
       const claim = await store.begin(key, lockTtlMs)
       if (claim.state === "replay") return replay(claim.record)
       if (claim.state === "in_flight") {
@@ -318,7 +318,7 @@ export function idempotency(options: IdempotencyOptions): Middleware {
         throw err
       }
       if (!("bytes" in captured)) {
-        await store.release(key) // too large to store — return it, but don't cache
+        await store.release(key) // too large to store - return it, but don't cache
         return captured.response
       }
       const bytes = captured.bytes

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * `@nifrajs/middleware` — composable, dependency-free middleware + plugins applied via `app.use()`.
+ * `@nifrajs/middleware` - composable, dependency-free middleware + plugins applied via `app.use()`.
  * The hardening set (`cors`, `rateLimit`, `securityHeaders`) returns a `@nifrajs/core` `Middleware`
  * (a hook bundle, context-agnostic). The seeded plugins (`requestId`, `logger`, `etag`, `bearer`,
- * `apiKey`) use the `definePlugin` convention — named (idempotent dedupe), and `requestId` threads
+ * `apiKey`) use the `definePlugin` convention - named (idempotent dedupe), and `requestId` threads
  * `c.requestId` into the handler context.
  */
 
@@ -44,6 +44,7 @@ export {
   csrf,
   verifyCsrfToken,
 } from "./csrf.ts"
+export { type DurableCommandOptions, durableCommand } from "./durable-command.ts"
 export { type ETagOptions, etag } from "./etag.ts"
 export { type HealthcheckOptions, healthcheck } from "./healthcheck.ts"
 export {

package/src/logger.ts

@@ -15,8 +15,8 @@ export interface LoggerOptions {
 }
 
 /**
- * A {@link definePlugin} plugin that logs one structured line per request — method, path, status,
- * and duration — via `onRequest`/`onResponse` (so it covers 404s and errors too). The start time is
+ * A {@link definePlugin} plugin that logs one structured line per request - method, path, status,
+ * and duration - via `onRequest`/`onResponse` (so it covers 404s and errors too). The start time is
  * paired to the request through a `WeakMap` (no per-request allocation leak). Idempotent.
  */
 export function logger(options: LoggerOptions = {}) {