@trim21/personal-pi-extensions 0.1.619 → 0.1.621

package/README.md

@@ -52,7 +52,7 @@ fs（文件系统）与 network（网络）各自独立取值，可任意组合
 | `network` | `limited`         | 仅白名单可达：deny-by-default 过滤，`network.allowlist` 之外全部拒绝    |
 | `network` | `allow-all`       | 网络不受限                                                              |
 
-默认 `fs: workspace-write` + `network: block`。两者都 `allow-all` 时完全不经 bwrap、直接执行；其余组合都在 bwrap 里执行：`block` 用 `--unshare-net` 断网，`limited` 叠一层 mihomo TUN（fakeip DNS）+ slirp4netns egress NAT，只有 allowlist 里的域名 / IP / CIDR 可达，未命中流量在连接层被拒（allowlist 为空 = 全部拒绝）。进程模型、生命周期与设计约束见 `src/bwrap/README.md`。
+默认 `fs: workspace-write` + `network: block`。两者都 `allow-all` 时完全不经 bwrap、直接执行；其余组合都在 bwrap 里执行：`block` 用 `--unshare-net` 断网，`limited` 叠一层 mihomo TUN（白名单 fakeip DNS）+ slirp4netns egress NAT，只有 allowlist 里的域名 / IP / CIDR 可达：未允许域名在 DNS 层即解析失败，裸 IP 连接在连接层被拒（allowlist 为空 = 全部拒绝）。条目匹配语义（精确 / `*.` 子域名）见 `src/bwrap/README.md`，进程模型与设计约束见同一文档。
 
 ### 提权机制
 
@@ -104,7 +104,8 @@ bash 工具（opencode 风格 `bash`、Claude Code 风格 `Bash`）注册了 `da
   "network": {
     "mode": "block",
     // limited 模式允许直连的域名 / IP / CIDR，可带 :port；空 = 全部拒绝
-    "allowlist": ["github.com", "*.githubassets.com"],
+    // 域名精确匹配，需要子域名时加 "*." 前缀（"*.github.com" 不含 github.com 本身）
+    "allowlist": ["github.com", "*.github.com", "*.githubassets.com"],
     // mihomo / slirp4netns 可执行文件路径（可选，缺省走 PATH）
     "mihomoPath": "/usr/local/bin/mihomo",
     "slirp4netnsPath": "/usr/bin/slirp4netns",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.619",
+  "version": "0.1.621",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/README.md

@@ -34,18 +34,43 @@ allowlist 变更因此即时生效，代价是每条命令重新启动一次 mih
 
 ## 网络路径
 
-- **mihomo（③）**：TUN（`auto-route` + `strict-route`）+ fakeip +
-  deny-by-default。`network.allowlist` 域名进 `fake-ip-filter`（真实解析），DNS 层
-  `DOMAIN-SUFFIX,…,DIRECT`；连接层未命中 allowlist 的流量 `MATCH,REJECT`。
-  注意：fakeip 对不在 filter 里的域名**直接本地应答**，不会走到
-  `dns.rules` 的 REJECT——未允许域名是先拿 fakeip、连接层再被拒。
+- **mihomo（③）**：TUN（`auto-route` + `strict-route`）+ **白名单 fakeip** +
+  deny-by-default。`network.allowlist` 的域名进 `fake-ip-filter`，配合
+  `fake-ip-filter-mode: whitelist` 即「只有这些域名拿 fake IP」；`dns.nameserver`
+  是 `rcode://name_error` 伪服务器，未命中白名单的域名（即未允许域名）落到它上面
+  即时拿到 NXDOMAIN（客户端报 `Could not resolve host`）；连接层再用 `MATCH,REJECT`
+  兜底裸 IP 连接。`dns.direct-nameserver` 必须指向真实 DNS：连接由 fake IP 还原成
+  域名后，DIRECT 出站要按域名重新解析，否则会解析回 fake-ip 再进 TUN 成环。
+  这样两边都成立：未允许域名在 DNS 层就被拒，allowlist 域名的归属又由 fake IP
+  精确给出（不依赖嗅探、不受 DNS TTL 影响）。
 - **slirp4netns（④）**：egress NAT。它 fork helper 进 netns 创建 tap0 并把
   tapfd 传回主进程，真正的出站 socket 在宿主 netns。
 - **interface-name: tap0**：mihomo 出站静态绑定 slirp 接口。不能用
   `auto-detect-interface` 顶替——启动瞬间 tap0 可能尚未就绪，monitor 事后
   纠正但 DNS 拨号已走错接口，上游查询进自己的 TUN 被 `dns-hijack` 自劫持。
 - **mihomo `-d <uuid 目录>`**：cache.db 等落盘位置，放
