Support automatic bridge retrieval

Status for fundraising

Iterations 1 and 2 are candidates for 2026, after we have completed:

• Support for Signal (#14567)
• Support Snowflake bridges (#5494)
• Add WebTunnel support (#20267)

Additionally, we'll have to do Support meek bridges (#8243) as part of this project.

How

Originally this issue was about using Moat + CAPTCHA. It's now about using the "Circumvention Settings" endpoints of the Moat distributor in order to achieve the same result, but without the need to solve a CAPTCHA.

As per #18647 (comment 179741) (2021Q4):

According to Tor devs, Salmon is just a future a plan, and we shouldn't be worried by it.

The Moat API is here to stay. It is currently implemented by BridgeDB. BridgeDB is going to be replaced by rdsys sooner or later, but the Moat API will still be available.

But things have been changing since: according to https://gitlab.torproject.org/tpo/anti-censorship/rdsys/-/blob/main/doc/distributors.md, the Moat distribution mechanism is being deprecated in favor of the "Settings" distributor, which we should use instead.

User research findings

• During #18762 (closed), P1 and P2 mentioned not feeling safe sending an email to get bridges, especially using Gmail, because they understand that both things could be connected.
• Someone from Russia requested this on tails-bugs@ on 2023-02-18 because they can't access Tor otherwise.

Implementation

• Old WIP branch, that dates back from when Tor Launcher was a thing: wip/feature/15331-moat
• In Tor Browser:
  • configuration lives in the BridgeDB section in browser/app/profile/000-tor-browser.js
  • toolkit/modules/BridgeDB.sys.mjs
  • toolkit/modules/Moat.sys.mjs
    • uses toolkit/modules/DomainFrontedRequests.sys.mjs to use domain fronting via meek
• Other implementations:
  • see list on https://gitlab.torproject.org/tpo/anti-censorship/rdsys/-/blob/main/doc/moat.md#implementations
  • OnionShare implements "Connection Assist", does it use this system?
• The Moat API:
  • Can be accessed with domain fronting.
    • In our use case, it's not can, it's a MUST: we should assume censors block access to bridges.torproject.org.
    • This part needs to bypass our Tor enforcement, likely by running the meek client as a dedicated user or in a special network namespace with different firewall rules.
    • We probably need to write code to manage the meek process and encapsulate connections to go through it. I suppose we would use the lyrebird aka. obfs4proxy implementation of meek_lite.
  • provides:
    • Circumvention Settings endpoints (the new way, which we should use)
      • https://gitlab.torproject.org/tpo/anti-censorship/rdsys/-/blob/main/doc/moat.md
      • This part looks quite straightforward.
    • a bridge, given a captcha but this is being deprecated:
      • https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/42086
      • https://gitlab.torproject.org/tpo/anti-censorship/rdsys/-/issues/173
      • https://gitlab.torproject.org/tpo/anti-censorship/rdsys/-/issues/182
    • a bridge, given no captcha (yes, exactly). The API is ready but there are no bridges in it.
    • circumvention map. This is by-country. Mostly equivalent to the deprecated https://gitlab.torproject.org/tpo/anti-censorship/state-of-censorship/
• Automated test suite: how do we test this?
• It would make more sense (and be easier to implement) if we supported all types of bridges that the Circumvention Settings endpoints return, so perhaps we should implement e.g. Support Snowflake bridges (#5494) and Support meek bridges (#8243) first. And perhaps Add WebTunnel support (#20267) too even if it's not returned by that API yet at the time I'm writing this (2024-07-23).

UX

At this stage, the main goal of this section is to figure out how much or how little UX work we need to get the main expected benefits of this new feature.

Iteration 1

Goal: improve UX for users who already know they need bridges

• "Automatic without configured bridge" mode: no change.
• "Automatic with configured bridge":
  • Add an option to use Circumvention API to get a bridge on bridge screen and error screen.
  • Keep explaining Email Bot and Telegram Bot (and so the QR code scanner) as alternative.
    • Design mockups for this alternative (@sajolida)
• "Hiding" mode: no change.

Iteration 2

Goal: improve UX for users who did not know they needed bridges, when they try to connect somewhere that blocks Tor; maybe help convert some of the people who use the "hiding" mode without a real need

• "Automatic without configured bridge":
  1. Try direct (is that useful?)
  2. Try default bridges (is that useful?)
  3. Try Circumvention API
• "Automatic with configured bridge": no change over Iteration 1.
• "Hiding" mode: no change.

Potential follow-ups

To reap the full benefits of the new Circumvention Settings API, probably as part of future iterations, we may want to go further:

• How much do we want to revisit the whole design of Tor Connection: now that Circumvention Settings can suggest something that should allow the user to connect:
  • Is our automatically vs. hide dichotomy still relevant and the best way to present things?
  • Do we still want to try direct connection & fall back to default bridges, even in the cases when the Circumvention Settings API could tell us that it's not going to work and we instead need a custom bridge that it can actually give us? In other words, can we switch from "give the user all the options and let them try to figure out which one is best for them" to "offer the user settings that we think will work in their situation"?
  • Related: donuts has an idea to work on "Application agnostic user flows, user research, for anti censorship for each product but to keep it consistence" which I guess might include Tails, so let's keep this in mind before embarking on a grand independent redesign of Tor Connection.
• Do we want to use this in the "hide" scenario?