feat: Support partial list matching in JWTClaimRegistry.validate, similar to aud claim logic (#63)

* test: add validation tests for custom claims in JWTClaimsRegistry (`list_inclusion` and `allow_blank`)

* feat: improve claim value validation logic in ClaimsRegistry to cover list inclusion validation as well

* docs: add list validation section to JWT claims registry guide

Author: feteu

docs/guide/jwt.rst

@@ -143,6 +143,47 @@ The ``JWTClaimsRegistry`` has built-in validators for timing related fields:
 - ``nbf``: not before
 - ``iat``: issued at
 
+List validation
+~~~~~~~~~~~~~~~
+
+When validating claims that contain lists, the registry checks if **any** of the 
+required values are present in the claim's list. This behavior is designed for 
+flexible authorization checks where matching any of the required permissions grants 
+access. For single values, it checks for an exact match.
+
+This is particularly useful for validating role based or permission based claims. For 
+example:
+
+.. code-block:: python
+
+    # Claim containing a list of permissions
+    claims = {"permissions": ["users:read", "users:write", "users:admin"]}
+
+    # Passes since "users:write" is present in the list
+    claims_requests = JWTClaimsRegistry(
+        permissions={"values": ["users:write", "system:admin"]}
+    )   
+    claims_requests.validate(claims)
+
+    # Raises InvalidClaimError since none of the required values are present
+    claims_requests = JWTClaimsRegistry(
+        permissions={"values": ["system:admin"]}
+    )
+    claims_requests.validate(claims)
+
+You can also validate against a single required value:
+
+.. code-block:: python
+
+    # Claim containing a list of permissions
+    claims = {"permissions": ["users:read", "users:write", "users:admin"]}
+
+    # Passes since "users:read" is present in the list
+    claims_requests = JWTClaimsRegistry(
+        permissions={"value": "users:read"}
+    )
+    claims_requests.validate(claims)
+
 JWS & JWE
 ---------
 

src/joserfc/_rfc7519/registry.py

@@ -26,17 +26,28 @@ def __init__(self, **kwargs: ClaimsOption):
 
     def check_value(self, claim_name: str, value: Any) -> None:
         option = self.options.get(claim_name)
-        if option:
-            allow_blank = option.get("allow_blank")
-            if not allow_blank and value == "":
-                raise InvalidClaimError(claim_name)
+        if not option:
+            return
+        
+        allow_blank = option.get("allow_blank")
+        if not allow_blank and value in (None, "", [], {}):
+            raise InvalidClaimError(claim_name)
 
+        option_values = option.get("values")
+        
+        if option_values is None:
             option_value = option.get("value")
-            if option_value is not None and value != option_value:
-                raise InvalidClaimError(claim_name)
+            if option_value is not None:
+                option_values = [option_value]
 
-            option_values = option.get("values")
-            if option_values is not None and value not in option_values:
+        if not option_values:
+            return
+
+        if isinstance(value, list):
+            if not any(v in value for v in option_values):
+                raise InvalidClaimError(claim_name)
+        else:
+            if value not in option_values:
                 raise InvalidClaimError(claim_name)
 
     def validate(self, claims: dict[str, Any]) -> None:

tests/jwt/test_claims.py

@@ -144,3 +144,61 @@ def test_claims_with_uuid_field(self):
         encoded_text = jwt.encode({"alg": "HS256"}, claims, key, encoder_cls=UUIDEncoder)
         token = jwt.decode(encoded_text, key)
         self.assertEqual(token.claims, {"uuid": str(value)})
+
+    def test_validate_list_inclusion(self):
+        # Case 1: use option value
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"essential": True, "value": "a"})
+        self.assertRaises(MissingClaimError, claims_requests.validate, {"iss": "a"})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": "b"})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": ["b"]})
+        claims_requests.validate({"custom_claim": "a"})
+        claims_requests.validate({"custom_claim": ["a"]})
+
+        # Case 2: use option values
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"essential": True, "values": ["a", "b"]})
+        self.assertRaises(MissingClaimError, claims_requests.validate, {"iss": "a"})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": "c"})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": ["c"]})
+        claims_requests.validate({"custom_claim": "a"})
+        claims_requests.validate({"custom_claim": "b"})
+        claims_requests.validate({"custom_claim": ["a"]})
+        claims_requests.validate({"custom_claim": ["b"]})
+        claims_requests.validate({"custom_claim": ["a", "b"]})
+        claims_requests.validate({"custom_claim": ["c", "a"]})
+
+        # Case 3: do not validate
+        claims_requests = jwt.JWTClaimsRegistry()
+        claims_requests.validate({"custom_claim": "a"})
+
+        # Case 4: essential claim without value(s)
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"essential": True})
+        claims_requests.validate({"custom_claim": "a"})
+
+    def test_validate_allow_blank(self):
+        # Case 1: allow blank value
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"essential": True, "allow_blank": True})
+        self.assertRaises(MissingClaimError, claims_requests.validate, {"custom_claim": None})
+        claims_requests.validate({"custom_claim": ""})
+        claims_requests.validate({"custom_claim": []})
+        claims_requests.validate({"custom_claim": {}})
+        
+        # Case 2: allow blank value without essential
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"allow_blank": True})
+        claims_requests.validate({"custom_claim": None})
+        claims_requests.validate({"custom_claim": ""})
+        claims_requests.validate({"custom_claim": []})
+        claims_requests.validate({"custom_claim": {}})
+
+        # Case 3: do not allow blank value
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"essential": True, "allow_blank": False})
+        self.assertRaises(MissingClaimError, claims_requests.validate, {"custom_claim": None})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": ""})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": []})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": {}})
+
+        # Case 4: do not allow blank value without essential
+        claims_requests = jwt.JWTClaimsRegistry(custom_claim={"allow_blank": False})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": None})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": ""})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": []})
+        self.assertRaises(InvalidClaimError, claims_requests.validate, {"custom_claim": {}})