@livedesk/hub 0.1.3 → 0.1.5

package/src/settings/effective-device-policy.js

@@ -0,0 +1,16 @@
+import { effectiveDevicePolicy } from './settings-schema.js';
+
+export function buildEffectiveDevicePolicy(settings, { deviceId = '', capabilities = {} } = {}) {
+  const policy = effectiveDevicePolicy(settings);
+  return {
+    ...policy,
+    deviceId: String(deviceId || ''),
+    supported: {
+      control: capabilities.control !== false,
+      clipboardText: capabilities.clipboardText !== false,
+      fileTransfer: capabilities.fileTransfer !== false,
+      remoteAudio: capabilities.audio === true || capabilities.remoteAudio === true,
+      agent: Array.isArray(capabilities.agentTools) && capabilities.agentTools.length > 0
+    }
+  };
+}

package/src/settings/settings-schema.js

@@ -0,0 +1,251 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const SETTINGS_SCHEMA_VERSION = 1;
+
+export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
+  settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
+  connection: {
+    usePinToAddDevices: true,
+    pinValidityMinutes: 30,
+    rotatePinAfterPairing: true,
+    allowNewDevices: true,
+    approveNewDevices: true,
+    startWithComputer: true,
+    keepRunningInTray: true,
+    showConnectionNotifications: true
+  },
+  security: {
+    accessMode: 'trusted-only',
+    requireEncryptedConnections: true,
+    allowInternetConnections: false,
+    allowLanConnections: true,
+    allowUnencryptedLanFallback: false,
+    requireNewDeviceApproval: true,
+    requireAdministratorForSecurityChanges: true,
+    visibleControlIndicator: true,
+    lockOnControlEnd: true,
+    disconnectIdleControlSessions: true,
+    idleControlMinutes: 30,
+    keepSessionHistory: true,
+    sessionHistoryDays: 30
+  },
+  control: {
+    allowKeyboardMouse: true,
+    allowSystemShortcuts: true,
+    allowClipboardText: true,
+    allowRemoteRestart: false,
+    reconnectAfterRemoteRestart: true,
+    allowSwitchingMonitors: true,
+    showConnectionToolbar: true,
+    showRemoteCursor: true,
+    openControlOnDoubleClick: true,
+    startRemoteAudioWithControl: false,
+    fitRemoteScreen: true,
+    rememberLastMonitor: true,
+    keepControlReadyBetweenPages: true
+  },
+  wall: {
+    performanceMode: 'auto',
+    autoStart: true,
+    connectedOnly: false,
+    keepEmptySlots: true,
+    showDeviceStatus: true,
+    showPerformanceDetails: false,
+    pauseHiddenTiles: true,
+    reduceWhenHidden: true,
+    autoAdjustTileQuality: true,
+    rememberDevicePositions: true
+  },
+  filesAudio: {
+    allowFileTransfer: true,
+    allowFolderSync: false,
+    askBeforeReceivingFiles: true,
+    openReceivedFolder: false,
+    notifyTransferComplete: true,
+    allowOverwrite: false,
+    defaultReceiveFolder: 'Desktop/LiveDeskFiles',
+    maxFileSizeBytes: 1024 * 1024 * 1024,
+    allowRemoteAudio: true,
+    startAudioMuted: false,
+    rememberVolume: true,
+    automaticallyRecoverAudio: true,
+    showAudioTroubleshooting: false,
+    rollingBufferEnabled: false,
+    recordingQuality: 'standard',
+    timelapseIntervalSeconds: 10,
+    includeRemoteCursor: true,
+    captureSaveLocation: 'LiveDesk Captures',
+    captureAutoDelete: 'never'
+  },
+  agent: {
+    enabled: false,
+    defaultPermissionMode: 'safe-auto',
+    askBeforeDestructive: true,
+    allowProcessManagement: true,
+    allowServiceManagement: true,
+    allowFileChanges: true,
+    allowCommandExecution: false,
+    allowSoftwareInstallation: false,
+    allowPowerActions: false,
+    keepAuditHistory: true,
+    timeoutMinutes: 10
+  },
+  advanced: {
+    wallFrameMode: 'auto',
+    wallFps: 20,
+    wallMaxWidth: 960,
+    wallMaxHeight: 540,
+    wallQuality: 55,
+    controlFrameMode: 'mode3-h264-hw',
+    controlFps: 30,
+    controlMaxWidth: 1920,
+    controlMaxHeight: 1080,
+    controlQuality: 60,
+    transport: 'auto',
+    allowPlainLanFallback: false,
+    verboseLogs: false,
+    frameStatistics: false
+  }
+});
+
+const ENUMS = {
+  accessMode: new Set(['trusted-only', 'ask-every-time', 'view-only', 'block-remote-access']),
+  performanceMode: new Set(['auto', 'responsive', 'quality', 'custom']),
+  permissionMode: new Set(['ask', 'safe-auto', 'full-access', 'custom']),
+  wallFrameMode: new Set(['auto', 'mode2-lzo', 'mode3-h264-hw', 'mode4-h264-atlas']),
+  controlFrameMode: new Set(['mode3-h264-hw', 'mode5-lzo-delta']),
+  transport: new Set(['auto', 'encrypted', 'plain-lan']),
+  recordingQuality: new Set(['standard', 'high']),
+  captureAutoDelete: new Set(['never', '7-days', '30-days'])
+};
+
+function booleanValue(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function numberValue(value, min, max, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, Math.round(number))) : fallback;
+}
+
+function enumValue(value, allowed, fallback) {
+  const normalized = String(value ?? fallback).trim().toLowerCase();
+  return allowed.has(normalized) ? normalized : fallback;
+}
+
+function stringValue(value, fallback, maxLength = 600) {
+  return typeof value === 'string' ? value.replace(/[\0\r\n]/g, ' ').trim().slice(0, maxLength) : fallback;
+}
+
+function normalizeSection(source, defaults, rules = {}) {
+  const input = source && typeof source === 'object' && !Array.isArray(source) ? source : {};
+  const result = {};
+  for (const [key, fallback] of Object.entries(defaults)) {
+    const rule = rules[key];
+    if (rule?.type === 'boolean') result[key] = booleanValue(input[key], fallback);
+    else if (rule?.type === 'number') result[key] = numberValue(input[key], rule.min, rule.max, fallback);
+    else if (rule?.type === 'enum') result[key] = enumValue(input[key], rule.values, fallback);
+    else if (rule?.type === 'string') result[key] = stringValue(input[key], fallback, rule.maxLength);
+    else result[key] = input[key] === undefined ? fallback : fallback;
+  }
+  return result;
+}
+
+const bools = keys => Object.fromEntries(keys.map(key => [key, { type: 'boolean' }]));
+const numbers = (entries) => Object.fromEntries(entries.map(([key, min, max]) => [key, { type: 'number', min, max }]));
+
+const RULES = {
+  connection: {
+    ...bools(['usePinToAddDevices', 'rotatePinAfterPairing', 'allowNewDevices', 'approveNewDevices', 'startWithComputer', 'keepRunningInTray', 'showConnectionNotifications']),
+    ...numbers([['pinValidityMinutes', 10, 1440]])
+  },
+  security: {
+    accessMode: { type: 'enum', values: ENUMS.accessMode },
+    ...bools(['requireEncryptedConnections', 'allowInternetConnections', 'allowLanConnections', 'allowUnencryptedLanFallback', 'requireNewDeviceApproval', 'requireAdministratorForSecurityChanges', 'visibleControlIndicator', 'lockOnControlEnd', 'disconnectIdleControlSessions', 'keepSessionHistory']),
+    ...numbers([['idleControlMinutes', 5, 1440], ['sessionHistoryDays', 7, 365]])
+  },
+  control: {
+    ...bools(['allowKeyboardMouse', 'allowSystemShortcuts', 'allowClipboardText', 'allowRemoteRestart', 'reconnectAfterRemoteRestart', 'allowSwitchingMonitors', 'showConnectionToolbar', 'showRemoteCursor', 'openControlOnDoubleClick', 'startRemoteAudioWithControl', 'fitRemoteScreen', 'rememberLastMonitor', 'keepControlReadyBetweenPages'])
+  },
+  wall: {
+    performanceMode: { type: 'enum', values: ENUMS.performanceMode },
+    ...bools(['autoStart', 'connectedOnly', 'keepEmptySlots', 'showDeviceStatus', 'showPerformanceDetails', 'pauseHiddenTiles', 'reduceWhenHidden', 'autoAdjustTileQuality', 'rememberDevicePositions'])
+  },
+  filesAudio: {
+    ...bools(['allowFileTransfer', 'allowFolderSync', 'askBeforeReceivingFiles', 'openReceivedFolder', 'notifyTransferComplete', 'allowOverwrite', 'allowRemoteAudio', 'startAudioMuted', 'rememberVolume', 'automaticallyRecoverAudio', 'showAudioTroubleshooting', 'rollingBufferEnabled', 'includeRemoteCursor']),
+    recordingQuality: { type: 'enum', values: ENUMS.recordingQuality },
+    captureAutoDelete: { type: 'enum', values: ENUMS.captureAutoDelete },
+    timelapseIntervalSeconds: { type: 'number', min: 5, max: 60 },
+    defaultReceiveFolder: { type: 'string', maxLength: 600 },
+    captureSaveLocation: { type: 'string', maxLength: 120 },
+    maxFileSizeBytes: { type: 'number', min: 1, max: Number.MAX_SAFE_INTEGER }
+  },
+  agent: {
+    defaultPermissionMode: { type: 'enum', values: ENUMS.permissionMode },
+    ...bools(['enabled', 'askBeforeDestructive', 'allowProcessManagement', 'allowServiceManagement', 'allowFileChanges', 'allowCommandExecution', 'allowSoftwareInstallation', 'allowPowerActions', 'keepAuditHistory']),
+    timeoutMinutes: { type: 'number', min: 1, max: 120 }
+  },
+  advanced: {
+    wallFrameMode: { type: 'enum', values: ENUMS.wallFrameMode },
+    controlFrameMode: { type: 'enum', values: ENUMS.controlFrameMode },
+    transport: { type: 'enum', values: ENUMS.transport },
+    ...bools(['allowPlainLanFallback', 'verboseLogs', 'frameStatistics']),
+    ...numbers([['wallFps', 1, 60], ['wallMaxWidth', 320, 3840], ['wallMaxHeight', 180, 2160], ['wallQuality', 20, 95], ['controlFps', 20, 60], ['controlMaxWidth', 640, 3840], ['controlMaxHeight', 360, 2160], ['controlQuality', 20, 95]])
+  }
+};
+
+export function normalizeLiveDeskSettings(value = {}) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const settings = {
+    settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
+    connection: normalizeSection(source.connection, DEFAULT_LIVEDESK_SETTINGS.connection, RULES.connection),
+    security: normalizeSection(source.security, DEFAULT_LIVEDESK_SETTINGS.security, RULES.security),
+    control: normalizeSection(source.control, DEFAULT_LIVEDESK_SETTINGS.control, RULES.control),
+    wall: normalizeSection(source.wall, DEFAULT_LIVEDESK_SETTINGS.wall, RULES.wall),
+    filesAudio: normalizeSection(source.filesAudio, DEFAULT_LIVEDESK_SETTINGS.filesAudio, RULES.filesAudio),
+    agent: normalizeSection(source.agent, DEFAULT_LIVEDESK_SETTINGS.agent, RULES.agent),
+    advanced: normalizeSection(source.advanced, DEFAULT_LIVEDESK_SETTINGS.advanced, RULES.advanced)
+  };
+  // Security invariants are enforced at the authority boundary, not just in
+  // the browser. Internet access can never use an unencrypted transport.
+  if (settings.security.requireEncryptedConnections) {
+    settings.security.allowUnencryptedLanFallback = false;
+  }
+  if (!settings.security.allowInternetConnections) {
+    settings.advanced.transport = settings.advanced.transport === 'encrypted' ? 'encrypted' : 'auto';
+  }
+  if (settings.agent.defaultPermissionMode === 'safe-auto') {
+    settings.agent.askBeforeDestructive = true;
+  }
+  if (![5, 10, 30, 60].includes(settings.filesAudio.timelapseIntervalSeconds)) {
+    settings.filesAudio.timelapseIntervalSeconds = 10;
+  }
+  return settings;
+}
+
+export function defaultSettingsPath(dataDir = undefined) {
+  return path.join(dataDir || path.join(os.homedir(), '.livedesk'), 'settings.json');
+}
+
+export function publicSettings(settings) {
+  return normalizeLiveDeskSettings(settings);
+}
+
+export function effectiveDevicePolicy(settings = DEFAULT_LIVEDESK_SETTINGS) {
+  const normalized = normalizeLiveDeskSettings(settings);
+  return {
+    settingsSchemaVersion: normalized.settingsSchemaVersion,
+    policyRevision: Number(settings?.revision || 0),
+    accessMode: normalized.security.accessMode,
+    allowInternetConnections: normalized.security.allowInternetConnections,
+    allowLanConnections: normalized.security.allowLanConnections,
+    requireEncryptedConnections: normalized.security.requireEncryptedConnections,
+    allowUnencryptedLanFallback: normalized.security.allowUnencryptedLanFallback,
+    allowControl: normalized.security.accessMode !== 'block-remote-access' && normalized.control.allowKeyboardMouse,
+    allowClipboardText: normalized.security.accessMode !== 'block-remote-access' && normalized.control.allowClipboardText,
+    allowFileTransfer: normalized.security.accessMode !== 'block-remote-access' && normalized.filesAudio.allowFileTransfer,
+    allowRemoteAudio: normalized.security.accessMode !== 'block-remote-access' && normalized.filesAudio.allowRemoteAudio,
+    allowAgent: normalized.security.accessMode !== 'block-remote-access' && normalized.agent.enabled
+  };
+}

