Skip to main content
D
Dits
Documentation

Peer-to-Peer Sharing

DITS includes Wormhole-style P2P capabilities for sharing files directly between peers without uploading to a central server.

What is P2P Sharing?

Unlike traditional file sharing where you upload to a server and others download from it, P2P creates a direct connection between two computers. Your files never touch a third-party server - they go straight from your machine to your collaborator's.

Fast
Direct transfers use your full network speed. No server bottleneck or bandwidth limits.
Private
End-to-end encrypted with QUIC/TLS 1.3. Files never touch external servers.
Works Anywhere
Same WiFi? Use mDNS. Different networks? Signal server handles NAT traversal.

How It Works

The Basic Flow

  1. Share: You run dits p2p share ./folder and get a join code (e.g., ABC-123)
  2. Discover: Your peer runs dits p2p connect ABC-123
  3. Connect: DITS finds your address via discovery methods and establishes a direct QUIC connection
  4. Transfer: Files flow directly between your machines, encrypted end-to-end

Discovery Methods

DITS uses multiple discovery methods to find peers. They're tried in priority order - the first one that works is used.

Direct IP (Priority 0)
If you know the peer's IP address, connect directly with no discovery needed. Fastest option for known addresses.
mDNS (Priority 10)
Zero-configuration discovery on local networks. Broadcasts on your WiFi/LAN - no internet required. Perfect for office or home use.
STUN (Priority 20)
Discovers your external IP by querying public STUN servers. Used for NAT traversal and hole-punching to reach peers behind firewalls.
Signal Server (Priority 30)
WebSocket rendezvous server for NAT traversal. Exchanges addresses between peers - your files never touch the signal server.
Relay (Priority 40) - No Port Forwarding!
When direct connections fail, traffic routes through the relay server. 100% success rate - works through any NAT type. Data is still end-to-end encrypted, the relay only sees encrypted bytes.

Local vs. Internet Sharing

Local Network (--local)

For peers on the same WiFi or LAN, use --local mode:

# Computer A
$ dits p2p share ./project --local
Connect with: dits p2p connect ABC-123 --local

# Computer B
$ dits p2p connect ABC-123 --local

Benefits:

  • No internet required
  • Maximum privacy (no external servers)
  • Fastest discovery (local broadcast)
  • Zero configuration

Internet Sharing (default)

For peers on different networks, the default auto mode uses the signal server for NAT traversal:

# Computer A
$ dits p2p share ./project
Connect with: dits p2p connect XYZ-789

# Computer B (anywhere in the world)
$ dits p2p connect XYZ-789

Security Model

Encryption

  • QUIC + TLS 1.3: All connections are encrypted
  • Certificate Pinning: Server cert verified via fingerprint
  • BLAKE3 Checksums: Fast integrity verification

Join Codes

Join codes are 6-character codes (e.g., ABC-123) that:

  • Use an unambiguous character set (no 0/O, 1/I/L confusion)
  • Are valid only while the share is active
  • Can be customized with --code

Trust Model

  • Signal server is semi-trusted (sees addresses, not data)
  • Peer connection is end-to-end encrypted
  • Use --local for maximum privacy

When to Use P2P

Good For
  • Quick file transfers between collaborators
  • Sharing large files without upload wait
  • Privacy-sensitive transfers
  • Same-office collaboration
  • One-time transfers
Consider Alternatives
  • Persistent team collaboration (use remotes)
  • Sharing with many people (use server)
  • Asynchronous workflows (use push/pull)
  • Version history needed (use repository)

Architecture Diagram

Discovery Chain

1.
Direct IP

If target is IP:port, use directly

2.
mDNS

Broadcast on local network

3.
STUN

Query for external IP

4.
Signal

WebSocket rendezvous

QUIC Connection

TLS 1.3 Encrypted

End-to-end encryption

UDP-based

NAT-friendly transport

Multiplexed

Multiple streams

Related Topics