@nifrajs/core 5.5.1 → 5.7.0

package/src/server/sse.ts

@@ -22,6 +22,7 @@
  *   }, { keepAlive: 15_000 }))
  */
 import { INSTALL_SSE } from "./install.ts"
+import { jsonText } from "./json-text.ts"
 import type { IdentityPlugin } from "./plugin.ts"
 import type { AnyServer } from "./server.ts"
 import type { SseRuntime } from "./sse-hook.ts"
@@ -66,7 +67,7 @@ export interface SSEInit {
    * 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.
+   * the client can read. A single frame over the cap is also refused; `Infinity` turns the limit off.
    */
   readonly maxBufferedBytes?: number
 }
@@ -92,7 +93,7 @@ export interface TypedSSEStream<Event> {
 export function typedSSEStream<Event>(stream: SSEStream): TypedSSEStream<Event> {
   return {
     send(event, init = {}) {
-      stream.send({ ...init, data: JSON.stringify(event) })
+      stream.send({ ...init, data: jsonText(event) })
     },
     comment(text) {
       stream.send({ comment: text })
@@ -158,9 +159,10 @@ export function sse(
         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) {
+            const frame = encoder.encode(formatMessage(message))
+            // Check the incoming frame too: a lone oversized event has no later send to trigger
+            // overflow detection. Erroring the body releases its queue and stops the producer.
+            if (frame.byteLength > (controller.desiredSize ?? 0)) {
               closed = true
               teardown()
               const reason = new Error("sse_client_too_slow")
@@ -168,7 +170,7 @@ export function sse(
               controller.error(reason)
               return
             }
-            controller.enqueue(encoder.encode(formatMessage(message)))
+            controller.enqueue(frame)
           },
           close,
           signal: stopped.signal,

package/src/server/text-slots.ts

@@ -0,0 +1,21 @@
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { RouteSchema } from "./context.ts"
+
+// What a schema offers for a slot whose values arrive as text: `@nifrajs/schema` sets it on a
+// `t.object` (and any `t` schema that does not coerce) to the coercing form of the same schema.
+const TEXT_SLOT = Symbol.for("nifra.schema.textSlot")
+
+/**
+ * `schema` with its `query`, `headers` and `cookies` schemas swapped for the text form each offers, or
+ * `schema` itself when none offers one. A query string, header values and a `Cookie` header are
+ * always text, so a schema that reads a boolean or a number there can only validate its coercing form.
+ */
+export function withTextSlots(schema: RouteSchema | undefined): RouteSchema | undefined {
+  let out = schema
+  for (const slot of ["query", "headers", "cookies"] as const) {
+    const validate = out?.[slot]?.["~standard"].validate
+    const form: StandardSchemaV1 | undefined = validate && Reflect.get(validate, TEXT_SLOT)
+    if (form !== undefined) out = { ...out, [slot]: form }
+  }
+  return out
+}

package/src/server/webhook.ts

@@ -4,9 +4,10 @@
  * 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
- * can't be discovered through timing. WebCrypto-only, so it runs on Bun / Node / Deno / workerd.
+ * Verification is **constant-time**: the expected HMAC is computed once per secret with
+ * `crypto.subtle.sign` (WebCrypto) and compared to each signature the header lists without an early
+ * exit - so a wrong signature can't be discovered through timing, and a header listing many
+ * signatures costs no extra HMAC over the body. WebCrypto-only, so it runs on Bun / Node / Deno / workerd.
  *
  * Presets cover Stripe (`t=…,v1=…` with a replay-window check) and GitHub (`sha256=…`); `generic`
  * takes an explicit header + encoding for any other provider.
@@ -48,6 +49,7 @@ export type WebhookFailureReason =
   | "malformed_signature"
   | "payload_too_large"
   | "invalid_content_length"
+  | "invalid_body"
 
 /** Verified ⇒ the raw `payload` text (parse it with your schema). Rejected ⇒ a stable `reason`. */
 export type WebhookResult =
@@ -74,7 +76,7 @@ const importHmacKey = (secret: string): Promise<CryptoKey> => {
     TEXT.encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
-    ["verify"],
+    ["sign"],
   )
 }
 
@@ -120,17 +122,26 @@ const decodeSignature = (
       ? 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(
-  keys: readonly CryptoKey[],
-  sig: Uint8Array<ArrayBuffer>,
-  payload: Uint8Array,
-): Promise<boolean> {
-  for (const key of keys) {
-    if (await crypto.subtle.verify("HMAC", key, sig, payload as Uint8Array<ArrayBuffer>))
-      return true
+/** The HMAC-SHA256 of `payload` under each of `keys`. */
+const expectedMacs = (keys: readonly CryptoKey[], payload: Uint8Array): Promise<Uint8Array[]> =>
+  Promise.all(
+    keys.map(
+      async (key) =>
+        new Uint8Array(await crypto.subtle.sign("HMAC", key, payload as Uint8Array<ArrayBuffer>)),
+    ),
+  )
+
+/** True iff `sig` equals one of `macs`. Every byte of a same-length MAC is visited; a MAC's length is
+ * fixed (32 bytes), so a length mismatch reveals nothing. */
+function matchesAny(macs: readonly Uint8Array[], sig: Uint8Array): boolean {
+  let matched = false
+  for (const mac of macs) {
+    if (mac.length !== sig.length) continue
+    let diff = 0
+    for (let i = 0; i < mac.length; i++) diff |= (mac[i] ?? 0) ^ (sig[i] ?? 0)
+    if (diff === 0) matched = true
   }
-  return false
+  return matched
 }
 
 // Parse a Stripe `Stripe-Signature` header: `t=<unix>,v1=<hex>[,v1=<hex>…]` (other schemes ignored).
@@ -193,10 +204,7 @@ export async function verifyWebhook(
 
   const read = await readBoundedBytes(req, maxBytes)
   if (!read.ok) {
-    return {
-      ok: false,
-      reason: read.status === 413 ? "payload_too_large" : "invalid_content_length",
-    }
+    return { ok: false, reason: read.error }
   }
   const payload = new TextDecoder().decode(read.bytes)
 
@@ -209,14 +217,11 @@ export async function verifyWebhook(
   if (preset.timestamped) {
     const parsed = parseStripeHeader(headerValue)
     if (parsed === null) return { ok: false, reason: "malformed_signature" }
-    const signedPayload = TEXT.encode(`${parsed.t}.${payload}`)
+    const macs = await expectedMacs(keys, TEXT.encode(`${parsed.t}.${payload}`))
     let matched = false
     for (const v1 of parsed.v1) {
       const sig = decodeSignature(v1, encoding)
-      if (sig !== null && (await verifyAny(keys, sig, signedPayload))) {
-        matched = true
-        break
-      }
+      if (sig !== null && matchesAny(macs, sig)) matched = true
     }
     if (!matched) return { ok: false, reason: "invalid_signature" }
     // The signature covers `t`, so `t` is authentic once matched - now enforce the replay window.
@@ -232,6 +237,6 @@ export async function verifyWebhook(
     prefix !== "" && headerValue.startsWith(prefix) ? headerValue.slice(prefix.length) : headerValue
   const sig = decodeSignature(raw, encoding)
   if (sig === null) return { ok: false, reason: "malformed_signature" }
-  if (await verifyAny(keys, sig, read.bytes)) return { ok: true, payload }
+  if (matchesAny(await expectedMacs(keys, read.bytes), sig)) return { ok: true, payload }
   return { ok: false, reason: "invalid_signature" }
 }

package/src/server/websocket.ts

@@ -18,7 +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"
+import { isResponseResult, type StatusResponse } from "./runtime-core.ts"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -35,7 +35,9 @@ 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, with a code an endpoint may send (1000-1003, 1007-1014, 3000-4999;
+   * 1000 when none is given, on every runtime) and a reason of at most 123 UTF-8 bytes. Any other
+   * close throws a `RangeError`, and the socket stays open. */
   close(code?: number, reason?: string): void
   /** `WebSocket.readyState` (0 CONNECTING · 1 OPEN · 2 CLOSING · 3 CLOSED). */
   readonly readyState: number
@@ -170,7 +172,7 @@ export interface WebSocketHandler<
    * `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>
+  upgrade?(c: WebSocketContext<Env> & Extra): MaybePromise<Data | Response | StatusResponse>
   /**
    * 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
@@ -211,6 +213,9 @@ export interface WebSocketHandler<
     issues: ReadonlyArray<StandardIssue>,
     raw: WebSocketData,
   ): MaybePromise<void>
+  /** The connection closed. `code` and `reason` are the server's own close when it closed first
+   * (`ws.close()`, or 1009 for a message over the cap), the peer's when the peer did, and 1006 when
+   * the connection dropped without a close frame. */
   close?(ws: NifraWebSocket<Data>, code: number, reason: string): MaybePromise<void>
   error?(ws: NifraWebSocket<Data>, error: unknown): MaybePromise<void>
 }
@@ -314,9 +319,20 @@ export function attachWebSocket<
     handler.transport,
     reportError,
   )
+  // The runtime's close event carries the peer's echo, which may drop the reason; `close` is given
+  // the server's own close when the server closed first, as on Bun.
+  let sentClose: readonly [number, string] | undefined
+  // A close with no code is 1000 here as on Bun, whose close() cannot send one without a status.
+  const closeSocket = (code = 1000, reason?: string): void => {
+    if (sentClose === undefined && socket.readyState <= 1) sentClose = [code, reason ?? ""]
+    socket.close(code, reason)
+  }
   ws = {
     send,
-    close: (code, reason) => socket.close(code, reason),
+    close: (code, reason) => {
+      assertCloseArgs(code, reason)
+      closeSocket(code, reason)
+    },
     get readyState() {
       return socket.readyState
     },
@@ -342,7 +358,7 @@ export function attachWebSocket<
     // The runtime hands over each message whole, so this bounds what reaches the handler, not what
     // the runtime buffered to deliver it.
     if (maxPayloadBytes !== undefined && exceedsPayloadCap(payload, maxPayloadBytes)) {
-      socket.close(1009, "message too large")
+      closeSocket(1009, "message too large")
       return
     }
     safe(() =>
@@ -357,7 +373,8 @@ export function attachWebSocket<
     "close",
     (event: { readonly code?: number; readonly reason?: string }) => {
       pubsub.unsubscribeAll(ws) // drop topic subscriptions so the registry never holds a dead socket
-      safe(() => handler.close?.(ws, event.code ?? 1005, event.reason ?? ""))
+      const [code, reason] = sentClose ?? [event.code ?? 1005, event.reason ?? ""]
+      safe(() => handler.close?.(ws, code, reason))
     },
   )
   socket.addEventListener("error", (event: unknown) => reportError(event))
@@ -372,7 +389,8 @@ export function attachWebSocket<
 const WS_MESSAGE_DECODER = new TextDecoder()
 
 /** Whether a message is over `cap` UTF-8 bytes, without encoding a text one: each UTF-16 unit takes
- * 1-3 bytes (a surrogate pair 4 for its 2), so only a length between those bounds is counted. */
+ * 1-3 bytes (a surrogate pair 4 for its 2, a lone surrogate the 3 of U+FFFD), so only a length
+ * between those bounds is counted. */
 export function exceedsPayloadCap(
   message: string | ArrayBuffer | Uint8Array,
   cap: number,
@@ -384,12 +402,43 @@ export function exceedsPayloadCap(
   let bytes = 0
   for (let i = 0; i < units; i++) {
     const unit = message.charCodeAt(i)
-    bytes += unit < 0x80 ? 1 : unit < 0x800 || (unit >= 0xd800 && unit <= 0xdfff) ? 2 : 3
+    if (unit >= 0xd800 && unit <= 0xdbff && (message.charCodeAt(i + 1) & 0xfc00) === 0xdc00) {
+      bytes += 4
+      i++
+    } else bytes += unit < 0x80 ? 1 : unit < 0x800 ? 2 : 3
     if (bytes > cap) return true
   }
   return false
 }
 
+/**
+ * Refuse a close RFC 6455 forbids before the runtime sees it: a code outside 1000-1003, 1007-1014 and
+ * 3000-4999, a reason over 123 UTF-8 bytes, or a reason without a code. Runtimes disagreed on such a
+ * close - Bun and Deno sent it, Node's `ws` threw after marking the socket closing, which left it
+ * half-open, and workerd threw - so every adapter throws this `RangeError` first and the socket stays
+ * open.
+ */
+export function assertCloseArgs(code: number | undefined, reason: string | undefined): void {
+  if (code === undefined) {
+    if (reason !== undefined && reason !== "")
+      throw new RangeError("ws.close(): a reason needs a code")
+    return
+  }
+  if (
+    !Number.isInteger(code) ||
+    !(
+      (code >= 1000 && code <= 1003) ||
+      (code >= 1007 && code <= 1014) ||
+      (code >= 3000 && code <= 4999)
+    )
+  )
+    throw new RangeError(
+      `ws.close(): ${code} is not a code a server may send (1000-1003, 1007-1014, 3000-4999)`,
+    )
+  if (reason !== undefined && exceedsPayloadCap(reason, 123))
+    throw new RangeError("ws.close(): the reason is over 123 UTF-8 bytes")
+}
+
 type WebSocketSendPayload = string | ArrayBufferView | ArrayBuffer
 
 const OUTBOUND_VALIDATION_ERROR = "outbound WebSocket frame failed sendSchema validation"

package/src/server/ws-bun.ts

@@ -6,6 +6,7 @@
  */
 
 import {
+  assertCloseArgs,
   createWebSocketSender,
   exceedsPayloadCap,
   type NifraWebSocket,
@@ -103,7 +104,10 @@ function wrapBunSocket(
   )
   ws = {
     send,
-    close: (code, reason) => raw.close(code, reason),
+    close: (code, reason) => {
+      assertCloseArgs(code, reason)
+      raw.close(code, reason)
+    },
     get readyState() {
       return raw.readyState
     },
@@ -206,8 +210,8 @@ export function createBunWsHandlers(
       // Registry mode: drop topic subscriptions so it never holds a dead socket. Native mode: Bun
       // unsubscribes the socket from every topic on close, so there is nothing to sweep here.
       if (!nativePubsub) (ws.data.pubsub ?? topics).unsubscribeAll(nifra)
-      // Bun's own maxPayloadLength drops the connection without a close frame, so the peer sees 1006;
-      // the handler gets the 1009 every other payload cap reports.
+      // Bun's own maxPayloadLength reports 1006 here, whether it dropped the connection (up to 1.4.3)
+      // or sent the peer a 1009 (from 1.4.4); the handler gets the 1009 every other payload cap reports.
       const oversize = code === 1006 && reason === BUN_TOO_BIG_REASON
       const closeCode = oversize ? 1009 : code
       const closeReason = oversize ? "message too large" : reason

package/src/server.ts

@@ -46,6 +46,7 @@ export {
   markAuthenticatedRequest,
   rejected,
 } from "./server/auth.ts"
+export { beforeHandler } from "./server/before-handler.ts"
 export type {
   Context,
   Params,
@@ -107,6 +108,7 @@ export type {
 } from "./server/registry.ts"
 export { replacedRequestOf } from "./server/request-lineage.ts"
 export { writableResponse } from "./server/respond.ts"
+export { routeTemplateOf } from "./server/route-template.ts"
 export {
   type PlainRender,
   type ResponseResult,

package/src/single-copy.ts

@@ -78,13 +78,9 @@ 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"
-}
+/** Appended to a linked file the load hook hands back to Bun untouched; see the hook. */
+const OWN_FILE_QUERY = "?nifra-single-copy"
+
 /** 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
@@ -233,6 +229,11 @@ export interface SingleCopyRegistration {
   readonly run: boolean
   /** `[test] preload`: covers `bun test`, the surface that runs app sources unbundled. */
   readonly test: boolean
+  /**
+   * Tables whose `preload` names the registrar although Bun reads it from neither place: below
+   * `[install]` the line is `install.preload`, so `bun run` loads every copy while the file looks armed.
+   */
+  readonly ignored?: readonly string[]
   /** The `bunfig.toml` that was read, if one exists. */
   readonly config?: string
 }
@@ -286,6 +287,7 @@ export function readSingleCopyRegistration(cwd: string): SingleCopyRegistration
   let section = ""
   let run = false
   let test = false
+  const ignored: string[] = []
   for (const line of text.split(/\r?\n/)) {
     const match = PRELOAD_ASSIGNMENT.exec(line)
     if (match?.groups === undefined) continue
@@ -298,8 +300,9 @@ export function readSingleCopyRegistration(cwd: string): SingleCopyRegistration
       continue
     if (section === "test") test = true
     else if (section === "") run = true
+    else if (!ignored.includes(section)) ignored.push(section)
   }
-  return { run, test, config }
+  return ignored.length === 0 ? { run, test, config } : { run, test, ignored, config }
 }
 
 /** The repository a linked checkout resolves its own dependencies from: its nearest `.git` ancestor.
@@ -598,6 +601,8 @@ export function singleCopyPlugin(options: SingleCopyOptions = {}): SingleCopyPlu
       // hook has to return contents for everything it matches, and re-emitting a CommonJS entry as an
       // ES module is how `Export named 'useEffect' not found` happens.
       const filter = new RegExp(`^(?:${roots})[/\\\\].*${REDIRECTABLE.source}`)
+      // `Bun.plugin` leaves `config` unset although the type says otherwise; only `Bun.build` sets it.
+      const bundling = build.config !== undefined
       build.onLoad({ filter }, (args) => {
         for (const redirect of plan.redirects) {
           const target = counterpart(redirect, args.path)
@@ -616,10 +621,13 @@ export function singleCopyPlugin(options: SingleCopyOptions = {}): SingleCopyPlu
             detail: `${relative(owner.from, args.path)} has no file at the same path in the app's copy, so it loads from the linked copy and its module state is not shared`,
           })
         }
-        // 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: sourceLoader(args.path) }
+        // The file loads as it is, in its own module format. A bundler takes `undefined` for that. A
+        // runtime `onLoad` must return an object, and source returned from here loads as an ES module,
+        // which empties a CommonJS file's exports - so the runtime gets a re-export of the file under a
+        // query the filter's `$` cannot match, which Bun then loads natively from its own directory.
+        // There its `__filename` and `import.meta.url` carry the query; the bundler cannot resolve it.
+        if (bundling) return undefined
+        return { contents: reexport(`${args.path}${OWN_FILE_QUERY}`), loader: "js" }
       })
     },
   }
@@ -646,12 +654,20 @@ const processSet = (key: symbol): Set<string> => {
 const copyLine = (label: string, path: string | undefined, version: string | undefined): string =>
   `  ${label}: ${path ?? "(not installed for the app)"}${version === undefined ? "" : ` (${version})`}`
 
-/** One report per package: both copies, both versions, the reason, and the fix. */
+/**
+ * One report per package: both copies, both versions, the reason, and the fix. A version skew comes
+ * from the plan, which reads installs, so it says installed: nothing may ever load that copy, and a
+ * runtime `onLoad` cannot watch for it without re-emitting CommonJS files as ES modules.
+ */
 const describeSkips = (name: string, skips: readonly SingleCopySkip[]): string => {
   const first = skips[0]
   const reason = first?.reason ?? "version-skew"
+  const effect =
+    reason === "version-skew"
+      ? "a second copy is installed at another version, and whatever loads it does not share this copy's module state."
+      : "a second copy loads, so its module state is not shared."
   const lines = [
-    `[nifra] single-copy: ${name} is NOT deduplicated (${reason}) - a second copy loads, so its module state is not shared.`,
+    `[nifra] single-copy: ${name} is NOT deduplicated (${reason}) - ${effect}`,
     copyLine("app copy", first?.to, first?.toVersion),
   ]
   for (const skip of skips) {
@@ -683,7 +699,7 @@ const describeSkewGroup = (skips: readonly SingleCopySkip[]): string => {
   if (first === undefined || skips.length === 1) return describeSkips(first?.package ?? "", skips)
   const names = skips.map((skip) => skip.package).sort(codeUnitOrder)
   return [
-    `[nifra] single-copy: ${names.length} packages are NOT deduplicated (version-skew) - a second copy of each loads, so their module state is not shared.`,
+    `[nifra] single-copy: ${names.length} packages are NOT deduplicated (version-skew) - a second copy of each is installed at another version, and whatever loads one does not share the app copy's module state.`,
     copyLine(
       "app copies",
       first.to === undefined ? undefined : modulesDirOf(first.to),