@nifrajs/core 2.11.0 → 2.12.0

package/src/server/body.ts

@@ -1,15 +1,40 @@
 /**
  * Bounded request-body reading - the single source of truth for nifra's body-size cap. A lying or
  * absent `Content-Length` can't force us to buffer an oversized payload: a declared length over the
- * cap is rejected *before* buffering, and a chunked / length-less body is aborted mid-stream once the
- * running byte count exceeds the cap. Shared by the server's schema path, `c.boundedBody`, and
- * `verifyWebhook` so they all enforce the same guarantee.
+ * cap is rejected *before* buffering, a chunked / length-less body is aborted mid-stream once the
+ * running byte count exceeds the cap, and the fast path re-checks the real byte count after the
+ * read - the declared length is a hint, never the enforcement. Shared by the server's schema path,
+ * `c.boundedBody`, and `verifyWebhook` so they all enforce the same guarantee.
  */
 
+import { jsonError } from "./http.ts"
+
 interface BodySource {
   readonly headers: Pick<Headers, "get">
   readonly body: ReadableStream<Uint8Array> | null
   arrayBuffer(): Promise<ArrayBuffer>
+  bytes?(): Promise<Uint8Array>
+}
+
+/** The pre-cap reader surface a transport-capped request stashes under {@link RAW_BODY_READERS}. */
+export interface RawBodyReaders {
+  readonly headers: Pick<Headers, "get">
+  readonly body: ReadableStream<Uint8Array> | null
+  arrayBuffer(): Promise<ArrayBuffer>
+  /** Runtime-native exact-byte reader, when the request implementation exposes one. */
+  bytes?(): Promise<Uint8Array>
+  json(): Promise<unknown>
+}
+
+/**
+ * The raw readers of a transport-capped request (see {@link capTransportBodyReads}), or the source
+ * itself when it was never capped. Framework readers (the schema lane, `c.boundedBody`,
+ * `verifyWebhook`, the idempotency lane) read through this so the transport cap on *direct* user
+ * reads never narrows their own caller-supplied cap - `c.boundedBody(explicitBytes)` must keep
+ * overriding the route cap upward, exactly as before the transport cap existed.
+ */
+export function rawBodySourceOf<T extends BodySource>(req: T): T {
+  return ((req as { [RAW_BODY_READERS]?: T })[RAW_BODY_READERS] as T | undefined) ?? req
 }
 
 /** Security/resource limits must be finite byte counts. Invalid values otherwise make `> maxBytes`
@@ -74,14 +99,16 @@ export async function drainCapped(
  * Read a request body as **bytes**, capped at `maxBytes`. Rejects a `Content-Length` over the cap
  * before buffering (`413`) and a malformed `Content-Length` (`400`); a chunked / length-less body
  * falls through to the streaming byte-cap guard. Fast path: a non-chunked request with a
- * `Content-Length` within the cap is read via native `arrayBuffer()` (framing-bounded by the runtime's
- * HTTP server), skipping the manual stream loop.
+ * `Content-Length` within the cap is read via native `arrayBuffer()`, then the **real** byte count
+ * is checked against the declared length - a source that delivers more than it declared (a lying
+ * or upstream-decoding adapter) is rejected with `413` even though its header passed the hint.
  */
 export async function readBoundedBytes(
-  req: BodySource,
+  source: BodySource,
   maxBytes: number,
 ): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 400 | 413 }> {
   assertByteLimit(maxBytes)
+  const req = rawBodySourceOf(source)
   const declared = req.headers.get("content-length")
   if (declared !== null) {
     // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A non-numeric
@@ -91,9 +118,250 @@ export async function readBoundedBytes(
     if (length === undefined) return { ok: false, status: 400 }
     if (length > maxBytes) return { ok: false, status: 413 }
     const chunked = req.headers.get("transfer-encoding") !== null
-    if (!chunked) return { ok: true, bytes: new Uint8Array(await req.arrayBuffer()) }
+    if (!chunked) {
+      const bytesReader = req.bytes
+      const bytes =
+        bytesReader === undefined
+          ? new Uint8Array(await req.arrayBuffer())
+          : await bytesReader.call(req)
+      // Content-Length was the fast-reject hint, never the enforcement: a lying or buffering
+      // source (an adapter that decoded/expanded the body upstream) can hand over more bytes
+      // than it declared. `length <= maxBytes` held above, so one comparison seals the cap.
+      if (bytes.byteLength > length) return { ok: false, status: 413 }
+      return { ok: true, bytes }
+    }
   }
   const body = req.body
   if (body === null) return { ok: true, bytes: new Uint8Array(0) }
   return drainCapped(body, maxBytes)
 }
+
+/** Key under which a transport-capped request stashes its {@link RawBodyReaders}. */
+export const RAW_BODY_READERS = Symbol("nifra.body.rawReaders")
+
+/**
+ * Ingress mark for a request whose bytes a runtime HTTP parser already delimited - Bun's compiled
+ * native route table, `Deno.serve`, or an edge runtime that hands its own `Request` through
+ * untouched. For those the declared Content-Length IS the transport frame, so the JSON lane keeps
+ * the runtime's fused decode+parse instead of copying the body out to count it.
+ *
+ * Everything unmarked - a hand-built `Request`, the in-process client, and above all an adapter
+ * that REBUILDS a body from parts an attacker supplied (an event envelope carrying both a header
+ * map and a payload) - stays on the delivered-byte check. That is the shape the cap actually
+ * defends against: a `content-length` copied from the caller while the body was decoded to a
+ * different size.
+ *
+ * Registered (`Symbol.for`) on purpose, matching `nifra.response.body`: `@nifrajs/deno` mirrors
+ * core's types rather than importing them, so an adapter must be able to set this without taking a
+ * dependency on core. Forging it needs in-process code execution, which could equally just call
+ * `app.fetch` with any `Request` it likes - so the registry costs no ground the process didn't
+ * already own.
+ */
+const TRUSTED_FRAMING = Symbol.for("nifra.body.trustedFraming")
+
+/** Mark a request delivered straight from a runtime HTTP parser. */
+export function markTrustedBodyFraming(source: object): void {
+  ;(source as { [TRUSTED_FRAMING]?: true })[TRUSTED_FRAMING] = true
+}
+
+/** True only for the runtime-framed ingress mark. */
+export function hasTrustedBodyFraming(source: object): boolean {
+  return (source as { [TRUSTED_FRAMING]?: true })[TRUSTED_FRAMING] === true
+}
+
+/** A capped request/source is capped exactly once; re-entry is a no-op. */
+const TRANSPORT_CAPPED = new WeakSet<object>()
+
+const CAP_DECODER = new TextDecoder()
+
+/** Key under which the dispatcher marks a source with its route's transport byte cap. */
+const TRANSPORT_CAP = Symbol("nifra.body.transportCap")
+
+/** The transport cap's over-cap rejection: the flat error a shadowed direct reader throws (and the
+ * capped `body` stream errors with). The lifecycle already treats a thrown `Response` as control
+ * flow (the `c.boundedBody` contract), so an over-cap direct read answers 413 like every other cap. */
+function transportCapError(status: 400 | 413): Response {
+  return jsonError(status, status === 413 ? "payload_too_large" : "invalid_content_length")
+}
+
+/** First matching own-or-inherited descriptor, so instance shadows and prototype accessors both resolve. */
+function descriptorOf(target: object, key: string): PropertyDescriptor | undefined {
+  let current: object | null = target
+  while (current !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, key)
+    if (descriptor !== undefined) return descriptor
+    current = Object.getPrototypeOf(current) as object | null
+  }
+  return undefined
+}
+
+/** An `ArrayBuffer` spanning exactly `bytes`, without a copy when the view already owns its buffer. */
+function exactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+    ? (bytes.buffer as ArrayBuffer)
+    : (bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer)
+}
+
+/** A pass-through stream that errors (with `reject(413)`) once more than `maxBytes` flow through. */
+function cappedStreamOf(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+  reject: (status: 400 | 413) => unknown,
+): ReadableStream<Uint8Array> {
+  // The reader is acquired on first pull, and `highWaterMark: 0` defers that first pull until a
+  // consumer actually reads (the default of 1 pulls eagerly at construction): merely *accessing*
+  // the capped `body` getter must not lock the raw stream (native semantics - only reading
+  // consumes the body).
+  // Typed structurally: the runtimes' lib typings disagree on the reader's shape (Bun's `readMany`,
+  // Node's BYOB `read(view)` overload), and only `read`/`cancel` are used here.
+  interface CappedReader {
+    read(): Promise<{ done: false; value: Uint8Array } | { done: true; value?: undefined }>
+    cancel(reason?: unknown): Promise<void>
+  }
+  let reader: CappedReader | undefined
+  let total = 0
+  return new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        reader ??= body.getReader() as unknown as CappedReader
+        const active = reader
+        const { done, value } = await active.read()
+        if (done) {
+          controller.close()
+          return
+        }
+        total += value.byteLength
+        if (total > maxBytes) {
+          await active.cancel().catch(() => {})
+          controller.error(reject(413))
+          return
+        }
+        controller.enqueue(value)
+      },
+      cancel(reason) {
+        return reader === undefined ? body.cancel(reason) : reader.cancel(reason)
+      },
+    },
+    { highWaterMark: 0 },
+  )
+}
+
+/**
+ * Shadow a request's direct body readers (`arrayBuffer`/`json`/`text`/`blob`/`bytes`/`formData`,
+ * the `body` stream, and `clone`) with byte-capped versions, **on the same object** - the request's
+ * identity is never swapped, so `WeakMap` keys, symbol stashes (the transport-codec lane's
+ * pre-decoded body), and hook-observed references all survive. Nothing is read eagerly: the cap
+ * only pays when user code actually reads, and framework readers bypass it through
+ * {@link rawBodySourceOf} (stashed under {@link RAW_BODY_READERS}) to enforce their own caps.
+ * An over-cap read rejects with `reject(413)` (a lying `Content-Length` with `reject(400)`), which
+ * the lifecycle already treats as control flow - the same contract as `c.boundedBody`.
+ */
+function capRequestBodyReads(request: Request, maxBytes: number): void {
+  if (TRANSPORT_CAPPED.has(request)) return
+  TRANSPORT_CAPPED.add(request)
+  const reject = transportCapError
+  const bodyDescriptor = descriptorOf(request, "body")
+  const raw: RawBodyReaders = {
+    get headers() {
+      return request.headers
+    },
+    get body() {
+      return (
+        bodyDescriptor?.get !== undefined
+          ? bodyDescriptor.get.call(request)
+          : (bodyDescriptor?.value ?? null)
+      ) as ReadableStream<Uint8Array> | null
+    },
+    arrayBuffer: request.arrayBuffer.bind(request),
+    json: request.json.bind(request),
+  }
+  if (typeof request.bytes === "function") raw.bytes = request.bytes.bind(request)
+  // 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
+    }))
+  // 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.
+  const shadowed = request as unknown as Record<string, unknown> & {
+    [RAW_BODY_READERS]?: RawBodyReaders
+  }
+  shadowed[RAW_BODY_READERS] = raw
+  shadowed.arrayBuffer = () => cappedBytes().then(exactArrayBuffer)
+  shadowed.bytes = () => cappedBytes().then((bytes) => bytes.slice())
+  shadowed.json = () =>
+    cappedBytes().then((bytes) => JSON.parse(CAP_DECODER.decode(bytes)) as unknown)
+  shadowed.text = () => cappedBytes().then((bytes) => CAP_DECODER.decode(bytes))
+  shadowed.blob = () =>
+    cappedBytes().then(
+      (bytes) =>
+        new Blob([exactArrayBuffer(bytes)], {
+          type: request.headers.get("content-type") ?? "",
+        }),
+    )
+  shadowed.formData = () =>
+    cappedBytes().then((bytes) =>
+      new Response(exactArrayBuffer(bytes), {
+        headers: { "content-type": request.headers.get("content-type") ?? "" },
+      }).formData(),
+    )
+  // `clone()` must not mint an uncapped escape hatch: the clone gets the same cap.
+  if (typeof request.clone === "function") {
+    // Node's lib typing returns undici's `Request` here; at runtime it's the same object shape.
+    const rawClone = request.clone.bind(request) as () => Request
+    shadowed.clone = () => {
+      const clone = rawClone()
+      capRequestBodyReads(clone, maxBytes)
+      return clone
+    }
+  }
+  let cappedBody: ReadableStream<Uint8Array> | null | undefined
+  Object.defineProperty(request, "body", {
+    configurable: true,
+    get(): ReadableStream<Uint8Array> | null {
+      if (cappedBody === undefined) {
+        const rawBody = raw.body
+        cappedBody = rawBody === null ? null : cappedStreamOf(rawBody, maxBytes, reject)
+      }
+      return cappedBody
+    },
+  })
+}
+
+/**
+ * Mark a request source with its route's transport byte cap. Dispatch-time cost is one property
+ * write; nothing is shadowed, wrapped, or read here - the hot path stays untouched. The cap is
+ * applied by {@link applyTransportCap} only when user code actually reaches for the request
+ * (`c.req` / `c.request`), so a route that never direct-reads the body pays nothing.
+ */
+export function markTransportCap(source: object, maxBytes: number): void {
+  ;(source as { [TRANSPORT_CAP]?: number })[TRANSPORT_CAP] = maxBytes
+}
+
+/**
+ * Enforce a marked source's transport byte cap on **direct user reads** of its request
+ * (`c.req.json()`, `c.req.arrayBuffer()`, the raw `body` stream, `clone()`, ...), without swapping
+ * the request's identity and without reading anything eagerly: the direct readers are shadowed with
+ * byte-capped versions on the same object, so `WeakMap` keys, symbol stashes (the transport-codec
+ * lane's pre-decoded body), and hook-observed references all survive. Framework readers bypass the
+ * shadow through {@link rawBodySourceOf} and enforce their own caps - `c.boundedBody(explicit)`
+ * still overrides in either direction. An unmarked source (`bodyLimit: "unlimited"`) is untouched.
+ */
+export function applyTransportCap(source: object, request: Request): void {
+  const maxBytes = (source as { [TRANSPORT_CAP]?: number })[TRANSPORT_CAP]
+  // The capped check comes BEFORE the body-null check: post-cap, `request.body` is the shadowed
+  // getter, and re-reading it on every `c.req` access would rebuild capped state for nothing.
+  if (maxBytes === undefined || TRANSPORT_CAPPED.has(request) || request.body === null) return
+  capRequestBodyReads(request, maxBytes)
+  // A wrapper source (Node's lazy source) delegates its own body readers to the request once it
+  // materializes - which are now the shadowed ones. Mirror the raw-reader stash onto the source so
+  // framework readers (`rawBodySourceOf(source)`) keep reading pre-shadow there too.
+  const raw = (request as unknown as { [RAW_BODY_READERS]?: RawBodyReaders })[RAW_BODY_READERS]
+  if ((source as unknown) !== request && raw !== undefined) {
+    ;(source as { [RAW_BODY_READERS]?: RawBodyReaders })[RAW_BODY_READERS] = raw
+  }
+}

