django-pfx 1.7.3.dev26__tar.gz → 1.7.3.dev35__tar.gz

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-pfx
-Version: 1.7.3.dev26
+Version: 1.7.3.dev35
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-pfx
-Version: 1.7.3.dev26
+Version: 1.7.3.dev35
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/django_pfx.egg-info/SOURCES.txt

@@ -140,6 +140,7 @@ pfx/pfxcore/views/fields.py
 pfx/pfxcore/views/filters_views.py
 pfx/pfxcore/views/locale_views.py
 pfx/pfxcore/views/media_rest_view_mixin.py
+pfx/pfxcore/views/mfa_authentication_views.py
 pfx/pfxcore/views/ordered_rest_view_mixin.py
 pfx/pfxcore/views/rest_views.py
 pfx/pfxcore/views/parameters/__init__.py
@@ -185,6 +186,7 @@ pfx/userjobs/views/user_websocket_consumer.py
 tests/__init__.py
 tests/apps.py
 tests/channel_group_send_calls.py
+tests/mfa_urls.py
 tests/models.py
 tests/urls.py
 tests/views.py

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/django_pfx.egg-info/scm_file_list.json

@@ -14,6 +14,7 @@
     "setup.py",
     "setup.cfg",
     "tests/channel_group_send_calls.py",
+    "tests/mfa_urls.py",
     "tests/urls.py",
     "tests/views.py",
     "tests/__init__.py",
@@ -124,6 +125,7 @@
     "pfx/pfxcore/middleware/profiling.py",
     "pfx/pfxcore/middleware/request_too_big_middleware.py",
     "pfx/pfxcore/views/authentication_views.py",
+    "pfx/pfxcore/views/mfa_authentication_views.py",
     "pfx/pfxcore/views/filters_views.py",
     "pfx/pfxcore/views/media_rest_view_mixin.py",
     "pfx/pfxcore/views/locale_views.py",

django_pfx-1.7.3.dev35/django_pfx.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.7.2",
+  "distance": 35,
+  "node": "gd7bce9634adc6a4594cbaad209c36133aba3e845",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-14"
+}

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/doc/source/api.views.rst

@@ -151,6 +151,11 @@ Base services
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: pfx.pfxcore.views.MFAAuthenticationView
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. autoclass:: pfx.pfxcore.views.SignupView
     :members:
     :undoc-members:

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/doc/source/authentication.md

