Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

29.6 KB
Raw Blame
// Relay socket + E2EE handshake + RPC/frame state machine (main process).
//
// A single connection to the dumb relay server (a separate repo). The relay
// forwards opaque bytes between a host and a client matched by a pairing token;
// it never decrypts. So the end-to-end-encrypted handshake and all traffic run
// HOST<->CLIENT *through* the relay — the relay is not a handshake participant.
//
// The handshake/RPC state machine, in brief:
//   - The token gates entry at the relay via a `?token=<token>` QUERY PARAM on
//     the wss URL (matching what the relay expects). It is NOT
//     interleaved as a data frame — every frame on the wire is opaque peer
//     traffic.
//   - Handshake `e2ee_hello -> e2ee_ready -> e2ee_auth -> e2ee_authenticated`:
//       * client (knows the host pubkey) sends `e2ee_hello {publicKeyB64}` and
//         derives the shared key from the host pubkey;
//       * host learns the client pubkey from `e2ee_hello`, derives the same
//         shared key, replies `e2ee_ready`;
//       * client then sends an ENCRYPTED `e2ee_auth` (the relay already verified
//         the token and the offer pins the host pubkey, so for MVP a simple
//         authenticated marker is sufficient — no extra secret to prove);
//       * host replies an ENCRYPTED `e2ee_authenticated`. Both sides fire onReady
//         once their side of the auth exchange is complete.
//   - After authentication every peer message is an E2EE box (sent as binary).
//     The decrypted plaintext is tagged: 0x01 = JSON RPC envelope, 0x02 = a
//     binary terminal frame (framing.ts). Handshake control frames (`e2ee_hello`
//     / `e2ee_ready`) are sent as plaintext JSON strings so the receiver can tell
//     them apart from the encrypted binary boxes.
//
// Pure-ish: no IPC, no renderer. The WebSocket is INJECTED as a `RelayTransport`
// so tests drive two RelaySockets via in-process fakes with no real network;
// production passes a `ws` WebSocket wrapped via `wrapWebSocket`.

import {
  canonicalB64ToBytes,
  decrypt,
  deriveSessionKey,
  deriveSharedKey,
  encrypt,
  publicKeyToB64,
  randomSessionNonce,
  sasFromSharedKey,
  type KeyPair
} from './e2ee'
import { decodeFrame, encodeFrame, type Frame, MAX_BINARY_BUFFERED_AMOUNT } from './framing'

// A minimal duplex transport. `send` accepts a string (handshake control) or a
// Uint8Array (encrypted box). `bufferedAmount` drives backpressure on frames.
export interface RelayTransport {
  readonly bufferedAmount: number
  send(data: string | Uint8Array): void
  close(): void
  onMessage(cb: (data: unknown) => void): void
  onClose(cb: () => void): void
}

// An RPC request envelope as seen by the peer's onRpc handler. `id` correlates a
// later `respond`.
export type RpcRequest = {
  id: string
  method: string
  params: unknown
}

export type RelaySocket = {
  // Send an RPC request to the peer; resolves with the peer's response body (or
  // rejects on a non-ok response / timeout / closed connection).
  rpc(method: string, params?: unknown): Promise<unknown>
  // Fire a one-way notification to the peer (no response expected, never rejects).
  // The peer receives it in `onRpc` with an empty `id` — answering it is a no-op
  // (notifications carry no correlation id). Returns false if not connected.
  notify(method: string, params?: unknown): boolean
  // Answer a received RPC request (from onRpc) by its id.
  respond(id: string, ok: boolean, body: unknown): void
  // Send a terminal frame to the peer. Returns false when the transport is over
  // its buffered-amount threshold (backpressure) or not connected.
  sendFrame(op: number, streamId: number, seq: number, payload: Uint8Array): boolean
  // The Short Authentication String for this channel (derived from the shared key), or null
  // before the handshake has derived a key. Both peers compute the same value.
  sas(): string | null
  // The peer's NaCl box public key (base64) once known: for a client it is the pinned host key
  // passed in; for a host it is learned from the client's `e2ee_hello`. Null before then. Used by
  // the standing (phone) host to look the connecting device up in its pin-once approval list.
  peerPublicKeyB64(): string | null
  // --- 4c tunnel: the Server Edition's rpc.ts protocol, carried inside the E2EE box ------------
  // Send one rpc.ts TEXT frame (a JSON RpcMessage). False if the channel is not ready — a tunnel
  // frame is NEVER sent in the clear.
  sendTunnelText(json: string): boolean
  // Send one rpc.ts BINARY frame (encodePtyData bytes). False if the channel is not ready.
  sendTunnelBinary(bytes: Uint8Array): boolean
  // Bytes handed to the underlying socket but not yet flushed (ws.bufferedAmount + anything still
  // sitting in the pre-open queue). This is the number Stage 2's per-client backpressure and the
  // 8 MB WS_DROP_WATER drop-and-redraw ceiling key on (see src/core/ui-sink-registry.ts): a sink
  // that reports 0 silently disables the ceiling, and a slow peer then queues pty output without
  // bound until the host process dies. It must stay honest.
  bufferedAmount(): number
  // Tear down: stops reconnects and closes the transport.
  close(): void
}

export type ConnectRelayOptions = {
  // The relay wss URL. `?token=` is appended automatically when opening a socket.
  url: string
  // Single-use pairing token; gates entry at the relay (query param).
  token: string
  role: 'host' | 'client'
  // Our long-lived (host) or ephemeral (client) NaCl keypair.
  ourKeys: KeyPair
  // The peer's public key, base64. REQUIRED for the client (it must know the
  // host's pubkey up front); for the host it is learned from `e2ee_hello`.
  theirPubB64?: string
  // Injected transport. Tests pass an in-process fake; production passes a `ws`
  // WebSocket wrapped via `wrapWebSocket`. When omitted, a `ws` socket is opened
  // from `url` (production default).
  transport?: RelayTransport
  onReady(): void
  onRpc(msg: RpcRequest): void
  onFrame(f: Frame): void
  onClose(): void
  // An rpc.ts frame arrived over the ENCRYPTED, session-keyed, role-tagged, replay-checked
  // channel. This is the ONLY inbound path 4c's trust + RPC layers may trust: anything that did
  // not come out of the E2EE box never reaches here.
  onTunnel?(kind: 'text' | 'binary', payload: Uint8Array): void
}

// Plaintext-tag bytes for decrypted peer payloads.
const TAG_RPC = 0x01
const TAG_FRAME = 0x02
// 4c tunnel: the Server Edition's rpc.ts protocol, carried verbatim inside the E2EE box. Text = a
// JSON RpcMessage; binary = an encodePtyData frame. Both ride the SAME encrypted stream as
// everything else — same sendSeq counter, same FIFO delivery — because Stage 3's canvas
// convergence needs a single ordered channel per client.
const TAG_TUNNEL_TEXT = 0x03
const TAG_TUNNEL_BIN = 0x04

const RPC_TIMEOUT_MS = 30_000
const KEEPALIVE_INTERVAL_MS = 25_000
const RECONNECT_DELAYS_MS = [500, 1000, 2000, 4000, 8000, 15_000]

type RpcEnvelope =
  | { kind: 'req'; id: string; method: string; params: unknown }
  | { kind: 'notify'; method: string; params: unknown }
  | { kind: 'res'; id: string; ok: boolean; body: unknown }
  | { kind: 'keepalive' }

type HandshakeControl =
  | { type: 'e2ee_hello'; publicKeyB64: string; nonceB64: string }
  | { type: 'e2ee_ready'; nonceB64: string }

function nonceToB64(n: Uint8Array): string {
  return Buffer.from(n).toString('base64')
}
// Canonical base64 only (e2ee.ts canonicalB64ToBytes): a nonce with junk around it is not a nonce.
function nonceFromB64(b64: unknown): Uint8Array | null {
  try {
    return canonicalB64ToBytes(b64, 16, 'session nonce')
  } catch {
    return null
  }
}

type State = 'connecting' | 'handshaking' | 'ready' | 'closed'

const textEncoder = new TextEncoder()
const textDecoder = new TextDecoder()

