realtimeApi.ts 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. import { randomBytes } from 'node:crypto'
  2. import type { Server, IncomingMessage } from 'node:http'
  3. import type { Duplex } from 'node:stream'
  4. import type Koa from 'koa'
  5. import { RealtimeBroker, type RealtimePrincipal, type RealtimeChannel } from './realtimeBroker.js'
  6. import type { ServerConfig } from './config.js'
  7. import { LocalAuthStore, UpstreamServiceSession } from './localAuth.js'
  8. import { NodePairingStore } from './pairing.js'
  9. import { CookieJar, UpstreamClient } from './upstream.js'
  10. import { CsrfProtection, isAllowedHostHeader, isExactOrigin } from './security.js'
  11. import { HttpError } from './errors.js'
  12. import { canonicalEpoch, groupCursor } from './realtimeProtocol.js'
  13. import { CHAT_MAX_PAYLOAD } from './realtimeProtocol.js'
  14. import { ChatPushRelayObserver, type ChatNotificationResolver, type PushEventCoordinator, type ChatPushTransportFactory } from './pushEvents.js'
  15. export class RealtimeAPI {
  16. readonly broker: RealtimeBroker
  17. private observers = new Map<string, ChatPushRelayObserver>()
  18. constructor(readonly config: ServerConfig, readonly auth: LocalAuthStore, readonly csrf: CsrfProtection,
  19. readonly pairings: NodePairingStore, readonly upstream: UpstreamClient, readonly session: UpstreamServiceSession,
  20. readonly push?: { coordinator: PushEventCoordinator; resolver: ChatNotificationResolver }) {
  21. this.broker = new RealtimeBroker(config.home, Date.now, change => {
  22. upstream.observeRealtime(change)
  23. if (change.kind === 'reset') session.invalidateAuthentication()
  24. })
  25. }
  26. private principal(ctx: Koa.Context, device?: string): RealtimePrincipal {
  27. let key: string
  28. let valid: () => boolean
  29. let authorize: RealtimePrincipal['authorize']
  30. let jar: CookieJar | undefined
  31. let observer: ChatPushRelayObserver | undefined
  32. if (device) {
  33. const bearer = ctx.get('authorization').match(/^Bearer\s+(.+)$/i)?.[1] ?? ''
  34. jar = new CookieJar(this.pairings.authorize(device, bearer))
  35. key = `device:${device}`
  36. valid = () => this.pairings.hasDevice(device)
  37. authorize = (kind, method) => {
  38. this.pairings.authorize(device, bearer, kind === 'groups' ? 'groups.read'
  39. : method === 'profiles.list' || method === 'profiles.get_asset' ? 'agents.read' : 'sessions.execute')
  40. }
  41. } else {
  42. const user = this.auth.require(ctx)
  43. const cookie = ctx.get('cookie')
  44. key = `user:${user.id}:${this.auth.pushAuthorizationVersion(user.id)}`
  45. valid = () => { try { return this.auth.currentFromCookieHeader(cookie)?.id === user.id } catch { return false } }
  46. if (this.push) {
  47. observer = this.observers.get(key)
  48. if (!observer) {
  49. observer = new ChatPushRelayObserver(this.push.coordinator, { localUserID: user.id, source: 'web' }, Date.now, this.push.resolver)
  50. this.observers.set(key, observer)
  51. }
  52. }
  53. }
  54. return {
  55. key, instanceKey: this.config.upstream.href, upstreamKey: `${this.config.upstream.href}:${device ? `device:${device}` : 'service'}`, paired: Boolean(device), valid, authorize,
  56. agent: this.upstream.directAgent,
  57. observeCommand: f => observer?.observeClientFrame(f),
  58. observeEvent: f => observer?.observeUpstreamFrame(Buffer.from(f), false),
  59. url: async (kind, anchor) => {
  60. if (device && !valid()) throw new HttpError(401, 'Device revoked', 'authentication_required')
  61. // Paired devices retain their delegated identity; never upgrade a device
  62. // cookie into the local service's loopback authorization.
  63. let credential: { name: string; value: string }
  64. if (jar) {
  65. const response = await this.upstream.request('/api/auth/ws-ticket', jar, { method: 'POST' })
  66. if (response.status !== 200) throw new HttpError(502, 'Upstream authentication failed', 'upstream_auth_failed')
  67. const ticket = JSON.parse(response.body.toString()).ticket
  68. if (typeof ticket !== 'string' || !ticket) throw new HttpError(502, 'Invalid upstream ticket', 'invalid_ticket')
  69. credential = { name: 'ticket', value: ticket }
  70. } else credential = await this.session.webSocketCredential()
  71. const url = new URL(this.config.upstream)
  72. url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
  73. url.pathname = `${url.pathname.replace(/\/$/, '')}/api/ws`
  74. url.search = ''; url.searchParams.set(credential.name, credential.value)
  75. if (anchor) { url.searchParams.set('epoch', anchor.epoch); url.searchParams.set('cursor', String(anchor.cursor)) }
  76. return url
  77. },
  78. }
  79. }
  80. recoveryTransport: ChatPushTransportFactory = async (job, onFrame, onClose) => {
  81. const principal: RealtimePrincipal = {
  82. key: `push:${job.localUserID}:${this.auth.pushAuthorizationVersion(job.localUserID)}`,
  83. upstreamKey: `${this.config.upstream.href}:service`, paired: false,
  84. instanceKey: this.config.upstream.href,
  85. agent: this.upstream.directAgent,
  86. valid: () => this.auth.isUserActive(job.localUserID),
  87. url: async () => {
  88. const credential = await this.session.webSocketCredential()
  89. const url = new URL(this.config.upstream)
  90. url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
  91. url.pathname = `${url.pathname.replace(/\/$/, '')}/api/ws`
  92. url.search = ''; url.searchParams.set(credential.name, credential.value)
  93. return url
  94. },
  95. }
  96. const channel = await this.broker.create(principal, 'chat')
  97. let off = () => {}, closed = false
  98. return {
  99. start: () => { off = this.broker.subscribe(channel, undefined, entry => { if (entry.event === 'reset') onClose(); else onFrame(entry.data) }) },
  100. send: raw => {
  101. const frame = JSON.parse(raw)
  102. void Promise.resolve().then(() => this.broker.command(channel, randomBytes(24).toString('hex'), frame)).then(receipt => {
  103. if (!closed) onFrame(JSON.stringify({ id: frame.id, ...(receipt.response ?? { error: { message: 'Submission uncertain' } }) }))
  104. }).catch(onClose)
  105. },
  106. close: () => { closed = true; off(); this.broker.release(channel) },
  107. }
  108. }
  109. ownsPushJob(jobID: string): boolean { return [...this.observers.values()].some(observer => observer.ownsJob(jobID)) }
  110. private checkMutation(ctx: Koa.Context, paired: boolean): void {
  111. if (paired || ['GET', 'HEAD'].includes(ctx.method)) return
  112. if (!isExactOrigin(ctx.get('origin'), ctx.get('host'), ctx.secure || Boolean(this.config.tlsCert), this.config.allowedHosts)
  113. || !this.csrf.verify(ctx.get('cookie'), ctx.get('x-csrf-token'))) {
  114. throw new HttpError(403, 'Origin or CSRF token is invalid', 'invalid_csrf')
  115. }
  116. }
  117. private async body(ctx: Koa.Context, limit = 2 * 1024 * 1024): Promise<Record<string, any>> {
  118. if (!ctx.is('application/json')) throw new HttpError(415, 'JSON body required', 'invalid_content_type')
  119. let bytes = 0
  120. const chunks: Buffer[] = []
  121. const timeout = setTimeout(() => ctx.req.destroy(), 30_000)
  122. timeout.unref()
  123. try {
  124. for await (const chunk of ctx.req) {
  125. bytes += Buffer.byteLength(chunk)
  126. if (bytes > limit) throw new HttpError(413, 'Request body too large', 'body_too_large')
  127. chunks.push(Buffer.from(chunk))
  128. }
  129. const value: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
  130. if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not object')
  131. return value as Record<string, any>
  132. } catch (e) { if (e instanceof HttpError) throw e; throw new HttpError(400, 'Invalid JSON', 'invalid_json_body') }
  133. finally { clearTimeout(timeout) }
  134. }
  135. middleware(): Koa.Middleware {
  136. return async (ctx, next) => {
  137. const match = /^(?:\/node\/([0-9a-f-]{36}))?\/api\/realtime(\/.*)$/.exec(ctx.path)
  138. if (/^(?:\/node\/[^/]+)?\/api\/(?:auth\/ws-ticket|ws|plugins\/yaoyao\/v1\/events)$/.test(ctx.path)
  139. || ctx.path === '/api/app/realtime-leases' || /^\/ws\/(?:chat|groups)$/.test(ctx.path)) {
  140. throw new HttpError(410, 'Legacy realtime endpoints were removed; use HTTP+SSE', 'http_sse_required')
  141. }
  142. if (!match) return next()
  143. const device = match[1]
  144. const principal = this.principal(ctx, device)
  145. ctx.set('Cache-Control', 'no-store')
  146. const path = match![2]!
  147. if (ctx.method === 'GET' && path === '/capabilities') {
  148. ctx.body = { protocolVersion: 1, channels: ['chat'], brokerEpoch: this.broker.epoch,
  149. ...(device ? {} : { csrfToken: this.csrf.issue(ctx) }) }
  150. return
  151. }
  152. this.checkMutation(ctx, Boolean(device))
  153. if (ctx.method === 'POST' && path === '/channels') {
  154. const body = await this.body(ctx)
  155. if (body.channel !== 'chat' && body.channel !== 'groups') throw new HttpError(400, 'Invalid channel', 'invalid_channel')
  156. const c = await this.broker.create(principal, body.channel, body.channel === 'groups'
  157. ? { epoch: canonicalEpoch(body.epoch), cursor: groupCursor(body.cursor) } : undefined)
  158. ctx.status = 201; ctx.body = { id: c.id, brokerEpoch: this.broker.epoch }; return
  159. }
  160. const receipt = /^\/commands\/([A-Za-z0-9:_-]{1,200})$/.exec(path)
  161. if (receipt && ctx.method === 'GET') { ctx.body = this.broker.receipt(principal, receipt[1]!); return }
  162. const channel = /^\/channels\/([0-9a-f-]{36})(?:\/(commands|events))?$/.exec(path)
  163. if (!channel) throw new HttpError(404, 'Realtime route not found', 'not_found')
  164. const c = this.broker.get(principal, channel[1]!)
  165. if (ctx.method === 'DELETE' && !channel[2]) { this.broker.detach(principal, c.id); ctx.status = 204; return }
  166. if (ctx.method === 'POST' && channel[2] === 'commands') {
  167. const body = await this.body(ctx, CHAT_MAX_PAYLOAD)
  168. ctx.body = await this.broker.command(c, ctx.get('idempotency-key'), body)
  169. return
  170. }
  171. if (ctx.method === 'GET' && channel[2] === 'events') { this.stream(ctx, c); return }
  172. throw new HttpError(405, 'Method not allowed', 'method_not_allowed')
  173. }
  174. }
  175. private stream(ctx: Koa.Context, c: RealtimeChannel): void {
  176. const res = ctx.res
  177. const initial: string[] = []
  178. let started = false
  179. let closed = false
  180. let congested: ReturnType<typeof setTimeout> | undefined
  181. let heartbeat: ReturnType<typeof setInterval> | undefined
  182. let off = () => {}
  183. const close = () => { if (closed) return; closed = true; clearInterval(heartbeat); clearTimeout(congested); off(); if (!res.writableEnded) res.end() }
  184. const write = (text: string) => {
  185. if (!started) { initial.push(text); return }
  186. if (res.destroyed || res.writableEnded) return close()
  187. if (res.writableLength + Buffer.byteLength(text) > 1024 * 1024) return close()
  188. if (!res.write(text) && !congested) { congested = setTimeout(close, 15_000); congested.unref() }
  189. }
  190. off = this.broker.subscribe(c, ctx.get('last-event-id') || undefined, entry => {
  191. write(`id: ${entry.id}\nevent: ${entry.event}\ndata: ${entry.data}\n\n`)
  192. if (entry.event === 'reset' && started) close()
  193. })
  194. ctx.respond = false
  195. res.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' })
  196. res.flushHeaders(); started = true
  197. write(`event: ready\ndata: ${JSON.stringify({ channelId: c.id, brokerEpoch: this.broker.epoch })}\n\n`)
  198. for (const text of initial) write(text)
  199. heartbeat = setInterval(() => { if (!c.principal.valid()) close(); else write(': heartbeat\n\n') }, 15_000)
  200. heartbeat.unref()
  201. res.on('drain', () => { clearTimeout(congested); congested = undefined })
  202. res.once('close', close)
  203. res.once('error', close)
  204. }
  205. rejectLegacyUpgrades(server: Server): () => void {
  206. const upgrade = (request: IncomingMessage, socket: Duplex) => {
  207. const path = (request.url ?? '/').split('?')[0]!
  208. if (!this.config.production && !path.startsWith('/api/') && !path.startsWith('/node/') && !path.startsWith('/ws/')) return
  209. const body = JSON.stringify({ code: 'http_sse_required', error: 'Client WebSockets are no longer supported; use HTTP+SSE' })
  210. socket.end('HTTP/1.1 410 Gone\r\nConnection: close\r\nContent-Type: application/json\r\nContent-Length: ' + Buffer.byteLength(body) + '\r\n\r\n' + body)
  211. }
  212. server.on('upgrade', upgrade)
  213. return () => server.off('upgrade', upgrade)
  214. }
  215. close(): void {
  216. for (const observer of this.observers.values()) observer.disconnected()
  217. this.observers.clear(); this.broker.close()
  218. }
  219. }