@nifrajs/core 2.11.0 → 2.12.1

package/src/server/request-context.ts

@@ -5,10 +5,19 @@
  * sits below the server module in the graph.
  */
 import type { RequestBudget } from "../budget.ts"
-import { drainCapped, parseContentLength, readBoundedBytes } from "./body.ts"
+import {
+  applyTransportCap,
+  drainCapped,
+  hasTrustedBodyFraming,
+  parseContentLength,
+  RAW_BODY_READERS,
+  readBoundedBytes,
+} from "./body.ts"
 import type { Platform } from "./context.ts"
-import { type CookieOptions, parseCookies, serializeCookie } from "./cookies.ts"
+import { type CookieOptions, cookieNamePrefix, parseCookies, serializeCookie } from "./cookies.ts"
+import { headerObjectOf } from "./headers.ts"
 import { jsonError } from "./http.ts"
+import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
 import {
   CONTEXT_SEARCH,
@@ -17,6 +26,8 @@ import {
   getNeverAbortSignal,
   getUnboundedRequestBudget,
   headerOf,
+  PRE_DECODED_BODY,
+  type PreDecodedBody,
   requestOf,
   TEXT_DECODER,
 } from "./runtime-core.ts"
@@ -58,9 +69,16 @@ class LazyResponseControls implements CtxSet {
 
   deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void {
     // Expire immediately; default Path=/, and match the original path/domain or the browser keeps it.
+    // A prefixed name gets Secure on the deletion write too - the browser holds the deletion
+    // Set-Cookie to the same prefix contract as the original, and rejects it without.
     this._cookies ??= []
+    const base = { path: "/", ...options, maxAge: 0, expires: EPOCH }
     this._cookies.push(
-      serializeCookie(name, "", { path: "/", ...options, maxAge: 0, expires: EPOCH }),
+      serializeCookie(
+        name,
+        "",
+        cookieNamePrefix(name) !== undefined ? { ...base, secure: true } : base,
+      ),
     )
   }
 }
@@ -85,11 +103,18 @@ export class RequestContext implements RawContext {
   private declare setValue: CtxSet | undefined
   private declare queryValue: unknown
   private declare queryReady: boolean
+  private declare headersValue: Record<string, string> | undefined
   private declare cookiesValue: Readonly<Record<string, string>> | undefined
   private declare readonly source: RequestSource
   private declare readonly maxBodyBytes: number
+  private declare readonly protoPoisoning: ProtoPoisoning
 
-  constructor(source: RequestSource, params: Record<string, string>, maxBodyBytes: number)
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    maxBodyBytes: number,
+    protoPoisoning?: ProtoPoisoning,
+  )
   constructor(
     source: RequestSource,
     params: Record<string, string>,
@@ -98,27 +123,32 @@ export class RequestContext implements RawContext {
     budget: RequestBudget,
     platform: Platform | undefined,
     maxBodyBytes: number,
+    protoPoisoning?: ProtoPoisoning,
   )
   constructor(
     source: RequestSource,
     params: Record<string, string>,
     searchOrMaxBodyBytes: string | number | undefined,
-    signal?: AbortSignal,
+    signalOrProtoPoisoning?: AbortSignal | ProtoPoisoning,
     budget?: RequestBudget,
     platform?: Platform,
     maxBodyBytes?: number,
+    protoPoisoning?: ProtoPoisoning,
   ) {
     this.source = source
     this.params = params
     if (typeof searchOrMaxBodyBytes === "number") {
       this.maxBodyBytes = searchOrMaxBodyBytes
+      this.protoPoisoning =
+        typeof signalOrProtoPoisoning === "string" ? signalOrProtoPoisoning : "reject"
       return
     }
     if (searchOrMaxBodyBytes !== undefined) this.searchValue = searchOrMaxBodyBytes
-    this.signalValue = signal
+    this.signalValue = signalOrProtoPoisoning as AbortSignal | undefined
     this.budgetValue = budget
     if (platform !== undefined) this.platformValue = platform
     this.maxBodyBytes = maxBodyBytes as number
+    this.protoPoisoning = protoPoisoning ?? "reject"
   }
 
   /**
@@ -133,8 +163,9 @@ export class RequestContext implements RawContext {
     search: string | undefined,
     maxBodyBytes: number,
     platform?: Platform,
+    protoPoisoning?: ProtoPoisoning,
   ): RequestContext {
-    const context = new RequestContext(source, params, maxBodyBytes)
+    const context = new RequestContext(source, params, maxBodyBytes, protoPoisoning)
     if (search !== undefined) context.searchValue = search
     if (platform !== undefined) context.platformValue = platform
     return context
@@ -177,17 +208,32 @@ export class RequestContext implements RawContext {
   }
 
   get req(): Request {
-    return requestOf(this.source)
+    // A dispatcher-marked source gets its route's transport byte cap applied here - at the moment
+    // user code reaches for the request - so routes that never direct-read the body pay nothing.
+    const request = requestOf(this.source)
+    applyTransportCap(this.source, request)
+    return request
   }
 
   get request(): Request {
-    return requestOf(this.source)
+    const request = requestOf(this.source)
+    applyTransportCap(this.source, request)
+    return request
   }
 
   header(name: string): string | null {
     return headerOf(this.source, name)
   }
 
+  get headers(): Record<string, string> {
+    this.headersValue ??= headerObjectOf(this.source.headers)
+    return this.headersValue
+  }
+
+  set headers(value: Record<string, string>) {
+    this.headersValue = value
+  }
+
   json(body: unknown, init?: ResponseInit | number): Response {
     return Response.json(body, statusInit(init))
   }
@@ -222,7 +268,12 @@ export class RequestContext implements RawContext {
   }
 
   boundedJson<T = unknown>(maxBytes?: number): Promise<T> {
-    return readBoundedJsonBodyOrThrow<T>(this.source, this.maxBodyBytes, maxBytes)
+    return readBoundedJsonBodyOrThrow<T>(
+      this.source,
+      this.maxBodyBytes,
+      this.protoPoisoning,
+      maxBytes,
+    )
   }
 }
 
@@ -241,27 +292,84 @@ async function readBoundedBodyOrThrow(
     : jsonError(400, "invalid_content_length")
 }
 
-/** Backs `c.boundedJson`: `readBoundedBodyOrThrow` + `JSON.parse`, throwing a flat 400 on bad JSON. */
+/** Backs `c.boundedJson`: `readBoundedJsonSource`, throwing its flat 400/413 on failure. */
 async function readBoundedJsonBodyOrThrow<T>(
   req: RequestSource,
   maxBodyBytes: number,
+  protoPoisoning: ProtoPoisoning,
   maxBytes?: number,
 ): Promise<T> {
-  const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes)
+  const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes, protoPoisoning)
   if (parsed instanceof Response) throw parsed
   return parsed as T
 }
 
 /**
- * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`.
- * Non-chunked, framed requests with an in-cap `Content-Length` use the runtime-native `req.json()`;
+ * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`, then
+ * parse it through the prototype-poisoning guard (`protoPoisoning`, default `"reject"` - a
+ * poisoned payload answers the same flat 400 as malformed JSON). Non-chunked, framed requests
+ * with an in-cap `Content-Length` take the runtime's fused `json()` and walk the parsed value;
  * chunked or length-less requests fall back to the streaming byte-cap guard.
  */
-export async function readBoundedJsonSource(
+/**
+ * Deliberately **not** `async`: the framed lane is the hot path for every JSON POST, and an async
+ * wrapper costs a coroutine frame, a wrapper promise, and an extra microtask hop on top of the one
+ * the body read already pays (~90ns/request on Node, measured). The lane returns the body read's
+ * own promise chain instead, and only the streaming fallback - which is already doing IO in a loop
+ * - runs as an async function. Callers that `await` the result are unaffected.
+ */
+type JsonResultContinuation<T> = (result: unknown | Response) => T | Promise<T>
+type JsonErrorContinuation<T> = (error: unknown) => T | Promise<T>
+type FramedJsonSource = RequestSource & {
+  readonly bytes?: () => Promise<Uint8Array>
+  readonly jsonWithByteLength?: () => Promise<{
+    readonly value: unknown
+    readonly byteLength: number
+  }>
+}
+
+export function readBoundedJsonSource(
   req: RequestSource,
   maxBytes: number,
-): Promise<unknown | Response> {
-  const declared = headerOf(req, "content-length")
+  protoPoisoning?: ProtoPoisoning,
+): Promise<unknown | Response>
+export function readBoundedJsonSource<T>(
+  req: RequestSource,
+  maxBytes: number,
+  protoPoisoning: ProtoPoisoning,
+  onResult: JsonResultContinuation<T>,
+  onError: JsonErrorContinuation<T>,
+): Promise<T>
+export function readBoundedJsonSource<T>(
+  req: RequestSource,
+  maxBytes: number,
+  protoPoisoning: ProtoPoisoning = "reject",
+  onResult?: JsonResultContinuation<T>,
+  onError?: JsonErrorContinuation<T>,
+): Promise<unknown | Response | T> {
+  // A pre-parsing hook (the transport-codec lane) may have decoded the body already - its stash
+  // is taken verbatim: the stasher enforced its own byte cap and poisoning policy on text this
+  // lane never sees. One symbol read; a miss on ordinary requests costs a cache-line, not a parse.
+  const preDecoded = (req as { [PRE_DECODED_BODY]?: PreDecodedBody })[PRE_DECODED_BODY]
+  if (preDecoded !== undefined) {
+    return onResult === undefined
+      ? Promise.resolve(preDecoded.value)
+      : Promise.resolve(preDecoded.value).then(onResult)
+  }
+  // Read through the pre-cap readers when the request is transport-capped: this lane enforces its
+  // own `maxBytes` (which may exceed the route's transport cap), so the shadowed user-facing
+  // readers must not narrow it.
+  // Keep the source's header dispatch local: the normal Node source exposes a direct `header`
+  // lookup, while a Web Request only exposes `Headers.get`. Rechecking that optional method through
+  // `headerOf` twice per body is measurable on the framed lane. The raw-reader shadow is still
+  // bypassed for reads, but header authority remains the original source (same semantics as before).
+  const raw = ((req as { [RAW_BODY_READERS]?: RequestSource })[RAW_BODY_READERS] ??
+    req) as FramedJsonSource
+  const sourceHeader = req.header
+  const declared =
+    sourceHeader === undefined
+      ? req.headers.get("content-length")
+      : sourceHeader.call(req, "content-length")
   if (declared !== null) {
     // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
     // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
@@ -270,23 +378,131 @@ export async function readBoundedJsonSource(
     // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
     // hardens hand-built Requests (tests, the in-process client) and crafted input.
     const length = parseContentLength(declared)
-    if (length === undefined) return jsonError(400, "invalid_content_length")
-    if (length > maxBytes) return jsonError(413, "payload_too_large")
-    const chunked = headerOf(req, "transfer-encoding") !== null
+    if (length === undefined)
+      return onResult === undefined
+        ? Promise.resolve(jsonError(400, "invalid_content_length"))
+        : Promise.resolve(jsonError(400, "invalid_content_length")).then(onResult)
+    if (length > maxBytes)
+      return onResult === undefined
+        ? Promise.resolve(jsonError(413, "payload_too_large"))
+        : Promise.resolve(jsonError(413, "payload_too_large")).then(onResult)
+    const chunked =
+      (sourceHeader === undefined
+        ? req.headers.get("transfer-encoding")
+        : sourceHeader.call(req, "transfer-encoding")) !== null
     if (!chunked) {
-      try {
-        return await req.json()
-      } catch {
-        return jsonError(400, "invalid_json")
+      // Bun's compiled native route table receives a Request whose bytes were already delimited by
+      // Bun's HTTP parser. Keep the exact-byte path for every portable/adapted source, but preserve
+      // Bun's fused decode+parse on this trusted ingress; the declared length is the transport frame
+      // there, not an attacker-controlled hint. The parsed-value poisoning walk still applies.
+      if (hasTrustedBodyFraming(req)) {
+        return raw.json().then(
+          (parsed) => {
+            let guarded: unknown
+            try {
+              guarded = guardParsedValue(parsed, protoPoisoning)
+            } catch {
+              return onResult === undefined
+                ? jsonError(400, "invalid_json")
+                : onResult(jsonError(400, "invalid_json"))
+            }
+            return onResult === undefined ? guarded : onResult(guarded)
+          },
+          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+        )
       }
+      const jsonWithByteLength = raw.jsonWithByteLength
+      if (jsonWithByteLength !== undefined) {
+        return jsonWithByteLength.call(raw).then(
+          ({ value, byteLength }) => {
+            if (byteLength > length || byteLength > maxBytes) {
+              return onResult === undefined
+                ? jsonError(413, "payload_too_large")
+                : onResult(jsonError(413, "payload_too_large"))
+            }
+            let guarded: unknown
+            try {
+              guarded = guardParsedValue(value, protoPoisoning)
+            } catch {
+              return onResult === undefined
+                ? jsonError(400, "invalid_json")
+                : onResult(jsonError(400, "invalid_json"))
+            }
+            return onResult === undefined ? guarded : onResult(guarded)
+          },
+          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+        )
+      }
+      const bytesReader = raw.bytes
+      if (bytesReader !== undefined) {
+        return bytesReader.call(raw).then(
+          (bytes) => {
+            if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
+              return onResult === undefined
+                ? jsonError(413, "payload_too_large")
+                : onResult(jsonError(413, "payload_too_large"))
+            }
+            try {
+              const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
+              return onResult === undefined ? parsed : onResult(parsed)
+            } catch {
+              return onResult === undefined
+                ? jsonError(400, "invalid_json")
+                : onResult(jsonError(400, "invalid_json"))
+            }
+          },
+          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+        )
+      }
+      // Read the actual framed bytes before parsing. A declared length is only a hint on Web
+      // Requests and adapter-shaped sources: a caller can construct a Request (or an adapter can
+      // decode/expand a body) whose header claims fewer bytes than the delivered payload. Calling
+      // native `json()` here would accept that understatement and bypass the cap. The byte lane
+      // already owns this post-read check; keeping the JSON lane on the same raw-byte read makes the
+      // trust boundary consistent. `Uint8Array(buffer)` is a view, not a copy.
+      return raw.arrayBuffer().then(
+        (buffer) => {
+          const bytes = new Uint8Array(buffer)
+          if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
+            return onResult === undefined
+              ? jsonError(413, "payload_too_large")
+              : onResult(jsonError(413, "payload_too_large"))
+          }
+          let parsed: unknown
+          try {
+            parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
+          } catch {
+            return onResult === undefined
+              ? jsonError(400, "invalid_json")
+              : onResult(jsonError(400, "invalid_json"))
+          }
+          return onResult === undefined ? parsed : onResult(parsed)
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
     }
   }
-  const body = req.body
+  const streamed = readStreamedJsonSource(raw, maxBytes, protoPoisoning)
+  return onResult === undefined ? streamed : streamed.then(onResult, onError)
+}
+
+/** The shared rejection handler for a body read that never completed (client abort, socket error,
+ * malformed framing): the same flat 400 a syntactically invalid body gets. Hoisted so the framed
+ * lane allocates no per-request closure for it. */
+const INVALID_JSON = (): Response => jsonError(400, "invalid_json")
+
+/** The chunked / length-less fallback: drain under the streaming byte cap, then parse guarded. */
+async function readStreamedJsonSource(
+  raw: RequestSource,
+  maxBytes: number,
+  protoPoisoning: ProtoPoisoning,
+): Promise<unknown | Response> {
+  const body = raw.body
   if (body === null) return jsonError(400, "invalid_json")
   const drained = await drainCapped(body, maxBytes)
   if (!drained.ok) return jsonError(413, "payload_too_large")
   try {
-    return JSON.parse(TEXT_DECODER.decode(drained.bytes))
+    return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
   } catch {
     return jsonError(400, "invalid_json")
   }

package/src/server/respond.ts

@@ -117,8 +117,13 @@ function withStatics(response: Response, statics: StaticResponseHeaders | undefi
 }
 
 function applyStaticDefaults(headers: Headers, statics: StaticResponseHeaders): void {
-  for (const [name, value] of statics.entries) {
-    if (!headers.has(name)) headers.set(name, value)
+  // Indexed with an explicit tuple read, not `for...of` with array destructuring: the destructuring
+  // pattern is itself an iterator walk, so the pair form pays two iterator protocols per header.
+  // Measured on a 5-header set: 211ns cheaper on Bun, 56ns on Node.
+  const entries = statics.entries
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!
+    if (!headers.has(entry[0])) headers.set(entry[0], entry[1])
   }
 }
 
@@ -293,7 +298,27 @@ export function fusedRespondNoSet(
   result: unknown,
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
+  unstamped = false,
 ): Response {
+  // With no response hook registered, no code path ever asks whether these headers are mutable, so
+  // stamping the Headers object into the mutability WeakSet is dead work - `Response.json` alone is
+  // cheaper on Bun than the same construction plus the WeakSet write. `unstamped` is the caller's
+  // assertion that the hook walk is empty; an app that registers ANY response hook keeps the stamp,
+  // because the alternative is the set/delete mutability probe on every single response (each one
+  // carries a fresh `Headers`, so the probe's memo never amortizes) - measured 19% slower than
+  // stamping. Default false: an unknown caller pays one WeakSet write rather than a probe per response.
+  if (
+    unstamped &&
+    (tagResponseBody === false || tagResponseBody === undefined) &&
+    statics === undefined &&
+    result !== undefined &&
+    typeof result === "object" &&
+    result !== null &&
+    !(result instanceof Response) &&
+    !isResponseResult(result)
+  ) {
+    return Response.json(result)
+  }
   if (
     result !== undefined &&
     !(result instanceof Response) &&
@@ -308,7 +333,12 @@ export function fusedRespondNoSet(
     // one-call prebuilt init below.
     if (statics !== undefined && IS_DENO && !tagResponseBody) {
       const response = Response.json(result)
-      for (const [name, value] of statics.entries) response.headers.set(name, value)
+      // Indexed for the same reason as `applyStaticDefaults`: pair destructuring is a second
+      // iterator walk per header.
+      for (let i = 0; i < statics.entries.length; i++) {
+        const entry = statics.entries[i]!
+        response.headers.set(entry[0], entry[1])
+      }
       return stamped(response)
     }
     // With declared static headers the prebuilt init already carries them plus the JSON
@@ -352,9 +382,10 @@ export function fusedRespond(
   ctx: RawContext,
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
+  unstamped = false,
 ): Response {
   const set = ctx[CONTEXT_SET]()
-  if (set === undefined) return fusedRespondNoSet(result, tagResponseBody, statics)
+  if (set === undefined) return fusedRespondNoSet(result, tagResponseBody, statics, unstamped)
   return toResponse(result as HandlerResult, set, tagResponseBody, statics)
 }
 

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

@@ -41,7 +41,11 @@
  * or lifecycle hook has already left that lane, so for the routes that look like production the
  * contract is effectively free - declare it.
  */
-import type { StandardIssue, StandardResult, StandardSchemaV1 } from "../schema/standard.ts"
+import {
+  formatStandardIssues,
+  type StandardResult,
+  type StandardSchemaV1,
+} from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
 import type { IdentityPlugin } from "./plugin.ts"
 import type { AnyServer } from "./server.ts"
@@ -75,21 +79,6 @@ function droppedKeys(result: unknown, value: unknown): string[] {
   return Object.keys(result).filter((k) => !(k in value))
 }
 
-function describeIssues(issues: ReadonlyArray<StandardIssue>): string {
-  return issues
-    .map((issue) => {
-      const path = Array.isArray(issue.path)
-        ? issue.path
-            .map((seg) =>
-              String(typeof seg === "object" && seg !== null ? (seg as { key: unknown }).key : seg),
-            )
-            .join(".")
-        : ""
-      return path === "" ? issue.message : `${path}: ${issue.message}`
-    })
-    .join("; ")
-}
-
 /**
  * Check one result against the route's declared response schema.
  *
@@ -116,7 +105,7 @@ function interpret(
   mode: "warn" | "enforce",
 ): ResponseContractOutcome {
   if (settled.issues !== undefined) {
-    const message = `response does not satisfy its declared contract: ${describeIssues(settled.issues)}`
+    const message = `response does not satisfy its declared contract: ${formatStandardIssues(settled.issues)}`
     // `warn` never changes what is served - it reports and gets out of the way, so switching it on can
     // never be the thing that broke production.
     return mode === "warn"

package/src/server/response-hooks.ts

@@ -0,0 +1,51 @@
+import type { NodeResponseContext, ResponseBodyReplacement } from "./node-outcome-hook.ts"
+import { markTaggedResponse, taggedResponseBody, taggedResponseOwner } from "./respond.ts"
+
+export function isBodylessStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304
+}
+
+/** Apply a body hook's return to the native response outcome. */
+export function applyBodyReplacement(
+  response: NodeResponseContext,
+  replaced: string | Uint8Array | ResponseBodyReplacement | undefined,
+): void {
+  if (replaced === undefined) return
+  if (typeof replaced === "string" || replaced instanceof Uint8Array) {
+    response.body = isBodylessStatus(response.status) ? null : replaced
+    return
+  }
+  if (replaced.body !== undefined) response.body = replaced.body
+  if (replaced.status !== undefined) response.status = replaced.status
+  if (isBodylessStatus(response.status)) response.body = null
+}
+
+/**
+ * Swap a tagged Response's body for a hook's replacement, re-tagging so later body hooks and the Node
+ * fallback's direct writer see the new bytes. Explicit lengths are dropped so framing is re-derived.
+ */
+export function withReplacedBody(
+  response: Response,
+  replaced: string | Uint8Array | ResponseBodyReplacement | undefined,
+): Response {
+  if (replaced === undefined) return response
+  const originalBody = taggedResponseBody(response)
+  let body: string | Uint8Array | null
+  let status = response.status
+  if (typeof replaced === "string" || replaced instanceof Uint8Array) {
+    body = replaced
+  } else {
+    body = replaced.body !== undefined ? replaced.body : (originalBody ?? null)
+    if (replaced.status !== undefined) status = replaced.status
+    if (body === (originalBody ?? null) && status === response.status) return response
+  }
+  if (isBodylessStatus(status)) body = null
+  const headers = new Headers(response.headers)
+  headers.delete("content-length")
+  const next = new Response(body as ConstructorParameters<typeof Response>[0], {
+    status,
+    headers,
+  })
+  if (body !== null) markTaggedResponse(next, body, taggedResponseOwner(response))
+  return next
+}

package/src/server/runtime-core.ts

@@ -14,6 +14,20 @@ export const RESPONSE_RESULT = Symbol.for("nifra.response.result")
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
 
+/**
+ * A transport codec (or other pre-parsing hook) that already decoded the body stashes the value
+ * here on the replacement `RequestSource`; the JSON body lane takes it verbatim instead of
+ * parsing again. Boxed so a decoded `undefined` stays distinguishable from "not present". The
+ * stasher owns the poisoning guard for what it stashes - the body lane's own guard only covers
+ * text the lane itself parses.
+ */
+export const PRE_DECODED_BODY = Symbol("nifra.body.preDecoded")
+
+/** The stash shape under {@link PRE_DECODED_BODY}. */
+export interface PreDecodedBody {
+  readonly value: unknown
+}
+
 export interface ResponseResult {
   readonly [RESPONSE_RESULT]: true
   toResponse(): Response