Le token d’accès et qui peut joindre le relais

Un relais a un seul propriétaire et un seul token d’accès. Qui détient le token a le contrôle total du relais et, à travers ses agents, du compte utilisateur sous lequel le relais tourne. Il n’y a ni comptes utilisateur, ni rôles, ni clés par appareil. Cette page dit d’où vient le token, comment un navigateur ou un script le présente, qui peut se connecter, ce qui est joignable sans lui, et que faire s’il fuite.

Le token #

oar setup crée le token (un token aléatoire pour une nouvelle config, 43 caractères aléatoires parmi lettres, chiffres, - et _) et l’écrit dans authToken dans le fichier de config, config.json dans le dossier d’état d’OAR. Hors Windows, le relais garde ce fichier lisible par vous seul. Voir config.json et Où se trouvent les secrets.

Sans authToken dans la config, le relais crée un token aléatoire à chaque démarrage, l’écrit dans son journal et ne l’enregistre pas. Démarrez le relais avec --token <value> et ce token sert pour cette exécution seulement ; il n’est jamais enregistré, et il fait partie de la ligne de commande. Vos agents lisent le token dans config.json (voir Les agents et le token) ; utilisez donc un token qui y est enregistré si les agents doivent fonctionner.

oar url affiche l’adresse avec le token actuel, par exemple http://localhost:3333/?token=<your token>. Traitez cette adresse comme un mot de passe.

Les façons de le présenter #

Le token n’est jamais lu dans le corps d’une requête ni, depuis la 0.9.11, dans la query d’une requête. Si une requête porte à la fois un en-tête et le cookie, le relais utilise l’en-tête. Une valeur erronée n’est pas ignorée : un en-tête erroné est refusé même quand le cookie est bon. La connexion en direct (Socket.IO) lit le token dans le champ auth.token de la connexion ou dans le cookie, pas dans un en-tête ni dans sa query.

Le cookie de connexion #

Après un token valide, le relais pose un cookie nommé copilot_auth qui dure 30 jours. Cela vaut aussi pour un script qui envoie le token dans un en-tête. Il est HttpOnly, donc les scripts de la page ne peuvent pas le lire, et SameSite=Lax. Il est marqué Secure quand le relais est joint en HTTPS. Si une requête arrive avec un cookie qui ne correspond plus au token, le relais répond 401 et efface le cookie, et le navigateur affiche la boîte de connexion. Le cookie contient le token lui-même.

Se déconnecter et révoquer un appareil #

L’app n’a pas de bouton de déconnexion pour le relais, et le relais ne tient pas de liste des appareils connectés. Comme le cookie contient le token lui-même, on ne peut pas révoquer un appareil à lui seul. Sur votre propre navigateur, effacez le cookie dans les réglages du site du navigateur. Pour exclure tous les appareils, y compris un appareil perdu, changez le token (section suivante).

Renouveler le token #

oar setup --new-token

Cette commande écrit un nouveau token et redémarre le relais (dans un terminal, elle demande d’abord ; voir oar setup). Ce qui se passe :

• Navigateurs connectés. L’ancien token cesse de fonctionner une fois le relais redémarré. Le redémarrage coupe la connexion en direct, et la requête suivante de chaque navigateur échoue : le relais efface son cookie et le navigateur affiche la boîte de connexion. Reconnectez-vous avec l’adresse donnée par oar url ou avec le nouveau token.
• Jusqu’au redémarrage. Si vous refusez le redémarrage, le relais en cours continue d’accepter l’ancien token jusqu’à oar restart.
• Relais associés. Un relais qui a votre token enregistré, parce que vous avez associé les deux, reçoit Token not accepted (Token refusé). Ajoutez-y à nouveau le relais avec le nouveau token ; voir Relais distants. Retirer une association sur ce relais ne révoque pas un token que l’autre côté détient déjà ; c’est donc en renouvelant le token que vous excluez ce relais.
• relay-previous.json. Tant qu’un port ou un token modifié attend le redémarrage, oar setup garde l’ancien port et l’ancien token dans ce fichier du dossier de données (texte en clair, lisible par vous seul), pour que oar status, oar stop et oar restart trouvent encore le relais en cours. Ce n’est pas un délai de grâce : le fichier ne change rien à ce que le relais accepte, et les commandes oar le suppriment dès que le relais répond avec les nouveaux réglages. L’ancien token ne cesse de fonctionner qu’au redémarrage du relais.
• Les liens de partage et les liens d’aperçu ont leurs propres tokens et ne sont pas concernés.

Modifier authToken à la main dans le fichier fonctionne de la même façon ; oar restart l’applique.

Qui peut se connecter #

localhostOnly dans la config décide où le relais écoute :

Seuls le booléen true et le texte "true" (casse indifférente) comptent comme local. false, null, 1, "yes" et toute autre valeur ouvrent le relais au réseau ; la valeur par défaut ne s’applique que si la clé manque. oar setup écrit la clé à true ou false. Un changement demande oar restart.

oar setup, oar url et oar status lisent la clé autrement : pour eux, seul le booléen false compte comme accès LAN, et oar doctor n’affiche localhostOnly: no que pour false. Avec une valeur comme null ou "no", le relais écoute sur toutes les interfaces alors que ces commandes affichent this machine only (cette machine uniquement). Limitez la clé à true ou false. Voir config.json.

Sur un LAN, le token est le seul verrou : le relais ne vérifie pas d’où vient une requête. Avec l’accès this machine only, un téléphone ne peut pas se connecter tant que vous n’activez pas l’accès LAN ou n’utilisez pas un tunnel. localhostOnly n’a pas d’effet sur les tunnels gérés, qui se connectent vers l’extérieur depuis la machine.

