hypothesis / hypothesis/h

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

Open
#8,881 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3.2k
Forks
459
Avg merge
27d 1h
Merged PRs (30d)
1

Description

## 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 https://github.com/hypothesis/h/pull/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:

![image](https://github.com/user-attachments/assets/e1f21997-b26e-44cc-862d-d5a3432300dd)

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

```json
{
"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.

* https://github.com/hypothesis/h/pull/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 https://github.com/hypothesis/h/pull/8861 would detect that situation and issue a new API cookie.

If https://github.com/hypothesis/h/pull/8865 was merged then the transitional code would no longer be present to save us in that situation, so perhaps we should consider closing https://github.com/hypothesis/h/pull/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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by tracing the backend authentication handling for the create-group API request and the frontend's handling of JSON API errors. Review the transitional authentication-cookie behavior described in pull requests 8861 and 8865. Done means an API request with the HTML cookie but without the API cookie receives a distinct authentication error that the frontend can present helpfully.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, authentication, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.