Skip to content

Detect fingerprint readers by USB interface name - #7726

Open
OldJobobo wants to merge 4 commits into
omacom:quattrofrom
OldJobobo:fix/fingerprint-interface-descriptor
Open

OldJobobo wants to merge 4 commits into
omacom:quattrofrom
OldJobobo:fix/fingerprint-interface-descriptor

Conversation

@OldJobobo

Copy link
Copy Markdown
Contributor

Problem

Some composite USB fingerprint readers expose only a generic device-level product name. The useful description appears on one of the device's USB interfaces instead.

For example, the Broadcom ControlVault 3+ (0a5c:5865) reports 58200 as its product while an interface reports Broadcom ControlVault 3+ w/FingerPrint. omarchy-hw-fingerprint currently reads only the product descriptor and therefore reports that no reader is present.

Fixes #7424.

Change

Inspect each device's immediate USB interface descriptors for the same explicit fingerprint/biometric identity used by the existing product-name detection. Explicit interface names are trusted before the broader vendor heuristic; generic interfaces remain rejected.

Scope

This fixes hardware detection only. Broadcom ControlVault readers may still require an out-of-tree TOD libfprint driver before enrollment can succeed, as noted in the issue. The setup flow already avoids modifying PAM unless enrollment and verification succeed.

Regression coverage

The test fixture models a composite ControlVault device with:

  • a generic 58200 product descriptor
  • a SmartCard interface at 1.0
  • a fingerprint interface at 1.1

It verifies that every interface is searched and also confirms that the generic SmartCard interface alone does not produce a false positive.

Validation

  • bash test/shell.d/hw-fingerprint-test.sh
  • bash test/shell.d/fingerprint-invitation-test.sh
  • bash -n bin/omarchy-hw-fingerprint test/shell.d/hw-fingerprint-test.sh
  • shellcheck -e SC1091 bin/omarchy-hw-fingerprint test/shell.d/hw-fingerprint-test.sh
  • ./test/cli
  • git diff --check

@OldJobobo
OldJobobo marked this pull request as ready for review August 22, 2026 02:25
Copilot AI balanced review requested due to automatic review settings August 22, 2026 02:25

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Extends fingerprint hardware detection to inspect USB interface descriptors for composite devices.

Changes:

  • Detects fingerprint or biometric in interface names.
  • Adds ControlVault detection and false-positive regression tests.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.

File Description
bin/omarchy-hw-fingerprint Scans immediate USB interface names.
test/shell.d/hw-fingerprint-test.sh Tests composite reader detection and generic interface rejection.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@omarchybot omarchybot added the bug Something isn't working label Sep 27, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at c2704aa on a disposable Omarchy VM. No defects found. The fix is proven against a model of the hardware, but not yet on real hardware, so this waits on @eworkshop.

What was run. I wrote a separate reproduction that builds a fake sysfs tree laid out like the one in #7424: 0a5c:5865 with product 58200 and interface Broadcom ControlVault 3+ w/FingerPrint, plus interfaces listed as top-level entries and a root hub, the way /sys/bus/usb/devices really is. It fails on quattro and passes on this head. A second case adds a Broadcom Bluetooth adapter, a smartcard-only ControlVault (0a5c:5832) and a HID receiver with a colon-named child directory, and it stays rejected on both. The PR's own new test fails with the fix reverted, so it is not vacuous. On the head, test/shell.d/hw-fingerprint-test.sh (13 passed), test/shell.d/fingerprint-invitation-test.sh (1 passed) and ./test/cli all pass. The branch merges cleanly into current quattro, and neither file has changed there since it forked.

Competing fixes. #8486 adds all of Broadcom's 0a5c to the vendor list, and #9524 adds the exact ID 0a5c:5843. This one matches the reader by what its interface calls itself, so it finds 5865 (which #9524 misses) without claiming smartcard-only ControlVault devices (which #8486 does). Of the three, it has the fewest side effects. One limit: it only finds 5843 and older ControlVault 2 readers if their interface string also says fingerprint, and nobody has shown that it does. Codex Medium, as the second opinion, picked this one too. It could not reach GitHub, so it judged the other two from their descriptions rather than their diffs, and its independence is not guaranteed. It found no defects here, including in how the new glob handles interface and root-hub entries. Choosing between the three is the maintainer's call.

