fastlifeweb 0.14.0__tar.gz → 0.15.0__tar.gz

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastlifeweb
-Version: 0.14.0
+Version: 0.15.0
 Summary: High-level web framework
 Home-page: https://github.com/mardiros/fastlife
 License: BSD-derived

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.14.0"
+version = "0.15.0"
 
 [tool.poetry.dependencies]
 python = "^3.11"

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/src/fastlife/config/configurator.py

@@ -28,20 +28,22 @@ from fastapi import Response
 from fastapi.params import Depends as DependsType
 from fastapi.staticfiles import StaticFiles
 from fastapi.types import IncEx
-from pydantic import BaseModel, Field
 
+from fastlife.config.openapiextra import OpenApiTag
 from fastlife.middlewares.base import AbstractMiddleware
 from fastlife.request.request import Request
 from fastlife.routing.route import Route
 from fastlife.routing.router import Router
 from fastlife.security.csrf import check_csrf
+from fastlife.services.policy import check_permission
 from fastlife.shared_utils.resolver import resolve
 
 from .settings import Settings
 
 if TYPE_CHECKING:
+    from fastlife.security.policy import AbstractSecurityPolicy  # coverage: ignore
     from fastlife.services.templates import (
-        AbstractTemplateRendererFactory,  # coverage: ignore; coverage: ignore
+        AbstractTemplateRendererFactory,  # coverage: ignore
     )
 
     from .registry import AppRegistry, LocaleNegociator  # coverage: ignore
@@ -58,24 +60,53 @@ class ConfigurationError(Exception):
     """
 
 
-class ExternalDocs(BaseModel):
-    """OpenAPI externalDocs object."""
+def rebuild_router(router: Router) -> Router:
+    """
+    Fix the router.
 
-    description: str
-    """link's description."""
-    url: str
-    """link's URL."""
+    FastAPI routers has dependencies that are injected to routes where they are added.
 
+    It means that if you add a dependencies in the router after the route has
+    been added, then the dependencies is missing in the route added before.
 
-class OpenApiTag(BaseModel):
-    """OpenAPI tag object."""
+    To prenvents issues, we rebuild the router route with the dependency.
 
-    name: str
-    """name of the tag."""
-    description: str
-    """explanation of the tag."""
-    external_docs: ExternalDocs | None = Field(alias="externalDocs", default=None)
-    """external link to the doc."""
+    :param router: the router to rebuild
+    :return: a new router with fixed routes.
+    """
+    if not router.dependencies:
+        return router
+    _router = Router(prefix=router.prefix)
+    _router.dependencies = router.dependencies
+    route: Route
+    for route in router.routes:  # type: ignore
+        dependencies = [
+            dep for dep in route.dependencies if dep not in _router.dependencies
+        ]
+        _router.add_api_route(
+            path=route.path,
+            endpoint=route.endpoint,
+            response_model=route.response_model,
+            status_code=route.status_code,
+            tags=route.tags,
+            dependencies=dependencies,
+            summary=route.summary,
+            description=route.description,
+            response_description=route.response_description,
+            deprecated=route.deprecated,
+            methods=route.methods,
+            operation_id=route.operation_id,
+            response_model_include=route.response_model_include,
+            response_model_exclude=route.response_model_exclude,
+            response_model_by_alias=route.response_model_by_alias,
+            response_model_exclude_unset=route.response_model_exclude_unset,
+            response_model_exclude_defaults=route.response_model_exclude_defaults,
+            response_model_exclude_none=route.response_model_exclude_none,
+            include_in_schema=route.include_in_schema,
+            name=route.name,
+            openapi_extra=route.openapi_extra,
+        )
+    return _router
 
 
 class Configurator:
@@ -107,6 +138,7 @@ class Configurator:
 
         self._route_prefix: str = ""
         self._routers: dict[str, Router] = defaultdict(Router)
+        self._security_policies: dict[str, "type[AbstractSecurityPolicy[Any]]"] = {}
 
         self.scanner = venusian.Scanner(fastlife=self)
         self.include("fastlife.views")
@@ -145,8 +177,6 @@ class Configurator:
             else None,
         )
         app.router.route_class = Route
-        for prefix, router in self._routers.items():
-            app.include_router(router, prefix=prefix)
 
         for middleware_class, options in self.middlewares:
             app.add_middleware(middleware_class, **options)  # type: ignore
@@ -154,6 +184,9 @@ class Configurator:
         for status_code_or_exc, exception_handler in self.exception_handlers:
             app.add_exception_handler(status_code_or_exc, exception_handler)
 
+        for prefix, router in self._routers.items():
+            app.include_router(rebuild_router(router), prefix=prefix)
+
         for route_path, directory, name in self.mounts:
             app.mount(route_path, StaticFiles(directory=directory), name=name)
         return app
@@ -262,6 +295,27 @@ class Configurator:
         self.middlewares.append((middleware_class, options))
         return self
 
+    def set_security_policy(
+        self, security_policy: "type[AbstractSecurityPolicy[Any]]"
+    ) -> Self:
+        """
+        Set a security policy for the application.
+
+        ```{important}
+        The security policy is **per route_prefix**.
+        It means that if the application is splitted via multiple
+        route_prefix using the {meth}`Configurator.include`, they
+        all have a distinct security policy. A secutity policy has
+        to be install by all of those include call.
+
+        :param security_policy: The security policy that will applied for the app
+            portion behind the route prefix.
+        ```
+        """
+        self._security_policies[self._route_prefix] = security_policy
+        self._current_router.dependencies.append(Depends(security_policy))
+        return self
+
     def add_api_route(
         self,
         name: str,
@@ -311,9 +365,7 @@ class Configurator:
         :param path: path of the route, use `{curly_brace}` to inject FastAPI Path
             parameters.
         :param endpoint: the function that will reveive the request.
-        :param permission: a permission to validate by the
-            :attr:`fastlife.config.settings.Settings.check_permission` function.
-
+        :param permission: a permission to validate by the security policy.
         :param methods: restrict route to a list of http methods.
         :param description:OpenAPI description for the route.
         :param summary: OpenAPI summary for the route.
@@ -339,7 +391,7 @@ class Configurator:
         """
         dependencies: list[DependsType] = []
         if permission:
