Skip to content
itsVentiePublic

About

Marrow is an experimental, zero-trust desktop messenger designed for high-performance and future-proof privacy. Powered by Rust, Tauri v2, and Preact, it combines hybrid post-quantum cryptography (ML-KEM-768 + X25519) with Double Ratchet E2EE and libp2p networking.

Topics

Resources

Contributing

Security policy

Stars

14 stars

Watchers

1 watching

Forks

Repository files navigation

Marrow

photo_2026-07-31_13-27-56

Warning

This project is under active development. The current version may contain bugs, incomplete or non-functional features, and breaking changes without prior notice. Use at your own risk.

High-performance, zero-trust, post-quantum resilient desktop communication suite built with Rust, Tauri v2, and Preact.


Security & Architectural Principles

Marrow follows a zero-trust security model centered around local cryptographic identities and end-to-end encrypted communication.

1. Identity & Cryptography

  • Local Identity: Ed25519-based identities are generated locally and do not require email addresses, phone numbers, or a centralized account provider.

  • Hybrid Key Exchange: Session establishment uses X25519 together with ML-KEM-768 to provide hybrid classical/post-quantum key agreement.

  • Forward Secrecy: One-to-one sessions use a Double Ratchet design to continuously evolve message encryption keys.

  • Authenticated Encryption: Application payloads are protected using modern AEAD primitives.

  • Key Hygiene: Sensitive cryptographic material is explicitly zeroized where supported. OS-level memory locking is planned and is not currently assumed as a universal security guarantee.

2. Networking

  • Peer-to-Peer Networking: The client uses a libp2p-based networking stack with encrypted transports and NAT traversal components.

  • Relay Infrastructure: Marrow includes an experimental in-memory relay for peer routing and bounded offline delivery.

  • Traffic Metadata: Fixed-size padding and timing randomization are being developed to reduce metadata leakage. These mechanisms do not currently provide complete protection against traffic analysis.

3. Local Storage

  • Encrypted Persistence: Persistent application records are encrypted before being stored in the local database.

  • Local Search: Tantivy provides local full-text search. Protecting search indexes at rest is an active security-hardening task.

  • Key Lifecycle: Storage keys and session state are intended to be destroyed when the application is securely locked or logged out.

4. Threat Model

Marrow is designed to reduce exposure to:

  • passive network interception;
  • compromised relay infrastructure;
  • local database disclosure;
  • future cryptanalytic attacks against classical key exchange;
  • unauthorized modification of network messages.

Marrow does not yet claim protection against:

  • a compromised endpoint;
  • a malicious operating system;
  • a fully compromised client runtime;
  • traffic-analysis attacks;
  • a malicious or compromised identity authority;
  • all metadata leakage;
  • physical compromise of an unlocked device.

Tech Stack

Layer Technology Status
Frontend Preact + TypeScript + Vite Active
Desktop Runtime Tauri v2 Active
Core Engine Rust Active
P2P Networking libp2p Active
QUIC Transport libp2p QUIC Active
Relay Server Quinn Experimental
Transport Security libp2p Noise / QUIC TLS Active
Serialization Serde + Bincode Active
Local Storage redb + XChaCha20-Poly1305 Active
Local Search Tantivy Active, at-rest encryption pending
Identity Ed25519 Active
Key Exchange X25519 + ML-KEM-768 Active
Session Security Double Ratchet Active, integration hardening pending
Audio/Video WebRTC + Opus Planned

Project Status & Engineering Metrics

Status: Experimental prototype
Production readiness: Not yet claimed
Last reviewed: YYYY-MM-DD

Area Status Current state
Core Rust architecture 🟢 Active Modular workspace with separated crypto, protocol, storage, and networking crates
Identity & cryptography 🟡 Hardening Ed25519, X25519, ML-KEM-768, XChaCha20-Poly1305 implemented
Hybrid handshake 🟡 Hardening Hybrid primitives and session construction implemented; authentication and transcript binding pending
Double Ratchet 🟡 Integration Ratchet primitives implemented; complete application-level integration pending
Local storage 🟡 Hardening Encrypted records implemented; search-index protection and key lifecycle hardening pending
P2P networking 🟡 Experimental libp2p TCP/QUIC stack implemented; relay architecture still under development
Desktop client 🟡 Incomplete Core application flow exists; several UI components remain unfinished
End-to-end verification 🔴 Incomplete Full Alice → Bob application-level E2E path is not yet covered
Traffic-analysis resistance 🔴 Experimental Padding and jitter exist; effectiveness has not yet been independently evaluated
External security review ⚪ Not performed No independent cryptographic/security audit has been completed

