baobab-auth-api 0.9.0__py3-none-any.whl

baobab_auth_api/__init__.py

@@ -0,0 +1,13 @@
+"""Package baobab_auth_api — API FastAPI d'authentification pour l'écosystème Baobab.
+
+Expose la factory ``create_app()`` et la classe de configuration ``AuthApiSettings``
+comme contrat public du package.
+
+:spec: CDC § 21.2
+:origin: docs/specifications/cahier-des-charges/cahier_des_charges.md
+"""
+
+from baobab_auth_api.app import AppFactory
+from baobab_auth_api.config import AuthApiSettings
+
+__all__: list[str] = ["AppFactory", "AuthApiSettings"]

baobab_auth_api/app.py

@@ -0,0 +1,79 @@
+"""Factory de l'application FastAPI baobab-auth-api.
+
+:spec: FEAT-002.2 FEAT-008.1
+:origin: docs/specifications/us/US-002-configuration/FEAT-002.2-create-app.rst
+"""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+
+from baobab_auth_api.config import AuthApiSettings
+from baobab_auth_api.error_handlers import ErrorHandlerRegistry
+from baobab_auth_api.lifespan import Lifespan
+from baobab_auth_api.openapi import OpenApiMetadata
+from baobab_auth_api.routers.health import HealthRouter
+
+
+class AppFactory:
+    """Factory statique qui instancie et configure l'application FastAPI.
+
+    Compose ``OpenApiMetadata``, ``Lifespan``, ``ErrorHandlerRegistry``
+    et les routers. Accepte un ``settings`` optionnel pour l'injection
+    en tests.
+
+    :spec: FEAT-002.2
+    """
+
+    @staticmethod
+    def create(settings: AuthApiSettings | None = None) -> FastAPI:
+        """Crée et retourne une instance FastAPI complètement configurée.
+
+        :param settings: Configuration injectée. Si ``None``, charge
+            ``AuthApiSettings()`` depuis les variables d'environnement.
+        :returns: Instance ``FastAPI`` prête à être servie.
+        """
+        if settings is None:
+            settings = AuthApiSettings()  # type: ignore[call-arg]
+
+        meta = OpenApiMetadata()
+
+        app = FastAPI(
+            title=meta.title,
+            version=meta.version,
+            description=meta.description,
+            contact=meta.contact,
+            license_info=meta.license_info,
+            lifespan=Lifespan.handler,
+        )
+
+        if settings.cors_origins:
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=settings.cors_origins,
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+            )
+
+        if settings.trusted_hosts:
+            app.add_middleware(TrustedHostMiddleware, allowed_hosts=settings.trusted_hosts)
+
+        ErrorHandlerRegistry.register(app)
+
+        AppFactory._include_routers(app)
+
+        return app
+
+    @staticmethod
+    def _include_routers(app: FastAPI) -> None:
+        """Inclut les routers de l'application.
+
+        :param app: Instance FastAPI sur laquelle inclure les routers.
+        """
+        from fastapi import APIRouter
+
+        router_auth = APIRouter(prefix="/auth", tags=["auth"])
+        app.include_router(router_auth)
+
+        app.include_router(HealthRouter.create())

baobab_auth_api/config.py

@@ -0,0 +1,113 @@
+"""Configuration injectée de l'API d'authentification Baobab.
+
+:spec: FEAT-002.1 FEAT-009.1
+:origin: docs/specifications/us/US-002-configuration/FEAT-002.1-auth-api-settings.rst
+"""
+
+from typing import Literal
+
+from pydantic import field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_SUPPORTED_JWT_ALGORITHMS: frozenset[str] = frozenset(
+    {"RS256", "RS384", "RS512", "ES256", "ES384", "ES512"}
+)
+
+
+class AuthApiSettings(BaseSettings):
+    """Configuration de l'API FastAPI d'authentification Baobab.
+
+    Toutes les valeurs sont injectées par variables d'environnement
+    préfixées ``BAOBAB_AUTH_`` ou par fichier ``.env``.
+    Aucun secret ne figure dans le code source.
+
+    :spec: FEAT-002.1
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="BAOBAB_AUTH_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    database_url: str
+    issuer: str = "baobab-auth"
+    audience: str = "baobab-api"
+    access_token_ttl_seconds: int = 900
+    refresh_token_ttl_seconds: int = 2_592_000
+    jwt_algorithm: str = "RS256"
+    password_min_length: int = 12
+    log_level: str = "INFO"
+    cors_origins: list[str] = []
+    trusted_hosts: list[str] = []
+    """Liste des hôtes autorisés pour TrustedHostMiddleware (vide = désactivé)."""
+
+    environment: Literal["development", "staging", "production"] = "production"
+
+    @field_validator("database_url", mode="after")
+    @classmethod
+    def database_url_non_vide(cls, v: str) -> str:
+        """Vérifie que l'URL de base de données n'est pas vide.
+
+        :param v: Valeur du champ ``database_url``.
+        :returns: La valeur inchangée si valide.
+        :raises ValueError: Si l'URL est vide ou ne contient que des espaces.
+        :spec: FEAT-002.1 critère 2
+        """
+        if not v.strip():
+            raise ValueError("database_url ne peut pas être vide")
+        return v
+
+    @field_validator("access_token_ttl_seconds", "refresh_token_ttl_seconds", mode="after")
+    @classmethod
+    def ttl_strictement_positif(cls, v: int) -> int:
+        """Vérifie que les TTL sont strictement positifs.
+
+        :param v: Valeur du TTL en secondes.
+        :returns: La valeur inchangée si valide.
+        :raises ValueError: Si le TTL est inférieur ou égal à zéro.
+        :spec: FEAT-002.1 critère 3
+        """
+        if v <= 0:
+            raise ValueError("Le TTL doit être strictement positif")
+        return v
+
+    @field_validator("jwt_algorithm", mode="after")
+    @classmethod
+    def algo_jwt_supporte(cls, v: str) -> str:
+        """Vérifie que l'algorithme JWT est dans la liste blanche asymétrique.
+
+        Seuls les algorithmes asymétriques (RSA, EC) sont autorisés.
+        Les algorithmes HMAC (HS256, etc.) sont refusés.
+
+        :param v: Nom de l'algorithme JWT.
+        :returns: La valeur inchangée si valide.
+        :raises ValueError: Si l'algorithme n'est pas supporté.
+        :spec: FEAT-002.1 critère 4
+        """
+        if v not in _SUPPORTED_JWT_ALGORITHMS:
+            raise ValueError(
+                f"Algorithme JWT non supporté : '{v}'. "
+                f"Algorithmes autorisés : {sorted(_SUPPORTED_JWT_ALGORITHMS)}"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def cors_wildcard_production_interdit(self) -> "AuthApiSettings":
+        """Refuse le CORS wildcard en environnement de production.
+
+        Un wildcard ``"*"`` dans ``cors_origins`` est acceptable en développement
+        mais constitue une faille de sécurité en production.
+
+        :returns: L'instance validée.
+        :raises ValueError: Si ``"*"`` est présent dans ``cors_origins``
+            et que l'environnement est ``"production"``.
+        :spec: FEAT-002.1 critère 5
+        """
+        if self.environment == "production" and "*" in self.cors_origins:
+            raise ValueError(
+                "CORS wildcard ('*') interdit en environnement 'production'. "
+                "Définir des origines explicites dans BAOBAB_AUTH_CORS_ORIGINS."
+            )
+        return self

baobab_auth_api/error_handlers.py

@@ -0,0 +1,123 @@
+"""Handlers d'erreurs HTTP pour l'application FastAPI baobab-auth-api.
+
+:spec: FEAT-002.2
+:origin: docs/specifications/us/US-002-configuration/FEAT-002.2-create-app.rst
+"""
+
+import logging
+
+from baobab_auth_core.exceptions.base import BaobabAuthCoreError
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from baobab_auth_api.integration.core_exception_http_mapper import CoreExceptionHttpMapper
+
+logger = logging.getLogger(__name__)
+_CORE_MAPPER = CoreExceptionHttpMapper()
+
+
+class ErrorHandlerRegistry:
+    """Enregistreur centralisé des handlers d'erreurs HTTP sur FastAPI.
+
+    Expose une méthode de classe ``register`` qui branche tous les handlers
+    sur l'instance FastAPI fournie. Aucun secret ni stack trace ne transite
+    dans les réponses d'erreur.
+
+    :spec: FEAT-002.2
+    """
+
+    @classmethod
+    def register(cls, app: FastAPI) -> None:
+        """Enregistre tous les handlers d'erreurs sur l'application FastAPI.
+
+        :param app: Instance FastAPI sur laquelle brancher les handlers.
+        :returns: None
+        """
+        app.add_exception_handler(
+            RequestValidationError,
+            cls._handle_validation_error,  # type: ignore[arg-type]
+        )
+        app.add_exception_handler(
+            HTTPException,
+            cls._handle_http_exception,  # type: ignore[arg-type]
+        )
+        app.add_exception_handler(
+            BaobabAuthCoreError,
+            cls._handle_core_exception,  # type: ignore[arg-type]
+        )
+        app.add_exception_handler(
+            Exception,
+            cls._handle_generic_exception,
+        )
+
+    @staticmethod
+    async def _handle_validation_error(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        """Handler pour les erreurs de validation Pydantic (422).
+
+        :param request: Requête HTTP entrante.
+        :param exc: Exception de validation levée.
+        :returns: Réponse JSON structurée avec le détail des erreurs.
+        """
+        return JSONResponse(
+            status_code=422,
+            content={
+                "error": "validation_error",
+                "detail": exc.errors(),
+            },
+        )
+
+    @staticmethod
+    async def _handle_http_exception(request: Request, exc: HTTPException) -> JSONResponse:
+        """Handler pour les HTTPException FastAPI.
+
+        :param request: Requête HTTP entrante.
+        :param exc: HTTPException levée.
+        :returns: Réponse JSON uniforme.
+        """
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": "http_error",
+                "detail": exc.detail,
+            },
+        )
+
+    @staticmethod
+    async def _handle_core_exception(
+        request: Request,
+        exc: BaobabAuthCoreError,
+    ) -> JSONResponse:
+        """Handler pour les exceptions métier ``baobab-auth-core``.
+
+        :param request: Requête HTTP entrante.
+        :param exc: Exception core levée par un use case.
+        :returns: Réponse JSON ``{"error": {"code", "message"}}``.
+        """
+        _ = request
+        status, code, message = _CORE_MAPPER.resolve(exc)
+        return JSONResponse(
+            status_code=status,
+            content={"error": {"code": code, "message": message}},
+        )
+
+    @staticmethod
+    async def _handle_generic_exception(request: Request, exc: Exception) -> JSONResponse:
+        """Handler fallback pour toute exception non anticipée (500).
+
+        Ne retourne aucune information interne pour éviter les fuites.
+
+        :param request: Requête HTTP entrante.
+        :param exc: Exception non gérée.
+        :returns: Réponse JSON générique 500.
+        """
+        logger.exception("Erreur interne non anticipée : %s", type(exc).__name__)
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "internal_server_error",
+                "detail": "Une erreur interne s'est produite.",
+            },
+        )

baobab_auth_api/exceptions/__init__.py

@@ -0,0 +1,26 @@
+"""Exceptions métier de baobab-auth-api.
+
+:spec: FEAT-004
+"""
+
+from baobab_auth_api.exceptions.auth import (
+    AccountDisabledError,
+    ExpiredTokenError,
+    InvalidCredentialsError,
+    InvalidTokenError,
+    SessionRevokedError,
+)
+from baobab_auth_api.exceptions.registration import (
+    EmailAlreadyExistsError,
+    WeakPasswordError,
+)
+
+__all__ = [
+    "AccountDisabledError",
+    "EmailAlreadyExistsError",
+    "ExpiredTokenError",
+    "InvalidCredentialsError",
+    "InvalidTokenError",
+    "SessionRevokedError",
+    "WeakPasswordError",
+]

baobab_auth_api/exceptions/auth.py

@@ -0,0 +1,71 @@
+"""Exceptions d'authentification et de session.
+
+:spec: FEAT-004.1 FEAT-004.2
+:origin: docs/specifications/us/US-004-services/FEAT-004.1-auth-service.rst
+"""
+
+from uuid import UUID
+
+
+class InvalidCredentialsError(Exception):
+    """Credentials invalides (email inconnu ou mot de passe erroné).
+
+    Le message d'erreur HTTP ne doit pas distinguer les deux cas
+    afin d'éviter l'énumération des comptes.
+
+    :spec: FEAT-004.1
+    """
+
+    def __init__(self) -> None:
+        """:spec: FEAT-004.1."""
+        super().__init__("Invalid credentials")
+
+
+class AccountDisabledError(Exception):
+    """Le compte utilisateur est désactivé.
+
+    :spec: FEAT-004.2
+    """
+
+    def __init__(self, user_id: UUID) -> None:
+        """:param user_id: UUID du compte désactivé. :spec: FEAT-004.2"""
+        super().__init__(f"Account {user_id} is disabled")
+        self.user_id = user_id
+
+
+class SessionRevokedError(Exception):
+    """La session a été révoquée (ou le refresh token réutilisé après rotation).
+
+    :spec: FEAT-004.2
+    """
+
+    def __init__(self, session_id: UUID | None = None) -> None:
+        """:param session_id: UUID de la session révoquée. :spec: FEAT-004.2"""
+        msg = f"Session {session_id} is revoked" if session_id else "Session is revoked"
+        super().__init__(msg)
+        self.session_id = session_id
+
+
+class InvalidTokenError(Exception):
+    """Token JWT malformé ou signature invalide.
+
+    :spec: FEAT-004.1
+    """
+
+    def __init__(self, detail: str = "Invalid token") -> None:
+        """:param detail: Message décrivant l'invalidité du token. :spec: FEAT-004.1"""
+        super().__init__(detail)
+
+
+class ExpiredTokenError(InvalidTokenError):
+    """Token JWT expiré.
+
+    Sous-classe de :exc:`InvalidTokenError` pour permettre une capture
+    générique ou spécialisée.
+
+    :spec: FEAT-004.1
+    """
+
+    def __init__(self) -> None:
+        """:spec: FEAT-004.1."""
+        super().__init__("Token has expired")

