feat(pam): recovery-code mode with Argon2id verify and pending re-enroll handoff

C-side: * New mode=recovery argv branch in pam_sm_authenticate. Reads the two-line /var/lib/authforge/recovery/<user> file, argon2_verify against PAM_AUTHTOK, on match unlinks the file (one-shot) and writes pending(re_enroll=true). Always returns PAM_IGNORE on failure paths so a missing/wrong code never blocks normal auth. * Makefile links -largon2 alongside -lpam. Daemon-side: * policy_apply::render_profile renders the recovery line first in the auth stack with [success=done default=ignore] — successful recovery short- circuits the rest, missing/wrong code falls through. * New policy_apply test asserts the recovery line precedes the default backstop. Doc: * pam/TESTING.md adds libargon2-dev to the build prereqs and a new Smoke test 4 walking through the manual recovery-code flow. C compile gate (make -C pam) requires libargon2-dev — flagged as a deferred verification step until a host with the dev package is available. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 09:49:44 -07:00
parent a420aa5f75
commit 56ba4dd924
4 changed files with 188 additions and 9 deletions
--- a/pam/Makefile
+++ b/pam/Makefile
@@ -2,7 +2,7 @@ CFLAGS ?= -Wall -Wextra -Werror -fPIC -O2
 LIBDIR ?= /usr/lib/$(shell dpkg-architecture -qDEB_HOST_MULTIARCH)/security

 pam_authforge_pending.so: pam_authforge_pending.c
-	$(CC) $(CFLAGS) -shared -o $@ $< -lpam
+	$(CC) $(CFLAGS) -shared -o $@ $< -lpam -largon2

 install: pam_authforge_pending.so
 	install -D -m 0644 pam_authforge_pending.so $(DESTDIR)$(LIBDIR)/pam_authforge_pending.so
--- a/pam/TESTING.md
+++ b/pam/TESTING.md
@@ -8,11 +8,13 @@ needs root to install. The recipe below runs in a VM or container with
 ## Build + install

 ```bash
-sudo apt-get install -y libpam0g-dev pamtester
+sudo apt-get install -y libpam0g-dev libargon2-dev pamtester
 sudo make -C pam install
 sudo install -D -m 0644 pam/test/authforge.pamd /etc/pam.d/authforge
 ```

+`libargon2-dev` is required for the recovery-mode verification path (Phase 12).
+
 `make install` drops the `.so` into
 `/usr/lib/$(dpkg-architecture -qDEB_HOST_MULTIARCH)/security/`.

@@ -48,6 +50,42 @@ done
 Logs show up via `journalctl -t authforge_pending` (or wherever your
 distribution routes `pam_syslog` — typically `/var/log/auth.log`).

+## Smoke test 4: recovery-code path (Phase 12)
+
+The module's recovery branch activates when invoked with `mode=recovery` in
+the PAM stack. The pam-auth-update profile rendered by Phase 4 puts this
+line first in the auth stack — a successful recovery code short-circuits
+the rest of the auth chain via `[success=done default=ignore]`.
+
+To exercise it manually with `pamtester` against a custom stack:
+
+```bash
+# 1. Issue a code via the daemon and stash the plaintext.
+CODE=$(sudo authforgectl recovery generate "$USER" | tr -d '\n')
+echo "issued $CODE"
+
+# 2. Build a PAM stack file that runs ONLY the recovery-mode module.
+sudo tee /etc/pam.d/authforge-recovery <<'EOF'
+auth [success=done default=ignore] pam_authforge_pending.so mode=recovery
+auth required                       pam_deny.so
+EOF
+
+# 3. Verify a matching code authenticates.
+echo "$CODE" | pamtester -v authforge-recovery "$USER" authenticate
+# Expect: PAM_SUCCESS, /var/lib/authforge/recovery/$USER deleted, and
+# /var/lib/authforge/pending/$USER now contains re_enroll: true.
+
+# 4. Verify a non-matching code falls through to pam_deny.
+echo "$CODE" | pamtester -v authforge-recovery "$USER" authenticate
+# Expect: failure (pam_deny) — the recovery file was already consumed.
+
+# 5. Cleanup.
+sudo rm /etc/pam.d/authforge-recovery /var/lib/authforge/pending/$USER
+```
+
+The recovery file is at `/var/lib/authforge/recovery/<user>` mode 0600.
+The two-line format is `<expires_unix>\n<argon2id-PHC>\n`.
+
 ## CI status

 CI cannot run `pamtester` against a real PAM stack without root and a VM, so
