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.

19.8 KB
Raw Blame
/**
 * Whether the process at the other end of a loopback TCP connection runs as this OS account.
 *
 * Any account can bind a free loopback port, so while the daemon or the bridge restarts another account (a Team
 * agent) can sit on its port and hear what clients send (audit H1, docs/security/2026-11-02-team-account-boundary.md).
 * A client that can only speak HTTP to a fixed address cannot avoid that: an MCP client's address carries its key, and
 * older clients send the local credential. So a secret heard must open nothing: the listeners also ask who is calling.
 *
 * Asked only after the secret matched, so a stranger cannot make the daemon spawn anything, and once per connection.
 * A lookup that fails answers no: this guards a credential, and a client refused can say so and retry.
 */
import { execFile } from 'node:child_process'
import { readFile } from 'node:fs/promises'
import type { Socket } from 'node:net'
import { patientExec, type ExecDone, type PatientExecOptions } from './patientExec.js'
import { ptyHostBinary } from './ptyHost/launch.js'
import { runPowershellAsync } from './windows/powershell.js'

export type PeerAccount = (socket: Socket) => Promise<boolean>

const LSOF_MS = 3_000

/** Linux: the row of /proc/net/tcp whose local end is the peer's and whose remote end is ours, and that row's uid. */
export function procNetOwner(table: string, peerPort: number, ownPort: number): number | null {
  const hex = (port: number) => port.toString(16).toUpperCase().padStart(4, '0')
  for (const line of table.split('\n').slice(1)) {
    const fields = line.trim().split(/\s+/)
    if (fields[1] === `0100007F:${hex(peerPort)}` && fields[2] === `0100007F:${hex(ownPort)}`) {
      const uid = Number(fields[7])
      return Number.isInteger(uid) ? uid : null
    }
  }
  return null
}

/**
 * macOS: whether `lsof -Fn` shows the client's end of the connection among this account's sockets. The daemon's own
 * end names the same two ports the other way round (`own->peer`), so only a line starting at the peer's port counts.
 */
export function lsofShowsPeer(output: string, peerPort: number, ownPort: number): boolean {
  return output.split('\n').some(line => /^n127\.0\.0\.1:(\d+)->127\.0\.0\.1:(\d+)$/.exec(line)?.slice(1).join() === `${peerPort},${ownPort}`)
}

function lsof(peerPort: number, ownPort: number, uid: number): Promise<boolean> {
  return new Promise((resolve) => {
    execFile('/usr/sbin/lsof', ['-nP', '-a', '-u', String(uid), `[email protected]:${peerPort}`, '-Fn'], { timeout: LSOF_MS }, (error, stdout) => {
      // lsof exits 1 when it found nothing: that is an answer, and its empty output says no.
      if (error && typeof error.code !== 'number') console.warn(`[peer] could not ask lsof who is calling: ${error.message}`)
      resolve(lsofShowsPeer(stdout ?? '', peerPort, ownPort))
    })
  })
}

async function ask(socket: Socket, platform: NodeJS.Platform): Promise<boolean> {
  const peerPort = socket.remotePort, ownPort = socket.localPort
  const uid = process.getuid?.()
  if (uid === undefined || !peerPort || !ownPort) return false
  // Both lookups below name 127.0.0.1 at both ends, which is what a client dialling this listener uses. All of 127/8 is
  // loopback, so another account can call from 127.0.0.2 on the same port number as a connection of this account's, and
  // would be read as that connection. Only an exact pair of addresses makes the pair of ports name one connection.
  if (socket.remoteAddress !== '127.0.0.1' || socket.localAddress !== '127.0.0.1') return false
  if (platform === 'linux') {
    try { return procNetOwner(await readFile('/proc/net/tcp', 'utf8'), peerPort, ownPort) === uid } catch { return false }
  }
  return lsof(peerPort, ownPort, uid)
}

/**
 * The addresses of a listener that keeps 127.0.0.1's port from being bound: 127.0.0.1 and any address, and for IPv6 the
 * same mapped, `::` and `::1`. Node's plain `listen(port)` is on `::`, dual-stack, and shows only in /proc/net/tcp6.
 */
