feat: P2P sync transport via Hyperswarm (DHT discovery + NAT holepunching)

[kayodebristol]

Summary

Add a sync module to PluresDB that enables two database instances to discover each other and replicate through firewalls using a shared encryption key — no relay servers, no port forwarding.

Motivation

PluresDB already has CRDTs for conflict-free merge. The missing piece is transport: how do two nodes find each other and establish an encrypted channel through NATs/firewalls?

Use cases:

• superlocalmemory sync — two OpenClaw agents sharing memory across machines
• OASIS — decentralized commerce with local-first data sync
• Any PluresDB app — zero-config P2P replication

Proposed Design

Transport: Hyperswarm

Hyperswarm provides:

• DHT-based discovery — derive a topic from the shared key, announce/lookup on a distributed hash table
• UDP holepunching — traverses most NAT configurations automatically
• Noise protocol encryption — encrypted streams authenticated by the shared key
• Battle-tested in production (Keet, Hypercore ecosystem)

API Surface

// Generate a new sync key
const key = PluresDB.generateSyncKey()  // returns 32-byte hex string

// Or set an existing key
db.setSyncKey(existingKey)

// Enable sync — discovers peers automatically
await db.enableSync({ key })
// That's it. CRDTs handle conflict resolution.

// Stop syncing
await db.disableSync()

// Events
db.on('peer:connected', (peerInfo) => { ... })
db.on('peer:disconnected', (peerInfo) => { ... })
db.on('sync:complete', (stats) => { ... })

Architecture

Node A                      DHT Network                    Node B
  │                             │                             │
  ├── announce(hash(key)) ─────►│◄───── announce(hash(key)) ──┤
  │                             │                             │
  │◄── peer discovered ────────►│◄──── peer discovered ──────►│
  │                             │                             │
  ├─── UDP holepunch ──────────────────────────────────────►  │
  │                             │                             │
  └─── Noise-encrypted stream (CRDT sync) ──────────────────┘

Implementation Plan

1. pluresdb-sync module — wraps Hyperswarm, manages key→topic derivation, connection lifecycle
2. Replication protocol — serialize CRDT operations over the encrypted stream
3. Key management — generate, store, rotate sync keys
4. Selective sync — optionally filter which collections/tables replicate
5. Rust port — investigate hyperswarm-rs or build a Rust Hyperswarm client for the native binary

Key Decisions Needed

• Hyperswarm vs alternatives (libp2p, custom) — research in progress
• Replication protocol format (length-prefixed JSON, protobuf, or custom binary)
• Key rotation strategy
• Mobile support (Hyperswarm on React Native / Tauri mobile)

Dependencies

• hyperswarm (npm) — DHT + holepunching
• @hyperswarm/dht — underlying DHT
• PluresDB CRDT engine (existing)

References

• Hyperswarm research report: pending (will link)
• Related: Add embedded export for pure embedded database usage (no server process) #68 (embedded mode), feat: add embedded export for pure embedded database usage #69 (embedded export)