Opened 9 months ago

Closed 7 months ago

#33035 closed defect (implemented)

create strings for onion service error pages

Reported by: brade Owned by: tbb-team
Priority: Medium Milestone:
Component: Applications/Tor Browser Version:
Severity: Normal Keywords: ux-team, TorBrowserTeam202003
Cc: tbb-team, antonela, asn, dgoulet, arma, stephw, catalyst, emmapeel Actual Points: 0.25
Parent ID: #19251 Points:
Reviewer: Sponsor: Sponsor27-must

Description

For sponsor 27 O2A4 (Better client-side errors), we need strings that can be localized for each onion service error. There are 7 errors listed in ticket:30090#comment:9.

We are implementing error pages that look like Antonela's design at: https://onion-error.glitch.me/

For each of the above errors (XF0-XF6) we need the following strings:

  • Page/tab title ("Problem loading page" in above design; you can see this when you hover over the tab).
  • Header (a title; "404 - Onion Not Found" in above design)
  • Short description (about one line)
  • Long description (optional; Firefox uses simple HTML for some long descriptions but this may make localization difficult).
  • Learn more URL (optional)

Note: for XF4 and XF5, users will only see an error page with the above strings if they dismiss the prompt without providing client authorization (see #30237).

Tor specs (includes a description of each error):

Related browser and UX tickets:

#19251 #30090 #23545

Related tor tickets:

#30382 #32542 #32546

Pili and Antonela -- can you coordinate with the right people to produce the English strings so we can begin the localization process soon?

Child Tickets

Attachments (1)

error-0xF0.png (121.6 KB) - added by mcs 8 months ago.
0xF0 error page

Download all attachments as: .zip

Change History (29)

comment:1 Changed 9 months ago by brade

Summary: crreate strings for onion service error pagescreate strings for onion service error pages

comment:2 Changed 9 months ago by pili

Cc: stephw added

Hi Steph,

Can you help us craft some good strings/error messages? Should we have a quick meeting/brainstorming session with antonela about this?

comment:3 Changed 9 months ago by antonela

Thanks for filing this ticket brade. I've started a spreadsheet here
https://nc.torproject.net/s/QAwoi7MfeeiTPp2

comment:4 Changed 9 months ago by brade

Thanks! I think we should keep the Learn More Label the same as Mozilla (Learn More...) and consistent for all of the errors, so I don't think we need that last column.

comment:5 Changed 9 months ago by brade

comment:6 Changed 9 months ago by pospeselr

Here's some proposed strings (based off of: https://github.com/torproject/tor/blob/6d06f23a4d70a3a6eb92a0b3f61fdecfebdb3275/doc/tor.1.txt#L1418 )

Error Code Tab Title Error Title
Short Description
XF0Problem Loading OnionOnion Descriptor Not Found
The requested onion service descriptor can not be found on the tor network
XF1Problem Loading OnionInvalid Onion Descriptor
The requested onion service descriptor stored on the tor network is invalid
XF2Problem Loading OnionCircuit Creation Failed
Could not establish rendezvous circuit to the requested onion service
XF3Problem Loading OnionCircuit Creation Failed
Could not connect to the onion service through the negotiated circuit
XF4Authorization RequiredOnion Service Requires Authorization
The onion service requires a $(secret-key) to access but none was provided
XF5Authorization FailedOnion Service Authorization Failed
The provided $(secret-key) is incorrect or has been revoked
XF6Address InvalidOnion Service Address Invalid
The provided onion service address is invalid
XF7Problem Loading OnionCircuit Creation Timed Out
Connection to requested onion service timed out when trying to build rendezvous circuit

Where $(secret-key) is whatever we end up naming the thing that lives in the new onion service authentication UI.

comment:7 Changed 9 months ago by dgoulet

Those codes are linked to different failure event when trying to connect to an onion service. But most of them can be summarized into a non technical term that is "what and why it is happening". Here is my attempt:

  • XF0: A descriptor that is not found means the service is not publishing it which summarize to: "Service A.onion is not running".
  • XF1: This will be extremely rare but can happen due to a bug service or client side. Or if someone is deliberately doing it. Or if the service is a custom tor implementation that is mis-behaving. It can be summarized to: "Service is unreachable due to an internal error".
  • XF2: Introduction circuit failed that means the service we are trying to reach does not have circuit established to the introduction point. In other words, it can be considerered: "Service A.onion is not running".
  • XF3: Unable to finalize the connection to the service through the rendezvous circuit. This means two things: Either the rendezvous point is overwhelmed or malicious that is dropping voluntarily the packets. Or, more likely scenario, the service is overwhelmed and is unable to rendezvous in time. The latter is probably what we want to tell the user ;). Like, come back later type of message, NOT pressing new circuit :P.
  • XF4: This one is easy :)
  • XF5: This one is easy :)
  • XF6: This one is easy :)
  • XF7: This should be quite rare but still, maybe not on bad networks. This means that for whatever circuit we tried, it timed out which means we are not even sure we reached the rendezvous or introduction. This most of the time results in a message that could be around "Bad network" or "Unstable connection"... something like that.

