From 44b9e74153f5e32b3665f319429b3b08fd3662d5 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Sun, 9 Aug 2026 14:57:01 +0200 Subject: docs: update all pointers after keyderive + QE restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md: add QE/ to structure, key modules table, server state reference, security rule updated (QE/ not keypair files), meshbay.org inventory pointer. devel-phases.md: add milestones 6.6-6.9 (keyderive, bundle, demo scripts, QUICKSTART rewrite). 81/81 tests. docs/meshbay-draft-v3.md §6.1.1: new section documenting 3 key generation strategies (Argon2id CLI, WebCrypto browser+bundle, keystore file) and the algorithm mismatch caveat between CLI and web registration paths. docs/USERGUIDE.md §2 Register+Login: replace "generate and persist before registering" warning with the two clean strategies (derive_keys_from_password for CLI, keyderive.js + keypair_bundle for browser). Login response updated with keypair_bundle field. hub/models.py + users.py + Alembic migration: keypair_bundle column on User, stored at registration, returned at login (web clients only). Co-Authored-By: Claude Sonnet 4.6 (1M context) --- docs/USERGUIDE.md | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) (limited to 'docs/USERGUIDE.md') diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index b49eb73..af03a60 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -62,9 +62,26 @@ MeshBay has three components. Understanding which role each plays avoids a lot o ### Register -Registration requires submitting your Ed25519 (signing) and X25519 (key agreement) public keys at account creation time. These are used by other members' nodes to wrap GEK bundles for you, and by nodes to verify your JWT offline. +Registration submits your Ed25519 (signing) and X25519 (key agreement) public keys. These let other members wrap GEK bundles for you and let nodes verify your JWT offline. -**Critical:** generate and persist your keypairs before registering. If you regenerate them later, all GEK bundles stored for you on the hub become undecryptable. See the Quickstart for the key generation script. +**Deux modes de génération de clés :** + +**Mode CLI / native node** (`setup_demo.py`, `meshbay-node`) : +Les clés sont *dérivées* de votre username + password via Argon2id — pas besoin de +fichier de clés séparé. Même identifiants → mêmes clés sur n'importe quelle machine. +Implémenté dans `meshbay_common.keyderive.derive_keys_from_password()`. + +```python +from meshbay_common.keyderive import derive_keys_from_password +sk_ed, sk_x = derive_keys_from_password("alice", "MonMotDePasse!") +``` + +**Mode navigateur** (interface web) : +Le navigateur génère des clés aléatoires via WebCrypto, les chiffre avec une clé +dérivée du mot de passe (PBKDF2-SHA512), et envoie le bundle chiffré au hub. +À la prochaine connexion, le hub retourne le bundle et le navigateur le déchiffre +localement. Le hub stocke le bundle mais ne peut pas le lire. +Implémenté dans `static/keyderive.js`. ``` POST /v1/users/register @@ -72,13 +89,15 @@ POST /v1/users/register "username": "string", "password": "string (min 8 chars)", "pk_user_ed25519": "base64 raw 32-byte Ed25519 public key", - "pk_user_x25519": "base64 raw 32-byte X25519 public key" + "pk_user_x25519": "base64 raw 32-byte X25519 public key", + "keypair_bundle": "base64 AES-256-GCM encrypted bundle (web clients only, optional)" } → 201 {"user_id": "uuid"} → 409 if username is taken ``` -Passwords are hashed with Argon2id (iterations=4, memory=256 MB, target ~500ms on a home server). This is intentionally slow to limit offline dictionary attacks. +Passwords are hashed with Argon2id (iterations=3, memory=64 MB in dev; +target 256 MB / ~500ms in production). Intentionally slow to resist offline attacks. ### Login @@ -86,13 +105,17 @@ Passwords are hashed with Argon2id (iterations=4, memory=256 MB, target ~500ms o POST /v1/users/login {"username": "yourname", "password": "yourpassword"} → { - "access_token": "JWT (Ed25519, 1 hour validity)", - "refresh_token": "opaque 256-bit token (30 days)", - "token_type": "bearer", - "expires_in": 3600 + "access_token": "JWT (Ed25519, 1 hour validity)", + "refresh_token": "opaque 256-bit token (30 days)", + "token_type": "bearer", + "expires_in": 3600, + "keypair_bundle": "base64 AES-GCM blob (présent uniquement si enregistré via web)" } ``` +Les clients web utilisent `keypair_bundle` pour récupérer leurs clés privées +sur un nouvel appareil : déchiffrement local avec le mot de passe via `keyderive.js`. + ```bash curl -s -X POST https://meshbay.org/v1/users/login \ -H "Content-Type: application/json" \ -- cgit v1.2.3