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

sanic_security/models.py

@@ -1,36 +1,49 @@
+import base64
 import datetime
-from io import BytesIO
+import logging
+import re
+import uuid
 from typing import Union
 
 import jwt
-from captcha.image import ImageCaptcha
 from jwt import DecodeError
-from sanic.log import logger
 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
+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, get_code, get_expiration_date
+from sanic_security.utils import (
+    get_ip,
+    get_code,
+    get_expiration_date,
+    image_generator,
+    audio_generator,
+    is_expired,
+)
 
 """
-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.
 """
 
 
@@ -39,30 +52,32 @@ class BaseModel(Model):
     Base Sanic Security model that all other models derive from.
 
     Attributes:
-        id (int): Primary key of model.
+        id (str): Primary key of model.
         date_created (datetime): Time this model was created in the database.
         date_updated (datetime): Time this model was updated in the database.
         deleted (bool): Renders the model filterable without removing from the database.
     """
 
-    id: int = fields.IntField(pk=True)
+    id: str = fields.CharField(
+        pk=True, max_length=36, default=lambda: str(uuid.uuid4())
+    )
     date_created: datetime.datetime = fields.DatetimeField(auto_now_add=True)
     date_updated: datetime.datetime = fields.DatetimeField(auto_now=True)
     deleted: bool = fields.BooleanField(default=False)
 
     def validate(self) -> None:
         """
-        Raises an error with respect to state.
+        Raises an error with respect to model's state.
 
         Raises:
             SecurityError
         """
-        raise NotImplementedError()
+        raise NotImplementedError
 
     @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 a request or response.
 
         Example:
             Below is an example of this method returning a dict to be used for JSON serialization.
@@ -79,7 +94,7 @@ class BaseModel(Model):
                     }
 
         """
-        raise NotImplementedError()
+        raise NotImplementedError
 
     class Meta:
         abstract = True
