alpha-python 0.5.0__tar.gz → 0.5.1__tar.gz

{alpha_python-0.5.0/src/alpha_python.egg-info → alpha_python-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-python
-Version: 0.5.0
+Version: 0.5.1
 Summary: Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction.
 Author-email: Bart Reijling <bart@reijling.eu>
 Requires-Python: >=3.11

{alpha_python-0.5.0 → alpha_python-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alpha-python"
-version = "0.5.0"
+version = "0.5.1"
 description = "Alpha is intended to be the first dependency you need to add to your Python application. It is a Python library which contains standard building blocks that can be used in applications that are used as APIs and/or make use of database interaction."
 readme = "README.md"
 authors = [

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/__init__.py

@@ -49,6 +49,7 @@ from alpha.repositories.models.repository_model import RepositoryModel
 from alpha.repositories.rest_api_repository import RestApiRepository
 from alpha.repositories.sql_alchemy_repository import SqlAlchemyRepository
 from alpha.services.authentication_service import AuthenticationService
+from alpha.services.user_lifecycle_management import UserLifecycleManagement
 from alpha.utils.is_attrs import is_attrs
 from alpha.utils.is_pydantic import is_pydantic
 from alpha.utils.logging_configurator import (
@@ -56,6 +57,7 @@ from alpha.utils.logging_configurator import (
     GunicornLogger,
 )
 from alpha.utils.logging_level_checker import logging_level_checker
+from alpha.utils.request_headers import Headers
 from alpha.utils.response_object import create_response_object
 from alpha.utils.verify_identity import verify_identity
 from alpha.utils.version_checker import minor_version_gte
@@ -126,11 +128,13 @@ __all__ = [
     "RestApiRepository",
     "SqlAlchemyRepository",
     "AuthenticationService",
+    "UserLifecycleManagement",
     "is_attrs",
     "is_pydantic",
     "LoggingConfigurator",
     "GunicornLogger",
     "logging_level_checker",
+    "Headers",
     "create_response_object",
     "verify_identity",
     "minor_version_gte",

alpha_python-0.5.1/src/alpha/domain/models/user.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum, auto
+from typing import Self, Sequence, cast
+from uuid import UUID
+
+from alpha.domain.models.base_model import BaseDomainModel, DomainModel
+from alpha.domain.models.group import Group
+from alpha.domain.models.life_cycle_base import LifeCycleBase
+
+from alpha.providers.models.identity import Identity
+
+
+class Role(Enum):
+    """Defines user roles with varying levels of permissions. The roles are
+    ordered from highest to lowest permissions. The comparison methods allow
+    for easy comparison of roles based on their hierarchy. The roles are
+    ordered on a scale from highest to lowest permissions.
+
+    Typical permissions are as follows:
+    - CREATE: Permission to create new content or data, but not modify existing
+    content.
+    - READ: Permission to read content or data.
+    - UPDATE: Permission to modify existing content or data, but not create new
+    content.
+    - DELETE: Permission to delete content or data.
+    - MANAGE_USERS: Permission to manage user accounts and permissions.
+    - MANAGE_SETTINGS: Permission to manage system settings and configurations.
+    - ALL: Permission to perform all actions, including user management and
+    system settings.
+
+    Roles:
+    - ADMIN: Role with permissions to manage users, content, and system
+    settings. Typically has the ALL permissions.
+    - SUPERUSER: Role with all permissions, including system settings and user
+    management. Typically has the ALL permissions, but may be used to denote a
+    special type of admin user with additional privileges or responsibilities.
+    - OWNER: Role with permissions to manage their own resources and users, but
+    not system settings. Typically has permissions similar to ADMIN, but
+    limited to their own scope of resources.
+    - MODERATOR: Role with permissions to manage content and users, but not
+    system settings. Typically has permissions to UPDATE and DELETE content,
+    and MANAGE_USERS, but not MANAGE_SETTINGS.
+    - EDITOR: Role with permissions to create and edit content, but not manage
+    users or settings. Typically has permissions to CREATE, READ, UPDATE, and
+    DELETE content, but not MANAGE_USERS or MANAGE_SETTINGS.
+    - USER: Default role with standard permissions. Typically has permissions
+    to CREATE, READ, and UPDATE their own content, but not DELETE content or
+    manage users or settings.
+    - VIEWER: Typical read-only role with limited permissions. Typically has
+    permission to READ content, but not CREATE, UPDATE, DELETE, or manage users
+    or settings.
+    """
+
+    ADMIN = auto()
+    SUPERUSER = auto()
+    OWNER = auto()
+    MODERATOR = auto()
+    EDITOR = auto()
+    USER = auto()
+    VIEWER = auto()
+
+    def __lt__(self, obj: Self) -> bool:
+        return self.value < obj.value
+
+    def __le__(self, obj: Self) -> bool:
+        return self.value <= obj.value
+
+    def __gt__(self, obj: Self) -> bool:
+        return self.value > obj.value
+
+    def __ge__(self, obj: Self) -> bool:
+        return self.value >= obj.value
+
+
+@dataclass(kw_only=True)
+class User(LifeCycleBase, BaseDomainModel):
+    id: UUID | int | str | None = None
+    username: str | None = None
+    password: str | None = None
+    role: str | Role | None = None
+    email: str | None = None
+    phone: str | None = None
+    display_name: str | None = None
+    permissions: Sequence[str] | None = None
+    groups: Sequence[str | Group] | None = None
+    is_active: bool = True
+    admin: bool = False
+
+    @classmethod
+    def from_identity(cls, identity: Identity) -> Self:
+        """Create a User instance from an Identity instance.
+
+        Parameters
+        ----------
+        identity
+            Identity object to convert.
+
+        Returns
+        -------
+            User instance created from the Identity.
+        """
+        return cls(
+            id=identity.subject,
+            username=identity.username,
+            email=identity.email,
+            display_name=identity.display_name,
+        )
+
+    def update(self, obj: DomainModel) -> DomainModel:
+        """Update the User instance with data from another User instance.
+
+        Parameters
+        ----------
+        obj
+            User object to update from.
+        """
+        if not isinstance(obj, User):
+            raise TypeError("User.update expects a User instance.")
+
+        self.username = obj.username
+        self.email = obj.email
+        self.phone = obj.phone
+        self.display_name = obj.display_name
+        self.permissions = obj.permissions
+        self.groups = obj.groups
+        self.modified_at = datetime.now(tz=timezone.utc)
+        self.is_active = obj.is_active
+        self.admin = obj.admin
+        return cast(DomainModel, self)

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/factories/jwt_factory.py

@@ -18,8 +18,12 @@ class JWTFactory:
         lifetime_hours: str | None = "12",
         issuer: str = "http://localhost",
         jwt_algorithm: str = "HS256",
+        options: dict[str, Any] | None = None,
     ) -> None:
-        """Initialize the JWTFactory.
+        """Initialize the JWTFactory. This method sets up the necessary
+        configuration for creating and validating JWT tokens. It requires a
+        secret key for signing the tokens and allows optional configuration
+        for token lifetime, issuer, algorithm, and decoding options.
 
         Parameters
         ----------
@@ -31,6 +35,10 @@ class JWTFactory:
             The issuer of the JWT, by default "http://localhost"
         jwt_algorithm, optional
             The algorithm used to sign the JWT, by default "HS256"
+        options, optional
+            A dictionary of options to customize the decoding behavior, by
+            default None. If not provided, it defaults to requiring standard
+            claims and verifying the signature.
 
         Raises
         ------
@@ -46,6 +54,10 @@ class JWTFactory:
         self.JWT_ISSUER = issuer
         self.JWT_ALGORITHM = jwt_algorithm
         self.JWT_LIFETIME_SECONDS = 3600 * int(lifetime_hours)
+        self.JWT_OPTIONS = options or {
+            "require": ["exp", "iat", "nbf", "iss", "sub"],
+            "verify_signature": True,
+        }
 
     def create(
         self,
@@ -93,13 +105,19 @@ class JWTFactory:
         )
         return token
 
-    def validate(self, token: str) -> bool:
-        """Validate a JWT token.
+    def validate(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> bool:
+        """Validate a JWT token. This method checks the token's signature,
+        expiration, and issuer. If the token is invalid, it raises an
+        appropriate exception. If the token is valid, it returns True.
 
         Parameters
         ----------
         token
             The JWT token to be validated.
+        options
+            A dictionary of options to customize the decoding behavior.
 
         Returns
         -------
@@ -112,15 +130,62 @@ class JWTFactory:
             InvalidSignatureException
                 If the token signature is invalid.
         """
+        if self._decode(token, options):
+            return True
+        return False
+
+    def get_payload(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Retrieve the payload from a JWT token. This method does not perform
+        validation of the token by default. It simply decodes the token and
+        extracts the payload.
+
+        If the `options` parameter is provided, it will be passed to the
+        `jwt.decode` function. This allows customization of the decoding
+        behavior, such as enabling or disabling signature verification.
+
+        Parameters
+        ----------
+        token
+            The JWT token from which to extract the payload.
+        options
+            A dictionary of options to customize the decoding behavior.
+
+        Returns
+        -------
+            A dictionary containing the payload data extracted from the token.
+        """
+        decoded = self._decode(token, options)
+        return decoded.get("payload", {})
+
+    def _decode(
+        self, token: str, options: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Decode a JWT token without performing validation. This method is
+        intended for internal use and should not be exposed as part of the
+        public API.
+
+        Parameters
+        ----------
+        token
+            The JWT token to be decoded.
+        options
+            A dictionary of options to customize the decoding behavior.
+
+        Returns
+        -------
+            A dictionary containing the decoded token data.
+        """
         try:
-            jwt.decode(
+            decoded: dict[str, Any] = jwt.decode(
                 jwt=token,
                 key=self.JWT_SECRET,
                 algorithms=[self.JWT_ALGORITHM],
                 issuer=self.JWT_ISSUER,
-                verify=True,
+                options=options or self.JWT_OPTIONS,
             )
-            return True
+            return decoded
         except jwt.ExpiredSignatureError as e:
             raise exceptions.TokenExpiredException(str(e)) from e
         except jwt.InvalidSignatureError as e:
@@ -129,23 +194,3 @@ class JWTFactory:
             raise exceptions.InvalidTokenException(
                 f"Token is invalid: {str(e)}"
             ) from e
-
-    def get_payload(self, token: str) -> dict[str, Any]:
-        """Retrieve the payload from a JWT token.
-
-        Parameters
-        ----------
-        token
-            The JWT token from which to extract the payload.
-
-        Returns
-        -------
-            A dictionary containing the payload data extracted from the token.
-        """
-        decoded: dict[str, Any] = jwt.decode(
-            jwt=token,
-            key=self.JWT_SECRET,
-            algorithms=[self.JWT_ALGORITHM],
-            issuer=self.JWT_ISSUER,
-        )
-        return decoded.get("payload", {})

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/factories/password_factory.py

@@ -11,6 +11,7 @@ from alpha import exceptions
 class PasswordFactory:
     """This class provides methods for hashing and verifying passwords using
     the argon2 library. It includes the following methods:
+
     - hash_password: Hashes a given password and returns the hashed value as a
         hexadecimal string.
     - verify_password: Verifies a given password against a provided hash and

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/handlers/templates/python-flask/controller.mustache

@@ -11,6 +11,7 @@ from typing import List
 from alpha.factories.request_factory import RequestFactory
 from alpha.factories.response_factory import ResponseFactory
 from alpha.utils.response_object import create_response_object
+from alpha.utils.request_headers import Headers
 from alpha.utils.verify_identity import verify_identity
 from alpha.utils._http_codes import http_codes_{{#languageCode}}{{languageCode}}{{/languageCode}}{{^languageCode}}en{{/languageCode}} as http_codes
 from alpha.exceptions import (
@@ -144,28 +145,36 @@ def {{operationId}}(
             {{response}}
         {{/isContainer}}
     {{/allParams}}
+    headers = Headers.from_headers(connexion.request.headers)
+
+    auth_token = headers.auth_token if headers.has_auth_token else None
+    refresh_token = headers.refresh_token
+    api_key = headers.api_key
 
-    {{#authMethods}}{{#isBasicBearer}}
-    if "Authorization" in connexion.request.headers:
-        token = connexion.request.headers["Authorization"].split(" ").pop()
-    else:
-        token = None
-    {{/isBasicBearer}}{{/authMethods}}
     try:
         # Objects used for authorization
         roles=[{{#vendorExtensions.x-alpha-verify-roles}}"{{.}}",{{/vendorExtensions.x-alpha-verify-roles}}]
         groups=[{{#vendorExtensions.x-alpha-verify-groups}}"{{.}}",{{/vendorExtensions.x-alpha-verify-groups}}]
         permissions=[{{#vendorExtensions.x-alpha-verify-permissions}}"{{.}}",{{/vendorExtensions.x-alpha-verify-permissions}}]
-        {{#authMethods}}{{#isBasicBearer}}
-        # validate token
-        if token_factory.validate(token):
-            identity = token_factory.get_payload(token)
-            verify_identity(identity,
-                roles=roles,
-                groups=groups,
-                permissions=permissions,
-            )
-        {{/isBasicBearer}}{{/authMethods}}
+        {{#authMethods}}
+        {{#isBasicBearer}}
+        # Validate authentication token
+        if auth_token is None:
+            raise UnauthorizedException('Missing authentication token')
+        
+        token_factory.validate(auth_token)
+
+        identity = token_factory.get_payload(auth_token)
+        verify_identity(identity,
+            roles=roles,
+            groups=groups,
+            permissions=permissions,
+        )
+        {{/isBasicBearer}}
+        {{#isApiKey}}
+        # This needs to be replaced by code to authenticate with an API key
+        {{/isApiKey}}
+        {{/authMethods}}
         # Call method or use variable
         {{#vendorExtensions.x-alpha-request-factory}}
             {{#vendorExtensions.x-alpha-service-name}}
@@ -180,35 +189,34 @@ def {{operationId}}(
                 {{/vendorExtensions.x-alpha-service-method}}
             {{/vendorExtensions.x-alpha-service-name}}
             {{^vendorExtensions.x-alpha-service-name}}
-                {{#vendorExtensions.x-alpha-method}}
-        result = {{vendorExtensions.x-alpha-method}}
-                {{/vendorExtensions.x-alpha-method}}
+                {{#vendorExtensions.x-alpha-custom-response}}
+        result = {{vendorExtensions.x-alpha-custom-response}}
+                {{/vendorExtensions.x-alpha-custom-response}}
             {{/vendorExtensions.x-alpha-service-name}}
         {{/vendorExtensions.x-alpha-request-factory}}
         {{^vendorExtensions.x-alpha-request-factory}}
             {{^vendorExtensions.x-alpha-service-name}}
-                {{^vendorExtensions.x-alpha-method}}
+                {{^vendorExtensions.x-alpha-custom-response}}
         raise ServerErrorException('Missing x-alpha-service-name in API specification')
-                {{/vendorExtensions.x-alpha-method}}
+                {{/vendorExtensions.x-alpha-custom-response}}
                 {{^vendorExtensions.x-alpha-service-method}}
-                    {{^vendorExtensions.x-alpha-method}}
+                    {{^vendorExtensions.x-alpha-custom-response}}
         raise ServerErrorException('Missing x-alpha-service-method in API specification')
-                    {{/vendorExtensions.x-alpha-method}}
+                    {{/vendorExtensions.x-alpha-custom-response}}
                 {{/vendorExtensions.x-alpha-service-method}}
             {{/vendorExtensions.x-alpha-service-name}}
             {{#vendorExtensions.x-alpha-service-name}}
                 {{#vendorExtensions.x-alpha-service-method}}
         result = {{vendorExtensions.x-alpha-service-name}}.{{vendorExtensions.x-alpha-service-method}}(
             {{#allParams}}{{paramName}}={{paramName}},{{/allParams}}
-            {{#vendorExtensions.x-alpha-service-additional-parameters}}{{.}}={{.}},
-            {{/vendorExtensions.x-alpha-service-additional-parameters}}
+            {{#vendorExtensions.x-alpha-service-additional-parameters}}{{.}}={{.}},{{/vendorExtensions.x-alpha-service-additional-parameters}}
         )
                 {{/vendorExtensions.x-alpha-service-method}}
             {{/vendorExtensions.x-alpha-service-name}}
             {{^vendorExtensions.x-alpha-service-name}}
-                {{#vendorExtensions.x-alpha-method}}
-        result = {{vendorExtensions.x-alpha-method}}
-                {{/vendorExtensions.x-alpha-method}}
+                {{#vendorExtensions.x-alpha-custom-response}}
+        result = {{vendorExtensions.x-alpha-custom-response}}
+                {{/vendorExtensions.x-alpha-custom-response}}
             {{/vendorExtensions.x-alpha-service-name}}
         {{/vendorExtensions.x-alpha-request-factory}}
     

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/interfaces/token_factory.py

@@ -48,13 +48,18 @@ class TokenFactory(Protocol):
         """
         ...
 
-    def get_payload(self, token: str) -> dict[str, str]:
+    def get_payload(
+        self, token: str, options: dict[str, bool] | None
+    ) -> dict[str, str]:
         """Retrieve the payload from an authentication token.
 
         Parameters
         ----------
         token
             The authentication token from which to extract the payload.
+        options
+            A dictionary of options to customize the decoding behavior, such as
+            enabling or disabling signature verification.
 
         Returns
         -------

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/providers/models/identity.py

@@ -123,7 +123,7 @@ class Identity:
     username: str | None
     email: str | None
     display_name: str | None
-    groups: Sequence[str]
+    groups: Sequence[str | Group]
     permissions: Sequence[str]
     claims: Mapping[str, Any]
     issued_at: datetime

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/repositories/models/repository_model.py

@@ -30,5 +30,5 @@ class RepositoryModel(Generic[DomainModel]):
     name: str
     repository: Callable[..., object]
     default_model: type[DomainModel]
-    interface: object | None
+    interface: object | None = None
     additional_config: dict[str, object] | None = None

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/services/__init__.py

@@ -1,5 +1,7 @@
 from alpha.services.authentication_service import AuthenticationService
+from alpha.services.user_lifecycle_management import UserLifecycleManagement
 
 __all__ = [
     "AuthenticationService",
+    "UserLifecycleManagement",
 ]

{alpha_python-0.5.0 → alpha_python-0.5.1}/src/alpha/services/authentication_service.py

@@ -43,8 +43,8 @@ class AuthenticationService:
         refresh_token_max_age: int = 3600 * 24 * 7,
         merge_with_database_users: bool = False,
         merge_with_database_groups: bool = False,
-        user_id_attribute: str = "username",
-        group_id_attribute: str = "name",
+        user_username_attribute: str = "username",
+        group_name_attribute: str = "name",
         uow: UnitOfWork | None = None,
         users_repository_name: str = "users",
         groups_repository_name: str = "groups",
@@ -106,10 +106,10 @@ class AuthenticationService:
         merge_with_database_groups, optional
             Whether to merge identity data with database group data,
             by default False
-        user_id_attribute, optional
+        user_username_attribute, optional
             Attribute name in the user database to use as the unique
             identifier, by default "username"
-        group_id_attribute, optional
+        group_name_attribute, optional
             Attribute name in the group database to use as the unique
             identifier, by default "name"
         uow, optional
@@ -176,8 +176,8 @@ class AuthenticationService:
         self._refresh_token_max_age = refresh_token_max_age
         self._merge_with_database_users = merge_with_database_users
         self._merge_with_database_groups = merge_with_database_groups
-        self._user_id_attribute = user_id_attribute
-        self._group_id_attribute = group_id_attribute
+        self._user_username_attribute = user_username_attribute
+        self._group_name_attribute = group_name_attribute
         self.uow = uow
         self._users_repository_name = users_repository_name
         self._groups_repository_name = groups_repository_name
@@ -368,8 +368,14 @@ class AuthenticationService:
                     "configured, cannot retrieve identity from auth token."
                 )
             try:
+                # Attempt to retrieve the identity from the auth token without
+                # validating the token, since it may be expired. The payload
+                # should still be retrievable if the token is expired, as long
+                # as the signature is valid. If the signature is invalid, an
+                # exception will be raised and caught, resulting in the
+                # identity remaining None.
                 payload = self._identity_provider.token_factory.get_payload(
-                    token=auth_token
+                    token=auth_token, options={"verify_exp": False}
                 )
                 identity = Identity.from_dict(payload)
             except Exception:
@@ -469,8 +475,8 @@ class AuthenticationService:
             )
 
             user = users.get_by_id(
-                value=getattr(identity, self._user_id_attribute),
-                attr=self._user_id_attribute,
+                value=getattr(identity, self._user_username_attribute),
+                attr=self._user_username_attribute,
             )
             if user:
                 identity.update_from_user(user)
@@ -502,18 +508,23 @@ class AuthenticationService:
             self._raise_no_uow()
 
         with self.uow:
-            groups: SqlRepository[Group] = getattr(
+            groups_repo: SqlRepository[Group] = getattr(
                 self.uow, self._groups_repository_name
             )
 
+            groups = list(identity.groups)
+            for i, group in enumerate(groups):
+                if isinstance(group, Group):
+                    groups[i] = getattr(group, self._group_name_attribute)
+
             filters = [
                 SearchFilter(
-                    field=self._group_id_attribute,
+                    field=self._group_name_attribute,
                     op=Operator.IN,
-                    value=identity.groups,
+                    value=groups,
                 )
             ]
-            user_groups = groups.select(filters=filters)
+            user_groups = groups_repo.select(filters=filters)
             identity.update_from_groups(user_groups)
 
         return identity