sanic-security 1.11.7__tar.gz → 1.12.1__tar.gz

sanic_security-1.12.1/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.7/README.md → sanic_security-1.12.1/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.1
+Name: sanic-security
+Version: 1.12.1
+Summary: An 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)
 
 
@@ -17,7 +48,7 @@
 <p align="center">
   <h3 align="center">Sanic Security</h3>
   <p align="center">
-   An effective, simple, and async security library for the Sanic framework.
+   An async security library for the Sanic framework.
   </p>
 </p>
 
@@ -46,17 +77,14 @@
 ## About The Project
 
 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 [here for an implementation guide](https://blog.na-stewart.com/entry?id=3).
 
 <!-- GETTING STARTED -->
 ## Getting Started
@@ -74,7 +102,7 @@ pip3 install sanic-security
 
 If you are 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 a required extra in the `sanic-security` requirement.
+as an extra requirement.
 
 ```shell
 pip3 install sanic-security[crypto]
@@ -109,7 +137,7 @@ You can also use the update() method like on regular dictionaries.
 Any environment variables defined with the SANIC_SECURITY_ prefix will be applied to the config. For example, setting 
 SANIC_SECURITY_SECRET will be loaded by the application automatically and fed into the SECRET config variable.
 
-You can load environment variables with a different prefix via calling the `config.load_environment_variables("NEW_PREFIX_")` method.
+You can load environment variables with a different prefix via `config.load_environment_variables("NEW_PREFIX_")` method.
 
 * Default configuration values:
 
@@ -126,15 +154,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).
@@ -151,7 +180,7 @@ This account can be logged into and has complete authoritative access. Login cre
       app.run(host="127.0.0.1", port=8000)
   ```
   
-* Registration (With Two-step Verification)
+* Registration (With two-step account verification)
 
 Phone can be null or empty.
 
@@ -168,11 +197,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
@@ -184,18 +213,16 @@ Verifies the client's account via two-step session code.
 
 | Key      | Value  |
 |----------|--------|
-| **code** | AJ8HGD |
+| **code** | 197251 |
 
 ```python
 @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)
+* Login (With two-factor authentication)
 
 Login credentials are retrieved via the Authorization header. Credentials are constructed by first combining the 
 username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string in base64 
@@ -211,11 +238,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)
@@ -228,15 +255,30 @@ Fulfills client authentication session's second factor requirement via two-step
 
 | Key      | Value  |
 |----------|--------|
-| **code** | BG5KLP |
+| **code** | 197251 |
 
 ```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 +290,57 @@ 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 will be returned if expired, 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.)
+* Requires Authentication (This method is not called directly and instead used as a decorator)
+
+New/Refreshed session will be returned if expired, requires encoding.
 
 ```python
 @app.post("api/security/auth")
 @requires_authentication
 async def on_authenticate(request):
-    return json(
+    authentication_session = request.ctx.authentication_session
+    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
+```
+
+* Authentication Refresh Middleware
+
+If it's inconvenient to encode the refreshed session during authentication, it can also be done automatically via middleware.
+
+```python
+@app.on_response
+async def authentication_refresh_encoder(request, response):
+    try:
+        authentication_session = request.ctx.authentication_session
+        if authentication_session.is_refresh:
+            authentication_session.encode(response)
+    except AttributeError:
+        pass
 ```
 
 ## Captcha
@@ -285,17 +352,13 @@ 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
 @app.get("api/security/captcha")
 async def on_captcha_img_request(request):
     captcha_session = await request_captcha(request)
-    response = captcha_session.get_image()  # Captcha: FV9NMQ
+    response = captcha_session.get_image()  # Captcha: 192731
     captcha_session.encode(response)
     return response
 ```
@@ -304,7 +367,7 @@ async def on_captcha_img_request(request):
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```python
 @app.post("api/security/captcha")
@@ -313,14 +376,14 @@ async def on_captcha(request):
     return json("Captcha attempt successful!", captcha_session.json)
 ```
 
-* Requires Captcha (This method is not called directly and instead used as a decorator.)
+* Requires Captcha (This method is not called directly and instead used as a decorator)
 
 | Key         | Value  |
 |-------------|--------|
-| **captcha** | FV9NMQ |
+| **captcha** | 192731 |
 
 ```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)
@@ -339,48 +402,46 @@ Two-step verification should be integrated with other custom functionality. For
 ```python
 @app.post("api/security/two-step/request")
 async def on_two_step_request(request):
-    two_step_session = await request_two_step_verification(request)
+    two_step_session = await request_two_step_verification(request)  # Code = 197251
     await email_code(
-        account.email, two_step_session.code  # Code = DT6JZX
+        two_step_session.bearer.email, two_step_session.code
     )  # 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
 
 ```python
 @app.post("api/security/two-step/resend")
 async def on_two_step_resend(request):
-    two_step_session = await TwoStepSession.decode(request)
+    two_step_session = await TwoStepSession.decode(request)  # Code = 197251
     await email_code(
-        account.email, two_step_session.code  # Code = DT6JZX
+        two_step_session.bearer.email, two_step_session.code
     )  # 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
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @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
 ```
 
-* Requires Two-step Verification (This method is not called directly and instead used as a decorator.)
+* Requires Two-step Verification (This method is not called directly and instead used as a decorator)
 
 | Key      | Value  |
 |----------|--------|
-| **code** | DT6JZX |
+| **code** | 197251 |
 
 ```python
 @app.post("api/security/two-step")
@@ -388,7 +449,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
 ```
@@ -445,7 +506,7 @@ async def on_check_roles(request):
     return text("Account is authorized.")
 ```
 
-* Require Roles (This method is not called directly and instead used as a decorator.)
+* Require Roles (This method is not called directly and instead used as a decorator)
 
 ```python
 @app.post("api/security/roles")
@@ -532,7 +593,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