Help Bitwarden test the new Manifest v3 Chrome extension and provide feedback: Use the
Google form, submit an issue inGitHub, or directly on thisReddit thread.
The
Every extension is created with a
The push to Manifest v3 spurred the formation of the
Although Manifest v3 was announced in 2019, the transition has been a multi-year effort; requiring close coordination between Chrome and the developer community to surface and remediate migration issues before Manifest v2 is deprecated. Now that many issues have been resolved, Google has resumed the deprecation
As Bitwarden upgraded its browser extension to Manifest v3, it required a significant architectural shift in structure, affecting how the extension operated. Here is how Bitwarden addressed the challenges posed by this new architectural approach and what lies ahead for Manifest v3 extensions.
What changed with Manifest v3?
Manifest v3 introduced the following changes for browser extensions, including:
Heavily limiting the usage of remotely executed code within a browser extension
Limiting how thoroughly and frequently a browser extension can intercept and interact with web requests as a user browses the internet
Limiting shared memory space to 10MB
Providing guardrails for how browser extensions can trigger arbitrarily executed or dynamically injected code
Removing redundancies within the browser extensions API to provide a better developer experience
Moving the core background logic of the extension from background pages to service workers
Bitwarden already supported most of these changes in the Manifest v2 extension due to a strong company stance on security and privacy, making it easy to comply with the tightened security requirements of Manifest v3. However, the move from background pages to service workers caused a significant architectural impact and required the most planning and solution design.
What are service workers?
Background pages function similarly to an open tab within your browser. They have access to the same features as a web page, but exist in a non-visible context. In the Manifest v2-supported browser extension, a
A
There are many benefits to using service workers. A service worker is most analogous to a web worker that a website can create.
In theory, service workers would encourage the development of performant extensions that only act when necessary and do not persist or consume resources in an active user session. However, the non-persistent aspect of the service worker presented the largest challenge for the Bitwarden engineering team in transitioning to Manifest v3, particularly to the unlimited size of Bitwarden vaults and maintaining vault security.
The solution to support service workers
To support service workers and the overall update to Manifest v3, Bitwarden developed a new architecture across its services that does the following:
Removes reliance on global memory due to the transition away from background pages
Introduces a state framework that enables memory references using observables
Stores an ephemeral, encrypted local backup during the user session to support large accounts given the ephemeral nature of service workers and limited memory allocation
The reliance on global memory with background pages
The Manifest v2-supported browser extension leveraged a persistent background page, which could directly provide data to different contexts of the extension. This enabled Bitwarden to access and update data by referencing the background page's global memory, regardless of where the data was needed.
This background page memory reference ensured that vault data did not require unnecessary processing and decryption for usage. Any modifications to user data within the extension would be instantly reflected throughout the extension's state, the current condition of the extension’s data.
The architectural approach for Bitwarden Manifest v2 extension
Moving away from referencing global memory using a state provider framework
By transitioning away from background pages, Manifest v3 removes the ability for browser extensions to access global memory. This introduces significant problems to the above architecture. Since a service worker can no longer directly share memory with extension popups, changes in the popup need to be propagated down into the service worker and vice versa.
For example, the service worker may wake up to automatically lock a vault, but that information needs to be propagated to any extension windows that may be open, rather than relying on a single pool of memory to synchronize each context. Similarly, actions taken in the UI need to be sent to the service worker to coordinate offscreen events, such as resetting auto lock timers, updating context menus and autofill, and clipboard manipulation.
To address this issue, Bitwarden has implemented a state framework that heavily relies on
These observables emit updates when modified which are then broadcast through ports, thereby propagating changes in state throughout the extension. This approach enables the extension to react to updates in stateful data across its various contexts of operation.
The implementation of this state management framework eliminates the necessity for a direct memory reference to the background page, all while upholding the performance of the extension. This resulted in a highly-responsive browser extension that synchronizes state across all execution contexts.
Supporting non-persistent service workers with local storage
The service worker introduced in Manifest v3 is ephemeral, meaning that stateful data in the service worker can be lost at any time. Consequently, data required for the Bitwarden extension must now be stored either in a limited, memory-only session storage or in some form of disk-based local storage.
To accommodate service workers and manage this data, we categorize state into two types: limited and unlimited. Examples of limited data include a user's account ID, email, or billing information. Unlimited data encompasses vault items, collections, or folders, with no preset limit and therefore not guaranteed to fit within a specific memory allocation.
Limited data is stored in a new storage location introduced by Manifest v3, known as
Unlimited data is stored in
When an application element outside of the background script, such as the extension pop-up, needs to manage state, it communicates with the service worker to update its stateful data through extension messaging. This ensures that the service worker remains the "source of truth" for all actions requiring stateful data, including the pop-up or content scripts utilized during the user session.
If the service worker becomes deactivated or is turned off, both session-stored and on-disk encrypted user data remains and is used to re-initialize the browser extension's logic once the service worker becomes active again.
Upholding the security and end-to-end encryption of vault data in local storage
Now that data is being locally stored, Bitwarden must ensure that this is also covered by end-to-end encryption in concert with
To facilitate this encryption process, a session key is generated each time the browser is opened. All locally stored data is then encrypted and decrypted using this key. Once the browser session is terminated, the session key is discarded rendering any previously stored encrypted data unusable. This ensures that any sensitive data retrieved from local storage cannot be decrypted outside of the current user session.
What’s next?
The Manifest v3-supported browser extension is now available as a beta, which can be downloaded from the
As the landscape for browser extensions continues to evolve, industry professionals will continue collaborating on guidelines for browser extension development. Bitwarden remains committed to
Help Bitwarden test the new Manifest v3 Chrome extension
Over the past year, the Bitwarden team has been adapting the browser extension to these new requirements. It is a significant upgrade and the team is asking the broader community to test by downloading the beta from the
You can install it side-by-side with your main Bitwarden browser extension, or disable the main Bitwarden extension during testing so that they do no conflict with one another.
There are several ways to provide feedback:
Use the
Google formSubmit an issue in
GitHubPost directly on this
Reddit thread