feat: new AlgorithmMismatchError exception

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - validate claims or headers with custom pydantic models for `decode()` ([#34])
 - expired token now raises `TokenExpiredError` upon claims validation ([#24])
+- new exception `AlgorithmMismatchError` is raised during decoding when `'alg'` is valid but not declared as processable by the JWS instance ([#31])
 
 ### :gear: Changes
 
@@ -59,6 +60,7 @@
 :tada: superjwt repository initialization
 
 [#34]: /../../issues/34
+[#31]: /../../issues/31
 [#24]: /../../issues/24
 [#17]: /../../issues/17
 [#15]: /../../issues/15

superjwt/definitions.py

@@ -48,10 +48,15 @@
     "RS256",
     "RS384",
     "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
     "ES256",
+    "ES256K",
     "ES384",
     "ES512",
-    "EdDSA",
+    "Ed25519",
+    "Ed448",
 ]
 
 
@@ -63,11 +68,15 @@ class AlgorithmInstance(Enum):
     RS256 = None  # Placeholder
     RS384 = None  # Placeholder
     RS512 = None  # Placeholder
+    PS256 = None  # Placeholder
+    PS384 = None  # Placeholder
+    PS512 = None  # Placeholder
     ES256 = None  # Placeholder
+    ES256K = None  # Placeholder
     ES384 = None  # Placeholder
     ES512 = None  # Placeholder
-    EdDSA = None  # Placeholder
-    ES256K = None  # Placeholder
+    Ed25519 = None  # Placeholder
+    Ed448 = None  # Placeholder
 
 
 class Key(Enum):

superjwt/exceptions.py

@@ -40,7 +40,7 @@ class SizeExceededError(InvalidTokenError):
 
 
 class MalformedTokenError(InvalidTokenError):
-    """Raised when the token data format is incorrect"""
+    """Raised when the token data format is incorrect."""
 
     error = "Malformed token"
 
@@ -107,6 +107,13 @@ class InvalidAlgorithmError(JWTError):
     error = "Algorithm is invalid"
 
 
+class AlgorithmMismatchError(InvalidAlgorithmError):
+    """Raised during decoding when the algorithm in the JWT header
+    does not match the expected registered algorithms."""
+
+    error = "Algorithm mismatch in header"
+
+
 class AlgorithmNotSupportedError(InvalidAlgorithmError):
     """Raised when the specified algorithm is not supported."""
 

superjwt/jws.py

@@ -17,6 +17,7 @@
     prepare_and_validate_data,
 )
 from superjwt.exceptions import (
+    AlgorithmMismatchError,
     HeaderValidationError,
     InvalidHeaderError,
     JWTError,
@@ -249,7 +250,7 @@ def validate_headers_and_algorithm(
         # check algorithm match
         pass_through = self.algorithm.name == "none" and self._allow_none_algorithm
         if not pass_through and headers_validated.alg != self.algorithm.name:
-            raise InvalidHeaderError(
+            raise AlgorithmMismatchError(
                 f"JWS algorithm '{headers_validated.alg}' does not match expected '{self.algorithm.name}'"
             )
 

tests/test_jws.py

@@ -1,6 +1,11 @@
 import pytest
 from superjwt.definitions import JOSEHeader
-from superjwt.exceptions import InvalidHeaderError, JWTError
+from superjwt.exceptions import (
+    AlgorithmMismatchError,
+    HeaderValidationError,
+    InvalidHeaderError,
+    JWTError,
+)
 from superjwt.jws import JWS
 from superjwt.keys import OctKey
 
@@ -67,7 +72,7 @@ def test_wrong_header_algorithm(
     headers = JOSEHeader(alg="HS256")
     headers.alg = "ABCDEF"  # wrong algorithm in header  # type: ignore
 
-    with pytest.raises(InvalidHeaderError):
+    with pytest.raises(HeaderValidationError):
         jws_HS256.encode(
             headers=headers,
             payload=claims_fixed_dt.to_dict(),
@@ -96,8 +101,8 @@ def test_wrong_header_algorithm(
     jws_HS256.reset()
 
     # algorithm mismatch error
-    with pytest.raises(InvalidHeaderError):
-        jws_HS256.decode(token=invalid_compact, key=key)
+    with pytest.raises(AlgorithmMismatchError):
+        jws_HS256.decode(token=invalid_compact, key=key, validation_headers=None)
     jws_HS256.reset()
 
     decoded_claims = JWTCustomClaims(