@livedesk/hub 0.1.36 → 0.1.38

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

@@ -1,1703 +1,1376 @@
-import crypto from 'node:crypto';
-import { EventEmitter } from 'node:events';
-import net from 'node:net';
-import {
-    SECURE_SESSION_MAX_CLOCK_SKEW_MS,
-    SECURE_SESSION_PROTOCOL,
-    deriveSecureSessionKey,
-    enrollmentProof,
-    fixedTimeBase64UrlEqual,
-    normalizeSecureChannel,
-    secureClientTranscript,
-    secureServerTranscript
-} from '@livedesk/runtime-core';
-
-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_MAX_RECEIVE_CHUNKS = 256;
-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;
-const DEFAULT_CONNECT_TIMEOUT_MS = 5_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.isBuffer(value) ? value : 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.isBuffer(sessionKey)
-        ? sessionKey
-        : 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 deriveCredentialRelayRoomId(hubId, hubPublicKey) {
-    const id = safeText(hubId, 128);
-    const key = decodeCanonicalBase64Url(hubPublicKey, 0, 160).toString('base64url');
-    if (!id) throw relayError('relay-hub-id-required');
-    return crypto.createHash('sha256')
-        .update(Buffer.from(`livedesk-relay-credential-room-v1\0${id}\0${key}`, 'utf8'))
-        .digest('base64url');
-}
-
-export function deriveCredentialRelayRegistrationToken(hubId, hubPublicKey) {
-    const roomId = deriveCredentialRelayRoomId(hubId, hubPublicKey);
-    return crypto.createHash('sha256')
-        .update(Buffer.from(`livedesk-relay-credential-register-v1\0${roomId}\0${hubPublicKey}`, 'utf8'))
-        .digest('base64url');
-}
-
-function requireP256SpkiPublicKey(value) {
-    const der = decodeCanonicalBase64Url(value, 0, 160);
-    if (der.length < 80) throw relayError('relay-public-key-invalid');
-    let key;
-    try {
-        key = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
-    } catch {
-        throw relayError('relay-public-key-invalid');
-    }
-    if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
-        throw relayError('relay-public-key-invalid');
-    }
-    return { key, text: der.toString('base64url') };
-}
-
-function verifyP256Signature(publicKey, message, signature) {
-    const bytes = decodeCanonicalBase64Url(signature, 64, 64);
-    if (!crypto.verify('sha256', Buffer.from(String(message || ''), 'utf8'), {
-        key: publicKey,
-        dsaEncoding: 'ieee-p1363'
-    }, bytes)) {
-        throw relayError('device-signature-invalid');
-    }
-}
-
-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.isBuffer(plaintext)
-        ? plaintext
-        : Buffer.from(plaintext || []);
-    if (cleartext.length < 1 || cleartext.length > RELAY_CONTROL_MAX_PLAINTEXT_BYTES) {
-        throw relayError('relay-plaintext-size-invalid');
-    }
-    const nonceBytes = Buffer.isBuffer(nonce)
-        ? nonce
-        : 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 update = cipher.update(cleartext);
-    const final = cipher.final();
-    const ciphertext = final.length > 0
-        ? Buffer.concat([update, final], update.length + final.length)
-        : update;
-    const tag = cipher.getAuthTag();
-    const envelope = Buffer.allocUnsafe(nonceBytes.length + ciphertext.length + tag.length);
-    nonceBytes.copy(envelope, 0);
-    ciphertext.copy(envelope, nonceBytes.length);
-    tag.copy(envelope, nonceBytes.length + ciphertext.length);
-    return encodeBase64Url(envelope);
-}
-
-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 update = decipher.update(ciphertext);
-        const final = decipher.final();
-        const plaintext = final.length > 0
-            ? Buffer.concat([update, final], update.length + final.length)
-            : update;
-        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) return;
-        if (Buffer.isBuffer(plaintext)) {
-            this.emit('data', plaintext);
-            return;
-        }
-        this.owner.recordPlaintextDeliveryCopy();
-        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,
-    secureSession = null,
-    onPeerSocket = () => {},
-    logEvent = () => {},
-    logWarn = () => {},
-    connect = options => net.createConnection(options),
-    randomBytes = size => crypto.randomBytes(size)
-} = {}) {
-    const secureMode = secureSession?.mode === 'credential'
-        ? 'credential'
-        : secureSession?.mode === 'enroll'
-            ? 'enroll'
-            : '';
-    const authority = secureMode ? secureSession?.authority : null;
-    if (secureMode && (!authority?.verifyCredential || !authority?.issueCredential || !authority?.signHubMessage)) {
-        throw relayError('relay-device-authority-required');
-    }
-    const token = secureMode === 'credential'
-        ? authority.hubPublicKey
-        : requirePairToken(pairToken);
-    const roomId = secureMode === 'credential'
-        ? deriveCredentialRelayRoomId(authority.hubId, authority.hubPublicKey)
-        : deriveRelayRoomId(token);
-    const registrationToken = secureMode === 'credential'
-        ? deriveCredentialRelayRegistrationToken(authority.hubId, authority.hubPublicKey)
-        : 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 connectTimeoutMs = boundedInteger(
-        env.LIVEDESK_RELAY_CONNECT_TIMEOUT_MS,
-        250,
-        30_000,
-        DEFAULT_CONNECT_TIMEOUT_MS);
-    const peers = new Map();
-    const retiredPeerIds = new Map();
-    const connectionOwners = new Map();
-    const sendQueue = [];
-    let sendQueueHead = 0;
-    const peerQueueStats = new Map();
-    const counters = {
-        connections: 0,
-        reconnects: 0,
-        handshakes: 0,
-        rejectedPeers: 0,
-        encryptedMessagesReceived: 0,
-        encryptedMessagesSent: 0,
-        queueDrops: 0,
-        receiveLineAssemblyCopies: 0,
-        receiveLineAssemblyBytes: 0,
-        plaintextDeliveryCopies: 0,
-        peerQueuePurges: 0,
-        peerQueuePurgedBytes: 0,
-        staleConnectionEventDrops: 0,
-        socketOwnersCreated: 0,
-        socketOwnersClosed: 0,
-        peerOwnersCreated: 0,
-        peerOwnersClosed: 0
-    };
-
-    let desired = false;
-    let started = false;
-    let closing = false;
-    let connection = null;
-    let connectionGeneration = 0;
-    let reconnectTimer = null;
-    let connectAttemptTimer = null;
-    let closeSocketTimer = null;
-    let closeTimedOut = false;
-    let reconnectAttempt = 0;
-    let receiveChunks = [];
-    let receiveBytes = 0;
-    let receiveChunkHighWater = 0;
-    let receiveByteHighWater = 0;
-    let queuedBytes = 0;
-    let queuedMessageHighWater = 0;
-    let queuedByteHighWater = 0;
-    let socketWritableByteHighWater = 0;
-    let totalOutboundByteHighWater = 0;
-    let socketOwnerHighWater = 0;
-    let peerOwnerHighWater = 0;
-    let timerOwnerHighWater = 0;
-    let awaitingDrain = false;
-    let lastError = '';
-    let lastDisconnectReason = '';
-    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 activeTimerCount() {
-        return Number(Boolean(reconnectTimer))
-            + Number(Boolean(connectAttemptTimer))
-            + Number(Boolean(closeSocketTimer));
-    }
-
-    function recordTimerOwnerHighWater() {
-        timerOwnerHighWater = Math.max(
-            timerOwnerHighWater,
-            activeTimerCount());
-    }
-
-    function addConnectionOwner(socket, generation) {
-        if (connectionOwners.has(socket)) {
-            throw relayError('relay-socket-owner-duplicate');
-        }
-        connectionOwners.set(socket, {
-            socket,
-            generation,
-            phase: 'current'
-        });
-        counters.socketOwnersCreated += 1;
-        socketOwnerHighWater = Math.max(
-            socketOwnerHighWater,
-            connectionOwners.size);
-    }
-
-    function markConnectionOwnerClosing(socket, generation) {
-        const owner = connectionOwners.get(socket);
-        if (!owner || owner.generation !== generation) return false;
-        owner.phase = 'closing';
-        return true;
-    }
-
-    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 = peerQueueStats.get(item.peerId);
-        if (!stats) return;
-        stats.messages = Math.max(0, stats.messages - 1);
-        stats.bytes = Math.max(0, stats.bytes - item.buffer.length);
-    }
-
-    function queuedMessageCount() {
-        return sendQueue.length - sendQueueHead;
-    }
-
-    function socketWritableBytes(socket = connection) {
-        const value = Number(socket?.writableLength);
-        return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
-    }
-
-    function recordOutboundHighWater(socket = connection) {
-        const writableBytes = socketWritableBytes(socket);
-        socketWritableByteHighWater = Math.max(
-            socketWritableByteHighWater,
-            writableBytes);
-        totalOutboundByteHighWater = Math.max(
-            totalOutboundByteHighWater,
-            queuedBytes + writableBytes);
-    }
-
-    function dequeueQueuedItem() {
-        if (queuedMessageCount() <= 0) return null;
-        const item = sendQueue[sendQueueHead];
-        sendQueue[sendQueueHead] = null;
-        sendQueueHead += 1;
-        if (sendQueueHead >= 64 && sendQueueHead * 2 >= sendQueue.length) {
-            sendQueue.splice(0, sendQueueHead);
-            sendQueueHead = 0;
-        }
-        return item;
-    }
-
-    function clearQueue() {
-        sendQueue.length = 0;
-        sendQueueHead = 0;
-        queuedBytes = 0;
-        awaitingDrain = false;
-        peerQueueStats.clear();
-    }
-
-    function purgePeerQueue(peerId) {
-        if (!peerId || queuedMessageCount() === 0) return;
-        let writeIndex = 0;
-        let purgedBytes = 0;
-        for (let readIndex = sendQueueHead; readIndex < sendQueue.length; readIndex += 1) {
-            const item = sendQueue[readIndex];
-            if (item.peerId === peerId) {
-                purgedBytes += item.buffer.length;
-                releaseQueuedItem(item);
-                continue;
-            }
-            sendQueue[writeIndex] = item;
-            writeIndex += 1;
-        }
-        for (let index = writeIndex; index < sendQueue.length; index += 1) {
-            sendQueue[index] = null;
-        }
-        if (purgedBytes > 0) {
-            sendQueue.length = writeIndex;
-            sendQueueHead = 0;
-            counters.peerQueuePurges += 1;
-            counters.peerQueuePurgedBytes += purgedBytes;
-        } else if (sendQueueHead > 0) {
-            sendQueue.splice(0, sendQueueHead);
-            sendQueueHead = 0;
-        }
-    }
-
-    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 (queuedMessageCount() > 0 && !awaitingDrain) {
-            const item = dequeueQueuedItem();
-            if (!item) break;
-            releaseQueuedItem(item);
-            let writable = false;
-            try {
-                writable = socket.write(item.buffer);
-            } catch {
-                socket.destroy();
-                return;
-            }
-            if (!writable) awaitingDrain = true;
-            recordOutboundHighWater(socket);
-        }
-        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);
-        const writableBytes = socketWritableBytes();
-        if (queuedMessageCount() >= maxQueueMessages
-            || queuedBytes + writableBytes + 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;
-        queuedMessageHighWater = Math.max(queuedMessageHighWater, queuedMessageCount());
-        queuedByteHighWater = Math.max(queuedByteHighWater, queuedBytes);
-        recordOutboundHighWater();
-        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'
-        });
-    }
-
-    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);
-        counters.peerOwnersClosed += 1;
-        rememberRetiredPeer(id);
-        purgePeerQueue(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.isBuffer(plaintext)
-            ? plaintext
-            : 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) {
-        if (secureMode) {
-            handleSecureClientHandshake(message);
-            return;
-        }
-        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);
-            counters.peerOwnersCreated += 1;
-            peerOwnerHighWater = Math.max(peerOwnerHighWater, peers.size);
-            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 handleSecureClientHandshake(message) {
-        let peerId = '';
-        try {
-            peerId = requirePeerId(message.peerId);
-            if (message.direction && requireDirection(message.direction) !== RELAY_CONTROL_DIRECTIONS.clientToHub) {
-                throw relayError('relay-direction-invalid');
-            }
-            if (safeText(message.stage, 40).toLowerCase() !== 'client-hello') throw relayError('relay-secure-stage-invalid');
-            if (message.securityProtocol !== SECURE_SESSION_PROTOCOL) {
-                lastError = `relay-secure-protocol:${safeText(message.securityProtocol, 80) || 'missing'}`;
-                throw relayError(message.securityProtocol === undefined
-                    ? 'relay-secure-protocol-missing'
-                    : 'relay-secure-protocol-invalid');
-            }
-            if (peers.has(peerId) || retiredPeerIds.has(peerId)) throw relayError('relay-handshake-replay');
-            if (peers.size >= maxPeers) throw relayError('relay-peer-capacity');
-            const expectedMode = secureMode === 'credential' ? 'resume' : 'enroll';
-            if (message.mode !== expectedMode) throw relayError('relay-secure-mode-invalid');
-            const current = Date.now();
-            const timestamp = Number(message.timestamp);
-            if (!Number.isSafeInteger(timestamp) || Math.abs(current - timestamp) > SECURE_SESSION_MAX_CLOCK_SKEW_MS) {
-                throw relayError('secure-handshake-timestamp-invalid');
-            }
-            const channel = normalizeSecureChannel(message.channel);
-            const deviceId = safeText(message.deviceId, 128);
-            if (!deviceId) throw relayError('device-id-required');
-            const devicePublic = requireP256SpkiPublicKey(message.devicePublicKey);
-            const clientEphemeral = requireP256SpkiPublicKey(message.clientEphemeralPublicKey);
-            const clientTranscript = secureClientTranscript(message);
-            const identity = secureSession.getIdentity?.() || {};
-            const accountId = safeText(identity.accountId, 128);
-            if (!accountId) throw relayError('secure-account-session-required');
-
-            let issued;
-            let enrollmentSecret = '';
-            if (expectedMode === 'enroll') {
-                enrollmentSecret = String(secureSession.getEnrollmentToken?.() || token);
-                if (!fixedTimeBase64UrlEqual(message.enrollmentProof, enrollmentProof(enrollmentSecret, clientTranscript), 32)) {
-                    throw relayError('secure-enrollment-proof-invalid');
-                }
-                verifyP256Signature(devicePublic.key, clientTranscript, message.deviceSignature);
-                authority.assertEnrollmentAllowed?.({ accountId, deviceId, devicePublicKey: devicePublic.text });
-                if (!secureSession.consumeEnrollmentToken?.(enrollmentSecret)) throw relayError('secure-enrollment-token-used');
-                issued = authority.issueCredential({ accountId, deviceId, devicePublicKey: devicePublic.text });
-            } else {
-                const verified = authority.verifyCredential(message.credential, { accountId, deviceId });
-                if (verified.payload.devicePublicKey !== devicePublic.text) throw relayError('device-credential-binding-invalid');
-                authority.verifyDeviceSignature(verified, clientTranscript, message.deviceSignature);
-                issued = { credential: verified.text, payload: verified.payload };
-            }
-
-            const { privateKey: serverPrivate, publicKey: serverPublic } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
-            const response = {
-                type: 'relay.handshake',
-                protocol: RELAY_CONTROL_PROTOCOL,
-                roomId,
-                peerId,
-                direction: RELAY_CONTROL_DIRECTIONS.hubToClient,
-                stage: 'hub-hello',
-                securityProtocol: SECURE_SESSION_PROTOCOL,
-                sessionId: crypto.randomBytes(16).toString('base64url'),
-                channel,
-                timestamp: current,
-                serverNonce: crypto.randomBytes(16).toString('base64url'),
-                serverEphemeralPublicKey: serverPublic.export({ format: 'der', type: 'spki' }).toString('base64url'),
-                credential: issued.credential,
-                hubId: authority.hubId,
-                accountId,
-                deviceId
-            };
-            const serverTranscript = secureServerTranscript(response, clientTranscript);
-            response.hubSignature = authority.signHubMessage(serverTranscript);
-            if (expectedMode === 'enroll') response.enrollmentServerProof = enrollmentProof(enrollmentSecret, serverTranscript);
-            const sharedSecret = crypto.diffieHellman({ privateKey: serverPrivate, publicKey: clientEphemeral.key });
-            let sessionKey;
-            try {
-                sessionKey = deriveSecureSessionKey({
-                    sharedSecret,
-                    clientTranscript,
-                    serverTranscript,
-                    sessionId: response.sessionId,
-                    channel
-                });
-            } finally {
-                sharedSecret.fill(0);
-            }
-            const remoteAddress = `relay://${host}:${port}/${peerId}`;
-            const peer = {
-                peerId,
-                sessionKey,
-                receiveSequence: 0,
-                sendSequence: 0,
-                handshakeState: 'established',
-                createdAt: current,
-                lastActivityAt: current,
-                socket: null
-            };
-            peer.socket = new HubRelayVirtualSocket(api, peerId, remoteAddress, port);
-            peer.socket.__liveDeskSecurityContext = Object.freeze({
-                protocol: SECURE_SESSION_PROTOCOL,
-                accountId,
-                hubId: authority.hubId,
-                deviceId,
-                channel,
-                credentialSerial: issued.payload.serial,
-                authenticated: true,
-                encrypted: true,
-                transport: 'relay'
-            });
-            peers.set(peerId, peer);
-            counters.peerOwnersCreated += 1;
-            peerOwnerHighWater = Math.max(peerOwnerHighWater, peers.size);
-            if (!enqueueEnvelope(response, peerId)) {
-                closePeer(peerId, 'relay-handshake-backpressure', { notify: false });
-                return;
-            }
-            onPeerSocket(peer.socket, {
-                protocol: RELAY_CONTROL_PROTOCOL,
-                securityProtocol: SECURE_SESSION_PROTOCOL,
-                peerId,
-                endpoint: `${host}:${port}`,
-                accountId,
-                hubId: authority.hubId,
-                deviceId,
-                channel
-            });
-            authority.markConnected(deviceId);
-            counters.handshakes += 1;
-        } catch (error) {
-            counters.rejectedPeers += 1;
-            if (peerId) {
-                rememberRetiredPeer(peerId);
-                sendRelayClose(peerId, safeText(error?.code || error?.message, 80) || 'relay-handshake-rejected');
-            }
-        }
-    }
-
-    function handleClientData(message) {
-        let peerId = '';
-        try {
-            peerId = safeText(message.peerId, 64);
-            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;
-        if (message.type === 'relay.registered') {
-            if (message.protocol !== RELAY_CONTROL_PROTOCOL
-                || message.roomId !== roomId
-                || message.role !== 'hub'
-                || safeText(message.peerId, 64) !== ''
-                || state !== 'registering') {
-                lastError = 'relay-registration-invalid';
-                connection?.destroy();
-                return;
-            }
-            clearConnectAttemptTimer();
-            reconnectAttempt = 0;
-            lastConnectedAt = new Date().toISOString();
-            lastError = '';
-            transition('registered');
-            logEvent('relay', `Encrypted relay control registered at ${host}:${port}`);
-            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') {
-            const reason = safeText(message.reason, 80) || 'relay-server-closed';
-            if (!peerId) {
-                lastError = reason;
-                lastDisconnectReason = reason;
-                connection?.destroy();
-                return;
-            }
-            try {
-                closePeer(requirePeerId(message.peerId), reason, { notify: false });
-            } catch {
-                // Invalid untrusted routing fields are ignored.
-            }
-        }
-    }
-
-    function clearReceiveChunks() {
-        receiveChunks = [];
-        receiveBytes = 0;
-    }
-
-    function retainReceiveTail(incoming, offset) {
-        const tail = incoming.subarray(offset);
-        if (tail.length === 0) return true;
-        if (receiveBytes + tail.length > RELAY_MAX_LINE_BYTES) return false;
-        // A tail following a complete line must not retain the complete large
-        // TCP chunk. A chunk containing no line is already exact ownership and
-        // can be retained without copying.
-        const retained = offset > 0 ? Buffer.from(tail) : tail;
-        if (receiveChunks.length >= RELAY_MAX_RECEIVE_CHUNKS) return false;
-        receiveChunks.push(retained);
-        receiveBytes += retained.length;
-        receiveChunkHighWater = Math.max(receiveChunkHighWater, receiveChunks.length);
-        receiveByteHighWater = Math.max(receiveByteHighWater, receiveBytes);
-        return true;
-    }
-
-    function assembleReceiveLine(segment) {
-        if (receiveBytes === 0) return segment;
-        const totalBytes = receiveBytes + segment.length;
-        const line = Buffer.allocUnsafe(totalBytes);
-        let offset = 0;
-        for (const chunk of receiveChunks) {
-            chunk.copy(line, offset);
-            offset += chunk.length;
-        }
-        segment.copy(line, offset);
-        counters.receiveLineAssemblyCopies += 1;
-        counters.receiveLineAssemblyBytes += totalBytes;
-        clearReceiveChunks();
-        return line;
-    }
-
-    function isCurrentConnectionOwner(socket, generation) {
-        return desired
-            && !closing
-            && connection === socket
-            && generation === connectionGeneration
-            && !socket.destroyed;
-    }
-
-    function processRelayLine(socket, generation, line) {
-        if (!isCurrentConnectionOwner(socket, generation)) {
-            counters.staleConnectionEventDrops += 1;
-            return false;
-        }
-        if (line.length === 0) return true;
-        let message;
-        try {
-            message = JSON.parse(line.toString('utf8'));
-        } catch {
-            lastError = 'relay-invalid-json';
-            socket.destroy();
-            return false;
-        }
-        if (!isCurrentConnectionOwner(socket, generation)) {
-            counters.staleConnectionEventDrops += 1;
-            return false;
-        }
-        handleRelayEnvelope(message);
-        return true;
-    }
-
-    function onConnectionData(socket, generation, chunk) {
-        if (!isCurrentConnectionOwner(socket, generation)) {
-            counters.staleConnectionEventDrops += 1;
-            return;
-        }
-        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        let offset = 0;
-        while (offset < incoming.length) {
-            if (!isCurrentConnectionOwner(socket, generation)) {
-                counters.staleConnectionEventDrops += 1;
-                return;
-            }
-            const newline = incoming.indexOf(0x0a, offset);
-            if (newline < 0) {
-                if (!retainReceiveTail(incoming, offset)) {
-                    lastError = 'relay-line-too-large';
-                    socket.destroy();
-                }
-                return;
-            }
-            const segmentLength = newline - offset;
-            if (receiveBytes + segmentLength > RELAY_MAX_LINE_BYTES) {
-                lastError = 'relay-line-too-large';
-                socket.destroy();
-                return;
-            }
-            const line = assembleReceiveLine(incoming.subarray(offset, newline));
-            if (!processRelayLine(socket, generation, line)) return;
-            offset = newline + 1;
-        }
-    }
-
-    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?.();
-        recordTimerOwnerHighWater();
-    }
-
-    function clearConnectAttemptTimer() {
-        if (connectAttemptTimer) clearTimeout(connectAttemptTimer);
-        connectAttemptTimer = null;
-    }
-
-    function handleConnectionClosed(socket, generation) {
-        const owner = connectionOwners.get(socket);
-        if (!owner || owner.generation !== generation) return;
-        connectionOwners.delete(socket);
-        counters.socketOwnersClosed += 1;
-        if (owner.phase === 'closing') return;
-        if (connection !== socket || generation !== connectionGeneration) return;
-        clearConnectAttemptTimer();
-        connection = null;
-        const disconnectReason = safeText(lastError, 120) || 'relay-socket-closed';
-        lastDisconnectReason = disconnectReason;
-        logWarn(
-            'relay',
-            `Encrypted relay control disconnected reason=${disconnectReason} peers=${peers.size}`
-        );
-        clearReceiveChunks();
-        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;
-        addConnectionOwner(socket, generation);
-        socket.setNoDelay?.(true);
-        socket.setKeepAlive?.(true, 10_000);
-        socket.once('connect', () => {
-            if (connection !== socket || generation !== connectionGeneration || !desired) return;
-            counters.connections += 1;
-            transition('registering');
-            const registered = enqueueEnvelope({
-                type: 'relay.register',
-                protocol: RELAY_CONTROL_PROTOCOL,
-                roomId,
-                role: 'hub',
-                peerId: '',
-                ack: true,
-                token: registrationToken
-            });
-            if (!registered) socket.destroy();
-        });
-        socket.on('data', chunk => onConnectionData(socket, generation, chunk));
-        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));
-        connectAttemptTimer = setTimeout(() => {
-            if (connection !== socket
-                || generation !== connectionGeneration
-                || socket.destroyed
-                || (state !== 'connecting' && state !== 'registering')) return;
-            lastError = 'relay-connect-timeout';
-            logWarn('relay', `Encrypted relay control connection failed code=${lastError}`);
-            socket.destroy();
-        }, connectTimeoutMs);
-        connectAttemptTimer.unref?.();
-        recordTimerOwnerHighWater();
-    }
-
-    async function start() {
-        if (!enabled || started) return getStatus();
-        if (closing || closeTimedOut || connectionOwners.size > 0) {
-            throw relayError('relay-close-nonterminal');
-        }
-        started = true;
-        desired = true;
-        closing = false;
-        connectNow();
-        return getStatus();
-    }
-
-    async function close() {
-        const closeDeadlineAt = Date.now() + 1_000;
-        desired = false;
-        started = false;
-        closing = true;
-        closeTimedOut = false;
-        transition('closing');
-        if (reconnectTimer) clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-        clearConnectAttemptTimer();
-        closeAllPeers('hub-shutdown');
-        clearQueue();
-        const socket = connection;
-        const generation = connectionGeneration;
-        if (socket) markConnectionOwnerClosing(socket, generation);
-        connection = null;
-        connectionGeneration += 1;
-        clearReceiveChunks();
-        const closingOwners = [...connectionOwners.values()];
-        if (closingOwners.length > 0) {
-            const ownersClosed = new Promise((resolve, reject) => {
-                let settled = false;
-                const onClose = () => {
-                    if (connectionOwners.size === 0) settle();
-                };
-                const settle = () => {
-                    if (settled) return;
-                    settled = true;
-                    if (closeSocketTimer) clearTimeout(closeSocketTimer);
-                    closeSocketTimer = null;
-                    for (const owner of closingOwners) {
-                        owner.socket.off?.('close', onClose);
-                    }
-                    resolve();
-                };
-                const fail = () => {
-                    if (settled) return;
-                    settled = true;
-                    closeSocketTimer = null;
-                    for (const owner of closingOwners) {
-                        owner.socket.off?.('close', onClose);
-                    }
-                    reject(relayError('relay-close-timeout'));
-                };
-                for (const owner of closingOwners) {
-                    owner.phase = 'closing';
-                    owner.socket.once('close', onClose);
-                }
-                closeSocketTimer = setTimeout(() => {
-                    fail();
-                }, Math.max(1, closeDeadlineAt - Date.now()));
-                recordTimerOwnerHighWater();
-                if (connectionOwners.size === 0) settle();
-            });
-            for (const owner of closingOwners) {
-                try {
-                    owner.socket.end();
-                } catch {
-                    // The exact owner remains in the ledger until close.
-                }
-                try {
-                    owner.socket.destroy();
-                } catch {
-                    // Timeout remains explicit and nonterminal.
-                }
-            }
-            try {
-                await ownersClosed;
-            } catch (error) {
-                closeTimedOut = true;
-                lastError = 'relay-close-timeout';
-                transition('close-timeout', lastError);
-                throw error;
-            }
-        }
-        if (connectionOwners.size !== 0) {
-            closeTimedOut = true;
-            lastError = 'relay-close-nonterminal';
-            transition('close-timeout', lastError);
-            throw relayError(lastError);
-        }
-        closeTimedOut = false;
-        closing = false;
-        lastError = '';
-        transition(enabled ? 'idle' : 'disabled');
-    }
-
-    function getStatus() {
-        const writableBytes = socketWritableBytes();
-        recordOutboundHighWater();
-        return {
-            enabled,
-            started,
-            state,
-            connected: !!connection && !connection.destroyed && state === 'registered',
-            closing,
-            closeTimedOut,
-            activeSocketCount: connectionOwners.size,
-            currentSocketCount: connection && connectionOwners.has(connection) ? 1 : 0,
-            closingSocketCount: [...connectionOwners.values()]
-                .filter(owner => owner.phase === 'closing').length,
-            activeTimerCount: activeTimerCount(),
-            timerOwnerHighWater,
-            socketOwnerHighWater,
-            socketOwnersCreated: counters.socketOwnersCreated,
-            socketOwnersClosed: counters.socketOwnersClosed,
-            protocol: RELAY_CONTROL_PROTOCOL,
-            endpoint: `${host}:${port}`,
-            host,
-            port,
-            peerCount: peers.size,
-            peerOwnerHighWater,
-            peerOwnersCreated: counters.peerOwnersCreated,
-            peerOwnersClosed: counters.peerOwnersClosed,
-            peerQueueCount: peerQueueStats.size,
-            queuedMessages: queuedMessageCount(),
-            queuedBytes,
-            socketWritableBytes: writableBytes,
-            totalOutboundBufferedBytes: queuedBytes + writableBytes,
-            queuedMessageHighWater,
-            queuedByteHighWater,
-            socketWritableByteHighWater,
-            totalOutboundByteHighWater,
-            receiveBufferedChunks: receiveChunks.length,
-            receiveBufferedBytes: receiveBytes,
-            receiveChunkHighWater,
-            receiveByteHighWater,
-            receiveLineAssemblyCopyCount: counters.receiveLineAssemblyCopies,
-            receiveLineAssemblyBytes: counters.receiveLineAssemblyBytes,
-            plaintextDeliveryCopyCount: counters.plaintextDeliveryCopies,
-            peerQueuePurgeCount: counters.peerQueuePurges,
-            peerQueuePurgedBytes: counters.peerQueuePurgedBytes,
-            staleConnectionEventDropCount: counters.staleConnectionEventDrops,
-            maxPeers,
-            maxQueueMessages,
-            maxQueueBytes,
-            reconnectCount: counters.reconnects,
-            handshakeCount: counters.handshakes,
-            rejectedPeerCount: counters.rejectedPeers,
-            encryptedMessagesReceived: counters.encryptedMessagesReceived,
-            encryptedMessagesSent: counters.encryptedMessagesSent,
-            queueDropCount: counters.queueDrops,
-            lastConnectedAt,
-            lastTransitionAt,
-            lastDisconnectReason,
-            lastError
-        };
-    }
-
-    function recordPlaintextDeliveryCopy() {
-        counters.plaintextDeliveryCopies += 1;
-    }
-
-    const api = {
-        start,
-        close,
-        getStatus,
-        sendPeerPlaintext,
-        closePeer,
-        isPeerBackpressured,
-        recordPlaintextDeliveryCopy
-    };
-    return api;
-}
-
-export function createSecureHubRelayControl({
-    env = process.env,
-    authority,
-    getIdentity = () => ({}),
-    getEnrollmentToken = () => '',
-    consumeEnrollmentToken = () => false,
-    onPeerSocket = () => {},
-    logEvent = () => {},
-    logWarn = () => {}
-} = {}) {
-    if (!authority?.hubId || !authority?.hubPublicKey) throw relayError('relay-device-authority-required');
-    let started = false;
-    let closed = false;
-    let enrollment = null;
-    const retired = new Set();
-    const retirementTimers = new Set();
-    const stable = createHubRelayControl({
-        env,
-        pairToken: authority.hubPublicKey,
-        secureSession: { mode: 'credential', authority, getIdentity },
-        onPeerSocket,
-        logEvent,
-        logWarn
-    });
-
-    function makeEnrollmentControl(token) {
-        return createHubRelayControl({
-            env,
-            pairToken: token,
-            secureSession: {
-                mode: 'enroll',
-                authority,
-                getIdentity,
-                getEnrollmentToken: () => token,
-                consumeEnrollmentToken: expected => {
-                    if (expected !== token || !consumeEnrollmentToken(expected)) return false;
-                    queueMicrotask(() => { void rotateEnrollment(); });
-                    return true;
-                }
-            },
-            onPeerSocket,
-            logEvent,
-            logWarn
-        });
-    }
-
-    function retireControl(control) {
-        if (!control) return;
-        retired.add(control);
-        const deadline = Date.now() + 10_000;
-        const poll = () => {
-            if (closed || control.getStatus().peerCount === 0 || Date.now() >= deadline) {
-                retired.delete(control);
-                void control.close().catch(error => logWarn('relay', `Secure enrollment relay retirement failed code=${safeText(error?.code, 80) || 'unknown'}`));
-                return;
-            }
-            const timer = setTimeout(() => {
-                retirementTimers.delete(timer);
-                poll();
-            }, 100);
-            timer.unref?.();
-            retirementTimers.add(timer);
-        };
-        poll();
-    }
-
-    async function rotateEnrollment() {
-        if (closed) return;
-        const previous = enrollment;
-        enrollment = makeEnrollmentControl(getEnrollmentToken());
-        if (started) await enrollment.start();
-        retireControl(previous);
-    }
-
-    async function start() {
-        if (started || closed) return getStatus();
-        started = true;
-        enrollment = makeEnrollmentControl(getEnrollmentToken());
-        await Promise.all([stable.start(), enrollment.start()]);
-        return getStatus();
-    }
-
-    async function close() {
-        if (closed) return;
-        closed = true;
-        started = false;
-        for (const timer of retirementTimers) clearTimeout(timer);
-        retirementTimers.clear();
-        const controls = [stable, enrollment, ...retired].filter(Boolean);
-        retired.clear();
-        enrollment = null;
-        const results = await Promise.allSettled(controls.map(control => control.close()));
-        const failure = results.find(result => result.status === 'rejected');
-        if (failure) throw failure.reason;
-    }
-
-    function getStatus() {
-        const stableStatus = stable.getStatus();
-        const enrollmentStatus = enrollment?.getStatus() || null;
-        const retiredStatuses = [...retired].map(control => control.getStatus());
-        const statuses = [stableStatus, enrollmentStatus, ...retiredStatuses].filter(Boolean);
-        return {
-            ...stableStatus,
-            started,
-            connected: statuses.some(status => status.connected),
-            state: stableStatus.connected ? 'registered' : enrollmentStatus?.state || stableStatus.state,
-            peerCount: statuses.reduce((sum, status) => sum + Number(status.peerCount || 0), 0),
-            activeSocketCount: statuses.reduce((sum, status) => sum + Number(status.activeSocketCount || 0), 0),
-            secureCredentialRelay: true,
-            credentialRoomId: deriveCredentialRelayRoomId(authority.hubId, authority.hubPublicKey),
-            enrollmentGenerationCount: 1 + retiredStatuses.length,
-            enrollment: enrollmentStatus,
-            retiredEnrollmentCount: retiredStatuses.length
-        };
-    }
-
-    return Object.freeze({ start, close, getStatus });
-}
+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_MAX_RECEIVE_CHUNKS = 256;
+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;
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_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.isBuffer(value) ? value : 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.isBuffer(sessionKey)
+        ? sessionKey
+        : 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.isBuffer(plaintext)
+        ? plaintext
+        : Buffer.from(plaintext || []);
+    if (cleartext.length < 1 || cleartext.length > RELAY_CONTROL_MAX_PLAINTEXT_BYTES) {
+        throw relayError('relay-plaintext-size-invalid');
+    }
+    const nonceBytes = Buffer.isBuffer(nonce)
+        ? nonce
+        : 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 update = cipher.update(cleartext);
+    const final = cipher.final();
+    const ciphertext = final.length > 0
+        ? Buffer.concat([update, final], update.length + final.length)
+        : update;
+    const tag = cipher.getAuthTag();
+    const envelope = Buffer.allocUnsafe(nonceBytes.length + ciphertext.length + tag.length);
+    nonceBytes.copy(envelope, 0);
+    ciphertext.copy(envelope, nonceBytes.length);
+    tag.copy(envelope, nonceBytes.length + ciphertext.length);
+    return encodeBase64Url(envelope);
+}
+
+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 update = decipher.update(ciphertext);
+        const final = decipher.final();
+        const plaintext = final.length > 0
+            ? Buffer.concat([update, final], update.length + final.length)
+            : update;
+        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) return;
+        if (Buffer.isBuffer(plaintext)) {
+            this.emit('data', plaintext);
+            return;
+        }
+        this.owner.recordPlaintextDeliveryCopy();
+        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 connectTimeoutMs = boundedInteger(
+        env.LIVEDESK_RELAY_CONNECT_TIMEOUT_MS,
+        250,
+        30_000,
+        DEFAULT_CONNECT_TIMEOUT_MS);
+    const peers = new Map();
+    const retiredPeerIds = new Map();
+    const connectionOwners = new Map();
+    const sendQueue = [];
+    let sendQueueHead = 0;
+    const peerQueueStats = new Map();
+    const counters = {
+        connections: 0,
+        reconnects: 0,
+        handshakes: 0,
+        rejectedPeers: 0,
+        encryptedMessagesReceived: 0,
+        encryptedMessagesSent: 0,
+        queueDrops: 0,
+        receiveLineAssemblyCopies: 0,
+        receiveLineAssemblyBytes: 0,
+        plaintextDeliveryCopies: 0,
+        peerQueuePurges: 0,
+        peerQueuePurgedBytes: 0,
+        staleConnectionEventDrops: 0,
+        socketOwnersCreated: 0,
+        socketOwnersClosed: 0,
+        peerOwnersCreated: 0,
+        peerOwnersClosed: 0
+    };
+
+    let desired = false;
+    let started = false;
+    let closing = false;
+    let connection = null;
+    let connectionGeneration = 0;
+    let reconnectTimer = null;
+    let connectAttemptTimer = null;
+    let closeSocketTimer = null;
+    let closeTimedOut = false;
+    let reconnectAttempt = 0;
+    let receiveChunks = [];
+    let receiveBytes = 0;
+    let receiveChunkHighWater = 0;
+    let receiveByteHighWater = 0;
+    let queuedBytes = 0;
+    let queuedMessageHighWater = 0;
+    let queuedByteHighWater = 0;
+    let socketWritableByteHighWater = 0;
+    let totalOutboundByteHighWater = 0;
+    let socketOwnerHighWater = 0;
+    let peerOwnerHighWater = 0;
+    let timerOwnerHighWater = 0;
+    let awaitingDrain = false;
+    let lastError = '';
+    let lastDisconnectReason = '';
+    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 activeTimerCount() {
+        return Number(Boolean(reconnectTimer))
+            + Number(Boolean(connectAttemptTimer))
+            + Number(Boolean(closeSocketTimer));
+    }
+
+    function recordTimerOwnerHighWater() {
+        timerOwnerHighWater = Math.max(
+            timerOwnerHighWater,
+            activeTimerCount());
+    }
+
+    function addConnectionOwner(socket, generation) {
+        if (connectionOwners.has(socket)) {
+            throw relayError('relay-socket-owner-duplicate');
+        }
+        connectionOwners.set(socket, {
+            socket,
+            generation,
+            phase: 'current'
+        });
+        counters.socketOwnersCreated += 1;
+        socketOwnerHighWater = Math.max(
+            socketOwnerHighWater,
+            connectionOwners.size);
+    }
+
+    function markConnectionOwnerClosing(socket, generation) {
+        const owner = connectionOwners.get(socket);
+        if (!owner || owner.generation !== generation) return false;
+        owner.phase = 'closing';
+        return true;
+    }
+
+    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 = peerQueueStats.get(item.peerId);
+        if (!stats) return;
+        stats.messages = Math.max(0, stats.messages - 1);
+        stats.bytes = Math.max(0, stats.bytes - item.buffer.length);
+    }
+
+    function queuedMessageCount() {
+        return sendQueue.length - sendQueueHead;
+    }
+
+    function socketWritableBytes(socket = connection) {
+        const value = Number(socket?.writableLength);
+        return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+    }
+
+    function recordOutboundHighWater(socket = connection) {
+        const writableBytes = socketWritableBytes(socket);
+        socketWritableByteHighWater = Math.max(
+            socketWritableByteHighWater,
+            writableBytes);
+        totalOutboundByteHighWater = Math.max(
+            totalOutboundByteHighWater,
+            queuedBytes + writableBytes);
+    }
+
+    function dequeueQueuedItem() {
+        if (queuedMessageCount() <= 0) return null;
+        const item = sendQueue[sendQueueHead];
+        sendQueue[sendQueueHead] = null;
+        sendQueueHead += 1;
+        if (sendQueueHead >= 64 && sendQueueHead * 2 >= sendQueue.length) {
+            sendQueue.splice(0, sendQueueHead);
+            sendQueueHead = 0;
+        }
+        return item;
+    }
+
+    function clearQueue() {
+        sendQueue.length = 0;
+        sendQueueHead = 0;
+        queuedBytes = 0;
+        awaitingDrain = false;
+        peerQueueStats.clear();
+    }
+
+    function purgePeerQueue(peerId) {
+        if (!peerId || queuedMessageCount() === 0) return;
+        let writeIndex = 0;
+        let purgedBytes = 0;
+        for (let readIndex = sendQueueHead; readIndex < sendQueue.length; readIndex += 1) {
+            const item = sendQueue[readIndex];
+            if (item.peerId === peerId) {
+                purgedBytes += item.buffer.length;
+                releaseQueuedItem(item);
+                continue;
+            }
+            sendQueue[writeIndex] = item;
+            writeIndex += 1;
+        }
+        for (let index = writeIndex; index < sendQueue.length; index += 1) {
+            sendQueue[index] = null;
+        }
+        if (purgedBytes > 0) {
+            sendQueue.length = writeIndex;
+            sendQueueHead = 0;
+            counters.peerQueuePurges += 1;
+            counters.peerQueuePurgedBytes += purgedBytes;
+        } else if (sendQueueHead > 0) {
+            sendQueue.splice(0, sendQueueHead);
+            sendQueueHead = 0;
+        }
+    }
+
+    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 (queuedMessageCount() > 0 && !awaitingDrain) {
+            const item = dequeueQueuedItem();
+            if (!item) break;
+            releaseQueuedItem(item);
+            let writable = false;
+            try {
+                writable = socket.write(item.buffer);
+            } catch {
+                socket.destroy();
+                return;
+            }
+            if (!writable) awaitingDrain = true;
+            recordOutboundHighWater(socket);
+        }
+        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);
+        const writableBytes = socketWritableBytes();
+        if (queuedMessageCount() >= maxQueueMessages
+            || queuedBytes + writableBytes + 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;
+        queuedMessageHighWater = Math.max(queuedMessageHighWater, queuedMessageCount());
+        queuedByteHighWater = Math.max(queuedByteHighWater, queuedBytes);
+        recordOutboundHighWater();
+        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'
+        });
+    }
+
+    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);
+        counters.peerOwnersClosed += 1;
+        rememberRetiredPeer(id);
+        purgePeerQueue(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.isBuffer(plaintext)
+            ? plaintext
+            : 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);
+            counters.peerOwnersCreated += 1;
+            peerOwnerHighWater = Math.max(peerOwnerHighWater, peers.size);
+            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 = safeText(message.peerId, 64);
+            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;
+        if (message.type === 'relay.registered') {
+            if (message.protocol !== RELAY_CONTROL_PROTOCOL
+                || message.roomId !== roomId
+                || message.role !== 'hub'
+                || safeText(message.peerId, 64) !== ''
+                || state !== 'registering') {
+                lastError = 'relay-registration-invalid';
+                connection?.destroy();
+                return;
+            }
+            clearConnectAttemptTimer();
+            reconnectAttempt = 0;
+            lastConnectedAt = new Date().toISOString();
+            lastError = '';
+            transition('registered');
+            logEvent('relay', `Encrypted relay control registered at ${host}:${port}`);
+            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') {
+            const reason = safeText(message.reason, 80) || 'relay-server-closed';
+            if (!peerId) {
+                lastError = reason;
+                lastDisconnectReason = reason;
+                connection?.destroy();
+                return;
+            }
+            try {
+                closePeer(requirePeerId(message.peerId), reason, { notify: false });
+            } catch {
+                // Invalid untrusted routing fields are ignored.
+            }
+        }
+    }
+
+    function clearReceiveChunks() {
+        receiveChunks = [];
+        receiveBytes = 0;
+    }
+
+    function retainReceiveTail(incoming, offset) {
+        const tail = incoming.subarray(offset);
+        if (tail.length === 0) return true;
+        if (receiveBytes + tail.length > RELAY_MAX_LINE_BYTES) return false;
+        // A tail following a complete line must not retain the complete large
+        // TCP chunk. A chunk containing no line is already exact ownership and
+        // can be retained without copying.
+        const retained = offset > 0 ? Buffer.from(tail) : tail;
+        if (receiveChunks.length >= RELAY_MAX_RECEIVE_CHUNKS) return false;
+        receiveChunks.push(retained);
+        receiveBytes += retained.length;
+        receiveChunkHighWater = Math.max(receiveChunkHighWater, receiveChunks.length);
+        receiveByteHighWater = Math.max(receiveByteHighWater, receiveBytes);
+        return true;
+    }
+
+    function assembleReceiveLine(segment) {
+        if (receiveBytes === 0) return segment;
+        const totalBytes = receiveBytes + segment.length;
+        const line = Buffer.allocUnsafe(totalBytes);
+        let offset = 0;
+        for (const chunk of receiveChunks) {
+            chunk.copy(line, offset);
+            offset += chunk.length;
+        }
+        segment.copy(line, offset);
+        counters.receiveLineAssemblyCopies += 1;
+        counters.receiveLineAssemblyBytes += totalBytes;
+        clearReceiveChunks();
+        return line;
+    }
+
+    function isCurrentConnectionOwner(socket, generation) {
+        return desired
+            && !closing
+            && connection === socket
+            && generation === connectionGeneration
+            && !socket.destroyed;
+    }
+
+    function processRelayLine(socket, generation, line) {
+        if (!isCurrentConnectionOwner(socket, generation)) {
+            counters.staleConnectionEventDrops += 1;
+            return false;
+        }
+        if (line.length === 0) return true;
+        let message;
+        try {
+            message = JSON.parse(line.toString('utf8'));
+        } catch {
+            lastError = 'relay-invalid-json';
+            socket.destroy();
+            return false;
+        }
+        if (!isCurrentConnectionOwner(socket, generation)) {
+            counters.staleConnectionEventDrops += 1;
+            return false;
+        }
+        handleRelayEnvelope(message);
+        return true;
+    }
+
+    function onConnectionData(socket, generation, chunk) {
+        if (!isCurrentConnectionOwner(socket, generation)) {
+            counters.staleConnectionEventDrops += 1;
+            return;
+        }
+        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let offset = 0;
+        while (offset < incoming.length) {
+            if (!isCurrentConnectionOwner(socket, generation)) {
+                counters.staleConnectionEventDrops += 1;
+                return;
+            }
+            const newline = incoming.indexOf(0x0a, offset);
+            if (newline < 0) {
+                if (!retainReceiveTail(incoming, offset)) {
+                    lastError = 'relay-line-too-large';
+                    socket.destroy();
+                }
+                return;
+            }
+            const segmentLength = newline - offset;
+            if (receiveBytes + segmentLength > RELAY_MAX_LINE_BYTES) {
+                lastError = 'relay-line-too-large';
+                socket.destroy();
+                return;
+            }
+            const line = assembleReceiveLine(incoming.subarray(offset, newline));
+            if (!processRelayLine(socket, generation, line)) return;
+            offset = newline + 1;
+        }
+    }
+
+    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?.();
+        recordTimerOwnerHighWater();
+    }
+
+    function clearConnectAttemptTimer() {
+        if (connectAttemptTimer) clearTimeout(connectAttemptTimer);
+        connectAttemptTimer = null;
+    }
+
+    function handleConnectionClosed(socket, generation) {
+        const owner = connectionOwners.get(socket);
+        if (!owner || owner.generation !== generation) return;
+        connectionOwners.delete(socket);
+        counters.socketOwnersClosed += 1;
+        if (owner.phase === 'closing') return;
+        if (connection !== socket || generation !== connectionGeneration) return;
+        clearConnectAttemptTimer();
+        connection = null;
+        const disconnectReason = safeText(lastError, 120) || 'relay-socket-closed';
+        lastDisconnectReason = disconnectReason;
+        logWarn(
+            'relay',
+            `Encrypted relay control disconnected reason=${disconnectReason} peers=${peers.size}`
+        );
+        clearReceiveChunks();
+        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;
+        addConnectionOwner(socket, generation);
+        socket.setNoDelay?.(true);
+        socket.setKeepAlive?.(true, 10_000);
+        socket.once('connect', () => {
+            if (connection !== socket || generation !== connectionGeneration || !desired) return;
+            counters.connections += 1;
+            transition('registering');
+            const registered = enqueueEnvelope({
+                type: 'relay.register',
+                protocol: RELAY_CONTROL_PROTOCOL,
+                roomId,
+                role: 'hub',
+                peerId: '',
+                ack: true,
+                token: registrationToken
+            });
+            if (!registered) socket.destroy();
+        });
+        socket.on('data', chunk => onConnectionData(socket, generation, chunk));
+        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));
+        connectAttemptTimer = setTimeout(() => {
+            if (connection !== socket
+                || generation !== connectionGeneration
+                || socket.destroyed
+                || (state !== 'connecting' && state !== 'registering')) return;
+            lastError = 'relay-connect-timeout';
+            logWarn('relay', `Encrypted relay control connection failed code=${lastError}`);
+            socket.destroy();
+        }, connectTimeoutMs);
+        connectAttemptTimer.unref?.();
+        recordTimerOwnerHighWater();
+    }
+
+    async function start() {
+        if (!enabled || started) return getStatus();
+        if (closing || closeTimedOut || connectionOwners.size > 0) {
+            throw relayError('relay-close-nonterminal');
+        }
+        started = true;
+        desired = true;
+        closing = false;
+        connectNow();
+        return getStatus();
+    }
+
+    async function close() {
+        const closeDeadlineAt = Date.now() + 1_000;
+        desired = false;
+        started = false;
+        closing = true;
+        closeTimedOut = false;
+        transition('closing');
+        if (reconnectTimer) clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+        clearConnectAttemptTimer();
+        closeAllPeers('hub-shutdown');
+        clearQueue();
+        const socket = connection;
+        const generation = connectionGeneration;
+        if (socket) markConnectionOwnerClosing(socket, generation);
+        connection = null;
+        connectionGeneration += 1;
+        clearReceiveChunks();
+        const closingOwners = [...connectionOwners.values()];
+        if (closingOwners.length > 0) {
+            const ownersClosed = new Promise((resolve, reject) => {
+                let settled = false;
+                const onClose = () => {
+                    if (connectionOwners.size === 0) settle();
+                };
+                const settle = () => {
+                    if (settled) return;
+                    settled = true;
+                    if (closeSocketTimer) clearTimeout(closeSocketTimer);
+                    closeSocketTimer = null;
+                    for (const owner of closingOwners) {
+                        owner.socket.off?.('close', onClose);
+                    }
+                    resolve();
+                };
+                const fail = () => {
+                    if (settled) return;
+                    settled = true;
+                    closeSocketTimer = null;
+                    for (const owner of closingOwners) {
+                        owner.socket.off?.('close', onClose);
+                    }
+                    reject(relayError('relay-close-timeout'));
+                };
+                for (const owner of closingOwners) {
+                    owner.phase = 'closing';
+                    owner.socket.once('close', onClose);
+                }
+                closeSocketTimer = setTimeout(() => {
+                    fail();
+                }, Math.max(1, closeDeadlineAt - Date.now()));
+                recordTimerOwnerHighWater();
+                if (connectionOwners.size === 0) settle();
+            });
+            for (const owner of closingOwners) {
+                try {
+                    owner.socket.end();
+                } catch {
+                    // The exact owner remains in the ledger until close.
+                }
+                try {
+                    owner.socket.destroy();
+                } catch {
+                    // Timeout remains explicit and nonterminal.
+                }
+            }
+            try {
+                await ownersClosed;
+            } catch (error) {
+                closeTimedOut = true;
+                lastError = 'relay-close-timeout';
+                transition('close-timeout', lastError);
+                throw error;
+            }
+        }
+        if (connectionOwners.size !== 0) {
+            closeTimedOut = true;
+            lastError = 'relay-close-nonterminal';
+            transition('close-timeout', lastError);
+            throw relayError(lastError);
+        }
+        closeTimedOut = false;
+        closing = false;
+        lastError = '';
+        transition(enabled ? 'idle' : 'disabled');
+    }
+
+    function getStatus() {
+        const writableBytes = socketWritableBytes();
+        recordOutboundHighWater();
+        return {
+            enabled,
+            started,
+            state,
+            connected: !!connection && !connection.destroyed && state === 'registered',
+            closing,
+            closeTimedOut,
+            activeSocketCount: connectionOwners.size,
+            currentSocketCount: connection && connectionOwners.has(connection) ? 1 : 0,
+            closingSocketCount: [...connectionOwners.values()]
+                .filter(owner => owner.phase === 'closing').length,
+            activeTimerCount: activeTimerCount(),
+            timerOwnerHighWater,
+            socketOwnerHighWater,
+            socketOwnersCreated: counters.socketOwnersCreated,
+            socketOwnersClosed: counters.socketOwnersClosed,
+            protocol: RELAY_CONTROL_PROTOCOL,
+            endpoint: `${host}:${port}`,
+            host,
+            port,
+            peerCount: peers.size,
+            peerOwnerHighWater,
+            peerOwnersCreated: counters.peerOwnersCreated,
+            peerOwnersClosed: counters.peerOwnersClosed,
+            peerQueueCount: peerQueueStats.size,
+            queuedMessages: queuedMessageCount(),
+            queuedBytes,
+            socketWritableBytes: writableBytes,
+            totalOutboundBufferedBytes: queuedBytes + writableBytes,
+            queuedMessageHighWater,
+            queuedByteHighWater,
+            socketWritableByteHighWater,
+            totalOutboundByteHighWater,
+            receiveBufferedChunks: receiveChunks.length,
+            receiveBufferedBytes: receiveBytes,
+            receiveChunkHighWater,
+            receiveByteHighWater,
+            receiveLineAssemblyCopyCount: counters.receiveLineAssemblyCopies,
+            receiveLineAssemblyBytes: counters.receiveLineAssemblyBytes,
+            plaintextDeliveryCopyCount: counters.plaintextDeliveryCopies,
+            peerQueuePurgeCount: counters.peerQueuePurges,
+            peerQueuePurgedBytes: counters.peerQueuePurgedBytes,
+            staleConnectionEventDropCount: counters.staleConnectionEventDrops,
+            maxPeers,
+            maxQueueMessages,
+            maxQueueBytes,
+            reconnectCount: counters.reconnects,
+            handshakeCount: counters.handshakes,
+            rejectedPeerCount: counters.rejectedPeers,
+            encryptedMessagesReceived: counters.encryptedMessagesReceived,
+            encryptedMessagesSent: counters.encryptedMessagesSent,
+            queueDropCount: counters.queueDrops,
+            lastConnectedAt,
+            lastTransitionAt,
+            lastDisconnectReason,
+            lastError
+        };
+    }
+
+    function recordPlaintextDeliveryCopy() {
+        counters.plaintextDeliveryCopies += 1;
+    }
+
+    const api = {
+        start,
+        close,
+        getStatus,
+        sendPeerPlaintext,
+        closePeer,
+        isPeerBackpressured,
+        recordPlaintextDeliveryCopy
+    };
+    return api;
+}