sousa-gecko/toolkit/components/ipprotection/docs/Components.md

# Components

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

The implementation is split across three layers:

- `toolkit/components/ipprotection` — platform-independent core (state machine,
  proxy/network stack, core helpers).
- `browser/components/ipprotection` — desktop-specific UI layer (panel, toolbar
  button, alert/infobar managers, and onboarding helpers).
- `mobile/shared/modules/geckoview/` — Android GeckoView entry point.

## Component Diagram

A diagram of all the main components is the following:

```{mermaid}
:align: center
:caption: IP Protection architecture

---
config:
  flowchart:
    defaultRenderer: "elk"
---
flowchart LR

  %% browser/components/ipprotection
  subgraph Browser["browser/components/ipprotection (UI layer)"]
    IPProtection
    IPProtectionPanel

    subgraph BrowserHelpers["Browser Helpers"]
      UIHelper["UI Helper"]
      IPPOnboardingMessage["Onboarding Message"]
      IPPOptOutHelper["Opt-Out Helper"]
      IPPUsageHelper["Usage Helper"]
      IPProtectionAlertManager["Alert Manager"]
      IPProtectionInfobarManager["Infobar Manager"]
    end
  end

  %% toolkit/components/ipprotection
  subgraph Toolkit["toolkit/components/ipprotection (core)"]
    IPProtectionService
    IPProtectionActivator

    subgraph CoreHelpers["Core Helpers"]
      IPPStartupCache["Startup Cache Helper"]
      IPProtectionServerlist
      IPPProxyManager
      IPPAutoStart["Auto-Start Helper"]
      IPPAutoRestoreHelper["Auto-Restore Helper"]
      IPPNimbusHelper["Nimbus Eligibility Helper"]
      IPPSessionPrefManager["Session Pref Manager"]
      IPPExceptionsManager
    end

    subgraph FxaAuth["FxA Authentication (fxa/)"]
      IPPAuthProvider
      IPPFxaActivateAuthProvider["Activate Auth Provider"]
      IPPSignInWatcher["Sign-in Observer"]
      GuardianClient
    end

    subgraph Proxy["Proxy stack"]
      IPPChannelFilter
      IPPNetworkErrorObserver
    end
  end

  %% Android layer
  subgraph Android["Android Glue"]
    GeckoViewIPProtection

    subgraph AndroidAuth["Android Authentication"]
      IPPAndroidAuthProvider["Android FxA Auth Provider"]
      IPPGpiAuthProvider["GPI Auth Provider"]
      IPPAndroidSignInWatcher["Android Sign-in Observer"]
    end
  end

  %% Activator wiring
  BrowserHelpers -- "addHelpers()" --> IPProtectionActivator
  IPProtectionActivator --> IPProtectionService
  IPProtectionActivator --> CoreHelpers
  IPProtectionActivator -- "setAuthProvider()" --> IPPFxaActivateAuthProvider
  GeckoViewIPProtection -- "setAuthProvider()" --> IPProtectionActivator

  %% Service wiring
  IPProtectionService --> CoreHelpers
  IPProtectionService -- "authProvider" --> IPPAuthProvider

  %% FxA auth wiring
  IPPFxaActivateAuthProvider -->|extends| IPPAuthProvider
  IPPFxaActivateAuthProvider --> IPPSignInWatcher
  IPPFxaActivateAuthProvider --> GuardianClient

  %% Android auth wiring
  IPPAndroidAuthProvider -->|extends| IPPFxaActivateAuthProvider
  IPPAndroidAuthProvider --> IPPAndroidSignInWatcher
  IPPGpiAuthProvider -->|extends| IPPAuthProvider

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

  %% Proxy wiring
  IPPProxyManager --> IPPChannelFilter
  IPPProxyManager --> IPPNetworkErrorObserver
  IPPNetworkErrorObserver -- "error events (401)" --> IPPProxyManager
```

## Toolkit components (`toolkit/components/ipprotection`)

GuardianClient

: HTTP client for the Guardian backend. Manages communication with Guardian to
  retrieve account information, obtain proxy tokens, and run the FxA enrollment
  flow.

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.

IPProtectionService

: The main service. It is initialized during browser startup, initializes helpers
  and other components, and implements the state machine that drives the feature.

IPProtectionActivator

: Entry point that assembles the full helper list and initialises
  `IPProtectionService`. It owns the ordered list of core helpers and exposes
  `addHelpers()` so that the browser layer can register additional,
  browser-specific helpers before `init()` is called. It also exposes
  `setAuthProvider()` to set the active authentication provider.

IPPExceptionsManager

: Manages the exceptions logic (for example, domain exclusions) in coordination
  with the panel and preferences.

### Additional proxy/telemetry components

IPProtectionServerlist

: Provides the available proxy endpoints (server list) to the proxy manager.

IPPNetworkErrorObserver

: Observes network errors related to the proxy and notifies the proxy manager
  (for example, authentication or connectivity failures).

### Core helpers

The core helper list is defined in `IPProtectionActivator.sys.mjs` (toolkit).

IPPAutoStart

: Activates the proxy at startup time when auto-start is enabled.

IPPAutoRestoreHelper

: Restores the proxy state after a crash or restart when auto-restore is enabled.

