import { connectionLog } from './connection-log' import appConfig from '../../app.json' import { MAX_DEVICE_NAME_LENGTH, deviceTokenPairSchema, type DeviceTokenPair as TokenPair } from '@dsh-remote/protocol' import { RemoteApiError } from '../lib/errors' import { normalizeServerUrl } from '../lib/server-url' import type { DeviceCredentials, DeviceIdentity, DevicePresence, RemoteDevice, } from '../types' interface ErrorBody { detail?: unknown code?: unknown error?: { code?: unknown message?: unknown retryable?: unknown } } interface AccountLoginResult { token: string expiresAt: number account: string isAdmin: boolean } export interface AuthorizedPeerDevice { deviceId: string name: string role: 'host' | 'client' platform: string identityKey: string membershipId: string online?: boolean lastSeenAt?: number clientVersion?: string harnessVersion?: string } export interface RtcIceServer { urls: string | string[] username?: string credential?: string } /** Server-owned OAuth provider; IDs are opaque and controlled by the Server. */ export interface OAuthProviderInfo { id: string displayName: string startUrl: string qrStartUrl?: string } export interface OAuthQrSession { qrId: string scanUrl: string expiresIn: number } export type OAuthQrPollResult = | { status: 'pending' | 'expired' } | { status: 'complete'; token: string } type FetchImplementation = typeof fetch export class RemoteServerApi { readonly baseUrl: string constructor( baseUrl: string, private readonly accessToken?: string, private readonly fetchImplementation: FetchImplementation = fetch, private readonly timeoutMs = 10_000, ) { this.baseUrl = normalizeServerUrl(baseUrl) } async health(): Promise { const body = await this.request('/health', {}, false) if (!isRecord(body) || body.status !== 'ok') { throw new RemoteApiError('CONNECTION_FAILED', 'The server health check failed.') } } /** Whether the server has Zhihu OAuth configured for account sign-in. */ async oauthStatus(): Promise<{ configured: boolean }> { const body = await this.request('/api/v1/auth/oauth/status', {}, false) if (!isRecord(body) || typeof body.configured !== 'boolean') invalidResponse('oauth status') return { configured: body.configured } } /** Whether the server has GitHub OAuth configured for account sign-in. */ async oauthGithubStatus(): Promise<{ configured: boolean }> { const body = await this.request('/api/v1/auth/oauth/github/status', {}, false) if (!isRecord(body) || typeof body.configured !== 'boolean') invalidResponse('GitHub oauth status') return { configured: body.configured } } /** * Server-defined OAuth providers. A provider without `qrStartUrl` cannot be * used for QR sign-in. Older Servers only expose the per-provider status * endpoints, so fall back to those only when the discovery endpoint is 404. */ async oauthProviders(): Promise { let body: unknown try { body = await this.request('/api/v1/auth/oauth/providers', {}, false) } catch (error) { if (!(error instanceof RemoteApiError) || error.status !== 404) throw error const legacy: OAuthProviderInfo[] = [] for (const [id, displayName, statusPath, startPath] of [ ['zhihu', '知乎', '/api/v1/auth/oauth/status', '/api/v1/auth/oauth/start'], ['github', 'GitHub', '/api/v1/auth/oauth/github/status', '/api/v1/auth/oauth/github/start'], ] as const) { try { const status = await this.request(statusPath, {}, false) if (isRecord(status) && status.configured === true) { legacy.push({ id, displayName, startUrl: startPath, qrStartUrl: `/api/v1/auth/oauth/qr/start?provider=${id}`, }) } } catch (reason) { if (reason instanceof RemoteApiError && reason.status === 404) continue throw reason } } return legacy } if (!isRecord(body) || !Array.isArray(body.items)) invalidResponse('OAuth providers') const ids = new Set() return body.items.map(item => { if (!isRecord(item) || typeof item.id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(item.id) || ids.has(item.id) || typeof item.displayName !== 'string' || item.displayName.trim().length === 0 || item.displayName.length > 128 || !isAuthEntryPath(item.startUrl) || (item.qrStartUrl !== undefined && item.qrStartUrl !== null && !isAuthEntryPath(item.qrStartUrl))) { invalidResponse('OAuth providers') } ids.add(item.id) return { id: item.id, displayName: item.displayName, startUrl: item.startUrl, ...(typeof item.qrStartUrl === 'string' ? { qrStartUrl: item.qrStartUrl } : {}), } satisfies OAuthProviderInfo }) } /** Create a short-lived QR sign-in session for one Server-owned provider. */ async startOAuthQrLogin(provider: OAuthProviderInfo): Promise { if (provider.qrStartUrl === undefined) { throw new RemoteApiError('INVALID_MESSAGE', 'This provider does not support QR sign-in.') } const body = await this.request(provider.qrStartUrl, { method: 'POST', body: '{}' }, false) if (!isRecord(body) || typeof body.qrId !== 'string' || body.qrId.length < 20 || !Number.isSafeInteger(body.expiresIn) || (body.expiresIn as number) <= 0 || (body.provider !== undefined && body.provider !== provider.id)) { invalidResponse('QR sign-in session') } const scanUrl = sameOriginScanUrl(body.scanUrl, this.baseUrl) if (scanUrl === undefined) invalidResponse('QR sign-in session') return { qrId: body.qrId, scanUrl, expiresIn: body.expiresIn as number } } /** Poll a QR sign-in session; the account token is returned exactly once on completion. */ async pollOAuthQrLogin(qrId: string): Promise { const body = await this.request(`/api/v1/auth/oauth/qr/${encodeURIComponent(qrId)}`, {}, false) if (!isRecord(body)) invalidResponse('QR sign-in status') if (body.status === 'pending' || body.status === 'expired') return { status: body.status } if (body.status !== 'complete' || typeof body.token !== 'string' || body.token.length < 16) { invalidResponse('QR sign-in status') } return { status: 'complete', token: body.token } } async accountMe(accountToken: string): Promise<{ account: string }> { const body = await this.request('/api/v1/auth/me', {}, false, accountToken) if (!isRecord(body) || typeof body.account !== 'string' || body.account.length === 0) invalidResponse('account profile') return { account: body.account } } async removeSelf(): Promise { await this.request('/api/v1/devices/self', { method: 'DELETE' }) } /** Remove an account-owned Host, matching the Web device removal operation. */ async removeAccountDevice(deviceId: string): Promise { await this.request(`/api/v1/account/devices/${encodeURIComponent(deviceId)}`, { method: 'DELETE' }) } /** Rename an account-owned Host using the same endpoint as Web management. */ async renameAccountDevice(deviceId: string, name: string): Promise<{ name: string }> { const trimmed = name.trim() if (trimmed.length === 0 || trimmed.length > MAX_DEVICE_NAME_LENGTH) { throw new RemoteApiError('INVALID_MESSAGE', 'Enter a device name between 1 and 128 characters.') } const body = await this.request(`/api/v1/account/devices/${encodeURIComponent(deviceId)}`, { method: 'PATCH', body: JSON.stringify({ name: trimmed }), }) if (!isRecord(body) || typeof body.name !== 'string' || body.name.trim().length === 0 || body.name.length > MAX_DEVICE_NAME_LENGTH) invalidResponse('renamed device') return { name: body.name } } /** Account password login; the returned token only authorizes device registration. */ async loginAccount(email: string, password: string): Promise { const body = await this.request('/api/v1/auth/login', { method: 'POST', body: JSON.stringify({ email: email.trim(), password }), }, false) if (!isRecord(body) || typeof body.token !== 'string' || body.token.length < 16 || typeof body.account !== 'string' || body.account.length === 0 || typeof body.expiresAt !== 'number' || !Number.isSafeInteger(body.expiresAt) || typeof body.isAdmin !== 'boolean') { invalidResponse('account login') } return { token: body.token, expiresAt: body.expiresAt, account: body.account, isAdmin: body.isAdmin, } } /** Register this Android client under the account token. */ async registerDevice(identity: DeviceIdentity, accountToken: string): Promise { const body = await this.request('/api/v1/devices/register', { method: 'POST', body: JSON.stringify({ v: 1, device: { deviceId: identity.deviceId, name: identity.name, role: 'client', platform: identity.platform, identityKey: identity.publicKey, clientVersion: ANDROID_CLIENT_VERSION, }, }), }, false, accountToken) return parseTokenPair(body) } async refreshToken(deviceId: string, refreshToken: string): Promise { const body = await this.request('/api/v1/auth/refresh', { method: 'POST', body: JSON.stringify({ deviceId, refreshToken }), }, false) return parseTokenPair(body) } /** Hosts visible through same-account membership. */ async listDevices(): Promise { const body = await this.request('/api/v1/devices') if (!isRecord(body) || !Array.isArray(body.items)) invalidResponse('device list') return body.items.flatMap(parseHostDevice) } /** Authorized peer descriptor including the identity key used for Noise pinning. */ async deviceFor(deviceId: string): Promise { const body = await this.request(`/api/v1/devices/${encodeURIComponent(deviceId)}`) return parseAuthorizedPeer(body) } async getPresence(deviceId: string): Promise { const body = await this.request(`/api/v1/devices/${encodeURIComponent(deviceId)}/presence`) if (!isRecord(body) || typeof body.deviceId !== 'string' || typeof body.online !== 'boolean' || (body.lastSeenAt !== null && body.lastSeenAt !== undefined && !Number.isSafeInteger(body.lastSeenAt))) { invalidResponse('device presence') } return { deviceId: body.deviceId, online: body.online, ...(typeof body.lastSeenAt === 'number' ? { lastSeenAt: body.lastSeenAt } : {}), } } async turnCredentials(connectionId: string): Promise { const body = await this.request( `/api/v1/turn/credentials?connection_id=${encodeURIComponent(connectionId)}`, ) if (!isRecord(body) || !Array.isArray(body.iceServers)) return [] return body.iceServers.flatMap(parseIceServer) } private async request( path: string, init: RequestInit = {}, authenticated = true, accountToken?: string, ): Promise { const bearer = accountToken ?? this.accessToken if (authenticated && bearer === undefined) { throw new RemoteApiError('AUTH_REQUIRED', 'This device is not registered with the server.') } const controller = new AbortController() const timer = setTimeout(() => controller.abort(), this.timeoutMs) const requestGroup = path.split('/')[3] const request = ['auth', 'devices', 'account', 'turn'].includes(requestGroup ?? '') ? requestGroup : 'other' const startedAt = Date.now() let response: Response try { response = await this.fetchImplementation(`${this.baseUrl}${path}`, { ...init, signal: controller.signal, headers: { Accept: 'application/json', 'Content-Type': 'application/json', ...(bearer === undefined ? {} : { Authorization: `Bearer ${bearer}` }), ...init.headers, }, }) } catch (error) { const timedOut = error instanceof Error && error.name === 'AbortError' connectionLog('http', { request, method: init.method ?? 'GET', reason: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt }) throw new RemoteApiError( 'CONNECTION_FAILED', timedOut ? 'The server request timed out.' : error instanceof Error ? error.message : 'Server request failed.', undefined, true, ) } finally { clearTimeout(timer) } connectionLog('http', { request, method: init.method ?? 'GET', status: response.status, durationMs: Date.now() - startedAt }) const text = await response.text() let body: unknown = undefined if (text.length > 0) { try { body = JSON.parse(text) } catch { // Proxies can return HTML or plain text when throttling. Preserve the // HTTP rate limit instead of disguising it as a protocol failure. if (response.status === 429) { throw new RemoteApiError('RATE_LIMITED', 'Too many requests. Please try again later.', 429, true) } throw new RemoteApiError('INVALID_MESSAGE', 'The server returned invalid JSON.', response.status) } } if (!response.ok) { const errorBody = (body ?? {}) as ErrorBody const detail = typeof errorBody.error?.message === 'string' ? errorBody.error.message : typeof errorBody.detail === 'string' ? errorBody.detail : 'The server rejected the request.' const code = mapStatus(response.status, detail, errorBody.error?.code ?? errorBody.code) throw new RemoteApiError(code, detail, response.status, errorBody.error?.retryable === true || response.status >= 500 || response.status === 429) } return body as TResult } } /** Keep Server device metadata aligned with the version embedded in the native APK. */ export const ANDROID_CLIENT_VERSION = appConfig.expo.version function parseTokenPair(input: unknown): TokenPair { const parsed = deviceTokenPairSchema.safeParse(input) if (!parsed.success) invalidResponse('device credentials') return parsed.data } function parseHostDevice(input: unknown): RemoteDevice[] { if (!isRecord(input) || typeof input.deviceId !== 'string' || typeof input.name !== 'string' || typeof input.platform !== 'string' || input.role !== 'host' || typeof input.membershipId !== 'string' || input.membershipId.length === 0) { return [] } return [{ deviceId: input.deviceId, name: input.name, platform: input.platform, role: 'host', membershipId: input.membershipId, identityKey: '', online: input.online === true, trusted: false, ...(typeof input.clientVersion === 'string' ? { clientVersion: input.clientVersion } : {}), ...(typeof input.harnessVersion === 'string' ? { harnessVersion: input.harnessVersion } : {}), ...(typeof input.lastSeenAt === 'number' ? { lastSeenAt: input.lastSeenAt } : {}), }] } function parseAuthorizedPeer(input: unknown): AuthorizedPeerDevice { if (!isRecord(input) || (input.role !== 'host' && input.role !== 'client') || typeof input.deviceId !== 'string' || input.deviceId.length === 0 || typeof input.name !== 'string' || input.name.length === 0 || typeof input.platform !== 'string' || typeof input.identityKey !== 'string' || input.identityKey.length === 0 || typeof input.membershipId !== 'string' || input.membershipId.length === 0) { invalidResponse('authorized peer') } return { deviceId: input.deviceId, name: input.name, role: input.role, platform: input.platform, identityKey: input.identityKey, membershipId: input.membershipId, ...(typeof input.online === 'boolean' ? { online: input.online } : {}), ...(typeof input.lastSeenAt === 'number' ? { lastSeenAt: input.lastSeenAt } : {}), ...(typeof input.clientVersion === 'string' ? { clientVersion: input.clientVersion } : {}), ...(typeof input.harnessVersion === 'string' ? { harnessVersion: input.harnessVersion } : {}), } } function parseIceServer(input: unknown): RtcIceServer[] { if (!isRecord(input)) return [] const urls = input.urls if (typeof urls !== 'string' && !(Array.isArray(urls) && urls.every(url => typeof url === 'string'))) return [] return [{ urls, ...(typeof input.username === 'string' ? { username: input.username } : {}), ...(typeof input.credential === 'string' ? { credential: input.credential } : {}), }] } function invalidResponse(name: string): never { throw new RemoteApiError('INVALID_MESSAGE', `The server returned invalid ${name} data.`) } /** * Only same-origin auth entry paths are accepted. This prevents a compromised * discovery response from turning the Client into an open request forwarder. */ function isAuthEntryPath(value: unknown): value is string { if (typeof value !== 'string' || !value.startsWith('/api/v1/auth/') || /[\u0000-\u001f\u007f\s\\#]/u.test(value)) { return false } return !(value.split('?')[0] ?? '').split('/').some(segment => segment === '.' || segment === '..' || segment.includes('%')) } /** The QR payload must stay on the configured Server origin and path prefix. */ function sameOriginScanUrl(value: unknown, baseUrl: string): string | undefined { if (typeof value !== 'string' || /[\u0000-\u001f\u007f]/u.test(value)) return undefined try { const normalized = new URL(value).href return normalized.startsWith(`${baseUrl}/`) ? normalized : undefined } catch { return undefined } } function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null } function mapStatus(status: number, detail: string, serverCode: unknown): string { if (status === 429) return 'RATE_LIMITED' if (typeof serverCode === 'string') return serverCode if (status === 401) return 'AUTH_INVALID' if (status === 403) return 'AUTH_REQUIRED' if (status === 404) return 'DEVICE_NOT_FOUND' if (status === 409) return 'DEVICE_OWNERSHIP_REQUIRED' return status >= 500 ? 'CONNECTION_FAILED' : 'INVALID_MESSAGE' }