Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.8 KB
Raw Blame
import { randomBytes, randomUUID } from 'node:crypto'
import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
import type { AddressInfo, Socket } from 'node:net'
import type { Duplex } from 'node:stream'
import type { Frame } from '../backendSocket.js'
import { VIEWER_MAX_STREAMS, VIEWER_UP_TYPES, ViewerWire, viewerHeaders, viewerTarget, type ViewerSend } from './viewerWire.js'

interface Gateway {
  agentId: string
  target: URL
  server: Server
  origin: string
  token: string
  cookie: string
  sockets: Set<Socket>
  wires: Set<ViewerWire>
}

const BOOTSTRAP = '/__harness_viewer/'
const MAX_VIEWERS = 64

/**
 * Runs on the desktop's daemon, after E2EE decryption. One private HTTP origin per remote viewer
 * preserves root-relative assets, iframes, EventSource, Range requests and WebSocket URLs. The
 * bootstrap URL establishes an HttpOnly cookie then redirects to the viewer's original path.
 * Cross-origin requests and requests without that cookie never reach the remote machine.
 */
export class RemoteViewerProxy {
  private readonly gateways = new Map<string, Gateway>()
  private readonly wires = new Map<string, { wire: ViewerWire; response: (payload: Record<string, unknown>) => void }>()
  private metadata = Promise.resolve()
  private generation = 0
  private disposed = false

  constructor(private readonly deps: {
    supported: () => boolean
    send: ViewerSend
    deliver: (frame: Frame) => void
  }) {}

  /** Viewer bytes are consumed here, never delivered to the desktop's control socket. */
  receive(frame: Frame): boolean {
    const type = typeof frame.type === 'string' ? frame.type : ''
    const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload as Record<string, unknown> : {}
    if (VIEWER_UP_TYPES.has(type)) {
      const stream = this.wires.get(String(payload.streamId))
      if (type === 'viewer_response') stream?.response(payload)
      else stream?.wire.handle(type, payload)
      return true
    }
    const metadata = ['agents_list_result', 'agent_synced', 'agent_created', 'agent_create_result', 'agent_create_status_result', 'agent_create_cancel_result', 'agent_restart_result', 'agent_deleted'].includes(type)
    if (!metadata) return false
    const generation = this.generation
    this.metadata = this.metadata.then(async () => {
      if (this.disposed || generation !== this.generation) return
      const rewritten = await this.rewrite(frame)
      if (!this.disposed && generation === this.generation) this.deps.deliver(rewritten)
    }).catch(() => {
      // A local bind failure must not turn an agents_list RPC into a timeout.
      if (!this.disposed && generation === this.generation) this.deps.deliver(frameWithViewerError(frame))
    })
    return true
  }

  private async rewrite(frame: Frame): Promise<Frame> {
    const generation = this.generation
    const p = frame.payload as Record<string, unknown> | undefined
    if (!p) return frame
    if (frame.type === 'agent_deleted' && typeof p.agentId === 'string') this.remove(p.agentId)
    if (Array.isArray(p.agents)) {
      const ids = new Set(p.agents.map((a) => (a as { id?: unknown })?.id))
      for (const id of this.gateways.keys()) if (!ids.has(id)) this.remove(id)
      const agents = []
      for (const agent of p.agents) {
        if (this.disposed || generation !== this.generation) return frame
        agents.push(await this.rewriteAgent(agent))
      }
      return { ...frame, payload: { ...p, agents } }
    }
    if (p.agent) return { ...frame, payload: { ...p, agent: await this.rewriteAgent(p.agent) } }
    return frame
  }

  private async rewriteAgent(raw: unknown): Promise<unknown> {
    const generation = this.generation
    if (!raw || typeof raw !== 'object') return raw
    const agent = raw as Record<string, unknown>
    if (typeof agent.id !== 'string') return raw
    const target = viewerTarget(agent.viewerUrl)
    if (!target) {
      this.remove(agent.id)
      // Public HTTP(S) URLs remain ordinary URLs; remote loopback URLs must never be opened locally.
      if (agent.viewerUrl && isLoopbackUrl(agent.viewerUrl)) return { ...agent, viewerUrl: null, viewerError: 'This remote viewer requires an HTTP loopback URL.' }
      return raw
    }
    if (!this.deps.supported()) {
      this.remove(agent.id)
      return { ...agent, viewerUrl: null, viewerError: 'Update Harness on the remote machine to show its viewer.' }
    }
    let gateway = this.gateways.get(agent.id)
    if (gateway?.target.origin !== target.origin) { this.remove(agent.id); gateway = undefined }
    if (!gateway) {
      if (this.gateways.size >= MAX_VIEWERS) return { ...agent, viewerUrl: null, viewerError: 'Too many remote viewers are open.' }
      gateway = await this.createGateway(agent.id, target)
      if (this.disposed || generation !== this.generation) { this.closeGateway(gateway); return { ...agent, viewerUrl: null } }
      this.gateways.set(agent.id, gateway)
    }
    gateway.target = target
    const path = target.pathname + target.search + target.hash
    return { ...agent, viewerUrl: `${gateway.origin}${BOOTSTRAP}${gateway.token}?path=${encodeURIComponent(path)}`, viewerError: null }
  }

