Bitwarden transitions from Manifest v2 to v3

Help Bitwarden test the new Manifest v3 Chrome extension and provide feedback: Use the Google form, submit an issue in GitHub, or directly on this Reddit thread.

The Bitwarden browser extension is utilized on over 6 million devices and serves as the primary interface for how users save and auto-fill login credentials to access their key websites. These kinds of extension features are facilitated through extension APIs, provided by the underlying browser, empowering extension developers to enhance the browsing experience for users.  

Every extension is created with a manifest.json file in its root directory that informs the browser about the functionality of the extension. The previous version of this manifest, Manifest v2, has powered extensions for all browsers over a decade. In 2019, the Google Chrome team announced a new update to this architecture, known as Manifest v3, that all extensions would be required to migrate to.

The push to Manifest v3 spurred the formation of the W3C WebExtensions Community Group in 2021, composed of browser teams from Google, Mozilla, and Apple, and extension developers, including active participation from Bitwarden. By having the browser developers and the extension developers coordinate on standards, this ensured that the rollout of Manifest v3 would uphold principles of performance, security, and user privacy.

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 timeline of Manifest v2 to June 2024.

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 persistent background page is utilized to maintain a user session as long as their browser is open. This ensures that the extension does not need to re-run any resource-intensive processes, such as retrieval and decryption of vault items to enable auto-fill, to keep the extension usable.

A service worker in contrast to persistent background pages, is designed to be active and running only when the extension background needs to process logic. Once the service worker completes its current task, it turns itself off to free up memory within the user session. It is designed to be non-persistent.

There are many benefits to using service workers. A service worker is most analogous to a web worker that a website can create. Web workers are scripts that operate in the background, distinct from the primary execution thread of a web page. They enable parallel processing, enabling tasks to be executed without impacting the user interface, improving performance and responsiveness. Utilizing a service worker to manage an extension's background logic offers many of the same advantages.

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 RxJS’s observable memory references and port messaging.

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 session storage. This storage has a capacity of 10MB but is automatically synchronized between the service worker and extension windows. Session storage is only persisted in memory, and is released when the browser closes.

Unlimited data is stored in local storage and encrypted before being stored to disk. When required by the service worker or extension windows, the data is decrypted and added to a memory cache. This division has allowed us to maintain performance and security across all accounts, even those with extensive data.

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 security principles at Bitwarden.

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 Chrome web store. Your feedback and real-life usage will ensure that Bitwarden continues to deliver a high-quality, exceptional user experience with Manifest v3 browser extension and beyond. 

As the landscape for browser extensions continues to evolve, industry professionals will continue collaborating on guidelines for browser extension development. Bitwarden remains committed to W3C WebExtensions Community Group, as well as participating in other standards bodies, including the FIDO Alliance.

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 Chrome web store.

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 form

• Submit an issue in GitHub

• Post directly on this Reddit thread