Design-Documents/Tor-Browser-Design-Doc.md

@@ -91,7 +91,7 @@ The browser is based on [Mozilla's Extended Support Release (ESR) Firefox branch
 We maintain a [series of patches](https://gitlab.torproject.org/tpo/applications/tor-browser) atop ESR Firefox which:
 - Backport surgical privacy features, security fixes and bug fixes from Mozilla's Rapid Release (RR) Firefox branch
 - Implement non-Tor related privacy and security features
-- Integrate Tor network communications capability into the browser
+- Integrate Tor Network connectivity into the browser
 - Implement Tor-specific privacy and security features
 
 To provide network anonymity, we integrate the legacy Tor daemon (aka little-t tor or c-tor) into the browser and drive all network communications through the daemon's SOCKS5 proxy functionality.
@@ -106,6 +106,7 @@ These browser design requirements are meant to describe the properties of a Priv
 There are two main categories of requirements: [Security Requirements](#21-security-requirements), and [Privacy Requirements](#22-privacy-requirements).
 Security Requirements are the minimum properties in order for a browser to be able to support Tor and similar privacy proxies safely.
 Privacy requirements are the set of properties that cause us to prefer one browser over another.
+`TODO: this section can probably lose the generality and just talk about Tor Browser`
 
 While we will endorse the use of browsers that meet the security requirements, it is primarily the privacy requirements that cause us to maintain our own browser distribution.
 
@@ -142,7 +143,8 @@ With respect to browser support, privacy requirements are the set of properties
 
 For the purposes of the unlinkability requirements of this section as well as the descriptions in the [implementation section](#4-implementation), a URL bar origin means at least the second-level DNS name.
 For example, for `mail.google.com`, the origin would be `google.com`.
-~Implementations MAY, at their option, restrict the URL bar origin to be the entire fully qualified domain name.~ `it seems this document in the past also talks about what other browser implementations ought to do for us to like them`
+~Implementations MAY, at their option, restrict the URL bar origin to be the entire fully qualified domain name.~
+`TODO: it seems this document in the past also talks about what other browser implementations ought to do for us to like them`
 
 1. [Cross-Origin Identifier Unlinkability](#45-cross-origin-identifier-unlinkability)
 
@@ -174,7 +176,7 @@ In addition to the above design requirements, the technology decisions about the
 
     ~User model breakage was one of the [failures of Torbutton](https://blog.torproject.org/blog/toggle-or-not-toggle-end-torbutton): Even if users managed to install everything properly, the toggle model was too hard for the average user to understand, especially in the face of accumulating tabs from multiple states crossed with the current Tor-state of the browser.~
 
-    `not sure there's much value in keeping this historical aside`
+    `TODO: not sure there's much value in keeping this historical aside`
 
 2. **Favor the implementation mechanism least likely to break sites**
 
@@ -224,7 +226,7 @@ In addition to the above design requirements, the technology decisions about the
 
     ~Users are free to install these addons if they wish, but doing so is not recommended, as it will alter the browser request fingerprint.~
 
-    `this whole section can probably be removed entirely since we're seriously considering adding uBlock-origin support`
+    `TODO: this whole section can probably be removed entirely since we're seriously considering adding uBlock-origin support`
 
 6. **Stay Current**
 
@@ -300,7 +302,7 @@ Let's start with the goals.
 
 7. **Censorship**
 
-    `section about censorship goals`
+    `TODO: section about censorship goals`
 
 ### 3.2 Adversary Capabilities - Positioning
 
@@ -329,7 +331,7 @@ The adversary can position themselves at a number of different locations in orde
     Users in Internet cafes, for example, face such a threat.
     In addition, in countries where simply using tools like Tor is illegal, users may face confiscation of their computer equipment for excessive Tor usage or just general suspicion.
 
-    `also mention adversaries in the home`
+    `TODO: also mention adversaries in the home`
 
 ### 3.3 Adversary Capabilities - Attacks
 
@@ -343,8 +345,8 @@ Others are performed by ad servers seeking to correlate users' activity across d
     These identifiers are most obviously cookies, but also include HTTP auth, DOM storage, cached scripts and other elements with embedded identifiers, client certificates, and even TLS Session IDs.
 
     An adversary in a position to perform MITM content alteration can inject document content elements to both read and inject cookies for arbitrary domains.
-    In fact, even many "SSL secured" websites are vulnerable to this sort of [active sidejacking](http://seclists.org/bugtraq/2007/Aug/0070.html).
-    `ma1 should review this`
+    In fact, even many "SSL secured" websites are vulnerable to this sort of [active sidejacking](http://seclists.org/bugtraq/2007/Aug/0070.html) `ma1 should review this`.
+    `TODO: ma1 should review this`
     In addition, the ad networks of course perform tracking with cookies as well.
 
     These types of attacks are attempts at subverting our [Cross-Origin Identifier Unlinkability](#45-cross-origin-identifier-unlinkability) and [Long-Term Unlinkability](#47-long-term-unlinkability-via-new-identity-button) design requirements.
@@ -387,13 +389,13 @@ Others are performed by ad servers seeking to correlate users' activity across d
         [Flash-based cookies](https://epic.org/privacy/cookies/flash.html) fall into this category, but there are likely numerous other examples.
         Beyond fingerprinting, plugins are also abysmal at obeying the proxy settings of the browser.~
 
-        `plugins are no longer relevant but we could arguably add a section about codec support as a fingerprinting vector`
+        `TODO: plugins are no longer relevant but we could arguably add a section about codec support as a fingerprinting vector`
 
     4. **Inserting CSS**
 
         [CSS media queries](https://developer.mozilla.org/En/CSS/Media_queries) can be inserted to gather information about the desktop size, widget size, display type, DPI, user agent type, and other information that was formerly available only to JavaScript.
 
-    `thorin should also review and suggest additions to this section`
+    `TODO: thorin should also review and suggest additions to this section`
 
 3. **Website traffic fingerprinting**
 
@@ -419,7 +421,7 @@ Others are performed by ad servers seeking to correlate users' activity across d
     Still, we do not believe that these issues are enough to dismiss the attack outright.
     But we do believe these factors make it both worthwhile and effective to [deploy light-weight defenses](https://2019.www.torproject.org/projects/torbrowser/design/#traffic-fingerprinting-defenses) that reduce the accuracy of this attack by further contributing noise to hinder successful feature extraction.
 
-    `so this whole section is very long to say not a lot, revise this down to the relevant bits`
+    `TODO: so this whole section is very long to say not a lot, revise this down to the relevant bits`
 
 4. **Remotely or locally exploit browser and/or OS**
 
@@ -433,7 +435,7 @@ Others are performed by ad servers seeking to correlate users' activity across d
     It can be quite hard to really significantly limit the capabilities of such an adversary.
     [The Tails system](https://tails.boum.org/contribute/design/) can provide some defense against this adversary through the use of readonly media and frequent reboots, but even this can be circumvented on machines without Secure Boot through the use of BIOS rootkits.
 
-    `adversaries with arbitrary code execution are outside the scope of what the browser can protect against`
+    `TODO: adversaries with arbitrary code execution are outside the scope of what the browser can protect against`
 
 ## 4. Implementation
 
@@ -466,7 +468,7 @@ Proxy obedience is assured through the following:
     We have verified that these settings and patches properly proxy HTTPS, OCSP, HTTP, FTP, gopher (now defunct), DNS, SafeBrowsing Queries, all JavaScript activity, including HTML5 audio and video objects, addon updates, WiFi geolocation queries, searchbox queries, XPCOM addon HTTPS/HTTP activity, WebSockets, and live bookmark updates.
     We have also verified that external protocol helpers, such as SMB URLs and other custom protocol handlers are all blocked.
 
-    `build with --enable-proxy-bypass-protection`
+    `TODO: build with --enable-proxy-bypass-protection`
 
 2. **Disabling plugins**
 
@@ -490,13 +492,13 @@ Proxy obedience is assured through the following:
 
     ~Furthermore, we ship a [patch for Linux users](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/23044) that makes sure `sftp://` and `smb://` URLs are not passed along to the operating system as this can lead to proxy bypasses on systems that have GIO/GnomeVFS support.~
 
-    `this patch has been uplifted and is a pref now`
+    `TODO: this patch has been uplifted and is a pref now`
 
     Additionally, modern desktops now preemptively fetch any URLs in Drag and Drop events as soon as the drag is initiated.
     This download happens independent of the browser's Tor settings, and can be triggered by something as simple as holding the mouse button down for slightly too long while clicking on an image link.
     We filter [drag and drop events](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/41613) before the OS downloads the URLs the events contained.
 
-    `this bit should be updated by ma1 to talk about our updated drag+drop patches`
+    `TODO: this bit should be updated by ma1 to talk about our updated drag+drop patches`
 
 4. **Disabling system extensions and clearing the addon allow-list**
 
@@ -505,7 +507,7 @@ Proxy obedience is assured through the following:
     We also exclude system-level addons from the browser through the use of `extensions.enabledScopes` and `extensions.autoDisableScopes`.
     Furthermore, we set `  extensions.systemAddon.update.url` and `extensions.hotfix.id` to an empty string in order to avoid the risk of getting extensions installed by Mozilla into the browser, and remove unused system extensions with a [Firefox patch](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/21431).
     In order to make it harder for users to accidentally install extensions which Mozilla presents to them on the *about:addons* page, we hide the *Get Addons* option on it by setting `extensions.getAddons.showPane` to **false**.
-    `not quiet true, pdfjs is system extension we include`
+    `TODO: not quiet true, pdfjs is system extension we include`
 
 ### 4.2 State Separation
 
@@ -544,7 +546,7 @@ The Cross-Origin Identifier Unlinkability design requirement is satisfied throug
 First party isolation means that all identifier sources and browser state are scoped (isolated) using the URL bar domain.
 This scoping is performed in combination with any additional third party scope.
 When first party isolation is used with explicit identifier storage that already has a constrained third party scope (such as cookies and DOM storage), this approach is referred to as "double-keying".
-`3rd party cookies are disabled, not double-keyed`
+`TODO: 3rd party cookies are disabled, not double-keyed`
 
 ~The benefit of this approach comes not only in the form of reduced linkability, but also in terms of simplified privacy UI.
 If all stored browser state and permissions become associated with the URL bar origin, the six or seven different pieces of privacy UI governing these identifiers and permissions can become just one piece of UI.
@@ -562,7 +564,9 @@ Once browser identifiers and site permissions operate on a URL bar basis, the sa
 ~Unfortunately, many aspects of browser state can serve as identifier storage, and no other browser vendor or standards body had invested the effort to enumerate or otherwise deal with these vectors for third party tracking.
 As such, we have had to enumerate and isolate these identifier sources on a piecemeal basis.
 This has gotten better lately with Mozilla stepping up and helping us with uplifting our patches, and with contributing their own patches where we lacked proper fixes.
-However, we are not done yet with our unlinkability defense as new identifier sources are still getting added to the web platform.~ `less commentary here` Here is the list that we have discovered and dealt with to date:
+However, we are not done yet with our unlinkability defense as new identifier sources are still getting added to the web platform.~
+`TODO: less commentary here`
+Here is the list that we have discovered and dealt with to date:
 
 1. **Cookies**
 
@@ -571,7 +575,7 @@ However, we are not done yet with our unlinkability defense as new identifier so
     ~**Implementation Status**: Double-keying cookies should just work by setting `privacy.firstparty.isolate` to **true**.
     However, [we have not audited that](https://gitlab.torproject.org/legacy/trac/-/issues/21905) yet and there is still the [UI part missing for managing cookies in Private Browsing Mode](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/10353).
     We therefore opted to keep third-party cookies disabled for now by setting `network.cookie.cookieBehavior` to **1**.~
-    `So 3rd party cookies realistically are going away relatively soon, chrome is starting to phase them out entirely in 2024: https://developers.google.com/privacy-sandbox/3pcd`
+    `TODO: So 3rd party cookies realistically are going away relatively soon, chrome is starting to phase them out entirely in 2024: https://developers.google.com/privacy-sandbox/3pcd`
 
 2. **Cache**