Implement new change password and email methods

Author: frankie567

fief_client/__init__.py

@@ -6,6 +6,7 @@
     FiefAccessTokenInvalid,
     FiefAccessTokenMissingPermission,
     FiefAccessTokenMissingScope,
+    FiefACR,
     FiefAsync,
     FiefError,
     FiefIdTokenInvalid,
@@ -18,6 +19,7 @@
 
 __all__ = [
     "Fief",
+    "FiefACR",
     "FiefAsync",
     "FiefTokenResponse",
     "FiefAccessTokenInfo",

fief_client/client.py

@@ -1,6 +1,7 @@
 import contextlib
 import json
 import uuid
+from enum import Enum
 from typing import Any, Dict, List, Mapping, Optional, Tuple, TypedDict, Union
 from urllib.parse import urlencode
 
@@ -13,6 +14,17 @@
 HTTPXClient = Union[httpx.Client, httpx.AsyncClient]
 
 
+class FiefACR(str, Enum):
+    """
+    List of defined Authentication Context Class Reference.
+    """
+
+    LEVEL_ZERO = "0"
+    """Level 0. No authentication was performed, a previous session was used."""
+    LEVEL_ONE = "1"
+    """Level 1. Password authentication was performed."""
+
+
 class FiefTokenResponse(TypedDict):
     """
     Typed dictionary containing the tokens and related information returned by Fief after a successful authentication.
@@ -40,6 +52,7 @@ class FiefAccessTokenInfo(TypedDict):
     {
         "id": "aeeb8bfa-e8f4-4724-9427-c3d5af66190e",
         "scope": ["openid", "required_scope"],
+        "acr": "1",
         "permissions": ["castles:read", "castles:create", "castles:update", "castles:delete"],
         "access_token": "ACCESS_TOKEN",
     }
@@ -50,6 +63,8 @@ class FiefAccessTokenInfo(TypedDict):
     """ID of the user."""
     scope: List[str]
     """List of granted scopes for this access token."""
+    acr: FiefACR
+    """Level of Authentication Context class Reference."""
     permissions: List[str]
     """List of [granted permissions](https://docs.fief.dev/getting-started/access-control/) for this user."""
     access_token: str
@@ -259,6 +274,7 @@ def _validate_access_token(
             return {
                 "id": uuid.UUID(claims["sub"]),
                 "scope": access_token_scope,
+                "acr": claims["acr"],
                 "permissions": permissions,
                 "access_token": access_token,
             }
@@ -367,6 +383,51 @@ def _get_update_profile_request(
             json=data,
         )
 
+    def _get_change_password_request(
+        self,
+        client: HTTPXClient,
+        *,
+        endpoint: str,
+        access_token: str,
+        new_password: str,
+    ) -> httpx.Request:
+        return client.build_request(
+            "PATCH",
+            endpoint,
+            headers={"Authorization": f"Bearer {access_token}"},
+            json={"password": new_password},
+        )
+
+    def _get_email_change_request(
+        self,
+        client: HTTPXClient,
+        *,
+        endpoint: str,
+        access_token: str,
+        email: str,
+    ) -> httpx.Request:
+        return client.build_request(
+            "PATCH",
+            endpoint,
+            headers={"Authorization": f"Bearer {access_token}"},
+            json={"email": email},
+        )
+
+    def _get_email_verify_request(
+        self,
+        client: HTTPXClient,
+        *,
+        endpoint: str,
+        access_token: str,
+        code: str,
+    ) -> httpx.Request:
+        return client.build_request(
+            "PATCH",
+            endpoint,
+            headers={"Authorization": f"Bearer {access_token}"},
+            json={"code": code},
+        )
+
     def _handle_request_error(self, response: httpx.Response):
         if response.is_error:
             raise FiefRequestError(response.status_code, response.text)
@@ -594,34 +655,115 @@ def update_profile(self, access_token: str, data: Dict[str, Any]) -> FiefUserInf
         :param access_token: A valid access token.
         :param data: A dictionary containing the data to update.
 
-        **Example: Update email address**
+        **Example: Update user field**
+
+        To update [user field](https://docs.fief.dev/getting-started/user-fields/) values, you need to nest them into a `fields` dictionary, indexed by their slug.
 
         ```py
-        userinfo = fief.update_profile("ACCESS_TOKEN", { "email": "anne@nantes.city" })
+        userinfo = fief.update_profile("ACCESS_TOKEN", { "fields": { "first_name": "Anne" } })
         ```
+        """
+        update_profile_endpoint = f"{self.base_url}/api/profile"
 
-        **Example: Update password**
+        with self._get_httpx_client() as client:
+            request = self._get_update_profile_request(
+                client,
+                endpoint=update_profile_endpoint,
+                access_token=access_token,
+                data=data,
+            )
+            response = client.send(request)
+
+            self._handle_request_error(response)
+
+            return response.json()
+
+    def change_password(self, access_token: str, new_password: str) -> FiefUserInfo:
+        """
+        Change the user password with the Fief API using a valid access token.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param new_password: The new password.
+
+        **Example**
 
         ```py
-        userinfo = fief.update_profile("ACCESS_TOKEN", { "password": "herminetincture" })
+        userinfo = fief.change_password("ACCESS_TOKEN", "herminetincture")
         ```
+        """
+        change_password_profile_endpoint = f"{self.base_url}/api/password"
 
-        **Example: Update user field**
+        with self._get_httpx_client() as client:
+            request = self._get_change_password_request(
+                client,
+                endpoint=change_password_profile_endpoint,
+                access_token=access_token,
+                new_password=new_password,
+            )
+            response = client.send(request)
 
-        To update [user field](https://docs.fief.dev/getting-started/user-fields/) values, you need to nest them into a `fields` dictionary, indexed by their slug.
+            self._handle_request_error(response)
+
+            return response.json()
+
+    def email_change(self, access_token: str, email: str) -> FiefUserInfo:
+        """
+        Request an email change with the Fief API using a valid access token.
+
+        The user will receive a verification code on this new email address.
+        It shall be used with the method `email_verify` to complete the modification.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param email: The new email address.
+
+        **Example**
 
         ```py
-        userinfo = fief.update_profile("ACCESS_TOKEN", { "fields": { "first_name": "Anne" } })
+        userinfo = fief.email_change("ACCESS_TOKEN", "anne@nantes.city")
         ```
         """
-        update_profile_endpoint = f"{self.base_url}/api/profile"
+        email_change_endpoint = f"{self.base_url}/api/email/change"
 
         with self._get_httpx_client() as client:
-            request = self._get_update_profile_request(
+            request = self._get_email_change_request(
                 client,
-                endpoint=update_profile_endpoint,
+                endpoint=email_change_endpoint,
                 access_token=access_token,
-                data=data,
+                email=email,
+            )
+            response = client.send(request)
+
+            self._handle_request_error(response)
+
+            return response.json()
+
+    def email_verify(self, access_token: str, code: str) -> FiefUserInfo:
+        """
+        Verify the user email with the Fief API using a valid access token and verification code.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param code: The verification code received by email.
+
+        **Example**
+
+        ```py
+        userinfo = fief.email_verify("ACCESS_TOKEN", "ABCDE")
+        ```
+        """
+        email_verify_endpoint = f"{self.base_url}/api/email/verify"
+
+        with self._get_httpx_client() as client:
+            request = self._get_email_verify_request(
+                client,
+                endpoint=email_verify_endpoint,
+                access_token=access_token,
+                code=code,
             )
             response = client.send(request)
 
@@ -924,34 +1066,117 @@ async def update_profile(
         :param access_token: A valid access token.
         :param data: A dictionary containing the data to update.
 
-        **Example: Update email address**
+        **Example: Update user field**
+
+        To update [user field](https://docs.fief.dev/getting-started/user-fields/) values, you need to nest them into a `fields` dictionary, indexed by their slug.
 
         ```py
-        userinfo = await fief.update_profile("ACCESS_TOKEN", { "email": "anne@nantes.city" })
+        userinfo = await fief.update_profile("ACCESS_TOKEN", { "fields": { "first_name": "Anne" } })
         ```
+        """
+        update_profile_endpoint = f"{self.base_url}/api/profile"
+
+        async with self._get_httpx_client() as client:
+            request = self._get_update_profile_request(
+                client,
+                endpoint=update_profile_endpoint,
+                access_token=access_token,
+                data=data,
+            )
+            response = await client.send(request)
+
+            self._handle_request_error(response)
+
+            return response.json()
+
+    async def change_password(
+        self, access_token: str, new_password: str
+    ) -> FiefUserInfo:
+        """
+        Change the user password with the Fief API using a valid access token.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param new_password: The new password.
 
-        **Example: Update password**
+        **Example**
 
         ```py
-        userinfo = await fief.update_profile("ACCESS_TOKEN", { "password": "herminetincture" })
+        userinfo = await fief.change_password("ACCESS_TOKEN", "herminetincture")
         ```
+        """
+        change_password_profile_endpoint = f"{self.base_url}/api/password"
 
-        **Example: Update user field**
+        async with self._get_httpx_client() as client:
+            request = self._get_change_password_request(
+                client,
+                endpoint=change_password_profile_endpoint,
+                access_token=access_token,
+                new_password=new_password,
+            )
+            response = await client.send(request)
 
-        To update [user field](https://docs.fief.dev/getting-started/user-fields/) values, you need to nest them into a `fields` dictionary, indexed by their slug.
+            self._handle_request_error(response)
+
+            return response.json()
+
+    async def email_change(self, access_token: str, email: str) -> FiefUserInfo:
+        """
+        Request an email change with the Fief API using a valid access token.
+
+        The user will receive a verification code on this new email address.
+        It shall be used with the method `email_verify` to complete the modification.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param email: The new email address.
+
+        **Example**
 
         ```py
-        userinfo = await fief.update_profile("ACCESS_TOKEN", { "fields": { "first_name": "Anne" } })
+        userinfo = await fief.email_change("ACCESS_TOKEN", "anne@nantes.city")
         ```
         """
-        update_profile_endpoint = f"{self.base_url}/api/profile"
+        email_change_endpoint = f"{self.base_url}/api/email/change"
 
         async with self._get_httpx_client() as client:
-            request = self._get_update_profile_request(
+            request = self._get_email_change_request(
                 client,
-                endpoint=update_profile_endpoint,
+                endpoint=email_change_endpoint,
                 access_token=access_token,
-                data=data,
+                email=email,
+            )
+            response = await client.send(request)
+
+            self._handle_request_error(response)
+
+            return response.json()
+
+    async def email_verify(self, access_token: str, code: str) -> FiefUserInfo:
+        """
+        Verify the user email with the Fief API using a valid access token and verification code.
+
+        **An access token with an ACR of at least level 1 is required.**
+
+        :param access_token: A valid access token.
+        :param code: The verification code received by email.
+
+        **Example**
+
+        ```py
+        userinfo = fief.email_verify("ACCESS_TOKEN", "ABCDE")
+        ```
+        """
+        email_verify_endpoint = f"{self.base_url}/api/email/verify"
+
+        async with self._get_httpx_client() as client:
+            request = self._get_email_verify_request(
+                client,
+                endpoint=email_verify_endpoint,
+                access_token=access_token,
+                code=code,
             )
             response = await client.send(request)