Files
meow/ARCHITECTURE.md
T

278 lines
17 KiB
Markdown
Raw Normal View History

2026-11-20 21:47:33 +01:00
# 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[] }
2026-11-20 21:47:33 +01:00
signature = Ed25519_sign(mailbox_sk,
"meow/v2/pull" ‖ server_sign_pk ‖ mailbox ‖ timestamp
‖ SHA-256(acks, préfixés par leur longueur) ‖ request_id)
2026-11-20 21:47:33 +01:00
```
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é.
2026-11-20 21:47:33 +01:00
---
## 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. |
2026-11-20 21:47:33 +01:00
| `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`.
2026-11-20 21:47:33 +01:00
---
## 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`.