zero-query 1.1.1 → 1.2.0

package/tests/webrtc/e2ee.test.js

@@ -0,0 +1,283 @@
+/**
+ * tests/webrtc/e2ee.test.js
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+    deriveSFrameKey,
+    generateSFrameKey,
+    SFrameContext,
+    encryptFrame,
+    decryptFrame,
+    attachE2ee,
+    E2eeError,
+} from '../../src/webrtc/index.js';
+
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+
+describe('deriveSFrameKey', () => {
+    it('derives a deterministic key from the same passphrase + salt', async () => {
+        const k1 = await deriveSFrameKey('correct horse battery', 'room-a');
+        const k2 = await deriveSFrameKey('correct horse battery', 'room-a');
+        // CryptoKey identity differs but encrypt/decrypt with one should
+        // decrypt with the other (same underlying material).
+        const ctx1 = new SFrameContext(); ctx1.setKey(0, k1);
+        const ctx2 = new SFrameContext(); ctx2.setKey(0, k2);
+        const enc1 = await encryptFrame(ctx1, enc.encode('hello'));
+        const out  = await decryptFrame(ctx2, enc1);
+        expect(dec.decode(out)).toBe('hello');
+    });
+
+    it('different passphrases produce non-interoperable keys', async () => {
+        const k1 = await deriveSFrameKey('one', 'room-a');
+        const k2 = await deriveSFrameKey('two', 'room-a');
+        const ctx1 = new SFrameContext(); ctx1.setKey(0, k1);
+        const ctx2 = new SFrameContext(); ctx2.setKey(0, k2);
+        const frame = await encryptFrame(ctx1, enc.encode('x'));
+        await expect(decryptFrame(ctx2, frame)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_AUTH_FAILED',
+        });
+    });
+
+    it('different salts produce non-interoperable keys', async () => {
+        const k1 = await deriveSFrameKey('pw', 'room-a');
+        const k2 = await deriveSFrameKey('pw', 'room-b');
+        const ctx1 = new SFrameContext(); ctx1.setKey(0, k1);
+        const ctx2 = new SFrameContext(); ctx2.setKey(0, k2);
+        const frame = await encryptFrame(ctx1, enc.encode('x'));
+        await expect(decryptFrame(ctx2, frame)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_AUTH_FAILED',
+        });
+    });
+
+    it('rejects empty passphrase / salt', async () => {
+        await expect(deriveSFrameKey('', 's')).rejects.toMatchObject({ code: 'ZQ_WEBRTC_E2EE_BAD_PASSPHRASE' });
+        await expect(deriveSFrameKey('p', '')).rejects.toMatchObject({ code: 'ZQ_WEBRTC_E2EE_BAD_SALT' });
+    });
+});
+
+
+describe('SFrameContext', () => {
+    it('rejects invalid epochs', async () => {
+        const ctx = new SFrameContext();
+        const key = await generateSFrameKey();
+        expect(() => ctx.setKey(-1, key)).toThrow(/epoch/);
+        expect(() => ctx.setKey(256, key)).toThrow(/epoch/);
+        expect(() => ctx.setKey(1.5, key)).toThrow(/epoch/);
+    });
+
+    it('rejects setKey without a key', async () => {
+        const ctx = new SFrameContext();
+        expect(() => ctx.setKey(0, null)).toThrow(/key required/);
+    });
+
+    it('tracks current epoch on every setKey', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        expect(ctx.currentEpoch).toBe(0);
+        ctx.setKey(7, await generateSFrameKey());
+        expect(ctx.currentEpoch).toBe(7);
+    });
+
+    it('evicts oldest epoch beyond maxEpochs', async () => {
+        const ctx = new SFrameContext({ maxEpochs: 2 });
+        ctx.setKey(0, await generateSFrameKey());
+        ctx.setKey(1, await generateSFrameKey());
+        ctx.setKey(2, await generateSFrameKey());
+        expect(ctx.epochCount).toBe(2);
+        expect(ctx.getKey(0)).toBeNull();
+        expect(ctx.getKey(1)).not.toBeNull();
+        expect(ctx.getKey(2)).not.toBeNull();
+    });
+
+    it('removeEpoch drops a tracked key', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(3, await generateSFrameKey());
+        expect(ctx.getKey(3)).not.toBeNull();
+        ctx.removeEpoch(3);
+        expect(ctx.getKey(3)).toBeNull();
+    });
+});
+
+
+describe('encryptFrame / decryptFrame', () => {
+    it('round-trips an arbitrary payload', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        const payload = enc.encode('the quick brown fox');
+        const frame   = await encryptFrame(ctx, payload);
+
+        // Header layout: 1-byte epoch + 12-byte IV
+        expect(frame[0]).toBe(0);
+        expect(frame.byteLength).toBe(13 + payload.byteLength + 16);
+
+        const plain = await decryptFrame(ctx, frame);
+        expect(dec.decode(plain)).toBe('the quick brown fox');
+    });
+
+    it('accepts ArrayBuffer payloads', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        const ab    = enc.encode('hi').buffer;
+        const frame = await encryptFrame(ctx, ab);
+        const out   = await decryptFrame(ctx, frame.buffer);
+        expect(dec.decode(out)).toBe('hi');
+    });
+
+    it('writes the current epoch into the frame header', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        ctx.setKey(5, await generateSFrameKey());
+        const frame = await encryptFrame(ctx, enc.encode('x'));
+        expect(frame[0]).toBe(5);
+    });
+
+    it('encryptFrame fails without a key for the current epoch', async () => {
+        const ctx = new SFrameContext();
+        await expect(encryptFrame(ctx, enc.encode('x'))).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_NO_KEY',
+        });
+    });
+
+    it('decryptFrame fails on a too-short frame', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        await expect(decryptFrame(ctx, new Uint8Array(5))).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_SHORT_FRAME',
+        });
+    });
+
+    it('decryptFrame fails when the epoch is unknown', async () => {
+        const enc1 = new SFrameContext();
+        enc1.setKey(2, await generateSFrameKey());
+        const frame = await encryptFrame(enc1, enc.encode('x'));
+
+        const dec1 = new SFrameContext();
+        dec1.setKey(7, await generateSFrameKey());
+        await expect(decryptFrame(dec1, frame)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_UNKNOWN_EPOCH',
+            context: { epoch: 2 },
+        });
+    });
+
+    it('decryptFrame fails when the key is wrong (AES-GCM auth fails)', async () => {
+        const ctx1 = new SFrameContext(); ctx1.setKey(0, await generateSFrameKey());
+        const ctx2 = new SFrameContext(); ctx2.setKey(0, await generateSFrameKey());
+        const frame = await encryptFrame(ctx1, enc.encode('x'));
+        await expect(decryptFrame(ctx2, frame)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_AUTH_FAILED',
+        });
+    });
+
+    it('decryptFrame fails when the ciphertext is tampered with', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        const frame = await encryptFrame(ctx, enc.encode('original'));
+        frame[frame.byteLength - 1] ^= 0x01;
+        await expect(decryptFrame(ctx, frame)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_AUTH_FAILED',
+        });
+    });
+
+    it('throws on non-BufferSource payloads', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+        await expect(encryptFrame(ctx, 'not bytes')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_BAD_INPUT',
+        });
+    });
+
+    it('encrypt/decrypt require an SFrameContext instance', async () => {
+        await expect(encryptFrame({}, new Uint8Array(1))).rejects.toMatchObject({ code: 'ZQ_WEBRTC_E2EE_BAD_CTX' });
+        await expect(decryptFrame({}, new Uint8Array(20))).rejects.toMatchObject({ code: 'ZQ_WEBRTC_E2EE_BAD_CTX' });
+    });
+});
+
+
+describe('epoch rotation', () => {
+    it('decryptor with both epochs decodes frames from either', async () => {
+        const k0 = await generateSFrameKey();
+        const k1 = await generateSFrameKey();
+
+        const enc0 = new SFrameContext(); enc0.setKey(0, k0);
+        const enc1 = new SFrameContext(); enc1.setKey(1, k1);
+
+        const decoder = new SFrameContext();
+        decoder.setKey(0, k0);
+        decoder.setKey(1, k1);
+
+        const f0 = await encryptFrame(enc0, enc.encode('old'));
+        const f1 = await encryptFrame(enc1, enc.encode('new'));
+
+        expect(dec.decode(await decryptFrame(decoder, f0))).toBe('old');
+        expect(dec.decode(await decryptFrame(decoder, f1))).toBe('new');
+    });
+
+    it('after rotation, frames from the evicted epoch fail to decrypt', async () => {
+        const k0 = await generateSFrameKey();
+        const k1 = await generateSFrameKey();
+
+        const sender = new SFrameContext();
+        sender.setKey(0, k0);
+        const stale = await encryptFrame(sender, enc.encode('stale'));
+
+        const receiver = new SFrameContext({ maxEpochs: 1 });
+        receiver.setKey(0, k0);
+        receiver.setKey(1, k1);   // evicts epoch 0
+
+        await expect(decryptFrame(receiver, stale)).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_E2EE_UNKNOWN_EPOCH',
+        });
+    });
+});
+
+
+describe('attachE2ee', () => {
+    it('rejects something that is not an RTCPeerConnection', () => {
+        const ctx = new SFrameContext();
+        expect(() => attachE2ee({}, ctx)).toThrow(/RTCPeerConnection/);
+    });
+
+    it('rejects a non-SFrameContext', () => {
+        const fakePc = { getSenders: () => [], getReceivers: () => [] };
+        expect(() => attachE2ee(fakePc, {})).toThrow(/SFrameContext/);
+    });
+
+    it('returns a refresh/detach handle and walks senders + receivers', async () => {
+        const ctx = new SFrameContext();
+        ctx.setKey(0, await generateSFrameKey());
+
+        const senderCalls   = [];
+        const receiverCalls = [];
+        const fakeSender    = { createEncodedStreams: () => { senderCalls.push(1);   return null; } };
+        const fakeReceiver  = { createEncodedStreams: () => { receiverCalls.push(1); return null; } };
+        const fakePc = {
+            getSenders:   () => [fakeSender],
+            getReceivers: () => [fakeReceiver],
+        };
+
+        const handle = attachE2ee(fakePc, ctx);
+        expect(typeof handle.refresh).toBe('function');
+        expect(typeof handle.detach).toBe('function');
+        expect(senderCalls).toHaveLength(1);
+        expect(receiverCalls).toHaveLength(1);
+
+        // refresh() is idempotent per sender / receiver (WeakSet dedupe).
+        handle.refresh();
+        expect(senderCalls).toHaveLength(1);
+
+        handle.detach();
+    });
+
+    it('survives a sender without createEncodedStreams', () => {
+        const ctx = new SFrameContext();
+        const fakePc = {
+            getSenders:   () => [{}],
+            getReceivers: () => [{}],
+        };
+        expect(() => attachE2ee(fakePc, ctx)).not.toThrow();
+    });
+});

package/tests/webrtc/ice.test.js

@@ -0,0 +1,202 @@
+/**
+ * tests/webrtc/ice.test.js
+ *
+ * Coverage for `src/webrtc/ice.js`: parse, stringify (round-trip),
+ * address classifiers, and `filterCandidates` policy combinations.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+    parseCandidate, stringifyCandidate,
+    isPrivateIp, isLoopbackIp, isLinkLocalIp, isMdnsHostname,
+    filterCandidates, CANDIDATE_TYPES,
+} from '../../src/webrtc/ice.js';
+import { IceError } from '../../src/webrtc/errors.js';
+
+
+describe('ice.parseCandidate', () => {
+    const HOST = 'candidate:842163049 1 udp 1677729535 192.168.1.5 50000 typ host';
+    const SRFLX = 'candidate:1 1 udp 2122194687 1.2.3.4 50001 typ srflx raddr 192.168.1.5 rport 50000';
+    const TCP = 'candidate:2 1 tcp 1518280447 10.0.0.1 9 typ host tcptype active';
+
+    it('parses a simple host candidate', () => {
+        const c = parseCandidate(HOST);
+        expect(c.foundation).toBe('842163049');
+        expect(c.component).toBe(1);
+        expect(c.transport).toBe('udp');
+        expect(c.priority).toBe(1677729535);
+        expect(c.address).toBe('192.168.1.5');
+        expect(c.port).toBe(50000);
+        expect(c.type).toBe('host');
+    });
+
+    it('lifts raddr/rport onto named fields for srflx', () => {
+        const c = parseCandidate(SRFLX);
+        expect(c.type).toBe('srflx');
+        expect(c.relatedAddress).toBe('192.168.1.5');
+        expect(c.relatedPort).toBe(50000);
+    });
+
+    it('lifts tcptype for TCP candidates', () => {
+        const c = parseCandidate(TCP);
+        expect(c.transport).toBe('tcp');
+        expect(c.tcpType).toBe('active');
+    });
+
+    it('accepts the `a=` SDP-attribute prefix', () => {
+        const c = parseCandidate(`a=${HOST}`);
+        expect(c.address).toBe('192.168.1.5');
+    });
+
+    it('captures unknown key/value pairs as extensions', () => {
+        const c = parseCandidate(`${HOST} generation 0 ufrag abcd network-id 1`);
+        expect(c.extensions.generation).toBe('0');
+        expect(c.extensions.ufrag).toBe('abcd');
+        expect(c.extensions['network-id']).toBe('1');
+    });
+
+    it('throws IceError on non-string input', () => {
+        expect(() => parseCandidate(null)).toThrowError(IceError);
+        expect(() => parseCandidate(123)).toThrowError(IceError);
+    });
+
+    it('throws IceError on missing candidate: prefix', () => {
+        expect(() => parseCandidate('842163049 1 udp ...')).toThrowError(IceError);
+    });
+
+    it('throws IceError on bad type keyword or unknown type', () => {
+        expect(() => parseCandidate('candidate:1 1 udp 1 1.2.3.4 1 nope host')).toThrowError(IceError);
+        expect(() => parseCandidate('candidate:1 1 udp 1 1.2.3.4 1 typ moon')).toThrowError(IceError);
+    });
+
+    it('throws IceError on out-of-range port', () => {
+        expect(() => parseCandidate('candidate:1 1 udp 1 1.2.3.4 99999 typ host')).toThrowError(IceError);
+    });
+});
+
+
+describe('ice.stringifyCandidate', () => {
+    it('round-trips parseCandidate output exactly', () => {
+        const line = 'candidate:1 1 udp 2122194687 1.2.3.4 50001 typ srflx raddr 10.0.0.1 rport 50000 generation 0';
+        const reser = stringifyCandidate(parseCandidate(line));
+        // generation lands in extensions; order is preserved.
+        expect(reser).toBe(line);
+    });
+
+    it('throws on missing required fields', () => {
+        expect(() => stringifyCandidate({ foundation: '1' })).toThrowError(IceError);
+        expect(() => stringifyCandidate(null)).toThrowError(IceError);
+    });
+});
+
+
+describe('ice address classifiers', () => {
+    it('isPrivateIp covers RFC 1918 / 6598 / ULA', () => {
+        expect(isPrivateIp('10.0.0.1')).toBe(true);
+        expect(isPrivateIp('172.16.0.1')).toBe(true);
+        expect(isPrivateIp('172.32.0.1')).toBe(false);
+        expect(isPrivateIp('192.168.1.1')).toBe(true);
+        expect(isPrivateIp('100.64.0.1')).toBe(true);
+        expect(isPrivateIp('1.2.3.4')).toBe(false);
+        expect(isPrivateIp('fc00::1')).toBe(true);
+        expect(isPrivateIp('2001:db8::1')).toBe(false);
+    });
+
+    it('isLoopbackIp covers 127.0.0.0/8 and ::1', () => {
+        expect(isLoopbackIp('127.0.0.1')).toBe(true);
+        expect(isLoopbackIp('127.1.2.3')).toBe(true);
+        expect(isLoopbackIp('::1')).toBe(true);
+        expect(isLoopbackIp('1.2.3.4')).toBe(false);
+    });
+
+    it('isLinkLocalIp covers 169.254/16 and fe80::/10', () => {
+        expect(isLinkLocalIp('169.254.1.1')).toBe(true);
+        expect(isLinkLocalIp('169.255.1.1')).toBe(false);
+        expect(isLinkLocalIp('fe80::1')).toBe(true);
+        expect(isLinkLocalIp('fec0::1')).toBe(false);
+    });
+
+    it('isMdnsHostname is strict about hostnames vs IPs', () => {
+        expect(isMdnsHostname('abcd1234.local')).toBe(true);
+        expect(isMdnsHostname('Abcd1234.LOCAL')).toBe(true);
+        expect(isMdnsHostname('1.2.3.4')).toBe(false);
+        expect(isMdnsHostname('fe80::1')).toBe(false);
+        expect(isMdnsHostname('example.com')).toBe(false);
+        expect(isMdnsHostname(null)).toBe(false);
+    });
+});
+
+
+describe('ice.filterCandidates', () => {
+    const lines = [
+        'candidate:1 1 udp 1 1.2.3.4 5000 typ host',                    // public
+        'candidate:2 1 udp 1 10.0.0.1 5000 typ host',                   // private
+        'candidate:3 1 udp 1 abc123.local 5000 typ host',               // mDNS
+        'candidate:4 1 udp 1 5.6.7.8 5000 typ srflx',                   // srflx public
+        'candidate:5 1 tcp 1 5.6.7.8 9 typ host tcptype active',        // TCP
+        'candidate:6 1 udp 1 fe80::1 5000 typ host',                    // IPv6 link-local
+        'garbage',                                                       // unparseable
+    ];
+
+    it('blockMdns drops .local hostnames only', () => {
+        const out = filterCandidates(lines, { blockMdns: true });
+        expect(out.find((l) => l.includes('.local'))).toBeUndefined();
+        expect(out.find((l) => l.includes('1.2.3.4'))).toBeDefined();
+    });
+
+    it('blockPrivate drops RFC 1918 addresses', () => {
+        const out = filterCandidates(lines, { blockPrivate: true });
+        expect(out.find((l) => l.includes('10.0.0.1'))).toBeUndefined();
+    });
+
+    it('blockTcp drops TCP transports', () => {
+        const out = filterCandidates(lines, { blockTcp: true });
+        expect(out.find((l) => l.startsWith('candidate:5 '))).toBeUndefined();
+    });
+
+    it('blockLinkLocal drops fe80:: addresses', () => {
+        const out = filterCandidates(lines, { blockLinkLocal: true });
+        expect(out.find((l) => l.includes('fe80::1'))).toBeUndefined();
+    });
+
+    it('allowedTypes whitelist filters out other types', () => {
+        const out = filterCandidates(lines, { allowedTypes: ['srflx'] });
+        expect(out).toHaveLength(1);
+        expect(out[0]).toContain('typ srflx');
+    });
+
+    it('maxCandidates caps the result', () => {
+        const out = filterCandidates(lines, { maxCandidates: 2 });
+        expect(out).toHaveLength(2);
+    });
+
+    it('predicate hook can drop individual candidates', () => {
+        const out = filterCandidates(lines, { predicate: (c) => c.priority !== 1 || c.address === '1.2.3.4' });
+        expect(out.find((l) => l.includes('1.2.3.4'))).toBeDefined();
+        expect(out.find((l) => l.includes('10.0.0.1'))).toBeUndefined();
+    });
+
+    it('silently skips unparseable lines', () => {
+        const out = filterCandidates(lines);
+        expect(out.includes('garbage')).toBe(false);
+    });
+
+    it('returns parsed objects when input is parsed objects', () => {
+        const parsed = lines.slice(0, 4).map(parseCandidate);
+        const out = filterCandidates(parsed, { blockMdns: true });
+        expect(out.every((c) => typeof c === 'object')).toBe(true);
+    });
+
+    it('returns [] when input is not an array', () => {
+        expect(filterCandidates(null)).toEqual([]);
+        expect(filterCandidates('x')).toEqual([]);
+    });
+});
+
+
+describe('ice module constants', () => {
+    it('exports CANDIDATE_TYPES frozen', () => {
+        expect(CANDIDATE_TYPES).toEqual(['host', 'srflx', 'prflx', 'relay']);
+        expect(Object.isFrozen(CANDIDATE_TYPES)).toBe(true);
+    });
+});

package/tests/webrtc/joinToken.test.js

@@ -0,0 +1,89 @@
+/**
+ * tests/webrtc/joinToken.test.js
+ */
+
+import { describe, it, expect } from 'vitest';
+import { decodeJoinToken, isJoinTokenExpired } from '../../src/webrtc/index.js';
+
+
+function b64urlJson(obj) {
+    const json = JSON.stringify(obj);
+    // base64url-encode in a Node-friendly way
+    const b64 = Buffer.from(json, 'utf8').toString('base64');
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+
+describe('decodeJoinToken', () => {
+    it('decodes a JWT-like 3-segment token', () => {
+        const header  = b64urlJson({ alg: 'HS256', typ: 'JWT' });
+        const payload = b64urlJson({ user: { id: 'u1', name: 'Ada' }, room: 'lobby', exp: 1_700_000_000 });
+        const token   = `${header}.${payload}.signature`;
+        const d       = decodeJoinToken(token);
+        expect(d.user).toEqual({ id: 'u1', name: 'Ada' });
+        expect(d.room).toBe('lobby');
+        expect(d.exp).toBe(1_700_000_000);
+    });
+
+    it('decodes a 2-segment token (payload.sig)', () => {
+        const token = `${b64urlJson({ user: { id: 'u2' }, room: 'r' })}.sig`;
+        expect(decodeJoinToken(token).user).toEqual({ id: 'u2' });
+    });
+
+    it('decodes a 1-segment payload-only token', () => {
+        const token = b64urlJson({ user: { id: 'u3' }, room: 'r' });
+        expect(decodeJoinToken(token).user.id).toBe('u3');
+    });
+
+    it('falls back to `sub` for user id', () => {
+        const token = `${b64urlJson({ sub: 'subject-1', room: 'r' })}.sig`;
+        expect(decodeJoinToken(token).user).toEqual({ id: 'subject-1' });
+    });
+
+    it('returns null user/room/exp when payload lacks them', () => {
+        const d = decodeJoinToken(b64urlJson({ foo: 1 }));
+        expect(d.user).toBeNull();
+        expect(d.room).toBeNull();
+        expect(d.exp).toBeNull();
+        expect(d.raw).toEqual({ foo: 1 });
+    });
+
+    it('rejects empty / non-string input', () => {
+        expect(() => decodeJoinToken('')).toThrow(/non-empty string/);
+        expect(() => decodeJoinToken(null)).toThrow(/non-empty string/);
+    });
+
+    it('rejects malformed shape', () => {
+        expect(() => decodeJoinToken('a.b.c.d')).toMatchObject; // throws below
+        try { decodeJoinToken('a.b.c.d'); throw new Error('want throw'); }
+        catch (err) { expect(err.code).toBe('ZQ_WEBRTC_TOKEN_BAD_SHAPE'); }
+    });
+
+    it('rejects bad base64url payload', () => {
+        try { decodeJoinToken('not!base64.sig'); throw new Error('want throw'); }
+        catch (err) { expect(err.code).toBe('ZQ_WEBRTC_TOKEN_BAD_PAYLOAD'); }
+    });
+});
+
+
+describe('isJoinTokenExpired', () => {
+    it('returns false when exp is missing', () => {
+        expect(isJoinTokenExpired({ exp: null })).toBe(false);
+        expect(isJoinTokenExpired({})).toBe(false);
+    });
+
+    it('returns true when exp is in the past', () => {
+        const expSec = Math.floor(Date.now() / 1000) - 60;
+        expect(isJoinTokenExpired({ exp: expSec })).toBe(true);
+    });
+
+    it('returns false when exp is in the future', () => {
+        const expSec = Math.floor(Date.now() / 1000) + 60;
+        expect(isJoinTokenExpired({ exp: expSec })).toBe(false);
+    });
+
+    it('respects nowMs override', () => {
+        expect(isJoinTokenExpired({ exp: 1000 }, { nowMs: 2_000_000 })).toBe(true);
+        expect(isJoinTokenExpired({ exp: 1000 }, { nowMs: 0 })).toBe(false);
+    });
+});

package/tests/webrtc/observe.test.js

@@ -0,0 +1,111 @@
+/**
+ * tests/webrtc/observe.test.js
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { samplePeerStats, createStatsSampler, classifyStats } from '../../src/webrtc/index.js';
+
+
+function makeReport(entries) {
+    const map = new Map();
+    for (const e of entries) map.set(e.id || e.type, e);
+    return map;
+}
+
+function makePc(report) {
+    return { getStats: vi.fn(async () => report) };
+}
+
+
+describe('samplePeerStats', () => {
+    it('reduces an iterable getStats report to a flat summary', async () => {
+        const pc = makePc(makeReport([
+            { id: 'in1',  type: 'inbound-rtp',    bytesReceived: 1000, packetsReceived: 100, packetsLost: 2 },
+            { id: 'out1', type: 'outbound-rtp',   bytesSent: 5000 },
+            { id: 'cp1',  type: 'candidate-pair', state: 'succeeded', nominated: true, currentRoundTripTime: 0.05 },
+        ]));
+        const s = await samplePeerStats(pc);
+        expect(s.inboundRtp.length).toBe(1);
+        expect(s.outboundRtp.length).toBe(1);
+        expect(s.candidatePair).not.toBeNull();
+        expect(s.summary.bytesSent).toBe(5000);
+        expect(s.summary.bytesReceived).toBe(1000);
+        expect(s.summary.rttMs).toBeCloseTo(50);
+        expect(s.summary.lossPct).toBeCloseTo((2 / 102) * 100);
+    });
+
+    it('handles a plain-object report', async () => {
+        const pc = makePc({
+            in1:  { type: 'inbound-rtp',  bytesReceived: 10, packetsReceived: 1, packetsLost: 0 },
+            out1: { type: 'outbound-rtp', bytesSent: 20 },
+        });
+        const s = await samplePeerStats(pc);
+        expect(s.summary.bytesSent).toBe(20);
+        expect(s.summary.bytesReceived).toBe(10);
+        expect(s.candidatePair).toBeNull();
+    });
+
+    it('rejects a non-RTCPeerConnection', async () => {
+        await expect(samplePeerStats({})).rejects.toMatchObject({ code: 'ZQ_WEBRTC_OBSERVE_BAD_PC' });
+    });
+
+    it('wraps getStats() failures', async () => {
+        const pc = { getStats: async () => { throw new Error('boom'); } };
+        await expect(samplePeerStats(pc)).rejects.toMatchObject({ code: 'ZQ_WEBRTC_OBSERVE_GETSTATS_FAILED' });
+    });
+});
+
+
+describe('classifyStats', () => {
+    it('returns "unknown" for empty samples', () => {
+        expect(classifyStats(null)).toBe('unknown');
+        expect(classifyStats({ summary: { rttMs: null, lossPct: 0 } })).toBe('unknown');
+    });
+
+    it('returns "good" for low rtt/loss', () => {
+        expect(classifyStats({ summary: { rttMs: 50, lossPct: 0.2 } })).toBe('good');
+    });
+
+    it('returns "fair" for moderate rtt/loss', () => {
+        expect(classifyStats({ summary: { rttMs: 250, lossPct: 0.5 } })).toBe('fair');
+        expect(classifyStats({ summary: { rttMs: 50,  lossPct: 2   } })).toBe('fair');
+    });
+
+    it('returns "poor" for high rtt/loss', () => {
+        expect(classifyStats({ summary: { rttMs: 500, lossPct: 0 } })).toBe('poor');
+        expect(classifyStats({ summary: { rttMs: 50,  lossPct: 10 } })).toBe('poor');
+    });
+});
+
+
+describe('createStatsSampler', () => {
+    it('samples immediately and reports via onSample', async () => {
+        const pc = makePc(makeReport([
+            { id: 'in1', type: 'inbound-rtp', bytesReceived: 1, packetsReceived: 1, packetsLost: 0 },
+        ]));
+        const samples = [];
+        const sampler = createStatsSampler(pc, {
+            intervalMs: 10_000,
+            onSample: (s) => samples.push(s),
+        });
+        // Yield so the immediate getStats() resolves.
+        await new Promise((r) => setTimeout(r, 5));
+        sampler.stop();
+        expect(samples.length).toBe(1);
+        expect(sampler.getLatest()).toBe(samples[0]);
+    });
+
+    it('forwards getStats() failures to onError', async () => {
+        const pc = { getStats: async () => { throw new Error('nope'); } };
+        const errs = [];
+        const sampler = createStatsSampler(pc, { intervalMs: 10_000, onError: (e) => errs.push(e) });
+        await new Promise((r) => setTimeout(r, 5));
+        sampler.stop();
+        expect(errs.length).toBe(1);
+        expect(errs[0].code).toBe('ZQ_WEBRTC_OBSERVE_GETSTATS_FAILED');
+    });
+
+    it('rejects a non-RTCPeerConnection', () => {
+        expect(() => createStatsSampler({})).toThrow(/RTCPeerConnection required/);
+    });
+});