comment:8 Changed 9 months ago by steph

I think the strings look good! Few things:

XF0:

  • Change "can not" to "cannot"
  • change "tor network" to "Tor network"

XF1:
-change "tor network" to "Tor network"

comment:9 Changed 8 months ago by catalyst

Cc: catalyst added

Changed 8 months ago by mcs

Attachment: error-0xF0.png added

0xF0 error page

comment:10 Changed 8 months ago by mcs

Kathy and I like all of the suggestions so far, but we wonder if we can make the error screens more user-friendly by providing a less technical explanation near the top of the page while using the long description field to provide more technical details. Combining comment:6, comment:7, comment:8 and mixing in some of our own ideas, here is a proposal for the 0xF0 error:

Tab Title:
Problem Loading Onionsite

Error Title:
The onionsite is not available.

Short Description:
The most likely cause is that the onionsite is offline or disabled.

Long Description:
Details: The requested onion service descriptor cannot be found on the Tor network.

What do other people think? Note that we also tried to use onionsite wherever it made sense to do so.

Below is a screenshot that shows roughly what this would look like (please ignore the placeholder green and red boxes; we do not have artwork for the checkmark and X yet):

https://trac.torproject.org/projects/tor/raw-attachment/ticket/33035/error-0xF0.png

comment:11 Changed 8 months ago by antonela

Thanks for this iteration! I think is a great idea having a friendly wording in the short description. Now, we should work on them. I'll do the first approach asap.

Some UI comments:

  • We are missing the error number. Perhaps is useful to have it in the long-description?
  • Having that padding between the short description and the long one looks weird, especially in short sentences. Can those paragraphs be closer?

For the status icons, I used Photon's defaults

https://design.firefox.com/icons/viewer/#check
https://design.firefox.com/icons/viewer/#stop

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

comment:12 in reply to:  11 ; Changed 8 months ago by mcs

Replying to antonela:

Thanks for this iteration! I think is a great idea having a friendly wording in the short description. Now, we should work on them. I'll do the first approach asap.

That would be great. Thanks!

Some UI comments:

  • We are missing the error number. Perhaps is useful to have it in the long-description?

Kathy and I thought about including the error number, e.g.,

Details: 0xF0 — The requested onion service descriptor cannot be found on the Tor network.

but we decided not to because it seems unnecessary. As long as we make sure that each error has a clear, unique description we should be okay. But I would love to hear what some Network Team people think.

  • Having that padding between the short description and the long one looks weird, especially in short sentences. Can those paragraphs be closer?

We can reduce the vertical spacing, but that spacing is what Firefox uses between its short description and long description. Maybe it looks better for the "standard" errors because the long description usually spans multiple lines? You can try to load https://torproject.org:9876/ to see an example.

For the status icons, I used Photon's defaults

https://design.firefox.com/icons/viewer/#check
https://design.firefox.com/icons/viewer/#stop

Thanks; we will use these.

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

Replying to mcs:

Some UI comments:

  • We are missing the error number. Perhaps is useful to have it in the long-description?

Kathy and I thought about including the error number, e.g.,

Details: 0xF0 — The requested onion service descriptor cannot be found on the Tor network.

but we decided not to because it seems unnecessary. As long as we make sure that each error has a clear, unique description we should be okay. But I would love to hear what some Network Team people think.

Let's include it anyways, even if the error text is clear.

  • Having that padding between the short description and the long one looks weird, especially in short sentences. Can those paragraphs be closer?

