247 lines
15 KiB
Markdown
247 lines
15 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 }
|
|||
|
|
signature = Ed25519_sign(mailbox_sk,
|
|||
|
|
"meow/v2/pull" ‖ server_sign_pk ‖ mailbox ‖ timestamp ‖ 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).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 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 }` | Vide les mailbox authentifiées. Long-poll si elles sont vides (≤ 120 s). |
|
|||
|
|
| `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` + `tokio::sync::Notify`, pour le dev et les tests.
|
|||
|
|
* `RedisStore` : `LIST mb:{hex}` (avec `EXPIRE`), `PUBLISH mbch:{hex}`, `SET inv:{code} EX`,
|
|||
|
|
`SET invpw:{code}`, `INCR invfa:{code}`, `SET replay:{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`.
|