tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

fedcm.rst (5462B)

      1 ===============================
      2 Federated Credential Management
      3 ===============================
      4 
      5 FedCM, as it is abbreviated, is a platform feature that requires a full-stack implementation.
      6 As such, its code is scattered throughout the codebase and it can be hard to follow the flow of execution.
      7 This documentation aims to make those two points easier.
      8 
      9 Code sites
     10 ==========
     11 
     12 Code relevant to it can be found in all of the following places.
     13 
     14 The webidl for this spec lives in ``dom/webidl/IdentityCredential.webidl``
     15 
     16 Core spec algorithm logic and the implementation of the ``IdentityCredential`` live in ``dom/credentialmanagement/identity/IdentityCredential.{cpp,h}``. The static functions of ``IdentityCredential`` are the spec algorithm logic. Helpers for managing the ``IdentityCredential.webidl`` objects are in the other files in ``dom/credentialmanagement/identity/``. The IPC is defined on the WindowGlobal in ``dom/ipc/PWindowGlobal.ipdl`` and ``dom/ipc/WindowGlobalParent.cpp``, and is a very thin layer.
     17 
     18 The service for managing state associated with IdentityCredentials is ``IdentityCredentialStorageService`` and the service for managing the UI prompts associated with IdentityCredentials is ``IdentityCredentialPromptService``. Both definitions and implementations are in ``toolkit/components/credentialmanagement``.
     19 
     20 The UI panel is spread around a little. The actual DOM elements are in the HTML subtree with root at ``#identity-credential-notification`` in ``browser/base/content/popup-notifications.inc.xhtml``. But the CSS describing it is spread through ``browser/themes/shared/customizableui/panelUI-shared.css``, ``browser/themes/shared/identity-credential-notification.css``, and ``browser/themes/shared/notification-icons.css``. Generally speaking, search for ``identity-credential`` in those files to find the relevant ids and classes.
     21 
     22 Content strings: ``browser/locales/en-US/browser/identityCredentialNotification.ftl``.
     23 
     24 All of this is entered from the ``navigator.credentials`` object, implemented in ``dom/credentialmanagement/CredentialsContainer.{cpp,h}``.
     25 
     26 Flow of Execution
     27 =================
     28 
     29 This is the general flow through code relevant to the core spec algorithms, which happens to be the complicated parts imo.
     30 
     31 A few notes:
     32 
     33 - All functions without a class specified are in ``IdentityCredential``.
     34 - Functions in ``IdentityCredentialPromptService`` mutate the Chrome DOM
     35 - FetchT functions send network requests via ``mozilla::dom::FetchJSONStructure<T>``.
     36 - A call to ``IdentityCredentialStorageService`` is made in ``PromptUserWithPolicy``
     37 
     38 .. graphviz::
     39 
     40  digraph fedcm {
     41    "RP (visited page) calls ``navigator.credentials.get()``" -> "CredentialsContainer::Get"
     42    "CredentialsContainer::Get" -> "DiscoverFromExternalSource"
     43    "DiscoverFromExternalSource" -> "DiscoverFromExternalSourceInMainProcess" [label="IPC via WindowGlobal's DiscoverIdentityCredentialFromExternalSource"]
     44    "DiscoverFromExternalSourceInMainProcess" -> "anonymous timeout callback" -> "CloseUserInterface" -> "IdentityCredentialPromptService::Close"
     45    "DiscoverFromExternalSourceInMainProcess" -> "CheckRootManifest A"
     46    "CheckRootManifest A" -> "FetchInternalManifest A" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
     47    "FetchInternalManifest A" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)"
     48    "DiscoverFromExternalSourceInMainProcess" -> "CheckRootManifest N"
     49    "CheckRootManifest N" -> "FetchInternalManifest N" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
     50    "FetchInternalManifest N" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)"
     51    "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)" -> "PromptUserToSelectProvider"
     52    "PromptUserToSelectProvider" -> "IdentityCredentialPromptService::ShowProviderPrompt"
     53    "IdentityCredentialPromptService::ShowProviderPrompt" -> "CreateCredential" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
     54    "CreateCredential" -> "FetchAccountList" [label="via promise chain in CreateCredential"]
     55    "FetchAccountList" -> "PromptUserToSelectAccount" [label="via promise chain in CreateCredential"]
     56    "PromptUserToSelectAccount" -> "IdentityCredentialPromptService::ShowAccountListPrompt"
     57    "IdentityCredentialPromptService::ShowAccountListPrompt" -> "PromptUserWithPolicy" [label="via promise chain in CreateCredential"]
     58    "PromptUserWithPolicy" -> "FetchMetadata"
     59    "FetchMetadata" -> "IdentityCredentialPromptService::ShowPolicyPrompt" [label="via promise chain in PromptUserWithPolicy"]
     60    "IdentityCredentialPromptService::ShowPolicyPrompt" -> "FetchToken" [label="via promise chain in CreateCredential"]
     61    "FetchToken" -> "cancel anonymous timeout callback"
     62    "FetchToken" -> "CreateCredential inline anonymous callback"
     63    "CreateCredential inline anonymous callback" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback"
     64    "DiscoverFromExternalSourceInMainProcess inline anonymous callback" -> "DiscoverFromExternalSource inline anonymous callback" [label="Resolving IPC via WindowGlobal's DiscoverIdentityCredentialFromExternalSource"]
     65    "DiscoverFromExternalSource inline anonymous callback" -> "CredentialsContainer::Get inline anonymous callback"
     66    "CredentialsContainer::Get inline anonymous callback" -> "RP (visited page) gets the credential"
     67  }