What's still open. A fake sysfs tree only shows what we believe the hardware looks like. @eworkshop, could you run this head on the Dell Pro Max 16 and say what it prints?

curl -fsSL https://raw.githubusercontent.com/basecamp/omarchy/c2704aa7ea00ff6d3016e29299feaa356939f6c8/bin/omarchy-hw-fingerprint -o /tmp/hw-fingerprint-7726
bash /tmp/hw-fingerprint-7726; echo $?

0 means the reader was detected. It only reads /sys and changes nothing. As #7424 already says, this fixes detection only. With stock libfprint, enrollment on ControlVault still needs the TOD driver.

@OldJobobo

OldJobobo commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

Updated in 5021810d: merged current quattro and resolved the test conflict by keeping both composite-interface detection fixtures and the newer platform-reader isolation. The detector retains upstream's kernel-driver exclusions, usbfs exception, and non-USB platform-reader support.

Validation: hw-fingerprint (25 checks), fingerprint invitation and package tests, CLI checks, shell syntax, and feature-diff whitespace checks pass. Real ControlVault hardware confirmation is still outstanding; this update does not claim that the fixture tests replace it.

--[ Pi :: gpt-6.1-sol ]--
--- on behalf of: @OldJobobo

@greptile-apps

greptile-apps Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Extends omarchy-hw-fingerprint to recognize readers named by a USB interface, even when their product name is generic.

  • USB readers can be recognized by the names of their interfaces.

No actionable issues were found. Review checks were static; tests were not run.

Reviews (3) · Last reviewed commit: "Merge current quattro into fingerprint i..." · Reviewed by Greptile

@omarchybot omarchybot added the compatibility Make Omarchy work better on everything! label Oct 22, 2026
docs/file-layout.md said omarchy-hw-fingerprint finds USB readers by product string or vendor; it now also matches the name an interface gives, as on ControlVault readers whose product reads 58200.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed again at 5021810, the merge of current quattro. The detection change is the same as at c2704aa, and it still holds on top of the platform-reader and usbfs changes that landed since. I pushed one line to the docs. This still waits on a run on the real reader.

What was run. On a disposable Omarchy VM, a fake sysfs tree laid out like #7424 (0a5c:5865, product 58200, interface Broadcom ControlVault 3+ w/FingerPrint, with interfaces as top-level entries and a root hub) fails on quattro (be54892), passes on this head, and fails again with the new has_fingerprint_interface call removed. A ControlVault 3 modelled on #16021's description (0a5c:5843, fingerprint named on its second interface, a driver bound to its smartcard interface) behaves the same way. A Broadcom Bluetooth adapter, a smartcard-only ControlVault (0a5c:5832) and a HID receiver stay undetected on every version. test/shell.d/hw-fingerprint-test.sh (25 passed), fingerprint-invitation-test.sh (1 passed), fingerprint-package-test.sh (18 passed) and ./test/cli all pass on the head. The PR's new test fails with the fix removed, so it tests the change.

Pushed. a7b704f: docs/file-layout.md said the detector finds USB readers "by their product string or vendor". It now names the interface string too. That is Markdown only, so nothing ran for it.

Second opinion. Codex Medium and muse-spark-1.3 (via pi, thinking high) both found no defect in the detection code. Both flagged the stale docs line, which is the commit above. Their independence is not guaranteed. I did not act on their smaller suggestions: a narrower glob, and matching Elan and FPC names on interfaces too. The current glob already skips everything without an interface file, and no reader on record needs the second.

Competing fixes. #8486 adds all of Broadcom's 0a5c, and #9524 adds only 0a5c:5843. #16021 is new. It detects ControlVault 3 (0a5c:5842–5845) by id and installs Broadcom's TOD driver for them. It deliberately leaves ControlVault 3+ (586x), the reader in #7424, undetected. Its description says ControlVault 3 also names its fingerprint reader only on an interface, so this PR should find those readers as well. Both reviewers and I think this one should win for detection. It is the oldest, and none of the others fixes the reader reported here without a broader guess. #16021's driver install is separate work this PR does not do. If both land, they change the same lines of the detector. Choosing is the maintainer's call.

For the maintainer. Once this detects a ControlVault 3+, the menu entry and the first-run invitation appear on that machine. Setup then installs libfprint-git, which has no driver for it, so enrollment fails. PAM is not touched. #7424 and this PR's description both say that, and it decides whether you want detection before a driver.

