magic-wormhole: transferência segura de ficheiros com um código de uso único

18 de fevereiro de 2026 • 6 min read

Olá a todos,

hoje quero partilhar convosco uma pequena ferramenta de linha de comandos a que recorro muitas vezes em suporte e incidentes: magic-wormhole. Resolve um problema que aparece no dia a dia das empresas muito mais do que qualquer história “enterprise”: precisas de enviar um ficheiro (ou uma pasta) a alguém agora, mas o email é pequeno demais, um link na cloud é politicamente ou legalmente sensível, e “abrir uma porta só por um bocadinho” não é opção.

Sexta-feira, 16:47. Uma empresa com cerca de 60 colaboradores tem um problema urgente: o servidor central de ficheiros está lento, os utilizadores reportam timeouts e o fornecedor externo de IT pede um bundle de suporte com logs e um pequeno export de configuração. O pacote anda perto de 900 MB. O email bloqueia, o SharePoint está fora por motivos de compliance, e montar um FTP ad-hoc é um pesadelo que em 2026 já não queres criar.

É aqui que o magic-wormhole brilha: trocas um código de uso único, transferes o ficheiro cifrado de ponta a ponta e acabou.

O que é o magic-wormhole?

O magic-wormhole é uma ferramenta leve para transferências ad-hoc entre dois computadores. O truque é o wormhole code (por exemplo 7-coral-lion): ambos os lados introduzem o mesmo código e isso inicia uma ligação cifrada de ponta a ponta.

O mais importante é o que o magic-wormhole não precisa:

sem conta
sem portal de login
sem “fazer upload para algum lado e partilhar um link”
sem regras de firewall de entrada

Ambos os lados só precisam de ter wormhole instalado e acesso à internet de saída. Na prática: se o HTTP(S) de saída funciona, o magic-wormhole normalmente também funciona.

Um caso real no mundo das PME

Voltando à nossa sexta-feira, o fluxo pragmático costuma ser assim:

Criar um bundle de suporte (logs, export, alguns screenshots).
Opcionalmente calcular um hash para confirmar depois que chegou exatamente o mesmo pacote.
Enviar o bundle via magic-wormhole.
Partilhar o código por um segundo canal (telefone, chat separado, ditar o código).

Do lado do emissor:

tar -czf support-bundle.tgz ./logs ./config-export
sha256sum support-bundle.tgz
wormhole send support-bundle.tgz

O magic-wormhole mostra o código. O recetor executa:

wormhole receive

Introduz o código, a transferência acontece e depois comparas os hashes. Na vida real, esta combinação de “rápido” e “mesmo assim limpo” é valiosa para muitas PME.

Como eu uso na prática

Enviar um ficheiro de A para B

Emissor:

wormhole send /path/to/file.zip

Recetor:

wormhole receive

O ficheiro fica no diretório atual. Eu costumo criar um diretório rápido para não perder nada entre Downloads e o Desktop:

mkdir -p ~/wormhole-recv && cd ~/wormhole-recv
wormhole receive

Enviar diretórios

Se precisares de enviar uma pasta inteira:

wormhole send --dir ./support-bundle/

O que acontece por trás (curto e sem marketing)

Por baixo do capô, o magic-wormhole faz três coisas que, de outra forma, terias de montar à mão: ligar as duas pontas, negociar chaves de forma segura e transferir dados de forma fiável, mesmo quando o NAT e as firewalls complicam.

Passo	O que acontece	Porque importa
1. Código	O emissor gera um código curto de uso único.	Um segredo partilhado para esta transferência.
2. Rendezvous	Ambos os clientes ligam-se a um servidor de rendezvous (por defeito a “mailbox” pública).	As pontas encontram-se sem portas de entrada.
3. PAKE	Uma chave partilhada é derivada do código via SPAKE2 (PAKE).	Chave E2E sem gestão clássica de chaves.
4. Caminho de dados	Tenta ligação direta e faz fallback para relay/transit se necessário.	Funciona atrás de NAT e em redes corporativas comuns.
5. Transferência E2E	Dados cifrados e com integridade de ponta a ponta.	O relay só vê ciphertext.

A ideia chave: rendezvous/relay é infraestrutura, mas não é o local onde os teus dados existem em claro.

Segurança: pontos fortes, limites e algumas regras

O que eu gosto no magic-wormhole é que o modelo de segurança é bastante honesto: é cifrado de ponta a ponta, mas identidade não vem “incluída”.

O que ganhas

Cifra de ponta a ponta: o conteúdo fica protegido entre emissor e recetor, mesmo usando relay.
Acesso de curta duração: o código é pensado para uma transferência, não como password permanente.
Superfície de ataque pequena: sem servidor para endurecer, sem gestão de utilizadores, sem UI web.

Onde tens de ter cuidado

O código é a password. Quem tem o código é “o teu peer”. Se o código vai parar a um ticket público, é um problema.
Sem auditoria por defeito. Para algumas empresas isto é bom; para outras, é inaceitável. Se precisas de DLP, aprovações e rastreabilidade, usa um canal oficial.
Os endpoints continuam a mandar. Se o emissor estiver comprometido, pode enviar lixo. Se o recetor estiver comprometido, o ficheiro fica comprometido depois de recebido.

Regras práticas (que ajudam mesmo)

Não partilhes o código no mesmo canal do link do ticket ou do contexto do ficheiro. Ideal: telefone ou chat privado separado.
Assume que logs podem conter tokens, hostnames ou dados pessoais. Envia apenas o necessário.
Para artefactos críticos: envia um hash por um canal separado e valida depois.

Instalação (curta e realista)

Em muitos sistemas, é um comando no gestor de pacotes:

Debian/Ubuntu: sudo apt install magic-wormhole
macOS: brew install magic-wormhole

Se os pacotes da distro estiverem desatualizados, pipx costuma ser a opção mais limpa:

pipx install magic-wormhole
pipx ensurepath

E se não quiseres Python de todo (servidor mínimo, container, rescue environment): wormhole-william é um port compatível em Go como binário único.

Automação e self-hosting

Para workflows controlados, o magic-wormhole pode ser usado de forma automatizada:

CODE="5-alpaca-orbit"
wormhole send --code "$CODE" /path/to/db.dump

Recetor:

wormhole receive --code "$CODE" --accept-file

Isto é prático, mas quando fixas um código voltas à gestão de credenciais. Se automatizares, faz isso com bom secret handling e com durações curtas.

Se quiseres controlo total sobre rendezvous/relay, podes apontar o cliente para infraestrutura própria, incluindo:

--relay-url para o teu servidor de rendezvous
--transit-helper para o teu relay de transit

Conclusão

O magic-wormhole não substitui processos geridos de transferência de ficheiros. Mas como ferramenta do dia a dia é excelente: rápida, sem fricção e com um modelo de segurança claro.

Especialmente em PME, onde muitas vezes não há tempo nem vontade para uma cascata de aprovações em cada caso de suporte, uma ferramenta “segura o suficiente e pronta a usar” é muitas vezes exatamente o que faz falta.

Fontes e leituras recomendadas

Até à próxima, Joe