fastapi-factory-utilities 0.4.0__py3-none-any.whl → 0.8.3__py3-none-any.whl

fastapi_factory_utilities/core/security/jwt/objects.py

@@ -0,0 +1,107 @@
+"""Provides the JWT bearer token objects."""
+
+import datetime
+from typing import Annotated, Any, ClassVar
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from .types import OAuth2Audience, OAuth2Issuer, OAuth2Scope, OAuth2Subject
+
+
+def validate_string_list_field(value: Any) -> list[str]:
+    """Validate a string list field.
+
+    Accepts either a space-separated string or a list of strings.
+    Converts all values to lowercase strings.
+
+    Args:
+        value: Either a string (space-separated) or a list of strings.
+
+    Returns:
+        A list of lowercase strings.
+
+    Raises:
+        ValueError: If the value is not a string or list, or if the resulting list is empty.
+    """
+    cleaned_value: list[str]
+    if isinstance(value, str):
+        cleaned_value = value.split(sep=" ")
+    elif isinstance(value, list):
+        cleaned_value = [str(item) for item in value if item is not None]
+    else:
+        raise ValueError(f"Invalid value type: expected str or list, got {type(value).__name__}")
+    cleaned_value = [item.lower() for item in cleaned_value if item.strip()]
+    if len(cleaned_value) == 0:
+        raise ValueError("Invalid value: empty list after processing")
+    return cleaned_value
+
+
+def validate_timestamp_field(value: Any) -> datetime.datetime:
+    """Validate a timestamp field.
+
+    Accepts either a Unix timestamp (int or string) or a datetime object.
+    Converts timestamps to UTC datetime objects.
+
+    Args:
+        value: Either a Unix timestamp (int or string) or a datetime object.
+
+    Returns:
+        A datetime object in UTC timezone.
+
+    Raises:
+        ValueError: If the value cannot be converted to a datetime.
+    """
+    if isinstance(value, datetime.datetime):
+        return value
+    if isinstance(value, str):
+        try:
+            value = int(value)
+        except ValueError as e:
+            raise ValueError(f"Invalid timestamp string: {value}") from e
+    if isinstance(value, int):
+        try:
+            return datetime.datetime.fromtimestamp(value, tz=datetime.UTC)
+        except (ValueError, OSError) as e:
+            raise ValueError(f"Invalid timestamp value: {value}") from e
+    raise ValueError(f"Invalid value type: expected int, str, or datetime, got {type(value).__name__}")
+
+
+class JWTPayload(BaseModel):
+    """JWT bearer token payload.
+
+    Represents a decoded JWT bearer token with OAuth2 claims.
+    All fields are required and validated according to OAuth2/JWT standards.
+
+    Attributes:
+        scope: List of OAuth2 scopes granted by the token.
+        aud: List of audiences (intended recipients) of the token.
+        iss: The issuer of the JWT token.
+        exp: The expiration date/time of the JWT token (UTC).
+        iat: The issued at date/time of the JWT token (UTC).
+        nbf: The not before date/time of the JWT token (UTC).
+        sub: The subject (user identifier) of the JWT token.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="ignore",
+        frozen=True,
+    )
+
+    scope: Annotated[list[OAuth2Scope], BeforeValidator(validate_string_list_field)] = Field(
+        description="The scope of the JWT token."
+    )
+    aud: Annotated[list[OAuth2Audience], BeforeValidator(validate_string_list_field)] = Field(
+        description="The audiences of the JWT token."
+    )
+    iss: OAuth2Issuer = Field(description="The issuer of the JWT token.")
+    exp: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The expiration date of the JWT token."
+    )
+    iat: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The issued at date of the JWT token."
+    )
+    nbf: Annotated[datetime.datetime, BeforeValidator(validate_timestamp_field)] = Field(
+        description="The not before date of the JWT token."
+    )
+    sub: OAuth2Subject = Field(description="The subject of the JWT token.")

fastapi_factory_utilities/core/security/jwt/services.py

@@ -0,0 +1,176 @@
+"""Provides the JWT bearer authentication service."""
+
+from http import HTTPStatus
+from typing import Generic, TypeVar
+
+from fastapi import HTTPException, Request
+
+from fastapi_factory_utilities.core.security.abstracts import AuthenticationAbstract
+
+from .configs import JWTBearerAuthenticationConfig
+from .decoders import JWTBearerTokenDecoder, JWTBearerTokenDecoderAbstract
+from .exceptions import InvalidJWTError, InvalidJWTPayploadError, MissingJWTCredentialsError, NotVerifiedJWTError
+from .objects import JWTPayload
+from .stores import JWKStoreAbstract
+from .types import JWTToken
+from .verifiers import JWTNoneVerifier, JWTVerifierAbstract
+
+JWTBearerPayloadGeneric = TypeVar("JWTBearerPayloadGeneric", bound=JWTPayload)
+
+
+class JWTAuthenticationServiceAbstract(AuthenticationAbstract, Generic[JWTBearerPayloadGeneric]):
+    """JWT authentication service.
+
+    This service is the orchestrator for the JWT bearer authentication.
+    """
+
+    def __init__(
+        self,
+        jwt_bearer_authentication_config: JWTBearerAuthenticationConfig,
+        jwt_verifier: JWTVerifierAbstract[JWTBearerPayloadGeneric],
+        jwt_decoder: JWTBearerTokenDecoderAbstract[JWTBearerPayloadGeneric],
+        raise_exception: bool = True,
+    ) -> None:
+        """Initialize the JWT bearer authentication service.
+
+        Args:
+            jwt_bearer_authentication_config (JWTBearerAuthenticationConfig): The JWT bearer authentication
+            configuration.
+            jwt_verifier (JWTVerifierAbstract): The JWT bearer token verifier.
+            jwt_decoder (JWTBearerTokenDecoderAbstract[JWTBearerPayloadGeneric]): The JWT bearer token decoder.
+            raise_exception (bool, optional): Whether to raise an exception or return None. Defaults to True.
+        """
+        # Configuration and Behavior
+        self._jwt_bearer_authentication_config: JWTBearerAuthenticationConfig = jwt_bearer_authentication_config
+        self._jwt_verifier: JWTVerifierAbstract[JWTBearerPayloadGeneric] = jwt_verifier
+        self._jwt_decoder: JWTBearerTokenDecoderAbstract[JWTBearerPayloadGeneric] = jwt_decoder
+        # Runtime variables
+        self._jwt: JWTToken | None = None
+        self._jwt_payload: JWTBearerPayloadGeneric | None = None
+        super().__init__(raise_exception=raise_exception)
+
+    @property
+    def verifier(self) -> JWTVerifierAbstract[JWTBearerPayloadGeneric]:
+        """Get the JWT bearer token verifier.
+
+        Returns:
+            JWTVerifierAbstract[JWTBearerPayloadGeneric]: The JWT bearer token verifier.
+        """
+        return self._jwt_verifier
+
+    @property
+    def decoder(self) -> JWTBearerTokenDecoderAbstract[JWTBearerPayloadGeneric]:
+        """Get the JWT bearer token decoder.
+
+        Returns:
+            JWTBearerTokenDecoderAbstract[JWTBearerPayloadGeneric]: The JWT bearer token decoder.
+        """
+        return self._jwt_decoder
+
+    @classmethod
+    def extract_authorization_header_from_request(cls, request: Request) -> str:
+        """Extract the authorization header from the request.
+
+        Args:
+            request (Request): The request object.
+
+        Returns:
+            str: The authorization header.
+
+        Raises:
+            MissingJWTCredentialsError: If the authorization header is missing.
+        """
+        authorization_header: str | None = request.headers.get("Authorization", None)
+        if not authorization_header:
+            raise MissingJWTCredentialsError(message="Missing Credentials")
+        return authorization_header
+
+    @classmethod
+    def extract_bearer_token_from_authorization_header(cls, authorization_header: str) -> JWTToken:
+        """Extract the bearer token from the authorization header.
+
+        Args:
+            authorization_header (str): The authorization header.
+
+        Returns:
+            JWTToken: The bearer token.
+
+        Raises:
+            InvalidJWTError: If the authorization header is invalid.
+        """
+        if not authorization_header.startswith("Bearer "):
+            raise InvalidJWTError(message="Invalid Credentials")
+        return JWTToken(authorization_header.split(sep=" ")[1])
+
+    @property
+    def payload(self) -> JWTBearerPayloadGeneric | None:
+        """Get the JWT bearer payload.
+
+        Returns:
+            JWTBearerPayloadGeneric | None: The JWT bearer payload, or None if not authenticated yet.
+        """
+        return self._jwt_payload
+
+    async def authenticate(self, request: Request) -> None:
+        """Authenticate the JWT bearer token.
+
+        Args:
+            request (Request): The request object.
+
+        Returns:
+            None: If the authentication is successful or not raise_exception is False.
+
+        Raises:
+            MissingJWTCredentialsError: If the authorization header is missing.
+            InvalidJWTError: If the authorization header is invalid.
+            InvalidJWTPayploadError: If the JWT bearer token payload is invalid.
+            NotVerifiedJWTError: If the JWT bearer token is not verified.
+        """
+        authorization_header: str
+        try:
+            authorization_header = self.extract_authorization_header_from_request(request=request)
+            self._jwt = self.extract_bearer_token_from_authorization_header(authorization_header=authorization_header)
+        except (MissingJWTCredentialsError, InvalidJWTError) as e:
+            return self.raise_exception(HTTPException(status_code=HTTPStatus.UNAUTHORIZED, detail=str(e)))
+
+        try:
+            self._jwt_payload = await self._jwt_decoder.decode_payload(jwt_token=self._jwt)
+        except (InvalidJWTError, InvalidJWTPayploadError) as e:
+            return self.raise_exception(HTTPException(status_code=HTTPStatus.FORBIDDEN, detail=str(e)))
+
+        try:
+            await self._jwt_verifier.verify(jwt_token=self._jwt, jwt_payload=self._jwt_payload)
+        except NotVerifiedJWTError as e:
+            return self.raise_exception(HTTPException(status_code=HTTPStatus.FORBIDDEN, detail=str(e)))
+
+        return
+
+
+class JWTAuthenticationService(JWTAuthenticationServiceAbstract[JWTPayload]):
+    """JWT bearer authentication service."""
+
+    def __init__(
+        self,
+        jwt_bearer_authentication_config: JWTBearerAuthenticationConfig,
+        jwks_store: JWKStoreAbstract,
+        raise_exception: bool = True,
+    ) -> None:
+        """Initialize the JWT bearer authentication service.
+
+        Don't enforce the public_key from configuration, for the developper to
+        provide it through the dependency injection freely from any source.
+
+        Args:
+            jwt_bearer_authentication_config (JWTBearerAuthenticationConfig): The JWT bearer authentication
+            configuration.
+            jwks_store (JWKStoreAbstract): The JWKS store.
+            raise_exception (bool, optional): Whether to raise an exception or return None. Defaults to True.
+        """
+        super().__init__(
+            jwt_bearer_authentication_config=jwt_bearer_authentication_config,
+            jwt_verifier=JWTNoneVerifier(),
+            jwt_decoder=JWTBearerTokenDecoder(
+                jwt_bearer_authentication_config=jwt_bearer_authentication_config, jwks_store=jwks_store
+            ),
+            raise_exception=raise_exception,
+        )

fastapi_factory_utilities/core/security/jwt/stores.py

@@ -0,0 +1,43 @@
+"""Provides the JWK stores."""
+
+from abc import ABC, abstractmethod
+from asyncio import Lock
+
+from jwt.api_jwk import PyJWK, PyJWKSet
+
+
+class JWKStoreAbstract(ABC):
+    """JWK store abstract class."""
+
+    async def get_jwk(self, kid: str) -> PyJWK:
+        """Get the JWK from the store."""
+        return (await self.get_jwks())[kid]
+
+    @abstractmethod
+    async def get_jwks(self) -> PyJWKSet:
+        """Get the JWKS from the store."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def store_jwks(self, jwks: PyJWKSet) -> None:
+        """Store the JWKS in the store."""
+        raise NotImplementedError()
+
+
+class JWKStoreMemory(JWKStoreAbstract):
+    """JWK store in memory. Concurrent safe."""
+
+    def __init__(self) -> None:
+        """Initialize the JWK store in memory."""
+        self._jwks: PyJWKSet = PyJWKSet([])
+        self._lock: Lock = Lock()
+
+    async def get_jwks(self) -> PyJWKSet:
+        """Get the JWKS from the store."""
+        async with self._lock:
+            return self._jwks
+
+    async def store_jwks(self, jwks: PyJWKSet) -> None:
+        """Store the JWKS in the store."""
+        async with self._lock:
+            self._jwks = jwks

