flip_api.auth.dependencies
==========================

.. py:module:: flip_api.auth.dependencies


Attributes
----------

.. autoapisummary::

   flip_api.auth.dependencies.security


Functions
---------

.. autoapisummary::

   flip_api.auth.dependencies._decode_cognito_jwt
   flip_api.auth.dependencies._decode_verified_claims
   flip_api.auth.dependencies._extract_user_id
   flip_api.auth.dependencies._extract_username
   flip_api.auth.dependencies.verify_token
   flip_api.auth.dependencies.verify_token_no_mfa


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

.. py:data:: security

.. py:function:: _decode_cognito_jwt(token: str) -> dict[str, Any]

   Verify a Cognito-issued access token and return its claims.

   Performs the verification steps documented by AWS for Cognito user pool tokens:
   signature, expiry, issuer, ``token_use == "access"``, and ``client_id`` binding
   to this app client. ID tokens (and any other ``token_use``) are rejected — see
   issue #344 for the rationale.

   Raises ``jwt.InvalidTokenError`` (or a subclass) on any validation failure.


.. py:function:: _decode_verified_claims(token: str) -> dict[str, Any]

   Validate a Cognito JWT and return its verified claims.

   :param token: The raw bearer token.
   :type token: str

   :returns: The decoded JWT payload.
   :rtype: dict[str, Any]

   :raises HTTPException: If token is invalid, expired, or wrong type.


.. py:function:: _extract_user_id(payload: dict[str, Any]) -> uuid.UUID

   Return the ``sub`` claim as a UUID, raising 401 on failure.


.. py:function:: _extract_username(payload: dict[str, Any]) -> str

   Return the Cognito Username claim (email in our pool) from an access token.

   :raises HTTPException: If the claim is missing (401).


.. py:function:: verify_token(credentials: fastapi.security.HTTPAuthorizationCredentials = Depends(security)) -> uuid.UUID

   Verify a Cognito JWT and enforce that the caller has TOTP MFA enabled.

   The MFA requirement is checked at the application boundary (rather than
   at the Cognito pool) so admin resets take effect immediately — see the
   comment on ``aws_cognito_user_pool.flip_user_pool`` in the cognito
   module for the full rationale. MFA-bootstrap endpoints use
   :func:`verify_token_no_mfa` instead.

   :param credentials: Bearer credentials from
                       the incoming request.
   :type credentials: HTTPAuthorizationCredentials

   :returns: The user ID (``sub`` claim) from the verified token.
   :rtype: UUID

   :raises HTTPException: 401 if the token is invalid, expired, or missing
       claims; 403 if the caller has not enrolled TOTP.


.. py:function:: verify_token_no_mfa(credentials: fastapi.security.HTTPAuthorizationCredentials = Depends(security)) -> uuid.UUID

   Verify a Cognito JWT without requiring TOTP MFA.

   Reserved for the MFA bootstrap endpoints (status check, enrolment
   helpers) that a freshly-reset or newly-invited user needs to reach
   before they have an active authenticator. Every other route must use
   :func:`verify_token`.

   :param credentials: Bearer credentials from
                       the incoming request.
   :type credentials: HTTPAuthorizationCredentials

   :returns: The user ID (``sub`` claim) from the verified token.
   :rtype: UUID

   :raises HTTPException: 401 if the token is invalid, expired, or missing
       claims.