sanic-security 1.12.0__tar.gz → 1.12.1__tar.gz

{sanic_security-1.12.0/sanic_security.egg-info → sanic_security-1.12.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: sanic-security
-Version: 1.12.0
-Summary: An effective, simple, and async security library for the Sanic framework.
+Version: 1.12.1
+Summary: An async security library for the Sanic framework.
 Author-email: Aidan Stewart <na.stewart365@gmail.com>
 Project-URL: Documentation, https://security.na-stewart.com/
 Project-URL: Repository, https://github.com/na-stewart/sanic-security
@@ -48,7 +48,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 <p align="center">
   <h3 align="center">Sanic Security</h3>
   <p align="center">
-   An effective, simple, and async security library for the Sanic framework.
+   An async security library for the Sanic framework.
   </p>
 </p>
 
@@ -77,7 +77,6 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 ## About The Project
 
 Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
-This library contains a variety of features including:
 
 * Login, registration, and authentication with refresh mechanisms
 * Two-factor authentication
@@ -85,7 +84,7 @@ This library contains a variety of features including:
 * Two-step verification
 * Role based authorization with wildcard permissions
 
-Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [click here for a comprehensive implementation guide](https://blog.na-stewart.com/entry?id=3).
+Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [here for an implementation guide](https://blog.na-stewart.com/entry?id=3).
 
 <!-- GETTING STARTED -->
 ## Getting Started
@@ -103,7 +102,7 @@ pip3 install sanic-security
 
 If you are planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use 
 the public secret and private secret), you will need to install the `cryptography` library. This can be installed explicitly, or 
-as a required extra in the `sanic-security` requirement.
+as an extra requirement.
 
 ```shell
 pip3 install sanic-security[crypto]
@@ -138,7 +137,7 @@ You can also use the update() method like on regular dictionaries.
 Any environment variables defined with the SANIC_SECURITY_ prefix will be applied to the config. For example, setting 
 SANIC_SECURITY_SECRET will be loaded by the application automatically and fed into the SECRET config variable.
 
-You can load environment variables with a different prefix via calling the `config.load_environment_variables("NEW_PREFIX_")` method.
+You can load environment variables with a different prefix via `config.load_environment_variables("NEW_PREFIX_")` method.
 
 * Default configuration values:
 
@@ -181,7 +180,7 @@ This account can be logged into and has complete authoritative access. Login cre
       app.run(host="127.0.0.1", port=8000)
   ```
   
-* Registration (With Two-step Verification)
+* Registration (With two-step account verification)
 
 Phone can be null or empty.
 
@@ -214,7 +213,7 @@ Verifies the client's account via two-step session code.
 
 | Key      | Value  |
 |----------|--------|
-| **code** | AJ8HGD |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/verify")
@@ -223,7 +222,7 @@ async def on_verify(request):
     return json("You have verified your account and may login!", two_step_session.json)
 ```
 
-* Login (With Two-factor Authentication)
+* Login (With two-factor authentication)
 
 Login credentials are retrieved via the Authorization header. Credentials are constructed by first combining the 
 username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string in base64 
@@ -256,7 +255,7 @@ Fulfills client authentication session's second factor requirement via two-step
 
 | Key      | Value  |
 |----------|--------|
-| **code** | BG5KLP |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/fulfill-2fa")
@@ -296,7 +295,7 @@ async def on_logout(request):
 
 * Authenticate
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
@@ -311,15 +310,15 @@ async def on_authenticate(request):
     return response
 ```
 
-* Requires Authentication (This method is not called directly and instead used as a decorator.)
+* Requires Authentication (This method is not called directly and instead used as a decorator)
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
 @requires_authentication
 async def on_authenticate(request):
-    authentication_session = request.ctx.authentication_session.json
+    authentication_session = request.ctx.authentication_session
     response = json(
         "You have been authenticated.",
         authentication_session.json,
@@ -329,6 +328,21 @@ async def on_authenticate(request):
     return response
 ```
 
+* Authentication Refresh Middleware
+
+If it's inconvenient to encode the refreshed session during authentication, it can also be done automatically via middleware.
+
+```python
+@app.on_response
+async def authentication_refresh_encoder(request, response):
+    try:
+        authentication_session = request.ctx.authentication_session
+        if authentication_session.is_refresh:
+            authentication_session.encode(response)
+    except AttributeError:
+        pass
+```
+
 ## Captcha
 
 A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
@@ -344,7 +358,7 @@ downloading a .ttf font and defining the file's path in the configuration.
 @app.get("api/security/captcha")
 async def on_captcha_img_request(request):
     captcha_session = await request_captcha(request)
-    response = captcha_session.get_image()  # Captcha: FV9NMQ
+    response = captcha_session.get_image()  # Captcha: 192731
     captcha_session.encode(response)
     return response
 ```
@@ -353,7 +367,7 @@ async def on_captcha_img_request(request):
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -362,11 +376,11 @@ async def on_captcha(request):
     return json("Captcha attempt successful!", captcha_session.json)
 ```
 
-* Requires Captcha (This method is not called directly and instead used as a decorator.)
+* Requires Captcha (This method is not called directly and instead used as a decorator)
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -388,9 +402,9 @@ Two-step verification should be integrated with other custom functionality. For
 ```python
 @app.post("api/security/two-step/request")
 async def on_two_step_request(request):
-    two_step_session = await request_two_step_verification(request)
+    two_step_session = await request_two_step_verification(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     response = json("Verification request successful!", two_step_session.json)
     two_step_session.encode(response)
@@ -402,9 +416,9 @@ async def on_two_step_request(request):
 ```python
 @app.post("api/security/two-step/resend")
 async def on_two_step_resend(request):
-    two_step_session = await TwoStepSession.decode(request)
+    two_step_session = await TwoStepSession.decode(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     return json("Verification code resend successful!", two_step_session.json)
 ```
@@ -413,7 +427,7 @@ async def on_two_step_resend(request):
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -423,11 +437,11 @@ async def on_two_step_verification(request):
     return response
 ```
 
-* Requires Two-step Verification (This method is not called directly and instead used as a decorator.)
+* Requires Two-step Verification (This method is not called directly and instead used as a decorator)
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -492,7 +506,7 @@ async def on_check_roles(request):
     return text("Account is authorized.")
 ```
 
-* Require Roles (This method is not called directly and instead used as a decorator.)
+* Require Roles (This method is not called directly and instead used as a decorator)
 
 ```python
 @app.post("api/security/roles")

{sanic_security-1.12.0 → sanic_security-1.12.1}/README.md

@@ -17,7 +17,7 @@
 <p align="center">
   <h3 align="center">Sanic Security</h3>
   <p align="center">
-   An effective, simple, and async security library for the Sanic framework.
+   An async security library for the Sanic framework.
   </p>
 </p>
 
@@ -46,7 +46,6 @@
 ## About The Project
 
 Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
-This library contains a variety of features including:
 
 * Login, registration, and authentication with refresh mechanisms
 * Two-factor authentication
@@ -54,7 +53,7 @@ This library contains a variety of features including:
 * Two-step verification
 * Role based authorization with wildcard permissions
 
-Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [click here for a comprehensive implementation guide](https://blog.na-stewart.com/entry?id=3).
+Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [here for an implementation guide](https://blog.na-stewart.com/entry?id=3).
 
 <!-- GETTING STARTED -->
 ## Getting Started
@@ -72,7 +71,7 @@ pip3 install sanic-security
 
 If you are planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use 
 the public secret and private secret), you will need to install the `cryptography` library. This can be installed explicitly, or 
-as a required extra in the `sanic-security` requirement.
+as an extra requirement.
 
 ```shell
 pip3 install sanic-security[crypto]
@@ -107,7 +106,7 @@ You can also use the update() method like on regular dictionaries.
 Any environment variables defined with the SANIC_SECURITY_ prefix will be applied to the config. For example, setting 
 SANIC_SECURITY_SECRET will be loaded by the application automatically and fed into the SECRET config variable.
 
-You can load environment variables with a different prefix via calling the `config.load_environment_variables("NEW_PREFIX_")` method.
+You can load environment variables with a different prefix via `config.load_environment_variables("NEW_PREFIX_")` method.
 
 * Default configuration values:
 
@@ -150,7 +149,7 @@ This account can be logged into and has complete authoritative access. Login cre
       app.run(host="127.0.0.1", port=8000)
   ```
   
-* Registration (With Two-step Verification)
+* Registration (With two-step account verification)
 
 Phone can be null or empty.
 
@@ -183,7 +182,7 @@ Verifies the client's account via two-step session code.
 
 | Key      | Value  |
 |----------|--------|
-| **code** | AJ8HGD |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/verify")
@@ -192,7 +191,7 @@ async def on_verify(request):
     return json("You have verified your account and may login!", two_step_session.json)
 ```
 
-* Login (With Two-factor Authentication)
+* Login (With two-factor authentication)
 
 Login credentials are retrieved via the Authorization header. Credentials are constructed by first combining the 
 username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string in base64 
@@ -225,7 +224,7 @@ Fulfills client authentication session's second factor requirement via two-step
 
 | Key      | Value  |
 |----------|--------|
-| **code** | BG5KLP |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/fulfill-2fa")
@@ -265,7 +264,7 @@ async def on_logout(request):
 
 * Authenticate
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
@@ -280,15 +279,15 @@ async def on_authenticate(request):
     return response
 ```
 
-* Requires Authentication (This method is not called directly and instead used as a decorator.)
+* Requires Authentication (This method is not called directly and instead used as a decorator)
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
 @requires_authentication
 async def on_authenticate(request):
-    authentication_session = request.ctx.authentication_session.json
+    authentication_session = request.ctx.authentication_session
     response = json(
         "You have been authenticated.",
         authentication_session.json,
@@ -298,6 +297,21 @@ async def on_authenticate(request):
     return response
 ```
 
+* Authentication Refresh Middleware
+
+If it's inconvenient to encode the refreshed session during authentication, it can also be done automatically via middleware.
+
+```python
+@app.on_response
+async def authentication_refresh_encoder(request, response):
+    try:
+        authentication_session = request.ctx.authentication_session
+        if authentication_session.is_refresh:
+            authentication_session.encode(response)
+    except AttributeError:
+        pass
+```
+
 ## Captcha
 
 A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
@@ -313,7 +327,7 @@ downloading a .ttf font and defining the file's path in the configuration.
 @app.get("api/security/captcha")
 async def on_captcha_img_request(request):
     captcha_session = await request_captcha(request)
-    response = captcha_session.get_image()  # Captcha: FV9NMQ
+    response = captcha_session.get_image()  # Captcha: 192731
     captcha_session.encode(response)
     return response
 ```
@@ -322,7 +336,7 @@ async def on_captcha_img_request(request):
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -331,11 +345,11 @@ async def on_captcha(request):
     return json("Captcha attempt successful!", captcha_session.json)
 ```
 
-* Requires Captcha (This method is not called directly and instead used as a decorator.)
+* Requires Captcha (This method is not called directly and instead used as a decorator)
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -357,9 +371,9 @@ Two-step verification should be integrated with other custom functionality. For
 ```python
 @app.post("api/security/two-step/request")
 async def on_two_step_request(request):
-    two_step_session = await request_two_step_verification(request)
+    two_step_session = await request_two_step_verification(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     response = json("Verification request successful!", two_step_session.json)
     two_step_session.encode(response)
@@ -371,9 +385,9 @@ async def on_two_step_request(request):
 ```python
 @app.post("api/security/two-step/resend")
 async def on_two_step_resend(request):
-    two_step_session = await TwoStepSession.decode(request)
+    two_step_session = await TwoStepSession.decode(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     return json("Verification code resend successful!", two_step_session.json)
 ```
@@ -382,7 +396,7 @@ async def on_two_step_resend(request):
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -392,11 +406,11 @@ async def on_two_step_verification(request):
     return response
 ```
 
-* Requires Two-step Verification (This method is not called directly and instead used as a decorator.)
+* Requires Two-step Verification (This method is not called directly and instead used as a decorator)
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -461,7 +475,7 @@ async def on_check_roles(request):
     return text("Account is authorized.")
 ```
 
-* Require Roles (This method is not called directly and instead used as a decorator.)
+* Require Roles (This method is not called directly and instead used as a decorator)
 
 ```python
 @app.post("api/security/roles")

{sanic_security-1.12.0 → sanic_security-1.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sanic-security"
-version = "1.12.0"
+version = "1.12.1"
 requires-python = ">=3.8"
 dependencies = [
     "tortoise-orm>=0.17.0",
@@ -14,7 +14,7 @@ dependencies = [
     "argon2-cffi>=20.1.0",
     "sanic>=21.3.0"
 ]
-description = "An effective, simple, and async security library for the Sanic framework."
+description = "An async security library for the Sanic framework."
 authors = [
   { name="Aidan Stewart", email="na.stewart365@gmail.com" },
 ]

{sanic_security-1.12.0 → sanic_security-1.12.1}/sanic_security/authentication.py

@@ -195,7 +195,7 @@ async def fulfill_second_factor(request: Request) -> AuthenticationSession:
     return authentication_session
 
 
-async def authenticate(request: Request) -> tuple[bool, AuthenticationSession]:
+async def authenticate(request: Request) -> AuthenticationSession:
     """
     Validates client's authentication session and account. New/Refreshed session automatically returned
     if expired during authentication, requires encoding.
@@ -214,6 +214,7 @@ async def authenticate(request: Request) -> tuple[bool, AuthenticationSession]:
         UnverifiedError
         DisabledError
         SecondFactorRequiredError
+        ExpiredError
     """
     authentication_session = await AuthenticationSession.decode(request)
     try:
@@ -245,6 +246,7 @@ def requires_authentication(arg=None):
         DeactivatedError
         UnverifiedError
         DisabledError
+        ExpiredError
     """
 
     def decorator(func):
@@ -272,7 +274,7 @@ def create_initial_admin_account(app: Sanic) -> None:
             role = await Role.filter(name="Head Admin").get()
         except DoesNotExist:
             role = await Role.create(
-                description="Has the ability to control any aspect of the API, assign sparingly.",
+                description="Has root abilities, assign sparingly.",
                 permissions="*:*",
                 name="Head Admin",
             )
@@ -283,9 +285,7 @@ def create_initial_admin_account(app: Sanic) -> None:
             await account.fetch_related("roles")
             if role not in account.roles:
                 await account.roles.add(role)
-                logger.warning(
-                    'The initial admin account role "Head Admin" was removed and has been reinstated.'
-                )
+                logger.warning("Initial admin account role has been reinstated.")
         except DoesNotExist:
             account = await Account.create(
                 username="Head-Admin",

{sanic_security-1.12.0 → sanic_security-1.12.1}/sanic_security/exceptions.py

@@ -128,7 +128,11 @@ class DeactivatedError(SessionError):
     Raised when session is deactivated.
     """
 
-    def __init__(self, message: str = "Session is deactivated.", code: int = 401):
+    def __init__(
+        self,
+        message: str = "Session has been deactivated or refreshed.",
+        code: int = 401,
+    ):
         super().__init__(message, code)
 
 

{sanic_security-1.12.0 → sanic_security-1.12.1}/sanic_security/models.py

@@ -524,13 +524,13 @@ class AuthenticationSession(Session):
     Used to authenticate and identify a client.
 
     Attributes:
-        requires_second_factor (bool): Determines if session requires a second factor.
         refresh_expiration_date (bool): Date and time the session can no longer be refreshed.
-        is_refresh (bool): Will only be true when instantiated during refresh of expired session.
+        requires_second_factor (bool): Determines if session requires a second factor.
+        is_refresh (bool): Will only be true once when instantiated during refresh of expired session.
     """
 
-    requires_second_factor: bool = fields.BooleanField(default=False)
     refresh_expiration_date: datetime.datetime = fields.DatetimeField(null=True)
+    requires_second_factor: bool = fields.BooleanField(default=False)
     is_refresh: bool = False
 
     def validate(self) -> None:
@@ -549,7 +549,7 @@ class AuthenticationSession(Session):
 
     async def refresh(self, request: Request):
         """
-        Seamlessly creates new session if within refresh date.
+        Refreshes session if expired and within refresh date.
 
         Raises:
             DeletedError

{sanic_security-1.12.0 → sanic_security-1.12.1}/sanic_security/test/server.py

@@ -19,7 +19,7 @@ from sanic_security.authorization import (
     check_roles,
 )
 from sanic_security.configuration import config as security_config
-from sanic_security.exceptions import SecurityError, CredentialsError
+from sanic_security.exceptions import SecurityError
 from sanic_security.models import Account, CaptchaSession, AuthenticationSession
 from sanic_security.utils import json
 from sanic_security.verification import (
@@ -110,7 +110,7 @@ async def on_login(request):
         )
         two_step_session.encode(response)
     else:
-        response = json("Login successful!", authentication_session.bearer.json)
+        response = json("Login successful!", authentication_session.json)
     authentication_session.encode(response)
     return response
 
@@ -148,7 +148,7 @@ async def on_logout(request):
     Logout of currently logged in account.
     """
     authentication_session = await logout(request)
-    response = json("Logout successful!", authentication_session.bearer.json)
+    response = json("Logout successful!", authentication_session.json)
     return response
 
 
@@ -170,11 +170,19 @@ async def on_authenticate(request):
             "refresh": authentication_session.is_refresh,
         },
     )
-    if authentication_session.is_refresh:
-        request.ctx.authentication_session.encode(response)
     return response
 
 
+@app.on_response
+async def authentication_refresh_encoder(request, response):
+    try:
+        authentication_session = request.ctx.authentication_session
+        if authentication_session.is_refresh:
+            authentication_session.encode(response)
+    except AttributeError:
+        pass
+
+
 @app.post("api/test/auth/expire")
 @requires_authentication
 async def on_authentication_expire(request):

{sanic_security-1.12.0 → sanic_security-1.12.1}/sanic_security/test/tests.py

@@ -306,6 +306,8 @@ class LoginTest(TestCase):
             "http://127.0.0.1:8000/api/test/auth",
         )
         assert authenticate_response.status_code == 200, authenticate_response.text
+        logout_response = self.client.post("http://127.0.0.1:8000/api/test/auth/logout")
+        assert logout_response.status_code == 200, logout_response.text
 
 
 class VerificationTest(TestCase):

{sanic_security-1.12.0 → sanic_security-1.12.1/sanic_security.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: sanic-security
-Version: 1.12.0
-Summary: An effective, simple, and async security library for the Sanic framework.
+Version: 1.12.1
+Summary: An async security library for the Sanic framework.
 Author-email: Aidan Stewart <na.stewart365@gmail.com>
 Project-URL: Documentation, https://security.na-stewart.com/
 Project-URL: Repository, https://github.com/na-stewart/sanic-security
@@ -48,7 +48,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 <p align="center">
   <h3 align="center">Sanic Security</h3>
   <p align="center">
-   An effective, simple, and async security library for the Sanic framework.
+   An async security library for the Sanic framework.
   </p>
 </p>
 
@@ -77,7 +77,6 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 ## About The Project
 
 Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
-This library contains a variety of features including:
 
 * Login, registration, and authentication with refresh mechanisms
 * Two-factor authentication
@@ -85,7 +84,7 @@ This library contains a variety of features including:
 * Two-step verification
 * Role based authorization with wildcard permissions
 
-Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [click here for a comprehensive implementation guide](https://blog.na-stewart.com/entry?id=3).
+Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [here for an implementation guide](https://blog.na-stewart.com/entry?id=3).
 
 <!-- GETTING STARTED -->
 ## Getting Started
@@ -103,7 +102,7 @@ pip3 install sanic-security
 
 If you are planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use 
 the public secret and private secret), you will need to install the `cryptography` library. This can be installed explicitly, or 
-as a required extra in the `sanic-security` requirement.
+as an extra requirement.
 
 ```shell
 pip3 install sanic-security[crypto]
@@ -138,7 +137,7 @@ You can also use the update() method like on regular dictionaries.
 Any environment variables defined with the SANIC_SECURITY_ prefix will be applied to the config. For example, setting 
 SANIC_SECURITY_SECRET will be loaded by the application automatically and fed into the SECRET config variable.
 
-You can load environment variables with a different prefix via calling the `config.load_environment_variables("NEW_PREFIX_")` method.
+You can load environment variables with a different prefix via `config.load_environment_variables("NEW_PREFIX_")` method.
 
 * Default configuration values:
 
@@ -181,7 +180,7 @@ This account can be logged into and has complete authoritative access. Login cre
       app.run(host="127.0.0.1", port=8000)
   ```
   
-* Registration (With Two-step Verification)
+* Registration (With two-step account verification)
 
 Phone can be null or empty.
 
@@ -214,7 +213,7 @@ Verifies the client's account via two-step session code.
 
 | Key      | Value  |
 |----------|--------|
-| **code** | AJ8HGD |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/verify")
@@ -223,7 +222,7 @@ async def on_verify(request):
     return json("You have verified your account and may login!", two_step_session.json)
 ```
 
-* Login (With Two-factor Authentication)
+* Login (With two-factor authentication)
 
 Login credentials are retrieved via the Authorization header. Credentials are constructed by first combining the 
 username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string in base64 
@@ -256,7 +255,7 @@ Fulfills client authentication session's second factor requirement via two-step
 
 | Key      | Value  |
 |----------|--------|
-| **code** | BG5KLP |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/fulfill-2fa")
@@ -296,7 +295,7 @@ async def on_logout(request):
 
 * Authenticate
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
@@ -311,15 +310,15 @@ async def on_authenticate(request):
     return response
 ```
 
-* Requires Authentication (This method is not called directly and instead used as a decorator.)
+* Requires Authentication (This method is not called directly and instead used as a decorator)
 
-New/Refreshed session automatically returned if expired during authentication, requires encoding.
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
 @requires_authentication
 async def on_authenticate(request):
-    authentication_session = request.ctx.authentication_session.json
+    authentication_session = request.ctx.authentication_session
     response = json(
         "You have been authenticated.",
         authentication_session.json,
@@ -329,6 +328,21 @@ async def on_authenticate(request):
     return response
 ```
 
+* Authentication Refresh Middleware
+
+If it's inconvenient to encode the refreshed session during authentication, it can also be done automatically via middleware.
+
+```python
+@app.on_response
+async def authentication_refresh_encoder(request, response):
+    try:
+        authentication_session = request.ctx.authentication_session
+        if authentication_session.is_refresh:
+            authentication_session.encode(response)
+    except AttributeError:
+        pass
+```
+
 ## Captcha
 
 A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
@@ -344,7 +358,7 @@ downloading a .ttf font and defining the file's path in the configuration.
 @app.get("api/security/captcha")
 async def on_captcha_img_request(request):
     captcha_session = await request_captcha(request)
-    response = captcha_session.get_image()  # Captcha: FV9NMQ
+    response = captcha_session.get_image()  # Captcha: 192731
     captcha_session.encode(response)
     return response
 ```
@@ -353,7 +367,7 @@ async def on_captcha_img_request(request):
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -362,11 +376,11 @@ async def on_captcha(request):
     return json("Captcha attempt successful!", captcha_session.json)
 ```
 
-* Requires Captcha (This method is not called directly and instead used as a decorator.)
+* Requires Captcha (This method is not called directly and instead used as a decorator)
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -388,9 +402,9 @@ Two-step verification should be integrated with other custom functionality. For
 ```python
 @app.post("api/security/two-step/request")
 async def on_two_step_request(request):
-    two_step_session = await request_two_step_verification(request)
+    two_step_session = await request_two_step_verification(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     response = json("Verification request successful!", two_step_session.json)
     two_step_session.encode(response)
@@ -402,9 +416,9 @@ async def on_two_step_request(request):
 ```python
 @app.post("api/security/two-step/resend")
 async def on_two_step_resend(request):
-    two_step_session = await TwoStepSession.decode(request)
+    two_step_session = await TwoStepSession.decode(request)  # Code = 197251
     await email_code(
-        two_step_session.bearer.email, two_step_session.code  # Code = 197251
+        two_step_session.bearer.email, two_step_session.code
     )  # Custom method for emailing verification code.
     return json("Verification code resend successful!", two_step_session.json)
 ```
@@ -413,7 +427,7 @@ async def on_two_step_resend(request):
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -423,11 +437,11 @@ async def on_two_step_verification(request):
     return response
 ```
 
-* Requires Two-step Verification (This method is not called directly and instead used as a decorator.)
+* Requires Two-step Verification (This method is not called directly and instead used as a decorator)
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -492,7 +506,7 @@ async def on_check_roles(request):
     return text("Account is authorized.")
 ```
 
-* Require Roles (This method is not called directly and instead used as a decorator.)
+* Require Roles (This method is not called directly and instead used as a decorator)
 
 ```python
 @app.post("api/security/roles")