Support signed deb self-updates with system authorization in 0.1.4

docs/launcher-updates.md

@@ -9,9 +9,13 @@ updater verifies signatures before installing; an unavailable or invalid feed
 does not prevent playing with the installed launcher.
 
 The first version containing the updater must be installed manually. Version
-0.1.2 has no code capable of installing this feature itself. On Linux, automatic
-replacement is for AppImage installations; deb installations and development
-binaries use the manual download path. Windows/macOS publication and actual
+0.1.2 has no code capable of installing this feature itself. AppImage supports
+self-updates from 0.1.3; deb adds them in 0.1.4. An existing 0.1.3 deb therefore
+needs one manual upgrade to 0.1.4 before its own update button can work. A deb
+installation keeps its package format and asks for system administrator
+authorization when installing an update. The launcher itself runs as the normal
+user. Development binaries use the manual download path. Windows/macOS
+publication and actual
 installation tests remain separate release work; supporting a platform in the
 feed schema does not certify a working release on it.
 
@@ -22,7 +26,7 @@ The archived 2026-09-09 review bundle at
 unreleased updater prototype: GitHub-hosted `latest.json`, a different pinned
 key and the former LoginSystem/Game Bridge proof flow. Its successful CI and
 prototype version numbers do not establish compatibility with the deployed
-admission protocol. The current 0.1.3 release follows the deployed 0.1.2
+admission protocol. The 0.1.3 and 0.1.4 releases follow the deployed 0.1.2
 admission line based on `bf43254`, using the ShaCraft-hosted feed described here.
 
 Never publish the archived `CI-NOT-FOR-RELEASE`/`CI_NOT_FOR_RELEASE` packages or
@@ -56,13 +60,65 @@ verified through Tauri's built-in updater signature check. The current version
 must increase; there is no unsigned or automatic downgrade fallback.
 
 The stable publisher accepts only plain `MAJOR.MINOR.PATCH` versions and these
-platforms: `linux-x86_64` (`.AppImage`), `windows-x86_64` (`.exe` or `.msi`),
+platforms: `linux-x86_64` (legacy `.AppImage`), `linux-x86_64-appimage`
+(`.AppImage`), `linux-x86_64-deb` (`.deb`), `windows-x86_64` (`.exe` or `.msi`),
 `darwin-x86_64` and `darwin-aarch64` (`.app.tar.gz`). Artifact filenames contain
 only ASCII letters, digits, dots, underscores and hyphens. Files must already
 exist in the matching version directory, must not be symlinks and must be
 between 1 byte and 256 MiB. A platform without a tested signed artifact is
 omitted, never represented by an empty signature or another platform's file.
 
+Format-aware Linux feeds must contain both AppImage keys with exactly the same
+URL and signature. This keeps 0.1.3 clients on their original AppImage path.
+New AppImage clients prefer `linux-x86_64-appimage` and can read the legacy key;
+deb clients require `linux-x86_64-deb` and never fall back to an AppImage.
+Preserve all three entries when publishing a release that supports both formats.
+
+After verifying each signature, the publisher also checks Linux package format.
+AppImage must have the ELF64 little-endian x86_64 and type-2 AppImage header.
+For deb, `/usr/bin/dpkg-deb` must report package `sha-craft-launcher`, architecture
+`amd64` and the exact signed release version. Inspection uses fixed arguments,
+no shell, a cleared environment, a 10-second timeout and a 4 KiB output limit.
+It does not install a package or execute its maintainer scripts. This protects
+against accidental publication of the wrong signed package; an installer
+signature remains mandatory and is checked before package inspection.
+
+## Debian installation boundary
+
+The installed launcher must be `/usr/bin/shacraft-launcher`, owned by root in
+root-owned directories that other users cannot write. The package database
+must assign that file to an installed `sha-craft-launcher` of the expected
+architecture. The updater needs the system `pkexec` authorization agent; it
+does not collect a password or fall back to running a shell with privileges.
+
+After the normal-user downloader verifies the update, `pkexec` launches the
+fixed installed binary with `--shacraft-install-deb`. This mode runs before
+Tauri/GTK initialization. It accepts only length-bounded signed metadata and
+package bytes over stdin, never a user-provided package path. The root helper
+independently verifies the metadata, selects only the exact deb target, checks
+the package signature and requires a higher version than the current dpkg
+database. It writes the verified bytes to a root-created mode-0700 temporary
+directory under the validated `/var/tmp`; the file has mode 0600.
+
+The helper checks the package's exact name, version and architecture with
+`dpkg-deb`, then invokes fixed `dpkg --refuse-downgrade --install` arguments in
+an environment without inherited variables. Dpkg's own downgrade refusal
+protects against a competing newer installation between the version check and
+the package-manager lock. A successful result also requires the package
+database to report the intended version as installed. The temporary package
+is removed on completion. A signed deb may include maintainer scripts, which
+dpkg runs with administrator privileges as part of normal installation: review
+release package contents before signing.
+
+Cancellation of system authorization, missing authorization support, signature
+rejection, a busy package manager and installation failure have distinct
+messages. There is no automatic retry with weaker checks. Dpkg installation
+is not an atomic file replacement: dependency/configuration failures or power
+loss can require normal package-manager recovery. The launcher reports failure
+instead of claiming the old installation is intact. Successful deb updates
+restart the fixed installed binary as the ordinary user. These guarantees
+are separate from AppImage's same-directory atomic replacement.
+
 ## Keys and builds
 
 The production private key stays **only on the operator's local machine** at
