baobab-auth-database 0.1.0__py3-none-any.whl

baobab_auth_database/__init__.py

@@ -0,0 +1,46 @@
+"""Adaptateur de persistance de l'écosystème ``baobab-auth``.
+
+Le package expose l'API publique de la librairie ``baobab-auth-database``.
+Les symboles listés dans ``__all__`` à la racine et dans chaque sous-package
+constituent le contrat SemVer consommable par les projets parents.
+
+Sous-packages publics stables : ``bootstrap``, ``cli``, ``mappers``,
+``migrations``, ``models``, ``repositories``, ``testing``.
+
+:spec: FEAT-001.1, FEAT-002.1, FEAT-002.2, FEAT-002.3, FEAT-003.1, FEAT-004.3,
+    FEAT-008.3
+"""
+
+from baobab_auth_database.auth_base import AuthBase
+from baobab_auth_database.auth_engine_factory import AuthEngineFactory
+from baobab_auth_database.auth_session_factory import AuthSessionFactory
+from baobab_auth_database.auth_sql_types import AuthSqlTypes
+from baobab_auth_database.database_url_masker import DatabaseUrlMasker
+from baobab_auth_database.exceptions import (
+    AuthDatabaseConfigurationError,
+    AuthDatabaseConnectionError,
+    AuthDatabaseError,
+    AuthDatabaseMappingError,
+    AuthDatabaseMigrationError,
+    AuthDatabaseOperationError,
+)
+from baobab_auth_database.migration_runner import MigrationRunner
+from baobab_auth_database.naming_convention import NamingConvention
+from baobab_auth_database.settings import AuthDatabaseSettings
+
+__all__: tuple[str, ...] = (
+    "AuthBase",
+    "AuthDatabaseConfigurationError",
+    "AuthDatabaseConnectionError",
+    "AuthDatabaseError",
+    "AuthDatabaseMappingError",
+    "AuthDatabaseMigrationError",
+    "AuthDatabaseOperationError",
+    "AuthDatabaseSettings",
+    "AuthEngineFactory",
+    "AuthSessionFactory",
+    "AuthSqlTypes",
+    "DatabaseUrlMasker",
+    "MigrationRunner",
+    "NamingConvention",
+)

baobab_auth_database/auth_base.py

@@ -0,0 +1,20 @@
+"""Base déclarative SQLAlchemy.
+
+:spec: FEAT-003.1
+"""
+
+from typing import ClassVar
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+from baobab_auth_database.naming_convention import NamingConvention
+
+
+class AuthBase(DeclarativeBase):
+    """Base déclarative commune des futurs modèles ORM auth.
+
+    :spec: FEAT-003.1
+    """
+
+    metadata: ClassVar[MetaData] = MetaData(naming_convention=NamingConvention.as_dict())

baobab_auth_database/auth_engine_factory.py

@@ -0,0 +1,48 @@
+"""Factory de création d'engine SQLAlchemy.
+
+:spec: FEAT-002.2, FEAT-002.3
+"""
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.engine.url import make_url
+from sqlalchemy.exc import SQLAlchemyError
+
+from baobab_auth_database.database_url_masker import DatabaseUrlMasker
+from baobab_auth_database.exceptions import AuthDatabaseConnectionError
+from baobab_auth_database.settings import AuthDatabaseSettings
+
+
+class AuthEngineFactory:
+    """Factory d'engine SQLAlchemy pour la persistance auth.
+
+    :spec: FEAT-002.2, FEAT-002.3
+    """
+
+    @classmethod
+    def create_auth_engine(
+        cls: type["AuthEngineFactory"], settings: AuthDatabaseSettings
+    ) -> Engine:
+        """Créer une engine SQLAlchemy depuis les settings database.
+
+        :param settings: Configuration database validée.
+        :returns: Engine SQLAlchemy configurée pour la librairie auth.
+        :raises AuthDatabaseConnectionError: Si SQLAlchemy rejette l'URL ou les options.
+        :spec: FEAT-002.2, FEAT-002.3
+        """
+        try:
+            database_url = make_url(settings.database_url)
+            engine_options: dict[str, object] = {
+                "echo": settings.database_echo,
+                "pool_pre_ping": settings.database_pool_pre_ping,
+            }
+
+            if database_url.get_backend_name() != "sqlite":
+                engine_options["pool_size"] = settings.database_pool_size
+                engine_options["max_overflow"] = settings.database_max_overflow
+
+            return create_engine(database_url, **engine_options)
+        except SQLAlchemyError as exc:
+            masked_url = DatabaseUrlMasker.mask_url(settings.database_url)
+            msg = f"Unable to create auth database engine for {masked_url}."
+            raise AuthDatabaseConnectionError(msg) from exc

