bx-mac 1.2.0 → 1.4.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?
 
@@ -45,7 +45,23 @@ bx ~/work/my-project ~/work/shared-lib
 - **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
 - **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** — `sandbox-exec` is undocumented; treat this as a safety net, not a guarantee
+- **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
 
@@ -227,6 +243,8 @@ ro:reference/docs
 ro:shared/toolchain
 ```
 
+`rw:` and `ro:` entries also **override** the built-in protected lists - e.g. `ro:.npmrc` makes the otherwise-blocked `~/.npmrc` readable, `rw:.aws` opens the AWS credentials directory. Files (not just directories) are accepted as targets. Use this with care - you are explicitly weakening the default protection.
+
 Deny rules are applied **in addition** to the built-in protected lists:
 
 > 🔒 **Dotdirs:** `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
@@ -380,7 +398,8 @@ 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 AI Sandboxes](https://docs.docker.com/ai/sandboxes/) — Docker's built-in sandbox environment for AI coding agents. Runs tools in isolated containers with controlled filesystem and network access. Stronger isolation than kernel-level sandboxing, but requires Docker Desktop and adds container overhead.
 - **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.
 

package/dist/bx.js

@@ -953,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",
@@ -1061,7 +1091,7 @@ function parseHomeConfig(home, workDirs) {
 		if (!match) continue;
 		const [, prefix, rawPath] = match;
 		const absolute = resolve(home, rawPath.trim());
-		if (!existsSync(absolute) || !statSync(absolute).isDirectory()) continue;
+		if (!existsSync(absolute)) continue;
 		if (prefix.toUpperCase() === "RW") allowed.add(absolute);
 		else readOnly.add(absolute);
 	}
@@ -1113,16 +1143,20 @@ function collectProtectedContainers(home) {
 	}
 	return matched;
 }
-function collectIgnoredPaths(home, workDirs) {
+function collectReadOnlyDotfiles(home, overrides = /* @__PURE__ */ new Set()) {
+	return PROTECTED_HOME_DOTFILES_RO.map((f) => join(home, f)).filter((p) => !overrides.has(p));
+}
+function collectIgnoredPaths(home, workDirs, overrides = /* @__PURE__ */ new Set()) {
 	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))
-	];
+	].filter((p) => !overrides.has(p));
 	const globalIgnore = join(home, ".bxignore");
 	if (existsSync(globalIgnore)) {
 		const denyLines = parseLines(globalIgnore).filter((l) => !ACCESS_PREFIX_RE.test(l));
-		for (const line of denyLines) ignored.push(...resolveGlobMatches(line, home));
+		for (const line of denyLines) for (const m of resolveGlobMatches(line, home)) if (!overrides.has(m)) ignored.push(m);
 	}
 	for (const workDir of workDirs) collectIgnoreFilesRecursive(workDir, ignored);
 	return ignored;
@@ -1162,17 +1196,18 @@ function collectSystemDenyPaths(home) {
 	} catch {}
 	return paths;
 }
-function generateProfile(workDirs, blockedDirs, ignoredPaths, readOnlyDirs = [], home = "") {
+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 readOnlyRules = sbplDenyBlock("Read-only paths", "file-write*", readOnlyDirs.map(sbplPathRule));
+	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
@@ -1588,8 +1623,8 @@ Configuration:
                        built-in apps (code, xcode) can be overridden
   ~/.bxignore          sandbox rules (one per line):
                          path         block access (deny)
-                         rw:path      allow read-write access
-                         ro:path      allow read-only access
+                         rw:path      allow read-write access (overrides built-in protection)
+                         ro:path      allow read-only access (overrides built-in protection)
   <workdir>/.bxignore  blocked paths in project (.gitignore-style matching)
                          / or .         self-protect: block entire directory
   <dir>/.bxprotect     marker file: block the containing directory
@@ -1664,7 +1699,7 @@ function printDryRunTree({ home, blockedDirs, ignoredPaths, readOnlyDirs, workDi
 }
 //#endregion
 //#region src/index.ts
-const VERSION = "1.2.0";
+const VERSION = "1.4.0";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 if (process$1.argv.includes("--version") || process$1.argv.includes("-v")) {
 	console.log(`bx ${VERSION}`);
@@ -1713,10 +1748,12 @@ async function main() {
 	const profileSandbox = vscodeUserFlag !== false ? vscodeUserFlag : app?.profile ?? false;
 	if (profileSandbox) await setupVSCodeProfile(HOME, profileSandbox);
 	const { allowed, readOnly } = parseHomeConfig(HOME, workDirs);
-	const blockedDirs = collectBlockedDirs(HOME, HOME, __dirname, new Set([...allowed, ...readOnly]));
-	const ignoredPaths = collectIgnoredPaths(HOME, workDirs);
+	const allAccessible = new Set([...allowed, ...readOnly]);
+	const blockedDirs = collectBlockedDirs(HOME, HOME, __dirname, allAccessible);
+	const ignoredPaths = collectIgnoredPaths(HOME, workDirs, allAccessible);
+	const readOnlyDotfiles = collectReadOnlyDotfiles(HOME, allAccessible);
 	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);
@@ -1837,7 +1874,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.2.0",
+  "version": "1.4.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"