Skip to content

Fingerprint setup and enrolment as a shell overlay - #10689

Closed
inauman wants to merge 1 commit into
omacom:quattrofrom
inauman:fingerprint-enroll-overlay
Closed

inauman wants to merge 1 commit into
omacom:quattrofrom
inauman:fingerprint-enroll-overlay

Conversation

@inauman

@inauman inauman commented Sep 7, 2026 •

Copy link
Copy Markdown

What

Turns Setup > Security > Fingerprint into a phone-style overlay in the shell, instead of a terminal running fprintd-enroll.

screenrecording-2026-09-07_13-12-00.mp4
  • Finger picker for both hands, enrolled fingers marked; arrow keys or click.
  • A print that fills in with every accepted press, a stage counter, and a hint for where to press next. The hint walks a spiral (center, above, right, below, left, corners) because on a small press sensor a print only verifies when a press overlaps something enrolled; twenty presses on the same spot enroll one spot.
  • Instant feedback: "Hold still" the moment the sensor sees skin, from fprintd's finger-present property.
  • First run: install packages, pick a finger, enroll, one confirming touch, then fingerprint login on for sudo, polkit and the lock screen. Later runs: the picker.

Works with any fprintd reader (stage count comes from fprintd over D-Bus). Without a running shell (TTY, SSH) the existing text flow runs unchanged.

How

