docs(pkg): piuparts test recipe — Ubuntu 24.04, install/remove/purge cycle

debian/PIUPARTS.md

@@ -0,0 +1,75 @@
+# Testing the AuthForge debs with piuparts
+
+piuparts simulates a clean Debian/Ubuntu install in a chroot, runs the
+install/upgrade/remove/purge cycle, and verifies no files leak.
+This is the strongest manual gate before the Phase 14 PPA build picks
+up automated VM-based testing.
+
+## Target
+
+**Ubuntu 24.04 only** for v1. The GUI (`authforge-gui`) hard-requires
+libadwaita 1.5+, which Ubuntu 22.04 does not ship. Older targets would
+need a 1.5 backport PPA — not worth the matrix complexity for v1.
+
+## Prerequisites
+
+```bash
+sudo apt install piuparts debootstrap
+```
+
+piuparts pulls a fresh `noble` (24.04) chroot on every run; first run
+takes ~5 minutes to download base, subsequent runs use the cache at
+`/var/cache/piuparts/`.
+
+## Run
+
+From the project root, after a successful `dpkg-buildpackage -us -uc -b`:
+
+```bash
+sudo piuparts \
+  --distribution=noble \
+  --mirror "http://archive.ubuntu.com/ubuntu noble main universe" \
+  --arch amd64 \
+  --warn-on-leftovers-after-purge \
+  ../authforge_*.deb \
+  ../authforge-*.deb
+```
+
+The `--mirror` line includes `universe` because `libpam-google-authenticator`
+(Recommends of `authforge-daemon`) lives there. Without it piuparts can't
+resolve the recommends and the test fails before installing AuthForge.
+
+## What piuparts exercises
+
+1. Install all debs together (metapackage pulls in all binary packages).
+2. Verify the daemon's systemd unit enables + starts under systemd-in-chroot.
+3. Verify `pam-auth-update --package` registered the AuthForge profile
+   (look for `authforge` in `/etc/pam.d/common-auth`).
+4. Reinstall (0.1.0 over 0.1.0) — postinst runs again, must be idempotent.
+5. Remove — `pam-auth-update --remove authforge` runs in prerm; the
+   binaries disappear; `/etc/authforge/` and `/var/lib/authforge/` survive.
+6. Purge — postrm wipes `/etc/authforge/` and `/var/lib/authforge/`;
+   piuparts diffs the chroot against its initial snapshot and reports
+   leftovers.
+
+## Pass criteria
+
+- [ ] piuparts exit code 0.
+- [ ] No `FAIL` lines in the output.
+- [ ] Any `WARN: leftover` lines refer only to systemd/journald state
+      (logs, runtime files in `/run/`) — not files in
+      `/etc/authforge/`, `/var/lib/authforge/`, or `/usr/share/pam-configs/`.
+- [ ] `pam-auth-update --list` (run inside the chroot mid-test, if you
+      pause it) shows `authforge` after install and absent after
+      remove — piuparts surfaces this implicitly via its `/etc/pam.d/`
+      diff.
+
+## Known surface gaps
+
+- piuparts can't exercise the GUI or the FIDO2 enrollment flow — those
+  need a real desktop session, deferred to Phase 14 VM smoke
+  (`gui/TESTING.md`, `gui/FIRSTRUN-TESTING.md`).
+- The debconf prompt is non-interactive in piuparts (uses defaults).
+  To test the "Required for sudo" branch end-to-end, run a manual
+  install with `DEBCONF_PRIORITY=critical` and check that
+  `/etc/authforge/policy.d/00-debconf.conf` was written.