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.