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 Waylandext-session-lock-v1display 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 usinglimes-lockfor PAM-backed unlock authentication.examples/simple-greet: minimal iced greeter usinglimes-loginfor 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:
- Build a
LoginRuntimefrom environment/config withlimes_login::LoginRuntime::from_env(). - Collect a username and password in the frontend UI. Arbitrary interactive PAM challenges, MFA, and password changes are not currently supported.
- Create an
AuthRequestwithusername,password, and optionaltty. - Call
runtime.authenticate(&request), then clear the secret withrequest.clear_secret(). - On success, move the returned
AuthenticatedLoginintoruntime.start_session_for(authenticated)orruntime.start_session_for_with_command(authenticated, command). This capability is not cloneable: one authentication can launch only one session. - Keep the returned mutable
limes_login::SessionHandleand callhandle.wait_with_cleanup(). AnErrmeans waiting failed and the child may still be alive; retain the handle and retry. AnOk(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:
- Build a
LockRuntimewithlimes_lock::LockRuntime::from_env(). - Call
runtime.lock_now()whenlimes-lockowns the display lock. - Render the locked UI and collect unlock credentials.
- 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:
For a minimal greeter and same-user session-launch smoke test:
LIMES_SESSIONS='Smoke test=/bin/true'
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:
Development
Use nix develop when the Rust toolchain or PAM development libraries are not
already available.
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::authenticatereturnsAuthenticatedLogin, notAuthSuccess. Read display metadata withauthenticated.identity(); pass the capability by value to the session-start method.- Custom login backends implement
AuthSessionand return an owned transaction; there is no global authentication-session ID to open or close later. - Import the owning
SessionHandlefromlimes-login. Keep it mutable for waiting and termination. UseSessionInfofromlimes-protoonly 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_sessionmethod. They must complete their transaction cleanup before reporting success. - Use
LockRuntime::for_frontend_from_env()for toolkit-owned locking;authenticate_unlockrejects a backend-owned runtime. Useruntime.state()to query backend-owned display state. LockState::Unknownmeans 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 reportUnknownfor 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.