oxutils 0.1.22__tar.gz → 0.3.2__tar.gz

{oxutils-0.1.22 → oxutils-0.3.2}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: oxutils
-Version: 0.1.22
+Version: 0.3.2
 Summary: Production-ready utilities for Django applications in the Oxiliere ecosystem
 Keywords: django,utilities,jwt,audit,logging,celery,structlog
 Author: Edimedia Mutoke
 Author-email: Edimedia Mutoke <eddycondor07@gmail.com>
-License-Expression: Apache-2.0
+License-Expression: LGPL-3.0-only
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 5.0
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -20,14 +20,17 @@ Requires-Dist: bcc-rates==1.1.1
 Requires-Dist: boto3>=1.41.5
 Requires-Dist: celery>=5.5.3
 Requires-Dist: cryptography>=46.0.3
+Requires-Dist: django-allauth[idp-oidc,mfa]>=65.18.0
 Requires-Dist: django-auditlog>=3.3.0
 Requires-Dist: django-celery-results>=2.6.0
 Requires-Dist: django-extensions>=4.1
 Requires-Dist: django-ninja>=1.5.0
 Requires-Dist: django-ninja-extra>=0.30.6
 Requires-Dist: django-structlog[celery]>=10.0.0
+Requires-Dist: django-user-agents>=0.4.0
 Requires-Dist: jwcrypto>=1.5.6
 Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic[email]>=2.12.5
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: requests>=2.32.5
 Requires-Dist: bcc-rates>=1.1.0 ; extra == 'all'

{oxutils-0.1.22 → oxutils-0.3.2}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "oxutils"
-version = "0.1.22"
+version = "0.3.2"
 description = "Production-ready utilities for Django applications in the Oxiliere ecosystem"
 readme = "README.md"
-license = "Apache-2.0"
+license = "LGPL-3.0-only"
 authors = [
     { name = "Edimedia Mutoke", email = "eddycondor07@gmail.com" }
 ]
