punchline

Chat pair-à-pair chiffré de bout en bout par UDP. Pas de comptes, pas de serveur central relayant/stocker les messages, pas d'intermédiaire. Juste deux pairs, une connexion directe et un chiffrement via le protocole Noise.

https://github.com/user-attachments/assets/939e96d3-45e3-4484-9a27-28c3a0457b05

Table des matières

• Ce qu'il fait
• Démarrage rapide
• Comment ça marche
• Référence CLI
• Utilisation
  • Configuration
  • Gestion des pairs
  • Vérification du statut
  • Options du serveur
  • Thèmes
  • Complétions shell
• Cryptographie
  • Poignée de main IK
  • Détermination de l'initiateur
  • Stockage des clés
• Protocole filaire
  • Protocole de trou de serrure (hole punch)
  • Protocole de transport
  • Protocole de signal
  • Protocole STUN
• Structure du projet
• Installation
  • Depuis crates.io
  • Compilation depuis les sources
• Exécution des tests
• Stack technique
• Licence

Ce qu'il fait

Deux personnes exécutent punchline connect <pair> sur leurs machines. Punchline traverse leurs NAT, effectue une poignée de main chiffrée et les plonge dans un chat privé – le tout en quelques millisecondes. Les serveurs STUN et de signal inclus gèrent la découverte, puis s'effacent.

Démarrage rapide

cargo build --release

Démarrer les serveurs (sur une machine que les deux pairs peuvent atteindre), ou utiliser ceux que j'héberge publiquement à 64.225.107.28 (STUN : port 3478, signal : port 8743) :

punchline-stund                  # Serveur STUN - indique aux pairs leur IP publique
punchline-signald                # Serveur de signal - associe les pairs qui veulent communiquer

Sur chaque machine des pairs :

# Générer votre identité (paire de clés X25519)
punchline keygen

# Partager votre clé publique avec votre pair
punchline pubkey

# Enregistrer sa clé
punchline peers add alice a1b2c3d4...64_hex_chars

# Se connecter (les deux pairs exécutent cette commande, ciblant l'autre)
punchline connect alice --stun <server>:3478 --signal <server>:8743

Le TUI se lance avec une vue en direct de la progression de la connexion :

1. Découverte STUN – résolution de votre adresse externe via punchline-stund

2. Serveur de signal – connexion à punchline-signald

3. Attente du pair – le serveur de signaux associe les deux pairs

4. Trou de serrure – établissement du chemin UDP direct

5. Poignée de main Noise – échange de clés chiffré

   

Une fois terminé, vous êtes dans le chat. Tapez et appuyez sur Entrée. Appuyez sur Échap pour quitter.

Comment ça marche

L'ensemble du système est composé de trois binaires, tous inclus dans ce dépôt :

Une fois la configuration initiale effectuée, les serveurs STUN et de signal ne sont plus contactés. Tout circule directement de pair à pair.

Référence CLI

punchline

Drapeaux globaux :

punchline-stund

punchline-signald

Utilisation

Configuration

Au lieu de passer --stun et --signal à chaque fois, créez ~/.config/punchline/config.toml :

stun_server = "203.0.113.10:3478"
signal_server = "203.0.113.10:8743"

Gestion des pairs

punchline peers                              # lister tous
punchline peers add alice a1b2c3d4...        # ajouter
punchline peers remove alice                 # supprimer

Les alias sont stockés dans ~/.punchline/known_peers.toml. Vous pouvez aussi vous connecter directement avec une clé hexadécimale brute de 64 caractères.

Vérification du statut

punchline status

Affiche votre identité, configuration, accessibilité des serveurs (envoie une véritable sonde STUN et une connexion TCP) et le nombre de pairs.

Options du serveur

Les deux serveurs supportent -v (debug), -vv (trace), -q (silencieux), --address et --port :

punchline-stund -v --port 3478
punchline-signald -v --port 8743

Thèmes

Personnalisez le TUI via ~/.config/punchline/style.toml Styles utilisés dans la vidéo :

[colors]
my_text = "#ebdbb2"
peer_text = "#bdae93"
input_text = "#ebdbb2"
border = "#ebdbb2"
sidebar_key = "#ebdbb2"
sidebar_value = "#bdae93"

