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.

10.8 KB
Raw Blame
/**
 * How a client on this computer reaches the daemon. On macOS and Linux that is the daemon's Unix socket, 0600 in a 0700
 * folder, and only that: any account can bind the TCP port while the daemon restarts (a Team agent, audit H1), and would
 * hear what is sent to it, which is the local credential and also the request itself: a message, a file. With the
 * socket gone the daemon is down, and the client says so. TCP remains where a socket cannot exist, a data folder whose
 * path is too long for one. On Windows it is the daemon's pipe, and only that: the Team account's daemon starts at boot,
 * before the owner's, and can hold the port from then on (audit W1, docs/security/2026-11-02-team-account-windows.md).
 * Reaching the pipe is no trust there, so every request proves the daemon's token and takes only an answer that proves
 * it back (lib/windows/pipeAuth.ts).
 *
 * The folder's mode is the guarantee here, as for every client of this socket (lib/localSocket.ts): nobody else can
 * have put a socket in it.
 */
import { existsSync, lstatSync, readdirSync } from 'node:fs'
import { request } from 'node:http'
import { dirname, join } from 'node:path'
import { Readable } from 'node:stream'
import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
import { configuredPortOf, readDaemonRecord } from './daemonRecord.js'
import { localCredentialHeaders } from './localCredential.js'
import { unixSocketPath } from './localSocket.js'
import { NOT_RUNNING } from './unreachable.js'
import { daemonPipe } from './windows/daemonPipe.js'
import { newPipeNonce, PIPE_AUTH_HEADER, pipeAuthValue, pipeProven, readDaemonToken } from './windows/pipeAuth.js'
import { pipeWebSocket, PipeUnproven, type PipeTarget } from './windows/pipeClient.js'

const LOCAL_WS_PATH = '/api/local-ws'

/**
 * The daemon's socket for [port], or null where it has none. A socket is named for the port the daemon was configured
 * with; [port] may be the one it was given instead, when another account held that one, so its records say which.
 * With neither there, the expected path: connecting to it fails as a daemon that is down does.
 */
export function localSocketRoute(dataDir: string, port: number, platform: NodeJS.Platform = process.platform): string | null {
  const expected = unixSocketPath(dataDir, port, platform)
  // A data folder's own mode covers its socket; a short folder's lies elsewhere, so it is checked, and one that isn't private is refused as
  // a daemon that is down is: connecting to this name fails.
  const checked = (socket: string): string => !socket.startsWith(dataDir) && !socketIsPrivate(socket) ? `${socket}.not-private` : socket
  if (!expected) return expected
  if (existsSync(expected)) return checked(expected)
  let names: string[] = []
  try { names = readdirSync(dataDir) } catch { return expected }
  for (const name of names) {
    const configured = /^daemon-(\d+)\.json$/.exec(name)?.[1]
    if (!configured || readDaemonRecord(dataDir, Number(configured), platform)?.port !== port) continue
    const socket = unixSocketPath(dataDir, Number(configured), platform)
    if (socket && existsSync(socket)) return checked(socket)
  }
  return expected
}

/** Where a WebSocket to the daemon goes, and the headers it carries: none over the socket. */
export function localWsTarget(dataDir: string, port: number, platform: NodeJS.Platform = process.platform): { url: string; headers: Record<string, string> } {
  const socket = localSocketRoute(dataDir, port, platform)
  if (socket) return { url: `ws+unix://${socket}:${LOCAL_WS_PATH}`, headers: {} }
  return { url: `ws://127.0.0.1:${readDaemonRecord(dataDir, port, platform)?.port ?? port}${LOCAL_WS_PATH}`, headers: localCredentialHeaders(dataDir, platform) }
}

/**
 * One request over the socket, or the Windows pipe of [pipe], answered as `fetch` answers. The body is whole first: these
 * are JSON and forms up to 10 MB. Over the pipe it carries a fresh auth, and an answer without the daemon's proof is
 * refused before its body is read (lib/windows/pipeClient.ts `pipeRequest`).
 */
async function overSocket(socketPath: string, input: Request, pipe?: PipeTarget): Promise<Response> {
  const url = new URL(input.url)
  const body = input.body ? Buffer.from(await input.arrayBuffer()) : null
  const headers = Object.fromEntries(input.headers)
  if (body) headers['content-length'] = String(body.length)
  const nonce = pipe ? newPipeNonce(pipe.pipe) : null
  if (pipe && nonce) headers[PIPE_AUTH_HEADER] = pipeAuthValue(pipe.token, nonce)
  return new Promise((resolve, reject) => {
    const req = request({ socketPath, method: input.method, path: `${url.pathname}${url.search}`, headers, signal: input.signal }, (res) => {
      if (pipe && nonce && !pipeProven(res.headers, pipe.token, nonce)) {
        reject(new PipeUnproven(pipe.pipe))
        res.destroy()
        req.destroy()
        return
      }
      const answer = new Headers()
      for (const [name, value] of Object.entries(res.headers)) {
        if (value !== undefined) answer.set(name, Array.isArray(value) ? value.join(', ') : value)
      }
      const status = res.statusCode ?? 502
      // A Response may have no body with these (and refuses one).
      if ([101, 204, 205, 304].includes(status)) { res.resume(); resolve(new Response(null, { status, headers: answer })); return }
      resolve(new Response(Readable.toWeb(res) as NodeReadableStream as ReadableStream, { status, headers: answer }))
    })
    // As fetch fails: a TypeError with the reason as its cause, which the callers' "is it running" texts read.
    req.on('error', (error) => { reject(input.signal.aborted ? error : Object.assign(new TypeError('fetch failed'), { cause: error })) })
    // A write the socket finishes after the answer was refused and the request destroyed fails with EPIPE on Linux, when
    // nothing listens on the socket any more: the request has settled by then (Linux CI on #2605).
    req.on('socket', (socket) => { socket.on('error', () => {}) })
    req.end(body ?? undefined)
  })
}

