# latchd

Want a TUI-based login manager because you are tired of GDM or Plasma Login? Latchd puts a small, keyboard-driven login screen on a Linux virtual terminal. It uses PAM for authentication and can start a TTY shell, an X11 desktop, or a Wayland desktop.

Latchd is written in Rust. The old Go prototype remains in `legacy/go/` for reference. It is not part of the release build.

![Latchd login screen](docs/images/latchd-preview.png)

The image above is the preview screen. It was captured from the Docker test image. See [`docs/ui.md`](docs/ui.md) for the keyboard reference and the second screenshot.

## Features

- Discovers normal login accounts through NSS.
- Shows account expiry, locked-account, and faillock status before login.
- Lets PAM handle authentication and password changes.
- Switches between users and sessions from the same screen.
- Finds X11 and Wayland desktop entries from configured directories.
- Can offer a TTY shell as a session choice.
- Starts the selected session with a restricted environment and the correct user ID.
- Passes the selected session, seat, and virtual terminal to PAM and logind.
- Imports approved values from PAM into the session environment.
- Writes UTMPX records when the platform supports them.
- Provides filtering, keyboard help, refresh, notifications, wallpaper, and reduced-motion controls.
- Has a preview mode for UI work and configuration checks.

The service needs Linux PAM and a virtual terminal. X11 and Wayland sessions also need their own display server, compositor, and desktop files. Docker covers the parts that do not require those host services. The remaining checks must run on a prepared machine or VM.

## Requirements

Builds use Rust 1.88 and the system PAM development files. On Debian or Ubuntu:

```sh
sudo apt-get install build-essential pkg-config libpam0g-dev libpam-modules
```

The repository includes the required `rustfmt` and `clippy` components in `rust-toolchain.toml`.

## Build and run

Run the local verification gate and build the release binary:

```sh
make check
make build
```

The binary is written to `build/latchd`. To open the non-authenticating preview:

```sh
make run-preview
# or
./build/latchd --preview --no-log
```

Preview mode does not contact PAM, start a user session, or run power actions. It is safe to use while changing the layout or configuration.

For terminals with limited character support, set `LATCHD_ASCII=1`. Set `NO_COLOR=1` for plain output. Set `LATCHD_HIGH_CONTRAST=1` for a stronger focus colour.

## Configuration

The example file is [`extra/config.toml`](extra/config.toml). Latchd uses separate paths for a system service and a local preview:

- A root service reads `/etc/latchd/config.toml`.
- Preview mode first checks `$XDG_CONFIG_HOME/latchd/config.toml`.
- If `XDG_CONFIG_HOME` is not set, preview mode checks `~/.config/latchd/config.toml`.
- `--config PATH` selects a file explicitly and takes precedence over the defaults.

Create the user file from the example:

```sh
make install-user
./build/latchd --preview --no-log
```

`make install-user` creates `~/.config/latchd/` with mode `700` and creates `config.toml` with mode `600`. It does not replace an existing file. Set `USER_CONFIG_HOME=/path` or `XDG_CONFIG_HOME=/path` when the file must be stored elsewhere.

The main sections in the example are:

- `[accounts]` for NSS discovery, faillock, and account-age checks.
- `[x11]` and `[wayland]` for desktop-entry and administrator script directories.
- `[environment_switcher]` for session choices and the last-session preference file.
- `[visual]` for wallpaper, animation, notification, and reduced-motion settings.
- `[power_controls]` for confirmed power commands. Latchd starts these programs directly; it does not use a shell.

Keep the system file owned by root and unwritable by group or other users. Do not put passwords or other secrets in command-line arguments.

## Install on a test machine

Use a disposable machine first. Keep another login path available while changing the display manager.

```sh
sudo make install
sudo systemctl enable latchd.service
```

This installs:

- `/usr/bin/latchd`
- `/etc/latchd/config.toml`
- `/etc/pam.d/latchd`
- `/usr/lib/systemd/system/latchd.service`

The supplied service uses `/dev/tty2`. If you choose another VT, change both the `tty` value in the config and `TTYPath` in the systemd unit. Stop or disable the existing display manager before enabling latchd on the same terminal.

## Keyboard controls

| Key | Action |
| --- | --- |
| Tab / Shift-Tab | Move focus |
| Up / Down | Move focus or move in a filtered list |
| Left / Right | Change the selected session |
| `/` | Filter sessions or accounts |
| Ctrl-R | Refresh account and session discovery |
| Ctrl-N / Ctrl-P | Select the next or previous account |
| Ctrl-B | Toggle wallpaper and ambient effects |
| Ctrl-M | Toggle reduced motion |
| Enter | Authenticate or submit a PAM password change |
| Esc | Clear the password or close a popup |
| `?` | Show keyboard help |
| Ctrl-C | Restore the terminal and quit |
| F1–F12 | Confirm a configured power action |

Lowercase filters ignore case. A filter with an uppercase letter is case-sensitive. The status line can show account and faillock information before login.

## Testing

Run the local checks with these commands:

```sh
make check
make integration-test
make docker-test
make system-e2e
```

Run `make audit` after you install `cargo-audit`. Run `make pam-fixture-test` as root. The PAM fixture command creates temporary policies and removes them when it exits.

`make system-e2e` checks the PAM library, faillock, virtual terminal, X11, Wayland, and systemd-logind on the current host. It prints `PASS`, `SKIP`, or `FAIL`. A pseudo-terminal does not provide a virtual terminal. The check does not install a PAM policy or start systemd-logind.

Run the strict check in a disposable VM with a test PAM policy, a real VT, systemd-logind, and the X11 or Wayland stack you want to test:

```sh
make system-e2e-strict
```

See [`docs/e2e-testing.md`](docs/e2e-testing.md) for the test limits and VM setup.

## Security notes

- PAM handles stay on one worker thread.
- Password buffers are zeroized. Passwords are not written to argv, logs, or the TUI.
- Audit records contain the account and a stable result code. They do not contain PAM's free-form error text or password data.
- Session environments are rebuilt from an allowlist.
- Latchd checks desktop files, scripts, binaries, home directories, logs, and configuration files before use.
- Xauthority files and session logs use private permissions and cleanup guards.
- Power commands need confirmation and are disabled in preview mode.
- Account and faillock checks do not unlock accounts or bypass PAM.

## Project layout

```text
crates/latchd-core/  configuration, account discovery, sessions, and UTMPX
crates/latchd-auth/  PAM FFI, password changes, and the authentication worker
crates/latchd-tui/   Ratatui state, rendering, filtering, and effects
rust/main.rs         command-line entry point and service orchestration
extra/               example configuration, PAM policy, and systemd unit
scripts/             Docker, CLI, PAM, and system capability tests
legacy/go/           non-production Go reference
```

## Releases

GitLab CI runs formatting, tests, Clippy, rustdoc, RustSec checks, CLI tests, capability checks, and the Docker suite. A SemVer tag runs the package job and publishes a Linux archive with its SHA-256 file. The strict VT, PAM, X11, Wayland, and logind checks are separate because CI containers do not provide those host services.

Create a local package with:

```sh
make package
```

## License

Apache-2.0. See [`LICENSE`](LICENSE).