import { waitForRelayCapacity, SerialSend, ControlLease } from '@dsh-remote/webrtc' import { NoiseIkSession, createNoisePrologue, fromBase64Url, toBase64Url, } from '@dsh-remote/crypto' import { DEFAULT_HEARTBEAT_INTERVAL_MS, PROTOCOL_VERSION, WEBRTC_RESUME_CAPABILITY, RELAY_RESUME_CAPABILITY, classifyControlClose, type ConnectionLeaseAck, SecureMessageCodec, acceptNegotiatedCapabilities, createControlFrame, createRelayDataFrame, decodeControlFrame, decodeRelayDataFrame, decodeMessage, encodeControlFrame, encodeMessage, encodeRelayDataFrame, type ControlFrameByteLimits, type ConnectIncomingPayload, type ControlErrorPayload, type HelloAckPayload, type RelayPayload, type RemoteMessage, type SecureHandshakePayload, type SelectedTransport, type SignalIcePayload, type SignalPayload, type TransportSelectedPayload, } from '@dsh-remote/protocol' import { RtcDataChannelTransport, stunOnlyIceServers, type RtcConnectionDiagnostics, type RtcIceServer, type RtcPeerConnectionFactory, type RtcSelectedTransport, type RtcSignal, } from '@dsh-remote/webrtc' import type { ConnectionCloseDetail, ConnectionController } from './connection-controller.js' import { isForceRelayEnabled } from './relay-preference.js' import type { ResolvedConfig } from './config.js' import type { HostIdentity, IdentityStore, TrustedPeer } from './identity-store.js' import type { SafeLogger } from './logging.js' import type { AuthorizedPeerDevice, HostServerApi } from './server-api.js' import { ServerApiError } from './server-api.js' import type { AuthenticatedPeerChannel } from './types.js' import { PLUGIN_VERSION } from './version.js' interface WebSocketLike { readonly readyState: number binaryType?: string onopen: ((event: unknown) => void) | null onmessage: ((event: { data: unknown }) => void) | null onerror: ((event: unknown) => void) | null onclose: ((event: { code: number; reason: string }) => void) | null send(data: string): void close(code?: number, reason?: string): void } type RelayAssignment = Pick export type WebSocketFactory = (url: string) => WebSocketLike interface PendingTunnel { recoveryTicket?: string relayRecoveryTicket?: string lease?: ControlLease connectionId: string membershipId: string peer: TrustedPeer preferredTransports: ConnectIncomingPayload['preferredTransports'] noise: NoiseIkSession transport: 'negotiating' | SelectedTransport transportMode?: 'LAN' | 'P2P' | 'TURN' rtc?: RtcDataChannelTransport channel?: ServerNoiseChannel pendingHandshake?: SecureHandshakePayload /** ICE candidates that arrived while the offer handler was still preparing the RTC backend. */ pendingIce?: SignalIcePayload['candidate'][] relayAssignment?: RelayAssignment dataSocket?: WebSocketLike dataReady?: boolean } const DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 12_000 /** * Transport capabilities the Host announces in `hello`. Relay-only wins when * the operator forces the relay or when this Host has no WebRTC backend: the * Server then never negotiates LAN/P2P/TURN for this device and the initiator * has nothing to probe. */ export function advertisedTransportCapabilities(forceRelay: boolean, rtcAvailable: boolean): string[] { return forceRelay || !rtcAvailable ? ['transport.relay', 'transport.relay.attach'] : ['transport.lan', 'transport.p2p', 'transport.turn', 'transport.relay', 'transport.relay.attach'] } export class HostServerConnection { private socket?: WebSocketLike private forceCloseSocket?: (code: number, reason: string) => void private running?: Promise private stopped = true private online = false private retryWake?: () => void private readonly tunnels = new Map() private terminalError?: string private lastActiveAt?: number private reconnectRequested = false private resumeQueued = false private authRecoveryAttempted = false private rtcFactory?: RtcPeerConnectionFactory private negotiatedCapabilities: string[] = ['transport.relay'] private controlFrameLimits: ControlFrameByteLimits = {} private heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS private webRtcNegotiateTimeoutMs = DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS constructor( private readonly config: ResolvedConfig, private readonly identity: HostIdentity, private readonly identities: IdentityStore, private readonly api: HostServerApi, private readonly connections: ConnectionController, private readonly logger: SafeLogger, private readonly createWebSocket: WebSocketFactory = url => new WebSocket(url) as unknown as WebSocketLike, private readonly rtcFactoryProvider?: () => Promise, private readonly hostCapabilities: () => readonly string[] = () => [], private readonly harnessVersion?: string, ) {} start(): void { if (this.running !== undefined) return this.stopped = false this.running = this.run().finally(() => { this.running = undefined }) } resume(): void { this.terminalError = undefined this.stopped = false if (this.running === undefined) { this.start() return } this.retryWake?.() if (this.resumeQueued) return this.resumeQueued = true void this.running.finally(() => { this.resumeQueued = false if (!this.stopped) this.start() }) } async stop(): Promise { this.stopped = true this.reconnectRequested = false this.retryWake?.() this.retryWake = undefined for (const tunnel of this.tunnels.values()) this.notifyTunnelClosed(tunnel) if (this.forceCloseSocket) this.forceCloseSocket(1000, 'plugin stopped') else this.socket?.close(1000, 'plugin stopped') await this.running await this.dropTunnels() } isOnline(): boolean { return this.online } recoveryExpiresAt(): number | undefined { const remaining = [...this.tunnels.values()].flatMap(tunnel => { const ms = tunnel.lease?.remainingMs() return ms === undefined ? [] : [ms] }) return remaining.length ? Date.now() + Math.min(...remaining) : undefined } lastError(): string | undefined { return this.terminalError } lastActivity(): number | undefined { return this.lastActiveAt } isReconnecting(): boolean { return !this.online && !this.stopped && this.running !== undefined } reconnect(): void { this.terminalError = undefined this.stopped = false if (this.running === undefined) { this.start() return } this.reconnectRequested = true this.retryWake?.() if (this.forceCloseSocket) this.forceCloseSocket(4000, 'manual reconnect') else this.socket?.close(4000, 'manual reconnect') void this.running.finally(() => { if (!this.reconnectRequested || this.stopped) return this.reconnectRequested = false this.start() }) } private async run(): Promise { this.authRecoveryAttempted = false while (!this.stopped) { try { await this.connectOnce() } catch (error) { if (this.stopped) return const code = errorCode(error) if (code === 'CREDENTIALS_REFRESHED') continue this.terminalError = code this.logger.warn('server control connection failed', { code, retryable: isRetryable(error), ...(error instanceof ServerApiError && error.phase !== undefined ? { phase: error.phase } : {}), ...(error instanceof ServerApiError && error.status !== undefined ? { status: error.status } : {}), ...(error instanceof ServerApiError && error.reason !== undefined ? { reason: error.reason } : {}), }) if (code === 'UNSUPPORTED_VERSION') { this.logger.warn('Server does not support the Remote protocol version; automatic reconnect is paused.') } if (TERMINAL_AUTH_ERRORS.has(code)) { this.logger.warn(code === 'CONNECTION_REPLACED' ? 'Another instance is using this Host identity. Stop it or use a separate DSH_HOME; automatic reconnect is paused.' : 'Host authorization failed. Authorize this Host again from a Remote client or in Remote settings.') } if (code === 'DEVICE_REVOKED') { try { await this.api.clearAuthorization() } catch (clearError) { this.logger.error('failed to clear revoked Host authorization', { code: errorCode(clearError) }) } } if (TERMINAL_AUTH_ERRORS.has(code) || code === 'UNSUPPORTED_VERSION') { await this.dropTunnels(); return } if (!this.config.reconnect.enabled) return } if (this.stopped) return if (this.reconnectRequested) { this.reconnectRequested = false continue } if (!this.config.reconnect.enabled) return // Every close, including the first, waits a full-jitter draw from // [0, maxDelayMs]. A restarted Server therefore gets the whole fleet // spread over the widest window, and an ordinary network drop cannot // turn into a tight reconnect loop either. await this.waitBeforeRetry() if (this.reconnectRequested) { this.reconnectRequested = false continue } } } private async connectOnce(): Promise { const credentials = await this.api.authenticate(this.identity) if (this.stopped) return const forceRelay = isForceRelayEnabled() || this.config.forceRelay const offeredCapabilities = [ ...(forceRelay || this.rtcFactoryProvider === undefined ? [RELAY_RESUME_CAPABILITY] : [WEBRTC_RESUME_CAPABILITY, RELAY_RESUME_CAPABILITY]), ...advertisedTransportCapabilities(forceRelay, this.rtcFactoryProvider !== undefined), ...this.hostCapabilities(), ] const recoveryTickets = [...this.tunnels.values()].flatMap(tunnel => tunnel.lease?.recoveryTicket() ?? []).slice(0, 64) const socket = this.createWebSocket(websocketUrl(this.api.baseUrl)) this.socket = socket this.controlFrameLimits = {} this.heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS let acknowledged = false let retainOnClose = false let invalidControl = false let socketError: string | undefined let messageQueue = Promise.resolve() await new Promise((resolve, reject) => { let settled = false let closing = false let upgradeTimer: ReturnType | undefined let helloTimer: ReturnType | undefined let refreshTimer: ReturnType | undefined let livenessTimer: ReturnType | undefined const clearLiveness = (): void => { if (livenessTimer === undefined) return clearTimeout(livenessTimer) livenessTimer = undefined } const finish = (error?: Error): void => { if (settled) return settled = true if (upgradeTimer !== undefined) clearTimeout(upgradeTimer) if (helloTimer !== undefined) clearTimeout(helloTimer) if (refreshTimer !== undefined) clearTimeout(refreshTimer) clearLiveness() this.online = false socket.onopen = socket.readyState === 0 ? () => { socket.onopen = null try { socket.close(1000, 'connection abandoned') } catch { // Ignore close failures on an abandoned socket. } ;(socket as { terminate?: () => void }).terminate?.() } : null socket.onmessage = null // Keep an inert error handler until the abandoned socket finishes closing // so asynchronous EventEmitter 'error' emissions on Node `ws` never throw. socket.onerror = () => undefined socket.onclose = () => { socket.onopen = null socket.onerror = null socket.onclose = null } if (this.socket === socket) { this.socket = undefined this.forceCloseSocket = undefined } const preserve = this.config.reconnect.enabled && !this.stopped && !this.reconnectRequested && (error === undefined ? retainOnClose : isRetryable(error)) && !invalidControl && !TERMINAL_AUTH_ERRORS.has(this.terminalError ?? '') && [...this.tunnels.values()].some(tunnel => tunnel.lease?.canDetach()) const cleanup = preserve ? Promise.all([...this.tunnels.values()].filter(tunnel => !tunnel.lease?.canDetach()).map(tunnel => this.dropTunnel(tunnel.connectionId))) : this.dropTunnels() void cleanup.catch(() => undefined).finally(() => error === undefined ? resolve() : reject(error)) } let forceDrainWake: (() => void) | undefined const handleClose = (event: { code: number; reason: string }, forced = false): void => { if (settled || this.socket !== socket) return if (closing) { if (forced) { forceDrainWake?.() if (this.stopped || this.reconnectRequested) finish() } return } closing = true clearLiveness() const closeSemantics = classifyControlClose(event.code, event.reason) // Retain authenticated tunnels only for an expected Server outage or a // peer heartbeat expiry. Another instance replacing us (4003) and // revocation (4004) must never retain; the reason string is the // semantic key because deployments disagree on the shutdown code. retainOnClose = [1000, 1001, 4007].includes(event.code) || (closeSemantics.retryable && !closeSemantics.replaced) const close = async (): Promise => { if (!forced) { let drainTimer: ReturnType | undefined await Promise.race([ messageQueue.catch(() => undefined), new Promise(resolve => { forceDrainWake = resolve drainTimer = setTimeout(resolve, 50) }), ]) if (drainTimer !== undefined) clearTimeout(drainTimer) } forceDrainWake = undefined if (settled) return if (this.stopped) { finish(); return } if (event.code === 4003 || event.reason === 'CONNECTION_REPLACED' || socketError === 'CONNECTION_REPLACED') { finish(new ControlConnectionError('CONNECTION_REPLACED', 'Another instance connected with this Host identity.')) return } if (event.code === 4004 || event.reason === 'DEVICE_REVOKED' || socketError === 'DEVICE_REVOKED' || this.terminalError === 'DEVICE_REVOKED') { finish(new ControlConnectionError('DEVICE_REVOKED', 'The Server revoked this Host device.')) return } if (event.code === 4011 || event.reason === 'UNSUPPORTED_VERSION' || socketError === 'UNSUPPORTED_VERSION' || this.terminalError === 'UNSUPPORTED_VERSION') { finish(new ControlConnectionError('UNSUPPORTED_VERSION', 'The Server does not support the Remote protocol version.')) return } if (!acknowledged && recoveryTickets.length && ([4008, 4012].includes(event.code) || (event.code === 4002 && event.reason === 'recovery authorization rejected'))) { // A rolled-back Server rejects the additive hello field; a newer // Server rejects invalid recovery tickets with a dedicated code. // Also accept the exact reason from the earlier implementation. // Drop the old sessions, then retry the legacy hello once. await this.dropTunnels() if (settled) return finish(new ControlConnectionError('CREDENTIALS_REFRESHED', 'Retry control without recovery state.')) return } // WHY: Hosted and self-hosted Servers report expired/invalid access // tokens differently (close 4002, control `error` frame AUTH_INVALID / // TOKEN_EXPIRED, or close 4001 with reason AUTH_INVALID / TOKEN_EXPIRED). // All of them must enter the single-attempt refresh recovery path. const isAuthRejection = event.code === 4002 || socketError === 'AUTH_INVALID' || socketError === 'TOKEN_EXPIRED' || (event.code === 4001 && (event.reason === 'AUTH_INVALID' || event.reason === 'TOKEN_EXPIRED')) if (isAuthRejection) { if (this.authRecoveryAttempted) { finish(new ControlConnectionError('AUTH_INVALID', 'Server rejected refreshed credentials.')) return } this.terminalError = undefined try { await Promise.race([ this.api.refreshCredentials(credentials.accessToken), new Promise((_, rejectRefresh) => { refreshTimer = setTimeout( () => rejectRefresh(new ControlConnectionError('CONNECTION_FAILED', 'Credential refresh timed out.')), 15_000, ) }), ]) } catch (error) { if (refreshTimer !== undefined) { clearTimeout(refreshTimer) refreshTimer = undefined } if (settled) return finish(asError(error)) return } if (refreshTimer !== undefined) { clearTimeout(refreshTimer) refreshTimer = undefined } if (settled) return // Only a successfully refreshed credential consumes the hello retry. // Transient refresh errors must remain eligible for normal backoff. this.authRecoveryAttempted = true this.terminalError = undefined finish(new ControlConnectionError('CREDENTIALS_REFRESHED', 'Retry hello with refreshed credentials.')) return } const finalCode = socketError ?? closeCode(event.code) if (acknowledged && this.terminalError === undefined) this.terminalError = finalCode finish(acknowledged ? undefined : new ControlConnectionError(finalCode, event.reason || 'Server control connection closed.')) } void close() } const closeSocket = (code: number, reason: string): void => { try { socket.close(code, reason) } catch { try { socket.close(1000, reason) } catch { // Half-open or CONNECTING sockets may fail to send a close frame; settle below. } } ;(socket as { terminate?: () => void }).terminate?.() handleClose({ code, reason }, true) } this.forceCloseSocket = closeSocket const armLiveness = (): void => { clearLiveness() const timeoutMs = Math.max(15_000, this.heartbeatIntervalMs * 3) livenessTimer = setTimeout(() => { livenessTimer = undefined if (this.stopped || settled || closing || this.socket !== socket) return const silentMs = this.lastActiveAt === undefined ? timeoutMs : Math.max(0, Date.now() - this.lastActiveAt) this.logger.warn('server control heartbeat timeout; reconnecting', { silentMs, heartbeatIntervalMs: this.heartbeatIntervalMs, }) closeSocket(4009, 'heartbeat timeout') }, timeoutMs) ;(livenessTimer as { unref?: () => void }).unref?.() } upgradeTimer = setTimeout(() => closeSocket(4001, 'upgrade timeout'), 30_000) ;(upgradeTimer as { unref?: () => void }).unref?.() socket.onopen = () => { if (settled || closing || this.socket !== socket) return if (upgradeTimer !== undefined) { clearTimeout(upgradeTimer) upgradeTimer = undefined } // The hello deadline starts after the WebSocket upgrade. The handshake // itself can be slow, and closing a socket while CONNECTING throws in // some implementations (including Node's built-in WebSocket). helloTimer = setTimeout(() => closeSocket(4001, 'hello timeout'), 10_000) this.sendControl('hello', { role: 'host', deviceId: this.identity.deviceId, accessToken: credentials.accessToken, protocols: [PROTOCOL_VERSION], clientVersion: PLUGIN_VERSION, ...(this.harnessVersion === undefined ? {} : { harnessVersion: this.harnessVersion }), capabilities: offeredCapabilities, ...(recoveryTickets.length ? { recoveryTickets } : {}), }) } socket.onmessage = event => { if (settled || closing || this.socket !== socket) return try { const preview = decodeControl(event.data, this.controlFrameLimits) if (preview.type === 'error') { const payload = requireControlError(preview.payload) if (payload.code === 'DEVICE_REVOKED' || payload.connectionId === undefined) { socketError = payload.code if (payload.code !== 'AUTH_INVALID' && payload.code !== 'TOKEN_EXPIRED') { this.terminalError = payload.code } } } } catch { // Malformed frames are handled in order by messageQueue below. } messageQueue = messageQueue.then(async () => { if (settled || this.socket !== socket) return const frame = decodeControl(event.data, this.controlFrameLimits) this.lastActiveAt = Date.now() if (acknowledged) armLiveness() if (frame.type === 'hello.ack') { const payload = requireHelloAck(frame.payload) this.heartbeatIntervalMs = payload.heartbeatIntervalMs this.webRtcNegotiateTimeoutMs = Math.max( DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS, payload.webrtcFallbackTimeoutMs ?? DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS, ) this.authRecoveryAttempted = false this.controlFrameLimits = { maxControlFrameBytes: payload.maxControlFrameBytes, maxRelayFrameBytes: payload.maxRelayFrameBytes, } this.negotiatedCapabilities = acceptNegotiatedCapabilities(offeredCapabilities, payload.capabilities) if (!this.negotiatedCapabilities.some(capability => capability === 'transport.relay' || capability === 'transport.lan' || capability === 'transport.p2p' || capability === 'transport.turn')) { throw new ControlConnectionError('INVALID_MESSAGE', 'Server did not negotiate a transport capability.') } acknowledged = true clearTimeout(helloTimer) armLiveness() // Warm the RTC backend right away: loading it lazily inside the // first signal.offer handler added seconds to every first WebRTC // negotiation and blocked the control frame queue. if (this.rtcFactory === undefined && this.rtcFactoryProvider !== undefined && !this.config.forceRelay) { void this.rtcFactoryProvider().then(factory => { if (factory !== undefined) this.rtcFactory ??= factory }).catch(() => undefined) } for (const tunnel of [...this.tunnels.values()]) { const required = tunnel.transport === 'relay' ? RELAY_RESUME_CAPABILITY : WEBRTC_RESUME_CAPABILITY if (tunnel.lease && !this.negotiatedCapabilities.includes(required)) await this.dropTunnel(tunnel.connectionId) } this.online = true this.terminalError = undefined this.logger.info('server control connection online', { serverVersion: payload.serverVersion, connectionSessionId: shortId(payload.connectionSessionId), }) for (const tunnel of this.tunnels.values()) tunnel.lease?.tick(true) return } // WHY: Connection-level `error` frames legitimately arrive before // `hello.ack` when the Server rejects `hello` (e.g. expired accessToken, // revoked device, unsupported version, or handshake rate limit). if (!acknowledged && (frame.type !== 'error' || requireControlError(frame.payload).connectionId !== undefined)) { throw new ControlConnectionError('INVALID_MESSAGE', 'Server sent a frame before hello.ack.') } await this.handleFrame(frame) if (!acknowledged && !closing) closeSocket(4001, socketError ?? 'hello rejected') }).catch(error => { if (settled || this.socket !== socket) return invalidControl = true const code = errorCode(error) this.terminalError = code this.logger.error('server control frame failed', { code, reason: diagnosticReason(error), }) closeSocket(4008, 'invalid control frame') }) } socket.onerror = () => { if (!acknowledged) finish(new ControlConnectionError('CONNECTION_FAILED', 'Unable to open the Server WebSocket.')) } socket.onclose = event => { handleClose(event) } }) } private async handleFrame(frame: ReturnType): Promise { if (frame.type === 'ping') { const nonce = objectValue(frame.payload, 'nonce') if (typeof nonce !== 'string') throw new ControlConnectionError('INVALID_MESSAGE', 'Control ping has no nonce.') this.sendControl('pong', { nonce }) return } if (frame.type === 'connection.lease.ack') { const ack = frame.payload as ConnectionLeaseAck this.tunnels.get(ack.connectionId)?.lease?.acknowledge(ack) return } if (frame.type === 'pong') return if (frame.type === 'connect.incoming') { await this.handleConnectIncoming(requireConnectIncoming(frame.payload)) return } if (frame.type === 'secure.handshake') { await this.handleHandshake(requireHandshake(frame.payload)) return } if (frame.type === 'relay') { const payload = requireRelay(frame.payload) if (this.tunnels.get(payload.connectionId)?.dataSocket !== undefined) return await this.handleRelay(payload) return } if (frame.type === 'signal.offer') { if (!this.canUseWebRtc()) { throw new ControlConnectionError('INVALID_MESSAGE', 'Server forwarded WebRTC signaling without negotiating it.') } // RTC backend loading and the TURN credential fetch must not block the // serial control frame queue: ICE candidates and the secure handshake // keep flowing while the offer is still being prepared. void this.handleSignalOffer(requireSignal(frame.payload)).catch(error => { if (this.stopped) return this.logger.warn('webrtc offer handling failed', { reason: diagnosticReason(asError(error)) }) }) return } if (frame.type === 'signal.ice') { this.handleSignalIce(requireSignalIce(frame.payload)) return } if (frame.type === 'transport.selected') { await this.handleTransportSelected(requireTransportSelected(frame.payload)) return } if (frame.type === 'signal.answer') return if (frame.type === 'error') { const payload = requireControlError(frame.payload) if (payload.code === 'DEVICE_REVOKED') { this.terminalError = payload.code if (this.forceCloseSocket) this.forceCloseSocket(4004, 'device revoked') else this.socket?.close(4004, 'device revoked') } else if (payload.connectionId !== undefined) { await this.dropTunnel(payload.connectionId, payload.code, { closedBy: 'server', retryable: payload.retryable, }) const fields = { code: payload.code, connectionId: shortId(payload.connectionId), retryable: payload.retryable, } // Retryable closes also cover ordinary Client disconnects, so they stay // at info. Debug hid the Server-side origin that shares the // CONNECTION_FAILED fallback code with local channel failures. if (payload.retryable) this.logger.info('server closed a remote connection', fields) else this.logger.warn('server closed a remote connection', fields) } else if (payload.code === 'AUTH_INVALID' || payload.code === 'TOKEN_EXPIRED') { this.logger.warn('server returned a control error', { code: payload.code, retryable: payload.retryable }) if (this.forceCloseSocket) this.forceCloseSocket(4002, payload.code) else this.socket?.close(4002, payload.code) } else if (payload.code === 'UNSUPPORTED_VERSION') { this.terminalError = payload.code this.logger.warn('server returned a control error', { code: payload.code, retryable: payload.retryable }) if (this.forceCloseSocket) this.forceCloseSocket(4011, 'unsupported version') else this.socket?.close(4011, 'unsupported version') } else if (payload.code === 'CONNECTION_REPLACED') { this.terminalError = payload.code this.logger.warn('server returned a control error', { code: payload.code, retryable: payload.retryable }) if (this.forceCloseSocket) this.forceCloseSocket(4003, 'connection replaced') else this.socket?.close(4003, 'connection replaced') } else { this.terminalError = payload.code this.logger.warn('server returned a control error', { code: payload.code, retryable: payload.retryable }) } return } throw new ControlConnectionError('INVALID_MESSAGE', `Unexpected Server control frame: ${frame.type}`) } private async handleConnectIncoming(payload: ConnectIncomingPayload): Promise { const sourceSocket = this.socket let descriptor: AuthorizedPeerDevice try { descriptor = await this.api.deviceFor(payload.clientDeviceId) } catch (error) { if (this.socket !== sourceSocket) return this.sendControl('connect.rejected', { connectionId: payload.connectionId }) this.logger.warn('connection rejected by account authorization', { clientDeviceId: shortId(payload.clientDeviceId), code: errorCode(error), }) return } if (this.socket !== sourceSocket) return if (descriptor.role !== 'client' || descriptor.deviceId !== payload.clientDeviceId || descriptor.identityKey !== payload.clientIdentityKey) { this.sendControl('connect.rejected', { connectionId: payload.connectionId }) this.logger.warn('connection rejected by peer identity validation', { clientDeviceId: shortId(payload.clientDeviceId), }) return } const existing = this.identities.trustedPeer(descriptor.deviceId) const stalePin = existing !== undefined && existing.publicKey !== descriptor.identityKey // A stale pin means the peer re-authorized with the account and obtained a new // identity key. descriptor.identityKey has already been validated against the // account directory above, so rotating the pin for the same membership is safe // when the operator opts in via config.rotatePinnedPeerKey. const rotateStalePin = stalePin && this.config.rotatePinnedPeerKey && existing.membershipId === descriptor.membershipId if (stalePin && !rotateStalePin) { this.sendControl('connect.rejected', { connectionId: payload.connectionId }) this.logger.warn('connection rejected by pinned peer identity', { clientDeviceId: shortId(payload.clientDeviceId), }) return } if (rotateStalePin) { this.logger.warn('rotating pinned peer identity for same-membership device', { clientDeviceId: shortId(payload.clientDeviceId), }) } const peer = existing !== undefined && !stalePin && existing.membershipId === descriptor.membershipId && existing.name === descriptor.name && existing.platform === descriptor.platform ? existing : await this.identities.trustPeer({ deviceId: descriptor.deviceId, name: descriptor.name, platform: descriptor.platform, publicKey: descriptor.identityKey, membershipId: descriptor.membershipId, }) if (this.socket !== sourceSocket) return const previous = this.tunnels.get(payload.connectionId) previous?.noise.destroy() const noise = new NoiseIkSession({ role: 'responder', localPrivateKey: this.identity.privateKey, localPublicKey: this.identity.publicKey, remotePublicKey: peer.publicKey, prologue: createNoisePrologue(payload.connectionId, this.identity.deviceId, peer.deviceId), }) const tunnel: PendingTunnel = { recoveryTicket: this.negotiatedCapabilities.includes(WEBRTC_RESUME_CAPABILITY) ? payload.recoveryTicket : undefined, relayRecoveryTicket: this.negotiatedCapabilities.includes(RELAY_RESUME_CAPABILITY) ? payload.relayRecoveryTicket : undefined, connectionId: payload.connectionId, membershipId: descriptor.membershipId, peer, preferredTransports: payload.preferredTransports, noise, transport: 'negotiating', ...(typeof payload.relayEndpoint === 'string' && typeof payload.relayTicket === 'string' ? { relayAssignment: payload as RelayAssignment } : {}), } this.tunnels.set(payload.connectionId, tunnel) this.sendControl('connect.accepted', { connectionId: payload.connectionId }) } private async handleHandshake(payload: SecureHandshakePayload): Promise { const tunnel = this.tunnels.get(payload.connectionId) if (tunnel !== undefined && tunnel.channel !== undefined && payload.targetDeviceId === this.identity.deviceId && payload.step === 1) { // A queued Relay/WebRTC fallback can deliver the initiator's first // handshake again after the authenticated channel is already ready. // It belongs to this exact tunnel, so ignore it without taking the // Host's shared control connection offline. this.logger.warn('duplicate secure handshake ignored', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), }) return } if (tunnel === undefined || payload.targetDeviceId !== this.identity.deviceId || payload.step !== 1) { throw new ControlConnectionError('SECURE_CHANNEL_FAILED', 'Noise IK handshake is not valid for this connection.') } if (tunnel.transport === 'negotiating' && (tunnel.rtc !== undefined || tunnel.relayAssignment !== undefined)) { // transport.selected and secure.handshake traverse the Server control // plane separately. Do not guess Relay if forwarding or the responder's // RTC-ready callback delivers the handshake first; resume as soon as // either side confirms the selected data plane. if (tunnel.pendingHandshake === undefined) tunnel.pendingHandshake = payload else this.logger.warn('duplicate pending secure handshake ignored', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), }) return } await this.completeHandshake(tunnel, payload) } private async completeHandshake(tunnel: PendingTunnel, payload: SecureHandshakePayload): Promise { tunnel.noise.readHandshake(fromBase64Url(payload.data)) const reply = tunnel.noise.writeHandshake() if (!tunnel.noise.complete) throw new ControlConnectionError('SECURE_CHANNEL_FAILED', 'Noise IK handshake did not complete.') const viaWebRtc = tunnel.rtc !== undefined && (tunnel.transport === 'lan' || tunnel.transport === 'p2p' || tunnel.transport === 'turn') if (!viaWebRtc && tunnel.transport === 'negotiating') tunnel.transport = 'relay' const mode = viaWebRtc ? tunnel.transportMode ?? (tunnel.transport === 'turn' ? 'TURN' : tunnel.transport === 'lan' ? 'LAN' : 'P2P') : 'Relay' const transmit = viaWebRtc ? (ciphertext: Uint8Array) => tunnel.rtc!.send(ciphertext) : (ciphertext: Uint8Array) => this.sendRelay(tunnel, ciphertext) const channel = new ServerNoiseChannel(tunnel, transmit, async () => { // The connection controller may close the channel directly. If it still // owns this tunnel, clean up its transport without re-entering the // controller's closeConnection path. if (this.tunnels.get(tunnel.connectionId) !== tunnel) return this.notifyTunnelClosed(tunnel) this.tunnels.delete(tunnel.connectionId) tunnel.lease?.stop() try { await tunnel.rtc?.close() } catch (error) { this.logger.warn('remote connection RTC cleanup failed', { connectionId: shortId(tunnel.connectionId), reason: diagnosticReason(error), }) } tunnel.dataSocket?.close() tunnel.dataSocket = undefined tunnel.dataReady = false }, mode) tunnel.channel = channel await this.connections.accept(channel) // Publish the responder handshake only after the channel is registered. // The Client starts its first RPC as soon as step 2 arrives; sending the // reply earlier lets WebRTC deliver that RPC while tunnel.channel is still // undefined, which silently drops the request. this.sendControl('secure.handshake', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, step: 2, data: toBase64Url(reply), } satisfies SecureHandshakePayload) const leaseTicket = viaWebRtc ? tunnel.recoveryTicket : tunnel.transport === 'relay' && tunnel.dataReady && tunnel.dataSocket?.readyState === 1 ? tunnel.relayRecoveryTicket : undefined if (leaseTicket) { tunnel.lease = new ControlLease(tunnel.connectionId, leaseTicket, payload => { const heartbeatTimeoutMs = Math.max(15_000, this.heartbeatIntervalMs * 3) if (this.online && this.lastActiveAt !== undefined && Date.now() - this.lastActiveAt >= heartbeatTimeoutMs) { if (this.forceCloseSocket) this.forceCloseSocket(4009, 'heartbeat timeout') else this.socket?.close(4009, 'heartbeat timeout') throw new Error('Control heartbeat timed out') } this.sendControl('connection.lease.request', payload) }, () => { void this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') }) tunnel.lease.start() } this.logger.info('authenticated peer channel ready', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), transport: mode, }) } private async resumePendingHandshake(tunnel: PendingTunnel): Promise { const payload = tunnel.pendingHandshake if (payload === undefined || tunnel.channel !== undefined || tunnel.transport === 'negotiating') return tunnel.pendingHandshake = undefined await this.completeHandshake(tunnel, payload) } private async handleRelay(payload: RelayPayload): Promise { if (!this.negotiatedCapabilities.includes('transport.relay')) { throw new ControlConnectionError('INVALID_MESSAGE', 'Server forwarded Relay without negotiating it.') } if (payload.targetDeviceId !== this.identity.deviceId) { throw new ControlConnectionError('INVALID_MESSAGE', 'Relay frame target does not match this Host.') } const tunnel = this.tunnels.get(payload.connectionId) if (tunnel?.channel === undefined) { this.logger.warn('stale relay frame ignored', { connectionId: shortId(payload.connectionId), }) return } try { tunnel.channel.receive(payload.counter, fromBase64Url(payload.ciphertext)) } catch (error) { await tunnel.channel.close() throw new ControlConnectionError('SECURE_CHANNEL_FAILED', asError(error).message) } } private async handleSignalOffer(payload: SignalPayload): Promise { const tunnel = this.tunnels.get(payload.connectionId) if (tunnel === undefined || payload.targetDeviceId !== this.identity.deviceId) { this.logger.warn('stale webrtc offer ignored', { connectionId: shortId(payload.connectionId) }) return } if (tunnel.channel !== undefined || tunnel.rtc !== undefined) { // Late or duplicate offer after relay establishment / RTC start: ignore. this.logger.warn('duplicate webrtc offer ignored', { connectionId: shortId(tunnel.connectionId) }) return } if (this.config.forceRelay || isForceRelayEnabled()) { // Device-level forced degradation (webrtc plan §11). this.logger.warn('webrtc offer ignored: forceRelay is enabled', { connectionId: shortId(tunnel.connectionId) }) return } if (this.rtcFactory === undefined && this.rtcFactoryProvider !== undefined) { this.rtcFactory = await this.rtcFactoryProvider().catch(() => undefined) } if (this.rtcFactory === undefined) { // No Node RTC backend on this Host (webrtc plan §6.2): drop the offer so // the initiator times out and falls back to the Relay data plane. this.logger.warn('webrtc offer ignored: no RTC backend available', { connectionId: shortId(tunnel.connectionId) }) return } let iceServers: RtcIceServer[] = [] try { iceServers = await this.api.turnCredentials(tunnel.connectionId) } catch (error) { this.logger.warn('TURN credentials unavailable; trying direct candidates', { connectionId: shortId(tunnel.connectionId), code: errorCode(error), }) } // Authorization/credentials can finish after this connection was dropped // or after the initiator gave up and selected the relay data plane. if (this.stopped || this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc !== undefined || tunnel.channel !== undefined || tunnel.transport !== 'negotiating') return if (!tunnel.preferredTransports.includes('turn')) iceServers = stunOnlyIceServers(iceServers) const rtc = new RtcDataChannelTransport({ role: 'responder', factory: this.rtcFactory, iceServers, onSignal: signal => this.sendRtcSignal(tunnel, signal), negotiateTimeoutMs: this.webRtcNegotiateTimeoutMs, label: `host<-${tunnel.peer.deviceId}`, onDiagnostic: event => { if (event.type !== 'local-candidate-filtered' && event.type !== 'candidate-pair-filtered') return this.logger.debug('webrtc candidate filtered', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), type: event.type, reason: event.reason, candidate: event.type === 'local-candidate-filtered' ? event.candidate : event.localCandidate, }) }, }) tunnel.rtc = rtc rtc.onMessage(data => tunnel.channel?.receive(undefined, data)) rtc.onClose(() => { void this.handleRtcFailed(tunnel, rtc, new Error('WebRTC data channel closed.')) }) void rtc.connect().then(() => { this.handleRtcOpened(tunnel, rtc.selectedTransport() ?? 'p2p') }).catch(error => { void this.handleRtcFailed(tunnel, rtc, asError(error)) }) rtc.handleSignal({ type: 'offer', sdp: payload.sdp }) // Candidates that arrived while the RTC backend / TURN credentials were // still loading. The data-channel transport buffers them itself until the // remote description is set, so replay order is safe. const buffered = tunnel.pendingIce if (buffered !== undefined) { tunnel.pendingIce = undefined for (const candidate of buffered) rtc.handleSignal({ type: 'ice', candidate }) } } private handleSignalIce(payload: SignalIcePayload): void { if (!this.canUseWebRtc()) { throw new ControlConnectionError('INVALID_MESSAGE', 'Server forwarded WebRTC signaling without negotiating it.') } const tunnel = this.tunnels.get(payload.connectionId) if (tunnel === undefined || payload.targetDeviceId !== this.identity.deviceId) return const rtc = tunnel.rtc if (rtc !== undefined) { rtc.handleSignal({ type: 'ice', candidate: payload.candidate }) return } // The offer handler is still loading the RTC backend or TURN credentials. // Buffer the candidate instead of dropping it: lost trickle ICE was a // major source of slow or failed hole punching. if (tunnel.channel === undefined) (tunnel.pendingIce ??= []).push(payload.candidate) } private async handleTransportSelected(payload: TransportSelectedPayload): Promise { const tunnel = this.tunnels.get(payload.connectionId) if (tunnel === undefined || payload.targetDeviceId !== this.identity.deviceId) { this.logger.warn('stale transport selection ignored', { connectionId: shortId(payload.connectionId) }) return } if (tunnel.channel !== undefined) { // Selection is immutable once Noise has bound the business channel to a // data plane. Late duplicate control frames must not switch it beneath // an authenticated connection. if (tunnel.transport !== payload.transport) { this.logger.warn('late transport selection ignored', { connectionId: shortId(tunnel.connectionId), selected: payload.transport, }) } return } const requiredCapability = `transport.${payload.transport}` if (!this.negotiatedCapabilities.includes(requiredCapability)) { throw new ControlConnectionError( 'INVALID_MESSAGE', `Client selected unnegotiated transport: ${payload.transport}`, ) } if (payload.transport === 'relay') { const rtc = tunnel.rtc tunnel.rtc = undefined tunnel.transport = 'relay' tunnel.transportMode = undefined await rtc?.close() if (tunnel.relayAssignment !== undefined) { try { await this.openDataSocket(tunnel) } catch (error) { this.logger.warn('relay data attach failed', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), reason: diagnosticReason(error), }) await this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') this.sendControl('error', { code: 'CONNECTION_FAILED', message: 'Relay data connection failed.', retryable: true, connectionId: tunnel.connectionId, }) return } } await this.resumePendingHandshake(tunnel) return } if (tunnel.rtc === undefined) { throw new ControlConnectionError('INVALID_MESSAGE', 'Client selected WebRTC before creating a data channel.') } // The initiator emits transport.selected only after its DataChannel is // open, then immediately starts Noise. Apply that ordered control frame // before the handshake so a slower responder-side RTC ready callback // cannot bind replies to Relay while requests arrive over WebRTC. tunnel.transport = payload.transport tunnel.transportMode = tunnel.rtc.selectedPathMode() if (payload.turnNode !== undefined) { this.logger.info('client selected a turn relay', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), // Hostnames only: never echo arbitrary client-supplied text into logs. turnNode: TURN_NODE_TEXT.test(payload.turnNode) ? payload.turnNode : '', }) } await this.resumePendingHandshake(tunnel) } private canUseWebRtc(): boolean { return this.negotiatedCapabilities.includes('transport.lan') || this.negotiatedCapabilities.includes('transport.p2p') || this.negotiatedCapabilities.includes('transport.turn') } private sendRtcSignal(tunnel: PendingTunnel, signal: RtcSignal): void { if (signal.type === 'answer') { this.sendControl('signal.answer', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, sdp: signal.sdp, } satisfies SignalPayload) } else if (signal.type === 'ice') { this.sendControl('signal.ice', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, candidate: signal.candidate, } satisfies SignalIcePayload) } } private handleRtcOpened(tunnel: PendingTunnel, selected: RtcSelectedTransport): void { if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc === undefined) return const wireSelected = selected === 'lan' && !this.negotiatedCapabilities.includes('transport.lan') && this.negotiatedCapabilities.includes('transport.p2p') ? 'p2p' : selected const requiredCapability = wireSelected === 'lan' ? 'transport.lan' : wireSelected === 'turn' ? 'transport.turn' : 'transport.p2p' if (!this.negotiatedCapabilities.includes(requiredCapability)) { const error = new Error(`WebRTC selected unnegotiated transport: ${selected}`) if (!this.negotiatedCapabilities.includes('transport.relay')) { void this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') return } void this.handleRtcFailed( tunnel, tunnel.rtc, error, ) return } tunnel.transport = wireSelected tunnel.transportMode = tunnel.rtc.selectedPathMode() this.sendTransportSelected(tunnel, wireSelected) const diagnostics = rtcDiagnostics(tunnel.rtc) this.logger.info('webrtc data channel ready', { connectionId: shortId(tunnel.connectionId), peerDeviceId: shortId(tunnel.peer.deviceId), transport: tunnel.transportMode ?? wireSelected, }) if (diagnostics !== undefined) { this.logger.debug('webrtc data channel diagnostics', { connectionId: shortId(tunnel.connectionId), ...webrtcDiagnosticsLogFields(diagnostics), }) } void this.resumePendingHandshake(tunnel).catch(error => { this.logger.warn('pending secure handshake failed', { connectionId: shortId(tunnel.connectionId), reason: diagnosticReason(error), }) void this.dropTunnel(tunnel.connectionId, 'SECURE_CHANNEL_FAILED') }) } private async handleRtcFailed( tunnel: PendingTunnel, rtc: RtcDataChannelTransport, error: Error, ): Promise { if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc !== rtc) return const diagnostics = rtcDiagnostics(rtc) if (tunnel.transport === 'lan' || tunnel.transport === 'p2p' || tunnel.transport === 'turn') { this.logger.warn('webrtc data channel failed; disconnecting peer', { connectionId: shortId(tunnel.connectionId), reason: diagnosticReason(error), }) if (diagnostics !== undefined) { this.logger.debug('webrtc data channel failure diagnostics', { connectionId: shortId(tunnel.connectionId), ...webrtcDiagnosticsLogFields(diagnostics), }) } await this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') return } tunnel.rtc = undefined tunnel.transport = 'relay' await rtc.close() this.logger.warn('webrtc negotiation failed; falling back to relay', { connectionId: shortId(tunnel.connectionId), reason: diagnosticReason(error), }) if (diagnostics !== undefined) { this.logger.debug('webrtc negotiation failure diagnostics', { connectionId: shortId(tunnel.connectionId), ...webrtcDiagnosticsLogFields(diagnostics), }) } await this.resumePendingHandshake(tunnel) } private sendTransportSelected(tunnel: PendingTunnel, transport: SelectedTransport): void { this.sendControl('transport.selected', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, transport, } satisfies TransportSelectedPayload) } private async sendRelay(tunnel: PendingTunnel, ciphertext: Uint8Array): Promise { if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.channel === undefined) { throw new Error('Relay tunnel closed') } const counter = Number(tunnel.noise.sendingCounter() - 1n) if (!Number.isSafeInteger(counter) || counter < 0) throw new ControlConnectionError('FRAME_TOO_LARGE', 'Noise transport counter overflowed.') const socket = tunnel.dataSocket ?? this.socket if (socket === undefined) throw new Error('Relay transport closed') await waitForRelayCapacity(socket) if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.channel === undefined) { throw new Error('Relay tunnel closed') } if (tunnel.dataSocket !== undefined) { if (tunnel.dataSocket !== socket || tunnel.dataSocket.readyState !== 1 || !tunnel.dataReady) { throw new Error('Relay data transport is not ready') } socket.send(encodeRelayDataFrame(createRelayDataFrame('relay', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, counter, ciphertext: toBase64Url(ciphertext), }), this.controlFrameLimits)) return } if (this.socket !== socket) throw new Error('Relay transport replaced') this.sendControl('relay', { connectionId: tunnel.connectionId, targetDeviceId: tunnel.peer.deviceId, counter, ciphertext: toBase64Url(ciphertext), } satisfies RelayPayload) } private async openDataSocket(tunnel: PendingTunnel): Promise { const assignment = tunnel.relayAssignment if (assignment === undefined || tunnel.dataSocket !== undefined) return if (typeof assignment.relayEndpoint !== 'string' || typeof assignment.relayTicket !== 'string') return const socket = this.createWebSocket(assignment.relayEndpoint) socket.binaryType = 'arraybuffer' tunnel.dataSocket = socket await new Promise((resolve, reject) => { let settled = false const timer = setTimeout(() => finish(new Error('Relay data attach timed out')), 15_000) const finish = (error?: Error): void => { if (settled) return settled = true clearTimeout(timer) if (error === undefined) resolve() else reject(error) } socket.onopen = () => { try { socket.send(encodeRelayDataFrame(createRelayDataFrame('relay.attach', { connectionId: tunnel.connectionId, deviceId: this.identity.deviceId, peerDeviceId: tunnel.peer.deviceId, ticket: assignment.relayTicket, }), this.controlFrameLimits)) } catch (error) { finish(asError(error)) } } socket.onmessage = event => { try { if (typeof event.data !== 'string') throw new ControlConnectionError('INVALID_MESSAGE', 'Relay data frames must be text JSON.') const frame = decodeRelayDataFrame(event.data, this.controlFrameLimits) if (frame.type === 'relay.ready') { if (frame.payload.connectionId !== tunnel.connectionId || (assignment.relayEpoch !== undefined && frame.payload.epoch !== assignment.relayEpoch)) { throw new ControlConnectionError('INVALID_MESSAGE', 'Relay data attach does not match the assigned connection.') } tunnel.dataReady = true finish() return } void this.handleDataSocketFrame(tunnel, frame.type, frame.payload).catch(error => { finish(asError(error)) void this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') }) } catch (error) { finish(asError(error)) void this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') } } socket.onerror = () => finish(new Error('Relay data socket failed')) socket.onclose = () => { if (!tunnel.dataReady) finish(new Error('Relay data socket closed before attach')) else void this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') } }) } private async handleDataSocketFrame( tunnel: PendingTunnel, type: string, payload: Record, ): Promise { if (this.tunnels.get(tunnel.connectionId) !== tunnel) return if (type === 'relay.detach') { await this.dropTunnel(tunnel.connectionId, 'CONNECTION_FAILED') return } if (type === 'ping') { if (tunnel.dataSocket?.readyState === 1) { tunnel.dataSocket.send(encodeRelayDataFrame(createRelayDataFrame('pong', payload), this.controlFrameLimits)) } return } if (type !== 'relay') throw new ControlConnectionError('INVALID_MESSAGE', `Unexpected Relay data frame: ${type}`) await this.handleRelay(requireRelay(payload)) } private sendControl(type: Parameters[0], payload: unknown): void { const socket = this.socket if (socket === undefined || socket.readyState !== 1) throw new ControlConnectionError('CONNECTION_FAILED', 'Server control socket is not open.') socket.send(encodeControlFrame(createControlFrame(type, payload), this.controlFrameLimits)) } private notifyTunnelClosed(tunnel: PendingTunnel): void { if (!tunnel.lease || this.socket?.readyState !== 1) return try { this.sendControl('connection.lease.close', { connectionId: tunnel.connectionId }) } catch { /* local cleanup proceeds */ } } private async dropTunnels(): Promise { const tunnels = [...this.tunnels.values()] this.tunnels.clear() await Promise.all(tunnels.map(async tunnel => { tunnel.lease?.stop() if (tunnel.rtc !== undefined) await tunnel.rtc.close() tunnel.dataSocket?.close() if (tunnel.channel !== undefined) await tunnel.channel.close() else tunnel.noise.destroy() })) await this.connections.close() } private async dropTunnel( connectionId: string, code?: string, detail?: ConnectionCloseDetail, ): Promise { const tunnel = this.tunnels.get(connectionId) if (tunnel === undefined) return this.notifyTunnelClosed(tunnel) this.tunnels.delete(connectionId) tunnel.lease?.stop() try { await tunnel.rtc?.close() } catch (error) { this.logger.warn('remote connection RTC cleanup failed', { connectionId: shortId(connectionId), reason: diagnosticReason(error), }) } tunnel.dataSocket?.close() tunnel.dataSocket = undefined tunnel.dataReady = false if (tunnel.channel !== undefined) { try { const closed = detail === undefined ? await this.connections.closeConnection(connectionId, code) : await this.connections.closeConnection(connectionId, code, detail) if (!closed) await tunnel.channel.close(code) } catch (error) { await tunnel.channel.close(code).catch(() => undefined) this.logger.warn('remote connection channel cleanup failed', { connectionId: shortId(connectionId), reason: diagnosticReason(error), }) } } else { tunnel.noise.destroy() } } private waitBeforeRetry(): Promise { // Full jitter over the configured maximum (AWS "full jitter"): every // retry draws uniformly from [0, maxDelayMs], so the fleet spreads out // even when the Server restarts. `reconnect.initialDelayMs` and // `reconnect.jitter` remain accepted configuration but no longer shape // the delay; only `maxDelayMs` bounds it. const delay = Math.round(Math.random() * this.config.reconnect.maxDelayMs) return new Promise(resolve => { const timer = setTimeout(() => { this.retryWake = undefined; resolve() }, delay) this.retryWake = () => { clearTimeout(timer); resolve() } }) } } const TERMINAL_AUTH_ERRORS = new Set([ 'CONNECTION_REPLACED', 'ACCOUNT_AUTH_REQUIRED', 'AUTH_INVALID', 'DEVICE_OWNERSHIP_REQUIRED', 'DEVICE_REVOKED', 'TOKEN_EXPIRED', ]) class ServerNoiseChannel implements AuthenticatedPeerChannel { private readonly sends = new SerialSend() readonly security readonly peerDeviceId: string readonly peerIdentityKey: string readonly mode: 'LAN' | 'P2P' | 'TURN' | 'Relay' private readonly handlers = new Set<(message: RemoteMessage) => void>() private readonly incoming = new SecureMessageCodec() private readonly outgoing = new SecureMessageCodec() private closed = false /** Noise + SecureMessageCodec counters are not re-entrant; serialize sends. */ private sendTail: Promise = Promise.resolve() constructor( private readonly tunnel: PendingTunnel, private readonly transmit: (ciphertext: Uint8Array) => Promise, private readonly onClose: () => Promise, mode: 'LAN' | 'P2P' | 'TURN' | 'Relay', ) { this.mode = mode this.security = { protocol: 'Noise_IK_25519_ChaChaPoly_SHA256' as const, connectionId: tunnel.connectionId, membershipId: tunnel.membershipId, } this.peerDeviceId = tunnel.peer.deviceId this.peerIdentityKey = tunnel.peer.publicKey } async send(message: RemoteMessage): Promise { const run = this.sendTail.then(() => this.sendNow(message)) this.sendTail = run.catch(() => undefined) return run } private async sendNow(message: RemoteMessage): Promise { if (this.tunnel.lease && !this.tunnel.lease.valid()) throw new Error('Control lease expired') if (this.closed) throw new Error('secure channel is closed') const encoded = encodeMessage(message) try { await this.sends.run(encoded.byteLength, async () => { if (this.closed) throw new Error('Secure channel closed') for (const plaintext of this.outgoing.encode(encoded)) { if (this.closed) throw new Error('Secure channel closed') await this.transmit(this.tunnel.noise.encrypt(plaintext)) } }) } catch (error) { await this.close().catch(() => undefined) throw error } } onMessage(handler: (message: RemoteMessage) => void): () => void { this.handlers.add(handler) return () => this.handlers.delete(handler) } receive(counter: number | undefined, ciphertext: Uint8Array): void { if (this.tunnel.lease && !this.tunnel.lease.valid()) return if (this.closed) return if (counter !== undefined) { const expected = Number(this.tunnel.noise.receivingCounter()) if (!Number.isSafeInteger(counter) || counter !== expected) { throw new ControlConnectionError('INVALID_MESSAGE', 'Relay counter is duplicated or out of order.') } } const plaintext = this.incoming.decode(this.tunnel.noise.decrypt(ciphertext)) if (plaintext === undefined) return const message = decodeMessage(plaintext) for (const handler of this.handlers) handler(message) } async close(_code?: string): Promise { if (this.closed) return this.closed = true this.handlers.clear() this.incoming.reset() this.outgoing.reset() this.tunnel.noise.destroy() await this.onClose() } } class ControlConnectionError extends Error { constructor(readonly code: string, message: string) { super(message) } } function websocketUrl(baseUrl: string): string { const url = new URL(baseUrl) url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:' url.pathname = `${url.pathname.replace(/\/$/, '')}/ws/v1/connect` return url.toString() } function decodeControl(data: unknown, limits: ControlFrameByteLimits): ReturnType { if (typeof data !== 'string') throw new ControlConnectionError('INVALID_MESSAGE', 'Server control frames must be text JSON.') try { return decodeControlFrame(data, limits) } catch { throw new ControlConnectionError('INVALID_MESSAGE', 'Server sent an invalid control frame.') } } function requireHelloAck(value: unknown): HelloAckPayload { const payload = requireObject(value) if (payload.protocol !== PROTOCOL_VERSION || typeof payload.serverVersion !== 'string' || typeof payload.connectionSessionId !== 'string' || !Number.isSafeInteger(payload.heartbeatIntervalMs) || (payload.heartbeatIntervalMs as number) <= 0 || !Number.isSafeInteger(payload.maxControlFrameBytes) || !Number.isSafeInteger(payload.maxRelayFrameBytes)) { throw new ControlConnectionError('INVALID_MESSAGE', 'hello.ack payload is invalid.') } return payload as unknown as HelloAckPayload } function requireConnectIncoming(value: unknown): ConnectIncomingPayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.clientDeviceId !== 'string' || typeof payload.clientIdentityKey !== 'string' || payload.authorization !== 'account' || !Array.isArray(payload.preferredTransports)) { throw new ControlConnectionError('INVALID_MESSAGE', 'connect.incoming payload is invalid.') } return payload as unknown as ConnectIncomingPayload } function requireHandshake(value: unknown): SecureHandshakePayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.targetDeviceId !== 'string' || !Number.isSafeInteger(payload.step) || typeof payload.data !== 'string') { throw new ControlConnectionError('INVALID_MESSAGE', 'secure.handshake payload is invalid.') } return payload as unknown as SecureHandshakePayload } function requireRelay(value: unknown): RelayPayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.targetDeviceId !== 'string' || !Number.isSafeInteger(payload.counter) || typeof payload.ciphertext !== 'string') { throw new ControlConnectionError('INVALID_MESSAGE', 'relay payload is invalid.') } return payload as unknown as RelayPayload } function requireSignal(value: unknown): SignalPayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.targetDeviceId !== 'string' || typeof payload.sdp !== 'string' || payload.sdp.length === 0) { throw new ControlConnectionError('INVALID_MESSAGE', 'signal offer/answer payload is invalid.') } return payload as unknown as SignalPayload } function requireSignalIce(value: unknown): SignalIcePayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.targetDeviceId !== 'string' || typeof payload.candidate !== 'object' || payload.candidate === null || Array.isArray(payload.candidate)) { throw new ControlConnectionError('INVALID_MESSAGE', 'signal.ice payload is invalid.') } return payload as unknown as SignalIcePayload } function requireTransportSelected(value: unknown): TransportSelectedPayload { const payload = requireObject(value) if (typeof payload.connectionId !== 'string' || typeof payload.targetDeviceId !== 'string' || (payload.transport !== 'lan' && payload.transport !== 'p2p' && payload.transport !== 'turn' && payload.transport !== 'relay')) { throw new ControlConnectionError('INVALID_MESSAGE', 'transport.selected payload is invalid.') } return payload as unknown as TransportSelectedPayload } function requireControlError(value: unknown): ControlErrorPayload { const payload = requireObject(value) if (typeof payload.code !== 'string' || typeof payload.message !== 'string' || (payload.connectionId !== undefined && (typeof payload.connectionId !== 'string' || payload.connectionId === ''))) { throw new ControlConnectionError('INVALID_MESSAGE', 'error payload is invalid.') } return payload as unknown as ControlErrorPayload } function requireObject(value: unknown): Record { if (typeof value !== 'object' || value === null || Array.isArray(value)) { throw new ControlConnectionError('INVALID_MESSAGE', 'Control payload must be an object.') } return value as Record } function objectValue(value: unknown, key: string): unknown { return requireObject(value)[key] } function shortId(value: string): string { return value.length <= 12 ? value : `${value.slice(0, 8)}…${value.slice(-4)}` } /** Client-reported TURN relay hostnames (IPv4/IPv6[:port]) may enter logs. */ const TURN_NODE_TEXT = /^[A-Za-z0-9.[\]:-]+$/ function asError(error: unknown): Error { return error instanceof Error ? error : new Error('Unknown Server connection error.') } function diagnosticReason(error: unknown): string { const message = asError(error).message.replace(/[\r\n]+/g, ' ').slice(0, 160) return message || 'Unknown Server connection error.' } function webrtcDiagnosticsLogFields(diagnostics: RtcConnectionDiagnostics | undefined): Record { if (diagnostics === undefined) return {} return { rtcConnectionState: diagnostics.connectionState, rtcIceConnectionState: diagnostics.iceConnectionState, rtcIceGatheringState: diagnostics.iceGatheringState, rtcLocalCandidates: diagnostics.localCandidates, rtcRemoteCandidates: diagnostics.remoteCandidates, rtcCandidatePairs: diagnostics.candidatePairs, rtcFilteredLocalCandidates: diagnostics.filteredLocalCandidates, rtcFilteredCandidatePairs: diagnostics.filteredCandidatePairs, ...(diagnostics.selectedPath === undefined ? {} : { rtcSelectedPath: diagnostics.selectedPath }), } } function rtcDiagnostics(rtc: RtcDataChannelTransport): RtcConnectionDiagnostics | undefined { try { const candidate = rtc as RtcDataChannelTransport & { diagnostics?: () => RtcConnectionDiagnostics } return typeof candidate.diagnostics === 'function' ? candidate.diagnostics() : undefined } catch { return undefined } } function errorCode(error: unknown): string { return error instanceof ServerApiError || error instanceof ControlConnectionError ? error.code : 'CONNECTION_FAILED' } function isRetryable(error: unknown): boolean { return errorCode(error) !== 'UNSUPPORTED_VERSION' && !TERMINAL_AUTH_ERRORS.has(errorCode(error)) && (!(error instanceof ServerApiError) || error.retryable) } function closeCode(code: number): string { if (code === 4002) return 'AUTH_INVALID' if (code === 4003) return 'CONNECTION_REPLACED' if (code === 4004) return 'DEVICE_REVOKED' if (code === 4007) return 'RATE_LIMITED' if (code === 4011) return 'UNSUPPORTED_VERSION' return 'CONNECTION_FAILED' }