Au bureau, votre homelab disparaît : la Webapp emprunte désormais les connexions enregistrées par Desktop


Mercredi après-midi, un portable emprunté, une salle de réunion. Vous ouvrez un navigateur, tapez l’adresse Webapp de la machine restée à la maison, et vous voulez un simple coup d’œil aux cron jobs qui tournent sur votre homelab. Ce que vous obtenez, c’est un seul gateway : celui en local. Desktop en a trois ou quatre d’enregistrés, et vous pourriez réciter leurs noms de mémoire — Homelab, le portable du boulot, ce VPS que vous payez tous les mois.

Ce n’est pas un problème de permissions et vous n’êtes pas déconnecté. La Webapp n’a jamais connu que le gateway qui sert la page. Tout le reste vivait dans le répertoire de données de l’application desktop, invisible depuis le navigateur.

Le 7 novembre, une série de commits a changé ça : les connexions enregistrées ont cessé d’être des données privées du desktop pour devenir un store que toute la machine partage. La Webapp lit la même liste, et elle peut joindre n’importe quelle entrée exactement comme le fait Desktop.

Un fichier, deux hôtes

Le changement est simple à énoncer : Desktop gardait son registre de connexions et ses connexions OAuth natives dans le répertoire userData d’Electron. Ils vivent maintenant dans le home Hermes, à côté de ui-preferences.json :

  • gateway-connections.json — les connexions elles-mêmes : libellés, URLs, hôtes SSH, et pour chaque entrée son propre token de session et ses en-têtes supplémentaires
  • gateway-connection-tokens.json — les connexions OAuth, indexées par connexion

Les deux sont en mode 0600, accessibles au seul propriétaire. Le processus principal d’Electron et le serveur de la Webapp écrivent tous les deux dans ces fichiers, et lisent le même : ajouter Homelab dans Desktop apparaît donc dans le navigateur après un rafraîchissement — et inversement, sans redémarrage. Au premier lancement d’un build doté de la liste partagée, connections.json, connection.json et native-oauth-tokens.json sont copiés une seule fois depuis l’ancien répertoire userData, avec les mêmes ids : rien à reconfigurer, aucun doublon. Les anciens fichiers restent intacts — les builds plus anciens continuent de fonctionner — et ne sont plus jamais relus.

Le contrat d’écriture compte, parce que deux hôtes sur un seul fichier, c’est toute l’astuce : les écrivains prennent un verrou de répertoire <store>.lock, remplacent le fichier en entier via fichier temporaire puis rename, mettent de côté un fichier illisible sous .corrupt-<ms> au lieu de l’écraser, et ne traitent comme « pas de store » que l’absence de fichier.

Le navigateur ne parle toujours qu’à un gateway

C’est la partie que les gens comprennent de travers. La Webapp ne fait pas joindre le VPS directement à votre navigateur — elle ne peut pas, et elle ne doit pas. Chaque requête et chaque socket partant du navigateur va toujours au gateway qui sert la page, et ce gateway la relaie vers la cible enregistrée :

  • mode token : le X-Hermes-Session-Token enregistré
  • mode OAuth : un bearer rafraîchissable, avec un ticket à usage unique pour la poignée de main WebSocket
  • plus les éventuels en-têtes supplémentaires enregistrés sur cette connexion

Le distant n’a rien à configurer de son côté — il voit un client ordinaire. Chaque gateway enregistré rejoint le sélecteur de gateways de la Webapp et les groupes de la barre latérale, donc vous pouvez passer de l’un à l’autre, grouper par Gateway & profile, et faire glisser les sections dans l’ordre voulu (ça renomme et réordonne les libellés de la barre latérale, jamais le gateway).

OAuth est passé côté serveur lui aussi : la machine qui sert la page pilote elle-même le flux natif RFC 8252, conserve le vérificateur PKCE, envoie le navigateur vers /auth/native/authorize du distant, et reçoit le callback sur /webapp/gateway-connections/oauth/callback. Les tokens tournent via /auth/native/refresh du distant — un seul en vol par connexion à la fois ; un 401 abandonne la connexion, une panne la conserve.

Si votre navigateur n’est pas sur la machine qui sert la page — le cas normal, puisque vous êtes au bureau et le gateway à la maison — la redirection atterrit sur votre propre loopback et le serveur ne la voit jamais. L’éditeur de connexion vous offre alors un champ pour recoller cette adresse, ce qui termine la connexion.

