@nifrajs/middleware 2.2.0 → 2.4.0

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/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>