game-updater 0.3.0__tar.gz

game_updater-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 game-updater contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

game_updater-0.3.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+# The signing and key-generation tools are useful to source users.
+graft tools
+
+# Keep test-only payloads out of the published source archive.
+prune tests
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.pyo
+global-exclude *.pem
+global-exclude *.key
+global-exclude *.p12
+global-exclude *.pfx

game_updater-0.3.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: game-updater
+Version: 0.3.0
+Summary: Signed, hash-verified updater for a self-hosted game or app.
+Author: game-updater contributors
+License-Expression: MIT
+Keywords: game,updater,ed25519,sha256
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Dynamic: license-file
+
+# Game Updater
+
+A small, auditable updater for a game or app that you host yourself.
+
+It does **not** run anything at install time. It runs only when you call the
+CLI or the `update()` function, and it refuses to install anything that is not
+covered by a valid Ed25519 signature and a matching SHA-256 hash.
+
+## What it does
+
+1. Checks the VM compatibility policy when enabled (default: `off`). With
+   `vm_policy="block"`, a detected VM stops the call before anything is
+   downloaded, installed, or run.
+2. Downloads `manifest.json` over HTTPS.
+3. Verifies the manifest signature against the public key embedded in this
+   package.
+4. Compares the remote version with the local `version.json`.
+5. Downloads each listed file to a staging folder.
+6. Verifies size and SHA-256 for every file.
+7. Moves the verified files into the game directory.
+8. Writes `version.json` with the version, sequence, notes, and file list.
+9. Optionally runs a patch executable — only if it is listed in the signed
+   manifest, hash-verified, and `--run` was passed.
+
+## What it does not do
+
+- No `setup.py` / PEP 517 hooks that execute anything.
+- No `.pth` files, no `sitecustomize.py`, no persistence.
+- No obfuscation. The source is readable.
+- No unsigned downloads. Every byte is checked against the signed manifest.
+- No silent execution. `--run` is explicit.
+- No stealth VM detection. The policy is explicit, documented, and printed by
+  the CLI.
+- No anti-debug, timing checks, process scanning, or security-tool
+  interference.
+- No network requests for VM detection. It only reads local OS metadata.
+
+## VM compatibility policy
+
+The check is a configurable compatibility policy, not a stealth feature. It
+runs at the start of `update()` and before the CLI reads local state.
+
+| Policy | Behavior |
+|---|---|
+| `off` (default) | Skip VM detection entirely. |
+| `allow` | Detect and report, but never block. Ordinary physical PCs and VM users both work. |
+| `block` | If a VM is detected, raise `VMBlockedError` before creating the game directory, fetching the manifest, installing files, or running a patch. |
+
+When detection runs, the CLI prints the result before doing any work. A
+`block` refusal prints the documented error instead; `off` prints nothing.
+
+```text
+vm check: physical machine (no known VM indicators found)
+```
+
+If a VM is detected and the policy is `block`:
+
+```text
+error: VM use is disabled by policy (vm_policy='block'), but this machine
+appears to be a vmware virtual machine (confidence: high). Indicators:
+DMI system manufacturer is VMware; DMI system product is VMware. No update
+was downloaded, installed, or run. If this is a physical machine, this is a
+false positive; use vm_policy='allow' or vm_policy='off' to proceed. VM
+detection is best-effort and can be wrong.
+```
+
+CLI exit code is `3` for a VM policy block, `2` for an update/manifest error,
+and `0` on success.
+
+### Indicators used
+
+Detection is conservative and uses only documented, read-only DMI/SMBIOS
+values exposed by the OS:
+
+| Environment | Definitive indicators | Supporting only |
+|---|---|---|
+| Hyper-V | DMI system product `Virtual Machine`; DMI system version `Hyper-V` | Hyper-V guest integration registry key |
+| QEMU / KVM | DMI system/board manufacturer `QEMU`; DMI product `Standard PC (Q35 ...)` or `Standard PC (i440FX ...)` | BIOS vendor `SeaBIOS` |
+| VMware | DMI manufacturer, product, version, board, or BIOS containing `VMware` | — |
+| VirtualBox | DMI manufacturer/board/BIOS `innotek`; product/version `VirtualBox` | — |
+
+Unsupported platforms (including macOS) return `UNKNOWN`; they are not
+guessed at and are allowed under `block`.
+
+Rules:
+
+- A VM result requires at least one **definitive** vendor-specific string.
+- Supporting-only evidence (for example, SeaBIOS alone, or the Hyper-V guest
+  key alone) returns `UNKNOWN`, not `VM`.
+- Two different definitive vendors return `UNKNOWN` with
+  `conflicting=True`.
+- A missing or unreadable DMI source returns `UNKNOWN`.
+- `block` refuses only on `VM`. `PHYSICAL` and `UNKNOWN` are allowed, which
+  keeps ordinary PCs working and avoids blocking on ambiguous evidence.
+
+### What is intentionally not used
+
+- The CPUID hypervisor-present bit. Physical Windows machines with Hyper-V,
+  VBS, or Memory Integrity enabled can set it, causing false positives.
+- Timing measurements, process scanning, debugger checks, or anti-analysis
+  tricks.
+- Network requests or external services.
+- Any attempt to disable or interfere with security tools.
+
+### Limitations
+
+VM detection is imperfect. DMI strings can be spoofed, hidden, or changed by
+the hypervisor, and some physical firmware exposes unusual values. A
+`PHYSICAL` result means "no known VM indicator was found", not proof. A `VM`
+result can be a false positive; `vm_policy="allow"` or `vm_policy="off"` is
+the documented escape hatch.
+
+This check is **not** a security boundary and does **not** make the library
+impossible to crack or bypass. The real protections are the signed manifest,
+SHA-256 verification, HTTPS, and keeping the private signing key offline. Do
+not use VM detection as a substitute for those controls.
+
+## Install
+
+```powershell
+pip install game-updater
+```
+
+From a local checkout:
+
+```powershell
+pip install .
+```
+
+This package is for publishers who control both the manifest host and the
+signing key. Only point it at manifests you signed.
+
+## Generate a signing key
+
+```powershell
+python tools/keygen.py --private game_private.pem
+```
+
+Put the printed public key into `src/game_updater/public_key.txt`.
+
+Keep `game_private.pem` offline. Never commit it.
+
+## Build and sign a manifest
+
+Create `manifest.json` without a signature:
+
+```json
+{
+  "version": "1.4.0",
+  "sequence": 3,
+  "notes": "Season 3 patch",
+  "files": [
+    {
+      "path": "game/data.pak",
+      "url": "https://cdn.example.com/game/data-1.4.0.pak",
+      "sha256": "…",
+      "size": 12345678
+    },
+    {
+      "path": "game/patch.exe",
+      "url": "https://cdn.example.com/game/patch-1.4.0.exe",
+      "sha256": "…",
+      "size": 456789,
+      "executable": true
+    }
+  ],
+  "run": "game/patch.exe"
+}
+```
+
+`sequence` is a signed, non-negative integer. Increase it for every release.
+The updater stores it in `version.json` and refuses a manifest whose sequence
+is lower than the installed one, or equal while claiming a different version.
+That prevents replay of an older signed manifest.
+
+Sign it:
+
+```powershell
+python tools/sign_manifest.py --key game_private.pem --manifest manifest.json --out manifest.signed.json
+```
+
+Upload `manifest.signed.json` (and the files) to your HTTPS host.
+
+## Update a game folder
+
+```powershell
+game-updater --manifest https://cdn.example.com/game/manifest.signed.json --dir "C:\Games\MyGame"
+```
+
+Other modes:
+
+```powershell
+game-updater --manifest ... --dir ... --check    # show versions only
+game-updater --manifest ... --dir ... --apply    # install (asks first)
+game-updater --manifest ... --dir ... --apply --yes
+game-updater --manifest ... --dir ... --apply --run
+game-updater --manifest ... --dir ... --apply --vm-policy block
+```
+
+`--vm-policy` accepts `off` (default), `allow`, or `block`.
+
+## Python API
+
+```python
+from game_updater import update
+
+result = update(
+    manifest_url="https://cdn.example.com/game/manifest.signed.json",
+    game_dir=r"C:\Games\MyGame",
+    apply=True,
+    run_patch=False,
+)
+print(result)
+print(result.vm.summary() if result.vm else "vm check skipped")
+```
+
+To refuse updates on a detected VM:
+
+```python
+from game_updater import VMBlockedError, update
+
+try:
+    result = update(
+        manifest_url="https://cdn.example.com/game/manifest.signed.json",
+        game_dir=r"C:\Games\MyGame",
+        apply=True,
+        vm_policy="block",
+    )
+except VMBlockedError as error:
+    print(error)                        # clear, documented explanation
+    print(error.detection.kind.value)   # e.g. "vmware"
+```
+
+Inspect detection without updating:
+
+```python
+from game_updater import detect_vm, collect_dmi
+
+print(collect_dmi())
+print(detect_vm().summary())
+print(detect_vm().indicators)
+```
+
+## Layout produced in the game folder
+
+```
+MyGame/
+  version.json      # version, sequence, notes, file list
+  game/
+    data.pak
+    patch.exe
+```
+
+`version.json` is written last, after every file is verified.
+
+## Threat model
+
+| Attack | Mitigation |
+|---|---|
+| Compromised CDN / HTTP host | Manifest signature check |
+| Modified file in transit | SHA-256 per file |
+| Manifest replay of an older signed version | Signed monotonic `sequence`; lower or unchanged sequences for a different version are rejected |
+| Path traversal (`../`) | `safe_join` rejects absolute paths and `..` |
+| Unsigned patch execution | `run` target must be in `files`, verified, and `--run` passed |
+| Malicious local manifest URL | HTTPS only (localhost allowed only with `--allow-insecure`) |
+| VM use against policy | `vm_policy="block"` stops before any work; best-effort detection, not a security boundary |
+
+## Honest limitation
+
+If someone steals your private signing key, they can sign a malicious update.
+Treat the key like a code-signing key: offline, backed up, never in the repo.
+
+VM detection is a compatibility policy, not DRM. DMI values can be spoofed or
+withheld, so the check can be wrong in both directions. It does not make the
+library uncrackable; the signed manifest and SHA-256 checks are the actual
+integrity controls.

