Quattro lock screen: support FIDO2/YubiKey unlock

[jacobaross]

What I'd like

Allow Quattro's Quickshell lock screen to unlock with an FIDO2/YubiKey registered through omarchy setup security fido2, alongside the existing fingerprint and password methods.

Current behavior

• omarchy setup security fido2 installs pam-u2f and registers the key in /etc/fido2/fido2.
• It configures FIDO2 authentication for sudo and polkit, where the key continues to work.
• Quattro's lock screen uses the separate PAM services omarchy-lock-password and omarchy-lock-fingerprint; neither invokes pam_u2f.
• Consequently, a correctly detected and registered YubiKey does nothing at the Quattro lock screen.
• Before upgrading from 3.8.4, a pam_u2f entry in the Hyprlock PAM stack allowed the same key to unlock the laptop. Quattro replaced Hyprlock, so that integration path no longer applies.

Suggested behavior

• Add a supported FIDO2 authentication flow to the Quattro lock screen, ideally with its own PAM service (for example, omarchy-lock-fido2) rather than coupling it to the password or fingerprint stack.
• Have omarchy setup security fido2 enable that flow when a key is registered.
• Have omarchy remove security fido2 remove it cleanly.
• Ensure omarchy apply lock regenerates/preserves the supported FIDO2 configuration, so users do not need an update-fragile local PAM patch.
• Keep fingerprint and password fallback behavior unchanged.

Environment

• Omarchy 4.0.0-1, upgraded from 3.8.4
• Yubico YubiKey FIDO (1050:0402)
• pam-u2f 1.4.0-2
• libfido2 1.17.0-1
• Fingerprint authentication is also configured and working

The YubiKey enumerates normally and the existing registration is intact; the missing piece is specifically the new Quattro lock-screen authentication flow.

[wmauz677]

I'd like to contribute FIDO2 (YubiKey / security key) unlock support for the Quattro lock screen, and before opening a PR I want to check direction and a few design decisions with maintainers. I've gone through the current quattro code (lock plugin, omarchy-apply-lock, the omarchy setup security fido2 scripts, and the migration/upgrade paths), so each question below comes with my current read and -- where I have one -- a suggestion.

flowchart LR
    LOCK([Locked]) --> PW[Password]
    LOCK --> FP[Fingerprint]
    LOCK -.-> KEY[Security key]
    PW --> PAM{PAM}
    FP --> PAM
    KEY -.-> PAM
    PAM -->|success| UNLOCK([Unlocked])

    classDef proposed stroke-dasharray: 6 4;
    class KEY proposed;

Loading

The two questions that gate everything:

1. Would FIDO2 lock-screen unlock be accepted upstream at all?

My take: this is really about restoring a capability that was effectively available before Omarchy 4. Under Omarchy 3 the lock screen was Hyprlock, which authenticates through the standard hyprlock PAM service (auth include system-auth on Arch). Omarchy never wired FIDO2 into it directly — omarchy setup security fido2 has always only touched sudo and polkit-1 — but because Hyprlock consumed a standard PAM stack, anyone who had registered a key could enable key unlock with a one-line addition to /etc/pam.d/hyprlock. The Quattro Quickshell lock instead uses dedicated, Omarchy-generated services (omarchy-lock-password, omarchy-lock-fingerprint) that deliberately don't include system-auth, so that avenue is gone. I'd like to bring it back as a first-class, supported feature rather than a manual PAM edit.

2. Dedicated PAM service, or fold pam_u2f into omarchy-lock-password?

My take: a dedicated /etc/pam.d/omarchy-lock-fido2, mirroring the existing password/fingerprint split. The lock service already runs one PamContext per method in parallel, so a third service slots straight into the existing architecture. Keeping hardware-token auth out of the password service means a missing or misbehaving key can never delay or degrade typing a password; enabling/disabling the feature becomes creating/deleting one file (exactly how fingerprint works today); and omarchy-apply-lock already has the conditional write/remove pattern to extend. Folding pam_u2f into omarchy-lock-password would make the password service secretly perform hardware-token detection on every unlock attempt, which is harder to reason about and harder to turn off independently.

