Files
orca/config/scripts/test-runtime/environment/vitest-real-agent-home-write-guard.ts
Neil 9bd6272fdf refactor(tooling): organize build, CI, and test owners (#38130)
* refactor(tooling): organize test runtime and maintenance owners

* test(tooling): preserve relocated runtime fixture dependency edges

* refactor(tooling): preserve xterm routing owner checks

* ci(tooling): include routing owner in sparse checkout

* test(tooling): preserve copied workflow dependency closures

* fix(tooling): normalize hashed JSON assets in release parity

* fix(tooling): distinguish asset aliases from literal references

* fix(tooling): frame normalized asset reference payloads

* fix(tooling): normalize decoded JSON asset references

* refactor(tooling): organize build, CI and release owners

* fix(tooling): align moved generator and workflow path contracts

* fix(tooling): update generated plugin bundle owner banners

* test(tooling): create relocated mobile verifier fixture directories

* test(tooling): copy headless detector dependency closure

* test(tooling): align native batch policy fixtures with owner path

* fix(tooling): link moved reliability command to historical evidence

* fix(tooling): preserve nested sandbox owners and canonical guide source

* fix(tooling): target release version owners in checkout fixture
2026-11-04 21:08:19 -08:00

226 lines
7.5 KiB
TypeScript

import fs from 'node:fs'
import { syncBuiltinESMExports } from 'node:module'
import { userInfo } from 'node:os'
import { isAbsolute, join, resolve, sep } from 'node:path'
import { fileURLToPath } from 'node:url'
import { afterAll, afterEach } from 'vitest'
// Reject in-process writes to real agent/app homes because trust/hook code resolves home at write time; spawned children are outside this guard.
type GuardState = { roots: string[]; violations: string[] }
const AGENT_HOME_ENTRIES = [
'.codex',
'.claude',
'.orca',
'.cursor',
'.copilot',
'.gemini',
'.qoder'
]
// Guard Claude file/temp prefixes beside .claude directory, not only inside it.
const AGENT_HOME_FILE_PREFIXES = ['.claude.json']
// Capture live Orca/agent roots from terminal env before clearing inherited values.
const INHERITED_STATE_ENV = [
'ORCA_USER_DATA_PATH',
'CODEX_HOME',
'ORCA_CODEX_HOME',
'CLAUDE_CONFIG_DIR'
]
// Why: an Orca terminal points this at the live app's CLI, which a test's child shell would run.
const INHERITED_LIVE_CLI_ENV = ['ORCA_CODEX_LAUNCH_PREFLIGHT']
// Real-agent opt-in suites intentionally use their own home and explicit switch.
const REAL_AGENT_SUITE_SWITCHES = [
'ORCA_REAL_CLAUDE_SUPERVISED_STOP',
'ORCA_CODEX_CONTRACT_BINARY',
'ORCA_CODEX_NO_DAEMON_CONTRACT_BINARY',
'ORCA_CODEX_TRUST_CONTRACT_BINARY',
'ORCA_REPRO_CODEX_BINARY'
]
const realAgentSuiteOptedIn = () => REAL_AGENT_SUITE_SWITCHES.some((name) => process.env[name])
const foldCase = process.platform === 'darwin' || process.platform === 'win32'
function normalize(path: string): string {
const resolved = resolve(path)
return foldCase ? resolved.toLowerCase() : resolved
}
function realHomes(): string[] {
const homes = [process.env.HOME, process.env.USERPROFILE]
try {
// Why: HOME does not move this one, so a test that swaps HOME cannot hide the real home.
homes.unshift(userInfo().homedir)
} catch {
// No passwd entry (some containers): HOME is all there is.
}
return homes.filter((home): home is string => Boolean(home))
}
/** Folder roots end in a separator so `~/.orca` never covers `~/.orca-relay`; file prefixes do not. */
function protectedRoots(): string[] {
const folders = realHomes().flatMap((home) => [
...AGENT_HOME_ENTRIES.map((entry) => join(home, entry)),
join(home, 'Library', 'Application Support', 'orca'),
join(home, '.config', 'orca'),
join(home, 'AppData', 'Roaming', 'orca')
])
for (const name of INHERITED_STATE_ENV) {
const value = process.env[name]
if (value && isAbsolute(value)) {
folders.push(value)
}
}
const filePrefixes = realHomes().flatMap((home) =>
AGENT_HOME_FILE_PREFIXES.map((entry) => normalize(join(home, entry)))
)
return [...new Set([...folders.map((folder) => normalize(folder) + sep), ...filePrefixes])]
}
function targetPath(target: unknown): string | null {
if (typeof target === 'string') {
return target.startsWith('file:') ? fileURLToPath(target) : target
}
if (target instanceof URL) {
return fileURLToPath(target)
}
if (Buffer.isBuffer(target)) {
return target.toString()
}
return null
}
function realClaudeTranscriptWriteOptedIn(path: string): boolean {
if (process.env.ORCA_REAL_CLAUDE_CLI_TEST !== '1') {
return false
}
const homes = [
...realHomes().map((home) => join(home, '.claude')),
process.env.CLAUDE_CONFIG_DIR
].filter((home): home is string => Boolean(home))
return homes.some((home) => normalize(path).startsWith(normalize(join(home, 'projects')) + sep))
}
function assertOutsideRealHome(state: GuardState, operation: string, target: unknown): void {
const path = targetPath(target)
if (path === null || realAgentSuiteOptedIn() || realClaudeTranscriptWriteOptedIn(path)) {
return
}
const normalized = normalize(path) + sep
const root = state.roots.find((candidate) => normalized.startsWith(candidate))
if (!root) {
return
}
const error = new Error(
`[vitest real-agent-home guard] ${operation}(${path}) would write the real agent home under ${root}; give the test a temp home`
)
// Why the stack: the writer that swallowed this is what the failing test has to fix.
state.violations.push(error.stack?.split('\n').slice(0, 12).join('\n') ?? error.message)
throw error
}
const WRITE_OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_RDWR | fs.constants.O_CREAT
function opensForWrite(flags: unknown): boolean {
if (typeof flags === 'number') {
return (flags & WRITE_OPEN_FLAGS) !== 0
}
return typeof flags === 'string' && /[wa+]/.test(flags)
}
// Argument positions each mutating call writes to; `open` counts only when its flags write.
const GUARDED_TARGETS: Record<string, readonly number[]> = {
writeFile: [0],
appendFile: [0],
mkdir: [0],
mkdtemp: [0],
rename: [0, 1],
copyFile: [1],
cp: [1],
symlink: [1],
link: [1],
rm: [0],
rmdir: [0],
unlink: [0],
truncate: [0],
open: [0]
}
function guard(
state: GuardState,
api: typeof fs | typeof fs.promises,
name: string,
positions: readonly number[],
label: string
): void {
const descriptor = Object.getOwnPropertyDescriptor(api, name)
const original: unknown = descriptor?.value
if (!descriptor || typeof original !== 'function') {
return
}
const target = original
function guarded(this: unknown, ...args: unknown[]): unknown {
try {
if (!name.startsWith('open') || opensForWrite(args[1] ?? 'r')) {
for (const position of positions) {
assertOutsideRealHome(state, label, args[position])
}
}
} catch (error) {
if (api === fs.promises) {
return Promise.reject(error)
}
throw error
}
return target.apply(this, args)
}
Object.defineProperty(api, name, { ...descriptor, value: guarded })
}
function install(): GuardState {
const state: GuardState = { roots: protectedRoots(), violations: [] }
for (const [name, positions] of Object.entries(GUARDED_TARGETS)) {
guard(state, fs, name, positions, `fs.${name}`)
guard(state, fs, `${name}Sync`, positions, `fs.${name}Sync`)
guard(state, fs.promises, name, positions, `fs.promises.${name}`)
}
guard(state, fs, 'createWriteStream', [0], 'fs.createWriteStream')
// Re-sync builtin ESM exports or named fs imports keep original unguarded writers.
syncBuiltinESMExports()
return state
}
declare global {
// Wrap once per process; per-file wrapping stacks duplicate guards.
var orcaRealAgentHomeWriteGuard: GuardState | undefined
}
const state = (globalThis.orcaRealAgentHomeWriteGuard ??= install())
// Clear inherited paths only after capturing guarded roots; suites can supply test-local values.
export function clearInheritedAgentStateEnv(): void {
const inheritedEnvToUnset = realAgentSuiteOptedIn()
? []
: [...INHERITED_STATE_ENV, ...INHERITED_LIVE_CLI_ENV]
for (const name of inheritedEnvToUnset) {
if (name === 'CLAUDE_CONFIG_DIR' && process.env.ORCA_REAL_CLAUDE_CLI_TEST === '1') {
continue
}
delete process.env[name]
}
}
clearInheritedAgentStateEnv()
/** Drains recorded violations; only the guard's own self-test should need this. */
export function takeRealAgentHomeWriteViolations(): string[] {
return state.violations.splice(0)
}
function failOnViolations(): void {
const violations = takeRealAgentHomeWriteViolations()
if (violations.length > 0) {
// Rethrow recorded violations: trust writers can swallow call-site errors.
throw new Error(`[vitest real-agent-home guard]\n${violations.join('\n')}`)
}
}
afterEach(failOnViolations)
afterAll(failOnViolations)