WebWormhole is a peer-to-peer file transfer tool that uses WebRTC data channels and PAKE-based authentication to securely send files between two devices. It generates a one-time code that cryptographically links the sender and receiver, ensuring end-to-end encryption without trusting the signaling server. You can use it via a command-line client or directly in a web browser.
Sending a file to a colleague across the internet should not require uploading it to a third-party cloud storage provider. Yet, that is exactly what most of us do when we need to share a configuration file, a database snapshot, or a sensitive document. You compress the file, upload it to a storage bucket, generate a shareable link, and hope the access permissions are set correctly. This process is slow, exposes your data to the storage provider, and leaves copies of your file lingering on external servers.
WebWormhole offers a fundamentally different approach. It leverages WebRTC to create a direct, encrypted peer-to-peer connection between two devices. The file never touches an intermediary server. Instead, a short, human-readable code acts as the cryptographic key to establish the connection. This approach combines the speed of direct network connections with the security of end-to-end encryption, making it an ideal tool for developers and technical teams who need to move data quickly and privately.

What Is WebWormhole?

WebWormhole is an open-source project that implements secure, ephemeral file transfers over WebRTC data channels. It is heavily inspired by Magic Wormhole, a popular Python command-line tool created by Brian Warner. While Magic Wormhole uses a centralized relay server to transport data when a direct peer-to-peer connection fails, WebWormhole was built specifically to run in the web browser, utilizing the native peer-to-peer capabilities of WebRTC.
The core difference lies in the transport layer and the client environment. WebWormhole compiles its core logic to WebAssembly, allowing it to run entirely in a browser tab without requiring users to install additional software. It also replaces the SPAKE2 password-authenticated key exchange used in the original Magic Wormhole with CPace, a more efficient PAKE protocol. This makes WebWormhole a distinct, browser-first implementation of the wormhole concept, prioritizing direct peer-to-peer data flow and minimal trust in the signaling infrastructure.

Core Architecture of WebWormhole

The WebWormhole architecture consists of four primary components: the client application, the signaling server, the TURN relay, and the PAKE cryptographic layer. The client can be either a command-line interface written in Go or a web browser running a WebAssembly compilation of the same logic. The signaling server is a lightweight relay that facilitates the initial handshake but cannot read the file contents. The TURN relay acts as a fallback network path when direct peer-to-peer connectivity is blocked by strict firewalls or NAT configurations.
When a sender initiates a transfer, the client generates a strong secret and encodes it into a short, human-readable code. This code is shared with the receiver out-of-band, such as through a chat application. Both clients connect to the signaling server and use the shared code to perform a PAKE exchange. This exchange derives a symmetric encryption key. Once the key is established, the clients negotiate a WebRTC data channel. If direct connection attempts fail, they route the encrypted traffic through a TURN server. The signaling server is only used to exchange connection metadata, never the actual file data or the derived encryption key.

The PAKE-Based Authentication

WebWormhole uses a Password-Authenticated Key Exchange (PAKE) protocol called CPace to secure the initial handshake. The problem with traditional pre-shared keys is that short, human-memorable passwords are vulnerable to brute-force attacks if an attacker intercepts the key exchange. PAKE protocols solve this by ensuring that an attacker who observes the entire exchange cannot derive the shared key, even if the underlying password (the one-time code) is relatively weak.
CPace is specifically chosen for its efficiency and security properties in constrained environments like the browser. When a sender generates a code, they are actually generating a high-entropy secret that is then mapped to a short, pronounceable string. The receiver enters this string, and the CPace protocol uses it to authenticate the key exchange. This guarantees that only the person with the exact code can derive the session key, preventing man-in-the-middle attacks on the signaling server.

WebRTC Data Channels & DTLS-SRTP

Once the PAKE exchange establishes a shared secret, WebWormhole uses WebRTC data channels to transport the file. WebRTC data channels use the Stream Control Transmission Protocol over DTLS, providing encrypted, multiplexed streams. The encryption is handled by DTLS-SRTP, as defined in RFC 5764. This means the data channel benefits from the same transport-level security used for WebRTC audio and video streams.
The connection is established through Interactive Connectivity Establishment (ICE) negotiation. Both clients gather local network interfaces and external IP addresses via STUN servers. They then attempt to connect directly using host candidates, server-reflexive candidates, and relay candidates. Because the data channel is encrypted via DTLS and the application layer is encrypted using the key derived from the PAKE exchange, the file transfer is secured twice: once at the transport layer and once at the application layer.