fastapi_factory_utilities/core/security/jwt/types.py

@@ -0,0 +1,9 @@
+"""Provides the JWT bearer token types."""
+
+from typing import NewType
+
+JWTToken = NewType("JWTToken", str)
+OAuth2Scope = NewType("OAuth2Scope", str)
+OAuth2Audience = NewType("OAuth2Audience", str)
+OAuth2Issuer = NewType("OAuth2Issuer", str)
+OAuth2Subject = NewType("OAuth2Subject", str)

fastapi_factory_utilities/core/security/jwt/verifiers.py

@@ -0,0 +1,46 @@
+"""Provides the JWT bearer token validator."""
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from .objects import JWTPayload
+from .types import JWTToken
+
+JWTBearerPayloadGeneric = TypeVar("JWTBearerPayloadGeneric", bound=JWTPayload)
+
+
+class JWTVerifierAbstract(ABC, Generic[JWTBearerPayloadGeneric]):
+    """JWT verifier."""
+
+    @abstractmethod
+    async def verify(
+        self,
+        jwt_token: JWTToken,
+        jwt_payload: JWTBearerPayloadGeneric,
+    ) -> None:
+        """Verify the JWT bearer token.
+
+        Args:
+            jwt_token (JWTToken): The JWT bearer token.
+            jwt_payload (JWTBearerPayloadGeneric): The JWT bearer payload.
+
+        Raises:
+            NotVerifiedJWTError: If the JWT bearer token is not verified.
+        """
+        raise NotImplementedError()
+
+
+class JWTNoneVerifier(JWTVerifierAbstract[JWTPayload]):
+    """JWT none verifier."""
+
+    async def verify(self, jwt_token: JWTToken, jwt_payload: JWTPayload) -> None:
+        """Verify the JWT bearer token.
+
+        Args:
+            jwt_token (JWTToken): The JWT bearer token.
+            jwt_payload (JWTBearerPayload): The JWT bearer payload.
+
+        Raises:
+            NotVerifiedJWTError: If the JWT bearer token is not verified.
+        """
+        return

