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.
• 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 connections and messages between KeePassXC using Native Messaging.
• page.js handles content script related changes and stores necessary information and credentials from tabs.

Content scripts and Objects

keepassxc-browser.js

• kpxcIcons handles all extension icons on the web page.
• kpxcForm identifies form submits and password changes.
• kpxcFields provides methods for input field handling and detection.
• kpxc is the main content script Object where almost everything happens.
• kpxcObserverHelper handles the dynamic input field detection (MutationObserver).

keepassxc-browser.js also handles other content scripts:

• autocomplete.js handles the Autocomplete Menu.
• banner.js handles the Credential Banner, shown when new/modified credentials are identified.
• define.js handles the Custom Login Fields selector.
• pwgen.js handles the Password Generator and icon(s).
• sites.js handles predefined web page configurations.
• 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).

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-----------------------+         |
| kpxc.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

+----------------------------------+
| kpxc.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.
    +---------------------------+