A content script is a script that the browser inserts into the page source for each page that the browser loads. Content scripts can read and modify the contents of the page in which they are loaded, but they do not have access to the full set of browser APIs.
The Bitwarden extension uses content scripts in order to perform the Autofill functionality, as Autofill must both parse the page source to find the relevant fields and also alter the page source to fill in the fields with the relevant Cipher data.
The extension uses the following scripts for Autofill:
|Collects form elements from the page and performs the autofill action on relevant fields.|
|Triggers autofill for users who have the "Enable Autofill on Page Load" setting enabled.|
|Detects when the user submits new or updated credentials on a website and triggers the Notification Bar UI.|
There are other content scripts that Bitwarden uses, but these are the scripts related to the Autofill functionality.
Background Pages and Listeners
The Bitwarden browser extension uses
background pages in order to
listen and respond to actions triggered by the content scripts running on the browser tab. They do
this by using
BrowserApi.messageListener() to attach to
The background scripts and listeners used in the Bitwarden extension are:
| Background Page / Listener | Responsibility | ------------------------------------------------------------------------ |
runtime.background.ts | Handles incoming requests related to core extension functionality. |
notification.background.ts | Handles incoming requests related to the notification bar. |
commands.background.ts | Handles incoming requests related to keyboard commands (including autofill) for Mv2 extensions. |
onCommandListener.ts | Handles incoming requests related to keyboard commands (including autofill) for Mv3 extensions. |
contextMenu.background.ts | Handles context menu actions (including autofill). |
main.background.js | Bootstraps the extension. It is relevant here only because it (arbitrarily) contains the
collectPageDetailsForContentScript() method. |
We have established that the Bitwarden extension uses content scripts and background pages or listeners in order to perform Autofill. The last piece of the puzzle is the communication between them. The Autofill architecture leverages the extension messaging API in order to communicate between the extension UI, the background pages, and the content scripts that are running on each browser tab.
Sending a request from the content script to the extension
To send a request from a content script to the extension, we have two services provided:
- When Dependency Injection is available, the
BrowserMessagingServiceshould be used, with its provided
- When no Dependency Injection is available, the static
BrowserApishould be used, with its
On the extension background pages, we attach with
BrowserApi.messageListener to receive the
messages destined for the extension.
BrowserApi abstract the
chrome.runtime.onMessage.addListener exposed by the browser. If any direct references to this API
are found, they should be refactored to use one of our abstractions.
Sending a request from the extension to the content script
BrowserApi.tabSendMessage to send messages from the extension to the content script running
on the browser tab.
In the content script on the tab, we attach with
chrome.runtime.onMessage.addListener to receive
the messages destined for that tab.
BrowserApi abstracts the
chrome.tabs.sendMessage API. If any direct references to this API
are found, they should be refactored to use our abstraction.