fix: keep launch project .env secrets out of tmux global env (#285)

centdix · claude · web-flow · commit 153ce85bfe7c · 2026-07-05T14:34:52.000+02:00
* fix: keep launch project .env secrets out of tmux global env

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* refactor: extend .env strip to all tmux spawns and address review

- extract leaked-key stripping into shared adapters/project-env
- strip project keys in terminal.ts tmux/PTY spawns (close born-clean gap)
- use Bun.env; also strip WEBMUX_PROJECT_ENV_KEYS marker itself
- gate global-env scrub to once per backend process
- add project-env unit tests and a scrub-in-isolation integration test

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/backend/src/__tests__/project-env.test.ts b/backend/src/__tests__/project-env.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { leakedProjectEnvKeys, stripProjectEnv } from "../adapters/project-env";
+
+const original = process.env.WEBMUX_PROJECT_ENV_KEYS;
+
+afterEach(() => {
+  if (original === undefined) delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+  else process.env.WEBMUX_PROJECT_ENV_KEYS = original;
+});
+
+describe("leakedProjectEnvKeys", () => {
+  it("returns an empty set when no project env keys were loaded", () => {
+    delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+    expect(leakedProjectEnvKeys().size).toBe(0);
+  });
+
+  it("includes the listed keys plus the marker var itself, trimming blanks", () => {
+    process.env.WEBMUX_PROJECT_ENV_KEYS = "SUPABASE_URL, SUPABASE_ANON_KEY ,";
+    expect(leakedProjectEnvKeys()).toEqual(
+      new Set(["WEBMUX_PROJECT_ENV_KEYS", "SUPABASE_URL", "SUPABASE_ANON_KEY"]),
+    );
+  });
+});
+
+describe("stripProjectEnv", () => {
+  it("removes the launch project's keys and the marker, keeping unrelated vars", () => {
+    process.env.WEBMUX_PROJECT_ENV_KEYS = "SUPABASE_URL";
+    const result = stripProjectEnv({
+      SUPABASE_URL: "secret",
+      WEBMUX_PROJECT_ENV_KEYS: "SUPABASE_URL",
+      PATH: "/usr/bin",
+      HOME: "/root",
+      UNSET: undefined,
+    });
+    expect(result).toEqual({ PATH: "/usr/bin", HOME: "/root" });
+  });
+
+  it("returns a full copy of defined vars when there is nothing to strip", () => {
+    delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+    expect(stripProjectEnv({ A: "1", B: "2", C: undefined })).toEqual({ A: "1", B: "2" });
+  });
+});
diff --git a/backend/src/__tests__/tmux-adapter.test.ts b/backend/src/__tests__/tmux-adapter.test.ts
@@ -115,6 +115,18 @@ function parseManagedSessionResult(output: string): ManagedSessionResult {
   };
 }
 
