limes-lock 0.3.0

Screenlock library for limes frontends.
Documentation

limes

Login manager and screenlock libraries for Rust frontends.

The project is split into focused crates so frontends can depend only on the backend pieces they need:

  • limes-common: shared PAM authentication, config, events, frontend launching, and error handling.
  • limes-lock: screenlock state, unlock authentication orchestration, and the Wayland ext-session-lock-v1 display backend.
  • limes-login: login authentication orchestration, PAM session open/close, user session launch, and session discovery.
  • limes-proto: lightweight shared types/events for frontends and backend code.
  • examples/simple-lock: minimal iced session-lock frontend using limes-lock for PAM-backed unlock authentication.
  • examples/simple-greet: minimal iced greeter using limes-login for authentication, session selection, launch, and logout cleanup.

The full-screen iced session-lock frontend that renders directly on Wayland ext-session-lock-v1 lock surfaces now lives in reimu_lays_on_water.

There is no bundled CLI. Applications and examples link to the crates directly instead of shelling out to a limes command.

Frontend integration

A login frontend should:

  1. Build a LoginRuntime from environment/config with limes_login::LoginRuntime::from_env().
  2. Collect a username and password in the frontend UI. Arbitrary interactive PAM challenges, MFA, and password changes are not currently supported.
  3. Create an AuthRequest with username, password, and optional tty.
  4. Call runtime.authenticate(&request), then clear the secret with request.clear_secret().
  5. On success, move the returned AuthenticatedLogin into runtime.start_session_for(authenticated) or runtime.start_session_for_with_command(authenticated, command). This capability is not cloneable: one authentication can launch only one session.
  6. Keep the returned mutable limes_login::SessionHandle and call handle.wait_with_cleanup(). An Err means waiting failed and the child may still be alive; retain the handle and retry. An Ok(SessionExit) confirms child exit and reports any PAM cleanup error separately. Subsequent waits return the cached exit instead of reaping or cleaning up again.

The session handle owns both the child and its PAM transaction, independently of the runtime. Dropping a live handle transfers it to a background reaper; normal applications should explicitly wait so cleanup errors remain observable. The process must stay alive for that reaper to finish. Process termination is not a supported cleanup mechanism.

AuthSuccess and SessionInfo in limes-proto are display metadata, not credentials or process-control handles. Authentication identity is held privately by AuthenticatedLogin, and session launch uses that canonical identity. Custom backends remain trusted code; these APIs are not an untrusted IPC boundary.

A lock frontend should either:

  1. Build a LockRuntime with limes_lock::LockRuntime::from_env().
  2. Call runtime.lock_now() when limes-lock owns the display lock.
  3. Render the locked UI and collect unlock credentials.
  4. Call runtime.unlock(&request), then clear the secret.

The backend-owned Wayland mode opens a dedicated connection using WAYLAND_DISPLAY and, for a relative display name, XDG_RUNTIME_DIR. It rejects WAYLAND_SOCKET: duplicating an inherited connection would share protocol state and prevent reliable disconnect-on-cancellation. Use frontend-owned mode when a toolkit owns the existing Wayland connection.

Or, if the frontend toolkit owns the Wayland ext-session-lock-v1 lock surfaces itself, construct LockRuntime::for_frontend_from_env() (or LockRuntime::for_frontend(config)), authenticate with runtime.authenticate_unlock(&request), clear the secret, and then ask the toolkit to release the compositor lock after success. This authentication-only operation does not claim that the display is unlocked; the frontend owns display-state confirmation. Do not mix frontend-owned and backend-owned lock lifecycles. Normal layer-shell surfaces are not visible while the session is locked.

Examples

Configure /etc/pam.d/limes before testing PAM-backed auth. Then run the local minimal lock API/authentication smoke test:

cargo run -p limes-simple-lock

For a minimal greeter and same-user session-launch smoke test:

LIMES_SESSIONS='Smoke test=/bin/true' cargo run -p limes-simple-greet

Choose Smoke test in the session picker (not an installed desktop session). See examples/simple-greet/README.md for PAM setup, session selection, and limitations. This is not a complete display manager: it requires an existing graphical server and does not manage seats or VTs. Do not run the GUI as root in your daily desktop to test multi-user login.

For a full-screen Wayland session-lock frontend, see reimu_lays_on_water.

Session choices are provided by limes-login from system .desktop files in wayland-sessions and xsessions. Extra backend session entries can be supplied with a semicolon-separated list:

export LIMES_SESSIONS='Lab Shell=/bin/sh;Sway=sway'

Development

Use nix develop when the Rust toolchain or PAM development libraries are not already available.

cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Unit tests and local mock-protocol tests do not replace a real PAM/compositor integration test. Validate distribution-specific PAM modules and full graphical session cleanup in a disposable VM, not by running the greeter as root inside a daily desktop.

API migration

Version 0.3.0 intentionally breaks token-based session ownership:

  • AuthBackend::authenticate returns AuthenticatedLogin, not AuthSuccess. Read display metadata with authenticated.identity(); pass the capability by value to the session-start method.
  • Custom login backends implement AuthSession and return an owned transaction; there is no global authentication-session ID to open or close later.
  • Import the owning SessionHandle from limes-login. Keep it mutable for waiting and termination. Use SessionInfo from limes-proto only for display metadata; a PID is not permission to control a process.
  • Custom process backends return a SessionProcess, rather than separating process creation from operations on caller-provided PID handles.
  • Lock-only backends implement authentication without a close_session method. They must complete their transaction cleanup before reporting success.
  • Use LockRuntime::for_frontend_from_env() for toolkit-owned locking; authenticate_unlock rejects a backend-owned runtime. Use runtime.state() to query backend-owned display state.
  • LockState::Unknown means the backend cannot confirm display state. It must not be treated as either permission to unlock or proof that locking succeeded. Authentication-only runtimes always report Unknown for display state.

Acknowledgements

The direct PAM login/session flow is informed by Ly: pam_start, PAM_TTY, pam_authenticate, pam_acct_mgmt, pam_setcred, pam_open_session, PAM environment import, user context switch, and parent-side session waiting/cleanup. Each authentication owns a separate PAM transaction; abandoned authentication capabilities clean up their own transaction, without invalidating another challenge. Successful session launch moves that ownership into the session handle until confirmed child exit. PAM cleanup is explicit and fallible, with drop-time cleanup as a fallback. The lock authentication path follows swaylock's model of a small PAM conversation that answers password prompts and maps PAM errors into frontend-renderable failures.