Configuration distante (WSS)

Connectez zerocode sur votre poste de travail à un daemon s’exécutant sur une autre machine (Raspberry Pi, serveur domestique, VPS, etc.).

Pour le guide complet, option par option, couvrant les trois topologies (directe, démon vers relais et client via relais), voir Transport sécurisé (configuration de bout en bout).

Le plan WSS est authentifié mutuellement (mTLS). Chaque client présente un certificat ; il n’existe aucun mode avec authentification du serveur uniquement / sans authentification. Le moyen le plus simple d’obtenir un certificat client est l’enrôlement (ci-dessous) : vous n’avez pas à gérer manuellement les certificats. Si vous préférez en générer un vous-même, consultez les étapes d’utilisation de votre propre certificat dans « Sur votre poste de travail » plus bas. --tls-skip-verify assouplit uniquement la vérification du certificat serveur pour un certificat auto-signé du démon ; le certificat client reste obligatoire dans tous les cas.

Inscription (recommandée)

La première fois que vous connectez interactivement un client sans certificat, zerocode l’inscrit automatiquement :

zerocode --connect wss://<remote-host>:9781

Il demande le code d’appariement à usage unique du démon (imprimé dans le journal du démon au démarrage), affiche une chaîne d’authentification courte (SAS) à comparer à celle de la console du démon (afin de détecter une autorité de certification de type homme du milieu), puis récupère et met en cache un certificat client sous <config-dir>/tls. Les exécutions ultérieures ne nécessitent aucune configuration, et le certificat est automatiquement renouvelé vers ~50 % de sa durée de vie. Pour effectuer l’inscription sans interaction, utilisez zerocode --enroll --connect wss://<remote-host>:9781.

Un client sans certificat qui atteint le plan WSS sans s’être inscrit reçoit un message exploitable « enroll first » (et le démon journalise le client non migré rejeté) — jamais de blocage silencieux. Un certificat révoqué est refusé lors de la négociation (sur la base du registre des certificats émis), de sorte que la révocation d’un appareil perdu prend effet dès sa prochaine connexion.

allow_unpaired_enrollment dans la section [enroll] est réservé à un futur flux de migration sans code. Cette version rejette toute valeur non vide au démarrage du démon ; laissez-la vide et utilisez le code d’association affiché.

Sur l’hôte distant (côté daemon)

1. Activez WSS. Définissez la configuration wss dans le volet Config (ou via la passerelle / zeroclaw config set) :

   [wss]
   enabled = true
   

   Laissez cert_path / key_path vides (la valeur par défaut) : le démon génère automatiquement son propre CA et son certificat serveur dans <data_dir>/tls/ au premier démarrage ; vous n’avez donc pas besoin d’exécuter vous-même openssl. Renseignez-les uniquement pour utiliser votre propre certificat serveur, et utilisez des chemins absolus dans les deux cas ; la configuration ne développe pas ~.

2. Ouvrez le port du pare-feu :

   sh

   sudo ufw allow 9781/tcp
   

   Le port WSS par défaut est 9781. Modifiez-le avec port = <number> dans la section [wss].

3. Démarrer (ou redémarrer) le daemon :

   sh

   zeroclaw daemon
   

   Vous devriez voir une ligne de journal confirmant que l’écouteur WSS a démarré sur 0.0.0.0:9781.

Sur votre poste de travail (côté zerocode)

L’enrôlement (ci-dessus) est le moyen le plus rapide d’obtenir un certificat client. Si vous préférez utiliser votre propre certificat client plutôt que de procéder à un enrôlement interactif :

1. Émettez un certificat client sur l’hôte du démon, à partir de l’autorité de certification mTLS du démon :

   zeroclaw security issue-client-cert --name my-laptop --out-dir /tmp/my-laptop-tls
   

   Cela écrit ca.crt, client.crt et client.key dans --out-dir. Ajoutez --force pour remplacer un certificat existant portant ce nom.

2. Copiez les trois fichiers dans <config-dir>/tls/ du poste de travail (ensuite, zerocode --connect wss://<remote-ip>:9781 les trouve automatiquement), ou indiquez-les explicitement :

   sh

   zerocode --connect wss://<remote-ip>:9781 \
     --tls-ca-cert     /path/ca.crt \
     --tls-client-cert /path/client.crt \
     --tls-client-key  /path/client.key
   

   Comme ca.crt est la même AC qui a signé le certificat serveur du daemon, cela vérifie également le serveur ; --tls-skip-verify est uniquement nécessaire si vous omettez --tls-ca-cert avec un certificat auto-signé du daemon que vous n’avez pas épinglé.

C’est tout. zerocode se reconnecte automatiquement si la connexion est interrompue.

Référence de configuration

La section wss :