@zero-server/sdk 0.9.7 → 0.9.8

package/README.md

@@ -12,7 +12,7 @@
 
 <p align="center">
   <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/tonywied17/zero-server/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
-  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7767%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
+  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7777%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
   <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-95.85%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
   <a href="https://z-server.dev"><img src="https://img.shields.io/badge/docs-z--server.dev-00d8e0?style=flat-square&logo=readthedocs&logoColor=white" alt="docs"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-00d8e0?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="MIT"></a>
@@ -55,13 +55,14 @@ npm install @zero-server/core @zero-server/body @zero-server/middleware
 | `@zero-server/auth` | `jwt`, `session`, `oauth`, `authorize`, `twoFactor`, `webauthn`, `trustedDevice`, `enrollment` |
 | `@zero-server/orm` | `Database`, `Model`, `Query`, `TYPES`, migrations, seeders, replicas, search, geo, tenancy, audit |
 | `@zero-server/realtime` | `WebSocketConnection`, `WebSocketPool`, `SSEStream` |
+| `@zero-server/webrtc` | signaling hub, rooms/peers, STUN/TURN, SFU adapters (memory, mediasoup, LiveKit), join tokens, E2EE, `spawnBotPeer` |
 | `@zero-server/grpc` | gRPC server, client, codec, status, metadata, framing, health, reflection, balancer |
 | `@zero-server/observe` | `MetricsRegistry`, `Tracer`, structured `Logger`, health checks |
 | `@zero-server/lifecycle` | `LifecycleManager`, `ClusterManager`, `clusterize` |
 | `@zero-server/env` | typed `.env` loader |
 | `@zero-server/fetch` | server-side `fetch` client |
 | `@zero-server/errors` | every typed `HttpError` class plus ORM/framework errors |
-| `@zero-server/cli` | programmatic `CLI` / `runCLI` entry points for `zh` / `zs` |
+| `@zero-server/cli` | programmatic `CLI` / `runCLI` entry points for `zs` |
 
 > Each scoped package is fully standalone at runtime - its own `index.js`, its own bundled lib, its own types. Mix and match freely; versions stay aligned across the `@zero-server/*` release set.
 
@@ -219,16 +220,16 @@ docker run -d -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml pr
 
 ### CLI
 
-Scaffolding and database management via `npx zh`:
+Scaffolding and database management via `npx zs`:
 
 ```bash
-npx zh migrate              # run pending migrations
-npx zh migrate:rollback     # rollback last migration
-npx zh migrate:status       # show migration status
-npx zh seed                 # run seeders
-npx zh make:model User      # scaffold a model
-npx zh make:migration name  # create migration file
-npx zh make:seeder User     # create seeder file
+npx zs migrate              # run pending migrations
+npx zs migrate:rollback     # rollback last migration
+npx zs migrate:status       # show migration status
+npx zs seed                 # run seeders
+npx zs make:model User      # scaffold a model
+npx zs make:migration name  # create migration file
+npx zs make:seeder User     # create seeder file
 ```
 
 ### Environment Config

package/lib/cli.js

@@ -18,13 +18,13 @@
  *   };
  *
  *   // Run via npx (no global install needed):
- *   // npx zh migrate
- *   // npx zh migrate:rollback
- *   // npx zh migrate:status
- *   // npx zh seed
- *   // npx zh make:model User
- *   // npx zh make:migration create_posts
- *   // npx zh make:seeder Users
+ *   // npx zs migrate
+ *   // npx zs migrate:rollback
+ *   // npx zs migrate:status
+ *   // npx zs seed
+ *   // npx zs make:model User
+ *   // npx zs make:migration create_posts
+ *   // npx zs make:seeder Users
  *
  *   // Or programmatically:
  *   const { runCLI } = require('@zero-server/sdk');
@@ -215,7 +215,7 @@ class CLI
             throw new Error(
                 'No configuration file found.\n' +
                 'Create a zero.config.js with database and migration settings.\n' +
-                'See "zh help" for examples.'
+                'See "zs help" for examples.'
             );
         }
 
@@ -431,7 +431,7 @@ class CLI
         if (status.executed.includes(lastMigration.name))
         {
             console.error(red(`Cannot remove "${lastMigration.name}" - it has already been applied.`));
-            console.error(dim('Run "zh migrate:rollback" first, then try again.'));
+            console.error(dim('Run "zs migrate:rollback" first, then try again.'));
             process.exitCode = 1;
             await db.close();
             return;
@@ -519,7 +519,7 @@ class CLI
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:model <Name>'));
+            console.error(red('Usage: zs make:model <Name>'));
             process.exitCode = 1;
             return;
         }
@@ -575,7 +575,7 @@ module.exports = ${className};
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:migration <name>'));
+            console.error(red('Usage: zs make:migration <name>'));
             process.exitCode = 1;
             return;
         }
@@ -701,7 +701,7 @@ module.exports = {
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:seeder <name>'));
+            console.error(red('Usage: zs make:seeder <name>'));
             process.exitCode = 1;
             return;
         }
@@ -751,9 +751,9 @@ module.exports = ${className};
     _help()
     {
         console.log(`
-${bold('zh CLI')} - zero-server ORM tooling
+${bold('zs CLI')} - zero-server ORM tooling
 
-${bold('Usage:')}  npx zh <command> [options]
+${bold('Usage:')}  npx zs <command> [options]
 
 ${bold('Commands:')}
 
@@ -803,19 +803,19 @@ ${bold('Config file:')} ${dim('zero.config.js (or .zero-server.js / legacy .zero
 
 ${bold('Auto-generated migrations:')}
 
-  ${dim('$')} npx zh make:migration create_users  ${dim('# detects new User model → generates CREATE TABLE')}
-  ${dim('$')} npx zh make:migration add_email     ${dim('# detects new email column → generates ADD COLUMN')}
-  ${dim('$')} npx zh make:migration --empty init   ${dim('# blank migration (manual mode)')}
-  ${dim('$')} npx zh migrate                      ${dim('# apply pending migrations')}
-  ${dim('$')} npx zh migrate:remove               ${dim('# undo last make:migration')}
+  ${dim('$')} npx zs make:migration create_users  ${dim('# detects new User model → generates CREATE TABLE')}
+  ${dim('$')} npx zs make:migration add_email     ${dim('# detects new email column → generates ADD COLUMN')}
+  ${dim('$')} npx zs make:migration --empty init   ${dim('# blank migration (manual mode)')}
+  ${dim('$')} npx zs migrate                      ${dim('# apply pending migrations')}
+  ${dim('$')} npx zs migrate:remove               ${dim('# undo last make:migration')}
 
 ${bold('Examples:')}
 
-  ${dim('$')} npx zh make:model User             ${dim('# creates models/User.js')}
-  ${dim('$')} npx zh make:migration create_users  ${dim('# auto-generates from models')}
-  ${dim('$')} npx zh migrate                     ${dim('# runs all pending migrations')}
-  ${dim('$')} npx zh migrate --config=db.config.js
-  ${dim('$')} npx zh seed                        ${dim('# runs all seeders')}
+  ${dim('$')} npx zs make:model User             ${dim('# creates models/User.js')}
+  ${dim('$')} npx zs make:migration create_users  ${dim('# auto-generates from models')}
+  ${dim('$')} npx zs migrate                     ${dim('# runs all pending migrations')}
+  ${dim('$')} npx zs migrate --config=db.config.js
+  ${dim('$')} npx zs seed                        ${dim('# runs all seeders')}
 `);
     }
 
@@ -825,7 +825,7 @@ ${bold('Examples:')}
     _version()
     {
         const pkg = require('../package.json');
-        console.log(`zh v${pkg.version} (zero-server)`);
+        console.log(`zs v${pkg.version} (zero-server)`);
     }
 }
 

package/lib/orm/snapshot.js

