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

baobab_auth_core/__init__.py

@@ -0,0 +1,13 @@
+"""baobab-auth-core — socle métier d'authentification et d'autorisation.
+
+Version : 0.1.0
+
+Ce package expose les entités, value objects, policies, ports et fakes
+de test du domaine d'authentification. Il ne contient aucune dépendance
+sur des technologies concrètes (ORM, framework web, JWT, Argon2, etc.).
+
+:spec: BL-010-001
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

baobab_auth_core/application/__init__.py

@@ -0,0 +1,6 @@
+"""Couche application de baobab-auth-core (réservé aux versions suivantes).
+
+:spec: BL-010-001
+"""
+
+__all__: list[str] = []

baobab_auth_core/application/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Commandes de la couche application (réservé aux versions suivantes).
+
+:spec: BL-010-001
+"""
+
+__all__: list[str] = []

baobab_auth_core/application/results/__init__.py

@@ -0,0 +1,6 @@
+"""Résultats de la couche application (réservé aux versions suivantes).
+
+:spec: BL-010-001
+"""
+
+__all__: list[str] = []

baobab_auth_core/application/use_cases/__init__.py

@@ -0,0 +1,6 @@
+"""Use cases de la couche application (réservé aux versions suivantes).
+
+:spec: BL-010-001
+"""
+
+__all__: list[str] = []

baobab_auth_core/domain/__init__.py

@@ -0,0 +1,6 @@
+"""Domaine métier de baobab-auth-core.
+
+:spec: BL-010-001
+"""
+
+__all__: list[str] = []

baobab_auth_core/domain/entities/__init__.py

@@ -0,0 +1,20 @@
+"""Entités du domaine baobab-auth-core.
+
+:spec: BL-010-003
+"""
+
+from baobab_auth_core.domain.entities.audit_event import AuditEvent as AuditEvent
+from baobab_auth_core.domain.entities.permission import Permission as Permission
+from baobab_auth_core.domain.entities.role import Role as Role
+from baobab_auth_core.domain.entities.session import Session as Session
+from baobab_auth_core.domain.entities.user import User as User
+from baobab_auth_core.domain.entities.user_profile import UserProfile as UserProfile
+
+__all__ = [
+    "AuditEvent",
+    "Permission",
+    "Role",
+    "Session",
+    "User",
+    "UserProfile",
+]

baobab_auth_core/domain/entities/audit_event.py

@@ -0,0 +1,46 @@
+"""Entité AuditEvent — événement d'audit immuable.
+
+:spec: BL-010-003
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from baobab_auth_core.domain.enums.audit_event_type import AuditEventType
+from baobab_auth_core.domain.enums.audit_severity import AuditSeverity
+from baobab_auth_core.domain.value_objects.audit_event_id import AuditEventId
+from baobab_auth_core.domain.value_objects.auth_subject import AuthSubject
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    """Événement d'audit immuable tracé dans le journal de sécurité.
+
+    Cette entité est frozen (immuable) car les événements d'audit
+    ne doivent jamais être modifiés après enregistrement.
+
+    :param id: Identifiant unique de l'événement.
+    :param event_type: Type de l'événement.
+    :param severity: Niveau de sévérité.
+    :param created_at: Horodatage de l'événement (UTC).
+    :param actor_subject: Sujet initiateur de l'action
+        (ou None pour des actions système).
+    :param target_type: Type de la ressource ciblée (ex. ``user``, ``session``).
+    :param target_id: Identifiant de la ressource ciblée.
+    :param ip_address: Adresse IP de l'acteur.
+    :param user_agent: User-Agent HTTP de l'acteur.
+    :param metadata: Métadonnées additionnelles contextuelles.
+    """
+
+    id: AuditEventId
+    event_type: AuditEventType
+    severity: AuditSeverity
+    created_at: datetime
+    actor_subject: AuthSubject | None = field(default=None)
+    target_type: str | None = field(default=None)
+    target_id: str | None = field(default=None)
+    ip_address: str | None = field(default=None)
+    user_agent: str | None = field(default=None)
+    metadata: Mapping[str, Any] = field(default_factory=dict)

baobab_auth_core/domain/entities/permission.py

@@ -0,0 +1,32 @@
+"""Entité Permission — permission atomique du système d'autorisation.
+
+:spec: BL-010-003
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from baobab_auth_core.domain.value_objects.permission_id import PermissionId
+from baobab_auth_core.domain.value_objects.permission_name import PermissionName
+
+
+@dataclass
+class Permission:
+    """Permission atomique du système d'autorisation.
+
+    :param id: Identifiant unique de la permission.
+    :param name: Nom unique au format ``scope:resource:action``.
+    :param resource: Ressource ciblée.
+    :param action: Action autorisée sur la ressource.
+    :param is_system: Si ``True``, permission système non supprimable.
+    :param created_at: Date de création (UTC).
+    :param description: Description optionnelle.
+    """
+
+    id: PermissionId
+    name: PermissionName
+    resource: str
+    action: str
+    is_system: bool
+    created_at: datetime
+    description: str | None = field(default=None)

