Module supertokens_python.recipe.passwordless.utils

Expand source code 
# 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 __future__ import annotations

from abc import ABC
from re import fullmatch
from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Union

from phonenumbers import is_valid_number, parse
from typing_extensions import Literal

from supertokens_python.ingredients.emaildelivery.types import (
    EmailDeliveryConfig,
    EmailDeliveryConfigWithService,
)
from supertokens_python.ingredients.smsdelivery.types import (
    SMSDeliveryConfig,
    SMSDeliveryConfigWithService,
)
from supertokens_python.recipe.multifactorauth.types import FactorIds
from supertokens_python.recipe.passwordless.emaildelivery.services.backward_compatibility import (
    BackwardCompatibilityService,
)
from supertokens_python.recipe.passwordless.smsdelivery.services.backward_compatibility import (
    BackwardCompatibilityService as SMSBackwardCompatibilityService,
)
from supertokens_python.recipe.passwordless.types import (
    PasswordlessLoginSMSTemplateVars,
)
from supertokens_python.types.config import (
    BaseConfig,
    BaseNormalisedConfig,
    BaseNormalisedOverrideConfig,
    BaseOverrideableConfig,
    BaseOverrideConfig,
)

from .interfaces import (
    APIInterface,
    PasswordlessLoginEmailTemplateVars,
    RecipeInterface,
)

if TYPE_CHECKING:
    from supertokens_python import AppInfo


async def default_validate_phone_number(value: str, _tenant_id: str):
    try:
        parsed_phone_number: Any = parse(value, None)
        if not is_valid_number(parsed_phone_number):
            return "Phone number is invalid"
    except Exception:
        return "Phone number is invalid"


async def default_validate_email(value: str, _tenant_id: str):
    pattern = r"^(([^<>()\[\]\\.,;:\s@\"]+(\.[^<>()\[\]\\.,;:\s@\"]+)*)|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$"
    if fullmatch(pattern, value) is None:
        return "Email is invalid"


PasswordlessOverrideConfig = BaseOverrideConfig[RecipeInterface, APIInterface]
NormalisedPasswordlessOverrideConfig = BaseNormalisedOverrideConfig[
    RecipeInterface, APIInterface
]
InputOverrideConfig = PasswordlessOverrideConfig
"""Deprecated, use `PasswordlessOverrideConfig` instead."""


class ContactConfig(ABC):
    def __init__(self, contact_method: Literal["PHONE", "EMAIL", "EMAIL_OR_PHONE"]):
        self.contact_method = contact_method


