sanic-security 1.11.6__tar.gz → 1.12.0__tar.gz

sanic_security-1.12.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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.

sanic_security-1.11.6/README.md → sanic_security-1.12.0/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.1
+Name: sanic-security
+Version: 1.12.0
+Summary: An effective, simple, and async security library for the Sanic framework.
+Author-email: Aidan Stewart <na.stewart365@gmail.com>
+Project-URL: Documentation, https://security.na-stewart.com/
+Project-URL: Repository, https://github.com/na-stewart/sanic-security
+Keywords: security,authentication,authorization,verification,async,sanic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+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: dev
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: blacken-docs; extra == "dev"
+Requires-Dist: pdoc3; extra == "dev"
+Requires-Dist: cryptography; extra == "dev"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=3.3.1; extra == "crypto"
+
 <!-- PROJECT SHIELDS -->
 <!--
 *** I'm using markdown "reference style" links for readability.
@@ -8,7 +39,7 @@
 -->
 
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Downloads](https://pepy.tech/badge/sanic-security)](https://pepy.tech/project/sanic-security)
+[![Downloads](https://static.pepy.tech/badge/sanic-security)](https://pepy.tech/project/sanic-security)
 [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/sanic-security.svg)](https://anaconda.org/conda-forge/sanic-security)
 
 
@@ -48,15 +79,13 @@
 Sanic Security is an authentication, authorization, and verification library designed for use with [Sanic](https://github.com/huge-success/sanic).
 This library contains a variety of features including:
 
-* Login, registration, and authentication
+* Login, registration, and authentication with refresh mechanisms
 * Two-factor authentication
 * Captcha
 * Two-step verification
 * Role based authorization with wildcard permissions
 
-Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation,
-
-and check out [blog.na-stewart.com](https://github.com/na-stewart/Aidans-Page) for an example implementation.
+Please visit [security.na-stewart.com](https://security.na-stewart.com) for documentation and [click here for a comprehensive implementation guide](https://blog.na-stewart.com/entry?id=3).
 
 <!-- GETTING STARTED -->
 ## Getting Started
@@ -126,15 +155,16 @@ You can load environment variables with a different prefix via calling the `conf
 | **MAX_CHALLENGE_ATTEMPTS**            | 5                            | The maximum amount of session challenge attempts allowed.                                                                        |
 | **CAPTCHA_SESSION_EXPIRATION**        | 60                           | 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.                                                                     |
-| **TWO_STEP_SESSION_EXPIRATION**       | 200                          | The amount of seconds till two step session expiration on creation. Setting to 0 will disable expiration.                        |
-| **AUTHENTICATION_SESSION_EXPIRATION** | 2692000                      | The amount of seconds till authentication session expiration on creation. Setting to 0 will disable expiration.                  |
+| **TWO_STEP_SESSION_EXPIRATION**       | 200                          | 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** | 2592000                      | The amount of seconds till authentication refresh expiration.                                                                    |
 | **ALLOW_LOGIN_WITH_USERNAME**         | False                        | Allows login via username and email.                                                                                             |
 | **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 would be sent
+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.
 
 The tables in the below examples represent example [request form-data](https://sanicframework.org/en/guide/basics/request.html#form).
@@ -168,11 +198,11 @@ async def on_register(request):
     account = await register(request)
     two_step_session = await request_two_step_verification(request, account)
     await email_code(
-        account.email, two_step_session.code  # Code = AJ8HGD
+        account.email, two_step_session.code  # Code = 197251
     )  # Custom method for emailing verification code.
     response = json(
         "Registration successful! Email verification required.",
-        two_step_session.bearer.json,
+        two_step_session.json,
     )
     two_step_session.encode(response)
     return response
@@ -190,9 +220,7 @@ Verifies the client's account via two-step session code.
 @app.post("api/security/verify")
 async def on_verify(request):
     two_step_session = await verify_account(request)
-    return json(
-        "You have verified your account and may login!", two_step_session.bearer.json
-    )
+    return json("You have verified your account and may login!", two_step_session.json)
 ```
 
 * Login (With Two-factor Authentication)
@@ -211,11 +239,11 @@ async def on_login(request):
         request, authentication_session.bearer
     )
     await email_code(
-        authentication_session.bearer.email, two_step_session.code  # Code = BG5KLP
+        authentication_session.bearer.email, two_step_session.code  # Code = 197251
     )  # Custom method for emailing verification code.
     response = json(
         "Login successful! Two-factor authentication required.",
-        authentication_session.bearer.json,
+        authentication_session.json,
     )
     authentication_session.encode(response)
     two_step_session.encode(response)
@@ -231,12 +259,27 @@ Fulfills client authentication session's second factor requirement via two-step
 | **code** | BG5KLP |
 
 ```python
-@app.post("api/security/validate-2fa")
+@app.post("api/security/fulfill-2fa")
 async def on_two_factor_authentication(request):
     authentication_session = await fulfill_second_factor(request)
     response = json(
         "Authentication session second-factor fulfilled! You are now authenticated.",
-        authentication_session.bearer.json,
+        authentication_session.json,
+    )
+    authentication_session.encode(response)
+    return response
+```
+
+* Anonymous Login
+
+Simply create a new session and encode it.
+
+```python
+@app.post("api/security/login/anon")
+async def on_anonymous_login(request):
+    authentication_session = await AuthenticationSession.new(request)
+    response = json(
+        "Anonymous client now associated with session!", authentication_session.json
     )
     authentication_session.encode(response)
     return response
@@ -248,32 +291,42 @@ async def on_two_factor_authentication(request):
 @app.post("api/security/logout")
 async def on_logout(request):
     authentication_session = await logout(request)
-    response = json("Logout successful!", authentication_session.bearer.json)
-    return response
+    return json("Logout successful!", authentication_session.json)
 ```
 
 * Authenticate
 
+New/Refreshed session automatically returned if expired during authentication, requires encoding.
+
 ```python
 @app.post("api/security/auth")
 async def on_authenticate(request):
     authentication_session = await authenticate(request)
-    return json(
+    response = json(
         "You have been authenticated.",
-        authentication_session.bearer.json,
+        authentication_session.json,
     )
+    if authentication_session.is_refresh:
+        authentication_session.encode(response)
+    return response
 ```
 
 * Requires Authentication (This method is not called directly and instead used as a decorator.)
 
+New/Refreshed session automatically returned if expired during authentication, requires encoding.
+
 ```python
 @app.post("api/security/auth")
 @requires_authentication
 async def on_authenticate(request):
-    return json(
+    authentication_session = request.ctx.authentication_session.json
+    response = json(
         "You have been authenticated.",
-        request.ctx.authentication_session.bearer.json,
+        authentication_session.json,
     )
+    if authentication_session.is_refresh:
+        authentication_session.encode(response)
+    return response
 ```
 
 ## Captcha
@@ -285,10 +338,6 @@ downloading a .ttf font and defining the file's path in the configuration.
 
 [Recommended Font](https://www.1001fonts.com/source-sans-pro-font.html)
 
-Captcha challenge example:
-
-[![Captcha image.](https://github.com/na-stewart/sanic-security/blob/main/images/captcha.png?raw=true)](https://github.com/na-stewart/sanic-security/blob/main/images/captcha.png?raw=true)
-
 * Request Captcha
 
 ```python
@@ -320,7 +369,7 @@ async def on_captcha(request):
 | **captcha** | FV9NMQ |
 
 ```python
-@app.post("ap/security/captcha")
+@app.post("api/security/captcha")
 @requires_captcha
 async def on_captcha(request):
     return json("Captcha attempt successful!", request.ctx.captcha_session.json)
@@ -341,12 +390,12 @@ Two-step verification should be integrated with other custom functionality. For
 async def on_two_step_request(request):
     two_step_session = await request_two_step_verification(request)
     await email_code(
-        account.email, two_step_session.code  # Code = DT6JZX
+        two_step_session.bearer.email, two_step_session.code  # Code = 197251
     )  # Custom method for emailing verification code.
-    response = json("Verification request successful!", two_step_session.bearer.json)
+    response = json("Verification request successful!", two_step_session.json)
     two_step_session.encode(response)
     return response
-```
+``` 
 
 * Resend Two-step Verification Code
 
@@ -355,9 +404,9 @@ async def on_two_step_request(request):
 async def on_two_step_resend(request):
     two_step_session = await TwoStepSession.decode(request)
     await email_code(
-        account.email, two_step_session.code  # Code = DT6JZX
+        two_step_session.bearer.email, two_step_session.code  # Code = 197251
     )  # Custom method for emailing verification code.
-    return json("Verification code resend successful!", two_step_session.bearer.json)
+    return json("Verification code resend successful!", two_step_session.json)
 ```
 
 * Two-step Verification
@@ -370,9 +419,7 @@ async def on_two_step_resend(request):
 @app.post("api/security/two-step")
 async def on_two_step_verification(request):
     two_step_session = await two_step_verification(request)
-    response = json(
-        "Two-step verification attempt successful!", two_step_session.bearer.json
-    )
+    response = json("Two-step verification attempt successful!", two_step_session.json)
     return response
 ```
 
@@ -388,7 +435,7 @@ async def on_two_step_verification(request):
 async def on_two_step_verification(request):
     response = json(
         "Two-step verification attempt successful!",
-        request.ctx.two_step_session.bearer.json,
+        request.ctx.two_step_session.json,
     )
     return response
 ```
@@ -532,7 +579,7 @@ Contributions are what make the open source community such an amazing place to b
 <!-- LICENSE -->
 ## License
 
-Distributed under the GNU Affero General Public License v3.0. See `LICENSE` for more information.
+Distributed under the MIT License. See `LICENSE` for more information.
 
 <!-- Versioning -->
 ## Versioning