@morlay/dsh-sandbox-local 0.0.2

package/src/containment.ts

@@ -0,0 +1,72 @@
+/**
+ * 目标是否位于某个可写根之下的判定。
+ *
+ * 语义与上游 `@deepseek-ai/dsh-fs-sandbox/src/containment.ts` 对齐（canonical 拼写走
+ * 词法快路径，别名/大小写差异由文件系统身份兜底）；本包自带一份，是因为该模块只存在于
+ * 上游包的 `src/` 深处，而发布产物（`lib/`）与安装态 profile 的模块解析都不覆盖深路径。
+ * @module @morlay/dsh-sandbox-local/containment
+ */
+
+import type { BigIntStats } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname, sep } from "node:path";
+
+/** 视为“路径不存在”的错误码：只有它们能让祖先遍历继续。 */
+const MISSING_CODES: ReadonlySet<string> = new Set(["ENOENT", "ENOTDIR"]);
+
+/** stat 一次，缺失返回 undefined；其它失败（权限、I/O）继续抛出。 */
+async function statIfPresent(path: string): Promise<BigIntStats | undefined> {
+  try {
+    return await stat(path, { bigint: true });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== undefined && MISSING_CODES.has(code)) return undefined;
+    throw error;
+  }
+}
+
+/** 按大小写敏感性归一用于比较的拼写。 */
+function comparablePath(path: string, caseSensitive: boolean): string {
+  return caseSensitive ? path : path.toLowerCase();
+}
+
+/** 词法包含判定（目标可带尚不存在的后缀）。 */
+function isLexicallyUnder(path: string, root: string, caseSensitive: boolean): boolean {
+  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: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+/**
+ * 判断 canonical 目标是否就是某个根或位于其下。
+ * 拼写不同时（Windows 长名/8.3 别名、大小写差异）沿目标的现存祖先比较文件系统身份，
+ * 不把包含判定弱化成文本近似。
+ * @param path - 目标的 canonical 路径（可带尚不存在的尾部）。
+ * @param root - canonical 可写根。
+ * @param caseSensitive - 词法比较是否区分大小写；默认按宿主平台约定。
+ * @returns 目标是该根或其后代时为 true。
+ */
+export async function isPathUnder(
+  path: string,
+  root: string,
+  caseSensitive = process.platform !== "win32",
+): Promise<boolean> {
+  if (isLexicallyUnder(path, root, caseSensitive)) return true;
+  const rootInfo = await statIfPresent(root);
+  if (rootInfo === undefined) return false;
+  let ancestor = path;
+  for (;;) {
+    const ancestorInfo = await statIfPresent(ancestor);
+    if (ancestorInfo !== undefined && sameIdentity(ancestorInfo, rootInfo)) return true;
+    const parent = dirname(ancestor);
+    if (parent === ancestor) return false;
+    ancestor = parent;
+  }
+}

package/src/dialects.ts

@@ -0,0 +1,158 @@
+/**
+ * 在官方 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
+ */
+
+import { isEmptyRules, type CompiledRules } from "./rules.ts";
+
+/** 官方 provider 可选的执行方言。 */
+export type SandboxDialect = "seatbelt" | "bwrap" | "landlock" | "windows-acl";
+
+/** runner 部分与调用方 argv 的分隔符。 */
+const SEPARATOR = "--";
+
+/**
+ * 一个方言能表达的规则能力。
+ * `readOnly` 指 `r-` 条目（只拒写入）；`denyWriteOnly` 指 `--` 条目在该方言上只能
+ * 退化为“只拒写入”（读取仍放行）。
+ */
+export interface DialectCapabilities {
+  /** 能否把额外可写根写进 runner 参数。 */
+  readonly allowWrite: boolean;
+  /** 能否表达 `r-`（只拒写入）。 */
+  readonly readOnly: boolean;
+  /** 能否表达 `--` 的完整语义（读与写都拒）。 */
+  readonly denyReadWrite: boolean;
+  /** `--` 是否只能退化为拒绝写入。 */
+  readonly denyWriteOnly: boolean;
+}
+
+/** 各方言的规则表达能力——加载期据此告警，运行期据此决定是否改写参数。 */
+export const DIALECT_CAPABILITIES: Record<SandboxDialect, DialectCapabilities> = {
+  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: readonly string[]): number {
+  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）。
+ */
+export function dialectOf(argv: readonly string[]): SandboxDialect | undefined {
+  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";
+  return undefined;
+}
+
+/** SBPL 字符串字面量。 */
+function sbplString(value: string): string {
+  return `"${value.replaceAll("\\", String.raw`\\`).replaceAll('"', String.raw`\"`)}"`;
+}
+
+/**
+ * SBPL `#"…"` 的正则体：正则自身的 `\` 必须保留（glob 翻译用它转义元字符），
+ * 因此拒绝项里出现双引号时直接报错，而不是产出一个含义变化的 profile。
+ */
+function sbplRegexBody(source: string): string {
+  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: readonly string[], rules: CompiledRules): string[] {
+  const index = argv.indexOf("-p");
+  const profile = index === -1 ? undefined : argv[index + 1];
+  if (profile === undefined) {
+    throw new Error("sandbox rules: the Seatbelt runner argv carries no `-p` profile to extend");
+  }
+  const additions = [
+    ...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)}"))`,
+    ),
+  ];
+  const extended = `${profile} ${additions.join(" ")}`;
+  return [...argv.slice(0, index + 1), extended, ...argv.slice(index + 2)];
+}
+
+/**
+ * bwrap：额外可写根用 `--bind-try`（路径不存在时跳过）；`r-` 与 `--` 都用
+ * `--ro-bind-try` 覆盖成只读（挂载后行覆盖前行）——也就是说 `--` 在 bwrap 上退化为
+ * “只拒写入”。glob 模式无法表达为静态挂载，由调用方在加载期告警。
+ */
+function extendBwrap(argv: readonly string[], rules: CompiledRules): string[] {
+  const separator = separatorIndex(argv);
+  const additions: string[] = [];
+  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: readonly string[], rules: CompiledRules): string[] {
+  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；方言无法识别时抛错（规则不能静默失效）。
+ */
+export function extendConfinedArgv(argv: readonly string[], rules: CompiledRules): string[] {
+  if (isEmptyRules(rules)) return [...argv];
+  const dialect = dialectOf(argv);
+  if (dialect === undefined) {
+    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":
+      // windows-acl 的 runner 参数没有承载额外 grant 的入口：加载期已告警，这里保持原 argv。
+      return [...argv];
+  }
+}

package/src/fs.ts

@@ -0,0 +1,190 @@
+/**
+ * 文件系统围栏：继承官方 `@deepseek-ai/dsh-fs-local` 的文本存储机制
+ * （resolve / stat / 读流 / 原子写 / read-match-write 编辑），在访问入口叠加规则：
+ * `--` 命中即拒绝访问（读与写都拒，任何模式下都生效），`r-` 只拒写入，`rw` 参与
+ * `workspace-write` 的可写判定（官方 `writableRoots` 之外的额外可写根）。
+ *
+ * 与它替换掉的官方 `@deepseek-ai/dsh-fs-sandbox` 一样，这是受信代码里的策略检查，
+ * 不是内核边界：内核级隔离仍由 `ctx.sandbox` 侧负责。
+ * @module @morlay/dsh-sandbox-local/fs
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import type {
+  FsEditOutcome,
+  FsEditRequest,
+  FsTarget,
+  FsVersion,
+  FsWriteIntent,
+  FsWriteOutcome,
+} from "@deepseek-ai/dsh-fs";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import type { Config } from "./config.ts";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+import type { SandboxExecutionPolicy, SandboxMode } from "@deepseek-ai/dsh-sandbox";
+import type {} from "@deepseek-ai/dsh-sandbox-policy";
+import { isPathUnder } from "./containment.ts";
+import {
+  compileRules,
+  isDenied,
+  isReadOnly,
+  ruleSourceOf,
+  type CompiledRules,
+  type RuleSource,
+} from "./rules.ts";
+
+/**
+ * 官方本机文件系统后端的可配置版本。
+ * `--` 条目在解析阶段拒绝目标（覆盖 read / write / edit / list 等一切工具入口），
+ * `r-` 与 `--` 条目在写入前拒绝写入（优先于任何可写根），写操作再按
+ * `workspace-write` + `rw` 条目复核 containment。
+ */
+export class ConfigurableFileSystem extends LocalFileSystem {
+  static inject = ["sandboxPolicy"];
+
+  private readonly defaultMode: SandboxMode;
+  private readonly source: RuleSource;
+  /** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
+  private readonly compiled = new Map<string, CompiledRules>();
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, config);
+    this.defaultMode = ctx.sandboxPolicy.defaultMode;
+    this.source = ruleSourceOf(config, process.env);
+  }
+
+  /** 工具层读它判断后端是否 confine（并据此广告 escalation 字段）。 */
+  override get sandboxMode(): SandboxMode {
+    return this.defaultMode;
+  }
+
+  /**
+   * 解析目标后立即执行拒绝判定：工具入口（read / write / edit / list）都先经过
+   * `resolve`，因此一次判定即可覆盖读与写。
+   * @param path - 待解析的路径。
+   * @param opts - cwd 与取消信号；cwd 同时是相对规则的解析根。
+   * @returns 解析后的目标。
+   */
+  override async resolve(
+    path: string,
+    opts?: { cwd?: string; signal?: AbortSignal },
+  ): Promise<FsTarget> {
+    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 上游写入结果。
+   */
+  override async writeText(
+    target: FsTarget,
+    content: string,
+    expected?: FsWriteIntent,
+    signal?: AbortSignal,
+    sandboxPolicy?: SandboxExecutionPolicy,
+  ): Promise<FsWriteOutcome> {
+    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 上游编辑结果。
+   */
+  override async editText(
+    target: FsTarget,
+    edit: FsEditRequest,
+    expected?: { version: FsVersion },
+    signal?: AbortSignal,
+    sandboxPolicy?: SandboxExecutionPolicy,
+  ): Promise<FsEditOutcome> {
+    return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+  }
+
+  /** `--` 条目命中即拒绝访问（读与写都拒）；抛 `FS_SANDBOX_DENIED`。 */
+  private assertNotDenied(
+    rules: CompiledRules,
+    canonicalTarget: string,
+    displayPath: string,
+  ): void {
+    if (!isDenied(rules, canonicalTarget)) return;
+    throw new FsError(
+      `cannot access "${displayPath}": file access denied by the configured "--" rules`,
+      "FS_SANDBOX_DENIED",
+    );
+  }
+
+  /** `--` 或 `r-` 条目命中即拒绝写入，且优先于任何可写根。 */
+  private assertWritable(rules: CompiledRules, canonicalTarget: string, displayPath: string): void {
+    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，返回必须被写入的那个目标。
+   */
+  private async checkedTarget(
+    target: FsTarget,
+    sandboxPolicy?: SandboxExecutionPolicy,
+  ): Promise<FsTarget> {
+    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",
+      );
+    }
+    // workspace-write：在新鲜解析出的 canonical 目标上复核，写入也用它（避免
+    // “检查这里、写那里”的 TOCTOU 窗口）。
+    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",
+    );
+  }
+
+  /** 取（并按需编译缓存）某个工作区根下的规则。 */
+  private rulesFor(workspaceRoot: string): CompiledRules {
+    const cached = this.compiled.get(workspaceRoot);
+    if (cached !== undefined) return cached;
+    const compiled = compileRules(this.source, workspaceRoot);
+    this.compiled.set(workspaceRoot, compiled);
+    return compiled;
+  }
+}
+
+export default ConfigurableFileSystem;

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * 可配置沙箱插件：替换官方进程沙箱 provider（`ctx.sandbox`）与文件系统后端（`ctx.fs`），
+ * 在官方语义之上叠加 `access` 规则。
+ *
+ * 每条规则以 `rw ` / `r- ` / `-- ` 开头：`rw <path>` 是工作区与平台临时目录之外的额外
+ * 可写根，`r- <path>` 是只读（读放行、写拒绝），`-- <pattern>` 是访问拒绝（读 + 写）。
+ * 三条都支持 `{{ env.NAME }}`（加载期展开，引用未定义的环境变量直接失败）与相对工作区的
+ * 路径；命中优先级是 `--` > `r-` > 可写根。`ctx.fs` 侧语义完整，`ctx.sandbox` 侧在能表达
+ * 该语义的方言上生效（见 {@link DIALECT_CAPABILITIES}）。
+ *
+ * 装配前提：官方 `sandbox` 与 `fs-sandbox` 行必须被禁用（包内 `cordis.patch.yml` 或
+ * 部署层 patch），否则同名服务 fail loud；规则由部署层在插入本行时写死
+ * （本部署见 `@morlay/dsh-preset`），包内不预设。
+ * @module @morlay/dsh-sandbox-local
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { Config } from "./config.ts";
+import { DIALECT_CAPABILITIES } from "./dialects.ts";
+import { ConfigurableFileSystem } from "./fs.ts";
+import { ruleSourceOf } from "./rules.ts";
+import { ConfigurableSandboxProvider } from "./sandbox.ts";
+
+// 值与类型一起转出：Loader 读 `Config`（schema），消费方读类型。
+export { Config } from "./config.ts";
+
+/** Cordis 插件名。 */
+export const name = "sandbox-local";
+
+/** fs 侧从策略服务取默认模式与工作区回退根，所以先等 `ctx.sandboxPolicy`。 */
+export const inject = ["sandboxPolicy"];
+
+/**
+ * 规则在进程沙箱侧的能力随平台方言变化，加载期把降级说清楚：
+ * `ctx.fs` 侧（read / write / edit 工具）在 macOS / Linux / Windows 上语义一致，
+ * 只有 bash 等子进程走平台 runner 的表达能力。
+ */
+function warnAboutDegradedRules(ctx: Context, config: Config): void {
+  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 填好默认值的配置。
+ */
+export function apply(ctx: Context, config: Config): void {
+  warnAboutDegradedRules(ctx, config);
+  new ConfigurableSandboxProvider(ctx, config);
+  new ConfigurableFileSystem(ctx, config);
+}