@xyit/wellspring 0.0.0-stage → 1.0.0

package/src/plugin/scaffold.ts

@@ -0,0 +1,152 @@
+/*
+ * 插件脚手架：生成可加载的最小插件目录。
+ */
+
+import { join, resolve } from "node:path"
+
+import {
+    ensureDir,
+    removePath,
+    statIfExists,
+    writeJsonAtomic,
+    writeTextAtomic,
+} from "../platform/file.ts"
+import { PLUGIN_NAME } from "./paths.ts"
+
+export interface ScaffoldPluginOptions {
+    readonly name: string
+    /** 生成到哪个父目录，默认当前工作目录 */
+    readonly parentDir?: string
+    readonly force?: boolean
+}
+
+export interface ScaffoldPluginResult {
+    readonly dir: string
+    readonly commandName: string
+}
+
+/** 插件名 → 合法命令名；名字不适用时回落到 hello */
+export function commandNameOf(pluginName: string): string {
+    let slug = pluginName
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+    if (!/^[a-z][a-z0-9-]*$/.test(slug) || slug.length < 2) {
+        slug = "hello"
+    }
+    return slug.slice(0, 32).replace(/-+$/, "")
+}
+
+function template(pluginName: string, commandName: string): string {
+    return [
+        'import { onMessage, onInit, onShutdown } from "wellspring/api/host/index.ts"',
+        'import type { WellspringPlugin } from "wellspring/api/host/index.ts"',
+        "",
+        "// 钩子可以放在模块顶层；平台在 import 时会把它们归属到当前插件",
+        "onMessage(({ phase, prompt }) => {",
+        '    if (phase === "before") prompt.push("你是一个运行在 Wellspring 里的助手")',
+        "})",
+        "",
+        "export function setup() {",
+        "    onInit(() => {",
+        "        // wellspring start 时触发",
+        "    })",
+        "    onShutdown(() => {",
+        "        // wellspring start 关闭时触发",
+        "    })",
+        "",
+        "    const plugin = {",
+        `        id: ${JSON.stringify(pluginName)},`,
+        `        name: ${JSON.stringify(pluginName)},`,
+        '        version: "0.1.0",',
+        '        status: "ok",',
+        "        deps: [],",
+        "        commands: [",
+        "            {",
+        `                name: ${JSON.stringify(commandName)},`,
+        `                summary: ${JSON.stringify(`${pluginName} 示例命令`)},`,
+        "                run: (ctx) => {",
+        '                    ctx.output.info("argv=" + ctx.argv.join(","))',
+        "                    return 0",
+        "                },",
+        "            },",
+        "        ],",
+        "    } satisfies WellspringPlugin",
+        "",
+        "    return plugin",
+        "}",
+        "",
+    ].join("\n")
+}
+
+function readmeTemplate(pluginName: string, commandName: string): string {
+    return [
+        `# ${pluginName}`,
+        "",
+        "## 开发",
+        "",
+        "编辑器 / tsc 解析 `wellspring/api/host/index.ts` 需要先把 Wellspring 链接进来：",
+        "",
+        "```bash",
+        "pnpm link /path/to/Wellspring",
+        "pnpm add -D typescript @types/node   # 如果还没有",
+        "pnpm exec tsc --noEmit",
+        "```",
+        "",
+        "运行时不需要链接：通过 `wellspring plugin link <this-dir>` 加载时，平台会解析宿主 API。",
+        "",
+        "## 加载",
+        "",
+        "```bash",
+        `wellspring plugin link \"$PWD\"`,
+        "wellspring plugin list",
+        `wellspring ${commandName}`,
+        "```",
+        "",
+    ].join("\n")
+}
+
+export async function scaffoldPlugin(
+    options: ScaffoldPluginOptions,
+): Promise<ScaffoldPluginResult> {
+    const name = options.name.trim()
+    if (!PLUGIN_NAME.test(name)) {
+        throw new Error(`插件名不合法：${name}`)
+    }
+    const parentDir = resolve(options.parentDir ?? process.cwd())
+    const dir = join(parentDir, name)
+    const existing = await statIfExists(dir)
+    if (existing !== null) {
+        if (options.force !== true) {
+            throw new Error(`目录已存在：${dir}`)
+        }
+        await removePath(dir)
+    }
+    await ensureDir(dir)
+
+    const commandName = commandNameOf(name)
+    await writeJsonAtomic(join(dir, "package.json"), {
+        name,
+        version: "0.1.0",
+        type: "module",
+        main: "index.ts",
+        wellspring: { apiVersion: 1 },
+    })
+    await writeTextAtomic(join(dir, "index.ts"), template(name, commandName))
+    await writeJsonAtomic(join(dir, "tsconfig.json"), {
+        compilerOptions: {
+            target: "ES2024",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            noEmit: true,
+            allowImportingTsExtensions: true,
+            skipLibCheck: true,
+            types: ["node"],
+        },
+        include: ["index.ts"],
+    })
+    await writeTextAtomic(join(dir, "README.md"), readmeTemplate(name, commandName))
+    return { dir, commandName }
+}

