mud_server.api.auth
===================

.. py:module:: mud_server.api.auth

.. autoapi-nested-parse::

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

.. autoapisummary::

   mud_server.api.auth.clear_all_sessions
   mud_server.api.auth.remove_session
   mud_server.api.auth.get_active_session_count
   mud_server.api.auth.get_username_from_session
   mud_server.api.auth.get_username_and_role_from_session
   mud_server.api.auth.validate_session
   mud_server.api.auth.validate_session_for_game
   mud_server.api.auth.validate_session_with_permission


Module Contents
---------------

.. py:function:: 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.

   Side Effects:
       - Deletes all rows from sessions table (committed to database)


.. py:function:: 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

   :param session_id: The UUID session identifier to remove.

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


.. py:function:: 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


.. py:function:: get_username_from_session(session_id)

   Get username from session ID.

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


.. py:function:: 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.


.. py:function:: 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


.. py:function:: 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
   :raises HTTPException(409): If no character is selected for this session


.. py:function:: 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
   :raises HTTPException(403): If session valid but user lacks required permission