@livedesk/hub 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/src/remote-hub.js

@@ -1,6 +1,7 @@
-import net from 'net';
-import os from 'os';
-import crypto from 'crypto';
+import net from 'net';
+import os from 'os';
+import crypto from 'crypto';
+import { createHubRelayControl } from './transport/relay-hub-control.js';
 
 const DEFAULT_REMOTE_HUB_PORT = 5197;
 const DEFAULT_REMOTE_HUB_HOST = '0.0.0.0';
@@ -1026,10 +1027,12 @@ function serializeDevice(device, options = {}) {
         disconnectedAt: device.disconnectedAt,
         lastSeenAt: device.lastSeenAt,
         lastStatusAt: device.lastStatusAt,
-        lastDisconnectReason: device.lastDisconnectReason,
-        remoteAddress: device.remoteAddress,
-        remotePort: device.remotePort,
-        channels: {
+        lastDisconnectReason: device.lastDisconnectReason,
+        remoteAddress: device.remoteAddress,
+        remotePort: device.remotePort,
+        controlTransport: device.controlTransport || 'direct-tcp',
+        relayEndpoint: device.relayEndpoint || '',
+        channels: {
             control: !!device.socket && !device.socket.destroyed,
             input: !!device.inputSocket && !device.inputSocket.destroyed,
             frame: !!device.frameSocket && !device.frameSocket.destroyed,
@@ -1560,9 +1563,18 @@ export function createRemoteHub(options = {}) {
     const hostInstanceId = safeString(options.hostInstanceId ?? env.LIVEDESK_HUB_INSTANCE_ID ?? env.MINDEXEC_BRIDGE_INSTANCE_ID ?? crypto.randomUUID(), 128) || crypto.randomUUID();
     const publicEndpoint = safeString(env.LIVEDESK_REMOTE_PUBLIC_ENDPOINT || env.MINDEXEC_REMOTE_PUBLIC_ENDPOINT || env.REMOTE_HUB_PUBLIC_ENDPOINT, 256);
     const publicHost = safeString(env.LIVEDESK_REMOTE_PUBLIC_HOST || env.MINDEXEC_REMOTE_PUBLIC_HOST || env.REMOTE_HUB_PUBLIC_HOST, 128);
-    const pairToken = safeString(
-        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN || crypto.randomBytes(6).toString('hex'),
-        256);
+    const pairToken = safeString(
+        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN || crypto.randomBytes(6).toString('hex'),
+        256);
+    const relayControl = options.relayControl && typeof options.relayControl === 'object'
+        ? options.relayControl
+        : createHubRelayControl({
+            env,
+            pairToken,
+            logEvent,
+            logWarn,
+            onPeerSocket: socket => handleTcpAgentSocket(socket)
+        });
     let pairingPin = /^\d{6}$/.test(String(options.pairingPin || env.LIVEDESK_PAIRING_PIN || '').trim())
         ? String(options.pairingPin || env.LIVEDESK_PAIRING_PIN).trim()
         : generatePairingPin();
@@ -1933,14 +1945,23 @@ export function createRemoteHub(options = {}) {
             publicIPv4Address: publicIPv4Cache.address,
             publicIPv4UpdatedAt: publicIPv4Cache.updatedAt ? new Date(publicIPv4Cache.updatedAt).toISOString() : '',
             publicIPv4Error: publicIPv4Cache.error,
-            udp: udpTransport?.getStatus?.() || {
-                enabled: false,
-                preferred: false,
-                started: false,
-                port: 0,
-                sessionCount: 0,
-                readySessionCount: 0
-            },
+            udp: udpTransport?.getStatus?.() || {
+                enabled: false,
+                preferred: false,
+                started: false,
+                port: 0,
+                sessionCount: 0,
+                readySessionCount: 0
+            },
+            relay: relayControl?.getStatus?.() || {
+                enabled: false,
+                started: false,
+                connected: false,
+                state: 'unavailable',
+                protocol: 'livedesk.relay.v1',
+                endpoint: '',
+                peerCount: 0
+            },
             externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
             diagnostics,
             lastError
@@ -2151,6 +2172,23 @@ export function createRemoteHub(options = {}) {
         }
     }
 
+    function failPendingCommandResultWaiter(commandId, error = 'command-not-sent') {
+        const key = safeString(commandId, 128);
+        const waiter = pendingCommandResultWaiters.get(key);
+        if (!waiter) {
+            return false;
+        }
+        pendingCommandResultWaiters.delete(key);
+        clearTimeout(waiter.timer);
+        waiter.resolve({
+            ok: false,
+            commandId: key,
+            result: null,
+            error: safeString(error, 500) || 'command-not-sent'
+        });
+        return true;
+    }
+
     function waitForCommandResult(device, commandId, timeoutMs = liveCaptureStopAckTimeoutMs) {
         const key = safeString(commandId, 128);
         if (!device?.deviceId || !device?.sessionId || !key) {
@@ -2845,9 +2883,13 @@ export function createRemoteHub(options = {}) {
         const frameModes = Array.isArray(hello.frameModes)
             ? hello.frameModes.map(normalizeIncomingFrameModeProfile).filter(Boolean)
             : [];
-        const capabilities = typeof hello.capabilities === 'object' && hello.capabilities
-            ? { ...hello.capabilities }
-            : {};
+        const capabilities = typeof hello.capabilities === 'object' && hello.capabilities
+            ? { ...hello.capabilities }
+            : {};
+        const relayConnected = socket.__liveDeskRelayControl === true;
+        if (relayConnected) {
+            capabilities.dedicatedInputChannel = false;
+        }
         if (!capabilities.frameProtocol) {
             capabilities.frameProtocol = frameProtocol || buildRemoteFrameProtocolDescriptor();
         }
@@ -2893,10 +2935,14 @@ export function createRemoteHub(options = {}) {
             disconnectedAt: '',
             lastSeenAt: now,
             lastStatusAt: '',
-            lastDisconnectReason: '',
-            remoteAddress: socket.remoteAddress || '',
-            remotePort: socket.remotePort || 0,
-            status: {},
+            lastDisconnectReason: '',
+            remoteAddress: socket.remoteAddress || '',
+            remotePort: socket.remotePort || 0,
+            controlTransport: relayConnected ? 'encrypted-rendezvous-relay' : 'direct-tcp',
+            relayEndpoint: relayConnected
+                ? safeString(socket.remoteAddress, 256)
+                : '',
+            status: {},
             latestThumbnail: null,
             latestLiveFrame: null,
             recentFramePayloads: {
@@ -4654,12 +4700,23 @@ export function createRemoteHub(options = {}) {
         scheduleAgentBinaryIngress(socket, state);
     }
 
-    function handleAgentMessage(socket, state, message) {
-        if (!message || typeof message !== 'object') {
-            return;
-        }
-
+    function handleAgentMessage(socket, state, message) {
+        if (!message || typeof message !== 'object') {
+            return;
+        }
+
         if (!state.authenticated) {
+            if (message.type === 'hello' && socket.__liveDeskRelayControl === true) {
+                message = {
+                    ...message,
+                    capabilities: {
+                        ...(message.capabilities && typeof message.capabilities === 'object'
+                            ? message.capabilities
+                            : {}),
+                        dedicatedInputChannel: false
+                    }
+                };
+            }
             if (message.type === 'slot.assign') {
                 if (!timingSafeStringEqual(message.pairToken, pairToken)) {
                     writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'invalid-pair-token' });
@@ -5230,10 +5287,15 @@ export function createRemoteHub(options = {}) {
             return getStatus({ includeSecrets: false });
         }
 
-        try {
-            await udpTransport?.start?.();
-            await listenOnPort(requestedPort);
-        } catch (error) {
+        try {
+            await udpTransport?.start?.();
+            await listenOnPort(requestedPort);
+            try {
+                await relayControl?.start?.();
+            } catch {
+                logWarn('relay', 'Encrypted relay control could not start; direct TCP remains available.');
+            }
+        } catch (error) {
             if (error?.code === 'EADDRINUSE') {
                 const conflict = new Error(
                     `LiveDesk Hub requires client endpoint TCP ${requestedPort}, but that port is already in use. Close the owning process or start Hub with an explicit --remote-port value.`);
@@ -5266,8 +5328,9 @@ export function createRemoteHub(options = {}) {
             }
         }
 
-        sockets.clear();
-        await udpTransport?.close?.();
+        sockets.clear();
+        await relayControl?.close?.();
+        await udpTransport?.close?.();
         if (!server) {
             started = false;
             return;
@@ -6790,35 +6853,100 @@ export function createRemoteHub(options = {}) {
 
         if (!device?.socket || device.socket.destroyed || !device.connected) {
             return { ok: false, error: 'device-not-connected' };
-        }
-
-        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-        const result = sendCommand(deviceId, {
-            command: 'stream.stop',
-            commandId,
+        }
+
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        // Register before writing the command. A local/relay Agent can answer
+        // quickly enough that registering after sendCommand loses the only
+        // proof that native capture actually stopped.
+        const acknowledgementPromise = waitForCommandResult(
+            device,
+            commandId,
+            liveCaptureStopAckTimeoutMs);
+        const result = sendCommand(deviceId, {
+            command: 'stream.stop',
+            commandId,
             payload: {
                 streamId,
                 requestedAt: new Date().toISOString()
             }
         });
-
-        if (!result.ok) {
-            return result;
-        }
 
-        if (streamState) {
-            streamState.active = false;
-            streamState.open = false;
-            streamState.stoppedAt = new Date().toISOString();
-            streamState.stopReason = safeString(options.reason, 128) || 'manager-request';
+        if (!result.ok) {
+            failPendingCommandResultWaiter(commandId, result.error || 'stream-stop-not-sent');
+            return result;
         }
-        device.counters.liveStreamsStopped += 1;
-        emitRemoteEvent('RemoteLiveStreamStopped', device, {
-            streamId,
-            commandId
-        });
-
-        return { ok: true, commandId, streamId };
+
+        const targetStreams = options.stopAll === true
+            ? [...ensureDeviceLiveStreams(device).values()]
+            : (streamState ? [streamState] : []);
+        for (const targetStream of targetStreams) {
+            targetStream.stopPending = true;
+            targetStream.stopCommandId = commandId;
+            targetStream.stopRequestedAt = new Date().toISOString();
+            targetStream.stopReason = safeString(options.reason, 128) || 'manager-request';
+            targetStream.stopError = '';
+            targetStream.stopUnconfirmed = false;
+        }
+        const sessionId = device.sessionId;
+        const stopPromise = acknowledgementPromise.then(acknowledgement => {
+            const currentDevice = devices.get(String(deviceId || ''));
+            const sessionCurrent = currentDevice?.sessionId === sessionId;
+            const captureStopConfirmed = acknowledgement.ok === true
+                && acknowledgement.result?.stream === true
+                && acknowledgement.result?.stopped === true;
+            const stoppedAt = new Date().toISOString();
+            if (sessionCurrent) {
+                const currentTargets = options.stopAll === true
+                    ? [...ensureDeviceLiveStreams(currentDevice).values()]
+                    : (() => {
+                        const currentStream = getDeviceLiveStream(currentDevice, streamId);
+                        return currentStream ? [currentStream] : [];
+                    })();
+                for (const targetStream of currentTargets) {
+                    if (targetStream.stopCommandId !== commandId) {
+                        continue;
+                    }
+                    targetStream.stopPending = false;
+                    targetStream.stopUnconfirmed = !captureStopConfirmed;
+                    targetStream.stopError = captureStopConfirmed
+                        ? ''
+                        : safeString(acknowledgement.error || 'capture-stop-unconfirmed', 500);
+                    if (captureStopConfirmed) {
+                        targetStream.active = false;
+                        targetStream.open = false;
+                        targetStream.stoppedAt = stoppedAt;
+                        targetStream.stopConfirmedAt = stoppedAt;
+                    }
+                }
+                if (captureStopConfirmed) {
+                    currentDevice.counters.liveStreamsStopped += 1;
+                    emitRemoteEvent('RemoteLiveStreamStopped', currentDevice, {
+                        streamId,
+                        commandId,
+                        captureStopConfirmed: true
+                    });
+                } else {
+                    emitRemoteEvent('RemoteLiveStreamStopUnconfirmed', currentDevice, {
+                        streamId,
+                        commandId,
+                        error: acknowledgement.error || 'capture-stop-unconfirmed'
+                    });
+                }
+            }
+            return {
+                ...acknowledgement,
+                streamId,
+                captureStopConfirmed
+            };
+        });
+
+        const stopResult = { ok: true, commandId, streamId, stopPending: true };
+        Object.defineProperty(stopResult, 'stopPromise', {
+            value: stopPromise,
+            enumerable: false
+        });
+        return stopResult;
     }
 
     function buildLiveCapturePauseResult(pause, extra = {}) {
@@ -6884,10 +7012,14 @@ export function createRemoteHub(options = {}) {
         if (pause.stopCommandId
             && stopResult.alreadyStopped !== true
             && stopResult.synthetic !== true) {
-            const acknowledgement = await waitForCommandResult(
-                device,
-                pause.stopCommandId,
-                liveCaptureStopAckTimeoutMs);
+            const acknowledgement = stopResult.stopPromise
+                ? await stopResult.stopPromise
+                : {
+                    ok: false,
+                    commandId: pause.stopCommandId,
+                    result: null,
+                    error: 'capture-stop-confirmation-missing'
+                };
             device = devices.get(String(deviceId || '')) || device;
             if (device.liveCapturePause?.token !== pause.token) {
                 return buildLiveCapturePauseResult(pause, {
@@ -6999,6 +7131,14 @@ export function createRemoteHub(options = {}) {
         if (!pause?.token) {
             return { ok: true, paused: false, alreadyResumed: true };
         }
+        const pauseToken = safeString(options.pauseToken, 128);
+        if (!pauseToken || pauseToken !== pause.token) {
+            return {
+                ok: false,
+                paused: true,
+                error: 'LIVE_CAPTURE_PAUSE_TOKEN_MISMATCH'
+            };
+        }
         if (pause.phase === 'pausing') {
             return {
                 ok: false,
@@ -7007,12 +7147,19 @@ export function createRemoteHub(options = {}) {
                 pauseToken: pause.token
             };
         }
-        const pauseToken = safeString(options.pauseToken, 128);
-        if (!pauseToken || pauseToken !== pause.token) {
-            return {
+        if (pause.captureStopConfirmed !== true) {
+            return buildLiveCapturePauseResult(pause, {
                 ok: false,
-                error: 'LIVE_CAPTURE_PAUSE_TOKEN_MISMATCH'
-            };
+                paused: true,
+                error: 'LIVE_CAPTURE_STOP_UNCONFIRMED'
+            });
+        }
+        if (pause.phase !== 'paused') {
+            return buildLiveCapturePauseResult(pause, {
+                ok: false,
+                paused: true,
+                error: 'LIVE_CAPTURE_PAUSE_PHASE_MISMATCH'
+            });
         }
 
         device.liveCapturePause = null;
@@ -7101,32 +7248,81 @@ export function createRemoteHub(options = {}) {
         }
         if (device.synthetic === true || !device.socket || device.socket.destroyed) {
             return { ok: false, error: 'device-audio-unavailable' };
-        }
-        const streamId = safeString(options.streamId, 128) || device.activeAudioStream?.streamId || '';
-        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-        const result = sendCommand(deviceId, {
-            command: 'audio.stop',
+        }
+        const streamId = safeString(options.streamId, 128) || device.activeAudioStream?.streamId || '';
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const acknowledgementPromise = waitForCommandResult(
+            device,
+            commandId,
+            liveCaptureStopAckTimeoutMs);
+        const result = sendCommand(deviceId, {
+            command: 'audio.stop',
             commandId,
             payload: {
                 streamId,
                 requestedAt: new Date().toISOString()
             }
-        });
-        if (!result.ok) {
-            return result;
-        }
-        if (device.activeAudioStream && (!streamId || device.activeAudioStream.streamId === streamId)) {
-            device.activeAudioStream.active = false;
-            device.activeAudioStream.stoppedAt = new Date().toISOString();
-            device.activeAudioStream.stopReason = 'manager-request';
-        }
-        device.counters.audioStreamsStopped += 1;
-        emitRemoteEvent('RemoteAudioStreamStopped', device, {
-            streamId,
-            commandId
-        });
-        return { ok: true, commandId, streamId };
-    }
+        });
+        if (!result.ok) {
+            failPendingCommandResultWaiter(commandId, result.error || 'audio-stop-not-sent');
+            return result;
+        }
+        if (device.activeAudioStream && (!streamId || device.activeAudioStream.streamId === streamId)) {
+            device.activeAudioStream.stopPending = true;
+            device.activeAudioStream.stopCommandId = commandId;
+            device.activeAudioStream.stopRequestedAt = new Date().toISOString();
+            device.activeAudioStream.stopReason = 'manager-request';
+            device.activeAudioStream.stopError = '';
+            device.activeAudioStream.stopUnconfirmed = false;
+        }
+        const sessionId = device.sessionId;
+        const stopPromise = acknowledgementPromise.then(acknowledgement => {
+            const currentDevice = devices.get(String(deviceId || ''));
+            const audioStopConfirmed = acknowledgement.ok === true
+                && acknowledgement.result?.audio === true
+                && acknowledgement.result?.stopped === true;
+            if (currentDevice?.sessionId === sessionId
+                && currentDevice.activeAudioStream
+                && currentDevice.activeAudioStream.stopCommandId === commandId
+                && (!streamId || currentDevice.activeAudioStream.streamId === streamId)) {
+                const stoppedAt = new Date().toISOString();
+                currentDevice.activeAudioStream.stopPending = false;
+                currentDevice.activeAudioStream.stopUnconfirmed = !audioStopConfirmed;
+                currentDevice.activeAudioStream.stopError = audioStopConfirmed
+                    ? ''
+                    : safeString(acknowledgement.error || 'audio-stop-unconfirmed', 500);
+                if (audioStopConfirmed) {
+                    currentDevice.activeAudioStream.active = false;
+                    currentDevice.activeAudioStream.open = false;
+                    currentDevice.activeAudioStream.stoppedAt = stoppedAt;
+                    currentDevice.activeAudioStream.stopConfirmedAt = stoppedAt;
+                    currentDevice.counters.audioStreamsStopped += 1;
+                    emitRemoteEvent('RemoteAudioStreamStopped', currentDevice, {
+                        streamId,
+                        commandId,
+                        captureStopConfirmed: true
+                    });
+                } else {
+                    emitRemoteEvent('RemoteAudioStreamStopUnconfirmed', currentDevice, {
+                        streamId,
+                        commandId,
+                        error: acknowledgement.error || 'audio-stop-unconfirmed'
+                    });
+                }
+            }
+            return {
+                ...acknowledgement,
+                streamId,
+                captureStopConfirmed: audioStopConfirmed
+            };
+        });
+        const stopResult = { ok: true, commandId, streamId, stopPending: true };
+        Object.defineProperty(stopResult, 'stopPromise', {
+            value: stopPromise,
+            enumerable: false
+        });
+        return stopResult;
+    }
 
     function getDeviceLiveFrame(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));