fix: Self review

Author: KShivendu

supertokens_python/recipe/session/api/implementation.py

@@ -42,7 +42,6 @@ async def refresh_post(
     ) -> SessionContainer:
         return await refresh_session_in_request(
             api_options.request,
-            # api_options.response,
             user_context,
             api_options.config,
             api_options.recipe_implementation,
@@ -80,15 +79,13 @@ async def verify_session(
         if incoming_path.equals(refresh_token_path) and method == "post":
             return await refresh_session_in_request(
                 api_options.request,
-                # api_options.response,
                 user_context,
                 api_options.config,
                 api_options.recipe_implementation,
             )
 
-        return await get_session_from_request(  # FIXME:
+        return await get_session_from_request(
             api_options.request,
-            # api_options.response,
             api_options.config,
             api_options.recipe_implementation,
             user_context=user_context,

supertokens_python/recipe/session/api/signout.py

@@ -39,7 +39,6 @@ async def handle_signout_api(api_implementation: APIInterface, api_options: APIO
 
     session = await get_session_from_request(
         api_options.request,
-        # api_options.response,
         api_options.config,
         api_options.recipe_implementation,
         session_required=False,

supertokens_python/recipe/session/asyncio/__init__.py

@@ -28,14 +28,14 @@
     ClaimsValidationResult,
     JSONObject,
     GetClaimValueOkResult,
-    GetSessionUnauthorizedResponse,
-    GetSessionTryRefreshTokenErrorResponse,
-    GetSessionClaimValidationErrorResponse,
+    GetSessionUnauthorizedErrorResult,
+    GetSessionTryRefreshTokenErrorResult,
+    GetSessionClaimValidationErrorResult,
     CreateNewSessionResult,
-    GetSessionOkResponse,
-    RefreshSessionOkResponse,
-    RefreshSessionUnauthorizedResponse,
-    RefreshSessionTokenTheftErrorResponse,
+    GetSessionOkResult,
+    RefreshSessionOkResult,
+    RefreshSessionUnauthorizedResult,
+    RefreshSessionTokenTheftErrorResult,
 )
 from supertokens_python.recipe.session.recipe import SessionRecipe
 from supertokens_python.recipe.session.session_request_functions import (
@@ -57,8 +57,7 @@
 
 
 async def create_new_session(
-    request: BaseRequest,
-    # response: BaseResponse,
+    request: Any,
     user_id: str,
     access_token_payload: Union[Dict[str, Any], None] = None,
     session_data_in_database: Union[Dict[str, Any], None] = None,
@@ -77,7 +76,6 @@ async def create_new_session(
 
     return await create_new_session_in_request(
         request,
-        # response,
         user_context,
         recipe_instance,
         access_token_payload,
@@ -280,7 +278,6 @@ async def remove_claim(
 
 async def get_session(
     request: BaseRequest,
-    # response: BaseResponse,
     session_required: Optional[bool] = None,
     anti_csrf_check: Optional[bool] = None,
     check_database: Optional[bool] = None,
@@ -301,7 +298,6 @@ async def get_session(
 
     return await get_session_from_request(
         request,
-        # response,
         config,
         recipe_interface_impl,
         session_required=session_required,
@@ -312,7 +308,6 @@ async def get_session(
     )
 
 
-# TODO: Add comments
 async def get_session_without_request_response(
     access_token: str,
     anti_csrf_token: Optional[str] = None,
@@ -326,11 +321,35 @@ async def get_session_without_request_response(
     ] = None,
     user_context: Union[None, Dict[str, Any]] = None,
 ) -> Union[
-    GetSessionOkResponse,
-    GetSessionUnauthorizedResponse,
-    GetSessionTryRefreshTokenErrorResponse,
-    GetSessionClaimValidationErrorResponse,
+    GetSessionOkResult,
+    GetSessionUnauthorizedErrorResult,
+    GetSessionTryRefreshTokenErrorResult,
+    GetSessionClaimValidationErrorResult,
 ]:
+    """Tries to validate an access token and build a Session object from it.
+
+    Notes about anti-csrf checking:
+    - if the `antiCsrf` is set to VIA_HEADER in the Session recipe config you have to handle anti-csrf checking before calling this function and set antiCsrfCheck to false in the options.
+    - you can disable anti-csrf checks by setting antiCsrf to NONE in the Session recipe config. We only recommend this if you are always getting the access-token from the Authorization header.
+    - if the antiCsrf check fails the returned status will be TRY_REFRESH_TOKEN_ERROR
+
+    args:
+    - access_token: The access token extracted from the authorization header or cookies
+    - anti_csrf_token: The anti-csrf token extracted from the authorization header or cookies. Can be undefined if antiCsrfCheck is false
+    - anti_csrf_check: If true, anti-csrf checking will be done. If false, it will be skipped. Defaults behaviour to check.
+    - check_database: If true, the session will be checked in the database. If false, it will be skipped. Defaults behaviour to skip.
+    - override_global_claim_validators: Alter the
+    - user_context: user context
+
+    Returned values:
+    - GetSessionOkResult: The session was successfully validated, including claim validation
+    - GetSessionClaimValidationErrorResult: While the access token is valid, one or more claim validators have failed. Our frontend SDKs expect a 403 response the contents matching the value returned from this function.
+    - GetSessionTryRefreshTokenErrorResult: This means, that the access token structure was valid, but it didn't pass validation for some reason and the user should call the refresh API.
+    - You can send a 401 response to trigger this behaviour if you are using our frontend SDKs
+    - GetSessionUnauthorizedErrorResult: This means that the access token likely doesn't belong to a SuperTokens session. If this is unexpected, it's best handled by sending a 401 response.
+    """
+
+
     if user_context is None:
         user_context = {}
 
@@ -345,23 +364,22 @@ async def get_session_without_request_response(
         user_context,
     )
 
-    if isinstance(res, GetSessionOkResponse):
+    if isinstance(res, GetSessionOkResult):
         claim_validators = await get_required_claim_validators(
             res.session, override_global_claim_validators, user_context
         )
         try:
             await res.session.assert_claims(claim_validators, user_context)
         except SuperTokensError as e:
             if isinstance(e, InvalidClaimsError):
-                return GetSessionClaimValidationErrorResponse(e)  # FIXME
+                return GetSessionClaimValidationErrorResult(e)  # FIXME: is this correct?
             raise e
 
     return res
 
 
 async def refresh_session(
     request: Any,
-    # response: BaseResponse,
     user_context: Union[None, Dict[str, Any]] = None,
 ) -> SessionContainer:
     if user_context is None:
@@ -372,15 +390,12 @@ async def refresh_session(
             SessionRecipe.get_instance().app_info.framework
         ].wrap_request(request)
 
-    # TODO: wrap response if required
-
     recipe_instance = SessionRecipe.get_instance()
     config = recipe_instance.config
     recipe_interface_impl = recipe_instance.recipe_implementation
 
     return await refresh_session_in_request(
         request,
-        # response,
         user_context,
         config,
         recipe_interface_impl,
@@ -393,9 +408,9 @@ async def refresh_session_without_request_response(
     anti_csrf_token: Optional[str] = None,
     user_context: Optional[Dict[str, Any]] = None,
 ) -> Union[
-    RefreshSessionOkResponse,
-    RefreshSessionUnauthorizedResponse,
-    RefreshSessionTokenTheftErrorResponse,
+    RefreshSessionOkResult,
+    RefreshSessionUnauthorizedResult,
+    RefreshSessionTokenTheftErrorResult,
 ]:
     if user_context is None:
         user_context = {}

supertokens_python/recipe/session/cookie_and_header.py

@@ -321,14 +321,14 @@ def access_token_mutator(
     def mutator(
         response: BaseResponse,
     ):
-        set_access_token_in_response(
+        _set_access_token_in_response(
             response, access_token, front_token, config, transfer_method
         )
 
     return mutator
 
 
-def set_access_token_in_response(
+def _set_access_token_in_response(
     res: BaseResponse,
     access_token: str,
     front_token: str,
@@ -361,10 +361,3 @@ def set_access_token_in_response(
             get_timestamp_ms() + HUNDRED_YEARS_IN_MS,
             "header",
         )
-
-
-def set_anti_csrf_token_in_header(res: BaseResponse, anti_csrf_token: str):
-    set_header(res, ANTI_CSRF_HEADER_KEY, anti_csrf_token, allow_duplicate=False)
-    set_header(
-        res, ACCESS_CONTROL_EXPOSE_HEADERS, ANTI_CSRF_HEADER_KEY, allow_duplicate=True
-    )

supertokens_python/recipe/session/interfaces.py

@@ -30,7 +30,8 @@
 from supertokens_python.types import APIResponse, GeneralErrorResponse, MaybeAwaitable
 
 from ...utils import resolve
-from .exceptions import ClaimValidationError, UnauthorisedError, TokenTheftError
+from .exceptions import ClaimValidationError, UnauthorisedError, TokenTheftError, TryRefreshTokenError, \
+    InvalidClaimsError
 from .utils import SessionConfig, TokenTransferMethod
 
 if TYPE_CHECKING:
@@ -77,101 +78,63 @@ def __init__(
         self.time_created: int = time_created
 
 
-# class GetSessionOptions:
-#     def __init__(
-#         self,
-#         anti_csrf_check: Optional[bool] = None,
-#         check_database: Optional[bool] = None,
-#         override_global_claim_validators: Optional[
-#             Callable[
-#                 [List[SessionClaimValidator], SessionContainer, Dict[str, Any]],
-#                 MaybeAwaitable[List[SessionClaimValidator]],
-#             ]
-#         ] = None,
-#     ):
-#         self.anti_csrf_check = anti_csrf_check
-#         self.check_database = check_database
-#         self.override_global_claim_validators = override_global_claim_validators
-#
-
-
 class ReqResInfo:
     def __init__(self, request: BaseRequest, transfer_method: TokenTransferMethod):
         self.request = request
         self.transfer_method = transfer_method
 
         self.response_mutators = []  # TODO: Use this everywhere!
 
-
-class VerifySessionOptions:
-    def __init__(
-        self,
-        session_required: Optional[bool] = None,
-        anti_csrf_check: Optional[bool] = None,
-        check_database: Optional[bool] = None,
-        override_global_claim_validators: Optional[
-            Callable[
-                [List[SessionClaimValidator], SessionContainer, Dict[str, Any]],
-                MaybeAwaitable[List[SessionClaimValidator]],
-            ]
-        ] = None,
-    ):
-        self.session_required = session_required
-        self.anti_csrf_check = anti_csrf_check
-        self.check_database = check_database
-        self.override_global_claim_validators = override_global_claim_validators
-
-
 class CreateNewSessionResult:
     status = "OK"
 
     def __init__(self, session: SessionContainer):
         self.session = session
 
 
-class GetSessionOkResponse:
+class GetSessionOkResult:
     status = "OK"
 
     def __init__(self, session: SessionContainer):
         self.session = session
 
 
-class GetSessionUnauthorizedResponse:
+class GetSessionUnauthorizedErrorResult:
     status = "UNAUTHORISED"
 
-    def __init__(self, error: Exception):
+    def __init__(self, error: UnauthorisedError):
         self.error = error
 
 
-class GetSessionTryRefreshTokenErrorResponse:
+class GetSessionTryRefreshTokenErrorResult:
     status = "TRY_REFRESH_TOKEN_ERROR"
 
-    def __init__(self, error: Exception):
+    def __init__(self, error: TryRefreshTokenError):
         self.error = error
 
 
-class GetSessionClaimValidationErrorResponse:
+class GetSessionClaimValidationErrorResult:
     status = "CLAIM_VALIDATION_ERROR"
 
-    def __init__(self, error: Exception):
+    def __init__(self, error: InvalidClaimsError):
         self.error = error
 
 
-class RefreshSessionOkResponse:
+class RefreshSessionOkResult:
     status = "OK"
 
     def __init__(self, session: SessionContainer):
         self.session = session
 
 
-class RefreshSessionUnauthorizedResponse:
+class RefreshSessionUnauthorizedResult:
     status = "UNAUTHORISED"
 
     def __init__(self, error: UnauthorisedError):
         self.error = error
 
 
-class RefreshSessionTokenTheftErrorResponse:
+class RefreshSessionTokenTheftErrorResult:
     status = "TOKEN_THEFT_ERROR"
 
     def __init__(self, error: TokenTheftError):
@@ -245,9 +208,9 @@ async def get_session(
         ] = None,
         user_context: Optional[Dict[str, Any]] = None,
     ) -> Union[
-        GetSessionOkResponse,
-        GetSessionUnauthorizedResponse,
-        GetSessionTryRefreshTokenErrorResponse,
+        GetSessionOkResult,
+        GetSessionUnauthorizedErrorResult,
+        GetSessionTryRefreshTokenErrorResult,
     ]:
         pass
 
@@ -279,9 +242,9 @@ async def refresh_session(
         disable_anti_csrf: bool,
         user_context: Dict[str, Any],
     ) -> Union[
-        RefreshSessionOkResponse,
-        RefreshSessionUnauthorizedResponse,
-        RefreshSessionTokenTheftErrorResponse,
+        RefreshSessionOkResult,
+        RefreshSessionUnauthorizedResult,
+        RefreshSessionTokenTheftErrorResult,
     ]:
         pass