django-pfx 1.7.2.dev8__tar.gz → 1.7.2.dev12__tar.gz

{django_pfx-1.7.2.dev8 → django_pfx-1.7.2.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-pfx
-Version: 1.7.2.dev8
+Version: 1.7.2.dev12
 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.2.dev8 → django_pfx-1.7.2.dev12}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-pfx
-Version: 1.7.2.dev8
+Version: 1.7.2.dev12
 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.2.dev8 → django_pfx-1.7.2.dev12}/django_pfx.egg-info/SOURCES.txt

@@ -75,14 +75,18 @@ pfx/pfxcore/models/__init__.py
 pfx/pfxcore/models/abstract_pfx_base_user.py
 pfx/pfxcore/models/cache_mixins.py
 pfx/pfxcore/models/login_ban.py
+pfx/pfxcore/models/mfa_user_mixin.py
 pfx/pfxcore/models/not_null_fields.py
 pfx/pfxcore/models/ordered_model_mixin.py
-pfx/pfxcore/models/otp_user_mixin.py
 pfx/pfxcore/models/pfx_models.py
 pfx/pfxcore/models/pfx_user.py
 pfx/pfxcore/models/user_filtered_queryset_mixin.py
 pfx/pfxcore/serializers/__init__.py
 pfx/pfxcore/serializers/json.py
+pfx/pfxcore/sms/__init__.py
+pfx/pfxcore/sms/backends/__init__.py
+pfx/pfxcore/sms/backends/base.py
+pfx/pfxcore/sms/backends/console.py
 pfx/pfxcore/storage/__init__.py
 pfx/pfxcore/storage/exceptions.py
 pfx/pfxcore/storage/local_storage.py
@@ -130,6 +134,7 @@ tests/locale/fr/LC_MESSAGES/django.po
 tests/migrations/0001_initial.py
 tests/migrations/0002_alter_book_cover.py
 tests/migrations/0003_book_local_file.py
+tests/migrations/0004_mfausermixin_fields.py
 tests/migrations/__init__.py
 tests/settings/__init__.py
 tests/settings/ci.py

{django_pfx-1.7.2.dev8 → django_pfx-1.7.2.dev12}/doc/source/authentication.md

@@ -89,8 +89,11 @@ the `Retry-After` header.
 ### Multifactor Authentication
 Multifactor authentication can be enabled in django-pfx Authentication API.
 
-PFX currently provides MFA with One Time Password (OTP), compatible with FreeOTP,
-Google Authenticator and other OTP app.
+PFX supports three MFA backends:
+
+* **`authenticator`** — TOTP, compatible with FreeOTP, Google Authenticator and other OTP apps.
+* **`email`** — a HOTP code sent by email.
+* **`sms`** — a HOTP code sent by SMS.
 
 To enable this feature, install django-pfx with otp.
 
@@ -98,35 +101,46 @@ To enable this feature, install django-pfx with otp.
 pip install django-pfx[otp]
 ```
 
-Then the user class must use the {class}`pfx.pfxcore.models.OtpUserMixin`.
+Then the user class must use the {class}`pfx.pfxcore.models.MFAUserMixin`.
 
 ```python
-from pfx.pfxcore.models import PFXUser, OtpUserMixin
+from pfx.pfxcore.models import PFXUser, MFAUserMixin
 
-class MyUser(OtpUserMixin, PFXUser):
+class MyUser(MFAUserMixin, PFXUser):
     pass
 ```
 
 or
 
 ```python
-from pfx.pfxcore.models import AbstractPFXBaseUser, OtpUserMixin
+from pfx.pfxcore.models import AbstractPFXBaseUser, MFAUserMixin
 
-class MyUser(OtpUserMixin, AbstractPFXBaseUser):
+class MyUser(MFAUserMixin, AbstractPFXBaseUser):
     pass
 ```
 
+:::{note}
+`OtpUserMixin` is a deprecated alias for `MFAUserMixin` and will be removed in a future version.
+:::
+
 #### Settings
 
+* `PFX_MFA_BACKENDS`: Ordered list of enabled MFA backends (optional, default `["authenticator", "email"]`).
+  The first backend for which the user is enrolled is used at login.
+* `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`).
+* `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.
 * `PFX_TOKEN_OTP_VALIDITY`: Validity for OTP tokens (corresponds to the maximum time to enter
   an OTP code after logging in with a password) (optional, default `{'minutes': 15}`)
-* `PFX_HOTP_CODE_VALIDITY`: Validity of HOTP codes in minutes (used to send code by email) (optional, default `15`).
+* `PFX_HOTP_CODE_VALIDITY`: Validity of HOTP codes in minutes (used to send code by email or SMS) (optional, default `15`).
 * `PFX_OTP_VALID_WINDOW`: TOTP valid window (optional, default `1`).
   According to [RFC 6238 section 5.2](https://www.ietf.org/rfc/rfc6238.html#section-5.2).
 * `PFX_OTP_IMAGE`: An image https URL used by FreeOTP. See [FreeOTP URI](https://github.com/npmccallum/freeotp-android/blob/master/URI.md).
 * `PFX_OTP_COLOR`: A brand color (in RRGGBB format) for used by FreeOTP. See [FreeOTP URI](https://github.com/npmccallum/freeotp-android/blob/master/URI.md).
 
-The user can then enable or disable the OTP auth using the [services documented below](#enable-mfa-otp).
+The user can then enable or disable the authenticator OTP using the [services documented below](#enable-mfa-otp).
 
 ## Services
 
@@ -163,15 +177,16 @@ In cookie mode, the JWT token is saved in an HTTP-only cookie.
 * `HTTP 401` if the credentials are incorrect
 * `HTTP 200` with the following body
 
-| Field | Description                            |
-|-------|----------------------------------------|
-| token | the jwt token. (only if mode is 'jwt') |
-| user  | the user object                        |
+| 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 |
 
 
-### Login + TOTP
-If the user has enabled the TOTP login, the process is the same as above for the first step,
-except that the login service returns a temporary JWT token valid only for the otp services.
+### Login + MFA
+If the user has an active MFA backend, the login service returns a temporary JWT token and
+triggers a challenge for out-of-band backends (email / SMS).
 
 ```{mermaid}
 
@@ -179,19 +194,23 @@ except that the login service returns a temporary JWT token valid only for the o
       participant App
       participant API
       App->>API: POST /auth/login
-      alt Login success
+      alt Login success + MFA required
         API->>App: 200 OK
-        note left of API: temporary jwt token
+        note left of API: need_otp=true + temporary jwt token<br/>+ mfa_backend + available_backends
+        opt Switch backend or resend code
+            App->>API: POST /mfa/challenge
+            note right of App: temporary jwt token + mfa_backend
+        end
         App->>API: POST /auth/otp/login
-        note right of App: temporary jwt token + OTP token in body.
+        note right of App: temporary jwt token + OTP code in body
         alt OTP success
             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 Unautorized
+            API->>App: 401 Unauthorized
         end
       else Login failed
-        API->>App: 401 Unautorized
+        API->>App: 401 Unauthorized
       end
 
 ```
@@ -209,21 +228,47 @@ except that the login service returns a temporary JWT token valid only for the o
 **Responses :**
 
 * `HTTP 401` if the credentials are incorrect
-* `HTTP 200` with the following body
+* `HTTP 200` with the following body when MFA is required (`need_otp=true`)
+
+| Field              | Description                                                           |
+|--------------------|-----------------------------------------------------------------------|
+| need_otp           | `true`                                                                |
+| token              | a temporary jwt token (valid only for OTP/MFA endpoints)              |
+| mfa_backend        | object with `id` (e.g. `"authenticator"`, `"email"`, `"sms"`) and `is_oob` |
+| available_backends | list of backend objects (`id`, `is_oob`) available for this user      |
+
+`is_oob` (*out-of-band*) is `true` when the code is delivered via a separate channel (email or SMS),
+as opposed to `authenticator` where the code is generated locally in the user's app.
+
+For OOB backends (`is_oob: true`), a challenge code is sent automatically at this step.
 
-| Field | Description           |
-|-------|-----------------------|
-| token | a temporary jwt token |
+
+**Request :** `POST` `/mfa/challenge`
+
+Request a new challenge code or switch to a different OOB backend (email or SMS).
+
+**Request body:**
+
+| Field       | Description                                       |
+|-------------|---------------------------------------------------|
+| token       | the temporary jwt token                           |
+| mfa_backend | the backend to use (`"email"` or `"sms"`)         |
+
+**Responses :**
+
+* `HTTP 401` if the token is missing, invalid or expired
+* `HTTP 403` if the requested backend is not available for this user
+* `HTTP 200` with a confirmation message
 
 
 **Request :** `POST` `/auth/otp/login?mode=<mode>`
 
 **Request body:**
 
-| Field       | Description                         |
-|-------------|-------------------------------------|
-| token       | the temporary jwt token             |
-| otp         | the one time password (TOTP)        |
+| Field | Description                                          |
+|-------|------------------------------------------------------|
+| token | the temporary jwt token                              |
+| otp   | the one-time password (TOTP code or emailed/SMS code)|
 
 **Responses :**
 
@@ -233,7 +278,7 @@ except that the login service returns a temporary JWT token valid only for the o
 
 | Field | Description                            |
 |-------|----------------------------------------|
-| token | the jwt token. (only if mode is 'jwt') |
+| token | the jwt token. (only if mode is `jwt`) |
 | user  | the user object                        |
 
 ### Enable MFA OTP

{django_pfx-1.7.2.dev8 → django_pfx-1.7.2.dev12}/pfx/pfxcore/default_settings.py

@@ -37,3 +37,8 @@ STORAGE_LOCAL_X_ACCEL_REDIRECT = False
 PFX_TEST_MODE = False
 
 PFX_AUTH_GROUPS_CREATE_ONLY = False
+
+PFX_MFA_BACKENDS = ["authenticator", "email"]
+PFX_MFA_FORCE = False
+
+PFX_SMS_BACKEND = 'pfx.pfxcore.sms.backends.console.ConsoleSMSBackend'

{django_pfx-1.7.2.dev8 → django_pfx-1.7.2.dev12}/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-04-20 13:42+0200\n"
+"POT-Creation-Date: 2026-04-20 16:17+0200\n"
 "PO-Revision-Date: 2021-06-22 23:31+0200\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -87,23 +87,45 @@ msgstr "Login banni"
 msgid "Login bans"
 msgstr "Login bannis"
 
-#: models/otp_user_mixin.py:16
+#: models/mfa_user_mixin.py:19
 msgid "OTP secret token"
 msgstr "Jeton secret OTP"
 
-#: models/otp_user_mixin.py:20
+#: models/mfa_user_mixin.py:23
 msgid "Temporary OTP secret token"
 msgstr "Jeton secret OTP temporaire"
 
-#: models/otp_user_mixin.py:22
+#: models/mfa_user_mixin.py:25
 msgid "HOTP count"
 msgstr "Compte HOTP"
 
-#: models/otp_user_mixin.py:24
+#: models/mfa_user_mixin.py:27
 msgid "HOTP expiry"
 msgstr "Expiration HOTP"
 
-#: models/otp_user_mixin.py:29 views/authentication_views.py:504
+#: models/mfa_user_mixin.py:30
+msgid "SMS phone number"
+msgstr "Numéro de téléphone (SMS)"
+
+#: models/mfa_user_mixin.py:33
+msgid "Temporary SMS phone number"
+msgstr "Numéro de téléphone temporaire (SMS)"
+
+#: models/mfa_user_mixin.py:35
+#, fuzzy
+#| msgid "OTP enabled"
+msgid "SMS MFA enabled"
+msgstr "OTP activé"
+
+#: models/mfa_user_mixin.py:37
+msgid "Email MFA enabled"
+msgstr "MFA par email activé"
+
+#: models/mfa_user_mixin.py:40
+msgid "MFA setup dismissed"
+msgstr "Configuration MFA annulée"
+
+#: models/mfa_user_mixin.py:47 views/authentication_views.py:712
 msgid "OTP enabled"
 msgstr "OTP activé"
 
@@ -209,7 +231,12 @@ msgstr "Bienvenue sur %(site_name)s."
 msgid "Welcome on %(site_name)s"
 msgstr "Bienvenue sur %(site_name)s"
 
-#: views/authentication_views.py:83
+#: views/authentication_views.py:98
+#, python-brace-format
+msgid "Your {site_name} verification code: {otp_code}"
+msgstr "Votre code pour {site_name} : {otp_code}"
+
+#: views/authentication_views.py:113
 #, python-brace-format
 msgid ""
 "Your connection is temporarily disabled after several unsuccessful attempts, "
@@ -218,43 +245,51 @@ msgstr ""
 "Votre connexion est temporairement désactivée après plusieurs tentatives "
 "infructueuses, veuillez réessayer dans {seconds} secondes."
 
-#: views/authentication_views.py:177
+#: views/authentication_views.py:214
 msgid "Successful login"
 msgstr "Connexion réussie"
 
-#: views/authentication_views.py:251 views/authentication_views.py:421
+#: views/authentication_views.py:385
+msgid "This field is required."
+msgstr "Ce champ est requis."
+
+#: views/authentication_views.py:396
+msgid "Code sent."
+msgstr "Code envoyé."
+
+#: views/authentication_views.py:459 views/authentication_views.py:629
 msgid "password updated successfully"
 msgstr "le mot de passe a été mis à jour avec succès"
 
-#: views/authentication_views.py:256
+#: views/authentication_views.py:464
 msgid "Incorrect password"
 msgstr "Mot de passe incorrect"
 
-#: views/authentication_views.py:259 views/authentication_views.py:430
+#: views/authentication_views.py:467 views/authentication_views.py:638
 msgid "Empty password is not allowed"
 msgstr "Un mot de passe vide n’est pas autorisé"
 
-#: views/authentication_views.py:350
+#: views/authentication_views.py:558
 msgid "User and token are valid"
 msgstr "L'utilisateur et le token sont valides"
 
-#: views/authentication_views.py:352
+#: views/authentication_views.py:560
 msgid "User or token is invalid"
 msgstr "L'utilisateur ou le token est invalide"
 
-#: views/authentication_views.py:464
+#: views/authentication_views.py:672
 msgid "OTP is already enabled"
 msgstr "OTP est déjà activé"
 
-#: views/authentication_views.py:505 views/authentication_views.py:541
+#: views/authentication_views.py:713 views/authentication_views.py:749
 msgid "Invalid code"
 msgstr "Code invalide"
 
-#: views/authentication_views.py:540
+#: views/authentication_views.py:748
 msgid "OTP disabled"
 msgstr "OTP désactivé"
 
-#: views/authentication_views.py:801
+#: views/authentication_views.py:1009
 msgid ""
 "If the email address you entered is correct, you will receive an email from "
 "us with instructions to reset your password."
@@ -263,7 +298,7 @@ msgstr ""
 "un courrier électronique de notre part contenant des instructions pour "
 "réinitialiser votre mot de passe."
 
-#: views/authentication_views.py:875
+#: views/authentication_views.py:1083
 msgid "A new authentication code has been sent by email."
 msgstr "Un nouveau code d'authentification a été envoyé par e-mail."
 

{django_pfx-1.7.2.dev8 → django_pfx-1.7.2.dev12}/pfx/pfxcore/models/__init__.py

@@ -1,13 +1,13 @@
 from .abstract_pfx_base_user import AbstractPFXBaseUser, AbstractPFXUser
 from .cache_mixins import CacheableMixin, CacheDependsMixin
 from .login_ban import LoginBan
+from .mfa_user_mixin import MFAUserMixin, OtpUserMixin
 from .not_null_fields import (
     NotNullCharField,
     NotNullTextField,
     NotNullURLField,
 )
 from .ordered_model_mixin import OrderedModelMixin
-from .otp_user_mixin import OtpUserMixin
 from .pfx_models import (
     ErrorMessageMixin,
     JSONReprMixin,

django_pfx-1.7.2.dev8/pfx/pfxcore/models/otp_user_mixin.py → django_pfx-1.7.2.dev12/pfx/pfxcore/models/mfa_user_mixin.py

@@ -8,8 +8,11 @@ from pfx.pfxcore.decorator import rest_property
 from pfx.pfxcore.settings import settings
 
 
-class OtpUserMixin(models.Model):
-    """A mixin to enable OTP MFA on a user class."""
+class MFAUserMixin(models.Model):
+    """A mixin to enable MFA on a user class.
+
+    Supports three methods: authenticator app (TOTP), SMS, and email.
+    """
 
     #: OTP secret token.
     otp_secret_token = models.CharField(
@@ -22,10 +25,25 @@ class OtpUserMixin(models.Model):
     hotp_count = models.IntegerField(_("HOTP count"), default=0)
     #: HOTP expiry.
     hotp_expiry = models.DateTimeField(_("HOTP expiry"), default=timezone.now)
+    #: Validated SMS phone number.
+    sms_phone_number = models.CharField(
+        _("SMS phone number"), max_length=32, null=True, blank=True)
+    #: SMS phone number pending validation.
+    sms_phone_number_tmp = models.CharField(
+        _("Temporary SMS phone number"), max_length=32, null=True, blank=True)
+    #: SMS MFA enabled.
+    sms_enabled = models.BooleanField(_("SMS MFA enabled"), default=False)
+    #: Email MFA enabled.
+    email_enabled = models.BooleanField(_("Email MFA enabled"), default=False)
+    #: User has dismissed or completed the MFA setup screen.
+    mfa_setup_dismissed = models.BooleanField(
+        _("MFA setup dismissed"), default=False)
 
     class Meta:
         abstract = True
 
+    # --- deprecated alias ---
+
     @rest_property(_("OTP enabled"), "BooleanField")
     def is_otp(self):
         return bool(self.otp_secret_token)
@@ -130,3 +148,7 @@ class OtpUserMixin(models.Model):
         self.save(update_fields=[
             'hotp_count', 'hotp_expiry'])
         return pyotp.hotp.HOTP(self.otp_secret_token).at(self.hotp_count)
+
+
+#: Deprecated alias for MFAUserMixin.
+OtpUserMixin = MFAUserMixin

django_pfx-1.7.2.dev12/pfx/pfxcore/sms/__init__.py

@@ -0,0 +1,9 @@
+from django.utils.module_loading import import_string
+
+from pfx.pfxcore.settings import settings
+
+
+def get_sms_backend():
+    """Return an instance of the configured SMS backend."""
+    backend_class = import_string(settings.PFX_SMS_BACKEND)
+    return backend_class()

django_pfx-1.7.2.dev12/pfx/pfxcore/sms/backends/base.py

@@ -0,0 +1,15 @@
+class BaseSMSBackend:
+    """Base SMS backend.
+
+    Subclass this to implement a custom SMS backend.
+    The only required method is ``send_sms``."""
+
+    def send_sms(self, to, message):
+        """Send an SMS message.
+
+        :param to: The recipient phone number (E.164 format recommended).
+        :param message: The text content of the message.
+        :raises NotImplementedError: Must be implemented by subclasses.
+        """
+        raise NotImplementedError(
+            "Subclasses of BaseSMSBackend must implement send_sms().")

django_pfx-1.7.2.dev12/pfx/pfxcore/sms/backends/console.py

@@ -0,0 +1,14 @@
+import logging
+
+from .base import BaseSMSBackend
+
+logger = logging.getLogger(__name__)
+
+
+class ConsoleSMSBackend(BaseSMSBackend):
+    """SMS backend that logs messages to the console.
+
+    Useful for development and testing — no real SMS is sent."""
+
+    def send_sms(self, to, message):
+        logger.info("SMS to %s: %s", to, message)