package/src/server/context.ts

@@ -62,6 +62,13 @@ export type Params<Path extends string> = Prettify<RawParams<Path>>
 
 /** Per-route input schemas. Each is any Standard Schema (zod/valibot/arktype/…). */
 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. */
+  readonly bodyLimit?: number | "unlimited"
+  /** Required explanation when bodyLimit is 'unlimited' (for example, a streaming upload is
+   * bounded by an upstream object-store protocol). */
+  readonly bodyLimitReason?: string
   /** Declared effect tokens. Reflected for assurance; never read by validation or serialization. */
   readonly capabilities?: readonly string[]
   /**
@@ -106,6 +113,10 @@ export interface RouteSchema {
    * The schema must cover every path param; with the strict default an undeclared path param is rejected.
    * When omitted, `c.params` stays the path-inferred `Record<name, string>`. */
   readonly params?: StandardSchemaV1
+  /** Optional request-header schema. Header names are normalized to lower-case and the validated
+   * output is exposed as `c.headers`; use lower-case keys because HTTP header names are
+   * case-insensitive. */
+  readonly headers?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it
@@ -130,8 +141,8 @@ export interface RouteSchema {
    */
   readonly sse?: StandardSchemaV1
   /**
-   * Hook fired when the request fails `body`/`query` validation, before the handler runs. `kind` says
-   * which input failed (`"body"` | `"query"`). Its return value selects one of three outcomes (may be async):
+   * Hook fired when the request fails `headers`/`params`/`body`/`query` validation, before the handler
+   * runs. `kind` says which input failed. Its return value selects one of three outcomes (may be async):
    *   - a **`Response`** → returned as-is, short-circuiting the route (custom error envelope, redirect, …).
    *   - **any other value** → treated as a repaired payload and **re-validated once** against the same
    *     schema. If it now passes, the handler runs with it; if it still fails, the original `422` stands.
@@ -145,7 +156,7 @@ export interface RouteSchema {
   readonly onValidationError?: (
     issues: ReadonlyArray<StandardIssue>,
     ctx: Context,
-    kind: "body" | "query" | "params",
+    kind: "body" | "query" | "params" | "headers",
   ) => Response | unknown | Promise<Response | unknown>
 }
 
@@ -159,6 +170,13 @@ type QueryOf<S extends RouteSchema> = S extends { query: infer Q extends Standar
   ? InferOutput<Q>
   : URLSearchParams
 
+/** The validated request-header type when a header schema is declared, else a lower-case record. */
+type HeadersOf<S extends RouteSchema> = S extends {
+  headers: infer H extends StandardSchemaV1
+}
+  ? InferOutput<H>
+  : Readonly<Record<string, string>>
+
 /** The validated params type when a params schema is declared, else the path-inferred `Params<Path>`. */
 type ParamsOf<S extends RouteSchema, Path extends string> = S extends {
   params: infer P extends StandardSchemaV1
@@ -216,6 +234,8 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   /** Read one request header without materializing a Web `Request` on the Node adapter hot path. */
   readonly header: (name: string) => string | null
   readonly params: ParamsOf<S, Path>
+  /** Lower-case request headers, validated/coerced when `schema.headers` is declared. */
+  readonly headers: HeadersOf<S>
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>
   /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on

package/src/server/contract.ts

@@ -2,7 +2,8 @@ import type { DataClassification } from "../classification.ts"
 import { RouteConfigError } from "../errors.ts"
 import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
 import { METHODS, type Method } from "../router/router.ts"
-import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import { assertByteLimit } from "./body.ts"
 import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
 import type { EmptyRegistry, OutputOf, Registry } from "./registry.ts"
 import { Server } from "./server.ts"
@@ -28,6 +29,8 @@ export interface OperationDef {
   readonly path: string
   /** Optional path-params schema (validated + coercible at the boundary; see {@link RouteSchema.params}). */
   readonly params?: StandardSchemaV1
+  /** Optional request-header schema (header names are normalized to lower-case). */
+  readonly headers?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
@@ -35,6 +38,9 @@ export interface OperationDef {
   readonly capabilities?: readonly string[]
   /** Dedupe retries of this operation on an `Idempotency-Key` header (see {@link RouteSchema.idempotency}). */
   readonly idempotency?: IdempotencyConfig
+  /** Per-route transport body cap; see RouteSchema.bodyLimit. */
+  readonly bodyLimit?: number | "unlimited"
+  readonly bodyLimitReason?: string
   /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
   readonly classification?: DataClassification
   /** Inline route-assurance evidence this operation carries (see {@link RouteSchema.assurance}). */
@@ -62,11 +68,14 @@ export interface OperationDef {
 /** A contract: named operations. Names are the handler keys and OpenAPI operationIds. */
 export type ContractShape = Record<string, OperationDef>
 
+/** Client-visible request inputs use the schema's INPUT side (what a caller sends pre-validation,
+ * so a defaulted field stays optional on the wire) - mirroring the inline registry's
+ * `RegistryBody`/`RegistryQuery`. Handler-facing types (ContextForOp) still use the output side. */
 type OpBody<O extends OperationDef> = O extends { body: infer B extends StandardSchemaV1 }
-  ? InferOutput<B>
+  ? InferInput<B>
   : never
 type OpQuery<O extends OperationDef> = O extends { query: infer Q extends StandardSchemaV1 }
-  ? InferOutput<Q>
+  ? InferInput<Q>
   : never
 type OpResponse<O extends OperationDef> = O extends { response: infer R extends StandardSchemaV1 }
   ? InferOutput<R>
@@ -129,6 +138,9 @@ type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends St
   ? { body: B }
   : Record<never, never>) &
   (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>) &
+  (O extends { headers: infer H extends StandardSchemaV1 }
+    ? { headers: H }
+    : Record<never, never>) &
   (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 /**
@@ -188,6 +200,29 @@ export function defineContract<const C extends ContractShape>(contract: C): C {
         `operation "${name}": path must start with "/": "${op.path}"`,
       )
     }
+    if (op.bodyLimitReason !== undefined && op.bodyLimit !== "unlimited") {
+      throw new RouteConfigError(
+        "INVALID_BODY_LIMIT",
+        `operation "${name}": bodyLimitReason is only valid with bodyLimit: "unlimited"`,
+      )
+    }
+    if (op.bodyLimit === "unlimited") {
+      if (typeof op.bodyLimitReason !== "string" || op.bodyLimitReason.trim().length === 0) {
+        throw new RouteConfigError(
+          "INVALID_BODY_LIMIT",
+          `operation "${name}": bodyLimit: "unlimited" requires a non-empty bodyLimitReason`,
+        )
+      }
+    } else if (op.bodyLimit !== undefined) {
+      try {
+        assertByteLimit(op.bodyLimit, "operation bodyLimit")
+      } catch {
+        throw new RouteConfigError(
+          "INVALID_BODY_LIMIT",
+          `operation "${name}": bodyLimit must be a non-negative safe integer or "unlimited"`,
+        )
+      }
+    }
     const key = `${method} ${op.path}`
     if (seen.has(key)) {
       throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
@@ -265,21 +300,26 @@ export function implement<
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
       op.params !== undefined ||
+      op.headers !== undefined ||
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
+      op.bodyLimit !== undefined ||
       op.classification !== undefined ||
       op.assurance !== undefined ||
       op.family !== undefined
         ? {
             ...(op.params !== undefined ? { params: op.params } : {}),
+            ...(op.headers !== undefined ? { headers: op.headers } : {}),
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
+            ...(op.bodyLimit !== undefined ? { bodyLimit: op.bodyLimit } : {}),
+            ...(op.bodyLimitReason !== undefined ? { bodyLimitReason: op.bodyLimitReason } : {}),
             ...(op.classification !== undefined ? { classification: op.classification } : {}),
             ...(op.assurance !== undefined ? { assurance: op.assurance } : {}),
             ...(op.family !== undefined ? { family: op.family } : {}),

package/src/server/cookies.ts

@@ -25,6 +25,21 @@ export interface CookieOptions {
 const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
 const MAX_COOKIE_BYTES = 4096 // browsers cap a cookie near 4 KB - reject oversized before the wire
 
+/**
+ * RFC 6265bis cookie-name prefix, matched **case-insensitively** the way browsers match it -
+ * `__secure-x` triggers the same enforcement as `__Secure-x`. `undefined` for unprefixed names.
+ * Writers (set AND delete) must satisfy the prefix contract or the user agent silently discards
+ * the whole `Set-Cookie`.
+ */
+export function cookieNamePrefix(name: string): "secure" | "host" | undefined {
+  // Both prefixes start `__`; two charCode probes keep unprefixed names (the common case) free.
+  if (name.charCodeAt(0) !== 95 /* _ */ || name.charCodeAt(1) !== 95) return undefined
+  const lowered = name.toLowerCase()
+  if (lowered.startsWith("__secure-")) return "secure"
+  if (lowered.startsWith("__host-")) return "host"
+  return undefined
+}
+
 /** True if `v` contains a character illegal in a cookie attribute (control char or `;` separator) -
  * the header-injection guard for dev-supplied `Path`/`Domain`. */
 const hasIllegalChar = (v: string): boolean => {
@@ -102,8 +117,9 @@ export function parseCookies(header: string | null | undefined): Record<string,
 /**
  * Serialize a `Set-Cookie` header value. Pure - applies **no** security defaults (the caller, e.g.
  * `c.set.cookie`, layers `HttpOnly`/`Secure`/`SameSite` on). Throws on an invalid cookie name, a
- * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result - a serialization
- * bug should fail loudly, not silently emit a cookie the browser drops.
+ * header-injecting `Path`/`Domain`, a non-integer `maxAge`, a `__Secure-`/`__Host-` name whose
+ * attributes violate its prefix contract, or an oversized result - a serialization bug should fail
+ * loudly, not silently emit a cookie the browser drops.
  */
 export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
   if (!COOKIE_NAME.test(name)) {
@@ -111,6 +127,25 @@ export function serializeCookie(name: string, value: string, options: CookieOpti
       `[nifra] invalid cookie name ${JSON.stringify(name)}: must be an RFC 6265 token`,
     )
   }
+  // Enforce the prefix contract: a violating cookie would be silently discarded by the user
+  // agent (or worse, only by SOME user agents, leaving the rest accepting a cookie whose prefix
+  // promises protections it doesn't have).
+  const prefix = cookieNamePrefix(name)
+  if (prefix !== undefined) {
+    if (options.secure !== true) {
+      throw new Error(
+        `[nifra] cookie ${JSON.stringify(name)}: ${prefix === "host" ? "__Host-" : "__Secure-"} requires Secure`,
+      )
+    }
+    if (prefix === "host") {
+      if (options.domain !== undefined) {
+        throw new Error(`[nifra] cookie ${JSON.stringify(name)}: __Host- forbids Domain`)
+      }
+      if (options.path !== "/") {
+        throw new Error(`[nifra] cookie ${JSON.stringify(name)}: __Host- requires Path=/`)
+      }
+    }
+  }
   let str = `${name}=${encodeURIComponent(value)}`
   if (options.maxAge !== undefined) {
     if (!Number.isInteger(options.maxAge)) {
@@ -159,8 +194,11 @@ const importHmacKey = (secret: string): Promise<CryptoKey> => {
 }
 
 const toBase64Url = (buf: ArrayBuffer): string => {
+  // Indexed, not `for...of`: iterating a typed array runs the iterator protocol per byte, and at a
+  // 32-byte HMAC digest that is 238ns on Bun and 174ns on Node - a third of the whole encode.
   let bin = ""
-  for (const b of new Uint8Array(buf)) bin += String.fromCharCode(b)
+  const bytes = new Uint8Array(buf)
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!)
   return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
 }
 
@@ -177,9 +215,24 @@ const fromBase64Url = (s: string): Uint8Array<ArrayBuffer> | null => {
   }
 }
 
-/** Append an HMAC-SHA256 signature to a value → `value.signature` (base64url). For signed cookies. */
-export async function signValue(value: string, secret: string): Promise<string> {
-  const key = await importHmacKey(secret)
+/**
+ * A signing secret, or a rotation list of them. With a list, **the first secret signs** and
+ * verification accepts **any** entry - so rotation is: prepend the new secret, keep the old one
+ * until every cookie signed by it has expired, then drop it. An empty list throws.
+ */
+export type CookieSecret = string | readonly string[]
+
+const firstSecret = (secret: CookieSecret): string => {
+  if (typeof secret === "string") return secret
+  const first = secret[0]
+  if (first === undefined) throw new Error("[nifra] signed-cookie: secret list cannot be empty")
+  return first
+}
+
+/** Append an HMAC-SHA256 signature to a value → `value.signature` (base64url). For signed cookies.
+ * With a {@link CookieSecret} rotation list, signs with the first secret. */
+export async function signValue(value: string, secret: CookieSecret): Promise<string> {
+  const key = await importHmacKey(firstSecret(secret))
   const sig = await crypto.subtle.sign("HMAC", key, TEXT.encode(value))
   return `${value}.${toBase64Url(sig)}`
 }
@@ -188,14 +241,31 @@ export async function signValue(value: string, secret: string): Promise<string>
  * Verify a `value.signature` produced by {@link signValue} and return the value, or `null` if the
  * signature is missing, malformed, or doesn't match. Verification is **constant-time**
  * (`crypto.subtle.verify`), so a wrong signature can't be discovered byte-by-byte via timing.
+ *
+ * With a {@link CookieSecret} rotation list, tries each secret in order and accepts the first
+ * match. Every listed secret must meet the 32-byte floor - a weak entry throws even when an
+ * earlier secret would have matched, so a rotation list can't quietly carry a weak key. (Which
+ * rotation generation matched is not attacker-meaningful, so the early exit between secrets leaks
+ * nothing useful; each individual comparison stays constant-time.)
  */
-export async function unsignValue(signed: string, secret: string): Promise<string | null> {
+export async function unsignValue(signed: string, secret: CookieSecret): Promise<string | null> {
   const dot = signed.lastIndexOf(".")
   if (dot < 1) return null // no signature segment (or empty value)
   const value = signed.slice(0, dot)
   const sig = fromBase64Url(signed.slice(dot + 1))
   if (sig === null) return null
-  const key = await importHmacKey(secret)
-  const ok = await crypto.subtle.verify("HMAC", key, sig, TEXT.encode(value))
-  return ok ? value : null
+  const data = TEXT.encode(value)
+  if (typeof secret === "string") {
+    // Hot path (single secret) - identical to the pre-rotation behavior, no array allocation.
+    const key = await importHmacKey(secret)
+    const ok = await crypto.subtle.verify("HMAC", key, sig, data)
+    return ok ? value : null
+  }
+  if (secret.length === 0) throw new Error("[nifra] signed-cookie: secret list cannot be empty")
+  for (const s of secret) requireSecretBytes(s, "signed-cookie")
+  for (const s of secret) {
+    const key = await importHmacKey(s)
+    if (await crypto.subtle.verify("HMAC", key, sig, data)) return value
+  }
+  return null
 }

package/src/server/edge.ts

@@ -103,6 +103,16 @@ export function toFetchHandler<Env = unknown>(
   const resolveWs = app.resolveWebSocketUpgrade?.bind(app)
   return {
     fetch: (request, env, ctx) => {
+      // The platform's own HTTP parser delimited this body, so the declared Content-Length IS the
+      // transport frame rather than a caller's hint - the same guarantee Bun's native routes and
+      // `Deno.serve` carry, and the reason `serve(request, env, ctx)` is a stronger statement about
+      // provenance than a bare `app.fetch(req)` (which anyone in-process can call with a hand-built
+      // Request). The mark keeps core's JSON lane on the runtime's fused parse instead of copying
+      // the body out to recount its bytes. Written as the registered symbol, not an import of
+      // `markTrustedBodyFraming`, so this file keeps its no-runtime-edge property: a GET-only edge
+      // app must not pull `body.ts` (and `http.ts` behind it) into its bundle for one flag.
+      ;(request as unknown as Record<symbol, unknown>)[Symbol.for("nifra.body.trustedFraming")] =
+        true
       const platform: Platform<Env> = { env, waitUntil: (promise) => ctx.waitUntil(promise) }
       // WebSocket broadcast on Workers: route upgrades to the hub Durable Object (it holds the
       // connections + runs the app's pub/sub, so `app.publish` reaches every client). The hub itself