moonlock/CLAUDE.md

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

# 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)
• 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) + 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 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 from GTK entry extraction, Zeroizing 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