passless config

[HGBits]

How does the Passless setup work? What kind of permissions are required to function properly? As mentioned before on Discord, I have hardened machine configurations for security so I need to know exactly what is needed to adapt my setup and impose restrictions that make sense and the application does not have any documentation that explains this. I'm blindly trying to configure but, with permission errors.

[pando85]

Thanks for raising this. You are right: the permission/security model should be documented better. I’ll use this as the basis for a proper docs section.

Passless is not intended to run as root. The privileged part is only the initial system integration needed to let an unprivileged user create a virtual FIDO2 HID device through Linux UHID.

At runtime, the basic flow is:

1. passless runs as your normal user, normally through the user systemd service.
2. It opens /dev/uhid.
3. It creates a virtual FIDO2/WebAuthn authenticator.
4. The browser or WebAuthn client talks to that virtual authenticator.
5. Passless handles CTAP/FIDO2 requests and reads/writes credentials using the configured backend.

The required runtime permissions are:

/dev/uhid read/write access for the user running passless

The packaged udev rule is currently:

KERNEL=="uhid", GROUP="fido", MODE="0660"

So the expected setup is:

sudo modprobe uhid
echo uhid | sudo tee /etc/modules-load.d/fido.conf

sudo groupadd fido 2>/dev/null || true
sudo usermod -aG fido "$USER"

echo 'KERNEL=="uhid", GROUP="fido", MODE="0660"' | sudo tee /etc/udev/rules.d/90-passless.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Then log out and back in, or otherwise refresh your group membership, and verify:

id
ls -l /dev/uhid

You should see your user in the fido group and /dev/uhid owned by root:fido with 0660 permissions.

What Passless does not need at runtime:

root
sudo
access to arbitrary input devices
access to physical security keys
access to all hidraw devices
network access, unless your password-store git remote sync needs it

Depending on your browser and distro, there is one separate browser-side detail: the browser must be allowed to access FIDO/HID devices. For normal non-sandboxed browsers this is usually handled by the desktop/session/udev stack. For sandboxed browsers, for example Snap/Flatpak-style installs, access may be blocked even when Passless itself is working. In that case you may need credentialsd or equivalent sandbox integration.

For the default pass backend, Passless also needs access to:

~/.password-store
~/.password-store/.gpg-id
your GPG setup / gpg-agent
git, only if the password-store is a git repository with sync enabled

By default it stores credentials under the configured path inside the password store, currently fido2, and encrypts entries with GPG. It may also run git operations for the password store: pull before loading and commit/push after write/delete if the store is configured that way. Git failures should not prevent the credential operation, but they can show up as warnings.

For a hardened AppArmor/SELinux/bubblewrap setup, the useful allowlist is roughly:

rw: /dev/uhid
r:  ~/.config/passless/config.toml
rw: ~/.password-store/**              # pass backend
rw: ~/.local/share/passless/**        # local or tpm backend paths
rw: ~/.gnupg/** and gpg-agent socket  # pass backend
x:  gpg / git as needed               # pass backend
rw: /dev/tpmrm0 or configured TCTI    # TPM backend only
session D-Bus notifications           # notification-based approval / first-run prompts

The user systemd service also applies some hardening:

NoNewPrivileges=true
LimitMEMLOCK=2M

Passless itself tries to disable core dumps and probes mlock. If mlock fails, it should warn rather than fail. For stricter hardening you can grant the binary CAP_IPC_LOCK, but that is optional and only affects whether sensitive memory can be locked:

sudo setcap cap_ipc_lock=+ep "$(command -v passless)"

A minimal config can be generated with:

mkdir -p ~/.config/passless
passless config print > ~/.config/passless/config.toml

For a stricter configuration, I recommend setting a PIN and requiring PIN-based user verification:

backend_type = "pass"

[pass]
store_path = "/home/YOUR_USER/.password-store"
path = "fido2"
gpg_backend = "gnupg-bin"

[security]
check_mlock = true
disable_core_dumps = true
always_uv = true

[pin]
enforcement = "required"
min_length = 4
max_retries = 8

Useful debugging commands:

lsmod | grep uhid
ls -l /dev/uhid
id
systemctl --user status passless
journalctl --user -u passless -f
passless --verbose

Typical failure mapping:

Failed to create UHID device
→ uhid module missing or /dev/uhid permissions are wrong.

Failed to show notification
→ desktop notification/session D-Bus is blocked or unavailable.

GPG decrypt/encrypt errors
→ password-store, .gpg-id, GPG key, or gpg-agent issue.

Browser does not see the authenticator
→ browser sandbox / hidraw / credentialsd integration issue.

So the smallest required permission for Passless itself is /dev/uhid read/write for the user running it. Everything else depends on the selected storage backend and desktop/browser integration.

[HGBits]

Feedback on v0.12.0 + bug reports from extended testing

Thanks for the quick turnaround on v0.12.0 — the uv-reset feature worked and unblocked my setup. Here's consolidated feedback from several days of testing, including some issues worth documenting or fixing.

---

What works well

• client pin uv-reset successfully resets UV retries without touching credentials ✅
• The systemd user service now starts cleanly without 216/GROUP errors after the PATH fix in fix: add user directories to PATH in systemd service #278 ✅
• pass backend with gnupg-bin is stable once the environment is correct ✅

---

Issue 1: uv_retries ceiling is 3, not 8 — too low for normal use

Behavior: After uv-reset, uv_retries resets to 3 (while pin retries resets to 8). With always_uv = true, each authentication attempt consumes one UV retry. Three retries are exhausted quickly across normal daily use without any warning.

Expected: Either a higher default ceiling for uv_retries, or a warning when the counter is low (e.g. 1 remaining), or documentation clarifying that uv-reset is expected to be run regularly as part of normal operation.

Impact: uv_retries silently reaches 0, daemon stops prompting for PIN/UV with no user-visible error. From the user's perspective, the passkey "randomly stops working".

---

Issue 2: No warning when uv_retries approaches zero

Related to Issue 1: when uv_retries hits 0, the authenticator silently falls back to notification-based UV (which times out in background systemd service context) instead of returning a clear error or logging a warning. A WARN log line like UV retries exhausted, falling back to notification would make this diagnosable without deep log inspection.

---

Issue 3: Two-daemon race condition corrupts pin_state

Context: After enabling the systemd user service (which now works correctly post-#278), I inadvertently had two passless processes running simultaneously — one via systemd and one started manually before the service was enabled.

Behavior: Both processes wrote to the same ~/.password-store/fido2/ concurrently. After ~14h, pin_state.gpg was corrupted (version field regressed, pin_hash missing), consistent with a last-write-wins race on GPG-encrypted files.

Suggestion: Document clearly that only one instance should run at a time, and consider adding a lock file or PID check at startup to detect and refuse to start if another instance is already running.

---

Environment

• Arch Linux, kernel zen 7.x
• Hyprland/Wayland
• pass backend with gnupg-bin
• always_uv = true, pin.enforcement = required
• systemd user service (enabled, persistent)

Happy to provide logs or test specific fixes. Thanks again for the fast response on the UV reset feature.

[HGBits]

I'm going to run some tests with xlibre in addition, to check behavior.

[pando85]

Great, I implemented those minor fixes and released 0.13.0.

If you find new issues I'm glad to fix them.

[HGBits]

Compatibility note: sandboxed Electron apps (Vesktop / Discord)

During testing, I found that Vesktop (an Electron-based Discord client with Vencord) fails to complete passkey registration even when Passless is working correctly. The same passkey flow works without issues on Discord's web interface.

The root cause appears to be Electron's sandbox model: Chromium-based sandboxed processes interact with HID/UHID devices differently than a regular browser, and certain Electron forks (particularly those that modify the security model, like Vesktop) may block or interfere with the WebAuthn flow before it reaches the authenticator.

This is not a Passless bug — the daemon responds correctly and the web client works fine. But it's a pattern that other users are likely to encounter with:

• Electron apps with modified sandbox configurations
• Snap or Flatpak packaged browsers/apps with strict confinement
• Any client that wraps Chromium with custom security policies

It might be worth adding a note to the documentation (perhaps in PERMISSIONS.md or a compatibility section) mentioning that passkey support depends on the client application's sandbox configuration, and that the web version of a service is a reliable fallback for testing whether an issue is with Passless or with the specific app packaging.

Also confirmed working correctly on both Wayland (Hyprland) and X11 (Bspwm/XLibre) with the same configuration, in case that's useful data.

[HGBits]

as all the main problems and derivatives have been solved I will close this discussion, if I find anything else in which I can be useful I will return.

Thank you very much for the corrections, at this moment almost all my applications are already with registered passkeys, I want to take the opportunity to warn you that I have put together a documentation on the arch wiki about the passless, I will just ask the staff to move to the main list of pages.

you can access here: https://wiki.archlinux.org/title/User:HG_Bits/My_new_subpage