Current Verification Metrics

Metric Value Verification
Rust tests TBD cargo test --workspace
Frontend typecheck TBD CI
Frontend production build TBD CI
Full application E2E tests 0 Planned
Fuzz targets 0 Planned
Independent security audits 0 Not yet performed
Published performance benchmarks 0 Planned

Metrics are only published when they are reproducible from a documented command, benchmark, or CI workflow. Unverified performance or security claims are intentionally omitted.

Detailed benchmark methodology and historical results will be maintained in docs/benchmarks/.


Roadmap

Roadmap status reflects the actual implementation state of the repository. Features are marked as completed only when they are implemented and sufficiently tested. Experimental and research features are explicitly separated from the stable 1-to-1 messaging core.

Legend

  • Implemented and verified
  • [~] Partially implemented / requires hardening or integration work
  • Planned
  • [!] Blocked by a prerequisite

Phase 0: Project Foundation & Engineering Infrastructure
  • Cargo workspace and modular crate architecture.
  • Rust core engine and Tauri v2 desktop shell.
  • Preact + TypeScript + Vite frontend.
  • Basic Rust ↔ Tauri IPC layer.
  • Versioned Git hooks.
  • Workspace formatting and linting configuration.
  • Automated Rust test workflow.
  • [~] Fix all current cargo fmt --check failures.
  • Add frontend dependency installation to CI.
  • Add frontend type checking to CI.
  • Add frontend production build to CI.
  • Add release artifact verification.
  • Add dependency auditing (cargo audit, cargo deny).
  • Add SBOM generation for release artifacts.
  • Pin and document supported toolchain versions.
  • Define semantic versioning and protocol compatibility policy.
Phase 1: Identity, Key Management & Local Cryptographic Foundation
  • Ed25519 identity generation.
  • Deterministic identity derivation from BIP-39 seed material.
  • Argon2id-based local identity protection.
  • X25519 key agreement primitives.
  • ML-KEM-768 key encapsulation primitives.
  • XChaCha20-Poly1305 authenticated encryption.
  • Cryptographic key zeroization in implemented sensitive structures.
  • [~] Complete zeroization audit across all crates.
  • Define explicit key hierarchy for identity, storage, sessions, and application data.
  • Add key-version identifiers to persistent cryptographic material.
  • Implement secure key rotation.
  • Implement identity backup/export using BIP-39.
  • Implement identity restore/import using BIP-39.
  • Add backup integrity verification and checksum validation.
  • Add secure identity deletion.
  • Add password/passphrase change with safe key migration.
  • Document identity recovery and compromise semantics.
Phase 2: Authenticated Hybrid Session Establishment
  • X25519 + ML-KEM-768 hybrid key exchange primitives.
  • Hybrid handshake state structures.
  • Initial Double Ratchet state construction primitives.
  • [~] Complete initiator/responder application integration.
  • Fix responder ephemeral X25519 keypair mismatch between handshake and Double Ratchet initialization.
  • Authenticate the handshake using Ed25519 identity signatures.
  • Bind the authenticated identity to the ephemeral X25519 key.
  • Bind ML-KEM material to the authenticated transcript.
  • Define canonical transcript serialization.
  • Include protocol version and cryptographic suite identifiers in the transcript.
  • Derive session secrets from the complete authenticated transcript.
  • Bind the application identity to the transport identity / PeerId.
  • Reject malformed, replayed, or inconsistent handshake states.
  • Add explicit handshake timeout and cancellation handling.
  • Add handshake state cleanup after failure.
  • Add deterministic handshake test vectors.
  • Add negative tests for MITM, key substitution, replay, malformed ciphertext, and transcript modification.
