@trim21/personal-pi-extensions 0.0.423 → 0.0.425

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.423",
+  "version": "0.0.425",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -23,6 +23,7 @@
     "format": "prettier --write .",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "build:holder": "esbuild src/bwrap/holder.ts --format=esm --target=node24 --outfile=src/bwrap/holder.js",
     "prepare": "husky"
   },
   "peerDependencies": {
@@ -40,6 +41,7 @@
     "@types/turndown": "^5.0.6",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^4.1.10",
+    "esbuild": "^0.28.2",
     "eslint": "^10.8.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-erasable-syntax-only": "0.7.1",

package/src/bwrap/core.ts

@@ -9,12 +9,20 @@ import { type BashOperations, getAgentDir, getShellConfig } from "@earendil-work
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { expandHome } from "../lib/path.js";
 import { type ApprovalRule } from "./approval-rules.js";
+import { type NetworkStack, resolveDnsServers, startNetworkStack } from "./network-stack.js";
 
 const PROTECTED_DIRS = [".pi", ".agent"];
 
-export const BWRAP_MODES = ["allow-all", "workspace-write", "allow-net", "readonly"] as const;
+export const BWRAP_MODES = [
+  "allow-all",
+  "workspace-write",
+  "allow-net",
+  "net-allowlist",
+  "readonly",
+] as const;
 
 export type BwrapMode = (typeof BWRAP_MODES)[number];
 
@@ -25,6 +33,9 @@ const bwrapConfigProperties = {
   extraWritablePaths: Type.Array(Type.String()),
   tmpfsPaths: Type.Array(Type.String()),
   extraArgs: Type.Array(Type.String()),
+  networkAllowlist: Type.Array(Type.String()),
+  singBoxPath: Type.Optional(Type.String()),
+  slirp4netnsPath: Type.Optional(Type.String()),
   approvalRules: Type.Optional(
     Type.Array(
       Type.Object(
@@ -32,18 +43,20 @@ const bwrapConfigProperties = {
           action: StringEnum(["allow", "deny"] as const),
           pattern: Type.String({ description: '命令模式，如 "git push *"、"npm install *"' }),
         },
-        { additionalProperties: false },
+        { additionalProperties: true },
       ),
     ),
   ),
 };
 
+// 配置文件容忍未知字段：schema 之外的字段（如新版本扩展新增的配置）会被忽略，
+// 避免整个 bwrap 配置因单个未知字段失效；已声明字段仍做类型/取值校验。
 export const bwrapConfigSchema = Type.Object(bwrapConfigProperties, {
-  additionalProperties: false,
+  additionalProperties: true,
 });
 
 export const bwrapConfigFileSchema = Type.Partial(bwrapConfigSchema, {
-  additionalProperties: false,
+  additionalProperties: true,
 });
 
 export type BwrapConfig = Static<typeof bwrapConfigSchema>;
@@ -58,6 +71,10 @@ export interface ResolvedBwrap {
   extraWritablePaths: string[];
   tmpfsPaths: string[];
   extraArgs: string[];
+  /** per-domain 过滤的允许域名（非空 = 启用 sing-box 网络过滤）。 */
+  networkAllowlist: string[];
+  singBoxPath?: string;
+  slirp4netnsPath?: string;
   /** 全权限执行的自动审批规则（allow/deny 命令模式）。 */
   approvalRules: ApprovalRule[];
 }
@@ -68,6 +85,7 @@ const DEFAULT_CONFIG: BwrapConfig = {
   extraWritablePaths: [],
   tmpfsPaths: [],
   extraArgs: [],
+  networkAllowlist: [],
 };
 
 export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
@@ -78,6 +96,9 @@ export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
     extraWritablePaths: config.extraWritablePaths,
     tmpfsPaths: config.tmpfsPaths ?? [],
     extraArgs: config.extraArgs ?? [],
+    networkAllowlist: config.networkAllowlist ?? [],
+    singBoxPath: config.singBoxPath,
+    slirp4netnsPath: config.slirp4netnsPath,
     approvalRules: config.approvalRules ?? [],
   };
   switch (config.mode) {
@@ -90,6 +111,9 @@ export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
     case "allow-net": {
       return { ...base, bwrapEnabled: true, network: true };
     }
+    case "net-allowlist": {
+      return { ...base, bwrapEnabled: true, network: true };
+    }
     case "readonly": {
       return { ...base, bwrapEnabled: true, network: false, writablePaths: [] };
     }
@@ -115,6 +139,9 @@ function deepMerge(base: BwrapConfig, overrides: Partial<BwrapConfig>): BwrapCon
     extraWritablePaths: [...base.extraWritablePaths, ...(overrides.extraWritablePaths ?? [])],
     tmpfsPaths: overrides.tmpfsPaths ?? base.tmpfsPaths,
     extraArgs: overrides.extraArgs ?? base.extraArgs,
+    networkAllowlist: overrides.networkAllowlist ?? base.networkAllowlist,
+    singBoxPath: overrides.singBoxPath ?? base.singBoxPath,
+    slirp4netnsPath: overrides.slirp4netnsPath ?? base.slirp4netnsPath,
     approvalRules: [...(base.approvalRules ?? []), ...(overrides.approvalRules ?? [])],
   };
 }
