livedesk 0.1.284 → 0.1.286

package/hub/src/remote-hub.js

@@ -960,8 +960,9 @@ function serializeDevice(device, options = {}) {
                 byteLength: device.latestAudioFrame.byteLength
             }
             : null,
-        latestAudioStatus: device.latestAudioStatus ? { ...device.latestAudioStatus } : null,
-        latestTask: device.latestTask ? { ...device.latestTask } : null,
+        latestAudioStatus: device.latestAudioStatus ? { ...device.latestAudioStatus } : null,
+        udp: device.udp ? { ...device.udp } : { enabled: false, state: 'tcp-only', ready: false },
+        latestTask: device.latestTask ? { ...device.latestTask } : null,
         synthetic: device.synthetic === true,
         recentTasks: Array.isArray(device.recentTasks)
             ? device.recentTasks.map(task => ({ ...task }))
@@ -1395,6 +1396,9 @@ export function createRemoteHub(options = {}) {
     const getWelcomeDevicePolicy = typeof options.getWelcomeDevicePolicy === 'function'
         ? options.getWelcomeDevicePolicy
         : getEffectiveDevicePolicy;
+    const udpTransport = options.udpTransport && typeof options.udpTransport === 'object'
+        ? options.udpTransport
+        : null;
 
     function getDevicePolicy(device) {
         try {
@@ -1746,7 +1750,7 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function getStatus({ includeSecrets = false } = {}) {
+    function getStatus({ includeSecrets = false } = {}) {
         const connectedDevices = [...devices.values()].filter(device => device.connected).length;
         const activeHostTarget = serializeHostTarget();
         const routeInfo = getAgentEndpointRouteInfo();
@@ -1791,10 +1795,18 @@ export function createRemoteHub(options = {}) {
             hostTargetExpiresAt: activeHostTarget.expiresAt,
             publicIPv4Address: publicIPv4Cache.address,
             publicIPv4UpdatedAt: publicIPv4Cache.updatedAt ? new Date(publicIPv4Cache.updatedAt).toISOString() : '',
-            publicIPv4Error: publicIPv4Cache.error,
-            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
-            lastError
-        };
+            publicIPv4Error: publicIPv4Cache.error,
+            udp: udpTransport?.getStatus?.() || {
+                enabled: false,
+                preferred: false,
+                started: false,
+                port: 0,
+                sessionCount: 0,
+                readySessionCount: 0
+            },
+            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
+            lastError
+        };
     }
 
     function rotatePairingPin() {
@@ -2650,9 +2662,15 @@ export function createRemoteHub(options = {}) {
             },
             activeLiveStream: null,
             activeAudioStream: null,
-            latestAudioFrame: null,
-            latestAudioStatus: null,
-            latestTask: null,
+            latestAudioFrame: null,
+            latestAudioStatus: null,
+            udp: {
+                enabled: capabilities.udpP2p === true,
+                state: 'tcp-only',
+                ready: false,
+                sessionId: ''
+            },
+            latestTask: null,
             recentTasks: [],
             pendingTaskCommands: new Map(),
             pendingTaskTimers: new Map(),
@@ -2662,7 +2680,7 @@ export function createRemoteHub(options = {}) {
 
         devices.set(deviceId, device);
         sockets.set(socket, deviceId);
-        writeJsonLine(socket, {
+        writeJsonLine(socket, {
             type: 'welcome',
             protocol: REMOTE_AGENT_PROTOCOL,
             protocolVersion: REMOTE_PROTOCOL_VERSION,
@@ -2672,8 +2690,22 @@ export function createRemoteHub(options = {}) {
             frameProtocol: buildRemoteFrameProtocolDescriptor(),
             frameModes: getSupportedRemoteFrameModeProfiles(),
             effectivePolicy: getWelcomeDevicePolicy({ deviceId, capabilities }),
-            serverTime: now
-        });
+            serverTime: now
+        });
+
+        const udpSession = udpTransport?.registerDevice?.({
+            deviceId,
+            sessionId,
+            sendControl: payload => writeJsonLine(socket, payload),
+            capabilities
+        });
+        if (udpSession?.sessionId) {
+            device.udp = {
+                ...device.udp,
+                state: 'udp-session-created',
+                sessionId: udpSession.sessionId
+            };
+        }
 
         logEvent('remote', `device connected ${device.deviceName} (${deviceId})`, 'success');
         emitRemoteEvent('RemoteDeviceConnected', device);
@@ -2812,8 +2844,9 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        device.connected = false;
-        device.socket = null;
+        device.connected = false;
+        device.socket = null;
+        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
         closeInputSocket(device, reason);
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
@@ -3687,7 +3720,7 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function handleAgentBinaryFrame(socket, state, header, framePayload) {
+    function handleAgentBinaryFrame(socket, state, header, framePayload) {
         if (!state.authenticated || !state.device) {
             writeJsonLine(socket, { type: 'error', error: 'hello-required' });
             socket.destroy();
@@ -3734,11 +3767,37 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        emitRemoteEvent('RemoteAgentMessageIgnored', device, {
-            messageType: safeString(header.type, 80),
-            frameKind
-        });
-    }
+        emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+            messageType: safeString(header.type, 80),
+            frameKind
+        });
+    }
+
+    function handleUdpFrame({ deviceId, sessionId, header, payload } = {}) {
+        const device = devices.get(safeString(deviceId, 160));
+        if (!device || !device.connected) {
+            return false;
+        }
+        if (device.udp?.sessionId && device.udp.sessionId !== safeString(sessionId, 160)) {
+            return false;
+        }
+        const frameMode = safeString(header?.frameMode || header?.mode, 40).toLowerCase();
+        if (frameMode !== 'mode3-h264-hw') {
+            emitRemoteEvent('RemoteFrameDropped', device, { reason: 'udp-frame-mode-not-supported', transport: 'udp-p2p', frameMode });
+            return false;
+        }
+        device.udp = {
+            ...device.udp,
+            state: 'udp-active',
+            ready: true,
+            lastFrameAt: new Date().toISOString(),
+            framesReceived: Number(device.udp?.framesReceived || 0) + 1
+        };
+        return applyLiveFrame(device, {
+            ...header,
+            transport: 'udp-p2p'
+        }, payload, 'udp-p2p');
+    }
 
     function dropQueuedAgentBinaryFrame(state) {
         if (!Array.isArray(state.binaryQueue) || state.binaryQueue.length === 0) {
@@ -4399,13 +4458,14 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    async function start() {
+    async function start() {
         if (!enabled || started) {
             return getStatus({ includeSecrets: false });
         }
 
-        try {
-            await listenOnPort(requestedPort);
+        try {
+            await udpTransport?.start?.();
+            await listenOnPort(requestedPort);
         } catch (error) {
             if (error?.code === 'EADDRINUSE') {
                 const conflict = new Error(
@@ -4422,7 +4482,7 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
+    async function close() {
         for (const device of devices.values()) {
             failAllPendingTasks(device, 'hub-shutdown');
             if (device.socket && !device.socket.destroyed) {
@@ -4437,8 +4497,9 @@ export function createRemoteHub(options = {}) {
             }
         }
 
-        sockets.clear();
-        if (!server) {
+        sockets.clear();
+        await udpTransport?.close?.();
+        if (!server) {
             started = false;
             return;
         }
@@ -5488,7 +5549,7 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    function getFramePayload(deviceId, frameKind, options = {}) {
+    function getFramePayload(deviceId, frameKind, options = {}) {
         const device = devices.get(String(deviceId || ''));
         if (!device) {
             return null;
@@ -5505,10 +5566,25 @@ export function createRemoteHub(options = {}) {
             payload: frame.payload,
             mimeType: safeString(frame.mimeType || frame.format || 'application/octet-stream', 120) || 'application/octet-stream',
             byteLength: frame.payload.length
-        };
-    }
-
-    return {
+        };
+    }
+
+    udpTransport?.setFrameHandler?.(handleUdpFrame);
+    udpTransport?.setEventHandler?.((type, event = {}) => {
+        const device = devices.get(safeString(event.deviceId, 160));
+        if (device?.udp) {
+            if (type === 'UdpSessionReady') {
+                device.udp = { ...device.udp, state: 'udp-ready', ready: true };
+            } else if (type === 'UdpSessionClosed') {
+                device.udp = { ...device.udp, state: 'tcp-fallback', ready: false };
+            }
+        }
+        if (device) {
+            emitRemoteEvent(`Remote${type}`, device, { ...event });
+        }
+    });
+
+    return {
         start,
         close,
         getStatus,
@@ -5534,8 +5610,9 @@ export function createRemoteHub(options = {}) {
         stopAudioStream,
         getDeviceLiveFrame,
         getDeviceThumbnail,
-        getFramePayload,
-        seedSyntheticFleet,
+        getFramePayload,
+        handleUdpFrame,
+        seedSyntheticFleet,
         clearSyntheticFleet,
         getPairToken: () => pairToken,
         getPairingPin: () => pairingPin

package/hub/src/server.js

@@ -27,6 +27,7 @@ import { effectiveDevicePolicy } from './settings/settings-schema.js';
 import { buildEffectiveDevicePolicy } from './settings/effective-device-policy.js';
 import { CaptureStore } from './captures/capture-store.js';
 import { createLiveDeskUpdateManager } from './live-desk-update.js';
+import { createHubUdpTransport } from './transport/udp-hub-transport.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const webDistCandidates = [
@@ -250,14 +251,21 @@ void liveDeskSettingsStore.getRecord().catch(error => {
   console.warn(`[LiveDesk Hub] settings load failed: ${error instanceof Error ? error.message : String(error)}`);
 });
 
+const udpTransport = createHubUdpTransport({
+  env: process.env,
+  logEvent: (_scope, message) => console.log(`[LiveDesk Hub] ${message}`),
+  logWarn: (_scope, message) => console.warn(`[LiveDesk Hub] ${message}`)
+});
+
 const remoteHub = createRemoteHub({
   managerPackage: '@livedesk/hub',
   managerVersion: packageInfo.version,
-  env: {
+  env: {
     ...process.env,
     MINDEXEC_MANAGER_PACKAGE: '@livedesk/hub',
     MINDEXEC_MANAGER_VERSION: packageInfo.version
-  },
+  },
+  udpTransport,
   logEvent: (_scope, message) => console.log(`[LiveDesk Hub] ${message}`),
   logWarn: (_scope, message) => console.warn(`[LiveDesk Hub] ${message}`),
   emitEvent: handleRemoteHubEvent,

package/hub/src/transport/udp-hub-transport.js

@@ -0,0 +1,281 @@
+import crypto from 'node:crypto';
+import dgram from 'node:dgram';
+import {
+    UDP_MAX_DATAGRAM_BYTES,
+    UDP_P2P_PROTOCOL,
+    UdpFrameReassembler,
+    UdpReplayWindow,
+    decodeRendezvousMessage,
+    decodeUdpPacket,
+    encodeRendezvousMessage,
+    encodeUdpPacket,
+    createUdpSessionKey
+} from './udp-protocol.js';
+
+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, max = 160) {
+    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, max);
+}
+
+function numberEnv(value, min, max, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number) ? Math.max(min, Math.min(max, Math.floor(number))) : fallback;
+}
+
+function sameEndpoint(left, right) {
+    return !!left && !!right && String(left.address) === String(right.address) && Number(left.port) === Number(right.port);
+}
+
+export function createHubUdpTransport({ env = process.env, logEvent = () => {}, logWarn = () => {} } = {}) {
+    const enabled = isEnabled(env.LIVEDESK_UDP_ENABLED, false);
+    const preferP2p = isEnabled(env.LIVEDESK_UDP_PREFER_P2P, true);
+    const bindHost = safeText(env.LIVEDESK_UDP_BIND_HOST || '0.0.0.0', 128) || '0.0.0.0';
+    const requestedPort = numberEnv(env.LIVEDESK_UDP_PORT, 0, 65535, 0);
+    const advertiseHost = safeText(env.LIVEDESK_UDP_ADVERTISE_HOST || env.LIVEDESK_REMOTE_PUBLIC_HOST || '', 128);
+    const rendezvousHost = safeText(env.LIVEDESK_UDP_RENDEZVOUS_HOST || '', 128);
+    const rendezvousPort = numberEnv(env.LIVEDESK_UDP_RENDEZVOUS_PORT, 1, 65535, 5199);
+    const punchTimeoutMs = numberEnv(env.LIVEDESK_UDP_PUNCH_TIMEOUT_MS, 500, 10_000, 3000);
+    const frameTimeoutMs = numberEnv(env.LIVEDESK_UDP_FRAME_TIMEOUT_MS, 20, 2000, 80);
+    const maxPendingFrames = numberEnv(env.LIVEDESK_UDP_MAX_PENDING_FRAMES, 1, 16, 2);
+    const trace = isEnabled(env.LIVEDESK_UDP_TRACE, false);
+    const socket = dgram.createSocket('udp4');
+    const sessions = new Map();
+    let frameHandler = () => {};
+    let eventHandler = () => {};
+    let started = false;
+    let boundPort = requestedPort;
+    let sequence = crypto.randomInt(1, 0x7fffffff);
+
+    function emit(type, event = {}) {
+        eventHandler(type, event);
+        if (trace) logEvent('udp', `${type} ${JSON.stringify({ deviceId: event.deviceId || '', state: event.state || '', reason: event.reason || '' })}`);
+    }
+
+    function nextSequence() {
+        sequence = (sequence + 1) >>> 0;
+        return sequence;
+    }
+
+    function sendPacket(session, type, header = {}, payload = Buffer.alloc(0), address = session.peerEndpoint || session.clientEndpoint) {
+        if (!address || !session) return false;
+        let packet;
+        try {
+            packet = encodeUdpPacket({ type, sessionId: session.sessionId, key: session.key, sequence: nextSequence(), header, payload });
+        } catch (error) {
+            logWarn('udp', `UDP packet rejected device=${session.deviceId}: ${error?.message || error}`);
+            return false;
+        }
+        socket.send(packet, address.port, address.address);
+        return true;
+    }
+
+    function sendRendezvousRegister(session) {
+        if (!rendezvousHost) return;
+        const message = encodeRendezvousMessage({
+            type: 'rendezvous.register',
+            protocol: UDP_P2P_PROTOCOL,
+            roomId: session.sessionId,
+            role: 'hub',
+            token: session.rendezvousToken
+        });
+        socket.send(message, rendezvousPort, rendezvousHost);
+    }
+
+    function sessionForPacket(packet, rinfo) {
+        if (!Buffer.isBuffer(packet) || packet.length < 7) return null;
+        const sessionLength = packet[6];
+        if (!sessionLength || packet.length < 27 + sessionLength) return null;
+        const sessionId = packet.subarray(27, 27 + sessionLength).toString('utf8');
+        const session = [...sessions.values()].find(item => item.sessionId === sessionId);
+        if (!session) return null;
+        if (!session.clientEndpoint) session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+        if (!sameEndpoint(session.clientEndpoint, rinfo)) return null;
+        return session;
+    }
+
+    function onRendezvousPeer(message, rinfo) {
+        const session = [...sessions.values()].find(item => item.sessionId === safeText(message.roomId, 160));
+        if (!session || !rendezvousHost || Number(rinfo.port) !== rendezvousPort) return;
+        const address = safeText(message.host, 128);
+        const port = Number(message.port);
+        if (!address || !Number.isInteger(port) || port < 1 || port > 65535) return;
+        session.peerEndpoint = { address, port };
+        session.lastPeerAt = Date.now();
+        sendPacket(session, 'probe', { punch: true }, Buffer.alloc(0), session.peerEndpoint);
+        emit('UdpPeerEndpointObserved', { deviceId: session.deviceId, endpoint: `${address}:${port}` });
+    }
+
+    socket.on('message', (payload, rinfo) => {
+        const rendezvous = decodeRendezvousMessage(payload);
+        if (rendezvous?.type === 'rendezvous.peer') {
+            onRendezvousPeer(rendezvous, rinfo);
+            return;
+        }
+        const session = sessionForPacket(payload, rinfo);
+        if (!session) return;
+        const packet = decodeUdpPacket(payload, session.key);
+        if (!packet || packet.sessionId !== session.sessionId || !session.replay.accept(packet.sequence)) return;
+        session.lastPacketAt = Date.now();
+        if (packet.type === 'probe') {
+            session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+            sendPacket(session, 'probe-ack', { observedHost: rinfo.address, observedPort: rinfo.port });
+            emit('UdpProbeReceived', { deviceId: session.deviceId });
+            return;
+        }
+        if (packet.type === 'ready') {
+            session.ready = true;
+            session.clientEndpoint = { address: rinfo.address, port: rinfo.port };
+            sendPacket(session, 'pong', { state: 'ready' });
+            session.sendControl?.({
+                type: 'udp.session.ready',
+                protocol: UDP_P2P_PROTOCOL,
+                sessionId: session.sessionId,
+                transport: 'udp-p2p',
+                ready: true,
+                endpoint: { host: advertiseHost, port: boundPort }
+            });
+            emit('UdpSessionReady', { deviceId: session.deviceId, state: 'udp-ready' });
+            return;
+        }
+        if (packet.type === 'ping') {
+            sendPacket(session, 'pong', { now: Date.now() });
+            return;
+        }
+        if (packet.type !== 'frame') return;
+        const complete = session.reassembler.ingest(packet);
+        if (!complete) return;
+        session.framesReceived += 1;
+        frameHandler({
+            deviceId: session.deviceId,
+            sessionId: session.sessionId,
+            header: complete.header,
+            payload: complete.payload,
+            transport: 'udp-p2p'
+        });
+        sendPacket(session, 'pong', {
+            state: 'frame-ack',
+            frameSeq: Number(complete.header?.frameSeq || 0) || 0
+        });
+    });
+    socket.on('error', error => logWarn('udp', `UDP socket error: ${error?.message || error}`));
+
+    async function start() {
+        if (!enabled || started) return getStatus();
+        await new Promise((resolve, reject) => {
+            const onError = error => { socket.off('listening', onListening); reject(error); };
+            const onListening = () => { socket.off('error', onError); resolve(); };
+            socket.once('error', onError);
+            socket.once('listening', onListening);
+            socket.bind(requestedPort, bindHost);
+        });
+        started = true;
+        boundPort = socket.address().port;
+        logEvent('udp', `UDP P2P socket listening on udp://${bindHost}:${boundPort}`);
+        return getStatus();
+    }
+
+    function registerDevice({ deviceId, sessionId: tcpSessionId, sendControl, capabilities } = {}) {
+        if (!enabled || capabilities?.udpP2p !== true || !started) return null;
+        const id = safeText(deviceId, 160);
+        if (!id) return null;
+        sessions.get(id)?.sendControl?.({ type: 'udp.session.close', reason: 'replaced' });
+        const key = createUdpSessionKey();
+        const session = {
+            deviceId: id,
+            tcpSessionId: safeText(tcpSessionId, 160),
+            sessionId: crypto.randomUUID(),
+            key,
+            keyBase64: key.toString('base64'),
+            rendezvousToken: crypto.randomBytes(16).toString('hex'),
+            sendControl,
+            clientEndpoint: null,
+            peerEndpoint: null,
+            replay: new UdpReplayWindow(),
+            reassembler: new UdpFrameReassembler({ maxPending: maxPendingFrames, timeoutMs: frameTimeoutMs }),
+            ready: false,
+            createdAt: Date.now(),
+            lastPacketAt: 0,
+            framesReceived: 0
+        };
+        sessions.set(id, session);
+        sendControl?.({
+            type: 'udp.session.offer',
+            protocol: UDP_P2P_PROTOCOL,
+            sessionId: session.sessionId,
+            key: session.keyBase64,
+            host: advertiseHost,
+            port: boundPort,
+            expiresInMs: punchTimeoutMs + 15_000,
+            punchTimeoutMs,
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            frameTimeoutMs,
+            maxPendingFrames,
+            rendezvous: rendezvousHost
+                ? { host: rendezvousHost, port: rendezvousPort, roomId: session.sessionId, token: session.rendezvousToken }
+                : null
+        });
+        sendRendezvousRegister(session);
+        emit('UdpSessionCreated', { deviceId: id, state: 'udp-session-created' });
+        return { sessionId: session.sessionId, ready: false };
+    }
+
+    function unregisterDevice(deviceId, tcpSessionId = '') {
+        const id = safeText(deviceId, 160);
+        const session = sessions.get(id);
+        if (!session || (tcpSessionId && session.tcpSessionId !== tcpSessionId)) return;
+        sessions.delete(id);
+        emit('UdpSessionClosed', { deviceId: id, reason: 'tcp-session-closed' });
+    }
+
+    function getDeviceStatus(deviceId) {
+        const session = sessions.get(safeText(deviceId, 160));
+        if (!session) return { enabled, state: enabled ? 'disabled' : 'tcp-only', ready: false };
+        return {
+            enabled,
+            preferred: preferP2p,
+            state: session.ready ? 'udp-ready' : 'udp-session-created',
+            ready: session.ready,
+            sessionId: session.sessionId,
+            lastPacketAt: session.lastPacketAt ? new Date(session.lastPacketAt).toISOString() : '',
+            framesReceived: session.framesReceived
+        };
+    }
+
+    async function close() {
+        sessions.clear();
+        if (!started) return;
+        await new Promise(resolve => socket.close(() => resolve()));
+        started = false;
+    }
+
+    return {
+        start,
+        close,
+        registerDevice,
+        unregisterDevice,
+        getDeviceStatus,
+        getStatus,
+        setFrameHandler: handler => { frameHandler = typeof handler === 'function' ? handler : () => {}; },
+        setEventHandler: handler => { eventHandler = typeof handler === 'function' ? handler : () => {}; }
+    };
+
+    function getStatus() {
+        return {
+            enabled,
+            preferred: preferP2p,
+            started,
+            bindHost,
+            port: boundPort,
+            advertiseHost,
+            rendezvousHost,
+            rendezvousPort,
+            maxDatagramBytes: UDP_MAX_DATAGRAM_BYTES,
+            sessionCount: sessions.size,
+            readySessionCount: [...sessions.values()].filter(session => session.ready).length
+        };
+    }
+}

package/hub/src/transport/udp-protocol.js

@@ -0,0 +1,216 @@
+import crypto from 'node:crypto';
+
+export const UDP_P2P_PROTOCOL = 'livedesk.udp.p2p.v1';
+export const UDP_P2P_VERSION = 1;
+export const UDP_MAX_DATAGRAM_BYTES = 1200;
+export const UDP_PACKET_TYPES = Object.freeze({
+    probe: 1,
+    'probe-ack': 2,
+    ready: 3,
+    ping: 4,
+    pong: 5,
+    frame: 6,
+    close: 7
+});
+const UDP_PACKET_TYPE_NAMES = new Map(Object.entries(UDP_PACKET_TYPES).map(([name, value]) => [value, name]));
+const UDP_FIXED_HEADER_BYTES = 15;
+const UDP_NONCE_BYTES = 12;
+const UDP_TAG_BYTES = 16;
+const UDP_MAX_SESSION_ID_BYTES = 96;
+const UDP_MAX_HEADER_BYTES = 4096;
+const UDP_MAX_PAYLOAD_BYTES = UDP_MAX_DATAGRAM_BYTES - UDP_FIXED_HEADER_BYTES - UDP_NONCE_BYTES - UDP_TAG_BYTES - 1;
+
+function asBuffer(value) {
+    if (Buffer.isBuffer(value)) return value;
+    if (value instanceof Uint8Array) return Buffer.from(value);
+    if (typeof value === 'string') return Buffer.from(value, 'utf8');
+    return Buffer.alloc(0);
+}
+
+function normalizeKey(key) {
+    const value = asBuffer(key);
+    return value.length === 32 ? value : crypto.createHash('sha256').update(value).digest();
+}
+
+function normalizeSessionId(value) {
+    const sessionId = String(value || '').trim();
+    if (!sessionId || Buffer.byteLength(sessionId, 'utf8') > UDP_MAX_SESSION_ID_BYTES) {
+        throw new Error('invalid-udp-session-id');
+    }
+    return sessionId;
+}
+
+function packetTypeCode(type) {
+    const code = typeof type === 'number' ? type : UDP_PACKET_TYPES[String(type || '').toLowerCase()];
+    if (!code || !UDP_PACKET_TYPE_NAMES.has(code)) throw new Error('invalid-udp-packet-type');
+    return code;
+}
+
+function encodeHeader(header) {
+    const bytes = Buffer.from(JSON.stringify(header && typeof header === 'object' ? header : {}), 'utf8');
+    if (bytes.length > UDP_MAX_HEADER_BYTES) throw new Error('udp-packet-header-too-large');
+    return bytes;
+}
+
+export function deriveUdpSessionKey(keyMaterial) {
+    return normalizeKey(keyMaterial);
+}
+
+export function createUdpSessionKey() {
+    return crypto.randomBytes(32);
+}
+
+export function encodeUdpPacket({ type, sessionId, key, sequence = 0, header = {}, payload = Buffer.alloc(0) }) {
+    const normalizedSessionId = normalizeSessionId(sessionId);
+    const sessionBytes = Buffer.from(normalizedSessionId, 'utf8');
+    const headerBytes = encodeHeader(header);
+    const payloadBytes = asBuffer(payload);
+    if (payloadBytes.length > UDP_MAX_PAYLOAD_BYTES) throw new Error('udp-packet-payload-too-large');
+
+    const preamble = Buffer.allocUnsafe(UDP_FIXED_HEADER_BYTES);
+    UDP_P2P_PROTOCOL.startsWith('livedesk') && Buffer.from('LDU1', 'ascii').copy(preamble, 0);
+    preamble[4] = UDP_P2P_VERSION;
+    preamble[5] = packetTypeCode(type);
+    preamble[6] = sessionBytes.length;
+    preamble.writeUInt16BE(headerBytes.length, 7);
+    preamble.writeUInt16BE(payloadBytes.length, 9);
+    preamble.writeUInt32BE((Number(sequence) >>> 0), 11);
+    const nonce = crypto.randomBytes(UDP_NONCE_BYTES);
+    const associatedData = Buffer.concat([preamble, nonce, sessionBytes, headerBytes]);
+    const cipher = crypto.createCipheriv('aes-256-gcm', normalizeKey(key), nonce);
+    cipher.setAAD(associatedData);
+    const encrypted = Buffer.concat([cipher.update(payloadBytes), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const packet = Buffer.concat([associatedData, encrypted, tag]);
+    if (packet.length > UDP_MAX_DATAGRAM_BYTES) throw new Error('udp-datagram-too-large');
+    return packet;
+}
+
+export function decodeUdpPacket(packet, key) {
+    const bytes = asBuffer(packet);
+    if (bytes.length < UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + UDP_TAG_BYTES) return null;
+    if (!bytes.subarray(0, 4).equals(Buffer.from('LDU1', 'ascii')) || bytes[4] !== UDP_P2P_VERSION) return null;
+    const type = UDP_PACKET_TYPE_NAMES.get(bytes[5]);
+    const sessionLength = bytes[6];
+    const headerLength = bytes.readUInt16BE(7);
+    const payloadLength = bytes.readUInt16BE(9);
+    const sequence = bytes.readUInt32BE(11);
+    const associatedLength = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES + sessionLength + headerLength;
+    const expectedLength = associatedLength + payloadLength + UDP_TAG_BYTES;
+    if (!type || sessionLength < 1 || sessionLength > UDP_MAX_SESSION_ID_BYTES
+        || headerLength > UDP_MAX_HEADER_BYTES || payloadLength > UDP_MAX_PAYLOAD_BYTES
+        || expectedLength !== bytes.length) return null;
+
+    const associatedData = bytes.subarray(0, associatedLength);
+    const sessionStart = UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES;
+    const sessionId = bytes.subarray(sessionStart, sessionStart + sessionLength).toString('utf8');
+    const headerStart = sessionStart + sessionLength;
+    let header;
+    try {
+        header = JSON.parse(bytes.subarray(headerStart, headerStart + headerLength).toString('utf8'));
+    } catch {
+        return null;
+    }
+    const nonce = bytes.subarray(UDP_FIXED_HEADER_BYTES, UDP_FIXED_HEADER_BYTES + UDP_NONCE_BYTES);
+    const ciphertextStart = associatedLength;
+    const ciphertext = bytes.subarray(ciphertextStart, ciphertextStart + payloadLength);
+    const tag = bytes.subarray(ciphertextStart + payloadLength);
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-gcm', normalizeKey(key), nonce);
+        decipher.setAAD(associatedData);
+        decipher.setAuthTag(tag);
+        const payload = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return { type, sessionId, sequence, header, payload };
+    } catch {
+        return null;
+    }
+}
+
+export class UdpReplayWindow {
+    constructor(size = 512) {
+        this.size = Math.max(32, Math.min(4096, Math.floor(Number(size) || 512)));
+        this.highest = -1;
+        this.seen = new Set();
+    }
+
+    accept(sequence) {
+        const value = Number(sequence) >>> 0;
+        if (this.highest >= 0 && value + this.size < this.highest) return false;
+        if (this.seen.has(value)) return false;
+        this.seen.add(value);
+        if (this.highest < 0 || value > this.highest) this.highest = value;
+        const minimum = Math.max(0, this.highest - this.size);
+        for (const item of this.seen) {
+            if (item < minimum) this.seen.delete(item);
+        }
+        return true;
+    }
+}
+
+export class UdpFrameReassembler {
+    constructor({ maxPending = 2, timeoutMs = 80, maxFrameBytes = 8 * 1024 * 1024 } = {}) {
+        this.maxPending = Math.max(1, Math.min(16, Math.floor(Number(maxPending) || 2)));
+        this.timeoutMs = Math.max(20, Math.min(2000, Math.floor(Number(timeoutMs) || 80)));
+        this.maxFrameBytes = Math.max(64 * 1024, Math.min(16 * 1024 * 1024, Math.floor(Number(maxFrameBytes) || 8 * 1024 * 1024)));
+        this.pending = new Map();
+    }
+
+    ingest(packet, now = Date.now()) {
+        if (!packet || packet.type !== 'frame') return null;
+        this.expire(now);
+        const header = packet.header && typeof packet.header === 'object' ? packet.header : {};
+        const frameId = String(header.frameId || '').slice(0, 160);
+        const chunkIndex = Number(header.chunkIndex);
+        const chunkCount = Number(header.chunkCount);
+        if (!frameId || !Number.isInteger(chunkIndex) || !Number.isInteger(chunkCount)
+            || chunkIndex < 0 || chunkCount < 1 || chunkCount > 4096 || chunkIndex >= chunkCount) return null;
+        let state = this.pending.get(frameId);
+        if (!state) {
+            while (this.pending.size >= this.maxPending) {
+                const oldest = this.pending.keys().next().value;
+                if (oldest === undefined) break;
+                this.pending.delete(oldest);
+            }
+            state = { createdAt: now, chunkCount, chunks: new Array(chunkCount), received: 0, totalBytes: 0, frameHeader: null };
+            this.pending.set(frameId, state);
+        }
+        if (state.chunkCount !== chunkCount || state.chunks[chunkIndex]) return null;
+        const payload = asBuffer(packet.payload);
+        state.chunks[chunkIndex] = payload;
+        state.received += 1;
+        state.totalBytes += payload.length;
+        if (header.frameHeader && typeof header.frameHeader === 'object') state.frameHeader = header.frameHeader;
+        if (state.totalBytes > this.maxFrameBytes) {
+            this.pending.delete(frameId);
+            return null;
+        }
+        if (state.received !== state.chunkCount) return null;
+        this.pending.delete(frameId);
+        return {
+            frameId,
+            header: state.frameHeader || header.frameHeader || {},
+            payload: Buffer.concat(state.chunks, state.totalBytes)
+        };
+    }
+
+    expire(now = Date.now()) {
+        for (const [frameId, state] of this.pending) {
+            if (now - state.createdAt > this.timeoutMs) this.pending.delete(frameId);
+        }
+    }
+}
+
+export function encodeRendezvousMessage(message) {
+    const payload = Buffer.from(JSON.stringify(message && typeof message === 'object' ? message : {}), 'utf8');
+    if (payload.length > UDP_MAX_DATAGRAM_BYTES) throw new Error('rendezvous-message-too-large');
+    return payload;
+}
+
+export function decodeRendezvousMessage(payload) {
+    try {
+        const value = JSON.parse(asBuffer(payload).toString('utf8'));
+        return value && typeof value === 'object' ? value : null;
+    } catch {
+        return null;
+    }
+}

package/hub/src/transport/udp-rendezvous.js

@@ -0,0 +1,78 @@
+import dgram from 'node:dgram';
+import { decodeRendezvousMessage, encodeRendezvousMessage, UDP_MAX_DATAGRAM_BYTES } from './udp-protocol.js';
+
+function safeText(value, max = 160) {
+    return String(value || '').replace(/[\r\n\t]/g, ' ').trim().slice(0, max);
+}
+
+function normalizePort(value, fallback) {
+    const port = Number(value);
+    return Number.isInteger(port) && port >= 0 && port <= 65535 ? port : fallback;
+}
+
+export function createUdpRendezvousServer({ host = '0.0.0.0', port = 5199, log = () => {} } = {}) {
+    const socket = dgram.createSocket('udp4');
+    const rooms = new Map();
+    let started = false;
+    let boundPort = normalizePort(port, 5199);
+
+    function send(message, address, targetPort) {
+        const payload = encodeRendezvousMessage(message);
+        socket.send(payload, targetPort, address);
+    }
+
+    function onMessage(payload, rinfo) {
+        if (!Buffer.isBuffer(payload) || payload.length > UDP_MAX_DATAGRAM_BYTES) return;
+        const message = decodeRendezvousMessage(payload);
+        if (message?.type !== 'rendezvous.register') return;
+        const roomId = safeText(message.roomId, 160);
+        const role = safeText(message.role, 16).toLowerCase();
+        const token = safeText(message.token, 256);
+        if (!roomId || !token || !['hub', 'client'].includes(role)) return;
+        let room = rooms.get(roomId);
+        if (!room || room.token !== token || Date.now() - room.updatedAt > 60_000) {
+            room = { token, peers: new Map(), updatedAt: Date.now() };
+            rooms.set(roomId, room);
+        }
+        room.updatedAt = Date.now();
+        room.peers.set(role, { address: rinfo.address, port: rinfo.port });
+        const peers = [...room.peers.entries()];
+        if (peers.length < 2) return;
+        for (const [peerRole, peer] of peers) {
+            const other = peers.find(([candidateRole]) => candidateRole !== peerRole)?.[1];
+            if (!other) continue;
+            send({ type: 'rendezvous.peer', roomId, role: peerRole === 'hub' ? 'client' : 'hub', host: other.address, port: other.port }, peer.address, peer.port);
+        }
+    }
+
+    socket.on('message', onMessage);
+    socket.on('error', error => log(`UDP rendezvous error: ${error?.message || error}`));
+
+    async function start() {
+        if (started) return { host, port: boundPort };
+        await new Promise((resolve, reject) => {
+            const onError = error => { socket.off('listening', onListening); reject(error); };
+            const onListening = () => { socket.off('error', onError); resolve(); };
+            socket.once('error', onError);
+            socket.once('listening', onListening);
+            socket.bind(boundPort, host);
+        });
+        started = true;
+        boundPort = socket.address().port;
+        log(`UDP rendezvous listening on udp://${host}:${boundPort}`);
+        return { host, port: boundPort };
+    }
+
+    async function close() {
+        rooms.clear();
+        if (!started) return;
+        await new Promise(resolve => socket.close(() => resolve()));
+        started = false;
+    }
+
+    return {
+        start,
+        close,
+        getStatus: () => ({ started, host, port: boundPort, rooms: rooms.size })
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livedesk",
-  "version": "0.1.284",
+  "version": "0.1.286",
   "description": "LiveDesk Hub and client launcher",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "@livedesk/client": "0.1.142",
+    "@livedesk/client": "0.1.143",
     "@openai/codex-sdk": "0.144.5",
     "cors": "^2.8.5",
     "express": "^4.21.2",