-  `<agentDir>/tmp/mihomo-<uuid>/`，每次启动独立目录避免并发争抢 bbolt 锁。
+  `<agentDir>/tmp/mihomo-<uuid>/`，每次启动独立目录避免并发争抢 bbolt 锁；
+  停栈时删除，启动失败时保留作诊断材料。
+
+## allowlist 条目
+
+条目形式为「域名 / IPv4 / CIDR（可带 `:port`）」，域名有两档匹配精度——两层
+（DNS 白名单与连接层规则）语义严格一致：
+
+| 条目                    | 匹配                                             | 不匹配                               |
+| ----------------------- | ------------------------------------------------ | ------------------------------------ |
+| `example.com`           | `example.com`                                    | `www.example.com`、`a.b.example.com` |
+| `*.example.com`         | `www.example.com`、`a.b.example.com`（任意深度） | `example.com`、`notexample.com`      |
+| `example.com:443`       | 精确域名 + 仅 443                                | 其它端口                             |
+| `*.example.com:443`     | 子域名 + 仅 443                                  | `example.com`、其它端口              |
+| `1.2.3.4`、`10.0.0.0/8` | 对应 IP / 网段                                   | —                                    |
+
+- 裸域名是**精确匹配**（不是子树），需要「域名本身 + 子域名」同时放行时写两条。
+- `*.` 必须占据完整的最左标签：`*`、`*example.com`、`a.*.example.com` 都是配置错误；
+  通配只对域名有效，IP 范围用 CIDR 表达。
+- 端口只约束连接层（DNS 无端口语义）：`example.com:443` 能解析，但只有 443 能连。
+- 映射到 mihomo：精确条目在 DNS 侧是裸域名、连接层是 `DOMAIN`；通配条目在 DNS 侧
+  是 `.example.com`（dot-wildcard）、连接层是 `DOMAIN-WILDCARD,*.example.com`。
 
 ## 生命周期与清理
 
@@ -77,9 +102,13 @@ dup 给 slirp4netns，且仅在子进程存活期间有效。
    持 tapfd 泄漏 netns。
 2. **tap fd pin 住 netns**：slirp4netns 持有 tapfd 期间 netns 不会销毁，
    所以任何架构下 slirp4netns 的终止都必须显式保证（stop() / exit-fd）。
-3. **fakeip 短路**：`dns.rules` 的 REJECT 拦不住 fakeip 应答，deny-by-default
-   实际由连接层 `MATCH,REJECT` 兜底。诊断时不要把"未允许域名能解析出
-   198.18.x.x"当成 DNS 层放行。
+3. **DNS 层拒绝要靠收窄 fakeip，不能靠 DNS 规则**：mihomo 没有 `dns.rules`
+   这个字段（`config.RawDNS` 里不存在，写进配置会被静默忽略），`fake-ip` 分支
+   也没有按域名拒绝的钩子——命中 fakeip 就直接回合成 IP。要让未允许域名在 DNS
+   层失败，只能把它们排除在 fakeip 白名单之外（`fake-ip-filter-mode: whitelist`），
+   让查询落到 `nameserver`，再由 `rcode://name_error` 即时回 NXDOMAIN。
+   诊断时注意两点：allowlist 域名解析出 `198.18.x.x` 是**正常现象**（fakeip 生效），
+   未允许域名则应当**解析失败**而不是解析出 fakeip。
 4. **诊断手段**：`pnpm sandbox --verbose` 透传 holder（mihomo/slirp4netns）
    日志；`nsenter -U -n --preserve-credentials -t <holderPid>` 可手动进入
    netns 用 AF_PACKET 抓 tap0 / 检查 `ip rule`（注意：沙盒里看不到宿主机

package/src/bwrap/core.ts

