solving-auth-middleware 0.3.0

Reusable middleware for jwt checking with modular validators and role hierarchy

🔐 Auth Middleware - Sécurisation de Microservices Flask

Middleware Flask modulaire et flexible pour sécuriser vos microservices avec JWT, gestion de rôles hiérarchiques, permissions et audit (RGPD/HDS).

✨ Nouveautés v3 (0.2.0)

🎉 Système de validators modulaires - Composez vos règles de validation de manière flexible
🎉 Nouveau rôle SOFTWARE_ADMIN - Hiérarchie de rôles étendue
🎉 Validators combinables - Logique AND/OR pour des règles complexes
🎉 Helpers rapides - Fonctions utilitaires pour les cas courants
🎉 100% rétrocompatible - Toutes les versions précédentes restent fonctionnelles

➡️ Guide complet v3 | Migration depuis v1/v2

---

📦 Installation

pip install solving-auth-middleware

Ou depuis les sources :

git clone https://github.com/yourusername/auth-middleware.git
cd auth-middleware
pip install -e .

---

🚀 Démarrage Rapide

Configuration de base

from flask import Flask
from flask_jwt_extended import JWTManager
from solving_auth_middleware import requires_access, quick_user_type_check, UserTypeEnum

app = Flask(__name__)
app.config['JWT_SECRET_KEY'] = 'votre-clé-secrète'
jwt = JWTManager(app)

@app.route('/api/admin')
@requires_access(quick_user_type_check(UserTypeEnum.SOFTWARE_ADMIN))
def admin_route():
    return {"message": "Zone administrateur"}

if __name__ == '__main__':
    app.run()

Exemple avec permissions

from solving_auth_middleware import (
    requires_access,
    UserTypeValidator,
    PermissionsValidator,
    UserTypeEnum
)

@app.route('/api/documents', methods=['POST'])
@requires_access([
    UserTypeValidator([UserTypeEnum.PRO, UserTypeEnum.SOFTWARE_ADMIN]),
    PermissionsValidator(['create_documents'], mode='all')
])
def create_document():
    return {"message": "Document créé"}

---

🎯 Fonctionnalités Principales

🔑 Authentification JWT

• Support de flask-jwt-extended
• Validation automatique des tokens
• Gestion des tokens frais (fresh=True)
• Multiples locations : headers, cookies, query string, JSON

👥 Hiérarchie de Rôles

SYSTEM (niveau 4)          → Accès système complet
    ↓
SOFTWARE_ADMIN (niveau 3)  → Administration logiciel
    ↓
USER_ADMIN (niveau 2)      → Gestion des utilisateurs
    ↓
PRO (niveau 1)             → Utilisateur professionnel
    ↓
PUBLIC (niveau 0)          → Utilisateur public

🛡️ Validators Modulaires (v3)

Validator	Description
UserTypeValidator	Valide le type d'utilisateur
PermissionsValidator	Vérifie les permissions (AND/OR)
RoleHierarchyValidator	Validation basée sur la hiérarchie
CustomFunctionValidator	Logique personnalisée
ClaimValidator	Validation de claims JWT
ResourceOwnerValidator	Vérification de propriété
RemoteAPIValidator	Validation via API externe
CompositeValidator	Combine plusieurs validators

📊 Exemples d'Utilisation

Validation simple

@requires_access(quick_user_type_check(UserTypeEnum.PRO))
def pro_route():
    return {"status": "ok"}

Validation avec hiérarchie

# Accepte USER_ADMIN, SOFTWARE_ADMIN et SYSTEM
@requires_access(quick_role_hierarchy_check(UserTypeEnum.USER_ADMIN))
def admin_and_above():
    return {"status": "ok"}

Validation complexe (OR logique)

from solving_auth_middleware import CompositeValidator

@requires_access(
    CompositeValidator([
        # Admin OU
        UserTypeValidator([UserTypeEnum.SOFTWARE_ADMIN]),
        # PRO avec permission spéciale
        CompositeValidator([
            UserTypeValidator([UserTypeEnum.PRO]),
            PermissionsValidator(['special_access'])
        ], mode='all')
    ], mode='any')
)
def flexible_route():
    return {"status": "ok"}

Validation de propriété

def load_document(doc_id):
    return Document.query.get(doc_id)

