Make the instances of overridable extendable classes visible in the p… (#1081)

* Make the instances of overridable extendable classes visible in the public API, and document them.
Mark as deprecated the ability to set these classes as part of init_ap(kwargs) or global app.config (only via Flask-Security construction).

close #1076

* Make the instances of overridable extendable classes visible in the public API, and document them.
Mark as deprecated the ability to set these classes as part of init_ap(kwargs) or global app.config (only via Flask-Security construction).

Bunmp flask-babel 'low' version.

close #1076

Author: jwag956

CHANGES.rst

@@ -12,6 +12,16 @@ Fixes
 +++++
 - (:issue:`1077`) Fix runtime modification of a config string (TWO_FACTOR_METHODS)
 - (:issue:`1078`) Fix CLI user_create when model doesn't contain username
+- (:issue:`1076`) xxx_util_cls instances should be public and documented.
+
+Backwards Compatibility Concerns
++++++++++++++++++++++++++++++++++
+As part of :issue:`1076` the following cleanup was done:
+
+- The xxx_util_cls arguments are now stored in 'private' instance variables - they are never
+  used after Flask-Security initialization and have never been documented.
+- The xxx_util_cls options should only be set as part of Flask-Security construction.
+  Setting them via init_app(kwargs) or app.config["SECURITY_XX"] has been deprecated.
 
 Version 5.6.0
 -------------

docs/customizing.rst

@@ -281,7 +281,7 @@ appropriate input attributes can be set)::
         # Side-effect - field.data is updated to normalized value.
         # Use proxy to we can declare this prior to initializing Security.
         _security = LocalProxy(lambda: app.extensions["security"])
-        msg, field.data = _security._username_util.validate(field.data)
+        msg, field.data = _security.username_util.validate(field.data)
         if msg:
             raise ValidationError(msg)
 

flask_security/core.py

