feat: webauthn (#583)

### Adds Webauthn (Passkeys) support
- Adds Webauthn recipe with support for:
  - Registration, sign-in, and credential verification flows
  - Account recovery
- Adds new API endpoints for WebAuthn operations:
  - GET `/api/webauthn/email/exists` - Check if email exists in system
  - POST `/api/webauthn/options/register` - Handle registration options
  - POST `/api/webauthn/options/signin` - Handle sign-in options
  - POST `/api/webauthn/signin` - Handle WebAuthn sign-in
  - POST `/api/webauthn/signup` - Handle WebAuthn sign-up
  - POST `/api/user/webauthn/reset` - Handle account recovery
  - POST `/api/user/webauthn/reset/token` - Generate recovery tokens
- Adds WebAuthn support to account linking functionality:
  - Support for linking users based on WebAuthn `credential_id`
  - Updates `AccountInfo` type to `AccountInfoInput` with WebAuthn fields
  - Adds `has_same_webauthn_info_as` method for credential comparison
- Adds FDI support for version `4.1`
- Recipe functions are directly importable from the Webauthn recipe module
  - ```python
    from supertokens_python.recipe.webauthn import sign_in

    await sign_in(...) # Async
    sign_in.sync(...) # Sync
    ```

### Breaking Changes
- Updates supported CDI version from `5.2` to `5.3`
- Changes `AccountInfo` to `AccountInfoInput` in various methods
  - This is required to allow querying by a single Webauthn `credential_id`, while the Webauthn login method contains an array of `credential_ids`
  - Affected functions:
    - `supertokens_python.asyncio.list_users_by_account_info`
    - `supertokens_python.syncio.list_users_by_account_info`
    - `supertokens_python.recipe.accountlinking.interface.RecipeInterface.list_users_by_account_info`
    - `supertokens_python.recipe.accountlinking.recipe_implementation.RecipeImplementation.list_users_by_account_info`

Author: namsnath

.github/workflows/backend-sdk-testing.yml

@@ -82,10 +82,11 @@ jobs:
         run: |
           source venv/bin/activate
           docker compose up --build --wait
-          python3 tests/test-server/app.py &
+          python3 tests/test-server/app.py &> python.log &
 
       - uses: supertokens/backend-sdk-testing-action@main
         with:
           version: ${{ matrix.fdi-version }}
           check-name-suffix: '[CDI=${{ matrix.cdi-version }}][Core=${{ steps.versions.outputs.coreVersionXy }}][FDI=${{ matrix.fdi-version }}][Py=${{ matrix.py-version }}][Node=${{ matrix.node-version }}]'
           path: backend-sdk-testing
+          app-server-logs: ${{ github.workspace }}/supertokens-python/python.log

.github/workflows/lint-code.yml

@@ -19,6 +19,11 @@ jobs:
     outputs:
       pyVersions: '["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]'
 
+    steps:
+      # Required to avoid errors in runs due to no steps
+      - name: Placeholder
+        run: echo "Placeholder"
+
   lint-format:
     name: Check linting and formatting
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -8,6 +8,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [0.30.0] - 2025-05-27
+### Adds Webauthn (Passkeys) support
+- Adds Webauthn recipe with support for:
+  - Registration, sign-in, and credential verification flows
+  - Account recovery
+- Adds new API endpoints for WebAuthn operations:
+  - GET `/api/webauthn/email/exists` - Check if email exists in system
+  - POST `/api/webauthn/options/register` - Handle registration options
+  - POST `/api/webauthn/options/signin` - Handle sign-in options
+  - POST `/api/webauthn/signin` - Handle WebAuthn sign-in
+  - POST `/api/webauthn/signup` - Handle WebAuthn sign-up
+  - POST `/api/user/webauthn/reset` - Handle account recovery
+  - POST `/api/user/webauthn/reset/token` - Generate recovery tokens
+- Adds WebAuthn support to account linking functionality:
+  - Support for linking users based on WebAuthn `credential_id`
+  - Updates `AccountInfo` type to `AccountInfoInput` with WebAuthn fields
+  - Adds `has_same_webauthn_info_as` method for credential comparison
+- Adds FDI support for version `4.1`
+- Recipe functions are directly importable from the Webauthn recipe module
+  - ```python
+    from supertokens_python.recipe.webauthn import sign_in
+
+    await sign_in(...) # Async
+    sign_in.sync(...) # Sync
+    ```
+
+### Breaking Changes
+- Updates supported CDI version from `5.2` to `5.3`
+- Changes `AccountInfo` to `AccountInfoInput` in various methods
+  - This is required to allow querying by a single Webauthn `credential_id`, while the Webauthn login method contains an array of `credential_ids`
+  - Affected functions:
+    - `supertokens_python.asyncio.list_users_by_account_info`
+    - `supertokens_python.syncio.list_users_by_account_info`
+    - `supertokens_python.recipe.accountlinking.interface.RecipeInterface.list_users_by_account_info`
+    - `supertokens_python.recipe.accountlinking.recipe_implementation.RecipeImplementation.list_users_by_account_info`
+    - `supertokens_python.recipe.passwordless.api.implementation.get_passwordless_user_by_account_info`
+    - `supertokens_python.recipe.passwordless.api.implementation.get_passwordless_user_by_account_info`
+
+
 ## [0.29.2] - 2025-05-19
 - Fixes cookies being set without expiry in Django
   - Reverts timezone change from 0.28.0 and uses GMT

coreDriverInterfaceSupported.json

@@ -1,6 +1,6 @@
 {
   "_comment": "contains a list of core-driver interfaces branch names that this core supports",
   "versions": [
-    "5.2"
+    "5.3"
   ]
 }

dev-requirements.txt

@@ -21,4 +21,5 @@ pyyaml==6.0.2
 requests-mock==1.12.1
 respx>=0.13.0, <1.0.0
 uvicorn==0.32.0
+wasmtime==25.0.0
 -e .

frontendDriverInterfaceSupported.json

@@ -7,6 +7,7 @@
         "2.0",
         "3.0",
         "3.1",
-        "4.0"
+        "4.0",
+        "4.1"
     ]
 }

