stapel-auth 0.3.2__py3-none-any.whl

stapel_auth/__init__.py

@@ -0,0 +1,46 @@
+"""stapel-auth — pluggable authentication for Django.
+
+Public API of the ``stapel_auth`` package, exported lazily (PEP 562) so that
+importing the package itself stays side-effect free: the runtime settings
+object (``auth_settings``), the per-feature URL-pattern factories from
+``stapel_auth.urls`` and the OAuth provider registry (``PROVIDER_REGISTRY``).
+"""
+
+from importlib import import_module
+
+# name -> (relative module, attribute) — resolved on first attribute access.
+_LAZY_EXPORTS = {
+    "auth_settings": (".conf", "auth_settings"),
+    "PROVIDER_REGISTRY": (".oauth_providers", "PROVIDER_REGISTRY"),
+    "get_admin_api_urls": (".urls", "get_admin_api_urls"),
+    "get_magic_link_urls": (".urls", "get_magic_link_urls"),
+    "get_mfa_urls": (".urls", "get_mfa_urls"),
+    "get_oauth_urls": (".urls", "get_oauth_urls"),
+    "get_openid_urls": (".urls", "get_openid_urls"),
+    "get_otp_urls": (".urls", "get_otp_urls"),
+    "get_password_urls": (".urls", "get_password_urls"),
+    "get_qr_urls": (".urls", "get_qr_urls"),
+    "get_security_urls": (".urls", "get_security_urls"),
+    "get_sessions_urls": (".urls", "get_sessions_urls"),
+    "get_sso_urls": (".urls", "get_sso_urls"),
+    "get_verification_urls": (".urls", "get_verification_urls"),
+}
+
+__all__ = sorted(_LAZY_EXPORTS)
+
+
+def __getattr__(name):
+    """PEP 562 lazy exports: resolve, cache into globals(), return."""
+    try:
+        module_path, attr = _LAZY_EXPORTS[name]
+    except KeyError:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}"
+        ) from None
+    value = getattr(import_module(module_path, __name__), attr)
+    globals()[name] = value  # cache — __getattr__ is skipped next time
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_auth/admin/dto.py

@@ -0,0 +1,46 @@
+"""Data Transfer Objects for the admin sub-package."""
+from dataclasses import dataclass
+from typing import Optional
+
+
+# =============================================================================
+# Admin Broker DTOs
+# =============================================================================
+
+
+@dataclass
+class AdminUserCreateRequest:
+    """Create a user via admin broker, bypassing OTP verification.
+
+    Attributes:
+        email: User email. Example: user@example.com
+        phone: Phone in E.164 format. Example: +79001234567
+        username: Username. Example: alice
+        display_name: Display name. Example: Alice
+        password: Initial password (optional). Example: secure123
+        send_welcome: Send welcome notification via notification service. Example: false
+        mark_verified: Mark email/phone as verified immediately. Example: true
+    """
+    email: Optional[str] = None
+    phone: Optional[str] = None
+    username: Optional[str] = None
+    display_name: Optional[str] = None
+    password: Optional[str] = None
+    send_welcome: bool = False
+    mark_verified: bool = True
+
+
+@dataclass
+class AdminUserCreateResponse:
+    """Created user summary.
+
+    Attributes:
+        user_id: Created user UUID. Example: 550e8400-e29b-41d4-a716-446655440000
+        email: User email. Example: user@example.com
+        phone: User phone. Example: +79001234567
+        username: Username. Example: alice
+    """
+    user_id: str
+    email: Optional[str]
+    phone: Optional[str]
+    username: Optional[str]

stapel_auth/admin/serializers.py

