Signify Browser Extension

This browser extension was initially developed as part of Provenant's Bounty PB311.1

This browser extension, initially implemented for Chromium browsers, uses signify-ts to connect to a KERIA agent and retrieve user AIDs and their associated keys and credentials. Those AIDs and credentials are used to sign in to enabled websites. Once a signin is associated with a website, it's stored in chrome store for future use.

The primary goal of this extension is to provide a secure way to sign in to websites without disclosing private keys to untrusted websites. Websites developers should adopt polaris-web library to send messages to the extension requesting signed headers that are needed to authenticate in a backend service. Additionally to the signed headers, the website may request to provide a credential (ACDC).

This browser extension adopts Manifest V3 to take advantage of the new security features and performance improvements.

Architecture

The browser extension is composed of the following components:

Background

The background script, known as service worker in Manifest v3, is responsible for handling messages received from the content script, popup, and external webpages that were already allowed to request signed headers from the extension. The background script is also responsible for handling the communication with the KERIA agent.

Popup

It's the user interface of the browser extension. It can be accessed by clicking on the extension action icon in the browser toolbar.

Content Script

The content script is injected in the active web page and is responsible for handling messages from the website, the background script and the popup.

Dialog

The dialog is a html that is injected by the content script in the active web page. It's used to display messages to the user and request user interaction.

Security considerations

The following rules are enforced by design to ensure the security of the extension:

• The extension only sends signed headers to the website if the user has previously created a signing association with that website.
• The extension only sends signed headers to the website if the website is the active tab on the browser.
• The passcode is temporarily stored in the extension and is zeroed out after a few minutes.
• Messages from content script are allowed if the content script belongs to the active tab.
• Direct messages from the website to the background script are only allowed for the active tab and if a signing association exists with the auto-signin flag enabled.
• Request minimum permission in the Manifest.
• All sensitive data is only accessed by the background script and popup, and never reaches the content script.
• Never run external scripts in the extension (eval()).

Development Environment Getting Started:

1. Install extension into target browser (whose build steps are described below). In Chrome you can do that by following these instructions
2. Start up a KERIA agent (the path of least resistance is probably through the docker image from the repo)
3. Click on Extension. First time you should see this: .
4. Fill in bootURL and agentURL with the boot and agent ports of the KERIA agent you started in step 2 and click "save"
5. From there it should tell you to enter your passcode: since you don't have a passcode yet you'll click on the dialogue that says Don't have a KERIA agent?
6. That will bring you to a screen with a button called "Generate Passcode". Click that and save the value, this is the passcode for this particular extension. In a production setting this would be the master secret that the user must keep secure. Enter it into the box that appears.
7. If successful, you'll be taken to the main landing page

How to build for various target browsers:

npm install

In order to run the extension locally, we first need to build. We are using vite frontend build tool. vite.config.js file is configured to generate build for chrome/chromium or firefox.

generate build for chrome:

The following command generates a build for chrome in dist/chrome folder.

npm run build

See this guide to run extension locally in chrome

generate build for firefox:

The following command generates a build for firefox in dist/firefox folder.

npm run build:firefox

See this guide to run extension locally in firefox

Troubleshooting

• There are three places things are logged. Look here first when developing.
  • KERIA's log console. If using the docker images these should be set up to scroll as events occur
  • Error log on the extension manager itself. This will print stack traces when the extension logs unresolvable errors
  • Console of the web worker run by the extension.