Deskdrop

Deskdrop is a production-grade, zero-server shared clipboard and peer-to-peer file transfer engine. Designed to replace bloated cloud-dependent clipboard syncing tools, it keeps your data entirely within your local area network (LAN) or private VPN. Powered by a shared Rust core, Deskdrop is blazing fast, light on system resources, and offers premium native integrations for macOS, Android, Linux, and Windows.

---

📑 Table of Contents

• ⚡ Key Value Propositions
• 🏗️ System Architecture
• 🌟 Technical Feature Highlights
• 💻 Command-Line Interface (CLI) Usage
• 📂 Configuration & Data Layout
• 🛠️ Detailed Building & Installation
• 🧪 Testing & CI/CD
• 📚 Deep Architecture Documentation
• 🤝 Contributing & License

---

⚡ Key Value Propositions

Unlike generic clipboard managers or complex sync utilities, Deskdrop focuses on three core pillars:

1. Absolute Local-First Privacy (Zero Cloud): Your data never contacts an external server. Discovery, handshake, and payload transfers are completely peer-to-peer over the local network using mDNS and secure sockets.
2. Timeline-First Clipboard UX: Say goodbye to remote copies silently hijacking your local clipboard. Deskdrop lands incoming text, images, and files in a rich Activity Feed first. You preview, tag, pin, and explicitly apply items when you are ready.
3. Premium Hardware Continuity: Experience high-end ecosystem features (like Apple's Universal Clipboard and Handoff) on all your devices—including call continuity controls, background sleep prevention (App Nap / Modern Standby), and resumable file sharing.
4. Wireless Continuity Camera: Transform your Android or iOS device into a high-quality, zero-lag wireless camera feed for your desktop. The feed streams entirely over your local network, ensuring absolute privacy without third-party servers.

---

🏗️ System Architecture

Deskdrop employs a modular, decoupled architecture centered around a high-performance Rust Engine Library (deskdrop-core). Native platforms interface with the core via direct C FFI, JNI (Android), or Named Pipe IPC (CLI & Daemons).

 ┌───────────────────────────────────────────────────────────────────────────────────────────┐
 │                                       PLATFORM LAYER                                      │
 │   macOS (Swift UI)       Android (Kotlin/JNI)       Windows (C#/WinUI)       Linux (GTK)  │
 └───────────┬───────────────────────┬─────────────────────────┬──────────────────────┬──────┘
             │                       │                         │                      │
             │ Native C FFI          │ JNI Direct              │ Named Pipe IPC       │ Unix IPC
             ▼                       ▼                         ▼                      ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────┐
 │                                  DESKDROP-CORE (RUST)                                     │
 │                                                                                           │
 │   ┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────────┐   │
 │   │       COORDINATOR     │   │      NETWORKING       │   │       SECURITY SUITE      │   │
 │   │   • engine.rs         │   │   • network.rs        │   │   • crypto.rs             │   │
 │   │   • engine_support.rs │   │   • network_manager.rs│   │     - X25519 Ephemeral    │   │
 │   │   • peer_manager.rs   │   │   • discovery.rs      │   │     - HKDF-SHA256         │   │
 │   └───────────┬───────────┘   │     - mDNS Private    │   │     - ChaCha20-Poly1305   │   │
 │               │               └───────────┬───────────┘   │   • pairing.rs            │   │
 │               ▼                           ▼               │     - PINmod10^6          │   │
 │   ┌───────────────────────┐   ┌───────────────────────┐   │   • trust.rs (TOFU)       │   │
 │   │      DATA STORES      │   │     SYNC CONTEXT      │   └───────────────────────────┘   │
 │   │   • history.rs        │   │   • sync_controller.rs│   ┌───────────────────────────┐   │
 │   │   • activity.rs       │   │   • dedup.rs          │   │      FILE TRANSFER        │   │
 │   │   • settings.rs       │   │   • filter.rs         │   │   • chunked.rs (256KB)    │   │
 │   └───────────────────────┘   │   • throttle.rs       │   │   • probe.rs (Adaptive)   │   │
 │                               └───────────────────────┘   └───────────────────────────┘   │
 └───────────────────────────────────────────────────────────────────────────────────────────┘

Protocol & Mesh Lifecycle

1. Discovery: Nodes advertise on _deskdrop._tcp.local. using mDNS. Incompatible versions are pruned early, and IPv4/IPv6 connections are prioritized dynamically.
2. Handshake (HelloFrame / HelloAckFrame): Peers establish identity and platform metadata. Ephemeral X25519 ECDH keys are exchanged in plaintext.
3. Session Secret: Diffie-Hellman secret is combined via HKDF-SHA256 to derive a symmetric session key.
4. Encrypted Tunnel: Subsequent frames (ClipboardPush, FileChunk, CallStateUpdate, BatteryStatus) are encrypted with ChaCha20-Poly1305 using strictly monotonic counter nonces.
5. Peer State & Mesh Dedup: Device lifecycle passes through five states (Cryptographic Approval, Persistent Pairing, Runtime Connection, Sync Enabled, Auto-connect). Mesh-aware deduplication safely suppresses echoes from all connected peers simultaneously.

---

🌟 Technical Feature Highlights

🔒 Cryptographic Security Model

• End-to-End Encryption: Every session is locked down with standard Curve25519 ECDH key exchange and ChaCha20-Poly1305 AEAD.
• Zeroization (CRIT-02): Memory containing Diffie-Hellman shared secret bytes is explicitly zeroized in RAM immediately after HKDF expansion to eliminate cold-boot vulnerabilities.
• Strict Replay Protection: Each frame relies on a strictly monotonic, 64-bit big-endian message counter, enforcing strict chronological order.
• PIN-Based Secure Pairing: Combats active Man-in-the-Middle (MITM) attacks by displaying a commutative numeric PIN (PairingPin).
• mDNS Privacy Enforcer (TRU-06): Friendly device names are never broadcast in plain-text mDNS TXT records. Only opaque UUIDs are published. Canonical device names and OS telemetry are exchanged only after a successful encrypted handshake.

📦 Resumable Chunked File Transfers

• High-Speed Chunking: Files are broken down into 256 KB chunks (FILE_CHUNK_SIZE), capped strictly at 512 MB per payload to prevent resource exhaustion attacks.
• Resumable Pipelines: If a transfer drops mid-stream, the receiver stores a progressive chunk acknowledgment state. On reconnect, the transfer resumes starting at index last_confirmed_chunk + 1.
• Adaptive Chunk Sizing & Throttling: Dynamic latency probes monitor link quality degradation to optimize buffer scale and timeout backoffs. The system incorporates an intelligent Token Bucket bandwidth throttle (defaulting to 4 MB/s limits on heavy payloads) to prevent saturating the user's local network. TCP connect timeouts and keepalives guarantee connections drop gracefully under network partitions.
• Native OS File Handling: Files are robustly routed directly to the OS-native root Downloads directory across all platforms, shielding against path-traversal attacks (../).
• Integrity Guarantee: Each file includes a pre-transfer SHA-256 validation checksum ensuring payload integrity before final reconstruction.

📞 Ecosystem Continuity

• OS-Level Sleep Immunity: Deskdrop implements native API calls on each system to maintain seamless background connections.
  • macOS: Employs ProcessInfo.beginActivity to prevent Apple's App Nap from throttling background daemon syncs.
  • Windows: Utilizes SetThreadExecutionState to halt Modern Standby sleep transitions during active file transfers.
  • Android: Features OEM-specific battery restriction diagnostics (Xiaomi, Samsung) to actively prevent background service termination.
• Continuity Camera: Wirelessly stream your mobile device's camera feed directly to a native, edge-to-edge, bezel-less HUD on macOS. Built on a pure Core Animation layer for high-performance, hardware-accelerated JPEG rendering without UI letterboxing.
• Cross-Platform Call Continuity: Android devices track call states (ringing, offhook, idle) and relay them to macOS peers, bringing premium glassmorphic notification controls to remote screens.
• Telemetry & Battery Sync: Passive battery monitoring synchronizes device charge levels (0-100%) and charging states across peers.

🛡️ Resilience & Content Filtering

• Connection Retry Strategy: Employs an exponential back-off connection retry algorithm featuring ±25% randomized jitter to prevent thundering herd problems during network partitions.
• Content Filter Chain: Implements highly configurable payload filtering, including size limits, file extension block-lists (e.g., .exe, .sh), and sensitive-text heuristics to aggressively block OTPs, API keys, or passwords from bleeding out to other devices.

---

💻 Command-Line Interface (CLI) Usage

The deskdrop-cli binary communicates with the background Rust daemon over local IPC channels (Unix Domain Sockets / Windows Named Pipes). It offers a powerful admin utility for power users and automation scripts.

1. Daemon Management

# Start the core background daemon natively
cargo run -p deskdrop-core --bin deskdrop-daemon

# Check the health of the daemon
cargo run -p deskdrop-cli -- status
# Expected Output: Daemon is running. Active Connections: 3, Uptime: 4h 23m

# Safely shut down the background daemon
cargo run -p deskdrop-cli -- stop

2. Network & Telemetry

# Ping the daemon to test IPC latency
cargo run -p deskdrop-cli -- ping
# Expected Output: PONG (1.2ms)

# View real-time metrics (latency p50/p95, bandwidth throughput)
cargo run -p deskdrop-cli -- metrics

3. History & Activity Feed

# Query the most recent 20 items in the clipboard history
cargo run -p deskdrop-cli -- history --last 20

# Pin an item in the history so it isn't evicted
cargo run -p deskdrop-cli -- history pin <id>

# Add a custom tag to an item for searching later
cargo run -p deskdrop-cli -- history tag <id> "work"

# Export the entire history feed to a JSON file for backup
cargo run -p deskdrop-cli -- history export json > backup.json

# Clear all historical payloads from the ring buffer
cargo run -p deskdrop-cli -- history clear

4. Device Lifecycle & Trust Management

# List all discovered and paired devices
cargo run -p deskdrop-cli -- devices list

# Manually trust a device via its UUID (TOFU bypass)
cargo run -p deskdrop-cli -- devices trust <device-id>

# Temporarily pause or resume synchronization with a specific peer
cargo run -p deskdrop-cli -- devices peer-settings <device-id> pause
cargo run -p d