@@ -269,7 +269,7 @@ function generateMigrationCode(migrationName, changes, currentSnap)
 
 /**
  * Auto-generated migration - ${migrationName}
- * Generated by: npx zh make:migration
+ * Generated by: npx zs make:migration
  */
 module.exports = {
     name: '${migrationName}',

package/lib/webrtc/bot.js

@@ -1,18 +1,10 @@
 /**
  * @module webrtc/bot
  * @description Server-side WebRTC peer ("bot") built on the `wrtc`
- *   peerDependency.
- *
- *   `spawnBotPeer({hub, room, ...})` attaches an in-process peer to a
- *   {@link SignalingHub}, joins a room, and drives a real
- *   {@link RTCPeerConnection} per remote peer (using the Node.js `wrtc`
- *   binding).  It implements the standard JSEP perfect-negotiation
- *   pattern and is designed for headless workloads such as recording,
- *   transcription, AI agents, and SFU verification harnesses.
- *
- *   The `wrtc` peerDependency is loaded lazily; in production any of
- *   `wrtc` or `@roamhq/wrtc` is acceptable.  Tests inject a fake via
- *   `opts.wrtc`.
+ *   peerDependency. `spawnBotPeer({ hub, room, ... })` attaches an
+ *   in-process peer that joins a room and drives a real
+ *   `RTCPeerConnection` per remote peer. Bidirectional — use for
+ *   recording, transcription, AI participants, or SFU verification.
  */
 'use strict';
 
@@ -43,6 +35,58 @@ const { WebRTCError }  = require('../errors');
  *   ready:              Promise<{ peerId: string }>,
  *   close:              () => void,
  * }}
