elo-node 0.4.0__py3-none-any.whl

elo/security.py

@@ -0,0 +1,201 @@
+"""Módulo de segurança do Elo — NKEYS, assinatura.
+
+Camadas:
+1. Geração e armazenamento de identidade (ed25519)
+2. Assinatura de mensagens (prova de autoria)
+3. Verificação de assinaturas
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+# ── Caminho padrão da identidade ──────────────────────────
+
+DEFAULT_KEY_DIR = Path.home() / ".elo"
+
+
+# ── Geração de identidade ──────────────────────────────────
+
+
+def generate_identity() -> tuple[ed25519.Ed25519PrivateKey, ed25519.Ed25519PublicKey]:
+    """Gera um par de chaves ed25519 para identidade do nó.
+
+    Returns:
+        (private_key, public_key)
+    """
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+# ── Codificação/decodificação ──────────────────────────────
+
+
+def pubkey_to_id(public_key: ed25519.Ed25519PublicKey) -> str:
+    """Converte chave pública ed25519 em node_id (base64 URL-safe sem padding)."""
+    raw = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def id_to_pubkey(node_id: str) -> ed25519.Ed25519PublicKey:
+    """Converte node_id de volta para chave pública ed25519."""
+    raw = base64.urlsafe_b64decode(node_id + "==")
+    return ed25519.Ed25519PublicKey.from_public_bytes(raw)
+
+
+# ── Armazenamento de identidade ────────────────────────────
+
+
+def _chmod_0600(path: Path) -> None:
+    """Define permissão 0o600 no arquivo (Unix). No-op no Windows."""
+    try:
+        path.chmod(0o600)
+    except NotImplementedError:
+        pass
+
+
+def save_identity(
+    private_key: ed25519.Ed25519PrivateKey,
+    key_dir: Path = DEFAULT_KEY_DIR,
+) -> Path:
+    """Salva a identidade do nó em disco.
+
+    Args:
+        private_key: Chave privada ed25519.
+        key_dir: Diretório para salvar os arquivos.
+
+    Returns:
+        Caminho do arquivo de seed salvo.
+    """
+    key_dir.mkdir(parents=True, exist_ok=True)
+
+    # Salva seed ed25519 (PKCS#8 PEM)
+    seed_path = key_dir / "identity.seed"
+    seed = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    seed_path.write_bytes(seed)
+    _chmod_0600(seed_path)
+
+    return seed_path
+
+
+def load_identity(
+    key_dir: Path = DEFAULT_KEY_DIR,
+) -> tuple[ed25519.Ed25519PrivateKey, None]:
+    """Carrega a identidade do nó do disco.
+
+    Returns:
+        (private_key, None) — None mantido para compatibilidade de interface.
+    """
+    seed_path = key_dir / "identity.seed"
+    if not seed_path.exists():
+        raise FileNotFoundError(
+            f"Identidade não encontrada em {seed_path}. "
+            "Use elo.security.generate_and_save_identity() primeiro."
+        )
+
+    private_key: ed25519.Ed25519PrivateKey = serialization.load_pem_private_key(
+        seed_path.read_bytes(),
+        password=None,
+    )  # type: ignore[assignment]
+
+    return private_key, None
+
+
+def generate_and_save_identity(
+    key_dir: Path = DEFAULT_KEY_DIR,
+) -> tuple[ed25519.Ed25519PublicKey, ed25519.Ed25519PrivateKey]:
+    """Gera e salva identidade (ed25519).
+
+    Returns:
+        (public_key, private_key)
+    """
+    private_key, public_key = generate_identity()
+    save_identity(private_key, key_dir)
+    return public_key, private_key
+
+
+# ── Assinatura de mensagens ────────────────────────────────
+
+
+def sign_message(private_key: ed25519.Ed25519PrivateKey, payload: dict[str, Any]) -> str:
+    """Assina um payload com a chave privada ed25519.
+
+    O payload é canonicalizado como JSON compacto antes de assinar.
+
+    Args:
+        private_key: Chave privada do nó.
+        payload: Dicionário a ser assinado.
+
+    Returns:
+        Assinatura em base64 URL-safe.
+    """
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    signature = private_key.sign(canonical)
+    return base64.urlsafe_b64encode(signature).rstrip(b"=").decode()
+
+
+def verify_signature(
+    public_key: ed25519.Ed25519PublicKey,
+    payload: dict[str, Any],
+    signature_b64: str,
+) -> bool:
+    """Verifica a assinatura de um payload.
+
+    Args:
+        public_key: Chave pública do remetente.
+        payload: Dicionário original.
+        signature_b64: Assinatura em base64 URL-safe.
+
+    Returns:
+        True se a assinatura for válida.
+    """
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    try:
+        sig = base64.urlsafe_b64decode(signature_b64 + "==")
+        public_key.verify(sig, canonical)
+        return True
+    except Exception:
+        return False
+
+
+# ── Utilitário de identidade efêmera (sem disco) ───────────
+
+
+class EphemeralIdentity:
+    """Identidade temporária — útil para testes ou nós sem persistência."""
+
+    def __init__(self) -> None:
+        self._private_key, self._public_key = generate_identity()
+
+    @property
+    def node_id(self) -> str:
+        return pubkey_to_id(self._public_key)
+
+    @property
+    def private_key(self) -> ed25519.Ed25519PrivateKey:
+        return self._private_key
+
+    @property
+    def public_key(self) -> ed25519.Ed25519PublicKey:
+        return self._public_key
+
+    def sign(self, payload: dict[str, Any]) -> str:
+        return sign_message(self._private_key, payload)
+
+    def verify(self, payload: dict[str, Any], signature: str) -> bool:
+        return verify_signature(self._public_key, payload, signature)

elo/transport/__init__.py

@@ -0,0 +1,34 @@
+"""Elo P2P transport layer — zero-infra mesh networking.
+
+Modules:
+- tcp: TCP connection manager (server + peer connections)
+- protocol: Wire protocol — framed JSON over TCP
+- routing: Interest-based routing table
+- tracker: Local capability registry (public/private)
+"""
+
+from elo.transport.tcp import TCPManager, PeerConnection
+from elo.transport.protocol import (
+    encode_frame, read_frame, write_frame,
+    hello_msg, hello_ack_msg,
+    query_msg, query_resp_msg,
+    interest_update_msg,
+    task_msg, result_msg,
+    heartbeat_msg, bye_msg,
+    MessageType, FrameError,
+)
+from elo.transport.routing import InterestTable
+from elo.transport.tracker import LocalTracker
+
+__all__ = [
+    "TCPManager", "PeerConnection",
+    "encode_frame", "read_frame", "write_frame",
+    "hello_msg", "hello_ack_msg",
+    "query_msg", "query_resp_msg",
+    "interest_update_msg",
+    "task_msg", "result_msg",
+    "heartbeat_msg", "bye_msg",
+    "MessageType", "FrameError",
+    "InterestTable",
+    "LocalTracker",
+]

elo/transport/protocol.py

@@ -0,0 +1,166 @@
+"""Wire protocol — framed JSON messages over TCP.
+
+Frame format: [4-byte big-endian length][JSON payload]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import struct
+import time
+from typing import Any
+
+# ── Frame constants ────────────────────────────────────────
+
+FRAME_HEADER_SIZE = 4  # uint32 big-endian
+MAX_PAYLOAD_SIZE = 1024 * 1024  # 1 MB
+
+
+class FrameError(Exception):
+    """Invalid frame received."""
+
+
+# ── Message types ──────────────────────────────────────────
+
+class MessageType:
+    HELLO = "hello"
+    HELLO_ACK = "hello_ack"
+    QUERY = "query"
+    QUERY_RESP = "query_resp"
+    INTEREST_UPDATE = "interest_update"
+    TASK = "task"
+    RESULT = "result"
+    EVENT = "event"
+    HEARTBEAT = "heartbeat"
+    BYE = "bye"
+    # DHT messages (v0.3+)
+    DHT_PING = "dht_ping"
+    DHT_PONG = "dht_pong"
+    DHT_FIND_NODE = "dht_find_node"
+    DHT_FIND_NODE_RESP = "dht_find_node_resp"
+    DHT_FIND_VALUE = "dht_find_value"
+    DHT_FIND_VALUE_RESP = "dht_find_value_resp"
+    DHT_STORE = "dht_store"
+    DHT_STORE_RESP = "dht_store_resp"
+
+
+# ── Framing ────────────────────────────────────────────────
+
+
+def encode_frame(payload: dict[str, Any]) -> bytes:
+    """Encodes a JSON dict into a framed message."""
+    data = json.dumps(payload, ensure_ascii=False).encode()
+    if len(data) > MAX_PAYLOAD_SIZE:
+        raise FrameError(f"Payload too large: {len(data)} bytes (max {MAX_PAYLOAD_SIZE})")
+    header = struct.pack("!I", len(data))
+    return header + data
+
+
+async def read_frame(reader: asyncio.StreamReader) -> dict[str, Any]:
+    """Reads one frame from a StreamReader. Returns the decoded JSON dict."""
+    header = await reader.readexactly(FRAME_HEADER_SIZE)
+    length = struct.unpack("!I", header)[0]
+    if length > MAX_PAYLOAD_SIZE:
+        raise FrameError(f"Invalid payload length: {length} (max {MAX_PAYLOAD_SIZE})")
+    data = await reader.readexactly(length)
+    return json.loads(data.decode())
+
+
+async def write_frame(writer: asyncio.StreamWriter, payload: dict[str, Any]) -> None:
+    """Writes one framed JSON message to a StreamWriter."""
+    writer.write(encode_frame(payload))
+    await writer.drain()
+
+
+# ── Message builders ───────────────────────────────────────
+
+
+def hello_msg(node_id: str, caps: dict, interests: list[str],
+              tracker: str = "public", version: str = "0.2.0") -> dict:
+    return {
+        "type": MessageType.HELLO,
+        "node_id": node_id,
+        "caps": caps,
+        "interests": interests,
+        "tracker": tracker,
+        "version": version,
+    }
+
+
+def hello_ack_msg(node_id: str, caps: dict, interests: list[str],
+                  tracker: str = "public") -> dict:
+    return {
+        "type": MessageType.HELLO_ACK,
+        "node_id": node_id,
+        "caps": caps,
+        "interests": interests,
+        "tracker": tracker,
+    }
+
+
+def query_msg(capability: str, query_id: str, ttl: int = 5) -> dict:
+    return {
+        "type": MessageType.QUERY,
+        "capability": capability,
+        "id": query_id,
+        "ttl": ttl,
+    }
+
+
+def query_resp_msg(query_id: str, nodes: list[dict]) -> dict:
+    return {
+        "type": MessageType.QUERY_RESP,
+        "id": query_id,
+        "nodes": nodes,
+    }
+
+
+def interest_update_msg(interests: list[str]) -> dict:
+    return {
+        "type": MessageType.INTEREST_UPDATE,
+        "interests": interests,
+    }
+
+
+def task_msg(task_id: str, target: str, caller: str, capability: str,
+             payload: dict, signature: str = "") -> dict:
+    return {
+        "type": MessageType.TASK,
+        "id": task_id,
+        "target": target,
+        "caller": caller,
+        "capability": capability,
+        "payload": payload,
+        "signature": signature,
+        "protocol": "elo.v1",
+        "timestamp": int(time.time()),
+        "ttl_s": 60,
+    }
+
+
+def result_msg(task_id: str, status: str, payload: dict | None = None,
+               error: dict | None = None) -> dict:
+    msg = {
+        "type": MessageType.RESULT,
+        "id": task_id,
+        "status": status,
+        "protocol": "elo.v1",
+    }
+    if payload is not None:
+        msg["payload"] = payload
+    if error is not None:
+        msg["error"] = error
+    return msg
+
+
+def heartbeat_msg(node_id: str) -> dict:
+    return {
+        "type": MessageType.HEARTBEAT,
+        "node_id": node_id,
+        "ts": int(time.time()),
+    }
+
+
+def bye_msg() -> dict:
+    return {"type": MessageType.BYE}

