@zero-server/sdk 0.9.5 → 0.9.7

package/lib/webrtc/index.js

@@ -0,0 +1,132 @@
+/**
+ * @module @zero-server/webrtc
+ * @description First-class 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.
+ *
+ *   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.
+ */
+
+'use strict';
+
+const {
+    WebRTCError, SignalingError, IceError, TurnError, SdpError,
+} = require('../errors');
+
+const { parseSdp, stringifySdp } = require('./sdp');
+const {
+    parseCandidate, stringifyCandidate, filterCandidates,
+    isPrivateIp, isLoopbackIp, isLinkLocalIp, isMdnsHostname,
+    CANDIDATE_TYPES, TCP_TYPES,
+} = require('./ice');
+const {
+    stunBinding, encodeBindingRequest, decodeMessage,
+    encodeXorMappedAddress, decodeXorMappedAddress,
+    STUN_MAGIC_COOKIE, STUN_METHOD, STUN_CLASS, STUN_ATTR,
+} = require('./stun');
+const { issueTurnCredentials } = require('./turn/credentials');
+const { TurnServer } = require('./turn/server');
+const { SignalingHub, Room, Peer, PEER_STATE } = require('./signaling');
+const { signJoinToken, verifyJoinToken } = require('./joinToken');
+const { bindObservability } = require('./observe');
+const {
+    E2eeChannel, attachE2ee,
+    generateE2eeKeyPair, sealKey, openSealedKey,
+} = require('./e2ee');
+const {
+    useCluster, ClusterCoordinator, MemoryClusterAdapter,
+} = require('./cluster');
+const { runWebRTCCommand } = require('./cli');
+const { SfuAdapter, loadSfuAdapter } = require('./sfu');
+const { MemorySfuAdapter } = require('./sfu/memory');
+const { MediasoupSfuAdapter } = require('./sfu/mediasoup');
+const { LiveKitSfuAdapter }   = require('./sfu/livekit');
+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.
+ */
+const notImplemented = (name) =>
+{
+    throw new WebRTCError(
+        `${name} is not implemented yet - see .myshit/WEBRTC-ROADMAP.md for the implementation plan.`,
+        { code: 'WEBRTC_NOT_IMPLEMENTED' },
+    );
+};
+
+module.exports = {
+    // Signaling - landing in a later PR
+    createWebRTC:          () => notImplemented('createWebRTC'),
+    SignalingHub,
+    Room,
+    Peer,
+    PEER_STATE,
+
+    // SDP - PR 1
+    parseSdp,
+    stringifySdp,
+
+    // ICE - PR 1
+    parseCandidate,
+    stringifyCandidate,
+    filterCandidates,
+    isPrivateIp,
+    isLoopbackIp,
+    isLinkLocalIp,
+    isMdnsHostname,
+    CANDIDATE_TYPES,
+    TCP_TYPES,
+
+    // NAT traversal - later PRs
+    stunBinding,
+    encodeBindingRequest,
+    decodeMessage,
+    encodeXorMappedAddress,
+    decodeXorMappedAddress,
+    STUN_MAGIC_COOKIE,
+    STUN_METHOD,
+    STUN_CLASS,
+    STUN_ATTR,
+    issueTurnCredentials,
+    TurnServer,
+
+    // SFU + tokens - later PRs
+    SfuAdapter,
+    MemorySfuAdapter,
+    MediasoupSfuAdapter,
+    LiveKitSfuAdapter,
+    loadSfuAdapter,
+    signJoinToken,
+    verifyJoinToken,
+
+    // Server-side WebRTC peer (wrtc bot)
+    spawnBotPeer,
+
+    // Observability - PR 6
+    bindObservability,
+
+    // E2EE key relay - PR 7
+    E2eeChannel,
+    attachE2ee,
+    generateE2eeKeyPair,
+    sealKey,
+    openSealedKey,
+
+    // Cluster - PR 8
+    useCluster,
+    ClusterCoordinator,
+    MemoryClusterAdapter,
+
+    // CLI
+    runWebRTCCommand,
+
+    // Errors (re-exported from lib/errors.js so consumers can `instanceof` them
+    // through @zero-server/webrtc without also requiring @zero-server/errors).
+    WebRTCError, SignalingError, IceError, TurnError, SdpError,
+};

package/lib/webrtc/joinToken.js

@@ -0,0 +1,116 @@
+/**
+ * @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.
+ *
+ *   Reuses the canonical sign/verify primitives from `lib/auth/jwt.js`.
+ */
+
+'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
+ *   const token = signJoinToken({
+ *       secret: process.env.JOIN_SECRET,
+ *       user:   req.user,
+ *       room:   'boardroom',
+ *       ttl:    300,
+ *   });
+ *   res.json({ wsUrl: '/rtc', token });
+ *
+ * @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.
+ *
+ * @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,229 @@
+/**
+ * @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.
+ */
+
+'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 | Plug into an existing app
+ *   const hub = new SignalingHub();
+ *   bindObservability(hub, { metrics: app.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,116 @@
+/**
+ * @module webrtc/peer
+ * @description Per-connection state machine for a WebRTC signaling peer.
+ *
+ *   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.
+ */
+
+'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.
+ *
+ * @class
+ * @section Peers
+ *
+ * @example
+ *   hub.on('join', ({ peer, room }) => {
+ *       peer.send('welcome', { roomSize: room.size });
+ *       peer.on('mute', ev => audit('mute', peer.id, ev.kind));
+ *   });
+ */
+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 };