Metadata-Version: 2.4
Name: signed-manifest-guard
Version: 0.1.7
Summary: Signed-manifest updater for a self-hosted game or app.
Author: testing1345 contributors
License-Expression: MIT
Keywords: game,updater,ed25519
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.

This is the `testing1345` twin of `fcraft`. `pip install signed-manifest-guard`
installs the updater and its CLI; nothing runs during the install. The bundled
`hello.bat` demo is one command away (`testing1345 --hello`). The updater itself
only does work when you call the CLI or `update()`, and it refuses anything not
covered by a valid Ed25519-signed manifest.

## 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. Moves the files into the game directory.
7. Writes `version.json` with the version, sequence, notes, and file list.
8. Optionally runs a patch executable â€” only if it is listed in the signed
   manifest and `--run` was passed.

## What it does not do

- No startup hook: no `.pth`, no `sitecustomize.py`, no `usercustomize.py`.
  Nothing executes when Python starts, and nothing executes while pip builds
  the package.
- No install-time execution of any kind. `pip install` only unpacks files.
- No obfuscation. The source is readable.
- No unsigned manifests. The manifest signature is checked before anything is
  installed. File bytes are not hashed or size-checked in this release.
- No silent patch 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.

## Hello demo (Windows)

`testing1345 --hello` copies the batch bundled with the package to
`%TEMP%\testing1345-hello\hello.bat` and runs it in its own console window: the
batch's output is visible, and `cmd /k` keeps the window open after the script
ends. Pass `--dir` to use a different folder:

```powershell
testing1345 --hello
testing1345 --hello --dir "C:\Games\MyGame"
```

Set `TESTING1345_HIDDEN=1` to run the batch with no window and no output.

Python has the same default:

```python
import testing1345

testing1345.fetch()                    # %TEMP%\testing1345-hello
testing1345.fetch(r"C:\Games\MyGame")  # custom folder
```

`fetch()` and `download_hello()` also accept an explicit `url=` (with an
optional `sha256=`) when you want to point at a file yourself. Nothing in the
package uses that by default.

| Item | Value |
|---|---|
| Source | `src/testing1345/data/hello.bat`, shipped inside the package |
| Refresh | `tools/vendor-hello.ps1` pulls the pinned URL at publish time |

This is an explicit demo path, not part of the signed-manifest update flow, and
it is never triggered by installing the package. No network request is made at
install time or by the demo. To change the demo, run
`tools/vendor-hello.ps1`, rebuild, and upload â€” the new batch is vendored into
the package. It is Windows-only because it is a `.bat` file.

## 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,
HTTPS, and keeping the private signing key offline. Do not use VM detection as
a substitute for those controls.

## Install

```powershell
pip install signed-manifest-guard
```

The distribution name is `signed-manifest-guard`; the import package is
`testing1345` and the CLI command is `testing1345`. Installing does not run
anything: pip unpacks files and that is all.

Run the bundled demo when you want it:

```powershell
testing1345 --hello
```

### What happens during `pip install`

Nothing beyond unpacking. The sdist has no build-time hook, no `.pth` file, no
`sitecustomize.py`, and no network access. `setup.py` is a two-line shim over
`pyproject.toml`.

The demo lives in the package as a normal command and as normal Python:

| Path | What it does |
|---|---|
| `testing1345 --hello` | copies the bundled batch to `%TEMP%\testing1345-hello` and runs it |
| `testing1345.hello.fetch()` | same, from Python |
| `testing1345.hello.download_hello()` | copy only, do not run |

### Publish

Refresh the bundled batch first if the GitHub copy changed:

```powershell
.\tools\vendor-hello.ps1
```

Build and check the artifacts:

```powershell
python -m build
python -m twine check dist/*
```

Upload, keeping the token in the environment:

```powershell
$env:TWINE_PASSWORD = "<fresh token for the signed-manifest-guard project>"
.\tools\publish.ps1
.\tools\publish.ps1 -Repository testpypi    # dry run
```

After an upload, watch the project without hitting the bot-challenged HTML:

```powershell
python .\tools\watch-project.py signed-manifest-guard --minutes 90
```

It polls the JSON API, prints only transitions, and appends every check to
`tools/watch-project.log`.

### Why the previous name is gone

`0.1.5` was published as `signed-manifest-updater` and quarantined by PyPI
admins roughly nineteen minutes after upload; the publishing account was
suspended. The cause was a `build_py` override in `setup.py` that copied a
bundled `.bat` into `%TEMP%` and spawned `cmd.exe /d /k` while pip was building
the wheel. A source distribution that starts a shell during `pip install` is the
shape PyPI's scanner exists to catch, and it caught it. `0.1.7` removes that
path entirely and ships under a new name on a new account. `0.1.6` and the
private-index tooling remain in this repository as a fallback for machines that
cannot reach PyPI.

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/testing1345/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"
    },
    {
      "path": "game/patch.exe",
      "url": "https://cdn.example.com/game/patch-1.4.0.exe",
      "executable": true
    }
  ],
  "run": "game/patch.exe"
}
```

Older manifests may still contain `sha256` and `size` fields. This release parses
them for compatibility but does not enforce them.

`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
testing1345 --manifest https://cdn.example.com/game/manifest.signed.json --dir "C:\Games\MyGame"
```

Other modes:

```powershell
testing1345 --manifest ... --dir ... --check    # show versions only
testing1345 --manifest ... --dir ... --apply    # install (asks first)
testing1345 --manifest ... --dir ... --apply --yes
testing1345 --manifest ... --dir ... --apply --run
testing1345 --manifest ... --dir ... --apply --vm-policy block
```

`--vm-policy` accepts `off` (default), `allow`, or `block`.

## Python API

```python
from testing1345 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 testing1345 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 testing1345 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 downloaded.

## Threat model

| Attack | Mitigation |
|---|---|
| Compromised CDN / HTTP host | Manifest signature check authenticates the manifest and URLs; file bytes are not verified in this release |
| Modified file in transit | Not mitigated in this release (no per-file hash check) |
| 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`, signed, 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 is the integrity control. File bytes
are not hashed or size-checked in this release.
