"Login lost" error when going back to a publisher page with 3rd-party accounts

# Problem

When the client is embedded in a partner site and using third-party accounts, an issue with the OAuth-based authorization system is that using the browser's **Back** button (or otherwise re-navigating to a page you've been to before, e.g. by clicking on links, changing tabs, waking laptop, etc) can result in the client asking the user to reload the page:

1. Make sure you have caching enabled in your browser (e.g. not the **Disable cache** checkbox checked in **Network** dev tools)
2. Visit http://localhost:5050/ (the publisher test site, with an embedded client)
3. Log in
4. Wait for 3 minutes
5. Now browse to another page in the same tab (could be another page on the publisher site, or a different website)
6. Wait for 3 minutes
7. Use the browser's back button to go back to http://localhost:5050/

**Result**: you get a broken sidebar that asks you to reload the page:


In order to get the broken sidebar at least 5 minutes must have passed in total between when you first loaded http://localhost:5050/ (step 1) and when you went back to it (step 7). This is because the grant token that the publisher site renders into the page needs to be expired, and grant tokens live for 5 minutes. The 5 minutes can be spent on the http://localhost:5050/ page and/or on any number of other pages (publisher site or other site) before going back to http://localhost:5050/ using the back button.

What's happening here is that the publisher site renders a grant token into the HTML of the page ([as documented here](http://h.readthedocs.io/projects/client/en/latest/publishers/config/#cmdoption-arg-granttoken)) and the Hypothesis client then exchanges the grant token with the Hypothesis web service for an access token. The grant token is only valid for 5 minutes, so the publisher site renders a **fresh** grant token into the page each time it renders the page. But when the user navigates to a publisher page that they've been to before their browser shows them its cached copy of the page, which contains the previous, now expired grant token.

This issue is a bit awkward to reproduce in a dev environment but it actually might not be that rare in production - real users _will_ have caching enabled in their browser, it probably isn't that rare to go back to a page after 5 minutes, and I think if there's a link to click on to go to the page again (rather than using the back button) that would produce the issue as well.

# Possible Solutions

## Reduce partner page cache time

This **may not be an issue if the partner sets the cache lifetime of their pages to less than the cache lifetime of the grant tokens** (five minutes), so the issue may be avoidable that way. Requires some investigation of what exactly the behaviour of browser caches are with different cache headers and different ways of navigating (clicking on links, using back and forward buttons, ...).

But it's a shame that the grant token is limiting the cacheability of pages though. (The fact that the page contains a grant token, which is different for every user, in the first place already hurts the cacheability of the page, but this issue means the page can't even be cached for more than 5 mins on a per-user basis by their browser.)

## Require grant token Promise rather than string

This issue can also be fixed by [replacing the grant token with a promise for a grant token](https://github.com/hypothesis/product-backlog/issues/330) which eLife intend to do. Our intention in that issue was initially to make using a promise **optional**, using a synchronous grant token would still be an option for publishers, but this issue maybe means that a Promise should be **required**, and grant tokens as plain strings not allowed.

# See Also

* [Allow partner sites to provide grant tokens asynchronously](https://github.com/hypothesis/product-backlog/issues/330)
* [The client needs to handle OAuth-related errors in a user-friendly way](https://github.com/hypothesis/product-backlog/issues/169)
* Slack discussion: https://hypothes-is.slack.com/archives/C5JB5AL11/p1498647429038634
* Earlier Slack discussion: https://hypothes-is.slack.com/files/seanh/F5EGRB43A/screenshot_from_2017-05-18_17-49-52.png

Start with the publisher test site at http://localhost:5050/ and trace the OAuth grant-token exchange when returning to a cached page after the five-minute token lifetime. Reproduce the Back-button flow with browser caching enabled; done means the embedded client no longer shows a broken sidebar asking the user to reload.

Written by the indexing model from the issue text.