Show a more specific error message if a user has h's HTML auth cookie but not the API auth cookie

[seanh]

Context

h uses two separate authentication cookies: an HTML auth cookie is used to authenticate requests for HTML pages, and a separate API auth cookie is used to authenticate requests made by h's own frontend code to some of h's JSON API endpoints (see #8861).

Problem

If for some reason the user's browser does not include the API auth cookie in an API request made by h's JavaScript code then the user will see a generic error message:

The response that the frontend receives to its unauthenticated create-group API request is 404 Not Found with this JSON body:

{
  "status": "failure",
  "reason": "Either the resource you requested doesn't exist, or you are not currently authorized to see it."
}

This should never happen or at least it should be rare:

• Both cookies are always set at the same time (at login) and deleted at the same time (on logout) and have the same max-age. So the browser should always have either both cookies or neither.

• Use a separate auth cookie for API requests #8861 also contains transitional code for existing logged-in users who had the HTML cookie but not the API cookie to detect that situation and issue an API cookie that will have a max-age beyond that of the existing HTML cookie.

• This can't currently be broken by a user going into their dev tools and deleting the API cookie but not the HTML one: the transitional code from Use a separate auth cookie for API requests #8861 would detect that situation and issue a new API cookie.

  If Remove no-longer-needed transitional cookie code #8865 was merged then the transitional code would no longer be present to save us in that situation, so perhaps we should consider closing Remove no-longer-needed transitional cookie code #8865 and making the transitional code permanent.

• Having a browser extension that blocks the API cookie but not the HTML one would still be a problem, but that seems unlikely to me particularly because it would have to specifically block the API cookie but not the HTML one.

Solution

Change the backend to detect this situation (someone is calling an API endpoint that requires authentication, but their request is unauthenticated) and send some sort of JSON error response that says to the caller "You need to be authenticated to call that API" rather than a generic 401 Unauthorized (which could apply to an authenticated request from a user who isn't authorized to make the given API call) or 404 Not Found.

The frontend knows that its API requests should always be authenticated so it should never receive a "You need to be authenticated" error from the backend. So the frontend can handle these new error responses from the backend by showing the user a more helpful error message, for example perhaps suggesting that they try logging out and in again.