@erichll/pi-sandbox 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.23.0 - 2026-10-02
+
+- Add opt-in `network.strictAllowlist` (default `false`) to deny unmatched
+  destinations without model or human approval. Forward the setting to Sandbox
+  Runtime for Bash and built-in workers, including persistent follow-up and
+  nested handoff.
+- Merge global/project strict mode with logical OR while retaining domain-list
+  unions. Both files remain trusted policy sources: projects can add endpoints
+  but cannot disable globally required strict enforcement.
+- Reject strict mode combined with Host-IPC `ask` after configuration merging
+  and embedding overrides. Keep non-strict approval and host forwarding behavior.
+- Require `@erichll/pi-auto-review` `^0.23.0` for current-session review models
+  and full-command execution-context validation.
+- Cover real Linux broker network enforcement, persistent worker lifecycle and
+  startup failures with synthetic endpoints; isolate configuration tests from
+  the developer's working directory.
+
 ## 0.22.1 - 2026-10-01
 
 - Fix sandboxed Bash on Bun-compiled Pi: launching the Sandbox Runtime broker

package/README.md

@@ -157,6 +157,7 @@ Domain authorization can be configured globally at
 ```json
 {
   "network": {
+    "strictAllowlist": false,
     "allowedDomains": [
       "github.com",
       "*.github.com",
@@ -179,14 +180,50 @@ The precedence is deterministic:
 
 1. A matching `deniedDomains` entry rejects the connection.
 2. Otherwise, a matching `allowedDomains` entry permits it without review.
-3. Otherwise, the canonical public hostname and port enter the existing
+3. Otherwise, if `strictAllowlist` is `true`, the connection is denied without
+   invoking the Runtime ask callback, model review, or human approval.
+4. Otherwise, the canonical public hostname and port enter the existing
    one-shot auto-review or human approval flow.
 
-Both arrays default to empty. That preserves the prior behavior: no persistent
-network authorization, with every eligible public connection reviewed once.
-The same trusted arrays govern main-agent Bash, built-in subagents, and the
+Both arrays default to empty and `strictAllowlist` defaults to `false`, preserving
+the existing per-connection approval behavior. The setting accepts only a boolean.
+With strict mode and an empty allowlist, all proxied destinations are denied.
+`deniedDomains: ["*"]` also blocks allowed entries because deny rules take priority.
+The same network policy governs main-agent Bash, user Bash, built-in subagents, and the
 sandboxed Bash tool loaded by protected native `pi-subagents` children.
 
+For a worker restricted to explicitly approved inference endpoints:
+
+```json
+{
+  "subagents": { "provider": "builtin" },
+  "network": {
+    "strictAllowlist": true,
+    "allowedDomains": ["inference.example.com:443"],
+    "deniedDomains": []
+  },
+  "hostIPC": { "mode": "off" }
+}
+```
+
+Replace the example hostname with your approved endpoint. Global and project
+`strictAllowlist` values merge with logical OR: a project cannot disable strict
+mode required globally. Domain lists still form unions, so a project **can add
+allowed destinations**. Both files are trusted policy inputs; the global allowlist
+is not an administrative upper bound on project permissions.
+
+Strict mode cannot be combined with `hostIPC.mode: "ask"`, since host execution
+would escape the network sandbox. The effective configuration is rejected before
+tools or workers are created; set Host-IPC mode to `off`. This is checked after
+global/project merging, and again after an embedding's Host-IPC override.
+
+Configuration is loaded when the extension is registered. Existing persistent
+workers keep their policy through follow-up, and handoff workers receive the same
+configured policy. Reload the extension and create new workers to apply file
+changes; there is no configuration hot reload. Broker startup failure never retries
+the worker outside the sandbox, and unavailable approval services cannot relax a
+strict network denial.
+
 Domain allowlists are not a complete data-loss-prevention boundary. A
 multi-tenant or user-uploadable destination such as `github.com` can itself be
 an exfiltration channel; grant only the narrow domains and ports you intend.
@@ -229,7 +266,7 @@ approval warns that the first attempt may already have had partial side
 effects. Successful, timed-out, or aborted commands are never retried.
 
 Host forwarding is intentionally unavailable inside built-in subagents in
-this version.
+this version. It is also incompatible with `network.strictAllowlist: true`.
 
 ## Additional trusted read paths
 
@@ -269,8 +306,12 @@ In addition to user-level configuration at `~/.pi/agent/extensions/pi-sandbox/co
 ```
 
 When present, project configuration is merged with global configuration:
+
 - Array policies (`additionalAllowRead`, `allowedDomains`, `deniedDomains`, `preflightCommandPrefixes`) form a deduplicated union.
 - Scalar settings (`provider`, `mode`, `retryOnUnixSocketError`) allow project-level overrides.
+- `network.strictAllowlist` uses logical OR: `true` in either file enables it.
+  Both configuration files are trusted; project allowlist additions remain effective.
+- The merged configuration must not enable both strict allowlist and Host-IPC `ask`.
 
 **Read-only Security Guarantee**:
 Project-level configuration is explicitly protected in the sandbox policy (`denyWrite`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "Linux (bubblewrap) and macOS (Seatbelt) process sandbox for Pi backed by Anthropic's @anthropic-ai/sandbox-runtime. Fail-closed static filesystem policy plus per-connection network approval from pi-auto-review; sandboxes main-agent Bash and built-in subagent process trees.",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.77",
-    "@erichll/pi-auto-review": "^0.22.1",
+    "@erichll/pi-auto-review": "^0.23.0",
     "jiti": "2.7.0"
   },
   "peerDependencies": {

package/src/config.ts

@@ -23,6 +23,8 @@ export type HostIPCConfig = {
 export type NetworkConfig = {
   readonly allowedDomains: readonly string[];
   readonly deniedDomains: readonly string[];
+  /** Deny unmatched destinations without review. Defaults to false. */
+  readonly strictAllowlist?: boolean;
 };
 
 export type PiSandboxConfig = {
@@ -34,7 +36,7 @@ export type PiSandboxConfig = {
   filesystem: {
     additionalAllowRead: readonly string[];
   };
-  network: NetworkConfig;
+  network: NetworkConfig & { readonly strictAllowlist: boolean };
   hostIPC: HostIPCConfig;
 };
 
@@ -57,6 +59,7 @@ export const DEFAULT_PI_SANDBOX_CONFIG: Readonly<PiSandboxConfig> = Object.freez
     network: Object.freeze({
       allowedDomains: Object.freeze([]),
       deniedDomains: Object.freeze([]),
+      strictAllowlist: false,
     }),
     hostIPC: Object.freeze({
       mode: "off",
@@ -263,9 +266,15 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
     }
     rejectUnknownKeys(
       value.network,
-      ["allowedDomains", "deniedDomains"],
+      ["allowedDomains", "deniedDomains", "strictAllowlist"],
       "network",
     );
+    const strictAllowlist = value.network.strictAllowlist;
+    if (strictAllowlist !== undefined && typeof strictAllowlist !== "boolean") {
+      throw new Error(
+        "invalid pi-sandbox configuration: network.strictAllowlist must be a boolean",
+      );
+    }
     const normalizeDomainList = (
       key: "allowedDomains" | "deniedDomains",
     ): string[] | undefined => {
@@ -310,6 +319,7 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
     parsedNetwork = {
       ...(allowed !== undefined ? { allowedDomains: allowed } : {}),
       ...(denied !== undefined ? { deniedDomains: denied } : {}),
+      ...(strictAllowlist !== undefined ? { strictAllowlist } : {}),
     };
   }
 
@@ -376,7 +386,24 @@ export function parsePiSandboxConfigRaw(value: unknown): PartialPiSandboxConfig
 }
 
 export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
-  const raw = parsePiSandboxConfigRaw(value);
+  const config = resolvePiSandboxConfig(parsePiSandboxConfigRaw(value));
+  validatePiSandboxConfig(config);
+  return config;
+}
+
+/** Validate the effective policy, after merging configuration layers. */
+export function validatePiSandboxConfig(
+  config: { network: NetworkConfig; hostIPC: HostIPCConfig },
+): void {
+  if (config.network.strictAllowlist && config.hostIPC.mode === "ask") {
+    throw new Error(
+      'invalid pi-sandbox configuration: network.strictAllowlist=true cannot be combined with hostIPC.mode="ask"; set hostIPC.mode="off" to keep execution sandboxed',
+    );
+  }
+}
+
+/** Apply defaults without validating conflicts in an intermediate layer. */
+function resolvePiSandboxConfig(raw: PartialPiSandboxConfig): PiSandboxConfig {
   const provider =
     raw.subagents?.provider ?? DEFAULT_PI_SANDBOX_CONFIG.subagents.provider;
   const isPiSubagents = provider === "pi-subagents";
@@ -400,6 +427,7 @@ export function parsePiSandboxConfig(value: unknown): PiSandboxConfig {
       ],
     },
     network: {
+      strictAllowlist: raw.network?.strictAllowlist ?? false,
       allowedDomains: [
         ...(raw.network?.allowedDomains ??
           DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains),
@@ -435,6 +463,7 @@ function defaultPiSandboxConfig(): PiSandboxConfig {
     network: {
       allowedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.allowedDomains],
       deniedDomains: [...DEFAULT_PI_SANDBOX_CONFIG.network.deniedDomains],
+      strictAllowlist: DEFAULT_PI_SANDBOX_CONFIG.network.strictAllowlist,
     },
     hostIPC: {
       mode: DEFAULT_PI_SANDBOX_CONFIG.hostIPC.mode,
@@ -507,7 +536,7 @@ export function mergePiSandboxConfigs(
     allowedNativeAgents = [...new Set([...trustedAgents, ...projectAgents])];
   }
 
-  return {
+  const merged: PiSandboxConfig = {
     subagents: {
       provider,
       ...(isPiSubagents
@@ -526,6 +555,10 @@ export function mergePiSandboxConfigs(
       ],
     },
     network: {
+      // Both configuration files are trusted policy inputs. Projects may add
+      // destinations, but cannot turn off strict enforcement required globally.
+      strictAllowlist:
+        trusted.network.strictAllowlist || (project.network?.strictAllowlist ?? false),
       allowedDomains: [
         ...new Set([
           ...trusted.network.allowedDomains,
@@ -552,6 +585,8 @@ export function mergePiSandboxConfigs(
         trusted.hostIPC.retryOnUnixSocketError,
     },
   };
+  validatePiSandboxConfig(merged);
+  return merged;
 }
 
 export function loadPiSandboxConfig(
@@ -572,9 +607,8 @@ export function loadPiSandboxConfig(
   const globalPath = getPiSandboxConfigPath(options.home);
   let globalConfig: PiSandboxConfig | undefined;
   try {
-    globalConfig = parsePiSandboxConfigFile(
-      globalPath,
-      readPiSandboxConfigFile(globalPath),
+    globalConfig = resolvePiSandboxConfig(
+      parsePiSandboxConfigFileRaw(globalPath, readPiSandboxConfigFile(globalPath)),
     );
   } catch (error) {
     if (!isNotFoundError(error)) {
@@ -599,5 +633,6 @@ export function loadPiSandboxConfig(
   if (projectRaw) {
     return mergePiSandboxConfigs(base, projectRaw);
   }
+  validatePiSandboxConfig(base);
   return base;
 }

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 } from "./approval.ts";
 import {
   loadPiSandboxConfig,
+  validatePiSandboxConfig,
   type HostIPCConfig,
   type NetworkConfig,
   type SubagentProvider,
@@ -220,6 +221,8 @@ async function performRegistration(
   let currentTurn = 0;
   const cwd = process.cwd();
   const config = loadPiSandboxConfig({ cwd });
+  const hostIPC = options.hostIPC ?? config.hostIPC;
+  validatePiSandboxConfig({ network: config.network, hostIPC });
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const isNativeSubagentChild = process.env.PI_SUBAGENT_CHILD === "1";
@@ -237,7 +240,6 @@ async function performRegistration(
     : undefined;
   const additionalAllowRead = config.filesystem.additionalAllowRead;
   const network = config.network;
-  const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
     subagentProvider === "builtin"
       ? (options.subagentManager ??
@@ -625,10 +627,13 @@ async function performRegistration(
       return;
     }
     if (ctx.hasUI) {
+      const networkMode = network.strictAllowlist
+        ? "strict network allowlist (unmatched destinations denied without review)"
+        : "per-connection network review";
       ctx.ui.notify(
         process.platform === "darwin"
-          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and per-connection network review`
-          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and per-connection network review`,
+          ? `${EXTENSION_NAME} enabled: macOS Sandbox Runtime with static filesystem/domain policy and ${networkMode}`
+          : `${EXTENSION_NAME} enabled: Linux Sandbox Runtime with static filesystem/domain policy and ${networkMode}`,
         "info",
       );
     }

package/src/policy.ts

@@ -115,6 +115,7 @@ export type SandboxPolicy = {
   network: {
     allowedDomains: string[];
     deniedDomains: string[];
+    strictAllowlist?: boolean;
     allowLocalBinding: boolean;
     allowAllUnixSockets: boolean;
     allowUnixSockets: string[];
@@ -273,6 +274,7 @@ export function createDefaultPolicy(
     network: {
       allowedDomains: [...(options.network?.allowedDomains ?? [])],
       deniedDomains: [...(options.network?.deniedDomains ?? [])],
+      strictAllowlist: options.network?.strictAllowlist ?? false,
       allowLocalBinding: false,
       allowAllUnixSockets: false,
       allowUnixSockets: [],
@@ -296,6 +298,7 @@ export function toSandboxRuntimeConfig(
     network: {
       allowedDomains: [...policy.network.allowedDomains],
       deniedDomains: [...policy.network.deniedDomains],
+      strictAllowlist: policy.network.strictAllowlist ?? false,
       allowLocalBinding: policy.network.allowLocalBinding,
       allowAllUnixSockets: policy.network.allowAllUnixSockets,
       allowUnixSockets: [...policy.network.allowUnixSockets],