From 21bf1f5a3fc353bb7eed83c0008ef82c6aba2e41 Mon Sep 17 00:00:00 2001
From: michael <operations@dangerousthings.com>
Date: Mon, 27 Apr 2026 19:54:47 -0700
Subject: [PATCH] =?UTF-8?q?docs(pkg):=20piuparts=20test=20recipe=20?=
 =?UTF-8?q?=E2=80=94=20Ubuntu=2024.04,=20install/remove/purge=20cycle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 debian/PIUPARTS.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 debian/PIUPARTS.md

diff --git a/debian/PIUPARTS.md b/debian/PIUPARTS.md
new file mode 100644
index 0000000..fd43b31
--- /dev/null
+++ b/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.