@zero-server/sdk 0.9.6 → 0.9.8

package/lib/webrtc/joinToken.js

@@ -0,0 +1,171 @@
+/**
+ * @module webrtc/joinToken
+ * @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`.
+ *
+ * @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';
+
+const { sign, verify } = require('../auth');
+const { SignalingError, WebRTCError } = require('../errors');
+
+/**
+ * Issue a join token for `user` to enter `room`.
+ *
+ * @param {object} opts
+ * @param {string|Buffer} opts.secret    - HMAC secret (HS256) or PEM key (RS256).
+ * @param {string|object} opts.user      - User identifier (string) or object containing `id`.
+ * @param {string}        opts.room      - Target room name.
+ * @param {number}        [opts.ttl=300] - Seconds until expiry.  Negative values are accepted
+ *                                         (used by tests to mint already-expired tokens).
+ * @param {string}        [opts.algorithm='HS256']
+ * @param {string|string[]} [opts.audience] - Override the default `room:<name>` audience.
+ * @param {object}        [opts.claims]    - Additional claims merged into the payload.
+ * @returns {string} Compact JWT.
+ *
+ * @example | Simple HS256 token with a user object
+ *   const token = signJoinToken({
+ *       secret: process.env.JOIN_SECRET,
+ *       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 = {})
+{
+    if (!opts || typeof opts !== 'object')
+        throw new SignalingError('signJoinToken: opts must be an object');
+    if (!opts.secret) throw new SignalingError('signJoinToken: secret is required');
+    if (opts.user === undefined || opts.user === null)
+        throw new SignalingError('signJoinToken: user is required');
+    if (typeof opts.room !== 'string' || opts.room.length === 0)
+        throw new SignalingError('signJoinToken: room is required');
+
+    const ttl   = Number.isFinite(opts.ttl) ? opts.ttl : 300;
+    const sub   = typeof opts.user === 'string' ? opts.user
+                : (opts.user && (opts.user.id || opts.user.userId || opts.user.sub));
+    if (!sub)   throw new SignalingError('signJoinToken: user.id is required');
+
+    const payload = Object.assign({}, opts.claims || {}, {
+        room: opts.room,
+        user: typeof opts.user === 'object' ? opts.user : { id: sub },
+    });
+
+    return sign(payload, opts.secret, {
+        algorithm: opts.algorithm || 'HS256',
+        expiresIn: ttl,
+        subject:   String(sub),
+        audience:  opts.audience || ('room:' + opts.room),
+    });
+}
+
+/**
+ * Verify a join token and return its payload.  Throws a `WebRTCError` with
+ * `code: 'INVALID_TOKEN'` on any failure - bad signature, expired, audience
+ * mismatch, malformed, etc.
+ *
+ * @param {string} token
+ * @param {object} opts
+ * @param {string|Buffer} opts.secret
+ * @param {string} [opts.room]              - If supplied, audience must be `room:<room>`.
+ * @param {string|string[]} [opts.audience] - Explicit audience override.
+ * @param {string|string[]} [opts.algorithms=['HS256']]
+ * @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 = {})
+{
+    if (!opts || typeof opts !== 'object')
+        throw new WebRTCError('verifyJoinToken: opts must be an object', { code: 'INVALID_TOKEN' });
+    if (!opts.secret)
+        throw new WebRTCError('verifyJoinToken: secret is required', { code: 'INVALID_TOKEN' });
+    if (typeof token !== 'string' || token.length === 0)
+        throw new WebRTCError('verifyJoinToken: token must be a non-empty string', { code: 'INVALID_TOKEN' });
+
+    const audience = opts.audience || (opts.room ? 'room:' + opts.room : undefined);
+    try
+    {
+        const { payload } = verify(token, opts.secret, {
+            algorithms:      opts.algorithms || ['HS256'],
+            audience,
+            clockTolerance:  opts.clockTolerance || 0,
+        });
+        if (opts.room && payload.room && payload.room !== opts.room)
+            throw new WebRTCError('verifyJoinToken: room claim mismatch', { code: 'INVALID_TOKEN' });
+        return payload;
+    }
+    catch (err)
+    {
+        if (err instanceof WebRTCError) throw err;
+        throw new WebRTCError(
+            'verifyJoinToken: ' + (err && err.message ? err.message : 'invalid token'),
+            { code: 'INVALID_TOKEN', cause: err && err.code ? err.code : undefined },
+        );
+    }
+}
+
+module.exports = { signJoinToken, verifyJoinToken };

package/lib/webrtc/observe.js

@@ -0,0 +1,260 @@
+/**
+ * @module webrtc/observe
+ * @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';
+
+// --- Helpers ---
+
+/** Extract the first `a=ice-ufrag:` value from an SDP blob. */
+function _extractUfrag(sdp)
+{
+    const m = /^a=ice-ufrag:([^\r\n]+)/m.exec(sdp);
+    return m ? m[1].trim() : null;
+}
+
+// --- Metrics binder ---
+
+function _registerMetrics(registry)
+{
+    return {
+        peersActive: registry.gauge({
+            name:   'zs_webrtc_peers_active',
+            help:   'Number of WebRTC peers currently joined per room.',
+            labels: ['room'],
+        }),
+        roomsActive: registry.gauge({
+            name: 'zs_webrtc_rooms_active',
+            help: 'Number of WebRTC rooms with at least one peer.',
+        }),
+        signalingMessages: registry.counter({
+            name:   'zs_webrtc_signaling_messages_total',
+            help:   'WebRTC signaling messages by type, direction, and outcome.',
+            labels: ['type', 'direction', 'result'],
+        }),
+        offerDuration: registry.histogram({
+            name:    'zs_webrtc_offer_duration_ms',
+            help:    'End-to-end latency between an offer and its matching answer, in ms.',
+            labels:  ['room'],
+            buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+        }),
+        joinFailures: registry.counter({
+            name:   'zs_webrtc_join_failures_total',
+            help:   'WebRTC room joins rejected by the hub.',
+            labels: ['reason'],
+        }),
+        iceRestart: registry.counter({
+            name:   'zs_webrtc_ice_restart_total',
+            help:   'Detected ICE restarts (ufrag rotation) per room.',
+            labels: ['room'],
+        }),
+    };
+}
+
+function _bindMetrics(hub, m)
+{
+    /** Outstanding offer timestamps: `offererPeerId` -> ms epoch. */
+    const offerStart = new Map();
+    /** Last seen ufrag per peer.id (for ICE-restart detection). */
+    const lastUfrag = new Map();
+
+    hub.on('signal', ({ peer, type }) =>
+    {
+        m.signalingMessages.inc({ type, direction: 'in', result: 'ok' });
+    });
+
+    hub.on('join', ({ peer, room }) =>
+    {
+        const before = m.peersActive.get({ room: room.name });
+        m.peersActive.inc({ room: room.name });
+        // Room newly non-empty?
+        if (before === 0) m.roomsActive.inc();
+    });
+
+    hub.on('leave', ({ peer, room }) =>
+    {
+        m.peersActive.dec({ room: room.name });
+        if (m.peersActive.get({ room: room.name }) <= 0)
+            m.roomsActive.dec();
+    });
+
+    hub.on('joinFailed', ({ reason }) =>
+    {
+        m.joinFailures.inc({ reason: reason || 'UNKNOWN' });
+    });
+
+    hub.on('offer', ({ peer, sdp, room }) =>
+    {
+        offerStart.set(peer.id, Date.now());
+
+        // ICE-restart detection: compare ufrag against last-known for this peer.
+        const ufrag = _extractUfrag(sdp);
+        if (ufrag)
+        {
+            const prev = lastUfrag.get(peer.id);
+            if (prev && prev !== ufrag)
+                m.iceRestart.inc({ room: room.name });
+            lastUfrag.set(peer.id, ufrag);
+        }
+    });
+
+    hub.on('answer', ({ peer, target, room }) =>
+    {
+        // The offer was sent by the original target (now answering back to it).
+        const startedAt = offerStart.get(target.id);
+        if (startedAt !== undefined)
+        {
+            m.offerDuration.observe({ room: room.name }, Date.now() - startedAt);
+            offerStart.delete(target.id);
+        }
+    });
+}
+
+// --- Tracing binder ---
+
+function _bindTracing(hub, tracer)
+{
+    hub.on('signal', ({ peer, type }) =>
+    {
+        const span = tracer.startSpan('webrtc.signal', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'rtc.type': type },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('join', ({ peer, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.join', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('joinFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.join', {
+            kind:       'server',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+
+    hub.on('offer', ({ peer, target, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.publish', {
+            kind:       'producer',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name, 'rtc.target': target.id },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('publishFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.publish', {
+            kind:       'producer',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+
+    hub.on('answer', ({ peer, target, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.subscribe', {
+            kind:       'consumer',
+            attributes: { 'peer.id': peer.id, 'room.id': room.name, 'rtc.target': target.id },
+        });
+        span.setOk();
+        span.end();
+    });
+
+    hub.on('subscribeFailed', ({ peer, reason, room }) =>
+    {
+        const span = tracer.startSpan('webrtc.subscribe', {
+            kind:       'consumer',
+            attributes: { 'peer.id': peer.id, 'room.id': room || '', 'rtc.error': reason },
+        });
+        span.setError(reason);
+        span.end();
+    });
+}
+
+// --- Public API ---
+
+/**
+ * Wire a {@link SignalingHub} to a metrics registry and / or a tracer.
+ *
+ * Registers six standard Prometheus series under the `zs_webrtc_` prefix:
+ *
+ * - `zs_webrtc_peers_active{room}`            (gauge)
+ * - `zs_webrtc_rooms_active`                  (gauge)
+ * - `zs_webrtc_signaling_messages_total{type,direction,result}` (counter)
+ * - `zs_webrtc_offer_duration_ms{room}`       (histogram)
+ * - `zs_webrtc_join_failures_total{reason}`   (counter)
+ * - `zs_webrtc_ice_restart_total{room}`       (counter)
+ *
+ * Emits spans named `webrtc.join`, `webrtc.signal`, `webrtc.publish`, and
+ * `webrtc.subscribe`, each annotated with `peer.id` and `room.id`.
+ *
+ * @section Observability
+ *
+ * @param {SignalingHub} hub - The hub to instrument.
+ * @param {object} opts
+ * @param {MetricsRegistry} [opts.metrics] - Prometheus-compatible registry.
+ * @param {Tracer}          [opts.tracer]  - Tracer for span emission.
+ * @returns {SignalingHub} The same hub, for chaining.
+ *
+ * @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 });
+ *   // 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 = {})
+{
+    if (opts.metrics) _bindMetrics(hub, _registerMetrics(opts.metrics));
+    if (opts.tracer)  _bindTracing(hub, opts.tracer);
+    return hub;
+}
+
+module.exports = { bindObservability };

package/lib/webrtc/peer.js

@@ -0,0 +1,143 @@
+/**
+ * @module webrtc/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.
+ *
+ * @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';
+
+let _peerCounter = 0;
+
+/**
+ * JSEP signaling state strings, matching RFC 8829 §4.1.
+ * @enum {string}
+ */
+const PEER_STATE = Object.freeze({
+    STABLE:             'stable',
+    HAVE_LOCAL_OFFER:   'have-local-offer',
+    HAVE_REMOTE_OFFER:  'have-remote-offer',
+});
+
+/**
+ * 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 | Push a per-peer welcome and tap mute events
+ *   hub.on('join', ({ peer, room }) => {
+ *       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
+{
+    /**
+     * @constructor
+     * @param {object} transport - Anything with `send(string)`, `on('message'|'close', cb)`, `close(code?, reason?)`.
+     * @param {object} [info]    - Connection metadata.
+     * @param {*}      [info.user] - Authenticated user object (if any).
+     * @param {string} [info.ip]   - Remote IP for audit / rate limits.
+     */
+    constructor(transport, info = {})
+    {
+        /** @type {string} Globally-unique peer id within a hub. */
+        this.id = 'peer_' + (++_peerCounter) + '_' + Date.now().toString(36);
+
+        /** @type {*} Authenticated user object (if any). */
+        this.user = info.user || null;
+
+        /** @type {string|null} Remote IP for audit / rate limits. */
+        this.ip = info.ip || null;
+
+        /** @type {object} Underlying transport (WS connection or mock). */
+        this.transport = transport;
+
+        /** @type {string} Current JSEP state. */
+        this.state = PEER_STATE.STABLE;
+
+        /** @type {import('./room')|null} Current room membership. */
+        this.room = null;
+
+        /** @type {number} Count of malformed frames received - rate-limit material. */
+        this.errors = 0;
+
+        /** @type {number} ms timestamp the peer was created. */
+        this.connectedAt = Date.now();
+
+        /** @type {boolean} */
+        this.closed = false;
+    }
+
+    /**
+     * Send a JSON envelope to this peer.  `type` is added to `payload` and
+     * the result is serialised once.  Silently drops sends after close.
+     * @param {string} type
+     * @param {object} [payload]
+     */
+    send(type, payload)
+    {
+        if (this.closed) return;
+        const frame = Object.assign({ type }, payload || {});
+        try { this.transport.send(JSON.stringify(frame)); }
+        catch { /* transport may already be closed; ignore */ }
+    }
+
+    /**
+     * Send a typed error frame.  Callers SHOULD use this rather than throwing,
+     * because exceptions escape the message handler and tear down the process.
+     * @param {string} code
+     * @param {string} message
+     */
+    sendError(code, message)
+    {
+        this.send('error', { code, message });
+    }
+
+    /**
+     * Close the underlying transport with a WebSocket-style code and reason.
+     * Defaults to 1000 (normal closure).
+     * @param {number} [code=1000]
+     * @param {string} [reason='']
+     */
+    close(code = 1000, reason = '')
+    {
+        if (this.closed) return;
+        this.closed = true;
+        try { this.transport.close(code, reason); }
+        catch { /* already closed */ }
+    }
+}
+
+module.exports = { Peer, PEER_STATE };