refactoring

Author: guillp

README.md

@@ -1149,6 +1149,92 @@ api = ApiClient("https://myapi.local/resource", session=session)
 assert api.session == session
 ```
 
+## Token and Authorization Requests serialization
+
+If you implement a web application, you will most likely need to serialize access tokens inside the user session.
+To make it easier, `requests_oauth2client` provides several classes that implement (de)serialization.
+
+```python
+from requests_oauth2client import BearerToken, TokenSerializer
+
+token_serializer = TokenSerializer()
+
+bearer_token = BearerToken("access_token", expires_in=60)  # here is a sample token
+serialized_value = token_serializer.dumps(bearer_token)
+print(serialized_value)
+# q1ZKTE5OLS6OL8nPTs1TskLl6iilVhRkFqUWxyeWKFkZmpsZWFiYmJqZ6iiB5eNLKgtSlayUnFITi1KLlGoB
+# you can store that string value in session or anywhere needed
+# beware, this is clear-text!
+
+# loading back the token to a BearerToken instance
+deserialized_token = token_serializer.loads(serialized_value)
+assert isinstance(deserialized_token, BearerToken)
+assert deserialized_token == bearer_token
+```
+
+Default `TokenSerializer` class supports both `BearerToken` and `DPoPToken` instances.
+
+```python
+from requests_oauth2client import AuthorizationRequest, AuthorizationRequestSerializer
+
+ar_serializer = AuthorizationRequestSerializer()
+
+auth_request = AuthorizationRequest(
+    authorization_endpoint="https://my.as.local/authorize",
+    client_id="my_client_id",
+    redirect_uri="http://localhost:8000/callback",
+)
+
+serialized_ar = ar_serializer.dumps(auth_request)
+assert ar_serializer.loads(serialized_ar) == auth_request
+```
+
+### Customizing token (de)serialization
+
+While provided serializers work well for standard tokens with default classes, you may need to override them for special
+purposes or if you are using custom token classes.
+To do that, you can pass custom methods as parameters when initializing your TokenSerializer instance:
+
+```python
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Mapping
+
+from requests_oauth2client import BearerToken, TokenSerializer
+
+
+class CustomToken(BearerToken):
+    TOKEN_TYPE = "CustomToken"
+
+
+def custom_make_instance(args: Mapping[str, Any]) -> BearerToken:
+    """This will add support for a custom token type."""
+    if args.get("token_type") == "CustomToken":
+        return CustomToken(**args)
+    return TokenSerializer.default_make_instance(args)
+
+
+def custom_dumper(token: CustomToken) -> bytes:
+    """This will serialize the token value to base64-encoded JSON"""
+    args = token.as_dict()
+    return base64.b64encode(json.dumps(args).encode())
+
+
+def custom_loader(serialized: bytes) -> dict[str, Any]:
+    """This will load from a base64-encoded JSON"""
+    return json.loads(base64.b64decode(serialized))
+
+
+token_serializer = TokenSerializer(make_instance=custom_make_instance, dumper=custom_dumper, loader=custom_loader)
+
+my_custom_token = CustomToken(**{"token_type": "CustomToken", "access_token": "..."})
+serialized = token_serializer.dumps(my_custom_token)
+assert serialized == b'eyJhY2Nlc3NfdG9rZW4iOiAiLi4uIiwgInRva2VuX3R5cGUiOiAiQ3VzdG9tVG9rZW4ifQ=='
+assert token_serializer.loads(serialized) == my_custom_token
+```
+
 ## Vendor-Specific clients
 
 `requests_oauth2client` is flexible enough to handle most use cases, so you should be able to use any AS by any vendor

pyproject.toml

@@ -42,13 +42,14 @@ dev = [
     "virtualenv>=20.30.0",
 ]
 doc = [
+    "griffe-fieldz>=0.3.0",
     "mkdocs>=1.3.1",
     "mkdocs-autorefs>=0.3.0",
     "mkdocs-include-markdown-plugin>=6",
     "mkdocs-material>=9.6.11",
     "mkdocs-material-extensions>=1.0.1",
     "mkdocstrings[python]>=0.29.1",
-    ]
+]
 test = [
     "coverage>=7.8.0",
     "pytest>=7.0.1",

requests_oauth2client/__init__.py

@@ -131,7 +131,7 @@
 from .polling import (
     BaseTokenEndpointPollingJob,
 )
-from .serializers import AuthorizationRequestSerializer, BearerTokenSerializer
+from .serializers import AuthorizationRequestSerializer, TokenSerializer
 from .tokens import (
     BearerToken,
     ExpiredAccessToken,
@@ -170,7 +170,6 @@
     "BaseTokenEndpointPollingJob",
     "BaseTokenEndpointPoolingJob",
     "BearerToken",
-    "BearerTokenSerializer",
     "ClientSecretBasic",
     "ClientSecretJwt",
     "ClientSecretPost",
@@ -263,6 +262,7 @@
     "SignatureAlgs",
     "SlowDown",
     "TokenEndpointError",
+    "TokenSerializer",
     "UnauthorizedClient",
     "UnknownActorTokenType",
     "UnknownIntrospectionError",

requests_oauth2client/deprecated.py

@@ -11,6 +11,7 @@
 from .backchannel_authentication import BackChannelAuthenticationPollingJob
 from .device_authorization import DeviceAuthorizationPollingJob
 from .polling import BaseTokenEndpointPollingJob
+from .serializers import TokenSerializer
 
 
 class _DeprecatedClassMeta(type):
@@ -77,8 +78,13 @@ class DeviceAuthorizationPoolingJob(metaclass=_DeprecatedClassMeta):
     _DeprecatedClassMeta__alias = DeviceAuthorizationPollingJob
 
 
+class BearerTokenSerializer(metaclass=_DeprecatedClassMeta):
+    _DeprecatedClassMeta__alias = TokenSerializer
+
+
 __all__ = [
     "BackChannelAuthenticationPoolingJob",
     "BaseTokenEndpointPoolingJob",
+    "BearerTokenSerializer",
     "DeviceAuthorizationPoolingJob",
 ]

requests_oauth2client/dpop.py

@@ -13,7 +13,7 @@
 from binapy import BinaPy
 from furl import furl  # type: ignore[import-untyped]
 from requests import codes
-from typing_extensions import Self
+from typing_extensions import Self, override
 
 from .enums import AccessTokenTypes
 from .tokens import BearerToken, IdToken, id_token_converter
@@ -150,13 +150,23 @@ def _response_hook(self, response: requests.Response, **kwargs: Any) -> requests
 
         return response
 
+    @override
     def __call__(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
         """Add a DPoP proof in each request."""
         request = super().__call__(request)
         add_dpop_proof(request, dpop_key=self.dpop_key, access_token=self.access_token, header_name=self.DPOP_HEADER)
         request.register_hook("response", self._response_hook)  # type: ignore[no-untyped-call]
         return request
 
+    @override
+    def as_dict(self, with_expires_in: bool = True) -> dict[str, Any]:
+        d = super().as_dict(with_expires_in=with_expires_in)
+        d["dpop_key"]["private_key"] = self.dpop_key.private_key.to_dict()
+        d["dpop_key"].pop("jti_generator", None)
+        d["dpop_key"].pop("iat_generator", None)
+        d["dpop_key"].pop("dpop_token_class", None)
+        return d
+
 
 def add_dpop_proof(
     request: requests.PreparedRequest,

requests_oauth2client/exceptions.py

@@ -264,3 +264,11 @@ class InvalidBackChannelAuthenticationResponse(OAuth2Error):
 
 class InvalidPushedAuthorizationResponse(OAuth2Error):
     """Raised when the Pushed Authorization Endpoint returns an error."""
+
+
+class UnsupportedTokenTypeError(ValueError):
+    """Raised when an unsupported token_type is provided."""
+
+    def __init__(self, token_type: str) -> None:
+        super().__init__(f"Unsupported token_type: {token_type}")
+        self.token_type = token_type

requests_oauth2client/flask/auth.py

@@ -6,7 +6,7 @@
 
 from flask import session
 
-from requests_oauth2client import BearerTokenSerializer
+from requests_oauth2client import TokenSerializer
 from requests_oauth2client.auth import OAuth2ClientCredentialsAuth
 from requests_oauth2client.tokens import BearerToken
 
@@ -27,11 +27,11 @@ class FlaskSessionAuthMixin:
     def __init__(
         self,
         session_key: str,
-        serializer: BearerTokenSerializer | None = None,
+        serializer: TokenSerializer | None = None,
         *args: Any,
         **token_kwargs: Any,
     ) -> None:
-        self.serializer = serializer or BearerTokenSerializer()
+        self.serializer = serializer or TokenSerializer()
         self.session_key = session_key
         super().__init__(*args, **token_kwargs)