@deepseek-ai/dsh-sandbox-windows-acl 0.1.5-rc.2 → 0.1.6-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/sandbox/sandbox-windows-acl/README.md
-README.md: c86c66395ce326293f93a5573e36b09eeff362d5
-README.zh.md: 0aaa7f52e26410e40c9930a7d34e8126dfe76bb4
+README.md: 30eaea27b9f8a0ebd1691348c9e6f87706891866
+README.zh.md: eeb65e5db1044eb75e0c13c5f3c76667432dc485

package/README.md

@@ -107,6 +107,8 @@ node runner.js --workspace <dir> --temp <dir> --mode <read-only|workspace-write>
 
 The seam materializes the deterministic workspace SID's ACE standing (once per workspace per server lifetime — the reuse cache), then creates a random private temp directory and a distinct revocable SID for each live session/workspace pair, passing both as the required `--write-sid`/`--temp-write-sid` pair; the runner verifies each against its owning path and neither grants nor revokes (`manageDacls: false`). A fork receives a different temp capability, and a fresh provider gives even the same resumed session a new path and SID, so crash residue is inert litter. Without the pair, `--temp` names a root: an agentless workspace-write runner creates a random private child, self-manages its temp SID, rewrites TMP/TEMP, and removes the child on exit. Re-granting the standing workspace ACE after a restart is idempotent: `grantWrite` reads the current DACL and skips the re-propagation when the exact ACE already stands. A workspace equal to or containing the temp root is rejected before any grant.
 
+When launched with the subprocess control marker, the runner forwards fd 7 through the restricted child's CRT startup table and closes its own copy immediately after spawn. The optional `controlFileDescriptor: 7` input requires `stdio: 'inherit'`; requesting it with piped stdio fails before process creation.
+
 ### Verified boundaries
 
 - **Everyone grants remain ambient write authority** — Everyone must stay in both restricting lists (removing it breaks early DLL initialization and CNG); an external NTFS object whose DACL grants Everyone a requested write right clears both checks and stays writable under both modes.

package/README.zh.md