Les connexions SSH fonctionnent aussi dans le navigateur. Le serveur embarque un portage du chemin SSH de Desktop : un ControlMaster vers l’hôte de l’entrée, le même spawn serve --isolated --host 127.0.0.1 --port 0 (avec fichier de token de session et nonce de propriétaire) sous le mutex des marqueurs de mise à jour distants, et un forward limité à 127.0.0.1 comme cible pour le relais. La propriété est limitée au store de connexions de cette machine, donc Desktop et le gateway ne se tuent jamais mutuellement leur serve. Les deux bouts doivent être sous Linux ou macOS ; un distant Windows ou un hôte local Windows est refusé comme plateforme non prise en charge.

Le prix, dit clairement

C’est ici que je veux que vous vous arrêtiez et lisiez deux fois.

La frontière de confiance de la Webapp, c’est « quiconque peut se connecter à cette page ». Une fois que c’est le cas, cette personne peut utiliser tous les gateways enregistrés sur cette machine — en tant que propriétaire de l’identifiant enregistré. La doc le dit sans adoucir : n’enregistrez que des gateways auxquels vous laisseriez ces gens accéder.

Ce qui limite le rayon d’action, c’est ce que le navigateur peut faire des réponses : une réponse relayée passe sous une politique de contenu sandboxée, n’est jamais mise en cache par le navigateur, et ne peut pas rediriger hors de ce gateway ; le relais ne garde aucun cookie jar ; supprimer une connexion ferme immédiatement ses sockets ouverts.

Cinq raisons pour qu’un identifiant atterrisse à la mauvaise adresse

La moitié de ce lot, ce sont des correctifs, et ils appartiennent tous à la même famille : l’identifiant et l’adresse à laquelle il a été envoyé pouvaient ne pas concorder. Cette partie est plus instructive que la fonctionnalité.

Un : deux lectures par dial. Le dial lisait l’URL de l’entrée, puis relisait son token, ses en-têtes et sa connexion par id. Une édition qui tombait entre ces deux lectures associait l’ancienne adresse à l’identifiant de la nouvelle. Le store fournit désormais un snapshot de dial unique — entrée, URL, token, en-têtes et la connexion liée à l’URL — à partir d’une seule lecture du registre. Le mode token dial l’URL du snapshot ; ensure_access_token d’OAuth renvoie le token avec l’adresse qui l’a émis, et le ticket de socket n’est forgé que par l’adresse que le socket dial réellement.

Deux : les connexions n’étaient pas liées à l’URL qui les avait émises. Les ensembles de tokens étaient indexés par id de connexion, et les ids sont des slugs de libellé recyclés. Changez une URL, ou supprimez puis rajoutez sous le même libellé, et le relais pouvait envoyer le bearer de l’hôte A vers l’hôte B et POSTer le refresh token de l’hôte A sur /auth/native/refresh de l’hôte B. Chaque ensemble stocké porte maintenant son baseUrl d’émission ; un ensemble dont le baseUrl diffère de l’URL courante de l’entrée est lu comme déconnecté dans les deux jumeaux, et le refresh ne part que vers l’URL propre à l’ensemble. Toute écriture de registre qui supprime une entrée ou change son url ou son authMode supprime l’ensemble des deux côtés.

Trois : une page cross-site pouvait emprunter votre relais. Le cookie de session de la Webapp est en SameSite=Lax, donc une navigation top-level cross-site vers /api/relay/<id>/<path> le transportait, et le relais faisait ce GET sur le gateway enregistré avec l’identifiant enregistré. La réponse était sandboxée et illisible, mais un GET distant avec des effets de bord s’exécutait quand même. Désormais, une requête relayée dont Sec-Fetch-Site est présent et n’est pas same-origin reçoit un 403 avant que quoi que ce soit ne parte ; les fetch de la page elle-même, et les clients qui n’envoient pas de Fetch Metadata, sont relayés comme avant.

Quatre : un callback collé pouvait être racheté sur la mauvaise connexion. La finalisation rachetait le code et stockait les tokens d’abord, et ne comparait qu’ensuite le flux en cours avec l’id du chemin. Le flux est maintenant mis en correspondance sous le verrou des flux avant le rachat : une redirection collée pour une autre connexion reçoit un 400 sans une seule requête de token, et le flux propre à cette connexion reste utilisable.

Cinq : le clonage et l’export emportaient des tokens en clair. hermes profile create --clone-all copiait les deux stores machine dans le clone, et hermes profile export expédiait ensuite des tokens de session en clair, parce que le scrubber d’export ne reconnaissait pas l’enveloppe {"encoding":"plain","value":…}. Les deux stores ont rejoint PROFILE_CREDENTIAL_PATHS ; clone-all les saute, eux et leur répertoire .lock ; le scrub d’export masque chaque enveloppe dans le JSON préparé.

Tant qu’on y est : pourquoi ces secrets sont-ils en clair sur le disque plutôt que dans le keychain de l’OS ? Parce que le serveur de la Webapp doit les lire, et le keychain n’existe pas pour un processus serveur. Les permissions de fichier sont la protection, plus une frontière — le renderer et les plugins ne voient jamais les octets des tokens (le host.connections() du SDK plugin ne renvoie que libellés, types et id primaire). Un secret chiffré par un build plus ancien avec safeStorage est déchiffré une fois à l’import ; celui qui refuse de se déchiffrer n’est pas jeté, il est conservé tel quel et listé dans les importNotices du fichier jusqu’à ce que le keychain de Desktop réponde et le convertisse.

Comment s’en servir

Desktop et la Webapp partagent le chemin parce qu’ils partagent la page : Settings → Gateways. Faites défiler jusqu’à Registered gateways et cliquez sur Add connection :

  • Local — le runtime que gère cette application (géré par l’app, non supprimable)
  • Remote gateway — un hermes serve en cours d’exécution ; donnez l’URL et choisissez session token ou OAuth
  • SSH — un champ composite user@host:22, plus un chemin complet facultatif vers l’exécutable hermes distant
  • Hermes Cloud — vient du flux de connexion et de découverte du Portal, pas d’une URL tapée à la main

Puis cliquez sur Test. Il sonde les deux jambes de la connexion, HTTP et WebSocket, donc « Reachable » veut dire que le chat fonctionnera vraiment, pas que le port répond. Dans la Webapp, Test sur une ligne SSH ouvre le même tunnel géré que celui qu’utilise le gateway, en démarrant (ou en réutilisant) hermes serve sur le distant ; ce tunnel n’est pas refermé dans votre dos — il s’arrête quand vous supprimez la connexion ou arrêtez le gateway, ou de lui-même après le timeout d’inactivité distant dashboard.ssh_isolated_idle_grace_s (15 minutes par défaut) sans client ni travail.

Les doublons sont rejetés à l’enregistrement : une seule entrée locale, jamais plus ; les entrées remote et cloud se dédupliquent sur l’URL normalisée (entre les deux types, donc une entrée cloud et une entrée remote ne peuvent pas pointer sur la même URL) ; les entrées SSH se dédupliquent sur user@host:port plus le profil distant.

Quand vous pourrez réellement l’avoir

Honnêtement : pas encore, si vous suivez les releases officielles. Ces commits sont arrivés le 7 novembre, et la v0.23.0 est sortie le 5 novembre — ils sont sur main et dans aucun tag. hermes update vous livre les releases, donc vous attendez la suivante, ou vous suivez main.

Mise à jour (10/11/2026) : ces changements sont sortis dans la v0.23.1 (9 novembre) : un hermes update suffit. Le « pas dans la v0.23.0 » ci-dessus reste exact ; la v0.23.1 comble l’écart.

En attendant, les connexions enregistrées de Desktop fonctionnent depuis un moment (voir le guide desktop multi-gateway). Ce qui change, c’est que la moitié navigateur cesse d’être un citoyen de seconde classe.

Et si votre connexion à un gateway distant vous a donné du fil à retordre avec les redirections loopback et les jump hosts, les trois routes de terminer OAuth sur un serveur distant tiennent toujours. La nouveauté, c’est que le serveur exécute désormais tout le flux natif à votre place, et vous laisse recoller l’adresse quand le callback atterrit sur la mauvaise machine.

La version courte

Les connexions gateway enregistrées sont passées du business privé d’une application desktop à une infrastructure machine partagée : un fichier JSON en 0600, deux hôtes qui y écrivent, le navigateur qui ne parle qu’à son gateway serveur, des identifiants liés à une adresse avant d’être relayés. La capacité en elle-même est simple. Les cinq correctifs sont la partie précieuse — ils montrent que « à qui appartient cet identifiant » est un piège partout dès qu’on autorise les éditions et les écritures concurrentes multi-hôtes.

Pour la surface en ligne de commande, voyez la référence hermes gateway du site ; pour le côté desktop, le guide du mode interface explique comment l’application présente les backends locaux et distants.