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
fix(control): require verified identity for terminal commands
enes2cd159fbae23
diff --git a/CLAUDE.md b/CLAUDE.mdindex f108819c7..cb2a180f4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1910,6 +1910,14 @@ else, and its context links must keep classifying across restarts).- The claude/gemini loop body became `installJsonAgentRemote`, with the same fail-open try/catchits three siblings already had. Its three steps stay strictly ordered inside: the merge readsthe file the write then replaces.++**Command-bearing terminal opens (issue #653):** the shared hook-server route requires verified+node identity whenever `open-terminal` carries `cmd`, including an empty value or a dry run.+The strict-policy override and foreign-instance fallback cannot release this gate. Desktop plain+terminal opens keep their existing identity policy; Server Edition still requires verification+for every control verb. Legacy mobile/SSH callers must present this instance’s node token for+command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.+- **Per-node hook identity** (`src/core/agents/node-auth-*.ts`, `node-token-*.ts`,`node-identity-policy.ts` — full write-up in **`docs/node-identity.md`**) — the shared bearer proves"a session on this machine", never *which* session, so every node also gets a capability deriveddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0223794bd..042511889 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -611,6 +611,13 @@ examples). If the same effect also WRITES, latch its first run: otherwise switchmid-session applies stored state to whatever the user is doing right then, which is a differentfeature from the one they asked for.+**Command-bearing terminal opens (issue #653):** the shared hook-server route requires verified+node identity whenever `open-terminal` carries `cmd`, including an empty value or a dry run.+The strict-policy override and foreign-instance fallback cannot release this gate. Desktop plain+terminal opens keep their existing identity policy; Server Edition still requires verification+for every control verb. Legacy mobile/SSH callers must present this instance’s node token for+command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.+## Testing`npm test` must pass, and `npm run typecheck` is the fastest gate.diff --git a/docs/node-identity.md b/docs/node-identity.mdindex e081d43f9..012af8bc3 100644--- a/docs/node-identity.md+++ b/docs/node-identity.md@@ -51,6 +51,13 @@ apart from a forgery.| `src/core/agents/hook-server.ts` | The routes that apply it, and the trust-on-first-proof latch. || `src/shared/node-identity.ts` | The cutoff DATE, the one string both the server and Settings read. |+**Command-bearing terminal opens (issue #653):** the shared hook-server route requires verified+node identity whenever `open-terminal` carries `cmd`, including an empty value or a dry run.+The strict-policy override and foreign-instance fallback cannot release this gate. Desktop plain+terminal opens keep their existing identity policy; Server Edition still requires verification+for every control verb. Legacy mobile/SSH callers must present this instance’s node token for+command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.+## The threat model### What was actually wrong, measureddiff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.tsindex c23386d7e..1afd7362f 100644--- a/src/core/agents/hook-server.ts+++ b/src/core/agents/hook-server.ts@@ -259,6 +259,7 @@ export const REPORT_ISSUE_CONTROL_REFUSAL = 'Issue reporting refused.'/** The verified-only refusal, worded for the verb that was refused. */export function verifiedRefusalFor(verb: string): string {+ if (verb === 'open-terminal') return 'Terminal command refused.'if (verb === 'settings') return SETTINGS_CONTROL_REFUSALif (verb === 'report-issue') return REPORT_ISSUE_CONTROL_REFUSALif (verb === 'sticky') return STICKY_CONTROL_REFUSAL@@ -616,7 +617,11 @@ class HookServer {// VERIFIED-ONLY VERBS, decided on the VERDICT and never on the decision: the policy's// `decision` is what the escape hatch and the warning window can reach, and neither may// reach these. See `requiresVerified` for the whole argument.- if (requiresVerified.has(verb) && verdict !== 'verified') {+ // Issue #653: command execution requires proof even when rollout policy allows+ // legacy callers. Presence (including empty --cmd and dry runs) decides this;+ // plain terminals keep their existing policy. Both shells and transports use this gate.+ const commandOpen = verb === 'open-terminal' && args.cmd !== undefined+ if ((requiresVerified.has(verb) || commandOpen) && verdict !== 'verified') {const refusal = verifiedRefusalFor(verb)if (wantsText) {res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })diff --git a/src/core/agents/open-terminal-verified.test.ts b/src/core/agents/open-terminal-verified.test.tsnew file mode 100644index 000000000..8ca2b4e21--- /dev/null+++ b/src/core/agents/open-terminal-verified.test.ts@@ -0,0 +1,100 @@+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'+import fs from 'node:fs'+import os from 'node:os'+import path from 'node:path'+import http from 'node:http'+import { initPlatform, resetPlatformForTests } from '../platform'+import { fakePlatform } from '../platform-fake'+import { hookServer } from './hook-server'+import { nodeAuthToken } from './node-auth-token'++const secret = Buffer.alloc(32, 5)+const foreign = Buffer.alloc(32, 9)+let dir: string+let handled: boolean[] = []++beforeAll(async () => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-cmd-auth-'))+ resetPlatformForTests()+ initPlatform(fakePlatform({ userDataDir: dir }))+ await hookServer.start()+ hookServer.setNodeAuthSecret(secret)+ hookServer.setControlHandler(async ({ verified }) => {+ handled.push(verified)+ return { ok: true, message: 'fixture only; no terminal spawned' }+ })+})+beforeEach(() => { handled = [] })+afterAll(() => {+ hookServer.setIdentityStrictOverride(() => undefined)+ hookServer.clearNodeAuthSecretForTests()+ hookServer.stop()+ resetPlatformForTests()+ fs.rmSync(dir, { recursive: true, force: true })+})++function post(socket: boolean, json: boolean, args: Record<string, string>, token?: string) {+ const body = json ? JSON.stringify({ nodeId: 'source', args }) : new URLSearchParams({+ nodeId: 'source', ...Object.fromEntries(Object.entries(args).map(([k, v]) => [`arg.${k}`, v]))+ }).toString()+ return new Promise<{ status: number; body: string }>((resolve, reject) => {+ const req = http.request({+ ...(socket ? { socketPath: hookServer.getSockPath() } : { host: '127.0.0.1', port: hookServer.getPort() }),+ path: '/control/open-terminal', method: 'POST',+ headers: {+ 'x-nodeterm-hook-token': hookServer.getToken(),+ ...(token === undefined ? {} : { 'x-nodeterm-node-token': token }),+ 'content-type': json ? 'application/json' : 'application/x-www-form-urlencoded',+ accept: json ? 'application/json' : 'text/plain'+ }+ }, (res) => {+ let text = ''+ res.setEncoding('utf8')+ res.on('data', (chunk) => { text += chunk })+ res.on('end', () => resolve({ status: res.statusCode!, body: text }))+ })+ req.on('error', reject)+ req.end(body)+ })+}++for (const socket of [false, true]) {+ describe(socket ? 'unix socket' : 'TCP', () => {+ for (const json of [false, true]) {+ it(`requires identity whenever cmd is present (${json ? 'JSON' : 'form/text'})`, async () => {+ for (const strict of [false, true, undefined]) {+ hookServer.setIdentityStrictOverride(() => strict)+ const cases: Record<string, string>[] = [+ { cmd: 'fixture-command' }, { cmd: '' }, { cmd: ' ', 'dry-run': '' }+ ]+ for (const args of cases) {+ for (const token of [undefined, '', nodeAuthToken(foreign, 'source')]) {+ const res = await post(socket, json, args, token)+ expect(res.status).toBe(403)+ expect(json ? JSON.parse(res.body).error : res.body.trim()).toBe('Terminal command refused.')+ }+ expect(handled).toEqual([])+ expect((await post(socket, json, args, nodeAuthToken(secret, 'other'))).status).toBe(403)+ expect(handled).toEqual([])+ expect((await post(socket, json, args, nodeAuthToken(secret, 'source'))).status).toBe(200)+ expect(handled).toEqual([true])+ handled = []+ }+ }+ })+ }+ it('preserves plain terminal policy and fails closed without an identity secret', async () => {+ hookServer.setIdentityStrictOverride(() => false)+ expect((await post(socket, true, {})).status).toBe(200)+ expect(handled).toEqual([false])+ handled = []+ hookServer.clearNodeAuthSecretForTests()+ try {+ expect((await post(socket, true, { cmd: 'fixture-command' })).status).toBe(403)+ expect(handled).toEqual([])+ expect((await post(socket, true, {})).status).toBe(200)+ expect(handled).toEqual([false])+ } finally { hookServer.setNodeAuthSecret(secret) }+ })+ })+}diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex 61d41670b..021206733 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -423,7 +423,7 @@ export function buildCanvasControlInstructions(shimPath: string): string {'Verbs:','- `list` — current nodes (id, kind, title). Start here when you need a node id.','- `help` — print the verb list. Answered by the shim itself, so it works even if the app is down.',- '- `open-terminal [--count N] [--cwd P] [--cmd C] [--group <id>] [--after <id,id>] [--project <id>]` — open N plain terminals.',+ '- `open-terminal [--count N] [--cwd P] [--cmd C] [--group <id>] [--after <id,id>] [--project <id>]` — open N plain terminals. `--cmd` requires verified node identity.','- `open-claude [--count N] [--cwd P] [--prompt T | --prompt-file F] [--model M] [--group <id>] [--after <id,id>] [--project <id>]` — open N Claude sessions.',`- \`open-agent --agent ${agentChoices} [--count N] [--cwd P] [--prompt T | --prompt-file F] [--model M] [--group <id>] [--after <id,id>] [--project <id>]\` — open`,' any agent CLI. `--group` parents the node(s) into a group frame; a worktree-bound group also',@@ -876,7 +876,7 @@ Verbs:not seven. It clears itself the moment that station completes another turn.- \`help\` — print the verb list. The shim answers this itself, without reaching the app, so itis also what to run when you are unsure whether the control endpoint is alive.-- \`open-terminal [--count N] [--cwd P] [--cmd C] [--group <id>] [--after <id,id>] [--project <id>]\` — open N plain terminals (default 1).+- \`open-terminal [--count N] [--cwd P] [--cmd C] [--group <id>] [--after <id,id>] [--project <id>]\` — open N plain terminals (default 1). \`--cmd\` requires verified node identity.- \`open-claude [--count N] [--cwd P] [--prompt T | --prompt-file F] [--model M] [--group <id>] [--after <id,id>] [--project <id>]\` — open N Claude sessions (default 1).- \`open-agent --agent ${agentChoices} [--count N] [--cwd P] [--prompt T | --prompt-file F] [--model M] [--group <id>] [--after <id,id>] [--project <id>]\` — open N sessions of any agent CLI.\`--group\` parents the node(s) into an existing group frame; a worktree-bound group alsodiff --git a/src/main/canvas-control-shim.test.ts b/src/main/canvas-control-shim.test.tsindex 5d776b8f7..38212d9e1 100644--- a/src/main/canvas-control-shim.test.ts+++ b/src/main/canvas-control-shim.test.ts@@ -118,16 +118,6 @@ describe('canvas-control shim', () => {expect(received.at(-1)?.args).toEqual({ count: '2', verbose: '', cwd: '/tmp' })})- it('--flag=value carries a value that itself starts with -- (unexpressible before)', async () => {- await callShim(['open-terminal', '--cmd=--version', '--cwd', '/srv'])- expect(received.at(-1)?.args).toEqual({ cmd: '--version', cwd: '/srv' })- })-- it('--flag=value splits on the FIRST =, and the rest survives urlencoding', async () => {- await callShim(['open-terminal', '--cmd=env A=1 B="2 3"'])- expect(received.at(-1)?.args).toEqual({ cmd: 'env A=1 B="2 3"' })- })-// The peek looks for `--`, not `-`. A single-dash value must still be consumed positionally.it('a value beginning with a single dash is still a value', async () => {await callShim(['rename', '--node', 'n1', '--title', '-7'])@@ -691,8 +681,8 @@ describe('parseControlBody', () => {})})-describe('sticky through the shim (verified-only verb)', () => {- // `sticky` is in `requiresVerified`, so unlike every other shim test these calls must present+describe('verified-only requests through the shim', () => {+ // `sticky` and command-bearing terminal opens require verification, so these calls present// the per-node token — the same file-in-a-directory arrangement `buildPtyEnv` hands a real// session. The secret is scoped to this describe so the rest of the suite keeps exercising the// legacy (no-secret) path.@@ -714,6 +704,16 @@ describe('sticky through the shim (verified-only verb)', () => {const callVerified = (args: string[]) => callShim(args, { NODETERM_NODE_TOKEN_DIR: tokenDir })+ it('--flag=value carries a value that itself starts with -- (unexpressible before)', async () => {+ await callVerified(['open-terminal', '--cmd=--version', '--cwd', '/srv'])+ expect(received.at(-1)?.args).toEqual({ cmd: '--version', cwd: '/srv' })+ })++ it('--flag=value splits on the FIRST =, and the rest survives urlencoding', async () => {+ await callVerified(['open-terminal', '--cmd=env A=1 B="2 3"'])+ expect(received.at(-1)?.args).toEqual({ cmd: 'env A=1 B="2 3"' })+ })+it('maps the bare positional to --node, title with spaces intact', async () => {await callVerified(['sticky', 'Linear: my tickets', '--text', '# Tickets'])expect(received.at(-1)).toMatchObject({diff --git a/src/shared/control-verbs.ts b/src/shared/control-verbs.tsindex b6e531fcb..b928b1a6e 100644--- a/src/shared/control-verbs.ts+++ b/src/shared/control-verbs.ts@@ -57,8 +57,8 @@ export const DESTRUCTIVE_VERBS: ReadonlySet<string> = new Set([* and answers `false` here (see the file header). And not "is this verb gated": the dialog itself* is hand-written per case, so this returning `true` for a new verb would gate nothing on its own.*- * `open-terminal --cmd` is deliberately NOT in the set and never was; the 2026-08-13 argv-leak- * writeup in `docs/node-identity.md` is the record of what that costs when the bearer leaks.+ * `open-terminal --cmd` is not confirm-gated; hook-server requires verified node identity+ * whenever cmd is present (issue #653), independently of the rollout policy.*/export function isDestructiveVerb(verb: string): boolean {return DESTRUCTIVE_VERBS.has(verb)