@requires_access(
    ResourceOwnerValidator(load_document, owner_field='owner_id')
)
def delete_document(doc_id):
    return {"status": "deleted"}

---

⚙️ Configuration

Variables d'environnement

Créez un fichier .env :

# Configuration JWT
JWT_SECRET_KEY=votre-clé-secrète-super-sécurisée

# Endpoints API de validation par type d'utilisateur
PUBLIC_USER_API_ENDPOINT=http://api.example.com/v1/public/verify
PRO_USER_API_ENDPOINT=http://api.example.com/v1/pro/verify
USER_ADMIN_API_ENDPOINT=http://api.example.com/v1/user-admin/verify
SOFTWARE_ADMIN_API_ENDPOINT=http://api.example.com/v1/software-admin/verify
SYSTEM_API_ENDPOINT=http://api.example.com/v1/system/verify

# Configuration
PERMISSIONS_API_TIMEOUT=10
AUDIT_ENABLED=True
AUDIT_LOG_PATH=/var/log/audit.log

Configuration Flask

from solving_auth_middleware import Config

class CustomConfig(Config):
    JWT_SECRET_KEY = 'votre-clé'
    SOFTWARE_ADMIN_API_ENDPOINT = 'http://api.example.com/v1/software-admin/verify'
    PERMISSIONS_API_TIMEOUT = 10

app.config.from_object(CustomConfig)

---

📚 Documentation

• Guide v3 Complet - Documentation détaillée de la v3
• Guide de Migration - Migrer depuis v1/v2
• Changelog - Historique des versions
• Exemples - Exemples d'utilisation pratiques

---

🧪 Tests et Développement

Lancer les exemples

# Exemple v3 avec tous les validators
python examples/example_v3.py

# Exemple original (v1)
python examples/example.py

Structure du Projet

auth-middleware/
├── solving_auth_middleware/
│   ├── __init__.py           # Exports publics
│   ├── config.py             # Configuration
│   ├── enums.py              # Énumérations (UserTypeEnum)
│   ├── middleware.py         # Middleware v1 (original)
│   ├── middleware_v2.py      # Middleware v2
│   ├── middleware_v3.py      # Middleware v3 (nouveau)
│   └── validators.py         # Système de validators modulaires
├── examples/
│   ├── example.py            # Exemples v1
│   └── example_v3.py         # Exemples v3 complets
├── GUIDE_V3.md              # Documentation v3
├── MIGRATION_V3.md          # Guide de migration
├── CHANGELOG.md             # Historique des versions
└── README.md                # Ce fichier

---

🔄 Versions du Middleware

Version	Décorateur	Description	Status
v1	@requires_permissions()	Version originale	✅ Stable
v2	@requires_permissions_v2()	Version intermédiaire	✅ Stable
v3	@requires_access()	Validators modulaires	✅ Recommandé

Toutes les versions sont 100% compatibles et peuvent coexister dans le même projet.

---

🤝 Contribution

Les contributions sont les bienvenues !

1. Fork le projet
2. Créez une branche (git checkout -b feature/amélioration)
3. Commit vos changements (git commit -m 'Ajout d'une fonctionnalité')
4. Push vers la branche (git push origin feature/amélioration)
5. Ouvrez une Pull Request

Créer votre propre Validator

from solving_auth_middleware.validators import AccessValidator

class MyCustomValidator(AccessValidator):
    def __init__(self, my_param):
        self.my_param = my_param
    
    def validate(self, jwt_data, identity, token, **context):
        # Votre logique ici
        if condition:
            return True, None
        return False, "Message d'erreur"

---

📦 Publication d'une Mise à Jour

Option 1 : Script automatique

./publish.sh

Option 2 : Manuelle

# 1. Mettre à jour la version dans pyproject.toml et __init__.py

# 2. Commit et tag
git add .
git commit -m "Release version 0.2.0"
git tag -a v0.2.0 -m "Release version 0.2.0"

# 3. Push
git push origin main
git push origin v0.2.0

# 4. Build et publish
python -m build
python -m twine upload dist/*

---

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

🙏 Remerciements

• Flask - Framework web
• Flask-JWT-Extended - Gestion JWT
• Tous les contributeurs du projet

---

📞 Support

• 📖 Documentation
• 💬 Issues GitHub
• 📧 Email: [e-mail]

---

Fait avec ❤️ pour la communauté Flask