We can reduce the vertical spacing, but that spacing is what Firefox uses between its short description and long description. Maybe it looks better for the "standard" errors because the long description usually spans multiple lines? You can try to load https://torproject.org:9876/ to see an example.

I see. We can keep it as it is and see how it looks in the other scenarios.

Thanks!

comment:14 Changed 8 months ago by mcs

Actual Points: 0.25

comment:15 Changed 8 months ago by sysrqb

Cc: emmapeel added

Adding emmapeel for visibility.

comment:16 Changed 8 months ago by antonela

Re comment:11

I've updated the spreadsheet, including short descriptions. Please, take a look.

https://nc.torproject.net/s/QAwoi7MfeeiTPp2

comment:17 Changed 8 months ago by antonela

So, when we started to work on this task, we talked about to offer recovery paths for users who were experiencing the less happy user flow by getting any of these errors.

Our main call to action here is Try Again. Can we verify if Try Again is the best recovery path for all these errors? Should any of those problems encourage another more successful path for recovery?

If we are OK, we are closest to finishing this task than ever.

comment:18 Changed 8 months ago by antonela

Keywords: ux-team added

comment:19 Changed 8 months ago by brade

I'm not sure how best to discuss possible improvements to the strings using the OnlyOffice spreadsheet, so I'm going to comment here.

Can we use "Onionsite" for the less technical text and "onion service descriptor" for the technical text (long description)? For example the tab titles could be "Problem Loading Onionsite". For XF0, the error title could be "Onionsite Not Found".

Do we want to include the error code in the Long Description?

Mark and I also have some suggested word-smithing for the Error Title and the Short Description. We tried to provide a unique title so users can distinguish among the errors at a glance, and we tried to add some guidance to lead the user toward possible next steps ("Contact the onionsite administrator"). Here's what we came up with:

CodeError TitleShort Description
XF0Onionsite Not FoundThe most likely cause is that the onionsite is offline or disabled. Contact the onionsite administrator.
XF1Onionsite Cannot Be ReachedThe onionsite is unreachable due to an internal error.
XF2Onionsite Has DisconnectedThe most likely cause is that the onionsite is offline or disabled. Contact the onionsite administrator.
XF3Unable to Connect to OnionsiteThe onionsite is busy or the Tor network is overloaded. Try again later.
XF4Onionsite Requires AuthenticationAccess to the onionsite requires a key but none was provided.
XF5Onionsite Authentication FailedThe provided key is incorrect or has been revoked. Contact the onionsite administrator.
XF6Invalid Onionsite AddressThe provided onionsite address is invalid. Please check that you entered it correctly.
XF7Onionsite Circuit Creation Timed OutFailed to connect to the onionsite, possibly due to a poor network connection.

comment:20 in reply to:  19 ; Changed 8 months ago by antonela

Replying to brade:

I'm not sure how best to discuss possible improvements to the strings using the OnlyOffice spreadsheet, so I'm going to comment here.

It is a collaborative document, so you should be able to click and comment or edit. Shared documents seem to be the best way to approach collaborative work. Especially to discuss content.

Can we use "Onionsite" for the less technical text and "onion service descriptor" for the technical text (long description)? For example the tab titles could be "Problem Loading Onionsite". For XF0, the error title could be "Onionsite Not Found".

Works for me.

Do we want to include the error code in the Long Description?

Yes, we do.

Mark and I also have some suggested word-smithing for the Error Title and the Short Description. We tried to provide a unique title so users can distinguish among the errors at a glance, and we tried to add some guidance to lead the user toward possible next steps ("Contact the onionsite administrator"). Here's what we came up with:

CodeError TitleShort Description
XF0Onionsite Not FoundThe most likely cause is that the onionsite is offline or disabled. Contact the onionsite administrator.
XF1Onionsite Cannot Be ReachedThe onionsite is unreachable due to an internal error.
XF2Onionsite Has DisconnectedThe most likely cause is that the onionsite is offline or disabled. Contact the onionsite administrator.
XF3Unable to Connect to OnionsiteThe onionsite is busy or the Tor network is overloaded. Try again later.
XF4Onionsite Requires AuthenticationAccess to the onionsite requires a key but none was provided.
XF5Onionsite Authentication FailedThe provided key is incorrect or has been revoked. Contact the onionsite administrator.
XF6Invalid Onionsite AddressThe provided onionsite address is invalid. Please check that you entered it correctly.
XF7Onionsite Circuit Creation Timed OutFailed to connect to the onionsite, possibly due to a poor network connection.

