Metadata-Version: 2.4
Name: baobab-auth-security
Version: 0.2.0
Summary: Librairie Python de sécurité pour l'écosystème baobab-auth (hash, JWT, JWKS, clés, refresh tokens).
Project-URL: Homepage, https://github.com/baobabgit/baobab-auth-security
Project-URL: Repository, https://github.com/baobabgit/baobab-auth-security
Project-URL: Documentation, https://baobabgit.github.io/baobab-auth-security/
Project-URL: Issues, https://github.com/baobabgit/baobab-auth-security/issues
Author: Michel ANDRIANAIVO
License: MIT License
        
        Copyright (c) 2026 Michel ANDRIANAIVO
        
        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.
License-File: LICENSE
Keywords: argon2,authentication,baobab-auth,jwks,jwt,password,security
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: baobab-auth-core<1.0.0,>=0.9.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: bandit[sarif,toml]>=1.7; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: remote-jwks
Requires-Dist: httpx>=0.27; extra == 'remote-jwks'
Description-Content-Type: text/markdown

# baobab-auth-security

[![CI](https://github.com/baobabgit/baobab-auth-security/actions/workflows/ci.yml/badge.svg)](https://github.com/baobabgit/baobab-auth-security/actions/workflows/ci.yml)
[![Docs](https://github.com/baobabgit/baobab-auth-security/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/baobabgit/baobab-auth-security/actions/workflows/docs-pages.yml)
[![codecov](https://codecov.io/gh/baobabgit/baobab-auth-security/branch/main/graph/badge.svg)](https://codecov.io/gh/baobabgit/baobab-auth-security)
[![PyPI version](https://img.shields.io/pypi/v/baobab-auth-security.svg)](https://pypi.org/project/baobab-auth-security/)
[![Python versions](https://img.shields.io/pypi/pyversions/baobab-auth-security.svg)](https://pypi.org/project/baobab-auth-security/)
[![GitHub release](https://img.shields.io/github/v/release/baobabgit/baobab-auth-security)](https://github.com/baobabgit/baobab-auth-security/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
[![Documentation](https://img.shields.io/badge/documentation-GitHub%20Pages-0366d6?logo=github)](https://baobabgit.github.io/baobab-auth-security/)

> Librairie Python de sécurité pour l'écosystème **baobab-auth** : hash de mots de passe,
> JWT, JWKS, clés cryptographiques, refresh tokens opaques et révocation abstraite.

## Table des matières

- [À propos](#à-propos)
- [Fonctionnalités](#fonctionnalités)
- [Stack technique](#stack-technique)
- [Architecture](#architecture)
- [Structure du projet](#structure-du-projet)
- [Démarrage rapide](#démarrage-rapide)
- [Configuration](#configuration)
- [Sécurité](#sécurité)
- [Contribuer](#contribuer)
- [Et après ?](#et-après-)
- [Licence](#licence)
- [Remerciements](#remerciements)
- [Auteur](#auteur)

## À propos

`baobab-auth-security` est la brique de **sécurité technique** de l'écosystème
`baobab-auth`. Elle centralise les mécanismes cryptographiques nécessaires à
l'authentification, sans couplage HTTP (FastAPI), sans ORM ni persistance directe.

La librairie s'intègre avec [`baobab-auth-core`](https://pypi.org/project/baobab-auth-core/)
via des ports et adaptateurs, et peut être utilisée seule dans un script Python,
un service d'authentification, une API métier ou un client de validation de tokens.

## Fonctionnalités

- 🔐 **Mots de passe** : hash Argon2id, vérification, détection de rehash.
- 🪪 **JWT** : génération et validation (RS256 par défaut, ES256/EdDSA optionnels).
- 🌐 **JWKS distant** : fetch HTTP, cache TTL, validation async (`remote-jwks`).
- 🔄 **Refresh tokens** : génération opaque, hash avant stockage.
- 🔑 **Clés** : génération RSA/EC/Ed25519, chargement PEM, rotation, statuts de clé.
- 📜 **JWKS** : document public RSA/EC/OKP sans clés privées.
- 🚫 **Révocation** : port abstrait, store enrichi (token/session/sujet/clé), composite.
- 🧩 **Intégration core** : adaptateurs vers les ports `baobab-auth-core` 0.9.x.
- ✅ **Qualité** : typage strict, couverture ≥ 90 %, CI complète.

## Stack technique

| Domaine        | Outil / librairie                      |
| -------------- | -------------------------------------- |
| Langage        | Python ≥ 3.12 (requis par `baobab-auth-core`) |
| Core métier    | `baobab-auth-core` ≥ 0.9.0             |
| Crypto         | `cryptography`, `argon2-cffi`, `PyJWT` |
| JWKS distant   | `httpx` (extra `remote-jwks`)          |
| Config         | `pydantic`, `pydantic-settings`        |
| Lint & types   | `ruff`, `mypy` (strict)                |
| Tests          | `pytest`, `pytest-cov` (≥ 90 %)        |
| Documentation  | Sphinx + Furo (RST)                    |
| CI             | GitHub Actions, `pre-commit`           |

## Architecture

Briques de l'écosystème `baobab-auth` :

```text
baobab-auth-core       → règles métier, entités, ports, exceptions métier
baobab-auth-database   → persistance (utilisateurs, sessions, clés, audit)
baobab-auth-security   → hash, JWT, JWKS, clés, refresh tokens, révocation
baobab-auth-api        → routes HTTP, orchestration applicative
baobab-auth-client     → validation de tokens dans les applications consommatrices
```

Traçabilité besoin → code :

```text
Cahier des charges → US-XXX → FEAT-XXX.Y → TASK-XXX.Y.Z → src/ + tests/
```

## Structure du projet

```text
.
├── src/baobab_auth_security/   # Code (1 classe = 1 fichier)
│   ├── password/               # Hash et vérification de mots de passe
│   ├── tokens/                 # JWT
│   ├── refresh_tokens/         # Refresh tokens opaques
│   ├── keys/                   # Clés, JWKS, rotation
│   ├── algorithms/             # Politique d'algorithmes JWT
│   ├── jwks_remote/            # JWKS distant et cache (extra remote-jwks)
│   ├── revocation/             # Révocation abstraite et enrichie
│   ├── config/                 # Configuration typée
│   └── integration/            # Adaptateurs baobab-auth-core
├── tests/baobab_auth_security/ # Tests en miroir de src/
├── docs/                       # Sphinx : specifications, API, guides
├── examples/                   # Scripts exécutables (voir guides how-to)
└── pyproject.toml              # Config unique du projet
```

## Démarrage rapide

```bash
# 1. Cloner
git clone https://github.com/baobabgit/baobab-auth-security.git
cd baobab-auth-security

# 2. Environnement virtuel
python -m venv .venv
# Windows : .venv\Scripts\Activate.ps1   |   Linux/macOS : source .venv/bin/activate

# 3. Installer + hooks
pip install -e ".[dev,docs]"
pre-commit install

# 4. Vérifier
ruff check . && mypy && pytest      # ou : make check
```

Import minimal :

```python
from baobab_auth_security import VERSION, BaobabAuthSecurityError

print(VERSION)
```

Exemples exécutables (après installation) :

```bash
python examples/verify_password.py
python examples/generate_token.py
python examples/validate_token.py
python examples/generate_jwks.py
python examples/rotate_key.py
python examples/jwt_algorithms.py
python examples/revocation_enriched.py
```

Guides détaillés : [`docs/guides/how-to/`](docs/guides/how-to/) (architecture, JWT,
algorithmes, JWKS local et distant, rotation, révocation enrichie).

## Configuration

La configuration passe par des **objets typés** (`pydantic-settings`) injectés
par l'application hôte. Copiez le modèle d'environnement :

```bash
cp .env.example .env
```

| Variable    | Description                      | Défaut        |
| ----------- | -------------------------------- | ------------- |
| `APP_ENV`   | Environnement applicatif         | `development` |
| `LOG_LEVEL` | Niveau de journalisation         | `INFO`        |

Classes de configuration security (injection par l'hôte) :

| Classe                   | Usage                                       |
| ------------------------ | ------------------------------------------- |
| `JwtSecuritySettings`    | Issuer, audience, TTL access token, horloge |
| `KeySettings`            | Clés RSA, JWKS distant, cache TTL           |
| `RevocationSettings`     | Portées de révocation JWT (jti/sid/sub/kid) |
| `SecuritySettings`       | Agrégateur password / JWT / clés / révocation |
| `RefreshTokenSettings`   | Longueur et pepper des refresh tokens       |

Extra optionnel : `pip install "baobab-auth-security[remote-jwks]"` pour la
validation JWT via JWKS HTTP distant.

## Sécurité

- **Aucun secret** dans le code ni dans Git : `.env` gitignoré, `.env.example` versionné.
- La librairie ne journalise jamais mots de passe, refresh tokens, clés privées
  ni tokens d'accès complets.
- Analyse `bandit` (SAST) + `pip-audit` (vulnérabilités) + Dependabot.
- Signalez toute vulnérabilité en privé (voir [`SECURITY.md`](SECURITY.md)).

## Contribuer

Règles de développement dans [`AGENTS.md`](AGENTS.md), processus dans
[`CONTRIBUTING.md`](CONTRIBUTING.md) et [`docs/workflow/`](docs/workflow/).
Branche `feat/<ID>-slug`, Conventional Commits avec ID spec, PR verte.

## Et après ?

- [x] Dépôt initialisé depuis le template multi-IA.
- [x] Cahier des charges déposé et découpé en US/FEAT.
- [x] US-002 à US-010 implémentées (password, JWT, clés, révocation, core, docs).
- [x] US-011 — intégration `baobab-auth-core` 0.9.0 ([`0.9.0`](https://pypi.org/project/baobab-auth-security/)).
- [x] US-012 — extension v0.2.0 : JWKS distant, ES256/EdDSA, révocation enrichie.
- [ ] Publication PyPI [`0.2.0`](https://pypi.org/project/baobab-auth-security/) après merge et tag `v0.2.0`.
- [x] Documentation ([GitHub Pages](https://baobabgit.github.io/baobab-auth-security/)).

## Licence

Distribué sous licence **MIT**. Voir [`LICENSE`](LICENSE).

## Remerciements

Écosystème `baobab-auth`, `baobab-auth-core`, et les outils Python open source
(cryptography, PyJWT, argon2-cffi, Ruff, mypy, pytest, Sphinx).

## Auteur

**Michel ANDRIANAIVO** — [patrick.andri@gmail.com](mailto:patrick.andri@gmail.com)
