@xyit/wellspring 1.1.1 → 1.2.0

package/src/sandbox/backends/node-permission.ts

@@ -0,0 +1,62 @@
+/*
+ * 非 Linux 平台的插件 sandbox：Node permission model。
+ *
+ * Windows / macOS 没有 bwrap，无法提供 mount / PID / network namespace；
+ * 这里用 Node 自带的 --permission 限制插件进程的文件读写，至少不让插件直接
+ * 读写宿主任意文件。它不隔离网络与进程，所以只用于插件，不用于任意 Agent 命令。
+ */
+
+import type {
+    AgentLaunchInput,
+    LaunchSpec,
+    PluginLaunchInput,
+    SandboxBackend,
+    SandboxBackendStatus,
+} from "../types.ts"
+
+const BACKEND_NAME = "node-permission"
+
+function permissionFlags(paths: readonly string[], flag: string): string[] {
+    return [...new Set(paths)].map((path) => `${flag}=${path}`)
+}
+
+/** 纯函数：插件 launch spec，方便单测 */
+export function buildNodePermissionPluginLaunch(input: PluginLaunchInput): LaunchSpec {
+    const read = [input.pluginDir, input.hostSdkDir, input.pluginDataDir]
+    const write = [input.pluginDataDir]
+    return {
+        command: process.execPath,
+        args: [
+            "--permission",
+            ...permissionFlags(read, "--allow-fs-read"),
+            ...permissionFlags(write, "--allow-fs-write"),
+            input.runnerPath,
+        ],
+        cwd: input.pluginDir,
+        env: input.env,
+    }
+}
+
+export class NodePermissionBackend implements SandboxBackend {
+    readonly name = BACKEND_NAME
+
+    async probe(): Promise<SandboxBackendStatus> {
+        const supported = process.allowedNodeEnvironmentFlags.has("--permission")
+        return {
+            available: supported,
+            backend: this.name,
+            reason: supported
+                ? "Node permission model（无网络/进程隔离）"
+                : "当前 Node 不支持 --permission",
+            version: process.version,
+        }
+    }
+
+    buildAgentLaunch(_input: AgentLaunchInput): LaunchSpec {
+        throw new Error("node-permission 后端只用于插件，不支持任意 Agent 命令")
+    }
+
+    buildPluginLaunch(input: PluginLaunchInput): LaunchSpec {
+        return buildNodePermissionPluginLaunch(input)
+    }
+}

package/src/sandbox/plugin-client.ts

@@ -8,7 +8,7 @@ import { createServer as createHttpsServer } from "node:https"
 import { WebSocketServer, type WebSocket } from "ws"
 import { randomUUID } from "node:crypto"
 import { cp, mkdir, rm, stat } from "node:fs/promises"
-import { basename, dirname, join, relative, resolve } from "node:path"
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
 
 import type { Logger } from "pino"
 