Each path is independent: a failure or absent factor on one never blocks the others (fingerprint failures silently retry; FIDO2 with no key present idles on a cheap device probe). The dashed path is the proposed addition; the other two exist today.

Remaining design questions (3–12): UX, enrollment, permissions, migration, faillock, PIN keys, SDDM, testing

flowchart TD
    LOCK["Quickshell lock screen<br/>shell/plugins/lock/Service.qml"]

    LOCK -->|"password submitted"| P1["PamContext<br/>(per attempt)"]
    LOCK -->|"always armed while locked"| P2["PamContext<br/>(retry loop)"]
    LOCK -->|"always armed while locked"| P3["PamContext<br/>(retry loop)"]

    P1 --> S1["/etc/pam.d/omarchy-lock-password<br/>pam_unix + pam_faillock"]
    P2 --> S2["/etc/pam.d/omarchy-lock-fingerprint<br/>pam_fprintd"]
    P3 --> S3["/etc/pam.d/omarchy-lock-fido2<br/>pam_u2f · authfile=/etc/fido2/fido2"]

    S1 -->|"PamResult.Success"| U(["finishUnlock()"])
    S2 -->|"PamResult.Success"| U
    S3 -->|"PamResult.Success"| U

    classDef proposed stroke-dasharray: 6 4;
    class P3,S3 proposed;

Loading

3. UX model

Is fingerprint-style always-armed parallel authentication the right model — i.e. while locked you can touch your key at any time, with no menu or mode selection, and password/fingerprint remain fully usable alongside?

4. Indicator and touch cue