Setting Up WebWormhole – From CLI to Browser

Using WebWormhole requires no complex infrastructure for the end user. If you prefer the command line, you can install the Go-based CLI tool. You initiate a send command, pointing to the file you want to share. The tool connects to the default public signaling server, generates a one-time code, and displays it in your terminal. You share this code with your recipient. When they enter the code on their end using the same CLI tool, the WebRTC connection is established and the file transfers directly to their machine.
If you prefer a browser-based workflow, you can navigate to the public WebWormhole web client. You drag and drop a file onto the page. The web client generates a code. You send the code to your colleague via any messaging platform. Your colleague opens the web client, types in the code, and the file downloads directly to their browser. The browser client handles the WebRTC negotiation, ICE candidate gathering, and file decryption entirely in JavaScript and WebAssembly.
For teams with strict data sovereignty requirements, self-hosting the signaling server is a straightforward process. The server component is lightweight and can be run in a Docker container or compiled from the Go source. You configure your CLI or web client to point to your custom signaling server URL instead of the default public one. This ensures that even the metadata about the connection (IP addresses and timing) never leaves your controlled infrastructure.

Choosing Between CLI and Browser

The CLI tool is best for developers who live in the terminal, automate file transfers via scripts, or need to send large files from headless servers. It integrates well into existing development workflows and can be chained with other command-line utilities. The browser client is ideal for non-technical users, quick one-off transfers, or environments where you cannot install software. It provides a familiar drag-and-drop interface and requires zero configuration. Both interfaces use the same underlying WebRTC and PAKE mechanisms, so the security guarantees are identical.

Security Considerations

WebWormhole's security model relies heavily on the separation of concerns between the signaling server and the data transfer path. The signaling server is treated as a completely untrusted entity. It relays the PAKE messages and the WebRTC SDP offers and answers, but because the PAKE exchange is encrypted and the WebRTC data channel is end-to-end encrypted, the signaling server cannot decrypt the file contents.
However, the signaling server does know that a connection is being made between two IP addresses. It can see the timing of the transfer and the size of the signaling messages. This metadata is minimal compared to cloud storage providers, but it is not zero. If you are transferring highly sensitive files where even the knowledge of a transfer occurring is a security risk, you should self-host the signaling server.
Another consideration is the one-time code itself. If an attacker intercepts the chat message containing the code and enters it before the intended recipient, they will establish the connection with the sender. The sender would then transfer the file to the attacker. To mitigate this, WebWormhole codes are single-use. Once a code is claimed, it is invalidated. Users should also verify the code out-of-band if they suspect interception, though the short lifespan of the code makes this attack window very narrow.

Threat Model Overview

The primary threats WebWormhole mitigates are passive network observation and malicious signaling servers. An attacker sniffing network traffic between the peers or the signaling server sees only encrypted DTLS packets and PAKE messages. They cannot derive the file contents. The tool also mitigates man-in-the-middle attacks through the PAKE protocol, which ties the cryptographic key to the specific one-time code. The main residual risk is code interception, where an attacker steals the code and claims the transfer before the legitimate receiver.

Performance & NAT Traversal

WebRTC is designed for real-time media, which makes it exceptionally fast for file transfer when a direct peer-to-peer connection is achieved. WebWormhole leverages this by using WebRTC data channels with unordered, unreliable delivery modes for maximum throughput, falling back to reliable modes if necessary. When both peers are on open networks, the file streams directly between them with sub-millisecond latency, limited only by their respective internet connection speeds.
NAT traversal is handled by the standard WebRTC ICE mechanism. WebWormhole clients use STUN servers to discover their public IP addresses and attempt direct connections. If both peers are behind symmetric NATs or strict corporate firewalls, a TURN relay is used. In relay mode, the file is sent to the TURN server and forwarded to the recipient. While this adds a network hop, the data is still end-to-end encrypted. The TURN server can only see encrypted packets, not the file contents. Throughput in relay mode is generally lower but still sufficient for most ad-hoc file transfers.

Self-Hosting the Signaling Server

