@livedesk/hub 0.1.13 → 0.1.14

package/src/transport/relay-hub-control.js

@@ -0,0 +1,1004 @@
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import net from 'node:net';
+
+export const RELAY_CONTROL_PROTOCOL = 'livedesk.relay.v1';
+export const RELAY_CONTROL_MAX_PLAINTEXT_BYTES = 512 * 1024;
+export const RELAY_CONTROL_DIRECTIONS = Object.freeze({
+    clientToHub: 'client-to-hub',
+    hubToClient: 'hub-to-client'
+});
+
+const RELAY_MAX_LINE_BYTES = 768 * 1024;
+const RELAY_NONCE_BYTES = 12;
+const RELAY_TAG_BYTES = 16;
+const RELAY_PUBLIC_KEY_BYTES = 65;
+const RELAY_PEER_ID_BYTES = 16;
+const DEFAULT_MAX_PEERS = 128;
+const DEFAULT_MAX_QUEUE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_QUEUE_MESSAGES = 256;
+const DEFAULT_MAX_PEER_QUEUE_BYTES = 1024 * 1024;
+const DEFAULT_MAX_PEER_QUEUE_MESSAGES = 64;
+const DEFAULT_RECONNECT_MIN_MS = 1_000;
+const DEFAULT_RECONNECT_MAX_MS = 30_000;
+
+function isEnabled(value, fallback = false) {
+    if (value === undefined || value === null || value === '') return fallback;
+    return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+function safeText(value, maximum = 160) {
+    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maximum);
+}
+
+function boundedInteger(value, minimum, maximum, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number)
+        ? Math.max(minimum, Math.min(maximum, Math.floor(number)))
+        : fallback;
+}
+
+function encodeBase64Url(value) {
+    return Buffer.from(value).toString('base64url');
+}
+
+function decodeCanonicalBase64Url(value, expectedBytes = 0, maximumBytes = 1024) {
+    const text = String(value || '');
+    if (!text || !/^[A-Za-z0-9_-]+$/.test(text)) {
+        throw relayError('relay-invalid-base64url');
+    }
+    const decoded = Buffer.from(text, 'base64url');
+    if (decoded.length > maximumBytes
+        || (expectedBytes > 0 && decoded.length !== expectedBytes)
+        || encodeBase64Url(decoded) !== text) {
+        throw relayError('relay-invalid-base64url');
+    }
+    return decoded;
+}
+
+function relayError(code) {
+    const error = new Error(code);
+    error.code = code;
+    return error;
+}
+
+function requirePairToken(pairToken) {
+    const token = String(pairToken || '');
+    if (!token || Buffer.byteLength(token, 'utf8') > 1024) {
+        throw relayError('relay-pair-token-required');
+    }
+    return token;
+}
+
+function requireRoomId(roomId) {
+    const value = String(roomId || '');
+    if (!value || value.length > 128 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw relayError('relay-room-invalid');
+    }
+    return value;
+}
+
+function requirePeerId(peerId) {
+    const value = String(peerId || '');
+    decodeCanonicalBase64Url(value, RELAY_PEER_ID_BYTES, RELAY_PEER_ID_BYTES);
+    return value;
+}
+
+function requirePublicKey(publicKey) {
+    const value = String(publicKey || '');
+    const decoded = decodeCanonicalBase64Url(value, RELAY_PUBLIC_KEY_BYTES, RELAY_PUBLIC_KEY_BYTES);
+    if (decoded[0] !== 0x04) {
+        throw relayError('relay-public-key-invalid');
+    }
+    return { text: value, bytes: decoded };
+}
+
+function requireDirection(direction) {
+    const value = String(direction || '');
+    if (value !== RELAY_CONTROL_DIRECTIONS.clientToHub
+        && value !== RELAY_CONTROL_DIRECTIONS.hubToClient) {
+        throw relayError('relay-direction-invalid');
+    }
+    return value;
+}
+
+function requireSequence(sequence) {
+    const value = Number(sequence);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw relayError('relay-sequence-invalid');
+    }
+    return value;
+}
+
+function normalizeSessionKey(sessionKey) {
+    const key = Buffer.from(sessionKey || []);
+    if (key.length !== 32) {
+        throw relayError('relay-session-key-invalid');
+    }
+    return key;
+}
+
+function proofMatches(actual, expected) {
+    let actualBytes;
+    try {
+        actualBytes = decodeCanonicalBase64Url(actual, 32, 32);
+    } catch {
+        return false;
+    }
+    const expectedBytes = decodeCanonicalBase64Url(expected, 32, 32);
+    return crypto.timingSafeEqual(actualBytes, expectedBytes);
+}
+
+function controlAad(roomId, peerId, direction, sequence) {
+    return Buffer.from(
+        `livedesk-relay-data-v1\0${requireRoomId(roomId)}\0${requirePeerId(peerId)}\0${requireDirection(direction)}\0${requireSequence(sequence)}`,
+        'utf8');
+}
+
+function sanitizeSocketError(error) {
+    const code = safeText(error?.code, 80);
+    return code && /^[A-Z0-9_]+$/.test(code) ? code : 'relay-socket-error';
+}
+
+export function deriveRelayRoomId(pairToken) {
+    const token = requirePairToken(pairToken);
+    return crypto
+        .createHash('sha256')
+        .update(Buffer.from(`livedesk-relay-room-v1\0${token}`, 'utf8'))
+        .digest('base64url');
+}
+
+export function deriveRelayRegistrationToken(pairToken, roomId = deriveRelayRoomId(pairToken)) {
+    const token = requirePairToken(pairToken);
+    const room = requireRoomId(roomId);
+    return crypto
+        .createHmac('sha256', Buffer.from(token, 'utf8'))
+        .update(Buffer.from(`livedesk-relay-register-v1\0${room}`, 'utf8'))
+        .digest('base64url');
+}
+
+export function deriveRelayClientProof(pairToken, {
+    roomId = deriveRelayRoomId(pairToken),
+    peerId,
+    clientPublicKey
+} = {}) {
+    const token = requirePairToken(pairToken);
+    const room = requireRoomId(roomId);
+    const peer = requirePeerId(peerId);
+    const clientKey = requirePublicKey(clientPublicKey).text;
+    return crypto
+        .createHmac('sha256', Buffer.from(token, 'utf8'))
+        .update(Buffer.from(`livedesk-relay-client-v1\0${room}\0${peer}\0${clientKey}`, 'utf8'))
+        .digest('base64url');
+}
+
+export function deriveRelayHubProof(pairToken, {
+    roomId = deriveRelayRoomId(pairToken),
+    peerId,
+    clientPublicKey,
+    hubPublicKey
+} = {}) {
+    const token = requirePairToken(pairToken);
+    const room = requireRoomId(roomId);
+    const peer = requirePeerId(peerId);
+    const clientKey = requirePublicKey(clientPublicKey).text;
+    const hubKey = requirePublicKey(hubPublicKey).text;
+    return crypto
+        .createHmac('sha256', Buffer.from(token, 'utf8'))
+        .update(Buffer.from(`livedesk-relay-hub-v1\0${room}\0${peer}\0${clientKey}\0${hubKey}`, 'utf8'))
+        .digest('base64url');
+}
+
+export function deriveRelaySessionKey(pairToken, {
+    roomId = deriveRelayRoomId(pairToken),
+    peerId,
+    clientPublicKey,
+    hubPublicKey,
+    sharedSecret
+} = {}) {
+    const token = requirePairToken(pairToken);
+    const room = requireRoomId(roomId);
+    const peer = requirePeerId(peerId);
+    const clientKey = requirePublicKey(clientPublicKey).text;
+    const hubKey = requirePublicKey(hubPublicKey).text;
+    const secret = Buffer.from(sharedSecret || []);
+    if (secret.length < 16 || secret.length > 256) {
+        throw relayError('relay-shared-secret-invalid');
+    }
+    const salt = crypto
+        .createHmac('sha256', Buffer.from(token, 'utf8'))
+        .update(Buffer.from(`livedesk-relay-salt-v1\0${room}\0${peer}`, 'utf8'))
+        .digest();
+    const info = Buffer.from(`livedesk-relay-e2e-v1\0${clientKey}\0${hubKey}`, 'utf8');
+    return Buffer.from(crypto.hkdfSync('sha256', secret, salt, info, 32));
+}
+
+export function encryptRelayControlPayload({
+    sessionKey,
+    roomId,
+    peerId,
+    direction,
+    sequence,
+    plaintext,
+    nonce = crypto.randomBytes(RELAY_NONCE_BYTES)
+} = {}) {
+    const key = normalizeSessionKey(sessionKey);
+    const cleartext = Buffer.from(plaintext || []);
+    if (cleartext.length < 1 || cleartext.length > RELAY_CONTROL_MAX_PLAINTEXT_BYTES) {
+        throw relayError('relay-plaintext-size-invalid');
+    }
+    const nonceBytes = Buffer.from(nonce || []);
+    if (nonceBytes.length !== RELAY_NONCE_BYTES) {
+        throw relayError('relay-nonce-invalid');
+    }
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, nonceBytes, { authTagLength: RELAY_TAG_BYTES });
+    cipher.setAAD(controlAad(roomId, peerId, direction, sequence));
+    const ciphertext = Buffer.concat([cipher.update(cleartext), cipher.final()]);
+    return encodeBase64Url(Buffer.concat([nonceBytes, ciphertext, cipher.getAuthTag()]));
+}
+
+export function decryptRelayControlPayload({
+    sessionKey,
+    roomId,
+    peerId,
+    direction,
+    sequence,
+    payload
+} = {}) {
+    const key = normalizeSessionKey(sessionKey);
+    let envelope;
+    try {
+        envelope = decodeCanonicalBase64Url(
+            payload,
+            0,
+            RELAY_NONCE_BYTES + RELAY_CONTROL_MAX_PLAINTEXT_BYTES + RELAY_TAG_BYTES);
+    } catch {
+        throw relayError('relay-data-invalid');
+    }
+    if (envelope.length <= RELAY_NONCE_BYTES + RELAY_TAG_BYTES) {
+        throw relayError('relay-data-invalid');
+    }
+    const nonce = envelope.subarray(0, RELAY_NONCE_BYTES);
+    const ciphertext = envelope.subarray(RELAY_NONCE_BYTES, envelope.length - RELAY_TAG_BYTES);
+    const tag = envelope.subarray(envelope.length - RELAY_TAG_BYTES);
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce, { authTagLength: RELAY_TAG_BYTES });
+        decipher.setAAD(controlAad(roomId, peerId, direction, sequence));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        if (plaintext.length < 1 || plaintext.length > RELAY_CONTROL_MAX_PLAINTEXT_BYTES) {
+            throw relayError('relay-plaintext-size-invalid');
+        }
+        return plaintext;
+    } catch (error) {
+        if (error?.code === 'relay-plaintext-size-invalid') throw error;
+        throw relayError('relay-data-authentication-failed');
+    }
+}
+
+export class HubRelayVirtualSocket extends EventEmitter {
+    constructor(owner, peerId, remoteAddress, remotePort) {
+        super();
+        this.owner = owner;
+        this.peerId = peerId;
+        this.remoteAddress = remoteAddress;
+        this.remotePort = remotePort;
+        this.destroyed = false;
+        this.connecting = false;
+        this.readable = true;
+        this.writable = true;
+        this.__liveDeskRelayControl = true;
+        this.__liveDeskRelayPeerId = peerId;
+    }
+
+    setNoDelay() {
+        return this;
+    }
+
+    setKeepAlive() {
+        return this;
+    }
+
+    address() {
+        return {
+            address: this.remoteAddress,
+            family: 'relay',
+            port: this.remotePort
+        };
+    }
+
+    write(chunk, encoding, callback) {
+        let completion = callback;
+        let textEncoding = encoding;
+        if (typeof encoding === 'function') {
+            completion = encoding;
+            textEncoding = undefined;
+        }
+        if (this.destroyed) {
+            if (typeof completion === 'function') {
+                queueMicrotask(() => completion(relayError('relay-virtual-socket-closed')));
+            }
+            return false;
+        }
+        const payload = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(String(chunk ?? ''), typeof textEncoding === 'string' ? textEncoding : 'utf8');
+        const accepted = this.owner.sendPeerPlaintext(this.peerId, payload);
+        if (typeof completion === 'function') {
+            queueMicrotask(() => completion(accepted ? undefined : relayError('relay-write-rejected')));
+        }
+        return accepted && !this.owner.isPeerBackpressured(this.peerId);
+    }
+
+    end(chunk, encoding, callback) {
+        if (chunk !== undefined && chunk !== null && typeof chunk !== 'function') {
+            this.write(chunk, typeof encoding === 'string' ? encoding : undefined);
+        }
+        const completion = typeof chunk === 'function'
+            ? chunk
+            : typeof encoding === 'function'
+                ? encoding
+                : callback;
+        this.destroy();
+        if (typeof completion === 'function') queueMicrotask(completion);
+        return this;
+    }
+
+    destroy(error) {
+        if (!this.destroyed) {
+            this.owner.closePeer(this.peerId, 'virtual-socket-destroyed', {
+                notify: true,
+                error: error instanceof Error ? error : null
+            });
+        }
+        return this;
+    }
+
+    _deliver(plaintext) {
+        if (!this.destroyed) this.emit('data', Buffer.from(plaintext));
+    }
+
+    _drain() {
+        if (!this.destroyed) this.emit('drain');
+    }
+
+    _close(reason, error = null) {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.readable = false;
+        this.writable = false;
+        this.closeReason = safeText(reason, 120) || 'relay-peer-closed';
+        if (error && this.listenerCount('error') > 0) this.emit('error', error);
+        this.emit('close', error ? true : false);
+    }
+}
+
+export function createHubRelayControl({
+    env = process.env,
+    pairToken,
+    onPeerSocket = () => {},
+    logEvent = () => {},
+    logWarn = () => {},
+    connect = options => net.createConnection(options),
+    randomBytes = size => crypto.randomBytes(size)
+} = {}) {
+    const token = requirePairToken(pairToken);
+    const roomId = deriveRelayRoomId(token);
+    const registrationToken = deriveRelayRegistrationToken(token, roomId);
+    const enabled = isEnabled(
+        env.LIVEDESK_RELAY_ENABLED,
+        isEnabled(env.LIVEDESK_UDP_ENABLED, true));
+    const host = safeText(
+        env.LIVEDESK_RELAY_HOST
+            || env.LIVEDESK_UDP_RENDEZVOUS_HOST
+            || 'www.gnsoftech.com',
+        253);
+    const port = boundedInteger(
+        env.LIVEDESK_RELAY_PORT || env.LIVEDESK_UDP_RENDEZVOUS_PORT,
+        1,
+        65535,
+        5199);
+    const maxPeers = boundedInteger(env.LIVEDESK_RELAY_MAX_PEERS, 1, 1024, DEFAULT_MAX_PEERS);
+    const maxQueueBytes = boundedInteger(
+        env.LIVEDESK_RELAY_MAX_QUEUE_BYTES,
+        RELAY_MAX_LINE_BYTES,
+        32 * 1024 * 1024,
+        DEFAULT_MAX_QUEUE_BYTES);
+    const maxQueueMessages = boundedInteger(
+        env.LIVEDESK_RELAY_MAX_QUEUE_MESSAGES,
+        1,
+        4096,
+        DEFAULT_MAX_QUEUE_MESSAGES);
+    const maxPeerQueueBytes = boundedInteger(
+        env.LIVEDESK_RELAY_MAX_PEER_QUEUE_BYTES,
+        RELAY_MAX_LINE_BYTES,
+        8 * 1024 * 1024,
+        DEFAULT_MAX_PEER_QUEUE_BYTES);
+    const maxPeerQueueMessages = boundedInteger(
+        env.LIVEDESK_RELAY_MAX_PEER_QUEUE_MESSAGES,
+        1,
+        512,
+        DEFAULT_MAX_PEER_QUEUE_MESSAGES);
+    const reconnectMinMs = boundedInteger(
+        env.LIVEDESK_RELAY_RECONNECT_MIN_MS,
+        50,
+        60_000,
+        DEFAULT_RECONNECT_MIN_MS);
+    const reconnectMaxMs = boundedInteger(
+        env.LIVEDESK_RELAY_RECONNECT_MAX_MS,
+        reconnectMinMs,
+        5 * 60_000,
+        DEFAULT_RECONNECT_MAX_MS);
+    const peers = new Map();
+    const retiredPeerIds = new Map();
+    const sendQueue = [];
+    const peerQueueStats = new Map();
+    const counters = {
+        connections: 0,
+        reconnects: 0,
+        handshakes: 0,
+        rejectedPeers: 0,
+        encryptedMessagesReceived: 0,
+        encryptedMessagesSent: 0,
+        queueDrops: 0
+    };
+
+    let desired = false;
+    let started = false;
+    let closing = false;
+    let connection = null;
+    let connectionGeneration = 0;
+    let reconnectTimer = null;
+    let reconnectAttempt = 0;
+    let receiveBuffer = Buffer.alloc(0);
+    let queuedBytes = 0;
+    let awaitingDrain = false;
+    let lastError = '';
+    let lastConnectedAt = '';
+    let lastTransitionAt = '';
+    let state = enabled ? 'idle' : 'disabled';
+
+    function transition(nextState, error = '') {
+        state = nextState;
+        lastTransitionAt = new Date().toISOString();
+        if (error) lastError = safeText(error, 120);
+    }
+
+    function queueStats(peerId) {
+        if (!peerId) return { messages: 0, bytes: 0, backpressured: false };
+        let stats = peerQueueStats.get(peerId);
+        if (!stats) {
+            stats = { messages: 0, bytes: 0, backpressured: false };
+            peerQueueStats.set(peerId, stats);
+        }
+        return stats;
+    }
+
+    function releaseQueuedItem(item) {
+        queuedBytes = Math.max(0, queuedBytes - item.buffer.length);
+        if (!item.peerId) return;
+        const stats = queueStats(item.peerId);
+        stats.messages = Math.max(0, stats.messages - 1);
+        stats.bytes = Math.max(0, stats.bytes - item.buffer.length);
+    }
+
+    function clearQueue() {
+        sendQueue.length = 0;
+        queuedBytes = 0;
+        awaitingDrain = false;
+        peerQueueStats.clear();
+    }
+
+    function emitPeerDrains() {
+        if (awaitingDrain) return;
+        for (const [peerId, stats] of peerQueueStats) {
+            if (!stats.backpressured
+                || stats.messages >= maxPeerQueueMessages
+                || stats.bytes >= maxPeerQueueBytes) {
+                continue;
+            }
+            stats.backpressured = false;
+            peers.get(peerId)?.socket?._drain();
+        }
+    }
+
+    function flushQueue() {
+        const socket = connection;
+        if (!socket || socket.destroyed || !socket.writable || awaitingDrain) return;
+        while (sendQueue.length > 0 && !awaitingDrain) {
+            const item = sendQueue.shift();
+            releaseQueuedItem(item);
+            let writable = false;
+            try {
+                writable = socket.write(item.buffer);
+            } catch {
+                socket.destroy();
+                return;
+            }
+            if (!writable) awaitingDrain = true;
+        }
+        emitPeerDrains();
+    }
+
+    function enqueueEnvelope(envelope, peerId = '') {
+        if (!connection || connection.destroyed || !connection.writable) return false;
+        let buffer;
+        try {
+            buffer = Buffer.from(`${JSON.stringify(envelope)}\n`, 'utf8');
+        } catch {
+            return false;
+        }
+        if (buffer.length > RELAY_MAX_LINE_BYTES) return false;
+        const stats = queueStats(peerId);
+        if (sendQueue.length >= maxQueueMessages
+            || queuedBytes + buffer.length > maxQueueBytes
+            || (peerId && (stats.messages >= maxPeerQueueMessages
+                || stats.bytes + buffer.length > maxPeerQueueBytes))) {
+            counters.queueDrops += 1;
+            if (peerId) stats.backpressured = true;
+            return false;
+        }
+        sendQueue.push({ buffer, peerId });
+        queuedBytes += buffer.length;
+        if (peerId) {
+            stats.messages += 1;
+            stats.bytes += buffer.length;
+        }
+        flushQueue();
+        if (peerId && awaitingDrain) stats.backpressured = true;
+        return true;
+    }
+
+    function rememberRetiredPeer(peerId) {
+        if (!peerId) return;
+        retiredPeerIds.delete(peerId);
+        retiredPeerIds.set(peerId, Date.now());
+        while (retiredPeerIds.size > maxPeers * 4) {
+            retiredPeerIds.delete(retiredPeerIds.keys().next().value);
+        }
+    }
+
+    function sendRelayClose(peerId, reason) {
+        if (!connection || connection.destroyed) return false;
+        return enqueueEnvelope({
+            type: 'relay.close',
+            protocol: RELAY_CONTROL_PROTOCOL,
+            roomId,
+            peerId,
+            reason: safeText(reason, 80) || 'relay-peer-closed'
+        }, peerId);
+    }
+
+    function closePeer(peerId, reason = 'relay-peer-closed', {
+        notify = true,
+        error = null
+    } = {}) {
+        const id = safeText(peerId, 64);
+        const peer = peers.get(id);
+        if (!peer) {
+            if (notify) {
+                try {
+                    sendRelayClose(requirePeerId(id), reason);
+                } catch {
+                    // Invalid untrusted routing fields are ignored.
+                }
+            }
+            return false;
+        }
+        peers.delete(id);
+        rememberRetiredPeer(id);
+        peerQueueStats.delete(id);
+        if (notify) sendRelayClose(id, reason);
+        if (Buffer.isBuffer(peer.sessionKey)) peer.sessionKey.fill(0);
+        peer.socket?._close(reason, error);
+        return true;
+    }
+
+    function rejectPeer(peerId, reason) {
+        counters.rejectedPeers += 1;
+        closePeer(peerId, reason, { notify: true });
+    }
+
+    function closeAllPeers(reason) {
+        for (const peerId of [...peers.keys()]) {
+            closePeer(peerId, reason, { notify: false });
+        }
+    }
+
+    function isPeerBackpressured(peerId) {
+        return peerQueueStats.get(String(peerId || ''))?.backpressured === true;
+    }
+
+    function sendPeerPlaintext(peerId, plaintext) {
+        const peer = peers.get(String(peerId || ''));
+        if (!peer || peer.socket.destroyed || peer.handshakeState !== 'established') return false;
+        const cleartext = Buffer.from(plaintext || []);
+        if (cleartext.length < 1 || cleartext.length > RELAY_CONTROL_MAX_PLAINTEXT_BYTES) {
+            rejectPeer(peer.peerId, 'relay-plaintext-size-invalid');
+            return false;
+        }
+        const sequence = peer.sendSequence + 1;
+        let payload;
+        try {
+            payload = encryptRelayControlPayload({
+                sessionKey: peer.sessionKey,
+                roomId,
+                peerId: peer.peerId,
+                direction: RELAY_CONTROL_DIRECTIONS.hubToClient,
+                sequence,
+                plaintext: cleartext,
+                nonce: randomBytes(RELAY_NONCE_BYTES)
+            });
+        } catch {
+            rejectPeer(peer.peerId, 'relay-encryption-failed');
+            return false;
+        }
+        const accepted = enqueueEnvelope({
+            type: 'relay.data',
+            protocol: RELAY_CONTROL_PROTOCOL,
+            roomId,
+            peerId: peer.peerId,
+            direction: RELAY_CONTROL_DIRECTIONS.hubToClient,
+            sequence,
+            payload
+        }, peer.peerId);
+        if (!accepted) {
+            counters.queueDrops += 1;
+            closePeer(peer.peerId, 'relay-backpressure-limit', { notify: false });
+            return false;
+        }
+        peer.sendSequence = sequence;
+        peer.lastActivityAt = Date.now();
+        counters.encryptedMessagesSent += 1;
+        return true;
+    }
+
+    function handleClientHandshake(message) {
+        let peerId = '';
+        try {
+            peerId = requirePeerId(message.peerId);
+            if (message.direction
+                && requireDirection(message.direction) !== RELAY_CONTROL_DIRECTIONS.clientToHub) {
+                throw relayError('relay-direction-invalid');
+            }
+            const stage = safeText(message.stage || message.handshake, 40).toLowerCase();
+            if (stage && stage !== 'client-hello') {
+                throw relayError('relay-handshake-stage-invalid');
+            }
+            if (peers.has(peerId) || retiredPeerIds.has(peerId)) {
+                throw relayError('relay-handshake-replay');
+            }
+            if (peers.size >= maxPeers) {
+                throw relayError('relay-peer-capacity');
+            }
+            const clientPublic = requirePublicKey(message.clientPublicKey);
+            const expectedProof = deriveRelayClientProof(token, {
+                roomId,
+                peerId,
+                clientPublicKey: clientPublic.text
+            });
+            if (!proofMatches(message.proof, expectedProof)) {
+                throw relayError('relay-client-proof-invalid');
+            }
+            const ecdh = crypto.createECDH('prime256v1');
+            ecdh.generateKeys();
+            const hubPublicKey = ecdh.getPublicKey(null, 'uncompressed').toString('base64url');
+            const sharedSecret = ecdh.computeSecret(clientPublic.bytes);
+            let sessionKey;
+            try {
+                sessionKey = deriveRelaySessionKey(token, {
+                    roomId,
+                    peerId,
+                    clientPublicKey: clientPublic.text,
+                    hubPublicKey,
+                    sharedSecret
+                });
+            } finally {
+                sharedSecret.fill(0);
+            }
+            const proof = deriveRelayHubProof(token, {
+                roomId,
+                peerId,
+                clientPublicKey: clientPublic.text,
+                hubPublicKey
+            });
+            const remoteAddress = `relay://${host}:${port}/${peerId}`;
+            const peer = {
+                peerId,
+                clientPublicKey: clientPublic.text,
+                hubPublicKey,
+                sessionKey,
+                receiveSequence: 0,
+                sendSequence: 0,
+                handshakeState: 'established',
+                createdAt: Date.now(),
+                lastActivityAt: Date.now(),
+                socket: null
+            };
+            peer.socket = new HubRelayVirtualSocket(api, peerId, remoteAddress, port);
+            peers.set(peerId, peer);
+            const sent = enqueueEnvelope({
+                type: 'relay.handshake',
+                protocol: RELAY_CONTROL_PROTOCOL,
+                roomId,
+                peerId,
+                direction: RELAY_CONTROL_DIRECTIONS.hubToClient,
+                stage: 'hub-hello',
+                clientPublicKey: clientPublic.text,
+                hubPublicKey,
+                proof
+            }, peerId);
+            if (!sent) {
+                closePeer(peerId, 'relay-handshake-backpressure', { notify: false });
+                return;
+            }
+            try {
+                onPeerSocket(peer.socket, {
+                    protocol: RELAY_CONTROL_PROTOCOL,
+                    peerId,
+                    endpoint: `${host}:${port}`
+                });
+            } catch {
+                closePeer(peerId, 'relay-peer-handler-failed', { notify: true });
+                return;
+            }
+            counters.handshakes += 1;
+        } catch (error) {
+            counters.rejectedPeers += 1;
+            if (peerId) {
+                rememberRetiredPeer(peerId);
+                sendRelayClose(peerId, safeText(error?.code, 80) || 'relay-handshake-rejected');
+            }
+        }
+    }
+
+    function handleClientData(message) {
+        let peerId = '';
+        try {
+            peerId = requirePeerId(message.peerId);
+            const peer = peers.get(peerId);
+            if (!peer || peer.handshakeState !== 'established') {
+                throw relayError('relay-handshake-required');
+            }
+            if (requireDirection(message.direction) !== RELAY_CONTROL_DIRECTIONS.clientToHub) {
+                throw relayError('relay-direction-invalid');
+            }
+            const sequence = requireSequence(message.sequence);
+            if (sequence !== peer.receiveSequence + 1) {
+                throw relayError('relay-sequence-invalid');
+            }
+            const plaintext = decryptRelayControlPayload({
+                sessionKey: peer.sessionKey,
+                roomId,
+                peerId,
+                direction: RELAY_CONTROL_DIRECTIONS.clientToHub,
+                sequence,
+                payload: message.payload
+            });
+            peer.receiveSequence = sequence;
+            peer.lastActivityAt = Date.now();
+            counters.encryptedMessagesReceived += 1;
+            peer.socket._deliver(plaintext);
+        } catch (error) {
+            if (peerId) rejectPeer(peerId, safeText(error?.code, 80) || 'relay-data-rejected');
+        }
+    }
+
+    function handleRelayEnvelope(message) {
+        if (!message || typeof message !== 'object' || Array.isArray(message)) return;
+        const peerId = safeText(message.peerId, 64);
+        if (message.protocol !== RELAY_CONTROL_PROTOCOL || message.roomId !== roomId) {
+            if (peerId) rejectPeer(peerId, 'relay-routing-mismatch');
+            return;
+        }
+        if (message.type === 'relay.handshake') {
+            handleClientHandshake(message);
+            return;
+        }
+        if (message.type === 'relay.data') {
+            handleClientData(message);
+            return;
+        }
+        if (message.type === 'relay.close') {
+            try {
+                closePeer(requirePeerId(message.peerId), 'relay-client-closed', { notify: false });
+            } catch {
+                // Invalid untrusted routing fields are ignored.
+            }
+        }
+    }
+
+    function onConnectionData(chunk) {
+        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        receiveBuffer = receiveBuffer.length > 0
+            ? Buffer.concat([receiveBuffer, incoming])
+            : incoming;
+        while (true) {
+            const newline = receiveBuffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (receiveBuffer.length > RELAY_MAX_LINE_BYTES) {
+                    lastError = 'relay-line-too-large';
+                    connection?.destroy();
+                }
+                return;
+            }
+            if (newline > RELAY_MAX_LINE_BYTES) {
+                lastError = 'relay-line-too-large';
+                connection?.destroy();
+                return;
+            }
+            const line = receiveBuffer.subarray(0, newline);
+            receiveBuffer = receiveBuffer.subarray(newline + 1);
+            if (line.length === 0) continue;
+            let message;
+            try {
+                message = JSON.parse(line.toString('utf8'));
+            } catch {
+                lastError = 'relay-invalid-json';
+                connection?.destroy();
+                return;
+            }
+            handleRelayEnvelope(message);
+        }
+    }
+
+    function scheduleReconnect() {
+        if (!desired || closing || reconnectTimer) return;
+        reconnectAttempt += 1;
+        counters.reconnects += 1;
+        const exponential = Math.min(
+            reconnectMaxMs,
+            reconnectMinMs * (2 ** Math.min(10, reconnectAttempt - 1)));
+        const jitter = Math.floor(exponential * 0.2 * Math.random());
+        const delay = Math.min(reconnectMaxMs, exponential + jitter);
+        transition('reconnect-wait');
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            connectNow();
+        }, delay);
+        reconnectTimer.unref?.();
+    }
+
+    function handleConnectionClosed(socket, generation) {
+        if (connection !== socket || generation !== connectionGeneration) return;
+        connection = null;
+        receiveBuffer = Buffer.alloc(0);
+        clearQueue();
+        closeAllPeers('relay-connection-lost');
+        if (desired && !closing) scheduleReconnect();
+        else transition(enabled ? 'idle' : 'disabled');
+    }
+
+    function connectNow() {
+        if (!enabled || !desired || closing || connection) return;
+        transition('connecting');
+        const generation = ++connectionGeneration;
+        let socket;
+        try {
+            socket = connect({ host, port });
+        } catch (error) {
+            lastError = sanitizeSocketError(error);
+            scheduleReconnect();
+            return;
+        }
+        connection = socket;
+        socket.setNoDelay?.(true);
+        socket.setKeepAlive?.(true, 10_000);
+        socket.once('connect', () => {
+            if (connection !== socket || generation !== connectionGeneration || !desired) return;
+            counters.connections += 1;
+            reconnectAttempt = 0;
+            lastConnectedAt = new Date().toISOString();
+            lastError = '';
+            transition('registered');
+            const registered = enqueueEnvelope({
+                type: 'relay.register',
+                protocol: RELAY_CONTROL_PROTOCOL,
+                roomId,
+                role: 'hub',
+                peerId: '',
+                token: registrationToken
+            });
+            if (!registered) socket.destroy();
+            else logEvent('relay', `Encrypted relay control registered at ${host}:${port}`);
+        });
+        socket.on('data', onConnectionData);
+        socket.on('drain', () => {
+            if (connection !== socket || generation !== connectionGeneration) return;
+            awaitingDrain = false;
+            flushQueue();
+        });
+        socket.once('error', error => {
+            if (connection !== socket || generation !== connectionGeneration) return;
+            lastError = sanitizeSocketError(error);
+            logWarn('relay', `Encrypted relay control connection failed code=${lastError}`);
+        });
+        socket.once('close', () => handleConnectionClosed(socket, generation));
+    }
+
+    async function start() {
+        if (!enabled || started) return getStatus();
+        started = true;
+        desired = true;
+        closing = false;
+        connectNow();
+        return getStatus();
+    }
+
+    async function close() {
+        desired = false;
+        started = false;
+        closing = true;
+        if (reconnectTimer) clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+        closeAllPeers('hub-shutdown');
+        clearQueue();
+        const socket = connection;
+        connection = null;
+        connectionGeneration += 1;
+        receiveBuffer = Buffer.alloc(0);
+        if (socket && !socket.destroyed) {
+            await new Promise(resolve => {
+                let settled = false;
+                const settle = () => {
+                    if (settled) return;
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve();
+                };
+                const timer = setTimeout(() => {
+                    socket.destroy();
+                    settle();
+                }, 250);
+                timer.unref?.();
+                socket.once('close', settle);
+                try {
+                    socket.end();
+                } catch {
+                    socket.destroy();
+                    settle();
+                }
+            });
+        }
+        closing = false;
+        transition(enabled ? 'idle' : 'disabled');
+    }
+
+    function getStatus() {
+        return {
+            enabled,
+            started,
+            state,
+            connected: !!connection && !connection.destroyed && state === 'registered',
+            protocol: RELAY_CONTROL_PROTOCOL,
+            endpoint: `${host}:${port}`,
+            host,
+            port,
+            peerCount: peers.size,
+            queuedMessages: sendQueue.length,
+            queuedBytes,
+            maxPeers,
+            maxQueueMessages,
+            maxQueueBytes,
+            reconnectCount: counters.reconnects,
+            handshakeCount: counters.handshakes,
+            rejectedPeerCount: counters.rejectedPeers,
+            encryptedMessagesReceived: counters.encryptedMessagesReceived,
+            encryptedMessagesSent: counters.encryptedMessagesSent,
+            queueDropCount: counters.queueDrops,
+            lastConnectedAt,
+            lastTransitionAt,
+            lastError
+        };
+    }
+
+    const api = {
+        start,
+        close,
+        getStatus,
+        sendPeerPlaintext,
+        closePeer,
+        isPeerBackpressured
+    };
+    return api;
+}