feat: Add session claims feature

.github/workflows/tests.yml

@@ -51,5 +51,10 @@ jobs:
               run: cd ../supertokens-root && ./loadModules
             - name: Setting up supertokens-root test environment
               run: cd ../supertokens-root && bash ./utils/setupTestEnvLocal
+            - name: Debugging with tmate
+              if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+              uses: mxschmitt/[email protected]
+              with:
+                sudo: false
             - name: Run tests
-              run: make test
+              run: make test

supertokens_python/recipe/session/api/implementation.py

@@ -13,14 +13,17 @@
 # under the License.
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Union, List, Callable, Optional
 
 from supertokens_python.normalised_url_path import NormalisedURLPath
 from supertokens_python.recipe.session.interfaces import (
     APIInterface,
     SignOutOkayResponse,
+    SessionClaimValidator,
 )
+from supertokens_python.types import MaybeAwaitable
 from supertokens_python.utils import normalise_http_method
+from ..utils import get_required_claim_validators
 
 if TYPE_CHECKING:
     from supertokens_python.recipe.session.interfaces import APIOptions
@@ -48,6 +51,7 @@ async def signout_post(
                 user_context=user_context,
                 anti_csrf_check=None,
                 session_required=True,
+                override_global_claim_validators=lambda _, __, ___: [],
             )
         except UnauthorisedError:
             return SignOutOkayResponse()
@@ -62,6 +66,12 @@ async def verify_session(
         api_options: APIOptions,
         anti_csrf_check: Union[bool, None],
         session_required: bool,
+        override_global_claim_validators: Optional[
+            Callable[
+                [List[SessionClaimValidator], SessionContainer, Dict[str, Any]],
+                MaybeAwaitable[List[SessionClaimValidator]],
+            ]
+        ],
         user_context: Dict[str, Any],
     ) -> Union[SessionContainer, None]:
         method = normalise_http_method(api_options.request.method())
