fix(typing): accept any Collection for algorithms, not just list

The `algorithms` argument is only ever tested with truthiness and the
`in` operator (it is stored verbatim as `self.allowed` on the JWS/JWE
registries), so a tuple, set, or frozenset works at runtime. Widen the
type hint from `list[str] | None` to `Collection[str] | None` across the
jwt/jws/jwe public APIs and the registry constructors, and add a
regression test covering list/tuple/set/frozenset.

Author: jonathangreen

src/joserfc/_rfc7515/registry.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 import warnings
 from typing import Any
+from collections.abc import Collection
 from enum import Enum
 from .model import JWSAlgModel
 from ..errors import (
@@ -56,7 +57,7 @@ class Strategy(Enum):
     def __init__(
         self,
         header_registry: HeaderRegistryDict | None = None,
-        algorithms: list[str] | None = None,
+        algorithms: Collection[str] | None = None,
         strict_check_header: bool = True,
     ):
         self.header_registry: HeaderRegistryDict = {}
@@ -173,7 +174,7 @@ def filter_algorithms(cls, key: Any, names: list[str] | None = None) -> list[JWS
 default_registry = JWSRegistry()
 
 
-def construct_registry(algorithms: list[str] | None = None) -> JWSRegistry:
+def construct_registry(algorithms: Collection[str] | None = None) -> JWSRegistry:
     if algorithms:
         registry = JWSRegistry(algorithms=algorithms)
     else:

src/joserfc/_rfc7516/registry.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 import warnings
 import typing as t
+from collections.abc import Collection
 from .models import JWEAlgModel, JWEEncModel, JWEZipModel
 from ..errors import (
     UnsupportedAlgorithmError,
@@ -66,7 +67,7 @@ class JWERegistry:
     def __init__(
         self,
         header_registry: HeaderRegistryDict | None = None,
-        algorithms: list[str] | None = None,
+        algorithms: Collection[str] | None = None,
         verify_all_recipients: bool = True,
         strict_check_header: bool = True,
     ):

src/joserfc/jwe.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 from typing import overload
+from collections.abc import Collection
 from ._rfc7516.types import (
     GeneralJSONSerialization,
     FlattenedJSONSerialization,
@@ -52,7 +53,7 @@ def encrypt_compact(
     protected: Header,
     plaintext: bytes | str,
     public_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> str:
@@ -68,7 +69,7 @@ def encrypt_compact(
     :param protected: protected header part of the JWE, in dict
     :param plaintext: the content (message) to be encrypted
     :param public_key: a public key used to encrypt the CEK
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWERegistry to use
     :param sender_key: only required when using ECDH-1PU
     :return: JWE Compact Serialization in bytes
@@ -95,7 +96,7 @@ def encrypt_compact(
 def decrypt_compact(
     value: bytes | str,
     private_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> CompactEncryption:
@@ -114,7 +115,7 @@ def decrypt_compact(
 
     :param value: a string (or bytes) of the JWE Compact Serialization
     :param private_key: a flexible private key to decrypt the serialization
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWERegistry to use
     :param sender_key: only required when using ECDH-1PU
     :return: object of the ``CompactEncryption``
@@ -140,7 +141,7 @@ def decrypt_compact(
 def encrypt_json(
     obj: GeneralJSONEncryption,
     public_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> GeneralJSONSerialization: ...
@@ -150,7 +151,7 @@ def encrypt_json(
 def encrypt_json(
     obj: FlattenedJSONEncryption,
     public_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> FlattenedJSONSerialization: ...
@@ -159,7 +160,7 @@ def encrypt_json(
 def encrypt_json(
     obj: GeneralJSONEncryption | FlattenedJSONEncryption,
     public_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> GeneralJSONSerialization | FlattenedJSONSerialization:
@@ -184,7 +185,7 @@ def encrypt_json(
 
     :param obj: an instance of ``GeneralJSONEncryption`` or ``FlattenedJSONEncryption``
     :param public_key: a public key used to encrypt the CEK
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWERegistry to use
     :param sender_key: only required when using ECDH-1PU
     :return: JWE JSON Serialization in dict
@@ -214,7 +215,7 @@ def encrypt_json(
 def decrypt_json(
     data: GeneralJSONSerialization | FlattenedJSONSerialization,
     private_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWERegistry | None = None,
     sender_key: ECKey | OKPKey | KeySet | None = None,
 ) -> GeneralJSONEncryption | FlattenedJSONEncryption:
@@ -223,7 +224,7 @@ def decrypt_json(
 
     :param data: JWE JSON Serialization in dict
     :param private_key: a flexible private key to decrypt the CEK
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWERegistry to use
     :param sender_key: only required when using ECDH-1PU
     :return: an instance of ``GeneralJSONEncryption`` or ``FlattenedJSONEncryption``

src/joserfc/jws.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 from typing import overload, Any
+from collections.abc import Collection
 from ._rfc7515.model import (
     JWSAlgModel,
     HeaderMember,
@@ -75,7 +76,7 @@ def serialize_compact(
     protected: Header,
     payload: bytes | str,
     private_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> str:
     """Generate a JWS Compact Serialization. The JWS Compact Serialization
@@ -91,7 +92,7 @@ def serialize_compact(
     :param protected: protected header part of the JWS, in dict
     :param payload: payload data of the JWS, in bytes
     :param private_key: a flexible private key to sign the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWSRegistry to use
     :return: JWS in str
     """
@@ -123,15 +124,15 @@ def serialize_compact(
 def validate_compact(
     obj: CompactSignature,
     public_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> bool:
     """Validate the JWS Compact Serialization with the given key.
     This method is usually used together with ``extract_compact``.
 
     :param obj: object of the JWS Compact Serialization
     :param public_key: a flexible public key to verify the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWSRegistry to use
     """
     if registry is None:
@@ -156,7 +157,7 @@ def validate_compact(
 def deserialize_compact(
     value: bytes | str,
     public_key: KeyFlexible | None,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
     payload: bytes | str | None = None,
 ) -> CompactSignature:
@@ -175,7 +176,7 @@ def deserialize_compact(
 
     :param value: a string (or bytes) of the JWS Compact Serialization
     :param public_key: a flexible public key to verify the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWSRegistry to use
     :param payload: optional payload, required with detached content
     :raises BadSignatureError: when signature verification fails
@@ -192,7 +193,7 @@ def serialize_json(
     members: list[HeaderDict],
     payload: bytes | str,
     private_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> GeneralJSONSerialization: ...
 
@@ -202,7 +203,7 @@ def serialize_json(
     members: HeaderDict,
     payload: bytes | str,
     private_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> FlattenedJSONSerialization: ...
 
@@ -211,7 +212,7 @@ def serialize_json(
     members: HeaderDict | list[HeaderDict],
     payload: bytes | str,
     private_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> GeneralJSONSerialization | FlattenedJSONSerialization:
     """Generate a JWS JSON Serialization (in dict). The JWS JSON Serialization
@@ -261,7 +262,7 @@ def find_key(obj: HeaderMember) -> Key:
 def deserialize_json(
     value: GeneralJSONSerialization,
     public_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> GeneralJSONSignature: ...
 
@@ -270,22 +271,22 @@ def deserialize_json(
 def deserialize_json(
     value: FlattenedJSONSerialization,
     public_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> FlattenedJSONSignature: ...
 
 
 def deserialize_json(
     value: GeneralJSONSerialization | FlattenedJSONSerialization,
     public_key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | None = None,
 ) -> GeneralJSONSignature | FlattenedJSONSignature:
     """Extract and validate the JWS (in string) with the given key.
 
     :param value: a dict of the JSON signature
     :param public_key: a flexible public key to verify the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a JWSRegistry to use
     :return: object of GeneralJSONSignature or FlattenedJSONSignature
     :raises BadSignatureError: when signature verification fails

src/joserfc/jwt.py

@@ -2,6 +2,7 @@
 import json
 from json import JSONEncoder, JSONDecoder
 from typing import Type
+from collections.abc import Collection
 from ._rfc7519.claims import (
     convert_claims,
     Claims,
@@ -58,7 +59,7 @@ def encode(
     header: Header,
     claims: Claims,
     key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | JWERegistry | None = None,
     encoder_cls: Type[JSONEncoder] | None = None,
     default_type: str | None = "JWT",
@@ -68,7 +69,7 @@ def encode(
     :param header: A dict of the JWT header
     :param claims: A dict of the JWT claims to be encoded
     :param key: key used to sign the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a ``JWSRegistry`` or ``JWERegistry`` to use
     :param encoder_cls: A JSONEncoder subclass to use
     :param default_type: default value of the ``typ`` header parameter
@@ -87,7 +88,7 @@ def encode(
 def decode(
     value: bytes | str,
     key: KeyFlexible,
-    algorithms: list[str] | None = None,
+    algorithms: Collection[str] | None = None,
     registry: JWSRegistry | JWERegistry | None = None,
     decoder_cls: Type[JSONDecoder] | None = None,
 ) -> Token:
@@ -96,7 +97,7 @@ def decode(
 
     :param value: text of the JWT
     :param key: key used to verify the signature
-    :param algorithms: a list of allowed algorithms
+    :param algorithms: a collection (list, tuple, or set) of allowed algorithms
     :param registry: a ``JWSRegistry`` or ``JWERegistry`` to use
     :param decoder_cls: A JSONDecoder subclass to use
     :raise BadSignatureError: when signature verification fails
@@ -119,15 +120,15 @@ def decode(
 
 
 def _decode_jwe(
-    value: bytes, key: KeyFlexible, algorithms: list[str] | None = None, registry: JWERegistry | None = None
+    value: bytes, key: KeyFlexible, algorithms: Collection[str] | None = None, registry: JWERegistry | None = None
 ) -> tuple[Header, bytes]:
     jwe_obj = decrypt_compact(value, key, algorithms, registry)
     assert jwe_obj.plaintext is not None
     return jwe_obj.headers(), jwe_obj.plaintext
 
 
 def _decode_jws(
-    value: bytes, key: KeyFlexible, algorithms: list[str] | None = None, registry: JWSRegistry | None = None
+    value: bytes, key: KeyFlexible, algorithms: Collection[str] | None = None, registry: JWSRegistry | None = None
 ) -> tuple[Header, bytes]:
     jws_obj = deserialize_compact(value, key, algorithms, registry)
     assert jws_obj.payload is not None

tests/jwt/test_jwt.py

@@ -5,6 +5,7 @@
     InvalidPayloadError,
     MissingClaimError,
     UnsupportedHeaderError,
+    UnsupportedAlgorithmError,
     DecodeError,
 )
 
@@ -94,6 +95,25 @@ def test_using_registry(self):
             registry=jws.JWSRegistry(),
         )
 
+    def test_algorithms_accepts_any_collection(self):
+        # ``algorithms`` only needs to support ``in`` and truthiness, so any
+        # collection works, not just a list.
+        data = jwt.encode({"alg": "HS256"}, {"sub": "a"}, self.oct_key)
+        for algorithms in (["HS256"], ("HS256",), {"HS256"}, frozenset({"HS256"})):
+            token = jwt.decode(data, self.oct_key, algorithms=algorithms)
+            self.assertEqual(token.claims["sub"], "a")
+
+    def test_algorithms_collection_rejects_disallowed(self):
+        data = jwt.encode({"alg": "HS256"}, {"sub": "a"}, self.oct_key)
+        # a disallowed algorithm is still rejected when given as a non-list
+        self.assertRaises(
+            UnsupportedAlgorithmError,
+            jwt.decode,
+            data,
+            self.oct_key,
+            ("HS384",),
+        )
+
     def test_with_embedded_jwk(self):
         value = (
             "eyJqd2siOnsiY3J2IjoiUC0yNTYiLCJ4IjoiVU05ZzVuS25aWFlvdldBbE"