@nifrajs/core 2.14.1 → 3.1.0

package/src/edge-kit.ts

@@ -0,0 +1,27 @@
+/**
+ * Edge kit - the moat-neutral free functions a compact fetch-handler server needs to enforce the
+ * SAME request trust boundary the full `Server` does, without pulling in the full builder.
+ *
+ * A minimal edge entrypoint (`@nifrajs/edge`) is not allowed to re-derive the body lane: the assembly
+ * order of the content-type dispatch, the bounded read, the Content-Length pre-reject, and the
+ * prototype-poisoning guard is a security contract, and a second copy of it would drift. This subpath
+ * exposes the one lane the fused body runner already calls, so a compact server reuses it verbatim:
+ *
+ *   - {@link readBodyFramed}   read + cap + proto-guard + content-type framing (JSON / urlencoded / 415)
+ *   - {@link toResponse}       render a {@link ResponseResult} (e.g. a 413 / 415 rejection) to a `Response`
+ *   - {@link plainError}       the structured rejection envelope the lane returns
+ *   - {@link queryObjectOf} / {@link searchOf}   query parse without a full WHATWG URL construction
+ *
+ * Everything here carries only structure - bytes, guards, and envelopes - never routing, lifecycle,
+ * or app state. It is the interface, not the framework.
+ */
+
+export { plainError } from "./server/http.ts"
+export type { ProtoPoisoning } from "./server/proto-guard.ts"
+export { type QueryValue, queryObjectOf, searchOf } from "./server/query.ts"
+export { readBodyFramed } from "./server/request-context.ts"
+export { toResponse } from "./server/respond.ts"
+export type { ResponseResult } from "./server/runtime-core.ts"
+export { EMPTY_RESPONSE_CONTROLS } from "./server/runtime-core.ts"
+export type { CtxSet, MaybePromise, RequestSource } from "./server/server.ts"
+export { plainValidationError } from "./server/server.ts"

package/src/errors.ts

@@ -26,6 +26,7 @@ export type RouteConfigErrorCode =
   | "INVALID_METHOD"
   | "INVALID_ASSURANCE"
   | "INVALID_IDEMPOTENCY"
+  | "INVALID_WS_SEND_VALIDATION"
   | "INVALID_BODY_LIMIT"
 
 /**

package/src/index.ts

@@ -10,7 +10,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.14.1" as const
+export const VERSION = "3.1.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/route-execution.ts

@@ -19,6 +19,7 @@
 import type { RequestBudget } from "../budget.ts"
 import type { RequestLedger } from "../ledger.ts"
 import type { StandardSchemaV1 } from "../schema/standard.ts"
+import { UNLIMITED_BODY_BYTES } from "../server/body.ts"
 import type { Platform, RouteSchema } from "../server/context.ts"
 import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
@@ -26,7 +27,7 @@ import type { ProtoPoisoning } from "../server/proto-guard.ts"
 import type { Registry } from "../server/registry.ts"
 import { RequestContext } from "../server/request-context.ts"
 import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
-import type { HandlerResult } from "../server/runtime-core.ts"
+import type { HandlerResult, ResponseResult } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
 
 export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
@@ -49,7 +50,7 @@ export type RouteExecutionRunner = <T, R extends Registry, Ctx>(
   platform: Platform | undefined,
   nativeContext: boolean,
   finalize: (result: unknown, set: CtxSet) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>
 
 export type ContextRouteRunner = <T, R extends Registry, Ctx>(
@@ -58,7 +59,7 @@ export type ContextRouteRunner = <T, R extends Registry, Ctx>(
   source: RequestSource,
   ctx: RawContext,
   finalize: (result: unknown, set: CtxSet) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>
 
 /** The kernel's private execution surface, mirrored structurally. The runner methods are private on
@@ -76,66 +77,66 @@ interface RouteExecutionRuntime {
     budget: RequestBudget,
     platform: Platform | undefined,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runBare<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runBodyOnly<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runQueryOnly<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runLifecycleHooks<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runLifecycleQuery<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runLifecycleBody<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runLifecycleBodyQuery<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runLifecycle<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runWithAround<T>(
     entry: RouteEntry,
     ctx: RawContext,
     run: () => MaybePromise<T>,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   readonly maxBodyBytes: number
   readonly protoPoisoning: ProtoPoisoning
@@ -295,7 +296,7 @@ export function compileRouteExecutionPlan(options: {
     wrapResponse,
   ) => {
     const server = runtime as unknown as RouteExecutionRuntime
-    const maxBodyBytes = entry.bodyLimit ?? server.maxBodyBytes
+    const maxBodyBytes = entry.bodyLimit ?? UNLIMITED_BODY_BYTES
     const ctx = nativeContext
       ? RequestContext.native(source, params, search, maxBodyBytes, platform, server.protoPoisoning)
       : new RequestContext(
@@ -346,7 +347,13 @@ export interface RouteExecutionPlan {
 export interface RouteEntry {
   readonly handler: InternalHandler
   readonly schema: RouteSchema | undefined
-  /** Effective transport body cap; `undefined` is an explicit streaming/upload exemption. */
+  /**
+   * Effective transport body cap, already resolved at registration: the route's own
+   * `schema.bodyLimit` when it declared one, the server's `maxBodyBytes` otherwise. `undefined` is
+   * an explicit streaming/upload exemption (`bodyLimit: "unlimited"`) and means NO cap - readers
+   * must fall back to {@link UNLIMITED_BODY_BYTES}, never to the server default, which would be a
+   * tighter bound than the route asked for.
+   */
   readonly bodyLimit: number | undefined
   /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
   readonly idempotent: ResolvedIdempotency | undefined