@@ -0,0 +1,60 @@
+"""Serializers for the admin sub-package."""
+from rest_framework import serializers
+from stapel_core.django.api.serializers import StapelDataclassSerializer
+from stapel_core.django.api.errors import StapelValidationError
+
+
+from stapel_auth.models import ServiceAPIKey
+from stapel_auth.errors import ERR_400_EMAIL_OR_PHONE_REQUIRED
+from stapel_auth.admin.dto import AdminUserCreateResponse
+
+
+def _normalize_phone(value):
+    """Parse and normalize phone number to E.164 format (+79991234567)."""
+    import phonenumbers
+    from stapel_auth.errors import (
+        ERR_400_INVALID_PHONE_FORMAT,
+        ERR_400_INVALID_PHONE,
+        ERR_400_PHONE_TOO_LONG,
+    )
+    try:
+        phone_number = phonenumbers.parse(value, None)
+    except phonenumbers.NumberParseException:
+        raise StapelValidationError(ERR_400_INVALID_PHONE_FORMAT)
+    if not phonenumbers.is_valid_number(phone_number):
+        raise StapelValidationError(ERR_400_INVALID_PHONE)
+    e164 = phonenumbers.format_number(phone_number, phonenumbers.PhoneNumberFormat.E164)
+    if len(e164) > 16:  # E.164: '+' + up to 15 digits
+        raise StapelValidationError(ERR_400_PHONE_TOO_LONG)
+    return e164
+
+
+class ServiceAPIKeySerializer(serializers.ModelSerializer):
+    """Serializer for Service API Keys"""
+
+    class Meta:
+        model = ServiceAPIKey
+        fields = ['id', 'name', 'key', 'description', 'is_active', 'created_at', 'last_used_at', 'allowed_endpoints']
+        read_only_fields = ['id', 'key', 'created_at', 'last_used_at']
+
+
+class AdminUserCreateRequestSerializer(serializers.Serializer):
+    email = serializers.EmailField(required=False, allow_null=True, default=None)
+    phone = serializers.CharField(required=False, allow_null=True, default=None)
+    username = serializers.CharField(required=False, allow_null=True, default=None)
+    display_name = serializers.CharField(required=False, allow_null=True, default=None)
+    password = serializers.CharField(required=False, allow_null=True, default=None, min_length=8)
+    send_welcome = serializers.BooleanField(default=False)
+    mark_verified = serializers.BooleanField(default=True)
+
+    def validate(self, attrs):
+        if not any([attrs.get("email"), attrs.get("phone"), attrs.get("username")]):
+            raise StapelValidationError(ERR_400_EMAIL_OR_PHONE_REQUIRED)
+        if attrs.get("phone"):
+            attrs["phone"] = _normalize_phone(attrs["phone"])
+        return attrs
+
+
+class AdminUserCreateResponseSerializer(StapelDataclassSerializer):
+    class Meta:
+        dataclass = AdminUserCreateResponse

stapel_auth/admin/views.py

@@ -0,0 +1,129 @@
+"""Views for the admin sub-package: ServiceAPIKeyViewSet, AdminUserViewSet, CapabilitiesView."""
+
+import logging
+
+from drf_spectacular.utils import extend_schema
+from rest_framework import permissions, viewsets
+from rest_framework.decorators import action
+from rest_framework.views import APIView
+from stapel_core.django.api.errors import (
+    StapelResponse,
+)
+
+from stapel_auth.admin.dto import AdminUserCreateResponse
+from stapel_auth.admin.serializers import (
+    AdminUserCreateRequestSerializer,
+    AdminUserCreateResponseSerializer,
+    ServiceAPIKeySerializer,
+)
+from stapel_auth.models import ServiceAPIKey
+
+logger = logging.getLogger(__name__)
+
+
+@extend_schema(tags=["API Keys"])
+class ServiceAPIKeyViewSet(viewsets.ModelViewSet):
+    """
+    ViewSet for managing service API keys
+    """
+
+    queryset = ServiceAPIKey.objects.all()
+    serializer_class = ServiceAPIKeySerializer
+    permission_classes = [permissions.IsAdminUser]
+
+    def perform_create(self, serializer):
+        """Generate API key on creation"""
+        serializer.save(key=ServiceAPIKey.generate_key())
+
+
+class CapabilitiesView(APIView):
+    """Public endpoint returning enabled auth methods for this deployment."""
+
+    permission_classes = [permissions.AllowAny]
+    authentication_classes = []
+
+    @extend_schema(
+        tags=["Auth"],
+        description="Return available authentication and registration methods for this deployment.",
+        responses={200: None},
+    )
+    def get(self, request):
+        from stapel_auth.oauth.services import AuthCapabilitiesService
+        from stapel_auth.serializers import AuthCapabilitiesSerializer
+
+        caps = AuthCapabilitiesService.get_capabilities()
+        return StapelResponse(AuthCapabilitiesSerializer(caps))
+
+
+# ── Admin User Broker ─────────────────────────────────────────────────────────
+
+
+class AdminUserViewSet(viewsets.GenericViewSet):
+    """Admin broker for creating users without OTP verification."""
+
+    permission_classes = [permissions.AllowAny]
+
+    @extend_schema(
+        tags=["Admin"],
+        description="Create a user account without OTP, bypassing normal registration flow. Requires service API key or admin (staff) credentials.",
+        request=AdminUserCreateRequestSerializer,
+        responses={201: AdminUserCreateResponseSerializer, 400: None, 403: None},
+    )
+    @action(detail=False, methods=["post"])
+    def create_user(self, request):
+        from django.contrib.auth import get_user_model
+        from stapel_core.django.api.errors import error_403_forbidden
+
+        from stapel_auth.permissions import IsServiceAPIKey
+
+        User = get_user_model()
+
+        # Allow either staff user or service API key
+        is_svc_key = IsServiceAPIKey().has_permission(request, self)
+        if not is_svc_key and not (
+            request.user.is_authenticated and request.user.is_staff
+        ):
+            return error_403_forbidden()
+
+        serializer = AdminUserCreateRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        data = serializer.validated_data
+
+        email = data.get("email")
+        phone = data.get("phone")
+        username = data.get("username")
+        display_name = data.get("display_name")
+        password = data.get("password")
+        mark_verified = data.get("mark_verified", True)
+        send_welcome = data.get("send_welcome", False)
+
+        user = User.objects.create(
+            email=email,
+            phone=phone,
+            username=username or (email.split("@")[0] if email else phone),
+            is_email_verified=mark_verified and bool(email),
+            is_phone_verified=mark_verified and bool(phone),
+        )
+        if display_name:
+            user.first_name = display_name
+        if password:
+            user.set_password(password)
+        user.save()
+
+        if send_welcome:
+            try:
+                from stapel_core.notifications import request_notification
+
+                request_notification(notification_type="welcome", user_id=str(user.id))
+            except Exception:
+                logger.exception(
+                    "Failed to send welcome notification for user %s", user.id
+                )
+
+        dto = AdminUserCreateResponse(
+            user_id=str(user.id),
+            email=user.email,
+            phone=user.phone,
+            username=user.username,
+        )
+        return StapelResponse(AdminUserCreateResponseSerializer(dto), status=201)

stapel_auth/admin.py