Still open. @eworkshop, could you run this head on the Dell Pro Max 16 and say what it prints?

curl -fsSL https://raw.githubusercontent.com/basecamp/omarchy/a7b704f7ed27e9e8db8ac0f4c6f76b540f81d37c/bin/omarchy-hw-fingerprint -o /tmp/hw-fingerprint-7726
bash /tmp/hw-fingerprint-7726; echo $?

0 means the reader was detected. It only reads /sys (and a platform's reader list, if one is installed) and changes nothing.

@OldJobobo

Copy link
Copy Markdown
Contributor Author

Merged current quattro, keeping both interface-name detection and the newer Apple/platform lifecycle documentation. Fingerprint detection, invitation and package suites pass locally; full VM CI and the current Greptile check pass. Real-reader acceptance remains pending; simulated sysfs coverage is not a substitute for that check.

--[ Pi :: gpt-6.1-sol ]--
--- on behalf of: @OldJobobo

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed again at f47e167, your merge of quattro. The detection change is the same as before and still holds. It now waits on the maintainer's decision below. A run on the real reader is still missing too.

What was run. On a disposable Omarchy VM, a fake sysfs tree laid out like #7424 (0a5c:5865, product 58200, interface Broadcom ControlVault 3+ w/FingerPrint) fails on quattro (e19607f), passes on this head, and fails again with the has_fingerprint_interface call removed. A ControlVault 3 (0a5c:5843, with a driver bound to its smartcard interface) does the same. A Broadcom Bluetooth adapter, a smartcard-only ControlVault and a HID receiver stay undetected. hw-fingerprint-test.sh (25 passed), fingerprint-invitation-test.sh (1 passed), fingerprint-package-test.sh (19 passed) and ./test/cli pass on the head, and the PR's new test fails with the fix removed. The branch still merges cleanly into current quattro.

Second opinion. Two reviewers read it: Codex Medium, and muse-wonder via pi at high thinking. Neither found a defect in the detector, the merge or the tests. Both raised the setup problem below. They disagree on order. Codex would land this one for detection, since it is the oldest and the only one that finds 5865. muse-wonder would land #16021 first and hold this one until something can drive a ControlVault 3+.

For the maintainer. Once this detects a ControlVault 3+, the first-run invitation and the menu entry appear on that machine. Setup then installs libfprint-git, which cannot drive that reader, so enrollment fails. That much was already known, and PAM is still left alone. What is new is the owner who drives the reader with a TOD stack they installed themselves (libfprint-tod and libfprint-2-tod1-broadcom-cv3plus, as @Younday describes on #9524). On quattro setup stops at "No fingerprint sensor detected" before installing anything. With this PR it reaches bin/omarchy-setup-security-fingerprint:153-156. omarchy-pkg-missing checks package names, so libfprint-git counts as missing there. It is then installed with --ask 4, and libfprint-git declares conflicts=(libfprint). If libfprint-tod provides libfprint, pacman offers to replace their working driver, and that replacement is accepted. I could not confirm libfprint-tod's package metadata from here. The same question came up on #9524.

Competing fixes. #16021 detects ControlVault 3 (0a5c:5842–5845) by id and installs Broadcom's TOD driver for it. It leaves 586x undetected, so it does not fix #7424. It does overlap this PR on ControlVault 3 detection and on the same lines of the detector. #8486 (all of Broadcom's 0a5c) is broader than needed, and #9524 (0a5c:5843 only) misses 5865. Whether detection should come before a driver, and in what order this and #16021 land, is the maintainer's call.

@eworkshop, the earlier request still stands, now at this head:

curl -fsSL https://raw.githubusercontent.com/basecamp/omarchy/f47e167fd2254166a72363300c73b975059b2b59/bin/omarchy-hw-fingerprint -o /tmp/hw-fingerprint-7726
bash /tmp/hw-fingerprint-7726; echo $?

A 0 means the reader was detected. It only reads /sys and changes nothing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working compatibility Make Omarchy work better on everything!

Projects

None yet

Development

Successfully merging this pull request may close these issues.

omarchy-hw-fingerprint misses readers named only in the USB interface descriptor (Dell ControlVault 3+, 0a5c:5865)

3 participants