@morlay/dsh-sandbox-local 0.0.2

package/dist/index.mjs

@@ -0,0 +1,585 @@
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { canonicalPath, writableRoots } from "@deepseek-ai/dsh-sandbox";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { stat } from "node:fs/promises";
+import { LocalSandboxProvider } from "@deepseek-ai/dsh-sandbox-local";
+import z from "@deepseek-ai/schemastery";
+//#region src/rules.ts
+/**
+* 规则编译：`access` 条目解析（`rw <path>` 额外可写根 / `r- <path>` 只读 /
+* `-- <pattern>` 拒绝访问）、`{{ env.NAME }}` 模板展开、相对工作区路径的绝对化、
+* glob → 正则，以及编译结果的匹配。
+*
+* 命中优先级：`--` 拒绝覆盖一切；`r-` 只读覆盖可写授予；都未命中时才按可写根判定。
+*
+* 生成的正则源码同时交给进程内检查（JS `RegExp`）与 macOS Seatbelt profile
+* （SBPL 的 `(regex #"…")`），因此只用 POSIX ERE 与 JS 正则共有的语法。
+* @module @morlay/dsh-sandbox-local/rules
+*/
+/** `{{ env.NAME }}` 模板；名字限定为环境变量的字符集。 */
+const ENV_TEMPLATE = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+/** `access` 的条目形式：`rw <path>` / `r- <path>` / `-- <pattern>`；前缀后必须有空白。 */
+const ACCESS_LINE = /^(rw|r-|--)(?:\s+(.*))?$/u;
+/** glob 元字符：规则里出现即按模式匹配，否则按字面路径（含其全部后代）匹配。 */
+const GLOB_META = /[*?[]/;
+/** glob 翻译时需要转义的正则元字符（字符类内部除外）。 */
+const REGEX_META = /[\\^$+.(){}|]/;
+/** 展开规则里的 `{{ env.NAME }}`；引用未定义或为空的环境变量直接抛错。 */
+function expandEnvTemplates(value, env) {
+	return value.replace(ENV_TEMPLATE, (_match, name) => {
+		const resolved = env[name];
+		if (resolved === void 0 || resolved.length === 0) throw new Error(`sandbox rules: "${value}" references the unset environment variable "${name}"`);
+		return resolved;
+	});
+}
+/**
+* 把含 glob 的规则翻译成正则源码。
+* `**` 跨目录层级（`**` 与“`**` 后接斜杠”都能匹配零层），`*` 与 `?` 不跨 `/`，
+* 字符类透传（`[!…]` 按 glob 习惯翻成 `[^…]`），其余正则元字符转义。
+* @param pattern - 已绝对化的 glob 规则。
+* @returns 可同时被 JS `RegExp` 与 SBPL regex 接受的正则源码。
+*/
+function globToRegexSource(pattern) {
+	let source = "";
+	for (let index = 0; index < pattern.length; index += 1) {
+		const char = pattern[index];
+		if (char === "*") {
+			if (pattern[index + 1] === "*") {
+				index += 1;
+				if (pattern[index + 1] === "/") {
+					index += 1;
+					source += "(.*/)?";
+				} else source += ".*";
+			} else source += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		if (char === "[") {
+			const close = pattern.indexOf("]", index + 1);
+			if (close === -1) {
+				source += "\\[";
+				continue;
+			}
+			const body = pattern.slice(index + 1, close);
+			if (body.length === 0) {
+				source += "\\[\\]";
+				index = close;
+				continue;
+			}
+			source += body.startsWith("!") ? `[^${body.slice(1)}]` : `[${body}]`;
+			index = close;
+			continue;
+		}
+		source += REGEX_META.test(char) ? `\\${char}` : char;
+	}
+	return source;
+}
+/** 规则是否为空——空规则下 provider 不改写任何 runner 参数。 */
+function isEmptyRules(rules) {
+	return rules.allowRoots.length === 0 && rules.readOnlySubtrees.length === 0 && rules.readOnlyPatterns.length === 0 && rules.denySubtrees.length === 0 && rules.denyPatterns.length === 0;
+}
+/** 只读模式不因 `rw` 条目放松：投影出只保留 `r-` / `--` 条目的规则集。 */
+function withoutAllowRoots(rules) {
+	return rules.allowRoots.length === 0 ? rules : {
+		...rules,
+		allowRoots: []
+	};
+}
+/**
+* 解析 `access` 配置：接受字符串数组（每项一条规则）或多行文本（每行一条规则），
+* 空行忽略；`rw <path>` 是额外可写根，`r- <path>` 是只读，`-- <pattern>` 是访问
+* 拒绝（读 + 写）。缺前缀或前缀后没有路径都直接报错——规则不因写法歧义而变形。
+* @param input - 配置里的 `access` 值。
+* @returns `allowWrite` / `readOnly` / `deny` 三组规则（模板尚未展开）。
+*/
+function parseAccess(input) {
+	const lines = (input === void 0 ? [] : typeof input === "string" ? [input] : [...input]).flatMap((value) => value.split(/\r?\n/u)).map((line) => line.trim()).filter((line) => line.length > 0);
+	const allowWrite = [];
+	const readOnly = [];
+	const deny = [];
+	for (const line of lines) {
+		const match = ACCESS_LINE.exec(line);
+		if (match === null) throw new Error(`sandbox rules: access entry ${JSON.stringify(line)} must start with "rw " (write), "r- " (read-only) or "-- " (deny)`);
+		const rule = (match[2] ?? "").trim();
+		if (rule.length === 0) throw new Error(`sandbox rules: access entry ${JSON.stringify(line)} carries no path`);
+		if (match[1] === "rw") allowWrite.push(rule);
+		else if (match[1] === "r-") readOnly.push(rule);
+		else deny.push(rule);
+	}
+	return {
+		allowWrite,
+		readOnly,
+		deny
+	};
+}
+/**
+* 把配置里的 `access` 转成规则来源：模板在这一步展开（加载期，fail-fast），
+* 相对路径留待按调用时的工作区根绝对化。
+* @param config - 含 `access` 的插件配置。
+* @param env - 模板展开用的进程环境。
+* @returns 模板已展开的规则来源。
+*/
+function ruleSourceOf(config, env) {
+	const parsed = parseAccess(config.access);
+	const expand = (values) => values.map((value) => expandEnvTemplates(value, env));
+	return {
+		allowWrite: expand(parsed.allowWrite),
+		readOnly: expand(parsed.readOnly),
+		deny: expand(parsed.deny)
+	};
+}
+/** 绝对化一条规则：相对路径相对工作区根。 */
+function absolutize(value, workspaceRoot) {
+	return isAbsolute(value) ? value : resolve(workspaceRoot, value);
+}
+/** 编译一组字面路径 / glob 规则：字面项按子树（含全部后代）匹配，glob 项按整串匹配。 */
+function compilePaths(values, workspaceRoot) {
+	const subtrees = [];
+	const patterns = [];
+	for (const value of values) {
+		const absolute = absolutize(value, workspaceRoot);
+		if (GLOB_META.test(value)) {
+			const pattern = `^${globToRegexSource(absolute)}$`;
+			patterns.push({
+				source: pattern,
+				regex: new RegExp(pattern)
+			});
+		} else subtrees.push(canonicalPath(absolute));
+	}
+	return {
+		subtrees,
+		patterns
+	};
+}
+/**
+* 按一个工作区根编译规则。
+* `rw` 条目必须是具体路径（glob 无法表达“可写根”）；`r-` 与 `--` 条目允许 glob。
+* @param source - 已展开模板的规则来源。
+* @param workspaceRoot - 相对规则解析用的工作区根（canonical 绝对路径）。
+* @returns 编译后的规则。
+*/
+function compileRules(source, workspaceRoot) {
+	const allowRoots = [];
+	for (const value of source.allowWrite) {
+		if (GLOB_META.test(value)) throw new Error(`sandbox rules: rw entry "${value}" must name a concrete path, not a glob`);
+		allowRoots.push(canonicalPath(absolutize(value, workspaceRoot)));
+	}
+	const readOnly = compilePaths(source.readOnly, workspaceRoot);
+	const deny = compilePaths(source.deny, workspaceRoot);
+	return {
+		allowRoots,
+		readOnlySubtrees: readOnly.subtrees,
+		readOnlyPatterns: readOnly.patterns,
+		denySubtrees: deny.subtrees,
+		denyPatterns: deny.patterns
+	};
+}
+/** 字面规则的后代判定（canonical 拼写，与 Seatbelt `subpath` 同一语义）。 */
+function isUnder(path, root) {
+	if (path === root) return true;
+	return path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+/** 命中任一子树或任一模式。 */
+function matches(canonicalTarget, subtrees, patterns) {
+	for (const subtree of subtrees) if (isUnder(canonicalTarget, subtree)) return true;
+	return patterns.some((pattern) => pattern.regex.test(canonicalTarget));
+}
+/**
+* 判断目标是否被 `--` 条目命中（读与写都拒）。
+* @param rules - 已编译规则。
+* @param canonicalTarget - 目标的 canonical 路径。
+* @returns 命中即 true。
+*/
+function isDenied(rules, canonicalTarget) {
+	return matches(canonicalTarget, rules.denySubtrees, rules.denyPatterns);
+}
+/**
+* 判断目标是否被 `r-` 条目命中（读放行、写拒绝）。
+* @param rules - 已编译规则。
+* @param canonicalTarget - 目标的 canonical 路径。
+* @returns 命中即 true。
+*/
+function isReadOnly(rules, canonicalTarget) {
+	return matches(canonicalTarget, rules.readOnlySubtrees, rules.readOnlyPatterns);
+}
+//#endregion
+//#region src/dialects.ts
+/**
+* 在官方 provider 生成的 confined argv 上追加本包规则：
+* Seatbelt 追加 SBPL 规则（后置规则覆盖先前的 allow，实测 `(deny file-read* file-write*
+* (subpath …))` 能压过 `(allow file-write* (subpath …))`，`r-` 条目则只 deny 写入），
+* bwrap 追加挂载参数（`rw` 用 `--bind-try`，`r-` 与 `--` 都用 `--ro-bind-try`），
+* Landlock 只能追加可写授权（其 allow-list 语义无法减除子路径），
+* Windows ACL runner 没有对应表达。
+*
+* 方言从官方 `ConfinedArgv.argv` 的结构识别：runner 参数在前，`--` 之后是调用方 argv。
+* @module @morlay/dsh-sandbox-local/dialects
+*/
+/** runner 部分与调用方 argv 的分隔符。 */
+const SEPARATOR = "--";
+/** 各方言的规则表达能力——加载期据此告警，运行期据此决定是否改写参数。 */
+const DIALECT_CAPABILITIES = {
+	seatbelt: {
+		allowWrite: true,
+		readOnly: true,
+		denyReadWrite: true,
+		denyWriteOnly: false
+	},
+	bwrap: {
+		allowWrite: true,
+		readOnly: true,
+		denyReadWrite: false,
+		denyWriteOnly: true
+	},
+	landlock: {
+		allowWrite: true,
+		readOnly: false,
+		denyReadWrite: false,
+		denyWriteOnly: false
+	},
+	"windows-acl": {
+		allowWrite: false,
+		readOnly: false,
+		denyReadWrite: false,
+		denyWriteOnly: false
+	}
+};
+/** runner 部分的结束位置。 */
+function separatorIndex(argv) {
+	const index = argv.indexOf(SEPARATOR);
+	if (index === -1) throw new Error("sandbox rules: the confined argv carries no `--` separator to extend");
+	return index;
+}
+/**
+* 识别 argv 使用的执行方言。
+* @param argv - 官方 provider 返回的完整 confined argv。
+* @returns 方言，或无法识别时的 `undefined`（例如运维自定义的 runnerCommand）。
+*/
+function dialectOf(argv) {
+	const separator = argv.indexOf(SEPARATOR);
+	const runner = separator === -1 ? argv : argv.slice(0, separator);
+	if (runner.includes("-p")) return "seatbelt";
+	if (runner[0] === "bwrap") return "bwrap";
+	if (runner.includes("--workspace")) return "windows-acl";
+	if (runner.includes("--ro") || runner.includes("--rw")) return "landlock";
+}
+/** SBPL 字符串字面量。 */
+function sbplString(value) {
+	return `"${value.replaceAll("\\", String.raw`\\`).replaceAll("\"", String.raw`\"`)}"`;
+}
+/**
+* SBPL `#"…"` 的正则体：正则自身的 `\` 必须保留（glob 翻译用它转义元字符），
+* 因此拒绝项里出现双引号时直接报错，而不是产出一个含义变化的 profile。
+*/
+function sbplRegexBody(source) {
+	if (source.includes("\"")) throw new Error(`sandbox rules: deny pattern ${JSON.stringify(source)} cannot be expressed in a Seatbelt profile`);
+	return source;
+}
+/** Seatbelt：把 allow / deny 规则追加到 `-p` 的 profile 文本末尾。 */
+function extendSeatbelt(argv, rules) {
+	const index = argv.indexOf("-p");
+	const profile = index === -1 ? void 0 : argv[index + 1];
+	if (profile === void 0) throw new Error("sandbox rules: the Seatbelt runner argv carries no `-p` profile to extend");
+	const extended = `${profile} ${[
+		...rules.allowRoots.map((root) => `(allow file-write* (subpath ${sbplString(root)}))`),
+		...rules.readOnlySubtrees.map((path) => `(deny file-write* (subpath ${sbplString(path)}))`),
+		...rules.readOnlyPatterns.map((pattern) => `(deny file-write* (regex #"${sbplRegexBody(pattern.source)}"))`),
+		...rules.denySubtrees.map((path) => `(deny file-read* file-write* (subpath ${sbplString(path)}))`),
+		...rules.denyPatterns.map((pattern) => `(deny file-read* file-write* (regex #"${sbplRegexBody(pattern.source)}"))`)
+	].join(" ")}`;
+	return [
+		...argv.slice(0, index + 1),
+		extended,
+		...argv.slice(index + 2)
+	];
+}
+/**
+* bwrap：额外可写根用 `--bind-try`（路径不存在时跳过）；`r-` 与 `--` 都用
+* `--ro-bind-try` 覆盖成只读（挂载后行覆盖前行）——也就是说 `--` 在 bwrap 上退化为
+* “只拒写入”。glob 模式无法表达为静态挂载，由调用方在加载期告警。
+*/
+function extendBwrap(argv, rules) {
+	const separator = separatorIndex(argv);
+	const additions = [];
+	for (const root of rules.allowRoots) additions.push("--bind-try", root, root);
+	for (const path of [...rules.readOnlySubtrees, ...rules.denySubtrees]) additions.push("--ro-bind-try", path, path);
+	return [
+		...argv.slice(0, separator),
+		...additions,
+		...argv.slice(separator)
+	];
+}
+/** Landlock：只能追加可写授权（`--rw`），`r-` 与 `--` 都无对应表达。 */
+function extendLandlock(argv, rules) {
+	const separator = separatorIndex(argv);
+	const additions = rules.allowRoots.flatMap((root) => ["--rw", root]);
+	return [
+		...argv.slice(0, separator),
+		...additions,
+		...argv.slice(separator)
+	];
+}
+/**
+* 按 argv 的方言追加规则。
+* @param argv - 官方 provider 返回的 confined argv。
+* @param rules - 已编译规则；空规则原样返回。
+* @returns 追加规则后的 argv；方言无法识别时抛错（规则不能静默失效）。
+*/
+function extendConfinedArgv(argv, rules) {
+	if (isEmptyRules(rules)) return [...argv];
+	const dialect = dialectOf(argv);
+	if (dialect === void 0) throw new Error("sandbox rules: cannot extend an unrecognized sandbox runner argv; drop allowWrite/deny or configure a bwrap-compatible runnerCommand");
+	switch (dialect) {
+		case "seatbelt": return extendSeatbelt(argv, rules);
+		case "bwrap": return extendBwrap(argv, rules);
+		case "landlock": return extendLandlock(argv, rules);
+		case "windows-acl": return [...argv];
+	}
+}
+//#endregion
+//#region src/containment.ts
+/** 视为“路径不存在”的错误码：只有它们能让祖先遍历继续。 */
+const MISSING_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+/** stat 一次，缺失返回 undefined；其它失败（权限、I/O）继续抛出。 */
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		const code = error.code;
+		if (code !== void 0 && MISSING_CODES.has(code)) return void 0;
+		throw error;
+	}
+}
+/** 按大小写敏感性归一用于比较的拼写。 */
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+/** 词法包含判定（目标可带尚不存在的后缀）。 */
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+/** 两次 stat 是否指向同一个文件系统对象。 */
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* 判断 canonical 目标是否就是某个根或位于其下。
+* 拼写不同时（Windows 长名/8.3 别名、大小写差异）沿目标的现存祖先比较文件系统身份，
+* 不把包含判定弱化成文本近似。
+* @param path - 目标的 canonical 路径（可带尚不存在的尾部）。
+* @param root - canonical 可写根。
+* @param caseSensitive - 词法比较是否区分大小写；默认按宿主平台约定。
+* @returns 目标是该根或其后代时为 true。
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (rootInfo === void 0) return false;
+	let ancestor = path;
+	for (;;) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo !== void 0 && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+//#endregion
+//#region src/fs.ts
+/**
+* 官方本机文件系统后端的可配置版本。
+* `--` 条目在解析阶段拒绝目标（覆盖 read / write / edit / list 等一切工具入口），
+* `r-` 与 `--` 条目在写入前拒绝写入（优先于任何可写根），写操作再按
+* `workspace-write` + `rw` 条目复核 containment。
+*/
+var ConfigurableFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy"];
+	defaultMode;
+	source;
+	/** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
+	compiled = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+		this.source = ruleSourceOf(config, process.env);
+	}
+	/** 工具层读它判断后端是否 confine（并据此广告 escalation 字段）。 */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* 解析目标后立即执行拒绝判定：工具入口（read / write / edit / list）都先经过
+	* `resolve`，因此一次判定即可覆盖读与写。
+	* @param path - 待解析的路径。
+	* @param opts - cwd 与取消信号；cwd 同时是相对规则的解析根。
+	* @returns 解析后的目标。
+	*/
+	async resolve(path, opts) {
+		const target = await super.resolve(path, opts);
+		this.assertNotDenied(this.rulesFor(opts?.cwd ?? this.ctx.sandboxPolicy.workspaceRoot), target.targetKey, target.displayPath);
+		return target;
+	}
+	/**
+	* 按 per-call 策略复核后写入。
+	* @param target - 工具解析出的目标。
+	* @param content - 新的完整内容。
+	* @param expected - 写入前版本守卫。
+	* @param signal - 取消信号。
+	* @param sandboxPolicy - per-call 策略；省略时用部署默认。
+	* @returns 上游写入结果。
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* 按 per-call 策略复核后编辑。
+	* @param target - 工具解析出的目标。
+	* @param edit - 字面量 search/replace 请求。
+	* @param expected - 版本守卫。
+	* @param signal - 取消信号。
+	* @param sandboxPolicy - per-call 策略；省略时用部署默认。
+	* @returns 上游编辑结果。
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/** `--` 条目命中即拒绝访问（读与写都拒）；抛 `FS_SANDBOX_DENIED`。 */
+	assertNotDenied(rules, canonicalTarget, displayPath) {
+		if (!isDenied(rules, canonicalTarget)) return;
+		throw new FsError(`cannot access "${displayPath}": file access denied by the configured "--" rules`, "FS_SANDBOX_DENIED");
+	}
+	/** `--` 或 `r-` 条目命中即拒绝写入，且优先于任何可写根。 */
+	assertWritable(rules, canonicalTarget, displayPath) {
+		this.assertNotDenied(rules, canonicalTarget, displayPath);
+		if (!isReadOnly(rules, canonicalTarget)) return;
+		throw new FsError(`cannot write "${displayPath}": path is read-only by the configured "r-" rule`, "FS_SANDBOX_DENIED");
+	}
+	/**
+	* 写前复核：`--` / `r-` 条目（任何模式）→ 模式本身的只读拒绝 → `workspace-write` 的
+	* `writableRoots + rw` containment，返回必须被写入的那个目标。
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const rules = this.rulesFor(policy.workspaceRoot);
+		this.assertWritable(rules, target.targetKey, target.displayPath);
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await super.resolve(target.displayPath);
+		this.assertWritable(rules, fresh.targetKey, fresh.displayPath);
+		for (const root of [...writableRoots(policy), ...rules.allowRoots]) if (await isPathUnder(fresh.targetKey, root)) return fresh;
+		throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+	}
+	/** 取（并按需编译缓存）某个工作区根下的规则。 */
+	rulesFor(workspaceRoot) {
+		const cached = this.compiled.get(workspaceRoot);
+		if (cached !== void 0) return cached;
+		const compiled = compileRules(this.source, workspaceRoot);
+		this.compiled.set(workspaceRoot, compiled);
+		return compiled;
+	}
+};
+//#endregion
+//#region src/sandbox.ts
+/**
+* 官方本机沙箱 provider 的可配置版本。
+* `read-only` 模式不追加 `rw` 条目（只读边界不因额外可写根放松）；`--` 条目在两种
+* confined 模式下都生效。
+*/
+var ConfigurableSandboxProvider = class extends LocalSandboxProvider {
+	source;
+	/** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
+	compiled = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.source = ruleSourceOf(config, process.env);
+	}
+	/**
+	* 官方拼装 + 规则追加。
+	* @param argv - 调用方即将 spawn 的 argv。
+	* @param policy - 本次调用的文件效果策略。
+	* @returns 追加规则后的 confined argv（空规则时与官方结果一致）。
+	*/
+	confine(argv, policy) {
+		const confined = super.confine(argv, policy);
+		const rules = this.rulesFor(policy.workspaceRoot);
+		const effective = policy.mode === "workspace-write" ? rules : withoutAllowRoots(rules);
+		if (isEmptyRules(effective)) return confined;
+		return {
+			...confined,
+			argv: extendConfinedArgv(confined.argv, effective)
+		};
+	}
+	/** 取（并按需编译缓存）某个工作区根下的规则。 */
+	rulesFor(workspaceRoot) {
+		const cached = this.compiled.get(workspaceRoot);
+		if (cached !== void 0) return cached;
+		const compiled = compileRules(this.source, workspaceRoot);
+		this.compiled.set(workspaceRoot, compiled);
+		return compiled;
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* 插件配置的单一真源：`access` 规则 + 透传官方的字段。
+*
+* 规则只在这里声明一次——provider 与 fs 后端按构造参数接收已解析的配置，
+* 不各自重复声明 schema；部署层的规则值随插入本行的 patch 写死（本部署见
+* `@morlay/dsh-preset`），包内不预设。
+* @module @morlay/dsh-sandbox-local/config
+*/
+/** 运行时配置 schema。 */
+const Config = z.object({
+	access: z.union([z.array(z.string()), z.string()]).default([]),
+	runnerCommand: z.array(z.string()).default([]),
+	runnerFailureSignatures: z.array(z.string()).default([]),
+	probeTimeoutMs: z.natural().default(5e3),
+	cwd: z.string().default(process.cwd()),
+	diffBasisMaxBytes: z.number().default(10485760)
+});
+//#endregion
+//#region src/index.ts
+/** Cordis 插件名。 */
+const name = "sandbox-local";
+/** fs 侧从策略服务取默认模式与工作区回退根，所以先等 `ctx.sandboxPolicy`。 */
+const inject = ["sandboxPolicy"];
+/**
+* 规则在进程沙箱侧的能力随平台方言变化，加载期把降级说清楚：
+* `ctx.fs` 侧（read / write / edit 工具）在 macOS / Linux / Windows 上语义一致，
+* 只有 bash 等子进程走平台 runner 的表达能力。
+*/
+function warnAboutDegradedRules(ctx, config) {
+	const rules = ruleSourceOf(config, process.env);
+	const grants = rules.allowWrite.length > 0;
+	const readOnly = rules.readOnly.length > 0;
+	const denials = rules.deny.length > 0;
+	if (!grants && !readOnly && !denials) return;
+	if (process.platform === "darwin") return;
+	if (readOnly || denials) {
+		const seatbelt = DIALECT_CAPABILITIES.seatbelt.denyReadWrite;
+		const bwrap = DIALECT_CAPABILITIES.bwrap.denyWriteOnly;
+		ctx.logger.warn(`sandbox-local: "r-" / "--" entries cannot be fully enforced for confined subprocesses on ${process.platform} (Seatbelt enforces both; bwrap binds the path read-only, so "--" degrades to write-only: ${bwrap}; Landlock and the Windows ACL runner cannot express a subpath rule at all: ${seatbelt} applies to Seatbelt only) — tools that read through ctx.fs stay covered`);
+	}
+	if (grants && process.platform === "win32") ctx.logger.warn("sandbox-local: \"rw\" entries cannot be granted to confined subprocesses on win32; ctx.fs covers the extra roots, the Windows ACL runner does not");
+}
+/**
+* 注册两个替换实现。
+* @param ctx - 插件上下文（官方 `sandbox` / `fs-sandbox` 行已禁用）。
+* @param config - 已由 schema 填好默认值的配置。
+*/
+function apply(ctx, config) {
+	warnAboutDegradedRules(ctx, config);
+	new ConfigurableSandboxProvider(ctx, config);
+	new ConfigurableFileSystem(ctx, config);
+}
+//#endregion
+export { Config, apply, inject, name };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@morlay/dsh-sandbox-local",
+  "version": "0.0.2",
+  "description": "Configurable sandbox bundle: replaces the shipped process-sandbox provider and filesystem fence with implementations that add extra writable roots and access denials on top of the upstream semantics.",
+  "keywords": [
+    "dsh",
+    "dsh-bundle",
+    "dsh-plugin",
+    "permission",
+    "sandbox"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/better-session.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "cordis.patch.yml",
+    "!**/__tests__"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs-sandbox": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs-sandbox": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown"
+  }
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+/**
+ * 插件配置的单一真源：`access` 规则 + 透传官方的字段。
+ *
+ * 规则只在这里声明一次——provider 与 fs 后端按构造参数接收已解析的配置，
+ * 不各自重复声明 schema；部署层的规则值随插入本行的 patch 写死（本部署见
+ * `@morlay/dsh-preset`），包内不预设。
+ * @module @morlay/dsh-sandbox-local/config
+ */
+
+import z from "@deepseek-ai/schemastery";
+import type { Config as UpstreamFsConfig } from "@deepseek-ai/dsh-fs-local";
+import type { Config as UpstreamSandboxConfig } from "@deepseek-ai/dsh-sandbox-local";
+
+/** 插件配置。 */
+export interface Config extends UpstreamSandboxConfig, UpstreamFsConfig {
+  /**
+   * 规则条目：`rw <path>`（额外可写根）、`r- <path>`（只读）、`-- <pattern>`（拒绝访问）。
+   * 数组每项一条，或写一段多行文本（每行一条）；`{{ env.NAME }}` 按进程环境展开。
+   */
+  access?: string | string[];
+}
+
+/** 运行时配置 schema。 */
+export const Config: z<Config> = z.object({
+  access: z.union([z.array(z.string()), z.string()]).default([]),
+  runnerCommand: z.array(z.string()).default([]),
+  runnerFailureSignatures: z.array(z.string()).default([]),
+  probeTimeoutMs: z.natural().default(5_000),
+  cwd: z.string().default(process.cwd()),
+  diffBasisMaxBytes: z.number().default(10 * 1024 * 1024),
+});