@zero-server/sdk 0.9.7 → 0.9.8

package/lib/webrtc/observe.js

@@ -1,10 +1,9 @@
 /**
  * @module webrtc/observe
- * @description Optional metrics + tracing wiring for a {@link SignalingHub}.
- *              Pass a `MetricsRegistry`, a `Tracer`, or both; the binder
- *              subscribes to the hub's lifecycle events and exports the six
- *              standard `zs_webrtc_*` Prometheus series plus per-operation
- *              OpenTelemetry-compatible spans.
+ * @description Optional metrics + tracing wiring for a `SignalingHub`.
+ *   `bindObservability(hub, { metrics, tracer })` exports the standard
+ *   `zs_webrtc_*` Prometheus series plus OTel-compatible spans. Both
+ *   adapters are duck-typed and opt-in.
  */
 
 'use strict';
@@ -215,9 +214,41 @@ function _bindTracing(hub, tracer)
  * @param {Tracer}          [opts.tracer]  - Tracer for span emission.
  * @returns {SignalingHub} The same hub, for chaining.
  *
- * @example | Plug into an existing app
+ * @example | Wire metrics + tracing from Zero Server's observe scope
+ *   const { createApp } = require('@zero-server/sdk');
+ *   const { Tracer } = require('@zero-server/sdk/observe');
+ *   const { SignalingHub, bindObservability } = require('@zero-server/webrtc');
+ *
+ *   const app = createApp();
+ *   const hub = new SignalingHub({ joinTokenSecret: process.env.JWT });
+ *
+ *   bindObservability(hub, {
+ *       metrics: app.metrics,        // exposes /metrics for Prometheus scraping
+ *       tracer:  new Tracer(),       // OTel-shaped tracer
+ *   });
+ *
+ *   app.ws('/rtc', (ws, req) => hub.attach(ws, { user: req.user, ip: req.ip }));
+ *
+ * @example | Metrics only (no tracer)
  *   const hub = new SignalingHub();
