@livedesk/hub 0.1.25 → 0.1.27

package/src/server.js

@@ -1303,7 +1303,7 @@ function isPrivateHubHostname(value) {
   return !!match && Number(match[2]) >= 16 && Number(match[2]) <= 31;
 }
 
-function isLoopbackAddress(value) {
+function isLoopbackAddress(value) {
   const address = String(value || '').trim().toLowerCase();
   return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
 }
@@ -1449,6 +1449,31 @@ function normalizeDeviceIds(value) {
   return ids;
 }
 
+function requireLocalTransportDiagnosticRequest(req, res) {
+  const forwardedFor = String(req.headers['x-forwarded-for'] || '').trim();
+  const forwardedHost = String(req.headers['x-forwarded-host'] || '').trim();
+  const browserOrigin = String(req.headers.origin || '').trim();
+  const browserFetchSite = String(req.headers['sec-fetch-site'] || '').trim();
+  if (!isLoopbackAddress(req.socket?.remoteAddress)
+    || !isLoopbackHostname(requestHostname(req))
+    || forwardedFor
+    || forwardedHost
+    || browserOrigin
+    || browserFetchSite) {
+    res.status(403).json({ ok: false, error: 'transport-diagnostic-loopback-only' });
+    return false;
+  }
+  if (runtimeRole !== 'hub') {
+    res.status(403).json({ ok: false, error: 'role-not-allowed' });
+    return false;
+  }
+  return true;
+}
+
+function transportDiagnosticToken(req) {
+  return String(req.headers['x-livedesk-diagnostic-token'] || '').trim();
+}
+
 function rejectRetiredAgentTaskRequest(req, res) {
   const body = req.body && typeof req.body === 'object' ? req.body : {};
   const approvalLevel = String(body.approvalLevel || '').trim().toLowerCase();
@@ -2112,6 +2137,10 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
       ? frame.nativeEncoderHardwareAccelerated
       : null,
     nativeEncoderHardwareQueryStatus: frame.nativeEncoderHardwareQueryStatus || '',
+    nativeCaptureDisplayId: Number.isSafeInteger(Number(frame.nativeCaptureDisplayId))
+      && Number(frame.nativeCaptureDisplayId) > 0
+      ? Number(frame.nativeCaptureDisplayId)
+      : 0,
     nativeCaptureFps: Number(frame.nativeCaptureFps || 0) || 0,
     nativeCompressionFps: Number(frame.nativeCompressionFps || 0) || 0,
     nativeEncodedFps: Number(frame.nativeEncodedFps || 0) || 0,
@@ -3093,7 +3122,7 @@ app.post('/api/settings/agent/summary', async (req, res) => {
   }
 });
 
-app.get('/api/remote/status', (_req, res) => {
+app.get('/api/remote/status', (_req, res) => {
   noStore(res);
   if (runtimeRole !== 'hub') {
     res.status(403).json({ ok: false, error: 'role-not-allowed' });
@@ -3111,9 +3140,134 @@ app.get('/api/remote/status', (_req, res) => {
     agentPackage: '@livedesk/client',
     update: getLiveDeskUpdateStatus()
   });
-});
-
-app.get('/api/runtime/status', (_req, res) => {
+});
+
+app.post('/api/remote/diagnostics/transport/start', async (req, res) => {
+  noStore(res);
+  if (!requireLocalTransportDiagnosticRequest(req, res)) return;
+  const requestController = new AbortController();
+  let responseFinished = false;
+  let issuedLease = null;
+  let releaseIssuedLeasePromise = null;
+  const detachResponseLifecycle = () => {
+    res.off('finish', markResponseFinished);
+    res.off('close', abortPendingStart);
+  };
+  const releaseIssuedLease = reason => {
+    if (!issuedLease?.leaseId || !issuedLease?.token) {
+      return releaseIssuedLeasePromise || Promise.resolve(null);
+    }
+    if (!releaseIssuedLeasePromise) {
+      const lease = issuedLease;
+      releaseIssuedLeasePromise = Promise.resolve(remoteHub.stopTransportDiagnostic(
+        lease.leaseId,
+        lease.token,
+        reason
+      )).catch(() => null);
+    }
+    return releaseIssuedLeasePromise;
+  };
+  const markResponseFinished = () => {
+    responseFinished = true;
+    issuedLease = null;
+    detachResponseLifecycle();
+  };
+  const abortPendingStart = () => {
+    if (responseFinished) return;
+    requestController.abort();
+    void releaseIssuedLease('start-response-closed');
+    detachResponseLifecycle();
+  };
+  res.once('finish', markResponseFinished);
+  res.once('close', abortPendingStart);
+  try {
+    const result = await remoteHub.startTransportDiagnostic(
+      String(req.body?.deviceId || ''),
+      Number(req.body?.ttlMs || 0),
+      { signal: requestController.signal });
+    if (result?.leaseId && result?.token) {
+      issuedLease = {
+        leaseId: result.leaseId,
+        token: result.token
+      };
+    }
+    if (requestController.signal.aborted) {
+      await releaseIssuedLease('start-response-closed');
+      return;
+    }
+    res.status(result.ok ? 200 : 409).json(result);
+  } catch (error) {
+    if (requestController.signal.aborted) return;
+    res.status(500).json({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  } finally {
+    if (res.writableFinished) {
+      markResponseFinished();
+    } else if (requestController.signal.aborted) {
+      detachResponseLifecycle();
+    }
+  }
+});
+
+app.get('/api/remote/diagnostics/transport/:leaseId', (req, res) => {
+  noStore(res);
+  if (!requireLocalTransportDiagnosticRequest(req, res)) return;
+  const token = transportDiagnosticToken(req);
+  if (!token) {
+    res.status(401).json({ ok: false, error: 'transport-diagnostic-token-required' });
+    return;
+  }
+  const result = remoteHub.getTransportDiagnostic(req.params.leaseId, token);
+  res.status(result.ok ? 200 : 404).json(result);
+});
+
+app.post('/api/remote/diagnostics/transport/:leaseId/phase', async (req, res) => {
+  noStore(res);
+  if (!requireLocalTransportDiagnosticRequest(req, res)) return;
+  const token = transportDiagnosticToken(req);
+  if (!token) {
+    res.status(401).json({ ok: false, error: 'transport-diagnostic-token-required' });
+    return;
+  }
+  try {
+    const result = await remoteHub.setTransportDiagnosticPhase(
+      req.params.leaseId,
+      token,
+      String(req.body?.phase || ''));
+    res.status(result.ok ? 200 : 409).json(result);
+  } catch (error) {
+    res.status(500).json({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+});
+
+app.delete('/api/remote/diagnostics/transport/:leaseId', async (req, res) => {
+  noStore(res);
+  if (!requireLocalTransportDiagnosticRequest(req, res)) return;
+  const token = transportDiagnosticToken(req);
+  if (!token) {
+    res.status(401).json({ ok: false, error: 'transport-diagnostic-token-required' });
+    return;
+  }
+  try {
+    const result = await remoteHub.stopTransportDiagnostic(
+      req.params.leaseId,
+      token,
+      String(req.body?.reason || 'runner-complete'));
+    res.status(result.ok ? 200 : 409).json(result);
+  } catch (error) {
+    res.status(500).json({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+});
+
+app.get('/api/runtime/status', (_req, res) => {
   noStore(res);
   res.json({ ok: true, ...hubRuntimeStatus(runtimeManager, { role: runtimeRole, deviceId: runtimeDeviceId, deviceName: runtimeDeviceName, roleSource: runtimeRoleSource }) });
 });

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

@@ -36,6 +36,27 @@ function normalizedAddress(value) {
     return address.startsWith('::ffff:') ? address.slice(7) : address;
 }
 
+function isPublicIPv4(value) {
+    const address = normalizedAddress(value);
+    const octets = address.split('.').map(Number);
+    if (octets.length !== 4
+        || octets.some(octet => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        return false;
+    }
+    const [a, b] = octets;
+    const c = octets[2];
+    return a !== 0
+        && a !== 10
+        && a !== 127
+        && !(a === 100 && b >= 64 && b <= 127)
+        && !(a === 169 && b === 254)
+        && !(a === 172 && b >= 16 && b <= 31)
+        && !(a === 192 && (b === 0 || b === 168 || (b === 88 && c === 99)))
+        && !(a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100)))
+        && !(a === 203 && b === 0 && c === 113)
+        && !(a >= 224);
+}
+
 export function createHubUdpTransport({ env = process.env, logEvent = () => {}, logWarn = () => {} } = {}) {
     const enabled = isEnabled(env.LIVEDESK_UDP_ENABLED, true);
     const preferP2p = isEnabled(env.LIVEDESK_UDP_PREFER_P2P, false);
@@ -182,9 +203,21 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         const session = [...sessions.values()].find(item => item.sessionId === safeText(message.roomId, 160));
         if (!session || message.protocol !== UDP_P2P_PROTOCOL || !isTrustedRendezvousSource(rinfo)) 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 };
+        const port = Number(message.port);
+        if (!address || !Number.isInteger(port) || port < 1 || port > 65535) return;
+        const observedAddress = normalizedAddress(message.observedHost);
+        const observedPort = Number(message.observedPort);
+        if (observedAddress
+            && Number.isInteger(observedPort)
+            && observedPort >= 1
+            && observedPort <= 65535) {
+            session.hubRendezvousEndpoint = {
+                address: observedAddress,
+                port: observedPort
+            };
+            session.hubRendezvousObservedAt = Date.now();
+        }
+        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}` });
@@ -230,7 +263,7 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         if (!complete) return;
         session.framesReceived += 1;
         const reassembly = session.reassembler.getStats();
-        frameHandler({
+        const handled = frameHandler({
             deviceId: session.deviceId,
             sessionId: session.sessionId,
             header: {
@@ -243,11 +276,34 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             },
             payload: complete.payload,
             transport: 'udp-p2p'
-        });
-        sendPacket(session, 'pong', {
-            state: 'frame-ack',
-            frameSeq: Number(complete.header?.frameSeq || 0) || 0
-        });
+        });
+        const accepted = handled === true || handled?.accepted === true;
+        const proofId = safeText(complete.header?.frameTransportProofId, 96);
+        if (proofId) {
+            if (handled?.suppressProofResponse === true) return;
+            const proofAccepted = accepted && handled?.proofAccepted === true;
+            sendPacket(session, 'pong', {
+                state: proofAccepted ? 'frame-proof-ack' : 'frame-proof-reject',
+                proofId,
+                protocol: 'livedesk.frame-transport-proof.v1',
+                streamId: safeText(complete.header?.streamId, 128),
+                commandId: safeText(complete.header?.commandId, 128),
+                captureGeneration: Number(complete.header?.captureGeneration || 0) || 0,
+                monitorIndex: Number(complete.header?.monitorIndex ?? -1),
+                error: proofAccepted ? '' : safeText(handled?.error || 'frame-proof-rejected', 160)
+            });
+            return;
+        }
+        if (accepted) {
+            sendPacket(session, 'pong', {
+                state: 'frame-ack',
+                frameSeq: Number(complete.header?.frameSeq || 0) || 0,
+                streamId: safeText(complete.header?.streamId, 128),
+                commandId: safeText(complete.header?.commandId, 128),
+                captureGeneration: Number(complete.header?.captureGeneration || 0) || 0,
+                monitorIndex: Number(complete.header?.monitorIndex ?? -1)
+            });
+        }
     });
     socket.on('error', error => logWarn('udp', `UDP socket error: ${error?.message || error}`));
 
@@ -290,6 +346,8 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             sendControl,
             clientEndpoint: null,
             peerEndpoint: null,
+            hubRendezvousEndpoint: null,
+            hubRendezvousObservedAt: 0,
             replay: new UdpReplayWindow(),
             reassembler: new UdpFrameReassembler({ maxPending: maxPendingFrames, timeoutMs: frameTimeoutMs }),
             ready: false,
@@ -327,7 +385,7 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         emit('UdpSessionClosed', { deviceId: id, reason: 'tcp-session-closed' });
     }
 
-    function getDeviceStatus(deviceId) {
+    function getDeviceStatus(deviceId) {
         const session = sessions.get(safeText(deviceId, 160));
         if (!session) return { enabled, state: enabled ? 'disabled' : 'tcp-only', ready: false };
         return {
@@ -340,7 +398,72 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
             framesReceived: session.framesReceived,
             ...session.reassembler.getStats()
         };
-    }
+    }
+
+    async function refreshDeviceDiagnosticNetwork(deviceId, { timeoutMs = 3_000 } = {}) {
+        const session = sessions.get(safeText(deviceId, 160));
+        if (!session || !started || !rendezvousHost) return false;
+        const requestedAt = Date.now();
+        await resolveRendezvousAddresses();
+        if (!sendRendezvousRegister(session)) return false;
+        const deadline = requestedAt + numberEnv(timeoutMs, 250, 5_000, 3_000);
+        while (Date.now() < deadline) {
+            if (session.hubRendezvousObservedAt >= requestedAt) return true;
+            await new Promise(resolve => {
+                const timer = setTimeout(resolve, 40);
+                timer.unref?.();
+            });
+        }
+        return false;
+    }
+
+    function getDeviceDiagnosticNetwork(deviceId, { salt = '' } = {}) {
+        const session = sessions.get(safeText(deviceId, 160));
+        const clientAddress = normalizedAddress(session?.clientEndpoint?.address);
+        const normalizedHubAddress = normalizedAddress(session?.hubRendezvousEndpoint?.address);
+        const hubAddressObservedAt = session?.hubRendezvousObservedAt
+            ? new Date(session.hubRendezvousObservedAt).toISOString()
+            : '';
+        const digest = value => value
+            ? crypto.createHash('sha256')
+                .update(`${safeText(salt, 160)}:${value}`)
+                .digest('hex')
+                .slice(0, 16)
+            : '';
+        if (!session?.ready || !clientAddress) {
+            return {
+                evidence: 'authenticated-udp-endpoint-unavailable',
+                differentPublicEgress: null,
+                clientAddressHash: '',
+                hubAddressHash: digest(normalizedHubAddress),
+                hubAddressObservedAt,
+                hubEndpointSource: normalizedHubAddress
+                    ? 'trusted-rendezvous-observation'
+                    : 'unavailable'
+            };
+        }
+        const clientAddressPublic = isPublicIPv4(clientAddress);
+        const hubAddressPublic = isPublicIPv4(normalizedHubAddress);
+        return {
+            evidence: normalizedHubAddress
+                ? 'authenticated-udp-endpoint-rendezvous-observed'
+                : 'authenticated-udp-endpoint-hub-egress-unavailable',
+            differentPublicEgress: clientAddressPublic && hubAddressPublic
+                ? clientAddress !== normalizedHubAddress
+                : null,
+            clientAddressHash: digest(clientAddress),
+            hubAddressHash: digest(normalizedHubAddress),
+            clientAddressPublic,
+            hubAddressPublic,
+            endpointAuthenticated: true,
+            udpReady: session.ready === true,
+            observedAt: session.lastPacketAt ? new Date(session.lastPacketAt).toISOString() : '',
+            hubAddressObservedAt,
+            hubEndpointSource: normalizedHubAddress
+                ? 'trusted-rendezvous-observation'
+                : 'unavailable'
+        };
+    }
 
     async function close() {
         stopRendezvousRefreshTimer();
@@ -354,9 +477,11 @@ export function createHubUdpTransport({ env = process.env, logEvent = () => {},
         start,
         close,
         registerDevice,
-        unregisterDevice,
-        getDeviceStatus,
-        getStatus,
+        unregisterDevice,
+        getDeviceStatus,
+        refreshDeviceDiagnosticNetwork,
+        getDeviceDiagnosticNetwork,
+        getStatus,
         setFrameHandler: handler => { frameHandler = typeof handler === 'function' ? handler : () => {}; },
         setEventHandler: handler => { eventHandler = typeof handler === 'function' ? handler : () => {}; }
     };

package/src/transport/udp-rendezvous.js

@@ -300,7 +300,9 @@ export function createUdpRendezvousServer({
             roomId,
             role: 'client',
             host: client.address,
-            port: client.port
+            port: client.port,
+            observedHost: hub.address,
+            observedPort: hub.port
         }, hub.address, hub.port);
         send({
             type: 'rendezvous.peer',
@@ -308,7 +310,9 @@ export function createUdpRendezvousServer({
             roomId,
             role: 'hub',
             host: hub.address,
-            port: hub.port
+            port: hub.port,
+            observedHost: client.address,
+            observedPort: client.port
         }, client.address, client.port);
     }