Show fingerprint reader status in authentication dialogs

[tonibergholm]

Summary

Fingerprint authentication currently shows an icon without the PAM reader status, leaving users without guidance while the sensor initializes or asks for another scan. Display PAM messages below the lock password field and the polkit fingerprint card, with a preparing-reader fallback before a message arrives.

The lock wakes once for the first informational PAM message per lock cycle; retry messages do not repeatedly wake an unattended display. Clear the message when resetting authentication and starting another attempt. Require an enrolled fingerprint entry in fprintd-list output rather than matching any occurrence of “finger”.

Integration context

This upstreams the UI integration from t2touch, which exposes Apple T2 Touch ID through the standard fprintd interface. Its installer applies these three QML changes to Omarchy. The machine owner confirms that T2 fingerprint authentication works on this machine with the existing local integration. This is user-confirmed hardware success, not a completed test of every authentication path on the final PR branch.

Validation

Passed focused suites: lock-fingerprint-message, lock-blank-fingerprint, polkit, system-lock, lock-password-overflow, and lock-fingerprint-indicator. The last two ran with compositor access. git diff --check passed.

Inspected the running desktop's lock preview with the original local patch: the preparing-reader text fits below the password field. The PR preserves that layout and adds message-reset cleanup and regression coverage.

The four t2touch UI installer unit tests also pass. A read-only transform check confirms that the current installer rejects the upstreamed source before writing, so rerunning it will safely skip this UI patch rather than apply it twice.

Draft checks remaining

• Verify real fingerprint success, failure/retry, cancellation, and password fallback on the final branch.
• Inspect the polkit status layout and long/translated messages in the running UI.
• Verify behavior with a standard non-T2 fprintd reader; T2 authentication is already reported working with the local integration.
• Confirm whether waking on the first informational message is desirable; PAM does not guarantee that this message means the reader is ready for placement.

[llstrk]

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Verified: PAM text now reaches both the lock view and the polkit fingerprint card. The lock wake fires at most once per lock. The new fprintd-list check reports only enrolled fingers. The new test fails on the base. One behaviour issue remains: the lock's "Preparing fingerprint reader…" fallback returns on every PAM retry, and it can stay up indefinitely when the reader never prompts. A smaller polkit note and some related open PRs follow.

Lock shows "Preparing fingerprint reader…" on every retry, indefinitely when pam_fprintd fails early

startFingerprint clears fingerprintMessage at the start of every attempt (shell/plugins/lock/Service.qml:255). The lock starts a new attempt 250 ms after every failed attempt or PAM error (Service.qml:262-271, 405-419). LockView.qml:131 shows the fallback whenever the message is empty.

pam_fprintd (fprintd 1.94.5) returns without sending any message when it cannot claim the device, cannot reach fprintd, or VerifyStart fails. In those states each retry clears the text and no replacement arrives:

lock → startFingerprint: message = ""   → view: "Preparing fingerprint reader…"
     → pam_fprintd: claim fails, no message, PAM error
     → 250 ms retry → startFingerprint: message = "" → same text
     → … repeats while the reader stays unavailable

On a working reader the same clear causes a brief flash. After the 30 s "Verification timed out", or after "Failed to match fingerprint" on the third mismatch, the next attempt shows "Preparing fingerprint reader…" again before the placement prompt (for example "Place your right index finger on the fingerprint reader"). Separately, if fingerprintPam.start() returns false, no retry is scheduled and the fallback stays up.

