capyy 0.3.0__tar.gz

capyy-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capyy-0.3.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: capyy
+Version: 0.3.0
+Summary: Tiny encrypted JSON-over-TCP APIs: call a function in another program, on your Wi-Fi or across the internet
+Author: Izac
+License-Expression: MIT
+Project-URL: Homepage, https://libs.zazac.link/capy/
+Project-URL: Documentation, https://libs.zazac.link/capy/
+Keywords: rpc,api,tcp,json,tls,lan,discovery,relay,nat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: French
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# capyy — tiny encrypted JSON-over-TCP APIs
+
+Call a function in another Python program — on the same machine, on your Wi-Fi, or across the internet —
+with one line of code. Zero dependencies, Python 3.9+, encrypted with TLS by default.
+
+```bash
+pip install capyy
+```
+
+The package is published as **capyy**, but you import it as **`capy`**.
+Error messages are in French (the library was written for French speakers), and the full documentation,
+with examples, is at **[libs.zazac.link/capy](https://libs.zazac.link/capy/)**.
+
+## Quick start
+
+```python
+# server.py
+import capy
+
+api = capy.Server(4000)
+
+@api.action("hello")
+def hello(name="you"):
+    return {"message": f"Hello {name}!"}
+
+api.run()
+```
+
+```python
+# client.py
+import capy
+
+print(capy.call("localhost", 4000, "hello", name="Alice"))   # {'message': 'Hello Alice!'}
+```
+
+- An action returns a `dict`, or JSON written as text with `capy.json('{"text": "Hello"}')`.
+- Errors raised on the server come back as `{"erreur": "..."}` (unknown action, bad parameters, exceptions).
+- `capy.call` raises `ConnectionError` when the server does not answer.
+
+## Reading a response
+
+```python
+reply = {"city": "Paris", "temp": "18.5", "days": [{"name": "monday"}, {"name": "tuesday"}]}
+
+capy.get(reply, "days.1.name")          # "tuesday"  (paths go through dicts and lists)
+capy.get(reply, "wind", default=0)      # 0
+capy.to_float(reply, "temp")            # 18.5
+capy.to_int("42"), capy.to_bool("yes")  # 42, True
+```
+
+`to_str`, `to_int`, `to_float`, `to_bool`, `to_list` and `to_dict` raise a `ValueError` that says exactly
+what could not be converted.
+
+## Encryption (TLS)
+
+Everything is encrypted by default, with nothing to configure.
+
+- Each machine running a server creates its own certificate on first launch (`~/.capy`, using `openssl`)
+  and prints its **fingerprint**.
+- Like SSH, a client **remembers a server's fingerprint** the first time (`~/.capy/known_hosts.json`)
+  and raises `capy.SecurityError` if it ever changes.
+- Use `tls=False` on **both** sides to talk in clear (faster on localhost).
+
+## `capy.wifi` — find each other on the same network
+
+```python
+import capy.wifi
+
+api = capy.wifi.Server("living-room")   # announces itself on the LAN, port chosen automatically
+...
+capy.wifi.call("living-room", "light", on=False)   # from any device on the same Wi-Fi
+capy.wifi.scan()                                    # {'living-room': ('192.168.1.42', 51234)}
+```
+
+## `capy.network` — across the internet, through a relay
+
+A machine behind a home router cannot be reached from the internet, so `capy.network` goes through a
+**relay** running on a machine with a public IP (a VPS). Servers connect to it and register a name;
+clients call that name. Everything is encrypted, and the connection is kept open between calls.
+
+```bash
+python3 -m capy.network 3879 my-secret-key      # on the VPS (open the port in its firewall)
+```
+
+```python
+import capy.network
+
+capy.network.use("my-vps.example:3879", key="my-secret-key")
+capy.network.Server("home").run()        # at home, even behind a router
+capy.network.call("home", "temperature") # from anywhere
+```
+
+## License
+
+MIT

capyy-0.3.0/README.md

@@ -0,0 +1,95 @@
+# capyy — tiny encrypted JSON-over-TCP APIs
+
+Call a function in another Python program — on the same machine, on your Wi-Fi, or across the internet —
+with one line of code. Zero dependencies, Python 3.9+, encrypted with TLS by default.
+
+```bash
+pip install capyy
+```
+
+The package is published as **capyy**, but you import it as **`capy`**.
+Error messages are in French (the library was written for French speakers), and the full documentation,
+with examples, is at **[libs.zazac.link/capy](https://libs.zazac.link/capy/)**.
+
+## Quick start
+
+```python
+# server.py
+import capy
+
+api = capy.Server(4000)
+
+@api.action("hello")
+def hello(name="you"):
+    return {"message": f"Hello {name}!"}
+
+api.run()
+```
+
+```python
+# client.py
+import capy
+
+print(capy.call("localhost", 4000, "hello", name="Alice"))   # {'message': 'Hello Alice!'}
+```
+
+- An action returns a `dict`, or JSON written as text with `capy.json('{"text": "Hello"}')`.
+- Errors raised on the server come back as `{"erreur": "..."}` (unknown action, bad parameters, exceptions).
+- `capy.call` raises `ConnectionError` when the server does not answer.
+
+## Reading a response
+
+```python
+reply = {"city": "Paris", "temp": "18.5", "days": [{"name": "monday"}, {"name": "tuesday"}]}
+
+capy.get(reply, "days.1.name")          # "tuesday"  (paths go through dicts and lists)
+capy.get(reply, "wind", default=0)      # 0
+capy.to_float(reply, "temp")            # 18.5
+capy.to_int("42"), capy.to_bool("yes")  # 42, True
+```
+
+`to_str`, `to_int`, `to_float`, `to_bool`, `to_list` and `to_dict` raise a `ValueError` that says exactly
+what could not be converted.
+
+## Encryption (TLS)
+
+Everything is encrypted by default, with nothing to configure.
+
+- Each machine running a server creates its own certificate on first launch (`~/.capy`, using `openssl`)
+  and prints its **fingerprint**.
+- Like SSH, a client **remembers a server's fingerprint** the first time (`~/.capy/known_hosts.json`)
+  and raises `capy.SecurityError` if it ever changes.
+- Use `tls=False` on **both** sides to talk in clear (faster on localhost).
+
+## `capy.wifi` — find each other on the same network
+
+```python
+import capy.wifi
+
+api = capy.wifi.Server("living-room")   # announces itself on the LAN, port chosen automatically
+...
+capy.wifi.call("living-room", "light", on=False)   # from any device on the same Wi-Fi
+capy.wifi.scan()                                    # {'living-room': ('192.168.1.42', 51234)}
+```
+
+## `capy.network` — across the internet, through a relay
+
+A machine behind a home router cannot be reached from the internet, so `capy.network` goes through a
+**relay** running on a machine with a public IP (a VPS). Servers connect to it and register a name;
+clients call that name. Everything is encrypted, and the connection is kept open between calls.
+
+```bash
+python3 -m capy.network 3879 my-secret-key      # on the VPS (open the port in its firewall)
+```
+
+```python
+import capy.network
+
+capy.network.use("my-vps.example:3879", key="my-secret-key")
+capy.network.Server("home").run()        # at home, even behind a router
+capy.network.call("home", "temperature") # from anywhere
+```
+
+## License
+
+MIT

capyy-0.3.0/capy/__init__.py

@@ -0,0 +1,275 @@
+# capy : mini-API en TCP, une ligne JSON par requête / réponse, chiffrée (TLS)
+
+import json as jsonlib  # "json" est pris par capy.json()
+import socket
+import threading
+
+from . import _tls
+from ._tls import SecurityError  # noqa: F401  (capy.SecurityError)
+
+
+# Serveur : @server.action("nom") pour déclarer une action, server.run() pour lancer
+# Le port se donne à Server(port) ou à run(port), au choix
+# Chiffré (TLS) par défaut ; tls=False pour parler en clair (le client aussi doit mettre tls=False)
+class Server:
+    def __init__(self, port=None, tls=True):
+        self.port, self.tls = port, tls
+        self.actions = {}
+        self.listening = False  # True une fois le serveur prêt
+        self._context = None
+
+    def action(self, name):
+        def decorator(function):
+            self.actions[name] = function
+            return function
+        return decorator
+
+    # {"action": "get", "id": 2} -> get(id=2)
+    def handle(self, line):
+        try:
+            request = jsonlib.loads(line)
+            function = self.actions[request.pop("action")]
+        except (ValueError, AttributeError, TypeError):  # pas du JSON, ou pas un objet {...}
+            return {"erreur": "JSON invalide"}
+        except KeyError:
+            return {"erreur": "action inconnue"}
+        try:
+            return function(**request)
+        except Exception as e:
+            return {"erreur": str(e)}
+
+    def client(self, conn, addr):
+        if self._context:
+            conn = _tls.accept(self._context, conn)
+            if conn is None:  # Le client ne parle pas en chiffré -> on raccroche
+                return
+        else:
+            conn.settimeout(10)
+        with conn:
+            try:
+                line = conn.makefile(encoding="utf-8").readline()
+                if not line.strip():  # Connexion ouverte puis fermée sans rien demander
+                    return
+                conn.sendall((jsonlib.dumps(self.handle(line), ensure_ascii=False) + "\n").encode())
+            except (OSError, ValueError):
+                return
+            print(f"{addr[0]} → {line.strip()}")
+
+    # port 0 -> le système choisit un port libre
+    def run(self, port=None):
+        self.port = self.port if port is None else port
+        if self.port is None:
+            raise ValueError("capy: aucun port, utilise Server(port) ou run(port)")
+        if self.tls:
+            self._context, empreinte = _tls.server_context("server")
+        with socket.create_server(("", self.port)) as server:
+            self.port = server.getsockname()[1]
+            self.listening = True
+            if self.tls:
+                print(f"API en écoute sur le port {self.port}, chiffrée (TLS) · empreinte : {empreinte}")
+            else:
+                print(f"API en écoute sur le port {self.port} (pas chiffrée)")
+            while True:
+                conn, addr = server.accept()
+                threading.Thread(target=self.client, args=(conn, addr), daemon=True).start()
+
+
+# Renvoyer du JSON écrit en texte depuis une action
+# Ex : return capy.json('{"text": "Hello"}')
+def json(text):
+    try:
+        return jsonlib.loads(text)
+    except ValueError as e:
+        raise ValueError(f"capy.json : JSON invalide ({e})") from None
+
+
+# ============================================================
+#  EXTRAIRE UNE VALEUR
+# ============================================================
+
+_NOTHING = object()  # Pour savoir si default a été donné (None est une vraie valeur)
+
+
+# Extraire une valeur d'un JSON (dict, liste, ou texte JSON) avec un chemin "a.b.0.c"
+# Ex : get('{"text": "Hello"}', "text") -> "Hello"
+#      get(reponse, "users.0.name") -> "Izac"  (0 = 1er élément d'une liste)
+#      get(reponse, "age", default=0) -> 0 si "age" n'existe pas (au lieu d'une erreur)
+def get(data, path, default=_NOTHING):
+    value = json(data) if isinstance(data, str) else data
+    for key in str(path).split("."):
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        elif isinstance(value, list) and key.lstrip("-").isdigit() and -len(value) <= int(key) < len(value):
+            value = value[int(key)]
+        elif default is not _NOTHING:
+            return default
+        elif isinstance(value, dict):
+            raise ValueError(f"capy.get : clé {key!r} introuvable dans {path!r} (clés : {', '.join(map(str, value)) or 'aucune'})")
+        elif isinstance(value, list):
+            raise ValueError(f"capy.get : {key!r} pas valable dans {path!r} (liste de {len(value)} éléments, 0 à {len(value) - 1})")
+        else:
+            raise ValueError(f"capy.get : impossible d'aller dans {key!r} de {path!r}, la valeur est un {type(value).__name__}")
+    return value
+
+
+# ============================================================
+#  CONVERSIONS
+# ============================================================
+#  Pour transformer une valeur reçue (réponse de capy.call, paramètre d'une action...)
+#  Si ça ne marche pas -> ValueError avec un message clair
+#  (dans une action, le client reçoit alors {"erreur": "..."})
+#  key (optionnel) : extraire d'abord une valeur, comme get()  ->  to_int(reponse, "age")
+
+# Erreur commune : "capy.to_int : impossible de transformer 'abc' (str) en int"
+def _error(name, data, target):
+    text = repr(data)
+    if len(text) > 60:
+        text = text[:60] + "…"
+    return ValueError(f"capy.{name} : impossible de transformer {text} ({type(data).__name__}) en {target}")
+
+
+# Du JSON (dict, liste...) -> texte JSON sur une ligne (un texte reste tel quel)
+# Ex : to_str({"text": "Hello"}) -> '{"text": "Hello"}'
+#      to_str('{"text": "Hello"}', "text") -> "Hello"
+def to_str(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if isinstance(data, str):
+        return data
+    try:
+        return jsonlib.dumps(data, ensure_ascii=False)
+    except (TypeError, ValueError):
+        raise _error("to_str", data, "texte JSON") from None
+
+
+# -> entier. Accepte 42, 42.0, "42", " 42 "
+# Ex : to_int("42") -> 42 / to_int("abc") -> ValueError
+def to_int(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if isinstance(data, bool):  # True est un int pour Python, mais pas pour nous
+        raise _error("to_int", data, "int")
+    if isinstance(data, int):
+        return data
+    if isinstance(data, float) and data.is_integer():
+        return int(data)
+    if isinstance(data, str):
+        try:
+            return to_int(float(data)) if "." in data else int(data)
+        except ValueError:
+            pass
+    raise _error("to_int", data, "int")
+
+
+# -> nombre à virgule. Accepte 4.5, 4, "4.5"
+# Ex : to_float("4.5") -> 4.5
+def to_float(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if not isinstance(data, bool) and isinstance(data, (int, float, str)):
+        try:
+            return float(data)
+        except ValueError:
+            pass
+    raise _error("to_float", data, "float")
+
+
+# -> True / False. Accepte true/false, 1/0, "true"/"false", "oui"/"non", "1"/"0"
+# Ex : to_bool("oui") -> True
+def to_bool(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if isinstance(data, bool):
+        return data
+    if data in (0, 1):
+        return bool(data)
+    if isinstance(data, str):
+        text = data.strip().lower()
+        if text in ("true", "oui", "yes", "1"):
+            return True
+        if text in ("false", "non", "no", "0"):
+            return False
+    raise _error("to_bool", data, "bool")
+
+
+# -> liste. Accepte une liste, un tuple, ou du texte JSON '[1, 2]'
+# Ex : to_list("[1, 2]") -> [1, 2]
+def to_list(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if isinstance(data, (list, tuple)):
+        return list(data)
+    if isinstance(data, str):
+        try:
+            value = jsonlib.loads(data)
+        except ValueError:
+            value = None
+        if isinstance(value, list):
+            return value
+    raise _error("to_list", data, "list")
+
+
+# -> dict. Accepte un dict, ou du texte JSON '{"a": 1}'
+# Ex : to_dict('{"a": 1}') -> {"a": 1}
+def to_dict(data, key=None):
+    if key is not None:
+        data = get(data, key)
+    if isinstance(data, dict):
+        return data
+    if isinstance(data, str):
+        try:
+            value = jsonlib.loads(data)
+        except ValueError:
+            value = None
+        if isinstance(value, dict):
+            return value
+    raise _error("to_dict", data, "dict")
+
+
+# Client : capy.call("127.0.0.1", 4000, "get", id=2) -> dict
+# Lève ConnectionError si le serveur ne répond pas, SecurityError si ce n'est pas le bon serveur
+# tls=False : pour un serveur pas chiffré (Server(..., tls=False))
+def call(host, port, action, /, tls=True, **params):
+    return _call(host, port, action, params, tls, label=f"{host}:{port}")
+
+
+# Envoyer une demande et lire la réponse
+# label : sous quel nom retenir l'empreinte du serveur ("ip:port", "wifi:salon"...)
+def _call(host, port, action, params, tls, label, who="capy"):
+    if not isinstance(host, str) or isinstance(port, bool) or not isinstance(port, int):
+        raise TypeError(
+            f"capy.call : l'ordre est call(host, port, action), ex : call(\"localhost\", 4000, \"get\")"
+            f" -> reçu call({host!r}, {port!r}, {action!r})"
+        )
+    if "://" in host:  # capy parle en TCP, pas en HTTP
+        raise ValueError(f"capy.call : host est un nom ou une IP, pas une URL -> {host.split('://', 1)[1].strip('/')!r}")
+    connected = False
+    hint = " — il est peut-être chiffré : enlève tls=False" if not tls else ""
+    try:
+        if tls:
+            conn = _tls.connect(host, port, label, timeout=3, who=who)
+        else:
+            conn = socket.create_connection((host, port), timeout=3)
+        connected = True
+        with conn:
+            conn.sendall((jsonlib.dumps({"action": action, **params}) + "\n").encode())
+            line = conn.makefile(encoding="utf-8").readline()
+        if not line:
+            raise ConnectionError(f"{who} : le serveur {host}:{port} n'a rien répondu{hint}")
+        return jsonlib.loads(line)
+    except ConnectionError as e:
+        if str(e).startswith(who):  # Message déjà clair (ex : chiffrement impossible)
+            raise
+        error = e
+    except (OSError, ValueError) as e:
+        error = e
+    if connected:  # Il a décroché puis coupé : souvent un serveur chiffré appelé en clair
+        raise ConnectionError(f"{who} : le serveur {host}:{port} a coupé la connexion sans répondre{hint}") from None
+    raise ConnectionError(f"{who} : le serveur {host}:{port} ne répond pas ({type(error).__name__})") from None
+
+
+# Empreinte du certificat des serveurs capy de cette machine (à donner aux clients qui veulent vérifier)
+# Ex : capy.fingerprint() -> "9dfa7b98…"
+def fingerprint():
+    _tls.server_context("server")  # Crée le certificat s'il n'existe pas encore
+    return _tls.my_fingerprint("server")

capyy-0.3.0/capy/_tls.py

@@ -0,0 +1,139 @@
+# capy._tls : le chiffrement (TLS) commun à capy, capy.wifi et capy.network
+#
+# Chaque machine qui fait tourner un serveur crée son certificat tout seul (dans ~/.capy, avec openssl).
+# Comme SSH, un client retient l'empreinte d'un serveur à la 1re connexion (~/.capy/known_hosts.json) ;
+# si elle change ensuite -> SecurityError (quelqu'un se fait peut-être passer pour le serveur).
+
+import hashlib
+import hmac
+import json
+import os
+import pathlib as pth
+import socket
+import ssl
+import subprocess
+import threading
+
+CAPY_DIR = pth.Path.home() / ".capy"
+KNOWN_FILE = CAPY_DIR / "known_hosts.json"
+LOCAL_HOSTS = ("127.0.0.1", "localhost", "::1")
+_lock = threading.Lock()
+
+
+# L'empreinte d'un serveur ne correspond pas : on refuse de lui parler
+class SecurityError(Exception):
+    pass
+
+
+# Empreinte d'un certificat (64 caractères)
+def fingerprint(der):
+    return hashlib.sha256(der).hexdigest()
+
+
+# Certificat de cette machine : créé une fois avec openssl, puis réutilisé
+# kind : "server" (capy, capy.wifi) ou "relay" (capy.network)
+def _certificate(kind):
+    cert, key = CAPY_DIR / f"{kind}-cert.pem", CAPY_DIR / f"{kind}-key.pem"
+    with _lock:
+        if not (cert.exists() and key.exists()):
+            CAPY_DIR.mkdir(exist_ok=True)
+            try:
+                subprocess.run(
+                    ["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "3650",
+                     "-subj", f"/CN=capy-{kind}", "-keyout", str(key), "-out", str(cert)],
+                    check=True, capture_output=True,
+                )
+            except (OSError, subprocess.CalledProcessError) as e:
+                raise RuntimeError(f"capy : impossible de créer le certificat avec openssl ({e})") from None
+            os.chmod(key, 0o600)  # Clé privée lisible par toi seul
+    return cert, key
+
+
+# Empreinte du certificat de cette machine (None s'il n'existe pas encore)
+def my_fingerprint(kind="server"):
+    cert = CAPY_DIR / f"{kind}-cert.pem"
+    try:
+        return fingerprint(ssl.PEM_cert_to_DER_cert(cert.read_text()))
+    except (OSError, ValueError):
+        return None
+
+
+# Contexte TLS côté serveur -> (contexte, empreinte)
+def server_context(kind="server"):
+    cert, key = _certificate(kind)
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.load_cert_chain(cert, key)
+    return context, my_fingerprint(kind)
+
+
+# Chiffrer une connexion qui arrive sur un serveur (None si le client ne parle pas en TLS)
+def accept(context, raw, timeout=10):
+    try:
+        raw.settimeout(timeout)
+        conn = context.wrap_socket(raw, server_side=True)
+        conn.settimeout(timeout)
+        return conn
+    except (OSError, ValueError):
+        raw.close()
+        return None
+
+
+# Se connecter en chiffré, et vérifier que c'est bien le bon serveur (empreinte)
+# label : sous quel nom retenir l'empreinte ("ip:port", "wifi:salon"...)
+# pinned : empreinte attendue (sinon : celle retenue la 1re fois)
+def connect(host, port, label, timeout=10, pinned=None, who="capy", kind="serveur"):
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.check_hostname = False       # Certificat fait maison :
+    context.verify_mode = ssl.CERT_NONE  # on le vérifie nous-mêmes avec l'empreinte juste après
+    raw = socket.create_connection((host, port), timeout=timeout)
+    try:
+        conn = context.wrap_socket(raw)
+    except (ssl.SSLError, OSError):
+        raw.close()
+        raise ConnectionError(
+            f"{who} : connexion chiffrée impossible avec {host}:{port}"
+            f" — le {kind} n'est peut-être pas chiffré (tls=False des deux côtés pour s'en passer)"
+        ) from None
+    try:
+        check(label, fingerprint(conn.getpeercert(binary_form=True)), pinned, who, kind, local=host in LOCAL_HOSTS)
+    except SecurityError:
+        conn.close()
+        raise
+    return conn
+
+
+# Comparer une empreinte avec celle attendue, ou celle retenue la 1re fois
+def check(label, seen, pinned=None, who="capy", kind="serveur", local=False):
+    wanted = (pinned or "").replace(":", "").lower()
+    if wanted:
+        if not hmac.compare_digest(wanted, seen):
+            raise SecurityError(f"{who} : l'empreinte du {kind} {label} n'est pas celle attendue (reçu {seen})")
+        return
+    if local and seen == my_fingerprint("server"):  # Ce Mac lui-même : rien à vérifier
+        return
+    with _lock:
+        known = _known()
+        if label not in known:
+            CAPY_DIR.mkdir(exist_ok=True)
+            known[label] = seen
+            KNOWN_FILE.write_text(json.dumps(known, indent=4))
+            print(f"{who} : nouveau {kind} {label}, empreinte retenue {seen}", flush=True)
+            return
+    if not hmac.compare_digest(known[label], seen):
+        raise SecurityError(
+            f"{who} : l'empreinte du {kind} {label} a CHANGÉ ! Quelqu'un se fait peut-être passer pour lui.\n"
+            f"  Si tu as réinstallé le {kind} (normal), supprime sa ligne dans {KNOWN_FILE}"
+        )
+
+
+# Les empreintes retenues (reprend l'ancien fichier known_relays.json s'il existe)
+def _known():
+    old = CAPY_DIR / "known_relays.json"
+    if not KNOWN_FILE.exists() and old.exists():
+        old.rename(KNOWN_FILE)
+    try:
+        return json.loads(KNOWN_FILE.read_text())
+    except (OSError, ValueError):
+        return {}