# Quarel — documentation # Architecture URL : https://quarel.app/wiki/decouvrir/architecture/ Quarel repose sur trois pièces indépendantes. ## Le service d’identité Il gère les **comptes** (email, pseudo, mot de passe, double authentification), les **amis**, et transporte les **messages privés chiffrés**. Il délivre à l’application une **identité portable** : un jeton signé qui prouve « je suis `pseudo@identity.quarel.app` » auprès des serveurs communautaires. - L’instance officielle est `identity.quarel.app`. Le logiciel est libre : une association, une école ou une famille peut [héberger le sien](/wiki/heberger/service-identite/). - **Chaque service d’identité est une bulle** : amis, messages privés et appels ne relient que des comptes du même service. - Il héberge aussi le **relais d’appels** de ses utilisateurs, utilisé seulement quand deux personnes ne peuvent pas se joindre directement. ## Les serveurs communautaires Chaque serveur (l’équivalent d’un « serveur Discord ») tourne **chez son hébergeur**, isolé de tous les autres : ses salons, ses rôles, ses règles, sa modération, ses fichiers. Il intègre un serveur vocal (LiveKit) pour les salons vocaux. - Il **accepte les comptes** des services d’identité qu’il choisit (par défaut `identity.quarel.app`) et vérifie les identités portables sans contacter le service. - Un membre est reconnu par son identifiant stable chez son service (pas par son pseudo, qui peut changer) : les bannissements tiennent même après un changement de pseudo. - Les **bannissements sont propres à chaque serveur**. Le service d’identité ne peut que désactiver un compte (sur décision de justice), jamais bannir d’un serveur. - Les salons des serveurs **ne sont pas chiffrés de bout en bout** : l’hébergeur peut les lire, comme sur tout forum ou chat de groupe. Choisissez des serveurs dont vous connaissez l’hébergeur. ## L’application Application de bureau (Windows, Linux) et version web, avec la même interface. Elle : - garde vos **clés de chiffrement** sur votre appareil ; - chiffre et déchiffre les messages privés et les fichiers qu’ils contiennent ; - **vérifie chaque serveur** : un serveur a une clé d’identité, et son certificat HTTPS est lié à cette clé. L’application le vérifie sans autorité de certification, même sans nom de domaine ; - se connecte directement à chaque serveur communautaire. ## Qui voit quoi ? | | Service d’identité | Serveur communautaire | Relais d’appels | |---|---|---|---| | Votre email | oui | non | non | | Vos messages privés | **non** (chiffrés) | — | — | | Messages des salons | — | oui (son hébergeur) | — | | Les serveurs que vous fréquentez | non ¹ | le sien | — | | Vos appels | non | — | flux chiffré, illisible | | Vos amis | oui | non | non | ¹ Sauf si le service est en mode « serveurs approuvés » : il voit alors les connexions, sans les conserver. --- # Nouveautés URL : https://quarel.app/wiki/decouvrir/nouveautes/ Quarel est en **version de test** : les versions `0.x` peuvent encore changer en profondeur. Le même journal est dans le dépôt ([CHANGELOG.md](https://github.com/anlekg/quarel/blob/main/CHANGELOG.md)) et sur la [page des versions GitHub](https://github.com/anlekg/quarel/releases). ## 0.5.0 — 2026-09-27 Le bloc cosmétique : personnalisez l'application, vos profils et vos serveurs. Et un outil pour venir de Discord. > **À mettre à jour ensemble.** Serveurs communautaires (schéma 14) et services d'identité (schéma 14) d'abord, application ensuite. ### Personnalisation - **Mon CSS** (Paramètres › Apparence) : votre propre CSS dans l'application, sur cet appareil, avec un **mode sans échec** (Ctrl + Maj + 0) si un CSS la rend inutilisable. - **Thème d'un serveur** (Paramètres du serveur › Apparence) : couleurs, dégradé, image de fond, police et CSS, sur les salons, les messages, les membres et le vocal du serveur. - Le thème d'un serveur **passe avant votre CSS** par défaut ; on peut inverser, ignorer le thème d'un serveur, ou ceux de tout le monde. - **Cartes de profil** : un clic sur une personne montre sa bannière, son image, ses rôles et sa présentation, dans son thème. - **Profil par serveur** : surnom, présentation, image, bannière et thème propres à un serveur (menu du serveur › Mon profil sur ce serveur) ; la modération peut le réinitialiser. - **Sécurité** : le CSS des serveurs et des cartes est filtré par votre application (rien n'est chargé depuis un autre site : votre adresse IP reste privée ; pas de faux texte ni de faux boutons ; rien hors de sa zone). ### Outils - **Migrer depuis Discord** : `tools/discord-import` recrée sur un serveur Quarel les rôles (permissions comprises), catégories, salons, droits des salons et emojis d'un serveur Discord, avec un rapport de ce qui n'a pas d'équivalent. Essai sans rien modifier, relançable sans doublon. ## 0.4.5 — 2026-09-27 Corrections du deuxième audit (sécurité et vie privée) et demandes de test. Première mise à jour **invisible** de l'application de bureau : depuis la 0.4.0, « Redémarrer » installe sans fenêtre et rouvre Quarel. > **À mettre à jour ensemble.** Serveurs communautaires (schéma 13) et services d'identité (schéma 13) d'abord, application ensuite : la connexion par clé d'accès et l'export des données demandent les deux côtés à jour. ### Corrections demandées - Toutes les confirmations (supprimer un salon, expulser, quitter un groupe…) s'ouvrent **dans l'application** : sous Windows, après une boîte du système, l'application de bureau ne prenait plus le clavier (impossible d'écrire après avoir supprimé un salon). - Les **fils** et les **posts de forum** se renomment et se suppriment (roue dentée, clic droit, en-tête du fil). - **Inviter ses amis** depuis « Inviter sur… » : une invitation personnelle envoyée en message privé ; un lien d'invitation dans un message s'affiche en carte **Rejoindre** / **Ouvrir**. - Rejoindre un second serveur auto-signé à la même adresse coupait le premier : c'est maintenant refusé avec une explication. ### Sécurité - **Webhooks** : nouvelle permission « Gérer les webhooks », et il faut pouvoir écrire dans le salon pour en créer un (un webhook permettait d'écrire dans un salon d'annonces sans en avoir le droit). Les rôles qui géraient les salons la reçoivent. - **Clés d'accès** : la page de connexion indique l'appareil, l'adresse et l'heure, puis un **code à taper dans l'application** ; email à l'ajout et au retrait d'une clé (le retrait demande le mot de passe). - **Fils et posts** : 5 créations par 10 minutes et par membre ; **archivés** après une semaine sans message (hors de la liste des salons, toujours lisibles ; un message les rouvre). - **Notifications web** envoyées seulement aux services des navigateurs. - **Modération automatique** : plus trompée par les caractères invisibles ni les lettres imitées (cyrillique, grec, pleine chasse) ; s'applique aussi aux noms de fils et aux surnoms. ### Vie privée - **Qui voit votre adresse IP** (Paramètres › Voix et vidéo) : par défaut, seulement vos amis ; avec les autres membres d'un groupe, appels par le relais et fichiers par la copie chiffrée. - **Messages éphémères** jamais sauvegardés ni transmis à un nouvel appareil ; notifications sans leur texte ni celui des divulgâcheurs ; pas d'aperçu pour un lien caché. - **Compte supprimé** : son nom devient « Ancien compte » sur les serveurs rejoints. - **Télécharger mes données** (Paramètres › Confidentialité, et « Mes données sur ce serveur » dans le menu d'un serveur). ## 0.4.0 — 2026-09-27 La plus grosse mise à jour depuis le début : toute la liste « plus tard » (P2) du plan, et du confort pour l'application de bureau. > **À mettre à jour ensemble.** Les nouveautés marquées ★ ne marchent qu'entre applications 0.4.0 (l'application se met à jour seule ; la version web est toujours à jour). Serveurs communautaires et services d'identité auto-hébergés : mettez-les à jour aussi (installateur Windows plus récent, ou nouvelle image Docker) — leurs bases sont migrées automatiquement, avec une copie de sécurité. ### Appels et vocal - ★ **Partage d'écran pendant un appel** entre amis (un écran ou une fenêtre ; sous Windows avec le son du système), les deux personnes en même temps si elles veulent. - ★ **Appels de groupe** dans les groupes de messages privés, jusqu'à 6 personnes, en direct entre vous (aucun serveur ne voit le son ni la vidéo) : sonnerie, « Rejoindre l'appel », caméra et partage d'écran. - **Salons « scène »** : un salon vocal où le public écoute et **lève la main** ; la modération invite à parler. - **Ping** : barres de signal à gauche de « Vocal connecté », dans la barre d'appel et sur chaque participant·e (valeur au survol). - **Volume par personne** (jusqu'à 200 %) et « Rendre muet pour moi », au clic droit. ### Messages privés et amis - **Messages éphémères** : durée de vie réglable par conversation (5 min à 7 jours), par n'importe quel membre ; chaque appareil efface lui-même messages et fichiers. - **Qui peut vous demander en ami** : tout le monde, les amis de vos amis et membres de vos groupes, ou personne. ### Serveurs communautaires - **Modération automatique** : mots interdits, liens, trop de mentions, messages répétés, exclusion automatique ; chaque refus est journalisé (sans le texte). - **Emojis personnalisés** (100 par serveur), dans les messages (`:nom:`) et les réactions. - **Salons forum** : des posts avec un titre, chacun sa discussion, les plus actifs en tête. - **Webhooks entrants** : une adresse secrète pour publier dans un salon (supervision, sauvegardes, formulaires…). - **Commandes slash** pour les bots (`/ping`, `/echo` dans le bot d'exemple), avec réponses publiques ou visibles par vous seul·e. - **Mise en forme** : titres, listes, citations, barré, souligné, divulgâcheurs `||…||`, langage des blocs de code. ### Application - **Clic droit** partout : sur une personne (volume, message, ami, modération selon vos droits), un message (réagir, répondre, épingler, copier…), un salon (marquer comme lu, modifier). - **Zone de notification** (Windows) : la croix garde Quarel près de l'horloge ; messages et appels continuent d'arriver. - **Mises à jour invisibles** : « Redémarrer » installe sans fenêtre et rouvre Quarel (à partir de la prochaine mise à jour). - **Vérification d'intégrité** (Windows) : l'application refuse de démarrer si ses fichiers ont été modifiés après l'installation. - **Version web installée sur téléphone** : notifications même application fermée, par un simple réveil **sans contenu ni expéditeur** (messages privés et appels). ### Compte et sécurité - **Clés d'accès** (Windows Hello, clé de sécurité, téléphone) en double authentification, à côté du code à 6 chiffres. - Les connexions des applications antérieures à 0.3.0 sont refusées (ancienne preuve de connexion). ### Corrections - Un salon qui venait d'être créé n'avait aucun droit dans l'application avant une reconnexion (pas de zone de saisie). ## 0.3.0 — 2026-09-26 Audit de sécurité appliqué : preuve de connexion liée au serveur réellement contacté, pages d'administration en HTTPS, blocage anti-force-brute revu, sessions inactives fermées après 90 jours, quotas des boîtes aux lettres et des fichiers, codes de sécurité entre contacts, membres de groupe confirmés, transfert de propriété d'un serveur. ## 0.2.0 — 2026-09-26 Première version publique de test : application de bureau (Windows, Linux) et version web, serveurs communautaires et service d'identité (Docker, installateurs Windows), messages privés et appels chiffrés de bout en bout. --- # Qu’est-ce que Quarel ? URL : https://quarel.app/wiki/decouvrir/presentation/ Quarel est une **alternative libre à Discord** : salons textuels et vocaux, rôles et modération, amis, messages privés et appels. La différence : **aucune plateforme centrale ne détient les communautés**. Chaque serveur tourne chez la personne qui l’héberge (un PC, un mini-serveur, un NAS) et ses données y restent. :::caution[Version de test] Quarel est en phase de test. Tout fonctionne de bout en bout, mais des changements sont encore possibles et des bugs attendus. Voir [Statut du projet](/wiki/decouvrir/statut/). ::: ## Ce que vous pouvez faire - **Rejoindre des serveurs communautaires** avec un seul compte, par un lien d’invitation. - **Discuter** : messages avec mise en forme, réponses, réactions, fichiers, fils, épingles, recherche, notifications réglables. - **Parler et vous montrer** dans les salons vocaux : micro, caméra, partage d’écran avec le son. - **Écrire en privé** à vos amis, seul·e à seul·e ou en groupe (jusqu’à 10), avec un **chiffrement de bout en bout** : même le service qui transporte les messages ne peut pas les lire. - **Appeler vos amis** directement, en pair à pair, avec la vidéo. - **Héberger votre propre serveur** en une commande, et même votre propre service de comptes. ## Les principes - **Auto-hébergement d’abord.** Un serveur tient dans une image Docker, avec une base de données embarquée : aucun service externe à installer. Il ouvre lui-même les ports de la box (UPnP) et se règle depuis une page web. - **Pas de fédération.** Chaque serveur est une île : il ne parle pas aux autres serveurs. Seuls les comptes circulent, grâce à une **identité portable** signée par votre service d’identité. - **Vie privée.** Les messages privés et les appels sont chiffrés de bout en bout. Un service d’identité réglé en mode ouvert ne sait pas quels serveurs vous fréquentez. Pas de publicité, pas de pistage. - **Logiciel libre.** Licence Apache-2.0, code sur [GitHub](https://github.com/anlekg/quarel). ## Par où commencer ? - Pour utiliser Quarel : [Installer l’application](/wiki/utiliser/installer/), puis [Premiers pas](/wiki/utiliser/premiers-pas/). - Pour héberger une communauté : [Héberger un serveur communautaire](/wiki/heberger/serveur-communautaire/). - Pour comprendre la technique : [Architecture](/wiki/decouvrir/architecture/) et [Sécurité et chiffrement](/wiki/decouvrir/securite/). --- # Sécurité et chiffrement URL : https://quarel.app/wiki/decouvrir/securite/ Quarel n’invente pas sa cryptographie : il s’appuie sur des bibliothèques éprouvées (Olm/Megolm via **vodozemac**, la bibliothèque de Matrix ; Ed25519, X25519, XChaCha20-Poly1305, HPKE). ## Votre compte - Mots de passe hachés avec **argon2id** ; double authentification **TOTP** (application d’authentification) avec 10 codes de secours. - Blocage automatique après des échecs répétés (par compte et par adresse IP), sans révéler si un compte existe. Un appareil que vous avez déjà utilisé pour vous connecter n'est pas bloqué par des échecs venus d'ailleurs : personne ne peut vous tenir dehors en tapant de faux mots de passe. - L'inscription ne révèle pas non plus si une adresse email a déjà un compte (la personne concernée est prévenue par email). - Mot de passe oublié : un code par email, **et la double authentification reste exigée**. Toutes les sessions sont alors fermées. - **Clés d’accès** (second facteur) : la page de votre service qui vérifie la clé indique quel appareil se connecte, d’où et à quelle heure ; ensuite elle affiche un **code à taper dans l’application**. Quelqu’un qui connaîtrait votre mot de passe et vous enverrait le lien de cette page n’obtiendrait donc rien en vous faisant toucher votre clé. Ajouter ou retirer une clé vous est signalé par email (le retrait demande le mot de passe). - **Vos données** : Paramètres › Confidentialité › « Télécharger mes données » (ce que votre service garde sur vous, et l’historique de vos messages privés gardé sur l’appareil) ; pour un serveur : menu du serveur › « Mes données sur ce serveur ». Si vous supprimez votre compte, les serveurs que vous aviez rejoints remplacent votre nom par « Ancien compte ». - Une session inutilisée pendant 90 jours se termine. Quand une session se termine (déconnexion, appareil retiré, changement de mot de passe), les serveurs communautaires en sont informés et ferment celles de cet appareil sous 10 minutes. ## Messages privés et fichiers - **Chiffrés de bout en bout** avec Olm (entre appareils) et Megolm (par conversation), le protocole de Matrix. Le service d’identité ne voit que des données illisibles et les efface dès que tous les appareils destinataires les ont reçues. - **Chaque appareil a ses clés.** Un nouvel appareil doit être **validé** par un appareil déjà validé, après comparaison d’un code affiché sur les deux écrans. Sans cela, il ne reçoit rien. - **Phrase de récupération** : 12 mots (liste BIP-39 française) qui chiffrent une sauvegarde de vos clés et de votre historique, stockée sur le service sous forme illisible. Si vous perdez tous vos appareils, elle seule permet de tout retrouver : notez-la sur papier. - Les **fichiers** envoyés en privé sont chiffrés sur votre appareil, transmis de préférence directement aux appareils en ligne (pair à pair), sinon déposés chiffrés sur le service, puis effacés dès réception (7 jours au plus). - Le contact avec chaque personne est **épinglé** au premier échange : si ses clés changent, l’application refuse d’envoyer et vous prévient. Un **code de sécurité**, le même des deux côtés, permet de vérifier hors ligne que personne (pas même votre service d’identité) n’a substitué ses clés. - Dans un **groupe**, l’application ne chiffre que pour les membres annoncés par un membre (chiffré) : un service compromis ne peut pas glisser quelqu’un dans une conversation pour lire les messages suivants. - Les **messages éphémères** ne quittent jamais les appareils qui les ont reçus : ni la sauvegarde chiffrée, ni l’historique envoyé à un nouvel appareil ne les contiennent, et les notifications n’en montrent pas le texte. ## Appels Les appels entre amis sont **pair à pair** et chiffrés (DTLS-SRTP). La mise en relation elle-même voyage dans des messages chiffrés : le service ne voit ni vos adresses IP ni les paramètres de l’appel. Si aucun chemin direct n’existe, le relais de votre service d’identité transmet le flux sans pouvoir le lire. Une connexion directe montre votre adresse IP à l’autre appareil. Par défaut (**« Mes amis seulement »**, Paramètres › Voix et vidéo), seuls vos amis la voient : avec les membres d’un groupe qui ne sont pas vos amis, les appels passent par le relais et les fichiers par la copie chiffrée du service. Vous pouvez aussi toujours passer par le relais, ou ne jamais l’utiliser. Les **notifications** de l’application web installée sont des réveils vides envoyés par le service de notification de votre navigateur (Google, Mozilla, Apple, Microsoft) : ni contenu, ni expéditeur. ## Connexion aux serveurs communautaires - **Identité portable** : un jeton signé par votre service, lié à la clé de votre appareil. Chaque connexion prouve la possession de cette clé en signant un défi à usage unique : un jeton volé seul ne suffit pas. - **Certificat lié à l’identité du serveur** : les liens d’invitation contiennent l’identifiant du serveur (`sid`). L’application vérifie pendant la connexion HTTPS que le serveur détient la clé correspondante, sans autorité de certification. Un intermédiaire ne peut pas se faire passer pour lui. Une adresse qui a prouvé ce lien doit continuer à le prouver : un certificat ordinaire y est ensuite refusé. - **Pas de connexion relayée** : la preuve signée à chaque connexion nomme aussi l’adresse contactée et la façon dont elle a été vérifiée. Un serveur malveillant (même muni d’un certificat reconnu) qui transmettrait votre connexion à un autre serveur en se faisant passer pour lui est refusé par ce dernier. - Les serveurs communautaires ne reçoivent jamais votre email. ## L’application - Secrets chiffrés par le trousseau du système (bureau) ou par une clé non exportable du navigateur (version web). - Interface isolée (Electron en bac à sable, politique de sécurité du contenu stricte), liens externes ouverts dans votre navigateur. - **Mises à jour signées** : chaque version est signée par la clé de publication de Quarel ; l’application refuse toute mise à jour qui ne l’est pas, même venant de notre propre site. ## Limites à connaître - Les **salons des serveurs** ne sont pas chiffrés de bout en bout : l’hébergeur du serveur peut les lire. - Pour le vocal des salons, votre adresse IP est visible du serveur vocal de ce serveur. - Les installateurs ne sont pas encore signés par un certificat d’éditeur (avertissement de Windows). - La **version web** reçoit son code de `app.quarel.app` à chaque ouverture : quiconque prendrait le contrôle de ce site pourrait y glisser du code capable de lire vos clés et vos messages privés dans le navigateur. C’est une limite de tout chiffrement de bout en bout dans une page web. L’application de bureau, elle, n’exécute que du code installé sur votre machine et ne se met à jour qu’avec des versions signées : préférez-la pour les conversations sensibles. Une faille ? Merci de la signaler en privé plutôt que dans un ticket public : voir [Contribuer](/wiki/developper/contribuer/). --- # Statut du projet URL : https://quarel.app/wiki/decouvrir/statut/ :::caution[Version de test] Quarel est en **phase de test**. Les fonctions ci-dessous marchent de bout en bout et sont couvertes par des tests automatiques, mais le projet n’a pas encore été éprouvé à grande échelle. Gardez des sauvegardes de vos serveurs. ::: ## Disponible - **Serveurs communautaires** : salons textuels, vocaux, catégories, annonces, fils ; rôles et droits par salon ; modération (exclusions temporaires, expulsions, bannissements, suppressions en masse, journal, modération automatique) ; règles à accepter ; vérification par SMS ; bots ; recherche ; épingles ; réactions ; fichiers ; aperçus de liens ; notifications réglables. - **Vocal et vidéo** dans les salons : micro, caméra, partage d’écran, modération du micro et du son, déplacement entre salons. - **Amis, messages privés et groupes chiffrés** de bout en bout, fichiers chiffrés, messages éphémères, validation des appareils, phrase de récupération ; choix de qui peut vous demander en ami. - **Appels** entre amis en pair à pair, avec vidéo, partage d’écran et relais de secours ; appels de groupe jusqu’à 6 personnes. - **Application de bureau** Windows et Linux (mises à jour automatiques signées) et **version web** installable, utilisable sur téléphone. - **Hébergement** : Docker, installateurs Windows des serveurs, page d’administration, sauvegardes et restauration, UPnP. ## Service officiel - Comptes : `identity.quarel.app`. Pendant la phase de test, **l’inscription se fait sur invitation** (un code d’invitation est demandé) et seuls les **serveurs communautaires approuvés** acceptent ces comptes : un nouveau serveur demande l’accès depuis sa page d’administration. - Application web : [app.quarel.app](https://app.quarel.app). - Un serveur de test tourne sur `test.quarel.app`. ## À venir - Traduction du site et de l’application en anglais. - Signature des installateurs par un certificat d’éditeur. - Application macOS, applications mobiles natives. - Vous avez une idée ou un bug ? [Ouvrez un ticket sur GitHub](https://github.com/anlekg/quarel/issues). --- # API des serveurs communautaires URL : https://quarel.app/wiki/developper/api/ Cette page décrit l'API d'un **serveur communautaire** Quarel, telle que l'utilisent les clients et les **bots**. Elle est stable dans sa version `v1` : des champs et des routes peuvent s'ajouter, rien d'existant n'est retiré ni renommé sans passer à `v2`. Un client doit donc ignorer les champs et les événements qu'il ne connaît pas. Un exemple complet de bot (~150 lignes de Go) se trouve dans [`examples/pingbot`](https://github.com/anlekg/quarel/blob/main/examples/pingbot/main.go). ## 1. Principes - **Adresse** : chaque serveur est auto-hébergé, par exemple `https://mon-serveur.fr:8090`. Toutes les routes sont sous `/v1/`. - **HTTPS** : un serveur a soit un certificat d'une autorité (Let's Encrypt…), soit un **certificat auto-signé lié à son identité**. Dans ce second cas, le certificat contient une preuve signée par la clé du serveur ; le client connaît l'identifiant du serveur (`server_id`, 26 caractères, donné par le lien d'invitation ou `quarelctl bot-create`) et vérifie cette preuve pendant la poignée de main TLS. En Go : `tlsbind.NewVerifier(hôte, serverID).Config()` (paquet `github.com/anlekg/quarel/pkg/tlsbind`) : il accepte un certificat d'autorité valable pour l'hôte, ou le certificat lié à ce serveur — et plus jamais un certificat ordinaire une fois le lien vérifié. Ne désactivez jamais simplement la vérification du certificat. - **Format** : JSON en UTF-8 ; corps de requête de 64 Ko au plus (sauf envoi de fichiers) ; champs inconnus refusés (`400 bad_request`). - **Dates** : RFC 3339 en UTC (`2026-09-24T09:30:00Z`). - **Identifiants** : membres, fichiers : chaînes de 26 caractères ; salons, messages, rôles, entrées du journal : entiers croissants. - **Permissions** : toujours échangées par **nom** (voir §6). - **Erreurs** : statut HTTP + `{"error": {"code": "missing_permissions", "message": "…"}}`. Le **code est stable** et fait foi ; le message est indicatif (en anglais). - **Limites de débit** : dépassement → `429 rate_limited` avec l'en-tête `Retry-After` (secondes). Par défaut : 600 requêtes/min par adresse IP, 10 messages par 10 s et 10 fichiers par minute par membre, 1 « en train d'écrire » par 3 s et par salon. L'hébergeur peut les modifier. ## 2. Authentification Chaque requête porte `Authorization: Bearer `. ### Bots Un gestionnaire du serveur (permission `manage_server`) crée le bot : `POST /v1/bots {"name": "Mon bot"}` (ou `quarelctl bot-create`). La réponse contient le **jeton** (`qb_…`), affiché une seule fois : conservez-le comme un mot de passe. Il n'expire pas ; `POST /v1/bots/{id}/token` le remplace (l'ancien cesse immédiatement de fonctionner et ses connexions temps réel sont fermées). Un bot est un membre comme les autres (`"bot": true`) : il reçoit ses droits par des **rôles** (`PUT /v1/members/{id}/roles/{role}`), sans compte sur un service d'identité. Il n'est pas concerné par l'écran de règles ni par la vérification du téléphone. ### Membres (clients) Les personnes se connectent avec leur identité portable : `POST /v1/auth/challenge` → `{server_id, nonce}`, puis `POST /v1/auth/login {identity_token, nonce, proof, host, tls, invite?}` → `{session_token, expires_at, member, server, joined}`. La preuve (`idtoken.SignProofV2`) est la signature, par la clé de l'appareil, de `quarel-auth-v2␀␀␀␀` : `host` est le nom contacté (minuscules, sans port ni crochets), `tls` vaut `binding` (certificat lié à l'identité du serveur, vérifié à chaque connexion) ou `authority` (certificat ordinaire : le serveur refuse alors, par `403 wrong_host`, un nom qui n'est pas le sien). Un serveur malveillant ne peut donc pas relayer la connexion d'une personne vers celui qu'il prétend être. La session expire avec le jeton d'identité (12 h par défaut) ; le client se reconnecte alors. Ce processus est décrit dans [Sécurité et chiffrement](/wiki/decouvrir/securite/) ; un bot n'en a pas besoin. Une connexion sans `host` ni `tls` (application antérieure à 0.3.0) est refusée : `426 client_outdated`. ## 3. Temps réel (`GET /v1/gateway`, WebSocket) 1. Ouvrir une connexion WebSocket (`wss://…/v1/gateway`). 2. Envoyer en premier message, dans les 10 s : `{"op": "auth", "token": ""}`. 3. Recevoir `{"t": "READY", "d": {…}}` : l'état initial. 4. Recevoir ensuite des événements `{"t": "", "d": {…}}`. La connexion est en lecture seule : **toutes les actions passent par l'API REST**. Le serveur envoie un ping WebSocket toutes les 30 s. Un événement peut répéter un état déjà connu : appliquez-les de façon idempotente. **READY** : `{member, server, roles, members, channels, voice_states, permissions: {server: [...], channels: {id: [...]}}, restriction, read_states, notification_settings}`. Seuls les salons visibles par vous sont inclus. `restriction` vaut `""`, ou la raison pour laquelle vous êtes en lecture seule (`timed_out`, `rules_not_accepted`, `phone_not_verified`). | Événement | Contenu | Quand | |---|---|---| | `MESSAGE_CREATE`, `MESSAGE_UPDATE` | message | Message écrit, modifié, épinglé, aperçu de lien ajouté, fil créé | | `MESSAGE_DELETE` | `{id, channel_id}` | Message supprimé | | `MESSAGE_DELETE_BULK` | `{channel_id, ids}` | Suppression en masse (modération) | | `REACTION_ADD`, `REACTION_REMOVE` | `{channel_id, message_id, emoji, member_id}` | | | `TYPING_START` | `{channel_id, member_id, at}` | À afficher ~8 s | | `CHANNEL_CREATE`, `CHANNEL_UPDATE` | salon | | | `CHANNEL_DELETE` | `{id}` | | | `CHANNELS_SYNC` | `{channels, permissions, voice_states, restriction}` | Vos droits ont changé : remplace votre liste de salons | | `MEMBER_JOIN`, `MEMBER_UPDATE` | membre | Arrivée, surnom, rôles, exclusion temporaire… | | `MEMBER_LEAVE` | `{id, reason: left\|kicked\|banned}` | | | `ROLES_UPDATE` | liste complète des rôles | | | `ROLE_DELETE` | `{id}` | | | `SERVER_UPDATE` | infos du serveur | | | `VOICE_STATE_UPDATE` | état vocal (`channel_id: null` = départ) | | | `VOICE_MOVE` | `{channel_id, from_channel_id}` | La modération vous déplace : rejoignez ce salon | | `READ_STATE_UPDATE` | état de lecture | Vos autres connexions ont lu un salon | | `NOTIFICATION_SETTINGS_UPDATE` | liste des réglages | | | `THEME_UPDATE` | `{theme, background_v}` | Le thème du serveur a changé (aussi dans READY : `theme`) | Les événements d'un salon ne sont envoyés qu'à ceux qui le voient. **Fermetures** : `4001` jeton invalide ou expiré (ne pas se reconnecter avec le même jeton) ; `1008` membre parti, client trop lent (plus de 256 événements en attente) ou arrêt du serveur. En cas de coupure, reconnectez-vous avec un délai croissant : le nouveau READY redonne l'état complet. ## 4. Objets **Membre** : `{id, handle, issuer, subject, nickname?, display_name, owner, roles: [ids], joined_at, bot, timeout_until, rules_accepted, phone_verified}`. L'identité stable d'une personne est `(issuer, subject)` ; `handle` (`pseudo@service`) peut changer. Profil public et avatar : `GET https:///v1/users//profile` sur son service Identity (sans session) → `{handle, pseudo, bio, avatar_url}` (`avatar_url` relative à ce service). Les bots n'ont pas de profil Identity. `timeout_until` : lecture seule jusqu'à cette date si elle est future. **Profil sur ce serveur** : `profile_v`, `avatar_v`, `banner_v` (versions, absentes = rien) ; présentation et thème par `GET /v1/members/{id}/profile`, images par `GET /v1/members/{id}/avatar` et `/banner` (avec le jeton). **Thème** (serveur, profils) : `{colors?: {bg, bg_1, bg_2, bg_3, line, text, text_2, text_3, accent, accent_ink, accent_text : "#RRGGBB" ou "#RRGGBBAA"}, gradient?: {angle, stops: [2 à 4 couleurs]}, font?: manrope|space-grotesk|system|serif|mono, css?}` (16 Ko de CSS au plus, sans `url(`, `@import`, `\` ni `<` ; `{}` le retire). Chaque application filtre encore le CSS et l'enferme dans sa zone. **Salon** : `{id, type, name, topic, parent_id, position, thread_starter?, overrides}`. Types : `text`, `voice`, `category`, `announcement` (écrire exige aussi `manage_messages`), `thread` (fil : `parent_id` = salon textuel, mêmes droits que lui). La liste est plate, triée par `(position, id)` ; l'arbre se reconstruit avec `parent_id`. **Message** : `{id, channel_id, author_id, content, mentions: [member ids], mention_roles, mention_everyone, reply_to, referenced?: {id, author_id, content}, attachments, embeds, reactions: [{emoji, count, me}], pinned_at, thread_id, created_at, edited_at}`. Contenu : 0 à 4000 caractères (vide seulement avec un fichier). Mentions dans le texte : `<@member_id>`, `<@&role_id>`, `@everyone`. **Fichier** : `{id, filename, content_type, size, url}` ; `url` est relative au serveur et exige le jeton. **Rôle** : `{id, name, color, position, permissions, mentionable, hoist}`. `@everyone` a l'id 1 et la position 0. ## 5. Routes REST Légende : 🔑 = permission requise. ### Serveur | | | | |---|---|---| | `GET /v1/server` | public | `{id, name, access, member_count, rules, require_phone, phone_verification}` | | `PATCH /v1/server` | 🔑 `manage_server` | `{name?, access?: private\|public, rules?, require_phone?}` | | `GET /v1/server/theme` | | `{theme, background_v}` | | `PUT /v1/server/theme` | 🔑 `manage_server` | `{theme}` | | `GET/PUT/DELETE /v1/server/theme/background` | — / 🔑 `manage_server` | Image de fond (corps = image PNG, JPEG, GIF ou WebP, 4 Mo) | ### Membres | | | | |---|---|---| | `GET /v1/members` | | Membres présents | | `GET/PATCH/DELETE /v1/members/@me` | | Soi / `{nickname?, bio?, theme?}` (champ absent : inchangé) / quitter | | `PUT/DELETE /v1/members/@me/avatar`, `…/banner` | | Mon image (1 Mo) et ma bannière (2 Mo) sur ce serveur | | `GET /v1/members/{id}/profile`, `…/avatar`, `…/banner` | | Profil d'un membre sur ce serveur | | `DELETE /v1/members/{id}/profile` | 🔑 `moderate_members` | `{reason?}` : retire son profil sur ce serveur | | `GET /v1/members/@me/permissions` | | `{server, channels}` | | `POST /v1/members/@me/accept-rules` | | Accepter les règles | | `POST /v1/members/@me/phone` | | `{phone}` (format international) → code par SMS | | `POST /v1/members/@me/phone/verify` | | `{phone, code}` | | `PUT/DELETE /v1/members/{id}/roles/{role}` | 🔑 `manage_roles` | Rôle strictement sous le vôtre | ### Rôles `GET /v1/roles` (du plus haut au plus bas) ; `POST /v1/roles {name, color?, permissions?, mentionable?, hoist?}` ; `PATCH /v1/roles/{id} {…, position?}` ; `DELETE /v1/roles/{id}` — 🔑 `manage_roles`, sur des rôles sous le vôtre, en n'accordant que des permissions que vous avez. ### Salons | | | | |---|---|---| | `GET /v1/channels` | | Salons visibles (sans les fils archivés) | | `GET /v1/channels/{id}` | 🔑 `view_channel` | Un salon, y compris un fil archivé (`archived_at`) | | `POST /v1/channels` | 🔑 `manage_channels` | `{type, name, topic?, parent_id?, position?}` | | `PATCH/DELETE /v1/channels/{id}` | 🔑 `manage_channels` | | | `PUT/DELETE /v1/channels/{id}/overrides/{role\|member}/{id}` | 🔑 `manage_roles` | `{allow: [...], deny: [...]}` | ### Messages | | | | |---|---|---| | `GET /v1/channels/{id}/messages` | 🔑 `view_channel` | `?limit=` (≤ 100) `&before=` ou `&after=` ; ordre chronologique | | `POST /v1/channels/{id}/messages` | 🔑 `send_messages` | `{content, reply_to?, mention_reply?, attachments?: [ids]}` | | `PATCH /v1/channels/{id}/messages/{mid}` | auteur | `{content}` | | `DELETE /v1/channels/{id}/messages/{mid}` | auteur ou 🔑 `manage_messages` | | | `POST /v1/channels/{id}/messages/bulk-delete` | 🔑 `manage_messages` | `{ids (≤ 100), reason?}` → `{deleted}` | | `POST /v1/channels/{id}/attachments` | 🔑 `attach_files` | multipart, champ `file` → fichier, à citer ensuite dans `attachments` | | `GET /v1/attachments/{id}/{nom}` | 🔑 `view_channel` | Téléchargement | | `PUT/DELETE /v1/channels/{id}/messages/{mid}/reactions/{emoji}` | 🔑 `add_reactions` | Emoji encodé dans l'URL | | `DELETE …/reactions/{emoji}/{member}` | 🔑 `manage_messages` | | | `GET /v1/channels/{id}/pins` ; `PUT/DELETE /v1/channels/{id}/pins/{mid}` | 🔑 `manage_messages` pour modifier | | | `POST /v1/channels/{id}/messages/{mid}/threads` | 🔑 `send_messages` | `{name?}` → salon `thread` (5 fils ou posts par 10 min et par membre, sauf `manage_channels` ; sans message pendant 7 jours, un fil est archivé : `CHANNEL_UPDATE` avec `archived_at`, absent de READY ; un message le rouvre : `CHANNEL_CREATE`) | | `POST /v1/channels/{id}/typing` | 🔑 `send_messages` | | | `POST /v1/channels/{id}/ack` | | `{message_id?}` : marquer lu | | `GET /v1/read-states` | | Non-lus et mentions par salon | | `GET /v1/notification-settings` ; `PUT /v1/notification-settings/{salon\|0}` | | `{level: default\|all\|mentions\|none, mute_for?: secondes, -1 = toujours}` | | `GET /v1/search` | | `?q=&channel_id=&author_id=&before=&limit=` (≤ 50) | | `GET /v1/members/@me/export` | | Vos données sur ce serveur : profil, rôles, réglages, réactions, fichiers et tous vos messages (JSON, 3 par heure) | ### Modération | | | | |---|---|---| | `POST /v1/members/{id}/kick` | 🔑 `kick_members` | `{reason?}` | | `GET /v1/bans` ; `PUT /v1/bans/{id}` ; `DELETE /v1/bans/{id}` | 🔑 `ban_members` | PUT : `{reason?, delete_messages?: secondes, -1 = tout}` | | `PUT /v1/members/{id}/timeout` ; `DELETE …` | 🔑 `moderate_members` | `{duration: secondes (≤ 28 j), reason?}` | | `POST /v1/members/{id}/purge` | 🔑 `manage_messages` | `{window: secondes ou -1, channel_id?, reason?}` → `{deleted}` | | `POST /v1/members/{id}/transfer-ownership` | propriétaire | Transmet le serveur à ce membre (une personne, pas un bot) ; l'ancien propriétaire reste membre | | `GET /v1/server/automod` ; `PUT …` | 🔑 `manage_server` | `{words: [...], block_links, max_mentions, duplicates, timeout: secondes}` : modération automatique. Message refusé : `403 automod_word`, `automod_link`, `automod_mentions`, `automod_duplicate` (sauf pour qui a `manage_messages` dans le salon) | | `GET /v1/audit-log` | 🔑 `view_audit_log` | `?limit=&before=&action=&actor_id=&target_id=` → `[{id, actor_id, action, target_id, reason, details, created_at, actor_name?, target_name?}]` (noms des membres concernés, même partis) ; conservé 90 jours | On n'agit que sur un membre dont le rôle le plus haut est **strictement sous** le vôtre ; le propriétaire est intouchable, les administrateurs ne peuvent pas être exclus temporairement. ### Invitations, bots, vocal - `GET /v1/invites`, `POST /v1/invites {max_uses?, expires_in?}` (🔑 `create_invite`), `DELETE /v1/invites/{code}`. - **Scènes** : un salon vocal avec `stage: true` (création ou `PATCH /v1/channels/{id} {stage}`) ; seuls les orateurs et les membres qui ont `mute_members` y parlent et partagent. `PATCH /v1/voice/state {hand_raised}` lève la main, `{speaker: false}` quitte la scène ; `PATCH /v1/voice/states/{member} {speaker}` (🔑 `mute_members`) invite à parler ou renvoie dans le public. L'état vocal porte `speaker`, `hand_raised`, `can_speak`. - **Forums** (type de salon `forum`) : pas de messages propres ; `POST /v1/channels/{id}/posts {title, content}` crée un post (un fil `thread` du forum, avec son premier message) ; `GET /v1/channels/{id}/posts?limit=&before=` → `[{channel, author_id, excerpt, message_count, last_message_at}]`, dernière activité d'abord. On répond dans un post comme dans n'importe quel fil. - **Emojis personnalisés** : `GET /v1/emojis` → `[{id, name}]` ; `POST /v1/emojis?name=nom` (corps = image PNG, GIF ou WebP, 256 Ko) et `DELETE /v1/emojis/{id}` — 🔑 `manage_server` ; image : `GET /v1/emojis/{id}` (session). Dans les messages et les réactions : `<:nom:id>`. Événement `EMOJIS_UPDATE` (liste complète), `emojis` dans `READY`. - **Commandes slash** : `PUT /v1/bots/@me/commands [{name, description, options: [{name, description, type, required}]}]` (bots, remplace la liste), `GET /v1/commands` → `[{bot_id, name, description, options}]` (événement `COMMANDS_UPDATE` avec la liste complète), `POST /v1/channels/{id}/commands {bot_id, name, options: {nom: valeur}}` → `202 {id}` (droit d'écrire dans le salon ; erreurs `unknown_command`, `missing_option`, `invalid_option`, `unknown_option`, `bot_offline`) ; le bot reçoit `INTERACTION_CREATE {id, name, options, channel_id, member_id}` et répond sous 15 min par `POST /v1/interactions/{id}/reply {content, ephemeral?}` → message (`interaction: {name, member_id}`) ou, éphémère, `INTERACTION_REPLY {interaction_id, channel_id, bot_id, name, content}` au seul membre (`204`). - **Webhooks entrants** : `GET /v1/channels/{id}/webhooks`, `POST /v1/channels/{id}/webhooks {name}` → `{id, channel_id, name, created_by, created_at, token}` (jeton `qw_…` affiché une seule fois), `DELETE /v1/webhooks/{id}` — 🔑 `manage_webhooks` dans le salon (textuel ou d'annonces) ; créer un webhook exige aussi d'y avoir le droit d'écrire (`send_messages`, et `manage_messages` dans un salon d'annonces). Publier : `POST /v1/webhooks/{id}/{token} {"content": "…"}` **sans session** → le message (`201`) ; 10 messages par 10 s ; pas de notification `@everyone` ni des rôles non mentionnables. Les messages d'un webhook portent `webhook: {id, name}` ; leur `author_id` est un membre caché, jamais listé. - `GET /v1/bots` → `[{member}]`, `POST /v1/bots {name}` → `{member, token}` (jeton affiché une seule fois), `POST /v1/bots/{id}/token` → `{member, token}`, `DELETE /v1/bots/{id}` — 🔑 `manage_server`. - **Vocal et vidéo** : `POST /v1/channels/{id}/voice/join` (🔑 `connect`) → `{url, token, room, can_speak, can_stream, server_mute, server_deaf}` pour se connecter au serveur média LiveKit (SDK `livekit-client` ou équivalent) ; micro = 🔑 `speak`, caméra et partage d'écran = 🔑 `stream`. `GET /v1/voice/states` → `[{member_id, channel_id, self_mute, self_deaf, server_mute, server_deaf, can_speak, can_stream, video, screen, joined_at}]`, `PATCH /v1/voice/state {self_mute?, self_deaf?}`, `POST /v1/voice/leave`. - **Modération vocale** : `PATCH /v1/voice/states/{member} {mute?, deaf?, channel_id?, reason?}` (🔑 `mute_members`, `deafen_members`, `move_members`) ; micro et son coupés par la modération persistent jusqu'à levée. Un client déplacé par la modération reçoit `VOICE_MOVE {channel_id, from_channel_id}` et doit rejoindre ce salon (il a déjà été retiré de l'ancien). `DELETE /v1/voice/states/{member}` (🔑 `move_members`) le déconnecte. ## 6. Permissions `view_channel`, `send_messages`, `manage_messages`, `mention_everyone`, `create_invite`, `manage_channels`, `manage_roles`, `kick_members`, `ban_members`, `manage_server`, `connect`, `speak`, `stream`, `add_reactions`, `attach_files`, `moderate_members`, `view_audit_log`, `mute_members`, `deafen_members`, `move_members`, `manage_webhooks`, `administrator`. Calcul dans un salon : permissions de `@everyone` + union de vos rôles → surcharges de la catégorie → surcharges du salon (à chaque niveau : `@everyone`, puis vos rôles, puis vous). Sans `view_channel`, le salon n'existe pas pour vous (`404`). `administrator` et le propriétaire ont tout. Un membre **restreint** (exclusion temporaire, règles non acceptées, téléphone non vérifié) garde seulement `view_channel` ; ses refus portent le code de la restriction plutôt que `missing_permissions`. ## 7. Bonnes pratiques pour les bots - Ne répondez jamais à vos propres messages ni, sauf besoin, à ceux des autres bots (`author_id` = votre id, ou membre `bot: true`). - Respectez `Retry-After` sur les `429`. - Reconnectez-vous avec un délai croissant (1 s, 2 s, 4 s… jusqu'à 1 min). - Donnez à votre bot un rôle avec **le strict nécessaire** : son jeton porte toutes ses permissions. --- # Écrire un bot URL : https://quarel.app/wiki/developper/bots/ Un bot est un **membre du serveur** qui se connecte avec un jeton au lieu d’un compte. Il reçoit ses droits par des rôles, comme tout le monde. Référence complète : [API des serveurs communautaires](/wiki/developper/api/). ## 1. Créer le bot Dans l’application : menu du serveur › **Paramètres du serveur** › **Bots** › nom du bot › Créer (il faut la permission « Gérer le serveur »). Le **jeton** `qb_…` s’affiche **une seule fois** : gardez-le comme un mot de passe. « Nouveau jeton » le remplace (l’ancien cesse aussitôt de marcher). Puis donnez-lui un rôle avec les permissions nécessaires (voir les salons, écrire…). ## 2. Le faire tourner L’exemple [`examples/pingbot`](https://github.com/anlekg/quarel/tree/main/examples/pingbot) (Go, ~150 lignes) répond « pong » à « !ping » dans tous les salons où il peut écrire : ```sh git clone https://github.com/anlekg/quarel.git && cd quarel QUAREL_URL=https://mon-serveur.fr:8090 \ QUAREL_BOT_TOKEN=qb_… \ QUAREL_SERVER_ID= \ go run ./examples/pingbot ``` `QUAREL_SERVER_ID` (26 caractères, affiché avec le jeton et dans les liens d’invitation après `sid=`) sert à vérifier un serveur au **certificat auto-signé lié à son identité** ; inutile avec Let’s Encrypt. ## 3. Comment ça marche 1. **Temps réel** : WebSocket sur `/v1/gateway`, premier message `{"op":"auth","token":"qb_…"}`, puis `READY` (le bot, le serveur, les salons visibles…) et les événements (`MESSAGE_CREATE`…). 2. **Actions** : API REST avec `Authorization: Bearer qb_…`, par exemple `POST /v1/channels/{id}/messages {"content": "pong"}`. 3. **Reconnexion** : en cas de coupure, se reconnecter avec un délai croissant ; `READY` redonne l’état complet. ## Commandes slash Un bot peut proposer des commandes : l’application les suggère dès qu’on tape `/` dans un salon. 1. **Déclarer** (à chaque connexion, par exemple sur `READY`) : `PUT /v1/bots/@me/commands` avec la liste complète, qui remplace la précédente : ```json [{"name": "lancer", "description": "Lance un dé", "options": [{"name": "faces", "description": "Nombre de faces", "type": "integer", "required": true}]}] ``` Noms : 1 à 32 caractères `a-z 0-9 - _` ; 50 commandes et 10 options au plus ; types `string`, `integer`, `boolean`, `member` (identifiant de membre), `channel` (identifiant de salon) ; les options obligatoires d’abord. 2. **Recevoir** : quand un membre lance la commande dans un salon où il peut écrire, le serveur vérifie les options puis envoie **au bot seul** `INTERACTION_CREATE {id, name, options, channel_id, member_id}`. Le bot doit être connecté (sinon `409 bot_offline` pour le membre). 3. **Répondre** dans les 15 minutes : `POST /v1/interactions/{id}/reply {"content": "…", "ephemeral": false}`. Réponse publique : un message du bot dans le salon, marqué « X a utilisé /nom » (le bot doit pouvoir écrire dans ce salon). `"ephemeral": true` : seul l’auteur de la commande la voit, rien n’est enregistré. Dans l’application, les arguments suivent la commande dans l’ordre (`/lancer 20`), `"entre guillemets"` pour garder des mots ensemble ; un texte en dernière option prend toute la fin de la ligne ; membres en `@pseudo`, salons en `#nom`. L’exemple `pingbot` déclare `/ping` et `/echo`. N’importe quel langage fait l’affaire (HTTP + WebSocket). Pour un certificat auto-signé hors Go, la vérification du lien entre le certificat et l’identité du serveur est décrite dans l’[API](/wiki/developper/api/#1-principes) ; ne désactivez jamais simplement la vérification du certificat. ## Bonnes pratiques - Respectez les limites de débit (`429` + `Retry-After`). - Ignorez les champs et événements inconnus : l’API v1 peut s’enrichir. - Ne répondez pas à vos propres messages ni à ceux des autres bots (membres `bot: true`) pour éviter les boucles. ## Plus simple : un webhook entrant Pour **publier** des messages sans rien écouter (alerte de supervision, fin d’une sauvegarde, intégration continue, formulaire), un webhook suffit : pas de programme qui tourne, une simple requête HTTP. 1. Roue dentée du salon › **Webhooks** › nom › **Créer un webhook** (permission « gérer les webhooks », et le droit d’écrire dans ce salon). Copiez l’adresse : elle n’est affichée qu’une fois. 2. Publiez : ```sh curl -X POST -H 'Content-Type: application/json' \ -d '{"content": "Sauvegarde terminée ✅"}' \ https://mon-serveur.exemple:8090/v1/webhooks// ``` Le message apparaît sous le nom du webhook, marqué **WEBHOOK**. Qui connaît l’adresse peut écrire dans le salon : gardez-la secrète, et supprimez le webhook s’il a fuité (l’adresse cesse aussitôt de fonctionner, ses anciens messages restent). --- # Contribuer URL : https://quarel.app/wiki/developper/contribuer/ Le code est sur [GitHub](https://github.com/anlekg/quarel), sous licence **Apache-2.0**. ## Organisation du dépôt | Dossier | Contenu | |---|---| | `cmd/quarel-identity`, `internal/identity` | service d’identité (Go) | | `cmd/quarel-server`, `internal/community` | serveur communautaire (Go, LiveKit embarqué pour le vocal) | | `cmd/quarelctl` | client de test en ligne de commande | | `client/` | application (Electron, React, TypeScript, Vite ; chiffrement vodozemac en WebAssembly) | | `site/` | ce site (Astro, Starlight) ; le wiki est dans `site/src/content/docs/wiki/` | | `cmd/quarel-docs-mcp`, `internal/docsmcp` | serveur MCP de la documentation | | `deploy/` | fichiers Docker Compose | ## Construire et tester Il faut Go 1.27+, Node.js 24, et pour certains tests Docker, `xvfb-run` et livekit-server. ```sh make build # binaires dans bin/ make test # tests Go make run-identity # service d’identité local (:8080) make run-server # serveur communautaire local (https://localhost:8090) make client-dev # application en développement make client-test # types et tests unitaires du client make e2e-client # application réelle contre de vrais services ``` Site : `cd site && npm ci && npm run dev`. ## Règles du projet - Documentation en **français**, rédigée de façon **neutre en genre** ; code, identifiants et messages de commit en anglais. - Dépendances : licences compatibles avec Apache-2.0 seulement (MIT, BSD, Apache-2.0, MPL-2.0…), **jamais de GPL/AGPL** ; les composants embarqués sont listés dans `NOTICE`. - Chiffrement : uniquement des bibliothèques éprouvées, jamais de cryptographie maison. ## Signaler un problème - **Bug ou idée** : [tickets GitHub](https://github.com/anlekg/quarel/issues). - **Faille de sécurité** : ne l’exposez pas dans un ticket public ; utilisez le [signalement privé de GitHub](https://github.com/anlekg/quarel/security/advisories/new). --- # MCP de la documentation URL : https://quarel.app/wiki/developper/mcp/ Le **serveur MCP de la documentation** permet à un assistant IA compatible avec le [Model Context Protocol](https://modelcontextprotocol.io) de **chercher et lire ce wiki** : il répond à vos questions sur l’hébergement, l’API ou les bots en s’appuyant sur la documentation à jour, et cite les pages utilisées. Adresse : **`https://quarel.app/mcp`** (transport HTTP « streamable », sans compte, en lecture seule). ## Outils proposés | Outil | Rôle | |---|---| | `search_docs` | recherche plein texte (accents et majuscules ignorés), renvoie les meilleures sections avec leur adresse | | `read_page` | une page entière en Markdown | | `list_pages` | toutes les pages, avec leur résumé | Chaque page est aussi disponible comme **ressource** MCP (adresse de la page sur le site). ## Le brancher **Claude Code** : ```sh claude mcp add --transport http quarel-docs https://quarel.app/mcp ``` **Claude (claude.ai ou application)** : Paramètres › Connecteurs › **Ajouter un connecteur personnalisé**, adresse `https://quarel.app/mcp`. **Autres clients** (fichier de configuration JSON) : ```json { "mcpServers": { "quarel-docs": { "type": "http", "url": "https://quarel.app/mcp" } } } ``` Puis demandez par exemple : « Comment sauvegarder mon serveur Quarel sous Docker ? » ou « Écris un bot Quarel en Python qui souhaite la bienvenue ». ## En local Le serveur fait partie du dépôt (`cmd/quarel-docs-mcp`, Go) et peut tourner chez vous, sur la documentation de votre copie : ```sh go run ./cmd/quarel-docs-mcp -docs site/src/content/docs -stdio # pour un assistant local (stdio) go run ./cmd/quarel-docs-mcp -docs site/src/content/docs -addr 127.0.0.1:8095 # HTTP, sur /mcp ``` ## Sans MCP Le site publie aussi [`/llms.txt`](/llms.txt) (sommaire) et [`/llms-full.txt`](/llms-full.txt) (toute la documentation en un fichier), à donner directement à un assistant. --- # Migrer depuis Discord URL : https://quarel.app/wiki/heberger/migrer-depuis-discord/ L’outil **quarel-discord-import** lit votre serveur Discord et recrée sa **structure** sur votre serveur Quarel. Il faut **deux bots** : un bot Discord qui lit, et un bot Quarel qui écrit. Comptez une quinzaine de minutes. ## Ce qui est copié | Discord | Quarel | |---|---| | Rôles : nom, couleur, ordre, « afficher séparément », « mentionnable », permissions | Pareil | | Permissions de `@everyone` | Permissions de `@everyone` | | Catégories, salons textuels, vocaux, d’annonces, forums | Pareil | | Salons « scène » | Salons vocaux avec la case **Scène** | | Salons « média » | Forums | | Sujet des salons | Sujet (1 024 caractères au plus) | | Permissions d’un salon ou d’une catégorie pour un rôle | Droits du salon ou de la catégorie pour ce rôle | | Emojis personnalisés | Emojis du serveur (100 au plus, 256 Ko chacun) | | Nom du serveur (option `--rename`) | Nom du serveur | ## Ce qui n’est pas copié - **Les membres et leurs rôles** : un compte Discord et un compte Quarel n’ont aucun lien. Invitez vos membres (menu du serveur › **Inviter sur…**), puis redonnez les rôles. - **Les messages**, les **fils**, l’**icône** du serveur et des rôles. - Les rôles **gérés par Discord** (bots, boosts, abonnements). - Les exceptions de permissions **pour une personne** dans un salon. - Les réglages sans équivalent : mode lent, salon réservé aux adultes, nombre de places d’un salon vocal, étiquettes des forums. À la fin, l’outil liste tout ce qui n’a pas pu être copié à l’identique : lisez ce rapport avant d’inviter vos membres. ## Avant de commencer - **Python 3.10** ou plus récent, et la bibliothèque `cryptography` : - Windows : installez Python depuis [python.org](https://www.python.org/downloads/), puis `py -m pip install cryptography` ; - Linux : `sudo apt install python3-cryptography` (ou `pip install cryptography`). - L’outil : téléchargez [`quarel_discord_import.py`](https://raw.githubusercontent.com/anlekg/quarel/main/tools/discord-import/quarel_discord_import.py) (clic droit › Enregistrer sous), ou prenez le dossier [`tools/discord-import`](https://github.com/anlekg/quarel/tree/main/tools/discord-import) du dépôt. - Sur Discord, la permission **Gérer le serveur** (pour ajouter un bot). Sur Quarel, être **propriétaire** du serveur, ou avoir « Gérer le serveur » et « Gérer les rôles ». ## 1. Le bot Discord (lecture seule) 1. Ouvrez le [portail des développeurs Discord](https://discord.com/developers/applications) › **New Application** › un nom (par exemple « Import Quarel ») › **Create**. 2. Onglet **Bot** › **Reset Token** › copiez le jeton et gardez-le pour l’étape 3. **Ne le partagez pas** : il donne accès à votre bot. 3. Onglet **OAuth2** › **URL Generator** : cochez **bot**, **aucune permission**, puis ouvrez le lien généré et choisissez votre serveur. Le bot n’a besoin d’aucune permission : il lit seulement la liste des rôles, des salons et des emojis. Si des salons privés manquent dans le plan, donnez-lui temporairement « Voir les salons ». ## 2. Le bot Quarel (écriture) Dans l’application Quarel, sur votre serveur : 1. Menu du serveur › **Paramètres du serveur** › **Bots** › nom « Importation » › **Créer**. Copiez le **jeton** `qb_…` : il ne s’affiche qu’une fois. 2. **Rôles** › créez un rôle « Importation » avec **Administrateur**, puis **montez-le tout en haut** de la liste. Un bot ne peut gérer que les rôles placés sous son propre rôle. 3. **Membres** › le bot « Importation » › donnez-lui ce rôle. 4. **Invitations** › créez une invitation et copiez le **lien** : il désigne votre serveur et permet à l’outil de vérifier qu’il parle bien à lui (même avec un certificat auto-signé). ## 3. Lancer l’import Ouvrez un terminal dans le dossier de l’outil. **D’abord un essai**, qui montre tout ce qui sera fait sans rien modifier : ```sh python3 quarel_discord_import.py 'https://app.quarel.app/join#…' --dry-run ``` Sous Windows, remplacez `python3` par `py`. L’outil demande les deux jetons (rien ne s’affiche pendant la saisie, c’est normal). Vous pouvez aussi les mettre dans les variables `DISCORD_BOT_TOKEN` et `QUAREL_BOT_TOKEN` : ne les écrivez jamais dans la commande elle-même, elle resterait dans l’historique du terminal. Si le plan vous convient, lancez l’import : ```sh python3 quarel_discord_import.py 'https://app.quarel.app/join#…' --rename --replace-defaults ``` - `--rename` : le serveur Quarel prend le nom du serveur Discord ; - `--replace-defaults` : supprime les salons créés d’office avec le serveur Quarel (« général », « Général » et leurs catégories), **seulement** s’il n’y a encore rien d’autre et aucun message ; - `--guild ` : si votre bot Discord est sur plusieurs serveurs (l’outil les liste) ; - `--no-emojis` : sans les emojis. **Relancer** la même commande est sans risque : ce qui existe est mis à jour, ce qui manque est créé, rien n’est dupliqué. Les correspondances entre Discord et Quarel sont gardées dans `discord-import-.json`, à côté de l’outil : gardez ce fichier si vous comptez relancer l’import. ## 4. Après l’import 1. Lisez le **rapport** de fin et ajustez à la main ce qui doit l’être (voir ci-dessous). 2. Retirez le rôle « Importation » au bot Quarel, puis supprimez le bot (**Bots** › Supprimer) et le rôle. 3. Sur Discord, retirez le bot du serveur, ou supprimez l’application. 4. Invitez vos membres et redonnez les rôles. ## Les différences à connaître ### Permissions | Discord | Quarel | |---|---| | Administrateur, Gérer le serveur, Gérer les salons, Gérer les webhooks | Mêmes permissions | | Gérer les rôles | Gérer les rôles et les droits des salons | | Voir les logs du serveur | Voir le journal de modération | | Expulser, Bannir, Exclure temporairement | Mêmes permissions | | Voir les salons, Envoyer des messages, Gérer les messages, Ajouter des réactions, Joindre des fichiers | Mêmes permissions | | Mentionner @everyone, @here et tous les rôles | Mentionner @everyone et tous les rôles | | Créer une invitation | Créer des invitations | | Se connecter, Parler | Mêmes permissions | | Vidéo | Caméra et partage d’écran | | Rendre les membres muets, Mettre en sourdine, Déplacer des membres | Couper le micro des autres, Mettre les autres en sourdine, Déplacer et déconnecter | | Voir les anciens messages | Pas de permission : voir un salon donne **tout son historique** | | Créer des fils, Envoyer des messages dans les fils | « Envoyer des messages » du salon | | Gérer les fils | « Gérer les salons » et « Gérer les messages » | | Gérer les expressions | Les emojis demandent « Gérer le serveur » | | Gérer les pseudos, Voix prioritaire, Événements, TTS, sondages, soundboard, activités, autocollants | Pas d’équivalent | Le rapport signale chaque rôle qui perd une permission, et chaque **restriction qui disparaît**. Par exemple, un salon où `@everyone` ne peut pas voir les anciens messages montrera tout l’historique sur Quarel. ### Salons d’annonces Dans Quarel, écrire dans un salon d’annonces demande **aussi** « Gérer les messages ». Vérifiez que les bonnes personnes l’ont dans ces salons. ### Catégories non synchronisées Sur Discord, un salon **non synchronisé** avec sa catégorie ignore les permissions de la catégorie. Sur Quarel, un salon applique **toujours** les droits de sa catégorie, puis les siens. L’outil copie les droits de chaque salon. Quand le résultat peut différer, il l’écrit dans la partie « À vérifier » du rapport : ouvrez alors les droits de ce salon (roue dentée › **Permissions**) et corrigez-les si besoin. Un salon **synchronisé** reçoit seulement les droits de sa catégorie, comme sur Discord. ## Questions fréquentes **« le bot Quarel doit avoir un rôle avec Administrateur »** : refaites l’étape 2 (rôle Administrateur, tout en haut, donné au bot). **« ce n’est pas le serveur attendu »** : l’adresse mène à un autre serveur que celui du lien d’invitation. L’outil s’arrête avant d’envoyer le jeton : vérifiez le lien. **« ce serveur a un certificat auto-signé : donnez son identifiant »** : utilisez un lien d’invitation plutôt que l’adresse seule (il contient l’identifiant du serveur), ou ajoutez `--sid `. **« role_hierarchy »** : le rôle du bot Quarel n’est pas tout en haut de la liste des rôles. **Rien ne s’affiche quand je colle le jeton** : c’est voulu, le jeton reste invisible. Collez-le puis appuyez sur Entrée. --- # Réseau, ports et HTTPS URL : https://quarel.app/wiki/heberger/reseau/ ## Ports d’un serveur communautaire | Port | Rôle | |---|---| | **8090/tcp** | application, connexions, temps réel (HTTPS) | | **7882/udp** | vocal et vidéo | | **7881/tcp** | vocal, secours quand l’UDP est bloqué | | 8091/tcp | page d’administration — **réseau local seulement, ne jamais l’ouvrir** | Par défaut, le serveur ouvre lui-même ces ports sur votre box par **UPnP** (bail d’une heure renouvelé, retiré à l’arrêt). Avec Docker, il faut pour cela le réseau de l’hôte (`network_mode: host`, déjà dans le `compose.yaml` fourni). Pour l’empêcher : `QUAREL_UPNP=off`, puis redirigez ces ports à la main vers la machine dans l’interface de votre box. **Plusieurs serveurs sur la même machine** : donnez à chacun ses propres ports (page d’administration › Réglages › Réseau et Vocal et vidéo, ou `QUAREL_ADDR`, `QUAREL_ADMIN_ADDR`, `QUAREL_VOICE_SIGNAL_PORT`, `QUAREL_VOICE_TCP_PORT`, `QUAREL_VOICE_UDP_PORT`). Si les ports vocaux sont déjà pris par un autre serveur, le vocal reste indisponible et le journal l’indique (« voice unavailable »). ## Diagnostic Le tableau de bord de la page d’administration indique si le serveur est joignable : - **ok** : ports ouverts, adresse publique trouvée ; - **ports à ouvrir à la main** : pas d’UPnP sur la box (désactivé, ou box qui ne le propose pas) ; - **double NAT** : votre box est elle-même derrière un autre routeur (box opérateur + routeur perso, réseau mobile 4G/5G, CGNAT). Il faut ouvrir les ports sur les deux équipements, ou demander une IP publique à votre opérateur ; - **inconnu** : le test n’a pas pu aboutir. L’adresse publique annoncée pour le vocal est celle de la box (trouvée par UPnP), sinon découverte par STUN. ## HTTPS Réglage « HTTPS › Certificat » de la page d’administration (`QUAREL_TLS`) : - **Auto-signé lié à l’identité** (par défaut) : rien à faire. Le certificat porte une preuve signée par la clé du serveur ; l’application le vérifie grâce à l’identifiant contenu dans les liens d’invitation. Pas besoin de nom de domaine. **Mais la version web (navigateur) ne peut pas rejoindre un tel serveur.** - **Let’s Encrypt** (`acme`) : avec un nom de domaine qui pointe vers votre box. Le port public **443** doit mener au port 8090 de la machine (défi TLS-ALPN). La version web peut alors rejoindre le serveur. - **Fichiers** : votre propre certificat (`QUAREL_TLS_CERT`, `QUAREL_TLS_KEY`). - **Désactivé** : derrière un proxy HTTPS (Caddy, nginx, Traefik…) qui transmet les WebSockets. Déclarez le proxy dans `QUAREL_TRUSTED_PROXIES` pour que les limites s’appliquent à la vraie adresse des clients, et **son nom de domaine dans `QUAREL_TLS_HOSTS`** (obligatoire, voir ci-dessous). Le vocal (UDP) ne passe pas par le proxy : ses ports restent à ouvrir. ## Adresse publique et nom `QUAREL_TLS_HOSTS` (réglage « Nom public du serveur ») : le nom ou l’adresse que les membres utilisent, repris dans les liens d’invitation. Si votre IP change souvent, utilisez un nom de domaine dynamique (DynDNS). Avec un certificat ordinaire (proxy, Let’s Encrypt, fichiers), l’application signe à chaque connexion le nom qu’elle a contacté, et le serveur refuse un nom qui n’est pas le sien : un autre serveur ne peut pas relayer les connexions de vos membres en se faisant passer pour le vôtre. Le serveur connaît ses noms par ce réglage, le domaine Let’s Encrypt ou les noms du certificat fourni. **Derrière un proxy, ce réglage est donc obligatoire** (le tableau de bord le rappelle). Avec le certificat automatique lié à l’identité, rien à faire : l’application vérifie ce certificat à chaque connexion. ## Service d’identité Il écoute sur 8080/tcp (derrière le port public 443) et, si le relais d’appels est actif, sur **3478/udp** et **49160-49200/udp**, ouverts aussi par UPnP à la maison. Détails : [Déployer un service d’identité](/wiki/heberger/service-identite/). --- # Héberger un serveur communautaire URL : https://quarel.app/wiki/heberger/serveur-communautaire/ Un serveur communautaire, c'est votre « serveur Discord » à vous : salons textuels et vocaux, rôles, modération. Il tourne chez vous (un PC, un mini-serveur, un NAS avec Docker) ; les membres s'y connectent avec leur compte Quarel. ## Installation Il faut Docker. Depuis une copie du dépôt : ```sh git clone https://github.com/anlekg/quarel.git && cd quarel/deploy/server docker compose up -d --build docker compose logs server # affiche l'adresse de l'administration et le code d'installation ``` (Sans Compose : `docker build -f Dockerfile.server -t quarel-server .` puis `docker run -d --name quarel --restart unless-stopped --network host -v quarel-data:/data quarel-server`.) ### Sous Windows 1. Téléchargez **`Quarel-Serveur-Setup-.exe`** depuis la [page d’accueil](/#heberger) (empreintes SHA-256 : [SHA256SUMS](https://quarel.app/telechargements/SHA256SUMS)) et lancez-le (Windows 10 ou 11, 64 bits). Windows demande l'autorisation d'administrateur : l'installateur place le programme dans `Program Files`, autorise le serveur et le vocal dans le pare-feu, et le fait démarrer avec votre session. > Les installateurs ne sont pas encore signés : Windows SmartScreen affiche « Windows a protégé votre ordinateur » ; cliquez sur « Informations complémentaires » puis « Exécuter quand même ». 2. À la fin, la **page d'administration** s'ouvre dans votre navigateur (`http://127.0.0.1:8091`) : choisissez son mot de passe, puis suivez la page comme ci-dessous. 3. Une **icône Quarel** (verte) reste près de l'horloge : clic → page d'administration ; clic droit → état du serveur, « Lancer au démarrage de Windows », « Quitter ». Sous Windows, la page d'administration n'est ouverte que sur l'ordinateur lui-même. Les données (base, clés, réglages, journal `quarel-server.log`) sont dans `%LOCALAPPDATA%\Quarel\Serveur` ; la désinstallation (Paramètres → Applications) les conserve. Pour reconstruire l'installateur depuis les sources (Linux ou macOS, avec Go et NSIS) : `make windows`. ### Page d'administration Ouvrez **`https://:8091`** depuis n'importe quel appareil du réseau local (l'adresse est affichée dans le journal). Le certificat de la page est auto-signé : le navigateur affiche un avertissement à accepter une fois ; son **empreinte** (SHA-256) est écrite dans le journal pour vérifier qu'il s'agit bien du vôtre. Depuis la machine elle-même, `http://localhost:8091` suffit. La page ne répond qu'à l'adresse IP de la machine, à `localhost` et au nom de la machine (autres noms : `QUAREL_ADMIN_HOSTS`) : un site web ne peut pas la piloter depuis votre navigateur. 1. **Premier passage** : choisissez le mot de passe administrateur. Depuis un autre appareil que la machine elle-même, le **code d'installation** affiché dans le journal est demandé (personne d'autre sur le réseau ne peut prendre la main avant vous). 2. **Tableau de bord** : état du service, adresse, identifiant, membres, vocal, ports de la box. Tant que le serveur n'a pas de propriétaire, il affiche un **lien propriétaire** : dans l'application Quarel, « Rejoindre un serveur », collez-le : vous devenez propriétaire. Bouton « Renommer le serveur ». Si le propriétaire ne peut plus se connecter (compte perdu ou supprimé), **« Réinitialiser le propriétaire »** le retire et affiche un nouveau lien propriétaire. Le propriétaire peut aussi transmettre le serveur à un autre membre depuis l'application (clic sur le membre › « Transférer la propriété »). 3. **Réglages** : services d'identité acceptés, réseau et UPnP, certificat HTTPS, vocal, taille des fichiers, espace disque réservé (les fichiers sont refusés quand il reste moins de 1 Go libre), aperçus de liens, SMS. **Enregistrer** vérifie les réglages (refusés avec explication s'ils sont incohérents, rien n'est changé) puis redémarre le service en quelques secondes. 4. **Sauvegardes** : télécharger une archive complète, ou en restaurer une (les données actuelles sont mises de côté, jamais effacées). 5. **Journal** : les derniers messages du serveur. 6. **Services d'identité acceptés** (bas du tableau de bord) : pour chacun, si votre serveur est accepté. Certains services n'autorisent que les serveurs qu'ils ont approuvés : bouton **Demander l'accès** (on vous demande un moyen de vous contacter), puis attendre l'approbation de leur opérateur. Un service peut aussi avoir **bloqué** votre serveur : ses utilisateurs ne peuvent plus le rejoindre. La page n'est **jamais ouverte vers Internet** : l'UPnP ne l'ouvre pas et elle refuse toute adresse qui ne vient pas du réseau local. Mot de passe oublié : arrêtez le serveur, supprimez `admin.json` dans le volume de données, relancez. Les réglages de la page elle-même (`QUAREL_ADMIN_PUBLIC=1` pour l'ouvrir au-delà du réseau local, `QUAREL_ADMIN_TLS=off` pour accepter HTTP depuis les autres machines, `QUAREL_ADMIN_HOSTS`) ne se règlent que par variables d'environnement : la page ne peut pas élargir elle-même son exposition. Les réglages sont enregistrés dans `settings.json` (volume de données). Une variable d'environnement `QUAREL_*` (option `-e` de Docker, fichier Compose) reste prioritaire : le réglage correspondant apparaît alors verrouillé dans la page. `QUAREL_ADMIN_ADDR` change l'adresse de la page (`off` pour la couper). ### Bon à savoir - `network_mode: host` (`--network host`) permet l'**ouverture automatique des ports** de la box (UPnP). Sans UPnP, ouvrez à la main vers cette machine : **8090/tcp** (application et connexions), **7882/udp** et **7881/tcp** (voix) ; le tableau de bord les rappelle. - **HTTPS** est actif d'office avec un certificat lié à l'identité du serveur : l'application le vérifie sans autorité ni nom de domaine. Avec un nom de domaine, choisissez Let's Encrypt dans les réglages (le port public 443 doit mener au 8090). Le **client web** (navigateur) ne peut joindre que des serveurs avec un nom de domaine et Let's Encrypt. - Comptes acceptés : ceux de `identity.quarel.app` par défaut ; ajoutez d'autres services dans les réglages. ## Venir de Discord Votre communauté est déjà sur Discord ? L’outil d’import recrée ses rôles, salons, droits et emojis sur votre serveur Quarel : voir [Migrer depuis Discord](/wiki/heberger/migrer-depuis-discord/). ## Modération automatique Dans l’application : menu du serveur › Paramètres du serveur › **Modération automatique** (permission « gérer le serveur »). - **Mots interdits**, un par ligne : majuscules et accents ignorés, mots entiers ; `arnaq*` couvre tous les mots qui commencent par « arnaq » ; plusieurs mots : cette suite exacte. - **Refuser les liens**, **limiter les mentions** par message, **refuser les messages répétés** (le même message une troisième fois en 30 secondes). - **Exclusion automatique** après 3 messages refusés en 10 minutes (durée au choix). Le message refusé n’est pas publié ; son auteur voit pourquoi. Chaque refus est noté dans le journal de modération, sans le texte du message. Les personnes qui peuvent gérer les messages d’un salon (modération, administration, propriétaire) n’y sont pas soumises. ## Exiger un numéro de téléphone (facultatif) Pour limiter les faux comptes et les retours de bannis, un serveur peut exiger un numéro vérifié par SMS (`quarelctl srv-set require_phone=true`). Le serveur ne garde jamais le numéro, seulement une empreinte. Choisissez comment les SMS partent (page d'administration, « Réglages », « Vérification du téléphone », ou variables ci-dessous) : - **Webhook (recommandé)** : le serveur envoie `{phone, code, text}` à une adresse de votre choix, qui fait partir le SMS. Vous pouvez y brancher votre propre téléphone Android (application « passerelle SMS »), un modem GSM ou n'importe quel fournisseur : aucun tiers imposé. `-e QUAREL_PHONE_VERIFY=webhook -e QUAREL_PHONE_WEBHOOK_URL=https://… -e QUAREL_PHONE_WEBHOOK_SECRET=…` Avec un secret, chaque requête porte `X-Quarel-Signature: sha256=` : vérifiez-la côté passerelle. - **OVHcloud SMS (recommandé)** : fournisseur européen. Créez un compte SMS et des clés d'API (droit `POST /sms/*/jobs`), puis `-e QUAREL_PHONE_VERIFY=ovh -e QUAREL_OVH_APP_KEY=… -e QUAREL_OVH_APP_SECRET=… -e QUAREL_OVH_CONSUMER_KEY=… -e QUAREL_OVH_SMS_SERVICE=sms-xx00000-1` (et `QUAREL_OVH_SMS_SENDER` si vous avez un nom d'expéditeur validé). - **Twilio (option)** : fournisseur américain ; les numéros de vos membres transitent chez lui. `QUAREL_PHONE_VERIFY=twilio` et les variables `QUAREL_TWILIO_*`. Les SMS sont à vos frais selon le fournisseur. ## Sauvegarder Le plus simple : page d'administration, **Sauvegardes**, « Télécharger une sauvegarde ». En ligne de commande : La sauvegarde se fait **serveur en marche** ; elle contient la base (messages, membres, rôles…), la **clé du serveur** (son identité : sans elle, les membres verraient un autre serveur) et les fichiers envoyés : ```sh docker exec quarel /quarel-server backup - > quarel-$(date +%F).tar.gz ``` Gardez ces fichiers en lieu sûr, idéalement chiffrés : ils permettent de se faire passer pour votre serveur. ## Restaurer Serveur arrêté, sur la même machine ou une nouvelle : ```sh docker stop quarel docker run --rm -i -v quarel-data:/data quarel-server restore - --force < quarel-2026-09-24.tar.gz docker start quarel ``` La restauration vérifie l'archive avant de toucher à quoi que ce soit (bon type de sauvegarde, version compatible, clé présente) ; sans `--force` elle refuse d'écrire par-dessus des données existantes, et avec `--force` les anciennes données sont **mises de côté** dans `before-restore-` (à supprimer à la main une fois rassuré). Le serveur garde la même identité : les membres se reconnectent sans rien faire. ## Mettre à jour ```sh cd quarel && git pull && docker build -f Dockerfile.server -t quarel-server . docker stop quarel && docker rm quarel docker run -d --name quarel --restart unless-stopped --network host -v quarel-data:/data quarel-server ``` Les données restent dans le volume `quarel-data`. Au premier démarrage d'une nouvelle version qui change la base, le serveur en **garde d'abord une copie** (`server.db.pre-v-`, les 3 dernières sont conservées), puis la met à jour. Une ancienne version refuse de démarrer sur une base plus récente plutôt que de l'abîmer : réinstallez la version récente, ou restaurez une sauvegarde faite avec l'ancienne. `docker run --rm quarel-server version` affiche la version et le schéma de base. Par prudence, faites une sauvegarde avant chaque mise à jour. --- # Déployer un service d’identité URL : https://quarel.app/wiki/heberger/service-identite/ Le service Identity gère les comptes (email, pseudo, mot de passe, 2FA), les amis et les messages privés chiffrés, et délivre les identités portables acceptées par les serveurs communautaires. L'instance officielle est `identity.quarel.app` ; n'importe qui peut héberger la sienne. ## Prérequis - Une machine avec Docker et Docker Compose. - Un **nom de domaine** pointant vers elle (ex. `identity.mon-asso.fr`). Il fait partie de chaque identité (`pseudo@identity.mon-asso.fr`) et de la configuration des serveurs qui l'acceptent : **choisissez-le une fois pour toutes**. - Le port **443** ouvert vers la machine (Let's Encrypt et les utilisateurs y passent). - Pour le **relais d'appels** (TURN, utilisé quand deux amis ne peuvent pas se joindre directement) : les ports **UDP 3478 et 49160-49200** ouverts vers la machine. L'adresse IP publique est trouvée automatiquement (`QUAREL_TURN_PUBLIC_IP=auto` : box par UPnP, sinon STUN ; suivie si elle change) ou indiquée à la main. À la maison, avec le réseau de l'hôte (`network_mode: host`, ou l'exécutable Windows), le service ouvre lui-même ces ports sur la box par **UPnP** (`QUAREL_UPNP=off` pour l'empêcher). Mettre `QUAREL_TURN=off` pour ne pas proposer de relais. - Un compte SMTP pour envoyer les codes (vérification d'email, mot de passe oublié). Sans SMTP, les codes n'apparaissent que dans le journal du service : suffisant pour un essai, pas pour de vrais utilisateurs. ## Installation ```sh git clone https://github.com/anlekg/quarel.git cd quarel/deploy/identity cp .env.example .env # renseigner le domaine, l'email Let's Encrypt, le SMTP docker compose up -d --build curl https://identity.mon-asso.fr/v1/health # {"status":"ok"} ``` Le certificat HTTPS est obtenu automatiquement au premier accès. **Derrière un proxy HTTPS existant** (Caddy, nginx, Traefik…) : utiliser `docker compose -f compose.proxy.yaml up -d --build`. Le service écoute alors en HTTP sur `127.0.0.1:8080` ; le proxy doit transmettre `https://` vers cette adresse, WebSockets compris (`/v1/gateway`), et `X-Forwarded-For`. ### Page d'administration Le service a une page d'administration sur le port **8081**, publiée seulement sur la machine elle-même (`127.0.0.1:8081`, et elle refuse toute adresse Internet ; les fichiers Compose l'autorisent donc en HTTP, `QUAREL_ADMIN_TLS=off` — ailleurs, les autres machines doivent passer par HTTPS). Sur un serveur loué, passez par un tunnel SSH : ```sh ssh -L 8081:127.0.0.1:8081 utilisateur@mon-serveur # puis ouvrir http://localhost:8081 ``` Au premier passage, choisissez le mot de passe administrateur. On y trouve : - **Tableau de bord** : nom public, nombre de comptes, certificat, emails, relais d'appels, avec des alertes (nom public encore « localhost », pas de SMTP…) ; - **Réglages** : tout ce que contient `.env`, modifiable sans ligne de commande. Une variable présente dans `.env` reste prioritaire (le réglage est alors verrouillé dans la page) : vous pouvez vider `.env` et tout régler dans la page ; - **Comptes** : rechercher, désactiver ou réactiver un compte (raison obligatoire, consignée), journal de l'opérateur, changement de la clé de signature ; - **Sauvegardes** et **Journal**. ### Qui peut s'inscrire, quels serveurs sont autorisés Dans **Réglages** : - **Inscriptions** : ouvertes, **sur invitation** (codes créés dans la page « Invitations », et par vos utilisateurs si vous leur en accordez), ou fermées ; éventuellement limitées à certains domaines d'email et à un nombre de comptes. - **Serveurs communautaires** : - **tous, sauf ceux que vous bloquez** (recommandé) : la page « Serveurs » tient une liste noire que l'application respecte ; vous ne savez pas où vont vos utilisateurs ; - **seulement les serveurs approuvés** : un serveur demande l'accès depuis sa propre page d'administration, vous l'approuvez dans « Serveurs ». Les jetons d'identité sont alors chiffrés pour ce seul serveur : aucun autre ne peut accepter vos comptes. En contrepartie, votre service voit à quels serveurs chacun se connecte (il ne le conserve pas). Pour que des serveurs communautaires acceptent vos comptes, leurs hébergeurs ajoutent votre domaine : `QUAREL_TRUSTED_ISSUERS=identity.quarel.app,identity.mon-asso.fr`. ### Place disque Le service ne garde que des données chiffrées en attente de livraison, avec des bornes réglables (« Messages privés ») : copies de fichiers en attente par personne (`QUAREL_DM_FILE_QUOTA_MB`, 500 Mo), messages en attente par appareil (`QUAREL_INBOX_MAX_MB`, 256 Mo, dont un quart au plus par expéditeur), effacés après 30 jours s'ils ne sont jamais récupérés (`QUAREL_INBOX_TTL`). Les fichiers sont refusés quand il reste moins de 1 Go libre sur la machine (`QUAREL_MIN_FREE_MB`). Les sessions inutilisées pendant 90 jours se terminent (`QUAREL_SESSION_IDLE`). ### Sous Windows `Quarel-Identite-Setup-.exe` (à télécharger depuis la [page d’accueil](/#heberger)) installe le service avec une icône (violette) près de l'horloge et sa page d'administration sur `http://127.0.0.1:8081` (données dans `%LOCALAPPDATA%\Quarel\Identite`). Les prérequis restent les mêmes : nom de domaine, port 443 vers la machine (Let's Encrypt, à choisir dans les réglages), SMTP. Convient à une petite instance (association, famille) sur un PC allumé en permanence. ## Relais d'appels Les appels entre amis sont pair à pair : le son ne passe par aucun serveur Quarel. Quand aucun chemin direct n'existe (NAT stricts), le relais TURN intégré au service transmet le flux, **toujours chiffré de bout en bout** (il ne peut pas l'écouter). Les identifiants du relais sont temporaires et propres à chaque compte ; il refuse de relayer vers des adresses privées ou locales (il ne peut pas servir à atteindre votre réseau). Chaque utilisateur peut refuser le relais dans son client. Avec Docker, la plage de ports du relais doit être publiée telle quelle (voir `compose.yaml`) ; ne l'élargissez pas trop (chaque port ouvert est une ligne de règle NAT pour Docker). ## Sauvegardes Le volume `identity-data` contient **la base** (`identity.db`), **la clé de signature** (`signing.key`) et les fichiers chiffrés des conversations. Perdre la clé invalide les jetons en cours ; la voir volée permettrait d'usurper n'importe quel compte de votre service. La sauvegarde intégrée fonctionne service en marche : ```sh docker compose exec -T identity /quarel-identity backup - > identity-$(date +%F).tar.gz ``` Restauration (service arrêté ; les données présentes sont mises de côté, jamais effacées) : ```sh docker compose stop identity docker compose run --rm -T identity restore - --force < identity-2026-09-24.tar.gz docker compose start identity ``` Gardez les sauvegardes chiffrées, hors de la machine. ## Outils de l'opérateur Ils s'exécutent sur la machine, jamais à distance, et chaque action est consignée : ```sh docker compose exec identity /quarel-identity admin help docker compose exec identity /quarel-identity admin disable --reason "réquisition n°…" --by "Nom" docker compose exec identity /quarel-identity admin enable --reason "…" --by "Nom" docker compose exec identity /quarel-identity admin log ``` **Supprimer son compte** (par la personne, dans l'application) efface tout sur le service ; son empreinte est publiée 400 jours dans la même liste (`deleted_accounts`) pour que les serveurs communautaires remplacent son nom par « Ancien compte ». **Exporter ses données** : `GET /v1/me/export` (dans l'application : Paramètres › Confidentialité), sans aucun secret. **Notifications de l'application web** (Web Push) : le service n'envoie de réveil qu'aux services de notification des navigateurs (Google FCM, Mozilla, Apple, Microsoft), sur le port 443. `QUAREL_PUSH_HOSTS` en ajoute d'autres (noms séparés par des virgules), pour des tests ou un navigateur particulier. **Désactiver un compte** ne se fait que sur ordre juridique : la personne ne peut plus se connecter ni obtenir de jeton, ses connexions ouvertes sont fermées, et les serveurs communautaires l'apprennent sous 10 minutes (liste publique `GET /v1/disabled-accounts`). Ses données sont conservées : une réactivation la rétablit à l'identique. Le service central ne peut ni bannir d'un serveur ni lire les messages : chaque serveur modère lui-même, et les messages privés sont chiffrés de bout en bout. **Changer la clé de signature** (par précaution, ou en cas de doute sur sa confidentialité) : ```sh docker compose exec identity /quarel-identity admin rotate-signing-key --reason "rotation annuelle" --by "Nom" docker compose restart identity ``` L'ancienne clé privée est détruite ; sa clé publique reste publiée le temps que les jetons qu'elle a signés expirent (`QUAREL_TOKEN_TTL`, 12 h), si bien que personne n'est déconnecté. ## Mises à jour ```sh git pull && docker compose up -d --build ``` La base est migrée automatiquement au démarrage, après en avoir gardé une copie (`identity.db.pre-v-`). Une ancienne version refuse de démarrer sur une base plus récente. Faites tout de même une sauvegarde avant. --- # Questions fréquentes URL : https://quarel.app/wiki/utiliser/faq/ ### Quarel est-il gratuit ? Oui, et libre (Apache-2.0). Héberger un serveur ne coûte que votre matériel et votre électricité. ### Faut-il un serveur pour utiliser Quarel ? Non : il suffit d’un compte et d’un lien d’invitation vers un serveur existant. Héberger est réservé à qui veut créer sa propre communauté. ### Pourquoi ne puis-je pas créer un serveur depuis l’application ? Parce qu’un serveur Quarel tourne **chez quelqu’un** : il n’y a pas de plateforme centrale qui en crée pour vous. Voir [Héberger un serveur communautaire](/wiki/heberger/serveur-communautaire/) : une commande Docker ou un installateur Windows. ### Mon ordinateur doit-il rester allumé pour que mon serveur marche ? Oui : le serveur est sur la machine qui l’héberge. Un mini-PC ou un NAS allumé en permanence est idéal. ### L’hébergeur d’un serveur peut-il lire mes messages ? Ceux des **salons** de son serveur, oui (comme tout forum). Vos **messages privés**, non : ils sont chiffrés de bout en bout et ne passent pas par les serveurs communautaires. ### J’ai perdu mon téléphone / réinstallé mon PC, mes messages privés ont disparu ? Validez le nouvel appareil depuis un autre appareil connecté, ou utilisez votre **phrase de récupération**. Sans l’un ni l’autre, personne ne peut les déchiffrer : c’est le prix du chiffrement de bout en bout. Voir [Messages privés et appareils](/wiki/utiliser/messages-prives/). ### Pourquoi l’application web refuse-t-elle certains serveurs ? Un navigateur ne sait pas vérifier le certificat « maison » d’un serveur sans nom de domaine. Utilisez l’application de bureau, ou demandez à l’hébergeur d’activer Let’s Encrypt. ### Windows dit que l’application n’est pas reconnue. Les installateurs ne sont pas encore signés par un certificat d’éditeur (c’est payant et en cours de réflexion). « Informations complémentaires » › « Exécuter quand même ». Les mises à jour, elles, sont vérifiées par une signature propre à Quarel. ### Puis-je utiliser mon compte Discord ou rejoindre un serveur Discord ? Non : Quarel est indépendant et n’est pas compatible avec Discord. ### Existe-t-il une application mobile ? Pas encore d’application native : utilisez [app.quarel.app](https://app.quarel.app) et installez-la sur l’écran d’accueil. --- # Installer l’application URL : https://quarel.app/wiki/utiliser/installer/ Les liens de téléchargement sont sur la [page d’accueil](/#telecharger). ## Windows 1. Téléchargez **`Quarel-Setup-.exe`** (Windows 10 ou 11, 64 bits). 2. Lancez-le. L’installateur ne demande pas de droits administrateur : Quarel s’installe pour votre compte Windows, dans le dossier de votre choix. > Les installateurs ne sont pas encore signés : Windows SmartScreen affiche « Windows a protégé votre ordinateur ». Cliquez sur **Informations complémentaires**, puis **Exécuter quand même**. 3. Quarel se lance ; un raccourci est créé sur le bureau et dans le menu Démarrer. ## Linux - **AppImage** (toutes distributions, recommandé) : téléchargez `Quarel--x86_64.AppImage`, rendez-le exécutable (`chmod +x Quarel-*.AppImage` ou Propriétés › Permissions) et lancez-le. Certaines distributions demandent le paquet `libfuse2` (`libfuse2t64` sur Ubuntu 24.04 et plus). - **Paquet .deb** (Debian, Ubuntu) : `sudo apt install ./Quarel--amd64.deb`. Ce paquet ne se met pas à jour seul : l’application vous signale les nouvelles versions. ## Dans le navigateur Ouvrez [app.quarel.app](https://app.quarel.app). Sur téléphone ou dans Chrome/Edge, vous pouvez l’**installer** comme une application (menu du navigateur › « Installer » ou « Ajouter à l’écran d’accueil »). La version web ne peut rejoindre que les serveurs qui ont un nom de domaine et un certificat reconnu (Let’s Encrypt) : un navigateur ne sait pas vérifier le certificat lié à l’identité d’un serveur hébergé à la maison. L’application de bureau les rejoint tous. ## Mises à jour L’application de bureau cherche une nouvelle version au lancement puis toutes les 6 heures, la télécharge en arrière-plan et affiche **« Mise à jour prête — Redémarrer »**. Sans rien faire, elle s’installe à la prochaine fermeture. Paramètres › **À propos** affiche votre version et permet de chercher tout de suite. Chaque mise à jour est **signée** par la clé de publication de Quarel : l’application refuse tout fichier qui ne l’est pas. ## Désinstaller - Windows : Paramètres › Applications › Quarel › Désinstaller. - Linux : supprimez l’AppImage, ou `sudo apt remove quarel`. Vos données locales (clés, historique des messages privés) sont dans `%APPDATA%\quarel-client` (Windows) ou `~/.config/quarel-client` (Linux). Sans elles, vous retrouvez tout avec votre [phrase de récupération](/wiki/utiliser/messages-prives/#phrase-de-récupération) ou un autre appareil validé. ## Fermer ou réduire Sous Windows, la croix **cache Quarel près de l’horloge** (zone de notification) : messages, notifications et appels continuent d’arriver ; un clic sur l’icône rouvre la fenêtre, et **Quitter Quarel** dans son menu la ferme vraiment. Réglage : Paramètres › À propos › « Réduire dans la zone de notification à la fermeture » (désactivé par défaut sous Linux). Les **mises à jour** se téléchargent seules ; « Redémarrer » (ou la prochaine fermeture) les installe sans fenêtre d’installation, puis Quarel se rouvre. --- # Messages privés et appareils URL : https://quarel.app/wiki/utiliser/messages-prives/ Les messages privés (en tête à tête ou en groupe jusqu’à 10 personnes) sont **chiffrés de bout en bout** : seuls les appareils des participant·es peuvent les lire. La mention « Chiffré de bout en bout » l’indique en haut de chaque conversation. ## Écrire - Messages privés › choisissez un·e ami·e, ou **Nouveau groupe**. - Vous voyez **Envoyé**, **Distribué** puis **Vu** (si la personne a laissé les accusés de lecture), et « … écrit ». - Fichiers : trombone ou glisser-déposer (100 Mo au plus). Ils sont chiffrés sur votre appareil et envoyés en direct aux appareils en ligne ; les autres les récupèrent chiffrés plus tard. - Paramètres › Confidentialité : désactiver « … écrit » et les accusés de lecture. - **Messages éphémères** : l’horloge en haut de la conversation règle la durée de vie des **prochains** messages (5 minutes, 1 heure, 1 jour, 7 jours ou désactivés), pour tout le monde. N’importe quel membre peut la changer ; le changement s’affiche dans la conversation. Passé ce délai, chaque appareil efface le message et son fichier. Cela protège si un appareil est perdu ou saisi, pas contre la personne qui les reçoit : elle peut toujours faire une capture d’écran. Les messages éphémères ne sont jamais sauvegardés (ni dans la sauvegarde liée à votre phrase de récupération, ni dans l’historique envoyé à un nouvel appareil) et leurs notifications n’en montrent pas le texte. ## Notifications sur téléphone L’application web installée (app.quarel.app, « Installer l’application » dans les paramètres) peut vous prévenir même fermée : Paramètres › Notifications › **Même quand l’application est fermée**. Votre service d’identité envoie alors un simple réveil, **sans contenu ni expéditeur**, par le service de notifications de votre navigateur (Google, Mozilla, Apple…), qui ne peut donc rien lire ; la notification dit seulement que du nouveau vous attend. Cela concerne les messages privés et les appels, pas encore les mentions sur les serveurs. ## Ajouter un appareil Votre historique n’est **pas** stocké en clair sur un serveur : un nouvel appareil (autre ordinateur, navigateur) doit être **validé**. 1. Connectez-vous sur le nouvel appareil : il affiche un **code** (`XXXX-XXXX-XXXX-XXXX`). 2. Sur un appareil déjà validé, un bandeau signale l’appareil en attente (ou Paramètres › Appareils). Vérifiez que le code est **le même** sur les deux écrans, puis validez. 3. Le nouvel appareil reçoit vos clés, votre historique et la liste de vos serveurs. Ne validez jamais un appareil que vous ne reconnaissez pas : il pourrait lire vos messages. ## Phrase de récupération Douze mots qui chiffrent une sauvegarde de vos clés et de votre historique. Créez-la dans le bandeau de Messages privés ou Paramètres › **Récupération** ; elle ne s’affiche **qu’une fois** : notez-la sur papier, hors ligne. Si vous n’avez plus aucun appareil validé, connectez-vous sur un nouvel appareil, choisissez de restaurer avec la phrase, saisissez les 12 mots puis **Restaurer** : tout revient (historique, contacts, serveurs). Sans phrase ni appareil validé, vos anciens messages privés sont **perdus** — personne, même pas nous, ne peut les déchiffrer. **Tout perdu** (appareils validés et phrase) ? Dans le bandeau de l’appareil non validé, « J’ai tout perdu » repart avec de nouvelles clés (mot de passe et double authentification demandés). Vos anciens messages restent illisibles, vos contacts sont prévenus que votre clé a changé. ## Code de sécurité Dans une conversation en tête à tête, le bouton **bouclier** affiche un code de sécurité (`XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`). Votre contact voit **le même code** si vos deux applications détiennent les vraies clés l’une de l’autre — et non des clés substituées par un service compromis. Comparez-le de vive voix ou par téléphone, puis « Les codes correspondent » : la conversation affiche **Vérifié**. ## Avertissement de sécurité Si les clés d’un contact changent, l’application **refuse d’envoyer** et vous prévient. C’est normal si la personne a réinitialisé ses clés ; sinon, quelqu’un tente peut-être de se faire passer pour elle. Comparez le **nouveau** code de sécurité avec elle avant d’accepter sa nouvelle clé. Dans un groupe, l’application ne chiffre que pour les membres qu’elle connaissait déjà et ceux qu’un membre a **annoncés** en les ajoutant (« alice a ajouté carol au groupe »). Une personne apparue dans la liste sans annonce ne reçoit rien, et l’application vous le signale. --- # Personnaliser Quarel URL : https://quarel.app/wiki/utiliser/personnaliser/ Quarel se personnalise à quatre niveaux : | Quoi | Qui le choisit | Qui le voit | Où | |---|---|---|---| | **Mon CSS** | vous | vous seul·e, sur cet appareil | Paramètres › Apparence | | **Thème d’un serveur** | les personnes qui peuvent « Gérer le serveur » | ses membres, sur ce serveur | Paramètres du serveur › Apparence | | **Carte de profil** | vous | les personnes qui cliquent sur vous | Paramètres › Profil › Carte de profil | | **Profil sur un serveur** | vous | les membres de ce serveur | menu du serveur › Mon profil sur ce serveur | ## Mon CSS Paramètres › **Apparence** › **Mon CSS** : collez du CSS, puis **Appliquer**. Il s’applique à toute l’application, **sur cet appareil seulement** (l’application de bureau et la version web ont chacune le leur), **sans aucun filtre**. N’y collez que du CSS que vous comprenez. Les couleurs de l’application sont des variables : changez-les sur `:root`. ```css :root { --bg: #101418; /* fond principal */ --bg-1: #151a20; /* colonnes */ --bg-2: #1b2129; /* cartes, fenêtres */ --bg-3: #242c36; /* champs, boutons */ --text: #eef1f4; --accent: #f08a4b; /* couleur d’accent */ --accent-text: #f6b58c; --font: Georgia, serif; } .msg { border-radius: 10px; } ``` ### Mode sans échec L’application devient illisible à cause d’un CSS ? Appuyez sur **Ctrl + Maj + 0** : plus aucun CSS personnalisé (ni le vôtre, ni ceux des serveurs) jusqu’au prochain lancement. Un bandeau le signale, avec « Réactiver ». Vous pouvez aussi lancer l’application de bureau avec `--safe-mode`, ou ajouter `?safe` à l’adresse de la version web. ## Le thème d’un serveur Dans Paramètres du serveur › **Apparence** (il faut « Gérer le serveur ») : - **couleurs** de l’application (fonds, texte, accent…) ; - **dégradé** et **image de fond** (envoyée au serveur, jamais chargée depuis un autre site) ; - **police**, parmi celles de l’application ; - **CSS**, filtré (voir plus bas). Le thème s’applique à la **zone du serveur** : liste des salons, messages, liste des membres, vocal. Il ne touche jamais la liste des serveurs, votre barre en bas à gauche, les paramètres ni les fenêtres (confirmations, modération…). Chaque membre choisit ce qu’il voit : - **Le thème d’un serveur passe avant mon CSS** (coché par défaut). Décoché, c’est votre CSS qui l’emporte : les couleurs que vous définissez restent les vôtres, même sur un serveur à thème. - **Afficher les thèmes des serveurs et des profils** : décoché, vous ne voyez plus aucun thème des autres. - **Animations des thèmes** : décoché, aucun thème ne peut rien animer. - Pour **un seul serveur** : menu du serveur › **Ignorer le thème de ce serveur**. ## Cartes de profil Un clic sur une personne (liste des membres, nom ou image d’un message) ouvre sa **carte** : bannière, image, nom, rôles, présentation, dans le thème qu’elle a choisi. Clic droit › **Voir le profil** fait pareil. - **Votre carte** : Paramètres › Profil › **Carte de profil** (bannière, couleurs, dégradé, police, CSS), avec un aperçu. C’est celle que voient vos amis, et les membres des serveurs où vous n’avez pas de profil propre. - **Votre profil sur un serveur** : menu du serveur › **Mon profil sur ce serveur**. Surnom, présentation, image, bannière et thème de carte **propres à ce serveur**. Ce que vous laissez vide reprend votre profil habituel. La modération d’un serveur (« Exclure temporairement ») peut **réinitialiser** le profil de quelqu’un sur ce serveur : clic droit › Réinitialiser son profil ici. Son profil habituel reste affiché. ## Ce que le CSS des autres ne peut pas faire Le CSS d’un serveur ou d’une carte est **filtré par votre application** avant d’être appliqué. Un serveur malveillant ne peut donc pas s’en servir contre vous : - **rien n’est chargé depuis un autre site** : ni `url()`, ni `@import`, ni police externe. Une simple image extérieure suffirait à révéler votre adresse IP ; - **pas de faux texte ni de faux boutons** : ni `content`, ni `position`, ni `z-index`, ni `transform`, ni `pointer-events` ; - **rien hors de sa zone** : la zone du serveur ou la carte, jamais le reste de l’application ; - pas de `!important` (vos réglages gardent le dernier mot), ni d’échappements (`\`), et 16 Ko au plus. L’éditeur du thème liste ce qui sera ignoré avant même d’enregistrer. --- # Premiers pas URL : https://quarel.app/wiki/utiliser/premiers-pas/ ## Créer un compte 1. Ouvrez l’application (ou [app.quarel.app](https://app.quarel.app)) et choisissez **Créer un compte**. 2. Service d’identité : laissez `identity.quarel.app` (le service officiel), ou indiquez celui de votre association si elle a le sien. 3. Email, pseudo, mot de passe — et, pendant la phase de test, le **code d’invitation** qu’on vous a donné. 4. Saisissez le code à 6 chiffres reçu par email. Vous êtes connecté·e. Votre identifiant complet est `pseudo@identity.quarel.app`. Le pseudo peut changer (une fois par jour) : vos serveurs vous reconnaissent quand même. :::tip[Protégez votre compte] Dans **Paramètres › Sécurité**, activez la **double authentification** et gardez les codes de secours. Puis créez votre **phrase de récupération** (bandeau de Messages privés ou Paramètres › Récupération) : c’est elle qui vous rendra vos messages privés si vous perdez vos appareils. ::: ### Clé d’accès (facultatif) Une fois la double authentification activée, Paramètres › Sécurité › **Clés d’accès** › **Ajouter une clé** : une page de votre service d’identité s’ouvre dans le navigateur pour enregistrer une clé de sécurité, Windows Hello ou votre téléphone. À la connexion, **Utiliser une clé d’accès** remplace alors le code à 6 chiffres. Les codes de secours restent valables. ## Rejoindre un serveur 1. On vous envoie un **lien d’invitation** (`https://app.quarel.app/join#…` ou `quarel://…`). 2. Cliquez dessus : il ouvre l’application de bureau, ou la version web. Sinon, dans l’application, bouton **+** (« Ajouter un serveur ») à gauche, puis collez le lien. 3. L’application vérifie le serveur et affiche son nom : **Rejoindre**. Certains serveurs demandent d’accepter leurs **règles**, ou de vérifier un **numéro de téléphone** par SMS (le serveur ne garde qu’une empreinte du numéro). Vos serveurs vous suivent sur tous vos appareils validés. ## Inviter quelqu’un Menu du serveur (son nom, en haut) › **Inviter des personnes** : vos amis sont listés, **Inviter** leur envoie en message privé une invitation valable pour une personne. Ou copiez le lien affiché (7 jours) pour quelqu’un d’autre. Un lien d’invitation reçu dans un message s’affiche en carte avec **Rejoindre** (ou **Ouvrir** si vous êtes déjà membre). ## Se repérer - **Colonne de gauche** : vos serveurs ; en haut, l’icône **Messages privés** (amis et conversations). - **Salons** d’un serveur : textuels (`#`), vocaux (haut-parleur), regroupés en catégories. Un clic sur un salon vocal vous y connecte. - **Barre du bas** : votre nom (clic : statut en ligne, absent, ne pas déranger, invisible), et **Paramètres**. - Sur un message : répondre, réagir, créer un fil, épingler (selon vos droits), modifier ou supprimer les vôtres. - **Fils** : sans message pendant une semaine, un fil est **archivé** (il disparaît de la liste des salons) ; on le retrouve par le lien sous son message de départ, et y écrire le rouvre. Les gestionnaires des salons le renomment ou le suppriment (roue dentée ou clic droit). - En tête de salon : **recherche**, messages épinglés, **cloche** des notifications (tous les messages, @mentions seulement, rien, sourdine). ## Forums Un salon **forum** rassemble des posts : chacun a un titre et sa propre discussion (**Nouveau post**). Les posts les plus actifs remontent en tête. Les gestionnaires des salons en créent avec « Créer un salon » › type **Forum**. ## Mettre en forme Dans les salons comme dans les messages privés : `**gras**`, `*italique*`, `__souligné__`, `~~barré~~`, `` `code` ``, `||divulgâcheur||` (caché jusqu’au clic) ; en début de ligne, `# Titre` (aussi `##`, `###`), `> citation`, `- liste` ou `1. liste numérotée` ; les blocs de code entre trois accents graves, avec le langage après les premiers (` ```js `). Les liens s’affichent toujours avec leur vraie adresse. **Emojis du serveur** : tapez `:` puis le début de leur nom (Tab ou clic pour choisir) ; ils sont aussi proposés pour réagir. Les gestionnaires du serveur les ajoutent dans Paramètres du serveur › **Emojis**. ## Clic droit Un **clic droit** ouvre les actions de ce qui est sous le pointeur : - sur une personne (liste des membres, salon vocal, appel) : son **volume pour vous** (jusqu’à 200 %) ou « Rendre muet pour moi » — gardés sur cet appareil, pour cette personne partout —, message privé, demande d’ami, et la modération que vos droits permettent (micro, son, exclusion, expulsion…) ; - sur un message : réagir, répondre, modifier, épingler, créer un fil, copier, supprimer ; - sur un salon ou un fil : marquer comme lu, rejoindre le vocal, modifier, renommer, supprimer. Les suppressions et autres actions importantes demandent toujours une confirmation dans une fenêtre de l’application. ## Ajouter des amis Messages privés › **Amis** › **Ajouter un ami** : tapez son pseudo. Dès qu’elle accepte, vous pouvez lui écrire et l’appeler. Les amis doivent avoir un compte sur le **même service d’identité** que vous. Paramètres › Confidentialité › **Qui peut vous demander en ami** : tout le monde, les amis de vos amis et les membres de vos groupes, ou personne. Une demande que vous avez envoyée peut toujours être acceptée. Vous pouvez **bloquer** quelqu’un depuis la liste d’amis ou Paramètres › Confidentialité : ses messages sont aussi masqués sur les serveurs communautaires. --- # Vocal et appels URL : https://quarel.app/wiki/utiliser/vocal-et-appels/ ## Salons vocaux - **Cliquez sur un salon vocal** pour le rejoindre. La barre « Vocal connecté » reste visible en bas, même quand vous changez de salon ou de serveur. - Commandes : **micro**, **sourdine** (vous n’entendez plus et votre micro se coupe), **caméra**, **partage d’écran** (un écran ou une fenêtre ; sous Windows, avec le son du système), **quitter**. - Qui parle s’entoure de vert ; un micro coupé par la modération apparaît en rouge. - Vous n’êtes que dans un salon vocal à la fois. Les modérateurs peuvent couper votre micro ou votre son, vous déplacer ou vous déconnecter. Le son et la vidéo vont directement au serveur vocal du serveur communautaire, jamais par un service central. ## Scènes Un salon vocal peut être une **scène** (conférence, soirée quiz…) : case « Scène » dans les réglages du salon. En arrivant, vous êtes dans le **public** : vous écoutez. **Lever la main** demande la parole ; les personnes qui peuvent couper le micro des autres dans ce salon parlent librement et **invitent à parler** (ou renvoient dans le public). « Quitter la scène » vous ramène dans le public ; en partant du salon, vous y revenez aussi. ## Appels entre amis - Dans une conversation en tête à tête avec un·e ami·e : bouton **Appeler**. La sonnerie retentit sur tous ses appareils ; le premier qui répond prend l’appel. - Pendant l’appel : micro, caméra, **partage d’écran** (un écran ou une fenêtre, les deux personnes peuvent partager en même temps ; sous Windows, avec le son du système ; il faut que l’autre personne ait Quarel 0.4.0 ou plus récent), raccrocher. La barre d’appel indique la durée et le **chemin** : réseau local, pair à pair ou relais. - En statut « Ne pas déranger », vous ne recevez ni sonnerie ni notification. ### Appels de groupe - Dans un groupe de messages privés : bouton **Appeler le groupe**. Les autres membres reçoivent une sonnerie (« Rejoindre » ou « Ignorer »). - Tant qu’un appel est en cours, le groupe affiche **Rejoindre l’appel** avec le nombre de participant·es : on peut partir et revenir. - **6 personnes au plus** : chaque participant·e envoie son son et sa vidéo directement à chacun·e des autres (aucun serveur ne voit le flux), ce qui demande plus de débit montant qu’un appel à deux. - Micro, caméra et partage d’écran comme pour un appel à deux. Il faut Quarel 0.4.0 ou plus récent. Les appels sont **pair à pair et chiffrés**. Quand aucun chemin direct n’existe, le relais de votre service d’identité transmet le flux chiffré. Une connexion directe montre votre **adresse IP** à l’autre appareil. Paramètres › Voix et vidéo › « Qui peut voir mon adresse IP » : - **Mes amis seulement** (par défaut) : direct avec vos amis ; avec les membres d’un groupe qui ne sont pas vos amis, par le relais (et, pour les fichiers des messages privés, par la copie chiffrée du service). - **Personne** : toujours par le relais (l’appel échoue si votre service n’en a pas). - **Tout le monde** : jamais de relais (certains appels échoueront, derrière certaines box ou réseaux d’entreprise). Le chemin de chaque personne s’affiche pendant l’appel (en direct, réseau local, relais). ## Micro, haut-parleurs, caméra Paramètres › **Voix et vidéo** : choisir les périphériques (appliqué en direct, même en plein appel), tester le micro (vu-mètre), jouer un son de test, prévisualiser la caméra. Dans le navigateur, le micro et la caméra demandent votre autorisation la première fois. ## Qualité de la connexion Des **barres de signal** indiquent le temps d’aller-retour (ping) : à gauche de « Vocal connecté » vers le serveur vocal, dans la barre d’appel et sur la tuile de chaque participant·e d’un appel. Quatre barres sous 60 ms, trois sous 120, deux sous 200, une sous 300, rouge au-delà ; la valeur exacte s’affiche au survol.