Skip to main content

deezchatz_sdk/
lib.rs

1//! # DeezChatz SDK for Rust
2//!
3//! An asynchronous Rust SDK for the DeezChatz platform, providing end-to-end encryption
4//! via the Signal Protocol (X3DH and Double Ratchet), zero-trust REST authentication via
5//! VXEdDSA signatures and VRF proofs, and real-time messaging over MQTT.
6//!
7//! ## Core Architecture
8//!
9//! - **End-to-End Cryptography**: Deeply integrated with `libsignal-dezire` to manage Identity
10//!   Keys, Signed Pre-Keys, One-Time Pre-Keys (OPKs), and active Double Ratchet sessions.
11//! - **Zero-Trust Stateless Authentication**: Authenticates every REST request using cryptographic
12//!   VXEdDSA signatures (`X-User-Id`, `X-Timestamp`, `X-Signature`, `X-Vrf`).
13//! - **Real-Time MQTT Transport**: Connects to the DeezChatz MQTT broker with cryptographic password
14//!   tokens, receiving events via an asynchronous `tokio::sync::mpsc::Receiver`.
15//! - **Bring-Your-Own-Storage (BYOS)**: Abstract async traits for key persistence ([`KeyStore`]),
16//!   session state ([`SessionStore`]), incoming message queue ([`InboxStore`]), and outgoing
17//!   queue ([`OutboxStore`]).
18//! - **Guaranteed Delivery & Crash Resilience**: Unprocessed inbound messages and pending outbound
19//!   messages are safely persisted to disk to prevent data loss across crashes or network disruptions.
20//! - **Multi-Type Framed Payloads**: Native support for UTF-8 text, Opus voice notes, and JPEG image
21//!   transfers with captions and timestamps.
22//!
23//! ## Quick Start
24//!
25//! ```no_run
26//! use std::sync::Arc;
27//! use deezchatz_sdk::{DeezChatzClient, ClientConfig, Event, decode_payload, DecodedPayload};
28//! # use deezchatz_sdk::{KeyStore, SessionStore, InboxStore, OutboxStore, SdkError};
29//! # use async_trait::async_trait;
30//! # struct DummyStore;
31//! # #[async_trait] impl KeyStore for DummyStore {
32//! #     async fn save_identity_key(&self, _: &[u8; 32], _: &[u8; 33]) -> Result<(), SdkError> { Ok(()) }
33//! #     async fn get_identity_key(&self) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
34//! #     async fn save_signed_pre_key(&self, _: u32, _: &[u8; 32], _: &[u8; 33]) -> Result<(), SdkError> { Ok(()) }
35//! #     async fn get_signed_pre_key(&self, _: u32) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
36//! #     async fn save_one_time_pre_keys(&self, _: Vec<(u32, [u8; 32], [u8; 33])>) -> Result<(), SdkError> { Ok(()) }
37//! #     async fn consume_one_time_pre_key(&self, _: u32) -> Result<Option<([u8; 32], [u8; 33])>, SdkError> { Ok(None) }
38//! # }
39//! # #[async_trait] impl SessionStore for DummyStore {
40//! #     async fn save_session(&self, _: &str, _: &[u8]) -> Result<(), SdkError> { Ok(()) }
41//! #     async fn get_session(&self, _: &str) -> Result<Option<Vec<u8>>, SdkError> { Ok(None) }
42//! #     async fn delete_session(&self, _: &str) -> Result<(), SdkError> { Ok(()) }
43//! # }
44//! # #[async_trait] impl InboxStore for DummyStore {
45//! #     async fn save_to_inbox(&self, _: &str, _: &[u8]) -> Result<i64, SdkError> { Ok(1) }
46//! #     async fn mark_inbox_processed(&self, _: i64) -> Result<(), SdkError> { Ok(()) }
47//! #     async fn mark_inbox_failed(&self, _: i64, _: &str) -> Result<(), SdkError> { Ok(()) }
48//! #     async fn get_pending_inbox(&self) -> Result<Vec<deezchatz_sdk::InboxEntry>, SdkError> { Ok(vec![]) }
49//! # }
50//! # #[async_trait] impl OutboxStore for DummyStore {
51//! #     async fn save_to_outbox(&self, _: &str, _: &str, _: &str, _: &[u8]) -> Result<i64, SdkError> { Ok(1) }
52//! #     async fn mark_outbox_sent(&self, _: i64) -> Result<(), SdkError> { Ok(()) }
53//! #     async fn mark_outbox_failed(&self, _: i64, _: &str) -> Result<(), SdkError> { Ok(()) }
54//! #     async fn get_pending_outbox(&self) -> Result<Vec<deezchatz_sdk::OutboxEntry>, SdkError> { Ok(vec![]) }
55//! # }
56//!
57//! #[tokio::main]
58//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
59//!     let config = ClientConfig::production();
60//!     let store = Arc::new(DummyStore);
61//!
62//!     let mut client = DeezChatzClient::new(
63//!         config,
64//!         store.clone(),
65//!         store.clone(),
66//!         store.clone(),
67//!         store.clone(),
68//!     );
69//!
70//!     // Connect to the real-time MQTT broker
71//!     let mut event_rx = client.connect("my-user-id", "my-device-id").await?;
72//!
73//!     // Process incoming messages
74//!     tokio::spawn(async move {
75//!         while let Some(event) = event_rx.recv().await {
76//!             if let Event::MessageReceived { sender, plaintext } = event {
77//!                 if let Ok(payload) = decode_payload(&plaintext) {
78//!                     match payload {
79//!                         DecodedPayload::Text { text } => println!("{}: {}", sender, text),
80//!                         DecodedPayload::Voice { audio_bytes } => println!("Voice note ({} bytes)", audio_bytes.len()),
81//!                         DecodedPayload::Image { caption, image_bytes, .. } => println!("Image '{}' ({} bytes)", caption, image_bytes.len()),
82//!                     }
83//!                 }
84//!             }
85//!         }
86//!     });
87//!
88//!     // Send an encrypted text message
89//!     let sent = client.send_text_message("recipient-id", "Hello!").await?;
90//!     println!("Message sent with ID: {}", sent.message_id);
91//!
92//!     client.disconnect().await?;
93//!     Ok(())
94//! }
95//! ```
96
97pub mod client;
98pub mod crypto;
99pub mod error;
100pub mod messaging;
101pub mod oauth;
102pub mod transport;
103
104pub use client::{ClientConfig, DeezChatzClient, SentMessage};
105pub use error::SdkError;
106pub use messaging::{
107    decode_payload, encode_image_payload, encode_text_payload, encode_voice_payload,
108    DecodedPayload, InboxEntry, InboxStore, KeyStore, MessageStatus, OutboxEntry, OutboxStore,
109    PayloadError, SessionStore, PAYLOAD_TYPE_IMAGE, PAYLOAD_TYPE_TEXT, PAYLOAD_TYPE_VOICE,
110};
111pub use transport::Event;
112pub use transport::SyncBundleResponse;
113
114pub use base64;
115pub use libsignal_dezire;