Metadata-Version: 2.4
Name: baobab-auth-security
Version: 0.1.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://github.com/baobabgit/baobab-auth-security/tree/main/docs
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.4.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: mypy>=1.11; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=3.8; 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'
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)
[![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/)
[![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)

> 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 stricte (RS256, claims, `kid`).
- 🔄 **Refresh tokens** : génération opaque, hash avant stockage.
- 🔑 **Clés** : génération RSA, chargement PEM, rotation, statuts de clé.
- 📜 **JWKS** : document public sans clés privées, résolution par `kid`.
- 🚫 **Révocation** : port abstrait + implémentation mémoire pour les tests.
- 🧩 **Intégration core** : adaptateurs vers les ports `baobab-auth-core`.
- ✅ **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.4.0             |
| Crypto         | `cryptography`, `argon2-cffi`, `PyJWT` |
| 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 et JWKS
│   ├── revocation/             # Révocation abstraite
│   ├── 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
```

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

## 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`            | Taille des clés RSA                         |
| `RefreshTokenSettings`   | Longueur et pepper des refresh tokens       |

## 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).
- [ ] Publication PyPI `0.1.0` — pré-release [`v0.1.0rc1`](https://github.com/baobabgit/baobab-auth-security/releases/tag/v0.1.0rc1) (build OK ; Trusted Publishing PyPI à configurer).
- [ ] Publier la documentation (Read the Docs).

## 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)
