sanic-security 1.15.2__py3-none-any.whl → 1.16.0__py3-none-any.whl

sanic_security/oauth.py

@@ -0,0 +1,239 @@
+import functools
+import time
+from typing import Literal
+
+import jwt
+from httpx_oauth.oauth2 import BaseOAuth2, RefreshTokenError
+from jwt import DecodeError
+from sanic import Request, HTTPResponse, Sanic
+from sanic.log import logger
+from tortoise.exceptions import IntegrityError, DoesNotExist
+
+from sanic_security.configuration import config
+from sanic_security.exceptions import JWTDecodeError, ExpiredError, CredentialsError
+from sanic_security.models import Account, AuthenticationSession
+from sanic_security.utils import get_ip
+
+"""
+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.
+"""
+
+
+async def oauth_url(
+    client: BaseOAuth2,
+    redirect_uri: str = config.OAUTH_REDIRECT,
+    state: str = None,
+    scopes: list[str] = None,
+    code_challenge: str = None,
+    code_challenge_method: Literal["plain", "S256"] = None,
+    **extra_params: str,
+) -> str:
+    """
+    Constructs an authorization URL to prompt the user to authorize the application.
+
+    Args:
+        client (BaseOAuth2): OAuth provider.
+        redirect_uri (str): The URL where the user will be redirected after authorization.
+        state (str): An opaque value used by the client to maintain state between the request and the callback.
+        scopes (list[str]): The scopes to be requested. If not provided, `base_scopes` will be used.
+        code_challenge (str): [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) code challenge.
+        code_challenge_method (str): [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) code challenge method.
+        **extra_params (dict[str, str]): Optional extra parameters specific to the service.
+
+    Returns:
+        oauth_redirect
+    """
+    return await client.get_authorization_url(
+        redirect_uri,
+        state,
+        scopes or client.base_scopes,
+        code_challenge,
+        code_challenge_method,
+        extra_params,
+    )
+
+
+async def oauth_callback(
+    request: Request,
+    client: BaseOAuth2,
+    redirect_uri: str = config.OAUTH_REDIRECT,
+    code_verifier: str = None,
+) -> tuple[dict, AuthenticationSession]:
+    """
+    Requests an access token using the authorization code obtained after the user has authorized the application.
+    An account is retrieved if it already exists, created if it doesn't, and the user is logged in.
+
+    Args:
+        request (Request): Sanic request parameter.
+        client (BaseOAuth2): OAuth provider.
+        redirect_uri (str): The URL where the user was redirected after authorization.
+        code_verifier (str): Optional code verifier used in the [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) flow.
+
+    Raises:
+        CredentialsError
+        GetAccessTokenError
+        GetIdEmailError
+
+    Returns:
+        oauth_redirect
+    """
+    token_info = await client.get_access_token(
+        request.args.get("code"),
+        redirect_uri,
+        code_verifier,
+    )
+    if "expires_at" not in token_info:
+        token_info["expires_at"] = time.time() + token_info["expires_in"]
+    oauth_id, email = await client.get_id_email(token_info["access_token"])
+    try:
+        try:
+            account = await Account.get(oauth_id=oauth_id)
+        except DoesNotExist:
+            account = await Account.create(
+                email=email,
+                username=email.split("@")[0],
+                password="",
+                oauth_id=oauth_id,
+            )
+        authentication_session = await AuthenticationSession.new(
+            request,
+            account,
+        )
+        logger.info(
+            f"Client {get_ip(request)} has logged in via {client.__class__.__name__} with authentication session {authentication_session.id}."
+        )
+        return token_info, authentication_session
+    except IntegrityError:
+        raise CredentialsError(
+            f"Account may not be linked to this OAuth provider if it already exists.",
+            409,
+        )
+
+
+def oauth_encode(response: HTTPResponse, token_info: dict) -> None:
+    """
+    Transforms OAuth access token into JWT and then is stored in a cookie.
+
+    Args:
+        response (HTTPResponse): Sanic response used to store JWT into a cookie on the client.
+        token_info (dict): OAuth access token.
+    """
+    response.cookies.add_cookie(
+        f"{config.SESSION_PREFIX}_oauth",
+        str(
+            jwt.encode(
+                token_info,
+                config.SECRET,
+                config.SESSION_ENCODING_ALGORITHM,
+            ),
+        ),
+        httponly=config.SESSION_HTTPONLY,
+        samesite=config.SESSION_SAMESITE,
+        secure=config.SESSION_SECURE,
+        domain=config.SESSION_DOMAIN,
+        max_age=token_info["expires_in"] + config.AUTHENTICATION_REFRESH_EXPIRATION,
+    )
+
+
+async def oauth_decode(request: Request, client: BaseOAuth2, refresh=False) -> dict:
+    """
+    Decodes OAuth JWT token from client cookie into an access token.
+
+    Args:
+        request (Request): Sanic request parameter.
+        client (BaseOAuth2): OAuth provider.
+        refresh (bool): Ensures that the decoded access token is refreshed.
+
+    Raises:
+        JWTDecodeError
+        ExpiredError
+        RefreshTokenNotSupportedError
+
+    Returns:
+        token_info
+    """
+    try:
+        token_info = jwt.decode(
+            request.cookies.get(
+                f"{config.SESSION_PREFIX}_oauth",
+            ),
+            config.PUBLIC_SECRET or config.SECRET,
+            config.SESSION_ENCODING_ALGORITHM,
+        )
+        if time.time() > token_info["expires_at"] or refresh:
+            token_info = await client.refresh_token(token_info["refresh_token"])
+            token_info["is_refresh"] = True
+            if "expires_at" not in token_info:
+                token_info["expires_at"] = time.time() + token_info["expires_in"]
+        request.ctx.oauth = token_info
+        return token_info
+    except RefreshTokenError:
+        raise ExpiredError
+    except DecodeError:
+        raise JWTDecodeError
+
+
+def requires_oauth(client: BaseOAuth2):
+    """
+    Decodes OAuth JWT token from client cookie into an access token.
+
+    Args:
+        client (BaseOAuth2): OAuth provider.
+
+    Example:
+        This method is not called directly and instead used as a decorator:
+
+            @app.post('api/oauth')
+            @requires_oauth
+            async def on_oauth(request):
+                return text('OAuth access token retrieved!')
+
+    Raises:
+        JWTDecodeError
+        ExpiredError
+        RefreshTokenNotSupportedError
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(request, *args, **kwargs):
+            await oauth_decode(request, client)
+            return await func(request, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def initialize_oauth(app: Sanic) -> None:
+    """
+    Attaches refresh encoder middleware.
+
+    Args:
+        app (Sanic): Sanic application instance.
+    """
+
+    @app.on_response
+    async def refresh_encoder_middleware(request, response):
+        if hasattr(request.ctx, "oauth") and getattr(
+            request.ctx.oauth, "is_refresh", False
+        ):
+            oauth_encode(response, request.ctx.oauth)

sanic_security/test/server.py

@@ -1,8 +1,8 @@
 import datetime
 import traceback
 
-from argon2 import PasswordHasher
-from sanic import Sanic, text
+from httpx_oauth.clients.google import GoogleOAuth2
+from sanic import Sanic, text, raw, redirect
 from tortoise.contrib.sanic import register_tortoise
 
 from sanic_security.authentication import (
@@ -18,10 +18,17 @@ from sanic_security.authorization import (
     check_permissions,
     check_roles,
 )
-from sanic_security.configuration import config as security_config
+from sanic_security.configuration import config
 from sanic_security.exceptions import SecurityError
 from sanic_security.models import Account, CaptchaSession, AuthenticationSession
-from sanic_security.utils import json
+from sanic_security.oauth import (
+    oauth_encode,
+    initialize_oauth,
+    oauth_url,
+    oauth_callback,
+    oauth_decode,
+)
+from sanic_security.utils import json, str_to_bool, password_hasher
 from sanic_security.verification import (
     request_two_step_verification,
     requires_two_step_verification,
@@ -52,11 +59,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
 
-app = Sanic("sanic-security-test")
-password_hasher = PasswordHasher()
-
-
-# TODO: Testing for new functionality.
+app = Sanic("tests")
+google_oauth = GoogleOAuth2(config.OAUTH_CLIENT, config.OAUTH_SECRET)
 
 
 @app.post("api/test/auth/register")
@@ -64,8 +68,8 @@ async def on_register(request):
     """Register an account with email and password."""
     account = await register(
         request,
-        verified=request.form.get("verified") == "true",
-        disabled=request.form.get("disabled") == "true",
+        verified=str_to_bool(request.form.get("verified")),
+        disabled=str_to_bool(request.form.get("disabled")),
     )
     if not account.verified:
         two_step_session = await request_two_step_verification(request, account)
@@ -90,11 +94,13 @@ async def on_verify(request):
 @app.post("api/test/auth/login")
 async def on_login(request):
     """Login to an account with an email and password."""
-    two_factor_authentication = request.args.get("two-factor-authentication") == "true"
     authentication_session = await login(
-        request, require_second_factor=two_factor_authentication
+        request,
+        require_second_factor=str_to_bool(
+            request.args.get("two-factor-authentication")
+        ),
     )
-    if two_factor_authentication:
+    if str_to_bool(request.args.get("two-factor-authentication")):
         two_step_session = await request_two_step_verification(
             request, authentication_session.bearer
         )
@@ -192,14 +198,14 @@ async def on_captcha_request(request):
 async def on_captcha_image(request):
     """Request captcha image."""
     captcha_session = await CaptchaSession.decode(request)
-    return captcha_session.get_image()
+    return raw(captcha_session.get_image(), content_type="image/jpeg")
 
 
 @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()
+    return raw(captcha_session.get_audio(), content_type="audio/mpeg")
 
 
 @app.post("api/test/capt")
@@ -226,7 +232,6 @@ async def on_verification_attempt(request):
 
 
 @app.post("api/test/auth/roles")
-@requires_authentication
 async def on_authorization(request):
     """Check if client is authorized with sufficient roles and permissions."""
     await check_roles(request, request.form.get("role"))
@@ -234,7 +239,7 @@ async def on_authorization(request):
         await check_permissions(
             request, *request.form.get("permissions_required").split(", ")
         )
-    return text("Account permitted.")
+    return text("Account permitted!")
 
 
 @app.post("api/test/auth/roles/assign")
@@ -244,10 +249,14 @@ async def on_role_assign(request):
     await assign_role(
         request.form.get("name"),
         request.ctx.session.bearer,
-        request.form.get("permissions"),
         "Role used for testing.",
+        *(
+            request.form.get("permissions").split(", ")
+            if request.form.get("permissions")
+            else []
+        ),
     )
-    return text("Role assigned.b")
+    return text("Role assigned!")
 
 
 @app.post("api/test/account")
@@ -255,7 +264,7 @@ async def on_account_creation(request):
     """Quick account creation."""
     account = await Account.create(
         username=request.form.get("username"),
-        email=request.form.get("email").lower(),
+        email=request.form.get("email"),
         password=password_hasher.hash("password"),
         verified=True,
         disabled=False,
@@ -264,6 +273,43 @@ async def on_account_creation(request):
     return response
 
 
+@app.get("api/test/oauth")
+async def on_oauth_request(request):
+    """OAuth request."""
+    return redirect(
+        await oauth_url(
+            google_oauth,
+            "http://localhost:8000/api/test/oauth/callback",
+        )
+    )
+
+
+@app.get("api/test/oauth/callback")
+async def on_oauth_callback(request):
+    """OAuth callback."""
+    token_info, authentication_session = await oauth_callback(
+        request,
+        google_oauth,
+        "http://localhost:8000/api/test/oauth/callback",
+    )
+    response = json(
+        "OAuth successful.",
+        {"token_info": token_info, "auth_session": authentication_session.json},
+    )
+    oauth_encode(response, token_info)
+    authentication_session.encode(response)
+    return response
+
+
+@app.get("api/test/oauth/token")
+async def on_oauth_token(request):
+    """OAuth token retrieval."""
+    token_info = await oauth_decode(
+        request, google_oauth, str_to_bool(request.args.get("refresh"))
+    )
+    return json("Access token retrieved!", token_info)
+
+
 @app.exception(SecurityError)
 async def on_security_error(request, exception):
     """Handles security errors with correct response."""
@@ -271,7 +317,7 @@ async def on_security_error(request, exception):
     return exception.json
 
 
-security_config.SECRET = """
+config.SECRET = """
 -----BEGIN RSA PRIVATE KEY-----
 MIIEpAIBAAKCAQEAww3pEiUx6wMFawJNAHCI80Qj3eyrP6Yx3LNNluQZXMyZkd+6ugBN9e1hw7v2z2PwmJENhYrqbBHU4vHCHEEZjdZIQRqwriFpeeoqMA1
 ecgwJz3fOuYo6WrUbS6pEyJ9vtjh5TaeZLzER+KIK2uvsjsQnFVt41hh3Xd+tR9p+QXT8aRep9hp4XLF87QlDVDrZIStfVn25+ZfSfKH+WYBUglZBmz/K6uW
@@ -289,7 +335,7 @@ mQ4BjbU1slel/eXlhomQpxoBCH3J/Ba9qd+uBql29QZMQXtKFg/mryjprapq8sUcbgazr9u1x+zJz9w+
 1G1CHHo/vq8zPNkVWmhciIUeHR3YJbw==
 -----END RSA PRIVATE KEY-----
 """