baobab_auth_api/exceptions/registration.py

@@ -0,0 +1,29 @@
+"""Exceptions liées à l'inscription d'un nouvel utilisateur.
+
+:spec: FEAT-004.1 FEAT-004.2
+:origin: docs/specifications/us/US-004-services/FEAT-004.1-auth-service.rst
+"""
+
+
+class WeakPasswordError(ValueError):
+    """Mot de passe trop court ou ne respectant pas la politique de sécurité.
+
+    :spec: FEAT-004.2
+    """
+
+    def __init__(self, min_length: int) -> None:
+        """:param min_length: Longueur minimale requise. :spec: FEAT-004.2"""
+        super().__init__(f"Password must be at least {min_length} characters long")
+        self.min_length = min_length
+
+
+class EmailAlreadyExistsError(ValueError):
+    """Adresse e-mail déjà utilisée par un compte existant.
+
+    :spec: FEAT-004.1
+    """
+
+    def __init__(self, email: str) -> None:
+        """:param email: Adresse e-mail en conflit. :spec: FEAT-004.1"""
+        super().__init__(f"Email '{email}' is already registered")
+        self.email = email

baobab_auth_api/integration/__init__.py

@@ -0,0 +1,13 @@
+"""Intégration avec ``baobab-auth-core`` (contrats, mapping HTTP)."""
+
+from baobab_auth_api.integration.core_endpoint_spec import CoreEndpointSpec
+from baobab_auth_api.integration.core_exception_http_mapper import CoreExceptionHttpMapper
+from baobab_auth_api.integration.core_integration_gaps import CoreIntegrationGaps
+from baobab_auth_api.integration.core_route_catalog import CoreRouteCatalog
+
+__all__ = [
+    "CoreEndpointSpec",
+    "CoreExceptionHttpMapper",
+    "CoreIntegrationGaps",
+    "CoreRouteCatalog",
+]

