mic-platform 0.1.0__tar.gz

mic_platform-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_platform-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: mic-platform
+Version: 0.1.0
+Summary: MIC — policy & contrôle (authz OPA/OpenFGA, ratelimit).
+License-Expression: MIT
+Requires-Python: >=3.14
+Requires-Dist: mic-core
+Requires-Dist: mic-datastore
+Provides-Extra: opa
+Requires-Dist: mic-core[client]; extra == 'opa'
+Provides-Extra: openfga
+Requires-Dist: mic-core[client]; extra == 'openfga'
+Provides-Extra: redis
+Requires-Dist: mic-datastore[redis]; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# mic-platform
+
+Briques **policy & contrôle** du framework MIC. Sommet du DAG
+`platform → data → core` : dépend de `mic-core` ET `mic-datastore`.
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.authz` | Autorisation : moteur in-memory, OPA, OpenFGA (appels API **via httpx**) |
+| `mic.ratelimit` | Rate limiting (in-memory / Redis Lua) + `RateLimitMiddleware` |
+
+Namespace **PEP 420** (pas de `mic/__init__.py`).
+
+## Installation
+
+```bash
+pip install "mic-platform[openfga,redis]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `opa` | `mic-core[client]` (httpx — appels HTTP vers l'agent OPA) |
+| `openfga` | `mic-core[client]` (httpx — API OpenFGA ; **pas** le SDK officiel) |
+| `redis` | `mic-datastore[redis]` (backend Lua du rate limiter) |
+
+> ℹ️ L'adaptateur OpenFGA (`mic.authz.openfga`) parle à l'API HTTP via `httpx`,
+> il n'utilise **pas** `openfga-sdk`.
+
+## Versionnage
+
+Brique volatile (OPA/OpenFGA bougent vite) — reste en `0.x`. Contraindre avec
+`>=0.1,<1`. Release : `make release-pkg PKG=platform VERSION=x.y.z` → tag
+`platform-vX.Y.Z` (cf. [`../../RELEASING.md`](../../RELEASING.md)).

mic_platform-0.1.0/README.md