@@ -63,7 +63,7 @@ sandbox.dispose() // revokes the revocable (temp) grant, keeps the standing work
 rmSync(tempDir, { recursive: true, force: true })
 ```
 
-工作区 ACE 以常驻方式授予——`dispose()` 保留它们，因为它们是跨实例的复用缓存——而不同的临时 SID 以可回收方式授予。服务端对应物是 `AclWriteGrant` 类：每个目录一次 `add(path, standing)`，`dispose()` 撤销可回收路径并释放 SID。
+工作区 ACE 以常驻方式授予——`dispose()` 保留它们，因为它们是跨实例的复用缓存——而不同的临时 SID 以可回收方式授予。服务端对应实现是 `AclWriteGrant` 类：每个目录一次 `add(path, standing)`，`dispose()` 撤销可回收路径并释放 SID。
 
 ### 隔离给你带来什么
 
@@ -107,6 +107,8 @@ node runner.js --workspace <dir> --temp <dir> --mode <read-only|workspace-write>
 
 seam 先把确定性工作区 SID 的 ACE 常驻物化（每个工作区每服务器生命周期一次——复用缓存），再为每个活跃的会话/工作区对创建随机私有临时目录和不同的可回收 SID，把两种身份作为必须成对出现的 `--write-sid`/`--temp-write-sid` 传入；runner 对照各自所属路径验证二者，既不授权也不撤销（`manageDacls: false`）。fork 获得不同的临时能力；即使恢复的是同一会话，新的提供方也会给出新的路径和 SID，因此崩溃残留只是失效垃圾。如果不带这一对标志，`--temp` 指定的是根目录：无 agent（智能体）/独立的 workspace-write runner 会创建随机私有子目录，自行管理其临时 SID，重写 TMP/TEMP，并在退出时移除该子目录。重启后重新授权常驻工作区 ACE 是幂等的：`grantWrite` 读取当前 DACL，当完全相同的 ACE 已存在时跳过重新传播。工作区若等于或包含临时根目录，会在任何授权前被拒绝。
 
+启动时若带有 subprocess 控制标记，runner 会通过受限子进程的 CRT 启动表转发 fd 7，并在 spawn 后立即关闭自身副本。可选的 `controlFileDescriptor: 7` 输入要求 `stdio: 'inherit'`；在管道 stdio 下请求它会在进程创建前失败。
+
 ### 已验证边界
 
 - **Everyone 授权仍是环境中的写权限来源。** Everyone 必须保留在两种 restricting 列表中（移除它会破坏早期 DLL 初始化与 CNG）；外部 NTFS 对象若其 DACL 向 Everyone 授予所请求的写权限，就会同时通过两次检查，并在两种模式下保持可写。
@@ -119,13 +121,13 @@ seam 先把确定性工作区 SID 的 ACE 常驻物化（每个工作区每服
 - **受限子进程的临时能力按每个活跃的会话/工作区对私有。** runner 在 spawn 之前把 TMP/TEMP 改写为该私有目录；共享同一工作区 SID 的两个令牌无法写入彼此的临时目录。
 - **受限令牌下 `whoami` 与令牌检查 cmdlet 会失败。** 子进程对复制令牌的 `GetTokenInformation` 部分不可用，这是诊断噪音而非运行故障。
 
-### 头部验证与源码地图
+### 头文件验证与源码索引
 
 沙箱拥有的 SID、ACL、令牌、文件与锁声明由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 Windows 头文件检查。共享进程、stdio 与 Job ABI 由 [`@deepseek-ai/dsh-win32-process`](../../subprocess/win32-process/README.zh.md#header-verification) 归属并验证。
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | `AclSandbox`：受限令牌策略、DACL 授权、故障关闭的 spawn 与 dispose |
+| [`src/index.ts`](src/index.ts) | `AclSandbox`：受限令牌策略、DACL 授权、fail-closed 的 spawn 与 dispose |
 | [`src/runner.ts`](src/runner.ts) | 基于共享 Win32 进程原语的 runner 入口 |
 | [`src/grant.ts`](src/grant.ts) | `AclWriteGrant`：服务端授权物化与撤销 |
 | [`src/token.ts`](src/token.ts) + [`src/acl.ts`](src/acl.ts) | 沙箱背后的 Win32 令牌与 DACL 原语 |

package/lib/index.js

@@ -1,2 +1,2 @@
-import { a as assertTempRootOutsideWorkspace, i as AclWriteGrant, n as tempWriteSid, r as workspaceWriteSid, t as AclSandbox } from "./types-DuU3lSVe.js";
+import { a as assertTempRootOutsideWorkspace, i as AclWriteGrant, n as tempWriteSid, r as workspaceWriteSid, t as AclSandbox } from "./types-CutH1Lgc.js";
 export { AclSandbox, AclWriteGrant, assertTempRootOutsideWorkspace, tempWriteSid, workspaceWriteSid };

package/lib/runner.js

@@ -1,6 +1,7 @@
-import { a as assertTempRootOutsideWorkspace, n as tempWriteSid, o as win32, r as workspaceWriteSid, t as AclSandbox } from "./types-DuU3lSVe.js";
-import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { a as assertTempRootOutsideWorkspace, n as tempWriteSid, o as win32, r as workspaceWriteSid, t as AclSandbox } from "./types-CutH1Lgc.js";
+import { closeSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { SUBPROCESS_CONTROL_ENV, SUBPROCESS_CONTROL_FD } from "@deepseek-ai/dsh-subprocess/control";
 //#region lib/types/runner.js
 /**
 * The windows-acl confinement runner: the argv-prefix wrapper the sandbox
@@ -153,11 +154,14 @@ async function main() {
 			if (api.setEnvironmentVariableW("TMP", privateTempDir) === 0) fail(`SetEnvironmentVariableW TMP failed (Win32 ${api.getLastError()})`);
 			if (api.setEnvironmentVariableW("TEMP", privateTempDir) === 0) fail(`SetEnvironmentVariableW TEMP failed (Win32 ${api.getLastError()})`);
 		}
-		return (await sandbox.spawn({
+		const child = sandbox.spawn({
 			command: parsed.command,
 			args: parsed.args,
-			stdio: "inherit"
-		}).wait()).exitCode;
+			stdio: "inherit",
+			...process.env[SUBPROCESS_CONTROL_ENV] === "pipe" ? { controlFileDescriptor: SUBPROCESS_CONTROL_FD } : {}
+		});
+		if (process.env[SUBPROCESS_CONTROL_ENV] === "pipe") closeSync(SUBPROCESS_CONTROL_FD);
+		return (await child.wait()).exitCode;
 	} finally {
 		if (initialized) try {
 			sandbox?.dispose();

package/lib/types/index.d.ts

@@ -98,6 +98,8 @@ export interface AclSandboxSpawnOptions {
      * child dies with the caller; stdout/stderr in the result are empty.
      */
     stdio?: 'pipe' | 'inherit';
+    /** Control pipe forwarded to the same payload descriptor in inherited-stdio mode. */
+    controlFileDescriptor?: 7;
 }
 /** A settled confined child: captured stdio and the exit code. */
 export interface AclSandboxChildResult {

package/lib/types/spawn.d.ts

@@ -31,6 +31,7 @@ export declare function spawnSandboxedInherited(api: Win32Bindings, token: Nativ
     command: string;
     args: readonly string[];
     cwd: string;
+    controlFileDescriptor?: 7;
 }): SpawnedInherited;
 /**
  * Wait for a restricted child and close its process handle.

package/lib/{types-DuU3lSVe.js → types-CutH1Lgc.js}

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ERROR_INSUFFICIENT_BUFFER, Win32Error, allocPtrSlot, allocUint32, decodePtr, decodeUint32, drainPipe, extendWin32ProcessBindings, isNullPtr, isNullPtr as isNullPtr$1, spawnInheritedJobProcess, spawnPipedProcess, throwLastError, throwLastError as throwLastError$1, throwWin32, waitForProcessExit } from "@deepseek-ai/dsh-win32-process";
 import { createHash } from "node:crypto";
-import koffi from "koffi";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 //#region lib/types/win32-abi.js
 /** ACL/token-specific Win32 constants. */
 /** OpenProcess access required to query the current process token. */
@@ -20,8 +20,17 @@ const FILE_ALL_ACCESS = 2032127;
 //#endregion
 //#region lib/types/ffi.js
 /** ACL/token bindings layered on the shared Win32 process owner. */
-const PVOID = koffi.pointer("void");
-const PPVOID = koffi.pointer(PVOID);
+const requireKoffi = createLazyRequire("koffi", import.meta.url);
+let cachedTypes;
+function ffiTypes() {
+	if (cachedTypes !== void 0) return cachedTypes;
+	const koffi = requireKoffi();
+	const PVOID = koffi.pointer("void");
+	return cachedTypes = {
+		PVOID,
+		PPVOID: koffi.pointer(PVOID)
+	};
+}
 /**
 * Return whether CreateFileW produced INVALID_HANDLE_VALUE.
 * @param handle - handle returned by CreateFileW.
@@ -37,7 +46,7 @@ function isInvalidHandle(handle) {
 * @param value - unsigned value to store.
 */
 function encodeUint32(slot, value) {
-	koffi.encode(slot, "uint32", value);
+	requireKoffi().encode(slot, "uint32", value);
 }
 /**
 * Return a Koffi pointer's numeric address for struct packing.
@@ -45,7 +54,7 @@ function encodeUint32(slot, value) {
 * @returns pointer address.
 */
 function ptrAddress(ptr) {
-	return koffi.address(ptr);
+	return requireKoffi().address(ptr);
 }
 /**
 * Allocate a raw byte block.
@@ -53,7 +62,7 @@ function ptrAddress(ptr) {
 * @returns allocated pointer.
 */
 function allocBytes(length) {
-	return koffi.alloc("uint8", length);
+	return requireKoffi().alloc("uint8", length);
 }
 /**
 * Allocate one zeroed x64 OVERLAPPED record.
@@ -71,7 +80,7 @@ function allocOverlapped() {
 * @returns decoded pointer, or null for address zero.
 */
 function decodePtrAt(buffer, offset) {
-	const value = koffi.decode(buffer, offset, PVOID);
+	const value = requireKoffi().decode(buffer, offset, ffiTypes().PVOID);
 	return isNullPtr(value) ? null : value;
 }
 /**
@@ -81,7 +90,7 @@ function decodePtrAt(buffer, offset) {
 * @returns decoded value.
 */
 function decodeUint8At(ptr, offset) {
-	return koffi.decode(ptr, offset, "uint8");
+	return requireKoffi().decode(ptr, offset, "uint8");
 }
 /**
 * Decode a uint16 field at a native pointer offset.
@@ -90,7 +99,7 @@ function decodeUint8At(ptr, offset) {
 * @returns decoded value.
 */
 function decodeUint16At(ptr, offset) {
-	return koffi.decode(ptr, offset, "uint16");
+	return requireKoffi().decode(ptr, offset, "uint16");
 }
 /**
 * Decode a uint32 field at a native pointer offset.
@@ -99,7 +108,7 @@ function decodeUint16At(ptr, offset) {
 * @returns decoded value.
 */
 function decodeUint32At(ptr, offset) {
-	return koffi.decode(ptr, offset, "uint32");
+	return requireKoffi().decode(ptr, offset, "uint32");
 }
 /**
 * Compare two in-memory SID records without allocating strings.
@@ -120,6 +129,8 @@ function sameSidAt(left, leftOffset, right, rightOffset) {
 let cached;
 function bindings() {
 	if (cached !== void 0) return cached;
+	const koffi = requireKoffi();
+	const { PVOID, PPVOID } = ffiTypes();
 	cached = extendWin32ProcessBindings(({ kernel32, advapi32, bind }) => ({
 		openProcess: bind(kernel32, "OpenProcess", PVOID, [
 			"uint32",
@@ -1041,13 +1052,15 @@ var AclSandbox = class {
 		const api = this.api;
 		const token = this.token;
 		if (api === void 0 || token === void 0) throw new Error("AclSandbox is not initialized: call init() first");
+		if (options.controlFileDescriptor !== void 0 && options.stdio !== "inherit") throw new Error("control pipe requires inherited stdio");
 		const args = options.args ?? [];
 		const cwd = options.cwd ?? process.cwd();
 		if (options.stdio === "inherit") {
 			const native = spawnSandboxedInherited(api, token, {
 				command: options.command,
 				args,
-				cwd
+				cwd,
+				...options.controlFileDescriptor === void 0 ? {} : { controlFileDescriptor: options.controlFileDescriptor }
 			});
 			let exitCodePromise;
 			return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-windows-acl",
   "description": "Windows ACL write-restriction sandbox backend (restricted-token spawn with capability-SID write allowlist) for the DeepSeek Harness sandbox seam",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,15 +33,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
-    "@deepseek-ai/dsh-win32-process": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-win32-process": "^0.1.6-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-pwsh-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-local": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-pwsh-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.2"
   }
 }