Identity, Auth, and Relationships
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- src/osu_server/config.py
- tests/unit/services/test_identity_use_cases.py
- src/osu_server/services/commands/identity/auth_service.py
- src/osu_server/domain/identity/authentication.py
- src/osu_server/domain/identity/users.py
- src/osu_server/domain/identity/sessions.py
- src/osu_server/domain/identity/authorization.py
The Identity, Auth, and Relationships module handles user registration, authentication workflows, and authorization management for the Athena server. It is designed as a modular system that separates core business logic (commands and queries) from transport-specific requirements (stable or lazer clients) while maintaining a strict hexagonal architecture.
The system manages several key concepts including system users, session-based authorization snapshots, and client-specific compatibility outputs. It ensures that business rules—such as password validation and privilege calculation—remain transport-independent through the use of domain dataclasses and use-case boundaries.
Sources: AGENTS.md:144-150, README.md:21-27, tests/unit/services/test_identity_use_cases.py:1-20
Architecture and Domain Structure
The Identity module is structured into distinct layers: Domain, Services (Commands/Queries), and Repositories. Domain models are implemented as standard @dataclass(slots=True) objects to avoid dependencies on external frameworks like Pydantic or SQLAlchemy.
Core Domain Models
| Component | Description |
|---|---|
| User | Represents a persistent user entity with safe username, email, and password hash. |
| SessionAuthorization | A point-in-time snapshot of a session's privileges and roles. |
| Privileges | Bitmask-based capability set (e.g., User, Moderator, Admin). |
| SessionData | Volatile session information stored in Valkey including client info and country. |
Sources: AGENTS.md:164-168, src/osu_server/domain/identity/users.py, tests/unit/services/test_identity_use_cases.py:92-102
Dependency Flow
The system follows a strict inward-facing dependency rule. Domain logic never imports services, repositories, or infrastructure.
The composition layer wires these components using Dishka, where the APP scope owns global state like database engines, and the REQUEST scope handles per-request session dependencies.
Sources: AGENTS.md:79-100, AGENTS.md:103-111
Authentication Workflows
Authentication is divided into command-side mutations (Login, Registration) and query-side lookups (Session Credentials).
Login and Registration
The LoginCommandUseCase and RegisterUserCommandUseCase coordinate with the AuthService to validate credentials and create new users. The registration process includes a "check-only" mode to verify form data without committing to the database.
Session Management
Volatile state such as active sessions and packet queues are stored in Valkey. This allows sessions to persist across application process restarts. The SessionStore provides methods for creating, deleting, and refreshing sessions, as well as updating authorization snapshots.
Sources: AGENTS.md:209-211, tests/unit/services/test_identity_use_cases.py:175-217
Authorization and Privileges
Authorization in Athena utilizes a snapshot-based approach where a user's capabilities are captured at login or updated via specific command use-cases.
Privilege Levels
The system defines Privileges as server-side authorization capabilities. These are distinct from Bancho Client Permissions, which are compatibility-layer outputs derived from internal privileges for stable clients.
| Privilege Property | Use Case |
|---|---|
User | Basic access level for all registered users. |
Moderator | Ability to manage chat and user status. |
Admin | Full server administrative access. |
System | Special privilege level for internal system users. |
Sources: AGENTS.md:164-167, tests/unit/services/test_identity_use_cases.py:64-70
Authorization Refresh Flow
When a user's role changes, the RefreshUserAuthorizationCommandUseCase is invoked to update the active session in Valkey. This ensures that permission changes take effect without requiring a user to re-login.
Configuration and Constraints
Identity behavior is governed by AppConfig settings, which define session lifetimes, rate limits, and security constraints.
| Setting | Type | Default | Description |
|---|---|---|---|
session_ttl | int | 300 | Lifetime of a session in seconds. |
banned_passwords | list[str] | [] | List of passwords disallowed during registration. |
bancho_bot_username | str | "BanchoBot" | Username reserved for the system bot. |
message_max_length | int | 450 | Maximum length for chat messages. |
Sources: src/osu_server/config.py:44-59, src/osu_server/config.py:108-124
Summary
The Identity and Auth module provides a robust foundation for user management in Athena. By strictly separating domain logic from persistence and transport details, the system supports both legacy stable clients and modern lazer clients while ensuring data integrity and security. The use of Valkey for volatile state ensures high availability for user sessions, while the command/query split maintains a clean architecture for authorization updates and credential verification.