@nifrajs/core 2.10.0 → 2.12.0

package/src/server/header-case.ts

@@ -0,0 +1,54 @@
+/**
+ * The all-lowercase header-name proof: one answer, computed once per request, read by everyone who
+ * would otherwise re-derive it.
+ *
+ * "Are these header names already the lowercase wire spelling?" is asked on every Node-direct
+ * response by the implicit-Content-Type lookup in the native response walk, by the portable header
+ * view's alias index, and by the `@nifrajs/node` writer's normalization gate. Each used to answer it
+ * by walking the same keys. Instead, whichever stage has ALREADY looked at the names - the static
+ * merge, which lowercases every own key anyway, or the native walk - records the answer on the
+ * record, and the readers take it.
+ *
+ * The mark is a plain enumerable symbol assignment on purpose. `Object.keys`, `Object.entries` and
+ * `for...in` never see symbol keys, so it cannot reach the wire, while a non-enumerable
+ * `defineProperty` would demote the record to V8's dictionary mode - the exact cost the record's `{}`
+ * literal shape exists to avoid. Spread and `Object.assign` DO copy it, which is what the clone paths
+ * want: a clone of an all-lowercase record is still all-lowercase.
+ *
+ * It is only ever SET where its truth is provable, and only where every writer that can still touch
+ * the record afterwards is case-normalizing. An app registering a raw `onNodeResponse` twin - handed
+ * the record itself rather than the case-normalizing view - is left unmarked, and every reader
+ * re-derives the answer exactly as it did before the mark existed.
+ *
+ * Declared with `Symbol.for` so the `@nifrajs/node` adapter can read it by key rather than importing
+ * across the package boundary - the same cross-package convention as the body and result marks.
+ */
+const LOWERCASE_HEADER_KEYS = Symbol.for("nifra.headers.lowercase")
+
+/** True when the name contains an ASCII `A`-`Z`, i.e. is not already the wire spelling. */
+export function hasUpperAscii(name: string): boolean {
+  for (let i = 0; i < name.length; i++) {
+    const code = name.charCodeAt(i)
+    if (code >= 65 && code <= 90) return true
+  }
+  return false
+}
+
+/** True when every name in the record is already the lowercase wire spelling. */
+export function headerKeysAllLowercase(record: Readonly<Record<string, unknown>>): boolean {
+  const keys = Object.keys(record)
+  for (let i = 0; i < keys.length; i++) {
+    if (hasUpperAscii(keys[i] as string)) return false
+  }
+  return true
+}
+
+/** Record the {@link LOWERCASE_HEADER_KEYS} proof on a record the caller has just verified. */
+export function markLowercaseHeaderKeys(record: Record<string, string | readonly string[]>): void {
+  ;(record as Record<symbol, unknown>)[LOWERCASE_HEADER_KEYS] = true
+}
+
+/** True when this record carries the proof - never a claim the reader has to re-check. */
+export function hasLowercaseHeaderKeysMark(record: Readonly<Record<string, unknown>>): boolean {
+  return (record as Record<symbol, unknown>)[LOWERCASE_HEADER_KEYS] === true
+}

package/src/server/headers.ts

@@ -0,0 +1,11 @@
+/** Materialize request headers for a Standard Schema boundary.
+ *
+ * HTTP field names are case-insensitive and `Headers` already combines repeated fields using the
+ * platform's defined comma-join behavior. A null-prototype record prevents a hostile field name
+ * such as `__proto__` or `constructor` from interacting with Object.prototype before validation.
+ */
+export function headerObjectOf(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = Object.create(null) as Record<string, string>
+  for (const [name, value] of headers) out[name.toLowerCase()] = value
+  return out
+}

package/src/server/node-outcome-hook.ts

@@ -1,6 +1,7 @@
 /** Lazy Node-direct renderer seam. The base server retains the typed method but not its renderer. */
 
 import type { Platform } from "./context.ts"
+import { hasLowercaseHeaderKeysMark, hasUpperAscii } from "./header-case.ts"
 import type { NodeServeOutcome } from "./node-outcome.ts"
 import type { CtxSet, MaybePromise } from "./server.ts"
 
