browserget 1.0.1__py3-none-any.whl

browserget/__init__.py

@@ -0,0 +1,46 @@
+"""browserget — Standalone CLI to install browsers and drivers without any framework."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from browserget.config import Config, load_config
+from browserget.exceptions import (
+    AlreadyInstalledError,
+    BrowsergetError,
+    ChecksumMismatchError,
+    DriverMatchError,
+    InsufficientDiskSpaceError,
+    NetworkError,
+    UnknownTargetError,
+    UnsupportedPlatformError,
+    VersionNotFoundError,
+)
+from browserget.models import InstalledArtifact, ResolvedVersion, SystemBrowser
+from browserget.platform import OS, Arch, Platform, detect_platform
+
+try:
+    __version__ = _pkg_version("browserget")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AlreadyInstalledError",
+    "Arch",
+    "BrowsergetError",
+    "ChecksumMismatchError",
+    "Config",
+    "DriverMatchError",
+    "InsufficientDiskSpaceError",
+    "InstalledArtifact",
+    "NetworkError",
+    "OS",
+    "Platform",
+    "ResolvedVersion",
+    "SystemBrowser",
+    "UnknownTargetError",
+    "UnsupportedPlatformError",
+    "VersionNotFoundError",
+    "__version__",
+    "detect_platform",
+    "load_config",
+]

browserget/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running browserget as a module."""
+
+from browserget.cli import main
+
+if __name__ == "__main__":
+    main()

browserget/archive.py

