@erichll/pi-sandbox 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.2 - 2026-07-30
+
+- Load trusted configuration from
+  `~/.pi/agent/extensions/pi-sandbox/config.json`, with a read fallback to the
+  legacy `~/.pi/agent/pi-sandbox.json` path when the new file is absent.
+- Deny writes to common workspace secrets by default (`.env` variants,
+  `secrets/` / `.secrets/`, and discovered `*.pem` / `*.key` / `*.p12` /
+  `*.pfx`), while leaving template files such as `.env.example` writable.
+- Protect `~/.pi/agent/extensions` (including the extension-local config) from
+  sandboxed writes.
+- On macOS, add git-style secret globs for nested create protection; Linux keeps
+  literal absolute paths only because Sandbox Runtime drops globs there.
+
 ## 0.4.1 - 2026-07-29
 
 - Republish to refresh the npm search index used by the pi.dev package gallery.

package/README.md

@@ -18,8 +18,15 @@ also run complete process-backed subagent trees inside independent sandboxes.
 - Every Bash command and persistent subagent session owns a separate broker
   process and Sandbox Runtime manager. Concurrent workers therefore keep
   independent policy, proxy, approval, and cleanup lifecycles.
-- Project and global Pi security configuration, the installed package, Git
-  hooks, and other Sandbox Runtime mandatory paths remain write-protected.
+- Project and global Pi security configuration, the trusted extensions tree,
+  the installed package, Git hooks, and other Sandbox Runtime mandatory paths
+  remain write-protected.
+- Common workspace secrets are write-denied by default: root-level `.env`
+  variants, `secrets/` / `.secrets/`, plus a shallow scan for nested `.env*`,
+  `*.pem`, `*.key`, `*.p12`, and `*.pfx`. Template files such as
+  `.env.example` stay writable. On macOS, additional globs also block nested
+  creates; Linux Sandbox Runtime only enforces literal paths, so nested creates
+  of new secret files remain a residual risk outside the scanned set.
 - Optional host IPC execution is disabled by default. When enabled, every
   complete host command still requires a one-shot `pi-auto-review` or human
   approval and runs outside the OS sandbox.
@@ -43,7 +50,11 @@ macOS uses built-in Seatbelt support but still requires `ripgrep`.
 ## Subagent provider
 
 The provider is selected only from the trusted global file
-`~/.pi/agent/pi-sandbox.json`:
+`~/.pi/agent/extensions/pi-sandbox/config.json`:
+
+If that file is missing, `pi-sandbox` still loads the legacy path
+`~/.pi/agent/pi-sandbox.json` when present. Prefer the extension-local path for
+new installs.
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",

package/src/config.ts

@@ -31,6 +31,8 @@ export type PiSandboxConfig = {
 
 export type LoadPiSandboxConfigOptions = {
   path?: string;
+  /** Override home directory when resolving default/legacy trusted paths. */
+  home?: string;
 };
 
 export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freeze(
@@ -50,6 +52,18 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
 );
 
 export function getPiSandboxConfigPath(home = homedir()): string {
+  return join(
+    home,
+    ".pi",
+    "agent",
+    "extensions",
+    "pi-sandbox",
+    "config.json",
+  );
+}
+
+/** Legacy trusted path used before the extension-local config layout. */
+export function getLegacyPiSandboxConfigPath(home = homedir()): string {
   return join(home, ".pi", "agent", "pi-sandbox.json");
 }
 
@@ -182,42 +196,48 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
   };
 }
 