setup.py

@@ -82,7 +82,7 @@
 
 setup(
     name="supertokens_python",
-    version="0.29.2",
+    version="0.30.0",
     author="SuperTokens",
     license="Apache 2.0",
     author_email="[email protected]",
@@ -127,6 +127,7 @@
         "pkce<1.1.0",
         "pyotp<3",
         "python-dateutil<3",
+        "pydantic>=2.10.6,<3.0.0",
     ],
     python_requires=">=3.8",
     include_package_data=True,

supertokens_python/async_to_sync_wrapper.py

@@ -13,8 +13,20 @@
 # under the License.
 
 import asyncio
+from functools import update_wrapper
 from os import getenv
-from typing import Any, Coroutine, TypeVar
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    Generic,
+    TypeVar,
+)
+
+from typing_extensions import ParamSpec
+
+Param = ParamSpec("Param")
+RetType = TypeVar("RetType", covariant=True)
 
 _T = TypeVar("_T")
 
@@ -43,3 +55,25 @@ def create_or_get_event_loop() -> asyncio.AbstractEventLoop:
 def sync(co: Coroutine[Any, Any, _T]) -> _T:
     loop = create_or_get_event_loop()
     return loop.run_until_complete(co)
+
+
+class syncify(Generic[Param, RetType]):
+    """
+    Decorator to allow async functions to be executed synchronously
+    using a `sync` attribute.
+    """
+
+    def __init__(self, func: Callable[Param, Coroutine[Any, Any, RetType]]):
+        update_wrapper(self, func)
+        self.func = func
+
+    def __call__(
+        self, *args: Param.args, **kwargs: Param.kwargs
+    ) -> Coroutine[Any, Any, RetType]:
+        return self.func(*args, **kwargs)
+
+    def sync(self, *args: Param.args, **kwargs: Param.kwargs) -> RetType:
+        """
+        Synchronous version of the decorated function.
+        """
+        return sync(self.func(*args, **kwargs))

supertokens_python/asyncio/__init__.py

@@ -26,7 +26,8 @@
 )
 from supertokens_python.recipe.accountlinking.interfaces import GetUsersResult
 from supertokens_python.recipe.accountlinking.recipe import AccountLinkingRecipe