@@ -399,5 +406,5 @@ export type FusedBodyRunner = <T>(
   platform: Platform | undefined,
   nativeContext: boolean,
   finalize: (result: unknown, set: CtxSet, ctx: RawContext) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>

package/src/response-observer.ts

@@ -0,0 +1,64 @@
+import { INSTALL_RESPONSE_OBSERVER } from "./server/install.ts"
+import {
+  createResponseObserverRuntime,
+  type ResponseObserverRuntime,
+} from "./server/response-observer-runtime.ts"
+import type { AnyServer } from "./server/server.ts"
+
+export type {
+  ResponseBodyHook,
+  ResponseHeadersHook,
+  ResponseObserverMethods,
+  ResponseObserverRuntime,
+} from "./server/response-observer-runtime.ts"
+
+/** A server shape with the opt-in response observation methods installed. */
+export type ResponseObserverServer<S extends AnyServer> = S &
+  import("./server/response-observer-runtime.ts").ResponseObserverMethods
+
+/** A plugin that enables response header, body, and raw-response observation methods. */
+export type ResponseObserverPlugin = (<S extends AnyServer>(
+  app: S,
+) => ResponseObserverServer<S>) & { readonly pluginName?: string }
+
+/**
+ * Enable the response observation methods on a server.
+ *
+ * The default server does not carry the header, body, or raw-response observation adapters. Apply
+ * this plugin before using those methods:
+ *
+ * ```ts
+ * import { responseObserver } from "@nifrajs/core/response-observer"
+ * const app = server().use(responseObserver()).onResponseHeaders((headers) => {
+ *   headers.set("cache-control", "no-store")
+ * })
+ * ```
+ */
+export function responseObserver(): ResponseObserverPlugin {
+  const apply = <S extends AnyServer>(app: S): ResponseObserverServer<S> => {
+    const install = (app as unknown as Record<symbol, unknown>)[INSTALL_RESPONSE_OBSERVER]
+    if (typeof install !== "function") {
+      throw new TypeError("[nifra] responseObserver() requires a compatible Server")
+    }
+    const methods = (install as (runtime: ResponseObserverRuntime) => unknown).call(
+      app,
+      createResponseObserverRuntime(),
+    )
+    if (methods === null || typeof methods !== "object") {
+      throw new TypeError("[nifra] responseObserver() failed to install its methods")
+    }
+    Object.assign(app, methods)
+    return app as ResponseObserverServer<S>
+  }
+  return Object.assign(apply, { pluginName: "nifra:response-observer" })
+}
+
+/** Attach the opt-in observer runtime to a middleware bundle that uses response observation. */
+export function withResponseObserver<T extends object>(middleware: T): T {
+  Object.defineProperty(middleware, INSTALL_RESPONSE_OBSERVER, {
+    value: createResponseObserverRuntime(),
+    enumerable: false,
+    configurable: false,
+  })
+  return middleware
+}

package/src/security/baseline.ts

@@ -0,0 +1,172 @@
+import type { AssurancePolicy, AssuranceRule } from "../assurance.ts"
+import { NIFRA_ASSURANCE_IDS } from "../internal/route-assurance.ts"
+
+/**
+ * How much a {@link securityBaseline} demands. Each level is a superset of the one before it, so
+ * raising the level only ever adds findings.
+ *
+ * - `"essential"` - the invariants that hold for ANY app and never false-positive on a reasonable
+ *   one: a body read must be bounded, an unlimited body may never claim to be bounded, an agent tool
+ *   ingress must be bounded, and an authenticated state change must prove CSRF. Every required piece
+ *   of evidence here is either published by the core from the route schema or only demanded when the
+ *   route already opted into the risk (CSRF is required only where authentication is present). Safe to
+ *   adopt on day one.
+ * - `"standard"` (default) - essential, plus: a route the app itself classified as `pii` or higher
+ *   must be authenticated, whether it reads or writes. High signal, low noise - it fires only on
+ *   routes the application already labelled sensitive.
+ * - `"strict"` - standard, plus the opinionated, higher-friction requirements: every route must carry
+ *   a response contract, every read must carry security headers, and every mutation must be rate
+ *   limited. These need middleware the app has to install, so they are opt-in rather than default.
+ */
+export type SecurityBaselineLevel = "essential" | "standard" | "strict"
+
+/** Tuning for {@link securityBaseline}. Every knob only ever tightens the policy. */
+export interface SecurityBaselineOptions {
+  /** How much the baseline demands. Default `"standard"`. See {@link SecurityBaselineLevel}. */
+  readonly level?: SecurityBaselineLevel
+  /**
+   * How to treat a route no rule matched. Default `"ignore"` so the baseline is purely additive - it
+   * asserts the invariants below and stays silent on everything else, which lets a project adopt it
+   * without first classifying its whole route table. Set `"error"` to make an unclassified route a
+   * finding, turning the baseline into a closed allow-list (recommended once the table is covered).
+   */
+  readonly unmatched?: "error" | "ignore"
+  /**
+   * Require that a matched route's evidence was installed by runtime enforcement (middleware/plugin
+   * or framework policy) rather than asserted inline on `schema.assurance`. Default `true`: an author
+   * label is not proof, and a security baseline that accepts labels is theater. Set `false` only to
+   * stage adoption before guards emit runtime evidence.
+   */
+  readonly requireRuntimeProvenance?: boolean
+}
+
+const MUTATING = ["POST", "PUT", "PATCH", "DELETE"] as const
+const READING = ["GET", "HEAD"] as const
+/** The classification threshold above which the baseline demands authentication. */
+const SENSITIVE = "pii" as const
+
+/**
+ * A first-match-wins security policy that turns the recurring audit finding classes into machine
+ * checked route invariants. Composed only from the public assurance engine, so it inherits its
+ * fail-closed evaluation, provenance checks, and selector validation - no bespoke evaluator.
+ *
+ * The rules are ordered most-specific-first because assurance evaluation is first-match-wins: each
+ * route is owned by exactly one rule, so that rule carries the FULL requirement bundle for its class
+ * (a body-carrying mutation proves bounded-body AND CSRF in one rule, not two). Raising the `level`
+ * widens those bundles; it never reorders them.
+ *
+ * Coverage by level (see {@link SecurityBaselineLevel} for the rationale):
+ *
+ * | invariant | essential | standard | strict |
+ * | --- | :-: | :-: | :-: |
+ * | unlimited body can never be "bounded" (F-001) | ✓ | ✓ | ✓ |
+ * | every body read is bounded | ✓ | ✓ | ✓ |
+ * | agent tool ingress is bounded | ✓ | ✓ | ✓ |
+ * | authenticated mutation proves CSRF | ✓ | ✓ | ✓ |
+ * | pii+ route is authenticated | | ✓ | ✓ |
+ * | every route carries a response contract | | | ✓ |
+ * | every read carries security headers | | | ✓ |
+ * | every mutation is rate limited | | | ✓ |
+ *
+ * The baseline deliberately does not select on `access`/`zone` capabilities: those selectors require
+ * capability definitions and would make the preset refuse an app that declares none. Extend the
+ * returned policy's `rules` for capability- or path-specific requirements; put more specific rules
+ * before these so they own their routes first.
+ */
+export function securityBaseline(options: SecurityBaselineOptions = {}): AssurancePolicy {
+  const level = options.level ?? "standard"
+  const strict = level === "strict"
+  const authSensitive = level !== "essential"
+  const provenance = options.requireRuntimeProvenance === false ? "any" : "runtime"
+
+  const A = NIFRA_ASSURANCE_IDS
+  // Evidence the app must install middleware for, gated to the levels that assume that cost.
+  const contract = strict ? [A.RESPONSE_CONTRACT] : []
+  const headers = strict ? [A.SECURITY_HEADERS] : []
+  const rateLimit = strict ? [A.RATE_LIMITED] : []
+  const authed = authSensitive ? [A.AUTHENTICATED] : []
+
+  const rules: AssuranceRule[] = [
+    // The static twin of the config-time rejection: a schema route that opted into `bodyLimit:
+    // "unlimited"` can never carry `nifra.body-bounded` (the core withholds it), so requiring it is a
+    // standing ban. Owns the unlimited case before any body rule below can soften it. (F-001.)
+    {
+      name: "banned-unlimited-body",
+      match: { hasBody: true, bodyLimit: "unlimited" },
+      require: [A.BODY_BOUNDED],
+    },
+    // Agent tool ingress buffers attacker-influenced arguments; it must be bounded. Not CSRF-guarded:
+    // tool calls are token-authenticated machine traffic, not ambient-cookie browser posts.
+    {
+      name: "tool-ingress-bounded",
+      match: { tools: true, hasBody: true },
+      require: [A.BODY_BOUNDED, ...contract],
+      requireProvenance: provenance,
+    },
+  ]
+
+  // Sensitive mutations, split by body shape so bounded-body is required only where a body exists.
+  // Emitted only when a level adds a requirement beyond the generic mutation rules, otherwise they
+  // would be redundant duplicates that only slow evaluation.
+  if (authSensitive || strict) {
+    rules.push(
+      {
+        name: "sensitive-mutation-body",
+        match: { methods: [...MUTATING], hasBody: true, classificationAtLeast: SENSITIVE },
+        require: [A.BODY_BOUNDED, ...authed, ...contract, ...rateLimit],
+        requireCsrfWithAuthenticated: true,
+        requireProvenance: provenance,
+      },
+      {
+        name: "sensitive-mutation",
+        match: { methods: [...MUTATING], classificationAtLeast: SENSITIVE },
+        require: [...authed, ...contract, ...rateLimit],
+        requireCsrfWithAuthenticated: true,
+        requireProvenance: provenance,
+      },
+    )
+  }
+
+  rules.push(
+    {
+      name: "mutation-body",
+      match: { methods: [...MUTATING], hasBody: true },
+      require: [A.BODY_BOUNDED, ...contract, ...rateLimit],
+      requireCsrfWithAuthenticated: true,
+      requireProvenance: provenance,
+    },
+    {
+      name: "mutation",
+      match: { methods: [...MUTATING] },
+      require: [...contract, ...rateLimit],
+      requireCsrfWithAuthenticated: true,
+      requireProvenance: provenance,
+    },
+  )
+
+  if (authSensitive || strict) {
+    rules.push({
+      name: "sensitive-read",
+      match: { methods: [...READING], classificationAtLeast: SENSITIVE },
+      require: [...authed, ...contract, ...headers],
+      requireProvenance: provenance,
+    })
+  }
+
+  // The catch-all read rule. At essential/standard its requirement bundle is empty, so it is a pure
+  // classification that simply marks reads as covered - which matters only under `unmatched: "error"`,
+  // where an unowned route would otherwise fail. At strict it demands the response + header contract.
+  rules.push({
+    name: "read",
+    match: { methods: [...READING] },
+    require: [...contract, ...headers],
+    ...(strict ? { requireProvenance: provenance } : {}),
+  })
+
+  return {
+    rules,
+    unmatched: options.unmatched ?? "ignore",
+    // A wrong import reflecting zero routes must fail, not silently pass a security gate.
+    allowEmpty: false,
+  }
+}

package/src/server/bare-error-lane.ts

@@ -0,0 +1,76 @@
+/**
+ * The bare lane's ERROR rendering, as free functions the kernel delegates to.
+ *
+ * ## Why this is a lane module and not methods on `Server`
+ *
+ * These are the cold half of the bare request lane: what happens when a handler (or a `derive`)
+ * throws, rather than returns. The success half stays on the class - it reads request-lifecycle
+ * state and is the async-frame-skip hot path - but the error half needs none of that class state:
+ * `renderBareError` is pure control-flow routing, and `emitRequestErrorLog` needs only the logger
+ * and the detail policy, both of which are config fixed at construction. Passing those two in keeps
+ * this file free of any runtime dependency back on `server.ts`, so there is no import cycle: the
+ * `RawContext`/`CtxSet` imports are type-only and erased (the same shape `edge.ts` already relies on).
+ *
+ * A single source of truth for the thrown-value contract matters because it is a security surface:
+ * an unhandled throw must render as a 500 with no caller-controlled body, and the amount of the
+ * error's own text that reaches the log sink is the app's `errorLogDetail` call, not an accident of
+ * which lane caught it. Both the generic bare lane and the fused body runner route here, so that
+ * decision lives in exactly one place.
+ */
+import { pathnameOf, plainError } from "./http.ts"
+import type { Logger } from "./logger.ts"
+import { isResponseResult, type ResponseResult } from "./runtime-core.ts"
+import type { CtxSet, RawContext } from "./server.ts"
+
+/** How much of a thrown error's own text reaches the log sink. Mirrors `Server`'s option. */
+export type ErrorLogDetail = "full" | "message" | "none"
+
+/**
+ * Render a value thrown on the bare lane. Three shapes, in the order the lane means them:
+ *   - a bare `Response` is the app answering directly - passed through untouched;
+ *   - a thrown `status(...)` is control flow, still plain data: rendered through the same `finalize`
+ *     a RETURNED one takes, with the request's `c.set`, so it costs what the return costs;
+ *   - anything else is a real fault: logged once, then a bodyless 500 (never the caller's error text).
+ *
+ * `responseSet` and `logError` are injected rather than imported so this file keeps no runtime edge
+ * back to `server.ts` (`responseSet` reaches into the context's set symbol; `logError` closes over the
+ * server's logger). Both run only on the throw path, so the closures cost nothing on the hot lane.
+ */
+export function renderBareError<T>(
+  err: unknown,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet, ctx: RawContext) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  responseSet: (ctx: RawContext) => CtxSet,
+  logError: (err: unknown, ctx: RawContext) => void,
+): T {
+  if (err instanceof Response) return wrapResponse(err)
+  if (isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
+  logError(err, ctx)
+  return wrapResponse(plainError(500, "internal_error"))
+}
+
+/**
+ * Write an unhandled request error to the log. An error's own text can quote the input that produced
+ * it, so how much of it reaches the sink is the app's call (`detail`). The default keeps it: a 500
+ * with no message and no stack is an incident nobody can diagnose, and the framework already ships
+ * the narrower instrument for the leak - a redacting logger with `valuePatterns`. `"none"` is there
+ * for an untrusted sink.
+ */
+export function emitRequestErrorLog(
+  logger: Logger,
+  detail: ErrorLogDetail,
+  err: unknown,
+  ctx: RawContext,
+): void {
+  logger.error("unhandled request error", {
+    method: ctx.req.method,
+    path: pathnameOf(ctx.req.url),
+    name: err instanceof Error ? err.name : "Error",
+    // `detail`, not `message`: the logger uses `message` for its own first argument, so a field of
+    // that name is silently overwritten and the thrown error's own text never reaches the sink. It
+    // survived only incidentally inside `stack`, and was lost outright for a non-Error throw.
+    ...(detail === "none" ? {} : { detail: err instanceof Error ? err.message : String(err) }),
+    ...(detail === "full" && err instanceof Error ? { stack: err.stack } : {}),
+  })
+}

package/src/server/body.ts

@@ -37,6 +37,14 @@ export function rawBodySourceOf<T extends BodySource>(req: T): T {
   return ((req as { [RAW_BODY_READERS]?: T })[RAW_BODY_READERS] as T | undefined) ?? req
 }
 
+/**
+ * The byte cap a route that declared `bodyLimit: "unlimited"` reads under. It is a real number, not
+ * `Infinity` or a skipped check: every bounded reader keeps its single `> maxBytes` enforcement
+ * point (and its `assertByteLimit` guard) rather than growing an uncapped branch that a future
+ * caller could reach by accident. No HTTP body reaches 2^53-1 bytes, so this is unlimited in fact.
+ */
+export const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER
+
 /** Security/resource limits must be finite byte counts. Invalid values otherwise make `> maxBytes`
  * comparisons fail open (notably for `NaN`) and can re-enable unbounded buffering. */
 export function assertByteLimit(value: number, name = "maxBytes"): void {

package/src/server/bridge-markers.ts

@@ -0,0 +1,24 @@
+/**
+ * Wire marker keys shared between @nifrajs/core and the @nifrajs/node adapter.
+ *
+ * Each entry names a symbol looked up with `Symbol.for(...)`, so the two packages agree ONLY by the
+ * string. A rename on one side and not the other is a silent protocol break - no type error, just a
+ * symbol that never matches and a body that stops taking the direct-write lane. This module is the
+ * single source: core defines its own symbols from these literals, and `scripts/gen-node-outcome.ts`
+ * copies the map verbatim into the adapter's generated contract, so @nifrajs/node reads the identical
+ * strings without a runtime dependency on core (the same deployment shape the generated outcome type
+ * preserves).
+ *
+ * Keep this module import-free: every core file that owns one of these symbols imports it, so a cycle
+ * here would reach most of the response path.
+ */
+export const NODE_BRIDGE_MARKER_KEYS = {
+  /** A `Response` carrying its already-serialized bytes, so the Node writer emits them without a drain. */
+  responseBody: "nifra.response.body",
+  /** A plain-data response-result carrier the node lane renders without building a `Response`. */
+  responseResult: "nifra.response.result",
+  /** Proof that a header record's names are already the lowercase wire spelling. */
+  lowercaseHeaderKeys: "nifra.headers.lowercase",
+  /** A mounted handler's node-direct resolver entry point. */
+  resolveNodeMount: "@nifrajs/core/resolve-node-mount",
+} as const

package/src/server/context.ts

@@ -64,7 +64,12 @@ export type Params<Path extends string> = Prettify<RawParams<Path>>
 export interface RouteSchema {
   /** Transport body cap for this route. Defaults to the server's maxBodyBytes. Use a finite
    * smaller/larger limit for a specific endpoint. The 'unlimited' value is an explicit
-   * streaming/upload exemption and requires a non-empty bodyLimitReason for auditability. */
+   * streaming/upload exemption and requires a non-empty bodyLimitReason for auditability.
+   *
+   * 'unlimited' is legal only for schema-less streaming/upload routes. It is rejected with `body` or
+   * `idempotency`, because those lanes buffer the body before user code can apply a protocol-specific
+   * bound. Read an unlimited route from `c.req.body` as a stream and bound it by the protocol it speaks;
+   * `nifra.body-bounded` is deliberately NOT published for an unlimited route. */
   readonly bodyLimit?: number | "unlimited"
   /** Required explanation when bodyLimit is 'unlimited' (for example, a streaming upload is
    * bounded by an upstream object-store protocol). */

package/src/server/header-case.ts

@@ -1,3 +1,5 @@
+import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
+
 /**
  * The all-lowercase header-name proof: one answer, computed once per request, read by everyone who
  * would otherwise re-derive it.
@@ -23,7 +25,7 @@
  * 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")
+const LOWERCASE_HEADER_KEYS = Symbol.for(NODE_BRIDGE_MARKER_KEYS.lowercaseHeaderKeys)
 
 /** True when the name contains an ASCII `A`-`Z`, i.e. is not already the wire spelling. */
 export function hasUpperAscii(name: string): boolean {

package/src/server/http.ts

@@ -1,8 +1,37 @@
 /**
- * Dependency-free HTTP helpers shared by the kernel and the opt-in request lanes (idempotency,
- * effect-ledger). Kept in a leaf module so a lane can reuse them without importing the server, and so
- * the server can reuse them without pulling a lane's feature code into the base bundle.
+ * HTTP helpers shared by the kernel and the opt-in request lanes (idempotency, effect-ledger). Kept
+ * in a leaf module (runtime-core aside, itself a leaf) so a lane can reuse them without importing the
+ * server, and so the server can reuse them without pulling a lane's feature code into the base bundle.
  */
+import { type ResponseResult, status as statusResult } from "./runtime-core.ts"
+
+/**
+ * Is `value` a destination that stays on this origin?
+ *
+ * True only for an absolute path: one leading `/`, never `//` (protocol-relative → another origin),
+ * and free of any character a URL parser turns into an origin escape. A leading `/` alone is not
+ * enough: under a special scheme `\` parses as `/`, and tab/CR/LF are STRIPPED before parsing, so
+ * `/\evil.example` and `/<TAB>/evil.example` both resolve to the external host `evil.example` while
+ * passing a `//` test. Rejecting CR/LF here also keeps a validated destination out of the
+ * response-splitting sink it usually flows into.
+ *
+ * One implementation, because every caller is the same open-redirect gate: `redirect()` in
+ * `@nifrajs/web`, the `redirectTo` of the `@nifrajs/auth` and `@nifrajs/better-auth` guards. Three
+ * copies of a security predicate is three chances for one of them to be hardened alone.
+ *
+ * It answers about a PATH, not a URL: an absolute `https://this.host/x` is false even for the
+ * current origin, because the whole point is that the value never got to name a host.
+ */
+export function isSameOriginPath(value: string): boolean {
+  if (!value.startsWith("/") || value.startsWith("//")) return false
+  // Scanned by character code rather than matched by regex: no control characters have to be written
+  // into a pattern, and the check is a single pass over a short string.
+  for (let i = 1; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code === 0x5c /* \ */ || code <= 0x1f || code === 0x7f) return false
+  }
+  return true
+}
 
 /** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
 export function jsonError(
@@ -16,6 +45,27 @@ export function jsonError(
   )
 }
 
+/**
+ * The same envelope as {@link jsonError}, as plain data rather than a built `Response`.
+ *
+ * This is what the framework's own renders - 404, 405, 422, the body caps, the timeouts, 500 - answer
+ * with wherever the value flows into a lane's response wrapper, so an error costs what a handler's
+ * plain return costs. Building the `Response` was measured as the dominant cost of answering early
+ * (see `PlainRender`), and on the Node lane an error `Response` is worse still: it is untagged, so
+ * the adapter cannot recognize its body and drains it through a Web stream, which is also why an
+ * error answered chunked while an ordinary return carries a `content-length`.
+ *
+ * `jsonError` stays for the callers that genuinely need a `Response` object (mount bridges, the
+ * lanes' own typed returns).
+ */
+export function plainError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): ResponseResult {
+  return statusResult(status, { ok: false, error }, headers !== undefined ? { headers } : undefined)
+}
+
 export interface UrlParts {
   readonly pathname: string
   readonly search: string