@@ -0,0 +1,73 @@
+from django.contrib import admin
+from .models import PhoneVerification, EmailVerification, ServiceAPIKey, RefreshTokenTracker, LoginAttempt, AuthenticatorChangeRequest
+
+
+@admin.register(PhoneVerification)
+class PhoneVerificationAdmin(admin.ModelAdmin):
+    """Phone Verification admin"""
+
+    list_display = ['phone', 'code', 'is_verified', 'created_at', 'expires_at', 'attempts']
+    list_filter = ['is_verified', 'created_at']
+    search_fields = ['phone']
+    ordering = ['-created_at']
+    readonly_fields = ['created_at']
+
+
+@admin.register(EmailVerification)
+class EmailVerificationAdmin(admin.ModelAdmin):
+    """Email Verification admin"""
+
+    list_display = ['email', 'code', 'is_verified', 'created_at', 'expires_at', 'attempts']
+    list_filter = ['is_verified', 'created_at']
+    search_fields = ['email']
+    ordering = ['-created_at']
+    readonly_fields = ['created_at']
+
+
+@admin.register(ServiceAPIKey)
+class ServiceAPIKeyAdmin(admin.ModelAdmin):
+    """Service API Key admin"""
+
+    list_display = ['name', 'key', 'is_active', 'created_at', 'last_used_at']
+    list_filter = ['is_active', 'created_at']
+    search_fields = ['name', 'key']
+    ordering = ['-created_at']
+    readonly_fields = ['key', 'created_at', 'last_used_at']
+
+    def save_model(self, request, obj, form, change):
+        if not change:  # Only set key on creation
+            obj.key = ServiceAPIKey.generate_key()
+        super().save_model(request, obj, form, change)
+
+
+@admin.register(RefreshTokenTracker)
+class RefreshTokenTrackerAdmin(admin.ModelAdmin):
+    """Refresh Token Tracker admin"""
+
+    list_display = ['user', 'created_at', 'expires_at', 'is_revoked', 'device_info']
+    list_filter = ['is_revoked', 'created_at']
+    search_fields = ['user__username', 'user__email', 'device_info']
+    ordering = ['-created_at']
+    readonly_fields = ['created_at']
+
+
+@admin.register(AuthenticatorChangeRequest)
+class AuthenticatorChangeRequestAdmin(admin.ModelAdmin):
+    """Authenticator Change Request admin"""
+
+    list_display = ['user', 'change_type', 'status', 'old_value', 'new_value', 'created_at', 'scheduled_at']
+    list_filter = ['status', 'change_type']
+    search_fields = ['old_value', 'new_value']
+    ordering = ['-created_at']
+    readonly_fields = ['id', 'change_token', 'created_at', 'completed_at', 'cancelled_at']
+
+
+@admin.register(LoginAttempt)
+class LoginAttemptAdmin(admin.ModelAdmin):
+    """Login Attempt admin"""
+
+    list_display = ['identifier', 'attempt_type', 'ip_address', 'created_at']
+    list_filter = ['attempt_type', 'created_at']
+    search_fields = ['identifier', 'ip_address']
+    ordering = ['-created_at']
+    readonly_fields = ['created_at']

stapel_auth/apps.py

@@ -0,0 +1,52 @@
+from django.apps import AppConfig
+
+
+class StapelAuthConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'stapel_auth'
+    label = 'authentication'   # keeps existing migration history / DB tables intact
+    verbose_name = 'Stapel Auth'
+
+    def ready(self):
+        import warnings
+        from django.conf import settings
+        from django.utils.module_loading import import_string
+        from stapel_core.oauth import register_provider
+        from .conf import auth_settings
+
+        if not auth_settings.FRONTEND_URL:
+            warnings.warn(
+                "stapel-auth: FRONTEND_URL is not set. "
+                "Set STAPEL_AUTH = {'FRONTEND_URL': '...'} or FRONTEND_URL env var. "
+                "Redirects after SSO/magic link/QR login will not work correctly.",
+                stacklevel=2,
+            )
+
+        classes = list(auth_settings.OAUTH_PROVIDER_CLASSES)
+        if getattr(settings, 'DEBUG', False):
+            classes.append('stapel_auth.oauth_providers.TestProvider')
+
+        for cls_path in classes:
+            register_provider(import_string(cls_path)())
+
+        # Step-up verification factors: the mechanism (challenge/grant
+        # stores, @requires_verification) lives in stapel-core; the concrete
+        # factor implementations on top of the auth services are registered
+        # here. register_factor is idempotent per factor id.
+        from stapel_core.verification import register_factor
+        from .verification_factors import DEFAULT_FACTOR_CLASSES
+        for factor_cls in DEFAULT_FACTOR_CLASSES:
+            register_factor(factor_cls())
+
+        # comm Function providers (auth.verification.policy). Importing the
+        # module runs the @function decorators; re-imports are no-ops and
+        # re-registering the same handler object is idempotent.
+        from . import functions  # noqa: F401
+
+        # In monolith mode (no GDPR_COLLECTING_SERVICES), register the GDPR provider
+        # in-process so the orchestrator can call it directly.
+        # In microservices mode the bus consumer (management/commands/consume_gdpr.py) handles it.
+        if not getattr(settings, 'GDPR_COLLECTING_SERVICES', None):
+            from stapel_core.gdpr import gdpr_registry
+            from .gdpr import AuthGDPRProvider
+            gdpr_registry.register(AuthGDPRProvider())

stapel_auth/conf.py

