@nifrajs/core 2.1.0 → 2.3.0

package/src/server/sse.ts

@@ -1,12 +1,12 @@
 /**
- * Server-Sent Events — a portable `text/event-stream` response helper.
+ * Server-Sent Events - a portable `text/event-stream` response helper.
  *
  * `sse(c, run)` returns a streaming `Response` a handler can return directly. The `run` callback
  * receives a stream it pushes messages to; the connection stays open until `run`'s promise resolves,
  * it calls `stream.close()`, or the client disconnects (`c.req.signal`). Works on every nifra runtime
- * (Bun, Node via `@nifrajs/node`, Deno, Cloudflare/Vercel edge) — it only uses a Web `ReadableStream`.
+ * (Bun, Node via `@nifrajs/node`, Deno, Cloudflare/Vercel edge) - it only uses a Web `ReadableStream`.
  *
- *   // finite stream — run resolves, the connection closes
+ *   // finite stream - run resolves, the connection closes
  *   app.get("/ticks", (c) => sse(c, async (stream) => {
  *     for (let i = 0; i < 5; i++) {
  *       stream.send({ event: "tick", data: String(i) })
@@ -14,7 +14,7 @@
  *     }
  *   }))
  *
- *   // event-driven — keep `run` pending until the client leaves
+ *   // event-driven - keep `run` pending until the client leaves
  *   app.get("/feed", (c) => sse(c, (stream) => {
  *     const off = bus.subscribe((e) => stream.send({ data: JSON.stringify(e) }))
  *     return new Promise<void>((resolve) =>
@@ -43,11 +43,11 @@ export interface SSEStream {
   send(message: SSEMessage): void
   /** End the stream now. */
   close(): void
-  /** Aborts when the client disconnects — use it to tear down subscriptions/loops. */
+  /** Aborts when the client disconnects - use it to tear down subscriptions/loops. */
   readonly signal: AbortSignal
 }
 
-/** Minimal context shape `sse` needs — the live request, for its client-disconnect signal. */
+/** Minimal context shape `sse` needs - the live request, for its client-disconnect signal. */
 export interface SSEContext {
   readonly req: Request
 }
