VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/_process.py

@@ -0,0 +1,912 @@
+"""Silent subprocess execution, ACL-restricted work directories, and UAC elevation.
+
+Everything in this module exists for one reason: the driver install must happen in an
+**elevated child process** while the caller keeps running unelevated.  Two consequences
+drive the design:
+
+* The caller must receive the child's exact outcome, so the child reports back over a
+  named pipe created by the caller (not over stdout, which ``ShellExecuteW`` cannot
+  connect, and not over a world-writable temp file, which any local process could forge).
+* The elevated child must not be able to run attacker-controlled code, so it is launched
+  with ``-E -s`` (ignore ``PYTHON*`` environment variables and the per-user site
+  directory) and only ever consumes files from a verified, digest-pinned cache.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from ctypes import wintypes
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from .errors import ConfigError, ElevationDenied, ElevationRequired, OffscreenMountError
+from ._winapi import IS_WINDOWS, format_hresult, require_windows
+
+log = get_logger("process")
+
+__all__ = [
+    "CREATE_NO_WINDOW",
+    "CommandResult",
+    "run_command",
+    "secure_mkdir",
+    "secure_write_json",
+    "ResponsePipe",
+    "ElevationResult",
+    "elevate_and_run_helper",
+    "helper_command",
+    "import_roots",
+    "last_getlasterror",
+]
+
+CREATE_NO_WINDOW = 0x08000000
+SW_HIDE = 0
+SW_SHOWNORMAL = 1
+_STILL_ACTIVE = 259
+_SEE_MASK_NOCLOSEPROCESS = 0x00000040
+_SEE_MASK_NOASYNC = 0x00000100
+_DEFAULT_CHUNK = 4096
+
+if IS_WINDOWS:  # pragma: no branch
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    shell32 = ctypes.WinDLL("shell32", use_last_error=True)
+    advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
+else:  # pragma: no cover
+    kernel32 = shell32 = advapi32 = None
+
+
+def last_getlasterror() -> int:
+    if not IS_WINDOWS:
+        return 0
+    return ctypes.get_last_error()
+
+
+# --------------------------------------------------------------------------------------
+# Hardened directories
+# --------------------------------------------------------------------------------------
+
+
+class _SECURITY_ATTRIBUTES(ctypes.Structure):
+    _fields_ = [
+        ("nLength", wintypes.DWORD),
+        ("lpSecurityDescriptor", ctypes.c_void_p),
+        ("bInheritHandle", wintypes.BOOL),
+    ]
+
+
+class _SHELLEXECUTEINFOW(ctypes.Structure):
+    """``SHELLEXECUTEINFOW`` - needed to obtain the elevated child's process handle."""
+
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("fMask", ctypes.c_ulong),
+        ("hwnd", wintypes.HWND),
+        ("lpVerb", ctypes.c_wchar_p),
+        ("lpFile", ctypes.c_wchar_p),
+        ("lpParameters", ctypes.c_wchar_p),
+        ("lpDirectory", ctypes.c_wchar_p),
+        ("nShow", ctypes.c_int),
+        ("hInstApp", wintypes.HINSTANCE),
+        ("lpIDList", ctypes.c_void_p),
+        ("lpClass", ctypes.c_wchar_p),
+        ("hkeyClass", wintypes.HKEY),
+        ("dwHotKey", wintypes.DWORD),
+        ("hIcon", wintypes.HANDLE),
+        ("hProcess", wintypes.HANDLE),
+    ]
+
+
+_SDDL_REVISION_1 = 1
+_SE_FILE_OBJECT = 1
+_DACL_SECURITY_INFORMATION = 0x00000004
+_PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000
+
+
+def _owner_only_sd(access: Tuple[str, ...] = ("FA",)) -> Optional[ctypes.c_void_p]:
+    """Build a protected DACL: full control for SYSTEM/Administrators/owner.
+
+    ``access`` overrides the permission mask granted to the owner (``OW``), which is how
+    the response pipe grants ``GW`` (generic write) instead of full control.
+    """
+    if not IS_WINDOWS:
+        return None
+    owner_mask = "".join(access)
+    sddl = f"D:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;{owner_mask};;;OW)"
+    descriptor = ctypes.c_void_p()
+    ok = advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
+        ctypes.c_wchar_p(sddl),
+        ctypes.c_uint(_SDDL_REVISION_1),
+        ctypes.byref(descriptor),
+        None,
+    )
+    if not ok:
+        log.debug("could not build security descriptor (%s): %s", sddl, last_getlasterror())
+        return None
+    return descriptor
+
+
+def _owner_sid_string() -> Optional[str]:
+    """The current process token's user SID in SDDL form (``S-1-5-21-...``)."""
+    if not IS_WINDOWS:
+        return None
+    TOKEN_QUERY = 0x0008
+    TokenUser = 1
+    token = wintypes.HANDLE()
+    if not advapi32.OpenProcessToken(
+        kernel32.GetCurrentProcess(), TOKEN_QUERY, ctypes.byref(token)
+    ):
+        return None
+    try:
+        needed = wintypes.DWORD()
+        advapi32.GetTokenInformation(token, TokenUser, None, 0, ctypes.byref(needed))
+        if not needed.value:
+            return None
+        buffer = ctypes.create_string_buffer(needed.value)
+        if not advapi32.GetTokenInformation(
+            token, TokenUser, buffer, needed.value, ctypes.byref(needed)
+        ):
+            return None
+        # TOKEN_USER is a SID_AND_ATTRIBUTES struct: the first pointer-sized field is the SID.
+        sid = ctypes.cast(buffer, ctypes.POINTER(ctypes.c_void_p))[0]
+        text = ctypes.c_wchar_p()
+        if not advapi32.ConvertSidToStringSidW(ctypes.c_void_p(sid), ctypes.byref(text)):
+            return None
+        try:
+            return text.value
+        finally:
+            kernel32.LocalFree(text)
+    finally:
+        kernel32.CloseHandle(token)
+
+
+#: FILE_GENERIC_WRITE, spelled numerically on purpose. The SDDL abbreviation ``GW`` maps to
+#: a mask that also includes DELETE-related bits, which a named pipe cannot satisfy, so the
+#: client's ``GENERIC_WRITE`` open failed the access check with ERROR_ACCESS_DENIED
+#: (measured: ``GW`` = FAIL(5), ``0x12019b`` = OK). The numeric mask is the exact
+#: *mappable* subset and is honoured on every Windows version tested.
+FILE_GENERIC_WRITE = 0x0012019B
+
+#: Directory equivalent: SDDL can safely use ``FA`` for directories because the object is
+#: created with the caller as owner, so generic bits resolve normally.
+FILE_ALL_ACCESS_SDDL = "FA"
+
+
+def _security_descriptor(
+    user_access: str = FILE_ALL_ACCESS_SDDL,
+    owner_sid: Optional[str] = None,
+) -> Optional[ctypes.c_void_p]:
+    """Build a *protected* DACL: SYSTEM + Administrators + this user's SID.
+
+    ``user_access`` is the access mask granted to the current user, either an SDDL
+    abbreviation (``FA``) or a numeric mask (``0x0012019B``).  The current user's SID is
+    written out explicitly instead of relying on the ``OW`` ("owner rights") SID: ``OW``
+    only applies to objects that actually have an owner, which a freshly created **named
+    pipe** does not (``ConvertStringSecurityDescriptorToSecurityDescriptor`` leaves the
+    owner unset), so an ``OW``-only ACE silently grants nothing and the client gets
+    ERROR_ACCESS_DENIED.
+    """
+    if not IS_WINDOWS:
+        return None
+    sid = owner_sid or _owner_sid_string()
+    user_ace = f"(A;OICI;{user_access};;;{sid})" if sid else ""
+    sddl = f"D:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA){user_ace}"
+    descriptor = ctypes.c_void_p()
+    ok = advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
+        ctypes.c_wchar_p(sddl),
+        ctypes.c_uint(_SDDL_REVISION_1),
+        ctypes.byref(descriptor),
+        None,
+    )
+    if not ok:
+        log.debug("could not build security descriptor (%s): %s", sddl, last_getlasterror())
+        return None
+    return descriptor
+
+
+def _local_free(descriptor: Optional[ctypes.c_void_p]) -> None:
+    if descriptor:
+        kernel32.LocalFree(descriptor)
+
+
+if IS_WINDOWS:  # pragma: no branch
+    advapi32.OpenProcessToken.argtypes = [
+        wintypes.HANDLE,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.HANDLE),
+    ]
+    advapi32.OpenProcessToken.restype = wintypes.BOOL
+    advapi32.GetTokenInformation.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    advapi32.GetTokenInformation.restype = wintypes.BOOL
+    advapi32.ConvertSidToStringSidW.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_wchar_p)]
+    advapi32.ConvertSidToStringSidW.restype = wintypes.BOOL
+    advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW.argtypes = [
+        ctypes.c_wchar_p,
+        ctypes.c_uint,
+        ctypes.POINTER(ctypes.c_void_p),
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW.restype = wintypes.BOOL
+    kernel32.CreateDirectoryW.argtypes = [
+        ctypes.c_wchar_p,
+        ctypes.POINTER(_SECURITY_ATTRIBUTES),
+    ]
+    kernel32.CreateDirectoryW.restype = wintypes.BOOL
+    kernel32.GetCurrentProcess.restype = wintypes.HANDLE
+
+
+def secure_mkdir(path: os.PathLike) -> Path:
+    """``mkdir -p`` with an ACL that excludes other local users where possible.
+
+    **Every** missing component is created with the hardened descriptor, not just the leaf:
+    creating a child inside a permissive parent leaves that parent traversable by other
+    users, and ``CreateDirectoryW`` fails with ``ERROR_PATH_NOT_FOUND`` (3) when its parent
+    does not exist — so delegating to Python's ``parents=True`` would silently skip the ACL
+    work for exactly the nested paths this library uses.
+
+    Falls back to a plain ``mkdir`` (and logs at debug level) when the security APIs are
+    unavailable; the directory then still lives under the user's own cache/profile root.
+    """
+    target = Path(path)
+    if target.exists():
+        return target
+    missing: List[Path] = []
+    cursor = target
+    while not cursor.exists():
+        missing.append(cursor)
+        if cursor.parent == cursor:  # pragma: no cover - filesystem root
+            break
+        cursor = cursor.parent
+    for directory in reversed(missing):
+        descriptor = _security_descriptor(FILE_ALL_ACCESS_SDDL)
+        if descriptor is None:
+            directory.mkdir(exist_ok=True)
+            continue
+        attributes = _SECURITY_ATTRIBUTES()
+        attributes.nLength = ctypes.sizeof(_SECURITY_ATTRIBUTES)
+        attributes.lpSecurityDescriptor = descriptor
+        attributes.bInheritHandle = False
+        try:
+            if not kernel32.CreateDirectoryW(str(directory), ctypes.byref(attributes)):
+                error = last_getlasterror()
+                if error != 183 and not directory.exists():  # ERROR_ALREADY_EXISTS
+                    log.debug("hardened CreateDirectory failed (%s); falling back", error)
+                    directory.mkdir(exist_ok=True)
+        finally:
+            _local_free(descriptor)
+    return target
+
+
+def secure_write_json(path: os.PathLike, payload: Dict[str, Any]) -> Path:
+    """Atomically write JSON into a file that is not group/world accessible."""
+    target = Path(path)
+    secure_mkdir(target.parent)
+    text = json.dumps(payload, indent=2, sort_keys=True, default=str)
+    temp = target.with_suffix(target.suffix + f".{uuid.uuid4().hex[:8]}.tmp")
+    temp.write_text(text, encoding="utf-8")
+    os.replace(temp, target)
+    return target
+
+
+# --------------------------------------------------------------------------------------
+# Subprocess execution
+# --------------------------------------------------------------------------------------
+
+
+@dataclass
+class CommandResult:
+    argv: Sequence[str]
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+    log_path: Optional[str] = None
+    duration: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    @property
+    def requires_reboot(self) -> bool:
+        return self.returncode == 3010
+
+    @property
+    def rendered(self) -> str:
+        return " ".join(str(a) if " " not in str(a) else f'"{a}"' for a in self.argv)
+
+    def to_dict(self) -> dict:
+        return {
+            "argv": list(self.argv),
+            "returncode": self.returncode,
+            "requires_reboot": self.requires_reboot,
+            "log_path": self.log_path,
+            "duration": round(self.duration, 3),
+            "stdout_tail": self.stdout[-2000:],
+            "stderr_tail": self.stderr[-2000:],
+        }
+
+
+def run_command(
+    argv: Sequence[str],
+    *,
+    timeout: float = 300.0,
+    log_path: Optional[os.PathLike] = None,
+    env: Optional[Dict[str, str]] = None,
+    cwd: Optional[os.PathLike] = None,
+) -> CommandResult:
+    """Run a command with no console window, capturing output and never using a shell.
+
+    ``argv`` is always passed as a list: no ``shell=True`` anywhere in this library, so
+    quotes inside a path can never turn into command injection.
+    """
+    if not argv:
+        raise ConfigError("run_command requires a non-empty argv", code="empty-argv")
+    argv = [str(a) for a in argv]
+    started = time.monotonic()
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=str(cwd) if cwd else None,
+            env=env,
+            creationflags=CREATE_NO_WINDOW if IS_WINDOWS else 0,
+            errors="replace",
+        )
+        stdout, stderr, code = completed.stdout or "", completed.stderr or "", completed.returncode
+    except FileNotFoundError as exc:
+        stdout, stderr, code = "", str(exc), 127
+    except subprocess.TimeoutExpired as exc:
+        stdout = (exc.stdout or b"").decode("utf-8", "replace") if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+        stderr = f"timed out after {timeout}s"
+        code = 124
+    duration = time.monotonic() - started
+    result = CommandResult(
+        argv=argv,
+        returncode=code,
+        stdout=stdout,
+        stderr=stderr,
+        log_path=str(log_path) if log_path else None,
+        duration=duration,
+    )
+    if log_path:
+        try:
+            secure_mkdir(Path(log_path).parent)
+            with open(log_path, "a", encoding="utf-8") as handle:
+                handle.write(f"\n=== {time.strftime('%Y-%m-%d %H:%M:%S')} {result.rendered}\n")
+                handle.write(f"--- exit code: {code} ({duration:.2f}s)\n")
+                if stdout:
+                    handle.write("--- stdout\n" + stdout + "\n")
+                if stderr:
+                    handle.write("--- stderr\n" + stderr + "\n")
+        except OSError as exc:  # pragma: no cover - logging must never break the flow
+            log.warning("could not write command log %s: %s", log_path, exc)
+    log.debug("ran %s -> %s in %.2fs", result.rendered, code, duration)
+    return result
+
+
+# --------------------------------------------------------------------------------------
+# Response pipe (child -> parent, spoof-proof)
+# --------------------------------------------------------------------------------------
+
+_PIPE_ACCESS_OUTBOUND = 0x00000002
+#: Duplex is required, not a preference: a client that asks for ``GENERIC_WRITE`` is
+#: checked against the pipe's *write* right, but an outbound-only pipe grants
+#: ``FILE_WRITE_DATA`` and the generic mapping then fails the access check with
+#: ERROR_ACCESS_DENIED (measured: outbound=FAIL 5, duplex=OK).
+_PIPE_ACCESS_DUPLEX = 0x00000003
+_FILE_FLAG_FIRST_PIPE_INSTANCE = 0x00080000
+_PIPE_TYPE_BYTE = 0x00000000
+_PIPE_READMODE_BYTE = 0x00000000
+_PIPE_WAIT = 0x00000000
+#: Non-blocking mode. Used deliberately for the **server** side of the response pipe so
+#: that a caller-supplied timeout is actually honoured: in blocking mode
+#: ``ConnectNamedPipe`` waits for ``nDefaultTimeOut`` (we would have to pass 10 minutes to
+#: cover a slow UAC prompt), which would make ``wait_for_message(timeout=...)`` a lie.
+_PIPE_NOWAIT = 0x00000001
+_INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+
+if IS_WINDOWS:  # pragma: no branch
+    # Explicit prototypes matter here: without them ctypes assumes ``int``, which
+    # truncates 64-bit HANDLEs and silently breaks named-pipe I/O on some builds.
+    kernel32.CreateNamedPipeW.argtypes = [
+        ctypes.c_wchar_p,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        ctypes.c_void_p,
+    ]
+    kernel32.CreateNamedPipeW.restype = wintypes.HANDLE
+    kernel32.ConnectNamedPipe.argtypes = [wintypes.HANDLE, ctypes.c_void_p]
+    kernel32.ConnectNamedPipe.restype = wintypes.BOOL
+    kernel32.DisconnectNamedPipe.argtypes = [wintypes.HANDLE]
+    kernel32.DisconnectNamedPipe.restype = wintypes.BOOL
+    kernel32.ReadFile.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    ]
+    kernel32.ReadFile.restype = wintypes.BOOL
+    kernel32.WriteFile.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    ]
+    kernel32.WriteFile.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    kernel32.CreateFileW.argtypes = [
+        ctypes.c_wchar_p,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        wintypes.DWORD,
+        wintypes.HANDLE,
+    ]
+    kernel32.CreateFileW.restype = wintypes.HANDLE
+
+
+class ResponsePipe:
+    """A one-shot named pipe the elevated child writes its JSON result into."""
+
+    def __init__(self, name: Optional[str] = None):
+        require_windows("ResponsePipe")
+        token = os.environ.get("USERNAME", "user")
+        self.name = name or rf"\\.\pipe\VirtualDesktop-{token}-{uuid.uuid4().hex}"
+        self._handle: Optional[int] = None
+        # The default named-pipe DACL does not always include the creating user's own
+        # account (WriteDAC is refused for non-elevated creators), and an outbound-only
+        # pipe fails the client's generic-write access check outright. Grant generic write
+        # explicitly to the owner, SYSTEM and Administrators, and keep the pipe duplex: it
+        # is then reliably usable by the elevated child while still excluding every other
+        # local user.
+        self._descriptor = _security_descriptor(f"0x{FILE_GENERIC_WRITE:08X}")
+        self._attrs = _SECURITY_ATTRIBUTES()
+        self._attrs.nLength = ctypes.sizeof(_SECURITY_ATTRIBUTES)
+        self._attrs.lpSecurityDescriptor = self._descriptor
+        self._attrs.bInheritHandle = False
+
+    def create(self) -> str:
+        handle = kernel32.CreateNamedPipeW(
+            self.name,
+            _PIPE_ACCESS_DUPLEX | _FILE_FLAG_FIRST_PIPE_INSTANCE,
+            _PIPE_TYPE_BYTE | _PIPE_READMODE_BYTE | _PIPE_NOWAIT,
+            1,
+            64 * 1024,
+            64 * 1024,
+            1000 * 60 * 10,
+            ctypes.byref(self._attrs),
+        )
+        if not handle or handle == _INVALID_HANDLE_VALUE:
+            raise OffscreenMountError(
+                f"could not create the response pipe {self.name}: {last_getlasterror()}",
+                code="pipe-create-failed",
+            )
+        self._handle = handle
+        return self.name
+
+    def wait_for_message(
+        self,
+        *,
+        timeout: float = 600.0,
+        poll: float = 0.05,
+        on_listening: Optional[callable] = None,
+    ) -> Optional[dict]:
+        """Block until the child connects (or the timeout expires), then read its JSON.
+
+        ``on_listening`` is invoked once, as soon as the pipe is listening, so a caller can
+        start the client *after* the server is ready (optional and purely an optimisation).
+        """
+        if self._handle is None:
+            raise OffscreenMountError("pipe not created", code="pipe-not-created")
+        deadline = time.monotonic() + timeout
+        connected = False
+        announced = False
+        access_denied_since: Optional[float] = None
+        while time.monotonic() < deadline:
+            if kernel32.ConnectNamedPipe(self._handle, None):
+                connected = True
+                break
+            error = last_getlasterror()
+            if error == 535:  # ERROR_PIPE_CONNECTED - client connected before we called
+                connected = True
+                break
+            # In PIPE_NOWAIT mode the *connected* state is reported as ERROR_NO_DATA (232)
+            # on the next ConnectNamedPipe call, so that error is the success signal here
+            # (measured: listening=536 -> client writes -> connected-but-reported-as-232).
+            if error == 232:
+                connected = True
+                break
+            # ERROR_PIPE_LISTENING (536) is the only proof that the pipe is *ready*; firing
+            # the callback any earlier would let a client race into ERROR_PIPE_BUSY.
+            if not announced and error == 536 and on_listening is not None:
+                announced = True
+                try:
+                    on_listening()
+                except Exception:  # pragma: no cover - callback must never break the wait
+                    log.debug("on_listening callback raised", exc_info=True)
+            if error == 5:  # ERROR_ACCESS_DENIED - the client could not open the pipe
+                if access_denied_since is None:
+                    access_denied_since = time.monotonic()
+                elif time.monotonic() - access_denied_since > min(2.0, max(timeout / 4.0, 0.25)):
+                    log.error(
+                        "the helper cannot open %s (ERROR_ACCESS_DENIED); it will not be "
+                        "able to report its result",
+                        self.name,
+                    )
+                    return None
+            time.sleep(poll)
+        if not connected:
+            log.warning("no response received on %s within %.0fs", self.name, timeout)
+            return None
+        buffer = ctypes.create_string_buffer(64 * 1024)
+        read = wintypes.DWORD()
+        chunks: List[bytes] = []
+        deadline = time.monotonic() + 5.0
+        while True:
+            ok = kernel32.ReadFile(
+                self._handle, buffer, ctypes.sizeof(buffer) - 1, ctypes.byref(read), None
+            )
+            if not ok:
+                error = last_getlasterror()
+                if error == 234:  # ERROR_MORE_DATA - message-mode leftovers, keep reading
+                    continue
+                # In PIPE_NOWAIT mode a read with no data pending reports ERROR_NO_DATA
+                # (232); the client may simply not have written yet, so retry briefly.
+                if error == 232 and time.monotonic() < deadline:
+                    time.sleep(0.02)
+                    continue
+                if error not in (232, 109):  # 109 = ERROR_BROKEN_PIPE
+                    log.debug("ReadFile on %s failed with %s", self.name, error)
+                break
+            if read.value == 0:
+                break
+            chunks.append(buffer.raw[: read.value])
+        payload = b"".join(chunks).decode("utf-8", "replace").strip()
+        if not payload:
+            return None
+        try:
+            data = json.loads(payload)
+        except json.JSONDecodeError:
+            log.warning("unparsable helper response: %r", payload[:400])
+            return None
+        return data if isinstance(data, dict) else None
+
+    def close(self) -> None:
+        if self._handle:
+            kernel32.DisconnectNamedPipe(self._handle)
+            kernel32.CloseHandle(self._handle)
+            self._handle = None
+        if getattr(self, "_descriptor", None):
+            _local_free(self._descriptor)
+            self._descriptor = None
+
+    def __enter__(self) -> "ResponsePipe":
+        self.create()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+def write_response(pipe_name: str, payload: Dict[str, Any], *, timeout: float = 30.0) -> bool:
+    """Child-side helper: open ``pipe_name`` and write the JSON payload.
+
+    Retries on ``ERROR_PIPE_BUSY`` (231), which is what a client sees if it races ahead of
+    the server's ``ConnectNamedPipe`` call. Returning silently on a busy pipe would lose the
+    child's result *and* hang the waiting parent, so this call is deliberately persistent.
+    """
+    require_windows("write_response")
+    GENERIC_WRITE = 0x40000000
+    OPEN_EXISTING = 3
+    ERROR_PIPE_BUSY = 231
+    handle = None
+    deadline = time.monotonic() + timeout
+    while True:
+        handle = kernel32.CreateFileW(pipe_name, GENERIC_WRITE, 0, None, OPEN_EXISTING, 0, None)
+        if handle and handle != _INVALID_HANDLE_VALUE:
+            break
+        error = last_getlasterror()
+        if error == ERROR_PIPE_BUSY and time.monotonic() < deadline:
+            time.sleep(0.05)
+            continue
+        log.warning("helper could not open response pipe %s: %s", pipe_name, error)
+        return False
+    try:
+        data = json.dumps(payload, default=str).encode("utf-8")
+        written = wintypes.DWORD()
+        ok = kernel32.WriteFile(handle, data, len(data), ctypes.byref(written), None)
+        if not ok:
+            log.warning("helper could not write to %s: %s", pipe_name, last_getlasterror())
+        return bool(ok)
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+# --------------------------------------------------------------------------------------
+# Elevation
+# --------------------------------------------------------------------------------------
+
+
+@dataclass
+class ElevationResult:
+    launched: bool
+    response: Optional[dict] = None
+    shell_result: int = 0
+    timed_out: bool = False
+
+    @property
+    def helper_ok(self) -> bool:
+        return bool(self.response and self.response.get("ok"))
+
+
+def package_root() -> str:
+    """Directory that must be importable for ``import VirtualDesktop`` to work."""
+    return str(Path(__file__).resolve().parent.parent)
+
+
+def import_roots() -> List[str]:
+    """Every directory the *current* interpreter imports ``VirtualDesktop`` from.
+
+    This matters for an installed package, and it is not the same as :func:`package_root`:
+
+    * a **source checkout** imports the package because its parent directory is on ``sys.path``;
+    * a **wheel install** imports it from ``site-packages``, and the *parent* of the package
+      directory is then ``site-packages`` while the code itself lives in
+      ``site-packages/VirtualDesktop``.
+
+    ``_helper.py`` adds its own directory and that directory's parent to ``sys.path``, which is
+    enough when the elevated child runs the *same* interpreter.  Handing it the real site-packages
+    as well keeps the helper working even when the elevated child resolves a different Python
+    (a different venv, or a system interpreter), which would otherwise fail with
+    ``ModuleNotFoundError: VirtualDesktop`` and a silent pipe.
+    """
+    roots: List[str] = []
+    package_dir = Path(__file__).resolve().parent
+    for candidate in (package_dir.parent, package_dir):
+        text = str(candidate)
+        if text not in roots:
+            roots.append(text)
+    try:
+        import site
+
+        for candidate in list(site.getsitepackages()) + [site.getusersitepackages()]:
+            text = str(candidate)
+            if text and text not in roots and Path(text).is_dir():
+                roots.append(text)
+    except Exception:  # pragma: no cover - site is always importable on CPython
+        log.debug("could not enumerate site-packages for the helper environment", exc_info=True)
+    return roots
+
+
+def helper_environment(base: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+    """A deliberately minimal environment for the elevated helper.
+
+    ``-E`` (ignore ``PYTHON*`` variables) is *not* used any more, because it also discards the
+    ``PYTHONPATH`` the helper needs when the library is not installed into site-packages.
+    Security is preserved by constructing the environment ourselves instead of inheriting one:
+    only the variables below are passed on, and ``PYTHONPATH`` is built from
+    :func:`import_roots` rather than taken from the caller, so neither an inherited variable nor
+    a stale one can redirect what the helper imports.  ``PYTHONSTARTUP``/``PYTHONHOME``/
+    ``PYTHONUSERBASE`` are explicitly removed.
+    """
+    source = dict(os.environ if base is None else base)
+    allowed = (
+        "SystemRoot",
+        "SystemDrive",
+        "windir",
+        "ComSpec",
+        "PATH",
+        "PATHEXT",
+        "TEMP",
+        "TMP",
+        "USERPROFILE",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "APPDATA",
+        "LOCALAPPDATA",
+        "ProgramData",
+        "ProgramFiles",
+        "ProgramFiles(x86)",
+        "ProgramW6432",
+        "CommonProgramFiles",
+        "NUMBER_OF_PROCESSORS",
+        "PROCESSOR_ARCHITECTURE",
+        "PROCESSOR_ARCHITEW6432",
+        "USERNAME",
+        "USERDOMAIN",
+        "SESSIONNAME",
+        "PUBLIC",
+        "LANG",
+        "VIRTUALDESKTOP_HELPER_TRACE",
+    )
+    env = {key: source[key] for key in allowed if key in source}
+    env["PYTHONPATH"] = os.pathsep.join(import_roots())
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    for forbidden in ("PYTHONSTARTUP", "PYTHONHOME", "PYTHONUSERBASE", "PYTHONWARNINGS"):
+        env.pop(forbidden, None)
+    return env
+
+
+def helper_command(*args: str) -> List[str]:
+    """The argv used to re-enter this library as the elevated helper.
+
+    Runs the module *by absolute path* rather than with ``-m``: ``-m`` resolves the package
+    through ``sys.path``, and the elevated child's ``sys.path`` contains only its own working
+    directory — which is not necessarily the project directory (measured: the helper died with
+    ``No module named VirtualDesktop`` while the pipe stayed silent).  Invoking
+    ``<package>/_helper.py`` works for a source checkout and for an installed wheel alike,
+    because the script directory is always on ``sys.path``.
+    """
+    helper = Path(__file__).resolve().with_name("_helper.py")
+    # ``--no-elevate`` tells the child it is already privileged: without it the child asks UAC
+    # for elevation *again* for an uninstall, because the token probe reports "not elevated"
+    # inside the elevated child on this machine (measured: the nested request never surfaced a
+    # prompt and the parent timed out with ``driver-uninstall-timeout``).
+    return [sys.executable, "-s", str(helper), "_elevated-install", "--no-elevate", *args]
+
+
+def elevate_and_run_helper(
+    args: Sequence[str],
+    *,
+    timeout: float = 900.0,
+    log_dir: Optional[os.PathLike] = None,
+    show_ui: bool = False,
+    extra_env: Optional[Dict[str, str]] = None,
+) -> ElevationResult:
+    """Re-launch this library as an elevated helper via UAC and read its result.
+
+    Uses ``ShellExecuteExW`` (not ``ShellExecuteW``) with ``SEE_MASK_NOCLOSEPROCESS`` so the
+    child's process handle is available.  That matters operationally: if the helper dies
+    immediately the wait ends at once with an actionable error instead of blocking for the
+    full (10-15 minute) driver-install timeout — which is exactly how a broken helper used to
+    present itself: "no response on the pipe" and nothing else.
+
+    ``ShellExecuteExW`` cannot pass an environment block, so the child is started through
+    ``cmd.exe /c set ... && python ...``: the *sanitised* environment is injected that way and
+    the helper inherits nothing else.
+    """
+    require_windows("elevate_and_run_helper")
+    answer: Optional[dict] = None
+    timed_out = False
+    shell_code = 0
+    exit_code: Optional[int] = None
+    env = helper_environment(os.environ | dict(extra_env or {}))
+
+    with ResponsePipe() as pipe:
+        argv = helper_command("--response-pipe", pipe.name, *args)
+        log.debug("elevating: %s", " ".join(argv))
+        launcher, parameters = _elevation_launcher(argv, env)
+        shell32.ShellExecuteExW.argtypes = [ctypes.POINTER(_SHELLEXECUTEINFOW)]
+        shell32.ShellExecuteExW.restype = wintypes.BOOL
+        info = _SHELLEXECUTEINFOW()
+        info.cbSize = ctypes.sizeof(_SHELLEXECUTEINFOW)
+        info.fMask = _SEE_MASK_NOCLOSEPROCESS | _SEE_MASK_NOASYNC
+        info.lpVerb = "runas"
+        info.lpFile = launcher
+        info.lpParameters = parameters
+        info.lpDirectory = str(log_dir) if log_dir else None
+        info.nShow = SW_HIDE if not show_ui else SW_SHOWNORMAL
+        ctypes.set_last_error(0)
+        if not shell32.ShellExecuteExW(ctypes.byref(info)):
+            error = ctypes.get_last_error()
+            log.warning("ShellExecuteExW(runas) failed with Win32 error %s", error)
+            raise ElevationDenied(
+                f"elevation was refused (Win32 error {error})",
+                details={"win32_error": error},
+            )
+        shell_code = int(info.hInstApp or 0)
+        handle = int(info.hProcess or 0)
+        if not handle:
+            raise ElevationDenied(
+                "elevation was accepted but no process was created",
+                details={"shell_result": shell_code},
+            )
+        try:
+            answer, timed_out, exit_code = _await_helper(pipe, handle, timeout)
+        finally:
+            kernel32.CloseHandle(wintypes.HANDLE(handle))
+
+    if answer is None and not timed_out:
+        raise OffscreenMountError(
+            f"the elevated helper exited with code {exit_code} before reporting a result",
+            code="helper-exited-early",
+            hint="Run `VirtualDesktop install-driver --dry-run` and then the printed helper "
+            "command from an elevated terminal to see its output.",
+            details={"exit_code": exit_code, "shell_result": shell_code},
+        )
+    return ElevationResult(
+        launched=True,
+        response=answer,
+        shell_result=shell_code or 32,
+        timed_out=timed_out,
+    )
+
+
+def _elevation_launcher(argv: Sequence[str], env: Dict[str, str]) -> tuple:
+    """Return ``(lpFile, lpParameters)`` for ``ShellExecuteExW``.
+
+    The helper is started **directly** (no ``cmd.exe`` wrapper).  An earlier revision injected
+    the sanitised environment through ``cmd /c set "K=V" && ...``; that died with exit code 1
+    and produced no log, because the assembled command line ran into the ``cmd.exe`` length
+    limit.  Direct invocation works because:
+
+    * the helper is addressed by absolute path, so its own directory lands on ``sys.path``;
+    * the elevated child inherits a normal user environment from the shell (measured: ``TEMP``,
+      ``LOCALAPPDATA`` and ``SystemRoot`` are all present), so nothing has to be injected;
+    * every value the helper needs from us (cache dir, strategy, signature policy, log dir) is
+      already an explicit command-line argument.
+
+    ``env`` is therefore only used by the caller that builds it (for diagnostics); it is not
+    placed on the command line.
+    """
+    inner = subprocess.list2cmdline([str(a) for a in argv])
+    if len(inner) > 8000:  # cmd/ShellExecute safety margin
+        raise ConfigError(
+            "the helper command line is too long to launch reliably",
+            code="helper-command-too-long",
+            details={"length": len(inner)},
+        )
+    return str(argv[0]), subprocess.list2cmdline([str(a) for a in argv[1:]])
+
+
+def _await_helper(pipe: "ResponsePipe", handle: int, timeout: float):
+    """Wait for the pipe message, aborting early if the helper process dies."""
+    kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    kernel32.WaitForSingleObject.restype = wintypes.DWORD
+    kernel32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.GetExitCodeProcess.restype = wintypes.BOOL
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        answer = pipe.wait_for_message(timeout=1.0, poll=0.05)
+        if answer is not None:
+            return answer, False, None
+        code = wintypes.DWORD()
+        if kernel32.GetExitCodeProcess(wintypes.HANDLE(handle), ctypes.byref(code)):
+            if code.value != _STILL_ACTIVE:
+                # Give the pipe one last chance: the child may have written and exited.
+                return pipe.wait_for_message(timeout=2.0, poll=0.05), False, int(code.value)
+        time.sleep(0.1)
+    return None, True, None
+
+
+def default_log_dir(cache_dir: Optional[os.PathLike] = None) -> Path:
+    from ._download import default_cache_dir
+
+    root = Path(cache_dir) if cache_dir else default_cache_dir()
+    return secure_mkdir(root / "logs")
+
+
+def tail_file(path: os.PathLike, *, lines: int = 40) -> str:
+    """Last ``lines`` lines of a file, for error messages."""
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            content = handle.readlines()
+    except OSError:
+        return ""
+    return "".join(content[-lines:])