fastapi_factory_utilities/core/security/kratos.py

@@ -1,41 +1,37 @@
 """Provide Kratos Session and Identity classes."""
 
-from enum import StrEnum
-from typing import Annotated
+from http import HTTPStatus
 
-from fastapi import Depends, HTTPException, Request
+from fastapi import HTTPException, Request
 
+from fastapi_factory_utilities.core.security.abstracts import AuthenticationAbstract
 from fastapi_factory_utilities.core.services.kratos import (
     KratosOperationError,
     KratosService,
     KratosSessionInvalidError,
     KratosSessionObject,
-    depends_kratos_service,
 )
 
 
-class KratosSessionAuthenticationErrors(StrEnum):
-    """Kratos Session Authentication Errors."""
-
-    MISSING_CREDENTIALS = "Missing Credentials"
-    INVALID_CREDENTIALS = "Invalid Credentials"
-    INTERNAL_SERVER_ERROR = "Internal Server Error"
-
-
-class KratosSessionAuthentication:
+class KratosSessionAuthenticationService(AuthenticationAbstract):
     """Kratos Session class."""
 
     DEFAULT_COOKIE_NAME: str = "ory_kratos_session"
 
-    def __init__(self, cookie_name: str = DEFAULT_COOKIE_NAME, raise_exception: bool = True) -> None:
+    def __init__(
+        self, kratos_service: KratosService, cookie_name: str = DEFAULT_COOKIE_NAME, raise_exception: bool = True
+    ) -> None:
         """Initialize the KratosSessionAuthentication class.
 
         Args:
-            cookie_name (str): Name of the cookie to extract the session
-            raise_exception (bool): Whether to raise an exception or return None
+            kratos_service (KratosService): Kratos service object.
+            cookie_name (str): Name of the cookie to extract the session.
+            raise_exception (bool): Whether to raise an exception or return None.
         """
+        self._kratos_service: KratosService = kratos_service
         self._cookie_name: str = cookie_name
-        self._raise_exception: bool = raise_exception
+        self._session: KratosSessionObject
+        super().__init__(raise_exception=raise_exception)
 
     def _extract_cookie(self, request: Request) -> str | None:
         """Extract the cookie from the request.
@@ -51,9 +47,16 @@ class KratosSessionAuthentication:
         """
         return request.cookies.get(self._cookie_name, None)
 
-    async def __call__(
-        self, request: Request, kratos_service: Annotated[KratosService, Depends(depends_kratos_service)]
-    ) -> KratosSessionObject | KratosSessionAuthenticationErrors:
+    @property
+    def session(self) -> KratosSessionObject:
+        """Get the Kratos session.
+
+        Returns:
+            KratosSessionObject: Kratos session object.
+        """
+        return self._session
+
+    async def authenticate(self, request: Request) -> None:
         """Extract the Kratos session from the request.
 
         Args:
@@ -61,38 +64,35 @@ class KratosSessionAuthentication:
             kratos_service (KratosService): Kratos service object.
 
         Returns:
-            KratosSessionObject | KratosSessionAuthenticationErrors: Kratos session object or error.
+            None: If the authentication is successful or not raise_exception is False.
 
         Raises:
             HTTPException: If the session is invalid and raise_exception is True.
         """
         cookie: str | None = self._extract_cookie(request)
         if not cookie:
