@nifrajs/core 5.0.0 → 5.1.0

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/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/edge.ts

@@ -116,7 +116,8 @@ export function toFetchHandler<Env = unknown>(
       const platform: Platform<Env> = { env, waitUntil: (promise) => ctx.waitUntil(promise) }
       // WebSocket broadcast on Workers: route upgrades to the hub Durable Object (it holds the
       // connections + runs the app's pub/sub, so `app.publish` reaches every client). The hub itself
-      // resolves the route and rejects non-WS paths. See `@nifrajs/workers`' `createWebSocketHub`.
+      // resolves the route, and a request that is no handshake for a WebSocket route gets its HTTP
+      // answer there. See `@nifrajs/workers`' `createWebSocketHub`.
       if (
         webSocketHub !== undefined &&
         request.headers.get("upgrade")?.toLowerCase() === "websocket"

package/src/server/http.ts

@@ -30,7 +30,13 @@ export function isSameOriginPath(value: string): boolean {
     const code = value.charCodeAt(i)
     if (code === 0x5c /* \ */ || code <= 0x1f || code === 0x7f) return false
   }
-  return true
+  // `/.//host` and `/a/..//host` (or their `%2e` forms) resolve to the path `//host`, which any
+  // relative reference later built from that path - a client router's redirect - reads as a host.
+  // A path-absolute reference against a valid base always parses, so this cannot throw.
+  return (
+    !(value.includes(".") || value.includes("%")) ||
+    !new URL(value, "http://n.invalid").pathname.startsWith("//")
+  )
 }
 
 /**

package/src/server/response-contract-lane.ts

@@ -28,7 +28,9 @@
  *
  * That is not an inconsistency to paper over: a strict schema has already declared that extra fields
  * are an error, and a stripping one has declared they are ignorable. Enforcement honours what the
- * author wrote rather than overriding it.
+ * author wrote rather than overriding it - unless the app asks for `extra: "strip"`. A schema that
+ * carries its JSON Schema as `jsonSchema` (every `t` schema does) CAN list its declared keys, so for
+ * those the payload is projected onto the declared shape before it is validated.
  *
  * ## What enforcement costs
  *
@@ -62,6 +64,18 @@ import type { AnyServer } from "./server.ts"
  */
 export type ResponseContractMode = "warn" | "enforce"
 
+export interface ResponseContractOptions {
+  /**
+   * Fields the schema does not declare. `"reject"` (the default) leaves them to the validator: a
+   * closed `t.object` reports them, so an enforced response becomes a 500 and the log names them.
+   * `"strip"` drops them first, for any schema exposing its JSON Schema as `jsonSchema` (every
+   * `@nifrajs/schema` `t` schema) - nested objects, arrays and records included. A union is projected
+   * only when exactly one branch can hold an object. Schemas without `jsonSchema` (zod, valibot) are
+   * unaffected: they already strip or reject by their own rules.
+   */
+  readonly extra?: "reject" | "strip"
+}
+
 /** Success and status-specific error schemas captured by one route at registration time. */
 export interface ResponseContractDefinition {
   readonly response?: StandardSchemaV1
@@ -80,6 +94,127 @@ export type ResponseContractOutcome =
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v)
 
+/** Rebuilds a value with only what its schema declares; absent when the schema can strip nothing. */
+type Projector = (value: unknown) => unknown
+
+const projectors = new WeakMap<object, Projector | null>()
+
+/** The projector for a schema's JSON Schema, compiled once per schema. */
+function projectorOf(schema: StandardSchemaV1): Projector | undefined {
+  const node: unknown = Reflect.get(schema, "jsonSchema")
+  if (typeof node !== "object" || node === null) return undefined
+  let found = projectors.get(node)
+  if (found === undefined) {
+    found = compileProjector(node) ?? null
+    projectors.set(node, found)
+  }
+  return found ?? undefined
+}
+
+const canHoldObject = (node: object): boolean => {
+  const type: unknown = Reflect.get(node, "type")
+  return type === undefined || type === "object" || type === "array"
+}
+
+const objectField = (node: object, key: string): object | undefined => {
+  const value: unknown = Reflect.get(node, key)
+  return typeof value === "object" && value !== null ? value : undefined
+}
+
+function compileProjector(node: unknown): Projector | undefined {
+  if (typeof node !== "object" || node === null) return undefined
+  const schema: object = node
+  const type: unknown = Reflect.get(schema, "type")
+  const branches: unknown = Reflect.get(schema, "anyOf") ?? Reflect.get(schema, "oneOf")
+  if (Array.isArray(branches)) {
+    // Which branch a value meets is the validator's call; projecting onto one of two object branches
+    // could strip the fields that make the other match.
+    const holders = branches.filter(
+      (branch): branch is object =>
+        typeof branch === "object" && branch !== null && canHoldObject(branch),
+    )
+    const only = holders.length === 1 ? compileProjector(holders[0]) : undefined
+    return only === undefined
+      ? undefined
+      : (value) => (typeof value === "object" && value !== null ? only(value) : value)
+  }
+  if (type === "array") {
+    const items: unknown = Reflect.get(schema, "items")
+    const item = Array.isArray(items) ? undefined : compileProjector(items)
+    return item === undefined
+      ? undefined
+      : (value) => (Array.isArray(value) ? value.map(item) : value)
+  }
+  if (type !== "object") return undefined
+  const properties = objectField(schema, "properties") ?? {}
+  const keys = Object.keys(properties)
+  const nested = new Map<string, Projector>()
+  for (const key of keys) {
+    const projector = compileProjector(Reflect.get(properties, key))
+    if (projector !== undefined) nested.set(key, projector)
+  }
+  const patterns: Array<readonly [RegExp, Projector | undefined]> = []
+  for (const [source, child] of Object.entries(objectField(schema, "patternProperties") ?? {})) {
+    let pattern: RegExp
+    try {
+      pattern = new RegExp(source, "u")
+    } catch {
+      return undefined // a pattern this engine can't read: the validator judges the value whole
+    }
+    patterns.push([pattern, compileProjector(child)])
+  }
+  const closed = Reflect.get(schema, "additionalProperties") === false
+  if (!closed && nested.size === 0 && patterns.every(([, projector]) => projector === undefined))
+    return undefined
+  const declared = new Set(keys)
+  return (value) => {
+    if (!isPlainObject(value)) return value
+    const out: Record<string, unknown> = closed ? {} : { ...value }
+    for (const key of closed ? keys : nested.keys()) {
+      // A getter on a row class's prototype is a declared field; `Object.prototype`'s members are not.
+      if (!Object.hasOwn(value, key) && (!(key in value) || key in Object.prototype)) continue
+      const projector = nested.get(key)
+      define(out, key, projector === undefined ? value[key] : projector(value[key]))
+    }
+    if (patterns.length > 0) projectPatternKeys(value, out, declared, patterns, closed)
+    return out
+  }
+}
+
+/**
+ * Carry the undeclared keys a `patternProperties` entry admits: a closed record's keys are all
+ * pattern keys, so dropping them empties a valid value. A key two patterns match is copied verbatim,
+ * since projecting it onto one could strip what the other requires.
+ */
+function projectPatternKeys(
+  value: Record<string, unknown>,
+  out: Record<string, unknown>,
+  declared: ReadonlySet<string>,
+  patterns: ReadonlyArray<readonly [RegExp, Projector | undefined]>,
+  closed: boolean,
+): void {
+  for (const key of Object.keys(value)) {
+    if (declared.has(key)) continue
+    let projector: Projector | undefined
+    let matches = 0
+    for (const [pattern, child] of patterns)
+      if (pattern.test(key)) {
+        projector = child
+        matches++
+      }
+    if (matches === 0) continue
+    if (matches === 1 && projector !== undefined) define(out, key, projector(value[key]))
+    else if (closed) define(out, key, value[key])
+  }
+}
+
+/** `__proto__` is a declared name like any other here; plain assignment would set the prototype. */
+function define(out: Record<string, unknown>, key: string, value: unknown): void {
+  if (key === "__proto__")
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true })
+  else out[key] = value
+}
+
 /** Top-level keys present in the handler's result but absent from the validated value. */
 function droppedKeys(result: unknown, value: unknown): string[] {
   if (!isPlainObject(result) || !isPlainObject(value)) return []
@@ -96,8 +231,9 @@ export function checkResponseContract(
   schema: StandardSchemaV1,
   result: unknown,
   mode: "warn" | "enforce",
+  options?: ResponseContractOptions,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
-  return checkRouteResponseContract({ response: schema }, result, mode)
+  return checkRouteResponseContract({ response: schema }, result, mode, undefined, options)
 }
 
 /** The schema a reply with this status is held to: `response` for 2xx, else `errors[status]`. */
@@ -127,12 +263,14 @@ export function checkRouteResponseContract(
   result: unknown,
   mode: "warn" | "enforce",
   jsonReply?: { readonly body: unknown },
+  options?: ResponseContractOptions,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
+  const strip = options?.extra === "strip"
   const plain = isResponseResult(result) ? result.plain : undefined
   if (plain !== undefined) {
     const schema = schemaFor(definition, plain.status)
     if (schema === undefined) return { kind: "ok", value: result }
-    return validateContract(schema, plain.body, result, mode, (value) =>
+    return validateContract(schema, plain.body, result, mode, strip, (value) =>
       status(
         plain.status,
         value,
@@ -143,7 +281,7 @@ export function checkRouteResponseContract(
   if (jsonReply !== undefined && result instanceof Response) {
     const schema = schemaFor(definition, result.status)
     if (schema === undefined) return { kind: "ok", value: result }
-    return validateContract(schema, jsonReply.body, result, mode, (value) =>
+    return validateContract(schema, jsonReply.body, result, mode, strip, (value) =>
       reserialize(result, value),
     )
   }
@@ -155,7 +293,7 @@ export function checkRouteResponseContract(
   if (result instanceof Response || result === undefined) return { kind: "ok", value: result }
   const schema = definition.response
   if (schema === undefined) return { kind: "ok", value: result }
-  return validateContract(schema, result, result, mode, (value) => value)
+  return validateContract(schema, result, result, mode, strip, (value) => value)
 }
 
 /** Validate `payload`; `served` is what goes out unchanged when nothing is enforced - the whole
@@ -165,9 +303,11 @@ function validateContract(
   payload: unknown,
   served: unknown,
   mode: "warn" | "enforce",
+  strip: boolean,
   replace: (value: unknown) => unknown,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
-  const settled = schema["~standard"].validate(payload)
+  const project = strip ? projectorOf(schema) : undefined
+  const settled = schema["~standard"].validate(project === undefined ? payload : project(payload))
   return settled instanceof Promise
     ? settled.then((r) => interpret(r, payload, served, mode, replace))
     : interpret(settled, payload, served, mode, replace)
@@ -195,7 +335,7 @@ function interpret(
     : {
         kind: "warn",
         value: served,
-        message: `response carries fields its contract does not declare: ${dropped.join(", ")}. They are being sent; \`responseContract: "enforce"\` would strip them.`,
+        message: `response carries fields its contract does not declare: ${dropped.join(", ")}. They are being sent; \`responseContract("enforce")\` would strip them.`,
       }
 }
 
@@ -219,10 +359,12 @@ interface ResponseContractInstallable {
 /**
  * Hold every route's declared `response` schema to what the handler actually returned.
  *
- *     app.use(responseContract("enforce"))
+ *     app.use(responseContract("enforce"))                      // a closed t.object -> 500 on extras
+ *     app.use(responseContract("enforce", { extra: "strip" }))  // extras dropped, declared fields sent
  *
  * Install it before the routes it should cover - like `idempotency()`, the decision is made per route
- * at registration, so routes registered earlier are not retroactively covered.
+ * at registration, so routes registered earlier are not retroactively covered. It covers routes on
+ * the server it is installed on, its `group()`s, and servers `merge()`d into it afterwards.
  *
  * The check itself is cheap - with a compiled validator it measures in the ~100ns-per-response
  * range, within benchmark noise of an uncontracted route on any route that carries middleware or a
@@ -231,7 +373,16 @@ interface ResponseContractInstallable {
  * taking anyway. Opt-in because not installing the plugin keeps the lane out of the bundle, not
  * because enforcement is expensive.
  */
-export function responseContract(mode: ResponseContractMode = "warn"): IdentityPlugin {
+export function responseContract(
+  mode: ResponseContractMode = "warn",
+  options: ResponseContractOptions = {},
+): IdentityPlugin {
+  if (options.extra !== undefined && options.extra !== "reject" && options.extra !== "strip") {
+    throw new TypeError(
+      `responseContract(): extra must be "reject" or "strip", got ${JSON.stringify(options.extra)}`,
+    )
+  }
+  const contractOptions = options.extra === "strip" ? options : undefined
   const runtime: ResponseContractRuntime = {
     mode,
     check: (definition, result, context) =>
@@ -242,6 +393,7 @@ export function responseContract(mode: ResponseContractMode = "warn"): IdentityP
         result instanceof Response && result === context?.jsonReply
           ? { body: context.jsonBody }
           : undefined,
+        contractOptions,
       ),
   }
   const apply = <S extends AnyServer>(app: S): S => {

package/src/server/server-types.ts

@@ -59,10 +59,18 @@ export interface ServerOptions {
    * `__proto__` key, or a `constructor` carrying a `prototype`, is the payload shape that turns a
    * later innocent merge/assign into prototype pollution. `"reject"` (default) answers the same
    * flat 400 as malformed JSON; `"strip"` removes the offending keys and continues; `"ignore"`
-   * parses as-is (only for routes that never merge body input into other objects). Clean payloads
-   * pay a substring pre-scan only - the deep walk runs solely on suspect text.
+   * parses as-is (only for routes that never merge body input into other objects). Every guarded
+   * payload pays one iterative pass over its parsed object nodes; `"ignore"` skips it.
    */
   readonly protoPoisoning?: "reject" | "strip" | "ignore"
+  /**
+   * Other sites whose HTML forms may post to a body-schema route: exact origins, or a function that
+   * receives the `Origin`. A urlencoded, multipart or `text/plain` body is one a form on any site can
+   * send with the visitor's cookies and no preflight, so one whose `Origin` names another site is
+   * refused with `403` before it is read. Same-origin posts and requests without an `Origin`, such
+   * as server-to-server calls, pass. JSON is not affected: a browser preflights it, so CORS decides.
+   */
+  readonly formOrigins?: ReadonlyArray<string> | ((origin: string) => boolean)
   /**
    * Declare that every `Request` reaching `app.fetch` was framed by a runtime HTTP parser, so its
    * `Content-Length` is an exact transport boundary rather than a hint. Set this ONLY when the
@@ -81,9 +89,12 @@ export interface ServerOptions {
    * untrusted input.
    */
   readonly trustBodyFraming?: boolean
-  /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun - frames over this are rejected
-   * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
-   * Default: `maxBodyBytes` (1 MB). */
+  /**
+   * Max inbound WebSocket message size (bytes). A larger message never reaches the handler and the
+   * socket closes with `1009`. Default: `maxBodyBytes` (1 MB). Bun and Node stop buffering at the cap,
+   * so a huge frame is never held in memory; on Bun a mounted app's smaller cap, and on Deno and
+   * Workers every cap, is checked after the runtime has buffered the whole message.
+   */
   readonly wsMaxPayloadBytes?: number
   /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
   readonly requestTimeoutMs?: number

package/src/server/server.ts

@@ -32,7 +32,7 @@ import {
   assuranceEvidenceFor,
 } from "../internal/route-assurance.ts"
 import { type CatalogRoute, RouteCatalog } from "../internal/route-catalog.ts"
-import { compileRouteOptions } from "../internal/route-compiler.ts"
+import { adoptRouteRuntimes, compileRouteOptions } from "../internal/route-compiler.ts"
 import {
   compileRouteExecutionPlan,
   type FusedBodyRunner,
@@ -74,6 +74,7 @@ import {
 } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
 import "./core-copies.ts"
+import type { FormOrigins } from "./body-lane.ts"
 import {
   hasLowercaseHeaderKeysMark,
   headerKeysAllLowercase,
@@ -982,6 +983,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     | undefined
   private readonly maxBodyBytes: number
   private readonly protoPoisoning: "reject" | "strip" | "ignore"
+  private readonly formOrigins: FormOrigins | undefined
   /** `trustBodyFraming`: mark every `app.fetch` request as runtime-framed (see ServerOptions). */
   private readonly trustBodyFraming: boolean
   private readonly wsMaxPayloadBytes: number
@@ -1117,6 +1119,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
     assertByteLimit(maxBodyBytes, "maxBodyBytes")
     this.protoPoisoning = options.protoPoisoning ?? "reject"
+    this.formOrigins = options.formOrigins
     this.trustBodyFraming = options.trustBodyFraming ?? false
     const wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? maxBodyBytes
     assertByteLimit(wsMaxPayloadBytes, "wsMaxPayloadBytes")
@@ -2586,6 +2589,27 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * registered before a `derive`). Fail closed: a path+method collision throws
    * `RouteConfigError` at merge time, and a group with WebSocket routes or mounts is refused
    * (register those on the parent).
+   *
+   * What this server's `.use()`, made BEFORE the merge, covers on a merged route versus a
+   * `group()` route:
+   *
+   *   | installed on this server                   | group() route | merge()d route                 |
+   *   | ------------------------------------------ | ------------- | ------------------------------ |
+   *   | derive/decorate/beforeHandle/afterHandle,  | yes           | no - wire it on the merged     |
+   *   | onError/around, authenticate, route-scoped |               | server                         |
+   *   | assurance                                  |               |                                |
+   *   | onRequest/onResponse/responseHeaders hooks | yes           | yes (app-wide)                 |
+   *   | responseContract()                         | yes           | yes, when the route declares a |
+   *   |                                            |               | response and its own server    |
+   *   |                                            |               | installed no contract          |
+   *   | effectLedger()                             | yes           | yes, when the route declares   |
+   *   |                                            |               | capabilities and has no ledger |
+   *   | idempotency()                              | yes           | the merged server's own; a     |
+   *   |                                            |               | route declaring it without one |
+   *   |                                            |               | is refused at registration     |
+   *
+   * The response contract and the ledger can only add a check or a record, so a merged route is
+   * recompiled under them. A runtime installed AFTER the merge covers neither kind of route.
    */
   merge<R2 extends Registry, Ctx2, HookOutput2>(
     other: Server<R2, Ctx2, HookOutput2>,
@@ -2630,7 +2654,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * The builder receives a scope that INHERITS this server's route chain as it stands at the call
    * (`derive`/`decorate`/`authenticate`/`beforeHandle`/`afterHandle`/`onError`/`around`, assurance,
    * capability interceptors, installed runtimes, applied plugins), exactly as a route declared here
-   * would. A plugin this server already applied is in effect for the group: the group's `use()` of
+   * would. {@link merge} documents how that differs for a merged server. A plugin this server already applied is in effect for the group: the group's `use()` of
    * that same instance does nothing, and its `use()` of another instance under the same name throws a
    * `RouteConfigError` (`PLUGIN_RECONFIGURED`), because that instance could never replace the parent's.
    * A plugin the group applies still shares the parent's copy of a dependency it `use()`s itself.
@@ -2738,7 +2762,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           })
         : (route: CatalogRoute): CatalogRoute => route
     this.catalog.addBatch(
-      sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(route))),
+      sourceRoutes.map((route) =>
+        this.bindFusedRuntime(
+          foldedAssurance(
+            adoptRouteRuntimes(route, this.responseContractRuntime, this.effectLedgerRuntime),
+          ),
+        ),
+      ),
     )
     // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
     // runtime object supplies the generic execution machinery. If the parent already has a runtime,
@@ -3547,6 +3577,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
               pubsub,
               attach: runtime.attach,
               maxPayloadBytes: this.wsMaxPayloadBytes,
+              sender: runtime.sender,
             }
       }
       const wrap = (response: Response | ResponseResult): WebSocketUpgradeOutcome =>
@@ -3659,9 +3690,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       if (o.kind === "pass")
         return this.fetch(req, bunPeerPlatform(server, req) as Platform<EnvOf<Ctx>>)
       if (o.kind === "reject") return o.response
-      return server.upgrade(req, {
-        data: { handler: o.handler, data: o.data, pubsub: o.pubsub },
-      })
+      // A copy: the Bun socket keeps per-connection state on it, and a hand-built outcome may be shared.
+      return server.upgrade(req, { data: { ...o } })
         ? undefined
         : jsonError(426, "upgrade_required")
     }
@@ -4689,6 +4719,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         wrapResponse,
         (err) => logError(err, ctx, finalize, wrapResponse),
         bodySchema,
+        this.formOrigins,
       )
     }
   }
@@ -5103,6 +5134,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         (response) => this.wrapWebResponse(response),
         (err) => Promise.resolve(logError(err, ctx)),
         bodySchema,
+        this.formOrigins,
       ) as MaybePromise<Response>
     }
   }
