intermesh 0.3.0__py3-none-any.whl

intermesh/apikeys.py

@@ -0,0 +1,273 @@
+"""
+Comptes de service : magasin de clés d'API du Hub.
+
+Les clés étaient auparavant écrites en clair dans le code source du Hub,
+donc publiées avec le dépôt. Une clé versionnée dans Git est une clé
+compromise : elle reste lisible dans l'historique même après suppression.
+
+Ce module les charge depuis une source externe et ne conserve jamais que
+leur empreinte SHA-256. Le Hub ne peut donc pas révéler une clé, même si
+sa configuration fuit — il peut seulement vérifier qu'une clé présentée
+correspond à une empreinte connue.
+
+Sources, par ordre de priorité :
+
+  1. INTERMESH_API_KEYS       — JSON inline (Kubernetes, CI)
+  2. INTERMESH_API_KEYS_FILE  — chemin d'un fichier JSON
+  3. ~/.intermesh/api_keys.json
+  4. aucune — les comptes de service sont simplement désactivés
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import stat
+import time
+from pathlib import Path
+
+ENV_INLINE = "INTERMESH_API_KEYS"
+ENV_FILE = "INTERMESH_API_KEYS_FILE"
+
+# Clés de démonstration, activées uniquement sur demande explicite
+# (--dev-api-keys). Elles sont publiques par construction : ne jamais
+# s'en servir ailleurs que pour une démo ou un test.
+DEV_API_KEYS = {
+    "nx_dev_acme_demo_key": {
+        "org_id": "acme",
+        "roles": ["admin", "service_account"],
+        "permissions": ["admin:*"],
+    },
+    "nx_dev_globex_demo_key": {
+        "org_id": "globex",
+        "roles": ["worker", "service_account"],
+        "permissions": ["compute:execute"],
+    },
+}
+
+
+def default_keys_path() -> Path:
+    base = os.environ.get("INTERMESH_HOME")
+    return (Path(base) if base else Path.home() / ".intermesh") / "api_keys.json"
+
+
+def hash_key(raw_key: str) -> str:
+    """Empreinte SHA-256 d'une clé d'API."""
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+
+
+def generate_key(prefix: str = "nx_live") -> str:
+    """Génère une clé d'API cryptographiquement aléatoire."""
+    return f"{prefix}_{secrets.token_urlsafe(32)}"
+
+
+class ApiKeyStore:
+    """Vérifie les clés d'API sans jamais conserver leur valeur en clair."""
+
+    def __init__(
+        self,
+        keys: dict[str, dict] | None = None,
+        source: str = "aucune",
+        path: Path | None = None,
+    ):
+        """
+        Args:
+            keys:   Mapping clé_en_clair -> {org_id, roles, permissions}.
+                    Seules les empreintes sont conservées.
+            source: Description de la provenance, pour la bannière de démarrage.
+            path:   Fichier de sauvegarde, si les mutations sont autorisées.
+        """
+        self._by_hash: dict[str, dict] = {}
+        self.source = source
+        self.path = path
+
+        for raw_key, info in (keys or {}).items():
+            self._by_hash[hash_key(raw_key)] = self._normalize(info)
+
+    @staticmethod
+    def _normalize(info: dict, label: str | None = None) -> dict:
+        entry = {
+            "org_id": info["org_id"],
+            "roles": list(info.get("roles", [])),
+            "permissions": list(info.get("permissions", [])),
+        }
+        if label or info.get("label"):
+            entry["label"] = label or info["label"]
+        if info.get("created_at"):
+            entry["created_at"] = info["created_at"]
+        return entry
+
+    # ------------------------------------------------------------------
+    # Mutations (console d'administration)
+    # ------------------------------------------------------------------
+
+    @property
+    def mutable(self) -> bool:
+        """Les mutations exigent un fichier : une config injectée par
+        l'environnement appartient à l'orchestrateur, pas au Hub."""
+        return self.path is not None
+
+    def describe(self) -> list[dict]:
+        """
+        Inventaire des clés, sans jamais exposer leur valeur.
+
+        L'empreinte est tronquée à 12 caractères : assez pour identifier
+        une clé dans une interface, trop peu pour aider une attaque hors
+        ligne si la page est capturée.
+        """
+        return [
+            {
+                "fingerprint": h[:12],
+                "org_id": info["org_id"],
+                "roles": info["roles"],
+                "permissions": info["permissions"],
+                "label": info.get("label", ""),
+                "created_at": info.get("created_at"),
+            }
+            for h, info in sorted(self._by_hash.items())
+        ]
+
+    def _persist(self) -> None:
+        if not self.path:
+            raise PermissionError(
+                "Les clés proviennent de l'environnement et sont en lecture seule. "
+                f"Utilisez un fichier ({ENV_FILE} ou ~/.intermesh/api_keys.json) "
+                "pour autoriser les mutations."
+            )
+        # Le fichier stocke déjà des empreintes : la valeur en clair n'a
+        # jamais existé côté Hub après création.
+        payload = {"__hashed__": True, "keys": self._by_hash}
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        tmp = self.path.with_suffix(".tmp")
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, json.dumps(payload, indent=2).encode("utf-8"))
+        finally:
+            os.close(fd)
+        os.replace(tmp, self.path)   # remplacement atomique
+
+    def create(self, org_id: str, roles: list[str], permissions: list[str],
+               label: str = "") -> str:
+        """
+        Crée une clé et retourne sa valeur en clair — la seule et unique
+        fois où elle existe. Seule l'empreinte est conservée ensuite.
+        """
+        raw = generate_key()
+        self._by_hash[hash_key(raw)] = self._normalize(
+            {
+                "org_id": org_id,
+                "roles": roles,
+                "permissions": permissions,
+                "created_at": time.time(),
+            },
+            label=label,
+        )
+        self._persist()
+        return raw
+
+    def revoke(self, fingerprint_prefix: str) -> bool:
+        """Révoque une clé désignée par le préfixe de son empreinte."""
+        matches = [h for h in self._by_hash if h.startswith(fingerprint_prefix)]
+        if len(matches) != 1:
+            return False
+        del self._by_hash[matches[0]]
+        self._persist()
+        return True
+
+    def __len__(self) -> int:
+        return len(self._by_hash)
+
+    # ------------------------------------------------------------------
+    # Instantanés
+    # ------------------------------------------------------------------
+
+    def export_hashed(self) -> dict[str, dict]:
+        """
+        Empreintes et privilèges, tels quels — la forme attendue par
+        `import_hashed`. Aucune clé en clair n'en sort, il n'y en a pas.
+        """
+        return {h: dict(info) for h, info in self._by_hash.items()}
+
+    def import_hashed(self, keys: dict[str, dict]) -> None:
+        """
+        Remplace intégralement le jeu de clés.
+
+        Raises:
+            PermissionError: si les clés viennent de l'environnement. Elles
+                appartiennent alors à l'orchestrateur (Kubernetes, CI), pas
+                au Hub : les écraser depuis un instantané ferait diverger la
+                mémoire du Hub de sa source de vérité.
+        """
+        if not self.mutable:
+            raise PermissionError(
+                "Les clés proviennent de l'environnement et sont en lecture seule : "
+                "elles ne peuvent pas être restaurées depuis un instantané."
+            )
+        self._by_hash = {h: self._normalize(info) for h, info in keys.items()}
+        self._persist()
+
+    def lookup(self, raw_key: str) -> dict | None:
+        """
+        Retourne les privilèges associés à une clé, ou None si inconnue.
+
+        La comparaison est à temps constant : comparer des empreintes avec
+        `==` laisse fuir, par le temps de réponse, le nombre d'octets
+        corrects en tête — de quoi reconstruire une empreinte valide
+        octet par octet.
+        """
+        if not raw_key:
+            return None
+
+        candidate = hash_key(raw_key)
+        matched = None
+        for known_hash, info in self._by_hash.items():
+            if secrets.compare_digest(candidate, known_hash):
+                matched = info
+        return matched
+
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def load(cls, dev_keys: bool = False) -> "ApiKeyStore":
+        """Charge les clés depuis la première source disponible."""
+        inline = os.environ.get(ENV_INLINE)
+        if inline:
+            try:
+                return cls(json.loads(inline), source=f"variable {ENV_INLINE}")
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"{ENV_INLINE} n'est pas du JSON valide : {exc}") from exc
+
+        explicit = os.environ.get(ENV_FILE)
+        path = Path(explicit) if explicit else default_keys_path()
+
+        if path.is_file():
+            mode = path.stat().st_mode
+            if mode & (stat.S_IRWXG | stat.S_IRWXO):
+                print(
+                    f"\033[33m⚠️  [SÉCURITÉ] {path} est lisible par d'autres utilisateurs.\033[0m\n"
+                    f"    Corrigez avec : chmod 600 {path}"
+                )
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"{path} n'est pas du JSON valide : {exc}") from exc
+
+            if data.get("__hashed__"):
+                # Format produit par la console : déjà haché, rien à recalculer.
+                store = cls({}, source=f"fichier {path}", path=path)
+                store._by_hash = {
+                    h: cls._normalize(info) for h, info in data.get("keys", {}).items()
+                }
+                return store
+
+            # Format historique : clés en clair, hachées au chargement.
+            return cls(data, source=f"fichier {path}", path=path)
+
+        if dev_keys:
+            return cls(DEV_API_KEYS, source="clés de DÉMONSTRATION (publiques)")
+
+        # Aucun fichier : le chemin par défaut devient la cible d'écriture,
+        # pour qu'une première clé créée depuis la console soit persistée.
+        return cls({}, source="aucune — comptes de service désactivés", path=path)

