DeezChatz SDK Rust 🦀
The deezchatz-sdk-rust is a high-performance, asynchronous Rust client for the DeezChatz ecosystem. It abstracts the complexities of the Signal Protocol (X3DH, Double Ratchet), zero-trust VXEdDSA REST authentication, and real-time MQTT networking into an intuitive, developer-friendly interface.
This SDK is engineered for developers building CLI clients, automated bots, desktop apps, or backend services interfacing securely with DeezChatz.
Features
- Automated End-to-End Cryptography: Deeply integrated with
libsignal-dezireto manage Curve25519 Identity Keys, Signed Pre-Keys, One-Time Pre-Keys (OPKs), and active Double Ratchet ratchet states. - Zero-Trust Stateless REST Authentication: Signs every API request using VXEdDSA signatures and VRF proofs (
X-User-Id,X-Timestamp,X-Signature,X-Vrf), eliminating cookies and JWT vulnerabilities. - Dynamic MQTT Authentication: Generates time-bounded cryptographic signatures for broker passwords, automatically refreshing credentials during reconnection loops.
- Event-Driven MQTT Transport: Asynchronous
tokio::sync::mpsc::Receiverfor real-time events (Connected,Disconnected,MessageReceived). - Bring-Your-Own-Storage (BYOS): Decoupled storage model via async traits: [
KeyStore], [SessionStore], [InboxStore], and [OutboxStore]. - Crash Resilience & Delivery Guarantees:
- Raw incoming ciphertexts are saved to [
InboxStore] immediately upon MQTT packet arrival before decryption. - Outgoing messages are enqueued to [
OutboxStore] as pending, tracked in-flight, and marked sent only whenPUBACKis confirmed. - Graceful disconnection drains pending in-flight messages before closing sockets.
- Raw incoming ciphertexts are saved to [
- Rich Media Payload Framing: Native encoding and decoding for UTF-8 text, Opus voice notes, and JPEG image transfers with captions and timestamps.
Installation
Add deezchatz-sdk-rust to your Cargo.toml:
[]
= { = "../deezchatz-sdk-rust" } # or git repository
= { = "1", = ["full"] }
= "0.1"
Architecture Overview
+-----------------------------+
| DeezChatz Client |
+--------------+--------------+
|
+---------------------+---------------------+
| |
v v
+-------------------+ +-------------------+
| REST API Client | | MQTT Transport |
| (Stateless VXEdDSA| | (Rumqttc + TLS / |
| Signatures) | | Dynamic Passwords)|
+---------+---------+ +---------+---------+
| |
| POST /register/device | /deezchatz/{uid}/{did}/#
| POST /bundle/{identifier} | Inbound / Outbound
v v
+---------------------+ +---------------------+
| DeezChatz REST API | | DeezChatz Broker |
+---------------------+ +---------------------+
Protocol Flow
- Registration: The client creates Identity Keys, a Signed Pre-Key, a Signed Device Key, and a pool of One-Time Pre-Keys (OPKs). These are cryptographically signed and uploaded to the server via OAuth 2.0 PKCE.
- Session Initiation (X3DH): When sending a message to a new contact, the SDK requests their pre-key bundle (
POST /bundle/{id}), performs X3DH key agreement, initializes the Double Ratchet sender state, and attaches the ephemeral key to the first ciphertext. - Double Ratchet: Subsequent messages advance the sending and receiving ratchets, deriving ephemeral symmetric keys per message for forward and backward secrecy.
- Transport: Ciphertexts are transmitted over MQTT topic
/deezchatz/{recipient_user_id}/{recipient_device_id}/{sender_user_id}/{sender_device_id}.
Quick Start
1. Implement Storage Backend (BYOS)
Implement the four storage traits using your preferred backend (e.g. SQLite, SQLCipher, Sled, Redis):
use async_trait;
use ;
2. Client Initialization & Configuration
use Arc;
use ;
// Pre-configured environments:
let config = production; // https://api.chatz.deez.in, mqtt.deez.in:8883 (TLS)
// let config = ClientConfig::development(); // http://localhost:3000, localhost:1883
// let config = ClientConfig::from_env(); // Configured via DEEZCHATZ_* environment variables
let storage = new;
let mut client = new;
Environment Variables (ClientConfig::from_env())
| Variable | Default | Description |
|---|---|---|
DEEZCHATZ_API_URL |
https://api.chatz.deez.in |
REST API base URL |
DEEZCHATZ_MQTT_URL |
mqtt.deez.in |
MQTT broker hostname |
DEEZCHATZ_MQTT_PORT |
8883 |
MQTT broker port |
DEEZCHATZ_OPK_COUNT |
100 |
Number of One-Time Pre-Keys generated |
DEEZCHATZ_USE_TLS |
true (if port 8883) |
Whether to use TLS encryption |
3. Device Registration (OAuth 2.0 PKCE)
Device registration uses Google OAuth 2.0 with PKCE:
use oauth;
// 1. Generate code verifier and challenge
let verifier = generate_code_verifier;
let challenge = generate_code_challenge;
// 2. Build Google OAuth authorization URL
let auth_url = build_google_auth_url;
println!;
// 3. Complete registration using returned auth code
let auth_code = "4/0AeaYSH...";
client.register_with_pkce.await?;
println!;
println!;
4. Real-Time Messaging & Event Loop
use ;
// Connect to MQTT broker
let mut event_rx = client.connect.await?;
// Spawn real-time event processing loop
spawn;
5. Sending Messages
The SDK handles X3DH pre-key bundle fetching and ratchet establishment automatically on the first message sent to any recipient.
Sending Text Messages
let sent = client.send_text_message.await?;
println!;
Sending Voice Notes
let opus_audio_bytes = read?;
let sent = client.send_voice_message.await?;
Sending Images with Captions
let jpeg_bytes = read?;
let sent = client.send_image_message.await?;
Sending Custom or Encoded Payloads
let payload_bytes = payload.encode;
client.send_message.await?;
6. Contact Sync & Profile Inspection
To query a contact's profile without consuming a One-Time Pre-Key (OPK):
let profile = client.get_sync_bundle.await?;
println!;
println!;
println!;
7. Graceful Disconnection
// Waits up to 5 seconds for in-flight messages to receive PUBACK before disconnecting
client.disconnect.await?;
Payload Framing Specification
DeezChatz uses structured binary payload framing compatible with mobile and web clients:
| Type Byte | Message Type | Wire Layout |
|---|---|---|
0x00 |
Text | [0x00, ...utf8_bytes] |
0x01 |
Voice | [0x01, ...opus_audio_bytes] |
0x02 |
Image | [0x02, timestamp (4 bytes BE), caption_len (2 bytes BE), caption (...utf8_bytes), ...jpeg_bytes] |
Decoding & Encoding Utilities
use ;
// Encoding
let text_bytes = encode_text_payload;
let voice_bytes = encode_voice_payload;
let image_bytes = encode_image_payload;
// Decoding
let payload = decode_payload?;
assert_eq!;
API Method Reference
DeezChatzClient
| Method | Endpoint / Layer | Description |
|---|---|---|
new(config, keystore, sessionstore, inboxstore, outboxstore) |
Client Constructor | Instantiates a client with BYOS persistence |
register_with_pkce(code, verifier, redirect_uri, phone) |
POST /register/google/pkcePOST /register/device |
Complete registration via OAuth 2.0 PKCE auth code & uploads signed keys |
connect(user_id, device_id) |
MQTT Broker (/deezchatz/...) |
Connects to MQTT broker using signature-auth password; returns event receiver |
send_text_message(recipient, text) |
X3DH / Double Ratchet + MQTT | Encodes text (0x00) and sends end-to-end encrypted message |
send_voice_message(recipient, audio) |
X3DH / Double Ratchet + MQTT | Encodes voice (0x01) and sends end-to-end encrypted message |
send_image_message(recipient, image, caption) |
X3DH / Double Ratchet + MQTT | Encodes image (0x02) with current timestamp and optional caption |
send_message(recipient, payload_bytes) |
X3DH / Double Ratchet + MQTT | Sends raw binary payload end-to-end encrypted |
get_sync_bundle(target_user_id) |
GET /bundle/sync/{userId} |
Read-only profile and identity key lookup without consuming OPKs |
disconnect() |
MQTT Client | Waits for in-flight PUBACKs and gracefully terminates connection |
user_id() |
Local State | Returns authenticated user ID |
device_id() |
Local State | Returns registered device ID |
oauth Module
| Function | Description |
|---|---|
generate_code_verifier() |
Generates a cryptographically random URL-safe PKCE code verifier |
generate_code_challenge(verifier) |
Generates SHA-256 code challenge for PKCE S256 |
build_google_auth_url(client_id, redirect, challenge, scopes) |
Builds Google OAuth authorization URL |
Cryptographic Security
- X3DH (Extended Triple Diffie-Hellman): Initiates forward-secret sessions between parties, combining Identity Keys, Signed Pre-Keys, and One-Time Pre-Keys.
- Double Ratchet: Continuous key derivation for every message exchange; compromise of a single key reveals neither past nor future messages.
- VXEdDSA & VRF: Zero-trust authentication where every REST request and MQTT connection attempt is cryptographically verifiable using public keys.
- Constant-Time Operations: Cryptographic primitives provided by
libsignal-dezireanded25519-dalekdefend against side-channel timing attacks.
License
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).