@@ -0,0 +1,196 @@
+"""
+Stapel-auth app settings.
+
+Configure via STAPEL_AUTH dict in Django settings:
+
+    STAPEL_AUTH = {
+        'FRONTEND_URL': 'https://app.example.com',
+        'USE_MOCK_SMS_OTP': True,
+        'OAUTH_PROVIDERS': {
+            'google': {'client_id': '...', 'client_secret': '...'},
+        },
+    }
+
+Each key falls back to: direct Django setting → env var → built-in default.
+"""
+import os
+from dataclasses import dataclass
+from django.test.signals import setting_changed
+
+
+@dataclass
+class OAuthProviderConfig:
+    """Credentials for a single OAuth provider.
+
+    Attributes:
+        client_id: OAuth app client ID. Example: abc123
+        client_secret: OAuth app client secret. Example: secret
+    """
+    client_id: str
+    client_secret: str = ''
+
+DEFAULTS = {
+    # URLs
+    'FRONTEND_URL': None,           # Required in production; falls back to env FRONTEND_URL
+    'BACKEND_URL': None,            # Required for SAML/OIDC; falls back to env BACKEND_URL
+
+    # OTP
+    'USE_MOCK_SMS_OTP': False,
+    'USE_MOCK_EMAIL_OTP': False,
+    'MOCK_OTP_CODE': '0000',
+    'OTP_TTL': 600,                 # seconds
+    'OTP_MAX_ATTEMPTS': 5,
+    'OTP_RATE_LIMIT_PER_HOUR': 3,
+
+    # Magic links
+    'MAGIC_LINK_TTL': 900,          # seconds (15 min)
+    'MAGIC_LINK_RATE_LIMIT_PER_HOUR': 3,
+
+    # QR auth
+    'QR_TOKEN_TTL': 300,            # seconds (5 min)
+
+    # Sessions
+    'SESSION_TTL_DAYS': 30,
+
+    # Anonymous users
+    'ANONYMOUS_USER_LIFETIME_DAYS': 30,
+
+    # JWT cookies (override if needed; usually inherited from stapel-core settings)
+    'JWT_COOKIE_DOMAIN': None,
+
+    # TOTP
+    'TOTP_ISSUER': 'Stapel',
+
+    # Passkeys (WebAuthn)
+    'WEBAUTHN_RP_ID': None,         # Falls back to request host
+    'WEBAUTHN_RP_NAME': 'Stapel',
+    'WEBAUTHN_ORIGIN': None,        # Falls back to FRONTEND_URL
+
+    # SSO
+    'SSO_ENFORCED_REDIRECT_PATH': '/login',
+
+    # Notifications (optional integration)
+    'LOGIN_NOTIFICATION_ENABLED': False,
+
+    # GDPR integration: dotted path to the model that stores re-registration
+    # hashes. Resolved lazily — stapel-gdpr is NOT a hard dependency.
+    'REREGISTRATION_MODEL': 'stapel_gdpr.models.ReRegistrationHash',
+
+    # Service-to-service
+    'INTERNAL_SERVICE_KEY': None,   # Falls back to env INTERNAL_SERVICE_KEY
+
+    # OAuth provider credentials (parsed into dict[str, OAuthProviderConfig])
+    'OAUTH_PROVIDERS': {},
+
+    # Dotted-path list of OAuthProvider subclasses to register on startup.
+    # Extend in settings to add providers without modifying stapel-auth:
+    #   STAPEL_AUTH = {'OAUTH_PROVIDER_CLASSES': [..., 'myapp.providers.YandexProvider']}
+    'OAUTH_PROVIDER_CLASSES': [
+        'stapel_auth.oauth_providers.GoogleProvider',
+        'stapel_auth.oauth_providers.GitHubProvider',
+        'stapel_auth.oauth_providers.ZoomProvider',
+        'stapel_auth.oauth_providers.FacebookProvider',
+        'stapel_auth.oauth_providers.AppleProvider',
+        'stapel_auth.oauth_providers.TwitterProvider',
+        'stapel_auth.oauth_providers.YandexProvider',
+        'stapel_auth.oauth_providers.VKProvider',
+        'stapel_auth.oauth_providers.SberProvider',
+    ],
+
+    # Registration method gates
+    'AUTH_PHONE_REGISTRATION':    True,
+    'AUTH_EMAIL_REGISTRATION':    True,
+    'AUTH_OAUTH_REGISTRATION':    True,
+    'AUTH_SSO_REGISTRATION':      True,
+    'AUTH_PASSWORD_REGISTRATION': False,
+
+    # Login method gates
+    'AUTH_PHONE_LOGIN':      True,
+    'AUTH_EMAIL_LOGIN':      True,
+    'AUTH_OAUTH_LOGIN':      True,
+    'AUTH_SSO_LOGIN':        True,
+    'AUTH_PASSWORD_LOGIN':   False,
+    'AUTH_QR_LOGIN':         True,
+    'AUTH_PASSKEY_LOGIN':    True,
+    'AUTH_MAGIC_LINK_LOGIN': True,
+
+    # Step-up (TOTP challenge) on existing login flows.
+    # OAuth: off by default — the provider already authenticated the user;
+    # opt back in with OAUTH_STEP_UP=True.
+    'OAUTH_STEP_UP': False,
+    # Password login: on by default (a password alone is phishable) —
+    # preserves the pre-0.3 behavior; opt out with PASSWORD_LOGIN_STEP_UP=False.
+    'PASSWORD_LOGIN_STEP_UP': True,
+}
+
+# Env var fallbacks for settings that are commonly set via environment
+_ENV_FALLBACKS = {
+    'FRONTEND_URL': 'FRONTEND_URL',
+    'BACKEND_URL': 'BACKEND_URL',
+    'INTERNAL_SERVICE_KEY': 'INTERNAL_SERVICE_KEY',
+    'JWT_COOKIE_DOMAIN': 'JWT_COOKIE_DOMAIN',
+    'WEBAUTHN_RP_ID': 'WEBAUTHN_RP_ID',
+    'WEBAUTHN_ORIGIN': 'WEBAUTHN_ORIGIN',
+    'TOTP_ISSUER': 'TOTP_ISSUER',
+}
+
+
+class AuthSettings:
+    """
+    Lazy accessor for STAPEL_AUTH settings.
+
+    Resolution order per key:
+      1. STAPEL_AUTH['KEY'] in Django settings
+      2. Direct Django setting (legacy / common.django.settings compat)
+      3. Environment variable (for keys in _ENV_FALLBACKS)
+      4. Built-in default
+    """
+
+    def __init__(self):
+        self._cache: dict = {}
+
+    def __getattr__(self, name: str):
+        if name.startswith('_') or name not in DEFAULTS:
+            raise AttributeError(f'Invalid stapel-auth setting: {name!r}')
+
+        if name in self._cache:
+            return self._cache[name]
+
+        from django.conf import settings as django_settings
+
+        user_settings = getattr(django_settings, 'STAPEL_AUTH', {})
+
+        if name in user_settings:
+            value = user_settings[name]
+        elif hasattr(django_settings, name):
+            # Legacy: setting defined directly (e.g. FRONTEND_URL = '...')
+            value = getattr(django_settings, name)
+        elif name in _ENV_FALLBACKS:
+            value = os.getenv(_ENV_FALLBACKS[name], DEFAULTS[name])
+        else:
+            value = DEFAULTS[name]
+
+        if name == 'OAUTH_PROVIDERS' and isinstance(value, dict):
+            value = {
+                pid: OAuthProviderConfig(**cfg) if isinstance(cfg, dict) else cfg
+                for pid, cfg in value.items()
+            }
+
+        self._cache[name] = value
+        return value
+
+    def reload(self):
+        self.__dict__['_cache'] = {}
+
+
+auth_settings = AuthSettings()
+
+
+def _reload_on_change(*, setting, **kwargs):
+    # Also reload when a flat (legacy) setting with the same name changes,
+    # e.g. override_settings(USE_MOCK_SMS_OTP=False) in tests.
+    if setting == 'STAPEL_AUTH' or setting in DEFAULTS:
+        auth_settings.reload()
+
+
+setting_changed.connect(_reload_on_change)