@@ -5534,6 +5566,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         wrapResponse,
         (err) => logError(err, ctx, finalize, wrapResponse),
         bodySchema,
+        this.formOrigins,
       )
     }
   }
@@ -6189,6 +6222,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       (response) => response,
       (error) => Promise.reject(error),
       bodySchema,
+      this.formOrigins,
     )
   }
 
@@ -6554,7 +6588,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // the parent.
     const nativePubsub =
       this.wsRoutes.length > 0 && !this.mountsTakeUpgrades() && !this.wsHasValidatedSend
-    const wsHandlers = wsRuntime?.bunHandlers(this.topics ?? wsRuntime.createTopics(), nativePubsub)
+    const wsHandlers = wsRuntime?.bunHandlers(
+      this.topics ?? wsRuntime.createTopics(),
+      nativePubsub,
+      this,
+    )
     // Spread rather than pass `hostname: undefined` (or an undefined idle timeout or TLS) - Bun treats
     // an explicit undefined as a value on some option paths, and omitting is what selects its own
     // defaults, 0.0.0.0 among them.
@@ -6602,8 +6640,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           // `unknown` params bridge a TS structural-variance quirk. Round-trip covered by websocket.test.ts.
           websocket: {
             // Cap inbound frames so a huge message can't be buffered/JSON-parsed into memory; the runtime
-            // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes).
-            maxPayloadLength: this.wsMaxPayloadBytes,
+            // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes). One
+            // limit per listener: the largest cap among this app and the apps mounted on it.
+            maxPayloadLength: wsHandlers.maxPayloadLength,
             open: (ws) => wsHandlers.open(ws),
             message: (ws, message) => wsHandlers.message(ws, message),
             close: (ws, code, reason) => wsHandlers.close(ws, code, reason),