sanic-security 1.15.3__py3-none-any.whl → 1.16.1__py3-none-any.whl

sanic_security/authentication.py

@@ -2,13 +2,13 @@ import functools
 import re
 import warnings
 
-from argon2.exceptions import VerifyMismatchError
+from argon2.exceptions import VerificationError, InvalidHashError
 from sanic import Sanic
 from sanic.log import logger
 from sanic.request import Request
 from tortoise.exceptions import DoesNotExist, ValidationError, IntegrityError
 
-from sanic_security.configuration import config as security_config, DEFAULT_CONFIG
+from sanic_security.configuration import config, DEFAULT_CONFIG
 from sanic_security.exceptions import (
     CredentialsError,
     DeactivatedError,
@@ -74,7 +74,7 @@ async def register(
         return account
     except ValidationError as e:
         raise CredentialsError(
-            "Username must be 3-32 characters long and can only include _ or -."
+            "Username must be 3-32 characters long."
             if "username" in e.args[0]
             else "Invalid email or phone number."
         )
@@ -128,7 +128,7 @@ async def login(
             f"Client {get_ip(request)} has logged in with authentication session {authentication_session.id}."
         )
         return authentication_session
-    except VerifyMismatchError:
+    except (VerificationError, InvalidHashError):
         logger.warning(
             f"Client {get_ip(request)} has failed to log into account {account.id}."
         )
@@ -283,7 +283,7 @@ def validate_password(password: str) -> str:
     return password
 
 
-def initialize_security(app: Sanic, create_root=True) -> None:
+def initialize_security(app: Sanic, create_root: bool = True) -> None:
     """
     Audits configuration, creates root administrator account, and attaches refresh encoder middleware.
 
@@ -294,30 +294,26 @@ def initialize_security(app: Sanic, create_root=True) -> None:
 
     @app.listener("before_server_start")
     async def audit_configuration(app, loop):
-        if security_config.SECRET == DEFAULT_CONFIG["SECRET"]:
+        if config.SECRET == DEFAULT_CONFIG["SECRET"]:
             warnings.warn("Secret should be changed from default.", AuditWarning, 2)
-        if not security_config.SESSION_HTTPONLY:
+        if not config.SESSION_HTTPONLY:
             warnings.warn("HttpOnly should be enabled.", AuditWarning, 2)
-        if not security_config.SESSION_SECURE:
+        if not config.SESSION_SECURE:
             warnings.warn("Secure should be enabled.", AuditWarning, 2)
-        if (
-            not security_config.SESSION_SAMESITE
-            or security_config.SESSION_SAMESITE.lower() == "none"
-        ):
+        if not config.SESSION_SAMESITE or config.SESSION_SAMESITE.lower() == "none":
             warnings.warn("SameSite should not be none.", AuditWarning, 2)
-        if not security_config.SESSION_DOMAIN:
+        if not config.SESSION_DOMAIN:
             warnings.warn("Domain should not be none.", AuditWarning, 2)
         if (
             create_root
-            and security_config.INITIAL_ADMIN_EMAIL
-            == DEFAULT_CONFIG["INITIAL_ADMIN_EMAIL"]
+            and config.INITIAL_ADMIN_EMAIL == DEFAULT_CONFIG["INITIAL_ADMIN_EMAIL"]
         ):
             warnings.warn(
                 "Initial admin email should be changed from default.", AuditWarning, 2
             )
         if (
             create_root
-            and security_config.INITIAL_ADMIN_PASSWORD
+            and config.INITIAL_ADMIN_PASSWORD
             == DEFAULT_CONFIG["INITIAL_ADMIN_PASSWORD"]
         ):
             warnings.warn(
@@ -335,13 +331,11 @@ def initialize_security(app: Sanic, create_root=True) -> None:
         except DoesNotExist:
             role = await Role.create(
                 description="Has administrator abilities, assign sparingly.",
-                permissions="*:*",
+                permissions=["*:*"],
                 name="Root",
             )
         try:
-            account = await Account.filter(
-                email=security_config.INITIAL_ADMIN_EMAIL
-            ).get()
+            account = await Account.filter(email=config.INITIAL_ADMIN_EMAIL).get()
             await account.fetch_related("roles")
             if role not in account.roles:
                 await account.roles.add(role)
@@ -349,8 +343,8 @@ def initialize_security(app: Sanic, create_root=True) -> None:
         except DoesNotExist:
             account = await Account.create(
                 username="Root",
-                email=security_config.INITIAL_ADMIN_EMAIL,
-                password=password_hasher.hash(security_config.INITIAL_ADMIN_PASSWORD),
+                email=config.INITIAL_ADMIN_EMAIL,
+                password=password_hasher.hash(config.INITIAL_ADMIN_PASSWORD),
                 verified=True,
             )
             await account.roles.add(role)

sanic_security/authorization.py

@@ -1,5 +1,4 @@
 import functools
-from fnmatch import fnmatch
 
 from sanic.log import logger
 from sanic.request import Request
@@ -65,18 +64,39 @@ async def check_permissions(
         raise AnonymousError
     roles = await authentication_session.bearer.roles.filter(deleted=False).all()
     for role in roles:
-        for required_permission, role_permission in zip(
-            required_permissions, role.permissions.split(", ")
-        ):
-            if fnmatch(required_permission, role_permission):
-                request.ctx.session = authentication_session
-                return authentication_session
+        for role_permission in role.permissions:
+            for required_permission in required_permissions:
+                if check_wildcard(role_permission, required_permission):
+                    request.ctx.session = authentication_session
+                    return authentication_session
     logger.warning(
         f"Client {get_ip(request)} with account {authentication_session.bearer.id} attempted an unauthorized action."
     )
     raise AuthorizationError("Insufficient permissions required for this action.")
 
 
+def check_wildcard(wildcard: str, pattern: str):
+    """
+    Evaluates if the input matches the pattern considering wildcards (`*`) and comma-separated options in the pattern.
+
+    Args:
+        wildcard (str): A wildcard string (e.g., "a:b:c").
+        pattern (str): A wildcard pattern optional (`*`) or comma-separated values to match against (e.g., "a:b,c:*").
+
+    Returns:
+        is_match
+    """
+    wildcard_parts = [set(part.split(",")) for part in wildcard.split(":")]
+    pattern_parts = [set(part.split(",")) for part in pattern.split(":")]
+    for i, pattern_part in enumerate(pattern_parts):
+        if i >= len(wildcard_parts):
+            return False
+        wildcard_part = wildcard_parts[i]
+        if "*" not in wildcard_part and not wildcard_part.issuperset(pattern_part):
+            return False
+    return all("*" in part for part in wildcard_parts[len(pattern_parts) :])
+
+
 async def check_roles(request: Request, *required_roles: str) -> AuthenticationSession:
     """
     Authenticates client and determines if the account has sufficient roles for an action.
@@ -105,19 +125,25 @@ async def check_roles(request: Request, *required_roles: str) -> AuthenticationS
             f"Client {get_ip(request)} attempted an unauthorized action anonymously."
         )
         raise AnonymousError
-    roles = await authentication_session.bearer.roles.filter(deleted=False).all()
-    for role in roles:
-        if role.name in required_roles:
-            request.ctx.session = authentication_session
-            return authentication_session
+    if set(required_roles) & {
+        role.name
+        for role in await authentication_session.bearer.roles.filter(
+            deleted=False
+        ).all()
+    }:
+        request.ctx.session = authentication_session
+        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 roles required for this action.")
+    raise AuthorizationError("Insufficient roles required for this action")
 
 
 async def assign_role(
-    name: str, account: Account, permissions: str = None, description: str = None
+    name: str,
+    account: Account,
+    description: str = None,
+    *permissions: str,
 ) -> Role:
     """
     Easy account role assignment. Role being assigned to an account will be created if it doesn't exist.
@@ -125,8 +151,8 @@ 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 ", " and in wildcard format.
         description (str):  The description of the role associated with the account.
+        *permissions (Tuple[str, ...]): The permissions of the role associated with the account, must be in wildcard format.
     """
     try:
         role = await Role.filter(name=name).get()
@@ -140,7 +166,7 @@ async def assign_role(
     return role
 
 
-def require_permissions(*required_permissions: str):
+def requires_permission(*required_permissions: str):
     """
     Authenticates client and determines if the account has sufficient permissions for an action.
 
@@ -178,7 +204,7 @@ def require_permissions(*required_permissions: str):
     return decorator
 
 
-def require_roles(*required_roles: str):
+def requires_role(*required_roles: str):
     """
     Authenticates client and determines if the account has sufficient roles for an action.
 

sanic_security/configuration.py

@@ -27,6 +27,9 @@ SOFTWARE.
 DEFAULT_CONFIG = {
     "SECRET": "This is a big secret. Shhhhh",
     "PUBLIC_SECRET": None,
+    "OAUTH_CLIENT": None,
+    "OAUTH_SECRET": None,
+    "OAUTH_REDIRECT": None,
     "SESSION_SAMESITE": "Strict",
     "SESSION_SECURE": True,
     "SESSION_HTTPONLY": True,
@@ -54,6 +57,9 @@ class Config(dict):
     Attributes:
         SECRET (str): The secret used by the hashing algorithm for generating and signing JWTs. This should be a string unique to your application. Keep it safe.
         PUBLIC_SECRET (str): The secret used for verifying and decoding JWTs and can be publicly shared. This should be a string unique to your application.
+        OAUTH_CLIENT (str): The client ID provided by the OAuth provider, this is used to identify the application making the OAuth request.
+        OAUTH_SECRET (str): The client secret provided by the OAuth provider, this is used in conjunction with the client ID to authenticate the application.
+        OAUTH_REDIRECT (str): The redirect URI registered with the OAuth provider, This is the URI where the user will be redirected after a successful authentication.
         SESSION_SAMESITE (str): The SameSite attribute of session cookies.
         SESSION_SECURE (bool): The Secure attribute of session cookies.
         SESSION_HTTPONLY (bool): The HttpOnly attribute of session cookies. HIGHLY recommended that you do not turn this off, unless you know what you are doing.
@@ -75,6 +81,9 @@ class Config(dict):
 
     SECRET: str
     PUBLIC_SECRET: str
+    OAUTH_CLIENT: str
+    OAUTH_SECRET: str
+    OAUTH_REDIRECT: str
     SESSION_SAMESITE: str
     SESSION_SECURE: bool
     SESSION_HTTPONLY: bool

sanic_security/exceptions.py

@@ -119,7 +119,9 @@ class JWTDecodeError(SessionError):
     Raised when client JWT is invalid.
     """
 
-    def __init__(self, message, code=400):
+    def __init__(
+        self, message="Session token invalid, not provided, or expired.", code=400
+    ):
         super().__init__(message, code)
 
 
@@ -141,8 +143,8 @@ class ExpiredError(SessionError):
     Raised when session has expired.
     """
 
-    def __init__(self):
-        super().__init__("Session has expired.")
+    def __init__(self, message="Session has expired."):
+        super().__init__(message)
 
 
 class SecondFactorRequiredError(SessionError):

sanic_security/models.py

@@ -8,12 +8,12 @@ from typing import Union
 import jwt
 from jwt import DecodeError
 from sanic.request import Request
-from sanic.response import HTTPResponse, raw
+from sanic.response import HTTPResponse
 from tortoise import fields, Model
 from tortoise.exceptions import DoesNotExist, ValidationError
 from tortoise.validators import RegexValidator
 
-from sanic_security.configuration import config as security_config
+from sanic_security.configuration import config
 from sanic_security.exceptions import *
 from sanic_security.utils import (
     get_ip,
@@ -108,16 +108,16 @@ class Account(BaseModel):
         username (str): Public identifier.
         email (str): Private identifier and can be used for verification.
         phone (str): Mobile phone number with country code included and can be used for verification. Can be null or empty.
-        password (str): Password of account for user protection. must be hashed via Argon2.
+        password (str): Password of account for user protection, must be hashed via Argon2.
+        oauth_id (str): Identifier associated with an OAuth 2.0 authorization flow.
         disabled (bool): Renders the account unusable but available.
         verified (bool): Renders the account unusable until verified via two-step verification or other method.
         roles (ManyToManyRelation[Role]): Roles associated with this account.
     """
 
     username: str = fields.CharField(
-        unique=security_config.ALLOW_LOGIN_WITH_USERNAME,
+        unique=config.ALLOW_LOGIN_WITH_USERNAME,
         max_length=32,
-        validators=[RegexValidator(r"^[A-Za-z0-9_-]*$", re.I)],
     )
     email: str = fields.CharField(
         unique=True,
@@ -135,6 +135,7 @@ class Account(BaseModel):
         ],
     )
     password: str = fields.CharField(max_length=255)
+    oauth_id: str = fields.CharField(unique=True, null=True, max_length=255)
     disabled: bool = fields.BooleanField(default=False)
     verified: bool = fields.BooleanField(default=False)
     roles: fields.ManyToManyRelation["Role"] = fields.ManyToManyField(
@@ -238,7 +239,7 @@ class Account(BaseModel):
         try:
             account = await Account.get_via_email(credential)
         except NotFoundError as e:
-            if security_config.ALLOW_LOGIN_WITH_USERNAME:
+            if config.ALLOW_LOGIN_WITH_USERNAME:
                 account = await Account.get_via_username(credential)
             else:
                 raise e
@@ -350,9 +351,6 @@ class Session(BaseModel):
         Args:
             response (HTTPResponse): Sanic response used to store JWT into a cookie on the client.
         """
-        cookie = (
-            f"{security_config.SESSION_PREFIX}_{self.__class__.__name__.lower()[:7]}"
-        )
         encoded_session = jwt.encode(
             {
                 "id": self.id,
@@ -361,22 +359,18 @@ class Session(BaseModel):
                 "bearer": self.bearer.id if isinstance(self.bearer, Account) else None,
                 "ip": self.ip,
             },
-            security_config.SECRET,
-            security_config.SESSION_ENCODING_ALGORITHM,
+            config.SECRET,
+            config.SESSION_ENCODING_ALGORITHM,
         )
         response.cookies.add_cookie(
-            cookie,
+            f"{config.SESSION_PREFIX}_{self.__class__.__name__[:7].lower()}",
             str(encoded_session),
-            httponly=security_config.SESSION_HTTPONLY,
-            samesite=security_config.SESSION_SAMESITE,
-            secure=security_config.SESSION_SECURE,
-            domain=security_config.SESSION_DOMAIN,
-            expires=(
-                self.refresh_expiration_date
-                if hasattr(self, "refresh_expiration_date")
-                and self.refresh_expiration_date
-                else self.expiration_date
-            ),
+            httponly=config.SESSION_HTTPONLY,
+            samesite=config.SESSION_SAMESITE,
+            secure=config.SESSION_SECURE,
+            domain=config.SESSION_DOMAIN,
+            expires=getattr(self, "refresh_expiration_date", None)
+            or self.expiration_date,
         )
 
     @property
@@ -405,7 +399,7 @@ class Session(BaseModel):
         cls,
         request: Request,
         account: Account,
-        **kwargs: Union[int, str, bool, float, list, dict],
+        **kwargs: dict[str, Union[int, str, bool, float, list, dict]],
     ):
         """
         Creates session with pre-set values.
@@ -413,7 +407,7 @@ class Session(BaseModel):
         Args:
             request (Request): Sanic request parameter.
             account (Account): Account being associated to the session.
-            **kwargs (dict[str, Union[int, str, bool, float, list, dict]]): Extra arguments applied during session creation.
+            **kwargs (Union[int, str, bool, float, list, dict]): Extra arguments applied during session creation.
 
         Returns:
             session
@@ -454,16 +448,16 @@ class Session(BaseModel):
             JWTDecodeError
         """
         cookie = request.cookies.get(
-            f"{security_config.SESSION_PREFIX}_{cls.__name__.lower()[:7]}"
+            f"{config.SESSION_PREFIX}_{cls.__name__[:7].lower()}"
         )
         try:
             if not cookie:
-                raise JWTDecodeError("Session token not provided or expired.", 401)
+                raise JWTDecodeError
             else:
                 return jwt.decode(
                     cookie,
-                    security_config.PUBLIC_SECRET or security_config.SECRET,
-                    security_config.SESSION_ENCODING_ALGORITHM,
+                    config.PUBLIC_SECRET or config.SECRET,
+                    config.SESSION_ENCODING_ALGORITHM,
                 )
         except DecodeError as e:
             raise JWTDecodeError(str(e))
@@ -521,7 +515,7 @@ class VerificationSession(Session):
         """
         if not code or self.code != code.upper():
             self.attempts += 1
-            if self.attempts < security_config.MAX_CHALLENGE_ATTEMPTS:
+            if self.attempts < config.MAX_CHALLENGE_ATTEMPTS:
                 await self.save(update_fields=["attempts"])
                 raise ChallengeError(
                     "Your code does not match verification session code."
@@ -532,7 +526,12 @@ class VerificationSession(Session):
             await self.deactivate()
 
     @classmethod
-    async def new(cls, request: Request, account: Account, **kwargs):
+    async def new(
+        cls,
+        request: Request,
+        account: Account,
+        **kwargs: Union[int, str, bool, float, list, dict],
+    ):
         raise NotImplementedError
 
     class Meta:
@@ -543,14 +542,17 @@ class TwoStepSession(VerificationSession):
     """Validates client using a code sent via email or text."""
 
     @classmethod
-    async def new(cls, request: Request, account: Account, **kwargs):
+    async def new(
+        cls,
+        request: Request,
+        account: Account,
+        **kwargs: Union[int, str, bool, float, list, dict],
+    ):
         return await cls.create(
             **kwargs,
             ip=get_ip(request),
             bearer=account,
-            expiration_date=get_expiration_date(
-                security_config.TWO_STEP_SESSION_EXPIRATION
-            ),
+            expiration_date=get_expiration_date(config.TWO_STEP_SESSION_EXPIRATION),
             code=get_code(True),
         )
 
@@ -562,38 +564,35 @@ class CaptchaSession(VerificationSession):
     """Validates client with a captcha challenge via image or audio."""
 
     @classmethod
-    async def new(cls, request: Request, **kwargs):
+    async def new(
+        cls,
+        request: Request,
+        **kwargs: Union[int, str, bool, float, list, dict],
+    ):
         return await cls.create(
             **kwargs,
             ip=get_ip(request),
             code=get_code(),
-            expiration_date=get_expiration_date(
-                security_config.CAPTCHA_SESSION_EXPIRATION
-            ),
+            expiration_date=get_expiration_date(config.CAPTCHA_SESSION_EXPIRATION),
         )
 
-    def get_image(self) -> HTTPResponse:
+    def get_image(self) -> bytes:
         """
         Retrieves captcha image data.
 
         Returns:
             captcha_image
         """
-        return raw(
-            image_generator.generate(self.code, "jpeg").getvalue(),
-            content_type="image/jpeg",
-        )
+        return image_generator.generate(self.code, "jpeg").getvalue()
 
-    def get_audio(self) -> HTTPResponse:
+    def get_audio(self) -> bytes:
         """
         Retrieves captcha audio data.
 
         Returns:
             captcha_audio
         """
-        return raw(
-            bytes(audio_generator.generate(self.code)), content_type="audio/mpeg"
-        )
+        return bytes(audio_generator.generate(self.code))
 
     class Meta:
         table = "captcha_session"
@@ -652,17 +651,21 @@ class AuthenticationSession(Session):
 
     @classmethod
     async def new(
-        cls, request: Request, account: Account = None, is_refresh=False, **kwargs
+        cls,
+        request: Request,
+        account: Account = None,
+        is_refresh=False,
+        **kwargs: Union[int, str, bool, float, list, dict],
     ):
         authentication_session = await cls.create(
             **kwargs,
             bearer=account,
             ip=get_ip(request),
             expiration_date=get_expiration_date(
-                security_config.AUTHENTICATION_SESSION_EXPIRATION
+                config.AUTHENTICATION_SESSION_EXPIRATION
             ),
             refresh_expiration_date=get_expiration_date(
-                security_config.AUTHENTICATION_REFRESH_EXPIRATION
+                config.AUTHENTICATION_REFRESH_EXPIRATION
             ),
         )
         authentication_session.is_refresh = is_refresh
@@ -679,12 +682,12 @@ class Role(BaseModel):
     Attributes:
         name (str): Name of the role.
         description (str): Description of the role.
-        permissions (str): Permissions of the role. Must be separated via comma & space and in wildcard format (printer:query, dashboard:info,delete).
+        permissions (list[str]): Permissions of the role. Must in wildcard format (printer:query, dashboard:info,delete).
     """
 
     name: str = fields.CharField(unique=True, max_length=255)
     description: str = fields.CharField(max_length=255, null=True)
-    permissions: str = fields.CharField(max_length=255, null=True)
+    permissions: list[str] = fields.JSONField(null=True)
 
     def validate(self) -> None:
         raise NotImplementedError