const LISTENER_ADDRESSES = ['0100007F', '00000000', '00000000000000000000000000000000', '00000000000000000000000001000000',
  '0000000000000000FFFF00000100007F', '0000000000000000FFFF000000000000']

/** Linux: the owner of the listener on loopback [port] in /proc/net/tcp and tcp6's text, or null when none is listening. */
export function procNetListener(table: string, port: number): number | null {
  const hex = port.toString(16).toUpperCase().padStart(4, '0')
  const holds = new Set(LISTENER_ADDRESSES.map(address => `${address}:${hex}`))
  for (const line of table.split('\n')) {
    const fields = line.trim().split(/\s+/)
    if (fields[3] === '0A' && holds.has(fields[1] ?? '')) {
      const uid = Number(fields[7])
      return Number.isInteger(uid) ? uid : null
    }
  }
  return null
}

/**
 * Whether the process listening on loopback [port] runs as this account: null when that cannot be said (a listener gone
 * by now, a lookup that failed). macOS shows an account only its own sockets, so a port that is taken but not among them
 * is another account's. Windows is asked ([windowsListenerQuery], [run]): it answered null until task #2162, so the
 * connectors bridge never moved off a port the Team account held from boot (Reed's review of #2605).
 */
export async function portHolderIsThisAccount(port: number, platform: NodeJS.Platform = process.platform, run: WindowsPeerRun = runWindowsPeer): Promise<boolean | null> {
  if (platform === 'win32') return askWindowsListener(port, run)
  const uid = process.getuid?.()
  if (uid === undefined) return null
  if (platform === 'linux') {
    // A kernel with no IPv6 has no tcp6, and /proc/net/tcp alone says who holds the port then.
    const tables = await Promise.all(['/proc/net/tcp', '/proc/net/tcp6'].map(file => readFile(file, 'utf8').catch(() => '')))
    const owner = procNetListener(tables.join('\n'), port)
    return owner === null ? null : owner === uid
  }
  return new Promise((resolve) => {
    execFile('/usr/sbin/lsof', ['-nP', '-a', '-u', String(uid), `-iTCP:${port}`, '-sTCP:LISTEN', '-Fn'], { timeout: LSOF_MS }, (error, stdout) => {
      if (error && typeof error.code !== 'number') { resolve(null); return }
      resolve(/^n/m.test(stdout ?? ''))
    })
  })
}

/**
 * Windows PowerShell's start and its CIM queries: about a second on x64, 20 to 25 s on the Windows ARM runner (the
 * Windows runs on #2605), so a slow or busy PC is given 45 s. A lookup past that is no for its connection. It runs only
 * for a host too old to answer (see [nativeFirst]).
 */
export const WINDOWS_PEER_MS = 45_000

/** How the daemon asks: the script is [windowsPeerQuery]'s, for PowerShell, and its inputs name the connection. Tests give their own. */
export type WindowsPeerRun = (script: string, inputs: Record<string, string>) => Promise<{ status: number | null; stdout: string }>

/**
 * `harness-pty peer-account` takes milliseconds (#2187). A helper that takes this long is hung: its connection is refused,
 * and the client can retry. Far more than the second the real Windows run allows, for a PC under load.
 */
export const WINDOWS_PEER_NATIVE_MS = 5_000

/** The helper's exit and output, or `missing` when there is no file to run. */
export type WindowsNativeRun = (inputs: Record<string, string>) => Promise<{ status: number | null; stdout: string } | 'missing'>
type NativeExec = (file: string, args: readonly string[], options: PatientExecOptions, done: ExecDone) => void
const nativeExec: NativeExec = patientExec(execFile)

