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

{sanic_security-1.15.2.dist-info → sanic_security-1.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: sanic-security
-Version: 1.15.2
+Version: 1.16.0
 Summary: An async security library for the Sanic framework.
 Author-email: Aidan Stewart <me@na-stewart.com>
 Project-URL: Documentation, https://security.na-stewart.com/
@@ -17,11 +17,12 @@ License-File: LICENSE
 Requires-Dist: tortoise-orm>=0.17.0
 Requires-Dist: pyjwt>=1.7.0
 Requires-Dist: captcha>=0.4
-Requires-Dist: pillow>=9.5.0
 Requires-Dist: argon2-cffi>=20.1.0
 Requires-Dist: sanic>=21.3.0
+Provides-Extra: oauth
+Requires-Dist: httpx-oauth>=0.16.1; extra == "oauth"
 Provides-Extra: dev
-Requires-Dist: httpx; extra == "dev"
+Requires-Dist: httpx-oauth; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: blacken-docs; extra == "dev"
 Requires-Dist: pdoc3; extra == "dev"
@@ -62,6 +63,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
   * [Installation](#installation)
   * [Configuration](#configuration)
 * [Usage](#usage)
+    * [OAuth](#oauth)
     * [Authentication](#authentication)
     * [CAPTCHA](#captcha)
     * [Two-step Verification](#two-step-verification)
@@ -79,6 +81,7 @@ Requires-Dist: cryptography>=3.3.1; extra == "crypto"
 Sanic Security is an authentication, authorization, and verification library designed for use with the 
 [Sanic](https://github.com/huge-success/sanic) framework.
 
+* OAuth2 integration
 * Login, registration, and authentication with refresh mechanisms
 * Role based authorization with wildcard permissions
 * Image & audio CAPTCHA
@@ -102,7 +105,7 @@ pip3 install sanic-security
 
 * Install the Sanic Security pip package with the `cryptography` dependency included.
 
-If you are planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use 
+If you're planning on encoding or decoding JWTs using certain digital signature algorithms (like RSA or ECDSA which use 
 the public secret and private secret), you will need to install the `cryptography` library. This can be installed explicitly, or 
 as an extra requirement.
 
@@ -110,7 +113,17 @@ as an extra requirement.
 pip3 install sanic-security[crypto]
 ````
 
-* Update sanic-security if already installed.
+* Install the Sanic Security pip package with the `httpx-oauth` dependency included.
+
+If you're planning on utilizing OAuth, you will need to install the `httpx-oauth` library. This can be installed explicitly, or 
+as an extra requirement.
+
+```shell
+pip3 install sanic-security[oauth]
+````
+
+* Update Sanic Security if already installed.
+
 ```shell
 pip3 install sanic-security --upgrade
 ```
@@ -138,41 +151,119 @@ You can load environment variables with a different prefix via `config.load_envi
 
 * Default configuration values:
 
-| Key                                   | Value                        | Description                                                                                                                      |
-|---------------------------------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
-| **SECRET**                            | This is a big secret. Shhhhh | The secret used for generating and signing JWTs. This should be a string unique to your application. Keep it safe.               |
-| **PUBLIC_SECRET**                     | None                         | The secret used for verifying and decoding JWTs and can be publicly shared. This should be a string unique to your application.  |
-| **SESSION_SAMESITE**                  | Strict                       | The SameSite attribute of session cookies.                                                                                       |
-| **SESSION_SECURE**                    | True                         | The Secure attribute of session cookies.                                                                                         |
-| **SESSION_HTTPONLY**                  | True                         | The HttpOnly attribute of session cookies. HIGHLY recommended that you do not turn this off, unless you know what you are doing. |
-| **SESSION_DOMAIN**                    | None                         | The Domain attribute of session cookies.                                                                                         |
-| **SESSION_ENCODING_ALGORITHM**        | HS256                        | The algorithm used to encode and decode session JWT's.                                                                           |
-| **SESSION_PREFIX**                    | tkn                          | Prefix attached to the beginning of session cookies.                                                                             |
-| **MAX_CHALLENGE_ATTEMPTS**            | 3                            | The maximum amount of session challenge attempts allowed.                                                                        |
-| **CAPTCHA_SESSION_EXPIRATION**        | 180                          | The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.                         |
-| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation. Several fonts can be used by separating them via comma.             |
-| **CAPTCHA_VOICE**                     | captcha-voice/               | The directory of the voice library being used for audio captcha generation.                                                      |
-| **TWO_STEP_SESSION_EXPIRATION**       | 300                          | The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.                        |
-| **AUTHENTICATION_SESSION_EXPIRATION** | 86400                        | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                  |
-| **AUTHENTICATION_REFRESH_EXPIRATION** | 604800                       | The amount of seconds till authentication refresh expiration. Setting to 0 will disable refresh mechanism.                       |
-| **ALLOW_LOGIN_WITH_USERNAME**         | False                        | Allows login via username; unique constraint is disabled when set to false.                                                      |
-| **INITIAL_ADMIN_EMAIL**               | admin@example.com            | Email used when creating the initial admin account.                                                                              |
-| **INITIAL_ADMIN_PASSWORD**            | admin123                     | Password used when creating the initial admin account.                                                                           |
+| Key                                   | Value                        | Description                                                                                                                       |
+|---------------------------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| **SECRET**                            | This is a big secret. Shhhhh | The secret used for generating and signing JWTs. This should be a string unique to your application. Keep it safe.                |
+| **PUBLIC_SECRET**                     | None                         | The secret used for verifying and decoding JWTs and can be publicly shared. This should be a string unique to your application.   |
+| **OAUTH_CLIENT**                      | None                         | The client ID provided by the OAuth provider, this is used to identify the application making the OAuth request.                  |
+| **OAUTH_SECRET**                      | None                         | The client secret provided by the OAuth provider, this is used in conjunction with the client ID to authenticate the application. |
+| **SESSION_SAMESITE**                  | Strict                       | The SameSite attribute of session cookies.                                                                                        |
+| **SESSION_SECURE**                    | True                         | The Secure attribute of session cookies.                                                                                          |
+| **SESSION_HTTPONLY**                  | True                         | The HttpOnly attribute of session cookies. HIGHLY recommended that you do not turn this off, unless you know what you are doing.  |
+| **SESSION_DOMAIN**                    | None                         | The Domain attribute of session cookies.                                                                                          |
+| **SESSION_ENCODING_ALGORITHM**        | HS256                        | The algorithm used to encode and decode session JWT's.                                                                            |
+| **SESSION_PREFIX**                    | tkn                          | Prefix attached to the beginning of session cookies.                                                                              |
+| **MAX_CHALLENGE_ATTEMPTS**            | 3                            | The maximum amount of session challenge attempts allowed.                                                                         |
+| **CAPTCHA_SESSION_EXPIRATION**        | 180                          | The amount of seconds till captcha session expiration on creation. Setting to 0 will disable expiration.                          |
+| **CAPTCHA_FONT**                      | captcha-font.ttf             | The file path to the font being used for captcha generation. Several fonts can be used by separating them via comma.              |
+| **CAPTCHA_VOICE**                     | captcha-voice/               | The directory of the voice library being used for audio captcha generation.                                                       |
+| **TWO_STEP_SESSION_EXPIRATION**       | 300                          | The amount of seconds till two-step session expiration on creation. Setting to 0 will disable expiration.                         |
+| **AUTHENTICATION_SESSION_EXPIRATION** | 86400                        | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                   |
+| **AUTHENTICATION_REFRESH_EXPIRATION** | 604800                       | The amount of seconds till authentication refresh expiration. Setting to 0 will disable refresh mechanism.                        |
+| **ALLOW_LOGIN_WITH_USERNAME**         | False                        | Allows login via username; unique constraint is disabled when set to false.                                                       |
+| **INITIAL_ADMIN_EMAIL**               | admin@example.com            | Email used when creating the initial admin account.                                                                               |
+| **INITIAL_ADMIN_PASSWORD**            | admin123                     | Password used when creating the initial admin account.                                                                            |
 
 ## Usage
 
 Sanic Security's authentication and verification functionality is session based. A new session will be created for the user after the user logs in or requests some form of verification (two-step, captcha). The session data is then encoded into a JWT and stored on a cookie on the user’s browser. The session cookie is then sent
 along with every subsequent request. The server can then compare the session stored on the cookie against the session information stored in the database to verify user’s identity and send a response with the corresponding state.
 
-* Initialize sanic-security as follows:
+* Initialize Sanic Security as follows:
 ```python
 initialize_security(app)
+initialize_oauth(app)  # Remove if not utilizing OAuth
 if __name__ == "__main__":
     app.run(host="127.0.0.1", port=8000, workers=1, debug=True)
 ```
 
 The tables in the below examples represent example [request form-data](https://sanicframework.org/en/guide/basics/request.html#form).
 
+## OAuth
+
+OAuth2 provides users with a familiar experience by having them register/login using their existing credentials from other trusted services (such as Google, Discord, etc.).
+
+This feature is designed to complement existing authentication protocols by linking a Sanic Security account with the user's OAuth credentials. As a result, developers can leverage all of Sanic Security's capabilities including robust session handling and account management.
+
+* Define OAuth clients
+
+You can [utilize various OAuth clients](https://frankie567.github.io/httpx-oauth/reference/httpx_oauth.clients/) based on your needs or [customize one](https://frankie567.github.io/httpx-oauth/usage/).
+ID and secret should be stored and referenced via configuration.
+
+```python
+discord_oauth = DiscordOAuth2(
+    "1325594509043830895",
+    "WNMYbkDJjGlC0ej60qM-50tC9mMy0EXa",
+)
+google_oauth = GoogleOAuth2(
+    "480512993828-e2e9tqtl2b8or62hc4l7hpoh478s3ni1.apps.googleusercontent.com",
+    "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",
+)
+```
+
+* Redirect to authorization URL
+
+```python
+@app.route("api/security/oauth", methods=["GET", "POST"])
+async def on_oauth_request(request):
+    return redirect(
+        await oauth_url(
+            google_oauth, "http://localhost:8000/api/security/oauth/callback"
+        )
+    )
+```
+
+* Handle OAuth callback
+
+```python
+@app.get("api/security/oauth/callback")
+async def on_oauth_callback(request):
+    token_info, authentication_session = await oauth_callback(
+        request, google_oauth, "http://localhost:8000/api/security/oauth/callback"
+    )
+    response = json(
+        "Authorization successful.",
+        {"token_info": token_info, "auth_session": authentication_session.json},
+    )
+    oauth_encode(response, token_info)
+    authentication_session.encode(response)
+    return response
+```
+
+* Get access token 
+
+```python
+@app.get("api/security/oauth/token")
+async def on_oauth_token(request):
+    token_info = await decode_oauth(request, google_oauth)
+    return json(
+        "Access token retrieved.",
+        token_info,
+    )
+```
+
+* Requires access token (This method is not called directly and instead used as a decorator)
+
+```python
+@app.get("api/security/oauth/token")
+@requires_oauth(google_oauth)
+async def on_oauth_token(request):
+    return json(
+        "Access token retrieved.",
+        request.ctx.oauth,
+    )
+```
+
 ## Authentication
   
 * Registration (With two-step account verification)
@@ -324,7 +415,9 @@ or you can download/create your own and specify its path in the configuration.
 @app.get("api/security/captcha")
 async def on_captcha_img_request(request):
     captcha_session = await request_captcha(request)
-    response = captcha_session.get_image()  # Captcha: LJ0F3U
+    response = raw(
+        captcha_session.get_image(), content_type="image/jpeg"
+    )  # Captcha: LJ0F3U
     captcha_session.encode(response)
     return response
 ```
@@ -334,8 +427,12 @@ async def on_captcha_img_request(request):
 ```python
 @app.get("api/security/captcha/audio")
 async def on_captcha_audio_request(request):
-    captcha_session = await CaptchaSession.decode(request)
-    return captcha_session.get_audio()  # Captcha: LJ0F3U
+    captcha_session = await request_captcha(request)
+    response = raw(
+        captcha_session.get_audio(), content_type="audio/mpeg"
+    )  # Captcha: LJ0F3U
+    captcha_session.encode(response)
+    return response
 ```
 
 * Attempt CAPTCHA
@@ -366,7 +463,7 @@ async def on_captcha(request):
 
 ## Two-step Verification
 
-Two-step verification should be integrated with other custom functionalities, such as account verification during registration.
+Two-step verification should be integrated with other custom functionalities, such as forgot password recovery.
 
 * Request Two-step Verification
 
@@ -447,8 +544,10 @@ Wildcard permissions support the concept of multiple levels or parts. For exampl
 await assign_role(
     "Chat Room Moderator",
     account,
-    "channels:view,delete, voice:*, account:suspend,mute",
     "Can read and delete messages in all chat rooms, suspend and mute accounts, and control voice chat.",
+    "channels:view,delete",
+    "voice:*",
+    "account:suspend,mute",
 )
 ```
 
@@ -467,7 +566,7 @@ async def on_check_perms(request):
 
 ```python
 @app.post("api/security/perms")
-@require_permissions("channels:view", "voice:*")
+@requires_permission("channels:view", "voice:*")
 async def on_check_perms(request):
     return text("Account is authorized.")
 ```
@@ -485,7 +584,7 @@ async def on_check_roles(request):
 
 ```python
 @app.post("api/security/roles")
-@require_roles("Chat Room Moderator")
+@requires_role("Chat Room Moderator")
 async def on_check_roles(request):
     return text("Account is authorized.")
 ```
@@ -582,16 +681,3 @@ Distributed under the MIT License. See `LICENSE` for more information.
 * PATCH version when you make backwards compatible bug fixes.
 
 [https://semver.org/](https://semver.org/)
-
-<!-- MARKDOWN LINKS & IMAGES -->
-<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
-[contributors-shield]: https://img.shields.io/github/contributors/sunset-developer/sanic-security.svg?style=flat-square
-[contributors-url]: https://github.com/sunset-developer/sanic-security/graphs/contributors
-[forks-shield]: https://img.shields.io/github/forks/sunset-developer/sanic-security.svg?style=flat-square
-[forks-url]: https://github.com/sunset-developer/sanic-security/network/members
-[stars-shield]: https://img.shields.io/github/stars/sunset-developer/sanic-security.svg?style=flat-square
-[stars-url]: https://github.com/sunset-developer/sanic-security/stargazers
-[issues-shield]: https://img.shields.io/github/issues/sunset-developer/sanic-security.svg?style=flat-square
-[issues-url]: https://github.com/sunset-developer/sanic-security/issues
-[license-shield]: https://img.shields.io/github/license/sunset-developer/sanic-security.svg?style=flat-square
-[license-url]: https://github.com/sunset-developer/sanic-security/blob/master/LICENSE

sanic_security-1.16.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sanic_security/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sanic_security/authentication.py,sha256=dogkcRsZH81WqKMqvwnDXN44ANCOuZsuuTGeo3di0c4,12985
+sanic_security/authorization.py,sha256=ssq58w4vLv4YsNt40ufxHVyCeNzVDby3UcOYOEeTnI4,8428
+sanic_security/configuration.py,sha256=2kWC4CZXvWR1wtBaqkMl58IA0VzxhI2ZbBTqd7LS_fE,6305
+sanic_security/exceptions.py,sha256=RCYrDUgczwH_Uz2A__z1zCc8iKKbt2YSBdNTQUaMykc,5381
+sanic_security/models.py,sha256=Ote83cdLUTpNWOMaY1uM04yDmst5_DamPEMFcSSmdks,22161
+sanic_security/oauth.py,sha256=Wnd-jqC3uIi-fi4cV15_gmhXTi2FyuY9NAwKG5FxLr8,8398
+sanic_security/utils.py,sha256=WlPOEEQGcfZk-GbPNu6OiysNXAo9mw80TitDV7XxWMc,3762
+sanic_security/verification.py,sha256=0pBoGBVGsyTFNLHI0lyz640Y1f8fnKjLjA8zHzXutqM,8660
+sanic_security/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sanic_security/test/server.py,sha256=opZGmoLuNZgZR2WHzu5WnWecniRnUu-nheqQsrhau5I,13313
+sanic_security/test/tests.py,sha256=h6v3N1YhvENNA0eC-RqJK1sqGe2gFeKAMPJu7hjceqc,22570
+sanic_security-1.16.0.dist-info/LICENSE,sha256=sXlJs9_mG-dCkPfWsDnuzydJWagS82E2gYtkVH9enHA,1100
+sanic_security-1.16.0.dist-info/METADATA,sha256=d9uGtSKHAiUtmZev-_kjjfTYWCcAKQ1s4RchCUPWPBc,25648
+sanic_security-1.16.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+sanic_security-1.16.0.dist-info/top_level.txt,sha256=ZybkhHXSjfzhmv8XeqLvnNmLmv21Z0oPX6Ep4DJN8b0,15
+sanic_security-1.16.0.dist-info/RECORD,,

{sanic_security-1.15.2.dist-info → sanic_security-1.16.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

sanic_security-1.15.2.dist-info/RECORD

@@ -1,16 +0,0 @@
-sanic_security/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sanic_security/authentication.py,sha256=3Pit1B4PN_MRvwAlhYPHl_6DGD9JVpdPjgjiyKQJanM,13145
-sanic_security/authorization.py,sha256=jAxfDT9cHN_zpMKcA3oYFZ5Eu2KItnMJZ7oPcqmMwrw,7537
-sanic_security/configuration.py,sha256=_E66ts5g9t_XHW9ZAnr48rWVcZmGNu_DWGDxm_AVVWE,5681
-sanic_security/exceptions.py,sha256=9zISLyAvP6qN8sNR8e5qxKP__FA4NLIXCun_fEKndOw,5297
-sanic_security/models.py,sha256=1gMoPnzA9cpJaZXJ1GtgAzsXxGO-rts-f3YyVgcd7lY,22475
-sanic_security/utils.py,sha256=Il5MjFzVe975yx_CV2HV_LVQYl2W3XYDRGtCG5CQA8Q,3531
-sanic_security/verification.py,sha256=9bi8-NZ8GE3rcuELZ63yh18zDg8RxvxGPkhAu5SzLn0,8692
-sanic_security/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sanic_security/test/server.py,sha256=RjL9Kfvkfqpm5TXWwFQKKa0J4hfTKgwI6U0s_TAKO8w,11984
-sanic_security/test/tests.py,sha256=bW5fHJfsCrg8eBmcSqVMLm0R5XRL1ou-XJJRgz09GOE,21993
-sanic_security-1.15.2.dist-info/LICENSE,sha256=sXlJs9_mG-dCkPfWsDnuzydJWagS82E2gYtkVH9enHA,1100
-sanic_security-1.15.2.dist-info/METADATA,sha256=PNjYIu36zcUqehxfO0Zg7X98CwHSzGbPc1FYXsXo7qs,23247
-sanic_security-1.15.2.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-sanic_security-1.15.2.dist-info/top_level.txt,sha256=ZybkhHXSjfzhmv8XeqLvnNmLmv21Z0oPX6Ep4DJN8b0,15
-sanic_security-1.15.2.dist-info/RECORD,,