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
2026-11-20 22:45:37 +01:00
│ ├── meow-store (lib) persistance client : sac de blocs chiffrés, espaces cachés (identité, contacts, serveurs,
2026-11-20 21:47:33 +01:00
│ │ 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
```
2026-11-20 22:00:54 +01:00
MailboxAuth { mailbox, timestamp, signature, acks[] }
2026-11-20 21:47:33 +01:00
signature = Ed25519_sign(mailbox_sk,
2026-11-20 22:00:54 +01:00
"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
2026-11-20 22:00:54 +01:00
`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. |
2026-11-20 22:00:54 +01:00
| `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) :
2026-11-20 22:00:54 +01:00
* `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` ).
---
2026-11-20 22:45:37 +01:00
## 6. Stockage client (`meow-store`)
2026-11-20 21:47:33 +01:00
2026-11-20 22:45:37 +01:00
### 6.1 Modèle de menace
L'appareil peut être saisi, une fois ou plusieurs fois, et l'utilisateur peut être contraint de
donner son mot de passe principal.
1. **Sans mot de passe** , l'attaquant ne doit apprendre ni le nombre de contacts, ni quelles
conversations sont actives (« qui sont ses proches »), ni leur taille ou leur date.
2. **Avec le mot de passe principal** , les *espaces cachés* restent invisibles : rien ne permet
de prouver qu'il en existe.
Hors périmètre : la mémoire vive d'un appareil allumé et déverrouillé, et les fuites du système
(notifications, caches d'images, clavier). Pour un utilisateur exposé, la cible est un Linux maîtrisé.
L'application limitera ces fuites, par exemple sans texte de message dans les notifications.
### 6.2 Un sac de blocs uniformes
Un fichier SQLite par identité, qui ne contient que deux tables :
* `meta` : le sel (16 octets, commun à tous les mots de passe) et les paramètres Argon2id.
Ces données sont publiques et non sensibles.
* `blocks(id, data)` : des lignes de * *4096 octets** sous des identifiants **aléatoires de
32 octets**. Un bloc utilisé vaut `XChaCha20-Poly1305(clé de l'espace, morceau complété par du
bourrage, aad = id)` . Un bloc de remplissage est de l'aléa. Sans clé, on ne peut pas les distinguer.
Aucune colonne en clair ne relie deux lignes. Un *objet* (profil, contact, segment de
conversation, fichier) est découpé en blocs, et son `ObjectRef { blocks[], len }` est rangé dans
l'objet parent.
```
mot de passe ─Argon2id(sel)─► k ─HMAC─► id de la racine (1 bloc, chiffré par HKDF(k))
└─ Root { type, clé d'espace, ObjectRef de l'index }
Index { meta, contacts[{ id, état, dir }], blocs libres[] }
Dir { segments[] (du plus ancien au plus récent), fichiers[(id de message, ObjectRef)] }
```
### 6.3 Espaces
* Le mot de passe principal ouvre l'espace principal : pseudo, serveurs, contacts visibles, acks
en attente.
* Chaque autre mot de passe ouvre un * *espace caché**, qui contient un ou plusieurs contacts avec
leurs conversations et leurs propres acks en attente. Les données d'un espace caché ne sont
jamais rangées dans l'espace principal.
* `unlock(mot de passe)` coûte une dérivation Argon2id et une lecture de la racine, qu'un espace
existe ou non. Le coût est dominé par Argon2id, et il n'y a pas de boucle d'essai sur des
emplacements. Un même champ de saisie sert au mot de passe principal comme aux mots de passe cachés.
* Changer un mot de passe ne fait que déplacer la racine. L'ancienne racine est écrasée par de
l'aléa.
### 6.4 Déni plausible et non-corrélation
* À la création, entre 128 et 1024 blocs d'aléa sont ajoutés **sans être enregistrés nulle
part**, et chaque sauvegarde en ajoute parfois quelques-uns. Tout magasin contient donc des
blocs que le mot de passe principal n'ouvre pas, et les blocs d'un espace caché se fondent parmi eux.
* Un objet réécrit change de blocs : ils sont pris au hasard parmi les blocs libres de l'espace.
Les anciens blocs sont écrasés par de l'aléa (ce qui efface aussi les anciens états de ratchet),
puis libérés. Chaque sauvegarde réécrit aussi quelques blocs libres au hasard. Seules les
racines gardent un identifiant fixe.
* On ne supprime jamais de bloc : les blocs libérés sont recyclés.
* Le WAL est vidé (`wal_checkpoint(TRUNCATE)` ) après chaque sauvegarde, et `secure_delete` est
actif.
### 6.5 Segments
Une conversation est une suite de segments d'environ 16 Kio. Ajouter un message ne réécrit que
le dernier segment, et l'historique se lit segment par segment, du plus récent au plus ancien.
C'est l'équivalent des bases de messages de taille fixe de la v1, sans qu'aucun fichier ne
révèle la longueur des conversations.
### 6.6 Limites connues
* **Plusieurs saisies de l'appareil.** Avec deux copies du fichier, l'attaquant voit quels blocs
ont changé entre elles, sans savoir à quel objet ils appartiennent. Il voit aussi que la racine
principale change à chaque sauvegarde. Si un espace caché a été utilisé entre les deux copies,
ses blocs ont changé alors que le mot de passe principal ne les explique pas. C'est la limite
connue des volumes cachés de VeraCrypt : l'éviter demanderait une ORAM, trop coûteuse ici.
Il vaut donc mieux ouvrir les espaces cachés rarement.
* * *Le volume total** stocké reste visible, à l'aléa de remplissage près. La date de dernière
modification du fichier aussi.
* * *Le temps d'ouverture** : lire l'index d'un espace qui existe prend environ une milliseconde
de plus, ce qui est négligeable devant Argon2id.
### 6.7 Durabilité et exclusivité
* WAL avec `synchronous=FULL` et une transaction par sauvegarde. Quand `save` revient, l'état
est durable : l'invariant **persister avant d'envoyer ou d'acquitter** repose sur cette garantie.
* Un verrou exclusif `<fichier>.lock` (`File::try_lock` ) empêche qu'un deuxième processus fasse
reculer l'état d'un ratchet.
* En attendant le lot 4.5, la CLI utilise encore le fichier provisoire `* .mwid2` de
` meow-client` (un profil postcard chiffré d'un seul bloc).
2026-11-20 21:47:33 +01:00
---
## 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`.