-            if self._raise_exception:
-                raise HTTPException(
-                    status_code=401,
-                    detail=KratosSessionAuthenticationErrors.MISSING_CREDENTIALS,
+            return self.raise_exception(
+                HTTPException(
+                    status_code=HTTPStatus.UNAUTHORIZED,
+                    detail="Missing Credentials",
                 )
-            else:
-                return KratosSessionAuthenticationErrors.MISSING_CREDENTIALS
+            )
 
         try:
-            session: KratosSessionObject = await kratos_service.whoami(cookie_value=cookie)
-        except KratosSessionInvalidError as e:
-            if self._raise_exception:
-                raise HTTPException(
-                    status_code=401,
+            self._session = await self._kratos_service.whoami(cookie_value=cookie)
+        except KratosSessionInvalidError:
+            return self.raise_exception(
+                HTTPException(
+                    status_code=HTTPStatus.UNAUTHORIZED,
                     detail="Invalid Credentials",
-                ) from e
-            else:
-                return KratosSessionAuthenticationErrors.INVALID_CREDENTIALS
-        except KratosOperationError as e:
-            if self._raise_exception:
-                raise HTTPException(
-                    status_code=500,
+                )
+            )
+        except KratosOperationError:
+            return self.raise_exception(
+                HTTPException(
+                    status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
                     detail="Internal Server Error",
-                ) from e
-            else:
-                return KratosSessionAuthenticationErrors.INTERNAL_SERVER_ERROR
+                )
+            )
 
-        return session
+        return

fastapi_factory_utilities/core/services/hydra/__init__.py

@@ -2,12 +2,19 @@
 
 from .exceptions import HydraOperationError, HydraTokenInvalidError
 from .objects import HydraTokenIntrospectObject
-from .services import HydraService, depends_hydra_service
+from .services import (
+    HydraIntrospectService,
+    HydraOAuth2ClientCredentialsService,
+    depends_hydra_introspect_service,
+    depends_hydra_oauth2_client_credentials_service,
+)
 
 __all__: list[str] = [
+    "HydraIntrospectService",
+    "HydraOAuth2ClientCredentialsService",
     "HydraOperationError",
-    "HydraService",
     "HydraTokenIntrospectObject",
     "HydraTokenInvalidError",
-    "depends_hydra_service",
+    "depends_hydra_introspect_service",
+    "depends_hydra_oauth2_client_credentials_service",
 ]