# JWT Authentication Documentation
This document explains the JWT authentication mechanism used in our web application.
To obtain a JWT token, the user needs to make a one-shot auth request to the appropriate endpoint.
The JWT token must be guarded carefully and treated as a secret.
## One-Shot Auth
The one-shot auth mechanism is used to protect the endpoints that grant JWT tokens. The user must
first obtain a challenge ID by sending a PUT request to the `/challenges` endpoint with a JSON
body of `{"path": "$http_verb $url_path"}`. The `path` field should be set to the path of the
endpoint that grants the JWT token, for example, `GET /vendors/{vendor-id}/auth`. The server
will respond with a JSON object containing a `challenge-id`.
The user must then make a GET request to the JWT token endpoint with the challenge ID and the
six-digit response code sent to their email. The challenge ID should be provided in the
`ST-Challenge-ID` header, and the response code should be provided in the `ST-Challenge-Response`
header. If the challenge ID and response code are valid, the server will respond with a JWT token.
## Storing and Using the JWT Token
The JWT token is a secret and should not be disclosed. To store the JWT token, it can be saved
as a cookie in the user's browser.
To use the JWT token to access protected endpoints, the JWT token must be included in the
HTTP authorization header of the request. The format of the HTTP authorization header is
as follows:
Authorization: Bearer <JWT-Token>
In most front-end frameworks, you can add the JWT token to the authorization header by
including it in the headers object of the HTTP request. Here's an example in JavaScript
using the `fetch` function:
```javascript
const jwtToken = /* Obtain JWT token from the server */;
fetch('https://example.com/api/data', {
headers: {
'Authorization': 'Bearer ' + jwtToken
}
}).then(response => {
/* Handle response */
});
```
The JWT token has a limited lifetime, after which the user will need to obtain a new JWT token to access protected endpoints.
## JWT Resources
- [jwt.io]
- [https://en.wikipedia.org/wiki/JSON_Web_Token]
# Security concerns
## Vulnerability to brute-forcing
Without any sort of rate-limiting, a user could hammer the challenge endpoint until their
lucky number comes up as the response code.
### Mitigation 1: A single challenge out at a time
Require no more than one auth-code out at a time for an email address.
This would have the problem of allowing a malicious user to lock out a legitimate user from
authenticating.
To enforce, I would need to scan the challenges table or add a secondary index of who's got
challenges outstanding.