fix: keep launch project .env secrets out of tmux global env

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: centdix

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,60 @@ 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("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");

backend/src/adapters/tmux.ts

@@ -41,10 +41,50 @@ export interface TmuxGateway {
   killPane(target: string): void;
 }
 
+/** Keys webmux's launcher loaded from the serve directory's `.env`/`.env.local`
+ *  into its own process env (comma-separated in WEBMUX_PROJECT_ENV_KEYS). These
+ *  are the launch project's application secrets; webmux does not need them in the
+ *  tmux server. When webmux starts the tmux server it inherits webmux's env, and
+ *  the server captures that as its *global* environment — which every session and
+ *  pane of every project then inherits. Stripping these keys from the env used to
+ *  spawn tmux keeps a webmux-created server from ever being born with one
+ *  project's secrets visible to all the others. */
+function leakedProjectEnvKeys(): Set<string> {
+  const raw = Bun.env.WEBMUX_PROJECT_ENV_KEYS;
+  if (!raw) return new Set();
+  return new Set(raw.split(",").map((key) => key.trim()).filter(Boolean));
+}
+
+let cachedTmuxSpawnEnv: { value: Record<string, string> | undefined } | null = null;
+
+/** Environment for spawning tmux control commands, stripped of the launch
+ *  project's `.env` keys. 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) when there is nothing to strip. */
+function tmuxSpawnEnv(): Record<string, string> | undefined {
+  if (cachedTmuxSpawnEnv) return cachedTmuxSpawnEnv.value;
+  const keys = leakedProjectEnvKeys();
+  if (keys.size === 0) {
+    cachedTmuxSpawnEnv = { value: undefined };
+    return undefined;
+  }
+  const env: Record<string, string> = {};
+  for (const [key, val] of Object.entries(process.env)) {
+    if (val !== undefined && !keys.has(key)) env[key] = val;
+  }
+  cachedTmuxSpawnEnv = { value: env };
+  return env;
+}
+
 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 +163,28 @@ 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. */
+  private scrubLeakedGlobalEnv(): void {
+    for (const key of leakedProjectEnvKeys()) {
+      runTmux(["set-environment", "-gu", key]);
+    }
   }
 
   hasWindow(sessionName: string, windowName: string): boolean {

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 ─────────────────────────────────────────────────────────
@@ -338,8 +345,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
@@ -413,6 +421,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" } : {}),
   };