@livedesk/hub 0.1.30 → 0.1.31

package/src/remote-hub.js

@@ -1,7 +1,10 @@
 import net from 'net';
 import os from 'os';
-import crypto from 'crypto';
-import { createHubRelayControl } from './transport/relay-hub-control.js';
+import crypto from 'crypto';
+import { isSecureHandshakeStart } from '@livedesk/runtime-core';
+import { createDeviceCredentialAuthority } from './security/device-credential-authority.js';
+import { createHubRelayControl, createSecureHubRelayControl } from './transport/relay-hub-control.js';
+import { createSecureDirectAcceptor } from './transport/secure-direct-acceptor.js';
 import { parseExactLiveStreamMonitorIndex } from './live-stream-monitor-contract.js';
 import {
     BoundedSegmentedBuffer,
@@ -32,9 +35,10 @@ const MAX_AGENT_TCP_BINARY_PACKET_BYTES = TCP_BINARY_FRAME_HEADER_BYTES
 const MAX_AGENT_WEBSOCKET_MESSAGE_BYTES = 4
     + MAX_AGENT_BINARY_META_BYTES
     + MAX_AGENT_BINARY_PAYLOAD_BYTES;
-const MAX_AGENT_SOCKET_ACCUMULATOR_BYTES = MAX_LINE_CHARS
-    + MAX_AGENT_TCP_BINARY_PACKET_BYTES
-    + (256 * 1024);
+const MAX_AGENT_SOCKET_ACCUMULATOR_BYTES = MAX_LINE_CHARS
+    + MAX_AGENT_TCP_BINARY_PACKET_BYTES
+    + (256 * 1024);
+const MAX_AGENT_MESSAGES_PER_SECOND = 240;
 const HTTP_HEADER_TERMINATOR = Buffer.from('\r\n\r\n', 'ascii');
 const MAX_AGENT_TASK_CHARS = 4000;
 const MAX_AGENT_TASK_RESULT_CHARS = 3000;
@@ -106,7 +110,7 @@ const MAC_NATIVE_RESOURCE_TELEMETRY_FIELDS = Object.freeze([
     'handoffOldestFrameAgeMs'
 ]);
 
-export function hasCompleteMacNativeResourceTelemetry(frame) {
+export function hasCompleteMacNativeResourceTelemetry(frame) {
     return Number(frame?.nativeCaptureTelemetryVersion) >= MAC_NATIVE_RESOURCE_TELEMETRY_VERSION
         && MAC_NATIVE_RESOURCE_TELEMETRY_FIELDS.every(field =>
             frame?.[field] !== null
@@ -824,14 +828,61 @@ function isPrivateIPv4(value) {
         || (parts[0] === 192 && parts[1] === 168);
 }
 
-function isPrivateNetworkAddress(value) {
+function isPrivateNetworkAddress(value) {
     const address = String(value || '').replace(/^::ffff:/i, '').trim().toLowerCase();
     return isLoopbackHost(address)
         || isPrivateIPv4(address)
         || address.startsWith('fe80:')
         || address.startsWith('fc')
-        || address.startsWith('fd');
-}
+        || address.startsWith('fd');
+}
+
+export function createRemoteMessageRateGate({
+    limit = MAX_AGENT_MESSAGES_PER_SECOND,
+    windowMs = 1_000,
+    now = () => Date.now()
+} = {}) {
+    const boundedLimit = Math.max(1, Math.min(10_000, Math.floor(Number(limit) || MAX_AGENT_MESSAGES_PER_SECOND)));
+    const boundedWindowMs = Math.max(100, Math.min(60_000, Math.floor(Number(windowMs) || 1_000)));
+    let windowStartedAt = Number(now());
+    let count = 0;
+    return Object.freeze({
+        consume() {
+            const current = Number(now());
+            if (!Number.isFinite(current) || current - windowStartedAt >= boundedWindowMs || current < windowStartedAt) {
+                windowStartedAt = current;
+                count = 0;
+            }
+            count += 1;
+            return count <= boundedLimit;
+        },
+        getStatus: () => ({ count, limit: boundedLimit, windowMs: boundedWindowMs, windowStartedAt })
+    });
+}
+
+export function evaluateRemoteConnectionPolicy({
+    remoteAddress = '',
+    relayConnection = false,
+    encrypted = false,
+    allowLegacyPlaintextForTests = false,
+    policy = {}
+} = {}) {
+    const address = String(remoteAddress || '').replace(/^::ffff:/i, '').trim().toLowerCase();
+    if (policy.requireEncryptedConnections === true
+        && encrypted !== true
+        && allowLegacyPlaintextForTests !== true) {
+        return 'encrypted-connection-required';
+    }
+    if (relayConnection === true || !isPrivateNetworkAddress(address)) {
+        return policy.allowInternetConnections === false
+            ? 'internet-connections-blocked-by-settings'
+            : '';
+    }
+    if (!isLoopbackHost(address) && policy.allowLanConnections === false) {
+        return 'lan-connections-blocked-by-settings';
+    }
+    return '';
+}
 
 function readCpuTimes() {
     let idle = 0;
@@ -1155,34 +1206,37 @@ function getRetiredAgentTaskError(options = {}) {
         : '';
 }
 
-const SUPPORTED_AGENT_OPERATIONS = new Set([
-    'system.health',
-    'gpu.status',
-    'disk.status',
-    'process.list',
-    'service.status',
-    'diagnostics.collect',
-    'process.control',
-    'service.control',
-    'application.launch',
-    'application.close',
-    'file.read',
-    'file.write',
-    'file.delete',
-    'file.list',
-    'command.run',
-    'script.run',
-    'software.install',
-    'network.status',
-    'system.power',
-    'system.configure',
-    'logs.collect'
-]);
-
-function normalizeAgentOperation(value) {
-    const operation = safeString(value, 80).toLowerCase();
-    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
-}
+const SUPPORTED_AGENT_OPERATIONS = new Set([
+    'system.health',
+    'gpu.status',
+    'disk.status',
+    'process.list',
+    'service.status',
+    'diagnostics.collect',
+    'file.read',
+    'file.list',
+    'network.status',
+    'logs.collect'
+]);
+
+const RETIRED_AGENT_MUTATING_OPERATIONS = new Set([
+    'process.control',
+    'service.control',
+    'application.launch',
+    'application.close',
+    'file.write',
+    'file.delete',
+    'command.run',
+    'script.run',
+    'software.install',
+    'system.power',
+    'system.configure'
+]);
+
+function normalizeAgentOperation(value) {
+    const operation = safeString(value, 80).toLowerCase();
+    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
+}
 
 const REMOTE_INPUT_MONITOR_KEYS = Object.freeze([
     'monitorIndex',
@@ -1348,7 +1402,7 @@ function buildRemoteFramePath(deviceId, frameKind, frame) {
     return `/api/remote/devices/${encodeURIComponent(deviceId)}/${endpoint}?${params.toString()}`;
 }
 
-function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
+function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
     if (!frame) {
         return null;
     }
@@ -1370,8 +1424,27 @@ function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
         serialized.dataUrl = dataUrl || buildFrameDataUrl(payload, '', publicFrame.mimeType || publicFrame.format || 'image/jpeg');
     }
 
-    return serialized;
-}
+    return serialized;
+}
+
+function serializeActiveLiveStream(activeLiveStream, deviceId) {
+    if (!activeLiveStream) {
+        return null;
+    }
+
+    return {
+        ...activeLiveStream,
+        // The active descriptor is status metadata. Keep its internal frame
+        // owner intact for immediate delivery, but never duplicate encoded
+        // bytes or its bearer token into React/status snapshots.
+        latestFrame: serializeRemoteFrame(
+            activeLiveStream.latestFrame,
+            deviceId,
+            'live',
+            { includeDataUrl: false }
+        )
+    };
+}
 
 function getRecentFrameCache(device, frameKind) {
     if (!device) {
@@ -1562,7 +1635,7 @@ function serializeDevice(device, options = {}) {
         },
         latestThumbnail: serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', options),
         latestLiveFrame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', options),
-        activeLiveStream: device.activeLiveStream ? { ...device.activeLiveStream } : null,
+        activeLiveStream: serializeActiveLiveStream(device.activeLiveStream, device.deviceId),
         liveCapturePause: device.liveCapturePause
             ? {
                 token: device.liveCapturePause.token,
@@ -2169,7 +2242,7 @@ export function createRemoteHub(options = {}) {
         : null;
     const sampleHubRuntimeDiagnostics = createHubRuntimeDiagnosticsSampler();
 
-    function getDevicePolicy(device) {
+    function getDevicePolicy(device) {
         try {
             return getEffectiveDevicePolicy({
                 deviceId: device?.deviceId || '',
@@ -2177,8 +2250,18 @@ export function createRemoteHub(options = {}) {
             }) || {};
         } catch {
             return {};
-        }
-    }
+        }
+    }
+
+    function connectionPolicyError(socket, policy = {}) {
+        return evaluateRemoteConnectionPolicy({
+            remoteAddress: socket?.remoteAddress || '',
+            relayConnection: socket?.__liveDeskRelayControl === true,
+            encrypted: socket?.__liveDeskSecurityContext?.encrypted === true,
+            allowLegacyPlaintextForTests,
+            policy
+        });
+    }
 
     function policyError(device, permission = '', command = '') {
         const policy = getDevicePolicy(device);
@@ -2228,22 +2311,82 @@ 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 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())
+    const configuredEnrollmentToken = safeString(
+        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN,
+        256);
+    const allowLegacyPlaintextForTests = options.allowLegacyPlaintextForTests === true
+        || isEnabledValue(env.LIVEDESK_TEST_ALLOW_LEGACY_PLAINTEXT, false)
+        || env.LIVEDESK_TEST_MODE === '1';
+    const canonicalEnrollmentToken = /^[A-Za-z0-9_-]{43}$/.test(configuredEnrollmentToken)
+        && Buffer.from(configuredEnrollmentToken, 'base64url').length === 32
+        && Buffer.from(configuredEnrollmentToken, 'base64url').toString('base64url') === configuredEnrollmentToken
+        ? configuredEnrollmentToken
+        : '';
+    let pairToken = allowLegacyPlaintextForTests && configuredEnrollmentToken
+        ? configuredEnrollmentToken
+        : canonicalEnrollmentToken || crypto.randomBytes(32).toString('base64url');
+    const deviceCredentialAuthority = options.deviceCredentialAuthority || createDeviceCredentialAuthority({
+        dataDir: options.dataDir || env.LIVEDESK_DATA_DIR || undefined
+    });
+    const getSecurityIdentity = typeof options.getSecurityIdentity === 'function'
+        ? options.getSecurityIdentity
+        : () => ({ accountId: safeString(options.accountId || env.LIVEDESK_ACCOUNT_ID, 128) });
+    udpTransport?.setRendezvousProofIssuer?.(({ roomId, deviceId, ttlMs }) => {
+        const identity = getSecurityIdentity() || {};
+        return deviceCredentialAuthority.issueRendezvousProof({
+            roomId,
+            deviceId,
+            ttlMs,
+            accountId: safeString(identity.accountId, 128)
+        });
+    });
+    let pairingPin = /^\d{6}$/.test(String(options.pairingPin || env.LIVEDESK_PAIRING_PIN || '').trim())
         ? String(options.pairingPin || env.LIVEDESK_PAIRING_PIN).trim()
         : generatePairingPin();
-    let pairingPinUpdatedAt = new Date().toISOString();
+    let pairingPinUpdatedAt = new Date().toISOString();
+    const consumeEnrollmentToken = expected => {
+        if (!timingSafeStringEqual(expected, pairToken)) return false;
+        pairToken = crypto.randomBytes(32).toString('base64url');
+        pairingPin = generatePairingPin();
+        pairingPinUpdatedAt = new Date().toISOString();
+        emitRemoteEvent('RemoteEnrollmentTokenRotated', null, {
+            pairingPinUpdatedAt,
+            hubId: deviceCredentialAuthority.hubId
+        });
+        return true;
+    };
+    const relayControl = options.relayControl && typeof options.relayControl === 'object'
+        ? options.relayControl
+        : allowLegacyPlaintextForTests
+            ? createHubRelayControl({
+                env,
+                pairToken,
+                logEvent,
+                logWarn,
+                onPeerSocket: socket => handleTcpAgentSocket(socket)
+            })
+            : createSecureHubRelayControl({
+                env,
+                authority: deviceCredentialAuthority,
+                getIdentity: () => getSecurityIdentity() || {},
+                getEnrollmentToken: () => pairToken,
+                consumeEnrollmentToken,
+                logEvent,
+                logWarn,
+                onPeerSocket: socket => handleTcpAgentSocket(socket)
+            });
+    const secureDirectAcceptor = createSecureDirectAcceptor({
+        authority: deviceCredentialAuthority,
+        getIdentity: () => getSecurityIdentity() || {},
+        getEnrollmentToken: () => pairToken,
+        consumeEnrollmentToken,
+        onSecureSocket: socket => handleTcpAgentSocket(socket),
+        onAudit: audit => emitEvent('RemoteSecurityHandshakeAudit', {
+            ...audit,
+            remoteHub: getStatus({ includeSecrets: false })
+        }),
+        logWarn
+    });
     const duplicateDeviceLogThrottleMs = clampNumber(
         env.MINDEXEC_REMOTE_DUPLICATE_DEVICE_LOG_MS || env.REMOTE_HUB_DUPLICATE_DEVICE_LOG_MS,
         5000,
@@ -2268,7 +2411,8 @@ export function createRemoteHub(options = {}) {
     const transportDiagnostics = new Map();
     const transportDiagnosticStartingDevices = new Set();
     const duplicateDeviceLogAt = new Map();
-    let server = null;
+    let server = null;
+    let controlIdleSweepTimer = null;
     let started = false;
     let boundPort = requestedPort;
     let lastError = '';
@@ -2590,8 +2734,8 @@ export function createRemoteHub(options = {}) {
             host,
             agentHost: routeInfo.host || getAnnouncedHost(),
             port: boundPort || requestedPort,
-            protocol: 'tcp-jsonl',
-            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            protocol: 'secure-record-v1',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
             agentProtocol: REMOTE_AGENT_PROTOCOL,
             frameProtocol: buildRemoteFrameProtocolDescriptor(),
             frameModes: getSupportedRemoteFrameModeProfiles(),
@@ -2607,9 +2751,18 @@ export function createRemoteHub(options = {}) {
             agentEndpointCandidates: routeInfo.candidates,
             agentEndpointCandidateDetails: routeInfo.candidateDetails,
             pairToken: includeSecrets ? pairToken : undefined,
-            pairTokenPreview: maskToken(pairToken),
-            pairingPin: includeSecrets ? pairingPin : '',
-            pairingPinUpdatedAt,
+            pairTokenPreview: maskToken(pairToken),
+            pairingPin: includeSecrets ? pairingPin : '',
+            pairingPinUpdatedAt,
+            security: {
+                direct: secureDirectAcceptor.getStatus(),
+                hubId: deviceCredentialAuthority.hubId,
+                hubPublicKeyFingerprint: crypto.createHash('sha256')
+                    .update(Buffer.from(deviceCredentialAuthority.hubPublicKey, 'base64url'))
+                    .digest('hex'),
+                enrolledDeviceCount: deviceCredentialAuthority.listDevices().filter(item => !item.revokedAt).length,
+                legacyPlaintextForTests: allowLegacyPlaintextForTests
+            },
             deviceCount: devices.size,
             connectedDeviceCount: connectedDevices,
             canvasDeviceListMode: 'all-devices',
@@ -3869,14 +4022,22 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function closeInputSocket(device, reason = 'input-socket-closed') {
+    function closeInputSocket(device, reason = 'input-socket-closed') {
         const socket = device?.inputSocket;
         if (!socket) {
             return;
         }
-
-        const writeOwner = device.inputWriteOwner;
-        device.inputSocket = null;
+
+        const writeOwner = device.inputWriteOwner;
+        if (device.controlOwnerConnectionId) {
+            endControlSession(
+                device,
+                device.controlOwnerConnectionId,
+                reason,
+                writeOwner,
+                writeOwner?.getBindingKey?.() || '');
+        }
+        device.inputSocket = null;
         device.inputWriteOwner = null;
         device.inputSocketConnectionId = '';
         device.inputOwnerConnectionId = '';
@@ -3906,9 +4067,17 @@ export function createRemoteHub(options = {}) {
         if (!device || device.inputSocket !== socket) {
             return;
         }
-
-        const writeOwner = device.inputWriteOwner;
-        device.inputSocket = null;
+
+        const writeOwner = device.inputWriteOwner;
+        if (device.controlOwnerConnectionId) {
+            endControlSession(
+                device,
+                device.controlOwnerConnectionId,
+                reason,
+                null,
+                '');
+        }
+        device.inputSocket = null;
         device.inputWriteOwner = null;
         device.inputSocketConnectionId = '';
         device.inputOwnerConnectionId = '';
@@ -4340,7 +4509,11 @@ export function createRemoteHub(options = {}) {
             inputWriteOwner: null,
             inputSocketConnectionId: '',
             inputOwnerConnectionId: '',
-            inputOwnerBindingKey: '',
+            inputOwnerBindingKey: '',
+            controlOwnerSessionId: '',
+            controlOwnerConnectionId: '',
+            controlOwnerStartedAtMs: 0,
+            controlOwnerLastInputAtMs: 0,
             frameSocket: null,
             audioSocket: null,
             fileSocket: null,
@@ -7261,8 +7434,14 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        if (!state.authenticated) {
-            if (message.type === 'hello' && socket.__liveDeskRelayControl === true) {
+        if (!state.authenticated) {
+            const securityContext = socket.__liveDeskSecurityContext;
+            const secureDeviceAuthenticated = securityContext?.authenticated === true
+                && securityContext?.encrypted === true
+                && safeString(securityContext.accountId, 128)
+                && safeString(securityContext.hubId, 128)
+                && safeString(securityContext.deviceId, 128);
+            if (message.type === 'hello' && socket.__liveDeskRelayControl === true) {
                 message = {
                     ...message,
                     capabilities: {
@@ -7272,13 +7451,14 @@ export function createRemoteHub(options = {}) {
                         dedicatedInputChannel: false
                     }
                 };
-            }
-            if (message.type === 'slot.assign') {
-                if (!timingSafeStringEqual(message.pairToken, pairToken)) {
-                    writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'invalid-pair-token' });
-                    socket.end();
-                    return;
-                }
+            }
+            if (message.type === 'slot.assign') {
+                if (!secureDeviceAuthenticated
+                    || safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
+                    writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'authenticated-device-credential-required' });
+                    socket.end();
+                    return;
+                }
                 const result = assignDeviceSlot(
                     message.deviceId || message.DeviceId,
                     message.slotNumber ?? message.slot ?? message.SlotNumber);
@@ -7292,13 +7472,54 @@ export function createRemoteHub(options = {}) {
                 return;
             }
 
-            if (!timingSafeStringEqual(message.pairToken, pairToken)) {
-                writeJsonLine(socket, { type: 'error', error: 'invalid-pair-token' });
-                socket.destroy();
-                return;
-            }
-
-            const channel = safeString(message.channel || message.Channel, 40).toLowerCase();
+            if (secureDeviceAuthenticated) {
+                if (safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
+                    writeJsonLine(socket, { type: 'error', error: 'device-credential-binding-invalid' });
+                    socket.destroy();
+                    return;
+                }
+                const helloChannel = safeString(message.channel || message.Channel || 'control', 40).toLowerCase() || 'control';
+                if (helloChannel !== securityContext.channel) {
+                    writeJsonLine(socket, { type: 'error', error: 'secure-channel-binding-invalid' });
+                    socket.destroy();
+                    return;
+                }
+            } else {
+                const legacyAllowed = socket.__liveDeskRelayControl === true
+                    || socket.__liveDeskLegacyPlaintext === true && allowLegacyPlaintextForTests;
+                if (!legacyAllowed || !timingSafeStringEqual(message.pairToken, pairToken)) {
+                    writeJsonLine(socket, { type: 'error', error: 'authenticated-device-credential-required' });
+                    socket.destroy();
+                    return;
+                }
+            }
+
+            const incomingDeviceId = safeString(message.deviceId || message.DeviceId, 128);
+            const incomingCapabilities = message.capabilities && typeof message.capabilities === 'object'
+                ? message.capabilities
+                : {};
+            const incomingPolicy = getWelcomeDevicePolicy({
+                deviceId: incomingDeviceId,
+                capabilities: incomingCapabilities
+            }) || {};
+            const connectionDenied = connectionPolicyError(socket, incomingPolicy);
+            if (connectionDenied) {
+                writeJsonLine(socket, { type: 'error', error: connectionDenied });
+                emitEvent('RemoteSecurityPolicyAudit', {
+                    result: 'rejected',
+                    reason: connectionDenied,
+                    deviceId: incomingDeviceId,
+                    sessionId: safeString(socket.__liveDeskSecurityContext?.sessionId, 160),
+                    accountId: safeString(socket.__liveDeskSecurityContext?.accountId, 128),
+                    hubId: safeString(socket.__liveDeskSecurityContext?.hubId, 128),
+                    transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
+                    remoteAddress: safeString(socket.remoteAddress, 256)
+                });
+                socket.destroy();
+                return;
+            }
+
+            const channel = safeString(message.channel || message.Channel, 40).toLowerCase();
             if (channel === 'input') {
                 const device = attachInputSocket(socket, message);
                 if (!device) {
@@ -7465,7 +7686,27 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function handleWebSocketAgentSocket(socket) {
+    function enforceAgentMessageRate(socket, state, channel = 'control') {
+        if (state.messageRateGate.consume()) return true;
+        const device = state.device;
+        emitEvent('RemoteAbuseDefense', {
+            result: 'rejected',
+            reason: 'authenticated-message-rate-exceeded',
+            deviceId: device?.deviceId || '',
+            sessionId: device?.sessionId || '',
+            accountId: socket.__liveDeskSecurityContext?.accountId || '',
+            hubId: socket.__liveDeskSecurityContext?.hubId || '',
+            transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
+            channel,
+            remoteAddress: safeString(socket.remoteAddress, 256),
+            rate: state.messageRateGate.getStatus()
+        });
+        writeJsonLine(socket, { type: 'error', error: 'message-rate-exceeded' });
+        socket.destroy();
+        return false;
+    }
+
+    function handleWebSocketAgentSocket(socket) {
         allSockets.add(socket);
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
@@ -7479,10 +7720,11 @@ export function createRemoteHub(options = {}) {
             audioOnly: false,
             fileOnly: false,
             parserBuffer: socket.buffer,
-            binaryIngress: null,
-            binaryQueueDrops: 0,
-            binaryQueueEpoch: crypto.randomUUID(),
-            closed: false
+            binaryIngress: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            messageRateGate: createRemoteMessageRateGate(),
+            closed: false
         };
         attachAgentBinaryIngress(socket, state);
 
@@ -7493,8 +7735,9 @@ export function createRemoteHub(options = {}) {
             }
         }, 10000);
 
-        socket.onTextMessage = text => {
-            try {
+        socket.onTextMessage = text => {
+            if (!enforceAgentMessageRate(socket, state, 'websocket-text')) return;
+            try {
                 handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
             } catch (err) {
                 writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
@@ -7502,8 +7745,9 @@ export function createRemoteHub(options = {}) {
             }
         };
 
-        socket.onBinaryMessage = payload => {
-            try {
+        socket.onBinaryMessage = payload => {
+            if (!enforceAgentMessageRate(socket, state, 'websocket-binary')) return;
+            try {
                 const packet = parseRemoteHubWebSocketBinaryFrame(payload);
                 if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
                     writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
@@ -7658,10 +7902,11 @@ export function createRemoteHub(options = {}) {
             buffer: new BoundedSegmentedBuffer(MAX_AGENT_SOCKET_ACCUMULATOR_BYTES),
             lineScanOffset: 0,
             pendingBinaryFrame: null,
-            binaryIngress: null,
-            binaryQueueDrops: 0,
-            binaryQueueEpoch: crypto.randomUUID(),
-            closed: false
+            binaryIngress: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            messageRateGate: createRemoteMessageRateGate(),
+            closed: false
         };
         attachAgentBinaryIngress(socket, state);
 
@@ -7776,9 +8021,18 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                try {
-                    const message = parseJsonLine(lineBuffer.toString('utf8'));
-                    if (message?.type === 'frame.binary') {
+                try {
+                    const message = parseJsonLine(lineBuffer.toString('utf8'));
+                    if (!enforceAgentMessageRate(socket, state, state.frameOnly
+                        ? 'frame'
+                        : state.audioOnly
+                            ? 'audio'
+                            : state.inputOnly
+                                ? 'input'
+                                : state.fileOnly ? 'file' : 'control')) {
+                        return;
+                    }
+                    if (message?.type === 'frame.binary') {
                         const frameKind = safeString(message.frameKind || message.kind || message.frameType, 40).toLowerCase();
                         const maxBytes = frameKind === 'thumbnail'
                             ? MAX_THUMBNAIL_BINARY_BYTES
@@ -7832,16 +8086,35 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function handleSocket(socket) {
-        socket.once('data', chunk => {
-            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
-                handleWebSocketUpgradeSocket(socket, firstChunk);
-                return;
-            }
-
-            handleTcpAgentSocket(socket, firstChunk);
-        });
+    function handleSocket(socket) {
+        if (!allowLegacyPlaintextForTests) {
+            secureDirectAcceptor.accept(socket);
+            return;
+        }
+        socket.once('data', chunk => {
+            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (isSecureHandshakeStart(firstChunk)) {
+                secureDirectAcceptor.accept(socket, firstChunk);
+                return;
+            }
+            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
+                if (!allowLegacyPlaintextForTests) {
+                    socket.write('HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n');
+                    socket.destroy();
+                    return;
+                }
+                socket.__liveDeskLegacyPlaintext = true;
+                handleWebSocketUpgradeSocket(socket, firstChunk);
+                return;
+            }
+            if (!allowLegacyPlaintextForTests) {
+                writeJsonLine(socket, { type: 'error', error: 'secure-direct-required' });
+                socket.destroy();
+                return;
+            }
+            socket.__liveDeskLegacyPlaintext = true;
+            handleTcpAgentSocket(socket, firstChunk);
+        });
 
         socket.once('error', () => {
             // The transport-specific handler owns logging after the first byte.
@@ -7863,10 +8136,10 @@ export function createRemoteHub(options = {}) {
                 started = true;
                 boundPort = candidateServer.address()?.port || port;
                 lastError = '';
-                logEvent('remote', `LiveDesk Hub client endpoint listening on tcp://${host}:${boundPort}`, 'success');
-                if (host === '0.0.0.0' || host === '::') {
-                    logWarn('remote', 'LiveDesk Hub client endpoint is externally reachable. Use a strong pairing token and trusted network.');
-                }
+                logEvent('remote', `LiveDesk Hub client endpoint listening with authenticated encryption on tcp://${host}:${boundPort}`, 'success');
+                if (host === '0.0.0.0' || host === '::') {
+                    logWarn('remote', 'LiveDesk Hub client endpoint is externally reachable; Secure Direct device credentials are required.');
+                }
                 emitRemoteEvent('RemoteHubStarted', null);
                 resolve();
             });
@@ -7878,10 +8151,14 @@ export function createRemoteHub(options = {}) {
             return getStatus({ includeSecrets: false });
         }
 
-        try {
-            await udpTransport?.start?.();
-            await listenOnPort(requestedPort);
-            try {
+        try {
+            await udpTransport?.start?.();
+            await listenOnPort(requestedPort);
+            if (!controlIdleSweepTimer) {
+                controlIdleSweepTimer = setInterval(sweepIdleControlSessions, 1_000);
+                controlIdleSweepTimer.unref?.();
+            }
+            try {
                 await relayControl?.start?.();
             } catch {
                 logWarn('relay', 'Encrypted relay control could not start; direct TCP remains available.');
@@ -7902,8 +8179,12 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
-        for (const state of [...agentBinaryIngressStates]) {
+    async function close() {
+        if (controlIdleSweepTimer) {
+            clearInterval(controlIdleSweepTimer);
+            controlIdleSweepTimer = null;
+        }
+        for (const state of [...agentBinaryIngressStates]) {
             closeAgentBinaryIngress(state, 'hub-shutdown');
         }
 
@@ -8109,7 +8390,7 @@ export function createRemoteHub(options = {}) {
         return { ok: true, commandId };
     }
 
-    function refreshDevicePolicies(deviceIds = undefined) {
+    function refreshDevicePolicies(deviceIds = undefined) {
         const requestedIds = Array.isArray(deviceIds) && deviceIds.length > 0
             ? new Set(deviceIds.map(deviceId => safeString(deviceId, 160)).filter(Boolean))
             : null;
@@ -8118,9 +8399,31 @@ export function createRemoteHub(options = {}) {
         for (const device of devices.values()) {
             if (requestedIds && !requestedIds.has(device.deviceId)) continue;
             if (!device?.socket || device.socket.destroyed || !device.connected) continue;
-            total += 1;
-            const effectivePolicy = getDevicePolicy(device);
-            if (writeJsonLine(device.socket, {
+            total += 1;
+            const effectivePolicy = getDevicePolicy(device);
+            const connectionDenied = connectionPolicyError(device.socket, effectivePolicy);
+            if (connectionDenied) {
+                emitEvent('RemoteSecurityPolicyAudit', {
+                    result: 'rejected',
+                    reason: connectionDenied,
+                    deviceId: device.deviceId,
+                    sessionId: device.sessionId,
+                    transport: device.controlTransport,
+                    remoteAddress: device.remoteAddress
+                });
+                disconnectDevice(device.deviceId, connectionDenied);
+                continue;
+            }
+            if (effectivePolicy.allowControl !== true && device.controlOwnerConnectionId) {
+                releaseInputOwner(
+                    device.deviceId,
+                    device.controlOwnerConnectionId,
+                    'control-disabled-by-policy');
+            }
+            if (effectivePolicy.allowRemoteAudio !== true && device.activeAudioStream) {
+                stopAudioStream(device.deviceId, { reason: 'remote-audio-disabled-by-policy' });
+            }
+            if (writeJsonLine(device.socket, {
                 type: 'policy.update',
                 effectivePolicy,
                 updatedAt: new Date().toISOString()
@@ -8199,7 +8502,7 @@ export function createRemoteHub(options = {}) {
         ]);
     }
 
-    function buildRemoteInputResetMessage(device, controlStream, ownerConnectionId, reason, activeMonitorIndex) {
+    function buildRemoteInputResetMessage(device, controlStream, ownerConnectionId, reason, activeMonitorIndex) {
         return {
             type: 'input.control',
             payload: {
@@ -8221,8 +8524,114 @@ export function createRemoteHub(options = {}) {
                 hubForwardedAtEpochMs: Date.now(),
                 issuedAt: new Date().toISOString()
             }
-        };
-    }
+        };
+    }
+
+    function controlSessionMessage(device, ownerConnectionId, type, reason = '') {
+        const policy = getDevicePolicy(device);
+        return {
+            type,
+            payload: {
+                controlOwnerSessionId: safeString(device?.controlOwnerSessionId, 160),
+                hubConnectionId: safeString(ownerConnectionId, 128),
+                deviceId: safeString(device?.deviceId, 160),
+                visibleIndicator: true,
+                lockOnEnd: type === 'control.session.stop' && policy.lockOnControlEnd === true,
+                idleControlMinutes: clampNumber(policy.idleControlMinutes, 5, 1440, 30),
+                reason: safeString(reason, 160),
+                issuedAt: new Date().toISOString()
+            }
+        };
+    }
+
+    function sendControlSessionMessage(device, ownerConnectionId, type, reason, inputWriteOwner, bindingKey) {
+        const message = controlSessionMessage(device, ownerConnectionId, type, reason);
+        if (inputWriteOwner && bindingKey) {
+            return inputWriteOwner.enqueue(message, bindingKey);
+        }
+        if (!device?.socket || device.socket.destroyed) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        const sent = writeJsonLine(device.socket, {
+            type: 'command',
+            commandId: crypto.randomUUID(),
+            command: type,
+            payload: message.payload,
+            issuedAt: new Date().toISOString()
+        });
+        return sent ? { ok: true, inputSocket: false } : { ok: false, error: 'device-not-connected' };
+    }
+
+    function beginControlSession(device, ownerConnectionId, inputWriteOwner, bindingKey) {
+        const owner = safeString(ownerConnectionId, 128);
+        if (!device || !owner) return { ok: false, error: 'control-owner-required' };
+        if (device.controlOwnerConnectionId === owner && device.controlOwnerSessionId) {
+            return { ok: true, alreadyActive: true };
+        }
+        device.controlOwnerSessionId = crypto.randomUUID();
+        device.controlOwnerConnectionId = owner;
+        device.controlOwnerStartedAtMs = Date.now();
+        device.controlOwnerLastInputAtMs = Date.now();
+        const sent = sendControlSessionMessage(
+            device,
+            owner,
+            'control.session.start',
+            'browser-control-owner-active',
+            inputWriteOwner,
+            bindingKey);
+        if (!sent.ok) {
+            device.controlOwnerSessionId = '';
+            device.controlOwnerConnectionId = '';
+            device.controlOwnerStartedAtMs = 0;
+            device.controlOwnerLastInputAtMs = 0;
+            return sent;
+        }
+        emitRemoteEvent('RemoteControlSessionStarted', device, {
+            controlOwnerSessionId: device.controlOwnerSessionId,
+            hubConnectionId: owner
+        });
+        return sent;
+    }
+
+    function endControlSession(device, ownerConnectionId, reason, inputWriteOwner, bindingKey) {
+        const owner = safeString(ownerConnectionId, 128);
+        if (!device?.controlOwnerSessionId
+            || !owner
+            || device.controlOwnerConnectionId !== owner) {
+            return { ok: false, error: 'control-owner-not-current' };
+        }
+        const controlOwnerSessionId = device.controlOwnerSessionId;
+        const sent = sendControlSessionMessage(
+            device,
+            owner,
+            'control.session.stop',
+            reason,
+            inputWriteOwner,
+            bindingKey);
+        device.controlOwnerSessionId = '';
+        device.controlOwnerConnectionId = '';
+        device.controlOwnerStartedAtMs = 0;
+        device.controlOwnerLastInputAtMs = 0;
+        emitRemoteEvent('RemoteControlSessionEnded', device, {
+            controlOwnerSessionId,
+            hubConnectionId: owner,
+            reason,
+            delivered: sent.ok === true
+        });
+        return sent;
+    }
+
+    function sweepIdleControlSessions() {
+        const nowMs = Date.now();
+        for (const device of devices.values()) {
+            if (!device?.connected || !device.controlOwnerConnectionId) continue;
+            const policy = getDevicePolicy(device);
+            if (policy.disconnectIdleControlSessions !== true) continue;
+            const idleMs = clampNumber(policy.idleControlMinutes, 5, 1440, 30) * 60 * 1000;
+            if (nowMs - Number(device.controlOwnerLastInputAtMs || 0) < idleMs) continue;
+            releaseInputOwner(device.deviceId, device.controlOwnerConnectionId, 'control-idle-timeout');
+        }
+    }
 
     function getCurrentInputWriteOwner(device) {
         if (!device?.inputSocket
@@ -8365,13 +8774,16 @@ export function createRemoteHub(options = {}) {
                 normalized,
                 activeMonitorIndex);
             const previousInputBindingKey = String(device.inputOwnerBindingKey || '');
-            const ownerChanged = normalized.hubConnectionId
+            const ownerChanged = normalized.hubConnectionId
                 && previousOwnerConnectionId
                 && normalized.hubConnectionId !== previousOwnerConnectionId;
             const bindingChanged = previousInputBindingKey
                 && previousInputBindingKey !== activeInputBindingKey;
-            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
-            if (ownerChanged || bindingChanged || writeBindingChanged) {
+            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
+            const startingControlOwner = !!normalized.hubConnectionId
+                && (!device.controlOwnerConnectionId
+                    || device.controlOwnerConnectionId !== normalized.hubConnectionId);
+            if (ownerChanged || bindingChanged || writeBindingChanged) {
                 const resetSent = inputWriteOwner.replaceBinding(
                     activeInputBindingKey,
                     buildRemoteInputResetMessage(
@@ -8386,9 +8798,28 @@ export function createRemoteHub(options = {}) {
                         activeMonitorIndex));
                 if (!resetSent.ok) {
                     closeInputSocket(device, resetSent.error || 'input-owner-reset-write-failed');
-                    return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
-                }
-            }
+                    return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+                }
+                if (startingControlOwner) {
+                    if (device.controlOwnerConnectionId) {
+                        endControlSession(
+                            device,
+                            device.controlOwnerConnectionId,
+                            'browser-input-owner-changed',
+                            inputWriteOwner,
+                            activeInputBindingKey);
+                    }
+                    const started = beginControlSession(
+                        device,
+                        normalized.hubConnectionId,
+                        inputWriteOwner,
+                        activeInputBindingKey);
+                    if (!started.ok) {
+                        closeInputSocket(device, started.error || 'control-session-indicator-start-failed');
+                        return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+                    }
+                }
+            }
             const sent = inputWriteOwner.enqueue({
                 type: 'input.control',
                 payload: {
@@ -8401,7 +8832,8 @@ export function createRemoteHub(options = {}) {
                 if (normalized.hubConnectionId) {
                     device.inputOwnerConnectionId = normalized.hubConnectionId;
                 }
-                device.inputOwnerBindingKey = activeInputBindingKey;
+                device.inputOwnerBindingKey = activeInputBindingKey;
+                device.controlOwnerLastInputAtMs = Date.now();
                 device.counters.commandsSent += 1;
                 device.inputLastSeenAt = new Date().toISOString();
                 return {
@@ -8430,8 +8862,27 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
         }
 
-        const hubForwardedAtEpochMs = Date.now();
-        const fallback = sendCommand(deviceId, {
+        const hubForwardedAtEpochMs = Date.now();
+        const startingFallbackOwner = !!normalized.hubConnectionId
+            && (!device.controlOwnerConnectionId
+                || device.controlOwnerConnectionId !== normalized.hubConnectionId);
+        if (startingFallbackOwner) {
+            if (device.controlOwnerConnectionId) {
+                endControlSession(
+                    device,
+                    device.controlOwnerConnectionId,
+                    'browser-input-owner-changed',
+                    null,
+                    '');
+            }
+            const started = beginControlSession(
+                device,
+                normalized.hubConnectionId,
+                null,
+                '');
+            if (!started.ok) return started;
+        }
+        const fallback = sendCommand(deviceId, {
             command: 'input.control',
             payload: {
                 ...normalized,
@@ -8439,7 +8890,7 @@ export function createRemoteHub(options = {}) {
                 issuedAt: normalized.issuedAt || new Date().toISOString()
             }
         });
-        if (fallback.ok && normalized.requestAck && normalized.inputSeq > 0) {
+        if (fallback.ok && normalized.requestAck && normalized.inputSeq > 0) {
             schedulePendingInputFallback(device, {
                 commandId: fallback.commandId,
                 inputSeq: normalized.inputSeq,
@@ -8451,10 +8902,26 @@ export function createRemoteHub(options = {}) {
                 hubReceivedAtEpochMs: normalized.hubReceivedAtEpochMs,
                 hubForwardedAtEpochMs,
                 fallback: true,
-                timeoutTimer: null
-            });
-        }
-        return fallback.ok
+                timeoutTimer: null
+            });
+        }
+        if (fallback.ok) {
+            device.inputOwnerConnectionId = normalized.hubConnectionId;
+            device.inputOwnerBindingKey = buildRemoteInputBindingKey(
+                device,
+                controlStream,
+                normalized,
+                activeMonitorIndex);
+            device.controlOwnerLastInputAtMs = Date.now();
+        } else if (startingFallbackOwner) {
+            endControlSession(
+                device,
+                normalized.hubConnectionId,
+                'input-control-delivery-failed',
+                null,
+                '');
+        }
+        return fallback.ok
             ? {
                 ...fallback,
                 inputSocket: false,
@@ -8480,15 +8947,20 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'input-owner-not-current' };
         }
 
-        device.inputOwnerConnectionId = '';
-        device.inputOwnerBindingKey = '';
-        const inputSocket = device.inputSocket;
-        const inputWriteOwner = getCurrentInputWriteOwner(device);
-        if (!inputSocket || !inputWriteOwner) {
-            return { ok: true, queued: false };
-        }
-        const controlStream = getActiveControlStream(device);
-        const releaseBindingKey = buildRemoteInputReleaseBindingKey(device, owner);
+        const inputSocket = device.inputSocket;
+        const inputWriteOwner = getCurrentInputWriteOwner(device);
+        if (!inputSocket || !inputWriteOwner) {
+            const ended = endControlSession(device, owner, reason, null, '');
+            device.inputOwnerConnectionId = '';
+            device.inputOwnerBindingKey = '';
+            return {
+                ok: ended.ok !== false,
+                queued: false,
+                controlSessionEnded: ended.ok === true
+            };
+        }
+        const controlStream = getActiveControlStream(device);
+        const releaseBindingKey = buildRemoteInputReleaseBindingKey(device, owner);
         const sent = inputWriteOwner.replaceBinding(
             releaseBindingKey,
             buildRemoteInputResetMessage(
@@ -8497,15 +8969,24 @@ export function createRemoteHub(options = {}) {
                 owner,
                 reason,
                 normalizeMonitorIndex(controlStream?.monitorIndex)));
-        if (!sent.ok) {
+        if (!sent.ok) {
             closeInputSocket(device, sent.error || 'input-owner-release-write-failed');
             return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
-        }
-        return {
-            ok: true,
-            queued: true,
-            backpressured: sent.backpressured === true
-        };
+        }
+        const ended = endControlSession(
+            device,
+            owner,
+            reason,
+            inputWriteOwner,
+            releaseBindingKey);
+        device.inputOwnerConnectionId = '';
+        device.inputOwnerBindingKey = '';
+        return {
+            ok: ended.ok !== false,
+            queued: true,
+            backpressured: sent.backpressured === true || ended.backpressured === true,
+            controlSessionEnded: ended.ok === true
+        };
     }
 
     function notifyAgentProgress(deviceIds, progress = {}) {
@@ -8545,9 +9026,12 @@ export function createRemoteHub(options = {}) {
         if (retiredRequestError) {
             return { ok: false, error: retiredRequestError };
         }
-        const device = devices.get(String(deviceId || ''));
-        const requestedOperation = safeString(options.operation, 80);
-        const operation = normalizeAgentOperation(requestedOperation);
+        const device = devices.get(String(deviceId || ''));
+        const requestedOperation = safeString(options.operation, 80);
+        if (RETIRED_AGENT_MUTATING_OPERATIONS.has(requestedOperation.toLowerCase())) {
+            return { ok: false, error: 'agent-mutating-tool-disabled' };
+        }
+        const operation = normalizeAgentOperation(requestedOperation);
         if (requestedOperation && !operation) {
             return { ok: false, error: 'unsupported-agent-operation' };
         }
@@ -10822,8 +11306,16 @@ export function createRemoteHub(options = {}) {
         handleUdpFrame,
         seedSyntheticFleet,
         clearSyntheticFleet,
-        getPairToken: () => pairToken,
-        getPairingPin: () => pairingPin
+        getPairToken: () => pairToken,
+        getPairingPin: () => pairingPin,
+        getSecurityStatus: () => ({
+            hubId: deviceCredentialAuthority.hubId,
+            hubPublicKey: deviceCredentialAuthority.hubPublicKey,
+            direct: secureDirectAcceptor.getStatus(),
+            devices: deviceCredentialAuthority.listDevices()
+        }),
+        revokeDeviceCredential: (deviceId, reason) => deviceCredentialAuthority.revokeDevice(deviceId, reason),
+        clearDeviceCredentials: () => deviceCredentialAuthority.clearDevices()
     };
 }