@@ -73,6 +83,24 @@ async def verify_session(
             return await api_options.recipe_implementation.refresh_session(
                 api_options.request, user_context
             )
-        return await api_options.recipe_implementation.get_session(
-            api_options.request, anti_csrf_check, session_required, user_context
+        session = await api_options.recipe_implementation.get_session(
+            api_options.request,
+            anti_csrf_check,
+            session_required,
+            override_global_claim_validators,
+            user_context,
         )
+
+        if session is not None:
+            claim_validators = await get_required_claim_validators(
+                session,
+                override_global_claim_validators,
+                user_context,
+            )
+            await api_options.recipe_implementation.assert_claims(
+                session,
+                claim_validators,
+                user_context,
+            )
+
+        return session

supertokens_python/recipe/session/asyncio/__init__.py

@@ -11,7 +11,7 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Union, TypeVar, Callable, Optional
 
 from supertokens_python.recipe.openid.interfaces import (
     GetOpenIdDiscoveryConfigurationResult,
@@ -20,16 +20,25 @@
     RegenerateAccessTokenOkResult,
     SessionContainer,
     SessionInformationResult,
+    SessionClaim,
+    SessionClaimValidator,
+    SessionDoesntExistError,
+    ValidateClaimsOkResult,
+    JSONObject,
+    GetClaimValueOkResult,
 )
 from supertokens_python.recipe.session.recipe import SessionRecipe
-from supertokens_python.utils import FRAMEWORKS
-
+from supertokens_python.types import MaybeAwaitable
+from supertokens_python.utils import FRAMEWORKS, resolve
+from ..utils import get_required_claim_validators
 from ...jwt.interfaces import (
     CreateJwtOkResult,
     CreateJwtResultUnsupportedAlgorithm,
     GetJWKSResult,
 )
 
+_T = TypeVar("_T")
+
 
 async def create_new_session(
     request: Any,
@@ -49,10 +58,160 @@ async def create_new_session(
     )
 
 
+async def validate_claims_for_session_handle(
+    session_handle: str,
+    override_global_claim_validators: Optional[
+        Callable[
+            [
+                List[SessionClaimValidator],
+                SessionInformationResult,
+                Dict[str, Any],
+            ],  # Prev. 2nd arg was SessionContainer
+            MaybeAwaitable[List[SessionClaimValidator]],
+        ]
+    ] = None,
+    user_context: Union[None, Dict[str, Any]] = None,
+) -> Union[SessionDoesntExistError, ValidateClaimsOkResult]:
+    if user_context is None:
+        user_context = {}
+
+    recipe_impl = SessionRecipe.get_instance().recipe_implementation
+    session_info = await recipe_impl.get_session_information(
+        session_handle, user_context
+    )
+
+    if session_info is None:
+        return SessionDoesntExistError()
+
+    claim_validators_added_by_other_recipes = (
+        SessionRecipe.get_claim_validators_added_by_other_recipes()
+    )
+    global_claim_validators = await resolve(
+        recipe_impl.get_global_claim_validators(
+            session_info.user_id,
+            claim_validators_added_by_other_recipes,
+            user_context,
+        )
+    )
+
+    if override_global_claim_validators is not None:
+        claim_validators = await resolve(
+            override_global_claim_validators(
+                global_claim_validators, session_info, user_context
+            )
+        )
+    else:
+        claim_validators = global_claim_validators
+
+    return await recipe_impl.validate_claims_for_session_handle(
+        session_info, claim_validators, user_context
+    )
+
+
+async def validate_claims_in_jwt_payload(
+    user_id: str,
+    jwt_payload: JSONObject,
+    override_global_claim_validators: Optional[
+        Callable[
+            [
+                List[SessionClaimValidator],
+                str,
+                Dict[str, Any],
+            ],  # Prev. 2nd arg was SessionContainer
+            MaybeAwaitable[List[SessionClaimValidator]],
+        ]
+    ] = None,
+    user_context: Union[None, Dict[str, Any]] = None,
+):
+    if user_context is None:
+        user_context = {}
+
+    recipe_impl = SessionRecipe.get_instance().recipe_implementation
+
+    claim_validators_added_by_other_recipes = (
+        SessionRecipe.get_claim_validators_added_by_other_recipes()
+    )
+    global_claim_validators = await resolve(
+        recipe_impl.get_global_claim_validators(
+            user_id,
+            claim_validators_added_by_other_recipes,
+            user_context,
+        )
+    )
+
+    if override_global_claim_validators is not None:
+        claim_validators = await resolve(
+            override_global_claim_validators(
+                global_claim_validators, user_id, user_context
+            )
+        )
+    else:
+        claim_validators = global_claim_validators
+
+    return await recipe_impl.validate_claims_in_jwt_payload(
+        user_id, jwt_payload, claim_validators, user_context
+    )
+
+
+async def fetch_and_set_claim(
+    session_handle: str,
+    claim: SessionClaim[Any],
+    user_context: Union[None, Dict[str, Any]] = None,
+) -> bool:
+    if user_context is None:
+        user_context = {}
+    return await SessionRecipe.get_instance().recipe_implementation.fetch_and_set_claim(
+        session_handle, claim, user_context
+    )
+
+
+async def get_claim_value(
+    session_handle: str,
+    claim: SessionClaim[_T],
+    user_context: Union[None, Dict[str, Any]] = None,
+) -> Union[SessionDoesntExistError, GetClaimValueOkResult[_T]]:
+    if user_context is None:
+        user_context = {}
+    return await SessionRecipe.get_instance().recipe_implementation.get_claim_value(
+        session_handle, claim, user_context
+    )
+
+
+async def set_claim_value(
+    session_handle: str,
+    claim: SessionClaim[_T],
+    value: _T,
+    user_context: Union[None, Dict[str, Any]] = None,
+) -> bool:
+    if user_context is None:
+        user_context = {}
+    return await SessionRecipe.get_instance().recipe_implementation.set_claim_value(
+        session_handle, claim, value, user_context
+    )
+
+
+async def remove_claim(
+    session_handle: str,
+    claim: SessionClaim[Any],
+    user_context: Union[None, Dict[str, Any]] = None,
+) -> bool:
+    if user_context is None:
+        user_context = {}
+    return await SessionRecipe.get_instance().recipe_implementation.remove_claim(
+        session_handle, claim, user_context
+    )
+
+
 async def get_session(
     request: Any,
     anti_csrf_check: Union[bool, None] = None,
     session_required: bool = True,
+    override_global_claim_validators: Optional[
+        Callable[
+            [List[SessionClaimValidator], SessionContainer, Dict[str, Any]],
+            MaybeAwaitable[List[SessionClaimValidator]],
+        ]
+    ] = None,
     user_context: Union[None, Dict[str, Any]] = None,
 ) -> Union[SessionContainer, None]:
     if user_context is None:
@@ -61,10 +220,24 @@ async def get_session(
         request = FRAMEWORKS[
             SessionRecipe.get_instance().app_info.framework
         ].wrap_request(request)
-    return await SessionRecipe.get_instance().recipe_implementation.get_session(
-        request, anti_csrf_check, session_required, user_context
+
+    session_recipe_impl = SessionRecipe.get_instance().recipe_implementation
+    session = await session_recipe_impl.get_session(
+        request,
+        anti_csrf_check,
+        session_required,
+        override_global_claim_validators,
+        user_context,
     )
 
+    if session is not None:
+        claim_validators = await get_required_claim_validators(
+            session, override_global_claim_validators, user_context
+        )
+        await session_recipe_impl.assert_claims(session, claim_validators, user_context)
+
+    return session
+
 
 async def refresh_session(
     request: Any, user_context: Union[None, Dict[str, Any]] = None

supertokens_python/recipe/session/claim_base_classes/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2021, VRAI Labs and/or its affiliates. All rights reserved.
+#
+# This software is licensed under the Apache License, Version 2.0 (the
+# "License") as published by the Apache Software Foundation.
+#
+# You may not use this file except in compliance with the License. You may
+# obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.

supertokens_python/recipe/session/claim_base_classes/boolean_claim.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2021, VRAI Labs and/or its affiliates. All rights reserved.
+#
+# This software is licensed under the Apache License, Version 2.0 (the
+# "License") as published by the Apache Software Foundation.
+#
+# You may not use this file except in compliance with the License. You may
+# obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from .primitive_claim import PrimitiveClaim
+
+
+class BooleanClaim(PrimitiveClaim):
+    pass