Opened 15 months ago

Closed 4 months ago

Last modified 4 months ago

#27385 closed defect (fixed)

https://snowflake.torproject.org/embed is confusing

Reported by: cypherpunks3 Owned by: arlolra
Priority: High Milestone:
Component: Circumvention/Snowflake Version:
Severity: Major Keywords: snowflake, ux-team, anti-censorship-roadmap-july
Cc: antonela, dcf, arlolra, irl, cohosh Actual Points:
Parent ID: Points:
Reviewer: cohosh Sponsor: Sponsor28-must

Description

embed.html should be the go to for embedding snowflake badges in webpages but it currently has a couple of problems,

  1. No description, nothing to suggest to the lambda visitor about what to do.
  1. Clicking on the badge redirects to the options page hosted in torproject.org, but this means that users who have first-party isolation manually enabled (as can be done in Firefox) won't be able to enable it on the page where embed.html is embedded.

Ideally what should be done is:

  1. Small description ("Do you want to help censored users access the Tor network?") with a snowflake logo.
  1. If user clicks on yes, then in that same iframe there's some JS check to see if WebRTC is disabled, if it is inform the user that WebRTC is necessary and perhaps add a link on how to enable it back.
  1. If WebRTC is enabled, then load up snowflake.js and modernizr.js. Description should contain if the connection to the broker is done and is waiting for a client request, and if it is then maybe the logo should change as well as the description. (Since everything is done on the same page then there won't be any problems with first party isolation -- except with 3rd party cookies disabled)

Ideally it should be easy to embed into webpages if what's above is done, and should be small enough.

(cc'ing antonela of the ux-team for her opinions :)

Child Tickets

TicketStatusOwnerSummaryComponent
#31029closedarlolraAdvertise the webextension outside the various storesCircumvention/Snowflake

Change History (31)

comment:1 Changed 15 months ago by arlolra

Duplicate of #25722, no?

comment:2 in reply to:  1 Changed 15 months ago by cypherpunks3

Replying to arlolra:

Duplicate of #25722, no?

That's about the main page, if you rename it to include the embed page then yes.

comment:3 Changed 15 months ago by antonela

hey, thanks for inviting me to the party! I have been playing/reading with/about snowflake, and I have some ideas. Is it this work attached to any deadline?

Added to my plate.

comment:4 in reply to:  3 Changed 15 months ago by cypherpunks3

Replying to antonela:

Is it this work attached to any deadline?

There is no dedicated snowflake maintainer currently so the answer is most probably no. That said I heard recently from a ~150K Alexa rank website owner that he wanted to include snowflake embeds in his site (which prompted me to open this ticket), so if this can be done early it would be nice.

comment:5 Changed 15 months ago by antonela

hi, i came back and i have questions

The user flow is described as:

  1. Volunteers visit websites which host the “snowflake” proxy (where does it happen? On Tor Browser? any browser?).
  2. Tor clients (do you mean relays or the browser?) automatically find available browser proxies via the Broker (the domain fronted signaling channel).
  3. Tor client and browser proxy establish a WebRTC peer connection (where?).
  4. Proxy connects to some relay (to another tor client?).
  5. Tor occurs (what it means? that tor gets 100% bootstrapped?).

So, we have two types of users:

  1. people who host snowflake
  2. people who "activate" snowflake

Lets back to the 1. item, what do you need from users at this moment?

  • Do we want users clicking at the snowflake badge to open a new tab?

In which of the above steps does occur that the user clicks at the badge and get moved to https://keroserene.net/snowflake/options.html? And, when the user arrives there, what we need?

  • We need the browser client with webRTC enabled.
  • We need a user who agreed on saving the world - clicked on YES.

I'm experimenting with using a natural-language user interface to improve options.html. The action is very simple and I don't think we need any more UI artifact to encourage the user’s action.

0

Do you want to help censored users access the Tor network?
Some description of what is happening. You can go a bit technical here.
[Yes] [I want to learn more]

1

We need WebRTC to work. [Enable WebRTC]

2.0

Snowflake Proxy is ACTIVE.
Thank you for contributing to internet freedom! [OFF Snowflake]

2.1

Snowflake Proxy is OFF.
Do you want to help censored users access the Tor network? [Activate Snowflake]

I made a quick prototype, you can click it here https://marvelapp.com/ebf367j/screen/47360204

The badge
I made two options for a better badge. Can we still animate it when is enabled like now? Can I animate it with a little css? What do you think about to have it rotating when is active? :)

Check a quick prototype https://snowfl4k3.glitch.me/

If we export/use svgs, then the site owners can customize the snowflake icon color so easy.

Sorry if I'm asking basic questions, i just want to be sure that i understand all the flow.

Let me know what do you think!

comment:6 Changed 15 months ago by cypherpunks3

@antonela

I get Maximum number of external links per post exceeded and captcha seems to be broken so here's my response:

https://privatebin.net/?40710214fdb2158e#kXFrvLMQnbszkao1cVk5/BPHJZNX+a4JKwKFWb46JWU=

[Edit: dcf pastes cypherpunks3's comment:]

Replying to antonela:

hi, i came back and i have questions

The user flow is described as:

  1. Volunteers visit websites which host the “snowflake” proxy (where does it happen? On Tor Browser? any browser?).

It happens on a browser with WebRTC enabled (Tor Browser isn't one).

  1. Tor clients (do you mean relays or the browser?) automatically find available browser proxies via the Broker (the domain fronted signaling channel).

I don't understand this question exactly, but the rest is correct. They may receive browser proxies or server proxies since there are two ways to run a snowflake proxy: https://trac.torproject.org/projects/tor/wiki/doc/Snowflake#HowtorunaSnowflakeproxy

  1. Tor client and browser proxy establish a WebRTC peer connection (where?).

What do you mean where? :) Like which component does the connection?

  1. Proxy connects to some relay (to another tor client?).

No, it connects to a specific snowflake bridge: (line 46) https://gitweb.torproject.org/builders/tor-browser-bundle.git/tree/Bundle-Data/PTConfigs/bridge_prefs.js#n46 Which you can find on metrics: https://metrics.torproject.org/rs.html#details/5481936581E23D2D178105D44DB6915AB06BFB7F

It wont work with other relays, it must be setup using this to work: https://gitweb.torproject.org/pluggable-transports/snowflake.git/tree/server In the future more snowflake bridges may be added, in which case not all snowflake proxies may connect to the same bridge.

  1. Tor occurs (what it means? that tor gets 100% bootstrapped?).

Yes. What it really means is that a circuit [User -> Snowflake proxy -> Snowflake bridge -> Middle relay -> Exit relay] gets created.

So, we have two types of users:

  1. people who host snowflake
  2. people who "activate" snowflake

Lets back to the 1. item, what do you need from users at this moment?

  • Do we want users clicking at the snowflake badge to open a new tab?

I'm personally against such a design (you want the whole snowflake setup to be fluid and not send them to some other page again). That's also similar to what dcf is thinking on #25722

I propose that both these pages should have a Yes/No button right there 
on the page. Clicking Yes should do both:

    set the opt-in cookie
    start up the proxy (without needing to refresh the page) 

In which of the above steps does occur that the user clicks at the badge and get moved to https://keroserene.net/snowflake/options.html? And, when the user arrives there, what we need?

  • We need the browser client with webRTC enabled.
  • We need a user who agreed on saving the world - clicked on YES.

I'm experimenting with using a natural-language user interface to improve options.html. The action is very simple and I don't think we need any more UI artifact to encourage the user’s action.

0

Do you want to help censored users access the Tor network?
Some description of what is happening. You can go a bit technical here.
[Yes] [I want to learn more]

1

We need WebRTC to work. [Enable WebRTC]

2.0

Snowflake Proxy is ACTIVE.
Thank you for contributing to internet freedom! [OFF Snowflake]

2.1

Snowflake Proxy is OFF.
Do you want to help censored users access the Tor network? [Activate Snowflake]

I made a quick prototype, you can click it here https://marvelapp.com/ebf367j/screen/47360204

The design is much better, and this would describe the options.html page.

For the embed.html one it should have ideally a maximum of 280px in width. Also a "Learn More" link in the bottom corner sounds interesting as well.

The badge
I made two options for a better badge. Can we still animate it when is enabled like now? Can I animate it with a little css? What do you think about to have it rotating when is active? :)

Check a quick prototype https://snowfl4k3.glitch.me/

If we export/use svgs, then the site owners can customize the snowflake icon color so easy.

Animate the logo sounds nice :) There are basically five states:

  • The one who wants to become a snowflake proxy (call him D) waits for a Tor snowflake user (call him F).
  • D successfully connects to F.
  • F is browsing on Tor so there's data transfer to D.
  • F is idle so there are no data transfers.
  • F quits and after a timeout D disconnects and goes back to the first step.

