feat: adds util function to get available first factors (#610)

- Adds util function to get available first factors
- Cleans up supertokens __init__ file to reduce redundancy
- Adds test to ensure FactorIds class and method are in sync

ref: supertokens/supertokens-node#1021

Author: namsnath

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [unreleased]
 
 ## [0.31.0] - 2025-08-21
+- Adds util function to get available first factors
+
 ### Adds plugins support
 - Adds an `experimental` property (`SuperTokensExperimentalConfig`) to the `SuperTokensConfig`
   - Plugins can be configured under using the `plugins` property in the `experimental` config

supertokens_python/__init__.py

@@ -12,11 +12,10 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-from typing import Any, Dict, List, Optional
+from typing import List, Optional
 
 from typing_extensions import Literal
 
-from supertokens_python.framework.request import BaseRequest
 from supertokens_python.recipe_module import RecipeModule
 from supertokens_python.types import RecipeUserId
 
@@ -30,6 +29,8 @@
     SupertokensExperimentalConfig,
     SupertokensInputConfig,
     SupertokensPublicConfig,
+    get_request_from_user_context,
+    is_recipe_initialized,
 )
 
 # Some Pydantic models need a rebuild to resolve ForwardRefs
@@ -69,19 +70,10 @@ def get_all_cors_headers() -> List[str]:
     return Supertokens.get_instance().get_all_cors_headers()
 
 
-def get_request_from_user_context(
-    user_context: Optional[Dict[str, Any]],
-) -> Optional[BaseRequest]:
-    return Supertokens.get_instance().get_request_from_user_context(user_context)
-
-
 def convert_to_recipe_user_id(user_id: str) -> RecipeUserId:
     return RecipeUserId(user_id)
 
 
