@bo-agent/sandbox-windows-acl 0.0.1

package/lib/runner.js

@@ -0,0 +1,222 @@
+/**
+ * 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-…>,
+ *     '--temp-write-sid', <S-1-4-…>], '--', <argv...>]
+ *
+ * Modes:
+ *  - workspace-write: the workspace and temp directories carry distinct
+ *    capability-SID Write grants; other ACL-addressable writes are denied
+ *    except for the documented Everyone and hard-link boundaries.
+ *  - read-only: no capability-SID grants; the restricting list carries no
+ *    capability 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 capabilities.
+ *
+ * `--write-sid` + `--temp-write-sid`: the seam's grant contract — the
+ * CALLER has already materialized distinct workspace and private-temp ACEs
+ * and owns their revocation, so the runner neither grants nor revokes
+ * (`manageDacls: false`). Both values are checked against their owning paths.
+ * Without the pair (standalone/agentless use), workspace-write treats
+ * `--temp` as a ROOT, creates a random private child directory, derives its
+ * own temp SID, and removes that directory after the child exits. In both
+ * flows the runner rewrites TMP/TEMP in its OWN environment to the private
+ * directory before spawning; the child inherits that 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 @bo-agent/sandbox-windows-acl/runner
+ */
+import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { win32 } from "./ffi.js";
+import { AclSandbox, assertTempRootOutsideWorkspace } from "./index.js";
+import { tempWriteSid, workspaceWriteSid } from "./workspace-sid.js";
+const RUNNER_SIGNATURE = 'windows-acl-run';
+const RUNNER_FAILURE_EXIT = 127;
+class RunnerFailure extends Error {
+}
+/** Print the runner-failure signature line and unwind. */
+function fail(detail) {
+    process.stderr.write(`${RUNNER_SIGNATURE}: ${detail}\n`);
+    throw new RunnerFailure(detail);
+}
+function parseArgs(raw) {
+    let workspace;
+    let temp;
+    let mode;
+    let writeSid;
+    let parsedTempWriteSid;
+    let index = 0;
+    for (; index < raw.length; index++) {
+        const token = raw[index];
+        if (token === '--') {
+            index++;
+            break;
+        }
+        index++;
+        const value = raw[index];
+        if (value === undefined)
+            fail(`missing value after ${token}`);
+        switch (token) {
+            case '--workspace':
+                workspace = value;
+                break;
+            case '--temp':
+                temp = value;
+                break;
+            case '--mode':
+                mode = value;
+                break;
+            case '--write-sid':
+                writeSid = value;
+                break;
+            case '--temp-write-sid':
+                parsedTempWriteSid = value;
+                break;
+            default: fail(`unknown argument: ${token}`);
+        }
+    }
+    if (workspace === undefined)
+        fail('missing --workspace');
+    if (temp === undefined)
+        fail('missing --temp');
+    if (mode !== 'read-only' && mode !== 'workspace-write')
+        fail(`unknown mode: ${String(mode)}`);
+    const argv = raw.slice(index);
+    const command = argv[0];
+    if (command === undefined)
+        fail('missing command after --');
+    return { workspace, temp, mode, writeSid, tempWriteSid: parsedTempWriteSid, command, args: argv.slice(1) };
+}
+function requireDirectory(label, path) {
+    if (!existsSync(path) || !statSync(path).isDirectory()) {
+        fail(`${label} is not an existing directory: ${path}`);
+    }
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    // Both directories are validated in both modes: a provider bug that passes
+    // a bogus root must fail loudly at the runner boundary, never mid-child.
+    requireDirectory('--workspace', parsed.workspace);
+    requireDirectory('--temp', parsed.temp);
+    const seamManaged = parsed.writeSid !== undefined || parsed.tempWriteSid !== undefined;
+    if (parsed.mode === 'read-only' && seamManaged) {
+        fail('read-only does not accept --write-sid or --temp-write-sid');
+    }
+    if (parsed.mode === 'workspace-write' && (parsed.writeSid === undefined) !== (parsed.tempWriteSid === undefined)) {
+        fail('workspace-write requires --write-sid and --temp-write-sid together');
+    }
+    if (parsed.mode === 'workspace-write') {
+        assertTempRootOutsideWorkspace(parsed.workspace, parsed.temp);
+    }
+    const api = await win32();
+    // Ignore this process's own CTRL+C: the confined child (same console) keeps
+    // handling its own; the runner must survive to revoke grants and mirror the
+    // child's exit code.
+    if (api.setConsoleCtrlHandler(null, 1) === 0) {
+        fail(`SetConsoleCtrlHandler failed (Win32 ${api.getLastError()})`);
+    }
+    let ownedTempDir;
+    let sandbox;
+    let initialized = false;
+    try {
+        let privateTempDir = null;
+        let writeSid;
+        let privateTempSid;
+        if (parsed.mode === 'workspace-write') {
+            writeSid = workspaceWriteSid(parsed.workspace);
+            if (seamManaged) {
+                if (parsed.writeSid !== writeSid)
+                    fail('--write-sid does not match --workspace');
+                privateTempDir = parsed.temp;
+                privateTempSid = tempWriteSid(privateTempDir);
+                if (parsed.tempWriteSid !== privateTempSid)
+                    fail('--temp-write-sid does not match --temp');
+            }
+            else {
+                ownedTempDir = mkdtempSync(join(parsed.temp, 'dsh-'));
+                privateTempDir = ownedTempDir;
+                privateTempSid = tempWriteSid(privateTempDir);
+            }
+        }
+        sandbox = new AclSandbox({
+            writableDirs: parsed.mode === 'workspace-write' ? [parsed.workspace] : [],
+            tempDir: privateTempDir,
+            mode: parsed.mode,
+            ...writeSid === undefined ? {} : { writeSid },
+            ...privateTempSid === undefined ? {} : { tempWriteSid: privateTempSid },
+            manageDacls: !seamManaged,
+        });
+        await sandbox.init();
+        initialized = true;
+        if (privateTempDir !== null) {
+            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()})`);
+            }
+        }
+        const child = sandbox.spawn({
+            command: parsed.command,
+            args: parsed.args,
+            stdio: 'inherit',
+        });
+        const result = await child.wait();
+        return result.exitCode;
+    }
+    finally {
+        // Cleanup failures must not mask the child's exit code: report and keep going.
+        if (initialized) {
+            try {
+                sandbox?.dispose();
+            }
+            catch (error) {
+                process.stderr.write(`${RUNNER_SIGNATURE}: cleanup: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        if (ownedTempDir !== undefined) {
+            try {
+                rmSync(ownedTempDir, { recursive: true, force: true });
+            }
+            catch (error) {
+                process.stderr.write(`${RUNNER_SIGNATURE}: cleanup: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+    }
+}
+main().then((exitCode) => {
+    // Exit-code mirroring is full-width on Windows, verified empirically on
+    // this machine (Windows 11 build 26200, Node 24): a child that exits
+    // with the NTSTATUS 0xC0000005 (STATUS_ACCESS_VIOLATION) is read back
+    // by GetExitCodeProcess as the uint32 3221225477, and after
+    // process.exitCode = 3221225477 the parent observes exactly
+    // 3221225477 (spawnSync status). PowerShell's $LASTEXITCODE and cmd
+    // print the signed view (-1073741819), but no truncation or masking
+    // happens anywhere in the chain — the mirror contract holds for the
+    // full 32-bit range, so no re-mapping is needed.
+    process.exitCode = exitCode;
+}, (error) => {
+    if (!(error instanceof RunnerFailure)) {
+        process.stderr.write(`${RUNNER_SIGNATURE}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.exitCode = RUNNER_FAILURE_EXIT;
+});
+//# sourceMappingURL=runner.js.map

package/lib/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/lib/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 @bo-agent/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

package/lib/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../src/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBjD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEjF;AAuBD,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,SAAS,CAAA;IAClB,UAAU,EAAE,SAAS,CAAA;IACrB,UAAU,EAAE,SAAS,CAAA;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjE,aAAa,CA+Df;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,GAAG,MAAM,CAO1E;AAsBD,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,SAAS,CAAA;IAClB,yFAAyF;IACzF,GAAG,EAAE,SAAS,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjE,gBAAgB,CAoFlB"}

package/lib/spawn.js

@@ -0,0 +1,307 @@
+/**
+ * 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 @bo-agent/sandbox-windows-acl/spawn
+ */
+import { allocPtrSlot, allocProcessInfo, allocStartupInfo, allocUint32, decodePtr, decodeProcessInfo, decodeUint32, encodeStartupInfo, isNullPtr, throwLastError, throwWin32 } from "./ffi.js";
+import * as abi from "./win32-abi.js";
+/**
+ * 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 function quoteArg(argument) {
+    if (argument === '')
+        return '""';
+    if (!/[\s"]/u.test(argument))
+        return argument;
+    let quoted = '"';
+    for (let index = 0; index < argument.length; index++) {
+        let backslashes = 0;
+        while (index < argument.length && argument.charAt(index) === '\\') {
+            backslashes++;
+            index++;
+        }
+        if (index === argument.length) {
+            // Trailing backslash run: doubled so it cannot escape the closing quote.
+            quoted += '\\'.repeat(backslashes * 2);
+        }
+        else if (argument.charAt(index) === '"') {
+            quoted += '\\'.repeat(backslashes * 2 + 1) + '"';
+        }
+        else {
+            quoted += '\\'.repeat(backslashes) + argument.charAt(index);
+        }
+    }
+    return quoted + '"';
+}
+/**
+ * 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 function buildCommandLine(program, args) {
+    return [program, ...args].map(quoteArg).join(' ');
+}
+function createPipe(api) {
+    const readSlot = allocPtrSlot();
+    const writeSlot = allocPtrSlot();
+    if (api.createPipe(readSlot, writeSlot, null, 0) === 0)
+        throwLastError(api, 'CreatePipe');
+    const read = decodePtr(readSlot);
+    const write = decodePtr(writeSlot);
+    if (read === null || write === null)
+        throwLastError(api, 'CreatePipe', 'null pipe handle');
+    return { read, write };
+}
+function setInheritable(api, handle, label) {
+    if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
+        throwLastError(api, 'SetHandleInformation', label);
+    }
+}
+/**
+ * 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 function spawnSandboxed(api, token, options) {
+    const stdIn = createPipe(api);
+    const stdOut = createPipe(api);
+    const stdErr = createPipe(api);
+    // Child side of each pipe must be inheritable (POC lines 262-268).
+    setInheritable(api, stdIn.read, 'stdin read end');
+    setInheritable(api, stdOut.write, 'stdout write end');
+    setInheritable(api, stdErr.write, 'stderr write end');
+    const startupInfo = allocStartupInfo();
+    encodeStartupInfo(startupInfo, {
+        cb: abi.STARTUPINFOW_SIZE,
+        dwFlags: abi.STARTF_USESTDHANDLES,
+        hStdInput: stdIn.read,
+        hStdOutput: stdOut.write,
+        hStdError: stdErr.write,
+    });
+    const processInfo = allocProcessInfo();
+    const commandLine = buildCommandLine(options.command, options.args);
+    const created = api.createProcessAsUserW(token, null, commandLine, null, null, 1, // bInheritHandles: required for redirection
+    0, // no creation flags: suspended/no-window variants are unusable under the restriction
+    null, options.cwd, startupInfo, processInfo);
+    // Capture the failure before CloseHandle calls clobber GetLastError, then
+    // close every pipe handle created so far — the six-close contract this test
+    // surface pins (tests/failure-paths.spec.ts).
+    if (created === 0) {
+        const win32Code = api.getLastError();
+        api.closeHandle(stdIn.read);
+        api.closeHandle(stdIn.write);
+        api.closeHandle(stdOut.read);
+        api.closeHandle(stdOut.write);
+        api.closeHandle(stdErr.read);
+        api.closeHandle(stdErr.write);
+        throwWin32(api, 'CreateProcessAsUserW', win32Code, `command: ${options.command}, cwd: ${options.cwd}`);
+    }
+    const info = decodeProcessInfo(processInfo);
+    const processHandle = info.hProcess;
+    const threadHandle = info.hThread;
+    if (processHandle === null || threadHandle === null) {
+        throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`);
+    }
+    // Host-side cleanup: child handles are now duplicated in the child; the
+    // host closes its copies so ReadFile sees EOF when the child exits.
+    api.closeHandle(stdIn.read);
+    api.closeHandle(stdOut.write);
+    api.closeHandle(stdErr.write);
+    api.closeHandle(stdIn.write);
+    api.closeHandle(threadHandle);
+    return {
+        pid: info.dwProcessId,
+        process: processHandle,
+        stdoutRead: stdOut.read,
+        stderrRead: stdErr.read,
+    };
+}
+/**
+ * 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 async function drainPipe(api, handle) {
+    const chunks = [];
+    for (;;) {
+        const bytesReadSlot = allocUint32();
+        const totalAvailSlot = allocUint32();
+        const leftThisMessageSlot = allocUint32();
+        const peeked = api.peekNamedPipe(handle, null, 0, bytesReadSlot, totalAvailSlot, leftThisMessageSlot);
+        if (peeked === 0) {
+            const win32Code = api.getLastError();
+            if (win32Code === abi.ERROR_BROKEN_PIPE || win32Code === abi.ERROR_NO_DATA)
+                break; // child closed its end: clean EOF
+            throwLastError(api, 'PeekNamedPipe', `drain failure after ${chunks.length} chunk(s)`);
+        }
+        const available = decodeUint32(totalAvailSlot);
+        if (available > 0) {
+            const chunk = Buffer.alloc(available);
+            const readSlot = allocUint32();
+            if (api.readFile(handle, chunk, chunk.length, readSlot, null) === 0) {
+                throwLastError(api, 'ReadFile', `drain failure after ${chunks.length} chunk(s)`);
+            }
+            chunks.push(chunk.subarray(0, decodeUint32(readSlot)));
+        }
+        // Small backoff instead of setImmediate: a bare next-tick would busy-poll
+        // the pipe at full event-loop speed while the child produces no output.
+        await new Promise(resolve => setTimeout(resolve, 1));
+    }
+    api.closeHandle(handle);
+    return Buffer.concat(chunks);
+}
+/**
+ * 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 function waitForExit(api, process) {
+    const waitResult = api.waitForSingleObject(process, abi.INFINITE);
+    if (waitResult === 0xFFFFFFFF)
+        throwLastError(api, 'WaitForSingleObject');
+    const exitCodeSlot = allocUint32();
+    if (api.getExitCodeProcess(process, exitCodeSlot) === 0)
+        throwLastError(api, 'GetExitCodeProcess');
+    api.closeHandle(process);
+    return decodeUint32(exitCodeSlot);
+}
+/**
+ * Create a kill-on-close job object (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE at
+ * LimitFlags offset 16 of JOBOBJECT_EXTENDED_LIMIT_INFORMATION, layout
+ * verified by abi-probe.cpp). When the caller dies with the job handle open,
+ * Windows terminates every process in the job — the orphan-child backstop.
+ * The caller keeps the returned handle open for the child's lifetime.
+ */
+function createKillOnCloseJob(api) {
+    const job = api.createJobObjectW(null, null);
+    if (isNullPtr(job))
+        throwLastError(api, 'CreateJobObjectW');
+    const information = Buffer.alloc(abi.JOBOBJECT_EXTENDED_LIMIT_SIZE);
+    information.writeUInt32LE(abi.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, abi.JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET);
+    if (api.setInformationJobObject(job, abi.JobObjectExtendedLimitInformation, information, information.length) === 0) {
+        const win32Code = api.getLastError();
+        api.closeHandle(job);
+        throwWin32(api, 'SetInformationJobObject', win32Code);
+    }
+    return job;
+}
+/**
+ * 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 function spawnSandboxedInherited(api, token, options) {
+    const job = createKillOnCloseJob(api);
+    const stdIn = api.getStdHandle(abi.STD_INPUT_HANDLE);
+    const stdOut = api.getStdHandle(abi.STD_OUTPUT_HANDLE);
+    const stdErr = api.getStdHandle(abi.STD_ERROR_HANDLE);
+    if (isNullPtr(stdIn) || isNullPtr(stdOut) || isNullPtr(stdErr)) {
+        api.closeHandle(job);
+        throwLastError(api, 'GetStdHandle', 'null standard handle');
+    }
+    const makeInheritable = (handle, label) => {
+        if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) {
+            throwLastError(api, 'SetHandleInformation', `${label} (enable inherit)`);
+        }
+    };
+    const restoreInherit = (handle) => {
+        // Best-effort hygiene: the runner spawns nothing else; failures here must
+        // not mask the child outcome, so the result is deliberately unchecked.
+        api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, 0);
+    };
+    makeInheritable(stdIn, 'stdin');
+    makeInheritable(stdOut, 'stdout');
+    makeInheritable(stdErr, 'stderr');
+    const startupInfo = allocStartupInfo();
+    encodeStartupInfo(startupInfo, {
+        cb: abi.STARTUPINFOW_SIZE,
+        dwFlags: abi.STARTF_USESTDHANDLES,
+        hStdInput: stdIn,
+        hStdOutput: stdOut,
+        hStdError: stdErr,
+    });
+    const processInfo = allocProcessInfo();
+    const commandLine = buildCommandLine(options.command, options.args);
+    const created = api.createProcessAsUserW(token, null, commandLine, null, null, 1, // bInheritHandles: the re-enabled std handles must be inheritable
+    abi.CREATE_SUSPENDED, // suspended so job assignment precedes any execution
+    null, options.cwd, startupInfo, processInfo);
+    restoreInherit(stdIn);
+    restoreInherit(stdOut);
+    restoreInherit(stdErr);
+    if (created === 0) {
+        const win32Code = api.getLastError();
+        api.closeHandle(job);
+        throwWin32(api, 'CreateProcessAsUserW', win32Code, `command: ${options.command}, cwd: ${options.cwd}`);
+    }
+    const info = decodeProcessInfo(processInfo);
+    const processHandle = info.hProcess;
+    const threadHandle = info.hThread;
+    if (processHandle === null || threadHandle === null) {
+        api.closeHandle(job);
+        throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`);
+    }
+    if (api.assignProcessToJobObject(job, processHandle) === 0) {
+        // The child was created suspended and is NOT in the kill-on-close job:
+        // closing handles would leave it suspended forever. Terminate it first,
+        // then drop the handles and throw.
+        const win32Code = api.getLastError();
+        api.terminateProcess(processHandle, 1);
+        api.closeHandle(threadHandle);
+        api.closeHandle(processHandle);
+        api.closeHandle(job);
+        throwWin32(api, 'AssignProcessToJobObject', win32Code, `pid ${info.dwProcessId}`);
+    }
+    if (api.resumeThread(threadHandle) === 0xFFFFFFFF) {
+        // Closing the job triggers kill-on-close, so the suspended child dies
+        // instead of hanging until this process exits; the process/thread handles
+        // must go too.
+        const win32Code = api.getLastError();
+        api.closeHandle(threadHandle);
+        api.closeHandle(processHandle);
+        api.closeHandle(job);
+        throwWin32(api, 'ResumeThread', win32Code, `pid ${info.dwProcessId}`);
+    }
+    api.closeHandle(threadHandle);
+    return { pid: info.dwProcessId, process: processHandle, job };
+}
+//# sourceMappingURL=spawn.js.map