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

amsdal/contrib/auth/transactions/mfa_device_transactions.pyi

@@ -0,0 +1,226 @@
+from _typeshed import Incomplete
+from amsdal.context.manager import AmsdalContextManager as AmsdalContextManager
+from amsdal.contrib.auth.decorators import require_auth as require_auth
+from amsdal.contrib.auth.models.email_mfa_device import EmailMFADevice as EmailMFADevice
+from amsdal.contrib.auth.models.user import User as User
+from amsdal.contrib.auth.services.mfa_device_service import MFADeviceService as MFADeviceService
+from amsdal.contrib.auth.utils.mfa import DeviceType as DeviceType
+from pydantic import BaseModel
+
+TAGS: Incomplete
+
+class AddEmailDeviceRequest(BaseModel):
+    """Request model for adding email MFA device."""
+    target_user_email: str
+    device_name: str
+    email: str | None
+
+class EmailDeviceResponse(BaseModel):
+    """Response model for email MFA device."""
+    device_id: str
+    user_email: str
+    name: str
+    email: str
+    confirmed: bool
+    @classmethod
+    def from_device(cls, device: EmailMFADevice) -> EmailDeviceResponse:
+        """Create response from EmailMFADevice model."""
+
+class AddBackupCodesRequest(BaseModel):
+    """Request model for adding backup codes."""
+    target_user_email: str
+    device_name: str
+    code_count: int | None
+
+class AddBackupCodesResponse(BaseModel):
+    """Response model for adding backup codes."""
+    model_config: Incomplete
+    device_count: int
+    codes: list[str]
+
+class ListDevicesRequest(BaseModel):
+    """Request model for listing MFA devices."""
+    target_user_email: str
+    include_unconfirmed: bool
+
+class DeviceInfo(BaseModel):
+    """Device information for list response."""
+    device_id: str
+    name: str
+    confirmed: bool
+    device_type: str
+
+class ListDevicesResponse(BaseModel):
+    """Response model for listing MFA devices."""
+    totp_devices: list[DeviceInfo]
+    email_devices: list[DeviceInfo]
+    sms_devices: list[DeviceInfo]
+    backup_codes: list[DeviceInfo]
+    total_count: int
+    @classmethod
+    def from_device_dict(cls, devices_by_type: dict) -> ListDevicesResponse:
+        """Create response from service layer result."""
+
+class RemoveDeviceRequest(BaseModel):
+    """Request model for removing MFA device."""
+    device_id: str
+    hard_delete: bool
+
+class RemoveDeviceResponse(BaseModel):
+    """Response model for removing MFA device."""
+    device_id: str
+    deleted: bool
+
+def get_current_user() -> User:
+    """Helper to get current authenticated user from context."""
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """
+@require_auth
+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.
+    """

amsdal/contrib/auth/transactions/totp_transactions.py

