flip_api.user_services.reset_user_mfa
=====================================

.. py:module:: flip_api.user_services.reset_user_mfa


Attributes
----------

.. autoapisummary::

   flip_api.user_services.reset_user_mfa.router


Functions
---------

.. autoapisummary::

   flip_api.user_services.reset_user_mfa.reset_mfa_for_user


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

.. py:data:: router

.. py:function:: reset_mfa_for_user(user_id: uuid.UUID, request: fastapi.Request, db: sqlmodel.Session = Depends(get_session), token_id: uuid.UUID = Depends(verify_token)) -> dict[str, Any]

   Reset a user's TOTP MFA preference and revoke their active sessions.

   Used by administrators to recover users who have lost their
   authenticator device. The Cognito pool is ``OPTIONAL`` (see the cognito
   module for rationale), so the next sign-in does NOT produce a
   ``CONTINUE_SIGN_IN_WITH_TOTP_SETUP`` challenge — Cognito signs the user
   in cleanly, and the app-layer MFA gate (``verify_token`` + the UI
   router guard on ``needsMfaEnrolment``) routes them through the
   post-auth enrolment page instead.

   :param user_id: ID (Cognito ``sub``) of the user whose MFA should be
                   reset. FastAPI validates the path segment, returning 422 on
                   malformed input.
   :type user_id: UUID
   :param request: FastAPI request object.
   :type request: Request
   :param db: Database session.
   :type db: Session
   :param token_id: ID of the authenticated user performing the reset.
   :type token_id: UUID

   :returns: Empty dictionary on success.
   :rtype: dict[str, Any]

   :raises HTTPException: If the caller lacks permission, the target user is not
   :raises found, or the Cognito call fails.: