@livedesk/hub 0.1.25 → 0.1.26

package/package.json

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

package/src/remote-hub.js

@@ -31,6 +31,17 @@ const LIVE_STREAM_MIN_FRESH_MS = 3000;
 const LIVE_STREAM_MAX_FRESH_MS = 12000;
 const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
 const DEFAULT_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS = 8000;
+const TRANSPORT_DIAGNOSTIC_MIN_TTL_MS = 15_000;
+const TRANSPORT_DIAGNOSTIC_MAX_TTL_MS = 180_000;
+const TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS = 8_000;
+const TRANSPORT_DIAGNOSTIC_RECORD_RETENTION_MS = 60_000;
+const TRANSPORT_DIAGNOSTIC_MAX_RECORDS = 32;
+const TRANSPORT_DIAGNOSTIC_PHASES = Object.freeze([
+    'direct',
+    'p2p',
+    'relay',
+    'recover-direct'
+]);
 const REMOTE_POLICY_BYPASS_COMMANDS = new Set([
     'ping',
     'stream.stop',
@@ -429,13 +440,23 @@ function isPublicIPv4(value) {
         return false;
     }
 
-    if (parts[0] === 192 && (parts[1] === 0 || parts[1] === 168)) {
-        return false;
-    }
-
-    if (parts[0] === 198 && (parts[1] === 18 || parts[1] === 19)) {
-        return false;
-    }
+    if (parts[0] === 192
+        && (parts[1] === 0
+            || parts[1] === 168
+            || (parts[1] === 88 && parts[2] === 99))) {
+        return false;
+    }
+
+    if (parts[0] === 198
+        && (parts[1] === 18
+            || parts[1] === 19
+            || (parts[1] === 51 && parts[2] === 100))) {
+        return false;
+    }
+
+    if (parts[0] === 203 && parts[1] === 0 && parts[2] === 113) {
+        return false;
+    }
 
     return true;
 }
@@ -1528,6 +1549,11 @@ class RemoteHubWebSocketAgentSocket {
 
 export function createRemoteHub(options = {}) {
     const env = options.env || process.env;
+    const transportDiagnosticCommandTimeoutMs = clampNumber(
+        options.transportDiagnosticCommandTimeoutMs,
+        25,
+        TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS,
+        TRANSPORT_DIAGNOSTIC_COMMAND_TIMEOUT_MS);
     const rejectFrameChannelForTest = isEnabledValue(env.LIVEDESK_TEST_MODE, false)
         && isEnabledValue(env.LIVEDESK_TEST_REJECT_FRAME_CHANNEL, false);
     const logEvent = options.logEvent || (() => {});
@@ -1631,7 +1657,9 @@ export function createRemoteHub(options = {}) {
     const fileSockets = new Map();
     const allSockets = new Set();
     const pendingCommandResultWaiters = new Map();
-    const duplicateDeviceLogAt = new Map();
+    const transportDiagnostics = new Map();
+    const transportDiagnosticStartingDevices = new Set();
+    const duplicateDeviceLogAt = new Map();
     let server = null;
     let started = false;
     let boundPort = requestedPort;
@@ -2266,6 +2294,700 @@ export function createRemoteHub(options = {}) {
         });
     }
 
+    function inspectAnnexBH264(payload) {
+        if (!Buffer.isBuffer(payload) || payload.length < 5) {
+            return {
+                annexB: false,
+                hasIdr: false,
+                hasSps: false,
+                hasPps: false,
+                nalOrderValid: false
+            };
+        }
+        let annexB = false;
+        let hasIdr = false;
+        let hasSps = false;
+        let hasPps = false;
+        let firstSpsAt = -1;
+        let firstPpsAfterSpsAt = -1;
+        let firstIdrAfterPpsAt = -1;
+        for (let index = 0; index + 4 < payload.length; index += 1) {
+            let headerIndex = -1;
+            if (payload[index] === 0 && payload[index + 1] === 0 && payload[index + 2] === 1) {
+                headerIndex = index + 3;
+            } else if (payload[index] === 0
+                && payload[index + 1] === 0
+                && payload[index + 2] === 0
+                && payload[index + 3] === 1) {
+                headerIndex = index + 4;
+            }
+            if (headerIndex < 0 || headerIndex >= payload.length) continue;
+            annexB = true;
+            const nalType = payload[headerIndex] & 0x1f;
+            if (nalType === 5) {
+                hasIdr = true;
+                if (firstPpsAfterSpsAt >= 0 && firstIdrAfterPpsAt < 0) {
+                    firstIdrAfterPpsAt = headerIndex;
+                }
+            }
+            if (nalType === 7) {
+                hasSps = true;
+                if (firstSpsAt < 0) firstSpsAt = headerIndex;
+            }
+            if (nalType === 8) {
+                hasPps = true;
+                if (firstSpsAt >= 0 && firstPpsAfterSpsAt < 0) {
+                    firstPpsAfterSpsAt = headerIndex;
+                }
+            }
+            index = headerIndex;
+        }
+        return {
+            annexB,
+            hasIdr,
+            hasSps,
+            hasPps,
+            nalOrderValid: firstSpsAt >= 0
+                && firstPpsAfterSpsAt > firstSpsAt
+                && firstIdrAfterPpsAt > firstPpsAfterSpsAt
+        };
+    }
+
+    function expectedTransportForDiagnosticPhase(phase) {
+        if (phase === 'p2p') return 'p2p';
+        if (phase === 'relay') return 'relay';
+        return 'direct';
+    }
+
+    function observedTransportPath(frame) {
+        const transport = safeString(frame?.transport, 32).toLowerCase();
+        if (transport === 'udp-p2p') return 'p2p';
+        if (transport === 'relay-binary') return 'relay';
+        if (transport === 'binary' || transport === 'ws-binary') return 'direct';
+        return '';
+    }
+
+    function optionalFiniteNumber(value) {
+        return value !== null && value !== undefined && value !== ''
+            && Number.isFinite(Number(value))
+            ? Number(value)
+            : null;
+    }
+
+    function transportDiagnosticIdentifierHash(value, salt) {
+        const normalized = safeString(value, 240);
+        return normalized
+            ? crypto.createHash('sha256')
+                .update(`${safeString(salt, 160)}:${normalized}`)
+                .digest('hex')
+                .slice(0, 16)
+            : '';
+    }
+
+    function currentTransportDiagnosticOwner(device) {
+        const frame = device?.latestLiveFrame;
+        if (!device?.connected
+            || !device.sessionId
+            || !frame
+            || frame.currentGenerationVerified !== true
+            || safeString(frame.mimeType, 80).toLowerCase() !== 'video/h264'
+            || !safeString(frame.streamId, 128)
+            || !safeString(frame.commandId, 128)
+            || Number(frame.captureGeneration || 0) <= 0) {
+            return null;
+        }
+        const monitorIndex = parseExactLiveStreamMonitorIndex(frame.monitorIndex);
+        const streamState = getDeviceLiveStream(device, frame.streamId);
+        if (monitorIndex === null
+            || !streamState?.active
+            || safeString(streamState.commandId, 128) !== safeString(frame.commandId, 128)
+            || Number(streamState.captureGeneration || 0) !== Number(frame.captureGeneration || 0)
+            || parseExactLiveStreamMonitorIndex(streamState.monitorIndex) !== monitorIndex) {
+            return null;
+        }
+        return {
+            deviceId: device.deviceId,
+            sessionId: device.sessionId,
+            streamId: safeString(frame.streamId, 128),
+            streamCommandId: safeString(frame.commandId, 128),
+            captureGeneration: Number(frame.captureGeneration),
+            monitorIndex
+        };
+    }
+
+    function transportDiagnosticOwnersEqual(left, right) {
+        return !!left
+            && !!right
+            && left.deviceId === right.deviceId
+            && left.sessionId === right.sessionId
+            && left.streamId === right.streamId
+            && left.streamCommandId === right.streamCommandId
+            && left.captureGeneration === right.captureGeneration
+            && left.monitorIndex === right.monitorIndex;
+    }
+
+    function transportDiagnosticOwnerMatches(record, device) {
+        const current = currentTransportDiagnosticOwner(device);
+        return transportDiagnosticOwnersEqual(current, record.owner);
+    }
+
+    function serializeTransportDiagnostic(record) {
+        const refreshedNetwork = udpTransport?.getDeviceDiagnosticNetwork?.(record.owner.deviceId, {
+            salt: record.leaseId
+        });
+        if (refreshedNetwork?.evidence
+                === 'authenticated-udp-endpoint-rendezvous-observed'
+            || record.network?.evidence
+                !== 'authenticated-udp-endpoint-rendezvous-observed') {
+            record.network = refreshedNetwork || record.network;
+        }
+        return {
+            ok: record.state !== 'failed',
+            leaseId: record.leaseId,
+            state: record.state,
+            phase: record.phase,
+            startedAt: record.startedAt,
+            updatedAt: record.updatedAt,
+            expiresAt: record.expiresAt,
+            completedAt: record.completedAt || '',
+            error: safeString(record.error, 240),
+            owner: {
+                deviceId: record.owner.deviceId,
+                streamId: record.owner.streamId,
+                streamCommandId: record.owner.streamCommandId,
+                captureGeneration: record.owner.captureGeneration,
+                monitorIndex: record.owner.monitorIndex
+            },
+            network: record.network,
+            baseline: { ...record.baseline },
+            frames: record.frames.map(frame => ({ ...frame })),
+            cleanup: record.cleanup.map(entry => ({ ...entry }))
+        };
+    }
+
+    function getTransportDiagnostic(leaseId, token) {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        return serializeTransportDiagnostic(record);
+    }
+
+    function diagnosticSecretEquals(expected, provided) {
+        const expectedHash = crypto.createHash('sha256').update(String(expected || '')).digest();
+        const providedHash = crypto.createHash('sha256').update(String(provided || '')).digest();
+        return crypto.timingSafeEqual(expectedHash, providedHash);
+    }
+
+    async function sendTransportDiagnosticCommand(record, operation, phase = record.phase) {
+        const device = devices.get(record.owner.deviceId);
+        if (!device?.connected || device.sessionId !== record.owner.sessionId) {
+            return { ok: false, error: 'transport-diagnostic-device-disconnected' };
+        }
+        if (operation !== 'release' && !transportDiagnosticOwnerMatches(record, device)) {
+            return { ok: false, error: 'transport-diagnostic-owner-changed' };
+        }
+        const commandId = crypto.randomUUID();
+        const waiter = waitForCommandResult(device, commandId, transportDiagnosticCommandTimeoutMs);
+        const queued = sendCommand(device.deviceId, {
+            commandId,
+            command: 'transport.diagnostic',
+            payload: {
+                operation,
+                leaseId: record.leaseId,
+                token: record.token,
+                streamId: record.owner.streamId,
+                streamCommandId: record.owner.streamCommandId,
+                captureGeneration: record.owner.captureGeneration,
+                monitorIndex: record.owner.monitorIndex,
+                phase,
+                ttlMs: Math.max(0, Date.parse(record.expiresAt) - Date.now())
+            }
+        });
+        if (!queued.ok) {
+            failPendingCommandResultWaiter(commandId, queued.error);
+        }
+        const outcome = await waiter;
+        if (!outcome.ok || outcome.result?.ok === false) {
+            return {
+                ok: false,
+                error: safeString(outcome.error || outcome.result?.error, 240)
+                    || 'transport-diagnostic-agent-rejected'
+            };
+        }
+        return { ok: true };
+    }
+
+    function appendTransportDiagnosticCleanup(record, state, reason = '') {
+        record.cleanup.push({
+            at: new Date().toISOString(),
+            state,
+            reason: safeString(reason, 160)
+        });
+        if (record.cleanup.length > 16) record.cleanup.splice(0, record.cleanup.length - 16);
+        record.updatedAt = new Date().toISOString();
+    }
+
+    function clearTransportDiagnosticTimers(record) {
+        clearTimeout(record?.expiryTimer);
+        clearTimeout(record?.removalTimer);
+        if (record) {
+            record.expiryTimer = null;
+            record.removalTimer = null;
+        }
+    }
+
+    function removeTransportDiagnostic(record) {
+        if (!record) return;
+        clearTransportDiagnosticTimers(record);
+        if (transportDiagnostics.get(record.leaseId) === record) {
+            transportDiagnostics.delete(record.leaseId);
+        }
+        record.token = '';
+    }
+
+    function scheduleTransportDiagnosticRemoval(record) {
+        if (!record) return;
+        clearTimeout(record.expiryTimer);
+        clearTimeout(record.removalTimer);
+        record.expiryTimer = null;
+        record.removalTimer = setTimeout(() => {
+            removeTransportDiagnostic(record);
+        }, TRANSPORT_DIAGNOSTIC_RECORD_RETENTION_MS);
+        record.removalTimer.unref?.();
+    }
+
+    function pruneTransportDiagnosticRecords() {
+        const finalized = [...transportDiagnostics.values()]
+            .filter(record => record.state !== 'active'
+                && record.state !== 'acquiring'
+                && record.state !== 'expiring')
+            .sort((left, right) => Date.parse(left.updatedAt || '') - Date.parse(right.updatedAt || ''));
+        while (transportDiagnostics.size >= TRANSPORT_DIAGNOSTIC_MAX_RECORDS && finalized.length > 0) {
+            removeTransportDiagnostic(finalized.shift());
+        }
+    }
+
+    async function expireTransportDiagnostic(record, reason = 'ttl-expired') {
+        if (!record || record.state !== 'active') return;
+        if (record.operationInFlight === true) {
+            record.expiryTimer = setTimeout(() => {
+                void expireTransportDiagnostic(record, reason);
+            }, 250);
+            record.expiryTimer.unref?.();
+            return;
+        }
+        record.operationInFlight = true;
+        record.state = 'expiring';
+        appendTransportDiagnosticCleanup(record, 'release-requested', reason);
+        try {
+            const released = await sendTransportDiagnosticCommand(record, 'release');
+            record.state = reason === 'ttl-expired' ? 'expired' : 'aborted';
+            record.error = released.ok ? '' : released.error;
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(
+                record,
+                released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                released.error);
+        } finally {
+            record.operationInFlight = false;
+            scheduleTransportDiagnosticRemoval(record);
+        }
+    }
+
+    function abortTransportDiagnosticsForDevice(device, reason) {
+        for (const record of transportDiagnostics.values()) {
+            if (!['active', 'acquiring', 'expiring'].includes(record.state)
+                || record.owner.deviceId !== device?.deviceId
+                || record.owner.sessionId !== device?.sessionId) {
+                continue;
+            }
+            clearTimeout(record.expiryTimer);
+            record.state = 'aborted';
+            record.error = safeString(reason, 160) || 'device-disconnected';
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(record, 'connection-closed', record.error);
+            scheduleTransportDiagnosticRemoval(record);
+        }
+    }
+
+    async function startTransportDiagnostic(deviceId, ttlMs = 150_000, options = {}) {
+        const requestSignal = options?.signal;
+        const requestAborted = () => requestSignal?.aborted === true;
+        const normalizedDeviceId = safeString(deviceId, 160);
+        const device = devices.get(normalizedDeviceId);
+        const owner = currentTransportDiagnosticOwner(device);
+        if (!owner) {
+            return { ok: false, error: 'transport-diagnostic-current-h264-stream-required' };
+        }
+        if (observedTransportPath(device.latestLiveFrame) !== 'direct'
+            || safeString(device.latestLiveFrame?.frameTransportActive, 20).toLowerCase() !== 'direct') {
+            return { ok: false, error: 'transport-diagnostic-direct-start-required' };
+        }
+        if (transportDiagnosticStartingDevices.has(normalizedDeviceId)) {
+            return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+        }
+        const existingLease = [...transportDiagnostics.values()].some(existing =>
+            ['active', 'acquiring', 'expiring'].includes(existing.state)
+            && existing.owner.deviceId === owner.deviceId);
+        if (existingLease) {
+            return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+        }
+        transportDiagnosticStartingDevices.add(normalizedDeviceId);
+        try {
+            const refreshedDiagnosticNetwork =
+                await udpTransport?.refreshDeviceDiagnosticNetwork?.(
+                    owner.deviceId,
+                    { timeoutMs: 3_000 });
+            if (requestAborted()) {
+                return { ok: false, error: 'transport-diagnostic-request-aborted' };
+            }
+            const physicalNetwork = udpTransport?.getDeviceDiagnosticNetwork?.(
+                owner.deviceId,
+                { salt: 'transport-diagnostic-preflight' }) || {};
+            if (refreshedDiagnosticNetwork !== true
+                || physicalNetwork.evidence
+                    !== 'authenticated-udp-endpoint-rendezvous-observed'
+                || physicalNetwork.endpointAuthenticated !== true
+                || physicalNetwork.clientAddressPublic !== true
+                || physicalNetwork.hubAddressPublic !== true) {
+                return {
+                    ok: false,
+                    error: 'transport-diagnostic-fresh-rendezvous-egress-required'
+                };
+            }
+            if (physicalNetwork.differentPublicEgress !== true) {
+                return {
+                    ok: false,
+                    error: 'transport-diagnostic-distinct-public-egress-required'
+                };
+            }
+            const currentDevice = devices.get(normalizedDeviceId);
+            const refreshedOwner = currentTransportDiagnosticOwner(currentDevice);
+            if (!transportDiagnosticOwnersEqual(owner, refreshedOwner)
+                || observedTransportPath(currentDevice?.latestLiveFrame) !== 'direct'
+                || safeString(currentDevice?.latestLiveFrame?.frameTransportActive, 20).toLowerCase() !== 'direct') {
+                return { ok: false, error: 'transport-diagnostic-owner-changed' };
+            }
+            const concurrentLease = [...transportDiagnostics.values()].some(existing =>
+                ['active', 'acquiring', 'expiring'].includes(existing.state)
+                && existing.owner.deviceId === owner.deviceId);
+            if (concurrentLease) {
+                return { ok: false, error: 'transport-diagnostic-device-lease-active' };
+            }
+            pruneTransportDiagnosticRecords();
+            if (transportDiagnostics.size >= TRANSPORT_DIAGNOSTIC_MAX_RECORDS) {
+                return { ok: false, error: 'transport-diagnostic-capacity-reached' };
+            }
+
+            const boundedTtlMs = clampNumber(
+                ttlMs,
+                TRANSPORT_DIAGNOSTIC_MIN_TTL_MS,
+                TRANSPORT_DIAGNOSTIC_MAX_TTL_MS,
+                150_000);
+            const now = new Date();
+            const leaseId = crypto.randomUUID();
+            const token = crypto.randomBytes(32).toString('base64url');
+            const currentFrame = currentDevice.latestLiveFrame;
+            const udpStatus = udpTransport?.getDeviceStatus?.(owner.deviceId) || {};
+            const hubAddressObservedAt = safeString(
+                physicalNetwork.hubAddressObservedAt,
+                80);
+            const record = {
+                leaseId,
+                token,
+                owner,
+                phase: 'direct',
+                phaseStartedAt: '',
+                state: 'acquiring',
+                operationInFlight: true,
+                startedAt: now.toISOString(),
+                updatedAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + boundedTtlMs).toISOString(),
+                completedAt: '',
+                error: '',
+                hubAddressObservedAt,
+                baseline: {
+                    observedAt: safeString(currentFrame.receivedAt, 80),
+                    frameSeq: optionalFiniteNumber(currentFrame.frameSeq),
+                    switchCount: optionalFiniteNumber(currentFrame.frameTransportSwitchCount),
+                    agentQueueDropped: optionalFiniteNumber(currentFrame.nativeOutputQueueDroppedCount),
+                    hubIngressDropped: optionalFiniteNumber(currentFrame.hubIngressDropped),
+                    udpIncompleteFrames: optionalFiniteNumber(udpStatus.droppedFrames),
+                    hubIngressCounterEpochHash: transportDiagnosticIdentifierHash(
+                        currentFrame.hubIngressCounterEpoch,
+                        leaseId),
+                    udpCounterEpochHash: transportDiagnosticIdentifierHash(
+                        udpStatus.sessionId,
+                        leaseId),
+                    agentQueueTelemetryAvailable:
+                        currentFrame.nativeOutputQueueTelemetryAvailable === true,
+                    hubIngressTelemetryAvailable:
+                        currentFrame.hubIngressTelemetryAvailable === true
+                        && !!currentFrame.hubIngressCounterEpoch,
+                    udpTelemetryAvailable:
+                        optionalFiniteNumber(udpStatus.droppedFrames) !== null
+                        && !!udpStatus.sessionId
+                },
+                frames: [],
+                cleanup: [],
+                network: udpTransport?.getDeviceDiagnosticNetwork?.(owner.deviceId, {
+                    salt: leaseId
+                }) || {
+                    evidence: 'unavailable',
+                    differentPublicEgress: null,
+                    hubAddressObservedAt
+                },
+                expiryTimer: null,
+                removalTimer: null
+            };
+            transportDiagnostics.set(leaseId, record);
+            const acquired = await sendTransportDiagnosticCommand(record, 'acquire', 'direct');
+            record.operationInFlight = false;
+            if (!acquired.ok || record.state !== 'acquiring') {
+                const acquireError = acquired.ok
+                    ? safeString(record.error, 240) || 'transport-diagnostic-acquire-interrupted'
+                    : acquired.error;
+                record.error = acquireError;
+                record.completedAt = new Date().toISOString();
+                appendTransportDiagnosticCleanup(record, 'acquire-failed', record.error);
+                appendTransportDiagnosticCleanup(
+                    record,
+                    'release-requested',
+                    'acquire-outcome-uncertain');
+                record.operationInFlight = true;
+                let released;
+                try {
+                    released = await sendTransportDiagnosticCommand(record, 'release');
+                } catch (error) {
+                    released = {
+                        ok: false,
+                        error: safeString(error instanceof Error ? error.message : error, 240)
+                            || 'transport-diagnostic-agent-release-failed'
+                    };
+                } finally {
+                    record.operationInFlight = false;
+                }
+                appendTransportDiagnosticCleanup(
+                    record,
+                    released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                    released.error);
+                record.state = 'failed';
+                record.completedAt = new Date().toISOString();
+                const failed = { ...serializeTransportDiagnostic(record), token: '' };
+                removeTransportDiagnostic(record);
+                return failed;
+            }
+            record.state = 'active';
+            record.phaseStartedAt = new Date().toISOString();
+            record.updatedAt = record.phaseStartedAt;
+            appendTransportDiagnosticCleanup(record, 'lease-acquired');
+            if (requestAborted()) {
+                await expireTransportDiagnostic(record, 'start-request-aborted');
+                return { ok: false, error: 'transport-diagnostic-request-aborted' };
+            }
+            const remainingTtlMs = Math.max(1, Date.parse(record.expiresAt) - Date.now());
+            record.expiryTimer = setTimeout(() => {
+                void expireTransportDiagnostic(record, 'ttl-expired');
+            }, remainingTtlMs);
+            record.expiryTimer.unref?.();
+            return { ...serializeTransportDiagnostic(record), token };
+        } finally {
+            transportDiagnosticStartingDevices.delete(normalizedDeviceId);
+        }
+    }
+
+    async function setTransportDiagnosticPhase(leaseId, token, phase) {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        const normalizedPhase = safeString(phase, 32).toLowerCase();
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        if (record.state !== 'active') {
+            return { ok: false, error: 'transport-diagnostic-not-active' };
+        }
+        if (record.operationInFlight === true) {
+            return { ok: false, error: 'transport-diagnostic-operation-in-flight' };
+        }
+        if (!TRANSPORT_DIAGNOSTIC_PHASES.includes(normalizedPhase)) {
+            return { ok: false, error: 'transport-diagnostic-phase-invalid' };
+        }
+        const currentIndex = TRANSPORT_DIAGNOSTIC_PHASES.indexOf(record.phase);
+        const nextIndex = TRANSPORT_DIAGNOSTIC_PHASES.indexOf(normalizedPhase);
+        const currentObserved = record.frames.some(frame => frame.phase === record.phase && frame.accepted === true);
+        if (nextIndex !== currentIndex + 1 || !currentObserved) {
+            return { ok: false, error: 'transport-diagnostic-phase-order-required' };
+        }
+        record.operationInFlight = true;
+        try {
+            const updated = await sendTransportDiagnosticCommand(record, 'set-phase', normalizedPhase);
+            if (!updated.ok) {
+                record.error = updated.error;
+                record.updatedAt = new Date().toISOString();
+                return { ok: false, error: updated.error };
+            }
+            if (record.state !== 'active') {
+                return { ok: false, error: 'transport-diagnostic-interrupted' };
+            }
+            record.phase = normalizedPhase;
+            record.phaseStartedAt = new Date().toISOString();
+            record.updatedAt = record.phaseStartedAt;
+            return serializeTransportDiagnostic(record);
+        } finally {
+            record.operationInFlight = false;
+        }
+    }
+
+    async function stopTransportDiagnostic(leaseId, token, reason = 'runner-complete') {
+        const record = transportDiagnostics.get(safeString(leaseId, 128));
+        if (!record || !diagnosticSecretEquals(record.token, token)) {
+            return { ok: false, error: 'transport-diagnostic-not-found' };
+        }
+        if (record.state !== 'active') return serializeTransportDiagnostic(record);
+        if (record.operationInFlight === true) {
+            return { ok: false, error: 'transport-diagnostic-operation-in-flight' };
+        }
+        clearTimeout(record.expiryTimer);
+        record.operationInFlight = true;
+        try {
+            appendTransportDiagnosticCleanup(record, 'release-requested', reason);
+            const released = await sendTransportDiagnosticCommand(record, 'release');
+            record.state = released.ok ? 'completed' : 'failed';
+            record.error = released.ok ? '' : released.error;
+            record.completedAt = new Date().toISOString();
+            appendTransportDiagnosticCleanup(
+                record,
+                released.ok ? 'agent-released' : 'agent-release-unconfirmed',
+                released.error);
+            const serialized = serializeTransportDiagnostic(record);
+            scheduleTransportDiagnosticRemoval(record);
+            return serialized;
+        } finally {
+            record.operationInFlight = false;
+        }
+    }
+
+    function recordTransportDiagnosticFrame(device, message, payload, frame) {
+        if (transportDiagnostics.size === 0 || message.transportDiagnosticApplied !== true) {
+            return;
+        }
+        const leaseId = safeString(message.transportDiagnosticLeaseId, 128);
+        const phase = safeString(message.transportDiagnosticPhase, 32).toLowerCase();
+        if (!leaseId) return;
+        const record = transportDiagnostics.get(leaseId);
+        if (!record
+            || record.state !== 'active'
+            || record.phase !== phase
+            || !transportDiagnosticOwnerMatches(record, device)
+            || frame.streamId !== record.owner.streamId
+            || frame.commandId !== record.owner.streamCommandId
+            || frame.captureGeneration !== record.owner.captureGeneration
+            || frame.monitorIndex !== record.owner.monitorIndex
+            || safeString(frame.mimeType, 80).toLowerCase() !== 'video/h264') {
+            return;
+        }
+        const expectedPath = expectedTransportForDiagnosticPhase(phase);
+        const h264 = inspectAnnexBH264(payload);
+        const agentPath = safeString(frame.frameTransportActive, 20).toLowerCase();
+        const hubObservedPath = observedTransportPath(frame);
+        const frameSeq = optionalFiniteNumber(frame.frameSeq);
+        const switchCount = optionalFiniteNumber(message.frameTransportSwitchCount);
+        const lastAcceptedFrame = [...record.frames]
+            .reverse()
+            .find(item => item.accepted === true);
+        const previousFrameSeq = optionalFiniteNumber(
+            lastAcceptedFrame?.frameSeq ?? record.baseline?.frameSeq);
+        const previousSwitchCount = optionalFiniteNumber(
+            lastAcceptedFrame?.switchCount ?? record.baseline?.switchCount);
+        const sequenceAdvanced = frameSeq !== null
+            && (previousFrameSeq === null || frameSeq > previousFrameSeq);
+        const switchAdvanced = switchCount !== null
+            && (lastAcceptedFrame
+                ? previousSwitchCount !== null && switchCount > previousSwitchCount
+                : previousSwitchCount === null || switchCount >= previousSwitchCount);
+        const agentQueueDepth = optionalFiniteNumber(message.nativeOutputQueueDepth);
+        const agentQueueBytes = optionalFiniteNumber(message.nativeOutputQueueBytes);
+        const agentQueueDropped = optionalFiniteNumber(message.nativeOutputQueueDroppedCount);
+        const hubIngressDropped = optionalFiniteNumber(message.hubIngressDropped);
+        const udpIncompleteFrames = optionalFiniteNumber(message.udpIncompleteFrames);
+        const hubIngressCounterEpochHash = transportDiagnosticIdentifierHash(
+            message.hubIngressCounterEpoch,
+            record.leaseId);
+        const agentQueueTelemetryAvailable = agentQueueDepth !== null
+            && agentQueueBytes !== null
+            && agentQueueDropped !== null;
+        const hubIngressTelemetryAvailable = hubIngressDropped !== null
+            && !!hubIngressCounterEpochHash;
+        const udpTelemetryAvailable = phase !== 'p2p' || udpIncompleteFrames !== null;
+        const phaseLatencyMs = Math.max(
+            0,
+            Date.parse(frame.receivedAt || '') - Date.parse(record.phaseStartedAt || ''));
+        const accepted = agentPath === expectedPath
+            && hubObservedPath === expectedPath
+            && frame.isKeyFrame === true
+            && h264.annexB
+            && h264.hasIdr
+            && h264.hasSps
+            && h264.hasPps
+            && h264.nalOrderValid
+            && sequenceAdvanced
+            && switchAdvanced
+            && agentQueueTelemetryAvailable
+            && hubIngressTelemetryAvailable
+            && udpTelemetryAvailable
+            && Number.isFinite(phaseLatencyMs);
+        if (record.frames.some(item => item.phase === phase && item.accepted === true)) return;
+        const observation = {
+            phase,
+            expectedPath,
+            actualPath: agentPath,
+            hubObservedPath,
+            protocol: safeString(frame.frameTransportProtocol, 20),
+            transport: safeString(frame.transport, 32),
+            reason: safeString(frame.frameTransportReason, 160),
+            receivedAt: frame.receivedAt,
+            frameSeq,
+            byteLength: frame.byteLength,
+            contentHash: safeString(frame.contentHash, 128),
+            isKeyFrame: frame.isKeyFrame === true,
+            annexB: h264.annexB,
+            hasIdr: h264.hasIdr,
+            hasSps: h264.hasSps,
+            hasPps: h264.hasPps,
+            nalOrderValid: h264.nalOrderValid,
+            switchCount,
+            tcpFailureCount: frame.frameTransportTcpFailureCount,
+            phaseLatencyMs,
+            sequenceAdvanced,
+            switchAdvanced,
+            agentQueueDepth,
+            agentQueueBytes,
+            agentQueueDropped,
+            hubIngressDropped,
+            udpIncompleteFrames,
+            hubIngressCounterEpochHash,
+            agentQueueTelemetryAvailable,
+            hubIngressTelemetryAvailable,
+            udpTelemetryAvailable,
+            accepted
+        };
+        if (accepted) {
+            record.frames = record.frames.filter(item => item.phase !== phase);
+            record.frames.push(observation);
+        } else {
+            const rejectedIndex = record.frames.findIndex(item =>
+                item.phase === phase && item.accepted !== true);
+            if (rejectedIndex >= 0) record.frames[rejectedIndex] = observation;
+            else record.frames.push(observation);
+        }
+        if (record.frames.length > TRANSPORT_DIAGNOSTIC_PHASES.length * 2) {
+            record.frames = record.frames.filter(item => item.accepted === true)
+                .concat(record.frames.filter(item => item.accepted !== true)
+                    .slice(-TRANSPORT_DIAGNOSTIC_PHASES.length));
+        }
+        record.updatedAt = new Date().toISOString();
+    }
+
     function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
         const now = new Date().toISOString();
         const descriptor = buildRemoteFrameTransferDescriptor(mode, mode === 'thumbnail' ? 'thumbnail' : DEFAULT_REMOTE_FRAME_MODE);
@@ -3135,9 +3857,10 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        device.connected = false;
-        device.socket = null;
-        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
+        device.connected = false;
+        device.socket = null;
+        abortTransportDiagnosticsForDevice(device, reason);
+        udpTransport?.unregisterDevice?.(deviceId, device.sessionId);
         closeInputSocket(device, reason);
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
@@ -3578,6 +4301,48 @@ export function createRemoteHub(options = {}) {
                 ?? result.HubForwardedAtEpochMs
                 ?? pending?.hubForwardedAtEpochMs
                 ?? 0) || 0,
+            duplicate: message.duplicate === true
+                || message.Duplicate === true
+                || result.duplicate === true
+                || result.Duplicate === true,
+            nativeInputBackend: safeString(
+                message.nativeInputBackend
+                || message.NativeInputBackend
+                || result.nativeInputBackend
+                || result.NativeInputBackend,
+                80),
+            nativeEventsRequested: Math.max(0, Number(
+                message.nativeEventsRequested
+                ?? message.NativeEventsRequested
+                ?? result.nativeEventsRequested
+                ?? result.NativeEventsRequested
+                ?? 0) || 0),
+            nativeEventsAccepted: Math.max(0, Number(
+                message.nativeEventsAccepted
+                ?? message.NativeEventsAccepted
+                ?? result.nativeEventsAccepted
+                ?? result.NativeEventsAccepted
+                ?? 0) || 0),
+            hookEventsObserved: Math.max(0, Number(
+                message.hookEventsObserved
+                ?? message.HookEventsObserved
+                ?? result.hookEventsObserved
+                ?? result.HookEventsObserved
+                ?? 0) || 0),
+            hookEventsBlocked: Math.max(0, Number(
+                message.hookEventsBlocked
+                ?? message.HookEventsBlocked
+                ?? result.hookEventsBlocked
+                ?? result.HookEventsBlocked
+                ?? 0) || 0),
+            focusChanged: message.focusChanged === true
+                || message.FocusChanged === true
+                || result.focusChanged === true
+                || result.FocusChanged === true,
+            inputDiagnostic: message.inputDiagnostic === true
+                || message.InputDiagnostic === true
+                || result.inputDiagnostic === true
+                || result.InputDiagnostic === true,
             fallback: pending?.fallback === true,
             hubAcknowledgedAtEpochMs: Date.now()
         };