+function parseGlobalEnvResult(output: string): { hasLeaked: boolean; hasKept: boolean } {
+  const value: unknown = JSON.parse(output);
+  if (!value || typeof value !== "object") {
+    throw new Error("global env result must be an object");
+  }
+  const { hasLeaked, hasKept } = value as { hasLeaked?: unknown; hasKept?: unknown };
+  if (typeof hasLeaked !== "boolean" || typeof hasKept !== "boolean") {
+    throw new Error("global env result must have boolean hasLeaked and hasKept");
+  }
+  return { hasLeaked, hasKept };
+}
+
 describe("sanitizeTmuxNameSegment", () => {
   it("normalizes arbitrary path-like input", () => {
     expect(sanitizeTmuxNameSegment("Workmux Web/Desktop")).toBe("workmux-web-desktop");
@@ -298,6 +310,116 @@ describe("BunTmuxGateway", () => {
     }
   });
 
+  it("keeps launch-project .env keys out of the tmux global environment", async () => {
+    const testRoot = await mkdtemp(join(tmpdir(), "webmux-tmux-env-leak-"));
+    const projectRoot = join(testRoot, "repo");
+    const runnerPath = join(testRoot, "ensure-session.ts");
+    const tmuxModuleUrl = new URL("../adapters/tmux.ts", import.meta.url).href;
+    await mkdir(projectRoot, { recursive: true });
+    await Bun.write(
+      runnerPath,
+      [
+        `import { BunTmuxGateway } from ${JSON.stringify(tmuxModuleUrl)};`,
+        "",
+        "function read(args: string[]): string {",
+        '  const result = Bun.spawnSync(args, { stdout: "pipe", stderr: "pipe" });',
+        "  if (result.exitCode !== 0) {",
+        "    const stderr = new TextDecoder().decode(result.stderr).trim();",
+        '    throw new Error(`${args.join(" ")} failed: ${stderr || `exit ${result.exitCode}`}`);',
+        "  }",
+        '  return new TextDecoder().decode(result.stdout).trim();',
+        "}",
+        "",
+        "const projectRoot = process.argv[2];",
+        'if (!projectRoot) throw new Error("expected projectRoot");',
+        "const gateway = new BunTmuxGateway();",
+        // ensureServer + ensureSession is the path that first creates a persistent
+        // server, capturing this process's env into the tmux global environment.
+        "gateway.ensureServer();",
+        'gateway.ensureSession("wm-env-leak", projectRoot);',
+        'const globalEnv = read(["tmux", "show-environment", "-g"]).split("\\n");',
+        "console.log(JSON.stringify({",
+        '  hasLeaked: globalEnv.some((line) => line.startsWith("LEAKED_PROJECT_SECRET=")),',
+        '  hasKept: globalEnv.some((line) => line.startsWith("KEPT_SHELL_VAR=")),',
+        "}));",
+      ].join("\n"),
+    );
+
+    try {
+      const result = parseGlobalEnvResult(readWithIsolatedTmux(
+        ["bun", runnerPath, projectRoot],
+        buildEnv({
+          WEBMUX_PROJECT_ENV_KEYS: "LEAKED_PROJECT_SECRET",
+          LEAKED_PROJECT_SECRET: "service-role-key",
+          KEPT_SHELL_VAR: "ok",
+        }),
+      ));
+      // The project .env key is stripped from the env used to spawn tmux, so the
+      // server is born without it in the global environment...
+      expect(result.hasLeaked).toBe(false);
+      // ...while unrelated inherited vars are still passed through normally.
+      expect(result.hasKept).toBe(true);
+    } finally {
+      await rm(testRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("scrubs launch-project .env keys left in the global env by an already-running server", async () => {
+    const testRoot = await mkdtemp(join(tmpdir(), "webmux-tmux-env-scrub-"));
+    const projectRoot = join(testRoot, "repo");
+    const runnerPath = join(testRoot, "scrub.ts");
+    const tmuxModuleUrl = new URL("../adapters/tmux.ts", import.meta.url).href;
+    await mkdir(projectRoot, { recursive: true });
+    await Bun.write(
+      runnerPath,
+      [
+        `import { BunTmuxGateway } from ${JSON.stringify(tmuxModuleUrl)};`,
+        "",
+        "function run(args: string[], env?: Record<string, string>): void {",
+        '  const result = Bun.spawnSync(args, { stdout: "pipe", stderr: "pipe", ...(env ? { env } : {}) });',
+        "  if (result.exitCode !== 0) {",
+        "    const stderr = new TextDecoder().decode(result.stderr).trim();",
+        '    throw new Error(`${args.join(" ")} failed: ${stderr || `exit ${result.exitCode}`}`);',
+        "  }",
+        "}",
+        "",
+        "function globalHasLeaked(): boolean {",
+        '  const result = Bun.spawnSync(["tmux", "show-environment", "-g"], { stdout: "pipe", stderr: "pipe" });',
+        '  return new TextDecoder().decode(result.stdout).split("\\n").some((line) => line.startsWith("LEAKED_PROJECT_SECRET="));',
+        "}",
+        "",
+        "const projectRoot = process.argv[2];",
+        'if (!projectRoot) throw new Error("expected projectRoot");',
+        // Simulate a server started before the stripped-env fix: its global env
+        // captured the leaked key. gateway commands never spawn with it set, so
+        // only the scrub can remove it. destroy-unattached off keeps this
+        // detached session (and thus the server + its global env) alive even when
+        // the tmux config enables destroy-unattached.
+        'run(["tmux", "new-session", "-d", "-s", "preexisting", "-c", projectRoot, ";", "set-option", "-t", "preexisting", "destroy-unattached", "off"], { ...process.env, LEAKED_PROJECT_SECRET: "service-role-key" } as Record<string, string>);',
+        "const before = globalHasLeaked();",
+        "const gateway = new BunTmuxGateway();",
+        "gateway.ensureServer();",
+        'gateway.ensureSession("wm-scrub", projectRoot);',
+        "console.log(JSON.stringify({ before, after: globalHasLeaked() }));",
+      ].join("\n"),
+    );
+
+    try {
+      const output = readWithIsolatedTmux(
+        ["bun", runnerPath, projectRoot],
+        buildEnv({ WEBMUX_PROJECT_ENV_KEYS: "LEAKED_PROJECT_SECRET" }),
+      );
+      const value: unknown = JSON.parse(output);
+      const { before, after } = value as { before?: unknown; after?: unknown };
+      // The pre-existing server really did leak the key into the global env...
+      expect(before).toBe(true);
+      // ...and ensureSession's self-heal scrub removed it.
+      expect(after).toBe(false);
+    } finally {
+      await rm(testRoot, { recursive: true, force: true });
+    }
+  });
+
   it("treats missing windows, sessions, and servers as already closed", async () => {
     const testRoot = await mkdtemp(join(tmpdir(), "webmux-tmux-kill-window-"));
     const projectRoot = join(testRoot, "repo");
diff --git a/backend/src/adapters/project-env.ts b/backend/src/adapters/project-env.ts
@@ -0,0 +1,31 @@
+/** The launch project's `.env`/`.env.local` keys that webmux's CLI loaded into
+ *  its own process env, passed down to the backend as a comma-separated list in
+ *  WEBMUX_PROJECT_ENV_KEYS. These are application secrets webmux does not need in
+ *  the tmux server: if the tmux *global* environment ever captures them (the
+ *  server inherits webmux's env from whatever process first starts it) they leak
+ *  into every session and pane of every project. WEBMUX_PROJECT_ENV_KEYS itself
+ *  is stripped too — it only holds key *names*, not values, but there is no
+ *  reason to let a webmux-internal marker reach the global env either. */
+export function leakedProjectEnvKeys(): Set<string> {
+  const raw = Bun.env.WEBMUX_PROJECT_ENV_KEYS;
+  if (!raw) return new Set();
+  const keys = new Set<string>(["WEBMUX_PROJECT_ENV_KEYS"]);
+  for (const key of raw.split(",").map((entry) => entry.trim()).filter(Boolean)) {
+    keys.add(key);
+  }
+  return keys;
+}
+
+/** Copy `base` (typically `Bun.env`) with the launch project's `.env` keys
+ *  removed, so a tmux server or client spawned by webmux never carries — nor
+ *  captures into its global environment — another project's secrets. Snapshots
+ *  `base` at call time; the leaked keys are fixed at launch, so a later mutation
+ *  to one of those vars is intentionally not reflected. */
+export function stripProjectEnv(base: Record<string, string | undefined>): Record<string, string> {
+  const keys = leakedProjectEnvKeys();
+  const env: Record<string, string> = {};
+  for (const [key, val] of Object.entries(base)) {
+    if (val !== undefined && !keys.has(key)) env[key] = val;
+  }
+  return env;
+}
diff --git a/backend/src/adapters/terminal.ts b/backend/src/adapters/terminal.ts
@@ -1,4 +1,5 @@
 import { log } from "../lib/log";
+import { stripProjectEnv } from "./project-env";
 
 interface PtyProcess {
   pid: number;
@@ -77,11 +78,15 @@ const defaultSpawnTmuxProcess: SpawnTmuxProcess = (args, opts = {}) =>
     stdin: opts.stdin ?? "ignore",
     stdout: "ignore",
     stderr: "pipe",
+    // Strip the launch project's `.env` keys: if one of these commands is ever
+    // the first to reach a not-yet-running server it must not birth it with
+    // another project's secrets in the global env (see project-env.ts).
+    env: stripProjectEnv(Bun.env),
   });
 const defaultSleep: Sleep = (ms) => Bun.sleep(ms);
 
 const defaultSpawnSyncCommand: SpawnSyncCommand = (args, opts = {}) => {
-  const result = Bun.spawnSync(args, opts);
+  const result = Bun.spawnSync(args, { ...opts, env: opts.env ?? stripProjectEnv(Bun.env) });
   return {
     exitCode: result.exitCode,
     stdout: result.stdout ?? new Uint8Array(),
@@ -242,7 +247,7 @@ export async function attach(
     initialPane,
   });
 
-  const proc = spawnPtyProcess(buildPtyArgs(cmd), { ...Bun.env, TERM: "xterm-256color" });
+  const proc = spawnPtyProcess(buildPtyArgs(cmd), { ...stripProjectEnv(Bun.env), TERM: "xterm-256color" });
 
   const session: TerminalSession = {
     proc,
diff --git a/backend/src/adapters/tmux.ts b/backend/src/adapters/tmux.ts
@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { basename, resolve } from "node:path";
 import type { PaneSplit } from "../domain/config";
+import { leakedProjectEnvKeys, stripProjectEnv } from "./project-env";
 
 export interface TmuxWindowSummary {
   sessionName: string;
@@ -41,10 +42,31 @@ export interface TmuxGateway {
   killPane(target: string): void;
 }
 
+let cachedTmuxSpawnEnv: { value: Record<string, string> | undefined } | null = null;
+let globalEnvScrubbed = false;
+
+/** Environment for spawning tmux control commands, stripped of the launch
+ *  project's `.env` keys (see {@link stripProjectEnv}). Whichever tmux command
+ *  first starts the server fixes the global environment for the server's
+ *  lifetime, so every tmux invocation must use the stripped env. Returns
+ *  `undefined` (inherit the process env unchanged) on the common path where no
+ *  project keys were loaded, so tmux spawns don't copy the whole env for
+ *  nothing. */
+function tmuxSpawnEnv(): Record<string, string> | undefined {
+  if (cachedTmuxSpawnEnv) return cachedTmuxSpawnEnv.value;
+  const value = Bun.env.WEBMUX_PROJECT_ENV_KEYS ? stripProjectEnv(Bun.env) : undefined;
+  cachedTmuxSpawnEnv = { value };
+  return value;
+}
+
 function runTmux(args: string[]): { stdout: string; stderr: string; exitCode: number } {
+  // Only pass `env` when we have a stripped copy: Bun.spawnSync treats an
+  // explicit `env: undefined` as an *empty* environment, not "inherit".
+  const spawnEnv = tmuxSpawnEnv();
   const result = Bun.spawnSync(["tmux", ...args], {
     stdout: "pipe",
     stderr: "pipe",
+    ...(spawnEnv ? { env: spawnEnv } : {}),
   });
 
   return {
@@ -123,13 +145,34 @@ export class BunTmuxGateway implements TmuxGateway {
         ["new-session", "-d", "-s", sessionName, "-c", cwd, ";", "set-option", "-t", sessionName, "destroy-unattached", "off"],
         `create tmux session ${sessionName}`,
       );
+      this.scrubLeakedGlobalEnv();
       return;
     }
 
     assertTmuxOk(
       ["set-option", "-t", sessionName, "destroy-unattached", "off"],
       `set destroy-unattached off for ${sessionName}`,
     );
+    this.scrubLeakedGlobalEnv();
+  }
+
+  /** Self-heal a tmux server that was already running with the launch project's
+   *  `.env` keys in its global environment (e.g. a server started by an older
+   *  webmux that predates the stripped-env spawn). Removing them from the global
+   *  environment cleans every pane created afterwards, in existing and new
+   *  sessions alike. Runs once the server is known to be up (`exit-empty` means a
+   *  server only persists after a session exists). Tolerant: unsetting a key that
+   *  is absent is a no-op.
+   *
+   *  Runs at most once per backend process: once the global env is scrubbed,
+   *  stripped-env spawns keep it clean, so re-scrubbing on every session-ensure /
+   *  reconciliation pass would be pure overhead (a tmux spawn per leaked key). */
+  private scrubLeakedGlobalEnv(): void {
+    if (globalEnvScrubbed) return;
+    globalEnvScrubbed = true;
+    for (const key of leakedProjectEnvKeys()) {
+      runTmux(["set-environment", "-gu", key]);
+    }
   }
 
   hasWindow(sessionName: string, windowName: string): boolean {
diff --git a/bin/src/webmux.ts b/bin/src/webmux.ts
@@ -183,8 +183,13 @@ function isWorktreeCommand(command: RootCommand): command is "add" | "list" | "o
 
 // ── Load env files from CWD (.env.local overrides .env) ─────────────────────
 
-async function loadEnvFile(path: string) {
-  if (!existsSync(path)) return;
+/** Load a `.env` file from CWD into `process.env`, returning the keys it added.
+ *  Those keys are the launch project's env: webmux tracks them so it can keep
+ *  them out of the tmux server's *global* environment (see WEBMUX_PROJECT_ENV_KEYS),
+ *  where they would otherwise leak into every project's sessions and panes. */
+async function loadEnvFile(path: string): Promise<string[]> {
+  if (!existsSync(path)) return [];
+  const added: string[] = [];
   const lines = (await Bun.file(path).text()).split("\n");
   for (const line of lines) {
     const trimmed = line.trim();
@@ -195,8 +200,10 @@ async function loadEnvFile(path: string) {
     const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
     if (!(key in process.env)) {
       process.env[key] = val;
+      added.push(key);
     }
   }
+  return added;
 }
 
 // ── Browser app mode ─────────────────────────────────────────────────────────
@@ -339,8 +346,9 @@ async function main(args: string[] = process.argv.slice(2)): Promise<void> {
     process.exit(code);
   }
 
-  await loadEnvFile(resolve(process.cwd(), ".env.local"));
-  await loadEnvFile(resolve(process.cwd(), ".env"));
+  const projectEnvKeys = new Set<string>();
+  for (const key of await loadEnvFile(resolve(process.cwd(), ".env.local"))) projectEnvKeys.add(key);
+  for (const key of await loadEnvFile(resolve(process.cwd(), ".env"))) projectEnvKeys.add(key);
 
   // When the user didn't pin a port, point CLI commands at the live server for
   // this project rather than the 5111 default. `webmux serve` walks to a free
@@ -414,6 +422,9 @@ async function main(args: string[] = process.argv.slice(2)): Promise<void> {
     ...process.env,
     PORT: String(parsed.port),
     WEBMUX_PROJECT_DIR: process.cwd(),
+    // Tell the backend which keys came from the launch project's `.env` so it can
+    // strip them from the tmux server's global environment (see tmux adapter).
+    ...(projectEnvKeys.size > 0 ? { WEBMUX_PROJECT_ENV_KEYS: [...projectEnvKeys].join(",") } : {}),
     ...(parsed.debug ? { WEBMUX_DEBUG: "1" } : {}),
   };
 
