This is the browser proxy component of Snowflake.
See https://snowflake.torproject.org/ for more info:
<iframe src="https://snowflake.torproject.org/embed.html" width="88" height="16" frameborder="0" scrolling="no"></iframe>
npm install
npm run build
which outputs to the build/
directory.
-
npm install
-
-
For Gecko (e.g. Firefox):
npm run webext gecko
-
For Chromium (e.g. Chrome, Edge)
npm run webext chromium
-
and then load the build-webext/
directory as an unpacked extension.
- https://developer.mozilla.org/en-US/docs/Tools/about:debugging#Loading_a_temporary_extension
- https://developer.chrome.com/extensions/getstarted#manifest
Unit testing with Jasmine are available with:
npm install
npm test
To run locally, first build it with:
npm run build
Then start an HTTP server in build/
and navigate to /embed.html
.
Background information:
- https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/-/issues/23947#note_2591838
- https://help.torproject.org/tsa/doc/static-sites/
- https://help.torproject.org/tsa/doc/ssh-jump-host/
You need to be in LDAP group "snowflake" and have set up an SSH key with your LDAP account. In your ~/.ssh/config file, you should have something like:
Host staticiforme
HostName staticiforme.torproject.org
User <your user name>
ProxyJump people.torproject.org
IdentityFile ~/.ssh/tor
npm install
npm run build
Do a "dry run" rsync with -n
to check that only expected files are being changed. If you don't understand why a file would be updated, you can add the -i
option to see the reason.
rsync -n --chown=:snowflake --chmod ug=rw,D+x --perms --delete -crv build/ staticiforme:/srv/snowflake.torproject.org/htdocs/
If it looks good, then repeat the rsync without -n
.
rsync --chown=:snowflake --chmod ug=rw,D+x --perms --delete -crv build/ staticiforme:/srv/snowflake.torproject.org/htdocs/
You can ignore errors of the form rsync: failed to set permissions on "<dirname>/": Operation not permitted (1)
.
Then run the command to copy the new files to the live web servers:
ssh staticiforme 'static-update-component snowflake.torproject.org'
Making a new release involves updating a few places,
- Uploading the webextension to the Firefox Add-ons and Chrome Web Store
- Publishing the new version to the npm repository
- Deploying the badge to snowflake.torproject.org
The following is a rough guide to getting that done:
# Clean things up
npm run clean
# Maybe check what's left behind
git clean -n -d -x
# Be sure that website.json and messages.json in translation/en/ have been
# populated with any new strings that may have been merged in the recent
# patches. It may take some time for weblate to have updated. You can
# check with the following,
git submodule update --remote
# We manage the translations we include manually. These translations are
# tracked separately for the website and the badge. Visit weblate to see
# the percentage completion for each language and update `websiteLangs`
# and `badgeLangs` in `make.js` accordingly. The links for weblate are:
# https://hosted.weblate.org/projects/tor/snowflake-badge/
# https://hosted.weblate.org/projects/tor/snowflake-website/
# But note that it's also run as part of the "pack-webext" script, so return
# it to previously committed state,
git submodule update
# Bump and pack the webext, where "x.y.z" is the version being released
npm run pack-webext x.y.z
# Push the bump commit and tags
git push origin master
git push origin --tags
# Upload the generated build-webext-chromium.zip, build-webext-gecko.zip (and source.zip) to the webextension stores, respectively,
# 1. https://chrome.google.com/webstore/devconsole/
# 2. https://addons.mozilla.org/en-US/developers/addon/torproject-snowflake/versions/submit/
# This time, really clean, because we don't want any extraneous files uploaded
git clean -f -d -x
# Send it off to npm
npm publish
# Clean things up
npm run clean
# From here on out, follow the "Deploying" section of the README
With no parameters,
snowflake uses the default relay snowflake.freehaven.net:443
and
uses automatic signaling with the default broker at
https://snowflake-broker.freehaven.net/
.
The badge and the webextension make use of the same underlying library and only differ in their UI. That same library can be produced for use with other interfaces, such as Cupcake, by running,
npm install
npm run library
which outputs a ./snowflake-library.js
.
You'd then want to create a subclass of UI
to perform various actions as
the state of the snowflake changes,
class MyUI extends UI {
...
}
See WebExtUI
in init-webext.js
and BadgeUI
in init-badge.js
for
examples.
Finally, initialize the snowflake with,
var log = function(msg) {
return console.log('Snowflake: ' + msg);
};
var dbg = log;
var config = new Config("myui"); // NOTE: Set a unique proxy type for metrics
var ui = new MyUI(); // NOTE: Using the class defined above
var broker = new Broker(config.brokerUrl);
var snowflake = new Snowflake(config, ui, broker);
snowflake.beginServingClients();
This minimal setup is pretty much what's currently in init-node.js
.
When configuring the snowflake, set a unique proxyType
(first argument
to Config
) that will be used when recording metrics at the broker. Also,
it would be helpful to get in touch with the Anti-Censorship Team at the
Tor Project to let them know about your tool.