fix(mfa): Make MfaRequiredError extend AccessTokenError and privatize encrypt_mfa_token

MfaRequiredError now extends AccessTokenError so existing
except AccessTokenError handlers in get_access_token() callers
continue to work. Callers needing MFA-specific handling can catch
MfaRequiredError before AccessTokenError.

Renamed encrypt_mfa_token to _encrypt_mfa_token since it is only
called internally by ServerClient.get_access_token().

Author: kishore7snehil

src/auth0_server_python/auth_server/mfa_client.py

@@ -105,7 +105,7 @@ async def _resolve_base_url(
     # MFA TOKEN ENCRYPTION / DECRYPTION
     # ============================================================================
 
-    def encrypt_mfa_token(
+    def _encrypt_mfa_token(
         self,
         raw_mfa_token: str,
         audience: str,

src/auth0_server_python/auth_server/server_client.py

@@ -1020,7 +1020,7 @@ async def get_access_token(
                 mfa_requirements = getattr(e, "mfa_requirements", None)
 
                 if raw_mfa_token:
-                    encrypted_token = self._mfa_client.encrypt_mfa_token(
+                    encrypted_token = self._mfa_client._encrypt_mfa_token(
                         raw_mfa_token=raw_mfa_token,
                         audience=audience or self.DEFAULT_AUDIENCE_STATE_KEY,
                         scope=merged_scope or "",

src/auth0_server_python/error/__init__.py

@@ -275,7 +275,7 @@ def __init__(self, message: str, cause: Optional[dict] = None):
         super().__init__("mfa_verify_error", message, cause)
 
 
-class MfaRequiredError(Auth0Error):
+class MfaRequiredError(AccessTokenError):
     """
     Error thrown when MFA step-up is required during token refresh.
 
@@ -291,11 +291,9 @@ def __init__(
         mfa_requirements=None,
         cause: Optional[Exception] = None
     ):
-        super().__init__(message)
-        self.code = "mfa_required"
+        super().__init__("mfa_required", message, cause)
         self.mfa_token = mfa_token
         self.mfa_requirements = mfa_requirements
-        self.cause = cause
 
 
 class MfaTokenExpiredError(Auth0Error):

src/auth0_server_python/tests/test_mfa_client.py

@@ -156,7 +156,7 @@ def test_encrypt_decrypt_roundtrip(self):
             enroll=[{"type": "otp"}],
             challenge=[{"type": "oob"}]
         )
-        encrypted = client.encrypt_mfa_token(
+        encrypted = client._encrypt_mfa_token(
             raw_mfa_token="raw_token_123",
             audience="https://api.example.com",
             scope="openid profile",
@@ -175,7 +175,7 @@ def test_decrypt_expired_token_raises(self, mocker):
         client = _make_client()
         mocker.patch("auth0_server_python.auth_server.mfa_client.time.time",
                      return_value=1000)
-        encrypted = client.encrypt_mfa_token(
+        encrypted = client._encrypt_mfa_token(
             raw_mfa_token="raw",
             audience="aud",
             scope="scope"
@@ -194,7 +194,7 @@ def test_decrypt_invalid_token_raises(self):
 
     def test_decrypt_tampered_token_raises(self):
         client = _make_client()
-        encrypted = client.encrypt_mfa_token(
+        encrypted = client._encrypt_mfa_token(
             raw_mfa_token="raw", audience="aud", scope="scope"
         )
         tampered = encrypted[:-5] + "XXXXX"
@@ -203,7 +203,7 @@ def test_decrypt_tampered_token_raises(self):
 
     def test_encrypt_without_mfa_requirements(self):
         client = _make_client()
-        encrypted = client.encrypt_mfa_token(
+        encrypted = client._encrypt_mfa_token(
             raw_mfa_token="raw", audience="aud", scope="scope"
         )
         context = client.decrypt_mfa_token(encrypted)