diff --git a/README.md b/README.md index 0338026..38d026e 100644 --- a/README.md +++ b/README.md @@ -335,7 +335,7 @@ async def on_captcha(request): ## Two-step Verification -Two-step verification should be integrated with other custom functionalities, such as password recovery. +Two-step verification should be integrated with other custom functionalities, such as forgot password recovery. * Request Two-step Verification diff --git a/pyproject.toml b/pyproject.toml index d6547ee..184ae10 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "sanic-security" -version = "1.15.2" +version = "1.15.3" requires-python = ">=3.8" dependencies = [ "tortoise-orm>=0.17.0", diff --git a/sanic_security/authentication.py b/sanic_security/authentication.py index 8fb12cc..2e577eb 100644 --- a/sanic_security/authentication.py +++ b/sanic_security/authentication.py @@ -247,6 +247,7 @@ async def on_authenticate(request): DeactivatedError UnverifiedError DisabledError + SecondFactorRequiredError ExpiredError """ @@ -287,7 +288,7 @@ def initialize_security(app: Sanic, create_root=True) -> None: Audits configuration, creates root administrator account, and attaches refresh encoder middleware. Args: - app (Sanic): The main Sanic application instance. + app (Sanic): Sanic application instance. create_root (bool): Determines root account creation on initialization. """ diff --git a/sanic_security/models.py b/sanic_security/models.py index 5ff9a93..954f8bb 100644 --- a/sanic_security/models.py +++ b/sanic_security/models.py @@ -52,7 +52,7 @@ 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. @@ -67,7 +67,7 @@ class BaseModel(Model): def validate(self) -> None: """ - Raises an error with respect to state. + Raises an error with respect to model's state. Raises: SecurityError @@ -77,7 +77,7 @@ def validate(self) -> None: @property def json(self) -> dict: """ - A JSON serializable dict to be used in an 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. @@ -108,7 +108,7 @@ 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. 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. @@ -247,7 +247,7 @@ async def get_via_credential(credential: str): @staticmethod async def get_via_header(request: Request): """ - Retrieve the account the client is logging into and client's password attempt via the basic authorization header. + Retrieve an account via the basic authorization header. Args: request (Request): Sanic request parameter. @@ -276,7 +276,7 @@ async def get_via_header(request: Request): @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. @@ -332,7 +332,7 @@ def validate(self) -> None: async def deactivate(self): """ - Renders session deactivated and unusable. + Renders session deactivated and therefor unusable. Raises: DeactivatedError @@ -426,7 +426,7 @@ async def get_associated(cls, account: Account): 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 @@ -442,7 +442,7 @@ async def get_associated(cls, account: Account): @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. @@ -471,7 +471,7 @@ def decode_raw(cls, request: Request) -> dict: @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. @@ -498,11 +498,11 @@ class Meta: 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) @@ -540,7 +540,7 @@ class Meta: 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): @@ -559,7 +559,7 @@ class Meta: 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): @@ -574,7 +574,7 @@ async def new(cls, request: Request, **kwargs): def get_image(self) -> HTTPResponse: """ - Retrieves captcha image file. + Retrieves captcha image data. Returns: captcha_image @@ -586,7 +586,7 @@ def get_image(self) -> HTTPResponse: def get_audio(self) -> HTTPResponse: """ - Retrieves captcha audio file. + Retrieves captcha audio data. Returns: captcha_audio @@ -604,9 +604,9 @@ class AuthenticationSession(Session): Used to authenticate and identify a client. Attributes: - refresh_expiration_date (bool): Date and time the session can no longer be refreshed. + 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 refresh of expired session. + 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) @@ -679,7 +679,7 @@ 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 (str): Permissions of the role. Must be separated via comma & space and in wildcard format (printer:query, dashboard:info,delete). """ name: str = fields.CharField(unique=True, max_length=255) diff --git a/sanic_security/utils.py b/sanic_security/utils.py index 944cb0c..e1d7d35 100644 --- a/sanic_security/utils.py +++ b/sanic_security/utils.py @@ -98,14 +98,12 @@ def get_expiration_date(seconds: int) -> datetime.datetime: ) -def json( - message: str, data, status_code: int = 200 -) -> HTTPResponse: # May be causing fixture error bc of json property +def json(message: str, data, status_code: int = 200) -> HTTPResponse: """ A preformatted Sanic json response. Args: - message (int): Message describing data or relaying human-readable information. + message (str): Message describing data or relaying human-readable information. data (Any): Raw information to be used by client. status_code (int): HTTP response code.