@nifrajs/core 3.3.0 → 4.0.0

package/src/server/auth.ts

@@ -0,0 +1,75 @@
+import type { ResponseResult } from "./runtime-core.ts"
+
+/** A promise-or-value return used by authentication providers. */
+export type AuthMaybePromise<T> = T | Promise<T>
+
+/**
+ * The deliberately narrow header surface given to an authentication provider.
+ *
+ * It is not a `Headers` object: providers can inspect credentials, but cannot mutate the request
+ * headers or reach the request body through this value. The server constructs the view per request.
+ */
+export interface AuthHeaders {
+  readonly get: (name: string) => string | null
+  readonly has: (name: string) => boolean
+  readonly forEach: (callback: (value: string, name: string) => void) => void
+}
+
+/**
+ * The authentication trust boundary. There is intentionally no `Request`, `body`, or parsed query
+ * here. Route parameters are present only for selecting an identity policy and remain untrusted
+ * strings until the normal route validation stage completes.
+ */
+export interface AuthenticationInput<Env = unknown> {
+  readonly method: string
+  readonly pathname: string
+  readonly headers: AuthHeaders
+  readonly params: Readonly<Record<string, string>>
+  readonly env: Env
+  readonly clientIp: string | undefined
+  readonly signal: AbortSignal
+}
+
+export type AuthenticationFailureReason = "unauthenticated" | "forbidden" | "unavailable"
+
+export interface AuthenticationSuccess<Principal> {
+  readonly kind: "authenticated"
+  readonly principal: Principal
+}
+
+export interface AuthenticationFailure {
+  readonly kind: "rejected"
+  readonly reason?: AuthenticationFailureReason
+  /** An integration may provide a redirect or protocol-specific challenge response. */
+  readonly response?: Response | ResponseResult
+}
+
+export type AuthenticationResult<Principal> =
+  | AuthenticationSuccess<Principal>
+  | AuthenticationFailure
+
+/**
+ * A dedicated authentication stage. Stages are captured by route scope at registration time and
+ * execute before input validation on required protected routes.
+ */
+export interface AuthenticationStage<Principal = unknown, Env = unknown> {
+  readonly id: string
+  /** Declares the common path so the compiler can preserve a synchronous protected lane. */
+  readonly mode?: "sync" | "async"
+  readonly run: (
+    input: AuthenticationInput<Env>,
+  ) => AuthMaybePromise<AuthenticationResult<Principal>>
+}
+
+export function authenticated<Principal>(principal: Principal): AuthenticationSuccess<Principal> {
+  return { kind: "authenticated", principal }
+}
+
+export function rejected(
+  reason: AuthenticationFailureReason = "unauthenticated",
+  response?: Response | ResponseResult,
+): AuthenticationFailure {
+  return response === undefined
+    ? { kind: "rejected", reason }
+    : { kind: "rejected", reason, response }
+}

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

@@ -19,17 +19,18 @@
  */
 import { pathnameOf } from "./http.ts"
 import type { Logger } from "./logger.ts"
-import { isResponseResult, type ResponseResult } from "./runtime-core.ts"
+import { isResponseResult } 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;
+ * Render a value thrown on the bare lane. Two shapes, in the order the lane means them:
+ *   - a `Response` or a `status(...)` is control flow - the app answering directly, or plain data.
+ *     Either renders through the same `finalize` a RETURNED one takes, with the request's `c.set`,
+ *     so a thrown one means what the return means: a `Response` ships as built, plus the cookies the
+ *     request queued (the set-session-then-`throw redirect()` pattern);
  *   - 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
@@ -40,13 +41,11 @@ 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,
   internalError: () => T,
 ): T {
-  if (err instanceof Response) return wrapResponse(err)
-  if (isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
+  if (err instanceof Response || isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
   logError(err, ctx)
   return internalError()
 }
@@ -62,11 +61,13 @@ export function emitRequestErrorLog(
   logger: Logger,
   detail: ErrorLogDetail,
   err: unknown,
-  ctx: RawContext,
+  // Only the request line is read, so a lane with no context yet (a request no route matched) can
+  // log through the same policy.
+  // Absent for a failure the runtime reports without its request (Bun's serve `error` callback).
+  ctx: { readonly req: { readonly method: string; readonly url: string } } | undefined,
 ): void {
   logger.error("unhandled request error", {
-    method: ctx.req.method,
-    path: pathnameOf(ctx.req.url),
+    ...(ctx === undefined ? {} : { 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

package/src/server/body-lane.ts

@@ -6,7 +6,7 @@
 import { drainCapped, hasTrustedBodyFraming, parseContentLength, RAW_BODY_READERS } from "./body.ts"
 import { plainError } from "./http.ts"
 import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
-import { isUrlEncodedForm, readBoundedForm } from "./query.ts"
+import { isJsonMediaType, isUrlEncodedForm, readBoundedForm } from "./query.ts"
 import {
   headerOf,
   isResponseResult,
@@ -53,9 +53,9 @@ export function readBoundedJsonSource<T>(
 ): Promise<unknown | ResponseResult | T> {
   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)
+    const value =
+      preDecoded.byteLength > maxBytes ? plainError(413, "payload_too_large") : preDecoded.value
+    return onResult === undefined ? Promise.resolve(value) : Promise.resolve(value).then(onResult)
   }
 
   const raw = ((req as { [RAW_BODY_READERS]?: RequestSource })[RAW_BODY_READERS] ??
@@ -170,7 +170,32 @@ export function readBoundedJsonSource<T>(
   return onResult === undefined ? streamed : streamed.then(onResult, onError)
 }
 
-/** The shared content-type dispatcher around the JSON and urlencoded lanes. */
+/**
+ * Brand under which a body schema carries its own reader for a media type the built-in lanes do not
+ * parse. A registered symbol, so a schema branded by one copy of this module is read by another.
+ */
+export const SCHEMA_BODY_READER: unique symbol = Symbol.for("nifra.body.schemaReader")
+
+/**
+ * A schema-carried body reader. It receives the request's own `content-type`, the route's byte cap,
+ * and the app's prototype-poisoning policy, and owns all three: it answers the value to validate, or
+ * the rejection to send (a `415` for a media type it does not read).
+ */
+export type SchemaBodyReader = ((
+  source: RequestSource,
+  contentType: string,
+  maxBodyBytes: number,
+  protoPoisoning: ProtoPoisoning,
+) => Promise<unknown | ResponseResult>) & {
+  /** The media types a reader declares it reads, for the documents generated from a route. */
+  readonly mediaTypes?: readonly string[]
+}
+
+/**
+ * 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.
+ */
 export function readBodyFramed<T>(
   source: RequestSource,
   maxBodyBytes: number,
@@ -178,15 +203,30 @@ export function readBodyFramed<T>(
   onParsed: (parsed: unknown) => MaybePromise<T>,
   wrapResponse: (response: Response | ResponseResult) => T,
   onError: (err: unknown) => MaybePromise<T>,
+  bodySchema?: object,
 ): Promise<T> {
   const contentType = headerOf(source, "content-type") ?? ""
-  if (contentType !== "application/json" && !contentType.includes("application/json")) {
+  if (!isJsonMediaType(contentType)) {
     if (isUrlEncodedForm(contentType)) {
       return readBoundedForm(source, maxBodyBytes).then(
         (form) => (isResponseResult(form) ? wrapResponse(form) : onParsed(form)),
         onError,
       ) as Promise<T>
     }
+    const reader =
+      bodySchema === undefined
+        ? undefined
+        : (bodySchema as { readonly [SCHEMA_BODY_READER]?: SchemaBodyReader })[SCHEMA_BODY_READER]
+    if (typeof reader === "function") {
+      try {
+        return reader(source, contentType, maxBodyBytes, protoPoisoning).then(
+          (parsed) => (isResponseResult(parsed) ? wrapResponse(parsed) : onParsed(parsed)),
+          onError,
+        ) as Promise<T>
+      } catch (err) {
+        return Promise.resolve(onError(err))
+      }
+    }
     return Promise.resolve(wrapResponse(plainError(415, "unsupported_media_type")))
   }
   try {

package/src/server/body-parser.ts

@@ -0,0 +1,241 @@
+/**
+ * Request bodies in a media type of your own - `bodyParser(schema, { types, parse })`.
+ *
+ * A route reads JSON and urlencoded bodies by default and answers `415` to everything else. Wrapping
+ * its body schema names the other media types that one route reads and the function that decodes
+ * them. The decoded value is then validated by the schema like any other body.
+ *
+ *   import { bodyParser } from "@nifrajs/core/body-parser"
+ *   import { parse } from "yaml"
+ *
+ *   const utf8 = new TextDecoder("utf-8", { fatal: true })
+ *
+ *   app.post(
+ *     "/pipelines",
+ *     {
+ *       body: bodyParser(Pipeline, {
+ *         types: ["application/yaml"],
+ *         parse: (bytes) => parse(utf8.decode(bytes), { maxAliasCount: 0 }),
+ *       }),
+ *     },
+ *     (c) => c.body.name,
+ *   )
+ *
+ * What is settled before `parse` runs:
+ * - the request's media type is one of `types`: compared whole, case folded, parameters set aside
+ * - the body is at most the route's `bodyLimit`, measured on the bytes delivered and not on the
+ *   header, and it is fully read: `parse` is handed bytes and never the request
+ *
+ * What is settled before the schema runs:
+ * - a `parse` that throws or rejects answers `400 invalid_body`
+ * - the value is a tree. An array or object reached twice is what an alias or a cycle decodes to,
+ *   and walking it can cost far more than the bytes that described it, so it answers `400`
+ * - the app's prototype-poisoning policy: a `__proto__` key, a `constructor` that carries a
+ *   `prototype`, and an object whose prototype was replaced by decoded data
+ *
+ * What it does not: a parser's own limits. Nesting depth, alias expansion, and number or string
+ * sizes belong to the decoder you pass, so configure it for untrusted input.
+ *
+ * `types` cannot name a media type that already has a reader (JSON, urlencoded, multipart) or
+ * `text/plain`. A browser sends `text/plain` from any site with the user's cookies and no preflight,
+ * so a route that parsed it would be reachable by a form no CORS policy ever saw. Read such a body
+ * in the handler with `c.boundedBody`, behind an explicit origin check.
+ */
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import { readBoundedBytes } from "./body.ts"
+import { SCHEMA_BODY_READER, type SchemaBodyReader } from "./body-lane.ts"
+import { plainError } from "./http.ts"
+import type { ProtoPoisoning } from "./proto-guard.ts"
+import { isJsonMediaType } from "./query.ts"
+
+/** What `parse` is told about the body it is decoding. */
+export interface BodyParserInput {
+  /** The media type that matched, lower-cased and without parameters. */
+  readonly mediaType: string
+  /** The request's `content-type` as sent, for a parser that reads a parameter such as `charset`. */
+  readonly contentType: string
+}
+
+export interface BodyParserOptions {
+  /** The media types this parser reads, each a full `type/subtype` with no parameters or wildcard. */
+  readonly types: readonly string[]
+  /** Decode the body. The result is what the schema validates; throw to refuse the body with `400`. */
+  readonly parse: (bytes: Uint8Array, input: BodyParserInput) => unknown
+}
+
+// RFC 6838 `restricted-name "/" restricted-name`, lower-cased.
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/
+
+const REFUSED = new Error("invalid_body")
+
+function mediaTypesOf(types: readonly string[]): readonly string[] {
+  if (!Array.isArray(types) || types.length === 0) {
+    throw new TypeError("bodyParser: types must name at least one media type")
+  }
+  const seen = new Set<string>()
+  for (const value of types as readonly unknown[]) {
+    if (typeof value !== "string") throw new TypeError("bodyParser: a media type must be a string")
+    const type = value.toLowerCase()
+    if (!MEDIA_TYPE.test(type)) {
+      throw new TypeError(
+        `bodyParser: "${value}" is not a media type. Name it in full, such as "application/yaml", with no parameters and no wildcard`,
+      )
+    }
+    if (isJsonMediaType(type)) {
+      throw new TypeError(`bodyParser: "${value}" is JSON, which every body schema already reads`)
+    }
+    if (type === "application/x-www-form-urlencoded") {
+      throw new TypeError(`bodyParser: "${value}" is a form, which every body schema already reads`)
+    }
+    if (type.startsWith("multipart/")) {
+      throw new TypeError(
+        `bodyParser: "${value}" is a multipart body. Use multipartBody from "@nifrajs/core/multipart"`,
+      )
+    }
+    if (type === "text/plain") {
+      throw new TypeError(
+        `bodyParser: "${value}" is sent by a browser from any site without a preflight. Read it in the handler with c.boundedBody, behind an origin check`,
+      )
+    }
+    seen.add(type)
+  }
+  return Object.freeze([...seen])
+}
+
+/** Whether `proto` is the prototype of a class, as opposed to an object decoded from the body. */
+function isClassPrototype(proto: object): boolean {
+  const own = Object.getOwnPropertyDescriptor(proto, "constructor")?.value as unknown
+  return typeof own === "function" && (own as { prototype?: unknown }).prototype === proto
+}
+
+/**
+ * One pass over a decoded value. It throws for a value that is not a tree, and applies the
+ * prototype-poisoning policy to every plain object in it. Iterative, so nesting cannot exhaust the
+ * call stack, and each node is visited once, so the cost is the size of what the parser built.
+ */
+function settle(root: unknown, policy: ProtoPoisoning): void {
+  const seen = new Set<object>()
+  const stack: object[] = []
+  const push = (value: unknown): void => {
+    if (value === null || typeof value !== "object") return
+    if (!Array.isArray(value) && !(value instanceof Map) && !(value instanceof Set)) {
+      const proto = Object.getPrototypeOf(value) as object | null
+      if (proto !== null && proto !== Object.prototype) {
+        if (!isClassPrototype(proto)) {
+          // A plain object whose prototype is now data: a decoder that assigns keys one by one
+          // turns a `__proto__` key into exactly this, and every property of that data then reads
+          // as the object's own.
+          if (policy === "reject") throw REFUSED
+          if (policy === "strip") Object.setPrototypeOf(value, Object.prototype)
+        } else if (Object.getPrototypeOf(proto) !== null) {
+          // An instance of a class (a Date, a typed array) is a leaf: it has no keys a body chose.
+          return
+        }
+        // A class prototype with nothing above it is the `Object.prototype` of another realm, and
+        // the object is as plain as one made here.
+      }
+    }
+    if (seen.has(value)) throw REFUSED
+    seen.add(value)
+    stack.push(value)
+  }
+
+  push(root)
+  while (stack.length > 0) {
+    const node = stack.pop() as object
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) push(node[i])
+      continue
+    }
+    if (node instanceof Map) {
+      for (const [key, value] of node) {
+        push(key)
+        push(value)
+      }
+      continue
+    }
+    if (node instanceof Set) {
+      for (const value of node) push(value)
+      continue
+    }
+    const record = node as Record<string, unknown>
+    for (const key of Object.keys(record)) {
+      const value = record[key]
+      if (policy !== "ignore") {
+        const poisoned =
+          key === "__proto__" ||
+          (key === "constructor" &&
+            value !== null &&
+            typeof value === "object" &&
+            Object.hasOwn(value, "prototype"))
+        if (poisoned) {
+          if (policy === "reject") throw REFUSED
+          delete record[key]
+          continue
+        }
+      }
+      push(value)
+    }
+  }
+}
+
+/**
+ * Opt a route's body schema into media types of your own. Returns a copy of `schema` that also reads
+ * a body whose media type is one of `types`, decoded by `parse`; the schema itself is not changed,
+ * and JSON and urlencoded bodies still reach it. A schema that already reads another type, such as a
+ * form, keeps reading it.
+ *
+ * Throws a `TypeError` for a `types` entry that is not a full media type, or that names JSON,
+ * urlencoded, multipart, or `text/plain`.
+ */
+export function bodyParser<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  options: BodyParserOptions,
+): Schema {
+  const types = mediaTypesOf(options.types)
+  const parse = options.parse
+  if (typeof parse !== "function") throw new TypeError("bodyParser: parse must be a function")
+  const accepts = new Set(types)
+  const carried = (schema as { readonly [SCHEMA_BODY_READER]?: SchemaBodyReader })[
+    SCHEMA_BODY_READER
+  ]
+  const inner = typeof carried === "function" ? carried : undefined
+
+  const read: SchemaBodyReader = async (source, contentType, maxBodyBytes, protoPoisoning) => {
+    const semi = contentType.indexOf(";")
+    const mediaType = (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase()
+    if (!accepts.has(mediaType)) {
+      return inner === undefined
+        ? plainError(415, "unsupported_media_type")
+        : inner(source, contentType, maxBodyBytes, protoPoisoning)
+    }
+    const body = await readBoundedBytes(source, maxBodyBytes)
+    if (!body.ok) {
+      return body.status === 413
+        ? plainError(413, "payload_too_large")
+        : plainError(400, "invalid_content_length")
+    }
+    try {
+      const value = await parse(body.bytes, { mediaType, contentType })
+      settle(value, protoPoisoning)
+      return value
+    } catch {
+      return plainError(400, "invalid_body")
+    }
+  }
+  const mediaTypes = Object.freeze([...new Set([...types, ...(inner?.mediaTypes ?? [])])])
+  const reader: PropertyDescriptor = {
+    value: Object.defineProperty(read, "mediaTypes", { value: mediaTypes }),
+  }
+
+  if (typeof schema === "function") {
+    // A callable schema cannot be copied; an object that delegates to it reads the same.
+    return Object.defineProperty(Object.create(schema), SCHEMA_BODY_READER, reader) as Schema
+  }
+  // The reader goes in with the copied properties rather than after them: a schema that was already
+  // opted in carries a reader that cannot be redefined.
+  return Object.create(Object.getPrototypeOf(schema), {
+    ...Object.getOwnPropertyDescriptors(schema),
+    [SCHEMA_BODY_READER]: reader,
+  }) as Schema
+}

package/src/server/body.ts

@@ -82,7 +82,9 @@ export async function drainCapped(
     if (done) break
     total += value.byteLength
     if (total > maxBytes) {
-      await reader.cancel()
+      // Not awaited: on a teed body (a `clone()` taken first) the cancel settles only once the other
+      // branch is read or cancelled too, and nothing here ever reads it.
+      reader.cancel().catch(() => {})
       return { ok: false, status: 413 }
     }
     if (first === undefined) {
@@ -210,9 +212,45 @@ function exactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
     : (bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer)
 }
 
+/** The two members of a raw body stream {@link cappedStreamOf} uses. */
+interface RawStream {
+  getReader(): unknown
+  cancel(reason?: unknown): Promise<void>
+}
+
+// Deno's `process.env` throws without `--allow-env`, so the dev guard in `capRequestBodyReads` asks
+// `typeof Deno` first: a bare typeof is pure, so a production `NODE_ENV` define folds the guard away.
+declare const Deno: unknown
+
+/** Dev only: `body`, recording the first reader user code takes from it through the capped getter. */
+function markedOnRead(body: ReadableStream<Uint8Array>, mark: () => void): RawStream {
+  return {
+    getReader: () => {
+      mark()
+      return body.getReader()
+    },
+    cancel: (reason) => body.cancel(reason),
+  }
+}
+
+/**
+ * Dev only: user code streamed the native body, which is one-shot, so every framework reader after
+ * it (a body schema, `c.boundedJson()`, the handler's `c.req.json()`) can only fail. Each raw reader
+ * now throws, synchronously so no lane maps it to a client error, naming the reader that replays.
+ */
+function spendRaw(raw: RawBodyReaders): void {
+  const spent = (): never => {
+    throw new TypeError(
+      "[nifra] c.req.body was read as a stream; read it with c.req.bytes() in a hook",
+    )
+  }
+  Object.assign(raw, { arrayBuffer: spent, bytes: spent, json: spent })
+  Object.defineProperty(raw, "body", { get: spent })
+}
+
 /** A pass-through stream that errors (with `reject(413)`) once more than `maxBytes` flow through. */
 function cappedStreamOf(
-  body: ReadableStream<Uint8Array>,
+  body: RawStream,
   maxBytes: number,
   reject: (status: 400 | 413) => unknown,
 ): ReadableStream<Uint8Array> {
@@ -231,7 +269,7 @@ function cappedStreamOf(
   return new ReadableStream<Uint8Array>(
     {
       async pull(controller) {
-        reader ??= body.getReader() as unknown as CappedReader
+        reader ??= body.getReader() as CappedReader
         const active = reader
         const { done, value } = await active.read()
         if (done) {
@@ -293,11 +331,34 @@ function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBod
   // One bounded buffer backs every shadowed reader; a second read replays it instead of failing
   // with "body already used" (a strict superset of the native one-shot contract).
   let buffered: Promise<Uint8Array> | undefined
-  const cappedBytes = (): Promise<Uint8Array> =>
-    (buffered ??= readBoundedBytes(raw, maxBytes).then((read) => {
-      if (!read.ok) throw reject(read.status)
-      return read.bytes
-    }))
+  const cappedBytes = (): Promise<Uint8Array> => {
+    if (buffered === undefined) {
+      const read = readBoundedBytes(raw, maxBytes).then((result) => {
+        if (!result.ok) throw reject(result.status)
+        return result.bytes
+      })
+      buffered = read
+      // The raw readers now replay these bytes, so a framework reader that runs after a hook read
+      // `c.req` (an auth-first route's body schema) parses the same body instead of a spent stream.
+      // readBoundedBytes took its reader before its first await, so it never reads the replay.
+      Object.assign(raw, {
+        arrayBuffer: shadowed.arrayBuffer,
+        bytes: shadowed.bytes,
+        json: shadowed.json,
+      })
+      Object.defineProperty(raw, "body", {
+        get: () =>
+          new ReadableStream<Uint8Array>({
+            start: (controller) =>
+              read.then((bytes) => {
+                controller.enqueue(bytes)
+                controller.close()
+              }),
+          }),
+      })
+    }
+    return buffered
+  }
   // The reader methods live on the prototype as writable data properties, so a plain instance
   // assignment shadows them - materially cheaper than defineProperty on this per-read path. Only
   // `body` (a prototype accessor) needs defineProperty below.
@@ -339,7 +400,19 @@ function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBod
     get(): ReadableStream<Uint8Array> | null {
       if (cappedBody === undefined) {
         const rawBody = raw.body
-        cappedBody = rawBody === null ? null : cappedStreamOf(rawBody, maxBytes, reject)
+        cappedBody =
+          rawBody === null
+            ? null
+            : cappedStreamOf(
+                typeof Deno === "undefined" && process.env.NODE_ENV !== "production"
+                  ? markedOnRead(rawBody, () => {
+                      // After a buffered read the getter streams a replay, which spends nothing.
+                      if (buffered === undefined) spendRaw(raw)
+                    })
+                  : rawBody,
+                maxBytes,
+                reject,
+              )
       }
       return cappedBody
     },

package/src/server/client-ip.ts

@@ -25,6 +25,15 @@
  */
 export type ClientIpTrust = { readonly trustedHops: number } | { readonly header: string }
 
+/**
+ * Marks a platform whose `clientIp` an enclosing nifra server already derived under its own `clientIp`
+ * trust declaration. A server that receives such a platform takes `clientIp` as-is instead of re-deriving
+ * it from the request's forwarding headers - an in-process call's `Request` is synthesized, so identity
+ * travels in the platform, never in headers a rebuilt request would lose. Only server code builds a
+ * platform; a client cannot set it.
+ */
+export const NIFRA_PLATFORM_CLIENT_IP_DERIVED = Symbol.for("@nifrajs/platform-client-ip-derived")
+
 function firstHeaderValue(req: Request, header: string): string | undefined {
   const raw = req.headers.get(header)
   if (raw === null) return undefined