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.

16.0 KB
Raw Blame
/**
 * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any
 * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket
 * gone the daemon is down, and the caller says so. On Windows it goes over the daemon's named pipe, proving the daemon's token, and
 * never to the port: the Team account's daemon starts at boot, before the owner's, and could hold it (audit W1,
 * docs/security/2026-11-02-team-account-windows.md). TCP remains only for a home too long to hold a socket.
 *
 * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies
 * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.
 */
import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
import { closeSync, fstatSync, lstatSync, openSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
import { request } from 'node:http'
import { homedir } from 'node:os'
import { join, win32 } from 'node:path'

/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */
const MAX_SOCKET_PATH_BYTES = 96
const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
/** Far above any answer a package reads: it only stops a runaway peer. */
const MAX_MESSAGE_BYTES = 64 * 1024 * 1024
const CLOSE_WAIT_MS = 2000

export function daemonDataDir(env = process.env) {
  return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')
}

/**
 * The daemon's socket for `port`: in its data folder, or where that path is too long for a socket, in a 0700 folder under the home folder
 * named by the folder's hash (the CLI's `socketPathIn`). Null where it can have none: Windows, or a home too long as well.
 */
export function daemonSocketPath(port, env = process.env, platform = process.platform) {
  if (platform === 'win32') return null
  const folder = daemonDataDir(env), name = `daemon-${port}.sock`, beside = join(folder, name)
  if (Buffer.byteLength(beside) <= MAX_SOCKET_PATH_BYTES) return beside
  const hash = createHash('sha256').update(folder).digest('hex').slice(0, 16)
  const short = join(env.HOME || homedir(), '.harness', 's', hash, name)
  return Buffer.byteLength(short) <= MAX_SOCKET_PATH_BYTES ? short : null
}

/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */
export function socketIsPrivate(path) {
  const uid = process.getuid?.()
  try {
    const folder = lstatSync(join(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
  }
}

/** Mirrors LOCAL_PIPE_RE in cli/src/lib/windows/pipeAuth.ts: a pipe on this computer named harness-<id>, nothing else. A file, or
 *  another computer's pipe (an SMB connection that can carry this user's NTLM credentials), is none. */
const LOCAL_PIPE_RE = /^\\\\\.\\pipe\\harness-([0-9a-f]{32})$/
/** Mirrors TOKEN_TEXT in cli/src/lib/windows/pipeAuth.ts. */
const DAEMON_TOKEN_RE = /^[0-9a-f]{64}\n?$/

export const HARNESS_NOT_RUNNING = 'Harness is not running on this computer. Start it with: harness start'
const PIPE_UNPROVEN = 'Something other than Harness answered on its local pipe. Restart Harness: harness stop && harness start'

/**
 * A state file of the daemon's on Windows, as cli/hook/notify.mjs `readWindowsStateFile` reads it. NTFS gives Node no owner or mode
 * bits, so the profile's ACL is the protection: the file must be a plain file, not a link or junction, whose real path lies inside
 * the profile or the data folder, and the file opened must be the one lstat saw. '' when it is refused; throws when there is none.
 */
function windowsStateFile(dataDir, name, maxBytes) {
  const file = join(dataDir, name)
  const roots = [homedir(), dataDir].flatMap((root) => { try { return [realpathSync.native(root)] } catch { return [] } })
  const inside = (target) => roots.some((root) => {
    const rel = win32.relative(root, target)
    return rel === '' || (rel !== '..' && !rel.startsWith('..\\') && !win32.isAbsolute(rel))
  })
  const link = lstatSync(file, { bigint: true })
  if (!link.isFile() || link.size > BigInt(maxBytes) || !inside(realpathSync.native(file))) return ''
  const fd = openSync(file, 'r')
  try {
    const opened = fstatSync(fd, { bigint: true })
    return opened.isFile() && opened.dev === link.dev && opened.ino === link.ino ? readFileSync(fd, 'utf8') : ''
  } finally {
    closeSync(fd)
  }
}

/**
 * The record's daemon still runs. Once it is gone any account can create a pipe of the recorded name, and would hear the request
 * before its answer can fail the proof. The daemon is this account's, so a pid that answers EPERM is another account's process now.
 */
function pidRuns(pid) {
  try { process.kill(pid, 0); return true } catch { return false }
}

/**
 * The daemon's pipe for `port` on Windows, as the CLI and its hook find it (cli/hook/notify.mjs `windowsDaemonPipe`): the record the
 * core writes, `daemon-<configured port>.json`, names the pipe and the core's pid, both new on each start; `port` may be the one the
 * daemon bound instead, so the records say which. One request's route: the pipe, its auth for a fresh nonce, and the check of the
 * daemon's proof (cli/src/lib/windows/pipeAuth.ts). The token never travels. Null off Windows, or with no record of a local pipe, no
 * token, or a core that has exited: then there is nothing to dial, and the port is never the way instead.
 */
export function daemonPipe(port, env = process.env, platform = process.platform) {
  if (platform !== 'win32') return null
  const dataDir = daemonDataDir(env)
  const read = (name) => { try { return JSON.parse(windowsStateFile(dataDir, name, 4096)) } catch { return null } }
  let record = read(`daemon-${port}.json`)
  if (!record) {
    try {
      for (const name of readdirSync(dataDir)) {
        if (!/^daemon-\d+\.json$/.test(name)) continue
        const candidate = read(name)
        if (candidate?.port === port) { record = candidate; break }
      }
    } catch { /* An unreadable folder has no record to offer. */ }
  }
  const id = typeof record?.pipe === 'string' ? LOCAL_PIPE_RE.exec(record.pipe)?.[1] : null
  if (!id || !Number.isSafeInteger(record.pid) || record.pid <= 0 || !pidRuns(record.pid)) return null
  let text = ''
  try { text = windowsStateFile(dataDir, 'daemon-token', 128) } catch { return null }
  if (!DAEMON_TOKEN_RE.test(text)) return null
  const token = Buffer.from(text.slice(0, 64), 'hex')
  const nonce = id + randomBytes(16).toString('hex')
  const mac = (separator) => createHmac('sha256', token).update(Buffer.of(separator)).update(nonce, 'utf8').digest('hex')
  const proof = Buffer.from(mac(0x00), 'hex')
  return {
    path: record.pipe,
    headers: { 'X-Harness-Auth': `${nonce}.${mac(0x01)}` },
    proven: (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value) && timingSafeEqual(Buffer.from(value, 'hex'), proof),
  }
}

/** How a request reaches the daemon here: its pipe on Windows, its private socket elsewhere; null when there is neither to use. */
function localRoute(port, env) {
  if (process.platform === 'win32') return daemonPipe(port, env)
  const path = daemonSocketPath(port, env)
  return path && socketIsPrivate(path) ? { path, headers: {}, proven: null } : null
}

const routeMissing = () => new Error(process.platform === 'win32' ? HARNESS_NOT_RUNNING : 'The Harness socket is missing or not private.')

const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)

/** One client frame: clients mask (RFC 6455 5.3). */
function frame(opcode, payload) {
  const size = payload.length
  const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])
    : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])
    : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])
  const mask = randomBytes(4), masked = Buffer.from(payload)
  for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]
  return Buffer.concat([head, mask, masked])
}

