Docs / Sync & Security / P2P Sync

P2P Sync

Sync your PrivStack data directly between devices without any server in the middle. Share specific documents with other PrivStack users using access controls.

P2P Sync Settings

How It Works

  1. Device Discovery: Your devices find each other automatically on your local network, or across the internet using your sync code
  2. Pairing: Pair devices with a simple 4-word code (e.g., “PEAR-MANGO-KIWI-GRAPE”)
  3. Verification: You manually approve each device before it can sync
  4. Sync: Only new changes are sent between devices — fast and efficient
  5. Automatic Merging: Edits from all devices merge automatically — no conflicts
  1. Device Discovery: Devices find each other via mDNS (local network) or Kademlia DHT (global, opt-in with sync code)
  2. Pairing: Pair devices with human-readable 4-word sync codes (e.g., “PEAR-MANGO-KIWI-GRAPE”)
  3. Authentication: Peers authenticate using the Noise protocol over QUIC transport
  4. Bidirectional Sync: Vector clocks determine missing events; only deltas are exchanged
  5. CRDT Merge: Changes merge automatically using conflict-free replicated data types

Setting Up P2P Sync

On Your First Device

  1. Go to Settings > Sync
  2. Click Enable P2P Sync
  3. A Sync Code is generated (4 easy-to-remember words)

On Additional Devices

  1. Install PrivStack and set up with the same master password
  2. Go to Settings > Sync
  3. Click Enable P2P Sync
  4. Enter the sync code from your first device
  5. Approve the connection on the first device — peers must be manually trusted

Local Network Sync

When devices are on the same network:

  • Discovery is automatic (zero configuration)
  • Sync is direct device-to-device
  • No internet required

Technical: Uses mDNS for discovery and QUIC (UDP) for low-latency transport.

Internet Sync

When devices are on different networks:

  • Your sync code lets devices find each other securely across the internet
  • Devices connect directly when possible
  • If a direct connection isn’t possible, an encrypted relay bridges the gap — but it can’t read your data
  • The sync code is SHA-256 hashed to create a DHT namespace
  • Peers discover each other via Kademlia DHT (only peers with the same code)
  • Direct connection attempted first; encrypted relay used as fallback
  • All traffic is end-to-end encrypted — relays see only encrypted packets

Sharing with Other Users

P2P sync isn’t just for your own devices. You can share specific entities with other PrivStack users:

  1. Open the item you want to share
  2. Select Share > Share with Peer
  3. The other user enters your sync code and you approve them
  4. Choose their access level: Viewer (read-only) or Editor (read/write)
  5. Only the shared entities sync to their device — nothing else

Access is enforced at every step. Revoking access stops future sync immediately.

Sync Status

View sync status in Settings > Sync:

  • Connected and trusted peers
  • Last sync time per peer
  • Events sent and received
  • Sync errors and diagnostics

Conflict Resolution

PrivStack automatically merges edits from all your devices:

  • Edits to different parts of an item merge cleanly
  • If two devices edit the same field, the most recent edit wins
  • Ordered content (like note blocks) merges intelligently — no lost edits
  • All devices always end up with the same result

PrivStack uses CRDTs (Conflict-free Replicated Data Types):

  • Vector clocks track causal ordering across all peers
  • LWW-per-field merge for most entities (last-writer-wins on individual fields, not whole documents)
  • RGA (Replicated Growable Array) for ordered content like note blocks
  • Edits from all devices are preserved — no data loss
  • Mathematically guaranteed convergence (commutative, associative, idempotent)

Security

  • End-to-end encrypted: All data encrypted before leaving your device
  • Zero-knowledge relays: Relay servers cannot read, modify, or correlate your data
  • Access control: Per-item permissions control who can see or edit your shared data
  • No account required: Sync works without creating an account with us
  • QUIC + Noise protocol: Peer authentication and transport encryption via libp2p
  • Replay protection: Event IDs and vector clocks prevent duplicate application
  • Per-entity ACLs enforced at handshake, sync request, event send, and event receive

Enterprise Features

For organizations using the Enterprise sync policy:

  • Role-based access: Viewer, Editor, Admin, Owner hierarchy
  • Team management: Group peers into teams for bulk access grants
  • Device limits: Enforce per-peer device counts based on license tier
  • Audit logging: Every access decision logged with peer, entity, action, and timestamp
  • ACL propagation: Access control changes replicate as CRDT events across all peers
Previous
Importing Data
Next
Cloud Sync