@livedesk/hub 0.1.46 → 0.1.48

package/src/console-relay.js

@@ -1,424 +1,424 @@
-import WebSocket from 'ws';
-
-const DEFAULT_CONSOLE_RELAY_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
-const DEFAULT_RETRY_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 20_000];
-const MAX_CHANNELS = 32;
-const MAX_HTTP_REQUEST_BYTES = 1024 * 1024;
-const MAX_HTTP_RESPONSE_BYTES = 4 * 1024 * 1024;
-const MAX_RELAY_BUFFERED_BYTES = 4 * 1024 * 1024;
-const HTTP_TIMEOUT_MS = 15_000;
-const BINARY_HEADER_BYTES = 73;
-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 normalizeRelayUrl(value) {
-  const source = String(value || DEFAULT_CONSOLE_RELAY_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;
-    url.pathname = '/v1/hub';
-    url.search = '';
-    url.hash = '';
-    return url;
-  } catch {
-    return null;
-  }
-}
-
-function allowedHttpRequest(method, path) {
-  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
-  const pathname = String(path || '').split('?')[0];
-  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;
-}
-
-function allowedWebSocketPath(path) {
-  const pathname = String(path || '').split('?')[0];
-  return pathname === '/api/remote/frames/ws'
-    || pathname === '/api/remote/atlas/ws'
-    || pathname === '/api/remote/input/ws'
-    || pathname === '/api/remote/audio/ws';
-}
-
-function channelKey(consoleId, channelId) {
-  return `${consoleId}\n${channelId}`;
-}
-
-function parseMessage(raw) {
-  try {
-    return JSON.parse(String(raw || ''));
-  } catch {
-    return null;
-  }
-}
-
-function safeContentHeaders(headers) {
-  const result = {};
-  for (const name of ['accept', 'content-type', 'if-match', 'range']) {
-    const value = headers && typeof headers === 'object' ? headers[name] || headers[name.toUpperCase()] : '';
-    if (value) result[name] = String(value).slice(0, 512);
-  }
-  return result;
-}
-
-export function createHubConsoleRelay(options = {}) {
-  const relayUrl = normalizeRelayUrl(options.url);
-  const deviceId = String(options.deviceId || '').trim();
-  const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
-  const WebSocketImpl = options.WebSocketImpl || WebSocket;
-  const fetchImpl = options.fetchImpl || globalThis.fetch;
-  const getAccessToken = typeof options.getAccessToken === 'function'
-    ? options.getAccessToken
-    : async () => String(options.accessToken || '').trim();
-  const logger = options.logger || console;
-  const retryDelaysMs = options.retryDelaysMs || DEFAULT_RETRY_DELAYS_MS;
-  const localSockets = new Map();
-  const pendingHttp = new Set();
-  let relaySocket = null;
-  let retryTimer = null;
-  let retryAttempt = 0;
-  let generation = 0;
-  let stopped = true;
-  let state = relayUrl ? 'idle' : 'disabled';
-  let lastConnectedAt = '';
-  let lastError = relayUrl instanceof URL ? '' : relayUrl === '' ? '' : 'invalid-relay-url';
-  let droppedBinaryMessages = 0;
-
-  const sendRelay = (payload, bypassBackpressure = false) => {
-    if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN) return false;
-    if (!bypassBackpressure
-      && Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) return false;
-    relaySocket.send(typeof payload === 'string' || Buffer.isBuffer(payload) ? payload : JSON.stringify(payload));
-    return true;
-  };
-
-  const sendError = (consoleId, channelId, error, type = 'relay-error') => {
-    sendRelay({ type, consoleId, channelId, error: String(error || 'console-relay-error').slice(0, 240) });
-  };
-
-  const closeLocalSocket = (key, code = 1000, reason = 'console-channel-closed') => {
-    const socket = localSockets.get(key);
-    if (!socket) return;
-    localSockets.delete(key);
-    try { socket.close(code, reason); } catch { /* exact socket is already closed */ }
-    try { socket.terminate?.(); } catch { /* exact socket is already closed */ }
-  };
-
-  const closeConsoleChannels = consoleId => {
-    for (const key of [...localSockets.keys()]) {
-      if (key.startsWith(`${consoleId}\n`)) closeLocalSocket(key, 1001, 'console-detached');
-    }
-  };
-
-  const closeAllLocalSockets = reason => {
-    for (const key of [...localSockets.keys()]) closeLocalSocket(key, 1012, reason);
-  };
-
-  const handleHttpRequest = async payload => {
-    const consoleId = String(payload?.consoleId || '');
-    const channelId = String(payload?.channelId || '');
-    const method = String(payload?.method || 'GET').toUpperCase();
-    const path = String(payload?.path || '');
-    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedHttpRequest(method, path)) {
-      sendError(consoleId, channelId, 'console-route-not-allowed', 'http-response');
-      return;
-    }
-    if (pendingHttp.size >= MAX_CHANNELS) {
-      sendError(consoleId, channelId, 'console-http-capacity-reached', 'http-response');
-      return;
-    }
-    let body;
-    try {
-      body = payload.bodyBase64 ? Buffer.from(String(payload.bodyBase64), 'base64') : undefined;
-    } catch {
-      sendError(consoleId, channelId, 'invalid-console-http-body', 'http-response');
-      return;
-    }
-    if (body && body.byteLength > MAX_HTTP_REQUEST_BYTES) {
-      sendError(consoleId, channelId, 'console-http-body-too-large', 'http-response');
-      return;
-    }
-
-    const requestKey = channelKey(consoleId, channelId);
-    pendingHttp.add(requestKey);
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(new Error('console-http-timeout')), HTTP_TIMEOUT_MS);
-    timeout.unref?.();
-    try {
-      const response = await fetchImpl(`${httpBaseUrl}${path}`, {
-        method,
-        headers: safeContentHeaders(payload.headers),
-        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
-        signal: controller.signal
-      });
-      const responseBytes = Buffer.from(await response.arrayBuffer());
-      if (responseBytes.byteLength > MAX_HTTP_RESPONSE_BYTES) {
-        sendError(consoleId, channelId, 'console-http-response-too-large', 'http-response');
-        return;
-      }
-      sendRelay({
-        type: 'http-response',
-        consoleId,
-        channelId,
-        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) {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'http-response');
-    } finally {
-      clearTimeout(timeout);
-      pendingHttp.delete(requestKey);
-    }
-  };
-
-  const handleWebSocketOpen = payload => {
-    const consoleId = String(payload?.consoleId || '');
-    const channelId = String(payload?.channelId || '');
-    const path = String(payload?.path || '');
-    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedWebSocketPath(path)) {
-      sendError(consoleId, channelId, 'console-websocket-route-not-allowed', 'ws-error');
-      return;
-    }
-    if (localSockets.size >= MAX_CHANNELS) {
-      sendError(consoleId, channelId, 'console-websocket-capacity-reached', 'ws-error');
-      return;
-    }
-    const key = channelKey(consoleId, channelId);
-    closeLocalSocket(key, 1000, 'console-channel-replaced');
-    const localUrl = new URL(path, httpBaseUrl);
-    localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
-    let socket;
-    try {
-      socket = new WebSocketImpl(localUrl, { perMessageDeflate: false });
-    } catch (error) {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
-      return;
-    }
-    localSockets.set(key, socket);
-    socket.once('open', () => {
-      if (localSockets.get(key) !== socket) return;
-      sendRelay({ type: 'ws-opened', consoleId, channelId });
-    });
-    socket.on('message', (data, isBinary) => {
-      if (localSockets.get(key) !== socket) return;
-      if (isBinary) {
-        if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN
-          || Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) {
-          droppedBinaryMessages += 1;
-          closeLocalSocket(key, 1013, 'console-relay-backpressure');
-          return;
-        }
-        const header = Buffer.from(`B${consoleId}${channelId}`, 'ascii');
-        if (header.byteLength !== BINARY_HEADER_BYTES) {
-          closeLocalSocket(key, 1008, 'invalid-relay-channel-id');
-          return;
-        }
-        relaySocket.send(Buffer.concat([header, Buffer.from(data)]));
-        return;
-      }
-      sendRelay({ type: 'ws-message', consoleId, channelId, data: String(data), binary: false });
-    });
-    socket.once('close', (code, reason) => {
-      if (localSockets.get(key) === socket) localSockets.delete(key);
-      const closeReason = String(reason || '').slice(0, 120);
-      // Do not silently punch a hole in an H.264 GOP. A tiny terminal control
-      // message is allowed behind the already-bounded video backlog so the
-      // browser replaces only this logical lane and starts again on a key.
-      sendRelay(
-        { type: 'ws-closed', consoleId, channelId, code, reason: closeReason },
-        closeReason === 'console-relay-backpressure'
-      );
-    });
-    socket.once('error', error => {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
-    });
-  };
-
-  const handleMessage = raw => {
-    const payload = parseMessage(raw);
-    if (!payload?.type) return;
-    if (payload.type === 'relay-ready') {
-      state = 'connected';
-      lastConnectedAt = new Date().toISOString();
-      lastError = '';
-      return;
-    }
-    if (payload.type === 'console-detached') {
-      closeConsoleChannels(String(payload.consoleId || ''));
-      return;
-    }
-    if (payload.type === 'http-request') {
-      void handleHttpRequest(payload);
-      return;
-    }
-    if (payload.type === 'ws-open') {
-      handleWebSocketOpen(payload);
-      return;
-    }
-    const key = channelKey(String(payload.consoleId || ''), String(payload.channelId || ''));
-    const socket = localSockets.get(key);
-    if (!socket) return;
-    if (payload.type === 'ws-send' && socket.readyState === WebSocketImpl.OPEN) {
-      const data = String(payload.data || '');
-      if (Buffer.byteLength(data) <= MAX_HTTP_REQUEST_BYTES) socket.send(data);
-    } else if (payload.type === 'ws-close') {
-      closeLocalSocket(key, Number(payload.code || 1000), String(payload.reason || 'console-request').slice(0, 120));
-    }
-  };
-
-  const scheduleReconnect = connect => {
-    if (stopped || retryTimer || !(relayUrl instanceof URL)) return;
-    const delayMs = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
-    retryAttempt += 1;
-    state = 'waiting-retry';
-    retryTimer = setTimeout(() => {
-      retryTimer = null;
-      void connect();
-    }, delayMs);
-    retryTimer.unref?.();
-  };
-
-  const connect = async () => {
-    if (stopped || !(relayUrl instanceof URL) || !deviceId) return;
-    const ownerGeneration = ++generation;
-    state = 'connecting';
-    let accessToken = '';
-    try {
-      accessToken = String(await getAccessToken() || '').trim();
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-    }
-    if (stopped || ownerGeneration !== generation) return;
-    if (!accessToken) {
-      lastError = 'hub-session-required';
-      scheduleReconnect(connect);
-      return;
-    }
-    const url = new URL(relayUrl);
-    url.searchParams.set('deviceId', deviceId);
-    let socket;
-    try {
-      socket = new WebSocketImpl(url, {
-        headers: { Authorization: `Bearer ${accessToken}` },
-        perMessageDeflate: false
-      });
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      scheduleReconnect(connect);
-      return;
-    }
-    if (stopped || ownerGeneration !== generation) {
-      try { socket.terminate?.(); } catch { /* stale connect is already gone */ }
-      return;
-    }
-    relaySocket = socket;
-    socket.once('open', () => {
-      if (relaySocket !== socket || ownerGeneration !== generation || stopped) return;
-      retryAttempt = 0;
-      state = 'authenticating';
-    });
-    socket.on('message', raw => {
-      if (relaySocket === socket && ownerGeneration === generation && !stopped) handleMessage(raw);
-    });
-    socket.once('close', () => {
-      if (relaySocket === socket) relaySocket = null;
-      if (ownerGeneration !== generation || stopped) return;
-      state = 'disconnected';
-      closeAllLocalSockets('relay-disconnected');
-      scheduleReconnect(connect);
-    });
-    socket.once('error', error => {
-      lastError = error instanceof Error ? error.message : String(error);
-      try { socket.terminate?.(); } catch { /* close handler owns retry */ }
-    });
-  };
-
-  const start = () => {
-    if (!stopped || !(relayUrl instanceof URL) || !deviceId) return;
-    stopped = false;
-    void connect();
-  };
-
-  const refresh = () => {
-    if (stopped) {
-      start();
-      return;
-    }
-    generation += 1;
-    if (retryTimer) {
-      clearTimeout(retryTimer);
-      retryTimer = null;
-    }
-    const socket = relaySocket;
-    relaySocket = null;
-    try { socket?.terminate?.(); } catch { /* refresh owns the exact socket */ }
-    closeAllLocalSockets('relay-refresh');
-    void connect();
-  };
-
-  const close = () => {
-    if (stopped) return;
-    stopped = true;
-    generation += 1;
-    if (retryTimer) clearTimeout(retryTimer);
-    retryTimer = null;
-    closeAllLocalSockets('hub-shutdown');
-    const socket = relaySocket;
-    relaySocket = null;
-    try { socket?.close(1001, 'hub-shutdown'); } catch { /* exact socket is already closed */ }
-    try { socket?.terminate?.(); } catch { /* exact socket is already closed */ }
-    state = relayUrl ? 'closed' : 'disabled';
-  };
-
-  return {
-    start,
-    refresh,
-    close,
-    inspect: () => ({
-      enabled: relayUrl instanceof URL && Boolean(deviceId),
-      state,
-      connected: state === 'connected',
-      localWebSocketChannels: localSockets.size,
-      pendingHttpRequests: pendingHttp.size,
-      droppedBinaryMessages,
-      lastConnectedAt,
-      lastError
-    })
-  };
-}
-
-export const consoleRelayContract = Object.freeze({
-  maxChannels: MAX_CHANNELS,
-  maxHttpRequestBytes: MAX_HTTP_REQUEST_BYTES,
-  maxHttpResponseBytes: MAX_HTTP_RESPONSE_BYTES,
-  maxBufferedBytes: MAX_RELAY_BUFFERED_BYTES,
-  binaryHeaderBytes: BINARY_HEADER_BYTES
-});
+import WebSocket from 'ws';
+
+const DEFAULT_CONSOLE_RELAY_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
+const DEFAULT_RETRY_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 20_000];
+const MAX_CHANNELS = 32;
+const MAX_HTTP_REQUEST_BYTES = 1024 * 1024;
+const MAX_HTTP_RESPONSE_BYTES = 4 * 1024 * 1024;
+const MAX_RELAY_BUFFERED_BYTES = 4 * 1024 * 1024;
+const HTTP_TIMEOUT_MS = 15_000;
+const BINARY_HEADER_BYTES = 73;
+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 normalizeRelayUrl(value) {
+  const source = String(value || DEFAULT_CONSOLE_RELAY_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;
+    url.pathname = '/v1/hub';
+    url.search = '';
+    url.hash = '';
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function allowedHttpRequest(method, path) {
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
+  const pathname = String(path || '').split('?')[0];
+  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;
+}
+
+function allowedWebSocketPath(path) {
+  const pathname = String(path || '').split('?')[0];
+  return pathname === '/api/remote/frames/ws'
+    || pathname === '/api/remote/atlas/ws'
+    || pathname === '/api/remote/input/ws'
+    || pathname === '/api/remote/audio/ws';
+}
+
+function channelKey(consoleId, channelId) {
+  return `${consoleId}\n${channelId}`;
+}
+
+function parseMessage(raw) {
+  try {
+    return JSON.parse(String(raw || ''));
+  } catch {
+    return null;
+  }
+}
+
+function safeContentHeaders(headers) {
+  const result = {};
+  for (const name of ['accept', 'content-type', 'if-match', 'range']) {
+    const value = headers && typeof headers === 'object' ? headers[name] || headers[name.toUpperCase()] : '';
+    if (value) result[name] = String(value).slice(0, 512);
+  }
+  return result;
+}
+
+export function createHubConsoleRelay(options = {}) {
+  const relayUrl = normalizeRelayUrl(options.url);
+  const deviceId = String(options.deviceId || '').trim();
+  const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
+  const WebSocketImpl = options.WebSocketImpl || WebSocket;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const getAccessToken = typeof options.getAccessToken === 'function'
+    ? options.getAccessToken
+    : async () => String(options.accessToken || '').trim();
+  const logger = options.logger || console;
+  const retryDelaysMs = options.retryDelaysMs || DEFAULT_RETRY_DELAYS_MS;
+  const localSockets = new Map();
+  const pendingHttp = new Set();
+  let relaySocket = null;
+  let retryTimer = null;
+  let retryAttempt = 0;
+  let generation = 0;
+  let stopped = true;
+  let state = relayUrl ? 'idle' : 'disabled';
+  let lastConnectedAt = '';
+  let lastError = relayUrl instanceof URL ? '' : relayUrl === '' ? '' : 'invalid-relay-url';
+  let droppedBinaryMessages = 0;
+
+  const sendRelay = (payload, bypassBackpressure = false) => {
+    if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN) return false;
+    if (!bypassBackpressure
+      && Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) return false;
+    relaySocket.send(typeof payload === 'string' || Buffer.isBuffer(payload) ? payload : JSON.stringify(payload));
+    return true;
+  };
+
+  const sendError = (consoleId, channelId, error, type = 'relay-error') => {
+    sendRelay({ type, consoleId, channelId, error: String(error || 'console-relay-error').slice(0, 240) });
+  };
+
+  const closeLocalSocket = (key, code = 1000, reason = 'console-channel-closed') => {
+    const socket = localSockets.get(key);
+    if (!socket) return;
+    localSockets.delete(key);
+    try { socket.close(code, reason); } catch { /* exact socket is already closed */ }
+    try { socket.terminate?.(); } catch { /* exact socket is already closed */ }
+  };
+
+  const closeConsoleChannels = consoleId => {
+    for (const key of [...localSockets.keys()]) {
+      if (key.startsWith(`${consoleId}\n`)) closeLocalSocket(key, 1001, 'console-detached');
+    }
+  };
+
+  const closeAllLocalSockets = reason => {
+    for (const key of [...localSockets.keys()]) closeLocalSocket(key, 1012, reason);
+  };
+
+  const handleHttpRequest = async payload => {
+    const consoleId = String(payload?.consoleId || '');
+    const channelId = String(payload?.channelId || '');
+    const method = String(payload?.method || 'GET').toUpperCase();
+    const path = String(payload?.path || '');
+    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedHttpRequest(method, path)) {
+      sendError(consoleId, channelId, 'console-route-not-allowed', 'http-response');
+      return;
+    }
+    if (pendingHttp.size >= MAX_CHANNELS) {
+      sendError(consoleId, channelId, 'console-http-capacity-reached', 'http-response');
+      return;
+    }
+    let body;
+    try {
+      body = payload.bodyBase64 ? Buffer.from(String(payload.bodyBase64), 'base64') : undefined;
+    } catch {
+      sendError(consoleId, channelId, 'invalid-console-http-body', 'http-response');
+      return;
+    }
+    if (body && body.byteLength > MAX_HTTP_REQUEST_BYTES) {
+      sendError(consoleId, channelId, 'console-http-body-too-large', 'http-response');
+      return;
+    }
+
+    const requestKey = channelKey(consoleId, channelId);
+    pendingHttp.add(requestKey);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('console-http-timeout')), HTTP_TIMEOUT_MS);
+    timeout.unref?.();
+    try {
+      const response = await fetchImpl(`${httpBaseUrl}${path}`, {
+        method,
+        headers: safeContentHeaders(payload.headers),
+        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
+        signal: controller.signal
+      });
+      const responseBytes = Buffer.from(await response.arrayBuffer());
+      if (responseBytes.byteLength > MAX_HTTP_RESPONSE_BYTES) {
+        sendError(consoleId, channelId, 'console-http-response-too-large', 'http-response');
+        return;
+      }
+      sendRelay({
+        type: 'http-response',
+        consoleId,
+        channelId,
+        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) {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'http-response');
+    } finally {
+      clearTimeout(timeout);
+      pendingHttp.delete(requestKey);
+    }
+  };
+
+  const handleWebSocketOpen = payload => {
+    const consoleId = String(payload?.consoleId || '');
+    const channelId = String(payload?.channelId || '');
+    const path = String(payload?.path || '');
+    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedWebSocketPath(path)) {
+      sendError(consoleId, channelId, 'console-websocket-route-not-allowed', 'ws-error');
+      return;
+    }
+    if (localSockets.size >= MAX_CHANNELS) {
+      sendError(consoleId, channelId, 'console-websocket-capacity-reached', 'ws-error');
+      return;
+    }
+    const key = channelKey(consoleId, channelId);
+    closeLocalSocket(key, 1000, 'console-channel-replaced');
+    const localUrl = new URL(path, httpBaseUrl);
+    localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+    let socket;
+    try {
+      socket = new WebSocketImpl(localUrl, { perMessageDeflate: false });
+    } catch (error) {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
+      return;
+    }
+    localSockets.set(key, socket);
+    socket.once('open', () => {
+      if (localSockets.get(key) !== socket) return;
+      sendRelay({ type: 'ws-opened', consoleId, channelId });
+    });
+    socket.on('message', (data, isBinary) => {
+      if (localSockets.get(key) !== socket) return;
+      if (isBinary) {
+        if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN
+          || Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) {
+          droppedBinaryMessages += 1;
+          closeLocalSocket(key, 1013, 'console-relay-backpressure');
+          return;
+        }
+        const header = Buffer.from(`B${consoleId}${channelId}`, 'ascii');
+        if (header.byteLength !== BINARY_HEADER_BYTES) {
+          closeLocalSocket(key, 1008, 'invalid-relay-channel-id');
+          return;
+        }
+        relaySocket.send(Buffer.concat([header, Buffer.from(data)]));
+        return;
+      }
+      sendRelay({ type: 'ws-message', consoleId, channelId, data: String(data), binary: false });
+    });
+    socket.once('close', (code, reason) => {
+      if (localSockets.get(key) === socket) localSockets.delete(key);
+      const closeReason = String(reason || '').slice(0, 120);
+      // Do not silently punch a hole in an H.264 GOP. A tiny terminal control
+      // message is allowed behind the already-bounded video backlog so the
+      // browser replaces only this logical lane and starts again on a key.
+      sendRelay(
+        { type: 'ws-closed', consoleId, channelId, code, reason: closeReason },
+        closeReason === 'console-relay-backpressure'
+      );
+    });
+    socket.once('error', error => {
+      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
+    });
+  };
+
+  const handleMessage = raw => {
+    const payload = parseMessage(raw);
+    if (!payload?.type) return;
+    if (payload.type === 'relay-ready') {
+      state = 'connected';
+      lastConnectedAt = new Date().toISOString();
+      lastError = '';
+      return;
+    }
+    if (payload.type === 'console-detached') {
+      closeConsoleChannels(String(payload.consoleId || ''));
+      return;
+    }
+    if (payload.type === 'http-request') {
+      void handleHttpRequest(payload);
+      return;
+    }
+    if (payload.type === 'ws-open') {
+      handleWebSocketOpen(payload);
+      return;
+    }
+    const key = channelKey(String(payload.consoleId || ''), String(payload.channelId || ''));
+    const socket = localSockets.get(key);
+    if (!socket) return;
+    if (payload.type === 'ws-send' && socket.readyState === WebSocketImpl.OPEN) {
+      const data = String(payload.data || '');
+      if (Buffer.byteLength(data) <= MAX_HTTP_REQUEST_BYTES) socket.send(data);
+    } else if (payload.type === 'ws-close') {
+      closeLocalSocket(key, Number(payload.code || 1000), String(payload.reason || 'console-request').slice(0, 120));
+    }
+  };
+
+  const scheduleReconnect = connect => {
+    if (stopped || retryTimer || !(relayUrl instanceof URL)) return;
+    const delayMs = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
+    retryAttempt += 1;
+    state = 'waiting-retry';
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void connect();
+    }, delayMs);
+    retryTimer.unref?.();
+  };
+
+  const connect = async () => {
+    if (stopped || !(relayUrl instanceof URL) || !deviceId) return;
+    const ownerGeneration = ++generation;
+    state = 'connecting';
+    let accessToken = '';
+    try {
+      accessToken = String(await getAccessToken() || '').trim();
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    if (stopped || ownerGeneration !== generation) return;
+    if (!accessToken) {
+      lastError = 'hub-session-required';
+      scheduleReconnect(connect);
+      return;
+    }
+    const url = new URL(relayUrl);
+    url.searchParams.set('deviceId', deviceId);
+    let socket;
+    try {
+      socket = new WebSocketImpl(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        perMessageDeflate: false
+      });
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      scheduleReconnect(connect);
+      return;
+    }
+    if (stopped || ownerGeneration !== generation) {
+      try { socket.terminate?.(); } catch { /* stale connect is already gone */ }
+      return;
+    }
+    relaySocket = socket;
+    socket.once('open', () => {
+      if (relaySocket !== socket || ownerGeneration !== generation || stopped) return;
+      retryAttempt = 0;
+      state = 'authenticating';
+    });
+    socket.on('message', raw => {
+      if (relaySocket === socket && ownerGeneration === generation && !stopped) handleMessage(raw);
+    });
+    socket.once('close', () => {
+      if (relaySocket === socket) relaySocket = null;
+      if (ownerGeneration !== generation || stopped) return;
+      state = 'disconnected';
+      closeAllLocalSockets('relay-disconnected');
+      scheduleReconnect(connect);
+    });
+    socket.once('error', error => {
+      lastError = error instanceof Error ? error.message : String(error);
+      try { socket.terminate?.(); } catch { /* close handler owns retry */ }
+    });
+  };
+
+  const start = () => {
+    if (!stopped || !(relayUrl instanceof URL) || !deviceId) return;
+    stopped = false;
+    void connect();
+  };
+
+  const refresh = () => {
+    if (stopped) {
+      start();
+      return;
+    }
+    generation += 1;
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    const socket = relaySocket;
+    relaySocket = null;
+    try { socket?.terminate?.(); } catch { /* refresh owns the exact socket */ }
+    closeAllLocalSockets('relay-refresh');
+    void connect();
+  };
+
+  const close = () => {
+    if (stopped) return;
+    stopped = true;
+    generation += 1;
+    if (retryTimer) clearTimeout(retryTimer);
+    retryTimer = null;
+    closeAllLocalSockets('hub-shutdown');
+    const socket = relaySocket;
+    relaySocket = null;
+    try { socket?.close(1001, 'hub-shutdown'); } catch { /* exact socket is already closed */ }
+    try { socket?.terminate?.(); } catch { /* exact socket is already closed */ }
+    state = relayUrl ? 'closed' : 'disabled';
+  };
+
+  return {
+    start,
+    refresh,
+    close,
+    inspect: () => ({
+      enabled: relayUrl instanceof URL && Boolean(deviceId),
+      state,
+      connected: state === 'connected',
+      localWebSocketChannels: localSockets.size,
+      pendingHttpRequests: pendingHttp.size,
+      droppedBinaryMessages,
+      lastConnectedAt,
+      lastError
+    })
+  };
+}
+
+export const consoleRelayContract = Object.freeze({
+  maxChannels: MAX_CHANNELS,
+  maxHttpRequestBytes: MAX_HTTP_REQUEST_BYTES,
+  maxHttpResponseBytes: MAX_HTTP_RESPONSE_BYTES,
+  maxBufferedBytes: MAX_RELAY_BUFFERED_BYTES,
+  binaryHeaderBytes: BINARY_HEADER_BYTES
+});