bx-mac 1.1.0 → 1.3.0

package/README.md

@@ -5,7 +5,7 @@
 [![license](https://img.shields.io/github/license/holtwick/bx-mac)](https://github.com/holtwick/bx-mac/blob/master/LICENSE)
 [![macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](https://github.com/holtwick/bx-mac)
 
-> **Put your AI in a box.** Launch VSCode, Claude Code, a terminal, or any command in a macOS sandbox — your tools can only see the project you're working on.
+> **Put your AI in a box.** Launch VSCode, Claude Code, a terminal, or any command in a macOS sandbox — your tools can only see the project you're working on. Not a vault, but a reasonable safety net.
 
 ## 🤔 Why?
 
@@ -44,7 +44,24 @@ bx ~/work/my-project ~/work/shared-lib
 - **No protection against root/sudo** — the sandbox applies to the user-level process
 - **macOS only** — relies on `sandbox-exec` (Apple-specific)
 - **Not dynamic** — the sandbox profile is a snapshot of `$HOME` at launch time; directories or files created later are **not** automatically blocked
-- **Not a vault** — `sandbox-exec` is undocumented; treat this as a safety net, not a guarantee
+- **File names visible** — blocked files cannot be read or written, but their names still appear in directory listings (a kernel-level `readdir` constraint, same as `chmod 000`)
+- **Not a vault** — this is a safety net, not airtight isolation (see [Security model](#-security-model-allow-first))
+
+## 🧱 Security model: allow-first
+
+bx uses an **allow-first / blocklist** approach: everything is accessible by default, and only sensitive paths are explicitly blocked. This is the opposite of a deny-first / allowlist model where everything is blocked and only specific paths are opened up.
+
+**Why allow-first?** Developer tools require access to an enormous and ever-changing set of paths -- dotfiles, `~/Library`, runtimes, caches, toolchains. A deny-first model would require new allow rules for every tool or framework update, breaking silently when a path is missing. The allow-first model works out of the box without per-tool tuning.
+
+**What this means in practice:**
+
+- bx provides **reasonable protection** against accidental or misguided file access -- not airtight isolation
+- Sensitive paths (credentials, personal data, other projects) are explicitly blocked
+- Paths that are not on the blocklist remain accessible -- including parts of `~/Library` and most dotfiles
+- The sandbox profile is a **snapshot at launch time** -- files created later are not protected
+- `sandbox-exec` itself is undocumented Apple API that could change with OS updates
+
+If you need stricter, deny-first isolation, consider [Agent Safehouse](https://agent-safehouse.dev/) or a Docker/VM-based approach (see [Alternatives](#-alternatives)). bx is designed for the common case: keep AI tools and editors functional while blocking access to things they should never touch.
 
 ## 📥 Install
 
@@ -379,7 +396,9 @@ These are great when available, but they only protect within their own tool. bx
 
 ## 🔗 Alternatives
 
-- [Agent Safehouse](https://agent-safehouse.dev/) — macOS kernel-level sandboxing for LLM coding agents via `sandbox-exec`. Deny-first model that blocks write access outside the project directory.
+- [Agent Safehouse](https://agent-safehouse.dev/) — macOS kernel-level sandboxing for LLM coding agents via `sandbox-exec`. Uses a **deny-first model**: everything is blocked by default and only explicitly listed paths are opened up. This gives you theoretically stricter control (e.g. `~/Library` is fully blocked and only specific subdirs are allowed), but requires more configuration — tools and runtimes that need paths you haven't whitelisted will break silently. If you need that level of precision and are willing to tune profiles per tool, Agent Safehouse may be the better fit. bx uses the opposite **allow-first model** (only sensitive paths are blocked), which works out of the box for VSCode, shells, Claude Code, and other tools without any per-tool configuration.
+- **Docker / VMs** — for stronger isolation, run AI tools in a virtualized environment (containers, VMs). Full process and network isolation at the cost of setup overhead.
+- **Web sandboxes** — browser-based approaches for running AI agents. See Simon Willison's [Living dangerously with Claude](https://simonwillison.net/2025/Oct/22/living-dangerously-with-claude/) for an overview.
 
 ## 💛 Sponsor
 

package/dist/bx.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { accessSync, constants, cpSync, existsSync, globSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, closeSync, constants, cpSync, existsSync, globSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { execFileSync, execSync, spawn } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -811,12 +811,15 @@ function parsePassPaths(val) {
 	if (typeof val === "number" && Number.isInteger(val) && val > 0) return val;
 	if (Array.isArray(val)) {
 		const paths = val.filter((a) => typeof a === "string");
+		if (val.length !== paths.length) console.error(fmt.warn("non-string items in array config were ignored"));
 		if (paths.length > 0) return paths;
+		return false;
 	}
 }
 function parseStringArray(val) {
 	if (Array.isArray(val)) {
 		const items = val.filter((a) => typeof a === "string");
+		if (val.length !== items.length) console.error(fmt.warn("non-string items in array config were ignored"));
 		if (items.length > 0) return items;
 	}
 }
@@ -950,13 +953,43 @@ function resolveAppPath(app) {
 //#endregion
 //#region src/profile.ts
 const PROTECTED_DOTDIRS = [
+	".Trash",
 	".ssh",
 	".gnupg",
 	".docker",
 	".zsh_sessions",
 	".cargo",
 	".gradle",
-	".gem"
+	".gem",
+	".aws",
+	".azure",
+	".azd",
+	".kube",
+	".config/gcloud"
+];
+const PROTECTED_HOME_DOTFILES = [
+	".zsh_history",
+	".bash_history",
+	".sh_history",
+	".node_repl_history",
+	".python_history",
+	".netrc",
+	".git-credentials",
+	".npmrc",
+	".pypirc",
+	".extra"
+];
+const PROTECTED_HOME_DOTFILES_RO = [
+	".zshrc",
+	".zprofile",
+	".zshenv",
+	".zlogin",
+	".zlogout",
+	".bashrc",
+	".bash_profile",
+	".bash_login",
+	".profile",
+	".config/fish/config.fish"
 ];
 const PROTECTED_LIBRARY_DIRS = [
 	"Accounts",
@@ -1084,9 +1117,12 @@ function collectBlockedDirs(parentDir, home, scriptDir, allowedDirs) {
 		} catch {
 			continue;
 		}
-		if (!isDir) continue;
 		if (parentDir === home && name === "Library") continue;
 		if (scriptDir.startsWith(fullPath + "/") || scriptDir === fullPath) continue;
+		if (!isDir) {
+			blocked.push(fullPath);
+			continue;
+		}
 		const status = isAllowedOrAncestor(fullPath, allowedDirs);
 		if (status === "allowed") continue;
 		if (status === "ancestor") {
@@ -1107,9 +1143,13 @@ function collectProtectedContainers(home) {
 	}
 	return matched;
 }
+function collectReadOnlyDotfiles(home) {
+	return PROTECTED_HOME_DOTFILES_RO.map((f) => join(home, f));
+}
 function collectIgnoredPaths(home, workDirs) {
 	const ignored = [
 		...PROTECTED_DOTDIRS.map((d) => join(home, d)),
+		...PROTECTED_HOME_DOTFILES.map((f) => join(home, f)),
 		...PROTECTED_LIBRARY_DIRS.map((d) => join(home, "Library", d)),
 		...new Set(collectProtectedContainers(home))
 	];
@@ -1122,7 +1162,7 @@ function collectIgnoredPaths(home, workDirs) {
 	return ignored;
 }
 function sbplEscape(path) {
-	return path.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+	return path.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
 }
 function sbplSubpath(path) {
 	return `  (subpath "${sbplEscape(path)}")`;
@@ -1156,17 +1196,18 @@ function collectSystemDenyPaths(home) {
 	} catch {}
 	return paths;
 }
-function generateProfile(workDirs, blockedDirs, ignoredPaths, readOnlyDirs = [], home = "") {
-	const blockedRules = sbplDenyBlock("Blocked directories (auto-generated from $HOME contents)", "file*", blockedDirs.map(sbplSubpath));
+function generateProfile(workDirs, blockedDirs, ignoredPaths, readOnlyDirs = [], home = "", readOnlyFiles = []) {
+	const blockedRules = sbplDenyBlock("Blocked paths (auto-generated from $HOME contents)", "file*", blockedDirs.map(sbplPathRule));
 	const ignoredRules = sbplDenyBlock("Hidden paths from .bxignore", "file*", ignoredPaths.map(sbplPathRule));
 	const readOnlyRules = sbplDenyBlock("Read-only directories", "file-write*", readOnlyDirs.map(sbplSubpath));
+	const readOnlyFileRules = sbplDenyBlock("Read-only home dotfiles (shell init - write-protected against injection)", "file-write*", readOnlyFiles.map(sbplLiteral));
 	const systemRules = home ? sbplDenyBlock("System-level restrictions", "file*", collectSystemDenyPaths(home).map(sbplSubpath)) : "";
 	return `; Auto-generated sandbox profile
 ; Working directories: ${workDirs.join(", ")}
 
 (version 1)
 (allow default)
-${blockedRules}${ignoredRules}${readOnlyRules}${systemRules}
+${blockedRules}${ignoredRules}${readOnlyRules}${readOnlyFileRules}${systemRules}
 `;
 }
 //#endregion
@@ -1405,10 +1446,20 @@ function buildCommand(mode, workDirs, home, profileSandbox, appArgs, apps) {
 }
 function buildBuiltinCommand(mode, appArgs) {
 	switch (mode) {
-		case "term": return {
-			bin: process$1.env.SHELL ?? "/bin/zsh",
-			args: ["-l"]
-		};
+		case "term": {
+			const shell = process$1.env.SHELL ?? "/bin/zsh";
+			if (!existsSync(shell)) {
+				console.error(fmt.warn(`shell not found: ${shell}, falling back to /bin/zsh`));
+				return {
+					bin: "/bin/zsh",
+					args: ["-l"]
+				};
+			}
+			return {
+				bin: shell,
+				args: ["-l"]
+			};
+		}
 		case "claude": return {
 			bin: "claude",
 			args: []
@@ -1594,7 +1645,7 @@ function kindIcon(kind) {
 		default: return `${RED}✖${RESET}`;
 	}
 }
-function insertPath(root, homeParts, absPath, kind, isDir) {
+function insertPath(root, absPath, kind, isDir) {
 	const parts = absPath.split("/").filter(Boolean);
 	let node = root;
 	for (const part of parts) {
@@ -1609,7 +1660,6 @@ function insertPath(root, homeParts, absPath, kind, isDir) {
 *  Intermediate directories on the home path are kept as navigation context. */
 function pruneTree(node, currentParts, homeParts, depth) {
 	if (node.kind) return true;
-	depth < homeParts.length && (currentParts[depth], homeParts[depth]);
 	for (const [name, child] of [...node.children]) if (!pruneTree(child, [...currentParts, name], homeParts, depth + 1)) node.children.delete(name);
 	return node.children.size > 0;
 }
@@ -1617,7 +1667,7 @@ function isDirectory(path) {
 	try {
 		return statSync(path).isDirectory();
 	} catch {
-		return path.slice(path.lastIndexOf("/") + 1).startsWith(".");
+		return true;
 	}
 }
 function printNode(node, prefix) {
@@ -1637,11 +1687,11 @@ function printNode(node, prefix) {
 function printDryRunTree({ home, blockedDirs, ignoredPaths, readOnlyDirs, workDirs, systemDenyPaths = [] }) {
 	const root = { children: /* @__PURE__ */ new Map() };
 	const homeParts = home.split("/").filter(Boolean);
-	for (const dir of blockedDirs) insertPath(root, homeParts, dir, "blocked", true);
-	for (const path of ignoredPaths) insertPath(root, homeParts, path, "ignored", isDirectory(path));
-	for (const dir of readOnlyDirs) insertPath(root, homeParts, dir, "read-only", true);
-	for (const dir of workDirs) insertPath(root, homeParts, dir, "workdir", true);
-	for (const dir of systemDenyPaths) insertPath(root, homeParts, dir, "blocked", true);
+	for (const dir of blockedDirs) insertPath(root, dir, "blocked", isDirectory(dir));
+	for (const path of ignoredPaths) insertPath(root, path, "ignored", isDirectory(path));
+	for (const dir of readOnlyDirs) insertPath(root, dir, "read-only", true);
+	for (const dir of workDirs) insertPath(root, dir, "workdir", true);
+	for (const dir of systemDenyPaths) insertPath(root, dir, "blocked", true);
 	pruneTree(root, [], homeParts, 0);
 	console.log(`\n${CYAN}/${RESET}`);
 	printNode(root, "");
@@ -1649,7 +1699,7 @@ function printDryRunTree({ home, blockedDirs, ignoredPaths, readOnlyDirs, workDi
 }
 //#endregion
 //#region src/index.ts
-const VERSION = "1.1.0";
+const VERSION = "1.3.0";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 if (process$1.argv.includes("--version") || process$1.argv.includes("-v")) {
 	console.log(`bx ${VERSION}`);
@@ -1675,6 +1725,10 @@ async function main() {
 	const { mode, workArgs, verbose, dry, vscodeUser: vscodeUserFlag, background: backgroundFlag, appArgs, implicit } = parseArgs(getValidModes(apps));
 	const app = apps[mode];
 	const workDirs = expandGlobs(implicit && app?.paths?.length ? app.paths : workArgs, HOME).map((a) => realpathSync(resolve(a)));
+	if (workDirs.length === 0) {
+		console.error(`\n${fmt.error("no matching working directories found")}\n`);
+		process$1.exit(1);
+	}
 	if (implicit && !app?.paths?.length) {
 		if (workDirs.some((d) => d === HOME)) {
 			console.error(`\n${fmt.error("no working directory specified and current directory is $HOME")}\n`);
@@ -1696,8 +1750,9 @@ async function main() {
 	const { allowed, readOnly } = parseHomeConfig(HOME, workDirs);
 	const blockedDirs = collectBlockedDirs(HOME, HOME, __dirname, new Set([...allowed, ...readOnly]));
 	const ignoredPaths = collectIgnoredPaths(HOME, workDirs);
+	const readOnlyDotfiles = collectReadOnlyDotfiles(HOME);
 	printPolicySummary(mode, workDirs, blockedDirs, ignoredPaths, readOnly);
-	const profile = generateProfile(workDirs, blockedDirs, ignoredPaths, [...readOnly], HOME);
+	const profile = generateProfile(workDirs, blockedDirs, ignoredPaths, [...readOnly], HOME, readOnlyDotfiles);
 	if (verbose) {
 		console.error("\n--- Generated sandbox profile ---");
 		console.error(profile);
@@ -1755,7 +1810,12 @@ async function main() {
 				CODEBOX_SANDBOX: "1"
 			}
 		});
+		child.on("error", (err) => {
+			console.error(fmt.error(`failed to start sandbox: ${err.message}`));
+			process$1.exit(1);
+		});
 		child.unref();
+		closeSync(logFd);
 		bringAppToFront(mode, apps);
 		console.error(fmt.info(`running in background (pid ${child.pid})`));
 		console.error(fmt.detail(`log: ${logPath}`));
@@ -1779,7 +1839,6 @@ async function main() {
 			CODEBOX_SANDBOX: "1"
 		}
 	});
-	bringAppToFront(mode, apps);
 	const cleanup = () => {
 		try {
 			rmSync(tmpDir, {
@@ -1789,6 +1848,11 @@ async function main() {
 		} catch {}
 	};
 	process$1.on("exit", cleanup);
+	child.on("error", (err) => {
+		console.error(fmt.error(`failed to start sandbox: ${err.message}`));
+		process$1.exit(1);
+	});
+	bringAppToFront(mode, apps);
 	child.on("close", (code) => {
 		process$1.exit(code ?? 0);
 	});
@@ -1809,7 +1873,7 @@ function printPolicySummary(mode, workDirs, blockedDirs, ignoredPaths, readOnly)
 	console.error(`\n${fmt.info(`${mode} → ${dirLabel}`)}`);
 	const parts = [`${blockedDirs.length} blocked`, `${ignoredPaths.length} hidden`];
 	if (readOnly.size > 0) parts.push(`${readOnly.size} read-only`);
-	const extraIgnored = ignoredPaths.length - PROTECTED_DOTDIRS.length;
+	const extraIgnored = ignoredPaths.length - PROTECTED_DOTDIRS.length - PROTECTED_HOME_DOTFILES.length;
 	if (extraIgnored > 0) parts.push(`${extraIgnored} from .bxignore`);
 	console.error(fmt.detail(parts.join(" · ")));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-mac",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Sandbox any macOS app — only your project directory stays accessible",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
     "darwin"
   ],
   "devDependencies": {
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "rolldown": "^1.0.0-rc.13",
     "smol-toml": "^1.6.1",
     "vitest": "^4.1.2"