punchline

Chat peer-to-peer cifrado de extremo a extremo sobre UDP. Sin cuentas, sin servidor central que retransmita/almacene mensajes, sin intermediarios. Solo dos pares, una conexión directa y cifrado mediante el protocolo Noise.

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

Índice

• Qué Hace
• Inicio Rápido
• Cómo Funciona
• Referencia CLI
• Uso
  • Configuración
  • Gestión de Pares
  • Verificación de Estado
  • Opciones del Servidor
  • Temas
  • Completado de Shell
• Criptografía
  • Handshake IK
  • Determinación del Iniciador
  • Almacenamiento de Claves
• Protocolo de Red
  • Protocolo de Perforación de NAT
  • Protocolo de Transporte
  • Protocolo de Señalización
  • Protocolo STUN
• Estructura del Proyecto
• Instalación
  • Desde crates.io
  • Compilación desde Fuente
• Ejecución de Pruebas
• Stack Tecnológico
• Licencia

Qué Hace

Dos personas ejecutan punchline connect <peer> en sus máquinas. Punchline atraviesa sus NATs, realiza un handshake cifrado y los introduce en un chat privado, todo en milisegundos. Los servidores STUN y de señalización incluidos manejan el descubrimiento y luego se apartan.

Inicio Rápido

cargo build --release

Inicia los servidores (en una máquina a la que ambos pares puedan acceder), o usa los públicos que tengo alojados en 64.225.107.28 (STUN: puerto 3478, señalización: puerto 8743):

punchline-stund                  # STUN server - tells peers their public IP
punchline-signald                # Signal server - matches peers who want to talk

En la máquina de cada par:

# Generate your identity (X25519 keypair)
punchline keygen

# Share your public key with your peer
punchline pubkey

# Save their key
punchline peers add alice a1b2c3d4...64_hex_chars

# Connect (both peers run this, targeting each other)
punchline connect alice --stun <server>:3478 --signal <server>:8743

La TUI se inicia con una vista en vivo del progreso de conexión:

1. Descubrimiento STUN - resolviendo tu dirección externa mediante punchline-stund

2. Servidor de señalización - conectándose a punchline-signald

3. Esperando al par - el servidor de señalización empareja a ambos pares

4. Perforación de NAT - estableciendo la ruta UDP directa

5. Handshake Noise - intercambio de claves cifrado

   

Una vez completado, estás en el chat. Escribe y presiona Enter. Presiona Esc para salir.

Cómo Funciona

El sistema completo consta de tres binarios, todos incluidos en este repositorio:

Después de la configuración inicial, ya no se contacta a los servidores STUN y de señalización. Todo fluye directamente entre pares.

Referencia CLI

punchline

Banderas globales:

punchline-stund

punchline-signald

Uso

Configuración

En lugar de pasar --stun y --signal cada vez, crea ~/.config/punchline/config.toml:

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

Gestión de Pares

punchline peers                              # list all
punchline peers add alice a1b2c3d4...        # add
punchline peers remove alice                 # remove

Los alias se almacenan en ~/.punchline/known_peers.toml. También puedes conectarte directamente con una clave hexadecimal de 64 caracteres.

Verificación de Estado

punchline status

Muestra tu identidad, configuración, accesibilidad del servidor (envía una sonda STUN real y una conexión TCP) y número de pares.

Opciones del Servidor

Ambos servidores soportan -v (debug), -vv (trace), -q (quieto), --address y --port:

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

Temas

Personaliza la TUI a través de ~/.config/punchline/style.toml Estilos usados en el vídeo:

[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

Todos los colores son RGB hexadecimal. Si el archivo no existe, se usan los colores predeterminados del terminal.

Completado de Shell

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

Criptografía

Nombre completo del protocolo: Noise_IK_25519_ChaChaPoly_SHA256

Handshake IK

El patrón IK significa que el iniciador conoce la clave pública estática del respondedor antes de que comience el handshake. Ambos pares ya tienen las claves del otro (intercambiadas fuera de banda o a través del registro de pares), por lo que no se requiere confianza en el primer uso.

1. Iniciador -> Respondedor: Envía un mensaje cifrado que contiene su clave pública estática, cifrada bajo la clave conocida del respondedor. Proporciona ocultación de identidad frente a observadores pasivos.
2. Respondedor -> Iniciador: Descifra, verifica y responde. Ambos lados transicionan al modo de transporte con claves de sesión compartidas.

Determinación del Iniciador

Punchline selecciona deterministamente al iniciador comparando los primeros 8 bytes de la clave pública de cada par como un u64 en big-endian. El par con el valor más pequeño se convierte en el iniciador. Ambos lados calculan esto de forma independiente.

Almacenamiento de Claves

La identidad es una clave secreta X25519 de 32 bytes en ~/.punchline/id_x25519 con permisos Unix 0600. La clave pública se deriva al cargar. La generación de claves usa x25519-dalek con OsRng.

Protocolo de Red

El primer byte de cada paquete UDP identifica su tipo:

Protocolo de Perforación de NAT

Ambos pares ejecutan el mismo algoritmo simultáneamente:

1. Enviar PROBE (0x00) cada 200ms a la dirección externa del par.
2. Al recibir un PROBE, cambiar a enviar ACK (0x01).
3. Al recibir un ACK, enviar un ACK final y declarar éxito.
4. Tiempo de espera de seguridad: 2 segundos enviando ACKs sin respuesta asume que el par terminó.

Protocolo de Transporte

Los mensajes (0x02) transportan cargas útiles UTF-8 cifradas con Noise. Los keepalives (0x03) son cargas útiles vacías cifradas enviadas cada 10 segundos para mantener la sincronización del nonce del cifrado. 30 segundos sin ningún paquete provoca la desconexión.

Protocolo de Señalización

JSON sobre 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..." }

Protocolo STUN

Sigue RFC 5389 (simplificado): solicitud/respuesta de enlace con XOR-MAPPED-ADDRESS. Solo IPv4.

Estructura del Proyecto

Workspace de Cargo con cuatro crates:

crates/
├── proto/      # Biblioteca compartida: criptografía, tipos STUN y de señalización, trait de transporte
├── client/     # Cliente P2P: CLI, TUI, lógica de conexión, gestión de pares
├── signald/    # Servidor de señalización: emparejamiento de pares vía WebSocket
└── stund/      # Servidor STUN: descubrimiento de dirección externa

Instalación

Desde crates.io

cargo install punchline           # TUI client
cargo install punchline-signald   # Signal server
cargo install punchline-stund     # STUN server

Compilación desde Fuente

Requisitos previos: Rust edición 2024 (rustc 1.85+)

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

Los binarios se colocan en target/release/:

• punchline
• punchline-signald
• punchline-stund

Ejecución de Pruebas

cargo test

Las pruebas cubren operaciones criptográficas, codificación/decodificación STUN, serialización del protocolo de señalización, análisis de configuración, gestión de pares, tematización de estilos y el handshake Noise IK.

Stack Tecnológico

Licencia

MIT - consulta LICENSE.