- *   bindObservability(hub, { metrics: app.metrics() });
+ *   bindObservability(hub, { metrics: app.metrics });
+ *   // Scrape /metrics:
+ *   //   zs_webrtc_peers_active{room="lobby"}              3
+ *   //   zs_webrtc_rooms_active                            1
+ *   //   zs_webrtc_signaling_messages_total{type="offer",direction="in",result="ok"} 17
+ *   //   zs_webrtc_offer_duration_ms_bucket{room="lobby",le="250"} 5
+ *
+ * @example | Custom prom-client registry adapter
+ *   const client = require('prom-client');
+ *   const reg = new client.Registry();
+ *   const adapter = {
+ *       counter:   ({ name, help, labels }) => new client.Counter({ name, help, labelNames: labels, registers: [reg] }),
+ *       gauge:     ({ name, help, labels }) => new client.Gauge  ({ name, help, labelNames: labels, registers: [reg] }),
+ *       histogram: ({ name, help, labels, buckets }) =>
+ *                  new client.Histogram({ name, help, labelNames: labels, buckets, registers: [reg] }),
+ *   };
+ *   bindObservability(hub, { metrics: adapter });
+ *   app.get('/metrics', async (_req, res) => res.type(reg.contentType).send(await reg.metrics()));
  */
 function bindObservability(hub, opts = {})
 {

package/lib/webrtc/peer.js

@@ -1,11 +1,20 @@
 /**
  * @module webrtc/peer
- * @description Per-connection state machine for a WebRTC signaling peer.
+ * @description Per-connection state machine for a signaling peer. Wraps a
+ *   `{ send, on, close }` transport (typically `app.ws()`'s
+ *   `WebSocketConnection`) and exposes JSEP message types as events.
+ *   Constructed by `hub.attach(transport, info)` — not directly.
  *
- *   A `Peer` wraps a transport object (typically a `WebSocketConnection`
- *   but any duck-typed `{ send, on, close }` works - see the unit tests
- *   for a minimal in-memory transport) and exposes the JSEP message
- *   types as ordinary events.  The hub is responsible for routing.
+ * @example | Inspect every newly-attached peer
+ *   hub.on('join', ({ peer, room }) => {
+ *       console.log(
+ *           'peer', peer.id,
+ *           'user=', peer.user && peer.user.id,
+ *           'ip=', peer.ip,
+ *           'joined', room.name,
+ *           'roster size=', room.size,
+ *       );
+ *   });
  */
 
 'use strict';
@@ -25,14 +34,32 @@ const PEER_STATE = Object.freeze({
 /**
  * One signaling peer attached to a `SignalingHub` via some transport.
  *
+ * `Peer` is created by `hub.attach(transport, info)` and lives until the
+ * underlying transport closes (or the hub kicks the peer for protocol
+ * abuse).  All event listeners are owned by the hub; application code
+ * subscribes to hub-level events such as `join`, `leave`, and the
+ * room-level `peer-joined` / `peer-left`.
+ *
  * @class
  * @section Peers
  *
- * @example
+ * @example | Push a per-peer welcome and tap mute events
  *   hub.on('join', ({ peer, room }) => {
- *       peer.send('welcome', { roomSize: room.size });
- *       peer.on('mute', ev => audit('mute', peer.id, ev.kind));
+ *       peer.send('welcome', { roomSize: room.size, you: peer.id });
+ *       peer.on?.('mute', ev => audit('mute', peer.id, ev.kind));
  *   });
+ *
+ * @example | Forcefully disconnect a peer that fails an auth refresh
+ *   async function rotateAuth(peer) {
+ *       const ok = await refreshSession(peer.user);
+ *       if (!ok) peer.close(4401, 'auth-expired');
+ *   }
+ *
+ * @example | Send a typed error frame instead of throwing inside a handler
+ *   if (msg.bytes.length > MAX_BYTES) {
+ *       peer.sendError('PAYLOAD_TOO_LARGE', 'frame > 64 KiB');
+ *       return;
+ *   }
  */
 class Peer
 {

package/lib/webrtc/room.js

@@ -1,10 +1,9 @@
 /**
  * @module webrtc/room
- * @description Room / channel abstraction for the WebRTC signaling hub.
- *
- *   A `Room` holds a set of `Peer`s plus a list of `require()` policy gates
- *   that decide whether a given peer may join.  Membership is in-process;
- *   the cluster adapter (PR 8) will fan room state out via pub/sub.
+ * @description Room / channel abstraction for the signaling hub. Holds a
+ *   set of peers plus a fluent chain of policy gates (`require()`,
+ *   `canPublish()`, `canSubscribe()`). Constructed lazily via
+ *   `hub.room(name)`; pair with `useCluster()` for multi-node membership.
  */
 
 'use strict';
@@ -20,11 +19,25 @@ const { SignalingError } = require('../errors');
  * @class
  * @section Rooms
  *
- * @example
+ * @example | Open a public lobby that anyone with a token may join
  *   hub.room('lobby').open();
+ *
+ * @example | Gate a room with role + per-publisher policies
  *   hub.room('boardroom')
  *       .require(peer => peer.user && peer.user.role === 'exec')
- *       .canPublish(peer => peer.user.isHost);
+ *       .canPublish(peer => peer.user.isHost)
+ *       .canSubscribe(peer => peer.user.verified === true)
+ *       .open();
+ *
+ * @example | Programmatic room metrics
+ *   const r = hub.room('webinar-42');
+ *   setInterval(() => log.info({ room: r.name, size: r.size }), 10_000);
+ *
+ * @example | Broadcast a system announcement from outside the message handler
+ *   hub.room('lobby').broadcast('notice', { text: 'Server restart in 60s' });
+ *
+ * @example | Boot the room and disconnect everyone gracefully
+ *   hub.room('lobby').close('shutdown');
  */
 class Room
 {

package/lib/webrtc/sdp.js

@@ -1,14 +1,9 @@
 /**
  * @module webrtc/sdp
- * @description Zero-dependency RFC 8866 Session Description Protocol parser and
- *              serializer, with WebRTC-specific attribute extraction (JSEP per
- *              RFC 8829: ice-ufrag, ice-pwd, fingerprint, setup, mid, rtcp-mux,
- *              direction, rtpmap, fmtp, rid, simulcast, ssrc, extmap, candidate).
- *
- *              The parser deliberately does NOT validate semantics that belong
- *              to a SignalingHub policy layer (codec allowlists, mDNS blocking,
- *              etc.) - it only structures the document.  Policy lives in
- *              `lib/webrtc/signaling.js`.
+ * @description Zero-dependency RFC 8866 SDP parser and serializer with
+ *   WebRTC-specific attribute extraction per RFC 8829 (ice-ufrag, ice-pwd,
+ *   fingerprint, setup, mid, rtcp-mux, rtpmap, fmtp, ssrc, etc.). Pure
+ *   structure — policy lives in the signaling layer.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8866
  * @see https://datatracker.ietf.org/doc/html/rfc8829

package/lib/webrtc/sfu/index.js

@@ -1,12 +1,28 @@
 /**
  * @module webrtc/sfu
- * @description SFU adapter base interface and discovery loader.
+ * @description Pluggable Selective Forwarding Unit (SFU) adapter interface.
+ *   The signaling hub stays media-agnostic; the adapter owns routers,
+ *   transports, producers, and consumers. Ships with `MemorySfuAdapter`,
+ *   `MediasoupSfuAdapter`, and `LiveKitSfuAdapter`. Subclass `SfuAdapter`
+ *   for custom backends.
  *
- *   `SfuAdapter` defines the contract every backend (memory / mediasoup /
- *   livekit / custom) must implement.  `loadSfuAdapter()` resolves either
- *   a pre-constructed instance, a known name ('memory', 'mediasoup',
- *   'livekit'), or a duck-typed object into a concrete adapter, throwing
- *   `WEBRTC_SFU_NOT_INSTALLED` when a native peerDep is missing.
+ * @example | Select an adapter at boot via env
+ *   const { loadSfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = loadSfuAdapter(process.env.SFU_BACKEND || 'memory', {
+ *       // adapter-specific options forwarded verbatim
+ *       workerSettings: { logLevel: 'warn' },
+ *   });
+ *
+ *   sfu.onEvent((event, payload) => log.debug({ event, payload }, 'sfu'));
+ *
+ * @example | Wire an SFU into the signaling hub per room
+ *   const router = await sfu.createRouter({ room: 'lobby' });
+ *
+ *   hub.on('join', async ({ peer, room }) => {
+ *       if (room.name !== 'lobby') return;
+ *       const transport = await sfu.createTransport(router, peer);
+ *       peer.send('sfu-transport', { iceParameters: transport.iceParameters });
+ *   });
  */
 'use strict';
 
@@ -20,11 +36,30 @@ const { WebRTCError } = require('../../errors');
  *   The interface is intentionally tiny so a backend can be written in a
  *   single file:
  *
- *     class MyAdapter extends SfuAdapter {
- *         async createRouter(opts)            { ... }
- *         async createTransport(router, peer) { ... }
- *         ...
- *     }
+ * @example | Skeleton adapter
+ *   class MyAdapter extends SfuAdapter {
+ *       async createRouter(opts)            { return { id: cuid(), opts }; }
+ *       async createTransport(router, peer) { return { id: cuid(), router, peer }; }
+ *       async produce(transport, kind, rtp) {
+ *           const id = cuid();
+ *           this._emit('producer-new', { id, kind, transportId: transport.id });
+ *           return { id, kind };
+ *       }
+ *       async consume(transport, producerId, _rtpCaps) {
+ *           return { id: cuid(), producerId, transportId: transport.id };
+ *       }
+ *       async pauseProducer(id)  { this._emit('producer-pause', { id }); }
+ *       async resumeProducer(id) { this._emit('producer-resume', { id }); }
+ *       async closeRouter(id)    { this._emit('router-close', { id }); }
+ *       async stats(_scope)      { return { ts: Date.now() }; }
+ *   }
+ *
+ * @example | Subscribe to adapter events
+ *   const off = sfu.onEvent((event, payload) => {
+ *       if (event === 'producer-new')   metrics.producers.inc();
+ *       if (event === 'producer-pause') log.info({ id: payload.id }, 'paused');
+ *   });
+ *   // later: off();
  */
 class SfuAdapter
 {
@@ -117,6 +152,21 @@ class SfuAdapter
  *   - 'memory' | 'mediasoup' | 'livekit' | adapter package id.
  * @param {object} [opts] - constructor options forwarded to the adapter.
  * @returns {SfuAdapter}
+ *
+ * @example | Built-in adapter by name
+ *   const sfu = loadSfuAdapter('mediasoup', {
+ *       numWorkers: 4,
+ *       workerSettings: { rtcMinPort: 40000, rtcMaxPort: 49999 },
+ *   });
+ *
+ * @example | Pre-constructed instance (e.g. shared singleton in tests)
+ *   const fake = new MemorySfuAdapter();
+ *   const sfu  = loadSfuAdapter(fake);
+ *   expect(sfu).toBe(fake);
+ *
+ * @example | Third-party adapter package
+ *   //   npm i @acme/zero-server-sfu-janus
+ *   const sfu = loadSfuAdapter('@acme/zero-server-sfu-janus', { wsUrl: 'ws://janus/ws' });
  */
 function loadSfuAdapter(spec, opts)
 {

package/lib/webrtc/sfu/livekit.js

@@ -1,31 +1,34 @@
 /**
  * @module webrtc/sfu/livekit
- * @description LiveKit-backed SFU adapter (peerDependency on `livekit-server-sdk`).
+ * @description LiveKit-backed SFU adapter (peerDependency on
+ *   `livekit-server-sdk`). Maps the `SfuAdapter` contract onto LiveKit's
+ *   remote media plane: `createTransport` mints an AccessToken, mute/close
+ *   delegate to `RoomServiceClient`, and produce/consume are local
+ *   bookkeeping while LiveKit handles media client-side.
  *
- *   LiveKit's media plane is controlled remotely: rooms live on the
- *   LiveKit server, participants connect directly with a signed JWT, and
- *   the server SDK exposes a control-plane REST API.  This adapter maps
- *   the {@link SfuAdapter} contract onto that model:
+ * @example | Cloud LiveKit project
+ *   //   npm install livekit-server-sdk
+ *   const { LiveKitSfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = new LiveKitSfuAdapter({
+ *       host:      'https://my-project.livekit.cloud',
+ *       apiKey:    process.env.LIVEKIT_API_KEY,
+ *       apiSecret: process.env.LIVEKIT_API_SECRET,
+ *       tokenTtl:  '30m',
+ *   });
  *
- *     - createRouter(opts)          -> RoomServiceClient.createRoom(...)
- *     - createTransport(router,peer) -> mints an AccessToken (the "transport"
- *                                       handle is the URL + JWT the peer
- *                                       uses to connect to LiveKit directly)
- *     - produce / consume           -> local bookkeeping; LiveKit handles
- *                                       the actual media plane client-side
- *     - pauseProducer / resume      -> RoomServiceClient.mutePublishedTrack()
- *                                       when the producer was registered
- *                                       with a `{room, identity, trackSid}`
- *                                       hint; otherwise emits the event
- *                                       without touching the server
- *     - closeRouter(routerId)       -> RoomServiceClient.deleteRoom(...)
- *     - stats()                     -> RoomServiceClient.listRooms() /
- *                                       listParticipants(...) plus local
- *                                       counters
+ * @example | Self-hosted LiveKit + handing the JWT to a browser
+ *   const router    = await sfu.createRouter({ room: 'standup' });
+ *   const transport = await sfu.createTransport(router, {
+ *       id:   peer.id,
+ *       user: { id: peer.user.id, name: peer.user.name },
+ *   });
+ *   peer.send('livekit', { url: transport.url, token: transport.token });
  *
- *   `livekit-server-sdk` is loaded lazily.  Tests inject a stub via
- *   `opts.livekit`; in production the constructor `require`s the package
- *   and throws `WEBRTC_SFU_NOT_INSTALLED` if it is missing.
+ * @example | Mute a noisy publisher (REST passthrough)
+ *   await sfu.pauseProducer(producer.id);
+ *   // adapter records the producerId; if it was registered with a
+ *   // { room, identity, trackSid } hint it issues
+ *   // RoomServiceClient.mutePublishedTrack() against LiveKit.
  */
 'use strict';
 

package/lib/webrtc/sfu/mediasoup.js

@@ -1,15 +1,55 @@
 /**
  * @module webrtc/sfu/mediasoup
- * @description mediasoup-backed SFU adapter (peerDependency on `mediasoup`).
+ * @description mediasoup-backed SFU adapter (peerDependency on
+ *   `mediasoup`). Wraps a `Worker` plus one `Router` per `createRouter()`
+ *   call and delegates produce/consume/pause/resume/close/stats to the
+ *   native objects. Adapter events are uniform via `onEvent`.
  *
- *   Wraps a single mediasoup `Worker` and one `Router` per createRouter()
- *   call.  WebRTC transports are created with `router.createWebRtcTransport()`
- *   and produce / consume / pause / resume / close / stats all delegate to
- *   the native mediasoup objects.
+ * @example | Production setup with custom RTP port range and announced IP
+ *   //   npm install mediasoup
+ *   const { MediasoupSfuAdapter } = require('@zero-server/webrtc');
  *
- *   `mediasoup` is loaded lazily.  Tests inject a stub via `opts.mediasoup`;
- *   in production the constructor `require('mediasoup')`s the real package
- *   and throws `WEBRTC_SFU_NOT_INSTALLED` if it is missing.
+ *   const sfu = new MediasoupSfuAdapter({
+ *       workerSettings: {
+ *           logLevel:   'warn',
+ *           rtcMinPort: 40000,
+ *           rtcMaxPort: 49999,
+ *       },
+ *       webRtcTransportOptions: {
+ *           listenIps:  [{ ip: '0.0.0.0', announcedIp: process.env.PUBLIC_IP }],
+ *           enableUdp:  true,
+ *           enableTcp:  true,
+ *           preferUdp:  true,
+ *           initialAvailableOutgoingBitrate: 800_000,
+ *       },
+ *   });
+ *
+ * @example | One router per room, lazy on first join
+ *   const routersByRoom = new Map();
+ *
+ *   async function getRouter(roomName) {
+ *       let r = routersByRoom.get(roomName);
+ *       if (!r) {
+ *           r = await sfu.createRouter({ room: roomName });
+ *           routersByRoom.set(roomName, r);
+ *       }
+ *       return r;
+ *   }
+ *
+ *   hub.on('join', async ({ peer, room }) => {
+ *       const router    = await getRouter(room.name);
+ *       const transport = await sfu.createTransport(router, peer);
+ *       peer.send('sfu-ready', { transportId: transport.id });
+ *   });
+ *
+ * @example | Inject a stub for unit tests
+ *   const stubMediasoup = {
+ *       createWorker: async () => ({
+ *           createRouter: async () => fakeRouter,
+ *           close: () => {},
+ *       }),
+ *   };
+ *   const sfu = new MediasoupSfuAdapter({ mediasoup: stubMediasoup });
  */
 'use strict';
 

package/lib/webrtc/sfu/memory.js

@@ -1,16 +1,33 @@
 /**
  * @module webrtc/sfu/memory
- * @description In-process "memory" SFU adapter.
+ * @description In-process "memory" SFU adapter. Bookkeeping-only
+ *   passthrough that records producers/consumers and emits adapter events
+ *   without forwarding media packets. Ideal for unit tests, CI, and local
+ *   dev — use a native adapter for real media plane work.
  *
- *   A passthrough router that never touches the network: every produce()
- *   call records a logical producer, every consume() call records a
- *   logical consumer, and events are emitted via {@link SfuAdapter#onEvent}.
- *   Perfect for unit tests, ≤ 4-peer audio-only rooms, and local dev
- *   where the cost of running mediasoup or LiveKit is unjustified.
+ * @example | Use the memory adapter inside a vitest suite
+ *   const { MemorySfuAdapter } = require('@zero-server/webrtc');
+ *   const sfu = new MemorySfuAdapter();
  *
- *   The adapter does NOT decode or forward media packets - it models
- *   bookkeeping only.  Real packet forwarding lives in native adapters
- *   (mediasoup, LiveKit).
+ *   const events = [];
+ *   sfu.onEvent((event, payload) => events.push({ event, payload }));
+ *
+ *   const router    = await sfu.createRouter({ room: 'lobby' });
+ *   const transport = await sfu.createTransport(router, { id: 'peer-1' });
+ *   const producer  = await sfu.produce(transport, 'audio', { codec: 'opus' });
+ *   const consumer  = await sfu.consume(transport, producer.id, {});
+ *
+ *   expect(events).toEqual([
+ *       { event: 'router-new',   payload: { routerId: router.id } },
+ *       { event: 'transport-new', payload: expect.any(Object) },
+ *       { event: 'producer-new',  payload: expect.objectContaining({ kind: 'audio' }) },
+ *       { event: 'consumer-new',  payload: expect.objectContaining({ producerId: producer.id }) },
+ *   ]);
+ *
+ * @example | Drive it through `loadSfuAdapter`
+ *   const sfu = loadSfuAdapter('memory');
+ *   const stats = await sfu.stats();
+ *   console.log(stats); // { routers, transports, producers, consumers }
  */
 'use strict';
 

package/lib/webrtc/signaling.js

@@ -1,13 +1,37 @@
 /**
  * @module webrtc/signaling
- * @description WebRTC signaling hub - the central WS broker that owns the
- *              room registry, attaches peers, validates JSEP messages, and
- *              routes offer / answer / ICE traffic between participants.
+ * @description WebRTC signaling hub. Central WS broker that owns the room
+ *   registry, attaches peers, validates JSEP messages, and routes
+ *   offer / answer / ICE traffic. Transport-agnostic — bind to `app.ws()`
+ *   in production, an `EventEmitter` shim in tests.
  *
- *   The hub itself is transport-agnostic: anything that exposes a
- *   `{ send(string), on('message'|'close', cb), close(code?, reason?) }`
- *   surface is acceptable.  `createWebRTC(app, opts)` (PR 9 wiring layer)
- *   binds an `app.ws()` upgrade handler to a `SignalingHub`.
+ * @example | Bind a hub to an `app.ws()` route with all production knobs
+ *   const app = createApp();
+ *   const hub = new SignalingHub({
+ *       joinTokenSecret:        process.env.WEBRTC_JWT_SECRET,
+ *       maxSdpSize:             64 * 1024,
+ *       maxCandidatesPerOffer:  20,
+ *       peerMessageRate:        30,
+ *       maxProtocolErrors:      5,
+ *       ipAttachRate:           60,
+ *       originAllowlist:        ['https://meet.acme.com'],
+ *       autoCreateRooms:        false,
+ *   });
+ *
+ *   hub.room('lobby').open();
+ *
+ *   app.ws('/rtc', (ws, req) => {
+ *       hub.attach(ws, {
+ *           user:   req.user,
+ *           ip:     req.ip,
+ *           origin: req.headers.origin,
+ *       });
+ *   });
+ *
+ * @example | Observe lifecycle events
+ *   hub.on('join',      ({ peer, room }) => log.info({ peer: peer.id, room: room.name }, 'joined'));
+ *   hub.on('leave',     ({ peer, room }) => log.info({ peer: peer.id, room: room.name }, 'left'));
+ *   hub.on('wireError', ({ peer, code })  => log.warn({ peer: peer.id, code }, 'wire-error'));
  */
 
 'use strict';
@@ -187,13 +211,33 @@ class SignalingHub extends EventEmitter
 
     /**
      * Attach a transport (WS connection or mock) as a new signaling peer.
-     * Wires up message and close handlers; returns the `Peer`.
+     * Wires up message and close handlers, performs origin / IP-rate
+     * pre-checks, sends a `hello` frame with the new peer id, and returns
+     * the `Peer`.  The returned peer is also registered in `hub.size`.
+     *
+     * Called from your `app.ws()` upgrade handler in production:
+     *
+     * ```js
+     * app.ws('/rtc', (ws, req) => hub.attach(ws, {
+     *     user:   req.user,
+     *     ip:     req.ip,
+     *     origin: req.headers.origin,
+     * }));
+     * ```
      *
      * @param {object} transport - `{ send, on, close }`-shaped object.
      * @param {object} [info]
-     * @param {*}      [info.user] - Authenticated user.
-     * @param {string} [info.ip]   - Remote IP.
+     * @param {*}      [info.user]   - Authenticated user (forwarded to room gates).
+     * @param {string} [info.ip]     - Remote IP for audit + `ipAttachRate`.
+     * @param {string} [info.origin] - Origin header for `originAllowlist`.
      * @returns {Peer}
+     *
+     * @example | Test harness: attach a mock transport
+     *   const mock = new EventEmitter();
+     *   mock.send  = (frame) => mock.emit('out', frame);
+     *   mock.close = ()      => mock.emit('close');
+     *   const peer = hub.attach(mock, { user: { id: 'u1' }, ip: '127.0.0.1' });
+     *   mock.emit('message', JSON.stringify({ type: 'join', room: 'lobby' }));
      */
     attach(transport, info = {})
     {

package/lib/webrtc/stun.js

@@ -1,19 +1,11 @@
 /**
  * @module webrtc/stun
- * @description Zero-dependency RFC 8489 STUN (Session Traversal Utilities for
- *              NAT) client.  Sends a Binding Request over UDP, parses the
- *              Binding Response, and returns the server-reflexive address
- *              decoded from XOR-MAPPED-ADDRESS (or, as a fallback, the
- *              deprecated MAPPED-ADDRESS attribute used by some legacy servers).
- *
- *              Only the parts of RFC 8489 we need for NAT discovery are
- *              implemented: BINDING method, REQUEST and SUCCESS classes,
- *              XOR-MAPPED-ADDRESS / MAPPED-ADDRESS attributes for IPv4 + IPv6.
- *              Authenticated TURN allocations are handled in
- *              `lib/webrtc/turn/`.
+ * @description Zero-dependency RFC 8489 STUN client. Sends a Binding Request
+ *   over UDP, parses the Binding Response, and returns the server-reflexive
+ *   address from XOR-MAPPED-ADDRESS (or legacy MAPPED-ADDRESS). NAT-discovery
+ *   subset only; TURN allocations live in `lib/webrtc/turn/`.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8489
- * @see https://datatracker.ietf.org/doc/html/rfc5769  (test vectors)
  */
 
 'use strict';

package/lib/webrtc/turn/credentials.js

@@ -1,19 +1,10 @@
 /**
  * @file lib/webrtc/turn/credentials.js
  * @module @zero-server/webrtc/turn/credentials
- * @description RFC 7635 ephemeral TURN credentials.
- *
- *   Generates time-limited username / credential pairs that any
- *   RFC 7635-compatible TURN server (notably `coturn` with
- *   `use-auth-secret` + `static-auth-secret=<S>`) will accept.
- *
- *   Wire format (RFC 7635 §6.2):
- *     username   = "<unix-expiry>:<userId>"
- *     credential = base64( HMAC-SHA1( <secret>, username ) )
- *
- *   The returned object is shaped like an `RTCIceServer` entry so it can
- *   be embedded straight into the ICE-server list a signaling endpoint
- *   serves to browsers.
+ * @description RFC 7635 ephemeral TURN credentials. Generates short-TTL
+ *   username/credential pairs accepted by any compliant TURN server
+ *   (notably `coturn` with `use-auth-secret`). Returns an `RTCIceServer`-
+ *   shaped object ready to hand to browsers.
  */
 
 'use strict';
@@ -53,14 +44,38 @@ const VALID_SCHEMES = ['turn:', 'turns:', 'stun:', 'stuns:'];
  * @returns {TurnCredentials}
  * @throws {TurnError} On missing / invalid input.
  *
- * @example
+ * @example | Hand a fresh credential to a browser before it joins a room
+ *   //   coturn.conf:
+ *   //     use-auth-secret
+ *   //     static-auth-secret=<TURN_SHARED_SECRET>
+ *   //     realm=turn.example.com
+ *   app.get('/rtc/turn', (req, res) => {
+ *       const creds = issueTurnCredentials({
+ *           secret:  process.env.TURN_SHARED_SECRET,
+ *           userId:  req.user.id,
+ *           ttl:     '20m',
+ *           servers: ['turn:turn.example.com:3478?transport=udp'],
+ *       });
+ *       res.json(creds); // { urls, username, credential, ttl }
+ *   });
+ *
+ * @example | Multiple URLs (UDP, TCP, TLS) for failover
  *   const creds = issueTurnCredentials({
  *       secret:  process.env.TURN_SHARED_SECRET,
- *       userId:  req.user.id,
- *       ttl:     '20m',
- *       servers: ['turn:turn.example.com:3478?transport=udp'],
+ *       userId:  'bot-42',
+ *       ttl:     3600,
+ *       servers: [
+ *           'turn:turn.example.com:3478?transport=udp',
+ *           'turn:turn.example.com:3478?transport=tcp',
+ *           'turns:turn.example.com:5349',
+ *           'stun:turn.example.com:3478',
+ *       ],
+ *   });
+ *
+ * @example | Use directly in an RTCPeerConnection (browser side)
+ *   const pc = new RTCPeerConnection({
+ *       iceServers: [creds], // { urls, username, credential } is RTCIceServer-shaped
  *   });
- *   res.json(creds);
  *
  * @section ICE & TURN
  */