@nifrajs/core 5.5.0 → 5.6.0

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
     },
@@ -149,6 +153,8 @@ function dispatchWsCallback(
   }
 }
 
+const BUN_TOO_BIG_REASON = "Received too big message"
+
 /**
  * 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`.
@@ -204,7 +210,16 @@ 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)
-      dispatchWsCallback(() => ws.data.handler.close?.(nifra, code, reason), nifra, ws.data.handler)
+      // 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
+      dispatchWsCallback(
+        () => ws.data.handler.close?.(nifra, closeCode, closeReason),
+        nifra,
+        ws.data.handler,
+      )
     },
   }
 }

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,