From 1c6c361d4ac1a652b4cf92bfc7ce9746fe0a79ed Mon Sep 17 00:00:00 2001
From: michael <operations@dangerousthings.com>
Date: Mon, 27 Apr 2026 08:19:18 -0700
Subject: [PATCH] docs(pam): smoke-test recipe + test PAM stack file (Task B2)

---
 pam/TESTING.md          | 55 +++++++++++++++++++++++++++++++++++++++++
 pam/test/authforge.pamd |  6 +++++
 2 files changed, 61 insertions(+)
 create mode 100644 pam/TESTING.md
 create mode 100644 pam/test/authforge.pamd

diff --git a/pam/TESTING.md b/pam/TESTING.md
new file mode 100644
index 0000000..830a7ca
--- /dev/null
+++ b/pam/TESTING.md
@@ -0,0 +1,55 @@
+# Testing pam_authforge_pending.so
+
+This module gates first-login enrollment. Its full behavior is impossible to
+exercise from a unit test because PAM modules run inside a real PAM stack that
+needs root to install. The recipe below runs in a VM or container with
+`libpam0g-dev` and `pamtester` installed.
+
+## Build + install
+
+```bash
+sudo apt-get install -y libpam0g-dev pamtester
+sudo make -C pam install
+sudo install -D -m 0644 pam/test/authforge.pamd /etc/pam.d/authforge
+```
+
+`make install` drops the `.so` into
+`/usr/lib/$(dpkg-architecture -qDEB_HOST_MULTIARCH)/security/`.
+
+## Smoke test 1: pending flag present → denied
+
+```bash
+sudo mkdir -p /var/lib/authforge/pending
+sudo touch /var/lib/authforge/pending/$USER
+pamtester -v authforge "$USER" authenticate
+# Expect: "Account setup incomplete..." printed and a non-zero exit code.
+```
+
+## Smoke test 2: pending flag cleared → falls through
+
+```bash
+sudo rm /var/lib/authforge/pending/$USER
+pamtester -v authforge "$USER" authenticate
+# Expect: success (the test PAM stack file falls through to pam_unix after
+# our PAM_IGNORE; pamtester will prompt for the user's password).
+```
+
+## Smoke test 3: path-traversal regression
+
+These usernames must all be rejected with a logged error and `PAM_AUTH_ERR`:
+
+```bash
+for u in "../etc" "a/b" "" "." ".." "x..y"; do
+    pamtester -v authforge "$u" authenticate 2>&1 | head -3
+    echo "---"
+done
+```
+
+Logs show up via `journalctl -t authforge_pending` (or wherever your
+distribution routes `pam_syslog` — typically `/var/log/auth.log`).
+
+## CI status
+
+CI cannot run `pamtester` against a real PAM stack without root and a VM, so
+this is the last manual gate before the Phase 14 PPA build. The CI pipeline
+only verifies that `make -C pam` produces a valid ELF.
diff --git a/pam/test/authforge.pamd b/pam/test/authforge.pamd
new file mode 100644
index 0000000..1bc1e12
--- /dev/null
+++ b/pam/test/authforge.pamd
@@ -0,0 +1,6 @@
+# /etc/pam.d/authforge — only used by the manual pamtester smoke run.
+# Maps to pam/TESTING.md scenarios.
+
+auth    required    pam_authforge_pending.so
+auth    required    pam_unix.so
+account required    pam_unix.so