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(watch-link): seal the secret as base64 text, never write over an unreadable file
reviewa48863c83852
diff --git a/src/core/watch-link/store.test.ts b/src/core/watch-link/store.test.tsindex 54a3266c2..dd0578a02 100644--- a/src/core/watch-link/store.test.ts+++ b/src/core/watch-link/store.test.ts@@ -1,14 +1,15 @@import { describe, it, expect, vi } from 'vitest'-import { readFileSync, statSync, writeFileSync } from 'node:fs'-import { join } from 'node:path'+import { promises as fsp, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'+import { dirname, join } from 'node:path'import { testTmpDir } from '../test-tmp'-import { writeFileAtomic } from '../fs-atomic'-import { WatchLinkStore, type WatchLinkRecord } from './store'+import { renameAtomic, writeFileAtomic } from '../fs-atomic'+import { WatchLinkStore, WatchLinkStoreUnreadable, type WatchLinkRecord } from './store'-// A pass-through spy, so a test can hold one write open (ordering) or fail one (chain recovery).+// Pass-through spies, so a test can hold one write open (ordering), fail one (chain recovery,+// set-aside failure) or count them (a latched store must not write at all).vi.mock('../fs-atomic', async (importOriginal) => {const actual = await importOriginal<typeof import('../fs-atomic')>()- return { ...actual, writeFileAtomic: vi.fn(actual.writeFileAtomic) }+ return { ...actual, writeFileAtomic: vi.fn(actual.writeFileAtomic), renameAtomic: vi.fn(actual.renameAtomic) }})const file = () => join(testTmpDir('wl-'), 'watch-links.json')@@ -21,6 +22,22 @@ const rec = (over: Partial<WatchLinkRecord> = {}): WatchLinkRecord => ({const seal = (b: Buffer) => Buffer.from(b.toString('hex'))const unseal = (b: Buffer) => Buffer.from(b.toString(), 'hex')+// The shape of the real desktop seam (src/main/platform-electron.ts): safeStorage encrypts the+// buffer's UTF-8 TEXT and decrypts back to text. Reversing the code points stands in for the cipher;+// what matters is the two UTF-8 conversions, which mangle any byte sequence that is not valid UTF-8.+const reverseText = (s: string) => [...s].reverse().join('')+const electronSeal = (b: Buffer) => Buffer.from(reverseText(b.toString('utf8')), 'utf8')+const electronUnseal = (b: Buffer) => Buffer.from(reverseText(b.toString('utf8')), 'utf8')+// 0x80..0x9f: every byte a lone UTF-8 continuation byte, so `toString('utf8')` replaces each one.+const HIGH_BYTES = Uint8Array.from({ length: 32 }, (_, i) => 0x80 + i)++const b64 = (b: Uint8Array) => Buffer.from(b).toString('base64')+const rawEntry = (over: Record<string, unknown> = {}) => ({+ linkId: 'AbCdEfGhIjKlMnOpQrStUv', nodeId: 'n1', role: 'viewer', label: 'Ada', title: 'build',+ createdAt: 1, expiresAt: EXPIRES_AT, secret: b64(new Uint8Array(32).fill(7)), sealed: false, ...over+})+const writeLinks = (f: string, links: unknown[], v: unknown = 1) => writeFileSync(f, JSON.stringify({ v, links }))+describe('WatchLinkStore', () => {it('round-trips sealed records and writes 0600', async () => {const f = file()@@ -31,11 +48,21 @@ describe('WatchLinkStore', () => {if (process.platform !== 'win32') expect(statSync(f).mode & 0o777).toBe(0o600)})+ it('round-trips a high-byte secret through an Electron-shaped (UTF-8 text) seam', async () => {+ const f = file()+ const s = new WatchLinkStore({ file: f, seal: electronSeal, unseal: electronUnseal })+ const r = rec({ secret: HIGH_BYTES })+ expect(await s.save([r])).toBe('saved')+ expect(await new WatchLinkStore({ file: f, seal: electronSeal, unseal: electronUnseal }).load()).toEqual([r])+ })+it('stores raw secrets where the platform has no seal (Server Edition)', async () => {const f = file()const s = new WatchLinkStore({ file: f })expect(await s.save([rec()])).toBe('saved')expect(await s.load()).toEqual([rec()])+ expect(await s.save([rec({ secret: HIGH_BYTES })])).toBe('saved')+ expect(await s.load()).toEqual([rec({ secret: HIGH_BYTES })])})it('writes an empty file and reports memory-only when sealing throws', async () => {@@ -45,6 +72,16 @@ describe('WatchLinkStore', () => {expect(JSON.parse(readFileSync(f, 'utf8'))).toEqual({ v: 1, links: [] })})+ it('reports a non-seal error while building the file as failed, and leaves the old file intact', async () => {+ const f = file()+ const s = new WatchLinkStore({ file: f, seal, unseal })+ expect(await s.save([rec()])).toBe('saved')+ const before = readFileSync(f, 'utf8')+ const broken = { ...rec({ linkId: 'BbCdEfGhIjKlMnOpQrStUv' }), secret: undefined } as unknown as WatchLinkRecord+ expect(await s.save([rec(), broken])).toBe('failed')+ expect(readFileSync(f, 'utf8')).toBe(before)+ })+it('an unsealable secret is skipped, and a desktop never accepts a raw one', async () => {const f = file()await new WatchLinkStore({ file: f }).save([rec()]) // raw on disk@@ -64,25 +101,148 @@ describe('WatchLinkStore', () => {expect(await new WatchLinkStore({ file: f }).load()).toEqual([])})+ it('drops an entry whose node id is not a safe node id', async () => {+ const f = file()+ writeLinks(f, [+ rawEntry({ nodeId: '../x', linkId: 'A1CdEfGhIjKlMnOpQrStUv' }),+ rawEntry({ nodeId: 'a b', linkId: 'A2CdEfGhIjKlMnOpQrStUv' }),+ rawEntry({ nodeId: 'x'.repeat(129), linkId: 'A3CdEfGhIjKlMnOpQrStUv' }),+ rawEntry()+ ])+ expect(await new WatchLinkStore({ file: f }).load()).toEqual([rec()])+ })++ it('drops a secret of the wrong length, sealed and unsealed', async () => {+ // Each bad entry is otherwise valid, so nothing but the length check can reject it.+ const f = file()+ writeLinks(f, [rawEntry({ linkId: 'ShortRawGhIjKlMnOpQrSt', secret: b64(new Uint8Array(1).fill(7)) }), rawEntry()])+ expect(await new WatchLinkStore({ file: f }).load()).toEqual([rec()])++ const f2 = file()+ const sealB64 = (bytes: Uint8Array) => seal(Buffer.from(b64(bytes), 'utf8')).toString('base64')+ writeLinks(f2, [+ rawEntry({ linkId: 'ShortSealIjKlMnOpQrStUv'.slice(0, 22), secret: sealB64(new Uint8Array(31).fill(7)), sealed: true }),+ rawEntry({ linkId: 'LongSealhIjKlMnOpQrStUv'.slice(0, 22), secret: sealB64(new Uint8Array(33).fill(7)), sealed: true }),+ rawEntry({ secret: sealB64(new Uint8Array(32).fill(7)), sealed: true })+ ])+ expect(await new WatchLinkStore({ file: f2, seal, unseal }).load()).toEqual([rec()])+ })++ it('returns at most 200 entries', async () => {+ const f = file()+ const id = (i: number) => `L${String(i).padStart(21, '0')}`+ writeLinks(f, Array.from({ length: 250 }, (_, i) => rawEntry({ linkId: id(i) })))+ const loaded = await new WatchLinkStore({ file: f }).load()+ expect(loaded).toHaveLength(200)+ expect(loaded[199].linkId).toBe(id(199))+ })++ it('sets an unparseable file aside and stays writable', async () => {+ const f = file()+ writeFileSync(f, '{nope')+ const s = new WatchLinkStore({ file: f })+ expect(await s.load()).toEqual([])+ expect(existsSync(f)).toBe(false)+ const aside = readdirSync(dirname(f)).filter((n) => n.startsWith('watch-links.json.corrupt-'))+ expect(aside).toHaveLength(1)+ expect(readFileSync(join(dirname(f), aside[0]), 'utf8')).toBe('{nope')+ expect(await s.save([rec()])).toBe('saved')+ expect(await s.load()).toEqual([rec()])+ })++ describe('never writes over a file it could not read', () => {+ const expectLatched = async (s: WatchLinkStore, f: string, before: string) => {+ const writes = vi.mocked(writeFileAtomic).mock.calls.length+ expect(await s.save([])).toBe('failed')+ expect(await s.save([rec()])).toBe('failed')+ expect(vi.mocked(writeFileAtomic).mock.calls.length).toBe(writes)+ expect(readFileSync(f, 'utf8')).toBe(before)+ }++ it('a read error other than ENOENT rejects and latches the store', async () => {+ const f = file()+ expect(await new WatchLinkStore({ file: f }).save([rec()])).toBe('saved')+ const before = readFileSync(f, 'utf8')+ const eio = Object.assign(new Error('EIO: i/o error, open'), { code: 'EIO' })+ const open = vi.spyOn(fsp, 'open').mockRejectedValueOnce(eio)+ const s = new WatchLinkStore({ file: f })+ await expect(s.load()).rejects.toBeInstanceOf(WatchLinkStoreUnreadable)+ open.mockRestore()+ await expectLatched(s, f, before)+ })++ it('a path that cannot be read as a file (a directory) rejects', async () => {+ const f = file()+ mkdirSync(f)+ const s = new WatchLinkStore({ file: f })+ await expect(s.load()).rejects.toBeInstanceOf(WatchLinkStoreUnreadable)+ expect(await s.save([rec()])).toBe('failed')+ expect(statSync(f).isDirectory()).toBe(true)+ })++ it('a file larger than 1 MiB rejects and latches the store', async () => {+ const f = file()+ writeLinks(f, [rawEntry({ pad: 'x'.repeat(1024 * 1024) })])+ const before = readFileSync(f, 'utf8')+ const s = new WatchLinkStore({ file: f })+ await expect(s.load()).rejects.toBeInstanceOf(WatchLinkStoreUnreadable)+ await expectLatched(s, f, before)+ })++ it('a version other than 1 rejects and latches the store', async () => {+ const f = file()+ writeLinks(f, [rawEntry()], 2)+ const before = readFileSync(f, 'utf8')+ const s = new WatchLinkStore({ file: f })+ await expect(s.load()).rejects.toBeInstanceOf(WatchLinkStoreUnreadable)+ await expectLatched(s, f, before)+ })++ it('an unparseable file that cannot be set aside rejects and latches the store', async () => {+ const f = file()+ writeFileSync(f, '{nope')+ vi.mocked(renameAtomic).mockRejectedValueOnce(Object.assign(new Error('EPERM'), { code: 'EPERM' }))+ const s = new WatchLinkStore({ file: f })+ await expect(s.load()).rejects.toBeInstanceOf(WatchLinkStoreUnreadable)+ await expectLatched(s, f, '{nope')+ })+ })+it('serializes saves: an older snapshot never lands after a newer one', async () => {// A revoke is a save of the smaller list. If two writes overlap and finish out of order, the// OLDER snapshot is what stays on disk — and the revoked link comes back at the next boot.const f = file()const s = new WatchLinkStore({ file: f })const { writeFileAtomic: realWrite } = await vi.importActual<typeof import('../fs-atomic')>('../fs-atomic')+ const events: string[] = []let release!: () => voidconst gate = new Promise<void>((r) => { release = r })- vi.mocked(writeFileAtomic).mockImplementationOnce(async (...args) => {- await gate // hold the FIRST write open- return realWrite(...args)- })+ let bLanded!: () => void+ const bDone = new Promise<void>((r) => { bLanded = r })+ vi.mocked(writeFileAtomic)+ .mockImplementationOnce(async (...args) => {+ events.push('a:start')+ await gate // the FIRST write is held until the test releases it+ await realWrite(...args)+ events.push('a:end')+ })+ .mockImplementationOnce(async (...args) => {+ events.push('b:start')+ await realWrite(...args)+ events.push('b:end')+ bLanded()+ })const a = s.save([rec()])const b = s.save([])- // Unserialized, `b` lands while `a` is held; serialized, it is still waiting behind `a`.- await Promise.race([b, new Promise((r) => setTimeout(r, 100))])+ // Let already-scheduled work run (microtasks only, no timers). Serialized, the second write has+ // still not been called: it waits on the held first one. If it has (the bug), let it land+ // before releasing the first, so the out-of-order finish is certain rather than a race.+ for (let i = 0; i < 10; i++) await Promise.resolve()+ if (events.includes('b:start')) await bDonerelease()expect(await a).toBe('saved')expect(await b).toBe('saved')+ expect(events).toEqual(['a:start', 'a:end', 'b:start', 'b:end'])expect(JSON.parse(readFileSync(f, 'utf8'))).toEqual({ v: 1, links: [] })expect(await s.load()).toEqual([])})diff --git a/src/core/watch-link/store.ts b/src/core/watch-link/store.tsindex 710b8e322..b9fe89512 100644--- a/src/core/watch-link/store.ts+++ b/src/core/watch-link/store.ts@@ -4,14 +4,27 @@// desktop there is no plaintext fallback: if sealing throws, the file is written EMPTY and links// live in memory for this run; a raw secret found on a desktop is refused, never adopted.//+// What is sealed is the BASE64 TEXT of the secret, never its bytes. The desktop seam is a string+// seam (`safeStorage.encryptString(b.toString('utf8'))` / `Buffer.from(decryptString(b), 'utf8')`),+// so 32 random bytes — almost never valid UTF-8 — come back as different bytes of a different+// length. Same convention as src/core/agents/node-auth-secret.ts. Unsealed entries (Server Edition)+// are the base64 of the raw bytes.+//+// The store never writes over a file it could not read. Only ENOENT means "no links". Any other+// read error, a file over 1 MiB, or a version other than 1 makes `load()` reject and LATCHES the+// store: every later `save()` resolves 'failed' without touching disk, so the file survives for the+// next boot or a newer build. JSON that does not parse is set aside as `<file>.corrupt-<ts>` and the+// store starts empty; if the set-aside fails, the same latch applies.+//// Saves are SERIALIZED: each write waits for the previous one to finish. Two overlapping atomic// writes can still complete out of order, and the older snapshot would then be what stays on disk —// a revoked link resurrected at the next boot. The snapshot is taken (and sealed) when `save` is// CALLED, so disk order is call order; a failed write never breaks the chain for the next save.import { promises as fs } from 'node:fs'-import { writeFileAtomic } from '../fs-atomic'+import { renameAtomic, writeFileAtomic } from '../fs-atomic'import { LINK_ID_RE } from '../../shared/watch-link/link'import type { WatchLinkRole } from '../../shared/watch-link/protocol'+import { isSafeNodeId } from '../../shared/safe-id'export interface WatchLinkRecord {linkId: string@@ -25,6 +38,20 @@ export interface WatchLinkRecord {}export type SaveOutcome = 'saved' | 'memory-only' | 'failed'+export type WatchLinkStoreUnreadableReason = 'read-error' | 'too-large' | 'unknown-version' | 'set-aside-failed'++/** `load()` could not read the file and will not write over it: the store is now latched. */+export class WatchLinkStoreUnreadable extends Error {+ constructor(+ readonly reason: WatchLinkStoreUnreadableReason,+ message: string,+ options?: { cause?: unknown }+ ) {+ super(message, options)+ this.name = 'WatchLinkStoreUnreadable'+ }+}+interface FileEntry {linkId: stringnodeId: string@@ -37,62 +64,138 @@ interface FileEntry {sealed: boolean}+/** A machine holds a handful of links; anything near this is a hand edit, not our file. */+export const MAX_FILE_BYTES = 1024 * 1024+/** Entries past this are dropped on read. */+export const MAX_ENTRIES = 200+const SECRET_BYTES = 32+const str = (v: unknown, max: number): v is string => typeof v === 'string' && v.length <= maxconst num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)+const codeOf = (e: unknown): string =>+ typeof e === 'object' && e && 'code' in e ? String((e as { code: unknown }).code) : ''++/** Base64 text → the 32-byte secret, or null. Canonical text only: Node's base64 decoder skips+ * characters it does not know, so a mangled string could otherwise decode to *some* bytes. */+function decodeSecret(text: string): Uint8Array | null {+ const bytes = Buffer.from(text, 'base64')+ if (bytes.length !== SECRET_BYTES) return null+ if (bytes.toString('base64') !== text) return null+ return new Uint8Array(bytes)+}export class WatchLinkStore {/** The previous save's write, settled either way: the next write starts only after it. */private writing: Promise<void> = Promise.resolve()+ /** False once `load()` found a file it could not read: never write over it this run. */+ private writable = trueconstructor(private readonly o: { file: string; seal?: (b: Buffer) => Buffer; unseal?: (b: Buffer) => Buffer }) {}async load(): Promise<WatchLinkRecord[]> {- let body: { links?: unknown }+ let text: stringtry {- body = JSON.parse((await fs.readFile(this.o.file, 'utf8')).replace(/\r\n/g, '\n'))+ const handle = await fs.open(this.o.file, 'r')+ try {+ const { size } = await handle.stat()+ if (size > MAX_FILE_BYTES) {+ throw this.latch('too-large', `${this.o.file} is ${size} bytes, over the ${MAX_FILE_BYTES}-byte limit`)+ }+ text = await handle.readFile('utf8')+ } finally {+ await handle.close().catch(() => {})+ }+ } catch (e) {+ if (e instanceof WatchLinkStoreUnreadable) throw e+ if (codeOf(e) === 'ENOENT') return []+ throw this.latch('read-error', `could not read ${this.o.file}: ${(e as Error)?.message ?? e}`, e)+ }++ let body: unknown+ try {+ body = JSON.parse(text.replace(/\r\n/g, '\n'))} catch {+ body = undefined+ }+ if (!body || typeof body !== 'object' || Array.isArray(body)) {+ // Not JSON, or JSON that cannot be any version of this envelope: keep a copy, start empty.+ await this.setAside()return []}+ const { v, links } = body as { v?: unknown; links?: unknown }+ if (v !== 1) throw this.latch('unknown-version', `${this.o.file} has version ${JSON.stringify(v)}, expected 1`)+const out: WatchLinkRecord[] = []- for (const e of Array.isArray(body?.links) ? (body.links as Partial<FileEntry>[]) : []) {- if (!e || !str(e.linkId, 22) || !LINK_ID_RE.test(e.linkId) || !str(e.nodeId, 200) || !e.nodeId) continue+ for (const e of Array.isArray(links) ? (links.slice(0, MAX_ENTRIES) as Partial<FileEntry>[]) : []) {+ if (!e || !str(e.linkId, 22) || !LINK_ID_RE.test(e.linkId) || !isSafeNodeId(e.nodeId)) continueif (e.role !== 'viewer' && e.role !== 'commenter') continueif (!str(e.label, 40) || !str(e.title, 80) || !num(e.createdAt) || !num(e.expiresAt) || typeof e.secret !== 'string') continueconst secret = this.readSecret(e.secret, e.sealed === true)- if (!secret || secret.length !== 32) continue- out.push({ linkId: e.linkId, nodeId: e.nodeId, role: e.role, label: e.label, title: e.title, createdAt: e.createdAt, expiresAt: e.expiresAt, secret })+ if (!secret) continue+ out.push({ linkId: e.linkId, nodeId: e.nodeId as string, role: e.role, label: e.label, title: e.title, createdAt: e.createdAt, expiresAt: e.expiresAt, secret })}return out}- private readSecret(b64: string, sealed: boolean): Uint8Array | null {+ private latch(reason: WatchLinkStoreUnreadableReason, message: string, cause?: unknown): WatchLinkStoreUnreadable {+ this.writable = false+ return new WatchLinkStoreUnreadable(reason, message, cause === undefined ? undefined : { cause })+ }++ private async setAside(): Promise<void> {+ const aside = `${this.o.file}.corrupt-${Date.now()}`try {- const raw = Buffer.from(b64, 'base64')- if (sealed) return this.o.unseal ? new Uint8Array(this.o.unseal(raw)) : null+ await renameAtomic(this.o.file, aside)+ } catch (e) {+ throw this.latch('set-aside-failed', `${this.o.file} does not parse and could not be set aside as ${aside}`, e)+ }+ }++ private readSecret(stored: string, sealed: boolean): Uint8Array | null {+ try {+ if (sealed) {+ if (!this.o.unseal) return null+ return decodeSecret(this.o.unseal(Buffer.from(stored, 'base64')).toString('utf8'))+ }// A desktop (it can seal) never adopts a raw secret it finds on disk.- return this.o.seal ? null : new Uint8Array(raw)+ return this.o.seal ? null : decodeSecret(stored)} catch {return null}}async save(records: readonly WatchLinkRecord[]): Promise<SaveOutcome> {- let links: FileEntry[]+ let links: FileEntry[] = []let outcome: SaveOutcome = 'saved'try {- links = records.map((r) => ({- linkId: r.linkId, nodeId: r.nodeId, role: r.role, label: r.label, title: r.title,- createdAt: r.createdAt, expiresAt: r.expiresAt,- secret: (this.o.seal ? this.o.seal(Buffer.from(r.secret)) : Buffer.from(r.secret)).toString('base64'),- sealed: !!this.o.seal- }))+ for (const r of records) {+ const text = Buffer.from(r.secret).toString('base64')+ let secret = text+ if (this.o.seal) {+ try {+ secret = this.o.seal(Buffer.from(text, 'utf8')).toString('base64')+ } catch {+ // The keychain refused: no plaintext fallback. Write nothing, keep links in memory.+ outcome = 'memory-only'+ break+ }+ }+ links.push({+ linkId: r.linkId, nodeId: r.nodeId, role: r.role, label: r.label, title: r.title,+ createdAt: r.createdAt, expiresAt: r.expiresAt, secret, sealed: !!this.o.seal+ })+ }} catch {- links = []- outcome = 'memory-only'+ // Not a seal failure (a malformed record): leave the old file exactly as it is.+ return 'failed'}+ if (outcome === 'memory-only') links = []const data = JSON.stringify({ v: 1, links })// Everything above ran synchronously at call time, so the chain is extended in call order.- const write = this.writing.then(() => writeFileAtomic(this.o.file, data, { mode: 0o600 }))+ const write = this.writing.then(() => {+ if (!this.writable) throw new Error('watch-link store is latched: it could not read its file')+ return writeFileAtomic(this.o.file, data, { mode: 0o600 })+ })this.writing = write.catch(() => {})try {await write