Skip to content

Guide fingerprint enrollment step by step - #15512

Merged
ryanrhughes merged 8 commits into
omacom:quattrofrom
scottjones:fix/fingerprint-enroll-guide
Oct 21, 2026
Merged

ryanrhughes merged 8 commits into
omacom:quattrofrom
scottjones:fix/fingerprint-enroll-guide

Conversation

@scottjones

Copy link
Copy Markdown
Contributor

Fingerprint setup told everyone to keep moving their finger around the sensor and printed fprintd's raw Enroll result: enroll-stage-passed lines. On a press sensor like a Mac's Touch ID, that read as "one touch and wait", and enrollment timed out a minute later.

Setup now asks fprintd for the reader's scan type. A press sensor is told to touch, lift and touch again until it says Enrolled. Each result becomes a plain line: a numbered step, a retry with what to do, or why it stopped. Verify reads the same way. fprintd's routine lines are hidden, but anything else it prints, like why it couldn't claim the reader, still shows. When fprintd can't say the scan type, the prompts say "touch or swipe".

This is a generic change, and three things change for every reader:

  • The setup output is the new step, retry and failure lines instead of fprintd's.
  • sudo is authenticated up front, with a line saying so. With fingerprint sudo already set up, its own touch was being taken as the first sample.
  • A failed verify exits 1, like a failed enrollment, so the setup terminal shows it failed. Before, it fell off the end with status 0.

PAM is still written only after a print verifies, through omarchy-apply-lock as on quattro.

fprintd runs a duplicate check before enrolling on readers that can identify, and Touch ID's needs no touch, so its first stage isn't shown as a step. Touch ID is spotted by the reader name from the driver omarchy-pkgs adds to libfprint-git (aurora-apple-sep.patch). On any other reader that comparison simply doesn't match.

This is the enrollment half of omacom#694; detection is in #14675. Thanks to @maralcbr for the review there.

#14965 (retry when the reader can't be claimed) and #14342 change the same enroll and verify lines. They fit with this, by teeing fprintd's raw output before the filter, but will need a rebase.

Evidence

test/shell.d/fingerprint-package-test.sh stubs fprintd, sudo and busctl, so nothing on the machine changes.

  • Before: the same test against quattro's script prints 41 not ok lines, e.g. not ok - a press sensor is told to lift and touch again, not ok - a failed verify fails setup, not ok - setup names sudo's prompt and authenticates before enrolling
  • After: 18/18. hw-fingerprint-test.sh 11/11.

On an M2 Max, fprintd reports the reader as Apple secure enclave fingerprint sensor with scan type press, which is the Touch ID path. I haven't run setup end to end on this branch, since that writes PAM. Swipe readers, other readers that identify, and the PAM success path are covered only by the stubbed tests.

Test plan

  • bash test/shell.d/fingerprint-package-test.sh passes
  • On a press reader: setup says to touch, lift and touch again, counts steps, and ends with Enrolled, Matched and PAM configured
  • On a Mac with Touch ID and fingerprint sudo already set up: the sudo touch comes first, under "First, confirm it's you", and isn't counted as a sample
  • A finger that doesn't match at verify: setup says so and exits 1, with PAM unchanged

Merge Danger

Door: two-way

Blast Radius: medium. Every machine that runs fingerprint setup sees the new output, and a failed verify now exits 1.

🤖 Generated with Claude Code

scottjones and others added 5 commits October 13, 2026 21:26
A failed enrollment on a Mac's Touch ID showed how setup's output misled:
it told everyone to keep moving the finger around the sensor, which suits a
swipe sensor, and printed fprintd's raw "Enroll result: enroll-stage-passed"
lines. A press sensor needs a separate touch for each sample, fprintd sends
one stage after its duplicate check before enrollment starts, and one stage
can take several touches, so after a single touch enrollment looked under
way and timed out a minute later.

Setup now asks fprintd for the reader's scan type and, for a press sensor,
says to touch, lift and touch again until it says Enrolled. It turns each
result into an instruction: the duplicate check's stage prints nothing, each
later stage is a numbered step followed by what to do next, retries and
failures say what to do, and verify reads the same way, " (done)" and
" (not done)" suffixes included. fprintd's routine lines are hidden, but
anything else it prints, such as why it could not claim the device, is
shown, and fprintd's exit status still decides each step. sudo is
authenticated first, and named, because with fingerprint sudo set up its own
touch read as the first sample; if it fails, setup says why and stops.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The first enroll-stage-passed was always hidden, on the assumption that
it is fprintd's duplicate check. fprintd runs that check only on readers
that identify, so on any other reader the first real stage was hidden
and every later step was numbered one low.

