amsdal 0.4.10__cp311-cp311-macosx_10_9_universal2.whl → 0.5.29__cp311-cp311-macosx_10_9_universal2.whl

amsdal/contrib/auth/models/mfa_device.py

@@ -0,0 +1,86 @@
+from datetime import UTC
+from datetime import datetime
+from typing import ClassVar
+
+from amsdal_models.classes.model import Model
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+from amsdal.contrib.auth.utils.mfa import DeviceType
+
+
+def _now_utc() -> datetime:
+    """Return current UTC datetime."""
+    return datetime.now(tz=UTC)
+
+
+class MFADevice(Model):
+    """
+    Base model for Multi-Factor Authentication devices.
+
+    This model serves as the base class for all MFA device types (TOTP, Backup Codes, Email, SMS).
+    Each device is associated with a user and must be confirmed before it can be used for authentication.
+
+    Attributes:
+        user_email (str): Email of the user who owns this device (reference to User).
+        device_type (str): Type of MFA device ('totp', 'backup_code', 'email', 'sms').
+        name (str): User-friendly name for the device.
+        is_active (bool): Whether the device is currently active and can be used.
+        confirmed (bool): Whether the device has been verified during setup.
+        created_at (datetime): When the device was created.
+        last_used_at (datetime | None): When the device was last used for authentication.
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+
+    user_email: str = Field(title='User Email')
+    device_type: DeviceType | None = Field(default=None, title='Device Type')
+    name: str = Field(title='Device Name')
+    is_active: bool = Field(True, title='Is Active')
+    confirmed: bool = Field(False, title='Confirmed')
+    created_at: datetime = Field(default_factory=_now_utc, title='Created At')
+    last_used_at: datetime | None = Field(None, title='Last Used At')
+
+    @property
+    def display_name(self) -> str:
+        """
+        Returns the display name of the device.
+
+        Returns:
+            str: The device name and type.
+        """
+        return f'{self.name} ({self.device_type})'
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __str__(self) -> str:
+        return f'MFADevice(name={self.name}, type={self.device_type}, user={self.user_email})'
+
+    def has_object_permission(self, user: 'User', action: str) -> bool:  # type: ignore # noqa: F821
+        """
+        Check if a user has permission to perform an action on this device.
+
+        Users can only manage their own devices. Admins with wildcard permissions
+        can manage all devices.
+
+        Args:
+            user: The user requesting the action.
+            action: The action being requested (read, update, delete, etc.).
+
+        Returns:
+            bool: True if the user has permission, False otherwise.
+        """
+        # Users can only manage their own devices
+        if self.user_email == user.email:
+            return True
+
+        # Check if user has admin permissions (wildcard model permissions)
+        if user.permissions:
+            for permission in user.permissions:
+                if permission.model == '*' and permission.action in ('*', action):
+                    return True
+                if permission.model == 'MFADevice' and permission.action in ('*', action):
+                    return True
+
+        return False

amsdal/contrib/auth/models/sms_device.py

@@ -0,0 +1,113 @@
+from datetime import datetime
+from typing import Any
+from typing import ClassVar
+
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+from amsdal.contrib.auth.models.mfa_device import MFADevice
+from amsdal.contrib.auth.utils.mfa import DeviceType
+
+
+class SMSDevice(MFADevice):
+    """
+    SMS-based MFA device model (future implementation).
+
+    This model represents an SMS-based MFA method where a temporary code is sent
+    to the user's phone number for authentication.
+
+    Note:
+        This is a placeholder for future SMS support. Full implementation requires
+        integration with an SMS service provider (e.g., Twilio, AWS SNS).
+
+    Attributes:
+        phone_number (str): The phone number to send codes to.
+        code (str | None): Temporary MFA code (stored temporarily, expires after use).
+        code_expires_at (datetime | None): When the current code expires.
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+
+    phone_number: str = Field(title='Phone Number')
+    code: str | None = Field(None, title='Current Code')
+    code_expires_at: datetime | None = Field(None, title='Code Expiration')
+
+    def post_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:
+        """
+        Post-initializes an SMS MFA device by setting the device type.
+
+        Args:
+            is_new_object (bool): Indicates if the object is new.
+            kwargs (dict[str, Any]): The keyword arguments containing device details.
+        """
+        super().post_init(is_new_object=is_new_object, kwargs=kwargs)
+        self.device_type = DeviceType.SMS
+
+    def generate_and_send_code(self) -> str:
+        """
+        Generate a new MFA code and send it via SMS.
+
+        This method generates a random numeric code, sets its expiration time,
+        and sends it to the configured phone number.
+
+        Returns:
+            str: The generated code (for testing purposes).
+
+        Raises:
+            NotImplementedError: This feature requires SMS service integration.
+
+        Note:
+            Full implementation requires integration with an SMS provider.
+            Example providers: Twilio, AWS SNS, MessageBird, etc.
+        """
+        from amsdal.contrib.auth.utils.mfa import generate_email_mfa_code
+        from amsdal.contrib.auth.utils.mfa import get_email_code_expiration
+
+        # Generate new code
+        self.code = generate_email_mfa_code()
+        self.code_expires_at = get_email_code_expiration()
+
+        # TODO: Implement SMS sending with your SMS provider
+        # Example with Twilio:
+        # from twilio.rest import Client
+        # client = Client(account_sid, auth_token)
+        # client.messages.create(
+        #     to=self.phone_number,
+        #     from_=your_twilio_number,
+        #     body=f'Your MFA code is: {self.code}'
+        # )
+
+        msg = 'SMS MFA is not yet implemented. Please integrate with an SMS service provider (e.g., Twilio, AWS SNS).'
+        raise NotImplementedError(msg)
+
+    def verify_code(self, code: str) -> bool:
+        """
+        Verify an SMS MFA code.
+
+        Args:
+            code (str): The code to verify.
+
+        Returns:
+            bool: True if the code is valid and not expired, False otherwise.
+        """
+        from amsdal.contrib.auth.utils.mfa import is_email_code_valid
+
+        # Check if code matches
+        if not self.code or self.code != code:
+            return False
+
+        # Check if code is expired
+        if not self.code_expires_at or not is_email_code_valid(self.code_expires_at):
+            return False
+
+        return True
+
+    def clear_code(self) -> None:
+        """
+        Clear the current code after successful use or expiration.
+        """
+        self.code = None
+        self.code_expires_at = None
+
+    def __str__(self) -> str:
+        return f'SMSDevice(name={self.name}, phone={self.phone_number}, user={self.user_email})'