+ *
+ * @example | Recording bot: dump every inbound audio track to a file
+ *   const { spawnBotPeer } = require('@zero-server/webrtc');
+ *   const { RTCAudioSink } = require('@roamhq/wrtc').nonstandard;
+ *   const fs = require('node:fs');
+ *
+ *   const bot = spawnBotPeer({
+ *       hub,
+ *       room: 'standup',
+ *       user: { id: 'recorder' },
+ *       iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+ *       onTrack: (track, _streams, fromPeerId) => {
+ *           if (track.kind !== 'audio') return;
+ *           const sink = new RTCAudioSink(track);
+ *           const out  = fs.createWriteStream(`./recordings/${fromPeerId}.pcm`);
+ *           sink.ondata = ({ samples }) => out.write(Buffer.from(samples.buffer));
+ *           track.onended = () => { sink.stop(); out.end(); };
+ *       },
+ *   });
+ *
+ *   await bot.ready;          // resolves with { peerId } once the hub welcomes us
+ *   process.on('SIGTERM', () => bot.close());
+ *
+ * @example | AI participant: push synthesized audio back to the room
+ *   const { spawnBotPeer } = require('@zero-server/webrtc');
+ *   const { RTCAudioSource } = require('@roamhq/wrtc').nonstandard;
+ *
+ *   const source = new RTCAudioSource();
+ *   const track  = source.createTrack();
+ *
+ *   const bot = spawnBotPeer({
+ *       hub, room: 'lounge', user: { id: 'ai-host' },
+ *       onPeerJoin: (remoteId) => {
+ *           const pc = bot.getPeerConnection(remoteId);
+ *           if (pc) pc.addTrack(track); // perfect-negotiation will renegotiate
+ *       },
+ *   });
+ *
+ *   // Feed synthesized PCM frames every 10ms.
+ *   setInterval(() => source.onData({
+ *       samples:     ttsNextFrame(),     // Int16Array(160)
+ *       sampleRate:  16000,
+ *       bitsPerSample: 16,
+ *       channelCount:  1,
+ *       numberOfFrames: 160,
+ *   }), 10);
+ *
+ * @example | Inject a fake `wrtc` for unit tests
+ *   const bot = spawnBotPeer({ hub, room: 'test', wrtc: fakeWrtc });
+ *   await bot.ready;
+ *   expect(hub.room('test').size).toBe(1);
+ *   bot.close();
  */
 function spawnBotPeer(opts)
 {

package/lib/webrtc/cli.js

@@ -1,6 +1,6 @@
 /**
  * @module webrtc/cli
- * @description CLI subcommands for the `zh webrtc:*` namespace.
+ * @description CLI subcommands for the `zs webrtc:*` namespace.
  *
  *   Pure-function entry point `runWebRTCCommand(subcmd, flags, deps)` so
  *   the dispatch can be exercised in tests without spawning a child
@@ -10,11 +10,11 @@
  *
  * @example
  *   // From the shell, via the top-level CLI:
- *   //   npx zh webrtc:stun --host stun.l.google.com --port 19302
- *   //   npx zh webrtc:turn-creds --secret $SECRET --user alice \
+ *   //   npx zs webrtc:stun --host stun.l.google.com --port 19302
+ *   //   npx zs webrtc:turn-creds --secret $SECRET --user alice \
  *   //                           --servers turn:turn.example.com:3478
- *   //   npx zh webrtc:join-token --secret $JT_SECRET --room lobby --sub u1
- *   //   npx zh webrtc:verify-token --secret $JT_SECRET --token $TOKEN
+ *   //   npx zs webrtc:join-token --secret $JT_SECRET --room lobby --sub u1
+ *   //   npx zs webrtc:verify-token --secret $JT_SECRET --token $TOKEN
  *
  *   // Programmatically:
  *   const { runWebRTCCommand } = require('@zero-server/webrtc/cli');
@@ -168,7 +168,7 @@ function runVerifyToken(flags, { out })
 function helpText()
 {
     return [
-        'zh webrtc:* - WebRTC tooling',
+        'zs webrtc:* - WebRTC tooling',
         '',
         'Subcommands:',
         '  webrtc:stun         --host H [--port 3478] [--timeout 1000] [--retries 1]',

package/lib/webrtc/cluster.js

@@ -1,22 +1,10 @@
 /**
  * @module webrtc/cluster
- * @description Cluster adapter for the WebRTC signaling hub.
- *
- *   `useCluster(hub, adapter)` glues a `SignalingHub` to any pub/sub
- *   adapter that implements `{ publish(channel, message), subscribe(
- *   channel, cb) -> unsubscribe }`.  Once attached:
- *
- *   - Every local `join` / `leave` is announced cluster-wide so other
- *     nodes can resolve a `peer.id` to its owning node.
- *   - Every `room.broadcast(...)` is mirrored to peers in the same room
- *     on other nodes.
- *   - Direct frames (`offer`, `answer`, `ice`) addressed to a peer that
- *     lives on a different node are forwarded to that node's inbox.
- *
- *   The adapter itself is intentionally tiny so production deployments
- *   can wire it up to Redis, NATS, Kafka, or any in-house bus.  A
- *   `MemoryClusterAdapter` is provided for tests and single-process
- *   simulations.
+ * @description Cluster adapter for the signaling hub. `useCluster(hub,
+ *   adapter)` glues a `SignalingHub` to any `{ publish, subscribe }`
+ *   pub/sub bus so joins, leaves, broadcasts, and direct frames flow
+ *   across nodes. Ships with `MemoryClusterAdapter`; wire to Redis, NATS,
+ *   Kafka, or any in-house bus in production.
  *
  * @section Cluster
  */

package/lib/webrtc/e2ee.js

@@ -1,18 +1,10 @@
 /**
  * @module webrtc/e2ee
- * @description End-to-end-encrypted key relay channel for WebRTC.
- *
- *   The hub never sees plaintext SFrame / Insertable-Streams keys.
- *   Publishers wrap each rotation in a sealed envelope (X25519 ECDH +
- *   HKDF-SHA-256 + AES-256-GCM) and broadcast it via the `e2ee-key`
- *   wire message; subscribers in the same room receive the sealed
- *   payload and decrypt locally with their private key.
- *
- *   For deployments that use a different sealing primitive (NaCl
- *   `crypto_box_seal`, libsignal, etc.) the {@link E2eeChannel} works
- *   with any opaque `Buffer` - the {@link sealKey} / {@link openSealedKey}
- *   helpers are provided as a zero-dependency default that satisfies the
- *   HIPAA / FINRA "server is opaque" requirement.
+ * @description End-to-end-encrypted key relay for WebRTC. Publishers wrap
+ *   SFrame/Insertable-Streams keys in sealed envelopes (X25519 + HKDF-SHA-256
+ *   + AES-256-GCM) and broadcast via `e2ee-key`; the hub stays opaque.
+ *   `E2eeChannel` accepts any opaque `Buffer`, so libsignal or NaCl-sealed
+ *   payloads work out of the box.
  *
  * @section E2EE
  */

package/lib/webrtc/ice.js

@@ -1,16 +1,9 @@
 /**
  * @module webrtc/ice
  * @description Zero-dependency ICE candidate parser, serializer, and address
- *              classifiers (private / loopback / link-local / mDNS), plus a
- *              `filterCandidates` helper used by `SignalingHub` to enforce
- *              privacy-preserving policies on relayed offers/answers.
- *
- *              Candidate grammar follows RFC 8839 §5.1 / RFC 5245 §15.1:
- *
- *                candidate-attribute = "candidate" ":" foundation SP component-id
- *                                      SP transport SP priority SP connection-address
- *                                      SP port SP cand-type [SP rel-addr] [SP rel-port]
- *                                      *(SP extension-att-name SP extension-att-value)
+ *   classifiers (private / loopback / link-local / mDNS) per RFC 8839,
+ *   plus a `filterCandidates` helper used by `SignalingHub` to enforce
+ *   privacy-preserving policies on relayed offers/answers.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8839
  * @see https://datatracker.ietf.org/doc/html/rfc5245

package/lib/webrtc/index.js

@@ -1,14 +1,91 @@
 /**
  * @module @zero-server/webrtc
- * @description First-class WebRTC support for Zero Server.
+ * @description First-class, batteries-included WebRTC support for Zero Server.
  *
- *   Signaling hub, room / peer orchestration, RFC 8489 STUN client,
- *   RFC 7635 TURN credential issuance, optional embedded TURN server,
- *   SFrame E2EE key relay, and a pluggable SFU adapter interface.
+ *   `@zero-server/webrtc` is a complete signaling + NAT-traversal toolkit you
+ *   can drop into any Zero Server app.  Everything is pure JavaScript with
+ *   zero hard dependencies — bring your own media engine (`wrtc`, browsers,
+ *   `mediasoup`, LiveKit, ...) and the library handles the rest.
  *
- *   Implementation is landing PR-by-PR per `.myshit/WEBRTC-ROADMAP.md`.
- *   Real exports already live in this barrel; the rest throw
- *   `WEBRTC_NOT_IMPLEMENTED` so accidental production use fails loud.
+ *   Surface area:
+ *
+ *   - **Signaling** — {@link SignalingHub}, {@link Room}, {@link Peer}.  A
+ *     transport-agnostic WS broker that owns the room registry, validates
+ *     JSEP traffic (offer / answer / ICE / `e2ee-key`), enforces per-peer
+ *     and per-IP rate limits, supports policy gates (`require()`,
+ *     `canPublish()`), and emits lifecycle events.
+ *   - **JSEP parsing** — {@link parseSdp}, {@link stringifySdp},
+ *     {@link parseCandidate}, {@link stringifyCandidate},
+ *     {@link filterCandidates}.  RFC 8866 / 8839 compliant pure-JS codecs.
+ *   - **STUN client** — {@link stunBinding} (RFC 5389 / 8489) for public-IP
+ *     discovery, plus low-level attribute encoders.
+ *   - **TURN** — {@link issueTurnCredentials} (RFC 7635 ephemeral creds) and
+ *     a full embedded {@link TurnServer} that speaks STUN/TURN over UDP.
+ *   - **Join tokens** — {@link signJoinToken} / {@link verifyJoinToken}: HS256
+ *     JWTs scoped to `room:<name>` with publish / subscribe claims.
+ *   - **End-to-end encryption** — {@link E2eeChannel}, {@link attachE2ee},
+ *     {@link generateE2eeKeyPair}, {@link sealKey}, {@link openSealedKey}.
+ *     SFrame-compatible key-relay primitives; the hub never sees media.
+ *   - **SFU adapters** — {@link SfuAdapter} interface plus first-party
+ *     {@link MemorySfuAdapter} (tests), {@link MediasoupSfuAdapter},
+ *     {@link LiveKitSfuAdapter}.  Pluggable via {@link loadSfuAdapter}.
+ *   - **Cluster** — {@link useCluster}, {@link ClusterCoordinator}, and the
+ *     {@link MemoryClusterAdapter} so multiple hub instances can share a
+ *     room registry behind a load balancer.
+ *   - **Server-side peer** — {@link spawnBotPeer} for headless recorders,
+ *     transcribers, or AI participants using `node-wrtc`.
+ *   - **Observability** — {@link bindObservability} wires Prometheus
+ *     counters / histograms and structured logs into a hub.
+ *   - **CLI** — {@link runWebRTCCommand} powers `zs webrtc:*` for STUN
+ *     probes, TURN credential issuance, and join-token sign / verify.
+ *
+ * @example | Bind a signaling hub to a Zero Server `app.ws()` route
+ *   const { createApp } = require('@zero-server/sdk');
+ *   const { SignalingHub, bindObservability } = require('@zero-server/webrtc');
+ *
+ *   const app = createApp();
+ *   const hub = new SignalingHub({
+ *       joinTokenSecret: process.env.WEBRTC_JWT_SECRET,
+ *       ipAttachRate: 60,          // max 60 attaches / IP / min
+ *       maxSdpSize: 64 * 1024,
+ *   });
+ *
+ *   bindObservability(hub, { app }); // exposes /metrics for Prometheus
+ *
+ *   app.ws('/rtc', (ws, req) =>
+ *   {
+ *       const peer = hub.attach(ws, {
+ *           user: req.user,
+ *           ip: req.ip,
+ *           origin: req.headers.origin,
+ *       });
+ *       ws.on('close', () => peer.close());
+ *   });
+ *
+ *   app.listen(3000);
+ *
+ * @example | Issue a join token and a TURN credential to a browser
+ *   const {
+ *       signJoinToken, issueTurnCredentials,
+ *   } = require('@zero-server/webrtc');
+ *
+ *   app.get('/rtc/session/:room', (req, res) =>
+ *   {
+ *       const token = signJoinToken({
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           room: req.params.room,
+ *           userId: req.user.id,
+ *           publish: req.user.isHost,
+ *           ttlSec: 60 * 30,
+ *       });
+ *       const turn = issueTurnCredentials({
+ *           secret: process.env.TURN_SHARED_SECRET,
+ *           userId: req.user.id,
+ *           ttlSec: 60 * 60,
+ *           uris: ['turn:turn.example.com:3478?transport=udp'],
+ *       });
+ *       res.json({ token, iceServers: turn.iceServers });
+ *   });
  */
 
 'use strict';
@@ -49,30 +126,31 @@ const { spawnBotPeer }        = require('./bot');
 
 /**
  * @private
- * Sentinel for surfaces that have not yet been implemented.  Each PR in the
- * roadmap replaces one of these with a real function/class export.
+ * Sentinel for surfaces that are intentionally not exported yet.  Reserved
+ * for future top-level shortcuts; current consumers should construct a
+ * `SignalingHub` directly and use `bindObservability(hub, { app })`.
  */
 const notImplemented = (name) =>
 {
     throw new WebRTCError(
-        `${name} is not implemented yet - see .myshit/WEBRTC-ROADMAP.md for the implementation plan.`,
+        `${name} is not implemented yet - construct \`new SignalingHub(opts)\` directly and wire it via \`app.ws()\`.`,
         { code: 'WEBRTC_NOT_IMPLEMENTED' },
     );
 };
 
 module.exports = {
-    // Signaling - landing in a later PR
+    // Signaling
     createWebRTC:          () => notImplemented('createWebRTC'),
     SignalingHub,
     Room,
     Peer,
     PEER_STATE,
 
-    // SDP - PR 1
+    // SDP / JSEP
     parseSdp,
     stringifySdp,
 
-    // ICE - PR 1
+    // ICE candidate utilities
     parseCandidate,
     stringifyCandidate,
     filterCandidates,
@@ -83,7 +161,7 @@ module.exports = {
     CANDIDATE_TYPES,
     TCP_TYPES,
 
-    // NAT traversal - later PRs
+    // STUN client + low-level codecs
     stunBinding,
     encodeBindingRequest,
     decodeMessage,
@@ -93,10 +171,12 @@ module.exports = {
     STUN_METHOD,
     STUN_CLASS,
     STUN_ATTR,
+
+    // TURN
     issueTurnCredentials,
     TurnServer,
 
-    // SFU + tokens - later PRs
+    // SFU adapters + tokens
     SfuAdapter,
     MemorySfuAdapter,
     MediasoupSfuAdapter,
@@ -105,20 +185,20 @@ module.exports = {
     signJoinToken,
     verifyJoinToken,
 
-    // Server-side WebRTC peer (wrtc bot)
+    // Server-side WebRTC peer (node-wrtc bot)
     spawnBotPeer,
 
-    // Observability - PR 6
+    // Observability
     bindObservability,
 
-    // E2EE key relay - PR 7
+    // SFrame E2EE key relay
     E2eeChannel,
     attachE2ee,
     generateE2eeKeyPair,
     sealKey,
     openSealedKey,
 
-    // Cluster - PR 8
+    // Cluster coordination
     useCluster,
     ClusterCoordinator,
     MemoryClusterAdapter,

package/lib/webrtc/joinToken.js

@@ -1,11 +1,28 @@
 /**
  * @module webrtc/joinToken
- * @description Signed, short-TTL join tokens that authenticate a peer's
- *              right to join a specific room.  JWT-shaped (HS256 by default)
- *              and audience-scoped to `room:<name>` so a token leaked from
- *              one channel cannot be replayed against another.
+ * @description Signed, short-TTL JWT join tokens scoped to `room:<name>`.
+ *   HS256 by default, RS256 supported. Verification is constant-time and
+ *   surfaces every failure mode as `WebRTCError({ code: 'INVALID_TOKEN' })`.
+ *   The hub auto-enforces tokens when constructed with `joinTokenSecret`.
  *
- *   Reuses the canonical sign/verify primitives from `lib/auth/jwt.js`.
+ * @example | Browser receives a token from a regular HTTP route
+ *   // server.js
+ *   const { signJoinToken } = require('@zero-server/webrtc');
+ *   app.get('/rtc/token/:room', (req, res) => {
+ *       const token = signJoinToken({
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           user:   req.user,          // { id, name, role }
+ *           room:   req.params.room,
+ *           ttl:    300,               // 5 minute window
+ *           claims: { publish: req.user.isHost === true },
+ *       });
+ *       res.json({ wsUrl: '/rtc', token });
+ *   });
+ *
+ *   // client.js (pseudo)
+ *   const { wsUrl, token } = await fetch(`/rtc/token/${room}`).then(r => r.json());
+ *   ws = new WebSocket(wsUrl);
+ *   ws.onopen = () => ws.send(JSON.stringify({ type: 'join', room, token }));
  */
 
 'use strict';
@@ -27,15 +44,34 @@ const { SignalingError, WebRTCError } = require('../errors');
  * @param {object}        [opts.claims]    - Additional claims merged into the payload.
  * @returns {string} Compact JWT.
  *
- * @example
+ * @example | Simple HS256 token with a user object
  *   const token = signJoinToken({
  *       secret: process.env.JOIN_SECRET,
- *       user:   req.user,
+ *       user:   req.user,           // { id: 'u_42', name: 'Ada', role: 'host' }
  *       room:   'boardroom',
  *       ttl:    300,
  *   });
  *   res.json({ wsUrl: '/rtc', token });
  *
+ * @example | Embed publish / subscribe permissions as custom claims
+ *   const token = signJoinToken({
+ *       secret: process.env.JOIN_SECRET,
+ *       user:   { id: 'guest_' + crypto.randomUUID() },
+ *       room:   'webinar-42',
+ *       ttl:    60 * 30,            // 30 minute viewer session
+ *       claims: { publish: false, subscribe: true, tier: 'free' },
+ *   });
+ *
+ * @example | RS256 with a per-tenant key id
+ *   const token = signJoinToken({
+ *       secret:    fs.readFileSync('./keys/tenant-A.private.pem'),
+ *       algorithm: 'RS256',
+ *       user:      req.user,
+ *       room:      'tenantA:lobby',
+ *       ttl:       300,
+ *       claims:    { kid: 'tenantA-2025-01' },
+ *   });
+ *
  * @section Signaling
  */
 function signJoinToken(opts = {})
@@ -80,6 +116,25 @@ function signJoinToken(opts = {})
  * @param {number} [opts.clockTolerance=0]
  * @returns {object} Verified payload.
  *
+ * @example | Manually verify a token (most apps never need this — the hub does it)
+ *   try {
+ *       const payload = verifyJoinToken(req.body.token, {
+ *           secret: process.env.WEBRTC_JWT_SECRET,
+ *           room:   'boardroom',
+ *       });
+ *       console.log('peer is', payload.user.id, 'publish =', payload.publish);
+ *   } catch (err) {
+ *       // err.code === 'INVALID_TOKEN'
+ *       res.status(401).json({ error: err.message });
+ *   }
+ *
+ * @example | Allow a 30-second clock skew between issuer and verifier
+ *   const payload = verifyJoinToken(token, {
+ *       secret:         sharedSecret,
+ *       room:           'lobby',
+ *       clockTolerance: 30,
+ *   });
+ *
  * @section Signaling
  */
 function verifyJoinToken(token, opts = {})