baobab_auth_database/auth_session_factory.py

@@ -0,0 +1,27 @@
+"""Factory de création de sessions SQLAlchemy.
+
+:spec: FEAT-002.2
+"""
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class AuthSessionFactory:
+    """Factory de sessionmaker SQLAlchemy pour la persistance auth.
+
+    :spec: FEAT-002.2
+    """
+
+    @classmethod
+    def create_auth_session_factory(
+        cls: type["AuthSessionFactory"],
+        engine: Engine,
+    ) -> sessionmaker[Session]:
+        """Créer un ``sessionmaker`` sans commit implicite.
+
+        :param engine: Engine SQLAlchemy à lier aux sessions.
+        :returns: Factory de sessions SQLAlchemy.
+        :spec: FEAT-002.2
+        """
+        return sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)

baobab_auth_database/auth_sql_types.py

@@ -0,0 +1,42 @@
+"""Types SQL communs de la couche auth.
+
+:spec: FEAT-003.1
+"""
+
+from uuid import UUID
+
+from sqlalchemy.types import JSON, DateTime, TypeEngine, Uuid
+
+
+class AuthSqlTypes:
+    """Factory de types SQLAlchemy compatibles SQLite et PostgreSQL.
+
+    :spec: FEAT-003.1
+    """
+
+    @classmethod
+    def uuid(cls: type["AuthSqlTypes"]) -> TypeEngine[UUID]:
+        """Créer un type UUID SQLAlchemy.
+
+        :returns: Type SQLAlchemy UUID avec valeurs Python ``uuid.UUID``.
+        :spec: FEAT-003.1
+        """
+        return Uuid(as_uuid=True)
+
+    @classmethod
+    def timestamp(cls: type["AuthSqlTypes"]) -> DateTime:
+        """Créer un type timestamp timezone-aware.
+
+        :returns: Type SQLAlchemy ``DateTime`` avec timezone activée.
+        :spec: FEAT-003.1
+        """
+        return DateTime(timezone=True)
+
+    @classmethod
+    def json(cls: type["AuthSqlTypes"]) -> JSON:
+        """Créer un type JSON SQLAlchemy générique.
+
+        :returns: Type SQLAlchemy JSON compatible SQLite/PostgreSQL.
+        :spec: FEAT-003.1
+        """
+        return JSON()

baobab_auth_database/bootstrap/__init__.py

@@ -0,0 +1,12 @@
+"""Bootstrap idempotent rôles et permissions système.
+
+:spec: FEAT-007.1
+"""
+
+from baobab_auth_database.bootstrap.default_auth_catalog import DefaultAuthCatalog
+from baobab_auth_database.bootstrap.seed_defaults import SeedDefaults
+
+__all__: tuple[str, ...] = (
+    "DefaultAuthCatalog",
+    "SeedDefaults",
+)

baobab_auth_database/bootstrap/default_auth_catalog.py

