sanic-security 1.11.7__py3-none-any.whl → 1.16.7__py3-none-any.whl

sanic_security/authorization.py

@@ -1,31 +1,34 @@
 import functools
-import logging
-from fnmatch import fnmatch
 
+from sanic.log import logger
 from sanic.request import Request
 from tortoise.exceptions import DoesNotExist
 
 from sanic_security.authentication import authenticate
-from sanic_security.exceptions import AuthorizationError
+from sanic_security.exceptions import AuthorizationError, AnonymousError
 from sanic_security.models import Role, Account, AuthenticationSession
 from sanic_security.utils import get_ip
 
 """
-An effective, simple, and async security library for the Sanic framework.
-Copyright (C) 2020-present Aidan Stewart
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published
-by the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+Copyright (c) 2020-present Nicholas Aidan Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 """
 
 
@@ -51,19 +54,48 @@ async def check_permissions(
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
     authentication_session = await authenticate(request)
+    if authentication_session.anonymous:
+        logger.warning(
+            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:
-        for required_permission, role_permission in zip(
-            required_permissions, role.permissions.split(", ")
-        ):
-            if fnmatch(required_permission, role_permission):
-                return authentication_session
-    logging.warning(f"Client ({get_ip(request)}) has insufficient permissions.")
+        for role_permission in role.permissions:
+            for required_permission in required_permissions:
+                if check_wildcard(role_permission, required_permission):
+                    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 wildcard matches 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.
@@ -84,17 +116,55 @@ async def check_roles(request: Request, *required_roles: str) -> AuthenticationS
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
     authentication_session = await authenticate(request)
-    roles = await authentication_session.bearer.roles.filter(deleted=False).all()
-    for role in roles:
-        if role.name in required_roles:
-            return authentication_session
-    logging.warning(f"Client ({get_ip(request)}) has insufficient roles.")
-    raise AuthorizationError("Insufficient roles required for this action.")
+    if authentication_session.anonymous:
+        logger.warning(
+            f"Client {get_ip(request)} attempted an unauthorized action anonymously."
+        )
+        raise AnonymousError
+    if set(required_roles) & {
+        role.name
+        for role in await authentication_session.bearer.roles.filter(
+            deleted=False
+        ).all()
+    }:
+        return authentication_session
+    logger.warning(
+        f"Client {get_ip(request)} with account {authentication_session.bearer.id} attempted an unauthorized action"
+    )
+    raise AuthorizationError("Insufficient roles required for this action")
 
 
-def require_permissions(*required_permissions: str):
+async def assign_role(
+    name: str,
+    account: Account,
+    description: str,
+    *permissions: str,
+) -> Role:
+    """
+    Easy account role assignment, role being assigned to an account will be created if it doesn't exist.
+
+    Args:
+        name (str):  The name of the role associated with the account.
+        account (Account): The account associated with the created role.
+        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()
+    except DoesNotExist:
+        role = await Role.create(
+            name=name,
+            description=description,
+            permissions=permissions,
+        )
+    await account.roles.add(role)
+    return role
+
+
+def requires_permission(*required_permissions: str):
     """
     Authenticates client and determines if the account has sufficient permissions for an action.
 
@@ -105,8 +175,8 @@ def require_permissions(*required_permissions: str):
         This method is not called directly and instead used as a decorator:
 
             @app.post("api/auth/perms")
-            @require_permissions("admin:update", "employee:add")
-            async def on_require_perms(request):
+            @requires_permission("admin:update", "employee:add")
+            async def on_authorize(request):
                 return text("Account permitted.")
 
     Raises:
@@ -118,14 +188,13 @@ def require_permissions(*required_permissions: str):
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
 
     def decorator(func):
         @functools.wraps(func)
         async def wrapper(request, *args, **kwargs):
-            request.ctx.authentication_session = await check_permissions(
-                request, *required_permissions
-            )
+            await check_permissions(request, *required_permissions)
             return await func(request, *args, **kwargs)
 
         return wrapper
@@ -133,7 +202,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.
 
@@ -144,8 +213,8 @@ def require_roles(*required_roles: str):
         This method is not called directly and instead used as a decorator:
 
             @app.post("api/auth/roles")
-            @require_roles("Admin", "Moderator")
-            async def on_require_roles(request):
+            @requires_role("Admin", "Moderator")
+            async def on_authorize(request):
                 return text("Account permitted")
 
     Raises:
@@ -157,38 +226,15 @@ def require_roles(*required_roles: str):
         UnverifiedError
         DisabledError
         AuthorizationError
+        AnonymousError
     """
 
     def decorator(func):
         @functools.wraps(func)
         async def wrapper(request, *args, **kwargs):
-            request.ctx.authentication_session = await check_roles(
-                request, *required_roles
-            )
+            await check_roles(request, *required_roles)
             return await func(request, *args, **kwargs)
 
         return wrapper
 
     return decorator
-
-
-async def assign_role(
-    name: str, account: Account, permissions: str = None, description: str = None
-) -> Role:
-    """
-    Easy account role assignment. Role being assigned to an account will be created if it doesn't exist.
-
-    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.
-        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
-        )
-    await account.roles.add(role)
-    return role

sanic_security/configuration.py

@@ -2,40 +2,47 @@ from os import environ
 
 from sanic.utils import str_to_bool
 
-
 """
-An effective, simple, and async security library for the Sanic framework.
-Copyright (C) 2020-present Aidan Stewart
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published
-by the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+Copyright (c) 2020-present Nicholas Aidan Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 """
 
-
 DEFAULT_CONFIG = {
     "SECRET": "This is a big secret. Shhhhh",
     "PUBLIC_SECRET": None,
-    "SESSION_SAMESITE": "strict",
+    "OAUTH_CLIENT": None,
+    "OAUTH_SECRET": None,
+    "OAUTH_REDIRECT": None,
+    "SESSION_SAMESITE": "Strict",
     "SESSION_SECURE": True,
     "SESSION_HTTPONLY": True,
     "SESSION_DOMAIN": None,
-    "SESSION_PREFIX": "token",
+    "SESSION_PREFIX": "tkn",
     "SESSION_ENCODING_ALGORITHM": "HS256",
-    "MAX_CHALLENGE_ATTEMPTS": 5,
-    "CAPTCHA_SESSION_EXPIRATION": 60,
+    "MAX_CHALLENGE_ATTEMPTS": 3,
+    "CAPTCHA_SESSION_EXPIRATION": 180,
     "CAPTCHA_FONT": "captcha-font.ttf",
-    "TWO_STEP_SESSION_EXPIRATION": 200,
-    "AUTHENTICATION_SESSION_EXPIRATION": 2592000,
+    "CAPTCHA_VOICE": "captcha-voice/",
+    "TWO_STEP_SESSION_EXPIRATION": 300,
+    "AUTHENTICATION_SESSION_EXPIRATION": 86400,
+    "AUTHENTICATION_REFRESH_EXPIRATION": 604800,
     "ALLOW_LOGIN_WITH_USERNAME": False,
     "INITIAL_ADMIN_EMAIL": "admin@example.com",
     "INITIAL_ADMIN_PASSWORD": "admin123",
@@ -50,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.
@@ -59,8 +69,10 @@ 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.
-        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 (bool): The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.
+        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.
         ALLOW_LOGIN_WITH_USERNAME (bool): Allows login via username and email.
         INITIAL_ADMIN_EMAIL (str): Email used when creating the initial admin account.
         INITIAL_ADMIN_PASSWORD (str): Password used when creating the initial admin account.
@@ -69,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
@@ -78,8 +93,10 @@ 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
     ALLOW_LOGIN_WITH_USERNAME: bool
     INITIAL_ADMIN_EMAIL: str
     INITIAL_ADMIN_PASSWORD: str

sanic_security/exceptions.py

@@ -3,21 +3,25 @@ from sanic.exceptions import SanicException
 from sanic_security.utils import json
 
 """
-An effective, simple, and async security library for the Sanic framework.
-Copyright (C) 2020-present Aidan Stewart
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published
-by the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+Copyright (c) 2020-present Nicholas Aidan Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 """
 
 
@@ -53,7 +57,25 @@ class DeletedError(SecurityError):
     """
 
     def __init__(self, message):
-        super().__init__(message, 410)
+        super().__init__(message, 404)
+
+
+class CredentialsError(SecurityError):
+    """
+    Raised when credentials are invalid.
+    """
+
+    def __init__(self, message, code=400):
+        super().__init__(message, code)
+
+
+class OAuthError(SecurityError):
+    """
+    Raised when an error occurs during OAuth flow.
+    """
+
+    def __init__(self, message, code=401):
+        super().__init__(message, code)
 
 
 class AccountError(SecurityError):
@@ -106,7 +128,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=401
+    ):
         super().__init__(message, code)
 
 
@@ -115,7 +139,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.",
+        code: int = 401,
+    ):
         super().__init__(message, code)
 
 
@@ -124,8 +152,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):
@@ -173,10 +201,16 @@ class AuthorizationError(SecurityError):
         super().__init__(message, 403)
 
 
-class CredentialsError(SecurityError):
+class AnonymousError(AuthorizationError):
     """
-    Raised when credentials are invalid.
+    Raised when attempting to authorize an anonymous user.
     """
 
-    def __init__(self, message, code=400):
-        super().__init__(message, code)
+    def __init__(self):
+        super().__init__("Session is anonymous.")
+
+
+class AuditWarning(Warning):
+    """
+    Raised when configuration may be dangerous.
+    """