A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
refactor: make env-export quoting unskippable (#148)
Brenno Ferrari2fc0c191fc98
diff --git a/.claude/scripts/lib/session-start.ts b/.claude/scripts/lib/session-start.tsindex d18f603..0d990ac 100644--- a/.claude/scripts/lib/session-start.ts+++ b/.claude/scripts/lib/session-start.ts@@ -204,13 +204,51 @@ export function formatDateHeader(d: Date): string {return `${y}-${m}-${day} (${weekday})`;}-/** Quote one value for the POSIX shell syntax used by `CLAUDE_ENV_FILE`.- * The split/reopen sequence is the only way to retain a literal apostrophe.+/**+ * Quote one value for the POSIX shell syntax used by `CLAUDE_ENV_FILE`.+ *+ * Single quotes make every character literal except `'` itself, so this needs+ * exactly one escape rule instead of the five a double-quoted string would+ * need (`$`, backtick, `"`, `\`, newline) — and it sidesteps the shell-to-shell+ * differences in how backslash is treated inside double quotes.+ *+ * The close/escape/reopen sequence (`'\''`) is the only way to carry a literal+ * apostrophe through a single-quoted string. Same algorithm as Python's+ * `shlex.quote`, minus its cosmetic "skip quoting when already safe" branch:+ * quoting unconditionally costs a few bytes and removes a regex that could be+ * wrong.+ *+ * Prefer `formatEnvExport` over calling this directly — see the note there.*/export function quoteForPosixShell(value: string): string {return `'${value.replaceAll("'", "'\\''")}'`;}+/** POSIX portable environment variable name. */+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;++/**+ * Build one complete `export NAME='value'` line, newline included.+ *+ * This exists so no call site has to *remember* to quote. `quoteForPosixShell`+ * gives you a safe tool but leaves the unsafe one within reach: a template+ * literal like `export FOO="${bar}"` is still the shortest thing to type, and+ * that is exactly the shape that shipped a command-execution bug here (#145).+ * Owning the whole line removes the choice — there is nothing left to forget.+ * `tests/session-start.test.ts` locks the entry script to this function so a+ * hand-rolled export cannot quietly come back.+ *+ * Throws on a name the shell could not accept. The call site treats env-file+ * persistence as best-effort and already swallows failures, so a bad name+ * degrades to "not persisted" rather than a corrupt env file or a dead hook.+ */+export function formatEnvExport(name: string, value: string): string {+ if (!ENV_NAME_PATTERN.test(name)) {+ throw new Error(`refusing to write unsafe env var name: ${JSON.stringify(name)}`);+ }+ return `export ${name}=${quoteForPosixShell(value)}\n`;+}+/*** Format the "Active Work" section from a list of filenames in work/active.* Strips `.md`, keeps the first `limit`, returns "(none)" for empty input.diff --git a/.claude/scripts/session-start.ts b/.claude/scripts/session-start.tsindex 836f231..196ed76 100644--- a/.claude/scripts/session-start.ts+++ b/.claude/scripts/session-start.ts@@ -23,7 +23,7 @@ import { join } from "node:path";import {take,formatDateHeader,- quoteForPosixShell,+ formatEnvExport,injectionMode,formatInjectionSize,formatActiveWork,@@ -108,11 +108,15 @@ const cwd =process.cwd();process.chdir(cwd);-// Persist vault path for any downstream shell consumers (Claude Code feature)+// Persist vault path for any downstream shell consumers (Claude Code feature).+// The whole line comes from formatEnvExport so quoting is not a step anyone+// can skip; see its doc comment. A hand-rolled template here is what caused+// the command-execution bug in #145, and a unit test now guards against one+// reappearing.const envFile = process.env["CLAUDE_ENV_FILE"];if (envFile) {try {- appendFileSync(envFile, `export VAULT_PATH=${quoteForPosixShell(cwd)}\n`);+ appendFileSync(envFile, formatEnvExport("VAULT_PATH", cwd));} catch {/* best-effort — session continues even if persistence fails */}diff --git a/.claude/scripts/tests/session-start.test.ts b/.claude/scripts/tests/session-start.test.tsindex d10aa37..044e664 100644--- a/.claude/scripts/tests/session-start.test.ts+++ b/.claude/scripts/tests/session-start.test.ts@@ -7,11 +7,16 @@import { test, describe } from "node:test";import assert from "node:assert/strict";-import { join } from "node:path";+import { join, dirname } from "node:path";+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";+import { fileURLToPath } from "node:url";+import { tmpdir } from "node:os";+import { spawnSync } from "node:child_process";import {take,formatDateHeader,quoteForPosixShell,+ formatEnvExport,formatInjectionSize,injectionMode,applyInjectionBudget,@@ -65,13 +70,241 @@ describe("formatDateHeader", () => {});describe("quoteForPosixShell", () => {- test("keeps shell syntax literal and escapes apostrophes", () => {- const value = "vault/\"$(echo owned)\`echo owned\`/$HOME/it's\nnext";+ // One row per hazard, so a failure names the case that broke instead of+ // pointing at a single combined string.+ const cases: ReadonlyArray<readonly [string, string, string]> = [+ ["plain path", "/home/me/vault", "'/home/me/vault'"],+ ["variable expansion", "/a/$HOME/b", "'/a/$HOME/b'"],+ ["command substitution", "/a/$(id)/b", "'/a/$(id)/b'"],+ ["backtick substitution", "/a/`id`/b", "'/a/`id`/b'"],+ ["double quote", '/a/"q"/b', "'/a/\"q\"/b'"],+ ["command separator", "/a/;rm -rf x/b", "'/a/;rm -rf x/b'"],+ // Windows paths are the common real-world case for this template, and+ // backslash is literal inside single quotes.+ ["windows path", "C:\\Users\\me\\vault", "'C:\\Users\\me\\vault'"],+ ["trailing backslash", "/a/b\\", "'/a/b\\'"],+ ["apostrophe", "/it's/vault", "'/it'\\''s/vault'"],+ ["only an apostrophe", "'", "''\\'''"],+ ["embedded newline", "a\nb", "'a\nb'"],+ ["empty string", "", "''"],+ ];+ for (const [label, input, expected] of cases) {+ test(label, () => {+ assert.equal(quoteForPosixShell(input), expected);+ });+ }+});++describe("formatEnvExport", () => {+ test("emits a complete, newline-terminated export line", () => {assert.equal(- quoteForPosixShell(value),- "'vault/\"$(echo owned)\`echo owned\`/$HOME/it'\\''s\nnext'",+ formatEnvExport("VAULT_PATH", "/home/me/vault"),+ "export VAULT_PATH='/home/me/vault'\n",+ );+ });++ test("quoting is applied without the caller asking for it", () => {+ assert.equal(+ formatEnvExport("VAULT_PATH", "/a/$(id)/b"),+ "export VAULT_PATH='/a/$(id)/b'\n",+ );+ });++ test("rejects names the shell could not accept", () => {+ for (const bad of ["", "1ABC", "A-B", "A B", "A;rm -rf /", "A=B", "$A"]) {+ assert.throws(+ () => formatEnvExport(bad, "x"),+ /unsafe env var name/,+ `should reject ${JSON.stringify(bad)}`,+ );+ }+ });++ test("accepts the portable name shapes", () => {+ for (const ok of ["A", "_A", "VAULT_PATH", "_x9"]) {+ assert.doesNotThrow(() => formatEnvExport(ok, "v"));+ }+ });+});++describe("session-start entry — env export cannot be hand-rolled", () => {+ // A source-level guard. The safe helper only helps if it is the thing the+ // entry actually calls; nothing in the type system stops someone writing+ // `export FOO="${bar}"` again, which is precisely the bug #145 fixed.+ const entry = readFileSync(+ join(dirname(fileURLToPath(import.meta.url)), "..", "session-start.ts"),+ "utf-8",+ );++ test("writes the env file through formatEnvExport", () => {+ assert.match(entry, /appendFileSync\(\s*envFile,\s*formatEnvExport\(/);+ });++ // Catches a hand-rolled line in any quoting style, not just backticks.+ const HANDROLLED = /["'`]export\s/;++ test("contains no hand-rolled `export ...=` literal", () => {+ assert.doesNotMatch(+ entry,+ HANDROLLED,+ "build the line with formatEnvExport instead of a string literal",+ );+ });++ test("does not reach past the helper to the raw quoter", () => {+ assert.doesNotMatch(+ entry,+ /quoteForPosixShell\(/,+ "the entry should call formatEnvExport, which quotes internally",);});++ // A guard that cannot fail is worse than no guard: it reads as coverage+ // while proving nothing. These assert the patterns above actually fire on+ // the regressions they exist to catch, including the exact pre-#145 line.+ test("GUARD IS NOT VACUOUS — the pattern catches every hand-rolled form", () => {+ const regressions = [+ 'appendFileSync(envFile, `export VAULT_PATH="${cwd}"\\n`);', // the pre-#145 bug+ "appendFileSync(envFile, `export VAULT_PATH=${quoteForPosixShell(cwd)}\\n`);",+ 'appendFileSync(envFile, "export FOO=" + bar);',+ "appendFileSync(envFile, 'export FOO=' + bar);",+ ];+ for (const bad of regressions) {+ assert.match(bad, HANDROLLED, `guard must reject: ${bad}`);+ }+ });++ test("GUARD IS NOT VACUOUS — the raw-quoter pattern catches a direct call", () => {+ assert.match("const x = quoteForPosixShell(cwd);", /quoteForPosixShell\(/);+ });++ test("GUARD IS NOT VACUOUS — the required-call pattern rejects a missing call", () => {+ const required = /appendFileSync\(\s*envFile,\s*formatEnvExport\(/;+ assert.doesNotMatch("appendFileSync(envFile, someOtherThing());", required);+ assert.match("appendFileSync(envFile, formatEnvExport('A', b));", required);+ });+});++/**+ * The quoting contract is a claim about how a real POSIX shell parses the+ * output, so assert it against a real POSIX shell rather than against our own+ * idea of one. Runs on Linux/macOS CI and on Windows runners that ship Git+ * Bash; skips cleanly where no shell exists, so it can never be the reason+ * the suite fails on an exotic platform.+ */+const posixShell = (() => {+ for (const candidate of ["sh", "bash"]) {+ try {+ const r = spawnSync(candidate, ["-c", "printf ok"], { encoding: "utf-8" });+ if (r.status === 0 && r.stdout === "ok") return candidate;+ } catch {+ /* not available */+ }+ }+ return null;+})();++describe("quoteForPosixShell — verified against a real POSIX shell", () => {+ const skip = posixShell === null ? "no POSIX shell on this platform" : false;++ /** Round-trip every value in one shell invocation, NUL-delimited. */+ function roundTrip(values: readonly string[]): string[] {+ const dir = mkdtempSync(join(tmpdir(), "quote-roundtrip-"));+ try {+ const script = join(dir, "rt.sh");+ writeFileSync(+ script,+ values+ .map((v) => `V=${quoteForPosixShell(v)}\nprintf '%s\\0' "$V"`)+ .join("\n") + "\n",+ );+ const r = spawnSync(posixShell as string, [script], { encoding: "utf-8" });+ assert.equal(r.status, 0, `shell exited ${r.status}: ${r.stderr}`);+ const parts = (r.stdout ?? "").split("\0");+ parts.pop(); // trailing empty after the final delimiter+ return parts;+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });+ }+ }++ test("adversarial paths round-trip byte-exact", { skip }, () => {+ const values = [+ "/home/me/vault",+ "/a/$HOME/b",+ "/a/$(id)/b",+ "/a/`id`/b",+ '/a/"q"/b',+ "/a/;rm -rf x/b",+ "/a/&& touch x/b",+ "/a/| tee x/b",+ "/it's/vault",+ "'",+ "''",+ "C:\\Users\\me\\vault",+ "/a/b\\",+ "/a/ spaces /b",+ "/a/\t tab/b",+ "/ünïcodé/路径/vault",+ "/a/*/b",+ "/a/~root/b",+ "/a/!history/b",+ "/a/#comment/b",+ "/a/${IFS}/b",+ "",+ ];+ assert.deepEqual(roundTrip(values), values);+ });++ test("no adversarial value can execute anything", { skip }, () => {+ // If substitution leaked, the marker file would exist afterwards.+ const dir = mkdtempSync(join(tmpdir(), "quote-exec-"));+ try {+ const marker = join(dir, "EXECUTED").replaceAll("\\", "/");+ roundTrip([`/a/$(touch ${marker})/b`, `/a/\`touch ${marker}\`/b`]);+ assert.throws(+ () => readFileSync(marker),+ "quoting leaked — a command substitution executed",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });+ }+ });++ test("fuzz: generated hostile strings round-trip", { skip }, () => {+ // Deterministic LCG — a flaky fuzz test is worse than none.+ let seed = 0x2026_0724;+ const rnd = () => (seed = (seed * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff;+ const alphabet = [..."abc/ '\"`$(){}[]|&;<>*?!#~\\\t=+:,.^%@-", "\n", "é", "路"];+ const values: string[] = [];+ for (let i = 0; i < 120; i++) {+ const len = 1 + Math.floor(rnd() * 24);+ let s = "";+ for (let j = 0; j < len; j++) {+ s += alphabet[Math.floor(rnd() * alphabet.length)] ?? "x";+ }+ values.push(s);+ }+ assert.deepEqual(roundTrip(values), values);+ });++ test("formatEnvExport output is a sourceable export", { skip }, () => {+ const dir = mkdtempSync(join(tmpdir(), "envexport-"));+ try {+ const envFile = join(dir, "env.sh");+ const value = "/a/$(id)/it's \"weird\"/b";+ writeFileSync(envFile, formatEnvExport("VAULT_PATH", value));+ const r = spawnSync(+ posixShell as string,+ ["-c", `. "$1"; printf '%s' "$VAULT_PATH"`, "sh", envFile],+ { encoding: "utf-8" },+ );+ assert.equal(r.status, 0, r.stderr);+ assert.equal(r.stdout, value, "sourcing the file must restore the exact path");+ } finally {+ rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });+ }+ });});describe("formatActiveWork", () => {