@@ -0,0 +1,98 @@
+"""Catalogue normatif des rôles et permissions système.
+
+:spec: FEAT-007.1
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+
+class DefaultAuthCatalog:
+    """Constantes et matrice rôle-permission du bootstrap auth.
+
+    :spec: FEAT-007.1
+    """
+
+    DEFAULT_ROLES: ClassVar[tuple[str, ...]] = (
+        "USER",
+        "ADMIN",
+        "SUPER_ADMIN",
+    )
+
+    DEFAULT_PERMISSIONS: ClassVar[tuple[str, ...]] = (
+        "auth:user:read",
+        "auth:user:write",
+        "auth:role:read",
+        "auth:role:write",
+        "auth:permission:read",
+        "auth:permission:write",
+        "auth:session:read",
+        "auth:session:revoke",
+        "auth:audit:read",
+        "auth:jwk:read",
+        "auth:jwk:write",
+    )
+
+    DEFAULT_ROLE_PERMISSIONS: ClassVar[dict[str, tuple[str, ...]]] = {
+        "USER": (
+            "auth:user:read",
+            "auth:session:read",
+        ),
+        "ADMIN": (
+            "auth:user:read",
+            "auth:user:write",
+            "auth:role:read",
+            "auth:permission:read",
+            "auth:session:read",
+            "auth:session:revoke",
+            "auth:audit:read",
+            "auth:jwk:read",
+        ),
+        "SUPER_ADMIN": DEFAULT_PERMISSIONS,
+    }
+
+    DEFAULT_ROLE_DESCRIPTIONS: ClassVar[dict[str, str]] = {
+        "USER": "Utilisateur standard : consultation de son compte et de ses sessions.",
+        "ADMIN": "Administration opérationnelle des utilisateurs, sessions, audit et JWKS.",
+        "SUPER_ADMIN": "Administration complète du système d'authentification.",
+    }
+
+    DEFAULT_PERMISSION_DESCRIPTIONS: ClassVar[dict[str, str]] = {
+        "auth:user:read": "Lire un utilisateur (périmètre restreint au compte courant pour USER).",
+        "auth:user:write": "Créer, modifier ou gérer un utilisateur et ses rôles.",
+        "auth:role:read": "Lire les rôles disponibles et leurs associations.",
+        "auth:role:write": "Créer, modifier ou supprimer un rôle système ou applicatif.",
+        "auth:permission:read": "Lire les permissions disponibles.",
+        "auth:permission:write": "Créer, modifier ou supprimer une permission.",
+        "auth:session:read": "Lire les sessions (périmètre restreint pour USER).",
+        "auth:session:revoke": "Révoquer une session.",
+        "auth:audit:read": "Consulter les événements d'audit.",
+        "auth:jwk:read": "Inspecter les clés JWKS en administration.",
+        "auth:jwk:write": "Créer, importer, désactiver ou préparer la rotation de clés JWKS.",
+    }
+
+    @classmethod
+    def validate_catalog(cls: type[DefaultAuthCatalog]) -> None:
+        """Vérifier la cohérence interne du catalogue.
+
+        :returns: ``None``.
+        :raises ValueError: Si un rôle ou une permission référencé est absent du catalogue.
+        :spec: FEAT-007.1
+        """
+        role_names = set(cls.DEFAULT_ROLES)
+        permission_codes = set(cls.DEFAULT_PERMISSIONS)
+        for role_name, permission_codes_for_role in cls.DEFAULT_ROLE_PERMISSIONS.items():
+            if role_name not in role_names:
+                message = f"Rôle inconnu dans DEFAULT_ROLE_PERMISSIONS : {role_name}."
+                raise ValueError(message)
+            for permission_code in permission_codes_for_role:
+                if permission_code not in permission_codes:
+                    message = (
+                        f"Permission {permission_code} référencée pour {role_name} "
+                        "mais absente de DEFAULT_PERMISSIONS."
+                    )
+                    raise ValueError(message)
+        if set(cls.DEFAULT_ROLE_PERMISSIONS) != role_names:
+            message = "DEFAULT_ROLE_PERMISSIONS doit couvrir exactement DEFAULT_ROLES."
+            raise ValueError(message)

baobab_auth_database/bootstrap/seed_defaults.py

@@ -0,0 +1,150 @@
+"""Bootstrap idempotent des rôles et permissions système.
+
+:spec: FEAT-007.1
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from baobab_auth_core import Permission, Role
+from baobab_auth_core.domain.value_objects.permission_name import PermissionName
+from baobab_auth_core.domain.value_objects.role_name import RoleName
+from baobab_auth_core.domain.value_objects.utc_datetime import UtcDatetime
+
+from baobab_auth_database.bootstrap.default_auth_catalog import DefaultAuthCatalog
+from baobab_auth_database.repositories.sql_alchemy_auth_unit_of_work import SqlAlchemyAuthUnitOfWork
+
+
+class SeedDefaults:
+    """Seeds idempotents des rôles et permissions par défaut.
+
+    :spec: FEAT-007.1
+    """
+
+    @classmethod
+    def seed_default_roles_and_permissions(
+        cls: type[SeedDefaults],
+        unit_of_work: SqlAlchemyAuthUnitOfWork,
+    ) -> None:
+        """Créer ou compléter les rôles, permissions et associations système.
+
+        Le seed ne supprime ni ne remplace les entités inconnues ajoutées par une
+        application consommatrice. Les associations existantes sont préservées et
+        complétées selon la matrice normative.
+
+        :param unit_of_work: Unit of Work ouverte (``__enter__`` déjà appelé).
+        :returns: ``None``.
+        :spec: FEAT-007.1
+        """
+        DefaultAuthCatalog.validate_catalog()
+        cls._seed_permissions(unit_of_work)
+        cls._seed_roles(unit_of_work)
+
+    @classmethod
+    def _seed_permissions(
+        cls: type[SeedDefaults],
+        unit_of_work: SqlAlchemyAuthUnitOfWork,
+    ) -> None:
+        for permission_code in DefaultAuthCatalog.DEFAULT_PERMISSIONS:
+            cls._ensure_permission(unit_of_work, permission_code)
+
+    @classmethod
+    def _seed_roles(
+        cls: type[SeedDefaults],
+        unit_of_work: SqlAlchemyAuthUnitOfWork,
+    ) -> None:
+        for role_name in DefaultAuthCatalog.DEFAULT_ROLES:
+            cls._ensure_role(unit_of_work, role_name)
+
+    @classmethod
+    def _ensure_permission(
+        cls: type[SeedDefaults],
+        unit_of_work: SqlAlchemyAuthUnitOfWork,
+        permission_code: str,
+    ) -> None:
+        permission_name = PermissionName(permission_code)
+        existing = unit_of_work.permissions.get_by_name(permission_name)
+        resource, action = cls._parse_permission_code(permission_code)
+        description = DefaultAuthCatalog.DEFAULT_PERMISSION_DESCRIPTIONS[permission_code]
+        if existing is None:
+            unit_of_work.permissions.save(
+                Permission(
+                    id=str(uuid4()),
+                    name=permission_name,
+                    resource=resource,
+                    action=action,
+                    description=description,
+                    is_system=True,
+                )
+            )
+            return
+        if existing.description != description:
+            unit_of_work.permissions.save(
+                Permission(
+                    id=existing.id,
+                    name=existing.name,
+                    resource=existing.resource,
+                    action=existing.action,
+                    description=description,
+                    is_system=existing.is_system,
+                )
+            )
+
+    @classmethod
+    def _ensure_role(
+        cls: type[SeedDefaults],
+        unit_of_work: SqlAlchemyAuthUnitOfWork,
+        role_name: str,
+    ) -> None:
+        name = RoleName(role_name)
+        default_permission_codes = DefaultAuthCatalog.DEFAULT_ROLE_PERMISSIONS[role_name]
+        default_permissions = {PermissionName(code) for code in default_permission_codes}
+        description = DefaultAuthCatalog.DEFAULT_ROLE_DESCRIPTIONS[role_name]
+        existing = unit_of_work.roles.get_by_name(name)
+        if existing is None:
+            now = cls._utc_now()
+            unit_of_work.roles.save(
+                Role(
+                    id=str(uuid4()),
+                    name=name,
+                    description=description,
+                    permissions=default_permissions,
+                    is_system=True,
+                    created_at=now,
+                    updated_at=now,
+                )
+            )
+            return
+        merged_permissions = existing.permissions | default_permissions
+        updated_description = (
+            description if existing.description != description else existing.description
+        )
+        if (
+            merged_permissions != existing.permissions
+            or updated_description != existing.description
+        ):
+            unit_of_work.roles.save(
+                Role(
+                    id=existing.id,
+                    name=existing.name,
+                    description=updated_description,
+                    permissions=merged_permissions,
+                    is_system=existing.is_system,
+                    created_at=existing.created_at,
+                    updated_at=cls._utc_now(),
+                )
+            )
+
+    @staticmethod
+    def _parse_permission_code(permission_code: str) -> tuple[str, str]:
+        parts = permission_code.split(":")
+        if len(parts) != 3 or parts[0] != "auth":
+            message = f"Code de permission système invalide : {permission_code}."
+            raise ValueError(message)
+        return parts[1], parts[2]
+
+    @staticmethod
+    def _utc_now() -> UtcDatetime:
+        return UtcDatetime(datetime.now(UTC))

