@nifrajs/core 2.10.0 → 2.12.0

package/src/server/static-headers.ts

@@ -9,6 +9,8 @@
  * hook) is applied later and therefore wins.
  */
 
+import { markLowercaseHeaderKeys } from "./header-case.ts"
+
 /** Valid HTTP field-name characters (RFC 9110 token). */
 const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
 
@@ -118,25 +120,47 @@ function store<V>(record: Record<string, V>, name: string, value: V): void {
  * than left alongside - one header name spelled two ways in a single record ships as a comma-joined
  * value on the Web paths and as two lines on Node, so writing the static entry blind would change
  * the wire instead of being overridden.
+ *
+ * `markLowercase` asks for the all-lowercase proof to be published on the result when it holds. The
+ * merge is the natural place to answer that: the static names were lowercased at registration, and
+ * the loop below already derives `lower` for every own name to decide the override, so `lower !==
+ * name` is the whole answer at no added cost. Only the Node-direct lane asks - its readers are the
+ * ones that would otherwise re-walk these keys - and only for an app with no raw native response
+ * twin, since such a twin writes the record past the case-normalizing view AFTER this runs.
  */
 export function mergeStaticHeaderRecord<V>(
   statics: Readonly<Record<string, string>>,
   own: Readonly<Record<string, V>>,
+  markLowercase = false,
 ): Record<string, V | string> {
   const merged: Record<string, V | string> = { ...statics }
+  let allLowercase = true
   for (const name of Object.keys(own)) {
     const value = own[name] as V
     if (value === undefined) continue
     const lower = name.toLowerCase()
-    if (lower !== name && Object.hasOwn(merged, lower)) delete merged[lower]
+    if (lower !== name) {
+      allLowercase = false
+      if (Object.hasOwn(merged, lower)) delete merged[lower]
+    }
     store(merged, name, value)
   }
+  if (markLowercase && allLowercase) {
+    markLowercaseHeaderKeys(merged as Record<string, string | readonly string[]>)
+  }
   return merged
 }
 
-/** A fresh, mutable copy of the static record - what the lanes whose writers mutate the record get. */
+/**
+ * A fresh, mutable copy of the static record - what the lanes whose writers mutate the record get.
+ * Every name in it was lowercased at registration, so `markLowercase` publishes a proof that needs no
+ * scan at all; the gate on it is the same one {@link mergeStaticHeaderRecord} documents.
+ */
 export function staticHeaderRecordCopy(
   statics: StaticResponseHeaders,
+  markLowercase = false,
 ): Record<string, string | readonly string[]> {
-  return { ...statics.record }
+  const copy = { ...statics.record }
+  if (markLowercase) markLowercaseHeaderKeys(copy)
+  return copy
 }

package/src/server/transport-lane.ts

@@ -2,7 +2,8 @@
 import type { TransportCodec, TransportCodecRegistry } from "../transport-codec.ts"
 import { readBoundedBytes } from "./body.ts"
 import { jsonError } from "./http.ts"
-import { isResponseResult } from "./runtime-core.ts"
+import { guardParsedValue, type ProtoPoisoning } from "./proto-guard.ts"
+import { isResponseResult, PRE_DECODED_BODY, type PreDecodedBody } from "./runtime-core.ts"
 import type { AnyServer, IdentityPlugin } from "./server.ts"
 
 interface TransportBodySource {
@@ -28,6 +29,13 @@ export interface TransportRuntime {
 export interface TransportCodecsOptions {
   /** Maximum encoded request bytes. Keep aligned with `server({ maxBodyBytes })`. */
   readonly maxBytes?: number
+  /**
+   * Prototype-poisoning policy for decoded request bodies, mirroring
+   * `server({ protoPoisoning })` - this lane parses with the codec's own decoder, so the body
+   * lane's guard never sees the raw text and the policy must be enforced here. Default `"reject"`:
+   * a poisoned payload answers the same flat 400 as an undecodable one.
+   */
+  readonly protoPoisoning?: ProtoPoisoning
 }
 
 export function transportCodecs(
@@ -38,6 +46,7 @@ export function transportCodecs(
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
     throw new RangeError("transport maxBytes must be a non-negative safe integer")
   }
+  const protoPoisoning = options.protoPoisoning ?? "reject"
   const runtime: TransportRuntime = Object.freeze({
     responseCodec(accept: string | null): TransportCodec {
       try {
@@ -70,9 +79,12 @@ export function transportCodecs(
         }
       }
       try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(read.bytes)
+        // Same poisoning policy as the body lane, enforced on the codec's own decode - a rejected
+        // payload answers exactly like an undecodable one.
         return {
           matched: true,
-          value: codec.decode(new TextDecoder("utf-8", { fatal: true }).decode(read.bytes)),
+          value: guardParsedValue(codec.decode(text), protoPoisoning),
         }
       } catch {
         return {
@@ -103,9 +115,9 @@ export function transportCodecs(
       if (!decoded.matched) return undefined
       if ("response" in decoded) return decoded.response
 
-      // Keep an untouched body branch while the bounded decoder consumes the other tee branch.
-      // Existing JSON validation lanes can then use their native `request.json()` fast path while
-      // receiving the already-decoded rich value without importing codec machinery into the kernel.
+      // Re-frame as a plain JSON request whose already-decoded value rides the pre-decoded stash;
+      // the body lane takes the stash verbatim (this lane owns the cap and poisoning policy), so
+      // the placeholder body is never parsed and codec machinery stays out of the kernel.
       const headers: Record<string, string> = {}
       replacement.headers.forEach((value, name) => {
         headers[name] = value
@@ -119,9 +131,8 @@ export function transportCodecs(
         body: "{}",
         signal: replacement.signal as never,
       })
-      Object.defineProperty(normalized, "json", {
-        value: () => Promise.resolve(decoded.value),
-      })
+      const stash: PreDecodedBody = { value: decoded.value }
+      Object.defineProperty(normalized, PRE_DECODED_BODY, { value: stash })
       return normalized
     })
     app.afterHandle((result, context) => {

package/src/server/websocket.ts

@@ -207,6 +207,7 @@ export type WebSocketUpgradeOutcome =
        * a standard socket without a static import of the WS implementation (which would defeat the
        * `.use(websocket())` tree-shaking). `@nifrajs/workers` may import `attachWebSocket` directly instead. */
       readonly attach: WsAttach
+      readonly maxPayloadBytes?: number
     }
 
 /** The socket-wiring signature the upgrade outcome carries (the installed runtime's `attach`). */
@@ -214,7 +215,7 @@ export type WsAttach = (
   socket: StandardWebSocket,
   handler: WebSocketHandler,
   data: unknown,
-  options: { openNow: boolean; pubsub: TopicRegistry },
+  options: { openNow: boolean; pubsub: TopicRegistry; maxPayloadBytes?: number },
 ) => NifraWebSocket
 
 /**
@@ -249,7 +250,7 @@ export function attachWebSocket(
   socket: StandardWebSocket,
   handler: WebSocketHandler,
   data: unknown,
-  options: { openNow: boolean; pubsub: TopicRegistry },
+  options: { openNow: boolean; pubsub: TopicRegistry; maxPayloadBytes?: number },
 ): NifraWebSocket {
   const { pubsub } = options
   const ws: NifraWebSocket = {
@@ -282,9 +283,23 @@ export function attachWebSocket(
   }
   // Deliver binary as ArrayBuffer (→ Uint8Array) rather than Blob, where the runtime allows it.
   if ("binaryType" in socket) socket.binaryType = "arraybuffer"
+  const maxPayloadBytes = options.maxPayloadBytes
   socket.addEventListener("message", (event: { readonly data: unknown }) => {
     const raw = event.data
     const payload: WebSocketData = typeof raw === "string" ? raw : toBinary(raw)
+    // Measuring a text frame costs a full UTF-8 encode plus the buffer it allocates, so it happens
+    // only for a route that actually declared a cap. Reading `.byteLength` off an already-decoded
+    // binary frame is free, but the branch stays under the same guard to keep one shape here.
+    if (maxPayloadBytes !== undefined) {
+      const payloadBytes =
+        typeof raw === "string"
+          ? WS_PAYLOAD_ENCODER.encode(raw).byteLength
+          : (payload as Uint8Array).byteLength
+      if (payloadBytes > maxPayloadBytes) {
+        socket.close(1009, "message too large")
+        return
+      }
+    }
     safe(() => handler.message?.(ws, payload))
   })
   socket.addEventListener(
@@ -304,6 +319,7 @@ export function attachWebSocket(
 }
 
 const WS_MESSAGE_DECODER = new TextDecoder()
+const WS_PAYLOAD_ENCODER = new TextEncoder()
 
 /**
  * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame -

package/src/server.ts

@@ -31,6 +31,8 @@ export type {
 } from "./server/context.ts"
 export {
   type CookieOptions,
+  type CookieSecret,
+  cookieNamePrefix,
   parseCookies,
   serializeCookie,
   signValue,
@@ -73,6 +75,9 @@ export {
   type AdmissionController,
   type AdmissionDecision,
   type AnyServer,
+  type ContextPlugin,
+  type DefinePluginResult,
+  defineContextPlugin,
   defineIdentityPlugin,
   definePlugin,
   defineRouterPlugin,
@@ -81,6 +86,7 @@ export {
   type McpPromptDescriptor,
   type McpResourceDescriptor,
   type Middleware,
+  type NifraFeatureVersion,
   type NifraPlugin,
   type NodeRequestContext,
   type NodeRequestHook,
@@ -88,6 +94,7 @@ export {
   type NodeResponseHook,
   type NodeServeOutcome,
   type OnRequestResult,
+  type PluginTypeCollapsed,
   type PromptArgument,
   type PromptMessage,
   type ResponseBodyHook,

package/src/tool-catalog.ts

@@ -0,0 +1,40 @@
+/** Descriptive projections of typed tool contracts for model and transport catalogs. */
+
+import {
+  type ToolAnnotations,
+  type ToolApprovalPolicy,
+  type ToolContract,
+  type ToolSensitivity,
+  toolInputJsonSchema,
+} from "./tool-contract.ts"
+
+/**
+ * A read-only, transport-neutral view of a tool contract.
+ *
+ * This module is descriptive only. It never validates input, checks capabilities, requests approval,
+ * reserves idempotency, consumes cost, or executes the tool. Those policies stay in `executeTool`.
+ */
+export interface ToolCatalogEntry {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Record<string, unknown>
+  readonly capability: string
+  readonly sensitivity: ToolSensitivity
+  readonly approval: ToolApprovalPolicy
+  readonly idempotent: boolean
+  readonly annotations: ToolAnnotations
+}
+
+/** Build the single descriptive projection shared by agent, MCP, and test adapters. */
+export function toCatalogEntry<Input, Output>(tool: ToolContract<Input, Output>): ToolCatalogEntry {
+  return Object.freeze({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: Object.freeze({ ...toolInputJsonSchema(tool) }),
+    capability: tool.capability,
+    sensitivity: tool.sensitivity,
+    approval: tool.approval,
+    idempotent: tool.idempotency !== undefined,
+    annotations: tool.annotations,
+  })
+}