@downcity/agent 1.1.91 → 1.1.96

package/bin/sandbox/SandboxPreflight.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SandboxPreflight：本机 shell sandbox 依赖预检。
+ *
+ * 关键点（中文）
+ * - shell 命令必须进入 sandbox；这里提前检查 backend 依赖，避免启动后首次 shell 执行才失败。
+ * - Linux backend 基于 bubblewrap，本质使用 Linux namespaces / bind mount 等内核能力。
+ * - 本模块只诊断并给出修复建议，不自动安装软件，也不修改宿主机 sysctl。
+ */
+import type { SandboxBackend } from "../sandbox/types/SandboxRuntime.js";
+/**
+ * sandbox 预检失败原因。
+ */
+export type SandboxPreflightIssueCode = "unsupported-platform" | "missing-command" | "userns-disabled";
+/**
+ * 单条 sandbox 预检失败。
+ */
+export interface SandboxPreflightIssue {
+    /**
+     * 机器可读的失败原因。
+     */
+    code: SandboxPreflightIssueCode;
+    /**
+     * 人类可读的失败说明。
+     */
+    message: string;
+    /**
+     * 可复制的修复建议列表。
+     */
+    fixes: string[];
+}
+/**
+ * sandbox 预检结果。
+ */
+export interface SandboxPreflightResult {
+    /**
+     * 当前平台是否满足 shell sandbox 启动要求。
+     */
+    ok: boolean;
+    /**
+     * 当前宿主平台。
+     */
+    platform: NodeJS.Platform;
+    /**
+     * 当前平台对应的 sandbox backend。
+     */
+    backend?: SandboxBackend;
+    /**
+     * 失败原因集合。
+     */
+    issues: SandboxPreflightIssue[];
+}
+/**
+ * sandbox 预检宿主探测依赖。
+ */
+export interface ShellSandboxPreflightProbe {
+    /**
+     * 判断命令是否存在于 PATH 中。
+     */
+    commandExists(command: string): Promise<boolean>;
+    /**
+     * 读取 `/proc` 下整数配置。
+     */
+    readProcInt(filePath: string): Promise<number | null>;
+}
+/**
+ * 检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export declare function checkShellSandboxPreflight(): Promise<SandboxPreflightResult>;
+/**
+ * 使用注入探针检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export declare function checkShellSandboxPreflightWithProbe(probe: ShellSandboxPreflightProbe): Promise<SandboxPreflightResult>;
+//# sourceMappingURL=SandboxPreflight.d.ts.map

package/bin/sandbox/SandboxPreflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxPreflight.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxPreflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,sBAAsB,GACtB,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,yBAAyB,CAAC;IAEhC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IAEZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAyCD;;GAEG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAKlF;AAED;;GAEG;AACH,wBAAsB,mCAAmC,CACvD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAoEjC"}

package/bin/sandbox/SandboxPreflight.js

@@ -0,0 +1,122 @@
+/**
+ * SandboxPreflight：本机 shell sandbox 依赖预检。
+ *
+ * 关键点（中文）
+ * - shell 命令必须进入 sandbox；这里提前检查 backend 依赖，避免启动后首次 shell 执行才失败。
+ * - Linux backend 基于 bubblewrap，本质使用 Linux namespaces / bind mount 等内核能力。
+ * - 本模块只诊断并给出修复建议，不自动安装软件，也不修改宿主机 sysctl。
+ */
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { delimiter } from "node:path";
+async function commandExists(command) {
+    const pathValue = String(process.env.PATH || "").trim();
+    const dirs = pathValue ? pathValue.split(delimiter) : [];
+    for (const dir of dirs) {
+        const candidate = path.join(dir, command);
+        try {
+            await access(candidate);
+            return true;
+        }
+        catch {
+            // continue
+        }
+    }
+    return false;
+}
+async function readProcInt(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const value = Number.parseInt(raw.trim(), 10);
+        return Number.isFinite(value) && !Number.isNaN(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function isLinuxUserNamespaceEnabled(probe) {
+    const unprivilegedUsernsClone = await probe.readProcInt("/proc/sys/kernel/unprivileged_userns_clone");
+    if (unprivilegedUsernsClone === 0)
+        return false;
+    const maxUserNamespaces = await probe.readProcInt("/proc/sys/user/max_user_namespaces");
+    if (maxUserNamespaces === 0)
+        return false;
+    return true;
+}
+/**
+ * 检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflight() {
+    return await checkShellSandboxPreflightWithProbe({
+        commandExists,
+        readProcInt,
+    });
+}
+/**
+ * 使用注入探针检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflightWithProbe(probe) {
+    const platform = process.platform;
+    const issues = [];
+    if (platform === "darwin") {
+        if (!(await probe.commandExists("sandbox-exec"))) {
+            issues.push({
+                code: "missing-command",
+                message: "macOS shell sandbox requires sandbox-exec, but it was not found.",
+                fixes: [
+                    "Use a macOS system that includes /usr/bin/sandbox-exec.",
+                ],
+            });
+        }
+        return {
+            ok: issues.length === 0,
+            platform,
+            backend: "macos-seatbelt",
+            issues,
+        };
+    }
+    if (platform === "linux") {
+        if (!(await probe.commandExists("bwrap"))) {
+            issues.push({
+                code: "missing-command",
+                message: "Linux shell sandbox requires bubblewrap (bwrap), but it was not found.",
+                fixes: [
+                    "Debian / Ubuntu: sudo apt install bubblewrap",
+                    "Fedora: sudo dnf install bubblewrap",
+                    "Arch: sudo pacman -S bubblewrap",
+                ],
+            });
+        }
+        if (!(await isLinuxUserNamespaceEnabled(probe))) {
+            issues.push({
+                code: "userns-disabled",
+                message: "Linux user namespaces are disabled, so bubblewrap cannot create the sandbox.",
+                fixes: [
+                    "Check: cat /proc/sys/kernel/unprivileged_userns_clone",
+                    "Check: cat /proc/sys/user/max_user_namespaces",
+                    "Debian / Ubuntu: sudo sysctl kernel.unprivileged_userns_clone=1",
+                ],
+            });
+        }
+        return {
+            ok: issues.length === 0,
+            platform,
+            backend: "linux-bubblewrap",
+            issues,
+        };
+    }
+    return {
+        ok: false,
+        platform,
+        issues: [
+            {
+                code: "unsupported-platform",
+                message: `Shell sandbox is not supported on this platform: ${platform}.`,
+                fixes: [
+                    "Use macOS or Linux for local shell execution.",
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=SandboxPreflight.js.map

package/bin/sandbox/SandboxPreflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxPreflight.js","sourceRoot":"","sources":["../../src/sandbox/SandboxPreflight.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.91",
+  "version": "1.1.96",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -29,7 +29,7 @@
     "node-cron": "^4.2.1",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@downcity/type": "0.1.26"
+    "@downcity/type": "0.1.30"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/scripts/shell-sandbox-preflight.test.mjs

@@ -0,0 +1,88 @@
+/**
+ * @file 验证 shell sandbox 启动前依赖诊断。
+ *
+ * 关键点（中文）
+ * - 测试编译后的 bin 输出，避免测试文件进入 package 源码导出面。
+ * - 通过注入探针模拟 Linux 依赖状态，不要求当前测试机安装 bwrap。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  checkShellSandboxPreflightWithProbe,
+} from "../bin/sandbox/SandboxPreflight.js";
+
+async function withPlatform(platform, callback) {
+  const previous = Object.getOwnPropertyDescriptor(process, "platform");
+  Object.defineProperty(process, "platform", {
+    configurable: true,
+    value: platform,
+  });
+  try {
+    return await callback();
+  } finally {
+    if (previous) {
+      Object.defineProperty(process, "platform", previous);
+    }
+  }
+}
+
+function createProbe(params) {
+  return {
+    commandExists: async (command) => params.commands?.has(command) === true,
+    readProcInt: async (filePath) => params.proc?.get(filePath) ?? null,
+  };
+}
+
+test("Linux shell sandbox preflight reports missing bwrap and disabled userns", async () => {
+  await withPlatform("linux", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(),
+      proc: new Map([
+        ["/proc/sys/kernel/unprivileged_userns_clone", 0],
+        ["/proc/sys/user/max_user_namespaces", 0],
+      ]),
+    }));
+
+    assert.equal(result.ok, false);
+    assert.equal(result.backend, "linux-bubblewrap");
+    assert.deepEqual(
+      result.issues.map((issue) => issue.code),
+      ["missing-command", "userns-disabled"],
+    );
+    assert.match(result.issues[0].message, /bubblewrap/);
+    assert.match(result.issues[1].message, /user namespaces/);
+  });
+});
+
+test("Linux shell sandbox preflight accepts bwrap with enabled userns", async () => {
+  await withPlatform("linux", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(["bwrap"]),
+      proc: new Map([
+        ["/proc/sys/kernel/unprivileged_userns_clone", 1],
+        ["/proc/sys/user/max_user_namespaces", 1024],
+      ]),
+    }));
+
+    assert.equal(result.ok, true);
+    assert.equal(result.backend, "linux-bubblewrap");
+    assert.deepEqual(result.issues, []);
+  });
+});
+
+test("Unsupported platforms fail shell sandbox preflight", async () => {
+  await withPlatform("win32", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(),
+      proc: new Map(),
+    }));
+
+    assert.equal(result.ok, false);
+    assert.deepEqual(
+      result.issues.map((issue) => issue.code),
+      ["unsupported-platform"],
+    );
+  });
+});

package/src/sandbox/SandboxPreflight.ts

@@ -0,0 +1,205 @@
+/**
+ * SandboxPreflight：本机 shell sandbox 依赖预检。
+ *
+ * 关键点（中文）
+ * - shell 命令必须进入 sandbox；这里提前检查 backend 依赖，避免启动后首次 shell 执行才失败。
+ * - Linux backend 基于 bubblewrap，本质使用 Linux namespaces / bind mount 等内核能力。
+ * - 本模块只诊断并给出修复建议，不自动安装软件，也不修改宿主机 sysctl。
+ */
+
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { delimiter } from "node:path";
+import type { SandboxBackend } from "@/sandbox/types/SandboxRuntime.js";
+
+/**
+ * sandbox 预检失败原因。
+ */
+export type SandboxPreflightIssueCode =
+  | "unsupported-platform"
+  | "missing-command"
+  | "userns-disabled";
+
+/**
+ * 单条 sandbox 预检失败。
+ */
+export interface SandboxPreflightIssue {
+  /**
+   * 机器可读的失败原因。
+   */
+  code: SandboxPreflightIssueCode;
+
+  /**
+   * 人类可读的失败说明。
+   */
+  message: string;
+
+  /**
+   * 可复制的修复建议列表。
+   */
+  fixes: string[];
+}
+
+/**
+ * sandbox 预检结果。
+ */
+export interface SandboxPreflightResult {
+  /**
+   * 当前平台是否满足 shell sandbox 启动要求。
+   */
+  ok: boolean;
+
+  /**
+   * 当前宿主平台。
+   */
+  platform: NodeJS.Platform;
+
+  /**
+   * 当前平台对应的 sandbox backend。
+   */
+  backend?: SandboxBackend;
+
+  /**
+   * 失败原因集合。
+   */
+  issues: SandboxPreflightIssue[];
+}
+
+/**
+ * sandbox 预检宿主探测依赖。
+ */
+export interface ShellSandboxPreflightProbe {
+  /**
+   * 判断命令是否存在于 PATH 中。
+   */
+  commandExists(command: string): Promise<boolean>;
+
+  /**
+   * 读取 `/proc` 下整数配置。
+   */
+  readProcInt(filePath: string): Promise<number | null>;
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const pathValue = String(process.env.PATH || "").trim();
+  const dirs = pathValue ? pathValue.split(delimiter) : [];
+  for (const dir of dirs) {
+    const candidate = path.join(dir, command);
+    try {
+      await access(candidate);
+      return true;
+    } catch {
+      // continue
+    }
+  }
+  return false;
+}
+
+async function readProcInt(filePath: string): Promise<number | null> {
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    const value = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(value) && !Number.isNaN(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function isLinuxUserNamespaceEnabled(
+  probe: ShellSandboxPreflightProbe,
+): Promise<boolean> {
+  const unprivilegedUsernsClone = await probe.readProcInt(
+    "/proc/sys/kernel/unprivileged_userns_clone",
+  );
+  if (unprivilegedUsernsClone === 0) return false;
+
+  const maxUserNamespaces = await probe.readProcInt("/proc/sys/user/max_user_namespaces");
+  if (maxUserNamespaces === 0) return false;
+
+  return true;
+}
+
+/**
+ * 检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflight(): Promise<SandboxPreflightResult> {
+  return await checkShellSandboxPreflightWithProbe({
+    commandExists,
+    readProcInt,
+  });
+}
+
+/**
+ * 使用注入探针检查当前宿主是否满足 shell sandbox 运行要求。
+ */
+export async function checkShellSandboxPreflightWithProbe(
+  probe: ShellSandboxPreflightProbe,
+): Promise<SandboxPreflightResult> {
+  const platform = process.platform;
+  const issues: SandboxPreflightIssue[] = [];
+
+  if (platform === "darwin") {
+    if (!(await probe.commandExists("sandbox-exec"))) {
+      issues.push({
+        code: "missing-command",
+        message: "macOS shell sandbox requires sandbox-exec, but it was not found.",
+        fixes: [
+          "Use a macOS system that includes /usr/bin/sandbox-exec.",
+        ],
+      });
+    }
+    return {
+      ok: issues.length === 0,
+      platform,
+      backend: "macos-seatbelt",
+      issues,
+    };
+  }
+
+  if (platform === "linux") {
+    if (!(await probe.commandExists("bwrap"))) {
+      issues.push({
+        code: "missing-command",
+        message: "Linux shell sandbox requires bubblewrap (bwrap), but it was not found.",
+        fixes: [
+          "Debian / Ubuntu: sudo apt install bubblewrap",
+          "Fedora: sudo dnf install bubblewrap",
+          "Arch: sudo pacman -S bubblewrap",
+        ],
+      });
+    }
+
+    if (!(await isLinuxUserNamespaceEnabled(probe))) {
+      issues.push({
+        code: "userns-disabled",
+        message: "Linux user namespaces are disabled, so bubblewrap cannot create the sandbox.",
+        fixes: [
+          "Check: cat /proc/sys/kernel/unprivileged_userns_clone",
+          "Check: cat /proc/sys/user/max_user_namespaces",
+          "Debian / Ubuntu: sudo sysctl kernel.unprivileged_userns_clone=1",
+        ],
+      });
+    }
+
+    return {
+      ok: issues.length === 0,
+      platform,
+      backend: "linux-bubblewrap",
+      issues,
+    };
+  }
+
+  return {
+    ok: false,
+    platform,
+    issues: [
+      {
+        code: "unsupported-platform",
+        message: `Shell sandbox is not supported on this platform: ${platform}.`,
+        fixes: [
+          "Use macOS or Linux for local shell execution.",
+        ],
+      },
+    ],
+  };
+}