@nifrajs/core 2.1.0 → 2.3.0

package/dist/server/websocket.js

@@ -1,17 +1,17 @@
 /**
- * WebSocket seam — portable types shared by `@nifrajs/core`'s `app.ws()` and every serving adapter
+ * WebSocket seam - portable types shared by `@nifrajs/core`'s `app.ws()` and every serving adapter
  * (Bun `listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler` on Workers). No runtime code here, so
  * it stays edge-safe and dependency-free; each adapter implements {@link NifraWebSocket} over its
  * runtime's native socket and dispatches to the handler.
  *
- * A WS upgrade can't go through `app.fetch` (which has no socket) — it's adapter-integrated. The
+ * A WS upgrade can't go through `app.fetch` (which has no socket) - it's adapter-integrated. The
  * adapter calls `app.resolveWebSocketUpgrade(req)` (runs the route's `upgrade()` guard in a real
  * request context), then performs the runtime upgrade with the returned data.
  */
 import { validateStandard } from "../schema/standard.js";
 import { decodeTransportFrame } from "../transport-codec.js";
 /**
- * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** —
+ * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** -
  * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load
  * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to
  * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.
@@ -38,11 +38,11 @@ export class TopicRegistry {
         if (subs !== undefined) {
             subs.delete(ws);
             if (subs.size === 0)
-                this.topics.delete(topic); // reclaim empty topics — no unbounded growth
+                this.topics.delete(topic); // reclaim empty topics - no unbounded growth
         }
         this.memberships.get(ws)?.delete(topic);
     }
-    /** Drop every subscription for a connection — called on close so a registry never leaks dead sockets. */
+    /** Drop every subscription for a connection - called on close so a registry never leaks dead sockets. */
     unsubscribeAll(ws) {
         const mine = this.memberships.get(ws);
         if (mine === undefined)
@@ -80,13 +80,13 @@ function toBinary(raw) {
         return new Uint8Array(raw);
     if (ArrayBuffer.isView(raw))
         return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
-    return new Uint8Array(0); // unknown (e.g. an unconverted Blob) — adapters set binaryType to avoid this
+    return new Uint8Array(0); // unknown (e.g. an unconverted Blob) - adapters set binaryType to avoid this
 }
 /**
  * Wire a standard server-side `WebSocket` to a nifra {@link WebSocketHandler}, returning the portable
  * {@link NifraWebSocket}. Shared by the Deno and Workers bridges. `openNow` fires `open` immediately
  * (Workers, where the socket is already open after `accept()`); otherwise `open` waits for the socket's
- * `open` event (Deno). Lifecycle callbacks are error-isolated — a throw (or async rejection) routes to
+ * `open` event (Deno). Lifecycle callbacks are error-isolated - a throw (or async rejection) routes to
  * `error()` and never tears the process down; binary frames are normalized to `Uint8Array`.
  */
 export function attachWebSocket(socket, handler, data, options) {
@@ -111,7 +111,7 @@ export function attachWebSocket(socket, handler, data, options) {
                 r.catch(() => { });
         }
         catch {
-            /* the error handler itself failed — last resort, swallow */
+            /* the error handler itself failed - last resort, swallow */
         }
     };
     const safe = (call) => {
@@ -147,7 +147,7 @@ export function attachWebSocket(socket, handler, data, options) {
 }
 const WS_MESSAGE_DECODER = new TextDecoder();
 /**
- * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame —
+ * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame -
  * parse as JSON, run the Standard Schema, then call the user's `message` with the typed value, or
  * `onInvalidMessage` on failure. Returns the handler unchanged when no schema is set. Called once at
  * `app.ws()` registration, so every adapter dispatches validated messages with no per-adapter code.

package/dist/server/ws-bun.d.ts

@@ -1,8 +1,8 @@
 /**
- * Bun WebSocket plumbing — the `websocket` dispatcher config `listen()` hands to Bun's serve when
+ * Bun WebSocket plumbing - the `websocket` dispatcher config `listen()` hands to Bun's serve when
  * the app has WS routes. Lives behind the `@nifrajs/core/ws` subpath (via `ws-hook.ts`) so the base
  * bundle of a no-WebSocket app never ships it; `server.ts` only imports the **types** from here
- * (erased). No `Bun.*` calls here — the runtime seam stays in `server.ts` (see runtime-boundary.test).
+ * (erased). No `Bun.*` calls here - the runtime seam stays in `server.ts` (see runtime-boundary.test).
  */
 import type { NifraWebSocket, TopicRegistry, WebSocketHandler } from "./websocket.js";
 import type { BunWsHandlers } from "./ws-hook.js";
@@ -13,7 +13,7 @@ export interface BunWsData {
     data: unknown;
     nifra?: NifraWebSocket;
 }
-/** Structural view of Bun's `ServerWebSocket` — keeps `Bun.*` types out of the public `.d.ts`
+/** Structural view of Bun's `ServerWebSocket` - keeps `Bun.*` types out of the public `.d.ts`
  * (`listen()` casts for the same reason). The real socket satisfies this. */
 export interface BunSocket {
     send(data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number;
@@ -21,7 +21,7 @@ export interface BunSocket {
     readonly readyState: number;
     readonly data: BunWsData;
 }
-/** The shared Bun `websocket` dispatcher config for one app — each connection's
+/** The shared Bun `websocket` dispatcher config for one app - each connection's
  * `ws.data.handler` is the matched route's handler, set by `server.upgrade`. */
 export declare function createBunWsHandlers(topics: TopicRegistry): BunWsHandlers;
 //# sourceMappingURL=ws-bun.d.ts.map

package/dist/server/ws-bun.js

@@ -1,8 +1,8 @@
 /**
- * Bun WebSocket plumbing — the `websocket` dispatcher config `listen()` hands to Bun's serve when
+ * Bun WebSocket plumbing - the `websocket` dispatcher config `listen()` hands to Bun's serve when
  * the app has WS routes. Lives behind the `@nifrajs/core/ws` subpath (via `ws-hook.ts`) so the base
  * bundle of a no-WebSocket app never ships it; `server.ts` only imports the **types** from here
- * (erased). No `Bun.*` calls here — the runtime seam stays in `server.ts` (see runtime-boundary.test).
+ * (erased). No `Bun.*` calls here - the runtime seam stays in `server.ts` (see runtime-boundary.test).
  */
 /** Normalize a received binary frame to `Uint8Array` (Bun hands a `Buffer`, already one; an
  * `ArrayBuffer` is wrapped). Text frames stay `string`. */
@@ -55,7 +55,7 @@ function dispatchWsCallback(call, ws, handler) {
         reportWsError(error, ws, handler);
     }
 }
-/** The shared Bun `websocket` dispatcher config for one app — each connection's
+/** The shared Bun `websocket` dispatcher config for one app - each connection's
  * `ws.data.handler` is the matched route's handler, set by `server.upgrade`. */
 export function createBunWsHandlers(topics) {
     return {

package/dist/server.d.ts

@@ -9,13 +9,15 @@
  */
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.js";
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.js";
+export { isSameOriginRequest } from "./internal/same-origin.js";
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.js";
 export type { InferInput, InferOutput, StandardIssue, StandardResult, StandardSchemaV1, StandardTypes, ValidationOutcome, } from "./schema/standard.js";
 export type { Context, Params, Platform, Prettify, ResponseControls, RouteSchema, } from "./server/context.js";
 export { type CookieOptions, parseCookies, serializeCookie, signValue, unsignValue, } from "./server/cookies.js";
+export { type DurableObjectNamespaceLike, type ExecutionContext, type ScheduledController, type ScheduledHandler, toFetchHandler, } from "./server/edge.js";
 export { commonSecretPatterns, jsonLogger, type LogFields, type Logger, type RedactOptions, redactLogFields, silentLogger, } from "./server/logger.js";
 export type { Registry, RouteInfo } from "./server/registry.js";
-export { type AdmissionController, type AdmissionDecision, type AnyServer, type DurableObjectNamespaceLike, defineIdentityPlugin, definePlugin, defineRouterPlugin, type ExecutionContext, type Handler, type IdentityPlugin, type McpPromptDescriptor, type McpResourceDescriptor, type Middleware, type NifraPlugin, type NodeServeOutcome, type OnRequestResult, type PromptArgument, type PromptMessage, type ResponseFinalization, type RouteDescriptor, type RunningServer, type ScheduledController, type ScheduledHandler, Server, type ServerOptions, server, type ToolAnnotations, toFetchHandler, } from "./server/server.js";
+export { type AdmissionController, type AdmissionDecision, type AnyServer, defineIdentityPlugin, definePlugin, defineRouterPlugin, type Handler, type IdentityPlugin, type McpPromptDescriptor, type McpResourceDescriptor, type Middleware, type NifraPlugin, type NodeServeOutcome, type OnRequestResult, type PromptArgument, type PromptMessage, type ResponseFinalization, type RouteDescriptor, type RunningServer, Server, type ServerOptions, server, type ToolAnnotations, } from "./server/server.js";
 export type { SSEContext, SSEInit, SSEMessage, SSEStream, TypedSSEStream, } from "./server/sse.js";
 export type { NifraWebSocket, StandardWebSocket, WebSocketContext, WebSocketData, WebSocketHandler, WebSocketUpgradeOutcome, } from "./server/websocket.js";
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,UAAU,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,UAAU,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA"}

package/dist/server.js

@@ -9,8 +9,10 @@
  */
 export { FrameworkError, RouteConfigError } from "./errors.js";
 export { FRAMEWORK_NAME } from "./internal/brand.js";
+export { isSameOriginRequest } from "./internal/same-origin.js";
 export { METHODS, Router } from "./router/router.js";
 export { parseCookies, serializeCookie, signValue, unsignValue, } from "./server/cookies.js";
+export { toFetchHandler, } from "./server/edge.js";
 export { commonSecretPatterns, jsonLogger, redactLogFields, silentLogger, } from "./server/logger.js";
-export { defineIdentityPlugin, definePlugin, defineRouterPlugin, Server, server, toFetchHandler, } from "./server/server.js";
+export { defineIdentityPlugin, definePlugin, defineRouterPlugin, Server, server, } from "./server/server.js";
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAsB,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAe,MAAM,EAAoB,MAAM,oBAAoB,CAAA;AAkBnF,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EAIV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAKL,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAiBlB,MAAM,EAEN,MAAM,EAEN,cAAc,GACf,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAsB,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAe,MAAM,EAAoB,MAAM,oBAAoB,CAAA;AAkBnF,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAKL,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,UAAU,EAIV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAIL,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAclB,MAAM,EAEN,MAAM,GAEP,MAAM,oBAAoB,CAAA"}

package/dist/transport-codec.d.ts

@@ -13,7 +13,7 @@ export interface TransportCodec {
     decode(text: string): unknown;
 }
 export declare class TransportCodecError extends TypeError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export declare const plainJsonCodec: TransportCodec;
 export interface TransportCodecRegistry {
@@ -25,6 +25,18 @@ export interface TransportCodecRegistry {
 export declare function createTransportCodecRegistry(codecs: readonly TransportCodec[], fallback?: TransportCodec): TransportCodecRegistry;
 export declare const defaultTransportCodecs: TransportCodecRegistry;
 export declare function encodeTransportResponse(value: unknown, codec?: TransportCodec, init?: ResponseInit): Response;
+/**
+ * Read a response body into memory, refusing to exceed `maxBytes`.
+ *
+ * Bounded while STREAMING rather than after the fact: the `content-length` shortcut only helps when a
+ * sender declares one, so the loop also counts as it goes and cancels the reader the moment the total
+ * passes the limit. A cap that buffers first and complains afterwards has already spent the memory it
+ * was meant to protect.
+ *
+ * Exported so the client can bound a plain-text body with the same reader it bounds JSON with, rather
+ * than growing a second copy of this loop that could drift from it.
+ */
+export declare function readBoundedBytes(response: Response, options: TransportDecodeOptions): Promise<Uint8Array>;
 export declare function decodeTransportResponse(response: Response, registry?: TransportCodecRegistry, options?: TransportDecodeOptions): Promise<unknown>;
 export declare function encodeTransportFrame(value: unknown, codec?: TransportCodec): string;
 export declare function decodeTransportFrame(frame: string, registry?: TransportCodecRegistry, options?: TransportDecodeOptions): unknown;

package/dist/transport-codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-codec.d.ts","sourceRoot":"","sources":["../src/transport-codec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC9B;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAmBD,eAAO,MAAM,cAAc,EAAE,cAY3B,CAAA;AAEF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IAC1D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IAChD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAA;CACxD;AAUD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,QAAQ,GAAE,cAA+B,GACxC,sBAAsB,CA0ExB;AAED,eAAO,MAAM,sBAAsB,EAAE,sBAEnC,CAAA;AAEF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,cAA+B,EACtC,IAAI,GAAE,YAAiB,GACtB,QAAQ,CAKV;AA2CD,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,sBAA+C,EACzD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,OAAO,CAAC,CAIlB;AAQD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,cAA+B,GACrC,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,sBAA+C,EACzD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAcT"}
+{"version":3,"file":"transport-codec.d.ts","sourceRoot":"","sources":["../src/transport-codec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC9B;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAsCD,eAAO,MAAM,cAAc,EAAE,cAY3B,CAAA;AAEF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IAC1D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IAChD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAA;CACxD;AAUD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,QAAQ,GAAE,cAA+B,GACxC,sBAAsB,CA0ExB;AAED,eAAO,MAAM,sBAAsB,EAAE,sBAEnC,CAAA;AAEF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,cAA+B,EACtC,IAAI,GAAE,YAAiB,GACtB,QAAQ,CAKV;AAQD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC,CA8BrB;AAaD,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,sBAA+C,EACzD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,OAAO,CAAC,CAQlB;AAQD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,cAA+B,GACrC,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,sBAA+C,EACzD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAsBT"}

package/dist/transport-codec.js

@@ -5,11 +5,31 @@
 const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
 const TOKEN = /^[a-z][a-z0-9_.-]{0,63}$/;
 export class TransportCodecError extends TypeError {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = "TransportCodecError";
     }
 }
+/**
+ * Run a decode step and normalize whatever it throws into {@link TransportCodecError}.
+ *
+ * Decoding is the one place this module touches attacker-controlled bytes, and the primitives it
+ * delegates to raise their own native types - `JSON.parse` throws `SyntaxError`, a BYO codec throws
+ * whatever it likes. Every other failure here is a `TransportCodecError`, so letting those escape
+ * would mean a malformed payload - the single most likely hostile input - is the one case that slips
+ * past a caller catching the documented error type. The original is kept as `cause`, so the parse
+ * failure stays diagnosable; a codec already speaking the contract is re-thrown untouched.
+ */
+function decodeOrThrow(decode, message) {
+    try {
+        return decode();
+    }
+    catch (cause) {
+        if (cause instanceof TransportCodecError)
+            throw cause;
+        throw new TransportCodecError(message, { cause });
+    }
+}
 function maxBytesOf(options) {
     const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
@@ -132,13 +152,24 @@ function appendVary(current, name) {
     const values = current.split(",").map((value) => value.trim().toLowerCase());
     return values.includes(name.toLowerCase()) ? current : `${current}, ${name}`;
 }
-async function readBoundedText(response, options) {
+/**
+ * Read a response body into memory, refusing to exceed `maxBytes`.
+ *
+ * Bounded while STREAMING rather than after the fact: the `content-length` shortcut only helps when a
+ * sender declares one, so the loop also counts as it goes and cancels the reader the moment the total
+ * passes the limit. A cap that buffers first and complains afterwards has already spent the memory it
+ * was meant to protect.
+ *
+ * Exported so the client can bound a plain-text body with the same reader it bounds JSON with, rather
+ * than growing a second copy of this loop that could drift from it.
+ */
+export async function readBoundedBytes(response, options) {
     const maxBytes = maxBytesOf(options);
     const declared = response.headers.get("content-length");
     if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes)
         throw new TransportCodecError("transport payload exceeds maxBytes");
     if (response.body === null)
-        return "";
+        return new Uint8Array(0);
     const reader = response.body.getReader();
     const chunks = [];
     let total = 0;
@@ -164,19 +195,25 @@ async function readBoundedText(response, options) {
         bytes.set(chunk, offset);
         offset += chunk.byteLength;
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return bytes;
+}
+async function readBoundedText(response, options) {
+    const bytes = await readBoundedBytes(response, options);
+    return decodeOrThrow(() => new TextDecoder("utf-8", { fatal: true }).decode(bytes), "transport payload is not valid UTF-8");
 }
 export async function decodeTransportResponse(response, registry = defaultTransportCodecs, options = {}) {
     const codec = registry.forContentType(response.headers.get("content-type"));
     const text = await readBoundedText(response, options);
-    return text === "" ? undefined : codec.decode(text);
+    if (text === "")
+        return undefined;
+    return decodeOrThrow(() => codec.decode(text), `malformed transport body for codec ${codec.id}@${codec.version}`);
 }
 export function encodeTransportFrame(value, codec = plainJsonCodec) {
     return JSON.stringify({ codec: codec.id, version: codec.version, payload: codec.encode(value) });
 }
 export function decodeTransportFrame(frame, registry = defaultTransportCodecs, options = {}) {
     assertBounded(frame, options);
-    const envelope = JSON.parse(frame);
+    const envelope = decodeOrThrow(() => JSON.parse(frame), "malformed transport frame");
     if (envelope === null ||
         typeof envelope !== "object" ||
         typeof envelope.codec !== "string" ||
@@ -184,7 +221,9 @@ export function decodeTransportFrame(frame, registry = defaultTransportCodecs, o
         typeof envelope.payload !== "string") {
         throw new TransportCodecError("malformed transport frame");
     }
-    assertBounded(envelope.payload, options);
-    return registry.byIdentity(envelope.codec, envelope.version).decode(envelope.payload);
+    const payload = envelope.payload;
+    assertBounded(payload, options);
+    const codec = registry.byIdentity(envelope.codec, envelope.version);
+    return decodeOrThrow(() => codec.decode(payload), `malformed transport frame payload for codec ${codec.id}@${codec.version}`);
 }
 //# sourceMappingURL=transport-codec.js.map

package/dist/transport-codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport-codec.js","sourceRoot":"","sources":["../src/transport-codec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transport-codec.js","sourceRoot":"","sources":["../src/transport-codec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/core",
-  "version": "2.1.0",
-  "description": "Bun-native, contract-first HTTP framework — the router, server, and route descriptor.",
+  "version": "2.3.0",
+  "description": "Bun-native, contract-first HTTP framework - the router, server, and route descriptor.",
   "keywords": [
     "bun",
     "typescript",
@@ -72,6 +72,11 @@
       "types": "./dist/assurance.d.ts",
       "default": "./dist/assurance.js"
     },
+    "./binary": {
+      "bun": "./src/binary.ts",
+      "types": "./dist/binary.d.ts",
+      "default": "./dist/binary.js"
+    },
     "./capabilities": {
       "bun": "./src/capabilities.ts",
       "types": "./dist/capabilities.d.ts",
@@ -201,6 +206,11 @@
       "bun": "./src/server/webhook.ts",
       "types": "./dist/server/webhook.d.ts",
       "default": "./dist/server/webhook.js"
+    },
+    "./response-contract": {
+      "bun": "./src/server/response-contract-lane.ts",
+      "types": "./dist/server/response-contract-lane.d.ts",
+      "default": "./dist/server/response-contract-lane.js"
     }
   },
   "files": [

package/src/assurance.ts

@@ -4,8 +4,11 @@
  */
 
 import {
+  type CapabilityAccess,
   type CapabilityAssuranceReport,
+  type CapabilityDefinition,
   type CapabilityPolicy,
+  type CapabilityZone,
   defineCapabilityPolicy,
 } from "./capabilities.ts"
 import type {
@@ -40,6 +43,62 @@ export interface AssuranceRouteSelector {
   readonly paths?: readonly string[]
   /** Restrict the rule to MCP tool routes (`true`) or non-tool routes (`false`). */
   readonly tools?: boolean
+  /**
+   * Match routes declaring ANY of these capability tokens.
+   *
+   * Lets a policy be written about what a route DOES rather than where it lives: "anything that writes
+   * to the database must be authenticated" survives a route being moved or renamed, which a path glob
+   * does not. Reflection already carries the declared tokens, so this reads what the route said about
+   * itself.
+   *
+   * Naming exact tokens is precise but closed: a rule listing `db.write` does not cover `storage.write`,
+   * and a capability added next year escapes it in silence. Prefer `access`/`zone` for a rule that is
+   * meant to hold for a CLASS of effect.
+   */
+  readonly capabilities?: readonly string[]
+  /**
+   * Match routes declaring any capability whose definition has this access.
+   *
+   * This is the selector to reach for when the rule is "anything that writes must prove who asked":
+   * it is keyed on what the capability IS rather than what it is called, so a token introduced later
+   * is covered the day it is declared instead of the day someone remembers to widen the rule.
+   *
+   * Requires capability definitions. A policy using it without them is refused rather than quietly
+   * matching nothing - a selector that matches nothing lets the route fall through to a laxer rule.
+   */
+  readonly access?: CapabilityAccess
+  /**
+   * Match routes declaring any capability in this zone. Combined with `access`, both must hold for the
+   * SAME capability, so `{ access: "write", zone: "domain" }` is "writes business state" and does not
+   * match a route that only writes an audit log.
+   */
+  readonly zone?: CapabilityZone
+}
+
+/** Extra inputs an assurance evaluation needs beyond the routes themselves. */
+export interface AssuranceEvaluationOptions {
+  /**
+   * Capability definitions, required by any rule selecting on `access`/`zone`. Normally
+   * `config.capabilities.definitions`.
+   */
+  readonly definitions?: readonly CapabilityDefinition[]
+}
+
+/** Selector keys that cannot be resolved from reflection alone. */
+const CLASS_SELECTOR_KEYS = ["access", "zone"] as const
+
+const usesClassSelector = (selector: AssuranceRouteSelector): boolean =>
+  selector.access !== undefined || selector.zone !== undefined
+
+/** The rules whose selector needs capability definitions to mean anything. */
+function rulesNeedingDefinitions(policy: AssurancePolicy): readonly string[] {
+  return policy.rules.filter((rule) => usesClassSelector(rule.match)).map((rule) => rule.name)
+}
+
+function definitionMap(
+  definitions: readonly CapabilityDefinition[] | undefined,
+): ReadonlyMap<string, CapabilityDefinition> {
+  return new Map((definitions ?? []).map((definition) => [definition.id, definition]))
 }
 
 export interface AssuranceRule {
@@ -166,6 +225,19 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
     if (names.has(name))
       throw new Error(`route assurance: duplicate rule name ${JSON.stringify(name)}`)
     names.add(name)
+    // The selector is rebuilt from known keys below, so an unrecognised one would be dropped in
+    // silence - and a selector that loses its only constraint matches EVERY route, making the rule
+    // swallow everything after it. A misspelled key is a policy hole, so it is refused here.
+    const unknown = Object.keys(rule.match).filter(
+      (key) => !["methods", "paths", "tools", "capabilities", ...CLASS_SELECTOR_KEYS].includes(key),
+    )
+    if (unknown.length > 0) {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(rule.name)} has unknown selector key(s) ${unknown
+          .map((key) => JSON.stringify(key))
+          .join(", ")} - a dropped selector would match every route`,
+      )
+    }
     if (rule.match.tools !== undefined && typeof rule.match.tools !== "boolean") {
       throw new Error(
         `route assurance: rule ${JSON.stringify(name)} tools selector must be boolean`,
@@ -181,6 +253,24 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
       routeGlob(path)
       return path
     })
+    const capabilities = rule.match.capabilities
+    if (capabilities !== undefined && (!Array.isArray(capabilities) || capabilities.length === 0)) {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} capabilities selector must be a non-empty array`,
+      )
+    }
+    const access = rule.match.access
+    if (access !== undefined && access !== "read" && access !== "write") {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} access selector must be "read" or "write"`,
+      )
+    }
+    const zone = rule.match.zone
+    if (zone !== undefined && zone !== "domain" && zone !== "operational") {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} zone selector must be "domain" or "operational"`,
+      )
+    }
     const required = normalizeEvidenceIds(rule.require, "required")
     const forbidden = normalizeEvidenceIds(rule.forbid, "forbidden")
     const overlap = required.find((id) => forbidden.includes(id))
@@ -195,6 +285,9 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
         ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
         ...(rule.match.tools !== undefined ? { tools: rule.match.tools } : {}),
+        ...(capabilities !== undefined ? { capabilities: Object.freeze([...capabilities]) } : {}),
+        ...(access !== undefined ? { access } : {}),
+        ...(zone !== undefined ? { zone } : {}),
       }),
       require: required,
       forbid: forbidden,
@@ -219,12 +312,27 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
   if (config.invariants !== undefined && typeof config.invariants.executor !== "function") {
     throw new Error("route assurance: invariant executor must be a function")
   }
+  const policy = defineAssurancePolicy(config.policy)
+  const capabilities =
+    config.capabilities !== undefined ? defineCapabilityPolicy(config.capabilities) : undefined
+  // An `access`/`zone` selector is resolved through the capability definitions. Without them it can
+  // only ever match nothing, and a rule that matches nothing does not fail - the route falls past it
+  // to whatever laxer rule comes next. Refuse the config here rather than ship a policy whose
+  // strictest rule is inert.
+  const needDefinitions = rulesNeedingDefinitions(policy)
+  if (needDefinitions.length > 0 && (capabilities?.definitions.length ?? 0) === 0) {
+    throw new Error(
+      `route assurance: rule(s) ${needDefinitions
+        .map((name) => JSON.stringify(name))
+        .join(
+          ", ",
+        )} select on ${CLASS_SELECTOR_KEYS.join("/")}, which needs capability definitions - add a \`capabilities\` policy defining the tokens your routes declare`,
+    )
+  }
   return Object.freeze({
     source: config.source,
-    policy: defineAssurancePolicy(config.policy),
-    ...(config.capabilities !== undefined
-      ? { capabilities: defineCapabilityPolicy(config.capabilities) }
-      : {}),
+    policy,
+    ...(capabilities !== undefined ? { capabilities } : {}),
     ...(config.manifest !== undefined
       ? {
           manifest: Object.freeze({
@@ -239,16 +347,38 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
   })
 }
 
-/** Shared selector semantics for policy rules and framework adapters. */
+/**
+ * Shared selector semantics for policy rules and framework adapters.
+ *
+ * `definitions` is only consulted by the `access`/`zone` selectors; every other selector reads
+ * reflection alone. A caller that omits it while the selector needs it gets no match, so callers that
+ * accept user policy must reject that combination up front - `defineAssuranceConfig` does.
+ */
 export function matchesAssuranceSelector(
-  route: Pick<ReflectedRoute, "method" | "path" | "tool">,
+  route: Pick<ReflectedRoute, "method" | "path" | "tool" | "capabilities">,
   selector: AssuranceRouteSelector,
+  definitions?: ReadonlyMap<string, CapabilityDefinition>,
 ): boolean {
-  const { methods, paths, tools } = selector
+  const { methods, paths, tools, capabilities, access, zone } = selector
   if (methods !== undefined && !methods.includes(route.method as Method)) return false
   if (paths !== undefined && !paths.some((pattern) => routeGlob(pattern).test(route.path)))
     return false
   if (tools !== undefined && (route.tool !== undefined) !== tools) return false
+  const declared = route.capabilities ?? []
+  if (capabilities !== undefined && !capabilities.some((token) => declared.includes(token)))
+    return false
+  if (access !== undefined || zone !== undefined) {
+    // Both constraints must hold for the SAME capability: a route that reads the database and writes
+    // an audit log must not satisfy "writes business state" by combining halves of two tokens.
+    const matched = declared.some((token) => {
+      const definition = definitions?.get(token)
+      if (definition === undefined) return false
+      if (access !== undefined && definition.access !== access) return false
+      if (zone !== undefined && definition.zone !== zone) return false
+      return true
+    })
+    if (!matched) return false
+  }
   return true
 }
 
@@ -256,8 +386,22 @@ export function matchesAssuranceSelector(
 export function evaluateRouteAssurance(
   source: unknown,
   policyInput: AssurancePolicy,
+  options?: AssuranceEvaluationOptions,
 ): AssuranceReport {
   const policy = defineAssurancePolicy(policyInput)
+  const definitions = definitionMap(options?.definitions)
+  // Same reasoning as `defineAssuranceConfig`, repeated for callers that evaluate a bare policy: a
+  // class selector with nothing to resolve against is an inert rule, not a lenient one.
+  const needDefinitions = rulesNeedingDefinitions(policy)
+  if (needDefinitions.length > 0 && definitions.size === 0) {
+    throw new Error(
+      `route assurance: rule(s) ${needDefinitions
+        .map((name) => JSON.stringify(name))
+        .join(
+          ", ",
+        )} select on ${CLASS_SELECTOR_KEYS.join("/")} but no capability definitions were supplied`,
+    )
+  }
   const findings: AssuranceFinding[] = []
   const routes: AssuredRoute[] = []
   const reflected = reflectRoutes(source)
@@ -272,7 +416,9 @@ export function evaluateRouteAssurance(
   }
 
   for (const route of reflected) {
-    const rule = policy.rules.find((candidate) => matchesAssuranceSelector(route, candidate.match))
+    const rule = policy.rules.find((candidate) =>
+      matchesAssuranceSelector(route, candidate.match, definitions),
+    )
     const evidence = route.assurance ?? []
     const evidenceIds = new Set(evidence.map((item) => item.id))
     if (rule === undefined) {