@@ -0,0 +1,206 @@
+"""TOTP 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 Field
+
+from amsdal.context.manager import AmsdalContextManager
+from amsdal.contrib.auth.decorators import require_auth
+from amsdal.contrib.auth.models.totp_device import TOTPDevice
+from amsdal.contrib.auth.models.user import User
+from amsdal.contrib.auth.services.totp_service import TOTPService
+
+# ============================================================================
+# REQUEST/RESPONSE MODELS
+# ============================================================================
+
+TAGS = ['Auth', 'MFA', 'TOTP']
+
+
+class SetupTOTPDeviceRequest(BaseModel):
+    """Request model for TOTP device setup."""
+
+    target_user_email: str = Field(..., description='Email of user to setup device for')
+    device_name: str = Field(..., description='User-friendly name for the device')
+    issuer: str | None = Field(None, description='TOTP issuer name (optional)')
+
+
+class SetupTOTPDeviceResponse(BaseModel):
+    """Response model for TOTP device setup."""
+
+    secret: str = Field(..., description='Base32 TOTP secret (show to user ONCE)')
+    qr_code_url: str = Field(..., description='otpauth:// URL for QR code generation')
+    device_id: str = Field(..., description='ID of unconfirmed device')
+
+
+class ConfirmTOTPDeviceRequest(BaseModel):
+    """Request model for TOTP device confirmation."""
+
+    device_id: str = Field(..., description='ID of unconfirmed device from setup')
+    verification_code: str = Field(..., description='6-digit code from authenticator app', min_length=6, max_length=6)
+
+
+class ConfirmTOTPDeviceResponse(BaseModel):
+    """Response model for TOTP device confirmation."""
+
+    device_id: str = Field(..., description='ID of confirmed device')
+    user_email: str = Field(..., description='User email')
+    name: str = Field(..., description='Device name')
+    confirmed: bool = Field(..., description='Confirmation status')
+
+    @classmethod
+    def from_device(cls, device: TOTPDevice) -> 'ConfirmTOTPDeviceResponse':
+        """Create response from TOTPDevice model."""
+        return cls(
+            device_id=device._object_id,
+            user_email=device.user_email,
+            name=device.name,
+            confirmed=device.confirmed,
+        )
+
+
+# ============================================================================
+# 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 setup_totp_device_transaction(
+    request: SetupTOTPDeviceRequest,
+) -> SetupTOTPDeviceResponse:
+    """
+    Setup TOTP device (Step 1 of 2).
+
+    Creates an unconfirmed TOTP device and returns the secret and QR code URL.
+    The secret is only returned once and cannot be retrieved later.
+
+    Args:
+        request: Setup request containing target user and device details.
+
+    Returns:
+        SetupTOTPDeviceResponse: Contains secret, QR code URL, and device ID.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = SetupTOTPDeviceRequest.model_validate(request)
+
+    result = TOTPService.setup_totp_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        issuer=request.issuer,
+    )
+
+    return SetupTOTPDeviceResponse(**result)
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def asetup_totp_device_transaction(
+    request: SetupTOTPDeviceRequest,
+) -> SetupTOTPDeviceResponse:
+    """
+    Async version of setup_totp_device_transaction.
+
+    Setup TOTP device (Step 1 of 2).
+
+    Args:
+        request: Setup request containing target user and device details.
+
+    Returns:
+        SetupTOTPDeviceResponse: Contains secret, QR code URL, and device ID.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+    if isinstance(request, dict):
+        request = SetupTOTPDeviceRequest.model_validate(request)
+
+    result = await TOTPService.asetup_totp_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        target_user_email=request.target_user_email,
+        device_name=request.device_name,
+        issuer=request.issuer,
+    )
+
+    return SetupTOTPDeviceResponse(**result)
+
+
+@require_auth
+@transaction(tags=TAGS)  # type: ignore[call-arg]
+def confirm_totp_device_transaction(
+    request: ConfirmTOTPDeviceRequest,
+) -> ConfirmTOTPDeviceResponse:
+    """
+    Confirm TOTP device by verifying code (Step 2 of 2).
+
+    Validates the verification code from the authenticator app and marks
+    the device as confirmed if successful.
+
+    Args:
+        request: Confirmation request containing device ID and verification code.
+
+    Returns:
+        ConfirmTOTPDeviceResponse: Confirmed device details.
+
+    Raises:
+        MFADeviceNotFoundError: If device doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+        InvalidMFACodeError: If verification code is incorrect.
+        MFASetupError: If device already confirmed.
+    """
+    if isinstance(request, dict):
+        request = ConfirmTOTPDeviceRequest.model_validate(request)
+
+    device = TOTPService.confirm_totp_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        device_id=request.device_id,
+        verification_code=request.verification_code,
+    )
+
+    return ConfirmTOTPDeviceResponse.from_device(device)
+
+
+@require_auth
+@async_transaction(tags=TAGS)  # type: ignore[call-arg]
+async def aconfirm_totp_device_transaction(
+    request: ConfirmTOTPDeviceRequest,
+) -> ConfirmTOTPDeviceResponse:
+    """
+    Async version of confirm_totp_device_transaction.
+
+    Confirm TOTP device by verifying code (Step 2 of 2).
+
+    Args:
+        request: Confirmation request containing device ID and verification code.
+
+    Returns:
+        ConfirmTOTPDeviceResponse: Confirmed device details.
+
+    Raises:
+        MFADeviceNotFoundError: If device doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+        InvalidMFACodeError: If verification code is incorrect.
+        MFASetupError: If device already confirmed.
+    """
+    if isinstance(request, dict):
+        request = ConfirmTOTPDeviceRequest.model_validate(request)
+
+    device = await TOTPService.aconfirm_totp_device(  # type: ignore[call-arg]
+        current_user=get_current_user(),
+        device_id=request.device_id,
+        verification_code=request.verification_code,
+    )
+
+    return ConfirmTOTPDeviceResponse.from_device(device)

amsdal/contrib/auth/transactions/totp_transactions.pyi

@@ -0,0 +1,113 @@
+from _typeshed import Incomplete
+from amsdal.context.manager import AmsdalContextManager as AmsdalContextManager
+from amsdal.contrib.auth.decorators import require_auth as require_auth
+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.services.totp_service import TOTPService as TOTPService
+from pydantic import BaseModel
+
+TAGS: Incomplete
+
+class SetupTOTPDeviceRequest(BaseModel):
+    """Request model for TOTP device setup."""
+    target_user_email: str
+    device_name: str
+    issuer: str | None
+
+class SetupTOTPDeviceResponse(BaseModel):
+    """Response model for TOTP device setup."""
+    secret: str
+    qr_code_url: str
+    device_id: str
+
+class ConfirmTOTPDeviceRequest(BaseModel):
+    """Request model for TOTP device confirmation."""
+    device_id: str
+    verification_code: str
+
+class ConfirmTOTPDeviceResponse(BaseModel):
+    """Response model for TOTP device confirmation."""
+    device_id: str
+    user_email: str
+    name: str
+    confirmed: bool
+    @classmethod
+    def from_device(cls, device: TOTPDevice) -> ConfirmTOTPDeviceResponse:
+        """Create response from TOTPDevice model."""
+
+def get_current_user() -> User:
+    """Helper to get current authenticated user from context."""
+@require_auth
+def setup_totp_device_transaction(request: SetupTOTPDeviceRequest) -> SetupTOTPDeviceResponse:
+    """
+    Setup TOTP device (Step 1 of 2).
+
+    Creates an unconfirmed TOTP device and returns the secret and QR code URL.
+    The secret is only returned once and cannot be retrieved later.
+
+    Args:
+        request: Setup request containing target user and device details.
+
+    Returns:
+        SetupTOTPDeviceResponse: Contains secret, QR code URL, and device ID.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+@require_auth
+async def asetup_totp_device_transaction(request: SetupTOTPDeviceRequest) -> SetupTOTPDeviceResponse:
+    """
+    Async version of setup_totp_device_transaction.
+
+    Setup TOTP device (Step 1 of 2).
+
+    Args:
+        request: Setup request containing target user and device details.
+
+    Returns:
+        SetupTOTPDeviceResponse: Contains secret, QR code URL, and device ID.
+
+    Raises:
+        UserNotFoundError: If target user doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+    """
+@require_auth
+def confirm_totp_device_transaction(request: ConfirmTOTPDeviceRequest) -> ConfirmTOTPDeviceResponse:
+    """
+    Confirm TOTP device by verifying code (Step 2 of 2).
+
+    Validates the verification code from the authenticator app and marks
+    the device as confirmed if successful.
+
+    Args:
+        request: Confirmation request containing device ID and verification code.
+
+    Returns:
+        ConfirmTOTPDeviceResponse: Confirmed device details.
+
+    Raises:
+        MFADeviceNotFoundError: If device doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+        InvalidMFACodeError: If verification code is incorrect.
+        MFASetupError: If device already confirmed.
+    """
+@require_auth
+async def aconfirm_totp_device_transaction(request: ConfirmTOTPDeviceRequest) -> ConfirmTOTPDeviceResponse:
+    """
+    Async version of confirm_totp_device_transaction.
+
+    Confirm TOTP device by verifying code (Step 2 of 2).
+
+    Args:
+        request: Confirmation request containing device ID and verification code.
+
+    Returns:
+        ConfirmTOTPDeviceResponse: Confirmed device details.
+
+    Raises:
+        MFADeviceNotFoundError: If device doesn't exist.
+        PermissionDeniedError: If user lacks permission.
+        InvalidMFACodeError: If verification code is incorrect.
+        MFASetupError: If device already confirmed.
+    """