Si tu as deja essaye d'integrer Signal dans tes projets Node.js, tu sais que l'experience oscille entre le bricolage et le parcours du combattant.
Le chiffrement de bout en bout de Signal est une merveille de securite, mais c'est un cauchemar pour l'automatisation. Contrairement a Discord ou Slack qui offrent des API REST simples, Signal demande de gerer des cles cryptographiques, le protocole Double Ratchet et des sessions asynchrones.
J'ai developpe signal-sdk pour combler ce trou. Ce n'est pas un script, c'est une abstraction logicielle en TypeScript qui pilote la cryptographie de Signal via une interface familiere aux devs Node.
Sous le capot : une architecture hybride
Pour etre clair : signal-sdk ne reinvente pas la cryptographie. Ce serait dangereux. Il agit comme un chef d'orchestre autour de signal-cli, le moteur de reference ecrit en Java/Rust.
- Node.js gere la logique metier, les evenements et le typage.
- Java (signal-cli) gere le transport, le chiffrement et le stockage des cles.
- La communication se fait via un canal JSON-RPC optimise (stdin/stdout).
On garde la securite d'une implementation eprouvee avec l'ergonomie de TypeScript.
Prerequis et installation
Puisqu'on pilote un moteur Java, il y a un prerequis systeme. Ce n'est pas du "Pure JS", c'est une solution systeme complete.
1. L'environnement Java
Avant d'installer le paquet, ta machine (ou conteneur Docker) doit avoir un JRE version 17 ou 21. C'est le moteur qui fait tourner la cryptographie.
# Verifie ta version java -version
2. Installation du SDK
Une fois Java confirme, installe le SDK. Le paquet inclut les binaires signal-cli pour Linux, macOS et Windows.
npm install signal-sdk
3. Liaison de l'appareil
Le SDK inclut un utilitaire CLI pour generer l'identite de ton bot sans manipuler des fichiers de configuration a la main.
npx signal-sdk connect
Cette commande lance le processus demon et affiche un QR Code dans ton terminal. Scanne-le via ton application Signal mobile (Parametres > Appareils relies) pour autoriser le bot a utiliser ton compte.
Le code : du scripting au framework
Le SDK offre deux niveaux d'abstraction selon tes besoins : le controle brut ou le framework de bot.
Niveau 1 : le client SignalCli
Ideal pour des taches d'administration systeme, des notifications ou de l'audit. On utilise ici le mode JSON-RPC persistant : le processus Java reste "chaud", ce qui permet d'envoyer des messages avec une latence minimale (quelques millisecondes) apres le demarrage.
import { SignalCli } from 'signal-sdk'; const client = new SignalCli('+336****5678'); async function main() { // Demarre le demon Java et etablit le canal RPC await client.connect(); // Abonnement aux evenements bruts (messages recus, typing...) client.on('message', (envelope) => { if (envelope.dataMessage) { console.log(`Message recu de ${envelope.source}: ${envelope.dataMessage.message}`); } }); // Envoi d'un message texte securise await client.sendMessage('+337****7777', 'Serveur de Prod : Redemarrage imminent'); } main().catch(console.error);
Niveau 2 : le framework SignalBot
C'est la partie interessante du SDK. Plutot que de parser des chaines et gerer des if/else, SignalBot structure tes interactions. Il gere le routage des commandes, l'extraction des arguments et les permissions.
import { SignalBot } from 'signal-sdk'; const bot = new SignalBot({ phoneNumber: "+336****5678", commandPrefix: "!", // Active les commandes type "!ping" }); // Definition declarative d'une commande bot.registerCommand({ name: "report", description: "Soumettre un rapport d'incident", handler: async (msg, args) => { // msg : objet enrichi avec methodes de reponse if (args.length === 0) { await msg.reply("Usage: !report <description>"); return; } console.log(`Incident rapporte : ${args.join(" ")}`); await msg.react(""); // Feedback visuel immediat } }); await bot.start();
Realites de production
Passer d'un script local a une app en production sur Signal demande de comprendre certaines contraintes. Voici ce qu'il faut savoir pour eviter les interruptions de service.
La persistance est critique
Signal n'est pas "stateless". Le protocole Double Ratchet maintient un etat cryptographique local (chaines de cles) qui evolue a chaque message.
Consequence : Si tu deployes ce SDK via Docker, tu dois monter un volume persistant pour stocker les donnees de signal-cli.
Si tu perds ce dossier :
- Tu perds ton identite (cles privees).
- Au redemarrage, une nouvelle identite est generee.
- Tes correspondants verront une alerte de securite ("Le numero de securite a change") et tes messages seront bloques.
Exemple de volume Docker :
VOLUME ["/home/botuser/.local/share/signal-cli"]
Gestion des processus
Le SDK lance un processus enfant Java. Bien qu'on gere les erreurs standard, un crash de la JVM (Out of Memory) peut arriver. En production, utilise un gestionnaire de processus comme PM2 ou la politique de redemarrage de Kubernetes pour garantir que le pont Node-Java soit relance automatiquement.
Rate limiting et CAPTCHA
Signal protege agressivement son reseau contre le spam. Si ton bot envoie trop de messages en peu de temps, il sera temporairement bloque ("Rate Limited"). Le SDK remonte cette erreur, mais la resolution du defi (CAPTCHA) doit souvent se faire manuellement via la CLI ou l'interface graphique. Concois tes bots pour etre "calmes" et respectueux des limites.
Conclusion
signal-sdk transforme un probleme de cryptographie complexe en une experience developpeur fluide. C'est l'outil ideal pour construire des chatbots internes, des systemes d'alerte securises ou des interfaces domotiques, a condition de respecter les exigences de l'architecture sous-jacente (Java + persistance).
Le projet est disponible sur npm et ouvert aux contributions.
- NPM : npmjs.com/package/signal-sdk
- GitHub : github.com/benoitpetit/signal-sdk
Tu as teste signal-sdk ou tu veux integrer Signal dans un projet ? Viens en parler sur Mastodon ou Bluesky. Et si l'article t'a plu, n'hesite pas a le partager !