Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Desktop dev-isolation contract.
*
* Several checkouts must be able to run the desktop app side by side on one
* machine. Without this module they cannot, because three pieces of state are
* machine-wide:
*
* - the OS protocol handler. `registerCustomProtocols()` makes the *running*
* bundle the default handler for `evenfire:`/`clerum:`, so whoever launches
* last steals the deep links of everyone else — and a computer-use agent
* that resolves the app by name lands on an arbitrary instance.
* - the application name (`Evenfire`), which is exactly what a computer-use
* agent has to disambiguate between.
* - the user-data directory, which holds the Chromium profile, the stored
* runtime-config profiles and the session material.
*
* This module is the pure contract for the explicit, opt-in isolation mode that
* removes that sharing. It owns:
*
* - the opt-in itself (`--evenfire-dev-isolation` or
* `EVENFIRE_DEV_ISOLATION=1`), so that a normal launch can never drift into
* isolated behaviour and an isolated launch can never silently fall back to
* the shared profile;
* - validation of what the launcher declared: an absolute per-run directory, a
* template of paths under it, loopback endpoints with explicit ports and no
* embedded credentials, and a safe target slug;
* - the derived visible identity (`PR660 · Minikube30488` plus an ASCII app
* name) used for the process title, `app.setName` and the window title;
* - the runtime policy that states, in one place, that an isolated run must
* not register OS protocols and must not process deep links;
* - verification of the *effective* runtime (real userData, app path,
* endpoints, config storage path) against the declaration, so a divergence
* aborts instead of quietly reading a shared profile.
*
* The module performs no I/O, imports nothing from Electron, and never reads a
* profile, a keychain entry, an environment dump or a secret: the caller passes
* in what it observed. That keeps every security-relevant invariant testable
* without launching a GUI.
*
* Nothing here changes the normal startup path. With no opt-in the only result
* is `{ mode: 'normal' }`, and callers keep today's behaviour unchanged.
*/
import path from 'node:path'
/** Opt-in flag accepted on the command line. */
export const DEV_ISOLATION_FLAG = '--evenfire-dev-isolation'
/** Opt-in environment variable; `1`/`true` enable, `0`/`false`/unset do not. */
export const DEV_ISOLATION_ENABLE_ENV = 'EVENFIRE_DEV_ISOLATION'
/**
* Payload the launcher declares. Only the run directory, the two endpoints, the
* target slug and (optionally) the PR number and expected app path are needed;
* every other value is derived here so the launcher and the app cannot disagree
* about names or paths.
*/
export const DEV_ISOLATION_ENV = {
runDir: 'EVENFIRE_DEV_ISOLATION_RUN_DIR',
restUrl: 'EVENFIRE_DEV_ISOLATION_REST_URL',
rpcUrl: 'EVENFIRE_DEV_ISOLATION_RPC_URL',
target: 'EVENFIRE_DEV_ISOLATION_TARGET',
pr: 'EVENFIRE_DEV_ISOLATION_PR',
appPath: 'EVENFIRE_DEV_ISOLATION_APP_PATH',
} as const
export const DEV_ISOLATION_USER_DATA_DIR_NAME = 'user-data'
export const DEV_ISOLATION_CONFIG_FILE_NAME = 'runtime-config.json'
export const DEV_ISOLATION_RECORD_FILE_NAME = 'run.json'
export const DEV_ISOLATION_PID_FILE_NAME = 'run.pid'
/** Prefix of the shared default app name; an isolated name must extend it. */
export const DEV_ISOLATION_APP_NAME_PREFIX = 'Evenfire'
const ENABLED_VALUES = new Set(['1', 'true'])
const DISABLED_VALUES = new Set(['0', 'false'])
const TARGET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
const PR_PATTERN = /^[0-9]{1,6}$/
// The visible label may contain the middle dot the operator reads; the app name
// stays plain ASCII because it becomes a process and application name.
const LABEL_PATTERN = /^[\x20-\x7e\u00b7]{1,80}$/
const APP_NAME_PATTERN = /^[\x20-\x7e]{1,64}$/
const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])
export type DevIsolationEnablement = 'disabled' | 'enabled' | 'invalid'
/**
* Read the opt-in. An unrecognized value is `invalid` rather than `disabled`:
* a typo must refuse the launch instead of quietly starting the shared-profile
* app the operator was trying to avoid.
*/
export function readDevIsolationEnablement(
env: NodeJS.ProcessEnv,
argv: readonly string[]
): DevIsolationEnablement {
const raw = String(env[DEV_ISOLATION_ENABLE_ENV] ?? '')
.trim()
.toLowerCase()
const flagged = argv.includes(DEV_ISOLATION_FLAG)
if (ENABLED_VALUES.has(raw) || flagged) return 'enabled'
if (raw === '' || DISABLED_VALUES.has(raw)) return 'disabled'
return 'invalid'
}
export type DevIsolationPaths = {
runDir: string
userDataDir: string
configPath: string
recordPath: string
pidPath: string
}
/** Template of the per-run paths, derived from the run directory alone. */
export function devIsolationPaths(runDir: string): DevIsolationPaths {
const root = path.resolve(runDir)
return {
runDir: root,
userDataDir: path.join(root, DEV_ISOLATION_USER_DATA_DIR_NAME),
configPath: path.join(root, DEV_ISOLATION_CONFIG_FILE_NAME),
recordPath: path.join(root, DEV_ISOLATION_RECORD_FILE_NAME),
pidPath: path.join(root, DEV_ISOLATION_PID_FILE_NAME),
}
}
export type DevIsolationIdentity = {
target: string
pr: string | null
/** Visible, non-ASCII-safe label, e.g. `PR660 · Minikube30488`. */
label: string
/** Process and application name, e.g. `Evenfire PR660 Minikube30488`. */
appName: string
}
function titleCaseToken(value: string): string {
return value
.split(/[^A-Za-z0-9]+/)
.filter(Boolean)
.map(token => token.charAt(0).toUpperCase() + token.slice(1).toLowerCase())
.join('')
}
/**
* Derive the unique visible identity from the target slug and the optional PR
* number. Deterministic: the launcher and the app compute the same value from
* the same inputs, so a drifted name is a detectable divergence, not a silent
* difference.
*/
export function deriveDevIsolationIdentity(input: {
target: string
pr?: string | null
}): DevIsolationIdentity {
const target = String(input.target ?? '').trim()
const pr = typeof input.pr === 'string' && input.pr.trim() ? input.pr.trim() : null
const targetLabel = titleCaseToken(target) || 'Target'
const prLabel = pr ? `PR${pr}` : ''
const label = prLabel ? `${prLabel} \u00b7 ${targetLabel}` : targetLabel
const appName = `${DEV_ISOLATION_APP_NAME_PREFIX} ${[prLabel, targetLabel]
.filter(Boolean)
.join(' ')}`
return { target, pr, label, appName }
}
/**
* A loopback endpoint with an explicit port and no embedded credentials. This
* is deliberately strict: an isolated run must not be pointable at a shared or
* remote deployment by a mistyped or hostile input, and a URL that carries a
* user/password must never reach the public run record.
*/
export function isLoopbackEndpointUrl(value: string): boolean {
const raw = String(value ?? '').trim()
if (!raw) return false
let url: URL
try {
url = new URL(raw)
} catch {
return false
}
if (url.protocol !== 'http:' && url.protocol !== 'https:') return false
if (url.username || url.password) return false
if (!LOOPBACK_HOSTS.has(url.hostname)) return false
if (!url.port) return false
const port = Number(url.port)
if (!Number.isInteger(port) || port < 1 || port > 65535) return false
if (url.pathname !== '/' || url.search || url.hash) return false
return true
}
/** Strict containment: a path equal to `parent` is not "inside" it. */
export function isPathInside(parent: string, child: string): boolean {
const from = path.resolve(parent)
const to = path.resolve(child)
if (from === to) return false
const prefix = from.endsWith(path.sep) ? from : `${from}${path.sep}`
return to.startsWith(prefix)
}
export type DevIsolationPlan = DevIsolationPaths & {
restUrl: string
rpcUrl: string
appPath: string | null
identity: DevIsolationIdentity
label: string
appName: string
}
export type DevIsolationRefusal = { code: string; message: string }
export type DevIsolationPlanResult =
| { ok: true; plan: DevIsolationPlan }
| ({ ok: false } & DevIsolationRefusal)
/**
* Validate the launcher's declaration and build the plan. Every failure is a
* refusal, never a fallback: the caller aborts.
*/
export function buildDevIsolationPlan(env: NodeJS.ProcessEnv): DevIsolationPlanResult {
const rawRunDir = String(env[DEV_ISOLATION_ENV.runDir] ?? '').trim()
if (!rawRunDir) {
return {
ok: false,
code: 'DEV_ISOLATION_RUN_DIR_REQUIRED',
message: `${DEV_ISOLATION_ENV.runDir} is required`,
}
}
if (!path.isAbsolute(rawRunDir)) {
return {
ok: false,
code: 'DEV_ISOLATION_RUN_DIR_NOT_ABSOLUTE',
message: `${DEV_ISOLATION_ENV.runDir} must be an absolute path`,
}
}
const rawTarget = String(env[DEV_ISOLATION_ENV.target] ?? '').trim()
if (!TARGET_PATTERN.test(rawTarget)) {
return {
ok: false,
code: 'DEV_ISOLATION_TARGET_INVALID',
message: `${DEV_ISOLATION_ENV.target} must match ${TARGET_PATTERN.source}`,
}
}
const rawPr = String(env[DEV_ISOLATION_ENV.pr] ?? '').trim()
if (rawPr && !PR_PATTERN.test(rawPr)) {
return {
ok: false,
code: 'DEV_ISOLATION_PR_INVALID',
message: `${DEV_ISOLATION_ENV.pr} must be digits only`,
}
}
const rawRestUrl = String(env[DEV_ISOLATION_ENV.restUrl] ?? '').trim()
if (!isLoopbackEndpointUrl(rawRestUrl)) {
return {
ok: false,
code: 'DEV_ISOLATION_REST_URL_INVALID',
message: `${DEV_ISOLATION_ENV.restUrl} must be an http(s) loopback URL with an explicit port and no credentials`,
}
}
const rawRpcUrl = String(env[DEV_ISOLATION_ENV.rpcUrl] ?? '').trim()
if (!isLoopbackEndpointUrl(rawRpcUrl)) {
return {
ok: false,
code: 'DEV_ISOLATION_RPC_URL_INVALID',
message: `${DEV_ISOLATION_ENV.rpcUrl} must be an http(s) loopback URL with an explicit port and no credentials`,
}
}
const rawAppPath = String(env[DEV_ISOLATION_ENV.appPath] ?? '').trim()
if (rawAppPath && !path.isAbsolute(rawAppPath)) {
return {
ok: false,
code: 'DEV_ISOLATION_APP_PATH_NOT_ABSOLUTE',
message: `${DEV_ISOLATION_ENV.appPath} must be an absolute path when set`,
}
}
const identity = deriveDevIsolationIdentity({ target: rawTarget, pr: rawPr || null })
if (!LABEL_PATTERN.test(identity.label)) {
return {
ok: false,
code: 'DEV_ISOLATION_LABEL_INVALID',
message: 'derived isolation label must be 1-80 printable characters',
}
}
if (!APP_NAME_PATTERN.test(identity.appName)) {
return {
ok: false,
code: 'DEV_ISOLATION_APP_NAME_INVALID',
message: 'derived isolation app name must be 1-64 printable ASCII characters',
}
}
if (identity.appName === DEV_ISOLATION_APP_NAME_PREFIX) {
return {
ok: false,
code: 'DEV_ISOLATION_APP_NAME_NOT_UNIQUE',
message: `an isolated app name must extend ${DEV_ISOLATION_APP_NAME_PREFIX}, not collide with it`,
}
}
const paths = devIsolationPaths(rawRunDir)
return {
ok: true,
plan: {
...paths,
restUrl: rawRestUrl,
rpcUrl: rawRpcUrl,
appPath: rawAppPath || null,
identity,
label: identity.label,
appName: identity.appName,
},
}
}
export type DevIsolationDecision =
| { mode: 'normal' }
| { mode: 'isolated'; plan: DevIsolationPlan }
| ({ mode: 'refused' } & DevIsolationRefusal)
/**
* Total decision for the main process: normal, isolated, or refused. Refused is
* a distinct outcome on purpose — an isolation request that cannot be honoured
* must never continue as a shared-profile launch.
*/
export function resolveDevIsolation(
env: NodeJS.ProcessEnv,
argv: readonly string[],
isPackaged = false
): DevIsolationDecision {
const enablement = readDevIsolationEnablement(env, argv)
if (enablement === 'disabled') return { mode: 'normal' }
if (enablement === 'invalid') {
return {
mode: 'refused',
code: 'DEV_ISOLATION_ENABLE_INVALID',
message: `${DEV_ISOLATION_ENABLE_ENV} must be 1/true/0/false or unset, or ${DEV_ISOLATION_FLAG} must be passed`,
}
}
if (isPackaged) {
return {
mode: 'refused',
code: 'DEV_ISOLATION_PACKAGED',
message: 'Isolation is development-only',
}
}
const plan = buildDevIsolationPlan(env)
if (!plan.ok) return { mode: 'refused', code: plan.code, message: plan.message }
const inline = argv.find(argument => argument.startsWith('--user-data-dir='))
const index = argv.indexOf('--user-data-dir')
const userData = inline?.slice('--user-data-dir='.length) ?? (index >= 0 ? argv[index + 1] : '')
if (
!userData ||
!path.isAbsolute(userData) ||
path.resolve(userData) !== plan.plan.userDataDir ||
env.CLERUM_DESKTOP_CONFIG_PATH !== plan.plan.configPath ||
env.EXTERNAL_REST_API_BASE_URL !== plan.plan.restUrl ||
env.RPC_PROXY_BASE_URL !== plan.plan.rpcUrl
) {
return {
mode: 'refused',
code: 'DEV_ISOLATION_LAUNCH_MISMATCH',
message:
'Explicit user data, config path and effective endpoints must match the isolation plan',
}
}
return { mode: 'isolated', plan: plan.plan }
}
export type DevIsolationRuntimePolicy = {
isolate: boolean
/** Isolated runs leave the machine-wide protocol handler untouched. */
registerOsProtocols: boolean
/** Isolated runs never route deep links, including another session's. */
acceptDeepLinks: boolean
/** Isolated runs keep their label as the window title. */
pinWindowTitle: boolean
/** Unique process/application name, or null to keep the shipped name. */
appName: string | null
/** Visible window title, or null to keep the derived production title. */
windowTitle: string | null
}
/**
* The single place that decides what an isolated run may do with machine-wide
* state. With no plan every field is the production value, so the normal path
* stays unchanged.
*/
export function devIsolationRuntimePolicy(
plan: DevIsolationPlan | null
): DevIsolationRuntimePolicy {
if (!plan) {
return {
isolate: false,
registerOsProtocols: true,
acceptDeepLinks: true,
pinWindowTitle: false,
appName: null,
windowTitle: null,
}
}
return {
isolate: true,
registerOsProtocols: false,
acceptDeepLinks: false,
pinWindowTitle: true,
appName: plan.appName,
windowTitle: plan.label,
}
}
export type DevIsolationObservation = {
pid: number
/** Real (`realpath`) userData directory Electron resolved. */
userDataDir: string
/** Real app path the process is running from. */
appPath: string
/** Effective endpoints after config hydration. */
restUrl: string
rpcUrl: string
/** Effective runtime-config storage path after hydration. */
configStoragePath: string
/** Derived environment key of the hydrated runtime. */
envKey: string
}
export type DevIsolationMismatch = {
field: 'userDataDir' | 'appPath' | 'restUrl' | 'rpcUrl' | 'configStoragePath'
expected: string
actual: string
}
export type DevIsolationVerdict = { ok: true } | { ok: false; mismatches: DevIsolationMismatch[] }
function samePath(left: string, right: string): boolean {
return path.resolve(left) === path.resolve(right)
}
/**
* Compare what the app actually resolved against what the launcher declared.
*
* The config storage path is compared exactly, not by containment: it is the
* proof that the runtime-config layer pointed at the isolated file instead of
* the developer's shared `runtime-configs` directory. Callers pass `realpath`
* results for the paths, so a symlinked parent cannot fake a match.
*/
export function verifyDevIsolationRuntime(
plan: DevIsolationPlan,
observed: DevIsolationObservation
): DevIsolationVerdict {
const mismatches: DevIsolationMismatch[] = []
if (!samePath(plan.userDataDir, observed.userDataDir)) {
mismatches.push({
field: 'userDataDir',
expected: plan.userDataDir,
actual: observed.userDataDir,
})
}
if (plan.appPath && !samePath(plan.appPath, observed.appPath)) {
mismatches.push({ field: 'appPath', expected: plan.appPath, actual: observed.appPath })
}
if (plan.restUrl !== observed.restUrl) {
mismatches.push({ field: 'restUrl', expected: plan.restUrl, actual: observed.restUrl })
}
if (plan.rpcUrl !== observed.rpcUrl) {
mismatches.push({ field: 'rpcUrl', expected: plan.rpcUrl, actual: observed.rpcUrl })
}
if (!samePath(plan.configPath, observed.configStoragePath)) {
mismatches.push({
field: 'configStoragePath',
expected: plan.configPath,
actual: observed.configStoragePath,
})
}
return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches }
}
/** Keys a public run record may contain. Nothing else is ever serialized. */
export const DEV_ISOLATION_RECORD_FIELDS = [
'kind',
'pid',
'label',
'appName',
'target',
'envKey',
'runDir',
'userDataDir',
'configPath',
'configStoragePath',
'appPath',
'restUrl',
'rpcUrl',
] as const
/**
* Public metadata for one isolated run: the identity, the pid and the paths and
* endpoints the operator asked to see. Built from an allow-list so a caller
* cannot leak an environment dump, a token or a credential into the record, and
* so the record is byte-identical between the launcher and the app.
*/
export function publicDevIsolationRecord(
plan: DevIsolationPlan,
observed: DevIsolationObservation
): Record<string, string | number> {
if (!verifyDevIsolationRuntime(plan, observed).ok) {
throw new Error('Isolation metadata is unavailable before runtime verification')
}
return {
kind: 'evenfire-dev-isolation',
pid: observed.pid,
label: plan.label,
appName: plan.appName,
target: plan.identity.target,
envKey: observed.envKey,
runDir: plan.runDir,
userDataDir: observed.userDataDir,
configPath: plan.configPath,
configStoragePath: observed.configStoragePath,
appPath: observed.appPath,
restUrl: observed.restUrl,
rpcUrl: observed.rpcUrl,
}
}
function singleLineValue(value: string | number | undefined): string {
const raw = typeof value === 'number' ? String(value) : String(value ?? '')
return raw
.replace(/[\u0000-\u001f\u007f]/g, '?')
.replace(/\s+/g, ' ')
.trim()
}
/** One log line, deterministic order, never multi-line. */
export function formatDevIsolationLogLine(record: Record<string, string | number>): string {
const fields = Object.keys(record)
.sort()
.map(key => `${key}=${singleLineValue(record[key])}`)
return `[Desktop][dev-isolation] ${fields.join(' ')}`
}
export type IsolationBaseDirDecision =
| { ok: true; baseDir: string }
| ({ ok: false } & DevIsolationRefusal)
/** Platform default parent directory for per-run directories. */
export function defaultIsolationBaseDir(input: {
platform: NodeJS.Platform
homedir: string
env: NodeJS.ProcessEnv
}): string {
if (input.platform === 'darwin') {
return path.join(
input.homedir,
'Library',
'Application Support',
`${DEV_ISOLATION_APP_NAME_PREFIX} Dev Isolation`
)
}
if (input.platform === 'win32') {
const localAppData = String(input.env.LOCALAPPDATA ?? '').trim()
return path.join(
localAppData || path.join(input.homedir, 'AppData', 'Local'),
`${DEV_ISOLATION_APP_NAME_PREFIX} Dev Isolation`
)
}
const stateHome = String(input.env.XDG_STATE_HOME ?? '').trim()
return path.join(
stateHome || path.join(input.homedir, '.local', 'state'),
'evenfire-dev-isolation'
)
}
/**
* Admit the parent directory of the per-run directories. A requested directory
* must be absolute and outside the repository: run state holds credentials-side
* material (the Chromium profile), and it must never land in the worktree where
* it could be committed or copied into notes.
*/
export function admitIsolationBaseDir(input: {
requested?: string
repoRoot: string
platform: NodeJS.Platform
homedir: string
env: NodeJS.ProcessEnv
}): IsolationBaseDirDecision {
const requested = String(input.requested ?? '').trim()
if (requested && !path.isAbsolute(requested)) {
return {
ok: false,
code: 'DEV_ISOLATION_BASE_DIR_NOT_ABSOLUTE',
message: 'the isolation base directory must be an absolute path',
}
}
const baseDir = requested
? path.resolve(requested)
: defaultIsolationBaseDir({
platform: input.platform,
homedir: input.homedir,
env: input.env,
})
if (isPathInside(input.repoRoot, baseDir) || path.resolve(input.repoRoot) === baseDir) {
return {
ok: false,
code: 'DEV_ISOLATION_BASE_DIR_INSIDE_REPO',
message: 'the isolation base directory must be outside the repository',
}
}
return { ok: true, baseDir }
}