@nifrajs/core 4.0.2 → 5.1.0

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/response-observer-runtime.ts

@@ -1,3 +1,4 @@
+import { tagSource } from "../internal/hook-origins.ts"
 import type {
   NodeRequestContext,
   NodeResponseBodyHook,
@@ -7,7 +8,7 @@ import type {
   ResponseHeadersView,
 } from "./node-outcome-hook.ts"
 import { recordHeadersView } from "./node-outcome-hook.ts"
-import { knownMutableHeaders, rememberMutableHeaders, taggedResponseBody } from "./respond.ts"
+import { taggedResponseBody, writableResponse } from "./respond.ts"
 import { applyBodyReplacement, withReplacedBody } from "./response-hooks.ts"
 
 type MaybePromise<T> = T | Promise<T>
@@ -19,6 +20,9 @@ export type {
   ResponseHeadersHook,
 } from "./node-outcome-hook.ts"
 
+// Deno reports `process.env` reads as `NotCapable` without --allow-env; read it only off Deno.
+declare const Deno: unknown
+
 export interface ResponseObserverHost {
   assertConfigurable(operation: string): void
   addResponseHook(
@@ -44,32 +48,6 @@ export interface ResponseObserverRuntime {
   install(host: ResponseObserverHost): ResponseObserverMethods
 }
 
-const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
-const GUARDED_RESPONSE_HEADERS = new WeakSet<Headers>()
-
-function hasMutableResponseHeaders(headers: Headers): boolean {
-  if (knownMutableHeaders(headers)) return true
-  if (GUARDED_RESPONSE_HEADERS.has(headers)) return false
-  let previous: string | null = null
-  try {
-    previous = headers.get(HEADER_MUTABILITY_PROBE)
-    headers.set(HEADER_MUTABILITY_PROBE, "1")
-    if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
-    else headers.set(HEADER_MUTABILITY_PROBE, previous)
-    rememberMutableHeaders(headers)
-    return true
-  } catch {
-    try {
-      if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
-      else headers.set(HEADER_MUTABILITY_PROBE, previous)
-    } catch {
-      // A guarded response rejected the probe and the clone path is authoritative.
-    }
-    GUARDED_RESPONSE_HEADERS.add(headers)
-    return false
-  }
-}
-
 function webRequestView(req: Request): NodeRequestContext {
   return { method: req.method, url: req.url, header: (name) => req.headers.get(name) }
 }
@@ -82,12 +60,8 @@ function webHeadersView(
   readonly headers: ResponseHeadersView
   readonly request: NodeRequestContext
 } {
-  const request = webRequestView(req)
-  if (!hasMutableResponseHeaders(response.headers)) {
-    const clone = new Response(response.body, response)
-    return { response: clone, headers: clone.headers, request }
-  }
-  return { response, headers: response.headers, request }
+  const writable = writableResponse(response, req)
+  return { response: writable, headers: writable.headers, request: webRequestView(req) }
 }
 
 export function createResponseObserverRuntime(): ResponseObserverRuntime {
@@ -100,12 +74,16 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
           node?: NodeResponseHook,
         ): ResponseObserverMethods {
           host.assertConfigurable("onResponseHeaders()")
+          const web: Parameters<typeof host.addResponseHook>[0] = (response, req) => {
+            const view = webHeadersView(response, req)
+            const out = fn(view.headers, view.request, response.status)
+            return out instanceof Promise ? out.then(() => view.response) : view.response
+          }
+          // Development-only provenance for `reflectHooks`; a production define folds it away.
+          if (typeof Deno === "undefined" && process.env.NODE_ENV !== "production")
+            tagSource(web, fn)
           host.addResponseHook(
-            (response, req) => {
-              const view = webHeadersView(response, req)
-              const out = fn(view.headers, view.request, response.status)
-              return out instanceof Promise ? out.then(() => view.response) : view.response
-            },
+            web,
             node ?? ((response, req) => fn(recordHeadersView(response), req, response.status)),
             true,
           )

package/src/server/runtime-core.ts

@@ -14,6 +14,8 @@ export type HandlerResult = Response | unknown
 export const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult)
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
+/** The request a context answers, read without the transport cap `req` applies for user code. */
+export const CONTEXT_REQUEST = Symbol("nifra.context.request")
 
 /**
  * A transport codec (or other pre-parsing hook) that already decoded the body stashes the value

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
@@ -109,8 +120,12 @@ export interface ServerOptions {
    * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
    */
   readonly maxInboundDeadlineMs?: number
-  /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
-  readonly gracefulSignals?: boolean
+  /**
+   * When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false.
+   * `{ drainMs }` sets how long in-flight requests get to finish before the stop forces them closed
+   * (default 10_000) - keep it under the platform's kill grace period (`docker stop` waits 10 s).
+   */
+  readonly gracefulSignals?: boolean | { readonly drainMs?: number }
   /**
    * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
    * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
@@ -196,9 +211,29 @@ export interface MountOptions<Env = unknown> {
    * Why this child is not analyzed, for a handler whose effects nifra cannot follow (a closure from
    * another package). Capability assurance lists a mount with a reason as a known gap; a mount
    * without one fails it, since its routes are invisible. A nifra `server()` belongs in `merge()`,
-   * where its routes are analyzed.
+   * where its routes are analyzed. Pass an {@link OpaqueMountDeclaration} to also state the routes
+   * the child serves.
    */
-  readonly opaque?: string
+  readonly opaque?: string | OpaqueMountDeclaration
+}
+
+/**
+ * An opaque mount's reason plus the routes it serves. Assurance lists those routes as declared, not
+ * analyzed: their capabilities are the mount's word, checked against the policy but never proven.
+ */
+export interface OpaqueMountDeclaration {
+  /** Why the child is not analyzed. A blank reason leaves the mount undeclared. */
+  readonly reason: string
+  readonly routes?: readonly DeclaredMountRoute[]
+}
+
+/** One route an opaque mount serves, as the app states it. */
+export interface DeclaredMountRoute {
+  readonly method: string
+  /** The request path, from the app root, under the mount's prefix (`/api/auth/sign-in`). */
+  readonly path: string
+  /** Capability ids the route exercises. */
+  readonly capabilities?: readonly string[]
 }
 
 /** Options for a legacy fetch-handler mount. */
@@ -210,7 +245,7 @@ export interface MountFetchOptions {
   /** For safe replayable methods only, try the next matching legacy mount when it returns 404. */
   readonly fallbackOn?: 404
   /** Why this handler is not analyzed - see {@link MountOptions.opaque}. */
-  readonly opaque?: string
+  readonly opaque?: string | OpaqueMountDeclaration
 }
 
 /** A callback awaited after the Bun server has drained and stopped. */