import type { PairingCredentials } from './pairing-contract.js' import { platform } from 'node:os' import { fromBase64Url, toBase64Url } from '@dsh-remote/crypto' import { deviceTokenPairSchema, type DeviceTokenPair as TokenPair } from '@dsh-remote/protocol' import type { RtcIceServer } from '@dsh-remote/webrtc' import type { HostIdentity } from './identity-store.js' import { ServerCredentialsBusyError, ServerCredentialsLockUnsupportedError, type ServerCredentialStore, type ServerCredentials } from './server-credentials.js' import { normalizeServerUrl } from './config.js' import { PLUGIN_VERSION } from './version.js' interface ErrorEnvelope { error: { code: string; message: string; retryable: boolean } } interface WebLoginResponse { token: string expiresAt: number account: string profile: unknown isAdmin: boolean } export interface OAuthQrSession { qrId: string scanUrl: string expiresIn: number } /** Server-owned opaque provider ID; new integrations need no plugin release. */ export type OAuthProvider = string export interface OAuthProviderInfo { id: OAuthProvider displayName: string startUrl: string qrStartUrl?: string | null devicePairing?: true } export type OAuthQrPollResult = | { status: 'pending' | 'expired' } | { status: 'complete'; authorization: DeviceAuthorization } export interface DeviceAuthorization { method: 'account' | 'host_registration_code' | 'owned_device' | 'device_pairing' account?: string expiresAt?: number isAdmin?: boolean } export type FetchImplementation = typeof fetch const TERMINAL_CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u export interface ServerHostDevice { deviceId: string name: string platform: string membershipId: string online?: boolean lastSeenAt?: number clientVersion?: string harnessVersion?: string } export interface AuthorizedPeerDevice extends ServerHostDevice { role: 'host' | 'client' identityKey: string } export class HostServerApi { readonly baseUrl: string private hostOnly = false private identity?: HostIdentity private credentials?: ServerCredentials private credentialsPromise?: Promise private harnessVersion?: string private readonly lifetime = new AbortController() constructor( serverUrl: string, private readonly store: ServerCredentialStore, private readonly fetchImplementation: FetchImplementation = fetch, private readonly role: 'host' | 'client' = 'host', httpServerAllowlist: readonly string[] = [], ) { this.baseUrl = normalizeServerUrl(serverUrl, httpServerAllowlist) } bindIdentity(identity: HostIdentity): void { this.identity = identity } setHarnessVersion(version: string | undefined): void { this.harnessVersion = version } /** End this runtime's HTTP requests, including authentication and response bodies. */ close(): void { this.lifetime.abort(new ServerApiError('CONNECTION_CLOSED', 'The Server API has been closed.', false)) } pairingHostOnly(): boolean { return this.hostOnly } async loadStoredPolicy(): Promise { this.hostOnly = this.role === 'host' && (await this.store.pairingHostOnly() || (await this.store.load(this.baseUrl, this.requireIdentity().deviceId))?.pairingRestricted === true) } async adoptPairing(result: PairingCredentials): Promise { const identity = this.requireIdentity() if (this.role !== 'host' || result.device.role !== 'host' || result.device.deviceId !== identity.deviceId || result.device.identityKey !== identity.publicKey) throw new ServerApiError('PAIRING_IDENTITY_INVALID', 'Pairing identity mismatch.', false) if (result.pairingRestricted) { if (!result.inboundOnly) throw new ServerApiError('DEVICE_SCOPE_REQUIRED', 'Paired Host must remain inbound only.', false) this.hostOnly = true await this.store.restrictPairingHostOnly() } this.credentials = await this.withRefreshLock(async () => { const existing = await this.store.load(this.baseUrl, identity.deviceId) if (existing?.account !== undefined && existing.account !== result.account) throw new ServerApiError('PAIRING_ACCOUNT_CONFLICT', 'Pairing cannot replace the current account.', false) if (existing !== undefined && existing.refreshTokenExpiresAt > Date.now() + 30_000) return existing return this.store.save({ serverUrl: this.baseUrl, deviceId: identity.deviceId, authorizationMethod: 'device_pairing', account: result.account, accountKind: result.accountKind, pairingRestricted: result.pairingRestricted, inboundOnly: result.inboundOnly, ...validateTokens(result.tokens) }) }) } currentAuthorization(): DeviceAuthorization | undefined { if (this.credentials === undefined) return undefined return { method: this.credentials.authorizationMethod, ...(this.credentials.account === undefined ? {} : { account: this.credentials.account }), } } /** Check the persisted device credential without issuing or refreshing one. */ async hasStoredAuthorization(): Promise { const identity = this.requireIdentity() return await this.store.load(this.baseUrl, identity.deviceId) !== undefined } async clearAuthorization(): Promise { this.credentials = undefined this.credentialsPromise = undefined await this.store.clear() } async revokeCurrentDevice(): Promise { const identity = this.requireIdentity() if (await this.store.load(this.baseUrl, identity.deviceId) === undefined) { await this.clearAuthorization() return } try { await this.request('/api/v1/devices/self', { method: 'DELETE' }) } finally { await this.clearAuthorization() } } async authorizeWithAccount( identity: HostIdentity, email: string, password: string, recoverIdentity?: () => Promise, ): Promise { this.bindIdentity(identity) const account = email.trim() if (account.length === 0 || password.length === 0) { throw new ServerApiError('INVALID_MESSAGE', 'Email and password are required.', false) } const login = validateWebLogin(await this.publicRequest('/api/v1/auth/login', { method: 'POST', body: JSON.stringify({ email: account, password }), })) const authorization = { accountToken: login.token, account: login.account, authorizationMethod: 'account' as const, } try { await this.register(identity, authorization) } catch (error) { // A Server-side device removal revokes the old identity permanently. // Account login is the explicit re-authorization boundary, so callers // may rotate the local identity and retry without requiring a separate // settings logout first. if (!(error instanceof ServerApiError) || error.code !== 'DEVICE_REVOKED' || recoverIdentity === undefined) throw error const nextIdentity = await recoverIdentity() this.bindIdentity(nextIdentity) await this.register(nextIdentity, authorization) } return { method: 'account', account: login.account, expiresAt: login.expiresAt, isAdmin: login.isAdmin, } } async oauthProviders(): Promise { let body: unknown try { body = await this.publicRequest('/api/v1/auth/oauth/providers', { method: 'GET' }) } catch (error) { if (!(error instanceof ServerApiError) || error.status !== 404) throw error // Older servers expose only individual status endpoints. Do not hide // network errors or malformed discovery responses behind this fallback. const legacy = [ { id: 'zhihu', displayName: 'Zhihu', startUrl: '/api/v1/auth/oauth/start', statusUrl: '/api/v1/auth/oauth/status' }, { id: 'github', displayName: 'GitHub', startUrl: '/api/v1/auth/oauth/github/start', statusUrl: '/api/v1/auth/oauth/github/status' }, ] const items = await Promise.all(legacy.map(async ({ statusUrl, ...provider }) => { try { const status = requireRecord(await this.publicRequest(statusUrl, { method: 'GET' }), 'OAuth status') if (typeof status.configured !== 'boolean') throw invalidOAuthProviders() return status.configured ? [{ ...provider, qrStartUrl: `/api/v1/auth/oauth/qr/start?provider=${provider.id}` }] : [] } catch (reason) { if (reason instanceof ServerApiError && reason.status === 404) return [] throw reason } })) return items.flat() } const value = requireRecord(body, 'OAuth providers') if (!Array.isArray(value.items)) throw invalidOAuthProviders() const ids = new Set() const providers: OAuthProviderInfo[] = value.items.map(item => { const provider = requireRecord(item, 'OAuth provider') if (typeof provider.id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(provider.id) || ids.has(provider.id) || typeof provider.displayName !== 'string' || !provider.displayName.trim() || provider.displayName.length > 128 || TERMINAL_CONTROL_CHARACTERS.test(provider.displayName) || !isOAuthEntryPath(provider.startUrl) || (provider.qrStartUrl != null && !isOAuthEntryPath(provider.qrStartUrl))) throw invalidOAuthProviders() ids.add(provider.id) return { id: provider.id, displayName: provider.displayName, startUrl: provider.startUrl, ...(typeof provider.qrStartUrl === 'string' ? { qrStartUrl: provider.qrStartUrl } : {}) } }) const capabilities = value.capabilities if (typeof capabilities === 'object' && capabilities !== null && (capabilities as Record).devicePairing === 'dsh-pairing-v1') { providers.push({ id: 'dsh-go-pairing-v1', displayName: 'DSH-Go', startUrl: '/api/v1/device-pairing', devicePairing: true }) } return providers } async startOAuthQrLogin(provider: OAuthProvider = 'zhihu'): Promise { const entry = (await this.oauthProviders()).find(item => item.id === provider) if (entry?.qrStartUrl == null) { throw new ServerApiError('OAUTH_PROVIDER_UNAVAILABLE', 'This OAuth provider is unavailable for QR login.', false) } const value = requireRecord(await this.publicRequest(entry.qrStartUrl, { method: 'POST', body: '{}', }), 'QR login') const scanUrl = normalizeOAuthScanUrl(value.scanUrl, this.baseUrl) if (typeof value.qrId !== 'string' || value.qrId.length < 20 || scanUrl === undefined || !Number.isSafeInteger(value.expiresIn) || (provider !== 'zhihu' && value.provider !== provider) || (value.provider !== undefined && value.provider !== provider)) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid QR login session.', false) } return { qrId: value.qrId, scanUrl, expiresIn: value.expiresIn as number } } async pollOAuthQrLogin( identity: HostIdentity, qrId: string, recoverIdentity?: () => Promise, ): Promise { this.bindIdentity(identity) const value = requireRecord(await this.publicRequest( `/api/v1/auth/oauth/qr/${encodeURIComponent(qrId)}`, { method: 'GET' }, ), 'QR login status') if (value.status === 'pending' || value.status === 'expired') return { status: value.status } if (value.status !== 'complete' || typeof value.token !== 'string' || value.token.length < 16) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid QR login status.', false) } const account = requireRecord(await this.publicRequest( '/api/v1/auth/me', { method: 'GET' }, value.token, ), 'account profile') if (typeof account.account !== 'string' || account.account.length === 0 || typeof account.isAdmin !== 'boolean') { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid account profile.', false) } const authorization = { accountToken: value.token, account: account.account, authorizationMethod: 'account' as const, } try { await this.register(identity, authorization) } catch (error) { if (!(error instanceof ServerApiError) || error.code !== 'DEVICE_REVOKED' || recoverIdentity === undefined) throw error const nextIdentity = await recoverIdentity() this.bindIdentity(nextIdentity) await this.register(nextIdentity, authorization) } return { status: 'complete', authorization: { method: 'account', account: account.account, isAdmin: account.isAdmin }, } } async authorizeHostWithCode(identity: HostIdentity, code: string): Promise { if (this.role !== 'host') { throw new ServerApiError('METHOD_NOT_ALLOWED', 'Host registration codes can only authorize a Host device.', false) } const registrationCode = code.trim().toUpperCase() if (registrationCode.length === 0) { throw new ServerApiError('INVALID_MESSAGE', 'A Host registration code is required.', false) } this.bindIdentity(identity) const tokens = await this.publicRequest('/api/v1/devices/register-with-code', { method: 'POST', body: JSON.stringify({ v: 1, code: registrationCode, device: this.deviceDescriptor(identity) }), }) this.credentials = await this.saveTokens(identity, validateTokens(tokens), { authorizationMethod: 'host_registration_code', }) return { method: 'host_registration_code' } } async authorizeOwnedRole( identity: HostIdentity, authorizingAccessToken: string, account?: string, ): Promise { this.bindIdentity(identity) const tokens = await this.publicRequest('/api/v1/devices/register-owned-role', { method: 'POST', body: JSON.stringify({ v: 1, device: this.deviceDescriptor(identity) }), }, authorizingAccessToken) this.credentials = await this.saveTokens(identity, validateTokens(tokens), { authorizationMethod: 'owned_device', ...(account === undefined ? {} : { account }), }) return { method: 'owned_device', ...(account === undefined ? {} : { account }), } } async authenticate(identity = this.requireIdentity()): Promise { this.bindIdentity(identity) if (this.credentials !== undefined && this.credentials.accessTokenExpiresAt > Date.now() + 30_000) { return this.credentials } this.credentialsPromise ??= this.loadOrIssue(identity).finally(() => { this.credentialsPromise = undefined }) this.credentials = await this.credentialsPromise return this.credentials } async refreshCredentials(rejectedAccessToken = this.credentials?.accessToken): Promise { const identity = this.requireIdentity() this.credentials = await this.withRefreshLock(async () => { // Another process may have rotated the token while we waited for the lock. const stored = await this.store.load(this.baseUrl, identity.deviceId) if (stored === undefined || stored.refreshTokenExpiresAt <= Date.now()) { // A rejected Client read must not implicitly register a signed-out device. if (this.role === 'client') throw new ServerApiError('ACCOUNT_AUTH_REQUIRED', 'Client sign-in is required.', false) return this.register(identity) } if (stored.accessToken !== rejectedAccessToken && stored.accessTokenExpiresAt > Date.now() + 30_000) { return stored } return this.rotateCredentials(identity, stored) }) return this.credentials } private async withRefreshLock(operation: () => Promise): Promise { try { return await this.store.withRefreshLock(operation) } catch (error) { if (error instanceof ServerCredentialsBusyError) { throw new ServerApiError(error.code, error.message, true) } if (error instanceof ServerCredentialsLockUnsupportedError) { throw new ServerApiError(error.code, error.message, false) } throw error } } private async rotateCredentials( identity: HostIdentity, stored: ServerCredentials, allowRecoveredRotation = true, ): Promise { let tokens: TokenPair try { tokens = await this.publicRequest('/api/v1/auth/refresh', { method: 'POST', body: JSON.stringify({ deviceId: identity.deviceId, refreshToken: stored.refreshToken }), }) } catch (error) { if (error instanceof ServerApiError) { // A delayed rejection must not discard credentials another writer saved. if (error.code === 'AUTH_INVALID' || error.code === 'TOKEN_EXPIRED') { const latest = await this.store.load(this.baseUrl, identity.deviceId) if (latest !== undefined && latest.refreshToken !== stored.refreshToken && latest.refreshTokenExpiresAt > Date.now()) { if (latest.accessTokenExpiresAt > Date.now() + 30_000) return latest if (allowRecoveredRotation) return this.rotateCredentials(identity, latest, false) } } throw new ServerApiError(error.code, error.message, error.retryable, error.status, 'credential_refresh', error.reason) } throw error } const saved = await this.store.save({ ...stored, ...validateTokens(tokens), }) // WHY: Self-hosted refresh response recovery returns the original successor // pair, whose accessTokenExpiresAt may already have elapsed while its // refreshToken remains valid. Rotate once more before returning so callers // never put an already-expired accessToken on the wire. if (allowRecoveredRotation && saved.accessTokenExpiresAt <= Date.now() + 30_000 && saved.refreshToken !== stored.refreshToken && saved.refreshTokenExpiresAt > Date.now()) { return this.rotateCredentials(identity, saved, false) } if (saved.accessTokenExpiresAt <= Date.now()) { throw new ServerApiError( 'CONNECTION_FAILED', 'The Server returned an already-expired access token.', true, 200, 'credential_refresh', ) } return saved } async listDevices(signal?: AbortSignal): Promise { const devices: ServerHostDevice[] = [] for await (const page of this.devicePages(signal)) devices.push(...page) return devices } async *devicePages(signal?: AbortSignal): AsyncGenerator { let cursor: string | undefined const cursors = new Set() const ids = new Set() do { signal?.throwIfAborted() const query = new URLSearchParams({ limit: '50' }) if (cursor !== undefined) query.set('cursor', cursor) const result = await this.request<{ items?: unknown; nextCursor?: unknown }>(`/api/v1/devices?${query}`, { signal }) if (!Array.isArray(result.items)) throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid device list.', false) const page = result.items.map(parseHostDevice) const next = result.nextCursor if (next !== undefined && next !== null && (typeof next !== 'string' || next.length === 0 || next.length > 512 || cursors.has(next) || page.length === 0)) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid device list cursor.', false) } for (const device of page) { if (ids.has(device.deviceId)) throw new ServerApiError('INVALID_MESSAGE', 'The Server returned a duplicate device.', false) ids.add(device.deviceId) } cursor = typeof next === 'string' ? next : undefined if (cursor !== undefined) cursors.add(cursor) // Older Servers may ignore limit and return all devices with no cursor. yield page } while (cursor !== undefined) } async deviceFor(peerDeviceId: string, signal?: AbortSignal): Promise { const result = await this.request(`/api/v1/devices/${encodeURIComponent(peerDeviceId)}`, { signal }) return parseAuthorizedPeer(result) } async turnCredentials(connectionId: string): Promise { const result = await this.request<{ iceServers?: unknown }>( `/api/v1/turn/credentials?connection_id=${encodeURIComponent(connectionId)}`, ) if (!Array.isArray(result.iceServers)) return [] return result.iceServers.map(parseIceServer) } async presenceFor(deviceId: string, signal?: AbortSignal): Promise<{ online: boolean; lastSeenAt?: number }> { const result = await this.request>(`/api/v1/devices/${encodeURIComponent(deviceId)}/presence`, { signal }) if (typeof result.online !== 'boolean' || (result.lastSeenAt !== null && result.lastSeenAt !== undefined && !Number.isSafeInteger(result.lastSeenAt))) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned invalid device presence.', false) } return { online: result.online, ...(typeof result.lastSeenAt === 'number' ? { lastSeenAt: result.lastSeenAt } : {}) } } private async loadOrIssue(identity: HostIdentity): Promise { return this.withRefreshLock(async () => { const stored = await this.store.load(this.baseUrl, identity.deviceId) if (stored === undefined || stored.refreshTokenExpiresAt <= Date.now() + 30_000) { return this.register(identity) } if (stored.accessTokenExpiresAt > Date.now() + 30_000) return stored return this.rotateCredentials(identity, stored) }) } private async register( identity: HostIdentity, authorization?: { accountToken: string account: string authorizationMethod: 'account' }, ): Promise { const tokens = await this.publicRequest('/api/v1/devices/register', { method: 'POST', body: JSON.stringify({ v: 1, device: this.deviceDescriptor(identity), }), }, authorization?.accountToken) this.credentials = await this.saveTokens(identity, validateTokens(tokens), { authorizationMethod: authorization?.authorizationMethod ?? 'account', ...(authorization?.account === undefined ? {} : { account: authorization.account }), }) return this.credentials } private deviceDescriptor(identity: HostIdentity): Record { return { deviceId: identity.deviceId, name: identity.name, role: this.role, platform: platform(), identityKey: identity.publicKey, clientVersion: PLUGIN_VERSION, ...(this.role === 'host' && this.harnessVersion !== undefined ? { harnessVersion: this.harnessVersion } : {}), } } private saveTokens( identity: HostIdentity, tokens: TokenPair, authorization: Pick, ): Promise { return this.store.save({ serverUrl: this.baseUrl, deviceId: identity.deviceId, authorizationMethod: authorization.authorizationMethod, ...(authorization.account === undefined ? {} : { account: authorization.account }), ...tokens, }) } private async request(path: string, init: RequestInit = {}): Promise { const credentials = await this.authenticate() try { return await this.publicRequest(path, init, credentials.accessToken) } catch (error) { // The Server may reject a bearer before its locally cached expiry. // Only retry an explicitly rejected, read-only request, once. if (this.identity?.deviceId !== credentials.deviceId || (init.method ?? 'GET') !== 'GET' || !(error instanceof ServerApiError) || error.status !== 401 || (error.code !== 'AUTH_INVALID' && error.code !== 'TOKEN_EXPIRED')) throw error init.signal?.throwIfAborted() const next = await this.refreshCredentials(credentials.accessToken) if (next.account !== credentials.account || this.identity?.deviceId !== credentials.deviceId) throw error return this.publicRequest(path, init, next.accessToken) } } private async publicRequest(path: string, init: RequestInit, accessToken?: string): Promise { const controller = new AbortController() const timer = setTimeout(() => controller.abort(), 10_000) const signal = AbortSignal.any([ this.lifetime.signal, controller.signal, ...(init.signal == null ? [] : [init.signal]), ]) try { signal.throwIfAborted() const response = await this.fetchImplementation(`${this.baseUrl}${path}`, { ...init, signal, headers: { Accept: 'application/json', 'Content-Type': 'application/json', ...(accessToken === undefined ? {} : { Authorization: `Bearer ${accessToken}` }), ...init.headers, }, }) const body = await parseBody(response) signal.throwIfAborted() if (!response.ok) { const envelope = isErrorEnvelope(body) ? body : undefined // A gateway can challenge requests during startup. Only a protocol // error envelope establishes that the device credentials were rejected. if ((response.status === 401 || response.status === 403) && envelope === undefined) { throw new ServerApiError('CONNECTION_FAILED', 'The Server returned an invalid authorization response.', true, response.status, undefined, 'invalid_error_envelope') } throw new ServerApiError( responseErrorCode(response.status, envelope?.error.code), envelope?.error.message ?? 'The Server rejected the request.', envelope?.error.retryable === true || response.status >= 500 || response.status === 429, response.status, undefined, 'http_error', ) } return body as TResult } catch (error) { if (this.lifetime.signal.aborted) throw this.lifetime.signal.reason if (error instanceof ServerApiError) throw error throw new ServerApiError('CONNECTION_FAILED', 'Server request failed.', true, undefined, undefined, controller.signal.aborted ? 'timeout' : 'network_error') } finally { clearTimeout(timer) } } private requireIdentity(): HostIdentity { if (this.identity === undefined) throw new ServerApiError('IDENTITY_INVALID', 'The device identity is not loaded.', false) return this.identity } } function isOAuthEntryPath(value: unknown): value is string { return typeof value === 'string' && /^\/api\/v1\/auth\/[^\s\\#]*$/.test(value) && !TERMINAL_CONTROL_CHARACTERS.test(value) && !value.split('?')[0]?.split('/').some(segment => segment === '.' || segment === '..' || /%/u.test(segment)) } function invalidOAuthProviders(): ServerApiError { return new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid OAuth provider list.', false) } function normalizeOAuthScanUrl(value: unknown, baseUrl: string): string | undefined { if (typeof value !== 'string' || TERMINAL_CONTROL_CHARACTERS.test(value)) return undefined try { const normalized = new URL(value).href return normalized.startsWith(`${baseUrl}/`) ? normalized : undefined } catch { return undefined } } export class ClientServerApi extends HostServerApi { constructor(serverUrl: string, store: ServerCredentialStore, fetchImplementation: FetchImplementation = fetch, httpServerAllowlist: readonly string[] = []) { super(serverUrl, store, fetchImplementation, 'client', httpServerAllowlist) } } export class ServerApiError extends Error { constructor( readonly code: string, message: string, readonly retryable: boolean, readonly status?: number, readonly phase?: 'credential_refresh', readonly reason?: 'http_error' | 'invalid_json' | 'invalid_error_envelope' | 'timeout' | 'network_error', ) { super(message) } } function validateTokens(value: unknown): TokenPair { const parsed = deviceTokenPairSchema.safeParse(value) if (!parsed.success) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned invalid device credentials.', false) } return parsed.data } function validateWebLogin(value: unknown): WebLoginResponse { const item = requireRecord(value, 'account login') if (typeof item.token !== 'string' || item.token.length < 16 || !Number.isSafeInteger(item.expiresAt) || typeof item.account !== 'string' || item.account.length === 0 || item.account.length > 254 || typeof item.isAdmin !== 'boolean') { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid account session.', false) } return { token: item.token, expiresAt: item.expiresAt as number, account: item.account, profile: item.profile, isAdmin: item.isAdmin, } } function isErrorEnvelope(value: unknown): value is ErrorEnvelope { if (typeof value !== 'object' || value === null || Array.isArray(value)) return false const error = (value as Record).error if (typeof error !== 'object' || error === null || Array.isArray(error)) return false const fields = error as Record return typeof fields.code === 'string' && fields.code.length > 0 && typeof fields.message === 'string' && typeof fields.retryable === 'boolean' } async function parseBody(response: Response): Promise { const text = await response.text() if (text.length === 0) return undefined try { return JSON.parse(text) } catch { const unstructuredAuth = response.status === 401 || response.status === 403 throw new ServerApiError(unstructuredAuth ? 'CONNECTION_FAILED' : response.ok ? 'INVALID_MESSAGE' : responseErrorCode(response.status, undefined), 'The Server returned invalid JSON.', unstructuredAuth || response.ok || response.status >= 500 || response.status === 429, response.status, undefined, 'invalid_json') } } function responseErrorCode(status: number, serverCode: unknown): string { // Only a specific authorization response may change the local login state. // A proxy error or an unclassified rejection must preserve stored credentials. if (status >= 500) return 'CONNECTION_FAILED' if (status === 429) return 'RATE_LIMITED' if ((status === 401 || status === 403) && typeof serverCode === 'string') return serverCode if (status === 401 || status === 403) return 'REQUEST_REJECTED' if (typeof serverCode === 'string' && !AUTHORIZATION_ERROR_CODES.has(serverCode)) return serverCode if (status === 404) return 'DEVICE_NOT_FOUND' return 'INVALID_MESSAGE' } const AUTHORIZATION_ERROR_CODES = new Set([ 'ACCOUNT_AUTH_REQUIRED', 'AUTH_INVALID', 'AUTH_REQUIRED', 'TOKEN_EXPIRED', 'DEVICE_REVOKED', 'DEVICE_OWNERSHIP_REQUIRED', ]) function parseHostDevice(value: unknown): ServerHostDevice { const item = requireRecord(value, 'host device') if (item.role !== 'host' || typeof item.deviceId !== 'string' || typeof item.name !== 'string' || typeof item.platform !== 'string' || typeof item.membershipId !== 'string' || item.membershipId.length === 0) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned invalid host device data.', false) } return { deviceId: item.deviceId, name: item.name, platform: item.platform, membershipId: item.membershipId, ...(typeof item.online === 'boolean' ? { online: item.online } : {}), ...(typeof item.lastSeenAt === 'number' && Number.isSafeInteger(item.lastSeenAt) ? { lastSeenAt: item.lastSeenAt } : {}), ...(typeof item.clientVersion === 'string' ? { clientVersion: item.clientVersion } : {}), ...(typeof item.harnessVersion === 'string' ? { harnessVersion: item.harnessVersion } : {}), } } function parseAuthorizedPeer(value: unknown): AuthorizedPeerDevice { const item = requireRecord(value, 'authorized peer') if ((item.role !== 'host' && item.role !== 'client') || typeof item.deviceId !== 'string' || item.deviceId.length === 0 || typeof item.name !== 'string' || item.name.length === 0 || typeof item.platform !== 'string' || item.platform.length === 0 || typeof item.identityKey !== 'string' || !isIdentityKey(item.identityKey) || typeof item.membershipId !== 'string' || item.membershipId.length === 0) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned invalid authorized peer data.', false) } return { deviceId: item.deviceId, name: item.name, role: item.role, platform: item.platform, identityKey: item.identityKey, membershipId: item.membershipId, ...(typeof item.online === 'boolean' ? { online: item.online } : {}), ...(typeof item.lastSeenAt === 'number' && Number.isSafeInteger(item.lastSeenAt) ? { lastSeenAt: item.lastSeenAt } : {}), } } function parseIceServer(value: unknown): RtcIceServer { const item = requireRecord(value, 'ICE server') const urls = item.urls if (typeof urls !== 'string' && !(Array.isArray(urls) && urls.every(url => typeof url === 'string'))) { throw new ServerApiError('INVALID_MESSAGE', 'The Server returned an invalid ICE server.', false) } return { urls, ...(typeof item.username === 'string' ? { username: item.username } : {}), ...(typeof item.credential === 'string' ? { credential: item.credential } : {}), } } function isIdentityKey(value: string): boolean { try { const decoded = fromBase64Url(value) return decoded.length === 32 && toBase64Url(decoded) === value } catch { return false } } function requireRecord(value: unknown, name: string): Record { if (typeof value !== 'object' || value === null || Array.isArray(value)) { throw new ServerApiError('INVALID_MESSAGE', `The Server returned invalid ${name} data.`, false) } return value as Record }