@deepseek-ai/dsh-sandbox-windows-acl 0.0.1-rc.1

package/lib/types/ffi.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Lazy koffi bindings for the Win32 ACL-sandbox backend. Koffi loads lazily so
+ * non-Windows processes never open Win32 libraries. Every function signature
+ * below was verified against the MinGW Windows headers on this machine
+ * (winnt.h / accctrl.h / aclapi.h / securitybaseapi.h / sddl.h /
+ * processthreadsapi.h / fileapi.h / namedpipeapi.h / synchapi.h / winbase.h);
+ * struct layouts are asserted at load time against verify/abi-probe.cpp.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl/ffi
+ */
+/** Branded koffi 3 native pointer. Koffi 3 pointers are BigInt values; the brand keeps them out of numeric contexts. */
+declare const nativePtr: unique symbol;
+/** Koffi 3 native pointer (a BigInt address), branded so it cannot silently enter numeric contexts. */
+export type NativePtr = bigint & {
+    readonly [nativePtr]: true;
+};
+/**
+ * True for NULL pointers, however koffi returns them (null or 0n).
+ * @param value - a pointer as koffi may hand it back (pointer, null, or 0n).
+ * @returns a type guard narrowing to the NULL shapes.
+ */
+export declare function isNullPtr(value: NativePtr | null | undefined): value is null | undefined;
+/**
+ * True for CreateFileW's INVALID_HANDLE_VALUE failure marker (-1, which
+ * koffi hands back as the unsigned 64-bit all-ones pointer).
+ * @param handle - the handle CreateFileW returned.
+ * @returns whether the handle signals failure.
+ */
+export declare function isInvalidHandle(handle: NativePtr | null | undefined): boolean;
+/** Field subset written into a zeroed STARTUPINFOW (layout verified: size 104). */
+export interface StartupInfoInput {
+    cb: number;
+    dwFlags: number;
+    hStdInput: NativePtr;
+    hStdOutput: NativePtr;
+    hStdError: NativePtr;
+}
+/** Decoded PROCESS_INFORMATION (layout verified: size 24). */
+export interface ProcessInfoOutput {
+    hProcess: NativePtr | null;
+    hThread: NativePtr | null;
+    dwProcessId: number;
+    dwThreadId: number;
+}
+/** The lazy koffi binding table: every Win32 call the ACL backend uses, signature-verified against the real headers. */
+export interface Win32Bindings {
+    openProcess(desiredAccess: number, inheritHandle: number, pid: number): NativePtr;
+    openProcessToken(process: NativePtr, desiredAccess: number, tokenHandle: NativePtr): number;
+    closeHandle(handle: NativePtr): number;
+    getLastError(): number;
+    formatMessageW(flags: number, source: null, messageId: number, languageId: number, buffer: Buffer, size: number, args: null): number;
+    localAlloc(flags: number, bytes: number): NativePtr;
+    localFree(memory: NativePtr): NativePtr;
+    convertStringSidToSidW(stringSid: string, sid: NativePtr): number;
+    createWellKnownSid(type: number, domainSid: null, sid: NativePtr, size: NativePtr): number;
+    isValidSid(sid: NativePtr): number;
+    getLengthSid(sid: NativePtr): number;
+    copySid(length: number, destination: NativePtr, source: NativePtr): number;
+    getTokenInformation(token: NativePtr, cls: number, info: Buffer | null, length: number, needed: NativePtr): number;
+    setTokenInformation(token: NativePtr, cls: number, info: Buffer, length: number): number;
+    createRestrictedToken(existing: NativePtr, flags: number, disableCount: number, disableSids: null, deletePrivilegeCount: number, privilegesToDelete: null, restrictCount: number, restrictingSids: Buffer, newToken: NativePtr): number;
+    setEntriesInAclW(count: number, entries: Buffer, oldAcl: NativePtr | null, newAcl: NativePtr): number;
+    setNamedSecurityInfoW(path: string, objectType: number, information: number, owner: null, group: null, dacl: NativePtr | null, sacl: null): number;
+    getNamedSecurityInfoW(path: string, objectType: number, information: number, owner: NativePtr, group: NativePtr, dacl: NativePtr, sacl: NativePtr, descriptor: NativePtr): number;
+    getTempPathW(length: number, buffer: Buffer): number;
+    createFileW(fileName: string, desiredAccess: number, shareMode: number, attributes: null, creationDisposition: number, flagsAndAttributes: number, templateFile: null): NativePtr;
+    lockFileEx(file: NativePtr, flags: number, reserved: number, bytesLow: number, bytesHigh: number, overlapped: NativePtr): number;
+    unlockFileEx(file: NativePtr, reserved: number, bytesLow: number, bytesHigh: number, overlapped: NativePtr): number;
+    createPipe(readHandle: NativePtr, writeHandle: NativePtr, attributes: null, size: number): number;
+    setHandleInformation(handle: NativePtr, mask: number, flags: number): number;
+    createProcessAsUserW(token: NativePtr, applicationName: null, commandLine: string, processAttributes: null, threadAttributes: null, inheritHandles: number, creationFlags: number, environment: null, currentDirectory: string | null, startupInfo: NativePtr, processInfo: NativePtr): number;
+    setEnvironmentVariableW(name: string, value: string): number;
+    readFile(file: NativePtr, buffer: Buffer, count: number, bytesRead: NativePtr, overlapped: null): number;
+    peekNamedPipe(pipe: NativePtr, buffer: null, size: number, bytesRead: NativePtr, totalAvail: NativePtr, leftThisMessage: NativePtr): number;
+    waitForSingleObject(handle: NativePtr, milliseconds: number): number;
+    getExitCodeProcess(process: NativePtr, exitCode: NativePtr): number;
+    resumeThread(thread: NativePtr): number;
+    createJobObjectW(attributes: null, name: null): NativePtr;
+    setInformationJobObject(job: NativePtr, cls: number, information: Buffer, length: number): number;
+    assignProcessToJobObject(job: NativePtr, process: NativePtr): number;
+    terminateProcess(process: NativePtr, exitCode: number): number;
+    setConsoleCtrlHandler(handler: null, add: number): number;
+    getStdHandle(stdHandle: number): NativePtr;
+}
+/** koffi STARTUPINFOW layout; its size is asserted against abi.STARTUPINFOW_SIZE at load. */
+export declare const STARTUPINFOW: import("koffi").TypeObject;
+/** koffi PROCESS_INFORMATION layout; its size is asserted against abi.PROCESS_INFORMATION_SIZE at load. */
+export declare const PROCESS_INFORMATION: import("koffi").TypeObject;
+/**
+ * Allocate one pointer-sized slot (for `T **` out-parameters).
+ * @returns the allocated slot pointer.
+ */
+export declare function allocPtrSlot(): NativePtr;
+/**
+ * Allocate one uint32 slot.
+ * @returns the allocated slot pointer.
+ */
+export declare function allocUint32(): NativePtr;
+/**
+ * Write a uint32 value into a slot pointer.
+ * @param slot - the slot allocated by {@link allocUint32}.
+ * @param value - the uint32 to encode.
+ */
+export declare function encodeUint32(slot: NativePtr, value: number): void;
+/**
+ * Decode the pointer stored in a pointer-sized slot (NULL becomes null).
+ * @param slot - the pointer-sized slot holding the out-parameter value.
+ * @returns the decoded pointer, or null for NULL.
+ */
+export declare function decodePtr(slot: NativePtr): NativePtr | null;
+/**
+ * Decode a uint32 at a slot pointer.
+ * @param slot - the uint32 slot holding the out-parameter value.
+ * @returns the decoded uint32.
+ */
+export declare function decodeUint32(slot: NativePtr): number;
+/**
+ * Cast a koffi pointer to its numeric address (bigint, used for raw struct packing).
+ * @param ptr - the koffi pointer.
+ * @returns the pointer's numeric address.
+ */
+export declare function ptrAddress(ptr: NativePtr): bigint;
+/**
+ * Allocate a raw byte block (used for SID copies and variable-length arrays).
+ * @param length - the block size in bytes.
+ * @returns the allocated block pointer.
+ */
+export declare function allocBytes(length: number): NativePtr;
+/**
+ * Allocate one zeroed OVERLAPPED (32 bytes on x64: Internal@0, InternalHigh@8,
+ * Offset@16, OffsetHigh@20, hEvent@24). LockFileEx/UnlockFileEx receive this
+ * instead of a NULL lpOverlapped: koffi 3.1.1 crashes on NULL there, and a
+ * zeroed OVERLAPPED on a synchronous file handle is the documented equivalent
+ * (the byte range locks from offset 0, hEvent stays NULL).
+ * @returns the zeroed block pointer.
+ */
+export declare function allocOverlapped(): NativePtr;
+/**
+ * Decode a pointer VALUE stored in memory at `buffer[offset]` (e.g. TOKEN_GROUPS entries).
+ * @param buffer - the buffer holding the pointer value.
+ * @param offset - byte offset of the pointer inside the buffer.
+ * @returns the decoded pointer, or null for NULL.
+ */
+export declare function decodePtrAt(buffer: Buffer, offset: number): NativePtr | null;
+/**
+ * Decode a uint8 at a native pointer plus byte offset — the ACL walk's
+ * field-read primitive (koffi.decode with an offset, no memcpy, no pointer
+ * arithmetic).
+ * @param ptr - the native pointer to read from.
+ * @param offset - byte offset from the pointer.
+ * @returns the decoded uint8.
+ */
+export declare function decodeUint8At(ptr: NativePtr, offset: number): number;
+/**
+ * Decode a uint16 at a native pointer plus byte offset (see {@link decodeUint8At}).
+ * @param ptr - the native pointer to read from.
+ * @param offset - byte offset from the pointer.
+ * @returns the decoded uint16.
+ */
+export declare function decodeUint16At(ptr: NativePtr, offset: number): number;
+/**
+ * Decode a uint32 at a native pointer plus byte offset (see {@link decodeUint8At}).
+ * @param ptr - the native pointer to read from.
+ * @param offset - byte offset from the pointer.
+ * @returns the decoded uint32.
+ */
+export declare function decodeUint32At(ptr: NativePtr, offset: number): number;
+/**
+ * Compare two SIDs field-by-field via BOUNDED offset reads (revision, count,
+ * identifier authority, subauthorities up to the count) — never a fixed-size
+ * struct decode, which would read past a short SID allocation (a SID with
+ * fewer than 8 subauthorities is smaller than `SID_STRUCT`). An implausible
+ * subauthority count reads as unequal.
+ * @param left - pointer to one SID (offset 0).
+ * @param leftOffset - byte offset of the SID structure within `left`.
+ * @param right - pointer to the other SID.
+ * @param rightOffset - byte offset of the SID structure within `right`.
+ * @returns whether the SIDs are identical.
+ */
+export declare function sameSidAt(left: NativePtr, leftOffset: number, right: NativePtr, rightOffset: number): boolean;
+/**
+ * Allocate a zeroed STARTUPINFOW.
+ * @returns the allocated struct pointer.
+ */
+export declare function allocStartupInfo(): NativePtr;
+/**
+ * Write the stdio-relevant fields into a zeroed STARTUPINFOW (others stay default-initialized).
+ * @param startupInfo - the allocated STARTUPINFOW to encode into.
+ * @param fields - the field subset to write.
+ */
+export declare function encodeStartupInfo(startupInfo: NativePtr, fields: StartupInfoInput): void;
+/**
+ * Allocate a zeroed PROCESS_INFORMATION.
+ * @returns the allocated struct pointer.
+ */
+export declare function allocProcessInfo(): NativePtr;
+/**
+ * Decode a PROCESS_INFORMATION after CreateProcessAsUserW.
+ * @param processInfo - the PROCESS_INFORMATION filled by the spawn call.
+ * @returns the decoded handle/id fields.
+ */
+export declare function decodeProcessInfo(processInfo: NativePtr): ProcessInfoOutput;
+/**
+ * Resolve the lazy Win32 bindings (throws the first binding failure, fail-closed).
+ * @returns the cached binding table.
+ */
+export declare function win32(): Promise<Win32Bindings>;
+/**
+ * Resolve the lazy Win32 bindings SYNCHRONOUSLY — the sandbox seam's
+ * server-side per-session grant materializes ACEs inside the synchronous
+ * `confine()` call, which cannot await. Same cached table as {@link win32}
+ * (the underlying koffi loads are synchronous; the async wrapper exists for
+ * the runner's await-shaped call sites).
+ * @returns the cached binding table.
+ */
+export declare function win32Sync(): Win32Bindings;
+/**
+ * Turn a Win32 error code into readable text via FormatMessageW.
+ * @param api - the binding table.
+ * @param win32Code - the error code to format.
+ * @returns the formatted message text, or '' when formatting fails.
+ */
+export declare function errorText(api: Win32Bindings, win32Code: number): string;
+/**
+ * Read the process temp directory via GetTempPathW (fileapi.h line ~188).
+ * Defensive against an overlong system temp path: GetTempPathW reports the
+ * REQUIRED length (including NUL) without writing the buffer when it is too
+ * small, so a reported length beyond the buffer's capacity means the buffer
+ * was never filled and must not be decoded.
+ * @param api - the binding table.
+ * @returns the NUL-terminated temp path decoded as a string.
+ */
+export declare function getTempPath(api: Win32Bindings): string;
+/**
+ * Throw a Win32Error for a BOOL-style API failure. MUST be called immediately
+ * after the failed call so GetLastError is not clobbered by other Win32 calls.
+ * @param api - the binding table.
+ * @param name - the failed API's name for the error message.
+ * @param detail - optional detail overriding the formatted system message.
+ * @returns never — always throws.
+ */
+export declare function throwLastError(api: Win32Bindings, name: string, detail?: string): never;
+/**
+ * Throw a Win32Error for an HRESULT-style API return value (the value IS the error code).
+ * @param api - the binding table.
+ * @param name - the failed API's name for the error message.
+ * @param win32Code - the API's returned error code.
+ * @param detail - optional detail overriding the formatted system message.
+ * @returns never — always throws.
+ */
+export declare function throwWin32(api: Win32Bindings, name: string, win32Code: number, detail?: string): never;
+export {};
+//# sourceMappingURL=ffi.d.ts.map

package/lib/types/grant.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Server-side per-session write grant: the ACE materialization half of the
+ * sandbox seam's per-session grant reuse. The seam (sandbox-local) holds ONE
+ * {@link AclWriteGrant} per session for the server process's lifetime —
+ * created lazily at the session's first confined execution, reused (never
+ * re-applied) for every later call, revoked on provider dispose. The durable
+ * half (the session's SID and paths surviving a restart) lives in the
+ * session log, owned by the seam; this module owns only the native half: the
+ * parsed SID pointer and the standing ACEs.
+ *
+ * Fail-closed: `add` throws on any grant failure and the caller disposes the
+ * instance (revoking every path granted so far); `dispose` revokes every
+ * standing grant and reports every cleanup failure.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl/grant
+ */
+import type { Win32Bindings } from './ffi.ts';
+/**
+ * One write SID's server-lifetime grant materialization: the parsed SID
+ * pointer plus every directory whose DACL currently carries its ACE.
+ * Workspace paths are added STANDING (their ACEs are the cross-session reuse
+ * cache and outlive the grant — dispose() skips revoking them, or the next
+ * provision would re-propagate the whole tree); temp paths are revocable
+ * (dispose() revokes them — an inheritable ACE must not outlive its
+ * session's temp directory). Create with {@link AclWriteGrant.create};
+ * dispose revokes the revocable paths and frees the SID.
+ */
+export declare class AclWriteGrant {
+    /** The write SID in SDDL string form. */
+    readonly writeSid: string;
+    private readonly api;
+    private readonly sidPtr;
+    private readonly revocablePaths;
+    private readonly standingPaths;
+    private constructor();
+    /**
+     * Parse the SID string and open the binding table (lazily, once per
+     * server). Fail-closed: any failure throws — nothing is granted yet.
+     * @param writeSid - the orphan write SID string (`S-1-4-x-y`).
+     * @param api - optional already-resolved bindings (tests).
+     * @returns the ready grant (no ACEs yet).
+     */
+    static create(writeSid: string, api?: Win32Bindings): AclWriteGrant;
+    /**
+     * Grant the write ACE on one directory (idempotent: an already-standing
+     * exact ACE skips the eager full-tree re-propagation — see
+     * {@link grantWrite}) and record the path for {@link dispose} unless it is
+     * standing. The path is recorded BEFORE the grant: a post-apply throw (a
+     * LocalFree failure after SetNamedSecurityInfoW succeeded) must still
+     * revoke it, and revoking an ungranted path is a no-op merge. Callers
+     * treat a throw as a failed materialization and dispose the instance to
+     * revoke the paths granted so far.
+     * @param path - the directory whose DACL gains the grant.
+     * @param standing - the ACE outlives this grant (the workspace reuse
+     *   cache; dispose() skips revoking it). Default false (revoked on
+     *   dispose — the temp-directory lifecycle).
+     */
+    add(path: string, standing?: boolean): void;
+    /** Every directory currently carrying the grant, in grant order. */
+    get paths(): readonly string[];
+    /** Revoke every revocable grant (standing ACEs stay) and free the SID; reports every cleanup failure. */
+    dispose(): void;
+}
+//# sourceMappingURL=grant.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Windows ACL write-restriction sandbox backend for the DeepSeek Harness
+ * sandbox seam. Mirrors the mechanism of github.com/huoyaoyuan/
+ * windows-acl-restrict-poc @ 10e4dfb (the fixed revision): a WRITE_RESTRICTED
+ * token whose restricting SIDs include a write SID (`S-1-4-x-y`) that only
+ * this sandbox adds to the target directories' DACLs — the intersection
+ * check then allows writes exactly where that SID has a Write ACE, and
+ * nowhere else the write SID is concerned (the token's write check ALSO
+ * inherits the ambient write ACEs of the other restricting SIDs — the
+ * keep-alive group logon SID + Everyone; Authenticated Users, INTERACTIVE,
+ * and LOCAL are absent from both lists — see the seam's dual-list contract
+ * in `packages/sandbox/sandbox-local` and the package README's Modes section
+ * for the complete boundary). The write SID is the per-WORKSPACE identity
+ * ({@link workspaceWriteSid}): deterministic from the canonical workspace
+ * path, so the workspace-root ACE materializes once per workspace per
+ * machine and every later provision hits the exact-ACE skip — the
+ * grant-reuse story the per-session random SID paid a full tree propagation
+ * per session for. Unlike the POC, every API failure throws with the API
+ * name and exact Win32 code; a child is NEVER spawned unrestricted.
+ *
+ * Known boundaries (inherent to restricted tokens, not this port):
+ *  - writes are restricted; reads, network, and process visibility are NOT
+ *    (WRITE_RESTRICTED intersects only write accesses);
+ *  - console isolation is unavailable — children share the host console
+ *    (CREATE_NO_WINDOW / CREATE_NEW_CONSOLE children die with
+ *    STATUS_DLL_INIT_FAILED under the restriction);
+ *  - the temp directory and every writable directory must be owned by the
+ *    caller (owner-implicit WRITE_DAC);
+ *  - grants are standing ACE mutations on real directories. WORKSPACE grants
+ *    are deliberately never revoked — the ACE is the cross-session reuse
+ *    cache (revoking would force the next session to re-propagate the whole
+ *    tree). TEMP grants are revocable: dispose() removes them so a standing
+ *    inheritable ACE never outlives its session's temp directory (an
+ *    inheritable ACE on the ambient temp root would otherwise widen the
+ *    SID's write reach to every future temp file). With `manageDacls: false`
+ *    the CALLER owns the DACLs (the sandbox seam's grant reuse):
+ *    init()/dispose() skip grant/revoke entirely and the caller must not
+ *    revoke under live children.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl
+ */
+export { quoteArg } from './spawn.ts';
+export { AclWriteGrant } from './grant.ts';
+export { workspaceWriteSid } from './workspace-sid.ts';
+export { Win32Error } from './errors.ts';
+/** Construction options: the write allowlist, the optional temp grant, and the orphan SID identity. */
+export interface AclSandboxOptions {
+    /** Directories the confined child may write into (must exist and be caller-owned). */
+    writableDirs: readonly string[];
+    /**
+     * Temp directory to also grant; defaults to GetTempPathW() at init time.
+     * Pass null for read-only confinement: NO temp grant (strict zero grant on
+     * the filesystem; the NUL device stays ambient-writable via Everyone — see
+     * README).
+     */
+    tempDir?: string | null;
+    /**
+     * The write SID forming the workspace-write allowlist: REQUIRED under
+     * workspace-write, ignored (and must be absent) under read-only. Callers
+     * derive it from the workspace via {@link workspaceWriteSid} — the identity
+     * is per workspace, not per sandbox instance, so the workspace-root ACE
+     * outlives every instance and later provisions hit the exact-ACE skip.
+     */
+    writeSid?: string;
+    /**
+     * The file-effect mode this instance confines under — selects the
+     * restricted token's restricting-SID list (I for read-only, J for
+     * workspace-write) and MUST match the grant shape: read-only pairs with
+     * zero grants. The runner validates the argv-borne mode string at its
+     * boundary; this typed seam trusts the union.
+     */
+    mode: 'read-only' | 'workspace-write';
+    /**
+     * Whether this instance owns its DACL grants (default true). False means
+     * the CALLER has already materialized the ACEs (the sandbox seam's
+     * per-session grant reuse): init()/dispose() skip grant/revoke entirely —
+     * the caller holds the grants for its own lifetime and revokes them.
+     */
+    manageDacls?: boolean;
+}
+/** Per-spawn options: the program, its argv/cwd, and the stdio shape. */
+export interface AclSandboxSpawnOptions {
+    /** Program to run (resolved via PATH search when unqualified, like CreateProcess). */
+    command: string;
+    /** Arguments, quoted per CommandLineToArgvW rules. */
+    args?: readonly string[];
+    /** Working directory; defaults to the caller's cwd. */
+    cwd?: string;
+    /**
+     * 'pipe' (default): capture stdout/stderr via anonymous pipes.
+     * 'inherit': the child inherits the caller's stdio directly (runner usage —
+     * bytes flow straight through), always wrapped in a kill-on-close job so the
+     * child dies with the caller; stdout/stderr in the result are empty.
+     */
+    stdio?: 'pipe' | 'inherit';
+}
+/** A settled confined child: captured stdio and the exit code. */
+export interface AclSandboxChildResult {
+    stdout: Buffer;
+    stderr: Buffer;
+    exitCode: number;
+}
+/** A running confined child: its pid and a settlement promise. */
+export interface AclSandboxChild {
+    /** Child process id. */
+    pid: number;
+    /** Resolve stdout/stderr and the exit code once the child exits. */
+    wait(): Promise<AclSandboxChildResult>;
+}
+/**
+ * One write-restricted sandbox instance: token + write-SID grants + spawn.
+ * `init()` is fail-closed — any Win32 failure revokes the revocable (temp)
+ * grants and throws; `dispose()` revokes the temp grants, leaves the
+ * standing workspace ACEs in place (the cross-instance reuse cache), frees
+ * every allocation, and reports every cleanup failure. With
+ * `manageDacls: false` the caller owns the grants (the sandbox seam's grant
+ * reuse): init() applies none and dispose() revokes none.
+ */
+export declare class AclSandbox {
+    /** Absolute writable directories (constructor-validated). */
+    readonly writableDirs: string[];
+    /** The write SID string whose ACEs form the write allowlist (workspace-write only). */
+    readonly writeSid: string | undefined;
+    /** The file-effect mode — the restricted token's restricting-SID list selection. */
+    readonly mode: 'read-only' | 'workspace-write';
+    private readonly tempDirOption;
+    private readonly manageDacls;
+    private tempDirResolved;
+    private api;
+    private token;
+    private writeSidPtr;
+    /** The well-known/logon SID allocations init() makes; freed by dispose() alongside the write SID. */
+    private sidAllocations;
+    private grantedPaths;
+    constructor(options: AclSandboxOptions);
+    /** Resolved temp directory (available after init; null when temp grants are disabled). */
+    get tempDir(): string | null | undefined;
+    /** Create the restricted token and apply the orphan-SID grants. Idempotent-unsafe: once per instance. */
+    init(): Promise<void>;
+    /**
+     * Spawn a process under the restricted token. Fails closed: throws on every
+     * Win32 failure; the child is never created unrestricted. With
+     * `stdio: 'inherit'` the child shares the caller's stdio directly and is
+     * placed in a kill-on-close job (dies with the caller). Call dispose() only
+     * after all children have exited — revoking grants under a live child
+     * removes its remaining write allowance.
+     * @param options - the program, argv/cwd, and stdio shape.
+     * @returns the running child.
+     */
+    spawn(options: AclSandboxSpawnOptions): AclSandboxChild;
+    /**
+     * Revoke the revocable (temp) grants, free the SID, close the token; the
+     * standing workspace ACEs stay (the reuse cache). Reports every cleanup
+     * failure.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sandbox-windows-acl`.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sandbox-windows-acl-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/runner.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The windows-acl confinement runner: the argv-prefix wrapper the sandbox
+ * seam spawns in place of the caller's command. It creates the
+ * WRITE_RESTRICTED token with the workspace write-SID allowlist, spawns the
+ * wrapped argv under it with the CALLER'S stdio inherited (bytes flow
+ * straight through), mirrors the child's exit code, and revokes its temp
+ * grant on exit (workspace ACEs stay standing as the reuse cache).
+ *
+ * Stable argv contract (the seam builds it; a native-exe replacement would
+ * keep the same contract):
+ *   [node, runner.js, '--workspace', <dir>, '--temp', <dir>,
+ *    '--mode', <read-only|workspace-write>,
+ *    ['--write-sid', <S-1-4-…>], '--', <argv...>]
+ *
+ * Modes:
+ *  - workspace-write: the workspace and temp directories carry the orphan-SID
+ *    Write grant; every other write is denied by the token intersection.
+ *  - read-only: STRICT zero grants — no directory is writable, not even the
+ *    NUL device (`> $null` fails with access denied); the restricting list
+ *    carries no orphan SID, so a standing grant ACE from an earlier
+ *    workspace-write period stays inert. BOTH modes drop Authenticated Users
+ *    (CIM unavailable — documented in README) and INTERACTIVE/LOCAL (the
+ *    Public tree writes are denied); the two lists share the keep-alive group
+ *    (logon SID, EVERYONE) and differ only by the orphan.
+ *
+ * `--write-sid`: the seam's grant contract — the CALLER has already
+ * materialized the write-SID ACEs (the seam's workspace + private-temp
+ * grants, server lifetime) and owns their revocation, so the runner neither
+ * grants nor revokes (manageDacls: false). The carried SID is the
+ * per-workspace identity ({@link workspaceWriteSid}) — the seam derives it
+ * from the policy root; the flag's PRESENCE is the seam-managed marker (its
+ * value must equal the workspace-derived SID). Absent `--write-sid`
+ * (standalone/test use) the runner self-manages grants per invocation with
+ * the same workspace-derived SID (its workspace ACEs are standing — the
+ * reuse cache — and its temp ACE is revoked on exit). With `--write-sid` in
+ * workspace-write mode, the runner rewrites the TMP/TEMP entries of its OWN
+ * environment (SetEnvironmentVariableW) to the `--temp` directory — a
+ * PRIVATE per-session temp subdirectory the seam provisions (bwrap `--tmpfs
+ * /tmp` semantics) — and the child inherits the rewritten block (lpEnvironment
+ * NULL; an explicit block through koffi trips ERROR_INVALID_PARAMETER in
+ * CreateProcessAsUserW, verified empirically). Read-only leaves the ambient
+ * temp entries untouched (writes there are denied anyway).
+ *
+ * Failure contract: every runner-side failure (bad args, missing
+ * directories, token/grant/spawn errors) prints `windows-acl-run: <detail>`
+ * to stderr and exits 127 — the seam's RUNNER_FAILURE_RULES matches that
+ * signature. The child is NEVER spawned unrestricted.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl/runner
+ */
+export {};
+//# sourceMappingURL=runner.d.ts.map

package/lib/types/spawn.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Restricted-process spawning: anonymous pipes for stdio, STARTUPINFOW with
+ * STARTF_USESTDHANDLES, CreateProcessAsUserW under the restricted token, then
+ * asynchronous pipe draining and exit waiting. Console isolation
+ * (CREATE_NO_WINDOW / CREATE_NEW_CONSOLE) is intentionally absent: under this
+ * restriction scheme hidden-console children die with STATUS_DLL_INIT_FAILED
+ * (0xC0000142) — verified empirically, see win32-abi.ts. Stdio redirection is
+ * pipe-based and unaffected; the child shares the host console.
+ * @module @deepseek-ai/dsh-sandbox-windows-acl/spawn
+ */
+import type { NativePtr, Win32Bindings } from './ffi.ts';
+/**
+ * Quote one argument per the CommandLineToArgvW parsing rules: backslashes
+ * are doubled only before a quote character — including the closing quote
+ * this function appends, so a trailing backslash run is doubled as well
+ * (otherwise an odd run would escape the closing quote into a literal
+ * character and corrupt the rest of the command line). Mirrors the CRT
+ * ArgvQuote behavior Microsoft documents for command-line arguments.
+ * @param argument - one argv entry to quote.
+ * @returns the quoted entry (bare when quoting is unnecessary).
+ */
+export declare function quoteArg(argument: string): string;
+/**
+ * Build the single command line CreateProcess parses from program + argv.
+ * @param program - the executable (argv[0]).
+ * @param args - the remaining argv entries.
+ * @returns the joined, quoted command line.
+ */
+export declare function buildCommandLine(program: string, args: readonly string[]): string;
+/** A confined child spawned with piped stdio: process handle plus the pipe read ends to drain. */
+export interface SpawnedNative {
+    pid: number;
+    process: NativePtr;
+    stdoutRead: NativePtr;
+    stderrRead: NativePtr;
+}
+/**
+ * Create a process under the restricted token with piped stdio. The child's
+ * stdin is closed immediately (EOF), matching the POC; stdout/stderr read ends
+ * are returned for draining. The child inherits the caller's environment block
+ * (lpEnvironment NULL); the caller rewrites entries through
+ * SetEnvironmentVariableW before spawning (the runner's per-session temp
+ * contract) — passing an explicit block through koffi trips
+ * ERROR_INVALID_PARAMETER in CreateProcessAsUserW (verified empirically).
+ * @param api - the binding table.
+ * @param token - the restricted token the child runs under.
+ * @param options - command, args, and working directory.
+ * @returns the spawned child's handles.
+ */
+export declare function spawnSandboxed(api: Win32Bindings, token: NativePtr, options: {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+}): SpawnedNative;
+/**
+ * Drain one pipe read end to a Buffer via non-blocking PeekNamedPipe polling.
+ * @param api - the binding table.
+ * @param handle - the pipe read end to drain (closed when done).
+ * @returns the complete pipe contents.
+ */
+export declare function drainPipe(api: Win32Bindings, handle: NativePtr): Promise<Buffer>;
+/**
+ * Wait for process exit and return its exit code. Call only after both drains
+ * have resolved — the drains finish when the child closed its pipe ends, i.e.
+ * the child has already exited, so this wait returns immediately. Calling it
+ * earlier would block the event loop and starve the drains (the pipe-buffer
+ * deadlock the POC comments warn about).
+ * @param api - the binding table.
+ * @param process - the child process handle (closed when done).
+ * @returns the child's exit code.
+ */
+export declare function waitForExit(api: Win32Bindings, process: NativePtr): number;
+/** A confined child spawned with inherited stdio: process handle plus its kill-on-close job. */
+export interface SpawnedInherited {
+    pid: number;
+    process: NativePtr;
+    /** Kill-on-close job the child was placed in; caller closes it after the child exits. */
+    job: NativePtr;
+}
+/**
+ * Create a process under the restricted token whose stdio passes straight
+ * through to the caller's pipes. This is the runner shape: the harness spawns
+ * the runner with piped stdio, and the runner's confined child writes to
+ * those same pipes.
+ *
+ * Node clears the inheritability of its stdio handles at startup
+ * (uv_disable_stdio_inheritance), so raw spawns must re-enable the inherit
+ * bit around the call (libuv instead duplicates the handles; re-enabling is
+ * equivalent here and cheaper) and pass them explicitly via
+ * STARTF_USESTDHANDLES — otherwise the child receives INVALID std handles
+ * ("The handle is invalid", verified the hard way). The child starts
+ * suspended so it can be assigned to a kill-on-close job before it runs.
+ * @param api - the binding table.
+ * @param token - the restricted token the child runs under.
+ * @param options - command, args, and working directory.
+ * @returns the spawned child's handles and job.
+ */
+export declare function spawnSandboxedInherited(api: Win32Bindings, token: NativePtr, options: {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+}): SpawnedInherited;
+//# sourceMappingURL=spawn.d.ts.map