zoe_wire_protocol/
lib.rs

1//! # Zoe Wire Protocol
2//!
3//! The wire protocol crate provides the core messaging infrastructure for the Zoe distributed
4//! messaging system. It defines message formats, cryptographic primitives, transport security,
5//! and RPC service interfaces.
6//!
7//! ## Key Features
8//!
9//! - **Versioned Message Protocol**: Forward-compatible message types with multiple encryption schemes
10//! - **Hybrid Cryptography**: Support for both Ed25519 (legacy) and ML-DSA (post-quantum) signatures
11//! - **Multiple Content Types**: Raw, ChaCha20-Poly1305, self-encrypted, and ephemeral ECDH encryption
12//! - **Transport Security**: TLS certificate generation with embedded identity keys
13//! - **RPC Services**: [`MessageService`] and [`BlobService`] for relay communication
14//! - **Streaming Protocol**: Real-time message subscriptions and filtering
15//! - **Challenge-Response Authentication**: Dynamic session management with configurable timeouts
16//!
17//! ## Quick Start
18//!
19//! ```rust
20//! use zoe_wire_protocol::{
21//!     MessageFull, Message, MessageV0, MessageV0Header, Content, Kind,
22//!     KeyPair, VerifyingKey, SigningKey
23//! };
24//! use rand::rngs::OsRng;
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! // Create a keypair (supports Ed25519, ML-DSA-44, ML-DSA-65, ML-DSA-87)
28//! let keypair = KeyPair::generate(&mut OsRng);
29//! let verifying_key = keypair.public_key();
30//!
31//! // Create message content (multiple encryption options available)
32//! let content = Content::raw(b"Hello, Zoeyr!".to_vec());
33//!
34//! // Create message header
35//! let header = MessageV0Header {
36//!     sender: verifying_key.clone(),
37//!     when: std::time::SystemTime::now()
38//!         .duration_since(std::time::UNIX_EPOCH)
39//!         .unwrap()
40//!         .as_secs(),
41//!     kind: Kind::Regular,
42//!     tags: vec![], // Optional: Tag::Event, Tag::User, Tag::Channel, Tag::Protected
43//! };
44//!
45//! // Create versioned message
46//! let message = Message::new_v0_raw(
47//!     content.as_raw().unwrap().clone(),
48//!     verifying_key,
49//!     header.when,
50//!     header.kind,
51//!     header.tags
52//! );
53//!
54//! // Create full message with signature
55//! let message_full = MessageFull::new(message, &keypair)?;
56//!
57//! // Access message properties
58//! println!("Message ID: {}", message_full.id());
59//! # Ok(())
60//! # }
61//! ```
62//!
63//! ## Message Structure
64//!
65//! Messages follow a versioned, forward-compatible structure:
66//!
67//! ```text
68//! MessageFull
69//! ├── id: Hash                    // Blake3 hash (computed from signature)
70//! ├── signature: Signature        // Digital signature (Ed25519 or ML-DSA)
71//! └── message: Message            // Versioned message content
72//!     └── V0(MessageV0)
73//!         ├── header: MessageV0Header
74//!         │   ├── sender: VerifyingKey
75//!         │   ├── when: u64
76//!         │   ├── kind: Kind
77//!         │   └── tags: Vec<Tag>
78//!         └── content: Content    // Payload with encryption options
79//! ```
80//!
81//! ## Content Encryption
82//!
83//! The protocol supports multiple encryption schemes:
84//!
85//! - [`Content::Raw`] - Unencrypted content
86//! - [`Content::ChaCha20Poly1305`] - Context-based encryption with shared keys
87//! - [`Content::Ed25519SelfEncrypted`] - Self-encryption using Ed25519 keys
88//! - [`Content::MlDsaSelfEncrypted`] - Self-encryption using ML-DSA keys (post-quantum)
89//! - [`Content::EphemeralEcdh`] - Public key encryption with perfect forward secrecy
90//!
91//! ## RPC Services
92//!
93//! The crate defines two main services for relay communication:
94//!
95//! - [`MessageService`] - Message publishing, retrieval, and real-time subscriptions
96//! - [`BlobService`] - Binary blob storage and retrieval
97//!
98//! ## Transport Security
99//!
100//! TLS certificates can embed identity keys for authentication:
101//!
102//! ```rust
103//! use zoe_wire_protocol::{generate_ed25519_cert_for_tls, extract_ed25519_public_key_from_cert};
104//! # use rand::rngs::OsRng;
105//!
106//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
107//! // Generate Ed25519 certificate
108//! let ed25519_key = ed25519_dalek::SigningKey::generate(&mut OsRng);
109//! let certs = generate_ed25519_cert_for_tls(&ed25519_key, "example.com")?;
110//! let extracted_key = extract_ed25519_public_key_from_cert(&certs[0])?;
111//! # Ok(())
112//! # }
113//! ```
114//!
115//! ## Serialization
116//!
117//! All data structures use [postcard](https://docs.rs/postcard/) for efficient binary serialization:
118//!
119//! ```rust
120//! use zoe_wire_protocol::MessageFull;
121//! # use zoe_wire_protocol::*;
122//! # fn example(message_full: MessageFull) -> std::result::Result<(), Box<dyn std::error::Error>> {
123//!
124//! // Serialize for transmission
125//! let bytes = postcard::to_stdvec(&message_full)?;
126//!
127//! // Deserialize received data
128//! let received: MessageFull = postcard::from_bytes(&bytes)?;
129//! # Ok(())
130//! # }
131//! ```
132
133pub mod blob;
134pub mod challenge;
135pub mod connection;
136pub mod connection_info;
137pub mod crypto;
138pub mod inbox;
139pub mod invitation;
140pub mod keys;
141pub mod message;
142pub mod primitives;
143pub mod relay;
144pub mod services;
145pub mod streaming;
146pub mod version;
147
148pub use blob::*;
149pub use challenge::*;
150pub use connection_info::*;
151pub use crypto::*;
152pub use inbox::*;
153pub use invitation::{
154    generate_ephemeral_group_invite_id, GroupInvitationData, GroupMetadata, HandshakePurpose,
155    HandshakeResponse, ProfileSetEvent, UserProfile, VerificationHandshakeRequest,
156};
157pub use message::*;
158pub use relay::*;
159pub use services::*;
160pub use streaming::*; // Re-export streaming protocol types
161pub use version::*; // Re-export protocol version negotiation types
162
163pub use primitives::*;
164// Re-export keys types for convenient access
165pub use keys::*;
166
167// Re-export ML-DSA utility functions for message crypto
168pub use crypto::{
169    generate_ml_dsa_from_mnemonic, recover_ml_dsa_from_mnemonic, MlDsaSelfEncryptedContent,
170};
171// Re-export bip39 for mnemonic functionality
172pub use bip39;
173
174// Re-export Ed25519 types
175pub use ed25519_dalek::SigningKey as Ed25519SigningKey;
176pub use ed25519_dalek::VerifyingKey as Ed25519VerifyingKey;
177
178// Hash type alias
179pub type Hash = blake3::Hash;
180
181/// Convinience function to creates from simple byte slices
182pub fn hash(data: &[u8]) -> Hash {
183    blake3::hash(data)
184}
zoe_wire_protocol/lib.rs

zoe_wire_protocol/
lib.rs
