VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/_download.py

@@ -0,0 +1,462 @@
+"""Download, cache, verify and safely extract release artifacts.
+
+Security posture (all of it is enforced, not optional):
+
+* **HTTPS only** – the manifest rejects anything else and redirects are re-checked.
+* **Digest pinning** – a file is only accepted when its SHA-256 matches the manifest.
+  Anything else is moved to ``<cache>/quarantine`` and never executed.
+* **Size ceilings** – a declared size is enforced (±1 %), and an undeclared size is capped
+  at ``max_bytes`` so a hostile endpoint cannot exhaust the disk.
+* **Atomic publish** – downloads land in ``<cache>/.tmp`` and are moved into place with
+  ``os.replace`` only after verification, so a crash never leaves a half-written artifact.
+* **Locking** – a per-artifact lock file serialises concurrent processes (multi-process
+  safety matters because the first ``mount()`` of two processes can race).
+* **Safe extraction** – zip members are validated against traversal, absolute paths,
+  symlinks, member-count, and expansion-ratio limits before anything is written.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import ssl
+import stat
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import uuid
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from .errors import DownloadError, ExtractionError, IntegrityError
+from .manifest import Artifact
+
+log = get_logger("download")
+
+__all__ = [
+    "default_cache_dir",
+    "verified_path",
+    "cache_status",
+    "download_artifact",
+    "extract_archive",
+    "file_sha256",
+    "sha256_of",
+    "FileLock",
+    "VerifyResult",
+]
+
+_CHUNK = 256 * 1024
+#: A zip may legitimately expand, but not without bound (zip-bomb guard).
+_MAX_EXPANSION_RATIO = 40
+_MAX_MEMBERS = 512
+_USER_AGENT = "VirtualDesktop/0.1 (+https://github.com/example/VirtualDesktop)"
+
+
+def default_cache_dir() -> Path:
+    """Per-user cache root, overridable with ``VIRTUALDESKTOP_CACHE_DIR``."""
+    override = os.environ.get("VIRTUALDESKTOP_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("LOCALAPPDATA") or os.environ.get("XDG_CACHE_HOME")
+    if base:
+        return Path(base) / "VirtualDesktop" / "cache"
+    return Path(tempfile.gettempdir()) / "VirtualDesktop-cache"  # pragma: no cover
+
+
+def file_sha256(path: os.PathLike, *, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for block in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+#: Backwards-compatible alias.
+sha256_of = file_sha256
+
+
+@dataclass
+class VerifyResult:
+    """Outcome of checking one cached artifact against its pinned digest."""
+
+    path: Path
+    expected: str
+    actual: str = ""
+    size: int = 0
+    ok: bool = False
+    reason: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "path": str(self.path),
+            "expected": self.expected,
+            "actual": self.actual,
+            "size": self.size,
+            "ok": self.ok,
+            "reason": self.reason,
+        }
+
+
+def verified_path(artifact: Artifact, cache_dir: Optional[os.PathLike] = None) -> Optional[Path]:
+    """Return the cached file path when it exists *and* matches the pinned digest."""
+    root = Path(cache_dir) if cache_dir else default_cache_dir()
+    candidate = root / artifact.filename
+    if not candidate.is_file():
+        return None
+    if artifact.size is not None and candidate.stat().st_size != artifact.size:
+        log.debug("cache size mismatch for %s", candidate)
+        return None
+    if file_sha256(candidate) != artifact.sha256:
+        log.warning(
+            "cached artifact %s does not match the pinned digest; it will be re-downloaded",
+            candidate,
+        )
+        return None
+    return candidate
+
+
+def cache_status(artifact: Artifact, cache_dir: Optional[os.PathLike] = None) -> VerifyResult:
+    """Detailed verification report, used by ``VirtualDesktop check``."""
+    root = Path(cache_dir) if cache_dir else default_cache_dir()
+    path = root / artifact.filename
+    result = VerifyResult(path=path, expected=artifact.sha256)
+    if not path.is_file():
+        result.reason = "not-cached"
+        return result
+    result.size = path.stat().st_size
+    result.actual = file_sha256(path)
+    if result.actual != artifact.sha256:
+        result.reason = "digest-mismatch"
+        return result
+    if artifact.size is not None and result.size != artifact.size:
+        result.reason = "size-mismatch"
+        return result
+    result.ok = True
+    result.reason = "ok"
+    return result
+
+
+class FileLock:
+    """Cross-process advisory lock built on ``O_CREAT | O_EXCL``.
+
+    Windows has no portable ``flock``; creating a lock file exclusively is atomic on NTFS
+    and behaves correctly across processes. Stale locks (crashed process) are reclaimed
+    after ``stale_after`` seconds.
+    """
+
+    def __init__(self, path: os.PathLike, *, timeout: float = 180.0, stale_after: float = 900.0):
+        self.path = Path(path)
+        self.timeout = timeout
+        self.stale_after = stale_after
+        self._fd: Optional[int] = None
+
+    def __enter__(self) -> "FileLock":
+        deadline = time.monotonic() + self.timeout
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        delay = 0.05
+        while True:
+            try:
+                self._fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                os.write(self._fd, f"{os.getpid()} {time.time():.3f}".encode())
+                return self
+            except FileExistsError:
+                try:
+                    age = time.time() - self.path.stat().st_mtime
+                except OSError:
+                    age = 0
+                if age > self.stale_after:
+                    log.warning("reclaiming stale download lock %s (age %.0fs)", self.path, age)
+                    try:
+                        self.path.unlink()
+                    except OSError:
+                        pass
+                    continue
+                if time.monotonic() > deadline:
+                    raise DownloadError(
+                        f"timed out waiting for the artifact lock {self.path}",
+                        code="download-lock-timeout",
+                        hint="Another process is downloading the driver. Remove the .lock file if it is stale.",
+                    )
+                time.sleep(delay)
+                delay = min(delay * 1.5, 0.5)
+            except OSError as exc:  # pragma: no cover - filesystem specific
+                raise DownloadError(f"cannot create lock {self.path}: {exc}") from exc
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            finally:
+                self._fd = None
+        try:
+            self.path.unlink()
+        except OSError:  # pragma: no cover
+            pass
+
+
+def _quarantine(path: Path, *, reason: str, dest_dir: Optional[Path] = None) -> Optional[Path]:
+    """Move a bad artifact out of the way so it can never be executed or reused.
+
+    Quarantining (rather than deleting) keeps the evidence for the operator, which matters
+    when the cause is a hostile mirror rather than a flaky connection.
+    """
+    try:
+        target_dir = dest_dir if dest_dir is not None else path.parent / "quarantine"
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / f"{path.name}.{int(time.time())}.{uuid.uuid4().hex[:8]}.bad"
+        os.replace(path, target)
+        log.error("quarantined %s (%s) as %s", path, reason, target)
+        return target
+    except OSError as exc:  # pragma: no cover - defensive
+        log.error("could not quarantine %s: %s", path, exc)
+        return None
+
+
+def _make_ssl_context() -> ssl.SSLContext:
+    context = ssl.create_default_context()
+    context.check_hostname = True
+    context.verify_mode = ssl.CERT_REQUIRED
+    return context
+
+
+def download_artifact(
+    artifact: Artifact,
+    *,
+    cache_dir: Optional[os.PathLike] = None,
+    timeout: float = 120.0,
+    progress: Optional[Callable[[int, Optional[int]], None]] = None,
+    force: bool = False,
+    max_retries: int = 3,
+    mirror_extra: Sequence[str] = (),
+) -> Path:
+    """Return a verified local copy of ``artifact``, downloading it when needed.
+
+    ``mirror_extra`` adds URL prefixes for this call only (the ``VIRTUALDESKTOP_GITHUB_MIRRORS``
+    environment variable is folded in by the callers).  The artifact's own ``mirrors`` from the
+    manifest are always tried first after the primary URL.
+    """
+    cache = Path(cache_dir) if cache_dir else default_cache_dir()
+    cache.mkdir(parents=True, exist_ok=True)
+    target = cache / artifact.filename
+
+    if not force:
+        existing = verified_path(artifact, cache)
+        if existing is not None:
+            log.debug("using cached artifact %s", existing)
+            return existing
+        if target.exists():
+            _quarantine(target, reason="digest mismatch", dest_dir=cache / "quarantine")
+
+    with FileLock(cache / f"{artifact.filename}.lock"):
+        # Another process may have completed the download while we waited.
+        if not force:
+            existing = verified_path(artifact, cache)
+            if existing is not None:
+                return existing
+
+        tmp_dir = cache / ".tmp"
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        tmp_path = tmp_dir / f"{artifact.filename}.{os.getpid()}.{uuid.uuid4().hex[:8]}.part"
+        limit = artifact.size or 512 * 1024 * 1024
+        if artifact.size:
+            # Allow a tiny slack for servers that re-encode, but stay tight.
+            limit = int(artifact.size * 1.01) + 1024
+
+        # Every candidate URL serves the *same bytes*; the digest below is what decides.  The
+        # mirrors exist because github.com is unreachable or unusably slow on many networks in
+        # mainland China, and they are tried in order after the primary URL fails.
+        urls = artifact.candidate_urls(mirror_extra)
+        last_error: Optional[Exception] = None
+        for url in urls:
+            for attempt in range(1, max_retries + 1):
+                try:
+                    _fetch(artifact, tmp_path, url=url, timeout=timeout, limit=limit, progress=progress)
+                    break
+                except (urllib.error.URLError, TimeoutError, OSError, DownloadError) as exc:
+                    last_error = exc
+                    log.warning(
+                        "download attempt %d/%d from %s failed: %s", attempt, max_retries, url, exc
+                    )
+                    if attempt == max_retries:
+                        break
+                    time.sleep(min(2 ** attempt, 8))
+            else:  # pragma: no cover - the inner loop always breaks or exhausts
+                continue
+            if tmp_path.exists() and tmp_path.stat().st_size:
+                break
+        else:
+            raise DownloadError(
+                f"failed to download {artifact.filename} from {len(urls)} URL(s): {last_error}",
+                code="download-failed",
+                details={"urls": urls, "filename": artifact.filename},
+            )
+
+        digest = file_sha256(tmp_path)
+        if digest != artifact.sha256:
+            size = tmp_path.stat().st_size
+            _quarantine(tmp_path, reason="sha256 mismatch", dest_dir=cache / "quarantine")
+            raise IntegrityError(
+                f"SHA-256 mismatch for {artifact.filename}: expected {artifact.sha256}, got {digest}",
+                code="digest-mismatch",
+                details={
+                    "url": artifact.url,
+                    "expected": artifact.sha256,
+                    "actual": digest,
+                    "bytes": size,
+                },
+                hint="The download was corrupted or the mirror serves different content; "
+                "update the manifest if the upstream release legitimately changed.",
+            )
+        if artifact.size is not None and tmp_path.stat().st_size != artifact.size:
+            actual_size = tmp_path.stat().st_size
+            _quarantine(tmp_path, reason="size mismatch", dest_dir=cache / "quarantine")
+            raise IntegrityError(
+                f"size mismatch for {artifact.filename}: expected {artifact.size}, got {actual_size}",
+                code="size-mismatch",
+            )
+        os.replace(tmp_path, target)
+        log.info(
+            "verified %s (%d bytes, sha256 %s)", target.name, target.stat().st_size, digest[:12]
+        )
+        return target
+
+
+def _fetch(
+    artifact: Artifact,
+    tmp_path: Path,
+    *,
+    url: Optional[str] = None,
+    timeout: float,
+    limit: int,
+    progress: Optional[Callable[[int, Optional[int]], None]],
+) -> None:
+    """Download ``url`` (default: the artifact's primary URL) into ``tmp_path``."""
+    source = url or artifact.url
+    request = urllib.request.Request(
+        source,
+        headers={"User-Agent": _USER_AGENT, "Accept": "application/octet-stream"},
+    )
+    handlers: List[urllib.request.BaseHandler] = [urllib.request.HTTPSHandler(context=_make_ssl_context())]
+    opener = urllib.request.build_opener(*handlers)
+    written = 0
+    with opener.open(request, timeout=timeout) as response:
+        final_url = response.geturl()
+        if not str(final_url).lower().startswith("https://"):
+            raise DownloadError(
+                f"refusing to download over an insecure channel: {final_url}",
+                code="insecure-redirect",
+            )
+        declared = response.headers.get("Content-Length")
+        total = int(declared) if declared and declared.isdigit() else artifact.size
+        if total and total > limit:
+            raise DownloadError(
+                f"remote file is {total} bytes which exceeds the accepted limit of {limit}",
+                code="size-exceeded",
+            )
+        with open(tmp_path, "wb") as handle:
+            while True:
+                chunk = response.read(_CHUNK)
+                if not chunk:
+                    break
+                written += len(chunk)
+                if written > limit:
+                    raise DownloadError(
+                        f"download exceeded the accepted limit of {limit} bytes",
+                        code="size-exceeded",
+                    )
+                handle.write(chunk)
+                if progress is not None:
+                    progress(written, total)
+            handle.flush()
+            os.fsync(handle.fileno())
+    if progress is not None:
+        progress(written, written)
+    log.debug("fetched %s -> %s (%d bytes)", source, tmp_path, written)
+
+
+def extract_archive(
+    archive_path: os.PathLike,
+    dest_dir: os.PathLike,
+    *,
+    strip_components: int = 0,
+    members: Sequence[str] = (),
+    overwrite: bool = True,
+) -> Path:
+    """Safely extract a zip archive and return the destination directory.
+
+    Raises :class:`ExtractionError` on any suspicious member instead of skipping it — a
+    silently skipped member would surface later as a confusing "INF not found".
+    """
+    archive_path = Path(archive_path)
+    dest = Path(dest_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+    try:
+        zf = zipfile.ZipFile(archive_path)
+    except zipfile.BadZipFile as exc:
+        raise ExtractionError(
+            f"{archive_path} is not a valid zip archive: {exc}", code="bad-archive"
+        ) from exc
+
+    with zf:
+        infos = zf.infolist()
+        if len(infos) > _MAX_MEMBERS:
+            raise ExtractionError(
+                f"archive contains {len(infos)} members (limit {_MAX_MEMBERS})",
+                code="archive-too-many-members",
+            )
+        total_uncompressed = sum(i.file_size for i in infos)
+        archive_size = max(archive_path.stat().st_size, 1)
+        if total_uncompressed > archive_size * _MAX_EXPANSION_RATIO:
+            raise ExtractionError(
+                f"archive expands to {total_uncompressed} bytes ({_MAX_EXPANSION_RATIO}x limit); refusing",
+                code="archive-bomb",
+            )
+        root = dest.resolve()
+        extracted: List[str] = []
+        for info in infos:
+            name = info.filename.replace("\\", "/")
+            if not name or name.endswith("/"):
+                continue
+            mode = (info.external_attr >> 16) & 0xFFFF
+            if mode and stat.S_ISLNK(mode):
+                raise ExtractionError(
+                    f"archive member {info.filename!r} is a symlink; refusing",
+                    code="archive-symlink",
+                )
+            parts = [p for p in name.split("/") if p not in ("", ".")]
+            if any(p == ".." for p in parts):
+                raise ExtractionError(
+                    f"archive member {info.filename!r} escapes the extraction root",
+                    code="archive-traversal",
+                )
+            if len(parts) <= strip_components:
+                continue
+            relative = Path(*parts[strip_components:])
+            target = (root / relative).resolve()
+            if root != target and root not in target.parents:
+                raise ExtractionError(
+                    f"archive member {info.filename!r} resolves outside {root}",
+                    code="archive-traversal",
+                )
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if target.exists() and not overwrite:
+                extracted.append(str(relative).replace("\\", "/"))
+                continue
+            with zf.open(info) as src, open(target, "wb") as dst:
+                shutil.copyfileobj(src, dst, _CHUNK)
+            extracted.append(str(relative).replace("\\", "/"))
+
+        missing = [m for m in members if m not in set(extracted)]
+        if missing:
+            raise ExtractionError(
+                f"archive {archive_path.name} is missing expected member(s): {', '.join(missing)}",
+                code="archive-missing-members",
+                details={"found": extracted[:50]},
+            )
+    log.debug("extracted %s -> %s (%d files)", archive_path.name, dest, len(extracted))
+    return dest

VirtualDesktop/_helper.py

@@ -0,0 +1,31 @@
+"""Absolute-path entry point for the elevated helper.
+
+Run as a *script* (``python <this file> _elevated-install ...``) rather than with ``-m``,
+because the elevated child's ``sys.path`` contains only its own working directory, which is
+not necessarily the project directory.
+
+Bootstrapping note: this file lives *inside* the package, so ``python script.py`` puts
+``<...>/VirtualDesktop`` on ``sys.path`` — enough to import ``errors``/``cli`` as siblings,
+but **not** enough for ``import VirtualDesktop.cli``, which needs the *parent* directory.
+Both are added below, so it works for a source checkout and for an installed wheel, with no
+reliance on the current working directory or on ``PYTHONPATH``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_PARENT_DIR = _PACKAGE_DIR.parent
+for _candidate in (str(_PARENT_DIR), str(_PACKAGE_DIR)):
+    if _candidate not in sys.path:
+        sys.path.insert(0, _candidate)
+
+try:
+    from VirtualDesktop.cli import main
+except ModuleNotFoundError:  # pragma: no cover - fallback for a renamed checkout
+    from cli import main  # type: ignore[no-redef]
+
+if __name__ == "__main__":
+    sys.exit(main())

VirtualDesktop/_log.py

@@ -0,0 +1,85 @@
+"""Logging helpers.
+
+The library never configures the root logger and never attaches handlers unless the
+application explicitly asks for it (``enable_debug_logging()`` or the
+``VIRTUALDESKTOP_LOG_FILE`` environment variable), so importing it stays side-effect free.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+from typing import Optional
+
+__all__ = ["get_logger", "enable_debug_logging", "configure_from_env", "LOG_NAMESPACE"]
+
+LOG_NAMESPACE = "VirtualDesktop"
+_CONFIGURED = False
+
+_FORMAT = "%(asctime)s %(levelname)-7s [%(name)s] %(message)s"
+
+
+def get_logger(name: str = "") -> logging.Logger:
+    """Return a namespaced logger (``VirtualDesktop.<name>``)."""
+    if not name:
+        return logging.getLogger(LOG_NAMESPACE)
+    if name.startswith(LOG_NAMESPACE):
+        return logging.getLogger(name)
+    return logging.getLogger(f"{LOG_NAMESPACE}.{name}")
+
+
+def _ensure_namespace_handler(handler: logging.Handler) -> logging.Logger:
+    logger = logging.getLogger(LOG_NAMESPACE)
+    logger.addHandler(handler)
+    # Do not duplicate records through the root logger; libraries must not own root.
+    logger.propagate = False
+    return logger
+
+
+def enable_debug_logging(
+    *,
+    level: int = logging.DEBUG,
+    stream=None,
+    log_file: Optional[str] = None,
+    max_bytes: int = 1_000_000,
+    backup_count: int = 2,
+) -> logging.Logger:
+    """Turn on library logging once; safe to call repeatedly."""
+    global _CONFIGURED
+    logger = logging.getLogger(LOG_NAMESPACE)
+    logger.setLevel(level)
+    if not _CONFIGURED:
+        formatter = logging.Formatter(_FORMAT)
+        if stream is None and not log_file:
+            stream = sys.stderr
+        if stream is not None:
+            handler = logging.StreamHandler(stream)
+            handler.setFormatter(formatter)
+            _ensure_namespace_handler(handler)
+        if log_file:
+            try:
+                directory = os.path.dirname(os.path.abspath(log_file))
+                if directory:
+                    os.makedirs(directory, exist_ok=True)
+                file_handler = RotatingFileHandler(
+                    log_file, maxBytes=max_bytes, backupCount=backup_count, encoding="utf-8"
+                )
+            except OSError:  # pragma: no cover - depends on filesystem state
+                file_handler = None
+            if file_handler is not None:
+                file_handler.setFormatter(formatter)
+                _ensure_namespace_handler(file_handler)
+        _CONFIGURED = True
+    return logger
+
+
+def configure_from_env() -> None:
+    """Honour ``VIRTUALDESKTOP_DEBUG`` / ``VIRTUALDESKTOP_LOG_FILE`` if set."""
+    debug = os.environ.get("VIRTUALDESKTOP_DEBUG", "").strip().lower()
+    log_file = os.environ.get("VIRTUALDESKTOP_LOG_FILE") or None
+    if debug in ("1", "true", "yes", "on"):
+        enable_debug_logging(level=logging.DEBUG, log_file=log_file)
+    elif log_file:
+        enable_debug_logging(level=logging.INFO, stream=None, log_file=log_file)