@livedesk/hub 0.1.55 → 0.1.57

package/src/console-direct.js

@@ -0,0 +1,1538 @@
+import crypto from 'node:crypto';
+import WebSocket from 'ws';
+import nodeDataChannel from 'node-datachannel';
+import {
+  DIRECT_CONSOLE_MAX_MESSAGE_BYTES,
+  DIRECT_CONSOLE_WIRE_CHUNK_BYTES,
+  createDirectConsoleWireAssembler,
+  createDirectConsoleWireBudget,
+  encodeDirectConsoleWireMessage
+} from '../../runtime-core/src/console-direct-wire.js';
+
+const DEFAULT_SIGNAL_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
+const DEFAULT_STUN_URLS = Object.freeze(['stun:stun.cloudflare.com:3478']);
+const DEFAULT_RETRY_DELAYS_MS = Object.freeze([1_000, 2_000, 5_000, 10_000, 20_000]);
+const SIGNAL_HTTP_429_RETRY_MS = 60_000;
+const SIGNAL_MESSAGE_MAX_BYTES = 32 * 1024;
+const SDP_MAX_BYTES = 24 * 1024;
+const ICE_CANDIDATE_MAX_BYTES = 4 * 1024;
+const CONTROL_LABEL = 'livedesk-control-v1';
+const LOGICAL_WS_LABEL_PREFIX = 'livedesk-ws-v1:';
+const LOGICAL_WS_PURPOSES = new Set(['frame', 'atlas', 'input', 'audio']);
+const MAX_PEERS = 4;
+const MAX_LOGICAL_CHANNELS_PER_PEER = 16;
+const MAX_PENDING_HTTP_PER_PEER = 32;
+const MAX_HTTP_REQUEST_BYTES = 1024 * 1024;
+const MAX_HTTP_RESPONSE_BYTES = 4 * 1024 * 1024;
+const MAX_SHARED_ASSEMBLY_BYTES = 12 * 1024 * 1024;
+const MAX_FRAME_MESSAGE_BYTES = (8 * 1024 * 1024) + DIRECT_CONSOLE_WIRE_CHUNK_BYTES;
+const MAX_PENDING_MEDIA_WIRE_MESSAGES = 8;
+const MAX_DATA_CHANNEL_BUFFERED_BYTES = 12 * 1024 * 1024;
+const MAX_LOCAL_WS_BUFFERED_BYTES = 4 * 1024 * 1024;
+const HTTP_TIMEOUT_MS = 15_000;
+const ICE_CONNECT_TIMEOUT_MS = 10_000;
+const PEER_DISCONNECTED_TIMEOUT_MS = 5_000;
+const ACCESS_TOKEN_TIMEOUT_MS = 8_000;
+const SIGNAL_READY_TIMEOUT_MS = 10_000;
+const CONTROL_ASSEMBLY_TIMEOUT_MS = 15_000;
+const MEDIA_ASSEMBLY_TIMEOUT_MS = 500;
+const LOGICAL_BIND_TIMEOUT_MS = 5_000;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function normalizeSignalUrl(value) {
+  const source = String(value || DEFAULT_SIGNAL_URL).trim();
+  if (!source || /^(off|disabled|none)$/i.test(source)) return '';
+  try {
+    const url = new URL(source);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : url.protocol === 'https:' ? 'wss:' : url.protocol;
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') return null;
+    url.pathname = '/v2/rtc/hub';
+    url.search = '';
+    url.hash = '';
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeStunUrls(value) {
+  const values = Array.isArray(value)
+    ? value
+    : String(value || '').split(/[\s,]+/);
+  const urls = [...new Set(values
+    .map(item => String(item || '').trim())
+    .filter(url => /^stun:[^\s@]+$/i.test(url)))];
+  const resolved = urls.length > 0 ? urls : [...DEFAULT_STUN_URLS];
+  return Object.freeze(resolved);
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function parseJson(value) {
+  try {
+    return JSON.parse(String(value || ''));
+  } catch {
+    return null;
+  }
+}
+
+function safeContentHeaders(headers) {
+  const result = {};
+  for (const name of ['accept', 'content-type', 'if-match', 'range', 'x-livedesk-csrf']) {
+    const value = headers && typeof headers === 'object'
+      ? headers[name] || headers[name.toUpperCase()]
+      : '';
+    if (value) result[name] = String(value).slice(0, 512);
+  }
+  return result;
+}
+
+function normalizeHttpBaseUrl(value) {
+  try {
+    const url = new URL(String(value || '').trim());
+    if (!['http:', 'https:'].includes(url.protocol)
+      || url.username
+      || url.password
+      || url.pathname !== '/'
+      || url.search
+      || url.hash) {
+      return null;
+    }
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function canonicalHttpRequestUrl(value, httpBaseUrl) {
+  const source = String(value || '');
+  const queryIndex = source.indexOf('?');
+  const rawPathname = queryIndex >= 0 ? source.slice(0, queryIndex) : source;
+  if (!(httpBaseUrl instanceof URL)
+    || !rawPathname.startsWith('/')
+    || rawPathname.startsWith('//')
+    || source.includes('#')
+    || rawPathname.includes('\\')
+    || /\/{2,}/.test(rawPathname)
+    || /(?:^|\/)\.{1,2}(?:\/|$)/.test(rawPathname)
+    || /%(?:25)*(?:2e|2f|5c)/i.test(rawPathname)) {
+    return null;
+  }
+  try {
+    const decodedPathname = decodeURIComponent(rawPathname);
+    if (/[\u0000-\u001f\u007f]/.test(decodedPathname)
+      || decodedPathname.includes('\\')
+      || /\/{2,}/.test(decodedPathname)
+      || /(?:^|\/)\.{1,2}(?:\/|$)/.test(decodedPathname)) {
+      return null;
+    }
+    const canonical = new URL(source, httpBaseUrl);
+    if (canonical.origin !== httpBaseUrl.origin
+      || canonical.protocol !== httpBaseUrl.protocol
+      || canonical.username
+      || canonical.password
+      || canonical.hash
+      || /\/{2,}/.test(canonical.pathname)) {
+      return null;
+    }
+    return canonical;
+  } catch {
+    return null;
+  }
+}
+
+function allowedHttpRequest(method, pathname) {
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
+  pathname = String(pathname || '');
+  if (pathname === '/api/health'
+    || pathname === '/api/runtime/status'
+    || pathname === '/api/runtime/restart'
+    || pathname === '/api/auth/status'
+    || pathname === '/api/remote/status'
+    || pathname === '/api/hub/status'
+    || pathname === '/api/update/status'
+    || pathname === '/api/update/apply') {
+    return true;
+  }
+  if (/^\/api\/settings(?:\/|$)/.test(pathname)
+    || /^\/api\/captures(?:\/|$)/.test(pathname)
+    || /^\/api\/capture-sessions(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/devices(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/frames$/.test(pathname)
+    || /^\/api\/remote\/filesystem(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/files(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/tasks(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/license(?:\/sync)?$/.test(pathname)) {
+    return pathname !== '/api/remote/registry-credentials'
+      && pathname !== '/api/remote/pairing-pin'
+      && !pathname.startsWith('/api/remote/host-target')
+      && !pathname.startsWith('/api/remote/synthetic');
+  }
+  return false;
+}
+
+const WEBSOCKET_PATH_BY_PURPOSE = Object.freeze({
+  frame: '/api/remote/frames/ws',
+  atlas: '/api/remote/atlas/ws',
+  input: '/api/remote/input/ws',
+  audio: '/api/remote/audio/ws'
+});
+
+function allowedWebSocketPath(path, purpose) {
+  return String(path || '').split('?')[0] === WEBSOCKET_PATH_BY_PURPOSE[purpose];
+}
+
+function parseLogicalWebSocketLabel(label) {
+  const source = String(label || '');
+  if (!source.startsWith(LOGICAL_WS_LABEL_PREFIX)) return null;
+  const remainder = source.slice(LOGICAL_WS_LABEL_PREFIX.length);
+  const separator = remainder.lastIndexOf(':');
+  if (separator <= 0) return null;
+  const channelId = remainder.slice(0, separator);
+  const purpose = remainder.slice(separator + 1);
+  if (!UUID_PATTERN.test(channelId) || !LOGICAL_WS_PURPOSES.has(purpose)) return null;
+  return Object.freeze({ channelId, purpose });
+}
+
+function candidateIsRelay(candidate) {
+  return /(?:^|\s)typ\s+relay(?:\s|$)/i.test(String(candidate || ''));
+}
+
+function peerSelectedRelay(peer) {
+  try {
+    const pair = peer?.getSelectedCandidatePair?.();
+    return String(pair?.local?.type || '').toLowerCase() === 'relay'
+      || String(pair?.remote?.type || '').toLowerCase() === 'relay'
+      || candidateIsRelay(pair?.local?.candidate)
+      || candidateIsRelay(pair?.remote?.candidate);
+  } catch {
+    return false;
+  }
+}
+
+function channelIsOpen(channel) {
+  try {
+    return channel?.isOpen?.() === true;
+  } catch {
+    return false;
+  }
+}
+
+function socketIsOpen(socket, WebSocketImpl) {
+  return Boolean(socket) && socket.readyState === Number(WebSocketImpl.OPEN ?? 1);
+}
+
+function decodeBase64Bounded(value, maxBytes) {
+  const source = String(value || '');
+  if (!source) return Buffer.alloc(0);
+  if (source.length > Math.ceil(maxBytes / 3) * 4 + 8
+    || !/^[A-Za-z0-9+/]*={0,2}$/.test(source)) {
+    throw new Error('invalid-console-http-body');
+  }
+  const bytes = Buffer.from(source, 'base64');
+  if (bytes.byteLength > maxBytes) throw new Error('console-http-body-too-large');
+  return bytes;
+}
+
+async function readBoundedResponseBytes(response, maxBytes) {
+  const contentLength = Number(response?.headers?.get?.('content-length') || 0);
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw new Error('console-http-response-too-large');
+  }
+  const reader = response?.body?.getReader?.();
+  if (!reader) {
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.byteLength > maxBytes) throw new Error('console-http-response-too-large');
+    return bytes;
+  }
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      const chunk = Buffer.from(result.value || []);
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel('console-http-response-too-large').catch(() => {});
+        throw new Error('console-http-response-too-large');
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  return Buffer.concat(chunks, total);
+}
+
+export function createHubConsoleDirect(options = {}) {
+  const signalUrl = normalizeSignalUrl(options.url);
+  const deviceId = String(options.deviceId || '').trim();
+  const requestedHubInstanceId = String(options.hubInstanceId || '').trim();
+  const hubInstanceId = UUID_PATTERN.test(requestedHubInstanceId)
+    ? requestedHubInstanceId
+    : crypto.randomUUID();
+  const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
+  const canonicalHttpBaseUrl = normalizeHttpBaseUrl(httpBaseUrl);
+  const stunUrls = normalizeStunUrls(options.stunUrls);
+  const SignalingWebSocketImpl = options.SignalingWebSocketImpl || options.WebSocketImpl || WebSocket;
+  const LocalWebSocketImpl = options.LocalWebSocketImpl || options.WebSocketImpl || WebSocket;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const getAccessToken = typeof options.getAccessToken === 'function'
+    ? options.getAccessToken
+    : async () => String(options.accessToken || '').trim();
+  const createPeerConnection = typeof options.createPeerConnection === 'function'
+    ? options.createPeerConnection
+    : (name, config) => new nodeDataChannel.PeerConnection(name, config);
+  const retryDelaysMs = Array.isArray(options.retryDelaysMs) && options.retryDelaysMs.length > 0
+    ? options.retryDelaysMs.map(value => Math.max(0, Number(value) || 0))
+    : DEFAULT_RETRY_DELAYS_MS;
+  const iceConnectTimeoutMs = Math.max(1, Number(options.iceConnectTimeoutMs) || ICE_CONNECT_TIMEOUT_MS);
+  const peerDisconnectedTimeoutMs = Math.max(
+    1,
+    Number(options.peerDisconnectedTimeoutMs) || PEER_DISCONNECTED_TIMEOUT_MS
+  );
+  const accessTokenTimeoutMs = Math.max(
+    1,
+    Number(options.accessTokenTimeoutMs) || ACCESS_TOKEN_TIMEOUT_MS
+  );
+  const signalReadyTimeoutMs = Math.max(
+    1,
+    Number(options.signalReadyTimeoutMs) || SIGNAL_READY_TIMEOUT_MS
+  );
+  const mediaAssemblyTimeoutMs = Math.max(
+    1,
+    Number(options.mediaAssemblyTimeoutMs) || MEDIA_ASSEMBLY_TIMEOUT_MS
+  );
+  const logicalBindTimeoutMs = Math.max(
+    1,
+    Number(options.logicalBindTimeoutMs) || LOGICAL_BIND_TIMEOUT_MS
+  );
+  const peers = new Map();
+  let signalSocket = null;
+  let signalGeneration = 0;
+  let peerGeneration = 0;
+  let retryTimer = null;
+  let accessTokenAttempt = null;
+  let signalReadyDeadline = null;
+  let retryAttempt = 0;
+  let retryNotBeforeAt = 0;
+  let nextRetryAt = '';
+  let stopped = true;
+  let state = signalUrl instanceof URL ? 'idle' : signalUrl === '' ? 'disabled' : 'error';
+  let hubEpoch = '';
+  let lastConnectedAt = '';
+  let lastError = signalUrl === null ? 'invalid-console-direct-signal-url' : '';
+  let lastHttpStatus = 0;
+  let rejectedRelayCandidates = 0;
+  let dataChannelBackpressureCloses = 0;
+  let malformedWireCloses = 0;
+  let wireBudgetCleanupFailures = 0;
+
+  const isOwnerActive = owner => !owner.retired
+    && owner.hubEpoch === hubEpoch
+    && peers.get(owner.consoleId) === owner
+    && owner.generation > 0;
+
+  const sendSignal = payload => {
+    if (!socketIsOpen(signalSocket, SignalingWebSocketImpl)) return false;
+    const serialized = JSON.stringify(payload);
+    if (byteLength(serialized) > SIGNAL_MESSAGE_MAX_BYTES) return false;
+    try {
+      signalSocket.send(serialized);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const ownerEnvelope = owner => ({
+    consoleId: owner.consoleId,
+    connectionId: owner.connectionId,
+    hubEpoch: owner.hubEpoch
+  });
+
+  const disposeAssemblerTimer = channelState => {
+    if (channelState.assemblyTimer) clearTimeout(channelState.assemblyTimer);
+    channelState.assemblyTimer = null;
+  };
+
+  const disposePendingLogicalControl = (owner, channelId) => {
+    const pending = owner.pendingLogicalControl.get(channelId);
+    if (!pending) return null;
+    clearTimeout(pending.timer);
+    owner.pendingLogicalControl.delete(channelId);
+    return pending;
+  };
+
+  const lifecycleOwnerMatches = (owner, payload) => payload?.connectionId === owner.connectionId
+    && payload?.hubEpoch === owner.hubEpoch;
+
+  function sendLifecycleControl(owner, payload, options = {}) {
+    return sendControl(owner, {
+      ...payload,
+      connectionId: owner.connectionId,
+      hubEpoch: owner.hubEpoch
+    }, options);
+  }
+
+  const closeLocalSocket = (owner, channelState, code = 1000, reason = 'console-direct-channel-closed') => {
+    const socket = channelState.localSocket;
+    channelState.localSocket = null;
+    if (!socket) return;
+    try { socket.close(code, reason); } catch { /* exact socket is already closed */ }
+    try { socket.terminate?.(); } catch { /* exact socket is already closed */ }
+  };
+
+  const closeLogicalChannel = (owner, channelState, options = {}) => {
+    if (!channelState || channelState.closed) return;
+    if (options.notify === true && isOwnerActive(owner)) {
+      sendLifecycleControl(owner, {
+        type: 'ws-closed',
+        channelId: channelState.channelId,
+        code: Number(options.code || 1000),
+        reason: String(options.reason || 'console-direct-channel-closed').slice(0, 120)
+      }, { closeOnFailure: false });
+    }
+    channelState.closed = true;
+    owner.channels.delete(channelState.channelId);
+    disposePendingLogicalControl(owner, channelState.channelId);
+    disposeAssemblerTimer(channelState);
+    channelState.assembler.dispose();
+    closeLocalSocket(
+      owner,
+      channelState,
+      Number(options.code || 1000),
+      String(options.reason || 'console-direct-channel-closed').slice(0, 120)
+    );
+    try { channelState.channel.close(); } catch { /* exact channel is already closed */ }
+  };
+
+  const retirePeer = (owner, reason = 'console-direct-peer-closed', options = {}) => {
+    if (!owner || owner.retired) return;
+    owner.retired = true;
+    if (peers.get(owner.consoleId) === owner) peers.delete(owner.consoleId);
+    clearTimeout(owner.iceTimer);
+    owner.iceTimer = null;
+    clearTimeout(owner.disconnectTimer);
+    owner.disconnectTimer = null;
+    for (const pending of owner.pendingHttp.values()) {
+      clearTimeout(pending.timeout);
+      pending.cancelled = true;
+      try { pending.controller.abort(new Error(reason)); } catch { /* request is already terminal */ }
+    }
+    owner.pendingHttp.clear();
+    for (const channelId of [...owner.pendingLogicalControl.keys()]) {
+      disposePendingLogicalControl(owner, channelId);
+    }
+    for (const channelState of [...owner.channels.values()]) {
+      closeLogicalChannel(owner, channelState, { code: 1012, reason, notify: false });
+    }
+    if (owner.control) {
+      disposeAssemblerTimer(owner.control);
+      owner.control.assembler.dispose();
+      try { owner.control.channel.close(); } catch { /* exact channel is already closed */ }
+      owner.control = null;
+    }
+    const terminalBudget = owner.wireBudget.inspect();
+    if (terminalBudget.retainedBytes !== 0 || terminalBudget.reservationCount !== 0) {
+      wireBudgetCleanupFailures += 1;
+      lastError = 'console-direct-wire-budget-not-zero-after-peer-close';
+    }
+    try { owner.peer.close(); } catch { /* exact peer is already closed */ }
+    if (options.notify !== false) {
+      sendSignal({ type: 'rtc-close', ...ownerEnvelope(owner), reason: String(reason).slice(0, 120) });
+    }
+  };
+
+  const retireAllPeers = reason => {
+    for (const owner of [...peers.values()]) retirePeer(owner, reason, { notify: false });
+  };
+
+  const retireNegotiatingPeers = reason => {
+    for (const owner of [...peers.values()]) {
+      if (!owner.control || !channelIsOpen(owner.control.channel)) {
+        retirePeer(owner, reason, { notify: false });
+      }
+    }
+  };
+
+  const refreshPeerDisconnectDeadline = owner => {
+    if (!isOwnerActive(owner)) return;
+    const disconnected = owner.peerState === 'disconnected'
+      || owner.iceState === 'disconnected';
+    if (!disconnected) {
+      clearTimeout(owner.disconnectTimer);
+      owner.disconnectTimer = null;
+      return;
+    }
+    if (owner.disconnectTimer) return;
+    const timer = setTimeout(() => {
+      if (owner.disconnectTimer !== timer) return;
+      owner.disconnectTimer = null;
+      if (isOwnerActive(owner)
+        && (owner.peerState === 'disconnected' || owner.iceState === 'disconnected')) {
+        retirePeer(owner, 'console-direct-peer-disconnected-timeout');
+      }
+    }, peerDisconnectedTimeoutMs);
+    owner.disconnectTimer = timer;
+    timer.unref?.();
+  };
+
+  const ownerBufferedAmount = owner => {
+    let total = 0;
+    const states = [owner.control, ...owner.channels.values()];
+    for (const state of states) {
+      if (!state || state.closed) continue;
+      try { total += Math.max(0, Number(state.channel.bufferedAmount?.() || 0)); } catch {}
+    }
+    return total;
+  };
+
+  const channelBufferedAmount = channelState => {
+    if (!channelState || channelState.closed) return 0;
+    try {
+      return Math.max(0, Number(channelState.channel.bufferedAmount?.() || 0));
+    } catch {
+      return 0;
+    }
+  };
+
+  const releaseLogicalBacklogForControl = (owner, requiredBytes) => {
+    const purposePriority = { frame: 0, atlas: 1, audio: 2, input: 3 };
+    const candidates = [...owner.channels.values()]
+      .filter(state => !state.closed && channelBufferedAmount(state) > 0)
+      .sort((left, right) => (
+        (purposePriority[left.purpose] ?? 4) - (purposePriority[right.purpose] ?? 4)
+        || channelBufferedAmount(right) - channelBufferedAmount(left)
+      ));
+    for (const state of candidates) {
+      if (ownerBufferedAmount(owner) + requiredBytes <= MAX_DATA_CHANNEL_BUFFERED_BYTES) break;
+      dataChannelBackpressureCloses += 1;
+      closeLogicalChannel(owner, state, {
+        code: 1013,
+        reason: 'console-direct-control-headroom',
+        notify: false
+      });
+    }
+  };
+
+  function sendWire(owner, channelState, kind, value, maxMessageBytes, options = {}) {
+    if (!isOwnerActive(owner) || channelState.closed || !channelIsOpen(channelState.channel)) return false;
+    let chunks;
+    try {
+      const messageId = channelState.nextSendMessageId >>> 0;
+      channelState.nextSendMessageId = (messageId + 1) >>> 0;
+      chunks = encodeDirectConsoleWireMessage(value, { messageId, kind, maxMessageBytes });
+    } catch {
+      if (options.closeOnFailure !== false) {
+        if (channelState === owner.control) retirePeer(owner, 'console-direct-wire-encode-failed');
+        else closeLogicalChannel(owner, channelState, {
+          code: 1009,
+          reason: 'console-direct-wire-encode-failed',
+          notify: false
+        });
+      }
+      return false;
+    }
+    const wireBytes = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+    if (channelState === owner.control
+      && ownerBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES) {
+      releaseLogicalBacklogForControl(owner, wireBytes);
+    }
+    if (wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES
+      || ownerBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES) {
+      dataChannelBackpressureCloses += 1;
+      if (options.closeOnFailure !== false) {
+        if (channelState === owner.control) retirePeer(owner, 'console-direct-control-backpressure');
+        else closeLogicalChannel(owner, channelState, {
+          code: 1013,
+          reason: 'console-direct-datachannel-backpressure',
+          notify: false
+        });
+      }
+      return false;
+    }
+    for (const chunk of chunks) {
+      if (!isOwnerActive(owner) || channelState.closed || !channelIsOpen(channelState.channel)) return false;
+      try {
+        if (channelState.channel.sendMessageBinary(chunk) !== true) throw new Error('send-rejected');
+      } catch {
+        if (options.closeOnFailure !== false) {
+          if (channelState === owner.control) retirePeer(owner, 'console-direct-control-send-failed');
+          else closeLogicalChannel(owner, channelState, {
+            code: 1011,
+            reason: 'console-direct-datachannel-send-failed',
+            notify: false
+          });
+        }
+        return false;
+      }
+    }
+    return true;
+  }
+
+  const sendControl = (owner, payload, options = {}) => owner.control
+    ? sendWire(owner, owner.control, 'control', JSON.stringify(payload), DIRECT_CONSOLE_MAX_MESSAGE_BYTES, options)
+    : false;
+
+  const sendHttpResponse = (owner, requestId, response = {}) => sendControl(owner, {
+    type: 'http-response',
+    requestId,
+    status: Math.max(0, Number(response.status || 0)),
+    statusText: String(response.statusText || '').slice(0, 120),
+    headers: response.headers && typeof response.headers === 'object' ? response.headers : {},
+    bodyBase64: String(response.bodyBase64 || ''),
+    ...(response.error ? { error: String(response.error).slice(0, 240) } : {})
+  });
+
+  const handleHttpRequest = async (owner, payload) => {
+    const requestId = String(payload?.requestId || '');
+    const method = String(payload?.method || 'GET').toUpperCase();
+    const path = String(payload?.path || '');
+    const requestUrl = canonicalHttpRequestUrl(path, canonicalHttpBaseUrl);
+    if (!UUID_PATTERN.test(requestId)
+      || !requestUrl
+      || !allowedHttpRequest(method, requestUrl.pathname)) {
+      sendHttpResponse(owner, requestId, { error: 'console-route-not-allowed' });
+      return;
+    }
+    if (owner.pendingHttp.has(requestId)) {
+      sendHttpResponse(owner, requestId, { error: 'console-http-request-duplicate' });
+      return;
+    }
+    if (owner.pendingHttp.size >= MAX_PENDING_HTTP_PER_PEER) {
+      sendHttpResponse(owner, requestId, { error: 'console-http-capacity-reached' });
+      return;
+    }
+    let body;
+    try {
+      body = decodeBase64Bounded(payload?.bodyBase64, MAX_HTTP_REQUEST_BYTES);
+    } catch (error) {
+      sendHttpResponse(owner, requestId, { error: error instanceof Error ? error.message : error });
+      return;
+    }
+    const controller = new AbortController();
+    const pending = { controller, timeout: null, cancelled: false };
+    pending.timeout = setTimeout(() => {
+      pending.cancelled = true;
+      try { controller.abort(new Error('console-http-timeout')); } catch { /* request is already terminal */ }
+    }, HTTP_TIMEOUT_MS);
+    pending.timeout.unref?.();
+    owner.pendingHttp.set(requestId, pending);
+    try {
+      const response = await fetchImpl(requestUrl.href, {
+        method,
+        headers: safeContentHeaders(payload?.headers),
+        body: ['GET', 'HEAD'].includes(method) || body.byteLength === 0 ? undefined : body,
+        signal: controller.signal
+      });
+      const responseBytes = await readBoundedResponseBytes(response, MAX_HTTP_RESPONSE_BYTES);
+      if (!isOwnerActive(owner) || owner.pendingHttp.get(requestId) !== pending || pending.cancelled) return;
+      sendHttpResponse(owner, requestId, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: {
+          'content-type': String(response.headers?.get?.('content-type') || '').slice(0, 256),
+          'content-range': String(response.headers?.get?.('content-range') || '').slice(0, 256)
+        },
+        bodyBase64: responseBytes.toString('base64')
+      });
+    } catch (error) {
+      if (isOwnerActive(owner)
+        && owner.pendingHttp.get(requestId) === pending
+        && !pending.cancelled) {
+        sendHttpResponse(owner, requestId, { error: error instanceof Error ? error.message : error });
+      }
+    } finally {
+      clearTimeout(pending.timeout);
+      if (owner.pendingHttp.get(requestId) === pending) owner.pendingHttp.delete(requestId);
+    }
+  };
+
+  const cancelHttpRequest = (owner, requestId) => {
+    const pending = owner.pendingHttp.get(String(requestId || ''));
+    if (!pending) return;
+    owner.pendingHttp.delete(String(requestId || ''));
+    clearTimeout(pending.timeout);
+    pending.cancelled = true;
+    try { pending.controller.abort(new Error('console-http-cancelled')); } catch { /* request is already terminal */ }
+  };
+
+  const queuePendingLogicalControl = (owner, payload) => {
+    const channelId = String(payload?.channelId || '');
+    if (!UUID_PATTERN.test(channelId)) throw new Error('console-direct-logical-channel-invalid');
+    const existing = owner.pendingLogicalControl.get(channelId);
+    if (payload.type === 'ws-open' && existing?.payload?.type === 'ws-open') {
+      throw new Error('console-direct-logical-open-duplicate');
+    }
+    if (!existing && owner.pendingLogicalControl.size >= MAX_LOGICAL_CHANNELS_PER_PEER) {
+      throw new Error('console-direct-logical-control-capacity');
+    }
+    if (existing) clearTimeout(existing.timer);
+    const pending = {
+      payload: { ...payload },
+      timer: setTimeout(() => {
+        if (!isOwnerActive(owner) || owner.pendingLogicalControl.get(channelId) !== pending) return;
+        owner.pendingLogicalControl.delete(channelId);
+        if (pending.payload.type === 'ws-open') {
+          sendLifecycleControl(owner, {
+            type: 'ws-error',
+            channelId,
+            error: 'console-direct-logical-channel-bind-timeout'
+          });
+        }
+      }, logicalBindTimeoutMs)
+    };
+    pending.timer.unref?.();
+    owner.pendingLogicalControl.set(channelId, pending);
+  };
+
+  const openLogicalWebSocket = (owner, channelState, payload) => {
+    const channelId = String(payload?.channelId || '');
+    const purpose = String(payload?.purpose || '');
+    const path = String(payload?.path || '');
+    if (channelState.openRequested
+      || channelId !== channelState.channelId
+      || purpose !== channelState.purpose
+      || !allowedWebSocketPath(path, purpose)) {
+      sendLifecycleControl(owner, {
+        type: 'ws-error',
+        channelId: channelState.channelId,
+        error: 'console-websocket-route-not-allowed'
+      });
+      closeLogicalChannel(owner, channelState, {
+        code: 1008,
+        reason: 'console-websocket-route-not-allowed',
+        notify: false
+      });
+      return;
+    }
+    channelState.openRequested = true;
+    const localUrl = new URL(path, httpBaseUrl);
+    const httpOrigin = new URL(httpBaseUrl).origin;
+    if (localUrl.origin !== httpOrigin) {
+      closeLogicalChannel(owner, channelState, { code: 1008, reason: 'console-websocket-origin-not-allowed' });
+      return;
+    }
+    localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+    let socket;
+    try {
+      socket = new LocalWebSocketImpl(localUrl, { perMessageDeflate: false });
+    } catch (error) {
+      sendLifecycleControl(owner, {
+        type: 'ws-error',
+        channelId,
+        error: String(error instanceof Error ? error.message : error).slice(0, 240)
+      });
+      closeLogicalChannel(owner, channelState, { code: 1011, reason: 'console-local-websocket-open-failed' });
+      return;
+    }
+    channelState.localSocket = socket;
+    socket.once('open', () => {
+      if (!isOwnerActive(owner) || owner.channels.get(channelId) !== channelState || channelState.localSocket !== socket) {
+        try { socket.terminate?.(); } catch {}
+        return;
+      }
+      sendLifecycleControl(owner, { type: 'ws-opened', channelId });
+    });
+    socket.on('message', (data, isBinary) => {
+      if (!isOwnerActive(owner) || owner.channels.get(channelId) !== channelState || channelState.localSocket !== socket) return;
+      const kind = isBinary ? 'binary' : 'text';
+      const value = isBinary ? new Uint8Array(Buffer.from(data)) : String(data);
+      if (!sendWire(owner, channelState, kind, value, channelState.maxMessageBytes)) {
+        closeLogicalChannel(owner, channelState, {
+          code: 1013,
+          reason: 'console-direct-datachannel-backpressure',
+          notify: false
+        });
+      }
+    });
+    socket.once('error', error => {
+      if (!isOwnerActive(owner) || owner.channels.get(channelId) !== channelState) return;
+      sendLifecycleControl(owner, {
+        type: 'ws-error',
+        channelId,
+        error: String(error instanceof Error ? error.message : error).slice(0, 240)
+      });
+    });
+    socket.once('close', (code, reason) => {
+      if (channelState.localSocket === socket) channelState.localSocket = null;
+      if (!isOwnerActive(owner) || owner.channels.get(channelId) !== channelState) return;
+      sendLifecycleControl(owner, {
+        type: 'ws-closed',
+        channelId,
+        code: Number(code || 1000),
+        reason: String(reason || 'console-local-websocket-closed').slice(0, 120)
+      });
+      closeLogicalChannel(owner, channelState, { code, reason: 'console-local-websocket-closed', notify: false });
+    });
+  };
+
+  const dispatchLogicalControl = (owner, payload) => {
+    if (!lifecycleOwnerMatches(owner, payload)) {
+      throw new Error('console-direct-logical-owner-invalid');
+    }
+    const channelId = String(payload.channelId || '');
+    if (!UUID_PATTERN.test(channelId)) throw new Error('console-direct-logical-channel-invalid');
+    const channelState = owner.channels.get(channelId);
+    if (payload.type === 'ws-open') {
+      if (!LOGICAL_WS_PURPOSES.has(String(payload.purpose || ''))
+        || typeof payload.path !== 'string') {
+        throw new Error('console-direct-logical-open-invalid');
+      }
+      if (!channelState || !channelIsOpen(channelState.channel)) {
+        queuePendingLogicalControl(owner, payload);
+        return;
+      }
+      disposePendingLogicalControl(owner, channelId);
+      openLogicalWebSocket(owner, channelState, payload);
+      return;
+    }
+    if (payload.type === 'ws-close') {
+      if (!channelState) {
+        queuePendingLogicalControl(owner, payload);
+        return;
+      }
+      closeLogicalChannel(owner, channelState, {
+        code: Math.max(1000, Number(payload.code || 1000)),
+        reason: String(payload.reason || 'console-request').slice(0, 120),
+        notify: true
+      });
+      return;
+    }
+    throw new Error('console-direct-logical-control-type-not-allowed');
+  };
+
+  const consumePendingLogicalControl = (owner, channelState) => {
+    const pending = disposePendingLogicalControl(owner, channelState.channelId);
+    if (pending) dispatchLogicalControl(owner, pending.payload);
+  };
+
+  const handleControlPayload = (owner, text) => {
+    const payload = parseJson(text);
+    if (!payload?.type) throw new Error('console-direct-control-invalid');
+    if (payload.type === 'http-request') {
+      void handleHttpRequest(owner, payload);
+      return;
+    }
+    if (payload.type === 'http-cancel') {
+      cancelHttpRequest(owner, payload.requestId);
+      return;
+    }
+    if (payload.type === 'ws-open' || payload.type === 'ws-close') {
+      dispatchLogicalControl(owner, payload);
+      return;
+    }
+    throw new Error('console-direct-control-type-not-allowed');
+  };
+
+  const forwardLogicalPayload = (owner, channelState, message) => {
+    const socket = channelState.localSocket;
+    if (!channelState.openRequested || !socketIsOpen(socket, LocalWebSocketImpl)) {
+      throw new Error('console-direct-logical-websocket-not-open');
+    }
+    if (Number(socket.bufferedAmount || 0) + message.byteLength > MAX_LOCAL_WS_BUFFERED_BYTES) {
+      throw new Error('console-direct-local-websocket-backpressure');
+    }
+    if (message.kind === 'text') socket.send(message.data);
+    else if (message.kind === 'binary') socket.send(Buffer.from(message.data));
+    else throw new Error('console-direct-logical-wire-kind-invalid');
+  };
+
+  const scheduleAssemblyDeadline = (owner, channelState) => {
+    const pending = Number(channelState.assembler.inspect().pendingMessages || 0);
+    if (pending === 0) {
+      disposeAssemblerTimer(channelState);
+      return;
+    }
+    if (channelState.assemblyTimer) return;
+    const delay = channelState.purpose === 'frame' || channelState.purpose === 'atlas'
+      ? mediaAssemblyTimeoutMs
+      : CONTROL_ASSEMBLY_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      if (channelState.assemblyTimer !== timer) return;
+      channelState.assemblyTimer = null;
+      if (!isOwnerActive(owner) || channelState.closed) return;
+      if (Number(channelState.assembler.inspect().pendingMessages || 0) === 0) return;
+      malformedWireCloses += 1;
+      if (channelState === owner.control) retirePeer(owner, 'console-direct-wire-assembly-timeout');
+      else closeLogicalChannel(owner, channelState, {
+        code: 1009,
+        reason: 'console-direct-wire-assembly-timeout',
+        notify: false
+      });
+    }, delay);
+    channelState.assemblyTimer = timer;
+    timer.unref?.();
+  };
+
+  const handleDataChannelMessage = (owner, channelState, raw) => {
+    if (!isOwnerActive(owner) || channelState.closed) return;
+    try {
+      if (typeof raw === 'string') throw new Error('console-direct-unframed-message');
+      const message = channelState.assembler.push(raw);
+      scheduleAssemblyDeadline(owner, channelState);
+      if (!message) return;
+      if (channelState === owner.control) {
+        if (message.kind !== 'control') throw new Error('console-direct-control-wire-kind-invalid');
+        handleControlPayload(owner, message.data);
+      } else {
+        if (message.kind === 'control') throw new Error('console-direct-logical-control-forbidden');
+        forwardLogicalPayload(owner, channelState, message);
+      }
+    } catch {
+      malformedWireCloses += 1;
+      if (channelState === owner.control) retirePeer(owner, 'console-direct-wire-invalid');
+      else closeLogicalChannel(owner, channelState, {
+        code: 1008,
+        reason: 'console-direct-wire-invalid',
+        notify: false
+      });
+    }
+  };
+
+  const bindDataChannel = (owner, channel) => {
+    if (!isOwnerActive(owner)) {
+      try { channel.close(); } catch {}
+      return;
+    }
+    const label = String(channel.getLabel?.() || '');
+    let channelState;
+    if (label === CONTROL_LABEL) {
+      if (owner.control) {
+        try { channel.close(); } catch {}
+        return;
+      }
+      channelState = {
+        channel,
+        channelId: 'control',
+        purpose: 'control',
+        maxMessageBytes: DIRECT_CONSOLE_MAX_MESSAGE_BYTES,
+        assembler: createDirectConsoleWireAssembler({
+          budget: owner.wireBudget,
+          maxMessageBytes: DIRECT_CONSOLE_MAX_MESSAGE_BYTES
+        }),
+        assemblyTimer: null,
+        nextSendMessageId: 1,
+        closed: false
+      };
+      owner.control = channelState;
+    } else {
+      const identity = parseLogicalWebSocketLabel(label);
+      if (!identity
+        || owner.channels.size >= MAX_LOGICAL_CHANNELS_PER_PEER
+        || owner.channels.has(identity?.channelId)) {
+        try { channel.close(); } catch {}
+        return;
+      }
+      const maxMessageBytes = identity.purpose === 'frame' || identity.purpose === 'atlas'
+        ? MAX_FRAME_MESSAGE_BYTES
+        : DIRECT_CONSOLE_MAX_MESSAGE_BYTES;
+      channelState = {
+        channel,
+        ...identity,
+        maxMessageBytes,
+        assembler: createDirectConsoleWireAssembler({
+          budget: owner.wireBudget,
+          maxMessageBytes,
+          maxPendingMessages: identity.purpose === 'frame' || identity.purpose === 'atlas'
+            ? MAX_PENDING_MEDIA_WIRE_MESSAGES
+            : 2
+        }),
+        assemblyTimer: null,
+        nextSendMessageId: 1,
+        openRequested: false,
+        localSocket: null,
+        closed: false
+      };
+      owner.channels.set(identity.channelId, channelState);
+    }
+    try { channel.setBufferedAmountLowThreshold?.(4 * 1024 * 1024); } catch {}
+    channel.onMessage(raw => handleDataChannelMessage(owner, channelState, raw));
+    channel.onClosed(() => {
+      if (!isOwnerActive(owner) || channelState.closed) return;
+      if (channelState === owner.control) retirePeer(owner, 'console-direct-control-closed');
+      else closeLogicalChannel(owner, channelState, {
+        code: 1001,
+        reason: 'console-direct-datachannel-closed',
+        notify: false
+      });
+    });
+    channel.onError(() => {
+      if (!isOwnerActive(owner) || channelState.closed) return;
+      if (channelState === owner.control) retirePeer(owner, 'console-direct-control-error');
+      else closeLogicalChannel(owner, channelState, {
+        code: 1011,
+        reason: 'console-direct-datachannel-error',
+        notify: false
+      });
+    });
+    channel.onOpen(() => {
+      if (!isOwnerActive(owner) || channelState.closed) return;
+      if (channelState === owner.control) {
+        clearTimeout(owner.iceTimer);
+        owner.iceTimer = null;
+        sendControl(owner, {
+          type: 'direct-ready',
+          connectionId: owner.connectionId,
+          hubEpoch: owner.hubEpoch
+        });
+      } else {
+        consumePendingLogicalControl(owner, channelState);
+      }
+    });
+  };
+
+  const createPeerOwner = payload => {
+    const consoleId = String(payload?.consoleId || '');
+    const connectionId = String(payload?.connectionId || '');
+    const ownerHubEpoch = String(payload?.hubEpoch || '');
+    const description = payload?.description;
+    if (!UUID_PATTERN.test(consoleId)
+      || !UUID_PATTERN.test(connectionId)
+      || ownerHubEpoch !== hubEpoch
+      || description?.type !== 'offer'
+      || typeof description.sdp !== 'string'
+      || byteLength(description.sdp) > SDP_MAX_BYTES) {
+      return null;
+    }
+    if (candidateIsRelay(description.sdp)) {
+      rejectedRelayCandidates += 1;
+      sendSignal({
+        type: 'rtc-close',
+        consoleId,
+        connectionId,
+        hubEpoch: ownerHubEpoch,
+        reason: 'console-direct-relay-candidate-rejected'
+      });
+      return null;
+    }
+    const existing = peers.get(consoleId);
+    if (existing
+      && existing.connectionId === connectionId
+      && existing.hubEpoch === ownerHubEpoch
+      && !existing.retired) {
+      const current = existing.peer.localDescription?.();
+      if (current?.type === 'answer' && typeof current.sdp === 'string') {
+        sendSignal({
+          type: 'rtc-answer',
+          ...ownerEnvelope(existing),
+          description: { type: 'answer', sdp: current.sdp }
+        });
+      }
+      return existing;
+    }
+    if (!existing && peers.size >= MAX_PEERS) {
+      sendSignal({
+        type: 'rtc-close',
+        consoleId,
+        connectionId,
+        hubEpoch: ownerHubEpoch,
+        reason: 'console-direct-peer-capacity-reached'
+      });
+      return null;
+    }
+    if (existing) retirePeer(existing, 'console-direct-peer-replaced');
+    let peer;
+    try {
+      peer = createPeerConnection(`console-${consoleId}`, {
+        iceServers: [...stunUrls],
+        iceTransportPolicy: 'all',
+        disableAutoNegotiation: false,
+        disableFingerprintVerification: false,
+        maxMessageSize: MAX_FRAME_MESSAGE_BYTES
+      });
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      sendSignal({
+        type: 'rtc-close',
+        consoleId,
+        connectionId,
+        hubEpoch: ownerHubEpoch,
+        reason: 'console-direct-peer-create-failed'
+      });
+      return null;
+    }
+    const owner = {
+      consoleId,
+      connectionId,
+      hubEpoch: ownerHubEpoch,
+      generation: ++peerGeneration,
+      peer,
+      control: null,
+      channels: new Map(),
+      pendingLogicalControl: new Map(),
+      pendingHttp: new Map(),
+      wireBudget: createDirectConsoleWireBudget({ maxBytes: MAX_SHARED_ASSEMBLY_BYTES }),
+      iceTimer: null,
+      disconnectTimer: null,
+      peerState: 'new',
+      iceState: 'new',
+      retired: false,
+      createdAt: Date.now()
+    };
+    peers.set(consoleId, owner);
+    peer.onLocalDescription((sdp, type) => {
+      if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
+      if (candidateIsRelay(sdp)) {
+        rejectedRelayCandidates += 1;
+        retirePeer(owner, 'console-direct-relay-candidate-rejected');
+        return;
+      }
+      sendSignal({
+        type: 'rtc-answer',
+        ...ownerEnvelope(owner),
+        description: { type: 'answer', sdp: String(sdp) }
+      });
+    });
+    peer.onLocalCandidate((candidate, sdpMid) => {
+      if (!isOwnerActive(owner)) return;
+      const candidateText = String(candidate || '');
+      if (byteLength(candidateText) > ICE_CANDIDATE_MAX_BYTES) {
+        retirePeer(owner, 'console-direct-candidate-invalid');
+        return;
+      }
+      if (candidateIsRelay(candidateText)) {
+        rejectedRelayCandidates += 1;
+        retirePeer(owner, 'console-direct-relay-candidate-rejected');
+        return;
+      }
+      sendSignal({
+        type: 'rtc-ice',
+        ...ownerEnvelope(owner),
+        candidate: candidateText,
+        sdpMid: sdpMid === undefined || sdpMid === null ? null : String(sdpMid).slice(0, 256)
+      });
+    });
+    peer.onDataChannel(channel => bindDataChannel(owner, channel));
+    peer.onStateChange(nextState => {
+      if (!isOwnerActive(owner)) return;
+      const normalized = String(nextState || '').toLowerCase();
+      owner.peerState = normalized;
+      if (normalized === 'connected') {
+        if (peerSelectedRelay(peer)) {
+          rejectedRelayCandidates += 1;
+          retirePeer(owner, 'console-direct-relay-pair-rejected');
+          return;
+        }
+      } else if (normalized === 'failed' || normalized === 'closed') {
+        retirePeer(owner, `console-direct-peer-${normalized}`);
+        return;
+      }
+      refreshPeerDisconnectDeadline(owner);
+    });
+    peer.onIceStateChange?.(nextState => {
+      if (!isOwnerActive(owner)) return;
+      const normalized = String(nextState || '').toLowerCase();
+      owner.iceState = normalized;
+      if (normalized === 'failed' || normalized === 'closed') {
+        retirePeer(owner, `console-direct-ice-${normalized}`);
+        return;
+      }
+      refreshPeerDisconnectDeadline(owner);
+    });
+    owner.iceTimer = setTimeout(() => {
+      owner.iceTimer = null;
+      if (isOwnerActive(owner)
+        && (!owner.control || !channelIsOpen(owner.control.channel))) {
+        retirePeer(owner, 'console-direct-ice-timeout');
+      }
+    }, iceConnectTimeoutMs);
+    owner.iceTimer.unref?.();
+    try {
+      peer.setRemoteDescription(description.sdp, 'offer');
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      retirePeer(owner, 'console-direct-description-failed');
+      return null;
+    }
+    return owner;
+  };
+
+  const handleSignalMessage = (raw, ownerSignalGeneration, socket) => {
+    if (typeof raw !== 'string' && !Buffer.isBuffer(raw)) return;
+    const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : raw;
+    if (byteLength(text) > SIGNAL_MESSAGE_MAX_BYTES) return;
+    const payload = parseJson(text);
+    if (!payload?.type) return;
+    if (payload.type === 'signal-ready' && payload.role === 'hub') {
+      const nextEpoch = String(payload.hubEpoch || '');
+      if (!UUID_PATTERN.test(nextEpoch)) {
+        lastError = 'console-direct-hub-epoch-invalid';
+        return;
+      }
+      clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      if (hubEpoch && hubEpoch !== nextEpoch) retireAllPeers('console-direct-hub-epoch-replaced');
+      hubEpoch = nextEpoch;
+      state = 'connected';
+      lastConnectedAt = new Date().toISOString();
+      lastError = '';
+      lastHttpStatus = 0;
+      retryAttempt = 0;
+      retryNotBeforeAt = 0;
+      nextRetryAt = '';
+      return;
+    }
+    const consoleId = String(payload.consoleId || '');
+    const connectionId = String(payload.connectionId || '');
+    const ownerHubEpoch = String(payload.hubEpoch || '');
+    if (!UUID_PATTERN.test(consoleId)
+      || !UUID_PATTERN.test(connectionId)
+      || ownerHubEpoch !== hubEpoch) return;
+    if (payload.type === 'rtc-offer') {
+      createPeerOwner(payload);
+      return;
+    }
+    const owner = peers.get(consoleId);
+    if (!owner
+      || owner.connectionId !== connectionId
+      || owner.hubEpoch !== ownerHubEpoch
+      || !isOwnerActive(owner)) return;
+    if (payload.type === 'rtc-ice') {
+      const candidate = String(payload.candidate || '');
+      if (byteLength(candidate) > ICE_CANDIDATE_MAX_BYTES) {
+        retirePeer(owner, 'console-direct-candidate-invalid');
+        return;
+      }
+      if (candidateIsRelay(candidate)) {
+        rejectedRelayCandidates += 1;
+        retirePeer(owner, 'console-direct-relay-candidate-rejected');
+        return;
+      }
+      try {
+        if (candidate) owner.peer.addRemoteCandidate(candidate, String(payload.sdpMid || ''));
+      } catch {
+        retirePeer(owner, 'console-direct-candidate-failed');
+      }
+      return;
+    }
+    if (payload.type === 'rtc-close') {
+      retirePeer(owner, String(payload.reason || 'console-direct-remote-closed'), { notify: false });
+    }
+  };
+
+  const cancelAccessTokenAttempt = () => {
+    accessTokenAttempt?.cancel();
+  };
+
+  const readAccessToken = ownerSignalGeneration => new Promise(resolve => {
+    let settled = false;
+    let attempt = null;
+    const finish = result => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(attempt.timer);
+      if (accessTokenAttempt === attempt) accessTokenAttempt = null;
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      finish({ kind: 'timeout' });
+    }, accessTokenTimeoutMs);
+    timer.unref?.();
+    attempt = {
+      generation: ownerSignalGeneration,
+      timer,
+      cancel: () => finish({ kind: 'cancelled' })
+    };
+    accessTokenAttempt = attempt;
+    void Promise.resolve()
+      .then(() => getAccessToken())
+      .then(
+        value => finish({ kind: 'value', value }),
+        error => finish({ kind: 'error', error })
+      );
+  });
+
+  const clearSignalReadyDeadline = (ownerSignalGeneration, socket) => {
+    const deadline = signalReadyDeadline;
+    if (!deadline
+      || (ownerSignalGeneration !== undefined && deadline.generation !== ownerSignalGeneration)
+      || (socket !== undefined && deadline.socket !== socket)) {
+      return false;
+    }
+    signalReadyDeadline = null;
+    clearTimeout(deadline.timer);
+    return true;
+  };
+
+  const armSignalReadyDeadline = (ownerSignalGeneration, socket, connect) => {
+    clearSignalReadyDeadline();
+    const deadline = {
+      generation: ownerSignalGeneration,
+      socket,
+      timer: null
+    };
+    deadline.timer = setTimeout(() => {
+      if (signalReadyDeadline !== deadline) return;
+      signalReadyDeadline = null;
+      if (stopped
+        || ownerSignalGeneration !== signalGeneration
+        || signalSocket !== socket) {
+        return;
+      }
+      signalSocket = null;
+      lastHttpStatus = 0;
+      lastError = 'console-direct-signal-ready-timeout';
+      retireNegotiatingPeers('console-direct-signal-ready-timeout');
+      try { socket.terminate?.(); } catch {}
+      scheduleReconnect(connect);
+    }, signalReadyTimeoutMs);
+    deadline.timer.unref?.();
+    signalReadyDeadline = deadline;
+  };
+
+  const scheduleReconnect = connect => {
+    if (stopped || retryTimer || !(signalUrl instanceof URL)) return;
+    const sequenceDelay = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
+    const delayMs = Math.max(sequenceDelay, retryNotBeforeAt - Date.now(), 0);
+    retryAttempt += 1;
+    state = 'waiting-retry';
+    nextRetryAt = new Date(Date.now() + delayMs).toISOString();
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      nextRetryAt = '';
+      void connect();
+    }, delayMs);
+    retryTimer.unref?.();
+  };
+
+  const connect = async () => {
+    if (stopped || !(signalUrl instanceof URL) || !deviceId) return;
+    const ownerSignalGeneration = ++signalGeneration;
+    let ownerHttpStatus = 0;
+    state = 'connecting';
+    nextRetryAt = '';
+    let accessToken = '';
+    const accessTokenResult = await readAccessToken(ownerSignalGeneration);
+    if (stopped || ownerSignalGeneration !== signalGeneration) return;
+    if (accessTokenResult.kind === 'cancelled') return;
+    if (accessTokenResult.kind === 'timeout') {
+      lastError = 'console-direct-access-token-timeout';
+      scheduleReconnect(connect);
+      return;
+    }
+    if (accessTokenResult.kind === 'error') {
+      lastError = accessTokenResult.error instanceof Error
+        ? accessTokenResult.error.message
+        : String(accessTokenResult.error);
+    } else {
+      accessToken = String(accessTokenResult.value || '').trim();
+    }
+    if (!accessToken) {
+      lastError = 'hub-session-required';
+      scheduleReconnect(connect);
+      return;
+    }
+    const url = new URL(signalUrl);
+    url.searchParams.set('deviceId', deviceId);
+    url.searchParams.set('hubInstanceId', hubInstanceId);
+    let socket;
+    try {
+      socket = new SignalingWebSocketImpl(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        perMessageDeflate: false
+      });
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      scheduleReconnect(connect);
+      return;
+    }
+    if (stopped || ownerSignalGeneration !== signalGeneration) {
+      try { socket.terminate?.(); } catch {}
+      return;
+    }
+    signalSocket = socket;
+    armSignalReadyDeadline(ownerSignalGeneration, socket, connect);
+    socket.once('open', () => {
+      if (signalSocket !== socket || ownerSignalGeneration !== signalGeneration || stopped) return;
+      state = 'authenticating';
+    });
+    socket.once('unexpected-response', (_request, response) => {
+      if (signalSocket !== socket || ownerSignalGeneration !== signalGeneration || stopped) {
+        response.resume?.();
+        return;
+      }
+      const status = Math.max(0, Number(response?.statusCode || 0));
+      ownerHttpStatus = status;
+      lastHttpStatus = status;
+      lastError = status > 0
+        ? `Console direct signaling returned HTTP ${status}`
+        : 'Console direct signaling returned an unexpected response.';
+      if (status === 429) retryNotBeforeAt = Math.max(retryNotBeforeAt, Date.now() + SIGNAL_HTTP_429_RETRY_MS);
+      if (signalSocket === socket) signalSocket = null;
+      clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      retireNegotiatingPeers('console-direct-signaling-rejected');
+      response.resume?.();
+      try { socket.terminate?.(); } catch {}
+      scheduleReconnect(connect);
+    });
+    socket.on('message', raw => {
+      if (signalSocket === socket && ownerSignalGeneration === signalGeneration && !stopped) {
+        handleSignalMessage(raw, ownerSignalGeneration, socket);
+      }
+    });
+    socket.once('close', () => {
+      const wasOwner = signalSocket === socket
+        && ownerSignalGeneration === signalGeneration
+        && !stopped;
+      if (signalSocket === socket) signalSocket = null;
+      clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      if (!wasOwner) return;
+      retireNegotiatingPeers('console-direct-signaling-closed');
+      if (!retryTimer) state = 'disconnected';
+      scheduleReconnect(connect);
+    });
+    socket.once('error', error => {
+      if (signalSocket !== socket || ownerSignalGeneration !== signalGeneration || stopped) return;
+      if (ownerHttpStatus <= 0) {
+        lastHttpStatus = 0;
+        lastError = error instanceof Error ? error.message : String(error);
+      }
+      signalSocket = null;
+      clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      retireNegotiatingPeers('console-direct-signaling-error');
+      try { socket.terminate?.(); } catch {}
+      scheduleReconnect(connect);
+    });
+  };
+
+  const start = () => {
+    if (!stopped || !(signalUrl instanceof URL) || !deviceId) return;
+    stopped = false;
+    void connect();
+  };
+
+  const refresh = () => {
+    if (stopped) {
+      start();
+      return;
+    }
+    signalGeneration += 1;
+    cancelAccessTokenAttempt();
+    clearSignalReadyDeadline();
+    if (retryTimer) clearTimeout(retryTimer);
+    retryTimer = null;
+    retryAttempt = 0;
+    retryNotBeforeAt = 0;
+    nextRetryAt = '';
+    retireNegotiatingPeers('console-direct-refresh');
+    const socket = signalSocket;
+    signalSocket = null;
+    try { socket?.terminate?.(); } catch {}
+    void connect();
+  };
+
+  const close = () => {
+    if (stopped) return;
+    stopped = true;
+    signalGeneration += 1;
+    cancelAccessTokenAttempt();
+    clearSignalReadyDeadline();
+    if (retryTimer) clearTimeout(retryTimer);
+    retryTimer = null;
+    nextRetryAt = '';
+    retireAllPeers('hub-shutdown');
+    hubEpoch = '';
+    const socket = signalSocket;
+    signalSocket = null;
+    try { socket?.close(1001, 'hub-shutdown'); } catch {}
+    try { socket?.terminate?.(); } catch {}
+    state = signalUrl ? 'closed' : 'disabled';
+  };
+
+  const inspect = () => {
+    let logicalWebSocketChannels = 0;
+    let localWebSocketChannels = 0;
+    let pendingHttpRequests = 0;
+    let pendingLogicalControlRequests = 0;
+    let controlChannels = 0;
+    let retainedAssemblyBytes = 0;
+    let bufferedSendBytes = 0;
+    let iceConnectTimers = 0;
+    let peerDisconnectTimers = 0;
+    let assemblyDeadlineTimers = 0;
+    for (const owner of peers.values()) {
+      logicalWebSocketChannels += owner.channels.size;
+      pendingHttpRequests += owner.pendingHttp.size;
+      pendingLogicalControlRequests += owner.pendingLogicalControl.size;
+      if (owner.iceTimer) iceConnectTimers += 1;
+      if (owner.disconnectTimer) peerDisconnectTimers += 1;
+      if (owner.control && !owner.control.closed) controlChannels += 1;
+      if (owner.control?.assemblyTimer) assemblyDeadlineTimers += 1;
+      for (const channelState of owner.channels.values()) {
+        if (channelState.localSocket) localWebSocketChannels += 1;
+        if (channelState.assemblyTimer) assemblyDeadlineTimers += 1;
+      }
+      retainedAssemblyBytes += Number(owner.wireBudget.inspect().retainedBytes || 0);
+      bufferedSendBytes += ownerBufferedAmount(owner);
+    }
+    const reconnectTimerActive = Boolean(retryTimer);
+    const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
+    const signalReadyDeadlineActive = Boolean(signalReadyDeadline);
+    return Object.freeze({
+      enabled: signalUrl instanceof URL && Boolean(deviceId),
+      state,
+      connected: state === 'connected',
+      hubEpoch,
+      peerConnections: peers.size,
+      controlChannels,
+      logicalWebSocketChannels,
+      localWebSocketChannels,
+      pendingHttpRequests,
+      pendingLogicalControlRequests,
+      retainedAssemblyBytes,
+      bufferedSendBytes,
+      iceConnectTimers,
+      peerDisconnectTimers,
+      assemblyDeadlineTimers,
+      reconnectTimerActive,
+      accessTokenDeadlineActive,
+      signalReadyDeadlineActive,
+      resourceTimers: iceConnectTimers
+        + peerDisconnectTimers
+        + assemblyDeadlineTimers
+        + pendingHttpRequests
+        + pendingLogicalControlRequests
+        + Number(reconnectTimerActive)
+        + Number(accessTokenDeadlineActive)
+        + Number(signalReadyDeadlineActive),
+      rejectedRelayCandidates,
+      dataChannelBackpressureCloses,
+      malformedWireCloses,
+      wireBudgetCleanupFailures,
+      lastConnectedAt,
+      lastError,
+      lastHttpStatus,
+      retryAttempt,
+      nextRetryAt
+    });
+  };
+
+  return Object.freeze({ start, refresh, close, inspect });
+}
+
+export const consoleDirectContract = Object.freeze({
+  controlLabel: CONTROL_LABEL,
+  logicalWebSocketLabelPrefix: LOGICAL_WS_LABEL_PREFIX,
+  maxPeers: MAX_PEERS,
+  maxLogicalChannelsPerPeer: MAX_LOGICAL_CHANNELS_PER_PEER,
+  maxPendingHttpPerPeer: MAX_PENDING_HTTP_PER_PEER,
+  maxHttpRequestBytes: MAX_HTTP_REQUEST_BYTES,
+  maxHttpResponseBytes: MAX_HTTP_RESPONSE_BYTES,
+  maxSharedAssemblyBytes: MAX_SHARED_ASSEMBLY_BYTES,
+  maxFrameMessageBytes: MAX_FRAME_MESSAGE_BYTES,
+  maxPendingMediaWireMessages: MAX_PENDING_MEDIA_WIRE_MESSAGES,
+  maxBufferedBytes: MAX_DATA_CHANNEL_BUFFERED_BYTES,
+  maxLocalWebSocketBufferedBytes: MAX_LOCAL_WS_BUFFERED_BYTES,
+  maxDefaultRetryDelayMs: DEFAULT_RETRY_DELAYS_MS.at(-1),
+  accessTokenTimeoutMs: ACCESS_TOKEN_TIMEOUT_MS,
+  signalReadyTimeoutMs: SIGNAL_READY_TIMEOUT_MS,
+  logicalBindTimeoutMs: LOGICAL_BIND_TIMEOUT_MS,
+  iceConnectTimeoutMs: ICE_CONNECT_TIMEOUT_MS,
+  peerDisconnectedTimeoutMs: PEER_DISCONNECTED_TIMEOUT_MS,
+  reliableAssemblyTimeoutMs: CONTROL_ASSEMBLY_TIMEOUT_MS,
+  partialMediaAssemblyTimeoutMs: MEDIA_ASSEMBLY_TIMEOUT_MS
+});