--- a/pam/pam_authforge_pending.c
+++ b/pam/pam_authforge_pending.c
@@ -1,7 +1,12 @@
 /*
- * pam_authforge_pending.so — backstop for AuthForge first-login enrollment.
+ * pam_authforge_pending.so — backstop for AuthForge first-login enrollment
+ * and recovery-code verification.
 *
- * Behavior:
+ * Modes (selected by argv):
+ *   default       — first-login pending-flag check (Phase 6).
+ *   mode=recovery — verify a one-shot recovery code (Phase 12).
+ *
+ * Default-mode behavior:
 *   1. Read PAM_USER.
 *   2. Reject usernames that would let the path computation escape
 *      /var/lib/authforge/pending/.
@@ -10,20 +15,33 @@
 *        - ENOENT   -> return PAM_IGNORE (let the rest of the stack decide).
 *        - other    -> log + return PAM_AUTH_ERR (fail closed).
 *
- * Recovery codes (Phase 12) wire into a separate hook that's a no-op here.
+ * Recovery-mode behavior:
+ *   1. Read PAM_USER (same sanity checks).
+ *   2. stat() /var/lib/authforge/recovery/<user>; ENOENT -> PAM_IGNORE.
+ *   3. Read the file's two lines: <expires_unix>\n<argon2id-PHC>\n.
+ *   4. argon2_verify(phc, PAM_AUTHTOK). On match: unlink the recovery file,
+ *      write a pending(re_enroll=true) flag for the user, return PAM_SUCCESS.
+ *      On mismatch / expired / parse error: PAM_IGNORE (never fail closed in
+ *      recovery mode — false negatives must not lock out normal login paths).
 */

 #define PAM_SM_AUTH
 #include <security/pam_modules.h>
 #include <security/pam_ext.h>

+#include <argon2.h>
 #include <errno.h>
+#include <stdint.h>
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 #include <syslog.h>
 #include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>

 #define PENDING_DIR  "/var/lib/authforge/pending/"