game_updater-0.3.0/README.md

@@ -0,0 +1,276 @@
+# Game Updater
+
+A small, auditable updater for a game or app that you host yourself.
+
+It does **not** run anything at install time. It runs only when you call the
+CLI or the `update()` function, and it refuses to install anything that is not
+covered by a valid Ed25519 signature and a matching SHA-256 hash.
+
+## What it does
+
+1. Checks the VM compatibility policy when enabled (default: `off`). With
+   `vm_policy="block"`, a detected VM stops the call before anything is
+   downloaded, installed, or run.
+2. Downloads `manifest.json` over HTTPS.
+3. Verifies the manifest signature against the public key embedded in this
+   package.
+4. Compares the remote version with the local `version.json`.
+5. Downloads each listed file to a staging folder.
+6. Verifies size and SHA-256 for every file.
+7. Moves the verified files into the game directory.
+8. Writes `version.json` with the version, sequence, notes, and file list.
+9. Optionally runs a patch executable — only if it is listed in the signed
+   manifest, hash-verified, and `--run` was passed.
+
+## What it does not do
+
+- No `setup.py` / PEP 517 hooks that execute anything.
+- No `.pth` files, no `sitecustomize.py`, no persistence.
+- No obfuscation. The source is readable.
+- No unsigned downloads. Every byte is checked against the signed manifest.
+- No silent execution. `--run` is explicit.
+- No stealth VM detection. The policy is explicit, documented, and printed by
+  the CLI.
+- No anti-debug, timing checks, process scanning, or security-tool
+  interference.
+- No network requests for VM detection. It only reads local OS metadata.
+
+## VM compatibility policy
+
+The check is a configurable compatibility policy, not a stealth feature. It
+runs at the start of `update()` and before the CLI reads local state.
+
+| Policy | Behavior |
+|---|---|
+| `off` (default) | Skip VM detection entirely. |
+| `allow` | Detect and report, but never block. Ordinary physical PCs and VM users both work. |
+| `block` | If a VM is detected, raise `VMBlockedError` before creating the game directory, fetching the manifest, installing files, or running a patch. |
+
+When detection runs, the CLI prints the result before doing any work. A
+`block` refusal prints the documented error instead; `off` prints nothing.
+
+```text
+vm check: physical machine (no known VM indicators found)
+```
+
+If a VM is detected and the policy is `block`:
+
+```text
+error: VM use is disabled by policy (vm_policy='block'), but this machine
+appears to be a vmware virtual machine (confidence: high). Indicators:
+DMI system manufacturer is VMware; DMI system product is VMware. No update
+was downloaded, installed, or run. If this is a physical machine, this is a
+false positive; use vm_policy='allow' or vm_policy='off' to proceed. VM
+detection is best-effort and can be wrong.
+```
+
+CLI exit code is `3` for a VM policy block, `2` for an update/manifest error,
+and `0` on success.
+
+### Indicators used
+
+Detection is conservative and uses only documented, read-only DMI/SMBIOS
+values exposed by the OS:
+
+| Environment | Definitive indicators | Supporting only |
+|---|---|---|
+| Hyper-V | DMI system product `Virtual Machine`; DMI system version `Hyper-V` | Hyper-V guest integration registry key |
+| QEMU / KVM | DMI system/board manufacturer `QEMU`; DMI product `Standard PC (Q35 ...)` or `Standard PC (i440FX ...)` | BIOS vendor `SeaBIOS` |
+| VMware | DMI manufacturer, product, version, board, or BIOS containing `VMware` | — |
+| VirtualBox | DMI manufacturer/board/BIOS `innotek`; product/version `VirtualBox` | — |
+
+Unsupported platforms (including macOS) return `UNKNOWN`; they are not
+guessed at and are allowed under `block`.
+
+Rules:
+
+- A VM result requires at least one **definitive** vendor-specific string.
+- Supporting-only evidence (for example, SeaBIOS alone, or the Hyper-V guest
+  key alone) returns `UNKNOWN`, not `VM`.
+- Two different definitive vendors return `UNKNOWN` with
+  `conflicting=True`.
+- A missing or unreadable DMI source returns `UNKNOWN`.
+- `block` refuses only on `VM`. `PHYSICAL` and `UNKNOWN` are allowed, which
+  keeps ordinary PCs working and avoids blocking on ambiguous evidence.
+
+### What is intentionally not used
+
+- The CPUID hypervisor-present bit. Physical Windows machines with Hyper-V,
+  VBS, or Memory Integrity enabled can set it, causing false positives.
+- Timing measurements, process scanning, debugger checks, or anti-analysis
+  tricks.
+- Network requests or external services.
+- Any attempt to disable or interfere with security tools.
+
+### Limitations
+
+VM detection is imperfect. DMI strings can be spoofed, hidden, or changed by
+the hypervisor, and some physical firmware exposes unusual values. A
+`PHYSICAL` result means "no known VM indicator was found", not proof. A `VM`
+result can be a false positive; `vm_policy="allow"` or `vm_policy="off"` is
+the documented escape hatch.
+
+This check is **not** a security boundary and does **not** make the library
+impossible to crack or bypass. The real protections are the signed manifest,
+SHA-256 verification, HTTPS, and keeping the private signing key offline. Do
+not use VM detection as a substitute for those controls.
+
+## Install
+
+```powershell
+pip install game-updater
+```
+
+From a local checkout:
+
+```powershell
+pip install .
+```
+
+This package is for publishers who control both the manifest host and the
+signing key. Only point it at manifests you signed.
+
+## Generate a signing key
+
+```powershell
+python tools/keygen.py --private game_private.pem
+```
+
+Put the printed public key into `src/game_updater/public_key.txt`.
+
+Keep `game_private.pem` offline. Never commit it.
+
+## Build and sign a manifest
+
+Create `manifest.json` without a signature:
+
+```json
+{
+  "version": "1.4.0",
+  "sequence": 3,
+  "notes": "Season 3 patch",
+  "files": [
+    {
+      "path": "game/data.pak",
+      "url": "https://cdn.example.com/game/data-1.4.0.pak",
+      "sha256": "…",
+      "size": 12345678
+    },
+    {
+      "path": "game/patch.exe",
+      "url": "https://cdn.example.com/game/patch-1.4.0.exe",
+      "sha256": "…",
+      "size": 456789,
+      "executable": true
+    }
+  ],
+  "run": "game/patch.exe"
+}
+```
+
+`sequence` is a signed, non-negative integer. Increase it for every release.
+The updater stores it in `version.json` and refuses a manifest whose sequence
+is lower than the installed one, or equal while claiming a different version.
+That prevents replay of an older signed manifest.
+
+Sign it:
+
+```powershell
+python tools/sign_manifest.py --key game_private.pem --manifest manifest.json --out manifest.signed.json
+```
+
+Upload `manifest.signed.json` (and the files) to your HTTPS host.
+
+## Update a game folder
+
+```powershell
+game-updater --manifest https://cdn.example.com/game/manifest.signed.json --dir "C:\Games\MyGame"
+```
+
+Other modes:
+
+```powershell
+game-updater --manifest ... --dir ... --check    # show versions only
+game-updater --manifest ... --dir ... --apply    # install (asks first)
+game-updater --manifest ... --dir ... --apply --yes
+game-updater --manifest ... --dir ... --apply --run
+game-updater --manifest ... --dir ... --apply --vm-policy block
+```
+
+`--vm-policy` accepts `off` (default), `allow`, or `block`.
+
+## Python API
+
+```python
+from game_updater import update
+
+result = update(
+    manifest_url="https://cdn.example.com/game/manifest.signed.json",
+    game_dir=r"C:\Games\MyGame",
+    apply=True,
+    run_patch=False,
+)
+print(result)
+print(result.vm.summary() if result.vm else "vm check skipped")
+```
+
+To refuse updates on a detected VM:
+
+```python
+from game_updater import VMBlockedError, update
+
+try:
+    result = update(
+        manifest_url="https://cdn.example.com/game/manifest.signed.json",
+        game_dir=r"C:\Games\MyGame",
+        apply=True,
+        vm_policy="block",
+    )
+except VMBlockedError as error:
+    print(error)                        # clear, documented explanation
+    print(error.detection.kind.value)   # e.g. "vmware"
+```
+
+Inspect detection without updating:
+
+```python
+from game_updater import detect_vm, collect_dmi
+
+print(collect_dmi())
+print(detect_vm().summary())
+print(detect_vm().indicators)
+```
+
+## Layout produced in the game folder
+
+```
+MyGame/
+  version.json      # version, sequence, notes, file list
+  game/
+    data.pak
+    patch.exe
+```
+
+`version.json` is written last, after every file is verified.
+
+## Threat model
+
+| Attack | Mitigation |
+|---|---|
+| Compromised CDN / HTTP host | Manifest signature check |
+| Modified file in transit | SHA-256 per file |
+| Manifest replay of an older signed version | Signed monotonic `sequence`; lower or unchanged sequences for a different version are rejected |
+| Path traversal (`../`) | `safe_join` rejects absolute paths and `..` |
+| Unsigned patch execution | `run` target must be in `files`, verified, and `--run` passed |
+| Malicious local manifest URL | HTTPS only (localhost allowed only with `--allow-insecure`) |
+| VM use against policy | `vm_policy="block"` stops before any work; best-effort detection, not a security boundary |
+
+## Honest limitation
+
+If someone steals your private signing key, they can sign a malicious update.
+Treat the key like a code-signing key: offline, backed up, never in the repo.
+
+VM detection is a compatibility policy, not DRM. DMI values can be spoofed or
+withheld, so the check can be wrong in both directions. It does not make the
+library uncrackable; the signed manifest and SHA-256 checks are the actual
+integrity controls.

game_updater-0.3.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "game-updater"
+version = "0.3.0"
+description = "Signed, hash-verified updater for a self-hosted game or app."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "game-updater contributors" }]
+keywords = ["game", "updater", "ed25519", "sha256"]
+dependencies = ["cryptography>=41"]
+
+[project.scripts]
+game-updater = "game_updater.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+game_updater = ["public_key.txt"]

game_updater-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

game_updater-0.3.0/src/game_updater/__init__.py

@@ -0,0 +1,36 @@
+"""Signed, hash-verified updater for a self-hosted game or app."""
+
+from .install import 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.3.0"
+
+__all__ = [
+    "__version__",
+    "DMIData",
+    "Manifest",
+    "ManifestError",
+    "UpdateResult",
+    "VMBlockedError",
+    "VMDetection",
+    "VMPolicy",
+    "VMStatus",
+    "VMVendor",
+    "classify",
+    "collect_dmi",
+    "detect_vm",
+    "ensure_vm_allowed",
+    "update",
+]

game_updater-0.3.0/src/game_updater/__main__.py

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