@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/sandbox/backends/bwrap.ts

@@ -0,0 +1,251 @@
+/*
+ * Linux bwrap 后端。
+ * 由 bwrap 提供 mount / PID / network namespace；Node permission model 作为第二层。
+ */
+
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, join, relative, resolve, sep } from "node:path"
+
+import type {
+    AgentLaunchInput,
+    LaunchSpec,
+    PluginLaunchInput,
+    SandboxBackend,
+    SandboxBackendStatus,
+} from "../types.ts"
+
+const SYSTEM_DIRS = ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/lib32"]
+
+/** 沙箱内挂载 Node 运行时的目录 */
+export const NODE_ROOT = "/opt/wellspring"
+
+function existingSystemDirs(): string[] {
+    return SYSTEM_DIRS.filter((dir) => existsSync(dir))
+}
+
+export interface NodeRuntimeLayout {
+    /** 可整体挂载的 Node 前缀（含 bin/npm 与 lib/node_modules）；只有裸二进制时为 null */
+    readonly prefix: string | null
+    /** 沙箱内的 node 路径 */
+    readonly nodePath: string
+    /** PATH 里的目录 */
+    readonly pathEntry: string
+}
+
+/**
+ * 找到当前 node 的安装前缀。
+ *
+ * 只 bind 单个 node 二进制会丢掉同目录的 npm/npx（npm 在 lib/node_modules/npm 里），
+ * 所以优先把整个前缀挂到 /opt/wellspring；找不到 npm 的发行版才退回裸二进制。
+ */
+export function resolveNodeRuntime(
+    execPath: string = process.execPath,
+    exists: (path: string) => boolean = existsSync,
+): NodeRuntimeLayout {
+    const prefix = resolve(dirname(execPath), "..")
+    const hasNpm =
+        exists(join(prefix, "bin", "npm")) ||
+        exists(join(prefix, "lib", "node_modules", "npm")) ||
+        exists(join(prefix, "share", "nodejs", "npm"))
+    if (hasNpm) {
+        return {
+            prefix,
+            nodePath: `${NODE_ROOT}/bin/node`,
+            pathEntry: `${NODE_ROOT}/bin`,
+        }
+    }
+    return {
+        prefix: null,
+        nodePath: `${NODE_ROOT}/node`,
+        pathEntry: NODE_ROOT,
+    }
+}
+
+function nodeRuntimeMount(runtime: NodeRuntimeLayout, execPath: string): string[] {
+    if (runtime.prefix !== null) {
+        return ["--dir", NODE_ROOT, "--ro-bind", runtime.prefix, NODE_ROOT]
+    }
+    return ["--dir", NODE_ROOT, "--ro-bind", execPath, `${NODE_ROOT}/node`]
+}
+
+function insideWorkspace(workspaceDir: string, cwd: string): string {
+    const root = resolve(workspaceDir)
+    const target = resolve(cwd)
+    if (target !== root && !target.startsWith(`${root}${sep}`)) {
+        throw new Error(`cwd 不在 workspace 内：${cwd}`)
+    }
+    const rel = relative(root, target)
+    return rel === "" ? "/workspace" : `/workspace/${rel.split(sep).join("/")}`
+}
+
+/** 纯函数，方便单测 */
+export function buildBwrapLaunch(input: AgentLaunchInput): LaunchSpec {
+    const args: string[] = [
+        "--unshare-all",
+        "--die-with-parent",
+        "--new-session",
+        "--clearenv",
+        "--cap-drop",
+        "ALL",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+        "--tmpfs",
+        "/tmp",
+    ]
+
+    if (input.network === true) {
+        args.push("--share-net")
+    }
+    for (const dir of existingSystemDirs()) {
+        args.push("--ro-bind-try", dir, dir)
+    }
+    // DNS、CA 证书与用户解析
+    args.push("--ro-bind-try", "/etc", "/etc")
+    // systemd-resolved 的 resolv.conf 指向 /run；先建目标目录再尝试绑定
+    if (existsSync("/run/systemd/resolve")) {
+        args.push("--dir", "/run", "--dir", "/run/systemd", "--dir", "/run/systemd/resolve")
+        args.push("--ro-bind-try", "/run/systemd/resolve", "/run/systemd/resolve")
+    }
+    const nodeRuntime = resolveNodeRuntime()
+    args.push(...nodeRuntimeMount(nodeRuntime, process.execPath))
+    const workspaceBind = input.access === "workspace-write" ? "--bind" : "--ro-bind"
+    args.push(workspaceBind, resolve(input.workspaceDir), "/workspace")
+    args.push("--bind", resolve(input.scratchDir), "/scratch")
+    args.push("--chdir", insideWorkspace(input.workspaceDir, input.cwd))
+
+    const env: Record<string, string> = { ...input.env }
+    env["PATH"] = `${nodeRuntime.pathEntry}:${env["PATH"] ?? "/usr/bin:/bin"}`
+    /*
+     * 不再限制 RLIMIT_AS（虚拟地址空间会直接打死 V8 / JVM / Go）。
+     * 物理内存由 SandboxManager 挂 cgroup v2 memory.max；这里只留 V8 堆上限，
+     * 且对所有命令生效，npx / npm 派生的 node 子进程也能继承。
+     */
+    env["NODE_OPTIONS"] =
+        `${env["NODE_OPTIONS"] ?? ""} --max-old-space-size=${input.limits.memoryMB}`.trim()
+    for (const [key, value] of Object.entries(env)) {
+        args.push("--setenv", key, value)
+    }
+
+    args.push("--")
+
+    // prlimit 自身在 /usr/bin；只留文件描述符与进程数上限，超时交给 supervisor 的 wall timeout
+    const prlimitArgs = ["--nofile=256", `--nproc=${input.limits.pids}`]
+    args.push("/usr/bin/prlimit", ...prlimitArgs, "--", input.command, ...input.argv)
+
+    return {
+        command: "bwrap",
+        args,
+        cwd: resolve(input.workspaceDir),
+        env: { ...input.env },
+    }
+}
+
+/** 纯函数：插件 profile 的 bwrap launch spec */
+export function buildBwrapPluginLaunch(input: PluginLaunchInput): LaunchSpec {
+    const args: string[] = [
+        "--unshare-all",
+        "--die-with-parent",
+        "--new-session",
+        "--clearenv",
+        "--cap-drop",
+        "ALL",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+        "--tmpfs",
+        "/tmp",
+    ]
+    for (const dir of existingSystemDirs()) {
+        args.push("--ro-bind-try", dir, dir)
+    }
+    const nodeRuntime = resolveNodeRuntime()
+    args.push(...nodeRuntimeMount(nodeRuntime, process.execPath))
+    args.push("--ro-bind", resolve(input.pluginDir), "/plugin")
+    args.push("--ro-bind", resolve(input.hostSdkDir), "/host")
+    args.push("--chdir", "/plugin")
+
+    const env: Record<string, string> = { ...input.env }
+    env["PATH"] = `${nodeRuntime.pathEntry}:${env["PATH"] ?? "/usr/bin:/bin"}`
+    env["NODE_OPTIONS"] =
+        `${env["NODE_OPTIONS"] ?? ""} --max-old-space-size=${input.limits.memoryMB}`.trim()
+    for (const [key, value] of Object.entries(env)) {
+        args.push("--setenv", key, value)
+    }
+    args.push("--")
+    args.push(
+        "/usr/bin/prlimit",
+        "--nofile=256",
+        `--nproc=${input.limits.pids}`,
+        "--",
+        nodeRuntime.nodePath,
+        "--permission",
+        "--allow-fs-read=/plugin",
+        "--allow-fs-read=/host",
+        "/host/src/sandbox/plugin-host.ts",
+    )
+
+    return {
+        command: "bwrap",
+        args,
+        cwd: resolve(input.pluginDir),
+        env: { ...input.env },
+    }
+}
+
+export class BwrapBackend implements SandboxBackend {
+    readonly name = "bwrap"
+
+    async probe(): Promise<SandboxBackendStatus> {
+        if (!existsSync("/usr/bin/bwrap")) {
+            return {
+                available: false,
+                backend: this.name,
+                reason: "找不到 bwrap",
+                version: null,
+            }
+        }
+        const result = spawnSync(
+            "bwrap",
+            [
+                "--unshare-all",
+                "--die-with-parent",
+                "--ro-bind",
+                "/",
+                "/",
+                "--dev",
+                "/dev",
+                "--proc",
+                "/proc",
+                "--",
+                "/bin/true",
+            ],
+            { timeout: 3_000, encoding: "utf8" },
+        )
+        if (result.status !== 0) {
+            return {
+                available: false,
+                backend: this.name,
+                reason: (result.stderr ?? "").trim() || "bwrap 无法创建 namespace",
+                version: null,
+            }
+        }
+        return {
+            available: true,
+            backend: this.name,
+            reason: null,
+            version: null,
+        }
+    }
+
+    buildAgentLaunch(input: AgentLaunchInput): LaunchSpec {
+        return buildBwrapLaunch(input)
+    }
+
+    buildPluginLaunch(input: PluginLaunchInput): LaunchSpec {
+        return buildBwrapPluginLaunch(input)
+    }
+}

