@nifrajs/core 5.0.0 → 5.2.0

package/src/internal/hook-origins.ts

@@ -16,6 +16,10 @@ export type HookKind =
   | "onResponse"
   | "responseHeaders"
   | "onResponseFinalized"
+  // Runtimes a route resolved at registration: reflected beside its hooks, never tagged as one.
+  | "effectLedger"
+  | "idempotency"
+  | "responseContract"
 
 export interface HookOrigin {
   readonly kind: HookKind
@@ -48,11 +52,24 @@ export interface AdoptionTag {
   readonly prefix: string | undefined
 }
 
+/** A `merge()` whose routes carry no authentication of their own while the parent authenticates the
+ * routes it declares: the parent's order-scoped auth never runs for merged routes. */
+export interface MergeAuthGapTag {
+  /** The `merge()` call's `file:line:col`, when a frame outside core was found. */
+  readonly site: string | undefined
+  /** The parent's auth in effect at the merge: `authenticate(<id>)` stages and evidence sources. */
+  readonly auth: readonly string[]
+  /** `METHOD /path` of each merged route the parent's auth would have covered. */
+  readonly routes: readonly string[]
+}
+
 const origins = new WeakMap<object, HookOrigin>()
 const scopes = new WeakMap<object, HookScopeTag>()
 const sources = new WeakMap<object, unknown>()
 const statics = new WeakMap<object, StaticHeadersTag[]>()
 const adoptions = new WeakMap<object, AdoptionTag[]>()
+const mergeAuthGaps = new WeakMap<object, MergeAuthGapTag[]>()
+const routeSites = new WeakMap<object, Map<string, string>>()
 let applying: string | undefined
 // A merged server whose static headers are about to become one of the target's response hooks.
 let staticsOwner: object | undefined
@@ -130,6 +147,20 @@ export function tagAdoption(target: object, source: object, prefix: string | und
   else list.push(tag)
 }
 
+export function tagMergeAuthGap(target: object, gap: MergeAuthGapTag): void {
+  const list = mergeAuthGaps.get(target)
+  if (list === undefined) mergeAuthGaps.set(target, [gap])
+  else list.push(gap)
+}
+
+/** Where `server` registered the route `key` (`METHOD /path`): a `file:line:col` frame. The first
+ * registration of a key wins, as it does for the router. */
+export function tagRouteSite(server: object, key: string, site: string): void {
+  const sites = routeSites.get(server)
+  if (sites === undefined) routeSites.set(server, new Map([[key, site]]))
+  else if (!sites.has(key)) sites.set(key, site)
+}
+
 const outer: (string | undefined)[] = []
 
 /** Mark the plugin a `use()` is applying, until the matching {@link leavePlugin}. */
@@ -151,3 +182,7 @@ export const hookSourceOf = (hook: unknown): unknown =>
 export const staticHeadersOf = (server: object): readonly StaticHeadersTag[] =>
   statics.get(server) ?? []
 export const adoptionsOf = (server: object): readonly AdoptionTag[] => adoptions.get(server) ?? []
+export const mergeAuthGapsOf = (server: object): readonly MergeAuthGapTag[] =>
+  mergeAuthGaps.get(server) ?? []
+export const routeSitesOf = (server: object): ReadonlyMap<string, string> =>
+  routeSites.get(server) ?? new Map()

package/src/internal/route-compiler.ts

@@ -35,6 +35,7 @@ import {
   NIFRA_ASSURANCE_IDS,
   validEvidenceId,
 } from "./route-assurance.ts"
+import type { CatalogRoute } from "./route-catalog.ts"
 import type {
   RawAfterHandle,
   RawAround,
@@ -43,7 +44,9 @@ import type {
   RawDerive,
   RawErrorHandler,
 } from "./route-execution.ts"
+import { compileRouteExecutionPlan } from "./route-execution.ts"
 import { type RouteLaneSelection, selectRouteLanes } from "./route-lanes.ts"
+import { compileRouteProgram } from "./route-program.ts"
 
 export interface RouteCompilerContext {
   readonly maxBodyBytes: number
@@ -83,6 +86,108 @@ export interface CompiledRouteOptions {
   readonly authenticated: boolean
 }
 
+const RESPONSE_CONTRACT_EVIDENCE: AssuranceDeclaration = Object.freeze({
+  id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
+  source: "response-contract",
+  scope: "plugin",
+})
+
+function responseDefinitionOf(
+  schema: RouteSchema | undefined,
+): ResponseContractDefinition | undefined {
+  return schema?.response !== undefined || schema?.errors !== undefined
+    ? {
+        ...(schema.response === undefined ? {} : { response: schema.response }),
+        ...(schema.errors === undefined ? {} : { errors: schema.errors }),
+      }
+    : undefined
+}
+
+/**
+ * Recompile a route another server compiled, under the response contract and effect ledger the
+ * adopting server installed and the route's own server did not. Both only add a check or a record,
+ * so a merged route can never serve more than it did standalone - and without this, the same
+ * `.use()` covered a `group()` route but not a `merge()`d one. A route that already resolved its
+ * own contract or ledger keeps it.
+ */
+export function adoptRouteRuntimes(
+  route: CatalogRoute,
+  responseContractRuntime: ResponseContractRuntime | undefined,
+  effectLedgerRuntime: EffectLedgerRuntime | undefined,
+): CatalogRoute {
+  const { entry, descriptor } = route
+  const definition =
+    entry.responseContract === undefined && responseContractRuntime !== undefined
+      ? responseDefinitionOf(entry.schema)
+      : undefined
+  const ledgered =
+    entry.ledgered ??
+    effectLedgerRuntime?.resolve(descriptor.capabilities ?? [], route.method, route.path)
+  if (definition === undefined && ledgered === entry.ledgered) return route
+  const responseContract =
+    definition === undefined || responseContractRuntime === undefined
+      ? entry.responseContract
+      : { runtime: responseContractRuntime, definition }
+  // Either runtime rules out every fused lane, so the route needs only the generic plan here - and
+  // nothing the source server's validation-error default decided about fusion can matter any more.
+  const lanes = selectRouteLanes({
+    schema: entry.schema,
+    hasAuth: entry.authStages.length > 0,
+    hasIdempotency: entry.idempotent !== undefined,
+    hasLedger: ledgered !== undefined,
+    hasResponseContract: responseContract !== undefined,
+    hasDecorations: entry.hasDecorations,
+    derives: entry.derives.length,
+    beforeHandle: entry.beforeHandle.length,
+    afterHandle: entry.afterHandle.length,
+    onError: entry.onError.length,
+    around: entry.around.length,
+    defaultOnValidationError: false,
+  })
+  const program = compileRouteProgram({
+    schema: entry.schema,
+    handler: entry.handler,
+    derives: entry.derives,
+    authStages: entry.authStages,
+    beforeHandle: entry.beforeHandle,
+    afterHandle: entry.afterHandle,
+    onError: entry.onError,
+    decorations: entry.decorations,
+    hasDecorations: entry.hasDecorations,
+    bodySchema: entry.schema?.body,
+    bodyLimit: entry.bodyLimit,
+    responseContract,
+  })
+  const execution = compileRouteExecutionPlan({
+    lane: lanes.lane,
+    contextless: false,
+    hasAround: entry.around.length > 0,
+    hasLedger: ledgered !== undefined,
+    fusedWeb: undefined,
+    fusedBody: undefined,
+    fusedLane: undefined,
+  })
+  const enforced = definition !== undefined && responseContractRuntime?.mode === "enforce"
+  return {
+    ...route,
+    entry: {
+      ...entry,
+      ledgered,
+      responseContract,
+      lifecycleHookLane: undefined,
+      execution,
+      program,
+    },
+    descriptor:
+      definition === undefined || responseContractRuntime === undefined
+        ? descriptor
+        : { ...descriptor, responseContract: responseContractRuntime.mode },
+    assurance: enforced
+      ? Object.freeze([...route.assurance, RESPONSE_CONTRACT_EVIDENCE])
+      : route.assurance,
+  }
+}
+
 /** Resolve all registration-time policy and lane facts for one route. */
 export function compileRouteOptions(
   context: RouteCompilerContext,
@@ -181,13 +286,7 @@ export function compileRouteOptions(
     context.maxBodyBytes,
   )
   const ledgered = context.effectLedgerRuntime?.resolve(capabilities, method, path)
-  const responseDefinition =
-    schema?.response !== undefined || schema?.errors !== undefined
-      ? {
-          ...(schema.response === undefined ? {} : { response: schema.response }),
-          ...(schema.errors === undefined ? {} : { errors: schema.errors }),
-        }
-      : undefined
+  const responseDefinition = responseDefinitionOf(schema)
   const contracted =
     context.responseContractRuntime !== undefined && responseDefinition !== undefined
       ? { runtime: context.responseContractRuntime, definition: responseDefinition }
@@ -208,15 +307,7 @@ export function compileRouteOptions(
   })
 
   const routeAssurance: AssuranceDeclaration[] = [...context.activeAssurance, ...handlerAssurance]
-  if (contracted?.runtime.mode === "enforce") {
-    routeAssurance.push(
-      Object.freeze({
-        id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
-        source: "response-contract",
-        scope: "plugin",
-      }),
-    )
-  }
+  if (contracted?.runtime.mode === "enforce") routeAssurance.push(RESPONSE_CONTRACT_EVIDENCE)
   for (const id of schema?.assurance ?? []) {
     if (!validEvidenceId(id)) {
       throw new Error(

package/src/internal/route-program.ts

@@ -9,6 +9,7 @@
 
 import type { StandardSchemaV1 } from "../schema/standard.ts"
 import { markAuthenticatedRequest } from "../server/auth.ts"
+import { declaredHeaderNames } from "../server/headers.ts"
 import { pathnameOf } from "../server/http.ts"
 import { queryObjectOf } from "../server/query.ts"
 import type { Registry } from "../server/registry.ts"
@@ -35,7 +36,12 @@ import type {
 export type ProgramValidationKind = "headers" | "cookies" | "params" | "body" | "query"
 
 export type RouteProgramStage =
-  | { readonly kind: ProgramValidationKind; readonly schema: StandardSchemaV1 }
+  | {
+      readonly kind: ProgramValidationKind
+      readonly schema: StandardSchemaV1
+      /** Headers only: the names a closed schema validates, read case-insensitively. */
+      readonly names?: readonly string[] | undefined
+    }
   | { readonly kind: "derive"; readonly run: RawDerive }
   | { readonly kind: "before"; readonly run: RawBeforeHandle }
   | { readonly kind: "handler"; readonly run: InternalHandler }
@@ -90,7 +96,8 @@ export function compileRouteProgram(input: RouteProgramInput): RouteProgram {
   for (const kind of ["headers", "cookies", "params", "body", "query"] as const) {
     const validator = schema?.[kind]
     if (validator !== undefined) {
-      const stage = { kind, schema: validator }
+      const names = kind === "headers" ? declaredHeaderNames(validator) : undefined
+      const stage = { kind, schema: validator, names }
       stages.push(stage)
       validationStages.push(stage)
     }
@@ -142,6 +149,7 @@ interface RouteProgramRuntime {
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
+    fallback?: () => T,
   ): MaybePromise<T>
   finishProgramResult<T>(
     entry: RouteEntry,
@@ -243,6 +251,21 @@ function validAuthenticationFailureReason(
   )
 }
 
+/** A failed stage still answers 503, but its cause takes the handler-error path (onError, else the
+ * logger) instead of vanishing. */
+function failAuthentication<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  error: unknown,
+): ProgramResult<T> {
+  return host.handleProgramError(entry, error, ctx, finalize, wrapResponse, () =>
+    finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx),
+  )
+}
+
 function runAuthenticationStages<T>(
   host: RouteProgramRuntime,
   entry: RouteEntry,
@@ -287,8 +310,8 @@ function runAuthenticationStages<T>(
   let outcome: MaybePromise<import("../server/auth.ts").AuthenticationResult<unknown>>
   try {
     outcome = stage.run(input)
-  } catch {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
+  } catch (error) {
+    return failAuthentication(host, entry, ctx, finalize, wrapResponse, error)
   }
   if (outcome instanceof Promise) {
     return outcome.then(
@@ -312,7 +335,7 @@ function runAuthenticationStages<T>(
           return host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
         }
       },
-      () => finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx),
+      (error) => failAuthentication(host, entry, ctx, finalize, wrapResponse, error),
     )
   }
   return finishAuthentication(
@@ -344,27 +367,23 @@ function finishAuthentication<T>(
   if (
     result === null ||
     typeof result !== "object" ||
-    (result.kind !== "authenticated" && result.kind !== "rejected")
+    (result.kind === "rejected"
+      ? !validAuthenticationFailureReason(result.reason) ||
+        (result.response !== undefined &&
+          !(result.response instanceof Response) &&
+          !isResponseResult(result.response))
+      : result.kind !== "authenticated" ||
+        result.principal === null ||
+        result.principal === undefined)
   ) {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
+    const id = program.authStages[next - 1]!.id
+    const error = new TypeError(`authenticate() stage "${id}" returned an invalid decision`)
+    return failAuthentication(host, entry, ctx, finalize, wrapResponse, error)
   }
   if (result.kind === "rejected") {
-    if (!validAuthenticationFailureReason(result.reason)) {
-      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-    }
-    if (
-      result.response !== undefined &&
-      !(result.response instanceof Response) &&
-      !isResponseResult(result.response)
-    ) {
-      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-    }
     const response = result.response ?? defaultAuthenticationResponse(result.reason)
     return finalize(response, responseSet(ctx), ctx)
   }
-  if (result.principal === null || result.principal === undefined) {
-    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx), ctx)
-  }
   Object.defineProperty(ctx, "principal", {
     value: result.principal,
     enumerable: true,

package/src/internal/same-origin.ts

@@ -26,7 +26,7 @@
  *
  * An unparseable Origin is not same-origin.
  */
-export function isSameOriginRequest(origin: string, request: Request): boolean {
+export function isSameOriginRequest(origin: string, request: { readonly url: string }): boolean {
   try {
     const from = new URL(origin)
     const own = new URL(request.url)
@@ -41,3 +41,16 @@ export function isSameOriginRequest(origin: string, request: Request): boolean {
     return false
   }
 }
+
+/**
+ * {@link isSameOriginRequest} for a browser form submission. Under `Referrer-Policy: no-referrer` a
+ * browser sends a same-origin form POST with `Origin: null`; that one passes on its
+ * `Sec-Fetch-Site: same-origin`, a header page script cannot set.
+ */
+export function isSameOriginForm(
+  origin: string,
+  secFetchSite: string | null,
+  request: { readonly url: string },
+): boolean {
+  return origin === "null" ? secFetchSite === "same-origin" : isSameOriginRequest(origin, request)
+}

package/src/reflection.ts

@@ -20,6 +20,9 @@ import {
   hookOriginOf,
   hookScopeOf,
   hookSourceOf,
+  type MergeAuthGapTag,
+  mergeAuthGapsOf,
+  routeSitesOf,
   staticHeadersOf,
 } from "./internal/hook-origins.ts"
 import {
@@ -33,6 +36,8 @@ import { NIFRA_BACKEND_EVIDENCE } from "./mount.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
+export { declaredHeaderNames } from "./server/headers.ts"
+
 /** JSON Schema permits either a schema object or the boolean schemas `true` and `false`. */
 export type JsonSchema = boolean | Readonly<Record<string, unknown>>
 
@@ -460,7 +465,9 @@ export interface ReflectedHook {
   readonly kind: HookKind
   /** The plugin that registered it, else the function's own name, else `(anonymous)`. */
   readonly name: string
-  /** Where it was registered: `app`, `group /api`, `merge #1`, `mount /auth`, or `unknown`. */
+  /** Where it was registered: `app`, `group /api`, `merge #1`, `mount /auth`, or `unknown`; `route`
+   * for a runtime the route resolved at registration (`responseContract`, `effectLedger`,
+   * `idempotency`), whose `name` is the contract mode or the runtime. */
   readonly site: string
   /** The header names a static `responseHeaders()` declaration sets. */
   readonly headers?: readonly string[]
@@ -559,6 +566,51 @@ const catalogOf = (
 const joinPath = (base: string, path: string): string =>
   base === "" ? path : path === "/" ? base : `${base}${path}`
 
+/** A `merge()` that authenticates none of its routes under a parent that authenticates its own. */
+export type ReflectedMergeAuthGap = MergeAuthGapTag
+
+/**
+ * Every `merge()` in the app, its merged servers included, whose server authenticates none of its
+ * routes while the parent's order-scoped auth - an `authenticate()` stage, or `authenticated` evidence
+ * scoped to subsequent routes - covers the parent's own: that auth never runs for a merged route.
+ * Recorded by a development load only (the same provenance {@link reflectHooks} reads), so reflect the
+ * app outside production. `nifra check` reports each one (NF-C043).
+ */
+export function reflectMergeAuthGaps(source: unknown): readonly ReflectedMergeAuthGap[] {
+  if (!isServerRecord(source)) return []
+  const gaps: ReflectedMergeAuthGap[] = []
+  const seen = new Set<object>()
+  const visit = (server: object): void => {
+    if (seen.has(server)) return
+    seen.add(server)
+    gaps.push(...mergeAuthGapsOf(server))
+    for (const adoption of adoptionsOf(server)) visit(adoption.source)
+  }
+  visit(source)
+  return gaps
+}
+
+/**
+ * Where each route was registered: `METHOD /path` (`WS` for a socket) mapped to the `file:line:col` of
+ * the call outside nifra's core that registered it, through every `group()` and `merge()`. Recorded only
+ * by a development load with `NIFRA_ROUTE_SITES=1` (the CLI sets it while it loads `nifra.assurance.ts`),
+ * so the map is empty otherwise. The paths are absolute, which is why they stay out of
+ * {@link reflectRoutes}, whose output is written into artifacts.
+ */
+export function reflectRouteSites(source: unknown): ReadonlyMap<string, string> {
+  const sites = new Map<string, string>()
+  if (!isServerRecord(source)) return sites
+  const seen = new Set<object>()
+  const visit = (server: object): void => {
+    if (seen.has(server)) return
+    seen.add(server)
+    for (const [key, site] of routeSitesOf(server)) if (!sites.has(key)) sites.set(key, site)
+    for (const adoption of adoptionsOf(server)) visit(adoption.source)
+  }
+  visit(source)
+  return sites
+}
+
 /**
  * Every hook that actually runs for each route, and for each prefix's unmatched paths, with the plugin
  * that registered it and where: the app, a `group()`, a `merge()`d server, or a `mount()`ed one. It
@@ -698,16 +750,24 @@ export function reflectHooks(source: unknown): ReflectedHookReport {
       const entry = recordOf(route.entry)
       const chain = (field: string, kind: HookKind) =>
         entry === undefined ? [] : listOf(entry, field).flatMap((hook) => entriesOf(hook, kind))
+      // A runtime is pinned into the route when it registers (or is merged), so it is listed with the
+      // route's site rather than a hook's; the mode is the name so a warn -> enforce change shows.
+      const mode = recordOf(recordOf(entry?.responseContract)?.runtime)?.mode
+      const pinned = (present: boolean, kind: HookKind, name: string): ReflectedHook[] =>
+        present ? [{ kind, name, site: "route" }] : []
       routes.push({
         method: route.method,
         path: reportPath(route.path),
         hooks: [
           ...requestPhase(probes),
           ...chain("around", "around"),
+          ...pinned(entry?.ledgered !== undefined, "effectLedger", "effectLedger"),
           ...chain("authStages", "authenticate"),
           ...chain("derives", "derive"),
           ...chain("beforeHandle", "beforeHandle"),
+          ...pinned(entry?.idempotent !== undefined, "idempotency", "idempotency"),
           ...chain("afterHandle", "afterHandle"),
+          ...pinned(typeof mode === "string", "responseContract", String(mode)),
           ...chain("onError", "onError"),
           ...responsePhase(probes),
         ],

package/src/server/body-lane.ts

@@ -3,6 +3,7 @@
  * reuse the exact trust-boundary lane without bundling the full context implementation (cookies,
  * deferred responses, and request helpers).
  */
+import { isSameOriginForm } from "../internal/same-origin.ts"
 import { drainCapped, hasTrustedBodyFraming, parseContentLength, RAW_BODY_READERS } from "./body.ts"
 import { plainError } from "./http.ts"
 import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
@@ -191,10 +192,39 @@ export type SchemaBodyReader = ((
   readonly mediaTypes?: readonly string[]
 }
 
+/**
+ * Origins besides the request's own whose HTML forms may post a body: exact origins, or a function
+ * that receives the request's `Origin`.
+ */
+export type FormOrigins = ReadonlyArray<string> | ((origin: string) => boolean)
+
+/** The media types a cross-site HTML form can send with the visitor's cookies and no preflight. */
+function isFormMediaType(contentType: string): boolean {
+  const semi = contentType.indexOf(";")
+  const essence = (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase()
+  return (
+    essence === "application/x-www-form-urlencoded" ||
+    essence === "multipart/form-data" ||
+    essence === "text/plain"
+  )
+}
+
+function formOriginAllowed(source: RequestSource, formOrigins: FormOrigins | undefined): boolean {
+  const origin = headerOf(source, "origin")
+  if (origin === null || isSameOriginForm(origin, headerOf(source, "sec-fetch-site"), source)) {
+    return true
+  }
+  if (formOrigins === undefined) return false
+  return typeof formOrigins === "function"
+    ? formOrigins(origin) === true
+    : formOrigins.includes(origin)
+}
+
 /**
  * The shared content-type dispatcher around the JSON and urlencoded lanes. A `bodySchema` branded
  * with {@link SCHEMA_BODY_READER} takes every other media type; JSON and urlencoded bodies keep
- * their lanes whatever the schema carries.
+ * their lanes whatever the schema carries. A form media type whose `Origin` is another site's, and
+ * not one of `formOrigins`, is refused with `403` before the body is read.
  */
 export function readBodyFramed<T>(
   source: RequestSource,
@@ -204,9 +234,14 @@ export function readBodyFramed<T>(
   wrapResponse: (response: Response | ResponseResult) => T,
   onError: (err: unknown) => MaybePromise<T>,
   bodySchema?: object,
+  formOrigins?: FormOrigins,
 ): Promise<T> {
   const contentType = headerOf(source, "content-type") ?? ""
   if (!isJsonMediaType(contentType)) {
+    // JSON needs a preflight, so CORS judges it; a form body reaches here from any site with cookies.
+    if (isFormMediaType(contentType) && !formOriginAllowed(source, formOrigins)) {
+      return Promise.resolve(wrapResponse(plainError(403, "forbidden_origin")))
+    }
     if (isUrlEncodedForm(contentType)) {
       return readBoundedForm(source, maxBodyBytes).then(
         (form) => (isResponseResult(form) ? wrapResponse(form) : onParsed(form)),

package/src/server/client-ip.ts

@@ -56,7 +56,9 @@ export function resolveClientIp(
   if (trust === undefined) return peer
   if ("header" in trust) return firstHeaderValue(req, trust.header)
 
-  // trustedHops: walk `X-Forwarded-For` (client-most first) plus the socket peer as the closest hop.
+  if (trust.trustedHops === 0) return peer
+  // Hop 0 is the socket peer and hop k the k-th XFF entry from the right, so the caller is read from the
+  // header alone: a peer-less request (Workers, a unix socket) must not shift an attacker's entry in.
   const xff = req.headers.get("x-forwarded-for")
   const forwarded =
     xff === null
@@ -65,8 +67,6 @@ export function resolveClientIp(
           .split(",")
           .map((entry) => entry.trim())
           .filter((entry) => entry !== "")
-  const chain = peer !== undefined ? [...forwarded, peer] : forwarded
-  // The caller sits just left of the `trustedHops` trusted proxies at the tail of the chain.
-  const index = chain.length - 1 - trust.trustedHops
-  return index >= 0 ? chain[index] : undefined
+  const index = forwarded.length - trust.trustedHops
+  return index >= 0 ? forwarded[index] : undefined
 }

package/src/server/context.ts

@@ -312,9 +312,12 @@ export interface RouteSchema {
    * The schema must cover every path param; with the strict default an undeclared path param is rejected.
    * When omitted, `c.params` stays the path-inferred `Record<name, string>`. */
   readonly params?: StandardSchemaV1
-  /** Optional request-header schema. Header names are normalized to lower-case and the validated
-   * output is exposed as `c.headers`; use lower-case keys because HTTP header names are
-   * case-insensitive. */
+  /** Optional request-header schema; the validated output is `c.headers` and a failure is a `422`.
+   * Every client sends headers a route never declares (`host`, `user-agent`, `accept`), so a closed
+   * object schema (`t.object`) validates only the names it declares, each read case-insensitively and
+   * keyed as declared. `t.headers` is the open form: it receives every header, names lower-cased,
+   * and coerces values like `t.query`. A schema that does not expose its JSON Schema (a zod
+   * `.strict()` or valibot `strictObject`) receives every header, so declare it open. */
   readonly headers?: StandardSchemaV1
   /** Optional request-cookie schema. It validates the cookies parsed from the `Cookie` header -
    * names as sent, values URL-decoded strings, the first of a repeated name - before the handler
@@ -446,7 +449,7 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   /** Read one request header without materializing a Web `Request` on the Node adapter hot path. */
   readonly header: (name: string) => string | null
   readonly params: ParamsOf<S, Path>
-  /** Lower-case request headers, validated/coerced when `schema.headers` is declared. */
+  /** Request headers, names lower-cased; when `schema.headers` is declared, its validated output. */
   readonly headers: HeadersOf<S>
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>

package/src/server/cookies.ts

@@ -212,17 +212,28 @@ export function serializeCookie(name: string, value: string, options: CookieOpti
 
 const TEXT = new TextEncoder()
 
+// Imported once per secret: every signed-cookie read and write, and every auth session check, signs or
+// verifies. Bounded, since a secret can come from per-tenant configuration.
+const HMAC_KEYS = new Map<string, Promise<CryptoKey>>()
+const MAX_HMAC_KEYS = 64
+
 const importHmacKey = (secret: string): Promise<CryptoKey> => {
+  const cached = HMAC_KEYS.get(secret)
+  if (cached !== undefined) return cached
   // Reject a weak secret at the choke point both signing and verification flow through (so signed
   // cookies AND @nifrajs/auth sessions, which delegate here via signValue/unsignValue, are covered).
   requireSecretBytes(secret, "signed-cookie")
-  return crypto.subtle.importKey(
+  const key = crypto.subtle.importKey(
     "raw",
     TEXT.encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["sign", "verify"],
   )
+  if (HMAC_KEYS.size >= MAX_HMAC_KEYS) HMAC_KEYS.clear()
+  HMAC_KEYS.set(secret, key)
+  key.catch(() => HMAC_KEYS.delete(secret))
+  return key
 }
 
 const toBase64Url = (buf: ArrayBuffer): string => {

package/src/server/core-copies.ts

@@ -10,6 +10,7 @@
  */
 const registry = globalThis as unknown as Record<symbol, string[] | undefined>
 const COPIES = Symbol.for("nifra.core.copies")
+const VERSIONS = Symbol.for("nifra.core.copy-versions")
 registry[COPIES] ??= []
 const copies = registry[COPIES]
 const here = String(import.meta.url).split("?")[0] as string
@@ -19,3 +20,42 @@ if (!copies.includes(here) && copies.push(here) > 1) {
     `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}`,
   )
 }
+
+/** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
+ * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
+const COPY_VERSION = "5.2.0"
+
+/** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
+ * so a production bundle drops it with the version; a copy that built a server has recorded one. */
+export function recordCopyVersion(): void {
+  versionsByUrl().set(here, COPY_VERSION)
+}
+
+/** The process-wide URL -> version map every copy shares. */
+const versionsByUrl = (): Map<unknown, unknown> => {
+  const found: unknown = Reflect.get(globalThis, VERSIONS)
+  if (found instanceof Map) return found
+  const created = new Map<unknown, unknown>()
+  Reflect.set(globalThis, VERSIONS, created)
+  return created
+}
+
+const labelled = (url: string): string => {
+  const version = versionsByUrl().get(url)
+  return typeof version === "string" ? `${url} (${version})` : url
+}
+
+/** Why `merge()` refused a value that is not a server of this copy: when another copy is loaded, the
+ * value is most likely its server, so both copies are named, with their versions where recorded
+ * (copies before 5.2 record none), and the way to collapse them. Called only outside production. */
+export function mergeRefusal(): string {
+  const base = "merge() requires a server() from this copy of @nifrajs/core"
+  const others = copies.filter((url) => url !== here)
+  if (others.length === 0) return base
+  return [
+    `${base}, and ${copies.length} copies are loaded:`,
+    `  this copy:  ${labelled(here)}`,
+    ...others.map((url) => `  other copy: ${labelled(url)}`),
+    "A server() from another copy cannot be merged. Make every package that builds a server() resolve one copy: in a linked repository, install the same nifra version (`nifra upgrade <version> --write`, then `bun install`); `nifra doctor` names each importer.",
+  ].join("\n")
+}