279 lines
17 KiB
Markdown
279 lines
17 KiB
Markdown
# Meow v2 — Architecture Rust
|
||
|
||
Ce document décrit la ré-architecture de `meowlib` / `meowsrv` / `meowcli` / `meowjsonlib`
|
||
en Rust. La progression est suivie dans [`ROADMAP.md`](ROADMAP.md).
|
||
|
||
> **Décision** : protocole **v2 en rupture nette**, sans compatibilité réseau avec la v1 en Go
|
||
> (OpenPGP). Les clients et serveurs v1 et v2 ne communiquent pas entre eux. La migration se
|
||
> fait en bloc (serveur, puis CLI, puis application Flutter). Les données v1 importables
|
||
> (pseudo, serveurs, historique) passent par un outil d'import (phase 10). Les contacts, eux,
|
||
> doivent refaire une invitation, car leurs clés ne sont pas transposables.
|
||
|
||
---
|
||
|
||
## 1. Constat sur la v1 (Go)
|
||
|
||
| Problème v1 | Conséquence | Réponse v2 |
|
||
|---|---|---|
|
||
| OpenPGP (gopenpgp) pour tout : clés base64 de ~600 octets, paquets PGP, S2K pour le stockage | Lent, volumineux (QR codes énormes), surface d'attaque large | Primitives brutes : X25519, Ed25519, XChaCha20-Poly1305, HKDF-SHA256, Argon2id. Clés de 32 octets. |
|
||
| `PackedUserMessage.signature` = signature **détachée, en clair, sur le texte en clair** | Un serveur qui connaît la clé publique d'un contact peut confirmer l'auteur ou deviner le contenu. Pas de déniabilité. | Pas de signature sur les messages : l'authentification passe par la session Double Ratchet (AEAD avec les identités en données associées). Déniabilité au sens Signal. |
|
||
| Trois couches empilées (asym + sym + DR) avec un état DR sérialisé en JSON | Coûteux, état fragile | Une seule couche pair-à-pair : Double Ratchet. L'état est sérialisé en protobuf et chiffré au repos. |
|
||
| `ConversationRequest.lookup_signature` jamais vérifiée (`// todo sign it`) | N'importe qui connaissant une clé de lookup peut **vider la boîte** d'un autre | Le pull est authentifié : signature Ed25519 de la clé de mailbox, liée au serveur, à un horodatage et à l'id de requête (anti-rejeu). |
|
||
| Singleton global `GetConfig().GetIdentity()` partout | Code non testable, non ré-entrant, une seule identité par processus | Pas d'état global. `MeowClient` est un objet possédé, injectable et clonable (`Arc`). |
|
||
| API FFI : 63 fonctions C, paramètres JSON, framing binaire maison, chemins de fichiers en paramètre | Fragile, lent (double sérialisation), erreurs en JSON | `flutter_rust_bridge` v2 : types Dart générés, `Future`/`Stream` natifs, erreurs typées. |
|
||
| Inbox/outbox sous forme de fichiers protobuf + une base SQLite par file d'envoi + Badger + SQLite par pair | 4 mécanismes de persistance, incohérences possibles | Une seule base SQLite par identité (WAL), transactions. Les blobs sensibles sont chiffrés au niveau applicatif. |
|
||
| Redis obligatoire, logs envoyés en dur vers Loki | Difficile à tester, fuite de métadonnées | Trait `ServerStore` avec un backend mémoire (dev/tests) et un backend Redis (prod). Logs locaux uniquement, sans clés ni mailbox en clair. |
|
||
| `meowsrv/config/*.json` contient clé privée serveur et secret LiveKit | Secrets versionnés | Clé serveur dans un fichier `0600` séparé (`server.key`), secrets passés par variables d'environnement. |
|
||
| TTL des invitations : `time.Duration(timeout*1000000)` interprète des secondes comme des millisecondes, et `mwiv:` est stockée sans expiration | Les invitations ne meurent jamais, et la réponse expire après 86 s au lieu de 24 h | TTL Redis réels (`SET EX`). Purge des mailbox via TTL configurable. |
|
||
| Accusés de livraison serveur : écriture dans `dvyrq:{uuid}` mais lecture dans `msg:{uuid}` | Le suivi de livraison ne fonctionne pas | Phase 5 : accusés de bout en bout, chiffrés dans le ratchet (pas de suivi côté serveur). |
|
||
|
||
---
|
||
|
||
## 2. Vue d'ensemble des crates
|
||
|
||
```
|
||
rust/
|
||
├── Cargo.toml workspace
|
||
├── proto/meow.proto schéma unique du protocole v2 (source de vérité, aussi pour Dart)
|
||
├── crates/
|
||
│ ├── meow-proto (lib) types prost générés + helpers d'encodage. Aucune logique.
|
||
│ ├── meow-crypto (lib) primitives : clés, sealed box, KDF, AEAD, Double Ratchet, chiffrement au repos
|
||
│ ├── meow-core (lib) protocole pur, sans E/S : cartes, invitation 4 étapes, codec de messages,
|
||
│ │ requêtes serveur scellées, authentification des pulls
|
||
│ ├── meow-store (lib) [à créer] persistance client : SQLite chiffrée (identité, contacts, serveurs,
|
||
│ │ sessions, messages, file d'envoi) [phase 4]
|
||
│ ├── meow-client (lib) façade asynchrone haut niveau : transport HTTP, envoi/réception,
|
||
│ │ files d'envoi, long-poll, événements
|
||
│ ├── meow-server (lib+bin `meowsrv`) serveur axum, stores mémoire/Redis
|
||
│ ├── meow-cli (bin `meow`) CLI clap, parité avec meowcli
|
||
│ └── meow-ffi (lib cdylib) [à créer] pont flutter_rust_bridge → bastet [phase 7]
|
||
└── tests/e2e.sh test bout-en-bout (équivalent de meowcli/test.sh)
|
||
```
|
||
|
||
Les dépendances vont uniquement vers le bas :
|
||
|
||
```
|
||
meow-cli ─┐ meow-ffi ─┐
|
||
▼ ▼
|
||
meow-client ──► meow-store
|
||
│
|
||
▼
|
||
meow-server ──► meow-core ──► meow-crypto
|
||
│
|
||
▼
|
||
meow-proto
|
||
```
|
||
|
||
* `meow-core` ne fait **aucune E/S** (ni réseau, ni disque, ni horloge implicite : le temps est
|
||
passé en paramètre). Il est donc entièrement testable de façon déterministe et réutilisable
|
||
côté serveur, CLI et mobile.
|
||
* `meow-crypto` n'expose que des types forts (`SigningKey`, `DhSecret`, `MailboxId`…) et met à
|
||
zéro les secrets avec `zeroize`. Il n'expose jamais d'octets bruts de clé privée hors de la
|
||
sérialisation explicite.
|
||
|
||
---
|
||
|
||
## 3. Cryptographie v2
|
||
|
||
| Usage | Primitive | Crate |
|
||
|---|---|---|
|
||
| Signature (identité par contact, mailbox, carte serveur) | Ed25519 | `ed25519-dalek` |
|
||
| Accord de clé | X25519 | `x25519-dalek` |
|
||
| AEAD | XChaCha20-Poly1305 (nonce aléatoire de 24 octets) | `chacha20poly1305` |
|
||
| KDF | HKDF-SHA256, avec des labels de domaine `meow/v2/...` | `hkdf`, `sha2` |
|
||
| Dérivation de mot de passe | Argon2id (m=64 MiB, t=3, p=1 ; réglable) | `argon2` |
|
||
| Aléa | `OsRng` | `rand_core` |
|
||
|
||
### 3.1 Sealed box (requêtes serveur, invitations)
|
||
|
||
Construction ECIES équivalente à HPKE en mode base (RFC 9180) :
|
||
|
||
```
|
||
eph ← X25519 éphémère
|
||
shared = DH(eph, recipient_pk)
|
||
okm(64) = HKDF(ikm=shared, salt=eph_pk‖recipient_pk, info="meow/v2/seal/"‖context)
|
||
k_req, k_resp = okm[0..32], okm[32..64]
|
||
ciphertext = XChaCha20-Poly1305(k_req, nonce, plaintext, aad=context)
|
||
```
|
||
|
||
`k_resp` sert à chiffrer la **réponse** du serveur. Le serveur reste sans état, et le client n'a
|
||
pas besoin de s'identifier auprès de lui : les requêtes sont **anonymes** par construction.
|
||
|
||
### 3.2 Clés par contact
|
||
|
||
Comme en v1, chaque contact a ses propres clés, ce qui empêche de corréler les contacts entre eux :
|
||
|
||
| Clé | Type | Rôle |
|
||
|---|---|---|
|
||
| `identity` | Ed25519 | Signe le transcript de l'invitation (preuve de possession) |
|
||
| `dh` | X25519 | Clé statique utilisée pour l'accord initial (X3DH simplifié) |
|
||
| `mailbox` | Ed25519 | La clé publique **est** l'adresse de la boîte aux lettres (`MailboxId`). La clé privée signe les pulls. |
|
||
| `ratchet` | X25519 | Clé initiale du Double Ratchet (rôle de « signed prekey » côté invité) |
|
||
|
||
### 3.3 Invitation en 4 étapes (le transport est indépendant : fichier, QR, serveur, BLE)
|
||
|
||
```
|
||
Initiateur (I) Invité (V)
|
||
1. Offer { inv_id, nom, offer_dh (X25519 temp),
|
||
answer_mailbox (Ed25519 temp), msg,
|
||
answer_servers, expires_at } ───────►
|
||
2. Crée ses clés + Card_V
|
||
Answer = seal(offer_dh, {Card_V,
|
||
sig_V(H(offer) ‖ Card_V)})
|
||
◄─────── (fichier, ou dépôt dans answer_mailbox)
|
||
3. Ouvre Answer, vérifie sig_V, crée ses clés + Card_I
|
||
eph_I ← X25519 ; th = H(offer ‖ Card_V ‖ Card_I ‖ eph_I)
|
||
SK = HKDF( DH(I.dh, V.dh) ‖ DH(eph_I, V.dh) ‖ DH(eph_I, V.ratchet) ; salt = th )
|
||
DR.init_sender(SK, V.ratchet) → I peut envoyer immédiatement
|
||
Confirm = seal(V.dh, {Card_I, eph_I, sig_I(th),
|
||
first_message = DR(HandshakeAck)}) ───►
|
||
4. Ouvre Confirm, vérifie sig_I, recalcule SK
|
||
DR.init_receiver(SK, V.ratchet_kp)
|
||
déchiffre first_message → chaîne d'envoi prête
|
||
◄─────── envoie DR(HandshakeAck) dans I.mailbox
|
||
5. Réception de l'ack → contact « Active » des deux côtés
|
||
```
|
||
|
||
Pourquoi `first_message` : dans un Double Ratchet, le receveur ne peut pas émettre avant d'avoir reçu un
|
||
message. Embarquer le premier message de l'initiateur dans le Confirm permet à l'invité d'émettre
|
||
l'ack dès l'étape 4. L'initiateur, lui, peut envoyer dès l'étape 3 (les messages attendent dans la
|
||
mailbox de l'invité et sont lisibles après l'étape 4).
|
||
|
||
Chaque étape est liée aux précédentes par le transcript `th` : un Answer ou un Confirm rejoué,
|
||
falsifié ou destiné à un autre invité est rejeté. Les 10 premiers octets de `th` donnent un
|
||
« numéro de sécurité » identique des deux côtés (`meow contact show`). La vérification visuelle (SAS)
|
||
de `peer_secure` reste disponible au-dessus (phase 8).
|
||
|
||
### 3.4 Messages entre pairs
|
||
|
||
```
|
||
UserMessage (protobuf) → padding par paliers (256 o, 1 Kio, 4 Kio, 16 Kio, 64 Kio…)
|
||
→ DoubleRatchet.encrypt(ad = "meow/v2/msg" ‖ id_émetteur ‖ id_destinataire)
|
||
→ PeerEnvelope { header, ciphertext }
|
||
→ Deposit { mailbox = contact.mailbox, payload = PeerEnvelope }
|
||
→ Request scellée vers chaque serveur de pull du contact
|
||
```
|
||
|
||
Le Double Ratchet suit la spécification Signal (KDF_RK = HKDF, KDF_CK = HMAC-SHA256). Les clés
|
||
sautées sont bornées (`MAX_SKIP = 1000`). Le chiffrement des en-têtes est prévu en phase 8.
|
||
|
||
### 3.5 Authentification des pulls
|
||
|
||
```
|
||
MailboxAuth { mailbox, timestamp, signature, acks[] }
|
||
signature = Ed25519_sign(mailbox_sk,
|
||
"meow/v2/pull" ‖ server_sign_pk ‖ mailbox ‖ timestamp
|
||
‖ SHA-256(acks, préfixés par leur longueur) ‖ request_id)
|
||
```
|
||
|
||
Le serveur rejette si `|now - timestamp| > 300 s`, si la signature est invalide ou si
|
||
`request_id` a déjà été vu (cache anti-rejeu avec TTL de 600 s). Les `acks` étant signés, seul
|
||
le propriétaire d'une mailbox peut en supprimer les messages.
|
||
|
||
### 3.6 Livraison au moins une fois
|
||
|
||
Un pull **ne supprime rien**. Chaque `StoredMessage` porte un `id` attribué par le serveur, et
|
||
reste stocké jusqu'à ce qu'un pull ultérieur l'acquitte dans `MailboxAuth.acks`.
|
||
|
||
```
|
||
client serveur
|
||
Pull{auths(acks=[])} ─────▶ fetch (sans supprimer)
|
||
◀───── PullResult{messages[id], more}
|
||
traitement, puis enregistrement de
|
||
l'état ET des acks en attente
|
||
Pull{auths(acks=[ids]), wait=0} ─────▶ ack(ids), puis fetch
|
||
◀───── PullResult{…}
|
||
```
|
||
|
||
* Côté client, les acks en attente (`PendingAck {server, mailbox, id}`) sont enregistrés
|
||
**dans la même sauvegarde** que l'état du ratchet. Un message redélivré dont l'id est encore
|
||
en attente n'est donc pas retraité : il est simplement acquitté de nouveau.
|
||
* `sync(wait)` relance un tour sans attente tant qu'il reçoit du nouveau ou que le serveur
|
||
signale `more` (limites de 256 messages et 16 Mio par pull). Un `sync` se termine donc avec
|
||
ses acks envoyés.
|
||
* Une mailbox qui disparaît alors qu'elle a encore des acks en attente (boîte de réponse
|
||
temporaire d'une invitation, contact supprimé) est « mise en retraite » : sa clé est conservée
|
||
le temps d'envoyer ces acks.
|
||
* Effacer les acks envoyés ne demande pas de sauvegarde, car un ack est idempotent : au pire,
|
||
il est renvoyé.
|
||
|
||
---
|
||
|
||
## 4. Protocole serveur
|
||
|
||
* `GET /v2/card` → `ServerCard` (protobuf) autosignée. Le client l'épingle à l'ajout (TOFU),
|
||
et un changement de clé est signalé explicitement.
|
||
* `POST /v2/rpc` → corps `SealedRequest`, réponse `SealedResponse` (protobuf binaire).
|
||
* `GET /healthz`, `GET /v2/stats` (compteurs agrégés, optionnel).
|
||
* Phase 8 : `GET /v2/ws` (WebSocket) pour le push.
|
||
|
||
Les opérations (`oneof` de `Request`) :
|
||
|
||
| Requête | Effet |
|
||
|---|---|
|
||
| `Post { deposits[] }` | Stocke chaque payload dans `mailbox`, avec un TTL. Retourne les ids serveur. |
|
||
| `Pull { auths[], wait_seconds }` | Supprime d'abord les messages acquittés (`auths[].acks`), puis renvoie sans les supprimer les messages restants des mailbox authentifiées (`more` si limité). Long-poll si elles sont vides (≤ 120 s). Voir §3.6. |
|
||
| `InvitationPublish { payload, ttl, shortcode_len, password }` | Retourne `shortcode` et `expiry`. |
|
||
| `InvitationFetch { shortcode, password }` | 3 échecs → invitation détruite. Comparaison en temps constant. |
|
||
| `Ping` | Retourne l'heure du serveur (synchronisation des horodatages). |
|
||
|
||
Stockage (`ServerStore`, trait asynchrone) :
|
||
|
||
* `MemoryStore` : `HashMap` + canal `broadcast`, pour le dev et les tests.
|
||
* `RedisStore` (Redis ≥ 5) : `meow:v2:mb:{hex}` est un **stream** (`XADD MAXLEN`, `XRANGE` pour
|
||
lire, `XDEL` pour acquitter ; l'id du stream sert d'id de message) avec `EXPIRE`,
|
||
`PUBLISH meow:v2:new`, `SET inv:{code} EX`, `SET invpw:{code}`, `INCR invfa:{code}`,
|
||
`SET rq:{id} NX EX`.
|
||
|
||
---
|
||
|
||
## 5. API publique de la bibliothèque client (`meow-client`)
|
||
|
||
```rust
|
||
let client = MeowClient::open(path, Password::from(...)).await?; // ou ::create(path, nickname, pw)
|
||
client.servers().add("http://localhost:8080").await?; // récupère et épingle la ServerCard
|
||
let offer = client.invitations().create("alice", &servers, msg).await?; // étape 1 → InvitationOffer
|
||
let answer = client.invitations().answer(&offer, "bob", &servers).await?; // étape 2
|
||
let confirm= client.invitations().accept(&answer).await?; // étape 3
|
||
client.invitations().finalize(&confirm).await?; // étape 4
|
||
client.messages().send_text(contact_id, "hello").await?;
|
||
let report = client.sync(Duration::from_secs(30)).await?; // pull/long-poll + traitement
|
||
let mut events = client.subscribe(); // Stream<Event>
|
||
```
|
||
|
||
* Tous les types publics sont des structs Rust idiomatiques (`ContactId`, `Contact`,
|
||
`Message`, `Event::{MessageReceived, ContactActivated, DeliveryAck, …}`). Le protobuf
|
||
reste interne.
|
||
* Erreurs : `thiserror`, un `enum Error` par crate, sans `unwrap` dans les bibliothèques.
|
||
* Le cœur est asynchrone (`tokio`). La FFI expose les mêmes méthodes via `flutter_rust_bridge`
|
||
(`Future` ↔ `Future`, `Stream` ↔ `Stream`).
|
||
|
||
---
|
||
|
||
## 6. Stockage client
|
||
|
||
* Une base SQLite par identité (`rusqlite`, `bundled`), en mode WAL.
|
||
* Clé maîtresse = Argon2id(mot de passe, sel). Toutes les colonnes sensibles (clés, état DR,
|
||
contenu des messages) sont chiffrées en XChaCha20-Poly1305 avec la clé maîtresse et une AAD
|
||
`table‖id`. Les index ne contiennent que des identifiants aléatoires.
|
||
* Phase 4 : contacts cachés. Des emplacements de taille fixe sont chiffrés avec des clés dérivées
|
||
de mots de passe secondaires, et les emplacements vides sont remplis d'aléa indiscernable, ce
|
||
qui conserve la déniabilité de la v1.
|
||
* Phase 1–3 (provisoire, pour la CLI) : un fichier d'identité unique `*.mwid2` chiffré
|
||
(Argon2id + XChaCha20-Poly1305), sauvegardé de façon atomique (écriture puis renommage) et
|
||
protégé par un verrou exclusif `*.mwid2.lock` (`File::try_lock`). Deux processus ne peuvent pas
|
||
ouvrir la même identité, car le dernier à écrire ferait reculer l'état du ratchet. Ce fichier est
|
||
remplacé par `meow-store` en phase 4.
|
||
* Invariant : tout changement d'état (ratchet, contact) est **persisté avant** que les octets
|
||
correspondants ne quittent l'appareil.
|
||
|
||
---
|
||
|
||
## 7. Conventions
|
||
|
||
* Edition 2021, MSRV = stable courante. `cargo fmt`, `cargo clippy -D warnings`.
|
||
* `#![forbid(unsafe_code)]` partout, sauf dans `meow-ffi`.
|
||
* Tests : unitaires dans chaque crate, protocole complet dans `meow-core/tests`, serveur via
|
||
`axum` en mémoire, et bout-en-bout avec `tests/e2e.sh`.
|
||
* Logs : `tracing`. Jamais de clé, de mailbox ou de contenu au niveau `info`.
|