butterfly-jwt 0.2.0

A lightweight, pure Python JWT implementation

Your updated README.md for the Butterfly JWT library looks good and includes concise, clear instructions for installation, usage, and features. Here’s the enhanced content you can use:

# Butterfly JWT

Butterfly JWT is a lightweight, pure Python library for handling JSON Web Tokens (JWT) efficiently and securely, with a focus on ease of integration and high security standards. This library is designed to work without any external dependencies, making it an excellent choice for projects requiring minimal setup.

## Installation

To install Butterfly JWT, simply run the following command in your terminal:

```bash
pip install butterfly-jwt

Usage

Encoding a Token

To encode a new JWT, provide a secret key and payload. Optionally, specify the email for encryption and set the development mode:

from butterfly import jwt

# Create a token
secret_key = "your_secret_key"
payload = {"user_id": 123, "username": "example_user"}
email = "[e-mail]"
token = jwt.encode(secret_key, payload, email=email)

Decoding a Token

To decode and verify a JWT, use the decode function. This function will check the token's validity, signature, and expiration:

from butterfly import jwt

try:
    payload = jwt.decode(secret_key, token)
    print("Token is valid. Payload:", payload)
except ValueError as e:
    print("Token verification failed:", str(e))

Using the ButterflyJWT Class

For more detailed control, you can directly use the ButterflyJWT class:

from butterfly.jwt import ButterflyJWT

# Create a JWT instance
jwt_handler = ButterflyJWT(secret_key)

# Create a token
token = jwt_handler.create_token(payload, email="[e-mail]")

# Verify and decode a token
try:
    payload = jwt_handler.verify_token(token)
    print("Token is valid. Payload:", payload)
except ValueError as e:
    print("Token verification failed:", str(e))

Features

• Pure Python implementation: Ensures compatibility and easy deployment.
• No external dependencies: Ideal for environments with strict dependency requirements.
• URL-safe Base64 encoding: Securely encodes tokens to be URL-friendly.
• HMAC-SHA256 signature: Provides a robust mechanism for verifying token integrity.
• Token expiration checking: Automatically verifies token expiry to maintain security.
• Constant-time signature verification: Prevents timing attacks on token signatures.

License

This project is licensed under the MIT License - see the LICENSE file for details.

This version enhances clarity on the library’s features, provides detailed code examples for both encoding and decoding tokens, and includes an example of handling email encryption within the token. It should be quite helpful for users of your library!