@@ -0,0 +1,114 @@
+"""Safe archive extraction utilities with path-traversal protection.
+
+All extraction functions validate that every entry in the archive resolves
+to a path inside the destination directory, preventing Zip Slip and similar
+path-traversal attacks.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+
+
+def _safe_extract_path(dest: Path, member_name: str) -> Path:
+    """Resolve *member_name* relative to *dest* and verify it stays inside.
+
+    Args:
+        dest: The destination directory.
+        member_name: The archive member's relative path.
+
+    Returns:
+        The resolved, validated path.
+
+    Raises:
+        ValueError: If the resolved path escapes *dest*.
+    """
+    dest_resolved = dest.resolve()
+    target = (dest / member_name).resolve()
+    try:
+        target.relative_to(dest_resolved)
+    except ValueError as exc:
+        raise ValueError(f"Archive entry '{member_name}' escapes destination directory") from exc
+    return target
+
+
+def extract_zip(archive_path: Path, dest: Path) -> None:
+    """Extract a zip archive safely, preventing path traversal.
+
+    Validates both member paths and symlink targets to prevent
+    path-traversal attacks via malicious symlinks.
+
+    Args:
+        archive_path: Path to the zip file.
+        dest: Destination directory (must exist).
+
+    Raises:
+        ValueError: If any entry escapes the destination directory.
+        zipfile.BadZipFile: If the archive is corrupt or not a zip file.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive_path, "r") as zf:
+        for member in zf.infolist():
+            _safe_extract_path(dest, member.filename)
+            unix_mode = member.external_attr >> 16
+            if stat.S_ISLNK(unix_mode):
+                link_target = zf.read(member).decode("utf-8", errors="replace")
+                _safe_extract_path(dest, link_target)
+        zf.extractall(dest)
+
+
+def extract_tar(archive_path: Path, dest: Path) -> None:
+    """Extract a tar archive safely, preventing path traversal.
+
+    Automatically detects compression (gzip, bzip2, xz, or uncompressed).
+    Validates both member paths and symlink/hardlink targets to prevent
+    path-traversal attacks via malicious symlinks.
+
+    Args:
+        archive_path: Path to the tar file.
+        dest: Destination directory (must exist).
+
+    Raises:
+        ValueError: If any entry escapes the destination directory.
+        tarfile.TarError: If the archive is corrupt.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(str(archive_path), "r:*") as tf:
+        for member in tf.getmembers():
+            _safe_extract_path(dest, member.name)
+            if member.issym() or member.islnk():
+                _safe_extract_path(dest, member.linkname)
+        if sys.version_info >= (3, 12):
+            tf.extractall(dest, filter="data")
+        else:
+            for member in tf.getmembers():
+                if not (member.isfile() or member.isdir() or member.issym() or member.islnk()):
+                    raise ValueError(f"Refusing to extract special file: {member.name!r}")
+            tf.extractall(dest)
+
+
+def find_file_by_name(root: Path, filename: str) -> Path | None:
+    """Find a file by name in a directory tree without following symlinks.
+
+    Uses ``os.walk(followlinks=False)`` to avoid infinite recursion from
+    circular symlinks that may exist in extracted archives.
+
+    Args:
+        root: The root directory to search.
+        filename: The filename to match (basename only).
+
+    Returns:
+        The first matching file path, or ``None`` if not found.
+    """
+    for dirpath, _dirnames, filenames in os.walk(root, followlinks=False):
+        for fname in filenames:
+            if fname == filename:
+                candidate = Path(dirpath) / fname
+                if not candidate.is_symlink() and candidate.is_file():
+                    return candidate
+    return None

browserget/cache.py

@@ -0,0 +1,187 @@
+"""Cache directory management for browserget."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+from pathlib import Path
+
+from browserget.config import load_config
+
+
+def get_cache_dir() -> Path:
+    """Return the cache directory, creating it if it does not exist.
+
+    Returns:
+        The path to the cache directory.
+
+    Raises:
+        OSError: If the directory cannot be created (e.g. read-only filesystem).
+    """
+    cache_dir = load_config().cache_dir
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def _validate_path_component(component: str) -> str:
+    """Validate that a string is safe to use as a single path component.
+
+    Rejects empty strings, strings containing path separators (``/`` or ``\\``),
+    and the ``..`` traversal sequence.  This prevents path-traversal attacks
+    when version strings or names from upstream APIs are used to construct
+    filesystem paths.
+
+    Args:
+        component: The string to validate.
+
+    Returns:
+        The validated string.
+
+    Raises:
+        ValueError: If the component contains path separators or ``..``.
+    """
+    if not component or component == ".." or component == ".":
+        raise ValueError(f"Unsafe path component: {component!r}")
+    if "\x00" in component:
+        raise ValueError(f"Path component contains null byte: {component!r}")
+    if "/" in component or "\\" in component:
+        raise ValueError(f"Path component contains separator: {component!r}")
+    # Reject any component that resolves to a parent path
+    if Path(component).parts != (component,):
+        raise ValueError(f"Path component is not a single segment: {component!r}")
+    return component
+
+
+def get_artifact_dir(name: str, version: str) -> Path:
+    """Return the directory path for a specific artifact version.
+
+    Args:
+        name: Artifact name (e.g. "chrome", "chromedriver").
+        version: Artifact version string.
+
+    Returns:
+        The path ``{cache_dir}/{name}/{version}/``.
+
+    Raises:
+        ValueError: If *name* or *version* contains path separators or
+            traversal sequences (``..``).
+    """
+    _validate_path_component(name)
+    _validate_path_component(version)
+    return get_cache_dir() / name / version
+
+
+def get_download_dir() -> Path:
+    """Return the temporary download directory inside the cache.
+
+    Returns:
+        The path ``{cache_dir}/downloads/``.
+    """
+    return get_cache_dir() / "downloads"
+
+
+def safe_download_path(download_dir: Path, filename: str) -> Path:
+    """Construct a safe download path, rejecting path traversal in *filename*.
+
+    Args:
+        download_dir: The base download directory.
+        filename: The filename to append (typically extracted from a URL).
+
+    Returns:
+        The resolved path inside *download_dir*.
+
+    Raises:
+        ValueError: If *filename* contains path separators or ``..``
+            sequences that would escape *download_dir*.
+    """
+    _validate_path_component(filename)
+    return download_dir / filename
+
+
+def cleanup_downloads() -> None:
+    """Delete all contents of the download directory.
+
+    Individual deletion errors are suppressed so that one locked file
+    does not prevent cleanup of the remaining items.
+    """
+    download_dir = get_download_dir()
+    if download_dir.is_symlink():
+        download_dir.unlink()
+        return
+    if not download_dir.exists():
+        return
+    for item in download_dir.iterdir():
+        try:
+            if item.is_symlink():
+                item.unlink()
+            elif item.is_dir():
+                safe_rmtree(item)
+            else:
+                item.unlink()
+        except OSError:
+            pass
+
+
+def safe_rmtree(path: Path) -> None:
+    """Remove a directory tree, handling symlinks safely.
+
+    If *path* is a symlink, the symlink itself is unlinked rather than
+    recursing into its target. This prevents accidental deletion of
+    files outside the cache when ``path`` points elsewhere via a symlink.
+
+    Args:
+        path: Directory path to remove.
+    """
+    if path.is_symlink():
+        path.unlink()
+        return
+    shutil.rmtree(path)
+
+
+def check_disk_space(required_mb: int) -> bool:
+    """Check if there is enough disk space for an installation.
+
+    Args:
+        required_mb: Required space in megabytes.
+
+    Returns:
+        True if available space is sufficient, False otherwise.
+    """
+    cache_dir = get_cache_dir()
+    check_dir = cache_dir if cache_dir.exists() else Path.home()
+    usage = shutil.disk_usage(check_dir)
+    return usage.free >= required_mb * 1024 * 1024
+
+
+def get_available_disk_mb() -> int:
+    """Return available disk space in megabytes.
+
+    Returns:
+        Available space in MB at the cache directory location.
+    """
+    cache_dir = get_cache_dir()
+    check_dir = cache_dir if cache_dir.exists() else Path.home()
+    usage = shutil.disk_usage(check_dir)
+    return usage.free // (1024 * 1024)
+
+
+def get_cache_size() -> int:
+    """Return the total size of the cache directory in bytes.
+
+    Returns:
+        Total bytes in the cache directory (recursive), or 0 if the
+        directory does not exist.
+    """
+    cache_dir = load_config().cache_dir
+    if not cache_dir.exists():
+        return 0
+    total = 0
+    for dirpath, _dirnames, filenames in os.walk(cache_dir, followlinks=False):
+        for filename in filenames:
+            filepath = Path(dirpath) / filename
+            if filepath.is_symlink():
+                continue
+            with contextlib.suppress(OSError):
+                total += filepath.stat().st_size
+    return total

browserget/checksum.py

@@ -0,0 +1,76 @@
+"""Checksum computation and verification using hashlib."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from pathlib import Path
+
+from browserget.exceptions import ChecksumMismatchError
+
+_CHUNK_SIZE = 8192
+
+
+def compute_checksum(filepath: Path, algorithm: str) -> str:
+    """Compute the hex digest of a file using the specified algorithm.
+
+    Reads the file in 8192-byte chunks to handle files larger than memory.
+
+    Args:
+        filepath: Path to the file to hash.
+        algorithm: Hash algorithm name (e.g. "sha256", "sha512").
+
+    Returns:
+        The hexadecimal digest string.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the algorithm is not supported by hashlib.
+    """
+    try:
+        hasher = hashlib.new(algorithm)
+    except ValueError as exc:
+        raise ValueError(f"Unsupported algorithm: {algorithm}") from exc
+
+    with open(filepath, "rb") as f:
+        while True:
+            chunk = f.read(_CHUNK_SIZE)
+            if not chunk:
+                break
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def verify_checksum(filepath: Path, expected: str, algorithm: str) -> bool:
+    """Verify that a file's checksum matches the expected value.
+
+    Args:
+        filepath: Path to the file to verify.
+        expected: Expected hexadecimal digest.
+        algorithm: Hash algorithm name (e.g. "sha256", "sha512").
+
+    Returns:
+        True if the computed checksum matches the expected value.
+    """
+    actual = compute_checksum(filepath, algorithm)
+    return hmac.compare_digest(actual, expected)
+
+
+def verify_or_raise(filepath: Path, expected: str, algorithm: str) -> None:
+    """Verify a file's checksum, raising on mismatch.
+
+    Args:
+        filepath: Path to the file to verify.
+        expected: Expected hexadecimal digest.
+        algorithm: Hash algorithm name (e.g. "sha256", "sha512").
+
+    Raises:
+        ChecksumMismatchError: If the computed checksum does not match.
+    """
+    actual = compute_checksum(filepath, algorithm)
+    if not hmac.compare_digest(actual, expected):
+        raise ChecksumMismatchError(
+            filename=filepath.name,
+            expected=expected,
+            actual=actual,
+        )