Phase 3: Reliable 1-to-1 End-to-End Messaging
  • Double Ratchet root/send/receive chain implementation.
  • DH ratchet implementation.
  • Message counters and previous-chain-length handling.
  • Skipped-message key storage.
  • Maximum skipped-message limits.
  • AEAD-protected message payloads.
  • [~] Complete application-level session integration.
  • Pass a complete Alice → Bob encrypted message.
  • Pass a complete Bob → Alice encrypted response.
  • Support out-of-order message delivery.
  • Support delayed messages using skipped keys.
  • Support dropped packets and retransmission.
  • Support concurrent message sends.
  • Queue messages while a handshake is in progress.
  • Securely persist ratchet state.
  • Recover ratchet state after application restart.
  • Verify bidirectional session establishment from fresh identities.
  • Verify messaging after simultaneous session establishment attempts.
  • Verify ratchet continuity across application restart.
  • Verify session state consistency after concurrent sends.
  • Detect and reject stale/replayed messages.
  • Add message-level authentication failure handling.
  • Remove duplicated ratchet header fields from the wire protocol.
  • Define a single canonical encrypted-message representation.
  • Add protocol versioning to encrypted message frames.
Phase 4: Secure Local Persistence & Recovery
  • Embedded redb storage.
  • Encrypted persistent records using XChaCha20-Poly1305.
  • Contact persistence.
  • Session persistence.
  • Message persistence.
  • Tantivy-based local search integration.
  • [~] Protect search index contents at rest.
  • Encrypt or otherwise protect Tantivy index files.
  • Implement persistent search writer/worker instead of opening and committing a writer for every message.
  • Define storage encryption key lifecycle.
  • Zeroize storage keys on logout.
  • Clear storage keys from application state after lock.
  • Securely destroy in-memory session and ratchet state on logout.
  • Implement crash-safe storage recovery.
  • Implement schema/version migrations.
  • Implement encrypted database backup/restore.
  • Test corrupted database recovery.
  • Test interrupted writes and process crashes.
  • Document what metadata remains observable locally.
Phase 5: Network Transport & Blind Relay Hardening
  • libp2p-based networking layer.
  • TCP transport.
  • libp2p QUIC transport.
  • Noise-secured libp2p transport.
  • Yamux stream multiplexing.
  • Kademlia integration.
  • Identify integration.
  • Ping integration.
  • AutoNAT integration.
  • DCUtR integration.
  • Relay client components.
  • Quinn-based relay server prototype.
  • In-memory active peer routing.
  • Bounded offline message queues.
  • TTL-based queue eviction.
  • [~] Unify the libp2p client relay architecture with the Quinn relay.
  • Define a single production transport architecture.
  • Implement authenticated relay registration.
  • Add relay connection lifecycle identifiers.
  • Fix duplicate-connection cleanup races.
  • Add relay rate limiting.
  • Add per-peer memory limits.
  • Add global queue limits.
  • Add connection limits.
  • Add backpressure.
  • Add relay abuse / flooding protection.
  • Add persistent production TLS certificates.
  • Add proper relay certificate validation.
  • Add secure relay deployment configuration.
  • Add recipient routing information to initial handshake frames.
  • Define an outer routing envelope independent from E2EE payloads.
  • Align network codec and protocol frame size limits.
  • Add malformed-frame and oversized-frame tests.
  • Add network partition and reconnection tests.
Phase 6: Traffic Analysis Resistance
  • Fixed-size message padding primitives.
  • Binary frame padding.
  • [~] Timing jitter.
  • Implement a real dummy-traffic scheduler.
  • Implement configurable cover traffic policies.
  • Define traffic generation limits and battery/CPU constraints.
  • Evaluate metadata leakage under realistic traffic analysis.
  • Benchmark padding overhead.
  • Document exactly which metadata remains visible to relays.
  • Avoid claiming protection against traffic analysis that has not been empirically evaluated.
Phase 7: Desktop Client Completion
  • Basic dashboard.
  • Contact management.
  • Conversation state management.
  • Basic chat screen.
  • Tauri event-based message delivery.
  • Logout flow.
  • [~] Complete chat component hierarchy.
  • Implement message list virtualization.
  • Implement message composer.
  • Implement chat header.
  • Implement conversation list/sidebar.
  • Implement profile UI.
  • Implement settings UI.
  • Implement connection status UI.
  • Implement handshake/session status UI.
  • Implement backup/restore UI.
  • Implement identity management UI.
  • Implement secure lock/unlock state.
  • Add application auto-lock.
  • Add secure clipboard handling.
  • Add accessibility and keyboard navigation.
  • Add localization infrastructure.
  • Add desktop notifications without leaking message contents.
  • Add OS-specific secure storage integrations where appropriate.
