# Authentication Specification

## Purpose

Manage user authentication via Authentik OAuth with secure session handling.

## Requirements

### Requirement: OAuth2/OIDC Flow

The system SHALL support OAuth2/OIDC authentication via Authentik.

#### Scenario: User login
- GIVEN a user clicks the login button
- WHEN the frontend redirects to Authentik authorization endpoint
- THEN the user authenticates with Authentik
- AND Authentik redirects back with authorization code

#### Scenario: Token exchange
- GIVEN Authentik has redirected with authorization code
- WHEN the callback endpoint receives the code
- THEN it exchanges the code for access and refresh tokens
- AND sets httpOnly, Secure, SameSite=strict cookies

### Requirement: Session Security

The system SHALL protect sessions using httpOnly cookies.

#### Scenario: Cookie attributes
- GIVEN successful authentication
- WHEN cookies are set
- THEN access_token cookie SHALL be httpOnly
- AND access_token cookie SHALL have Secure flag
- AND access_token cookie SHALL have SameSite=strict
- AND refresh_token cookie SHALL have same attributes

### Requirement: Token Refresh

The system SHALL support automatic token refresh.

#### Scenario: Access token expiration
- GIVEN a user has an expired access token
- WHEN the user makes an authenticated request
- THEN the system uses the refresh token to get a new access token
- AND rotates the refresh token

### Requirement: Session Termination

The system SHALL support explicit logout.

#### Scenario: User logout
- GIVEN an authenticated user
- WHEN the user clicks logout
- THEN all auth cookies are cleared
- AND the refresh token is invalidated

## Dependencies

- Authentik OIDC provider configured
- Database models: User

## Quality Gates

- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass