Skip to content

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.

fix(control): require verified identity for terminal commands

enes2cd159fbae23
diff --git a/CLAUDE.md b/CLAUDE.md
index 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/catch
its three siblings already had. Its three steps stay strictly ordered inside: the merge reads
the 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 derived
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 switch
mid-session applies stored state to whatever the user is doing right then, which is a different
feature 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.md
index 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, measured
diff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.ts
index 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_REFUSAL
if (verb === 'report-issue') return REPORT_ISSUE_CONTROL_REFUSAL
if (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.ts
new file mode 100644
index 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.ts
index 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 it
is 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 also
diff --git a/src/main/canvas-control-shim.test.ts b/src/main/canvas-control-shim.test.ts
index 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.ts
index 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)