IPPStartupCache

: Exposes cached information to keep the state machine responsive during startup
  (last known state and entitlement JSON object).

IPPNimbusHelper

: Monitors the Nimbus feature (`NimbusFeatures.ipProtection`) and triggers a
  state recomputation on updates.

### FxA authentication (`toolkit/components/ipprotection/fxa`)

Authentication is abstracted behind `IPPAuthProvider`, which lives in the
toolkit root. `IPProtectionService` always interacts with the provider through
this interface, so all FxA dependencies are fully contained in the `fxa/`
sub-directory. On desktop, the concrete provider and its helpers are registered
from `IPProtectionHelpers.sys.mjs` in the browser layer. On Android, the
selection is done by `GeckoViewIPProtection` at initialisation time (see below).

IPPAuthProvider

: Base class that defines the authentication interface used by
  `IPProtectionService`. The default implementation is a no-op that keeps
  the service in an unauthenticated/inactive state.

IPPFxaActivateAuthProvider

: Concrete FxA implementation of `IPPAuthProvider`. It obtains short-lived
  OAuth tokens from `fxAccounts` via `getToken()`, passes them to
  `GuardianClient` for all Guardian HTTP calls, and enrolls the user by sending
  the FxA Bearer token directly to Guardian's activate endpoint, without using a
  hidden tab or window.

IPPSignInWatcher

: Observes user authentication state. It informs the state machine when the
  user signs in or out.

IPPSessionPrefManager

: Sets session-scoped preferences while the
  proxy is active and resets them when it deactivates, preserving any
  user-set values.

### Android authentication

On Android, two concrete `IPPAuthProvider` implementations are available and
selected at initialisation time by `GeckoViewIPProtection` based on the FxA
sign-in state stored in `toolkit.ipProtection.android.authProvider`.

IPPAndroidAuthProvider

: Android variant of the FxA provider. Extends `IPPFxaActivateAuthProvider`
  and uses `IPPAndroidSignInWatcher` to track the FxA sign-in state.

IPPGpiAuthProvider

: Google Play Integrity implementation of `IPPAuthProvider`. Used when the
  user is not signed into FxA. Obtains a short-lived GPI token from the Android
  layer via `EventDispatcher` and exchanges it for an Auth JWT with Guardian.
  The JWT is cached in `browser.ipProtection.gpi.authJwt` so that subsequent
  proxy starts require no network requests.

IPPAndroidSignInWatcher

: Monitors the FxA sign-in state on Android by listening to
  `IPP:AuthStateChanged` events from the Android layer. Exposes `isSignedIn`
  and dispatches `IPPSignInWatcher:StateChanged` when the state changes.

## Android GeckoView entry point

GeckoViewIPProtection

: GeckoView module that owns the IP Protection lifecycle on Android. On
  `GeckoView:IPProtection:Init` it reads the `toolkit.ipProtection.android.authProvider`
  preference to determine which auth provider to activate: `IPPAndroidAuthProvider`
  (with its FxA helpers) when the user is signed in, or `IPPGpiAuthProvider`
  otherwise. When the FxA sign-in state changes the Android layer clears the
  preference and calls `Uninit` followed by `Init` so that the correct
  provider is selected again.

## Browser components (`browser/components/ipprotection`)

IPProtection

: Manages the UI integration and interactions with the panel.

IPProtectionPanel

: Controls the feature's panel UI.

IPProtectionHelpers

: Registers browser-specific helpers with `IPProtectionActivator` via
  `addHelpers()`: `UIHelper`, `IPPOnboardingMessage`, `IPPOptOutHelper`,
  `IPPUsageHelper`, `IPProtectionAlertManager`, and `IPProtectionInfobarManager`.
  It also registers `IPPFxaActivateAuthProvider` (and its FxA helpers) via
  `setAuthProvider()` and `addHelpers()`.

UIHelper

: Shows and hides the UI based on the current state machine state.

IPPOptOutHelper

: Handles the user opt-out flow and clears stored state accordingly.

IPPOnboardingMessage

: Handles the onboarding message flow for new users.

IPPUsageHelper

: Tracks bandwidth usage warning state and fires state-change events when
  usage crosses the 75% or 90% thresholds.

IPProtectionAlertManager

: Manages alert notifications related to IP Protection.

IPProtectionInfobarManager

: Manages infobar notifications displayed to the user.

## 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:

1. Decide whether the helper belongs in the **toolkit** layer (no UI, no chrome
   dependency) or the **browser** layer (UI or chrome integration required).

2. Create a helper class with the methods `init()`, `initOnStartupCompleted()`
   and `uninit()` as appropriate for lifecycle needs.

3. If your helper reacts to state changes, listen to the
   `IPProtectionService:StateChanged` event.

4. Register your helper:

   - **Toolkit helpers**: add it to the `coreHelpers` array in
     `toolkit/components/ipprotection/IPProtectionActivator.sys.mjs`.
   - **Browser helpers**: call `IPProtectionActivator.addHelpers([...])` in
     `browser/components/ipprotection/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.

5. If your component needs to recompute the service state, call
   `IPProtectionService.updateState()` after updating the helper data it
   relies on; the recomputation is synchronous.