mud_server.api.auth

Session management and authentication.

This module handles session-based authentication for the MUD server. It provides: 1. Database-backed session storage (source of truth) 2. Session validation with expiration enforcement 3. Permission checks for admin endpoints

Session Lifecycle: 1. Login: New session ID created and stored in the database 2. Requests: Each API call validates session, enforces expiry, updates activity 3. Logout: Session removed from the database 4. Server Restart: Sessions survive until they expire or are revoked

Security Considerations: - Sessions use opaque IDs (UUIDs by default) - Sessions expire using a TTL and (optionally) sliding expiration - Database is the source of truth (supports restart persistence) - Session validation updates activity timestamp to track last action

Future Improvements: - Implement session refresh tokens (“remember me”) - Add device/session management UI - Add optional IP/User-Agent tracking for session audits

Functions

clear_all_sessions()	Clear all sessions from the database.
remove_session(session_id)	Remove a specific session from the database.
get_active_session_count()	Get the count of active (non-expired) sessions.
get_username_from_session(session_id)	Get username from session ID.
get_username_and_role_from_session(session_id)	Get both username and role from session ID.
validate_session(session_id)	Validate session and return user information.
validate_session_for_game(session_id)	Validate session and ensure a character is selected for gameplay.
validate_session_with_permission(session_id, permission)	Validate session and check if user has required permission.

Module Contents

mud_server.api.auth.clear_all_sessions()

Clear all sessions from the database.

This should be called:

1. When performing emergency session resets

2. In test fixtures to ensure clean state

Returns:

Number of sessions removed from the database.

Return type:

int

Side Effects:

• Deletes all rows from sessions table (committed to database)

mud_server.api.auth.remove_session(session_id)

Remove a specific session from the database.

This function handles targeted session removal, typically used when:

1. A user explicitly logs out (via logout endpoint)

2. An admin force-disconnects a user

3. A session is detected as invalid and needs cleanup

Parameters:

session_id (str) – The UUID session identifier to remove.

Returns:

True if the session was removed, False if it was not found.

Return type:

bool

mud_server.api.auth.get_active_session_count()

Get the count of active (non-expired) sessions.

This is useful for:

1. Health check endpoints (reporting active_players)

2. Admin dashboards showing current load

3. Rate limiting decisions based on server load

4. Logging and monitoring

mud_server.api.auth.get_username_from_session(session_id)

Get username from session ID.

Returns None if the session is not found or has expired.

mud_server.api.auth.get_username_and_role_from_session(session_id)

Get both username and role from session ID.

Returns None if the session is not found or has expired.

mud_server.api.auth.validate_session(session_id)

Validate session and return user information.

Returns:

(user_id, username, role)

Raises:

HTTPException(401) – If session_id is invalid or expired

Return type:

tuple[int, str, str]

mud_server.api.auth.validate_session_for_game(session_id)

Validate session and ensure a character is selected for gameplay.

Returns:

(user_id, username, role, character_id, character_name, world_id)

Raises:

• HTTPException(401) – If session_id is invalid or expired

• HTTPException(409) – If no character is selected for this session

Return type:

tuple[int, str, str, int, str, str]

mud_server.api.auth.validate_session_with_permission(session_id, permission)

Validate session and check if user has required permission.

Raises:

• HTTPException(401) – If session is invalid or expired

• HTTPException(403) – If session valid but user lacks required permission