gtk-ahfail/docs/plans/2026-05-05-pam-rewrite-design.md

# Design: PAM module + cross-platform support

**Date:** 2026-05-05
**Status:** Approved

## Problem

`ahfail-module.so` is a gtklock-specific plugin. It works only on Wayland via gtklock. The goal is to also support X11 Linux lock screens and macOS, while keeping the existing Wayland/gtklock integration intact.

## Decision: Approach A — Two integration points, shared core

Keep the gtklock module for Wayland. Add a PAM module for X11 Linux and macOS. Share all display/audio/update logic through a common `ahfail-ui` crate.

| Platform | Lock screen | Integration | Display |
|----------|------------|-------------|---------|
| Wayland | gtklock | `ahfail-module.so` (gtklock module, kept) | inline GTK overlay via `ahfail-ui` |
| X11 Linux | any PAM locker (i3lock, xscreensaver…) | `ahfail-pam.so` | `ahfail-display` binary via `ahfail-ui` |
| macOS | loginwindow / screensaver | `ahfail-pam.so` | `ahfail-display` binary via `ahfail-ui` |

macOS CI is out of scope — users build from source via Homebrew. Linux x86_64 release binaries are produced by Gitea Actions.

---

## Cargo workspace layout

```
ahfail/
├── Cargo.toml                  ← workspace root
├── meson.build                 ← updated for new crate layout
├── crates/
│   ├── ahfail-gtklock/         → ahfail-module.so  (existing module, moved)
│   ├── ahfail-pam/             → ahfail-pam.so     (new)
│   ├── ahfail-display/         → ahfail-display    (new binary)
│   └── ahfail-ui/              → lib               (shared display/audio/update logic)
├── assets/                     ← unchanged
├── include/                    ← unchanged
└── .gitea/workflows/
    ├── test.yml
    └── release.yml
```

**Dependency graph:**
- `ahfail-gtklock` → `ahfail-ui`
- `ahfail-display` → `ahfail-ui`
- `ahfail-pam` → nothing (no GTK/GStreamer; minimal by design)

---

## Section 1: `ahfail-ui` (shared crate)

Contains everything that `ahfail-gtklock` and `ahfail-display` share:

- Animation loading (GResources → `PixbufSimpleAnim`, `set_loop(true)`)
- GTK display: `show_animation_on_overlay(overlay, monitor, deadzone)` — works for both an in-process gtklock overlay and a standalone window
- GStreamer audio playback (player pool, seek-to-0 on end-of-stream loop)
- Deadzone logic (random placement with retry, `--deadzone=x,y,w,h`)
- Update check (see below)
- System volume save/restore (`pactl` on Linux, `osascript` on macOS)

---

## Section 2: PAM module (`ahfail-pam`)

A minimal C-ABI shared library. No GTK. No GStreamer. No credential handling.

**Security principle:** we never touch `PAM_AUTHTOK` or any credential. All authentication is performed exclusively by the native host (pam_unix, pam_opendirectory, etc.). We are a pure side-effect observer.

**`pam_sm_authenticate`:**
1. Register a cleanup function via `pam_set_data(pamh, "ahfail", …, cleanup_fn)`
2. Return `PAM_IGNORE`

All other `pam_sm_*` functions return `PAM_IGNORE`.

**Cleanup function fires in two cases:**

| `error_status` | Meaning | Action |
|---------------|---------|--------|
| `PAM_DATA_REPLACE` set | `pam_sm_authenticate` called again (previous attempt failed, same handle) | spawn `ahfail-display` |
| `PAM_AUTH_ERR` (no replace) | final failure from `pam_end()` | spawn `ahfail-display` |
| `PAM_SUCCESS` (no replace) | auth succeeded from `pam_end()` | `pkill -SIGTERM ahfail-display`; restore volume via state file |

This handles both lock screens that loop `pam_authenticate()` on one handle and those that create a fresh PAM transaction per attempt.

**Finding `ahfail-display`:** compile-time default path (`/usr/lib/ahfail/ahfail-display` on Linux, `/usr/local/lib/ahfail/ahfail-display` on macOS), overridable via PAM argument `display_path=/custom/path`.