@@ -93,35 +108,40 @@ 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 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 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=True, max_length=32)
-    email: str = fields.CharField(unique=True, max_length=255)
-    phone: str = fields.CharField(unique=True, max_length=14, null=True)
+    username: str = fields.CharField(
+        unique=config.ALLOW_LOGIN_WITH_USERNAME,
+        max_length=32,
+    )
+    email: str = fields.CharField(
+        unique=True,
+        max_length=255,
+        validators=[
+            RegexValidator(r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$", re.I)
+        ],
+    )
+    phone: str = fields.CharField(
+        unique=True,
+        max_length=15,
+        null=True,
+        validators=[
+            RegexValidator(r"^(\+\d{1,2}\s)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}$", re.I)
+        ],
+    )
     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(
         "models.Role", through="account_role"
     )
 
-    @property
-    def json(self) -> dict:
-        return {
-            "id": self.id,
-            "date_created": str(self.date_created),
-            "date_updated": str(self.date_updated),
-            "email": self.email,
-            "username": self.username,
-            "phone": self.phone,
-            "disabled": self.disabled,
-            "verified": self.verified,
-        }
-
     def validate(self) -> None:
         """
         Raises an error with respect to account state.
@@ -134,9 +154,9 @@ class Account(BaseModel):
         if self.deleted:
             raise DeletedError("Account has been deleted.")
         elif not self.verified:
-            raise UnverifiedError()
+            raise UnverifiedError
         elif self.disabled:
-            raise DisabledError()
+            raise DisabledError
 
     async def disable(self):
         """
@@ -151,6 +171,19 @@ class Account(BaseModel):
             self.disabled = True
             await self.save(update_fields=["disabled"])
 
+    @property
+    def json(self) -> dict:
+        return {
+            "id": self.id,
+            "date_created": str(self.date_created),
+            "date_updated": str(self.date_updated),
+            "email": self.email,
+            "username": self.username,
+            "phone": self.phone,
+            "disabled": self.disabled,
+            "verified": self.verified,
+        }
+
     @staticmethod
     async def get_via_email(email: str):
         """
@@ -166,9 +199,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.lower(), deleted=False).get()
+        except (DoesNotExist, ValidationError):
             raise NotFoundError("Account with this email does not exist.")
 
     @staticmethod
@@ -186,15 +218,66 @@ class Account(BaseModel):
             NotFoundError
         """
         try:
-            account = await Account.filter(username=username, deleted=False).get()
-            return account
-        except DoesNotExist:
+            return await Account.filter(username=username, deleted=False).get()
+        except (DoesNotExist, ValidationError):
             raise NotFoundError("Account with this username does not exist.")
 
+    @staticmethod
+    async def get_via_credential(credential: str):
+        """
+        Retrieve an account with an email or username.
+
+        Args:
+            credential (str): Email or username associated to account being retrieved.
+
+        Returns:
+            account
+
+        Raises:
+            NotFoundError
+        """
+        try:
+            account = await Account.get_via_email(credential)
+        except NotFoundError as e:
+            if config.ALLOW_LOGIN_WITH_USERNAME:
+                account = await Account.get_via_username(credential)
+            else:
+                raise e
+        return account
+
+    @staticmethod
+    async def get_via_header(request: Request):
+        """
+         Retrieve an account via the basic authorization header.
+
+        Args:
+            request (Request): Sanic request parameter.
+
+        Returns:
+            account, password
+
+        Raises:
+            NotFoundError
+        """
+        if request.headers.get("Authorization"):
+            authorization_type, credentials = request.headers.get(
+                "Authorization"
+            ).split()
+            if authorization_type == "Basic":
+                email_or_username, password = (
+                    base64.b64decode(credentials).decode().split(":")
+                )
+                account = await Account.get_via_credential(email_or_username)
+                return account, password
+            else:
+                raise CredentialsError("Invalid authorization type.")
+        else:
+            raise CredentialsError("Authorization header not provided.")
+
     @staticmethod
     async def get_via_phone(phone: str):
         """
-        Retrieve an account with a phone number.
+        Retrieve an account via a phone number.
 
         Args:
             phone (str): Phone number associated to account being retrieved.
@@ -206,9 +289,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.")
 
 
@@ -219,7 +301,7 @@ class Session(BaseModel):
     Attributes:
         expiration_date (datetime): Date and time the session expires and can no longer be used.
         active (bool): Determines if the session can be used.
-        ip (str): IP address of client creating session.
+        ip (str): IP address of client instantiating session.
         bearer (ForeignKeyRelation[Account]): Account associated with this session.
     """
 
@@ -233,19 +315,6 @@ class Session(BaseModel):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-    @property
-    def json(self) -> dict:
-        return {
-            "id": self.id,
-            "date_created": str(self.date_created),
-            "date_updated": str(self.date_updated),
-            "expiration_date": str(self.expiration_date),
-            "bearer": self.bearer.username
-            if isinstance(self.bearer, Account)
-            else None,
-            "active": self.active,
-        }
-
     def validate(self) -> None:
         """
         Raises an error with respect to session state.
@@ -257,17 +326,14 @@ class Session(BaseModel):
         """
         if self.deleted:
             raise DeletedError("Session has been deleted.")
-        elif (
-            self.expiration_date
-            and datetime.datetime.now(datetime.timezone.utc) >= self.expiration_date
-        ):
-            raise ExpiredError()
         elif not self.active:
-            raise DeactivatedError()
+            raise DeactivatedError
+        elif is_expired(self.expiration_date):
+            raise ExpiredError
 
-    async def deactivate(self):
+    async def deactivate(self) -> None:
         """
-        Renders session deactivated and unusable.
+        Renders session deactivated and therefor unusable.
 
         Raises:
             DeactivatedError
@@ -285,38 +351,55 @@ class Session(BaseModel):
         Args:
             response (HTTPResponse): Sanic response used to store JWT into a cookie on the client.
         """
-        payload = {
-            "id": self.id,
-            "date_created": str(self.date_created),
-            "expiration_date": str(self.expiration_date),
-            "ip": self.ip,
-        }
-        cookie = (
-            f"{security_config.SESSION_PREFIX}_{self.__class__.__name__.lower()[:7]}"
-        )
         encoded_session = jwt.encode(
-            payload, security_config.SECRET, security_config.SESSION_ENCODING_ALGORITHM
+            {
+                "id": self.id,
+                "date_created": str(self.date_created),
+                "expiration_date": str(self.expiration_date),
+                "bearer": self.bearer.id if isinstance(self.bearer, Account) else None,
+                "ip": self.ip,
+            },
+            config.SECRET,
+            config.SESSION_ENCODING_ALGORITHM,
         )
-        if isinstance(encoded_session, bytes):
-            encoded_session = encoded_session.decode()
         response.cookies.add_cookie(
-            cookie,
-            encoded_session,
-            httponly=security_config.SESSION_HTTPONLY,
-            samesite=security_config.SESSION_SAMESITE,
-            secure=security_config.SESSION_SECURE,
+            f"{config.SESSION_PREFIX}_{self.__class__.__name__[:7].lower()}",
+            str(encoded_session),
+            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,
         )
-        if self.expiration_date:
-            response.cookies.get_cookie(cookie).expires = self.expiration_date
-        if security_config.SESSION_DOMAIN:
-            response.cookies.get_cookie(cookie).domain = security_config.SESSION_DOMAIN
+
+    @property
+    def json(self) -> dict:
+        return {
+            "id": self.id,
+            "date_created": str(self.date_created),
+            "date_updated": str(self.date_updated),
+            "expiration_date": str(self.expiration_date),
+            "bearer": self.bearer.id if isinstance(self.bearer, Account) else None,
+            "active": self.active,
+        }
+
+    @property
+    def anonymous(self) -> bool:
+        """
+        Determines if an account is associated with session.
+
+        Returns:
+            anonymous
+        """
+        return self.bearer is None
 
     @classmethod
     async def new(
         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.
@@ -324,12 +407,12 @@ 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
         """
-        raise NotImplementedError()
+        raise NotImplementedError
 
     @classmethod
     async def get_associated(cls, account: Account):
@@ -337,7 +420,7 @@ class Session(BaseModel):
         Retrieves sessions associated to an account.
 
         Args:
-            account (Request): Account associated with sessions being retrieved.
+            account (Account): Account associated with sessions being retrieved.
 
         Returns:
             sessions
@@ -345,7 +428,7 @@ class Session(BaseModel):
         Raises:
             NotFoundError
         """
-        sessions = await cls.filter(bearer=account).prefetch_related("bearer").all()
+        sessions = await cls.filter(bearer=account, deleted=False).all()
         if not sessions:
             raise NotFoundError("No sessions associated to account were found.")
         return sessions
@@ -353,7 +436,7 @@ class Session(BaseModel):
     @classmethod
     def decode_raw(cls, request: Request) -> dict:
         """
-        Decodes JWT token from client cookie into a python dict.
+        Decodes session JWT token from client cookie into a python dict.
 
         Args:
             request (Request): Sanic request parameter.
@@ -365,18 +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.SECRET
-                    if not security_config.PUBLIC_SECRET
-                    else security_config.PUBLIC_SECRET,
-                    security_config.SESSION_ENCODING_ALGORITHM,
+                    config.PUBLIC_SECRET or config.SECRET,
+                    config.SESSION_ENCODING_ALGORITHM,
                 )
         except DecodeError as e:
             raise JWTDecodeError(str(e))
@@ -384,7 +465,7 @@ class Session(BaseModel):
     @classmethod
     async def decode(cls, request: Request):
         """
-        Decodes session JWT from client cookie to a Sanic Security session.
+        Decodes session JWT token from client cookie into a session model.
 
         Args:
             request (Request): Sanic request parameter.
@@ -401,6 +482,7 @@ class Session(BaseModel):
             decoded_session = (
                 await cls.filter(id=decoded_raw["id"]).prefetch_related("bearer").get()
             )
+            request.ctx.session = decoded_session
         except DoesNotExist:
             raise NotFoundError("Session could not be found.")
         return decoded_session
@@ -411,66 +493,68 @@ class Session(BaseModel):
 
 class VerificationSession(Session):
     """
-    Used for a client verification method that requires some form of code, challenge, or key.
+    Used for client verification challenges that require some form of code or key.
 
     Attributes:
-        attempts (int): The amount of incorrect times a user entered a code not equal to this verification sessions code.
-        code (str): Used as a secret key that would be sent via email, text, etc to complete the verification challenge.
+        attempts (int): The amount of times a user entered a code not equal to this verification sessions code.
+        code (str): A secret key that would be sent via email, text, etc.
     """
 
     attempts: int = fields.IntField(default=0)
-    code: str = fields.CharField(max_length=10, default=get_code, null=True)
-
-    @classmethod
-    async def new(cls, request: Request, account: Account, **kwargs):
-        raise NotImplementedError
+    code: str = fields.CharField(max_length=6, null=True)
 
-    async def check_code(self, request: Request, code: str) -> None:
+    async def check_code(self, code: str) -> None:
         """
         Checks if code passed is equivalent to the session code.
 
         Args:
             code (str): Code being cross-checked with session code.
-            request (Request): Sanic request parameter.
 
         Raises:
             ChallengeError
             MaxedOutChallengeError
         """
-        if self.code != code.upper():
-            if self.attempts < security_config.MAX_CHALLENGE_ATTEMPTS:
-                self.attempts += 1
+        if not code or self.code != code.upper():
+            self.attempts += 1
+            if self.attempts < config.MAX_CHALLENGE_ATTEMPTS:
                 await self.save(update_fields=["attempts"])
                 raise ChallengeError(
                     "Your code does not match verification session code."
                 )
             else:
-                logger.warning(
-                    f"Client ({get_ip(request)}) has maxed out on session challenge attempts"
-                )
-                raise MaxedOutChallengeError()
+                raise MaxedOutChallengeError
         else:
-            self.active = False
-            await self.save(update_fields=["active"])
+            await self.deactivate()
+
+    @classmethod
+    async def new(
+        cls,
+        request: Request,
+        account: Account,
+        **kwargs: Union[int, str, bool, float, list, dict],
+    ):
+        raise NotImplementedError
 
     class Meta:
         abstract = True
 
 
 class TwoStepSession(VerificationSession):
-    """
-    Validates a client using a code sent via email or text.
-    """
+    """Validates client using a code sent via email or text."""
 
     @classmethod
-    async def new(cls, request: Request, account: Account, **kwargs):
-        return await TwoStepSession.create(
+    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),
         )
 
     class Meta:
@@ -478,31 +562,38 @@ class TwoStepSession(VerificationSession):
 
 
 class CaptchaSession(VerificationSession):
-    """
-    Validates a client with a captcha challenge.
-    """
+    """Validates client with a captcha challenge via image or audio."""
 
     @classmethod
-    async def new(cls, request: Request, **kwargs):
-        return await CaptchaSession.create(
+    async def new(
+        cls,
+        request: Request,
+        **kwargs: Union[int, str, bool, float, list, dict],
+    ):
+        return await cls.create(
             **kwargs,
             ip=get_ip(request),
-            expiration_date=get_expiration_date(
-                security_config.CAPTCHA_SESSION_EXPIRATION
-            ),
+            code=get_code(),
+            expiration_date=get_expiration_date(config.CAPTCHA_SESSION_EXPIRATION),
         )
 
-    def get_image(self) -> HTTPResponse:
+    def get_image(self) -> bytes:
         """
-        Retrieves captcha image file.
+        Retrieves captcha image data.
 
         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 image_generator.generate(self.code, "jpeg").getvalue()
+
+    def get_audio(self) -> bytes:
+        """
+        Retrieves captcha audio data.
+
+        Returns:
+            captcha_audio
+        """
+        return bytes(audio_generator.generate(self.code))
 
     class Meta:
         table = "captcha_session"
@@ -513,10 +604,14 @@ class AuthenticationSession(Session):
     Used to authenticate and identify a client.
 
     Attributes:
+        refresh_expiration_date (datetime): Date and time the session can no longer be refreshed.
         requires_second_factor (bool): Determines if session requires a second factor.
+        is_refresh (bool): Will only be true once when instantiated during the refresh of expired session.
     """
 
+    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:
         """
@@ -530,18 +625,49 @@ class AuthenticationSession(Session):
         """
         super().validate()
         if self.requires_second_factor:
-            raise SecondFactorRequiredError()
+            raise SecondFactorRequiredError
+
+    async def refresh(self, request: Request):
+        """
+        Refreshes session if within refresh date.
+
+        Args:
+            request (Request): Sanic request parameter.
+
+        Raises:
+            ExpiredError
+
+        Returns:
+            session
+        """
+        if self.active and not is_expired(self.refresh_expiration_date):
+            await self.deactivate()
+            logging.info(
+                f"Client {get_ip(request)} has refreshed authentication session {self.id}."
+            )
+            return await self.new(request, self.bearer)
+        else:
+            raise ExpiredError
 
     @classmethod
-    async def new(cls, request: Request, account: Account, **kwargs):
-        return await AuthenticationSession.create(
+    async def new(
+        cls,
+        request: Request,
+        account: Account = None,
+        **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(
+                config.AUTHENTICATION_REFRESH_EXPIRATION
             ),
         )
+        return authentication_session
 
     class Meta:
         table = "authentication_session"
@@ -554,15 +680,15 @@ 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 and in wildcard format (printer:query, printer:query,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()
+        raise NotImplementedError
 
     @property
     def json(self) -> dict: