checkpoint, switching to node native typescript

src/client/components/messenger.jsx

···
+// @ts-nocheck
+
+import * as connection_types from '#client/realm/connection.js'
+import * as protocol_types from '#common/protocol.js'
+import { useState, useEffect, useCallback } from 'preact/hooks'
+
+/**
+ * @param {object} props list props
+ * @param {connection_types.RealmConnection} props.webrtcManager connection manager
+ * @returns {preact.JSX.Element} the peerlist component
+ */
+export function Messenger({ webrtcManager }) {
+  const [messages, setMessages] = useState(/** @type {Array<any>} */ [])
+
+  const peerdata = useCallback(
+    /** @type {function(CustomEvent): void} */
+    (event) => {
+      setMessages([...messages, [event.detail.remoteId, event.detail.data]])
+    },
+    [messages],
+  )
+
+  const sendMessage = useCallback(
+    () => {
+      webrtcManager.broadcast('what\'s up friends?')
+    },
+    [webrtcManager],
+  )
+
+  useEffect(() => {
+    if (!webrtcManager) return
+
+    webrtcManager.addEventListener('peerdata', peerdata)
+    return () => {
+      webrtcManager.removeEventListener('peerdata', peerdata)
+    }
+  }, [webrtcManager, peerdata])
+
+  return (
+    <div className="messages-list">
+      <h3>Realm Messages</h3>
+      <pre>
+        { JSON.stringify(messages, null, 2) }
+      </pre>
+      <div>
+        <textarea />
+        <button onClick={sendMessage}>Send</button>
+      </div>
+    </div>
+  )
+}

src/client/components/peer-list.jsx

···
+import * as connection_types from '#client/realm/connection.js'
+import * as protocol_types from '#common/protocol.js'
+import { useState, useEffect } from 'preact/hooks'
+
+/**
+ * @param {object} props list props
+ * @param {connection_types.RealmConnection} props.webrtcManager connection manager
+ * @returns {preact.JSX.Element} the peerlist component
+ */
+export function PeerList({ webrtcManager }) {
+  const [peers, setPeers] = useState(
+    /** @type {Record<protocol_types.IdentID, connection_types.PeerState>} */ ({}),
+  )
+
+  useEffect(() => {
+    if (!webrtcManager) return
+
+    const updatePeers = () => {
+      queueMicrotask(() => {
+        const states = webrtcManager.getPeerStates()
+        console.log('updating peers', states)
+        setPeers(states)
+      })
+    }
+
+    // Listen to WebRTC events
+    const events = ['peeropen', 'peerclose']
+
+    events.forEach((event) => {
+      webrtcManager.addEventListener(event, updatePeers)
+    })
+
+    // Initial state
+    updatePeers()
+
+    return () => {
+      events.forEach((event) => {
+        webrtcManager.removeEventListener(event, updatePeers)
+      })
+    }
+  }, [webrtcManager])
+
+  return (
+    <div className="peer-list">
+      <h3>Realm Members</h3>
+      {
+        Object.keys(peers).length === 0
+          ? <p>No other peers connected</p>
+          : (
+              <ul>
+                {Object.entries(peers).map(([peerId, state]) => (
+                  <li key={peerId} className={`peer-item ${state.state}`}>
+                    <span className="peer-id">{peerId}</span>
+                    <ConnectionStatus state={state} />
+                  </li>
+                ))}
+              </ul>
+            )
+      }
+    </div>
+  )
+}
+
+/**
+ * @private
+ * @param {object} props status props
+ * @param {connection_types.PeerState} props.state current state
+ * @returns {preact.JSX.Element} the status component
+ */
+function ConnectionStatus({ state }) {
+  const getStatusIcon = () => {
+    if (state.connected) return '🟢'
+    if (state.destroyed) return '🔴'
+    return '🟡'
+  }
+
+  return (
+    <div className="connection-status">
+      <span className="status-icon">{getStatusIcon()}</span>
+      <code className="initiator">
+        {state.address.family}
+        -
+        {state.address.address}
+        :
+        {state.address.port}
+      </code>
+    </div>
+  )
+}

src/client/index.css

···
-:root {
-  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
-  line-height: 1.5;
-  font-weight: 400;
-
-  color-scheme: light dark;
-  color: rgba(255, 255, 255, 0.87);
-  background-color: #242424;
-
-  font-synthesis: none;
-  text-rendering: optimizeLegibility;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-a {
-  font-weight: 500;
-  color: #646cff;
-  text-decoration: inherit;
-}
-a:hover {
-  color: #535bf2;
-}
-
-body {
-  margin: 0;
-  display: flex;
-  place-items: center;
-  min-width: 320px;
-  min-height: 100vh;
-}
-
-h1 {
-  font-size: 3.2em;
-  line-height: 1.1;
-}
-
-button {
-  border-radius: 8px;
-  border: 1px solid transparent;
-  padding: 0.6em 1.2em;
-  font-size: 1em;
-  font-weight: 500;
-  font-family: inherit;
-  background-color: #1a1a1a;
-  cursor: pointer;
-  transition: border-color 0.25s;
-}
-button:hover {
-  border-color: #646cff;
-}
-button:focus,
-button:focus-visible {
-  outline: 4px auto -webkit-focus-ring-color;
-}
-
-@media (prefers-color-scheme: light) {
-  :root {
-    color: #213547;
-    background-color: #ffffff;
-  }
-  a:hover {
-    color: #747bff;
-  }
-  button {
-    background-color: #f9f9f9;
-  }
-}

src/client/page-app.jsx

···
-import './page-app.css'
+import { RealmConnectionProvider } from './realm/context.jsx'
+import { WebRTCDemo } from './webrtc-demo.jsx'
 
 /**
  * @returns {preact.JSX.Element} app wrapper component
  */
 export function App() {
   return (
-    <>
-      <h1>whatever</h1>
-      <h2>and, how!</h2>
-    </>
+    <RealmConnectionProvider url="ws://localhost:3001/stream">
+      <WebRTCDemo />
+    </RealmConnectionProvider>
   )
 }

src/client/page-app.spec.jsx

···
-/** @jest-environment jsdom */
+/** @jest-environment jest-fixed-jsdom */
 
 import { describe, it, expect } from '@jest/globals'
 

src/client/realm/connection.js

···
+/** @module client/realm */
+
+import { nanoid } from 'nanoid'
+import SimplePeer from 'simple-peer'
+
+import { generateSignableJwt, jwkExport } from '#common/crypto/jwks.js'
+import { normalizeError, normalizeProtocolError, ProtocolError } from '#common/errors.js'
+import { parseJson, realmFromServerMessageSchema, realmRtcPeerWelcomeMessageSchema } from '#common/protocol.js'
+import { sendSocket, streamSocket, streamSocketJson, takeSocketJson } from '#common/socket.js'
+
+import * as protocol_types from '#common/protocol.js'
+
+/**
+ * @typedef {object} PeerState
+ * @property {ReturnType<SimplePeer.Instance['address']>} address peer address
+ * @property {boolean} connected true if the peer connection is active
+ * @property {boolean} destroyed true if the peer connection has been destroyed
+ * @property {string} state a simple status string
+ */
+
+/**
+ * @typedef {object} RealmIdentity
+ * @property {protocol_types.RealmID} realmid
+ * @property {protocol_types.IdentID} identid
+ * @property {CryptoKeyPair} keypair
+ */
+
+/**
+ * A connection manager
+ */
+export class RealmConnection extends EventTarget {
+
+  /** @type {string} */
+  #url
+
+  /** @type {RealmIdentity} */
+  #identity
+
+  /** @type {WebSocket} */
+  #socket
+
+  /** @type {Map<protocol_types.IdentID, SimplePeer.Instance>} */
+  #peers
+
+  /** @type {Map<protocol_types.IdentID, string>} */
+  #nonces
+
+  /**
+   * @param {string} url the realm server we're connecting to
+   * @param {RealmIdentity} identity this connection's realm identity
+   */
+  constructor(url, identity) {
+    super()
+
+    this.#url = url
+    this.#identity = identity
+
+    this.#peers = new Map()
+    this.#nonces = new Map()
+
+    this.#socket = new WebSocket(this.#url)
+    this.#socket.onopen = this.#handleSocketOpen
+    this.#socket.onclose = this.#handleSocketClose
+    this.#socket.onerror = this.#handleSocketError
+  }
+
+  /** @type {WebSocket['onopen']} */
+  #handleSocketOpen = async () => {
+    if (this.#socket == undefined)
+      throw new Error('socket open handler called with no socket?')
+
+    try {
+      console.debug('realm connection, socket loop open')
+      this.#dispatchCustomEvent('wsopen')
+
+      // do the auth dance
+      // TODO: this should be a state machine
+
+      const pubkey = await jwkExport.parseAsync(this.#identity.keypair.publicKey)
+      this.#socket.send(
+        await this.#signJwt(
+          /** @type {protocol_types.PreauthRegisterMessage} */
+          ({ msg: 'preauth.register', pubkey }),
+        ),
+      )
+
+      // the next message should be a welcome message
+      // this will throw (authenticated) otherwise
+
+      /** @type {protocol_types.RealmRtcPeerWelcomeMessage} */
+      let welcome
+      try {
+        welcome = await takeSocketJson(this.#socket, realmRtcPeerWelcomeMessageSchema)
+      }
+      catch (exc) {
+        const err = normalizeError(exc)
+        throw new ProtocolError('failure on authentication', 401, { cause: err })
+      }
+
+      this.#dispatchCustomEvent('wsauth', { welcome })
+
+      // we initiate connections outbound when starting up
+      // we never initiate connections to other peers otherwise
+
+      for (const peerid of welcome.peers) {
+        if (peerid === this.#identity.identid) continue
+        this.connectToPeer(peerid, true)
+      }
+
+      // then continue looping over messages on the socket and handle them
+
+      for await (const data of streamSocketJson(this.#socket)) {
+        const parse = realmFromServerMessageSchema.safeParse(data)
+
+        // not a known rtc specific message, so we don't capture it
+        if (!parse.success) {
+          this.#dispatchCustomEvent('wsdata', { data })
+          continue
+        }
+
+        // otherwise, we handle it
+        switch (parse.data.msg) {
+          case 'realm.rtc.peer-joined':
+            // new peers connect to us, we don't connect to them
+            this.#dispatchCustomEvent('peerjoined', { identid: parse.data.identid })
+            continue
+
+          case 'realm.rtc.peer-left':
+            // peer is gone, disconnect
+            this.disconnectPeer(parse.data.identid)
+            this.#dispatchCustomEvent('peerleft', { identid: parse.data.identid })
+            continue
+
+          case 'realm.rtc.signal': {
+            // some other peer is trying to send us some rtc data
+            // only connect if _they_ are the initiator - our initiating conns were above
+            let peer = this.#peers.get(parse.data.sender)
+            if (!peer && parse.data.initiator) {
+              peer = this.connectToPeer(parse.data.sender, false)
+            }
+
+            // may not have a connection yet if we're waiting for them to answer
+            if (peer) {
+              peer.signal(JSON.parse(parse.data.payload))
+            }
+
+            continue
+          }
+        }
+      }
+    }
+    catch (exc) {
+      const err = normalizeProtocolError(exc)
+
+      console.error('realm connection, socket loop error', err)
+      this.#dispatchCustomEvent('wserror', { error: err })
+    }
+    finally {
+      console.debug('realm connection, socket loop ended')
+      this.destroy()
+    }
+  }
+
+  /** @type {WebSocket['onerror']} */
+  #handleSocketError = async (exc) => {
+    this.#dispatchCustomEvent('wserror', { error: normalizeProtocolError(exc) })
+    this.destroy()
+  }
+
+  /** @type {WebSocket['onclose']} */
+  #handleSocketClose = async () => {
+    this.#dispatchCustomEvent('wsclose')
+    this.destroy()
+  }
+
+  get connected() {
+    return this.#socket.readyState === this.#socket.OPEN
+  }
+
+  destroy() {
+    console.debug('realm connection #destroy!')
+
+    if (this.connected)
+      this.#socket.close()
+
+    for (const peer of this.#peers.values())
+      peer.destroy()
+
+    this.#peers.clear()
+    this.#nonces.clear()
+  }
+
+  /**
+   * dispatch a `CustomEvent`
+   *
+   * @param {string} type the event type (for addEVentListener(type))
+   * @param {object} [detail] the details object to include
+   */
+  #dispatchCustomEvent(type, detail) {
+    this.dispatchEvent(new CustomEvent(type, { detail }))
+  }
+
+  /**
+   * generates and signs a JWT scoped to this identity/realm containing the given payload
+   *
+   * @param {object} payload the payload to embed in the JWT
+   * @returns {Promise<string>} a signed JWT for sending upstream
+   */
+  async #signJwt(payload) {
+    return await generateSignableJwt({
+      aud: this.#identity.realmid,
+      iss: this.#identity.identid,
+      payload,
+    }).sign(this.#identity.keypair.privateKey)
+  }
+
+  /**
+   * @private
+   * @param {protocol_types.IdentID} remoteid the identity we're connecting to
+   * @param {boolean} initiator are we the initiator of this connection?
+   * @returns {SimplePeer.Instance} the configured peer for the identid
+   */
+  connectToPeer(remoteid, initiator) {
+    let peer = this.#peers.get(remoteid)
+    if (peer) {
+      console.log(`already connected to ${remoteid}`)
+      return peer
+    }
+
+    peer = new RealmConnectionPeer(
+      this,
+      nanoid(),
+      this.#identity.identid,
+      remoteid,
+      initiator,
+    )
+
+    peer.on('connect', () => {
+      console.log(`connected to ${remoteid}`)
+
+      this.#dispatchCustomEvent('peeropen', { remoteid })
+    })
+
+    peer.on('close', () => {
+      console.log(`Disconnected from ${remoteid}`)
+
+      this.#peers.delete(remoteid)
+      this.#nonces.delete(remoteid)
+      this.#dispatchCustomEvent('peerclose', { remoteid })
+    })
+
+    peer.on('error', (err) => {
+      console.error(`Error with peer ${remoteid}:`, err)
+
+      this.#dispatchCustomEvent('peererror', { remoteid, error: err })
+    })
+
+    peer.on('message', (data) => {
+      this.#dispatchCustomEvent('peerdata', { remoteid, data })
+    })
+
+    this.#peers.set(remoteid, peer)
+    return peer
+  }
+
+  /** @param {protocol_types.IdentID} identid the recipient to disconnect from */
+  disconnectPeer(identid) {
+    const peer = this.#peers.get(identid)
+    if (peer) {
+      peer.destroy()
+      this.#peers.delete(identid)
+      this.#nonces.delete(identid)
+    }
+  }
+
+  /**
+   * @param {protocol_types.IdentID} identid the recipient to send data to
+   * @param {any} data the data to send via peer connection
+   */
+  sendToPeer(identid, data) {
+    const peer = this.#peers.get(identid)
+    if (peer && peer.connected) {
+      peer.send(JSON.stringify(data))
+    }
+    else {
+      throw new Error(`Not connected to peer: ${identid}`)
+    }
+  }
+
+  /**
+   * @param {unknown} data to send along the socket to the realm server
+   */
+  sendToServer(data) {
+    sendSocket(this.#socket, data)
+  }
+
+  /** @param {any} data the data to send via peer connection */
+  broadcast(data) {
+    const message = JSON.stringify(data)
+    for (const [_, peer] of this.#peers) {
+      if (peer.connected) {
+        peer.send(message)
+      }
+    }
+  }
+
+  /** @param {any} data the data to send via server */
+  broadcastViaServer(data) {
+    /** @type {protocol_types.RealmBroadcastMessage} */
+    const resp = {
+      msg: 'realm.broadcast',
+      payload: data,
+      recipients: false,
+    }
+    sendSocket(this.#socket, resp)
+  }
+
+  /**
+   * @returns {Record<protocol_types.IdentID, PeerState>} the current peer state mapping
+   */
+  getPeerStates() {
+    /** @type {Record<protocol_types.IdentID, PeerState>} */
+    const states = {}
+
+    for (const [peerId, peer] of this.#peers) {
+      states[peerId] = {
+        address: peer.address(),
+        connected: peer.connected,
+        destroyed: peer.destroyed,
+        state: peer.connected ? 'connected' : 'disconnected',
+      }
+    }
+
+    return states
+  }
+
+}
+
+/**
+ * a peer belonging to the connection manager
+ */
+export class RealmConnectionPeer extends SimplePeer {
+
+  /** @type {RealmConnection} */
+  #connection
+
+  /** @type {boolean} */
+  initiator
+
+  /** @type {protocol_types.IdentID} */
+  localid
+
+  /** @type {protocol_types.IdentID} */
+  remoteid
+
+  /** @type {string} */
+  nonce
+
+  /**
+   * @param {RealmConnection} connection the connection that owns this peer
+   * @param {string} nonce a uniquely identifying string for this peer
+   * @param {protocol_types.IdentID} localid the local identity
+   * @param {protocol_types.IdentID} remoteid the remote identity
+   * @param {boolean} initiator whether we're initiating the connection
+   */
+  constructor(connection, nonce, localid, remoteid, initiator) {
+    super({
+      initiator,
+      config: {
+        iceServers: [
+          { urls: 'stun:stun.l.google.com:19302' },
+          { urls: 'stun:stun1.l.google.com:19302' },
+        ],
+      },
+    })
+
+    this.initiator = initiator
+    this.localid = localid
+    this.remoteid = remoteid
+    this.nonce = nonce
+
+    this.#connection = connection
+
+    this.on('signal', this.#handlePeerSignal)
+    this.on('data', this.#handlePeerData)
+  }
+
+  /** @type {function(SimplePeer.SignalData): void} */
+  #handlePeerSignal = (e) => {
+    this.#connection.sendToServer(
+      /** @type {protocol_types.RealmRtcSignalMessage} */
+      ({
+        msg: 'realm.rtc.signal',
+        initiator: this.initiator,
+        sender: this.localid,
+        recipient: this.remoteid,
+        payload: JSON.stringify(e),
+      }),
+    )
+  }
+
+  /** @type {function(string): void} */
+  #handlePeerData = (chunk) => {
+    try {
+      const parsed = JSON.parse(chunk)
+      switch (parsed.type) {
+        // there are some connection-manager internal messages
+        case 'pong':
+          this.send(
+            JSON.stringify({ type: 'pong', timestamp: parsed.timestamp }),
+          )
+          break
+
+        // dispatch others messages
+        default:
+          this.emit('message', parsed)
+          break
+      }
+    }
+    catch (err) {
+      console.error('Failed to parse message:', err)
+    }
+  }
+
+}

src/client/realm/context.jsx

···
+import { createContext } from 'preact'
+import * as preact_types from 'preact'
+import * as connection_types from '#client/realm/connection.js'
+
+import { RealmConnection } from '#client/realm/connection.js'
+import { useCallback, useEffect, useState } from 'preact/hooks'
+
+/**
+ * @typedef {object} RealmConnectionContext
+ * @property {RealmConnection | null} realm the realm server we're connected to
+ * @property {connection_types.RealmIdentity | null} identity the realm identity we're connected as
+ * @property {function(connection_types.RealmIdentity): void} setIdentity
+ * a callback to set the current identity
+ */
+
+export const RealmConnectionContext
+  = createContext(/** @type {RealmConnectionContext | null} */ (null))
+
+/**
+ * @typedef {object} RealmConnectionProviderProps
+ * @property {string} url the realm server to connect to
+ * @property {preact_types.ComponentChildren} children the children to render
+ */
+
+/**
+ * @type {preact.FunctionComponent<RealmConnectionProviderProps>}
+ */
+export const RealmConnectionProvider = (props) => {
+  const [identity$, setIdentity$]
+    = useState(/** @type {connection_types.RealmIdentity | null} */ (null))
+
+  const [connection$, setConnection$]
+    = useState(/** @type {RealmConnection | null} */ (null))
+
+  const connect = useCallback(
+    () => {
+      if (connection$) return
+      if (!identity$) return
+
+      const connection = new RealmConnection(props.url, identity$)
+      setConnection$(connection)
+    },
+    [connection$, identity$, props.url],
+  )
+
+  const disconnect = useCallback(
+    () => {
+      connection$?.destroy()
+    },
+    [connection$],
+  )
+
+  useEffect(
+    () => {
+      console.log('use effect in provider', identity$)
+      // connect on mount, or identity change
+      if (identity$) connect()
+
+      // disconnect on unsubscribe
+      return disconnect
+    },
+    [connect, disconnect, identity$],
+  )
+
+  return (
+    <RealmConnectionContext.Provider
+      children={props.children}
+      value={{
+        realm: connection$,
+        identity: identity$,
+        setIdentity: setIdentity$,
+      }}
+    />
+  )
+}

src/client/webrtc-demo.css

···
+.webrtc-demo {
+  padding: 20px;
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+.connection-info {
+  background: #f0f0f0;
+  padding: 10px;
+  border-radius: 5px;
+  margin-bottom: 20px;
+}
+
+.connection-info p {
+  margin: 5px 0;
+}
+
+.demo-layout {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
+}
+
+.demo-section {
+  background: #f9f9f9;
+  padding: 15px;
+  border-radius: 5px;
+  border: 1px solid #ddd;
+}
+
+.demo-section h3 {
+  margin-top: 0;
+}
+
+/* Peer List Styles */
+.peer-list ul {
+  list-style: none;
+  padding: 0;
+}
+
+.peer-item {
+  padding: 5px;
+  margin: 5px 0;
+  background: white;
+  border-radius: 3px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.peer-id {
+  font-family: monospace;
+  font-size: 12px;
+}
+
+.connection-status {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 12px;
+}
+
+.status-icon {
+  font-size: 10px;
+}
+
+.initiator {
+  color: #666;
+  font-size: 11px;
+}
+
+/* Message Interface Styles */
+.broadcast-mode {
+  margin-bottom: 10px;
+}
+
+.broadcast-mode label {
+  margin-right: 15px;
+}
+
+.message-list {
+  height: 200px;
+  overflow-y: auto;
+  background: white;
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 3px;
+  margin-bottom: 10px;
+}
+
+.message {
+  margin: 5px 0;
+}
+
+.message .sender {
+  font-weight: bold;
+  margin-right: 5px;
+}
+
+.message .via {
+  color: #666;
+  font-size: 12px;
+  margin-left: 5px;
+}
+
+.message-input {
+  display: flex;
+  gap: 10px;
+}
+
+.message-input input {
+  flex: 1;
+  padding: 5px;
+}
+
+/* System Messages */
+.system-messages {
+  height: 200px;
+  overflow-y: auto;
+  background: white;
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 3px;
+  font-size: 12px;
+}
+
+.system-message {
+  margin: 3px 0;
+}
+
+.system-message.error {
+  color: #d00;
+}
+
+.system-message.info {
+  color: #333;
+}
+
+.system-message .timestamp {
+  color: #666;
+  margin-right: 5px;
+}
+
+.system-message .from {
+  font-weight: bold;
+  margin: 0 5px;
+}

src/client/webrtc-demo.jsx

···
+// @ts-nocheck
+
+import { useEffect, useContext, useCallback } from 'preact/hooks'
+
+import { RealmConnectionContext } from '#client/realm/context.jsx'
+import { PeerList } from '#client/components/peer-list.jsx'
+
+import * as protocol from '#common/protocol.js'
+import { generateSigningJwkPair } from '#common/crypto/jwks.js'
+import { Messenger } from './components/messenger'
+
+/**
+ * @private
+ * @param {EventTarget} target event target to attach
+ * @param {string} name the name of the event to listen to
+ * @param {function(): void} listener the listener to add
+ * @returns {function(): void} the listener, for removing later
+ */
+function attachEventListener(target, name, listener) {
+  target.addEventListener(name, listener)
+  return listener
+}
+
+/**
+ * @private
+ * @returns {preact.JSX.Element}
+ */
+export function WebRTCDemo() {
+  const context = useContext(RealmConnectionContext)
+  if (!context)
+    throw new Error('expected to be called inside realm connection context!')
+
+  useEffect(() => {
+    if (!context.realm) return
+
+    /* setup event listeners on the socket */
+
+    const wsopen = attachEventListener(context.realm, 'wsopen', () => {
+      console.log('connection socket open!')
+    })
+
+    const wsdata = attachEventListener(context.realm, 'wsdata', (e) => {
+      console.log('connection socket data!', e)
+    })
+
+    const wserror = attachEventListener(context.realm, 'wserror', (e) => {
+      console.log('connection socket error!', e)
+    })
+
+    const wsclose = attachEventListener(context.realm, 'wsclose', (e) => {
+      console.log('connection socket closed!', e)
+    })
+
+    const peeropen = attachEventListener(context.realm, 'peeropen', (p) => {
+      console.log('peer connected', p)
+    })
+
+    const peerdata = attachEventListener(context.realm, 'peerdata', (p) => {
+      console.log('peer data', p)
+    })
+
+    const peerclose = attachEventListener(context.realm, 'peerclose', (p) => {
+      console.log('peer disconnected', p)
+    })
+
+    const peererror = attachEventListener(context.realm, 'peererror', (p) => {
+      console.log('peer error', p)
+    })
+
+    return () => {
+      context.realm?.removeEventListener('wsopen', wsopen)
+      context.realm?.removeEventListener('wsdata', wsdata)
+      context.realm?.removeEventListener('wserror', wserror)
+      context.realm?.removeEventListener('wsclose', wsclose)
+
+      context.realm?.removeEventListener('peeropen', peeropen)
+      context.realm?.removeEventListener('peerdata', peerdata)
+      context.realm?.removeEventListener('peererror', peererror)
+      context.realm?.removeEventListener('peerclose', peerclose)
+    }
+  })
+
+  const connect = useCallback(async () => {
+    const realmid = protocol.RealmBrand.parse('realm-n7-qM0rOzsJ8N-iF') // hard code for now
+    const identid = protocol.IdentBrand.generate()
+    const keypair = await generateSigningJwkPair()
+
+    context.setIdentity({ realmid, identid, keypair })
+  }, [context])
+
+  return (
+    <div className="webrtc-demo">
+      <h1>WebRTC Demo</h1>
+
+      <button onClick={connect}>
+        Connect
+      </button>
+
+      <div>
+        Identity:
+        <pre>{ JSON.stringify(context.identity, null, 2) }</pre>
+      </div>
+
+      <div className="connection-info">
+        <p>
+          Status:
+          {context.realm?.connected ? '🟢 Connected' : '🔴 Disconnected'}
+        </p>
+        <pre>
+          <code>
+            { JSON.stringify(context.realm, null, 2) }
+          </code>
+        </pre>
+      </div>
+
+      { context.realm && (
+        <div className="demo-layout">
+          <div className="demo-section">
+            <PeerList webrtcManager={context.realm} />
+            <Messenger webrtcManager={context.realm} />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

src/common/crypto/jwks.js

···
 import { z } from 'zod/v4'
 import { CryptoError } from './errors.js'
 
+/** @typedef {jose.JWK} JWK */
+
 const subtleSignAlgo = { name: 'ECDSA', namedCurve: 'P-256' }
 const joseSignAlgo = { name: 'ES256' }
 
···
  *
  * @see https://www.rfc-editor.org/rfc/rfc7517
  * @see https://github.com/panva/jose/blob/main/src/types.d.ts#L2
- * @type {z.ZodType<jose.JWK>}
+ * @type {z.ZodType<JWK>}
  */
 export const jwkSchema = z.union([
   jwkEcPublicSchema,
···
 /**
  * zod transform from JWK to CryptoKey
  *
- * @type {z.ZodTransform<CryptoKey, jose.JWK>}
+ * @type {z.ZodTransform<CryptoKey, JWK>}
  */
 export const jwkImport = z.transform(async (val, ctx) => {
   try {
···
 /**
  * zod transform from exportable CryptoKey to JWK
  *
- * @type {z.ZodTransform<jose.JWK, CryptoKey>}
+ * @type {z.ZodTransform<JWK, CryptoKey>}
  */
 export const jwkExport = z.transform(async (val, ctx) => {
   try {

src/common/crypto/jwts.js

···
 /**
  * @typedef {object} JWTToken
  * @property {string} token the still-encoded JWT, for later verification
- * @property {jose.JWTPayload} payload the decoded JWT payload, for later verification
- *
- * A JWTToken is both the decoded payload and the token itself, for later processing.
+ * @property {jose.JWTPayload} claims the decoded JWT payload, for later verification
+ */
+
+/**
+ * @template T
+ * @typedef {object} JWTTokenPayload
+ * @property {string} token the still-encoded JWT, for later verification
+ * @property {jose.JWTPayload} claims the decoded JWT payload, for later verification
+ * @property {T} payload the validate payload type, extracted from a payloadkey
  */
 
 /**
···
  */
 export const jwtSchema = z.jwt({ abort: true }).transform((token, ctx) => {
   try {
-    const payload = jose.decodeJwt(token)
-    return { payload, token }
+    const claims = jose.decodeJwt(token)
+    return { claims, token }
   }
   catch (e) {
     ctx.issues.push({
···
     return z.NEVER
   }
 })
+
+/**
+ * schema describing a verified payload in a JWT.
+ * **important** - this does no claims validation, only decoding from string to JWT!
+ *
+ * @template T
+ * @param {z.ZodType<T>} schema the schema to extract from the payload
+ * @returns {z.ZodType<JWTTokenPayload<T>>} transformer
+ */
+export const jwtPayload = (schema) => {
+  const parser = z.looseObject({ payload: schema })
+
+  return jwtSchema.transform(async (payload, ctx) => {
+    const result = await parser.safeParseAsync(payload.claims)
+    if (result.success)
+      return { ...payload, payload: result.data.payload }
+
+    result.error.issues.forEach((iss) => {
+      ctx.issues.push(iss)
+    })
+
+    return z.NEVER
+  })
+}
 
 /** @typedef {Partial<Omit<jose.JWTVerifyOptions, 'algorithms'>>} VerifyOpts */
 

src/common/protocol.js

···
     return JSON.parse(input)
   }
   catch {
-    ctx.issues.push({ code: 'custom', input, message: 'input could not be parsed as JSON' })
+    ctx.issues.push({
+      code: 'custom',
+      input,
+      message: 'input could not be parsed as JSON',
+    })
 
     return z.NEVER
   }

src/common/protocol/messages-realm.js

···
 import { z } from 'zod/v4'
-import { IdentBrand, RealmBrand } from './brands.js'
+import { IdentBrand } from './brands.js'
 import { okResponseSchema } from './messages.js'
 
-/** zod schema for `realm.status` message */
-export const realmStatusMessageSchema = z.object({
-  msg: z.literal('realm.status'),
-})
-/** @typedef {z.infer<typeof realmStatusMessageSchema>} RealmStatusMessage */
-
-/** zod schema for `realm.status` response */
-export const realmStatusResponseSchema = okResponseSchema.extend({
-  msg: z.literal('realm.status'),
-  realm: RealmBrand.schema,
-  identities: z.array(IdentBrand.schema),
-})
-/** @typedef {z.infer<typeof realmStatusResponseSchema>} RealmStatusResponse */
-
-/** zod schema for `realm.broadcast` message */
+/**
+ * zod schema for `realm.broadcast` message
+ * recipients = true, include self in broadcast
+ * recipients = false, exclude self in broadcast (default)
+ * recipients = [], use these exact recipients
+ */
 export const realmBroadcastMessageSchema = z.object({
   msg: z.literal('realm.broadcast'),
   payload: z.any(),
-  recipients: z.array(IdentBrand.schema).optional(),
+  recipients: z.union([
+    z.boolean(),
+    z.array(IdentBrand.schema),
+  ]).default(false),
 })
 /** @typedef {z.infer<typeof realmBroadcastMessageSchema>} RealmBroadcastMessage */
 
-/** zod schema for `realm.broadcast` message */
-export const realmBroadcastResponseSchema = okResponseSchema.extend({
-  msg: z.literal('realm.broadcast'),
+// rtc messages
+
+export const realmRtcSignalMessageSchema = z.object({
+  msg: z.literal('realm.rtc.signal'),
+  payload: z.string(),
   sender: IdentBrand.schema,
-  payload: z.any(),
+  recipient: IdentBrand.schema,
+  initiator: z.boolean(),
 })
-/** @typedef {z.infer<typeof realmBroadcastResponseSchema>} RealmBroadcastResponse */
+/** @typedef {z.infer<typeof realmRtcSignalMessageSchema>} RealmRtcSignalMessage */
+
+export const realmRtcPeerWelcomeMessageSchema = okResponseSchema.extend({
+  msg: z.literal('realm.rtc.peer-welcome'),
+  peers: z.array(IdentBrand.schema),
+})
+/** @typedef {z.infer<typeof realmRtcPeerWelcomeMessageSchema>} RealmRtcPeerWelcomeMessage */
+
+export const realmRtcPeerJoinedMessageSchema = okResponseSchema.extend({
+  msg: z.literal('realm.rtc.peer-joined'),
+  identid: IdentBrand.schema,
+})
+/** @typedef {z.infer<typeof realmRtcPeerJoinedMessageSchema>} RealmRtcPeerJoinedMessage */
+
+export const realmRtcPeerLeftMessageSchema = okResponseSchema.extend({
+  msg: z.literal('realm.rtc.peer-left'),
+  identid: IdentBrand.schema,
+})
+/** @typedef {z.infer<typeof realmRtcPeerLeftMessageSchema>} RealmRtcPeerLeftMessage */
+
+/// useful unions
 
-/** zod schema for any `realm` messages */
-export const realmMessageSchema = z.discriminatedUnion('msg', [
-  realmStatusMessageSchema,
+export const realmToServerMessageSchema = z.discriminatedUnion('msg', [
   realmBroadcastMessageSchema,
+  realmRtcSignalMessageSchema,
 ])
+/** @typedef {z.infer<typeof realmToServerMessageSchema>} RealmToServerMessage */
+
+export const realmFromServerMessageSchema = z.discriminatedUnion('msg', [
+  realmRtcPeerJoinedMessageSchema,
+  realmRtcPeerLeftMessageSchema,
+  realmRtcSignalMessageSchema,
+])
+/** @typedef {z.infer<typeof realmFromServerMessageSchema>} RealmFromServerMessage */

src/common/socket.js

···
 /** @module common/socket */
 
+import * as z_types from 'zod/v4'
+
 import { combineSignals } from '#common/async/aborts.js'
 import { BlockingAtom } from '#common/async/blocking-atom.js'
 import { BlockingQueue } from '#common/async/blocking-queue.js'
 import { Breaker } from '#common/breaker.js'
 import { ProtocolError } from '#common/errors.js'
 
-import * as protocol_types from './protocol.js'
+import { parseJson } from './protocol.js'
 
 /**
  * Send some data in JSON format down the wire.
  *
  * @param {WebSocket} ws the socket to send on
- * @param {protocol_types.OkResponse | protocol_types.ErrorResponse} data the data to send
+ * @param {unknown} data the data to send
  */
 export function sendSocket(ws, data) {
   ws.send(JSON.stringify(data))
···
     ws.removeEventListener('error', onError)
     ws.removeEventListener('close', onClose)
   }
+}
+
+/**
+ * exactly take socket, but will additionally apply a json decoding
+ *
+ * @template T the schema's type
+ * @param {WebSocket} ws the socket to read
+ * @param {z_types.ZodSchema<T>} schema an a schema to execute
+ * @param {AbortSignal} [signal] an abort signal to cancel the block
+ * @returns {Promise<T>} the message off the socket
+ */
+export async function takeSocketJson(ws, schema, signal) {
+  const data = await takeSocket(ws, signal)
+  return parseJson.pipe(schema).parseAsync(data)
 }
 
 /**
···
     ws.removeEventListener('close', onClose)
   }
 }
+
+/**
+ * exactly stream socket, but will additionally apply a json decoding
+ * messages not validating will end the stream with an error
+ *
+ * @param {WebSocket} ws the socket to read
+ * @param {Partial<ConfigProps>} [config] stream configuration to merge into defaults
+ * @returns {AsyncGenerator<unknown>} an async generator
+ * @yields the message off the socket
+ */
+export async function* streamSocketJson(ws, config) {
+  for await (const message of streamSocket(ws, config)) {
+    yield parseJson.parseAsync(message)
+  }
+}
+
+/**
+ * exactly stream socket, but will additionally apply a json decoding
+ * messages not validating will end the stream with an error
+ *
+ * @template T the schema's type
+ * @param {WebSocket} ws the socket to read
+ * @param {z_types.ZodSchema<T>} schema an a schema to execute
+ * @param {Partial<ConfigProps>} [config] stream configuration to merge into defaults
+ * @returns {AsyncGenerator<T>} an async generator
+ * @yields the message off the socket
+ */
+export async function* streamSocketSchema(ws, schema, config) {
+  const parser = parseJson.pipe(schema)
+
+  for await (const message of streamSocket(ws, config)) {
+    yield await parser.parseAsync(message)
+  }
+}

src/common/strict-map.js

···
 
   /**
    * @param {K} key to update in the map
-   * @param {function(V=): V} update function which returns the new value for the map
+   * @param {function(V=): V | undefined} update
+   * function which returns the new value for the map
+   * if the return value is REMOVE_KEY, the whole entry in the map will be removed.
    */
   update(key, update) {
-    const current = this.get(key)
-    this.set(key, update(current))
+    const prev = this.get(key)
+    const next = update(prev)
+
+    if (next === undefined) {
+      this.delete(key)
+    }
+    else {
+      this.set(key, next)
+    }
   }
 
 }

src/server/routes-socket/handler-preauth.js

···
 import { combineSignals, timeoutSignal } from '#common/async/aborts.js'
 import { jwkImport } from '#common/crypto/jwks.js'
-import { jwtSchema, verifyJwtToken } from '#common/crypto/jwts.js'
+import { jwtPayload, verifyJwtToken } from '#common/crypto/jwts.js'
 import { normalizeError, ProtocolError } from '#common/errors.js'
 import { IdentBrand, preauthMessageSchema, RealmBrand } from '#common/protocol.js'
 import { takeSocket } from '#common/socket.js'
···
     const data = await takeSocket(ws, combinedSignal)
 
     // if any of the parsing fails, it'll throw a zod error
-    const jwt = jwtSchema.parse(data)
-    const msg = await preauthMessageSchema.parseAsync(jwt.payload)
-    const identid = IdentBrand.parse(jwt.payload.iss)
-    const realmid = RealmBrand.parse(jwt.payload.aud)
+    const jwt = await jwtPayload(preauthMessageSchema).parseAsync(data)
+    const identid = IdentBrand.parse(jwt.claims.iss)
+    const realmid = RealmBrand.parse(jwt.claims.aud)
 
     // if we're registering, make sure the realm exists
-    if (msg.msg === 'preauth.register') {
-      const registrantkey = await jwkImport.parseAsync(msg.pubkey)
+    if (jwt.payload.msg === 'preauth.register') {
+      const registrantkey = await jwkImport.parseAsync(jwt.payload.pubkey)
       realms.ensureRegisteredRealm(realmid, identid, registrantkey)
     }
 

src/server/routes-socket/handler-realm.js

···
 import { normalizeProtocolError, ProtocolError } from '#common/errors.js'
-import { realmMessageSchema, parseJson } from '#common/protocol.js'
+import { realmToServerMessageSchema, parseJson } from '#common/protocol.js'
 import { sendSocket, streamSocket } from '#common/socket.js'
-import { format } from 'node:util'
 
 import * as protocol_types from '#common/protocol.js'
 import * as realm_types from '#server/routes-socket/state.js'
···
  * @param {AbortSignal} [signal] an optional signal to abort the blocking loop
  */
 export async function realmHandler(ws, auth, signal) {
-  respondWithRealmStatus(ws, auth)
-  broadcastToRealm(undefined, { ok: true, msg: 'welcome', ident: auth.identid }, auth)
+  realmBroadcast(auth, buildRtcPeerJoined(auth))
+  sendSocket(ws, buildRtcPeerWelcome(auth))
 
-  for await (const data of streamSocket(ws, { signal })) {
-    try {
-      const msg = await parseJson.pipe(realmMessageSchema).parseAsync(data)
-      switch (msg.msg) {
-        case 'realm.status':
-          respondWithRealmStatus(ws, auth)
-          continue
+  try {
+    for await (const data of streamSocket(ws, { signal })) {
+      try {
+        const msg = await parseJson.pipe(realmToServerMessageSchema).parseAsync(data)
+        switch (msg.msg) {
+          case 'realm.broadcast':
+            realmBroadcast(auth, msg.payload, msg.recipients)
+            continue
 
-        case 'realm.broadcast':
-          broadcastToRealm(msg.recipients, msg.payload, auth)
-          continue
+          case 'realm.rtc.signal':
+            realmBroadcast(auth, msg, [msg.recipient])
+            continue
 
-        default:
-          throw new ProtocolError('unknown message type: ${msg.msg}', 400)
+          default:
+            throw new ProtocolError(`unknown message type: ${msg}`, 400)
+        }
       }
-    }
-    catch (exc) {
-      const error = normalizeProtocolError(exc)
-      if (error.status >= 500) throw error
+      catch (exc) {
+        const error = normalizeProtocolError(exc)
+        if (error.status >= 500)
+          throw error
 
-      if (ws.readyState === ws.OPEN) {
-        /** @type {protocol_types.ErrorResponse} */
-        const resp = {
-          ok: false,
-          message: format('Error: %s', error.message),
-          status: error.status,
+        if (ws.readyState === ws.OPEN) {
+          sendSocket(ws, buildRealmError(error))
         }
-
-        sendSocket(ws, resp)
       }
     }
   }
+  finally {
+    console.log('client left!', auth)
+    realmBroadcast(auth, buildRtcPeerLeft(auth))
+  }
 }
 
 /**
  * @private
- * @param {WebSocket} ws the socket to communicate on
  * @param {realm_types.AuthenticatedConnection} auth the current identity
+ * @returns {protocol_types.RealmRtcPeerWelcomeMessage} a realm welcome response
  */
-function respondWithRealmStatus(ws, auth) {
-  /** @type {protocol_types.RealmStatusResponse} */
-  const resp = {
+function buildRtcPeerWelcome(auth) {
+  return {
     ok: true,
-    msg: 'realm.status',
-    realm: auth.realmid,
-    identities: Array.from(auth.realm.identities.keys()),
+    msg: 'realm.rtc.peer-welcome',
+    peers: Array.from(auth.realm.sockets.keys()),
   }
+}
 
-  sendSocket(ws, resp)
+/**
+ * @private
+ * @param {realm_types.AuthenticatedConnection} auth the current identity
+ * @returns {protocol_types.RealmRtcPeerJoinedMessage} a realm status response
+ */
+function buildRtcPeerJoined(auth) {
+  return {
+    ok: true,
+    msg: 'realm.rtc.peer-joined',
+    identid: auth.identid,
+  }
 }
 
 /**
  * @private
- * @param {protocol_types.IdentID[] | undefined} recipients array of recips, or undef to send all
- * @param {unknown} payload the payload to send
  * @param {realm_types.AuthenticatedConnection} auth the current identity
+ * @returns {protocol_types.RealmRtcPeerLeftMessage} a realm status response
  */
-function broadcastToRealm(recipients, payload, auth) {
-  /** @type {protocol_types.RealmBroadcastResponse} */
-  const resp = {
+function buildRtcPeerLeft(auth) {
+  return {
     ok: true,
-    msg: 'realm.broadcast',
-    sender: auth.identid,
-    payload: payload,
+    msg: 'realm.rtc.peer-left',
+    identid: auth.identid,
   }
+}
 
-  recipients ??= Array.from(auth.realm.identities.keys())
-  for (const recip of recipients) {
-    if (recip === auth.identid) continue
+/**
+ * @private
+ * @param {ProtocolError} error the error to report
+ * @returns {protocol_types.ErrorResponse} a realm error response
+ */
+function buildRealmError(error) {
+  return {
+    ok: false,
+    message: error.message,
+    status: error.status,
+  }
+}
 
-    const sockets = auth.realm.sockets.get(recip)
-    if (sockets == null) continue
+/**
+ * @private
+ * @param {realm_types.AuthenticatedConnection} auth the current identity
+ * @param {unknown} payload the payload to send
+ * @param {protocol_types.IdentID[] | boolean} [recipients]
+ * when true, send to the whole realm, including self
+ * when false, send to the whole realm, excluding self
+ * when an array of recipients, send to those recipients explicitly
+ */
+function realmBroadcast(auth, payload, recipients) {
+  const echo = recipients === true || Array.isArray(recipients)
+  const recips = Array.isArray(recipients) ? recipients : Array.from(auth.realm.identities.keys())
 
-    for (const socket of sockets) {
-      sendSocket(socket, resp)
+  for (const recip of recips) {
+    if (!echo && recip === auth.identid) continue
+
+    const sockets = auth.realm.sockets.get(recip)
+    if (sockets) {
+      for (const socket of sockets) {
+        sendSocket(socket, payload)
+      }
     }
   }
 }

src/server/routes-socket/state.js

···
  * @returns {Realm} a registered realm, possibly newly created with the registrant
  */
 export function ensureRegisteredRealm(realmid, registrantid, registrantkey) {
-  return realmMap.ensure(realmid, () => ({
+  const realm = realmMap.ensure(realmid, () => ({
     realmid,
     sockets: new StrictMap(),
     identities: new StrictMap([[registrantid, registrantkey]]),
   }))
+
+  // hack for now, allow any registration to work
+  realm.identities.ensure(registrantid, () => registrantkey)
+  return realm
 }
 
 /**
···
  * @param {WebSocket} socket the socket to dettach
  */
 export function detachSocket(realm, ident, socket) {
-  realm.sockets.update(ident, ss => ss ? ss.filter(s => s !== socket) : [])
+  realm.sockets.update(ident, (sockets) => {
+    const next = sockets?.filter(s => s !== socket)
+    return next?.length ? next : undefined
+  })
 }