@zero-server/sdk 0.9.6 → 0.9.8

package/lib/webrtc/cluster.js

@@ -0,0 +1,338 @@
+/**
+ * @module webrtc/cluster
+ * @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
+ */
+
+'use strict';
+
+const crypto = require('node:crypto');
+
+// --- Channel naming ---
+
+const CH_ANNOUNCE = 'zs:rtc:announce';
+const chRoom = (name) => `zs:rtc:room:${name}`;
+const chNode = (id) => `zs:rtc:node:${id}`;
+
+// --- ClusterCoordinator ---
+
+/**
+ * Per-hub cluster glue.  Created by {@link useCluster} and parked on
+ * `hub._cluster`.  Owns the directory of remote peers and the set of
+ * pub/sub subscriptions.
+ *
+ * @class
+ * @section Cluster
+ */
+class ClusterCoordinator
+{
+    /**
+     * @constructor
+     * @param {import('./signaling').SignalingHub} hub
+     * @param {{publish:Function, subscribe:Function}} adapter
+     * @param {object} [opts]
+     * @param {string} [opts.nodeId] - Stable id for this node.  Defaults to
+     *                                  a random 8-byte hex string.
+     */
+    constructor(hub, adapter, opts = {})
+    {
+        /** @type {import('./signaling').SignalingHub} */
+        this.hub = hub;
+        /** @type {{publish:Function, subscribe:Function}} */
+        this.adapter = adapter;
+        /** @type {string} */
+        this.nodeId = opts.nodeId || crypto.randomBytes(8).toString('hex');
+
+        /**
+         * Remote peer directory.  `peerId -> { nodeId, room }`.
+         * @type {Map<string, {nodeId: string, room: string}>}
+         */
+        this._remotePeers = new Map();
+
+        /** @type {Map<string, Function|null>} */
+        this._roomSubs = new Map();
+
+        /** @type {Function[]} */
+        this._unsubs = [];
+
+        /** @type {boolean} */
+        this._closed = false;
+
+        this._wire();
+    }
+
+    /** @private */
+    _wire()
+    {
+        const offAnnounce = this.adapter.subscribe(CH_ANNOUNCE, (m) => this._onAnnounce(m));
+        const offNode     = this.adapter.subscribe(chNode(this.nodeId), (m) => this._onNodeMsg(m));
+        if (typeof offAnnounce === 'function') this._unsubs.push(offAnnounce);
+        if (typeof offNode === 'function')     this._unsubs.push(offNode);
+
+        this._onJoin = ({ peer, room }) =>
+        {
+            this._ensureRoomSub(room.name);
+            this._safePub(CH_ANNOUNCE, {
+                kind: 'join', nodeId: this.nodeId, peerId: peer.id, room: room.name,
+            });
+        };
+        this._onLeave = ({ peer, room }) =>
+        {
+            this._safePub(CH_ANNOUNCE, {
+                kind: 'leave', nodeId: this.nodeId, peerId: peer.id, room: room.name,
+            });
+        };
+        this.hub.on('join',  this._onJoin);
+        this.hub.on('leave', this._onLeave);
+
+        // Ask existing nodes to rebroadcast their directory.
+        this._safePub(CH_ANNOUNCE, { kind: 'hello', nodeId: this.nodeId });
+    }
+
+    /** @private */
+    _ensureRoomSub(roomName)
+    {
+        if (this._roomSubs.has(roomName)) return;
+        const off = this.adapter.subscribe(chRoom(roomName), (m) => this._onRoomMsg(roomName, m));
+        this._roomSubs.set(roomName, typeof off === 'function' ? off : null);
+    }
+
+    /** @private */
+    _onAnnounce(m)
+    {
+        if (!m || m.nodeId === this.nodeId || this._closed) return;
+        if (m.kind === 'join')
+        {
+            this._remotePeers.set(m.peerId, { nodeId: m.nodeId, room: m.room });
+            this._ensureRoomSub(m.room);
+        }
+        else if (m.kind === 'leave')
+        {
+            const entry = this._remotePeers.get(m.peerId);
+            if (entry && entry.nodeId === m.nodeId) this._remotePeers.delete(m.peerId);
+        }
+        else if (m.kind === 'hello')
+        {
+            // Replay our local directory so the newcomer learns about us.
+            for (const peer of this.hub._peers.values())
+            {
+                if (peer.room)
+                {
+                    this._safePub(CH_ANNOUNCE, {
+                        kind: 'join', nodeId: this.nodeId, peerId: peer.id, room: peer.room.name,
+                    });
+                }
+            }
+        }
+    }
+
+    /** @private */
+    _onNodeMsg(m)
+    {
+        if (!m || m.nodeId === this.nodeId || this._closed) return;
+        const target = this.hub._peers.get(m.target);
+        if (!target) return;
+        target.send(m.type, m.payload);
+    }
+
+    /** @private */
+    _onRoomMsg(roomName, m)
+    {
+        if (!m || m.nodeId === this.nodeId || this._closed) return;
+        const room = this.hub._rooms.get(roomName);
+        if (!room) return;
+        for (const p of room._peers)
+        {
+            if (m.exclude && p.id === m.exclude) continue;
+            p.send(m.type, m.payload);
+        }
+    }
+
+    /**
+     * Look up the node that owns a remote peer, if any.
+     * @param {string} peerId
+     * @returns {{nodeId:string, room:string}|null}
+     */
+    locate(peerId)
+    {
+        return this._remotePeers.get(peerId) || null;
+    }
+
+    /**
+     * Forward a direct frame to a peer on another node.  Called by the
+     * hub when a routed message (`offer` / `answer` / `ice`) targets a
+     * peer id that is not in the local registry.
+     *
+     * @param {string} toPeerId
+     * @param {string} type
+     * @param {object} payload
+     * @returns {boolean} `true` if a remote node was addressed.
+     */
+    routeDirect(toPeerId, type, payload)
+    {
+        const entry = this._remotePeers.get(toPeerId);
+        if (!entry) return false;
+        this._safePub(chNode(entry.nodeId), {
+            nodeId: this.nodeId, target: toPeerId, type, payload,
+        });
+        return true;
+    }
+
+    /**
+     * Mirror a `room.broadcast(...)` to peers in the same room on other
+     * nodes.  Called automatically from `Room#broadcast`.
+     *
+     * @param {string} roomName
+     * @param {string} type
+     * @param {object} payload
+     * @param {string} [excludeId]
+     */
+    fanoutRoom(roomName, type, payload, excludeId)
+    {
+        this._safePub(chRoom(roomName), {
+            nodeId: this.nodeId, type, payload, exclude: excludeId || null,
+        });
+    }
+
+    /** Tear down all subscriptions and clear remote state. */
+    close()
+    {
+        if (this._closed) return;
+        this._closed = true;
+        try { this.hub.off('join',  this._onJoin);  } catch { /* ignore */ }
+        try { this.hub.off('leave', this._onLeave); } catch { /* ignore */ }
+        for (const off of this._unsubs) { try { off(); } catch { /* ignore */ } }
+        for (const off of this._roomSubs.values())
+        {
+            if (typeof off === 'function') { try { off(); } catch { /* ignore */ } }
+        }
+        this._unsubs.length = 0;
+        this._roomSubs.clear();
+        this._remotePeers.clear();
+        if (this.hub._cluster === this) this.hub._cluster = null;
+    }
+
+    /** @private */
+    _safePub(channel, message)
+    {
+        try
+        {
+            const result = this.adapter.publish(channel, message);
+            if (result && typeof result.catch === 'function')
+                result.catch((err) => this.hub.emit('clusterError', err));
+        }
+        catch (err)
+        {
+            this.hub.emit('clusterError', err);
+        }
+    }
+}
+
+// --- useCluster ---
+
+/**
+ * Attach a cluster adapter to a `SignalingHub`.
+ *
+ * @param {import('./signaling').SignalingHub} hub
+ * @param {{publish:Function, subscribe:Function}} adapter
+ * @param {object} [opts]
+ * @param {string} [opts.nodeId]
+ * @returns {ClusterCoordinator}
+ *
+ * @section Cluster
+ *
+ * @example | In-memory cluster (tests / single-process simulation)
+ *   const { SignalingHub, useCluster, MemoryClusterAdapter } = require('@zero-server/webrtc');
+ *   const adapter = new MemoryClusterAdapter();
+ *   const a = new SignalingHub(); useCluster(a, adapter, { nodeId: 'a' });
+ *   const b = new SignalingHub(); useCluster(b, adapter, { nodeId: 'b' });
+ *
+ * @example | Redis adapter (BYO ioredis)
+ *   const Redis = require('ioredis');
+ *   const pub = new Redis(), sub = new Redis();
+ *   const adapter = {
+ *       publish:   (ch, msg) => pub.publish(ch, JSON.stringify(msg)),
+ *       subscribe: (ch, cb) => {
+ *           sub.subscribe(ch);
+ *           const on = (c, raw) => { if (c === ch) cb(JSON.parse(raw)); };
+ *           sub.on('message', on);
+ *           return () => { sub.off('message', on); sub.unsubscribe(ch); };
+ *       },
+ *   };
+ *   useCluster(hub, adapter);
+ */
+function useCluster(hub, adapter, opts)
+{
+    if (!adapter || typeof adapter.publish !== 'function' || typeof adapter.subscribe !== 'function')
+        throw new TypeError('useCluster: adapter must implement { publish, subscribe }');
+    const coord = new ClusterCoordinator(hub, adapter, opts);
+    hub._cluster = coord;
+    return coord;
+}
+
+// --- MemoryClusterAdapter ---
+
+/**
+ * In-memory pub/sub adapter for tests and single-process simulations.
+ * Delivers synchronously to all subscribers on the same channel.
+ *
+ * @class
+ * @section Cluster
+ *
+ * @example
+ *   const adapter = new MemoryClusterAdapter();
+ *   useCluster(hubA, adapter); useCluster(hubB, adapter);
+ */
+class MemoryClusterAdapter
+{
+    constructor()
+    {
+        /** @type {Map<string, Function[]>} */
+        this._channels = new Map();
+    }
+
+    /**
+     * @param {string} channel
+     * @param {*} message
+     */
+    publish(channel, message)
+    {
+        const list = this._channels.get(channel);
+        if (!list || list.length === 0) return;
+        for (const fn of list.slice())
+        {
+            try { fn(message); } catch { /* swallow subscriber errors */ }
+        }
+    }
+
+    /**
+     * @param {string} channel
+     * @param {(msg:*) => void} fn
+     * @returns {() => void} unsubscribe
+     */
+    subscribe(channel, fn)
+    {
+        let list = this._channels.get(channel);
+        if (!list) { list = []; this._channels.set(channel, list); }
+        list.push(fn);
+        return () =>
+        {
+            const cur = this._channels.get(channel);
+            if (!cur) return;
+            const i = cur.indexOf(fn);
+            if (i >= 0) cur.splice(i, 1);
+            if (cur.length === 0) this._channels.delete(channel);
+        };
+    }
+}
+
+module.exports = {
+    useCluster,
+    ClusterCoordinator,
+    MemoryClusterAdapter,
+};

