ds-harness-remote-fast/packages/plugin/src/server-api.ts

796 lines
33 KiB
TypeScript

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<ServerCredentials>
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<void> {
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<void> {
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<boolean> {
const identity = this.requireIdentity()
return await this.store.load(this.baseUrl, identity.deviceId) !== undefined
}
async clearAuthorization(): Promise<void> {
this.credentials = undefined
this.credentialsPromise = undefined
await this.store.clear()
}
async revokeCurrentDevice(): Promise<void> {
const identity = this.requireIdentity()
if (await this.store.load(this.baseUrl, identity.deviceId) === undefined) {
await this.clearAuthorization()
return
}
try {
await this.request<unknown>('/api/v1/devices/self', { method: 'DELETE' })
} finally {
await this.clearAuthorization()
}
}
async authorizeWithAccount(
identity: HostIdentity,
email: string,
password: string,
recoverIdentity?: () => Promise<HostIdentity>,
): Promise<DeviceAuthorization> {
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<unknown>('/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<OAuthProviderInfo[]> {
let body: unknown
try {
body = await this.publicRequest<unknown>('/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<unknown>(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<string>()
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<string, unknown>).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<OAuthQrSession> {
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<unknown>(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<HostIdentity>,
): Promise<OAuthQrPollResult> {
this.bindIdentity(identity)
const value = requireRecord(await this.publicRequest<unknown>(
`/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<unknown>(
'/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<DeviceAuthorization> {
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<TokenPair>('/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<DeviceAuthorization> {
this.bindIdentity(identity)
const tokens = await this.publicRequest<TokenPair>('/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<ServerCredentials> {
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<ServerCredentials> {
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<T>(operation: () => Promise<T>): Promise<T> {
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<ServerCredentials> {
let tokens: TokenPair
try {
tokens = await this.publicRequest<TokenPair>('/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<ServerHostDevice[]> {
const devices: ServerHostDevice[] = []
for await (const page of this.devicePages(signal)) devices.push(...page)
return devices
}
async *devicePages(signal?: AbortSignal): AsyncGenerator<ServerHostDevice[]> {
let cursor: string | undefined
const cursors = new Set<string>()
const ids = new Set<string>()
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<AuthorizedPeerDevice> {
const result = await this.request<unknown>(`/api/v1/devices/${encodeURIComponent(peerDeviceId)}`, { signal })
return parseAuthorizedPeer(result)
}
async turnCredentials(connectionId: string): Promise<RtcIceServer[]> {
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<Record<string, unknown>>(`/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<ServerCredentials> {
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<ServerCredentials> {
const tokens = await this.publicRequest<TokenPair>('/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<string, unknown> {
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<ServerCredentials, 'authorizationMethod' | 'account'>,
): Promise<ServerCredentials> {
return this.store.save({
serverUrl: this.baseUrl,
deviceId: identity.deviceId,
authorizationMethod: authorization.authorizationMethod,
...(authorization.account === undefined ? {} : { account: authorization.account }),
...tokens,
})
}
private async request<TResult>(path: string, init: RequestInit = {}): Promise<TResult> {
const credentials = await this.authenticate()
try {
return await this.publicRequest<TResult>(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<TResult>(path, init, next.accessToken)
}
}
private async publicRequest<TResult>(path: string, init: RequestInit, accessToken?: string): Promise<TResult> {
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<string, unknown>).error
if (typeof error !== 'object' || error === null || Array.isArray(error)) return false
const fields = error as Record<string, unknown>
return typeof fields.code === 'string' && fields.code.length > 0
&& typeof fields.message === 'string' && typeof fields.retryable === 'boolean'
}
async function parseBody(response: Response): Promise<unknown> {
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<string, unknown> {
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<string, unknown>
}