The setup logic is not duplicated.

  • bin/omarchy-setup-security-fingerprint gains --enable-login, which runs its existing PAM step and omarchy-apply-lock (so the resume recovery from Fix fingerprint enrollment and lock-screen recovery #7158 comes along), and hands over to the overlay once it is confirmed on screen. If the overlay cannot open, it continues with its text flow, which is untouched apart from calling the same enable_fingerprint_login function; from the menu (--menu) that text flow reopens in a terminal (--text).
  • bin/omarchy-fingerprint-setup-helper (hidden): the overlay has no terminal for sudo, so its privileged steps go through this, following the omarchy-dns pattern: it re-runs itself through pkexec from /usr/bin with PATH pinned, runs the same package transaction as the setup script, and execs the packaged setup script for --enable-login.
  • shell/plugins/fingerprint-enroll/ — the overlay (Enroll.qml, FingerprintGlyph.qml canvas, EnrollModel.js parsing and hints).
  • bin/omarchy-fingerprint-enroll [finger] — summons the overlay; with a finger it enrolls that one and exits 0 or 1 like fprintd-enroll, reading the result from a private temporary directory. The overlay takes one request at a time and answers isOpen() / handles(doneFile) over omarchy-shell shell call, so a waiting script stops within seconds if the overlay goes away. Each request carries a deadline: the overlay refuses one the shell delivers late, and the wrapper falls back only once the deadline has passed, so a slow-loading overlay and the text flow never both run. Without the overlay it falls back to fprintd-enroll in a terminal, and fails without one.
  • The menu row runs omarchy-setup-security-fingerprint --menu directly; GROUP_DESCRIPTIONS gains fingerprint. All overlay text goes through I18n.t() with English entries in default/i18n/en/shell.json.

Security

  • Enrolling asks for the user's own password: fprintd's default polkit policy, remembered for a few minutes, so an unlocked session alone cannot add a fingerprint to someone's account. No polkit rules or actions are added.
  • Root runs only the packaged helper and setup script, with PATH pinned; polkit-1 is still written by the setup script with include system-auth (Defer to system-auth in the polkit stack written by fingerprint/FIDO2 setup #9873).

Tests

  • fingerprint-package-test.sh: new cases for the overlay hand-over, the text-flow fallback when the overlay cannot open, --menu reopening in a terminal, --text, --enable-login (lock confirmation required, nothing else runs), and the helper's install step run against the package stub (fresh, already installed, failed transaction).
  • fingerprint-enroll-test.sh: result parsing, cancelled password prompts, D-Bus errors kept out of the overlay, finger names and catalog keys, placement hints, and the wrapper against a stubbed shell: result delivery, picker confirmation, an overlay that vanishes mid-request (fails in seconds), an overlay that loads slowly, giving up only after the request's deadline, no terminal, and an invalid finger name.
  • Every test/shell.d test run on this branch and on quattro: no failures unique to this branch.
  • Hardware: Elan press sensor on an ASUS VivoBook; first-run flow, multiple fingers, lock screen, password prompt on enrollment and one-step cancel.

Try it

omarchy-fingerprint-enroll                  # picker, or first-run setup
omarchy-fingerprint-enroll right-thumb      # one finger, exit 0 on success

@inauman
inauman marked this pull request as ready for review September 7, 2026 20:04
@omarchybot omarchybot added the enhancement New feature or request label Sep 27, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

#9873 has merged into quattro, restoring include system-auth in the polkit PAM stack. This overlay/helper work remains separate and stays open. The new omarchy-fingerprint-setup-helper still creates polkit-1 with bare pam_unix entries; carrying that heredoc forward would reintroduce the missing faillock path. Rebase it onto the new stack and retain the distro system-auth includes when moving setup into the helper.

Scope checked by GPT-6 in Codex and Codex Medium against the current diffs and landed fix; independence is not guaranteed. No runtime tests were rerun for this reconciliation.

@inauman

inauman commented Oct 4, 2026

Copy link
Copy Markdown
Author

Thanks, good catch. Rebased onto current quattro (now including #9873) and fixed:

  • omarchy-fingerprint-setup-helper writes the polkit-1 stack with include system-auth for all four phases, so polkit prompts keep pam_faillock, matching the setup script after Defer to system-auth in the polkit stack written by fingerprint/FIDO2 setup #9873.
  • The helper's package step mirrors the current setup script: libfprint-git fprintd usbutils with --ask 4 in one transaction, instead of swapping libfprint-git out.
  • test/shell.d/security-polkit-faillock-test.sh now checks the helper, since that is where fingerprint setup writes the stack in this PR, so Defer to system-auth in the polkit stack written by fingerprint/FIDO2 setup #9873's guard keeps covering the moved code.
  • The remove command keeps upstream's UID-strict caller resolution and template cleanup; this PR only adds removal of the enrolment polkit rule.

Tests: security-polkit-faillock-test.sh, security-polkit-migration-test.sh, fingerprint-enroll-test.sh pass; ./test/cli has one failure (vscode generated theme references current theme file) that also fails on quattro in this environment. Runtime check on hardware: polkit approval by fingerprint and the password fallback after three failed touches both work on the repaired stack.

@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from 5a8dc55 to 2203802 Compare October 4, 2026 15:40
@greptile-apps

greptile-apps Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no outstanding finding or actionable new issue was identified.

Summary

The PR moves fingerprint setup into a shell overlay while retaining the terminal-based fallback. It adds guided enrollment, a privileged helper for package installation and login configuration, and tests for hand-off and result handling.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Fingerprint menu or setup command] --> B{Shell overlay opens?}
  B -- Yes --> C[Picker or requested finger]
  C --> D[Install packages if needed]
  D --> E[Enroll and confirm fingerprint]
  E --> F[Enable fingerprint login]
  B -- No --> G[Existing terminal text flow]
Loading

Reviews (7) · Last reviewed commit: "Fingerprint setup and enrollment as a sh..." · Reviewed by Greptile

Comment thread bin/omarchy-fingerprint-setup-helper Resolved
Comment thread bin/omarchy-setup-security-fingerprint Resolved
@inauman

inauman commented Oct 4, 2026

Copy link
Copy Markdown
Author

Addressed all three in 57af12f:

  1. Unprotected enrolment: removed the passwordless polkit rule entirely. Enrolment uses fprintd's default policy again (the user's own password, remembered for a few minutes), so an unlocked session alone cannot add a fingerprint. The PR description's security note is updated to match.
  2. Cancellation result: the result is now written with Quickshell.execDetached, which outlives the plugin, so unloading on hide cannot drop it. A cancelled password prompt also closes the overlay in one step and reports failed; raw D-Bus errors no longer reach the overlay.
  3. Package test: the text flow uses the original package transaction and enrolment command, and fingerprint-package-test.sh stubs omarchy-shell so it exercises that flow, plus asserts the helper runs the same guarded transaction.

Also fixed while there: omarchy-shell -q shell ping exits 0 even with no shell running, so the TTY/SSH fallback could never trigger; both scripts now check the ping reply. bin-style-test.sh and privileged-heredoc-test.sh pass (helper uses omarchy-cmd-present, and the polkit-1 heredoc carries the same omarchy:heredoc-expands declaration as the setup script).

Every test/shell.d test was run on this branch and on quattro: no failures unique to this branch (the remainder fail identically on quattro in this environment). Verified on hardware: enrolment prompts for the password, Esc on that prompt returns exit 1 immediately from omarchy-fingerprint-enroll FINGER.

@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from 57af12f to a76b02d Compare October 4, 2026 17:20
@inauman

inauman commented Oct 4, 2026

Copy link
Copy Markdown
Author

Thanks for the second pass. Both points are addressed, and I took the opportunity to go through the whole change once more; the branch is now a single commit on current quattro.

Your two comments

  • Refused authentication: fprintd reports a cancelled and a failed password prompt with the same PermissionDenied, so they can't be told apart, but the picker now says why nothing happened ("Not added: your password is needed to add a fingerprint") instead of returning silently.
  • Helper install untested: fingerprint-package-test.sh now runs the helper's install step against the package stub: one transaction on a fresh machine, no pacman when everything is installed, failure reported.

From the wider review

  • No duplicated setup logic. With Fix fingerprint enrollment and lock-screen recovery #7158 moving lock-screen setup into omarchy-apply-lock, the helper no longer writes any PAM itself. omarchy-setup-security-fingerprint --enable-login runs the script's existing PAM step and omarchy-apply-lock, so the overlay gets the resume recovery too; the helper only execs it. The faillock test is back to its original form.
  • House privilege pattern. No custom polkit action, install step or migration any more: the helper re-runs itself through pkexec from /usr/bin with PATH pinned, like omarchy-dns, and calls no omarchy-* command by bare name as root.
  • Wrapper hardening: the finger argument is validated before it goes into the JSON payload, and the result file lives in a private temporary directory.
  • Smaller things: user-facing messages no longer show exit codes, US spelling throughout, GROUP_DESCRIPTIONS[fingerprint] added, unused payload keys removed.

New tests cover the overlay hand-over, --enable-login (nothing else runs; lock confirmation required) and the wrapper's input check. Every test/shell.d test was run on this branch and on quattro: the same 11 fail on both in this environment, none only here. The PR description is updated to match.

@omarchybot omarchybot removed the enhancement New feature or request label Oct 13, 2026
@HemangKumawat

Copy link
Copy Markdown

We have a settings prototype using standard fprintd D-Bus and would like to consolidate its generic behavior into this overlay. Useful additions are explicit replacement confirmation, rechecking enrolled fingers after Claim, confirmed single-finger deletion without a delete-all fallback, and precise duplicate/full/busy handling.

Our stock/unknown Egis path blocks Test because verification/storage reconciliation can lose registrations. We can contribute isolated private-bus fixtures and a narrow verification-safety policy while preserving your setup/PAM/privilege flow. Our latest candidate’s physical acceptance remains pending.

— Written by Claude on behalf of @HemangKumawat.

@omarchybot omarchybot added the enhancement New feature or request label Oct 14, 2026
@inauman

inauman commented Oct 15, 2026

Copy link
Copy Markdown
Author

Thanks, glad it's useful. To keep this PR reviewable I'd rather not widen it, but the generic pieces sound like a natural follow-up on top of it once it lands: confirming before replacing an enrolled finger, and single-finger deletion through fprintd's DeleteEnrolledFinger (which the same net.reactivated.fprint.device.enroll permission covers, so no admin prompt). Duplicate, storage-full and busy results are already mapped to their own messages in EnrollModel.js. Reader-specific verification safety feels like it belongs with the driver or in its own PR. Happy to review a follow-up.

@inauman

inauman commented Oct 15, 2026

Copy link
Copy Markdown
Author

Rebased onto current quattro and moved the overlay onto the new translation system from #15326: every user-facing string goes through I18n.t() with English entries in default/i18n/en/shell.json (76 fingerprint.* keys, including the finger names and placement hints), the layout mirrors for right-to-left languages like the other overlays, and it no longer shows the helper's raw English output during setup. extract-scan --check reports no literals, the structural i18n test passes, and fingerprint-enroll-test.sh now checks that every key it uses is in the catalog. No translations included; those are for the sync workflow.

@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from a76b02d to 94b0cd3 Compare October 15, 2026 22:15
Comment thread bin/omarchy-fingerprint-enroll Resolved
@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from 94b0cd3 to 88f0453 Compare October 15, 2026 23:27
@inauman

inauman commented Oct 15, 2026

Copy link
Copy Markdown
Author

Thanks. All three are fixed, along with related issues found by going through the overlay's request and lifecycle handling as a whole:

The three comments

  • Repeated requests: the overlay takes one request at a time. A request arriving while it is open is refused with failed immediately, so the first caller keeps its result.
  • Reader details on first enrollment: the reader is queried again once installation succeeds, which also starts the finger-present watch.
  • Fallback skipping setup: setup hands over only after the overlay confirms it is on screen. Otherwise it continues with the full text flow; from the menu (now omarchy-setup-security-fingerprint --menu) that flow reopens in a terminal with --text.

Related

  • Esc or a click outside during package installation or while turning login on is refused, so pkexec/pacman are never cut off by the overlay unloading.
  • Closing stops every timer and background query, so nothing from one session fires into the next.
  • The overlay answers isOpen() and handles(doneFile) over omarchy-shell shell call; omarchy-fingerprint-enroll polls them, so a request the overlay can no longer answer fails within seconds instead of waiting out the safety net.
  • Without a terminal the wrapper fails instead of running a bare fprintd-enroll.
  • Retrying after a failed setup step no longer depends on the wording of the (now translated) message.

New tests cover the text-flow fallback, --menu and --text, and the wrapper against a stubbed shell (result delivery, picker confirmation, an overlay that vanishes mid-request, no terminal). Every test/shell.d test was run on this branch and on quattro with no display or compositor attached: no failures unique to this branch.

Comment thread bin/omarchy-fingerprint-enroll Resolved
@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from 88f0453 to d66cc2b Compare October 16, 2026 00:10
Comment thread test/shell.d/fingerprint-enroll-test.sh Resolved
Setup > Security > Fingerprint opened a terminal that ran fprintd-enroll
and printed "place your finger" a number of times. Small press sensors
only verify when a press overlaps something enrolled, so an enrollment has
to cover the finger, and nothing in that flow said so.

Replace it, when the shell is running, with an overlay
(omarchy.fingerprint-enroll):

- a finger picker for both hands with enrolled fingers marked;
- a fingerprint drawn as thin ridges that fill in with every accepted
  press, a stage counter, and a hint that walks the finger around a spiral
  (center, above, right, below, left, corners);
- instant "hold still" feedback from fprintd's finger-present property,
  and a plain-language message for each result fprintd can report;
- first run: packages, enrollment, one confirming touch, then fingerprint
  login on; later runs open the picker.

The setup logic is not duplicated. omarchy-setup-security-fingerprint
gains --enable-login, which runs its existing PAM and omarchy-apply-lock
steps (so the lock-screen resume recovery comes along), and hands over to
the overlay when the shell is running; without one, the text flow is
unchanged. The overlay has no terminal for sudo, so its privileged steps go
through omarchy-fingerprint-setup-helper, which re-runs itself through
pkexec from its packaged path with PATH pinned, installs the same package
transaction, and execs the packaged setup script for --enable-login.

Enrolling keeps fprintd's default polkit policy: the user's own password,
remembered for a few minutes, so an unlocked session alone cannot add a
fingerprint. omarchy-fingerprint-enroll [finger] summons the overlay from
scripts (a finger enrolls it and waits for the result, which the overlay
writes into a private directory) and falls back to fprintd-enroll without
a shell. Works with any fprintd reader.
@inauman
inauman force-pushed the fingerprint-enroll-overlay branch from d66cc2b to dd639e1 Compare October 16, 2026 01:00
@inauman

inauman commented Oct 25, 2026

Copy link
Copy Markdown
Author

Closing this. The step-by-step terminal setup from #15512 and the platform hook from #16360 now cover the main thing this PR was for: guiding enrollment on press sensors. Rebasing a large overlay onto it doesn't seem worth the review cost. If an on-screen flow is wanted later, I'm happy to rebuild it on top of the current setup script.

Thanks for the work on the fingerprint flow. Support for the reader that started this (Elan 04f3:0c3d) is going upstream in libfprint instead: https://gitlab.freedesktop.org/libfprint/libfprint/-/merge_requests/654

@inauman inauman closed this Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants