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

amsdal/contrib/auth/services/totp_service.pyi

@@ -0,0 +1,158 @@
+from amsdal.contrib.auth.errors import InvalidMFACodeError as InvalidMFACodeError, MFADeviceNotFoundError as MFADeviceNotFoundError, MFASetupError as MFASetupError, PermissionDeniedError as PermissionDeniedError, UserNotFoundError as UserNotFoundError
+from amsdal.contrib.auth.models.totp_device import TOTPDevice as TOTPDevice
+from amsdal.contrib.auth.models.user import User as User
+from amsdal.contrib.auth.settings import auth_settings as auth_settings
+from amsdal.contrib.auth.utils.mfa import generate_qr_code_url as generate_qr_code_url, generate_totp_secret as generate_totp_secret
+from amsdal_data.transactions.decorators import async_transaction, transaction
+
+class TOTPService:
+    """Service for TOTP device two-step enrollment flow."""
+    @classmethod
+    def _is_admin(cls, user: User) -> bool:
+        """
+        Check if user has admin permissions (wildcard or MFADevice-specific).
+
+        Args:
+            user: The user to check.
+
+        Returns:
+            bool: True if user has admin permissions, False otherwise.
+        """
+    @classmethod
+    def _check_permission(cls, current_user: User, target_user_email: str, action: str) -> None:
+        """
+        Check if current_user has permission for action on target_user.
+
+        Args:
+            current_user: The authenticated user making the request.
+            target_user_email: Email of the user being targeted.
+            action: The action being performed.
+
+        Raises:
+            PermissionDeniedError: If user lacks permission.
+        """
+    @classmethod
+    async def _acheck_permission(cls, current_user: User, target_user_email: str, action: str) -> None:
+        """
+        Async version of _check_permission.
+
+        Args:
+            current_user: The authenticated user making the request.
+            target_user_email: Email of the user being targeted.
+            action: The action being performed.
+
+        Raises:
+            PermissionDeniedError: If user lacks permission.
+        """
+    @classmethod
+    @transaction
+    def setup_totp_device(cls, current_user: User, target_user_email: str, device_name: str, issuer: str | None = None) -> dict[str, str]:
+        """
+        Step 1: Setup TOTP device (generate secret, create unconfirmed device).
+
+        Args:
+            current_user: The authenticated user making the request.
+            target_user_email: Email of user to setup device for.
+            device_name: User-friendly name for the device.
+            issuer: TOTP issuer name (defaults to MFA_TOTP_ISSUER setting).
+
+        Returns:
+            dict with keys:
+                - secret: Base32 secret (show to user ONCE)
+                - qr_code_url: otpauth:// URL for QR code generation
+                - device_id: ID of unconfirmed device
+
+        Raises:
+            UserNotFoundError: If target user doesn't exist.
+            PermissionDeniedError: If user lacks permission.
+
+        Security Note:
+            Secret is returned ONLY during setup.
+            User must scan QR or manually enter secret.
+            Device is created with confirmed=False.
+        """
+    @classmethod
+    @async_transaction
+    async def asetup_totp_device(cls, current_user: User, target_user_email: str, device_name: str, issuer: str | None = None) -> dict[str, str]:
+        """
+        Async version of setup_totp_device.
+
+        Step 1: Setup TOTP device (generate secret, create unconfirmed device).
+
+        Args:
+            current_user: The authenticated user making the request.
+            target_user_email: Email of user to setup device for.
+            device_name: User-friendly name for the device.
+            issuer: TOTP issuer name (defaults to MFA_TOTP_ISSUER setting).
+
+        Returns:
+            dict with keys:
+                - secret: Base32 secret (show to user ONCE)
+                - qr_code_url: otpauth:// URL for QR code generation
+                - device_id: ID of unconfirmed device
+
+        Raises:
+            UserNotFoundError: If target user doesn't exist.
+            PermissionDeniedError: If user lacks permission.
+
+        Security Note:
+            Secret is returned ONLY during setup.
+            User must scan QR or manually enter secret.
+            Device is created with confirmed=False.
+        """
+    @classmethod
+    @transaction
+    def confirm_totp_device(cls, current_user: User, device_id: str, verification_code: str) -> TOTPDevice:
+        """
+        Step 2: Confirm TOTP device by verifying code.
+
+        Args:
+            current_user: The authenticated user making the request.
+            device_id: ID of unconfirmed device from setup step.
+            verification_code: 6-digit code from authenticator app.
+
+        Returns:
+            TOTPDevice: The confirmed device.
+
+        Raises:
+            PermissionDeniedError: If user lacks permission.
+            MFADeviceNotFoundError: If device doesn't exist.
+            InvalidMFACodeError: If verification code is incorrect.
+            MFASetupError: If device already confirmed.
+
+        Flow:
+            1. Retrieve unconfirmed device
+            2. Check ownership/permissions
+            3. Verify code using device.verify_code()
+            4. Mark device as confirmed=True
+            5. Save and return
+        """
+    @classmethod
+    @async_transaction
+    async def aconfirm_totp_device(cls, current_user: User, device_id: str, verification_code: str) -> TOTPDevice:
+        """
+        Async version of confirm_totp_device.
+
+        Step 2: Confirm TOTP device by verifying code.
+
+        Args:
+            current_user: The authenticated user making the request.
+            device_id: ID of unconfirmed device from setup step.
+            verification_code: 6-digit code from authenticator app.
+
+        Returns:
+            TOTPDevice: The confirmed device.
+
+        Raises:
+            PermissionDeniedError: If user lacks permission.
+            MFADeviceNotFoundError: If device doesn't exist.
+            InvalidMFACodeError: If verification code is incorrect.
+            MFASetupError: If device already confirmed.
+
+        Flow:
+            1. Retrieve unconfirmed device
+            2. Check ownership/permissions
+            3. Verify code using device.verify_code()
+            4. Mark device as confirmed=True
+            5. Save and return
+        """

amsdal/contrib/auth/settings.py

@@ -16,6 +16,10 @@ class Settings(BaseSettings):
         AUTH_JWT_KEY (str | None): The key used for JWT authentication.
         AUTH_TOKEN_EXPIRATION (int): The expiration time for authentication tokens in seconds.
         REQUIRE_DEFAULT_AUTHORIZATION (bool): Flag to require default authorization.
+        REQUIRE_MFA_BY_DEFAULT (bool): Flag to require MFA for all users by default.
+        MFA_TOTP_ISSUER (str): The issuer name displayed in TOTP authenticator apps.
+        MFA_BACKUP_CODES_COUNT (int): Number of backup codes to generate per user.
+        MFA_EMAIL_CODE_EXPIRATION (int): Email MFA code expiration time in seconds.
     """
 
     model_config = SettingsConfigDict(
@@ -31,6 +35,10 @@ class Settings(BaseSettings):
     AUTH_JWT_KEY: str | None = None
     AUTH_TOKEN_EXPIRATION: int = 86400
     REQUIRE_DEFAULT_AUTHORIZATION: bool = True
+    REQUIRE_MFA_BY_DEFAULT: bool = False
+    MFA_TOTP_ISSUER: str = 'AMSDAL'
+    MFA_BACKUP_CODES_COUNT: int = 10
+    MFA_EMAIL_CODE_EXPIRATION: int = 300
 
 
 auth_settings = Settings()

amsdal/contrib/auth/settings.pyi

@@ -15,6 +15,10 @@ class Settings(BaseSettings):
         AUTH_JWT_KEY (str | None): The key used for JWT authentication.
         AUTH_TOKEN_EXPIRATION (int): The expiration time for authentication tokens in seconds.
         REQUIRE_DEFAULT_AUTHORIZATION (bool): Flag to require default authorization.
+        REQUIRE_MFA_BY_DEFAULT (bool): Flag to require MFA for all users by default.
+        MFA_TOTP_ISSUER (str): The issuer name displayed in TOTP authenticator apps.
+        MFA_BACKUP_CODES_COUNT (int): Number of backup codes to generate per user.
+        MFA_EMAIL_CODE_EXPIRATION (int): Email MFA code expiration time in seconds.
     """
     model_config: Incomplete
     ADMIN_USER_EMAIL: str | None
@@ -22,5 +26,9 @@ class Settings(BaseSettings):
     AUTH_JWT_KEY: str | None
     AUTH_TOKEN_EXPIRATION: int
     REQUIRE_DEFAULT_AUTHORIZATION: bool
