botmux 3.4.3 → 3.5.2

package/dist/adapters/cli/fs-policy.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Unified file-sandbox policy (FsPolicy) — the single source of truth for BOTH
+ * platform sandbox engines.
+ *
+ * Model (three-tier whitelist, per product decision 2026-07-16, design doc
+ * "botmux 文件沙盒重构方案"): every path gets one of three access levels —
+ * readWrite / readOnly / deny — and EVERYTHING NOT COVERED BY A RULE IS
+ * INACCESSIBLE (deny-by-default). Nested black/white lists are supported: the
+ * DEEPEST matching rule wins (longest-prefix), so `readOnly ~/Library` +
+ * `deny ~/Library/Keychains` and `deny bots/` + `readWrite bots/<self>` both
+ * work. This replaces the previous "read-everything + enumerated blocklist"
+ * model whose failure mode was silent secret exposure; here a missing baseline
+ * entry fails loud (CLI error), never silent.
+ *
+ * Architecture: this module is PURE (no fs / no spawn — fully unit-testable).
+ *   buildFsPolicy(ctx)      merges baseline preset + botmux-internal + adapter
+ *                           + user rules into one ordered rule list
+ *   compileToSeatbelt(...)  → macOS sandbox-exec profile text
+ *   compileToBwrap(...)     → Linux bwrap argv prefix
+ * Both engines resolve conflicts by "last emitted wins" (Seatbelt last-match /
+ * bwrap mount order), so emitting rules sorted shallow→deep yields
+ * longest-prefix-wins on BOTH platforms by construction — cross-platform
+ * parity needs no hand-synced rule lists.
+ *
+ * The worker resolves every impure input up front (realpath, existence
+ * filtering, sibling-free by design) and passes canonical absolute paths.
+ */
+export type FsAccess = 'readWrite' | 'readOnly' | 'deny';
+export type FsRuleSource = 'baseline' | 'adapter' | 'internal' | 'user' | 'mandatory';
+export interface FsRule {
+    /** Canonical absolute path (no trailing slash). */
+    path: string;
+    access: FsAccess;
+    /** Where the rule came from — for the dashboard policy viewer / path tester. */
+    source: FsRuleSource;
+}
+export interface FsPolicy {
+    /** Deduped rules sorted shallow→deep (emission order = precedence order). */
+    rules: FsRule[];
+    /** Keep network egress (bwrap-only knob; Seatbelt does not confine net here). */
+    net: boolean;
+    /** Extra Seatbelt write-allow regexes (e.g. ~/.claude.json.tmp.* atomic-save
+     *  siblings when the CLI data dir is NOT redirected into BOT_HOME). */
+    writeRegexes: string[];
+    /** Final host-security denies that cannot be represented as path prefixes. */
+    denyRegexes?: string[];
+    /** Narrow read-only exceptions emitted after denyRegexes (macOS gateway socket). */
+    finalReadOnlyPaths?: string[];
+}
+export interface FsPolicyUserPaths {
+    readWrite?: readonly string[];
+    readOnly?: readonly string[];
+    deny?: readonly string[];
+}
+export interface FsPolicyContext {
+    platform: 'darwin' | 'linux';
+    /** All paths below must be CANONICAL (realpath'd by the worker). */
+    homeDir: string;
+    botmuxHome: string;
+    sessionDataDir: string;
+    workingDir: string;
+    currentAppId: string;
+    /** This session's id — scopes the turn-sends dedup marker to a single file
+     *  (`turn-sends/<sessionId>.jsonl`) so a sandboxed CLI cannot rewrite ANOTHER
+     *  session's markers. Optional: when absent, no turn-sends grant is emitted
+     *  (a non-session policy has no marker to write). */
+    sessionId?: string;
+    /** This bot's BOT_HOME (`<botmuxHome>/bots/<appId>`) — always readWrite. */
+    botHome: string;
+    /** True when the CLI's data root is redirected into BOT_HOME
+     *  (CLAUDE_CONFIG_DIR / CODEX_HOME). False → cliDataPaths are exposed rw. */
+    redirectedCliData: boolean;
+    /** The CLI's REAL data paths (e.g. ~/.claude, ~/.claude.json, ~/.codex) to
+     *  keep readWrite when NOT redirected. Ignored when redirectedCliData. */
+    cliDataPaths?: readonly string[];
+    /** Adapter auth/login paths kept readWrite (token refresh must persist). */
+    authPaths?: readonly string[];
+    /** Directories of every executable spawned inside the sandbox (cliBin dir,
+     *  node dir, adapter second-stage bins) — exposed readOnly. */
+    execPaths?: readonly string[];
+    /** Trusted runtime read-only roots (skill/plugin dirs, botmux dist). */
+    readonlyRoots?: readonly string[];
+    /** The botmux install/checkout root (dir containing dist/ + node_modules).
+     *  Exposed readOnly so the agent's `botmux` CLI and the claude hooks (which
+     *  exec `node <checkout>/dist/cli.js …`) can load — without this a sandboxed
+     *  `botmux send` / SessionStart+AskUserQuestion hooks EPERM on cli.js. */
+    botmuxInstallRoot?: string;
+    /** Daemon-mediated relay outbox (Linux) — readWrite. */
+    outbox?: string;
+    /** Extra writable roots (resolved TMPDIR, admin extras). */
+    extraWritePaths?: readonly string[];
+    /** Per-bot user config (bots.json sandboxPaths) — highest precedence. */
+    userPaths?: FsPolicyUserPaths;
+    /** Host-owned boundaries that user policy may not override. */
+    mandatoryDenyPaths?: readonly string[];
+    mandatoryDenyRegexes?: readonly string[];
+    mandatoryReadOnlyPaths?: readonly string[];
+    net?: boolean;
+    /** Seatbelt write-allow regex passthrough (see FsPolicy.writeRegexes). */
+    writeRegexes?: readonly string[];
+}
+/** Normalize: require absolute, strip trailing slashes, reject `..` segments.
+ *  Returns null for anything unusable (silently-dropped relative paths are a
+ *  fail-open trap — callers log dropped entries). */
+export declare function normalizeFsPath(p: string): string | null;
+/** Is `p` equal to or an ancestor of `child`? (both normalized) */
+export declare function coversPath(p: string, child: string): boolean;
+/**
+ * Merge candidate rules into the final ordered list:
+ *  - normalize paths, drop unusable entries
+ *  - dedupe same-path conflicts: higher source rank wins (user > internal >
+ *    adapter > baseline); tie → the MORE RESTRICTIVE access wins (deny >
+ *    readOnly > readWrite) so a duplicated entry can never widen access
+ *  - sort shallow→deep (stable within a depth) — the emission order both
+ *    compilers rely on for longest-prefix-wins
+ */
+export declare function mergeFsRules(candidates: readonly FsRule[]): FsRule[];
+/**
+ * The effective access for `path` under `rules`: the DEEPEST rule whose path
+ * covers it; no match → 'none' (inaccessible). This one function IS the policy
+ * semantics — the dashboard path tester and the unit tests both call it, and
+ * both compilers are tested to agree with it.
+ */
+export declare function accessForPath(rules: readonly FsRule[], path: string): {
+    access: FsAccess | 'none';
+    rule?: FsRule;
+};
+/**
+ * Build the unified FsPolicy: baseline preset (platform) + adapter-declared
+ * paths + botmux-internal injections + user sandboxPaths (highest precedence).
+ * Pure — the worker canonicalizes and existence-filters all ctx paths first.
+ */
+export declare function buildFsPolicy(ctx: FsPolicyContext): FsPolicy;
+/** Every strict ancestor of every non-deny rule path. Under read-deny-default,
+ *  realpath()/stat of an intermediate dir fails and crashes CLIs that
+ *  canonicalize their config dir — so each ancestor needs file-read-metadata
+ *  (literal, NOT subpath: no listing/enumeration is granted). */
+export declare function ancestorsNeedingTraverse(rules: readonly FsRule[]): string[];
+/**
+ * Compile the policy to a macOS Seatbelt profile. `(deny default)` + Apple's
+ * bsd.sb base makes it deny-by-default for BOTH files and other operations,
+ * then we re-allow the non-file operation classes the CLI needs (process/mach/
+ * ipc/sysctl/signal, network gated on policy.net) and the three file tiers
+ * emitted shallow→deep (Seatbelt applies the LAST matching rule → deepest rule
+ * wins, matching accessForPath()).
+ */
+export declare function compileToSeatbelt(policy: FsPolicy): string;
+export interface CompileBwrapOpts {
+    /** Top-level symlinks to replicate inside the tmpfs root (usrmerge /bin →
+     *  usr/bin etc.). Resolved by the worker (impure readlink). */
+    symlinks?: readonly {
+        path: string;
+        target: string;
+    }[];
+    /** A single MODE-000 EMPTY directory (worker-created, kept empty) ro-bound
+     *  over DIRECTORY-shaped deny rules. `--ro-bind emptyDir <deny>` masks the
+     *  real contents, makes the mountpoint read-only (unlike `--tmpfs <deny>`,
+     *  which left a WRITABLE tmpfs), AND — because the source is mode 000 — makes
+     *  the mask itself unreadable (`ls`/`cat` on it fail, not just "returns
+     *  empty"). A real deny is neither readable, listable, nor writable. */
+    emptyDir: string;
+    /** Directory that will hold MODE-000 empty placeholder files for FILE-shaped
+     *  deny rules (dirs are masked with the empty ro-bind above; files need an
+     *  empty ro-bind source). The worker creates the returned `emptyFiles`
+     *  (mode 000) first. */
+    emptiesDir: string;
+    /** Rule paths that are FILES (not dirs) on the host — deny compiles to an
+     *  empty-file bind, readOnly/readWrite file binds work as-is. Resolved by
+     *  the worker (impure stat). A deny path NOT in this set is masked as a
+     *  DIRECTORY (covers both existing dirs and not-yet-existing paths). */
+    filePaths?: ReadonlySet<string>;
+    /** chdir target (the project working dir). */
+    chdir: string;
+}
+export interface BwrapCompilation {
+    /** bwrap argv prefix (caller appends --setenv pairs and `-- cli args`). */
+    args: string[];
+    /** Mode-000 empty placeholder files the worker must create before spawn
+     *  (the ro-bind SOURCE for file-shaped deny masks). */
+    emptyFiles: {
+        path: string;
+        maskedPath: string;
+    }[];
+    /** Every deny mountpoint that was masked, with its shape. The worker must
+     *  ensure each exists on the host BEFORE spawn (bwrap cannot bind onto a
+     *  missing target, and a missing target under a read-write parent would make
+     *  bwrap materialise it on the host anyway) — creating a mountpoint the host
+     *  can write to even when the policy makes its PARENT read-only in-sandbox,
+     *  which is exactly what closes the "host/other process creates the secret
+     *  mid-session" TOCTOU. Mountpoints the worker itself had to create (didn't
+     *  pre-exist) are removed at teardown IFF still empty (never a recursive rm —
+     *  content written by the host/a concurrent process is preserved). */
+    maskMounts: {
+        path: string;
+        kind: 'dir' | 'file';
+    }[];
+}
+/**
+ * Compile the policy to a bwrap argv prefix. Deny-by-default is bwrap's
+ * natural shape: a fresh tmpfs root, then ONLY the rule paths are bound in
+ * (later mounts win → emitting shallow→deep gives deepest-rule-wins, matching
+ * accessForPath()). deny rules materialize as READ-ONLY, UNREADABLE empty
+ * masks (mode-000 empty-dir ro-bind for dirs, mode-000 empty-file ro-bind for
+ * files) and are emitted whenever they sit under an exposed tree — outside it
+ * they're unreachable already (deny-by-default), and bwrap would fail mounting
+ * onto a void path.
+ *
+ * Two properties this must preserve (both cost real blockers in review):
+ *  1. The mask is `--ro-bind` of an EMPTY source, NOT `--tmpfs`: a `--tmpfs
+ *     <deny>` mount is WRITABLE inside the sandbox, so it hid the real contents
+ *     but still let the CLI write into the denied path — not a real deny.
+ *  2. A deny path is masked EVEN WHEN IT DOES NOT EXIST YET. Skipping absent
+ *     denies left the path inside the read-write parent bind, so the sandbox
+ *     could `mkdir`+write it straight onto the host, and anything the host
+ *     created there mid-session became readable (a stat→exec TOCTOU). The
+ *     worker pre-creates the mountpoint on the host so the mask always binds.
+ */
+export declare function compileToBwrap(policy: FsPolicy, opts: CompileBwrapOpts): BwrapCompilation;
+export interface LegacySandboxFields {
+    sandbox?: boolean;
+    readIsolation?: boolean;
+    sandboxReadonlyPaths?: readonly string[];
+    sandboxHidePaths?: readonly string[];
+    readDenyExtraPaths?: readonly string[];
+}
+export interface MigratedSandboxFields {
+    sandbox: boolean;
+    sandboxPaths?: {
+        readWrite?: string[];
+        readOnly?: string[];
+        deny?: string[];
+    };
+}
+/**
+ * old→new field mapping (lossless: the old fields' expressiveness is a subset
+ * of the three-tier model). Used by the registry's load-time auto-migration,
+ * which writes the NEW fields while KEEPING the old ones in bots.json — a
+ * downgraded daemon reads the untouched old fields, so downgrade needs no
+ * reverse script (design doc §6.2). Returns null when nothing to migrate.
+ */
+export declare function migrateLegacySandboxFields(entry: LegacySandboxFields & {
+    sandboxPaths?: unknown;
+}): MigratedSandboxFields | null;
+//# sourceMappingURL=fs-policy.d.ts.map

package/dist/adapters/cli/fs-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-policy.d.ts","sourceRoot":"","sources":["../../../src/adapters/cli/fs-policy.ts"],"names":[],"mappings":"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"}