baobab_auth_core/domain/entities/role.py

@@ -0,0 +1,33 @@
+"""Entité Role — rôle du système d'autorisation.
+
+:spec: BL-010-003
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from baobab_auth_core.domain.value_objects.permission_name import PermissionName
+from baobab_auth_core.domain.value_objects.role_id import RoleId
+from baobab_auth_core.domain.value_objects.role_name import RoleName
+
+
+@dataclass
+class Role:
+    """Rôle du système d'autorisation regroupant un ensemble de permissions.
+
+    :param id: Identifiant unique du rôle.
+    :param name: Nom unique du rôle.
+    :param is_system: Si ``True``, rôle système non supprimable.
+    :param created_at: Date de création (UTC).
+    :param updated_at: Date de dernière mise à jour (UTC).
+    :param description: Description optionnelle.
+    :param permission_names: Permissions associées (sans doublon).
+    """
+
+    id: RoleId
+    name: RoleName
+    is_system: bool
+    created_at: datetime
+    updated_at: datetime
+    description: str | None = field(default=None)
+    permission_names: tuple[PermissionName, ...] = field(default_factory=tuple)

baobab_auth_core/domain/entities/session.py

@@ -0,0 +1,42 @@
+"""Entité Session — session utilisateur active.
+
+:spec: BL-010-003
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from baobab_auth_core.domain.enums.session_status import SessionStatus
+from baobab_auth_core.domain.value_objects.session_id import SessionId
+from baobab_auth_core.domain.value_objects.token_id import TokenId
+from baobab_auth_core.domain.value_objects.user_id import UserId
+
+
+@dataclass
+class Session:
+    """Session utilisateur associant un token de rafraîchissement à un utilisateur.
+
+    :param id: Identifiant unique de la session.
+    :param user_id: Identifiant de l'utilisateur propriétaire.
+    :param refresh_token_id: Identifiant du token de rafraîchissement.
+    :param status: Statut courant de la session.
+    :param created_at: Date de création (UTC).
+    :param expires_at: Date d'expiration (UTC).
+    :param revoked_at: Date de révocation (UTC ou None).
+    :param last_used_at: Date de dernière utilisation (UTC ou None).
+    :param user_agent: User-Agent HTTP du client (ou None).
+    :param ip_address: Adresse IP du client (ou None).
+    :param device_label: Libellé lisible du device (ou None).
+    """
+
+    id: SessionId
+    user_id: UserId
+    refresh_token_id: TokenId
+    status: SessionStatus
+    created_at: datetime
+    expires_at: datetime
+    revoked_at: datetime | None = field(default=None)
+    last_used_at: datetime | None = field(default=None)
+    user_agent: str | None = field(default=None)
+    ip_address: str | None = field(default=None)
+    device_label: str | None = field(default=None)

baobab_auth_core/domain/entities/user.py

@@ -0,0 +1,157 @@
+"""Entité User — compte utilisateur du domaine.
+
+:spec: BL-010-003
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from baobab_auth_core.domain.enums.user_status import UserStatus
+from baobab_auth_core.domain.value_objects.auth_subject import AuthSubject
+from baobab_auth_core.domain.value_objects.email import Email
+from baobab_auth_core.domain.value_objects.password_hash import PasswordHash
+from baobab_auth_core.domain.value_objects.role_name import RoleName
+from baobab_auth_core.domain.value_objects.user_id import UserId
+from baobab_auth_core.exceptions.validation import ValidationError
+
+
+@dataclass
+class User:
+    """Compte utilisateur — agrégat racine du domaine d'authentification.
+
+    Invariants :
+    - ``email`` obligatoire et normalisé ;
+    - ``auth_subject`` obligatoire et stable ;
+    - ``password_hash`` jamais vide ;
+    - ``failed_login_count >= 0`` ;
+    - dates UTC aware ;
+    - rôles sans doublon.
+
+    :param id: Identifiant unique de l'utilisateur.
+    :param auth_subject: Identifiant stable du sujet d'authentification.
+    :param email: Adresse email normalisée.
+    :param password_hash: Hash du mot de passe.
+    :param status: Statut actuel du compte.
+    :param role_names: Rôles assignés (sans doublon).
+    :param created_at: Date de création (UTC).
+    :param updated_at: Date de dernière mise à jour (UTC).
+    :param last_login_at: Date de dernière connexion réussie (UTC ou None).
+    :param failed_login_count: Nombre de tentatives de connexion échouées consécutives.
+    :param locked_until: Date de fin de verrouillage (UTC ou None).
+    """
+
+    id: UserId
+    auth_subject: AuthSubject
+    email: Email
+    password_hash: PasswordHash
+    status: UserStatus
+    role_names: tuple[RoleName, ...]
+    created_at: datetime
+    updated_at: datetime
+    last_login_at: datetime | None = field(default=None)
+    failed_login_count: int = field(default=0)
+    locked_until: datetime | None = field(default=None)
+
+    def __post_init__(self) -> None:
+        """Valide les invariants à la construction.
+
+        :raises ValidationError: Si ``failed_login_count`` est négatif ou si
+            ``role_names`` contient des doublons.
+        """
+        if self.failed_login_count < 0:
+            raise ValidationError(
+                "failed_login_count doit être supérieur ou égal à zéro."
+            )
+        unique = list(dict.fromkeys(self.role_names))
+        if len(unique) != len(self.role_names):
+            raise ValidationError("role_names ne peut pas contenir de doublons.")
+
+    def activate(self, now: datetime) -> None:
+        """Active le compte utilisateur.
+
+        :param now: Horodatage courant (UTC).
+        """
+        self.status = UserStatus.ACTIVE
+        self.updated_at = now
+
+    def disable(self, now: datetime) -> None:
+        """Désactive le compte utilisateur.
+
+        :param now: Horodatage courant (UTC).
+        """
+        self.status = UserStatus.DISABLED
+        self.updated_at = now
+
+    def lock(self, until: datetime, now: datetime) -> None:
+        """Verrouille le compte jusqu'à une date donnée.
+
+        :param until: Date de fin de verrouillage (UTC).
+        :param now: Horodatage courant (UTC).
+        """
+        self.status = UserStatus.LOCKED
+        self.locked_until = until
+        self.updated_at = now
+
+    def unlock(self, now: datetime) -> None:
+        """Déverrouille le compte et remet le compteur d'échecs à zéro.
+
+        :param now: Horodatage courant (UTC).
+        """
+        self.status = UserStatus.ACTIVE
+        self.locked_until = None
+        self.failed_login_count = 0
+        self.updated_at = now
+
+    def mark_login_success(self, now: datetime) -> None:
+        """Enregistre une connexion réussie et réinitialise le compteur d'échecs.
+
+        :param now: Horodatage courant (UTC).
+        """
+        self.last_login_at = now
+        self.failed_login_count = 0
+        self.updated_at = now
+
+    def mark_login_failure(self, now: datetime) -> None:
+        """Incrémente le compteur de tentatives de connexion échouées.
+
+        :param now: Horodatage courant (UTC).
+        """
+        self.failed_login_count += 1
+        self.updated_at = now
+
+    def change_password_hash(self, password_hash: PasswordHash, now: datetime) -> None:
+        """Remplace le hash de mot de passe.
+
+        :param password_hash: Nouveau hash.
+        :param now: Horodatage courant (UTC).
+        """
+        self.password_hash = password_hash
+        self.updated_at = now
+
+    def assign_role(self, role_name: RoleName, now: datetime) -> None:
+        """Assigne un rôle si non déjà présent.
+
+        :param role_name: Nom du rôle à assigner.
+        :param now: Horodatage courant (UTC).
+        """
+        if role_name not in self.role_names:
+            self.role_names = (*self.role_names, role_name)
+            self.updated_at = now
+
+    def remove_role(self, role_name: RoleName, now: datetime) -> None:
+        """Retire un rôle de l'utilisateur.
+
+        :param role_name: Nom du rôle à retirer.
+        :param now: Horodatage courant (UTC).
+        """
+        if role_name in self.role_names:
+            self.role_names = tuple(r for r in self.role_names if r != role_name)
+            self.updated_at = now
+
+    def has_role(self, role_name: RoleName) -> bool:
+        """Vérifie si l'utilisateur possède un rôle donné.
+
+        :param role_name: Nom du rôle à vérifier.
+        :returns: ``True`` si le rôle est présent.
+        """
+        return role_name in self.role_names

baobab_auth_core/domain/entities/user_profile.py

@@ -0,0 +1,34 @@
+"""Entité UserProfile — profil public d'un utilisateur.
+
+:spec: BL-010-003
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from baobab_auth_core.domain.value_objects.user_id import UserId
+
+
+@dataclass
+class UserProfile:
+    """Profil public d'un utilisateur, sans aucun secret.
+
+    Cette entité ne contient aucune information d'authentification
+    (pas de mot de passe, hash, token ou secret).
+
+    :param user_id: Identifiant de l'utilisateur associé.
+    :param display_name: Nom d'affichage public (ou None).
+    :param locale: Code de locale BCP-47 (ex. ``fr-FR``) ou None.
+    :param timezone: Fuseau horaire IANA (ex. ``Europe/Paris``) ou None.
+    :param avatar_url: URL publique de l'avatar (ou None).
+    :param created_at: Date de création (UTC).
+    :param updated_at: Date de dernière mise à jour (UTC).
+    """
+
+    user_id: UserId
+    created_at: datetime
+    updated_at: datetime
+    display_name: str | None = None
+    locale: str | None = None
+    timezone: str | None = None
+    avatar_url: str | None = None

baobab_auth_core/domain/enums/__init__.py

@@ -0,0 +1,18 @@
+"""Énumérations du domaine baobab-auth-core.
+
+:spec: BL-010-004
+"""
+
+from baobab_auth_core.domain.enums.audit_event_type import (
+    AuditEventType as AuditEventType,
+)
+from baobab_auth_core.domain.enums.audit_severity import AuditSeverity as AuditSeverity
+from baobab_auth_core.domain.enums.session_status import SessionStatus as SessionStatus
+from baobab_auth_core.domain.enums.user_status import UserStatus as UserStatus
+
+__all__ = [
+    "AuditEventType",
+    "AuditSeverity",
+    "SessionStatus",
+    "UserStatus",
+]

baobab_auth_core/domain/enums/audit_event_type.py

@@ -0,0 +1,37 @@
+"""Types d'événements d'audit.
+
+:spec: BL-010-004
+"""
+
+from enum import StrEnum
+
+
+class AuditEventType(StrEnum):
+    """Catalogue des types d'événements traçables.
+
+    :cvar USER_REGISTERED: Nouvel utilisateur enregistré.
+    :cvar LOGIN_SUCCESS: Connexion réussie.
+    :cvar LOGIN_FAILURE: Échec de connexion (identifiants invalides).
+    :cvar LOGOUT: Déconnexion explicite.
+    :cvar SESSION_REFRESHED: Token de session renouvelé.
+    :cvar SESSION_REVOKED: Session révoquée.
+    :cvar ROLE_ASSIGNED: Rôle attribué à un utilisateur.
+    :cvar ROLE_REMOVED: Rôle retiré d'un utilisateur.
+    :cvar PASSWORD_CHANGED: Mot de passe modifié.
+    :cvar ACCOUNT_LOCKED: Compte verrouillé suite à trop d'échecs.
+    :cvar ACCOUNT_DISABLED: Compte désactivé par un administrateur.
+    :cvar ACCOUNT_DELETED: Compte supprimé.
+    """
+
+    USER_REGISTERED = "USER_REGISTERED"
+    LOGIN_SUCCESS = "LOGIN_SUCCESS"
+    LOGIN_FAILURE = "LOGIN_FAILURE"
+    LOGOUT = "LOGOUT"
+    SESSION_REFRESHED = "SESSION_REFRESHED"
+    SESSION_REVOKED = "SESSION_REVOKED"
+    ROLE_ASSIGNED = "ROLE_ASSIGNED"
+    ROLE_REMOVED = "ROLE_REMOVED"
+    PASSWORD_CHANGED = "PASSWORD_CHANGED"  # nosec B105
+    ACCOUNT_LOCKED = "ACCOUNT_LOCKED"
+    ACCOUNT_DISABLED = "ACCOUNT_DISABLED"
+    ACCOUNT_DELETED = "ACCOUNT_DELETED"

baobab_auth_core/domain/enums/audit_severity.py

@@ -0,0 +1,19 @@
+"""Niveau de sévérité d'un événement d'audit.
+
+:spec: BL-010-004
+"""
+
+from enum import StrEnum
+
+
+class AuditSeverity(StrEnum):
+    """Sévérité d'un événement d'audit.
+
+    :cvar INFO: Événement informatif, opération normale.
+    :cvar WARNING: Situation anormale mais non critique.
+    :cvar CRITICAL: Incident de sécurité ou erreur grave.
+    """
+
+    INFO = "INFO"
+    WARNING = "WARNING"
+    CRITICAL = "CRITICAL"

baobab_auth_core/domain/enums/session_status.py

@@ -0,0 +1,20 @@
+"""Statut d'une session utilisateur.
+
+:spec: BL-010-004
+"""
+
+from enum import StrEnum
+
+
+class SessionStatus(StrEnum):
+    """Cycle de vie d'une session.
+
+    :cvar ACTIVE: Session active et valide.
+    :cvar REVOKED: Session révoquée explicitement
+        (déconnexion, changement de mot de passe).
+    :cvar EXPIRED: Session expirée (TTL dépassé).
+    """
+
+    ACTIVE = "ACTIVE"
+    REVOKED = "REVOKED"
+    EXPIRED = "EXPIRED"

baobab_auth_core/domain/enums/user_status.py

@@ -0,0 +1,23 @@
+"""Statut d'un compte utilisateur.
+
+:spec: BL-010-004
+"""
+
+from enum import StrEnum
+
+
+class UserStatus(StrEnum):
+    """Cycle de vie d'un compte utilisateur.
+
+    :cvar PENDING: Compte créé, en attente de validation.
+    :cvar ACTIVE: Compte actif, l'utilisateur peut se connecter.
+    :cvar LOCKED: Compte temporairement verrouillé (trop d'échecs de connexion).
+    :cvar DISABLED: Compte désactivé par un administrateur.
+    :cvar DELETED: Compte supprimé (soft-delete).
+    """
+
+    PENDING = "PENDING"
+    ACTIVE = "ACTIVE"
+    LOCKED = "LOCKED"
+    DISABLED = "DISABLED"
+    DELETED = "DELETED"

baobab_auth_core/domain/policies/__init__.py

@@ -0,0 +1,18 @@
+"""Politiques du domaine baobab-auth-core.
+
+:spec: BL-010-004
+"""
+
+from baobab_auth_core.domain.policies.password_policy import (
+    PasswordPolicy as PasswordPolicy,
+)
+from baobab_auth_core.domain.policies.role_policy import RolePolicy as RolePolicy
+from baobab_auth_core.domain.policies.session_policy import (
+    SessionPolicy as SessionPolicy,
+)
+
+__all__ = [
+    "PasswordPolicy",
+    "RolePolicy",
+    "SessionPolicy",
+]

baobab_auth_core/domain/policies/password_policy.py

