@deepseek-ai/dsh-pwsh-sandbox 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/pwsh-sandbox/README.md
-README.md: cddcce511d01f3c10208304ea55bf6156ccf2429
-README.zh.md: 40aa055770e526cc41607f0e4cd63273b80ebc15
+README.md: 8d75347efa49ff2697bab7a3fd5b6195faf6685f
+README.zh.md: 295d60d9a63d4f039e49e52385561e51194bd25e

package/README.md

@@ -35,7 +35,7 @@ Choose it when a deployment needs file-level confinement for PowerShell commands
 
 | Mode | File effects |
 |---|---|
-| `read-only` (default) | Writes are denied; the boundary stays partial because the restricted token retains Everyone |
+| `read-only` (default) | Writes are denied; the boundary stays partial for the shared hard-link, unconfined-read, and AppContainer-ACL limits |
 | `workspace-write` | Writes under the policy's workspace root plus a private temp directory; `TMP`/`TEMP` are rewritten to it before spawning |
 | `danger-full-access` | No confinement; the provider is never consulted, and results carry `sandbox: { mode, denied: false }` |
 
@@ -75,20 +75,20 @@ This section explains the design of the executor and points at the code that rea
 
 ### Design concept
 
-The executor is the pwsh twin of `dsh-bash-sandbox`: it inherits `dsh-pwsh-local`'s process mechanics, consumes its argv-level seam (`argv()`/`runArgv()`/`startArgv()`/`onProcessDone()`), and awaits confinement of the exact pwsh invocation through `ctx.sandbox.confine()` before spawning. Foreground preparation uses the local executor’s shared command deadline; timeout before spawn carries no enforcement claim. Background preparation follows only the caller signal. Both paths recheck cancellation before spawn. The confinement substance is platform-neutral — the sandbox seam resolves to the platform's runner — while this package owns the pwsh side only: the selected mode, enforcement completeness, and denial classification on results.
+The executor is the pwsh twin of `dsh-bash-sandbox`: it inherits `dsh-pwsh-local`'s process mechanics, consumes its argv-level seam (`argv()`/`executeArgv()`/`onProcessDone()`), and wraps the exact pwsh invocation through `ctx.sandbox.confine()` before spawning. The confinement substance is platform-neutral — the sandbox seam resolves to the platform's runner — while this package owns the pwsh side only: the selected mode, enforcement completeness, and denial classification on results.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxPwshExecutor`, per-process fact retention, run/start wrapping |
+| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxPwshExecutor`, per-process fact retention, execution preparation |
 | [`src/helpers.ts`](src/helpers.ts) | Denial, runner-failure, and runner-spawn-failure classification |
 | — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seams. Classification is observable in results. |
 | `tests/` | Exercised behavior across the ACL and platform runners |
 
 ### Main flow
 
-For a confined mode, `resolve()` stamps the per-call policy; `run` and `start` wrap the pwsh argv through the provider and hand the confined argv to the inherited subprocess path. At settlement the executor classifies the outcome: a runner failure outranks a denial because the command never ran, a failed run whose stderr carries the runner's denial dialect is reported `denied: true`, and every confined run carries its mode and enforcement facts. `danger-full-access` bypasses the provider entirely and stamps `denied: false`.
+For a confined mode, `resolve()` stamps the per-call policy; `execute` awaits preparation of the pwsh argv through the provider and hands the confined argv to the inherited subprocess path. At settlement the executor classifies the outcome: a runner failure outranks a denial because the command never ran, a failed run whose stderr carries the runner's denial dialect is reported `denied: true`, and every confined run carries its mode and enforcement facts. `danger-full-access` bypasses the provider entirely and stamps `denied: false`.
 
 ### Invariants
 
@@ -140,7 +140,7 @@ These limits define when this executor is only a partial boundary on Windows. Th
 
 - **Reads are unrestricted on Windows** — the ACL runner restricts writes only; the read boundary is documented in `@deepseek-ai/dsh-sandbox-windows-acl`.
 - **Windows workspace-write temp authority is private** — per live session/workspace pair; agentless calls receive a fresh private directory per invocation; the ambient temp root is never granted, and the runner rewrites `TMP`/`TEMP` to the private directory before spawning.
-- **Windows read-only grants no explicit writable root but remains partial** — the restricted token must retain Everyone; objects whose DACL grants Everyone write access — including compatible opens of the NUL device — remain ambient authority, while PowerShell's `> $null` redirection still works without opening NUL.
+- **Windows read-only grants no explicit writable root but remains partial** — NTFS hard links alias one file object across paths, reads stay unconfined, and a tree another AppContainer tool has ACL'd with a package SID is unreadable to the Low-integrity child. NUL stays writable in both modes because the device DACL grants Everyone write and carries no higher label; PowerShell's `> $null` redirection still works without opening it.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -35,7 +35,7 @@ kind: "package-reference"
 
 | 模式 | 文件影响 |
 |---|---|
-| `read-only`（默认） | 写入被拒绝；由于受限令牌必须保留 Everyone，边界仍是不完整的 |
+| `read-only`（默认） | 写入被拒绝；边界仍受共享的硬链接、读取不受限与 AppContainer ACL 限制 |
 | `workspace-write` | 只能写入策略的工作区根目录加一个私有临时目录；spawn 前 `TMP`/`TEMP` 会被重写到该目录 |
 | `danger-full-access` | 不作限制；绝不咨询提供方，结果携带 `sandbox: { mode, denied: false }` |
 
@@ -75,20 +75,20 @@ kind: "package-reference"
 
 ### 设计概念
 
-本执行器是 `dsh-bash-sandbox` 的 pwsh 孪生：它继承 `dsh-pwsh-local` 的进程机制，消费其 argv 级 seam（`argv()`/`runArgv()`/`startArgv()`/`onProcessDone()`），并在 spawn 前通过 `ctx.sandbox.confine()` 等待精确的 pwsh 调用完成限制准备。前台准备使用本地执行器与命令共享的 deadline；在 spawn 前超时不会声明 enforcement 事实。后台准备只跟随调用方信号。两条路径都在 spawn 前重新检查取消状态。隔离实体本身是平台无关的——沙箱 seam 解析到平台的 runner——而本包只负责 pwsh 侧：所选模式、强制执行完整度，以及结果上的拒绝分类。
+本执行器是 `dsh-bash-sandbox` 的 pwsh 孪生：它继承 `dsh-pwsh-local` 的进程机制，消费其 argv 级 seam（`argv()`/`executeArgv()`/`onProcessDone()`），并在 spawn 前把精确的 pwsh 调用经 `ctx.sandbox.confine()` 包装。隔离实体本身是平台无关的——沙箱 seam 解析到平台的 runner——而本包只负责 pwsh 侧：所选模式、强制执行完整度，以及结果上的拒绝分类。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxPwshExecutor`、按进程保留事实、run/start 包装 |
+| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxPwshExecutor`、按进程保留事实、执行准备 |
 | [`src/helpers.ts`](src/helpers.ts) | 拒绝、runner 失败与 runner spawn 失败分类 |
 | — | 不发布运行时不变式伴生入口；除所属 seam 所执行的约定外，本包不暴露独立事件序列或可变数据关系；分类可在结果中观察。 |
 | `tests/` | 跨 ACL 与平台 runner 演练的行为 |
 
 ### 主要流程
 
-对受限模式，`resolve()` 标记每次调用的策略；`run` 与 `start` 把 pwsh argv 经提供方包装，再把受限 argv 交给继承的子进程路径。结算时执行器对结果分类：runner 失败优先于拒绝（命令从未运行），stderr 携带 runner 拒绝方言的失败运行报告 `denied: true`，每次受限运行都携带模式与强制执行事实。`danger-full-access` 完全绕过提供方，并标记 `denied: false`。
+对受限模式，`resolve()` 标记每次调用的策略；`execute` 把 pwsh argv 经提供方包装，再把受限 argv 交给继承的子进程路径。结算时执行器对结果分类：runner 失败优先于拒绝（命令从未运行），stderr 携带 runner 拒绝方言的失败运行报告 `denied: true`，每次受限运行都携带模式与强制执行事实。`danger-full-access` 完全绕过提供方，并标记 `denied: false`。
 
 ### 不变式
 
@@ -140,7 +140,7 @@ kind: "package-reference"
 
 - **Windows 上读不受限**——ACL runner 只限写；读边界文档在 `@deepseek-ai/dsh-sandbox-windows-acl`。
 - **Windows workspace-write 的临时权限按每个活跃的会话/工作区对私有**——无 agent（智能体）的调用每次都获得一个新的私有目录；环境临时根目录绝不会被授权，runner 会在 spawn 前将 `TMP`/`TEMP` 重写为该私有目录。
