hachiflow.com

Cet article parle de Buzz, notre produit précédent. Aujourd'hui, nous construisons Waggle.

Appairage

Pourquoi l'appairage par QR renvoie 404 : le sidecar que personne n'a démarré

Scannez le code, regardez-le échouer. L'appairage a besoin d'un canal qu'un téléphone non appairé peut atteindre, et sur un relais qui impose l'appartenance ce canal est un processus distinct lié à la boucle locale. Il est livré dans l'image du relais, ce qui est précisément pourquoi il est facile de le laisser éteint. Nous l'avons fait.

Tout fonctionne, sauf le code QR

Le signalement arrive sans le moindre détail utile, parce qu'il n'y en a aucun à donner. Quelqu'un ouvre Buzz sur son ordinateur, choisit l'option pour ajouter un téléphone, et un code QR s'affiche aussitôt. Il le scanne. Quelques secondes plus tard, l'ordinateur affiche une erreur d'appairage, et son texte contient un 404.

De quoi dérouter, parce que le relais est manifestement en bonne santé. Les messages arrivent, les fichiers se téléversent, les invitations fonctionnent, et l'ordinateur qui n'arrive pas à s'appairer est lui-même connecté au relais à cet instant. Seul l'appairage est cassé, et la raison, c'est que l'appairage est la seule chose qui ne parle pas au relais que vous avez configuré.

Un téléphone non appairé ne peut pas frapper à la porte d'entrée

Un relais qui impose l'appartenance filtre la connexion WebSocket elle-même : vous prouvez qui vous êtes avant d'obtenir une socket. C'est tout l'intérêt de l'activer. Mais un téléphone qui n'a jamais été appairé ne détient aucune identité que le relais reconnaisse. Il ne peut pas se connecter au relais principal pour recevoir la poignée de main d'appairage, parce que c'est justement cette poignée de main qui lui donne la clé dont il aurait besoin pour se connecter. L'œuf et la poule.

La poignée de main d'appairage passe donc ailleurs, par un canal qui accepte n'importe qui : un minuscule relais qui transporte un seul type d'événement, ne garde aucun historique et vous oublie au bout de deux minutes. Sur un relais ouvert, sans contrôle d'appartenance, rien de tout cela n'est nécessaire, car le téléphone peut simplement se connecter au relais principal comme n'importe quel inconnu. Le canal hors bande existe précisément parce que vous avez verrouillé la porte d'entrée.

Le canal est un second processus, et il se cache en pleine vue

Ce canal, c'est buzz-pair-relay, un binaire distinct dans l'arborescence de Buzz. Il est volontairement petit : pas de persistance, pas d'authentification, pas d'historique, un seul type d'événement, signatures vérifiées, dédoublonnage, une fenêtre de fraîcheur, un plafond de 128 connexions, une limite de trame de 4 Kio et une durée de vie stricte de 120 secondes par connexion. C'est le genre de composant qu'on lit d'une traite avant de ne plus jamais y penser.

Sa note de déploiement raconte à elle seule toute l'histoire de cet article. Il écoute uniquement sur la boucle locale, par défaut 127.0.0.1:5000, et sa documentation exige devant lui un proxy inverse qui lui route /pair, termine le TLS et impose des délais de lecture. Il ne restreint pas lui-même les chemins et ne limite pas les connexions avant la bascule, à dessein, parce que c'est le travail du proxy. Un processus qui écoute sur 127.0.0.1 et vers lequel rien ne route est un processus qui ne fait rien du tout, en silence, pour toujours.

Et voici ce qui le rend insaisissable : le binaire est livré dans l'image standard du relais. Le Dockerfile le compile avec le relais et le copie dans /usr/local/bin/buzz-pair-relay. Si vous le cherchez, il est donc bien là, dans le conteneur. Il a l'air installé parce qu'il est installé. Simplement, il n'a jamais été démarré, et rien n'a jamais été routé vers lui.

Comment le client décide où s'appairer

Avant de dessiner un code QR, l'ordinateur demande au relais où se fait l'appairage. La question est un simple GET HTTP vers l'origine du relais avec Accept: application/nostr+json, le document d'information standard NIP-11, et la réponse décide de tout ce qui suit.

Il y a trois issues. Si le document contient un pairing_relay_url qui s'analyse comme une URL ws ou wss, l'ordinateur l'utilise et rien d'autre ne compte. Sinon, si supported_nips contient 43, le relais déclare qu'il impose l'appartenance, et l'ordinateur se rabat sur une ancienne convention : prendre l'URL du relais lui-même et y ajouter /pair. À défaut des deux, il utilise directement le relais principal, ce qui est la bonne réponse pour un relais ouvert.

La deuxième branche est le piège. Elle est choisie sur la foi d'une annonce, pas d'une vérification. Rien ne contrôle que /pair existe avant que le code QR ne s'affiche, parce que le code QR est construit à partir de l'URL et non d'une connexion réussie vers elle. Un relais qui impose l'appartenance, et qui annonce donc honnêtement NIP-43, envoie ainsi chaque tentative d'appairage vers un chemin qui peut renvoyer 404, et c'est votre client qui s'en aperçoit.

Bureau Buzz lit NIP-11 pairing_relay_url annoncé par le relais supported_nips: 43 ancien : même hôte + /pair 404 : personne n'écoute wss://pairing.example wss://relay.example/pair buzz-pair-relay boucle locale, port 5000 le proxy doit router /pair ici
Avant de dessiner le code QR, l'ordinateur demande au relais où se fait l'appairage. Un relais qui annonce un hôte d'appairage est utilisé directement. Un relais qui n'annonce que NIP-43 envoie le client vers son propre nom d'hôte suivi de /pair, et cette route renvoie 404 tant que personne n'a démarré le sidecar et routé vers lui. Rien ne le vérifie au préalable, donc le code QR s'affiche dans les deux cas.

Une requête, et vous savez

Pas besoin de téléphone, de code QR ni d'un second appareil pour le vérifier. Demandez /pair au nom d'hôte public du relais avec curl, depuis n'importe où.

Un 404 veut dire que l'appairage est cassé sur ce relais, aujourd'hui, pour tout le monde. La réponse qu'il faut connaître, c'est celle d'un relais sain, parce qu'elle ressemble elle aussi à un échec : un sidecar correctement routé répond 400 Bad Request. Curl n'envoie pas de bascule WebSocket, et le sidecar rejette avec un 400 tout ce qui n'est pas une bascule bien formée, avant de faire quoi que ce soit d'autre. 400 est donc une bonne nouvelle et 404 une mauvaise, et les deux ne diffèrent que d'un chiffre, à un endroit que personne ne regarde de près.

Lisez ensuite ce que le relais affirme, parce que c'est ce qui décide si /pair est seulement la bonne chose à tester. Si pairing_relay_url est défini, les clients vont là-bas et le même test 400 contre 404 s'applique plutôt à cet hôte. S'il est absent et que NIP-43 figure dans la liste, l'ancienne route est active et /pair est exactement là où arrivera chaque client.

tout le diagnostic
# est-ce que quelque chose répond sur /pair ? $ curl -i https://<relay-host>/pair # 404 veut dire que l'appairage est cassé. 400 Bad Request est la bonne réponse : c'est le sidecar qui refuse une requête qui n'est pas une bascule WebSocket. # et que promet le relais dans son document NIP-11 ? $ curl -sH 'Accept: application/nostr+json' https://<relay-host>/ \ | jq '{pairing_relay_url, nip43: (.supported_nips | index(43))}'

Si pairing_relay_url renvoie une valeur, c'est cette URL qu'il faut tester, et /pair n'est pas utilisé du tout. Si elle est nulle et que la vérification NIP-43 renvoie un indice plutôt que null, alors /pair sur cet hôte est exactement là où ira chaque client.

Trois correctifs, un seul suffit

Démarrez-le et routez vers lui. Le binaire est déjà dans votre image : il s'agit donc d'un second service et d'une règle de proxy, pas d'une reconstruction. Lancez buzz-pair-relay à côté du relais, puis ajoutez en frontal une route /pair qui lui transmet la bascule WebSocket sur le port 5000. Ne routez que /pair, et gardez le TLS et les délais de lecture au niveau du proxy : c'est ce que le sidecar suppose par construction.

Ou donnez-lui son propre nom d'hôte. Définissez BUZZ_PAIRING_RELAY_URL sur le relais et il annonce pairing_relay_url dans son document NIP-11 : les clients ignorent alors complètement l'ancienne convention et se connectent directement à un point d'accès dédié. Dans le chart Helm, ce sont pairingRelay.enabled et pairingRelay.url, qui font tourner le sidecar comme son propre Deployment et son propre Service sur le port 5000. Le chart ne crée pas d'ingress pour lui, délibérément, donc router ce nom d'hôte reste votre travail.

Ou cessez d'annoncer ce que vous ne faites pas. Si votre relais n'impose pas réellement l'appartenance, il ne devrait pas du tout annoncer NIP-43, et le client ne prend alors jamais l'ancienne branche. En amont, NIP-43 est tenu hors de la liste statique des NIP pris en charge précisément pour cette raison, et la décision est verrouillée par un test dont le commentaire dit en toutes lettres que l'annoncer sur des relais ouverts envoie les pairs en cours d'appairage vers un sidecar /pair inexistant.

Nous aussi, nous avons livré ce trou

Nos propres instances gérées faisaient tourner l'image du relais sans jamais démarrer le sidecar, alors que le binaire était dans le conteneur depuis le début. Nous l'avons découvert comme tout le monde : en scannant un code QR. Trois choses se liguent pour cacher celui-ci, et aucune ne relève de la négligence de qui que ce soit. Le sidecar écoute sur la boucle locale, donc il n'échoue jamais bruyamment. Il est livré dans l'image, donc il a l'air présent. Et le client choisit l'ancienne route sur la foi d'une déclaration plutôt que d'une vérification, donc le code QR s'affiche parfaitement jusqu'au moment où la connexion est tentée. C'est un mode de défaillance qu'il vaut mieux vérifier que supposer écarté : si vous faites tourner un relais Buzz qui impose l'appartenance, envoyez la requête unique du haut de cette page avant que quelqu'un ne scanne un code.

← Toutes les notes