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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The boundary a Harness Team account stands on: an agent in that account is refused every read and write in the home of
* the Mac's or Linux computer's owner (audit of 2026-11-02, docs/security/2026-11-02-team-account-boundary.md).
*
* The other specs here check the setup script as text and the privacy check with made-up answers. Neither would notice a
* home folder that the kernel lets another account into. These ask the kernel, about the mode the real setup script gives,
* in a fixture folder: no real account, home or permission changes, and nothing here uses sudo beyond becoming `nobody`.
*
* Two ways to be the other account:
* - As `nobody`, through `sudo -n`, where that needs no password: CI's Linux, where it may not be missing.
* - Everywhere else (a shared Mac has no passwordless sudo, and its accounts are not ours to change): as this user, with the
* fixture's owner bits set to what the group and other bits say. A Team account on a Mac is in the owner's group (staff), so
* both count. At the mode setup gives, that is mode 000, so these runs show only that 000 refuses. What guards the home on
* such a machine is the check that no group or other bit is set, on every line of the script that changes it.
*/
import { spawn, spawnSync } from 'node:child_process'
import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
import { createServer } from 'node:http'
import type { AddressInfo } from 'node:net'
import { tmpdir } from 'node:os'
import { join, relative } from 'node:path'
import { fileURLToPath } from 'node:url'
import { afterEach, describe, expect, it } from 'vitest'
import { env } from '../config/env.js'
import { startHookServer, type HookServerHandlers } from '../hookServer.js'
import { bridgeKey } from '../lib/connectors/agents.js'
import { createBridge } from '../lib/connectors/bridge.js'
import { portHolderIsThisAccount } from '../lib/peerAccount.js'
import { Store } from '../lib/connectors/store.js'
import { SENTINEL_NAME } from './layout.js'
import { realPrivacyDeps, runPrivacyCheck } from './privacy.js'
import { buildLinuxSetupScript, buildSetupScript, type SetupScriptInput } from './script.js'
const SETUP: SetupScriptInput = {
user: 'harnessteam', realName: 'Harness Team', home: '/Users/harnessteam', owner: 'owner-placeholder', ownerHome: '/Users/owner-placeholder',
stageDir: '/private/var/folders/aa/T/harness-team-x1', nodeRuntimeDir: '/Users/owner-placeholder/.harness/runtime/node-v24',
tmuxRuntimeDir: null, cliDir: '/Users/owner-placeholder/.harness/cli', ownerNode: '/Users/owner-placeholder/.harness/runtime/node-v24/bin/node',
ownerCli: '/Users/owner-placeholder/.harness/cli/cli.js', mintEnv: {}, signIn: 'missing',
}
/** A line of a script that changes who may enter the owner's home, indented or wrapped in anything, by variable or by its path. */
const changesOwnerHome = (line: string): boolean => !line.trimStart().startsWith('#')
&& /\b(chmod|chown|chgrp|setfacl)\b/.test(line)
&& (line.includes('OWNER_HOME') || new RegExp(`${SETUP.ownerHome}(?![\\w./-])`).test(line))
/**
* What the script does to the owner's home, as a mode. Every line of it counts, not only step 3's: a later `chmod 755`, or an ACL
* for the Team account, would reopen the home after that step closed it. It throws on a line it cannot read, or more than the one.
*/
function ownerHomeMode(script: string): number {
const step = script.split('\n').filter(changesOwnerHome)
expect(step, 'the one line that closes the owner\'s home, and no other that changes it').toHaveLength(1)
const line = step[0]!.trim()
const chmod = /^chmod (\d{3}) "\$OWNER_HOME"$/.exec(line)
if (chmod) return Number.parseInt(chmod[1]!, 8)
const acl = /^setfacl -n -m u::([rwx-]{3}),g::([rwx-]{3}),o::([rwx-]{3}) "\$OWNER_HOME"$/.exec(line)
if (!acl) throw new Error(`this line changes the owner's home in a way this spec cannot read: ${line}`)
const bits = (word: string) => (word[0] === 'r' ? 4 : 0) + (word[1] === 'w' ? 2 : 0) + (word[2] === 'x' ? 1 : 0)
return bits(acl[1]!) * 0o100 + bits(acl[2]!) * 0o10 + bits(acl[3]!)
}
/** Whether this process can be `nobody` with no password. */
const sudoNobody = process.platform !== 'win32' && process.getuid?.() !== 0
&& spawnSync('sudo', ['-n', '-u', 'nobody', '/usr/bin/id', '-u'], { stdio: 'ignore', timeout: 5_000 }).status === 0
/** Each fixture's path and the mode it would have for its owner, so a test can put it back and remove it. */
interface Fixture {
root: string
home: string
/** A folder of the other account's own. */
own: string
modes: Map<string, number>
}
const fixtures: Fixture[] = []
/**
* An owner's home, as a default install leaves it: open to the group and everyone (macOS's staff, older Debian's 755), with a
* project folder anyone may write to, so nothing below the home's own mode would keep the other account out.
*/
function ownerHome(parent: string): Fixture {
const root = realpathSync(mkdtempSync(join(parent, 'hb-')))
chmodSync(root, 0o755)
const home = join(root, 'owner'), own = join(root, 'other')
mkdirSync(home)
mkdirSync(own)
chmodSync(own, 0o777)
const entries: Array<[string, number, string | null]> = [
[SENTINEL_NAME, 0o644, 'sentinel\n'],
['.gitconfig', 0o644, '[user]\n\tname = owner\n'],
['.ssh', 0o700, null],
['.ssh/id_ed25519', 0o600, 'not a real key\n'],
['code', 0o777, null],
['code/project.txt', 0o666, 'project\n'],
]
const modes = new Map<string, number>([[home, 0o755]])
for (const [name, mode, text] of entries) {
const path = join(home, name)
if (text === null) mkdirSync(path)
else writeFileSync(path, text)
modes.set(path, mode)
}
for (const [path, mode] of modes) chmodSync(path, mode)
const fixture = { root, home, own, modes }
fixtures.push(fixture)
return fixture
}
/** Every path in the home with its contents: what no refused write may change. */
function snapshot(fixture: Fixture): Record<string, string> {
const seen: Record<string, string> = {}
const walk = (path: string): void => {
const info = lstatSync(path)
seen[relative(fixture.home, path) || '.'] = info.isDirectory() ? 'folder' : readFileSync(path, 'utf8')
if (info.isDirectory()) for (const name of readdirSync(path).sort()) walk(join(path, name))
}
walk(fixture.home)
return seen
}
/** Sets the fixture's owner bits to what its group and other bits allow: this user now gets what the other account gets. */
function seenFromOutside(fixture: Fixture, homeMode: number): void {
// Files before the folders above them: a closed folder lets nothing below it change.
for (const [path, mode] of [...fixture.modes].reverse()) {
const actual = path === fixture.home ? homeMode : mode
chmodSync(path, (((actual >> 3) | actual) & 0o7) * 0o111)
}
}
/** The fixture's real modes again, so this user can read and remove it. */
function restored(fixture: Fixture, homeMode: number): void {
for (const [path, mode] of fixture.modes) chmodSync(path, path === fixture.home ? homeMode : mode)
}
afterEach(() => {
for (const fixture of fixtures.splice(0)) {
for (const path of fixture.modes.keys()) { try { chmodSync(path, 0o700) } catch { /* Removed by a write that should have been refused: its test said so. */ } }
rmSync(fixture.root, { recursive: true, force: true })
}
})
type Run = (command: string) => { status: number | null; output: string }
const asThisUser: Run = (command) => {
const result = spawnSync('/bin/sh', ['-c', command], { encoding: 'utf8', timeout: 10_000 })
return { status: result.status, output: `${result.stdout}${result.stderr}` }
}
const asNobody: Run = (command) => {
const result = spawnSync('sudo', ['-n', '-u', 'nobody', '/bin/sh', '-c', `cd /; ${command}`], { encoding: 'utf8', timeout: 10_000 })
return { status: result.status, output: `${result.stdout}${result.stderr}` }
}
/** Everything an agent in the other account might try, by name. A refusal must come from the kernel, not from a missing path. */
const attempts = ({ home, own }: Fixture): Record<string, string> => ({
'read the sentinel': `cat '${home}/${SENTINEL_NAME}'`,
'read a world-readable dotfile': `cat '${home}/.gitconfig'`,
'read a private key': `cat '${home}/.ssh/id_ed25519'`,
'read a world-readable project file': `cat '${home}/code/project.txt'`,
'read through its own symbolic link': `ln -sf '${home}/.gitconfig' '${own}/link' && cat '${own}/link'`,
'list the home': `ls -A '${home}'`,
'list .ssh': `ls -A '${home}/.ssh'`,
'list a project folder': `ls -A '${home}/code'`,
'stat a file by name': `ls -l '${home}/.gitconfig'`,
'create a file in the home': `: > '${home}/planted'`,
'make a folder in the home': `mkdir '${home}/planted-folder'`,
'leave a link in the home': `ln -s /tmp '${home}/planted-link'`,
'overwrite a dotfile': `: > '${home}/.gitconfig'`,
'append to a world-writable project file': `echo planted >> '${home}/code/project.txt'`,
'create a file in a world-writable folder': `: > '${home}/code/planted'`,
'delete a file': `rm -f '${home}/code/project.txt'`,
'rename a file': `mv '${home}/.gitconfig' '${home}/moved'`,
'hard-link a file out': `ln '${home}/.gitconfig' '${own}/hard'`,
})
/** Every attempt ends with the kernel's refusal, and the home is as it was. */
function expectRefused(run: Run, fixture: Fixture): void {
for (const [what, command] of Object.entries(attempts(fixture))) {
const { status, output } = run(command)
expect(status, `${what} was not refused: ${output}`).not.toBe(0)
expect(output, what).toMatch(/permission denied|not permitted/i)
}
}
const SCRIPTS: Array<[string, (input: SetupScriptInput) => string]> = [['macOS', buildSetupScript], ['Linux', buildLinuxSetupScript]]
describe('an agent in the Team account, in the owner\'s home', () => {
it.each(SCRIPTS)('%s: the mode setup gives it keeps group and everyone out, before the daemon starts', (name, build) => {
const script = build(SETUP)
// Not a loosening of 700: any group or other bit would let the other account back in.
expect(ownerHomeMode(script) & 0o077).toBe(0)
const closes = script.split('\n').findIndex(changesOwnerHome)
const starts = script.split('\n').findIndex(line => /launchctl bootstrap system|systemctl enable --now/.test(line))
expect(closes, name).toBeGreaterThan(-1)
expect(closes, name).toBeLessThan(starts)
})
it.each([
['a later chmod', 'chmod 755 "$OWNER_HOME"'],
['an indented chmod', ' chmod 755 "$OWNER_HOME"'],
['an ACL for the Team account', 'chmod +a "$TEAM allow list,search,read" "$OWNER_HOME"'],
['a chmod by its path', `/bin/chmod 755 ${SETUP.ownerHome}`],
['a change of group', 'chgrp staff "$OWNER_HOME"'],
['a recursive ACL as the owner', 'as_owner setfacl -R -m u:harnessteam:rX "$OWNER_HOME"'],
])('a script is refused when %s reopens the home after it closed', (_name, line) => {
const script = `${buildSetupScript(SETUP)}\n${line}\n`
expect(() => ownerHomeMode(script)).toThrow()
})
it('is let in before setup closes it: the attempts below are not refused for some other reason', () => {
const fixture = ownerHome(tmpdir())
seenFromOutside(fixture, 0o755)
const run = asThisUser
expect(run(`cat '${fixture.home}/.gitconfig'`).output).toContain('name = owner')
expect(run(`ls -A '${fixture.home}'`).output).toContain('.gitconfig')
expect(run(`cat '${fixture.home}/code/project.txt'`).status).toBe(0)
// The refusals that hold with the home open are the files' own, and none of the home's mode.
expect(run(`cat '${fixture.home}/.ssh/id_ed25519'`).status).not.toBe(0)
restored(fixture, 0o755)
})
it.each(SCRIPTS)('%s: is refused every read and write once setup closed it', (_name, build) => {
const fixture = ownerHome(tmpdir())
const mode = ownerHomeMode(build(SETUP))
const before = snapshot(fixture)
seenFromOutside(fixture, mode)
expectRefused(asThisUser, fixture)
restored(fixture, mode)
expect(snapshot(fixture)).toEqual(before)
})
// As a real other account, where one can be had for free. CI's Linux must have it: a required check is never skipped there.
it('CI\'s Linux can be another account', () => {
if (process.env.CI && process.platform === 'linux') expect(sudoNobody).toBe(true)
})
describe.runIf(sudoNobody)('as nobody, a real other account', () => {
/** Under /tmp: Vitest's own temporary folder may not be searchable by another account. */
const parent = '/tmp'
it('reads and lists the home before setup closes it', () => {
const fixture = ownerHome(parent)
expect(asNobody(`cat '${fixture.home}/.gitconfig'`).output).toContain('name = owner')
expect(asNobody(`ls -A '${fixture.home}'`).output).toContain('.gitconfig')
expect(asNobody(`echo planted >> '${fixture.home}/code/project.txt'`).status).toBe(0)
})
it.each(SCRIPTS)('%s: is refused every read and write once setup closed it', (_name, build) => {
const fixture = ownerHome(parent)
const before = snapshot(fixture)
chmodSync(fixture.home, ownerHomeMode(build(SETUP)))
expectRefused(asNobody, fixture)
expect(snapshot(fixture)).toEqual(before)
})
})
})
describe('the privacy check, on the real file system', () => {
const check = (fixture: Fixture) => runPrivacyCheck(
{ ownerHome: fixture.home, sentinel: join(fixture.home, SENTINEL_NAME) },
// This process may be an administrator on a developer's Mac; the account it stands in for may not. The rest is real.
{ ...realPrivacyDeps, platform: 'darwin', groups: () => [] },
)
it('passes a home closed as setup closes it', () => {
const fixture = ownerHome(tmpdir())
const mode = ownerHomeMode(buildSetupScript(SETUP))
seenFromOutside(fixture, mode)
expect(check(fixture).passed).toBe(true)
restored(fixture, mode)
})
it.each([
['open to everyone (755)', 0o755],
['open to the group, as a Mac makes a home (750)', 0o750],
// No listing, yet anyone who knows a name may open it: what a web server's home is often set to.
['searchable only (711)', 0o711],
['open to the group alone, to write too (770)', 0o770],
])('fails a home %s', (_name, mode) => {
const fixture = ownerHome(tmpdir())
seenFromOutside(fixture, mode)
const result = check(fixture)
restored(fixture, mode)
expect(result.passed).toBe(false)
})
it('fails closed on a sentinel that is not there: a missing file means the folder above it let the search through', () => {
const fixture = ownerHome(tmpdir())
rmSync(join(fixture.home, SENTINEL_NAME))
fixture.modes.delete(join(fixture.home, SENTINEL_NAME))
seenFromOutside(fixture, 0o711)
const result = check(fixture)
restored(fixture, 0o711)
expect(result).toMatchObject({ passed: false, item: 'sentinel' })
})
it('names the home by ~ or by what it is, never by its path, which carries the owner\'s account name', () => {
const fixture = ownerHome(tmpdir())
seenFromOutside(fixture, 0o755)
const result = check(fixture)
restored(fixture, 0o755)
expect(JSON.stringify(result)).not.toContain(fixture.home)
})
})
/**
* Audit H1 against a real other account and the real lookup: `nobody`, with a secret it heard. On a Mac with no passwordless
* sudo, this does not run; there the refusal is tested with a stand-in (hookServer.spec.ts, connectors.spec.ts).
*/
describe.runIf(sudoNobody)('a secret another account heard opens nothing, as nobody', () => {
/** One request as `nobody`: its status and body, from the real Node client. */
const askAsNobody = async (url: string, init: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{ status: number; text: string }> => {
const script = `fetch(${JSON.stringify(url)}, ${JSON.stringify(init)}).then(async r => console.log(JSON.stringify({ status: r.status, text: await r.text() })), e => { console.error(e); process.exit(9) })`
// Not asNobody: its spawnSync would hold this process, which is the server being asked, until the timeout.
const child = spawn('sudo', ['-n', '-u', 'nobody', process.execPath, '-e', script], { cwd: '/', stdio: ['ignore', 'pipe', 'pipe'], timeout: 20_000 })
let output = ''
child.stdout.on('data', (chunk: Buffer) => { output += chunk.toString() })
child.stderr.on('data', (chunk: Buffer) => { output += chunk.toString() })
const status = await new Promise<number | null>((resolve) => { child.on('close', resolve) })
expect(status, output).toBe(0)
return JSON.parse(output.trim().split('\n').at(-1)!) as { status: number; text: string }
}
it('the daemon refuses the credential and the hook token from nobody, and takes them from this account', async () => {
const started = await startHookServer(0, { onRegistered: () => {}, onSessionEnd: () => {}, onStatus: async () => ({ secretDetail: 'x' }) } as unknown as HookServerHandlers)
try {
const credential = readFileSync(join(env.ADAPTER_DATA_DIR, 'hook-credential'), 'utf8').trim()
const hookToken = readFileSync(join(env.ADAPTER_DATA_DIR, 'hook-token'), 'utf8').trim()
const base = `http://127.0.0.1:${started.port}`
expect((await askAsNobody(`${base}/api/machines`, { headers: { 'X-Harness-Local': credential } })).status).toBe(401)
expect((await askAsNobody(`${base}/api/status`, { headers: { 'X-Harness-Local': credential } })).text).not.toContain('secretDetail')
expect((await askAsNobody(`${base}/api/hook/session-end`, { method: 'POST', headers: { 'x-harness-hook-token': hookToken }, body: '{}' })).status).toBe(401)
expect(await (await fetch(`${base}/api/status`, { headers: { 'X-Harness-Local': credential } })).text()).toContain('secretDetail')
expect((await fetch(`${base}/api/hook/session-end`, { method: 'POST', headers: { 'x-harness-hook-token': hookToken }, body: '{}' })).status).not.toBe(401)
} finally {
started.server.closeAllConnections()
await new Promise<void>((resolve) => { started.server.close(() => resolve()) })
await started.localSocket?.close()
}
}, 60_000)
it('a listener of nobody on a plain listen(port), on `::`, reads as another account\'s', async () => {
// It exits by itself: this process may not stop another account's.
const script = `const s = require('node:net').createServer().listen(0, () => console.log(s.address().port)); setTimeout(() => process.exit(0), 8000)`
const child = spawn('sudo', ['-n', '-u', 'nobody', process.execPath, '-e', script], { cwd: '/', stdio: ['ignore', 'pipe', 'inherit'] })
const port = await new Promise<number>((resolve, reject) => {
child.stdout.once('data', (chunk: Buffer) => resolve(Number(chunk.toString().trim())))
child.once('close', () => reject(new Error('the listener ended before it named its port')))
})
try {
expect(await portHolderIsThisAccount(port)).toBe(false)
} finally {
await new Promise((resolve) => { child.once('close', resolve) })
}
}, 30_000)
it('the bridge answers nobody with the right key as it answers an unknown key', async () => {
const root = realpathSync(mkdtempSync(join(tmpdir(), 'hb-')))
const vault = new Store(root, {})
const key = bridgeKey(vault)
const bridge = createBridge(vault, { key: () => key })
await new Promise<void>((resolve) => { bridge.listen(0, '127.0.0.1', resolve) })
try {
const base = `http://127.0.0.1:${(bridge.address() as AddressInfo).port}`
const heard = await askAsNobody(`${base}/${key}/linear/mcp`, { method: 'POST', body: '{}' })
const unknown = await askAsNobody(`${base}/wrong/linear/mcp`, { method: 'POST', body: '{}' })
expect(heard).toEqual(unknown)
const mine = await fetch(`${base}/${key}/linear/mcp`, { method: 'POST', body: '{}' })
expect(await mine.text()).not.toBe(unknown.text)
} finally {
bridge.closeAllConnections()
await new Promise<void>((resolve) => { bridge.close(() => resolve()) })
rmSync(root, { recursive: true, force: true })
}
}, 60_000)
})
/** A hole the audit found (finding H1), now closed: the real hook, with a made-up credential, against a plain listener on the port. Its other cases are in localCredential.spec.ts. */
describe('the owner\'s credential and whoever holds the daemon\'s port', () => {
const NOTIFY = fileURLToPath(new URL('../../hook/notify.mjs', import.meta.url))
/** Made up for this test: never a real credential. */
const CREDENTIAL = 'A'.repeat(43)
it('H1: an engine hook hands its credential to no listener on the daemon\'s port', async () => {
const root = realpathSync(mkdtempSync(join(tmpdir(), 'hc-')))
const data = join(root, 'data')
mkdirSync(data, { mode: 0o700 })
writeFileSync(join(data, 'hook-credential'), CREDENTIAL, { mode: 0o600 })
// Any account may bind a free port above 1023: an agent in the Team account, while the owner's daemon restarts.
const heard: string[] = []
const impostor = createServer((req, res) => {
heard.push(String(req.headers['x-harness-hook-token'] ?? ''))
req.resume()
req.on('end', () => { res.writeHead(200, { 'content-type': 'application/json' }); res.end('{}') })
})
await new Promise<void>(resolve => { impostor.listen(0, '127.0.0.1', resolve) })
try {
const port = (impostor.address() as AddressInfo).port
const hook = spawn(process.execPath, [NOTIFY, '--port', String(port), '--data-dir', data], {
stdio: ['pipe', 'ignore', 'ignore'],
// Its own empty tmux folder, so the pane's routing reads no real tmux server.
env: { PATH: process.env.PATH, HOME: root, TMUX_PANE: '%999', TMUX_TMPDIR: root },
})
hook.stdin.end(JSON.stringify({ hook_event_name: 'SessionStart', session_id: '11111111-1111-4111-8111-111111111111', cwd: root, source: 'startup' }))
await new Promise<void>(resolve => { hook.on('exit', () => resolve()) })
// Nothing at all: the hook goes over the daemon's 0600 socket, and with none there the daemon is down.
expect(heard).toEqual([])
} finally {
await new Promise<void>(resolve => { impostor.close(() => resolve()) })
rmSync(root, { recursive: true, force: true })
}
}, 30_000)
})