punchline

Chat peer-to-peer crittografata end-to-end su UDP. Niente account, nessun server centrale che inoltra/memorizza messaggi, nessun intermediario. Solo due peer, una connessione diretta e crittografia con il protocollo Noise.

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

Indice

• Cosa fa
• Avvio rapido
• Come funziona
• Riferimento CLI
• Utilizzo
  • Configurazione
  • Gestione dei peer
  • Verifica dello stato
  • Opzioni del server
  • Tema
  • Completamenti per shell
• Crittografia
  • Handshake IK
  • Determinazione dell'iniziatore
  • Archiviazione delle chiavi
• Protocollo di rete
  • Protocollo di hole punch
  • Protocollo di trasporto
  • Protocollo di segnalazione
  • Protocollo STUN
• Struttura del progetto
• Installazione
  • Da crates.io
  • Compilazione dai sorgenti
• Esecuzione dei test
• Stack tecnologico
• Licenza

Cosa fa

Due persone eseguono punchline connect <peer> sulle loro macchine. Punchline buca i loro NAT, esegue un handshake crittografato e li porta in una chat privata – tutto in pochi millisecondi. I server STUN e di segnalazione inclusi gestiscono la scoperta, poi si mettono da parte.

Avvio rapido

cargo build --release

Avvia i server (su una macchina raggiungibile da entrambi i peer), oppure usa quelli pubblici che ospito su 64.225.107.28 (STUN: porta 3478, segnalazione: porta 8743):

punchline-stund                  # Server STUN – dice ai peer il loro IP pubblico
punchline-signald                # Server di segnalazione – abbina i peer che vogliono parlare

Su ogni macchina peer:

# Genera la tua identità (coppia di chiavi X25519)
punchline keygen

# Condividi la tua chiave pubblica con il peer
punchline pubkey

# Salva la loro chiave
punchline peers add alice a1b2c3d4...64_caratteri_hex

# Connettiti (entrambi i peer eseguono questo, puntandosi l'un l'altro)
punchline connect alice --stun <server>:3478 --signal <server>:8743

La TUI si avvia con una vista dell'avanzamento della connessione in tempo reale:

1. Scoperta STUN – risoluzione del tuo indirizzo esterno tramite punchline-stund

2. Server di segnalazione – connessione a punchline-signald

3. Attesa del peer – il server di segnalazione abbina entrambi i peer

4. Hole punch – creazione del percorso UDP diretto

5. Handshake Noise – scambio di chiavi crittografato

   

Una volta completato, sei nella chat. Digita e premi Invio. Premi Esc per uscire.

Come funziona

L'intero sistema è composto da tre binari, tutti inclusi in questo repository:

Dopo la configurazione iniziale, i server STUN e di segnalazione non vengono più contattati. Tutto fluisce direttamente peer-to-peer.

Riferimento CLI

punchline

Flag globali:

punchline-stund

punchline-signald

Utilizzo

Configurazione

Invece di passare --stun e --signal ogni volta, crea ~/.config/punchline/config.toml:

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

Gestione dei peer

punchline peers                              # elenca tutti
punchline peers add alice a1b2c3d4...        # aggiungi
punchline peers remove alice                 # rimuovi

Gli alias sono memorizzati in ~/.punchline/known_peers.toml. Puoi anche connetterti direttamente con una chiave hex di 64 caratteri.

Verifica dello stato

punchline status

Mostra la tua identità, configurazione, raggiungibilità del server (invia una vera sonda STUN e una connessione TCP) e numero di peer.

Opzioni del server

Entrambi i server supportano -v (debug), -vv (trace), -q (silenzioso), --address e --port:

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

Tema

Personalizza la TUI tramite ~/.config/punchline/style.toml Stili usati nel video:

[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

Tutti i colori sono RGB esadecimali. Se il file è assente, vengono usati i colori predefiniti del terminale.

Completamenti per shell

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

Crittografia

Nome completo del protocollo: Noise_IK_25519_ChaChaPoly_SHA256

Handshake IK

Il pattern IK significa che l'iniziatore conosce la chiave pubblica statica del risponditore prima dell'inizio dell'handshake. Entrambi i peer hanno già le chiavi l'uno dell'altro (scambiate out-of-band o tramite il registro dei peer), quindi non è necessario alcun trust-on-first-use.

1. Iniziatore -> Risponditore: Invia un messaggio crittografato contenente la sua chiave pubblica statica, crittografata con la chiave nota del risponditore. Fornisce occultamento dell'identità contro osservatori passivi.
2. Risponditore -> Iniziatore: Decifra, verifica e risponde. Entrambi i lati passano alla modalità di trasporto con chiavi di sessione condivise.

Determinazione dell'iniziatore

Punchline seleziona deterministicamente l'iniziatore confrontando i primi 8 byte della chiave pubblica di ciascun peer come u64 big-endian. Il peer con il valore minore diventa l'iniziatore. Entrambi i lati calcolano questo indipendentemente.

Archiviazione delle chiavi

L'identità è una chiave segreta X25519 di 32 byte in ~/.punchline/id_x25519 con permessi Unix 0600. La chiave pubblica viene derivata al caricamento. La generazione delle chiavi utilizza x25519-dalek con OsRng.

Protocollo di rete

Il primo byte di ogni pacchetto UDP identifica il suo tipo:

Protocollo di hole punch

Entrambi i peer eseguono lo stesso algoritmo simultaneamente:

1. Invia PROBE (0x00) ogni 200ms all'indirizzo esterno del peer.
2. Alla ricezione di un PROBE, passa all'invio di ACK (0x01).
3. Alla ricezione di un ACK, invia un ultimo ACK e dichiara successo.
4. Timeout di sicurezza: 2 secondi di invio di ACK senza risposta presume che il peer abbia terminato.

Protocollo di trasporto

I messaggi (0x02) trasportano payload UTF-8 crittografati con Noise. I keepalive (0x03) sono payload vuoti crittografati inviati ogni 10 secondi per mantenere la sincronizzazione del nonce del cifrario. 30 secondi senza alcun pacchetto triggerano la disconnessione.

Protocollo di segnalazione

JSON su WebSocket:

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

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

Protocollo STUN

Segue RFC 5389 (semplificato): richiesta/risposta di binding con XOR-MAPPED-ADDRESS. Solo IPv4.

Struttura del progetto

Workspace Cargo con quattro crate:

crates/
├── proto/      # Libreria condivisa: crittografia, tipi STUN, segnalazione, trait di trasporto
├── client/     # Client P2P: CLI, TUI, logica di connessione, gestione peer
├── signald/    # Server di segnalazione: abbinamento peer via WebSocket
└── stund/      # Server STUN: scoperta indirizzo esterno

Installazione

Da crates.io

cargo install punchline           # Client TUI
cargo install punchline-signald   # Server di segnalazione
cargo install punchline-stund     # Server STUN

Compilazione dai sorgenti

Requisiti: Edizione Rust 2024 (rustc 1.85+)

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

I binari sono posizionati in target/release/:

• punchline
• punchline-signald
• punchline-stund

Esecuzione dei test

cargo test

I test coprono operazioni crittografiche, codifica/decodifica STUN, serializzazione del protocollo di segnalazione, parsing della configurazione, gestione peer, temi di stile e handshake Noise IK.

Stack tecnologico

Licenza

MIT – consulta LICENSE.