enigma-protocol 0.1.0

High-level orchestrator that composes the Enigma crates into a production-ready messaging protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Protocol Flow

## Session Bootstrap

1. Upper layers derive or provision a 32-byte shared secret (for example via X3DH).
2. Both peers call `ensure_session_with` using the shared secret and their role (initiator or responder). This deterministically derives:
   - Conversation identifier (UUID)
   - Send/receive ratchet chains
   - Associated-data salt that binds user identities to the session
3. Sessions live entirely in memory. Applications decide when to persist or drop them.

## Sending

1. Build a packet-level message (text or attachment fragment).
2. Call `encrypt_message` which:
   - Encodes the `Message` via `enigma-packet`
   - Advances the ratchet to obtain a per-packet AEAD key
   - Encrypts the encoded bytes with `enigma-aead` using AD = conversation id + sender + receiver
3. Pass the ciphertext bytes to the active transport.

## Receiving

1. Transport delivers ciphertext bytes.
2. `decrypt_packet` pulls the next ratchet key, decrypts the AEAD envelope, and decodes the packet into a `Message`.
3. `MessengerClient::poll_once` emits a `ClientEvent` (`MessageReceived`, `AttachmentProgress`, `AttachmentCompleted`). Attachments are tracked by attachment id to enforce init → chunk → end ordering.

## Attachments

- `build_attachment_init`, `build_attachment_chunks`, and `build_attachment_end` construct the three-phase flow expected by `enigma-packet`.
- Each chunk is an individual message. Progress events expose chunk counts so applications can wire UI updates.