class ContactPhoneOnlyConfig(ContactConfig):
    def __init__(
        self,
        validate_phone_number: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("PHONE")

        if validate_phone_number is None:
            self.validate_phone_number = default_validate_phone_number
        else:
            self.validate_phone_number = validate_phone_number


class ContactEmailOnlyConfig(ContactConfig):
    def __init__(
        self,
        validate_email_address: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("EMAIL")

        if validate_email_address is None:
            self.validate_email_address = default_validate_email
        else:
            self.validate_email_address = validate_email_address


class ContactEmailOrPhoneConfig(ContactConfig):
    def __init__(
        self,
        validate_email_address: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
        validate_phone_number: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("EMAIL_OR_PHONE")

        if validate_email_address is None:
            self.validate_email_address = default_validate_email
        else:
            self.validate_email_address = validate_email_address

        if validate_phone_number is None:
            self.validate_phone_number = default_validate_phone_number
        else:
            self.validate_phone_number = validate_phone_number


class PhoneOrEmailInput:
    def __init__(self, phone_number: Union[str, None], email: Union[str, None]):
        self.phone_number = phone_number
        self.email = email


class PasswordlessOverrideableConfig(BaseOverrideableConfig):
    """Input config properties overrideable using the plugin config overrides"""

    contact_config: ContactConfig
    flow_type: Literal[
        "USER_INPUT_CODE", "MAGIC_LINK", "USER_INPUT_CODE_AND_MAGIC_LINK"
    ]
    get_custom_user_input_code: Union[
        Callable[[str, Dict[str, Any]], Awaitable[str]], None
    ] = None
    email_delivery: Union[
        EmailDeliveryConfig[PasswordlessLoginEmailTemplateVars], None
    ] = None
    sms_delivery: Union[SMSDeliveryConfig[PasswordlessLoginSMSTemplateVars], None] = (
        None
    )


class PasswordlessConfig(
    PasswordlessOverrideableConfig,
    BaseConfig[RecipeInterface, APIInterface, PasswordlessOverrideableConfig],
):
    def to_overrideable_config(self) -> PasswordlessOverrideableConfig:
        """Create a `PasswordlessOverrideableConfig` from the current config."""
        return PasswordlessOverrideableConfig(**self.model_dump())

    def from_overrideable_config(
        self,
        overrideable_config: PasswordlessOverrideableConfig,
    ) -> "PasswordlessConfig":
        """
        Create a `PasswordlessConfig` from a `PasswordlessOverrideableConfig`.
        Not a classmethod since it needs to be used in a dynamic context within plugins.
        """
        return PasswordlessConfig(
            **overrideable_config.model_dump(),
            override=self.override,
        )


class NormalisedPasswordlessConfig(BaseNormalisedConfig[RecipeInterface, APIInterface]):
    contact_config: ContactConfig
    flow_type: Literal[
        "USER_INPUT_CODE", "MAGIC_LINK", "USER_INPUT_CODE_AND_MAGIC_LINK"
    ]
    get_email_delivery_config: Callable[
        [], EmailDeliveryConfigWithService[PasswordlessLoginEmailTemplateVars]
    ]
    get_sms_delivery_config: Callable[
        [], SMSDeliveryConfigWithService[PasswordlessLoginSMSTemplateVars]
    ]
    get_custom_user_input_code: Union[
        Callable[[str, Dict[str, Any]], Awaitable[str]], None
    ]


def validate_and_normalise_user_input(
    app_info: AppInfo,
    config: PasswordlessConfig,
) -> NormalisedPasswordlessConfig:
    override_config = NormalisedPasswordlessOverrideConfig.from_input_config(
        override_config=config.override
    )

    def get_email_delivery_config() -> EmailDeliveryConfigWithService[
        PasswordlessLoginEmailTemplateVars
    ]:
        email_service = (
            config.email_delivery.service if config.email_delivery is not None else None
        )

        if email_service is None:
            email_service = BackwardCompatibilityService(app_info)

        if (
            config.email_delivery is not None
            and config.email_delivery.override is not None
        ):
            override = config.email_delivery.override
        else:
            override = None

        return EmailDeliveryConfigWithService(email_service, override=override)

    def get_sms_delivery_config() -> SMSDeliveryConfigWithService[
        PasswordlessLoginSMSTemplateVars
    ]:
        sms_service = (
            config.sms_delivery.service if config.sms_delivery is not None else None
        )

        if sms_service is None:
            sms_service = SMSBackwardCompatibilityService(app_info)

        if config.sms_delivery is not None and config.sms_delivery.override is not None:
            override = config.sms_delivery.override
        else:
            override = None

        return SMSDeliveryConfigWithService(sms_service, override=override)

    if not isinstance(config.contact_config, ContactConfig):  # type: ignore user might not have linter enabled
        raise ValueError("contact_config must be of type ContactConfig")

    if config.flow_type not in [
        "USER_INPUT_CODE",
        "MAGIC_LINK",
        "USER_INPUT_CODE_AND_MAGIC_LINK",
    ]:
        raise ValueError(
            "flow_type must be one of USER_INPUT_CODE, MAGIC_LINK, USER_INPUT_CODE_AND_MAGIC_LINK"
        )

    return NormalisedPasswordlessConfig(
        contact_config=config.contact_config,
        override=override_config,
        flow_type=config.flow_type,
        get_email_delivery_config=get_email_delivery_config,
        get_sms_delivery_config=get_sms_delivery_config,
        get_custom_user_input_code=config.get_custom_user_input_code,
    )


def get_enabled_pwless_factors(
    config: NormalisedPasswordlessConfig,
) -> List[str]:
    all_factors: List[str] = []

    if config.flow_type == "MAGIC_LINK":
        if config.contact_config.contact_method == "EMAIL":
            all_factors = [FactorIds.LINK_EMAIL]
        elif config.contact_config.contact_method == "PHONE":
            all_factors = [FactorIds.LINK_PHONE]
        else:
            all_factors = [FactorIds.LINK_EMAIL, FactorIds.LINK_PHONE]
    elif config.flow_type == "USER_INPUT_CODE":
        if config.contact_config.contact_method == "EMAIL":
            all_factors = [FactorIds.OTP_EMAIL]
        elif config.contact_config.contact_method == "PHONE":
            all_factors = [FactorIds.OTP_PHONE]
        else:
            all_factors = [FactorIds.OTP_EMAIL, FactorIds.OTP_PHONE]
    else:
        if config.contact_config.contact_method == "EMAIL":
            all_factors = [FactorIds.OTP_EMAIL, FactorIds.LINK_EMAIL]
        elif config.contact_config.contact_method == "PHONE":
            all_factors = [FactorIds.OTP_PHONE, FactorIds.LINK_PHONE]
        else:
            all_factors = [
                FactorIds.OTP_EMAIL,
                FactorIds.OTP_PHONE,
                FactorIds.LINK_EMAIL,
                FactorIds.LINK_PHONE,
            ]

    return all_factors

Functions

async def default_validate_email(value: str, _tenant_id: str)
async def default_validate_phone_number(value: str, _tenant_id: str)
def get_enabled_pwless_factors(config: NormalisedPasswordlessConfig) ‑> List[str]
def validate_and_normalise_user_input(app_info: AppInfo, config: PasswordlessConfig)

Classes

class InputOverrideConfig (**data: Any)

Base class for input override config with API overrides.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Inherited members

class ContactConfig (contact_method: "Literal['PHONE', 'EMAIL', 'EMAIL_OR_PHONE']")

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

Expand source code 
class ContactConfig(ABC):
    def __init__(self, contact_method: Literal["PHONE", "EMAIL", "EMAIL_OR_PHONE"]):
        self.contact_method = contact_method

Ancestors

  • abc.ABC

Subclasses

class ContactEmailOnlyConfig (validate_email_address: Union[Callable[[str, str], Awaitable[Union[str, None]]], None] = None)

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

Expand source code 
class ContactEmailOnlyConfig(ContactConfig):
    def __init__(
        self,
        validate_email_address: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("EMAIL")

        if validate_email_address is None:
            self.validate_email_address = default_validate_email
        else:
            self.validate_email_address = validate_email_address

Ancestors

class ContactEmailOrPhoneConfig (validate_email_address: Union[Callable[[str, str], Awaitable[Union[str, None]]], None] = None, validate_phone_number: Union[Callable[[str, str], Awaitable[Union[str, None]]], None] = None)

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

Expand source code 
class ContactEmailOrPhoneConfig(ContactConfig):
    def __init__(
        self,
        validate_email_address: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
        validate_phone_number: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("EMAIL_OR_PHONE")

        if validate_email_address is None:
            self.validate_email_address = default_validate_email
        else:
            self.validate_email_address = validate_email_address

        if validate_phone_number is None:
            self.validate_phone_number = default_validate_phone_number
        else:
            self.validate_phone_number = validate_phone_number

Ancestors

class ContactPhoneOnlyConfig (validate_phone_number: Union[Callable[[str, str], Awaitable[Union[str, None]]], None] = None)

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

Expand source code 
class ContactPhoneOnlyConfig(ContactConfig):
    def __init__(
        self,
        validate_phone_number: Union[
            Callable[[str, str], Awaitable[Union[str, None]]], None
        ] = None,
    ):
        super().__init__("PHONE")

        if validate_phone_number is None:
            self.validate_phone_number = default_validate_phone_number
        else:
            self.validate_phone_number = validate_phone_number

Ancestors

class NormalisedPasswordlessConfig (**data: Any)

Base class for normalized config of a Recipe with API overrides.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Expand source code 
class NormalisedPasswordlessConfig(BaseNormalisedConfig[RecipeInterface, APIInterface]):
    contact_config: ContactConfig
    flow_type: Literal[
        "USER_INPUT_CODE", "MAGIC_LINK", "USER_INPUT_CODE_AND_MAGIC_LINK"
    ]
    get_email_delivery_config: Callable[
        [], EmailDeliveryConfigWithService[PasswordlessLoginEmailTemplateVars]
    ]
    get_sms_delivery_config: Callable[
        [], SMSDeliveryConfigWithService[PasswordlessLoginSMSTemplateVars]
    ]
    get_custom_user_input_code: Union[
        Callable[[str, Dict[str, Any]], Awaitable[str]], None
    ]

Ancestors

Class variables

var contact_config : ContactConfig

The type of the None singleton.

var flow_type : Literal['USER_INPUT_CODE', 'MAGIC_LINK', 'USER_INPUT_CODE_AND_MAGIC_LINK']

The type of the None singleton.

var get_custom_user_input_code : Optional[Callable[[str, Dict[str, Any]], Awaitable[str]]]

The type of the None singleton.

var get_email_delivery_config : Callable[[], EmailDeliveryConfigWithService[CreateAndSendCustomEmailParameters]]

The type of the None singleton.

var get_sms_delivery_config : Callable[[], SMSDeliveryConfigWithService[CreateAndSendCustomTextMessageParameters]]

The type of the None singleton.

Inherited members

class PasswordlessConfig (**data: Any)

Input config properties overrideable using the plugin config overrides

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Expand source code 
class PasswordlessConfig(
    PasswordlessOverrideableConfig,
    BaseConfig[RecipeInterface, APIInterface, PasswordlessOverrideableConfig],
):
    def to_overrideable_config(self) -> PasswordlessOverrideableConfig:
        """Create a `PasswordlessOverrideableConfig` from the current config."""
        return PasswordlessOverrideableConfig(**self.model_dump())

    def from_overrideable_config(
        self,
        overrideable_config: PasswordlessOverrideableConfig,
    ) -> "PasswordlessConfig":
        """
        Create a `PasswordlessConfig` from a `PasswordlessOverrideableConfig`.
        Not a classmethod since it needs to be used in a dynamic context within plugins.
        """
        return PasswordlessConfig(
            **overrideable_config.model_dump(),
            override=self.override,
        )

Ancestors

Methods

def from_overrideable_config(self, overrideable_config: PasswordlessOverrideableConfig) ‑> PasswordlessConfig

Create a PasswordlessConfig from a PasswordlessOverrideableConfig. Not a classmethod since it needs to be used in a dynamic context within plugins.

def to_overrideable_config(self) ‑> PasswordlessOverrideableConfig

Create a PasswordlessOverrideableConfig from the current config.

Inherited members

class PasswordlessOverrideableConfig (**data: Any)

Input config properties overrideable using the plugin config overrides

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Expand source code 
class PasswordlessOverrideableConfig(BaseOverrideableConfig):
    """Input config properties overrideable using the plugin config overrides"""

    contact_config: ContactConfig
    flow_type: Literal[
        "USER_INPUT_CODE", "MAGIC_LINK", "USER_INPUT_CODE_AND_MAGIC_LINK"
    ]
    get_custom_user_input_code: Union[
        Callable[[str, Dict[str, Any]], Awaitable[str]], None
    ] = None
    email_delivery: Union[
        EmailDeliveryConfig[PasswordlessLoginEmailTemplateVars], None
    ] = None
    sms_delivery: Union[SMSDeliveryConfig[PasswordlessLoginSMSTemplateVars], None] = (
        None
    )

Ancestors

Subclasses

Class variables

var contact_config : ContactConfig

The type of the None singleton.

var email_delivery : Optional[EmailDeliveryConfig[CreateAndSendCustomEmailParameters]]

The type of the None singleton.

var flow_type : Literal['USER_INPUT_CODE', 'MAGIC_LINK', 'USER_INPUT_CODE_AND_MAGIC_LINK']

The type of the None singleton.

var get_custom_user_input_code : Optional[Callable[[str, Dict[str, Any]], Awaitable[str]]]

The type of the None singleton.

var sms_delivery : Optional[SMSDeliveryConfig[CreateAndSendCustomTextMessageParameters]]

The type of the None singleton.

Inherited members

class PhoneOrEmailInput (phone_number: Union[str, None], email: Union[str, None])
Expand source code 
class PhoneOrEmailInput:
    def __init__(self, phone_number: Union[str, None], email: Union[str, None]):
        self.phone_number = phone_number
        self.email = email