@@ -458,14 +458,47 @@ export class PluginSandboxClient {
         await this.#prepareHostSdk()
 
         const pluginEntryRel = relative(this.#options.pluginDir, this.#options.pluginEntry)
-        const env: Record<string, string> = {
-            PATH: "/usr/bin:/bin",
-            LANG: "C.UTF-8",
-            LC_ALL: "C.UTF-8",
-            TERM: "dumb",
-            HOME: "/tmp",
-            TMPDIR: "/tmp",
-        }
+        const pluginTempDir = join(this.#pluginDataDir, "tmp")
+        await mkdir(pluginTempDir, { recursive: true })
+        const env: Record<string, string> = isBwrap
+            ? {
+                  PATH: "/usr/bin:/bin",
+                  LANG: "C.UTF-8",
+                  LC_ALL: "C.UTF-8",
+                  TERM: "dumb",
+                  HOME: "/tmp",
+                  TMPDIR: "/tmp",
+              }
+            : {
+                  /*
+                   * Windows / macOS 的插件 sandbox（Node permission）使用宿主路径；
+                   * 只透传系统定位变量，不把 API Key 等敏感环境变量带进插件进程。
+                   */
+                  PATH:
+                      process.env["PATH"] ?? (process.platform === "win32" ? "" : "/usr/bin:/bin"),
+                  TERM: "dumb",
+                  HOME: this.#pluginDataDir,
+                  TMP: pluginTempDir,
+                  TEMP: pluginTempDir,
+                  TMPDIR: pluginTempDir,
+                  ...(process.platform === "win32"
+                      ? {
+                            USERPROFILE: process.env["USERPROFILE"] ?? this.#pluginDataDir,
+                            APPDATA: process.env["APPDATA"] ?? this.#pluginDataDir,
+                            LOCALAPPDATA: process.env["LOCALAPPDATA"] ?? this.#pluginDataDir,
+                            SystemRoot: process.env["SystemRoot"] ?? "C:\\Windows",
+                            SystemDrive: process.env["SystemDrive"] ?? "C:",
+                            ComSpec: process.env["ComSpec"] ?? "C:\\Windows\\System32\\cmd.exe",
+                            PATHEXT: process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD",
+                            NUMBER_OF_PROCESSORS: process.env["NUMBER_OF_PROCESSORS"] ?? "1",
+                            PROCESSOR_ARCHITECTURE:
+                                process.env["PROCESSOR_ARCHITECTURE"] ?? "AMD64",
+                        }
+                      : {
+                            LANG: "C.UTF-8",
+                            LC_ALL: "C.UTF-8",
+                        }),
+              }
         const input: PluginLaunchInput = {
             pluginDir: this.#options.pluginDir,
             pluginEntryRel,
@@ -1528,6 +1561,13 @@ export class PluginSandboxClient {
                         error instanceof Error ? error.message : String(error),
                     )
                 }
+            } else if (request.method === "host.fileRoots.open") {
+                this.#requireHostApi("fileRoots")
+                const api = await this.#resolveFileRoot(params["root"])
+                result = { root: api.root }
+            } else if (request.method.startsWith("host.fileRoots.")) {
+                this.#requireHostApi("fileRoots")
+                result = await this.#handleFileRoot(request.method, params)
             } else if (request.method.startsWith("host.fs.")) {
                 this.#requireHostApi("fs")
                 result = await this.#handleFs(request.method, params, false)
@@ -1639,7 +1679,6 @@ export class PluginSandboxClient {
         const api: HostFileApi = workspace
             ? createPluginFileApi(process.cwd())
             : createPluginFileApi(this.#pluginDataDir)
-        const path = String(params["path"] ?? "")
         const action = method.replace(/^host\.(fs|workspaceFs)\./, "")
         if (
             workspace &&
@@ -1653,6 +1692,36 @@ export class PluginSandboxClient {
                 throw new PluginSandboxError("当前 Agent 权限是 read-only，不能修改工作区文件")
             }
         }
+        return await this.#dispatchFileApi(api, action, method, params)
+    }
+
+    /** 校验绝对目录并创建以它为根的文件 API */
+    async #resolveFileRoot(rootValue: unknown): Promise<HostFileApi> {
+        const root = typeof rootValue === "string" ? rootValue.trim() : ""
+        if (root === "" || root.includes("\0") || !isAbsolute(root)) {
+            throw new PluginSandboxError("fileRoots.open 需要绝对目录路径")
+        }
+        const absolute = resolve(root)
+        const info = await stat(absolute).catch(() => null)
+        if (info === null || !info.isDirectory()) {
+            throw new PluginSandboxError(`目录不存在或不是文件夹：${root}`)
+        }
+        return createPluginFileApi(absolute)
+    }
+
+    async #handleFileRoot(method: string, params: Record<string, unknown>): Promise<unknown> {
+        const api = await this.#resolveFileRoot(params["root"])
+        const action = method.replace(/^host\.fileRoots\./, "")
+        return await this.#dispatchFileApi(api, action, method, params)
+    }
+
+    async #dispatchFileApi(
+        api: HostFileApi,
+        action: string,
+        method: string,
+        params: Record<string, unknown>,
+    ): Promise<unknown> {
+        const path = String(params["path"] ?? "")
         switch (action) {
             case "readText":
                 return { text: await api.readText(path) }

package/src/sandbox/plugin-host.ts

@@ -607,11 +607,11 @@ const output: HostOutput = {
     print: (text = "") => bridgeNotify("host.output", { kind: "print", text }),
 }
 
-function createFileApi(scope: "fs" | "workspaceFs"): HostFileApi {
-    const call = (method: string, params: Record<string, unknown> = {}) =>
-        bridgeRequest(`host.${scope}.${method}`, params)
+type FileApiCall = (method: string, params?: Record<string, unknown>) => Promise<unknown>
+
+function fileApi(root: string, call: FileApiCall): HostFileApi {
     return {
-        root: scope,
+        root,
         async readText(path) {
             const result = (await call("readText", { path })) as { text: string | null }
             return result.text
@@ -660,6 +660,16 @@ function createFileApi(scope: "fs" | "workspaceFs"): HostFileApi {
     }
 }
 
+function createFileApi(scope: "fs" | "workspaceFs"): HostFileApi {
+    return fileApi(scope, (method, params = {}) => bridgeRequest(`host.${scope}.${method}`, params))
+}
+
+function createRootedFileApi(root: string): HostFileApi {
+    return fileApi(root, (method, params = {}) =>
+        bridgeRequest(`host.fileRoots.${method}`, { root, ...params }),
+    )
+}
+
 function patchConsole(): void {
     const methods: Array<[string, string]> = [
         ["log", "info"],
@@ -785,6 +795,14 @@ async function bootstrap(params: ConfigurePayload): Promise<{
         pluginConfig: params.pluginConfig,
         fs: createFileApi("fs"),
         workspaceFs: createFileApi("workspaceFs"),
+        fileRoots: {
+            async open(root: string): Promise<HostFileApi> {
+                const result = (await bridgeRequest("host.fileRoots.open", { root })) as {
+                    root: string
+                }
+                return createRootedFileApi(result.root)
+            },
+        },
         registerCommand: (command: PluginCommand): void => {
             commands.push(command)
         },