Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { app } from 'electron'
import { promises as fs } from 'node:fs'
import { join } from 'node:path'
import { ChatStore } from './chatStore.js'
import { resolveDevIsolation } from './devIsolation.js'
import { assertSafeFilesystemSegment } from './pathSafety.js'
import type { ChatAuthorityScope } from './types.js'
/**
* Keep the shared catalog at v2 so pre-paging desktop builds can read the
* bounded compatibility snapshots. Paged transcripts version their own files.
*/
const SCHEMA_VERSION = 2
const PREVIOUS_PAGED_INDEX_VERSION = 3
const LEGACY_INDEX_VERSIONS = new Set([1])
const CORRUPT_QUARANTINE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
// Default base dir derived from the user's home. Tests override via
// __setChatStoreBaseDirForTests to point at a tmpdir, which means the
// app.getPath call below is only reached in production.
let baseDirOverride: string | null = null
function currentBaseDir(): string {
if (baseDirOverride !== null) return baseDirOverride
const isolation = resolveDevIsolation(process.env, process.argv, app.isPackaged)
if (isolation.mode === 'isolated') return join(isolation.plan.runDir, 'chats')
return join(app.getPath('home'), '.clerum', 'chats')
}
let activeChatStore: ChatStore | null = null
let activeUserId: string | null = null
let activeEnvKey: string | null = null
let bindInFlight: { key: string; promise: Promise<void> } | null = null
let bindingGeneration = 0
/** Marker file (per base dir) that records the pre-`envKey` legacy wipe ran. */
const PRE_ENV_MIGRATION_MARKER = '.env-scoped'
/**
* Reject a segment that isn't a single safe path component. It roots both the
* store and the destructive bootstrap wipe (`fs.rm` recursive): `userId` comes
* from the auth server's `me.id` and `envKey` from the runtime config — an
* empty/`.`/`..`/separator-bearing value could make the wipe escape its subdir
* or target the whole base dir.
*/
/**
* Bind the chat store to a `(envKey, user)` directory (spec §5.2). The path is
* namespaced by environment — `<base>/<envKey>/<userId>/…` — so switching
* clusters never surfaces or reconciles another environment's chats (the
* cross-cluster 404-eviction bug). Wipes any legacy (pre-v2) per-agent cache
* first; the desktop is a cache of the server (spec §3.5, §7.1), so a stale
* directory is dropped and re-hydrated from the source of truth.
*/
export async function bindChatStoreForUser(
userId: string,
envKey: string,
options: { legacyEnvKeys?: readonly string[]; teamId?: string | null } = {}
): Promise<void> {
assertSafeFilesystemSegment('userId', userId)
assertSafeFilesystemSegment('envKey', envKey)
for (const legacyEnvKey of options.legacyEnvKeys ?? []) {
assertSafeFilesystemSegment('legacyEnvKey', legacyEnvKey)
}
// Re-binding the same (env, user) is a no-op. Team switches and access-catalog
// refreshes re-call this with an unchanged `me.id`; tearing the store down
// just to rebuild it opens a window where every concurrent chat IPC fails
// with "Not authenticated" (seen as an empty "Latest sessions" at boot).
const authorityScope: ChatAuthorityScope = {
environmentKey: envKey,
userId,
teamId: String(options.teamId || '').trim() || null,
}
if (activeChatStore && activeUserId === userId && activeEnvKey === envKey) {
activeChatStore.setAuthorityScope(authorityScope)
return
}
const bindKey = `${envKey}::${userId}`
if (bindInFlight?.key === bindKey) {
await bindInFlight.promise
if (activeChatStore && activeUserId === userId && activeEnvKey === envKey) {
activeChatStore.setAuthorityScope(authorityScope)
}
return
}
const generation = ++bindingGeneration
const promise = (async () => {
// bind is async (it awaits a directory wipe); until it completes,
// requireChatStore must not keep serving the previous user's store.
activeChatStore = null
activeUserId = null
activeEnvKey = null
const baseDir = currentBaseDir()
// One-shot: drop the pre-`envKey` cache tree (no env level) before rooting
// the env-scoped store. Safe to discard — the server rebuilds it (spec §5.5).
await maybeWipePreEnvLegacyCache(baseDir)
await maybeMigrateEnvScopedCache(baseDir, userId, envKey, options.legacyEnvKeys ?? [])
const userDir = join(baseDir, envKey, userId)
await ensurePrivateDirectory(baseDir)
await ensurePrivateDirectory(join(baseDir, envKey))
await ensurePrivateDirectory(userDir)
await maybeWipeLegacyCache(userDir)
await sweepExpiredCorruptQuarantines(userDir)
if (generation !== bindingGeneration) return
activeChatStore = new ChatStore(userDir)
activeChatStore.setAuthorityScope(authorityScope)
activeUserId = userId
activeEnvKey = envKey
})()
bindInFlight = { key: bindKey, promise }
try {
await promise
} finally {
if (bindInFlight?.promise === promise) bindInFlight = null
}
}
async function ensurePrivateDirectory(directoryPath: string): Promise<void> {
await fs.mkdir(directoryPath, { recursive: true, mode: 0o700 })
// mkdir's mode does not update an existing directory. Tighten legacy
// permissions at the three ancestry boundaries that protect the full cache.
await fs.chmod(directoryPath, 0o700)
}
/**
* One-shot rename from older env-key namespaces into the current env-key
* namespace. This preserves local chat pages when only the env-key derivation
* changed, e.g. REST-only key → REST+RPC key.
*/
async function maybeMigrateEnvScopedCache(
baseDir: string,
userId: string,
envKey: string,
legacyEnvKeys: readonly string[]
): Promise<void> {
const candidates = Array.from(
new Set(legacyEnvKeys.map(key => String(key || '').trim()).filter(key => key && key !== envKey))
)
if (!candidates.length) return
const targetDir = join(baseDir, envKey, userId)
try {
await fs.access(targetDir)
return
} catch {
// target absent → a legacy env-scoped cache may be migrated below
}
for (const legacyEnvKey of candidates) {
const sourceDir = join(baseDir, legacyEnvKey, userId)
try {
await fs.access(sourceDir)
} catch {
continue
}
await fs.mkdir(join(baseDir, envKey), { recursive: true, mode: 0o700 })
try {
await fs.rename(sourceDir, targetDir)
console.info(`[chatStore] Migrated chat cache from legacy env key "${legacyEnvKey}"`)
return
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'EEXIST') return
throw err
}
}
}
/**
* One-shot wipe of the pre-`envKey` cache layout (spec §5.5, D3). Before this
* feature the tree was `<base>/<userId>/<agentRef>/index.json`; it is now
* `<base>/<envKey>/<userId>/<agentRef>/index.json`. Legacy user dirs are
* indistinguishable from env dirs by name, but not by SHAPE: a legacy `<userId>`
* dir has `index.json` at depth 2 (`<userId>/<agentRef>/index.json`), whereas an
* env dir only ever has it at depth 3 (`<envKey>/<userId>/<agentRef>/index.json`).
* So any top-level dir with an `index.json` in one of its children is legacy and
* is dropped.
* Guarded by a marker file so it runs exactly once (the first launch after the
* update, before any env dir exists); it never touches env-scoped subtrees.
*/
async function maybeWipePreEnvLegacyCache(baseDir: string): Promise<void> {
const markerPath = join(baseDir, PRE_ENV_MIGRATION_MARKER)
try {
await fs.access(markerPath)
return // already migrated
} catch {
// marker absent → run the one-shot below
}
let entries
try {
entries = await fs.readdir(baseDir, { withFileTypes: true })
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
// Fresh install — nothing legacy to wipe. Create the base + marker so the
// scan never runs again.
await fs.mkdir(baseDir, { recursive: true, mode: 0o700 })
await writeMigrationMarker(markerPath)
return
}
throw err
}
for (const entry of entries) {
if (!entry.isDirectory()) continue
const topDir = join(baseDir, entry.name)
if (await looksLikeLegacyUserDir(topDir)) {
console.warn(`[chatStore] Wiping pre-envKey legacy cache dir "${entry.name}"`)
await fs.rm(topDir, { recursive: true, force: true })
}
}
await writeMigrationMarker(markerPath)
}
/** A top-level dir is a legacy user dir iff any child holds `index.json`. */
async function looksLikeLegacyUserDir(topDir: string): Promise<boolean> {
let children
try {
children = await fs.readdir(topDir, { withFileTypes: true })
} catch {
return false
}
for (const child of children) {
if (!child.isDirectory()) continue
try {
await fs.access(join(topDir, child.name, 'index.json'))
return true
} catch {
// no index.json under this child — keep scanning siblings
}
}
return false
}
async function writeMigrationMarker(markerPath: string): Promise<void> {
try {
await fs.writeFile(markerPath, new Date().toISOString(), { mode: 0o600 })
} catch (err) {
// Non-fatal: worst case the one-shot scan reruns next launch (idempotent).
console.warn('[chatStore] Failed to persist pre-envKey migration marker:', err)
}
}
/**
* Scan a user's per-agent chat directories and remove only caches whose parsed
* catalog declares a known legacy schema. Missing, torn, or future-version
* catalogs are not evidence that their paged transcripts are disposable.
*/
async function maybeWipeLegacyCache(userDir: string): Promise<void> {
let entries
try {
entries = await fs.readdir(userDir, { withFileTypes: true })
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'ENOENT') return // nothing cached yet
throw err
}
for (const entry of entries) {
if (!entry.isDirectory()) continue
const agentDir = join(userDir, entry.name)
const indexPath = join(agentDir, 'index.json')
let isLegacy = false
try {
const raw = await fs.readFile(indexPath, 'utf-8')
const parsed = JSON.parse(raw) as { version?: number }
if (parsed.version === PREVIOUS_PAGED_INDEX_VERSION) {
// A parsed v3 catalog is valid. Leave it in place during binding so the
// next ordinary ChatStore RMW normalizes it through the same crash-durable
// temp-write, file-fsync, rename, and directory-fsync path as every other
// index update.
isLegacy = false
} else if (LEGACY_INDEX_VERSIONS.has(parsed.version ?? Number.NaN)) {
isLegacy = true
} else if (parsed.version !== SCHEMA_VERSION) {
console.warn(`[chatStore] Preserving cache for "${entry.name}" with unknown index schema`)
}
} catch (error) {
const code = (error as NodeJS.ErrnoException | undefined)?.code
if (code !== undefined && code !== 'ENOENT') {
// A transient permission/I/O failure is not evidence of an old schema.
// Propagate it instead of recursively deleting a live agent cache.
throw error
}
// Missing or unparseable catalogs can be a torn atomic write. Preserve
// paged transcripts so server reconciliation or manual recovery can use them.
console.warn(`[chatStore] Preserving cache for "${entry.name}" with unreadable index`)
}
if (isLegacy) {
console.warn(
`[chatStore] Wiping legacy cache for "${entry.name}" (expected v${SCHEMA_VERSION})`
)
await fs.rm(agentDir, { recursive: true, force: true })
}
}
}
/**
* Corrupt snapshots preserve recoverable local work, but they also retain full
* transcript content. Keep recent quarantines for downgrade/crash recovery and
* remove abandoned copies after a bounded retention window on each bind.
*/
async function sweepExpiredCorruptQuarantines(userDir: string, nowMs = Date.now()): Promise<void> {
const agentEntries = await fs.readdir(userDir, { withFileTypes: true }).catch(() => [])
await Promise.all(
agentEntries
.filter(entry => entry.isDirectory())
.map(async entry => {
const agentDir = join(userDir, entry.name)
await removeExpiredQuarantineEntries(join(agentDir, '.corrupt'), () => true, nowMs)
const snapshotRoot = join(agentDir, 'chats', '.snapshots')
if (!(await isRealDirectory(snapshotRoot))) return
const chatEntries = await fs.readdir(snapshotRoot, { withFileTypes: true }).catch(() => [])
await Promise.all(
chatEntries
.filter(chatEntry => chatEntry.isDirectory())
.map(chatEntry =>
removeExpiredQuarantineEntries(
join(snapshotRoot, chatEntry.name),
name => name.startsWith('corrupt-'),
nowMs
)
)
)
})
)
}
async function isRealDirectory(directory: string): Promise<boolean> {
const stat = await fs.lstat(directory).catch(() => null)
return Boolean(stat?.isDirectory() && !stat.isSymbolicLink())
}
async function removeExpiredQuarantineEntries(
directory: string,
shouldRemove: (name: string) => boolean,
nowMs: number
): Promise<void> {
if (!(await isRealDirectory(directory))) return
const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => [])
await Promise.all(
entries
.filter(entry => shouldRemove(entry.name))
.map(async entry => {
const target = join(directory, entry.name)
const stat = await fs.lstat(target).catch(() => null)
if (!stat || nowMs - stat.mtimeMs < CORRUPT_QUARANTINE_RETENTION_MS) return
await fs.rm(target, { recursive: entry.isDirectory(), force: true }).catch(() => undefined)
})
)
}
export function unbindChatStore(): void {
bindingGeneration += 1
bindInFlight = null
activeChatStore = null
activeUserId = null
activeEnvKey = null
}
export function requireChatStore(): ChatStore {
if (!activeChatStore) throw new Error('Not authenticated')
return activeChatStore
}
/** Fences destructive IPC work to the store binding that issued the request. */
export function getChatStoreBindingGeneration(): number {
requireChatStore()
return bindingGeneration
}
export function requireChatStoreForBindingGeneration(expectedGeneration: number): ChatStore {
if (!Number.isSafeInteger(expectedGeneration) || expectedGeneration !== bindingGeneration) {
throw new Error('Chat store binding changed')
}
return requireChatStore()
}
/** Test-only helper. Do not call from production code. */
export function __setChatStoreBaseDirForTests(base: string | null): void {
baseDirOverride = base
}