Module supertokens_python.recipe.session.recipe

Classes

class SessionRecipe (recipe_id: str, app_info: AppInfo, cookie_domain: Union[str, None] = None, cookie_secure: Union[bool, None] = None, cookie_same_site: "Union[Literal['lax', 'none', 'strict'], None]" = None, session_expired_status_code: Union[int, None] = None, anti_csrf: "Union[Literal['VIA_TOKEN', 'VIA_CUSTOM_HEADER', 'NONE'], None]" = None, get_token_transfer_method: "Union[Callable[[BaseRequest, bool, Dict[str, Any]], Union[TokenTransferMethod, Literal['any']]], None]" = None, error_handlers: Union[InputErrorHandlers, None] = None, override: Union[InputOverrideConfig, None] = None, jwt: Union[JWTConfig, None] = None, invalid_claim_status_code: Union[int, None] = None)

Helper class that provides a standard way to create an ABC using inheritance.

Expand source code

class SessionRecipe(RecipeModule):
    recipe_id = "session"
    __instance = None

    def __init__(
        self,
        recipe_id: str,
        app_info: AppInfo,
        cookie_domain: Union[str, None] = None,
        cookie_secure: Union[bool, None] = None,
        cookie_same_site: Union[Literal["lax", "none", "strict"], None] = None,
        session_expired_status_code: Union[int, None] = None,
        anti_csrf: Union[
            Literal["VIA_TOKEN", "VIA_CUSTOM_HEADER", "NONE"], None
        ] = None,
        get_token_transfer_method: Union[
            Callable[
                [BaseRequest, bool, Dict[str, Any]],
                Union[TokenTransferMethod, Literal["any"]],
            ],
            None,
        ] = None,
        error_handlers: Union[InputErrorHandlers, None] = None,
        override: Union[InputOverrideConfig, None] = None,
        jwt: Union[JWTConfig, None] = None,
        invalid_claim_status_code: Union[int, None] = None,
    ):
        super().__init__(recipe_id, app_info)
        self.openid_recipe: Union[None, OpenIdRecipe] = None
        self.config = validate_and_normalise_user_input(
            app_info,
            cookie_domain,
            cookie_secure,
            cookie_same_site,
            session_expired_status_code,
            anti_csrf,
            get_token_transfer_method,
            error_handlers,
            override,
            jwt,
            invalid_claim_status_code,
        )
        log_debug_message("session init: anti_csrf: %s", self.config.anti_csrf)
        if self.config.cookie_domain is not None:
            log_debug_message(
                "session init: cookie_domain: %s", self.config.cookie_domain
            )
        else:
            log_debug_message("session init: cookie_domain: None")
        log_debug_message(
            "session init: cookie_same_site: %s", self.config.cookie_same_site
        )
        log_debug_message(
            "session init: cookie_secure: %s", str(self.config.cookie_secure)
        )
        log_debug_message(
            "session init: refresh_token_path: %s ",
            self.config.refresh_token_path.get_as_string_dangerous(),
        )
        log_debug_message(
            "session init: session_expired_status_code: %s",
            str(self.config.session_expired_status_code),
        )

        if self.config.jwt.enable:
            openid_feature_override = None
            if override is not None:
                openid_feature_override = override.openid_feature
            self.openid_recipe = OpenIdRecipe(
                recipe_id,
                app_info,
                None,
                self.config.jwt.issuer,
                openid_feature_override,
            )
            recipe_implementation = RecipeImplementation(
                Querier.get_instance(recipe_id), self.config, self.app_info
            )
            recipe_implementation = get_recipe_implementation_with_jwt(
                recipe_implementation,
                self.config,
                self.openid_recipe.recipe_implementation,
            )
        else:
            recipe_implementation = RecipeImplementation(
                Querier.get_instance(recipe_id), self.config, self.app_info
            )
        self.recipe_implementation: RecipeInterface = (
            recipe_implementation
            if self.config.override.functions is None
            else self.config.override.functions(recipe_implementation)
        )
        api_implementation = APIImplementation()
        self.api_implementation: APIInterface = (
            api_implementation
            if self.config.override.apis is None
            else self.config.override.apis(api_implementation)
        )

        self.claims_added_by_other_recipes: List[SessionClaim[Any]] = []
        self.claim_validators_added_by_other_recipes: List[SessionClaimValidator] = []

    def is_error_from_this_recipe_based_on_instance(self, err: Exception) -> bool:
        return isinstance(err, SuperTokensError) and (
            isinstance(err, SuperTokensSessionError)
            or (
                self.openid_recipe is not None
                and self.openid_recipe.is_error_from_this_recipe_based_on_instance(err)
            )
        )

    def get_apis_handled(self) -> List[APIHandled]:
        apis_handled = [
            APIHandled(
                NormalisedURLPath(SESSION_REFRESH),
                "post",
                SESSION_REFRESH,
                self.api_implementation.disable_refresh_post,
            ),
            APIHandled(
                NormalisedURLPath(SIGNOUT),
                "post",
                SIGNOUT,
                self.api_implementation.disable_signout_post,
            ),
        ]
        if self.openid_recipe is not None:
            apis_handled = apis_handled + self.openid_recipe.get_apis_handled()

        return apis_handled

    async def handle_api_request(
        self,
        request_id: str,
        request: BaseRequest,
        path: NormalisedURLPath,
        method: str,
        response: BaseResponse,
    ) -> Union[BaseResponse, None]:
        if request_id == SESSION_REFRESH:
            return await handle_refresh_api(
                self.api_implementation,
                APIOptions(
                    request,
                    response,
                    self.recipe_id,
                    self.config,
                    self.recipe_implementation,
                ),
            )
        if request_id == SIGNOUT:
            return await handle_signout_api(
                self.api_implementation,
                APIOptions(
                    request,
                    response,
                    self.recipe_id,
                    self.config,
                    self.recipe_implementation,
                ),
            )
        if self.openid_recipe is not None:
            return await self.openid_recipe.handle_api_request(
                request_id, request, path, method, response
            )
        return None

    async def handle_error(
        self, request: BaseRequest, err: SuperTokensError, response: BaseResponse
    ) -> BaseResponse:
        if isinstance(err, SuperTokensSessionError):
            for mutator in err.response_mutators:
                mutator(response)

        if isinstance(err, UnauthorisedError):
            log_debug_message("errorHandler: returning UNAUTHORISED")
            return await self.config.error_handlers.on_unauthorised(
                self, err.clear_tokens, request, str(err), response
            )
        if isinstance(err, TokenTheftError):
            log_debug_message("errorHandler: returning TOKEN_THEFT_DETECTED")
            return await self.config.error_handlers.on_token_theft_detected(
                self, request, err.session_handle, err.user_id, response
            )
        if isinstance(err, InvalidClaimsError):
            log_debug_message("errorHandler: returning INVALID_CLAIMS")
            return await self.config.error_handlers.on_invalid_claim(
                self, request, err.payload, response
            )

        log_debug_message("errorHandler: returning TRY_REFRESH_TOKEN")
        return await self.config.error_handlers.on_try_refresh_token(
            request, str(err), response
        )

    def get_all_cors_headers(self) -> List[str]:
        cors_headers = get_cors_allowed_headers()
        if self.openid_recipe is not None:
            cors_headers = cors_headers + self.openid_recipe.get_all_cors_headers()

        return cors_headers

    @staticmethod
    def init(
        cookie_domain: Union[str, None] = None,
        cookie_secure: Union[bool, None] = None,
        cookie_same_site: Union[Literal["lax", "none", "strict"], None] = None,
        session_expired_status_code: Union[int, None] = None,
        anti_csrf: Union[
            Literal["VIA_TOKEN", "VIA_CUSTOM_HEADER", "NONE"], None
        ] = None,
        get_token_transfer_method: Union[
            Callable[
                [BaseRequest, bool, Dict[str, Any]],
                Union[TokenTransferMethod, Literal["any"]],
            ],
            None,
        ] = None,
        error_handlers: Union[InputErrorHandlers, None] = None,
        override: Union[InputOverrideConfig, None] = None,
        jwt: Union[JWTConfig, None] = None,
        invalid_claim_status_code: Union[int, None] = None,
    ):
        def func(app_info: AppInfo):
            if SessionRecipe.__instance is None:
                SessionRecipe.__instance = SessionRecipe(
                    SessionRecipe.recipe_id,
                    app_info,
                    cookie_domain,
                    cookie_secure,
                    cookie_same_site,
                    session_expired_status_code,
                    anti_csrf,
                    get_token_transfer_method,
                    error_handlers,
                    override,
                    jwt,
                    invalid_claim_status_code,
                )
                return SessionRecipe.__instance
            raise_general_exception(
                "Session recipe has already been initialised. Please check your code for bugs."
            )

        return func

    @staticmethod
    def get_instance() -> SessionRecipe:
        if SessionRecipe.__instance is not None:
            return SessionRecipe.__instance
        raise_general_exception(
            "Initialisation not done. Did you forget to call the SuperTokens.init function?"
        )

    @staticmethod
    def reset():
        if ("SUPERTOKENS_ENV" not in environ) or (
            environ["SUPERTOKENS_ENV"] != "testing"
        ):
            raise_general_exception("calling testing function in non testing env")
        SessionRecipe.__instance = None

    def add_claim_from_other_recipe(self, claim: SessionClaim[Any]):
        # We are throwing here (and not in addClaimValidatorFromOtherRecipe) because if multiple
        # claims are added with the same key they will overwrite each other. Validators will all run
        # and work as expected even if they are added multiple times.
        if claim.key in [c.key for c in self.claims_added_by_other_recipes]:
            raise Exception("Claim added by multiple recipes")

        self.claims_added_by_other_recipes.append(claim)

    def get_claims_added_by_other_recipes(self) -> List[SessionClaim[Any]]:
        return self.claims_added_by_other_recipes

    def add_claim_validator_from_other_recipe(
        self, claim_validator: SessionClaimValidator
    ):
        self.claim_validators_added_by_other_recipes.append(claim_validator)

    def get_claim_validators_added_by_other_recipes(
        self,
    ) -> List[SessionClaimValidator]:
        return self.claim_validators_added_by_other_recipes

    async def verify_session(
        self,
        request: BaseRequest,
        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],
    ):
        _ = user_context

        return await self.api_implementation.verify_session(
            APIOptions(
                request,
                None,
                self.recipe_id,
                self.config,
                self.recipe_implementation,
            ),
            anti_csrf_check,
            session_required,
            override_global_claim_validators,
            user_context=default_user_context(request),
        )