-security_config.PUBLIC_SECRET = """
+config.PUBLIC_SECRET = """
 -----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAww3pEiUx6wMFawJNAHCI80Qj3eyrP6Yx3LNNluQZXMyZkd+6ugBN9e1hw7v2z2PwmJENhYrqbBHU
 4vHCHEEZjdZIQRqwriFpeeoqMA1ecgwJz3fOuYo6WrUbS6pEyJ9vtjh5TaeZLzER+KIK2uvsjsQnFVt41hh3Xd+tR9p+QXT8aRep9hp4XLF87QlDVDrZIStf
@@ -297,16 +343,17 @@ Vn25+ZfSfKH+WYBUglZBmz/K6uW41mSRuuH3Pu/lnPgGvsxtT7KE8dkbyrI+Tyg0pniOYdxBxgpu06S6
 MHlkstd6FFYu5lJQcuppOm79iQIDAQAB
 -----END PUBLIC KEY-----
 """
-security_config.INITIAL_ADMIN_EMAIL = "admin@login.test"
-security_config.SESSION_ENCODING_ALGORITHM = "RS256"
-security_config.ALLOW_LOGIN_WITH_USERNAME = True
-security_config.SESSION_SECURE = False
+config.INITIAL_ADMIN_EMAIL = "admin@login.test"
+config.SESSION_ENCODING_ALGORITHM = "RS256"
+config.ALLOW_LOGIN_WITH_USERNAME = True
+config.SESSION_SECURE = False
 register_tortoise(
     app,
-    db_url=security_config.TEST_DATABASE_URL,
+    db_url=config.TEST_DATABASE_URL,
     modules={"models": ["sanic_security.models"]},
     generate_schemas=True,
 )
 initialize_security(app, True)
+initialize_oauth(app)
 if __name__ == "__main__":
     app.run(host="127.0.0.1", port=8000, workers=1, debug=True)

sanic_security/test/tests.py

@@ -89,12 +89,6 @@ class RegistrationTest(TestCase):
         assert (
             invalid_phone_registration_response.status_code == 400
         ), invalid_phone_registration_response.text
-        invalid_username_registration_response = self.register(
-            "invalid_user@register.test", "_inVal!d_", False, True
-        )
-        assert (
-            invalid_username_registration_response.status_code == 400
-        ), invalid_username_registration_response.text
         too_many_characters_registration_response = self.register(
             "too_long_user@register.test",
             "this_username_is_too_long_to_be_registered_with",
@@ -232,7 +226,7 @@ class LoginTest(TestCase):
             "http://127.0.0.1:8000/api/test/auth/roles",
             data={
                 "role": "Root",
-                "permissions_required": "perm1:create,add, perm2:*",
+                "permissions_required": ["perm1:create,add", "perm2:*"],
             },
         )
         assert (
@@ -390,24 +384,45 @@ class AuthorizationTest(TestCase):
             "http://127.0.0.1:8000/api/test/auth/roles/assign",
             data={
                 "name": "AuthTestPerms",
-                "permissions": "perm1:create,add, perm2:delete",
+                "permissions": "perm1:create,update, perm2:delete,retrieve, perm3:*",
             },
         )
         permitted_authorization_response = self.client.post(
             "http://127.0.0.1:8000/api/test/auth/roles",
             data={
                 "role": "AuthTestPerms",
-                "permissions_required": "perm1:create,add, perm2:*",
+                "permissions_required": "perm1:create,update, perm3:retrieve",
+            },
+        )
+        assert (
+            permitted_authorization_response.status_code == 200
+        ), permitted_authorization_response.text
+        permitted_authorization_response = self.client.post(
+            "http://127.0.0.1:8000/api/test/auth/roles",
+            data={
+                "role": "AuthTestPerms",
+                "permissions_required": "perm1:retrieve, perm2:delete",
             },
         )
         assert (
             permitted_authorization_response.status_code == 200
         ), permitted_authorization_response.text
+
+        prohibited_authorization_response = self.client.post(
+            "http://127.0.0.1:8000/api/test/auth/roles",
+            data={
+                "role": "AuthTestPerms",
+                "permissions_required": "perm1:create,retrieve",
+            },
+        )
+        assert (
+            prohibited_authorization_response.status_code == 403
+        ), prohibited_authorization_response.text
         prohibited_authorization_response = self.client.post(
             "http://127.0.0.1:8000/api/test/auth/roles",
             data={
                 "role": "AuthTestPerms",
-                "permissions_required": "perm2:add, perm1:delete",
+                "permissions_required": "perm1:delete, perm2:create",
             },
         )
         assert (

sanic_security/utils.py

@@ -7,6 +7,7 @@ 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 sanic.utils import str_to_bool as sanic_str_to_bool
 
 from sanic_security.configuration import config
 
@@ -32,11 +33,11 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
 
-image_generator = ImageCaptcha(
+image_generator: ImageCaptcha = ImageCaptcha(
     190, 90, fonts=config.CAPTCHA_FONT.replace(" ", "").split(",")
 )
-audio_generator = AudioCaptcha(voicedir=config.CAPTCHA_VOICE)
-password_hasher = PasswordHasher()
+audio_generator: AudioCaptcha = AudioCaptcha(voicedir=config.CAPTCHA_VOICE)
+password_hasher: PasswordHasher = PasswordHasher()
 
 
 def get_ip(request: Request) -> str:
@@ -98,14 +99,17 @@ 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 str_to_bool(val: str) -> bool:
+    """Returns false if val is None instead of raising ValueError (Sanic's implementation)."""
+    return sanic_str_to_bool(val) if val else False
+
+
+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.
 

sanic_security/verification.py

@@ -264,7 +264,4 @@ def requires_captcha(arg=None):
 
         return wrapper
 
-    if callable(arg):
-        return decorator(arg)
-    else:
-        return decorator
+    return decorator(arg) if callable(arg) else decorator