-- **Windows read-only 不授予任何显式可写根目录，但仍为部分强制执行**——受限令牌必须保留 Everyone；DACL 向 Everyone 授予写访问的对象——包括以兼容方式打开的 NUL 设备——仍构成环境权限来源，而 PowerShell 的 `> $null` 重定向仍可工作，且不会打开 NUL。
+- **Windows read-only 不授予任何显式可写根目录，但仍为部分强制执行**——NTFS 硬链接会把同一文件对象别名为多个路径、读取仍不受限，且被其他 AppContainer 工具以包 SID 标记过的目录树对 Low 完整性子进程不可读。NUL 在两种模式下仍可写，因为设备 DACL 向 Everyone 授予写权限且不带更高的标签；PowerShell 的 `> $null` 重定向仍然工作，且不会打开 NUL。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -115,7 +115,7 @@ function matchesSignature(exitCode, stderr, signatures) {
 * `result.sandbox` reports the mode, enforcement, and denial facts the tool
 * renders.
 */
-var SandboxPwshExecutor = class extends PwshLocalExecutor {
+var SandboxPwshExecutor = class SandboxPwshExecutor extends PwshLocalExecutor {
 	static inject = [
 		"subprocess",
 		"sandbox",
@@ -148,79 +148,74 @@ var SandboxPwshExecutor = class extends PwshLocalExecutor {
 			sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
 		};
 	}
-	async run(spec) {
+	async execute(spec) {
 		const policy = spec.sandboxPolicy;
 		const { mode } = policy;
-		if (mode === "danger-full-access") return {
-			...await super.run(spec),
+		if (mode === "danger-full-access") return SandboxPwshExecutor.decorateResult(await super.execute(spec), (result) => ({
+			...result,
 			sandbox: {
 				mode,
 				denied: false
 			}
-		};
+		}));
 		let confined;
-		let result;
-		let spawnRequested;
-		try {
-			({result, spawnRequested} = await this.runArgv(spec, async (signal) => {
-				const prepared = await this.confine(spec, {
-					...policy,
-					mode
-				}, signal);
-				signal.throwIfAborted();
-				confined = prepared;
-				return prepared.argv;
-			}));
-		} catch (error) {
+		const ex = await this.executeArgv(spec, async (signal) => {
+			const prepared = await this.confine(spec, {
+				...policy,
+				mode
+			}, signal);
+			signal.throwIfAborted();
+			confined = prepared;
+			return prepared.argv;
+		}, (process) => {
+			const facts = confined;
+			this.processFacts.set(process, {
+				mode,
+				enforcement: facts.enforcement,
+				denialSignatures: facts.denialSignatures,
+				runnerFailureRules: facts.runnerFailureRules,
+				runnerProgram: facts.argv[0],
+				workdir: spec.workdir
+			});
+		});
+		return SandboxPwshExecutor.decorateResult(ex, (result) => {
+			if (confined === void 0) return {
+				...result,
+				sandbox: {
+					mode,
+					denied: false
+				}
+			};
+			const { enforcement, denialSignatures, runnerFailureRules } = confined;
+			const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
+			if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
+			return {
+				...result,
+				sandbox: {
+					mode,
+					denied: classifyDenial(result, denialSignatures),
+					enforcement
+				}
+			};
+		}, (error) => {
 			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
 			if (confined !== void 0 && isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
 			throw error;
-		}
-		if (!spawnRequested) return {
-			...result,
-			sandbox: {
-				mode,
-				denied: false
-			}
-		};
-		const facts = confined;
-		const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, facts.runnerFailureRules);
-		if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
-		return {
-			...result,
-			sandbox: {
-				mode,
-				denied: classifyDenial(result, facts.denialSignatures),
-				enforcement: facts.enforcement
-			}
-		};
-	}
-	async start(spec) {
-		const policy = spec.sandboxPolicy;
-		const { mode } = policy;
-		if (mode === "danger-full-access") return super.start(spec);
-		const confined = await this.confine(spec, {
-			...policy,
-			mode
-		}, spec.signal);
-		spec.signal?.throwIfAborted();
-		let proc;
-		try {
-			proc = this.startArgv(spec, confined.argv);
-		} catch (error) {
-			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
-			throw error;
-		}
-		const { enforcement, denialSignatures, runnerFailureRules } = confined;
-		this.processFacts.set(proc, {
-			mode,
-			enforcement,
-			denialSignatures,
-			runnerFailureRules,
-			runnerProgram: confined.argv[0],
-			workdir: spec.workdir
 		});
-		return proc;
+	}
+	/**
+	* Decorate the handle's foreground projection in place, memoized once. The
+	* handle keeps its identity (never wrapped in a second object) because the
+	* per-process facts and `onProcessDone` key on the exact instance.
+	*/
+	static decorateResult(ex, map, mapError) {
+		const base = ex.result.bind(ex);
+		let decorated;
+		ex.result = () => {
+			decorated ??= base().then(map, mapError);
+			return decorated;
+		};
+		return ex;
 	}
 	/**
 	* Stamp per-process sandbox facts before `done` settles. Full-access

package/lib/types/index.d.ts

@@ -12,7 +12,7 @@
  * @module @deepseek-ai/dsh-pwsh-sandbox
  */
 import { Context } from '@deepseek-ai/cordis';
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell';
+import type { ShellExecRequest, ShellExecSpec, ShellExecution, ShellProcess } from '@deepseek-ai/dsh-shell';
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
 import { PwshLocalExecutor } from '@deepseek-ai/dsh-pwsh-local';
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-pwsh-local';
@@ -53,8 +53,13 @@ export declare class SandboxPwshExecutor extends PwshLocalExecutor {
      * the deployment policy.
      */
     resolve(request: ShellExecRequest): ShellExecSpec;
-    run(spec: ShellExecSpec): Promise<ShellRunResult>;
-    start(spec: ShellExecSpec): Promise<ShellProcess>;
+    execute(spec: ShellExecSpec): Promise<ShellExecution>;
+    /**
+     * Decorate the handle's foreground projection in place, memoized once. The
+     * handle keeps its identity (never wrapped in a second object) because the
+     * per-process facts and `onProcessDone` key on the exact instance.
+     */
+    private static decorateResult;
     /**
      * Stamp per-process sandbox facts before `done` settles. Full-access
      * processes have no facts; signal deaths are not denials.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-pwsh-sandbox",
   "description": "Sandbox-consuming implementation of the DeepSeek Harness PowerShell executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,20 +27,20 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-pwsh-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-pwsh-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-pwsh-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-pwsh-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }