core-auth#

This project/library contains common elements related to authentication & authorization…

Python Versions License Pipeline Status Docs Status Security

Documentation Contents#

Index:

Features#

  • JWT Token Wrapper - Simplified interface for JSON Web Token operations

  • Multiple Cryptographic Algorithms - Support for HMAC (HS256, HS384, HS512), RSA (RS256, RS384, RS512, PS256, PS384, PS512), ECDSA (ES256, ES256K, ES384, ES512), and EdDSA algorithms

  • Token Encoding - Create JWT tokens with customizable claims, headers, and expiration times

  • Token Decoding & Validation - Decode and verify JWT tokens with comprehensive validation options (signature, expiration, audience, issuer, etc.)

  • Authorization Header Parsing - Extract Bearer tokens from HTTP Authorization headers

  • Public/Private Key Support - Compatible with RSA, Elliptic Curve (EC), Ed25519, and Ed448 key pairs

  • Custom Claims - Add standardized or custom claims to JWT payloads

  • Type-Safe - Full type hints support for better IDE integration and code safety

Quick Start#

from core_auth import JwtToken, JwtException, ALGORITHM

# HMAC (symmetric)
client = JwtToken(private_key="S3cr3t", expire=3600)
token = client.encode(subject="user-123", claims={"iss": "my-service"})

payload = client.decode(token, issuer="my-service")
print(payload["sub"])  # "user-123"

# Asymmetric (RSA, ECDSA, EdDSA) — keys loaded from PEM files
private_pem = open("tests/resources/private.pem").read()
public_pem = open("tests/resources/public.pem").read()
client = JwtToken(private_key=private_pem, public_key=public_pem)
token = client.encode(subject="user-123", algorithm=ALGORITHM.RS256)
payload = client.decode(token, algorithms=[ALGORITHM.RS256])
print(payload["sub"])

# Parse an HTTP Authorization header
raw_token = JwtToken.from_auth_header("Bearer eyJ...")

# Handle errors
try:
    client.decode("invalid.token")
except JwtException as exc:
    print(exc)  # "Invalid token."

See the JWT Token page for the full API reference and more examples.

Installation#

Install from PyPI using pip:

pip install core-auth
uv pip install core-auth    # Or using UV...
pip install -e ".[dev]"     # For development...

Setting Up Environment#

  1. Install required libraries:

pip install --upgrade pip
pip install virtualenv

  1. Create Python virtual environment:

virtualenv --python=python3.12 .venv

  1. Activate the virtual environment:

source .venv/bin/activate

Install packages#

pip install .
pip install -e ".[dev]"

Check tests and coverage#

python manager.py run-tests
python manager.py run-coverage

Contributing#

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Write tests for new functionality

  4. Ensure all tests pass: pytest -n auto

  5. Run linting: pylint core_auth

  6. Run security checks: bandit -r core_auth

  7. Submit a pull request

License#

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

Support#

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors#