@sysid/sandbox-runtime-improved 0.0.61-sysid.1 → 0.0.64-sysid.1

package/dist/sandbox/windows-sandbox-utils.d.ts

@@ -1,67 +1,67 @@
 export { containsGlobCharsWin, stripExtendedPathPrefix, } from './sandbox-utils.js';
 import type { SandboxDependencyCheck } from './linux-sandbox-utils.js';
+import type { SrtWinConfig } from './sandbox-config.js';
 /**
  * Windows sandbox backend.
  *
  * Network isolation is enforced by `srt-win.exe` — a Rust helper that
- * manages a local discriminator group, a machine-wide WFP filter set
- * keyed on that group's SID, and an `exec` subcommand that spawns the
- * target under a restricted token (group flipped deny-only) inside a
- * hardened job. The sandboxed child reaches the host only via the JS
- * http/socks proxies, which `srt-win exec` points at via env vars.
+ * provisions a dedicated `srt-sandbox` local user account, installs a
+ * machine-wide WFP filter set keyed on that account's SID, and
+ * provides an `exec` subcommand that spawns the target via a two-hop
+ * launch (broker → `CreateProcessWithLogonW(runner)` → runner →
+ * restricted-token child) under `srt-sandbox`. The sandboxed child
+ * reaches the host only via the JS mux proxy, which the caller
+ * passes in via `--env`.
+ *
+ * The separate-user account structurally closes the surrogate-spawn
+ * class (schtasks, `PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`, BITS,
+ * RunAs="Interactive User" COM): the child's token carries a
+ * different user SID, so it cannot reach real-user processes, tasks
+ * register under `srt-sandbox`, and the user-SID WFP filter fences
+ * `srt-sandbox` egress regardless of how the child was spawned.
  *
  * This module is a thin wrapper around the `srt-win` CLI; all status
- * comes from live enumeration (group via `LookupAccountNameW` +
- * token-membership check; WFP via providerData-tag enumeration under
- * the configured sublayer). There is no marker file.
+ * comes from live enumeration. There is no marker file.
  *
- * Filesystem deny (`denyRead`/`denyWrite`) is enforced via
- * `srt-win acl stamp` at session start: a broker-only DACL is
- * applied to each listed file plus a `Modify`-minus-`FILE_DELETE_CHILD`
- * allow-list on its immediate parent directory, with restore state
- * sealed by an inert hash-ACE marker so the on-disk SD is
- * self-authenticating. See {@link stampWindowsAcl}.
+ * Filesystem rules (`denyRead`/`denyWrite`/`allowRead`/`allowWrite`)
+ * are enforced via additive explicit ACEs for `<sb-SID>` — see
+ * {@link grantWindowsAcl} / {@link stampWindowsAcl}.
  */
-export declare const DEFAULT_WINDOWS_GROUP_NAME = "sandbox-runtime-net";
 export declare const DEFAULT_WINDOWS_PROXY_PORT_RANGE: readonly [number, number];