@@ -126,6 +127,9 @@ class RecordHeadersView implements ResponseHeadersView {
 
   #prepare(record: Record<string, string | readonly string[]>): void {
     this.#prepared = true
+    // The native response walk proved this record's names before any twin ran (and every write this
+    // view makes stores the wire spelling), so the index is known-empty without touching a key.
+    if (hasLowercaseHeaderKeysMark(record)) return
     // `Object.keys`, not `for...in`: the record is a `{}`-prototype literal on the render paths, and
     // a for-in would let an enumerable `Object.prototype` property become a header on the wire.
     const keys = Object.keys(record)
@@ -136,24 +140,15 @@ class RecordHeadersView implements ResponseHeadersView {
       // framework, `c.set`, and middleware twins all write the wire spelling. An inline ASCII scan
       // answers the common case without leaving the loop, and only a genuinely mixed-case key (a
       // hand-written `X-Foo`) pays for the lowercase copy and the alias entry.
-      if (!RecordHeadersView.#hasUpperAscii(key)) continue
+      if (!hasUpperAscii(key)) continue
       if (this.#alias === undefined) this.#alias = new Map()
       this.#alias.set(key.toLowerCase(), key)
     }
   }
 
-  /** True when the name contains an ASCII `A`-`Z`, i.e. is not already the wire spelling. */
-  static #hasUpperAscii(name: string): boolean {
-    for (let i = 0; i < name.length; i++) {
-      const code = name.charCodeAt(i)
-      if (code >= 65 && code <= 90) return true
-    }
-    return false
-  }
-
   /** The wire spelling of a header name, without paying `toLowerCase` when it already is one. */
   static #lower(name: string): string {
-    return RecordHeadersView.#hasUpperAscii(name) ? name.toLowerCase() : name
+    return hasUpperAscii(name) ? name.toLowerCase() : name
   }
 
   /** The stored key for an already-lowercased name. Resolution is the prepared index ONLY - a

package/src/server/node-outcome.ts

@@ -138,10 +138,18 @@ export function nodeOutcomeToResponse(outcome: NodeServeOutcome): Response {
  * The record handed over is always a fresh copy: the Node writers mutate the outcome's record in
  * place (content-type, content-length, cookies), and the static record is shared by every request.
  * Its names are already lowercase, so the writer's all-lowercase fast path still holds.
+ *
+ * `markLowercase` publishes that fast path as a proof on the record instead of leaving each reader to
+ * re-derive it. This stage can answer it for free - the static names were lowercased at registration
+ * and the merge lowercases every own name anyway - and it runs BEFORE the response hooks, so it
+ * covers the hookless lane too, which never reaches the native walk that would otherwise mark. The
+ * caller passes `false` for an app carrying a raw `onNodeResponse` twin: that twin writes the record
+ * directly, past the case-normalizing view, after this point.
  */
 export function withStaticNodeHeaders(
   outcome: NodeServeOutcome,
   statics: StaticResponseHeaders,
+  markLowercase = false,
 ): NodeServeOutcome {
   if (outcome.kind === "response") {
     return { kind: "response", response: applyStaticResponseHeaders(outcome.response, statics) }
@@ -149,8 +157,8 @@ export function withStaticNodeHeaders(
   const own = outcome.headers
   const headers =
     own === undefined
-      ? staticHeaderRecordCopy(statics)
-      : mergeStaticHeaderRecord(statics.record, own)
+      ? staticHeaderRecordCopy(statics, markLowercase)
+      : mergeStaticHeaderRecord(statics.record, own, markLowercase)
   return { ...outcome, headers }
 }
 

package/src/server/plugin.ts

@@ -3,7 +3,8 @@
  * `use`/`derive`/`decorate` and/or registering routes) and returns it; these helpers attach a name
  * for idempotent dedupe and pin the type-threading so `.use()` preserves the caller's typed server.
  */
-import type { AnyServer } from "./server.ts"
+import type { Registry } from "./registry.ts"
+import type { AnyServer, Server } from "./server.ts"
 
 /**
  * A nifra **plugin**: a function that augments an app - calling `use`/`derive`/`decorate` and/or
@@ -26,26 +27,104 @@ export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
   readonly pluginName?: string
 }
 
+/**
+ * A named plugin built with {@link defineContextPlugin}: it adds the context `D` to every handler
+ * downstream while threading the caller's route registry and existing context UNCHANGED. This is the
+ * type {@link definePlugin} cannot express - `definePlugin` infers its parameter from an untyped
+ * `(app) => ...` arrow, which lands on `AnyServer`, so `use` returns `Server<any, any>`.
+ */
+export type ContextPlugin<D extends object> = (<R extends Registry, Ctx>(
+  app: Server<R, Ctx>,
+) => Server<R, Ctx & D>) & { readonly pluginName?: string }
+
+/**
+ * Define a named plugin that **adds typed context and nothing else** - the `derive` case - without
+ * collapsing the caller's types. `use` instantiates the generic signature against the concrete
+ * receiver, so `R` and `Ctx` come back unchanged with `D` intersected onto the context.
+ *
+ * Use this instead of {@link definePlugin} for every `(app) => app.derive(...)` plugin. `definePlugin`
+ * is only safe when the caller supplies `In`/`Out` explicitly; with the usual untyped arrow both
+ * default to `AnyServer` and the typed client silently collapses to `any`.
+ *
+ * ```ts
+ * export const requestId = defineContextPlugin<{ requestId: string }>("requestId", (app) =>
+ *   app.derive(() => ({ requestId: crypto.randomUUID() })),
+ * )
+ * const api = server().get("/a", h).use(requestId).get("/b", h) // /a AND /b stay typed; c.requestId typed
+ * ```
+ */
+export function defineContextPlugin<D extends object>(
+  name: string,
+  apply: <R extends Registry, Ctx>(app: Server<R, Ctx>) => Server<R, Ctx & D>,
+): ContextPlugin<D> {
+  return Object.assign(apply, { pluginName: name }) as ContextPlugin<D>
+}
+
+declare const COLLAPSED: unique symbol
+
+/**
+ * What {@link definePlugin} returns when its `apply` argument never pinned the input server type -
+ * the `definePlugin("x", (app) => ...)` arrow, where `app` falls back to `AnyServer`.
+ *
+ * It is deliberately **not callable**, so `app.use(thatPlugin)` is a type error at the call site
+ * instead of a silent widening to `Server<any, any>` that surfaces hundreds of lines away as
+ * `Property 'x' does not exist on type 'Promise<Result<unknown, unknown>>'` in the typed client.
+ *
+ * The plugin still works at runtime. To fix the type, pick the definer that matches what it does:
+ *
+ * - adds context via `derive`/`decorate` -> {@link defineContextPlugin}
+ * - mounts routes/hooks and adds NO context -> {@link defineRouterPlugin} ({@link defineIdentityPlugin})
+ * - genuinely needs `definePlugin`: annotate the parameter (`(app: typeof api) => ...`) or pass
+ *   explicit type arguments (`definePlugin<typeof api, typeof api>(...)`).
+ */
+export interface PluginTypeCollapsed {
+  readonly [COLLAPSED]: "definePlugin erased the caller's server type: use defineContextPlugin (adds context) or defineRouterPlugin (routes/hooks only), or pin the input type"
+}
+
+/**
+ * True when `S`'s route registry is `any` - i.e. nothing pinned the plugin's input server type, so
+ * every route type flowing through it is about to be widened away.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: matches any Server shape to inspect its Registry alone
+type ServerTypeUnpinned<S> = [S] extends [Server<infer R, any>]
+  ? 0 extends 1 & R
+    ? true
+    : false
+  : false
+
+export type DefinePluginResult<In extends AnyServer, Out extends AnyServer> =
+  ServerTypeUnpinned<In> extends true ? PluginTypeCollapsed : NifraPlugin<In, Out>
+
 /**
  * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
  * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
  * other without double-registering hooks.
  *
  * ```ts
- * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * export const requestId = definePlugin("requestId", (app: typeof api) =>
+ *   app.derive(() => ({ requestId: uuid() })),
+ * )
  * app.use(requestId)   // downstream handlers see c.requestId
  * ```
  *
- * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
- * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
- * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
- * and your whole typed client silently collapses to `any` - no type error, no runtime error.
+ * This helper only threads types when the caller pins the input server type - by annotating the
+ * parameter as above, or with explicit type arguments. With a bare `(app) => ...` arrow `app` infers as
+ * `AnyServer`, which would widen the caller's whole route registry to `any`; that case now returns
+ * {@link PluginTypeCollapsed}, so `.use()` fails to compile with one error at the call site rather than
+ * producing a typed client full of `any`. Prefer a definer that cannot collapse at all:
+ *
+ * - adds context via `derive`/`decorate` -> {@link defineContextPlugin}
+ * - mounts routes/hooks and adds NO context -> {@link defineRouterPlugin} ({@link defineIdentityPlugin})
  */
 export function definePlugin<In extends AnyServer, Out extends AnyServer>(
   name: string,
   apply: (app: In) => Out,
-): NifraPlugin<In, Out> {
-  return Object.assign(apply, { pluginName: name }) as NifraPlugin<In, Out>
+): DefinePluginResult<In, Out>
+export function definePlugin(
+  name: string,
+  apply: (app: AnyServer) => AnyServer,
+): NifraPlugin<AnyServer, AnyServer> {
+  return Object.assign(apply, { pluginName: name })
 }
 
 /**

package/src/server/proto-guard.ts

@@ -0,0 +1,118 @@
+/**
+ * Prototype-poisoning guard for the JSON body lane - the check behind `c.boundedJson` and the
+ * schema path. A single walk of the parsed value, never a reviver (a reviver taxes every key of
+ * every parse, including the parses that carry no object at all).
+ *
+ * No raw-text pre-scan: the Fastify-style `text.includes('"__proto__"')` filter is a pessimization
+ * on 2026 engines. A quoted-name search runs a general substring algorithm over the whole body,
+ * while the walk only touches the nodes the parse already built. Measured on Node 26 and Bun 1.3,
+ * three `includes()` calls cost 2-4x the walk on every body shape an API actually receives
+ * (records, strings, nested objects); the scan only wins on a body that is mostly a flat array of
+ * numbers, where it saves ~1.5us on a 9KB payload that spends 20us in `JSON.parse` regardless.
+ * Dropping the tier also removes an escape-analysis obligation - the scan had to route every `\u`
+ * to the walk, because `_` spells `_`.
+ */
+
+export type ProtoPoisoning = "reject" | "strip" | "ignore"
+
+/** Thrown (as a reused singleton - never surfaced, always mapped to a flat 400) on `"reject"`. */
+const POISONED = new Error("json_proto_poisoning")
+
+/**
+ * `JSON.parse` + the poisoning policy. Returns the parsed value (stripped in place under
+ * `"strip"`); throws on invalid JSON or - via the same catch path - on a rejected poisoning, so
+ * a poisoned payload is indistinguishable from malformed JSON to the caller.
+ */
+export function parseJsonGuarded(text: string, policy: ProtoPoisoning): unknown {
+  return guardParsedValue(JSON.parse(text), policy)
+}
+
+/**
+ * The policy applied to an already-parsed value - the native-`json()` lane, which never holds the
+ * raw text, and the transport codecs, which parse with their own decoder. Escapes are resolved by
+ * the time a key is an own property, so a `\u`-spelled `__proto__` and a literal one look identical
+ * here. Cost is one iterative pass over the value's object nodes; `"ignore"` skips even that.
+ * Throws the reject singleton; callers map it to their lane's flat error.
+ */
+export function guardParsedValue(value: unknown, policy: ProtoPoisoning): unknown {
+  if (policy === "ignore") return value
+  return sweep(value, policy)
+}
+
+/**
+ * Iterative deep-walk (adversarial nesting must not blow the call stack). An own key
+ * `__proto__`, or an own `constructor` whose value carries an own `prototype`, is the poisoning
+ * shape - `JSON.parse` creates these as plain data properties, and the blast radius is whatever
+ * downstream merge/assign later copies them onto a real prototype. A string *value* of
+ * `"__proto__"` is legal data and never triggers.
+ */
+/** Reused walk stack - `sweep` is synchronous and single-threaded, and a thrown rejection can
+ * leave residue, so each entry clears it. Saves one array allocation per swept request. */
+const STACK: unknown[] = []
+
+function sweep(root: unknown, policy: "reject" | "strip"): unknown {
+  if (root === null || typeof root !== "object") return root
+  const stack = STACK
+  stack.length = 0
+  stack.push(root)
+  while (stack.length > 0) {
+    const node = stack.pop() as object
+    if (Array.isArray(node)) {
+      // Only objects are stacked, here and below: a scalar carries no keys, so pushing it just to
+      // pop and type-test it is pure stack traffic. Filtering at the push site measured 1.5-3x
+      // faster on every body shape, both engines - the win grows with how scalar-heavy the body is.
+      //
+      // Indexed, not `for...of`: JSC allocates an array iterator per loop and calls `next()` per
+      // element, and it does not escape either. Measured on Bun 1.3 the iterator form costs 4x on
+      // an array of records, 8x on strings, and 12x on numbers - a 9KB numeric body walked in 27us
+      // instead of 2.2us, which at the 1MB default cap is milliseconds of CPU an attacker picks.
+      // V8 optimizes the iterator away, so on Node the two forms measure identical; the indexed
+      // loop is simply the form that is fast on both.
+      for (let i = 0; i < node.length; i++) {
+        const item = node[i]
+        if (item !== null && typeof item === "object") stack.push(item)
+      }
+      continue
+    }
+    const record = node as Record<string, unknown>
+    // One pass, not two `Object.hasOwn` probes plus a walk: the suspect names are checked against
+    // the keys the walk already enumerates, so a clean node pays two pointer-comparisons per key
+    // instead of two hash lookups per node (measured ~30ns/request cheaper on a typical API body).
+    // `for-in`, not `Object.keys()`: the keys array would be an allocation per node (~2x the whole
+    // walk on measured bodies, both engines, at realistic widths; V8 only prefers `Object.keys` on
+    // 200+-property dictionary-mode objects). On JSON.parse output the two enumerate identically -
+    // own enumerable string keys, nothing enumerable on the prototype chain. A custom transport
+    // codec could hand `guardParsedValue` an object with enumerable INHERITED properties; `for-in`
+    // sweeps those too, which only over-sweeps - a poisoned inherited subtree rejects rather than
+    // slips through. A *non-enumerable* own `__proto__` is the one shape this misses, and it is
+    // not the poisoning shape: `JSON.parse` never produces one, and the merges that carry the
+    // payload onward (spread, `Object.assign`, key loops) copy enumerable own keys only.
+    for (const key in record) {
+      const value = record[key]
+      const nested = value !== null && typeof value === "object"
+      // Keep the hot clean-key check branch-local and cheap. JSON keys are strings, and the length
+      // + first-code-unit guards avoid a full string comparison for the overwhelming majority of
+      // fields while preserving exact equality for the two security-sensitive names.
+      if (key.length === 9 && key.charCodeAt(0) === 95 /* _ */ && key === "__proto__") {
+        if (policy === "reject") throw POISONED
+        // biome-ignore lint/complexity/useLiteralKeys: bracket access keeps the guarded key an explicit string, never a prototype walk
+        delete record["__proto__"]
+        continue
+      }
+      if (
+        key.length === 11 &&
+        key.charCodeAt(0) === 99 /* c */ &&
+        key === "constructor" &&
+        nested &&
+        Object.hasOwn(value, "prototype")
+      ) {
+        if (policy === "reject") throw POISONED
+        // biome-ignore lint/complexity/useLiteralKeys: bracket access keeps the guarded key an explicit string, never a prototype walk
+        delete record["constructor"]
+        continue
+      }
+      if (nested) stack.push(value)
+    }
+  }
+  return root
+}

package/src/server/registry.ts

@@ -35,12 +35,16 @@ export type Registry = Record<string, Record<string, RouteInfo>>
 /** The empty registry (no routes). `NonNullable<unknown>` is `{}` without tripping noBannedTypes. */
 export type EmptyRegistry = NonNullable<unknown>
 
+/** The client-visible request inputs use the schema's INPUT side: the registry describes what a
+ * caller must SEND over the wire (pre-validation), not what the handler receives after parsing. With
+ * a Zod `.default()`/transform the two differ - `InferOutput` would force the client to supply
+ * fields the schema fills in. (Same rule as the WS `in` channel below.) */
 type RegistryBody<S extends RouteSchema> = S extends { body: infer B extends StandardSchemaV1 }
-  ? InferOutput<B>
+  ? InferInput<B>
   : never
 
 type RegistryQuery<S extends RouteSchema> = S extends { query: infer Q extends StandardSchemaV1 }
-  ? InferOutput<Q>
+  ? InferInput<Q>
   : never
 
 /** The client-visible output: the declared `response` contract when present (so the client sees the