amsdal/contrib/auth/models/totp_device.py

@@ -0,0 +1,58 @@
+from typing import Any
+from typing import ClassVar
+
+from amsdal_utils.models.enums import ModuleType
+from pydantic.fields import Field
+
+from amsdal.contrib.auth.models.mfa_device import MFADevice
+from amsdal.contrib.auth.utils.mfa import DeviceType
+
+
+class TOTPDevice(MFADevice):
+    """
+    Time-based One-Time Password (TOTP) device model.
+
+    This model represents an authenticator app device (e.g., Google Authenticator, Authy)
+    that generates time-based one-time passwords following RFC 6238.
+
+    Attributes:
+        secret (str): The encrypted TOTP secret key shared with the authenticator app.
+        qr_code_url (str | None): URL for the QR code used during device setup.
+        digits (int): Number of digits in the generated code (default: 6).
+        step (int): Time step in seconds for code generation (default: 30).
+    """
+
+    __module_type__: ClassVar[ModuleType] = ModuleType.CONTRIB
+
+    secret: str = Field(title='TOTP Secret')
+    qr_code_url: str | None = Field(None, title='QR Code URL')
+    digits: int = Field(6, title='Code Digits')
+    step: int = Field(30, title='Time Step (seconds)')
+
+    def post_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:
+        """
+        Post-initializes a TOTP device by setting the device type.
+
+        Args:
+            is_new_object (bool): Indicates if the object is new.
+            kwargs (dict[str, Any]): The keyword arguments containing device details.
+        """
+        super().post_init(is_new_object=is_new_object, kwargs=kwargs)
+        self.device_type = DeviceType.TOTP
+
+    def verify_code(self, code: str) -> bool:
+        """
+        Verify a TOTP code against this device's secret.
+
+        Args:
+            code (str): The TOTP code to verify.
+
+        Returns:
+            bool: True if the code is valid, False otherwise.
+        """
+        from amsdal.contrib.auth.utils.mfa import verify_totp_code
+
+        return verify_totp_code(self.secret, code, self.digits, self.step)
+
+    def __str__(self) -> str:
+        return f'TOTPDevice(name={self.name}, user={self.user_email})'

amsdal/contrib/auth/models/user.py

@@ -47,6 +47,56 @@ class User(Model):
         """
         return self.email
 
+    @property
+    def requires_mfa(self) -> bool:
+        """
+        Determines if MFA is required for this user.
+
+        This checks both the per-user override (mfa_required) and the global
+        REQUIRE_MFA_BY_DEFAULT setting.
+
+        Returns:
+            bool: True if MFA is required, False otherwise.
+        """
+        from amsdal.contrib.auth.settings import auth_settings
+
+        # Fall back to global setting
+        return auth_settings.REQUIRE_MFA_BY_DEFAULT
+
+    async def ahas_valid_mfa_device(self) -> bool:
+        """
+        Check if the user has at least one confirmed and active MFA device.
+
+        Returns:
+            bool: True if the user has a valid MFA device, False otherwise.
+        """
+        from amsdal.contrib.auth.utils.mfa import aget_active_user_devices
+
+        devices = await aget_active_user_devices(self)
+        for device_list in devices.values():
+            if device_list:
+                return True
+        return False
+
+    def has_valid_mfa_device(self) -> bool:
+        """
+        Check if the user has at least one confirmed and active MFA device (sync version).
+
+        Returns:
+            bool: True if the user has a valid MFA device, False otherwise.
+        """
+        from amsdal.contrib.auth.utils.mfa import get_active_user_devices
+
+        devices = get_active_user_devices(self)
+        for device_list in devices.values():
+            if device_list:
+                return True
+        return False
+
+    def pre_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:  # noqa: ARG002
+        if 'email' in kwargs and isinstance(kwargs['email'], str):
+            kwargs['email'] = kwargs['email'].lower()
+
     def post_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:
         """
         Post-initializes a user object by validating email and password, and hashing the password.

amsdal/contrib/auth/services/__init__.py

@@ -0,0 +1 @@
+"""MFA device management services."""