Extension details

KeePassXC-Browser

This wiki page describes the basic files of the extension and explains the basic input field detection functionality. This information may be helpful for anyone who wants to debug the extension or wants to know how it actually works.

This information is only valid with KeePassXC-Browser version 1.7.0 and newer.

Background scripts

• browserAction.js handles the extension icon and popup switching.
• client.js handles all connections and messages between KeePassXC using Native Messaging.
• event.js handles all events and messages between background scripts and content scripts.
• httpauth.js handles HTTP Basic Auth filling.
• init.js initializes the background scripts on extension load and controls the tab information.
• keepass.js handles all basic functionality, commands and saved databases.
• page.js handles content script related changes and stores necessary information and credentials from tabs.

Content scripts and Objects

Main functionality is divided to these content scripts:

• keepassxc-browser.js handles all messaging and works as the base script.
• fields.js provides methods for input field handling and detection.
• fill.js handles all different filling variations from Autocomplete Menu, context menus etc.
• form.js identifies form submits and password changes.
• icons.js handles all extension icons on the web page.
• observer-helper.js handles the dynamic input field detection (MutationObserver).

Other actions are handled by:

• autocomplete.js base class for all Autocomplete Menus.
• banner.js handles the Credential Banner, shown when new/modified credentials are identified.
• credential-autocomplete.js handles Autocomplete Menu for credentials.
• define.js handles the Custom Login Fields selector.
• pwgen.js handles the Password Generator and icon(s).
• totp-autocomplete handles Autocomplete Menu for TOTP.
• totp-field.js handles OTP input fields and icon(s).
• ui.js - Generic content script functions and prototype additions/overrides.
• username-field.js handles username field input fields and icon(s).

Global scripts

Global scripts are used both for background and content scripts.

• global.js includes all global functions needed by scripts.
• sites.js handles predefined web page configurations.
• translate.js includes all translation related functions.

Page load

+-----------------------------+
| kpxc.initCredentialFields() |         Identifies all forms in the page. Save the forms and input fields.
+-+---------------------------+
  |
+-v------------------------------------+
| kpxc.identifyFormInputs() <-------+   Identifies all forms in the page and save them and the input fields.
+-+------------------------------------+ 
  |                                 | 
+-v-----------------------------+   |
| kpxcFields.getAllPageInputs() |   |   Return all input fields on the page, but ignore previously detected.
+-+--------------+--------------+   |   (If not found, try again in 2 seconds.)
  |              |------------------+
  | +------------v------------+
  | | kpxc.initCombinations() |         Handles and saves input fields as username/password combinations.
  | +-------------------------+
  |
+-v---------------------+
| kpxcIcons.initICons() |               Initializes all icons needed to be shown.
+-+---------------------+
  |
+-v--------------------------+
| kpxc.retrieveCredentials() |          Retrieves credentials from KeePassXC if database is unlocked.
+----------------+-----------+          Retrieval is made in the background script.
                 |
    +------------v--------------+
    | kpxc.prepareCredentials() |       Initializes login popup and Autocomplete Menu.
    +---------------------------+       Also shows the Credential Banner if there are new/modified credentials available. 

Dynamic input field detection

+------------------------------------------------+
| kpxcObserverHelper.observer (MutationObserver) |        MutationObserver handler.
+-+----------------------------------------------+
  |
+-v-----------------------------------+
| Ignore unnecessary nodes (elements) |     Don't handle any mutations that are not necessary.
+-+-----------------------------------+
  |
+-v-----------------------+
| Cache CSS style changes |                 Cache all CSS style changes to an internal list.
+-+--------------+--------+
  |
+-v----------------------------------+
| Handle addedNodes and removedNodes |      MutationObserver either adds or removes nodes.
+-+----------------------------------+
  |
+-v-------------------------------+
| Handle forms with class changes |         Target must be a form or contain a form.
+-+--------------+----------------+
  |              |
  | +------------v-------------------+
  | | Detect possible CSS animations |      Handle animation end in a separate function.
  | +--------------------------------+ 
  |
+-v-------------------------------+
| Handle cached CSS style changes |         Only the last display or z-index change to the element counts.
+---------------------------------+

Handling dynamic input fields

+----------------------------------------+
| kpxcObserverHelper.handleObserverAdd() |
+-+--------------------------------------+
  |
+-v-----------------------------------+
| kpxcObserverHelper.ignoredElement() |     Check for ignored nodes.
+-+-----------------------------------+
  |
+-v------------------------------+
| kpxcObserverHelper.getInputs() |          Get target node input fields.
+-+------------------------------+
  |
+-v-----------------------+
| kpxc.initCombinations() |                 Handles and saves input fields as username/password combinations.
+-------------------------+
  |
+-v---------------------+
| kpxcIcons.initICons() |                   Initializes all icons needed to be shown.
+-+---------------------+
  |
+-v--------------------------+
| kpxc.retrieveCredentials() |              Retrieves credentials from KeePassXC if database is unlocked.
+----------------+-----------+              Retrieval is made in the background script.
                 |
    +------------v--------------+
    | kpxc.prepareCredentials() |           Initializes login popup and Autocomplete Menu.
    +---------------------------+