django-pfx 1.7.3.dev14__tar.gz → 1.7.3.dev18__tar.gz

{django_pfx-1.7.3.dev14 → django_pfx-1.7.3.dev18}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-pfx
-Version: 1.7.3.dev14
+Version: 1.7.3.dev18
 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.dev14 → django_pfx-1.7.3.dev18}/doc/source/authentication.md

@@ -119,9 +119,9 @@ class MyUser(MFAUserMixin, AbstractPFXBaseUser):
     pass
 ```
 
-:::{note}
+```{note}
 `OtpUserMixin` is a deprecated alias for `MFAUserMixin` and will be removed in a future version.
-:::
+```
 
 #### Settings
 
@@ -140,7 +140,7 @@ class MyUser(MFAUserMixin, AbstractPFXBaseUser):
 * `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 authenticator OTP using the [services documented below](#enable-mfa-otp).
+The user can then manage MFA methods using the [services documented below](#mfa-setup-services).
 
 ## Services
 
@@ -281,53 +281,197 @@ Request a new challenge code or switch to a different OOB backend (email or SMS)
 | token | the jwt token. (only if mode is `jwt`) |
 | user  | the user object                        |
 
-### Enable MFA OTP
-Services to enable the MFA with OTP.
-You have to call first the `setup-uri` service to get the URI,
-encode it as a QR code and present it in the UI of your software.
-Then user then scans this QR code to add the OTP secret to his OTP App.
-Finally, the `enable` service must be called with an OTP code retrieved
-in the OTP App to confirm the activation.
+### MFA Setup Services
 
-**Request :** `GET` `/auth/otp/setup-uri`
+All three MFA methods follow the same `{setup, confirm, disable}` pattern under `/auth/mfa/{authenticator|email|sms}/`.
 
-**Responses :**
+The **setup** step initiates enrollment and, for OOB backends (email/SMS), sends a challenge code.
+The **confirm** step validates the code and activates the method, returning a fresh JWT token.
+The **disable** step deactivates the method after verifying a valid OTP code; when the last active
+method is disabled, the shared OTP secret is also deleted.
 
-* `HTTP 400` if the otp is already enabled
-* `HTTP 200` with the following body
+```{mermaid}
+
+   sequenceDiagram
+      participant App
+      participant API
+      App->>API: GET/PUT /auth/mfa/{method}/setup
+      API->>App: 200 — setup_uri (authenticator) or code sent (email/SMS)
+      App->>API: PUT /auth/mfa/{method}/confirm
+      note right of App: otp_code
+      alt Code valid
+          API->>App: 200 — new JWT token + updated user
+      else Code invalid
+          API->>App: 422 — otp_code error
+      end
+
+```
+
+#### List backends
+
+**Request:** `GET` `/auth/mfa/backends`
+
+Returns the list of backends configured in `PFX_MFA_BACKENDS` and their activation status for the
+authenticated user.
+
+**Response:** `HTTP 200`
+
+```json
+{
+  "backends": [
+    {"id": "authenticator", "is_oob": false, "enabled": true},
+    {"id": "email",         "is_oob": true,  "enabled": false}
+  ]
+}
+```
+
+#### Authenticator (TOTP)
+
+**Request:** `GET` `/auth/mfa/authenticator/setup`
 
-| Field     | Description                           |
-|-----------|---------------------------------------|
-| setup_uri | the uri to enable the OTP application |
+Generates a temporary OTP secret and returns the provisioning URI to encode as a QR code.
 
-**Request :** `PUT` `/auth/otp/enable`
+**Responses:**
+
+* `HTTP 400` if authenticator MFA is already enabled
+* `HTTP 200` with:
+
+| Field     | Description                                          |
+|-----------|------------------------------------------------------|
+| setup_uri | `otpauth://` URI to scan with an authenticator app  |
+
+---
+
+**Request:** `PUT` `/auth/mfa/authenticator/confirm`
+
+Confirms authenticator activation with a TOTP code scanned from the QR code.
 
 **Request body:**
 
-| Field       | Description                           |
-|-------------|---------------------------------------|
-| otp_code    | the otp code retrieved in the OTP app |
+| Field    | Description                            |
+|----------|----------------------------------------|
+| otp_code | TOTP code from the authenticator app  |
 
-**Responses :**
+**Responses:**
+
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
 
-* `HTTP 422` if the otp code is invalid
-* `HTTP 200` if the otp code is valid
+---
 
-### Disable MFA OTP
-A service to disable the MFA with OTP.
+**Request:** `PUT` `/auth/mfa/authenticator/disable`
 
-**Request :** `PUT` `/auth/otp/disable`
+Disables authenticator MFA. Requires a valid OTP code (TOTP or HOTP).
 
 **Request body:**
 
-| Field       | Description                           |
-|-------------|---------------------------------------|
-| otp_code    | the otp code retrieved in the OTP app |
+| Field    | Description       |
+|----------|-------------------|
+| otp_code | a valid OTP code  |
 
-**Responses :**
+**Responses:**
+
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
+
+#### Email
+
+**Request:** `PUT` `/auth/mfa/email/setup`
+
+Starts email MFA enrollment. If no shared secret exists yet, a temporary one is generated.
+A HOTP challenge code is sent to the user's email address.
+
+**Responses:**
+
+* `HTTP 400` if email MFA is already enabled
+* `HTTP 200` with a confirmation message
+
+---
+
+**Request:** `PUT` `/auth/mfa/email/confirm`
+
+Confirms email MFA activation with the code received by email.
+On success the temporary secret is promoted to the permanent shared secret.
+
+**Request body:**
+
+| Field    | Description                       |
+|----------|-----------------------------------|
+| otp_code | the code received by email        |
+
+**Responses:**
+
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
+
+---
+
+**Request:** `PUT` `/auth/mfa/email/disable`
+
+Disables email MFA. Requires a valid OTP code (TOTP or HOTP).
+
+**Request body:**
+
+| Field    | Description       |
+|----------|-------------------|
+| otp_code | a valid OTP code  |
+
+**Responses:**
+
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
+
+#### SMS
+
+```{note}
+`sms_phone_number` must be set on the user before calling the setup endpoint.
+`sms` must also be included in `PFX_MFA_BACKENDS` and `PFX_SMS_BACKEND` must point to a real
+SMS provider for production use.
+```
+
+**Request:** `PUT` `/auth/mfa/sms/setup`
+
+Starts SMS MFA enrollment. A HOTP challenge code is sent to `sms_phone_number`.
+
+**Responses:**
+
+* `HTTP 422` if `sms_phone_number` is not set on the user
+* `HTTP 400` if SMS MFA is already enabled
+* `HTTP 200` with a confirmation message
+
+---
+
+**Request:** `PUT` `/auth/mfa/sms/confirm`
+
+Confirms SMS MFA activation with the code received by SMS.
+
+**Request body:**
+
+| Field    | Description                |
+|----------|----------------------------|
+| otp_code | the code received by SMS   |
+
+**Responses:**
+
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
+
+---
+
+**Request:** `PUT` `/auth/mfa/sms/disable`
+
+Disables SMS MFA. Requires a valid OTP code (TOTP or HOTP).
+
+**Request body:**
+
+| Field    | Description       |
+|----------|-------------------|
+| otp_code | a valid OTP code  |
+
+**Responses:**
 
-* `HTTP 422` if the otp code is invalid
-* `HTTP 200` if the otp code is valid
+* `HTTP 422` if the code is invalid
+* `HTTP 200` with a new JWT token and updated user object
 
 
 ### Logout

{django_pfx-1.7.3.dev14 → django_pfx-1.7.3.dev18}/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-05-21 16:23+0200\n"
+"POT-Creation-Date: 2026-06-08 15:57+0200\n"
 "PO-Revision-Date: 2021-06-22 23:31+0200\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -25,8 +25,8 @@ msgstr "Une erreur interne du serveur est survenue."
 #: default_settings.py:51
 msgid "A system error occurred. Our support team has been notified."
 msgstr ""
-"Une erreur système s’est produite. "
-"Notre équipe d’assistance en a été informée."
+"Une erreur système s’est produite. Notre équipe d’assistance en a été "
+"informée."
 
 #: exceptions.py:53 exceptions.py:76
 #, python-brace-format
@@ -121,11 +121,11 @@ msgstr "Numéro de téléphone (SMS)"
 msgid "Temporary SMS phone number"
 msgstr "Numéro de téléphone temporaire (SMS)"
 
-#: models/mfa_user_mixin.py:35
+#: models/mfa_user_mixin.py:35 views/authentication_views.py:650
 msgid "SMS MFA enabled"
 msgstr "MFA SMS activé"
 
-#: models/mfa_user_mixin.py:38
+#: models/mfa_user_mixin.py:38 views/authentication_views.py:532
 msgid "Email MFA enabled"
 msgstr "MFA par email activé"
 
@@ -133,7 +133,7 @@ msgstr "MFA par email activé"
 msgid "MFA setup dismissed"
 msgstr "Configuration MFA annulée"
 
-#: models/mfa_user_mixin.py:44
+#: models/mfa_user_mixin.py:44 views/authentication_views.py:1007
 msgid "Authenticator MFA enabled"
 msgstr "Application MFA activée"
 
@@ -273,51 +273,70 @@ msgstr ""
 msgid "Successful login"
 msgstr "Connexion réussie"
 
-#: views/authentication_views.py:386
+#: views/authentication_views.py:399
 msgid "This field is required."
 msgstr "Ce champ est requis."
 
-#: views/authentication_views.py:397
+#: views/authentication_views.py:410 views/authentication_views.py:494
+#: views/authentication_views.py:612
 msgid "Code sent."
 msgstr "Code envoyé."
 
-#: views/authentication_views.py:460 views/authentication_views.py:628
+#: views/authentication_views.py:491
+msgid "Email MFA is already enabled"
+msgstr "MFA par email déjà activé."
+
+#: views/authentication_views.py:534 views/authentication_views.py:569
+#: views/authentication_views.py:652 views/authentication_views.py:687
+#: views/authentication_views.py:1009 views/authentication_views.py:1048
+msgid "Invalid code"
+msgstr "Code invalide"
+
+#: views/authentication_views.py:573
+msgid "Email MFA disabled"
+msgstr "MFA par email désactivé"
+
+#: views/authentication_views.py:606
+msgid "Phone number is required."
+msgstr "Le numéro de téléphone est requis."
+
+#: views/authentication_views.py:609
+msgid "SMS MFA is already enabled"
+msgstr "MFA par SMS déjà activé."
+
+#: views/authentication_views.py:691
+msgid "SMS MFA disabled"
+msgstr "MFA par SMS désactivé"
+
+#: views/authentication_views.py:754 views/authentication_views.py:922
 msgid "password updated successfully"
 msgstr "le mot de passe a été mis à jour avec succès"
 
-#: views/authentication_views.py:465
+#: views/authentication_views.py:759
 msgid "Incorrect password"
 msgstr "Mot de passe incorrect"
 
-#: views/authentication_views.py:468 views/authentication_views.py:637
+#: views/authentication_views.py:762 views/authentication_views.py:931
 msgid "Empty password is not allowed"
 msgstr "Un mot de passe vide n’est pas autorisé"
 
-#: views/authentication_views.py:557
+#: views/authentication_views.py:851
 msgid "User and token are valid"
 msgstr "L’utilisateur et le token sont valides"
 
-#: views/authentication_views.py:559
+#: views/authentication_views.py:853
 msgid "User or token is invalid"
 msgstr "L’utilisateur ou le token est invalide"
 
-#: views/authentication_views.py:671
-msgid "OTP is already enabled"
-msgstr "OTP est déjà activé"
-
-#: views/authentication_views.py:711
-msgid "OTP enabled"
-msgstr "OTP activé"
+#: views/authentication_views.py:967
+msgid "Authenticator MFA is already enabled"
+msgstr "MFA par application déjà activé"
 
-#: views/authentication_views.py:712 views/authentication_views.py:748
-msgid "Invalid code"
-msgstr "Code invalide"
+#: views/authentication_views.py:1046
+msgid "Authenticator MFA disabled"
+msgstr "MFA par application activée"
 
-#: views/authentication_views.py:747
-msgid "OTP disabled"
-msgstr "OTP désactivé"
-
-#: views/authentication_views.py:1008
+#: views/authentication_views.py:1308
 msgid ""
 "If the email address you entered is correct, you will receive an email from "
 "us with instructions to reset your password."
@@ -326,7 +345,7 @@ msgstr ""
 "un courrier électronique de notre part contenant des instructions pour "
 "réinitialiser votre mot de passe."
 
-#: views/authentication_views.py:1082
+#: views/authentication_views.py:1382
 msgid "A new authentication code has been sent by email."
 msgstr "Un nouveau code d’authentification a été envoyé par e-mail."
 
@@ -369,3 +388,9 @@ msgstr "{model} {obj} modifié."
 #, python-brace-format
 msgid "{model} {obj} deleted."
 msgstr "{model} {obj} supprimé."
+
+#~ msgid "OTP enabled"
+#~ msgstr "OTP activé"
+
+#~ msgid "OTP disabled"
+#~ msgstr "OTP désactivé"

django_pfx-1.7.3.dev18/pfx/pfxcore/middleware/ws_cookie_authentication_middleware.py

@@ -0,0 +1,35 @@
+import logging
+
+from django.contrib.auth.models import AnonymousUser
+from django.http import parse_cookie
+
+from channels.db import database_sync_to_async
+from channels.middleware import BaseMiddleware
+
+from pfx.pfxcore.middleware.authentication import JWTTokenDecodeMixin
+
+logger = logging.getLogger(__name__)
+
+
+class WSCookieAuthenticationMiddleware(JWTTokenDecodeMixin, BaseMiddleware):
+    async def __call__(self, scope, receive, send):
+        if scope.get("user") is not None:
+            return await super().__call__(scope, receive, send)
+
+        headers = dict(scope.get("headers", []))
+        cookies = {}
+        if b"cookie" in headers:
+            cookies = parse_cookie(headers[b"cookie"].decode())
+
+        key = cookies.get("token")
+        if key:
+            try:
+                user, __, __ = await database_sync_to_async(
+                    self.decode_jwt)(key)
+            except Exception as e:
+                logger.exception(e, exc_info=True)
+                user = AnonymousUser()
+        else:
+            user = AnonymousUser()
+        scope['user'] = user
+        return await super().__call__(scope, receive, send)

{django_pfx-1.7.3.dev14 → django_pfx-1.7.3.dev18}/pfx/pfxcore/models/mfa_user_mixin.py

@@ -82,24 +82,76 @@ class MFAUserMixin(models.Model):
         """Add extra attribute to response when need_otp=True."""
         return {}
 
+    # --- private helpers ---
+
+    def _clear_secret_if_no_mfa(self):
+        """Delete otp_secret_token when no MFA method remains active."""
+        if not (self.mfa_authenticator_enabled
+                or self.mfa_sms_enabled
+                or self.mfa_email_enabled):
+            self.otp_secret_token = None
+            self.save(update_fields=['otp_secret_token'])
+
+    def _prepare_oob_mfa_activation(self):
+        """Prepare an OOB (email or SMS) MFA activation.
+
+        If no permanent secret exists yet, generates ``otp_secret_token_tmp``
+        so the JWT signature key is not changed before the user confirms.
+        Returns the HOTP code to send to the user.
+        """
+        import pyotp
+        if not self.otp_secret_token:
+            self.otp_secret_token_tmp = pyotp.random_base32()
+            self.save(update_fields=['otp_secret_token_tmp'])
+        secret = self.otp_secret_token_tmp or self.otp_secret_token
+        self.hotp_count += 1
+        self.hotp_expiry = timezone.now() + timedelta(
+            minutes=settings.PFX_HOTP_CODE_VALIDITY)
+        self.save(update_fields=['hotp_count', 'hotp_expiry'])
+        return pyotp.hotp.HOTP(secret).at(self.hotp_count)
+
+    def _confirm_oob_mfa_activation(self, otp_code, flag_field):
+        """Confirm an OOB MFA activation.
+
+        Validates the code against the temporary secret (first-time setup) or
+        the permanent one (adding a second method). On success promotes the
+        temporary secret when applicable and sets the method flag.
+
+        :param otp_code: Code entered by the user.
+        :param flag_field: Model field name to set to ``True`` on success.
+        :returns: ``True`` on success, ``False`` if the code is invalid.
+        """
+        use_tmp = bool(self.otp_secret_token_tmp)
+        if self.is_otp_valid(otp_code, tmp=use_tmp):
+            if use_tmp:
+                self.otp_secret_token = self.otp_secret_token_tmp
+                self.otp_secret_token_tmp = None
+                setattr(self, flag_field, True)
+                self.save(update_fields=[
+                    'otp_secret_token', 'otp_secret_token_tmp', flag_field])
+            else:
+                setattr(self, flag_field, True)
+                self.save(update_fields=[flag_field])
+            return True
+        return False
+
+    # --- authenticator (TOTP) ---
+
     def enable_otp(self):
-        """Activate OTP for this user.
+        """Start authenticator setup.
 
-        Generates a new temporary OTP secret token. To complete activation,
-        call `confirm_otp` with a valid code.
+        Generates a new temporary OTP secret. Call :meth:`confirm_otp`
+        with a valid TOTP code to complete activation.
         """
         import pyotp
         self.otp_secret_token_tmp = pyotp.random_base32()
         self.save(update_fields=['otp_secret_token_tmp'])
 
     def confirm_otp(self, otp_code):
-        """Confirm OTP activation for this user.
-
-        Set the OTP secret token from the temporary one if the provided
-        code is valid.
+        """Confirm authenticator activation.
 
-        :param otp_code: A valid OTP code for the temporary OTP secret key.
-        :returns: `True` if success, `False` otherwise.
+        :param otp_code: A valid TOTP code for the temporary secret.
+        :returns: ``True`` on success, ``False`` otherwise.
         """
         if self.is_otp_valid(otp_code, tmp=True):
             self.otp_secret_token = self.otp_secret_token_tmp
@@ -112,14 +164,67 @@ class MFAUserMixin(models.Model):
         return False
 
     def disable_otp(self):
-        """Disable OTP for this user.
+        """Disable authenticator MFA.
 
-        Remove the OTP secret token.
+        Clears the permanent secret only when no other method remains active.
         """
-        self.otp_secret_token = None
         self.mfa_authenticator_enabled = False
-        self.save(update_fields=[
-            'otp_secret_token', 'mfa_authenticator_enabled'])
+        self.save(update_fields=['mfa_authenticator_enabled'])
+        self._clear_secret_if_no_mfa()
+
+    # --- email ---
+
+    def enable_email_mfa(self):
+        """Start email MFA activation.
+
+        :returns: The HOTP code to send to the user by email.
+        """
+        return self._prepare_oob_mfa_activation()
+
+    def confirm_email_mfa(self, otp_code):
+        """Confirm email MFA activation.
+
+        :param otp_code: Code received by the user.
+        :returns: ``True`` on success, ``False`` if the code is invalid.
+        """
+        return self._confirm_oob_mfa_activation(otp_code, 'mfa_email_enabled')
+
+    def disable_email_mfa(self):
+        """Disable email MFA.
+
+        Clears the permanent secret when this was the last active method.
+        """
+        self.mfa_email_enabled = False
+        self.save(update_fields=['mfa_email_enabled'])
+        self._clear_secret_if_no_mfa()
+
+    # --- SMS ---
+
+    def enable_sms_mfa(self):
+        """Start SMS MFA activation.
+
+        :returns: The HOTP code to send to the user by SMS.
+        """
+        return self._prepare_oob_mfa_activation()
+
+    def confirm_sms_mfa(self, otp_code):
+        """Confirm SMS MFA activation.
+
+        :param otp_code: Code received by the user.
+        :returns: ``True`` on success, ``False`` if the code is invalid.
+        """
+        return self._confirm_oob_mfa_activation(otp_code, 'mfa_sms_enabled')
+
+    def disable_sms_mfa(self):
+        """Disable SMS MFA.
+
+        Clears the permanent secret when this was the last active method.
+        """
+        self.mfa_sms_enabled = False
+        self.save(update_fields=['mfa_sms_enabled'])
+        self._clear_secret_if_no_mfa()
+
+    # --- shared OTP helpers ---
 
     def get_otp_setup_uri(self, tmp=False, with_color=True):
         """Return the setup URL for OTP activation.