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, it, expect, beforeEach, afterEach, vi } from 'vitest'
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { initPlatform, resetPlatformForTests } from '../platform'
import { fakePlatform } from '../platform-fake'
import { hookServer } from './hook-server'
import { loadOrCreateNodeAuthSecret, resetNodeAuthSecretForTests } from './node-auth-secret'
import { nodeTokenDir, resetNodeTokenFilesForTests } from './node-token-files'
import {
initNodeTokens,
ensureNodeToken,
sweepNodeToken,
refreshNodeTokens,
nodeIdFoldKey,
nodeIdsForCanvas,
remoteNodeTokenMinter,
setRemoteNodeTokenWriter,
ensureRemoteNodeToken,
forgetRemoteNodeTokens,
seedRemoteNodeTokens,
REMOTE_TOKEN_COALESCE_MS
} from './node-token-service'
/** The coalescing window is a real timer (see REMOTE_TOKEN_COALESCE_MS); wait it out. */
const flushCoalesce = (): Promise<void> =>
new Promise((r) => setTimeout(r, REMOTE_TOKEN_COALESCE_MS + 20))
let dir = ''
beforeEach(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodeterm-svc-'))
resetPlatformForTests()
resetNodeAuthSecretForTests()
resetNodeTokenFilesForTests()
hookServer.clearNodeAuthSecretForTests()
initPlatform(fakePlatform({ userDataDir: dir }))
})
afterEach(() => {
hookServer.clearNodeAuthSecretForTests()
fs.rmSync(dir, { recursive: true, force: true })
})
const canvases = [
{ nodes: [{ id: 'node-1' }, { id: 'node-2' }] },
{ nodes: [{ id: 'node-3' }] }
]
describe('node token service', () => {
it('materialises every node id in every persisted canvas at boot', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
expect(fs.readdirSync(nodeTokenDir()).sort()).toEqual(['node-1', 'node-2', 'node-3'])
})
it('writes nothing at all when the server has no secret (legacy mode)', () => {
hookServer.clearNodeAuthSecretForTests()
initNodeTokens({ canvases: () => canvases })
expect(fs.existsSync(nodeTokenDir())).toBe(false)
})
it('skips an unsafe id in a corrupt project file without aborting the sweep', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ nodes: [{ id: '..' }, { id: 'node-9' }] }] })
expect(fs.readdirSync(nodeTokenDir())).toEqual(['node-9'])
})
it('re-derives identical bytes on a refresh (no churn)', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
ensureNodeToken('node-1')
const first = fs.readFileSync(path.join(nodeTokenDir(), 'node-1'), 'utf8')
ensureNodeToken('node-1')
expect(fs.readFileSync(path.join(nodeTokenDir(), 'node-1'), 'utf8')).toBe(first)
})
it('sweeps a token on delete', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
ensureNodeToken('node-1')
sweepNodeToken('node-1')
expect(fs.existsSync(path.join(nodeTokenDir(), 'node-1'))).toBe(false)
})
})
/**
* On APFS `<tokenDir>/Term-1` and `<tokenDir>/term-1` are ONE file, so a `project.json` carrying
* both ids picks — by array order — which node's token lands in it, and the other node reads it.
* The refusal is unconditional (not fs-dependent): the test host here is case-SENSITIVE, so a
* missing refusal shows up as two files being written rather than as a hijack.
*/
describe('node token service — case-folding node id collisions', () => {
const files = () => fs.readdirSync(nodeTokenDir()).sort()
it('writes NEITHER token for two ids that differ only in case, and says so out loud', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ nodes: [{ id: 'Term-1' }, { id: 'term-1' }] }] })
expect(fs.existsSync(nodeTokenDir()) ? files() : []).toEqual([])
expect(warn.mock.calls.flat().join(' ')).toMatch(/Term-1.*term-1|term-1.*Term-1/)
warn.mockRestore()
})
it('refuses only the colliding pair — an innocent third node still gets its token', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({
canvases: () => [{ nodes: [{ id: 'Term-1' }, { id: 'term-1' }, { id: 'node-9' }] }]
})
expect(files()).toEqual(['node-9'])
vi.restoreAllMocks()
})
it('refuses on the SPAWN path too, checked against the live canvas', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
// The canvas holds only the attacker's id; the victim is spawning right now.
initNodeTokens({ canvases: () => [{ nodes: [{ id: 'TERM-1' }] }] })
expect(files()).toEqual(['TERM-1'])
ensureNodeToken('term-1')
// Both are gone: writing the second would have overwritten the first on APFS, and LEAVING the
// first is exactly the token the second node would have read.
expect(files()).toEqual([])
vi.restoreAllMocks()
})
it('sweeps a token already written before its twin appeared on the canvas', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
let hostile = false
initNodeTokens({
canvases: () => [{ nodes: hostile ? [{ id: 'Term-1' }, { id: 'term-1' }] : [{ id: 'Term-1' }] }]
})
expect(files()).toEqual(['Term-1'])
hostile = true
refreshNodeTokens()
expect(files()).toEqual([])
vi.restoreAllMocks()
})
it('an exact duplicate id is not a collision — a cloned project.json still gets its token', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ nodes: [{ id: 'node-1' }] }, { nodes: [{ id: 'node-1' }] }] })
expect(files()).toEqual(['node-1'])
})
it('folds Unicode case and normalization, not just ASCII', () => {
// Not reachable through NODE_ID_CHARSET today — asserted so the key stays correct if it widens,
// since APFS folds both and a missed fold is the vulnerability.
expect(nodeIdFoldKey('CAFÉ')).toBe(nodeIdFoldKey('café')) // É vs e + combining acute
expect(nodeIdFoldKey('KELVIN')).toBe(nodeIdFoldKey('kelvin')) // U+212A KELVIN SIGN
})
})
/**
* `refreshNodeTokens` is wired to `onPersist`, which fires on every canvas load AND save, so a
* ~375-node workspace paid ~2000 synchronous syscalls on the main thread per save to rewrite bytes
* that cannot change. The inode is the assertion rather than mtime: the writer is tmp+rename, so a
* real rewrite always lands a NEW inode (the tmp is allocated while the old file still exists),
* which no clock resolution can blur.
*/
describe('node token service — writes once, not on every persist', () => {
const ino = (id: string) => fs.statSync(path.join(nodeTokenDir(), id)).ino
it('does not touch the file again for an id already materialised this run', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
const before = canvases.flatMap((c) => c.nodes).map((n) => [n.id, ino(n.id)] as const)
refreshNodeTokens() // what every save costs
ensureNodeToken('node-1') // ...and what every spawn costs
for (const [id, was] of before) expect(ino(id), id).toBe(was)
})
it('rewrites anyway under `force` — the boot sweep re-asserts what is on disk', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
ensureNodeToken('node-1')
const was = ino('node-1')
ensureNodeToken('node-1', { force: true })
expect(ino('node-1')).not.toBe(was)
})
/**
* The short-circuit is a "we wrote it" cache, and before this it was never re-checked against the
* filesystem. Anything that removes `node-tokens/` while the app runs — a cleanup tool, a user
* tidying their data dir, a sync client — therefore made every later refresh a no-op: live
* sessions present an empty header, and every already-PROVEN node takes a hard 403 for the rest
* of the run.
*/
it('re-writes a token file deleted out of band, instead of trusting the cache forever', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
fs.rmSync(nodeTokenDir(), { recursive: true, force: true })
refreshNodeTokens() // an ordinary persist, no `force`
expect(fs.readdirSync(nodeTokenDir()).sort()).toEqual(['node-1', 'node-2', 'node-3'])
})
it('still writes once, not twice, when the file IS there — the stat is not a rewrite', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
const was = ino('node-1')
refreshNodeTokens()
refreshNodeTokens()
expect(ino('node-1')).toBe(was)
})
it('re-materialises a swept id, so a deleted-then-recreated node is not left on legacy', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
ensureNodeToken('node-1')
sweepNodeToken('node-1')
expect(fs.existsSync(path.join(nodeTokenDir(), 'node-1'))).toBe(false)
ensureNodeToken('node-1')
expect(fs.existsSync(path.join(nodeTokenDir(), 'node-1'))).toBe(true)
})
})
/**
* The REMOTE (SSH) materialiser's half. The host is a different filesystem with a different
* writer, but it must be judged by the SAME rules — otherwise a hostile `project.json` bypasses
* the local guards simply by living on an SSH project.
*/
describe('node token service — the remote (SSH) minter', () => {
it('returns null when there is no secret, so a connect spends no round-trips at all', () => {
hookServer.clearNodeAuthSecretForTests()
initNodeTokens({ canvases: () => canvases })
expect(remoteNodeTokenMinter()).toBeNull()
})
it('mints the same token the local writer would file, without touching the local disk', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
const before = fs.readFileSync(path.join(nodeTokenDir(), 'node-1'), 'utf8')
const mint = remoteNodeTokenMinter()!
expect(`${mint('node-1')}\n`).toBe(before)
})
it('refuses a case-folding collision on the remote path too (empty ⇒ the caller sweeps)', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ id: 'p1', nodes: [{ id: 'Node-1' }, { id: 'node-1' }] }] })
const mint = remoteNodeTokenMinter()!
expect(mint('Node-1')).toBe('')
expect(mint('node-1')).toBe('')
expect(mint('node-7')).not.toBe('')
})
it('refuses an unsafe id', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => canvases })
const mint = remoteNodeTokenMinter()!
expect(mint('..')).toBe('')
expect(mint('../x')).toBe('')
})
it('nodeIdsForCanvas returns one project’s node ids, de-duplicated, and nothing for a stranger', () => {
initNodeTokens({
canvases: () => [
{ id: 'p1', nodes: [{ id: 'node-1' }, { id: 'node-1' }, { id: 'node-2' }] },
{ id: 'p2', nodes: [{ id: 'node-3' }] }
]
})
expect(nodeIdsForCanvas('p1')).toEqual(['node-1', 'node-2'])
expect(nodeIdsForCanvas('p2')).toEqual(['node-3'])
expect(nodeIdsForCanvas('nope')).toEqual([])
})
it('the spawn-path writer is a no-op until one is registered, and never throws', async () => {
forgetRemoteNodeTokens('/cm.sock')
setRemoteNodeTokenWriter(null)
expect(() => ensureRemoteNodeToken('/cm.sock', 'node-1')).not.toThrow()
const seen: [string, string[]][] = []
setRemoteNodeTokenWriter((cp, ids) => seen.push([cp, [...ids]]))
ensureRemoteNodeToken('/cm.sock', 'node-1')
await flushCoalesce()
expect(seen).toEqual([['/cm.sock', ['node-1']]])
// a writer that throws must not reach the pty spawn that called it
forgetRemoteNodeTokens('/cm.sock')
setRemoteNodeTokenWriter(() => {
throw new Error('ssh gone')
})
expect(() => ensureRemoteNodeToken('/cm.sock', 'node-1')).not.toThrow()
await flushCoalesce()
setRemoteNodeTokenWriter(null)
})
it('COALESCES a mount burst into ONE remote write, and never rewrites an id twice', async () => {
// The shape that prompted this: a project switch mounts every node in the same tick, and each
// spawn used to be its own ssh exec child on the one multiplexed connection.
forgetRemoteNodeTokens('/cm.sock')
const seen: [string, string[]][] = []
setRemoteNodeTokenWriter((cp, ids) => seen.push([cp, [...ids]]))
for (const id of ['n1', 'n2', 'n3', 'n2']) ensureRemoteNodeToken('/cm.sock', id)
await flushCoalesce()
expect(seen).toEqual([['/cm.sock', ['n1', 'n2', 'n3']]])
// A second burst for ids this run already wrote costs NOTHING at all.
seen.length = 0
for (const id of ['n1', 'n2', 'n3']) ensureRemoteNodeToken('/cm.sock', id)
await flushCoalesce()
expect(seen).toEqual([])
// …and a genuinely new node still gets its token.
ensureRemoteNodeToken('/cm.sock', 'n4')
await flushCoalesce()
expect(seen).toEqual([['/cm.sock', ['n4']]])
setRemoteNodeTokenWriter(null)
forgetRemoteNodeTokens('/cm.sock')
})
it('keeps hosts separate, and a connect-time seed silences the spawn path for what it wrote', async () => {
forgetRemoteNodeTokens('/a.sock')
forgetRemoteNodeTokens('/b.sock')
const seen: [string, string[]][] = []
setRemoteNodeTokenWriter((cp, ids) => seen.push([cp, [...ids]]))
// This is what `materialiseNodeTokens` records after the connect wrote every node's token.
seedRemoteNodeTokens('/a.sock', ['n1', 'n2'])
ensureRemoteNodeToken('/a.sock', 'n1') // already on that host ⇒ no round trip
ensureRemoteNodeToken('/b.sock', 'n1') // a DIFFERENT host has never seen it
await flushCoalesce()
expect(seen).toEqual([['/b.sock', ['n1']]])
// A re-connect re-seeds, and the seed RESETS: the control path is keyed by project, so it can
// point at a different host after a server edit, where nothing of ours has been written.
seen.length = 0
seedRemoteNodeTokens('/a.sock', [])
ensureRemoteNodeToken('/a.sock', 'n1')
await flushCoalesce()
expect(seen).toEqual([['/a.sock', ['n1']]])
setRemoteNodeTokenWriter(null)
forgetRemoteNodeTokens('/a.sock')
forgetRemoteNodeTokens('/b.sock')
})
})
/**
* A token file outlives its node whenever the node leaves the canvas by a path that does not go
* through `ptyManager.destroy(intent:'delete')` — a project removed, a canvas edited elsewhere, a
* hand-rewritten `project.json` — so the dir grows one 0600 file per dead id, forever.
*
* The sweep's authority is deliberately narrow: an id has to have been OBSERVED on a canvas earlier
* this run. `persistedCanvases()` is a view of what has been READ this run, so an id's absence from
* it is not evidence a node is gone — and sweeping a live node's token un-proves it and drops it to
* `legacy`, which after the cutoff is a node that cannot drive the canvas at all.
*/
describe('node token service — a node that leaves the canvas takes its token with it', () => {
it('sweeps the file and releases the latch for an id that was there and now is not', async () => {
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
let live = [{ id: 'stays' }, { id: 'departs' }]
initNodeTokens({ canvases: () => [{ nodes: live }] })
expect(fs.readdirSync(nodeTokenDir()).sort()).toEqual(['departs', 'stays'])
// A departed node may have proved itself while it was still here, and a latch outliving the
// token it was earned with is a permanent 403 on that id if it ever comes back.
const forget = vi.spyOn(hookServer, 'forgetProvenNode')
live = [{ id: 'stays' }]
refreshNodeTokens()
expect(fs.readdirSync(nodeTokenDir())).toEqual(['stays'])
expect(forget).toHaveBeenCalledWith('departs')
forget.mockRestore()
})
it('never sweeps an id it has not seen on a canvas this run', async () => {
// A file from a PREVIOUS run, for a node on a project this run has not read yet. Deleting it
// because it is missing from `canvasNodeIds()` would strand that node the moment its project
// loads — the exact bug the narrow authority exists to avoid.
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ nodes: [{ id: 'known' }] }] })
fs.writeFileSync(path.join(nodeTokenDir(), 'from-a-project-not-loaded-yet'), 'tok\n', { mode: 0o600 })
refreshNodeTokens()
expect(fs.readdirSync(nodeTokenDir()).sort()).toEqual([
'from-a-project-not-loaded-yet',
'known'
])
})
it('sweeps nothing on the BOOT pass, however empty the index still is', async () => {
// `initNodeTokens` runs before the desktop's workspace has necessarily been read. Starting the
// observed set empty is what stops a half-loaded index from costing every live node its token.
hookServer.setNodeAuthSecret(await loadOrCreateNodeAuthSecret())
initNodeTokens({ canvases: () => [{ nodes: [{ id: 'node-1' }] }] })
initNodeTokens({ canvases: () => [] })
expect(fs.readdirSync(nodeTokenDir())).toEqual(['node-1'])
})
})