**PAM config lines:**
```
# Linux — /etc/pam.d/gtklock (or i3lock, xscreensaver, etc.)
auth optional ahfail-pam.so

# macOS — /etc/pam.d/screensaver
auth optional ahfail-pam.so display_path=/usr/local/lib/ahfail/ahfail-display
```

---

## Section 3: Display binary (`ahfail-display`)

Spawned by `ahfail-pam.so` via double-fork (fully detached). Uses `ahfail-ui` for all rendering.

**Startup sequence:**
1. Initialise GTK + GStreamer
2. Register GResources (same embedded assets as gtklock module)
3. Acquire volume lock: atomically create `$XDG_RUNTIME_DIR/ahfail.lock`
   - If created (first instance): save current volume/mute state into the file, set system volume to 100% unmuted
   - If already exists: skip volume management
4. Open floating, decoration-free, always-on-top GTK window
5. Call `ahfail-ui::show_animation_on_overlay(...)` — places Nedry at random position respecting `--deadzone`
6. Loop animation (`PixbufSimpleAnim`, `set_loop(true)`) and audio (GStreamer, seek-to-0 on end-of-stream)
7. Concurrently: run update check in a background thread (see below)
8. Block on GTK main loop until `SIGTERM` or 15-minute failsafe timeout

**On `SIGTERM` (clean exit):**
- If holding volume lock: restore volume/mute state from lock file, delete lock file
- Exit

**Multiple instances:** each failed attempt spawns one additional `ahfail-display`. Each shows one Nedry sprite independently. Only the first instance (lock file holder) manages volume. On success, `pkill -SIGTERM ahfail-display` terminates all instances simultaneously.

**Volume control:**
- Linux: `pactl set-sink-mute @DEFAULT_SINK@ 0 && pactl set-sink-volume @DEFAULT_SINK@ 100%`
- macOS: `osascript -e 'set volume output volume 100 without output muted'`
- Restore: reverse using saved state from lock file

**Update check (background thread):**
- Calls `https://gitea.weircon.dk/api/v1/repos/agw/gtk-ahfail/releases/latest`, parses `tag_name`
- Rate-limited: skips network call if `~/.cache/ahfail/last_update_check` was written within 24 hours
- If newer version found: fires desktop notification
  - Linux: `notify-send "ahfail" "Update available — visit https://gitea.weircon.dk/agw/gtk-ahfail/releases"`
  - macOS: `osascript -e 'display notification "..." with title "ahfail"'`
- Fails silently on any error (no network, bad response, parse failure)

---

## Section 4: gtklock module (`ahfail-gtklock`)

The existing module, moved to `crates/ahfail-gtklock/`. Integration mechanism is unchanged.

**Changes from current `src/`:**
- Display/audio logic extracted into `ahfail-ui`; module calls `ahfail-ui` functions instead of implementing them inline
- Volume: on first `error_label` signal (first failure), acquire volume lock and set to 100%. On `on_window_destroy`, restore volume.
- Update check: called from `ahfail-ui` on each failure (same shared code path as display binary)
- Multiple Nerdys on multiple failures: unchanged — each `error_label` signal adds a new sprite to the overlay

---

## Section 5: Gitea CI/CD

**`.gitea/workflows/test.yml`** — on push and pull request:
```
deps: libgtk-3-dev libgstreamer1.0-dev gstreamer-plugins-base libpam0g-dev
→ cargo test
→ meson setup builddir && meson compile -C builddir
→ meson test -C builddir
```

**`.gitea/workflows/release.yml`** — on `v*` tag push:
```
→ same build with --buildtype=release
→ bundle into ahfail-linux-x86_64.tar.gz:
    ahfail-module.so   (gtklock/Wayland)
    ahfail-pam.so      (PAM/X11+macOS)
    ahfail-display     (display binary)
→ create Gitea release + upload asset via curl to Gitea API
   using GITEA_TOKEN secret
```

**macOS:** no CI. README documents:
```bash
brew install gtk+3 gstreamer gst-plugins-good gst-plugins-base
cargo build --release
meson setup builddir && meson compile -C builddir
```

---

## Out of scope

- macOS CI / cross-compilation (SDK licensing + native dep complexity)
- Supporting Wayland compositors other than gtklock (protocol blocks external surfaces during lock)
- Auto-installing updates (notification only)