Bug 1811349 - Add documentation for cookie purging, data sanitization and query stripping. r=anti-tracking-reviewers,bvandersloot DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D167301

toolkit/components/antitracking/docs/cookie-purging/index.md

@@ -0,0 +1,217 @@
+# Cookie Purging
+
+“Cookie Purging” describes a technique that will periodically clear
+cookies and site data of known tracking domains without user interaction
+to protect against [bounce
+tracking](https://privacycg.github.io/nav-tracking-mitigations/#bounce-tracking).
+
+## Protection Background
+
+### What similar protections do other browsers have?
+
+**Safari** classifies sites as redirect trackers which directly or
+shortly after navigation redirect the user to other sites. Sites which
+receive user interaction are exempt from this. To detect bigger redirect
+networks, sites may also inherit redirect tracker
+[classification](https://privacycg.github.io/nav-tracking-mitigations/#mitigations-safari).
+If a site is classified as a redirect tracker, any site pointing to it
+will inherit this classification. Safari does not use tracker lists.
+
+When the source site is classified as a tracker, Safari will purge all
+storage, excluding cookies. Sites which receive user interaction within
+seven days of browser use are exempt. If the destination site's URL
+includes query parameters or URL fragments, Safari caps the lifetime of
+client-side set cookies of the destination site to 24 hours.
+
+**Brave** uses lists to classify redirect trackers. Recently, they have
+rolled out a new protection, [Unlinkable Bouncing](https://brave.com/privacy-updates/16-unlinkable-bouncing/),
+which limits first party storage lifetime. The underlying mechanism is
+called “first-party ephemeral storage”. If a user visits a known
+bounce-tracker which doesn’t have any pre-existing storage, the browser
+will create a temporary first-party storage bucket for the destination
+site. This temporary storage is cleared 30 seconds after the user closes
+the last tab of the site.
+
+**Chrome** and **Edge** currently do not implement any navigational
+tracking protections.
+
+### Is it standardized?
+
+At this time there are no standardized navigational tracking
+protections. The PrivacyCG has a [work item for Navigation-based Tracking Mitigations](https://privacycg.github.io/nav-tracking-mitigations/).
+Also see Apple’s proposal
+[here](https://github.com/privacycg/proposals/issues/6).
+
+### How does it fit into our vision of “Zero Privacy Leaks?”
+
+Existing tracking protections mechanisms focus mostly on third-party
+trackers. Redirect tracking can circumvent these mechanisms and utilize
+first-party storage for tracking. Cookie purging contributes to the
+“Zero Privacy Leaks” vision by mitigating this cross-site tracking
+vector.
+
+## Firefox Status
+
+Metabug: [Bug 1594226 - \[Meta\] Purging Tracking Cookies](https://bugzilla.mozilla.org/show_bug.cgi?id=1594226)
+
+### What is the ship state of this protection in Firefox?
+
+Shipped to Release in standard ETP mode
+
+### Is there outstanding work?
+
+The mechanism of storing user interaction as a permission via
+nsIPermissionManager has shown to be brittle and has led to users
+getting logged out of sites in the past. The concept of a permission
+doesn’t fully match that of a user interaction flag. Permissions may be
+separated between normal browsing and PBM (Bug
+[1692567](https://bugzilla.mozilla.org/show_bug.cgi?id=1692567)).
+They may also get purged when clearing site data (Bug
+[1675018](https://bugzilla.mozilla.org/show_bug.cgi?id=1675018)).
+
+A proposed solution to this is to create a dedicated data store for
+keeping track of user interaction. This could also enable tracking user
+interaction relative to browser usage time, rather than absolute time
+([Bug 1637146](https://bugzilla.mozilla.org/show_bug.cgi?id=1637146)).
+
+Important outstanding bugs:
+-   [Bug 1637146 - Use use-time rather than absolute time when computing whether to purge cookies](https://bugzilla.mozilla.org/show_bug.cgi?id=1637146)
+
+### Existing Documentation
+
+-   [https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect\_tracking\_protection](https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect_tracking_protection)
+
+-   [PrivacyCG: Navigational-Tracking Mitigations](https://privacycg.github.io/nav-tracking-mitigations/)
+
+
+## Technical Information
+
+### Feature Prefs
+
+Cookie purging can be enabled or disabled by flipping the
+`privacy.purge_trackers.enabled` preference. Further, it will only run if
+the `network.cookie.cookieBehavior` pref is set to `4` or `5` ([bug 1643045](https://bugzilla.mozilla.org/show_bug.cgi?id=1643045) adds
+support for behaviors `1` and `3`).
+
+Different log levels can be set via the pref
+`privacy.purge_trackers.logging.level`.
+
+The time until user interaction permissions expire can be set to a lower
+amount of time using the `privacy.userInteraction.expiration` pref. Note
+that you will have to set this pref before visiting the sites you want
+to test on, it will not apply retroactively.
+
+### How does it work?
+
+Cookie purging periodically clears first-party storage of known
+trackers, which the user has not interacted with recently. It is
+implemented in the
+[PurgeTrackerService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm),
+which implements the
+[nsIPurgeTrackerService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/nsIPurgeTrackerService.idl)
+IDL interface.
+
+#### What origins are cleared?
+
+An origin will be cleared if it fulfills the following conditions:
+
+1.  It has stored cookies or accessed other site storage (e.g.
+    [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API),
+    [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API),
+    or the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage))
+    within the last 72 hours. Since cookies are per-host, we will
+    clear both the http and https origin variants of a cookie host.
+
+2.  The origin is [classified as a tracker](https://developer.mozilla.org/en-US/docs/Web/Privacy/Storage_Access_Policy#tracking_protection_explained)
+    in our Tracking Protection list.
+
+3.  No origin with the same base domain (eTLD+1) has a user-interaction
+    permission.
+
+    -   This permission is granted to an origin for 45 days once a user
+        interacts with a top-level document from that origin.
+        "Interacting" includes scrolling.
+
+    -   Although this permission is stored on a per-origin level, we
+        will check whether any origin with the same base domain has
+        it, to avoid breaking sites with subdomains and a
+        corresponding cookie setup.
+
+#### What data is cleared?
+
+Firefox will clear the [following data](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm#205-213):
+
+-   Network cache and image cache
+
+-   Cookies
+
+-   DOM Quota Storage (localStorage, IndexedDB, ServiceWorkers, DOM
+    Cache, etc.)
+
+-   DOM Push notifications
+
+-   Reporting API Reports
+
+-   Security Settings (i.e. HSTS)
+
+-   EME Media Plugin Data
+
+-   Plugin Data (e.g. Flash)
+
+-   Media Devices
+
+-   Storage Access permissions granted to the origin
+
+-   HTTP Authentication Tokens
+
+-   HTTP Authentication Cache
+
+**Note:** Even though we're clearing all of this data, we currently only
+flag origins for clearing when they use cookies or other site storage.
+
+Storage clearing ignores origin attributes. This means that storage will
+be cleared across
+[containers](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers)
+and isolated storage (i.e. from [First-Party Isolation](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation)).
+
+#### How frequently is data cleared?
+
+Firefox clears storage based on the firing of an internal event called
+[idle-daily](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm#60,62,65),
+which is defined by the following conditions:
+
+-   It will, at the earliest, fire 24h after the last idle-daily event
+    fired.
+
+-   It will only fire if the user has been idle for at least 3min (for
+    24-48h after the last idle-daily) or 1 min (for >48h after the
+    last idle-daily).
+
+This means that there are at least 24 hours between each storage
+clearance, and storage will only be cleared when the browser is idle.
+When clearing cookies, we sort cookies by creation date and batch them
+into sets of 100 (controlled by the pref
+`privacy.purge_trackers.max_purge_count`) for performance reasons.
+
+#### Debugging
+
+For debugging purposes, it's easiest to trigger storage clearing by
+triggering the service directly via the [Browser Console command line](/devtools-user/browser_console/index.html#browser_console_command_line).
+Note that this is different from the normal [Web Console](/devtools-user/web_console/index.rst)
+you might use to debug a website, and requires the
+`devtools.chrome.enabled` pref to be set to true to use it interactively.
+Once you've enabled the Browser Console you can trigger storage clearing
+by running the following command:
+
+``` javascript
+await Components.classes["@mozilla.org/purge-tracker-service;1"]
+.getService(Components.interfaces.nsIPurgeTrackerService)
+.purgeTrackingCookieJars()
+```
+
+<!---
+TODO: consider integrating
+[https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect\_tracking\_protection](https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect_tracking_protection)
+into firefox source docs. The article doesn’t really belong into MDN,
+because it’s very specific to Firefox.
+-->

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.jsm](https://searchfox.org/mozilla-central/source/toolkit/components/forgetaboutsite/ForgetAboutSite.jsm)
+
+    -   [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)
+-->

toolkit/components/antitracking/docs/index.rst

@@ -0,0 +1,12 @@
+=================================
+Anti-Tracking
+=================================
+
+This page is an overview of various anti-tracking components.
+
+.. toctree::
+   :maxdepth: 1
+
+   Cookie Purging <cookie-purging/index.md>
+   Data Sanitization <data-sanitization/index.md>
+   Query Stripping <query-stripping/index.md>

toolkit/components/antitracking/docs/query-stripping/index.md

@@ -0,0 +1,153 @@
+# Query Parameter Stripping
+
+To combat [Navigational
+Tracking](https://privacycg.github.io/nav-tracking-mitigations/#navigational-tracking)
+through [link
+decoration](https://privacycg.github.io/nav-tracking-mitigations/#link-decoration),
+Firefox can strip known tracking query parameters from URLs before the
+user navigates to them.
+
+## Protection Background
+
+### What similar protections do other browsers have?
+
+Brave also has a list-based query parameter stripping mechanism. A list
+of query parameters stripped can be found
+[here](https://github.com/brave/brave-core/blob/5fcad3e35bac6fea795941fd8189a59d79d488bc/browser/net/brave_site_hacks_network_delegate_helper.cc#L29-L67).
+Brave also has a strip-on-copy feature which allows users to copy a
+stripped version of the current URL.
+
+### Is it standardized?
+
+At this time there are no standardized navigational tracking
+protections. The PrivacyCG has a [work item for Navigation-based
+Tracking
+Mitigations](https://privacycg.github.io/nav-tracking-mitigations/).
+Also see Apple’s proposal
+[here](https://github.com/privacycg/proposals/issues/6).
+
+### How does it fit into our vision of “Zero Privacy Leaks?”
+
+Existing tracking protections mechanisms in Firefox, such as ETP and TCP
+focus mostly on third-party trackers. Redirect tracking can circumvent
+these mechanisms by passing identifiers through link decoration and
+first-party storage. Query parameter stripping contributes to the “Zero
+Privacy Leaks” vision by mitigating this cross-site tracking vector.
+
+## Firefox Status
+
+Metabug: [Bug 1706602 - \[meta\] Implement URL query string stripping
+prototype](https://bugzilla.mozilla.org/show_bug.cgi?id=1706602)
+
+### What is the ship state of this protection in Firefox?
+
+Query stripping is enabled in release in ETP strict with an initial list
+of query params:
+
+-   mc\_eid
+
+-   oly\_anon\_id
+
+-   oly\_enc\_id
+
+-   \_\_s
+
+-   vero\_id
+
+-   \_hsenc
+
+-   mkt\_tok
+
+-   fbclid
+
+It is enabled in Nightly by default in all modes with an extended
+strip-list. You can find the current list of parameters that are
+stripped
+[here](https://firefox.settings.services.mozilla.com/v1/buckets/main/collections/query-stripping/records).
+Note that some records have a *filter\_expression* that limits where
+they apply.
+
+### Is there outstanding work?
+
+After our initial release on ETP strict, we are considering to ship the
+feature to Private Browsing Mode and possibly also to enable it by default
+in release in the future.
+
+Other possible improvements:
+
+-   Extend the list of query parameters stripped, in accordance with our policy.
+
+-   Extend the protection to cover different kinds of link decoration, beyond just query parameters.
+
+-   Ability to identify and strip hashed link decoration fields
+
+-   Strip query params for urls shared / copied out from the browser
+
+Outstanding bugs:
+
+-   See dependencies of [Bug 1706602 - \[meta\] Implement URL query
+    string stripping
+    prototype](https://bugzilla.mozilla.org/show_bug.cgi?id=1706602)
+
+### Existing Documentation
+
+-   [Anti-Tracking Policy: Navigational cross-site
+     tracking](https://wiki.mozilla.org/Security/Anti_tracking_policy#2._Navigational_cross-site_tracking)
+
+## Technical Information
+
+### Feature Prefs
+
+| Pref | Description |
+| ---- | ----------- |
+| privacy.query_stripping.enabled | Enable / disable the feature in normal browsing. |
+| privacy.query_stripping.enabled.pbmode | Enable / disable the feature in private browsing. |
+| privacy.query_stripping.allow_list | Comma separated list of sites (without scheme) which should not have their query parameters stripped. |
+| privacy.query_stripping.redirect | Whether to perform stripping for redirects. |
+| privacy.query_stripping.strip_list | List of space delimited query parameters to be stripped. |
+
+### How does it work?
+
+![Architecture](overview.png "Overview")
+
+[**UrlQueryStrippingListService**](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm)
+
+-   Collects list of query parameters to be stripped and allow-list from
+    the *privacy.query\_stripping.strip\_list/allow\_list* preference
+    and the *query-stripping* Remote Settings collection
+
+-   Lists from the two sources are
+    [concatenated](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm#150-151)
+
+-   Lists are distributed via [observer
+    notification](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm#158-161)
+    via the
+    [nsIUrlQueryStrippingListService](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/nsIURLQueryStrippingListService.idl#25).
+    [onQueryStrippingListUpdate](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/nsIURLQueryStrippingListService.idl#25)
+    is called initially on registration and whenever the preferences
+    or the Remote Settings collection updates.
+
+[**URLQueryStringStripper**](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.h)
+
+-   Only subscriber of the
+    [UrlQueryStrippingListService](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm)
+
+-   Holds [hash set
+    representations](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.h#56-57)
+    of the strip- and allow-list.
+
+-   [URLQueryStringStripper::Strip](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.cpp#45):
+    takes a nsIURI as input and strips any query parameters that are
+    on the strip-list. If the given URI matches a site on the
+    allow-list no query parameters are stripped.
+
+**Consumers**
+
+-   [nsDocShell::DoURILoad](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/docshell/base/nsDocShell.cpp#10569):
+    Strips in the content, before creating the channel.
+
+-   [BrowsingContext::LoadURI](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/docshell/base/BrowsingContext.cpp#2019):
+    Strips before loading the URI in the parent.
+
+-   [nsHttpChannel::AsyncProcessRedirection](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/netwerk/protocol/http/nsHttpChannel.cpp#5154):
+    Strips query parameters for HTTP redirects (e.g. 301).

toolkit/components/antitracking/moz.build

@@ -94,3 +94,5 @@ XPCSHELL_TESTS_MANIFESTS += ["test/xpcshell/xpcshell.ini"]
 TEST_DIRS += ["test/gtest"]
 
 REQUIRES_UNIFIED_BUILD = True
+
+SPHINX_TREES["anti-tracking"] = "docs"

toolkit/docs/index.rst

@@ -28,3 +28,4 @@ This is the nascent documentation of the Toolkit code that is shared across Fire
    components/extensions/webextensions/index
    /extensions/spellcheck/index
    mozapps/update/docs/index
+   components/antitracking/anti-tracking/index