Ancestors

• RecipeModule
• abc.ABC

Class variables

var recipe_id

Static methods

def get_instance() ‑> SessionRecipe

Expand source code

@staticmethod
def get_instance() -> SessionRecipe:
    if SessionRecipe.__instance is not None:
        return SessionRecipe.__instance
    raise_general_exception(
        "Initialisation not done. Did you forget to call the SuperTokens.init function?"
    )

def init(cookie_domain: Union[str, None] = None, cookie_secure: Union[bool, None] = None, cookie_same_site: "Union[Literal['lax', 'none', 'strict'], None]" = None, session_expired_status_code: Union[int, None] = None, anti_csrf: "Union[Literal['VIA_TOKEN', 'VIA_CUSTOM_HEADER', 'NONE'], None]" = None, get_token_transfer_method: "Union[Callable[[BaseRequest, bool, Dict[str, Any]], Union[TokenTransferMethod, Literal['any']]], None]" = None, error_handlers: Union[InputErrorHandlers, None] = None, override: Union[InputOverrideConfig, None] = None, jwt: Union[JWTConfig, None] = None, invalid_claim_status_code: Union[int, None] = None)

Expand source code

@staticmethod
def init(
    cookie_domain: Union[str, None] = None,
    cookie_secure: Union[bool, None] = None,
    cookie_same_site: Union[Literal["lax", "none", "strict"], None] = None,
    session_expired_status_code: Union[int, None] = None,
    anti_csrf: Union[
        Literal["VIA_TOKEN", "VIA_CUSTOM_HEADER", "NONE"], None
    ] = None,
    get_token_transfer_method: Union[
        Callable[
            [BaseRequest, bool, Dict[str, Any]],
            Union[TokenTransferMethod, Literal["any"]],
        ],
        None,
    ] = None,
    error_handlers: Union[InputErrorHandlers, None] = None,
    override: Union[InputOverrideConfig, None] = None,
    jwt: Union[JWTConfig, None] = None,
    invalid_claim_status_code: Union[int, None] = None,
):
    def func(app_info: AppInfo):
        if SessionRecipe.__instance is None:
            SessionRecipe.__instance = SessionRecipe(
                SessionRecipe.recipe_id,
                app_info,
                cookie_domain,
                cookie_secure,
                cookie_same_site,
                session_expired_status_code,
                anti_csrf,
                get_token_transfer_method,
                error_handlers,
                override,
                jwt,
                invalid_claim_status_code,
            )
            return SessionRecipe.__instance
        raise_general_exception(
            "Session recipe has already been initialised. Please check your code for bugs."
        )

    return func

