https://github.com/jeremyckahn/secure-file-transfer
A library to encrypt and transfer files P2P in the browser
https://github.com/jeremyckahn/secure-file-transfer
decentralized-applications encryption file-sharing peer-to-peer webtorrent
Last synced: 3 months ago
JSON representation
A library to encrypt and transfer files P2P in the browser
- Host: GitHub
- URL: https://github.com/jeremyckahn/secure-file-transfer
- Owner: jeremyckahn
- License: mit
- Created: 2023-02-19T02:48:06.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-17T13:12:04.000Z (about 1 year ago)
- Last Synced: 2025-06-18T10:53:07.793Z (4 months ago)
- Topics: decentralized-applications, encryption, file-sharing, peer-to-peer, webtorrent
- Language: TypeScript
- Homepage: https://jeremyckahn.github.io/secure-file-transfer
- Size: 409 KB
- Stars: 33
- Watchers: 2
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `secure-file-transfer`
[**API documentation**](https://jeremyckahn.github.io/secure-file-transfer/)
[**Source code**](https://github.com/jeremyckahn/secure-file-transfer)
## Install
```sh
npm i --save secure-file-transfer
```
`secure-file-transfer` (SFT) is the easiest solution for securely getting a file from one web browser to another. It works by connecting two people via WebTorrent and transferring files peer-to-peer via WebRTC. Files are encrypted prior to transmission and decrypted upon receipt, so data is never exposed to anyone other than the intended recipient. Files are never sent to a server, and no server setup is needed to use SFT.
SFT is the library that [Chitchatter](https://chitchatter.im/) uses to transfer files to connected peers.
## Why use `secure-file-transfer`?
SFT builds on top of WebTorrent and several other excellent JavaScript libraries. It is specially tuned to minimize memory usage, thus enabling the delivery of very large files (as much as [your browser can handle](#limitations)).
WebTorrent is a powerful library, but there are a number of important things it doesn't do:
- File encryption
- This is critical when using public WebTorrent trackers. Without encryption, anyone with access to the tracker could intercept files being transferred between peers. Short of running your own private tracker, [encrypting data prior to sending it](https://github.com/webtorrent/webtorrent/issues/386#issuecomment-125379219) is the best way to ensure that only the intended party can access transferred file. SFT uses [`wormhole-crypto`](https://github.com/SocketDev/wormhole-crypto) to do this automatically.
- File saving
- This functionality is left up to WebTorrent users to implement. The most straightforward solution for closing this gap is [FileSaver.js](https://github.com/eligrey/FileSaver.js/). However, FileSaver.js has [limited file size support](https://github.com/eligrey/FileSaver.js/#supported-browsers). A more scalable solution is to stream data to disk, which SFT uses [StreamSaver.js](https://github.com/jimmywarting/StreamSaver.js) to do automatically.
By default, WebTorrent stores torrents in system memory. This is also not suitable for very large files. To work around this, SFT uses [idb-chunk-store](https://github.com/SocketDev/idb-chunk-store) to stream data directly from the sender's disk to the receiver's and keep memory usage low.
### Limitations
SFT has no file size limits. However, since transferred data is cached in IndexedDB via idb-chunk-store (to minimize memory usage and enable larger file transfers), it is subject to browser [storage limits](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria#storage_limits).
## Example
On one page have, [something like this](https://codesandbox.io/s/secure-file-transfer-offer-hhovi4?file=/src/index.ts) (in TypeScript):
```ts
import { fileTransfer } from "secure-file-transfer";
document.body.innerHTML = `
Magnet URI:
`;
const fileInput = document.querySelector('[type="file"]');
const passwordInput = document.querySelector('[type="text"]');
const p = document.querySelector("p");
const handleChange = async (evt: Event) => {
const password = passwordInput.value;
const magnetURI = await fileTransfer.offer(evt.target.files, password);
p.innerText = magnetURI;
};
fileInput?.addEventListener("change", handleChange);
```
Then on another page, [something like this](https://codesandbox.io/s/secure-file-transfer-receive-5fsweg?file=/src/index.ts):
```ts
import { fileTransfer } from "secure-file-transfer";
document.body.innerHTML = `
Download file(s)
`;
const downloadButton = document.querySelector("button");
const passwordInput = document.querySelector('[type="text"]');
const magnetUriInput = document.querySelector("textarea");
const status = document.querySelector("p");
const handleDownloadClick = async (evt: Event) => {
status?.innerText = "Downloading...";
const password = passwordInput.value;
const magnetUri = magnetUriInput.value;
await fileTransfer.download(magnetUri, password, { doSave: true });
status?.innerText = "Done!";
};
downloadButton.addEventListener("click", handleDownloadClick);
```
If the encryption keys match, the file will be transferred directly from the offerer to the receiver and saved to the local file system (so long as both peers keep their pages open).
## Troubleshooting
### Files can't be downloaded from peers
SFT uses [StreamSaver.js](https://github.com/jimmywarting/StreamSaver.js) to facilitate large file transfers. Download managers such as [FDM](https://www.freedownloadmanager.org/) are [known to interfere with StreamSaver.js](https://github.com/jimmywarting/StreamSaver.js/issues/325), so it is recommended to disable such download managers when using SFT to receive files.
## License
MIT.