@@ -127,9 +154,10 @@ function parseBwrapConfigFile(path: string): BwrapConfigFile {
     throw new Error(`Invalid bwrap configuration at ${path}: ${String(error)}`, { cause: error });
   }
   try {
-    return Value.Parse(bwrapConfigFileSchema, raw);
+    return parseWithSchema(bwrapConfigFileSchema, raw);
   } catch (error) {
-    throw new Error(`Invalid bwrap configuration at ${path}: ${String(error)}`, { cause: error });
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid bwrap configuration at ${path}: ${detail}`, { cause: error });
   }
 }
 
@@ -190,6 +218,41 @@ export function findBwrap(override?: string): string {
   return findDefaultBwrap();
 }
 
+function findCommandInPath(name: string, hint: string): string {
+  const pathEnv = process.env.PATH ?? "";
+  for (const directory of pathEnv.split(delimiter)) {
+    const candidate = join(directory, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(hint);
+}
+
+export function findSingBox(override?: string): string {
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`sing-box not found at configured path: ${override}`);
+    }
+    return override;
+  }
+  return findCommandInPath(
+    "sing-box",
+    "sing-box not found in PATH. Install it from https://sing-box.sagernet.org/",
+  );
+}
+
+export function findSlirp4netns(override?: string): string {
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`slirp4netns not found at configured path: ${override}`);
+    }
+    return override;
+  }
+  return findCommandInPath(
+    "slirp4netns",
+    "slirp4netns not found in PATH. Install it from https://github.com/rootless-containers/slirp4netns",
+  );
+}
+
 /** 扫描 .git 时跳过的目录：包/依赖/构建产物，嵌套 git 仓库几乎不会出现在这里。 */
 const GIT_DIR_SCAN_SKIP = new Set([
   "node_modules",
@@ -310,6 +373,19 @@ function killChild(child: ChildProcess): void {
   }
 }
 
+/** 为 net-allowlist 模式创建常驻网络栈；非该模式返回 undefined。 */
+export async function createNetworkStack(
+  resolved: ResolvedBwrap,
+): Promise<NetworkStack | undefined> {
+  if (!resolved.network || resolved.networkAllowlist.length === 0) return undefined;
+  return startNetworkStack({
+    allowlist: resolved.networkAllowlist,
+    dnsServers: await resolveDnsServers(),
+    singBoxPath: findSingBox(resolved.singBoxPath),
+    slirp4netnsPath: findSlirp4netns(resolved.slirp4netnsPath),
+  });
+}
+
 /**
  * @param workspace session 工作区：writablePaths 的 "." 与 PROTECTED_DIRS 都基于它解析，
  *   与当次命令的 cwd（仅作为进程执行目录）解耦，避免 workdir 参数漂移可写边界。
@@ -317,6 +393,7 @@ function killChild(child: ChildProcess): void {
 export function createBwrapBashOperations(
   resolved: ResolvedBwrap,
   workspace: string,
+  networkStack?: NetworkStack,
 ): BashOperations {
   // 沙箱内不透传 PATH，execvp 的默认路径可能找不到 bash（如 NixOS），故在父进程解析绝对路径
   const shell = getShellConfig().shell;
@@ -333,7 +410,6 @@ export function createBwrapBashOperations(
         throw new Error("HOME is not set; refusing to run bash in a clean environment");
       }
 
-      const seccompFd = resolved.network ? undefined : getSeccompFd();
       const baseArgs = [
         "--ro-bind",
         "/",
@@ -344,6 +420,33 @@ export function createBwrapBashOperations(
         "--proc",
         "/proc",
       ];
+      const env = {
+        HOME: home,
+        SHELL: "/bin/bash",
+        TERM: "dumb",
+        LANG: "C.UTF-8",
+        // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
+        PATH: "/usr/local/bin:/usr/bin:/bin",
+      };
+
+      if (resolved.network && resolved.networkAllowlist.length > 0) {
+        if (!networkStack) {
+          throw new Error("Network stack is not initialized for net-allowlist mode");
+        }
+        return networkStack.exec({
+          command,
+          cwd,
+          bwrapPath: findBwrap(resolved.bwrapPath),
+          bwrapArgs: baseArgs,
+          shell,
+          env,
+          onData,
+          signal,
+          timeout,
+        });
+      }
+
+      const seccompFd = resolved.network ? undefined : getSeccompFd();
       const child = spawn(
         findBwrap(resolved.bwrapPath),
         seccompFd === undefined
@@ -356,14 +459,7 @@ export function createBwrapBashOperations(
             seccompFd === undefined
               ? ["ignore", "pipe", "pipe"]
               : ["ignore", "pipe", "pipe", seccompFd],
-          env: {
-            HOME: home,
-            SHELL: "/bin/bash",
-            TERM: "dumb",
-            LANG: "C.UTF-8",
-            // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
-            PATH: "/usr/local/bin:/usr/bin:/bin",
-          },
+          env,
         },
       );
 

package/src/bwrap/holder.js

@@ -0,0 +1,61 @@
+import { spawn } from "node:child_process";
+import { open, readFile, writeFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+const args = process.argv.slice(2);
+const configPath = args[0];
+const singBoxPath = args[1];
+const readyFile = args[2];
+if (!configPath || !singBoxPath || !readyFile) {
+  process.exit(2);
+}
+function tap0Exists() {
+  return new Promise((resolve) => {
+    const child = spawn("ip", ["link", "show", "tap0"], { stdio: "ignore" });
+    child.once("exit", (code) => resolve(code === 0));
+    child.once("error", () => resolve(false));
+  });
+}
+async function waitFor(attempts, delayMs, predicate) {
+  for (let i = 0; i < attempts; i++) {
+    if (await predicate()) return true;
+    await sleep(delayMs);
+  }
+  return false;
+}
+async function main() {
+  await waitFor(100, 100, tap0Exists);
+  const logPath = `${configPath}.log`;
+  const logFd = await open(logPath, "w");
+  const singbox = spawn(singBoxPath, ["run", "-c", configPath], {
+    env: { ...process.env, ENABLE_DEPRECATED_MISSING_DOMAIN_RESOLVER: "true" },
+    stdio: ["ignore", logFd.fd, logFd.fd]
+  });
+  const stop = () => {
+    singbox.kill("SIGTERM");
+  };
+  process.on("SIGTERM", () => {
+    stop();
+    process.exit(0);
+  });
+  process.on("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  await waitFor(200, 100, async () => {
+    try {
+      const log = await readFile(logPath, "utf8");
+      return log.includes("sing-box started");
+    } catch {
+      return false;
+    }
+  });
+  await sleep(4e3);
+  await writeFile(readyFile, "");
+  await new Promise((resolve) => singbox.once("exit", () => resolve()));
+}
+try {
+  await main();
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

package/src/bwrap/holder.ts

@@ -0,0 +1,79 @@
+/* eslint-disable no-console, unicorn/no-process-exit -- 独立 CLI 脚本，由 unshare 直接执行 */
+import { spawn } from "node:child_process";
+import { open, readFile, writeFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+
+// 用法：unshare -Urn node holder.ts <config> <singbox> <ready-file>
+const args = process.argv.slice(2);
+const configPath = args[0];
+const singBoxPath = args[1];
+const readyFile = args[2];
+if (!configPath || !singBoxPath || !readyFile) {
+  process.exit(2);
+}
+
+function tap0Exists(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const child = spawn("ip", ["link", "show", "tap0"], { stdio: "ignore" });
+    child.once("exit", (code) => resolve(code === 0));
+    child.once("error", () => resolve(false));
+  });
+}
+
+async function waitFor(
+  attempts: number,
+  delayMs: number,
+  predicate: () => Promise<boolean>,
+): Promise<boolean> {
+  for (let i = 0; i < attempts; i++) {
+    if (await predicate()) return true;
+    await sleep(delayMs);
+  }
+  return false;
+}
+
+async function main(): Promise<void> {
+  // slirp4netns 由宿主侧 spawn，这里等它建好 tap0
+  await waitFor(100, 100, tap0Exists);
+
+  const logPath = `${configPath}.log`;
+  const logFd = await open(logPath, "w");
+  const singbox = spawn(singBoxPath, ["run", "-c", configPath], {
+    env: { ...process.env, ENABLE_DEPRECATED_MISSING_DOMAIN_RESOLVER: "true" },
+    stdio: ["ignore", logFd.fd, logFd.fd],
+  });
+
+  const stop = (): void => {
+    singbox.kill("SIGTERM");
+  };
+  process.on("SIGTERM", () => {
+    stop();
+    process.exit(0);
+  });
+  process.on("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+
+  // tun0 设备在 sing-box 启动早期就创建，但 gvisor 栈初始化仍需时间；
+  // 以 "sing-box started" 日志作为进程就绪标志，再等待栈初始化完成
+  await waitFor(200, 100, async () => {
+    try {
+      const log = await readFile(logPath, "utf8");
+      return log.includes("sing-box started");
+    } catch {
+      return false;
+    }
+  });
+  await sleep(4000);
+  await writeFile(readyFile, "");
+
+  await new Promise<void>((resolve) => singbox.once("exit", () => resolve()));
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

package/src/bwrap/network-stack.ts

@@ -0,0 +1,230 @@
+import { spawn } from "node:child_process";
+import { access, mkdtemp, readFile, readlink, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { generateSingboxConfig } from "./singbox-config.js";
+
+export interface NetworkStackOptions {
+  /** 允许直连的域名列表（session 启动时固定，reload 才会重新加载）。 */
+  readonly allowlist: readonly string[];
+  /** 真实 DNS 服务器列表，按顺序 fallback。 */
+  readonly dnsServers: readonly string[];
+  readonly singBoxPath: string;
+  readonly slirp4netnsPath: string;
+}
+
+export interface NetworkStackExecOptions {
+  readonly command: string;
+  readonly cwd: string;
+  readonly bwrapPath: string;
+  /** bwrap 的完整参数（不含 -- 后的 shell 与命令），由 core.ts 组装。 */
+  readonly bwrapArgs: readonly string[];
+  readonly shell: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly onData: (data: Buffer) => void;
+  readonly signal?: AbortSignal;
+  readonly timeout?: number;
+}
+
+const NAMESERVER_PATTERN = /^\s*nameserver\s+(\S+)/;
+const HOLDER_PATH = fileURLToPath(new URL("holder.js", import.meta.url));
+// ip 通常位于 /usr/sbin 或 /sbin，进程默认 PATH 不含它们；node 则依赖宿主完整 PATH
+const SBIN_PATH_SUFFIX = "/usr/local/sbin:/usr/sbin:/sbin";
+
+function killProcess(pid: number | undefined): void {
+  if (!pid) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // 已退出
+  }
+}
+
+/** 读宿主机 /etc/resolv.conf 的全部 IPv4 nameserver，按声明顺序返回。 */
+export async function resolveDnsServers(): Promise<string[]> {
+  const content = await readFile("/etc/resolv.conf", "utf8");
+  const nameservers = content
+    .split("\n")
+    .map((line) => NAMESERVER_PATTERN.exec(line)?.[1])
+    .filter((value): value is string => value !== undefined);
+  // slirp4netns 出口仅 IPv4，IPv6 nameserver 无法出站，故只保留 IPv4
+  const ipv4 = nameservers.filter((value) => !value.includes(":"));
+  if (ipv4.length === 0) {
+    throw new Error("No IPv4 nameserver found in /etc/resolv.conf");
+  }
+  return ipv4;
+}
+
+/** 等待目标进程进入新的 user namespace（unshare 完成），返回后 slirp4netns 才能 setns。 */
+async function waitForNewUserns(pid: number, timeoutMs = 5000): Promise<void> {
+  const self = await readlink("/proc/self/ns/user");
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      if ((await readlink(`/proc/${pid}/ns/user`)) !== self) return;
+    } catch {
+      // /proc/<pid> 尚未就绪，重试
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error("Timed out waiting for sandbox network namespace");
+}
+
+async function waitForFile(path: string, timeoutMs = 15000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await access(path);
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+  throw new Error("Timed out waiting for sandbox network stack to become ready");
+}
+
+function killChild(pid: number | undefined): void {
+  if (!pid) return;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // 已退出
+    }
+  }
+}
+
+export interface NetworkStack {
+  exec(options: NetworkStackExecOptions): Promise<{ exitCode: number | null }>;
+  stop(): Promise<void>;
+}
+
+interface NetworkStackState {
+  holderPid: number;
+  slirpPid: number | undefined;
+  directory: string;
+}
+
+/** 兜底：调用方忘记 stop() 时，对象被 GC 回收后 kill 残留进程并清理目录。 */
+const stackFinalizer = new FinalizationRegistry<NetworkStackState>((state) => {
+  killProcess(state.slirpPid);
+  killProcess(state.holderPid);
+  void rm(state.directory, { recursive: true, force: true }).catch(() => false);
+});
+
+/**
+ * 启动常驻的 per-session 网络栈：holder 进程持有 netns（内部跑 sing-box 的
+ * TUN + fakeip + deny-by-default），slirp4netns 提供 egress。返回前
+ * netns/sing-box/slirp4netns 均已就绪，命令通过 nsenter 进入该 netns 执行。
+ */
+export async function startNetworkStack(options: NetworkStackOptions): Promise<NetworkStack> {
+  const { allowlist, dnsServers, singBoxPath, slirp4netnsPath } = options;
+  const directory = await mkdtemp(join(tmpdir(), "pi-netns-"));
+  const configPath = join(directory, "singbox.json");
+  const readyFile = join(directory, "ready");
+  await writeFile(configPath, generateSingboxConfig({ allowlist, dnsServers }));
+
+  const holder = spawn(
+    "unshare",
+    ["-Urn", "--", "node", HOLDER_PATH, configPath, singBoxPath, readyFile],
+    {
+      env: {
+        HOME: process.env.HOME ?? "",
+        PATH: `${process.env.PATH ?? ""}:${SBIN_PATH_SUFFIX}`,
+      },
+      stdio: "ignore",
+    },
+  );
+  if (holder.pid === undefined) {
+    throw new Error("Failed to start network namespace holder");
+  }
+  const holderPid = holder.pid;
+  await waitForNewUserns(holderPid);
+
+  const slirp = spawn(
+    slirp4netnsPath,
+    [
+      "-c",
+      `--userns-path=/proc/${holderPid}/ns/user`,
+      "--netns-type=pid",
+      String(holderPid),
+      "tap0",
+    ],
+    { stdio: "ignore" },
+  );
+  const slirpPid = slirp.pid;
+  await waitForFile(readyFile);
+
+  const state: NetworkStackState = { holderPid, slirpPid, directory };
+  const stack: NetworkStack = {
+    exec: async (execOptions: NetworkStackExecOptions) => {
+      const child = spawn(
+        "nsenter",
+        [
+          "-U",
+          "-n",
+          "--preserve-credentials",
+          "-t",
+          String(holderPid),
+          "--",
+          execOptions.bwrapPath,
+          ...execOptions.bwrapArgs,
+          "--",
+          execOptions.shell,
+          "-lc",
+          execOptions.command,
+        ],
+        {
+          cwd: execOptions.cwd,
+          detached: true,
+          stdio: ["ignore", "pipe", "pipe"],
+          env: execOptions.env,
+        },
+      );
+
+      return new Promise<{ exitCode: number | null }>((resolve, reject) => {
+        let timedOut = false;
+        let settled = false;
+        const timeoutHandle = execOptions.timeout
+          ? setTimeout(() => {
+              timedOut = true;
+              killChild(child.pid);
+            }, execOptions.timeout * 1000)
+          : undefined;
+        const onAbort = (): void => {
+          killChild(child.pid);
+        };
+
+        child.stdout?.on("data", execOptions.onData);
+        child.stderr?.on("data", execOptions.onData);
+        execOptions.signal?.addEventListener("abort", onAbort, { once: true });
+
+        child.once("error", (error) => {
+          if (settled) return;
+          settled = true;
+          reject(error);
+        });
+        child.once("close", (exitCode) => {
+          if (settled) return;
+          settled = true;
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          execOptions.signal?.removeEventListener("abort", onAbort);
+          if (execOptions.signal?.aborted) reject(new Error("aborted"));
+          else if (timedOut) reject(new Error(`timeout:${execOptions.timeout}`));
+          else resolve({ exitCode });
+        });
+      });
+    },
+    stop: async () => {
+      killProcess(state.slirpPid);
+      killProcess(state.holderPid);
+      await rm(state.directory, { recursive: true, force: true }).catch(() => false);
+    },
+  };
+  stackFinalizer.register(stack, state);
+  return stack;
+}

package/src/bwrap/runtime.ts

@@ -28,6 +28,7 @@ import { commandPatternsFor } from "./approval-suggest.js";
 import {
   type BwrapMode,
   createBwrapBashOperations,
+  createNetworkStack,
   findBwrap,
   getBwrapConfigPaths,
   loadBwrapConfig,
@@ -37,6 +38,7 @@ import {
   resolveHeadlessBwrap,
 } from "./core.js";
 import { dcgSuggestion } from "./dcg-scan.js";
+import { type NetworkStack } from "./network-stack.js";
 
 export type EscalationDecision = { kind: "dialog" } | { kind: "deny"; reason: string };
 
@@ -230,6 +232,7 @@ function notifyMode(
     "allow-all": "allow-all: sandbox off, network on",
     "workspace-write": "workspace-write: sandbox on, network off",
     "allow-net": "allow-net: sandbox on, network on, workspace writable",
+    "net-allowlist": "net-allowlist: sandbox on, network filtered by domain allowlist",
     readonly: "readonly: sandbox on, network off, read-only fs",
   };
   ctx.ui.notify(labels[mode], "info");
@@ -239,6 +242,7 @@ export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private sandboxDisabled = false;
   private bwrapUnavailable = false;
+  private networkStack: NetworkStack | undefined;
 
   setup(pi: ExtensionAPI): void {
     pi.registerFlag("no-bwrap", {
@@ -311,6 +315,8 @@ export class BwrapRuntime {
   setMode(cwd: string, mode: BwrapMode): ResolvedBwrap {
     this.resolved = resolveBwrap({ ...loadBwrapConfig(cwd), mode });
     this.sandboxDisabled = false;
+    void this.networkStack?.stop();
+    this.networkStack = undefined;
     return this.resolved;
   }
 
@@ -318,6 +324,8 @@ export class BwrapRuntime {
     this.resolved = undefined;
     this.sandboxDisabled = false;
     this.bwrapUnavailable = false;
+    void this.networkStack?.stop();
+    this.networkStack = undefined;
   }
 
   async execute(request: BwrapExecutionRequest): Promise<BwrapExecutionResult> {
@@ -356,7 +364,7 @@ export class BwrapRuntime {
     const operations =
       isWindows || needsApproval || !runtime.bwrapEnabled
         ? createLocalBashOperations()
-        : createBwrapBashOperations(runtime, workspace);
+        : createBwrapBashOperations(runtime, workspace, await this.getNetworkStack(runtime));
     const output = new BashOutput(request.ctx.sessionManager.getSessionId());
     const { onUpdate } = request;
 
@@ -446,6 +454,21 @@ export class BwrapRuntime {
     return this.resolved;
   }
 
+  /** net-allowlist 模式的常驻网络栈：惰性创建，session 期间复用（allowlist 固定）。 */
+  private async getNetworkStack(runtime: ResolvedBwrap): Promise<NetworkStack | undefined> {
+    if (runtime.mode !== "net-allowlist" || runtime.networkAllowlist.length === 0) {
+      if (this.networkStack) {
+        void this.networkStack.stop();
+        this.networkStack = undefined;
+      }
+      return undefined;
+    }
+    if (!this.networkStack) {
+      this.networkStack = await createNetworkStack(runtime);
+    }
+    return this.networkStack;
+  }
+
   private async approveFullAccess(
     ctx: ExtensionContext,
     command: string,
@@ -646,12 +669,24 @@ export class BwrapRuntime {
         description: "Sandbox on, network on, workspace writable",
         flags: Type.Object({}),
       },
+      "bwrap-net-allowlist": {
+        name: "bwrap-net-allowlist",
+        usage: "",
+        description: "Sandbox on, network filtered by domain allowlist, workspace writable",
+        flags: Type.Object({}),
+      },
       "bwrap-readonly": {
         name: "bwrap-readonly",
         usage: "",
         description: "Sandbox on, network off, no writes",
         flags: Type.Object({}),
       },
+      "bwrap-reload": {
+        name: "bwrap-reload",
+        usage: "",
+        description: "Reload bwrap config and restart the network stack",
+        flags: Type.Object({}),
+      },
     } as const satisfies Record<string, CommandSpec<TObject>>;
 
     pi.registerCommand("bwrap", {
@@ -685,6 +720,7 @@ export class BwrapRuntime {
       ["bwrap-allow-all", "allow-all"],
       ["bwrap-workspace-write", "workspace-write"],
       ["bwrap-allow-net", "allow-net"],
+      ["bwrap-net-allowlist", "net-allowlist"],
       ["bwrap-readonly", "readonly"],
     ] as const) {
       pi.registerCommand(name, {
@@ -695,6 +731,24 @@ export class BwrapRuntime {
           ),
       });
     }
+
+    pi.registerCommand("bwrap-reload", {
+      description: specs["bwrap-reload"].description,
+      handler: (args, ctx) =>
+        this.runCommand(pi, specs["bwrap-reload"], args, ctx, (commandCtx) => {
+          this.reload(commandCtx);
+        }),
+    });
+  }
+
+  private reload(ctx: ExtensionCommandContext): void {
+    this.resolved = undefined;
+    this.bwrapUnavailable = false;
+    void this.networkStack?.stop();
+    this.networkStack = undefined;
+    const runtime = this.resolve(ctx);
+    ctx.ui.setStatus("bwrap", ctx.ui.theme.fg("accent", `bwrap: ${runtime.mode}`));
+    ctx.ui.notify(`bwrap config reloaded (mode: ${runtime.mode})`, "info");
   }
 
   private switchMode(pi: ExtensionAPI, mode: BwrapMode, ctx: ExtensionCommandContext): void {

package/src/bwrap/singbox-config.ts

@@ -0,0 +1,77 @@
+const FAKEIP_RANGE = "198.18.0.0/15";
+const TUN_ADDRESS = "198.18.0.1/16";
+const EGRESS_INTERFACE = "tap0";
+
+export interface SingboxConfigOptions {
+  /** 允许直连的域名列表（空列表 = 默认拒绝一切出网）。 */
+  readonly allowlist: readonly string[];
+  /** 真实 DNS 服务器地址列表（IPv4，UDP 53），按顺序 fallback，至少一个。 */
+  readonly dnsServers: readonly string[];
+}
+
+/**
+ * 生成 sing-box 1.13 配置：TUN + fakeip + deny-by-default allowlist。
+ *
+ * - 出站绑定到 slirp4netns 的 tap0，避免 auto_route 把 sing-box 自身出站
+ *   流量（尤其 DNS 解析）重新路由回 TUN 形成环。
+ * - 真实解析不设 domain_resolver（它只接受单个 server 且绕过规则），而是
+ *   用 DNS rules 的顺序 fallback 链：前 N-1 个 nameserver 带 ip_accept_any
+ *   过滤（响应不合格时落到下一条），最后一个作为 dns.final 兜底。
+ *   该用法在 1.13 已标记 deprecated，运行需设置
+ *   ENABLE_DEPRECATED_MISSING_DOMAIN_RESOLVER=true。
+ */
+export function generateSingboxConfig(options: SingboxConfigOptions): string {
+  const { allowlist, dnsServers } = options;
+  const lastServer = dnsServers.at(-1);
+  if (!lastServer) {
+    throw new Error("At least one DNS server is required");
+  }
+  const config = {
+    log: { level: "info", timestamp: false },
+    dns: {
+      servers: [
+        ...dnsServers.map((server, index) => ({
+          type: "udp",
+          tag: `remote-${index}`,
+          server,
+          server_port: 53,
+        })),
+        { type: "fakeip", tag: "fakeip", inet4_range: FAKEIP_RANGE },
+      ],
+      rules: [
+        { query_type: ["A", "AAAA"], server: "fakeip" },
+        ...dnsServers.slice(0, -1).map((_, index) => ({
+          server: `remote-${index}`,
+          ip_accept_any: true,
+        })),
+      ],
+      final: `remote-${dnsServers.length - 1}`,
+      strategy: "prefer_ipv4",
+      independent_cache: true,
+    },
+    inbounds: [
+      {
+        type: "tun",
+        tag: "tun-in",
+        stack: "gvisor",
+        address: [TUN_ADDRESS],
+        auto_route: true,
+        strict_route: true,
+      },
+    ],
+    outbounds: [
+      { type: "direct", tag: "direct" },
+      { type: "block", tag: "block" },
+    ],
+    route: {
+      default_interface: EGRESS_INTERFACE,
+      final: "block",
+      rules: [
+        { action: "sniff" },
+        { protocol: "dns", action: "hijack-dns" },
+        ...(allowlist.length > 0 ? [{ domain: [...allowlist], outbound: "direct" }] : []),
+      ],
+    },
+  };
+  return `${JSON.stringify(config, null, 2)}\n`;
+}

package/src/lib/parse-with-schema.ts

@@ -0,0 +1,21 @@
+import type { Static, TSchema } from "typebox";
+import Value, { ParseError } from "typebox/value";
+
+/**
+ * 用 typebox schema 解析 value。成功返回解析结果；失败抛带字段路径的 Error
+ * （Value.Parse 的 ParseError 错误详情在 cause.errors，默认 message 只有
+ * "Parse"，这里拼成可读信息，供调用方包装上下文如配置文件路径）。
+ */
+export function parseWithSchema<T extends TSchema>(schema: T, value: unknown): Static<T> {
+  try {
+    return Value.Parse(schema, value);
+  } catch (error) {
+    if (error instanceof ParseError) {
+      const details = error.cause.errors
+        .map((e) => `${e.instancePath || "(root)"}: ${e.message}`)
+        .join("; ");
+      throw new Error(details, { cause: error });
+    }
+    throw error;
+  }
+}