def reset()

Expand source code

@staticmethod
def reset():
    if ("SUPERTOKENS_ENV" not in environ) or (
        environ["SUPERTOKENS_ENV"] != "testing"
    ):
        raise_general_exception("calling testing function in non testing env")
    SessionRecipe.__instance = None

Methods

def add_claim_from_other_recipe(self, claim: SessionClaim[Any])

Expand source code

def add_claim_from_other_recipe(self, claim: SessionClaim[Any]):
    # We are throwing here (and not in addClaimValidatorFromOtherRecipe) because if multiple
    # claims are added with the same key they will overwrite each other. Validators will all run
    # and work as expected even if they are added multiple times.
    if claim.key in [c.key for c in self.claims_added_by_other_recipes]:
        raise Exception("Claim added by multiple recipes")

    self.claims_added_by_other_recipes.append(claim)

def add_claim_validator_from_other_recipe(self, claim_validator: SessionClaimValidator)

Expand source code

def add_claim_validator_from_other_recipe(
    self, claim_validator: SessionClaimValidator
):
    self.claim_validators_added_by_other_recipes.append(claim_validator)

def get_all_cors_headers(self) ‑> List[str]

Expand source code

def get_all_cors_headers(self) -> List[str]:
    cors_headers = get_cors_allowed_headers()
    if self.openid_recipe is not None:
        cors_headers = cors_headers + self.openid_recipe.get_all_cors_headers()

    return cors_headers

