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(node-identity): mint node tokens on a Linux desktop with no keyring
review60714074c7a0
diff --git a/CLAUDE.md b/CLAUDE.mdindex 41a2ea385..7dd52db3b 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3126,6 +3126,16 @@ command-bearing opens; this does not add a human-confirm dialog or change mobilereconnecting terminals. These changes share the core listener in Desktop and Server Edition;the mobile wire protocol and node-identity rules are unchanged.+ - **No keyring is not "no identity" (#1088).** Electron 42 on a Linux session without Secret+ Service/kwallet picks `basic_text` and `safeStorage.encryptString` THROWS (measured under xvfb).+ The desktop secret load used to reject on every boot ⇒ no node token was ever written ⇒ `send` /+ `settings` refused forever with no visible cause. The loader now falls back to the Server+ Edition's raw 0600 `node-auth-key.bin` when it cannot seal and no sealed key exists (a sealed key+ it merely cannot unseal still rejects — rotating it orphans codex thread records), and both shells+ record a failed arming via `hookServer.setNodeIdentityUnavailable`, which a verified-only refusal+ then names. A secret that cannot be stored must degrade to the weaker store, never to a feature+ that is silently off.+Enforcement is dated (`NODE_IDENTITY_STRICT_AFTER`, 2026-10-13, read through `isStrictInstant` so aclock years ahead cannot enter strict mode early) with a `settings.hookIdentityStrict` escape hatchin Settings → Agents. **Trust on first proof latches a node the moment it authenticates, so itdiff --git a/docs/node-identity.md b/docs/node-identity.mdindex 2cc6e7c4f..2834ee9cc 100644--- a/docs/node-identity.md+++ b/docs/node-identity.md@@ -151,7 +151,7 @@ the data dir and restarting. What that does:| Surface | Holds | How || --- | --- | --- |-| Desktop (Electron) | The **secret** | `node-auth-key.json`, sealed with `safeStorage`, 0600, tmp+rename. |+| Desktop (Electron) | The **secret** | `node-auth-key.json`, sealed with `safeStorage`, 0600, tmp+rename — or, when `safeStorage` cannot seal at all (Linux with no keyring, issue #1088), `node-auth-key.bin` exactly as the Server Edition stores it. || Server Edition | The **secret** | `node-auth-key.bin`, **raw 32 bytes**, 0600, tmp+rename. || SSH host | Per-node **tokens** only | `$HOME/.nodeterm/node-tokens/<nodeId>`, 0600 under a 0700 dir, written over the ControlMaster with the token on **stdin**. || Phone | Nothing | No secret, no token, no change. |@@ -163,6 +163,18 @@ in that configuration the sealing is obfuscation, and the protection that actualTwo distinct file names (`.json` vs `.bin`) exist so a data dir moved between shells can never haveone format misread as the other.+**And on Linux it may not seal at all** (issue #1088, measured on Electron 42 under xvfb with no+session bus): a session with no Secret Service or kwallet — a bare window manager — selects+`basic_text`, reports `isEncryptionAvailable() === false`, and `encryptString` **throws**. The+loader used to reject on every boot, so the instance ran with no secret forever: no token file was+ever written, every session was `legacy`, and every verified-only verb (`send`, `settings`, …) was+refused permanently, while `hook-endpoint.env` still advertised a token dir that would never fill.+Now, when sealing throws and no sealed key exists, the desktop writes the raw 0600 `.bin` — the+Server Edition's format, which on that backend gives up nothing real. A raw key from an earlier+keyring-less boot is reused when a keyring appears later (never rotated); a **sealed** key that+merely cannot be unsealed right now (keyring locked at boot) still fails the load rather than being+replaced, because rotating the secret orphans every bound codex thread.+**The Server Edition stores it raw, deliberately.** A headless Linux host has no keychain; there isno `safeStorage` to reach. Inventing a passphrase prompt would make the app un-bootableunattended, which is the entire point of that edition. The in-repo precedents are the same@@ -239,8 +251,12 @@ can act on. A sentence it can read is the better failure.**Why no gate at all when there is no secret.** An instance that cannot mint can never verify anyone,so warning or refusing `legacy` there would hit **every** caller on the machine with advice thatcannot work ("restart this node to pick up an identity" — there is none to pick up). That is the-desktop's `safeStorage`-unavailable path and the Server Edition's uncreatable-key-file path; both-keep working exactly as before.+desktop's locked-keyring path and the Server Edition's uncreatable-key-file path; the open verbs+keep working exactly as before. The **verified-only** verbs cannot (nothing is verified), so their+flat refusal is followed by `identityUnavailableNote`: one sentence saying the cause is the+INSTANCE, with the error the shell recorded via `hookServer.setNodeIdentityUnavailable` — the only+place a refusal here carries a diagnosis, because it is a fact about the machine that no caller can+act on. Before #1088 that cause was a `console.warn` nobody could see.## Migrationdiff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.tsindex 8449d085d..64f7b79ef 100644--- a/src/core/agents/hook-server.ts+++ b/src/core/agents/hook-server.ts@@ -335,6 +335,23 @@ export { REPORT_OUTCOME_CONTROL_REFUSAL }/** The flat refusal for an unverified `issues` / `prs` read (core/github/control-read.ts). */export const GITHUB_READ_CONTROL_REFUSAL = 'GitHub lane read refused.'+/**+ * Issue #1088: appended to a verified-only refusal when THIS INSTANCE has no node-auth secret, so no+ * session on the machine can ever be `verified`. The flat refusals deliberately carry no per-node+ * diagnosis (advice to a prober), but this is not one: it is a fact about the instance that no+ * caller can change, and leaving it out made the refusal permanent AND causeless — the reporter+ * had only a `console.warn` in a log they could not see. It names no token and no restart, because+ * neither helps; the cause is fixed on the machine, then NodeTerm is restarted.+ */+export function identityUnavailableNote(reason: string | null): string {+ const why = reason ? ` (${reason.replace(/\s+/g, ' ').trim().slice(0, 200)})` : ''+ return (+ `Node identity is unavailable in this NodeTerm instance: it could not load its node-identity key at startup${why}, ` ++ 'so no session on this machine can be verified and restarting a node will not help. ' ++ 'Fix the cause and restart NodeTerm; details are in its log under [node-identity].'+ )+}+/** 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.'@@ -456,6 +473,8 @@ export class HookServer {private endpointPath = ''private publishedEndpoint = ''private nodeAuthSecret: Buffer | null = null+ /** Why the shell could not arm a secret, when it tried and failed (see `setNodeIdentityUnavailable`). */+ private nodeIdentityUnavailableReason: string | null = null/*** `settings.hookIdentityStrict`, read LIVE (a getter, not a snapshot) so flipping it in Settings* takes effect on the next request rather than the next launch. `undefined` — the default, and@@ -634,6 +653,17 @@ export class HookServer {setNodeAuthSecret(secret: Uint8Array): void {if (secret.byteLength < 32) throw new Error('Invalid NodeTerm node-auth secret')this.nodeAuthSecret = Buffer.from(secret)+ this.nodeIdentityUnavailableReason = null+ }++ /**+ * The shell's boot-time arming FAILED (issue #1088). Recorded so a verified-only refusal can say+ * the cause is the instance, not the node — see `identityUnavailableNote`. Both shells call it+ * from the catch around their arming; a later successful `setNodeAuthSecret` supersedes it.+ */+ setNodeIdentityUnavailable(reason: unknown): void {+ this.nodeIdentityUnavailableReason =+ reason instanceof Error ? reason.message : typeof reason === 'string' ? reason : 'unknown error'}/** True once a valid secret is set; false before, and after a failed load (nothing was set). The@@ -651,6 +681,7 @@ export class HookServer {/** Test seam only: this server is a module singleton, so its secret otherwise leaks across tests. */clearNodeAuthSecretForTests(): void {this.nodeAuthSecret = null+ this.nodeIdentityUnavailableReason = null}/**@@ -811,7 +842,9 @@ export class HookServer {// plain terminals keep their existing policy. Both shells and transports use this gate.const commandOpen = verb === 'open-terminal' && args.cmd !== undefinedif ((requiresVerified.has(verb) || commandOpen) && verdict !== 'verified') {- const refusal = verifiedRefusalFor(verb)+ const refusal = this.identityAvailable()+ ? verifiedRefusalFor(verb)+ : `${verifiedRefusalFor(verb)} ${identityUnavailableNote(this.nodeIdentityUnavailableReason)}`if (wantsText) {res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })res.end(`${refusal}\n`)diff --git a/src/core/agents/messaging-verified-only.test.ts b/src/core/agents/messaging-verified-only.test.tsindex 6a87e774f..d64121d0a 100644--- a/src/core/agents/messaging-verified-only.test.ts+++ b/src/core/agents/messaging-verified-only.test.ts@@ -136,6 +136,33 @@ describe('send/reply require `verified` — and controlPolicy is NOT the decider})})+describe('issue #1088: a refusal caused by the INSTANCE says so', () => {+ it('names the unavailable node identity and the shell-reported cause, still refusing', async () => {+ // A keyring-less Linux desktop could not arm a secret at all, so EVERY session was legacy and+ // `send`/`settings` were refused forever with only the flat sentence — no visible cause.+ hookServer.clearNodeAuthSecretForTests()+ hookServer.setNodeIdentityUnavailable(new Error('Encryption is not available.'))+ try {+ for (const verb of ['send', 'settings'] as const) {+ const res = await post(verb, 'n-src', undefined, 'text/plain')+ expect(res.status, verb).toBe(403)+ const text = (await res.text()).trim()+ expect(text.startsWith(verifiedRefusalFor(verb)), verb).toBe(true)+ expect(text, verb).toContain('Node identity is unavailable in this NodeTerm instance')+ expect(text, verb).toContain('Encryption is not available.')+ const json = (await (await post(verb, 'n-src')).json()) as { error: string }+ expect(json.error, verb).toContain('Node identity is unavailable')+ }+ expect(handled).toEqual([])+ } finally {+ hookServer.setNodeAuthSecret(SECRET)+ }+ // Arming a secret supersedes the recorded failure: back to the flat, diagnosis-free sentence.+ const res = await post('send', 'n-src', undefined, 'text/plain')+ expect((await res.text()).trim()).toBe(MESSAGING_CONTROL_REFUSAL)+ })+})+describe('where the verbs sit in the routing tables', () => {// `needsLiveCanvas('send'/'reply') === false` is pinned where the function lives —// `src/renderer/lib/controlRouting.test.ts` — because this core project cannot import thediff --git a/src/core/agents/node-auth-secret.test.ts b/src/core/agents/node-auth-secret.test.tsindex 8ecad5160..015b43487 100644--- a/src/core/agents/node-auth-secret.test.ts+++ b/src/core/agents/node-auth-secret.test.ts@@ -126,6 +126,46 @@ describe('node-auth secret behind CorePlatform', () => {expect(fs.existsSync(path.join(dir, 'node-auth-key.bin'))).toBe(false)})+ // Issue #1088 — Electron 42 on a Linux session with no Secret Service/kwallet: backend+ // `basic_text`, isEncryptionAvailable() false, encryptString THROWS. Measured under xvfb.+ const noKeyring = (): Buffer => {+ throw new Error('Error while encrypting the text provided to safeStorage.encryptString. Encryption is not available.')+ }+ const cannotUnseal = (): Buffer => {+ throw new Error('Error while decrypting the ciphertext provided to safeStorage.decryptString. Decryption is not available.')+ }++ it('Desktop without a usable keyring: stores the secret raw 0600 instead of running legacy forever', async () => {+ initPlatform(fakePlatform({ userDataDir: dir, sealSecret: noKeyring, unsealSecret: cannotUnseal }))+ const first = await loadOrCreateNodeAuthSecret()+ expect(first.byteLength).toBe(32)+ const file = path.join(dir, 'node-auth-key.bin')+ expect(fs.readFileSync(file).equals(first)).toBe(true)+ expect(mode(file)).toBe(0o600)+ expect(fs.existsSync(path.join(dir, 'node-auth-key.json'))).toBe(false)++ // Restart-stable: the next boot (still no keyring) reads the same secret, so tokens keep verifying.+ resetNodeAuthSecretForTests()+ expect((await loadOrCreateNodeAuthSecret()).equals(first)).toBe(true)++ // And a keyring that appears later does not rotate it (the secret signs codex thread records).+ resetPlatformForTests()+ initPlatform(fakePlatform({ userDataDir: dir, sealSecret: xor, unsealSecret: xor }))+ resetNodeAuthSecretForTests()+ expect((await loadOrCreateNodeAuthSecret()).equals(first)).toBe(true)+ expect(fs.existsSync(path.join(dir, 'node-auth-key.json'))).toBe(false)+ })++ it('Desktop: a SEALED key that cannot be unsealed right now still rejects — never replaced by a raw one', async () => {+ const file = path.join(dir, 'node-auth-key.json')+ fs.writeFileSync(file, sealedBody(randomBytes(32)), { mode: 0o600 })+ const before = fs.readFileSync(file, 'utf8')+ initPlatform(fakePlatform({ userDataDir: dir, sealSecret: noKeyring, unsealSecret: cannotUnseal }))+ await expect(loadOrCreateNodeAuthSecret()).rejects.toThrow(/Decryption is not available/)+ expect(fs.readFileSync(file, 'utf8')).toBe(before)+ expect(fs.existsSync(path.join(dir, 'node-auth-key.bin'))).toBe(false)+ })+it('reject-then-retry: a rejected load clears the single-flight cache so a later healthy call succeeds', async () => {// The whole fail-open series leans on this: if a rejection LEFT the rejected promise cached, the// shell's catch would swallow it once and every subsequent boot-path retry would re-await the samediff --git a/src/core/agents/node-auth-secret.ts b/src/core/agents/node-auth-secret.tsindex 779f6df6f..5395989fc 100644--- a/src/core/agents/node-auth-secret.ts+++ b/src/core/agents/node-auth-secret.ts@@ -91,28 +91,61 @@ async function adoptLegacy(dir: string): Promise<Buffer | null> {}}+/**+ * Issue #1088. A desktop shell that CAN seal in principle may still be unable to seal on this+ * machine: Electron 42 on a Linux session with no Secret Service / kwallet (a bare window manager —+ * Arch + sway/i3 is the reported case) selects the `basic_text` backend, answers+ * `isEncryptionAvailable() === false`, and `encryptString` THROWS ("Encryption is not available").+ * Measured on this repo's Electron under xvfb with no session bus.+ *+ * Before this, that throw rejected the load on EVERY boot, the shell's catch put the whole instance+ * in legacy mode, no token file was ever written, and every verified-only verb (`send`, `settings`,+ * …) was refused forever — while hook-endpoint.env still advertised a token dir that would never+ * fill. So when sealing is impossible AND no sealed key exists, the desktop stores the secret+ * exactly as the Server Edition does: raw 32 bytes, 0600, `node-auth-key.bin`. On that backend+ * "sealed" would only ever have been obfuscation under a hard-coded key (docs/node-identity.md);+ * the 0600 mode is the protection that holds either way.+ *+ * What this deliberately does NOT do: replace a sealed key it merely cannot UNSEAL right now+ * (keyring locked at boot). That key signs the codex thread→node records, so rotating it would+ * orphan every bound thread — the load still rejects there, and the shell reports why.+ */async function loadSealed(dir: string): Promise<Buffer> {try {return decodeSealed(await fs.readFile(sealedFile(dir), 'utf8'))} catch (error) {if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error}+ // A raw key from an earlier keyring-less boot wins over minting: it is this machine's identity.+ const raw = await readRaw(dir)+ if (raw) return rawconst secret = (await adoptLegacy(dir)) ?? randomBytes(32)- await persistSealed(dir, secret)+ try {+ await persistSealed(dir, secret)+ } catch (error) {+ console.warn('[node-identity] cannot seal the node-auth key (no usable OS keyring) — storing it 0600 instead', error)+ await persistFile(rawFile(dir), secret)+ }return secret}-async function loadRaw(dir: string): Promise<Buffer> {- const file = rawFile(dir)+/** The raw key file, or null when there is none. Any other read failure / wrong length throws. */+async function readRaw(dir: string): Promise<Buffer | null> {try {- const buf = await fs.readFile(file)+ const buf = await fs.readFile(rawFile(dir))if (buf.byteLength !== 32) throw new Error('node-auth key is invalid')return buf} catch (error) {if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error+ return null}+}++async function loadRaw(dir: string): Promise<Buffer> {+ const existing = await readRaw(dir)+ if (existing) return existingconst secret = randomBytes(32)- await persistFile(file, secret)+ await persistFile(rawFile(dir), secret)return secret}diff --git a/src/main/index.ts b/src/main/index.tsindex 89446a8a7..6fc73a230 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -2123,6 +2123,8 @@ app.whenReady().then(async () => {initNodeTokens({ canvases: () => workspaceStore.persistedCanvases() })} catch (error) {console.warn('[node-identity] no secret — hook identity unavailable, running legacy', error)+ // Issue #1088: a verified-only refusal must be able to say the cause is this instance.+ hookServer.setNodeIdentityUnavailable(error)}// Probes the CLI for `--remote`, installs the launcher, and publishes the construction-time// answer. MUST stay after the secret above and before the window: it is what unblocksdiff --git a/src/main/platform-electron.ts b/src/main/platform-electron.tsindex 938655e0f..28324d762 100644--- a/src/main/platform-electron.ts+++ b/src/main/platform-electron.ts@@ -206,8 +206,9 @@ export function electronPlatform(): ElectronPlatform {// Seal / unseal node secrets at rest with the OS keychain. Byte-in byte-out, mirroring #167's// codex-node-auth-key.json shape: encrypt the UTF-8 content of the passed buffer, decrypt back to// the same bytes. Both are supplied together (a shell must supply BOTH hooks or NEITHER — see- // CorePlatform). If the keychain is unavailable safeStorage throws, which node-auth-secret.ts- // surfaces as a rejected load; both shells catch that and run legacy (fail-open), never crash.+ // CorePlatform). If the keychain is unavailable safeStorage throws: node-auth-secret.ts then stores+ // a NEW secret raw at 0600 (issue #1088 — Linux with no keyring), and only a sealed key it cannot+ // unseal rejects the load, which the shell catches into legacy (fail-open), never a crash.sealSecret: (b) => safeStorage.encryptString(b.toString('utf8')),unsealSecret: (b) => Buffer.from(safeStorage.decryptString(b), 'utf8'),}diff --git a/src/server/index.ts b/src/server/index.tsindex 7586b3b56..bb6342bf6 100644--- a/src/server/index.ts+++ b/src/server/index.ts@@ -724,6 +724,8 @@ export async function startServer(await armServerNodeIdentity(hookServer, () => workspaceStore.persistedCanvases())} catch (error) {console.warn('[node-identity] no secret — hook identity unavailable, running legacy', error)+ // Issue #1088: a verified-only refusal must be able to say the cause is this instance.+ hookServer.setNodeIdentityUnavailable(error)}// The Server Edition has the same local app-server, signed node tokens, and persistent canvas