fastlifeweb 0.22.1__tar.gz → 0.23.0__tar.gz

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.23.0  - Released on 2024-12-04
+* Update Request type.
+  * Breaking changes: Request[TUser, TRegistry] -> Request[TRegistry, TIdentity, TClaimedIdentity].
+* Update SecurityPolicy, designed for MFA by default.
+  * Breaking changes: new abstract method added. build_authentication_state.
+  * Breaking changes: there is no more get_authenticated_userid method.
+  * The identity method is not abstract anymore, result comes from the build_authentication_state.
+  * New method get_authentication_state, claimed_identity and pre_remember.
+* Add a AbstractNoMFASecurityPolicy that build a AbstractSecurityPolicy without TClaimedIdentity as None.
+* New ACL type added to raise 401 errors due to missing MFA which may not be same url as tu login/password.
+
 ## 0.22.1  - Released on 2024-11-27
 * Improve Request typing
 

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastlifeweb
-Version: 0.22.1
+Version: 0.23.0
 Summary: High-level web framework
 Author-Email: Guillaume Gauvrit <guillaume@gauvr.it>
 License: MIT License

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/pyproject.toml

@@ -13,7 +13,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.22.1"
+version = "0.23.0"
 requires-python = ">=3.11"
 dependencies = [
     "fastapi[standard] >=0.115.0,<1",

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/__init__.py

@@ -27,9 +27,15 @@ from .domain.model.form import FormModel
 from .domain.model.request import GenericRequest
 from .domain.model.security_policy import (
     Allowed,
+    Anonymous,
+    Authenticated,
+    AuthenticationState,
     Denied,
     Forbidden,
     HasPermission,
+    NoMFAAuthenticationState,
+    PendingMFA,
+    PreAuthenticated,
     Unauthenticated,
     Unauthorized,
 )
@@ -37,7 +43,11 @@ from .domain.model.template import JinjaXTemplate
 
 # from .request.form_data import model
 from .service.registry import DefaultRegistry, GenericRegistry, TRegistry, TSettings
-from .service.security_policy import AbstractSecurityPolicy, InsecurePolicy
+from .service.security_policy import (
+    AbstractNoMFASecurityPolicy,
+    AbstractSecurityPolicy,
+    InsecurePolicy,
+)
 from .settings import Settings
 
 __all__ = [
@@ -69,13 +79,20 @@ __all__ = [
     "RedirectResponse",
     # Security
     "AbstractSecurityPolicy",
+    "AbstractNoMFASecurityPolicy",
     "HasPermission",
     "Unauthenticated",
+    "PreAuthenticated",
     "Allowed",
     "Denied",
     "Unauthorized",
     "Forbidden",
     "InsecurePolicy",
+    "Anonymous",
+    "PendingMFA",
+    "Authenticated",
+    "AuthenticationState",
+    "NoMFAAuthenticationState",
     # Template
     "JinjaXTemplate",
     # i18n

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/adapters/fastapi/request.py

@@ -9,18 +9,18 @@ from fastlife.domain.model.request import GenericRequest
 from fastlife.service.registry import DefaultRegistry
 
 
-def get_request(request: FastAPIRequest) -> GenericRequest[Any, Any]:
+def get_request(request: FastAPIRequest) -> GenericRequest[Any, Any, Any]:
     """Return the Fastlife Request object."""
     return request  # type: ignore
 
 
-Request = Annotated[GenericRequest[Any, DefaultRegistry], Depends(get_request)]
+Request = Annotated[GenericRequest[DefaultRegistry, Any, Any], Depends(get_request)]
 """A request that is associated to the default registry."""
 # FastAPI handle its Request objects using a lenient_issubclass,
 # basically a issubclass(Request), does not work with Generic[T].
 
 
-AnyRequest = Annotated[GenericRequest[Any, Any], Depends(get_request)]
+AnyRequest = Annotated[GenericRequest[Any, Any, Any], Depends(get_request)]
 """A request version that is associated to the any registry."""
 
 

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/adapters/fastapi/routing/route.py

@@ -41,7 +41,7 @@ class Route(APIRoute):
         orig_route_handler = super().get_route_handler()
 
         async def route_handler(request: StarletteRequest) -> Response:
-            req = GenericRequest[Any, Any](self._registry, request)
+            req = GenericRequest[Any, Any, Any](self._registry, request)
             return await orig_route_handler(req)
 
         return route_handler

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/config/configurator.py

@@ -144,7 +144,7 @@ class GenericConfigurator(Generic[TRegistry]):
         self._route_prefix: str = ""
         self._routers: dict[str, Router] = defaultdict(Router)
         self._security_policies: dict[
-            str, type[AbstractSecurityPolicy[Any, TRegistry]]
+            str, type[AbstractSecurityPolicy[Any, Any, TRegistry]]
         ] = {}
 
         self._registered_permissions: set[str] = set()
@@ -322,7 +322,7 @@ class GenericConfigurator(Generic[TRegistry]):
         return self
 
     def set_security_policy(
-        self, security_policy: "type[AbstractSecurityPolicy[Any, TRegistry]]"
+        self, security_policy: "type[AbstractSecurityPolicy[TRegistry, Any, Any]]"
     ) -> Self:
         """
         Set a security policy for the application.
@@ -594,7 +594,7 @@ class GenericConfigurator(Generic[TRegistry]):
             # class is wrong.
             # Until we store a security policy per rooter, we rebuild an
             # incomplete request here.
-            req = GenericRequest[Any, DefaultRegistry](self.registry, request)
+            req = GenericRequest[DefaultRegistry, Any, Any](self.registry, request)
             resp = handler(req, exc)
             if isinstance(resp, Response):
                 return resp

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/domain/model/request.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Any, Generic
 from starlette.requests import Request as BaseRequest
 
 from fastlife.domain.model.csrf import CSRFToken, create_csrf_token
-from fastlife.domain.model.security_policy import TUser
+from fastlife.domain.model.security_policy import TClaimedIdentity, TIdentity
 from fastlife.service.registry import TRegistry
 
 if TYPE_CHECKING:
@@ -15,7 +15,7 @@ if TYPE_CHECKING:
     )
 
 
-class GenericRequest(BaseRequest, Generic[TUser, TRegistry]):
+class GenericRequest(BaseRequest, Generic[TRegistry, TIdentity, TClaimedIdentity]):
     """HTTP Request representation."""
 
     registry: TRegistry
@@ -23,7 +23,9 @@ class GenericRequest(BaseRequest, Generic[TUser, TRegistry]):
     locale_name: str
     """Request locale used for the i18n of the response."""
 
-    security_policy: "AbstractSecurityPolicy[TUser, TRegistry] | None"
+    security_policy: (
+        "AbstractSecurityPolicy[TRegistry, TIdentity, TClaimedIdentity] | None"
+    )
     """Request locale used for the i18n of the response."""
 
     renderer_globals: dict[str, Any]

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/domain/model/security_policy.py

@@ -2,7 +2,7 @@
 
 import logging
 from collections.abc import Callable, Coroutine
-from typing import Any, Literal, TypeVar
+from typing import Any, Generic, Literal, TypeVar
 
 from fastapi import HTTPException
 from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
@@ -10,13 +10,62 @@ from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
 CheckPermissionHook = Callable[..., Coroutine[Any, Any, None]] | Callable[..., None]
 CheckPermission = Callable[[str], CheckPermissionHook]
 
-TUser = TypeVar("TUser")
+TClaimedIdentity = TypeVar("TClaimedIdentity")
+TIdentity = TypeVar("TIdentity")
 
 log = logging.getLogger(__name__)
 
 
+class _Anonymous: ...
+
+
+Anonymous = _Anonymous()
+"""
+The user is not authenticated.
+"""
+
+
+class PendingMFA(Generic[TClaimedIdentity]):
+    """
+    The user provided its identity, usually validated with a first factor,
+    such as a password but it has not totally proved its authentication
+    by a second or many other factors of authentication.
+    The type TClaimedIdentity will store the relevant informations during
+    this authentication phase.
+    """
+
+    claimed: TClaimedIdentity | None
+    __match_args__ = ("claimed",)
+
+    def __init__(self, claimed: TClaimedIdentity) -> None:
+        self.claimed = claimed
+
+
+class Authenticated(Generic[TIdentity]):
+    """The identity has been validated."""
+
+    __match_args__ = ("identity",)
+
+    def __init__(self, identity: TIdentity) -> None:
+        self.identity = identity
+
+
+AuthenticationState = (
+    _Anonymous | PendingMFA[TClaimedIdentity] | Authenticated[TIdentity]
+)
+"""
+Type representing the state of an authentication.
+"""
+
+NoMFAAuthenticationState = AuthenticationState[None, TIdentity]
+"""
+Type representing a state of authentication when no multiple factor of authentication
+is involved.
+"""
+
+
 class Unauthorized(HTTPException):
-    """An exception raised to stop a request exectution and return an HTTP Error."""
+    """An exception raised to stop a request execution and return a 401 HTTP Error."""
 
     def __init__(
         self,
@@ -27,8 +76,22 @@ class Unauthorized(HTTPException):
         super().__init__(status_code, detail, headers)
 
 
+class MFARequired(Unauthorized):
+    """
+    An exception raised to stop a request execution and return a 401 HTTP Error for MFA.
+    """
+
+    def __init__(
+        self,
+        status_code: int = HTTP_401_UNAUTHORIZED,
+        detail: str = "MFA Required",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(status_code, detail, headers)
+
+
 class Forbidden(HTTPException):
-    """An exception raised to stop a request exectution and return an HTTP Error."""
+    """An exception raised to stop a request execution and return a 403 HTTP Error."""
 
     def __init__(
         self,
@@ -59,7 +122,7 @@ class HasPermission(int, metaclass=BoolMeta):
     or the frontend may use the information to adapt its interface.
     """
 
-    kind: Literal["allowed", "unauthenticated", "denied"]
+    kind: Literal["allowed", "unauthenticated", "mfa_required", "denied"]
     """
     Identified basic information of the response.
     It distinguished unauthenticated and denied to eventually raised 401 over 403 error.
@@ -96,6 +159,16 @@ class Unauthenticated(HasPermission):
     reason = "Authentication required"
 
 
+class PreAuthenticated(HasPermission):
+    """
+    Represent a permission check result that is not allowed due to
+    missing secondary authentication mechanism.
+    """
+
+    kind = "mfa_required"
+    reason = "MFA required"
+
+
 class Denied(HasPermission):
     """
     Represent a permission check result that is not allowed due to lack of permission.

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/service/check_permission.py

@@ -34,6 +34,8 @@ def check_permission(permission_name: str) -> CheckPermissionHook:
                 return
             case "denied":
                 raise request.security_policy.Forbidden(detail=allowed.reason)
+            case "mfa_required":
+                raise request.security_policy.MFARequired(detail=allowed.reason)
             case "unauthenticated":
                 raise request.security_policy.Unauthorized(detail=allowed.reason)
 

{fastlifeweb-0.22.1 → fastlifeweb-0.23.0}/src/fastlife/service/locale_negociator.py

@@ -10,14 +10,16 @@ LocaleName = str
 
 from fastlife.adapters.fastapi.request import GenericRequest  # coverage: ignore
 
-LocaleNegociator = Callable[[GenericRequest[Any, Any]], LocaleName]  # coverage: ignore
+LocaleNegociator = Callable[
+    [GenericRequest[Any, Any, Any]], LocaleName
+]  # coverage: ignore
 """Interface to implement to negociate a locale"""  # coverage: ignore
 
 
 def default_negociator(settings: Settings) -> LocaleNegociator:
     """The default local negociator return the locale set in the conf."""
 
-    def locale_negociator(request: "GenericRequest[Any, Any]") -> str:
+    def locale_negociator(request: "GenericRequest[Any, Any, Any]") -> str:
         return settings.default_locale
 
     return locale_negociator

fastlifeweb-0.23.0/src/fastlife/service/security_policy.py

@@ -0,0 +1,147 @@
+"""Security policy."""
+
+import abc
+from typing import Annotated, Any, Generic
+
+from fastapi import Depends
+
+from fastlife import GenericRequest, get_request
+from fastlife.domain.model.security_policy import (
+    Allowed,
+    Anonymous,
+    Authenticated,
+    AuthenticationState,
+    Forbidden,
+    HasPermission,
+    MFARequired,
+    PendingMFA,
+    TClaimedIdentity,
+    TIdentity,
+    Unauthorized,
+)
+from fastlife.service.registry import TRegistry
+
+
+class AbstractSecurityPolicy(abc.ABC, Generic[TRegistry, TIdentity, TClaimedIdentity]):
+    """Security policy base class."""
+
+    Forbidden = Forbidden
+    """The exception raised if the user identified is not granted."""
+    Unauthorized = Unauthorized
+    """The exception raised if no user has been identified."""
+    MFARequired = MFARequired
+    """The exception raised if no user has been authenticated using a MFA."""
+
+    request: GenericRequest[TRegistry, TIdentity, TClaimedIdentity]
+    """Request where the security policy is applied."""
+
+    def __init__(
+        self,
+        request: Annotated[
+            GenericRequest[TRegistry, TIdentity, TClaimedIdentity], Depends(get_request)
+        ],
+    ):
+        """
+        Build the security policy.
+
+        When implementing a security policy, multiple parameters can be added
+        to the constructor as FastAPI dependencies, using the `Depends` FastAPI
+        annotation.
+        The security policy is installed has a depenency of the router that hold
+        a route prefix of the application.
+        """
+        self.request = request
+        self.request.security_policy = self  # we do backref to implement has_permission
+        self._authentication_state: (
+            AuthenticationState[TClaimedIdentity, TIdentity] | None
+        ) = None
+
+    async def get_authentication_state(
+        self,
+    ) -> AuthenticationState[TClaimedIdentity, TIdentity]:
+        """
+        Return app-specific user object or None.
+        """
+        if self._authentication_state is None:
+            self._authentication_state = await self.build_authentication_state()
+        return self._authentication_state
+
+    async def claimed_identity(self) -> TClaimedIdentity | None:
+        """
+        Return app-specific user object that pretend to be identified.
+        """
+        auth = await self.get_authentication_state()
+        match auth:
+            case PendingMFA(claimed):
+                return claimed
+            case _:
+                return None
+
+    async def identity(self) -> TIdentity | None:
+        """
+        Return app-specific user object after an mfa authentication or None.
+        """
+        auth = await self.get_authentication_state()
+        match auth:
+            case Authenticated(identity):
+                return identity
+            case _:
+                return None
+
+    @abc.abstractmethod
+    async def build_authentication_state(
+        self,
+    ) -> AuthenticationState[TClaimedIdentity, TIdentity]:
+        """
+        Return the authentication state for the current request.
+        """
+
+    @abc.abstractmethod
+    async def has_permission(
+        self, permission: str
+    ) -> HasPermission | type[HasPermission]:
+        """Allow access to everything if signed in."""
+
+    @abc.abstractmethod
+    async def pre_remember(self, claimed_identity: TClaimedIdentity) -> None:
+        """Save the user identity in the request session."""
+
+    @abc.abstractmethod
+    async def remember(self, identity: TIdentity) -> None:
+        """Save the user identity in the request session."""
+
+    @abc.abstractmethod
+    async def forget(self) -> None:
+        """Destroy the request session."""
+
+
+class AbstractNoMFASecurityPolicy(AbstractSecurityPolicy[TRegistry, TIdentity, None]):
+    async def pre_remember(self, claimed_identity: None) -> None:
+        """Do Nothing."""
+
+
+class InsecurePolicy(AbstractNoMFASecurityPolicy[Any, None]):
+    """
+    An implementation of the security policy made for explicit unsecured access.
+
+    Setting a permission on a view require a security policy, if not set, accessing
+    to a view will raise a RuntimeError. To bypass this error for testing purpose
+    or your own reason, the InsecurePolicy has to be set to the configurator.
+    """
+
+    async def build_authentication_state(
+        self,
+    ) -> AuthenticationState[None, None]:
+        return Anonymous
+
+    async def has_permission(
+        self, permission: str
+    ) -> HasPermission | type[HasPermission]:
+        """Access is allways granted."""
+        return Allowed
+
+    async def remember(self, identity: None) -> None:
+        """Do nothing."""
+
+    async def forget(self) -> None:
+        """Do nothing."""

fastlifeweb-0.22.1/src/fastlife/service/security_policy.py

@@ -1,100 +0,0 @@
-"""Security policy."""
-
-import abc
-from typing import Annotated, Any, Generic
-from uuid import UUID
-
-from fastapi import Depends
-
-from fastlife import GenericRequest, get_request
-from fastlife.domain.model.security_policy import (
-    Allowed,
-    Forbidden,
-    HasPermission,
-    TUser,
-    Unauthorized,
-)
-from fastlife.service.registry import TRegistry
-
-
-class AbstractSecurityPolicy(abc.ABC, Generic[TUser, TRegistry]):
-    """Security policy base class."""
-
-    Forbidden = Forbidden
-    """The exception raised if the user identified is not granted."""
-    Unauthorized = Unauthorized
-    """The exception raised if no user has been identified."""
-
-    request: GenericRequest[TUser, TRegistry]
-    """Request where the security policy is applied."""
-
-    def __init__(
-        self, request: Annotated[GenericRequest[TUser, TRegistry], Depends(get_request)]
-    ):
-        """
-        Build the security policy.
-
-        When implementing a security policy, multiple parameters can be added
-        to the constructor as FastAPI dependencies, using the `Depends` FastAPI
-        annotation.
-        The security policy is installed has a depenency of the router that hold
-        a route prefix of the application.
-        """
-        self.request = request
-        self.request.security_policy = self  # we do backref to implement has_permission
-
-    @abc.abstractmethod
-    async def identity(self) -> TUser | None:
-        """
-        Return app-specific user object or raise an HTTPException.
-        """
-
-    @abc.abstractmethod
-    async def authenticated_userid(self) -> str | UUID | None:
-        """
-        Return app-specific user object or raise an HTTPException.
-        """
-
-    @abc.abstractmethod
-    async def has_permission(
-        self, permission: str
-    ) -> HasPermission | type[HasPermission]:
-        """Allow access to everything if signed in."""
-
-    @abc.abstractmethod
-    async def remember(self, user: TUser) -> None:
-        """Save the user identity in the request session."""
-
-    @abc.abstractmethod
-    async def forget(self) -> None:
-        """Destroy the request session."""
-
-
-class InsecurePolicy(AbstractSecurityPolicy[None, Any]):
-    """
-    An implementation of the security policy made for explicit unsecured access.
-
-    Setting a permission on a view require a security policy, if not set, accessing
-    to a view will raise a RuntimeError. To bypass this error for testing purpose
-    or your own reason, the InsecurePolicy has to be set to the configurator.
-    """
-
-    async def identity(self) -> None:
-        """Nobodies is identified."""
-        return None
-
-    async def authenticated_userid(self) -> str | UUID:
-        """An uuid mades of 0."""
-        return UUID(int=0)
-
-    async def has_permission(
-        self, permission: str
-    ) -> HasPermission | type[HasPermission]:
-        """Access is allways granted."""
-        return Allowed
-
-    async def remember(self, user: None) -> None:
-        """Do nothing."""
-
-    async def forget(self) -> None:
-        """Do nothing."""