-is_recipe_initialized = Supertokens.is_recipe_initialized
-
-
 __all__ = [
     "AppInfo",
     "InputAppInfo",

supertokens_python/asyncio/__init__.py

@@ -14,6 +14,7 @@
 from typing import Any, Dict, List, Optional, Union
 
 from supertokens_python import Supertokens
+from supertokens_python.exceptions import BadInputError
 from supertokens_python.interfaces import (
     CreateUserIdMappingOkResult,
     DeleteUserIdMappingOkResult,
@@ -26,8 +27,9 @@
 )
 from supertokens_python.recipe.accountlinking.interfaces import GetUsersResult
 from supertokens_python.recipe.accountlinking.recipe import AccountLinkingRecipe
+from supertokens_python.recipe.session.interfaces import SessionContainer
 from supertokens_python.types import User
-from supertokens_python.types.base import AccountInfoInput
+from supertokens_python.types.base import AccountInfoInput, UserContext
 
 
 async def get_users_oldest_first(
@@ -172,3 +174,31 @@ async def list_users_by_account_info(
         do_union_of_account_info,
         user_context,
     )
+
+
+async def get_available_first_factors(
+    tenant_id: str,
+    session: Optional[SessionContainer],
+    user_context: Optional[UserContext],
+):
+    from supertokens_python.auth_utils import (
+        filter_out_invalid_first_factors_or_throw_if_all_are_invalid,
+    )
+    from supertokens_python.recipe.multifactorauth.types import FactorIds
+
+    available_first_factors: List[str] = []
+
+    try:
+        available_first_factors = (
+            await filter_out_invalid_first_factors_or_throw_if_all_are_invalid(
+                factor_ids=FactorIds.get_all_factors(),
+                tenant_id=tenant_id,
+                has_session=session is not None,
+                user_context=user_context if user_context is not None else {},
+            )
+        )
+    except BadInputError:
+        # All the factors were invalid, so we let it pass through and return the empty list
+        pass
+
+    return available_first_factors

supertokens_python/recipe/multifactorauth/types.py

@@ -61,14 +61,27 @@ class NormalisedMultiFactorAuthConfig(
 
 
 class FactorIds:
-    EMAILPASSWORD: Literal["emailpassword"] = "emailpassword"
-    OTP_EMAIL: Literal["otp-email"] = "otp-email"
-    OTP_PHONE: Literal["otp-phone"] = "otp-phone"
-    LINK_EMAIL: Literal["link-email"] = "link-email"
-    LINK_PHONE: Literal["link-phone"] = "link-phone"
-    THIRDPARTY: Literal["thirdparty"] = "thirdparty"
-    TOTP: Literal["totp"] = "totp"
-    WEBAUTHN: Literal["webauthn"] = "webauthn"
+    EMAILPASSWORD = "emailpassword"
+    OTP_EMAIL = "otp-email"
+    OTP_PHONE = "otp-phone"
+    LINK_EMAIL = "link-email"
+    LINK_PHONE = "link-phone"
+    THIRDPARTY = "thirdparty"
+    TOTP = "totp"
+    WEBAUTHN = "webauthn"
+
+    @staticmethod
+    def get_all_factors():
+        return [
+            FactorIds.EMAILPASSWORD,
+            FactorIds.OTP_EMAIL,
+            FactorIds.OTP_PHONE,
+            FactorIds.LINK_EMAIL,
+            FactorIds.LINK_PHONE,
+            FactorIds.THIRDPARTY,
+            FactorIds.TOTP,
+            FactorIds.WEBAUTHN,
+        ]
 
 
 class FactorIdsAndType:

supertokens_python/supertokens.py

@@ -42,6 +42,7 @@
     SuperTokensPlugin,
     SuperTokensPublicPlugin,
 )
+from supertokens_python.types.base import UserContext
 from supertokens_python.types.response import CamelCaseBaseModel
 
 from .constants import FDI_KEY_HEADER, RID_KEY_HEADER, USER_COUNT
@@ -181,13 +182,13 @@ def __init__(
         self.mode = mode
 
     def get_top_level_website_domain(
-        self, request: Optional[BaseRequest], user_context: Dict[str, Any]
+        self, request: Optional[BaseRequest], user_context: UserContext
     ) -> str:
         return get_top_level_domain_for_same_site_resolution(
             self.get_origin(request, user_context).get_as_string_dangerous()
         )
 
-    def get_origin(self, request: Optional[BaseRequest], user_context: Dict[str, Any]):
+    def get_origin(self, request: Optional[BaseRequest], user_context: UserContext):
         origin = self.__origin
         if origin is None:
             origin = self.__website_domain
@@ -211,7 +212,7 @@ def defaultImpl(o: Any):
 
 
 def manage_session_post_response(
-    session: SessionContainer, response: BaseResponse, user_context: Dict[str, Any]
+    session: SessionContainer, response: BaseResponse, user_context: UserContext
 ):
     # Something similar happens in handle_error of session/recipe.py
     for mutator in session.response_mutators:
@@ -577,7 +578,7 @@ async def get_user_count(
         self,
         include_recipe_ids: Union[None, List[str]],
         tenant_id: Optional[str] = None,
-        user_context: Optional[Dict[str, Any]] = None,
+        user_context: Optional[UserContext] = None,
     ) -> int:
         querier = Querier.get_instance(None)
         include_recipe_ids_str = None
@@ -601,7 +602,7 @@ async def create_user_id_mapping(
         external_user_id: str,
         external_user_id_info: Optional[str],
         force: Optional[bool],
-        user_context: Optional[Dict[str, Any]],
+        user_context: Optional[UserContext],
     ) -> Union[
         CreateUserIdMappingOkResult,
         UnknownSupertokensUserIDError,
@@ -641,7 +642,7 @@ async def get_user_id_mapping(
         self,
         user_id: str,
         user_id_type: Optional[UserIDTypes],
-        user_context: Optional[Dict[str, Any]],
+        user_context: Optional[UserContext],
     ) -> Union[GetUserIdMappingOkResult, UnknownMappingError]:
         querier = Querier.get_instance(None)
 
@@ -676,7 +677,7 @@ async def delete_user_id_mapping(
         user_id: str,
         user_id_type: Optional[UserIDTypes],
         force: Optional[bool],
-        user_context: Optional[Dict[str, Any]],
+        user_context: Optional[UserContext],
     ) -> DeleteUserIdMappingOkResult:
         querier = Querier.get_instance(None)
 
@@ -708,7 +709,7 @@ async def update_or_delete_user_id_mapping_info(
         user_id: str,
         user_id_type: Optional[UserIDTypes],
         external_user_id_info: Optional[str],
-        user_context: Optional[Dict[str, Any]],
+        user_context: Optional[UserContext],
     ) -> Union[UpdateOrDeleteUserIdMappingInfoOkResult, UnknownMappingError]:
         querier = Querier.get_instance(None)
 
@@ -734,7 +735,7 @@ async def update_or_delete_user_id_mapping_info(
         raise_general_exception("Please upgrade the SuperTokens core to >= 3.15.0")
 
     async def middleware(
-        self, request: BaseRequest, response: BaseResponse, user_context: Dict[str, Any]
+        self, request: BaseRequest, response: BaseResponse, user_context: UserContext
     ) -> Union[BaseResponse, None]:
         from supertokens_python.recipe.session.recipe import SessionRecipe
 
@@ -907,7 +908,7 @@ async def handle_supertokens_error(
         request: BaseRequest,
         err: Exception,
         response: BaseResponse,
-        user_context: Dict[str, Any],
+        user_context: UserContext,
     ) -> Optional[BaseResponse]:
         log_debug_message("errorHandler: Started")
         log_debug_message(
@@ -935,7 +936,7 @@ async def handle_supertokens_error(
 
     def get_request_from_user_context(
         self,
-        user_context: Optional[Dict[str, Any]] = None,
+        user_context: Optional[UserContext] = None,
     ) -> Optional[BaseRequest]:
         if user_context is None:
             return None
@@ -948,20 +949,22 @@ def get_request_from_user_context(
 
         return user_context.get("_default", {}).get("request")
 
-    @staticmethod
-    def is_recipe_initialized(recipe_id: str) -> bool:
+    def is_recipe_initialized(self, recipe_id: str) -> bool:
         """
         Check if a recipe is initialized.
         :param recipe_id: The ID of the recipe to check.
         :return: Whether the recipe is initialized.
         """
         return any(
-            recipe.get_recipe_id() == recipe_id
-            for recipe in Supertokens.get_instance().recipe_modules
+            recipe.get_recipe_id() == recipe_id for recipe in self.recipe_modules
         )
 
 
 def get_request_from_user_context(
-    user_context: Optional[Dict[str, Any]],
+    user_context: Optional[UserContext],
 ) -> Optional[BaseRequest]:
     return Supertokens.get_instance().get_request_from_user_context(user_context)
+
+
+def is_recipe_initialized(recipe_id: str) -> bool:
+    return Supertokens.get_instance().is_recipe_initialized(recipe_id)

supertokens_python/syncio/__init__.py

@@ -25,8 +25,9 @@
     UserIdMappingAlreadyExistsError,
     UserIDTypes,
 )
+from supertokens_python.recipe.session.interfaces import SessionContainer
 from supertokens_python.types import User
-from supertokens_python.types.base import AccountInfoInput
+from supertokens_python.types.base import AccountInfoInput, UserContext
 
 
 def get_users_oldest_first(
@@ -178,3 +179,19 @@ def list_users_by_account_info(
             tenant_id, account_info, do_union_of_account_info, user_context
         )
     )
+
+
+def get_available_first_factors(
+    tenant_id: str,
+    session: Optional[SessionContainer],
+    user_context: Optional[UserContext],
+):
+    from supertokens_python.asyncio import (
+        get_available_first_factors as async_get_available_first_factors,
+    )
+
+    return sync(
+        async_get_available_first_factors(
+            tenant_id=tenant_id, session=session, user_context=user_context
+        )
+    )

tests/test_mfa.py

@@ -0,0 +1,15 @@
+from supertokens_python.recipe.multifactorauth.types import FactorIds
+
+
+def test_get_all_factors():
+    """Test that FactorIds.get_all_factors returns all factors defined in FactorIds class."""
+    factors_from_dict: list[str] = []
+    for k, v in FactorIds.__dict__.items():
+        if (
+            (not k.startswith("__") or not k.endswith("__"))
+            and not k.startswith("<")
+            and isinstance(v, str)
+        ):
+            factors_from_dict.append(v)
+
+    assert factors_from_dict == FactorIds.get_all_factors()