Skip to content
This repository has been archived by the owner on Nov 25, 2023. It is now read-only.
/ portal Public archive

๐Ÿ”— zero-config peer-to-peer encrypted live folder syncing that respects your `.gitignore`

License

Notifications You must be signed in to change notification settings

jackyzha0/portal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Banner

portal

Zero-config peer-to-peer encrypted live folder syncing tool that respects your .gitignore. Built on top of the Hypercore protocol with emphasis on being zero-config, secure, and decentralized.

Demos

Uploading Files Downloading Files

Installation

Binary

Pre-packaged binary, no external dependencies required! You can find the binaries on the latest release here.

With Node.js

# Requires node >=v12.22.1
$ npm i -g portal-sync

# Start using portal
$ portal new

# or 
$ portal join [sessionID]

Troubleshooting

  • On MacOS, ensure you give your terminal full disk access permission. (System preferences > Security & privacy > Privacy > Full disk access)

Highlights

  • Ephemeral: As soon as you close your portal, no further content can be downloaded from it. No data is stored anywhere except on the host device.
  • Decentralized: There is no central portal server that all data is routed through. portal only uses public servers to maintain a DHT (distributed hash table) for peer discovery.
  • One-to-many: A single host can sync data to any number of connected peers.
  • Stream-based: Utilizes file streaming to handle files of arbitrary size (regardless of whether they fit in memory or not)
  • Efficient: Changes in single files means that only one file needs to be synced. portal tracks which files have changed to avoid resyncing entire folders wherever possible. A priority queue is used to optimize concurrent operations.
  • Secure: Like Dat, all data is encrypted using the read key. Only those that possess your current 32-byte portal session ID can view the data you share.

Architecture

Project Architecture

Publish-subscribe Model

Portal relies on a publish-subscribe event model to drive its render and update cycles. File tree structure and individual file statuses are stored in a trie structure known as the Registry. On the host side, there is a local Registry that listens to file changes on the host machine and broadcasts them to an append-only Hypercore that is used as an event log. A drive syncing hook listens for changes in the local registry and streams file changes from disk to a Hyperdrive. On the client side, a remote Registry listens for changes in the event log and replicates changes locally. A drive download hook listens for changes in the remote registry and streams file changes from the Hyperdrive to the local disk.

Connection

Portals are identified by unique* 32-byte keys. When a client 'joins' a portal, portal looks up the session key using Hyperswarm and establishes a connection to the host using UDP holepunching.

*8.63x10-78 chance of collision

How is this different from Dat?

Might seem similar to another similar project built on top of the Hypercore protocol called Dat but there are a few key differences.

  1. Dat relies on nodes to keep seeding archives and drives and aims to be a distributed filesystem whereas portal focuses purely on being one-to-many for file sharing/syncing.
  2. No footprint. Because portal is designed to be zero-config, it doesn't leave any dotfiles laying around, whereas Dat stores secrets and metadata in a ~/.dat folder.
  3. Dat tracks version history. Although portal runs on the same underlying protocols, I haven't found a need to utilize version histories yet.
  4. portal respects your .gitignore so it doesn't sync anything you don't want (like pesky node_modules)

Developing

  1. Clone the repository and ensure you have node >= v12.22.1
  2. Run yarn to install deps and yarn dev to enable hot-reload
  3. Run yarn link to register portal as a valid executable

About

๐Ÿ”— zero-config peer-to-peer encrypted live folder syncing that respects your `.gitignore`

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published