first commit
This commit is contained in:
commit
6d3ea3e2a6
43 files changed
+8204
No files matched your search
+247
@@ -0,0 +1,247 @@
|
||||
# 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`.
|
||||
Reference in new issue
Block a user