9 files changed, 443 insertions, 0 deletions
diff --git a/toolkit/components/antitracking/docs/data-sanitization/index.md b/toolkit/components/antitracking/docs/data-sanitization/index.md
new file mode 100644
index 0000000000..412896c200
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/index.md
@@ -0,0 +1,443 @@
+# Data Sanitization
+
+<!-- TODO: This doesn't strictly talk only about toolkit code. Consider splitting the article up and moving to relevant components -->
+
+Firefox has several Data Sanitization features. They allow users to
+clear preferences and website data. Clearing data is an essential
+feature for user privacy. There are two major privacy issues data
+clearing helps mitigate:
+
+1.  Websites tracking the user via web-exposed APIs and storages. This
+    can be traditional storages, e.g. localStorage, or cookies.
+    However, sites can also use Supercookies, e.g. caches, to persist
+    storage in the browser.
+
+2.  Attackers who have control over a computer can exfiltrate data from
+    Firefox, such as history, passwords, etc.
+
+## Protection Background
+
+### What similar protections do other browsers have?
+
+All major browsers implement data clearing features
+([Chrome](https://support.google.com/chrome/answer/2392709?hl=en&co=GENIE.Platform%3DDesktop&oco=0#zippy=),
+[Edge](https://support.microsoft.com/en-us/microsoft-edge/view-and-delete-browser-history-in-microsoft-edge-00cf7943-a9e1-975a-a33d-ac10ce454ca4),
+[Safari](https://support.apple.com/guide/safari/clear-your-browsing-history-sfri47acf5d6/mac),
+[Brave](https://support.brave.com/hc/en-us/articles/360054509991-How-do-I-clear-Cookies-and-Site-data-in-Brave-on-Android-)).
+They usually include a way for users to clear site data within a
+configurable time-span along with a list of data categories to be
+cleared.
+
+Chrome, Edge and Brave all share Chromium’s data clearing dialog with
+smaller adjustments. Notably, Brave extends it with a clear-on-shutdown
+mechanism similar to Firefox, while Chrome only supports clearing
+specifically site data on shutdown.
+
+Safari’s history clearing feature only allows users to specify a time
+span. It does not allow filtering by categories, but clears all website
+related data.
+
+All browsers allow fine grained control over website cookies and
+storages via the developer tools.
+
+### Is it standardized?
+
+This is a browser UX feature and is therefore not standardized. It is
+not part of the web platform.
+
+There is a standardized HTTP header sites can send to clear associated
+browser cache, cookies and storage:
+[Clear-Site-Data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data).
+However, Firefox no longer allows sites to clear caches via the header
+since [Bug
+1671182](https://bugzilla.mozilla.org/show_bug.cgi?id=1671182).
+
+### How does it fit into our vision of “Zero Privacy Leaks?”
+
+Clearing site data protects users against various tracking techniques
+that rely on browser state to (re-)identify users. While Total Cookie
+Protection covers many cross-site tracking scenarios, clearing site data
+can additionally protect against first-party tracking and other tracking
+methods that bypass TCP such as [navigational
+tracking](https://privacycg.github.io/nav-tracking-mitigations/#intro).
+
+## Firefox Status
+
+### What is the ship state of this protection in Firefox?
+
+This long standing set of features is shipped in Release in default ETP
+mode. In Firefox 91 we introduced [Enhanced Cookie
+Clearing](https://blog.mozilla.org/security/2021/08/10/firefox-91-introduces-enhanced-cookie-clearing/)
+which makes use of TCP’s cookie jars. This feature only benefits users
+who have TCP enabled - in ETP strict mode or Private Browsing Mode.
+
+### Is there outstanding work?
+
+Since [Bug
+1422365](https://bugzilla.mozilla.org/show_bug.cgi?id=1422365) the
+ClearDataService provides a common interface to clear data of various
+storage implementations. However, we don’t have full coverage of all
+browser state yet. There are several smaller blind spots, most of which
+are listed in this [meta
+bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1102808). There is
+also a long backlog of data sanitization bugs
+[here](https://bugzilla.mozilla.org/show_bug.cgi?id=1550317).
+
+From a user perspective it’s difficult to understand what kind of data
+is cleared from which UI. The category selection in the “Clear recent
+history” dialog is especially confusing.
+
+Data clearing can take a long time on bigger Firefox profiles. Since
+these operations mostly run on the main thread, this can lock up the UI
+making the browser unresponsive until the operation has completed.
+
+Generally it would be worth revisiting cleaner implementations in the
+ClearDataService and beyond to see where we can improve clearing
+performance.
+
+Slow data clearing is especially problematic on shutdown. If the
+sanitize-on-shutdown feature takes too long to clear storage, the parent
+process will be terminated, resulting in a shutdown crash. [Bug
+1756724](https://bugzilla.mozilla.org/show_bug.cgi?id=1756724)
+proposes a solution to this: We could show a progress dialog when
+clearing data. This way we can allow a longer shutdown phase, since the
+user is aware that we’re clearing data.
+
+Important outstanding bugs:
+
+-   [Bug 1550317 - \[meta\] Broken data
+    sanitization](https://bugzilla.mozilla.org/show_bug.cgi?id=1550317)
+
+-   [Bug 1102808 - \[meta\] Clear Recent History / Forget button
+    blind
+    spots](https://bugzilla.mozilla.org/show_bug.cgi?id=1102808)
+
+-   [Bug 1756724 - Show a data clearing progress dialog when
+    sanitizing data at shutdown due to "delete cookies and site data
+    when Firefox is
+    closed"](https://bugzilla.mozilla.org/show_bug.cgi?id=1756724)
+
+### Existing Documentation
+<!-- TODO: link existing documentation, if any -->
+
+\-
+
+## Technical Information
+
+### Feature Prefs
+
+| Pref | Description |
+| ---- | ----------- |
+| places.forgetThisSite.clearByBaseDomain | Switches “Forget about this site” to clear for the whole base domain rather than just the host. |
+| privacy.sanitize.sanitizeOnShutdown | Whether to clear data on Firefox shutdown. |
+| privacy.clearOnShutdown.* | Categories of data to be cleared on shutdown. True = clear category. Data is only cleared if privacy.sanitize.sanitizeOnShutdown is enabled.|
+
+### How does it work?
+
+The following section lists user facing data sanitization features in
+Firefox, along with a brief description and a diagram how they tie into
+the main clearing logic in `nsIClearDataService`.
+
+#### Clear Data
+
+-   Accessible via `about:preferences#privacy`
+
+-   Clears site data and caches depending on user selection
+
+-   Clears
+
+    -   Cookies
+
+    -   DOM storages
+
+    -   HSTS
+
+    -   EME
+
+    -   Caches: CSS, Preflight, HSTS
+
+-   Source
+
+    -   [clearSiteData.xhtml](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.xhtml)
+
+    -   [clearSiteData.js](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.js)
+
+    -   [clearSiteData.css](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.css)
+
+![image3](media/image3.png)
+
+![image1](media/image1.png)
+
+#### Clear Recent History
+
+-   Accessible via hamburger menu =&gt; History =&gt; Clear Recent
+    history or `about:preferences#privacy` =&gt; History =&gt; Clear
+    History
+
+-   Clears a configurable list of categories as [defined in
+    Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#356)
+
+-   Can clear everything or a specific time range
+
+-   Source
+
+    -   [sanitize.xhtml](https://searchfox.org/mozilla-central/source/browser/base/content/sanitize.xhtml)
+
+    -   [sanitizeDialog.js](https://searchfox.org/mozilla-central/source/browser/base/content/sanitizeDialog.js)
+
+![image4](media/image4.png)
+
+#### Forget About this Site
+
+-   Accessible via hamburger menu =&gt; History =&gt; Contextmenu of an
+    item =&gt; Forget About This Site
+
+-   Clears all data associated with the base domain of the selected site
+
+-   \[With TCP\] Also clears data of any third-party sites embedded
+    under the top level base domain
+
+-   The goal is to remove all traces of the associated site from Firefox
+
+-   Clears
+    \[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307)\]
+
+    -   History, session history, download history
+
+    -   All caches
+
+    -   Site data (cookies, dom storages)
+
+    -   Encrypted Media Extensions (EME)
+
+    -   Passwords (See [Bug
+        702925](https://bugzilla.mozilla.org/show_bug.cgi?id=702925))
+
+    -   Permissions
+
+    -   Content preferences (e.g. page zoom level)
+
+    -   Predictor network data
+
+    -   Reports (Reporting API)
+
+    -   Client-Auth-Remember flag, Certificate exceptions
+
+    -   Does **not** clear bookmarks
+
+-   Source
+
+    -   [ForgetAboutSite.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/components/forgetaboutsite/ForgetAboutSite.sys.mjs)
+
+    -   [nsIClearDataService flags
+        used](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307)
+
+![image6](media/image6.png)
+
+![image2](media/image2.png)
+
+#### Sanitize on Shutdown
+
+-   Can be enabled via `about:preferences#privacy` =&gt; History: Firefox
+    will: Use custom settings for history =&gt; Check “Clear history
+    when Firefox closes”
+
+    -   After [Bug
+        1681493](https://bugzilla.mozilla.org/show_bug.cgi?id=1681493)
+        it can also be controlled via the checkbox “Delete cookies and
+        site data when Firefox is closed”
+
+-   On shutdown of Firefox, will clear all data for the selected
+    categories. The list of categories is defined in
+    [Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#356)
+
+-   Categories are the same as for the “Clear recent history” dialog
+
+-   Exceptions
+
+    -   Sites which have a “cookie” permission, set to
+        [ACCESS\_SESSION](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#28)
+        always get cleared, even if sanitize-on-shutdown is disabled
+
+    -   Sites which have a “cookie” permission set to
+        [ACCESS\_ALLOW](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#19)
+        are exempt from data clearing
+
+    -   Caveat: When “site settings” is selected in the categories to be
+        cleared, the Sanitizer will remove exception permissions too.
+        This results in the above exceptions being cleared.
+
+-   Uses PrincipalsCollector to obtain a list of principals which have
+    site data associated with them
+
+    -   [getAllPrincipals](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/PrincipalsCollector.jsm#72)
+        queries the QuotaManager, the cookie service and the service
+        worker manager for principals
+
+-   The list of principals obtained is checked for permission
+    exceptions. Principals which set a cookie
+    [ACCESS\_ALLOW](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#19)
+    permission are removed from the list.
+
+-   Sanitizer.jsm [calls the
+    ClearDataService](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#1022,1027-1032)
+    to clear data for every principal from the filtered list
+
+-   Source
+
+    -   Most of the sanitize-on-shutdown logic is implemented in
+        [Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm)
+
+    -   The main entry point is
+        [sanitizeOnShutdown](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#790)
+
+    -   [Parts of
+        sanitize-on-shutdown](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#904-911)
+        always have to run, even if the rest of the feature is
+        disabled, to support clearing storage of sites which have
+        “cookie” set to
+        [ACCESS\_SESSION](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#28)
+        (see exceptions above)
+
+#### Manage Cookies and Site Data
+
+-   Accessible via `about:preferences#privacy` =&gt; Cookies and Site Data
+    =&gt; Manage Data
+
+-   Clears
+    \[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#499,510-514)\]
+
+    -   Cookies
+
+    -   DOM storages
+
+    -   EME
+
+    -   Caches: CSS, Preflight, HSTS
+
+-   Lists site cookies and storage grouped by base domain.
+
+-   Clearing data on a more granular (host or origin) level is not
+    possible. This is a deliberate decision to make this UI more
+    thorough in cleaning and easier to understand. If users need very
+    granular data management capabilities, they can install an addon
+    or use the devtools.
+
+-   Allows users to clear storage for specific sites, or all sites
+
+-   \[With TCP\] Also clears data of any third-party sites embedded
+    under the top level base domain
+
+-   Collects list of sites via
+    [SiteDataManager.getSites](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#366)
+
+-   Before removal, prompts via SiteDataManger.promptSiteDataRemoval
+
+-   On removal calls SiteDataManager.removeAll() if all sites have been
+    selected or SiteDataManager.remove() passing a list of sites to be
+    removed.
+
+-   Source
+
+    -   [siteDataSettings.xhtml](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/components/preferences/dialogs/siteDataSettings.xhtml)
+
+    -   [siteDataSettings.js](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/components/preferences/dialogs/siteDataSettings.js)
+
+#### Clear Cookies and Site Data
+
+-   Accessible via the identity panel (click on lock icon in the URL
+    bar)
+
+-   Clears
+    \[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#499,510-514)\]
+
+    -   Cookies
+
+    -   DOM storages
+
+    -   EME
+
+    -   Caches: CSS, Preflight, HSTS
+
+-   Button handler method:
+    [clearSiteData](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/base/content/browser-siteIdentity.js#364-385)
+
+-   Calls SiteDataManager.remove() with the base domain of the currently
+    selected tab
+
+-   The button is only shown if a site has any cookies or quota storage.
+    This is checked
+    [here](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/base/content/browser-siteIdentity.js#923).
+
+-   Source
+
+    -   [identityPanel.inc.xhtml](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/components/controlcenter/content/identityPanel.inc.xhtml#97)
+
+    -   [browser-siteIdentity.js](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/base/content/browser-siteIdentity.js#364)
+
+![image7](media/image7.png)
+
+![image5](media/image5.png)
+
+A broad overview of the different data clearing features accessible via
+about:preferences#privacy.
+
+The user can clear data on demand or choose to clear data on shutdown.
+For the latter the user may make exceptions for specific origins not to
+be cleared or to be always cleared on shutdown.
+
+#### ClearDataService
+
+This service serves as a unified module to hold all data clearing logic
+in Firefox / Gecko. Callers can use the
+[nsIClearDataService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/nsIClearDataService.idl)
+interface to clear data. From JS the service is accessible via
+Services.clearData.
+
+To specify which state to clear pass a combination of
+[flags](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/nsIClearDataService.idl#161-308)
+into aFlags.
+
+Every category of browser state should have its own cleaner
+implementation which exposes the following methods to the
+ClearDataService:
+
+-   **deleteAll**: Deletes all data owned by the cleaner
+
+-   **deleteByPrincipal**: Deletes data associated with a specific
+    principal.
+
+-   **deleteByBaseDomain**: Deletes all entries which are associated
+    with the given base domain. This includes data partitioned by
+    Total Cookie Protection.
+
+-   **deleteByHost**: Clears data associated with a host. Does not clear
+    partitioned data.
+
+-   **deleteByRange**: Clear data which matches a given time-range.
+
+-   **deleteByLocalFiles**: Delete data held for local files and other
+    hostless origins.
+
+-   **deleteByOriginAttributes**: Clear entries which match an
+    [OriginAttributesPattern](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/caps/OriginAttributes.h#153).
+
+Some of these methods are optional. See [comment
+here](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/ClearDataService.jsm#85-105).
+If a cleaner does not support a specific method, we will usually try to
+fall back to deleteAll. For privacy reasons we try to over-clear storage
+rather than under-clear it or not clear it at all because we can’t
+target individual entries.
+
+![image8](media/image8.png)
+
+Overview of the most important cleaning methods of the ClearDataService
+called by other Firefox / Gecko components. deleteDataFromPrincipal is
+called programmatically, while user exposed data clearing features clear
+by base domain, host or all data.
+
+<!--
+TODO: For firefox-source-docs, import JSdoc for relevant modules
+[like
+so](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/prompts/docs/nsIPromptService-reference.rst#9)
+-->
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image1.png b/toolkit/components/antitracking/docs/data-sanitization/media/image1.png
new file mode 100644
index 0000000000..c9029753a3
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image1.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image2.png b/toolkit/components/antitracking/docs/data-sanitization/media/image2.png
new file mode 100644
index 0000000000..451b297b7e
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image2.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image3.png b/toolkit/components/antitracking/docs/data-sanitization/media/image3.png
new file mode 100644
index 0000000000..8b37d5f160
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image3.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image4.png b/toolkit/components/antitracking/docs/data-sanitization/media/image4.png
new file mode 100644
index 0000000000..566b0d3b36
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image4.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image5.png b/toolkit/components/antitracking/docs/data-sanitization/media/image5.png
new file mode 100644
index 0000000000..21f34894fa
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image5.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image6.png b/toolkit/components/antitracking/docs/data-sanitization/media/image6.png
new file mode 100644
index 0000000000..719227d2ca
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image6.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image7.png b/toolkit/components/antitracking/docs/data-sanitization/media/image7.png
new file mode 100644
index 0000000000..9259380188
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image7.png
diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image8.png b/toolkit/components/antitracking/docs/data-sanitization/media/image8.png
new file mode 100644
index 0000000000..469aa398cd
--- /dev/null
+++ b/toolkit/components/antitracking/docs/data-sanitization/media/image8.png