mic-struct 0.0.1__py3-none-any.whl

mic/auth/service_auth.py

@@ -0,0 +1,317 @@
+"""ServiceAuthSigner + ServiceAuthVerifier — JWT HS256 audience-bound.
+
+Convention (cf. ``service_auth_convention`` mémoire +
+``runbooks/RUNBOOK_SECRETS_ROTATION.md`` sentinel) :
+
+- Algorithme : HS256 uniquement (pas RS256 ; les services partagent
+  un secret commun gardé en OpenBao).
+- Claims standard : ``iss`` (émetteur), ``aud`` (destinataire),
+  ``iat``, ``exp``, ``sub`` optionnel.
+- Double-key : ``ServiceAuthVerifier`` accepte une liste ordonnée
+  de secrets (``current`` puis ``previous``) pour permettre une
+  rotation sans downtime — cf. RUNBOOK_SECRETS_ROTATION.md procédure
+  générique étape 2-3.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+
+from mic.contracts import StrictSchema
+from mic.model.errors import DomainError
+
+_ALGORITHM = "HS256"
+
+_logger = logging.getLogger(__name__)
+
+#: Claims standard que ``ServiceAuthSigner.sign`` met lui-même —
+#: les overrider via ``extra_claims`` permettrait à un caller de forger
+#: un ``aud`` arbitraire, faussement étendre ``exp``, falsifier ``iss``,
+#: etc. On refuse explicitement (cf. ``sign(extra_claims=...)``).
+_RESERVED_CLAIMS: frozenset[str] = frozenset({"iss", "aud", "iat", "exp", "sub", "jti", "nbf"})
+
+# Message constant retourné dans tous les DomainError de verify. On NE
+# leak PAS les détails PyJWT (str(last_error)) au caller — un attacker
+# peut sinon distinguer "signature valide mais expirée" (= il a un
+# secret valide juste périmé) vs "signature invalide" (= mauvais secret),
+# oracle particulièrement utile pendant les fenêtres de rotation. Les
+# détails (exc_info + issuer whitelist) sont loggés côté serveur via
+# ``_logger.warning(..., exc_info=True)`` pour la diagnose ops.
+_GENERIC_VERIFY_FAILURE_MESSAGE = "Token verification failed"
+
+
+class ServiceAuthClaims(StrictSchema):
+    """Claims canoniques exposés par un service token.
+
+    ``jti`` (RFC 7519 §4.1.7) est exposé optionnellement : il est
+    automatiquement injecté par :meth:`ServiceAuthSigner.sign` depuis
+    cette version, mais reste ``None`` quand on vérifie un token
+    émis par une version antérieure ou par un autre service qui ne
+    le propage pas. C'est OK : ``jti`` est une RECOMMENDED claim, pas
+    un REQUIRED claim — l'absence n'est pas une erreur de validation.
+
+    Pour les consommateurs qui font de la révocation per-token
+    (typiquement via :class:`mic.auth.RevokeBlacklist.revoke_jti`),
+    vérifier ``claims.jti is not None`` avant de l'utiliser : un
+    ``None`` signale qu'on ne peut pas révoquer ce token
+    spécifiquement, seulement via la voie per-subject (revoke-epoch).
+
+    ``extra`` porte les claims additionnels embedés par le signer via
+    ``ServiceAuthSigner.sign(extra_claims=...)``. Use case : un service
+    qui propage ``profile_id`` aux côtés du ``sub`` standard pour
+    éviter un lookup DB aval. Dictionnaire vide quand le token n'embed
+    aucun claim non-standard. Les valeurs sont opaques pour mic — le
+    consumer décide leur sémantique.
+    """
+
+    iss: str
+    aud: str
+    iat: int
+    exp: int
+    sub: str | None = None
+    jti: str | None = None
+    # Pydantic copie le default per-instance via Field — ``RUF012`` ne
+    # s'applique pas aux BaseModel. ``noqa`` cosmétique mais explicite.
+    extra: dict[str, Any] = {}  # noqa: RUF012
+
+
+class ServiceAuthSigner:
+    """Signe des JWT HS256 audience-bound.
+
+    Une instance par couple (issuer, secret). L'audience est passée
+    à chaque appel ``sign()`` puisque le même service appelle souvent
+    plusieurs destinataires.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        issuer: str,
+        token_ttl_seconds: int = 3600,
+    ) -> None:
+        if not secret:
+            raise ValueError("ServiceAuthSigner.secret must be a non-empty string")
+        if not issuer:
+            raise ValueError("ServiceAuthSigner.issuer must be a non-empty string")
+        if token_ttl_seconds <= 0:
+            raise ValueError("ServiceAuthSigner.token_ttl_seconds must be > 0")
+        self._secret = secret
+        self._issuer = issuer
+        self._token_ttl = token_ttl_seconds
+
+    def sign(
+        self,
+        *,
+        audience: str,
+        subject: str | None = None,
+        jti: str | None = None,
+        extra_claims: dict[str, Any] | None = None,
+    ) -> str:
+        """Build a Bearer JWT signed with the configured secret.
+
+        Returns the encoded JWT string (no "Bearer " prefix — the
+        client adds it).
+
+        Args:
+            audience: ``aud`` claim — destinataire attendu (un service
+                par token).
+            subject: ``sub`` claim — identité propagée (typiquement
+                user_id ou email pour les tokens user-side).
+            jti: ``jti`` claim (RFC 7519 §4.1.7) — identifiant unique
+                du token. **Auto-généré** via ``uuid.uuid4().hex`` (128
+                bits d'entropie) si ``None``, ce qui est le cas standard.
+                Override uniquement pour les tests qui ont besoin de
+                jtis déterministes, ou pour les use cases avancés
+                (ex. propager un trace-id en jti). Si fourni, doit être
+                non-vide.
+            extra_claims: claims additionnels à embedder dans le JWT.
+                Use case typique : propager une identité applicative
+                secondaire (``profile_id``, ``tenant_id``, ``role``)
+                aux côtés du ``sub`` standard pour éviter un lookup DB
+                aval. Les claims standard (``iss``, ``aud``, ``iat``,
+                ``exp``, ``sub``, ``jti``) ne peuvent PAS être
+                overridées via ce paramètre — un override silencieux
+                permettrait à un caller de forger un ``aud`` arbitraire
+                ou de faussement étendre l'``exp``. Une tentative lève
+                ``ValueError``.
+
+        Le ``jti`` permet aux consumers de faire de la révocation
+        per-token via :class:`mic.auth.RevokeBlacklist` (``revoke_jti``,
+        ``is_jti_revoked``) — usage typique : logout-single-device en
+        ajoutant l'ancien ``jti`` à la blacklist à TTL = lifetime
+        restant du token.
+        """
+        if not audience:
+            raise ValueError("ServiceAuthSigner.sign(audience=...) must be non-empty")
+        if jti is not None and not jti:
+            raise ValueError("ServiceAuthSigner.sign(jti=...) must be non-empty when provided")
+        if extra_claims is not None:
+            reserved = _RESERVED_CLAIMS & extra_claims.keys()
+            if reserved:
+                raise ValueError(
+                    f"ServiceAuthSigner.sign(extra_claims=...) cannot override "
+                    f"reserved claim(s): {sorted(reserved)}"
+                )
+        now = datetime.now(UTC)
+        payload: dict[str, Any] = {
+            "iss": self._issuer,
+            "aud": audience,
+            "iat": int(now.timestamp()),
+            "exp": int((now + timedelta(seconds=self._token_ttl)).timestamp()),
+            "jti": jti if jti is not None else uuid.uuid4().hex,
+        }
+        if subject is not None:
+            payload["sub"] = subject
+        if extra_claims:
+            payload.update(extra_claims)
+        return jwt.encode(payload, self._secret, algorithm=_ALGORITHM)
+
+
+class ServiceAuthVerifier:
+    """Vérifie les JWT HS256 destinés à ce service.
+
+    Supporte la rotation à zéro-downtime via une **liste ordonnée**
+    de secrets : le verifier essaye le ``current`` d'abord, puis les
+    ``previous`` un par un. Tant qu'au moins un secret valide
+    correspond ET que les claims passent (audience, issuer, expiration),
+    le token est accepté.
+
+    L'``audience`` attendue est fixe par instance (= app name de ce
+    service). Les ``allowed_issuers`` est la liste des émetteurs
+    légitimes (whitelist).
+    """
+
+    def __init__(
+        self,
+        *,
+        secrets: tuple[str, ...],
+        audience: str,
+        allowed_issuers: tuple[str, ...],
+        leeway_seconds: int = 30,
+    ) -> None:
+        # leeway 30s par défaut = tolérance NTP-skew typique entre 2
+        # services. Sans ça, une dérive d'1s entre signer et verifier
+        # rejette le token (``iat`` dans le futur OU ``exp`` expirée).
+        # 30s = compromis : couvre 99 % des skews observés en cluster
+        # sans ouvrir une fenêtre de replay critique.
+        if not secrets:
+            raise ValueError("ServiceAuthVerifier.secrets must be non-empty tuple")
+        if any(not s for s in secrets):
+            raise ValueError("ServiceAuthVerifier.secrets must not contain empty strings")
+        if not audience:
+            raise ValueError("ServiceAuthVerifier.audience must be non-empty")
+        if not allowed_issuers:
+            raise ValueError("ServiceAuthVerifier.allowed_issuers must be non-empty tuple")
+        if leeway_seconds < 0:
+            raise ValueError("ServiceAuthVerifier.leeway_seconds must be >= 0")
+        self._secrets = secrets
+        self._audience = audience
+        self._allowed_issuers = set(allowed_issuers)
+        self._leeway = leeway_seconds
+
+    def verify(self, token: str) -> ServiceAuthClaims:
+        """Vérifie le token et retourne les claims parsés.
+
+        Raises ``DomainError`` (code ``service_auth.invalid_*``) si :
+
+        - signature ne match aucun secret (current ou previous)
+        - exp dépassée (au-delà du leeway)
+        - aud != self.audience
+        - iss not in allowed_issuers
+        - structure du token invalide
+
+        **Timing-safe iteration** : tous les secrets de la
+        liste sont essayés systématiquement, sans early break sur le
+        premier match. Sans ça, un attacker qui mesure la latence à la
+        μs peut deviner la **position** du secret valide (``current``
+        vs ``previous``) → side-channel mineur mais réel pendant la
+        fenêtre de rotation. Coût : 1 HMAC supplémentaire par requête
+        (≪ 1 μs) — négligeable.
+        """
+        if not token:
+            raise DomainError(
+                code="service_auth.invalid_token",
+                message="Empty token",
+            )
+
+        payload: dict[str, Any] | None = None
+        last_error: jwt.PyJWTError | None = None
+        for secret in self._secrets:
+            try:
+                candidate = jwt.decode(
+                    token,
+                    secret,
+                    algorithms=[_ALGORITHM],
+                    audience=self._audience,
+                    leeway=self._leeway,
+                    options={"require": ["iss", "aud", "iat", "exp"]},
+                )
+            except jwt.PyJWTError as exc:
+                last_error = exc
+                continue
+            # Garde le PREMIER payload valide trouvé, mais on continue
+            # d'itérer pour ne pas leak la position via timing.
+            if payload is None:
+                payload = candidate
+
+        if payload is None:
+            # Toutes les secrets ont échoué. On retourne au caller un
+            # ``code`` catégorisé (contrat public — utile pour l'UX :
+            # ``expired`` vs ``invalid_signature``) mais **aucun message
+            # détaillé ni stacktrace** : ce serait un oracle pour
+            # l'attacker (cf. constante ``_GENERIC_VERIFY_FAILURE_MESSAGE``).
+            # La cause précise (str(last_error)) est loggée côté serveur
+            # pour la diagnose ops.
+            code = _classify_error(last_error)
+            _logger.warning(
+                "ServiceAuthVerifier: token verification failed (code=%s)",
+                code,
+                exc_info=last_error,
+            )
+            raise DomainError(code=code, message=_GENERIC_VERIFY_FAILURE_MESSAGE)
+
+        issuer = payload.get("iss")
+        if issuer not in self._allowed_issuers:
+            # Ne pas leaker ``self._allowed_issuers`` au caller — c'est
+            # de la recon précieuse (liste des services internes connus).
+            # On garde le ``code`` précis pour le caller légitime, et
+            # on log la valeur reçue + la whitelist server-side.
+            _logger.warning(
+                "ServiceAuthVerifier: issuer rejected (received=%r, allowed=%s)",
+                issuer,
+                sorted(self._allowed_issuers),
+            )
+            raise DomainError(
+                code="service_auth.invalid_issuer",
+                message=_GENERIC_VERIFY_FAILURE_MESSAGE,
+            )
+
+        # Sépare les claims standard (typés sur ServiceAuthClaims) des
+        # claims additionnels embedés via ``ServiceAuthSigner.sign(
+        # extra_claims=...)``. Les non-standard atterrissent dans
+        # ``extra``, opaques pour mic mais accessibles au consumer.
+        standard_claims = {"iss", "aud", "iat", "exp", "sub", "jti"}
+        normalized: dict[str, Any] = {k: v for k, v in payload.items() if k in standard_claims}
+        normalized["extra"] = {k: v for k, v in payload.items() if k not in standard_claims}
+        return ServiceAuthClaims.model_validate(normalized)
+
+
+def _classify_error(error: jwt.PyJWTError | None) -> str:
+    """Mapping fin des erreurs PyJWT vers code DomainError."""
+    if isinstance(error, jwt.ExpiredSignatureError):
+        return "service_auth.expired"
+    if isinstance(error, jwt.InvalidAudienceError):
+        return "service_auth.invalid_audience"
+    if isinstance(error, jwt.InvalidSignatureError):
+        return "service_auth.invalid_signature"
+    if isinstance(error, jwt.MissingRequiredClaimError):
+        return "service_auth.missing_claim"
+    if isinstance(error, jwt.DecodeError):
+        return "service_auth.malformed"
+    return "service_auth.invalid_token"

mic/authz/__init__.py

@@ -0,0 +1,60 @@
+"""Authorization (authz) — qui peut faire quoi sur quoi.
+
+Distinct de :mod:`mic.auth` (authn = qui es-tu, JWT verification).
+``mic.authz`` répond à la question : **étant donné que tu es X, peux-tu
+faire Y sur Z ?**
+
+Architecture (Protocol-based, comme :mod:`mic.datastorage`) :
+
+- :class:`AuthorizationEngine` (ABC) : ``check(subject, action,
+  resource)`` retourne ``bool``. Tout backend authz le satisfait
+  structurellement.
+- :class:`AuthorizationDeniedError` : sous-classe de ``DomainError``
+  mappée HTTP **403** (cf. ``http_status_code``). À lever quand
+  ``check()`` retourne ``False``.
+
+Backends fournis :
+
+- :class:`InMemoryAuthorizationEngine` — RBAC simple (subject → roles
+  → permissions). Pour dev / tests. Aucune dépendance externe.
+- :class:`OpaAuthorizationEngine` (extra ``[opa]``) — Open Policy
+  Agent via REST API. Pour des politiques Rego complexes.
+- :class:`OpenFgaAuthorizationEngine` (extra ``[openfga]``) — OpenFGA
+  via REST API (modèle Google Zanzibar / ReBAC fine-grain). Pour
+  des relations transitives (groupes, parents, héritage).
+
+Usage typique :
+
+    from mic.authz import (
+        AuthorizationEngine, AuthorizationDeniedError,
+        InMemoryAuthorizationEngine,
+    )
+
+    engine: AuthorizationEngine = InMemoryAuthorizationEngine()
+    engine.grant_role("user:42", role="admin")
+    engine.bind_role_to_permission("admin", action="users.delete", resource="*")
+
+    if not engine.check(subject="user:42", action="users.delete", resource="user:99"):
+        raise AuthorizationDeniedError(
+            code="authz.users_delete_forbidden",
+            message="cannot delete users",
+        )
+
+Pour ajouter un nouveau backend (Casbin, Permify, Cerbos, AWS IAM,
+Keto, ...) : implémenter ``check()`` (signature unique du Protocol).
+Pas d'héritage forcé.
+"""
+
+from mic.authz.base import AuthorizationEngine
+from mic.authz.errors import AuthorizationDeniedError
+from mic.authz.in_memory import InMemoryAuthorizationEngine
+from mic.authz.opa import OpaAuthorizationEngine
+from mic.authz.openfga import OpenFgaAuthorizationEngine
+
+__all__ = [
+    "AuthorizationDeniedError",
+    "AuthorizationEngine",
+    "InMemoryAuthorizationEngine",
+    "OpaAuthorizationEngine",
+    "OpenFgaAuthorizationEngine",
+]

mic/authz/base.py

@@ -0,0 +1,44 @@
+"""``AuthorizationEngine`` ABC — abstraction d'un backend authz.
+
+Méthode unique : ``check(subject, action, resource)`` retourne True si
+le sujet a le droit d'exécuter l'action sur la ressource.
+
+Convention sur les paramètres :
+
+- ``subject`` : identifiant stable du sujet — typiquement
+  ``user:<uuid>`` ou ``service:<name>``. Préfixe libre, c'est le
+  consumer qui définit son schéma.
+- ``action`` : verbe métier — ``users.delete``, ``mail.send``,
+  ``profile.read``. Convention ``<domain>.<verb>`` cohérente avec
+  les codes ``DomainError``.
+- ``resource`` : identifiant de la ressource — ``user:99``,
+  ``profile:42``, ``*`` (wildcard). Le format est libre et propre
+  au backend (ex: OpenFGA utilise ``type:id``, Cerbos utilise des
+  ressources structurées, etc.).
+
+Le retour est binaire (True/False) — pas de "raisons partielles", pas
+de "obligations" (= conditions à appliquer post-décision). Si vous
+avez besoin de ces niveaux de richesse, le backend expose ses
+primitives natives en plus (ex: ``opa.evaluate(input)`` complet).
+
+Cf. CONTRIBUTING.md "ABC vs Protocol" pour le rationnel du choix ABC.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AuthorizationEngine(ABC):
+    """Backend d'authorisation — ``check(subject, action, resource)``.
+
+    Doit retourner ``True`` si le sujet a le droit, ``False`` sinon.
+    Ne lève **jamais** sur une décision négative (= c'est au consumer
+    de lever ``AuthorizationDeniedError`` selon son besoin). Peut
+    lever sur erreur d'infrastructure (backend OPA injoignable,
+    config malformée, etc.) — le consumer décide alors si ça doit
+    être un fail-open ou fail-close.
+    """
+
+    @abstractmethod
+    def check(self, *, subject: str, action: str, resource: str) -> bool: ...

mic/authz/errors.py

@@ -0,0 +1,27 @@
+"""``AuthorizationDeniedError`` — DomainError sous-typée mappée HTTP 403.
+
+Convention :
+- ``DomainError`` (default) → 400 (erreur métier client).
+- ``TransientError`` → 503 (panne temporaire upstream).
+- ``AuthorizationDeniedError`` → 403 (subject authentifié mais sans
+  droit sur la ressource).
+
+À distinguer de :
+- 401 Unauthorized = le subject n'est PAS authentifié (token absent /
+  invalide). Géré par ``ServiceAuthVerifier`` côté middleware.
+- 403 Forbidden = le subject EST authentifié mais le contrôle authz
+  refuse l'action. C'est ``AuthorizationDeniedError``.
+"""
+
+from __future__ import annotations
+
+from mic.model.errors import DomainError
+
+
+class AuthorizationDeniedError(DomainError):
+    """Authorization denied — subject autorisé mais sans droit suffisant.
+
+    Mappée HTTP **403** par les adapters via ``http_status_code``.
+    """
+
+    http_status_code: int = 403

mic/authz/in_memory.py

@@ -0,0 +1,91 @@
+"""``InMemoryAuthorizationEngine`` — RBAC simple en RAM.
+
+Implémentation de référence pédagogique qui satisfait
+:class:`AuthorizationEngine`. Pour dev / tests.
+
+Modèle RBAC (3 niveaux, classique) :
+
+- subject → roles  (un subject peut avoir plusieurs roles)
+- role → permissions (action, resource_pattern)
+- permission match : action == p.action ET (resource == p.resource OU
+  p.resource == "*")
+
+Pas de hiérarchie de roles, pas de scope, pas de conditions. Pour des
+politiques riches, voir :class:`OpaAuthorizationEngine` ou
+``OpenFgaAuthorizationEngine`` (v1.8).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mic.authz.base import AuthorizationEngine
+
+
+@dataclass(frozen=True, slots=True)
+class _Permission:
+    action: str
+    resource: str
+
+
+class InMemoryAuthorizationEngine(AuthorizationEngine):
+    """RBAC simple en RAM, implémente :class:`AuthorizationEngine`."""
+
+    def __init__(self) -> None:
+        self._subject_roles: dict[str, set[str]] = {}
+        self._role_permissions: dict[str, set[_Permission]] = {}
+
+    # ------------------------------------------------------------------
+    # Mutation API (admin)
+    # ------------------------------------------------------------------
+
+    def grant_role(self, subject: str, *, role: str) -> None:
+        """Attribue un rôle à un subject."""
+        self._subject_roles.setdefault(subject, set()).add(role)
+
+    def revoke_role(self, subject: str, *, role: str) -> None:
+        """Retire un rôle d'un subject. No-op si déjà absent."""
+        roles = self._subject_roles.get(subject)
+        if roles is not None:
+            roles.discard(role)
+
+    def bind_role_to_permission(self, role: str, *, action: str, resource: str) -> None:
+        """Associe une permission (action, resource) à un rôle.
+
+        ``resource="*"`` = wildcard (la permission match toute resource
+        pour cette action).
+        """
+        self._role_permissions.setdefault(role, set()).add(
+            _Permission(action=action, resource=resource)
+        )
+
+    def unbind_role_from_permission(self, role: str, *, action: str, resource: str) -> None:
+        """Retire une permission d'un rôle. No-op si déjà absente."""
+        perms = self._role_permissions.get(role)
+        if perms is not None:
+            perms.discard(_Permission(action=action, resource=resource))
+
+    # ------------------------------------------------------------------
+    # AuthorizationEngine Protocol
+    # ------------------------------------------------------------------
+
+    def check(self, *, subject: str, action: str, resource: str) -> bool:
+        """True si le subject a au moins un rôle qui couvre l'(action, resource)."""
+        roles = self._subject_roles.get(subject, set())
+        for role in roles:
+            for perm in self._role_permissions.get(role, set()):
+                if perm.action == action and perm.resource in (resource, "*"):
+                    return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Introspection (debug)
+    # ------------------------------------------------------------------
+
+    def roles_of(self, subject: str) -> frozenset[str]:
+        """Retourne les rôles d'un subject (frozen, pour ne pas leaker la mutation)."""
+        return frozenset(self._subject_roles.get(subject, set()))
+
+    def permissions_of(self, role: str) -> frozenset[tuple[str, str]]:
+        """Retourne les permissions d'un rôle sous forme de tuples (action, resource)."""
+        return frozenset((p.action, p.resource) for p in self._role_permissions.get(role, set()))

mic/authz/opa.py

@@ -0,0 +1,131 @@
+"""``OpaAuthorizationEngine`` — Open Policy Agent backend via REST.
+
+Démontre comment satisfaire :class:`AuthorizationEngine` sur un
+backend externe (sidecar OPA HTTP). Lisez ce fichier si vous voulez
+écrire votre propre backend (Casbin, Permify, Cerbos, Keto, ...).
+
+Convention :
+- ``httpx`` est tiré par l'extra ``[client]`` (déjà présent pour
+  ``ServiceHttpClient``). L'extra dédié ``[opa]`` ne tire **rien**
+  de plus — c'est un alias documentaire.
+- L'OPA endpoint attendu : ``POST {policy_url}`` avec body
+  ``{"input": {"subject": ..., "action": ..., "resource": ...}}``.
+  Réponse attendue : ``{"result": {"allow": true|false}}``.
+- ``fail_close=True`` (default) : si OPA injoignable / réponse
+  malformée → ``check()`` retourne ``False`` (= refuser par
+  défaut, principe de moindre privilège).
+
+Politique Rego type :
+
+    package mic.authz
+
+    default allow := false
+
+    allow if {
+        input.action == "users.read"
+        startswith(input.subject, "user:")
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mic.authz.base import AuthorizationEngine
+
+_logger = logging.getLogger("mic.authz.opa")
+
+_HTTP_OK = 200
+
+
+class OpaAuthorizationEngine(AuthorizationEngine):
+    """Backend OPA via REST API. Implémente :class:`AuthorizationEngine`.
+
+    Args:
+        policy_url: URL complète de l'endpoint policy OPA. Format
+            typique : ``http://opa-sidecar:8181/v1/data/<package>/allow``.
+        timeout_seconds: timeout réseau HTTP. Default 1s — OPA en
+            sidecar est généralement < 10ms en latence locale.
+        client: ``httpx.Client`` pré-construit (utile en tests).
+        fail_close: si True (default), un OPA injoignable / réponse
+            malformée → ``check()`` retourne ``False``. Si False,
+            retourne ``True`` (fail-open : utile en dev local sans
+            OPA, dangereux en prod).
+    """
+
+    def __init__(
+        self,
+        *,
+        policy_url: str,
+        timeout_seconds: float = 1.0,
+        client: Any = None,
+        fail_close: bool = True,
+    ) -> None:
+        if not policy_url:
+            raise ValueError("OpaAuthorizationEngine.policy_url must be non-empty")
+        self._policy_url = policy_url
+        self._timeout_seconds = timeout_seconds
+        self._fail_close = fail_close
+        if client is not None:
+            self._client = client
+        else:
+            try:
+                import httpx  # noqa: PLC0415 — optional dep guard
+            except ImportError as exc:
+                raise ImportError(
+                    "httpx not installed. Install with: pip install 'mic-struct[client]'"
+                ) from exc
+            self._client = httpx.Client(timeout=timeout_seconds)
+
+    @property
+    def native(self) -> Any:
+        """Le ``httpx.Client`` natif — escape-hatch pour les requêtes
+        OPA non couvertes par ``check`` (data API, query API, batch
+        evaluations). Aligné avec ``.native`` MIC.
+        """
+        return self._client
+
+    def check(self, *, subject: str, action: str, resource: str) -> bool:
+        """POST l'input à OPA et retourne la décision.
+
+        En cas d'erreur réseau / format de réponse inattendu, retourne
+        ``not self._fail_close`` (= False par default = refuser).
+        """
+        payload = {
+            "input": {
+                "subject": subject,
+                "action": action,
+                "resource": resource,
+            }
+        }
+        try:
+            response = self._client.post(self._policy_url, json=payload)
+        except Exception as exc:
+            _logger.warning("OPA check failed (network): %s", exc)
+            return not self._fail_close
+
+        if response.status_code != _HTTP_OK:
+            _logger.warning(
+                "OPA check returned HTTP %s : %s",
+                response.status_code,
+                response.text[:200],
+            )
+            return not self._fail_close
+
+        try:
+            body = response.json()
+        except Exception as exc:
+            _logger.warning("OPA check : invalid JSON response: %s", exc)
+            return not self._fail_close
+
+        result = body.get("result")
+        if isinstance(result, bool):
+            # OPA peut retourner directement {"result": true|false}
+            return result
+        if isinstance(result, dict):
+            allow = result.get("allow")
+            if isinstance(allow, bool):
+                return allow
+        _logger.warning("OPA check : unexpected result shape: %r", result)
+        return not self._fail_close