  private async createGateway(agentId: string, target: URL): Promise<Gateway> {
    const token = randomBytes(24).toString('hex')
    const server = createServer()
    const gateway: Gateway = { agentId, target, server, token, cookie: `hv_${token}`, origin: '', sockets: new Set(), wires: new Set() }
    server.on('connection', (socket) => {
      gateway.sockets.add(socket)
      socket.on('error', () => {})
      socket.on('close', () => gateway.sockets.delete(socket))
    })
    server.on('request', (req, res) => this.serve(gateway, req, res))
    server.on('upgrade', (req, socket, head) => this.serveUpgrade(gateway, req, socket, head))
    server.on('connect', (_req, socket) => socket.destroy())
    server.on('clientError', (_error, socket) => socket.destroy())
    await new Promise<void>((resolve, reject) => {
      server.once('error', reject)
      server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve() })
    })
    server.on('error', () => this.remove(agentId))
    server.unref()
    gateway.origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
    return gateway
  }

  private allowed(gateway: Gateway, req: IncomingMessage): boolean {
    return req.headers.host === new URL(gateway.origin).host
      && (!req.headers.origin || req.headers.origin === gateway.origin)
      && !['cross-site', 'same-site'].includes(String(req.headers['sec-fetch-site']))
      && (!req.headers.referer || req.headers.referer.startsWith(`${gateway.origin}/`))
  }

  private authenticated(gateway: Gateway, req: IncomingMessage): boolean {
    return String(req.headers.cookie ?? '').split(';').some((part) => part.trim() === `${gateway.cookie}=${gateway.token}`)
  }

  private serve(gateway: Gateway, req: IncomingMessage, res: ServerResponse): void {
    res.setHeader('Referrer-Policy', 'no-referrer')
    res.setHeader('Cache-Control', 'no-store')
    if (!this.allowed(gateway, req)) { res.writeHead(403).end('Viewer access denied'); return }
    const requestPath = req.url ?? '/'
    if (!requestPath.startsWith('/') || requestPath.startsWith('//') || /[\s\\]/.test(requestPath)) {
      res.writeHead(400).end('Invalid viewer path'); return
    }
    const url = new URL(requestPath, gateway.origin)
    if (req.method === 'GET' && url.pathname === `${BOOTSTRAP}${gateway.token}`) {
      const path = url.searchParams.get('path') ?? '/'
      if (!path.startsWith('/') || path.startsWith('//') || /[\r\n\\]/.test(path)) { res.writeHead(400).end(); return }
      res.setHeader('Set-Cookie', `${gateway.cookie}=${gateway.token}; Path=/; HttpOnly; SameSite=Strict`)
      res.writeHead(302, { Location: path }).end()
      return
    }
    if (!this.authenticated(gateway, req)) { res.writeHead(403).end('Viewer access denied'); return }
    let responded = false
    const wire = this.open(gateway, req, false, (p, stream) => {
      if (responded) { stream.destroy(new Error('Duplicate viewer response')); return }
      try {
        const status = Number(p.status)
        if (!Number.isInteger(status) || status < 200 || status > 599 || p.upgrade === true) throw new Error('Invalid response')
        responded = true
        res.writeHead(status, this.responseHeaders(gateway, p.headers))
        res.flushHeaders()
        stream.ready()
        stream.pipe(res)
      } catch { stream.destroy(new Error('Invalid viewer response')) }
    })
    if (!wire) { res.writeHead(503).end('Too many viewer requests'); return }
    wire.on('error', () => {
      if (res.headersSent) res.destroy()
      else res.writeHead(502).end('The remote viewer disconnected. Reload to try again.')
    })
    res.on('close', () => wire.destroy())
    req.on('error', () => wire.destroy(new Error('Viewer request interrupted')))
    req.pipe(wire)
  }

  private serveUpgrade(gateway: Gateway, req: IncomingMessage, socket: Duplex, head: Buffer): void {
    if (!this.allowed(gateway, req) || !this.authenticated(gateway, req) || req.headers.upgrade?.toLowerCase() !== 'websocket') {
      socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); return
    }
    let responded = false
    const wire = this.open(gateway, req, true, (p, stream) => {
      if (responded) { stream.destroy(); return }
      responded = true
      if (p.status !== 101 || p.upgrade !== true) { socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); stream.destroy(); return }
      try {
        const headers = this.responseHeaders(gateway, p.headers, true)
        const lines = Object.entries(headers).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((v) => `${key}: ${v}`))
        socket.write(`HTTP/1.1 101 Switching Protocols\r\n${lines.join('\r\n')}\r\n\r\n`)
        stream.ready()
        if (head.length) stream.write(head)
        socket.pipe(stream).pipe(socket)
      } catch { stream.destroy() }
    })
    if (!wire) { socket.destroy(); return }
    wire.on('error', () => socket.destroy())
    wire.on('close', () => socket.destroy())
    socket.on('error', () => wire.destroy())
    socket.on('close', () => wire.destroy())
  }

  private open(gateway: Gateway, req: IncomingMessage, upgrade: boolean, response: (p: Record<string, unknown>, wire: ViewerWire) => void): ViewerWire | null {
    if (this.disposed || this.wires.size >= VIEWER_MAX_STREAMS) return null
    const id = randomUUID()
    const wire = new ViewerWire(id, this.deps.send)
    this.wires.set(id, { wire, response: (p) => response(p, wire) })
    gateway.wires.add(wire)
    wire.on('close', () => { this.wires.delete(id); gateway.wires.delete(wire) })
    try {
      const headers = viewerHeaders(req.headers, upgrade)
      headers.host = gateway.target.host
      if (headers.origin) headers.origin = gateway.target.origin
      if (headers.referer) headers.referer = String(headers.referer).replace(gateway.origin, gateway.target.origin)
      // Cookies are scoped to hosts, not ports. Only this gateway's namespaced viewer cookies cross
      // the wire; the bootstrap credential and other loopback apps' cookies stay on this computer.
      const cookies = String(headers.cookie ?? '').split(';').map((s) => s.trim())
        .filter((s) => s.startsWith(`${gateway.cookie}_`)).map((s) => s.slice(gateway.cookie.length + 1))
      delete headers.cookie
      if (cookies.length) headers.cookie = cookies.join('; ')
      if (!this.deps.send('viewer_request', {
        streamId: id, agentId: gateway.agentId, origin: gateway.target.origin,
        path: req.url, method: req.method, headers, upgrade,
      })) queueMicrotask(() => wire.destroy(new Error('Viewer connection closed')))
    } catch { queueMicrotask(() => wire.destroy(new Error('Invalid viewer request'))) }
    return wire
  }

  private responseHeaders(gateway: Gateway, raw: unknown, upgrade = false): ReturnType<typeof viewerHeaders> {
    const headers = viewerHeaders(raw, upgrade)
    if (typeof headers.location === 'string') {
      const location = new URL(headers.location, gateway.target)
      if (location.origin === gateway.target.origin) headers.location = gateway.origin + location.pathname + location.search + location.hash
    }
    if (headers['set-cookie']) {
      const values = headers['set-cookie']
      headers['set-cookie'] = (Array.isArray(values) ? values : [values]).map((value) =>
        `${gateway.cookie}_${value.replace(/;\s*Domain=[^;]*/ig, '')}`)
    }
    headers['referrer-policy'] = 'no-referrer'
    return headers
  }

  private closeGateway(gateway: Gateway): void {
    for (const wire of gateway.wires) wire.destroy()
    for (const socket of gateway.sockets) socket.destroy()
    gateway.server.close()
  }

  private remove(agentId: string): void {
    const gateway = this.gateways.get(agentId)
    this.gateways.delete(agentId)
    if (gateway) this.closeGateway(gateway)
  }

  /** Detach closes all access immediately, even though the terminal relay pool lingers. */
  reset(): void {
    this.generation++
    for (const id of this.gateways.keys()) this.remove(id)
  }

  close(): void { this.disposed = true; this.reset() }
}

function isLoopbackUrl(raw: unknown): boolean {
  try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(String(raw)).hostname) } catch { return false }
}

function frameWithViewerError(frame: Frame): Frame {
  const p = frame.payload as Record<string, unknown> | undefined
  if (!p) return frame
  const failed = (a: unknown): unknown => a && typeof a === 'object' && isLoopbackUrl((a as Record<string, unknown>).viewerUrl)
    ? { ...a, viewerUrl: null, viewerError: 'The remote viewer could not be opened. Reconnect to try again.' } : a
  return { ...frame, payload: { ...p, ...(p.agent ? { agent: failed(p.agent) } : {}), ...(Array.isArray(p.agents) ? { agents: p.agents.map(failed) } : {}) } }
}