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.

12.5 KB
Raw Blame
/**
 * What an MCP client runs to reach a connection (follow-up of audit H1, docs/plans/2026-11-02-connections-bridge-stdio-shim-plan.md).
 * A client on a loopback address talks to whoever holds that port, so another account that took it could read its tool calls and
 * feed false answers to the owner's running agents. This talks stdio to the client and HTTP to the bridge over its 0600 socket. It
 * holds no key, as reaching that socket is the credential, and it never falls back to a port: with the socket gone the daemon is
 * down, and the client is told so.
 *
 * Its own small script, written into the vault's private folder as lib/buddyGuard.ts writes its guard, for three reasons found in
 * review of #2558. An entry naming the running script would name the lean bundle from the daemon, which has no CLI, and from any
 * `harness connections` a worktree that may be removed. An entry naming cli.js would load all of it, about 45 MiB, once per
 * connection per agent. And the updater ships only cli.js and notify.mjs, so a third file there would need its manifest changed.
 * Node's built-ins only: nothing else is beside it.
 *
 * On Windows there is no socket: the shim reaches the bridge's pipe (bridge.ts serveBridgePipe, task #2162), named in a record in
 * the vault's private folder (`--pipe <record>`). Node cannot set a pipe's DACL, so reaching it proves nothing, and once the bridge
 * is gone any account can make a pipe of its name: the shim dials it only while the recorded process runs as this account, proves
 * the record's token without sending it, and relays no answer that does not prove the token back (lib/windows/pipeAuth.ts).
 *
 * The client's stream is newline-delimited JSON-RPC (MCP's stdio transport). Each message becomes one POST of MCP's HTTP transport,
 * whose answer is JSON or an event stream. `initialize` goes first and alone: its answer names the session the rest carry. A
 * service's own unprompted stream (GET) is not opened, so `notifications/*_changed` are not relayed.
 */
import { PIPE_AUTH_HEADER, PIPE_PROOF_HEADER } from '../windows/pipeAuth.js'
import { SOCKET_KEY } from './bridge.js'

export const MCP_SHIM_SOURCE = String.raw`#!/usr/bin/env node
// Written by Harness (lib/connectors/mcpShimSource.ts); it is replaced at each daemon start.
import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
import { closeSync, fstatSync, lstatSync, openSync, readFileSync } from 'node:fs'
import { request as httpRequest } from 'node:http'
import { dirname } from 'node:path'
import { createInterface } from 'node:readline'

const NOT_RUNNING = 'Harness is not running on this computer, so this connection cannot be reached. Start it and try again.'
const UNREADABLE = "The connection's answer could not be read. Try again."
const NOT_PRIVATE = "Harness's connection socket is not private to this account, so it was not used. Restart Harness."
const UNPROVEN = "Something other than Harness answered on its connection pipe, so its answer was not used. Restart Harness."

const [flag, socket, code, graceFlag, grace] = process.argv.slice(2)
// --pipe names the bridge's pipe record on Windows (lib/connectors/bridge.ts serveBridgePipe), --socket its 0600 socket elsewhere.
const piped = flag === '--pipe'
if ((flag !== '--socket' && !piped) || !socket || !code) { console.error('usage: mcp-shim --socket PATH CODE | --pipe RECORD CODE'); process.exit(2) }
// How long open requests get once the client has gone, so a hung stream does not leave a process behind.
const graceMs = graceFlag === '--grace-ms' ? Number(grace) : 5000
const path = '/${SOCKET_KEY}/' + encodeURIComponent(code) + '/mcp'

// Whether the socket is what the daemon made: 0600, this account's, in a folder only this account can write to.
function socketState() {
  try {
    const uid = process.getuid?.()
    const file = lstatSync(socket), folder = lstatSync(dirname(socket))
    if (!file.isSocket() || (file.mode & 0o777) !== 0o600 || !folder.isDirectory() || (folder.mode & 0o022) !== 0) return 'open'
    return uid !== undefined && (file.uid !== uid || folder.uid !== uid) ? 'open' : 'private'
  } catch (error) {
    return error.code === 'ENOENT' ? 'absent' : 'open'
  }
}

// Mirrors LOCAL_PIPE_RE and isPipePath in lib/windows/pipeAuth.ts: on Windows a pipe on this computer named harness-<id>, never
// another computer's (an SMB connection that can carry this user's sign-in); elsewhere only the tests make one, a socket so named.
const PIPE_RE = process.platform === 'win32' ? /^\\\\\.\\pipe\\harness-([0-9a-f]{32})$/ : /(?:^|\/)harness-([0-9a-f]{32})$/

// The bridge's pipe, read from its record for each request so a bridge that restarted under a new name is followed; null when
// there is nothing to dial. The record must be a plain file (not a link), the very one opened, and private to this account where
// the system says so. The bridge is this account's, so a pid that is gone or answers EPERM (another account's process, one that
// took the pid since) means no bridge: a pipe of its name may be anyone's.
function pipeTarget() {
  let fd = null
  try {
    const seen = lstatSync(socket, { bigint: true })
    if (!seen.isFile() || seen.size > 4096n) return null
    fd = openSync(socket, 'r')
    const opened = fstatSync(fd, { bigint: true })
    if (!opened.isFile() || opened.dev !== seen.dev || opened.ino !== seen.ino) return null
    const uid = process.getuid?.()
    if (process.platform !== 'win32' && ((opened.mode & 0o077n) !== 0n || (uid !== undefined && opened.uid !== BigInt(uid)))) return null
    const record = JSON.parse(readFileSync(fd, 'utf8'))
    const id = typeof record?.pipe === 'string' ? PIPE_RE.exec(record.pipe)?.[1] : null
    if (!id || typeof record.token !== 'string' || !/^[0-9a-f]{64}$/.test(record.token)) return null
    if (!Number.isSafeInteger(record.pid) || record.pid <= 0) return null
    try { process.kill(record.pid, 0) } catch { return null }
    return { pipe: record.pipe, id, token: Buffer.from(record.token, 'hex') }
  } catch {
    return null
  } finally {
    if (fd !== null) closeSync(fd)
  }
}
const mac = (token, separator, nonce) => createHmac('sha256', token).update(Buffer.of(separator)).update(nonce, 'utf8').digest('hex')
const proven = (proof, token, nonce) => {
  if (typeof proof !== 'string' || !/^[0-9a-f]{64}$/.test(proof)) return false
  return timingSafeEqual(Buffer.from(proof, 'hex'), Buffer.from(mac(token, 0x00, nonce), 'hex'))
}

// A client that went away closes this stream: nothing more to say, and no reason to fall over saying it.
process.stdout.on('error', () => {})
let closing = false
const say = (message) => { if (!closing) process.stdout.write(JSON.stringify(message) + '\n') }
const refuse = (id, errorCode, message) => say({ jsonrpc: '2.0', id, error: { code: errorCode, message } })
let session, version
// The client's initialize and what it sent after, to open a new session when the service forgets this one.
let opening = null, opened = null
const open = new Set()

// One answer: JSON, or an event stream whose every data is a message of its own. quiet: for this shim alone.
const relay = (answer, sent, quiet) => new Promise((resolve, reject) => {
  const header = answer.headers['mcp-session-id']
  if (typeof header === 'string') session = header
  const status = answer.statusCode ?? 500
  const streaming = String(answer.headers['content-type'] ?? '').includes('text/event-stream')
  const asked = sent.method !== undefined && sent.id !== undefined
  let held = '', answered = false
  const take = (raw) => {
    let message
    // Not ours to read, a service's keep-alive say: it must not end the client's connection.
    try { message = JSON.parse(raw) } catch { return }
    answered ||= message.id === sent.id
    if (sent.method === 'initialize' && typeof message.result?.protocolVersion === 'string') version = message.result.protocolVersion
    if (!quiet) say(message)
  }
  // An event ends at a blank line; its data lines joined are its message.
  const events = () => {
    for (let at = held.search(/\r?\n\r?\n/); at >= 0; at = held.search(/\r?\n\r?\n/)) {
      const event = held.slice(0, at)
      held = held.slice(at).replace(/^\r?\n\r?\n/, '')
      const data = event.split(/\r?\n/).filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n')
      if (data) take(data)
    }
  }
  answer.setEncoding('utf8')
  answer.on('data', (chunk) => { held += chunk; if (streaming) events() })
  answer.on('error', reject)
  answer.on('end', () => {
    if (streaming) { held += '\n\n'; events() }
    else if (held.trim() && status < 300) take(held)
    else if (status >= 300 && asked) {
      // The bridge's refusal names no request: this one is what it answers.
      let reason = 'The connection answered ' + status + '.'
      try { reason = JSON.parse(held).error?.message ?? reason } catch { /* not its JSON */ }
      if (!quiet) refuse(sent.id, -32001, reason)
      answered = true
    }
    // A client would wait for ever on a request nothing answered.
    if (asked && !answered && !quiet) refuse(sent.id, -32001, UNREADABLE)
    resolve()
  })
})

// One POST; its status, or 0 when none came.
const post = (raw, sent, quiet = false, retried = false) => new Promise((resolve) => {
  const asked = sent.method !== undefined && sent.id !== undefined
  const failed = (reason) => { if (asked && !quiet) refuse(sent.id, -32001, reason); resolve(0) }
  let target = null, nonce = null
  if (piped) {
    target = pipeTarget()
    if (!target) { failed(NOT_RUNNING); return }
    nonce = target.id + randomBytes(16).toString('hex')
  } else {
    const state = socketState()
    if (state !== 'private') { failed(state === 'absent' ? NOT_RUNNING : NOT_PRIVATE); return }
  }
  const request = httpRequest({ socketPath: target ? target.pipe : socket, method: 'POST', path,
    headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream',
      ...(session ? { 'mcp-session-id': session } : {}), ...(version ? { 'mcp-protocol-version': version } : {}),
      ...(target ? { '${PIPE_AUTH_HEADER}': nonce + '.' + mac(target.token, 0x01, nonce) } : {}) } },
  (answer) => {
    open.delete(request)
    // Before anything of it is read: an answer that is not the bridge's never reaches the client.
    if (target && !proven(answer.headers['${PIPE_PROOF_HEADER}'], target.token, nonce)) {
      request.destroy()
      failed(UNPROVEN)
      return
    }
    // The service forgot the session (it restarted, or it expired). An HTTP client opens another on a 404; a stdio client
    // cannot know to, so an agent running for days would lose this connection until it restarts.
    if (answer.statusCode === 404 && session && !retried && sent.method !== 'initialize' && opening) {
      answer.resume()
      reopen().then((ok) => {
        if (ok) post(raw, sent, quiet, true).then(resolve)
        else failed(code + ' could not be reached. Try again.')
      })
      return
    }
    relay(answer, sent, quiet).then(() => resolve(answer.statusCode ?? 0), () => failed(UNREADABLE))
  })
  open.add(request)
  request.on('error', () => { open.delete(request); failed(closing ? UNREADABLE : NOT_RUNNING) })
  request.end(raw)
})

// A new session from the client's own initialize, its answer kept to this shim. Requests that fail together share it.
let reopening = null
const reopen = () => reopening ??= (async () => {
  session = undefined
  // Each marked as retried: a 404 here must not wait on the very reopen that sent it.
  const status = await post(opening, JSON.parse(opening), true, true)
  if (status >= 300 || status === 0) return false
  if (opened) await post(opened, JSON.parse(opened), true, true)
  return true
})().finally(() => { reopening = null })

const running = new Set()
let first = null
for await (const raw of createInterface({ input: process.stdin, crlfDelay: Infinity })) {
  if (!raw.trim()) continue
  let sent
  try {
    sent = JSON.parse(raw)
    if (!sent || typeof sent !== 'object') throw new Error('not a message')
  } catch { refuse(null, -32700, 'That line is not JSON.'); continue }
  // initialize alone: nothing else goes until its answer has named the session. Its notification goes in order too.
  if (first) await first
  if (sent.method === 'initialize') opening = raw
  else if (sent.method === 'notifications/initialized') opened = raw
  const send = post(raw, sent)
  if (sent.method === 'initialize' || sent.id === undefined) first = send
  running.add(send)
  send.finally(() => { running.delete(send) })
}
// The client has gone. What is open gets a moment; a hung stream must not keep this process.
await Promise.race([Promise.all(running), new Promise((resolve) => { setTimeout(resolve, graceMs).unref() })])
closing = true
process.exit(0)
`