export function connectRelay(opts: ConnectRelayOptions): RelaySocket {
  if (opts.role === 'client' && !opts.theirPubB64) {
    throw new Error('connectRelay: client role requires theirPubB64 (the host public key)')
  }
  // A client derives its identity key from the PINNED host key before anything is opened: a key
  // that is not canonical base64, or is a low-order point (WeakPeerKeyError — a public-constant
  // shared secret), throws HERE, so no socket is dialed for a session that could never be private.
  const clientBaseKey =
    opts.role === 'client' ? deriveSharedKey(opts.theirPubB64!, opts.ourKeys.secretKey) : null

  let transport: RelayTransport | null = null
  // baseKey = the stable ECDH precompute (for the SAS, which represents the pinned identity).
  // sessionKey = HKDF(baseKey, hostNonce‖clientNonce) = the fresh per-session traffic key.
  let baseKey: Uint8Array | null = null
  let sessionKey: Uint8Array | null = null
  let ourNonce: Uint8Array | null = null
  // Role byte prefixed to every sealed plaintext, so a relay can't REFLECT a box back to its
  // sender (same sessionKey both directions): each side only accepts boxes tagged with the peer's
  // role. host=1, client=2.
  const OUR_ROLE = opts.role === 'host' ? 1 : 2
  const PEER_ROLE = opts.role === 'host' ? 2 : 1
  // The peer's base64 public key. Known up front for a client (the pinned host key); learned from
  // `e2ee_hello` for a host. Exposed via peerPublicKeyB64() for the standing host's pin-once check.
  let peerPubB64: string | null = opts.role === 'client' ? opts.theirPubB64 ?? null : null
  let state: State = 'connecting'
  let intentionallyClosed = false
  let reconnectAttempt = 0
  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
  let keepaliveTimer: ReturnType<typeof setInterval> | null = null
  let requestCounter = 0
  let readyFired = false
  // Replay/reorder protection: every encrypted message carries a strictly-increasing per-
  // direction counter inside the authenticated plaintext. The receiver rejects any message whose
  // counter is not greater than the last accepted one, so a relay (or on-path attacker) cannot
  // replay a captured box (e.g. re-injecting an OP.Input keystroke frame or a pty.kill RPC) nor
  // reorder traffic. Counters reset per (re)connection — a fresh handshake is a fresh stream.
  let sendSeq = 0
  let recvSeq = -1

  const pending = new Map<
    string,
    { resolve: (body: unknown) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout> }
  >()

  function buildUrl(): string {
    // Append `?token=` so the relay can read the pairing token from the query
    // string. Preserve any existing query.
    const sep = opts.url.includes('?') ? '&' : '?'
    return `${opts.url}${sep}token=${encodeURIComponent(opts.token)}`
  }

  function openConnection(): void {
    if (intentionallyClosed) {
      return
    }
    state = 'connecting'
    baseKey = null
    sessionKey = null
    ourNonce = randomSessionNonce()
    readyFired = false
    sendSeq = 0
    recvSeq = -1

    if (opts.transport) {
      // Injected transport (tests). It is already "open"; treat that as the
      // open event. A re-open after a drop is not supported for injected
      // transports — production reconnect goes through the real ws path.
      transport = opts.transport
    } else {
      transport = openWebSocketTransport(buildUrl())
    }

    transport.onMessage((data) => handleMessage(data))
    transport.onClose(() => handleClose())

    state = 'handshaking'
    if (opts.role === 'client') {
      // Client knows the host pubkey: derive the base (identity) key now and greet with our
      // session nonce. The traffic key is derived once the host's nonce arrives in e2ee_ready.
      baseKey = clientBaseKey
      sendControl({
        type: 'e2ee_hello',
        publicKeyB64: publicKeyToB64(opts.ourKeys.publicKey),
        nonceB64: nonceToB64(ourNonce!)
      })
    }
    // Host waits passively for `e2ee_hello` to learn the client pubkey.
  }

  function sendControl(control: HandshakeControl): void {
    transport?.send(JSON.stringify(control))
  }

  // Prepend the outbound monotonic counter (8 bytes LE) to the plaintext before sealing, so the
  // peer can reject replays/reorders. Mirrors framing.ts's 64-bit split to stay within safe ints.
  // Authenticated plaintext layout: [role:1][seq:8][payload…]. The role defeats reflection; the
  // strictly-increasing seq defeats in-session replay/reorder.
  const SEQ_BYTES = 8
  const HEADER_BYTES = 1 + SEQ_BYTES
  function withHeader(plaintext: Uint8Array): Uint8Array {
    const seq = sendSeq++
    const out = new Uint8Array(HEADER_BYTES + plaintext.length)
    out[0] = OUR_ROLE
    const view = new DataView(out.buffer)
    view.setUint32(1, Math.floor(seq / 0x100000000), true)
    view.setUint32(5, seq >>> 0, true)
    out.set(plaintext, HEADER_BYTES)
    return out
  }

  function sendEncrypted(plaintext: Uint8Array): boolean {
    if (!transport || !sessionKey || state !== 'ready') {
      return false
    }
    transport.send(encrypt(withHeader(plaintext), sessionKey))
    return true
  }

  // During the handshake the auth control frames must be sent before `state`
  // flips to 'ready', so this variant does not gate on state.
  function sendEncryptedHandshake(plaintext: Uint8Array): void {
    if (!transport || !sessionKey) {
      return
    }
    transport.send(encrypt(withHeader(plaintext), sessionKey))
  }

  function tagged(tag: number, body: Uint8Array): Uint8Array {
    const out = new Uint8Array(body.length + 1)
    out[0] = tag
    out.set(body, 1)
    return out
  }

  function fireReadyOnce(): void {
    if (readyFired) {
      return
    }
    readyFired = true
    reconnectAttempt = 0
    startKeepalive()
    opts.onReady()
  }

  function handleMessage(data: unknown): void {
    if (state === 'closed') {
      return
    }

    const asString = stringFromData(data)
    if (asString !== null) {
      // Plaintext JSON => a handshake control frame.
      handleControl(asString)
      return
    }

    const bytes = bytesFromData(data)
    if (!bytes) {
      return
    }

    // Everything binary is an E2EE box, sealed under the fresh session key.
    if (!sessionKey) {
      return
    }
    const sealed = decrypt(bytes, sessionKey)
    if (!sealed || sealed.length < HEADER_BYTES) {
      return
    }
    // Reject a box tagged with our OWN role (a reflected message) — only the peer's role is valid.
    if (sealed[0] !== PEER_ROLE) {
      return
    }
    // Enforce the strictly-increasing per-direction counter inside the authenticated plaintext.
    // A non-increasing counter means a replayed or reordered box — drop it.
    const seqView = new DataView(sealed.buffer, sealed.byteOffset, sealed.byteLength)
    const seq = seqView.getUint32(1, true) * 0x100000000 + seqView.getUint32(5, true)
    if (seq <= recvSeq) {
      return
    }
    recvSeq = seq
    const plain = sealed.subarray(HEADER_BYTES)

    if (state === 'handshaking') {
      handleHandshakeEncrypted(plain)
      return
    }
    if (state !== 'ready') {
      return
    }
    handlePeerPlaintext(plain)
  }

  function handleControl(raw: string): void {
    // SECURITY: a handshake control frame (`e2ee_hello` / `e2ee_ready`) is legitimate ONLY during the
    // one handshake, i.e. before the session goes ready. Once ready, re-processing one would let a
    // relay MITM RE-KEY a live session under its own keypair (re-deriving baseKey/sessionKey and
    // overwriting peerPubB64) and then forge the peer's encrypted `trust:confirm` under the swapped
    // key — degrading mutual approval to one-way (see docs/remote-sessions.md, obligation (a)). The
    // real peer never re-sends a hello on an established session, so such a frame is an attack or a
    // bug, never legitimate. Drop it WITHOUT re-keying: the derived session identity (SAS + peer key)
    // stays frozen. We do NOT close the socket — the relay already fully controls the transport
    // (it can drop us at will), so closing would add no real protection while handing a MITM a
    // trivial way to tear down an established, mutually-approved session with one plaintext frame.
    // Ignoring keeps the good session robust; layer 2 (relay-host key binding) independently
    // guarantees no traffic or approval can advance under a swapped key even if this check regressed.
    if (readyFired) {
      return
    }
    let control: HandshakeControl
    try {
      control = JSON.parse(raw) as HandshakeControl
    } catch {
      return
    }
    if (control.type === 'e2ee_hello' && opts.role === 'host') {
      // Host learns the client pubkey + its session nonce, derives the base identity key and the
      // fresh session traffic key, replies ready with its own nonce.
      const clientNonce = nonceFromB64(control.nonceB64)
      if (typeof control.publicKeyB64 !== 'string' || !clientNonce || !ourNonce) {
        return
      }
      // Refuse a key that is not canonical base64 or is a LOW-ORDER point (WeakPeerKeyError): with
      // the latter the shared secret is a public constant — a secret-less peer would complete the
      // handshake, both humans would read the same fixed SAS, and anyone on the wire could derive
      // the session key. FAIL CLOSED: no key is learned or bound (peerPubB64 is set only after a
      // successful derive, so nothing can pin or auto-approve the refused key), no `e2ee_ready` is
      // sent, and the transport is closed so the caller's onClose runs its usual teardown. Never a
      // throw here: this runs inside the WebSocket's synchronous message emit.
      let derived: Uint8Array
      try {
        derived = deriveSharedKey(control.publicKeyB64, opts.ourKeys.secretKey)
      } catch (err) {
        console.warn(`[relay] refused a peer handshake key: ${err instanceof Error ? err.message : String(err)}`)
        transport?.close()
        return
      }
      peerPubB64 = control.publicKeyB64
      baseKey = derived
      // salt = hostNonce ‖ clientNonce (host's nonce first, both roles agree on the order).
      sessionKey = deriveSessionKey(baseKey, ourNonce, clientNonce)
      sendControl({ type: 'e2ee_ready', nonceB64: nonceToB64(ourNonce) })
      return
    }
    if (control.type === 'e2ee_ready' && opts.role === 'client') {
      // Client learns the host's nonce, derives the same session key, and proves the pairing with
      // an encrypted auth marker. The marker is sealed under the SESSION key (which mixes in this
      // session's fresh nonces), so a recorded auth box from an earlier session can't be replayed
      // to silently authenticate a new one.
      const hostNonce = nonceFromB64(control.nonceB64)
      if (!hostNonce || !baseKey || !ourNonce) {
        return
      }
      sessionKey = deriveSessionKey(baseKey, hostNonce, ourNonce)
      sendEncryptedHandshake(tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ type: 'e2ee_auth' }))))
    }
  }

  function handleHandshakeEncrypted(plain: Uint8Array): void {
    // Tag byte distinguishes control vs payload; during handshake we only expect
    // control JSON (auth / authenticated).
    if (plain.length < 1 || plain[0] !== TAG_RPC) {
      return
    }
    let msg: { type?: string }
    try {
      msg = JSON.parse(textDecoder.decode(plain.subarray(1))) as { type?: string }
    } catch {
      return
    }
    if (msg.type === 'e2ee_auth' && opts.role === 'host') {
      // Host accepts the client's authenticated marker, confirms, becomes ready.
      sendEncryptedHandshake(
        tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ type: 'e2ee_authenticated' })))
      )
      state = 'ready'
      fireReadyOnce()
      return
    }
    if (msg.type === 'e2ee_authenticated' && opts.role === 'client') {
      state = 'ready'
      fireReadyOnce()
    }
  }

  function handlePeerPlaintext(plain: Uint8Array): void {
    if (plain.length < 1) {
      return
    }
    const tag = plain[0]
    const body = plain.subarray(1)
    if (tag === TAG_TUNNEL_TEXT) {
      opts.onTunnel?.('text', body)
      return
    }
    if (tag === TAG_TUNNEL_BIN) {
      opts.onTunnel?.('binary', body)
      return
    }
    if (tag === TAG_FRAME) {
      const frame = decodeFrame(body)
      if (frame) {
        opts.onFrame(frame)
      }
      return
    }
    if (tag !== TAG_RPC) {
      return
    }
    let env: RpcEnvelope
    try {
      env = JSON.parse(textDecoder.decode(body)) as RpcEnvelope
    } catch {
      return
    }
    if (env.kind === 'keepalive') {
      return
    }
    if (env.kind === 'req') {
      opts.onRpc({ id: env.id, method: env.method, params: env.params })
      return
    }
    if (env.kind === 'notify') {
      // One-way notification: surface it like an RPC but with an empty id, so a
      // `respond` (if any) is a no-op (no matching pending request on our side).
      opts.onRpc({ id: '', method: env.method, params: env.params })
      return
    }
    if (env.kind === 'res') {
      const waiter = pending.get(env.id)
      if (!waiter) {
        return
      }
      pending.delete(env.id)
      clearTimeout(waiter.timer)
      if (env.ok) {
        waiter.resolve(env.body)
      } else {
        waiter.reject(new Error(rpcErrorMessage(env.body)))
      }
    }
  }

  function startKeepalive(): void {
    stopKeepalive()
    keepaliveTimer = setInterval(() => {
      sendEncrypted(tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ kind: 'keepalive' }))))
    }, KEEPALIVE_INTERVAL_MS)
    // Don't keep the event loop alive purely for keepalives.
    keepaliveTimer.unref?.()
  }

  function stopKeepalive(): void {
    if (keepaliveTimer) {
      clearInterval(keepaliveTimer)
      keepaliveTimer = null
    }
  }

  function handleClose(): void {
    stopKeepalive()
    transport = null
    baseKey = null
    sessionKey = null
    const wasReady = state === 'ready'
    rejectAllPending('Relay connection closed.')
    if (intentionallyClosed) {
      state = 'closed'
      return
    }
    state = 'closed'
    // Reconnect is the CALLER's responsibility (via onClose), NOT this socket's. Re-dialing here
    // would reuse the same pairing token, which the relay rejects after its short TTL — and worse,
    // for a standing host it fights the caller's fresh-token reconnect, repeatedly clobbering the
    // new session so the connection never restabilises. So we fire onClose once and stop; the
    // standing host mints a fresh token and reconnects cleanly.
    void wasReady
    opts.onClose()
  }

  // (Internal same-token reconnect removed — see handleClose. The caller reconnects with a fresh
  // token.)
  function scheduleReconnect(): void {
    if (reconnectTimer || intentionallyClosed) {
      return
    }
    const delay = RECONNECT_DELAYS_MS[Math.min(reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)]
    reconnectAttempt += 1
    reconnectTimer = setTimeout(() => {
      reconnectTimer = null
      openConnection()
    }, delay)
    reconnectTimer.unref?.()
  }

  function rejectAllPending(reason: string): void {
    const err = new Error(reason)
    for (const [id, waiter] of pending) {
      pending.delete(id)
      clearTimeout(waiter.timer)
      waiter.reject(err)
    }
  }

  function nextId(): string {
    requestCounter += 1
    return `${opts.role}-rpc-${requestCounter}-${Date.now()}`
  }

  openConnection()

  return {
    rpc(method, params) {
      return new Promise((resolve, reject) => {
        const id = nextId()
        const timer = setTimeout(() => {
          pending.delete(id)
          reject(new Error(`RPC timed out: ${method}`))
        }, RPC_TIMEOUT_MS)
        timer.unref?.()
        pending.set(id, { resolve, reject, timer })
        const sent = sendEncrypted(
          tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ kind: 'req', id, method, params })))
        )
        if (!sent) {
          pending.delete(id)
          clearTimeout(timer)
          reject(new Error('Relay socket is not connected.'))
        }
      })
    },
    notify(method, params) {
      return sendEncrypted(
        tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ kind: 'notify', method, params })))
      )
    },
    respond(id, ok, body) {
      sendEncrypted(tagged(TAG_RPC, textEncoder.encode(JSON.stringify({ kind: 'res', id, ok, body }))))
    },
    sendFrame(op, streamId, seq, payload) {
      if (!transport || state !== 'ready') {
        return false
      }
      if (transport.bufferedAmount > MAX_BINARY_BUFFERED_AMOUNT) {
        return false
      }
      return sendEncrypted(tagged(TAG_FRAME, encodeFrame(op, streamId, seq, payload)))
    },
    sendTunnelText(json) {
      return sendEncrypted(tagged(TAG_TUNNEL_TEXT, textEncoder.encode(json)))
    },
    sendTunnelBinary(bytes) {
      return sendEncrypted(tagged(TAG_TUNNEL_BIN, bytes))
    },
    bufferedAmount() {
      // Honest by construction: the transport reports what it has been handed and has not yet
      // flushed. No backpressure decision is made here — the caller (ui-sink-registry) owns the
      // thresholds; this only has to tell the truth. Not connected => nothing is queued => 0.
      return transport?.bufferedAmount ?? 0
    },
    sas() {
      return baseKey ? sasFromSharedKey(baseKey) : null
    },
    peerPublicKeyB64() {
      return peerPubB64
    },
    close() {
      intentionallyClosed = true
      if (reconnectTimer) {
        clearTimeout(reconnectTimer)
        reconnectTimer = null
      }
      stopKeepalive()
      rejectAllPending('Relay socket closed.')
      state = 'closed'
      transport?.close()
      transport = null
      baseKey = null
      sessionKey = null
    }
  }
}

function rpcErrorMessage(body: unknown): string {
  if (body && typeof body === 'object') {
    const maybe = body as { message?: unknown; error?: unknown }
    if (typeof maybe.message === 'string') {
      return maybe.message
    }
    if (typeof maybe.error === 'string') {
      return maybe.error
    }
  }
  return 'RPC failed.'
}

// --- transport payload coercion ---------------------------------------------

function stringFromData(data: unknown): string | null {
  if (typeof data === 'string') {
    return data
  }
  return null
}

function bytesFromData(data: unknown): Uint8Array | null {
  if (data instanceof Uint8Array) {
    return data
  }
  if (data instanceof ArrayBuffer) {
    return new Uint8Array(data)
  }
  // `ws` may deliver a Node Buffer (which is a Uint8Array) or an array of
  // Buffers when fragmented; handle the array case defensively.
  if (Array.isArray(data) && data.every((d) => d instanceof Uint8Array)) {
    const total = data.reduce((n, d) => n + (d as Uint8Array).length, 0)
    const out = new Uint8Array(total)
    let offset = 0
    for (const d of data as Uint8Array[]) {
      out.set(d, offset)
      offset += d.length
    }
    return out
  }
  return null
}

// --- production ws wrapper ----------------------------------------------------

// Wrap a connected `ws` WebSocket as a RelayTransport. Kept here so the host
// (Task 6) and client (Task 7) share one ws adapter. Imported lazily so the
// pure module + its tests never load `ws`.
export function wrapWebSocket(ws: import('ws').WebSocket): RelayTransport {
  ws.binaryType = 'nodebuffer'
  return {
    get bufferedAmount() {
      return ws.bufferedAmount
    },
    // Strings (handshake control) go out as ws *text* frames; Uint8Array (E2EE boxes) as ws
    // *binary*. The relay preserves that text/binary-ness end to end.
    send: (data) => ws.send(data, { binary: typeof data !== 'string' }),
    close: () => ws.close(),
    // Deliver ws *text* frames as JS strings and *binary* frames as bytes, so relay-socket's
    // type-based control-vs-box discrimination works. (`ws` hands us a Buffer for both unless we
    // consult `isBinary`.)
    onMessage: (cb) =>
      ws.on('message', (data: Buffer, isBinary: boolean) =>
        cb(isBinary ? data : data.toString('utf-8'))
      ),
    onClose: (cb) => {
      // Fire `cb` on EITHER a close OR an error, exactly once. A ws `error` (a 504 upgrade timeout,
      // a TLS/DNS failure, connection refused) is otherwise an UNHANDLED 'error' event, which Node
      // re-throws as an uncaught exception that crashes the whole app. Treat it as a close so the
      // caller tears the session down / reconnects gracefully instead. The caller registers this
      // synchronously right after opening (relay-socket connectRelay), before any async error fires.
      let fired = false
      const fire = (): void => {
        if (fired) return
        fired = true
        cb()
      }
      ws.on('close', fire)
      ws.on('error', fire)
    }
  }
}

// Open a `ws` WebSocket to `url` and return it wrapped. Sends start only once
// the socket is open; messages before open are dropped (the handshake retries on
// reconnect). Used as the production default when no transport is injected.
function openWebSocketTransport(url: string): RelayTransport {
  // Lazy require so test/pure consumers don't pull in the native-ish dep.
  // eslint-disable-next-line @typescript-eslint/no-var-requires
  const WS = require('ws') as typeof import('ws')
  const ws = new WS.WebSocket(url)
  ws.binaryType = 'nodebuffer'
  const wrapped = wrapWebSocket(ws)
  // Buffer sends issued before 'open'.
  const queue: (string | Uint8Array)[] = []
  let open = false
  // Bytes sitting in `queue`. They are real, un-flushed bytes that `ws.bufferedAmount` cannot see
  // (the socket has not been handed them yet), so leaving them out would make bufferedAmount lie
  // during exactly the window in which a burst can pile up — and a backpressure ceiling that
  // believes the lie stops capping, letting the host queue pty output without bound.
  let queuedBytes = 0
  ws.on('open', () => {
    open = true
    for (const item of queue.splice(0)) {
      ws.send(item)
    }
    queuedBytes = 0
  })
  return {
    get bufferedAmount() {
      return ws.bufferedAmount + queuedBytes
    },
    send: (data) => {
      if (open) {
        ws.send(data)
      } else {
        queue.push(data)
        queuedBytes += typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength
      }
    },
    close: () => ws.close(),
    onMessage: wrapped.onMessage,
    onClose: wrapped.onClose
  }
}