@nifrajs/middleware 2.11.0 → 2.12.0

package/src/request-id.ts

@@ -1,4 +1,5 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { type ContextPlugin, defineContextPlugin } from "@nifrajs/core/server"
+import { setNodeHeader, withHeaders } from "./_utils.ts"
 
 export interface RequestIdOptions {
   /** Header read for an inbound id (trace propagation) + echoed on the response. Default `"x-request-id"`. */
@@ -8,23 +9,74 @@ export interface RequestIdOptions {
 }
 
 /**
- * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
+ * A {@link defineContextPlugin} 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
- * no-op.
+ * threaded by `derive`), and echoes it on EVERY response leaving the app - handler-returned raw
+ * `Response`s and redirects, `onRequest` short-circuits (an auth 401, an admission 429), and
+ * framework-generated 404/405/422/timeout responses included. Core deliberately does not merge
+ * `c.set.headers` onto a handler-returned `Response`, so the echo lives in an app-global
+ * `onResponse` hook (paired with the derive through a `WeakMap` keyed on the request) with a node
+ * twin, keeping the Node adapter on its direct writer with no request-walk cost. Idempotent -
+ * applying it twice is a no-op.
  *
  * ```ts
  * app.use(requestId())          // c.requestId available downstream; X-Request-Id on responses
  * ```
  */
-export function requestId(options: RequestIdOptions = {}) {
+export function requestId(options: RequestIdOptions = {}): ContextPlugin<{ requestId: string }> {
   const header = options.header ?? "x-request-id"
+  // The wire spelling: `c.set.headers` and the Node outcome record both store lowercase names, so
+  // the response twin's "already echoed?" probe and the derive's write must agree on it.
+  const wireHeader = header.toLowerCase()
   const generate = options.generate ?? (() => crypto.randomUUID())
-  return definePlugin("requestId", (app) =>
-    app.derive((c) => {
-      const id = c.header(header) ?? generate()
-      c.set.headers[header] = id // echo on the response (route handlers)
-      return { requestId: id }
-    }),
+  // Web-lane derive-to-response pairing for GENERATED ids (an inbound one is re-readable from the
+  // request in onResponse). Entries are deleted in onResponse; a Node-lane derive also writes here
+  // but its id travels via the `c.set` write into the outcome record, and the weakly-held entry is
+  // simply collected with the request.
+  const ids = new WeakMap<Request, string>()
+  // defineContextPlugin, not definePlugin: the latter would infer `app` as `AnyServer` here and make
+  // `.use(requestId())` return `Server<any, any>`, erasing the route registry for every route the app
+  // declares afterwards - and with it the end-to-end types of any typed client built from the app.
+  return defineContextPlugin<{ requestId: string }>("requestId", (app) =>
+    app
+      // No `name` on the bundle: the surrounding plugin's "requestId" dedupe already makes the
+      // install idempotent, and a bundle named the same would be skipped as already-installed.
+      // Response hooks ONLY - no onRequest, so the bundle adds nothing to the request walk and the
+      // Node adapter's native request lane stays engaged without needing a no-op twin.
+      .use({
+        onResponse(res, req) {
+          const id = ids.get(req)
+          ids.delete(req)
+          // Already carried (the derive's `c.set` write merged into a framework-rendered response,
+          // or the handler set it explicitly): leave the response untouched.
+          if (res.headers.get(header) !== null) return res
+          // The id the derive generated; else the inbound header, then a fresh id - so a response
+          // no derive saw (a 404, an earlier middleware's short-circuit) is still covered.
+          const echo = id ?? req.headers.get(header) ?? generate()
+          return withHeaders(res, (headers) => {
+            headers.set(header, echo)
+          })
+        },
+        onNodeResponse(res, req) {
+          // The common node path (a handler route, whose derive wrote the id through `c.set`) pays
+          // exactly this one record-property check. Anything the derive never saw - a 404, a native
+          // short-circuit - gets the inbound id or a fresh one here.
+          if (res.headers?.[wireHeader] !== undefined) return
+          setNodeHeader(res, wireHeader, req.header(header) ?? generate())
+        },
+      })
+      .derive((c) => {
+        // Inbound header first (readable on every lane without materializing a Request); generate
+        // otherwise, ONCE. A generated id is stored keyed on `c.req` so the Web onResponse hook
+        // echoes the exact id a raw-Response handler saw as `c.requestId`; the `c.set` write below
+        // carries it into a framework-rendered result on every lane - on Node-direct, into the
+        // outcome record, where the response twin sees it as already echoed. Header and
+        // `c.requestId` are therefore the same value everywhere with a single generation.
+        const inbound = c.header(header)
+        const id = inbound ?? generate()
+        if (inbound === null) ids.set(c.req, id)
+        c.set.headers[wireHeader] = id
+        return { requestId: id }
+      }),
   )
 }

package/src/security-headers.ts

@@ -14,6 +14,17 @@ export interface SecurityHeadersOptions {
   readonly frameOptions?: "DENY" | "SAMEORIGIN"
   /** `Referrer-Policy`. Default `"no-referrer"`. */
   readonly referrerPolicy?: string
+  /** `Cross-Origin-Opener-Policy`. Off by default - isolates the browsing context group; opt in
+   * when the app tolerates losing `window.opener` links from cross-origin pages. */
+  readonly crossOriginOpenerPolicy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none"
+  /** `Cross-Origin-Embedder-Policy`. Off by default - `require-corp` breaks embedding of
+   * cross-origin resources that do not opt in, so this is a deliberate decision. */
+  readonly crossOriginEmbedderPolicy?: "require-corp" | "credentialless" | "unsafe-none"
+  /** `Cross-Origin-Resource-Policy`. Off by default (app-specific: assets meant for other
+   * origins need `cross-origin`). */
+  readonly crossOriginResourcePolicy?: "same-origin" | "same-site" | "cross-origin"
+  /** `Permissions-Policy` value, e.g. `"camera=(), geolocation=()"`. Off by default (app-specific). */
+  readonly permissionsPolicy?: string
 }
 
 /**
@@ -46,6 +57,18 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
   }
   if (hstsValue !== undefined) declared["strict-transport-security"] = hstsValue
   if (csp !== undefined) declared["content-security-policy"] = csp
+  if (options.crossOriginOpenerPolicy !== undefined) {
+    declared["cross-origin-opener-policy"] = options.crossOriginOpenerPolicy
+  }
+  if (options.crossOriginEmbedderPolicy !== undefined) {
+    declared["cross-origin-embedder-policy"] = options.crossOriginEmbedderPolicy
+  }
+  if (options.crossOriginResourcePolicy !== undefined) {
+    declared["cross-origin-resource-policy"] = options.crossOriginResourcePolicy
+  }
+  if (options.permissionsPolicy !== undefined) {
+    declared["permissions-policy"] = options.permissionsPolicy
+  }
 
   return withRouteAssurance<Middleware>(
     {

package/src/timing.ts

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { type ContextPlugin, defineContextPlugin } from "@nifrajs/core/server"
 import { withHeaders } from "./_utils.ts"
 
 export interface TimingMetric {
@@ -62,7 +62,7 @@ function formatMetric(metric: TimingMetric, precision: number): string {
  * Put request-rewriting middleware (for example `methodOverride`) before `timing()` so timing is
  * attached to the final routed request.
  */
-export function timing(options: TimingOptions = {}) {
+export function timing(options: TimingOptions = {}): ContextPlugin<{ timing: TimingControls }> {
   const totalName = options.total === undefined ? "total" : options.total
   if (totalName !== false) assertMetricName(totalName)
   const precision = options.precision ?? 1
@@ -104,7 +104,7 @@ export function timing(options: TimingOptions = {}) {
     },
   })
 
-  return definePlugin("timing", (app) =>
+  return defineContextPlugin<{ timing: TimingControls }>("timing", (app) =>
     app
       .onRequest((req) => {
         if (!isEnabled(req)) return undefined

package/src/token-auth.ts

@@ -1,5 +1,5 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import { definePlugin, type NifraPlugin } from "@nifrajs/core/server"
+import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -19,7 +19,7 @@ type MaybePromise<T> = T | Promise<T>
  * const app = server().use(auth).get("/me", (c) => auth.requirePrincipal(c.req))
  * ```
  */
-export type AuthPlugin<P> = NifraPlugin & {
+export type AuthPlugin<P> = IdentityPlugin & {
   /** The verified principal for this request, or `null` (no/invalid token in `optional` mode). */
   principal(request: Request): P | null
   /** The verified principal, or **throws a `401` `Response`** when absent. */
@@ -48,7 +48,7 @@ function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
         headers: config.challenge !== undefined ? { "www-authenticate": config.challenge } : {},
       },
     )
-  const plugin = definePlugin(config.name, (app) =>
+  const plugin = defineIdentityPlugin(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.

package/src/trailing-slash.ts

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { defineRouterPlugin } from "@nifrajs/core/server"
 
 export interface TrailingSlashOptions {
   /** Redirect (default) or route internally with a rewritten URL. */
@@ -59,7 +59,7 @@ export function trimTrailingSlash(options: TrailingSlashOptions = {}) {
   validateStatus(status)
   const methods = methodsOf(options.methods)
 
-  return definePlugin("trimTrailingSlash", (app) =>
+  return defineRouterPlugin("trimTrailingSlash", (app) =>
     app.onRequest((req) => {
       if (!methods.has(req.method.toUpperCase())) return undefined
       const path = new URL(req.url).pathname
@@ -81,7 +81,7 @@ export function appendTrailingSlash(options: TrailingSlashOptions = {}) {
   validateStatus(status)
   const methods = methodsOf(options.methods)
 
-  return definePlugin("appendTrailingSlash", (app) =>
+  return defineRouterPlugin("appendTrailingSlash", (app) =>
     app.onRequest((req) => {
       if (!methods.has(req.method.toUpperCase())) return undefined
       const path = new URL(req.url).pathname