@@ -58,7 +58,10 @@ const fsConfigProperties = {
 const networkConfigProperties = {
   mode: StringEnum(NETWORK_MODES),
   allowlist: Type.Array(
-    Type.String({ description: "limited 模式允许直连的域名 / IP / CIDR，可带 :port" }),
+    Type.String({
+      description:
+        'limited 模式允许直连的域名 / IP / CIDR，可带 :port；域名默认精确匹配，加 "*." 前缀表示其全部子域名（任意深度，不含该域名本身），如 "*.example.com"',
+    }),
   ),
   mihomoPath: Type.Optional(Type.String()),
   slirp4netnsPath: Type.Optional(Type.String()),

package/src/bwrap/mihomo-config.ts

@@ -1,4 +1,6 @@
 const FAKEIP_RANGE = "198.18.0.1/16";
+/** mihomo 的拒绝伪 DNS 服务器：即时返回 NXDOMAIN，不查上游、不等超时。 */
+const REJECT_NAMESERVER = "rcode://name_error";
 /** TUN 与 slirp4netns tap0 共用；不对齐时大包会在 slirp NAT 后 PMTU blackhole。 */
 export const TUN_MTU = 1500;
 
@@ -12,6 +14,8 @@ export interface MihomoConfigOptions {
 interface AllowlistEntry {
   readonly host: string;
   readonly port?: number;
+  /** `*.host` 条目：匹配 host 的全部子域名（任意深度），不含 host 本身。 */
+  readonly subdomains: boolean;
 }
 
 /** mihomo 配置以 JSON 序列化输出（JSON 是 YAML 子集，-f 加载无差别）。 */
@@ -27,11 +31,15 @@ export interface MihomoConfig {
     ipv6: false;
     "enhanced-mode": "fake-ip";
     "fake-ip-range": string;
+    /** whitelist：只有 fake-ip-filter 命中的域名才拿 fake IP，其余走 nameserver。 */
+    "fake-ip-filter-mode": "whitelist";
+    /** fake IP 白名单：allowlist 里的域名（带端口条目的域名也进）。 */
+    "fake-ip-filter"?: string[];
+    /** 默认解析服务器：拒绝伪服务器，未命中白名单的域名（即未允许域名）即时 NXDOMAIN。 */
     nameserver: string[];
     "default-nameserver": string[];
-    "fake-ip-filter"?: string[];
-    /** 域名级 DNS 规则（mihomo >= 1.18）：allowlist 域名 DIRECT，其余 REJECT。 */
-    rules: string[];
+    /** DIRECT 出站按域名解析用；不指定会解析回 fake-ip 再进 TUN 成环。 */
+    "direct-nameserver": string[];
   };
   tun: {
     enable: true;
@@ -46,6 +54,8 @@ export interface MihomoConfig {
 }
 
 const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}(?:\/\d{1,2})?$/;
+/** 子域名条目前缀：`*.example.com` 表示 example.com 的全部子域名（不含它本身）。 */
+const WILDCARD_PREFIX = "*.";
 /** 合法 DNS 主机名（标签 1-63 字符，字母数字加连字符，不得以连字符开头/结尾）。 */
 const DOMAIN_PATTERN =
   /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
@@ -73,14 +83,32 @@ function parsePort(value: string): number {
 }
 
 /**
- * 解析 allowlist 条目：域名 / IPv4 / CIDR，可带 :port；IPv6 必须用 [] 包裹
- * （如 `[::1]:80`），裸 IPv6 会报错提示补方括号。
+ * 解析 allowlist 条目：域名 / IPv4 / CIDR，可带 :port；域名可加 `*.` 前缀表示
+ * 「它的全部子域名（任意深度，不含它本身）」；IPv6 必须用 [] 包裹（如 `[::1]:80`），
+ * 裸 IPv6 会报错提示补方括号。
  */
 function parseAllowlistEntry(entry: string): AllowlistEntry {
+  if (entry === "*") {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must be followed by a domain, e.g. "*.example.com"`,
+    );
+  }
+  if (entry.startsWith("*") && !entry.startsWith(WILDCARD_PREFIX)) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must occupy the whole leftmost label, e.g. "*.example.com"`,
+    );
+  }
+  const subdomains = entry.startsWith(WILDCARD_PREFIX);
+  const body = subdomains ? entry.slice(WILDCARD_PREFIX.length) : entry;
+  if (body.length === 0) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must be followed by a domain, e.g. "*.example.com"`,
+    );
+  }
   let host: string;
   let port: number | undefined;
-  if (entry.startsWith("[")) {
-    const match = /^\[(.+)\](?::(\d+))?$/.exec(entry);
+  if (body.startsWith("[")) {
+    const match = /^\[(.+)\](?::(\d+))?$/.exec(body);
     if (match?.[1] === undefined) {
       throw new Error(`Invalid allowlist entry "${entry}"`);
     }
@@ -89,18 +117,15 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
     const portPart = match.at(2);
     port = portPart === undefined ? undefined : parsePort(portPart);
   } else {
-    const colon = entry.lastIndexOf(":");
+    const colon = body.lastIndexOf(":");
     if (colon === -1) {
-      if (entry.length === 0) {
-        throw new Error(`Invalid allowlist entry ""`);
-      }
-      host = entry;
+      host = body;
     } else {
-      const portPart = entry.slice(colon + 1);
+      const portPart = body.slice(colon + 1);
       if (!/^\d+$/.test(portPart)) {
         throw new Error(`Invalid allowlist entry "${entry}"`);
       }
-      host = entry.slice(0, colon);
+      host = body.slice(0, colon);
       if (host.length === 0) {
         throw new Error(`Invalid allowlist entry "${entry}"`);
       }
@@ -110,14 +135,24 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
       port = parsePort(portPart);
     }
   }
+  if (host.includes("*")) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" is only allowed as the leftmost label, e.g. "*.example.com"`,
+    );
+  }
   if (isIp(host)) {
+    if (subdomains) {
+      throw new Error(
+        `Invalid allowlist entry "${entry}": "*" applies to domains only, use a CIDR entry for IP ranges`,
+      );
+    }
     if (!IP_CHARS_PATTERN.test(host)) {
       throw new Error(`Invalid allowlist entry "${entry}"`);
     }
   } else if (!DOMAIN_PATTERN.test(host)) {
     throw new Error(`Invalid allowlist entry "${entry}"`);
   }
-  return { host, port };
+  return { host, port, subdomains };
 }
 
 /** IP 条目的 mihomo 规则（IPv6 用 IP-CIDR6；no-resolve 跳过反向解析）。 */