package/src/settings/settings-store.js

@@ -0,0 +1,77 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_LIVEDESK_SETTINGS, defaultSettingsPath, normalizeLiveDeskSettings, publicSettings } from './settings-schema.js';
+
+export class SettingsConflictError extends Error {
+  constructor(settings) {
+    super('Settings changed in another session. Reload before saving again.');
+    this.name = 'SettingsConflictError';
+    this.code = 'settings-revision-conflict';
+    this.status = 409;
+    this.settings = settings;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  await rename(temporaryPath, filePath);
+}
+
+export class LiveDeskSettingsStore {
+  constructor({ dataDir } = {}) {
+    this.filePath = defaultSettingsPath(dataDir);
+    this.record = null;
+  }
+
+  async getRecord() {
+    if (this.record) return structuredClone(this.record);
+    try {
+      const raw = JSON.parse(await readFile(this.filePath, 'utf8'));
+      this.record = {
+        revision: Math.max(0, Number(raw?.revision) || 0),
+        updatedAt: String(raw?.updatedAt || ''),
+        settings: normalizeLiveDeskSettings(raw?.settings || raw)
+      };
+    } catch {
+      this.record = { revision: 0, updatedAt: '', settings: normalizeLiveDeskSettings(DEFAULT_LIVEDESK_SETTINGS) };
+    }
+    return structuredClone(this.record);
+  }
+
+  getCached() {
+    if (!this.record) return DEFAULT_LIVEDESK_SETTINGS;
+    return { ...this.record.settings, revision: this.record.revision };
+  }
+
+  async get() {
+    return publicSettings((await this.getRecord()).settings);
+  }
+
+  async update(patch = {}, expectedRevision = undefined) {
+    const current = await this.getRecord();
+    if (expectedRevision !== undefined && Number(expectedRevision) !== current.revision) {
+      throw new SettingsConflictError({ revision: current.revision, updatedAt: current.updatedAt, settings: publicSettings(current.settings) });
+    }
+    const source = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
+    const merged = {};
+    for (const section of Object.keys(current.settings)) {
+      if (section === 'settingsSchemaVersion') continue;
+      merged[section] = { ...current.settings[section], ...(source[section] && typeof source[section] === 'object' ? source[section] : {}) };
+    }
+    const next = {
+      revision: current.revision + 1,
+      updatedAt: new Date().toISOString(),
+      settings: normalizeLiveDeskSettings(merged)
+    };
+    await writeJsonAtomic(this.filePath, next);
+    this.record = next;
+    return structuredClone(next);
+  }
+
+  async reset() {
+    const current = await this.getRecord();
+    return this.update(normalizeLiveDeskSettings(DEFAULT_LIVEDESK_SETTINGS), current.revision);
+  }
+}

package/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
+        };
+    }
+}