mecord-connect 1.0.0

package/runtime/app/src/core/relay-client.js

@@ -0,0 +1,568 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { DeviceIdentityStore } from './device-identity.js';
+import { OperatorError } from './errors.js';
+import { readDurableStateText, writeDurableStateText } from './durable-state.js';
+
+const PROTOCOL = 1;
+const MAX_FRAME_BYTES = 256 * 1024;
+const MAX_DELIVERY_ID = 128;
+const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER;
+const MIN_BACKOFF_MS = 250;
+const MAX_BACKOFF_MS = 30_000;
+const DEFAULT_HEARTBEAT_MS = 20_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
+const MIN_CONNECT_TIMEOUT_MS = 100;
+const MAX_CONNECT_TIMEOUT_MS = 60_000;
+
+                                          
+
+                                  
+                              
+                        
+                           
+                                              
+                                                                                                       
+                                                                                                           
+ 
+
+                                                                  
+
+                                
+              
+             
+               
+                      
+ 
+
+                                       
+                          
+               
+                
+               
+                      
+    
+ 
+
+                                                             
+
+                                              
+                                                 
+                            
+ 
+
+                                                          
+
+                      
+             
+                             
+                
+                
+               
+                      
+    
+ 
+
+                        
+                  
+              
+                       
+                        
+                             
+                       
+                        
+                          
+ 
+
+                         
+                   
+              
+             
+               
+                      
+ 
+
+                                                   
+
+                                                            
+
+                                     
+                   
+              
+                                
+                                     
+                                         
+                                            
+                                                              
+                                                         
+                                                                                 
+                                                                                                      
+                                                                                         
+                                    
+                        
+                     
+                                        
+                            
+ 
+
+export class RelayClient {
+  #stateFile        ;
+  #url        ;
+  #identity                     ;
+  #socketFactory                    ;
+  #getSessionToken                       ;
+  #getSupportedCapabilities                         ;
+  #requireCapabilityBinding         ;
+  #onDelivery                                            ;
+  #onRecovery                                                                    ;
+  #onExpiredRecovery                                                                                  ;
+  #onAcknowledged                                                                        ;
+  #random              ;
+  #clock            ;
+  #sleep                               ;
+  #connectTimeoutMs        ;
+  #stopped = false;
+  #socket                         = null;
+  #attempt = 0;
+  #heartbeatTimer                        = null;
+  #lastPongAt = 0;
+  #interruptConnection                      = null;
+
+  constructor(options                    ) {
+    this.#stateFile = path.join(path.resolve(options.stateDir), 'relay-client.json');
+    this.#url = validateRelayUrl(options.url, Boolean(options.allowLoopbackInsecureWs));
+    this.#identity = options.identity;
+    this.#socketFactory = options.socketFactory ?? nativeSocketFactory;
+    this.#getSessionToken = options.getSessionToken;
+    if (options.supportedCapabilities !== undefined && options.getSupportedCapabilities) {
+      throw new OperatorError('RELAY_CAPABILITIES_CONFIGURATION_INVALID', 'Configure either static or dynamic relay capabilities, not both.');
+    }
+    this.#requireCapabilityBinding = options.supportedCapabilities !== undefined || options.getSupportedCapabilities !== undefined;
+    const staticCapabilities = validateSupportedCapabilities(options.supportedCapabilities ?? []);
+    this.#getSupportedCapabilities = options.getSupportedCapabilities
+      ? async () => validateSupportedCapabilities(await options.getSupportedCapabilities ())
+      : async () => [...staticCapabilities];
+    this.#onDelivery = options.onDelivery;
+    this.#onRecovery = options.onRecovery;
+    this.#onExpiredRecovery = options.onExpiredRecovery;
+    this.#onAcknowledged = options.onAcknowledged;
+    this.#random = options.random ?? Math.random;
+    this.#clock = options.clock ?? (() => new Date());
+    this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.#connectTimeoutMs = boundedConnectTimeout(options.connectTimeoutMs);
+  }
+
+  async run()                {
+    this.#stopped = false;
+    while (!this.#stopped) {
+      try {
+        await this.#connectOnce();
+        this.#attempt = 0;
+      } catch (error) {
+        if (this.#stopped) break;
+        if (error instanceof OperatorError && !error.retryable) throw error;
+        const delay = reconnectDelay(this.#attempt++, this.#random());
+        await this.#sleep(delay);
+      }
+    }
+  }
+
+  stop()       {
+    this.#stopped = true;
+    this.#clearHeartbeat();
+    try { this.#socket?.close(1000, 'operator stopping'); } catch { /* already closed */ }
+    this.#socket = null;
+  }
+
+  reconnect()       {
+    if (this.#stopped) return;
+    const interrupt = this.#interruptConnection;
+    if (interrupt) {
+      interrupt();
+      return;
+    }
+    try { this.#socket?.close(1012, 'session refresh recovery'); } catch { /* reconnect loop handles the next attempt */ }
+  }
+
+  async state()                                {
+    return await this.#readState();
+  }
+
+  async #connectOnce()                {
+    const state = await this.#readState();
+    const token = await this.#getSessionToken();
+    const supportedCapabilities = await this.#getSupportedCapabilities();
+    if (!token || Buffer.byteLength(token, 'utf8') > 16 * 1024) {
+      throw new OperatorError('RELAY_SESSION_TOKEN_INVALID', 'Relay session token is missing or exceeds the bounded size.');
+    }
+
+    const socket = this.#socketFactory(this.#url);
+    this.#socket = socket;
+    await waitForOpen(socket, this.#connectTimeoutMs);
+    if (typeof socket.url === 'string' && !sameRelayDestination(this.#url, socket.url)) {
+      try { socket.close(4003, 'destination changed'); } catch { /* mismatch is already authoritative */ }
+      throw new OperatorError('RELAY_SOCKET_DESTINATION_CHANGED', 'Opened relay WebSocket destination differs from the authorized endpoint.', { retryable: false });
+    }
+    if (this.#stopped) return;
+
+    const identity = await this.#identity.loadOrCreate();
+    const helloPayload = {
+      protocol: PROTOCOL,
+      deviceId: identity.deviceId,
+      deviceName: identity.deviceName,
+      fingerprint: identity.fingerprint,
+      resumeAfterSeq: state.lastAckedServerSeq,
+      pendingRecovery: state.processing ? { seq: state.processing.seq, id: state.processing.id } : null,
+      ...(this.#requireCapabilityBinding ? { capabilityBinding: 1         , capabilities: [...supportedCapabilities] } : {}),
+      sentAt: this.#clock().toISOString(),
+      nonce: crypto.randomBytes(24).toString('base64url')
+    };
+    const signature = await this.#identity.sign(canonicalBytes(helloPayload));
+
+    const connectionDone = new Promise      ((resolve, reject) => {
+      let welcomed = false;
+      let settled = false;
+      let messageQueue                = Promise.resolve();
+      let interrupt                      = null;
+
+      const cleanup = () => {
+        socket.removeEventListener?.('message', onMessage);
+        socket.removeEventListener?.('error', onError);
+        socket.removeEventListener?.('close', onClose);
+        if (this.#interruptConnection === interrupt) this.#interruptConnection = null;
+      };
+      const succeed = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const fail = (error         ) => {
+        if (settled) return;
+        settled = true;
+        this.#clearHeartbeat();
+        cleanup();
+        try { socket.close(4002, 'protocol/recovery error'); } catch { /* noop */ }
+        reject(error instanceof OperatorError ? error : new OperatorError('RELAY_PROTOCOL_ERROR', error instanceof Error ? error.message : String(error), { retryable: true }));
+      };
+      const onError = () => fail(new OperatorError('RELAY_SOCKET_ERROR', 'Relay socket reported an error.', { retryable: true }));
+      const onClose = () => {
+        if (this.#stopped) succeed();
+        else fail(new OperatorError(welcomed ? 'RELAY_SOCKET_CLOSED' : 'RELAY_CONNECT_FAILED', welcomed ? 'Relay socket closed unexpectedly.' : 'Relay socket closed before handshake completion.', { retryable: true }));
+      };
+      interrupt = () => fail(new OperatorError('RELAY_RECONNECT_REQUESTED', 'Relay reconnect was requested.', { retryable: true }));
+      this.#interruptConnection = interrupt;
+      const processMessage = async (event     ) => {
+        const frame = parseServerFrame(event?.data);
+        if (!welcomed) {
+          if (frame.type !== 'welcome') throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay sent a non-welcome frame before handshake completion.');
+          await this.#validateWelcome(frame, state, supportedCapabilities);
+          welcomed = true;
+          this.#attempt = 0;
+          this.#lastPongAt = Date.now();
+          this.#startHeartbeat(socket, boundedHeartbeat(frame.heartbeatMs));
+          return;
+        }
+        if (frame.type === 'pong') {
+          this.#lastPongAt = Date.now();
+          return;
+        }
+        if (frame.type === 'welcome') throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay sent a duplicate welcome frame.');
+        await this.#handleDelivery(socket, frame);
+      };
+      const onMessage = (event     ) => {
+        messageQueue = messageQueue.then(() => processMessage(event));
+        void messageQueue.catch(fail);
+      };
+
+      socket.addEventListener('message', onMessage);
+      socket.addEventListener('error', onError);
+      socket.addEventListener('close', onClose);
+    });
+
+    sendFrame(socket, { type: 'hello', payload: helloPayload, signature, sessionToken: token });
+    await connectionDone;
+    this.#clearHeartbeat();
+    this.#socket = null;
+  }
+
+  async #validateWelcome(frame              , state            , supportedCapabilities                   )                {
+    if (frame.protocol !== PROTOCOL) throw new OperatorError('RELAY_PROTOCOL_VERSION', 'Relay protocol version mismatch.');
+    if (this.#requireCapabilityBinding) {
+      const legacyRelay = frame.capabilityBinding === undefined && frame.capabilities === undefined;
+      if (!legacyRelay) {
+        if (frame.capabilityBinding !== 1 || frame.capabilities === undefined) {
+          throw new OperatorError('RELAY_CAPABILITY_BINDING_INVALID', 'Relay returned a partial or invalid capability-binding negotiation.', { retryable: false });
+        }
+        const effective = validateSupportedCapabilities(frame.capabilities);
+        const advertised = new Set(supportedCapabilities);
+        if (effective.some((capability) => !advertised.has(capability))) {
+          throw new OperatorError('RELAY_CAPABILITY_BINDING_INVALID', 'Relay acknowledged a capability that the local runtime did not advertise.', { retryable: false });
+        }
+      }
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(frame.connectionId)) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay connection ID is invalid.');
+    if (!Number.isSafeInteger(frame.resumeFromSeq) || frame.resumeFromSeq < 0) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay resume sequence is invalid.');
+    const expiredThroughSeq = frame.expiredThroughSeq;
+    if (expiredThroughSeq !== undefined && (!Number.isSafeInteger(expiredThroughSeq) || expiredThroughSeq < 1 || expiredThroughSeq !== frame.resumeFromSeq)) {
+      throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay expired-history reconciliation proof is invalid.');
+    }
+    if (frame.resumeFromSeq === state.lastAckedServerSeq) {
+      if (expiredThroughSeq !== undefined) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay supplied an unnecessary expired-history reconciliation proof.');
+      return;
+    }
+    if (frame.resumeFromSeq < state.lastAckedServerSeq || expiredThroughSeq !== frame.resumeFromSeq) {
+      throw new OperatorError('RELAY_RESUME_MISMATCH', 'Relay resume cursor does not match the durable local acknowledgement cursor.', { retryable: true });
+    }
+    if (state.processing) {
+      if (state.processing.seq > frame.resumeFromSeq || !this.#onExpiredRecovery) {
+        throw new OperatorError('RELAY_RECOVERY_CONFLICT', 'Relay cannot skip expired history while a local delivery remains in uncertain processing state.', { retryable: false });
+      }
+      const decision = await this.#onExpiredRecovery({ processing: { ...state.processing }, expiredThroughSeq: frame.resumeFromSeq });
+      if (decision !== 'ack') {
+        throw new OperatorError('RELAY_RECOVERY_REQUIRED', 'Expired delivery recovery callback refused to reconcile the durable processing result.', { retryable: false });
+      }
+    }
+    await this.#writeState({ version: 1, lastAckedServerSeq: frame.resumeFromSeq });
+    if (state.processing && state.processing.seq <= frame.resumeFromSeq) {
+      await this.#notifyAcknowledged(state.processing);
+    }
+  }
+
+  async #handleDelivery(socket                 , frame               )                {
+    const delivery = validateDelivery(frame);
+    let state = await this.#readState();
+
+    if (delivery.seq <= state.lastAckedServerSeq) {
+      await this.#notifyAcknowledged(delivery);
+      sendFrame(socket, { type: 'ack', seq: delivery.seq, id: delivery.id, duplicate: true });
+      return;
+    }
+    if (delivery.seq !== state.lastAckedServerSeq + 1) {
+      throw new OperatorError('RELAY_SEQUENCE_GAP', `Expected relay sequence ${state.lastAckedServerSeq + 1} but received ${delivery.seq}.`, { retryable: true });
+    }
+
+    if (state.processing) {
+      if (state.processing.seq !== delivery.seq || state.processing.id !== delivery.id) {
+        throw new OperatorError('RELAY_RECOVERY_CONFLICT', 'A different delivery arrived while an uncertain delivery is awaiting recovery.', { retryable: false });
+      }
+      if (!this.#onRecovery) {
+        throw new OperatorError('RELAY_RECOVERY_REQUIRED', 'A prior delivery may have executed before a crash; explicit recovery is required before replay.', { retryable: false });
+      }
+      const decision = await this.#onRecovery({ delivery, processing: { ...state.processing } });
+      if (decision === 'stop') throw new OperatorError('RELAY_RECOVERY_REQUIRED', 'Recovery callback refused to continue the uncertain delivery.', { retryable: false });
+      if (decision === 'retry') {
+        await this.#writeState({ ...state, processing: undefined });
+        state = await this.#readState();
+      } else if (decision === 'ack') {
+        const completed = { version: 1         , lastAckedServerSeq: delivery.seq };
+        await this.#writeState(completed);
+        await this.#notifyAcknowledged(delivery);
+        sendFrame(socket, { type: 'ack', seq: delivery.seq, id: delivery.id, recovered: true });
+        return;
+      } else {
+        throw new OperatorError('RELAY_RECOVERY_REQUIRED', 'Recovery callback returned an invalid decision.', { retryable: false });
+      }
+    }
+
+    const processing                           = { seq: delivery.seq, id: delivery.id, startedAt: this.#clock().toISOString() };
+    await this.#writeState({ ...state, processing });
+    await this.#onDelivery(delivery);
+    await this.#writeState({ version: 1, lastAckedServerSeq: delivery.seq });
+    await this.#notifyAcknowledged(delivery);
+    sendFrame(socket, { type: 'ack', seq: delivery.seq, id: delivery.id });
+  }
+
+  async #notifyAcknowledged(delivery                                   )                {
+    try { await this.#onAcknowledged?.({ seq: delivery.seq, id: delivery.id }); }
+    catch { /* acknowledgement is already durable; cleanup is best-effort */ }
+  }
+
+  #startHeartbeat(socket                 , heartbeatMs        )       {
+    this.#clearHeartbeat();
+    this.#heartbeatTimer = setInterval(() => {
+      if (Date.now() - this.#lastPongAt > heartbeatMs * 3) {
+        try { socket.close(4000, 'heartbeat timeout'); } catch { /* noop */ }
+        return;
+      }
+      const nonce = crypto.randomBytes(12).toString('base64url');
+      try { sendFrame(socket, { type: 'ping', nonce, at: new Date().toISOString() }); } catch { /* close path handles reconnect */ }
+    }, heartbeatMs);
+    this.#heartbeatTimer.unref();
+  }
+
+  #clearHeartbeat()       {
+    if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
+    this.#heartbeatTimer = null;
+  }
+
+  async #readState()                      {
+    try {
+      const text = await readDurableStateText(this.#stateFile, {
+        maxBytes: 64 * 1024,
+        errorCode: 'RELAY_STATE_CORRUPT',
+        invalidMessage: 'Relay client state is invalid.'
+      });
+      return validateState(JSON.parse(text));
+    } catch (error) {
+      if ((error                         ).code === 'ENOENT') return { version: 1, lastAckedServerSeq: 0 };
+      if (error instanceof OperatorError) throw error;
+      throw new OperatorError('RELAY_STATE_CORRUPT', 'Relay client state could not be read.');
+    }
+  }
+
+  async #writeState(stateInput            )                {
+    const state = validateState(stateInput);
+    await writeDurableStateText(this.#stateFile, JSON.stringify(state, null, 2), {
+      maxBytes: 64 * 1024,
+      errorCode: 'RELAY_STATE_CORRUPT',
+      invalidMessage: 'Relay client state is invalid.'
+    });
+  }
+}
+
+export function reconnectDelay(attemptInput        , randomInput = Math.random())         {
+  const attempt = Math.min(Math.max(Math.trunc(attemptInput), 0), 20);
+  const random = Number.isFinite(randomInput) ? Math.min(Math.max(randomInput, 0), 1) : 0.5;
+  const base = Math.min(MIN_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+  const jitter = 0.75 + random * 0.5;
+  return Math.min(Math.max(Math.round(base * jitter), MIN_BACKOFF_MS), MAX_BACKOFF_MS);
+}
+
+
+function validateSupportedCapabilities(input                   )           {
+  if (!Array.isArray(input) || input.length > 128) {
+    throw new OperatorError('RELAY_CAPABILITIES_INVALID', 'Relay supported capabilities must be a bounded array.');
+  }
+  const output           = [];
+  const seen = new Set        ();
+  for (const item of input) {
+    const capability = String(item ?? '');
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(capability)) {
+      throw new OperatorError('RELAY_CAPABILITIES_INVALID', 'Relay supported capability name is invalid.');
+    }
+    if (seen.has(capability)) continue;
+    seen.add(capability);
+    output.push(capability);
+  }
+  return output.sort();
+}
+
+function sameRelayDestination(expectedRaw        , actualRaw        )          {
+  try { return new URL(expectedRaw).toString() === new URL(actualRaw).toString(); } catch { return false; }
+}
+
+export function validateRelayUrl(urlInput        , allowLoopbackInsecureWs = false)         {
+  let url     ;
+  try { url = new URL(urlInput); } catch { throw new OperatorError('RELAY_URL_INVALID', 'Relay URL is invalid.'); }
+  if (url.username || url.password || url.hash) throw new OperatorError('RELAY_URL_INVALID', 'Relay URL must not contain credentials or a fragment.');
+  if (url.protocol === 'wss:') return url.toString();
+  if (url.protocol === 'ws:' && allowLoopbackInsecureWs && isLoopbackHost(url.hostname)) return url.toString();
+  throw new OperatorError('RELAY_TLS_REQUIRED', 'Relay connections require wss://; insecure ws:// is permitted only for explicit loopback development tests.');
+}
+
+function validateState(input     )             {
+  if (!input || input.version !== 1 || !Number.isSafeInteger(input.lastAckedServerSeq) || input.lastAckedServerSeq < 0 || input.lastAckedServerSeq > MAX_SEQUENCE) {
+    throw new OperatorError('RELAY_STATE_CORRUPT', 'Relay client state structure is invalid.');
+  }
+  if (input.processing === undefined) return { version: 1, lastAckedServerSeq: input.lastAckedServerSeq };
+  const seq = Number(input.processing.seq);
+  const id = validDeliveryId(String(input.processing.id ?? ''));
+  const startedAt = validIso(String(input.processing.startedAt ?? ''));
+  if (!Number.isSafeInteger(seq) || seq !== input.lastAckedServerSeq + 1) throw new OperatorError('RELAY_STATE_CORRUPT', 'Relay processing sequence is invalid.');
+  return { version: 1, lastAckedServerSeq: input.lastAckedServerSeq, processing: { seq, id, startedAt } };
+}
+
+function validateDelivery(frame               )                {
+  if (!Number.isSafeInteger(frame.seq) || frame.seq < 1 || frame.seq > MAX_SEQUENCE) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay delivery sequence is invalid.');
+  const id = validDeliveryId(frame.id);
+  const kind = String(frame.kind ?? '');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(kind)) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay delivery kind is invalid.');
+  if (!frame.payload || typeof frame.payload !== 'object' || Array.isArray(frame.payload)) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay delivery payload must be an object.');
+  return { seq: frame.seq, id, kind, payload: frame.payload };
+}
+
+function validDeliveryId(value        )         {
+  if (!value || value.length > MAX_DELIVERY_ID || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value)) throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay delivery ID is invalid.');
+  return value;
+}
+
+function validIso(value        )         {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) throw new OperatorError('RELAY_STATE_CORRUPT', 'Relay state timestamp is invalid.');
+  return value;
+}
+
+function parseServerFrame(raw         )              {
+  const text = typeof raw === 'string' ? raw : raw instanceof ArrayBuffer ? Buffer.from(raw).toString('utf8') : ArrayBuffer.isView(raw) ? Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString('utf8') : '';
+  if (!text || Buffer.byteLength(text, 'utf8') > MAX_FRAME_BYTES) throw new OperatorError('RELAY_FRAME_INVALID', 'Relay frame is missing or exceeds the bounded size.');
+  let parsed     ;
+  try { parsed = JSON.parse(text); } catch { throw new OperatorError('RELAY_FRAME_INVALID', 'Relay frame is not valid JSON.'); }
+  if (!parsed || typeof parsed !== 'object') throw new OperatorError('RELAY_FRAME_INVALID', 'Relay frame must be an object.');
+  if (parsed.type === 'welcome') return parsed                ;
+  if (parsed.type === 'delivery') return parsed                 ;
+  if (parsed.type === 'pong' && typeof parsed.nonce === 'string') return parsed             ;
+  throw new OperatorError('RELAY_PROTOCOL_ERROR', 'Relay frame type is unsupported.');
+}
+
+function sendFrame(socket                 , frame            )       {
+  const text = JSON.stringify(frame);
+  if (Buffer.byteLength(text, 'utf8') > MAX_FRAME_BYTES) throw new OperatorError('RELAY_FRAME_TOO_LARGE', 'Outbound relay frame exceeds the bounded size.');
+  socket.send(text);
+}
+
+function boundedHeartbeat(value         )         {
+  const parsed = Number(value ?? DEFAULT_HEARTBEAT_MS);
+  if (!Number.isInteger(parsed)) return DEFAULT_HEARTBEAT_MS;
+  return Math.min(Math.max(parsed, 5_000), 60_000);
+}
+
+function waitForOpen(socket                 , timeoutMs        )                {
+  if (socket.readyState === 1) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback            ) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const onOpen = () => finish(resolve);
+    const onError = () => finish(() => reject(new OperatorError('RELAY_CONNECT_FAILED', 'Relay socket failed before opening.', { retryable: true })));
+    const onClose = () => finish(() => reject(new OperatorError('RELAY_CONNECT_FAILED', 'Relay socket closed before opening.', { retryable: true })));
+    const timer = setTimeout(() => finish(() => {
+      try { socket.close(4001, 'connect timeout'); } catch { /* timeout failure is already authoritative */ }
+      reject(new OperatorError('RELAY_CONNECT_TIMEOUT', `Relay socket did not open within ${timeoutMs}ms.`, { retryable: true }));
+    }), timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeEventListener?.('open', onOpen);
+      socket.removeEventListener?.('error', onError);
+      socket.removeEventListener?.('close', onClose);
+    };
+    socket.addEventListener('open', onOpen);
+    socket.addEventListener('error', onError);
+    socket.addEventListener('close', onClose);
+  });
+}
+
+function boundedConnectTimeout(value         )         {
+  const parsed = Number(value ?? DEFAULT_CONNECT_TIMEOUT_MS);
+  if (!Number.isFinite(parsed)) return DEFAULT_CONNECT_TIMEOUT_MS;
+  return Math.min(Math.max(Math.trunc(parsed), MIN_CONNECT_TIMEOUT_MS), MAX_CONNECT_TIMEOUT_MS);
+}
+
+function canonicalBytes(value            )         {
+  return Buffer.from(JSON.stringify(value), 'utf8');
+}
+
+function nativeSocketFactory(url        )                  {
+  const Ctor = (globalThis       ).WebSocket;
+  if (typeof Ctor !== 'function') throw new OperatorError('RELAY_WEBSOCKET_UNAVAILABLE', 'This Node runtime does not provide a WebSocket client.', { retryable: false });
+  return new Ctor(url)                   ;
+}
+
+function isLoopbackHost(hostname        )          {
+  const value = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  return value === 'localhost' || value === '127.0.0.1' || value === '::1';
+}