From 2dde8d7942361e414053452fdf6c793d2a8cd986 Mon Sep 17 00:00:00 2001 From: ae Date: Thu, 10 Apr 2025 22:31:09 +0300 Subject: [PATCH] docs: csrf handling --- docs/API.md | 7 ++++--- docs/media/auth-sequence.svg | 2 +- docs/media/protected-resource-flow.svg | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/API.md b/docs/API.md index b521032..5a75731 100644 --- a/docs/API.md +++ b/docs/API.md @@ -18,9 +18,10 @@ Endpoints protected with `requireAccessToken` middleware: - `GET /auth/admin/all`: As an administrator, list all users stored in the system (adjustable with pagination URL parameters) -> Array of `userResponse` DTOs - `DELETE /auth/admin/{userID}`: As an administrator, delete a specific user -> HTTP 204 response -Endpoints protected with `requireRefreshToken` middleware: +Endpoints protected with `requireRefreshToken` and `gorilla/csrf` middlewares: -- `POST /auth/refresh`: Perform token rotation (revokes the old refresh token server-side) -> Cookie with new refresh token and response with access token +- `GET /auth/cookie/csrf`: Get new CSRF token -> HTTP 204 response with the token set in the `X-CSRF-Token` response header +- `POST /auth/cookie/refresh`: Perform token rotation (revokes the old refresh token server-side) -> Cookie with new refresh token and response with access token ## Notes @@ -40,7 +41,7 @@ All notes related endpoints are protected with `requireAccessToken` middleware, ![Sequence diagram of the authentication flow](./media/auth-sequence.svg) -- Store access token in memory (never in `localStorage`) +- Store access and CSRF tokens in memory (never in `localStorage`) - Automatically handle 401 responses by attempting token refresh - Queue pending requests during token refresh, if necessary - Clear local tokens on logout (`POST /auth/logout`) diff --git a/docs/media/auth-sequence.svg b/docs/media/auth-sequence.svg index 1107559..02d4a13 100644 --- a/docs/media/auth-sequence.svg +++ b/docs/media/auth-sequence.svg @@ -1,4 +1,4 @@ -
Client
API
POST /api/auth/login
Set refresh_token httpOnly cookie & return access_token
[ Protected request ] (401 if access token is expired)
POST /api/auth/refresh (refresh token as bearer)
Set new refresh_token httpOnly cookie & return access_token
Retry [ Protected request ]
Check if refresh_token 
is in a cookie, otherwise 
redirect to login page
Check if given refresh_token 
can be found in the database
 \ No newline at end of file +
Client
API
POST /api/auth/login
Set refresh token cookie & return access token
[ Protected request ] (401 if access token is expired)
POST /api/auth/cookie/refresh (cookie included)
Set new refresh token cookie & return new access token
Retry [ Protected request ]
Check if refresh_token 
is in a cookie, otherwise 
redirect to login page
Check if given refresh_token 
can be found in the database
GET /api/auth/cookie/csrf (cookie included)
Check if CSRF token
is in memory
 \ No newline at end of file diff --git a/docs/media/protected-resource-flow.svg b/docs/media/protected-resource-flow.svg index 6ae0cd6..8d11b18 100644 --- a/docs/media/protected-resource-flow.svg +++ b/docs/media/protected-resource-flow.svg @@ -1,4 +1,4 @@ -
Access a protected resource
Is locally stored 
access token 
available?
No
Make API request with access token as bearer
Yes
Does response 
contain 401 
status scode?
Request was 
successful
No
Yes
Attempt token refresh
 and attempt to access again
Is still 
unauthorized?
Yes
No
Redirect to 
login page
 \ No newline at end of file +
Access a protected resource
Is locally stored 
access token 
available?
No
Make API request with access token as bearer
Yes
Does response 
contain 401 
status scode?
Request was 
successful
No
Yes
Attempt token refresh
and try to access again
Is still 
unauthorized?
Yes
No
Redirect to 
login page
Is locally stored
CSRF token
available?
Yes
Request new
CSRF token
No
Was the request
successful?
No
Yes
 \ No newline at end of file