def get_apis_handled(self) ‑> List[APIHandled]

Expand source code

def get_apis_handled(self) -> List[APIHandled]:
    apis_handled = [
        APIHandled(
            NormalisedURLPath(SESSION_REFRESH),
            "post",
            SESSION_REFRESH,
            self.api_implementation.disable_refresh_post,
        ),
        APIHandled(
            NormalisedURLPath(SIGNOUT),
            "post",
            SIGNOUT,
            self.api_implementation.disable_signout_post,
        ),
    ]
    if self.openid_recipe is not None:
        apis_handled = apis_handled + self.openid_recipe.get_apis_handled()

    return apis_handled

def get_claim_validators_added_by_other_recipes(self) ‑> List[SessionClaimValidator]

Expand source code

def get_claim_validators_added_by_other_recipes(
    self,
) -> List[SessionClaimValidator]:
    return self.claim_validators_added_by_other_recipes

def get_claims_added_by_other_recipes(self) ‑> List[SessionClaim[Any]]

Expand source code

def get_claims_added_by_other_recipes(self) -> List[SessionClaim[Any]]:
    return self.claims_added_by_other_recipes

async def handle_api_request(self, request_id: str, request: BaseRequest, path: NormalisedURLPath, method: str, response: BaseResponse) ‑> Union[BaseResponse, None]

Expand source code

async def handle_api_request(
    self,
    request_id: str,
    request: BaseRequest,
    path: NormalisedURLPath,
    method: str,
    response: BaseResponse,
) -> Union[BaseResponse, None]:
    if request_id == SESSION_REFRESH:
        return await handle_refresh_api(
            self.api_implementation,
            APIOptions(
                request,
                response,
                self.recipe_id,
                self.config,
                self.recipe_implementation,
            ),
        )
    if request_id == SIGNOUT:
        return await handle_signout_api(
            self.api_implementation,
            APIOptions(
                request,
                response,
                self.recipe_id,
                self.config,
                self.recipe_implementation,
            ),
        )
    if self.openid_recipe is not None:
        return await self.openid_recipe.handle_api_request(
            request_id, request, path, method, response
        )
    return None

async def handle_error(self, request: BaseRequest, err: SuperTokensError, response: BaseResponse) ‑> BaseResponse

Expand source code

async def handle_error(
    self, request: BaseRequest, err: SuperTokensError, response: BaseResponse
) -> BaseResponse:
    if isinstance(err, SuperTokensSessionError):
        for mutator in err.response_mutators:
            mutator(response)

    if isinstance(err, UnauthorisedError):
        log_debug_message("errorHandler: returning UNAUTHORISED")
        return await self.config.error_handlers.on_unauthorised(
            self, err.clear_tokens, request, str(err), response
        )
    if isinstance(err, TokenTheftError):
        log_debug_message("errorHandler: returning TOKEN_THEFT_DETECTED")
        return await self.config.error_handlers.on_token_theft_detected(
            self, request, err.session_handle, err.user_id, response
        )
    if isinstance(err, InvalidClaimsError):
        log_debug_message("errorHandler: returning INVALID_CLAIMS")
        return await self.config.error_handlers.on_invalid_claim(
            self, request, err.payload, response
        )

    log_debug_message("errorHandler: returning TRY_REFRESH_TOKEN")
    return await self.config.error_handlers.on_try_refresh_token(
        request, str(err), response
    )

def is_error_from_this_recipe_based_on_instance(self, err: Exception) ‑> bool

Expand source code

def is_error_from_this_recipe_based_on_instance(self, err: Exception) -> bool:
    return isinstance(err, SuperTokensError) and (
        isinstance(err, SuperTokensSessionError)
        or (
            self.openid_recipe is not None
            and self.openid_recipe.is_error_from_this_recipe_based_on_instance(err)
        )
    )

async def verify_session(self, request: BaseRequest, 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])

Expand source code

async def verify_session(
    self,
    request: BaseRequest,
    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],
):
    _ = user_context

    return await self.api_implementation.verify_session(
        APIOptions(
            request,
            None,
            self.recipe_id,
            self.config,
            self.recipe_implementation,
        ),
        anti_csrf_check,
        session_required,
        override_global_claim_validators,
        user_context=default_user_context(request),
    )