/** Runs the helper for [inputs], the connection [windowsPeerQuery] names. A file that is there and will not run is a failed lookup, not a missing one. */
export function runWindowsNative(inputs: Record<string, string>, binary: () => string | null = ptyHostBinary, exec: NativeExec = nativeExec): ReturnType<WindowsNativeRun> {
  let file: string | null
  try {
    file = binary()
  } catch {
    file = null
  }
  if (!file) return Promise.resolve('missing')
  const args = ['peer-account', '--peer-port', inputs.HARNESS_PEER_PORT!, '--own-port', inputs.HARNESS_OWN_PORT!, '--daemon-pid', inputs.HARNESS_DAEMON_PID!]
  return new Promise((resolve) => {
    exec(file, args, { timeout: WINDOWS_PEER_NATIVE_MS, maxBuffer: 64 * 1024, windowsHide: true }, (error, stdout) => {
      const code = error ? error.code : 0
      if (code === 'ENOENT') resolve('missing')
      else if (code === 'ETIMEDOUT') resolve({ status: null, stdout: '' })
      else resolve({ status: typeof code === 'number' ? code : 1, stdout })
    })
  })
}

/**
 * Asks the helper, and PowerShell only when the helper cannot be asked: it is missing, or a host older than this CLI says
 * 2 for a command it does not know (or 3, unsupported). Its yes and no are final, and so is a hang or a crash: PowerShell
 * after a no would be a second chance for a caller the helper refused, and after a hang 45 s more for each connection.
 */
export function nativeFirst(native: WindowsNativeRun, powershell: WindowsPeerRun): WindowsPeerRun {
  let told = false
  return async (script, inputs) => {
    // The helper answers only who owns a connection. Another query through this default, as the listener check of #2608, has
    // its own script and rules: run with no ports, the helper could say nothing, and that check would go quiet.
    if (inputs.HARNESS_PEER_PORT === undefined) return powershell(script, inputs)
    const answer = await native(inputs)
    if (answer !== 'missing' && answer.status !== 2 && answer.status !== 3) return answer
    if (!told) {
      told = true
      console.warn('[peer] harness-pty cannot say who is calling (missing or too old): asking PowerShell, which is far slower')
    }
    return powershell(script, inputs)
  }
}

const runWindowsPeer: WindowsPeerRun = nativeFirst(runWindowsNative, (script, inputs) => runPowershellAsync(script, inputs, WINDOWS_PEER_MS))

/**
 * Windows: whether the client end of the connection 127.0.0.1:[peerPort] → 127.0.0.1:[ownPort] belongs to a process of
 * this account. Prints `yes`, or `no: <why>` for the daemon's log. Windows lists the client's end with its own port as the local one. The owner is
 * compared by SID, never by name; a process of another account, one whose owner Windows will not give, one gone, one
 * that started after the connection was made (an id reused since its creator exited), or more than one row (which cannot
 * be told apart) is `no`. The ports are inputs, never in the script's text.
 */
export function windowsPeerQuery(peerPort: number, ownPort: number, daemonPid: number = process.pid): { script: string; inputs: Record<string, string> } {
  return {
    script: [
      '$rows = @(Get-NetTCPConnection -State Established -LocalAddress 127.0.0.1 -LocalPort ([int]$env:HARNESS_PEER_PORT) -RemoteAddress 127.0.0.1 -RemotePort ([int]$env:HARNESS_OWN_PORT) -ErrorAction SilentlyContinue)',
      "if ($rows.Count -ne 1) { 'no: ' + $rows.Count + ' connections match'; exit 0 }",
      '$process = Get-CimInstance Win32_Process -Filter ("ProcessId = " + [int]$rows[0].OwningProcess)',
      "if (-not $process) { 'no: its process is gone'; exit 0 }",
      // The lookup's own process is never the caller: it could have taken a freed id.
      "if ($rows[0].OwningProcess -eq $PID) { 'no: the lookup itself owns it'; exit 0 }",
      // Windows keeps naming a socket's creator after it exits when a child inherited the handle, and the id may have gone
      // to another process since: only one that started before the connection was made can be its owner. Windows gives the
      // connection's time to the second and the process's finer (the Windows run on #2605 read a process started at
      // 13:32:35 as after its connection of 13:32:35), so the process's time is cut to the second and compared with no
      // slack. Slack let the lookup's own PowerShell, started just after, take the freed id and pass (Remy's review). A
      // reuse within the connection's own second stays open here; the native lookup compares finer where Windows gives it.
      "if (-not $process.CreationDate -or -not $rows[0].CreationTime) { 'no: Windows gave no start time'; exit 0 }",
      '$started = $process.CreationDate.AddTicks(-($process.CreationDate.Ticks % [TimeSpan]::TicksPerSecond))',
      "if ($started -gt $rows[0].CreationTime) { 'no: its process started ' + $process.CreationDate.ToString('o') + ', the connection ' + $rows[0].CreationTime.ToString('o'); exit 0 }",
      // Nor another lookup running at once: a PowerShell the daemon started, the helper that ran before it, or a console
      // host of either, started in the connection's second, could have taken the freed id (Remy's review of #2605). Nothing
      // of that kind the daemon starts calls its port with a secret.
      '$daemon = [int]$env:HARNESS_DAEMON_PID',
      "if ($process.Name -match '^(powershell|conhost|harness-pty)\\.exe$') {",
      "  if ($process.ParentProcessId -eq $daemon) { 'no: a ' + $process.Name + ' the daemon started owns it'; exit 0 }",
      '  $parent = Get-CimInstance Win32_Process -Filter ("ProcessId = " + [int]$process.ParentProcessId)',
      "  if ($parent -and $parent.ParentProcessId -eq $daemon) { 'no: a ' + $process.Name + ' the daemon started owns it'; exit 0 }",
      '}',
      '$owner = Invoke-CimMethod -InputObject $process -MethodName GetOwnerSid',
      "if ($owner.ReturnValue -eq 0 -and $owner.Sid -and $owner.Sid -eq [Security.Principal.WindowsIdentity]::GetCurrent().User.Value) { 'yes' } else { 'no: its owner is ' + $owner.Sid + ' (' + $owner.ReturnValue + ')' }",
    ].join('\n'),
    inputs: { HARNESS_PEER_PORT: String(peerPort), HARNESS_OWN_PORT: String(ownPort), HARNESS_DAEMON_PID: String(daemonPid) },
  }
}