package/src/plugin/state.ts

@@ -0,0 +1,52 @@
+/*
+ * 插件启用状态：<dataDir>/plugins-state.json。
+ * 以插件目录名为 key，禁用后 loader 不再 import 该插件。
+ */
+
+import { join } from "node:path"
+
+import { readJsonIfExists, writeJsonAtomic } from "../platform/file.ts"
+import { getPaths, type ResolvedPaths } from "../platform/path.ts"
+
+interface PluginStateFile {
+    readonly version?: number
+    readonly disabled?: readonly string[]
+}
+
+export function pluginStateFile(paths: ResolvedPaths = getPaths()): string {
+    return join(paths.dataDir, "plugins-state.json")
+}
+
+/** 读取被禁用的插件目录名集合 */
+export async function readPluginState(
+    paths: ResolvedPaths = getPaths(),
+): Promise<ReadonlySet<string>> {
+    const value = await readJsonIfExists<PluginStateFile>(pluginStateFile(paths))
+    if (value === null || !Array.isArray(value.disabled)) {
+        return new Set()
+    }
+    return new Set(value.disabled.filter((item): item is string => typeof item === "string"))
+}
+
+/** 设置插件启用/禁用，返回是否发生变化 */
+export async function setPluginEnabled(
+    name: string,
+    enabled: boolean,
+    paths: ResolvedPaths = getPaths(),
+): Promise<boolean> {
+    const disabled = new Set(await readPluginState(paths))
+    const had = disabled.has(name)
+    if (enabled) {
+        disabled.delete(name)
+    } else {
+        disabled.add(name)
+    }
+    if (had === !enabled) {
+        return false
+    }
+    await writeJsonAtomic(pluginStateFile(paths), {
+        version: 1,
+        disabled: [...disabled].sort(),
+    })
+    return true
+}

package/src/plugin/zip.ts