@@ -0,0 +1,80 @@
+"""Politique de mot de passe.
+
+:spec: BL-010-004
+"""
+
+from dataclasses import dataclass, field
+
+from baobab_auth_core.domain.value_objects.email import Email
+from baobab_auth_core.domain.value_objects.plain_password import PlainPassword
+from baobab_auth_core.exceptions.validation import WeakPasswordError
+
+_DEFAULT_MIN_LENGTH = 12
+_DEFAULT_MAX_LENGTH = 256
+
+
+@dataclass(frozen=True)
+class PasswordPolicy:
+    """Politique de validation des mots de passe.
+
+    Les valeurs par défaut correspondent au niveau de sécurité minimal
+    recommandé par OWASP.
+
+    :param min_length: Longueur minimale (défaut : 12).
+    :param max_length: Longueur maximale (défaut : 256).
+    :param require_letter: Exige au moins une lettre (défaut : True).
+    :param require_digit_or_symbol: Exige au moins un chiffre ou symbole
+        (défaut : True).
+    :param forbid_email_as_password: Interdit l'email comme mot de passe
+        (défaut : True).
+    """
+
+    min_length: int = field(default=_DEFAULT_MIN_LENGTH)
+    max_length: int = field(default=_DEFAULT_MAX_LENGTH)
+    require_letter: bool = field(default=True)
+    require_digit_or_symbol: bool = field(default=True)
+    forbid_email_as_password: bool = field(default=True)
+
+    def validate(
+        self,
+        password: PlainPassword,
+        email: Email | None = None,
+    ) -> None:
+        """Valide un mot de passe selon la politique.
+
+        :param password: Mot de passe en clair à valider.
+        :param email: Adresse email de l'utilisateur (pour la règle d'exclusion).
+        :raises WeakPasswordError: Si le mot de passe ne respecte pas la politique.
+        """
+        value = password.value
+
+        if len(value) < self.min_length:
+            raise WeakPasswordError(
+                f"Le mot de passe doit contenir au moins {self.min_length} caractères."
+            )
+
+        if len(value) > self.max_length:
+            raise WeakPasswordError(
+                f"Le mot de passe ne peut pas dépasser {self.max_length} caractères."
+            )
+
+        if self.require_letter and not any(c.isalpha() for c in value):
+            raise WeakPasswordError(
+                "Le mot de passe doit contenir au moins une lettre."
+            )
+
+        if self.require_digit_or_symbol and not any(
+            c.isdigit() or not c.isalnum() for c in value
+        ):
+            raise WeakPasswordError(
+                "Le mot de passe doit contenir au moins un chiffre ou un symbole."
+            )
+
+        if (
+            self.forbid_email_as_password
+            and email is not None
+            and value.strip().lower() == email.value
+        ):
+            raise WeakPasswordError(
+                "Le mot de passe ne peut pas être identique à l'adresse email."
+            )

baobab_auth_core/domain/policies/role_policy.py

@@ -0,0 +1,30 @@
+"""Politique de gestion des rôles.
+
+:spec: BL-010-004
+"""
+
+from dataclasses import dataclass, field
+
+from baobab_auth_core.domain.value_objects.role_name import RoleName
+
+_DEFAULT_ROLE = "USER"
+_SUPER_ADMIN_ROLE = "SUPER_ADMIN"
+
+
+@dataclass(frozen=True)
+class RolePolicy:
+    """Politique de gestion des rôles et de la hiérarchie.
+
+    :param default_role_name: Rôle attribué automatiquement à tout nouvel utilisateur
+        (défaut : ``USER``).
+    :param super_admin_role_name: Nom du rôle super-administrateur
+        (défaut : ``SUPER_ADMIN``).
+    :param enforce_last_super_admin: Interdit la suppression du dernier super-admin
+        (défaut : True).
+    """
+
+    default_role_name: RoleName = field(default_factory=lambda: RoleName(_DEFAULT_ROLE))
+    super_admin_role_name: RoleName = field(
+        default_factory=lambda: RoleName(_SUPER_ADMIN_ROLE)
+    )
+    enforce_last_super_admin: bool = field(default=True)