livedesk 0.1.613 → 0.1.615

package/runtime-core/src/direct-secure-transport.js

@@ -0,0 +1,752 @@
+import crypto from 'node:crypto';
+import net from 'node:net';
+import { Duplex } from 'node:stream';
+
+export const DIRECT_SECURE_PROTOCOL = 'livedesk.direct.secure.v1';
+export const DIRECT_SECURE_MAGIC = Buffer.from('LDS1', 'ascii');
+
+const VALID_CHANNELS = new Set(['control', 'frame', 'audio', 'file', 'input']);
+const HANDSHAKE_HEADER_BYTES = 8;
+const MAX_HANDSHAKE_BYTES = 8 * 1024;
+const RECORD_HEADER_BYTES = 12;
+const RECORD_TAG_BYTES = 16;
+const MAX_RECORD_PLAINTEXT_BYTES = 256 * 1024;
+const MAX_ENCRYPTED_ACCUMULATOR_BYTES = 4 * 1024 * 1024;
+const MAX_HANDSHAKE_ACCUMULATOR_BYTES = HANDSHAKE_HEADER_BYTES
+  + MAX_HANDSHAKE_BYTES
+  + MAX_ENCRYPTED_ACCUMULATOR_BYTES;
+const MAX_SAFE_SEQUENCE = 9_007_199_254_740_991n;
+const CLIENT_NONCE_BYTES = 16;
+const HUB_NONCE_BYTES = 16;
+const PUBLIC_KEY_BYTES = 65;
+const PROOF_BYTES = 32;
+const CLIENT_DIRECTION = 'client-to-hub';
+const HUB_DIRECTION = 'hub-to-client';
+const CLIENT_NONCE_PREFIX = Buffer.from('LDCH', 'ascii');
+const HUB_NONCE_PREFIX = Buffer.from('LDHC', 'ascii');
+
+class BoundedByteSegments {
+  constructor(maxBytes) {
+    this.maxBytes = maxBytes;
+    this.chunks = [];
+    this.headIndex = 0;
+    this.headOffset = 0;
+    this.byteLength = 0;
+  }
+
+  get length() {
+    return this.byteLength;
+  }
+
+  append(value) {
+    const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value || []);
+    if (chunk.length === 0) return true;
+    if (chunk.length > this.maxBytes - this.byteLength) return false;
+    this.chunks.push(chunk);
+    this.byteLength += chunk.length;
+    return true;
+  }
+
+  byteAt(index) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.byteLength) return undefined;
+    let remaining = index;
+    for (let chunkIndex = this.headIndex; chunkIndex < this.chunks.length; chunkIndex += 1) {
+      const chunk = this.chunks[chunkIndex];
+      const start = chunkIndex === this.headIndex ? this.headOffset : 0;
+      const available = chunk.length - start;
+      if (remaining < available) return chunk[start + remaining];
+      remaining -= available;
+    }
+    return undefined;
+  }
+
+  readUInt32BE(index) {
+    const bytes = [0, 1, 2, 3].map(offset => this.byteAt(index + offset));
+    if (bytes.some(value => value === undefined)) return null;
+    return (((bytes[0] << 24) >>> 0)
+      | (bytes[1] << 16)
+      | (bytes[2] << 8)
+      | bytes[3]) >>> 0;
+  }
+
+  readBigUInt64BE(index) {
+    let value = 0n;
+    for (let offset = 0; offset < 8; offset += 1) {
+      const byte = this.byteAt(index + offset);
+      if (byte === undefined) return null;
+      value = (value << 8n) | BigInt(byte);
+    }
+    return value;
+  }
+
+  readExact(index, length) {
+    if (!Number.isInteger(index)
+      || !Number.isInteger(length)
+      || index < 0
+      || length < 0
+      || index + length > this.byteLength) {
+      return null;
+    }
+    const output = Buffer.allocUnsafeSlow(length);
+    let skip = index;
+    let written = 0;
+    for (let chunkIndex = this.headIndex; chunkIndex < this.chunks.length && written < length; chunkIndex += 1) {
+      const chunk = this.chunks[chunkIndex];
+      const baseOffset = chunkIndex === this.headIndex ? this.headOffset : 0;
+      const available = chunk.length - baseOffset;
+      if (skip >= available) {
+        skip -= available;
+        continue;
+      }
+      const sourceStart = baseOffset + skip;
+      const copyLength = Math.min(length - written, chunk.length - sourceStart);
+      chunk.copy(output, written, sourceStart, sourceStart + copyLength);
+      written += copyLength;
+      skip = 0;
+    }
+    return written === length ? output : null;
+  }
+
+  discard(length) {
+    let remaining = Math.max(0, Math.min(this.byteLength, Number(length) || 0));
+    const discarded = remaining;
+    while (remaining > 0 && this.headIndex < this.chunks.length) {
+      const chunk = this.chunks[this.headIndex];
+      const available = chunk.length - this.headOffset;
+      if (remaining < available) {
+        this.headOffset += remaining;
+        remaining = 0;
+        break;
+      }
+      remaining -= available;
+      this.chunks[this.headIndex] = null;
+      this.headIndex += 1;
+      this.headOffset = 0;
+    }
+    this.byteLength -= discarded;
+    if (this.byteLength === 0) {
+      this.clear();
+    } else if (this.headIndex >= 64 && this.headIndex * 2 >= this.chunks.length) {
+      this.chunks = this.chunks.slice(this.headIndex);
+      this.headIndex = 0;
+    }
+    return discarded;
+  }
+
+  clear() {
+    this.chunks = [];
+    this.headIndex = 0;
+    this.headOffset = 0;
+    this.byteLength = 0;
+  }
+}
+
+function base64Url(value) {
+  return Buffer.from(value).toString('base64url');
+}
+
+export function isDirectSecureChannel(value) {
+  return VALID_CHANNELS.has(String(value || '').trim().toLowerCase());
+}
+
+function requireSecureChannel(value) {
+  const channel = String(value || '').trim().toLowerCase();
+  if (!VALID_CHANNELS.has(channel)) throw new Error('direct-secure-channel-invalid');
+  return channel;
+}
+
+function decodeBase64Url(value, expectedBytes) {
+  const text = String(value || '').trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(text)) throw new Error('direct-secure-base64-invalid');
+  const decoded = Buffer.from(text, 'base64url');
+  if (decoded.length !== expectedBytes || base64Url(decoded) !== text) {
+    throw new Error('direct-secure-base64-invalid');
+  }
+  return decoded;
+}
+
+function hmac(key, value) {
+  return crypto.createHmac('sha256', key).update(value, 'utf8').digest();
+}
+
+function timingSafeEqual(left, right) {
+  return Buffer.isBuffer(left)
+    && Buffer.isBuffer(right)
+    && left.length === right.length
+    && crypto.timingSafeEqual(left, right);
+}
+
+function deriveKey(sharedSecret, salt, info) {
+  return Buffer.from(crypto.hkdfSync(
+    'sha256',
+    sharedSecret,
+    salt,
+    Buffer.from(info, 'utf8'),
+    32));
+}
+
+function buildNonce(prefix, sequence) {
+  const nonce = Buffer.allocUnsafe(12);
+  prefix.copy(nonce, 0);
+  nonce.writeBigUInt64BE(sequence, 4);
+  return nonce;
+}
+
+function buildAad(direction, header) {
+  return Buffer.concat([
+    Buffer.from(DIRECT_SECURE_PROTOCOL, 'utf8'),
+    Buffer.from([0]),
+    Buffer.from(direction, 'utf8'),
+    Buffer.from([0]),
+    header
+  ]);
+}
+
+function encodeHandshake(payload) {
+  const json = Buffer.from(JSON.stringify(payload), 'utf8');
+  if (json.length < 1 || json.length > MAX_HANDSHAKE_BYTES) {
+    throw new Error('direct-secure-handshake-size-invalid');
+  }
+  const frame = Buffer.allocUnsafe(HANDSHAKE_HEADER_BYTES + json.length);
+  DIRECT_SECURE_MAGIC.copy(frame, 0);
+  frame.writeUInt32BE(json.length, 4);
+  json.copy(frame, HANDSHAKE_HEADER_BYTES);
+  return frame;
+}
+
+function isMagicPrefix(value) {
+  const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value || []);
+  const compareLength = Math.min(chunk.length, DIRECT_SECURE_MAGIC.length);
+  return compareLength > 0
+    && chunk.subarray(0, compareLength).equals(DIRECT_SECURE_MAGIC.subarray(0, compareLength));
+}
+
+export function isSecureDirectHandshakeStart(firstChunk) {
+  return isMagicPrefix(firstChunk);
+}
+
+function readHandshake(socket, firstChunk, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const buffer = new BoundedByteSegments(MAX_HANDSHAKE_ACCUMULATOR_BYTES);
+    let settled = false;
+    let expectedLength = -1;
+    const timer = setTimeout(
+      () => fail(new Error('direct-secure-handshake-timeout')),
+      Math.max(500, Math.min(10_000, Number(timeoutMs) || 4_000)));
+    timer.unref?.();
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onError);
+      socket.removeListener('close', onClose);
+    };
+    const fail = error => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      buffer.clear();
+      reject(error);
+    };
+    const complete = () => {
+      const total = HANDSHAKE_HEADER_BYTES + expectedLength;
+      if (settled || expectedLength < 0 || buffer.length < total) return;
+      const jsonBytes = buffer.readExact(HANDSHAKE_HEADER_BYTES, expectedLength);
+      const remainderLength = buffer.length - total;
+      const remainder = remainderLength > 0 ? buffer.readExact(total, remainderLength) : Buffer.alloc(0);
+      if (!jsonBytes || !remainder) {
+        fail(new Error('direct-secure-handshake-read-failed'));
+        return;
+      }
+      let message;
+      try {
+        message = JSON.parse(jsonBytes.toString('utf8'));
+      } catch {
+        fail(new Error('direct-secure-handshake-json-invalid'));
+        return;
+      }
+      // A successful handshake changes the owner of this raw stream. Stop the
+      // flowing socket before removing our data listener so bytes arriving in
+      // the short handoff window are retained for SecureDirectDuplex.
+      socket.pause();
+      settled = true;
+      cleanup();
+      buffer.clear();
+      resolve({ message, remainder });
+    };
+    const append = value => {
+      if (settled) return;
+      if (!buffer.append(value)) {
+        fail(new Error('direct-secure-handshake-too-large'));
+        return;
+      }
+      if (buffer.length >= DIRECT_SECURE_MAGIC.length) {
+        const magic = buffer.readExact(0, DIRECT_SECURE_MAGIC.length);
+        if (!magic?.equals(DIRECT_SECURE_MAGIC)) {
+          fail(new Error('direct-secure-magic-invalid'));
+          return;
+        }
+      }
+      if (buffer.length >= HANDSHAKE_HEADER_BYTES && expectedLength < 0) {
+        expectedLength = buffer.readUInt32BE(4);
+        if (!Number.isInteger(expectedLength)
+          || expectedLength < 1
+          || expectedLength > MAX_HANDSHAKE_BYTES) {
+          fail(new Error('direct-secure-handshake-size-invalid'));
+          return;
+        }
+      }
+      complete();
+    };
+    const onData = chunk => append(chunk);
+    const onError = error => fail(error);
+    const onClose = () => fail(new Error('direct-secure-handshake-closed'));
+    socket.on('data', onData);
+    socket.once('error', onError);
+    socket.once('close', onClose);
+    append(firstChunk);
+  });
+}
+
+function writeRaw(socket, payload) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => socket.removeListener('error', onError);
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) reject(error);
+      else resolve();
+    };
+    const onError = error => finish(error);
+    socket.once('error', onError);
+    socket.write(payload, error => finish(error || null));
+  });
+}
+
+function combineCipherOutput(updated, finalized) {
+  if (updated.length === 0) return finalized;
+  if (finalized.length === 0) return updated;
+  return Buffer.concat([updated, finalized], updated.length + finalized.length);
+}
+
+class SecureDirectDuplex extends Duplex {
+  constructor(rawSocket, options) {
+    super({ allowHalfOpen: false });
+    this.rawSocket = rawSocket;
+    this.sendKey = Buffer.from(options.sendKey);
+    this.receiveKey = Buffer.from(options.receiveKey);
+    this.sendDirection = options.sendDirection;
+    this.receiveDirection = options.receiveDirection;
+    this.sendNoncePrefix = options.sendNoncePrefix;
+    this.receiveNoncePrefix = options.receiveNoncePrefix;
+    this.sendSequence = 1n;
+    this.receiveSequence = 1n;
+    this.encrypted = new BoundedByteSegments(MAX_ENCRYPTED_ACCUMULATOR_BYTES);
+    this.processing = false;
+    this.rawPaused = true;
+    this.readBackpressured = false;
+    this.__liveDeskSecureDirect = true;
+    this.__liveDeskSecureChannel = options.channel;
+
+    this.onRawData = chunk => {
+      if (!this.encrypted.append(chunk)) {
+        this.destroy(new Error('direct-secure-record-buffer-overflow'));
+        return;
+      }
+      this.processEncrypted();
+    };
+    this.onRawError = error => this.destroy(error);
+    this.onRawEnd = () => {
+      if (this.encrypted.length !== 0) {
+        this.destroy(new Error('direct-secure-truncated-record'));
+        return;
+      }
+      this.push(null);
+    };
+    this.onRawClose = () => {
+      if (!this.destroyed) this.destroy();
+    };
+    this.onRawTimeout = () => this.emit('timeout');
+
+    rawSocket.pause();
+    rawSocket.on('data', this.onRawData);
+    rawSocket.on('error', this.onRawError);
+    rawSocket.on('end', this.onRawEnd);
+    rawSocket.on('close', this.onRawClose);
+    rawSocket.on('timeout', this.onRawTimeout);
+    if (options.initialEncryptedBytes?.length
+      && !this.encrypted.append(options.initialEncryptedBytes)) {
+      throw new Error('direct-secure-record-buffer-overflow');
+    }
+  }
+
+  get remoteAddress() { return this.rawSocket.remoteAddress; }
+  get remoteFamily() { return this.rawSocket.remoteFamily; }
+  get remotePort() { return this.rawSocket.remotePort; }
+  get localAddress() { return this.rawSocket.localAddress; }
+  get localPort() { return this.rawSocket.localPort; }
+  get bufferSize() { return this.rawSocket.bufferSize; }
+
+  setNoDelay(value = true) {
+    this.rawSocket.setNoDelay(value);
+    return this;
+  }
+
+  setKeepAlive(enable = false, initialDelay = 0) {
+    this.rawSocket.setKeepAlive(enable, initialDelay);
+    return this;
+  }
+
+  setTimeout(timeout, callback) {
+    if (typeof callback === 'function') this.once('timeout', callback);
+    this.rawSocket.setTimeout(timeout);
+    return this;
+  }
+
+  _read() {
+    this.readBackpressured = false;
+    this.processEncrypted();
+    if (this.rawPaused && !this.readBackpressured && !this.destroyed) {
+      this.rawPaused = false;
+      this.rawSocket.resume();
+    }
+  }
+
+  _write(chunk, encoding, callback) {
+    void this.writeEncrypted(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding))
+      .then(() => callback(), callback);
+  }
+
+  async writeEncrypted(plaintext) {
+    let offset = 0;
+    while (offset < plaintext.length) {
+      if (this.sendSequence > MAX_SAFE_SEQUENCE) {
+        throw new Error('direct-secure-send-sequence-exhausted');
+      }
+      const length = Math.min(MAX_RECORD_PLAINTEXT_BYTES, plaintext.length - offset);
+      const sequence = this.sendSequence;
+      this.sendSequence += 1n;
+      const header = Buffer.allocUnsafe(RECORD_HEADER_BYTES);
+      header.writeUInt32BE(length, 0);
+      header.writeBigUInt64BE(sequence, 4);
+      const nonce = buildNonce(this.sendNoncePrefix, sequence);
+      const aad = buildAad(this.sendDirection, header);
+      const cipher = crypto.createCipheriv('aes-256-gcm', this.sendKey, nonce, {
+        authTagLength: RECORD_TAG_BYTES
+      });
+      cipher.setAAD(aad, { plaintextLength: length });
+      const ciphertext = combineCipherOutput(
+        cipher.update(plaintext.subarray(offset, offset + length)),
+        cipher.final());
+      const wire = Buffer.concat([header, ciphertext, cipher.getAuthTag()]);
+      await writeRaw(this.rawSocket, wire);
+      offset += length;
+    }
+  }
+
+  processEncrypted() {
+    if (this.processing || this.destroyed) return;
+    this.processing = true;
+    try {
+      while (!this.destroyed) {
+        if (this.encrypted.length < RECORD_HEADER_BYTES) return;
+        const length = this.encrypted.readUInt32BE(0);
+        const sequence = this.encrypted.readBigUInt64BE(4);
+        if (!Number.isInteger(length) || length < 1 || length > MAX_RECORD_PLAINTEXT_BYTES) {
+          throw new Error('direct-secure-record-size-invalid');
+        }
+        if (sequence !== this.receiveSequence) {
+          throw new Error('direct-secure-record-sequence-invalid');
+        }
+        const total = RECORD_HEADER_BYTES + length + RECORD_TAG_BYTES;
+        if (this.encrypted.length < total) return;
+        const record = this.encrypted.readExact(0, total);
+        if (!record) throw new Error('direct-secure-record-read-failed');
+        this.encrypted.discard(total);
+        const header = record.subarray(0, RECORD_HEADER_BYTES);
+        const ciphertext = record.subarray(RECORD_HEADER_BYTES, RECORD_HEADER_BYTES + length);
+        const tag = record.subarray(RECORD_HEADER_BYTES + length, total);
+        const nonce = buildNonce(this.receiveNoncePrefix, sequence);
+        const aad = buildAad(this.receiveDirection, header);
+        const decipher = crypto.createDecipheriv('aes-256-gcm', this.receiveKey, nonce, {
+          authTagLength: RECORD_TAG_BYTES
+        });
+        decipher.setAAD(aad, { plaintextLength: length });
+        decipher.setAuthTag(tag);
+        const plaintext = combineCipherOutput(decipher.update(ciphertext), decipher.final());
+        this.receiveSequence += 1n;
+        if (!this.push(plaintext)) {
+          this.readBackpressured = true;
+          this.rawPaused = true;
+          this.rawSocket.pause();
+          return;
+        }
+      }
+    } catch (error) {
+      this.destroy(error);
+    } finally {
+      this.processing = false;
+    }
+  }
+
+  _final(callback) {
+    this.rawSocket.end(callback);
+  }
+
+  _destroy(error, callback) {
+    this.rawSocket.removeListener('data', this.onRawData);
+    this.rawSocket.removeListener('error', this.onRawError);
+    this.rawSocket.removeListener('end', this.onRawEnd);
+    this.rawSocket.removeListener('close', this.onRawClose);
+    this.rawSocket.removeListener('timeout', this.onRawTimeout);
+    this.sendKey.fill(0);
+    this.receiveKey.fill(0);
+    this.encrypted.clear();
+    if (!this.rawSocket.destroyed) this.rawSocket.destroy();
+    callback(error);
+  }
+}
+
+function secureDuplexOptions(role, channel, sendKey, receiveKey, initialEncryptedBytes) {
+  const isClient = role === 'client';
+  return {
+    channel,
+    sendKey,
+    receiveKey,
+    initialEncryptedBytes,
+    sendDirection: isClient ? CLIENT_DIRECTION : HUB_DIRECTION,
+    receiveDirection: isClient ? HUB_DIRECTION : CLIENT_DIRECTION,
+    sendNoncePrefix: isClient ? CLIENT_NONCE_PREFIX : HUB_NONCE_PREFIX,
+    receiveNoncePrefix: isClient ? HUB_NONCE_PREFIX : CLIENT_NONCE_PREFIX
+  };
+}
+
+export async function acceptSecureDirectSocket(rawSocket, firstChunk, pairToken, options = {}) {
+  const tokenBytes = Buffer.from(String(pairToken || ''), 'utf8');
+  let actualClientProof;
+  let expectedClientProof;
+  let hubProof;
+  let sharedSecret;
+  let salt;
+  let clientToHubKey;
+  let hubToClientKey;
+  try {
+    if (tokenBytes.length === 0) throw new Error('direct-secure-pair-token-required');
+    const { message, remainder } = await readHandshake(rawSocket, firstChunk, options.timeoutMs);
+    if (message?.type !== 'direct.secure.hello' || message?.protocol !== DIRECT_SECURE_PROTOCOL) {
+      throw new Error('direct-secure-client-hello-invalid');
+    }
+    const channel = requireSecureChannel(message.channel);
+    const clientPublicKeyText = String(message.clientPublicKey || '');
+    const clientNonceText = String(message.clientNonce || '');
+    const clientPublicKey = decodeBase64Url(clientPublicKeyText, PUBLIC_KEY_BYTES);
+    decodeBase64Url(clientNonceText, CLIENT_NONCE_BYTES).fill(0);
+    actualClientProof = decodeBase64Url(message.proof, PROOF_BYTES);
+    expectedClientProof = hmac(
+      tokenBytes,
+      `livedesk-direct-client-v1\0${channel}\0${clientPublicKeyText}\0${clientNonceText}`);
+    if (!timingSafeEqual(actualClientProof, expectedClientProof)) {
+      await writeRaw(rawSocket, encodeHandshake({
+        type: 'direct.secure.reject',
+        protocol: DIRECT_SECURE_PROTOCOL,
+        channel,
+        error: 'invalid-pair-token'
+      }));
+      const error = new Error('direct-secure-client-proof-invalid');
+      error.code = 'LIVEDESK_INVALID_PAIR_TOKEN_REJECTED';
+      throw error;
+    }
+
+    const hubEcdh = crypto.createECDH('prime256v1');
+    hubEcdh.generateKeys();
+    const hubPublicKeyText = base64Url(hubEcdh.getPublicKey(null, 'uncompressed'));
+    const hubNonceText = base64Url(crypto.randomBytes(HUB_NONCE_BYTES));
+    hubProof = hmac(
+      tokenBytes,
+      `livedesk-direct-hub-v1\0${channel}\0${clientPublicKeyText}\0${clientNonceText}\0${hubPublicKeyText}\0${hubNonceText}`);
+    sharedSecret = hubEcdh.computeSecret(clientPublicKey);
+    salt = hmac(
+      tokenBytes,
+      `livedesk-direct-salt-v1\0${channel}\0${clientNonceText}\0${hubNonceText}`);
+    clientToHubKey = deriveKey(
+      sharedSecret,
+      salt,
+      `livedesk-direct-e2e-v1\0${channel}\0${CLIENT_DIRECTION}\0${clientPublicKeyText}\0${hubPublicKeyText}`);
+    hubToClientKey = deriveKey(
+      sharedSecret,
+      salt,
+      `livedesk-direct-e2e-v1\0${channel}\0${HUB_DIRECTION}\0${clientPublicKeyText}\0${hubPublicKeyText}`);
+
+    await writeRaw(rawSocket, encodeHandshake({
+      type: 'direct.secure.welcome',
+      protocol: DIRECT_SECURE_PROTOCOL,
+      channel,
+      clientPublicKey: clientPublicKeyText,
+      clientNonce: clientNonceText,
+      hubPublicKey: hubPublicKeyText,
+      hubNonce: hubNonceText,
+      proof: base64Url(hubProof)
+    }));
+    return new SecureDirectDuplex(rawSocket, secureDuplexOptions(
+      'hub', channel, hubToClientKey, clientToHubKey, remainder));
+  } finally {
+    tokenBytes.fill(0);
+    actualClientProof?.fill(0);
+    expectedClientProof?.fill(0);
+    hubProof?.fill(0);
+    sharedSecret?.fill(0);
+    salt?.fill(0);
+    clientToHubKey?.fill(0);
+    hubToClientKey?.fill(0);
+  }
+}
+
+function waitForConnect(socket, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(
+      () => finish(new Error('direct-secure-connect-timeout')),
+      Math.max(500, Math.min(30_000, Number(timeoutMs) || 10_000)));
+    timer.unref?.();
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener('connect', onConnect);
+      socket.removeListener('error', onError);
+      socket.removeListener('close', onClose);
+    };
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) reject(error);
+      else resolve();
+    };
+    const onConnect = () => finish();
+    const onError = error => finish(error);
+    const onClose = () => finish(new Error('direct-secure-connect-closed'));
+    socket.once('connect', onConnect);
+    socket.once('error', onError);
+    socket.once('close', onClose);
+  });
+}
+
+export async function connectSecureDirectSocket(endpoint, pairToken, requestedChannel, options = {}) {
+  const channel = requireSecureChannel(requestedChannel);
+  const tokenBytes = Buffer.from(String(pairToken || ''), 'utf8');
+  const rawSocket = net.createConnection(endpoint);
+  let clientNonce;
+  let clientPublicKeyBytes;
+  let clientProof;
+  let actualHubProof;
+  let expectedHubProof;
+  let hubPublicKeyBytes;
+  let hubNonce;
+  let sharedSecret;
+  let salt;
+  let clientToHubKey;
+  let hubToClientKey;
+  try {
+    if (tokenBytes.length === 0) throw new Error('direct-secure-pair-token-required');
+    await waitForConnect(rawSocket, options.connectTimeoutMs);
+    rawSocket.setNoDelay(true);
+    const clientEcdh = crypto.createECDH('prime256v1');
+    clientEcdh.generateKeys();
+    clientNonce = crypto.randomBytes(CLIENT_NONCE_BYTES);
+    clientPublicKeyBytes = clientEcdh.getPublicKey(null, 'uncompressed');
+    const clientPublicKeyText = base64Url(clientPublicKeyBytes);
+    const clientNonceText = base64Url(clientNonce);
+    clientProof = hmac(
+      tokenBytes,
+      `livedesk-direct-client-v1\0${channel}\0${clientPublicKeyText}\0${clientNonceText}`);
+    await writeRaw(rawSocket, encodeHandshake({
+      type: 'direct.secure.hello',
+      protocol: DIRECT_SECURE_PROTOCOL,
+      channel,
+      clientPublicKey: clientPublicKeyText,
+      clientNonce: clientNonceText,
+      proof: base64Url(clientProof)
+    }));
+
+    const { message, remainder } = await readHandshake(rawSocket, null, options.handshakeTimeoutMs);
+    if (message?.type === 'direct.secure.reject'
+      && message?.protocol === DIRECT_SECURE_PROTOCOL
+      && message?.error === 'invalid-pair-token') {
+      const error = new Error('invalid-pair-token');
+      error.code = 'LIVEDESK_INVALID_PAIR_TOKEN';
+      throw error;
+    }
+    if (message?.type !== 'direct.secure.welcome' || message?.protocol !== DIRECT_SECURE_PROTOCOL) {
+      throw new Error('direct-secure-welcome-invalid');
+    }
+    if (message.channel !== channel
+      || message.clientPublicKey !== clientPublicKeyText
+      || message.clientNonce !== clientNonceText) {
+      throw new Error('direct-secure-client-echo-mismatch');
+    }
+    const hubPublicKeyText = String(message.hubPublicKey || '');
+    const hubNonceText = String(message.hubNonce || '');
+    hubPublicKeyBytes = decodeBase64Url(hubPublicKeyText, PUBLIC_KEY_BYTES);
+    hubNonce = decodeBase64Url(hubNonceText, HUB_NONCE_BYTES);
+    actualHubProof = decodeBase64Url(message.proof, PROOF_BYTES);
+    expectedHubProof = hmac(
+      tokenBytes,
+      `livedesk-direct-hub-v1\0${channel}\0${clientPublicKeyText}\0${clientNonceText}\0${hubPublicKeyText}\0${hubNonceText}`);
+    if (!timingSafeEqual(actualHubProof, expectedHubProof)) {
+      throw new Error('direct-secure-hub-proof-invalid');
+    }
+    sharedSecret = clientEcdh.computeSecret(hubPublicKeyBytes);
+    salt = hmac(
+      tokenBytes,
+      `livedesk-direct-salt-v1\0${channel}\0${clientNonceText}\0${hubNonceText}`);
+    clientToHubKey = deriveKey(
+      sharedSecret,
+      salt,
+      `livedesk-direct-e2e-v1\0${channel}\0${CLIENT_DIRECTION}\0${clientPublicKeyText}\0${hubPublicKeyText}`);
+    hubToClientKey = deriveKey(
+      sharedSecret,
+      salt,
+      `livedesk-direct-e2e-v1\0${channel}\0${HUB_DIRECTION}\0${clientPublicKeyText}\0${hubPublicKeyText}`);
+
+    return new SecureDirectDuplex(rawSocket, secureDuplexOptions(
+      'client', channel, clientToHubKey, hubToClientKey, remainder));
+  } catch (error) {
+    if (!rawSocket.destroyed) rawSocket.destroy();
+    throw error;
+  } finally {
+    tokenBytes.fill(0);
+    clientNonce?.fill(0);
+    clientPublicKeyBytes?.fill(0);
+    clientProof?.fill(0);
+    actualHubProof?.fill(0);
+    expectedHubProof?.fill(0);
+    hubPublicKeyBytes?.fill(0);
+    hubNonce?.fill(0);
+    sharedSecret?.fill(0);
+    salt?.fill(0);
+    clientToHubKey?.fill(0);
+    hubToClientKey?.fill(0);
+  }
+}
+
+export function isLoopbackSocketAddress(value) {
+  const address = String(value || '').trim().toLowerCase();
+  return address === '127.0.0.1'
+    || address === '::1'
+    || address === '::ffff:127.0.0.1';
+}
+
+export function isPrivateSocketAddress(value) {
+  const address = String(value || '').trim().toLowerCase();
+  if (isLoopbackSocketAddress(address)) return true;
+  const ipv4 = address.startsWith('::ffff:') ? address.slice(7) : address;
+  if (net.isIPv4(ipv4)) {
+    const [first, second] = ipv4.split('.').map(Number);
+    return first === 10
+      || (first === 172 && second >= 16 && second <= 31)
+      || (first === 192 && second === 168)
+      || (first === 169 && second === 254);
+  }
+  return address.startsWith('fc') || address.startsWith('fd') || address.startsWith('fe80:');
+}