@@ -0,0 +1,156 @@
+/*
+ * 最小 ZIP 读取器，只服务本地插件安装。
+ * 支持 store/deflate 两种压缩方式，拒绝加密、ZIP64、符号链接与路径穿越。
+ */
+
+import { inflateRawSync } from "node:zlib"
+
+import { ensureDir, writeBytesAtomic } from "../platform/file.ts"
+import { dirname, resolve, sep } from "node:path"
+
+const EOCD_SIGNATURE = 0x06054b50
+const CENTRAL_SIGNATURE = 0x02014b50
+const LOCAL_SIGNATURE = 0x04034b50
+const MAX_ENTRIES = 10_000
+const MAX_ENTRY_BYTES = 100 * 1024 * 1024
+const MAX_TOTAL_BYTES = 200 * 1024 * 1024
+
+export interface ZipEntry {
+    readonly name: string
+    readonly data: Buffer
+}
+
+function fail(message: string): never {
+    throw new Error(`zip 包非法：${message}`)
+}
+
+function validateName(name: string): void {
+    if (name === "" || name.startsWith("/") || name.includes("\\") || /^[A-Za-z]:/.test(name)) {
+        fail(`非法路径：${name}`)
+    }
+    for (const segment of name.split("/")) {
+        if (segment === ".." || segment === ".") {
+            fail(`非法路径：${name}`)
+        }
+    }
+}
+
+function findEocd(buffer: Buffer): number {
+    const minimum = Math.max(0, buffer.length - 65_557)
+    for (let offset = buffer.length - 22; offset >= minimum; offset -= 1) {
+        if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) {
+            return offset
+        }
+    }
+    return fail("找不到中央目录")
+}
+
+export function readZip(buffer: Buffer): ZipEntry[] {
+    if (buffer.length < 22) {
+        fail("文件过短")
+    }
+    const eocd = findEocd(buffer)
+    const entries = buffer.readUInt16LE(eocd + 10)
+    const centralOffset = buffer.readUInt32LE(eocd + 16)
+    if (entries > MAX_ENTRIES) {
+        fail("文件条目过多")
+    }
+    if (centralOffset === 0xffffffff) {
+        fail("不支持 ZIP64")
+    }
+
+    const result: ZipEntry[] = []
+    let total = 0
+    let offset = centralOffset
+
+    for (let index = 0; index < entries; index += 1) {
+        if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== CENTRAL_SIGNATURE) {
+            fail("中央目录损坏")
+        }
+        const flags = buffer.readUInt16LE(offset + 8)
+        const method = buffer.readUInt16LE(offset + 10)
+        const compressedSize = buffer.readUInt32LE(offset + 20)
+        const uncompressedSize = buffer.readUInt32LE(offset + 24)
+        const nameLength = buffer.readUInt16LE(offset + 28)
+        const extraLength = buffer.readUInt16LE(offset + 30)
+        const commentLength = buffer.readUInt16LE(offset + 32)
+        const externalAttributes = buffer.readUInt32LE(offset + 38)
+        const localOffset = buffer.readUInt32LE(offset + 42)
+        const name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString("utf8")
+        offset += 46 + nameLength + extraLength + commentLength
+
+        validateName(name)
+        if ((flags & 0x1) !== 0) {
+            fail(`不支持加密条目：${name}`)
+        }
+        if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff) {
+            fail("不支持 ZIP64 条目")
+        }
+        if (uncompressedSize > MAX_ENTRY_BYTES) {
+            fail(`单文件过大：${name}`)
+        }
+        total += uncompressedSize
+        if (total > MAX_TOTAL_BYTES) {
+            fail("解压后总大小超限")
+        }
+
+        if (name.endsWith("/")) {
+            result.push({ name, data: Buffer.alloc(0) })
+            continue
+        }
+        if (((externalAttributes >>> 16) & 0o170000) === 0o120000) {
+            fail(`不支持符号链接：${name}`)
+        }
+        if (
+            localOffset + 30 > buffer.length ||
+            buffer.readUInt32LE(localOffset) !== LOCAL_SIGNATURE
+        ) {
+            fail(`本地文件头损坏：${name}`)
+        }
+        const localNameLength = buffer.readUInt16LE(localOffset + 26)
+        const localExtraLength = buffer.readUInt16LE(localOffset + 28)
+        const dataStart = localOffset + 30 + localNameLength + localExtraLength
+        const end = dataStart + compressedSize
+        if (end > buffer.length) {
+            fail(`数据越界：${name}`)
+        }
+        const compressed = buffer.subarray(dataStart, end)
+
+        let data: Buffer
+        if (method === 0) {
+            data = Buffer.from(compressed)
+        } else if (method === 8) {
+            try {
+                data = inflateRawSync(compressed)
+            } catch (error) {
+                fail(
+                    `解压失败：${name}（${error instanceof Error ? error.message : String(error)}）`,
+                )
+            }
+        } else {
+            fail(`不支持的压缩方式 ${method}：${name}`)
+        }
+        if (data.length !== uncompressedSize) {
+            fail(`解压大小不符：${name}`)
+        }
+        result.push({ name, data })
+    }
+    return result
+}
+
+/** 解压到目标目录；调用方负责临时目录与清理 */
+export async function extractZip(buffer: Buffer, destination: string): Promise<void> {
+    const root = resolve(destination)
+    for (const entry of readZip(buffer)) {
+        const target = resolve(root, entry.name)
+        if (target !== root && !target.startsWith(`${root}${sep}`)) {
+            fail(`路径穿越：${entry.name}`)
+        }
+        if (entry.name.endsWith("/")) {
+            await ensureDir(target)
+            continue
+        }
+        await ensureDir(dirname(target))
+        await writeBytesAtomic(target, entry.data)
+    }
+}

package/src/sandbox/audit.ts

@@ -0,0 +1,38 @@
+/*
+ * sandbox 审计日志：<logDir>/sandbox-audit.log，JSONL。
+ */
+
+import { appendFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+
+import { ensureDir } from "../platform/file.ts"
+import type { ResolvedPaths } from "../platform/path.ts"
+
+export interface SandboxAuditEvent {
+    readonly type: string
+    readonly sandboxId: string
+    readonly pluginId?: string
+    readonly backend?: string
+    readonly decision?: "allowed" | "denied"
+    readonly reason?: string
+    readonly [key: string]: unknown
+}
+
+let queue: Promise<void> = Promise.resolve()
+
+export function auditSandbox(paths: ResolvedPaths, event: SandboxAuditEvent): void {
+    const file = join(paths.logDir, "sandbox-audit.log")
+    queue = queue
+        .then(async () => {
+            await ensureDir(dirname(file))
+            await appendFile(
+                file,
+                `${JSON.stringify({ time: new Date().toISOString(), ...event })}\n`,
+            )
+        })
+        .catch(() => undefined)
+}
+
+export async function flushSandboxAudit(): Promise<void> {
+    await queue
+}

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,
+        }
+    }
+}