Is a static key glyph next to the existing fingerprint icon the right presentation? And is there any appetite for the lock screen displaying PAM conversation messages ("touch your security key"), or should it stay message-free like today? (If message-free, the lock's pam_u2f stack should drop the cue option, since nothing would render it.)

5. Should enrollment fixes be bundled, or kept separate?

My take: the current enrollment has some real limitations worth knowing about, but I'd keep the lock PR minimal (reusing /etc/fido2/fido2 exactly as-is) and treat enrollment improvements as a separate change. The issues with enrollment today:

• Hostname fragility. Registration runs bare pamu2fcfg, so the credential's origin/appid default to pam://$HOSTNAME. Renaming the machine silently breaks all FIDO2 auth (sudo and polkit today; the lock screen too once added). Passing an explicit -o/-i origin at enrollment would make credentials survive a rename.
• Single key only. Setup short-circuits with "already registered" if /etc/fido2/fido2 exists, and pamu2fcfg -n (append a second key) is never used. That means no backup key — generally considered essential practice for hardware tokens, since losing the only registered key means losing key-based auth entirely.
• No re-enroll path. Replacing a key means running the full removal (which also strips sudo/polkit config and drops packages) and setting up from scratch.
• Single user. The authfile holds one user's line; a second user on the machine can't register.

None of these block the lock-screen feature, which is why I'd sequence them separately — but if maintainers would rather see enrollment hardened first, I'd like to know before building on it.

6. Making the authfile user-readable — any objections?

The lock screen's PAM conversation runs unprivileged inside the user's shell process (unlike sudo, which runs as root), so pam_u2f must be able to read /etc/fido2/fido2 as the user. Today the file usually ends up user-owned and world-readable by accident of how it's created (pamu2fcfg > /tmp/fido2 then sudo mv), but under a strict umask it can end up unreadable. My proposal includes an explicit chmod 0644.

On the risks, to be transparent: the file contains, per user, a credential handle and the credential's public key — by FIDO2's design this is not secret material; the security of the scheme lives in the private key that never leaves the token, plus physical presence. What world-readability does expose is metadata: any local user or process can see which usernames have registered keys and read their credential handles. That's an enumeration/privacy consideration, not an authentication bypass — an attacker with the file still can't authenticate without the physical key. The alternative would be moving to pam_u2f's default per-user location (~/.config/Yubico/u2f_keys), but that changes the enrollment format and contradicts keeping enrollment untouched. I think 0644 on the central file is the right trade-off; flagging it in case maintainers see it differently.

7. Should existing FIDO2 users get lock unlock automatically via a migration?

My take: yes, auto-enable via a migration, and I think that's the better practice here for three reasons. First, the user already expressed the intent — they ran omarchy setup security fido2 to use their key for authentication; the lock screen not being covered is a gap, not a choice they made. Second, it matches the fingerprint mental model: setting up fingerprint enables sudo, polkit, and lock-screen unlock together, so FIDO2 behaving differently is the surprising case. Third, there's direct precedent — migrations/1784818437.sh retroactively patched PAM for existing fingerprint installs. The migration would be strictly additive and idempotent: it only writes /etc/pam.d/omarchy-lock-fido2 when a registration already exists and the file doesn't, and never touches anything else.

8. The new PAM file would have two writers — acceptable?

Why this matters: /etc/pam.d/omarchy-lock-fingerprint is already written from two places with duplicated heredocs — omarchy-apply-lock (install/ISO path) and omarchy-setup-security-fingerprint (interactive path). Following the same pattern for FIDO2 puts identical copies of the new PAM stack in three files (omarchy-apply-lock, omarchy-setup-security-fido2, and the migration). Duplicated PAM content is a real maintenance hazard: if one copy is later edited and the others aren't, users end up with different authentication stacks depending on how their system was configured — and drift in PAM is security-relevant, not cosmetic. My suggestion: follow the existing pattern to keep the PR small and familiar, but add a test that extracts the heredoc from all three sources and asserts they're byte-identical, so drift fails CI. If maintainers would rather consolidate lock-PAM generation into a single writer first, I'm happy to discuss, but I'd treat that as a separate refactor.

9. Confirming: no pam_faillock in the FIDO2 lock stack

What this means: pam_faillock keeps a per-user tally of consecutive authentication failures across services, and omarchy-lock-password uses it (deny=10 unlock_time=120) to throttle password brute-forcing. The FIDO2 context, like fingerprint, would be always-armed while the screen is locked — and some keys enforce a touch timeout, so a locked, unattended machine with a plugged-in key can rack up periodic "failed" transactions with nobody at the keyboard. If faillock were in that stack, those idle timeouts would count against the user's tally and could lock them out of password authentication on their own machine. The existing fingerprint stack already handles this exactly the same way: /etc/pam.d/omarchy-lock-fingerprint is a bare pam_fprintd.so line with no faillock, because a physical-presence factor isn't something you can brute-force by submitting guesses — each attempt requires the actual hardware. I'd match that precedent; flagging it since omitting a rate-limiter from an auth stack deserves an explicit sign-off.

10. Touch-only for v1 — no PIN-protected credentials?

Previous state, for context: under Omarchy 3, Hyprlock rendered whatever the PAM conversation asked for through its single input field — so for someone who had manually wired pam_u2f into the hyprlock service, even a PIN prompt was at least mechanically typable. The Quattro lock is different by design: it never displays PAM conversation prompts, and the input field is fixed-purpose for the password. Supporting pinverification keys would therefore mean new conversation plumbing through the lock UI (prompt display, input rerouting, state handling) — a materially bigger and riskier change to a security-sensitive surface. My suggestion: v1 is touch-only (user presence), matching how the sudo/polkit pam_u2f lines are configured today; credentials that require a PIN simply won't unlock via key and the password remains the fallback. PIN support can be a follow-up if there's demand.

11. SDDM / graphical-login FIDO2 — formally out of scope?

What this is about: the natural follow-on question to lock-screen support is "what about logging in with the key after boot?" Having looked at how Omarchy boots, I don't think that feature would reach anyone by default: Omarchy does use SDDM, but omarchy-provision-owner configures permanent autologin on encrypted installs (which the manual says is the mandatory/default path) — the LUKS passphrase at boot is the real authentication boundary, and the SDDM greeter is never actually shown after first boot. Unencrypted installs only autologin once, but they're the non-default case. So FIDO2-at-SDDM would be configuring an auth method on a screen almost no Omarchy user ever sees, while touching upstream-owned PAM files (/etc/pam.d/sddm). My suggestion: declare it out of scope for this work and note it in the docs as a possible follow-up; the lock screen is where the feature actually gets used.

12. Testing expectations

The lock plugin currently has static source-assertion tests, live Quickshell fixture tests (e.g. the fingerprint indicator test), and Node unit tests for PAM-config parsing. I'd add equivalents for FIDO2 (indicator/layout fixture, arming/teardown invariants, plus the heredoc drift guard from Q8). Is that sufficient, or would you want a graphical acceptance test for the auth flow as well?

[Erijl]

Most of this is built. I've been running it on my machine since mid-August and published it today as a plugin: omarchy-fido2-key-suite, feel free to check it out and give feedback!
It lands on the same architecture you argue for in Q2, dedicated omarchy-lock-fido2 service, its own PamContext, so there's a working reference to argue with

Notes:
Q2: you need the split security wise, not just because of architecture. shared buffer → password spent as a PIN attempt → 8 retries → factory reset
Q5: multiple keys is smaller than it looks, and I'd bundle it. pamu2fcfg -n concatenates onto the user's line
Q6: the ownership problem is bigger than the metadata one. sudo mv relinks → user-writable file behind a sufficient rule = append-your-own-credential, not enumeration
Q10: touch-only v1 doesn't defer PIN keys, it excludes them. alwaysUv rejects presence-only with FIDO_ERR_PIN_REQUIRED; can't even be enrolled today. I already have a PR for that going; plus the pinverification=1 OR-ing trap

[wmauz677]

Thank you @Erijl — this is exactly the reply I was hoping for, and the plugin is impressive. I checked your notes against the code and docs, and you're right on all four; two of them change my proposal:

Q2: your shared-buffer/PIN-retry argument is stronger than my architectural one, and it also explains your mode-switch UX. For a touch-only upstream v1 I'd still argue for always-armed parallel (no typed input ever reaches the fido2 context, so the buffer risk doesn't exist) — with the explicit understanding that PIN support later means a mode switch like yours, never PIN bolted onto parallel.