Phase 8: Security Hardening & Verification
  • Build a complete in-process Alice/Bob end-to-end test.
  • Test identity creation → handshake → encryption → delivery → decryption → storage → restart → continued messaging.
  • Test out-of-order messages.
  • Test duplicate messages.
  • Test replay attacks.
  • Test malformed protocol frames.
  • Test invalid cryptographic keys.
  • Test failed authentication.
  • Test network interruption and recovery.
  • Test relay restart.
  • Test client restart.
  • Test storage corruption.
  • Add cargo-fuzz targets for protocol parsing.
  • Add fuzzing for handshake state transitions.
  • Add fuzzing for Double Ratchet state transitions.
  • Add fuzzing for storage deserialization.
  • Run Miri where applicable.
  • Run AddressSanitizer / relevant sanitizers where applicable.
  • Run dependency vulnerability audits.
  • Perform cryptographic API misuse audit.
  • Perform Tauri IPC security audit.
  • Define and enforce a strict Content Security Policy.
  • Minimize Tauri capabilities and filesystem access.
  • Audit all filesystem paths exposed through IPC.
  • Add rate limiting to expensive cryptographic operations.
  • Add resource exhaustion tests.
  • Publish reproducible security test results.
  • Perform an independent cryptographic/security review before production security claims.
  • Establish reproducible benchmark environment.
  • Add criterion benchmarks for cryptographic operations.
  • Benchmark X25519 key agreement.
  • Benchmark ML-KEM-768 encapsulation/decapsulation.
  • Benchmark Ed25519 signing/verification.
  • Benchmark AEAD encryption/decryption.
  • Benchmark Double Ratchet message processing.
  • Benchmark encrypted storage reads/writes.
  • Benchmark Tantivy indexing/search.
  • Benchmark relay throughput.
  • Benchmark relay memory consumption per connected peer.
  • Benchmark message delivery latency.
  • Benchmark handshake latency.
  • Publish benchmark methodology and hardware/software environment.
  • Track benchmark regressions in CI.
Phase 9: Memory Protection & Local Privacy
  • Implement OS memory locking (mlock / VirtualLock) where supported.
  • Define portable fallback behavior when memory locking is unavailable.
  • Complete zeroization audit for ratchet keys and skipped keys.
  • Zeroize storage encryption keys on lock/logout.
  • Minimize plaintext lifetime in memory.
  • Implement secure application lock.
  • Implement panic mode.
  • Define secure local data destruction semantics.
  • Add optional encrypted temporary-file handling.
  • Audit crash dumps and logging for sensitive data.
  • Ensure production logging never contains plaintext message contents or cryptographic secrets.
Phase 10: Group Messaging & Multi-Party Sessions
  • Evaluate IETF Messaging Layer Security (MLS).
  • Design group identity and membership model.
  • Implement group session state machine.
  • Implement authenticated group membership changes.
  • Implement member addition/removal.
  • Implement group key rotation.
  • Implement group state persistence.
  • Implement group state recovery after restart.
  • Design blind group relay routing.
  • Define group metadata minimization.
  • Add group replay and state-conflict handling.
  • Add group synchronization and recovery.
  • Add comprehensive multi-party integration tests.

Group messaging will not be considered production-ready until the 1-to-1 authenticated session and ratchet implementation is stable.

Phase 11: Voice, Video & Real-Time Media
  • Design E2EE media session architecture.
  • Implement encrypted signaling over the Marrow protocol.
  • Implement WebRTC connectivity.
  • Implement DTLS-SRTP media transport.
  • Integrate Opus audio.
  • Implement adaptive bitrate control.
  • Implement voice activity detection.
  • Implement echo cancellation / noise suppression where supported.
  • Implement call lifecycle state machine.
  • Implement call recovery after network changes.
  • Add media permission handling.
  • Add call UI and background call state.
  • Evaluate post-quantum protection for media session establishment.
  • Benchmark CPU, latency, bandwidth, and battery consumption.
Phase 12: Anonymity & Advanced Privacy
  • Define Marrow's anonymity threat model.
  • Document what IP and metadata are visible to peers and relays.
  • Implement proxy support.
  • Implement SOCKS5 support.
  • Evaluate Tor integration.
  • Evaluate multi-hop relay routing.
  • Implement onion-style routing only after the threat model and routing protocol are formally specified.
  • Evaluate traffic-analysis resistance experimentally.
  • Add relay rotation policies.
  • Add relay trust minimization.
  • Add privacy-preserving relay discovery.
  • Document limitations of anonymity guarantees.
