# Moonlock

## Project

Moonlock is a secure Wayland lockscreen, built with Rust + gtk4-rs + ext-session-lock-v1.
Part of the Moonarch ecosystem.

## Tech Stack

- Rust (edition 2024), gtk4-rs 0.11, glib 0.22
- gtk4-session-lock 0.4 for the ext-session-lock-v1 protocol
- PAM authentication via raw FFI (libc, libpam.so)
- fprintd D-Bus integration (gio::DBusProxy) for fingerprint unlock
- zeroize for secure password wiping
- `cargo test` for unit tests

## Project Structure

- `src/` — Rust source code (main.rs, lockscreen.rs, auth.rs, fingerprint.rs, config.rs, i18n.rs, users.rs, power.rs)
- `resources/` — GResource assets (style.css, default-avatar.svg)
- `config/` — PAM configuration and example config

## Commands

```bash
# Run tests
cargo test

# Release build
cargo build --release

# Start the lockscreen (for testing)
LD_PRELOAD=/usr/lib/libgtk4-layer-shell.so ./target/release/moonlock
```

## Architecture

- `auth.rs` — PAM authentication via raw FFI (unsafe extern "C" conv callback, msg_style-aware, Zeroizing<CString>)
- `fingerprint.rs` — fprintd D-Bus listener, async init/claim/verify via gio futures, sender-validated signal handler, cleanup_dbus() for a clean D-Bus lifecycle, running_flag for race safety in async restarts, on_exhausted callback after MAX_FP_ATTEMPTS, resume_async() for restart after a transient error (with failed_attempts reset and signal handler cleanup)
- `users.rs` — current user via nix getuid, avatar loading with symlink rejection
- `power.rs` — reboot/shutdown via /usr/bin/systemctl
- `i18n.rs` — locale detection (OnceLock-cached) and string tables (DE/EN), faillock_warning with configurable max_attempts
- `config.rs` — TOML config (background_path, background_blur clamped [0,200], fingerprint_enabled as Option<bool>) + wallpaper fallback + symlink rejection via symlink_metadata + parse-error logging
- `lockscreen.rs` — GTK4 UI via LockscreenHandles, PAM auth via gio::spawn_blocking with a 30s timeout and generation counter, FP success calls unlock_callback directly (PAM stack without account module, lockout via the auth path and MAX_FP_ATTEMPTS), Zeroizing<String> for the password, power confirm, GPU blur via GskBlurNode (downscale to max 1920px), blur/avatar cache for multi-monitor
- `main.rs` — entry point, panic hook (before logging), root check, ext-session-lock-v1 (mandatory in release), monitor hotplug via the `connect_monitor` signal (v1_2), unlock via `unlock()` + `connect_unlocked`→`app.quit()` (the lib destroys the lock windows itself when the lock ends — no own destroy/quit, otherwise double-destroy SIGSEGV), shared blur/avatar caches in Rc, systemd journal logging, debug level via the `MOONLOCK_DEBUG` env var, async fprintd init after window.present()

## Security

- ext-session-lock-v1 guarantees: the compositor locks all surfaces on lock()
- Release build: without ext-session-lock-v1, `exit(1)` is called — no window fallback
- Panic hook: on a crash it logs, but NEVER calls unlock() — the screen stays black. The hook is installed before logging.
- PAM callback: msg_style-aware (password only on PAM_PROMPT_ECHO_OFF), strdup-OOM-safe, num_msg guard against negative values
- fprintd: the D-Bus signal sender is validated against fprintd's unique bus name (anti-spoofing)
- Password: Zeroizing<String> from GTK entry extraction, Zeroizing<CString> in the PAM FFI layer (known limitation: the GLib GString and the strdup copy in PAM are not zeroized — an inherent GTK/libc limitation)
- Fingerprint unlock: calls unlock_callback directly after a verify match (no additional PAM acct check, because the PAM stack contains only `auth include login` — like swaylock); FP lockout is implemented via MAX_FP_ATTEMPTS in fingerprint.rs
- PAM stack: only `auth include login` (standard pattern like swaylock/gtklock); no `account`/`session` stack, because the lockscreen does not manage a session lifecycle and `pam_unix(account)` requires setuid root
- The wallpaper is loaded before lock() — connect_monitor fires during lock() and needs the texture; local JPEG loading is fast enough
- PAM timeout: a 30s timeout prevents permanent lockout when PAM modules hang, the generation counter prevents interference from parallel auth attempts
- Root check: exits with an error if started as root
- Faillock: UI warning after 3 failed attempts, but PAM decides on lockout (the entry stays active)
- No closing via Escape/Alt-F4 — only via successful PAM auth or fingerprint
- Peek icon on the password field active (UX decision, consistent with moongreet)
- GResource bundle: CSS/assets compiled into the binary