You could have the logo animating when it first connects with a message "Connected" or something like that, then the logo stops and only rotates when it's in the 3rd state above, and you could have the messages "transferring" "idle" (this is not necessary for a first version, but it may be interesting later on so that the one who runs the proxy knows when someone is connecting).

You can also take inspiration from this old flashproxy addon (the predecessor of snowflake): https://addons.cdn.mozilla.net/user-media/previews/full/158/158664.png?modified=1530209248 (that's waiting to be reporposed to incorporate snowflake: https://github.com/glamrock/cupcake/issues/24 )

Sorry if I'm asking basic questions, i just want to be sure that i understand all the flow.

Let me know what do you think!

If I have more time I may even start working a bit on an implementation :)

Last edited 15 months ago by dcf (previous) (diff)

comment:7 Changed 15 months ago by antonela

hey, thanks for all the answers

There are basically five states:
The one who wants to become a snowflake proxy (call him D) waits for a Tor snowflake user (call him F).
D successfully connects to F.
F is browsing on Tor so there's data transfer to D.
F is idle so there are no data transfers.
F quits and after a timeout D disconnects and goes back to the first step.

Great, that gives us:

  1. waiting [white]
  2. no transferring [fuscia]
  3. connected [green]
  4. transferring [green + rotate]
  5. transferring with peers [+1 white + rotate]

