mud_server.db.users_repo
========================

.. py:module:: mud_server.db.users_repo

.. autoapi-nested-parse::

   User account repository operations for the SQLite backend.

   This module isolates account and guest-lifecycle persistence logic from the
   monolithic compatibility facade in ``database.py``.



Functions
---------

.. autoapisummary::

   mud_server.db.users_repo.create_user_with_password
   mud_server.db.users_repo.user_exists
   mud_server.db.users_repo.get_user_id
   mud_server.db.users_repo.get_username_by_id
   mud_server.db.users_repo.get_user_role
   mud_server.db.users_repo.get_user_account_origin
   mud_server.db.users_repo.set_user_role
   mud_server.db.users_repo.verify_password_for_user
   mud_server.db.users_repo.is_user_active
   mud_server.db.users_repo.deactivate_user
   mud_server.db.users_repo.activate_user
   mud_server.db.users_repo.change_password_for_user
   mud_server.db.users_repo.tombstone_user
   mud_server.db.users_repo.delete_user
   mud_server.db.users_repo.unlink_characters_for_user
   mud_server.db.users_repo.cleanup_expired_guest_accounts


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

.. py:function:: create_user_with_password(username, password, *, role = 'player', account_origin = 'legacy', email_hash = None, is_guest = False, guest_expires_at = None)

   Create an account row without provisioning characters.

   :param username: Unique account username.
   :param password: Plain text password (hashed before persistence).
   :param role: Role label for authorization policy.
   :param account_origin: Provenance marker for auditing and cleanup.
   :param email_hash: Optional hashed email value.
   :param is_guest: Whether the account is guest-scoped.
   :param guest_expires_at: Optional guest expiry timestamp.

   :returns: ``True`` when the account is created, otherwise ``False`` for
             uniqueness/integrity conflicts.


.. py:function:: user_exists(username)

   Return ``True`` when a user account exists.


.. py:function:: get_user_id(username)

   Return user id for ``username`` or ``None`` if missing.


.. py:function:: get_username_by_id(user_id)

   Return username for ``user_id`` or ``None`` if missing.


.. py:function:: get_user_role(username)

   Return role for ``username`` or ``None`` if missing.


.. py:function:: get_user_account_origin(username)

   Return account origin label for ``username``.


.. py:function:: set_user_role(username, role)

   Update user role.

   :returns: ``True`` on successful SQL update, otherwise ``False``.


.. py:function:: verify_password_for_user(username, password)

   Verify password against bcrypt hash.

   Uses a dummy hash when user lookup fails to preserve timing behavior.


.. py:function:: is_user_active(username)

   Return ``True`` when the account is active.


.. py:function:: deactivate_user(username)

   Deactivate user account.


.. py:function:: activate_user(username)

   Activate user account.


.. py:function:: change_password_for_user(username, new_password)

   Change user password using bcrypt hash.


.. py:function:: tombstone_user(user_id)

   Soft-delete account row by marking tombstone fields.


.. py:function:: delete_user(username)

   Soft-delete user after detaching characters and removing sessions.


.. py:function:: unlink_characters_for_user(user_id)

   Detach all characters from a user id.


.. py:function:: cleanup_expired_guest_accounts()

   Delete expired guest accounts and detach their character ownership.

   :returns: Number of user rows removed.