class SocketEvent extends Event {
  constructor(type, fields) { super(type); Object.assign(this, fields) }
}

/** The WebSocket client these packages use, over the daemon's socket or pipe: open, message (text), error, close, send, close. */
class LocalWebSocket extends EventTarget {
  static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3
  readyState = 0
  #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null

  /** `route` is localRoute's: null is no daemon to dial. */
  constructor(route, resource) {
    super()
    // Told after this returns, as a WebSocket always is: the caller adds its listeners first.
    if (!route) { const error = routeMissing(); queueMicrotask(() => this.#end(1006, error)); return }
    const key = randomBytes(16).toString('base64')
    const asked = this.#asked = request({ socketPath: route.path, path: resource,
      headers: { ...route.headers, Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })
    asked.on('error', (error) => this.#end(1006, error))
    asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })
    asked.on('upgrade', (answer, stream, head) => {
      // Given up on while it was on its way: the caller has been told, so it never comes back to life.
      if (this.#closed) { stream.destroy(); return }
      // A pipe's name can be taken by any account once its daemon is gone: an upgrade without the daemon's proof never opens,
      // so a caller that sends its first frame on `open` sends it nothing.
      if (route.proven && !route.proven(answer.headers['x-harness-proof'])) { stream.destroy(); this.#end(1006, new Error(PIPE_UNPROVEN)); return }
      const accept = createHash('sha1').update(key + WS_GUID).digest('base64')
      if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }
      this.#stream = stream
      this.readyState = 1
      stream.on('data', (chunk) => this.#read(chunk))
      stream.on('error', (error) => this.#end(1006, error))
      stream.on('close', () => this.#end(1006))
      this.dispatchEvent(new SocketEvent('open'))
      if (head.length) this.#read(head)
    })
    asked.end()
  }

  send(text) {
    if (this.readyState !== 1) throw new Error('The Harness connection is not open.')
    this.#stream.write(frame(1, Buffer.from(String(text))))
  }

  close(code = 1000) {
    if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }
    this.readyState = 2
    const body = Buffer.alloc(2); body.writeUInt16BE(code)
    this.#stream.write(frame(8, body))
    // A peer that never answers must not hold this process.
    this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)
    this.#timer.unref?.()
  }

  #end(code, error) {
    if (this.#closed) return
    this.#closed = true
    this.readyState = 3
    clearTimeout(this.#timer)
    // A request still waiting holds the process and could open after the caller was told it failed.
    this.#asked?.destroy()
    this.#stream?.destroy()
    if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))
    this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))
  }

  #read(chunk) {
    this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk
    while (!this.#closed) {
      const taken = this.#next()
      if (taken === 0) return
      this.#held = this.#held.subarray(taken)
    }
  }

  /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */
  #next() {
    const held = this.#held
    if (held.length < 2) return 0
    const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f
    // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).
    if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }
    const start = short === 126 ? 4 : short === 127 ? 10 : 2
    if (held.length < start) return 0
    const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)
    if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }
    const size = Number(big)
    if (held.length < start + size) return 0
    const payload = held.subarray(start, start + size)
    if (opcode === 9) this.#stream.write(frame(10, payload))
    else if (opcode === 8) {
      const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005
      if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }
      this.#end(code)
    } else if (opcode === 0 || opcode === 1 || opcode === 2) {
      this.#size += size
      if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }
      this.#parts.push(Buffer.from(payload))
      if (fin) {
        const data = Buffer.concat(this.#parts)
        this.#parts = []; this.#size = 0
        this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))
      }
    }
    return start + size
  }

  #fail(code) {
    const body = Buffer.alloc(2); body.writeUInt16BE(code)
    this.#stream.write(frame(8, body))
    this.#end(code)
  }
}

