Dmitri
8996161cc9
All checks were successful
Build and Push Docker Image / build-and-push (push) Successful in 12m50s
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# Rhythm Backend API Documentation
|
|
|
|
## Authentication System Overview
|
|
|
|
The authentication system is built with a security-first approach, featuring multi-layered protection against common web vulnerabilities.
|
|
|
|
### Security Layers (Middleware)
|
|
|
|
1. **Rate Limiting (Anti-Spam Bucket)**
|
|
- **Mechanism:** Token Bucket (in-memory `DashMap`).
|
|
- **Logic:** Identifies users via the `X-Client-IP` header (trusted from proxy).
|
|
- **Config:** 5 attempts per minute, refilling 1 token every 12 seconds.
|
|
- **Response:** `429 Too Many Requests`.
|
|
|
|
2. **Anti-Enumeration (Timing Protection)**
|
|
- **Mechanism:** Variable response delay.
|
|
- **Logic:** Ensures every authentication request takes between 150ms and 300ms.
|
|
- **Purpose:** Hides whether an account exists or a password was correct from timing analysis.
|
|
|
|
### Current API Endpoints
|
|
|
|
#### `POST /api/v1/auth/register`
|
|
Registers a new user.
|
|
- **Payload:** `RegisterRequest { email, password }`
|
|
- **Response:** `200 OK` with `AuthResponse { access_token }`
|
|
- **Side Effect:** Sets an `HttpOnly`, `Secure`, `SameSite=Strict` cookie named `refresh_token`.
|
|
|
|
#### `POST /api/v1/auth/login`
|
|
Authenticates a user.
|
|
- **Payload:** `LoginRequest { email, password }`
|
|
- **Response:** `200 OK` with `AuthResponse { access_token }`
|
|
- **Side Effect:** Sets a new `refresh_token` cookie.
|
|
|
|
#### `POST /api/v1/auth/refresh`
|
|
Rotates tokens for an active session.
|
|
- **Requirement:** Valid `refresh_token` cookie.
|
|
- **Response:** `200 OK` with new `access_token`.
|
|
- **Rotation Logic:** Revokes the old refresh token and issues a completely new one (Rotation) to prevent session hijacking.
|
|
|
|
#### `POST /api/v1/auth/logout`
|
|
Invalidates the current session.
|
|
- **Requirement:** Valid `refresh_token` cookie.
|
|
- **Response:** `200 OK`.
|
|
- **Logic:** Revokes the refresh token in the database and clears the HttpOnly cookie.
|
|
|
|
---
|
|
|
|
## Security Features Detail
|
|
|
|
### 1. Rate Limiting (Anti-Spam)
|
|
Protects against brute-force and DoS attacks by limiting requests per IP address. Uses an in-memory Token Bucket algorithm.
|
|
|
|
### 2. Anti-Enumeration (Timing Protection)
|
|
Ensures that the time taken to process an auth request is independent of the result (e.g., whether a user exists or not). This prevents attackers from using timing differences to discover valid emails.
|
|
|
|
### 3. Password Strength (zxcvbn)
|
|
Uses Dropbox's `zxcvbn` algorithm to estimate password entropy. Registration requires a score of at least 3/4.
|
|
|
|
### 4. Refresh Token Rotation
|
|
Every time a refresh token is used to get a new access token, the old refresh token is invalidated and a new one is issued. This limits the window of opportunity if a refresh token is leaked.
|