/** What `fetch` throws for a daemon that is not there: the callers' "is it running" texts read its cause. */
export function notThere(): TypeError {
  return Object.assign(new TypeError('fetch failed'), { cause: Object.assign(new Error('connect ECONNREFUSED: no Harness pipe'), { code: 'ECONNREFUSED' }) })
}

/** Whether [path] is what the daemon makes: a socket of this account's, owner only, in a real folder nobody else can write to. */
export function socketIsPrivate(path: string): boolean {
  const uid = process.getuid?.()
  try {
    const folder = lstatSync(dirname(path)), file = lstatSync(path)
    return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0
      && (uid === undefined || (folder.uid === uid && file.uid === uid))
  } catch { return false }
}

/** `fetch` that sends every request over the private Unix socket at [socketPath], whatever host its address names, and fails as `fetch` does
 *  when the socket is missing or not private: what is sent can carry a key. */
export function fetchOverSocket(socketPath: string): typeof fetch {
  return async (input, init) => {
    if (!socketIsPrivate(socketPath)) throw new TypeError('fetch failed', { cause: new Error('The socket is missing or not private.') })
    return overSocket(socketPath, new Request(input, init))
  }
}

/** `fetch` that sends every request over the pipe [target] names at the time, whatever host its address names: it proves the pipe's
 *  token and takes only an answer that proves it back. With no pipe it fails as `fetch` does for a daemon that is not there. */
export function fetchOverPipe(target: () => PipeTarget | null): typeof fetch {
  return async (input, init) => {
    const pipe = target()
    if (!pipe) throw notThere()
    return overSocket(pipe.pipe, new Request(input, init), pipe)
  }
}

/**
 * `fetch` for the daemon on [port] of [dataDir]: a request to its loopback address goes over its socket where it can
 * have one, and on Windows over its pipe ([pipe], `daemonPipe` by default) or nowhere. Any other address, such as a
 * storage link, is the ordinary [base].
 */
export function daemonFetch(
  dataDir: string, port: number, base: typeof fetch = fetch, platform: NodeJS.Platform = process.platform,
  pipe: (dataDir: string, configuredPort: number) => Promise<PipeTarget | null> = daemonPipe,
): typeof fetch {
  return async (input, init) => {
    const url = new URL(input instanceof Request ? input.url : String(input))
    const saved = readDaemonRecord(dataDir, configuredPortOf(dataDir, port, platform), platform)?.port
    const daemon = url.hostname === '127.0.0.1' && (Number(url.port) === port || Number(url.port) === saved)
    if (daemon && platform === 'win32') {
      const target = await pipe(dataDir, port)
      if (!target) throw notThere()
      return overSocket(target.pipe, new Request(input, init), target)
    }
    const socket = daemon ? localSocketRoute(dataDir, port, platform) : null
    return socket ? overSocket(socket, new Request(input, init)) : base(input, init)
  }
}

/**
 * Whether this account's process [pid] runs. The daemon is this account's, so EPERM is another account's process, one
 * that took the pid since the daemon exited (processProof.ts `pidAlive` counts it alive): not the daemon.
 */
function ownProcessRuns(pid: number): boolean {
  try {
    process.kill(pid, 0)
    return true
  } catch {
    return false
  }
}

/**
 * The daemon's pipe for a client that opens its WebSocket at once (`openLocalWs`): the recorded pipe while the recorded
 * daemon runs, and its token. Not the process table `daemonPipe` also reads: the socket's upgrade must prove the token
 * (`pipeWebSocket`), so a squatter is refused before any frame is sent to it.
 */
export function daemonPipeNow(dataDir: string, port: number): PipeTarget | null {
  const record = readDaemonRecord(dataDir, configuredPortOf(dataDir, port))
  if (!record?.pipe || !record.pid || !ownProcessRuns(record.pid)) return null
  const token = readDaemonToken(dataDir)
  return token ? { pipe: record.pipe, token } : null
}

/**
 * A WebSocket to the daemon on [port] of [dataDir]: [connect] to its socket (or, for a data folder too long to hold one,
 * its port) on macOS and Linux, and on Windows its pipe ([pipe], `daemonPipeNow` by default), never the port. With no
 * pipe there it throws that Harness is not running.
 */
export function openLocalWs<S>(
  dataDir: string, port: number, connect: (url: string, headers: Record<string, string>) => S,
  platform: NodeJS.Platform = process.platform, pipe: (dataDir: string, port: number) => PipeTarget | null = daemonPipeNow,
): S {
  if (platform !== 'win32') {
    const target = localWsTarget(dataDir, port, platform)
    return connect(target.url, target.headers)
  }
  const target = pipe(dataDir, port)
  if (!target) throw new Error(NOT_RUNNING)
  return pipeWebSocket(target) as unknown as S
}