Find, verify and apply a newer release from the command line

[owenpkent]

Summary

The installer landed in #7 with nothing to drive it. This is the update client the release plan's Updater boundary section described, and it meets the conditions that section set: signature, publisher and embedded version verified before elevation, and the /D= target computed from the running executable rather than read from the uninstall registry key.

offloader update              # report what is available
offloader update --install    # download, verify, hand to the installer

Exit status distinguishes "nothing to do" (0) from "an update exists but was not applied" (1) from a verification failure (2), so it can be scripted.

Two deliberate divergences from alpha-osk

Worth reviewing first, because they are where I did not copy the reference:

1. It never closes a running copy. alpha-osk's installer taskkills the app and a helper process restarts it. Offloader's installer refuses maintenance while a transfer is in flight and exits non-zero, and docs/data-safety.md makes that a promise. So this verifies and hands over. The command prints the consequence before the UAC prompt, because an operator who does not know it reads the installer's refusal as a broken update.
2. Prereleases are ordered, not rejected. alpha-osk's updater only accepts X.Y.Z tags. Offloader's first packaged release is planned as 0.1.0b1, so that rule would make the updater blind to the very build it ships in. The grammar here is the one build/windows/versioning.py already enforces, and test_the_ordering_agrees_with_the_windows_version_fields asserts both orderings agree across a list of versions — a disagreement would let an update install a build Windows then considers older than the one it replaced.

What it refuses

An updater runs network-delivered code with elevation, so the refusals are the design:

Check	Stops
Host allowlist re-applied after redirects	GitHub redirects assets to another domain, so the host serving the bytes is the one that matters
Ceiling on Content-Length and mid-stream	A hostile server owes us no honest header
SHA-256 taken while streaming, re-compared before launch	The window in which anything able to write to the download directory could swap the file
Authenticode Valid + our thumbprint + our publisher name	A valid signature belonging to somebody else
Installer's embedded FileVersion matches the release	Rollback. Re-uploading an older, still validly signed installer under a newer asset name would otherwise move every install onto a build whose faults are fixed
Tag must be a version this project publishes	latest or 1.0.3-evil being string-compared into an upgrade
Asset named exactly Offloader-Setup-{version}.exe	A file attached beside the real installer being served instead

/D= is emitted last and unquoted, the two rules NSIS enforces silently. Certificate constants are duplicated from build/windows/sign.py rather than imported, since the build scripts are not shipped — flagging that as the one bit of duplication, in case you would rather move them into the package.

Not included

• No in-app check. A timer, notification and progress surface belong with the desktop interface; the release plan already treats that as separate. download() takes a progress callback so the GUI can wire straight into it.
• No release workflow. The updater needs a published release to see, and .github/workflows/release.yml still does not exist. Worth knowing: alpha-osk has no release automation either (releases are built and gh release created by hand), so this is net-new work rather than parity. Happy to do it next.
• No rollback, by design: the installer's own transactional recovery owns that, and a second recovery mechanism layered on top would fight it.

Test plan

• tests/test_update.py — 62 tests, mostly refusals: unparseable versions fail closed, prerelease ordering, the cross-check against versioning.py, malformed feeds, wrong/renamed assets, non-HTTPS and off-allowlist hosts, a redirect to another host, the ceiling both ways, digest-changed-after-download, each signature rule failing on its own, thumbprint compared without spacing or case, /D= shape, and a declined UAC prompt reported as such rather than as a failed download
• Full suite 782 passed, 12 skipped; ruff check src tests scripts build/windows clean
• Live smoke: offloader update against the real feed with no releases published returns "0.1.0 is the newest release available", exit 0 (fails closed on the 404 rather than raising)
• End-to-end against an actual signed published release — cannot be done until one exists

[owenpkent]

Reviewed feed discovery, version/asset selection, download handling, installer verification, installed-location handling, and the CLI handoff. The actual feed cannot deliver the planned beta-to-beta updates; details inline.

Additional updater-security findings are supplied privately under SECURITY.md, including their affected call paths and suggested regression coverage. This public comment omits those reproductions. Validation for this review was static code inspection and verification of GitHub's documented release-feed behavior; no downloaded installer was executed.

[owenpkent]

[P2] Use a feed that can discover the beta releases being shipped.

GitHub's /releases/latest endpoint returns a published full release and excludes releases marked as prereleases. Consequently an installed 0.1.0b1 cannot discover 0.1.0b2 or 0.1.0rc1 through this URL, despite the prerelease ordering supported below. If the repository has only beta releases, the endpoint does not return any eligible candidate. This also conflicts with the candidate workflow's use of --prerelease.

Select the greatest eligible version from the releases collection, or define explicit stable/beta channels and their selection rules. Add a feed-level test containing multiple beta/RC releases, a stable release, and drafts, rather than testing only version comparison against a hand-picked single payload.

Reference: GitHub's latest-release API contract.