Phase 13: Cryptographic Agility & Hardware Security
  • Define versioned cryptographic suite identifiers.
  • Implement explicit protocol capability negotiation.
  • Implement safe cryptographic suite migration.
  • Add ML-DSA support where justified by the threat model.
  • Evaluate hybrid Ed25519 + ML-DSA identity signatures.
  • Add hardware-backed key storage support.
  • Evaluate FIDO2 / WebAuthn integration.
  • Evaluate PKCS#11 support.
  • Support optional hardware-backed identity authorization.
  • Define migration procedures for compromised or deprecated keys.
Phase 14: Relay Infrastructure & Research
  • Design authenticated relay discovery.
  • Implement decentralized relay discovery.
  • Implement cryptographically signed relay descriptors.
  • Add relay health checks.
  • Add relay capacity advertisement.
  • Add relay load balancing.
  • Add privacy-preserving relay telemetry.
  • Evaluate eBPF-based observability for Linux relay deployments.
  • Add optional operator metrics without collecting message contents.
  • Build relay fleet deployment tooling.
  • Build reproducible relay container images.
  • Add automated relay integration environments.

Research infrastructure must not become a dependency of the secure 1-to-1 messaging core.


Testing & Quality Assurance

Marrow currently contains unit and integration tests covering cryptographic primitives, protocol serialization, storage persistence, and selected networking components.

The project is still missing a complete end-to-end client test covering:

identity creation → authenticated handshake → Double Ratchet → network transport → message delivery → decryption → persistence → application restart → continued messaging.

Until this path is covered by automated tests, Marrow should be considered an experimental prototype rather than a production-ready messenger.

Local Git Hooks Setup

To automatically run pre-commit checks (cargo fmt, cargo clippy, and cargo test) before every commit, enable the repository's versioned hooks:

git config core.hooksPath .githooks

Code Quality & Linting

Before submitting changes, ensure your code passes all formatting and linter checks:

# Check code formatting across the entire workspace
cargo fmt --all -- --check

# Run clippy static analysis and lints
cargo clippy --workspace -- -D warnings

Running Tests

Execute the full workspace test suite:

cargo test --workspace

Building Locally

Prerequisites

  • Rust: 1.78.0 or newer
  • Node.js: v20+
  • pnpm: required for the frontend workspace
  • Tauri CLI: v2.x
  • Git: required for cloning the repository

Platform-specific Tauri dependencies may also be required. See the Tauri prerequisites documentation for the required system packages for your operating system.

Clone the Repository

git clone https://github.com/itsVentie/Marrow.git
cd Marrow

Install Frontend Dependencies

cd apps/Marrow
pnpm install

Development

Run the Tauri desktop application in development mode:

pnpm tauri dev

Production Build

Build the application using Tauri's production build pipeline:

pnpm tauri build

The generated release artifacts are placed in the Tauri build output directory under:

apps/Marrow/src-tauri/target/release/bundle/

The exact artifact format depends on the target operating system.

Rust Checks

From the repository root:

cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspace

Frontend Checks

From apps/Marrow:

pnpm install
pnpm build

Git Hooks

Marrow includes versioned Git hooks for local development. Enable them with:

git config core.hooksPath .githooks

This enables the repository's configured pre-commit checks.

Troubleshooting

If the Tauri build fails because of missing system dependencies, verify that the platform-specific prerequisites listed in the Tauri documentation are installed.

If Rust dependencies or generated build artifacts become inconsistent, clean the workspace and rebuild:

cargo clean
pnpm tauri build

For development issues, check the Rust, Node.js, pnpm, and Tauri CLI versions:

rustc --version
cargo --version
node --version
pnpm --version
cargo tauri --version

Contributing & Security

  • For development guidelines, branch strategies, and PR expectations, read CONTRIBUTING.md.
  • To report a security vulnerability or cryptographic flaw, review our SECURITY.md.

License

Licensed under GPLv3.

About

Marrow is an experimental, zero-trust desktop messenger designed for high-performance and future-proof privacy. Powered by Rust, Tauri v2, and Preact, it combines hybrid post-quantum cryptography (ML-KEM-768 + X25519) with Double Ratchet E2EE and libp2p networking.

Topics

Resources

Contributing

Security policy

Stars

14 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages