mic-struct 0.0.1__py3-none-any.whl

mic/__init__.py

@@ -0,0 +1,9 @@
+"""mic-struct — boilerplate / framework MIC pour l'écosystème microservices.
+
+Cf. README.md et CONTRIBUTING.md.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

mic/_lazy.py

@@ -0,0 +1,80 @@
+"""Lazy package re-exports (PEP 562) — keeps ``import mic.X`` cheap and
+import-safe even when the optional extra for X isn't installed.
+
+Problem
+-------
+A package ``__init__.py`` that eagerly does
+``from mic.X.submodule import Symbol`` forces ``import mic.X`` to import
+``submodule`` at package-load time. If that submodule imports an optional
+dependency at module top-level (``import prometheus_client``,
+``import httpx``, ``import grpc``, …), then ``import mic.X`` **crashes**
+for anyone who ran ``pip install mic-struct`` without the ``[X]`` extra —
+even if they only wanted a stdlib-only symbol from another submodule.
+
+Fix
+---
+Defer the submodule import to first attribute access via PEP 562
+``__getattr__``. ``import mic.X`` only runs ``__init__.py`` itself; the
+heavy submodule loads when (and only when) a symbol from it is used.
+If the optional dependency is missing at that point, the ``ImportError``
+is re-raised with a clear ``pip install 'mic-struct[X]'`` hint.
+
+This keeps the established "Philosophy B" of the codebase consistent:
+*importing a package never fails for a missing optional dependency —
+only actually using the dependency-backed symbol does.*
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from typing import Any
+
+#: Une entrée d'export lazy : ``(chemin du sous-module, nom de l'extra | None)``.
+#: ``extra=None`` = sous-module sans dépendance optionnelle (stdlib only) —
+#: le lazy reste utile pour ne pas charger inutilement, mais pas de
+#: message "install extra" à émettre.
+LazyExport = tuple[str, str | None]
+
+
+def make_lazy_getattr(
+    *,
+    package: str,
+    exports: dict[str, LazyExport],
+    fallback: Callable[[str], Any] | None = None,
+) -> Callable[[str], Any]:
+    """Construit un ``__getattr__`` PEP 562 pour un ``__init__.py`` de package.
+
+    Args:
+        package: le ``__name__`` du package (pour les messages d'erreur).
+        exports: ``{symbole: (sous-module, extra | None)}``. Le sous-module
+            est importé à la demande au premier accès du symbole.
+        fallback: handler optionnel essayé quand le nom n'est **pas** dans
+            ``exports`` (ex: alias deprecated). Doit lever ``AttributeError``
+            s'il ne sait pas résoudre — sinon la vraie ``AttributeError``
+            Python serait masquée.
+
+    Returns:
+        Une fonction ``__getattr__(name) -> Any`` à assigner au niveau
+        module dans le ``__init__.py`` du package.
+    """
+
+    def __getattr__(name: str) -> Any:
+        entry = exports.get(name)
+        if entry is None:
+            if fallback is not None:
+                return fallback(name)
+            raise AttributeError(f"module {package!r} has no attribute {name!r}")
+        module_path, extra = entry
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            if extra is not None:
+                raise ImportError(
+                    f"{package}.{name} requires the optional [{extra}] extra. "
+                    f"Install it with: pip install 'mic-struct[{extra}]'"
+                ) from exc
+            raise
+        return getattr(module, name)
+
+    return __getattr__

mic/auth/__init__.py

@@ -0,0 +1,43 @@
+"""Service-to-service auth — JWT HS256 audience-bound.
+
+- Émetteur signe avec un secret partagé (HS256)
+- Audience-bound (chaque token est destiné à UN service)
+- Double-key support pour rotation zéro-downtime : le verifier accepte
+  N et N-1 pendant la fenêtre de transition.
+
+Import lazy (PEP 562) : ``import mic.auth`` ne charge PAS ``pyjwt``.
+Les symboles tirent ``service_auth`` (donc ``jwt``) au premier accès —
+si l'extra ``[auth]`` n'est pas installé, l'erreur est claire. Cf.
+:mod:`mic._lazy`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mic._lazy import LazyExport, make_lazy_getattr
+
+if TYPE_CHECKING:  # pragma: no cover — résolution de types only, pas de coût runtime
+    from mic.auth.revoke_blacklist import RevokeBlacklist
+    from mic.auth.service_auth import (
+        ServiceAuthClaims,
+        ServiceAuthSigner,
+        ServiceAuthVerifier,
+    )
+
+_EXPORTS: dict[str, LazyExport] = {
+    "ServiceAuthClaims": ("mic.auth.service_auth", "auth"),
+    "ServiceAuthSigner": ("mic.auth.service_auth", "auth"),
+    "ServiceAuthVerifier": ("mic.auth.service_auth", "auth"),
+    # RevokeBlacklist ne tire que mic.cache (core) — pas d'extra requis.
+    "RevokeBlacklist": ("mic.auth.revoke_blacklist", None),
+}
+
+__getattr__ = make_lazy_getattr(package=__name__, exports=_EXPORTS)
+
+__all__ = [
+    "RevokeBlacklist",
+    "ServiceAuthClaims",
+    "ServiceAuthSigner",
+    "ServiceAuthVerifier",
+]

mic/auth/revoke_blacklist.py

@@ -0,0 +1,247 @@
+"""``RevokeBlacklist`` — révocation de JWT court-TTL via :class:`CacheBackend`.
+
+Le pattern *JWT stateless* a une faiblesse intrinsèque : un token signé
+reste valide jusqu'à ``exp``, on ne peut pas l'invalider unilatéralement.
+Pour les use cases qui ont besoin de révocation immédiate (logout, vol
+de token, "logout everywhere"), ce module expose deux mécanismes
+complémentaires backed par n'importe quel :class:`CacheBackend` :
+
+1. **Per-jti** — :meth:`revoke_jti` / :meth:`is_jti_revoked`. Ajoute un
+   ``jti`` spécifique à une blacklist. TTL = lifetime restant du token
+   au moment de la révocation (auto-cleanup à ``exp``). Usage : logout
+   d'un device, rotation refresh token (l'ancien ``jti`` est révoqué).
+
+2. **Per-subject (revoke-epoch)** — :meth:`revoke_all_for_subject` /
+   :meth:`is_subject_revoked_since`. Stocke un timestamp "tous les
+   tokens de ce sujet émis AVANT ce moment sont révoqués". Usage :
+   "logout me everywhere", changement de mot de passe, compromission
+   compte. TTL = max lifetime des tokens longue durée du sujet
+   (typiquement refresh TTL).
+
+L'epoch-pattern bat la SET-per-user d'``jti`` actifs :
+
+- O(1) clé Redis par sujet (vs N entrées à maintenir et nettoyer).
+- Auto-cleanup natif via TTL (vs scan périodique pour purger les
+  jtis expirés d'une SET, Redis ne fait pas TTL par élément).
+- Couvre access + refresh + tokens futurs émis avant le epoch — pas
+  besoin d'énumérer.
+
+L'API reste sync (cohérent avec :class:`CacheBackend` et
+:class:`IdempotencyStore`). Un consumer async wrap via
+``asyncio.to_thread`` si besoin.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+from mic.cache.backends import CacheBackend, CacheError
+
+#: Préfixe par défaut pour les clés ``jti`` révoqués individuellement.
+#: Namespace distinct du subject-epoch pour éviter toute collision
+#: si le caller utilise des sub == jti par accident.
+_DEFAULT_JTI_NAMESPACE = "revoke:jti:"
+
+#: Préfixe par défaut pour le timestamp d'epoch de révocation par sujet.
+_DEFAULT_SUBJECT_NAMESPACE = "revoke:sub:"
+
+#: Valeur sentinel stockée pour les entrées per-jti — seule l'existence
+#: de la clé compte, le payload est ignoré. ``b"1"`` minimise la mémoire
+#: Redis (1 byte vs un timestamp).
+_JTI_PRESENT = b"1"
+
+
+class RevokeBlacklist:
+    """Tracker de révocation pour JWT court-TTL.
+
+    Args:
+        cache: backend cache (typiquement :class:`RedisCache` en prod,
+            :class:`InMemoryCache` en tests). Le backend est partagé
+            avec d'éventuels autres consommateurs — préfixe-isolé via
+            ``jti_namespace`` et ``subject_namespace``.
+        jti_namespace: préfixe des clés per-jti (default ``"revoke:jti:"``).
+        subject_namespace: préfixe des clés per-subject (default
+            ``"revoke:sub:"``).
+        time_fn: source d'horloge en secondes Unix. Injectable pour tests.
+            Default ``lambda: int(time.time())`` (wall-clock — l'epoch
+            DOIT être comparable à ``iat`` du JWT qui est aussi wall-clock).
+
+    ## Pourquoi pas ``time.monotonic`` ?
+
+    L'epoch stocké doit être comparable au claim ``iat`` du JWT, qui est
+    un timestamp Unix wall-clock (cf. RFC 7519 §4.1.6). Utiliser
+    ``time.monotonic`` cassserait la comparaison ``iat < epoch`` : les
+    deux horloges n'ont pas la même origine. Le coût (clock-skew entre
+    replicas) est négligeable ici : un skew de quelques secondes ne change
+    pas la sémantique de "logout everywhere".
+
+    ## Cohérence avec :class:`ServiceAuthVerifier`
+
+    Le verifier `ServiceAuthVerifier` lui-même n'appelle PAS
+    ``RevokeBlacklist`` — c'est au caller (typiquement un middleware
+    d'auth applicatif) de combiner les deux : vérifier la signature
+    via le verifier PUIS interroger la blacklist. Garder les
+    responsabilités séparées permet :
+
+    - Au verifier de rester stateless (pas de dep Redis).
+    - À la blacklist d'être optionnelle (services qui n'ont pas besoin
+      de révocation immédiate).
+    """
+
+    def __init__(
+        self,
+        *,
+        cache: CacheBackend,
+        jti_namespace: str = _DEFAULT_JTI_NAMESPACE,
+        subject_namespace: str = _DEFAULT_SUBJECT_NAMESPACE,
+        time_fn: Callable[[], int] = lambda: int(time.time()),
+    ) -> None:
+        self._cache = cache
+        self._jti_namespace = jti_namespace
+        self._subject_namespace = subject_namespace
+        self._time_fn = time_fn
+
+    # ------------------------------------------------------------------
+    # Per-jti revocation
+    # ------------------------------------------------------------------
+
+    def revoke_jti(self, jti: str, *, ttl_seconds: int) -> None:
+        """Marque un ``jti`` comme révoqué pour ``ttl_seconds`` secondes.
+
+        ``ttl_seconds`` doit être le **lifetime restant** du token au
+        moment de la révocation. Une fois le TTL écoulé, la clé est
+        nettoyée par le backend (Redis EXPIRE) et le ``jti`` est
+        considéré comme à nouveau "non révoqué" — mais c'est OK : à ce
+        moment-là le token lui-même est expiré (``exp`` passée), donc le
+        verifier le rejette de toute façon. La blacklist ne sert qu'à
+        couvrir l'écart entre "révocation" et "expiration naturelle".
+
+        Args:
+            jti: identifiant unique du token (claim JWT ``jti``).
+            ttl_seconds: durée de vie restante du token (≥1).
+
+        Raises:
+            ValueError: si ``jti`` est vide.
+            CacheError: si ``ttl_seconds < 1`` (propagé du backend) ou
+                si le backend est indisponible.
+        """
+        if not jti:
+            raise ValueError("RevokeBlacklist.revoke_jti(jti=...) must be non-empty")
+        # ttl_seconds est validé par le backend (>= 1). On laisse le
+        # CacheError remonter pour cohérence avec les autres consumers.
+        self._cache.set(self._jti_key(jti), _JTI_PRESENT, ttl_seconds=ttl_seconds)
+
+    def is_jti_revoked(self, jti: str) -> bool:
+        """``True`` si le ``jti`` est dans la blacklist active.
+
+        Lookup O(1) en Redis. Le caller (middleware d'auth) appelle
+        cette méthode APRÈS la vérification de signature du
+        :class:`ServiceAuthVerifier` — pas la peine d'interroger Redis
+        sur un token invalide cryptographiquement.
+
+        Args:
+            jti: identifiant du token à tester.
+
+        Returns:
+            ``True`` si révoqué (caller rejette → 401), ``False`` sinon
+            (caller accepte).
+
+        Raises:
+            ValueError: si ``jti`` est vide.
+            CacheError: si le backend est indisponible. Le caller décide
+                de la politique : fail-closed (rejeter, sécurité d'abord)
+                ou fail-open (accepter, disponibilité d'abord). Recommandé
+                fail-closed pour les use cases sécurité-critiques.
+        """
+        if not jti:
+            raise ValueError("RevokeBlacklist.is_jti_revoked(jti=...) must be non-empty")
+        return self._cache.get(self._jti_key(jti)) is not None
+
+    # ------------------------------------------------------------------
+    # Per-subject mass revocation (revoke-epoch)
+    # ------------------------------------------------------------------
+
+    def revoke_all_for_subject(self, subject: str, *, ttl_seconds: int) -> None:
+        """Stocke un epoch "tous les tokens du sujet émis AVANT now sont révoqués".
+
+        Sémantique "logout everywhere" : invalide TOUS les tokens (access
+        + refresh) du sujet émis avant l'instant courant. Les tokens
+        émis APRÈS (typiquement après un nouveau login) sont valides.
+
+        ``ttl_seconds`` doit être >= au TTL max des tokens longue durée
+        du sujet (typiquement refresh token TTL = ~30j). Au-delà, l'epoch
+        est garbage-collected mais c'est OK : à ce moment-là, le token
+        le plus ancien encore en circulation est expiré naturellement.
+
+        Args:
+            subject: identifiant du sujet (``sub`` claim JWT, typiquement
+                ``user_id``). Doit être non-vide.
+            ttl_seconds: durée de rétention de l'epoch (≥1, typiquement
+                = refresh token TTL).
+
+        Raises:
+            ValueError: si ``subject`` est vide.
+            CacheError: si le backend est indisponible.
+
+        Idempotent : appel répété écrase l'epoch avec ``now`` courant
+        (re-clic "logout everywhere" → re-révoque tout token émis
+        entre les deux clics).
+        """
+        if not subject:
+            raise ValueError(
+                "RevokeBlacklist.revoke_all_for_subject(subject=...) must be non-empty"
+            )
+        epoch = self._time_fn()
+        payload = str(epoch).encode("ascii")
+        self._cache.set(self._subject_key(subject), payload, ttl_seconds=ttl_seconds)
+
+    def is_subject_revoked_since(self, subject: str, *, issued_at: int) -> bool:
+        """``True`` si le sujet a un epoch de révocation et ``issued_at < epoch``.
+
+        Le caller (middleware d'auth) appelle cette méthode avec le
+        claim ``iat`` du token vérifié. Si l'epoch existe et que
+        ``iat < epoch`` → token émis avant la révocation → rejeté.
+        Si pas d'epoch (clé absente ou expirée TTL) → ``False`` (jamais
+        révoqué pour ce sujet, ou révocation trop vieille pour matter).
+
+        Args:
+            subject: identifiant du sujet (``sub`` claim).
+            issued_at: timestamp Unix du claim ``iat`` du token.
+
+        Returns:
+            ``True`` si le token doit être rejeté (caller → 401).
+
+        Raises:
+            ValueError: si ``subject`` est vide.
+            CacheError: si le backend est indisponible (cf. politique
+                fail-closed/fail-open documentée sur :meth:`is_jti_revoked`).
+        """
+        if not subject:
+            raise ValueError(
+                "RevokeBlacklist.is_subject_revoked_since(subject=...) must be non-empty"
+            )
+        raw = self._cache.get(self._subject_key(subject))
+        if raw is None:
+            return False
+        try:
+            epoch = int(raw.decode("ascii"))
+        except (UnicodeDecodeError, ValueError) as exc:
+            # Payload corrompu (cache empoisonné, collision de
+            # namespace). Fail-closed : on traite comme révoqué. La
+            # corruption est suffisamment anormale pour qu'on préfère
+            # forcer un re-login plutôt que d'accepter aveuglément.
+            raise CacheError(
+                f"RevokeBlacklist: corrupted subject epoch payload for {subject!r}: {raw!r}"
+            ) from exc
+        return issued_at < epoch
+
+    # ------------------------------------------------------------------
+    # Helpers internes
+    # ------------------------------------------------------------------
+
+    def _jti_key(self, jti: str) -> str:
+        return f"{self._jti_namespace}{jti}"
+
+    def _subject_key(self, subject: str) -> str:
+        return f"{self._subject_namespace}{subject}"