min-agent 0.3.0 → 0.4.0

package/dist/sandbox.js

@@ -0,0 +1,403 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { existsSync, realpathSync } from "fs";
+import os from "os";
+import path from "path";
+import { getEffectiveConfig } from "./config.js";
+export const DEFAULT_SANDBOX_MODE = "off";
+export const DEFAULT_NETWORK_POLICY = "allow";
+const MODE_RANK = { off: 0, workspace: 1, strict: 2 };
+const sandboxAls = new AsyncLocalStorage();
+let processOverride = {};
+export function parseSandboxMode(value) {
+    if (value === "off" || value === "workspace" || value === "strict")
+        return value;
+    return undefined;
+}
+export function parseNetworkPolicy(value) {
+    if (value === "allow" || value === "deny")
+        return value;
+    return undefined;
+}
+export function parseSandboxConfig(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw === "string") {
+        const mode = parseSandboxMode(raw);
+        return mode ? { mode } : undefined;
+    }
+    if (typeof raw !== "object")
+        return undefined;
+    const obj = raw;
+    const mode = parseSandboxMode(obj.mode);
+    const network = parseNetworkPolicy(obj.network);
+    const extraWriteRoots = Array.isArray(obj.extraWriteRoots)
+        ? obj.extraWriteRoots.filter((p) => typeof p === "string" && p.length > 0)
+        : undefined;
+    const extraReadRoots = Array.isArray(obj.extraReadRoots)
+        ? obj.extraReadRoots.filter((p) => typeof p === "string" && p.length > 0)
+        : undefined;
+    if (!mode && !network && !extraWriteRoots && !extraReadRoots)
+        return undefined;
+    return { mode, network, extraWriteRoots, extraReadRoots };
+}
+export function mergeSandboxConfig(global, project) {
+    if (!global && !project)
+        return undefined;
+    const extraWriteRoots = project?.extraWriteRoots ?? global?.extraWriteRoots;
+    const extraReadRoots = project?.extraReadRoots ?? global?.extraReadRoots;
+    return {
+        mode: project?.mode ?? global?.mode,
+        network: project?.network ?? global?.network,
+        ...(extraWriteRoots ? { extraWriteRoots } : {}),
+        ...(extraReadRoots ? { extraReadRoots } : {}),
+    };
+}
+export function setSandboxOverride(partial) {
+    processOverride = { ...processOverride, ...partial };
+}
+export function clearSandboxOverride() {
+    processOverride = {};
+}
+export function getSandboxOverride() {
+    return { ...processOverride };
+}
+export function sandboxLaunchSource() {
+    if (processOverride.mode != null || processOverride.network != null)
+        return "cli";
+    if (envMode() != null || envNetwork() != null)
+        return "env";
+    return null;
+}
+export function runWithSandboxPolicy(policy, fn) {
+    return sandboxAls.run(policy, fn);
+}
+export function workspaceRoot() {
+    try {
+        return realpathSync(process.cwd());
+    }
+    catch {
+        return path.resolve(process.cwd());
+    }
+}
+function envMode() {
+    return parseSandboxMode(process.env.MIN_AGENT_SANDBOX);
+}
+function envNetwork() {
+    return parseNetworkPolicy(process.env.MIN_AGENT_SANDBOX_NETWORK);
+}
+function basePolicyFromConfig() {
+    const parsed = parseSandboxConfig(getEffectiveConfig().sandbox);
+    return {
+        mode: processOverride.mode ?? envMode() ?? parsed?.mode ?? DEFAULT_SANDBOX_MODE,
+        network: processOverride.network ?? envNetwork() ?? parsed?.network ?? DEFAULT_NETWORK_POLICY,
+        extraWriteRoots: processOverride.extraWriteRoots ?? parsed?.extraWriteRoots ?? [],
+        extraReadRoots: processOverride.extraReadRoots ?? parsed?.extraReadRoots ?? [],
+        workspaceRoot: workspaceRoot(),
+    };
+}
+export function tightenSandbox(base, request) {
+    const mode = request.mode && MODE_RANK[request.mode] > MODE_RANK[base.mode] ? request.mode : base.mode;
+    const network = request.network === "deny" || base.network === "deny" ? "deny" : "allow";
+    return { ...base, mode, network };
+}
+export function getEffectiveSandboxPolicy() {
+    const base = basePolicyFromConfig();
+    const als = sandboxAls.getStore();
+    if (!als)
+        return base;
+    if (als.replace) {
+        return {
+            mode: als.mode ?? DEFAULT_SANDBOX_MODE,
+            network: als.network ?? DEFAULT_NETWORK_POLICY,
+            extraWriteRoots: als.extraWriteRoots ?? [],
+            extraReadRoots: als.extraReadRoots ?? [],
+            workspaceRoot: als.workspaceRoot ?? workspaceRoot(),
+        };
+    }
+    return tightenSandbox(base, als);
+}
+export function isInsideRoot(target, root) {
+    const normalize = (p) => {
+        const resolved = path.resolve(p);
+        return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    };
+    const child = normalize(target);
+    const parent = normalize(root);
+    if (child === parent)
+        return true;
+    const prefix = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(prefix);
+}
+export function resolveCheckedPath(userPath, cwd = process.cwd()) {
+    const lexical = path.resolve(cwd, userPath);
+    const parts = [];
+    let cur = lexical;
+    for (;;) {
+        try {
+            const realBase = realpathSync(cur);
+            return { lexical, real: parts.length === 0 ? realBase : path.resolve(realBase, ...parts) };
+        }
+        catch {
+            const next = path.dirname(cur);
+            if (next === cur)
+                return { lexical, real: lexical };
+            parts.unshift(path.basename(cur));
+            cur = next;
+        }
+    }
+}
+function homePath(...segments) {
+    return path.join(os.homedir(), ...segments);
+}
+function sensitiveDirPrefixes() {
+    return [
+        homePath(".ssh"),
+        homePath(".gnupg"),
+        homePath(".aws"),
+        path.join(homePath(".min-agent"), "config.json"),
+        homePath(".netrc"),
+        homePath(".npmrc"),
+        homePath(".pypirc"),
+        homePath(".git-credentials"),
+        path.join(homePath(".config"), "gh"),
+        path.join(homePath(".config"), "git", "credentials"),
+        "/etc/shadow",
+        "/etc/sudoers",
+        "/etc/master.passwd",
+    ];
+}
+function isSensitivePath(real) {
+    return sensitiveDirPrefixes().some((root) => {
+        try {
+            const resolvedRoot = existsSync(root) ? realpathSync(root) : path.resolve(root);
+            return isInsideRoot(real, resolvedRoot) || path.resolve(real) === path.resolve(root);
+        }
+        catch {
+            return isInsideRoot(real, root);
+        }
+    });
+}
+function uniqueExistingAndLexical(paths) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of paths) {
+        const lexical = path.resolve(raw);
+        const aliases = [lexical];
+        try {
+            aliases.push(realpathSync(lexical));
+        }
+        catch {
+            /* not created yet */
+        }
+        for (const item of aliases) {
+            const key = process.platform === "win32" ? item.toLowerCase() : item;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(item);
+        }
+    }
+    return out;
+}
+function defaultCacheWriteRoots() {
+    const home = os.homedir();
+    return [
+        path.join(home, ".npm"),
+        path.join(home, ".bun"),
+        path.join(home, ".cache"),
+        path.join(home, ".local"),
+        path.join(home, ".yarn"),
+        path.join(home, "Library", "Caches"),
+        path.join(home, "AppData", "Local"),
+        path.join(home, "AppData", "Roaming"),
+    ];
+}
+export function writeRoots(policy = getEffectiveSandboxPolicy()) {
+    return uniqueExistingAndLexical([
+        policy.workspaceRoot,
+        os.tmpdir(),
+        "/tmp",
+        "/var/tmp",
+        "/private/tmp",
+        "/private/var/tmp",
+        ...defaultCacheWriteRoots(),
+        ...policy.extraWriteRoots.map((p) => path.resolve(policy.workspaceRoot, p)),
+    ]);
+}
+export function readRoots(policy = getEffectiveSandboxPolicy()) {
+    return uniqueExistingAndLexical([
+        policy.workspaceRoot,
+        ...writeRoots(policy),
+        ...policy.extraReadRoots.map((p) => path.resolve(policy.workspaceRoot, p)),
+    ]);
+}
+function inAnyRoot(real, roots) {
+    return roots.some((root) => isInsideRoot(real, root));
+}
+export function checkPathAccess(userPath, access, cwd = process.cwd(), policy = getEffectiveSandboxPolicy()) {
+    const { real } = resolveCheckedPath(userPath, cwd);
+    if (isSensitivePath(real)) {
+        return { ok: false, message: "该路径受保护，无法访问。" };
+    }
+    if (policy.mode === "off")
+        return { ok: true, real };
+    if (access === "write") {
+        if (!inAnyRoot(real, writeRoots(policy))) {
+            return { ok: false, message: `无法写入工作区以外的路径: ${userPath}` };
+        }
+        return { ok: true, real };
+    }
+    if (policy.mode === "strict" && !inAnyRoot(real, readRoots(policy))) {
+        return { ok: false, message: `当前隔离级别不允许读取工作区以外的文件: ${userPath}` };
+    }
+    return { ok: true, real };
+}
+export function pathAccessError(userPath, access, cwd) {
+    const result = checkPathAccess(userPath, access, cwd);
+    return result.ok ? null : result.message;
+}
+export function isNetworkCommand(command) {
+    return (/\b(curl|wget|nc|ncat|netcat|ssh|scp|sftp|ftp|telnet|nmap|ping|nslookup|dig|traceroute|rsync)\b/i.test(command) ||
+        /\bgit\s+(clone|fetch|pull|push|ls-remote)\b/i.test(command) ||
+        /\b(npm|pnpm|yarn|bun)\s+(install|add|publish|update|upgrade)\b/i.test(command));
+}
+export function networkDeniedMessage() {
+    return "当前设置不允许访问网络。";
+}
+let backendCache;
+export function detectSandboxBackend() {
+    if (backendCache)
+        return backendCache;
+    const forced = process.env.MIN_AGENT_SANDBOX_BACKEND;
+    if (forced === "seatbelt" || forced === "bwrap" || forced === "none") {
+        backendCache = forced;
+        return backendCache;
+    }
+    if (process.platform === "darwin" && existsSync("/usr/bin/sandbox-exec")) {
+        backendCache = "seatbelt";
+    }
+    else if (process.platform === "linux" && (existsSync("/usr/bin/bwrap") || existsSync("/usr/local/bin/bwrap"))) {
+        backendCache = "bwrap";
+    }
+    else {
+        backendCache = "none";
+    }
+    return backendCache;
+}
+export function resetSandboxBackendCache() {
+    backendCache = undefined;
+}
+function seatbeltQuote(p) {
+    return `"${p.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+export function buildSeatbeltProfile(policy) {
+    const writes = writeRoots(policy)
+        .map((root) => `(subpath ${seatbeltQuote(root)})`)
+        .join("\n    ");
+    const denyReads = sensitiveDirPrefixes()
+        .map((root) => `(subpath ${seatbeltQuote(path.resolve(root))})`)
+        .join("\n    ");
+    const network = policy.network === "deny" ? "(deny network*)" : "";
+    return `(version 1)
+(allow default)
+(deny file-write*)
+(allow file-write-data (literal "/dev/null"))
+(allow file-write*
+    ${writes}
+)
+(deny file-read*
+    ${denyReads}
+)
+${network}
+`;
+}
+export function bwrapBin() {
+    if (existsSync("/usr/bin/bwrap"))
+        return "/usr/bin/bwrap";
+    return "/usr/local/bin/bwrap";
+}
+export function buildBwrapArgs(policy, cwd, command) {
+    const args = ["--die-with-parent", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc"];
+    const bound = new Set();
+    for (const root of writeRoots(policy)) {
+        const key = process.platform === "win32" ? root.toLowerCase() : root;
+        if (bound.has(key))
+            continue;
+        bound.add(key);
+        if (existsSync(root))
+            args.push("--bind", root, root);
+    }
+    if (policy.network === "deny")
+        args.push("--unshare-net");
+    args.push("--chdir", cwd, "/bin/sh", "-c", command);
+    return args;
+}
+const NO_BACKEND_COMMAND_WARNING = "⚠ 当前平台不支持命令级隔离（需要 macOS 的 sandbox-exec 或 Linux 的 bwrap），bash 命令未在隔离环境中执行，工作区写入限制对它不生效（read/write/edit 等文件工具仍会校验路径）。";
+const NO_BACKEND_NETWORK_WARNING = "⚠ 当前平台不支持系统级网络隔离，禁止联网仅按命令名拦截，脚本或解释器仍可能访问网络。";
+const STRICT_NO_BACKEND_ERROR = "当前平台不支持命令级隔离（需要 macOS 的 sandbox-exec 或 Linux 的 bwrap），严格隔离模式下无法安全执行 bash 命令，已拒绝执行。可将隔离级别设为 workspace（文件工具仍会校验路径）或 off。";
+/** Config-time caveat when the platform cannot enforce command-level isolation for the given mode. */
+export function sandboxEnforcementCaveat(mode) {
+    if (mode === "off" || detectSandboxBackend() !== "none")
+        return null;
+    return mode === "strict"
+        ? "⚠ Command-level sandboxing isn't supported on this platform (requires macOS sandbox-exec or Linux bwrap); bash commands will be rejected in strict mode."
+        : "⚠ Command-level sandboxing isn't supported on this platform (requires macOS sandbox-exec or Linux bwrap); bash commands won't be restricted to the workspace (file tools still validate paths).";
+}
+export function planSandboxedSpawn(command, cwd, env, policy = getEffectiveSandboxPolicy()) {
+    if (policy.mode !== "off") {
+        const cwdCheck = checkPathAccess(cwd, "write", process.cwd(), policy);
+        if (!cwdCheck.ok)
+            return { error: `无法在工作区以外的目录执行命令: ${cwd}` };
+    }
+    const backend = detectSandboxBackend();
+    if (policy.network === "deny" && backend === "none" && isNetworkCommand(command)) {
+        return { error: networkDeniedMessage() };
+    }
+    const isWin = process.platform === "win32";
+    const actualCommand = isWin ? `chcp 65001 >nul && ${command}` : command;
+    const childEnv = { ...env, ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}) };
+    const shellPlan = () => ({ file: actualCommand, args: [], shell: true, cwd, env: childEnv });
+    if (policy.mode === "off") {
+        const plan = shellPlan();
+        if (policy.network === "deny" && backend === "none")
+            plan.warning = NO_BACKEND_NETWORK_WARNING;
+        return plan;
+    }
+    if (backend === "seatbelt") {
+        return {
+            file: "/usr/bin/sandbox-exec",
+            args: ["-p", buildSeatbeltProfile(policy), "/bin/sh", "-c", actualCommand],
+            shell: false,
+            cwd,
+            env: childEnv,
+        };
+    }
+    if (backend === "bwrap") {
+        return {
+            file: bwrapBin(),
+            args: buildBwrapArgs(policy, cwd, actualCommand),
+            shell: false,
+            cwd,
+            env: childEnv,
+        };
+    }
+    // No OS-level sandbox available: strict cannot be honored at all, so refuse;
+    // workspace still gets path checks from the file tools, so run with a caveat.
+    if (policy.mode === "strict")
+        return { error: STRICT_NO_BACKEND_ERROR };
+    const plan = shellPlan();
+    plan.warning =
+        policy.network === "deny"
+            ? `${NO_BACKEND_COMMAND_WARNING}\n${NO_BACKEND_NETWORK_WARNING}`
+            : NO_BACKEND_COMMAND_WARNING;
+    return plan;
+}
+export function sandboxModeLabel(mode) {
+    return mode === "off" ? "off" : mode === "strict" ? "strict" : "workspace";
+}
+export function sandboxNetworkLabel(network) {
+    return network === "deny" ? "network denied" : "network allowed";
+}
+export function sandboxStatusLabel(policy = getEffectiveSandboxPolicy()) {
+    return `${sandboxModeLabel(policy.mode)}, ${sandboxNetworkLabel(policy.network)}`;
+}

package/dist/save-throttle.js

@@ -0,0 +1,45 @@
+export function createSaveThrottle(save, intervalMs = 2000, now = Date.now) {
+    let lastRun = 0;
+    let timer;
+    let pending = false;
+    const run = () => {
+        timer = undefined;
+        pending = false;
+        lastRun = now();
+        try {
+            save();
+        }
+        catch {
+            /* persistence is best-effort */
+        }
+    };
+    return {
+        request() {
+            if (timer) {
+                pending = true;
+                return;
+            }
+            const elapsed = now() - lastRun;
+            if (elapsed >= intervalMs) {
+                run();
+                return;
+            }
+            pending = true;
+            timer = setTimeout(run, intervalMs - elapsed);
+        },
+        flush() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (pending)
+                run();
+        },
+        cancel() {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            pending = false;
+        },
+    };
+}