Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Train A: continue the security key-files page on security-continued.md after the merge took it past its size cap
garrytan7a6cb666cacb
diff --git a/docs/architecture/key-files/security-continued.md b/docs/architecture/key-files/security-continued.mdnew file mode 100644index 0000000000..ec105ce7c8--- /dev/null+++ b/docs/architecture/key-files/security-continued.md@@ -0,0 +1,8 @@+# Key files: Security (continued)++[Subsystem index](../KEY_FILES.md) · [Previous entries](security.md). Read only the entries relevant to your change.++- `src/core/git-env.ts` + `src/core/hardened-git.ts` — #7584, the operator's `safe.directory` in scrubbed Git environments: `hardenedGitEnvironment` still drops system and global config and every `GIT_*` variable, but carries the operator's `safe.directory` entries (system and global, read from `/` with `git config --includes --show-scope` and cached for 30 s, then `GIT_CONFIG_*`) as environment config, so a source repository owned by another user reads once the operator allows it. `gitChildEnv` carries the environment entries the same way (`envSafeDirectories`, `safeDirectoryEnv`). Every other key in those places stays out. `gitChildEnv` also drops Git's global pathspec switches (`GIT_PATHSPEC_ENV_VARS`: `GIT_LITERAL_PATHSPECS`, `GIT_GLOB_PATHSPECS`, `GIT_NOGLOB_PATHSPECS`, `GIT_ICASE_PATHSPECS`; `extra` can still set one). gbrain's writers mark each path literal with `literalPathspecs` (`:(literal)<path>`), never `git --literal-pathspecs`, which Git exports to every hook and child as `GIT_LITERAL_PATHSPECS=1`, where a hook's glob pathspec then matches nothing. GST-2331: `NO_LAZY_FETCH_ENV` (`GIT_NO_LAZY_FETCH=1` and an empty `GIT_ALLOW_PROTOCOL`) is what a managed-sync read that runs under `gitChildEnv` adds beside `HARDENED_GIT_ARGS`, so a partial clone fetches nothing (Git before 2.45 ignores the first; the empty allowlist allows no transport on any Git): `syncGit`/`syncGitAsync`, every read in `sync-blobs.ts`, `sync-delta.ts`'s text runner (a rename whose old blob the clone lacks fails the diff, `diff_failed`, and discovery walks the whole tree), `sync-rename-identity.ts`, `sync-metafile-pages.ts`, `sync-origin-evidence.ts`, `sync-held-deletions.ts`, `unindexed-files.ts` and `pending-import.ts`. Tests: `test/hardened-git-safe-directory-7584.test.ts` (ownership forced with `GIT_TEST_ASSUME_DIFFERENT_OWNER` through a `git` wrapper on PATH), `test/git-literal-pathspec-hooks-7759.test.ts`, `test/sync-partial-clone-2331.test.ts`.++- `src/core/outside-content.ts` — GBRA-221: `neutralizeOutsideText(text)`, the one neutralizer for text a third party wrote before it lands in a page body (Gmail/Calendar/Contacts renders in `google-render.ts`, GitHub `renderItemPage`/`renderRepoCard`, chat transcripts in `transcripts/render.ts`, `book-mirror` chapter output). It escapes every `gbrain<ws>:<ws><name>` marker token to `gbrain\:<name>` (case-insensitive), `[Source:` to `[Source\:`, and backslash-prefixes each timeline sentinel, bare `## Timeline`/`## History` heading, dated timeline row or heading, transcript message anchor and date heading, using the parsers' own predicates. Idempotent and readable; apply it per outside field (or a composed line holding one), never to a whole page that may hold gbrain's own fences or citations. Also owns `escapeAnchorLines` and `MESSAGE_ANCHOR_RE` (re-exported by `transcripts/render.ts`). New connectors use it.+- `src/core/function-search-path.ts` — #7632 search_path hardening (#7688, #7785): `PINNED_FUNCTION_NAMES` (every gbrain function with a pinned search_path; `scripts/check-search-path.sh` fails one missing from it or a pinned path not ending in `pg_temp`), `FUNCTION_SEARCH_PATH_HARDENING_SQL` (the schema blob's last statement), and `hardenFunctionSearchPaths` (v277 and the end of every migration run: one transaction under the migration timeouts, a pg_proc row lock it cannot take becomes `schema_lock_blocked`, a concurrent pg_proc update is retried, returns the functions left or null when listing them failed). Doctor check: `src/commands/doctor/checks/function-search-path.ts` (`function_search_path`: names any pinned function whose path does not end in `pg_temp`; the fix is `gbrain apply-migrations --yes` below v277, else the schema-qualified `ALTER FUNCTION` SQL (argument types only) in `details.sql` to run as the owner, with no runnable fix).diff --git a/docs/architecture/key-files/security.md b/docs/architecture/key-files/security.mdindex 7aef483fe2..8fe68d7e9a 100644--- a/docs/architecture/key-files/security.md+++ b/docs/architecture/key-files/security.md@@ -44,7 +44,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/write-gate-scan.ts` + `scripts/trust-dry-run-scan.ts` — read-only exposure scan: keyset batches over pages, facts, takes and timeline entries, tier projected from deterministic signals (connector source, webhook/clipper page, `mcp:*`/capture/transcript page, agent fact lanes, `persistence_requests` operation and authority; none -> `unknown`), flag/quarantine counts and families per tier and table, counts and pattern names only. The script runs it in a REPEATABLE READ READ ONLY transaction (PGLite: on a copy of the data directory). Test: `test/write-gate-scan.test.ts`.-- `src/core/git-env.ts` + `src/core/hardened-git.ts` — #7584, the operator's `safe.directory` in scrubbed Git environments: `hardenedGitEnvironment` still drops system and global config and every `GIT_*` variable, but carries the operator's `safe.directory` entries (system and global, read from `/` with `git config --includes --show-scope` and cached for 30 s, then `GIT_CONFIG_*`) as environment config, so a source repository owned by another user reads once the operator allows it. `gitChildEnv` carries the environment entries the same way (`envSafeDirectories`, `safeDirectoryEnv`). Every other key in those places stays out. `gitChildEnv` also drops Git's global pathspec switches (`GIT_PATHSPEC_ENV_VARS`: `GIT_LITERAL_PATHSPECS`, `GIT_GLOB_PATHSPECS`, `GIT_NOGLOB_PATHSPECS`, `GIT_ICASE_PATHSPECS`; `extra` can still set one). gbrain's writers mark each path literal with `literalPathspecs` (`:(literal)<path>`), never `git --literal-pathspecs`, which Git exports to every hook and child as `GIT_LITERAL_PATHSPECS=1`, where a hook's glob pathspec then matches nothing. GST-2331: `NO_LAZY_FETCH_ENV` (`GIT_NO_LAZY_FETCH=1` and an empty `GIT_ALLOW_PROTOCOL`) is what a managed-sync read that runs under `gitChildEnv` adds beside `HARDENED_GIT_ARGS`, so a partial clone fetches nothing (Git before 2.45 ignores the first; the empty allowlist allows no transport on any Git): `syncGit`/`syncGitAsync`, every read in `sync-blobs.ts`, `sync-delta.ts`'s text runner (a rename whose old blob the clone lacks fails the diff, `diff_failed`, and discovery walks the whole tree), `sync-rename-identity.ts`, `sync-metafile-pages.ts`, `sync-origin-evidence.ts`, `sync-held-deletions.ts`, `unindexed-files.ts` and `pending-import.ts`. Tests: `test/hardened-git-safe-directory-7584.test.ts` (ownership forced with `GIT_TEST_ASSUME_DIFFERENT_OWNER` through a `git` wrapper on PATH), `test/git-literal-pathspec-hooks-7759.test.ts`, `test/sync-partial-clone-2331.test.ts`.--- `src/core/outside-content.ts` — GBRA-221: `neutralizeOutsideText(text)`, the one neutralizer for text a third party wrote before it lands in a page body (Gmail/Calendar/Contacts renders in `google-render.ts`, GitHub `renderItemPage`/`renderRepoCard`, chat transcripts in `transcripts/render.ts`, `book-mirror` chapter output). It escapes every `gbrain<ws>:<ws><name>` marker token to `gbrain\:<name>` (case-insensitive), `[Source:` to `[Source\:`, and backslash-prefixes each timeline sentinel, bare `## Timeline`/`## History` heading, dated timeline row or heading, transcript message anchor and date heading, using the parsers' own predicates. Idempotent and readable; apply it per outside field (or a composed line holding one), never to a whole page that may hold gbrain's own fences or citations. Also owns `escapeAnchorLines` and `MESSAGE_ANCHOR_RE` (re-exported by `transcripts/render.ts`). New connectors use it.-- `src/core/function-search-path.ts` — #7632 search_path hardening (#7688, #7785): `PINNED_FUNCTION_NAMES` (every gbrain function with a pinned search_path; `scripts/check-search-path.sh` fails one missing from it or a pinned path not ending in `pg_temp`), `FUNCTION_SEARCH_PATH_HARDENING_SQL` (the schema blob's last statement), and `hardenFunctionSearchPaths` (v277 and the end of every migration run: one transaction under the migration timeouts, a pg_proc row lock it cannot take becomes `schema_lock_blocked`, a concurrent pg_proc update is retried, returns the functions left or null when listing them failed). Doctor check: `src/commands/doctor/checks/function-search-path.ts` (`function_search_path`: names any pinned function whose path does not end in `pg_temp`; the fix is `gbrain apply-migrations --yes` below v277, else the schema-qualified `ALTER FUNCTION` SQL (argument types only) in `details.sql` to run as the owner, with no runnable fix).+[Continue this subsystem](security-continued.md).