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)

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.
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.

2.6 KiB Raw Blame History