-from supertokens_python.types import AccountInfo, User
+from supertokens_python.types import User
+from supertokens_python.types.base import AccountInfoInput
 
 
 async def get_users_oldest_first(
@@ -159,7 +160,7 @@ async def update_or_delete_user_id_mapping_info(
 
 async def list_users_by_account_info(
     tenant_id: str,
-    account_info: AccountInfo,
+    account_info: AccountInfoInput,
     do_union_of_account_info: bool = False,
     user_context: Optional[Dict[str, Any]] = None,
 ) -> List[User]:

supertokens_python/auth_utils.py

@@ -1,4 +1,4 @@
-from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, Union
 
 from typing_extensions import Literal
 
@@ -31,37 +31,18 @@
 from supertokens_python.recipe.session.interfaces import SessionContainer
 from supertokens_python.recipe.thirdparty.types import ThirdPartyInfo
 from supertokens_python.types import (
-    AccountInfo,
     LoginMethod,
     RecipeUserId,
     User,
 )
+from supertokens_python.types.auth_utils import LinkingToSessionUserFailedError
+from supertokens_python.types.base import AccountInfoInput
 from supertokens_python.utils import log_debug_message
 
 from .asyncio import get_user
 
-
-class LinkingToSessionUserFailedError:
-    status: Literal["LINKING_TO_SESSION_USER_FAILED"] = "LINKING_TO_SESSION_USER_FAILED"
-    reason: Literal[
-        "EMAIL_VERIFICATION_REQUIRED",
-        "RECIPE_USER_ID_ALREADY_LINKED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-        "ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-        "SESSION_USER_ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-        "INPUT_USER_IS_NOT_A_PRIMARY_USER",
-    ]
-
-    def __init__(
-        self,
-        reason: Literal[
-            "EMAIL_VERIFICATION_REQUIRED",
-            "RECIPE_USER_ID_ALREADY_LINKED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-            "ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-            "SESSION_USER_ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR",
-            "INPUT_USER_IS_NOT_A_PRIMARY_USER",
-        ],
-    ):
-        self.reason = reason
+if TYPE_CHECKING:
+    from supertokens_python.recipe.webauthn.types.base import WebauthnInfoInput
 
 
 class OkResponse:
@@ -290,6 +271,7 @@ async def get_authenticating_user_and_add_to_current_tenant_if_required(
     session: Optional[SessionContainer],
     check_credentials_on_tenant: Callable[[str], Awaitable[bool]],
     user_context: Dict[str, Any],
+    webauthn: Optional["WebauthnInfoInput"] = None,
 ) -> Optional[AuthenticatingUserInfo]:
     i = 0
     while i < 300:
@@ -303,8 +285,11 @@ async def get_authenticating_user_and_add_to_current_tenant_if_required(
         )
         existing_users = await AccountLinkingRecipe.get_instance().recipe_implementation.list_users_by_account_info(
             tenant_id=tenant_id,
-            account_info=AccountInfo(
-                email=email, phone_number=phone_number, third_party=third_party
+            account_info=AccountInfoInput(
+                email=email,
+                phone_number=phone_number,
+                third_party=third_party,
+                webauthn=webauthn,
             ),
             do_union_of_account_info=True,
             user_context=user_context,
@@ -324,6 +309,7 @@ async def get_authenticating_user_and_add_to_current_tenant_if_required(
                             (email is not None and lm.has_same_email_as(email))
                             or lm.has_same_phone_number_as(phone_number)
                             or lm.has_same_third_party_info_as(third_party)
+                            or lm.has_same_webauthn_info_as(webauthn)
                         )
                     ),
                     None,

supertokens_python/constants.py

@@ -14,8 +14,8 @@
 
 from __future__ import annotations
 
-SUPPORTED_CDI_VERSIONS = ["5.2"]
-VERSION = "0.29.2"
+SUPPORTED_CDI_VERSIONS = ["5.3"]
+VERSION = "0.30.0"
 TELEMETRY = "/telemetry"
 USER_COUNT = "/users/count"
 USER_DELETE = "/user/remove"

supertokens_python/recipe/accountlinking/interfaces.py

@@ -18,9 +18,10 @@
 
 from typing_extensions import Literal
 
+from supertokens_python.types.base import AccountInfoInput
+
 if TYPE_CHECKING:
     from supertokens_python.types import (
-        AccountInfo,
         RecipeUserId,
         User,
     )
@@ -104,7 +105,7 @@ async def get_user(
     async def list_users_by_account_info(
         self,
         tenant_id: str,
-        account_info: AccountInfo,
+        account_info: AccountInfoInput,
         do_union_of_account_info: bool,
         user_context: Dict[str, Any],
     ) -> List[User]:

supertokens_python/recipe/accountlinking/recipe.py

@@ -27,11 +27,11 @@
 from supertokens_python.querier import Querier
 from supertokens_python.recipe_module import APIHandled, RecipeModule
 from supertokens_python.supertokens import Supertokens
+from supertokens_python.types.base import AccountInfoInput
 
 from .interfaces import RecipeInterface
 from .recipe_implementation import RecipeImplementation
 from .types import (
-    AccountInfo,
     AccountInfoWithRecipeId,
     AccountInfoWithRecipeIdAndUserId,
     InputOverrideConfig,
@@ -210,7 +210,15 @@ async def get_primary_user_that_can_be_linked_to_recipe_user_id(
         # Then, we try and find a primary user based on the email / phone number / third party ID.
         users = await self.recipe_implementation.list_users_by_account_info(
             tenant_id=tenant_id,
-            account_info=user.login_methods[0],
+            account_info=AccountInfoInput(
+                email=user.login_methods[0].email,
+                phone_number=user.login_methods[0].phone_number,
+                third_party=user.login_methods[0].third_party,
+                # We don't need to list by (webauthn) credentialId because we are looking for
+                # a user to link to the current recipe user, but any search using the credentialId
+                # of the current user "will identify the same user" which is the current one.
+                webauthn=None,
+            ),
             do_union_of_account_info=True,
             user_context=user_context,
         )
@@ -266,7 +274,15 @@ async def get_oldest_user_that_can_be_linked_to_recipe_user(
         # Then, we try and find matching users based on the email / phone number / third party ID.
         users = await self.recipe_implementation.list_users_by_account_info(
             tenant_id=tenant_id,
-            account_info=user.login_methods[0],
+            account_info=AccountInfoInput(
+                email=user.login_methods[0].email,
+                phone_number=user.login_methods[0].phone_number,
+                third_party=user.login_methods[0].third_party,
+                # We don't need to list by (webauthn) credentialId because we are looking for
+                # a user to link to the current recipe user, but any search using the credentialId
+                # of the current user "will identify the same user" which is the current one.
+                webauthn=None,
+            ),
             do_union_of_account_info=True,
             user_context=user_context,
         )
@@ -346,7 +362,15 @@ async def is_sign_in_up_allowed_helper(
 
         users = await self.recipe_implementation.list_users_by_account_info(
             tenant_id=tenant_id,
-            account_info=account_info,
+            account_info=AccountInfoInput(
+                email=account_info.email,
+                phone_number=account_info.phone_number,
+                third_party=account_info.third_party,
+                # We don't need to list by (webauthn) credentialId because we are looking for
+                # a user to link to the current recipe user, but any search using the credentialId
+                # of the current user "will identify the same user" which is the current one.
+                webauthn=None,
+            ),
             do_union_of_account_info=True,
             user_context=user_context,
         )
@@ -548,7 +572,7 @@ async def is_email_change_allowed(
             existing_users_with_new_email = (
                 await self.recipe_implementation.list_users_by_account_info(
                     tenant_id=tenant_id,
-                    account_info=AccountInfo(email=new_email),
+                    account_info=AccountInfoInput(email=new_email),
                     do_union_of_account_info=False,
                     user_context=user_context,
                 )

supertokens_python/recipe/accountlinking/recipe_implementation.py

@@ -19,6 +19,7 @@
 
 from supertokens_python.normalised_url_path import NormalisedURLPath
 from supertokens_python.types import RecipeUserId, User
+from supertokens_python.types.base import AccountInfoInput
 
 from .interfaces import (
     CanCreatePrimaryUserAccountInfoAlreadyAssociatedError,
@@ -39,7 +40,7 @@
     RecipeInterface,
     UnlinkAccountOkResult,
 )
-from .types import AccountInfo, AccountLinkingConfig, RecipeLevelUser
+from .types import AccountLinkingConfig, RecipeLevelUser
 
 if TYPE_CHECKING:
     from supertokens_python.querier import Querier
@@ -327,7 +328,7 @@ async def get_user(
     async def list_users_by_account_info(
         self,
         tenant_id: str,
-        account_info: AccountInfo,
+        account_info: AccountInfoInput,
         do_union_of_account_info: bool,
         user_context: Dict[str, Any],
     ) -> List[User]:
@@ -343,6 +344,9 @@ async def list_users_by_account_info(
             params["thirdPartyId"] = account_info.third_party.id
             params["thirdPartyUserId"] = account_info.third_party.user_id
 
+        if account_info.webauthn:
+            params["webauthnCredentialId"] = account_info.webauthn.credential_id
+
         response = await self.querier.send_get_request(
             NormalisedURLPath(f"/{tenant_id or 'public'}/users/by-accountinfo"),
             params,