/**
 * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be
 * and over the pipe on Windows. Only a home too long to hold a socket gets Node's own WebSocket on `url`, with the headers given.
 */
export class DaemonWebSocket {
  constructor(url, { headers = {}, env = process.env } = {}) {
    const parsed = new URL(url), port = portOf(parsed)
    if (process.platform !== 'win32' && !daemonSocketPath(port, env)) return new globalThis.WebSocket(url, { headers })
    return new LocalWebSocket(localRoute(port, env), parsed.pathname)
  }
}

/**
 * `fetch` for the daemon's REST API at `url`, over its socket where one can be and over its pipe on Windows, where an answer is taken
 * only with the daemon's proof. Answers `status`, `ok`, `json()` and `text()`.
 */
export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {
  const parsed = new URL(url), port = portOf(parsed)
  if (process.platform !== 'win32' && !daemonSocketPath(port, env)) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })
  return new Promise((resolve, reject) => {
    const route = localRoute(port, env)
    if (!route) { reject(routeMissing()); return }
    const payload = body === undefined ? null : Buffer.from(body)
    const asked = request({ socketPath: route.path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),
      headers: { ...headers, ...route.headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {
      // Before the body is read: an answer on the pipe without the daemon's proof is whatever took its name (cli pipeClient.ts).
      if (route.proven && !route.proven(answer.headers['x-harness-proof'])) { reject(new Error(PIPE_UNPROVEN)); asked.destroy(); return }
      const parts = []
      answer.on('data', (part) => parts.push(part))
      answer.on('error', reject)
      answer.on('end', () => {
        const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502
        resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })
      })
    })
    // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.
    asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))
    asked.end(payload ?? undefined)
  })
}