https://snowfl4k3.glitch.me/

Wondering if we can add a new snowflake each time a new user gets connected to the proxy/bridge. They will make a cool pattern of snowflakes rotating :)

I used a .svg so you can change the fill color via css.

The prototype was updated too

https://marvelapp.com/ebf367j/screen/47360204

Let me know what is next or if you need any help with the implementation.

Last edited 15 months ago by antonela (previous) (diff)

comment:8 in reply to:  7 ; Changed 12 months ago by dcf

Replying to antonela:

hey, thanks for all the answers

There are basically five states:
The one who wants to become a snowflake proxy (call him D) waits for a Tor snowflake user (call him F).
D successfully connects to F.
F is browsing on Tor so there's data transfer to D.
F is idle so there are no data transfers.
F quits and after a timeout D disconnects and goes back to the first step.

Great, that gives us:

  1. waiting [white]
  2. no transferring [fuscia]
  3. connected [green]
  4. transferring [green + rotate]
  5. transferring with peers [+1 white + rotate]

I would add a state separate from "waiting" to represent when the proxy is disabled because the user has not opted in. I don't think it's worth distinguishing the states "connected and idle" and "connected and transmitting". It's not well-defined anyway, because a proxy can have multiple connections, some idle and some transmitting. I don't understand the difference between "transferring" and "transferring with peers"--what's a peer?

These are the states I am thinking of:

  • disabled because not opted in
  • disabled because of an error (e.g. missing JS, missing WebRTC, unhandled exception)
  • enabled, no clients
  • enabled, at least one client (could depict the number of clients)

comment:9 in reply to:  8 Changed 12 months ago by antonela

These are the states I am thinking of:

  • disabled because not opted in
  • disabled because of an error (e.g. missing JS, missing WebRTC, unhandled exception)
  • enabled, no clients
  • enabled, at least one client (could depict the number of clients)

OK. I updated the prototype to reflect those states:
https://snowfl4k3.glitch.me/

comment:10 Changed 11 months ago by arma