elo/transport/routing.py

@@ -0,0 +1,135 @@
+"""Interest-based routing table.
+
+Each node maintains:
+- Local caps: what this node provides
+- Local interests: what this node is looking for
+- Remote caps: per-peer, what capabilities each peer has
+- Remote interests: per-peer, what each peer is looking for
+- Forwarding table: capability → set of peer addresses that can serve it
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+
+class InterestTable:
+    """Interest-based routing for P2P capability discovery."""
+
+    def __init__(self) -> None:
+        self._local_caps: set[str] = set()
+        self._local_interests: set[str] = set()
+
+        # peer_address → {capability, ...}
+        self._peer_caps: dict[str, set[str]] = {}
+        self._peer_interests: dict[str, set[str]] = {}
+
+        # capability → {peer_address, ...}
+        self._forwarding: dict[str, set[str]] = defaultdict(set)
+
+    # ── local ───────────────────────────────────────────────
+
+    def set_local_caps(self, caps: dict[str, list[dict[str, Any]]]) -> None:
+        """Register local capabilities from agents, models, and tools."""
+        self._local_caps.clear()
+        for agent in caps.get("agents", []):
+            self._local_caps.add(agent.get("name", ""))
+        for model in caps.get("models", []):
+            self._local_caps.add(model.get("name", ""))
+        for tool in caps.get("tools", []):
+            self._local_caps.add(tool.get("name", ""))
+
+    def set_local_interests(self, interests: list[str]) -> None:
+        self._local_interests = set(interests)
+
+    def has_local(self, capability: str) -> bool:
+        return capability in self._local_caps
+
+    @property
+    def local_caps(self) -> set[str]:
+        return self._local_caps
+
+    @property
+    def local_interests(self) -> set[str]:
+        return self._local_interests
+
+    # ── peer ────────────────────────────────────────────────
+
+    def register_peer(self, peer_addr: str, caps: dict[str, list[dict[str, Any]]],
+                      interests: list[str]) -> None:
+        """Register or update a peer's capabilities and interests."""
+        cap_set: set[str] = set()
+        for agent in caps.get("agents", []):
+            cap_set.add(agent.get("name", ""))
+        for model in caps.get("models", []):
+            cap_set.add(model.get("name", ""))
+        for tool in caps.get("tools", []):
+            cap_set.add(tool.get("name", ""))
+
+        self._peer_caps[peer_addr] = cap_set
+        self._peer_interests[peer_addr] = set(interests)
+
+        # Update forwarding table
+        for cap in cap_set:
+            self._forwarding[cap].add(peer_addr)
+
+    def remove_peer(self, peer_addr: str) -> None:
+        """Remove a peer and clean forwarding entries."""
+        old_caps = self._peer_caps.pop(peer_addr, set())
+        for cap in old_caps:
+            self._forwarding.get(cap, set()).discard(peer_addr)
+        self._peer_interests.pop(peer_addr, None)
+
+    def find_peer_for(self, capability: str) -> str | None:
+        """Find a peer that can serve the given capability."""
+        peers = self._forwarding.get(capability, set())
+        if peers:
+            return next(iter(peers))
+        return None
+
+    def find_all_peers_for(self, capability: str) -> set[str]:
+        """Return all known peers for a capability."""
+        return self._forwarding.get(capability, set()).copy()
+
+    def query_peers(self, capability: str, exclude: set[str] | None = None) -> list[str]:
+        """Find peers that might know about a capability.
+
+        First: direct matches from forwarding table.
+        Second: peers whose interests overlap (they're looking for similar things).
+        Third: random peers as a fallback.
+        """
+        exclude = exclude or set()
+        results: list[str] = []
+
+        # Direct matches
+        for peer in self._forwarding.get(capability, set()):
+            if peer not in exclude:
+                results.append(peer)
+
+        # Peers with overlapping interests (might know about this capability)
+        if not results:
+            for peer_addr, interests in self._peer_interests.items():
+                if peer_addr in exclude:
+                    continue
+                # If the peer is interested in something, it might know
+                # about similar capabilities
+                if any(capability.startswith(i.split(":")[0])
+                       for i in interests):
+                    results.append(peer_addr)
+
+        # Fallback: all known peers
+        if not results:
+            results = [p for p in self._peer_caps if p not in exclude]
+
+        return results
+
+    @property
+    def known_peers(self) -> list[str]:
+        return list(self._peer_caps.keys())
+
+    def get_peer_caps(self, peer_addr: str) -> dict[str, set[str]]:
+        return {
+            "caps": self._peer_caps.get(peer_addr, set()),
+            "interests": self._peer_interests.get(peer_addr, set()),
+        }