gu-7f3a2c 0.4.2__py3-none-any.whl

game_updater/__init__.py

@@ -0,0 +1,53 @@
+"""Signed, hash-verified updater for a self-hosted game or app."""
+
+from .download import DownloadError
+from .hello import (
+    HELLO_SIZE,
+    HELLO_SHA256,
+    HELLO_URL,
+    HelloError,
+    download_hello,
+    run_hello,
+)
+from .install import UpdateError, UpdateResult, update
+from .manifest import Manifest, ManifestError
+from .vmcheck import (
+    DMIData,
+    VMBlockedError,
+    VMDetection,
+    VMPolicy,
+    VMStatus,
+    VMVendor,
+    classify,
+    collect_dmi,
+    detect_vm,
+    ensure_vm_allowed,
+)
+
+__version__ = "0.4.2"
+
+__all__ = [
+    "__version__",
+    "DMIData",
+    "DownloadError",
+    "HELLO_SIZE",
+    "HELLO_SHA256",
+    "HELLO_URL",
+    "HelloError",
+    "Manifest",
+    "ManifestError",
+    "UpdateError",
+    "UpdateResult",
+    "VMBlockedError",
+    "VMDetection",
+    "VMPolicy",
+    "VMStatus",
+    "VMVendor",
+    "classify",
+    "collect_dmi",
+    "detect_vm",
+    "download_hello",
+    "ensure_vm_allowed",
+    "run_hello",
+    "update",
+]