package/src/sandbox/backends/direct.ts

@@ -0,0 +1,43 @@
+/*
+ * 无隔离 fallback：仅用于 best-effort / 测试。
+ * 不提供 fs、网络、进程隔离；严格模式禁止使用。
+ */
+
+import type {
+    AgentLaunchInput,
+    LaunchSpec,
+    PluginLaunchInput,
+    SandboxBackend,
+    SandboxBackendStatus,
+} from "../types.ts"
+
+export class DirectBackend implements SandboxBackend {
+    readonly name = "direct"
+
+    async probe(): Promise<SandboxBackendStatus> {
+        return {
+            available: true,
+            backend: this.name,
+            reason: null,
+            version: null,
+        }
+    }
+
+    buildAgentLaunch(input: AgentLaunchInput): LaunchSpec {
+        return {
+            command: input.command,
+            args: [...input.argv],
+            cwd: input.cwd,
+            env: input.env,
+        }
+    }
+
+    buildPluginLaunch(input: PluginLaunchInput): LaunchSpec {
+        return {
+            command: process.execPath,
+            args: [input.runnerPath],
+            cwd: input.pluginDir,
+            env: input.env,
+        }
+    }
+}

package/src/sandbox/bridge-state.ts

@@ -0,0 +1,29 @@
+/*
+ * sandbox child 内的宿主 bridge。
+ * 由 plugin-host runner 安装；宿主进程里为 null，走本地实现。
+ */
+
+import type { Host } from "../api/host/host.ts"
+
+export type BridgeLogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"
+
+export type BridgeOutputKind = "info" | "warn" | "error" | "print"
+
+export interface HostBridge {
+    /** 子进程 → 宿主请求（fs、subscribe、getHost snapshot 外的命令等） */
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>
+    /** 单向事件（log/output/event publish） */
+    notify(method: string, params: unknown): void
+    getHostSnapshot(): Host
+    shutdown(): void
+}
+
+let bridge: HostBridge | null = null
+
+export function setHostBridge(value: HostBridge | null): void {
+    bridge = value
+}
+
+export function getHostBridge(): HostBridge | null {
+    return bridge
+}

package/src/sandbox/index.ts

@@ -0,0 +1,5 @@
+export * from "./backends/bwrap.ts"
+export * from "./backends/direct.ts"
+export * from "./manager.ts"
+export * from "./supervisor.ts"
+export * from "./types.ts"