Metadata-Version: 2.4
Name: baobab-auth-api
Version: 0.9.0
Summary: API FastAPI d'authentification pour l'écosystème Baobab.
Project-URL: Homepage, https://github.com/baobabgit/baobab-auth-api
Project-URL: Repository, https://github.com/baobabgit/baobab-auth-api
Project-URL: Issues, https://github.com/baobabgit/baobab-auth-api/issues
Author: Patrick 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: api,authentication,baobab,fastapi,jwks,jwt
Classifier: Framework :: FastAPI
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: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: baobab-auth-core<1.0.0,>=0.9.0
Requires-Dist: baobab-auth-security<1.0.0,>=0.9.0
Requires-Dist: email-validator>=2.0
Requires-Dist: fastapi>=0.110
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: database
Requires-Dist: baobab-auth-database<1.0.0,>=0.1.0; extra == 'database'
Provides-Extra: dev
Requires-Dist: bandit[sarif,toml]>=1.7; 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.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; 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-api

[![CI](https://github.com/baobabgit/baobab-auth-api/actions/workflows/ci.yml/badge.svg)](https://github.com/baobabgit/baobab-auth-api/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/baobab-auth-api.svg)](https://pypi.org/project/baobab-auth-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/baobab-auth-api.svg)](https://pypi.org/project/baobab-auth-api/)
[![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/)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)

> API FastAPI d'authentification pour l'écosystème Baobab.
> Expose register, login, refresh, logout, me, JWKS, rôles et permissions.

## Table des matières

- [À propos](#à-propos)
- [Positionnement](#positionnement)
- [Fonctionnalités](#fonctionnalités)
- [Stack technique](#stack-technique)
- [Installation](#installation)
- [Configuration](#configuration)
- [Lancement](#lancement)
- [Endpoints](#endpoints)
- [Exemples](#exemples)
- [Sécurité](#sécurité)
- [Contribuer](#contribuer)
- [Licence](#licence)
- [Auteur](#auteur)

## À propos

`baobab-auth-api` est la brique HTTP du système d'authentification Baobab.
Elle orchestre `baobab-auth-core`, `baobab-auth-database` et `baobab-auth-security`
pour exposer une API FastAPI complète : création de compte, connexion, gestion des
sessions avec refresh token, exposition JWKS, rôles et permissions.

La librairie expose une factory `create_app()` et peut être lancée directement avec
`uvicorn`. Elle ne porte aucune logique métier applicative (Riftbound, Altered, etc.) :
son rôle est strictement l'authentification.

## Positionnement

```text
baobab-auth-core      → entités métier, ports, exceptions
baobab-auth-database  → ORM, repositories, unit of work, migrations
baobab-auth-security  → hash, JWT, JWKS, refresh token, rotation de clés
baobab-auth-api       → API FastAPI  ← CE DÉPÔT
baobab-auth-client    → client Python pour les consommateurs
baobab-auth-service   → assemblage Docker complet
```

## Fonctionnalités

- **Création de compte** : `POST /auth/register`
- **Connexion** : `POST /auth/login` → JWT + refresh token opaque
- **Rafraîchissement** : `POST /auth/refresh` avec rotation obligatoire du refresh token
- **Déconnexion** : `POST /auth/logout` → révocation de session
- **Utilisateur courant** : `GET /auth/me`
- **JWKS** : `GET /auth/jwks` → clés publiques RSA pour validation hors-ligne
- **Rôles** : `GET /auth/roles`
- **Permissions** : `GET /auth/permissions`
- **Santé** : `GET /health` et `GET /ready`

## Stack technique

| Domaine       | Outil                                       |
|---------------|---------------------------------------------|
| Langage       | Python ≥ 3.12                               |
| Core métier   | `baobab-auth-core` ≥ 0.9.0                  |
| Sécurité      | `baobab-auth-security` ≥ 0.9.0              |
| Persistance   | `baobab-auth-database` (extra `[database]`) |
| Framework     | FastAPI + Pydantic v2                       |
| Configuration | pydantic-settings                           |
| Serveur       | uvicorn                                     |
| Lint/format   | ruff                                        |
| Types         | mypy strict                                 |
| Tests         | pytest + pytest-asyncio + httpx             |
| Sécurité SAST | bandit + pip-audit                          |
| CI            | GitHub Actions                              |

## Installation

```bash
# Cloner le dépôt
git clone https://github.com/baobabgit/baobab-auth-api.git
cd baobab-auth-api

# Créer l'environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Windows : .venv\Scripts\activate

# Installer les dépendances internes baobab-auth (depuis leurs dépôts locaux)
pip install -e ../baobab-auth-core
pip install -e ../baobab-auth-database
pip install -e ../baobab-auth-security

# Installer baobab-auth-api en mode développement
pip install -e ".[dev,docs]"
```

## Configuration

Copiez `.env.example` en `.env` et renseignez les variables :

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

Variables obligatoires :

```env
BAOBAB_AUTH_DATABASE_URL=postgresql+asyncpg://auth:auth@localhost:5432/auth
```

Variables avec valeurs par défaut :

```env
BAOBAB_AUTH_ISSUER=baobab-auth
BAOBAB_AUTH_AUDIENCE=baobab-api
BAOBAB_AUTH_ACCESS_TOKEN_TTL_SECONDS=900
BAOBAB_AUTH_REFRESH_TOKEN_TTL_SECONDS=2592000
BAOBAB_AUTH_JWT_ALGORITHM=RS256
BAOBAB_AUTH_PASSWORD_MIN_LENGTH=12
BAOBAB_AUTH_LOG_LEVEL=INFO
```

## Lancement

```bash
uvicorn baobab_auth_api.main:app --host 0.0.0.0 --port 8000
```

La documentation OpenAPI est accessible à : `http://localhost:8000/docs`

## Endpoints

| Méthode | URL                  | Auth requise | Description                    |
|---------|----------------------|--------------|--------------------------------|
| POST    | /auth/register       | Non          | Créer un compte                |
| POST    | /auth/login          | Non          | Connexion, obtenir les tokens  |
| POST    | /auth/refresh        | Non          | Rafraîchir les tokens          |
| POST    | /auth/logout         | Bearer       | Déconnexion, révoquer session  |
| GET     | /auth/me             | Bearer       | Utilisateur courant            |
| GET     | /auth/jwks           | Non          | Clés publiques JWKS            |
| GET     | /auth/roles          | Non          | Catalogue des rôles            |
| GET     | /auth/permissions    | Non          | Catalogue des permissions      |
| GET     | /health              | Non          | Liveness probe                 |
| GET     | /ready               | Non          | Readiness probe                |

## Exemples

### Créer un compte

```bash
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "MyStr0ngP@ssword!", "username": "patrick"}'
```

### Se connecter

```bash
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "MyStr0ngP@ssword!"}'
```

Réponse :

```json
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rt_opaque_token",
  "token_type": "bearer",
  "expires_in": 900
}
```

### Récupérer les clés JWKS (pour valider les JWT côté client)

```bash
curl http://localhost:8000/auth/jwks
```

## Sécurité

- Les mots de passe ne sont jamais stockés en clair ni dans les logs.
- Les refresh tokens ne sont stockés que sous forme hashée.
- La rotation du refresh token est obligatoire à chaque `/auth/refresh`.
- Les JWT sont signés avec une clé RSA gérée par `baobab-auth-security`.
- Le `kid` est obligatoire dans l'en-tête JWT pour la validation JWKS.
- Les erreurs de login ne distinguent pas email inconnu et mot de passe invalide.
- Aucun secret ne figure dans les logs ni dans les réponses d'erreur.

Pour les recommandations de déploiement en production, voir [`docs/security.md`](docs/security.md).

## Contribuer

Voir [`CONTRIBUTING.md`](CONTRIBUTING.md) et [`AGENTS.md`](AGENTS.md) pour les règles de développement.

```bash
make check  # lint + types + tests
```

## Licence

MIT — voir [`LICENSE`](LICENSE).

## Auteur

Patrick ANDRIANAIVO
