pi-codex-auto-review 0.1.0

package/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/windows-sandbox-utils.js

@@ -0,0 +1,1419 @@
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { logForDebugging } from '../utils/debug.js';
+import { generateProxyEnvVars, encodeSandboxedCommand, attributionKeyFor, buildGitConfigEnv, normalizePathForSandbox, containsGlobCharsWin, expandGlobPattern, isUncPath, } from './sandbox-utils.js';
+// Kept on this module's surface for out-of-tree importers; the
+// implementations live in sandbox-utils.ts.
+export { containsGlobCharsWin, stripExtendedPathPrefix, buildGitConfigEnv, isUncPath, } from './sandbox-utils.js';
+import { certThumbprint, generateCa, validateCaPair } from './mitm-ca.js';
+/**
+ * Error thrown by the Windows sandbox backend. Carries a stable
+ * {@link WindowsSandboxErrorCode} on `.code` so callers can branch
+ * without prose-matching `.message`. `instanceof WindowsSandboxError`
+ * narrows `.code` to the union.
+ *
+ * `.subcommand` is set on errors thrown from the `srt-win` spawn
+ * chokepoint (`spawn_failed`, `srt_win_timeout`, `srt_win_nonzero`,
+ * `srt_win_bad_json`) to the first CLI arg (e.g. `'install'`,
+ * `'wfp'`) so a consumer can distinguish install-spawn-failed from
+ * probe-spawn-failed without prose-matching. Unset elsewhere.
+ */
+export class WindowsSandboxError extends Error {
+    constructor(code, message, subcommand) {
+        super(message);
+        this.name = 'WindowsSandboxError';
+        this.code = code;
+        this.subcommand = subcommand;
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────
+export const DEFAULT_WINDOWS_PROXY_PORT_RANGE = [
+    60080, 60089,
+];
+const PWSH_FLAGS = ['-NoProfile', '-Command'];
+/**
+ * Sole normalizer from the cross-platform `binShell?: string |
+ * WindowsBinShell` surface ({@link SandboxManager.wrapWithSandboxArgv})
+ * to a spawnable `{exe, args}` pair. All validation lives here —
+ * {@link wrapCommandWithSandboxWindows} consumes the result verbatim.
+ *
+ * String form: bare token (`'cmd'|'pwsh'|'powershell'`) resolves to
+ * the default install; absolute path to `bash.exe`/`sh.exe`/
+ * `pwsh.exe`/`powershell.exe`/`cmd.exe` keeps the caller's path with
+ * the matching flag shape. Object form: `exe` must be absolute; `args`
+ * pass through unchanged. Throws on anything else — no silent
+ * fallback to cmd.exe.
+ *
+ * Uses `path.win32` explicitly so the function (and its unit test)
+ * is platform-independent.
+ */
+export function parseWindowsBinShell(raw) {
+    const systemRoot = process.env.SystemRoot ?? 'C:\\Windows';
+    const cmdDefault = {
+        exe: path.win32.join(systemRoot, 'System32', 'cmd.exe'),
+        args: ['/d', '/s', '/c'],
+    };
+    if (raw === undefined || raw === null)
+        return cmdDefault;
+    if (typeof raw === 'object') {
+        if (!path.win32.isAbsolute(raw.exe)) {
+            throw new WindowsSandboxError('bin_shell_invalid', `binShell.exe must be an absolute path ` +
+                `(got ${JSON.stringify(raw.exe)})`);
+        }
+        if (!Array.isArray(raw.args)) {
+            throw new WindowsSandboxError('bin_shell_invalid', `binShell.args must be an array (got ${JSON.stringify(raw.args)})`);
+        }
+        return raw;
+    }
+    const rawBase = path.win32.basename(raw);
+    const base = rawBase.toLowerCase();
+    const isAbs = path.win32.isAbsolute(raw);
+    // A relative path with a directory component (`bin\bash.exe`) is
+    // neither a token nor a resolved install — never silently degrade.
+    if (!isAbs && raw !== rawBase) {
+        throw new WindowsSandboxError('bin_shell_invalid', `binShell string must be a bare token or an absolute path ` +
+            `(got ${JSON.stringify(raw)})`);
+    }
+    switch (base) {
+        case 'bash':
+        case 'bash.exe':
+        case 'sh':
+        case 'sh.exe':
+            // Bare 'bash' is ambiguous (WSL vs Git Bash) — require the
+            // resolved install path.
+            if (!isAbs) {
+                throw new WindowsSandboxError('bin_shell_invalid', `binShell bash path must be absolute ` +
+                    `(got ${JSON.stringify(raw)}); pass the resolved Git Bash ` +
+                    `install path`);
+            }
+            return { exe: raw, args: ['-c'] };
+        case 'pwsh':
+        case 'pwsh.exe':
+            return { exe: isAbs ? raw : 'pwsh.exe', args: PWSH_FLAGS };
+        case 'powershell':
+        case 'powershell.exe':
+            return {
+                exe: isAbs
+                    ? raw
+                    : path.win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+                args: PWSH_FLAGS,
+            };
+        case 'cmd':
+        case 'cmd.exe':
+            return isAbs ? { exe: raw, args: cmdDefault.args } : cmdDefault;
+        default:
+            throw new WindowsSandboxError('bin_shell_invalid', `unrecognised binShell ${JSON.stringify(raw)}: expected ` +
+                `'cmd' | 'powershell' | 'pwsh' or an absolute path to ` +
+                `bash.exe/sh.exe/pwsh.exe/powershell.exe`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Binary resolution
+// ────────────────────────────────────────────────────────────────────
+function repoRoot() {
+    // src/sandbox/windows-sandbox-utils.ts → repo root (compiled: dist/sandbox/…)
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '..', '..');
+}
+const nodeArchToDir = { x64: 'x64', arm64: 'arm64' };
+/**
+ * The srt-win binary packaged with this module
+ * (`vendor/srt-win/<arch>/srt-win.exe`, arch from `process.arch`).
+ * Pass explicitly as `windows.srtWin.path` if you want the vendored
+ * exe — {@link resolveSrtWin} never falls back to it implicitly.
+ *
+ * WARNING: in a dev checkout this file may live inside your sandbox
+ * write grant — a sandboxed process could overwrite it; prefer a
+ * binary outside any grant (e.g. your own signed executable).
+ */
+export const VENDORED_SRT_WIN_EXE = path.join(repoRoot(), 'vendor', 'srt-win', nodeArchToDir[process.arch] ?? process.arch, 'srt-win.exe');
+/**
+ * Locate a built `srt-win.exe` for development/CI. Checks, in order:
+ *   1. `<root>/vendor/srt-win/{arch}/srt-win.exe` (prebuilt —
+ *      {@link VENDORED_SRT_WIN_EXE}).
+ *   2. `<root>/vendor/srt-win-src/target/release/srt-win.exe` (local
+ *      `cargo build --release`).
+ *
+ * `<root>` is {@link repoRoot} — `__dirname/../..`, which resolves to the
+ * repo root from `src/sandbox/` and `dist/sandbox/` alike, and to the
+ * package root when installed under `node_modules`.
+ *
+ * This is an explicit helper — nothing calls it as an ambient
+ * default. Production callers set `windows.srtWin.path` (their own
+ * binary, or {@link VENDORED_SRT_WIN_EXE}); see {@link resolveSrtWin}.
+ *
+ * @throws if neither candidate exists.
+ */
+export function getSrtWinPath() {
+    const root = repoRoot();
+    const arch = nodeArchToDir[process.arch];
+    const candidates = [];
+    if (arch) {
+        candidates.push(path.join(root, 'vendor', 'srt-win', arch, 'srt-win.exe'));
+    }
+    candidates.push(path.join(root, 'vendor', 'srt-win-src', 'target', 'release', 'srt-win.exe'));
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    throw new WindowsSandboxError('srt_win_not_found', `srt-win.exe not found. Set windows.srtWin.path or build with ` +
+        `\`cargo build --release --manifest-path vendor/srt-win-src/Cargo.toml\`. ` +
+        `Looked in: ${candidates.join(', ')}`);
+}
+/**
+ * `argv[1]` sentinel a multicall embedder's dispatcher matches
+ * against to route into `srt_win::run_from_args`. Mirrors the Rust
+ * `srt_win::SRT_WIN_DISPATCH_ARG1`; the two MUST stay in sync.
+ * `run_from_args` strips it before clap, so the standalone binary
+ * accepts it harmlessly.
+ */
+export const SRT_WIN_DISPATCH_ARG1 = '--srt-win';
+/**
+ * Resolve the `srt-win` spawn target from config. `cfg.path` is
+ * required and used verbatim; {@link SRT_WIN_DISPATCH_ARG1} is
+ * prepended so a multicall dispatcher routes on `argv[1]` (the
+ * standalone binary strips it harmlessly).
+ *
+ * The path must be explicit because the packaged exe lives under
+ * the package root, which in a dev checkout sits inside the
+ * working-tree write grant (a planted `srt-win.exe` there would be
+ * spawned as the broker). Callers that want the packaged binary
+ * pass {@link VENDORED_SRT_WIN_EXE}.
+ *
+ * @throws if `cfg.path` is unset or names a missing file.
+ */
+export function resolveSrtWin(cfg) {
+    if (cfg?.path === undefined) {
+        throw new WindowsSandboxError('srt_win_not_found', `no srt-win path configured; set windows.srtWin.path (e.g. to the ` +
+            `exported VENDORED_SRT_WIN_EXE constant for the packaged binary)`);
+    }
+    if (!fs.existsSync(cfg.path)) {
+        throw new WindowsSandboxError('srt_win_not_found', `windows.srtWin.path is set to '${cfg.path}' but the file does ` +
+            `not exist`);
+    }
+    return { exe: cfg.path, prependArgs: [SRT_WIN_DISPATCH_ARG1] };
+}
+function runSrtWin(args, opts = {}) {
+    // Callers must thread `srtWin` (SandboxManager resolves once at
+    // `initialize()`); the argless `resolveSrtWin()` throws, telling a
+    // direct helper caller to pass an explicit path.
+    const { exe, prependArgs } = opts.srtWin ?? resolveSrtWin();
+    const r = spawnSync(exe, [...prependArgs, ...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: opts.timeoutMs ?? 15000,
+        ...(opts.stdin !== undefined ? { input: opts.stdin } : {}),
+    });
+    if (r.error) {
+        // ETIMEDOUT means the process ran and spawnSync killed it after
+        // `timeout` — throw a distinct code so every caller surfaces
+        // "timed out" instead of an opaque `exited null`. Callers with a
+        // more specific mapping (e.g. `install_timeout`) catch by code.
+        // Any other `r.error` (ENOENT, EACCES, EINVAL) means the process
+        // never started.
+        if (r.error.code === 'ETIMEDOUT') {
+            throw new WindowsSandboxError('srt_win_timeout', `srt-win ${args.join(' ')} timed out after ` +
+                `${opts.timeoutMs ?? 15000}ms` +
+                (r.signal ? ` (killed by ${r.signal})` : ''), args[0]);
+        }
+        throw new WindowsSandboxError('spawn_failed', `srt-win ${args[0]}: spawn failed: ${r.error.message}`, args[0]);
+    }
+    return {
+        status: r.status,
+        signal: r.signal,
+        stdout: (r.stdout ?? '').trim(),
+        stderr: (r.stderr ?? '').trim(),
+    };
+}
+/**
+ * Async twin of {@link runSrtWin}: same signature, same result shape,
+ * but the event loop stays live. Prefer it for any call reachable
+ * from a UI/render path — the sync variant `spawnSync`-blocks, which
+ * on Windows can be seconds when Defender cold-scans `srt-win.exe`.
+ */
+function runSrtWinAsync(args, opts = {}) {
+    const { exe, prependArgs } = opts.srtWin ?? resolveSrtWin();
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    return new Promise((resolve, reject) => {
+        const child = spawn(exe, [...prependArgs, ...args], {
+            windowsHide: true,
+        });
+        // Manual timer instead of spawn's `timeout` option so a timeout
+        // is distinguishable from an external kill — parity with the
+        // sync variant's ETIMEDOUT branch (same code, same message).
+        let timedOut = false;
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, timeoutMs)
+            : undefined;
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8').on('data', d => (stdout += d));
+        child.stderr?.setEncoding('utf8').on('data', d => (stderr += d));
+        // Swallow EPIPE if the child dies before the stdin write drains.
+        child.stdin?.on('error', () => { }).end(opts.stdin);
+        child.once('error', e => {
+            clearTimeout(timer);
+            reject(new WindowsSandboxError('spawn_failed', `srt-win ${args[0]}: spawn failed: ${e.message}`, args[0]));
+        });
+        child.once('close', (status, signal) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new WindowsSandboxError('srt_win_timeout', `srt-win ${args.join(' ')} timed out after ${timeoutMs}ms` +
+                    (signal ? ` (killed by ${signal})` : ''), args[0]));
+                return;
+            }
+            resolve({ status, signal, stdout: stdout.trim(), stderr: stderr.trim() });
+        });
+    });
+}
+function parseSrtWinJson(args, r) {
+    if (r.status !== 0) {
+        throw new WindowsSandboxError('srt_win_nonzero', `srt-win ${args.join(' ')} exited ${r.status}: ${r.stderr || r.stdout}`, args[0]);
+    }
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch (e) {
+        throw new WindowsSandboxError('srt_win_bad_json', `srt-win ${args.join(' ')}: unparseable JSON output ` +
+            `${JSON.stringify(r.stdout)}: ${e.message}`, args[0]);
+    }
+}
+function runSrtWinJson(args, opts) {
+    return parseSrtWinJson(args, runSrtWin(args, opts));
+}
+async function runSrtWinJsonAsync(args, opts) {
+    return parseSrtWinJson(args, await runSrtWinAsync(args, opts));
+}
+/**
+ * As {@link runSrtWinJson} but parses stdout BEFORE checking the
+ * exit code, so a non-zero exit with the per-path JSON intact
+ * still surfaces every entry. For best-effort teardown helpers
+ * (`acl restore`/`acl revoke`).
+ */
+function runSrtWinJsonAllowFail(args, opts) {
+    const r = runSrtWin(args, opts);
+    let json;
+    try {
+        json = JSON.parse(r.stdout);
+    }
+    catch (e) {
+        throw new WindowsSandboxError('srt_win_bad_json', `srt-win ${args.join(' ')}: unparseable JSON output ` +
+            `${JSON.stringify(r.stdout)}: ${e.message}`, args[0]);
+    }
+    return { ok: r.status === 0, json, stderr: r.stderr };
+}
+function wfpStatusArgs(sublayerGuid) {
+    const args = ['wfp', 'status'];
+    if (sublayerGuid)
+        args.push('--sublayer-guid', sublayerGuid);
+    return args;
+}
+function mapWfpStatus(raw) {
+    return {
+        state: raw.state,
+        filters: raw.filters,
+        ...(raw.port_range && { portRange: raw.port_range }),
+        ...(raw.user_sid && { userSid: raw.user_sid }),
+        ...(raw.hint && { hint: raw.hint }),
+    };
+}
+function mapUserStatus(raw) {
+    return {
+        provisioned: raw.user.exists,
+        ...(raw.user.sid && { sid: raw.user.sid }),
+        groupExists: raw.user.group_exists,
+        ...(raw.user.group_sid && { groupSid: raw.user.group_sid }),
+        inBuiltinUsers: raw.user.in_builtin_users,
+        inSandboxGroup: raw.user.in_sandbox_group,
+        hiddenFromLogon: raw.user.hidden_from_logon,
+        credPresent: raw.cred_present,
+        ...(typeof raw.marker_version === 'number' && {
+            markerVersion: raw.marker_version,
+        }),
+        realUserSid: raw.real_user_sid,
+        ...(raw.ca_cert_thumb && { caCertThumb: raw.ca_cert_thumb }),
+        ...(raw.ca_cert_pem && { caCertPem: raw.ca_cert_pem }),
+    };
+}
+/**
+ * Query sandbox-user provisioning state AND the WFP filter set in a
+ * single `srt-win status` spawn — the same objects
+ * {@link getWindowsSandboxUserStatus} and {@link getWindowsWfpStatus}
+ * return, without paying two subprocess round-trips. Does not require
+ * elevation (WFP degrades to `cannot-read` for a non-elevated caller;
+ * see {@link WindowsWfpStatusResult.hint}).
+ */
+export function checkWindowsSandboxStatus(opts = {}) {
+    const args = ['status'];
+    if (opts.sublayerGuid)
+        args.push('--sublayer-guid', opts.sublayerGuid);
+    const raw = runSrtWinJson(args, {
+        srtWin: opts.srtWin,
+    });
+    return { user: mapUserStatus(raw.user), wfp: mapWfpStatus(raw.wfp) };
+}
+/** Async twin of {@link checkWindowsSandboxStatus}. */
+export async function checkWindowsSandboxStatusAsync(opts = {}) {
+    const args = ['status'];
+    if (opts.sublayerGuid)
+        args.push('--sublayer-guid', opts.sublayerGuid);
+    const raw = await runSrtWinJsonAsync(args, { srtWin: opts.srtWin });
+    return { user: mapUserStatus(raw.user), wfp: mapWfpStatus(raw.wfp) };
+}
+/**
+ * Query the WFP filter set under the given sublayer via live BFE
+ * enumeration. `installed` means at least one srt-win-tagged
+ * `block-user` filter is present. Detection is **tag-based**
+ * (providerData JSON); filters installed by other tooling without the
+ * tag are not counted.
+ *
+ * BFE enumeration is admin-gated — a non-elevated caller gets
+ * `state:"cannot-read"` with a `hint` (not an error). The
+ * non-elevated readiness check is {@link verifyWindowsWfpEgress}.
+ *
+ * Prefer {@link getWindowsWfpStatusAsync}; this variant
+ * `spawnSync`-blocks the event loop.
+ */
+export function getWindowsWfpStatus(opts = {}) {
+    return mapWfpStatus(runSrtWinJson(wfpStatusArgs(opts.sublayerGuid), {
+        srtWin: opts.srtWin,
+    }));
+}
+/** Async twin of {@link getWindowsWfpStatus}. */
+export async function getWindowsWfpStatusAsync(opts = {}) {
+    return mapWfpStatus(await runSrtWinJsonAsync(wfpStatusArgs(opts.sublayerGuid), {
+        srtWin: opts.srtWin,
+    }));
+}
+/**
+ * Behavioral proof that the WFP egress fence is active for the
+ * sandbox user. Binds a local listener on an ephemeral loopback port
+ * outside the WFP loopback-permit range, then spawns `srt-win
+ * runner` as the sandbox user (via `CreateProcessWithLogonW`) to
+ * attempt a direct TCP connect to it. The WFP block-user filter
+ * fires at `ALE_AUTH_CONNECT` — before any packet leaves — so an
+ * active fence yields WSAEACCES immediately and a missing fence lets
+ * the connect through (the kernel completes the handshake against
+ * the listening socket's backlog; no event-loop tick required, so
+ * the synchronous `runSrtWin` is safe). Does not require elevation
+ * and does not depend on any external host.
+ *
+ * `initialize()` calls this once per session, so a stale install
+ * (sandbox user provisioned but filters since removed) fails closed
+ * at session start instead of running every exec with full egress.
+ *
+ * @param opts.target overrides the probe target (skips the local
+ *   listener bind).
+ * @param opts.proxyPortRange the WFP loopback-permit range the
+ *   listener must avoid. Default
+ *   {@link DEFAULT_WINDOWS_PROXY_PORT_RANGE}.
+ * @throws on any outcome other than `blocked` (exit 0).
+ */
+export async function verifyWindowsWfpEgress(opts = {}) {
+    let target = opts.target;
+    let server;
+    if (!target) {
+        // Bind ephemeral; retry if it lands inside the WFP
+        // loopback-permit range (a port in-range would be PERMITted
+        // even with the fence active → false `connected`).
+        const [lo, hi] = opts.proxyPortRange ?? DEFAULT_WINDOWS_PROXY_PORT_RANGE;
+        for (let i = 0; i < 5; i++) {
+            const s = net.createServer();
+            s.listen(0, '127.0.0.1');
+            await once(s, 'listening');
+            const p = s.address().port;
+            if (p < lo || p > hi) {
+                server = s;
+                target = `127.0.0.1:${p}`;
+                break;
+            }
+            s.close();
+        }
+        if (!target) {
+            throw new WindowsSandboxError('wfp_verify_bind_failed', `verifyWindowsWfpEgress: could not bind a loopback ` +
+                `listener outside the WFP permit range [${lo},${hi}] in ` +
+                `5 attempts`);
+        }
+    }
+    try {
+        // 30s: first call after install may create the sandbox user's
+        // profile (LOGON_WITH_PROFILE) via CreateProcessWithLogonW, and
+        // the runner allows itself 2s to connect (runner.rs).
+        const r = runSrtWin(['wfp', 'verify', '--target', target], {
+            timeoutMs: 30000,
+            srtWin: opts.srtWin,
+        });
+        logForDebugging(`[Sandbox Windows] wfp verify exit=${r.status}: ${r.stderr || r.stdout}`);
+        let raw;
+        try {
+            raw = JSON.parse(r.stdout);
+        }
+        catch {
+            // Timeout is thrown as `srt_win_timeout` by `runSrtWin` before
+            // this parse; status=null here means an external signal.
+            // Include signal + stderr so the CI log self-explains instead
+            // of just `exited null with unparseable output ""`.
+            throw new WindowsSandboxError('wfp_verify_unparseable', `WFP egress fence could not be verified — \`srt-win wfp ` +
+                `verify\` exited ${r.status}` +
+                (r.signal ? ` (signal ${r.signal})` : '') +
+                ` with unparseable output ${JSON.stringify(r.stdout)} ` +
+                `(stderr: ${JSON.stringify(r.stderr)})`);
+        }
+        if (r.status === 3) {
+            throw new WindowsSandboxError('wfp_fence_inactive', `WFP egress fence is not active — direct outbound from the ` +
+                `sandbox user to ${raw.target} succeeded. Re-run ` +
+                `\`srt-win install\` (one UAC prompt). (${r.stderr})`);
+        }
+        if (r.status !== 0) {
+            throw new WindowsSandboxError('wfp_verify_inconclusive', `WFP egress fence could not be verified — probe to ` +
+                `${raw.target} was '${raw.egress_probe}' (exit ` +
+                `${r.status}). The fence may be absent. Re-run \`srt-win ` +
+                `install\`. (${r.stderr})`);
+        }
+        return { target: raw.target, stderr: r.stderr };
+    }
+    finally {
+        server?.close();
+    }
+}
+/**
+ * Query the sandbox user account's provisioning state. Each field
+ * is independently observed so a half-provisioned install (e.g.
+ * user exists but credential file missing) is distinguishable.
+ * Does not require elevation.
+ *
+ * Prefer {@link getWindowsSandboxUserStatusAsync}; this variant
+ * `spawnSync`-blocks the event loop.
+ */
+export function getWindowsSandboxUserStatus(opts = {}) {
+    return mapUserStatus(runSrtWinJson(['user', 'status'], { srtWin: opts.srtWin }));
+}
+/** Async twin of {@link getWindowsSandboxUserStatus}. */
+export async function getWindowsSandboxUserStatusAsync(opts = {}) {
+    return mapUserStatus(await runSrtWinJsonAsync(['user', 'status'], {
+        srtWin: opts.srtWin,
+    }));
+}
+/**
+ * Read back the persistent MITM CA the sandbox was installed with
+ * (via `srt-win user trust-ca` / {@link windowsTrustCa}).
+ * Returns `null` when no CA was installed. The PEM is what `srt-win
+ * user status` reconstructs from the DER recorded in the registry.
+ *
+ * On Windows, `tlsTerminate` requires this CA to be present in the
+ * sandbox user's `CurrentUser\Root` (schannel-level trust is an
+ * install-time concern, not per-session); the host calls this from
+ * `initialize()` to fail early with an actionable message when it
+ * isn't.
+ *
+ * @param status pass an already-fetched
+ *   {@link getWindowsSandboxUserStatus} result to avoid a second
+ *   `srt-win user status` spawn.
+ */
+export function getWindowsSandboxCaCert(status, opts = {}) {
+    const u = status ?? getWindowsSandboxUserStatus(opts);
+    if (!u.caCertThumb || !u.caCertPem)
+        return null;
+    return { pem: u.caCertPem, thumb: u.caCertThumb };
+}
+/**
+ * Install (or replace) the MITM CA in the **sandbox user's**
+ * `CurrentUser\Root` and record it in the registry (so
+ * {@link getWindowsSandboxCaCert} surfaces its thumbprint + PEM).
+ * Thin wrapper around `srt-win user trust-ca <path>`. Does NOT
+ * require elevation. Persistent until {@link uninstallWindowsSandbox}
+ * deletes the sandbox user's profile.
+ *
+ * The CA has a separate lifecycle from {@link installWindowsSandbox}
+ * — install provisions the account/filters and never touches the CA;
+ * call this AFTER install when `tlsTerminate` will be used.
+ *
+ * @throws when the sandbox user is not provisioned, the file is not a
+ *   parseable X.509 certificate, or the registry write into the
+ *   sandbox user's hive fails.
+ */
+export function windowsTrustCa(caCertPath, opts = {}) {
+    // 60s: first call may create the sandbox user's profile
+    // (LOGON_WITH_PROFILE) via the one-shot CreateProcessWithLogonW.
+    const r = runSrtWin(['user', 'trust-ca', caCertPath], {
+        timeoutMs: 60000,
+        srtWin: opts.srtWin,
+    });
+    checkTrustCaResult(caCertPath, r);
+}
+/** Async twin of {@link windowsTrustCa} — identical argv and errors. */
+export async function windowsTrustCaAsync(caCertPath, opts = {}) {
+    const r = await runSrtWinAsync(['user', 'trust-ca', caCertPath], {
+        timeoutMs: 60000,
+        srtWin: opts.srtWin,
+    });
+    checkTrustCaResult(caCertPath, r);
+}
+function checkTrustCaResult(caCertPath, r) {
+    logForDebugging(`[Sandbox Windows] user trust-ca exit=${r.status}: ${r.stderr || r.stdout}`);
+    if (r.status !== 0) {
+        throw new WindowsSandboxError('trust_ca_failed', `srt-win user trust-ca '${caCertPath}' failed (exit ` +
+            `${r.status}): ${r.stderr || r.stdout}`);
+    }
+}
+/**
+ * The machine-wide state directory `%ProgramData%\sandbox-runtime`,
+ * mirroring `srt-win`'s `state_db::machine_store_dir()` exactly.
+ * Since the registry move it hosts only the managed CA key material
+ * (`ca\`), which must stay on the filesystem because the broker's
+ * unelevated generate-if-absent self-heal rewrites it; the
+ * credential, marker, and CA record live in
+ * `HKLM\SOFTWARE\sandbox-runtime`. Created and ACL'd by the
+ * elevated `srt-win install`: Administrators own it, BUILTIN\Users
+ * have modify, and the sandbox group carries an explicit
+ * `(OI)(CI)` DENY.
+ */
+export function windowsStateDir() {
+    const programData = process.env.ProgramData;
+    if (!programData)
+        throw new Error('ProgramData is not set');
+    return path.win32.join(programData, 'sandbox-runtime');
+}
+/**
+ * Generate-if-absent a persistent MITM CA under
+ * `{windowsStateDir()}\ca\` and ensure it is trusted in
+ * the sandbox user's `CurrentUser\Root`. Idempotent and unelevated:
+ * a second call with a valid on-disk pair returns it with
+ * `generated: false`. On the machine store the `ca\` subdir is
+ * user-writable by design (BUILTIN\Users modify, inherited from the
+ * install-ACL'd store), so this self-heal keeps working without
+ * admin rights for every user of the machine.
+ *
+ * **Storage.** The pair lives in a single `ca.json = {certPem,
+ * keyPem}` written atomically (tmp+rename) and re-read after every
+ * write, so it is always a matched pair and concurrent brokers
+ * converge on whichever rename landed last. `cert.pem`/`key.pem` are
+ * derived copies for diagnostic tooling; `ca.json` is the source of
+ * truth.
+ *
+ * **Key custody is broker-side.** The MITM proxy runs as the real
+ * user, so the sandbox user never needs to read the key. The `ca/`
+ * subdirectory inherits the machine store's `(OI)(CI)` DACL, which
+ * carries an explicit `sandbox-runtime-users` DENY (see
+ * {@link windowsStateDir}), so `ca.json`/`key.pem` are unreadable
+ * from inside the sandbox with no per-file ACL work here. The key
+ * IS readable (and replaceable) by other REAL local users — an
+ * accepted trade-off of the shared store: the sandbox account is
+ * network-confined by SID-keyed WFP filters regardless of who
+ * spawns it. The certificate reaches the sandboxed child via the
+ * schannel registry write ({@link windowsTrustCa}) and the
+ * trust-bundle env vars — never via these files.
+ *
+ * `SandboxManager.initialize()` calls this on Windows when
+ * `tlsTerminate` is enabled without an explicit
+ * `caCertPath`/`caKeyPath`, then feeds the returned PEMs to
+ * `createMitmCA` — so an embedder gets a stable CA across restarts
+ * without orchestrating generation, storage, or trust itself. Explicit
+ * paths in config bypass this entirely.
+ *
+ * @param opts.force regenerate even if a valid pair is on disk.
+ * @param opts.status pass an already-fetched
+ *   {@link getWindowsSandboxUserStatus} result to skip the
+ *   provisioning check and avoid re-spawning `srt-win user status`
+ *   for the trust reconcile.
+ * @param opts.dir override the CA directory (tests). Default
+ *   `windowsStateDir()/ca`.
+ * @param opts.regenerateWithinDays regenerate if `notAfter` is within
+ *   this many days. Default 30.
+ * @throws when the sandbox user is not provisioned (run
+ *   {@link installWindowsSandbox} first), or the CA directory cannot
+ *   be created.
+ */
+export async function ensurePersistentWindowsCa(opts = {}) {
+    // Provisioning gate. The `ca/` subdirectory's whole custody story
+    // depends on inheriting the state-DB dir's stamped DACL — which
+    // `srt-win install` creates. Never mkdir the state dir here.
+    const status = opts.status ??
+        (await getWindowsSandboxUserStatusAsync({ srtWin: opts.srtWin }));
+    if (!status.provisioned || !status.credPresent) {
+        throw new Error(`ensurePersistentWindowsCa: sandbox user is not provisioned ` +
+            `(user=${status.provisioned}, cred=${status.credPresent}). ` +
+            `Run \`npx sandbox-runtime windows-install\` first.`);
+    }
+    const stateDir = opts.dir ? undefined : windowsStateDir();
+    if (stateDir && !fs.existsSync(stateDir)) {
+        throw new Error(`ensurePersistentWindowsCa: state directory ${stateDir} does not ` +
+            `exist. Run \`npx sandbox-runtime windows-install\` first.`);
+    }
+    const dir = opts.dir ?? path.win32.join(stateDir, 'ca');
+    const jsonPath = path.join(dir, 'ca.json');
+    const certPath = path.join(dir, 'cert.pem');
+    const keyPath = path.join(dir, 'key.pem');
+    const horizonMs = (opts.regenerateWithinDays ?? 30) * 24 * 60 * 60 * 1000;
+    // tmp+rename atomic write. Node's `renameSync` on Windows is
+    // libuv's `MoveFileExW(…, MOVEFILE_REPLACE_EXISTING)` — an atomic
+    // same-volume replace — so `p` is either its previous content or
+    // the full new content, never partial.
+    const atomicWrite = (p, data) => {
+        const tmp = `${p}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, data);
+        fs.renameSync(tmp, p);
+    };
+    // Shared return path: write the derived cert.pem/key.pem siblings
+    // (tooling-only — trust-ca never reads them), reconcile trust, and
+    // assemble the result. Trust is idempotent and ADDITIVE: `srt-win
+    // user trust-ca` writes a per-thumbprint registry key (a rotation
+    // adds the new cert, prior ones stay trusted); the state-DB
+    // `ca_cert` column tracks the latest.
+    const finish = async (certPem, keyPem, thumbprint, generated) => {
+        atomicWrite(certPath, certPem);
+        atomicWrite(keyPath, keyPem);
+        const trusted = generated || status.caCertThumb !== thumbprint;
+        if (trusted) {
+            // Trust from a per-call unique temp, never a shared mutable
+            // path — a concurrent broker's write to `cert.pem` could
+            // otherwise swap the bytes between our write and `srt-win user
+            // trust-ca`'s read, leaving the registry trusting a different
+            // cert than this session's proxy signs with.
+            const t = path.join(dir, `.trust.${process.pid}.${Date.now()}.pem`);
+            fs.writeFileSync(t, certPem);
+            try {
+                await windowsTrustCaAsync(t, { srtWin: opts.srtWin });
+            }
+            finally {
+                fs.rmSync(t, { force: true });
+            }
+        }
+        logForDebugging(`[Sandbox Windows] persistent CA ` +
+            `${generated ? 'generated' : 'reused'} (thumb=${thumbprint}` +
+            `${trusted && !generated ? ', trust reconciled' : ''})`);
+        return {
+            certPem,
+            keyPem,
+            certPath,
+            keyPath,
+            thumbprint,
+            generated,
+            trusted,
+        };
+    };
+    // Read+validate helper. Any read/parse/validate failure returns
+    // undefined (never throws) so a corrupt on-disk pair is not an
+    // error the embedder has to handle.
+    const readValid = () => {
+        let stored;
+        try {
+            stored = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+        }
+        catch (err) {
+            logForDebugging(`[Sandbox Windows] persistent CA ca.json unreadable ` +
+                `(${err.message})`, { level: 'warn' });
+            return undefined;
+        }
+        if (typeof stored.certPem !== 'string' || typeof stored.keyPem !== 'string')
+            return undefined;
+        const v = validateCaPair(stored.certPem, stored.keyPem);
+        if (!v.ok) {
+            logForDebugging(`[Sandbox Windows] persistent CA invalid (${v.reason})`, {
+                level: 'warn',
+            });
+            return undefined;
+        }
+        return {
+            certPem: stored.certPem,
+            keyPem: stored.keyPem,
+            thumbprint: v.thumbprint,
+            notAfter: v.notAfter,
+        };
+    };
+    // Reuse when ca.json exists, validates, and isn't expiring inside
+    // the horizon.
+    if (!opts.force) {
+        const on = readValid();
+        if (on && on.notAfter.getTime() - Date.now() > horizonMs) {
+            return await finish(on.certPem, on.keyPem, on.thumbprint, false);
+        }
+        if (on) {
+            logForDebugging(`[Sandbox Windows] persistent CA expiring ` +
+                `${on.notAfter.toISOString()}; regenerating`, { level: 'warn' });
+        }
+    }
+    // Generate. `ca/` (not the state dir) is mkdir'd here so it
+    // inherits the parent's (OI)(CI) DACL. After the atomic write,
+    // RE-READ ca.json and use that content: a concurrent broker's
+    // rename may have won, and returning our own PEMs would diverge
+    // from disk — the re-read makes every racer converge.
+    fs.mkdirSync(dir, { recursive: true });
+    // Best-effort sweep of stale `*.tmp.*` / `.trust.*` files from
+    // crashed prior brokers.
+    try {
+        const cutoff = Date.now() - 5 * 60 * 1000;
+        for (const f of fs.readdirSync(dir)) {
+            if (!f.includes('.tmp.') && !f.startsWith('.trust.'))
+                continue;
+            const p = path.join(dir, f);
+            if (fs.statSync(p).mtimeMs < cutoff)
+                fs.rmSync(p, { force: true });
+        }
+    }
+    catch {
+        // sweep is best-effort; a leftover tmp is harmless.
+    }
+    const gen = generateCa({ cn: 'sandbox-runtime persistent CA' });
+    atomicWrite(jsonPath, JSON.stringify({ certPem: gen.certPem, keyPem: gen.keyPem }));
+    const on = readValid();
+    // `on` can only be undefined if a concurrent broker overwrote with
+    // an invalid pair (which the tmp+rename path can't produce) — so
+    // treat as our own write having landed.
+    const { certPem, keyPem, thumbprint } = on ?? {
+        certPem: gen.certPem,
+        keyPem: gen.keyPem,
+        thumbprint: certThumbprint(gen.certPem),
+    };
+    return await finish(certPem, keyPem, thumbprint, true);
+}
+/**
+ * Default spawn budget for the self-elevating install/uninstall. The Windows
+ * UAC consent dialog auto-dismisses after ~2 minutes, so anything shorter
+ * risks killing the subprocess while a legitimate approval is still pending
+ * (elevation is not retracted when the parent dies, so a late approval after
+ * we have timed out would half-complete).
+ */
+const INSTALL_TIMEOUT_MS = 120000;
+/** Effective spawn budget for the self-elevating install/uninstall. */
+function installTimeoutMs(opts) {
+    return opts.timeoutMs ?? INSTALL_TIMEOUT_MS;
+}
+function installArgs(opts) {
+    const args = ['install'];
+    if (opts.sublayerGuid)
+        args.push('--sublayer-guid', opts.sublayerGuid);
+    if (opts.proxyPortRange) {
+        args.push('--proxy-port-range', `${opts.proxyPortRange[0]}-${opts.proxyPortRange[1]}`);
+    }
+    if (opts.sandboxUser)
+        args.push('--sandbox-user', opts.sandboxUser);
+    if (opts.force)
+        args.push('--force');
+    return args;
+}
+/**
+ * Re-throw a `srt_win_timeout` from the install spawn as the more
+ * specific `install_timeout` (the UAC prompt is the usual cause).
+ * Shared by the sync and async install variants.
+ */
+function remapInstallTimeout(e) {
+    if (e instanceof WindowsSandboxError && e.code === 'srt_win_timeout') {
+        throw new WindowsSandboxError('install_timeout', `srt-win install timed out — the UAC prompt may still be open. ` +
+            `Re-run when ready to grant elevation. (${e.message})`);
+    }
+    throw e;
+}
+// srt-win install exit-code contract:
+//   0  ok
+//   10 user cancelled UAC elevation
+//   12 WFP install failed
+//   13 already installed with different config (use --force)
+//   14 sandbox-user provisioning failed
+//   17 ambient write-deny stamping failed
+//   1  other error (stderr has detail)
+// Throws on any failure code; the caller reads back state on 0/10.
+function throwOnInstallFailure(r) {
+    logForDebugging(`[Sandbox Windows] install exit=${r.status}: ${r.stderr || r.stdout}`);
+    if (r.status === 0 || r.status === 10)
+        return;
+    const out = r.stderr || r.stdout;
+    switch (r.status) {
+        case 12:
+            throw new WindowsSandboxError('install_wfp_failed', `srt-win install: WFP filter install failed: ${out}`);
+        case 14:
+            throw new WindowsSandboxError('install_user_failed', `srt-win install: sandbox user provisioning failed: ${out}`);
+        case 13:
+            throw new WindowsSandboxError('install_config_conflict', `srt-win install: filters already exist under this sublayer with ` +
+                `a different port range or sandbox-user name. Pass ` +
+                `{force: true} to replace, or pick a different sublayerGuid. ` +
+                `Output: ${out}`);
+        case 17:
+            throw new WindowsSandboxError('install_ambient_failed', `srt-win install: ambient write-deny stamping failed (stock ` +
+                `world-writable system dirs could not be deny-stamped for the ` +
+                `sandbox user): ${out}`);
+        default:
+            throw new WindowsSandboxError('install_failed', `srt-win install failed (exit ${r.status}): ${out}`);
+    }
+}
+/**
+ * One-shot install: provisions the `srt-sandbox` user account and
+ * installs the user-SID-keyed WFP filter set — all in a single
+ * self-elevating process (one UAC prompt). Idempotent; re-running
+ * rotates the sandbox user's password.
+ *
+ * Network for the calling user is **not disrupted**: the filters key
+ * on the `srt-sandbox` user's SID, so the broker, services, and
+ * every other principal fall through to default-permit. No logout
+ * is required.
+ *
+ * Returns the post-call WFP + sandbox-user state. If the user
+ * cancels the UAC prompt this returns `{cancelled: true, …}` rather
+ * than throwing — cancellation is a user choice, not an error.
+ *
+ * Prefer {@link installWindowsSandboxAsync}; this variant
+ * `spawnSync`-blocks the event loop for the full UAC-prompt wait
+ * (up to `timeoutMs`).
+ *
+ * @throws on user/WFP creation failure, or if filters already exist
+ *   under `sublayerGuid` with a different port range and `force` is
+ *   not set.
+ */
+export function installWindowsSandbox(opts = {}) {
+    const srtWin = opts.srtWin ?? resolveSrtWin();
+    let r;
+    try {
+        r = runSrtWin(installArgs(opts), {
+            timeoutMs: installTimeoutMs(opts),
+            srtWin,
+        });
+    }
+    catch (e) {
+        remapInstallTimeout(e);
+    }
+    throwOnInstallFailure(r);
+    const state = checkWindowsSandboxStatus({
+        sublayerGuid: opts.sublayerGuid,
+        srtWin,
+    });
+    return r.status === 10 ? { ...state, cancelled: true } : state;
+}
+/**
+ * Async twin of {@link installWindowsSandbox}. Same options, same
+ * return type, same throw semantics. The UAC prompt is still modal,
+ * but the event loop stays live — spinners keep painting and timers
+ * keep firing.
+ */
+export async function installWindowsSandboxAsync(opts = {}) {
+    const srtWin = opts.srtWin ?? resolveSrtWin();
+    let r;
+    try {
+        r = await runSrtWinAsync(installArgs(opts), {
+            timeoutMs: installTimeoutMs(opts),
+            srtWin,
+        });
+    }
+    catch (e) {
+        remapInstallTimeout(e);
+    }
+    throwOnInstallFailure(r);
+    const state = await checkWindowsSandboxStatusAsync({
+        sublayerGuid: opts.sublayerGuid,
+        srtWin,
+    });
+    return r.status === 10 ? { ...state, cancelled: true } : state;
+}
+/**
+ * Remove the WFP filter set under `sublayerGuid` and the
+ * `srt-sandbox` account, its credential file, and the setup marker
+ * (one UAC prompt). Idempotent.
+ *
+ * @returns `{cancelled: true}` if the user dismissed UAC.
+ */
+export function uninstallWindowsSandbox(opts = {}) {
+    const args = ['uninstall'];
+    if (opts.sublayerGuid)
+        args.push('--sublayer-guid', opts.sublayerGuid);
+    if (opts.keepUser)
+        args.push('--keep-user');
+    const r = runSrtWin(args, {
+        timeoutMs: installTimeoutMs(opts),
+        srtWin: opts.srtWin,
+    });
+    logForDebugging(`[Sandbox Windows] uninstall exit=${r.status}: ${r.stderr || r.stdout}`);
+    if (r.status === 10)
+        return { cancelled: true };
+    if (r.status !== 0) {
+        throw new WindowsSandboxError('uninstall_failed', `srt-win uninstall failed (exit ${r.status}): ${r.stderr || r.stdout}`);
+    }
+    return {};
+}
+/**
+ * Resolve any Windows filesystem-config path list — `allowRead`/
+ * `allowWrite` grants and `denyRead`/`denyWrite` stamps — to
+ * concrete paths via the single platform-aware
+ * {@link normalizePathForSandbox} chokepoint (Linux/macOS parity:
+ * point-in-time expansion at session initialize, not per-exec).
+ * Glob patterns are expanded; non-glob paths are normalized and
+ * returned 1:1. Directory targets are accepted — the additive
+ * sandbox-user ACE carries `(OI)(CI)` so it covers the subtree.
+ *
+ * Missing literal paths are dropped for `mode: 'grant'` (a grant on
+ * nothing is meaningless) but PASSED THROUGH for `mode: 'deny'` —
+ * `srt-win acl stamp` materializes a placeholder chain (mkdirs each
+ * missing intermediate + creates an empty leaf) and stamps every
+ * created component, so the deny lands on the exact target path
+ * and the sandbox user cannot create/write/delete it. A trailing
+ * `/` or `\` on the raw input means "the target is a directory":
+ * the placeholder leaf is created as an empty directory instead of
+ * an empty file, so a later `mkdirSync({recursive: true})` on the
+ * real path succeeds. Glob results (existing-by-construction) drop
+ * on a stat miss regardless of mode: a glob is inherently "match
+ * existing".
+ *
+ * **UNC exception:** a `\\server\share\…` **literal** passes through
+ * raw in BOTH modes (no existence probe — see {@link isUncPath});
+ * `srt-win` soft-drops a missing UNC deny target rather than
+ * materializing a placeholder chain on an SMB share. A UNC **glob**
+ * still walks the share (user-trusted).
+ */
+export function expandWindowsFsPaths(patterns, opts) {
+    const out = new Set();
+    for (const raw of patterns) {
+        const norm = normalizePathForSandbox(raw);
+        const isGlob = containsGlobCharsWin(norm);
+        // UNC literal: pass raw (no stat) — see {@link isUncPath}. A
+        // UNC glob falls through to expandGlobPattern below.
+        if (isUncPath(norm) && !isGlob) {
+            out.add(norm);
+            continue;
+        }
+        const candidates = isGlob
+            ? expandGlobPattern(norm, { caseInsensitive: true })
+            : [norm];
+        for (const c of candidates) {
+            const st = fs.statSync(c, { throwIfNoEntry: false });
+            if (!st) {
+                // normalizePathForSandbox (path.resolve) strips the
+                // trailing separator (the dir-leaf signal — see doc);
+                // re-apply it from the raw input.
+                if (opts?.mode === 'deny' && !isGlob) {
+                    out.add(/[\\/]$/.test(raw) && !/[\\/]$/.test(c) ? c + '\\' : c);
+                }
+                continue;
+            }
+            out.add(c);
+        }
+    }
+    return [...out];
+}
+/**
+ * Parse a structured `srt-win exec` error from its stderr. `exec`
+ * emits typed launch failures as a single JSON line
+ * `{"code":…,"message":…}` alongside a distinct exit code —
+ * `mapped_drive_cwd` is exit **16**. Embedders that spawn the
+ * `{argv, env}` from {@link wrapCommandWithSandboxWindows} call
+ * this on non-zero exit to surface an actionable
+ * {@link WindowsSandboxError} instead of a bare status.
+ *
+ * Returns `undefined` when no typed-error line is present (the
+ * common case: exit status is the child's own). Gate on the
+ * `srt-win` exit code before calling — the sandboxed child's own
+ * stderr is pumped through unchanged, so a child that happened to
+ * print a matching JSON line would parse here too.
+ */
+export function parseWindowsSandboxError(stderr) {
+    for (const line of stderr.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t.startsWith('{') || !t.includes('"code"'))
+            continue;
+        try {
+            const j = JSON.parse(t);
+            if (j.code === 'mapped_drive_cwd') {
+                // The canonical class carries `code`/`subcommand`; `drive`
+                // is this one code's extra payload, attached as a plain
+                // property rather than forking the class.
+                return Object.assign(new WindowsSandboxError('mapped_drive_cwd', j.message ?? 'mapped/network-drive working directory', 'exec'), { drive: j.drive });
+            }
+        }
+        catch {
+            // not our line
+        }
+    }
+    return undefined;
+}
+/**
+ * Apply the file-deny ACE set for one host session: an additive
+ * `(D;OICI;mask;;;<sb-SID>)` on the target plus a
+ * `(D;OICI;FILE_DELETE_CHILD;;;<sb-SID>)` on the parent — no
+ * PROTECTED rewrite, no SD snapshot. Idempotent and refcounted via
+ * srt-win's `working_aces` table.
+ *
+ * Inputs are passed verbatim to `srt-win` (which canonicalizes and
+ * rejects globs). Callers that accept globs should pre-expand via
+ * {@link expandWindowsFsPaths}.
+ *
+ * @throws on exit ≠ 0 — including exit 2 (one or more inputs
+ *   skipped). srt-win stamps the resolvable inputs before exiting
+ *   2, so on throw the caller should call {@link restoreWindowsAcl}
+ *   to release whatever WAS stamped.
+ */
+export function stampWindowsAcl(opts) {
+    const holder = opts.holderPid ?? process.pid;
+    const stdin = JSON.stringify({
+        denyRead: opts.denyRead,
+        denyWrite: opts.denyWrite,
+    });
+    const r = runSrtWin([
+        'acl',
+        'stamp',
+        '--holder-pid',
+        `${holder}`,
+        '--sandbox-user-sid',
+        opts.sandboxUserSid,
+    ], { timeoutMs: 60000, stdin, srtWin: opts.srtWin });
+    logForDebugging(`[Sandbox Windows] acl stamp exit=${r.status}: ${r.stderr || r.stdout}`);
+    if (r.status !== 0) {
+        throw new WindowsSandboxError('acl_stamp_failed', `srt-win acl stamp exited ${r.status} ` +
+            (r.status === 2 ? '(partial — some inputs skipped)' : '(failed)') +
+            `: ${r.stderr || r.stdout}`);
+    }
+}
+/**
+ * Release this holder's deny ACEs and remove the sandbox-user ACE
+ * on any path whose refcount falls to zero. Best-effort (does not
+ * throw on per-path anomalies); returns per-path outcomes for the
+ * caller to surface. Returns `undefined` only when `srt-win`
+ * itself failed (no JSON to parse).
+ */
+export function restoreWindowsAcl(opts) {
+    const holder = opts.holderPid ?? process.pid;
+    // Don't let a teardown helper throw — the caller's reset() must
+    // complete. runSrtWinJsonAllowFail parses stdout before checking
+    // the exit code, so a non-zero exit with the per-path JSON intact
+    // still surfaces every entry to reset()'s loop. Only spawn-fail
+    // / unparseable output throws → log and return undefined.
+    try {
+        const r = runSrtWinJsonAllowFail([
+            'acl',
+            'restore',
+            '--holder-pid',
+            `${holder}`,
+            '--sandbox-user-sid',
+            opts.sandboxUserSid,
+            '--json',
+        ], { timeoutMs: 60000, srtWin: opts.srtWin });
+        if (!r.ok) {
+            logForDebugging(`[Sandbox Windows] acl restore exited non-zero (per-path ` +
+                `outcomes preserved): ${r.stderr}`, { level: 'error' });
+        }
+        // Pre- same-user-removal builds emit `{paths, parents}`; post-
+        // emit a flat array. Flatten either so reset()'s logging loop
+        // is shape-agnostic across the transition.
+        return Array.isArray(r.json)
+            ? r.json
+            : [...(r.json.paths ?? []), ...(r.json.parents ?? [])];
+    }
+    catch (e) {
+        logForDebugging(`[Sandbox Windows] acl restore: ${e.message}`, {
+            level: 'error',
+        });
+        return undefined;
+    }
+}
+/**
+ * Apply per-session additive `(OI)(CI)` ALLOW ACEs for the sandbox
+ * user on each path. The sandbox user has no inherent rights on
+ * real-user-owned files; this is what makes the working tree (and
+ * explicit `allowRead`/`allowWrite` paths) reachable from the
+ * child. Idempotent and refcounted via srt-win's `working_aces`
+ * table.
+ *
+ * @throws on exit ≠ 0. On throw the caller should call
+ *   {@link revokeWindowsAcl} to release whatever WAS granted.
+ */
+export function grantWindowsAcl(opts) {
+    const holder = opts.holderPid ?? process.pid;
+    const stdin = JSON.stringify({ read: opts.read, write: opts.write });
+    const r = runSrtWin([
+        'acl',
+        'grant',
+        '--holder-pid',
+        `${holder}`,
+        '--sandbox-user-sid',
+        opts.sandboxUserSid,
+    ], { timeoutMs: 60000, stdin, srtWin: opts.srtWin });
+    logForDebugging(`[Sandbox Windows] acl grant exit=${r.status}: ${r.stderr || r.stdout}`);
+    if (r.status !== 0) {
+        throw new WindowsSandboxError('acl_grant_failed', `srt-win acl grant exited ${r.status}: ${r.stderr || r.stdout}`);
+    }
+}
+/**
+ * Release this holder's grants and remove the sandbox-user ACE on
+ * any path whose refcount falls to zero. Best-effort (does not
+ * throw); logs anomalies.
+ */
+export function revokeWindowsAcl(opts) {
+    const holder = opts.holderPid ?? process.pid;
+    try {
+        const r = runSrtWinJsonAllowFail([
+            'acl',
+            'revoke',
+            '--holder-pid',
+            `${holder}`,
+            '--sandbox-user-sid',
+            opts.sandboxUserSid,
+            '--json',
+        ], { timeoutMs: 60000, srtWin: opts.srtWin });
+        if (!r.ok) {
+            logForDebugging(`[Sandbox Windows] acl revoke exited non-zero: ${r.stderr}`, { level: 'error' });
+        }
+        return r.json;
+    }
+    catch (e) {
+        logForDebugging(`[Sandbox Windows] acl revoke: ${e.message}`, {
+            level: 'error',
+        });
+        return undefined;
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Wrap
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Build the spawn descriptor for running `command` inside the Windows
+ * sandbox: an `argv` array plus the `env` to spawn it with.
+ *
+ * Caller MUST spawn the result with `{shell: false}` — that is the
+ * security boundary that keeps untrusted bytes off the host's shell
+ * (the inner `cmd.exe /c` runs INSIDE the sandbox; see
+ * `vendor/srt-win-src/src/launch.rs` `build_cmdline` for the passthrough
+ * rationale) — AND with the returned `env`.
+ *
+ * Proxy configuration is single-sourced by {@link generateProxyEnvVars}
+ * (the same canonical builder used on macOS/Linux). `srt-win exec`
+ * takes no `--http-proxy` / `--socks-proxy` flags and synthesizes no
+ * proxy env. The two-hop runner starts with the SANDBOX user's
+ * profile env (`USERPROFILE`/`TEMP` isolated) and overlays exactly
+ * what we pass as `--env` — built here from the broker's `PATH` plus
+ * the generated proxy set.
+ */
+export function wrapCommandWithSandboxWindows(p) {
+    const { exe, prependArgs } = p.srtWin ?? resolveSrtWin();
+    // Generated proxy + CA-trust env. Single-sourced here so the
+    // same object feeds (a) the spawn env merge below and (b) the
+    // explicit `--env` overlay for the runner.
+    //
+    // The CA trust-bundle path is emitted with forward slashes:
+    // msys2's POSIX-path conversion leaves `C:/…` alone and every
+    // tool we set the var for (curl, git, node, python, …) accepts
+    // forward slashes on Windows; backslashes would be mangled if
+    // the value passes through a bash command line. Schannel-level
+    // trust comes from the registry write `srt-win user trust-ca`
+    // did at install time; the env-var layer here covers the
+    // OpenSSL-backed tools.
+    const generated = envListToObject(generateProxyEnvVars(p.httpProxyPort, p.socksProxyPort, p.caCertPath?.replace(/\\/g, '/'), p.proxyAuthToken, undefined, encodeSandboxedCommand(attributionKeyFor(p.command, p.commandId))));
+    // TMPDIR is a POSIX path meant for the macOS/Linux FS sandbox — it
+    // serves no purpose on Windows and breaks msys2 tools (mktemp etc.).
+    delete generated.TMPDIR;
+    // NO_PROXY=localhost,127.0.0.1,… is correct on POSIX where seatbelt/
+    // bwrap allow direct loopback: a NO_PROXY match makes the client
+    // connect directly and it works. On Windows the WFP fence blocks
+    // ALL direct connects from the sandbox user — including loopback
+    // outside the proxy-port PERMIT range — so NO_PROXY makes clients
+    // bypass the proxy and hit the fence; every localhost/127.0.0.1
+    // request fails. Consumers currently work around with
+    // `curl --noproxy ""`. Drop NO_PROXY here so localhost goes through
+    // the proxy (which connects on the child's behalf, from the broker's
+    // SID, and is not fenced).
+    delete generated.NO_PROXY;
+    delete generated.no_proxy;
+    // GIT_CONFIG_* set — safe.directory (dubious-ownership) + the
+    // schannel CA knobs. Composed against setEnvVars so a caller
+    // that already emits GIT_CONFIG_COUNT keeps its entries.
+    const gitCfg = buildGitConfigEnv({
+        safeDirs: [
+            p.cwd ?? process.cwd(),
+            ...(p.allowWrite ?? []),
+            ...(p.gitSafeDirectories ?? []),
+        ],
+        schannelCa: p.caCertPath !== undefined,
+        baseEnv: p.setEnvVars,
+    });
+    const argv = [exe, ...prependArgs, 'exec'];
+    if (p.quiet !== false)
+        argv.push('--quiet');
+    for (const d of p.denyRead ?? [])
+        argv.push('--deny-read', d);
+    for (const d of p.denyWrite ?? [])
+        argv.push('--deny-write', d);
+    // The two-hop runner starts with the SANDBOX user's profile env
+    // (USERPROFILE/TEMP isolated) and overlays exactly what we pass as
+    // `--env`. The broker does NOT enumerate its own env — the overlay
+    // is built here from the broker's PATH, the mode:'mask' sentinel
+    // set, the generated proxy set, and the GIT_CONFIG_* set.
+    // Sentinels precede `generated` so a caller masking e.g.
+    // `HTTPS_PROXY` cannot break the sandbox's own proxy plumbing —
+    // same precedence as the macOS/Linux `env -u … VAR=…
+    // sandbox-exec` order. `gitCfg` is last so its GIT_CONFIG_COUNT
+    // (which composes against setEnvVars) wins.
+    const overlay = {
+        PATH: process.env.PATH,
+        PATHEXT: process.env.PATHEXT,
+        ...(p.setEnvVars ?? {}),
+        ...generated,
+        ...gitCfg,
+    };
+    for (const [k, v] of Object.entries(overlay)) {
+        if (v !== undefined)
+            argv.push('--env', `${k}=${v}`);
+    }
+    argv.push('--');
+    // Inner shell: `{exe, args}` from parseWindowsBinShell — the SOLE
+    // normalizer. `p.command` lands as a single argv element; srt-win's
+    // `build_cmdline` MSVCRT-quotes it (or wraps in one outer "…" for
+    // cmd /s) so the inner shell receives it intact. See launch.rs.
+    const sh = p.binShell ?? parseWindowsBinShell(undefined);
+    argv.push(sh.exe, ...sh.args, p.command);
+    // CreateProcessW's lpCommandLine is capped at 32 767 WCHARs.
+    // Node's `shell:false` spawn builds it by MSVCRT-quoting each
+    // argv element and joining with spaces; ~30 000 leaves headroom
+    // for the quote overhead the estimate doesn't model.
+    const cmdlineEstimate = argv.reduce((n, a) => n + a.length + 3, 0);
+    if (cmdlineEstimate > 30000) {
+        throw new WindowsSandboxError('argv_too_long', `Windows sandbox argv is ~${cmdlineEstimate} chars ` +
+            `(CreateProcessW limit is 32 767).`);
+    }
+    // The two-hop runner starts with a FRESH `srt-sandbox` profile
+    // env (`lpEnvironment = NULL` + `LOGON_WITH_PROFILE`), so the
+    // broker process's environment never reaches the child. The
+    // returned `env` is the spawn env for the broker (srt-win)
+    // process only; the child sees the `--env` overlay built into
+    // `argv` above (PATH/PATHEXT + mode:'mask' sentinels + proxy).
+    const env = { ...process.env, ...generated };
+    return { argv, env };
+}
+/**
+ * Parse a list of `KEY=VALUE` strings (as produced by
+ * {@link generateProxyEnvVars}) into an object. Splits on the FIRST
+ * `=` only, so values containing `=` survive intact.
+ */
+function envListToObject(list) {
+    const out = {};
+    for (const entry of list) {
+        const eq = entry.indexOf('=');
+        if (eq === -1)
+            continue;
+        out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return out;
+}
+// ────────────────────────────────────────────────────────────────────
+// Dependency / readiness check
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Install instructions, surfaced verbatim in error messages.
+ */
+export function windowsInstallInstructions(sublayerGuid) {
+    const sl = sublayerGuid ? ` --sublayer-guid ${sublayerGuid}` : '';
+    return (`Windows sandbox needs a one-time install (one UAC prompt):\n` +
+        `  npx sandbox-runtime windows-install\n` +
+        `  — or call installWindowsSandbox(), or run ` +
+        `\`srt-win.exe install${sl}\` directly.\n` +
+        `No logout is needed: the WFP filter keys on the dedicated ` +
+        `\`srt-sandbox\` user's SID, so your network is unaffected.`);
+}
+function settle(fn) {
+    try {
+        return { status: 'fulfilled', value: fn() };
+    }
+    catch (e) {
+        return { status: 'rejected', reason: e };
+    }
+}
+/**
+ * Interpret the two probe results into a {@link SandboxDependencyCheck}.
+ * Shared by the sync and async `checkWindowsDependencies*` variants so
+ * both produce byte-identical `errors[]` for the same underlying state.
+ *
+ * `getWfp` is lazy: the sync caller's thunk spawns `wfp status` on
+ * demand (preserving the short-circuit — no second spawn when
+ * `user status` already failed); the async caller has already run
+ * both probes concurrently and its thunk returns the settled result.
+ */
+function interpretDependencyProbes(sublayerGuid, user, getWfp) {
+    const errors = [];
+    const warnings = [];
+    // 2. Sandbox user provisioned + credential readable.
+    if (user.status === 'rejected') {
+        errors.push(`srt-win user status failed: ${user.reason.message}`);
+        return { errors, warnings };
+    }
+    const us = user.value;
+    if (!us.provisioned || !us.credPresent) {
+        errors.push(`Sandbox user is not provisioned (user=${us.provisioned}, ` +
+            `cred=${us.credPresent}). ` +
+            windowsInstallInstructions(sublayerGuid));
+    }
+    // 3. WFP filters installed under the sublayer. BFE enumeration is
+    // admin-gated; `cannot-read` is informational only — the
+    // BEHAVIORAL check (`verifyWindowsWfpEgress`) runs at
+    // `initialize()` and is what actually fails closed.
+    const wfp = getWfp();
+    if (wfp.status === 'rejected') {
+        errors.push(`srt-win wfp status failed: ${wfp.reason.message}`);
+        return { errors, warnings };
+    }
+    const ws = wfp.value;
+    if (ws.state === 'cannot-read') {
+        logForDebugging(`[Sandbox Windows] wfp status cannot-read (non-elevated): ${ws.hint}`);
+    }
+    else if (ws.state !== 'installed') {
+        // 'absent'. If the user is also not-provisioned, the user-state
+        // error above already gave the right instruction; don't repeat.
+        if (us.provisioned && us.credPresent) {
+            errors.push(`WFP filters not installed under sublayer ` +
+                `${sublayerGuid ?? '(default)'}. ` +
+                windowsInstallInstructions(sublayerGuid));
+        }
+    }
+    else if (ws.portRange) {
+        logForDebugging(`[Sandbox Windows] WFP installed: ${ws.filters} filters, ` +
+            `proxy port range ${ws.portRange[0]}-${ws.portRange[1]}`);
+    }
+    return { errors, warnings };
+}
+/**
+ * Check the Windows backend is ready to sandbox. Errors block
+ * `initialize()`; warnings are informational.
+ *
+ * Prefer {@link checkWindowsDependenciesAsync}; this variant
+ * `spawnSync`-blocks the event loop on two `srt-win.exe` spawns
+ * (Windows Defender cold-scan can add seconds).
+ */
+export function checkWindowsDependencies(opts = {}) {
+    // 1. Binary present. The argless `resolveSrtWin()` throws (no
+    // implicit vendor fallback) — surfaced as a dependency error
+    // telling the caller to thread an explicit path.
+    let srtWin;
+    try {
+        srtWin = opts.srtWin ?? resolveSrtWin();
+    }
+    catch (e) {
+        return { errors: [e.message], warnings: [] };
+    }
+    logForDebugging(`[Sandbox Windows] using srt-win at ${srtWin.exe}`);
+    return interpretDependencyProbes(opts.sublayerGuid, settle(() => getWindowsSandboxUserStatus({ srtWin })), 
+    // Lazy: spawned only if user-status succeeded (short-circuit).
+    () => settle(() => getWindowsWfpStatus({ sublayerGuid: opts.sublayerGuid, srtWin })));
+}
+/**
+ * Async twin of {@link checkWindowsDependencies}. Same result for the
+ * same underlying state; runs the two `srt-win` probes concurrently
+ * and never blocks the event loop.
+ */
+export async function checkWindowsDependenciesAsync(opts = {}) {
+    let srtWin;
+    try {
+        srtWin = opts.srtWin ?? resolveSrtWin();
+    }
+    catch (e) {
+        return { errors: [e.message], warnings: [] };
+    }
+    logForDebugging(`[Sandbox Windows] using srt-win at ${srtWin.exe}`);
+    const [user, wfp] = await Promise.allSettled([
+        getWindowsSandboxUserStatusAsync({ srtWin }),
+        getWindowsWfpStatusAsync({ sublayerGuid: opts.sublayerGuid, srtWin }),
+    ]);
+    return interpretDependencyProbes(opts.sublayerGuid, user, () => wfp);
+}
+//# sourceMappingURL=windows-sandbox-utils.js.map