@nifrajs/middleware 2.1.0 → 2.3.0

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 = {}) {

package/src/openapi.ts

@@ -1,15 +1,15 @@
 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"
 
-/** A registered route as seen by {@link buildOpenApiDocument} — structurally a `@nifrajs/core`
+/** A registered route as seen by {@link buildOpenApiDocument} - structurally a `@nifrajs/core`
  * `RouteDescriptor` (so `app.routes()` is passed straight through). */
 export interface RouteLike {
   readonly method: string
   readonly path: string
-  // `| undefined` (not just `?`) so a core `RouteDescriptor` — whose `schema` is a *required*
-  // `RouteSchema | undefined` — is assignable under `exactOptionalPropertyTypes`.
+  // `| undefined` (not just `?`) so a core `RouteDescriptor` - whose `schema` is a *required*
+  // `RouteSchema | undefined` - is assignable under `exactOptionalPropertyTypes`.
   readonly schema?:
     | { readonly body?: unknown; readonly query?: unknown; readonly response?: unknown }
     | undefined
@@ -57,7 +57,7 @@ export interface OpenApiOptions {
   readonly path?: string
   /** Exclude routes from the document (the doc path itself is always excluded). */
   readonly exclude?: (route: { readonly method: string; readonly path: string }) => boolean
-  /** Per-operation overrides keyed by `"GET /users/:id"`, shallow-merged over the generated skeleton —
+  /** Per-operation overrides keyed by `"GET /users/:id"`, shallow-merged over the generated skeleton -
    * the escape hatch for rich request/response schemas, tags, and per-op security (Standard Schema
    * can't be introspected). */
   readonly operations?: Readonly<Record<string, Record<string, unknown>>>
@@ -127,10 +127,10 @@ function scalarPage(specUrl: string, title: string, cdn: string): string {
 }
 
 /**
- * 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`,
@@ -149,7 +149,7 @@ export function openapi(options: OpenApiOptions = {}) {
   let uiCached: string | undefined
   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(), {

package/src/pretty-json.ts

@@ -25,26 +25,82 @@ function parseLength(value: string | null): number | undefined {
   return Number(value)
 }
 
-async function readTextCapped(res: Response, maxBytes: number): Promise<string | null> {
-  const body = res.clone().body
-  if (body === null) return null
+/**
+ * The two reader methods this file uses, structurally.
+ *
+ * Named by use rather than imported: `lib.dom`'s `ReadableStreamDefaultReader` and Bun's augmented one
+ * are not mutually assignable (Bun adds `readMany`), and `ReturnType<…getReader>` resolves to the BYOB
+ * overload, whose `read` requires an argument. A structural shape sidesteps all of it without a cast.
+ */
+interface ChunkReader {
+  read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array }>
+  cancel(reason?: unknown): Promise<void>
+}
+
+/** Re-emit the bytes already pulled, then the untouched remainder of the same reader. */
+function replayFrom(res: Response, chunks: readonly Uint8Array[], reader: ChunkReader): Response {
+  const stream = new ReadableStream<Uint8Array>({
+    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,
+  })
+}
+
+type Peeked = { readonly text: string } | { readonly response: Response }
+
+/**
+ * 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: Response, maxBytes: number): Promise<Peeked> {
+  const body = res.body
+  if (body === null) return { response: res }
   const reader = body.getReader()
-  const decoder = new TextDecoder()
+  const chunks: Uint8Array[] = []
   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) }
   }
 }
 
@@ -76,13 +132,19 @@ export function prettyJson(options: PrettyJsonOptions = {}) {
       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: unknown
       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)

package/src/rate-limit.ts

@@ -10,7 +10,7 @@ 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 {
@@ -18,7 +18,7 @@ export interface RateLimitStore {
 }
 
 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). */
@@ -29,7 +29,7 @@ export interface MemoryStoreOptions {
 
 /** 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
 
 /**
@@ -38,8 +38,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 implements RateLimitStore {
   private readonly windows = new Map<string, { count: number; resetAt: number }>()
@@ -48,7 +48,7 @@ export class MemoryStore implements RateLimitStore {
   private lastSweep = 0
   private 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(): number {
@@ -98,7 +98,7 @@ export class MemoryStore implements RateLimitStore {
   private enforceMaxKeys(now: number): void {
     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`.
@@ -132,13 +132,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).
    */
@@ -151,7 +151,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/src/request-id.ts

@@ -10,7 +10,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/src/security-headers.ts

@@ -3,7 +3,7 @@ import type { Middleware } from "@nifrajs/core/server"
 import { withHeaders } from "./_utils.ts"
 
 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
@@ -40,7 +40,7 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
     {
       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")

package/src/token-auth.ts

@@ -4,7 +4,7 @@ import { definePlugin, 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
@@ -51,11 +51,11 @@ function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
   const plugin = definePlugin(config.name, (app) =>
     app.beforeHandle(async (c: { readonly req: Request }) => {
       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)
     }),
@@ -79,7 +79,7 @@ function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
 
 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
@@ -90,7 +90,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 function bearer<P>(options: BearerOptions<P>): AuthPlugin<P> {
   const realm = options.realm ?? "api"
@@ -140,7 +140,7 @@ function timingSafeEqualBytes(a: Uint8Array, b: Uint8Array): boolean {
 /**
  * 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: readonly string[]): (candidate: string) => Promise<string | null> {
@@ -158,11 +158,11 @@ function staticKeyVerify(keys: readonly string[]): (candidate: string) => Promis
 
 /**
  * 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 function apiKey(options: ApiKeyStaticOptions): AuthPlugin<string>
 export function apiKey<P>(options: ApiKeyVerifyOptions<P>): AuthPlugin<P>