+#define RECOVERY_DIR "/var/lib/authforge/recovery/"
 #define USER_MSG     "Account setup incomplete. Please complete enrollment in the Authentication app."

 static int username_is_safe(const char *u) {
@@ -47,18 +65,117 @@ static int pending_flag_present(const char *user) {
    return -1;
 }

+/* Read /var/lib/authforge/recovery/<user>. On success: *expires_out gets
+ * the UNIX timestamp from line 1, *phc_out is a heap-allocated copy of
+ * line 2 (caller frees). Returns 0 on success, -1 on any error. */
+static int read_recovery_file(const char *user,
+                              uint64_t *expires_out,
+                              char **phc_out) {
+    *phc_out = NULL;
+    char path[1024];
+    int n = snprintf(path, sizeof(path), "%s%s", RECOVERY_DIR, user);
+    if (n < 0 || (size_t)n >= sizeof(path)) return -1;
+    FILE *f = fopen(path, "r");
+    if (!f) return -1;
+    char line1[64];
+    char line2[256];
+    if (!fgets(line1, sizeof(line1), f) || !fgets(line2, sizeof(line2), f)) {
+        fclose(f);
+        return -1;
+    }
+    fclose(f);
+    line1[strcspn(line1, "\r\n")] = '\0';
+    line2[strcspn(line2, "\r\n")] = '\0';
+    char *end = NULL;
+    unsigned long long parsed = strtoull(line1, &end, 10);
+    if (end == NULL || *end != '\0' || end == line1) return -1;
+    *expires_out = (uint64_t)parsed;
+    *phc_out = strdup(line2);
+    return *phc_out ? 0 : -1;
+}
+
+/* Write a JSON pending(re_enroll=true) flag for `user`. Format mirrors
+ * authforge_common::types::PendingFlag's serde representation; the daemon
+ * round-trips it on next read. Returns 0 on success, -1 on error. */
+static int write_pending_re_enroll(const char *user) {
+    char path[1024];
+    int n = snprintf(path, sizeof(path), "%s%s", PENDING_DIR, user);
+    if (n < 0 || (size_t)n >= sizeof(path)) return -1;
+    FILE *f = fopen(path, "w");
+    if (!f) return -1;
+    fprintf(f,
+            "{\n  \"required_methods\": [\"fido2\"],\n"
+            "  \"created_unix\": %ld,\n"
+            "  \"deadline_unix\": 0,\n"
+            "  \"re_enroll\": true\n}\n",
+            (long)time(NULL));
+    fclose(f);
+    chmod(path, 0644);
+    return 0;
+}
+
+/* Verify a candidate code for `user` against the on-disk recovery file.
+ * On match: unlinks the recovery file (one-shot semantics), writes a
+ * pending(re_enroll=true) flag, returns 1. Otherwise returns 0. Never
+ * fails closed — returns 0 on any I/O / parse / expiry condition. */
+static int recovery_code_matches(const char *user, const char *candidate) {
+    uint64_t expires = 0;
+    char *phc = NULL;
+    if (read_recovery_file(user, &expires, &phc) != 0) return 0;
+
+    int ok = 0;
+    if ((uint64_t)time(NULL) <= expires) {
+        if (argon2_verify(phc, candidate, strlen(candidate), Argon2_id) == ARGON2_OK) {
+            ok = 1;
+        }
+    }
+
+    free(phc);
+    if (ok) {
+        char path[1024];
+        int n = snprintf(path, sizeof(path), "%s%s", RECOVERY_DIR, user);
+        if (n > 0 && (size_t)n < sizeof(path)) {
+            unlink(path);
+        }
+        write_pending_re_enroll(user);
+    }
+    return ok;
+}
+
 PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
                                    int argc, const char **argv) {
-    (void)flags; (void)argc; (void)argv;
+    (void)flags;
+
+    int recovery_mode = 0;
+    for (int i = 0; i < argc; i++) {
+        if (strcmp(argv[i], "mode=recovery") == 0) {
+            recovery_mode = 1;
+            break;
+        }
+    }

    const char *user = NULL;
    if (pam_get_user(pamh, &user, NULL) != PAM_SUCCESS || user == NULL) {
        pam_syslog(pamh, LOG_ERR, "authforge_pending: pam_get_user failed");
-        return PAM_AUTH_ERR;
+        return recovery_mode ? PAM_IGNORE : PAM_AUTH_ERR;
    }
    if (!username_is_safe(user)) {
        pam_syslog(pamh, LOG_ERR, "authforge_pending: rejected unsafe username");
-        return PAM_AUTH_ERR;
+        return recovery_mode ? PAM_IGNORE : PAM_AUTH_ERR;
+    }
+
+    if (recovery_mode) {
+        const char *authtok = NULL;
+        if (pam_get_authtok(pamh, PAM_AUTHTOK, &authtok, NULL) != PAM_SUCCESS
+            || authtok == NULL) {
+            return PAM_IGNORE;
+        }
+        if (recovery_code_matches(user, authtok)) {
+            pam_syslog(pamh, LOG_INFO,
+                       "authforge_pending: recovery code accepted for %s", user);
+            return PAM_SUCCESS;
+        }
+        return PAM_IGNORE; /* let pam_unix / pam_u2f handle */
    }

    int present = pending_flag_present(user);