Advanced to version 0.6.2.

.readthedocs.yaml

@@ -0,0 +1,40 @@
+# The Flask HTTP Digest Authentication Project.
+# Author: imacat@mail.imacat.idv.tw (imacat), 2023/4/5
+
+#  Copyright (c) 2023 imacat.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
+# Build documentation in the docs/ directory with Sphinx
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats: all
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - method: pip
+     path: .

MANIFEST.in

@@ -15,8 +15,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-include docs/*
-include docs/source/*
-include docs/source/_static/*
-include docs/source/_templates/*
-include tests/*
+recursive-include docs *
+recursive-exclude docs/build *
+recursive-include tests *
+recursive-exclude tests *.pyc

README.rst

@@ -6,14 +6,12 @@ Flask HTTP Digest Authentication
 Description
 ===========
 
-*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
 for Flask_ applications.  It authenticates the user for the protected
 views.
 
 HTTP Digest Authentication is specified in `RFC 2617`_.
 
-Refer to the full `Flask-Digest-Auth readthedocs documentation`_.
-
 
 Why HTTP Digest Authentication?
 -------------------------------
@@ -30,7 +28,7 @@ own challenge-response log in form, but then you are reinventing the
 wheels.  If a pretty log in form is not critical to your project, HTTP
 Digest Authentication should be a good choice.
 
-Flask-Digest-Auth works with Flask-Login_.  Log in protection can be
+Flask-DigestAuth works with Flask-Login_.  Log in protection can be
 separated with the authentication mechanism.  You can create protected
 Flask modules without knowing the actual authentication mechanisms.
 
@@ -38,358 +36,36 @@ Flask modules without knowing the actual authentication mechanisms.
 Installation
 ============
 
-You can install Flask-Digest-Auth with ``pip``:
+You can install Flask-DigestAuth with ``pip``:
 
 ::
 
-    pip install Flask-Digest-Auth
+    pip install Flask-DigestAuth
 
 You may also install the latest source from the
-`Flask-Digest-Auth GitHub repository`_.
+`Flask-DigestAuth GitHub repository`_.
 
 ::
 
-    pip install git+https://github.com/imacat/flask-digest-auth.git
+    pip install git+https://github.com/imacat/flask-digestauth.git
 
 
-Setting the Password
-====================
+Documentation
+=============
 
-The password hash of the HTTP Digest Authentication is composed of the
-realm, the username, and the password.  Example for setting the
-password:
+Refer to the `documentation on Read the Docs`_.
 
-::
 
-    from flask_digest_auth import make_password_hash
+Change Log
+==========
 
-    user.password = make_password_hash(realm, username, password)
-
-The username is part of the hash.  If the user changes their username,
-you need to ask their password, to generate and store the new password
-hash.
-
-
-Flask-Digest-Auth Alone
-=======================
-
-Flask-Digest-Auth can authenticate the users alone.
-
-
-Simple Applications with Flask-Digest-Auth Alone
-------------------------------------------------
-
-In your ``my_app.py``:
-
-::
-
-    from flask import Flask, request, redirect
-    from flask_digest_auth import DigestAuth
-
-    app: flask = Flask(__name__)
-    ... (Configure the Flask application) ...
-
-    auth: DigestAuth = DigestAuth(realm="Admin")
-    auth.init_app(app)
-
-    @auth.register_get_password
-    def get_password_hash(username: str) -> t.Optional[str]:
-        ... (Load the password hash) ...
-
-    @auth.register_get_user
-    def get_user(username: str) -> t.Optional[t.Any]:
-        ... (Load the user) ...
-
-    @app.get("/admin")
-    @auth.login_required
-    def admin():
-        return f"Hello, {g.user.username}!"
-
-    @app.post("/logout")
-    @auth.login_required
-    def logout():
-        auth.logout()
-        return redirect(request.form.get("next"))
-
-
-Larger Applications with ``create_app()`` with Flask-Digest-Auth Alone
-----------------------------------------------------------------------
-
-In your ``my_app/__init__.py``:
-
-::
-
-    from flask import Flask
-    from flask_digest_auth import DigestAuth
-
-    auth: DigestAuth = DigestAuth()
-
-    def create_app(test_config = None) -> Flask:
-        app: flask = Flask(__name__)
-        ... (Configure the Flask application) ...
-
-        auth.realm = app.config["REALM"]
-        auth.init_app(app)
-
-        @auth.register_get_password
-        def get_password_hash(username: str) -> t.Optional[str]:
-            ... (Load the password hash) ...
-
-        @auth.register_get_user
-        def get_user(username: str) -> t.Optional[t.Any]:
-            ... (Load the user) ...
-
-        return app
-
-In your ``my_app/views.py``:
-
-::
-
-    from my_app import auth
-    from flask import Flask, Blueprint, request, redirect
-
-    bp = Blueprint("admin", __name__, url_prefix="/admin")
-
-    @bp.get("/admin")
-    @auth.login_required
-    def admin():
-        return f"Hello, {g.user.username}!"
-
-    @app.post("/logout")
-    @auth.login_required
-    def logout():
-        auth.logout()
-        return redirect(request.form.get("next"))
-
-    def init_app(app: Flask) -> None:
-        app.register_blueprint(bp)
-
-
-
-Flask-Login Integration
-=======================
-
-Flask-Digest-Auth works with Flask-Login_.  You can write a Flask
-module that requires log in, without specifying how to log in.  The
-application can use either HTTP Digest Authentication, or the log in
-forms, as needed.
-
-To use Flask-Login with Flask-Digest-Auth,
-``login_manager.init_app(app)`` must be called before
-``auth.init_app(app)``.
-
-The currently logged-in user can be retrieved at
-``flask_login.current_user``, if any.
-
-The views only depend on Flask-Login, but not the Flask-Digest-Auth.
-You can change the actual authentication mechanism without changing
-the views.
-
-
-Simple Applications with Flask-Login Integration
-------------------------------------------------
-
-In your ``my_app.py``:
-
-::
-
-    import flask_login
-    from flask import Flask, request, redirect
-    from flask_digest_auth import DigestAuth
-
-    app: flask = Flask(__name__)
-    ... (Configure the Flask application) ...
-
-    login_manager: flask_login.LoginManager = flask_login.LoginManager()
-    login_manager.init_app(app)
-
-    @login_manager.user_loader
-    def load_user(user_id: str) -> t.Optional[User]:
-        ... (Load the user with the username) ...
-
-    auth: DigestAuth = DigestAuth(realm="Admin")
-    auth.init_app(app)
-
-    @auth.register_get_password
-    def get_password_hash(username: str) -> t.Optional[str]:
-        ... (Load the password hash) ...
-
-    @app.get("/admin")
-    @flask_login.login_required
-    def admin():
-        return f"Hello, {flask_login.current_user.get_id()}!"
-
-    @app.post("/logout")
-    @flask_login.login_required
-    def logout():
-        auth.logout()
-        # Do not call flask_login.logout_user()
-        return redirect(request.form.get("next"))
-
-
-Larger Applications with ``create_app()`` with Flask-Login Integration
-----------------------------------------------------------------------
-
-In your ``my_app/__init__.py``:
-
-::
-
-    from flask import Flask
-    from flask_digest_auth import DigestAuth
-    from flask_login import LoginManager
-
-    auth: DigestAuth = DigestAuth()
-
-    def create_app(test_config = None) -> Flask:
-        app: flask = Flask(__name__)
-        ... (Configure the Flask application) ...
-
-        login_manager: LoginManager = LoginManager()
-        login_manager.init_app(app)
-
-        @login_manager.user_loader
-        def load_user(user_id: str) -> t.Optional[User]:
-            ... (Load the user with the username) ...
-
-        auth.realm = app.config["REALM"]
-        auth.init_app(app)
-
-        @auth.register_get_password
-        def get_password_hash(username: str) -> t.Optional[str]:
-            ... (Load the password hash) ...
-
-        return app
-
-In your ``my_app/views.py``:
-
-::
-
-    import flask_login
-    from flask import Flask, Blueprint, request, redirect
-    from my_app import auth
-
-    bp = Blueprint("admin", __name__, url_prefix="/admin")
-
-    @bp.get("/admin")
-    @flask_login.login_required
-    def admin():
-        return f"Hello, {flask_login.current_user.get_id()}!"
-
-    @app.post("/logout")
-    @flask_login.login_required
-    def logout():
-        auth.logout()
-        # Do not call flask_login.logout_user()
-        return redirect(request.form.get("next"))
-
-    def init_app(app: Flask) -> None:
-        app.register_blueprint(bp)
-
-The views only depend on Flask-Login, but not the actual
-authentication mechanism.  You can change the actual authentication
-mechanism without changing the views.
-
-
-Session Integration
-===================
-
-Flask-Digest-Auth features session integration.  The user log in
-is remembered in the session.  The authentication information is not
-requested again.  This is different to the practice of the HTTP Digest
-Authentication, but is convenient for the log in accounting.
-
-
-Log In Bookkeeping
-==================
-
-You can register a callback to run when the user logs in, for ex.,
-logging the log in event, adding the log in counter, etc.
-
-::
-
-    @auth.register_on_login
-    def on_login(user: User) -> None:
-        user.visits = user.visits + 1
-
-
-Log Out
-=======
-
-Flask-Digest-Auth supports log out.  The user will be prompted for the
-new username and password.
-
-
-Test Client
-===========
-
-Flask-Digest-Auth comes with a test client that supports HTTP digest
-authentication.
-
-
-A unittest Test Case
---------------------
-
-::
-
-    from flask import Flask
-    from flask_digest_auth import Client
-    from flask_testing import TestCase
-    from my_app import create_app
-
-    class MyTestCase(TestCase):
-
-        def create_app(self):
-            app: Flask = create_app({
-                "SECRET_KEY": token_urlsafe(32),
-                "TESTING": True
-            })
-            app.test_client_class = Client
-            return app
-
-        def test_admin(self):
-            response = self.client.get("/admin")
-            self.assertEqual(response.status_code, 401)
-            response = self.client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
-            self.assertEqual(response.status_code, 200)
-
-
-A pytest Test
--------------
-
-::
-
-    import pytest
-    from flask import Flask
-    from flask_digest_auth import Client
-    from my_app import create_app
-
-    @pytest.fixture()
-    def app():
-        app: Flask = create_app({
-            "SECRET_KEY": token_urlsafe(32),
-            "TESTING": True
-        })
-        app.test_client_class = Client
-        yield app
-
-    @pytest.fixture()
-    def client(app):
-        return app.test_client()
-
-    def test_admin(app: Flask, client: Client):
-        with app.app_context():
-            response = client.get("/admin")
-            assert response.status_code == 401
-            response = client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
-            assert response.status_code == 200
+Refer to the `change log`_.
 
 
 Copyright
 =========
 
- Copyright (c) 2022 imacat.
+ Copyright (c) 2022-2023 imacat.
 
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
@@ -414,6 +90,7 @@ Authors
 .. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
 .. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
 .. _Flask: https://flask.palletsprojects.com
-.. _Flask-Digest-Auth GitHub repository: https://github.com/imacat/flask-digest-auth
-.. _Flask-Digest-Auth readthedocs documentation: https://flask-digest-auth.readthedocs.io
+.. _Flask-DigestAuth GitHub repository: https://github.com/imacat/flask-digestauth
 .. _Flask-Login: https://flask-login.readthedocs.io
+.. _documentation on Read the Docs: https://flask-digestauth.readthedocs.io
+.. _change log: https://flask-digestauth.readthedocs.io/en/latest/changelog.html

docs/make.bat

@@ -10,8 +10,6 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
-if "%1" == "" goto help
-
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -21,10 +19,12 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
+if "%1" == "" goto help
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

docs/requirements.txt

@@ -1 +0,0 @@
-flask

docs/source/changelog.rst

@@ -0,0 +1,142 @@
+Change Log
+==========
+
+
+Version 0.6.2
+-------------
+
+Released 2023/6/10
+
+* Changed logging from STDERR to the Flask logger.
+* Test case updates:
+  * Added missing documentation.
+  * Changed properties from public to private.
+  * Disabled logging.
+
+
+Version 0.6.1
+-------------
+
+Released 2023/5/3
+
+* Revised the code for the upcoming Werkzeug 2.4.
+
+
+Version 0.6.0
+-------------
+
+Released 2023/4/26
+
+* Updated the minimal Python version to 3.8.
+* Switched from ``setup.cfg`` to ``pyproject.toml``.
+* Added the change log.
+* Simplified ``README.rst``.
+
+
+Version 0.5.0
+-------------
+
+Released 2023/1/6
+
+* Added the ``DIGEST_AUTH_REALM`` configuration variable as the
+  recommended way to set the authentication realm.
+* Changed the default realm from an empty string to
+  ``Login Required``.
+
+
+Version 0.4.0
+-------------
+
+Released 2023/1/4
+
+* Changed the package name from ``flask-digest-auth`` to
+  ``Flask-DigestAuth``, according to the Flask recommended extension
+  guidelines
+  https://flask.palletsprojects.com/en/latest/extensiondev/ .
+* Replaced ``app.digest_auth`` with ``app.extensions["digest-auth"]``
+  to store the ``DigestAuth`` instance.
+* Replaced ``auth.app`` with ``current_app``, to prevent circular
+  imports.
+
+
+Version 0.3.1
+-------------
+
+Released 2022/12/29
+
+Fixed the missing authentication state with disabled users.
+
+
+Version 0.3.0
+-------------
+
+Released 2022/12/7
+
+Changed the visibility of several methods and properties of the
+DigestAuth class that should be private to private.
+
+
+Version 0.2.4
+-------------
+
+Released 2022/12/6
+
+Fixed the pytest example in the documentation.
+
+
+Version 0.2.3
+-------------
+
+Released 2022/12/6
+
+Fixed the dependencies for the documentation hosted on Read the Docs.
+
+
+Version 0.2.2
+-------------
+
+Released 2022/12/6
+
+Added the Sphinx documentation, and hosted the documentation on
+Read the Docs.
+
+
+Version 0.2.1
+-------------
+
+Released 2022/12/6
+
+Various fixes, with the help from SonarQube.
+
+
+Version 0.2.0
+-------------
+
+Released 2022/11/27
+
+* Added log out support.  User can log out.
+* Added on-login event handler.  You can do some accounting when the
+  user logs in.
+
+This release is written in Sydney and on the international flight,
+and released in Taipei.
+
+
+Version 0.1.1
+-------------
+
+Released 2022/11/24
+
+Changed the minimal Python version to 3.7.
+
+Released at Sydney, Australia on vacation.
+
+
+Version 0.1.0
+-------------
+
+Released 2022/11/24
+
+The initial release.
+
+Released at Sydney, Australia on vacation.

docs/source/conf.py

@@ -1,59 +1,33 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import sys
 
 sys.path.insert(0, os.path.abspath('../../src/'))
-
+import flask_digest_auth
 
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Flask-Digest-Auth'
-copyright = '2022, imacat'
+project = 'Flask-DigestAuth'
+copyright = '2022-2023, imacat'
 author = 'imacat'
-
-# The full version, including alpha/beta/rc tags
-release = '0.2.4'
-
+release = flask_digest_auth.VERSION
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "sphinx.ext.autodoc"
-]
+extensions = ["sphinx.ext.autodoc"]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
 
+
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-
-# For readthedocs.io to work properly.
-master_doc = 'index'

docs/source/examples.rst

@@ -4,8 +4,8 @@ Examples
 
 .. _example-alone-simple:
 
-Simple Applications with Flask-Digest-Auth Alone
-------------------------------------------------
+Simple Applications with Flask-DigestAuth Alone
+-----------------------------------------------
 
 In your ``my_app.py``:
 
@@ -17,7 +17,7 @@ In your ``my_app.py``:
     app: flask = Flask(__name__)
     ... (Configure the Flask application) ...
 
-    auth: DigestAuth = DigestAuth(realm="Admin")
+    auth: DigestAuth = DigestAuth()
     auth.init_app(app)
 
     @auth.register_get_password
@@ -42,8 +42,8 @@ In your ``my_app.py``:
 
 .. _example-alone-large:
 
-Larger Applications with ``create_app()`` with Flask-Digest-Auth Alone
-----------------------------------------------------------------------
+Larger Applications with ``create_app()`` with Flask-DigestAuth Alone
+---------------------------------------------------------------------
 
 In your ``my_app/__init__.py``:
 
@@ -58,7 +58,6 @@ In your ``my_app/__init__.py``:
         app: flask = Flask(__name__)
         ... (Configure the Flask application) ...
 
-        auth.realm = app.config["REALM"]
         auth.init_app(app)
 
         @auth.register_get_password
@@ -118,7 +117,7 @@ In your ``my_app.py``:
     def load_user(user_id: str) -> t.Optional[User]:
         ... (Load the user with the username) ...
 
-    auth: DigestAuth = DigestAuth(realm="Admin")
+    auth: DigestAuth = DigestAuth()
     auth.init_app(app)
 
     @auth.register_get_password
@@ -164,7 +163,6 @@ In your ``my_app/__init__.py``:
         def load_user(user_id: str) -> t.Optional[User]:
             ... (Load the user with the username) ...
 
-        auth.realm = app.config["REALM"]
         auth.init_app(app)
 
         @auth.register_get_password
@@ -219,8 +217,9 @@ A unittest Test Case
 
         def create_app(self):
             app: Flask = create_app({
+                "TESTING": True,
                 "SECRET_KEY": token_urlsafe(32),
-                "TESTING": True
+                "DIGEST_AUTH_REALM": "admin",
             })
             app.test_client_class = Client
             return app
@@ -229,7 +228,7 @@ A unittest Test Case
             response = self.client.get("/admin")
             self.assertEqual(response.status_code, 401)
             response = self.client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             self.assertEqual(response.status_code, 200)
 
 
@@ -249,8 +248,9 @@ A pytest Test
     @pytest.fixture()
     def app():
         app: Flask = create_app({
+            "TESTING": True,
             "SECRET_KEY": token_urlsafe(32),
-            "TESTING": True
+            "DIGEST_AUTH_REALM": "admin",
         })
         app.test_client_class = Client
         yield app
@@ -264,5 +264,5 @@ A pytest Test
             response = client.get("/admin")
             assert response.status_code == 401
             response = client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             assert response.status_code == 200

docs/source/flask_digest_auth.rst

@@ -1,24 +1,37 @@
 flask\_digest\_auth package
 ===========================
 
-The ``DigestAuth`` Class
-------------------------
-.. autoclass:: flask_digest_auth.DigestAuth
+Submodules
+----------
+
+flask\_digest\_auth.algo module
+-------------------------------
+
+.. automodule:: flask_digest_auth.algo
    :members:
    :undoc-members:
    :show-inheritance:
 
-The ``make_password_hash`` Function
------------------------------------
-.. autofunction:: flask_digest_auth.make_password_hash
+flask\_digest\_auth.auth module
+-------------------------------
 
-The ``calc_response`` Function
-------------------------------
-.. autofunction:: flask_digest_auth.calc_response
-
-The ``Client`` Test Class
--------------------------
-.. autoclass:: flask_digest_auth.Client
+.. automodule:: flask_digest_auth.auth
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+flask\_digest\_auth.test module
+-------------------------------
+
+.. automodule:: flask_digest_auth.test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: flask_digest_auth
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/index.rst

@@ -1,12 +1,12 @@
-.. flask-digest-auth documentation master file, created by
-   sphinx-quickstart on Tue Dec  6 15:15:08 2022.
+.. Flask-DigestAuth documentation master file, created by
+   sphinx-quickstart on Wed Dec  7 09:40:48 2022.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Flask-Digest-Auth's documentation!
-=============================================
+Welcome to Flask-DigestAuth's documentation!
+============================================
 
-*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
 for Flask_ applications.  It authenticates the user for the protected
 views.
 
@@ -19,6 +19,7 @@ HTTP Digest Authentication is specified in `RFC 2617`_.
    intro
    flask_digest_auth
    examples
+   changelog
 
 
 
@@ -26,6 +27,7 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
+* :ref:`modindex`
 * :ref:`search`
 
 .. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication

docs/source/intro.rst

@@ -2,7 +2,7 @@ Introduction
 ============
 
 
-*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
 for Flask_ applications.  It authenticates the user for the protected
 views.
 
@@ -24,7 +24,7 @@ own challenge-response log in form, but then you are reinventing the
 wheels.  If a pretty log in form is not critical to your project, HTTP
 Digest Authentication should be a good choice.
 
-Flask-Digest-Auth works with Flask-Login_.  Log in protection can be
+Flask-DigestAuth works with Flask-Login_.  Log in protection can be
 separated with the authentication mechanism.  You can create protected
 Flask modules without knowing the actual authentication mechanisms.
 
@@ -32,18 +32,25 @@ Flask modules without knowing the actual authentication mechanisms.
 Installation
 ------------
 
-You can install Flask-Digest-Auth with ``pip``:
+You can install Flask-DigestAuth with ``pip``:
 
 ::
 
-    pip install Flask-Digest-Auth
+    pip install Flask-DigestAuth
 
 You may also install the latest source from the
-`Flask-Digest-Auth GitHub repository`_.
+`Flask-DigestAuth GitHub repository`_.
 
 ::
 
-    pip install git+https://github.com/imacat/flask-digest-auth.git
+    pip install git+https://github.com/imacat/flask-digestauth.git
+
+
+Configuration
+-------------
+
+Flask-DigestAuth takes the configuration ``DIGEST_AUTH_REALM`` as the
+realm.  The default realm is ``Login Required``.
 
 
 Setting the Password
@@ -63,13 +70,13 @@ The username is part of the hash.  If the user changes their username,
 you need to ask their password, to generate and store the new password
 hash.
 
-See :meth:`flask_digest_auth.make_password_hash`.
+See :func:`flask_digest_auth.algo.make_password_hash`.
 
 
-Flask-Digest-Auth Alone
------------------------
+Flask-DigestAuth Alone
+----------------------
 
-Flask-Digest-Auth can authenticate the users alone.
+Flask-DigestAuth can authenticate the users alone.
 
 See :ref:`example-alone-simple` and :ref:`example-alone-large`.
 
@@ -77,12 +84,12 @@ See :ref:`example-alone-simple` and :ref:`example-alone-large`.
 Flask-Login Integration
 -----------------------
 
-Flask-Digest-Auth works with Flask-Login_.  You can write a Flask
+Flask-DigestAuth works with Flask-Login_.  You can write a Flask
 module that requires log in, without specifying how to log in.  The
 application can use either HTTP Digest Authentication, or the log in
 forms, as needed.
 
-To use Flask-Login with Flask-Digest-Auth,
+To use Flask-Login with Flask-DigestAuth,
 ``login_manager.init_app(app)`` must be called before
 ``auth.init_app(app)``.
 
@@ -92,7 +99,7 @@ The currently logged-in user can be retrieved at
 See :ref:`example-flask-login-simple` and
 :ref:`example-flask-login-large`.
 
-The views only depend on Flask-Login, but not the Flask-Digest-Auth.
+The views only depend on Flask-Login, but not the Flask-DigestAuth.
 You can change the actual authentication mechanism without changing
 the views.
 
@@ -100,7 +107,7 @@ the views.
 Session Integration
 -------------------
 
-Flask-Digest-Auth features session integration.  The user log in
+Flask-DigestAuth features session integration.  The user log in
 is remembered in the session.  The authentication information is not
 requested again.  This is different to the practice of the HTTP Digest
 Authentication, but is convenient for the log in accounting.
@@ -118,25 +125,25 @@ logging the log in event, adding the log in counter, etc.
     def on_login(user: User) -> None:
         user.visits = user.visits + 1
 
-See :meth:`flask_digest_auth.DigestAuth.register_on_login`.
+See :meth:`flask_digest_auth.auth.DigestAuth.register_on_login`.
 
 
 Log Out
 -------
 
-Flask-Digest-Auth supports log out.  The user will be prompted for the
+Flask-DigestAuth supports log out.  The user will be prompted for the
 new username and password.
 
-See :meth:`flask_digest_auth.DigestAuth.logout`.
+See :meth:`flask_digest_auth.auth.DigestAuth.logout`.
 
 
 Test Client
 -----------
 
-Flask-Digest-Auth comes with a test client that supports HTTP digest
+Flask-DigestAuth comes with a test client that supports HTTP digest
 authentication.
 
-See :class:`flask_digest_auth.Client`.
+See :class:`flask_digest_auth.test.Client`.
 
 Also see :ref:`example-unittest` and :ref:`example-pytest`.
 
@@ -145,4 +152,4 @@ Also see :ref:`example-unittest` and :ref:`example-pytest`.
 .. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
 .. _Flask: https://flask.palletsprojects.com
 .. _Flask-Login: https://flask-login.readthedocs.io
-.. _Flask-Digest-Auth GitHub repository: https://github.com/imacat/flask-digest-auth
+.. _Flask-DigestAuth GitHub repository: https://github.com/imacat/flask-digestauth

docs/source/modules.rst

@@ -0,0 +1,7 @@
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   flask_digest_auth

pyproject.toml

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/11/23
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -15,6 +15,43 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+[project]
+name = "Flask-DigestAuth"
+dynamic = ["version"]
+description = "The Flask HTTP Digest Authentication project."
+readme = "README.rst"
+requires-python = ">=3.8"
+authors = [
+    {name = "imacat", email = "imacat@mail.imacat.idv.tw"},
+]
+keywords = ["flask", "digest-authentication"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Framework :: Flask",
+    "Topic :: System :: Systems Administration :: Authentication/Directory",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "flask",
+]
+
+[project.optional-dependencies]
+test = [
+    "unittest",
+    "flask-testing",
+]
+
+[project.urls]
+"Documentation" = "https://flask-digestauth.readthedocs.io"
+"Change Log" = "https://mia-accounting.readthedocs.io/en/latest/changelog.html"
+"Repository" = "https://github.com/imacat/flask-digestauth"
+"Bug Tracker" = "https://github.com/imacat/flask-digestauth/issues"
+
 [build-system]
 requires = ["setuptools>=42"]
 build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "flask_digest_auth.VERSION"}

setup.cfg

@@ -1,53 +0,0 @@
-# The Flask HTTP Digest Authentication Project.
-# Author: imacat@mail.imacat.idv.tw (imacat), 2022/11/23
-
-#  Copyright (c) 2022 imacat.
-#
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-[metadata]
-name = flask-digest-auth
-version = 0.2.4
-author = imacat
-author_email = imacat@mail.imacat.idv.tw
-description = The Flask HTTP Digest Authentication project.
-long_description = file: README.rst
-long_description_content_type = text/x-rst
-url = https://github.com/imacat/flask-digest-auth
-project_urls =
-    Bug Tracker = https://github.com/imacat/flask-digest-auth/issues
-classifiers =
-    Programming Language :: Python :: 3
-    License :: OSI Approved :: Apache Software License
-    Operating System :: OS Independent
-    Framework :: Flask
-    Topic :: System :: Systems Administration :: Authentication/Directory
-    Intended Audience :: Developers
-
-[options]
-package_dir =
-    = src
-packages = find:
-python_requires = >=3.7
-install_requires =
-  flask
-tests_require =
-  unittest
-  flask-testing
-
-[options.packages.find]
-where = src
-
-[options.extras_require]
-flask_login =
-    flask-login

src/flask_digest_auth/__init__.py

@@ -21,3 +21,6 @@
 from flask_digest_auth.algo import make_password_hash, calc_response
 from flask_digest_auth.auth import DigestAuth
 from flask_digest_auth.test import Client
+
+VERSION: str = "0.6.2"
+"""The package version."""

src/flask_digest_auth/algo.py

@@ -20,15 +20,15 @@
 """
 from __future__ import annotations
 
-import typing as t
 from hashlib import md5
+from typing import Optional, Literal
 
 
 def make_password_hash(realm: str, username: str, password: str) -> str:
     """Calculates the password hash for the HTTP digest authentication.
     Use this function to set the password for the user.
 
-    For example:
+    :Example:
 
     ::
 
@@ -44,17 +44,17 @@ def make_password_hash(realm: str, username: str, password: str) -> str:
 
 def calc_response(
         method: str, uri: str, password_hash: str,
-        nonce: str, qop: t.Optional[t.Literal["auth", "auth-int"]] = None,
-        algorithm: t.Optional[t.Literal["MD5", "MD5-sess"]] = "MD5-sess",
-        cnonce: t.Optional[str] = None, nc: t.Optional[str] = None,
-        body: t.Optional[bytes] = None) -> str:
+        nonce: str, qop: Optional[Literal["auth", "auth-int"]] = None,
+        algorithm: Optional[Literal["MD5", "MD5-sess"]] = "MD5-sess",
+        cnonce: Optional[str] = None, nc: Optional[str] = None,
+        body: Optional[bytes] = None) -> str:
     """Calculates the response value of the HTTP digest authentication.
 
     :param method: The request method.
     :param uri: The request URI.
     :param password_hash: The password hash for the HTTP digest authentication.
     :param nonce: The nonce.
-    :param qop: the quality of protection, either ``auth`` or ``auth-int``.
+    :param qop: The quality of protection, either ``auth`` or ``auth-int``.
     :param algorithm: The algorithm, either ``MD5`` or ``MD5-sess``.
     :param cnonce: The client nonce, which must exists when qop exists or
         algorithm is ``MD5-sess``.

src/flask_digest_auth/auth.py

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/10/22
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -16,17 +16,19 @@
 #  limitations under the License.
 
 """The HTTP Digest Authentication.
-See RFC 2617 HTTP Authentication: Basic and Digest Access Authentication
+See `RFC 2617`_ HTTP Authentication: Basic and Digest Access Authentication
 
+.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
 """
 from __future__ import annotations
 
 import sys
-import typing as t
 from functools import wraps
 from secrets import token_urlsafe, randbits
+from typing import Any, Optional, Literal, Callable, List
 
-from flask import g, request, Response, session, abort, Flask, Request
+from flask import g, request, Response, session, abort, Flask, Request, \
+    current_app
 from itsdangerous import URLSafeTimedSerializer, BadData
 from werkzeug.datastructures import Authorization
 
@@ -36,32 +38,43 @@ from flask_digest_auth.algo import calc_response
 class DigestAuth:
     """The HTTP digest authentication."""
 
-    def __init__(self, realm: t.Optional[str] = None):
+    def __init__(self, realm: Optional[str] = None):
         """Constructs the HTTP digest authentication.
 
         :param realm: The realm.
         """
-        self.secret_key: str = token_urlsafe(32)
-        self.serializer: URLSafeTimedSerializer \
-            = URLSafeTimedSerializer(self.secret_key)
-        self.realm: str = "" if realm is None else realm
-        self.algorithm: t.Optional[str] = None
+        self.__serializer: URLSafeTimedSerializer \
+            = URLSafeTimedSerializer(token_urlsafe(32))
+        """The serializer to generate and validate the nonce and opaque."""
+        self.realm: str = "Login Required" if realm is None else realm
+        """The realm.  Default is "Login Required"."""
+        self.algorithm: Optional[Literal["MD5", "MD5-sess"]] = None
+        """The algorithm, either None, ``MD5``, or ``MD5-sess``.  Default is
+        None."""
         self.use_opaque: bool = True
-        self.domain: t.List[str] = []
-        self.qop: t.List[str] = ["auth", "auth-int"]
-        self.app: t.Optional[Flask] = None
+        """Whether to use an opaque.  Default is True."""
+        self.__domain: List[str] = []
+        """A list of directories that this username and password applies to.
+        Default is empty."""
+        self.__qop: List[Literal["auth", "auth-int"]] = ["auth", "auth-int"]
+        """A list of supported quality of protection supported, either
+        ``qop``, ``auth-int``, both, or empty.  Default is both."""
         self.__get_password_hash: BasePasswordHashGetter \
             = BasePasswordHashGetter()
+        """The callback to return the password hash."""
         self.__get_user: BaseUserGetter = BaseUserGetter()
+        """The callback to return the user."""
         self.__on_login: BaseOnLogInCallback = BaseOnLogInCallback()
+        """The callback to run when the user logs in."""
 
-    def login_required(self, view) -> t.Callable:
-        """The view decorator for HTTP digest authentication.
+    def login_required(self, view) -> Callable:
+        """The view decorator for the HTTP digest authentication.
 
-        For example:
+        :Example:
 
         ::
 
+            @app.get("/admin")
             @auth.login_required
             def admin():
                 return f"Hello, {g.user.username}!"
@@ -75,7 +88,7 @@ class DigestAuth:
         class NoLogInException(Exception):
             """The exception thrown when the user is not authorized."""
 
-        def get_logged_in_user() -> t.Any:
+        def get_logged_in_user() -> Any:
             """Returns the currently logged-in user.
 
             :return: The currently logged-in user.
@@ -83,13 +96,13 @@ class DigestAuth:
             """
             if "user" not in session:
                 raise NoLogInException
-            user: t.Optional[t.Any] = self.__get_user(session["user"])
+            user: Optional[Any] = self.__get_user(session["user"])
             if user is None:
                 del session["user"]
                 raise NoLogInException
             return user
 
-        def auth_user(state: AuthState) -> t.Any:
+        def auth_user(state: AuthState) -> Any:
             """Authenticates a user.
 
             :param state: The authentication state.
@@ -107,7 +120,7 @@ class DigestAuth:
             return self.__get_user(authorization.username)
 
         @wraps(view)
-        def login_required_view(*args, **kwargs) -> t.Any:
+        def login_required_view(*args, **kwargs) -> Any:
             """The login-protected view.
 
             :param args: The positional arguments of the view.
@@ -127,7 +140,7 @@ class DigestAuth:
                 return view(*args, **kwargs)
             except UnauthorizedException as e:
                 if len(e.args) > 0:
-                    sys.stderr.write(e.args[0] + "\n")
+                    current_app.logger.warning(e.args[0])
                 response: Response = Response()
                 response.status = 401
                 response.headers["WWW-Authenticate"] \
@@ -152,12 +165,12 @@ class DigestAuth:
                 raise UnauthorizedException(
                     "Missing \"opaque\" in the Authorization header")
             try:
-                self.serializer.loads(
+                self.__serializer.loads(
                     authorization.opaque, salt="opaque", max_age=1800)
             except BadData:
                 raise UnauthorizedException("Invalid opaque")
             state.opaque = authorization.opaque
-        password_hash: t.Optional[str] \
+        password_hash: Optional[str] \
             = self.__get_password_hash(authorization.username)
         if password_hash is None:
             raise UnauthorizedException(
@@ -173,7 +186,7 @@ class DigestAuth:
             state.stale = False
             raise UnauthorizedException("Incorrect response value")
         try:
-            self.serializer.loads(
+            self.__serializer.loads(
                 authorization.nonce,
                 salt="nonce" if authorization.opaque is None
                 else f"nonce-{authorization.opaque}")
@@ -188,7 +201,7 @@ class DigestAuth:
         :return: The ``WWW-Authenticate`` response header.
         """
 
-        def get_opaque() -> t.Optional[str]:
+        def get_opaque() -> Optional[str]:
             """Returns the opaque value.
 
             :return: The opaque value.
@@ -197,34 +210,34 @@ class DigestAuth:
                 return None
             if state.opaque is not None:
                 return state.opaque
-            return self.serializer.dumps(randbits(32), salt="opaque")
+            return self.__serializer.dumps(randbits(32), salt="opaque")
 
-        opaque: t.Optional[str] = get_opaque()
-        nonce: str = self.serializer.dumps(
+        opaque: Optional[str] = get_opaque()
+        nonce: str = self.__serializer.dumps(
             randbits(32),
             salt="nonce" if opaque is None else f"nonce-{opaque}")
 
         header: str = f"Digest realm=\"{self.realm}\""
-        if len(self.domain) > 0:
-            domain_list: str = ",".join(self.domain)
+        if len(self.__domain) > 0:
+            domain_list: str = ",".join(self.__domain)
             header += f", domain=\"{domain_list}\""
         header += f", nonce=\"{nonce}\""
         if opaque is not None:
             header += f", opaque=\"{opaque}\""
         if state.stale is not None:
-            header += f", stale=TRUE" if state.stale else f", stale=FALSE"
+            header += ", stale=TRUE" if state.stale else ", stale=FALSE"
         if self.algorithm is not None:
             header += f", algorithm=\"{self.algorithm}\""
-        if len(self.qop) > 0:
-            qop_list: str = ",".join(self.qop)
+        if len(self.__qop) > 0:
+            qop_list: str = ",".join(self.__qop)
             header += f", qop=\"{qop_list}\""
         return header
 
-    def register_get_password(self, func: t.Callable[[str], t.Optional[str]])\
+    def register_get_password(self, func: Callable[[str], Optional[str]]) \
             -> None:
         """The decorator to register the callback to obtain the password hash.
 
-        For example:
+        :Example:
 
         ::
 
@@ -242,7 +255,7 @@ class DigestAuth:
             """The base password hash getter."""
 
             @staticmethod
-            def __call__(username: str) -> t.Optional[str]:
+            def __call__(username: str) -> Optional[str]:
                 """Returns the password hash of a user.
 
                 :param username: The username.
@@ -252,11 +265,10 @@ class DigestAuth:
 
         self.__get_password_hash = PasswordHashGetter()
 
-    def register_get_user(self, func: t.Callable[[str], t.Optional[t.Any]])\
-            -> None:
+    def register_get_user(self, func: Callable[[str], Optional[Any]]) -> None:
         """The decorator to register the callback to obtain the user.
 
-        For example:
+        :Example:
 
         ::
 
@@ -273,7 +285,7 @@ class DigestAuth:
             """The user getter."""
 
             @staticmethod
-            def __call__(username: str) -> t.Optional[t.Any]:
+            def __call__(username: str) -> Optional[Any]:
                 """Returns a user.
 
                 :param username: The username.
@@ -283,10 +295,10 @@ class DigestAuth:
 
         self.__get_user = UserGetter()
 
-    def register_on_login(self, func: t.Callable[[t.Any], None]) -> None:
+    def register_on_login(self, func: Callable[[Any], None]) -> None:
         """The decorator to register the callback to run when the user logs in.
 
-        For example:
+        :Example:
 
         ::
 
@@ -302,7 +314,7 @@ class DigestAuth:
             """The callback when the user logs in."""
 
             @staticmethod
-            def __call__(user: t.Any) -> None:
+            def __call__(user: Any) -> None:
                 """Runs the callback when the user logs in.
 
                 :param user: The logged-in user.
@@ -313,26 +325,34 @@ class DigestAuth:
         self.__on_login = OnLogInCallback()
 
     def init_app(self, app: Flask) -> None:
-        """Initializes the Flask application.
+        """Initializes the Flask application.  The DigestAuth instance will
+        be stored in ``app.extensions["digest_auth"]``.
 
-        For example:
+        :Example:
 
         ::
 
             app: flask = Flask(__name__)
             auth: DigestAuth = DigestAuth()
-            auth.realm = "My Admin"
             auth.init_app(app)
 
         :param app: The Flask application.
         :return: None.
         """
-        app.digest_auth = self
-        self.app = app
+        app.extensions["digest_auth"] = self
+        if "DIGEST_AUTH_REALM" in app.config:
+            self.realm = app.config["DIGEST_AUTH_REALM"]
 
         if hasattr(app, "login_manager"):
-            from flask_login import LoginManager, login_user
+            self.__init_login_manager(app)
 
+    def __init_login_manager(self, app: Flask) -> None:
+        """Initializes the Flask-Login login manager.
+
+        :param app: The Flask application.
+        :return: None.
+        """
+        from flask_login import LoginManager, login_user
         login_manager: LoginManager = getattr(app, "login_manager")
 
         @login_manager.unauthorized_handler
@@ -341,21 +361,24 @@ class DigestAuth:
 
             :return: None.
             """
+            state: AuthState = getattr(request, "_digest_auth_state") \
+                if hasattr(request, "_digest_auth_state") \
+                else AuthState()
             response: Response = Response()
             response.status = 401
             response.headers["WWW-Authenticate"] \
-                    = self.__make_response_header(g.digest_auth_state)
+                = self.__make_response_header(state)
             abort(response)
 
         @login_manager.request_loader
-            def load_user_from_request(req: Request) -> t.Optional[t.Any]:
+        def load_user_from_request(req: Request) -> Optional[Any]:
             """Loads the user from the request header.
 
             :param req: The request.
             :return: The authenticated user, or None if the
                 authentication fails
             """
-                g.digest_auth_state = AuthState()
+            request._digest_auth_state = AuthState()
             authorization: Authorization = req.authorization
             try:
                 if authorization is None:
@@ -363,9 +386,8 @@ class DigestAuth:
                 if authorization.type != "digest":
                     raise UnauthorizedException(
                         "Not an HTTP digest authorization")
-                    self.__authenticate(g.digest_auth_state)
-                    user = login_manager.user_callback(
-                        authorization.username)
+                self.__authenticate(request._digest_auth_state)
+                user = login_manager.user_callback(authorization.username)
                 login_user(user)
                 self.__on_login(user)
                 return user
@@ -379,7 +401,7 @@ class DigestAuth:
         This actually causes the next authentication to fail, which forces
         the browser to ask the user for the username and password again.
 
-        For example:
+        :Example:
 
         ::
 
@@ -394,7 +416,7 @@ class DigestAuth:
         if "user" in session:
             del session["user"]
         try:
-            if hasattr(self.app, "login_manager"):
+            if hasattr(current_app, "login_manager"):
                 from flask_login import logout_user
                 logout_user()
         except ModuleNotFoundError:
@@ -403,24 +425,33 @@ class DigestAuth:
 
 
 class AuthState:
-    """The authorization state."""
+    """The authentication state.  It keeps the status in the earlier
+    authentication stage, so that the latter response stage knows how to
+    response.
+    """
 
     def __init__(self):
         """Constructs the authorization state."""
-        self.opaque: t.Optional[str] = None
-        self.stale: t.Optional[bool] = None
+        self.opaque: Optional[str] = None
+        """The opaque value specified by the client, if valid."""
+        self.stale: Optional[bool] = None
+        """The stale value, if there is a previous log in attempt."""
 
 
 class UnauthorizedException(Exception):
-    """The exception thrown when the authentication is failed."""
-    pass
+    """The exception thrown when the authentication fails."""
 
 
 class BasePasswordHashGetter:
-    """The base password hash getter."""
+    """The base callback that given the username, returns the password hash,
+    or None if the user does not exist.  The default is to raise an
+    :class:`UnboundLocalError` if the callback is not registered yet.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_get_password`
+    """
 
     @staticmethod
-    def __call__(username: str) -> t.Optional[str]:
+    def __call__(username: str) -> Optional[str]:
         """Returns the password hash of a user.
 
         :param username: The username.
@@ -433,10 +464,15 @@ class BasePasswordHashGetter:
 
 
 class BaseUserGetter:
-    """The base user getter."""
+    """The base callback that given the username, returns the user, or None if
+    the user does not exist.  The default is to raise an
+    :class:`UnboundLocalError` if the callback is not registered yet.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_get_user`
+    """
 
     @staticmethod
-    def __call__(username: str) -> t.Optional[t.Any]:
+    def __call__(username: str) -> Optional[Any]:
         """Returns a user.
 
         :param username: The username.
@@ -449,10 +485,14 @@ class BaseUserGetter:
 
 
 class BaseOnLogInCallback:
-    """The base callback when the user logs in."""
+    """The base callback to run when the user logs in, given the logged-in
+    user.  The default does nothing.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_on_login`
+    """
 
     @staticmethod
-    def __call__(user: t.Any) -> None:
+    def __call__(user: Any) -> None:
         """Runs the callback when the user logs in.
 
         :param user: The logged-in user.

src/flask_digest_auth/test.py

@@ -18,11 +18,12 @@
 """The test client with HTTP digest authentication enabled.
 
 """
-import typing as t
 from secrets import token_urlsafe
+from typing import Optional, Literal, Tuple, Dict
 
 from flask import g
 from werkzeug.datastructures import Authorization, WWWAuthenticate
+from werkzeug.http import parse_set_header
 from werkzeug.test import TestResponse, Client as WerkzeugClient
 
 from flask_digest_auth.algo import calc_response, make_password_hash
@@ -31,7 +32,9 @@ from flask_digest_auth.algo import calc_response, make_password_hash
 class Client(WerkzeugClient):
     """The test client with HTTP digest authentication enabled.
 
-    For unittest example:
+    :Example:
+
+    For unittest_:
 
     ::
 
@@ -49,10 +52,10 @@ class Client(WerkzeugClient):
                 response = self.client.get("/admin")
                 self.assertEqual(response.status_code, 401)
                 response = self.client.get(
-                    "/admin", digest_auth=("my_name", "my_pass"))
+                    "/admin", digest_auth=(USERNAME, PASSWORD))
                 self.assertEqual(response.status_code, 200)
 
-    For pytest example:
+    For pytest_:
 
     ::
 
@@ -74,16 +77,19 @@ class Client(WerkzeugClient):
                 response = client.get("/admin")
                 assert response.status_code == 401
                 response = client.get(
-                    "/admin", digest_auth=("my_name", "my_pass"))
+                    "/admin", digest_auth=(USERNAME, PASSWORD))
                 assert response.status_code == 200
+
+    .. _unittest: https://docs.python.org/3/library/unittest.html
+    .. _pytest: https://pytest.org
     """
 
-    def open(self, *args, digest_auth: t.Optional[t.Tuple[str, str]] = None,
+    def open(self, *args, digest_auth: Optional[Tuple[str, str]] = None,
              **kwargs) -> TestResponse:
         """Opens a request.
 
         :param args: The arguments.
-        :param digest_auth: A tuple of the username and password for the HTTP
+        :param digest_auth: The (*username*, *password*) tuple for the HTTP
             digest authentication.
         :param kwargs: The keyword arguments.
         :return: The response.
@@ -112,14 +118,14 @@ class Client(WerkzeugClient):
         :param password: The password.
         :return: The request authorization.
         """
-        qop: t.Optional[t.Literal["auth", "auth-int"]] = None
-        if www_authenticate.qop is not None and "auth" in www_authenticate.qop:
+        qop: Optional[Literal["auth", "auth-int"]] = None
+        if "auth" in parse_set_header(www_authenticate.get("qop")):
             qop = "auth"
 
-        cnonce: t.Optional[str] = None
+        cnonce: Optional[str] = None
         if qop is not None or www_authenticate.algorithm == "MD5-sess":
             cnonce = token_urlsafe(8)
-        nc: t.Optional[str] = None
+        nc: Optional[str] = None
         count: int = 1
         if qop is not None:
             nc: str = hex(count)[2:].zfill(8)
@@ -132,7 +138,7 @@ class Client(WerkzeugClient):
             algorithm=www_authenticate.algorithm, cnonce=cnonce, nc=nc,
             body=None)
 
-        data: t.Dict[str, str] = {
+        data: Dict[str, str] = {
             "username": username, "realm": www_authenticate.realm,
             "nonce": www_authenticate.nonce, "uri": uri, "response": expected}
         if www_authenticate.algorithm is not None:

tests/test_algo.py

@@ -18,8 +18,8 @@
 """The test case for the HTTP digest authentication algorithm.
 
 """
-import typing as t
 import unittest
+from typing import Optional, Literal
 
 from flask_digest_auth import make_password_hash, calc_response
 
@@ -39,11 +39,11 @@ class AlgorithmTestCase(unittest.TestCase):
         method: str = "GET"
         uri: str = "/dir/index.html"
         nonce: str = "dcd98b7102dd2f0e8b11d0f600bfb0c093"
-        qop: t.Optional[t.Literal["auth", "auth-int"]] = "auth"
-        algorithm: t.Optional[t.Literal["MD5", "MD5-sess"]] = None
-        cnonce: t.Optional[str] = "0a4f113b"
-        nc: t.Optional[str] = "00000001"
-        body: t.Optional[bytes] = None
+        qop: Optional[Literal["auth", "auth-int"]] = "auth"
+        algorithm: Optional[Literal["MD5", "MD5-sess"]] = None
+        cnonce: Optional[str] = "0a4f113b"
+        nc: Optional[str] = "00000001"
+        body: Optional[bytes] = None
 
         password_hash: str = make_password_hash(realm, username, password)
         response: str = calc_response(method, uri, password_hash, nonce, qop,

tests/test_auth.py

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/10/22
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -18,8 +18,9 @@
 """The test case for the HTTP digest authentication.
 
 """
-import typing as t
+import logging
 from secrets import token_urlsafe
+from typing import Any, Optional, Dict
 
 from flask import Response, Flask, g, redirect, request
 from flask_testing import TestCase
@@ -28,8 +29,11 @@ from werkzeug.datastructures import WWWAuthenticate, Authorization
 from flask_digest_auth import DigestAuth, make_password_hash, Client
 
 _REALM: str = "testrealm@host.com"
+"""The realm."""
 _USERNAME: str = "Mufasa"
+"""The username."""
 _PASSWORD: str = "Circle Of Life"
+"""The password."""
 
 
 class User:
@@ -42,9 +46,11 @@ class User:
         :param password: The clear-text password.
         """
         self.username: str = username
-        self.password_hash: str = make_password_hash(
-            _REALM, username, password)
+        """The username."""
+        self.password_hash: str = make_password_hash(_REALM, username, password)
+        """The password hash."""
         self.visits: int = 0
+        """The number of visits."""
 
 
 class AuthenticationTestCase(TestCase):
@@ -55,20 +61,23 @@ class AuthenticationTestCase(TestCase):
 
         :return: The Flask application.
         """
+        logging.getLogger("test_auth").addHandler(logging.NullHandler())
         app: Flask = Flask(__name__)
         app.config.from_mapping({
+            "TESTING": True,
             "SECRET_KEY": token_urlsafe(32),
-            "TESTING": True
+            "DIGEST_AUTH_REALM": _REALM,
         })
         app.test_client_class = Client
 
-        auth: DigestAuth = DigestAuth(realm=_REALM)
+        auth: DigestAuth = DigestAuth()
         auth.init_app(app)
-        self.user: User = User(_USERNAME, _PASSWORD)
-        user_db: t.Dict[str, User] = {_USERNAME: self.user}
+        self.__user: User = User(_USERNAME, _PASSWORD)
+        """The user account."""
+        user_db: Dict[str, User] = {_USERNAME: self.__user}
 
         @auth.register_get_password
-        def get_password_hash(username: str) -> t.Optional[str]:
+        def get_password_hash(username: str) -> Optional[str]:
             """Returns the password hash of a user.
 
             :param username: The username.
@@ -78,7 +87,7 @@ class AuthenticationTestCase(TestCase):
                 else None
 
         @auth.register_get_user
-        def get_user(username: str) -> t.Optional[t.Any]:
+        def get_user(username: str) -> Optional[Any]:
             """Returns a user.
 
             :param username: The username.
@@ -141,7 +150,7 @@ class AuthenticationTestCase(TestCase):
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.data.decode("UTF-8"),
                          f"Hello, {_USERNAME}! #2")
-        self.assertEqual(self.user.visits, 1)
+        self.assertEqual(self.__user.visits, 1)
 
     def test_stale_opaque(self) -> None:
         """Tests the stale and opaque value.
@@ -157,7 +166,7 @@ class AuthenticationTestCase(TestCase):
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
         self.assertEqual(www_authenticate.type, "digest")
-        self.assertEqual(www_authenticate.stale, None)
+        self.assertIsNone(www_authenticate.get("stale"))
         opaque: str = www_authenticate.opaque
 
         www_authenticate.nonce = "bad"
@@ -166,7 +175,7 @@ class AuthenticationTestCase(TestCase):
         response = super(Client, self.client).get(admin_uri, auth=auth_data)
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
-        self.assertEqual(www_authenticate.stale, True)
+        self.assertEqual(www_authenticate.get("stale"), "TRUE")
         self.assertEqual(www_authenticate.opaque, opaque)
 
         auth_data = Client.make_authorization(
@@ -174,7 +183,7 @@ class AuthenticationTestCase(TestCase):
         response = super(Client, self.client).get(admin_uri, auth=auth_data)
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
-        self.assertEqual(www_authenticate.stale, False)
+        self.assertEqual(www_authenticate.get("stale"), "FALSE")
         self.assertEqual(www_authenticate.opaque, opaque)
 
         auth_data = Client.make_authorization(
@@ -218,4 +227,4 @@ class AuthenticationTestCase(TestCase):
 
         response = self.client.get(admin_uri)
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(self.user.visits, 2)
+        self.assertEqual(self.__user.visits, 2)

tests/test_flask_login.py

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/11/23
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -18,8 +18,9 @@
 """The test case for the Flask-Login integration.
 
 """
-import typing as t
+import logging
 from secrets import token_urlsafe
+from typing import Optional, Dict
 
 from flask import Response, Flask, g, redirect, request
 from flask_testing import TestCase
@@ -28,8 +29,11 @@ from werkzeug.datastructures import WWWAuthenticate, Authorization
 from flask_digest_auth import DigestAuth, make_password_hash, Client
 
 _REALM: str = "testrealm@host.com"
+"""The realm."""
 _USERNAME: str = "Mufasa"
+"""The username."""
 _PASSWORD: str = "Circle Of Life"
+"""The password."""
 
 
 class User:
@@ -42,12 +46,15 @@ class User:
         :param password: The clear-text password.
         """
         self.username: str = username
-        self.password_hash: str = make_password_hash(
-            _REALM, username, password)
+        """The username."""
+        self.password_hash: str = make_password_hash(_REALM, username, password)
+        """The password hash."""
         self.visits: int = 0
-        self.is_authenticated: bool = True
+        """The number of visits."""
         self.is_active: bool = True
+        """True if the account is active, or False otherwise."""
         self.is_anonymous: bool = False
+        """True if the account is anonymous, or False otherwise."""
 
     def get_id(self) -> str:
         """Returns the username.
@@ -57,6 +64,16 @@ class User:
         """
         return self.username
 
+    @property
+    def is_authenticated(self) -> bool:
+        """Returns whether the user is authenticated.
+        This is required by Flask-Login.
+        This should return self.is_active.
+
+        :return: True if the user is active, or False otherwise.
+        """
+        return self.is_active
+
 
 class FlaskLoginTestCase(TestCase):
     """The test case with the Flask-Login integration."""
@@ -66,31 +83,35 @@ class FlaskLoginTestCase(TestCase):
 
         :return: The Flask application.
         """
+        logging.getLogger("test_flask_login").addHandler(logging.NullHandler())
         app: Flask = Flask(__name__)
         app.config.from_mapping({
+            "TESTING": True,
             "SECRET_KEY": token_urlsafe(32),
-            "TESTING": True
+            "DIGEST_AUTH_REALM": _REALM,
         })
         app.test_client_class = Client
 
-        self.has_flask_login: bool = True
+        self.__has_flask_login: bool = True
+        """Whether the Flask-Login package is installed."""
         try:
             import flask_login
         except ModuleNotFoundError:
-            self.has_flask_login = False
+            self.__has_flask_login = False
             return app
 
         login_manager: flask_login.LoginManager = flask_login.LoginManager()
         login_manager.init_app(app)
 
-        auth: DigestAuth = DigestAuth(realm=_REALM)
+        auth: DigestAuth = DigestAuth()
         auth.init_app(app)
 
-        self.user: User = User(_USERNAME, _PASSWORD)
-        user_db: t.Dict[str, User] = {_USERNAME: self.user}
+        self.__user: User = User(_USERNAME, _PASSWORD)
+        """The user account."""
+        user_db: Dict[str, User] = {_USERNAME: self.__user}
 
         @auth.register_get_password
-        def get_password_hash(username: str) -> t.Optional[str]:
+        def get_password_hash(username: str) -> Optional[str]:
             """Returns the password hash of a user.
 
             :param username: The username.
@@ -109,7 +130,7 @@ class FlaskLoginTestCase(TestCase):
             user.visits = user.visits + 1
 
         @login_manager.user_loader
-        def load_user(user_id: str) -> t.Optional[User]:
+        def load_user(user_id: str) -> Optional[User]:
             """Loads a user.
 
             :param user_id: The username.
@@ -152,7 +173,7 @@ class FlaskLoginTestCase(TestCase):
 
         :return: None.
         """
-        if not self.has_flask_login:
+        if not self.__has_flask_login:
             self.skipTest("Skipped without Flask-Login.")
 
         response: Response = self.client.get(self.app.url_for("admin-1"))
@@ -166,14 +187,14 @@ class FlaskLoginTestCase(TestCase):
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.data.decode("UTF-8"),
                          f"Hello, {_USERNAME}! #2")
-        self.assertEqual(self.user.visits, 1)
+        self.assertEqual(self.__user.visits, 1)
 
     def test_stale_opaque(self) -> None:
         """Tests the stale and opaque value.
 
         :return: None.
         """
-        if not self.has_flask_login:
+        if not self.__has_flask_login:
             self.skipTest("Skipped without Flask-Login.")
 
         admin_uri: str = self.app.url_for("admin-1")
@@ -185,7 +206,7 @@ class FlaskLoginTestCase(TestCase):
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
         self.assertEqual(www_authenticate.type, "digest")
-        self.assertEqual(www_authenticate.stale, None)
+        self.assertIsNone(www_authenticate.get("stale"))
         opaque: str = www_authenticate.opaque
 
         if hasattr(g, "_login_user"):
@@ -196,7 +217,7 @@ class FlaskLoginTestCase(TestCase):
         response = super(Client, self.client).get(admin_uri, auth=auth_data)
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
-        self.assertEqual(www_authenticate.stale, True)
+        self.assertEqual(www_authenticate.get("stale"), "TRUE")
         self.assertEqual(www_authenticate.opaque, opaque)
 
         if hasattr(g, "_login_user"):
@@ -206,7 +227,7 @@ class FlaskLoginTestCase(TestCase):
         response = super(Client, self.client).get(admin_uri, auth=auth_data)
         self.assertEqual(response.status_code, 401)
         www_authenticate = response.www_authenticate
-        self.assertEqual(www_authenticate.stale, False)
+        self.assertEqual(www_authenticate.get("stale"), "FALSE")
         self.assertEqual(www_authenticate.opaque, opaque)
 
         if hasattr(g, "_login_user"):
@@ -221,7 +242,7 @@ class FlaskLoginTestCase(TestCase):
 
         :return: None.
         """
-        if not self.has_flask_login:
+        if not self.__has_flask_login:
             self.skipTest("Skipped without Flask-Login.")
 
         admin_uri: str = self.app.url_for("admin-1")
@@ -255,4 +276,35 @@ class FlaskLoginTestCase(TestCase):
 
         response = self.client.get(admin_uri)
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(self.user.visits, 2)
+        self.assertEqual(self.__user.visits, 2)
+
+    def test_disabled(self) -> None:
+        """Tests the disabled user.
+
+        :return: None.
+        """
+        if not self.__has_flask_login:
+            self.skipTest("Skipped without Flask-Login.")
+
+        response: Response
+
+        self.__user.is_active = False
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 401)
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 401)
+
+        self.__user.is_active = True
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 200)
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 200)
+
+        self.__user.is_active = False
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 401)
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 401)