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(node-identity): mint node tokens on a Linux desktop with no keyring

review60714074c7a0
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 mobile
reconnecting 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 a
clock years ahead cannot enter strict mode early) with a `settings.hookIdentityStrict` escape hatch
in Settings → Agents. **Trust on first proof latches a node the moment it authenticates, so it
diff --git a/docs/node-identity.md b/docs/node-identity.md
index 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 actual
Two distinct file names (`.json` vs `.bin`) exist so a data dir moved between shells can never have
one 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 is
no `safeStorage` to reach. Inventing a passphrase prompt would make the app un-bootable
unattended, 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 that
cannot 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.
## Migration
diff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.ts
index 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 !== undefined
if ((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.ts
index 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 the
diff --git a/src/core/agents/node-auth-secret.test.ts b/src/core/agents/node-auth-secret.test.ts
index 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 same
diff --git a/src/core/agents/node-auth-secret.ts b/src/core/agents/node-auth-secret.ts
index 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 raw
const 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 existing
const 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.ts
index 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 unblocks
diff --git a/src/main/platform-electron.ts b/src/main/platform-electron.ts
index 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.ts
index 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