Wormhole Transfer

The Magic Wormhole protocol lets two parties transfer files using a short human-readable code as the only shared secret. No accounts. No passwords stored anywhere. No pre-shared keys.

The sender contacts a mailbox relay and claims a numbered slot (e.g. channel 7). The relay is a lightweight broker — it never sees file content, only encrypted handshake messages.

This server runs its own private relay, so no traffic touches third-party infrastructure.

A wormhole code is generated: 7-piano-dagger

• 7 — the channel number (routes to the right mailbox slot)
• piano-dagger — two random words that form the shared password

The code is short enough to read aloud or type in seconds. Share it with the recipient over any channel (voice, text, email).

SPAKE2 (Simple Password-Authenticated Key Exchange) is a cryptographic protocol that lets both sides prove they know the same password without ever transmitting it.

• Each side generates a random scalar and blends it with the password to produce a public message
• These messages are exchanged through the mailbox relay
• Each side can then derive the same session key — an ephemeral secret unknown to the relay or any eavesdropper
• Both sides verify a key confirmation hash before proceeding

An attacker who intercepts the SPAKE2 messages cannot derive the session key without knowing the password words.

Once both sides hold the same session key, file transfer begins over a transit relay connection.

• The file is encrypted with AES-256-GCM using the SPAKE2 session key
• GCM provides both confidentiality and authentication — tampering is detected
• The transit relay only ever forwards opaque encrypted bytes
• The receiver decrypts and verifies locally before writing to disk

After the transfer completes:

• The wormhole code is consumed and cannot be reused
• The mailbox channel is released
• The temporary file is deleted from server storage after download
• No record of the transfer is retained

SENDER                     RELAY                    RECEIVER
  |                          |                          |
  |-- claim channel 7 ------>|                          |
  |<- channel confirmed ------|                          |
  |                          |<-- join channel 7 -------|
  |-- SPAKE2 message A ----->|-- SPAKE2 message A ---->|
  |<- SPAKE2 message B ------| <- SPAKE2 message B -----|
  |   [derive session key]   |   [derive session key]   |
  |-- key confirmation ----->|-- key confirmation ---->|
  |<- key confirmation ------| <- key confirmation -----|
  |                          |                          |
  |==== AES-GCM ciphertext ==================>|        |
  |                          |                [decrypt] |
  |                          |            file written  |