@livedesk/hub 0.1.32 → 0.1.34

package/src/transport/secure-direct-acceptor.js

@@ -1,433 +1,440 @@
-import crypto from 'node:crypto';
-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 HANDSHAKE_TIMEOUT_MS = 5_000;
-const REPLAY_TTL_MS = 2 * 60 * 1000;
-const MAX_REPLAY_ENTRIES = 8192;
-const DEFAULT_MAX_PENDING_HANDSHAKES = 128;
-const DEFAULT_MAX_CONNECTIONS_PER_IP_PER_MINUTE = 60;
-const DEFAULT_MAX_CONSECUTIVE_FAILURES = 8;
-const DEFAULT_IP_BLOCK_MS = 60_000;
-const MAX_TRACKED_IPS = 4096;
-
-function directError(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 directError('secure-public-key-invalid');
-  }
-  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
-    throw directError('secure-public-key-invalid');
-  }
-  return { key, text: der.toString('base64url') };
-}
-
-function verifyP256Signature(publicKey, message, signature) {
-  const bytes = decodeCanonicalBase64Url(signature, 64, 64);
-  if (!crypto.verify('sha256', Buffer.from(String(message || ''), 'utf8'), {
-    key: publicKey,
-    dsaEncoding: 'ieee-p1363'
-  }, bytes)) {
-    throw directError('device-signature-invalid');
-  }
-}
-
-function safeHandshakeError(error) {
-  const code = clean(error?.code || error?.message, 100).toLowerCase();
-  return /^[-a-z0-9]+$/.test(code) ? code : 'secure-handshake-rejected';
-}
-
-export function createSecureDirectAcceptor({
-  authority,
-  getIdentity = () => ({}),
-  getEnrollmentToken = () => '',
-  consumeEnrollmentToken = () => false,
-  onSecureSocket = () => {},
-  onAudit = () => {},
-  logWarn = () => {},
-  now = () => Date.now(),
-  abuseLimits = {}
-} = {}) {
-  if (!authority?.verifyCredential || !authority?.issueCredential || !authority?.signHubMessage) {
-    throw directError('secure-device-authority-required');
-  }
-  const replayCache = new Map();
-  const ipStates = new Map();
-  const maxPendingHandshakes = Math.max(1, Number(abuseLimits.maxPendingHandshakes)
-    || DEFAULT_MAX_PENDING_HANDSHAKES);
-  const maxConnectionsPerIpPerMinute = Math.max(1, Number(abuseLimits.maxConnectionsPerIpPerMinute)
-    || DEFAULT_MAX_CONNECTIONS_PER_IP_PER_MINUTE);
-  const maxConsecutiveFailures = Math.max(1, Number(abuseLimits.maxConsecutiveFailures)
-    || DEFAULT_MAX_CONSECUTIVE_FAILURES);
-  const ipBlockMs = Math.max(1_000, Number(abuseLimits.ipBlockMs) || DEFAULT_IP_BLOCK_MS);
-  let acceptedSessions = 0;
-  let rejectedSessions = 0;
-  let enrollmentCount = 0;
-  let resumedSessions = 0;
-  let replayRejections = 0;
-  let pendingHandshakes = 0;
-  let capacityRejections = 0;
-  let rateLimitRejections = 0;
-  let blockedIpRejections = 0;
-
-  function remoteAddress(rawSocket) {
-    return clean(rawSocket?.remoteAddress, 100).replace(/^::ffff:/, '') || 'unknown';
-  }
-
-  function pruneIpStates(current) {
-    for (const [ip, state] of ipStates) {
-      if (current - state.lastSeenAt >= Math.max(ipBlockMs * 2, 5 * 60_000)) {
-        ipStates.delete(ip);
-      }
-    }
-    while (ipStates.size > MAX_TRACKED_IPS) {
-      const oldest = ipStates.keys().next().value;
-      if (!oldest) break;
-      ipStates.delete(oldest);
-    }
-  }
-
-  function getIpState(ip, current) {
-    pruneIpStates(current);
-    let state = ipStates.get(ip);
-    if (!state) {
-      state = {
-        windowStartedAt: current,
-        connectionCount: 0,
-        consecutiveFailures: 0,
-        blockedUntil: 0,
-        lastSeenAt: current
-      };
-      ipStates.set(ip, state);
-    }
-    state.lastSeenAt = current;
-    if (current - state.windowStartedAt >= 60_000) {
-      state.windowStartedAt = current;
-      state.connectionCount = 0;
-    }
-    return state;
-  }
-
-  function admissionError(ip, current) {
-    const state = getIpState(ip, current);
-    if (state.blockedUntil > current) {
-      blockedIpRejections += 1;
-      return 'secure-ip-temporarily-blocked';
-    }
-    if (pendingHandshakes >= maxPendingHandshakes) {
-      capacityRejections += 1;
-      return 'secure-handshake-capacity';
-    }
-    state.connectionCount += 1;
-    if (state.connectionCount > maxConnectionsPerIpPerMinute) {
-      rateLimitRejections += 1;
-      return 'secure-ip-rate-limited';
-    }
-    return '';
-  }
-
-  function recordFailure(ip, current) {
-    const state = getIpState(ip, current);
-    state.consecutiveFailures += 1;
-    if (state.consecutiveFailures >= maxConsecutiveFailures) {
-      state.blockedUntil = Math.max(state.blockedUntil, current + ipBlockMs);
-    }
-  }
-
-  function recordSuccess(ip, current) {
-    const state = getIpState(ip, current);
-    state.consecutiveFailures = 0;
-    state.blockedUntil = 0;
-  }
-
-  function rejectSocket(rawSocket, code, ip, observedDeviceId = '') {
-    rejectedSessions += 1;
-    onAudit({
-      transport: 'direct-tcp',
-      action: code === 'secure-ip-rate-limited'
-        || code === 'secure-ip-temporarily-blocked'
-        || code === 'secure-handshake-capacity'
-        ? 'remote.abuse-defense'
-        : 'remote.handshake',
-      result: 'rejected',
-      reason: code,
-      deviceId: observedDeviceId,
-      remoteAddress: ip
-    });
-    try { rawSocket.write(`${JSON.stringify({ type: 'secure.error', protocol: SECURE_SESSION_PROTOCOL, error: code })}\n`); } catch {}
-    logWarn('security', `Secure Direct handshake rejected reason=${code}`);
-    rawSocket.destroy();
-  }
-
-  function pruneReplay(current) {
-    for (const [key, expiresAt] of replayCache) {
-      if (expiresAt > current && replayCache.size <= MAX_REPLAY_ENTRIES) break;
-      replayCache.delete(key);
-    }
-  }
-
-  function claimReplayOwner(message, current) {
-    const nonce = decodeCanonicalBase64Url(message.nonce, 16, 32).toString('base64url');
-    const owner = crypto.createHash('sha256')
-      .update(String(message.credential || getEnrollmentToken() || ''), 'utf8')
-      .digest('base64url');
-    const key = `${owner}:${nonce}`;
-    pruneReplay(current);
-    if (replayCache.has(key)) {
-      replayRejections += 1;
-      throw directError('secure-handshake-replay');
-    }
-    if (replayCache.size >= MAX_REPLAY_ENTRIES) throw directError('secure-replay-cache-capacity');
-    replayCache.set(key, current + REPLAY_TTL_MS);
-  }
-
-  function handleHello(rawSocket, hello, remainder) {
-    if (hello?.type !== 'secure.client-hello' || hello?.protocol !== SECURE_SESSION_PROTOCOL) {
-      throw directError('secure-client-hello-required');
-    }
-    const current = Math.floor(now());
-    const timestamp = Number(hello.timestamp);
-    if (!Number.isSafeInteger(timestamp) || Math.abs(current - timestamp) > SECURE_SESSION_MAX_CLOCK_SKEW_MS) {
-      throw directError('secure-handshake-timestamp-invalid');
-    }
-    claimReplayOwner(hello, current);
-    const channel = normalizeSecureChannel(hello.channel);
-    const deviceId = clean(hello.deviceId, 128);
-    if (!deviceId) throw directError('device-id-required');
-    const devicePublic = requireP256PublicKey(hello.devicePublicKey);
-    const clientEphemeral = requireP256PublicKey(hello.clientEphemeralPublicKey);
-    const clientTranscript = secureClientTranscript(hello);
-    const identity = getIdentity() || {};
-    const accountId = clean(identity.accountId, 128);
-    if (!accountId) throw directError('secure-account-session-required');
-
-    let credential;
-    let credentialPayload;
-    let enrollmentSecret = '';
-    if (hello.mode === 'enroll') {
-      if (channel !== 'control') throw directError('secure-enrollment-control-channel-required');
-      const token = String(getEnrollmentToken() || '');
-      enrollmentSecret = token;
-      const expectedProof = enrollmentProof(token, clientTranscript);
-      if (!fixedTimeBase64UrlEqual(hello.enrollmentProof, expectedProof, 32)) {
-        throw directError('secure-enrollment-proof-invalid');
-      }
-      verifyP256Signature(devicePublic.key, clientTranscript, hello.deviceSignature);
-      authority.assertEnrollmentAllowed?.({ accountId, deviceId, devicePublicKey: devicePublic.text });
-      if (!consumeEnrollmentToken(token)) throw directError('secure-enrollment-token-used');
-      const issued = authority.issueCredential({ accountId, deviceId, devicePublicKey: devicePublic.text });
-      credential = issued.credential;
-      credentialPayload = issued.payload;
-      enrollmentCount += 1;
-    } else if (hello.mode === 'resume') {
-      const verified = authority.verifyCredential(hello.credential, { accountId, deviceId });
-      if (verified.payload.devicePublicKey !== devicePublic.text) throw directError('device-credential-binding-invalid');
-      authority.verifyDeviceSignature(verified, clientTranscript, hello.deviceSignature);
-      credential = verified.text;
-      credentialPayload = verified.payload;
-      resumedSessions += 1;
-    } else {
-      throw directError('secure-handshake-mode-invalid');
-    }
-
-    const { privateKey: serverEphemeralPrivate, publicKey: serverEphemeralPublic } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
-    const sessionId = crypto.randomBytes(16).toString('base64url');
-    const response = {
-      type: 'secure.server-hello',
-      protocol: SECURE_SESSION_PROTOCOL,
-      sessionId,
-      channel,
-      timestamp: current,
-      serverNonce: crypto.randomBytes(16).toString('base64url'),
-      serverEphemeralPublicKey: serverEphemeralPublic.export({ format: 'der', type: 'spki' }).toString('base64url'),
-      credential,
-      hubId: authority.hubId,
-      accountId,
-      deviceId
-    };
-    const serverTranscript = secureServerTranscript(response, clientTranscript);
-    response.hubSignature = authority.signHubMessage(serverTranscript);
-    if (hello.mode === 'enroll') {
-      response.enrollmentServerProof = enrollmentProof(enrollmentSecret, serverTranscript);
-    }
-    const sharedSecret = crypto.diffieHellman({ privateKey: serverEphemeralPrivate, publicKey: clientEphemeral.key });
-    let sessionKey;
-    try {
-      sessionKey = deriveSecureSessionKey({ sharedSecret, clientTranscript, serverTranscript, sessionId, channel });
-    } finally {
-      sharedSecret.fill(0);
-    }
-    const secureSocket = new SecureRecordSocket(rawSocket, {
-      sessionKey,
-      sessionId,
-      channel,
-      role: 'hub',
-      securityContext: {
-        protocol: SECURE_SESSION_PROTOCOL,
-        accountId,
-        hubId: authority.hubId,
-        deviceId,
-        credentialSerial: credentialPayload.serial,
-        authenticated: true,
-        encrypted: true
-      }
-    });
-    sessionKey.fill(0);
-    secureSocket.__liveDeskDirectSecure = true;
-    rawSocket.write(`${JSON.stringify(response)}\n`);
-    onSecureSocket(secureSocket, {
-      protocol: SECURE_SESSION_PROTOCOL,
-      accountId,
-      hubId: authority.hubId,
-      deviceId,
-      channel,
-      credentialSerial: credentialPayload.serial,
-      enrolled: hello.mode === 'enroll'
-    });
-    onAudit({
-      transport: 'direct-tcp',
-      action: hello.mode === 'enroll' ? 'remote.device.enroll' : 'remote.device.resume',
-      result: 'accepted',
-      accountId,
-      hubId: authority.hubId,
-      deviceId,
-      sessionId,
-      channel,
-      credentialSerial: credentialPayload.serial
-    });
-    authority.markConnected(deviceId);
-    acceptedSessions += 1;
-    if (remainder.length > 0) secureSocket.feedEncrypted(remainder);
-  }
-
-  function accept(rawSocket, firstChunk = null) {
-    const ip = remoteAddress(rawSocket);
-    const admittedAt = Math.floor(now());
-    const denied = admissionError(ip, admittedAt);
-    if (denied) {
-      rejectSocket(rawSocket, denied, ip);
-      return false;
-    }
-    pendingHandshakes += 1;
-    let chunks = [];
-    let bytes = 0;
-    let settled = false;
-    let pendingHeld = true;
-    let observedDeviceId = '';
-    const timer = setTimeout(() => fail(directError('secure-handshake-timeout')), HANDSHAKE_TIMEOUT_MS);
-    timer.unref?.();
-
-    const releasePending = () => {
-      if (!pendingHeld) return;
-      pendingHeld = false;
-      pendingHandshakes = Math.max(0, pendingHandshakes - 1);
-    };
-
-    const cleanup = () => {
-      clearTimeout(timer);
-      rawSocket.removeListener('data', onData);
-      rawSocket.removeListener('close', onClose);
-      releasePending();
-    };
-
-    const fail = error => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      const code = safeHandshakeError(error);
-      recordFailure(ip, Math.floor(now()));
-      rejectSocket(rawSocket, code, ip, observedDeviceId);
-    };
-
-    const onClose = () => {
-      if (!settled) fail(directError('secure-handshake-closed'));
-    };
-
-    const onData = chunk => {
-      if (settled) return;
-      const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk || []);
-      bytes += incoming.length;
-      if (bytes > SECURE_SESSION_MAX_HANDSHAKE_BYTES) {
-        fail(directError('secure-handshake-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;
-      settled = true;
-      cleanup();
-      let hello;
-      try {
-        hello = JSON.parse(combined.subarray(0, newline).toString('utf8'));
-        observedDeviceId = clean(hello?.deviceId, 128);
-      } catch {
-        settled = false;
-        fail(directError('secure-handshake-json-invalid'));
-        return;
-      }
-      try {
-        handleHello(rawSocket, hello, combined.subarray(newline + 1));
-        recordSuccess(ip, Math.floor(now()));
-      } catch (error) {
-        // settled is reset only for the common failure path so it can emit the
-        // bounded rejection response and release the raw socket.
-        settled = false;
-        fail(error);
-      }
-    };
-
-    rawSocket.on('data', onData);
-    rawSocket.once('close', onClose);
-    if (firstChunk) onData(firstChunk);
-  }
-
-  return Object.freeze({
-    accept,
-    getStatus: () => ({
-      protocol: SECURE_SESSION_PROTOCOL,
-      acceptedSessions,
-      rejectedSessions,
-      enrollmentCount,
-      resumedSessions,
-      replayCacheSize: replayCache.size,
-      replayRejections,
-      pendingHandshakes,
-      trackedIpCount: ipStates.size,
-      capacityRejections,
-      rateLimitRejections,
-      blockedIpRejections,
-      limits: {
-        maxPendingHandshakes,
-        maxConnectionsPerIpPerMinute,
-        maxConsecutiveFailures,
-        ipBlockMs,
-        handshakeTimeoutMs: HANDSHAKE_TIMEOUT_MS
-      }
-    })
-  });
-}
+import crypto from 'node:crypto';
+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 HANDSHAKE_TIMEOUT_MS = 5_000;
+const REPLAY_TTL_MS = 2 * 60 * 1000;
+const MAX_REPLAY_ENTRIES = 8192;
+const DEFAULT_MAX_PENDING_HANDSHAKES = 128;
+const DEFAULT_MAX_CONNECTIONS_PER_IP_PER_MINUTE = 60;
+const DEFAULT_MAX_CONSECUTIVE_FAILURES = 8;
+const DEFAULT_IP_BLOCK_MS = 60_000;
+const MAX_TRACKED_IPS = 4096;
+
+function directError(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 directError('secure-public-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw directError('secure-public-key-invalid');
+  }
+  return { key, text: der.toString('base64url') };
+}
+
+function verifyP256Signature(publicKey, message, signature) {
+  const bytes = decodeCanonicalBase64Url(signature, 64, 64);
+  if (!crypto.verify('sha256', Buffer.from(String(message || ''), 'utf8'), {
+    key: publicKey,
+    dsaEncoding: 'ieee-p1363'
+  }, bytes)) {
+    throw directError('device-signature-invalid');
+  }
+}
+
+function safeHandshakeError(error) {
+  const code = clean(error?.code || error?.message, 100).toLowerCase();
+  return /^[-a-z0-9]+$/.test(code) ? code : 'secure-handshake-rejected';
+}
+
+export function createSecureDirectAcceptor({
+  authority,
+  getIdentity = () => ({}),
+  getEnrollmentToken = () => '',
+  consumeEnrollmentToken = () => false,
+  onSecureSocket = () => {},
+  onAudit = () => {},
+  logWarn = () => {},
+  now = () => Date.now(),
+  abuseLimits = {}
+} = {}) {
+  if (!authority?.verifyCredential || !authority?.issueCredential || !authority?.signHubMessage) {
+    throw directError('secure-device-authority-required');
+  }
+  const replayCache = new Map();
+  const ipStates = new Map();
+  const maxPendingHandshakes = Math.max(1, Number(abuseLimits.maxPendingHandshakes)
+    || DEFAULT_MAX_PENDING_HANDSHAKES);
+  const maxConnectionsPerIpPerMinute = Math.max(1, Number(abuseLimits.maxConnectionsPerIpPerMinute)
+    || DEFAULT_MAX_CONNECTIONS_PER_IP_PER_MINUTE);
+  const maxConsecutiveFailures = Math.max(1, Number(abuseLimits.maxConsecutiveFailures)
+    || DEFAULT_MAX_CONSECUTIVE_FAILURES);
+  const ipBlockMs = Math.max(1_000, Number(abuseLimits.ipBlockMs) || DEFAULT_IP_BLOCK_MS);
+  let acceptedSessions = 0;
+  let rejectedSessions = 0;
+  let enrollmentCount = 0;
+  let resumedSessions = 0;
+  let replayRejections = 0;
+  let pendingHandshakes = 0;
+  let capacityRejections = 0;
+  let rateLimitRejections = 0;
+  let blockedIpRejections = 0;
+  let probeClosures = 0;
+
+  function remoteAddress(rawSocket) {
+    return clean(rawSocket?.remoteAddress, 100).replace(/^::ffff:/, '') || 'unknown';
+  }
+
+  function pruneIpStates(current) {
+    for (const [ip, state] of ipStates) {
+      if (current - state.lastSeenAt >= Math.max(ipBlockMs * 2, 5 * 60_000)) {
+        ipStates.delete(ip);
+      }
+    }
+    while (ipStates.size > MAX_TRACKED_IPS) {
+      const oldest = ipStates.keys().next().value;
+      if (!oldest) break;
+      ipStates.delete(oldest);
+    }
+  }
+
+  function getIpState(ip, current) {
+    pruneIpStates(current);
+    let state = ipStates.get(ip);
+    if (!state) {
+      state = {
+        windowStartedAt: current,
+        connectionCount: 0,
+        consecutiveFailures: 0,
+        blockedUntil: 0,
+        lastSeenAt: current
+      };
+      ipStates.set(ip, state);
+    }
+    state.lastSeenAt = current;
+    if (current - state.windowStartedAt >= 60_000) {
+      state.windowStartedAt = current;
+      state.connectionCount = 0;
+    }
+    return state;
+  }
+
+  function admissionError(ip, current) {
+    const state = getIpState(ip, current);
+    if (state.blockedUntil > current) {
+      blockedIpRejections += 1;
+      return 'secure-ip-temporarily-blocked';
+    }
+    if (pendingHandshakes >= maxPendingHandshakes) {
+      capacityRejections += 1;
+      return 'secure-handshake-capacity';
+    }
+    state.connectionCount += 1;
+    if (state.connectionCount > maxConnectionsPerIpPerMinute) {
+      rateLimitRejections += 1;
+      return 'secure-ip-rate-limited';
+    }
+    return '';
+  }
+
+  function recordFailure(ip, current) {
+    const state = getIpState(ip, current);
+    state.consecutiveFailures += 1;
+    if (state.consecutiveFailures >= maxConsecutiveFailures) {
+      state.blockedUntil = Math.max(state.blockedUntil, current + ipBlockMs);
+    }
+  }
+
+  function recordSuccess(ip, current) {
+    const state = getIpState(ip, current);
+    state.consecutiveFailures = 0;
+    state.blockedUntil = 0;
+  }
+
+  function rejectSocket(rawSocket, code, ip, observedDeviceId = '') {
+    rejectedSessions += 1;
+    onAudit({
+      transport: 'direct-tcp',
+      action: code === 'secure-ip-rate-limited'
+        || code === 'secure-ip-temporarily-blocked'
+        || code === 'secure-handshake-capacity'
+        ? 'remote.abuse-defense'
+        : 'remote.handshake',
+      result: 'rejected',
+      reason: code,
+      deviceId: observedDeviceId,
+      remoteAddress: ip
+    });
+    try { rawSocket.write(`${JSON.stringify({ type: 'secure.error', protocol: SECURE_SESSION_PROTOCOL, error: code })}\n`); } catch {}
+    logWarn('security', `Secure Direct handshake rejected reason=${code} remote=${ip || 'unknown'}`);
+    rawSocket.destroy();
+  }
+
+  function pruneReplay(current) {
+    for (const [key, expiresAt] of replayCache) {
+      if (expiresAt > current && replayCache.size <= MAX_REPLAY_ENTRIES) break;
+      replayCache.delete(key);
+    }
+  }
+
+  function claimReplayOwner(message, current) {
+    const nonce = decodeCanonicalBase64Url(message.nonce, 16, 32).toString('base64url');
+    const owner = crypto.createHash('sha256')
+      .update(String(message.credential || getEnrollmentToken() || ''), 'utf8')
+      .digest('base64url');
+    const key = `${owner}:${nonce}`;
+    pruneReplay(current);
+    if (replayCache.has(key)) {
+      replayRejections += 1;
+      throw directError('secure-handshake-replay');
+    }
+    if (replayCache.size >= MAX_REPLAY_ENTRIES) throw directError('secure-replay-cache-capacity');
+    replayCache.set(key, current + REPLAY_TTL_MS);
+  }
+
+  function handleHello(rawSocket, hello, remainder) {
+    if (hello?.type !== 'secure.client-hello' || hello?.protocol !== SECURE_SESSION_PROTOCOL) {
+      throw directError('secure-client-hello-required');
+    }
+    const current = Math.floor(now());
+    const timestamp = Number(hello.timestamp);
+    if (!Number.isSafeInteger(timestamp) || Math.abs(current - timestamp) > SECURE_SESSION_MAX_CLOCK_SKEW_MS) {
+      throw directError('secure-handshake-timestamp-invalid');
+    }
+    claimReplayOwner(hello, current);
+    const channel = normalizeSecureChannel(hello.channel);
+    const deviceId = clean(hello.deviceId, 128);
+    if (!deviceId) throw directError('device-id-required');
+    const devicePublic = requireP256PublicKey(hello.devicePublicKey);
+    const clientEphemeral = requireP256PublicKey(hello.clientEphemeralPublicKey);
+    const clientTranscript = secureClientTranscript(hello);
+    const identity = getIdentity() || {};
+    const accountId = clean(identity.accountId, 128);
+    if (!accountId) throw directError('secure-account-session-required');
+
+    let credential;
+    let credentialPayload;
+    let enrollmentSecret = '';
+    if (hello.mode === 'enroll') {
+      if (channel !== 'control') throw directError('secure-enrollment-control-channel-required');
+      const token = String(getEnrollmentToken() || '');
+      enrollmentSecret = token;
+      const expectedProof = enrollmentProof(token, clientTranscript);
+      if (!fixedTimeBase64UrlEqual(hello.enrollmentProof, expectedProof, 32)) {
+        throw directError('secure-enrollment-proof-invalid');
+      }
+      verifyP256Signature(devicePublic.key, clientTranscript, hello.deviceSignature);
+      authority.assertEnrollmentAllowed?.({ accountId, deviceId, devicePublicKey: devicePublic.text });
+      if (!consumeEnrollmentToken(token)) throw directError('secure-enrollment-token-used');
+      const issued = authority.issueCredential({ accountId, deviceId, devicePublicKey: devicePublic.text });
+      credential = issued.credential;
+      credentialPayload = issued.payload;
+      enrollmentCount += 1;
+    } else if (hello.mode === 'resume') {
+      const verified = authority.verifyCredential(hello.credential, { accountId, deviceId });
+      if (verified.payload.devicePublicKey !== devicePublic.text) throw directError('device-credential-binding-invalid');
+      authority.verifyDeviceSignature(verified, clientTranscript, hello.deviceSignature);
+      credential = verified.text;
+      credentialPayload = verified.payload;
+      resumedSessions += 1;
+    } else {
+      throw directError('secure-handshake-mode-invalid');
+    }
+
+    const { privateKey: serverEphemeralPrivate, publicKey: serverEphemeralPublic } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const sessionId = crypto.randomBytes(16).toString('base64url');
+    const response = {
+      type: 'secure.server-hello',
+      protocol: SECURE_SESSION_PROTOCOL,
+      sessionId,
+      channel,
+      timestamp: current,
+      serverNonce: crypto.randomBytes(16).toString('base64url'),
+      serverEphemeralPublicKey: serverEphemeralPublic.export({ format: 'der', type: 'spki' }).toString('base64url'),
+      credential,
+      hubId: authority.hubId,
+      accountId,
+      deviceId
+    };
+    const serverTranscript = secureServerTranscript(response, clientTranscript);
+    response.hubSignature = authority.signHubMessage(serverTranscript);
+    if (hello.mode === 'enroll') {
+      response.enrollmentServerProof = enrollmentProof(enrollmentSecret, serverTranscript);
+    }
+    const sharedSecret = crypto.diffieHellman({ privateKey: serverEphemeralPrivate, publicKey: clientEphemeral.key });
+    let sessionKey;
+    try {
+      sessionKey = deriveSecureSessionKey({ sharedSecret, clientTranscript, serverTranscript, sessionId, channel });
+    } finally {
+      sharedSecret.fill(0);
+    }
+    const secureSocket = new SecureRecordSocket(rawSocket, {
+      sessionKey,
+      sessionId,
+      channel,
+      role: 'hub',
+      securityContext: {
+        protocol: SECURE_SESSION_PROTOCOL,
+        accountId,
+        hubId: authority.hubId,
+        deviceId,
+        credentialSerial: credentialPayload.serial,
+        authenticated: true,
+        encrypted: true
+      }
+    });
+    sessionKey.fill(0);
+    secureSocket.__liveDeskDirectSecure = true;
+    rawSocket.write(`${JSON.stringify(response)}\n`);
+    onSecureSocket(secureSocket, {
+      protocol: SECURE_SESSION_PROTOCOL,
+      accountId,
+      hubId: authority.hubId,
+      deviceId,
+      channel,
+      credentialSerial: credentialPayload.serial,
+      enrolled: hello.mode === 'enroll'
+    });
+    onAudit({
+      transport: 'direct-tcp',
+      action: hello.mode === 'enroll' ? 'remote.device.enroll' : 'remote.device.resume',
+      result: 'accepted',
+      accountId,
+      hubId: authority.hubId,
+      deviceId,
+      sessionId,
+      channel,
+      credentialSerial: credentialPayload.serial
+    });
+    authority.markConnected(deviceId);
+    acceptedSessions += 1;
+    if (remainder.length > 0) secureSocket.feedEncrypted(remainder);
+  }
+
+  function accept(rawSocket, firstChunk = null) {
+    const ip = remoteAddress(rawSocket);
+    const admittedAt = Math.floor(now());
+    const denied = admissionError(ip, admittedAt);
+    if (denied) {
+      rejectSocket(rawSocket, denied, ip);
+      return false;
+    }
+    pendingHandshakes += 1;
+    let chunks = [];
+    let bytes = 0;
+    let settled = false;
+    let pendingHeld = true;
+    let observedDeviceId = '';
+    const timer = setTimeout(() => fail(directError('secure-handshake-timeout')), HANDSHAKE_TIMEOUT_MS);
+    timer.unref?.();
+
+    const releasePending = () => {
+      if (!pendingHeld) return;
+      pendingHeld = false;
+      pendingHandshakes = Math.max(0, pendingHandshakes - 1);
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      rawSocket.removeListener('data', onData);
+      rawSocket.removeListener('close', onClose);
+      releasePending();
+    };
+
+    const fail = error => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const code = safeHandshakeError(error);
+      if (code === 'secure-handshake-closed' && bytes === 0) {
+        probeClosures += 1;
+        try { rawSocket.destroy(); } catch {}
+        return;
+      }
+      recordFailure(ip, Math.floor(now()));
+      rejectSocket(rawSocket, code, ip, observedDeviceId);
+    };
+
+    const onClose = () => {
+      if (!settled) fail(directError('secure-handshake-closed'));
+    };
+
+    const onData = chunk => {
+      if (settled) return;
+      const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk || []);
+      bytes += incoming.length;
+      if (bytes > SECURE_SESSION_MAX_HANDSHAKE_BYTES) {
+        fail(directError('secure-handshake-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;
+      settled = true;
+      cleanup();
+      let hello;
+      try {
+        hello = JSON.parse(combined.subarray(0, newline).toString('utf8'));
+        observedDeviceId = clean(hello?.deviceId, 128);
+      } catch {
+        settled = false;
+        fail(directError('secure-handshake-json-invalid'));
+        return;
+      }
+      try {
+        handleHello(rawSocket, hello, combined.subarray(newline + 1));
+        recordSuccess(ip, Math.floor(now()));
+      } catch (error) {
+        // settled is reset only for the common failure path so it can emit the
+        // bounded rejection response and release the raw socket.
+        settled = false;
+        fail(error);
+      }
+    };
+
+    rawSocket.on('data', onData);
+    rawSocket.once('close', onClose);
+    if (firstChunk) onData(firstChunk);
+  }
+
+  return Object.freeze({
+    accept,
+    getStatus: () => ({
+      protocol: SECURE_SESSION_PROTOCOL,
+      acceptedSessions,
+      rejectedSessions,
+      enrollmentCount,
+      resumedSessions,
+      replayCacheSize: replayCache.size,
+      replayRejections,
+      pendingHandshakes,
+      trackedIpCount: ipStates.size,
+      capacityRejections,
+      rateLimitRejections,
+      blockedIpRejections,
+      probeClosures,
+      limits: {
+        maxPendingHandshakes,
+        maxConnectionsPerIpPerMinute,
+        maxConsecutiveFailures,
+        ipBlockMs,
+        handshakeTimeoutMs: HANDSHAKE_TIMEOUT_MS
+      }
+    })
+  });
+}