@@ -63,7 +63,7 @@ export interface SSEInit {
 
 /**
  * The stream handed to an `app.sse()` handler: `send` takes the route's TYPED event payload and
- * serializes it (JSON) into the SSE `data:` field — the compile-time half of the `sse` contract.
+ * serializes it (JSON) into the SSE `data:` field - the compile-time half of the `sse` contract.
  */
 export interface TypedSSEStream<Event> {
   /** Send one typed event. `init` sets the optional SSE frame fields (`event`, `id`, `retry`). */
@@ -72,7 +72,7 @@ export interface TypedSSEStream<Event> {
   comment(text: string): void
   /** End the stream now. */
   close(): void
-  /** Aborts when the client disconnects — use it to tear down subscriptions/loops. */
+  /** Aborts when the client disconnects - use it to tear down subscriptions/loops. */
   readonly signal: AbortSignal
 }
 
@@ -93,7 +93,7 @@ export function typedSSEStream<Event>(stream: SSEStream): TypedSSEStream<Event>
 const CRLF = /[\r\n]/g
 const LINE_SPLIT = /\r\n|\r|\n/
 
-/** `event:`/`id:`/`comment` must be single-line — stripping CR/LF prevents SSE frame injection. */
+/** `event:`/`id:`/`comment` must be single-line - stripping CR/LF prevents SSE frame injection. */
 function formatMessage(m: SSEMessage): string {
   let frame = ""
   if (m.comment !== undefined) frame += `: ${m.comment.replace(CRLF, "")}\n`
@@ -139,7 +139,7 @@ export function sse(
         try {
           controller.close()
         } catch {
-          // Already closed by the runtime's cancel() — safe to ignore.
+          // Already closed by the runtime's cancel() - safe to ignore.
         }
       }
       const stream: SSEStream = {
@@ -180,7 +180,7 @@ export function sse(
       })
     },
     cancel() {
-      // Consumer/runtime canceled (client gone) — pending sends become no-ops.
+      // Consumer/runtime canceled (client gone) - pending sends become no-ops.
       closed = true
       teardown()
     },

package/src/server/webhook.ts

@@ -1,11 +1,11 @@
 /**
- * Webhook signature verification — **read the raw body, verify the HMAC, *then* parse**. A handler
+ * Webhook signature verification - **read the raw body, verify the HMAC, *then* parse**. A handler
  * that `JSON.parse`s a webhook before checking the signature is trusting an unauthenticated payload;
  * this reads the body bounded (DoS guard, shared with `c.boundedBody`) and verifies before handing
  * back the raw text for the handler to parse with its own schema.
  *
  * Verification is **constant-time**: the provider's signature is fed to `crypto.subtle.verify`
- * (WebCrypto), which checks the HMAC without a byte-by-byte string compare — so a wrong signature
+ * (WebCrypto), which checks the HMAC without a byte-by-byte string compare - so a wrong signature
  * can't be discovered through timing. WebCrypto-only, so it runs on Bun / Node / Deno / workerd.
  *
  * Presets cover Stripe (`t=…,v1=…` with a replay-window check) and GitHub (`sha256=…`); `generic`
@@ -15,7 +15,7 @@ import { requireSecretBytes } from "../internal/secret.ts"
 import { readBoundedBytes } from "./body.ts"
 
 const TEXT = new TextEncoder()
-const DEFAULT_MAX_BYTES = 1024 * 1024 // 1 MiB — webhook payloads are small; cap the raw read.
+const DEFAULT_MAX_BYTES = 1024 * 1024 // 1 MiB - webhook payloads are small; cap the raw read.
 const DEFAULT_TOLERANCE_SECONDS = 300 // 5-min replay window for timestamped schemes (Stripe's default).
 
 export type WebhookProvider = "stripe" | "github" | "generic"
@@ -136,7 +136,7 @@ function parseStripeHeader(value: string): { t: number; v1: string[] } | null {
 
 /**
  * Verify a webhook request's signature and return its raw payload. Reads `req.body` (bounded), so the
- * body is consumed — parse the returned `payload`, don't re-read the request.
+ * body is consumed - parse the returned `payload`, don't re-read the request.
  *
  * @param secret the signing secret (or an array, to accept either during a secret rotation).
  *
@@ -189,7 +189,7 @@ export async function verifyWebhook(
       }
     }
     if (!matched) return { ok: false, reason: "invalid_signature" }
-    // The signature covers `t`, so `t` is authentic once matched — now enforce the replay window.
+    // The signature covers `t`, so `t` is authentic once matched - now enforce the replay window.
     const now = options.now ?? Math.floor(Date.now() / 1000)
     const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS
     if (Math.abs(now - parsed.t) > tolerance) {

package/src/server/websocket.ts

@@ -1,10 +1,10 @@
 /**
- * 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.
  */
@@ -33,22 +33,22 @@ type WsMessageInput<Schema extends StandardSchemaV1 | undefined> = Schema extend
 export interface NifraWebSocket<Data = unknown> {
   /** Send a text (`string`) or binary (`ArrayBuffer`/typed-array) frame. No-op once closed. */
   send(data: string | ArrayBufferView | ArrayBuffer): void
-  /** Close the connection (optional code 1000–4999 + short reason). */
+  /** Close the connection (optional code 1000-4999 + short reason). */
   close(code?: number, reason?: string): void
   /** `WebSocket.readyState` (0 CONNECTING · 1 OPEN · 2 CLOSING · 3 CLOSED). */
   readonly readyState: number
-  /** Join a pub/sub topic — `app.publish(topic, data)` then reaches this connection. Idempotent. */
+  /** Join a pub/sub topic - `app.publish(topic, data)` then reaches this connection. Idempotent. */
   subscribe(topic: string): void
   /** Leave a pub/sub topic. Idempotent. (All topics are dropped automatically on close.) */
   unsubscribe(topic: string): void
-  /** Per-connection state — seeded by `upgrade()`, mutable for the connection's lifetime. */
+  /** Per-connection state - seeded by `upgrade()`, mutable for the connection's lifetime. */
   data: Data
   /** Escape hatch to the runtime's native socket (Bun `ServerWebSocket`, Web `WebSocket`, `ws`). */
   readonly raw: unknown
 }
 
 /**
- * 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`.
@@ -76,12 +76,12 @@ export class TopicRegistry {
     const subs = this.topics.get(topic)
     if (subs !== undefined) {
       subs.delete(ws)
-      if (subs.size === 0) this.topics.delete(topic) // reclaim empty topics — no unbounded growth
+      if (subs.size === 0) 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: NifraWebSocket): void {
     const mine = this.memberships.get(ws)
     if (mine === undefined) return
@@ -110,7 +110,7 @@ export class TopicRegistry {
 }
 
 /**
- * The request-context subset the `upgrade()` guard sees — the same lazy accessors a route handler's
+ * The request-context subset the `upgrade()` guard sees - the same lazy accessors a route handler's
  * `c` has (cookies/headers/env are read straight off the upgrade request). Structurally a slice of the
  * core `RawContext`, so the real context object satisfies it.
  */
@@ -134,7 +134,7 @@ export interface WebSocketHandler<
   Send extends StandardSchemaV1 | undefined = undefined,
 > {
   /**
-   * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not
+   * Cross-site WebSocket hijacking (CSWSH) guard - checked BEFORE `upgrade()`. A browser does not
    * apply CORS to WebSocket handshakes and DOES send the page's cookies, so without an Origin check
    * any site can open an authenticated socket to your app. Set this to lock the route to known
    * origins: a string allow-list (exact `Origin` header match) or a predicate. A request whose
@@ -145,11 +145,11 @@ export interface WebSocketHandler<
    * whose host differs from the request's) is rejected with `403`. Non-browser clients (no `Origin`) and
    * same-origin browsers pass. Set this to allow specific cross-origin clients, or `() => true` for a
    * genuinely public socket. Non-browser clients can spoof `Origin`, so this is a browser-CSWSH defense,
-   * not authentication — pair it with auth in `upgrade()`.
+   * not authentication - pair it with auth in `upgrade()`.
    */
   allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean)
   /**
-   * Runs in the HTTP request context **before** the upgrade (and after {@link allowedOrigins}) — the
+   * Runs in the HTTP request context **before** the upgrade (and after {@link allowedOrigins}) - the
    * place to authenticate or rate-limit. Return the initial per-connection `data` (→ `ws.data`), or a
    * `Response` to **reject** the upgrade (the client never connects). Omit to accept with
    * `data: undefined`. A thrown error rejects with a flat 500.
@@ -188,10 +188,10 @@ export interface WebSocketHandler<
 }
 
 /**
- * The outcome of `app.resolveWebSocketUpgrade(req)` — for serving adapters:
- * - `pass` — not a WS upgrade for a registered WS route; handle as a normal HTTP request.
- * - `reject` — a WS route matched but `upgrade()` rejected (or the path was malformed); return `response`.
- * - `upgrade` — perform the runtime upgrade, then dispatch the native socket's events to `handler`,
+ * The outcome of `app.resolveWebSocketUpgrade(req)` - for serving adapters:
+ * - `pass` - not a WS upgrade for a registered WS route; handle as a normal HTTP request.
+ * - `reject` - a WS route matched but `upgrade()` rejected (or the path was malformed); return `response`.
+ * - `upgrade` - perform the runtime upgrade, then dispatch the native socket's events to `handler`,
  *   seeding `ws.data` with `data`.
  */
 export type WebSocketUpgradeOutcome =
@@ -201,7 +201,7 @@ export type WebSocketUpgradeOutcome =
       readonly kind: "upgrade"
       readonly handler: WebSocketHandler
       readonly data: unknown
-      /** The app's pub/sub registry — the adapter wires `ws.subscribe` + close-cleanup to it. */
+      /** The app's pub/sub registry - the adapter wires `ws.subscribe` + close-cleanup to it. */
       readonly pubsub: TopicRegistry
       /** The installed runtime's {@link attachWebSocket}, carried on the outcome so an adapter can wire
        * a standard socket without a static import of the WS implementation (which would defeat the
@@ -218,7 +218,7 @@ export type WsAttach = (
 ) => NifraWebSocket
 
 /**
- * A standard server-side `WebSocket` — the half returned by Deno's `Deno.upgradeWebSocket` and the
+ * A standard server-side `WebSocket` - the half returned by Deno's `Deno.upgradeWebSocket` and the
  * Workers `WebSocketPair`. {@link attachWebSocket} wires one to a nifra handler, so the Deno and Workers
  * bridges share all the dispatch/normalization/error-isolation logic (only the upgrade call differs).
  */
@@ -235,14 +235,14 @@ function toBinary(raw: unknown): Uint8Array {
   if (raw instanceof Uint8Array) return raw
   if (raw instanceof ArrayBuffer) 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(
@@ -269,7 +269,7 @@ export function attachWebSocket(
       const r = handler.error(ws, error)
       if (r instanceof Promise) r.catch(() => {})
     } catch {
-      /* the error handler itself failed — last resort, swallow */
+      /* the error handler itself failed - last resort, swallow */
     }
   }
   const safe = (call: () => MaybePromise<void>): void => {
@@ -306,7 +306,7 @@ export function attachWebSocket(
 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/src/server/ws-bun.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, WebSocketData, WebSocketHandler } from "./websocket.ts"
@@ -16,7 +16,7 @@ export interface BunWsData {
   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
@@ -80,7 +80,7 @@ function dispatchWsCallback(
   }
 }
 
-/** 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: TopicRegistry): BunWsHandlers {
   return {

package/src/server.ts

@@ -10,6 +10,7 @@
 
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export { isSameOriginRequest } from "./internal/same-origin.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
 export type {
   InferInput,
@@ -35,6 +36,13 @@ export {
   signValue,
   unsignValue,
 } from "./server/cookies.ts"
+export {
+  type DurableObjectNamespaceLike,
+  type ExecutionContext,
+  type ScheduledController,
+  type ScheduledHandler,
+  toFetchHandler,
+} from "./server/edge.ts"
 export {
   commonSecretPatterns,
   jsonLogger,
@@ -49,11 +57,9 @@ export {
   type AdmissionController,
   type AdmissionDecision,
   type AnyServer,
-  type DurableObjectNamespaceLike,
   defineIdentityPlugin,
   definePlugin,
   defineRouterPlugin,
-  type ExecutionContext,
   type Handler,
   type IdentityPlugin,
   type McpPromptDescriptor,
@@ -67,13 +73,10 @@ export {
   type ResponseFinalization,
   type RouteDescriptor,
   type RunningServer,
-  type ScheduledController,
-  type ScheduledHandler,
   Server,
   type ServerOptions,
   server,
   type ToolAnnotations,
-  toFetchHandler,
 } from "./server/server.ts"
 export type {
   SSEContext,

package/src/transport-codec.ts

@@ -19,12 +19,31 @@ export interface TransportCodec {
 }
 
 export class TransportCodecError extends TypeError {
-  constructor(message: string) {
-    super(message)
+  constructor(message: string, options?: ErrorOptions) {
+    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<T>(decode: () => T, message: string): T {
+  try {
+    return decode()
+  } catch (cause) {
+    if (cause instanceof TransportCodecError) throw cause
+    throw new TransportCodecError(message, { cause })
+  }
+}
+
 function maxBytesOf(options: TransportDecodeOptions): number {
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
@@ -171,15 +190,26 @@ function appendVary(current: string | null, name: string): string {
   return values.includes(name.toLowerCase()) ? current : `${current}, ${name}`
 }
 
-async function readBoundedText(
+/**
+ * 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: Response,
   options: TransportDecodeOptions,
-): Promise<string> {
+): Promise<Uint8Array> {
   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 ""
+  if (response.body === null) return new Uint8Array(0)
   const reader = response.body.getReader()
   const chunks: Uint8Array[] = []
   let total = 0
@@ -203,7 +233,18 @@ async function readBoundedText(
     bytes.set(chunk, offset)
     offset += chunk.byteLength
   }
-  return new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  return bytes
+}
+
+async function readBoundedText(
+  response: Response,
+  options: TransportDecodeOptions,
+): Promise<string> {
+  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(
@@ -213,7 +254,11 @@ export async function decodeTransportResponse(
 ): Promise<unknown> {
   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}`,
+  )
 }
 
 interface TransportFrame {
@@ -235,7 +280,10 @@ export function decodeTransportFrame(
   options: TransportDecodeOptions = {},
 ): unknown {
   assertBounded(frame, options)
-  const envelope = JSON.parse(frame) as Partial<TransportFrame>
+  const envelope = decodeOrThrow(
+    () => JSON.parse(frame),
+    "malformed transport frame",
+  ) as Partial<TransportFrame>
   if (
     envelope === null ||
     typeof envelope !== "object" ||
@@ -245,6 +293,11 @@ export function decodeTransportFrame(
   ) {
     throw new TransportCodecError("malformed transport frame")
   }
-  assertBounded(envelope.payload, options)
-  return registry.byIdentity(envelope.codec, envelope.version as number).decode(envelope.payload)
+  const payload = envelope.payload
+  assertBounded(payload, options)
+  const codec = registry.byIdentity(envelope.codec, envelope.version as number)
+  return decodeOrThrow(
+    () => codec.decode(payload),
+    `malformed transport frame payload for codec ${codec.id}@${codec.version}`,
+  )
 }