FileFerry

Peer-to-peer, encrypted file sharing, without leaving your browser!
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

Important

Unfortunately, I no longer have the resources to host the backend components required for the live version of the project, fileferry.xyz. While this project doesn't store files or log transfers, it is sadly not server-less and still requires a few services to support the p2p magic. Follow the Getting Started guide to host it yourself!

About The Project

FileFerry is a browser-based application for direct file transfers without the need to store the file on a third-party server. The sender creates a unique phrase the receiver enters to get the file.

The app utilizes js-libp2p for networking and WebRTC for transfers. Senders register their p2p network address with a temporary passphrase through a lookup API. Receivers use this passphrase to find and connect to senders, using a relay server to establish the connection. Once that initial connection is made, both parties establish a direct WebRTC connection.

When a direct connection is prevented by Network Address Translation (NAT) on one or both ends, the app completes the transfer by using a relay server. This server acts as a glue for the two connections, allowing two peers to communicate, and uses only the bandwidth needed for the transfer. The entire transfer is protected by end-to-end encryption using the Noise framework, with x25519 key pairs for authentication and the ChaCha20Poly1305 cipher for data encryption, ensuring your data stays private and secure.

Built With

This project would not have been possible without the awesome contributors to Libp2p. I hope one day I'll be able to contribute as well :)

Here is the software stack used to build FileFerry:

• 
• 
• 
• 
• 
• 
• 
• 

Getting Started

Follow these steps to get FileFerry running locally. I run the backend externally (on a seperate remote machine) to the front-end, your mileage may vary as to how well this would or wouldn't work on a single host.

Prerequisites

Here is what you need to build and run your own instance of FileFerry:

• Node.js and npm
• Docker and Docker Compose

Installation

1. Clone the repository:

   git clone https://github.com/smp46/FileFerry.git
   cd FileFerry
   

2. Install Frontend Dependencies: Navigate to the root of the cloned repository and install the Node.js packages for the frontend:

   npm install
   

3. Build Backend Docker Images: The passphrase-server (Go) and relay-server (Node.js) are built as Docker images. You need to build them from their respective directories.

   docker build -t passphrase-server ./backend/passphrase-server
   

   docker build -t relay-server ./backend/relay-server
   

   Additionally you will need to build the GeoIP service that FileFerry uses to geo-locate the closest STUN servers to the user:

   git clone https://github.com/smp46/geoip-api.git
   cd geoip-api
   docker build -t geoip-api .

4. Configure Backend Services

   • Relay Server: The relay-server currently uses a .env file for basic config, find this in `./backend/relay-server. The only addition you need is a Base64 encoded private key for a persistent peer id.
   • CoTURN Configuration: The coturn service requires a my-turnserver.conf file. coturn uses a config file found at ./backend/relay-server/my-turnserver.conf, you can customise this as you want/need to to suit your network environment.
   • TLS: Modern browsers require remote connections to be secured, I recommend using a Reverse Proxy such as nginx with seperate domains (or sub-domains) for each service. This can be skipped if the project just being run locally for development or testing, but to be deployed, domains with certs are required.

5. Start Backend Services with Docker Compose: Navigate to the backend directory and start all services defined in docker-compose.yaml. This will launch the coturn server, passphrase-server, and relay-server.

   cd backend
   docker-compose up -d
   

   This command will run the services in detached mode, meaning they will run in the background.

6. Configure the Frontend: To ensure FileFerry knows where to look for it's external services, create a .env file in the root of the project. There is an example.env that can be renamed, and contains placeholders for what you'll need:

   VITE_RELAY_ADDRESS='/dns4/10-10-10-100.k51qzi5uqu5dlg6rzzu1wamxpip5om9vddzw5dvmw38wp1f4b30yi0q4it1234.libp2p.direct/tcp/41338/wss/p2p/12D3KooWQ3E3PsbrVnnh34dSggrcTqBKqrA2bbMwTH9EHmea1234'
   VITE_EXCHANGE_ADDRESS='https://exchange.example.com' 
   VITE_TURN_SERVER='turn:turn.example.com:3478'
   VITE_TURN_USERNAME='admin'
   VITE_TURN_CREDENTIAL='password'

7. Run the Frontend: Once the backend services are running and you have modified the frontend environment variables. return to the root of your repo directory and start the website.

   npm start
   

   This will typically start a development server and open FileFerry in your browser. Look for output in the terminal indicating the local URL (e.g., http://localhost:5173).

8. Optional: Build for Production: To build the static website files for deployment, run:

npm run build

The compiled website files will be located in the dist directory, ready for static hosting.

Usage

Here's a demo of the site:

demo.mp4

Roadmap

• File transfer resumption after broken or interrupted streams.
• Favicons using the FileFerry logo.
• Typescript conversion with TypeDoc documentation.
• Acquire and hold wake lock while transferring.
• Make it easier to configure your own FileFerry instance, i.e. centralise all variables that need to be changed.
• Night mode, with a moon and stars in the sky.
• Direct links to transfers to facilitate easier sharing.
• Share links to transfers.
• QR Code links to transfers.
• Prevent trigger words being generated for passphrase.
• Validate file integrity after transfer.

If you have any ideas or feedback, I would appreciate if you open an Issue and let me know!

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Samuel - Linkedin/smp46 - me@smp46.me

Project Link: https://github.com/smp46/FileFerry