intermesh/audit.py

@@ -0,0 +1,153 @@
+import hashlib
+import json
+import time
+from typing import Optional, List, Dict, Any
+
+
+class AuditEntry:
+    """
+    Une entrée immuable dans le journal d'audit InterMesh.
+    Chaque entrée est scellée par son empreinte SHA-256 incluant le hash de l'entrée précédente.
+    """
+
+    def __init__(
+        self,
+        index: int,
+        event_type: str,
+        sender: str,
+        target: Optional[str],
+        metadata: Dict[str, Any],
+        prev_hash: str,
+        timestamp: Optional[float] = None,
+        entry_hash: Optional[str] = None
+    ):
+        self.index = index
+        self.timestamp = timestamp or time.time()
+        self.event_type = event_type
+        self.sender = sender
+        self.target = target
+        self.metadata = metadata
+        self.prev_hash = prev_hash
+        self.hash = entry_hash or self.compute_hash()
+
+    def compute_hash(self) -> str:
+        """Calcule le hash SHA-256 de cette entrée lié à l'entrée précédente."""
+        payload = {
+            "index": self.index,
+            "timestamp": self.timestamp,
+            "event_type": self.event_type,
+            "sender": self.sender,
+            "target": self.target,
+            "metadata": self.metadata,
+            "prev_hash": self.prev_hash
+        }
+        raw = json.dumps(payload, sort_keys=True).encode("utf-8")
+        return hashlib.sha256(raw).hexdigest()
+
+    def to_dict(self) -> dict:
+        return {
+            "index": self.index,
+            "timestamp": self.timestamp,
+            "event_type": self.event_type,
+            "sender": self.sender,
+            "target": self.target,
+            "metadata": self.metadata,
+            "prev_hash": self.prev_hash,
+            "hash": self.hash
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AuditEntry":
+        """
+        Reconstruit une entrée depuis sa forme sérialisée.
+
+        Le hash stocké est conservé tel quel, sans être recalculé : c'est
+        précisément l'écart entre le hash stocké et le hash recalculé qui
+        révèle une altération lors de verify_integrity().
+        """
+        return cls(
+            index=data["index"],
+            event_type=data["event_type"],
+            sender=data["sender"],
+            target=data.get("target"),
+            metadata=data.get("metadata", {}),
+            prev_hash=data["prev_hash"],
+            timestamp=data.get("timestamp"),
+            entry_hash=data.get("hash"),
+        )
+
+
+class ImmutableAuditLog:
+    """
+    Registre d'audit chaîné (Merkle-Chain).
+    Permet d'ajouter des événements et de vérifier l'intégrité globale du journal.
+    """
+
+    def __init__(self, entries: Optional[List[dict]] = None, on_append=None):
+        """
+        Args:
+            entries:   Chaîne existante à reprendre (forme sérialisée). Si elle
+                       est vide ou absente, un bloc genesis est créé.
+            on_append: Callback appelé avec chaque nouvelle AuditEntry, pour
+                       l'écrire dans un stockage durable.
+        """
+        self.chain: List[AuditEntry] = []
+        self._on_append = on_append
+
+        if entries:
+            self.chain = [AuditEntry.from_dict(e) for e in entries]
+        else:
+            self._create_genesis_block()
+
+    def _create_genesis_block(self):
+        """Crée le bloc racine (Genesis) de la chaîne d'audit."""
+        genesis = AuditEntry(
+            index=0,
+            event_type="GENESIS",
+            sender="intermesh_system",
+            target=None,
+            metadata={"system": "InterMesh Protocol Immutable Audit Log Initialized"},
+            prev_hash="0" * 64,
+            timestamp=time.time()
+        )
+        self.chain.append(genesis)
+        if self._on_append:
+            self._on_append(genesis)
+
+    def log(self, event_type: str, sender: str, target: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> AuditEntry:
+        """Ajoute un nouvel événement au journal et le scelle cryptographiquement."""
+        prev_entry = self.chain[-1]
+        new_entry = AuditEntry(
+            index=len(self.chain),
+            event_type=event_type,
+            sender=sender,
+            target=target,
+            metadata=metadata or {},
+            prev_hash=prev_entry.hash
+        )
+        self.chain.append(new_entry)
+        if self._on_append:
+            self._on_append(new_entry)
+        return new_entry
+
+    def verify_integrity(self) -> bool:
+        """
+        Vérifie l'intégrité mathématique complète de toute la chaîne d'audit.
+        Retourne False si une quelconque entrée a été modifiée ou supprimée.
+        """
+        for i in range(1, len(self.chain)):
+            curr = self.chain[i]
+            prev = self.chain[i - 1]
+
+            # 1. Vérifier la liaison avec le bloc précédent
+            if curr.prev_hash != prev.hash:
+                return False
+
+            # 2. Vérifier que le hash correspond au contenu actuel
+            if curr.hash != curr.compute_hash():
+                return False
+
+        return True
+
+    def export_json(self) -> str:
+        return json.dumps([e.to_dict() for e in self.chain], indent=2)

intermesh/bridge.py

@@ -0,0 +1,181 @@
+"""
+Pont universel : brancher un agent écrit dans n'importe quel langage.
+
+Écrire un SDK natif par langage ne passe pas à l'échelle — il y en aurait
+toujours un qui manque. Ce module prend le problème par l'autre bout : le
+protocole reste du JSON, et l'agent étranger n'a qu'à savoir lire du JSON
+sur son entrée standard, ou répondre à une requête HTTP. Go, Rust, Java,
+PHP, C, un script shell : tout ce qui sait faire ça devient un agent
+InterMesh sans une ligne de code d'intégration.
+
+Deux modes, selon ce que le programme existant sait déjà faire :
+
+  * `exec`  — un processus est lancé par tâche. Le JSON d'entrée arrive sur
+              stdin, la réponse est lue sur stdout. C'est le mode des
+              binaires, des scripts et des CLI.
+  * `http`  — la tâche est POSTée en JSON sur une URL. C'est le mode des
+              services déjà en ligne, qu'on ne veut pas relancer.
+
+Tolérance assumée en mode `exec` : si stdout n'est pas du JSON valide, le
+texte brut est renvoyé sous `{"output": ...}`. Un `echo` en shell doit
+suffire à faire un agent ; exiger du JSON parfait tuerait le cas d'usage.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import shlex
+import signal
+import urllib.error
+import urllib.request
+from typing import Any, Optional, Sequence
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class BridgeError(RuntimeError):
+    """L'agent externe a échoué : code de sortie non nul, timeout, ou HTTP en erreur."""
+
+
+def _decode_output(raw: str) -> Any:
+    text = raw.strip()
+    if not text:
+        return {}
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return {"output": text}
+
+
+def _kill_process_group(process) -> None:
+    """Tue le programme et toute sa descendance.
+
+    Un agent qui dépasse son délai ne doit pas laisser d'orphelins derrière
+    lui : ils continueraient de consommer des ressources et de tenir les
+    tuyaux d'un appel qu'on a déjà abandonné.
+    """
+    with contextlib.suppress(ProcessLookupError, PermissionError, OSError):
+        os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+        return
+    with contextlib.suppress(ProcessLookupError):
+        process.kill()
+
+
+async def run_command(command: str | Sequence[str], payload: Any,
+                      timeout: float = DEFAULT_TIMEOUT) -> Any:
+    """Exécute `command`, lui passe `payload` en JSON sur stdin, lit sa réponse.
+
+    `command` accepte une chaîne (interprétée par le shell, pratique pour
+    les pipelines) ou une liste d'arguments (sans shell, à préférer quand
+    la commande vient d'une source non maîtrisée).
+    """
+    stdin_data = json.dumps(payload).encode("utf-8")
+
+    # start_new_session place le programme dans son propre groupe de processus.
+    # Sans ça, un timeout ne tue que le shell : ses enfants survivent, gardent
+    # les tuyaux ouverts, et l'appel reste bloqué jusqu'à leur propre fin — le
+    # délai maximal ne protégeait alors de rien.
+    spawn = dict(
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        start_new_session=True,
+    )
+    if isinstance(command, str):
+        process = await asyncio.create_subprocess_shell(command, **spawn)
+        shown = command
+    else:
+        process = await asyncio.create_subprocess_exec(*command, **spawn)
+        shown = shlex.join(command)
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            process.communicate(input=stdin_data), timeout=timeout)
+    except asyncio.TimeoutError:
+        _kill_process_group(process)
+        with contextlib.suppress(Exception):
+            await asyncio.wait_for(process.wait(), timeout=5.0)
+        raise BridgeError(f"'{shown}' n'a pas répondu en {timeout}s.")
+
+    if process.returncode != 0:
+        detail = stderr.decode("utf-8", "replace").strip() or "(stderr vide)"
+        raise BridgeError(f"'{shown}' a terminé avec le code {process.returncode} : {detail}")
+
+    return _decode_output(stdout.decode("utf-8", "replace"))
+
+
+def _post_json(url: str, payload: Any, timeout: float) -> Any:
+    request = urllib.request.Request(
+        url, data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"}, method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        return _decode_output(response.read().decode("utf-8", "replace"))
+
+
+async def post_task(url: str, payload: Any, timeout: float = DEFAULT_TIMEOUT) -> Any:
+    """POSTe `payload` en JSON sur `url` et retourne la réponse décodée.
+
+    urllib plutôt qu'un client HTTP tiers : le pont ne doit pas imposer une
+    dépendance de plus à qui veut juste brancher un service existant.
+    """
+    loop = asyncio.get_running_loop()
+    try:
+        return await loop.run_in_executor(None, _post_json, url, payload, timeout)
+    except urllib.error.HTTPError as exc:
+        raise BridgeError(f"{url} a répondu {exc.code} : {exc.reason}") from exc
+    except urllib.error.URLError as exc:
+        raise BridgeError(f"{url} injoignable : {exc.reason}") from exc
+
+
+def exec_handler(command: str | Sequence[str], timeout: float = DEFAULT_TIMEOUT):
+    """Handler de tâche déléguant à un programme externe."""
+    async def handler(input_data: Any, task: Any):
+        return await run_command(command, input_data, timeout)
+    return handler
+
+
+def http_handler(url: str, timeout: float = DEFAULT_TIMEOUT):
+    """Handler de tâche déléguant à un service HTTP."""
+    async def handler(input_data: Any, task: Any):
+        return await post_task(url, input_data, timeout)
+    return handler
+
+
+def _build_agent(name: str, handler, capabilities, roles, org_id, hub_url,
+                 encrypt, **kwargs):
+    from intermesh.agent import InterMeshAgent
+
+    agent = InterMeshAgent(
+        name=name, org_id=org_id, capabilities=capabilities or ["compute"],
+        roles=roles or ["worker"], hub_url=hub_url, encrypt=encrypt, **kwargs,
+    )
+    agent.on_task(handler)
+    return agent
+
+
+def from_command(command: str | Sequence[str], name: str,
+                 capabilities: Optional[list] = None, roles: Optional[list] = None,
+                 org_id: str = "default", hub_url: str = "ws://localhost:8765",
+                 encrypt: bool = True, timeout: float = DEFAULT_TIMEOUT, **kwargs):
+    """Transforme n'importe quel exécutable en agent InterMesh.
+
+        agent = from_command("./mon-agent-en-go", name="pricing")
+    """
+    return _build_agent(name, exec_handler(command, timeout), capabilities, roles,
+                        org_id, hub_url, encrypt, **kwargs)
+
+
+def from_http(url: str, name: str,
+              capabilities: Optional[list] = None, roles: Optional[list] = None,
+              org_id: str = "default", hub_url: str = "ws://localhost:8765",
+              encrypt: bool = True, timeout: float = DEFAULT_TIMEOUT, **kwargs):
+    """Transforme n'importe quel service HTTP en agent InterMesh.
+
+        agent = from_http("http://localhost:9000/task", name="scoring")
+    """
+    return _build_agent(name, http_handler(url, timeout), capabilities, roles,
+                        org_id, hub_url, encrypt, **kwargs)