@@ -4426,10 +5191,17 @@ export function createRemoteHub(options = {}) {
             nativeOutputQueueHighWatermark: Number.isFinite(Number(message.nativeOutputQueueHighWatermark)) ? Number(message.nativeOutputQueueHighWatermark) : 0,
             nativeOutputQueueDroppedCount: Number.isFinite(Number(message.nativeOutputQueueDroppedCount)) ? Number(message.nativeOutputQueueDroppedCount) : 0,
             nativeOutputQueueAwaitingKeyFrame: message.nativeOutputQueueAwaitingKeyFrame === true,
+            nativeOutputQueueTelemetryAvailable:
+                optionalFiniteNumber(message.nativeOutputQueueDepth) !== null
+                && optionalFiniteNumber(message.nativeOutputQueueBytes) !== null
+                && optionalFiniteNumber(message.nativeOutputQueueDroppedCount) !== null,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,
             udpIncompleteFrames: Number.isFinite(Number(message.udpIncompleteFrames)) ? Number(message.udpIncompleteFrames) : 0,
+            hubIngressTelemetryAvailable: optionalFiniteNumber(message.hubIngressDropped) !== null,
+            udpIncompleteTelemetryAvailable: optionalFiniteNumber(message.udpIncompleteFrames) !== null,
+            hubIngressCounterEpoch: safeString(message.hubIngressCounterEpoch, 160),
             hardwareEncoder: safeString(message.hardwareEncoder, 80),
             platformProfile: safeString(message.platformProfile, 80),
             monitorIndex: activeMonitorIndex,
@@ -4480,9 +5252,10 @@ export function createRemoteHub(options = {}) {
             frameTransportTcpFailureCount: Number.isFinite(Number(message.frameTransportTcpFailureCount)) ? Number(message.frameTransportTcpFailureCount) : 0,
             sameContentStreak,
             payload,
-            accessToken: createFrameAccessToken()
-        };
-        streamState.latestFrame = device.latestLiveFrame;
+            accessToken: createFrameAccessToken()
+        };
+        recordTransportDiagnosticFrame(device, message, payload, device.latestLiveFrame);
+        streamState.latestFrame = device.latestLiveFrame;
         rememberRecentFramePayload(device, 'live', device.latestLiveFrame);
         emitFrame({
             kind: 'live',
@@ -4677,7 +5450,8 @@ export function createRemoteHub(options = {}) {
         if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
             applyLiveFrame(device, {
                 ...header,
-                hubIngressDropped: Number(state.binaryQueueDrops || 0)
+                hubIngressDropped: Number(state.binaryQueueDrops || 0),
+                hubIngressCounterEpoch: state.binaryQueueEpoch
             }, framePayload, binaryTransport);
             return;
         }
@@ -4718,10 +5492,11 @@ export function createRemoteHub(options = {}) {
             lastFrameAt: new Date().toISOString(),
             framesReceived: Number(device.udp?.framesReceived || 0) + 1
         };
-        return applyLiveFrame(device, {
-            ...header,
-            transport: 'udp-p2p'
-        }, payload, 'udp-p2p');
+        return applyLiveFrame(device, {
+            ...header,
+            transport: 'udp-p2p',
+            hubIngressCounterEpoch: sessionId
+        }, payload, 'udp-p2p');
     }
 
     function dropQueuedAgentBinaryFrame(state) {
@@ -5051,9 +5826,10 @@ export function createRemoteHub(options = {}) {
             binaryQueue: [],
             binaryQueueDraining: false,
             binaryQueueScheduled: false,
-            binaryQueueSocket: null,
-            binaryQueueDrops: 0,
-            closed: false
+            binaryQueueSocket: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            closed: false
         };
 
         const helloTimer = setTimeout(() => {
@@ -5211,9 +5987,10 @@ export function createRemoteHub(options = {}) {
             binaryQueue: [],
             binaryQueueDraining: false,
             binaryQueueScheduled: false,
-            binaryQueueSocket: null,
-            binaryQueueDrops: 0,
-            closed: false
+            binaryQueueSocket: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            closed: false
         };
 
         const helloTimer = setTimeout(() => {
@@ -5437,8 +6214,9 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
+    async function close() {
         for (const device of devices.values()) {
+            abortTransportDiagnosticsForDevice(device, 'hub-shutdown');
             failAllPendingTasks(device, 'hub-shutdown');
             failAllPendingInputFallbacks(device, 'hub-shutdown');
             failPendingCommandResultWaiters(device, 'hub-shutdown');
@@ -5490,10 +6268,11 @@ export function createRemoteHub(options = {}) {
 
     function disconnectDevice(deviceId, reason = 'manager-disconnect') {
         const device = devices.get(String(deviceId || ''));
-        if (device?.synthetic === true) {
-            device.connected = false;
-            device.disconnectedAt = new Date().toISOString();
-            device.lastDisconnectReason = reason;
+        if (device?.synthetic === true) {
+            device.connected = false;
+            device.disconnectedAt = new Date().toISOString();
+            device.lastDisconnectReason = reason;
+            abortTransportDiagnosticsForDevice(device, reason);
             deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
             failAllPendingTasks(device, 'device-disconnected');
             failAllPendingInputFallbacks(device, 'device-disconnected');
@@ -7547,6 +8326,10 @@ export function createRemoteHub(options = {}) {
         stopLiveStream,
         pauseLiveCapture,
         resumeLiveCapture,
+        startTransportDiagnostic,
+        getTransportDiagnostic,
+        setTransportDiagnosticPhase,
+        stopTransportDiagnostic,
         startAudioStream,
         stopAudioStream,
         getDeviceLiveFrame,

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();
@@ -3093,7 +3118,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 +3136,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}` });
@@ -290,6 +323,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 +362,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 +375,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 +454,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);
     }