-export function loadPiSandboxConfig(
-  options: LoadPiSandboxConfigOptions = {},
-): PiSandboxConfig {
-  const path = options.path ?? getPiSandboxConfigPath();
-  let source: string;
+function defaultPiSandboxConfig(): PiSandboxConfig {
+  return {
+    subagents: { provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider },
+    filesystem: {
+      additionalAllowRead: [
+        ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
+      ],
+    },
+    hostIPC: {
+      mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
+      preflightCommandPrefixes: [
+        ...DEFAULT_PI_SANDBOX_CONFIG.hostIPC.preflightCommandPrefixes,
+      ],
+      retryOnUnixSocketError:
+        DEFAULT_PI_SANDBOX_CONFIG.hostIPC.retryOnUnixSocketError,
+    },
+  };
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+function readPiSandboxConfigFile(path: string): string {
   try {
-    source = readFileSync(path, "utf8");
+    return readFileSync(path, "utf8");
   } catch (error) {
-    if (
-      typeof error === "object" &&
-      error !== null &&
-      "code" in error &&
-      error.code === "ENOENT"
-    ) {
-      return {
-        subagents: { provider: DEFAULT_PI_SANDBOX_CONFIG.subagents.provider },
-        filesystem: {
-          additionalAllowRead: [
-            ...DEFAULT_PI_SANDBOX_CONFIG.filesystem.additionalAllowRead,
-          ],
-        },
-        hostIPC: {
-          mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
-          preflightCommandPrefixes: [
-            ...DEFAULT_PI_SANDBOX_CONFIG.hostIPC.preflightCommandPrefixes,
-          ],
-          retryOnUnixSocketError:
-            DEFAULT_PI_SANDBOX_CONFIG.hostIPC.retryOnUnixSocketError,
-        },
-      };
+    if (isNotFoundError(error)) {
+      throw error;
     }
     throw new Error(`failed to read pi-sandbox configuration at ${path}`, {
       cause: error,
     });
   }
+}
 
+function parsePiSandboxConfigFile(path: string, source: string): PiSandboxConfig {
   let value: unknown;
   try {
     value = JSON.parse(source);
@@ -226,6 +246,35 @@ export function loadPiSandboxConfig(
       cause: error,
     });
   }
-
   return parsePiSandboxConfig(value);
 }
+
+export function loadPiSandboxConfig(
+  options: LoadPiSandboxConfigOptions = {},
+): PiSandboxConfig {
+  const path = options.path ?? getPiSandboxConfigPath(options.home);
+  try {
+    return parsePiSandboxConfigFile(path, readPiSandboxConfigFile(path));
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw error;
+    }
+  }
+
+  // Only fall back to the legacy path when loading the default trusted location.
+  if (options.path === undefined) {
+    const legacyPath = getLegacyPiSandboxConfigPath(options.home);
+    try {
+      return parsePiSandboxConfigFile(
+        legacyPath,
+        readPiSandboxConfigFile(legacyPath),
+      );
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+    }
+  }
+
+  return defaultPiSandboxConfig();
+}

package/src/policy.ts

@@ -1,3 +1,4 @@
+import { readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import {
   dirname,
@@ -18,6 +19,88 @@ const SANDBOX_RUNTIME_ROOT = dirname(
   ),
 );
 
+/** Common secret basenames always denied at the workspace root (even if missing). */
+export const WORKSPACE_SECRET_DENY_WRITE_BASENAMES = [
+  ".env",
+  ".env.local",
+  ".env.development",
+  ".env.development.local",
+  ".env.test",
+  ".env.test.local",
+  ".env.production",
+  ".env.production.local",
+  ".env.staging",
+  ".env.staging.local",
+  ".env.ci",
+] as const;
+
+/** Secret-like directories denied at the workspace root (even if missing). */
+export const WORKSPACE_SECRET_DENY_WRITE_DIRECTORIES = [
+  "secrets",
+  ".secrets",
+] as const;
+
+/** Private-key / certificate extensions denied when discovered under the workspace. */
+export const WORKSPACE_SECRET_DENY_WRITE_EXTENSIONS = [
+  ".pem",
+  ".key",
+  ".p12",
+  ".pfx",
+] as const;
+
+/**
+ * Template / sample env files that agents may legitimately create or edit.
+ * These are excluded from secret write denials.
+ */
+export const WORKSPACE_SECRET_TEMPLATE_BASENAMES = new Set([
+  ".env.example",
+  ".env.sample",
+  ".env.template",
+  ".env.dist",
+]);
+
+const WALK_SKIP_DIRECTORIES = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  "target",
+  "vendor",
+]);
+
+/** Bounded workspace walk used to discover nested secrets on every platform. */
+const WORKSPACE_SECRET_SCAN_MAX_DEPTH = 4;
+
+/**
+ * macOS Seatbelt supports git-style globs; Linux bubblewrap silently drops them.
+ * Keep these as an extra nested-create defense on Darwin only.
+ */
+const DARWIN_SECRET_DENY_WRITE_GLOBS = [
+  "**/.env",
+  "**/.env.local",
+  "**/.env.development",
+  "**/.env.development.local",
+  "**/.env.test",
+  "**/.env.test.local",
+  "**/.env.production",
+  "**/.env.production.local",
+  "**/.env.staging",
+  "**/.env.staging.local",
+  "**/.env.ci",
+  "**/secrets",
+  "**/secrets/**",
+  "**/.secrets",
+  "**/.secrets/**",
+  "**/*.pem",
+  "**/*.key",
+  "**/*.p12",
+  "**/*.pfx",
+] as const;
+
 export type SandboxPolicy = {
   filesystem: {
     denyRead: string[];
@@ -39,6 +122,104 @@ export type CreateDefaultPolicyOptions = {
   additionalAllowRead?: readonly string[];
 };
 
+export function isSecretDenyWriteBasename(name: string): boolean {
+  if (WORKSPACE_SECRET_TEMPLATE_BASENAMES.has(name)) {
+    return false;
+  }
+  if (
+    (WORKSPACE_SECRET_DENY_WRITE_BASENAMES as readonly string[]).includes(name)
+  ) {
+    return true;
+  }
+  // Catch less common variants such as `.env.preview` while sparing templates.
+  if (name.startsWith(".env.")) {
+    return true;
+  }
+  const lower = name.toLowerCase();
+  return WORKSPACE_SECRET_DENY_WRITE_EXTENSIONS.some((extension) =>
+    lower.endsWith(extension),
+  );
+}
+
+function collectNestedSecretDenyWritePaths(
+  workspace: string,
+  maxDepth = WORKSPACE_SECRET_SCAN_MAX_DEPTH,
+): string[] {
+  const discovered: string[] = [];
+
+  const visit = (directory: string, depth: number): void => {
+    if (depth > maxDepth) {
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "." || entry.name === "..") {
+        continue;
+      }
+      const fullPath = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (WALK_SKIP_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        if (
+          (WORKSPACE_SECRET_DENY_WRITE_DIRECTORIES as readonly string[]).includes(
+            entry.name,
+          )
+        ) {
+          discovered.push(fullPath);
+          continue;
+        }
+        visit(fullPath, depth + 1);
+        continue;
+      }
+      if (entry.isFile() && isSecretDenyWriteBasename(entry.name)) {
+        discovered.push(fullPath);
+      }
+    }
+  };
+
+  visit(workspace, 0);
+  return discovered;
+}
+
+/**
+ * Build workspace secret write denials.
+ *
+ * - Always includes root-level secret basenames/directories as absolute paths so
+ *   Linux can block both existing files and first-time creation.
+ * - Scans a shallow workspace tree for nested secrets that already exist.
+ * - Adds Darwin-only globs so nested creates are also blocked on macOS.
+ */
+export function createWorkspaceSecretDenyWritePaths(
+  workspace: string,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const root = resolve(workspace);
+  const paths = new Set<string>();
+
+  for (const name of WORKSPACE_SECRET_DENY_WRITE_BASENAMES) {
+    paths.add(join(root, name));
+  }
+  for (const name of WORKSPACE_SECRET_DENY_WRITE_DIRECTORIES) {
+    paths.add(join(root, name));
+  }
+  for (const discovered of collectNestedSecretDenyWritePaths(root)) {
+    paths.add(discovered);
+  }
+  if (platform === "darwin") {
+    for (const pattern of DARWIN_SECRET_DENY_WRITE_GLOBS) {
+      paths.add(pattern);
+    }
+  }
+
+  return [...paths];
+}
+
 export function createDefaultPolicy(
   cwd: string,
   options: CreateDefaultPolicyOptions = {},
@@ -69,11 +250,24 @@ export function createDefaultPolicy(
         join(workspace, ".pi", "pi-auto-review.json"),
         join(home, ".pi", "agent", "settings.json"),
         join(home, ".pi", "agent", "permissions.json"),
-        join(home, ".pi", "agent", "pi-sandbox.json"),
         join(home, ".pi", "agent", "sandbox.json"),
+        // Legacy config path kept write-protected during migration.
+        join(home, ".pi", "agent", "pi-sandbox.json"),
         join(home, ".pi", "agent", "logs"),
+        // Prevent the sandbox from installing or rewriting trusted extensions
+        // (includes ~/.pi/agent/extensions/pi-sandbox/config.json).
+        join(home, ".pi", "agent", "extensions"),
+        join(
+          home,
+          ".pi",
+          "agent",
+          "extensions",
+          "pi-sandbox",
+          "config.json",
+        ),
         ...(packageIsInWorkspace ? [] : [PACKAGE_ROOT]),
         dirname(process.execPath),
+        ...createWorkspaceSecretDenyWritePaths(workspace),
       ],
     },
     network: {