@livedesk/client 0.1.222 → 0.1.224

package/bin/livedesk-client-node.js

@@ -1,13 +1,15 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import net from 'net';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
-import { existsSync, promises as fs, statfsSync } from 'fs';
+import { constants as fsConstants, existsSync, promises as fs, statfsSync } from 'fs';
 import { spawn } from 'child_process';
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { createClientDeviceCredentialStore } from '../src/security/device-credential-store.js';
+import { connectSecureDirect } from '../src/security/secure-direct-client.js';
 
 const require = createRequire(import.meta.url);
 const CLIENT_UPDATE_BOOTSTRAP_PATH = fileURLToPath(
@@ -657,7 +659,7 @@ function sanitizePathSegment(value, fallback = 'file') {
     return normalized.slice(0, 160);
 }
 
-function sanitizeRelativeFilePath(value, fallbackName = 'file') {
+function sanitizeRelativeFilePath(value, fallbackName = 'file') {
     const parts = String(value || '')
         .replace(/\0/g, '')
         .split(/[\\/]+/)
@@ -668,7 +670,52 @@ function sanitizeRelativeFilePath(value, fallbackName = 'file') {
         return sanitizePathSegment(fallbackName, 'file');
     }
     return path.join(...parts.slice(-8));
-}
+}
+
+function isPathInsideRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+async function resolveReceiveDirectory(options, remoteDirectory) {
+    const configuredRoot = path.resolve(options.filesDir || getDefaultFilesDir());
+    await fs.mkdir(configuredRoot, { recursive: true });
+    const rootStat = await fs.lstat(configuredRoot);
+    if (rootStat.isSymbolicLink()) throw new Error('The LiveDesk receive root cannot be a symbolic link or junction.');
+    const canonicalRoot = await fs.realpath(configuredRoot);
+    const relativeDirectory = String(remoteDirectory || '').replace(/\0/g, '').trim();
+    if (relativeDirectory.length > 600 || path.isAbsolute(relativeDirectory)) {
+        throw new Error('The remote receive directory must be relative to the LiveDesk files root.');
+    }
+    const candidate = path.resolve(canonicalRoot, relativeDirectory || '.');
+    if (!isPathInsideRoot(canonicalRoot, candidate)) throw new Error('The remote receive directory escapes the LiveDesk files root.');
+    await assertAgentPathDoesNotTraverseLink(canonicalRoot, candidate);
+    await fs.mkdir(candidate, { recursive: true });
+    await assertAgentPathDoesNotTraverseLink(canonicalRoot, candidate);
+    const canonicalCandidate = await fs.realpath(candidate);
+    if (!isPathInsideRoot(canonicalRoot, canonicalCandidate)) throw new Error('The remote receive directory resolves outside the LiveDesk files root.');
+    return { root: canonicalRoot, directory: canonicalCandidate };
+}
+
+function requireFileSha256(value) {
+    const hash = String(value || '').trim().toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(hash)) throw new Error('A valid SHA-256 file hash is required.');
+    return hash;
+}
+
+function hashBuffer(buffer) {
+    return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+async function commitNewFile(tempPath, targetPath) {
+    try {
+        await fs.link(tempPath, targetPath);
+    } catch (error) {
+        if (error?.code === 'EEXIST') throw new Error(`Refusing to overwrite an existing file: ${path.basename(targetPath)}`);
+        throw error;
+    }
+    await fs.rm(tempPath, { force: true });
+}
 
 async function handleFileTransferCommand(options, payload = {}) {
     const files = Array.isArray(payload.files) ? payload.files.slice(0, MAX_FILE_TRANSFER_FILES) : [];
@@ -676,32 +723,46 @@ async function handleFileTransferCommand(options, payload = {}) {
         throw new Error('No files were included in the transfer.');
     }
 
-    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
-    await fs.mkdir(baseDir, { recursive: true });
+    const { root, directory: baseDir } = await resolveReceiveDirectory(options, payload.remoteDirectory);
 
     let totalBytes = 0;
     const saved = [];
     for (const file of files) {
         const name = sanitizePathSegment(file?.name, 'file');
         const relativePath = sanitizeRelativeFilePath(file?.relativePath || name, name);
-        const targetPath = path.resolve(baseDir, relativePath);
-        const relativeFromBase = path.relative(baseDir, targetPath);
-        if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
-            throw new Error(`Unsafe file path: ${relativePath}`);
-        }
+        const targetPath = path.resolve(baseDir, relativePath);
+        if (!isPathInsideRoot(baseDir, targetPath)) {
+            throw new Error(`Unsafe file path: ${relativePath}`);
+        }
 
         const dataBase64 = String(file?.dataBase64 || '').replace(/^data:[^,]*,/i, '').trim();
         if (!dataBase64) {
             throw new Error(`Missing file data: ${name}`);
         }
-        const buffer = Buffer.from(dataBase64, 'base64');
+        const buffer = Buffer.from(dataBase64, 'base64');
+        const expectedSha256 = requireFileSha256(file?.sha256);
+        if (hashBuffer(buffer) !== expectedSha256) throw new Error(`File SHA-256 mismatch: ${name}`);
         totalBytes += buffer.length;
         if (totalBytes > MAX_FILE_TRANSFER_BYTES) {
             throw new Error('File transfer exceeded the local size limit.');
         }
 
-        await fs.mkdir(path.dirname(targetPath), { recursive: true });
-        await fs.writeFile(targetPath, buffer);
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await assertAgentPathDoesNotTraverseLink(root, path.dirname(targetPath));
+        await assertAgentPathDoesNotTraverseLink(root, targetPath);
+        const tempPath = `${targetPath}.livedesk-${crypto.randomBytes(12).toString('hex')}.part`;
+        try {
+            const handle = await fs.open(tempPath, 'wx', 0o600);
+            try {
+                await handle.writeFile(buffer);
+                await handle.sync();
+            } finally {
+                await handle.close();
+            }
+            await commitNewFile(tempPath, targetPath);
+        } finally {
+            await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        }
         saved.push({
             name,
             relativePath,
@@ -722,12 +783,11 @@ async function handleFileTransferCommand(options, payload = {}) {
 }
 
 async function handleFileTransferChunkCommand(options, payload = {}) {
-    const baseDir = normalizeDirectoryPath(payload.remoteDirectory || options.filesDir);
+    const { root, directory: baseDir } = await resolveReceiveDirectory(options, payload.remoteDirectory);
     const name = sanitizePathSegment(payload.name, 'file');
     const relativePath = sanitizeRelativeFilePath(payload.relativePath || name, name);
     const targetPath = path.resolve(baseDir, relativePath);
-    const relativeFromBase = path.relative(baseDir, targetPath);
-    if (relativeFromBase.startsWith('..') || path.isAbsolute(relativeFromBase)) {
+    if (!isPathInsideRoot(baseDir, targetPath)) {
         throw new Error(`Unsafe file path: ${relativePath}`);
     }
 
@@ -736,19 +796,31 @@ async function handleFileTransferChunkCommand(options, payload = {}) {
     const totalBytes = Math.max(0, Math.floor(Number(payload.totalBytes) || 0));
     const final = payload.final === true;
     const buffer = payload.dataBase64 ? Buffer.from(String(payload.dataBase64), 'base64') : Buffer.alloc(0);
-    if (!transferId || offset > totalBytes || offset + buffer.length > totalBytes || buffer.length > 512 * 1024) {
+    if (!transferId || totalBytes > MAX_FILE_TRANSFER_BYTES || offset > totalBytes || offset + buffer.length > totalBytes || buffer.length > 512 * 1024) {
         throw new Error('Invalid file transfer chunk.');
     }
     if (buffer.length === 0 && !(final && totalBytes === 0 && offset === 0)) {
         throw new Error('Empty file chunks are not allowed.');
     }
 
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    const tempPath = `${targetPath}.livedesk-${transferId}.part`;
-    const handle = await fs.open(tempPath, offset === 0 ? 'w+' : 'r+');
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await assertAgentPathDoesNotTraverseLink(root, path.dirname(targetPath));
+    await assertAgentPathDoesNotTraverseLink(root, targetPath);
+    const tempPath = `${targetPath}.livedesk-${transferId}.part`;
+    if (offset > 0) {
+        const staging = await fs.lstat(tempPath);
+        if (!staging.isFile() || staging.isSymbolicLink() || staging.nlink !== 1) {
+            throw new Error('Unsafe file transfer staging path.');
+        }
+    }
+    const openFlags = offset === 0
+        ? fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_RDWR
+        : fsConstants.O_RDWR | (fsConstants.O_NOFOLLOW || 0);
+    const handle = await fs.open(tempPath, openFlags, 0o600);
     let completedSize = 0;
     try {
-        const before = await handle.stat();
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1) throw new Error('Unsafe file transfer staging path.');
         if (offset > before.size) {
             throw new Error(`File chunk gap detected at ${offset}; current length is ${before.size}.`);
         }
@@ -767,9 +839,19 @@ async function handleFileTransferChunkCommand(options, payload = {}) {
         await handle.close();
     }
 
-    if (final) {
-        await fs.rm(targetPath, { force: true });
-        await fs.rename(tempPath, targetPath);
+    if (final) {
+        const expectedSha256 = requireFileSha256(payload.sha256);
+        const received = await fs.readFile(tempPath);
+        if (hashBuffer(received) !== expectedSha256) {
+            await fs.rm(tempPath, { force: true });
+            throw new Error('File SHA-256 mismatch.');
+        }
+        try {
+            await commitNewFile(tempPath, targetPath);
+        } catch (error) {
+            await fs.rm(tempPath, { force: true });
+            throw error;
+        }
         const lastModified = Number(payload.lastModified || 0);
         if (lastModified > 0) {
             const modifiedAt = new Date(lastModified);
@@ -1430,7 +1512,20 @@ function normalizeNodeAgentTaskResult(result) {
     return { ...result, ok, status: ok ? 'completed' : 'failed', error };
 }
 
-const NODE_AGENT_OPERATIONS = new Set(['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']);
+const NODE_AGENT_OPERATIONS = new Set(['file.read', 'file.list', 'network.status', 'logs.collect']);
+const RETIRED_NODE_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 remotePolicyAllows(options, command) {
     const policy = options.effectivePolicy;
@@ -1587,8 +1682,8 @@ async function scheduleClientUpdate(options, payload = {}) {
     }
 }
 
-async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
-    const command = String(message.command || '');
+async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
+    const command = String(message.command || '');
     if (command === 'ping') {
         writeJsonLine(socket, {
             type: 'command.result',
@@ -1598,8 +1693,20 @@ async function handleRemoteCommand(socket, options, message, nextFrameSeq, activ
                 at: new Date().toISOString()
             }
         });
-        return;
-    }
+        return;
+    }
+
+    // LD-SEC-AI-001 is enforced before settings or permission modes. A stale
+    // Hub can therefore never revive a retired mutation with full-access.
+    if (RETIRED_NODE_AGENT_MUTATING_OPERATIONS.has(command)) {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            error: 'agent-mutating-tool-disabled',
+            result: { ok: false, status: 'rejected', error: 'agent-mutating-tool-disabled', sideEffects: 'none' }
+        });
+        return;
+    }
 
     const policyDecision = remotePolicyAllows(options, command);
     if (!policyDecision.ok) {
@@ -1900,18 +2007,20 @@ async function handleRemoteCommand(socket, options, message, nextFrameSeq, activ
     });
 }
 
-function connectOnce(options, deviceId) {
-    const manager = parseManagerAddress(options.manager);
-    if (!isPrivateLanHost(manager.host) && !isTruthy(process.env.LIVEDESK_ALLOW_UNENCRYPTED_LAN)) {
-        return Promise.reject(new Error('Plain TCP LiveDesk connections are limited to loopback/private LAN. Use an encrypted endpoint for external connections.'));
-    }
-    return new Promise((resolve, reject) => {
-        const socket = net.createConnection({
-            host: manager.host,
-            port: manager.port
-        });
-
-        let buffer = '';
+async function connectOnce(options, deviceId) {
+    const manager = parseManagerAddress(options.manager);
+    const credentialStore = createClientDeviceCredentialStore({ deviceId });
+    const socket = await connectSecureDirect({
+        host: manager.host,
+        port: manager.port,
+        channel: 'control',
+        deviceId,
+        enrollmentToken: options.pair,
+        credentialStore,
+        timeoutMs: 5000
+    });
+    return new Promise((resolve, reject) => {
+        let buffer = '';
         let heartbeatTimer = null;
         let resolved = false;
         let frameSeq = 0;
@@ -1945,44 +2054,43 @@ function connectOnce(options, deviceId) {
         socket.setNoDelay(true);
         socket.setKeepAlive(true, options.heartbeatMs);
 
-        socket.once('connect', () => {
-            writeJsonLine(socket, {
-                type: 'hello',
-                pairToken: options.pair,
-                deviceId,
-                deviceName: options.name,
-                slotNumber: options.slotNumber || undefined,
-                hostname: os.hostname(),
-                platform: os.platform(),
-                arch: os.arch(),
-                pid: process.pid,
-                agentVersion: AGENT_VERSION,
-                productVersion: PRODUCT_VERSION,
-                capabilities: {
-                    status: true,
-                    thumbnail: options.thumbnailEnabled,
-                    liveStream: options.liveEnabled,
-                    monitorSelection: true,
-                    screenCount: 1,
-                    monitorCount: 1,
-                    control: false,
-                    audio: false,
-                    remoteAudio: false,
-                    fileTransfer: true,
-                    remoteFiles: true,
-                    fileTransferMaxBytes: MAX_FILE_TRANSFER_BYTES,
-                    computerAgent: options.taskEnabled,
-                    taskDispatch: options.taskEnabled,
-                    clientUpdate: true,
-                    productVersion: PRODUCT_VERSION,
-                    agentApproval: options.taskEnabled,
-                    agentAudit: options.taskEnabled,
-                    agentTools: [...NODE_AGENT_OPERATIONS],
-                    elevation: typeof process.getuid === 'function' ? process.getuid() === 0 : false,
-                    externalEffects: options.taskEnabled
-                }
-            });
-        });
+        writeJsonLine(socket, {
+            type: 'hello',
+            deviceId,
+            deviceName: options.name,
+            slotNumber: options.slotNumber || undefined,
+            hostname: os.hostname(),
+            platform: os.platform(),
+            arch: os.arch(),
+            pid: process.pid,
+            agentVersion: AGENT_VERSION,
+            productVersion: PRODUCT_VERSION,
+            capabilities: {
+                status: true,
+                thumbnail: options.thumbnailEnabled,
+                liveStream: options.liveEnabled,
+                monitorSelection: true,
+                screenCount: 1,
+                monitorCount: 1,
+                control: false,
+                audio: false,
+                remoteAudio: false,
+                fileTransfer: true,
+                remoteFiles: true,
+                fileTransferMaxBytes: MAX_FILE_TRANSFER_BYTES,
+                computerAgent: options.taskEnabled,
+                taskDispatch: options.taskEnabled,
+                clientUpdate: true,
+                productVersion: PRODUCT_VERSION,
+                agentApproval: options.taskEnabled,
+                agentAudit: options.taskEnabled,
+                agentTools: [...NODE_AGENT_OPERATIONS],
+                elevation: typeof process.getuid === 'function' ? process.getuid() === 0 : false,
+                externalEffects: false,
+                authenticatedDeviceCredential: true,
+                encryptedDirect: true
+            }
+        });
 
         socket.on('data', chunk => {
             buffer += chunk;

package/bin/livedesk-client.js

@@ -20,11 +20,14 @@ import {
 } from '../src/runtime/agent-process-lifecycle.js';
 import { writeWindowsOwnedProcessManifest } from '../src/runtime/windows-owned-process-manifest.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
+import { createClientDeviceCredentialStore } from '../src/security/device-credential-store.js';
+import { connectSecureDirect } from '../src/security/secure-direct-client.js';
 import {
     inspectLinuxVideoAcceleration,
     installLinuxVideoAcceleration
 } from '../src/runtime/linux-video-acceleration.js';
 import { normalizeRuntimeAuthSession } from '../../runtime-core/src/auth-session.js';
+import { createOsSecretStore, OS_SECRET_REFERENCE } from '../../runtime-core/src/os-secret-store.js';
 import { startRoleTransitionSupervisor } from '../../runtime-core/src/role-transition-supervisor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -66,6 +69,11 @@ const UNIFIED_CLIENT_AUTH_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'auth.json');
 const UNIFIED_CLIENT_PIN_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'pin.json');
 const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
 const CLIENT_HUB_TARGET_CACHE_STORAGE_KEY = 'livedesk.client.last-hub-target';
+const CLIENT_REFRESH_SECRET_STORE = createOsSecretStore({
+    service: 'LiveDesk',
+    account: 'client-refresh-token',
+    dataDir: UNIFIED_CLIENT_STATE_DIR
+});
 const DEVICE_ROLE_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-role.json');
 const FAST_PREFLIGHT_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'fast-preflight.json');
 const CLIENT_SLOT_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-slot.json');
@@ -1051,10 +1059,23 @@ function readSavedSessionFromFile() {
     for (const path of [preferredClientAuthPath(), CLIENT_AUTH_PATH, UNIFIED_CLIENT_AUTH_PATH]) {
         try {
             const state = JSON.parse(readFileSync(path, 'utf8'));
-            const raw = state?.[CLIENT_AUTH_STORAGE_KEY];
-            if (typeof raw !== 'string' || !raw.trim()) continue;
+            const raw = state?.[CLIENT_AUTH_STORAGE_KEY];
+            if (typeof raw !== 'string' || !raw.trim()) continue;
             const session = JSON.parse(raw);
-            const normalized = normalizeRuntimeAuthSession(session, { requireRefreshToken: true });
+            const plaintextRefreshToken = String(session?.refresh_token || '').trim();
+            const refreshToken = plaintextRefreshToken || (session?.refresh_token_ref === OS_SECRET_REFERENCE
+                ? CLIENT_REFRESH_SECRET_STORE.read()
+                : '');
+            if (plaintextRefreshToken) {
+                if (!CLIENT_REFRESH_SECRET_STORE.write(plaintextRefreshToken)) {
+                    createFileStorage(path).removeItem(CLIENT_AUTH_STORAGE_KEY);
+                    continue;
+                }
+                const migrated = { ...session, refresh_token_ref: OS_SECRET_REFERENCE };
+                delete migrated.refresh_token;
+                createFileStorage(path).setItem(CLIENT_AUTH_STORAGE_KEY, JSON.stringify(migrated));
+            }
+            const normalized = normalizeRuntimeAuthSession({ ...session, refresh_token: refreshToken }, { requireRefreshToken: true });
             if (normalized.ok) return { ...session, ...normalized.session };
         } catch {
             // Try the next compatible state location.
@@ -1068,12 +1089,16 @@ function writeSavedSessionToFile(session) {
     if (!normalized.ok) {
         return false;
     }
+    if (!CLIENT_REFRESH_SECRET_STORE.write(normalized.session.refresh_token)) return false;
     const storage = createFileStorage(preferredClientAuthPath());
-    storage.setItem(CLIENT_AUTH_STORAGE_KEY, JSON.stringify({ ...session, ...normalized.session }));
+    const persisted = { ...session, ...normalized.session, refresh_token_ref: OS_SECRET_REFERENCE };
+    delete persisted.refresh_token;
+    storage.setItem(CLIENT_AUTH_STORAGE_KEY, JSON.stringify(persisted));
     return true;
 }
-
-function clearSavedSession() {
+
+function clearSavedSession() {
+    CLIENT_REFRESH_SECRET_STORE.clear();
     rmSync(CLIENT_AUTH_PATH, { force: true });
     rmSync(UNIFIED_CLIENT_AUTH_PATH, { force: true });
 }
@@ -3119,7 +3144,7 @@ async function startConnectionChoiceServer(supabase, options = {}) {
 
             if (requestUrl.pathname === '/logout') {
                 try {
-                    await supabase.auth.signOut();
+                    await supabase.auth.signOut({ scope: 'local' });
                 } catch {
                 }
                 clearSavedSession();
@@ -3570,45 +3595,57 @@ export function shouldSkipAutomaticDirectProbe(endpoint, options = {}) {
         && !isEndpointOnLocalNetwork(endpoint, options.networkInterfaces);
 }
 
-function requestHubSlotAssignment({ manager, pairToken, deviceId, slotNumber, timeoutMs = 5000 }) {
+export async function requestHubSlotAssignment({ manager, pairToken, deviceId, slotNumber, timeoutMs = 5000 }) {
     const endpoint = parseManagerEndpoint(manager);
     const normalizedPairToken = String(pairToken || '').trim();
     const normalizedDeviceId = String(deviceId || '').trim();
     const normalizedSlot = normalizeSlotNumber(slotNumber);
     if (!endpoint) {
-        return Promise.resolve({ ok: false, error: 'hub-endpoint-unavailable' });
+        return { ok: false, error: 'hub-endpoint-unavailable' };
     }
     if (!normalizedPairToken) {
-        return Promise.resolve({ ok: false, error: 'hub-pair-token-unavailable' });
+        return { ok: false, error: 'hub-pair-token-unavailable' };
     }
     if (!normalizedDeviceId) {
-        return Promise.resolve({ ok: false, error: 'device-id-required' });
+        return { ok: false, error: 'device-id-required' };
     }
     if (!normalizedSlot) {
-        return Promise.resolve({ ok: false, error: 'invalid-slot-number' });
+        return { ok: false, error: 'invalid-slot-number' };
+    }
+
+    let socket;
+    try {
+        const credentialStore = createClientDeviceCredentialStore({ deviceId: normalizedDeviceId });
+        socket = await connectSecureDirect({
+            host: endpoint.host,
+            port: endpoint.port,
+            channel: 'control',
+            deviceId: normalizedDeviceId,
+            enrollmentToken: normalizedPairToken,
+            credentialStore,
+            timeoutMs
+        });
+    } catch (error) {
+        return { ok: false, error: error?.code || error?.message || 'hub-slot-secure-connect-failed' };
     }
 
     return new Promise(resolveAssignment => {
-        const socket = net.createConnection(endpoint);
         let settled = false;
         let buffer = '';
+        const timer = setTimeout(
+            () => settle({ ok: false, error: 'hub-slot-request-timeout' }),
+            Math.max(250, Math.min(30_000, Number(timeoutMs) || 5000))
+        );
+        timer.unref?.();
         const settle = result => {
             if (settled) return;
             settled = true;
+            clearTimeout(timer);
             socket.removeAllListeners();
             socket.destroy();
             resolveAssignment(result);
         };
         socket.setEncoding('utf8');
-        socket.setTimeout(timeoutMs);
-        socket.once('connect', () => {
-            socket.write(`${JSON.stringify({
-                type: 'slot.assign',
-                pairToken: normalizedPairToken,
-                deviceId: normalizedDeviceId,
-                slotNumber: Number(normalizedSlot)
-            })}\n`);
-        });
         socket.on('data', chunk => {
             buffer += chunk;
             const newlineIndex = buffer.indexOf('\n');
@@ -3624,11 +3661,15 @@ function requestHubSlotAssignment({ manager, pairToken, deviceId, slotNumber, ti
                 settle({ ok: false, error: 'invalid-hub-response' });
             }
         });
-        socket.once('timeout', () => settle({ ok: false, error: 'hub-slot-request-timeout' }));
         socket.once('error', error => settle({ ok: false, error: error?.message || 'hub-slot-request-failed' }));
         socket.once('close', () => {
-            if (!settled) settle({ ok: false, error: 'hub-slot-response-missing' });
+                if (!settled) settle({ ok: false, error: 'hub-slot-response-missing' });
         });
+        socket.write(`${JSON.stringify({
+            type: 'slot.assign',
+            deviceId: normalizedDeviceId,
+            slotNumber: Number(normalizedSlot)
+        })}\n`);
     });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.222",
+  "version": "0.1.224",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
   "scripts": {
     "check": "node --check bin/client-version.js && node --check bin/livedesk-client.js && node --check bin/livedesk-client-node.js && node --check bin/livedesk-client-update-bootstrap.cjs && node --check bin/livedesk-client-fast.js",
     "test:version": "node --test tests/client-version.test.mjs",
-    "pack:dry": "npm pack --dry-run"
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "node ../../scripts/livedesk-release-git-gate.mjs"
   },
   "keywords": [
     "livedesk",
@@ -35,16 +36,16 @@
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "ffmpeg-static": "^5.3.0",
-    "@livedesk/runtime-core": "0.1.1",
+    "@livedesk/runtime-core": "0.1.3",
     "@supabase/supabase-js": "^2.110.0",
     "node-screenshots": "^0.2.8",
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.427",
-    "@livedesk/fast-osx-arm64": "0.1.427",
-    "@livedesk/fast-osx-x64": "0.1.427",
-    "@livedesk/fast-win-x64": "0.1.427"
+    "@livedesk/fast-linux-x64": "0.1.429",
+    "@livedesk/fast-osx-arm64": "0.1.429",
+    "@livedesk/fast-osx-x64": "0.1.429",
+    "@livedesk/fast-win-x64": "0.1.429"
   },
   "publishConfig": {
     "access": "public"

package/src/runtime/client-runtime-server.js

@@ -5,6 +5,7 @@ import { accessSync, chmodSync, constants as fsConstants, existsSync, mkdirSync,
 import { delimiter, dirname, join, parse, posix, resolve } from 'node:path';
 import os from 'node:os';
 import { createRuntimeManager, normalizeRuntimeAuthSession, runtimeRoleError, RuntimeState } from '../../../runtime-core/src/index.js';
+import { createOsSecretStore, OS_SECRET_REFERENCE } from '../../../runtime-core/src/os-secret-store.js';
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 5179;
@@ -20,6 +21,11 @@ const SUPABASE_URL = process.env.LIVEDESK_SUPABASE_URL || 'https://otbyfkjxrkngv
 const SUPABASE_PUBLISHABLE_KEY = process.env.LIVEDESK_SUPABASE_PUBLISHABLE_KEY || 'sb_publishable_NpUs0RDJH2YnllsqTKO6TQ_1jTdSsNQ';
 const CLIENT_STATE_DIR = process.env.LIVEDESK_STATE_DIR || (process.env.LIVEDESK_UNIFIED_RUNTIME === '1' ? join(os.homedir(), '.livedesk') : join(os.homedir(), '.livedesk-client'));
 const CLIENT_AUTH_PATH = join(CLIENT_STATE_DIR, 'auth.json');
+const CLIENT_REFRESH_SECRET_STORE = createOsSecretStore({
+  service: 'LiveDesk',
+  account: 'client-refresh-token',
+  dataDir: CLIENT_STATE_DIR
+});
 const DEFAULT_TRUSTED_WEB_ORIGINS = Object.freeze([
   'https://livedesk.pages.dev',
   'http://127.0.0.1:5173',
@@ -950,13 +956,35 @@ function readSavedSession() {
   if (process.env.LIVEDESK_DESKTOP_HOST === '1') return null;
   try {
     const raw = JSON.parse(readFileSync(CLIENT_AUTH_PATH, 'utf8'))?.[CLIENT_AUTH_STORAGE_KEY];
-    const session = typeof raw === 'string' ? JSON.parse(raw) : null;
-    return session?.access_token ? session : null;
+    const session = typeof raw === 'string' ? JSON.parse(raw) : null;
+    if (!session?.access_token) return null;
+    const plaintextRefreshToken = normalizeString(session.refresh_token, 8192);
+    const refreshToken = plaintextRefreshToken || (session.refresh_token_ref === OS_SECRET_REFERENCE
+      ? CLIENT_REFRESH_SECRET_STORE.read()
+      : '');
+    if (!refreshToken) return null;
+    if (plaintextRefreshToken) {
+      if (!CLIENT_REFRESH_SECRET_STORE.write(plaintextRefreshToken)) {
+        writePrivateJsonAtomic(CLIENT_AUTH_PATH, {});
+        return null;
+      }
+      const migrated = { ...session, refresh_token_ref: OS_SECRET_REFERENCE };
+      delete migrated.refresh_token;
+      writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(migrated) });
+    }
+    return { ...session, refresh_token: refreshToken };
   } catch {
     return null;
   }
 }
 
+function resolveSavedSessionSecret(session) {
+  if (!session || typeof session !== 'object') return null;
+  const refreshToken = normalizeString(session.refresh_token, 8192)
+    || (session.refresh_token_ref === OS_SECRET_REFERENCE ? CLIENT_REFRESH_SECRET_STORE.read() : '');
+  return session.access_token && refreshToken ? { ...session, refresh_token: refreshToken } : null;
+}
+
 function writePrivateJsonAtomic(path, value) {
   mkdirSync(dirname(path), { recursive: true });
   const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
@@ -974,13 +1002,45 @@ function writePrivateJsonAtomic(path, value) {
 function writeSavedSession(session) {
   if (!session?.access_token || !session?.refresh_token) return false;
   if (process.env.LIVEDESK_DESKTOP_HOST === '1') return true;
-  writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(session) });
+  if (!CLIENT_REFRESH_SECRET_STORE.write(session.refresh_token)) return false;
+  const persisted = { ...session, refresh_token_ref: OS_SECRET_REFERENCE };
+  delete persisted.refresh_token;
+  writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(persisted) });
   return true;
 }
 
 function clearSavedSession() {
+  CLIENT_REFRESH_SECRET_STORE.clear();
   writePrivateJsonAtomic(CLIENT_AUTH_PATH, {});
 }
+
+export async function revokeClientProviderSession(session, options = {}) {
+  const accessToken = normalizeString(session?.access_token, 8192);
+  if (!accessToken) return { ok: true, skipped: true, reason: 'no-access-token' };
+  try {
+    if (typeof options.revokeProviderSession === 'function') {
+      const result = await options.revokeProviderSession(session);
+      return result && typeof result === 'object' ? result : { ok: result !== false };
+    }
+    const fetchImpl = typeof options.fetchImpl === 'function' ? options.fetchImpl : fetch;
+    const response = await fetchImpl(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/logout?scope=local`, {
+      method: 'POST',
+      headers: {
+        apikey: SUPABASE_PUBLISHABLE_KEY,
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json'
+      },
+      signal: AbortSignal.timeout(10_000)
+    });
+    if (response.ok) return { ok: true, revoked: true };
+    if ([401, 403, 404].includes(response.status)) {
+      return { ok: true, alreadyInvalid: true, status: response.status };
+    }
+    return { ok: false, error: `provider-session-revoke-failed:${response.status}` };
+  } catch (error) {
+    return { ok: false, error: normalizeString(error?.message || error, 240) || 'provider-session-revoke-failed' };
+  }
+}
 
 function readBody(req) {
   return new Promise((resolveBody, reject) => {
@@ -1114,12 +1174,13 @@ export function createClientRuntimeServer(options = {}) {
   const trustedWebOrigins = createTrustedWebOrigins(port);
   const webDist = resolve(String(options.webDist || process.env.LIVEDESK_WEB_DIST || '').trim() || join(process.cwd(), 'apps', 'web', 'dist'));
   const deviceId = normalizeString(options.deviceId || process.env.LIVEDESK_DEVICE_ID, 160);
-  const deviceName = normalizeString(options.deviceName || os.hostname(), 160) || os.hostname();
+  const deviceName = normalizeString(options.deviceName || os.hostname(), 160) || os.hostname();
   const appVersion = normalizeString(options.appVersion || process.env.LIVEDESK_NPM_LAUNCHER_VERSION, 80) || 'dev';
+  const providedSavedSession = resolveSavedSessionSecret(options.savedSession);
   const savedSession = options.loadSavedSession === false
     ? null
-    : options.savedSession?.refresh_token
-      ? options.savedSession
+    : providedSavedSession
+      ? providedSavedSession
       : readSavedSession();
   const savedSessionPersisted = Boolean(savedSession?.refresh_token);
   const savedAccountProfile = readClientAccountProfile(savedSession);
@@ -1635,8 +1696,13 @@ export function createClientRuntimeServer(options = {}) {
       complete({ type: 'google', session }, 'Signed in. Finding the LiveDesk Hub.');
       respondJson(200, { ok: true, authenticated: true, persisted: true, role: 'client' });
       return;
-    }
-    if (pathname === '/api/auth/session' && req.method === 'DELETE') {
+    }
+    if (pathname === '/api/auth/session' && req.method === 'DELETE') {
+      const activeSession = lastChoice?.session || savedSession || readSavedSession();
+      const providerLogout = await revokeClientProviderSession(activeSession, {
+        revokeProviderSession: options.revokeProviderSession,
+        fetchImpl: options.fetchImpl
+      });
       clearSavedSession();
       loggedOut = true;
       completed = false;
@@ -1653,9 +1719,15 @@ export function createClientRuntimeServer(options = {}) {
         name: '',
         avatarUrl: ''
       };
-      runtime.setAuthenticated(false);
-      respondJson(200, { ok: true, authenticated: false, role: 'client' });
-      return;
+      runtime.setAuthenticated(false);
+      respondJson(providerLogout.ok ? 200 : 502, {
+        ok: providerLogout.ok,
+        authenticated: false,
+        localCleared: true,
+        role: 'client',
+        providerLogout
+      });
+      return;
     }
     if (pathname === '/api/runtime/restart' && req.method === 'POST') {
       runtime.emit('runtime.restart.requested', { role: 'client' });

package/src/security/device-credential-store.js

@@ -0,0 +1,190 @@
+import crypto from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { decodeCanonicalBase64Url } from '@livedesk/runtime-core';
+import { createOsSecretStore, OS_SECRET_REFERENCE } from '@livedesk/runtime-core/os-secret-store';
+
+const STORE_VERSION = 1;
+
+function credentialError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function clean(value, maximum = 512) {
+  return String(value || '').replace(/[\0\r\n]/g, '').trim().slice(0, maximum);
+}
+
+function atomicPrivateJson(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, filePath);
+}
+
+function loadJson(filePath) {
+  try {
+    const value = JSON.parse(readFileSync(filePath, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function requirePrivateKey(value) {
+  const der = decodeCanonicalBase64Url(value, 100, 512);
+  let key;
+  try {
+    key = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  } catch {
+    throw credentialError('device-private-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw credentialError('device-private-key-invalid');
+  }
+  return key;
+}
+
+function parseCredential(credential) {
+  const text = String(credential || '');
+  const parts = text.split('.');
+  if (parts.length !== 2 || text.length > 8192) throw credentialError('device-credential-invalid');
+  const payloadBytes = decodeCanonicalBase64Url(parts[0], 32, 4096);
+  const signature = decodeCanonicalBase64Url(parts[1], 64, 64);
+  let payload;
+  try {
+    payload = JSON.parse(payloadBytes.toString('utf8'));
+  } catch {
+    throw credentialError('device-credential-invalid');
+  }
+  if (!payload || Number(payload.version) !== 1) throw credentialError('device-credential-invalid');
+  const hubPublicDer = decodeCanonicalBase64Url(payload.hubPublicKey, 80, 160);
+  let hubPublicKey;
+  try {
+    hubPublicKey = crypto.createPublicKey({ key: hubPublicDer, format: 'der', type: 'spki' });
+  } catch {
+    throw credentialError('device-credential-invalid');
+  }
+  if (hubPublicKey.asymmetricKeyType !== 'ec'
+    || hubPublicKey.asymmetricKeyDetails?.namedCurve !== 'prime256v1'
+    || !crypto.verify('sha256', Buffer.from(parts[0], 'utf8'), { key: hubPublicKey, dsaEncoding: 'ieee-p1363' }, signature)) {
+    throw credentialError('device-credential-signature-invalid');
+  }
+  const normalized = {
+    serial: clean(payload.serial, 128),
+    accountId: clean(payload.accountId, 128),
+    hubId: clean(payload.hubId, 128),
+    deviceId: clean(payload.deviceId, 128),
+    devicePublicKey: clean(payload.devicePublicKey, 512),
+    hubPublicKey: hubPublicDer.toString('base64url'),
+    issuedAt: Number(payload.issuedAt),
+    expiresAt: Number(payload.expiresAt)
+  };
+  if (!normalized.serial || !normalized.accountId || !normalized.hubId || !normalized.deviceId
+    || !Number.isSafeInteger(normalized.issuedAt) || !Number.isSafeInteger(normalized.expiresAt)
+    || normalized.expiresAt <= Date.now()) {
+    throw credentialError('device-credential-expired');
+  }
+  return { text, payloadText: parts[0], payload: normalized, hubPublicKey };
+}
+
+export function createClientDeviceCredentialStore({
+  filePath = String(process.env.LIVEDESK_DEVICE_CREDENTIAL_PATH || '').trim()
+    || path.join(os.homedir(), '.livedesk-client', 'device-credential-v1.json'),
+  deviceId
+} = {}) {
+  const normalizedDeviceId = clean(deviceId, 128);
+  if (!normalizedDeviceId) throw credentialError('device-id-required');
+  const privateKeyStore = createOsSecretStore({
+    service: 'LiveDesk',
+    account: `client-device-private-key:${normalizedDeviceId}`,
+    dataDir: path.dirname(filePath)
+  });
+  let state = loadJson(filePath);
+  let privateKey;
+  let publicKey;
+  if (state) {
+    if (Number(state.version) !== STORE_VERSION || state.deviceId !== normalizedDeviceId) throw credentialError('device-key-state-invalid');
+    const plaintextPrivateKey = clean(state.privateKey, 1024);
+    if (plaintextPrivateKey) {
+      if (!privateKeyStore.write(plaintextPrivateKey)) throw credentialError('device-private-key-migration-failed');
+      state = { ...state, privateKeyRef: OS_SECRET_REFERENCE, updatedAt: new Date().toISOString() };
+      delete state.privateKey;
+      atomicPrivateJson(filePath, state);
+    }
+    if (state.privateKeyRef !== OS_SECRET_REFERENCE) throw credentialError('device-private-key-reference-invalid');
+    const privateKeyText = privateKeyStore.read();
+    if (!privateKeyText) throw credentialError('device-private-key-secure-store-unavailable');
+    privateKey = requirePrivateKey(privateKeyText);
+    publicKey = crypto.createPublicKey(privateKey);
+    const publicText = publicKey.export({ format: 'der', type: 'spki' }).toString('base64url');
+    if (publicText !== state.publicKey) throw credentialError('device-key-mismatch');
+  } else {
+    const generated = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    privateKey = generated.privateKey;
+    publicKey = generated.publicKey;
+    const privateKeyText = privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url');
+    if (!privateKeyStore.write(privateKeyText)) throw credentialError('device-private-key-secure-store-unavailable');
+    state = {
+      version: STORE_VERSION,
+      deviceId: normalizedDeviceId,
+      publicKey: publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'),
+      privateKeyRef: OS_SECRET_REFERENCE,
+      credential: '',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    atomicPrivateJson(filePath, state);
+  }
+
+  function saveCredential(credential) {
+    const parsed = parseCredential(credential);
+    if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) {
+      throw credentialError('device-credential-binding-invalid');
+    }
+    state.credential = parsed.text;
+    state.accountId = parsed.payload.accountId;
+    state.hubId = parsed.payload.hubId;
+    state.updatedAt = new Date().toISOString();
+    atomicPrivateJson(filePath, state);
+    return parsed;
+  }
+
+  function readCredential() {
+    if (!state.credential) return null;
+    try {
+      const parsed = parseCredential(state.credential);
+      if (parsed.payload.deviceId !== normalizedDeviceId || parsed.payload.devicePublicKey !== state.publicKey) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  function clearCredential() {
+    state.credential = '';
+    state.accountId = '';
+    state.hubId = '';
+    state.updatedAt = new Date().toISOString();
+    atomicPrivateJson(filePath, state);
+  }
+
+  return Object.freeze({
+    filePath,
+    deviceId: normalizedDeviceId,
+    publicKey: state.publicKey,
+    privateKey,
+    sign(message) {
+      return crypto.sign('sha256', Buffer.from(String(message || ''), 'utf8'), {
+        key: privateKey,
+        dsaEncoding: 'ieee-p1363'
+      }).toString('base64url');
+    },
+    readCredential,
+    saveCredential,
+    clearCredential,
+    parseCredential
+  });
+}

package/src/security/secure-direct-client.js

@@ -0,0 +1,224 @@
+import crypto from 'node:crypto';
+import net from 'node:net';
+import {
+  SECURE_SESSION_MAX_CLOCK_SKEW_MS,
+  SECURE_SESSION_MAX_HANDSHAKE_BYTES,
+  SECURE_SESSION_PROTOCOL,
+  SecureRecordSocket,
+  decodeCanonicalBase64Url,
+  deriveSecureSessionKey,
+  enrollmentProof,
+  fixedTimeBase64UrlEqual,
+  normalizeSecureChannel,
+  secureClientTranscript,
+  secureServerTranscript
+} from '@livedesk/runtime-core';
+
+const CONNECT_TIMEOUT_MS = 5_000;
+
+function secureError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function clean(value, maximum = 256) {
+  return String(value || '').replace(/[\0\r\n]/g, '').trim().slice(0, maximum);
+}
+
+function requireP256PublicKey(value) {
+  const der = decodeCanonicalBase64Url(value, 80, 160);
+  let key;
+  try {
+    key = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    throw secureError('secure-public-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw secureError('secure-public-key-invalid');
+  }
+  return key;
+}
+
+async function connectRaw(host, port, timeoutMs) {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host, port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(secureError('secure-direct-connect-timeout'));
+    }, timeoutMs);
+    timer.unref?.();
+    socket.once('connect', () => {
+      clearTimeout(timer);
+      socket.setNoDelay(true);
+      resolve(socket);
+    });
+    socket.once('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+async function readHandshakeLine(socket, timeoutMs) {
+  return await new Promise((resolve, reject) => {
+    let chunks = [];
+    let bytes = 0;
+    const timer = setTimeout(() => finish(secureError('secure-server-hello-timeout')), timeoutMs);
+    timer.unref?.();
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onError);
+      socket.removeListener('close', onClose);
+    };
+    const finish = (error, value) => {
+      cleanup();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onError = error => finish(error);
+    const onClose = () => finish(secureError('secure-server-hello-closed'));
+    const onData = chunk => {
+      const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk || []);
+      bytes += incoming.length;
+      if (bytes > SECURE_SESSION_MAX_HANDSHAKE_BYTES) {
+        finish(secureError('secure-server-hello-too-large'));
+        return;
+      }
+      chunks.push(incoming);
+      const combined = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, bytes);
+      const newline = combined.indexOf(0x0a);
+      if (newline < 0) return;
+      let message;
+      try {
+        message = JSON.parse(combined.subarray(0, newline).toString('utf8'));
+      } catch {
+        finish(secureError('secure-server-hello-invalid'));
+        return;
+      }
+      finish(null, { message, remainder: combined.subarray(newline + 1) });
+    };
+    socket.on('data', onData);
+    socket.once('error', onError);
+    socket.once('close', onClose);
+  });
+}
+
+export async function connectSecureDirect({
+  host,
+  port,
+  channel = 'control',
+  deviceId,
+  enrollmentToken,
+  credentialStore,
+  timeoutMs = CONNECT_TIMEOUT_MS
+} = {}) {
+  const normalizedChannel = normalizeSecureChannel(channel);
+  const normalizedDeviceId = clean(deviceId, 128);
+  if (!normalizedDeviceId || !credentialStore?.privateKey || credentialStore.deviceId !== normalizedDeviceId) {
+    throw secureError('device-credential-store-required');
+  }
+  const existingCredential = credentialStore.readCredential();
+  const mode = existingCredential ? 'resume' : 'enroll';
+  if (mode === 'enroll' && normalizedChannel !== 'control') throw secureError('secure-enrollment-control-channel-required');
+  const generated = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+  const hello = {
+    type: 'secure.client-hello',
+    protocol: SECURE_SESSION_PROTOCOL,
+    mode,
+    channel: normalizedChannel,
+    timestamp: Date.now(),
+    nonce: crypto.randomBytes(16).toString('base64url'),
+    deviceId: normalizedDeviceId,
+    devicePublicKey: credentialStore.publicKey,
+    clientEphemeralPublicKey: generated.publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'),
+    ...(existingCredential ? { credential: existingCredential.text } : {})
+  };
+  const clientTranscript = secureClientTranscript(hello);
+  hello.deviceSignature = credentialStore.sign(clientTranscript);
+  if (mode === 'enroll') hello.enrollmentProof = enrollmentProof(enrollmentToken, clientTranscript);
+
+  const socket = await connectRaw(host, port, Math.max(250, Math.min(30_000, Number(timeoutMs) || CONNECT_TIMEOUT_MS)));
+  try {
+    socket.write(`${JSON.stringify(hello)}\n`);
+    const { message: response, remainder } = await readHandshakeLine(socket, timeoutMs);
+    if (response?.type === 'secure.error') throw secureError(clean(response.error, 100) || 'secure-handshake-rejected');
+    if (response?.type !== 'secure.server-hello'
+      || response.protocol !== SECURE_SESSION_PROTOCOL
+      || response.channel !== normalizedChannel
+      || response.deviceId !== normalizedDeviceId) {
+      throw secureError('secure-server-hello-invalid');
+    }
+    if (!Number.isSafeInteger(Number(response.timestamp))
+      || Math.abs(Date.now() - Number(response.timestamp)) > SECURE_SESSION_MAX_CLOCK_SKEW_MS) {
+      throw secureError('secure-server-timestamp-invalid');
+    }
+    decodeCanonicalBase64Url(response.sessionId, 16, 32);
+    decodeCanonicalBase64Url(response.serverNonce, 16, 32);
+    const serverEphemeralPublicKey = requireP256PublicKey(response.serverEphemeralPublicKey);
+    const parsedCredential = credentialStore.parseCredential(response.credential);
+    if (parsedCredential.payload.deviceId !== normalizedDeviceId
+      || parsedCredential.payload.devicePublicKey !== credentialStore.publicKey
+      || response.hubId !== parsedCredential.payload.hubId
+      || response.accountId !== parsedCredential.payload.accountId) {
+      throw secureError('device-credential-binding-invalid');
+    }
+    if (existingCredential
+      && (parsedCredential.payload.hubId !== existingCredential.payload.hubId
+        || parsedCredential.payload.accountId !== existingCredential.payload.accountId
+        || parsedCredential.payload.hubPublicKey !== existingCredential.payload.hubPublicKey)) {
+      throw secureError('secure-hub-identity-changed');
+    }
+    const serverTranscript = secureServerTranscript(response, clientTranscript);
+    if (mode === 'enroll') {
+      const expectedServerProof = enrollmentProof(enrollmentToken, serverTranscript);
+      if (!fixedTimeBase64UrlEqual(response.enrollmentServerProof, expectedServerProof, 32)) {
+        throw secureError('secure-enrollment-server-proof-invalid');
+      }
+    }
+    const hubSignature = decodeCanonicalBase64Url(response.hubSignature, 64, 64);
+    if (!crypto.verify('sha256', Buffer.from(serverTranscript, 'utf8'), {
+      key: parsedCredential.hubPublicKey,
+      dsaEncoding: 'ieee-p1363'
+    }, hubSignature)) {
+      throw secureError('secure-hub-signature-invalid');
+    }
+    const sharedSecret = crypto.diffieHellman({ privateKey: generated.privateKey, publicKey: serverEphemeralPublicKey });
+    let sessionKey;
+    try {
+      sessionKey = deriveSecureSessionKey({
+        sharedSecret,
+        clientTranscript,
+        serverTranscript,
+        sessionId: response.sessionId,
+        channel: normalizedChannel
+      });
+    } finally {
+      sharedSecret.fill(0);
+    }
+    if (!existingCredential || existingCredential.text !== parsedCredential.text) credentialStore.saveCredential(parsedCredential.text);
+    const secureSocket = new SecureRecordSocket(socket, {
+      sessionKey,
+      sessionId: response.sessionId,
+      channel: normalizedChannel,
+      role: 'client',
+      securityContext: {
+        protocol: SECURE_SESSION_PROTOCOL,
+        accountId: parsedCredential.payload.accountId,
+        hubId: parsedCredential.payload.hubId,
+        deviceId: normalizedDeviceId,
+        credentialSerial: parsedCredential.payload.serial,
+        authenticated: true,
+        encrypted: true
+      }
+    });
+    sessionKey.fill(0);
+    secureSocket.__liveDeskDirectSecure = true;
+    if (remainder.length > 0) secureSocket.feedEncrypted(remainder);
+    return secureSocket;
+  } catch (error) {
+    socket.destroy();
+    throw error;
+  }
+}