État actuel : ElSigm fonctionne en mode passerelle
À lire avant toute configuration
ElSigm reçoit aujourd'hui ses interactions par la passerelle WebSocket de Discord, au moyen d'une connexion permanente sortante établie par la bibliothèque discord.py. Dans cette architecture, le champ Interactions Endpoint URL du portail développeur doit rester vide. Y inscrire une adresse alors qu'aucun serveur HTTP n'écoute derrière entraînerait l'échec de la validation par Discord et, en cas de validation forcée, la rupture complète du traitement des commandes.
Cette page conserve néanmoins toute son utilité. Elle documente le mécanisme dans son intégralité, pour trois raisons.
D'abord parce qu'elle constitue la documentation de référence à laquelle renvoyer si le champ venait à être renseigné un jour, notamment lors d'une migration vers une architecture sans état.
Ensuite parce qu'elle permet de répondre aux questions légitimes que se posent les administrateurs et les auditeurs sur la manière dont le bot reçoit et traite les commandes.
Enfin parce que le modèle HTTP présente des avantages réels pour certaines évolutions envisageables : exécution sans processus permanent, montée en charge horizontale, hébergement sur des plateformes de fonctions serverless.
Comparaison des deux modèles
| Critère | Passerelle WebSocket actuel | Point de terminaison HTTP |
|---|---|---|
| Sens de la connexion | Sortante, du bot vers Discord | Entrante, de Discord vers le bot |
| Adresse publique requise | Non | Oui, avec certificat TLS valide |
| Processus permanent | Requis | Non requis |
| Événements reçus | Tous : messages, membres, réactions, présences | Interactions uniquement |
| Réseau InterPub possible | Oui | Non — les messages ne sont pas transmis |
| Tâches de fond périodiques | Oui | Nécessitent un ordonnanceur externe |
| Vérification de signature | Non applicable | Obligatoire, Ed25519 |
| Sensibilité aux attaques réseau | Faible, aucun port exposé | Réelle, surface exposée à Internet |
| Coût d'hébergement au repos | Continu | Nul en l'absence de trafic |
| Montée en charge | Par fragmentation | Horizontale naturelle |
Incompatibilité structurelle avec le réseau InterPub
Le cœur fonctionnel d'ElSigm repose sur la lecture des messages publiés dans les salons InterPub. Or le point de terminaison HTTP ne reçoit que les interactions : commandes en barre oblique, clics sur boutons, soumissions de formulaires, sélections de menus. Il ne reçoit jamais les événements de message, d'arrivée de membre ou de réaction. Une migration complète vers le modèle HTTP supprimerait donc purement et simplement le réseau InterPub, le mode absent, la détection des mentions et l'ensemble des tâches périodiques. Une architecture hybride — passerelle pour les événements, HTTP pour les interactions — est techniquement possible mais notablement plus complexe à opérer.
Définition et rôle du point de terminaison
Le point de terminaison des interactions désigne une adresse HTTPS publique que vous déclarez auprès de Discord et vers laquelle la plateforme envoie une requête POST chaque fois qu'un utilisateur interagit avec votre application.
Dans ce modèle, votre application n'a pas besoin de maintenir une connexion permanente. Elle se comporte comme un serveur web ordinaire : elle attend, reçoit une requête, la vérifie, la traite et répond.
Ce que le point de terminaison reçoit
- Les commandes en barre oblique —
/help,/ping,/profil,/config_interpubet l'ensemble des commandes de l'application. - Les commandes contextuelles déclenchées depuis le menu d'un message ou d'un utilisateur.
- Les clics sur composants — boutons d'acceptation ou de refus d'une annonce, boutons de signalement, bouton de participation à un tirage au sort, boutons de pagination.
- Les sélections dans un menu déroulant.
- Les soumissions de formulaires modaux — configuration d'une annonce Premium, rédaction d'une suggestion, saisie d'un identifiant dans le panneau de vérification.
- Les requêtes d'autocomplétion émises pendant la frappe d'un paramètre de commande.
- Les requêtes de validation de type PING, décrites plus bas.
Ce que le point de terminaison ne reçoit jamais
- Les messages publiés dans un salon.
- Les arrivées, départs et mises à jour de membres.
- Les ajouts et retraits de réactions.
- Les changements de présence ou de statut.
- Les créations, modifications et suppressions de salons ou de rôles.
- Les événements vocaux.
Formulation simple
La passerelle est un flux permanent qui vous apporte tout ce qui se passe. Le point de terminaison est une boîte aux lettres qui reçoit uniquement ce qu'un utilisateur déclenche volontairement en interagissant avec votre application.
Prérequis techniques
Un point de terminaison ne peut être validé par Discord que si l'ensemble des conditions suivantes est réuni.
| Exigence | Détail | Conséquence en cas de manquement |
|---|---|---|
| Protocole HTTPS | Le protocole HTTP simple est refusé, sans exception | Validation impossible |
| Certificat TLS valide | Émis par une autorité reconnue, non expiré, chaîne complète | Validation impossible |
| Accessibilité publique | Aucun pare-feu, aucun réseau privé, aucune authentification préalable | Discord ne peut pas joindre l'adresse |
| Méthode POST acceptée | La route doit accepter POST avec un corps JSON | Erreur 405 lors de la validation |
| Absence de redirection | Aucun code 301, 302, 307 ou 308 sur la route | Discord ne suit pas les redirections |
| Vérification de signature | Contrôle Ed25519 obligatoire sur chaque requête | Validation refusée par Discord |
| Rejet des signatures invalides | Réponse 401 obligatoire, jamais 200 ni 400 | Validation refusée par Discord |
| Réponse au PING | Corps {"type": 1} avec un code 200 | Validation refusée |
| Latence de réponse | Trois secondes au maximum | Interaction perdue, message d'échec côté utilisateur |
| Accès au corps brut | Le corps doit être lisible avant toute désérialisation | Signature systématiquement invalide |
| Stabilité | Le point de terminaison doit rester joignable en permanence | Discord peut désactiver l'application après échecs répétés |
Le piège du corps désérialisé
La signature Ed25519 porte sur les octets exacts du corps de la requête. De nombreux cadriciels web désérialisent automatiquement le JSON avant que votre code n'y accède ; si vous re-sérialisez ensuite l'objet pour vérifier la signature, l'ordre des clés, les espaces et l'échappement des caractères diffèrent, et la vérification échoue systématiquement. Vous devez impérativement conserver le corps brut. C'est de très loin l'erreur la plus fréquente lors de la mise en place d'un point de terminaison.
Vérification de la signature Ed25519
Chaque requête envoyée par Discord est signée cryptographiquement. Cette signature permet de garantir que la requête provient bien de Discord et n'a pas été altérée en transit. Sa vérification est obligatoire et constitue le seul rempart contre l'envoi de fausses interactions par un tiers.
En-têtes transmis
| En-tête | Contenu | Usage |
|---|---|---|
X-Signature-Ed25519 | Signature hexadécimale de 128 caractères | Signature à vérifier |
X-Signature-Timestamp | Horodatage Unix en secondes | Préfixe du message signé, protection anti-rejeu |
Content-Type | application/json | Format du corps |
User-Agent | Chaîne identifiant Discord | Information, ne doit pas servir de contrôle d'accès |
Message signé
Le message effectivement signé est la concaténation, dans cet ordre exact et sans séparateur, de l'horodatage puis du corps brut de la requête :
message_signe = X-Signature-Timestamp + corps_brut
La vérification s'effectue au moyen de la clé publique de l'application, disponible dans l'onglet General Information du portail développeur sous l'intitulé Public Key. Cette clé est publique par nature : sa divulgation ne présente aucun risque, contrairement au jeton du bot et au secret d'application.
Comportement attendu en cas d'échec
Toute requête dont la signature est invalide, absente ou malformée doit recevoir une réponse 401 Unauthorized. Discord teste explicitement ce comportement lors de la validation en envoyant délibérément des requêtes mal signées. Répondre 200, 400 ou 403 fait échouer la validation.
Implémentation en Python avec PyNaCl
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError
PUBLIC_KEY = "VOTRE_CLE_PUBLIQUE_HEXADECIMALE" # portail → General Information
_verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY))
def signature_valide(signature: str, timestamp: str, corps_brut: bytes) -> bool:
"""Vérifie la signature Ed25519 d'une requête Discord."""
if not signature or not timestamp:
return False
try:
_verify_key.verify(
timestamp.encode() + corps_brut,
bytes.fromhex(signature),
)
return True
except (BadSignatureError, ValueError):
return False
Implémentation en JavaScript avec tweetnacl
import nacl from 'tweetnacl';
const PUBLIC_KEY = process.env.DISCORD_PUBLIC_KEY;
export function signatureValide(signature, timestamp, corpsBrut) {
if (!signature || !timestamp) return false;
try {
return nacl.sign.detached.verify(
Buffer.concat([Buffer.from(timestamp, 'utf8'), corpsBrut]),
Buffer.from(signature, 'hex'),
Buffer.from(PUBLIC_KEY, 'hex'),
);
} catch {
return false;
}
}
Protection contre le rejeu
L'horodatage permet de rejeter les requêtes trop anciennes. Une fenêtre de tolérance de cinq minutes est un choix raisonnable : elle absorbe les dérives d'horloge légitimes tout en limitant la fenêtre d'exploitation d'une requête interceptée.
import time
FENETRE_TOLERANCE = 300 # cinq minutes
def horodatage_acceptable(timestamp: str) -> bool:
try:
return abs(time.time() - int(timestamp)) <= FENETRE_TOLERANCE
except (TypeError, ValueError):
return False
Comparaison en temps constant
Les bibliothèques Ed25519 sérieuses effectuent leurs comparaisons en temps constant. N'écrivez jamais votre propre comparaison de signatures avec un opérateur d'égalité classique : le temps d'exécution variable révélerait de l'information exploitable par une attaque temporelle.
Protocole de validation : PING et PONG
Lorsque vous enregistrez une adresse dans le champ Interactions Endpoint URL, Discord procède immédiatement à une séquence de validation. Cette séquence doit réussir intégralement, faute de quoi l'enregistrement est refusé.
Séquence exécutée par Discord
- Requête PING correctement signée
Discord envoie une requête
POSTdont le corps est{"type": 1}, accompagnée d'une signature valide. Votre serveur doit répondre200avec le corps{"type": 1}. - Requête à signature invalide
Discord envoie une requête délibérément mal signée. Votre serveur doit répondre
401. Toute autre réponse fait échouer la validation. - Requête à en-têtes manquants
Discord peut omettre les en-têtes de signature. Votre serveur doit également répondre
401. - Contrôle du délai
Les réponses doivent parvenir dans le délai imparti. Un serveur trop lent échoue à la validation.
Échange nominal
--- Requête entrante ---
POST /api/interactions HTTP/1.1
Host: votre-domaine.tld
Content-Type: application/json
X-Signature-Ed25519: 4f8e2a...c91d
X-Signature-Timestamp: 1786377600
{"type": 1}
--- Réponse attendue ---
HTTP/1.1 200 OK
Content-Type: application/json
{"type": 1}
Échange en cas de signature invalide
--- Requête entrante ---
POST /api/interactions HTTP/1.1
X-Signature-Ed25519: 0000000000000000...0000
X-Signature-Timestamp: 1786377600
{"type": 1}
--- Réponse attendue ---
HTTP/1.1 401 Unauthorized
Content-Type: text/plain
invalid request signature
Revalidation périodique
Discord revérifie périodiquement la disponibilité du point de terminaison. En cas d'indisponibilité prolongée ou d'échecs répétés, la plateforme peut désactiver l'adresse enregistrée, ce qui interrompt le traitement de toutes les interactions jusqu'à correction et réenregistrement manuel.
Typologie des interactions reçues
Le champ type du corps de la requête indique la nature de l'interaction.
| Valeur | Nom | Déclencheur | Réponse attendue |
|---|---|---|---|
1 | PING | Validation par Discord | Type 1 (PONG) |
2 | APPLICATION_COMMAND | Commande en barre oblique ou contextuelle | Type 4 ou 5 |
3 | MESSAGE_COMPONENT | Clic sur bouton ou sélection dans un menu | Type 4, 5, 6, 7 ou 9 |
4 | APPLICATION_COMMAND_AUTOCOMPLETE | Frappe dans un paramètre à autocomplétion | Type 8 |
5 | MODAL_SUBMIT | Envoi d'un formulaire modal | Type 4, 5, 6 ou 7 |
Structure d'une interaction de commande
{
"id": "1398075278592311417",
"application_id": "1361056395524313158",
"type": 2,
"token": "jeton_opaque_valable_15_minutes",
"version": 1,
"guild_id": "1361756362933010586",
"channel_id": "1363113136965812426",
"member": {
"user": {
"id": "781287178743447552",
"username": "exemple",
"global_name": "Exemple",
"avatar": "a1b2c3d4e5f6"
},
"roles": ["967844785983479848"],
"permissions": "2147483647",
"joined_at": "2026-01-15T10:00:00.000000+00:00"
},
"data": {
"id": "1398075278592311418",
"name": "profil",
"type": 1,
"options": [
{ "name": "membre", "type": 6, "value": "781287178743447552" }
]
},
"locale": "fr",
"guild_locale": "fr"
}
Structure d'une interaction de composant
{
"type": 3,
"id": "…",
"token": "…",
"data": {
"custom_id": "gw_join",
"component_type": 2
},
"message": { "id": "…", "content": "…" },
"member": { "user": { "id": "781287178743447552" } }
}
Le champ custom_id est l'identifiant que votre application a attribué au composant lors de sa création. Dans ElSigm, ces identifiants suivent des conventions explicites : gw_join pour la participation à un tirage au sort, rp_report pour le signalement d'une annonce, rp_sb pour le signalement d'un selfbot, sb_yes et sb_no pour la qualification d'un selfbot, deban_btn pour le déblocage d'un utilisateur, confirm_<identifiant> pour l'accusé de réception du message de bienvenue.
Structure d'une soumission de formulaire
{
"type": 5,
"data": {
"custom_id": "config_pub_modal",
"components": [
{
"type": 1,
"components": [
{ "type": 4, "custom_id": "title_inp", "value": "Rejoignez-nous" }
]
},
{
"type": 1,
"components": [
{ "type": 4, "custom_id": "desc_inp", "value": "Description de l'annonce…" }
]
}
]
}
}
Typologie des réponses possibles
La réponse à une interaction est un objet JSON comportant obligatoirement un champ type et, selon les cas, un champ data.
| Type | Nom | Effet | Cas d'usage dans ElSigm |
|---|---|---|---|
1 | PONG | Réponse au PING de validation | Validation du point de terminaison |
4 | CHANNEL_MESSAGE_WITH_SOURCE | Envoie un message immédiat | /help, /stats, /profil |
5 | DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE | Affiche « réfléchit… », réponse ultérieure | /meme, qui interroge une interface externe |
6 | DEFERRED_UPDATE_MESSAGE | Accuse réception sans modification visible | Progression dans le jeu Simon |
7 | UPDATE_MESSAGE | Modifie le message portant le composant | Pagination du panneau de vérification |
8 | APPLICATION_COMMAND_AUTOCOMPLETE_RESULT | Renvoie des suggestions de saisie | Non utilisé actuellement |
9 | MODAL | Ouvre un formulaire modal | /config_pub, /suggestion, saisie d'identifiant |
10 | PREMIUM_REQUIRED | Invite à souscrire une offre payante | Non utilisé, le bot étant gratuit |
12 | LAUNCH_ACTIVITY | Lance une activité intégrée | Non utilisé |
Réponse immédiate simple
{
"type": 4,
"data": {
"content": "🏓 Pong ! Latence : 42 ms",
"flags": 64
}
}
L'indicateur 64 correspond au caractère éphémère : le message n'est visible que par la personne ayant déclenché l'interaction. ElSigm l'utilise systématiquement pour les réponses contenant des données personnelles — notes, avertissements, configuration Premium, panneau de vérification.
Réponse enrichie avec composants
{
"type": 4,
"data": {
"embeds": [{
"title": "📘 Commandes disponibles",
"description": "Liste des commandes d'ElSigm.",
"color": 3447003,
"fields": [
{ "name": "🔧 Configuration", "value": "`/config_interpub`\n`/config_pub`", "inline": false }
],
"footer": { "text": "ElSigm • Interpublicité intelligente" }
}],
"components": [{
"type": 1,
"components": [
{ "type": 2, "style": 5, "label": "💬 Support", "url": "https://discord.gg/aCszSWa8zd" },
{ "type": 2, "style": 1, "label": "🎉 Participer", "custom_id": "gw_join" }
]
}],
"flags": 64
}
}
Ouverture d'un formulaire modal
{
"type": 9,
"data": {
"custom_id": "config_pub_modal",
"title": "Configurer votre publicité Premium",
"components": [
{
"type": 1,
"components": [{
"type": 4,
"custom_id": "title_inp",
"label": "Titre",
"style": 1,
"max_length": 60,
"required": true
}]
},
{
"type": 1,
"components": [{
"type": 4,
"custom_id": "desc_inp",
"label": "Description",
"style": 2,
"max_length": 850,
"required": true
}]
}
]
}
}
Un formulaire modal ne peut pas suivre une réponse différée
L'ouverture d'un formulaire modal, de type 9, doit constituer la toute première réponse à une interaction. Il est impossible de différer d'abord puis d'ouvrir un formulaire ensuite : le formulaire ne s'affichera jamais. Si votre traitement requiert une vérification préalable lente, restructurez le flux — par exemple en ouvrant immédiatement le formulaire et en effectuant la vérification à sa soumission.
Contrainte de latence et réponses différées
Discord impose une fenêtre de trois secondes pour la réponse initiale à une interaction. Ce délai court à partir de l'émission de la requête, et non de sa réception : la latence réseau, la résolution DNS et la négociation TLS sont incluses.
Ce qui se produit en cas de dépassement
L'utilisateur voit le message « L'application n'a pas répondu ». Le jeton d'interaction devient inutilisable, et aucun rattrapage ultérieur n'est possible. L'interaction est définitivement perdue.
Stratégie de réponse différée
Lorsqu'un traitement risque de dépasser trois secondes — appel à une interface externe, lecture volumineuse, opération en boucle sur de nombreux serveurs — il faut répondre immédiatement avec un type 5 puis compléter la réponse ensuite.
# 1) accusé de réception immédiat, sous les trois secondes
{ "type": 5 }
# 2) traitement effectif, jusqu'à quinze minutes disponibles
# puis envoi du résultat via l'API :
PATCH https://discord.com/api/v10/webhooks/{application_id}/{token}/messages/@original
Content-Type: application/json
{ "content": "✅ Traitement terminé.", "embeds": [ … ] }
Fenêtres temporelles applicables
| Opération | Délai | Remarque |
|---|---|---|
| Réponse initiale | 3 secondes | Impératif absolu, sans exception |
| Validité du jeton d'interaction | 15 minutes | Pour les messages complémentaires |
| Édition de la réponse initiale | 15 minutes | Via la route @original |
| Messages complémentaires | 15 minutes | Nombre non limité dans la fenêtre |
| Suppression de la réponse initiale | 15 minutes | Méthode DELETE sur @original |
Routes complémentaires
Envoie un message complémentaire après la réponse initiale.
Récupère la réponse initiale.
Modifie la réponse initiale, notamment après un différé.
Supprime la réponse initiale.
Repère pratique appliqué à ElSigm
Dans le code actuel, plusieurs traitements dépasseraient largement la fenêtre de trois secondes en mode HTTP : la commande /meme interroge successivement jusqu'à trois espaces communautaires Reddit ; la commande /ping comporte une animation de plus de deux secondes ; la diffusion d'une annonce parcourt l'ensemble des serveurs du réseau avec une pause entre chaque envoi. Toutes exigeraient une réponse différée.
Implémentations de référence
Python — aiohttp
import os, json, time
from aiohttp import web
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError
PUBLIC_KEY = os.environ["DISCORD_PUBLIC_KEY"]
VERIFY_KEY = VerifyKey(bytes.fromhex(PUBLIC_KEY))
FENETRE = 300
def verifier(signature, timestamp, corps: bytes) -> bool:
if not signature or not timestamp:
return False
try:
if abs(time.time() - int(timestamp)) > FENETRE:
return False
VERIFY_KEY.verify(timestamp.encode() + corps, bytes.fromhex(signature))
return True
except (BadSignatureError, ValueError, TypeError):
return False
async def interactions(request: web.Request):
corps = await request.read() # corps BRUT, indispensable
signature = request.headers.get("X-Signature-Ed25519")
timestamp = request.headers.get("X-Signature-Timestamp")
if not verifier(signature, timestamp, corps):
return web.Response(status=401, text="invalid request signature")
data = json.loads(corps)
itype = data.get("type")
# ── PING de validation
if itype == 1:
return web.json_response({"type": 1})
# ── Commande en barre oblique
if itype == 2:
nom = data["data"]["name"]
if nom == "ping":
return web.json_response({
"type": 4,
"data": {"content": "🏓 Pong !", "flags": 64},
})
if nom == "help":
return web.json_response({"type": 4, "data": embed_aide()})
if nom == "meme":
request.app.loop.create_task(traiter_meme(data)) # traitement long
return web.json_response({"type": 5}) # différé
return web.json_response({
"type": 4,
"data": {"content": "❓ Commande inconnue.", "flags": 64},
})
# ── Clic sur un composant
if itype == 3:
cid = data["data"]["custom_id"]
if cid == "gw_join":
return web.json_response({
"type": 4,
"data": {"content": "✅ Participation enregistrée !", "flags": 64},
})
if cid.startswith("rp_"):
return web.json_response({
"type": 4,
"data": {"content": "✅ Signalement transmis.", "flags": 64},
})
return web.json_response({"type": 6}) # accusé silencieux
# ── Soumission d'un formulaire modal
if itype == 5:
champs = extraire_champs(data["data"]["components"])
enregistrer_config_premium(data["member"]["user"]["id"], champs)
return web.json_response({
"type": 4,
"data": {"content": "✅ Configuration enregistrée.", "flags": 64},
})
return web.Response(status=400, text="type non pris en charge")
def extraire_champs(rows) -> dict:
"""Aplatit la structure imbriquée d'un formulaire modal."""
return {
c["custom_id"]: c.get("value", "")
for row in rows for c in row.get("components", [])
}
app = web.Application()
app.add_routes([web.post("/api/interactions", interactions)])
if __name__ == "__main__":
web.run_app(app, port=int(os.environ.get("PORT", 8080)))
Python — FastAPI
import os, json
from fastapi import FastAPI, Request, Response
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError
app = FastAPI()
VERIFY_KEY = VerifyKey(bytes.fromhex(os.environ["DISCORD_PUBLIC_KEY"]))
@app.post("/api/interactions")
async def interactions(request: Request):
corps = await request.body() # corps BRUT avant désérialisation
sig = request.headers.get("x-signature-ed25519", "")
ts = request.headers.get("x-signature-timestamp", "")
try:
VERIFY_KEY.verify(ts.encode() + corps, bytes.fromhex(sig))
except (BadSignatureError, ValueError):
return Response(status_code=401, content="invalid request signature")
data = json.loads(corps)
if data["type"] == 1:
return {"type": 1}
return {"type": 4, "data": {"content": "Reçu.", "flags": 64}}
Spécificité FastAPI
N'utilisez pas un modèle Pydantic comme paramètre de la route : le corps serait consommé et désérialisé avant que vous n'y accédiez, et await request.body() renverrait alors un contenu vide ou réordonné. Lisez toujours le corps brut en premier, puis désérialisez-le vous-même.
Node.js — Express
import express from 'express';
import nacl from 'tweetnacl';
const app = express();
const PUBLIC_KEY = process.env.DISCORD_PUBLIC_KEY;
// conservation du corps brut pour la vérification
app.use(express.json({
verify: (req, _res, buf) => { req.rawBody = buf; },
}));
app.post('/api/interactions', (req, res) => {
const signature = req.get('X-Signature-Ed25519');
const timestamp = req.get('X-Signature-Timestamp');
if (!signature || !timestamp) return res.status(401).send('missing headers');
let valide = false;
try {
valide = nacl.sign.detached.verify(
Buffer.concat([Buffer.from(timestamp, 'utf8'), req.rawBody]),
Buffer.from(signature, 'hex'),
Buffer.from(PUBLIC_KEY, 'hex'),
);
} catch { valide = false; }
if (!valide) return res.status(401).send('invalid request signature');
const interaction = req.body;
if (interaction.type === 1) return res.json({ type: 1 });
if (interaction.type === 2) {
return res.json({
type: 4,
data: { content: `Commande ${interaction.data.name} reçue.`, flags: 64 },
});
}
if (interaction.type === 3) return res.json({ type: 6 });
return res.status(400).send('unsupported type');
});
app.listen(process.env.PORT || 8080);
Node.js — bibliothèque officielle discord-interactions
import express from 'express';
import { verifyKeyMiddleware, InteractionType, InteractionResponseType } from 'discord-interactions';
const app = express();
app.post(
'/api/interactions',
verifyKeyMiddleware(process.env.DISCORD_PUBLIC_KEY), // gère signature et 401
(req, res) => {
const { type, data } = req.body;
if (type === InteractionType.PING) {
return res.send({ type: InteractionResponseType.PONG });
}
if (type === InteractionType.APPLICATION_COMMAND) {
return res.send({
type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
data: { content: `Commande ${data.name} exécutée.`, flags: 64 },
});
}
return res.sendStatus(400);
},
);
app.listen(8080);
Dépendances requises
# Python
pip install pynacl aiohttp # ou : pip install pynacl fastapi uvicorn
# Node.js
npm install express tweetnacl # ou : npm install express discord-interactions
Architecture hybride recommandée
Si un point de terminaison HTTP devait être mis en place pour ElSigm sans sacrifier le réseau InterPub, l'architecture suivante serait la plus adaptée.
┌──────────────────────────────────────────────────────────────┐
│ DISCORD │
└───────────────┬──────────────────────────┬───────────────────┘
│ │
WebSocket sortante HTTPS entrante
(événements) (interactions)
│ │
▼ ▼
┌──────────────────┐ ┌───────────────────────┐
│ Processus │ │ Serveur HTTP │
│ passerelle │ │ /api/interactions │
│ │ │ │
│ • on_message │ │ • signature Ed25519 │
│ • réseau InterPub│ │ • PING / PONG │
│ • AFK, mentions │ │ • commandes │
│ • tâches de fond │ │ • boutons, formulaires│
└────────┬─────────┘ └───────────┬───────────┘
│ │
└──────────┬──────────────────┘
▼
┌───────────────────────┐
│ Stockage partagé │
│ fichiers JSON ou │
│ base de données │
└───────────────────────┘
Points d'attention de cette architecture
- Concurrence d'écriture. Deux processus écrivant simultanément dans les mêmes fichiers JSON provoqueraient des pertes de données. Un verrou de fichier, ou mieux, une migration vers une base de données transactionnelle, devient nécessaire.
- Cohérence des états en mémoire. Le dictionnaire des délais entre annonces et les parties de jeu Simon vivent actuellement en mémoire vive d'un seul processus. Ils devraient être externalisés vers un stockage partagé.
- Duplication de la logique. Certaines fonctions devraient être accessibles depuis les deux processus, ce qui impose de les extraire dans un module commun.
- Ordonnancement des tâches périodiques. Les sept boucles de fond actuelles resteraient portées par le processus passerelle.
- Observabilité. Deux processus impliquent deux flux de journaux à corréler.
Recommandation
Compte tenu de la nature d'ElSigm — dont le cœur est la lecture de messages, incompatible avec le modèle HTTP — le maintien du mode passerelle seul reste le choix le plus sain. Le champ Interactions Endpoint URL doit donc rester vide. Cette page documente l'alternative sans la préconiser.
Sécurité du point de terminaison
Contrôles obligatoires
- Vérifier la signature avant toute autre opération. Aucune désérialisation, aucun accès à la base, aucune journalisation du contenu avant validation.
- Répondre 401 sur toute signature invalide, sans détail exploitable dans le corps de la réponse.
- Rejeter les horodatages hors fenêtre afin de limiter le rejeu.
- Ne jamais faire confiance au contenu de la requête pour déterminer des droits : les permissions doivent être revérifiées auprès de l'API lorsque l'enjeu est sensible.
- Valider les identifiants reçus avant de les employer dans une opération de lecture ou d'écriture.
Durcissement de l'infrastructure
- Limiter la taille maximale du corps accepté, par exemple à 256 kilo-octets, afin d'écarter les envois abusifs.
- Appliquer une limitation de débit par adresse source en amont de l'application.
- Placer le service derrière un mandataire inverse assurant la terminaison TLS et le filtrage.
- Exposer uniquement la route d'interactions ; toute autre route doit renvoyer 404.
- Ne jamais journaliser le jeton d'interaction, le jeton du bot ni le secret d'application.
- Charger toutes les valeurs sensibles depuis des variables d'environnement.
- Maintenir les dépendances cryptographiques à jour.
- Surveiller le taux de réponses 401 : une hausse soudaine signale une tentative d'envoi de fausses interactions.
Erreurs classiques à éviter
| Erreur | Conséquence | Correction |
|---|---|---|
| Vérifier la signature sur du JSON re-sérialisé | Échec systématique | Conserver et utiliser le corps brut |
| Répondre 200 à une signature invalide | Validation refusée par Discord | Répondre 401 |
| Utiliser le jeton du bot au lieu de la clé publique | Vérification impossible | Employer la Public Key du portail |
| Traiter avant de répondre | Dépassement des trois secondes | Répondre en type 5 puis traiter |
| Placer une redirection sur la route | Validation refusée | Servir la route directement |
| Certificat auto-signé | Connexion refusée par Discord | Utiliser une autorité reconnue |
| Confondre clé publique et secret d'application | Vérification impossible | Vérifier l'origine de chaque valeur |
| Ignorer l'horodatage | Rejeu possible | Contrôler la fenêtre temporelle |
| Journaliser le corps avant vérification | Pollution des journaux par des données non authentifiées | Journaliser après validation |
Se fier au champ permissions sans contrôle | Élévation de privilèges possible | Revérifier auprès de l'API |
Codes de réponse et diagnostic
Codes que votre serveur doit émettre
| Code | Situation | Corps |
|---|---|---|
200 | Interaction traitée avec succès | Objet de réponse JSON |
401 | Signature absente, invalide ou hors fenêtre | Message générique, sans détail |
400 | Corps illisible ou type non pris en charge | Message générique |
405 | Méthode autre que POST | Vide |
413 | Corps excédant la limite fixée | Vide |
500 | Erreur interne inattendue | Message générique, détails en journal uniquement |
Codes que vous pouvez recevoir de l'API Discord
| Code | Signification | Résolution |
|---|---|---|
400 | Corps de réponse mal formé | Vérifier la structure JSON et les limites de longueur |
401 | Jeton d'autorisation invalide | Vérifier l'en-tête Authorization |
403 | Permissions insuffisantes | Contrôler les permissions du bot sur le salon |
404 | Ressource introuvable | Jeton expiré, ou message déjà supprimé |
429 | Limite de débit atteinte | Respecter l'en-tête Retry-After |
500–504 | Incident côté Discord | Réessayer avec un délai exponentiel |
Codes d'erreur applicatifs fréquents
| Code | Message | Cause |
|---|---|---|
10062 | Unknown interaction | Réponse envoyée après expiration du délai de trois secondes |
40060 | Interaction has already been acknowledged | Deux réponses initiales envoyées pour la même interaction |
50001 | Missing access | Le bot n'a pas accès au salon visé |
50013 | Missing permissions | Permission requise absente |
50035 | Invalid form body | Champ trop long, couleur invalide, structure incorrecte |
30046 | Maximum number of edits reached | Trop de modifications successives d'un même message |
Procédure de mise en service
Si vous décidez de déployer un point de terminaison, suivez cette procédure dans l'ordre indiqué.
- Développez et testez localement
Implémentez la vérification de signature et la réponse au PING. Testez avec un tunnel HTTPS temporaire avant tout déploiement.
- Déployez sur une infrastructure joignable
Assurez-vous que l'adresse répond publiquement en HTTPS avec un certificat valide et sans redirection.
- Vérifiez manuellement
Testez la route avec un appel simulé et contrôlez que les signatures invalides reçoivent bien un 401.
- Renseignez le portail développeur
Dans l'onglet General Information, complétez le champ Interactions Endpoint URL avec l'adresse complète, par exemple
https://votre-domaine.tld/api/interactions. - Enregistrez
Discord exécute immédiatement sa séquence de validation. Une erreur explicite s'affiche en cas d'échec.
- Testez de bout en bout
Exécutez une commande sur un serveur de test et vérifiez que la réponse s'affiche correctement.
- Surveillez
Mettez en place une supervision de la disponibilité et une alerte sur le taux d'erreurs.
Test manuel de la route
# Ce test doit renvoyer 401 : la signature est délibérément invalide
curl -i -X POST https://votre-domaine.tld/api/interactions \
-H "Content-Type: application/json" \
-H "X-Signature-Ed25519: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" \
-H "X-Signature-Timestamp: 1786377600" \
-d '{"type":1}'
# Attendu : HTTP/1.1 401 Unauthorized
Liste de contrôle avant enregistrement
- La route répond en HTTPS avec un certificat valide et une chaîne complète.
- La méthode POST est acceptée avec un corps
application/json. - Aucune redirection n'est appliquée à la route.
- Le corps brut est lu avant toute désérialisation.
- La signature Ed25519 est vérifiée avec la clé publique de l'application.
- Une signature invalide entraîne une réponse 401.
- Des en-têtes manquants entraînent une réponse 401.
- Un PING signé correctement reçoit une réponse 200 avec
{"type": 1}. - L'horodatage est contrôlé dans une fenêtre raisonnable.
- Toute réponse est émise en moins de trois secondes.
- Les traitements longs utilisent une réponse différée de type 5.
- La clé publique est chargée depuis une variable d'environnement.
- Aucun secret n'apparaît dans les journaux.
- Une limitation de débit est en place en amont.
- La taille maximale du corps est bornée.
- Une supervision de disponibilité est active.
- Les commandes ont été enregistrées auprès de Discord.
- Un serveur de test a permis une validation de bout en bout.
Enregistrement des commandes
Le point de terminaison reçoit les interactions, mais les commandes doivent au préalable être déclarées auprès de Discord. Cette déclaration est indépendante du mode de réception choisi.
Commandes globales
Remplace l'intégralité des commandes globales. La propagation peut prendre jusqu'à une heure.
Commandes de serveur
Remplace les commandes propres à un serveur. La propagation est immédiate, ce qui en fait le mode privilégié pendant le développement.
Exemple de déclaration
PUT https://discord.com/api/v10/applications/1361056395524313158/commands
Authorization: Bot <TOKEN_DU_BOT>
Content-Type: application/json
[
{ "name": "ping", "description": "Vérifie la latence du bot", "type": 1 },
{ "name": "help", "description": "Afficher la liste des commandes", "type": 1 },
{ "name": "stats", "description": "Voir les statistiques du bot", "type": 1 },
{
"name": "profil",
"description": "Voir votre profil ou celui d'un membre",
"type": 1,
"options": [
{ "name": "membre", "description": "Le membre à consulter", "type": 6, "required": false }
]
},
{
"name": "config_interpub",
"description": "Configurer le salon de PUB interpub (admin)",
"type": 1,
"default_member_permissions": "8"
}
]
| Type d'option | Valeur | Contenu attendu |
|---|---|---|
| SUB_COMMAND | 1 | Sous-commande |
| SUB_COMMAND_GROUP | 2 | Groupe de sous-commandes |
| STRING | 3 | Chaîne de caractères |
| INTEGER | 4 | Nombre entier |
| BOOLEAN | 5 | Booléen |
| USER | 6 | Utilisateur ou membre |
| CHANNEL | 7 | Salon |
| ROLE | 8 | Rôle |
| MENTIONABLE | 9 | Utilisateur ou rôle |
| NUMBER | 10 | Nombre décimal |
| ATTACHMENT | 11 | Pièce jointe |
Le champ default_member_permissions exprime en décimal le masque de permissions requis. La valeur 8 correspond à la permission Administrateur, appliquée dans ElSigm aux commandes /config_interpub, /avertissement et /giveaway.
Données transitant par le point de terminaison
Cette section documente, en cohérence avec la Politique de Confidentialité, la nature des données présentes dans une requête d'interaction.
| Champ | Nature | Usage par l'application | Conservation |
|---|---|---|---|
id | Identifiant de l'interaction | Corrélation et journalisation | Non conservé |
token | Jeton opaque de réponse | Répondre et compléter | Mémoire vive uniquement, 15 minutes |
member.user.id | Identifiant de l'utilisateur | Retrouver ses données | Selon la fonction appelée |
member.user.username | Pseudonyme | Affichage | Non conservé |
member.user.avatar | Empreinte d'avatar | Affichage | Non conservé |
member.roles | Rôles de l'utilisateur | Contrôle d'accès | Non conservé |
member.permissions | Masque de permissions | Contrôle d'accès | Non conservé |
guild_id | Identifiant du serveur | Configuration InterPub | Conservé pour la configuration |
channel_id | Identifiant du salon | Configuration InterPub | Conservé pour la configuration |
data.options | Paramètres saisis | Selon la commande | Variable selon la fonction |
data.components | Champs d'un formulaire | Configuration Premium, suggestion | Conservé selon la fonction |
locale | Langue de l'utilisateur | Localisation éventuelle | Non conservé |
Principes appliqués
- Le jeton d'interaction n'est jamais journalisé ni persisté sur disque.
- Aucune donnée n'est extraite d'une requête dont la signature n'a pas été validée.
- Les réponses contenant des données personnelles portent l'indicateur éphémère.
- Les journaux applicatifs conservent l'identifiant de l'interaction et le nom de la commande, jamais le contenu des champs saisis.
- Aucune donnée d'interaction n'est transmise à un tiers.
Dépannage
| Symptôme | Cause probable | Résolution |
|---|---|---|
| « Validation errors — interactions endpoint url » | Le PING n'a pas reçu la réponse attendue | Vérifier le renvoi de {"type": 1} avec un code 200 |
| Signature toujours invalide | Corps re-sérialisé au lieu du corps brut | Conserver les octets originaux de la requête |
| Validation refusée malgré un PING correct | Les signatures invalides ne reçoivent pas de 401 | Corriger le code de retour en cas d'échec |
| « L'application n'a pas répondu » | Dépassement des trois secondes | Répondre en type 5 puis compléter |
| Erreur 10062 | Réponse trop tardive | Réduire le temps de traitement, différer |
| Erreur 40060 | Double réponse initiale | Une seule réponse initiale par interaction |
| Les commandes n'apparaissent pas | Commandes non enregistrées ou propagation en cours | Enregistrer au niveau du serveur pour un effet immédiat |
| Formulaire modal non affiché | Réponse différée envoyée en premier | Le type 9 doit être la première réponse |
| Erreur 401 côté Discord | En-tête d'autorisation incorrect | Utiliser le préfixe Bot avec le jeton |
| Interactions reçues en double | Absence de réponse dans le délai, réémission | Rendre le traitement idempotent, répondre rapidement |
| Point de terminaison désactivé par Discord | Échecs répétés de disponibilité | Rétablir le service puis réenregistrer l'adresse |
Référence rapide
Valeurs propres à ElSigm
| Élément | Valeur |
|---|---|
| Identifiant d'application | 1361056395524313158 |
| Version d'API recommandée | v10 |
| Base de l'API | https://discord.com/api/v10 |
| Route d'interactions suggérée | /api/interactions |
| Mode de réception actuel | Passerelle WebSocket |
| Intents privilégiés activés | Message Content, Server Members |
| Interactions Endpoint URL | à laisser vide |
| Nombre de commandes déclarées | 24 |
| Identifiants de composants utilisés | gw_join, rp_report, rp_sb, sb_yes, sb_no, deban_btn, confirm_<id> |
Constantes du protocole
| Constante | Valeur |
|---|---|
| Algorithme de signature | Ed25519 |
| Longueur de la signature | 128 caractères hexadécimaux |
| Délai de réponse initiale | 3 secondes |
| Validité du jeton d'interaction | 15 minutes |
| Indicateur éphémère | 64 |
| Longueur maximale d'un contenu | 2000 caractères |
| Embeds par message | 10 au maximum |
| Champs par embed | 25 au maximum |
| Rangées de composants | 5 au maximum |
| Boutons par rangée | 5 au maximum |
| Champs par formulaire modal | 5 au maximum |
Longueur d'un custom_id | 100 caractères |
Documents liés
La Politique de Confidentialité détaille le traitement des données mentionnées ici. Les Conditions d'Utilisation encadrent l'usage du service. La page Vérification des rôles liés documente le second point d'entrée HTTP de l'application, celui-là effectivement destiné à être exposé publiquement.