@@ -129,35 +164,38 @@ function ipRule(host: string): string {
 
 interface BuiltRules {
   rules: string[];
-  fakeIpFilter: string[];
-  /** DNS 层规则：allowlist 域名正常解析，未允许域名直接拒绝（解析失败而非 fake-ip 后连接失败）。 */
-  dnsRules: string[];
+  /** 拿 fake IP 的域名：只有它们会进 fakeip 分支，其余域名落到默认解析（拒绝）。 */
+  fakeIpWhitelist: string[];
 }
 
 /**
  * allowlist 条目 → mihomo 规则：
- * - 域名（含 :port 条目里的域名）进 fake-ip-filter，真实解析避免 DIRECT 出站
- *   拿到 fakeip 再进 TUN 形成环（loopback detector 会拒绝）；
+ * - 域名（含 :port 条目里的域名）进 fake-ip-filter（配合 filter-mode: whitelist，
+ *   即「只有这些域名拿 fake IP」）：fake IP 与域名一一对应，连接到达时凭它精确还原
+ *   域名再匹配规则，不依赖嗅探、也不受 DNS TTL 影响；
+ * - 匹配精度两档：裸域名只匹配该域名本身（DOMAIN / 白名单里的裸域名），
+ *   `*.` 前缀匹配它的全部子域名、不含它本身（DOMAIN-WILDCARD / dot-wildcard）；
  * - 无端口条目直接匹配；带端口条目用 AND 组合（域名/IP + DST-PORT）精确放行；
- * - 最后以 MATCH,REJECT 兜底实现 deny-by-default。
- * dns.rules 同步构建：allowlist 域名 DIRECT，其余 MATCH,REJECT——未允许域名
- * 在 DNS 层即被拒绝（curl 报 Could not resolve host），而不是先拿 fake-ip、
- * 到连接层才断（报 TLS decode error，容易误判为网络故障）。
+ * - 最后以 MATCH,REJECT 兜底实现 deny-by-default（裸 IP 连接、绕过 DNS 的客户端）。
+ *
+ * 未进白名单的域名（即未允许域名）不拿 fake IP，直接落到 nameserver，被
+ * rcode://name_error 即时拒绝（客户端报 Could not resolve host）——mihomo 的 fakeip
+ * 分支本身没有按域名拒绝的钩子，收窄白名单是唯一能让拒绝发生在 DNS 层的办法。
  */
 function buildRules(allowlist: readonly string[]): BuiltRules {
   const rules: string[] = [];
-  const fakeIpFilter: string[] = [];
-  const dnsRules: string[] = [];
+  const fakeIpWhitelist: string[] = [];
   for (const entry of allowlist) {
-    const { host, port } = parseAllowlistEntry(entry);
+    const { host, port, subdomains } = parseAllowlistEntry(entry);
     if (!isIp(host)) {
-      fakeIpFilter.push(`+.${host}`);
-      // DNS 层按域名放行（端口无关）；连接层规则保留端口语义
-      dnsRules.push(`DOMAIN-SUFFIX,${host},DIRECT`);
+      // DNS 侧与连接层必须表达同一集合：精确条目用裸域名 / DOMAIN，
+      // 子域名条目用 dot-wildcard（任意深度子域名，不含 apex）/ DOMAIN-WILDCARD
+      fakeIpWhitelist.push(subdomains ? `.${host}` : host);
+      const domainRule = subdomains ? `DOMAIN-WILDCARD,*.${host},DIRECT` : `DOMAIN,${host},DIRECT`;
       if (port === undefined) {
-        rules.push(`DOMAIN-SUFFIX,${host},DIRECT`);
+        rules.push(domainRule);
       } else {
-        rules.push(`AND,(DOMAIN-SUFFIX,${host},DIRECT),(DST-PORT,${port},DIRECT),DIRECT`);
+        rules.push(`AND,(${domainRule}),(DST-PORT,${port},DIRECT),DIRECT`);
       }
     } else if (port === undefined) {
       rules.push(ipRule(host));
@@ -166,24 +204,26 @@ function buildRules(allowlist: readonly string[]): BuiltRules {
     }
   }
   rules.push("MATCH,REJECT");
-  dnsRules.push("MATCH,REJECT");
-  return { rules, fakeIpFilter, dnsRules };
+  return { rules, fakeIpWhitelist };
 }
 
 /**
- * 生成 mihomo（Clash Meta）配置对象：TUN + fakeip + deny-by-default allowlist。
+ * 生成 mihomo（Clash Meta）配置对象：TUN + 白名单 fakeip + deny-by-default allowlist。
  *
  * - auto-detect-interface 让 mihomo 出站绑定 slirp4netns 的 tap0，否则它自己的
  *   DNS 查询会被 auto_route 送回 TUN 形成环；
  * - TUN mtu 与 slirp4netns `--mtu` 共用 TUN_MTU，避免依赖各自默认值；
- * - allowlist 域名走 fake-ip-filter 真实解析（见 buildRules 注释）。
+ * - fakeip 只服务 allowlist 域名（filter-mode: whitelist，见 buildRules 注释）：
+ *   域名归属因此精确且不随 TTL 失效；
+ * - direct-nameserver 必须指向真实 DNS：连接由 fake IP 还原成域名后，DIRECT 出站要
+ *   按域名重新解析，不指定就会解析回 fake-ip 再进 TUN 成环。
  */
 export function generateMihomoConfig(options: MihomoConfigOptions): MihomoConfig {
   const { allowlist, dnsServers } = options;
   if (dnsServers.length === 0) {
     throw new Error("At least one DNS server is required");
   }
-  const { rules, fakeIpFilter, dnsRules } = buildRules(allowlist);
+  const { rules, fakeIpWhitelist } = buildRules(allowlist);
   return {
     "mixed-port": 0,
     mode: "rule",
@@ -199,10 +239,11 @@ export function generateMihomoConfig(options: MihomoConfigOptions): MihomoConfig
       ipv6: false,
       "enhanced-mode": "fake-ip",
       "fake-ip-range": FAKEIP_RANGE,
-      nameserver: [...dnsServers],
+      "fake-ip-filter-mode": "whitelist",
+      ...(fakeIpWhitelist.length > 0 && { "fake-ip-filter": fakeIpWhitelist }),
+      nameserver: [REJECT_NAMESERVER],
       "default-nameserver": [...dnsServers],
-      ...(fakeIpFilter.length > 0 && { "fake-ip-filter": fakeIpFilter }),
-      rules: dnsRules,
+      "direct-nameserver": [...dnsServers],
     },
     tun: {
       enable: true,