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





test cache docker build and gitea