I'm not sure how this idea ties into the above prototypes and requirements, but it might be nice to have something more than the "you aren't being helpful right now" and "you are helping someone now" binary situation.

Specifically, if I turn on my snowflake and go to sleep and wake up and look, and it's on "nope not helpful", I have no idea whether I've been helpful anytime in the past.

So it would be interesting to consider changing the icon over time to reflect not just current state right now, but past contributions.

(The idea came about based on antonela's sentence above about "adding" a snowflake.)

comment:11 Changed 7 months ago by irl

Cc: irl added

comment:12 Changed 7 months ago by pili

Sponsor: Sponsor19

comment:13 Changed 6 months ago by gaba

Keywords: ex-sponsor-19 added

Adding the keyword to mark everything that didn't fit into the time for sponsor 19.

comment:14 Changed 6 months ago by phw

Sponsor: Sponsor19Sponsor28-must

Moving from Sponsor 19 to Sponsor 28.

comment:15 Changed 5 months ago by arlolra

Owner: set to arlolra
Status: newassigned

comment:16 Changed 5 months ago by arlolra

Status: assignedneeds_review

Here's a branch that pretty much gets this done,
https://github.com/keroserene/snowflake/commits/badge

It's rather invasive and doesn't offer much in terms of explanation, sorry.

Last edited 5 months ago by arlolra (previous) (diff)

comment:17 Changed 5 months ago by gaba

Keywords: anti-censorship-roadmap-july added; ex-sponsor-19 removed

comment:18 Changed 5 months ago by arlolra

Cc: cohosh added

It's rather invasive and doesn't offer much in terms of explanation, sorry.

Ok, looking this over, the goal was to,

  • reuse the html and css from the webextension for the badge
  • move setting the cookie over to the badge, using the on/off toggle (as suggested in this ticket)
  • consolidate the use specific code in one place (init, ui, etc)

comment:19 Changed 5 months ago by cohosh

Reviewer: cohosh

comment:20 Changed 4 months ago by cohosh

Overall, I like the code changes and refactors. Smaller commits in the future would be easier to review for changes like this where it's hard to piece together which code was just moved around and where the logic changed.

It looks like cp -r static/{embed.html,embed.css,popup.js,icons} webext/ isn't running properly for some reason. When I run it manually it works, but when I ran npm run webext to build it, the files didn't copy and it fails with the error

The character encoding of the HTML document was not declared. The document will render with garbled text in some browser configurations if the document contains characters from outside the US-ASCII range. The character encoding of the page must be declared in the document or in the transfer protocol.

A few comments on the refactoring:

  • WebExtUI and BadgeUI classes were moved to init-webext.js and init-badge.js, respectively, but DebugUI is still in ui.js. To follow the pattern, should DebugUI be moved to init-test.js? That leaves ui.js pretty sparse...
  • UI.prototype.active = false;
    
    UI.prototype.enabled = true;
    
    This code might be specific to just WebExtUI. If so we should probably move it into that class or init-webext.js.

comment:21 Changed 4 months ago by cohosh

Status: needs_reviewneeds_revision

comment:22 Changed 4 months ago by arlolra

Smaller commits in the future would be easier to review for changes like this where it's hard to piece together which code was just moved around and where the logic changed.

Sorry, I was working on this on the last day of the meeting and just pushed what I had since it wasn't clear when I'd be able to get back to it.

When I run it manually it works, but when I ran npm run webext to build it, the files didn't copy and it fails with the error

Where are getting this error? I'm not able to reproduce it.

A few comments on the refactoring:

Added another commit to the branch to address this,
https://github.com/keroserene/snowflake/commit/f9c515cbdd302097245fd85231dc34c06d234802

I left UI.prototype.active = false; where it was since it's used in both the badge and webextension.

comment:23 in reply to:  22 Changed 4 months ago by cohosh

Replying to arlolra:

When I run it manually it works, but when I ran npm run webext to build it, the files didn't copy and it fails with the error

Where are getting this error? I'm not able to reproduce it.

If I clean the webext directory to remove all nontracked files, and then run npm run webext, the embed.css and embed.html files don't copy over... is this the right way to build the webextenson? It's possible this is just a problem for me locally. I'm using npm version '6.9.0'

Also, maybe not as a part of these changes though, we should probably update the README with insructions to build the webextension

A few comments on the refactoring:

Added another commit to the branch to address this,
https://github.com/keroserene/snowflake/commit/f9c515cbdd302097245fd85231dc34c06d234802

I left UI.prototype.active = false; where it was since it's used in both the badge and webextension.

Cool, looks good to me!

comment:24 Changed 4 months ago by arlolra

is this the right way to build the webextenson?

Yes

It's possible this is just a problem for me locally. I'm using npm version '6.9.0'

I installed that version of npm and it seemed to work for me. What version of node? It's odd that invoking the command manually wasn't an issue. I should test in a different OS.

Also, maybe not as a part of these changes though, we should probably update the README with insructions to build the webextension

They are here but can certainly be improved,
https://gitweb.torproject.org/pluggable-transports/snowflake.git/tree/proxy/webext/README.md

comment:25 in reply to:  24 Changed 4 months ago by cohosh

Replying to arlolra:

It's possible this is just a problem for me locally. I'm using npm version '6.9.0'

I installed that version of npm and it seemed to work for me. What version of node? It's odd that invoking the command manually wasn't an issue. I should test in a different OS.

My host machine is ubuntu 18.04 with node v10.16.0, and I ran it in snowbox which is debian with node v12.1.0

Also, maybe not as a part of these changes though, we should probably update the README with insructions to build the webextension

They are here but can certainly be improved,
https://gitweb.torproject.org/pluggable-transports/snowflake.git/tree/proxy/webext/README.md

Ah, my bad I keep forgetting there's another README in the webext directory.

comment:26 Changed 4 months ago by arlolra

My host machine is ubuntu 18.04 with node v10.16.0, and I ran it in snowbox which is debian with node v12.1.0

I see, this should fix it,
https://github.com/keroserene/snowflake/commit/0aa5ee24d4e4f7fac8a4f63f1917ab2fa34330eb

I also added a commit for #31222 in,
https://github.com/keroserene/snowflake/commit/8385e7c2dab3e587ce63cc522d3a667b02c949b8

If you're happy with this branch, please merge it. I'll be away for a few days

Ah, my bad I keep forgetting there's another README in the webext directory.

Maybe this is an indication that we should move the contents to the one in the higher directory.

comment:27 in reply to:  26 Changed 4 months ago by cohosh

Replying to arlolra:

My host machine is ubuntu 18.04 with node v10.16.0, and I ran it in snowbox which is debian with node v12.1.0

I see, this should fix it,
https://github.com/keroserene/snowflake/commit/0aa5ee24d4e4f7fac8a4f63f1917ab2fa34330eb

Yup, works now. Thanks!

I also added a commit for #31222 in,
https://github.com/keroserene/snowflake/commit/8385e7c2dab3e587ce63cc522d3a667b02c949b8

Awesome, thanks for doing that.

If you're happy with this branch, please merge it. I'll be away for a few days

Okay, sounds good.

comment:28 Changed 4 months ago by cohosh

Status: needs_revisionmerge_ready

comment:29 Changed 4 months ago by cohosh

Resolution: fixed
Status: merge_readyclosed

merged in 8de6e26c597edadac633ae8bed163893f4d932e2

comment:30 Changed 4 months ago by arlolra

merged in 8de6e26c597edadac633ae8bed163893f4d932e2

Thanks, I deployed these changes (which you should now also be able to do, see comment:6:ticket:31143)

Unfortunately, there seems to be some permissioning issue with the icons/ folder. Trying to fix that ...

comment:31 Changed 4 months ago by arlolra

Unfortunately, there seems to be some permissioning issue with the icons/ folder. Trying to fix that ...

It was an aliasing issue (hat tip to @boklm). There's a default alias for icons/, https://www.electrictoolbox.com/apache-icons-directory/

Fixed in (and deployed),
https://gitweb.torproject.org/pluggable-transports/snowflake.git/commit/?id=b324d9d42fff09e7db0f2fe2657a2265a3b39271

Note: See TracTickets for help on using tickets.