fprintd's D-Bus interface doesn't say whether a reader identifies, but
it gives the reader's name. Touch ID ("Apple secure enclave fingerprint
sensor") identifies, and its check needs no touch while nothing is
enrolled, so its first stage stays hidden. Every other reader's first
stage counts: on one that doesn't identify it is the first enrollment
stage, and a duplicate check that took a touch is shown as step 1.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A failed verify printed its message and fell off the end with status 0;
it now exits 1 like a failed enrollment. The test now covers a failed
verify after a successful enrollment: setup fails and leaves PAM and the
lock screen alone.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
When busctl couldn't read the reader's scan type, setup took the swipe
branch and told a press reader to swipe its finger across the sensor to
enroll and verify. A reader fprintd can't describe is now asked to touch
or swipe.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@greptile-apps

greptile-apps Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issues were found.

Summary

Fingerprint setup gives reader-specific instructions, turns fprintd results into plain progress messages, and authenticates sudo before enrollment. Failed verification stops setup before PAM changes.

  • Fingerprint setup guides each reader through enrollment.
  • Fingerprint verification shows its result and fails setup when the check fails.
  • Setup confirms sudo before asking for fingerprint samples.

Reviews (3) · Last reviewed commit: "Say lift and try again in one line when ..." · Reviewed by Greptile

Comment thread bin/omarchy-setup-security-fingerprint Resolved
verify-disconnected and every other finished failure read the same
"The check stopped", hiding what fprintd-verify reported. A disconnect
now says so, as enrollment does, and any other failure names fprintd's
result.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@omarchybot omarchybot added the enhancement New feature or request label Oct 17, 2026

@maralcbr maralcbr left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at a808491, merged onto current quattro (clean). In a Linux container fingerprint-package-test.sh passes 18/18 and hw-fingerprint-test.sh 11/11.

Approve, with nits:

  • The pipes are fine. fprintd's g_print flushes stdout on every line (glib print_string), so the steps show live, and PIPESTATUS[0] right after each pipe gets fprintd's status under set -e without pipefail.
  • Skipping Touch ID's first stage is right. fprintd 1.94.5 runs an identify for duplicates on any FP_DEVICE_FEATURE_IDENTIFY reader and then emits one enroll-stage-passed (src/device.c:2162, 2239–2257). Matching on the reader name is the best option while D-Bus doesn't expose features.
  • Under the C/POSIX locale, fingerprint-package-test.sh fails "enrollment results read as instructions, counting steps after the duplicate check" because the expected strings use $'✓'. Literal ✓/✗ in the fixture, or LC_ALL=C.UTF-8 in the test, would fix it.
  • "Lift your finger off the sensor, then: Keep lifting your finger and touching the sensor." reads twice. Maybe "Lift your finger off the sensor, then touch it again."
  • A failed verify now exits 1 on every machine, x86 included. The body says so; worth Ryan accepting that explicitly.

scottjones and others added 2 commits October 18, 2026 22:36
The expected strings spelled ✓ and ✗ as $'\u2713' and $'\u2717', which bash
only turns into those characters under a UTF-8 locale. Under C or POSIX the
enrollment check failed even though setup printed the right lines. The
fixtures now hold the characters themselves.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The remove-and-retry line added the step's own "again" prompt after "then:",
so a press reader read "Lift your finger off the sensor, then: Keep lifting
your finger and touching the sensor." It now says "Lift your finger off the
sensor, then try again." on every reader: libfprint sends this retry from
swipe drivers too (elanspi, upekts, vfs101), so the line names no gesture.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@scottjones

Copy link
Copy Markdown
Contributor Author

Thanks for the review @maralcbr, both nits were good ones.

  • C locale: good catch. The expected strings now hold the ✓ and ✗ characters themselves instead of $'\u2713' and $'\u2717'. Under LC_ALL=C that check failed before and the test passes 18/18 now. (aef8d09)
  • "Lift your finger off the sensor, then:" now reads "Lift your finger off the sensor, then try again." for both enroll and verify. I went with "try again" over "touch it again" because libfprint sends that retry from swipe drivers too (elanspi, upekts, vfs101). (64685fa)
  • The verify exit: agreed. I'll ask Ryan to sign off on that one explicitly.

@maralcbr

Copy link
Copy Markdown
Member

@scottjones thanks. Both nits are fixed at 64685fa. Merged onto current quattro (clean), fingerprint-package-test.sh passes 18/18 and hw-fingerprint-test.sh 23/23 under both LC_ALL=C and C.UTF-8. "Then try again" works for swipe and press readers alike. My approval stands; only Ryan's sign-off on the verify exit 1 is left.

@ryanrhughes
ryanrhughes merged commit be5fefb into omacom:quattro Oct 21, 2026
2 checks passed
omarchybot added a commit to kvnloo/omarchy that referenced this pull request Oct 21, 2026
omacom#15512 replaced the single fprintd-verify with a pipe through verify_progress, which turns fprintd's results into guidance. The retry now tees into that filter instead of replacing it, so each attempt shows the same guidance and a claim failure is still printed for the user.

The settle test follows setup as quattro now runs it: it stubs the sudo -n check and the busctl reader lookups, so it never reaches the worker's own sudo or system bus, and it expects setup to exit 1 when verification fails, as a1fa8cd made it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.

4 participants