-            dependencies.append(Depends(self.registry.check_permission(permission)))
+            dependencies.append(Depends(check_permission(permission)))
 
         self._current_router.add_api_route(
             path,
@@ -394,15 +446,13 @@ class Configurator:
         :param path: path of the route, use `{curly_brace}` to inject FastAPI Path
             parameters.
         :param endpoint: the function that will reveive the request.
-        :param permission: a permission to validate by the
-            :attr:`fastlife.config.settings.Settings.check_permission` function.
-
+        :param permission: a permission to validate by the security policy.
         :param methods: restrict route to a list of http methods.
         :return: the configurator.
         """
         dependencies: list[DependsType] = []
         if permission:
-            dependencies.append(Depends(self.registry.check_permission(permission)))
+            dependencies.append(Depends(check_permission(permission)))
 
         if template:
 
@@ -459,6 +509,11 @@ class Configurator:
         """
 
         def exception_handler(request: BaseRequest, exc: Exception) -> Any:
+            # FastAPI exception handler does not provide our request object
+            # it seems like it is rebuild from the asgi scope. Even the router
+            # class is wrong.
+            # Until we store a security policy per rooter, we rebuild an
+            # incomplete request here.
             request = Request(self.registry, request)
             resp = handler(request, exc)
             if isinstance(resp, Response):

fastlifeweb-0.15.0/src/fastlife/config/openapiextra.py

@@ -0,0 +1,22 @@
+"""Types for OpenAPI documentation."""
+from pydantic import BaseModel, Field
+
+
+class ExternalDocs(BaseModel):
+    """OpenAPI externalDocs object."""
+
+    description: str
+    """link's description."""
+    url: str
+    """link's URL."""
+
+
+class OpenApiTag(BaseModel):
+    """OpenAPI tag object."""
+
+    name: str
+    """name of the tag."""
+    description: str
+    """explanation of the tag."""
+    external_docs: ExternalDocs | None = Field(alias="externalDocs", default=None)
+    """external link to the doc."""

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/src/fastlife/config/registry.py

@@ -5,9 +5,7 @@ from fastapi import Depends
 from fastapi import Request as FastAPIRequest
 
 from fastlife.request.request import Request
-from fastlife.security.policy import CheckPermission
 from fastlife.services.translations import LocalizerFactory
-from fastlife.shared_utils.resolver import resolve
 
 if TYPE_CHECKING:
     from fastlife.services.templates import (  # coverage: ignore
@@ -34,13 +32,11 @@ class AppRegistry:
 
     settings: Settings
     renderers: Mapping[str, "AbstractTemplateRendererFactory"]
-    check_permission: CheckPermission
     locale_negociator: LocaleNegociator
     localizer: LocalizerFactory
 
     def __init__(self, settings: Settings) -> None:
         self.settings = settings
-        self.check_permission = resolve(settings.check_permission)
         self.locale_negociator = _default_negociator(self.settings)
         self.renderers = {}
         self.localizer = LocalizerFactory()

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/src/fastlife/config/resources.py

@@ -13,11 +13,12 @@ from typing import Any, Callable
 import venusian
 from fastapi.types import IncEx
 
+from fastlife.config.openapiextra import ExternalDocs
+
 from .configurator import (
     VENUSIAN_CATEGORY,
     ConfigurationError,
     Configurator,
-    ExternalDocs,
     OpenApiTag,
 )
 
@@ -143,6 +144,7 @@ def resource(
 
 
 def resource_view(
+    *,
     permission: str | None = None,
     status_code: int | None = None,
     summary: str | None = None,

{fastlifeweb-0.14.0 → fastlifeweb-0.15.0}/src/fastlife/config/settings.py

@@ -106,9 +106,6 @@ class Settings(BaseSettings):
     domain_name: str = Field(default="", title="domain name where the app is served")
     """Domain name whre the app is served."""
 
-    check_permission: str = Field(default="fastlife.security.policy:check_permission")
-    """Handler for checking permission set on any views using the configurator."""
-
     decode_reverse_proxy_headers: bool = Field(default=True)
     """Ensure that the request object has information based on http proxy headers."""
 

fastlifeweb-0.15.0/src/fastlife/request/request.py

@@ -0,0 +1,49 @@
+"""HTTP Request representation in a python object."""
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import Request as FastAPIRequest
+
+if TYPE_CHECKING:
+    from fastlife.config.registry import AppRegistry  # coverage: ignore
+    from fastlife.security.policy import (  # coverage: ignore
+        AbstractSecurityPolicy,
+        HasPermission,
+    )
+
+
+class Request(FastAPIRequest):
+    """HTTP Request representation."""
+
+    registry: "AppRegistry"
+    """Direct access to the application registry."""
+    locale_name: str
+    """Request locale used for the i18n of the response."""
+
+    security_policy: "AbstractSecurityPolicy[Any] | None"
+    """Request locale used for the i18n of the response."""
+
+    def __init__(self, registry: "AppRegistry", request: FastAPIRequest) -> None:
+        super().__init__(request.scope, request.receive)
+        self.registry = registry
+        self.locale_name = registry.locale_negociator(self)
+        self.security_policy = None  # build it from the ? registry
+
+    async def has_permission(
+        self, permission: str
+    ) -> "HasPermission | type[HasPermission]":
+        """
+        A helper to check that a user has the given permission.
+
+        Not that this method does not raised, it return a boolean like object.
+        It allows batch permission checks.
+        You might need to check multiple permissions in different contexts or
+        for different resources before raising an http error.
+        """
+        if self.security_policy is None:
+            raise RuntimeError(
+                f"Request {self.url.path} require a security policy, "
+                "explicit fastlife.security.policy.InsecurePolicy is required."
+            )
+
+        return await self.security_policy.has_permission(permission)

fastlifeweb-0.15.0/src/fastlife/security/policy.py

@@ -0,0 +1,171 @@
+"""Security policy."""
+
+import abc
+import logging
+from typing import Any, Callable, Coroutine, Literal, TypeVar
+from uuid import UUID
+
+from fastapi import HTTPException
+from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
+from typing_extensions import Generic
+
+from fastlife import Request
+
+CheckPermissionHook = Callable[..., Coroutine[Any, Any, None]] | Callable[..., None]
+CheckPermission = Callable[[str], CheckPermissionHook]
+
+TUser = TypeVar("TUser")
+
+log = logging.getLogger(__name__)
+
+
+class Unauthorized(HTTPException):
+    """An exception raised to stop a request exectution and return an HTTP Error."""
+
+    def __init__(
+        self,
+        status_code: int = HTTP_401_UNAUTHORIZED,
+        detail: str = "Unauthorized",
+        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."""
+
+    def __init__(
+        self,
+        status_code: int = HTTP_403_FORBIDDEN,
+        detail: str = "Forbidden",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(status_code, detail, headers)
+
+
+class BoolMeta(type):
+    def __bool__(cls) -> bool:
+        return cls.kind == "allowed"  # type: ignore
+
+    def __repr__(cls) -> str:
+        return cls.reason  # type: ignore
+
+
+class HasPermission(int, metaclass=BoolMeta):
+    kind: Literal["allowed", "unauthenticated", "denied"]
+    reason: str
+
+    def __new__(cls, reason: str) -> "HasPermission":
+        instance = super().__new__(cls)
+        instance.reason = reason
+        return instance
+
+    def __repr__(self) -> str:
+        return self.reason
+
+    def __bool__(self) -> bool:
+        return self.kind == "allowed"
+
+
+class Allowed(HasPermission):
+    """Represent a permission check result that is allowed."""
+
+    kind = "allowed"
+    reason = "Allowed"
+
+
+class Unauthenticated(HasPermission):
+    """
+    Represent a permission check result that is not allowed due to
+    missing authentication mechanism.
+    """
+
+    kind = "unauthenticated"
+    reason = "Authentication required"
+
+
+class Denied(HasPermission):
+    """
+    Represent a permission check result that is not allowed due to lack of permission.
+    """
+
+    kind = "denied"
+    reason = "Access denied to this resource"
+
+
+class AbstractSecurityPolicy(abc.ABC, Generic[TUser]):
+    """Security policy base classe."""
+
+    Forbidden = Forbidden
+    """The exception raised if the user identified is not granted."""
+    Unauthorized = Unauthorized
+    """The exception raised if no user has been identified."""
+
+    def __init__(self, request: 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]):
+    """
+    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."""

fastlifeweb-0.15.0/src/fastlife/services/policy.py

@@ -0,0 +1,39 @@
+"""Security policy."""
+
+from typing import Any, Callable, Coroutine
+
+CheckPermissionHook = Callable[..., Coroutine[Any, Any, None]] | Callable[..., None]
+CheckPermission = Callable[[str], CheckPermissionHook]
+
+
+def check_permission(permission_name: str) -> CheckPermissionHook:
+    """
+    A closure that check that a user as the given permission_name.
+
+    Adding a permission on the route requires that a security policy has been
+    added using the method
+    {meth}`fastlife.config.configurator.Configurator.set_security_policy`
+
+    :param permission_name: a permission name set in a view to check access.
+    :return: a function that raise http exceptions or any configured exception here.
+    """
+    # the check_permission is called by the configurator
+    # and the request is exposed in the public module creating a circular dependency.
+    from fastlife import Request  # a type must be resolved to inject a dependency.
+
+    async def depencency_injection(request: Request) -> None:
+        if request.security_policy is None:
+            raise RuntimeError(
+                f"Request {request.url.path} require a security policy, "
+                "explicit fastlife.security.policy.InsecurePolicy is required"
+            )
+        allowed = await request.security_policy.has_permission(permission_name)
+        match allowed.kind:
+            case "allowed":
+                return
+            case "denied":
+                raise request.security_policy.Forbidden(detail=allowed.reason)
+            case "unauthenticated":
+                raise request.security_policy.Unauthorized(detail=allowed.reason)
+
+    return depencency_injection

fastlifeweb-0.14.0/src/fastlife/request/request.py

@@ -1,22 +0,0 @@
-"""HTTP Request representation in a python object."""
-
-from typing import TYPE_CHECKING
-
-from fastapi import Request as FastAPIRequest
-
-if TYPE_CHECKING:
-    from fastlife.config.registry import AppRegistry  # coverage: ignore
-
-
-class Request(FastAPIRequest):
-    """HTTP Request representation."""
-
-    registry: "AppRegistry"
-    """Direct access to the application registry."""
-    locale_name: str
-    """Request locale used for the i18n of the response."""
-
-    def __init__(self, registry: "AppRegistry", request: FastAPIRequest) -> None:
-        super().__init__(request.scope, request.receive)
-        self.registry = registry
-        self.locale_name = registry.locale_negociator(self)

fastlifeweb-0.14.0/src/fastlife/security/policy.py

@@ -1,26 +0,0 @@
-"""Security policy."""
-from typing import Any, Callable, Coroutine
-
-CheckPermissionHook = Callable[..., Coroutine[Any, Any, None]] | Callable[..., None]
-CheckPermission = Callable[[str], CheckPermissionHook]
-
-
-def check_permission(permission_name: str) -> CheckPermissionHook:
-    """
-    A closure that check that a user as the given permission_name.
-
-    This method has to be overriden using the setting
-    :attr:`fastlife.config.settings.Settings.check_permission` to implement it.
-
-    When the check permission is properly set in the settings., the hook is called
-    for every route added with a permission keyword.
-    {meth}`fastlife.config.configurator.Configurator.add_route`
-
-    :param permission_name: a permission name set in a view to check access.
-    :return: a function that raise http exceptions or any configured exception here.
-    """
-
-    def depencency_injection() -> None:
-        ...
-
-    return depencency_injection