@@ -126,6 +126,31 @@ class MyUser(MFAUserMixin, AbstractPFXBaseUser):
     pass
 ```
 
+Finally, the MFA endpoints (OTP login, challenge and backend management) are provided by
+{class}`pfx.pfxcore.views.MFAAuthenticationView`, a subclass of
+{class}`pfx.pfxcore.views.AuthenticationView`. Register it **instead of** the plain
+`AuthenticationView` in your urls:
+
+```python
+from django.urls import path, include
+from pfx.pfxcore import register_views
+from pfx.pfxcore.views import MFAAuthenticationView
+
+urlpatterns = [
+    path('api/', include(register_views(MFAAuthenticationView))),
+]
+```
+
+With the default `AuthenticationView`, the `/auth/otp/login` and `/auth/mfa/*` endpoints are not
+registered and login never returns `need_otp` — MFA is effectively disabled regardless of the user
+mixin or settings.
+
+```{note}
+**Migrating from a previous version.** The MFA endpoints used to live on `AuthenticationView`; they
+have moved to {class}`pfx.pfxcore.views.MFAAuthenticationView`. If you rely on MFA, register that
+view (see above) in place of `AuthenticationView`.
+```
+
 ```{note}
 **Migrating from a previous version.** The MFA state used to live directly on the user table
 (`otp_secret_token`, `mfa_*_enabled`, `sms_phone_number`, …) with a single shared secret. It now
@@ -147,9 +172,12 @@ removed.
   {class}`pfx.pfxcore.mfa.MFABackend` subclass and add its dotted path to the list; to override a
   built-in, list your subclass (keeping the same `id`) in place of the built-in path.
 * `PFX_MFA_FORCE`: If `True`, MFA is required for all users — a `mfa_setup_required` flag is returned
-  at login when the user has not yet dismissed the setup screen (optional, default `False`).
+  at login as long as the user has neither configured a backend nor dismissed the setup screen
+  (optional, default `False`). It is cleared as soon as any backend is confirmed (email only is
+  enough) or the user calls `PUT /auth/mfa/dismiss`.
   A forced user who has not enrolled yet still receives an email code challenge at first login
-  (the email backend is always available).
+  (the email backend is always available). While MFA is forced, the email backend cannot be
+  disabled (nor can MFA be disabled globally); the other backends can still be disabled.
 * `PFX_SMS_BACKEND`: Dotted path to the SMS backend class (optional, default
   `'pfx.pfxcore.sms.backends.console.ConsoleSMSBackend'`).
   Implement {class}`pfx.pfxcore.sms.backends.base.BaseSMSBackend` to integrate a real SMS provider.
@@ -178,7 +206,7 @@ In cookie mode, the JWT token is saved in an HTTP-only cookie.
       alt Authentication success
         API->>App: 200 OK + cookie
       else Authentication failed
-        API->>App: 401 Unautorized
+        API->>App: 422 Unprocessable Entity
       end
 
 ```
@@ -195,14 +223,14 @@ In cookie mode, the JWT token is saved in an HTTP-only cookie.
 
 **Responses :**
 
-* `HTTP 401` if the credentials are incorrect
+* `HTTP 422` if the credentials are incorrect (a global `__all__` error)
 * `HTTP 200` with the following body
 
 | Field              | Description                                                            |
 |--------------------|------------------------------------------------------------------------|
 | token              | the jwt token (only if mode is `jwt`)                                  |
 | user               | the user object                                                        |
-| mfa_setup_required | `true` if MFA is forced and the user has not yet dismissed setup screen |
+| mfa_setup_required | `true` if MFA is forced and the user has neither configured a backend nor dismissed the setup screen |
 
 
 ### Login + MFA
@@ -228,10 +256,10 @@ triggers a challenge for out-of-band backends (email / SMS).
             API->>App: 200 OK
             note left of API: JWT token in cookie or in body <br/> + user in body
         else OTP failed
-            API->>App: 401 Unauthorized
+            API->>App: 422 Unprocessable Entity
         end
       else Login failed
-        API->>App: 401 Unauthorized
+        API->>App: 422 Unprocessable Entity
       end
 
 ```
@@ -248,7 +276,7 @@ triggers a challenge for out-of-band backends (email / SMS).
 
 **Responses :**
 
-* `HTTP 401` if the credentials are incorrect
+* `HTTP 422` if the credentials are incorrect (a global `__all__` error)
 * `HTTP 200` with the following body when MFA is required (`need_otp=true`)
 
 | Field              | Description                                                           |
@@ -298,7 +326,7 @@ the highest-priority available backend is used.
 **Responses :**
 
 * `HTTP 401` if the temporary jwt token is incorrect
-* `HTTP 422` if the otp code is incorrect
+* `HTTP 422` if the otp code is incorrect (an `otp_code` field error)
 * `HTTP 200` with the following body
 
 | Field | Description                            |
@@ -318,6 +346,14 @@ The **disable** step deactivates the backend after verifying an OTP code from **
 backend (e.g. you can disable SMS with an authenticator or email code). Disabling the email (base)
 backend disables MFA entirely. A dedicated `PUT /auth/mfa/disable` disables all backends at once.
 
+To obtain that code on an out-of-band backend (email/SMS), an **authenticated** user can request a
+challenge with `PUT /auth/mfa/{email|sms}/challenge` — it sends a code using the same delivery
+service as the login challenge (authenticator codes are generated locally and need no request).
+
+When MFA is forced (`PFX_MFA_FORCE`), the email backend must stay active: disabling it — or calling
+`PUT /auth/mfa/disable` — is rejected with `HTTP 400`. The other backends (`authenticator`, `sms`)
+can still be disabled individually.
+
 ```{note}
 To change an OOB target (e.g. a new phone number), disable the backend then enroll it again with
 the new value. The email backend's target is always the user's account email and is changed through
@@ -359,6 +395,19 @@ authenticated user.
 }
 ```
 
+#### Request a challenge code (authenticated)
+
+**Request:** `PUT` `/auth/mfa/{email|sms}/challenge`
+
+Sends a challenge code on a **confirmed** out-of-band backend for the authenticated user, so they
+can authorise a sensitive operation such as disabling a backend. Uses the same delivery service as
+the login challenge. No request body.
+
+**Responses:**
+
+* `HTTP 403` if the backend is not out-of-band or is not enabled for the user
+* `HTTP 200` with a confirmation message
+
 #### Authenticator (TOTP)
 
 **Request:** `GET` `/auth/mfa/authenticator/setup`
@@ -454,6 +503,7 @@ backends are removed too). Requires a valid OTP code from any confirmed backend.
 
 **Responses:**
 
+* `HTTP 400` if MFA is forced (email cannot be disabled)
 * `HTTP 422` if the code is invalid
 * `HTTP 200` with a new JWT token and updated user object
 
@@ -529,9 +579,22 @@ Disables MFA entirely (all backends). Requires a valid OTP code from any confirm
 
 **Responses:**
 
+* `HTTP 400` if MFA is forced (MFA cannot be disabled)
 * `HTTP 422` if the code is invalid
 * `HTTP 200` with a new JWT token and updated user object
 
+---
+
+**Request:** `PUT` `/auth/mfa/dismiss`
+
+Dismisses the MFA setup screen when MFA is forced: the user states they do not want to configure
+any backend beyond email. This clears `mfa_setup_required` without enabling an extra backend (email
+stays the fallback). No request body and no OTP code required.
+
+**Responses:**
+
+* `HTTP 200` with a new JWT token and updated user object (`mfa_setup_required` is now `false`)
+
 
 ### Logout
 A service that deletes the authentication cookie if it exists.

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/pfx/pfxcore/exceptions.py

@@ -26,6 +26,8 @@ class APIError(Exception):
 
         self.status = status
         if validation_error:
+            # For 400 error (not validation 422 errors)
+            # allow to send debug validations errors in the api return
             errors = []
             errors_dict = validation_error_dict(validation_error)
             for k, v in errors_dict.items():
@@ -77,11 +79,8 @@ class RelatedModelNotFoundAPIError(ModelValidationAPIError):
             status=status, delete_cookie=delete_cookie, **kwargs)
 
 
-class AuthenticationError(APIError):
-    def __init__(self, message=None, status=422, **kwargs):
-        super().__init__(
-            f(message or _("Login failed")),
-            status=status, **kwargs)
+class AuthenticationError(ModelValidationAPIError):
+    pass
 
 
 class UnauthorizedError(APIError):

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/pfx/pfxcore/locale/fr/LC_MESSAGES/django.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-06-23 10:26+0200\n"
+"POT-Creation-Date: 2026-07-08 16:13+0200\n"
 "PO-Revision-Date: 2021-06-22 23:31+0200\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -28,28 +28,24 @@ msgstr ""
 "Une erreur système s’est produite. Notre équipe d’assistance en a été "
 "informée."
 
-#: exceptions.py:53 exceptions.py:76
+#: exceptions.py:55 exceptions.py:78
 #, python-brace-format
 msgid "{model} not found."
 msgstr "{model} non trouvé."
 
-#: exceptions.py:60
+#: exceptions.py:62
 msgid "JSON Malformed {}"
 msgstr "JSON malformé {}"
 
-#: exceptions.py:83
-msgid "Login failed"
-msgstr "La connexion a échoué"
-
-#: exceptions.py:90
+#: exceptions.py:89
 msgid "Unauthorized"
 msgstr "Non autorisé"
 
-#: exceptions.py:97
+#: exceptions.py:96
 msgid "Forbidden"
 msgstr "Interdit"
 
-#: exceptions.py:104
+#: exceptions.py:103
 msgid "Resource not found"
 msgstr "Ressource non trouvée"
 
@@ -103,22 +99,20 @@ msgid "Login bans"
 msgstr "Login bannis"
 
 #: models/mfa_device.py:20
-#, fuzzy
-#| msgid "Username"
 msgid "User"
-msgstr "Nom d’utilisateur"
+msgstr "Utilisateur"
 
 #: models/mfa_device.py:22
 msgid "Backend"
-msgstr ""
+msgstr "Backend"
 
 #: models/mfa_device.py:24
 msgid "Secret"
-msgstr ""
+msgstr "Secret"
 
 #: models/mfa_device.py:26
 msgid "Confirmed"
-msgstr ""
+msgstr "Confirmé"
 
 #: models/mfa_device.py:28
 msgid "HOTP count"
@@ -130,21 +124,21 @@ msgstr "Expiration HOTP"
 
 #: models/mfa_device.py:34
 msgid "Target"
-msgstr ""
+msgstr "Cible"
 
 #: models/mfa_device.py:37
 msgid "MFA device"
-msgstr ""
+msgstr "Appareil MFA"
 
 #: models/mfa_device.py:38
 msgid "MFA devices"
-msgstr ""
+msgstr "Appareils MFA"
 
 #: models/mfa_user_mixin.py:20
 msgid "MFA signature key"
-msgstr ""
+msgstr "Clé de signature MFA"
 
-#: models/mfa_user_mixin.py:23
+#: models/mfa_user_mixin.py:23 views/mfa_authentication_views.py:523
 msgid "MFA setup dismissed"
 msgstr "Configuration MFA annulée"
 
@@ -172,7 +166,7 @@ msgstr "Numéro de téléphone (SMS)"
 msgid "MFA setup required"
 msgstr "Configuration MFA requise"
 
-#: models/mfa_user_mixin.py:75
+#: models/mfa_user_mixin.py:82
 msgid "Is MFA forced"
 msgstr "MFA est forcé"
 
@@ -282,7 +276,11 @@ msgstr "Bienvenue sur %(site_name)s."
 msgid "Welcome on %(site_name)s"
 msgstr "Bienvenue sur %(site_name)s"
 
-#: views/authentication_views.py:95
+#: views/authentication_views.py:80
+msgid "Login failed"
+msgstr "La connexion a échoué"
+
+#: views/authentication_views.py:89
 #, python-brace-format
 msgid ""
 "Your connection is temporarily disabled after several unsuccessful attempts, "
@@ -291,78 +289,31 @@ msgstr ""
 "Votre connexion est temporairement désactivée après plusieurs tentatives "
 "infructueuses, veuillez réessayer dans {seconds} secondes."
 
-#: views/authentication_views.py:191
+#: views/authentication_views.py:181
 msgid "Successful login"
 msgstr "Connexion réussie"
 
-#: views/authentication_views.py:293
-msgid "This field is required."
-msgstr "Ce champ est requis."
-
-#: views/authentication_views.py:299 views/authentication_views.py:419
-msgid "Code sent."
-msgstr "Code envoyé."
-
-#: views/authentication_views.py:402
-#, fuzzy
-#| msgid "MFA enabled"
-msgid "MFA must be enabled first"
-msgstr "MFA activé"
-
-#: views/authentication_views.py:405
-#, fuzzy
-#| msgid "Email MFA is already enabled"
-msgid "This MFA backend is already enabled"
-msgstr "MFA par email déjà activé."
-
-#: views/authentication_views.py:416
-msgid "Phone number is required."
-msgstr "Le numéro de téléphone est requis."
-
-#: views/authentication_views.py:456
-#, fuzzy
-#| msgid "MFA enabled"
-msgid "MFA backend enabled"
-msgstr "MFA activé"
-
-#: views/authentication_views.py:458 views/authentication_views.py:493
-#: views/authentication_views.py:531
-msgid "Invalid code"
-msgstr "Code invalide"
-
-#: views/authentication_views.py:497
-#, fuzzy
-#| msgid "MFA enabled"
-msgid "MFA backend disabled"
-msgstr "MFA activé"
-
-#: views/authentication_views.py:535
-#, fuzzy
-#| msgid "SMS MFA disabled"
-msgid "MFA disabled"
-msgstr "MFA par SMS désactivé"
-
-#: views/authentication_views.py:598 views/authentication_views.py:766
+#: views/authentication_views.py:255 views/authentication_views.py:423
 msgid "password updated successfully"
 msgstr "le mot de passe a été mis à jour avec succès"
 
-#: views/authentication_views.py:603
+#: views/authentication_views.py:260
 msgid "Incorrect password"
 msgstr "Mot de passe incorrect"
 
-#: views/authentication_views.py:606 views/authentication_views.py:775
+#: views/authentication_views.py:263 views/authentication_views.py:432
 msgid "Empty password is not allowed"
 msgstr "Un mot de passe vide n’est pas autorisé"
 
-#: views/authentication_views.py:695
+#: views/authentication_views.py:352
 msgid "User and token are valid"
 msgstr "L’utilisateur et le token sont valides"
 
-#: views/authentication_views.py:697
+#: views/authentication_views.py:354
 msgid "User or token is invalid"
 msgstr "L’utilisateur ou le token est invalide"
 
-#: views/authentication_views.py:1042
+#: views/authentication_views.py:631
 msgid ""
 "If the email address you entered is correct, you will receive an email from "
 "us with instructions to reset your password."
@@ -380,6 +331,48 @@ msgstr "Valeur invalide pour le filtre {filter}"
 msgid "Unexpected storage error"
 msgstr "Erreur de stockage inattendue"
 
+#: views/mfa_authentication_views.py:161 views/mfa_authentication_views.py:407
+#: views/mfa_authentication_views.py:446 views/mfa_authentication_views.py:488
+msgid "Invalid code"
+msgstr "Code invalide"
+
+#: views/mfa_authentication_views.py:208
+msgid "This field is required."
+msgstr "Ce champ est requis."
+
+#: views/mfa_authentication_views.py:214 views/mfa_authentication_views.py:288
+#: views/mfa_authentication_views.py:368
+msgid "Code sent."
+msgstr "Code envoyé."
+
+#: views/mfa_authentication_views.py:351
+msgid "MFA must be enabled first"
+msgstr "Le MFA doit d’abord être activé"
+
+#: views/mfa_authentication_views.py:354
+msgid "This MFA backend is already enabled"
+msgstr "Ce backend MFA est déjà activé"
+
+#: views/mfa_authentication_views.py:365
+msgid "Phone number is required."
+msgstr "Le numéro de téléphone est requis."
+
+#: views/mfa_authentication_views.py:405
+msgid "MFA backend enabled"
+msgstr "Backend MFA activé"
+
+#: views/mfa_authentication_views.py:441 views/mfa_authentication_views.py:483
+msgid "MFA is required and cannot be disabled"
+msgstr "Le MFA est requis et ne peut pas être désactivé"
+
+#: views/mfa_authentication_views.py:450
+msgid "MFA backend disabled"
+msgstr "Backend MFA désactivé"
+
+#: views/mfa_authentication_views.py:492
+msgid "MFA disabled"
+msgstr "MFA désactivé"
+
 #: views/ordered_rest_view_mixin.py:32
 #, python-brace-format
 msgid "object parameter is mandatory for move={move}."

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/pfx/pfxcore/mfa/base.py

@@ -52,6 +52,14 @@ class MFABackend:
         """Confirm the activation with a code. Returns ``True`` on success."""
         raise NotImplementedError
 
+    def can_disable(self, user):
+        """Return ``True`` if the user is allowed to disable this backend.
+
+        The base backend (email) cannot be disabled while MFA is forced: it
+        must stay available so a forced user can always receive a login code.
+        Other backends can always be disabled."""
+        return not (self.is_base and user.mfa_forced)
+
     def disable(self, user):
         """Disable this backend by removing its device."""
         device = self.get_device(user)

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/pfx/pfxcore/models/mfa_user_mixin.py

@@ -70,7 +70,14 @@ class MFAUserMixin(models.Model):
 
     @rest_property(_("MFA setup required"), "BooleanField")
     def mfa_setup_required(self):
-        return self.mfa_forced and not self.mfa_setup_dismissed
+        """Return True if the forced user must still choose a MFA setup.
+
+        Cleared once the user either configured a backend (any confirmed
+        device, e.g. email only) or explicitly dismissed the setup screen."""
+        return (
+            self.mfa_forced
+            and not self.mfa_setup_dismissed
+            and not self.mfa_devices.filter(confirmed=True).exists())
 
     @rest_property(_("Is MFA forced"), "BooleanField")
     def mfa_forced(self):

{django_pfx-1.7.3.dev26 → django_pfx-1.7.3.dev35}/pfx/pfxcore/views/__init__.py

@@ -12,6 +12,7 @@ from .media_rest_view_mixin import (
     MediaRestViewMixin,
     get_media_field_response,
 )
+from .mfa_authentication_views import MFAAuthenticationView
 from .ordered_rest_view_mixin import OrderedRestViewMixin
 from .rest_views import (
     BaseRestView,