1592 lines
69 KiB
TypeScript
1592 lines
69 KiB
TypeScript
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<ConnectIncomingPayload, 'relayEndpoint' | 'relayTicket' | 'relayNodeId' | 'relayEpoch'>
|
|
|
|
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<void>
|
|
private stopped = true
|
|
private online = false
|
|
private retryWake?: () => void
|
|
private readonly tunnels = new Map<string, PendingTunnel>()
|
|
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<RtcPeerConnectionFactory | undefined>,
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void>((resolve, reject) => {
|
|
let settled = false
|
|
let closing = false
|
|
let upgradeTimer: ReturnType<typeof setTimeout> | undefined
|
|
let helloTimer: ReturnType<typeof setTimeout> | undefined
|
|
let refreshTimer: ReturnType<typeof setTimeout> | undefined
|
|
let livenessTimer: ReturnType<typeof setTimeout> | 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<void> => {
|
|
if (!forced) {
|
|
let drainTimer: ReturnType<typeof setTimeout> | undefined
|
|
await Promise.race([
|
|
messageQueue.catch(() => undefined),
|
|
new Promise<void>(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<never>((_, 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<typeof decodeControlFrame>): Promise<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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 : '<invalid>',
|
|
})
|
|
}
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void>((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<string, unknown>,
|
|
): Promise<void> {
|
|
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<typeof createControlFrame>[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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
// 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<void> = Promise.resolve()
|
|
|
|
constructor(
|
|
private readonly tunnel: PendingTunnel,
|
|
private readonly transmit: (ciphertext: Uint8Array) => Promise<void>,
|
|
private readonly onClose: () => Promise<void>,
|
|
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<void> {
|
|
const run = this.sendTail.then(() => this.sendNow(message))
|
|
this.sendTail = run.catch(() => undefined)
|
|
return run
|
|
}
|
|
|
|
private async sendNow(message: RemoteMessage): Promise<void> {
|
|
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<void> {
|
|
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<typeof decodeControlFrame> {
|
|
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<string, unknown> {
|
|
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
throw new ControlConnectionError('INVALID_MESSAGE', 'Control payload must be an object.')
|
|
}
|
|
return value as Record<string, unknown>
|
|
}
|
|
|
|
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<string, unknown> {
|
|
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'
|
|
}
|