Add Credential Manager support and improve WebAuthnLinux authenticator functionality

[Karloss1234]

Core authenticator improvements (webauthn-authenticator.js)

Major improvements have been made to the WebAuthn authenticator implementation. It is now a functional Linux software Passkey authenticator with built-in credential management capabilities.

Summary

This PR improves WebAuthnLinux by adding Credential Manager functionality, improving credential persistence, and strengthening browser/native messaging integration.

The main areas changed are:

• Credential management and storage (view, rename, and delete credentials)
• Authenticator state handling
• WebAuthn metadata improvements
• Firefox and Chrome compatibility improvements
• Native messaging installation improvements
• Extensive testing on Kubuntu, Fedora and Manjaro with Firefox/Librewolf and Chrome/Brave.
• UPDATE, August 2026: Addition of install wizard.

Testing has successfully verified Passkey registration and login with:

• Google
• Microsoft
• GitHub
• Government tax reporting websites
• webauthn.io
• Proton.me

Specific changes

Credential management

• Added improved credential storage handling and persistence.
• Improved loading and saving of system_credentials through browser storage.
• Added reliable credential retrieval after extension restart.
• Improved handling of stored credential metadata.
• Added credential management operations including renaming and deleting credentials.

Authenticator reliability

• Improved authenticator initialisation and state handling.
• Improved asynchronous storage operations using modern Promise/async patterns.
• Reduced the risk of credential storage inconsistencies.
• Improved handling of authenticator state across browser sessions.

WebAuthn compatibility

]- Improved authenticator metadata handling, including AAGUID management.

• Improved compatibility with browser WebAuthn flows.
• Maintained compatibility with existing WebAuthn registration and authentication processes.

Native messaging installation improvements

• Simplified native host installation.
• Removed the need for users to manually create the native messaging manifest.
• Added support for different Firefox configuration paths used by distributions such as Fedora.
• Improved installer verification output.

Debugging and development

• Added additional logging around credential operations and storage events.
• Improved visibility of authenticator state transitions during testing.

Breaking changes

Installing over Previous developments produces errors. Delete all traces of previous installs.

[rgpublic]

This PR is a huge progress. The installation is currently still very cumbersome though. I had to upload under addons.mozilla.org and change the ID (because of duplicate ID error) and also change the ID in the installer script and download the signed XPI. Any other attempt to make the temporary addon permanent failed (tried the Firefox Developer Version, disabled signature verification in about:config, yada yada - to no avail). But this will hopefully be better when there is an official version on addons.mozilla.org.

Now, I have a permanent addon in the browser and a popup window appears with a button. But unfortunately, the fingerprint doesnt verify:

WebAuthnLinux Authenticator
Error: Fingerprint Failed: Failed: Using device /net/reactivated/Fprint/Device/0 Listing enrolled fingers: - #0: right-index-finger Verify started! Verifying: right-index-finger Verify result: verify-no-match (done)

fprintd-verify on the command-line works. But no matter how often I try, always verify-no-match with the add-on.

[Karloss1234]

Good to see someone testing it. Thanks for trying the fork.

I did make one small change in /WebAuthnLinux/native/webauthnlinux_host.py: I changed the fingerprint command from:

fprintd-verify to: fprintd-verify -f any

Would you mind testing these two commands in your terminal and letting me know if there is any difference?

fprintd-verify

and:

fprintd-verify -f any

The extension error you posted is identical to what I get if I intentionally use the wrong finger, so I want to confirm whether the command behaves differently on your system.

If you like, you can also temporarily edit webauthnlinux_host.py back to the original command and test the extension again (remember to restart Firefox).

Could you also let me know:

Linux distribution and version
fingerprint sensor model (lsusb output would help)
fprintd --version

Yes, the installation procedure still needs a lot of work.

For my setup, setting: xpinstall.signatures.required = false allows the extension to be installed permanently.

I am using the latest Firefox installed from the Kubuntu APT repository (not Snap or Flatpak), and I also test with LibreWolf.

It would be useful to know whether this behaves differently on other Firefox builds or distributions. Can you let me know your Firefox Install environment?

Thanks!`

[Karloss1234]

I have been playing around with Flatpack Firefox.
The extension loads, but I can't get fprintd-verify to load. The fingerprint backend integration requires a future D-Bus/portal implementation.
Installing this extension in Snap or Flatpack Firefox is a nightmare.
Only load extension in APT or DNF installed browsers.

[rgpublic]

@Karloss1234 : My coworker took that laptop home, so I can only check next week. A few things I can already say though:

• There is no "fprintd" executable. Only "fprintd-verify", "fprintd-enroll" etc. There is no version argument.
• We're all on Manjaro Linux 26.1 "Bian-May".
• Package manager says fprintd 1.94.5-2
• I'm suprised xpinstall.signatures.required=false worked for you per https://wiki.mozilla.org/Add-ons/Extension_Signing this should only work for Firefox Developer or Nightly Releases. We temporarily tried to use the Firefox Developer release yesterday but setting this to false had not effect.
• We noticed that we can't drag and drop the "extension" folder to add-ons - we had to zip the extension folder into a file and drag and drop that. Alternatively we could indeed install as a temporary addon like described in the README via. Add temporary addon and selecting the manifest.json but this addon always vanished after restarting Firefox.
• I guess getting this to work with Snap/Flatback will still be on a whole other level of difficulty so I would recommend tackling normale Firefox releases in the first place. We didn't use a Snap/Flatback edition but the regular Firefox edition from the official Manjaro extra repository.
• The only way we could install it was by uploading the addon on my private addons.mozilla.org account and downloading the signed version from there but that required changing the ID.
• I will try next week the commands you suggested. Although I don't think it's a wrong finger issue. We only used fprintd-enroll without any arguments and there is only one finger registered - the default right index finger. fprintd-verify (without arguments) worked. Using the fingerprint e.g. for GNOME sudo dialog windows (e.g. during package installations) worked flawlessly.

[Karloss1234]

Okay, I'll look to making an install of Manjaro and see if I get the same.

Let me know about fprintd-verify -f any command run from the terminal?

Does which fprintd-verify return /usr/bin/fprintd-verify?

It appears that some distros allow xpinstall.signatures.required = false, such as Kubuntu APT firefox.

[Karloss1234]

Updated the installer and tested the new installation flow. See fork README for install instructions.

Changes:

• Added an interactive installer wizard that asks for Firefox-family or Chromium-family browsers.
• Added branch warning/checking to help prevent installing from the unsupported main branch.
• Added Firefox-family manifest support (manifest.firefox.json).
• Improved Firefox/LibreWolf native messaging host handling.
• Improved Chromium-family browser detection and added per-browser selection:
  • Chrome
  • Chromium
  • Brave
  • Microsoft Edge
  • Vivaldi
  • Opera
• Improved native host reliability by using an explicit fprintd-verify path.

Testing completed:

• Kubuntu:
  • Firefox-family / Firefox Permanent and LibreWolf Permanent XPI installs tested successfully.
  • Google Chrome successful.
• Fedora:
  • Chromium tested successfully.
  • Brave tested successfully.
• Manjaro (fresh distro install):
  • Firefox temporary tested successfully. (Manjaro Firefox blocks permanent install of unsigned extensions.)
  • Chromium tested successfully.

The installer is now intended to make the correct branch and browser-family setup clearer for normal users rather than only developers.

[samveen]

This PR is a huge progress. The installation is currently still very cumbersome though. I had to upload under addons.mozilla.org and change the ID (because of duplicate ID error) and also change the ID in the installer script and download the signed XPI. Any other attempt to make the temporary addon permanent failed (tried the Firefox Developer Version, disabled signature verification in about:config, yada yada - to no avail). But this will hopefully be better when there is an official version on addons.mozilla.org.

This started off as a solution to exactly one problem I was facing. I truthfully did not expect a 2nd user for this plugin 😅 . I'll work on pipelining the project to firefox addons.

Now, I have a permanent addon in the browser and a popup window appears with a button. But unfortunately, the fingerprint doesnt verify:

WebAuthnLinux Authenticator
Error: Fingerprint Failed: Failed: Using device /net/reactivated/Fprint/Device/0 Listing enrolled fingers: - #0: right-index-finger Verify started! Verifying: right-index-finger Verify result: verify-no-match (done)

fprintd-verify on the command-line works. But no matter how often I try, always verify-no-match with the add-on.

Others have pointed out the issue too, where only the first enrolled fingerprint is being tested. Let me merge that, once I have the responses from the contributor.

[samveen]

Thank you for your contribution 🥇 .

I'll work on reviewing, merging and releasing this, but please bear with me a tiny bit more.

Core authenticator improvements (webauthn-authenticator.js)

Major improvements have been made to the WebAuthn authenticator implementation. It is now a functional Linux software Passkey authenticator with built-in credential management capabilities.

[samveen]

@Karloss1234 That's an awesome update. Does a lot of required fixes.

I do have a couple of requests:

• Some of the comments that have been removed, which should stay in place.
• There should be no white space at the ends of lines, not multiple consecutive empty lines.

[Karloss1234]

I went through the branch and cleaned up the diff:

-restored upstream explanatory comments
-removed trailing whitespace and duplicate blank lines
-restructured a few lines of code so that they comply with the original samveen code structure
-removed temporary debugging output from background.js, that was no longer required

There is still debugging in webauthn-authenticator.js. I was of the mind that I would have another go at improving the extension at some point, and the existing debugging may be useful for myself or other contributors. But I can clear it out if you want. It can always be removed with later efforts.

The install wizard is a little backwards for Chrome install (it asks for Extension ID before asking for desired install browser), but at least it works and is a big improvement.

The updated commit is now pushed.

[rgpublic]

Okay, thanks for all the changes. The problem with the unrecognized fingerprint was my fault. A bit embarassing. fprintd --verify did in fact also show verify-no-match on the command line, but because it immediately returned I didn't notice this as an error, didnt notice the word "no" and thought it had verified. The main problem was that my coworker swiped over the sensor but apparently this sensor just requires a single touch. When we re-enrolled the fingerprint with single touch it worked.

I still don't understand why there isn't much more interest of a wider audience in this. Linux on a laptop used to be an absolute nightmare (no audio, no keyboard backlight, sometimes even no graphics) just a few years ago. Now, with various laptops I have zero problems except this one. It's really great that I can now use the fingerprint for web authentication. Thank you so much for making this.

The only part missing now is an updated extension on the addon store so we don't have to jump through all these hoops to install it :-)

And very minor, the dialog that appears could perhaps one day need an UI designer ;-) And the additional necessary click on the button is of course unnecessary, but I don't know whether there's a way to avoid that. But that's nitpicking of course. This is otherwise just brilliant and a major step forward to bring the Linux laptop experience on par with The Evil OS. Thanks again for making this!

[Karloss1234]

I used Windows Hello Finger scan all the time. I'm surprised of the lack of demand for this as well.

Yes, I'd like to do some updates for the UI. Some ideas:

• Make the UI more modern looking.
• Skip the extra button click and go straight to 'scan your finger' (this would happen after further stability testing).
• Port the extension directly into dbus-service (skipping over fprind-verify). This would result in the UI displaying any errors after every swipe.

[samveen]

-restored upstream explanatory comments
-removed trailing whitespace and duplicate blank lines
-restructured a few lines of code so that they comply with the original samveen code structure

Perfect.

-removed temporary debugging output from background.js, that was no longer required

@Karloss1234 no no no no. Please put all that beautiful debug info back in there 🙏 . This was almost perfect, as-was. Maybe add a debug flag, defaulting to false, to keep things sanitized.

There is still debugging in webauthn-authenticator.js. I was of the mind that I would have another go at improving the extension at some point, and the existing debugging may be useful for myself or other contributors. But I can clear it out if you want. It can always be removed with later efforts.

We want and love debug information. Expand and extent it as much as you want.

The install wizard is a little backwards for Chrome install (it asks for Extension ID before asking for desired install browser), but at least it works and is a big improvement.

I'll work on registering a release against the chrome store as well. And see if I can integrate the deployment process into the repository via release tagging.

I used Windows Hello Finger scan all the time. I'm surprised of the lack of demand for this as well.

Windows and Mac have the advantage (and disadvantage) of centralized control and policy, so its easy to implement a platform framework. Linux is about freedom, and that comes at the cost of freedom to not conform to a unified platform architecture, if you see issues with the architecture. that said, there are major efforts to standardize the authn layer for linux, but it'll take time to spread wide.

Till then, we have this (which also explains why I put linux in the name 😆 )

• Make the UI more modern looking.

• Skip the extra button click and go straight to 'scan your finger' (this would happen after further stability testing).

• Port the extension directly into dbus-service (skipping over fprind-verify). This would result in the UI displaying any errors after every swipe.

Keep that for the next PR. Just put back the debug info, and I'll proceed with version update, new firefox version release, and investigating and releasing via chrome+chromium store.

[samveen]

@Karloss1234 @rgpublic

I'm unable to merge this as-is, as the commits are unsigned:

I'll pull the changes on my end, squash them into a single commit, and push a signed commit into the repo via a new PR. including the required fixes to the indentation and comment restoration.

Additionally, I will create 2 ticket:

• for extended debugging and an associated flag @Karloss1234
• ticket for UI modernization assigned to the both of you. Go wild!!

In the mean time, please look into signing your commits with GPG at https://git-scm.com/book/ms/v2/Git-Tools-Signing-Your-Work, so that:

• Your work stays your own, proving your ownership of it
• No one can impersonate you and push commits under your name.
• Github's merge checks pass, allowing your contributions to be merged 😮‍💨

[Karloss1234]

GPG signing is now configured locally. Future commits from me will be signed and verified by GitHub. Thanks for the guidance.

Restored the background.js debug logging as requested.

The additional logging is useful for diagnosing message flow between the content script, background script, and authenticator popup. I have kept the existing behaviour changes (such as forwarding responses only to the requesting tab) while restoring the diagnostic information.

Future improvements could move this behind a debug flag as discussed.

As much as I am not a fan of Chrome, it would be great if it were added to the Chrome extension library to get more user feedback.

[Karloss1234]

Tested and fixed the Firefox/LibreWolf native messaging directory handling. I did a fresh install of Manjaro and found that the messaging host fall back installation directory was wrong.

The installer now consistently uses only ~/.mozilla/native-messaging-hosts, which is the location used by Firefox/LibreWolf on Manjaro, Kubuntu, and Fedora.

The previous fallback incorrectly created/used ~/.config/mozilla/native-messaging-hosts. I haven't come across any system/browser which uses this directory. This directory was an addition by myself, which should have never been made, and is now totally removed.

Fix committed and pushed as f1596fb.