@@ -1317,14 +1317,14 @@ def __init__(
         self.app = app
         self._datastore = datastore
         self._register_blueprint = register_blueprint
-        self.mail_util_cls = mail_util_cls
-        self.password_util_cls = password_util_cls
-        self.phone_util_cls = phone_util_cls
+        self._mail_util_cls = mail_util_cls
+        self._password_util_cls = password_util_cls
+        self._phone_util_cls = phone_util_cls
         self.render_template = render_template
-        self.totp_cls = totp_cls
-        self.username_util_cls = username_util_cls
-        self.webauthn_util_cls = webauthn_util_cls
-        self.mf_recovery_codes_util_cls = mf_recovery_codes_util_cls
+        self._totp_cls = totp_cls
+        self._username_util_cls = username_util_cls
+        self._webauthn_util_cls = webauthn_util_cls
+        self._mf_recovery_codes_util_cls = mf_recovery_codes_util_cls
         self._oauth = oauth
 
         # Forms - we create a list from constructor.
@@ -1543,7 +1543,7 @@ def init_app(
         ):
             self._use_confirm_form = False
 
-        # The following will be set as attributes and initialized from either
+        # The following will be set as attributes and initialized from constructor or
         # kwargs or config.
         attr_names = [
             "trackable",
@@ -1558,17 +1558,32 @@ def init_app(
             "username_recovery",
             "passwordless",
             "webauthn",
+            "render_template",
+            "datetime_factory",
+        ]
+        for attr in attr_names:
+            if ov := kwargs.get(attr, cv(attr.upper(), app, strict=False)):
+                setattr(self, attr, ov)
+
+        # Deprecated BC attrs - only settable at constructor time. Noter that newer
+        # _util classes (username_util_cls) already are this way
+        dep_attr_names = [
             "mail_util_cls",
             "password_util_cls",
             "phone_util_cls",
-            "render_template",
             "totp_cls",
             "webauthn_util_cls",
-            "datetime_factory",
         ]
-        for attr in attr_names:
+        for attr in dep_attr_names:
             if ov := kwargs.get(attr, cv(attr.upper(), app, strict=False)):
-                setattr(self, attr, ov)
+                setattr(self, f"_{attr}", ov)
+                warnings.warn(
+                    f"Setting {attr} via kwargs or config is"
+                    " deprecated as of version 5.6.1 and will be removed in a future"
+                    " release. Use the Flask-Security constructor.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
 
         identity_loaded.connect_via(app)(_on_identity_loaded)
 
@@ -1597,12 +1612,12 @@ def init_app(
                 )
 
         self.login_manager = _get_login_manager(app, self)
-        self._phone_util = self.phone_util_cls(app)
-        self._mail_util = self.mail_util_cls(app)
-        self._password_util = self.password_util_cls(app)
-        self._username_util = self.username_util_cls(app)
-        self._webauthn_util = self.webauthn_util_cls(app)
-        self._mf_recovery_codes_util = self.mf_recovery_codes_util_cls(app)
+        self._phone_util = self._phone_util_cls(app)
+        self._mail_util = self._mail_util_cls(app)
+        self._password_util = self._password_util_cls(app)
+        self._username_util = self._username_util_cls(app)
+        self._webauthn_util = self._webauthn_util_cls(app)
+        self._mf_recovery_codes_util = self._mf_recovery_codes_util_cls(app)
         self.remember_token_serializer = _get_serializer(app, "remember")
         self.login_serializer = _get_serializer(app, "login")
         self.reset_serializer = _get_serializer(app, "reset")
@@ -1768,22 +1783,22 @@ def init_app(
                 sms_service = cv("SMS_SERVICE", app=app)
                 if sms_service == "Twilio":  # pragma: no cover
                     self._check_modules("twilio", "SMS")
-                if self.phone_util_cls == PhoneUtil:
+                if self._phone_util_cls == PhoneUtil:
                     self._check_modules("phonenumbers", "SMS")
 
             secrets = cv("TOTP_SECRETS", app=app)
             issuer = cv("TOTP_ISSUER", app=app)
             if not secrets or not issuer:
                 raise ValueError("Both TOTP_SECRETS and TOTP_ISSUER must be set")
-            self._totp_factory = self.totp_cls(secrets, issuer)
+            self._totp_factory = self._totp_cls(secrets, issuer)
 
         if cv("PASSWORD_COMPLEXITY_CHECKER", app=app) == "zxcvbn":
             self._check_modules("zxcvbn", "PASSWORD_COMPLEXITY_CHECKER")
 
         if cv("WEBAUTHN", app=app):
             self._check_modules("webauthn", "WEBAUTHN")
 
-        if cv("USERNAME_ENABLE", app=app) and self.username_util_cls == UsernameUtil:
+        if cv("USERNAME_ENABLE", app=app) and self._username_util_cls == UsernameUtil:
             self._check_modules("bleach", "USERNAME_ENABLE")
 
         # Register so other packages can reference our translations.
@@ -2048,6 +2063,48 @@ def reauthn_handler(
         """
         self._reauthn_handler = cb
 
+    @property
+    def mail_util(self) -> MailUtil:
+        """Instance of mail_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._mail_util
+
+    @property
+    def password_util(self) -> PasswordUtil:
+        """Instance of password_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._password_util
+
+    @property
+    def username_util(self) -> UsernameUtil:
+        """Instance of username_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._username_util
+
+    @property
+    def phone_util(self) -> PhoneUtil:
+        """Instance of phone_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._phone_util
+
+    @property
+    def totp_factory(self) -> Totp:
+        """Instance of totp_factory created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._totp_factory
+
+    @property
+    def mf_recovery_codes_util(self) -> MfRecoveryCodesUtil:
+        """Instance of mf_recovery_codes_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._mf_recovery_codes_util
+
+    @property
+    def webauthn_util(self) -> WebauthnUtil:
+        """Instance of webauthn_util_cls created at init_app() time.
+        See :ref:`api:extendable classes`"""
+        return self._webauthn_util
+
     def _add_ctx_processor(
         self, endpoint: str, fn: t.Callable[[], dict[str, t.Any]]
     ) -> None:

flask_security/datastore.py

@@ -446,7 +446,7 @@ def create_user(self, **kwargs: t.Any) -> UserMixin:
             Best practice is::
 
                 try:
-                    enorm = app.security._mail_util.validate(email)
+                    enorm = app.security.mail_util.validate(email)
                 except ValueError:
 
         .. danger::
@@ -459,7 +459,7 @@ def create_user(self, **kwargs: t.Any) -> UserMixin:
 
            Best practice is::
 
-            pbad, pnorm = app.security._password_util.validate(password, True)
+            pbad, pnorm = app.security.password_util.validate(password, True)
 
            Look for `pbad` being None. Pass the normalized password `pnorm` to this
            method.
@@ -533,7 +533,7 @@ def tf_set(
         This could be called from an application to apiori setup a user for two factor
         without the user having to go through the setup process.
 
-        To get a totp_secret - use ``app.security._totp_factory.generate_totp_secret()``
+        To get a totp_secret - use ``app.security.totp_factory.generate_totp_secret()``
 
         .. versionadded: 3.4.1
         """
@@ -629,7 +629,7 @@ def us_set(
         This could be called from an application to apiori setup a user for unified
         sign in without the user having to go through the setup process.
 
-        To get a totp_secret - use ``app.security._totp_factory.generate_totp_secret()``
+        To get a totp_secret - use ``app.security.totp_factory.generate_totp_secret()``
 
         .. versionadded:: 3.4.1
         """
@@ -673,7 +673,7 @@ def us_setup_email(self, user: UserMixin) -> bool:
         if not cv("UNIFIED_SIGNIN") or "email" not in cv("US_ENABLED_METHODS"):
             return False
         totp_secrets = self.us_get_totp_secrets(user)
-        totp_secrets["email"] = _security._totp_factory.generate_totp_secret()
+        totp_secrets["email"] = _security.totp_factory.generate_totp_secret()
         self.us_put_totp_secrets(user, totp_secrets)
         return True
 

flask_security/forms.py

@@ -164,9 +164,9 @@ def __call__(self, form, field):
 
         try:
             if self.verify:
-                field.data = _security._mail_util.validate(field.data)
+                field.data = _security.mail_util.validate(field.data)
             else:
-                field.data = _security._mail_util.normalize(field.data)
+                field.data = _security.mail_util.normalize(field.data)
         except EmailValidateException as e:
             # we stop further validators if email isn't valid.
             # TODO: email_validator provides some really nice error messages - however
@@ -228,7 +228,7 @@ def unique_user_email(form, field):
 
 def username_validator(form, field):
     # Side-effect - field.data is updated to normalized value.
-    msg, field.data = _security._username_util.validate(field.data)
+    msg, field.data = _security.username_util.validate(field.data)
     if msg:
         raise ValidationError(msg)
 
@@ -599,7 +599,7 @@ def validate(self, **kwargs: t.Any) -> bool:
             # Reduce timing variation between existing and non-existing users
             hash_password(self.password.data)
             return False
-        self.password.data = _security._password_util.normalize(self.password.data)
+        self.password.data = _security.password_util.normalize(self.password.data)
         if not self.user.verify_and_update_password(self.password.data):
             self.password.errors.append(get_message("INVALID_PASSWORD")[0])
             return False
@@ -657,7 +657,7 @@ def validate(self, **kwargs: t.Any) -> bool:
             return False
 
         assert self.password.data is not None
-        self.password.data = _security._password_util.normalize(self.password.data)
+        self.password.data = _security.password_util.normalize(self.password.data)
         assert isinstance(self.password.errors, list)
         if not self.user.verify_and_update_password(self.password.data):
             self.password.errors.append(get_message("INVALID_PASSWORD")[0])
@@ -713,7 +713,7 @@ def validate(self, **kwargs: t.Any) -> bool:
                 if hasattr(_datastore.user_model, k):
                     rfields[k] = v
             del rfields["password"]
-            pbad, self.password.data = _security._password_util.validate(
+            pbad, self.password.data = _security.password_util.validate(
                 self.password.data, True, **rfields
             )
             if pbad:
@@ -823,7 +823,7 @@ def validate(self, **kwargs: t.Any) -> bool:
                 if hasattr(_datastore.user_model, k):
                     rfields[k] = v
             del rfields["password"]
-            pbad, self.password.data = _security._password_util.validate(
+            pbad, self.password.data = _security.password_util.validate(
                 self.password.data, True, **rfields
             )
             if pbad:
@@ -877,7 +877,7 @@ def validate(self, **kwargs: t.Any) -> bool:
 
         assert isinstance(self.password.errors, list)
         assert self.password.data is not None
-        pbad, self.password.data = _security._password_util.validate(
+        pbad, self.password.data = _security.password_util.validate(
             self.password.data, False, user=self.user
         )
         if pbad:
@@ -922,7 +922,7 @@ def validate(self, **kwargs: t.Any) -> bool:
                 self.password.errors.append(get_message("PASSWORD_NOT_PROVIDED")[0])
                 return False
 
-            self.password.data = _security._password_util.normalize(self.password.data)
+            self.password.data = _security.password_util.normalize(self.password.data)
             if not verify_password(self.password.data, current_user.password):
                 self.password.errors.append(get_message("INVALID_PASSWORD")[0])
                 return False
@@ -931,7 +931,7 @@ def validate(self, **kwargs: t.Any) -> bool:
                 return False
 
         assert self.new_password.data is not None
-        pbad, self.new_password.data = _security._password_util.validate(
+        pbad, self.new_password.data = _security.password_util.validate(
             self.new_password.data, False, user=current_user
         )
         if pbad:
@@ -980,7 +980,7 @@ def validate(self, **kwargs: t.Any) -> bool:
             if not self.phone.data:
                 self.phone.errors.append(get_message("PHONE_INVALID")[0])
                 return False
-            msg = _security._phone_util.validate_phone_number(self.phone.data)
+            msg = _security.phone_util.validate_phone_number(self.phone.data)
             if msg:
                 self.phone.errors.append(msg)
                 return False
@@ -1020,7 +1020,7 @@ def validate(self, **kwargs: t.Any) -> bool:
         assert self.user is not None
         assert self.code.data is not None
         assert isinstance(self.code.errors, list)
-        if not _security._totp_factory.verify_totp(
+        if not _security.totp_factory.verify_totp(
             token=self.code.data,
             totp_secret=self.tf_totp_secret,
             user=self.user,

flask_security/recovery_codes.py

@@ -77,7 +77,7 @@ def create_recovery_codes(self, user: UserMixin) -> list[str]:
         If configured (:data:`SECURITY_MULTI_FACTOR_RECOVERY_CODES_KEYS`),
         codes are stored encrypted - but plainttext versions are returned.
         """
-        new_codes = _security._totp_factory.generate_recovery_codes(
+        new_codes = _security.totp_factory.generate_recovery_codes(
             cv("MULTI_FACTOR_RECOVERY_CODES_N")
         )
         _datastore.mf_set_recovery_codes(user, self._encrypt_codes(new_codes))
@@ -173,7 +173,7 @@ def validate(self, **kwargs: t.Any) -> bool:
         assert self.user is not None
         assert self.code.data is not None  # RequiredLocalize validator
         assert isinstance(self.code.errors, list)
-        if not _security._mf_recovery_codes_util.check_recovery_code(
+        if not _security.mf_recovery_codes_util.check_recovery_code(
             self.user, self.code.data
         ):
             self.code.errors.append(get_message("INVALID_RECOVERY_CODE")[0])
@@ -198,7 +198,7 @@ def mf_recovery_codes() -> ResponseValue:
 
     if form.validate_on_submit():
         # generate new codes
-        codes = _security._mf_recovery_codes_util.create_recovery_codes(current_user)
+        codes = _security.mf_recovery_codes_util.create_recovery_codes(current_user)
         after_this_request(view_commit)
         if _security._want_json(request):
             payload = dict(recovery_codes=codes)
@@ -210,7 +210,7 @@ def mf_recovery_codes() -> ResponseValue:
             **_security._run_ctx_processor("mf_recovery_codes"),
         )
 
-    codes = _security._mf_recovery_codes_util.get_recovery_codes(current_user)
+    codes = _security.mf_recovery_codes_util.get_recovery_codes(current_user)
     if _security._want_json(request):
         return base_render_json(
             form, include_user=False, additional=dict(recovery_codes=codes)
@@ -243,9 +243,7 @@ def mf_recovery():
 
     if form.validate_on_submit():
         # Valid code - we want these to be one time - so remove it from list
-        _security._mf_recovery_codes_util.delete_recovery_code(
-            form.user, form.code.data
-        )
+        _security.mf_recovery_codes_util.delete_recovery_code(form.user, form.code.data)
         after_this_request(view_commit)
 
         # In the recovery case - don't set/offer validity token.

flask_security/twofactor.py

@@ -60,7 +60,7 @@ def tf_send_security_token(user, method, totp_secret, phone_number):
     Flask-Security code should NOT call this directly -
     call :meth:`.UserMixin.tf_send_security_token`
     """
-    token_to_be_sent = _security._totp_factory.generate_totp_password(totp_secret)
+    token_to_be_sent = _security.totp_factory.generate_totp_password(totp_secret)
     if method == "email" or method == "mail":
         send_mail(
             cv("EMAIL_SUBJECT_TWO_FACTOR"),