✅ Project status: Phases 0-21 are fully implemented. SecureSync performs real, fully autonomous, bidirectional peer-to-peer file sync end to end — verified by tests/integration/test_end_to_end_sync.py, which runs two real instances over real TCP and confirms a file created on one device is reconstructed correctly on the other, with no manual intervention. See ROADMAP.md for the full implementation history and docs/adr/ for 26 ADRs documenting every real bug found and fixed along the way.
- What is SecureSync?
- Architecture
- Features
- Installation
- Quick Start
- Configuration
- Documentation
- Benchmarks
- Roadmap
- Known Limitations
- FAQ
- Contributing
- Security
- Community
- License
SecureSync is a peer-to-peer file synchronization engine: devices discover each other on the network, establish an authenticated end-to-end encrypted channel, and synchronize only the parts of files that actually changed. No central server holds your data.
This isn't a toy that only passes its own tests — it's been pressure-tested against reality at every layer:
- 413 tests, 93% coverage, including a real end-to-end test (tests/integration/test_end_to_end_sync.py) that runs two independent instances over real TCP with real crypto and confirms a file actually reconstructs correctly on the other side.
- CI on 3 OSes × 2 Python versions (Ubuntu, macOS, Windows; 3.12/3.13) —
not just "works on my machine." Building this out caught real,
platform-specific bugs (a Windows-only
asynciosignal-handling crash, a macOS-only test race, a Windows-only timer-precision flake) that a single-platform setup would never have surfaced. - 26 Architecture Decision Records (docs/adr/) — a real, unfiltered account of every non-trivial design decision and every real bug found along the way (including bugs the end-to-end test caught that 413 passing unit tests had missed entirely, because they only existed at the boundary between two independent processes).
- Honest about what isn't finished — see Known Limitations below instead of a roadmap that quietly stops mentioning what's incomplete.
SecureSync is built with Clean Architecture — domain logic is fully isolated from infrastructure (filesystem, network, database), which keeps the core sync/conflict-resolution logic testable and every adapter (transport, cipher, discovery mechanism) independently swappable.
Full write-up: docs/architecture.md
flowchart LR
A[Filesystem Watcher] --> B[Chunk Engine]
B --> C[Delta Sync]
C --> D[Transfer Engine]
D <--> E[Peer Discovery]
D --> F[End-to-End Encryption]
C --> G[Conflict Resolution]
C --> H[(Metadata DB)]
- Real-time filesystem watching (create/modify/delete/rename/move)
- Streaming, bounded-memory chunking + SHA-256 hashing
- Delta synchronization: content-hash comparison against a recorded baseline
- Peer discovery (mDNS via zeroconf)
- TCP transfers with AEAD-encrypted binary wire protocol
- End-to-end encryption: X25519 key exchange, AES-256-GCM / ChaCha20-Poly1305
- Trust-on-first-use peer authentication (Ed25519 identity signing)
- Conflict resolution with version vectors and pluggable strategies
- SQLite-backed metadata store (files, chunks, version history)
- Synchronization Orchestrator with state machine and lifecycle control
- Version-aware sync direction (PUSH / PULL / CONFLICT / NOOP)
- Autonomous push receiver: an unsolicited pushed file is drained and reconstructed automatically, with no manual intervention
- CLI entry point (
securesyncinit / config / peers / sync / pull / daemon) — 100% test coverage - YAML configuration and production bootstrap with signal handling
(with a graceful fallback on platforms where
asynciodoesn't support signal handlers, e.g. Windows) - Verified end-to-end: two real instances, real TCP, real crypto — not just unit tests in isolation (see tests/integration/test_end_to_end_sync.py)
git clone https://github.com/Abolfazlrwm/SecureSync.git
cd SecureSync
pip install -e ".[dev]"# Initialize a new device identity and default config
securesync init --storage-dir ~/.securesync
# Show current configuration (secrets redacted by default)
securesync config
# List known peers and their trust status
securesync peers
# Start the sync daemon (discovers peers, syncs automatically)
securesync daemon
# Push specific files/directories to all discovered peers
securesync sync path/to/file.txt
# Pull a file from a specific peer
securesync pull path/to/file.txt --from <peer-device-id>
# Reset trust for a peer (e.g. after a key rotation)
securesync trust <peer-device-id>The YAML configuration system is fully implemented. The schema and all
available options are documented in
docs/configuration.md. Key sections: storage
(sync directory, database path, chunk size), network (handshake,
transfer, and manifest ports), device_id (auto-generated if omitted),
and log_level (default: INFO). See also
examples/config for working example files.
| Doc | Covers |
|---|---|
| docs/architecture.md | Clean Architecture layers, SOLID, design patterns, tech decisions, diagrams |
| docs/networking.md | Peer discovery, topology, connection lifecycle |
| docs/protocol.md | Binary wire protocol: header layout, packet types, handshake |
| docs/security.md | Cryptographic design and full threat model |
| docs/performance.md | Benchmark methodology and metrics tracked |
| docs/development.md | Local dev setup, testing conventions |
| docs/deployment.md | Docker, docker-compose, systemd, ports |
| docs/configuration.md | YAML schema, environment variables, hot reload |
| docs/troubleshooting.md | Common issues and diagnostics |
| docs/adr/ | Architecture Decision Records |
Benchmarks for chunking, hashing, encryption, and networking are implemented — see benchmarks/. Methodology is defined in docs/performance.md.
See ROADMAP.md for the full phase-by-phase plan.
A real answer, not a marketing one:
- The Phase 1 filesystem watcher exists and is fully tested, but isn't
wired into
main.pyyet. Right now, a device only syncs a file once something records it in the metadata store — the live watcher that would do this automatically on every save is a separate, already-built component waiting to be connected. Until then, treatsecuresync sync(explicit) as the supported path. - No compression, resumable transfers, or bandwidth/rate limiting yet. These are real, scoped items in ROADMAP.md's Advanced Features list, not silently dropped.
- The cryptographic protocol composition is not independently audited (see the FAQ below) — the primitives are, the specific way they're combined here isn't.
- Single-writer conflict resolution only (Last-Writer-Wins by default). True CRDT-style automatic merging for concurrent edits to the same file isn't implemented.
Why not just use Syncthing? You should, if you need a production-ready sync tool today — Syncthing is mature, battle-tested, and does far more than this. SecureSync exists to demonstrate real engineering practice end to end: Clean Architecture with enforced dependency direction, a real (not simulated) cross-device protocol, and a development process that documents every real bug found rather than hiding it. See Known Limitations for what it deliberately doesn't try to do yet.
Is the cryptography audited?
SecureSync only uses well-established primitives from the audited cryptography
(pyca) library — X25519 for key exchange, Ed25519 for identity, AES-256-GCM
/ ChaCha20-Poly1305 for AEAD. The composition of those primitives into a
protocol is not independently audited. See
docs/security.md for the full threat model.
Why does the README mention bugs you found in your own code? Because they're real, and hiding them wouldn't make the code better — see docs/adr/, especially ADR-0025 and ADR-0026, for two examples where two-process end-to-end testing caught real defects that hundreds of passing unit tests had missed.
See CONTRIBUTING.md for the development workflow, coding standards, and commit conventions.
See SECURITY.md for how to privately report a vulnerability, and docs/security.md for the full cryptographic design and threat model.
- Code of Conduct
- Issue templates — bug reports and feature requests
- Pull request template
- Architecture Decision Records — the "why" behind every major decision