Running your own WebWormhole signaling server gives you complete control over the connection metadata. The server is distributed as a Go binary and can be deployed in minutes. You can run it inside a Docker container on any cloud provider or on-premise hardware. The server requires minimal CPU and memory resources, as it only handles small signaling messages and does not process the actual file data.
Configuration involves setting a few environment variables for the listening port, TLS certificates, and optional TURN server credentials. You will need a domain name and valid TLS certificates to use the web client securely, as browsers require HTTPS for WebRTC APIs to function. Once the server is running, you simply pass your server's URL when generating or claiming a code in the CLI, or host the web client with your server's address configured as the default signaling endpoint.

Deployment Checklist

  • Provision a server with a public IP address.
  • Obtain a domain name and configure DNS records.
  • Set up TLS certificates (via Let's Encrypt or your internal CA).
  • Run the signaling server binary or Docker container.
  • Configure firewall rules to allow inbound traffic on the signaling port.
  • Deploy a TURN server if your users are behind strict firewalls.
  • Update your CLI and web clients to point to your custom signaling server URL.

Real-World Use Cases

WebWormhole shines in scenarios where speed and privacy are paramount. A developer needing to send a multi-gigabyte database dump to a remote teammate can use the CLI tool to transfer the file directly, bypassing the size limits and upload times of cloud storage. A security consultant needing to share a sensitive penetration test report can use the browser client, ensuring the document never resides on a third-party server.
It is also highly effective for ad-hoc collaboration. During a pair programming session, one developer can quickly send a local configuration file or a log snapshot to the other without setting up a shared repository. The ephemeral nature of the connection means there is no cleanup required. Once the transfer completes and the tab or terminal is closed, the connection is gone, leaving no trace of the exchange on any intermediary infrastructure.

Comparison with Similar Tools

WebWormhole occupies a specific niche among file transfer tools. The original Magic Wormhole is a robust, battle-tested command-line tool, but its primary transport mechanism relies on a centralized relay server rather than native WebRTC peer-to-peer connections. While Magic Wormhole can use transit relays, WebWormhole was built from the ground up to use WebRTC data channels, making it more naturally suited for browser-based transfers.
Tools like wormhole.page offer similar browser-based WebRTC transfers, but they may differ in their specific PAKE implementation and self-hosting capabilities. WebWormhole's use of CPace and its dual CLI/browser interface written in Go set it apart. Finally, generic WebRTC file-transfer libraries require developers to build their own signaling, authentication, and user interface. WebWormhole provides a complete, secure, and usable product out of the box, abstracting away the complexity of WebRTC ICE negotiation and PAKE key exchange.

Future Directions & Community

WebWormhole is an active open-source project. Development focuses on improving WebRTC reliability across different network conditions, updating cryptographic dependencies, and refining the user experience for both the CLI and web clients. The community welcomes contributions, from bug reports and documentation improvements to protocol enhancements. You can follow the project on GitHub to track ongoing development, participate in discussions, and explore the source code to better understand how WebRTC and PAKE can be combined to build secure, decentralized tools.

Definitions Glossary

PAKE (Password-Authenticated Key Exchange): A cryptographic protocol where two parties derive a shared secret key using a short, human-memorable password, without exposing the password or the derived key to eavesdroppers.
WebRTC Data Channel: A network transport path in WebRTC that allows peer-to-peer communication of arbitrary data with low latency, using SCTP over DTLS.
Signaling Server: A lightweight intermediary server used in WebRTC to exchange connection metadata (SDP offers and ICE candidates) between peers before a direct connection is established.
TURN (Traversal Using Relays around NAT): A protocol that acts as a relay server for WebRTC traffic when direct peer-to-peer connections fail due to strict firewalls or symmetric NAT configurations.
DTLS-SRTP: Datagram Transport Layer Security for Secure Real-time Transport Protocol, the encryption standard used by WebRTC to secure data channels and media streams.

Key Takeaways

  • WebWormhole uses WebRTC data channels to enable direct, peer-to-peer file transfers, bypassing cloud storage providers entirely.
  • It employs the CPace PAKE protocol to securely derive an encryption key from a short, one-time code, preventing man-in-the-middle attacks.
  • The signaling server only relays connection metadata and cannot read the file contents, which are protected by end-to-end encryption.
  • Users can transfer files via a Go-based CLI or a WebAssembly browser client, with the option to self-host the signaling server for maximum privacy.
  • WebRTC ICE negotiation and TURN relays ensure connections succeed even across strict NATs and corporate firewalls.

Conclusion

WebWormhole represents a practical application of WebRTC for secure, ad-hoc file sharing. By combining the peer-to-peer performance of WebRTC data channels with the robust cryptographic guarantees of PAKE authentication, it eliminates the need to trust third-party servers with your data. Whether you are a developer sharing logs from a terminal or a team exchanging sensitive documents via a browser, WebWormhole provides a fast, private, and secure alternative to traditional file upload services. What are you building with WebRTC? Drop a comment below, I would love to hear about your peer-to-peer projects.

Step 5: Running the Complete Application

Compiling and Running the Application

After implementing the signalling server, client interface, and security protocols, it's time to compile and run the complete WebWormHole application. Here are the steps to achieve this:

[a] Compile the Project

  • Ensure all dependencies are installed and WebAssembly files are compiled as described in previous sections.
  • In the project root directory, run the following commands:
bash
1     go build -o webwormhole
2

[b] Start the Signalling Server

  • Start the signalling server to facilitate the WebRTC connections.
  • Run the server using:
bash
1     ./webwormhole server -http=localhost:8000
2

[c] Run the Client Application

  • If you are using a React application for the client interface, start the React development server.
  • Navigate to the webwormhole-client directory and run:
bash
1     npm start
2
  • This will start the React application, and you can access it via http://localhost:3000.

Testing the Application

To ensure everything is working correctly, perform thorough testing on different devices and browsers:

Local Testing

  • Open the client application in a web browser and test sending and receiving files.
  • Verify that the connection is established, files are transferred successfully, and the status messages are displayed correctly.

Cross-Device Testing

  • Test the application on different devices (e.g., laptops, smartphones, tablets) to ensure compatibility and responsiveness.
  • Check that the file transfer works seamlessly across different operating systems and browser versions.

Network Testing

  • Test the application in different network conditions (e.g., Wi-Fi, mobile data) to ensure robust performance.
  • Verify that the WebRTC connection handles NAT traversal and peer discovery effectively.

Common Issues and Fixes

Connection Issues

  • If peers cannot establish a connection, check the signalling server logs for errors. Common issues include misconfigured server settings or network restrictions.
  • Ensure that the ICE candidates are exchanged correctly and that both peers can reach the signalling server.

File Transfer Failures

  • If file transfers fail, check the data channel state and the file reading/writing logic. Ensure that the data is being correctly read as an ArrayBuffer and sent over the data channel.
  • Debug using console logs to trace the data transfer process and identify where it fails.

Security Warnings

  • If there are security warnings or errors, verify that the CPace implementation is correct and that the session descriptions are properly encrypted and decrypted.
  • Ensure that the password generation and key derivation processes are secure and free of vulnerabilities.

Example Commands and Expected Outputs

Start the Server

bash
1   ./webwormhole server -http=localhost:8000
2
Expected output:
1   2023/06/11 12:34:56 Starting WebWormHole signalling server
2   2023/06/11 12:34:56 Listening on http://localhost:8000
3

Send a File

JavaScript
1   // In the client application
2   const file = document.querySelector('input[type="file"]').files[0];
3   sendFile(file);
4
Expected output (console log):
1   Data channel is open
2   File sent: myfile.txt
3

Receive a File

JavaScript
1   dataChannel.onmessage = (event) => {
2     const receivedBuffer = event.data;
3     const blob = new Blob([receivedBuffer]);
4     const url = URL.createObjectURL(blob);
5     const link = document.createElement('a');
6     link.href = url;
7     link.download = 'receivedFile';
8     document.body.appendChild(link);
9     link.click();
10     document.body.removeChild(link);
11     console.log('File received and saved');
12   };
13
Expected output (console log):
1   File received and saved
2
By following these steps, you can compile, run, and test your complete WebWormHole application, ensuring it functions correctly and securely across various environments and conditions.

Conclusion

WebWormHole is a cutting-edge tool designed to facilitate secure, peer-to-peer file transfers using WebRTC technology. It combines the strengths of WebAssembly and Go to deliver high performance and cross-platform compatibility. By leveraging CPace for secure key exchange, WebWormHole ensures that all data transfers are encrypted and protected from unauthorized access. The application’s design emphasizes simplicity and efficiency, making it an ideal choice for users who need reliable and private file-sharing capabilities without the need for central servers.

Free $20 Balance for AI Voice Agents & Video Calls

FAQ