Thunderbird Support for Browserpass

[thardeck]

Summary

This PR adds Thunderbird email client support to the Browserpass extension. It allows users to store and retrieve email credentials (IMAP, SMTP, POP3) and OAuth tokens (Gmail, Microsoft, Fastmail) from their pass password store instead of Thunderbird's built-in password manager.

I am already running the implementation locally since a few days. I have tried different setups, fixed several issues on the way and also ran into Thunderbird issues.
For debugging purposes I have added quite some logging, which should not hurt and probably at least be kept until more users tried the extension.

I am interested in this feature myself and got some time to work on this.
It turned out to be much more code then originally anticipated but there were a lot of edge cases to cover and will probably be some more.
Any feedback is appreciated.

Features

• Mail Protocol Support: Automatic password retrieval for IMAP, SMTP, and POP3 accounts
• OAuth2 Token Storage: Refresh token storage for Gmail, Microsoft, and Fastmail
• CalDAV/CardDAV: OAuth authentication for calendar and contacts
• Automatic Migration: Credentials are migrated from Thunderbird's password manager to pass
• Credential Saving: New credentials entered in Thunderbird are automatically saved to pass
• OAuth Window Autofill: Clipboard-based autofill for OAuth browser windows with keyboard shortcuts

Technical Implementation

Why Separate Builds?

Thunderbird requires WebExtension Experiments to hook into its authentication system, which Firefox doesn't allow for non-privileged add-ons. The experiment API provides access to:

• MsgAuthPrompt - Intercepts IMAP/SMTP/POP3 password prompts
• OAuth2Module - Intercepts OAuth token requests for CalDAV/CardDAV
• browserRequest - Monitors OAuth browser windows for autofill

Therefore, the extension is built separately:

• Firefox: make firefox - Standard browser extension
• Thunderbird: make thunderbird - Includes experimental credentials API

The core extension code remains shared; only the manifest and experiment files differ.

Architecture

Thunderbird Auth Request
        ↓
implementation.js (WebExtension Experiment)
  - Hooks MsgAuthPrompt (IMAP/SMTP/POP3)
  - Hooks OAuth2Module (CalDAV/CardDAV)
  - Hooks browserRequest (OAuth windows)
        ↓
Event Emitters → background.js
        ↓
thunderbird.js
  - Matches credentials from pass
  - Stores new credentials to pass
        ↓
browserpass-native (GPG decryption)

Requirements

• Thunderbird 128.0+: Uses WebExtension Experiments API
• browserpass-native: Required for GPG decryption - run make hosts-thunderbird-user to register
• pass: Standard Unix password manager with GPG

Testing

1. Build extension: make thunderbird
2. Package as XPI: cd thunderbird && zip -r browserpass-thunderbird.xpi *
3. Install in Thunderbird via Add-ons → Install from File
4. Open Thunderbird Error Console with Ctrl+Shift+J
5. Test credential retrieval for existing email accounts
6. Test OAuth authentication for Google/Microsoft accounts
7. Test migration of existing Thunderbird credentials

Password Store Organization

~/.password-store/
├── imap/
│   └── mail.example.com.gpg            # IMAP server credentials
├── smtp/
│   └── mail.example.com.gpg            # SMTP server credentials
├── pop3/
│   └── pop.example.com.gpg             # POP3 server credentials
├── https/
│   └── sso.example.com.gpg             # OAuth identity provider credentials
└── oauth/
    ├── mail/
    │   └── [email protected]        # OAuth mail tokens
    ├── caldav/
    │   └── [email protected]        # Calendar OAuth tokens
    └── carddav/
        └── [email protected]        # Contacts OAuth tokens

The https/ directory is for OAuth identity provider login pages (e.g., Google, Okta) that appear in the OAuth browser window during account setup.

Design Decisions

1. Offline Startup Control

Thunderbird is forced to start offline to prevent auth requests before the extension is ready (This seems to be a Thunderbird issue). Once hooks are registered, Thunderbird goes online automatically. User's "Always offline" preference is respected.

2. OAuth Token Caching

Tokens retrieved from pass are cached for 8 hours to reduce GPG decryption overhead. Cache is cleared on token update or after the timeout expires.

3. Credential Migration

Credentials are migrated from Thunderbird's password manager to pass. Existing pass entries are not overwritten.

4. Service-Specific OAuth Storage

OAuth tokens are stored in service-specific directories (oauth/mail/, oauth/caldav/, oauth/carddav/) because different services may request tokens with different scopes. A calendar app might request a token with calendar-only permissions, while mail needs separate permissions. Sharing a single token would break services that require permissions the new token doesn't have.

Known Limitations

• CalDAV Startup OAuth Windows: CalDAV calendars without offline cache may trigger OAuth windows at startup before the extension hooks are ready (This seems to be a Thunderbird issue). The extension automatically closes these windows and retries once initialization is complete
• OAuth Autofill Method: OAuth browser window autofill uses clipboard-based injection with keyboard shortcuts rather than direct DOM manipulation, due to security restrictions in browser windows.

Breaking Changes

None - this is additive functionality that is mainly added to the Thunderbird extension.

Related PRs

A companion PR to browserpass-native is required to register the native host for Thunderbird:

• Adds hosts-thunderbird-user and hosts-thunderbird Makefile targets
• Registers firefox-host.json native messaging manifest

References

• pass - Standard Unix password manager
• WebExtension Experiments - Thunderbird API documentation
• keepassxc-mail - Inspired the general architecture approach (offline startup control, WebExtension Experiments, credential event handling)

[max-baz]

This is an impressive amount of work, thanks for sharing! It will take some time to go through, as it's quite a lot of code, but I'll try to not delay it much.

@erayd do you have time to review this as well?

A few initial questions & remarks, mostly based on PR description:

1. It looks like OAuth tokens are cached in memory, but regular credentials are not? How come, is the frequency really that different? I'd imagine that synchronizing email over regular IMAP will happen just as frequently as using OAuth tokens?
2. I'm wondering whether credentials migration is not a bit too invasive? I understand the convenience, but an unprompted dump of credentials feels a bit off. Have you considered alternatives, e.g. a shell script to explicitly call, to perform the migration? Not saying that this is a way to go, just asking.
3. Have you considered some alternatives to the password store organization? Again, not saying that your choice is wrong, but curios to explore ideas. For example, instead of multiple files with the same name under different folders, why not have all that info in a single file, that needs to be decrypted once? Instead of enforcing a specific path, why not make use of the popup to find the credentials anywhere in the password store, and perhaps cache the last choice with the ability to override it?
4. I didn't really understand the "Known limitations" section, maybe it will get clear once I test it... But is it something you would like to address before merging the PR, or this is just explaining reasoning behind the implementation details?
5. GPG decryption overheard is a good point you mention, I would say that even more important point is that quite a lot of users of this extensions have Yubikeys, which requires a physical touch for every single decryption operation (some have a few seconds cache, but not all).
6. In order to avoid merging the PR while you are still working on it, could you drop a note here whenever you feel like you have completed all the work you had in mind for the PR and are happy to see it merged? The same would apply once we go through code review and potentially think of some improvement ideas.

[thardeck]

Many thanks for your quick response.

1. Good question. It seems that the IMAP password gets cached by Thunderbird already - that's why I never looked into it. I will test this over a longer time now though to be sure.
2. Yes, I thought about this too. I does feels a bit invasive, at the same time the credentials are only copied from a local encrypted storage to another local encrypted storage, so it is not like we are transferring something to the cloud.
   Initially I have tried to read the credentials from pass, when they are not there fall back to the Thunderbird password storage, and then migrate that credential. I ran into quite some issues with this though and it seemed overly complex, so I went for the one-time migration instead. Possible solutions:
   1. Show a notification asking the user for migration. This would also require to store if the migration was tried and probably have a button to restart it in the Browserpass preferences. Feels a bit complex in terms of UI interaction and shared extension code.
   2. Same as above, but only explaining how to migrate and having a button the in the Browserpass preferences.
   3. Shell script might be an option but not a very convenient one. I would also somehow need to be able to access the Thunderbird password store, which will most likely need quite some additional code (did not verify if there is a command line tool for it).
   4. On-demand migration, like I have mentioned, if pass does not provide the credentials look them up in the password storage and migrate them. This variant does not provide a clear separation between those two password storages though (you do not know where the credentials come from).
3. In regards to directory structure I am flexible, but I did not think about and would not like the idea to deviate from the pass concept and store all Thunderbird credentials in one file.
   Having one file means I need a file structure concept and parsing which should be pass compatible but at the same time stores multiple passwords and tokens in one file.
   With the current file structure, you can easily link the SMTP password to IMAP withouth any additional implementation required. The same you could do for OAuth tokens.
   You can link your HTTPS OAuth Login password to your regular Firefox pass directory, so have every credential only in one place while everything else links to it.
   
   In regards to a popup selecting the relevant credential, to me Thunderbird authentication should not be interactive. I have my mail and calendar and so on in it and would not like to be asked on every restart which credential I would like to enter or go through a dir structure. It should just work without the possibility of selecting a wrong domain, similar to a passkey.
   
   Since Thunderbird does usually not have that many credentials, what about a single directory with protocols in front:

~/.password-store/
└── thunderbird/
    └── imap-mail.example.com.gpg            # IMAP server credentials
    └── smtp-mail.example.com.gpg            # SMTP server credentials
    └── oauth-mail-sso.example.com.gpg       # OAuth mail tokens
    └── https-sso.example.com.gpg            # OAuth identity provider credentials

4. Fair point, maybe I should have phrased it differently.
   I am not directly planning to work on those although I would like to report the underlying issue of the first mentioned "limitation" against Thunderbird.
   Since the workaround for the Thunderbird issue is that my implementation closes a window at the start, I thought it might be good to mention this in the pull request.
   
   When trying to implement the OAuth Autofill I ran into quite some issues with the internal Thunderbird browser's security restrictions, and came up with the clipboard solution which I started to like. I am open to look at this again though if you prefer it - but OAuth re-authentication should not happen that often anyway.
5. Yes, I also have a Yubikey. That's why I have implemented the eight hour caching which I thought might be not liked by some.
   I have also fixed a matching issue in this regards when searching for the OAuth token.
   
   The OAuth implementation might be overengineered and could potentially be improved in regards to decryption overhead, because Thunderbird at the moment only stores one OAuth token in its password storage per domain.
   When I tested this though I realized - at least in combination with Google - that if you remove your token and the calendar is checked first - then Google provides you with a token which only has permissions for the calendar, so this would break your carddav and caldav authentication. This would lead in the best case (Thunderbird carddav at the moment just fails silently in case of authentication issues) to reauthentication windows and so on.
   In general the OAuth token implementation in Thunderbird feels still a bit experimental but is also quite complex anyway.
   
   Maybe the best and least complex solution would be to just go for a single token and when there is an issue the user needs to manually make sure to use the correct OAuth authentication path.
6. I think my pull request is ready for review, but if you know already that certain behavior should be changed - the migration for example or OAuth simplification - then I would implement that before your initial review - so let me know beforehand.
   There is always room for improvement but at a certain point it is good to get feedback and then iterate on that.

[thardeck]

I am using the extension now for over two weeks and did not run into any issues so far.
Nevertheless I am planning to refactor at least the following things over Christmas.

• Most likely reduce the logic to use one OAuth token per domain/username to simplify the whole logic - I will test around a bit if the permission issue can be worked around
• Look into the internal caching, because it seems Thunderbird also caches Oauth tokens too - during testing I played too much around with removing/re-adding accounts, restarting Thunderbird and changing things to realize this and it seems Thunderbird caches the tokens per task, so different calendars still ask each time for the same token
• Try to implement the on-demand migration, so requested credentials, which are not in pass but in Thunderbird password storage - should be migrated

Let me know if anything else should be changed.

[thardeck]

I looked into this over the holidays and it is possible to consolidate the OAuth token to one entry.
The issue is that Thunderbird does ignore the offline mode for the calendar and when there is no OAuth entry in the password storage, then it requests in case of GMail a new token which seems to recall the previous one forcing for a re-authentication in case of the calendar.
The new token though has only permissions for the Google Calendar so the carddav and mail would fail if we only have one token.

While my initial implementation takes care of the issue, it is still not as nice as having a consolidated token, especially when a Yubikey with manual interaction for each encryption is used.
A work around is to have the token also in the Thunderbird password storage - so it is there during start - but this kind of defeats the purpose of this addon.

So I think the issue needs to be fixed in Thunderbird first. I will create an issue and maybe try to fix the issue myself when I have some spare time.

I will keep this thread updated.