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
// The add-identity encoder against a fake agent that DECODES the message and rebuilds the private
// key from it (a sign/verify round trip, so a field in the wrong order or an mpint with a lost sign
// byte fails), plus the reply handling, and — where the platform has one — a real OpenSSH agent.
import { describe, it, expect, afterEach } from 'vitest'
import net from 'net'
import os from 'os'
import path from 'path'
import fs from 'fs'
import crypto from 'crypto'
import { spawn, type ChildProcess } from 'child_process'
import { utils, createAgent, type ParsedKey } from 'ssh2'
import {
addKeyToAgent,
addIdentityRequest,
removeIdentityRequest,
sendAgentRequest,
sshMpint,
parseAddKeysToAgent,
decideAgentAdd,
SSH2_AGENTC_ADD_IDENTITY,
SSH2_AGENTC_ADD_ID_CONSTRAINED,
SSH_AGENT_CONSTRAIN_LIFETIME,
SSH_AGENT_FAILURE,
SSH_AGENT_SUCCESS
} from './agent-add'
import { findExecutableSync } from '../../exec-path'
import { ed25519KeyPair } from './test-keys'
import { pickWindowsAgent } from './windows-agent-discovery'
function parsed(k: string, pass?: string): ParsedKey {
const p = utils.parseKey(k, pass)
const one = Array.isArray(p) ? p[0] : p
if (one instanceof Error) throw one
return one
}
const PASS = 'pw'
const KEYS: Record<string, ParsedKey> = {
ed25519: parsed(ed25519KeyPair({ passphrase: PASS, cipher: 'aes256-ctr', rounds: 4 }).private, PASS),
ecdsa256: parsed(utils.generateKeyPairSync('ecdsa', { bits: 256, passphrase: PASS, cipher: 'aes256-ctr', rounds: 4 }).private, PASS),
ecdsa384: parsed(utils.generateKeyPairSync('ecdsa', { bits: 384 }).private),
ecdsa521: parsed(utils.generateKeyPairSync('ecdsa', { bits: 521 }).private),
rsa: parsed(utils.generateKeyPairSync('rsa', { bits: 2048, passphrase: PASS, cipher: 'aes256-ctr', rounds: 4 }).private, PASS)
}
/** A cursor over an SSH-encoded buffer. */
function reader(b: Buffer) {
let o = 0
return {
byte: () => b[o++],
u32: () => {
const v = b.readUInt32BE(o)
o += 4
return v
},
str(): Buffer {
const n = this.u32()
const s = b.subarray(o, o + n)
o += n
return s
},
rest: () => b.subarray(o)
}
}
/** mpint → unsigned magnitude, asserting the encoding is canonical (minimal, non-negative). */
function mp(s: Buffer): Buffer {
if (s.length === 0) return s
expect(s[0] & 0x80).toBe(0)
if (s[0] === 0) expect(s[1] & 0x80).not.toBe(0)
return s[0] === 0 ? s.subarray(1) : s
}
const u = (b: Buffer): string => b.toString('base64url')
/** Rebuild a node private key from a decoded add-identity body and prove it signs as `key`. */
function decodeAndCheck(body: Buffer, key: ParsedKey): { type: number; comment: string; constraints: Buffer } {
const r = reader(body)
const type = r.byte()
const keyType = r.str().toString()
expect(keyType).toBe(key.type)
let jwk: crypto.webcrypto.JsonWebKey
if (keyType === 'ssh-ed25519') {
const a = r.str()
const ka = r.str()
expect(a.length).toBe(32)
expect(ka.length).toBe(64)
expect(ka.subarray(32).equals(a)).toBe(true)
jwk = { kty: 'OKP', crv: 'Ed25519', x: u(a), d: u(ka.subarray(0, 32)) }
} else if (keyType.startsWith('ecdsa-')) {
const curve = r.str().toString()
expect(keyType).toBe(`ecdsa-sha2-${curve}`)
const q = r.str()
expect(q[0]).toBe(4)
const w = (q.length - 1) / 2
const d = mp(r.str())
const crv = { nistp256: 'P-256', nistp384: 'P-384', nistp521: 'P-521' }[curve] as string
jwk = { kty: 'EC', crv, x: u(q.subarray(1, 1 + w)), y: u(q.subarray(1 + w)), d: u(Buffer.concat([Buffer.alloc(w - d.length), d])) }
} else {
const [n, e, d, iqmp, p, q] = [r.str(), r.str(), r.str(), r.str(), r.str(), r.str()].map(mp)
const bn = (b: Buffer): bigint => BigInt('0x' + (b.toString('hex') || '0'))
const hex = (v: bigint): Buffer => {
const h = v.toString(16)
return Buffer.from(h.length % 2 ? '0' + h : h, 'hex')
}
// iqmp must be q^-1 mod p (OpenSSH's definition), i.e. q * iqmp ≡ 1 (mod p).
expect((bn(q) * bn(iqmp)) % bn(p)).toBe(1n)
jwk = {
kty: 'RSA', n: u(n), e: u(e), d: u(d), p: u(p), q: u(q), qi: u(iqmp),
dp: u(hex(bn(d) % (bn(p) - 1n))), dq: u(hex(bn(d) % (bn(q) - 1n)))
}
}
const priv = crypto.createPrivateKey({ key: jwk, format: 'jwk' })
const data = Buffer.from('nodeterm agent add round trip')
const algo = keyType === 'ssh-ed25519' ? null : 'sha256'
const sig = crypto.sign(algo, data, priv)
expect(crypto.verify(algo, data, crypto.createPublicKey(key.getPublicPEM()), sig)).toBe(true)
const comment = r.str().toString()
return { type, comment, constraints: r.rest() }
}
function unframe(req: Buffer): Buffer {
const len = req.readUInt32BE(0)
expect(req.length).toBe(4 + len)
return req.subarray(4)
}
describe('sshMpint', () => {
it('encodes minimally and keeps the value non-negative', () => {
expect(sshMpint(Buffer.from([])).equals(Buffer.from([0, 0, 0, 0]))).toBe(true)
expect(sshMpint(Buffer.from([0, 0])).equals(Buffer.from([0, 0, 0, 0]))).toBe(true)
expect(sshMpint(Buffer.from([0x7f])).equals(Buffer.from([0, 0, 0, 1, 0x7f]))).toBe(true)
expect(sshMpint(Buffer.from([0x80])).equals(Buffer.from([0, 0, 0, 2, 0, 0x80]))).toBe(true)
expect(sshMpint(Buffer.from([0, 0, 0x81, 1])).equals(Buffer.from([0, 0, 0, 3, 0, 0x81, 1]))).toBe(true)
})
})
describe('parseAddKeysToAgent (ssh -G spellings, measured on Windows 9.5p2 and macOS 10.3p1)', () => {
it('reads true, a lifetime in seconds, and treats everything else as no', () => {
expect(parseAddKeysToAgent('true')).toEqual({ add: true })
expect(parseAddKeysToAgent('yes')).toEqual({ add: true })
expect(parseAddKeysToAgent('3600')).toEqual({ add: true, lifetimeSec: 3600 })
for (const v of ['false', 'no', 'ask', 'confirm', 'confirm 1800', '0', '-5', '1h', '', undefined, 'TRUEISH']) {
expect(parseAddKeysToAgent(v)).toEqual({ add: false })
}
})
})
describe('decideAgentAdd', () => {
const WIN = '\\\\.\\pipe\\openssh-ssh-agent'
it('adds nothing by default — the Windows agent keeps keys until removed', () => {
expect(decideAgentAdd({ agentPath: WIN, addKeysToAgent: 'false', windowsAgentOptIn: false })).toBeNull()
expect(decideAgentAdd({ agentPath: WIN, addKeysToAgent: undefined, windowsAgentOptIn: false })).toBeNull()
})
it('the machine opt-in applies to the Windows agent pipe only', () => {
expect(decideAgentAdd({ agentPath: WIN, addKeysToAgent: 'false', windowsAgentOptIn: true })).toEqual({})
expect(decideAgentAdd({ agentPath: WIN.toUpperCase(), addKeysToAgent: 'false', windowsAgentOptIn: true })).toEqual({})
expect(decideAgentAdd({ agentPath: '\\\\.\\pipe\\pageant.x', addKeysToAgent: 'false', windowsAgentOptIn: true })).toBeNull()
// The Pageant pipe windows-agent-discovery.ts picks as a default agent is never written to by the opt-in.
const discovered = pickWindowsAgent({ pipes: ['pageant.dev.3f9a1c0b2e'], user: 'dev' }) as string
expect(discovered).toBe('\\\\.\\pipe\\pageant.dev.3f9a1c0b2e')
expect(decideAgentAdd({ agentPath: discovered, addKeysToAgent: 'false', windowsAgentOptIn: true })).toBeNull()
expect(decideAgentAdd({ agentPath: '/tmp/agent.sock', addKeysToAgent: 'false', windowsAgentOptIn: true })).toBeNull()
})
it("the host's own AddKeysToAgent is honoured on any agent, a lifetime kept as a constraint", () => {
expect(decideAgentAdd({ agentPath: WIN, addKeysToAgent: 'true', windowsAgentOptIn: false })).toEqual({})
expect(decideAgentAdd({ agentPath: '/tmp/agent.sock', addKeysToAgent: 'true', windowsAgentOptIn: false })).toEqual({})
// A lifetime wins over the opt-in's unconstrained add: Windows refuses it and stores NOTHING.
expect(decideAgentAdd({ agentPath: WIN, addKeysToAgent: '600', windowsAgentOptIn: true })).toEqual({ lifetimeSec: 600 })
})
})
describe('addIdentityRequest', () => {
for (const [name, key] of Object.entries(KEYS)) {
it(`${name}: an unconstrained add carries a key that signs as the original`, () => {
const req = addIdentityRequest(key, `C:\\Users\\me\\.ssh\\id_${name}`)
expect(req).not.toBeNull()
const m = decodeAndCheck(unframe(req as Buffer), key)
expect(m.type).toBe(SSH2_AGENTC_ADD_IDENTITY)
expect(m.comment).toBe(`C:\\Users\\me\\.ssh\\id_${name}`)
expect(m.constraints.length).toBe(0)
})
}
it('a lifetime makes it ADD_ID_CONSTRAINED with one lifetime constraint', () => {
const m = decodeAndCheck(unframe(addIdentityRequest(KEYS.ed25519, 'k', { lifetimeSec: 3600 }) as Buffer), KEYS.ed25519)
expect(m.type).toBe(SSH2_AGENTC_ADD_ID_CONSTRAINED)
expect(m.constraints.equals(Buffer.from([SSH_AGENT_CONSTRAIN_LIFETIME, 0, 0, 0x0e, 0x10]))).toBe(true)
})
it('refuses a nonsense lifetime instead of sending an unbounded add', () => {
for (const lifetimeSec of [0, -1, 1.5, NaN]) expect(addIdentityRequest(KEYS.ed25519, 'k', { lifetimeSec })).toBeNull()
})
it('refuses a key type it does not encode', () => {
const odd = { ...KEYS.rsa, type: 'ssh-dss', getPrivatePEM: () => KEYS.rsa.getPrivatePEM() } as unknown as ParsedKey
expect(addIdentityRequest(odd, 'k')).toBeNull()
const broken = { type: 'ssh-ed25519', getPrivatePEM: () => 'not a pem' } as unknown as ParsedKey
expect(addIdentityRequest(broken, 'k')).toBeNull()
})
})
describe('addKeyToAgent against a fake agent', () => {
let server: net.Server | null = null
let sockPath = ''
const tmps: string[] = []
afterEach(async () => {
await new Promise<void>((r) => (server ? server.close(() => r()) : r()))
server = null
for (const t of tmps.splice(0)) fs.rmSync(t, { recursive: true, force: true })
})
async function fakeAgent(reply: (req: Buffer, sock: net.Socket) => void): Promise<string> {
if (process.platform === 'win32') {
sockPath = `\\\\.\\pipe\\nodeterm-agent-add-test-${crypto.randomUUID()}`
} else {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-aa-'))
tmps.push(tmp)
sockPath = path.join(tmp, 's')
}
server = net.createServer((sock) => {
let buf = Buffer.alloc(0)
sock.on('data', (d: Buffer) => {
buf = Buffer.concat([buf, d])
if (buf.length >= 4 && buf.length >= 4 + buf.readUInt32BE(0)) reply(buf, sock)
})
sock.on('error', () => {})
})
await new Promise<void>((r) => server?.listen(sockPath, () => r()))
return sockPath
}
const answer = (type: number) => (_req: Buffer, sock: net.Socket) => sock.write(Buffer.from([0, 0, 0, 1, type]))
it('reports SUCCESS as added, and the agent received the whole key', async () => {
let got: Buffer | null = null
const p = await fakeAgent((req, sock) => {
got = req
answer(SSH_AGENT_SUCCESS)(req, sock)
})
expect(await addKeyToAgent(p, KEYS.rsa, 'id_rsa')).toBe('added')
expect(decodeAndCheck(unframe(got as unknown as Buffer), KEYS.rsa).comment).toBe('id_rsa')
})
it('reports FAILURE as refused', async () => {
const p = await fakeAgent(answer(SSH_AGENT_FAILURE))
expect(await addKeyToAgent(p, KEYS.ed25519, 'k', { lifetimeSec: 60 })).toBe('refused')
})
it('an agent that hangs up, stays silent or answers garbage is an error, never a throw', async () => {
let p = await fakeAgent((_r, sock) => sock.destroy())
expect(await addKeyToAgent(p, KEYS.ed25519, 'k')).toBe('error')
await new Promise<void>((r) => server?.close(() => r()))
p = await fakeAgent(() => {})
expect(await addKeyToAgent(p, KEYS.ed25519, 'k', { timeoutMs: 150 })).toBe('error')
await new Promise<void>((r) => server?.close(() => r()))
p = await fakeAgent((_r, sock) => sock.write(Buffer.from([0xff, 0xff, 0xff, 0xff, 6])))
expect(await addKeyToAgent(p, KEYS.ed25519, 'k')).toBe('error')
})
it('no agent at the path is an error', async () => {
const missing = process.platform === 'win32' ? `\\\\.\\pipe\\nodeterm-missing-${crypto.randomUUID()}` : path.join(os.tmpdir(), `nt-missing-${crypto.randomUUID()}`)
expect(await addKeyToAgent(missing, KEYS.ed25519, 'k')).toBe('error')
})
it('an unsupported key never touches the agent', async () => {
let calls = 0
const p = await fakeAgent((req, sock) => {
calls++
answer(SSH_AGENT_SUCCESS)(req, sock)
})
const odd = { type: 'ssh-dss', getPrivatePEM: () => '' } as unknown as ParsedKey
expect(await addKeyToAgent(p, odd, 'k')).toBe('unsupported-key')
expect(calls).toBe(0)
})
})
// A REAL agent: OpenSSH's own ssh-agent where the platform ships one (macOS, Linux). Proves the
// agent accepts every encoded type, honours the lifetime, and can SIGN with what it received.
const sshAgentBin = process.platform === 'win32' ? null : findExecutableSync('ssh-agent', ['/usr/bin/ssh-agent'])
describe.skipIf(!sshAgentBin)('addKeyToAgent against OpenSSH ssh-agent', () => {
let child: ChildProcess | null = null
let tmp = ''
afterEach(() => {
child?.kill()
child = null
if (tmp) fs.rmSync(tmp, { recursive: true, force: true })
})
async function startAgent(): Promise<string | null> {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-ag-'))
const sock = path.join(tmp, 'a')
if (Buffer.byteLength(sock) > 100) return null // sun_path; the sandbox dir may be deep
child = spawn(sshAgentBin as string, ['-D', '-a', sock], { stdio: 'ignore' })
for (let i = 0; i < 50 && !fs.existsSync(sock); i++) await new Promise((r) => setTimeout(r, 50))
return fs.existsSync(sock) ? sock : null
}
const identities = (sock: string): Promise<string[]> =>
new Promise((res, rej) =>
createAgent(sock).getIdentities((e, ks) => (e ? rej(e) : res((ks ?? []).map((k) => (k as ParsedKey).comment))))
)
it('adds every key type, signs with it, and drops a constrained key at its lifetime', async (ctx) => {
const sock = await startAgent()
if (!sock) return ctx.skip()
for (const [name, key] of Object.entries(KEYS)) expect(await addKeyToAgent(sock, key, name)).toBe('added')
expect((await identities(sock)).sort()).toEqual(Object.keys(KEYS).sort())
// Sign through the agent with a key it only knows from our message.
const sig = await new Promise<Buffer>((res, rej) =>
createAgent(sock).sign(KEYS.ed25519, Buffer.from('x'), {}, (e, s) => (e ? rej(e) : res(s as Buffer)))
)
expect(KEYS.ed25519.verify(Buffer.from('x'), sig)).toBe(true)
const rsaSig = await new Promise<Buffer>((res, rej) =>
createAgent(sock).sign(KEYS.rsa, Buffer.from('x'), { hash: 'sha256' }, (e, s) => (e ? rej(e) : res(s as Buffer)))
)
expect(KEYS.rsa.verify(Buffer.from('x'), rsaSig, 'sha256')).toBe(true)
for (const key of Object.values(KEYS)) expect(await sendAgentRequest(sock, removeIdentityRequest(key))).toBe('added')
expect(await identities(sock)).toEqual([])
expect(await addKeyToAgent(sock, KEYS.rsa, 'short', { lifetimeSec: 1 })).toBe('added')
expect(await identities(sock)).toEqual(['short'])
await new Promise((r) => setTimeout(r, 2200))
expect(await identities(sock)).toEqual([])
}, 15_000)
})
// The REAL Windows OpenSSH agent service. Runs on the windows-latest CI leg, which starts the
// service first (ci.yml); skipped where the pipe does not exist. Pins the measurement the policy
// rests on: a constrained add is REFUSED, an unconstrained one is stored and signs.
const WINDOWS_PIPE = '\\\\.\\pipe\\openssh-ssh-agent'
const windowsAgentUp = process.platform === 'win32' && (() => {
try {
return fs.existsSync(WINDOWS_PIPE)
} catch {
return false
}
})()
describe.skipIf(!windowsAgentUp)('addKeyToAgent against the Windows OpenSSH agent service', () => {
afterEach(async () => {
for (const key of Object.values(KEYS)) await sendAgentRequest(WINDOWS_PIPE, removeIdentityRequest(key))
})
const comments = (): Promise<string[]> =>
new Promise((res, rej) =>
createAgent(WINDOWS_PIPE).getIdentities((e, ks) => (e ? rej(e) : res((ks ?? []).map((k) => (k as ParsedKey).comment))))
)
it('refuses a lifetime constraint for every key type, and stores nothing', async () => {
for (const [name, key] of Object.entries(KEYS)) {
expect(await addKeyToAgent(WINDOWS_PIPE, key, `nt-test-${name}`, { lifetimeSec: 60 })).toBe('refused')
}
expect((await comments()).filter((c) => c.startsWith('nt-test-'))).toEqual([])
})
it('stores an unconstrained key of every type, signs with it, and removes it', async () => {
for (const [name, key] of Object.entries(KEYS)) expect(await addKeyToAgent(WINDOWS_PIPE, key, `nt-test-${name}`)).toBe('added')
expect((await comments()).filter((c) => c.startsWith('nt-test-')).sort()).toEqual(Object.keys(KEYS).map((n) => `nt-test-${n}`).sort())
const sig = await new Promise<Buffer>((res, rej) =>
createAgent(WINDOWS_PIPE).sign(KEYS.rsa, Buffer.from('x'), { hash: 'sha256' }, (e, s) => (e ? rej(e) : res(s as Buffer)))
)
expect(KEYS.rsa.verify(Buffer.from('x'), sig, 'sha256')).toBe(true)
for (const key of Object.values(KEYS)) expect(await sendAgentRequest(WINDOWS_PIPE, removeIdentityRequest(key))).toBe('added')
expect((await comments()).filter((c) => c.startsWith('nt-test-'))).toEqual([])
}, 20_000)
})