nevaforget/moonlock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: translate CLAUDE.md to English

Browse Source 
Per the committed=English rule.
This commit is contained in:
nevaforget
2026-06-16 10:46:13 +02:00
parent 37309ec566
commit baae17e1d8
1 changed files with 43 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+43 -43
View File
@@ -1,63 +1,63 @@
# Moonlock # Moonlock
## Projekt ## Project
Moonlock ist ein sicherer Wayland-Lockscreen, gebaut mit Rust + gtk4-rs + ext-session-lock-v1. Moonlock is a secure Wayland lockscreen, built with Rust + gtk4-rs + ext-session-lock-v1.
Teil des Moonarch-Ökosystems. Part of the Moonarch ecosystem.
## Tech-Stack ## Tech Stack
- Rust (Edition 2024), gtk4-rs 0.11, glib 0.22 - Rust (edition 2024), gtk4-rs 0.11, glib 0.22
- gtk4-session-lock 0.4 für ext-session-lock-v1 Protokoll - gtk4-session-lock 0.4 for the ext-session-lock-v1 protocol
- PAM-Authentifizierung via Raw FFI (libc, libpam.so) - PAM authentication via raw FFI (libc, libpam.so)
- fprintd D-Bus Integration (gio::DBusProxy) für Fingerabdruck-Unlock - fprintd D-Bus integration (gio::DBusProxy) for fingerprint unlock
- zeroize für sicheres Passwort-Wiping - zeroize for secure password wiping
- `cargo test` für Unit-Tests - `cargo test` for unit tests
## Projektstruktur ## Project Structure
- `src/` — Rust-Quellcode (main.rs, lockscreen.rs, auth.rs, fingerprint.rs, config.rs, i18n.rs, users.rs, power.rs) - `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) - `resources/` — GResource assets (style.css, default-avatar.svg)
- `config/` — PAM-Konfiguration und Beispiel-Config - `config/` — PAM configuration and example config
## Kommandos ## Commands
```bash ```bash
# Tests ausführen # Run tests
cargo test cargo test
# Release-Build # Release build
cargo build --release cargo build --release
# Lockscreen starten (zum Testen) # Start the lockscreen (for testing)
LD_PRELOAD=/usr/lib/libgtk4-layer-shell.so ./target/release/moonlock LD_PRELOAD=/usr/lib/libgtk4-layer-shell.so ./target/release/moonlock
``` ```
## Architektur ## Architecture
- `auth.rs` — PAM-Authentifizierung via Raw FFI (unsafe extern "C" conv callback, msg_style-aware, Zeroizing<CString>) - `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() für sauberen D-Bus-Lifecycle, running_flag für Race-Safety in async restarts, on_exhausted callback after MAX_FP_ATTEMPTS, resume_async() für Neustart nach transientem Fehler (mit failed_attempts-Reset und Signal-Handler-Cleanup) - `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` — Aktuellen User via nix getuid, Avatar-Loading mit Symlink-Rejection - `users.rs` — current user via nix getuid, avatar loading with symlink rejection
- `power.rs` — Reboot/Shutdown via /usr/bin/systemctl - `power.rs` — reboot/shutdown via /usr/bin/systemctl
- `i18n.rs` — Locale-Erkennung (OnceLock-cached) und String-Tabellen (DE/EN), faillock_warning mit konfigurierbarem max_attempts - `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 als Option<bool>) + Wallpaper-Fallback + Symlink-Rejection via symlink_metadata + Parse-Error-Logging - `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 mit 30s Timeout und Generation Counter, FP-Success ruft unlock_callback direkt (PAM-Stack ohne account-Modul, Lockout via auth-Pfad und MAX_FP_ATTEMPTS), Zeroizing<String> für Passwort, Power-Confirm, GPU-Blur via GskBlurNode (Downscale auf max 1920px), Blur/Avatar-Cache für Multi-Monitor - `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 (vor Logging), Root-Check, ext-session-lock-v1 (Pflicht in Release), Monitor-Hotplug via `connect_monitor`-Signal (v1_2), Unlock via `unlock()` + `connect_unlocked`→`app.quit()` (Lib zerstört die Lock-Fenster selbst beim Lock-Ende — kein eigenes Destroy/quit, sonst Double-Destroy-SIGSEGV), shared Blur/Avatar-Caches in Rc, systemd-Journal-Logging, Debug-Level per `MOONLOCK_DEBUG` Env-Var, async fprintd-Init nach window.present() - `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()
## Sicherheit ## Security
- ext-session-lock-v1 garantiert: Compositor sperrt alle Surfaces bei lock() - ext-session-lock-v1 guarantees: the compositor locks all surfaces on lock()
- Release-Build: Ohne ext-session-lock-v1 wird `exit(1)` aufgerufen — kein Fenster-Fallback - Release build: without ext-session-lock-v1, `exit(1)` is called — no window fallback
- Panic-Hook: Bei Crash wird geloggt, aber NIEMALS unlock() aufgerufen — Screen bleibt schwarz. Hook wird vor Logging installiert. - 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 (Passwort nur bei PAM_PROMPT_ECHO_OFF), strdup-OOM-sicher, num_msg-Guard gegen negative Werte - PAM callback: msg_style-aware (password only on PAM_PROMPT_ECHO_OFF), strdup-OOM-safe, num_msg guard against negative values
- fprintd: D-Bus Signal-Sender wird gegen fprintd's unique bus name validiert (Anti-Spoofing) - fprintd: the D-Bus signal sender is validated against fprintd's unique bus name (anti-spoofing)
- Passwort: Zeroizing<String> ab GTK-Entry-Extraktion, Zeroizing<CString> im PAM-FFI-Layer (bekannte Einschränkung: GLib-GString und strdup-Kopie in PAM werden nicht gezeroized — inhärente GTK/libc-Limitierung) - 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: ruft unlock_callback direkt nach verify-match (kein zusätzlicher PAM-acct-Check, weil PAM-Stack nur `auth include login` enthält — wie swaylock); FP-Lockout ist über MAX_FP_ATTEMPTS in fingerprint.rs umgesetzt - 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: nur `auth include login` (Standard-Pattern wie swaylock/gtklock); kein `account`/`session`-Stack, weil Lockscreen keinen Session-Lifecycle managed und `pam_unix(account)` setuid root benötigt - 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
- Wallpaper wird vor lock() geladen — connect_monitor feuert während lock() und braucht die Textur; lokales JPEG-Laden ist schnell genug - The wallpaper is loaded before lock() — connect_monitor fires during lock() and needs the texture; local JPEG loading is fast enough
- PAM-Timeout: 30s Timeout verhindert permanentes Aussperren bei hängenden PAM-Modulen, Generation Counter verhindert Interferenz paralleler Auth-Versuche - PAM timeout: a 30s timeout prevents permanent lockout when PAM modules hang, the generation counter prevents interference from parallel auth attempts
- Root-Check: Exit mit Fehler wenn als root gestartet - Root check: exits with an error if started as root
- Faillock: UI-Warnung nach 3 Fehlversuchen, aber PAM entscheidet über Lockout (Entry bleibt aktiv) - Faillock: UI warning after 3 failed attempts, but PAM decides on lockout (the entry stays active)
- Kein Schließen per Escape/Alt-F4 — nur durch erfolgreiche PAM-Auth oder Fingerprint - No closing via Escape/Alt-F4 — only via successful PAM auth or fingerprint
- Peek-Icon am Passwortfeld aktiv (UX-Entscheidung, konsistent mit moongreet) - Peek icon on the password field active (UX decision, consistent with moongreet)
- GResource-Bundle: CSS/Assets in der Binary kompiliert - GResource bundle: CSS/assets compiled into the binary