/**
 * Windows: whose the listeners on loopback [port] are, of those that hold 127.0.0.1's port (on it, on any IPv4 address, or
 * dual-stack on any address). Prints `none` when nothing listens there, `yes` when one of them belongs
 * to a process of this account (a second daemon or a handover of its own, which the bridge waits out), and `no` otherwise.
 * As in [windowsPeerQuery], the owner is compared by SID, and a process that started after its listener was made (an id
 * reused since its creator exited) or one gone is not this account's: the answer that moves the bridge is the safe one.
 * The port is an input, never in the script's text.
 */
export function windowsListenerQuery(port: number): { script: string; inputs: Record<string, string> } {
  return {
    script: [
      // Only these keep 127.0.0.1's port from being bound; this account's listener on ::1 or 127.0.0.2 must not keep the bridge
      // waiting on another account's 127.0.0.1 (Quinn 2's review of #2608).
      "$rows = @(Get-NetTCPConnection -State Listen -LocalPort ([int]$env:HARNESS_LISTEN_PORT) -ErrorAction SilentlyContinue | Where-Object { $_.LocalAddress -in @('127.0.0.1', '0.0.0.0', '::') })",
      "if ($rows.Count -eq 0) { 'none'; exit 0 }",
      '$me = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value',
      'foreach ($row in $rows) {',
      // The lookup's own process, or one it started, never holds the port: it could have taken a freed id (as windowsPeerQuery).
      '  if ($row.OwningProcess -eq $PID) { continue }',
      '  $process = Get-CimInstance Win32_Process -Filter ("ProcessId = " + [int]$row.OwningProcess)',
      '  if (-not $process -or -not $process.CreationDate -or -not $row.CreationTime) { continue }',
      // Windows gives a socket's time to the second and a process's finer: the process's is cut to the second and compared with
      // no slack, as in windowsPeerQuery.
      '  $started = $process.CreationDate.AddTicks(-($process.CreationDate.Ticks % [TimeSpan]::TicksPerSecond))',
      '  if ($started -gt $row.CreationTime) { continue }',
      '  $owner = Invoke-CimMethod -InputObject $process -MethodName GetOwnerSid',
      "  if ($owner.ReturnValue -eq 0 -and $owner.Sid -and $owner.Sid -eq $me) { 'yes'; exit 0 }",
      '}',
      "'no'",
    ].join('\n'),
    inputs: { HARNESS_LISTEN_PORT: String(port) },
  }
}

async function askWindowsListener(port: number, run: WindowsPeerRun): Promise<boolean | null> {
  const query = windowsListenerQuery(port)
  try {
    const result = await run(query.script, query.inputs)
    if (result.status !== 0) return null
    const answer = result.stdout.trim()
    return answer === 'yes' ? true : answer === 'no' ? false : null
  } catch {
    return null
  }
}

/**
 * How many lookups run at once. Each is a process in this account, a PowerShell for up to WINDOWS_PEER_MS, and whoever heard the
 * hook token could open connections without end (Luna's review of #2605). Past these a lookup waits its turn, so the
 * owner's own burst of new connections (an agent's MCP clients on the bridge at start) is answered, not told "unknown
 * address" (Reed's review). Only past the queue too is it no, for now: that no is not kept on the connection, so a
 * keep-alive client asking again on it is asked of Windows once a slot frees.
 */
export const WINDOWS_PEER_LOOKUPS = 4
export const WINDOWS_PEER_QUEUE = 32
let windowsLookups = 0
const waiting: Array<() => void> = []

/** A Windows answer: yes, no and why, or not asked: too many lookups were running and waiting, or the lookup never finished. */
type WindowsAnswer = boolean | 'busy' | 'timeout' | { no: string }

async function askWindows(socket: Socket, run: WindowsPeerRun): Promise<WindowsAnswer> {
  const peerPort = socket.remotePort, ownPort = socket.localPort
  // As on Linux and macOS: only an exact pair of addresses makes the pair of ports name one connection.
  if (!peerPort || !ownPort || socket.remoteAddress !== '127.0.0.1' || socket.localAddress !== '127.0.0.1') return false
  if (windowsLookups >= WINDOWS_PEER_LOOKUPS) {
    if (waiting.length >= WINDOWS_PEER_QUEUE) return 'busy'
    // The slot is handed over by the lookup that ends (below), so the count never drops between them.
    await new Promise<void>((resolve) => { waiting.push(resolve) })
  } else {
    windowsLookups++
  }
  // A connection that went while it waited needs no answer: pass the slot on (Remy's review of #2605).
  if (socket.destroyed) {
    release()
    return false
  }
  const query = windowsPeerQuery(peerPort, ownPort)
  try {
    const result = await run(query.script, query.inputs)
    // runPowershellAsync gives a null status to a script it ended at its limit, or one that never started.
    if (result.status === null) return 'timeout'
    const said = result.stdout.trim()
    if (result.status === 0 && said === 'yes') return true
    // Only the script's own reason is logged: one line, bounded.
    return /^no: [^\r\n]{1,200}$/.test(said) ? { no: said.slice(4) } : false
  } catch {
    return false
  } finally {
    release()
  }
}

/** Hands this lookup's slot to the next one waiting, or frees it. */
function release(): void {
  const next = waiting.shift()
  if (next) next()
  else windowsLookups--
}

const answers = new WeakMap<Socket, Promise<boolean>>()

/**
 * Whether the caller on [socket] runs as this OS account: asked of `/proc/net/tcp`, `lsof`, or on Windows of Windows itself
 * ([run], audit W1: Windows answered yes without asking, and the Team account, holding the port at boot, opened the daemon
 * with the credential it heard).
 */
export function peerIsThisAccount(socket: Socket, platform: NodeJS.Platform = process.platform, run: WindowsPeerRun = runWindowsPeer): Promise<boolean> {
  let answer = answers.get(socket)
  if (!answer) {
    const asked: Promise<WindowsAnswer> = platform === 'win32' ? askWindows(socket, run) : ask(socket, platform)
    answer = asked.then((result) => {
      const why = result === 'busy' ? 'busy, too many lookups are running; asked again on its next request'
        : result === 'timeout' ? 'Windows did not say who the caller is in time'
        : typeof result === 'object' ? `the caller is not this account (${result.no})` : 'the caller is not this account'
      if (result !== true) console.warn(`[peer] refused a valid secret on 127.0.0.1:${socket.localPort}: ${why}`)
      if (result === 'busy') answers.delete(socket)
      return result === true
    })
    answers.set(socket, answer)
  }
  return answer
}