sanic-security 1.13.3__tar.gz → 1.13.4__tar.gz

{sanic_security-1.13.3/sanic_security.egg-info → sanic_security-1.13.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sanic-security
-Version: 1.13.3
+Version: 1.13.4
 Summary: An async security library for the Sanic framework.
 Author-email: Aidan Stewart <me@na-stewart.com>
 Project-URL: Documentation, https://security.na-stewart.com/
@@ -20,6 +20,7 @@ Requires-Dist: captcha>=0.4
 Requires-Dist: pillow>=9.5.0
 Requires-Dist: argon2-cffi>=20.1.0
 Requires-Dist: sanic>=21.3.0
+Requires-Dist: secure>=1.0.1
 Provides-Extra: dev
 Requires-Dist: httpx; extra == "dev"
 Requires-Dist: black; extra == "dev"
@@ -63,7 +64,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
   * [Configuration](#configuration)
 * [Usage](#usage)
     * [Authentication](#authentication)
-    * [Captcha](#captcha)
+    * [CAPTCHA](#captcha)
     * [Two-step Verification](#two-step-verification)
     * [Authorization](#authorization)
     * [Testing](#testing)
@@ -76,21 +77,22 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
+Sanic Security is an authentication, authorization, and verification library designed for use with the 
+[Sanic](https://github.com/huge-success/sanic) framework.
 
 * Login, registration, and authentication with refresh mechanisms
 * Role based authorization with wildcard permissions
+* Image & audio CAPTCHA
 * Two-factor authentication
 * Two-step verification
-* Logging & Auditing
-* Captcha
+* Logging & auditing
 
 Visit [security.na-stewart.com](https://security.na-stewart.com) for documentation.
 
 <!-- GETTING STARTED -->
 ## Getting Started
 
-In order to get started, please install [Pip](https://pypi.org/).
+In order to get started, please install [PyPI](https://pypi.org/).
 
 ### Installation
 
@@ -109,14 +111,9 @@ as an extra requirement.
 pip3 install sanic-security[crypto]
 ````
 
-* For developers, fork Sanic Security and install development dependencies.
-```shell
-pip3 install -e ".[dev]"
-````
-
 * Update sanic-security if already installed.
 ```shell
-pip3 install --upgrade sanic-security
+pip3 install sanic-security --upgrade
 ```
 
 ### Configuration
@@ -154,7 +151,8 @@ You can load environment variables with a different prefix via `config.load_envi
 | **SESSION_PREFIX**                    | tkn                          | Prefix attached to the beginning of session cookies.                                                                             |
 | **MAX_CHALLENGE_ATTEMPTS**            | 5                            | The maximum amount of session challenge attempts allowed.                                                                        |
 | **CAPTCHA_SESSION_EXPIRATION**        | 60                           | The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.                         |
-| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation.                                                                     |
+| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation. Several fonts can be used by separating them via comma.             |
+| **CAPTCHA_VOICE**                     | captcha-voice/               | The directory of the voice library being used for audio captcha generation.                                                      |
 | **TWO_STEP_SESSION_EXPIRATION**       | 200                          | The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.                        |
 | **AUTHENTICATION_SESSION_EXPIRATION** | 86400                        | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                  |
 | **AUTHENTICATION_REFRESH_EXPIRATION** | 604800                       | The amount of seconds till authentication refresh expiration. Setting to 0 will disable refresh mechanism.                       |
@@ -319,16 +317,40 @@ async def on_authenticate(request):
     return response
 ```
 
-## Captcha
+## CAPTCHA
+
+Protects against spam and malicious activities by ensuring that only real humans can complete certain actions, like 
+submitting a form or creating an account.
 
-A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
-downloading a .ttf font and defining the file's path in the configuration.
+* Fonts
+
+A font for captcha challenges is included in the repository. You can set a custom font by downloading a .ttf file and 
+specifying its path in the configuration.
 
 [1001 Free Fonts](https://www.1001fonts.com/)
 
-[Recommended Font](https://www.1001fonts.com/source-sans-pro-font.html)
+* Voice Library
+
+A voice library for captcha challenges is included in the repository. You can generate your own using `espeak` and 
+`ffmpeg`, then specify the library's directory in the configuration.
 
-* Request Captcha
+```bash
+# Set the language code
+export ESLANG=en
+
+# Create a directory for the specified language code
+mkdir "$ESLANG"
+
+# Loop through each character (A-Z, 0-9) and create a directory for each
+for i in {A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,0,1,2,3,4,5,6,7,8,9}; do
+    mkdir "$ESLANG/$i"
+    espeak -a 150 -s 100 -p 15 -v "$ESLANG" "$i" -w "$ESLANG/$i/orig_default.wav"
+    ffmpeg -i "$ESLANG/$i/orig_default.wav" -ar 8000 -ac 1 -acodec pcm_u8 "$ESLANG/$i/default.wav"
+    rm "$ESLANG/$i/orig_default.wav"
+done
+```
+
+* Request CAPTCHA
 
 ```python
 @app.get("api/security/captcha")
@@ -339,7 +361,16 @@ async def on_captcha_img_request(request):
     return response
 ```
 
-* Captcha
+* Request CAPTCHA Audio
+
+```python
+@app.get("api/security/captcha/audio")
+async def on_captcha_audio_request(request):
+    captcha_session = await CaptchaSession.decode(request)
+    return captcha_session.get_audio()  # Captcha: LJ0F3U
+```
+
+* Attempt CAPTCHA
 
 | Key         | Value  |
 |-------------|--------|
@@ -352,7 +383,7 @@ 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  |
 |-------------|--------|
@@ -367,7 +398,7 @@ async def on_captcha(request):
 
 ## Two-step Verification
 
-Two-step verification should be integrated with other custom functionality. For example, account verification during registration.
+Two-step verification should be integrated with other custom functionalities, such as account verification during registration.
 
 * Request Two-step Verification
 
@@ -399,7 +430,7 @@ async def on_two_step_resend(request):
     return json("Verification code resend successful!", two_step_session.json)
 ```
 
-* Two-step Verification
+* Attempt Two-step Verification
 
 | Key      | Value  |
 |----------|--------|
@@ -442,13 +473,14 @@ user's account; this simplifies common operations, such as adding a user, or cha
 
 Wildcard permissions support the concept of multiple levels or parts. For example, you could grant a user the permission
 `printer:query`, `printer:query,delete`, or `printer:*`.
+
 * Assign Role
 
 ```python
 await assign_role(
     "Chat Room Moderator",
     account,
-    "channels:view,delete, account:suspend,mute, voice:*",
+    "channels:view,delete, voice:*, account:suspend,mute",
     "Can read and delete messages in all chat rooms, suspend and mute accounts, and control voice chat.",
 )
 ```
@@ -497,7 +529,7 @@ async def on_check_roles(request):
 
 * Make sure the test Sanic instance (`test/server.py`) is running on your machine.
 
-* Run the unit test client (`test/tests.py`) for results.
+* Run the test client (`test/tests.py`) for results.
 
 ## Tortoise
 

{sanic_security-1.13.3 → sanic_security-1.13.4}/README.md

@@ -32,7 +32,7 @@
   * [Configuration](#configuration)
 * [Usage](#usage)
     * [Authentication](#authentication)
-    * [Captcha](#captcha)
+    * [CAPTCHA](#captcha)
     * [Two-step Verification](#two-step-verification)
     * [Authorization](#authorization)
     * [Testing](#testing)
@@ -45,21 +45,22 @@
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
+Sanic Security is an authentication, authorization, and verification library designed for use with the 
+[Sanic](https://github.com/huge-success/sanic) framework.
 
 * Login, registration, and authentication with refresh mechanisms
 * Role based authorization with wildcard permissions
+* Image & audio CAPTCHA
 * Two-factor authentication
 * Two-step verification
-* Logging & Auditing
-* Captcha
+* Logging & auditing
 
 Visit [security.na-stewart.com](https://security.na-stewart.com) for documentation.
 
 <!-- GETTING STARTED -->
 ## Getting Started
 
-In order to get started, please install [Pip](https://pypi.org/).
+In order to get started, please install [PyPI](https://pypi.org/).
 
 ### Installation
 
@@ -78,14 +79,9 @@ as an extra requirement.
 pip3 install sanic-security[crypto]
 ````
 
-* For developers, fork Sanic Security and install development dependencies.
-```shell
-pip3 install -e ".[dev]"
-````
-
 * Update sanic-security if already installed.
 ```shell
-pip3 install --upgrade sanic-security
+pip3 install sanic-security --upgrade
 ```
 
 ### Configuration
@@ -123,7 +119,8 @@ You can load environment variables with a different prefix via `config.load_envi
 | **SESSION_PREFIX**                    | tkn                          | Prefix attached to the beginning of session cookies.                                                                             |
 | **MAX_CHALLENGE_ATTEMPTS**            | 5                            | The maximum amount of session challenge attempts allowed.                                                                        |
 | **CAPTCHA_SESSION_EXPIRATION**        | 60                           | The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.                         |
-| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation.                                                                     |
+| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation. Several fonts can be used by separating them via comma.             |
+| **CAPTCHA_VOICE**                     | captcha-voice/               | The directory of the voice library being used for audio captcha generation.                                                      |
 | **TWO_STEP_SESSION_EXPIRATION**       | 200                          | The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.                        |
 | **AUTHENTICATION_SESSION_EXPIRATION** | 86400                        | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                  |
 | **AUTHENTICATION_REFRESH_EXPIRATION** | 604800                       | The amount of seconds till authentication refresh expiration. Setting to 0 will disable refresh mechanism.                       |
@@ -288,16 +285,40 @@ async def on_authenticate(request):
     return response
 ```
 
-## Captcha
+## CAPTCHA
+
+Protects against spam and malicious activities by ensuring that only real humans can complete certain actions, like 
+submitting a form or creating an account.
 
-A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
-downloading a .ttf font and defining the file's path in the configuration.
+* Fonts
+
+A font for captcha challenges is included in the repository. You can set a custom font by downloading a .ttf file and 
+specifying its path in the configuration.
 
 [1001 Free Fonts](https://www.1001fonts.com/)
 
-[Recommended Font](https://www.1001fonts.com/source-sans-pro-font.html)
+* Voice Library
+
+A voice library for captcha challenges is included in the repository. You can generate your own using `espeak` and 
+`ffmpeg`, then specify the library's directory in the configuration.
 
-* Request Captcha
+```bash
+# Set the language code
+export ESLANG=en
+
+# Create a directory for the specified language code
+mkdir "$ESLANG"
+
+# Loop through each character (A-Z, 0-9) and create a directory for each
+for i in {A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,0,1,2,3,4,5,6,7,8,9}; do
+    mkdir "$ESLANG/$i"
+    espeak -a 150 -s 100 -p 15 -v "$ESLANG" "$i" -w "$ESLANG/$i/orig_default.wav"
+    ffmpeg -i "$ESLANG/$i/orig_default.wav" -ar 8000 -ac 1 -acodec pcm_u8 "$ESLANG/$i/default.wav"
+    rm "$ESLANG/$i/orig_default.wav"
+done
+```
+
+* Request CAPTCHA
 
 ```python
 @app.get("api/security/captcha")
@@ -308,7 +329,16 @@ async def on_captcha_img_request(request):
     return response
 ```
 
-* Captcha
+* Request CAPTCHA Audio
+
+```python
+@app.get("api/security/captcha/audio")
+async def on_captcha_audio_request(request):
+    captcha_session = await CaptchaSession.decode(request)
+    return captcha_session.get_audio()  # Captcha: LJ0F3U
+```
+
+* Attempt CAPTCHA
 
 | Key         | Value  |
 |-------------|--------|
@@ -321,7 +351,7 @@ 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  |
 |-------------|--------|
@@ -336,7 +366,7 @@ async def on_captcha(request):
 
 ## Two-step Verification
 
-Two-step verification should be integrated with other custom functionality. For example, account verification during registration.
+Two-step verification should be integrated with other custom functionalities, such as account verification during registration.
 
 * Request Two-step Verification
 
@@ -368,7 +398,7 @@ async def on_two_step_resend(request):
     return json("Verification code resend successful!", two_step_session.json)
 ```
 
-* Two-step Verification
+* Attempt Two-step Verification
 
 | Key      | Value  |
 |----------|--------|
@@ -411,13 +441,14 @@ user's account; this simplifies common operations, such as adding a user, or cha
 
 Wildcard permissions support the concept of multiple levels or parts. For example, you could grant a user the permission
 `printer:query`, `printer:query,delete`, or `printer:*`.
+
 * Assign Role
 
 ```python
 await assign_role(
     "Chat Room Moderator",
     account,
-    "channels:view,delete, account:suspend,mute, voice:*",
+    "channels:view,delete, voice:*, account:suspend,mute",
     "Can read and delete messages in all chat rooms, suspend and mute accounts, and control voice chat.",
 )
 ```
@@ -466,7 +497,7 @@ async def on_check_roles(request):
 
 * Make sure the test Sanic instance (`test/server.py`) is running on your machine.
 
-* Run the unit test client (`test/tests.py`) for results.
+* Run the test client (`test/tests.py`) for results.
 
 ## Tortoise
 

{sanic_security-1.13.3 → sanic_security-1.13.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sanic-security"
-version = "1.13.3"
+version = "1.13.4"
 requires-python = ">=3.8"
 dependencies = [
     "tortoise-orm>=0.17.0",
@@ -12,7 +12,8 @@ dependencies = [
     "captcha>=0.4",
     "pillow>=9.5.0",
     "argon2-cffi>=20.1.0",
-    "sanic>=21.3.0"
+    "sanic>=21.3.0",
+    "secure>=1.0.1"
 ]
 description = "An async security library for the Sanic framework."
 authors = [

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/authentication.py

@@ -2,7 +2,6 @@ import functools
 import re
 import warnings
 
-from argon2 import PasswordHasher
 from argon2.exceptions import VerifyMismatchError
 from sanic import Sanic
 from sanic.log import logger
@@ -18,7 +17,7 @@ from sanic_security.exceptions import (
     AuditWarning,
 )
 from sanic_security.models import Account, AuthenticationSession, Role, TwoStepSession
-from sanic_security.utils import get_ip
+from sanic_security.utils import get_ip, password_hasher, secure_headers
 
 """
 Copyright (c) 2020-present Nicholas Aidan Stewart
@@ -42,8 +41,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
 
-password_hasher = PasswordHasher()
-
 
 async def register(
     request: Request, verified: bool = False, disabled: bool = False
@@ -193,8 +190,7 @@ async def fulfill_second_factor(request: Request) -> AuthenticationSession:
     authentication_session.requires_second_factor = False
     await authentication_session.save(update_fields=["requires_second_factor"])
     logger.info(
-        f"Client {get_ip(request)} has fulfilled authentication session {authentication_session.id} "
-        "second factor."
+        f"Client {get_ip(request)} has fulfilled authentication session {authentication_session.id} second factor."
     )
     return authentication_session
 
@@ -288,7 +284,7 @@ def validate_password(password: str) -> str:
 
 def initialize_security(app: Sanic, create_root=True) -> None:
     """
-    Audits configuration, creates root administrator account, and attaches refresh encoder middleware.
+    Audits configuration, creates root administrator account, and attaches response handler middleware.
 
     Args:
         app (Sanic): The main Sanic application instance.
@@ -296,7 +292,8 @@ def initialize_security(app: Sanic, create_root=True) -> None:
     """
 
     @app.on_response
-    async def refresh_encoder_middleware(request, response):
+    async def response_handler_middleware(request, response):
+        secure_headers.set_headers(response)
         if hasattr(request.ctx, "authentication_session"):
             authentication_session = request.ctx.authentication_session
             if authentication_session.is_refresh:

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/authorization.py

@@ -71,7 +71,7 @@ async def check_permissions(
             if fnmatch(required_permission, role_permission):
                 return authentication_session
     logger.warning(
-        f"Client {get_ip(request)} with account {authentication_session.bearer.id} attempted an unauthorized action. "
+        f"Client {get_ip(request)} with account {authentication_session.bearer.id} attempted an unauthorized action."
     )
     raise AuthorizationError("Insufficient permissions required for this action.")
 
@@ -123,14 +123,16 @@ async def assign_role(
     Args:
         name (str):  The name of the role associated with the account.
         account (Account): The account associated with the created role.
-        permissions (str):  The permissions of the role associated with the account. Permissions must be separated via comma and in wildcard format.
+        permissions (str):  The permissions of the role associated with the account. Permissions must be separated via ", " and in wildcard format.
         description (str):  The description of the role associated with the account.
     """
     try:
         role = await Role.filter(name=name).get()
     except DoesNotExist:
         role = await Role.create(
-            description=description, permissions=permissions, name=name
+            name=name,
+            description=description,
+            permissions=permissions,
         )
     await account.roles.add(role)
     return role

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/configuration.py

@@ -36,6 +36,7 @@ DEFAULT_CONFIG = {
     "MAX_CHALLENGE_ATTEMPTS": 5,
     "CAPTCHA_SESSION_EXPIRATION": 60,
     "CAPTCHA_FONT": "captcha-font.ttf",
+    "CAPTCHA_VOICE": "captcha-voice/",
     "TWO_STEP_SESSION_EXPIRATION": 300,
     "AUTHENTICATION_SESSION_EXPIRATION": 86400,
     "AUTHENTICATION_REFRESH_EXPIRATION": 604800,
@@ -62,6 +63,7 @@ class Config(dict):
         MAX_CHALLENGE_ATTEMPTS (str): The maximum amount of session challenge attempts allowed.
         CAPTCHA_SESSION_EXPIRATION (int): The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.
         CAPTCHA_FONT (str): The file path to the font being used for captcha generation.
+        CAPTCHA_VOICE (str): The directory of the voice library being used for audio captcha generation.
         TWO_STEP_SESSION_EXPIRATION (int):  The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.
         AUTHENTICATION_SESSION_EXPIRATION (int): The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.
         AUTHENTICATION_REFRESH_EXPIRATION (int): The amount of seconds till authentication session refresh expiration. Setting to 0 will disable refresh mechanism.
@@ -82,6 +84,7 @@ class Config(dict):
     MAX_CHALLENGE_ATTEMPTS: int
     CAPTCHA_SESSION_EXPIRATION: int
     CAPTCHA_FONT: str
+    CAPTCHA_VOICE: str
     TWO_STEP_SESSION_EXPIRATION: int
     AUTHENTICATION_SESSION_EXPIRATION: int
     AUTHENTICATION_REFRESH_EXPIRATION: int

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/models.py

@@ -1,11 +1,9 @@
 import base64
 import datetime
 import re
-from io import BytesIO
 from typing import Union
 
 import jwt
-from captcha.image import ImageCaptcha
 from jwt import DecodeError
 from sanic.request import Request
 from sanic.response import HTTPResponse, raw
@@ -15,7 +13,13 @@ from tortoise.validators import RegexValidator
 
 from sanic_security.configuration import config as security_config
 from sanic_security.exceptions import *
-from sanic_security.utils import get_ip, get_code, get_expiration_date
+from sanic_security.utils import (
+    get_ip,
+    get_code,
+    get_expiration_date,
+    image_generator,
+    audio_generator,
+)
 
 """
 Copyright (c) 2020-present Nicholas Aidan Stewart
@@ -68,7 +72,7 @@ class BaseModel(Model):
     @property
     def json(self) -> dict:
         """
-        A JSON serializable dict to be used in a HTTP request or response.
+        A JSON serializable dict to be used in an HTTP request or response.
 
         Example:
             Below is an example of this method returning a dict to be used for JSON serialization.
@@ -119,7 +123,7 @@ class Account(BaseModel):
     )
     phone: str = fields.CharField(
         unique=True,
-        max_length=14,
+        max_length=15,
         null=True,
         validators=[
             RegexValidator(r"^(\+\d{1,2}\s)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}$", re.I)
@@ -189,9 +193,8 @@ class Account(BaseModel):
             NotFoundError
         """
         try:
-            account = await Account.filter(email=email, deleted=False).get()
-            return account
-        except DoesNotExist:
+            return await Account.filter(email=email, deleted=False).get()
+        except (DoesNotExist, ValidationError):
             raise NotFoundError("Account with this email does not exist.")
 
     @staticmethod
@@ -209,8 +212,7 @@ class Account(BaseModel):
             NotFoundError
         """
         try:
-            account = await Account.filter(username=username, deleted=False).get()
-            return account
+            return await Account.filter(username=username, deleted=False).get()
         except (DoesNotExist, ValidationError):
             raise NotFoundError("Account with this username does not exist.")
 
@@ -230,7 +232,7 @@ class Account(BaseModel):
         """
         try:
             account = await Account.get_via_email(credential)
-        except (NotFoundError, ValidationError) as e:
+        except NotFoundError as e:
             if security_config.ALLOW_LOGIN_WITH_USERNAME:
                 account = await Account.get_via_username(credential)
             else:
@@ -281,9 +283,8 @@ class Account(BaseModel):
             NotFoundError
         """
         try:
-            account = await Account.filter(phone=phone, deleted=False).get()
-            return account
-        except DoesNotExist:
+            return await Account.filter(phone=phone, deleted=False).get()
+        except (DoesNotExist, ValidationError):
             raise NotFoundError("Account with this phone number does not exist.")
 
 
@@ -574,10 +575,21 @@ class CaptchaSession(VerificationSession):
         Returns:
             captcha_image
         """
-        image = ImageCaptcha(190, 90, fonts=[security_config.CAPTCHA_FONT])
-        with BytesIO() as output:
-            image.generate_image(self.code).save(output, format="JPEG")
-            return raw(output.getvalue(), content_type="image/jpeg")
+        return raw(
+            image_generator.generate(self.code, "jpeg").getvalue(),
+            content_type="image/jpeg",
+        )
+
+    def get_audio(self) -> HTTPResponse:
+        """
+        Retrieves captcha audio file.
+
+        Returns:
+            captcha_audio
+        """
+        return raw(
+            bytes(audio_generator.generate(self.code)), content_type="audio/mpeg"
+        )
 
     class Meta:
         table = "captcha_session"

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/test/server.py

@@ -195,9 +195,14 @@ async def on_captcha_request(request):
 async def on_captcha_image(request):
     """Request captcha image."""
     captcha_session = await CaptchaSession.decode(request)
-    response = captcha_session.get_image()
-    captcha_session.encode(response)
-    return response
+    return captcha_session.get_image()
+
+
+@app.get("api/test/capt/audio")
+async def on_captcha_audio(request):
+    """Request captcha audio."""
+    captcha_session = await CaptchaSession.decode(request)
+    return captcha_session.get_audio()
 
 
 @app.post("api/test/capt")

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security/utils.py

@@ -2,8 +2,14 @@ import datetime
 import random
 import string
 
+from argon2 import PasswordHasher
+from captcha.audio import AudioCaptcha
+from captcha.image import ImageCaptcha
 from sanic.request import Request
 from sanic.response import json as sanic_json, HTTPResponse
+from secure import Secure
+
+from sanic_security.configuration import config
 
 """
 Copyright (c) 2020-Present Nicholas Aidan Stewart
@@ -27,6 +33,13 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
 
+image_generator = ImageCaptcha(
+    190, 90, fonts=config.CAPTCHA_FONT.replace(" ", "").split(",")
+)
+audio_generator = AudioCaptcha(voicedir=config.CAPTCHA_VOICE)
+password_hasher = PasswordHasher()
+secure_headers = Secure.with_default_headers()
+
 
 def get_ip(request: Request) -> str:
     """

{sanic_security-1.13.3 → sanic_security-1.13.4/sanic_security.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sanic-security
-Version: 1.13.3
+Version: 1.13.4
 Summary: An async security library for the Sanic framework.
 Author-email: Aidan Stewart <me@na-stewart.com>
 Project-URL: Documentation, https://security.na-stewart.com/
@@ -20,6 +20,7 @@ Requires-Dist: captcha>=0.4
 Requires-Dist: pillow>=9.5.0
 Requires-Dist: argon2-cffi>=20.1.0
 Requires-Dist: sanic>=21.3.0
+Requires-Dist: secure>=1.0.1
 Provides-Extra: dev
 Requires-Dist: httpx; extra == "dev"
 Requires-Dist: black; extra == "dev"
@@ -63,7 +64,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
   * [Configuration](#configuration)
 * [Usage](#usage)
     * [Authentication](#authentication)
-    * [Captcha](#captcha)
+    * [CAPTCHA](#captcha)
     * [Two-step Verification](#two-step-verification)
     * [Authorization](#authorization)
     * [Testing](#testing)
@@ -76,21 +77,22 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
+Sanic Security is an authentication, authorization, and verification library designed for use with the 
+[Sanic](https://github.com/huge-success/sanic) framework.
 
 * Login, registration, and authentication with refresh mechanisms
 * Role based authorization with wildcard permissions
+* Image & audio CAPTCHA
 * Two-factor authentication
 * Two-step verification
-* Logging & Auditing
-* Captcha
+* Logging & auditing
 
 Visit [security.na-stewart.com](https://security.na-stewart.com) for documentation.
 
 <!-- GETTING STARTED -->
 ## Getting Started
 
-In order to get started, please install [Pip](https://pypi.org/).
+In order to get started, please install [PyPI](https://pypi.org/).
 
 ### Installation
 
@@ -109,14 +111,9 @@ as an extra requirement.
 pip3 install sanic-security[crypto]
 ````
 
-* For developers, fork Sanic Security and install development dependencies.
-```shell
-pip3 install -e ".[dev]"
-````
-
 * Update sanic-security if already installed.
 ```shell
-pip3 install --upgrade sanic-security
+pip3 install sanic-security --upgrade
 ```
 
 ### Configuration
@@ -154,7 +151,8 @@ You can load environment variables with a different prefix via `config.load_envi
 | **SESSION_PREFIX**                    | tkn                          | Prefix attached to the beginning of session cookies.                                                                             |
 | **MAX_CHALLENGE_ATTEMPTS**            | 5                            | The maximum amount of session challenge attempts allowed.                                                                        |
 | **CAPTCHA_SESSION_EXPIRATION**        | 60                           | The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.                         |
-| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation.                                                                     |
+| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation. Several fonts can be used by separating them via comma.             |
+| **CAPTCHA_VOICE**                     | captcha-voice/               | The directory of the voice library being used for audio captcha generation.                                                      |
 | **TWO_STEP_SESSION_EXPIRATION**       | 200                          | The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.                        |
 | **AUTHENTICATION_SESSION_EXPIRATION** | 86400                        | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                  |
 | **AUTHENTICATION_REFRESH_EXPIRATION** | 604800                       | The amount of seconds till authentication refresh expiration. Setting to 0 will disable refresh mechanism.                       |
@@ -319,16 +317,40 @@ async def on_authenticate(request):
     return response
 ```
 
-## Captcha
+## CAPTCHA
+
+Protects against spam and malicious activities by ensuring that only real humans can complete certain actions, like 
+submitting a form or creating an account.
 
-A pre-existing font for captcha challenges is included in the Sanic Security repository. You may set your own font by 
-downloading a .ttf font and defining the file's path in the configuration.
+* Fonts
+
+A font for captcha challenges is included in the repository. You can set a custom font by downloading a .ttf file and 
+specifying its path in the configuration.
 
 [1001 Free Fonts](https://www.1001fonts.com/)
 
-[Recommended Font](https://www.1001fonts.com/source-sans-pro-font.html)
+* Voice Library
+
+A voice library for captcha challenges is included in the repository. You can generate your own using `espeak` and 
+`ffmpeg`, then specify the library's directory in the configuration.
 
-* Request Captcha
+```bash
+# Set the language code
+export ESLANG=en
+
+# Create a directory for the specified language code
+mkdir "$ESLANG"
+
+# Loop through each character (A-Z, 0-9) and create a directory for each
+for i in {A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,0,1,2,3,4,5,6,7,8,9}; do
+    mkdir "$ESLANG/$i"
+    espeak -a 150 -s 100 -p 15 -v "$ESLANG" "$i" -w "$ESLANG/$i/orig_default.wav"
+    ffmpeg -i "$ESLANG/$i/orig_default.wav" -ar 8000 -ac 1 -acodec pcm_u8 "$ESLANG/$i/default.wav"
+    rm "$ESLANG/$i/orig_default.wav"
+done
+```
+
+* Request CAPTCHA
 
 ```python
 @app.get("api/security/captcha")
@@ -339,7 +361,16 @@ async def on_captcha_img_request(request):
     return response
 ```
 
-* Captcha
+* Request CAPTCHA Audio
+
+```python
+@app.get("api/security/captcha/audio")
+async def on_captcha_audio_request(request):
+    captcha_session = await CaptchaSession.decode(request)
+    return captcha_session.get_audio()  # Captcha: LJ0F3U
+```
+
+* Attempt CAPTCHA
 
 | Key         | Value  |
 |-------------|--------|
@@ -352,7 +383,7 @@ 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  |
 |-------------|--------|
@@ -367,7 +398,7 @@ async def on_captcha(request):
 
 ## Two-step Verification
 
-Two-step verification should be integrated with other custom functionality. For example, account verification during registration.
+Two-step verification should be integrated with other custom functionalities, such as account verification during registration.
 
 * Request Two-step Verification
 
@@ -399,7 +430,7 @@ async def on_two_step_resend(request):
     return json("Verification code resend successful!", two_step_session.json)
 ```
 
-* Two-step Verification
+* Attempt Two-step Verification
 
 | Key      | Value  |
 |----------|--------|
@@ -442,13 +473,14 @@ user's account; this simplifies common operations, such as adding a user, or cha
 
 Wildcard permissions support the concept of multiple levels or parts. For example, you could grant a user the permission
 `printer:query`, `printer:query,delete`, or `printer:*`.
+
 * Assign Role
 
 ```python
 await assign_role(
     "Chat Room Moderator",
     account,
-    "channels:view,delete, account:suspend,mute, voice:*",
+    "channels:view,delete, voice:*, account:suspend,mute",
     "Can read and delete messages in all chat rooms, suspend and mute accounts, and control voice chat.",
 )
 ```
@@ -497,7 +529,7 @@ async def on_check_roles(request):
 
 * Make sure the test Sanic instance (`test/server.py`) is running on your machine.
 
-* Run the unit test client (`test/tests.py`) for results.
+* Run the test client (`test/tests.py`) for results.
 
 ## Tortoise
 

{sanic_security-1.13.3 → sanic_security-1.13.4}/sanic_security.egg-info/requires.txt

@@ -4,6 +4,7 @@ captcha>=0.4
 pillow>=9.5.0
 argon2-cffi>=20.1.0
 sanic>=21.3.0
+secure>=1.0.1
 
 [crypto]
 cryptography>=3.3.1