Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

16.9 KB
Raw Blame
/**
 * The launch wrapper.
 *
 * Two of these assertions are about SECURITY (only deltas reach the disk, and
 * the file is 0600) and two are about a contract that fails silently if it
 * breaks (the exports come after the login shell, and the strip list is
 * applied). The rest pin the gate: an implementation that wrapped `-p`, a
 * non-TTY, or a machine without magmux would break surfaces that have nothing
 * to do with this feature.
 */

import { afterEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import {
  STRIPPED_CHILD_VARS,
  buildLauncherScript,
  envDeltas,
  magmuxPaneCapability,
  planMagmuxWrap,
} from "./magmux-wrapper.js";

const roots: string[] = [];
function scratch(): string {
  const d = mkdtempSync(join(tmpdir(), "claudish-wrap-test-"));
  roots.push(d);
  return d;
}

afterEach(() => {
  for (const d of roots.splice(0)) rmSync(d, { recursive: true, force: true });
});

const BASE = {
  claudeBinary: "/usr/local/bin/claude",
  claudeArgs: ["--dangerously-skip-permissions"],
  interactive: true,
  stdoutIsTty: true,
  magmuxBinary: "/opt/homebrew/bin/magmux",
  pid: 4242,
};

describe("envDeltas", () => {
  test("carries ONLY what claudish changed — never the inherited environment", () => {
    // The difference between a delta and a dump is whether the user's exported
    // secrets end up in a file on disk.
    const parent = { PATH: "/usr/bin", HOME: "/Users/jack", OPENAI_API_KEY: "sk-secret" };
    const child = { ...parent, ANTHROPIC_BASE_URL: "http://127.0.0.1:8787" };
    const { set, unset } = envDeltas(parent, child);
    expect(set).toEqual([["ANTHROPIC_BASE_URL", "http://127.0.0.1:8787"]]);
    expect(set.map(([k]) => k)).not.toContain("OPENAI_API_KEY");
    expect(set.map(([k]) => k)).not.toContain("PATH");
    expect(unset).toEqual([...STRIPPED_CHILD_VARS]);
  });

  test("a CHANGED value is a delta; an identical one is not", () => {
    const parent = { A: "1", B: "2" };
    const child = { A: "1", B: "changed" };
    expect(envDeltas(parent, child).set).toEqual([["B", "changed"]]);
  });

  test("a variable claudish deleted is unset, not silently inherited", () => {
    // Monitor mode deletes ANTHROPIC_API_KEY so Claude Code uses its own
    // credentials. If the login shell re-inherited it, the session would bill
    // the API instead of the subscription.
    const parent = { ANTHROPIC_API_KEY: "sk-real" };
    const child = {};
    expect(envDeltas(parent, child).unset).toContain("ANTHROPIC_API_KEY");
  });

  test("CLAUDECODE and CLAUDE_CODE_CHILD_SESSION are always unset, never exported", () => {
    // Inherited, the pair turns transcript saving off and degrades magmux's own
    // controller to terminal-idle heuristics. `claude-runner.ts` spreads
    // `...process.env` and strips only the first.
    const parent = { CLAUDECODE: "1", CLAUDE_CODE_CHILD_SESSION: "1" };
    const child = { CLAUDECODE: "1", CLAUDE_CODE_CHILD_SESSION: "1", X: "y" };
    const { set, unset } = envDeltas(parent, child);
    expect(set.map(([k]) => k)).not.toContain("CLAUDECODE");
    expect(set.map(([k]) => k)).not.toContain("CLAUDE_CODE_CHILD_SESSION");
    expect(unset).toContain("CLAUDECODE");
    expect(unset).toContain("CLAUDE_CODE_CHILD_SESSION");
  });
});

describe("buildLauncherScript", () => {
  test("exports come AFTER the profile and immediately before exec — that is the point", () => {
    // RISK-5, measured rather than assumed: a live `list` reply shows magmux
    // runs a pane command as `/bin/zsh -l -c …`. A user's `.zprofile` therefore
    // runs between claudish and Claude Code, and claudish's whole contract with
    // Claude Code — starting with ANTHROPIC_BASE_URL — travels in the
    // environment. Re-asserting after the profile is what survives it.
    const script = buildLauncherScript("/usr/local/bin/claude", ["-i"], {
      set: [["ANTHROPIC_BASE_URL", "http://127.0.0.1:8787"]],
      unset: ["CLAUDECODE"],
    });
    const lines = script.trim().split("\n");
    const exportAt = lines.findIndex((l) => l.startsWith("export ANTHROPIC_BASE_URL="));
    const execAt = lines.findIndex((l) => l.startsWith("exec "));
    expect(exportAt).toBeGreaterThan(-1);
    expect(execAt).toBe(lines.length - 1);
    expect(exportAt).toBeLessThan(execAt);
  });

  test("values and arguments are single-quoted, so a space or a quote cannot escape", () => {
    const script = buildLauncherScript("/path with space/claude", ["it's", "--flag"], {
      set: [["WEIRD", "a'b c"]],
      unset: [],
    });
    expect(script).toContain(`export WEIRD='a'\\''b c'`);
    expect(script).toContain(`exec '/path with space/claude' 'it'\\''s' '--flag'`);
  });
});

describe("planMagmuxWrap", () => {
  test("returns null for a non-interactive run — `-p` and `--stdin` are untouched", () => {
    expect(
      planMagmuxWrap({ ...BASE, interactive: false, childEnv: {}, tmpRoot: scratch() })
    ).toBeNull();
  });

  test("returns null when stdout is not a TTY", () => {
    expect(
      planMagmuxWrap({ ...BASE, stdoutIsTty: false, childEnv: {}, tmpRoot: scratch() })
    ).toBeNull();
  });

  test("returns null INSIDE an existing magmux — a grid pane must not nest one", () => {
    // `team --grid --mode interactive` runs one `claudish -i` per pane, each
    // interactive with a real TTY. Without this, every slot would wrap itself
    // in a second magmux inside the pane it is already running in. magmux
    // exports MAGMUX_SOCK to its children precisely so a child can tell.
    expect(
      planMagmuxWrap({
        ...BASE,
        parentEnv: { MAGMUX_SOCK: "/tmp/magmux-someone-else.sock" },
        childEnv: {},
        tmpRoot: scratch(),
      })
    ).toBeNull();
  });

  test("returns null when magmux is missing — the session launches exactly as before", () => {
    // The correct degradation, and it needs no version check: without a
    // multiplexer nothing can open a pane, so no lease is ever granted and the
    // feature is simply absent.
    expect(
      planMagmuxWrap({ ...BASE, magmuxBinary: null, childEnv: {}, tmpRoot: scratch() })
    ).toBeNull();
  });

  test("the control socket path is DERIVED from --id, so it is known before magmux starts", () => {
    // claudish is magmux's parent and `MAGMUX_SOCK` is exported downward only,
    // so a pid-derived socket could never be discovered by the parent. `--id`
    // is what makes the recovery UI reachable at all.
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    expect(plan).not.toBeNull();
    expect(plan?.controlSocket).toBe("/tmp/magmux-claudish-4242.sock");
    expect(plan?.args).toContain("--id");
    expect(plan?.args[plan.args.indexOf("--id") + 1]).toBe("claudish-4242");
  });

  test("passes --no-idle-done, -w and --no-status", () => {
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    // `--no-idle-done` is the fix for the `-w` trap: an idle pane is a resting
    // session, not a finished one, and with the flag `-w` waits for the process
    // to exit rather than for a turn to end.
    expect(plan?.args).toContain("--no-idle-done");
    expect(plan?.args).toContain("-w");
    expect(plan?.args).toContain("--no-status");
  });

  test("the pane command SOURCES the generated script", () => {
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    const cmd = plan?.args[plan.args.length - 1] as string;
    expect(cmd.startsWith(". '")).toBe(true);
    expect(cmd).toContain(plan?.scriptPath as string);
  });

  test("the script is 0600 inside a 0700 directory and carries only the deltas", () => {
    const root = scratch();
    const plan = planMagmuxWrap({
      ...BASE,
      parentEnv: { PATH: "/usr/bin", OPENAI_API_KEY: "sk-inherited-secret" },
      childEnv: {
        PATH: "/usr/bin",
        OPENAI_API_KEY: "sk-inherited-secret",
        ANTHROPIC_BASE_URL: "http://127.0.0.1:8787",
      },
      tmpRoot: root,
    });
    const script = readFileSync(plan?.scriptPath as string, "utf-8");
    expect(script).toContain("export ANTHROPIC_BASE_URL='http://127.0.0.1:8787'");
    // The inherited secret is NOT written to disk. This is the assertion that
    // makes "only the deltas" a property rather than a comment.
    expect(script).not.toContain("sk-inherited-secret");
    expect(script).not.toContain("PATH=");
    expect(statSync(plan?.scriptPath as string).mode & 0o777).toBe(0o600);
    expect(statSync(dirname(plan?.scriptPath as string)).mode & 0o777).toBe(0o700);
  });

  test("MAGMUX_SCROLLBACK defaults to 10000 but never overrides the user's own", () => {
    // RISK-4: the pane replaces the emulator's native scrollback with magmux's
    // ring. A bigger ring does not give selection back, but it stops the
    // session's history from being the thing that is lost.
    const a = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    expect(a?.env.MAGMUX_SCROLLBACK).toBe("10000");
    const b = planMagmuxWrap({
      ...BASE,
      childEnv: { MAGMUX_SCROLLBACK: "500" },
      tmpRoot: scratch(),
    });
    expect(b?.env.MAGMUX_SCROLLBACK).toBe("500");
  });

  test("the magmux process itself never inherits the stripped variables", () => {
    const plan = planMagmuxWrap({
      ...BASE,
      childEnv: { CLAUDECODE: "1", CLAUDE_CODE_CHILD_SESSION: "1", KEEP: "yes" },
      tmpRoot: scratch(),
    });
    expect(plan?.env.CLAUDECODE).toBeUndefined();
    expect(plan?.env.CLAUDE_CODE_CHILD_SESSION).toBeUndefined();
    expect(plan?.env.KEEP).toBe("yes");
  });

  test("cleanup removes the script and its directory", () => {
    const root = scratch();
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: root });
    expect(statSync(plan?.scriptPath as string).isFile()).toBe(true);
    plan?.cleanup();
    expect(() => statSync(plan?.scriptPath as string)).toThrow();
  });

  test("the pane exit code starts unknown — magmux's own status is not the child's", () => {
    // Measured: pane 0 exited 42 while magmux stayed alive waiting for a second
    // pane, so the exit code has to come off the control socket's `exit` event.
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    expect(plan?.paneExitCode()).toBeNull();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// The launcher script is a SECRET on disk
// ───────────────────────────────────────────────────────────────────────────

describe("the script's directory is unguessable and cannot be pre-created", () => {
  /**
   * The file this guards is sourced by the LOGIN SHELL immediately before
   * `exec`, and it carries claudish's env deltas — including, on the proxy
   * path, the `ANTHROPIC_API_KEY` Claude Code authenticates to us with.
   *
   * It used to live at `<tmp>/claudish-launch-<pid>`, created with
   * `mkdirSync(..., { recursive: true })`. `recursive: true` neither throws on
   * `EEXIST` nor applies `mode` to a directory that already exists, and the
   * name contains only the pid, which is enumerable — so on a multi-user host
   * another uid could pre-create (or symlink) that path and have it adopted
   * without a word, then read the session's secrets or swap the script between
   * the write and the `exec`. CWE-377 / CWE-59.
   */
  test("the path does not contain the pid, and two plans never collide", () => {
    const root = scratch();
    const a = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: root });
    const b = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: root });

    // Same pid, same tmpRoot, different directory: the name is random, so it
    // cannot be pre-created by someone who knows the pid.
    expect(dirname(a?.scriptPath as string)).not.toBe(dirname(b?.scriptPath as string));
    expect(a?.scriptPath).not.toContain(String(BASE.pid));
    expect(statSync(dirname(a?.scriptPath as string)).mode & 0o777).toBe(0o700);
    expect(statSync(a?.scriptPath as string).mode & 0o777).toBe(0o600);
  });

  test("a directory planted at the OLD predictable path is never adopted", () => {
    // The attack, verbatim: another uid creates the path first — world-writable
    // or a symlink into its own tree — and waits for claudish to write the
    // session's environment into it. `recursive: true` adopted it silently and
    // left its mode alone, and `writeFileSync` follows whatever is already
    // there. `mkdtempSync` + `wx` makes both impossible.
    const root = scratch();
    const planted = join(root, `claudish-launch-${BASE.pid}`);
    mkdirSync(planted, { recursive: true, mode: 0o777 });
    const decoy = join(planted, "claude-launch.sh");
    writeFileSync(decoy, "# planted");

    const plan = planMagmuxWrap({
      ...BASE,
      childEnv: { ANTHROPIC_API_KEY: "sk-session-secret" },
      tmpRoot: root,
    });

    expect(dirname(plan?.scriptPath as string)).not.toBe(planted);
    // The secret did not land anywhere the planter can read.
    expect(readFileSync(decoy, "utf-8")).toBe("# planted");
    expect(readFileSync(plan?.scriptPath as string, "utf-8")).toContain("sk-session-secret");
    expect(statSync(dirname(plan?.scriptPath as string)).mode & 0o777).toBe(0o700);
  });

  test("a plan that is never watched still takes its secret off disk at exit", () => {
    // `watch()` cleans up on the CHILD's exit, which covers the ordinary path
    // only. A SIGTERM to claudish, or a launch that never spawns, would
    // otherwise leave the key in /tmp.
    const plan = planMagmuxWrap({ ...BASE, childEnv: {}, tmpRoot: scratch() });
    expect(process.listeners("exit").length).toBeGreaterThan(0);
    plan?.cleanup();
    expect(() => statSync(plan?.scriptPath as string)).toThrow();
    // Idempotent, and it unhooks itself: a long-lived host must not accumulate
    // one exit listener per launch.
    plan?.cleanup();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// Eligibility, asked separately because the watchdog has to ask it EARLY
// ───────────────────────────────────────────────────────────────────────────

describe("magmuxPaneCapability", () => {
  test("wrap when interactive, on a TTY, with a binary and no ambient socket", () => {
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: true,
        magmuxBinary: "/opt/homebrew/bin/magmux",
        parentEnv: {},
      })
    ).toEqual({ kind: "wrap", magmux: "/opt/homebrew/bin/magmux" });
  });

  test("ambient inside someone else's magmux — a pane is reachable without wrapping", () => {
    // `team --grid --mode interactive`, or a user who launched claudish in a
    // pane by hand. Nothing to wrap, but there IS a multiplexer to ask.
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: true,
        magmuxBinary: "/opt/homebrew/bin/magmux",
        parentEnv: { MAGMUX_SOCK: "/tmp/magmux-someone-else.sock" },
      })
    ).toEqual({ kind: "ambient", sock: "/tmp/magmux-someone-else.sock" });
  });

  test("none for `-p`, for a pipe, and for a machine without magmux", () => {
    const env = {};
    expect(
      magmuxPaneCapability({ interactive: false, stdoutIsTty: true, parentEnv: env }).kind
    ).toBe("none");
    expect(
      magmuxPaneCapability({ interactive: true, stdoutIsTty: false, parentEnv: env }).kind
    ).toBe("none");
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: true,
        magmuxBinary: null,
        parentEnv: env,
      }).kind
    ).toBe("none");
  });

  test("it is the SAME predicate planMagmuxWrap uses — they cannot drift", () => {
    // The watchdog is decided from `magmuxPaneCapability` before the child
    // environment is finalised; the wrap is decided from `planMagmuxWrap`
    // afterwards. Two independent gates would mean a launch that exports the
    // ~300-attempt retry budget and then turns out to have no surface for it.
    for (const input of [
      { interactive: false, stdoutIsTty: true },
      { interactive: true, stdoutIsTty: false },
      { interactive: true, stdoutIsTty: true, magmuxBinary: null },
      { interactive: true, stdoutIsTty: true },
    ] as const) {
      const shape = { ...BASE, ...input, childEnv: {}, tmpRoot: scratch(), parentEnv: {} };
      const wrapped = planMagmuxWrap(shape) !== null;
      expect(wrapped).toBe(magmuxPaneCapability(shape).kind === "wrap");
    }
  });
});