@@ -0,0 +1,36 @@
+# mic-platform
+
+Briques **policy & contrôle** du framework MIC. Sommet du DAG
+`platform → data → core` : dépend de `mic-core` ET `mic-datastore`.
+
+## Modules
+
+| Module | Rôle |
+| -- | -- |
+| `mic.authz` | Autorisation : moteur in-memory, OPA, OpenFGA (appels API **via httpx**) |
+| `mic.ratelimit` | Rate limiting (in-memory / Redis Lua) + `RateLimitMiddleware` |
+
+Namespace **PEP 420** (pas de `mic/__init__.py`).
+
+## Installation
+
+```bash
+pip install "mic-platform[openfga,redis]"
+```
+
+## Extras
+
+| Extra | Tire |
+| -- | -- |
+| `opa` | `mic-core[client]` (httpx — appels HTTP vers l'agent OPA) |
+| `openfga` | `mic-core[client]` (httpx — API OpenFGA ; **pas** le SDK officiel) |
+| `redis` | `mic-datastore[redis]` (backend Lua du rate limiter) |
+
+> ℹ️ L'adaptateur OpenFGA (`mic.authz.openfga`) parle à l'API HTTP via `httpx`,
+> il n'utilise **pas** `openfga-sdk`.
+
+## Versionnage
+
+Brique volatile (OPA/OpenFGA bougent vite) — reste en `0.x`. Contraindre avec
+`>=0.1,<1`. Release : `make release-pkg PKG=platform VERSION=x.y.z` → tag
+`platform-vX.Y.Z` (cf. [`../../RELEASING.md`](../../RELEASING.md)).

mic_platform-0.1.0/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_platform-0.1.0/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_platform-0.1.0/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_platform-0.1.0/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_platform-0.1.0/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

mic_platform-0.1.0/mic/authz/openfga.py

@@ -0,0 +1,167 @@
+"""``OpenFgaAuthorizationEngine`` — OpenFGA backend via REST.
+
+OpenFGA implémente le modèle Google Zanzibar (relation-based access
+control / ReBAC). Au lieu de "user X a le rôle admin" (RBAC), on
+modélise "user X a la relation ``viewer`` avec l'objet
+``document:roadmap``" — fine-grained et naturellement transitif
+(héritage via group, parent, etc.).
+
+Mapping du Protocol :class:`AuthorizationEngine` → API OpenFGA Check :
+
+- ``subject``  → ``tuple_key.user``     (ex. ``"user:42"``)
+- ``action``   → ``tuple_key.relation`` (ex. ``"viewer"``, ``"editor"``)
+- ``resource`` → ``tuple_key.object``   (ex. ``"document:roadmap"``)
+
+Endpoint OpenFGA attendu :
+    ``POST {api_url}/stores/{store_id}/check``
+Réponse attendue :
+    ``{"allowed": true|false}``
+
+Ref : https://openfga.dev/docs/interacting/relationship-queries#check
+
+Conventions (identiques à :class:`OpaAuthorizationEngine`) :
+
+- ``httpx`` est tiré par l'extra ``[client]``. L'extra ``[openfga]``
+  est un alias documentaire (pas de SDK officiel tiré — l'API REST
+  est stable et minimaliste, le SDK ajoute du poids inutile).
+- ``fail_close=True`` (default) : OpenFGA injoignable / réponse
+  malformée → ``check()`` retourne ``False`` (= refuser, principe de
+  moindre privilège).
+- ``authorization_model_id`` est optionnel (OpenFGA prend le dernier
+  modèle déployé si absent ; le passer rend la décision déterministe
+  dans le temps).
+
+Exemple de modèle OpenFGA pour un cas "documents partagés" :
+
+    model
+      schema 1.1
+    type user
+    type document
+      relations
+        define viewer: [user]
+        define editor: [user]
+        define owner: [user]
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mic.authz.base import AuthorizationEngine
+
+_logger = logging.getLogger("mic.authz.openfga")
+
+_HTTP_OK = 200
+
+
+class OpenFgaAuthorizationEngine(AuthorizationEngine):
+    """Backend OpenFGA via REST API. Implémente :class:`AuthorizationEngine`.
+
+    Args:
+        api_url: URL racine OpenFGA, sans slash final. Ex.
+            ``"http://openfga.observability.svc.cluster.local:8080"``.
+        store_id: identifiant du store OpenFGA (``01HXX...``).
+        authorization_model_id: modèle d'autorisation à utiliser
+            (optionnel ; default = dernier modèle déployé).
+        api_token: bearer token optionnel (OpenFGA Cloud / déploiements
+            sécurisés).
+        timeout_seconds: timeout réseau HTTP. Default 1s — OpenFGA
+            sidecar < 10ms en latence locale.
+        client: ``httpx.Client`` pré-construit (utile en tests).
+        fail_close: si True (default), un OpenFGA injoignable / réponse
+            malformée → ``check()`` retourne ``False``. Si False,
+            retourne ``True`` (fail-open : utile en dev local sans
+            OpenFGA, dangereux en prod).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        store_id: str,
+        authorization_model_id: str | None = None,
+        api_token: str | None = None,
+        timeout_seconds: float = 1.0,
+        client: Any = None,
+        fail_close: bool = True,
+    ) -> None:
+        if not api_url:
+            raise ValueError("OpenFgaAuthorizationEngine.api_url must be non-empty")
+        if not store_id:
+            raise ValueError("OpenFgaAuthorizationEngine.store_id must be non-empty")
+        self._api_url = api_url.rstrip("/")
+        self._store_id = store_id
+        self._authorization_model_id = authorization_model_id
+        self._api_token = api_token
+        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[openfga]'"
+                ) from exc
+            self._client = httpx.Client(timeout=timeout_seconds)
+
+    @property
+    def check_url(self) -> str:
+        """URL complète de l'endpoint Check pour ce store."""
+        return f"{self._api_url}/stores/{self._store_id}/check"
+
+    @property
+    def native(self) -> Any:
+        """Le ``httpx.Client`` natif — escape-hatch pour les autres
+        endpoints OpenFGA (Write, ListObjects, Expand, ...). Aligné
+        avec ``.native`` MIC.
+        """
+        return self._client
+
+    def check(self, *, subject: str, action: str, resource: str) -> bool:
+        """POST l'input à OpenFGA 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: dict[str, Any] = {
+            "tuple_key": {
+                "user": subject,
+                "relation": action,
+                "object": resource,
+            }
+        }
+        if self._authorization_model_id is not None:
+            payload["authorization_model_id"] = self._authorization_model_id
+
+        headers: dict[str, str] = {}
+        if self._api_token is not None:
+            headers["Authorization"] = f"Bearer {self._api_token}"
+
+        try:
+            response = self._client.post(self.check_url, json=payload, headers=headers)
+        except Exception as exc:
+            _logger.warning("OpenFGA check failed (network): %s", exc)
+            return not self._fail_close
+
+        if response.status_code != _HTTP_OK:
+            _logger.warning(
+                "OpenFGA 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("OpenFGA check : invalid JSON response: %s", exc)
+            return not self._fail_close
+
+        allowed = body.get("allowed")
+        if isinstance(allowed, bool):
+            return allowed
+        _logger.warning("OpenFGA check : unexpected response shape: %r", body)
+        return not self._fail_close