Components

This page summarizes the main components and how to extend the system safely.

Component Diagram

A diagram of all the main components is the following:

        flowchart TD

  IPProtectionService

  Helpers["IPProtectionHelpers"]

  %% UI
  subgraph UI
    IPProtection
    IPProtectionPanel
    IPPExceptionsManager
  end

  %% Helpers
  subgraph Helpers
    IPPStartupCache["Startup Cache Helper"]
    IPPSignInWatcher["Sign-in Observer"]
    UIHelper["UI Helper"]
    AccountResetHelper["Account Reset Helper"]
    VPNAddonHelper["VPN Add-on Helper"]
    IPPNimbusHelper["Nimbus Eligibility Helper"]
    IPPAutoStart["Auto-Start Helper"]
    IPPEarlyStartupFilter["Early Startup Filter Helper"]
    IPPEnrollAndEntitleManager["Enroll & Entitle Manager"]
  end

  %% Proxy stack
  subgraph Proxy
    IPPProxyManager
    IPPChannelFilter
    IPProtectionUsage
    IPPNetworkErrorObserver
    IPProtectionServerlist
    GuardianClient
  end

  %% Service wiring
  IPProtectionService --> IPPProxyManager
  IPProtectionService --> GuardianClient
  IPProtectionService --> Helpers

  %% UI wiring
  IPProtection --> IPProtectionPanel
  IPProtection --> IPProtectionService

  %% Proxy wiring
  IPPProxyManager --> GuardianClient
  IPPProxyManager --> IPPChannelFilter
  IPPProxyManager --> IPProtectionUsage
  IPPProxyManager --> IPPNetworkErrorObserver
  IPPProxyManager --> IPProtectionServerlist
  IPPNetworkErrorObserver -- "error events (401)" --> IPPProxyManager

IP Protection architecture

GuardianClient: Manages communication between Firefox and the Guardian backend. It retrieves account information, obtains the token for the proxy, and exposes the server list.
IPPChannelFilter: Main network component. It processes network requests and decides which ones should go through the proxy.
IPPProxyManager: Implements the proxy activation/deactivation and exposes the current status.
IPProtectionPanel: Controls the feature’s panel UI.
IPPExceptionsManager: Manages the exceptions UI and logic (for example, domain exclusions and exceptions mode) in coordination with the panel and preferences.
IPProtectionService: The main service. It is initialized during browser startup, initializes helpers and other components, and implements the state machine that drives the feature.
IPProtection: Manages the UI integration and interactions with the panel.

Additional proxy/telemetry components

IPProtectionServerlist: Provides the available proxy endpoints (server list) to the proxy manager.
IPProtectionUsage: Gathers usage information and telemetry related to proxy activity.
IPPNetworkErrorObserver: Observes network errors related to the proxy and notifies the proxy manager (for example, authentication or connectivity failures).

Helper objects

The list of helpers lives in IPProtectionHelpers.sys.mjs and is exported as the IPPHelpers array. Helpers implement small, self‑contained behaviors and listen to service events when needed.

IPPAutoStart: Activates the proxy at startup time when auto‑start is enabled.
IPPSignInWatcher: Observes user authentication state. It informs the state machine when the user signs in or out.
IPPStartupCache: Exposes cached information to keep the state machine responsive during startup (last known state and entitlement JSON object).
UIHelper: Shows and hides the UI based on the current state machine state.
AccountResetHelper: Resets stored account information and stops the proxy when the account becomes unavailable.
VPNAddonHelper: Monitors the installation of the Mozilla VPN add‑on and removes the UI when appropriate.
IPPNimbusHelper: Monitors the Nimbus feature (NimbusFeatures.ipProtection) and triggers a state recomputation on updates.
IPPEnrollAndEntitleManager: Orchestrates the user enrollment flow with Guardian and updates the service when enrollment status changes.

How to implement new components

Do not modify the state machine. New functionality should be added via helper classes to keep the core simple and robust.

Recommended steps:

Create a helper class with the methods init(), initOnStartupCompleted() and uninit() as appropriate for lifecycle needs.
If your helper reacts to state changes, listen to the IPProtectionService:StateChanged event.
Add your helper to the IPPHelpers array in IPProtectionHelpers.sys.mjs. Be mindful of ordering if your helper depends on others. For example, IPPNimbusHelper is registered last to avoid premature state updates triggered by Nimbus’ immediate callback.
If your component needs to trigger a recomputation, call IPProtectionService.updateState.