baobab_auth_database/cli/__init__.py

@@ -0,0 +1,12 @@
+"""Interface en ligne de commande ``baobab-auth-db``.
+
+:spec: FEAT-007.2
+"""
+
+from baobab_auth_database.cli.auth_database_cli import AuthDatabaseCli
+from baobab_auth_database.cli.cli_configuration import CliConfiguration
+
+__all__: tuple[str, ...] = (
+    "AuthDatabaseCli",
+    "CliConfiguration",
+)

baobab_auth_database/cli/auth_database_cli.py

@@ -0,0 +1,123 @@
+"""Interface en ligne de commande ``baobab-auth-db``.
+
+:spec: FEAT-007.2
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+
+from baobab_auth_database import (
+    AuthEngineFactory,
+    AuthSessionFactory,
+    MigrationRunner,
+)
+from baobab_auth_database.bootstrap import SeedDefaults
+from baobab_auth_database.cli.cli_configuration import CliConfiguration
+from baobab_auth_database.repositories import SqlAlchemyAuthUnitOfWork
+from baobab_auth_database.settings import AuthDatabaseSettings
+
+
+class AuthDatabaseCli:
+    """Pilote les commandes migrations et bootstrap de la librairie.
+
+    :spec: FEAT-007.2
+    """
+
+    def run(
+        self: AuthDatabaseCli,
+        argv: Sequence[str] | None = None,
+    ) -> int:
+        """Exécuter la commande CLI demandée.
+
+        :param argv: Arguments (``None`` pour ``sys.argv[1:]``).
+        :returns: Code de sortie POSIX (``0`` si succès).
+        :spec: FEAT-007.2
+        """
+        parser = self._build_parser()
+        args = parser.parse_args(list(argv) if argv is not None else None)
+        if args.verbose:
+            logging.basicConfig(level=logging.DEBUG)
+        settings = CliConfiguration.load_settings(
+            database_url=args.database_url,
+            env_file=args.env_file,
+        )
+        if args.command == "upgrade":
+            MigrationRunner.from_settings(settings).upgrade(args.revision)
+            return 0
+        if args.command == "downgrade":
+            MigrationRunner.from_settings(settings).downgrade(args.revision)
+            return 0
+        if args.command == "current":
+            current = MigrationRunner.from_settings(settings).current()
+            sys.stdout.write(f"{current}\n" if current is not None else "None\n")
+            return 0
+        if args.command == "history":
+            history = MigrationRunner.from_settings(settings).history()
+            for revision in history:
+                sys.stdout.write(f"{revision}\n")
+            return 0
+        if args.command == "seed-defaults":
+            self._run_seed_defaults(settings)
+            return 0
+        parser.error(f"Commande inconnue : {args.command}")
+        return 2
+
+    @staticmethod
+    def _build_parser() -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser(
+            prog="baobab-auth-db",
+            description="CLI de migrations et bootstrap pour baobab-auth-database.",
+        )
+        parser.add_argument(
+            "--database-url",
+            help="URL SQLAlchemy explicite (prioritaire sur BAOBAB_AUTH_DATABASE_URL).",
+        )
+        parser.add_argument(
+            "--env-file",
+            help="Fichier d'environnement à charger avant la résolution des settings.",
+        )
+        parser.add_argument(
+            "--verbose",
+            action="store_true",
+            help="Active le logging de debug.",
+        )
+        subparsers = parser.add_subparsers(dest="command", required=True)
+
+        upgrade = subparsers.add_parser("upgrade", help="Appliquer les migrations.")
+        upgrade.add_argument(
+            "revision",
+            nargs="?",
+            default="head",
+            help="Révision cible (défaut : head).",
+        )
+
+        downgrade = subparsers.add_parser("downgrade", help="Revenir à une révision antérieure.")
+        downgrade.add_argument(
+            "revision",
+            nargs="?",
+            default="-1",
+            help="Révision cible (défaut : -1).",
+        )
+
+        subparsers.add_parser("current", help="Afficher la révision courante.")
+        subparsers.add_parser("history", help="Lister les révisions connues.")
+        subparsers.add_parser(
+            "seed-defaults",
+            help="Exécuter le bootstrap idempotent des rôles et permissions.",
+        )
+        return parser
+
+    @staticmethod
+    def _run_seed_defaults(settings: AuthDatabaseSettings) -> None:
+        engine = AuthEngineFactory.create_auth_engine(settings)
+        session_factory = AuthSessionFactory.create_auth_session_factory(engine)
+        try:
+            with SqlAlchemyAuthUnitOfWork(session_factory) as unit_of_work:
+                SeedDefaults.seed_default_roles_and_permissions(unit_of_work)
+                unit_of_work.commit()
+        finally:
+            engine.dispose()

baobab_auth_database/cli/cli_configuration.py

@@ -0,0 +1,37 @@
+"""Résolution de configuration pour la CLI ``baobab-auth-db``.
+
+:spec: FEAT-007.2
+"""
+
+from baobab_auth_database.settings import AuthDatabaseSettings
+
+
+class CliConfiguration:
+    """Charge les settings database pour les commandes CLI.
+
+    :spec: FEAT-007.2
+    """
+
+    @classmethod
+    def load_settings(
+        cls: type["CliConfiguration"],
+        *,
+        database_url: str | None = None,
+        env_file: str | None = None,
+    ) -> AuthDatabaseSettings:
+        """Construire les settings depuis l'environnement et les options CLI.
+
+        :param database_url: URL SQLAlchemy explicite (prioritaire sur l'environnement).
+        :param env_file: Fichier d'environnement optionnel à charger.
+        :returns: Settings validés pour la commande CLI.
+        :spec: FEAT-007.2
+        """
+        if env_file is not None:
+            settings = AuthDatabaseSettings(_env_file=env_file)  # type: ignore[call-arg]
+        elif database_url is not None:
+            return AuthDatabaseSettings(database_url=database_url)
+        else:
+            settings = AuthDatabaseSettings()
+        if database_url is not None:
+            return settings.model_copy(update={"database_url": database_url})
+        return settings

baobab_auth_database/cli/main.py

@@ -0,0 +1,16 @@
+"""Point d'entrée console ``baobab-auth-db``.
+
+:spec: FEAT-007.2
+"""
+
+import sys
+
+from baobab_auth_database.cli.auth_database_cli import AuthDatabaseCli
+
+
+def main() -> None:
+    """Lancer la CLI et propager le code de sortie au processus.
+
+    :spec: FEAT-007.2
+    """
+    sys.exit(AuthDatabaseCli().run())

baobab_auth_database/database_url_masker.py

@@ -0,0 +1,27 @@
+"""Masquage des URLs database sensibles.
+
+:spec: FEAT-002.3
+"""
+
+from sqlalchemy.engine.url import make_url
+from sqlalchemy.exc import ArgumentError
+
+
+class DatabaseUrlMasker:
+    """Masque les informations sensibles dans une URL database.
+
+    :spec: FEAT-002.3
+    """
+
+    @classmethod
+    def mask_url(cls: type["DatabaseUrlMasker"], database_url: str) -> str:
+        """Rendre une URL database affichable sans mot de passe.
+
+        :param database_url: URL database brute.
+        :returns: URL masquée ou libellé générique si l'URL est invalide.
+        :spec: FEAT-002.3
+        """
+        try:
+            return make_url(database_url).render_as_string(hide_password=True)
+        except ArgumentError:
+            return "<invalid database url>"