baobab_auth_api/integration/core_endpoint_spec.py

@@ -0,0 +1,20 @@
+"""Spécification d'un endpoint HTTP aligné sur le contrat core."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CoreEndpointSpec:
+    """Route HTTP attendue pour un cas d'usage ``baobab-auth-core``.
+
+    :param method: verbe HTTP (``GET``, ``POST``, …).
+    :param path: chemin relatif (ex. ``/auth/login``).
+    :param use_case: nom du use case core cible.
+    :param command: commande core associée ; ``None`` pour les lectures.
+    :spec: FEAT-011.1
+    """
+
+    method: str
+    path: str
+    use_case: str
+    command: str | None = None

baobab_auth_api/integration/core_exception_http_mapper.py

@@ -0,0 +1,57 @@
+"""Mapping exceptions ``baobab-auth-core`` → réponses HTTP."""
+
+from typing import ClassVar
+
+from baobab_auth_core.exceptions.base import BaobabAuthCoreError
+
+
+class CoreExceptionHttpMapper:
+    """Convertit une exception métier core en statut HTTP et payload d'erreur.
+
+    S'appuie uniquement sur ``error_code`` et ``safe_message`` — jamais sur le
+    message interne de l'exception.
+
+    :spec: FEAT-011.1
+    """
+
+    _CODE_TO_HTTP: ClassVar[dict[str, int]] = {
+        "auth.validation.invalid_email": 422,
+        "auth.validation.weak_password": 422,  # nosec B105
+        "auth.validation.invalid_role_name": 422,
+        "auth.user.already_exists": 409,
+        "auth.user.not_found": 404,
+        "auth.user.disabled": 403,
+        "auth.user.locked": 423,
+        "auth.user.deleted": 403,
+        "auth.user.account_disabled": 403,
+        "auth.user.account_pending": 403,
+        "auth.credentials.invalid": 401,
+        "auth.authorization.unauthorized": 401,
+        "auth.token.invalid": 401,
+        "auth.token.expired": 401,
+        "auth.session.expired": 401,
+        "auth.session.revoked": 401,
+        "auth.session.not_found": 404,
+        "auth.authorization.forbidden": 403,
+        "auth.authorization.permission_denied": 403,
+        "auth.role.not_found": 404,
+        "auth.permission.not_found": 404,
+        "auth.role.last_super_admin": 409,
+    }
+
+    def resolve(self, exc: BaobabAuthCoreError) -> tuple[int, str, str]:
+        """Résout le statut HTTP et le corps d'erreur pour une exception core.
+
+        :param exc: exception métier levée par un use case core.
+        :returns: tuple ``(status_code, error_code, safe_message)``.
+        """
+        status = self._CODE_TO_HTTP.get(exc.error_code, 400)
+        return status, exc.error_code, exc.safe_message
+
+    @classmethod
+    def covered_codes(cls) -> frozenset[str]:
+        """Renvoie l'ensemble des ``error_code`` mappés explicitement.
+
+        :returns: codes couverts par le mapping HTTP.
+        """
+        return frozenset(cls._CODE_TO_HTTP)

baobab_auth_api/integration/core_integration_gaps.py

@@ -0,0 +1,26 @@
+"""Écarts documentés entre l'API et ``baobab-auth-core`` 0.9.0."""
+
+
+class CoreIntegrationGaps:
+    """Liste les écarts connus d'intégration avec ``baobab-auth-core``.
+
+    :spec: FEAT-011.1
+    """
+
+    GAPS: tuple[str, ...] = (
+        "Les services v0.1.0 (``AuthService``, modèles locaux) n'orchestrent pas encore "
+        "les use cases exportés du core — migration progressive prévue.",
+        "Huit routes contractuelles §9.1 manquantes (sessions admin, rôles, disable/enable, "
+        "rotation JWK) — voir ``CoreRouteCatalog.missing_from_contract()``.",
+        "``AppFactory`` n'injecte pas encore database/security ; ``baobab-auth-database`` "
+        "reporté en extra ``[database]`` jusqu'à alignement 0.9.x.",
+        "Validation E2E inter-briques → prérequis ``1.0.0``.",
+    )
+
+    @classmethod
+    def documented_gaps(cls) -> tuple[str, ...]:
+        """Renvoie les écarts documentés pour revue PO/architecte.
+
+        :returns: tuple de descriptions d'écarts.
+        """
+        return cls.GAPS

baobab_auth_api/integration/core_route_catalog.py

@@ -0,0 +1,83 @@
+"""Catalogue des routes HTTP — contrat core vs implémentation actuelle."""
+
+from baobab_auth_api.integration.core_endpoint_spec import CoreEndpointSpec
+
+
+class CoreRouteCatalog:
+    """Référentiel des endpoints ``api_contract.md`` et de l'implémentation v0.1.0.
+
+    :spec: FEAT-011.1
+    """
+
+    CONTRACT: tuple[CoreEndpointSpec, ...] = (
+        CoreEndpointSpec("POST", "/auth/register", "RegisterUser", "RegisterUserCommand"),
+        CoreEndpointSpec("POST", "/auth/login", "AuthenticateUser", "AuthenticateUserCommand"),
+        CoreEndpointSpec("POST", "/auth/refresh", "RefreshSession", "RefreshSessionCommand"),
+        CoreEndpointSpec("POST", "/auth/logout", "Logout", "LogoutCommand"),
+        CoreEndpointSpec("GET", "/auth/me", "GetCurrentUser"),
+        CoreEndpointSpec("GET", "/auth/sessions", "ListUserSessions"),
+        CoreEndpointSpec(
+            "POST",
+            "/auth/sessions/{id}/revoke",
+            "RevokeSession",
+            "RevokeSessionCommand",
+        ),
+        CoreEndpointSpec(
+            "POST",
+            "/auth/users/{id}/sessions/revoke",
+            "RevokeAllSessions",
+            "RevokeAllSessionsCommand",
+        ),
+        CoreEndpointSpec("GET", "/auth/roles", "ListRoles"),
+        CoreEndpointSpec("GET", "/auth/permissions", "ListPermissions"),
+        CoreEndpointSpec("POST", "/auth/users/{id}/roles", "AssignRole", "AssignRoleCommand"),
+        CoreEndpointSpec(
+            "DELETE",
+            "/auth/users/{id}/roles/{role}",
+            "RemoveRole",
+            "RemoveRoleCommand",
+        ),
+        CoreEndpointSpec("POST", "/auth/users/{id}/disable", "DisableUser", "DisableUserCommand"),
+        CoreEndpointSpec("POST", "/auth/users/{id}/enable", "EnableUser", "EnableUserCommand"),
+        CoreEndpointSpec(
+            "POST",
+            "/auth/jwks/rotation-request",
+            "RequestJwkRotation",
+            "RequestJwkRotationCommand",
+        ),
+    )
+
+    IMPLEMENTED: tuple[CoreEndpointSpec, ...] = (
+        CoreEndpointSpec("POST", "/auth/register", "RegisterUser", "RegisterUserCommand"),
+        CoreEndpointSpec("POST", "/auth/login", "AuthenticateUser", "AuthenticateUserCommand"),
+        CoreEndpointSpec("POST", "/auth/refresh", "RefreshSession", "RefreshSessionCommand"),
+        CoreEndpointSpec("POST", "/auth/logout", "Logout", "LogoutCommand"),
+        CoreEndpointSpec("GET", "/auth/me", "GetCurrentUser"),
+        CoreEndpointSpec("GET", "/auth/roles", "ListRoles"),
+        CoreEndpointSpec("GET", "/auth/permissions", "ListPermissions"),
+    )
+
+    @classmethod
+    def contract_keys(cls) -> frozenset[tuple[str, str]]:
+        """Renvoie les couples (méthode, chemin) du contrat core.
+
+        :returns: ensemble immuable de clés de route.
+        """
+        return frozenset((spec.method, spec.path) for spec in cls.CONTRACT)
+
+    @classmethod
+    def implemented_keys(cls) -> frozenset[tuple[str, str]]:
+        """Renvoie les couples (méthode, chemin) implémentés en v0.1.0.
+
+        :returns: ensemble immuable de clés de route.
+        """
+        return frozenset((spec.method, spec.path) for spec in cls.IMPLEMENTED)
+
+    @classmethod
+    def missing_from_contract(cls) -> tuple[CoreEndpointSpec, ...]:
+        """Liste les routes contractuelles non encore exposées.
+
+        :returns: endpoints manquants par rapport au contrat core.
+        """
+        implemented = cls.implemented_keys()
+        return tuple(spec for spec in cls.CONTRACT if (spec.method, spec.path) not in implemented)