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-stating on every helper call.
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.
Inner shell to run command under, inside the sandbox: the
executable to spawn and the flag argv placed between it and the
user's command string. exe MUST originate from trusted host
configuration (user settings / install detection), NEVER from
workspace or repository content — the inner shell runs INSIDE the
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.
Result of srt-win wfp verify on success (exit 0); anything else
throws. plain is blocked. A lowered-integrity attempt may be
error (not set up), and the rest anything: see residuals.
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.
The one loopback port that stays blocked for the sandbox account with
network.allowLocalBinding, so the fence check has a connect that must
be refused. srt-win owns it (LOOPBACK_PROBE_PORT in wfp.rs).
The variables {@link windowsProfileReadEnv} can return; any other name
srt-win reports is dropped. RUSTUP_HOME and CARGO_HOME name
directories, which stay read-only to the sandboxed command.
Git configuration schema (cross-platform). Injected via
GIT_CONFIG_COUNT / GIT_CONFIG_KEY_<n> / GIT_CONFIG_VALUE_<n>
env vars — see buildGitConfigEnv in sandbox-utils.ts.
Configuration for locating/invoking the srt-win helper (Windows
only). An embedder that links srt-win's CLI into its own
multicall binary points path at that binary; spawns then pass
--srt-win as argv[1] (see SRT_WIN_DISPATCH_ARG1 in
windows-sandbox-utils.ts / srt_win::SRT_WIN_DISPATCH_ARG1) so
the embedder's dispatcher can route to srt_win::run_from_args.
Windows cannot reliably preserve a spoofed argv[0] across
CreateProcessWithLogonW / ShellExecuteExW(runas), so dispatch
keys on argv[1], not on argv[0] like
{@link SeccompConfigSchema} does on Linux.
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.
SHA-1 thumbprint of certPem as uppercase hex with no separators —
the format srt-win user status reports (ca_cert_thumb) and
PowerShell's Cert:\…\Thumbprint uses. Throws if certPem is not a
parseable X.509 certificate.
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.
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}).
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.
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.
Remove the profile read grant (srt-win profile forget). Synchronous:
blocks for as long as the removal takes; with an event loop use
{@link forgetWindowsProfileReadAsync}. Throws profile_forget_failed.
Generate a self-signed RSA-2048 CA certificate + private key as PEM
strings. Pure — no filesystem side effects; the caller decides where (and
whether) to persist. This is the primitive under both the ephemeral
per-process CA and the Windows persistent CA
(ensurePersistentWindowsCa).
The recorded profile read grant (srt-win profile status): whether one
exists and is current, and with paths every path it wrote on. Throws
profile_operation_in_progress while a grant or forget is running.
Blocks the event loop: prefer {@link getWindowsProfileReadStatusAsync}.
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.
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.
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.
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.
Write or refresh the profile read grant (srt-win profile grant), as
the user of this process, unelevated. Runs only while no sandbox session
or command is running (profile_grant_blocked_by_session).
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.
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.
True for a Windows UNC path in any spelling — \\server\share\…,
extended-length \\?\UNC\server\share\…, device-namespace
\\.\UNC\server\share\… (all any casing, either separator).
Delegates path-form normalization to
path.win32.toNamespacedPath — every UNC spelling canonicalizes
to \\?\UNC\… — so the check is "namespaced form starts with
\\?\UNC\ (or \\.\UNC\)". Drive-local forms (C:\…,
\\?\C:\…), other device paths (\\.\pipe\…), relative paths
(resolved against a local cwd), and server-only \\srv (no
share) are all false.
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.
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, seclogon_disabled exit 18,
wfp_loopback_mismatch exit 19. 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.
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).
Release this holder's deny ACEs. Best-effort; undefined when
srt-win failed. srt-win refuses (status grantPending) while the
holder still has a grant recorded: revoke first.
Release this holder's grants. Best-effort (does not throw). Do not
follow with {@link restoreWindowsAcl}: use
{@link revokeWindowsAclChecked}, which says whether it completed.
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.
Check that certPem + keyPem are a usable RSA CA pair: both parse, the
key is RSA (node-forge signs with nothing else), the private key's
modulus matches the certificate's public key (i.e. this key actually
signs for this cert), and notBefore is not in the future — a CA
minted while the system clock was ahead and later NTP-corrected would
otherwise be permanently not-yet-valid with nothing to trigger a
regenerate. Returns the cert's thumbprint and notAfter on success so
a caller can decide expiry policy without a second parse.
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 direct TCP connects, one per token shape a sandboxed
process can present. 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). The event loop stays live while
srt-win runs. Does not require elevation and does not depend on
any external host.
The paths among paths a session must not grant while the profile read
grant exists, with the exclusion each collides with. Paths are resolved
first; fails closed on a path that exists and cannot be listed.
Why an install leaves the profile read grant unapplied (undefined: it
applies it): asked to skip, a service account, or not running as the
owner of the interactive session, whose profile it would open instead.
Variables an embedder may set so a tool reads the real user's files in
place. Empty unless the grant is current; never one env already holds.
The library sets none of them itself.
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.
Install (or replace) the MITM CA in the sandbox user'sCurrentUser\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.
Every path a write config allows, whichever list it came in on. Whoever
asks "may the command write here" asks this, not allowOnly alone: a
path the caller marked literal is in literalAllowOnly and nowhere else.
Asked about a host that no configured rule and no per-command allow list
decided (never asked under network.strictAllowlist). Only true allows.
{ allow: false, reason } denies with that reason, which the violation
line reports, and which the sandboxed client reads as the status phrase of
the 403 that answers its CONNECT. false and every other answer, truthy
or not, deny with the generic reason "user denied": a reason on an
object that does not say allow: false is not reported.
Thrown when a Linux bubblewrap profile cannot be run on this host: what the
configuration expands to, with the mandatory denies of the working
directory, is past a limit, or, for command_too_long and nul_in_path,
what the caller passed in is. The command was not run and no
profile file stays open, so do not run the per-command cleanup
(cleanupAfterCommand(), cleanupBwrapMountPoints()) for a wrap that
threw: it would release a second time, and a sandbox still running would
lose its mount points. Branch on .code, never on .message, which
carries the sizes of the moment. Other wrap-time failures (a shell that is
not on PATH, a bridge socket that is gone) are plain Errors.
{@link WindowsSandboxError} narrowed to mapped_drive_cwd,
carrying the DRIVE_REMOTE root that made the launch fail
(Z:\ for a mapped letter, \\server\share\ for a raw UNC cwd).
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.