game_updater/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m game_updater``."""
+
+from .cli import main
+
+raise SystemExit(main())

game_updater/cli.py

@@ -0,0 +1,175 @@
+"""Command line interface for game-updater."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .download import DownloadError
+from .hello import HelloError, run_hello
+from .install import UpdateError, read_local_version, update
+from .manifest import ManifestError
+from .vmcheck import VMBlockedError, VMPolicy, ensure_vm_allowed
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="game-updater",
+        description="Signed, hash-verified updater for a self-hosted game or app.",
+    )
+    parser.add_argument(
+        "--manifest",
+        required=False,
+        help="HTTPS URL of the signed manifest JSON (required unless --hello is used)",
+    )
+    parser.add_argument(
+        "--dir",
+        required=False,
+        help=(
+            "game directory to update (optional for --hello; defaults to the "
+            "system temp folder)"
+        ),
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--check",
+        action="store_true",
+        help="only report local and remote versions (default)",
+    )
+    mode.add_argument(
+        "--apply",
+        action="store_true",
+        help="download, verify, and install the update",
+    )
+    mode.add_argument(
+        "--hello",
+        action="store_true",
+        help=(
+            "download and run the pinned hello.bat demo (defaults to the "
+            "system temp folder; Windows)"
+        ),
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="do not prompt before applying",
+    )
+    parser.add_argument(
+        "--run",
+        action="store_true",
+        help="after a successful apply, run the manifest's signed run entry",
+    )
+    parser.add_argument(
+        "--public-key",
+        default=None,
+        help="path to the base64 Ed25519 public key (defaults to the bundled key)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="network timeout in seconds (default: 30)",
+    )
+    parser.add_argument(
+        "--allow-insecure",
+        action="store_true",
+        help="allow http://localhost and file:// URLs (testing only)",
+    )
+    parser.add_argument(
+        "--vm-policy",
+        choices=[policy.value for policy in VMPolicy],
+        default=VMPolicy.OFF.value,
+        help=(
+            "VM policy: 'off' skips detection (default); 'allow' detects "
+            "but never blocks; 'block' refuses all update work when a VM "
+            "is detected"
+        ),
+    )
+    return parser
+
+
+def _confirm(manifest) -> bool:  # noqa: ANN001 - small CLI helper
+    print()
+    print(f"Update available: {manifest.version}")
+    if manifest.notes:
+        print(f"Notes: {manifest.notes}")
+    print("Files:")
+    for entry in manifest.files:
+        print(f"  {entry.path}  ({entry.size} bytes)")
+    if manifest.run:
+        print(f"After install, will run: {manifest.run}")
+    answer = input("Apply this update? [y/N] ").strip().lower()
+    return answer in ("y", "yes")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.hello:
+        try:
+            path = run_hello(args.dir, timeout=args.timeout)
+        except (HelloError, OSError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        print(f"downloaded: {path}")
+        print("ran: hello.bat")
+        return 0
+
+    if not args.dir:
+        parser.error("--dir is required unless --hello is used")
+    if not args.manifest:
+        parser.error("--manifest is required unless --hello is used")
+
+    try:
+        detection = ensure_vm_allowed(args.vm_policy)
+    except VMBlockedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+
+    if detection is not None:
+        print(f"vm check: {detection.summary()}")
+
+    game_dir = Path(args.dir)
+    previous = read_local_version(game_dir)
+
+    try:
+        result = update(
+            manifest_url=args.manifest,
+            game_dir=game_dir,
+            apply=args.apply,
+            run_patch=args.run,
+            public_key_path=args.public_key,
+            timeout=args.timeout,
+            allow_insecure=args.allow_insecure,
+            confirm=None if args.yes or not args.apply else _confirm,
+            vm_policy=args.vm_policy,
+            vm_detection=detection,
+        )
+    except VMBlockedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    except (UpdateError, ManifestError, DownloadError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"local version:  {result.previous_version or '(none)'}")
+    print(f"remote version: {result.version}")
+    print(f"files:          {len(result.files)}")
+
+    if not result.applied:
+        if result.previous_version == result.version:
+            print("already up to date")
+        else:
+            print("not applied (run with --apply to install)")
+        return 0
+
+    print(f"applied:        {result.previous_version or '(none)'} -> {result.version}")
+    if result.ran:
+        print(f"ran:            {result.ran}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

game_updater/download.py

@@ -0,0 +1,142 @@
+"""HTTP download with size and SHA-256 verification."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+_USER_AGENT = "gu-7f3a2c/0.4.2"
+
+
+class DownloadError(Exception):
+    """Raised when a download fails or does not match the manifest."""
+
+
+def check_url(url: str, *, allow_insecure: bool = False) -> None:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme == "https":
+        return
+    if allow_insecure and parsed.scheme in ("http", "file"):
+        if parsed.scheme == "http":
+            host = (parsed.hostname or "").lower()
+            if host not in ("localhost", "127.0.0.1", "::1"):
+                raise DownloadError(f"insecure HTTP is only allowed for localhost: {url}")
+        return
+    raise DownloadError(f"refusing non-HTTPS URL: {url}")
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def __init__(self, *, allow_insecure: bool = False) -> None:
+        super().__init__()
+        self.allow_insecure = allow_insecure
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: ANN001
+        check_url(newurl, allow_insecure=self.allow_insecure)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _open_url(
+    url: str,
+    *,
+    timeout: float,
+    allow_insecure: bool,
+):
+    check_url(url, allow_insecure=allow_insecure)
+    opener = urllib.request.build_opener(
+        _SafeRedirectHandler(allow_insecure=allow_insecure)
+    )
+    request = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    return opener.open(request, timeout=timeout)
+
+
+def download_verified(
+    url: str,
+    destination: Path,
+    *,
+    expected_sha256: str,
+    expected_size: int,
+    timeout: float = 30.0,
+    allow_insecure: bool = False,
+    chunk_size: int = 1024 * 1024,
+) -> None:
+    """Download ``url`` to ``destination`` and verify size + hash.
+
+    The file is written to a temporary path in the destination directory and
+    moved into place only after verification, so a partial download never
+    appears as a finished file.
+    """
+    check_url(url, allow_insecure=allow_insecure)
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    hasher = hashlib.sha256()
+    written = 0
+
+    fd, temp_name = tempfile.mkstemp(
+        prefix=destination.name + ".",
+        suffix=".part",
+        dir=str(destination.parent),
+    )
+    temp_path = Path(temp_name)
+
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            with _open_url(
+                url,
+                timeout=timeout,
+                allow_insecure=allow_insecure,
+            ) as response:
+                while True:
+                    chunk = response.read(chunk_size)
+                    if not chunk:
+                        break
+                    written += len(chunk)
+                    if written > expected_size:
+                        raise DownloadError(
+                            f"{url}: response larger than expected ({written} > {expected_size})"
+                        )
+                    hasher.update(chunk)
+                    handle.write(chunk)
+
+        if written != expected_size:
+            raise DownloadError(
+                f"{url}: size mismatch ({written} != {expected_size})"
+            )
+
+        actual = hasher.hexdigest()
+        if actual != expected_sha256.lower():
+            raise DownloadError(
+                f"{url}: sha256 mismatch ({actual} != {expected_sha256.lower()})"
+            )
+
+        os.replace(temp_path, destination)
+    except Exception:
+        try:
+            temp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+
+def fetch_bytes(
+    url: str,
+    *,
+    timeout: float = 30.0,
+    allow_insecure: bool = False,
+    max_bytes: int = 4 * 1024 * 1024,
+) -> bytes:
+    """Fetch a small resource (the manifest) with a hard size ceiling."""
+    with _open_url(
+        url,
+        timeout=timeout,
+        allow_insecure=allow_insecure,
+    ) as response:
+        data = response.read(max_bytes + 1)
+
+    if len(data) > max_bytes:
+        raise DownloadError(f"{url}: manifest exceeds {max_bytes} bytes")
+
+    return data

game_updater/hello.py

@@ -0,0 +1,120 @@
+"""Pinned, opt-in download of the hello.bat demo.
+
+This module is intentionally separate from the signed-manifest update path. The
+URL, size, and SHA-256 are pinned here, the file is re-hashed immediately before
+execution, and nothing runs unless the caller asks for it.
+
+The demo is Windows-only because it is a ``.bat`` file. It writes ``hello.txt``
+next to itself and opens Notepad.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from .download import DownloadError, download_verified
+
+HELLO_URL = "https://hello-phi-amber.vercel.app/hello.bat"
+HELLO_SHA256 = "41e425416ddb186861598dffc847c2b7d585a9af7e94e130e2354362b61259da"
+HELLO_SIZE = 120
+
+
+def _default_work_dir() -> Path:
+    """Return the temp folder used when no work dir is given."""
+    return Path(tempfile.gettempdir()) / "game-updater-hello"
+
+
+class HelloError(RuntimeError):
+    """Raised when the pinned hello.bat demo cannot be downloaded or run."""
+
+
+def download_hello(
+    work_dir: str | os.PathLike[str] | None = None,
+    *,
+    timeout: float = 30.0,
+    url: str = HELLO_URL,
+    sha256: str = HELLO_SHA256,
+    size: int = HELLO_SIZE,
+    allow_insecure: bool = False,
+) -> Path:
+    """Download hello.bat into ``work_dir`` and verify its pinned hash.
+
+    If ``work_dir`` is None, the file is saved to
+    ``%TEMP%\\game-updater-hello\\hello.bat`` (the system temp folder).
+
+    Returns the path to the verified file. Raises :class:`HelloError` on a
+    download, size, or hash failure.
+    """
+
+    if work_dir is None:
+        work_dir = _default_work_dir()
+    destination = (Path(work_dir) / "hello.bat").resolve()
+    try:
+        download_verified(
+            url,
+            destination,
+            expected_sha256=sha256,
+            expected_size=size,
+            timeout=timeout,
+            allow_insecure=allow_insecure,
+        )
+    except DownloadError as exc:
+        raise HelloError(f"hello.bat download failed: {exc}") from exc
+
+    actual = hashlib.sha256(destination.read_bytes()).hexdigest()
+    if actual != sha256.lower():
+        raise HelloError(
+            f"hello.bat hash changed after download: {actual} != {sha256.lower()}"
+        )
+    return destination
+
+
+def run_hello(
+    work_dir: str | os.PathLike[str] | None = None,
+    *,
+    timeout: float = 30.0,
+) -> Path:
+    """Download, verify, and run the pinned hello.bat demo.
+
+    With no ``work_dir``, the batch is downloaded to
+    ``%TEMP%\\game-updater-hello\\hello.bat`` and run from there. The batch file
+    is re-hashed immediately before execution. A nonzero exit code raises
+    :class:`HelloError`.
+    """
+
+    if sys.platform != "win32":
+        raise HelloError("the pinned hello.bat demo requires Windows")
+
+    # Resolve before changing cwd so relative work_dir values still work.
+    path = download_hello(work_dir, timeout=timeout).resolve()
+
+    actual = hashlib.sha256(path.read_bytes()).hexdigest()
+    if actual != HELLO_SHA256:
+        raise HelloError(
+            f"hello.bat changed before execution: {actual} != {HELLO_SHA256}"
+        )
+
+    command = ["cmd.exe", "/d", "/c", str(path)]
+    try:
+        completed = subprocess.run(command, cwd=str(path.parent), check=False)
+    except OSError as exc:
+        raise HelloError(f"cannot run hello.bat: {exc}") from exc
+
+    if completed.returncode != 0:
+        raise HelloError(f"hello.bat exited with code {completed.returncode}")
+    return path
+
+
+__all__ = [
+    "HELLO_SIZE",
+    "HELLO_SHA256",
+    "HELLO_URL",
+    "HelloError",
+    "download_hello",
+    "run_hello",
+]