[tbb-dev] proposal for #10760 (Integrate TorButton to TorBrowser core ...)
Alex Catarineu
acat at torproject.org
Tue May 14 13:20:17 UTC 2019
A draft proposal for #10760 (Integrate TorButton to TorBrowser core to
prevent users from disabling it) is
attached.
This should already address some review comments in
https://trac.torproject.org/projects/tor/ticket/10760#comment:36.
Feedback appreciated!
--
Alex Catarineu
Tor Browser Developer
acat at torproject dot org
gpg 3F5B D76C 2C9B D09B F4A8 0AB0 75DC D26C 3A21 2E9A
-------------- next part --------------
Filename: NNN-integrate-torbutton-into-tor-browser.txt
Title: Integration of Torbutton into Tor Browser Core
Author: Alex Catarineu
Created: 13-May-2019
Status: Draft Ticket: #10760
Target: Tor Browser 9 (Firefox ESR 68)
1. Overview
This proposal describes how we will integrate Torbutton into the browser
core code.
2. Motivation
We refer to Tor Browser proposal 102 for motivation, since it is shared. This
has been a task in backlog for a while and we intend to use the ESR68 release
to finally integrate Torbutton code in tor-browser repository.
3. Design
The design is similar to the one specified in proposal 102 for Tor
Launcher. One notable difference is that we do not need to maintain the
capability to package the Torbutton code as a XUL/XPCOM extension. Besides,
we will not continue further development of torbutton in a separate repository,
but directly in the tor-browser one.
3.1 Source Code Integration
Torbutton code is already a git submodule inside tor-browser, and used in
Android without being an extension. Its source code is currently placed
in toolkit/torproject/torbutton. For the scope of this proposal, we will
keep that location for the parts that do not require moving somewhere
else in tor-browser repository. This includes XPCOM components, files
needed for the build (moz.build, jar.mn, chrome.manifest), localization,
UI resources and other logic that is loaded in main process (chrome/content,
chrome/skin). Therefore, we leave big code refactorization efforts (e.g. of
torbutton.js) as a next step, once code has been integrated.
Note that this code location differs from browser/extensions where Tor Launcher
will be placed according to proposal 102. This is because while Tor Launcher is
not used in Android, Tor Button components are. Therefore, toolkit seems a
more suitable choice than browser, since the latter is Desktop only, while the
other is shared.
For reviewing purposes, work needed for this proposal for the files in
toolkit/torproject/torbutton will be done on torbutton repository. Once the
changes are accepted, the code will be moved to toolkit/torproject/torbutton
together with the rest of commits in tor-browser needed for the integration.
From then on, 'torbutton' code maintenance will happen entirely on tor-browser
repository. Ideally, we would like to find a way to do this while keeping
change history and original commiters, but we are not sure this is possible.
Changes in tor-browser-build will also be required to remove torbutton as
a dependency.
3.2 The Location of Torbutton Files In The Final Browser Package
All of the Torbutton files will be packaged inside omni.ja in the final
browser package. Within omni.ja, files will be at the following locations:
chrome/torbutton/defaults/preferences/preferences.js
chrome/torbutton/defaults/
chrome/torbutton/components/
chrome/torbutton/content/
chrome/torbutton/locale/
chrome/torbutton/modules/
chrome/torbutton/skin/
3.3 Firefox Build System Integration
We will use the work that was already done for this in #25013 as part of
torbutton integration for Android.
We will modify toolkit/moz.build to not only use torbutton code in Android but
also in Desktop, and also browser/installer/package-manifest.in to include
the needed files.
3.4 Remove unnecessary files for build
The folder structure of torbutton repository is currently:
makexpi.sh
moz.build
pkg
README
README.BUILD
README.RELEASE
src
trans_tools
update-unsigned.rdf
website
We will remove everything that is not needed for building, with the exception
of trans_tool/import-translations.sh, which will be moved one level up
together with the contents of src.
The final structure will be:
chrome
chrome.manifest
components
CREDITS
defaults
jar.mn
modules
moz.build
import-translations.sh
3.5 Code Changes
3.5.1 Components
In order to minimize code changes for the integration, we will keep the
components almost as they are now. One exception is aboutTor, which can be
easily moved to AboutRedirector.cpp by simply adding the about:tor definition
in the corresponding array. After this proposals work, we can revise whether
we can eliminate code that is not needed anymore, perhaps together with
refactorization work for chrome/content scripts.
aboutTor:
Handles about:tor page. Move to AboutRedirector.cpp.
@torproject.org/torbutton-dragDropFilter;1
Filter drag events to prevent OS access to URLs (a potential proxy bypass
vector). Keep as it is.
@torproject.org/torbutton-extAppBlocker;1
Handles displaying confirmation dialogs for external apps and
protocols. Keep as it is.
@torproject.org/startup-observer;1
Sets up Tor Browser networking proxy settings and loads the content-policy
and aboutTor scripts. Keep as it is.
@torproject.org/cookie-jar-selector;1
Used at least by the new identity feature. Probably contains code that
this not used anymore, but keep as it is for now.
@torproject.org/torbutton-torCheckService;1
Verifies if the Tor Service is up and running. Keep as it is.
@torproject.org/torbutton-logger;1
Used internally, not sure if we need a component for this but keep for now.
@torproject.org/domain-isolator;1
Put requests from different first party domains on separate circuits.
Keep as it is.
3.5.2 Overlays in chrome/content
These will not work anymore on ESR68. Therefore, the needed ones will have
to be ported and the rest, dropped. In general, we will try to move them to the
corresponding parts of the browser UI where they would have been overlaid. Next
is a detailed plan, file by file.
torbutton.xul
- Scripts that are needed both in mobile and desktop can be loaded from
browser/base/content/browser.js. Platform specific scripts can be loaded
from the specific browser.xul. The same applies to stylesheets.
- Move localization DTD to browser/base/content/browser-doctype.inc.
- Torbutton context menu will go away: that should include popup.xul
and toolbarpalette.
- Move keyset shortcuts to browser/base/content/browser-sets.inc
menu-items-overlay.xul
- Move elements to browser/base/content/browser-menubar.inc and
browser/components/customizableui/content/panelUI.inc.xul.
menu-overlay.xul
- Move elements to browser/base/content/browser-menubar.inc. For
elements with removeelement="true", comment out the corresponding ones
in previous file.
- Add aboutTor.dtd to browser/base/content/browser-doctype.inc.
tor-circuit-display.xul
- Move css to browser.xul.
- Move elements to browser/components/controlcenter/content/panel.inc.xul.
torbutton-extensions.xul
- This can be moved to toolkit/mozapps/extensions/content/extensions.xul
together with patch for #10280 rebase.
aboutDialog.xul
- Move to browser/base/content/aboutDialog.xul.
torbutton_tb.xul, pref-connection.xul
- Not needed, just remove.
3.5.3 Scripts and other xul files in chrome/content
popup.xul:
- Remove, already mentioned in overlays part.
torcookiedialog.xul
- Used from popup.xul, button used to open it is hidden: remove.
torcookie.js
- Remove, only used in torcookiedialog.xul.
preferences.xhtml, preferences-mobile.js
- Leave as they are.
torbutton.js, tor-circuit-display.js, torbutton_util.js
- Currently loaded in torbrowser.xul, this proposal suggests loading them
in browser.xul or browser.js instead.
These implement, amongst others:
1) New Identity
2) New circuit for this site
3) The circuit display logic
4) The security slider
5) Tor Network Settings
6) Check for Tor Browser update...
7) Showing the state of Tor (green onion vs. crossed out onion)
8) Helpers for 1) - 7)
9) Things in torbutton.js doing e.g. window resizing on start-up
Even though there is potentially significant work to do, for the scope of
this proposal we would prefer to only do changes to these if they are strictly
required to fix ESR68 migration. After the integration has been done,
we can keep doing maintenance work, refactoring and removing
unnecessary code in subsequent tickets or proposals. Some examples of
items that might need some work:
- Move parts of torbutton.js to components when they belong there
(e.g. torbutton_unique_pref_observer).
- Make sure loaded tor scripts in browser.xul or browser.js do not
export more symbols than needed (ideally only functions that need to be
called from some UI element).
- Reviewing New Identity feature (Ticket #30504).
4. Localization
In the final omni.jar we will still ship all the locales that were available
already in Tor Button xpi package. We will have to fix some code that relied on
specific paths to find these locales at runtime, such as
https://gitweb.torproject.org/tor-browser.git/tree/toolkit/xre/nsAppRunner.cpp?h=tor-browser-60.6.1esr-8.5-1&id=178fcbbe24f543a15b165bdc680a5083247e87a3#n1823
For example, in that case the path for es-ES locale would have to be found at
jar:file:///absolute/path/to/firefox/omni.ja!/chrome/torbutton/locale/es-ES/torbutton.dtd
While not strictly needed, we should start working on moving
to the new localization system used in Firefox: Fluent
(https://firefox-source-docs.mozilla.org/intl/l10n/l10n/index.html). However,
to simplify work on this proposal we will postpone these localization migration
efforts until the changes has been accepted merged (Ticket ##30505).
5. Code style
We should follow Firefox internal JS code style. One way is to make sure we
obey their ESLint rules
https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/ESLint. On a
related note, it would be desirable to make a decision on Ticket #26184.
We will also postpone code style changes after the work on this proposal has
been accepted merged, in order to simplify reviewing process (Ticket #30506).
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://lists.torproject.org/pipermail/tbb-dev/attachments/20190514/0b7e6160/attachment.sig>
More information about the tbb-dev
mailing list