Q5: agreed it's smaller than I framed it; with #6912's per-credential flags in place, bundling multi-key makes sense.

Q6: conceded, and it's the bigger finding — sudo mv leaving /etc/fido2/fido2 user-owned behind a sufficient rule in sudo is an append-your-own-credential escalation today, before any lock-screen work. My chmod 0644 suggestion fixed the wrong half; root-owned via install(1) as in your PR is correct.

Q10: conceded — "touch-only v1" excludes alwaysUv keys rather than deferring them, since bare pamu2fcfg can't even enroll them. That makes #6912 a prerequisite for any lock-screen PR, not a parallel improvement.

Proposal: rather than two competing efforts, I'd like to sequence behind you. #6912 lands first (it fixes enrollment and the ownership hole that everything else builds on). For the lock screen itself, I have a working patch against the stock lock plugin (same omarchy-lock-fido2 service + third PamContext your plugin validates, plus the omarchy-apply-lock branch, setup/remove wiring, a migration for existing enrollments, and tests in the repo's styles) — happy to co-author an upstream PR with you, or to review/test yours if you'd rather drive it since you've been running this since August. The plugin stays the natural home for the parts upstream likely won't take (PIN mode, SSH suite, unplug-lock, management panel), and upstreaming the core removes your fork-divergence problem. How do you want to split it?