@@ -14,7 +14,7 @@ classifiers = [
     "Framework :: Django",
     "Framework :: Django :: 5.0",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: Apache Software License",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
@@ -26,14 +26,17 @@ dependencies = [
     "boto3>=1.41.5",
     "celery>=5.5.3",
     "cryptography>=46.0.3",
+    "django-allauth[idp-oidc,mfa]>=65.18.0",
     "django-auditlog>=3.3.0",
     "django-celery-results>=2.6.0",
     "django-extensions>=4.1",
     "django-ninja>=1.5.0",
     "django-ninja-extra>=0.30.6",
     "django-structlog[celery]>=10.0.0",
+    "django-user-agents>=0.4.0",
     "jwcrypto>=1.5.6",
     "pydantic-settings>=2.12.0",
+    "pydantic[email]>=2.12.5",
     "pyjwt>=2.10.1",
     "requests>=2.32.5",
 ]
@@ -128,5 +131,12 @@ pythonpath = [".", "src"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-addopts = "-v --tb=short --ds=tests.settings"
+addopts = "-v --tb=short --ds=tests.settings --strict-markers"
 testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning:django.*",
+    "ignore::DeprecationWarning:pydantic.*",
+    "ignore::PendingDeprecationWarning:",
+    "ignore::pydantic.PydanticDeprecatedSince20:ninja.*",
+    "ignore::pydantic.PydanticDeprecatedSince20:ninja_extra.*",
+]

oxutils-0.3.2/src/oxutils/__init__.py

@@ -0,0 +1,28 @@
+"""OxUtils - Production-ready utilities for Django applications.
+
+This package provides:
+- JWT authentication with JWKS support
+- Multi-tenant architecture (django-tenants integration, middleware, signals)
+- Auth system: invitations, MFA, password reset, registration, sessions
+- Structured logging with correlation IDs
+- Audit system with S3 export
+- Celery integration
+- Django model mixins (ChangeTracker, CookieToken, SafeDelete)
+- Permission management & authorization
+- PDF generation
+- Pagination utilities
+- Currency utilities
+- Custom exceptions, enums, and type definitions
+"""
+
+__version__ = "0.3.1"
+
+from oxutils.conf import AUDIT_MIDDLEWARE, UTILS_APPS
+from oxutils.settings import oxi_settings
+
+__all__ = [
+    "oxi_settings",
+    "UTILS_APPS",
+    "AUDIT_MIDDLEWARE",
+    "__version__",
+]

oxutils-0.3.2/src/oxutils/auth/adapter.py

@@ -0,0 +1,212 @@
+from allauth.account import app_settings as allauth_app_settings
+from allauth.account.adapter import DefaultAccountAdapter
+from allauth.account.models import EmailAddress
+from allauth.core import context as allauth_ctx
+from django.contrib.sites.shortcuts import get_current_site
+from django.core.mail import EmailMessage, EmailMultiAlternatives
+from django.template import TemplateDoesNotExist
+from django.template.loader import render_to_string
+from django.utils.translation import gettext_lazy as _
+
+from oxutils.auth.utils import format_confirm_email_url, get_template_path
+
+
+class JWTAllAuthAdapter(DefaultAccountAdapter):
+    """
+    Custom account adapter extending allauth's DefaultAccountAdapter with JWT-specific email handling.
+
+    Provides enhanced email confirmation functionality with template path customization
+    and JWT-related email content handling.
+
+    Key Features:
+
+        - Email normalization (trimming and lowercasing)
+        - Customizable template paths for verification emails
+        - Dual template support (HTML/text) with fallback handling
+        - Integration with JWT verification workflows
+    """
+
+    def clean_email(self, email):
+        """
+        Normalize email addresses by trimming whitespace and converting to lowercase.
+
+        Args:
+            email (str): Raw email input
+
+        Returns:
+            str: Normalized email address
+        """
+        email = super().clean_email(email)
+        email = email.strip().lower()
+
+        if allauth_app_settings.UNIQUE_EMAIL:
+            if EmailAddress.objects.filter(email=email, verified=True).exists():
+                raise ValueError(_("A user is already registered with this e-mail address."))
+            # delete previous non-verified registration attempts
+            EmailAddress.objects.filter(email=email, verified=False).delete()
+
+        return email
+
+    def populate_username(self, request, user):
+        """
+        Override username population since our User model doesn't use usernames.
+
+        Our User model has username = None and uses email as USERNAME_FIELD,
+        so we skip the username generation process entirely.
+
+        Args:
+            request (HttpRequest): Current request object
+            user (User): User instance to populate
+        """
+        # Do nothing - our User model doesn't use usernames
+        pass
+
+    def get_email_confirmation_url(self, request, emailconfirmation):
+        return format_confirm_email_url(emailconfirmation.key)
+
+    def send_confirmation_mail(self, request, emailconfirmation, signup):
+        """
+        Generate and send email confirmation message with context customization.
+
+        Context Includes:
+
+            - User object
+            - Verification code or URL (based on EMAIL_VERIFICATION_BY_CODE_ENABLED)
+            - Site-specific information
+
+        Args:
+            request (HttpRequest): Current request object
+            emailconfirmation (EmailConfirmation): Email confirmation instance
+            signup (bool): Flag indicating if this is a signup confirmation
+
+        Returns:
+            str: Confirmation key used in the email
+        """
+        ctx = {
+            "user": emailconfirmation.email_address.user,
+        }
+        if allauth_app_settings.EMAIL_VERIFICATION_BY_CODE_ENABLED:
+            ctx.update({"code": emailconfirmation.key})
+        else:
+            ctx.update(
+                {
+                    "key": emailconfirmation.key,
+                    "activate_url": self.get_email_confirmation_url(request, emailconfirmation),
+                }
+            )
+        if signup:
+            email_template = "email/signup/email_signup"
+            template_path = get_template_path(
+                "EMAIL_VERIFICATION", "email/signup/email_message.html"
+            )
+            subject_path = get_template_path(
+                "EMAIL_VERIFICATION_SUBJECT", "email/signup/email_subject.txt"
+            )
+        else:
+            email_template = "account/email/email_confirmation"
+            template_path = None
+            subject_path = None
+        self.send_mail(
+            email_template,
+            emailconfirmation.email_address.email,
+            ctx,
+            subject_path=subject_path,
+            template_path=template_path,
+        )
+        return ctx["key"]
+
+    def send_mail(self, template_prefix, email, context, subject_path=None, template_path=None):
+        """
+        Construct and send email using template configuration.
+
+        Enhances Context With:
+
+            - Current site information
+            - Recipient email address
+
+        Args:
+            template_prefix (str): Base path for template lookup
+            email (str|list): Recipient email address(es)
+            context (dict): Template context variables
+            subject_path (str, optional): Custom path for subject template
+            template_path (str, optional): Custom path for body template
+        """
+        ctx = {
+            "email": email,
+            "current_site": get_current_site(allauth_ctx.request),
+        }
+        ctx.update(context)
+        msg = self.render_mail(
+            template_prefix, email, ctx, subject_path=subject_path, template_path=template_path
+        )
+        msg.send()
+
+    def render_mail(
+        self, template_prefix, email, context, headers=None, subject_path=None, template_path=None
+    ):
+        """
+        Render email message with support for multiple template formats and custom paths.
+
+        Behavior:
+
+            - Generates multipart emails when both HTML and text templates exist
+            - Uses custom template paths when provided
+            - Automatically formats email subject
+            - Supports HTML email content as primary when specified
+
+        Args:
+            template_prefix (str): Base template path prefix
+            email (str|list): Recipient email address(es)
+            context (dict): Template context variables
+            headers (dict, optional): Custom email headers
+            subject_path (str, optional): Override path for subject template
+            template_path (str, optional): Override path for body template
+
+        Returns:
+            EmailMessage: Configured email message object
+
+        Raises:
+            TemplateDoesNotExist: If no valid template can be found
+        """
+        to = [email] if isinstance(email, str) else email
+        if subject_path is None:
+            subject_path = "{0}_subject.txt".format(template_prefix)
+        subject = render_to_string(subject_path, context)
+        # remove superfluous line breaks
+        subject = " ".join(subject.splitlines()).strip()
+        subject = self.format_email_subject(subject)
+
+        from_email = self.get_from_email()
+
+        if template_path is None:
+            bodies = {}
+            html_ext = allauth_app_settings.TEMPLATE_EXTENSION
+            for ext in [html_ext, "txt"]:
+                try:
+                    template_name = "{0}_message.{1}".format(template_prefix, ext)
+                    bodies[ext] = render_to_string(
+                        template_name,
+                        context,
+                        allauth_ctx.request,
+                    ).strip()
+                except TemplateDoesNotExist:
+                    if ext == "txt" and not bodies:
+                        # We need at least one body
+                        raise
+        else:
+            html_ext = "html"
+            bodies = {
+                html_ext: render_to_string(
+                    template_path,
+                    context,
+                    allauth_ctx.request,
+                ).strip()
+            }
+        if "txt" in bodies:
+            msg = EmailMultiAlternatives(subject, bodies["txt"], from_email, to, headers=headers)
+            if html_ext in bodies:
+                msg.attach_alternative(bodies[html_ext], "text/html")
+        else:
+            msg = EmailMessage(subject, bodies[html_ext], from_email, to, headers=headers)
+            msg.content_subtype = "html"  # Main content is now text/html
+        return msg

oxutils-0.3.2/src/oxutils/auth/app_settings.py

@@ -0,0 +1,25 @@
+from django.conf import settings
+
+from oxutils.auth.password_reset.schemas import PasswordResetSchema as DefaultPasswordResetSchema
+from oxutils.auth.registration.schemas import RegisterSchema as DefaultRegisterSchema
+from oxutils.auth.schemas import (
+    LoginSchema as DefaultLoginSchema,
+)
+from oxutils.auth.schemas import (
+    PasswordChangeSchema as DefaultPasswordChangeSchema,
+)
+from oxutils.auth.utils import import_callable
+
+schemas = getattr(settings, "JWT_ALLAUTH_SCHEMAS", {})
+
+LoginSerializer = import_callable(schemas.get("LOGIN_SCHEMA", DefaultLoginSchema))
+
+PasswordResetSerializer = import_callable(
+    schemas.get("PASSWORD_RESET_SCHEMA", DefaultPasswordResetSchema)
+)
+
+PasswordChangeSerializer = import_callable(
+    schemas.get("PASSWORD_CHANGE_SCHEMA", DefaultPasswordChangeSchema)
+)
+
+RegisterSerializer = import_callable(schemas.get("REGISTER_SCHEMA", DefaultRegisterSchema))

oxutils-0.3.2/src/oxutils/auth/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class OxiAuthConfig(AppConfig):
+    name = 'oxutils.auth'
+    label = 'oxi_auth'

oxutils-0.3.2/src/oxutils/auth/constants.py

@@ -0,0 +1,14 @@
+PASS_RESET = 'PASS_RESET'
+PASS_RESET_ACCESS = 'PASS_RESET_ACCESS'
+TEMPLATE_PATHS = 'JWT_ALLAUTH_TEMPLATES'
+
+EMAIL_VERIFIED_REDIRECT = 'EMAIL_VERIFIED_REDIRECT'
+PASSWORD_RESET_REDIRECT = 'PASSWORD_RESET_REDIRECT'
+
+PASS_RESET_COOKIE = 'password_reset_access_token'
+
+FOR_USER = 'for_user'
+ONE_TIME_PERMISSION = 'one_time_permission'
+
+REFRESH_TOKEN_COOKIE = 'refresh_token'
+ACCESS_TOKEN_COOKIE = 'access_token'

oxutils-0.3.2/src/oxutils/auth/controllers.py

@@ -0,0 +1,203 @@
+from typing import Optional
+
+from django.http import HttpRequest
+from django.utils.translation import gettext_lazy as _
+from ninja_extra import ControllerBase, api_controller, http_post
+from ninja_extra.permissions import IsAuthenticated
+from ninja_extra.throttling import AnonRateThrottle, UserRateThrottle
+from ninja_jwt.exceptions import InvalidToken, TokenError
+from ninja_jwt.schema_control import SchemaControl
+from ninja_jwt.settings import api_settings
+
+from oxutils.auth.invitations.controllers import InvitationController
+from oxutils.auth.mixins import CookieTokenMixin
+from oxutils.auth.signals import user_logged_in, user_logged_out
+from oxutils.auth.password_reset.controllers import (
+    PasswordResetConfirmController,
+    PasswordResetController,
+    ResetNewPasswordController,
+)
+from oxutils.auth.registration.controllers import (
+    EmailVerificationController,
+    RegisterController,
+)
+from oxutils.auth.schemas import (
+    LoginSchema,
+    PasswordChangeResponseSchema,
+    PasswordChangeSchema,
+    ReauthenticatePasswordSchema,
+    RemoveRefreshTokenSchema,
+    SendVerificationEmailSchema,
+    TokenObtainMFARequiredSchema,
+    TokenObtainPairOutputSchema,
+    TokenRefreshInputSchema,
+    TokenRefreshOutputSchema,
+    TokenRefreshSchema,
+)
+from oxutils.auth.utils import (
+    get_refresh_token,
+    get_user_agent,
+    load_user,
+    sensitive_post_parameters_m,
+    user_agent_dict,
+)
+from oxutils.exceptions import ExceptionCode
+from oxutils.mixins.schemas import ResponseSchema
+
+schema = SchemaControl(api_settings)
+
+
+class LoginController(ControllerBase, CookieTokenMixin):
+    auto_import = False
+
+    @http_post(
+        "/login",
+        response={200: TokenObtainPairOutputSchema, 202: TokenObtainMFARequiredSchema},
+        url_name="token_obtain_pair",
+        operation_id="token_obtain_pair",
+        throttle=[AnonRateThrottle()],
+        auth=None,
+    )
+    def obtain_token(self, request: HttpRequest, user_token: LoginSchema):
+        user_token.check_user_authentication_rule()
+        schema = user_token.to_response_schema()
+
+        if schema.is_mfa_required():
+            return 202, schema
+
+        self.set_token_cookie(access_token=schema.access, refresh_token=schema.refresh)
+
+        user_logged_in.send_robust(sender=self.__class__, request=request, user=user_token._user)
+
+        return schema
+
+    @http_post(
+        "/verify-email",
+        response={
+            200: ResponseSchema,
+        },
+        throttle=[AnonRateThrottle()],
+        auth=None,
+    )
+    def send_verification_email(self, request: HttpRequest, payload: SendVerificationEmailSchema):
+        payload.send_verification_email(request)
+
+        return ResponseSchema(
+            code=ExceptionCode.SUCCESS, detail=str(_("Verification email sent successfully."))
+        )
+
+
+class ReauthenticateController(ControllerBase, CookieTokenMixin):
+    auto_import = False
+
+    @http_post(
+        "/reauthenticate",
+        response={
+            200: TokenObtainPairOutputSchema,
+        },
+        url_name="reauthenticate_password",
+        operation_id="reauthenticate_password",
+        throttle=[UserRateThrottle()],
+        permissions=[IsAuthenticated],
+    )
+    @load_user
+    def reauthenticate(self, request: HttpRequest, payload: ReauthenticatePasswordSchema):
+        schema = payload.authenticate(request)
+
+        self.set_token_cookie(access_token=schema.access, refresh_token=schema.refresh)
+
+        user_logged_in.send_robust(sender=self.__class__, request=request, user=request.user)
+
+        return schema
+
+
+class LogoutController(ControllerBase, CookieTokenMixin):
+    """
+    Calls Django logout method and delete the Token object
+    assigned to the current User object.
+
+    Accepts/Returns nothing.
+    """
+
+    @http_post("/logout", permissions=[IsAuthenticated], response={200: dict, 401: dict})
+    def logout(self, request: HttpRequest):
+        input_data = {"user": request.user.id}
+
+        refresh_token = get_refresh_token(request)
+
+        if not refresh_token:
+            raise InvalidToken
+
+        input_data["refresh"] = refresh_token
+
+        try:
+            RemoveRefreshTokenSchema.model_validate(input_data, context={"user": request.user.id})
+            self.remove_token_cookie()
+            user_logged_out.send_robust(sender=self.__class__, request=request, user=request.user)
+            return 200, {"detail": _("Successfully logged out.")}
+        except (TokenError, InvalidToken) as exc:
+            return 401, {"detail": _("Invalid token.")}
+
+
+class PasswordChangeController(ControllerBase):
+    @http_post(
+        "/change_password",
+        permissions=[IsAuthenticated],
+        throttle=[UserRateThrottle()],
+        response=PasswordChangeResponseSchema,
+    )
+    @sensitive_post_parameters_m
+    @load_user
+    def change_user_password(self, request: HttpRequest, payload: PasswordChangeSchema):
+        return payload.get_response(request)
+
+
+class TokenRefreshController(ControllerBase, CookieTokenMixin):
+    @http_post(
+        "/refresh",
+        auth=None,
+        response={200: TokenRefreshOutputSchema, 401: dict},
+        url_name="token_refresh",
+        operation_id="token_refresh",
+        throttle=[AnonRateThrottle()],
+    )
+    @get_user_agent
+    def refresh_token(self, request: HttpRequest, payload: Optional[TokenRefreshInputSchema]):
+        try:
+            input_data = {}
+            refresh_token = get_refresh_token(request)
+
+            if not refresh_token:
+                if payload.refresh is None:
+                    raise InvalidToken
+
+                refresh_token = payload.refresh
+
+            input_data["refresh"] = refresh_token
+            ctx = user_agent_dict(request)
+            tokens = TokenRefreshSchema.model_validate(input_data, context=ctx)
+
+            self.set_token_cookie(access_token=tokens["access"], refresh_token=tokens["refresh"])
+
+            return tokens
+        except (TokenError, InvalidToken) as exc:
+            return 401, {"detail": _("Invalid token.")}
+
+
+@api_controller(
+    "/auth",
+)
+class AuthController(
+    LoginController,
+    ReauthenticateController,
+    LogoutController,
+    PasswordChangeController,
+    TokenRefreshController,
+    EmailVerificationController,
+    RegisterController,
+    InvitationController,
+    PasswordResetConfirmController,
+    PasswordResetController,
+    ResetNewPasswordController,
+):
+    pass