[padding]
chat_horizontal = 2
chat_vertical = 1

Toutes les couleurs sont en hexadécimal RVB. Si le fichier est absent, les couleurs par défaut du terminal sont utilisées.

Complétions shell

punchline completions bash > ~/.local/share/bash-completion/completions/punchline
punchline completions zsh > ~/.zfunc/_punchline
punchline completions fish > ~/.config/fish/completions/punchline.fish

Cryptographie

Nom complet du protocole : Noise_IK_25519_ChaChaPoly_SHA256

Poignée de main IK

Le modèle IK signifie que l'initiateur connaît la clé publique statique du répondant avant le début de la poignée de main. Les deux pairs possèdent déjà les clés l'un de l'autre (échangées hors bande ou via le registre de pairs), donc aucune confiance à la première utilisation n'est requise.

1. Initiateur -> Répondant : Envoie un message chiffré contenant sa clé publique statique, chiffrée sous la clé connue du répondant. Offre un masquage d'identité contre les observateurs passifs.
2. Répondant -> Initiateur : Déchiffre, vérifie et répond. Les deux côtés passent en mode transport avec des clés de session partagées.

Détermination de l'initiateur

Punchline sélectionne déterministiquement l'initiateur en comparant les 8 premiers octets de la clé publique de chaque pair sous forme de u64 big-endian. Le pair avec la valeur la plus petite devient l'initiateur. Les deux côtés calculent cela indépendamment.

Stockage des clés

L'identité est une clé secrète X25519 de 32 octets dans ~/.punchline/id_x25519 avec permissions Unix 0600. La clé publique est dérivée au chargement. La génération de clés utilise x25519-dalek avec OsRng.

Protocole filaire

Le premier octet de chaque paquet UDP identifie son type :

Protocole de trou de serrure (hole punch)

Les deux pairs exécutent simultanément le même algorithme :

1. Envoie un PROBE (0x00) toutes les 200 ms à l'adresse externe du pair.
2. À la réception d'un PROBE, passe à l'envoi d'ACK (0x01).
3. À la réception d'un ACK, envoie un dernier ACK et déclare le succès.
4. Délai de sécurité : 2 secondes d'envoi d'ACK sans réponse suppose que le pair a terminé.

Protocole de transport

Les messages (0x02) transportent des charge utiles UTF-8 chiffrées par Noise. Les keepalives (0x03) sont des charge utiles vides chiffrées envoyées toutes les 10 secondes pour maintenir la synchronisation des compteurs de nonce de chiffrement. 30 secondes sans paquet déclenchent la déconnexion.

Protocole de signal

JSON sur WebSocket :

// PairRequest (client -> serveur)
{ "external_addr": "203.0.113.5:48291", "public_key": "a1b2...", "target_public_key": "d4e5..." }

// PairResponse (serveur -> client)
{ "target_external_addr": "198.51.100.7:51003", "target_public_key": "d4e5..." }

Protocole STUN

Suit RFC 5389 (simplifié) : requête/réponse de liaison avec XOR-MAPPED-ADDRESS. IPv4 uniquement.

Structure du projet

Espace de travail Cargo avec quatre crates :

crates/
├── proto/      # Bibliothèque partagée : crypto, STUN, types de signal, trait de transport
├── client/     # Client P2P : CLI, TUI, logique de connexion, gestion des pairs
├── signald/    # Serveur de signal : appariement des pairs via WebSocket
└── stund/      # Serveur STUN : découverte d'adresse externe

Installation

Depuis crates.io

cargo install punchline           # Client TUI
cargo install punchline-signald   # Serveur de signal
cargo install punchline-stund     # Serveur STUN

Compilation depuis les sources

Prérequis : Édition Rust 2024 (rustc 1.85+)

git clone https://github.com/michal-pielka/punchline.git
cd punchline
cargo build --release

Les binaires sont placés dans target/release/ :

• punchline
• punchline-signald
• punchline-stund

Exécution des tests

cargo test

Les tests couvrent les opérations cryptographiques, l'encodage/décodage STUN, la sérialisation du protocole de signal, l'analyse de configuration, la gestion des pairs, les thèmes de style et la poignée de main Noise IK.

Stack technique

Licence

MIT - voir LICENSE.