feat(us-017): P2P gossip, NAT-traversal relay node, and TLS

- packages/p2p: identity (peer_id from sha256 of RSA pubkey), TLS cert
  generation with SHA-256 fingerprint, GossipClient (WSS PubSub with
  per-topic handlers, dedup by msg_id, auto-reconnect), MdnsDiscovery
  (zeroconf optional dependency, graceful no-op fallback)
- packages/relay: new meshnet-relay package — RelayServer (asyncio +
  websockets) with gossip fanout hub, circuit relay proxy for NAT traversal,
  peer registry; meshnet-relay CLI
- packages/p2p/relay_bootstrap.json: team relay bootstrap list
- Tracker: _NodeEntry gains relay_addr, cert_fingerprint, peer_id; both
  register and heartbeat handlers read and store these optional fields
- docs/adr/0010 already written (previous commit)
- conftest.py: packages/relay added to sys.path
- 18 new tests; 115 passed total, 1 skipped (no regressions)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/p2p/meshnet_p2p/gossip.py

@@ -0,0 +1,162 @@
+"""WebSocket gossip client — connects to relay, publish/subscribe to topics."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+import uuid
+from collections import defaultdict
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+# Message envelope topics
+TOPIC_NODE_JOIN = "node-join"
+TOPIC_NODE_LEAVE = "node-leave"
+TOPIC_COVERAGE_UPDATE = "coverage-update"
+TOPIC_HEARTBEAT = "heartbeat"
+TOPIC_PEER_LIST = "peer-list"
+TOPIC_RELAY_ANNOUNCE = "relay-announce"
+
+_MSG_TTL = 3  # max re-broadcast hops
+
+
+def _make_envelope(topic: str, payload: dict, from_peer: str, ttl: int = _MSG_TTL) -> dict:
+    return {
+        "topic": topic,
+        "version": 1,
+        "from_peer": from_peer,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "msg_id": str(uuid.uuid4()),
+        "ttl": ttl,
+        "payload": payload,
+    }
+
+
+class GossipClient:
+    """Thread-safe WebSocket gossip client.
+
+    Usage::
+
+        client = GossipClient(relay_url="ws://relay:8765", peer_id="abc123")
+        client.subscribe("node-join", lambda env: print(env["payload"]))
+        client.start()
+        client.publish("node-join", {"addr": "http://192.168.1.42:8001", ...})
+        ...
+        client.stop()
+    """
+
+    def __init__(self, relay_url: str, peer_id: str, reconnect_interval: float = 3.0):
+        self.relay_url = relay_url
+        self.peer_id = peer_id
+        self.reconnect_interval = reconnect_interval
+
+        self._handlers: dict[str, list[Callable]] = defaultdict(list)
+        self._seen: set[str] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ws = None
+        self._running = False
+        self._connected = threading.Event()
+        self._stop_event: asyncio.Event | None = None
+
+    def subscribe(self, topic: str, handler: Callable) -> None:
+        """Register a sync callback for messages on topic."""
+        self._handlers[topic].append(handler)
+
+    def publish(self, topic: str, payload: dict) -> None:
+        """Send a gossip message to all peers via the relay. Thread-safe."""
+        envelope = _make_envelope(topic, payload, self.peer_id)
+        if self._loop and self._running:
+            asyncio.run_coroutine_threadsafe(self._send(envelope), self._loop)
+
+    def start(self) -> None:
+        """Start the gossip client in a background thread."""
+        self._running = True
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._run_loop, daemon=True, name="gossip")
+        self._thread.start()
+
+    def wait_connected(self, timeout: float = 5.0) -> bool:
+        """Block until connected to relay or timeout. Returns True if connected."""
+        return self._connected.wait(timeout)
+
+    def stop(self) -> None:
+        """Stop the gossip client and clean up."""
+        self._running = False
+        if self._loop and self._stop_event is not None:
+            self._loop.call_soon_threadsafe(self._stop_event.set)
+        if self._thread:
+            self._thread.join(timeout=3.0)
+
+    # ------------------------------------------------------------------
+    # Internal asyncio methods (run inside the background event loop)
+    # ------------------------------------------------------------------
+
+    def _run_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._stop_event = asyncio.Event()
+        try:
+            self._loop.run_until_complete(self._connect_loop())
+        except Exception:
+            log.debug("Gossip loop exited", exc_info=True)
+
+    async def _connect_loop(self) -> None:
+        import websockets  # type: ignore[import]
+
+        while self._running and not (self._stop_event and self._stop_event.is_set()):
+            try:
+                async with websockets.connect(
+                    self.relay_url,
+                    ping_interval=20,
+                    ping_timeout=10,
+                    open_timeout=5,
+                ) as ws:
+                    self._ws = ws
+                    self._connected.set()
+                    log.debug("Gossip connected to %s", self.relay_url)
+                    # Send peer registration
+                    await ws.send(json.dumps(
+                        _make_envelope(
+                            "peer-register",
+                            {"peer_id": self.peer_id},
+                            self.peer_id,
+                        )
+                    ))
+                    await self._receive_loop(ws)
+            except Exception as exc:
+                self._connected.clear()
+                if self._running:
+                    log.debug("Gossip disconnected (%s); reconnecting in %ss", exc, self.reconnect_interval)
+                    await asyncio.sleep(self.reconnect_interval)
+
+    async def _receive_loop(self, ws) -> None:
+        async for raw in ws:
+            try:
+                envelope = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                continue
+            msg_id = envelope.get("msg_id", "")
+            if msg_id in self._seen:
+                continue
+            self._seen.add(msg_id)
+            if len(self._seen) > 10_000:
+                # Trim seen set to avoid unbounded growth
+                self._seen = set(list(self._seen)[-5_000:])
+
+            topic = envelope.get("topic", "")
+            for handler in self._handlers.get(topic, []):
+                try:
+                    handler(envelope)
+                except Exception:
+                    log.debug("Gossip handler error for topic %s", topic, exc_info=True)
+
+    async def _send(self, envelope: dict) -> None:
+        if self._ws is not None:
+            try:
+                await self._ws.send(json.dumps(envelope))
+            except Exception as exc:
+                log.debug("Gossip send failed: %s", exc)

packages/p2p/meshnet_p2p/identity.py

@@ -0,0 +1,64 @@
+"""Peer identity — stable peer_id and RSA keypair, persisted to disk."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+
+_DEFAULT_IDENTITY_PATH = Path.home() / ".config" / "meshnet" / "identity.json"
+
+
+def _generate_keypair() -> tuple[bytes, bytes]:
+    """Return (private_key_pem, public_key_pem) for a new RSA-2048 keypair."""
+    from cryptography.hazmat.primitives.asymmetric import rsa
+    from cryptography.hazmat.primitives import serialization
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    priv_pem = key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    pub_pem = key.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return priv_pem, pub_pem
+
+
+def _peer_id_from_pubkey(pub_pem: bytes) -> str:
+    return hashlib.sha256(pub_pem).hexdigest()[:16]
+
+
+def load_or_create_identity(path: Path | None = None) -> dict:
+    """Return identity dict with peer_id, private_key_pem, public_key_pem.
+
+    Creates and persists a new identity if none exists at path.
+    """
+    p = path or _DEFAULT_IDENTITY_PATH
+    if p.exists():
+        try:
+            data = json.loads(p.read_text())
+            if "peer_id" in data and "public_key_pem" in data:
+                return data
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    priv_pem, pub_pem = _generate_keypair()
+    identity = {
+        "peer_id": _peer_id_from_pubkey(pub_pem),
+        "private_key_pem": priv_pem.decode(),
+        "public_key_pem": pub_pem.decode(),
+    }
+
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(identity, indent=2))
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    return identity

packages/p2p/meshnet_p2p/mdns.py

@@ -0,0 +1,136 @@
+"""mDNS peer discovery using zeroconf (optional dependency).
+
+Falls back gracefully if zeroconf is not installed.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+MDNS_SERVICE_TYPE = "_meshnet._tcp.local."
+
+try:
+    from zeroconf import ServiceInfo, ServiceBrowser, Zeroconf  # type: ignore[import]
+
+    _HAS_ZEROCONF = True
+except ImportError:
+    _HAS_ZEROCONF = False
+
+
+def _local_ip() -> str:
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except OSError:
+        return "127.0.0.1"
+
+
+class MdnsDiscovery:
+    """Announce this node on mDNS and discover peers on the same LAN.
+
+    If `zeroconf` is not installed, all methods are no-ops.
+
+    Usage::
+
+        disc = MdnsDiscovery(
+            peer_id="abc123",
+            port=8001,
+            on_peer_found=lambda peer_id, addr: print("found", peer_id, addr),
+        )
+        disc.start()
+        ...
+        disc.stop()
+    """
+
+    def __init__(
+        self,
+        peer_id: str,
+        port: int,
+        on_peer_found: Callable[[str, str], None] | None = None,
+        on_peer_lost: Callable[[str], None] | None = None,
+    ):
+        self.peer_id = peer_id
+        self.port = port
+        self.on_peer_found = on_peer_found
+        self.on_peer_lost = on_peer_lost
+        self._zc: "Zeroconf | None" = None  # type: ignore[name-defined]
+        self._info: "ServiceInfo | None" = None  # type: ignore[name-defined]
+        self._browser = None
+
+    def is_available(self) -> bool:
+        return _HAS_ZEROCONF
+
+    def start(self) -> None:
+        if not _HAS_ZEROCONF:
+            log.info("zeroconf not installed — mDNS discovery disabled")
+            return
+        try:
+            self._zc = Zeroconf()
+            local_ip = _local_ip()
+            self._info = ServiceInfo(
+                MDNS_SERVICE_TYPE,
+                f"{self.peer_id}.{MDNS_SERVICE_TYPE}",
+                addresses=[socket.inet_aton(local_ip)],
+                port=self.port,
+                properties={"peer_id": self.peer_id, "version": "1"},
+            )
+            self._zc.register_service(self._info)
+            if self.on_peer_found or self.on_peer_lost:
+                self._browser = ServiceBrowser(
+                    self._zc, MDNS_SERVICE_TYPE, listener=_Listener(self)
+                )
+            log.info("mDNS announced: %s on %s:%d", self.peer_id, local_ip, self.port)
+        except Exception as exc:
+            log.warning("mDNS start failed: %s", exc)
+
+    def stop(self) -> None:
+        if not _HAS_ZEROCONF or self._zc is None:
+            return
+        try:
+            if self._info:
+                self._zc.unregister_service(self._info)
+            self._zc.close()
+        except Exception as exc:
+            log.debug("mDNS stop error: %s", exc)
+        self._zc = None
+
+
+class _Listener:
+    """Internal zeroconf service listener."""
+
+    def __init__(self, disc: MdnsDiscovery):
+        self._disc = disc
+
+    def add_service(self, zc, type_, name):
+        try:
+            info = zc.get_service_info(type_, name)
+            if info is None:
+                return
+            remote_peer_id = (info.properties or {}).get(b"peer_id", b"").decode()
+            if remote_peer_id == self._disc.peer_id:
+                return  # ignore self
+            addr = f"http://{socket.inet_ntoa(info.addresses[0])}:{info.port}"
+            if self._disc.on_peer_found:
+                self._disc.on_peer_found(remote_peer_id, addr)
+        except Exception as exc:
+            log.debug("mDNS add_service error: %s", exc)
+
+    def remove_service(self, zc, type_, name):
+        try:
+            # name is like "peer_id._meshnet._tcp.local."
+            peer_id = name.split(".")[0]
+            if self._disc.on_peer_lost:
+                self._disc.on_peer_lost(peer_id)
+        except Exception as exc:
+            log.debug("mDNS remove_service error: %s", exc)
+
+    def update_service(self, zc, type_, name):
+        pass

packages/p2p/meshnet_p2p/tls.py

@@ -0,0 +1,114 @@
+"""TLS certificate generation and fingerprint helpers for node-to-node comms."""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import ipaddress
+import json
+import os
+import socket
+import ssl
+import stat
+from pathlib import Path
+
+_CERT_PATH = Path.home() / ".config" / "meshnet" / "node_cert.pem"
+_KEY_PATH = Path.home() / ".config" / "meshnet" / "node_key.pem"
+
+
+def generate_self_signed_cert(
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+    common_name: str | None = None,
+) -> tuple[Path, Path]:
+    """Generate a self-signed RSA-2048 cert valid for 10 years.
+
+    Returns (cert_path, key_path). Skips generation if both files already exist.
+    """
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import rsa
+    from cryptography.x509.oid import NameOID
+
+    cert_p = cert_path or _CERT_PATH
+    key_p = key_path or _KEY_PATH
+
+    if cert_p.exists() and key_p.exists():
+        return cert_p, key_p
+
+    cert_p.parent.mkdir(parents=True, exist_ok=True)
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    cn = common_name or socket.getfqdn()
+
+    subject = issuer = x509.Name([
+        x509.NameAttribute(NameOID.COMMON_NAME, cn),
+        x509.NameAttribute(NameOID.ORGANIZATION_NAME, "meshnet-node"),
+    ])
+
+    san_list: list = [x509.DNSName(cn)]
+    try:
+        san_list.append(x509.IPAddress(ipaddress.IPv4Address(socket.gethostbyname(cn))))
+    except (socket.gaierror, ValueError):
+        pass
+    san_list.append(x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")))
+
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(datetime.datetime.now(datetime.timezone.utc))
+        .not_valid_after(datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=365 * 10))
+        .add_extension(x509.SubjectAlternativeName(san_list), critical=False)
+        .sign(key, hashes.SHA256())
+    )
+
+    key_pem = key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.TraditionalOpenSSL,
+        serialization.NoEncryption(),
+    )
+    cert_pem = cert.public_bytes(serialization.Encoding.PEM)
+
+    key_p.write_bytes(key_pem)
+    cert_p.write_bytes(cert_pem)
+    try:
+        os.chmod(key_p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    return cert_p, key_p
+
+
+def cert_fingerprint(cert_path: Path | None = None) -> str:
+    """Return sha256 fingerprint of the cert as 'sha256:<hex>'."""
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes
+
+    p = cert_path or _CERT_PATH
+    cert = x509.load_pem_x509_certificate(p.read_bytes())
+    fp = cert.fingerprint(hashes.SHA256()).hex()
+    return f"sha256:{fp}"
+
+
+def make_server_ssl_context(
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+) -> ssl.SSLContext:
+    """Return an ssl.SSLContext for a server using our self-signed cert."""
+    cert_p = cert_path or _CERT_PATH
+    key_p = key_path or _KEY_PATH
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ctx.load_cert_chain(certfile=str(cert_p), keyfile=str(key_p))
+    return ctx
+
+
+def make_client_ssl_context(verify: bool = False) -> ssl.SSLContext:
+    """Return a client SSLContext. verify=False for self-signed TOFU connections."""
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    if not verify:
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    return ctx

packages/p2p/pyproject.toml

@@ -8,6 +8,14 @@ version = "0.1.0"
 description = "Distributed Inference Network gossip and shard swarm"
 requires-python = ">=3.10"
 
+dependencies = [
+    "cryptography>=41",
+    "websockets>=13",
+]
+
+[project.optional-dependencies]
+mdns = ["zeroconf>=0.131"]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["meshnet_p2p*"]

packages/p2p/relay_bootstrap.json

@@ -0,0 +1,10 @@
+{
+  "relays": [
+    {
+      "url": "ws://localhost:8765",
+      "cert_fingerprint": null,
+      "operator": "localhost-dev",
+      "note": "Local development relay — replace with team relay URL before production"
+    }
+  ]
+}