package/lib/webrtc/e2ee.js

@@ -0,0 +1,274 @@
+/**
+ * @module webrtc/e2ee
+ * @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
+ */
+
+'use strict';
+
+const {
+    createPublicKey, createPrivateKey,
+    generateKeyPairSync,
+    diffieHellman,
+    hkdfSync,
+    createCipheriv, createDecipheriv,
+    randomBytes,
+} = require('node:crypto');
+
+const { WebRTCError } = require('../errors');
+
+// --- Envelope constants ---
+
+/** Envelope version byte. */
+const ENVELOPE_VERSION = 0x01;
+
+/** Raw X25519 key length, bytes. */
+const X25519_RAW_LEN = 32;
+
+/** AES-256-GCM nonce length, bytes. */
+const GCM_NONCE_LEN = 12;
+
+/** AES-256-GCM auth tag length, bytes. */
+const GCM_TAG_LEN = 16;
+
+/** HKDF salt - a short constant tying the envelope to this project. */
+const HKDF_INFO = Buffer.from('zs-webrtc/e2ee/v1');
+
+// --- Raw <-> KeyObject helpers ---
+
+function _rawFromPublicKey(pub)
+{
+    if (Buffer.isBuffer(pub) && pub.length === X25519_RAW_LEN) return pub;
+    const jwk = pub.export({ format: 'jwk' });
+    return Buffer.from(jwk.x, 'base64url');
+}
+
+function _publicKeyFromRaw(raw)
+{
+    return createPublicKey({
+        key:    { kty: 'OKP', crv: 'X25519', x: raw.toString('base64url') },
+        format: 'jwk',
+    });
+}
+
+// --- Public crypto helpers ---
+
+/**
+ * Generate a fresh X25519 keypair suitable for {@link sealKey} /
+ * {@link openSealedKey}.
+ *
+ * @returns {{publicKey: KeyObject, privateKey: KeyObject}}
+ *
+ * @example
+ *   const { publicKey, privateKey } = generateE2eeKeyPair();
+ *   const wireKey = publicKey.export({ format: 'jwk' }).x; // base64url
+ */
+function generateE2eeKeyPair()
+{
+    return generateKeyPairSync('x25519');
+}
+
+/**
+ * Seal an opaque byte string for a single recipient using the project's
+ * default envelope (X25519 ECDH + HKDF-SHA-256 + AES-256-GCM).
+ *
+ * Envelope layout:
+ *
+ *   `[ver:1] [ephPubRaw:32] [nonce:12] [ciphertext:N] [tag:16]`
+ *
+ * @param {Buffer|Uint8Array} plaintext        - The bytes to encrypt.
+ * @param {KeyObject|Buffer}  recipientPubKey  - Recipient's X25519 public
+ *                                                key (KeyObject or 32-byte raw).
+ * @returns {Buffer} The sealed envelope.
+ *
+ * @example
+ *   const sealed = sealKey(Buffer.from(sframeKey), bob.publicKey);
+ *   peer.e2ee.publish(epoch, sealed);
+ */
+function sealKey(plaintext, recipientPubKey)
+{
+    const pt    = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext);
+    const pubKO = Buffer.isBuffer(recipientPubKey) ? _publicKeyFromRaw(recipientPubKey) : recipientPubKey;
+
+    const eph    = generateKeyPairSync('x25519');
+    const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: pubKO });
+    const ephRaw = _rawFromPublicKey(eph.publicKey);
+    const recRaw = _rawFromPublicKey(pubKO);
+
+    const salt = Buffer.concat([ephRaw, recRaw]);
+    const aesKey = Buffer.from(hkdfSync('sha256', shared, salt, HKDF_INFO, 32));
+
+    const nonce  = randomBytes(GCM_NONCE_LEN);
+    const cipher = createCipheriv('aes-256-gcm', aesKey, nonce);
+    const ct     = Buffer.concat([cipher.update(pt), cipher.final()]);
+    const tag    = cipher.getAuthTag();
+
+    return Buffer.concat([Buffer.from([ENVELOPE_VERSION]), ephRaw, nonce, ct, tag]);
+}
+
+/**
+ * Open an envelope produced by {@link sealKey} with the recipient's private
+ * key.  Throws if the envelope is malformed, was sealed for a different
+ * recipient, or was tampered with in flight.
+ *
+ * @param {Buffer|Uint8Array} sealed     - Sealed envelope.
+ * @param {KeyObject|Buffer} recipientPrivKey - Recipient's X25519 private key.
+ * @returns {Buffer} Decrypted plaintext.
+ * @throws {WebRTCError} `code='E2EE_OPEN_FAILED'` on any failure.
+ *
+ * @example
+ *   const sframeKey = openSealedKey(received.key, bob.privateKey);
+ */
+function openSealedKey(sealed, recipientPrivKey)
+{
+    const buf = Buffer.isBuffer(sealed) ? sealed : Buffer.from(sealed);
+    const minLen = 1 + X25519_RAW_LEN + GCM_NONCE_LEN + GCM_TAG_LEN;
+    if (buf.length < minLen)
+        throw new WebRTCError('sealed envelope too short', { code: 'E2EE_OPEN_FAILED' });
+    if (buf[0] !== ENVELOPE_VERSION)
+        throw new WebRTCError(`unsupported envelope version 0x${buf[0].toString(16)}`, { code: 'E2EE_OPEN_FAILED' });
+
+    const ephRaw = buf.subarray(1, 1 + X25519_RAW_LEN);
+    const nonce  = buf.subarray(1 + X25519_RAW_LEN, 1 + X25519_RAW_LEN + GCM_NONCE_LEN);
+    const tag    = buf.subarray(buf.length - GCM_TAG_LEN);
+    const ct     = buf.subarray(1 + X25519_RAW_LEN + GCM_NONCE_LEN, buf.length - GCM_TAG_LEN);
+
+    try
+    {
+        const privKO = Buffer.isBuffer(recipientPrivKey) ? createPrivateKey({ key: recipientPrivKey, format: 'der', type: 'pkcs8' }) : recipientPrivKey;
+        const ephPub = _publicKeyFromRaw(ephRaw);
+        const shared = diffieHellman({ privateKey: privKO, publicKey: ephPub });
+
+        const recPubRaw = _rawFromPublicKey(createPublicKey(privKO));
+        const salt = Buffer.concat([ephRaw, recPubRaw]);
+        const aesKey = Buffer.from(hkdfSync('sha256', shared, salt, HKDF_INFO, 32));
+
+        const decipher = createDecipheriv('aes-256-gcm', aesKey, nonce);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    catch (err)
+    {
+        throw new WebRTCError(`failed to open sealed envelope: ${err.message}`, { code: 'E2EE_OPEN_FAILED' });
+    }
+}
+
+// --- E2eeChannel ---
+
+/**
+ * Per-peer view of the room's E2EE key channel.  Created by
+ * {@link attachE2ee} and parked on `peer.e2ee`.
+ *
+ * Maintains a monotonically increasing `epoch` that callers may either
+ * supply explicitly or let the channel allocate.  Every `publish()` is
+ * relayed by the hub to all other peers in the same room as an opaque
+ * `e2ee-key` frame - the hub never inspects or decrypts the payload.
+ *
+ * @class
+ * @section E2EE
+ */
+class E2eeChannel
+{
+    /**
+     * @constructor
+     * @param {Peer} peer
+     * @param {SignalingHub} hub
+     */
+    constructor(peer, hub)
+    {
+        /** @type {Peer} */
+        this.peer = peer;
+        /** @type {SignalingHub} */
+        this.hub  = hub;
+        /** @type {number} Last published or observed epoch. */
+        this.epoch = 0;
+    }
+
+    /**
+     * Broadcast a sealed key to the rest of the peer's room.
+     *
+     * @param {number|null} epoch - Explicit epoch, or `null` to auto-increment.
+     * @param {Buffer|Uint8Array|string} key - Sealed bytes (or wire-ready string).
+     * @returns {number} The epoch the key was published under.
+     *
+     * @example
+     *   const sealed = sealKey(sframeKey, bob.publicKey);
+     *   const epoch  = peer.e2ee.publish(null, sealed);
+     */
+    publish(epoch, key)
+    {
+        const ep = (typeof epoch === 'number') ? epoch : (this.epoch + 1);
+        if (ep > this.epoch) this.epoch = ep;
+
+        let wire;
+        if (typeof key === 'string') wire = key;
+        else if (Buffer.isBuffer(key)) wire = key.toString('base64');
+        else wire = Buffer.from(key).toString('base64');
+
+        // Route through the hub's authoritative handler so all the usual
+        // validation, broadcast, and observability hooks fire.
+        this.hub._handleE2eeKey(this.peer, { type: 'e2ee-key', epoch: ep, key: wire });
+        return ep;
+    }
+
+    /**
+     * Receive sealed keys published by *other* peers in the same room.
+     *
+     * @param {(ev: {from: string, epoch: number, key: Buffer}) => void} fn
+     * @returns {() => void} Unsubscribe function.
+     *
+     * @example
+     *   peer.e2ee.subscribe(({ from, epoch, key }) => {
+     *       const sframeKey = openSealedKey(key, myPrivKey);
+     *       sframeContext.setKey(epoch, sframeKey);
+     *   });
+     */
+    subscribe(fn)
+    {
+        const listener = (ev) =>
+        {
+            if (!ev || ev.peer === this.peer) return;
+            if (this.peer.room && ev.peer.room !== this.peer.room) return;
+            if (ev.epoch > this.epoch) this.epoch = ev.epoch;
+            const keyBuf = Buffer.isBuffer(ev.key) ? ev.key : Buffer.from(ev.key, 'base64');
+            try { fn({ from: ev.peer.id, epoch: ev.epoch, key: keyBuf }); }
+            catch { /* don't let subscriber errors break the hub */ }
+        };
+        this.hub.on('e2eeKey', listener);
+        return () => this.hub.off('e2eeKey', listener);
+    }
+}
+
+/**
+ * Install an {@link E2eeChannel} on a peer as `peer.e2ee`.  Idempotent: a
+ * second call returns the existing channel.
+ *
+ * @param {Peer} peer
+ * @param {SignalingHub} hub
+ * @returns {E2eeChannel}
+ *
+ * @section E2EE
+ *
+ * @example | Attach E2EE on every join
+ *   hub.on('join', ({ peer }) => attachE2ee(peer, hub));
+ */
+function attachE2ee(peer, hub)
+{
+    if (peer.e2ee instanceof E2eeChannel) return peer.e2ee;
+    peer.e2ee = new E2eeChannel(peer, hub);
+    return peer.e2ee;
+}
+
+module.exports = {
+    ENVELOPE_VERSION,
+    E2eeChannel,
+    attachE2ee,
+    generateE2eeKeyPair,
+    sealKey,
+    openSealedKey,
+};