@@ -88,33 +144,40 @@ package signatures; passing updater checks does not establish those assurances.
 
 ## Local preparation and signing
 
-The publisher requires Python 3.10+ and `minisign`. It performs verification
+The publisher requires Python 3.10+ and `minisign`; releases containing deb also
+require `/usr/bin/dpkg-deb` (Debian/Ubuntu's `dpkg` package). It performs verification
 through the standard minisign CLI, without implementing cryptography in Python.
 `--minisign /absolute/path/to/minisign` supports a locally extracted tool without
 installing a global package. Run these examples from the launcher repository,
 substituting the actual release version and tested filenames.
 
 1. Stage immutable, tested packages below a local downloads root. The following
-   example assumes the Linux artifact already exists at
-   `/tmp/shacraft-release/downloads/0.1.3/ShaCraft.Launcher_0.1.3_amd64.AppImage`
+   example assumes both tested Linux artifacts already exist below
+   `/tmp/shacraft-release/downloads/0.1.4/`
    and release notes exist at `/tmp/shacraft-release/notes.txt`. Create signatures
    with the Tauri CLI; `.sig` is written beside each artifact:
 
    ```bash
    npm run tauri -- signer sign \
      --private-key-path /home/emil/.local/share/shacraft-updater/production.key \
-     /tmp/shacraft-release/downloads/0.1.3/ShaCraft.Launcher_0.1.3_amd64.AppImage
+     /tmp/shacraft-release/downloads/0.1.4/ShaCraft.Launcher_0.1.4_amd64.AppImage
+   npm run tauri -- signer sign \
+     --private-key-path /home/emil/.local/share/shacraft-updater/production.key \
+     /tmp/shacraft-release/downloads/0.1.4/ShaCraft.Launcher_0.1.4_amd64.deb
    ```
 
 2. Prepare a deterministic payload after verifying every package signature.
    Repeat `--artifact PLATFORM=FILENAME` for each tested platform included in this
-   release. Do not list a deb, dmg, nonexistent package or untested architecture:
+   release. Keep the legacy AppImage alias. Do not list a dmg, nonexistent
+   package or untested architecture:
 
    ```bash
    python3 scripts/publish_launcher_update.py prepare \
-     --version 0.1.3 \
+     --version 0.1.4 \
      --downloads-root /tmp/shacraft-release/downloads \
-     --artifact linux-x86_64=ShaCraft.Launcher_0.1.3_amd64.AppImage \
+     --artifact linux-x86_64=ShaCraft.Launcher_0.1.4_amd64.AppImage \
+     --artifact linux-x86_64-appimage=ShaCraft.Launcher_0.1.4_amd64.AppImage \
+     --artifact linux-x86_64-deb=ShaCraft.Launcher_0.1.4_amd64.deb \
      --notes-file /tmp/shacraft-release/notes.txt \
      --public-key /home/emil/.local/share/shacraft-updater/production.key.pub \
      --payload /tmp/shacraft-release/release.payload.json
@@ -173,8 +236,12 @@ must validate against the actual deployed feed, not an empty staging directory.
 Caddy should serve this feed as JSON with `Cache-Control: no-store`. Check the
 public response, decoded metadata, signatures and downloadable artifact hashes
 after deployment. Exercise a real installed AppImage updating to a higher
-version, including relaunch and retained settings/account state. Unit tests,
-packaging or a browser mock alone do not establish successful installation.
+version, including relaunch and retained settings/account state. For deb, also
+exercise administrator cancellation, package-manager lock conflicts, failed
+installation and a successful package upgrade/relaunch. Use an isolated system
+for destructive package-manager failure cases; never modify player data as a
+test fixture. Unit tests, packaging or a browser mock alone do not establish
+successful installation or distribution compatibility.
 If a release is faulty, stop offering it and publish a corrected higher version;
 do not weaken signature checks or silently downgrade users.
 
@@ -187,6 +254,10 @@ python3 -m unittest discover -s scripts -p 'test_*.py'
 Publisher tests exercise the real minisign CLI with temporary test keys,
 including valid publication, modified packages and metadata, authenticated
 previous-version checks, downgrade refusal, URL/path restrictions and dry-run.
+Linux tests also build real temporary deb packages with `dpkg-deb`, validate
+package/version/architecture, ensure inspection never executes maintainer
+scripts, retain the legacy AppImage feed alias, and reject malformed signed
+Linux packages. Package-inspection output and time bounds are exercised.
 No test private key is checked into the repository. CI installs minisign so
 the signature tests run; locally they explicitly skip if the tool is absent.
 Set `SHACRAFT_TEST_MINISIGN` to use an extracted executable.