-/** Identifies the discriminator group either by name or by SID. */
-export interface WindowsGroupRef {
-    /** Local or domain group name. Default: `sandbox-runtime-net`. */
-    groupName?: string;
-    /**
-     * Group SID in `S-1-…` form. Takes precedence over `groupName` —
-     * use for domain groups or where name resolution is unreliable.
-     */
-    groupSid?: string;
-}
-export type WindowsGroupStatus = 'absent' | 'created-not-on-token' | 'ready';
-export interface WindowsGroupStatusResult {
-    state: WindowsGroupStatus;
-    sid?: string;
-    warning?: string;
-    error?: string;
-}
-export type WindowsWfpStatus = 'absent' | 'installed';
+/**
+ * `cannot-read` is the graceful-degrade state when BFE enumeration
+ * is access-denied (it is admin-gated). The non-elevated readiness
+ * check is {@link verifyWindowsWfpEgress}, not this enum.
+ */
+export type WindowsWfpStatus = 'absent' | 'installed' | 'cannot-read';
 export interface WindowsWfpStatusResult {
     state: WindowsWfpStatus;
+    /** Live filter count from BFE enum; `0` on `cannot-read`. */
     filters: number;
-    /** `[low, high]` from the `permit-loopback` filter's tag, when present. */
+    /** `[low, high]` for the loopback PERMIT, when known. */
     portRange?: [number, number];
-    /**
-     * Number of user-SID-keyed filters present (subset of `filters`).
-     * Zero on installs that predate the sandbox-user provisioning
-     * step, or when only `wfp install` (group set) was run.
-     */
-    userFilters: number;
     /** Sandbox-user SID read from the first user-keyed filter tag. */
     userSid?: string;
+    /**
+     * Populated only on `cannot-read` (BFE enumeration is admin-gated;
+     * a non-elevated caller can't read it). The non-elevated readiness
+     * check is {@link verifyWindowsWfpEgress}, not this enum.
+     */
+    hint?: string;
+}
+/**
+ * Result of `srt-win wfp verify` on success (exit 0, `blocked`) —
+ * see {@link verifyWindowsWfpEgress}. Any other outcome throws, so
+ * the tri-state is unobservable on the return path.
+ */
+export interface WindowsWfpVerifyResult {
+    target: string;
+    /** Runner's stderr (carries the `BLOCKED (…)` diagnostic line). */
+    stderr: string;
 }
 /**
  * State of the `srt-sandbox` local account that `srt-win install`
- * provisions. The sandboxed child eventually runs **as** this
- * account; for now it is reported alongside the group/WFP status
- * so callers can surface a "re-run install" diagnostic when the
- * account is missing.
+ * provisions. The sandboxed child runs **as** this account.
  */
 export interface WindowsSandboxUserStatus {
     /** The `srt-sandbox` local account exists. */
@@ -85,6 +85,12 @@ export interface WindowsSandboxUserStatus {
     credPresent: boolean;
     /** Setup marker schema version, when the marker row exists. */
     markerVersion?: number;
+    /**
+     * The calling (real) user's SID — the broker's identity, surfaced
+     * for diagnostics. The DENY-ACE trustee is `srt-sandbox`'s SID
+     * ({@link sid}), not this. Always present.
+     */
+    realUserSid: string;
     /**
      * SHA-1 thumbprint of the install-time CA, when one was
      * installed via `srt-win user trust-ca`. Uppercase hex.
@@ -94,18 +100,17 @@ export interface WindowsSandboxUserStatus {
     caCertPem?: string;
 }
 /**
- * Inner shell to run `command` under, inside the restricted-token
- * sandbox. The discriminant picks both the executable and the flag
- * shape (`/c` vs `-Command` vs `-c`); see
- * {@link wrapCommandWithSandboxWindows}.
+ * Inner shell to run `command` under, inside the sandbox. The
+ * discriminant picks both the executable and the flag shape (`/c`
+ * vs `-Command` vs `-c`); see {@link wrapCommandWithSandboxWindows}.
  *
  * For `kind: 'bash'`, `path` is the absolute Git Bash executable
  * (no fixed install location). It MUST originate from trusted host
  * configuration (user settings / install detection), NEVER from
  * workspace or repository content — the inner shell runs INSIDE the
- * restricted-token sandbox so an unexpected path is not a
- * sandbox-escape vector, but it would still be an arbitrary-exec
- * footgun if sourced from untrusted input.
+ * sandbox so an unexpected path is not a sandbox-escape vector, but
+ * it would still be an arbitrary-exec footgun if sourced from
+ * untrusted input.
  */
 export type WindowsBinShell = {
     kind: 'cmd';
@@ -129,94 +134,95 @@ export type WindowsBinShell = {
 export declare function parseWindowsBinShell(raw?: string): WindowsBinShell;
 export interface WindowsSandboxParams {
     command: string;
-    group: WindowsGroupRef;
     /**
-     * Sublayer GUID under which the WFP filters were installed.
-     * `srt-win exec` checks `wfp status` against it and refuses to
-     * launch when no filter set is present (fail-closed network
-     * fence). When omitted, srt-win uses its compile-time default
-     * GUID — same as `srt-win install` with no `--sublayer-guid`.
+     * JS HTTP proxy port — fed to `generateProxyEnvVars` for the env
+     * overlay. With the in-process proxy this is the mux front-end
+     * port (same as `socksProxyPort`).
      */
-    sublayerGuid?: string;
-    /** JS HTTP proxy port — fed to `generateProxyEnvVars` for the returned env. */
     httpProxyPort?: number;
-    /** JS SOCKS proxy port — fed to `generateProxyEnvVars` for the returned env. */
+    /**
+     * JS SOCKS proxy port — fed to `generateProxyEnvVars` for the env
+     * overlay. With the in-process proxy this is the mux front-end
+     * port (same as `httpProxyPort`).
+     */
     socksProxyPort?: number;
     /** Per-session proxy auth token; embedded in proxy env URLs. */
     proxyAuthToken?: string;
     /**
-     * Credential env vars to drop from the inherited environment
-     * (`mode: 'deny'`). Applied BEFORE the proxy assignments so the
-     * sandbox's own proxy plumbing survives even if a caller lists
-     * one of those names here — same precedence as the macOS/Linux
-     * `env -u … VAR=… sandbox-exec` order.
-     */
-    unsetEnvVars?: readonly string[];
-    /**
-     * Credential env vars to overwrite with a sentinel
-     * (`mode: 'mask'`). Applied BEFORE the proxy assignments for the
-     * same precedence reason as {@link unsetEnvVars}.
+     * `mode: 'mask'` credential env vars — sentinel values the
+     * sandboxed child should see in place of the real credentials.
+     * Threaded through the `--env` overlay so the runner forwards
+     * them into the child's fresh profile env (the broker's own
+     * environment never reaches the child, so an `env -u`-style
+     * scrub is structurally moot — there is no `unsetEnvVars`).
+     * Applied BEFORE the proxy assignments so the sandbox's own
+     * proxy plumbing survives even if a caller masks one of those
+     * names — same precedence as macOS/Linux.
      */
     setEnvVars?: Readonly<Record<string, string>>;
     /**
-     * PID of the long-lived host whose `srt-win acl stamp` holds
-     * this exec should run under. When set, `srt-win exec` opens a
-     * no-`FILE_SHARE_DELETE` handle on each of that holder's stamped
-     * directories and fenced files before spawning the child — the
-     * OS then refuses delete/rename of those, which the file's DACL
-     * alone cannot prevent. Omit for an exec with no file-deny
-     * session active.
-     */
-    holderPid?: number;
-    /**
-     * Per-exec read-deny paths, stamped under the `srt-win exec`
-     * process's own PID and restored after the child exits. Same
+     * Per-exec read-deny paths, applied via an additive
+     * `(D;OICI;FA;;;<sb-SID>)` ACE under the `srt-win exec`
+     * process's own PID and released after the child exits. Same
      * disk-first chokepoint as the session-level
      * {@link stampWindowsAcl}; same fail-closed semantics (exec
      * fails if any path cannot be stamped).
      *
-     * Pass RAW normalized paths. Do NOT pre-filter or pre-expand
-     * via {@link expandWindowsFsDenyPaths} — `srt-win exec`'s
-     * `canonicalize_deny_targets` is the sole authority for
-     * glob/dir/nonexistent rejection (hard-fail). A missing path
-     * is a caller error, not a skip; pre-filtering would silently
-     * drop it and run the child with the file readable.
+     * Normalized concrete paths — globs expanded by the caller via
+     * {@link expandWindowsFsPaths}, the same as session-level.
+     * `srt-win exec`'s `canonicalize_ace_targets` hard-fails on a
+     * glob (it never expands), so a `*`/`?` reaching this field is
+     * a caller bug.
      */
     denyRead?: readonly string[];
     /** Per-exec write-deny paths — see {@link denyRead}. */
     denyWrite?: readonly string[];
     /**
-     * Run the child as the dedicated `srt-sandbox` user via the
-     * two-hop launch (broker → `CreateProcessWithLogonW(runner)` →
-     * runner → restricted-token child). Requires `srt-win install` to
-     * have provisioned the sandbox user. Opt-in — when `false` or
-     * omitted the same-user deny-only-group path is used. The
-     * separate-user path structurally closes the surrogate-spawn
-     * class (schtasks, `PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`, BITS,
-     * RunAs="Interactive User" COM): the child's token carries a
-     * different user SID, so it cannot reach real-user processes,
-     * tasks register under `srt-sandbox`, and the user-SID WFP filter
-     * fences `srt-sandbox` egress regardless of how the child was
-     * spawned.
+     * Working directory the child starts in. Fed to
+     * {@link buildGitConfigEnv} as a `safe.directory` entry so git
+     * inside the sandbox accepts the real-user-owned working tree.
+     * Default: `process.cwd()`.
+     *
+     * `srt-win exec` has no `--cwd` flag — the child's working
+     * directory is whatever the caller passes as the spawn `{cwd:}`
+     * option (broker `current_dir()` → runner `lpCurrentDirectory` →
+     * child inherits). This field must match that spawn option so
+     * `safe.directory` covers where git actually runs.
      */
-    asSandboxUser?: boolean;
+    cwd?: string;
     /**
-     * PEM-encoded CA certificate file. Same parameter macOS/Linux
-     * thread to {@link generateProxyEnvVars} for the env-var trust
-     * layer (`NODE_EXTRA_CA_CERTS` etc.). NOT passed to `srt-win
-     * exec` — schannel-level trust under the sandbox user is set
-     * separately via `srt-win user trust-ca` /
-     * {@link windowsTrustCa}; per-exec only sets the env-var layer.
+     * Session-level write-granted paths (the resolved
+     * `filesystem.allowWrite` set). Each becomes a `safe.directory`
+     * entry — see {@link buildGitConfigEnv}.
+     */
+    allowWrite?: readonly string[];
+    /**
+     * Path to the TLS-termination trust bundle (the MITM CA + system
+     * roots) — fed to {@link generateProxyEnvVars} so the child's
+     * `NODE_EXTRA_CA_CERTS` / `CURL_CA_BUNDLE` / `SSL_CERT_FILE` /
+     * etc. point at it. Backslashes are normalised to forward slashes
+     * before emission so the value survives msys2 env conversion AND
+     * is accepted by native tools.
+     *
+     * The env-var layer covers OpenSSL-backed clients (msys2 curl,
+     * openssl-backed git, node, python, cargo). Schannel/.NET clients
+     * that read the Windows certificate store exclusively (System32
+     * `curl.exe`, `Invoke-WebRequest`, Go-built tools) trust via the
+     * separate `srt-win user trust-ca` / {@link windowsTrustCa}
+     * install-time write into the sandbox user's `CurrentUser\Root`.
      *
-     * **Under {@link asSandboxUser}**, this is currently NOT
-     * forwarded to the child: the bundle file lives in the broker's
-     * `%TEMP%`, which the `srt-sandbox` user cannot read, so OpenSSL
-     * clients (msys2 curl, openssl-backed git, node, python) would
-     * fail with `ACCESS_DENIED` on the bundle. The schannel-level
-     * trust set via {@link windowsTrustCa} is the only CA-trust path
-     * for the two-hop launch until working-tree/profile grants land.
+     * The caller is responsible for the sandbox user having read
+     * access to this path — `sandbox-manager.ts`'s `initialize()`
+     * pushes it into the session's `acl grant` read-set alongside the
+     * working-tree grants.
      */
     caCertPath?: string;
+    /**
+     * Resolved `srt-win` spawn descriptor — from
+     * {@link resolveSrtWin}. Omit to resolve the packaged vendor
+     * binary at call time.
+     */
+    srtWin?: SrtWinSpawn;
     /**
      * Inner shell. Defaults to `{ kind: 'cmd' }`. The child's post-`/c`
      * (or `-Command` / `-c`) content is **passthrough** — `&` chains,
@@ -229,19 +235,21 @@ export interface WindowsSandboxParams {
     binShell?: WindowsBinShell;
 }
 /**
- * Locate `srt-win.exe`. Resolution order:
- *   1. `SRT_WIN_PATH` env var (CI sets this to the freshly-built binary).
- *   2. `<root>/vendor/srt-win/{arch}/srt-win.exe` (prebuilt — published npm
+ * Locate the packaged `srt-win.exe`. Resolution order:
+ *   1. `<root>/vendor/srt-win/{arch}/srt-win.exe` (prebuilt — published npm
  *      package, or after `npm run build:srt-win` locally).
- *   3. `<root>/vendor/srt-win-src/target/release/srt-win.exe` (local
+ *   2. `<root>/vendor/srt-win-src/target/release/srt-win.exe` (local
  *      `cargo build --release` fallback for development).
- *   4. `<root>/vendor/srt-win/target/release/srt-win.exe` (transitional:
- *      stale local build from before the srt-win-src rename).
  *
  * `<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`.
  *
+ * Callers that ship their own binary (or a multicall binary that
+ * routes on `argv[1] == `{@link SRT_WIN_DISPATCH_ARG1}) pass
+ * `windows.srtWin` instead of relying on this lookup — see
+ * {@link resolveSrtWin}.
+ *
  * Resolution via the optional `@anthropic-ai/sandbox-runtime-win32-*`
  * platform packages is added separately.
  *
@@ -249,46 +257,105 @@ export interface WindowsSandboxParams {
  */
 export declare function getSrtWinPath(): string;
 /**
- * Query the discriminator group's state in SAM and in the current
- * process's `TokenGroups`. `ready` means the group exists AND is
- * enabled in the caller's token (i.e. the logout/login dance has
- * happened). `created-not-on-token` means the install step ran but
- * a fresh logon is needed before {@link initialize} can succeed.
+ * `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 declare const SRT_WIN_DISPATCH_ARG1 = "--srt-win";
+/**
+ * Resolved `srt-win` spawn descriptor — the executable to load plus
+ * the leading arguments that carry the dispatch sentinel. Threaded
+ * to every spawn site so {@link resolveSrtWin} runs once (at
+ * `initialize()`) instead of re-`stat`ing on every helper call.
+ */
+export type SrtWinSpawn = Readonly<{
+    exe: string;
+    prependArgs: readonly string[];
+}>;
+/**
+ * Resolve the `srt-win` spawn target from config. When `cfg.path` is
+ * set it is used verbatim (no fallback to the packaged binary — an
+ * explicit override is a directive, not a hint) and
+ * {@link SRT_WIN_DISPATCH_ARG1} is prepended so a multicall
+ * dispatcher routes on `argv[1]`. When unset, falls back to
+ * {@link getSrtWinPath} with no sentinel (the packaged binary
+ * doesn't need it; `run_from_args` would strip it anyway).
  */
-export declare function getWindowsGroupStatus(ref: WindowsGroupRef): WindowsGroupStatusResult;
+export declare function resolveSrtWin(cfg?: SrtWinConfig): SrtWinSpawn;
 /**
- * Query the WFP filter set under the given sublayer. `installed` means
- * srt-win-tagged `permit-group` AND `block` filters are both present
- * under that sublayer. Detection is **tag-based** (providerData JSON);
- * filters installed by other tooling without the tag are not counted.
+ * 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}.
  */
 export declare function getWindowsWfpStatus(opts?: {
     sublayerGuid?: string;
+    srtWin?: SrtWinSpawn;
 }): WindowsWfpStatusResult;
+/**
+ * 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 declare function verifyWindowsWfpEgress(opts?: {
+    target?: string;
+    proxyPortRange?: readonly [number, number];
+    srtWin?: SrtWinSpawn;
+}): Promise<WindowsWfpVerifyResult>;
 /**
  * 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.
  */
-export declare function getWindowsSandboxUserStatus(): WindowsSandboxUserStatus;
+export declare function getWindowsSandboxUserStatus(opts?: {
+    srtWin?: SrtWinSpawn;
+}): WindowsSandboxUserStatus;
 /**
  * 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 stored in `state.db`.
  *
- * On Windows with `windows.asSandboxUser`, `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.
+ * 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 declare function getWindowsSandboxCaCert(status?: WindowsSandboxUserStatus): {
+export declare function getWindowsSandboxCaCert(status?: WindowsSandboxUserStatus, opts?: {
+    srtWin?: SrtWinSpawn;
+}): {
     pem: string;
     thumb: string;
 } | null;
@@ -302,17 +369,16 @@ export declare function getWindowsSandboxCaCert(status?: WindowsSandboxUserStatu
  *
  * 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 with
- * `windows.asSandboxUser`.
+ * 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 declare function windowsTrustCa(caCertPath: string): void;
-export interface WindowsInstallOptions extends WindowsGroupRef {
-    /** Add this user (instead of the current user) to the group. */
-    userSid?: string;
+export declare function windowsTrustCa(caCertPath: string, opts?: {
+    srtWin?: SrtWinSpawn;
+}): void;
+export interface WindowsInstallOptions {
     /** WFP sublayer GUID. Omit for srt-win's compile-time default. */
     sublayerGuid?: string;
     /**
@@ -321,17 +387,23 @@ export interface WindowsInstallOptions extends WindowsGroupRef {
      * Default {@link DEFAULT_WINDOWS_PROXY_PORT_RANGE}.
      */
     proxyPortRange?: readonly [number, number];
+    /**
+     * Name for the sandbox user account (created if absent, adopted
+     * if it already exists as a local user). Default `srt-sandbox`.
+     */
+    sandboxUser?: string;
     /**
      * Replace an existing install whose configuration differs
-     * (different group SID or port range under the same sublayer).
-     * Without this, install refuses with "already installed with
-     * different config" rather than silently overwriting.
+     * (different port range or sandbox-user name under the same
+     * sublayer). Without this, install refuses with "already
+     * installed with different config" rather than silently
+     * overwriting.
      */
     force?: boolean;
+    /** Resolved `srt-win` spawn descriptor — from {@link resolveSrtWin}. */
+    srtWin?: SrtWinSpawn;
 }
 export interface WindowsInstallResult {
-    /** Post-install group state. */
-    group: WindowsGroupStatusResult;
     /** Post-install WFP state. */
     wfp: WindowsWfpStatusResult;
     /** Post-install sandbox-user state. */
@@ -344,187 +416,169 @@ export interface WindowsInstallResult {
     cancelled?: true;
 }
 /**
- * One-shot install: creates the discriminator group, adds the
- * current user (or `userSid`), and installs the machine-wide WFP
- * filter set — all in a single self-elevating process (one UAC
- * prompt). Idempotent.
+ * 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** before the
- * required logout: while the group is absent from the token, WFP
- * filter-0 (PERMIT non-members) matches and traffic flows normally.
- * After log-out/log-in, the group is enabled in the token and
- * filter-1 (PERMIT group-enabled) takes over for the broker; only
- * `srt-win exec` children (group flipped deny-only) fall through to
- * the loopback/BLOCK filters.
+ * 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 group + WFP state. If the user cancels the
- * UAC prompt this returns `{cancelled: true, …}` rather than
- * throwing — cancellation is a user choice, not an error.
+ * 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.
  *
- * @throws on group/WFP creation failure, or if filters already
- *   exist under `sublayerGuid` with different configuration and
- *   `force` is not set.
+ * @throws on user/WFP creation failure, or if filters already exist
+ *   under `sublayerGuid` with a different port range and `force` is
+ *   not set.
  */
 export declare function installWindowsSandbox(opts?: WindowsInstallOptions): WindowsInstallResult;
 /**
- * Remove the WFP filter set under `sublayerGuid` (one UAC prompt).
- * Idempotent.
- *
- * **Does NOT delete the discriminator group** — group membership is
- * persistent user state and removing it would force every user to
- * re-do the logout dance on the next install. Call
- * {@link deleteWindowsGroup} explicitly if you want full teardown.
- *
- * **Does** remove the `srt-sandbox` account, its credential file,
- * and the setup marker, unless `keepUser` is set — the credential
- * is useless without the account and vice versa, so they're
- * treated as one unit.
+ * 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 declare function uninstallWindowsSandbox(opts?: {
     sublayerGuid?: string;
     keepUser?: boolean;
+    srtWin?: SrtWinSpawn;
 }): {
     cancelled?: true;
 };
 /**
- * Delete the discriminator group. Separate from
- * {@link uninstallWindowsSandbox} so that uninstall→reinstall
- * doesn't force a fresh logout for every member. **Requires
- * elevation.** Idempotent (no-op if the group doesn't exist).
- */
-export declare function deleteWindowsGroup(ref: WindowsGroupRef): void;
-/**
- * Granular primitive: create the discriminator group and add the
- * current user (or `userSid`). Most callers should use
- * {@link installWindowsSandbox} instead; this exists for
- * enterprise/CI flows that manage group and WFP separately.
- * **Requires elevation.** Idempotent.
- */
-export declare function createWindowsGroup(ref: WindowsGroupRef & {
-    userSid?: string;
-}): void;
-/**
- * Granular primitive: install the machine-wide WFP filter set
- * under `sublayerGuid` keyed on the group SID. Most callers should
- * use {@link installWindowsSandbox} instead; this exists for
- * enterprise/CI flows that manage group and WFP separately.
- * **Requires elevation.** Idempotent — re-running replaces any
- * existing srt-win-tagged filters under that sublayer.
- */
-export declare function createWindowsWfp(ref: WindowsGroupRef & {
-    sublayerGuid?: string;
-    proxyPortRange?: readonly [number, number];
-}): void;
-/**
- * Per-file outcome from `srt-win acl restore --json`. `status:
- * "restored"` covers both `Restored` and `AlreadyOriginal` on the
- * Rust side (the host doesn't need to distinguish them); every
- * other status keeps the snapshot row (fail-closed) and is
- * surfaced to the user as an anomaly to investigate. Mirrors
- * `restore_entry()` in `vendor/srt-win-src/src/main.rs`.
- */
-export interface WindowsAclPathOutcome {
-    path: string;
-    status: 'restored' | 'relocated' | 'missing' | 'leftChanged' | 'leftUnreadable' | 'originalSdTampered' | 'originalSdLost' | 'stampedUnrecognized';
-    /** Hex `FILE_ID_INFO` recorded at stamp time. Present when `status ≠ "restored"`. */
-    expectedFileId?: string;
-    /** Where the protected file was found by `file_id`. Only on `relocated`. */
-    movedTo?: string;
-    /** `true` whenever `status ≠ "restored"` — the snapshot row was kept (restore not confirmed). */
-    leftStamped?: boolean;
-}
-/**
- * Per-parent-directory outcome from `srt-win acl restore --json`.
- * `stillHeld` is normal (another active session still references
- * a file under this directory). Mirrors `parent_entries_from()` +
- * `ParentRestoreOutcome::as_str()` in `vendor/srt-win-src/src/`.
+ * Resolve any Windows filesystem-config path list — `allowRead`/
+ * `allowWrite` grants and `denyRead`/`denyWrite` stamps — to
+ * concrete existing 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. Missing paths are dropped (statSync probe).
+ * Directory targets are accepted — the additive sandbox-user ACE
+ * carries `(OI)(CI)` so it covers the subtree.
  */
-export interface WindowsAclParentOutcome {
-    path: string;
-    status: 'restored' | 'alreadyOriginal' | 'stillHeld' | 'leftChanged' | 'missing' | 'leftStamped';
-    /** Underlying error for `leftStamped`. */
-    error?: string;
-}
-/** Top-level shape of `srt-win acl restore --json`. */
-export interface WindowsAclRestoreResult {
-    paths: WindowsAclPathOutcome[];
-    parents: WindowsAclParentOutcome[];
-}
-/**
- * Expand the `denyRead`/`denyWrite` input set to a flat list of
- * existing FILE paths for `srt-win acl stamp`.
- *
- * Every input goes through {@link normalizePathForSandbox} (the
- * single Windows-aware chokepoint: `\\?\`/UNC-strip, drive-letter
- * case-fold, ~-expand, realpath). Globs (`*`/`?` only — `[`/`]`
- * are legal Win32 filename chars) expand via the shared walker
- * with case-insensitive matching (point-in-time: a file appearing
- * after this returns is NOT covered). Each candidate is checked
- * with one `statSync({throwIfNoEntry:false})`: missing → drop
- * (the protection model covers files present at session start);
- * directory → reject (the file stamp applies a per-file DACL plus
- * a per-parent-directory allow-list; stamping a directory itself
- * would touch every child); file → keep.
- */
-export declare function expandWindowsFsDenyPaths(patterns: readonly string[]): string[];
+export declare function expandWindowsFsPaths(patterns: readonly string[]): string[];
 export interface WindowsAclStampOptions {
-    group: WindowsGroupRef;
-    /** Files the sandboxed child must not read. */
+    /** Paths the sandboxed child must not read. */
     denyRead: readonly string[];
-    /** Files the sandboxed child must not write (read stays allowed). */
+    /** Paths the sandboxed child must not write (read stays allowed). */
     denyWrite: readonly string[];
+    /** SID of the dedicated sandbox user — {@link WindowsSandboxUserStatus.sid}. */
+    sandboxUserSid: string;
     /** Long-lived host PID the holds are tied to. Default: this process. */
     holderPid?: number;
+    /** Resolved `srt-win` spawn descriptor — from {@link resolveSrtWin}. */
+    srtWin?: SrtWinSpawn;
 }
 /**
- * Apply the file-deny stamp set for one host session. Idempotent
- * via `srt-win`'s disk-first `ensure_stamped` chokepoint — calling
- * this again with overlapping paths re-verifies the on-disk DACL
- * against the hash-ACE marker rather than trusting state-DB rows.
+ * 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,
- * rejects directories and globs, and stamps each file plus its
- * immediate parent directory). Callers that accept globs should
- * pre-expand via {@link expandWindowsFsDenyPaths}.
+ * 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 (fail-closed at session start
- *   means tearing down a partial setup).
+ *   to release whatever WAS stamped.
  */
 export declare function stampWindowsAcl(opts: WindowsAclStampOptions): void;
-export interface WindowsAclRestoreOptions {
-    group: WindowsGroupRef;
-    /** Long-lived host PID whose holds to release. Default: this process. */
+/**
+ * Per-path outcome from `srt-win acl restore --json` /
+ * `revoke --json`. The status set is intentionally loose: the
+ * pre-/post- same-user-removal `srt-win` builds emit different
+ * vocabularies for `restore` (`restored`/`leftChanged`/… vs
+ * `revoked`/`stillHeld`/…). Callers (`reset()`) only log these,
+ * so the union is whatever the binary on PATH says.
+ */
+export interface WindowsAclAceOutcome {
+    path: string;
+    status: string;
+}
+/**
+ * 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 declare function restoreWindowsAcl(opts: {
+    sandboxUserSid: string;
+    holderPid?: number;
+    srtWin?: SrtWinSpawn;
+}): WindowsAclAceOutcome[] | undefined;
+export interface WindowsAclGrantOptions {
+    /** Paths to grant `MODIFY_NO_FDC` on (the working tree, `allowWrite`). */
+    write: readonly string[];
+    /** Paths to grant `FILE_GENERIC_READ|EXECUTE` on (`allowRead`). */
+    read: readonly string[];
+    /** SID of the dedicated sandbox user — {@link WindowsSandboxUserStatus.sid}. */
+    sandboxUserSid: string;
+    /** Long-lived host PID the holds are tied to. Default: this process. */
     holderPid?: number;
+    /** Resolved `srt-win` spawn descriptor — from {@link resolveSrtWin}. */
+    srtWin?: SrtWinSpawn;
 }
 /**
- * Release this holder's file-deny stamps and return per-path /
- * per-parent outcomes. Best-effort: a non-`restored` entry means
- * the file's stamp was LEFT in place (fail-closed) — see
- * {@link WindowsAclPathOutcome} for the cases. Does not throw on
- * anomalies; the caller decides whether to surface them.
+ * 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.
  *
- * Returns `undefined` when `srt-win acl restore` itself failed
- * (no JSON to parse) — the caller should log and move on rather
- * than block teardown.
+ * @throws on exit ≠ 0. On throw the caller should call
+ *   {@link revokeWindowsAcl} to release whatever WAS granted.
  */
-export declare function restoreWindowsAcl(opts: WindowsAclRestoreOptions): WindowsAclRestoreResult | undefined;
+export declare function grantWindowsAcl(opts: WindowsAclGrantOptions): void;
 /**
- * Per-path outcomes that mean the file's DACL was returned to its
- * pre-stamp state (or was already there). Anything else left the
- * stamp in place and should be surfaced to the user.
+ * 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 declare const WINDOWS_ACL_PATH_OK: Set<"restored" | "relocated" | "missing" | "leftChanged" | "leftUnreadable" | "originalSdTampered" | "originalSdLost" | "stampedUnrecognized">;
+export declare function revokeWindowsAcl(opts: {
+    sandboxUserSid: string;
+    holderPid?: number;
+    srtWin?: SrtWinSpawn;
+}): WindowsAclAceOutcome[] | undefined;
 /**
- * Per-parent-directory outcomes that are expected during normal
- * teardown. `stillHeld` is normal when another active session
- * still references a file under this directory.
+ * Build the `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_<n>` /
+ * `GIT_CONFIG_VALUE_<n>` env-var set for the sandboxed child.
+ *
+ * Emits:
+ *   - `safe.directory=<dir>` for each entry in `safeDirs` (or one
+ *     `safe.directory=*` when the list is long) — the working tree
+ *     is owned by the real user, so git running as `srt-sandbox`
+ *     refuses with "detected dubious ownership" without it.
+ *   - `http.schannelUseSSLCAInfo=true` and
+ *     `http.schannelCheckRevoke=false` when `schannelCa` — makes
+ *     git's default (schannel) backend honor `GIT_SSL_CAINFO`
+ *     without `-c http.sslBackend=openssl`. Revocation is disabled
+ *     because CryptoAPI CRL/OCSP fetches ignore proxy env and would
+ *     be WFP-fenced.
+ *
+ * Composes with an existing `GIT_CONFIG_COUNT` in `baseEnv` by
+ * continuing its numbering; the returned `GIT_CONFIG_COUNT` is the
+ * new total. Under the two-hop launch the broker's own environment
+ * never reaches the child, so `baseEnv` is the caller-supplied
+ * overlay ({@link WindowsSandboxParams.setEnvVars}), not
+ * `process.env`.
+ *
+ * Paths are emitted with forward slashes so the value survives
+ * msys2's env conversion untouched and native git accepts it.
  */
-export declare const WINDOWS_ACL_PARENT_OK: Set<"restored" | "missing" | "leftChanged" | "alreadyOriginal" | "stillHeld" | "leftStamped">;
+export declare function buildGitConfigEnv(opts: {
+    safeDirs: readonly string[];
+    schannelCa: boolean;
+    baseEnv?: Readonly<Record<string, string | undefined>>;
+}): Record<string, string>;
 /**
  * Build the spawn descriptor for running `command` inside the Windows
  * sandbox: an `argv` array plus the `env` to spawn it with.
@@ -538,9 +592,10 @@ export declare const WINDOWS_ACL_PARENT_OK: Set<"restored" | "missing" | "leftCh
  * 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; it forwards its own environment to the sandboxed child
- * verbatim. So the full proxy set is merged over the broker's
- * environment here and the child inherits it through the spawn.
+ * 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 declare function wrapCommandWithSandboxWindows(p: WindowsSandboxParams): {
     argv: string[];
@@ -548,13 +603,14 @@ export declare function wrapCommandWithSandboxWindows(p: WindowsSandboxParams):
 };
 /**
  * Install instructions, surfaced verbatim in error messages.
- * Tailored to the observed group state: if the install already
- * ran (`created-not-on-token`), only the logout is missing.
  */
-export declare function windowsInstallInstructions(ref: WindowsGroupRef, sublayerGuid: string | undefined, groupState: WindowsGroupStatus): string;
+export declare function windowsInstallInstructions(sublayerGuid: string | undefined): string;
 /**
  * Check the Windows backend is ready to sandbox. Errors block
  * `initialize()`; warnings are informational.
  */
-export declare function checkWindowsDependencies(ref: WindowsGroupRef, sublayerGuid?: string): SandboxDependencyCheck;
+export declare function checkWindowsDependencies(opts?: {
+    sublayerGuid?: string;
+    srtWin?: SrtWinSpawn;
+}): SandboxDependencyCheck;
 //# sourceMappingURL=windows-sandbox-utils.d.ts.map