+    REQUIRE_MFA_BY_DEFAULT: bool
+    MFA_TOTP_ISSUER: str
+    MFA_BACKUP_CODES_COUNT: int
+    MFA_EMAIL_CODE_EXPIRATION: int
 
 auth_settings: Incomplete

amsdal/contrib/auth/transactions/__init__.py

@@ -0,0 +1 @@
+"""MFA transaction wrappers for API endpoints."""

amsdal/contrib/auth/transactions/mfa_device_transactions.py

@@ -0,0 +1,463 @@
+"""MFA device transaction wrappers for API endpoints."""
+
+from amsdal_data.transactions.decorators import async_transaction
+from amsdal_data.transactions.decorators import transaction
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from amsdal.context.manager import AmsdalContextManager
+from amsdal.contrib.auth.decorators import require_auth
+from amsdal.contrib.auth.models.email_mfa_device import EmailMFADevice
+from amsdal.contrib.auth.models.user import User
+from amsdal.contrib.auth.services.mfa_device_service import MFADeviceService
+from amsdal.contrib.auth.utils.mfa import DeviceType
+
+# ============================================================================
+# REQUEST/RESPONSE MODELS
+# ============================================================================
+
+TAGS = ['Auth', 'MFA']
+
+
+class AddEmailDeviceRequest(BaseModel):
+    """Request model for adding email MFA device."""
+
+    target_user_email: str = Field(..., description='Email of user to add device for')
+    device_name: str = Field(..., description='User-friendly name for the device')
+    email: str | None = Field(None, description='Email for MFA codes (defaults to target_user_email)')
+
+
+class EmailDeviceResponse(BaseModel):
+    """Response model for email MFA device."""
+
+    device_id: str = Field(..., description='Device ID')
+    user_email: str = Field(..., description='User email')
+    name: str = Field(..., description='Device name')
+    email: str = Field(..., description='Email where MFA codes are sent')
+    confirmed: bool = Field(..., description='Whether device is confirmed')
+
+    @classmethod
+    def from_device(cls, device: EmailMFADevice) -> 'EmailDeviceResponse':
+        """Create response from EmailMFADevice model."""
+        return cls(
+            device_id=device._object_id,
+            user_email=device.user_email,
+            name=device.name,
+            email=device.email,
+            confirmed=device.confirmed,
+        )
+
+
+class AddBackupCodesRequest(BaseModel):
+    """Request model for adding backup codes."""
+
+    target_user_email: str = Field(..., description='Email of user to add codes for')
+    device_name: str = Field('Backup Codes', description='Name for the backup code set')
+    code_count: int | None = Field(None, description='Number of codes to generate (optional)', ge=1, le=20)
+
+
+class AddBackupCodesResponse(BaseModel):
+    """Response model for adding backup codes."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            'example': {
+                'device_count': 10,
+                'codes': ['ABC123DEF456', 'GHI789JKL012', '...'],
+            },
+        },
+    )
+
+    device_count: int = Field(..., description='Number of backup codes generated')
+    codes: list[str] = Field(..., description='Plaintext backup codes (DISPLAY ONCE)')
+
+
+class ListDevicesRequest(BaseModel):
+    """Request model for listing MFA devices."""
+
+    target_user_email: str = Field(..., description='Email of user to list devices for')
+    include_unconfirmed: bool = Field(False, description='Whether to include unconfirmed devices')
+
+
+class DeviceInfo(BaseModel):
+    """Device information for list response."""
+
+    device_id: str = Field(..., description='Device ID')
+    name: str = Field(..., description='Device name')
+    confirmed: bool = Field(..., description='Whether device is confirmed')
+    device_type: str = Field(..., description='Type of device')
+
+
+class ListDevicesResponse(BaseModel):
+    """Response model for listing MFA devices."""
+
+    totp_devices: list[DeviceInfo] = Field(default_factory=list, description='TOTP authenticator devices')
+    email_devices: list[DeviceInfo] = Field(default_factory=list, description='Email MFA devices')
+    sms_devices: list[DeviceInfo] = Field(default_factory=list, description='SMS MFA devices')
+    backup_codes: list[DeviceInfo] = Field(default_factory=list, description='Backup code devices')
+    total_count: int = Field(..., description='Total number of devices')
+
+    @classmethod
+    def from_device_dict(cls, devices_by_type: dict) -> 'ListDevicesResponse':  # type: ignore[type-arg]
+        """Create response from service layer result."""
+        totp_devices = [
+            DeviceInfo(
+                device_id=device._object_id,
+                name=device.name,
+                confirmed=device.confirmed,
+                device_type='totp',
+            )
+            for device in devices_by_type.get(DeviceType.TOTP, [])
+        ]
+
+        email_devices = [
+            DeviceInfo(
+                device_id=device._object_id,
+                name=device.name,
+                confirmed=device.confirmed,
+                device_type='email',
+            )
+            for device in devices_by_type.get(DeviceType.EMAIL, [])
+        ]
+
+        sms_devices = [
+            DeviceInfo(
+                device_id=device._object_id,
+                name=device.name,
+                confirmed=device.confirmed,
+                device_type='sms',
+            )
+            for device in devices_by_type.get(DeviceType.SMS, [])
+        ]
+
+        backup_codes = [
+            DeviceInfo(
+                device_id=device._object_id,
+                name=device.name,
+                confirmed=device.confirmed,
+                device_type='backup_code',
+            )
+            for device in devices_by_type.get(DeviceType.BACKUP_CODE, [])
+        ]
+
+        total = len(totp_devices) + len(email_devices) + len(sms_devices) + len(backup_codes)
+
+        return cls(
+            totp_devices=totp_devices,
+            email_devices=email_devices,
+            sms_devices=sms_devices,
+            backup_codes=backup_codes,
+            total_count=total,
+        )
+
+
+class RemoveDeviceRequest(BaseModel):
+    """Request model for removing MFA device."""
+
+    device_id: str = Field(..., description='ID of device to remove')
+    hard_delete: bool = Field(False, description='If True, permanently delete; if False, soft delete')
+
+
+class RemoveDeviceResponse(BaseModel):
+    """Response model for removing MFA device."""
+
+    device_id: str = Field(..., description='ID of removed device')
+    deleted: bool = Field(..., description='Whether device was permanently deleted')
+
+
+# ============================================================================
+# TRANSACTION FUNCTIONS
+# ============================================================================
+
+
+def get_current_user() -> User:
+    """Helper to get current authenticated user from context."""
+    return AmsdalContextManager().get_context().get('request').user  # type: ignore[union-attr]
+
+
+@require_auth
+@transaction(tags=TAGS)  # type: ignore[call-arg]
+def add_email_device_transaction(
+    request: AddEmailDeviceRequest,
+) -> EmailDeviceResponse:
+    """
+    Add email MFA device for a user.
+
+    Email devices are automatically confirmed and can be used immediately.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Email device creation request.
+
+    Returns:
+        EmailDeviceResponse: Created device details.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = AddEmailDeviceRequest.model_validate(request)
+
+    device = MFADeviceService.add_email_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        email=request.email,
+    )
+
+    return EmailDeviceResponse.from_device(device)
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def aadd_email_device_transaction(
+    request: AddEmailDeviceRequest,
+) -> EmailDeviceResponse:
+    """
+    Async version of add_email_device_transaction.
+
+    Add email MFA device for a user.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Email device creation request.
+
+    Returns:
+        EmailDeviceResponse: Created device details.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = AddEmailDeviceRequest.model_validate(request)
+
+    device = await MFADeviceService.aadd_email_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        email=request.email,
+    )
+
+    return EmailDeviceResponse.from_device(device)
+
+
+@require_auth
+@transaction(tags=TAGS)  # type: ignore[call-arg]
+def add_backup_codes_transaction(
+    request: AddBackupCodesRequest,
+) -> AddBackupCodesResponse:
+    """
+    Add backup codes for a user.
+
+    Backup codes are one-time use codes that can be used if primary
+    MFA methods are unavailable.
+
+    Security Note:
+        Plaintext codes are returned ONLY during creation.
+        Caller must display/send these to user immediately.
+        Codes cannot be retrieved later.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Backup codes creation request.
+
+    Returns:
+        AddBackupCodesResponse: Contains plaintext backup codes.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = AddBackupCodesRequest.model_validate(request)
+
+    devices, plaintext_codes = MFADeviceService.add_backup_codes(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        code_count=request.code_count,
+    )
+
+    return AddBackupCodesResponse(
+        device_count=len(devices),
+        codes=plaintext_codes,
+    )
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def aadd_backup_codes_transaction(
+    request: AddBackupCodesRequest,
+) -> AddBackupCodesResponse:
+    """
+    Async version of add_backup_codes_transaction.
+
+    Add backup codes for a user.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Backup codes creation request.
+
+    Returns:
+        AddBackupCodesResponse: Contains plaintext backup codes.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = AddBackupCodesRequest.model_validate(request)
+
+    devices, plaintext_codes = await MFADeviceService.aadd_backup_codes(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        code_count=request.code_count,
+    )
+
+    return AddBackupCodesResponse(
+        device_count=len(devices),
+        codes=plaintext_codes,
+    )
+
+
+@require_auth
+@transaction(tags=TAGS)  # type: ignore[call-arg]
+def list_devices_transaction(
+    request: ListDevicesRequest,
+) -> ListDevicesResponse:
+    """
+    List all MFA devices for a user.
+
+    Returns devices grouped by type (TOTP, Email, SMS, Backup Codes).
+
+    Note: Read-only operation, no @transaction decorator needed.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: List devices request.
+
+    Returns:
+        ListDevicesResponse: Devices grouped by type.
+
+    Raises:
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = ListDevicesRequest.model_validate(request)
+
+    devices_by_type = MFADeviceService.list_devices(
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        include_unconfirmed=request.include_unconfirmed,
+    )
+
+    return ListDevicesResponse.from_device_dict(devices_by_type)
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def alist_devices_transaction(
+    request: ListDevicesRequest,
+) -> ListDevicesResponse:
+    """
+    Async version of list_devices_transaction.
+
+    List all MFA devices for a user.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: List devices request.
+
+    Returns:
+        ListDevicesResponse: Devices grouped by type.
+
+    Raises:
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = ListDevicesRequest.model_validate(request)
+
+    devices_by_type = await MFADeviceService.alist_devices(
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        include_unconfirmed=request.include_unconfirmed,
+    )
+
+    return ListDevicesResponse.from_device_dict(devices_by_type)
+
+
+@require_auth
+@transaction(tags=TAGS)  # type: ignore[call-arg]
+def remove_device_transaction(
+    request: RemoveDeviceRequest,
+) -> RemoveDeviceResponse:
+    """
+    Remove (deactivate or delete) an MFA device.
+
+    By default performs soft delete (marks inactive) to preserve audit trail.
+    Use hard_delete=True to permanently remove the device.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Remove device request.
+
+    Returns:
+        RemoveDeviceResponse: Removal confirmation.
+
+    Raises:
+        PermissionDeniedError: If user lacks permission.
+        MFADeviceNotFoundError: If device doesn't exist.
+    """
+    if isinstance(request, dict):
+        request = RemoveDeviceRequest.model_validate(request)
+
+    MFADeviceService.remove_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        device_id=request.device_id,
+        hard_delete=request.hard_delete,
+    )
+
+    return RemoveDeviceResponse(
+        device_id=request.device_id,
+        deleted=request.hard_delete,
+    )
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def aremove_device_transaction(
+    request: RemoveDeviceRequest,
+) -> RemoveDeviceResponse:
+    """
+    Async version of remove_device_transaction.
+
+    Remove (deactivate or delete) an MFA device.
+
+    Args:
+        current_user: The authenticated user making the request.
+        request: Remove device request.
+
+    Returns:
+        RemoveDeviceResponse: Removal confirmation.
+
+    Raises:
+        PermissionDeniedError: If user lacks permission.
+        MFADeviceNotFoundError: If device doesn't exist.
+    """
+    if isinstance(request, dict):
+        request = RemoveDeviceRequest.model_validate(request)
+
+    await MFADeviceService.aremove_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        device_id=request.device_id,
+        hard_delete=request.hard_delete,
+    )
+
+    return RemoveDeviceResponse(
+        device_id=request.device_id,
+        deleted=request.hard_delete,
+    )