@nifrajs/core 0.1.0-alpha.1

package/src/server/sse.ts

@@ -0,0 +1,161 @@
+/**
+ * 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`.
+ *
+ *   // 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) })
+ *       await new Promise((r) => setTimeout(r, 1000))
+ *     }
+ *   }))
+ *
+ *   // 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) =>
+ *       stream.signal.addEventListener("abort", () => { off(); resolve() }, { once: true }))
+ *   }, { keepAlive: 15_000 }))
+ */
+
+/** One SSE frame. Every field is optional; `data` may be multi-line (emitted as multiple `data:` lines). */
+export interface SSEMessage {
+  readonly data?: string
+  readonly event?: string
+  readonly id?: string
+  /** Client reconnection delay hint, ms (coerced to an integer). */
+  readonly retry?: number
+  /** A `: comment` line (e.g. a keep-alive ping). */
+  readonly comment?: string
+}
+
+/** The stream handed to the `run` callback. */
+export interface SSEStream {
+  /** Enqueue an event frame. No-op once the stream is closed. */
+  send(message: SSEMessage): void
+  /** End the stream now. */
+  close(): void
+  /** 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. */
+export interface SSEContext {
+  readonly req: Request
+}
+
+export interface SSEInit {
+  readonly status?: number
+  // Derived from the `Headers` constructor so we don't depend on the DOM lib's `HeadersInit`
+  // (core is DOM-free for edge-safety).
+  readonly headers?: ConstructorParameters<typeof Headers>[0]
+  /** Send a `: ` comment ping every N ms so idle proxies don't drop the connection. */
+  readonly keepAlive?: number
+}
+
+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. */
+function formatMessage(m: SSEMessage): string {
+  let frame = ""
+  if (m.comment !== undefined) frame += `: ${m.comment.replace(CRLF, "")}\n`
+  if (m.event !== undefined) frame += `event: ${m.event.replace(CRLF, "")}\n`
+  if (m.id !== undefined) frame += `id: ${m.id.replace(CRLF, "")}\n`
+  if (m.retry !== undefined) frame += `retry: ${Math.trunc(m.retry)}\n`
+  if (m.data !== undefined) {
+    for (const line of m.data.split(LINE_SPLIT)) frame += `data: ${line}\n`
+  }
+  return `${frame}\n` // the blank line terminates the event
+}
+
+let neverAbort: AbortSignal | undefined
+function getNeverAbort(): AbortSignal {
+  neverAbort ??= new AbortController().signal
+  return neverAbort
+}
+
+export function sse(
+  c: SSEContext,
+  run: (stream: SSEStream) => void | Promise<void>,
+  init: SSEInit = {},
+): Response {
+  const encoder = new TextEncoder()
+  const requestSignal: AbortSignal | undefined = c.req?.signal
+  let closed = false
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  let onAbort: (() => void) | undefined
+
+  const teardown = (): void => {
+    if (heartbeat !== undefined) clearInterval(heartbeat)
+    if (requestSignal !== undefined && onAbort !== undefined) {
+      requestSignal.removeEventListener("abort", onAbort)
+    }
+  }
+
+  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: requestSignal ?? getNeverAbort(),
+      }
+
+      // Stop the moment the client goes away.
+      if (requestSignal !== undefined) {
+        if (requestSignal.aborted) {
+          close()
+          return
+        }
+        onAbort = close
+        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
+        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()
+    },
+  })
+
+  const headers = new Headers(init.headers)
+  headers.set("content-type", "text/event-stream; charset=utf-8")
+  headers.set("cache-control", "no-cache, no-transform")
+  if (!headers.has("x-accel-buffering")) headers.set("x-accel-buffering", "no") // defeat proxy buffering
+  return new Response(body, { status: init.status ?? 200, headers })
+}

package/src/server/webhook.ts

@@ -0,0 +1,207 @@
+/**
+ * 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
+ * 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`
+ * takes an explicit header + encoding for any other provider.
+ */
+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_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 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"`. */
+  readonly encoding?: SignatureEncoding
+  /** A prefix stripped from the header value before decoding, e.g. `"sha256="`. */
+  readonly prefix?: string
+  /** Max raw body bytes to read before rejecting (`payload_too_large`). Default 1 MiB. */
+  readonly maxBytes?: number
+  /** Replay window in seconds for timestamped schemes (Stripe). Default 300. */
+  readonly toleranceSeconds?: number
+  /** Current unix time (seconds); defaults to `Date.now()/1000`. Injectable for tests. */
+  readonly now?: number
+}
+
+export type WebhookFailureReason =
+  | "missing_signature"
+  | "invalid_signature"
+  | "timestamp_out_of_tolerance"
+  | "malformed_signature"
+  | "payload_too_large"
+  | "invalid_content_length"
+
+/** Verified ⇒ the raw `payload` text (parse it with your schema). Rejected ⇒ a stable `reason`. */
+export type WebhookResult =
+  | { readonly ok: true; readonly payload: string }
+  | { readonly ok: false; readonly reason: WebhookFailureReason }
+
+interface Preset {
+  readonly header: string
+  readonly encoding: SignatureEncoding
+  readonly prefix: string
+  readonly timestamped: boolean
+}
+
+const PRESETS: Record<WebhookProvider, Preset> = {
+  stripe: { header: "stripe-signature", encoding: "hex", prefix: "", timestamped: true },
+  github: { header: "x-hub-signature-256", encoding: "hex", prefix: "sha256=", timestamped: false },
+  generic: { header: "", encoding: "hex", prefix: "", timestamped: false },
+}
+
+const importHmacKey = (secret: string): Promise<CryptoKey> => {
+  requireSecretBytes(secret, "webhook")
+  return crypto.subtle.importKey(
+    "raw",
+    TEXT.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  )
+}
+
+// Decoders return `Uint8Array<ArrayBuffer>` (not the generic `Uint8Array<ArrayBufferLike>`) so they
+// satisfy WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics. `null` = the
+// header value wasn't valid for the declared encoding (treated as a malformed signature, never a 500).
+const fromHex = (hex: string): Uint8Array<ArrayBuffer> | null => {
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) return null
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return out
+}
+
+const fromBase64 = (value: string): Uint8Array<ArrayBuffer> | null => {
+  try {
+    const bin = atob(value)
+    const out = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+    return out
+  } catch {
+    return null
+  }
+}
+
+const decodeSignature = (
+  value: string,
+  encoding: SignatureEncoding,
+): Uint8Array<ArrayBuffer> | null => (encoding === "hex" ? fromHex(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
+  }
+  return false
+}
+
+// Parse a Stripe `Stripe-Signature` header: `t=<unix>,v1=<hex>[,v1=<hex>…]` (other schemes ignored).
+function parseStripeHeader(value: string): { t: number; v1: string[] } | null {
+  let t: number | null = null
+  const v1: string[] = []
+  for (const part of value.split(",")) {
+    const eq = part.indexOf("=")
+    if (eq < 1) continue
+    const k = part.slice(0, eq).trim()
+    const v = part.slice(eq + 1).trim()
+    if (k === "t") {
+      if (!/^\d+$/.test(v)) return null
+      t = Number(v)
+    } else if (k === "v1") {
+      v1.push(v)
+    }
+  }
+  if (t === null || v1.length === 0) return null
+  return { t, v1 }
+}
+
+/**
+ * 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.
+ *
+ * @param secret the signing secret (or an array, to accept either during a secret rotation).
+ *
+ * @example
+ * ```ts
+ * const r = await verifyWebhook(c.req, env.STRIPE_WEBHOOK_SECRET, { provider: "stripe" })
+ * if (!r.ok) return c.json({ ok: false, error: r.reason }, 400)
+ * const event = StripeEvent.parse(JSON.parse(r.payload)) // validate at the trust boundary
+ * ```
+ */
+export async function verifyWebhook(
+  req: Request,
+  secret: string | readonly string[],
+  options: VerifyWebhookOptions = {},
+): Promise<WebhookResult> {
+  const provider = options.provider ?? "generic"
+  const preset = PRESETS[provider]
+  const headerName = (options.header ?? preset.header).toLowerCase()
+  if (headerName === "") {
+    throw new Error('[nifra] verifyWebhook: a `header` is required for provider "generic"')
+  }
+  const encoding = options.encoding ?? preset.encoding
+  const prefix = options.prefix ?? preset.prefix
+
+  const read = await readBoundedBytes(req, options.maxBytes ?? DEFAULT_MAX_BYTES)
+  if (!read.ok) {
+    return {
+      ok: false,
+      reason: read.status === 413 ? "payload_too_large" : "invalid_content_length",
+    }
+  }
+  const payload = new TextDecoder().decode(read.bytes)
+
+  const headerValue = req.headers.get(headerName)
+  if (headerValue === null || headerValue === "") return { ok: false, reason: "missing_signature" }
+
+  const secrets = typeof secret === "string" ? [secret] : secret
+  const keys = await Promise.all(secrets.map(importHmacKey))
+
+  if (preset.timestamped) {
+    const parsed = parseStripeHeader(headerValue)
+    if (parsed === null) return { ok: false, reason: "malformed_signature" }
+    const signedPayload = 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 (!matched) return { ok: false, reason: "invalid_signature" }
+    // 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) {
+      return { ok: false, reason: "timestamp_out_of_tolerance" }
+    }
+    return { ok: true, payload }
+  }
+
+  const raw =
+    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 }
+  return { ok: false, reason: "invalid_signature" }
+}

package/src/server/websocket.ts

@@ -0,0 +1,308 @@
+/**
+ * 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
+ * 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 type {
+  InferOutput,
+  StandardIssue,
+  StandardSchemaV1,
+  ValidationOutcome,
+} from "../schema/standard.ts"
+import { validateStandard } from "../schema/standard.ts"
+
+type MaybePromise<T> = T | Promise<T>
+
+/** A received frame, normalized across runtimes: text → `string`, binary → `Uint8Array`. */
+export type WebSocketData = string | Uint8Array
+
+/** The value `message` receives: the schema's validated output when a `messageSchema` is set on the
+ * handler, otherwise the raw frame (`string | Uint8Array`). */
+type WsMessageInput<Schema extends StandardSchemaV1 | undefined> = Schema extends StandardSchemaV1
+  ? InferOutput<Schema>
+  : WebSocketData
+
+/** The portable socket handed to WS lifecycle callbacks. Each adapter wraps its native socket. */
+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(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. */
+  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. */
+  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** —
+ * 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`.
+ */
+export class TopicRegistry {
+  private readonly topics = new Map<string, Set<NifraWebSocket>>()
+  private readonly memberships = new WeakMap<NifraWebSocket, Set<string>>()
+
+  subscribe(topic: string, ws: NifraWebSocket): void {
+    let subs = this.topics.get(topic)
+    if (subs === undefined) {
+      subs = new Set()
+      this.topics.set(topic, subs)
+    }
+    subs.add(ws)
+    let mine = this.memberships.get(ws)
+    if (mine === undefined) {
+      mine = new Set()
+      this.memberships.set(ws, mine)
+    }
+    mine.add(topic)
+  }
+
+  unsubscribe(topic: string, ws: NifraWebSocket): void {
+    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
+    }
+    this.memberships.get(ws)?.delete(topic)
+  }
+
+  /** 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
+    for (const topic of mine) {
+      const subs = this.topics.get(topic)
+      if (subs !== undefined) {
+        subs.delete(ws)
+        if (subs.size === 0) this.topics.delete(topic)
+      }
+    }
+    this.memberships.delete(ws)
+  }
+
+  /** Send `data` to every connection subscribed to `topic`. Per-socket send errors are isolated. */
+  publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void {
+    const subs = this.topics.get(topic)
+    if (subs === undefined) return
+    for (const ws of subs) {
+      try {
+        ws.send(data)
+      } catch {
+        /* a single dead/closing socket must not abort the broadcast to the rest */
+      }
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export interface WebSocketContext<Env = unknown> {
+  readonly req: Request
+  readonly params: Record<string, string>
+  readonly query: unknown
+  readonly cookies: Readonly<Record<string, string>>
+  readonly env: Env
+  readonly signal: AbortSignal
+  readonly waitUntil: (promise: Promise<unknown>) => void
+  boundedBody(maxBytes?: number): Promise<Uint8Array>
+  boundedJson<T = unknown>(maxBytes?: number): Promise<T>
+}
+
+/** A WebSocket route's lifecycle. All callbacks optional; only `message` is needed for an echo. */
+export interface WebSocketHandler<
+  Data = unknown,
+  Env = unknown,
+  Schema extends StandardSchemaV1 | undefined = undefined,
+> {
+  /**
+   * 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
+   * `Origin` doesn't match (or is absent, for the allow-list form) is rejected with `403` before any
+   * per-connection work. Omit for no built-in check (same as today — then enforce it yourself in
+   * `upgrade()`). Non-browser clients can spoof `Origin`, so this is a browser-CSWSH defense, 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
+   * 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.
+   */
+  upgrade?(c: WebSocketContext<Env>): 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
+   * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).
+   */
+  messageSchema?: Schema
+  open?(ws: NifraWebSocket<Data>): MaybePromise<void>
+  message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>
+  /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is
+   * set). `raw` is the original frame; `issues` are the Standard Schema issues (one synthetic issue for
+   * a JSON parse failure). Omit to silently drop invalid frames. */
+  onInvalidMessage?(
+    ws: NifraWebSocket<Data>,
+    issues: ReadonlyArray<StandardIssue>,
+    raw: WebSocketData,
+  ): MaybePromise<void>
+  close?(ws: NifraWebSocket<Data>, code: number, reason: string): MaybePromise<void>
+  error?(ws: NifraWebSocket<Data>, error: unknown): MaybePromise<void>
+}
+
+/**
+ * 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 =
+  | { readonly kind: "pass" }
+  | { readonly kind: "reject"; readonly response: Response }
+  | {
+      readonly kind: "upgrade"
+      readonly handler: WebSocketHandler
+      readonly data: unknown
+      /** The app's pub/sub registry — the adapter wires `ws.subscribe` + close-cleanup to it. */
+      readonly pubsub: TopicRegistry
+    }
+
+/**
+ * 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).
+ */
+export interface StandardWebSocket {
+  send(data: string | ArrayBufferView | ArrayBuffer): void
+  close(code?: number, reason?: string): void
+  readonly readyState: number
+  binaryType?: string
+  addEventListener(type: string, listener: (event: never) => void): void
+}
+
+/** Normalize a received binary frame to `Uint8Array` (text frames stay `string`). */
+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
+}
+
+/**
+ * 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
+ * `error()` and never tears the process down; binary frames are normalized to `Uint8Array`.
+ */
+export function attachWebSocket(
+  socket: StandardWebSocket,
+  handler: WebSocketHandler,
+  data: unknown,
+  options: { openNow: boolean; pubsub: TopicRegistry },
+): NifraWebSocket {
+  const { pubsub } = options
+  const ws: NifraWebSocket = {
+    send: (payload) => socket.send(payload),
+    close: (code, reason) => socket.close(code, reason),
+    get readyState() {
+      return socket.readyState
+    },
+    subscribe: (topic) => pubsub.subscribe(topic, ws),
+    unsubscribe: (topic) => pubsub.unsubscribe(topic, ws),
+    data,
+    raw: socket,
+  }
+  const reportError = (error: unknown): void => {
+    if (handler.error === undefined) return
+    try {
+      const r = handler.error(ws, error)
+      if (r instanceof Promise) r.catch(() => {})
+    } catch {
+      /* the error handler itself failed — last resort, swallow */
+    }
+  }
+  const safe = (call: () => MaybePromise<void>): void => {
+    try {
+      const r = call()
+      if (r instanceof Promise) r.catch(reportError)
+    } catch (error) {
+      reportError(error)
+    }
+  }
+  // Deliver binary as ArrayBuffer (→ Uint8Array) rather than Blob, where the runtime allows it.
+  if ("binaryType" in socket) socket.binaryType = "arraybuffer"
+  socket.addEventListener("message", (event: { readonly data: unknown }) => {
+    const raw = event.data
+    const payload: WebSocketData = typeof raw === "string" ? raw : toBinary(raw)
+    safe(() => handler.message?.(ws, payload))
+  })
+  socket.addEventListener(
+    "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 ?? ""))
+    },
+  )
+  socket.addEventListener("error", (event: unknown) => reportError(event))
+  if (options.openNow) {
+    safe(() => handler.open?.(ws))
+  } else {
+    socket.addEventListener("open", () => safe(() => handler.open?.(ws)))
+  }
+  return ws
+}
+
+const WS_MESSAGE_DECODER = new TextDecoder()
+
+/**
+ * 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.
+ */
+export function wrapWebSocketMessageValidation(handler: WebSocketHandler): WebSocketHandler {
+  const schema = handler.messageSchema
+  if (schema === undefined) return handler
+  // The handler is type-erased here; the user's `message` really accepts the schema's validated output
+  // (typed at the real call site), so widen its param to `unknown` for the internal call.
+  const userMessage = handler.message as
+    | ((ws: NifraWebSocket, data: unknown) => MaybePromise<void>)
+    | undefined
+  const onInvalid = handler.onInvalidMessage
+  const validatingMessage = (ws: NifraWebSocket, raw: WebSocketData): MaybePromise<void> => {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(typeof raw === "string" ? raw : WS_MESSAGE_DECODER.decode(raw))
+    } catch {
+      return onInvalid?.(ws, [{ message: "invalid JSON" }], raw)
+    }
+    const outcome = validateStandard(schema, parsed)
+    const finish = (o: ValidationOutcome<unknown>): MaybePromise<void> =>
+      o.ok ? userMessage?.(ws, o.value) : onInvalid?.(ws, o.issues, raw)
+    return outcome instanceof Promise ? outcome.then(finish) : finish(outcome)
+  }
+  // The wrapped `message` takes the raw frame (adapters pass that) and produces the typed value
+  // internally; the stored handler is type-erased, so the signature is sound.
+  return { ...handler, message: validatingMessage } as WebSocketHandler
+}