@nifrajs/core 4.0.2 → 5.0.0

package/src/server/sse.ts

@@ -39,7 +39,10 @@ export interface SSEMessage {
 
 /** The stream handed to the `run` callback. */
 export interface SSEStream {
-  /** Enqueue an event frame. No-op once the stream is closed. */
+  /**
+   * Enqueue an event frame. No-op once the stream is closed, including after a client that fell
+   * more than `maxBufferedBytes` behind was dropped.
+   */
   send(message: SSEMessage): void
   /** End the stream now. */
   close(): void
@@ -59,8 +62,17 @@ export interface SSEInit {
   readonly headers?: ConstructorParameters<typeof Headers>[0]
   /** Send a `: ` comment ping every N ms so idle proxies don't drop the connection. */
   readonly keepAlive?: number
+  /**
+   * Bytes of sent events one client may leave unread, default 1 MiB. Past it the client is dropped:
+   * `signal` aborts, the queued frames are released, and later sends are no-ops, so a reader that
+   * stalls cannot hold server memory without limit. Raise it for a burst larger than this sent before
+   * the client can read; `Infinity` turns the limit off.
+   */
+  readonly maxBufferedBytes?: number
 }
 
+const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024
+
 /**
  * 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.
@@ -111,6 +123,9 @@ export function sse(
   run: (stream: SSEStream) => void | Promise<void>,
   init: SSEInit = {},
 ): Response {
+  const maxBuffered = init.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES
+  if (!(maxBuffered >= 0))
+    throw new RangeError("sse maxBufferedBytes must be a non-negative number")
   const encoder = new TextEncoder()
   const requestSignal: AbortSignal | undefined = c.req?.signal
   // The producer's signal also aborts when the runtime cancels the body: a writer that finds the
@@ -127,66 +142,80 @@ export function sse(
     }
   }
 
-  const body = new ReadableStream<Uint8Array>({
-    start(controller) {
-      const close = (): void => {
-        if (closed) return
-        closed = true
-        teardown()
-        try {
-          controller.close()
-        } catch {
-          // Already closed by the runtime's cancel() - safe to ignore.
+  const body = new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        const close = (): void => {
+          if (closed) return
+          closed = true
+          teardown()
+          try {
+            controller.close()
+          } catch {
+            // Already closed by the runtime's cancel() - safe to ignore.
+          }
         }
-      }
-      const stream: SSEStream = {
-        send(message) {
-          if (!closed) controller.enqueue(encoder.encode(formatMessage(message)))
-        },
-        close,
-        signal: stopped.signal,
-      }
-
-      // Stop the moment the client goes away.
-      if (requestSignal !== undefined) {
-        if (requestSignal.aborted) {
-          stopped.abort()
-          close()
-          return
+        const stream: SSEStream = {
+          send(message) {
+            if (closed) return
+            // The queue only shrinks as the runtime writes to the socket, so a backlog past the cap
+            // is a client that stopped reading. Erroring the body releases the queue and the socket.
+            if ((controller.desiredSize ?? 0) < 0) {
+              closed = true
+              teardown()
+              const reason = new Error("sse_client_too_slow")
+              stopped.abort(reason)
+              controller.error(reason)
+              return
+            }
+            controller.enqueue(encoder.encode(formatMessage(message)))
+          },
+          close,
+          signal: stopped.signal,
+        }
+
+        // Stop the moment the client goes away.
+        if (requestSignal !== undefined) {
+          if (requestSignal.aborted) {
+            stopped.abort()
+            close()
+            return
+          }
+          onAbort = () => {
+            stopped.abort()
+            close()
+          }
+          requestSignal.addEventListener("abort", onAbort, { once: true })
         }
-        onAbort = () => {
-          stopped.abort()
-          close()
+
+        if (init.keepAlive !== undefined && init.keepAlive > 0) {
+          heartbeat = setInterval(() => stream.send({ comment: "" }), init.keepAlive)
+          // Don't let the ping keep a Node process alive on its own.
+          ;(heartbeat as { unref?: () => void }).unref?.()
         }
-        requestSignal.addEventListener("abort", onAbort, { once: true })
-      }
-
-      if (init.keepAlive !== undefined && init.keepAlive > 0) {
-        heartbeat = setInterval(() => stream.send({ comment: "" }), init.keepAlive)
-        // Don't let the ping keep a Node process alive on its own.
-        ;(heartbeat as { unref?: () => void }).unref?.()
-      }
-      // An async IIFE so a synchronous throw in `run` becomes a rejection we can surface.
-      ;(async () => {
-        await run(stream)
-      })().then(close, (err: unknown) => {
-        if (closed) return
+        // An async IIFE so a synchronous throw in `run` becomes a rejection we can surface.
+        ;(async () => {
+          await run(stream)
+        })().then(close, (err: unknown) => {
+          if (closed) return
+          closed = true
+          teardown()
+          try {
+            controller.error(err instanceof Error ? err : new Error("sse_producer_failed"))
+          } catch {
+            // Stream already torn down.
+          }
+        })
+      },
+      cancel() {
+        // Consumer/runtime canceled (client gone) - pending sends become no-ops.
         closed = true
         teardown()
-        try {
-          controller.error(err instanceof Error ? err : new Error("sse_producer_failed"))
-        } catch {
-          // Stream already torn down.
-        }
-      })
-    },
-    cancel() {
-      // Consumer/runtime canceled (client gone) - pending sends become no-ops.
-      closed = true
-      teardown()
-      stopped.abort()
+        stopped.abort()
+      },
     },
-  })
+    { highWaterMark: maxBuffered, size: (chunk) => chunk?.byteLength ?? 0 },
+  )
 
   const headers = new Headers(init.headers)
   headers.set("content-type", "text/event-stream; charset=utf-8")

package/src/server/transport-lane.ts

@@ -27,7 +27,13 @@ export interface TransportRuntime {
 }
 
 export interface TransportCodecsOptions {
-  /** Maximum encoded request bytes. Keep aligned with `server({ maxBodyBytes })`. */
+  /**
+   * Maximum encoded request bytes. Default 1,000,000. Keep aligned with `server({ maxBodyBytes })`.
+   *
+   * The plugin decodes a codec body in an `onRequest` hook, before routing, so a route's own
+   * `bodyLimit` and its `authenticate()` stages run only after the decode. This cap is the only
+   * bound on that work: set it to the largest codec body any route should accept.
+   */
   readonly maxBytes?: number
   /**
    * Prototype-poisoning policy for decoded request bodies, mirroring

package/src/server/webhook.ts

@@ -19,14 +19,17 @@ const DEFAULT_MAX_BYTES = 1024 * 1024 // 1 MiB - webhook payloads are small; cap
 const DEFAULT_TOLERANCE_SECONDS = 300 // 5-min replay window for timestamped schemes (Stripe's default).
 
 export type WebhookProvider = "stripe" | "github" | "generic"
-export type SignatureEncoding = "hex" | "base64"
+export type SignatureEncoding = "hex" | "base64" | "base64url"
 
 export interface VerifyWebhookOptions {
   /** Known-provider preset. Default `"generic"` (which requires {@link header}). */
   readonly provider?: WebhookProvider
   /** Header carrying the signature. Required for `generic`; overrides the preset otherwise. */
   readonly header?: string
-  /** How the signature is encoded in the header. Default `"hex"`. */
+  /**
+   * How the signature is encoded in the header. Default `"hex"`. `"base64url"` accepts the padded and
+   * unpadded forms and nothing outside its alphabet.
+   */
   readonly encoding?: SignatureEncoding
   /** A prefix stripped from the header value before decoding, e.g. `"sha256="`. */
   readonly prefix?: string
@@ -96,10 +99,26 @@ const fromBase64 = (value: string): Uint8Array<ArrayBuffer> | null => {
   }
 }
 
+const BASE64URL = /^[A-Za-z0-9_-]+={0,2}$/
+
+const fromBase64Url = (value: string): Uint8Array<ArrayBuffer> | null => {
+  if (!BASE64URL.test(value)) return null
+  const unpadded = value.replace(/=+$/, "")
+  // Padding only ever completes the last quartet; a lone trailing character encodes no byte.
+  if (unpadded.length % 4 === 1) return null
+  if (unpadded.length !== value.length && value.length % 4 !== 0) return null
+  return fromBase64(unpadded.replaceAll("-", "+").replaceAll("_", "/"))
+}
+
 const decodeSignature = (
   value: string,
   encoding: SignatureEncoding,
-): Uint8Array<ArrayBuffer> | null => (encoding === "hex" ? fromHex(value) : fromBase64(value))
+): Uint8Array<ArrayBuffer> | null =>
+  encoding === "hex"
+    ? fromHex(value)
+    : encoding === "base64url"
+      ? fromBase64Url(value)
+      : fromBase64(value)
 
 /** True iff `sig` is a valid HMAC-SHA256 of `payload` under any of `keys` (constant-time per check). */
 async function verifyAny(

package/src/server/websocket.ts

@@ -18,6 +18,7 @@ import type {
 import { validateStandard } from "../schema/standard.ts"
 import { decodeTransportFrame, type TransportCodecRegistry } from "../transport-codec.ts"
 import { guardDecodedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
+import { isResponseResult } from "./runtime-core.ts"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -133,6 +134,7 @@ export interface WebSocketHandler<
   Env = unknown,
   Schema extends StandardSchemaV1 | undefined = undefined,
   Send extends StandardSchemaV1 | undefined = undefined,
+  Extra = unknown,
 > {
   /**
    * Cross-site WebSocket hijacking (CSWSH) guard - checked BEFORE `upgrade()`. A browser does not
@@ -150,12 +152,22 @@ export interface WebSocketHandler<
    */
   allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean)
   /**
-   * 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.
+   * The capability ids this socket's code may reach, exactly as an HTTP route's `capabilities`.
+   * `nifra capabilities check` compares them with the effects reachable from the module that
+   * registers the socket. The handshake context carries the guard, so a runtime beacon in `upgrade()`
+   * (or one that keeps `c`) fails closed on an undeclared capability.
    */
-  upgrade?(c: WebSocketContext<Env>): MaybePromise<Data | Response>
+  capabilities?: readonly string[]
+  /**
+   * Runs in the HTTP request context **before** the upgrade, last in the chain an HTTP `GET` to the
+   * same path runs: after {@link allowedOrigins}, then the `authenticate()` stages, `derive`s and
+   * `beforeHandle`s registered before this route, any of which can refuse the handshake. `c` carries
+   * what they derived. Return the initial per-connection `data` (→ `ws.data`), or a `Response` or
+   * `status(...)` to **reject** the upgrade (the client never connects). Omit to accept with
+   * `data: undefined`. A thrown `Response` rejects with it; any other throw goes to the route's
+   * `onError` hooks, then a flat 500.
+   */
+  upgrade?(c: WebSocketContext<Env> & Extra): MaybePromise<Data | Response>
   /**
    * Contract-first messages: a Standard Schema (`t`, zod, valibot, …) validating each **inbound** frame.
    * Text frames are parsed as JSON first. When set, `message` receives the validated, typed value; a
@@ -444,6 +456,33 @@ export function createWebSocketSender(
  * `protoPoisoning` is the app's body policy: a frame with a `__proto__` key gets what a JSON body
  * with one gets, and under `"reject"` reads as invalid JSON.
  */
+/** `upgrade()`'s acceptance, wrapped so a handshake's route chain tells it from an early result such
+ * as a guard's `Response` or a rejected auth stage. */
+class HandshakeAccepted {
+  readonly data: unknown
+  constructor(data: unknown) {
+    this.data = data
+  }
+}
+
+const acceptHandshake = (value: unknown): unknown =>
+  value instanceof Response || isResponseResult(value) ? value : new HandshakeAccepted(value)
+
+/** The step a handshake's route chain ends in: the route's `upgrade()`, or an acceptance without data. */
+export function handshakeUpgradeStep(
+  handler: WebSocketHandler,
+): (ctx: WebSocketContext) => unknown {
+  return (ctx) => {
+    const data = handler.upgrade?.(ctx)
+    return data instanceof Promise ? data.then(acceptHandshake) : acceptHandshake(data)
+  }
+}
+
+/** The acceptance a handshake's route chain ended in, or `undefined` when the chain refused it. */
+export function acceptedHandshake(result: unknown): { readonly data: unknown } | undefined {
+  return result instanceof HandshakeAccepted ? result : undefined
+}
+
 export function wrapWebSocketMessageValidation(
   handler: WebSocketHandler,
   protoPoisoning: ProtoPoisoning = "reject",

package/src/server/ws-hook.ts

@@ -13,6 +13,7 @@ import type {
   NifraWebSocket,
   StandardWebSocket,
   TopicRegistry,
+  WebSocketContext,
   WebSocketHandler,
 } from "./websocket.ts"
 
@@ -29,6 +30,10 @@ export interface BunWsHandlers {
 export interface WsRuntime {
   /** `wrapWebSocketMessageValidation` - applied once at `app.ws()` registration. */
   wrapHandler(handler: WebSocketHandler, protoPoisoning: ProtoPoisoning): WebSocketHandler
+  /** `handshakeUpgradeStep` - the step a handshake's route chain ends in. */
+  upgradeStep(handler: WebSocketHandler): (ctx: WebSocketContext) => unknown
+  /** `acceptedHandshake` - the acceptance a chain ended in, `undefined` when it refused. */
+  accepted(result: unknown): { readonly data: unknown } | undefined
   /** One in-process pub/sub registry per app (backs `ws.subscribe` + `app.publish`). */
   createTopics(): TopicRegistry
   /** The Bun `websocket` config for `listen()` when the app has WS routes. `nativePubsub` routes

package/src/server.ts

@@ -42,6 +42,8 @@ export {
   type AuthHeaders,
   type AuthMaybePromise,
   authenticated,
+  isAuthenticatedRequest,
+  markAuthenticatedRequest,
   rejected,
 } from "./server/auth.ts"
 export type {
@@ -104,6 +106,7 @@ export type {
   RouteInfoFor,
 } from "./server/registry.ts"
 export { replacedRequestOf } from "./server/request-lineage.ts"
+export { writableResponse } from "./server/respond.ts"
 export {
   type PlainRender,
   type ResponseResult,
@@ -115,6 +118,7 @@ export {
   type AdmissionDecision,
   type AnyServer,
   type ContextPlugin,
+  type DeclaredMountRoute,
   type DefinePluginResult,
   defineContextPlugin,
   defineIdentityPlugin,
@@ -137,6 +141,7 @@ export {
   type NodeResponseHook,
   type NodeServeOutcome,
   type OnRequestResult,
+  type OpaqueMountDeclaration,
   type PluginTypeCollapsed,
   type PromptArgument,
   type PromptMessage,

package/src/single-copy.ts

@@ -77,6 +77,14 @@ export const IDENTITY_SENSITIVE_PACKAGES: readonly string[] = [
 
 /** Files a redirect may rewrite. Everything else in a package (json, css, wasm) loads unchanged. */
 const REDIRECTABLE = /\.(?:m|c)?[jt]sx?$/
+
+/** The loader a {@link REDIRECTABLE} file is parsed with. `.ts` is never `tsx`: under JSX rules a
+ * generic arrow (`<T>(x: T) => x`) reads as an unclosed element and swallows the file. */
+function sourceLoader(path: string): "js" | "jsx" | "ts" | "tsx" {
+  if (path.endsWith(".tsx")) return "tsx"
+  if (path.endsWith(".jsx")) return "jsx"
+  return /\.[mc]?ts$/.test(path) ? "ts" : "js"
+}
 /** Runaway guards. A real `node_modules` top level is hundreds of entries, a repo walk is a few. */
 const MAX_SCANNED_ENTRIES = 4_096
 const MAX_ANCESTOR_DIRS = 16
@@ -411,6 +419,17 @@ const declaredNames = (root: string, declared: readonly string[]): readonly stri
   return [...names].sort()
 }
 
+/**
+ * The installed package names the app's declaration covers: each exact name, and each package
+ * installed under a declared `@scope/*`. Empty without a declaration. A bundler that pins packages by
+ * name, such as Vite's `resolve.dedupe`, takes this list.
+ */
+export function singleCopyPackageNames(cwd: string): readonly string[] {
+  const root = realpathOrSelf(resolve(cwd))
+  const declared = readSingleCopyDeclaration(root)
+  return declared === undefined ? [] : declaredNames(root, declared)
+}
+
 /**
  * Work out which foreign copies exist and which of them may be redirected.
  *
@@ -569,7 +588,7 @@ export function singleCopyPlugin(options: SingleCopyOptions = {}): SingleCopyPlu
         // A runtime `onLoad` must always return an object - returning nothing fails the load rather
         // than falling through to the default. Hand back the file as it was, at its own path, so its
         // relative imports keep resolving exactly as they would have.
-        return { contents: readFileSync(args.path, "utf8"), loader: "js" }
+        return { contents: readFileSync(args.path, "utf8"), loader: sourceLoader(args.path) }
       })
     },
   }

package/src/tool-contract.ts

@@ -461,6 +461,25 @@ export async function executeTool<Input, Output>(
       ...(tool.cost === undefined ? {} : { cost: tool.cost }),
     })
   }
+  // A failed abandon leaves the key reserved until its lease lapses, as a failed renewal does; the
+  // call's own outcome still stands.
+  const abandon = async (): Promise<void> => {
+    if (reservation === undefined) return
+    try {
+      await options.idempotency?.abandon(reservationInput(reservation))
+    } catch {}
+  }
+  // Once the executor has run, the reservation is never released: a retry would repeat a side effect
+  // that may have committed. A store that throws on completion counts as one that refused it.
+  let executed = false
+  const complete = async (): Promise<boolean> => {
+    if (reservation === undefined) return true
+    try {
+      return (await options.idempotency?.complete(reservationInput(reservation))) === true
+    } catch {
+      return false
+    }
+  }
   type ToolCallOutcome =
     | { readonly ok: true; readonly dryRun: boolean; readonly output?: Output }
     | { readonly ok: false; readonly dryRun: boolean; readonly error: ToolError }
@@ -625,22 +644,19 @@ export async function executeTool<Input, Output>(
     record("idempotency", tool.idempotency === undefined ? "skipped" : "passed")
 
     if (options.budget !== undefined && !options.budget.consume(tool.cost)) {
-      if (reservation !== undefined)
-        await options.idempotency?.abandon(reservationInput(reservation))
+      await abandon()
       record("budget", "denied", "budget_exceeded")
       return finish({ ok: false, dryRun, error: { code: "budget_exceeded", stage: "budget" } })
     }
     record("budget", tool.cost === undefined ? "skipped" : "passed")
 
     if (signal.aborted) {
-      if (reservation !== undefined)
-        await options.idempotency?.abandon(reservationInput(reservation))
+      await abandon()
       record("execution", "denied", "cancelled")
       return finish({ ok: false, dryRun, error: { code: "cancelled", stage: "execution" } })
     }
     if (dryRun) {
-      if (reservation !== undefined)
-        await options.idempotency?.abandon(reservationInput(reservation))
+      await abandon()
       record("execution", "dry-run")
       return finish({ ok: true, dryRun })
     }
@@ -651,21 +667,19 @@ export async function executeTool<Input, Output>(
       dryRun,
       ...(tool.policy === undefined ? {} : { policy: tool.policy }),
     })
+    executed = true
     record("execution", "committed")
     const validatedOutput = await validateStandard(tool.output, output)
     if (!validatedOutput.ok) {
       // The executor has already run. Keep the reservation completed even when its return shape is
       // invalid, so a caller cannot retry and duplicate a side effect that may have committed.
-      if (reservation !== undefined) {
-        const completed = await options.idempotency?.complete(reservationInput(reservation))
-        if (completed !== true) {
-          record("idempotency", "failed", "idempotency_capacity")
-          return finish({
-            ok: false,
-            dryRun,
-            error: { code: "idempotency_capacity", stage: "idempotency" },
-          })
-        }
+      if (!(await complete())) {
+        record("idempotency", "failed", "idempotency_capacity")
+        return finish({
+          ok: false,
+          dryRun,
+          error: { code: "idempotency_capacity", stage: "idempotency" },
+        })
       }
       record("output", "failed", "output_invalid")
       return finish({
@@ -675,20 +689,17 @@ export async function executeTool<Input, Output>(
       })
     }
     record("output", "passed")
-    if (reservation !== undefined) {
-      const completed = await options.idempotency?.complete(reservationInput(reservation))
-      if (completed !== true) {
-        record("idempotency", "failed", "idempotency_capacity")
-        return finish({
-          ok: false,
-          dryRun,
-          error: { code: "idempotency_capacity", stage: "idempotency" },
-        })
-      }
+    if (!(await complete())) {
+      record("idempotency", "failed", "idempotency_capacity")
+      return finish({
+        ok: false,
+        dryRun,
+        error: { code: "idempotency_capacity", stage: "idempotency" },
+      })
     }
     return finish({ ok: true, dryRun, output: validatedOutput.value })
   } catch (error) {
-    if (reservation !== undefined) await options.idempotency?.abandon(reservationInput(reservation))
+    if (!executed) await abandon()
     const code = signal.aborted || isAbortError(error) ? "cancelled" : "execution_failed"
     record("execution", "failed", code)
     return finish({ ok: false, dryRun, error: { code, stage: "execution" } })
@@ -788,18 +799,35 @@ export function toolHttpResult<Output>(result: ToolCallResult<Output>): Response
       ? { ok: true, output: result.output, dryRun: result.dryRun, evidence: result.evidence }
       : { ok: false, error: result.error, dryRun: result.dryRun, evidence: result.evidence },
   )
-  const status = result.ok
-    ? 200
-    : result.error.code === "input_invalid"
-      ? 422
-      : result.error.code === "approval_required" ||
-          result.error.code === "approval_denied" ||
-          result.error.code === "capability_denied"
-        ? 403
-        : result.error.code === "budget_exceeded"
-          ? 429
-          : 500
-  return new Response(body, { status, headers: { "content-type": "application/json" } })
+  const headers: Record<string, string> = { "content-type": "application/json" }
+  const status = result.ok ? 200 : toolErrorStatus(result.error.code)
+  // The idempotency refusals answer as the HTTP idempotency lane does, a retry included.
+  if (!result.ok && retryableIdempotency(result.error.code)) headers["retry-after"] = "1"
+  return new Response(body, { status, headers })
+}
+
+function retryableIdempotency(code: ToolError["code"]): boolean {
+  return code === "idempotency_in_flight" || code === "idempotency_capacity"
+}
+
+function toolErrorStatus(code: ToolError["code"]): number {
+  switch (code) {
+    case "input_invalid":
+      return 422
+    case "approval_required":
+    case "approval_denied":
+    case "capability_denied":
+      return 403
+    case "idempotency_duplicate":
+    case "idempotency_in_flight":
+      return 409
+    case "budget_exceeded":
+      return 429
+    case "idempotency_capacity":
+      return 503
+    default:
+      return 500
+  }
 }
 
 export function toolInputJsonSchema<Input, Output>(

package/src/ws.ts

@@ -21,7 +21,9 @@ import { INSTALL_WS } from "./server/install.ts"
 import type { IdentityPlugin } from "./server/plugin.ts"
 import type { AnyServer } from "./server/server.ts"
 import {
+  acceptedHandshake,
   attachWebSocket,
+  handshakeUpgradeStep,
   TopicRegistry,
   wrapWebSocketMessageValidation,
 } from "./server/websocket.ts"
@@ -30,6 +32,8 @@ import type { WsRuntime } from "./server/ws-hook.ts"
 
 const WS_RUNTIME: WsRuntime = {
   wrapHandler: wrapWebSocketMessageValidation,
+  upgradeStep: handshakeUpgradeStep,
+  accepted: acceptedHandshake,
   createTopics: () => new TopicRegistry(),
   bunHandlers: createBunWsHandlers,
   attach: attachWebSocket,