stapel-auth 0.3.3__tar.gz

stapel_auth-0.3.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usestapel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_auth-0.3.3/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: stapel-auth
+Version: 0.3.3
+Summary: Full-featured authentication Django app for the Stapel framework
+License: MIT
+Keywords: django,stapel,authentication,jwt,passkey,totp,sso
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Requires-Dist: pyotp>=2.10
+Requires-Dist: webauthn>=2.8
+Requires-Dist: phonenumbers>=8.13
+Provides-Extra: phone
+Requires-Dist: twilio>=9.0; extra == "phone"
+Provides-Extra: oauth
+Requires-Dist: social-auth-app-django>=5.4; extra == "oauth"
+Requires-Dist: python3-openid>=3.2; extra == "oauth"
+Provides-Extra: saml
+Requires-Dist: lxml>=5.0; extra == "saml"
+Requires-Dist: signxml>=3.2; extra == "saml"
+Provides-Extra: all
+Requires-Dist: stapel-auth[oauth,phone,saml]; extra == "all"
+Dynamic: license-file
+
+# stapel-auth
+
+[![CI](https://github.com/usestapel/stapel-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-auth/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-auth/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-auth)
+
+> Full-featured authentication — JWT, passkeys (WebAuthn), TOTP, QR login, OAuth2, SSO (SAML/OIDC), magic link, phone OTP
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-auth
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_auth',
+]
+```
+
+## Bus events
+
+### Emits
+| `user.session_created` | [schema](schemas/emits/user.session_created.json) | User successfully authenticated and a new session was created. |
+| `user.session_revoked` | [schema](schemas/emits/user.session_revoked.json) | A user session was revoked (logout or admin action). |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_auth-0.3.3/README.md

@@ -0,0 +1,34 @@
+# stapel-auth
+
+[![CI](https://github.com/usestapel/stapel-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-auth/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-auth/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-auth)
+
+> Full-featured authentication — JWT, passkeys (WebAuthn), TOTP, QR login, OAuth2, SSO (SAML/OIDC), magic link, phone OTP
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-auth
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_auth',
+]
+```
+
+## Bus events
+
+### Emits
+| `user.session_created` | [schema](schemas/emits/user.session_created.json) | User successfully authenticated and a new session was created. |
+| `user.session_revoked` | [schema](schemas/emits/user.session_revoked.json) | A user session was revoked (logout or admin action). |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_auth-0.3.3/__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-0.3.3/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-0.3.3/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-0.3.3/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-0.3.3/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-0.3.3/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())