ds-harness-remote-fast/apps/android/src/services/api.ts

472 lines
18 KiB
TypeScript

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<void> {
const body = await this.request<unknown>('/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<unknown>('/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<unknown>('/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<OAuthProviderInfo[]> {
let body: unknown
try {
body = await this.request<unknown>('/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<unknown>(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<string>()
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<OAuthQrSession> {
if (provider.qrStartUrl === undefined) {
throw new RemoteApiError('INVALID_MESSAGE', 'This provider does not support QR sign-in.')
}
const body = await this.request<unknown>(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<OAuthQrPollResult> {
const body = await this.request<unknown>(`/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<unknown>('/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<void> {
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<void> {
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<unknown>(`/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<AccountLoginResult> {
const body = await this.request<unknown>('/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<TokenPair> {
const body = await this.request<unknown>('/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<TokenPair> {
const body = await this.request<unknown>('/api/v1/auth/refresh', {
method: 'POST',
body: JSON.stringify({ deviceId, refreshToken }),
}, false)
return parseTokenPair(body)
}
/** Hosts visible through same-account membership. */
async listDevices(): Promise<RemoteDevice[]> {
const body = await this.request<unknown>('/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<AuthorizedPeerDevice> {
const body = await this.request<unknown>(`/api/v1/devices/${encodeURIComponent(deviceId)}`)
return parseAuthorizedPeer(body)
}
async getPresence(deviceId: string): Promise<DevicePresence> {
const body = await this.request<unknown>(`/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<RtcIceServer[]> {
const body = await this.request<unknown>(
`/api/v1/turn/credentials?connection_id=${encodeURIComponent(connectionId)}`,
)
if (!isRecord(body) || !Array.isArray(body.iceServers)) return []
return body.iceServers.flatMap(parseIceServer)
}
private async request<TResult>(
path: string,
init: RequestInit = {},
authenticated = true,
accountToken?: string,
): Promise<TResult> {
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<string, unknown> {
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'
}