Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Trust boundary for environment variables that Bun auto-loaded from the
* CURRENT DIRECTORY's `.env` files.
*
* Bun merges `.env`, `.env.local` and the `.env.<NODE_ENV>[.local]` variants
* from the process cwd into process.env before any user code runs — for
* `bun run` AND for `bun build --compile` binaries alike (verified on Bun
* 1.3.10 and 1.3.13). For a globally installed CLI the cwd is arbitrary: any
* cloned repository can carry a `.env`, so those files are UNTRUSTED input.
* Bun gives no way to ask which variables came from a file (the merge happens
* before module load), so this module re-parses the same files and reasons
* about them. Two guards sit on top of that parse:
*
* - The #427 DATABASE_URL guard (`config.ts:effectiveEnvDatabaseUrl`) is a
* VALUE match: the URL is ignored when it equals a cwd-.env assignment.
* Running gbrain inside a web-app checkout must not retarget the brain at
* that app's database. That value guard never touches
* `GBRAIN_DATABASE_URL`; the key-presence quarantine below is what drops
* it when a cwd .env ASSIGNS it (a planted brain URL is never intent).
* - The security quarantine below is a KEY-PRESENCE match: a protected key
* that any cwd .env file assigns is dropped, whatever its value. Value
* matching is unsound for a security list because Bun expands `${VAR}`
* inside .env values — `KEY=${PWD}/x` lands in process.env as an absolute
* path that never equals the file text.
*
* What the quarantine covers: the code-loading, exec-target, root-redirect,
* endpoint-redirect and posture-widening GBRAIN_* keys
* (`CWD_DOTENV_PROTECTED_KEYS`) AND the loader / git / node / XDG-config /
* TLS-trust / pager-editor / proxy / AI-endpoint / shell-startup hijack families
* a cwd .env could plant for the programs gbrain spawns (`CWD_DOTENV_PROTECTED_PREFIXES`,
* `CWD_DOTENV_PROTECTED_TOOLCHAIN_KEYS`) — `isCwdDotenvProtectedKey` is the
* single predicate. Routing/tuning GBRAIN_* keys and everything not listed
* still load from a cwd .env. Dropping is in-process; making the drop reach
* the programs gbrain spawns is `cli-preflight.ts`'s neutral-cwd re-run.
*
* Grammar: this parser must accept AT LEAST every line shape Bun's loader
* accepts, or an assignment Bun honours becomes invisible to the guard. Bun
* treats `\n`, `\r\n` AND a bare `\r` as line terminators (`A=x\rB=1` sets
* BOTH keys), keeps U+2028/U+2029 as ordinary value bytes, and does not strip
* a leading BOM (we strip it anyway — counting one more assignment is the
* safe side). The right-hand side is therefore matched as "everything up to
* the line terminator", never as `.*$`: `.` skips `\r` and U+2028/2029, and
* the `$` anchor then fails, hiding the whole assignment.
*
* fs/path only — this runs before anything else in the CLI.
*/
import { readFileSync } from 'fs';
import { join } from 'path';
/**
* The .env names Bun auto-loads from cwd — a superset across NODE_ENV values
* so the guards don't depend on replicating Bun's exact selection logic.
*/
export const CWD_DOTENV_FILES: readonly string[] = [
'.env', '.env.local',
'.env.development', '.env.development.local',
'.env.production', '.env.production.local',
'.env.test', '.env.test.local',
];
// Bun's terminator set: CRLF first so it is consumed as one break.
const LINE_TERMINATOR = /\r\n|\r|\n/;
/**
* Split .env file content into lines the way Bun's loader does (see the
* grammar note above) and strip a leading BOM. Shared with the
* `~/.gbrain/.env` loader in gbrain-env-file.ts so both files speak the same
* grammar.
*/
export function splitDotenvLines(content: string): string[] {
const body = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
return body.split(LINE_TERMINATOR);
}
// `export KEY=...` is accepted so a shell-styled .env still counts as an
// assignment (the guard errs toward "file-origin"). RHS: see the grammar note.
const ASSIGNMENT = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^\r\n]*)$/;
/** One `KEY=<raw rhs>` pair as a cwd .env file spells it (rhs untrimmed, unquoted). */
export type DotenvAssignment = readonly [key: string, raw: string];
/** Every `KEY=<raw rhs>` pair across the cwd .env files in `dir`, in file order. */
function* dotenvAssignments(dir: string): Generator<DotenvAssignment> {
for (const name of CWD_DOTENV_FILES) {
let content: string;
try {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- name iterates the fixed CWD_DOTENV_FILES list and dir is the cwd under audit (process.cwd() by default); read-only scan of the .env files Bun auto-loads from there
content = readFileSync(join(dir, name), 'utf-8');
} catch {
continue; // missing/unreadable file — nothing to guard against
}
for (const rawLine of splitDotenvLines(content)) {
const line = rawLine.trim();
if (!line || line.startsWith('#')) continue;
const m = line.match(ASSIGNMENT);
if (m) yield [m[1]!, m[2] ?? ''];
}
}
}
/**
* Materialise every assignment across the cwd .env files in `dir` — ONE read
* of the 8 files that `cwdDotenvAssignsKey` and `quarantineCwdDotenv` both
* accept in place of `dir`, so cli-preflight.ts parses once per process.
*/
export function parseCwdDotenv(dir: string = process.cwd()): DotenvAssignment[] {
return [...dotenvAssignments(dir)];
}
/** `dir` (parse now) or an already-parsed list from `parseCwdDotenv`. */
type DirOrAssignments = string | readonly DotenvAssignment[];
function assignmentsOf(source: DirOrAssignments): Iterable<DotenvAssignment> {
return typeof source === 'string' ? dotenvAssignments(source) : source;
}
/**
* All values assigned to `key` across the .env files in `dir`. Collecting
* every assignment (rather than emulating override order) keeps the #427
* guard independent of dotenv precedence rules — a match against ANY
* assignment means the value is file-origin. Exported for tests.
*/
export function dotenvValuesForKey(key: string, dir: string = process.cwd()): Set<string> {
const values = new Set<string>();
for (const [k, raw] of dotenvAssignments(dir)) {
if (k !== key) continue;
let v = raw.trim();
if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
(v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
v = v.slice(1, -1);
} else {
const hash = v.indexOf(' #');
if (hash !== -1) v = v.slice(0, hash).trim();
}
if (v) values.add(v);
}
return values;
}
/**
* True when ANY cwd .env file in `dir` assigns `key` — the value is ignored
* (an empty assignment still shadows the key in Bun's loader). This is the
* predicate the security quarantine and the guardrails loader use. The second
* argument may be a pre-parsed `parseCwdDotenv(dir)` list.
*/
export function cwdDotenvAssignsKey(key: string, dir: DirOrAssignments = process.cwd()): boolean {
for (const [k] of assignmentsOf(dir)) {
if (k === key) return true;
}
return false;
}
/**
* GBRAIN_* variables a cwd `.env` file must never be allowed to set. Each
* one either makes gbrain load or execute something, relocates its
* operator-owned roots, or widens a security posture — so a value planted by
* a cloned repository is never operator intent.
*
* Deliberately NOT listed (documented container/service deployments may
* legitimately co-locate them with the process cwd, and the attack model is
* a hostile cloned repo, not a serve cwd — SECURITY.md says to launch
* `serve --http` from a directory you control): GBRAIN_ADMIN_BOOTSTRAP_TOKEN,
* GBRAIN_HTTP_CORS_ORIGIN, GBRAIN_HTTP_TRUST_PROXY. Deferred for a later
* decision (TODOS): GBRAIN_SKILLS_DIR, GBRAIN_RECIPES_DIR, GBRAIN_GITHUB_PAT.
* `test/env-trust-protected-keys.test.ts` fails when a new suspicious-looking
* read (`_BIN|_CLI|_MODULE|_PATH|_HOME|_URL` suffix, `GBRAIN_ALLOW_` prefix)
* appears in src/ without a decision here or a `cwd-dotenv-ok:` annotation at
* the read site.
*/
export const CWD_DOTENV_PROTECTED_KEYS: readonly string[] = [
// --- code-loading: gbrain import()s the named module -------------------
'GBRAIN_GUARDRAILS_MODULE', // guardrail provider module loaded before dispatch
'GBRAIN_PLUGIN_PATH', // plugin / skillpack module path
// --- exec-target: gbrain spawns the named program ------------------------
'GBRAIN_CLAUDE_CLI_BIN', // binary run for the claude-cli language model
'GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG', // becomes that binary's CLAUDE_CONFIG_DIR → its hooks/settings
'GBRAIN_CLAUDE_CLI_USER_SETTINGS', // #8342: =1 lets the user's ~/.claude CLAUDE.md and settings.json back into that binary's calls
'GBRAIN_JOB_CHILD_CLI', // CLI the job-isolation worker spawns per job
'GBRAIN_BIN_OVERRIDE', // gbrain binary used by claw-test
// --- root / registry redirect ------------------------------------------
'GBRAIN_HOME', // relocates ~/.gbrain (config, .env, keys, registry)
'GBRAIN_COORDINATION_HOME', // #6765: where a checkout's writer coordination lock goes when GBRAIN_HOME is inside it; a planted value moves the lock two writers must share
'GBRAIN_MOUNTS_PATH', // brain mounts registry file
'GBRAIN_WORKER_STATUS_PATH',
'GBRAIN_WORKER_STATUS_TOKEN',
'GBRAIN_DATABASE_URL', // THE brain connection string: a cwd .env would retarget every hook, query and write at a planted database; the #427 value guard covers only the bare DATABASE_URL, and this key is "stated intent" everywhere it is read
'GBRAIN_DIRECT_DATABASE_URL', // direct-pool override (connection-manager.ts): retargets brain writes at a planted host; has no #427 value guard
'GBRAIN_REMOTE_MCP_URL', // `init --remote` default: where the thin client sends its MCP traffic and bearer token
'GBRAIN_REMOTE_ISSUER_URL', // `init --remote` default: the OAuth issuer the client trusts and hands its credential to
'GBRAIN_OAUTH_RELAY_URL', // the OAuth relay that hands back Google tokens (creds/relay-client.ts): a planted relay is token theft
'GBRAIN_OPENCLAW_GATEWAY_URL', // GST-2768: the Gateway the archive's openclaw child calls with GBRAIN_OPENCLAW_GATEWAY_TOKEN; a planted URL would receive the token and serve forged history
'GBRAIN_OPENCLAW_GATEWAY_TOKEN', // GST-2768: the credential that child presents; a planted one pairs with a planted Gateway to archive forged history
'GBRAIN_HOOK_CWD', // #8424: the session directory the hook launcher records; a planted value moves the yield checks and the turn-rule project match
// --- re-run marker ------------------------------------------------------
'GBRAIN_CWD_ENV_QUARANTINED', // cli-preflight.ts's sanitized re-run marker; only honoured when the startup cwd IS the .env-free dir it names, so a planted one is inert — listed so it is also dropped and named in the warning
// --- posture-widening ----------------------------------------------------
'GBRAIN_ALLOW_SHELL_JOBS', // enables the shell job handler (arbitrary exec on the worker)
'GBRAIN_ALLOW_PRIVATE_REMOTES', // permits git remotes on private networks
'GBRAIN_ALLOW_UNVERIFIED_REMOTE', // skips remote verification on workspace push
'GBRAIN_GIT_ALLOW_FILE_TRANSPORT', // permits the git file:// transport
'GBRAIN_ALLOW_MASS_RECONCILE', // lifts the mass-delete reconcile guard
'GBRAIN_ALLOW_DEFAULT_WRITE', // permits writes into the 'default' source
'GBRAIN_NO_SANITY', // disables content sanity checks
'GBRAIN_REMOTE_PRIVATE_PAGES', // exposes private pages to remote callers
'GBRAIN_SURFACE', // stdio MCP tool surface: a planted `full` widens the tools an agent sees (a shell export still widens; GBRAIN_MCP_FORCE_SURFACE stays narrow-only)
];
/**
* Non-GBRAIN hijack families a cwd `.env` could plant for the PROGRAMS gbrain
* spawns (git, the claude CLI, bun/node workers, shell jobs). These are
* normally absent from an operator's environment, which is exactly why a
* file-planted value lands (Bun never overrides a variable that already
* exists). Matched by PREFIX because each family is open-ended
* (`GIT_CONFIG_KEY_<n>`, `LD_*`, `BUN_CONFIG_*`); a family member the shell
* DID export is untouched unless a cwd .env assigns that same name.
*/
export const CWD_DOTENV_PROTECTED_PREFIXES: readonly string[] = [
'LD_', // glibc loader injection (LD_PRELOAD / LD_LIBRARY_PATH / LD_AUDIT) into every dynamically linked child
'DYLD_', // the macOS loader's equivalents (DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH)
'GIT_', // git config/hook/exec injection: GIT_CONFIG_COUNT/KEY_n/VALUE_n (core.fsmonitor, core.hooksPath), GIT_EXEC_PATH, GIT_SSH*, GIT_ASKPASS
'BUN_', // bun runtime hijack for bun-based children: BUN_OPTIONS (--preload), BUN_INSTALL, BUN_CONFIG_*
'NPM_CONFIG_', // npm registry / script-shell / node-options redirection for npm-based children
'npm_config_', // the lowercase spelling npm actually reads
'BASH_FUNC_', // exported-function injection (`BASH_FUNC_name%%=() {…}`): bash imports the body as a function into every child shell
'OPENCLAW_', // GST-2768: the openclaw child's Gateway URL, token, config and state roots; a planted value redirects the Gateway token or serves forged history
];
/**
* Exact non-GBRAIN keys with the same effect as the prefix families above but
* no shared prefix. Same rule: dropped only when a cwd .env assigns them.
*/
export const CWD_DOTENV_PROTECTED_TOOLCHAIN_KEYS: readonly string[] = [
// --- node preload / resolution / TLS --------------------------------------
'NODE_OPTIONS', // --require/--import a module into every node child (the claude CLI among them)
'NODE_PATH', // extra module-resolution roots → dependency shadowing
'NODE_EXTRA_CA_CERTS', // trusts a planted CA → TLS interception of API traffic
'NODE_TLS_REJECT_UNAUTHORIZED', // =0 disables certificate verification outright
// --- ssh credential prompts -----------------------------------------------
'SSH_ASKPASS', // program ssh/git run to obtain a passphrase
'SSH_ASKPASS_REQUIRE', // forces that program even when a tty is present
// --- per-user config roots the spawned tools read as GLOBAL config --------
'XDG_CONFIG_HOME', // git reads $XDG_CONFIG_HOME/git/config as global config even when ~/.gitconfig exists → core.fsmonitor / core.hooksPath (no GIT_ prefix); the claude CLI and opencode resolve their config dirs from it too
'XDG_DATA_HOME', // per-user data root (credential stores, tool state) the children load from
'XDG_CACHE_HOME', // per-user cache root — a planted cache is replayed as trusted state
'GNUPGHOME', // gpg home for git commit/tag signing → planted keyring and agent config
// --- TLS trust roots for the non-node children (git via curl, python, …) --
'SSL_CERT_FILE', 'SSL_CERT_DIR', // OpenSSL trust store override → a planted CA intercepts every HTTPS call the children make
'CURL_CA_BUNDLE', // curl's (and libcurl-linked git's) CA bundle override
'REQUESTS_CA_BUNDLE', // python requests' CA bundle override
// --- OpenSSL code loading: every OpenSSL-linked child (git over https, curl, python, ssh) ---
'OPENSSL_CONF', // a planted openssl.cnf names a provider/engine .so that OpenSSL dlopen()s at init
'OPENSSL_ENGINES', // the directory OpenSSL loads engine .so files from
'OPENSSL_MODULES', // the directory OpenSSL 3 loads provider .so files from
// --- per-user roots read raw from the environment by gbrain AND its children ---
'TMPDIR', 'TMP', 'TEMP', // os.tmpdir() honours these at call time: a planted (even relative) value steers the sanitized re-run's neutral dir and every temp write into the hostile tree
'HOME', 'USERPROFILE', // inert while exported (Bun never overrides a live variable) but under systemd/cron HOME is often UNSET, and the planted value then reaches process.env.HOME and every child's $HOME → ~/.gitconfig, ~/.ssh, ~/.gbrain resolve inside the checkout
// --- programs the children hand control to -------------------------------
'EDITOR', 'VISUAL', // takes.ts spawns $EDITOR || $VISUAL — an arbitrary program
'PAGER', // git (and other children) pipe output through it — an arbitrary program
// --- interpreter preload for scripted children (git's own helpers included)
'PYTHONPATH', // python module shadowing
'PYTHONSTARTUP', // python startup script
'PERL5LIB', // perl library path
'PERL5OPT', // implicit perl -M module load
'RUBYOPT', // implicit ruby -r preload
'RUBYLIB', // ruby library path
// --- shell startup files / interpreter homes: every NON-INTERACTIVE shell gbrain's children start (the git hooks gbrain writes, `sh -c` in workspace-push and shell jobs) reads these before its first command ---
'BASH_ENV', // bash sources this file at the start of every non-interactive shell — arbitrary code before the script's first line
// `ENV` (sh/ksh startup file) is deliberately NOT listed: every shell gbrain's children run reads it for INTERACTIVE shells only, and `ENV=production` is a routine key in project .env files.
'SHELLOPTS', // imported read-only into every bash: an inherited `xtrace` turns PS4 into code that runs on every traced command
'PS4', // the xtrace prompt — expanded, `$(…)` command substitution included, before each traced command
'BASHOPTS', // imported shopt set for every bash (expand_aliases, sourcepath, …) — changes how the child parses its own script
'PROMPT_COMMAND', // executed before every bash prompt — any interactive child shell (an $EDITOR's shell escape, a hook that drops to a shell) runs it
'ZDOTDIR', // relocates zsh's startup files: .zshenv is sourced by EVERY zsh, scripts included
'PYTHONHOME', // relocates the python stdlib → the interpreter imports planted code on start (PYTHONPATH is listed above)
'PERLLIB', // perl's other library-path variable (PERL5LIB is listed above)
'GCONV_PATH', // glibc loads iconv gconv modules — shared objects — from this directory on any charset conversion, in every glibc-linked child
// --- proxy MITM of every HTTP client gbrain or its children run -----------
'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY',
'http_proxy', 'https_proxy', 'all_proxy',
// --- AI CLI / API endpoint redirection ------------------------------------
'CLAUDE_CONFIG_DIR', // the claude CLI's config dir → its hooks and settings
'ANTHROPIC_BASE_URL', // redirects Anthropic API traffic (and the key with it) to a planted host
'ANTHROPIC_AUTH_TOKEN', // substitutes the bearer credential the SDK / claude CLI send
'OPENAI_BASE_URL', // redirects OpenAI-compatible API traffic
// --- the same redirection for every other provider gbrain's gateway / probes / recipes read from env (build-gateway-config.ts, probes.ts, recipes/*) — the API key travels to the planted host
'OPENROUTER_BASE_URL',
'LITELLM_BASE_URL',
'OLLAMA_BASE_URL',
'LMSTUDIO_BASE_URL',
'LLAMA_SERVER_BASE_URL',
'LLAMA_SERVER_RERANKER_BASE_URL',
];
const PROTECTED_EXACT: ReadonlySet<string> = new Set([
...CWD_DOTENV_PROTECTED_KEYS,
...CWD_DOTENV_PROTECTED_TOOLCHAIN_KEYS,
]);
/** The one predicate: is `key` something a cwd .env must never be allowed to set? */
export function isCwdDotenvProtectedKey(key: string): boolean {
if (PROTECTED_EXACT.has(key)) return true;
for (const prefix of CWD_DOTENV_PROTECTED_PREFIXES) {
if (key.startsWith(prefix)) return true;
}
return false;
}
export interface QuarantineOpts {
/** Warning sink; default writes one line to stderr. Injectable for tests. */
warn?: (line: string) => void;
/** Pre-parsed `parseCwdDotenv(dir)` list; when given, `dir` is not re-read. */
assignments?: readonly DotenvAssignment[];
}
/** The remediation every cwd-.env refusal ends with (also used by guardrails.ts). */
export const CWD_DOTENV_REMEDIATION =
'cwd .env files are untrusted for security settings. Export it from your shell or set it ' +
'in ~/.gbrain/.env.';
export function formatQuarantineWarning(keys: readonly string[]): string {
return (
`[env] Ignoring ${keys.join(', ')} because a .env file in the current directory assigns it — ` +
CWD_DOTENV_REMEDIATION
);
}
/**
* Drop every protected key present in `env` that a cwd .env file in `dir`
* assigns, and print ONE stderr warning naming them (sorted). Returns the
* dropped keys, sorted. Iterates the keys the .env files ASSIGN (not a fixed
* list) so the prefix families are covered.
*
* Semantics worth knowing:
* - Per-process, in-process. Deleting a key from process.env is NOT seen by
* children spawned without an explicit `env` option (Bun hands them the
* environ snapshot it took at startup — verified on Bun 1.3.13). So
* whenever this returns a non-empty list, `cli-preflight.ts` re-runs
* gbrain once from a fresh EMPTY temporary directory with the sanitized
* environment: the re-run's Bun never sees the cwd .env, its environ
* simply LACKS the dropped keys (deleted, never carried as `''` — git and
* the dynamic loader presence-check `GIT_SSL_NO_VERIFY=` /
* `LD_TRACE_LOADED_OBJECTS=`), and every descendant inherits that view.
* The re-run switches back to the original cwd in its own preflight.
* - Key presence, not value. A value the operator exported from the shell
* is ALSO dropped while a cwd .env assigns the same key: Bun's `${VAR}`
* expansion makes the two indistinguishable, and for this fixed security
* list a false drop (loud, with the fix in the message) is the safe side.
* - Fail-soft on I/O: an unreadable .env is treated as absent.
*/
export function quarantineCwdDotenv(
env: Record<string, string | undefined> = process.env,
dir: string = process.cwd(),
opts: QuarantineOpts = {},
): string[] {
const dropped: string[] = [];
const seen = new Set<string>();
for (const [key] of opts.assignments ?? dotenvAssignments(dir)) {
if (seen.has(key)) continue;
seen.add(key);
if (env[key] === undefined || !isCwdDotenvProtectedKey(key)) continue;
delete env[key];
dropped.push(key);
}
dropped.sort();
if (dropped.length > 0) {
(opts.warn ?? ((line: string) => console.error(line)))(formatQuarantineWarning(dropped));
}
return dropped;
}