Looks good for me. Do we need any other reviewers?

comment:21 in reply to:  20 Changed 8 months ago by mcs

Replying to antonela:

Replying to brade:

I'm not sure how best to discuss possible improvements to the strings using the OnlyOffice spreadsheet, so I'm going to comment here.

It is a collaborative document, so you should be able to click and comment or edit. Shared documents seem to be the best way to approach collaborative work. Especially to discuss content.

It looks like I can edit; cool! I went ahead and copied the proposed strings from comment:19 into the spreadsheet.

Do we need any other reviewers?

I think the relevant people are already CC'd on this ticket, so hopefully they are paying attention :)

Kathy and I made a pass through the long description strings and did some word-smithing to make the text easier to understand (while hopefully keeping the technical info intact).

Network Team people: please quickly read through the Long Description column in the following spreadsheet and verify that we did not change the meaning of any of the errors:
https://nc.torproject.net/apps/onlyoffice/s/QAwoi7MfeeiTPp2

comment:22 Changed 8 months ago by asn

Quick review:

  • What does "disabled" mean? What's the diff from "offline"? I think offline is a simpler term and also includes "disabled".

Other than that, looks great!

comment:23 in reply to:  22 Changed 8 months ago by mcs

Replying to asn:

Quick review:

  • What does "disabled" mean? What's the diff from "offline"? I think offline is a simpler term and also includes "disabled".

Other than that, looks great!

Thanks. That has been fixed.

Unfortunately, due to an OnlyOffice or NextCloud glitch, the "Long Description" column disappeared yesterday along with our edits. Antonela restored an older copy (thanks!) and Kathy and I went through and reconstructed our long description edits... but I am sure the resulting text is not 100% the same as it was a couple of days ago :(

Antonela and George, please load the spreadsheet and read through the Long Description column one more time. You will know you are looking at the correct revision if each long description string begins with Details: (we added that today after we reconstructed our earlier edits).

https://nc.torproject.net/s/QAwoi7MfeeiTPp2

comment:24 Changed 8 months ago by antonela

I'm sorry the NC file glitched :( Thanks for putting it back mcs, brade!

Looks good for me. Let's see what asn says.

comment:25 in reply to:  17 ; Changed 8 months ago by mcs

Replying to antonela:

So, when we started to work on this task, we talked about to offer recovery paths for users who were experiencing the less happy user flow by getting any of these errors.

Our main call to action here is Try Again. Can we verify if Try Again is the best recovery path for all these errors? Should any of those problems encourage another more successful path for recovery?

Kathy and I did some thinking about this, and we do not think it makes sense to offer a Try Again button for 0xF6 (typo in .onion address). We are unsure about 0xF1 and would appreciate input from the network team. For all of the other errors it makes sense to provide a Try Again button.

comment:26 Changed 8 months ago by sysrqb

Keywords: TorBrowserTeam202003 added

comment:27 in reply to:  25 Changed 8 months ago by sysrqb

Replying to mcs:

Replying to antonela:

So, when we started to work on this task, we talked about to offer recovery paths for users who were experiencing the less happy user flow by getting any of these errors.

Our main call to action here is Try Again. Can we verify if Try Again is the best recovery path for all these errors? Should any of those problems encourage another more successful path for recovery?

Kathy and I did some thinking about this, and we do not think it makes sense to offer a Try Again button for 0xF6 (typo in .onion address).

When we first started discussing this, we had the idea that we could *force* tor to bypass it's checksum verification and try connecting to the onion service regardless of checksum failure. This could be useful in the (off chance) there is a typo within the checksum (portion) of the address and not the public key portion. Overall, this has a pretty low probability of helping, because it is much more likely that the public key has a typo. Honestly, I don't have a strong opinion on this.

On the one hand, I would like us to have usable/useful/smart "recovery" features. On the other hand, if the onion service is offline, then it is offline and we have absolutely no control over that. If the onion service address has a typo in the public key, then we don't have many recovery options. We could present a list of alternative (similar) valid onion addresses, but that is not something we can implement right now (it will take too much time, and I don't know how to create that list in a smart/efficient way).

comment:28 Changed 7 months ago by pili

Resolution: implemented
Status: newclosed

We are done defining strings

Note: See TracTickets for help on using tickets.