More implementation documentation

flaskbb/auth/services/activation.py

@@ -17,6 +17,10 @@ from ...email import send_activation_token
 
 
 class AccountActivator(_AccountActivator):
+    """
+    Default account activator for FlaskBB, handles the activation
+    process through email.
+    """
 
     def __init__(self, token_serializer, users):
         self.token_serializer = token_serializer

flaskbb/auth/services/authentication.py

@@ -12,9 +12,10 @@
 import logging
 from datetime import datetime
 
+from pytz import UTC
+
 import attr
 from flask_babelplus import gettext as _
-from pytz import UTC
 from werkzeug import check_password_hash
 
 from ...core.auth.authentication import (AuthenticationFailureHandler,
@@ -31,11 +32,20 @@ logger = logging.getLogger(__name__)
 
 @attr.s(frozen=True)
 class FailedLoginConfiguration(object):
+    """
+    Used to configure how many failed logins are accepted until an account
+    is temporarily locked out and how long to temporarily lock the account
+    out for.
+    """
     limit = attr.ib()
     lockout_window = attr.ib()
 
 
 class BlockTooManyFailedLogins(AuthenticationProvider):
+    """
+    Pre authentication check to block a login from an account that has too
+    many failed login attempts in place.
+    """
 
     def __init__(self, configuration):
         self.configuration = configuration
@@ -65,6 +75,15 @@ class BlockTooManyFailedLogins(AuthenticationProvider):
 
 
 class DefaultFlaskBBAuthProvider(AuthenticationProvider):
+    """
+    This is the default username/email and password authentication checker,
+    locates the user based on the identifer passed -- either username or email
+    -- and compares the supplied password to the hash connected to the matching
+    user (if any).
+
+    Offers protection against timing attacks that would rely on the difference
+    in response time from not matching a password hash.
+    """
 
     def authenticate(self, identifier, secret):
         user = User.query.filter(
@@ -81,6 +100,10 @@ class DefaultFlaskBBAuthProvider(AuthenticationProvider):
 
 
 class MarkFailedLogin(AuthenticationFailureHandler):
+    """
+    Failure handler that marks the login attempt on the user and sets the
+    last failed date when it happened.
+    """
 
     def handle_authentication_failure(self, identifier):
         user = User.query.filter(
@@ -93,6 +116,10 @@ class MarkFailedLogin(AuthenticationFailureHandler):
 
 
 class BlockUnactivatedUser(PostAuthenticationHandler):
+    """
+    Post auth handler that will block a user that has managed to pass the
+    authentication check but has not actually activated their account yet.
+    """
 
     def handle_post_auth(self, user):
         if not user.activated:  # pragma: no branch
@@ -106,12 +133,20 @@ class BlockUnactivatedUser(PostAuthenticationHandler):
 
 
 class ClearFailedLogins(PostAuthenticationHandler):
+    """
+    Post auth handler that clears all failed login attempts from a user's
+    account.
+    """
 
     def handle_post_auth(self, user):
         user.login_attempts = 0
 
 
 class PluginAuthenticationManager(AuthenticationManager):
+    """
+    Authentication manager relying on plugin hooks to manage the authentication
+    process. This is the default authentication manager for FlaskBB.
+    """
 
     def __init__(self, plugin_manager, session):
         self.plugin_manager = plugin_manager

flaskbb/auth/services/password.py

@@ -17,6 +17,10 @@ from ...email import send_reset_token
 
 
 class ResetPasswordService(_ResetPasswordService):
+    """
+    Default password reset handler for FlaskBB, manages the process through
+    email.
+    """
 
     def __init__(self, token_serializer, users, token_verifiers):
         self.token_serializer = token_serializer
@@ -24,6 +28,13 @@ class ResetPasswordService(_ResetPasswordService):
         self.token_verifiers = token_verifiers
 
     def initiate_password_reset(self, email):
+        """
+        Looks up a user by email and raises a
+        :class:`ValidationError<flaskbb.core.exceptions.ValidationError>`
+        if that user does not exist, otherwise generates a reset password
+        token and emails it to the user.
+        """
+
         user = self.users.query.filter_by(email=email).first()
 
         if user is None:
@@ -38,6 +49,18 @@ class ResetPasswordService(_ResetPasswordService):
         )
 
     def reset_password(self, token, email, new_password):
+        """
+        Resets a user's password if the email entered by the user matches
+        the email on file for the user in FlaskBB.
+
+        If the provided token is not a reset password token, then it raises a
+        :class:`TokenError<flaskbb.core.tokens.TokenError>` and if the
+        information provided by the user does not meet criteria defined
+        by the passed token verifiers, then a
+        :class:`StopValidation<flaskbb.core.exceptions.StopValidation>` is
+        raised.
+        """
+
         token = self.token_serializer.loads(token)
         if token.operation != TokenActions.RESET_PASSWORD:
             raise TokenError.invalid()

flaskbb/auth/services/reauthentication.py

@@ -24,6 +24,10 @@ logger = logging.getLogger(__name__)
 
 
 class DefaultFlaskBBReauthProvider(ReauthenticateProvider):
+    """
+    This is the default reauth provider in FlaskBB, it compares the provided
+    password against the current user's hashed password.
+    """
 
     def reauthenticate(self, user, secret):
         if check_password_hash(user.password, secret):  # pragma: no branch
@@ -31,12 +35,20 @@ class DefaultFlaskBBReauthProvider(ReauthenticateProvider):
 
 
 class ClearFailedLoginsOnReauth(PostReauthenticateHandler):
+    """
+    Handler that clears failed login attempts after a successful
+    reauthentication.
+    """
 
     def handle_post_reauth(self, user):
         user.login_attempts = 0
 
 
 class MarkFailedReauth(ReauthenticateFailureHandler):
+    """
+    Failure handler that marks the failed reauth attempt as a failed login
+    and when it occurred.
+    """
 
     def handle_reauth_failure(self, user):
         user.login_attempts += 1
@@ -44,6 +56,10 @@ class MarkFailedReauth(ReauthenticateFailureHandler):
 
 
 class PluginReauthenticationManager(ReauthenticateManager):
+    """
+    Default reauthentication manager for FlaskBB, it relies on plugin hooks
+    to manage the reauthentication flow.
+    """
 
     def __init__(self, plugin_manager, session):
         self.plugin_manager = plugin_manager