punchline

Chat ponto a ponto criptografado de ponta a ponta via UDP. Sem contas, sem servidor central retransmitindo/armazenando mensagens, sem intermediário. Apenas dois pares, uma conexão direta e criptografia pelo protocolo Noise.

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

Índice

• O que faz
• Início rápido
• Como funciona
• Referência da CLI
• Uso
  • Configuração
  • Gerenciando Pares
  • Verificação de Status
  • Opções do Servidor
  • Temas
  • Completudes do Shell
• Criptografia
  • Handshake IK
  • Determinação do Iniciador
  • Armazenamento de Chaves
• Protocolo de Rede
  • Protocolo de Furação de NAT
  • Protocolo de Transporte
  • Protocolo de Sinalização
  • Protocolo STUN
• Estrutura do Projeto
• Instalação
  • Pelo crates.io
  • Compilando a partir do código-fonte
• Executando Testes
• Pilha de Tecnologias
• Licença

O que faz

Duas pessoas executam punchline connect <peer> em suas máquinas. O Punchline atravessa seus NATs, realiza um handshake criptografado e os coloca em um chat privado – tudo em alguns milissegundos. Os servidores STUN e de sinalização incluídos cuidam da descoberta e depois saem do caminho.

Início rápido

cargo build --release

Inicie os servidores (em uma máquina que ambos os pares possam acessar) ou use os meus públicos hospedados em 64.225.107.28 (STUN: porta 3478, sinalização: porta 8743):

punchline-stund                  # Servidor STUN - informa aos pares seu IP público
punchline-signald                # Servidor de sinalização - combina pares que querem conversar

Em cada máquina dos pares:

# Gere sua identidade (par de chaves X25519)
punchline keygen

# Compartilhe sua chave pública com seu par
punchline pubkey

# Salve a chave dele
punchline peers add alice a1b2c3d4...64_hex_chars

# Conecte-se (ambos os pares executam isso, direcionando um ao outro)
punchline connect alice --stun <servidor>:3478 --signal <servidor>:8743

A TUI é iniciada com uma visualização do progresso da conexão ao vivo:

1. Descoberta STUN - resolvendo seu endereço externo via punchline-stund

2. Servidor de sinalização - conectando ao punchline-signald

3. Aguardando o par - o servidor de sinalização combina ambos os pares

4. Furação de NAT - estabelecendo o caminho UDP direto

5. Handshake Noise - troca de chaves criptografada

   

Quando concluído, você está no chat. Digite e pressione Enter. Pressione Esc para sair.

Como funciona

Todo o sistema consiste em três binários, todos incluídos neste repositório:

Após a configuração inicial, os servidores STUN e de sinalização não são mais contatados. Tudo flui diretamente entre pares.

Referência da CLI

punchline

Bandeiras globais:

punchline-stund

punchline-signald

Uso

Configuração

Em vez de passar --stun e --signal toda vez, crie ~/.config/punchline/config.toml:

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

Gerenciando Pares

punchline peers                              # listar todos
punchline peers add alice a1b2c3d4...        # adicionar
punchline peers remove alice                 # remover

Os apelidos são armazenados em ~/.punchline/known_peers.toml. Você também pode conectar diretamente com uma chave hex bruta de 64 caracteres.

Verificação de Status

punchline status

Mostra sua identidade, configuração, alcançabilidade do servidor (envia uma sonda STUN real e conexão TCP) e número de pares.

Opções do Servidor

Ambos os servidores suportam -v (debug), -vv (trace), -q (silencioso), --address e --port:

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

Temas

Personalize a TUI via ~/.config/punchline/style.toml Estilos usados no 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

Todas as cores são RGB hex. Se o arquivo estiver ausente, as cores padrão do terminal são usadas.

Completudes do Shell

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

Criptografia

Nome completo do protocolo: Noise_IK_25519_ChaChaPoly_SHA256

Handshake IK

O padrão IK significa que o iniciador conhece a chave pública estática do respondedor antes do handshake começar. Ambos os pares já possuem as chaves um do outro (trocadas fora da banda ou via registro de pares), portanto nenhuma confiança no primeiro uso é necessária.

1. Iniciador -> Respondedor: Envia uma mensagem criptografada contendo sua chave pública estática, criptografada sob a chave conhecida do respondedor. Oferece ocultação de identidade contra observadores passivos.
2. Respondedor -> Iniciador: Decripta, verifica e responde. Ambos os lados transitam para o modo de transporte com chaves de sessão compartilhadas.

Determinação do Iniciador

O Punchline determina deterministicamente o iniciador comparando os primeiros 8 bytes da chave pública de cada par como um u64 big-endian. O par com o menor valor se torna o iniciador. Ambos os lados calculam isso independentemente.

Armazenamento de Chaves

A identidade é uma chave secreta X25519 de 32 bytes em ~/.punchline/id_x25519 com permissões Unix 0600. A chave pública é derivada na carga. A geração de chaves usa x25519-dalek com OsRng.

Protocolo de Rede

O primeiro byte de cada pacote UDP identifica seu tipo:

Protocolo de Furação de NAT

Ambos os pares executam o mesmo algoritmo simultaneamente:

1. Envie PROBE (0x00) a cada 200ms para o endereço externo do par.
2. Ao receber um PROBE, alterne para enviar ACK (0x01).
3. Ao receber um ACK, envie um ACK final e declare sucesso.
4. Timeout de segurança: 2 segundos enviando ACKs sem resposta assume que o par terminou.

Protocolo de Transporte

Mensagens (0x02) carregam payloads UTF-8 criptografados com Noise. Keepalives (0x03) são payloads vazios criptografados enviados a cada 10 segundos para manter a sincronização do nonce da cifra. 30 segundos sem nenhum pacote aciona desconexão.

Protocolo de Sinalização

JSON sobre WebSocket:

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

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

Protocolo STUN

Segue RFC 5389 (simplificado): requisição/resposta de binding com XOR-MAPPED-ADDRESS. Apenas IPv4.

Estrutura do Projeto

Workspace Cargo com quatro crates:

crates/
├── proto/      # Biblioteca compartilhada: criptografia, tipos STUN e sinalização, trait de transporte
├── client/     # Cliente P2P: CLI, TUI, lógica de conexão, gerenciamento de pares
├── signald/    # Servidor de sinalização: combinação de pares via WebSocket
└── stund/      # Servidor STUN: descoberta de endereço externo

Instalação

Pelo crates.io

cargo install punchline           # Cliente TUI
cargo install punchline-signald   # Servidor de sinalização
cargo install punchline-stund     # Servidor STUN

Compilando a partir do código-fonte

Pré-requisitos: Edição Rust 2024 (rustc 1.85+)

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

Os binários são colocados em target/release/:

• punchline
• punchline-signald
• punchline-stund

Executando Testes

cargo test

Os testes cobrem operações criptográficas, codificação/decodificação STUN, serialização do protocolo de sinalização, análise de configuração, gerenciamento de pares, temas de estilo e o handshake Noise IK.

Pilha de Tecnologias

Licença

MIT - veja LICENSE.