Merge pull request #1 from BelCo94/enrich-token-expired

feat: add jti to TokenExpired exception and get_unverified_jwt method

Author: ivolnistov

src/fastapi_jwt_harmony/base.py

@@ -170,6 +170,33 @@ def configure(
         if denylist_callback:
             cls._token_in_denylist_callback = denylist_callback
 
+    def get_unverified_jwt(self, encoded_token: Optional[str] = None) -> Optional[dict[str, Union[str, int, bool]]]:
+        """
+        Decode a JWT token without signature or expiration verification.
+
+        This method decodes a JWT token to extract its claims without validating
+        the signature or checking if it has expired. Useful for extracting information
+        from tokens that may be expired or when signature verification is not needed.
+
+        Args:
+            encoded_token: Encoded JWT as a string. If not provided, uses internal token.
+
+        Returns:
+            Decoded token payload if successful, None if no token is available.
+
+        Raises:
+            JWTDecodeError: If the token structure is invalid and cannot be decoded.
+        """
+        token = encoded_token or self._token
+        if not token:
+            return None
+
+        try:
+            decoded: dict[str, Union[str, int, bool]] = jwt.decode(token, options={'verify_signature': False, 'verify_exp': False})
+            return decoded
+        except jwt.DecodeError as e:
+            raise JWTDecodeError(str(e)) from e
+
     def get_raw_jwt(self, encoded_token: Optional[str] = None) -> Optional[dict[str, Union[str, int, bool]]]:
         """
         Decodes and verifies a JSON Web Token (JWT).
@@ -185,10 +212,9 @@ def get_raw_jwt(self, encoded_token: Optional[str] = None) -> Optional[dict[str,
             return None
 
         # Decode token without verification first to check if it's in denylist
-        try:
-            unverified_token = jwt.decode(token, options={'verify_signature': False, 'verify_exp': False})
-        except jwt.DecodeError as e:
-            raise JWTDecodeError(str(e)) from e
+        unverified_token = self.get_unverified_jwt(token)
+        if not unverified_token:
+            return None
 
         # Check if denylist is enabled
         if self.config.denylist_enabled:
@@ -494,7 +520,8 @@ def _verified_token(self, encoded_token: str) -> dict[str, Any]:
             )
             return decoded
         except jwt.ExpiredSignatureError as exc:
-            raise TokenExpired('Token expired') from exc
+            jti_value = (self.get_unverified_jwt(encoded_token) or {}).get('jti')
+            raise TokenExpired('Token expired', jti=str(jti_value) if jti_value else None) from exc
         except jwt.InvalidTokenError as e:
             raise JWTDecodeError(str(e)) from e
 

src/fastapi_jwt_harmony/exceptions.py

@@ -231,12 +231,15 @@ class TokenExpired(JWTHarmonyException):
         status_code (int): HTTP status code corresponding to the exception (401).
         message (str): Description or message explaining the reason for the
             exception.
+        jti (str | None): The JWT ID (jti claim) of the expired token, if available.
     """
 
-    def __init__(self, message: str) -> None:
+    def __init__(self, message: str, jti: str | None = None) -> None:
         """Initializes a token expired error with a message.
 
         Args:
             message (str): The message explaining that the token has expired.
+            jti (str | None): The JWT ID (jti claim) of the expired token, if available.
         """
         super().__init__(401, message)
+        self.jti = jti

tests/test_decode_token.py

@@ -10,7 +10,7 @@
 
 from fastapi_jwt_harmony import JWTHarmony, JWTHarmonyDep, JWTHarmonyRefresh
 from fastapi_jwt_harmony.config import JWTHarmonyConfig
-from fastapi_jwt_harmony.exceptions import JWTHarmonyException
+from fastapi_jwt_harmony.exceptions import JWTDecodeError, JWTHarmonyException, TokenExpired
 from tests.user_models import SimpleUser
 
 
@@ -147,6 +147,39 @@ def test_get_raw_jwt(default_access_token, encoded_token):
     assert auth.get_raw_jwt(encoded_token) == default_access_token
 
 
+def test_get_unverified_jwt(default_access_token):
+    """Test that get_unverified_jwt decodes tokens without verification."""
+    # Reset configuration
+    JWTHarmony._config = None
+
+    JWTHarmony.configure(SimpleUser, JWTHarmonyConfig(secret_key='secret-key'))
+
+    auth = JWTHarmony()
+
+    # Test with valid token
+    token = jwt.encode(default_access_token, 'secret-key', algorithm='HS256')
+    result = auth.get_unverified_jwt(token)
+    assert result == default_access_token
+
+    # Test with expired token (should still decode)
+    expired_payload = {**default_access_token, 'exp': 0}
+    expired_token = jwt.encode(expired_payload, 'secret-key', algorithm='HS256')
+    result = auth.get_unverified_jwt(expired_token)
+    assert result == expired_payload
+
+    # Test with invalid signature (should still decode)
+    token_wrong_sig = jwt.encode(default_access_token, 'wrong-key', algorithm='HS256')
+    result = auth.get_unverified_jwt(token_wrong_sig)
+    assert result == default_access_token
+
+    # Test with completely malformed token (should raise JWTDecodeError)
+    with pytest.raises(JWTDecodeError):
+        auth.get_unverified_jwt('invalid.token')
+
+    # Test with no token provided
+    assert auth.get_unverified_jwt() is None
+
+
 def test_get_jwt_jti(client, default_access_token, encoded_token):
     # Reset configuration
     JWTHarmony._config = None
@@ -339,3 +372,24 @@ def test_invalid_asymmetric_algorithms(client):
     token = auth2.create_access_token(user_claims=user)
     with pytest.raises(RuntimeError, match=r'public_key'):
         client.get('/protected', headers={'Authorization': f'Bearer {token}'})
+
+
+def test_expired_token_includes_jti(default_access_token):
+    """Test that TokenExpired exception includes the jti from expired tokens."""
+    # Reset configuration
+    JWTHarmony._config = None
+
+    JWTHarmony.configure(SimpleUser, JWTHarmonyConfig(secret_key='secret-key'))
+
+    auth = JWTHarmony()
+
+    # Create an expired token using the fixture
+    expired_payload = {**default_access_token, 'exp': 0}  # Expired in 1970
+    expired_token = jwt.encode(expired_payload, 'secret-key', algorithm='HS256')
+
+    # Try to verify the expired token
+    with pytest.raises(TokenExpired, match='Token expired') as exc_info:
+        auth.get_raw_jwt(expired_token)
+
+    # Verify the exception contains the jti
+    assert exc_info.value.jti == default_access_token['jti']