Un relais placé derrière un proxy ou un tunnel sur la même machine peut rester en this machine only. Les proxys dont le relais croit les en-têtes X-Forwarded-* sont fixés par trustProxy (par défaut loopback) ; cela décide s’il traite une connexion comme HTTPS et marque le cookie Secure.

Ce qui demande le token #

Tout ce qui lit ou modifie vos conversations, fichiers, réglages ou agents demande le token. Voici les exceptions, et la liste est complète.

Il n’y a pas de point d’accès de santé ou de version sans authentification : /api/status, qu’appelle oar status, demande le token.

Les liens de partage et les liens d’aperçu sont publics par conception. Le token aléatoire du lien est leur seule protection ; fermez-les ou révoquez-les donc quand vous avez fini. Les fichiers que le relais sert sont envoyés avec une politique de sandbox, de sorte qu’un fichier HTML ou SVG servi ne peut pas exécuter de script sur l’origine du relais.

La connexion des workers ne répond qu’aux requêtes venant de la machine même du relais qu’aucun proxy ni tunnel n’a transmises ; tout le reste est refusé avec 403 avant la vérification du token. Les liens partagés passant par un tunnel ne sont pas concernés. Voir Le garde-fou des chemins du worker de session.

Les protections à la connexion #

• Pour la connexion et la connexion en direct, le relais compare les tokens en temps constant.
• Ajouté en 0.9.11 Dix tokens erronés bloquent une adresse pendant une minute. Dix tokens erronés depuis une même adresse client en une minute, dans un en-tête, le cookie, la boîte de connexion ou une poignée de main de connexion en direct, font que le relais répond 429 à cette adresse avec Retry-After jusqu’à la fin de la minute, y compris pour le bon token. La boîte de connexion indique Too many failed sign-in attempts. Try again in 42 seconds. (Trop de tentatives de connexion échouées. Réessayez dans 42 secondes.) La même valeur erronée répétée compte une seule fois, donc un onglet avec un ancien cookie ne vous bloque pas. Le relais écrit dans le journal une ligne commençant par [auth] quand il refuse une adresse.
• Les requêtes venant de la machine même du relais qu’aucun proxy ni tunnel n’a transmises ne sont jamais comptées ni bloquées, pour que les workers du relais et les outils des agents continuent de fonctionner.
• L’adresse client est celle à laquelle le relais fait confiance. Derrière un proxy sur une autre machine à laquelle le relais ne fait pas confiance, tous les clients ont l’adresse du proxy, et les tokens erronés d’un client les bloquent tous.
• Le blocage ralentit les tentatives de devinette ; il ne remplace pas un bon token. Gardez un token long et aléatoire : oar setup en génère un ; ne le remplacez pas par un mot court.
• La seule limite de débit sur les routes qui ne demandent pas de token concerne les signaux de présence des conversations partagées : 24 par tranche de 10 secondes pour chaque lien de partage et adresse client. Ajouté en 0.9.11 L’adresse client suit trustProxy, comme le blocage, de sorte qu’un client ne peut pas choisir la sienne en envoyant X-Forwarded-For.
• Le token n’est pas écrit dans le journal, sauf quand la config n’en a pas et que le relais en crée un temporaire au démarrage. oar start et oar url l’affichent dans votre terminal.

Les agents et le token #

Vos agents tournent comme processus de l’utilisateur sous lequel tourne le relais, sur la machine du relais. Ils n’ont pas d’identifiants propres : pour parler au relais, ils lisent le token du relais dans config.json et l’envoient comme le ferait le propriétaire. Le relais ne met le token ni dans l’environnement ni dans le prompt d’un agent, mais un agent tourne sous le même utilisateur du système d’exploitation ; il peut donc lire le fichier, et le token avec. Il en va de même pour tout ce qu’un agent lance. Considérez le token comme connu de chaque agent que vous lancez, et ne lancez des agents que sous un utilisateur à qui vous confiez le relais.

Le relais ne communique pas aux agents le token d’un relais associé : les agents joignent un relais associé à travers ce relais, qui ajoute le token enregistré (Relais distants). Un agent agit aussi avec les droits de l’utilisateur sous lequel tourne le relais ; donc tout ce que le propriétaire du relais peut faire sur la machine, on peut demander à un agent de le faire.

HTTP en clair sur un LAN #

Avec l’accès LAN et une adresse http://, le token et le cookie traversent le réseau sans chiffrement. Quiconque peut observer ce trafic peut lire le token. Utilisez cela sur un réseau de confiance, ou placez HTTPS devant. Le cookie n’est pas marqué Secure en HTTP en clair.

L’installation d’OAR comme app et les notifications push demandent HTTPS ou localhost ; aucune des deux ne fonctionne donc sur une adresse LAN en clair : voir Installer comme app et Notifications.

Si vous pensez que le token a fuité #

1. Lancez oar setup --new-token et laissez la commande redémarrer le relais. Tous les navigateurs sont déconnectés. Si vous refusez le redémarrage, lancez oar restart : d’ici là, l’ancien token fonctionne encore.
2. Reconnectez-vous avec l’adresse donnée par oar url.
3. Sur chaque relais que vous avez associé à celui-ci, ajoutez à nouveau ce relais avec le nouveau token (Relais distants).
4. Vérifiez où le token a été stocké : scripts, historique du shell, adresse que vous avez collée dans un chat, et copies ou sauvegardes de config.json.
5. Arrêtez ou renouvelez les liens partagés dans Settings → Sharing (Réglages → Partage) (Vos liens partagés) et fermez les aperçus que vous ne reconnaissez pas. Ceux-ci ont leurs propres tokens.
6. Si quelqu’un a pu utiliser le relais pendant qu’il était exposé, regardez ce que ses agents ont fait. Un détenteur du token peut lancer des agents qui exécutent des commandes sous l’utilisateur du relais.