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(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.ts
index 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!: () => void
const 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 bDone
release()
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.ts
index 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: string
nodeId: 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 <= max
const 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 = true
constructor(private readonly o: { file: string; seal?: (b: Buffer) => Buffer; unseal?: (b: Buffer) => Buffer }) {}
async load(): Promise<WatchLinkRecord[]> {
- let body: { links?: unknown }
+ let text: string
try {
- 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)) continue
if (e.role !== 'viewer' && e.role !== 'commenter') continue
if (!str(e.label, 40) || !str(e.title, 80) || !num(e.createdAt) || !num(e.expiresAt) || typeof e.secret !== 'string') continue
const 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