VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/driver.py

@@ -0,0 +1,831 @@
+"""Driver bootstrap: detect, verify, install and remove the virtual display driver.
+
+The flow is deliberately *two-phase*, because installing a display driver is a
+machine-wide privileged operation:
+
+1. **Unprivileged phase** (this module, first call): work out whether the device already
+   exists. If it does, nothing else happens — the common case costs a single SetupAPI
+   enumeration.
+2. **Privileged phase** (``--internal-elevated`` child): download + digest-verify the
+   package, verify its Authenticode signature, then create the ROOT device node and bind
+   the driver with ``nefconw``.
+
+If the process is already elevated, phase 2 runs in-process; otherwise it is executed
+through UAC via :func:`~VirtualDesktop._process.elevate_and_run_helper`, and the caller
+gets the child's structured result back over a private named pipe.
+
+Nothing here shells out with ``shell=True``, nothing is installed without a SHA-256 match
+against the manifest, and a driver that fails signature verification is reported instead
+of being installed silently (``signature_policy="warn"``) or refused
+(``signature_policy="strict"``).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from ._bundle import BundleManager, driver_spec_for_arch, machine_arch
+from ._devices import device_status_summary, find_devices_by_hardware_id
+from ._download import cache_status, default_cache_dir
+from ._log import get_logger
+from ._process import (
+    CommandResult,
+    default_log_dir,
+    elevate_and_run_helper,
+    run_command,
+    tail_file,
+    write_response,
+)
+from ._sigcheck import assert_driver_trusted
+from ._winapi import IS_WINDOWS, enumerate_monitors, is_admin, is_system_session, require_windows
+from .errors import (
+    ConfigError,
+    DriverInstallError,
+    DriverNotFoundError,
+    ElevationDenied,
+    ElevationRequired,
+    OffscreenMountError,
+)
+from .manifest import Manifest, load_manifest
+
+log = get_logger("driver")
+
+__all__ = [
+    "STRATEGIES",
+    "VIRTUAL_DISPLAY_MARKERS",
+    "InstallReport",
+    "DriverInstaller",
+    "virtual_display_present",
+    "wait_for_virtual_display",
+]
+
+#: Marker substrings that identify our virtual display among all display devices.
+VIRTUAL_DISPLAY_MARKERS = ("MttVDD", "VID_1B0F", "IddSampleDriver", "ROOT\\IDD")
+STRATEGIES = ("auto", "nefcon", "nefcon-manual", "pnputil", "scoop")
+_REBOOT_REQUIRED = 3010
+
+
+def virtual_display_present(
+    markers: Sequence[str] = VIRTUAL_DISPLAY_MARKERS, *, extra_markers: Sequence[str] = ()
+) -> bool:
+    """True when a virtual display device is registered (installed), present or not.
+
+    This is a *device* check (SetupAPI), which is what matters: a driver can be installed
+    and enabled while its monitor is temporarily absent, and vice versa.
+    """
+    if not IS_WINDOWS:
+        return False
+    summary = device_status_summary([*markers, *extra_markers])
+    return bool(summary["present"])
+
+
+def wait_for_virtual_display(
+    timeout: float = 20.0,
+    *,
+    interval: float = 1.0,
+    markers: Sequence[str] = VIRTUAL_DISPLAY_MARKERS,
+    extra_markers: Sequence[str] = (),
+) -> bool:
+    """Poll for the monitor to show up after installation (drivers come up asynchronously)."""
+    deadline = time.monotonic() + timeout
+    while True:
+        if IS_WINDOWS:
+            monitors = enumerate_monitors()
+            if any(
+                any(
+                    m.upper() in f"{mon.device_string} {mon.pnp_device_id}".upper()
+                    for m in [*markers, *extra_markers]
+                )
+                for mon in monitors
+            ):
+                return True
+        if virtual_display_present(markers, extra_markers=extra_markers):
+            # Device is registered; the monitor itself may need a few more seconds.
+            if IS_WINDOWS and time.monotonic() < deadline:
+                monitors = enumerate_monitors()
+                if len(monitors) > 1:
+                    return True
+            else:
+                return True
+        if time.monotonic() >= deadline:
+            return virtual_display_present(markers, extra_markers=extra_markers)
+        time.sleep(interval)
+
+
+@dataclass
+class InstallReport:
+    """Structured outcome of a bootstrap attempt (JSON-serialisable)."""
+
+    action: str = "detect"
+    ok: bool = False
+    device_present: bool = False
+    driver: str = ""
+    version: str = ""
+    strategy_used: str = ""
+    elevated: bool = False
+    requires_reboot: bool = False
+    skipped_reason: str = ""
+    signature_findings: List[str] = field(default_factory=list)
+    commands: List[dict] = field(default_factory=list)
+    cache: Dict[str, Any] = field(default_factory=dict)
+    message: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "action": self.action,
+            "ok": self.ok,
+            "device_present": self.device_present,
+            "driver": self.driver,
+            "version": self.version,
+            "strategy_used": self.strategy_used,
+            "elevated": self.elevated,
+            "requires_reboot": self.requires_reboot,
+            "skipped_reason": self.skipped_reason,
+            "signature_findings": list(self.signature_findings),
+            "commands": list(self.commands),
+            "cache": dict(self.cache),
+            "message": self.message,
+        }
+
+
+class DriverInstaller:
+    """Owns every decision about the virtual display driver."""
+
+    def __init__(
+        self,
+        *,
+        manifest: Optional[Manifest] = None,
+        cache_dir: Optional[os.PathLike] = None,
+        driver: Optional[str] = None,
+        strategy: str = "auto",
+        signature_policy: str = "warn",
+        allow_scoop: bool = False,
+        install_timeout: float = 600.0,
+        download_timeout: float = 300.0,
+        monitor_tags: Sequence[str] = (),
+    ) -> None:
+        if strategy not in STRATEGIES:
+            raise ConfigError(
+                f"unknown strategy {strategy!r}; expected one of {', '.join(STRATEGIES)}",
+                code="bad-strategy",
+            )
+        if signature_policy not in ("warn", "strict", "off"):
+            raise ConfigError(
+                f"unknown signature_policy {signature_policy!r}", code="bad-signature-policy"
+            )
+        self.manifest = manifest or load_manifest()
+        self.cache_dir = Path(cache_dir) if cache_dir else default_cache_dir()
+        self.spec = driver_spec_for_arch(self.manifest, driver)
+        self.strategy = strategy
+        self.signature_policy = signature_policy
+        self.allow_scoop = allow_scoop
+        self.install_timeout = install_timeout
+        self.download_timeout = download_timeout
+        self.monitor_tags = tuple(monitor_tags)
+        self.bundles = BundleManager(self.cache_dir)
+        self.log_dir = default_log_dir(self.cache_dir)
+
+    # -- detection -------------------------------------------------------------------
+    @property
+    def markers(self) -> tuple:
+        return tuple(VIRTUAL_DISPLAY_MARKERS) + tuple(self.spec.device_match) + self.monitor_tags
+
+    def is_present(self) -> bool:
+        return virtual_display_present(extra_markers=self.markers)
+
+    def devices(self) -> List[dict]:
+        return device_status_summary(self.markers)["devices"]
+
+    def detect(self) -> InstallReport:
+        present = self.is_present()
+        return InstallReport(
+            action="detect",
+            ok=present,
+            device_present=present,
+            driver=self.spec.name,
+            version=self.spec.version,
+            skipped_reason="" if present else "device-absent",
+            cache=self.cache_report(),
+            message=(
+                "virtual display device is registered"
+                if present
+                else "virtual display device is not installed yet"
+            ),
+        )
+
+    def cache_report(self) -> Dict[str, Any]:
+        artifact = self.spec.artifact
+        status = cache_status(artifact, self.cache_dir)
+        return {
+            "cache_dir": str(self.cache_dir),
+            "artifact": artifact.filename,
+            "artifact_url": artifact.url,
+            "artifact_cached": status.ok,
+            "artifact_reason": status.reason,
+            "driver_tree": bool(self.bundles.cached_driver(self.spec)),
+            "tools": self.bundles.tools_integrity(self.manifest),
+            "log_dir": str(self.log_dir),
+        }
+
+    # -- installation ----------------------------------------------------------------
+    def ensure(self, *, allow_install: bool = True, timeout: Optional[float] = None) -> InstallReport:
+        """Install the driver when it is missing, going through UAC when needed."""
+        present = self.is_present()
+        if present:
+            report = self.detect()
+            report.action = "ensure"
+            report.skipped_reason = "already-installed"
+            report.message = "virtual display device already present; nothing to install"
+            log.info(report.message)
+            return report
+        if not allow_install:
+            raise DriverNotFoundError(
+                "no virtual display device is installed and driver installation is disabled "
+                "(driver_policy='never')",
+                details={"driver": self.spec.name, "markers": list(self.markers)},
+            )
+        if is_admin():
+            log.info("process is elevated; installing the driver in-process")
+            report = self.install(timeout=timeout)
+            report.elevated = True
+            return report
+        if is_system_session():
+            raise ElevationRequired(
+                "driver installation is required but the process runs in a non-interactive "
+                "session, so a UAC prompt cannot be shown",
+                hint="Pre-install the driver once from an elevated terminal: "
+                "`VirtualDesktop install-driver`.",
+            )
+        return self._install_elevated(timeout=timeout)
+
+    def _announce(self, action: str) -> None:
+        """Tell the operator that a UAC prompt is imminent.
+
+        The elevated call blocks on the helper's response pipe, so a silent console looks like a
+        hang while the consent dialog waits for a click.  Printing first makes the interaction
+        obvious (and is the difference between "it hung" and "I missed the prompt").
+        """
+        print(
+            f"[VirtualDesktop] {action} requires administrator rights - "
+            "approve the UAC prompt (press Enter on it) to continue ...",
+            flush=True,
+        )
+
+    @staticmethod
+    def _helper_env() -> Dict[str, str]:
+        """Extra environment the elevated helper needs, and nothing more.
+
+        The helper builds its own minimal environment; these are the values it legitimately
+        needs from us: which manifest to trust, and whether the operator asked for debug logs.
+        """
+        passthrough = ("VIRTUALDESKTOP_MANIFEST", "VIRTUALDESKTOP_DEBUG", "VIRTUALDESKTOP_HELPER_TRACE")
+        return {name: os.environ[name] for name in passthrough if os.environ.get(name)}
+
+    def _install_elevated(self, *, timeout: Optional[float] = None) -> InstallReport:
+        """Run the privileged phase through UAC and translate the child's report."""
+        log.info("driver is missing; requesting elevation to install %s", self.spec.name)
+        self._announce(f"installing driver {self.spec.name}")
+        log_dir = str(self.log_dir)
+        try:
+            result = elevate_and_run_helper(
+                [
+                    "--cache-dir",
+                    str(self.cache_dir),
+                    "--strategy",
+                    self.strategy,
+                    "--signature-policy",
+                    self.signature_policy,
+                    "--driver",
+                    self.spec.name,
+                    "--install-timeout",
+                    str(self.install_timeout),
+                    "--log-dir",
+                    log_dir,
+                ],
+                timeout=timeout or (self.install_timeout + 300.0),
+                log_dir=log_dir,
+                extra_env=self._helper_env(),
+            )
+        except ElevationDenied:
+            raise
+        if result.timed_out:
+            raise DriverInstallError(
+                "the elevated installer did not report a result before the timeout",
+                hint=f"Check {self.log_dir} for the elevated log.",
+                code="driver-install-timeout",
+            )
+        response = result.response or {}
+        report = InstallReport(
+            action="install",
+            ok=bool(response.get("ok")),
+            device_present=bool(response.get("device_present")),
+            driver=str(response.get("driver", self.spec.name)),
+            version=str(response.get("version", self.spec.version)),
+            strategy_used=str(response.get("strategy_used", "")),
+            elevated=True,
+            requires_reboot=bool(response.get("requires_reboot")),
+            signature_findings=list(response.get("signature_findings") or []),
+            commands=list(response.get("commands") or []),
+            cache=self.cache_report(),
+            message=str(response.get("message", "")),
+        )
+        if not report.ok:
+            detail = response.get("error") or report.message or "unknown failure"
+            raise DriverInstallError(
+                f"the elevated driver installation failed: {detail}",
+                attempts=[c.get("argv", []) for c in report.commands],
+                hint=f"Full log: {self.log_dir}",
+                details={"response": response},
+            )
+        log.info("elevated installation succeeded (%s)", report.strategy_used)
+        return report
+
+    def install(self, *, timeout: Optional[float] = None) -> InstallReport:
+        """Privileged phase: download, verify, extract and install. Must run elevated."""
+        require_windows("driver installation")
+        report = self.detect()
+        report.action = "install"
+        report.elevated = is_admin()
+        if report.device_present:
+            report.ok = True
+            report.skipped_reason = "already-installed"
+            report.message = "virtual display device already present"
+            return report
+
+        bundle = self.bundles.prepare_driver(self.spec, progress=self._progress_logger())
+        report.driver = self.spec.name
+        report.version = self.spec.version
+        report.signature_findings = assert_driver_trusted(
+            bundle.driver_dir,
+            self.spec.signer_thumbprints,
+            policy=self.signature_policy,
+        )
+        report.cache = self.cache_report()
+
+        attempts: List[str] = []
+        for name, runner in self._strategy_order():
+            log.info("trying driver install strategy %s", name)
+            outcome = runner(bundle, timeout=timeout)
+            report.commands.extend(outcome.setdefault("commands", []))
+            if outcome.get("ok"):
+                report.ok = True
+                report.strategy_used = name
+                report.requires_reboot = bool(outcome.get("requires_reboot"))
+                report.message = outcome.get("message", f"installed via {name}")
+                break
+            attempts.append(f"{name}: {outcome.get('message', 'failed')}")
+            if outcome.get("fatal"):
+                break
+        else:
+            report.ok = False
+
+        if not report.ok:
+            raise DriverInstallError(
+                "all driver installation strategies failed",
+                attempts=attempts,
+                code="driver-install-failed",
+                hint=f"Inspect {self.log_dir} (nefcon output is captured there).",
+                details={"driver": self.spec.name, "attempts": attempts},
+            )
+
+        report.device_present = wait_for_virtual_display(
+            timeout=20.0, extra_markers=self.markers
+        )
+        if not report.device_present:
+            report.message += " (device registered but its monitor has not appeared yet)"
+            log.warning("driver installed but no virtual monitor is visible yet")
+        if report.requires_reboot:
+            report.message += " - a reboot is required to finish the installation"
+            log.warning("driver install reported ERROR_SUCCESS_REBOOT_REQUIRED (3010)")
+        return report
+
+    def _progress_logger(self):
+        state = {"next": 0.0}
+
+        def _progress(done: int, total: Optional[int]) -> None:
+            now = time.monotonic()
+            if now < state["next"] and (total is None or done < total):
+                return
+            state["next"] = now + 2.0
+            if total:
+                log.info("downloading driver package: %.1f%% (%d/%d bytes)", 100.0 * done / total, done, total)
+            else:
+                log.info("downloading driver package: %d bytes", done)
+
+        return _progress
+
+    def _strategy_order(self):
+        """Yield ``(name, callable)`` pairs in the order dictated by ``strategy``."""
+        available = {
+            "nefcon": self._strategy_nefcon,
+            "nefcon-manual": self._strategy_nefcon_manual,
+            "pnputil": self._strategy_pnputil,
+            "scoop": self._strategy_scoop,
+        }
+        if self.strategy == "auto":
+            order = ["nefcon", "nefcon-manual", "pnputil"]
+        else:
+            order = [self.strategy]
+        for name in order:
+            runner = available.get(name)
+            if runner is None:
+                continue
+            if name == "scoop" and not self.allow_scoop:
+                log.debug("skipping the scoop strategy (allow_scoop=False)")
+                continue
+            yield name, runner
+
+    # -- individual strategies -------------------------------------------------------
+    def _nefcon(self, *, console: bool = False) -> Path:
+        tool = "nefcon_console" if console else "nefcon"
+        return self.bundles.tool(self.manifest, tool, progress=self._progress_logger())
+
+    def _log_file(self, name: str) -> Path:
+        return self.log_dir / f"{name}.log"
+
+    def _strategy_nefcon(self, bundle, *, timeout: Optional[float] = None) -> dict:
+        """``nefconw install <inf> <hwid> --no-duplicates``: device node + driver in one step."""
+        try:
+            exe = self._nefcon()
+        except OffscreenMountError as exc:
+            return {"ok": False, "message": f"nefcon unavailable: {exc}", "commands": []}
+        commands: List[dict] = []
+        last_message = ""
+        for hardware_id in self.spec.all_hardware_ids:
+            argv = [str(exe), "install", str(bundle.inf_path), hardware_id, "--no-duplicates"]
+            result = run_command(
+                argv,
+                timeout=timeout or self.install_timeout,
+                log_path=self._log_file("nefcon-install"),
+            )
+            commands.append(result.to_dict())
+            if result.ok or result.requires_reboot:
+                return {
+                    "ok": True,
+                    "requires_reboot": result.requires_reboot,
+                    "message": f"nefcon install succeeded for {hardware_id}",
+                    "commands": commands,
+                    "result": result,
+                }
+            last_message = (result.stderr or result.stdout or "").strip()[-400:]
+            log.warning("nefcon install failed for %s (exit %s): %s", hardware_id, result.returncode, last_message)
+        return {
+            "ok": False,
+            "message": f"nefcon install failed: {last_message or 'unknown error'}",
+            "commands": commands,
+        }
+
+    def _strategy_nefcon_manual(self, bundle, *, timeout: Optional[float] = None) -> dict:
+        """Explicit ``--create-device-node`` + ``--install-driver`` (matches the docs)."""
+        try:
+            exe = self._nefcon()
+        except OffscreenMountError as exc:
+            return {"ok": False, "message": f"nefcon unavailable: {exc}", "commands": []}
+        commands: List[dict] = []
+        create = run_command(
+            [
+                str(exe),
+                "--create-device-node",
+                "--hardware-id",
+                self.spec.hardware_id,
+                "--class-name",
+                self.spec.class_name,
+                "--class-guid",
+                self.spec.class_guid,
+                "--no-duplicates",
+            ],
+            timeout=timeout or self.install_timeout,
+            log_path=self._log_file("nefcon-create-node"),
+        )
+        commands.append(create.to_dict())
+        # Already-existing node is not an error for us; the install step is what matters.
+        if not create.ok and not _looks_like_already_exists(create):
+            return {
+                "ok": False,
+                "message": f"device node creation failed: {_tail(create)}",
+                "commands": commands,
+            }
+        install = run_command(
+            [str(exe), "--install-driver", "--inf-path", str(bundle.inf_path)],
+            timeout=timeout or self.install_timeout,
+            log_path=self._log_file("nefcon-install-driver"),
+        )
+        commands.append(install.to_dict())
+        if install.ok or install.requires_reboot:
+            return {
+                "ok": True,
+                "requires_reboot": install.requires_reboot,
+                "message": "device node created and driver installed",
+                "commands": commands,
+                "result": install,
+            }
+        return {
+            "ok": False,
+            "message": f"--install-driver failed: {_tail(install)}",
+            "commands": commands,
+        }
+
+    def _strategy_pnputil(self, bundle, *, timeout: Optional[float] = None) -> dict:
+        """Fallback: add the package to the driver store and let PnP bind the ROOT node."""
+        pnputil = os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32", "pnputil.exe")
+        if not os.path.isfile(pnputil):
+            return {"ok": False, "message": "pnputil.exe not found", "commands": []}
+        commands: List[dict] = []
+        add = run_command(
+            [pnputil, "/add-driver", str(bundle.inf_path), "/install"],
+            timeout=timeout or self.install_timeout,
+            log_path=self._log_file("pnputil-add-driver"),
+        )
+        commands.append(add.to_dict())
+        if add.ok or _REBOOT_REQUIRED == add.returncode:
+            # pnputil cannot create a ROOT-enumerated node; nefcon (or the installer the
+            # user ran) must have created one already for the driver to bind.
+            if self.is_present():
+                return {
+                    "ok": True,
+                    "requires_reboot": add.returncode == _REBOOT_REQUIRED,
+                    "message": "driver store updated and the device is present",
+                    "commands": commands,
+                    "result": add,
+                }
+            return {
+                "ok": False,
+                "message": (
+                    "pnputil added the package but no ROOT\\MttVDD device node exists, so the "
+                    "driver cannot bind (this is the documented pnputil limitation)"
+                ),
+                "commands": commands,
+            }
+        return {
+            "ok": False,
+            "message": f"pnputil failed: {_tail(add)}",
+            "commands": commands,
+        }
+
+    def _strategy_scoop(self, bundle, *, timeout: Optional[float] = None) -> dict:
+        """Opt-in convenience path for machines that already use Scoop."""
+        import shutil
+
+        if not self.allow_scoop:
+            return {"ok": False, "message": "scoop strategy disabled (allow_scoop=False)", "commands": []}
+        scoop = shutil.which("scoop")
+        if not scoop:
+            return {"ok": False, "message": "scoop is not on PATH", "commands": []}
+        commands: List[dict] = []
+        for argv in (
+            [scoop, "bucket", "add", "extras"],
+            [scoop, "bucket", "add", "nonportable"],
+            [scoop, "install", "iddsampledriver-ge9-np", "-g"],
+        ):
+            result = run_command(
+                argv, timeout=timeout or self.install_timeout, log_path=self._log_file("scoop")
+            )
+            commands.append(result.to_dict())
+            if not result.ok and "already" not in (result.stderr or "").lower():
+                return {
+                    "ok": False,
+                    "message": f"scoop step failed: {_tail(result)}",
+                    "commands": commands,
+                }
+        return {
+            "ok": self.is_present(),
+            "message": "scoop finished" if self.is_present() else "scoop ran but no device appeared",
+            "commands": commands,
+        }
+
+    # -- removal ---------------------------------------------------------------------
+    def uninstall(
+        self,
+        *,
+        purge_files: bool = False,
+        purge_driver_store: bool = False,
+        timeout: Optional[float] = None,
+        elevate: bool = True,
+    ) -> InstallReport:
+        """Remove the device node, optionally purging the store package and cached files.
+
+        Removal is a privileged operation (measured: nefcon refuses with "This command requires
+        elevated privileges"), so an unelevated caller is routed through the same UAC helper that
+        installation uses.  ``elevate=False`` keeps the in-process behaviour for callers that are
+        already elevated (the helper passes it that way).
+        """
+        require_windows("driver uninstall")
+        if elevate and not is_admin():
+            return self._uninstall_elevated(
+                purge_files=purge_files, purge_driver_store=purge_driver_store, timeout=timeout
+            )
+        return self._uninstall_in_process(
+            purge_files=purge_files, purge_driver_store=purge_driver_store, timeout=timeout
+        )
+
+    def _uninstall_in_process(
+        self,
+        *,
+        purge_files: bool = False,
+        purge_driver_store: bool = False,
+        timeout: Optional[float] = None,
+    ) -> InstallReport:
+        report = self.detect()
+        report.action = "uninstall"
+        if not report.device_present:
+            report.ok = True
+            report.message = "no virtual display device was registered"
+        else:
+            try:
+                exe = self._nefcon()
+            except OffscreenMountError as exc:
+                raise DriverInstallError(
+                    f"nefcon is required to remove the device node: {exc}",
+                    hint="Run `VirtualDesktop fetch-driver` first (needs network access).",
+                ) from exc
+            remove = run_command(
+                [
+                    str(exe),
+                    "--remove-device-node",
+                    "--hardware-id",
+                    self.spec.hardware_id,
+                    "--class-guid",
+                    self.spec.class_guid,
+                ],
+                timeout=timeout or self.install_timeout,
+                log_path=self._log_file("nefcon-remove-device-node"),
+            )
+            report.commands.append(remove.to_dict())
+            report.ok = remove.ok or remove.requires_reboot
+            report.requires_reboot = remove.requires_reboot
+            report.message = "device node removed" if report.ok else f"removal failed: {_tail(remove)}"
+            if not report.ok:
+                raise DriverInstallError(
+                    f"could not remove the virtual display device: {_tail(remove)}",
+                    attempts=[remove.to_dict()],
+                    hint=f"See {self._log_file('nefcon-remove-device-node')}",
+                )
+            if purge_driver_store:
+                purge = run_command(
+                    [
+                        str(exe),
+                        "--remove-driver-store-package",
+                        "--inf-name",
+                        Path(self.spec.inf_member).name,
+                        "--class-guid",
+                        self.spec.class_guid,
+                    ],
+                    timeout=timeout or self.install_timeout,
+                    log_path=self._log_file("nefcon-purge-package"),
+                )
+                report.commands.append(purge.to_dict())
+                if not purge.ok:
+                    log.warning("driver-store purge failed: %s", _tail(purge))
+        if purge_files:
+            report.skipped_reason = (
+                "cached driver tree removed"
+                if self.bundles.remove_driver_tree(self.spec)
+                else "no cached driver tree to remove"
+            )
+        return report
+
+    def _uninstall_elevated(
+        self,
+        *,
+        purge_files: bool,
+        purge_driver_store: bool,
+        timeout: Optional[float] = None,
+    ) -> InstallReport:
+        """Run the removal through UAC, exactly like installation does."""
+        log.info("removing the virtual display; requesting elevation")
+        self._announce("removing the virtual display driver")
+        log_dir = str(self.log_dir)
+        try:
+            result = elevate_and_run_helper(
+                [
+                    "--uninstall",
+                    "--cache-dir",
+                    str(self.cache_dir),
+                    "--driver",
+                    self.spec.name,
+                    "--install-timeout",
+                    str(self.install_timeout),
+                    "--log-dir",
+                    log_dir,
+                    *(["--purge-files"] if purge_files else []),
+                    *(["--purge-driver-store"] if purge_driver_store else []),
+                ],
+                timeout=timeout or (self.install_timeout + 300.0),
+                log_dir=log_dir,
+                extra_env=self._helper_env(),
+            )
+        except ElevationDenied:
+            raise
+        if result.timed_out:
+            raise DriverInstallError(
+                "the elevated uninstaller did not report a result before the timeout",
+                hint=f"Check {self.log_dir} for the elevated log.",
+                code="driver-uninstall-timeout",
+            )
+        response = result.response or {}
+        report = InstallReport(
+            action="uninstall",
+            ok=bool(response.get("ok")),
+            device_present=bool(response.get("device_present")),
+            driver=str(response.get("driver", self.spec.name)),
+            elevated=True,
+            requires_reboot=bool(response.get("requires_reboot")),
+            commands=list(response.get("commands") or []),
+            cache=self.cache_report(),
+            message=str(response.get("message", "")),
+        )
+        if not report.ok:
+            detail = response.get("error") or report.message or "unknown failure"
+            raise DriverInstallError(
+                f"the elevated removal failed: {detail}",
+                attempts=[c.get("argv", []) for c in report.commands],
+                hint=f"Full log: {self.log_dir}",
+                details={"response": response},
+            )
+        log.info("elevated removal succeeded")
+        return report
+
+
+def _tail(result: CommandResult, limit: int = 400) -> str:
+    text = (result.stderr or "").strip() or (result.stdout or "").strip()
+    return text[-limit:] if text else f"exit code {result.returncode}"
+
+
+def _looks_like_already_exists(result: CommandResult) -> bool:
+    haystack = f"{result.stdout} {result.stderr}".lower()
+    return "already exists" in haystack or "0x800700b7" in haystack or "183" in haystack
+
+
+def install_from_helper(
+    *,
+    cache_dir: Optional[str] = None,
+    strategy: str = "auto",
+    signature_policy: str = "warn",
+    driver: Optional[str] = None,
+    install_timeout: float = 600.0,
+    log_dir: Optional[str] = None,
+    response_pipe: Optional[str] = None,
+    uninstall: bool = False,
+    purge_files: bool = False,
+    purge_driver_store: bool = False,
+    elevate: bool = True,
+) -> int:
+    """Entry point for the elevated child process (``_elevated-install``).
+
+    Handles both directions: installing (default) and **removing** the device
+    (``uninstall=True``).  Removal needs the same privilege as installation — measured: nefcon
+    answers ``This command requires elevated privileges`` otherwise, which is why
+    ``VirtualDesktop uninstall-driver`` goes through this helper exactly like installation does.
+
+    ``elevate`` must be ``False`` when *this* call already runs inside the elevated child.  It is
+    the caller's decision, not a token probe: the token probe (``is_admin()``) reports "not
+    elevated" inside the elevated child on some configurations, and ``uninstall()`` would then
+    ask UAC for elevation a second time — spawning a nested helper that nobody is left to
+    approve, so the outer helper waited on its pipe until the parent gave up
+    (measured: ``driver-uninstall-timeout`` with no ``consent.exe`` and no helper process).
+    """
+    payload: Dict[str, Any] = {"ok": False, "action": "uninstall" if uninstall else "install"}
+    exit_code = 1
+    installer: Optional[DriverInstaller] = None
+    try:
+        installer = DriverInstaller(
+            cache_dir=cache_dir,
+            driver=driver,
+            strategy=strategy,
+            signature_policy=signature_policy,
+            install_timeout=install_timeout,
+        )
+        if uninstall:
+            report = installer.uninstall(
+                purge_files=purge_files,
+                purge_driver_store=purge_driver_store,
+                timeout=install_timeout,
+                elevate=elevate,
+            )
+            payload = report.to_dict()
+            payload["ok"] = bool(report.ok) and not installer.is_present()
+            payload["device_present"] = installer.is_present()
+            exit_code = 0 if payload["ok"] else 1
+        else:
+            report = installer.install()
+            payload = report.to_dict()
+            payload["ok"] = True
+            payload["device_present"] = report.device_present
+            exit_code = 0
+    except Exception as exc:  # noqa: BLE001 - the child must never die silently
+        log.exception("elevated driver operation failed")
+        payload["ok"] = False
+        payload["error"] = str(exc)
+        payload["error_code"] = getattr(exc, "code", type(exc).__name__)
+        payload["hint"] = getattr(exc, "hint", None)
+        if isinstance(exc, DriverInstallError):
+            payload["commands"] = list(exc.details.get("attempts") or [])
+        payload["cache"] = installer.cache_report() if installer else {}
+    finally:
+        if response_pipe:
+            write_response(response_pipe, payload)
+    return exit_code