Support automatic bridge retrieval

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.

Mockup

Note: this is outdated since the Moat captcha is being deprecated.

CAPTCHA

Success

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

Disclaimer: all this was written by a developer (intrigeri) trying to figure out how much or how little UX work we need to get the benefits of this new feature.

A first iteration could be to only make this available in the "connect automatically + use bridges" scenario, in addition to, or replacing, the QR code. This should be a net improvement for users who already know they need bridges, and does not require much UX work.

A second iteration could be to present the option to retrieve a bridge automatically when both direct connection and the automatic fallback to default bridges failed. This should be a net improvement for users who did not know they needed bridges, when they try to connect somewhere that blocks Tor.

But to reap the full benefits of the new Circumvention Settings API, we would need 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"?
• Do we want to use this in the "hide" scenario?