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.

Il vous faut deux éléments : un certificat et un jeton de porteur. Le certificat client sécurise le transport : il prouve quel appareil se trouve à l’autre extrémité de la connexion TLS. Il ne dit pas qui vous êtes. Chaque connexion distante doit aussi présenter un jeton de porteur dans la poignée de main initialize, et c’est ce jeton qui vous identifie (voir Jeton de porteur ci-dessous). L’enrôlement ne vous fournit que le certificat. Un client disposant d’un certificat mais sans jeton complète la poignée de main TLS, puis est refusé avec AUTH_REQUIRED (-32010).

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’appairage à usage unique du daemon (affiché dans le journal du daemon au démarrage), affiche une chaîne d’authentification courte (SAS) à comparer avec la console du daemon (ce qui permet de détecter une autorité de certification d’interception, ou « homme du milieu »), puis récupère et met en cache un certificat client sous <config-dir>/tls. Les exécutions suivantes réutilisent ce certificat sans demander à nouveau, et il est renouvelé automatiquement à environ 50 % de sa durée de validité. Pour effectuer l’enrôlement de manière non interactive, utilisez zerocode --enroll --connect wss://<remote-host>:9781.

L’inscription ne vous fournit pas de jeton d’accès (bearer token). Le code d’appairage d’inscription est distinct du code d’appairage de la passerelle, et il est consommé par l’inscription. Vous avez tout de même besoin d’un jeton avant que le daemon accepte une session ; voir Bearer token.

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é.

Quoi qu’il en soit, le certificat ne vous permet de passer que la couche TLS. Ajoutez ensuite un jeton Bearer.

Jeton Bearer (obligatoire pour chaque connexion)

Le démon refuse tout initialize distant qui ne contient pas de auth_token, même lorsque le certificat client est valide. Une fois que vous fournissez un jeton à zerocode, celui-ci le présente à chaque connexion et à chaque reconnexion.

1. Associez-vous à la passerelle pour obtenir un jeton. Utilisez la page Pairing du tableau de bord ou, sur l’hôte du démon (la passerelle écoute sur 127.0.0.1:42617 par défaut), envoyez en POST le code d’association de la passerelle figurant dans le journal du démon vers /pair :

   curl -X POST http://127.0.0.1:42617/pair -H 'X-Pairing-Code: <code>'
   

   Je n’ai pas de chaîne source à traduire, et je ne dispose ni d’un code d’appairage ni d’un code d’inscription pour zerocode dans cette conversation. Pouvez-vous me fournir la chaîne à traduire ? Je ne modifierai aucun jeton zc_....

2. Donnez le jeton à zerocode. La variable d’environnement est la méthode recommandée, car elle garde le secret hors du fichier de configuration :

   export ZEROCLAW_AUTH_TOKEN=zc_...
   zerocode --connect wss://<remote-host>:9781
   

   Ou définissez-la dans la configuration de zerocode, soit comme chemin vers un fichier que vous seul pouvez lire, soit directement en ligne :

   [connection.wss]
   uri = "wss://<remote-host>:9781"
   auth_token_file = "/abs/path/zerocode-bearer"   # ou : auth_token = "zc_..."
   

   Ordre de priorité : ZEROCLAW_AUTH_TOKEN, puis auth_token_file, puis auth_token. Un fichier de jeton lisible par d’autres comptes est ignoré et un avertissement est affiché.

Pour utiliser un jeton d’accès OIDC au lieu d’un jeton d’appairage, définissez également auth_provider = "oidc.<alias>" sous [connection.wss]. Pour les règles de permissions de fichiers, OIDC et le traitement du jeton par le daemon, consultez Authentification et principaux.

Après cela, zerocode --connect wss://<remote-host>:9781 (ou simplement zerocode avec uri dans la configuration) ne nécessite plus aucun autre indicateur, et zerocode se reconnecte automatiquement si la connexion est interrompue.

Référence de configuration

La section wss :