mic-core 0.1.0__tar.gz

mic_core-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+
+# OS / Editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.bak
+
+# Reports / temp
+reports/
+.benchmarks/
+.mutmut-cache/
+.wily/

mic_core-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: mic-core
+Version: 0.1.0
+Summary: MIC — fondations agnostiques (contracts, model, http, auth, client, observability, healthcheck, resilience, cli, grpc).
+License-Expression: MIT
+Requires-Python: >=3.14
+Requires-Dist: pydantic>=2.6
+Provides-Extra: auth
+Requires-Dist: pyjwt<3,>=2.8; extra == 'auth'
+Provides-Extra: cli
+Provides-Extra: client
+Requires-Dist: httpx<1,>=0.27; extra == 'client'
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.115; extra == 'fastapi'
+Requires-Dist: starlette<2,>=1.0.1; extra == 'fastapi'
+Requires-Dist: uvicorn[standard]<1,>=0.30; extra == 'fastapi'
+Provides-Extra: full-observability
+Requires-Dist: opentelemetry-api<2,>=1.27; extra == 'full-observability'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == 'full-observability'
+Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'full-observability'
+Requires-Dist: prometheus-client<1,>=0.20; extra == 'full-observability'
+Requires-Dist: sentry-sdk<3,>=2.20; extra == 'full-observability'
+Requires-Dist: urllib3<3,>=2.7; extra == 'full-observability'
+Provides-Extra: grpc
+Requires-Dist: grpcio-health-checking<2,>=1.66; extra == 'grpc'
+Requires-Dist: grpcio<2,>=1.66; extra == 'grpc'
+Provides-Extra: litestar
+Requires-Dist: litestar<3,>=2.13; extra == 'litestar'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api<2,>=1.27; extra == 'observability'
+Requires-Dist: prometheus-client<1,>=0.20; extra == 'observability'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk<3,>=2.20; extra == 'sentry'
+Requires-Dist: urllib3<3,>=2.7; extra == 'sentry'
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == 'tracing'
+Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# mic-core
+
+Fondations agnostiques du framework **MIC** (Model / Interface / Controller).
+`mic-core` est le socle : il ne dépend d'aucune brique de persistance ni de
+plateforme (voir le DAG `platform → data → core` dans
+[`../README.md`](../README.md)).
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.contracts` | Contrats / DTO partagés inter-couches |
+| `mic.model` | Erreurs de domaine (`DomainError`, `TransientError`), value objects |
+| `mic.http` | Spécifications HTTP **agnostiques** (`HttpRouteSpec`, `HttpResponseSpec`, `HttpCookieSpec`, `HttpRequestContext`) |
+| `mic.fastapi` | Adaptateur FastAPI (router builder, middlewares) — extra `[fastapi]` |
+| `mic.litestar` | Adaptateur Litestar — extra `[litestar]` |
+| `mic.auth` | JWT service-to-service (signer/verifier) — extra `[auth]` |
+| `mic.client` | Client HTTP inter-services (httpx) — extra `[client]` |
+| `mic.observability` | Logs JSON, métriques Prometheus, traces OTel — extra `[observability]` / `[full-observability]` |
+| `mic.healthcheck` | Sondes liveness/readiness |
+| `mic.resilience` | Circuit breaker, retry, timeouts |
+| `mic.cli` | Squelette CLI (argparse stdlib) — extra `[cli]` |
+| `mic.grpc` | Transport gRPC — extra `[grpc]` |
+
+Le paquet est un **namespace PEP 420** (pas de `mic/__init__.py`) : `import mic.*`
+reste identique côté consommateur, qu'on installe `mic-core` seul ou avec
+`mic-datastore` / `mic-platform`.
+
+## Installation
+
+```bash
+pip install "mic-core[fastapi,auth,client,observability]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `fastapi` | fastapi + uvicorn[standard] + starlette |
+| `litestar` | litestar |
+| `auth` | pyjwt |
+| `client` | httpx |
+| `observability` | prometheus-client + opentelemetry-api |
+| `sentry` | sentry-sdk (+ urllib3 patché) |
+| `tracing` | opentelemetry-sdk + exporter OTLP |
+| `full-observability` | `observability` + `sentry` + `tracing` |
+| `grpc` | grpcio + grpcio-health-checking |
+| `cli` | (rien — argparse stdlib) |
+
+## Versionnage
+
+`mic-core` démarre en `0.x` (pré-releases `dev`/`rc` sur TestPyPI). Il **graduera
+en `1.0`** une fois les frontières prouvées et les services migrés (fin du split,
+cf. [ADR-0001](../../docs/decisions/ADR-0001-split-mic-struct-into-three-packages.md)).
+En `0.x`, un bump *minor* peut porter un changement cassant (SemVer 0.x) —
+contraindre avec `>=0.1,<1`.
+
+## Release
+
+Voir [`../../RELEASING.md`](../../RELEASING.md) § « Release par paquet »
+(`make release-pkg PKG=core VERSION=x.y.z` → tag `core-vX.Y.Z`).

mic_core-0.1.0/README.md

@@ -0,0 +1,61 @@
+# mic-core
+
+Fondations agnostiques du framework **MIC** (Model / Interface / Controller).
+`mic-core` est le socle : il ne dépend d'aucune brique de persistance ni de
+plateforme (voir le DAG `platform → data → core` dans
+[`../README.md`](../README.md)).
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.contracts` | Contrats / DTO partagés inter-couches |
+| `mic.model` | Erreurs de domaine (`DomainError`, `TransientError`), value objects |
+| `mic.http` | Spécifications HTTP **agnostiques** (`HttpRouteSpec`, `HttpResponseSpec`, `HttpCookieSpec`, `HttpRequestContext`) |
+| `mic.fastapi` | Adaptateur FastAPI (router builder, middlewares) — extra `[fastapi]` |
+| `mic.litestar` | Adaptateur Litestar — extra `[litestar]` |
+| `mic.auth` | JWT service-to-service (signer/verifier) — extra `[auth]` |
+| `mic.client` | Client HTTP inter-services (httpx) — extra `[client]` |
+| `mic.observability` | Logs JSON, métriques Prometheus, traces OTel — extra `[observability]` / `[full-observability]` |
+| `mic.healthcheck` | Sondes liveness/readiness |
+| `mic.resilience` | Circuit breaker, retry, timeouts |
+| `mic.cli` | Squelette CLI (argparse stdlib) — extra `[cli]` |
+| `mic.grpc` | Transport gRPC — extra `[grpc]` |
+
+Le paquet est un **namespace PEP 420** (pas de `mic/__init__.py`) : `import mic.*`
+reste identique côté consommateur, qu'on installe `mic-core` seul ou avec
+`mic-datastore` / `mic-platform`.
+
+## Installation
+
+```bash
+pip install "mic-core[fastapi,auth,client,observability]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `fastapi` | fastapi + uvicorn[standard] + starlette |
+| `litestar` | litestar |
+| `auth` | pyjwt |
+| `client` | httpx |
+| `observability` | prometheus-client + opentelemetry-api |
+| `sentry` | sentry-sdk (+ urllib3 patché) |
+| `tracing` | opentelemetry-sdk + exporter OTLP |
+| `full-observability` | `observability` + `sentry` + `tracing` |
+| `grpc` | grpcio + grpcio-health-checking |
+| `cli` | (rien — argparse stdlib) |
+
+## Versionnage
+
+`mic-core` démarre en `0.x` (pré-releases `dev`/`rc` sur TestPyPI). Il **graduera
+en `1.0`** une fois les frontières prouvées et les services migrés (fin du split,
+cf. [ADR-0001](../../docs/decisions/ADR-0001-split-mic-struct-into-three-packages.md)).
+En `0.x`, un bump *minor* peut porter un changement cassant (SemVer 0.x) —
+contraindre avec `>=0.1,<1`.
+
+## Release
+
+Voir [`../../RELEASING.md`](../../RELEASING.md) § « Release par paquet »
+(`make release-pkg PKG=core VERSION=x.y.z` → tag `core-vX.Y.Z`).

mic_core-0.1.0/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_core-0.1.0/mic/auth/__init__.py

@@ -0,0 +1,39 @@
+"""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.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"),
+}
+
+__getattr__ = make_lazy_getattr(package=__name__, exports=_EXPORTS)
+
+__all__ = [
+    "ServiceAuthClaims",
+    "ServiceAuthSigner",
+    "ServiceAuthVerifier",
+]

mic_core-0.1.0/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.cache.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.cache.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_core-0.1.0/mic/cli/__init__.py

@@ -0,0 +1,24 @@
+"""CLI canon — argparse stdlib + ``CliCommandSpec`` builder.
+
+Cf. R12 dans ``CONTRIBUTING.md`` :
+
+- Tout service avec opérations opérateur (drain, requeue,
+  reindex, query, replay, …) doit livrer un CLI via cette brique.
+- Framework imposé : ``argparse`` stdlib (pas de Click/Typer).
+- 1 fichier ``frameworks/cli/<groupe>_commands.py`` par bounded
+  context, chaque commande exposée via un ``CliCommandSpec``.
+
+L'extra ``mic-struct[cli]`` existe pour cohérence — ``mic.cli`` n'a
+aucune dépendance externe (stdlib only).
+"""
+
+from __future__ import annotations
+
+from mic.cli.builder import build_parser, dispatch
+from mic.cli.spec import CliCommandSpec
+
+__all__ = [
+    "CliCommandSpec",
+    "build_parser",
+    "dispatch",
+]