# 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.