Fix fingerprint sensor timeout on long-running lock sessions

[JeremieRodon]

Summary

This PR addresses issue #702 where fingerprint authentication stops working after the session is left locked for approximately 3-5 minutes (for me).

The root cause I identified is that keeping the fingerprint sensor in an active verification state indefinitely causes some device drivers to disconnect or disable the sensor, leading to a no-retry error in Hyprlock's fingerprint handler.

Changes

The solution introduces an inactivity timeout mechanism that automatically pauses fingerprint verification when no user input is detected, then resumes scanning when the user interacts with the lock screen:

1. New configuration parameter: auth:fingerprint:inactive_timeout

   • Default value: 30 seconds
   • When set to <= 0, the timeout is disabled (preserving previous behavior)
   • Configurable to suit different hardware and user preferences

2. Activity tracking: The fingerprint handler now monitors user input events:

   • Mouse movement
   • Mouse clicks
   • Keyboard input

3. Verification management:

   • After the configured timeout period with no activity, fingerprint verification is paused and the Fingerprint Sensor is released
   • When user activity is detected, verification automatically resumes and the Fingerprint Sensor is claimed again
   • The prompt message is cleared when paused to provide visual feedback to the user

Implementation Details

Modified files:

• src/auth/Fingerprint.cpp / .hpp: Core timeout logic and activity handling
• src/config/ConfigManager.cpp: New configuration parameter
• src/core/Seat.cpp: Mouse movement event tracking
• src/core/hyprlock.cpp / .hpp: New onMouseMove handler. Activity event propagation to fingerprint handler

Key technical choices:

• Uses a cancellable timer that resets on each activity event
• Non-destructive pause: verification is stopped and device released, but can be resumed
• Prompt clearing provides user feedback when in paused state

Configuration

Users can add this to their hyprlock.conf:

auth {
    fingerprint {
        enabled = true
        inactive_timeout = 30  # seconds, set to 0 to disable
    }
}

Discussion Points

I chose a 30-second default as a balance between:

• Keeping the sensor active for quick unlock attempts
• Preventing driver issues on extended lock sessions
• Reducing unnecessary hardware activity

It also means that the timeout is enabled by default. My rational is that I believe:

1. Others currently have the issue so...
2. I don't think it's a good idea to hold the sensor in a "read/verify" state indefinitely in general

Thoughts?

When the Fingerprint verification is paused, I decided to remove the $FPRINTPROMPT content to provide a kind of visual feedback to the user. This is based on the observation that $FPRINTPROMPT is initially empty when hyprlock start rendering.

Thoughts?

I added the new onMouseMove() event handler on CHyprlock mostly because I did not have any better idea. I'm really not knowledgeable in Hyprland ecosystem in general and there may be a better solution to detect that the user is AFK. I'm really all ears on the topic and will be happy to implement it another way if pointed in the right direction.

Thoughts?

Testing

Tested on my system, where I experience the fingerprint disconnection issue (Goodix Fingerprint Sensor 53xc). The timeout mechanism successfully prevents sensor driver disconnections while maintaining a responsive unlock experience.

---

Fixes #702

---

[Jackaed]

These changes do fix the issue on my system!

I don't know if Hyprland follows the general conventions on commit messages, but you may want to change the commit message to a short title and an explanatory body. See https://www.conventionalcommits.org/en/v1.0.0/.

[Jackaed]

Update: This doesn't fix the issues I was experiencing (which is the issue described in #702 (comment)). This doesn't mean that this shouldn't be merged, but I don't think it fixes #702.

[tauraamui]

I have the exact same issue, using a custom build of libfprint to support my USB based Chipsailing GS9711Fingprint device.

[JeremieRodon]

@Jackaed

Update: This doesn't fix the issues I was experiencing (which is the issue described in #702 (comment)). This doesn't mean that this shouldn't be merged, but I don't think it fixes #702.

Sorry to hear that 🙁 I'll admit it is difficult to assert exactly what is the issue in #702 as the original report, your comment and mine could well be 3 separate problems. The original report logs are not really helpful. If we want to understand what happens, we ought to correlate both hyprlock and fprintd logs. As hyprlock do not timestamp its log, I debugged my issue in real time using other TTYs while hyprlock was running and I would advise anyone to do the same to make sure how events correlate.

@tauraamui

I have the exact same issue, using a custom build of libfprint to support my USB based Chipsailing GS9711Fingprint device.

Do you mean you have the same issue as me, same issue as @Jackaed or just that my PR does not fix your problem whatever it is?

[PointerDilemma]

While the idea is ok, I don't believe you actually thought about what this code does.
With this you literally have to move the mouse or press a key before unlocking with fingerprint by default.
I believe a bunch of people do use fingerprint and this breaks it for them.
All the AI comments in the code are not helpful. The PR description is also not written by you and I hate that.
Come back with a PR that introduces off by default, or, better, figure out why verification dies and how to restart it. I do believe that fprintd should handle stuff like suspend and all that.

[JeremieRodon]

While the idea is ok, I don't believe you actually thought about what this code does. With this you literally have to move the mouse or press a key before unlocking with fingerprint by default. I believe a bunch of people do use fingerprint and this breaks it for them.

I am using fingerprint and this code change is what's been enabling me to use it daily with Hyprlock for 3 weeks now. I did thought about what this do and I argued my choice in the PR description.

1. Most people, when they come back to their locked computer, will have to move their mouse or press a key to turn their screen back on or wake-up their OS, so I did not thought it was a problem to ride on that fact.
2. I really believe it is not a good idea to forcibly maintain the FP reader powered and actively reading for the whole lock duration, which can be hours.
3. I thought the extended FP reader activity is causing problem, and I may have been over-eager on that. Sorry.

I will also admit that my time writing C was 15 years ago and I never wrote more than a few lines of C++ so I chose the easiest path I could to fix the issue. I believe I made it clear that I was actively asking for suggestions on how to better detect the "AFK-ness" of the user.

All the AI comments in the code are not helpful.

You are the second person pointing that comments are not helpful. I will abide and remove them, that's your project. Just know that as an external contributor not familiar with the project nor C++, these kind of unhelpful comments would have saved me at least an hour that instead was dedicated to understand what does what. But I get that they may be redundant for you.

The PR description is also not written by you and I hate that.

I did use Claude to generate the original text, then I modified it to remove false claims. I did not care about the writing style though, sorry for that I suppose.

Come back with a PR that introduces off by default

Ok.

or, better, figure out why verification dies and how to restart it. I do believe that fprintd should handle stuff like suspend and all that.

You may discuss that with the people responsible for the behavior/design of fprintd. In the meantime, it seems to work by allowing a single client at a time to "claim" the fingerprint reader device, which seems to put it in a "actively reading" mode (i.e. powered) until it is "released" by that client, and only that client can release it. The issue on my system, with my particular device, is that the driver does not like to power the device for more than ~3min as I described in #702 (comment) . Hyprlock not only fails to unlock with fingerprint at this point, but it also does not "release" the device, which makes the daemon forbid its usage by any other client (including PAM) until the daemon is restarted.

There is only two fixes I can imagine for that in Hyprlock:

• Gracefully handling the reported failure and try to release then re-claim the device, but:
  • I don't believe it is a good idea to maintain such devices in "active read mode" (i.e. powered) for eternity
  • I don't think I'm capable of writing that correctly anyway
• Not maintain a permanent "active read" state:
  • I do believe it is the right way to interact with fprintd as it is.