Impact: with a busy, wedged or unreachable reader (the situation several open PRs, such as #7158, #11918 and #12544, deal with), the base shows only the icon. The head now tells the user to wait for a reader that is not coming. On a working reader, "Preparing" after a timeout or the third mismatch suggests the reader is reinitialising.

Suggested change: show the fallback only until the first PAM message of a lock cycle (a flag reset in beginLock), and keep the last message across retries instead of clearing it in startFingerprint. When attempts keep ending with no message, show nothing or an "unavailable" state instead of the preparing text.

Polkit status can describe the wrong module or a previous attempt

Quickshell (v0.3.1) never clears supplementaryMessage within one polkit request, including when it starts a new session after a failed attempt. Omarchy clears it only when the dialog resets. The new box (shell/plugins/polkit/PolkitAgent.qml:367-388) therefore shows the last message from any module until the next one speaks:

• After a wrong password, the box is hidden for a 1.2 s error flash. If the new attempt has not sent its first message by then, the previous attempt's last message (for example "Verification timed out") shows until the next module speaks.
• When omarchy-setup-security-fingerprint runs before omarchy-setup-security-fido2, pam_u2f sits first in /etc/pam.d/polkit-1. With the lid open, the dialog still enters fingerprint mode, because it checks only for a pam_fprintd.so line. It shows "Preparing fingerprint reader…" while pam_u2f, not the reader, is running.

When a registered key is attached and pam_u2f prompts, the box correctly shows "Please touch the FIDO authenticator.", though the card still shows a fingerprint glyph. The base shows only the glyph in that state, so this part is an improvement.

Impact: short periods of wrong text, not a failed authentication.

Suggested change: use a neutral fallback (not reader-specific), or show it only when pam_fprintd is the first auth module. With a neutral fallback in place, the displayed message can also be cleared when a new attempt starts, without reintroducing reader-specific text. Open PR #13217 also reads supplementaryMessage for security-key cues and would need reconciling with this box.

Verified: fprintd enrolment check

fprintd 1.94.5 utils/list.c prints fixed, untranslated strings, with - #N: <finger> once per enrolled finger. The fingerprintCheckProc command from base and head (with only the PAM file path redirected) was run against synthetic fprintd-list output:

Case	Base (grep -qi finger)	Head (enrolled-row regex)
No fingers enrolled	yes	no
One or several fingers	yes	yes
Two devices, second enrolled	yes	yes
Two devices, none enrolled	yes	no
ListEnrolledFingers failed (exit 1)	yes	no
No devices, or no daemon (exit 1)	no	no

bin/omarchy-apply-lock:43-44 still uses grep -qi finger, so on a machine with a reader it still writes /etc/pam.d/omarchy-lock-fingerprint for users with no enrolled fingers. The lock's own check now says no in that case, so the UI is unaffected. Open PR #9551 changes both callers to one shared helper.

Optional test improvement: the new test runs the real handler and reset bodies, and fails on the base. These diagnostic mutations still pass it:

• removing the clear in startFingerprint;
• removing the fingerprintWakeUsed = false reset in beginLock;
• dropping the fingerprintMessage binding to the lock surface;
• restoring the old grep -qi finger.

Asserting those lines would cover the lifecycle and binding the PR describes.

Related open PRs:

• [Intel Mac P12] Consolidate T1Bridge support and fingerprint UI #12690 (draft) lists this PR as included and carries the same changes.
• Detect fingerprint enrollment by the enrolled entries, not the word "finger" #9551 and Keep fingerprint unlock alive when the probe cannot reach fprintd #9456 rewrite the same fingerprintCheckProc line. Keep fingerprint unlock alive when the probe cannot reach fprintd #9456 adds an "unknown" state with retries and its own enrolled-row check, so the three need reconciling.
• Keep the lock screen fingerprint working across suspend, and show when the reader is unavailable #7158 (an 18 px "Fingerprint reader unavailable" notice) and Pulse the fingerprint glyph and flag a rejected scan #12291 (a "Try again" label 8 px below the field) place text in the same spot as this PR's status text, 16 px below the field.
• Flash the lock screen fingerprint icon when a read is rejected #11162 and Pulse the fingerprint glyph and flag a rejected scan #12291 each add their own onPamMessage handler to fingerprintPam, which would need merging with this one.

---

Review information

Test scope: Source review of the head, the base and a local merge with the current quattro tip (clean merge). Upstream sources read: Quickshell v0.3.1, fprintd 1.94.5, pam-u2f 1.4.0 and polkit 127. In a sandbox: the new test (passes on the head and the merge, fails on the base), diagnostic mutants, related shell tests, and the fprintd-list check against synthetic output. lock-fingerprint-indicator and lock-password-overflow were skipped, since there was no compositor. video-background fails identically on quattro without this PR. The PAM stacks for the FIDO2 case come from replaying the setup scripts' text edits on private copies. No QML rendering, real PAM, fprintd, polkit or fingerprint/FIDO hardware was exercised. Lifecycle and timing conclusions come from source.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

[GeertJohan]

I implemented a similar solution in #7158