v0.1.0-pre.071

kb-wallet/CHANGELOG.md

@@ -0,0 +1,18 @@
+<!-- file: kb-wallet/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-wallet
+
+## 0.1.0-pre.071
+
+- réécriture du README avec indication explicite du statut d’ébauche ;
+- ajout du TODO détaillant les fonctionnalités prévues pour `0.5.x` ;
+- ajout du guide d’utilisation et de plusieurs exemples publics ;
+- clarification de la frontière entre signer, politique et exécution.
+
+## 0.1.0-pre.062
+
+- migration et renommage du wallet temporaire vers `kb-wallet` ;
+- conservation des alias validés, keypairs temporaires et stockage local ;
+- ajout des contrôles de permissions, type de fichier et effacement des buffers secrets ;
+- adaptation aux normes Rust 2024 et Khadhroony bot3.

kb-wallet/README.md

@@ -1,18 +1,46 @@
 <!-- file: kb-wallet/README.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # kb-wallet
 
-Frontière locale de portefeuille et de signature pour Khadhroony Bot3.
+`kb-wallet` fournit actuellement une frontière locale minimale de portefeuille pour les démonstrations et tests d’intégration.
 
-La crate fournit :
+## État actuel
 
-- des alias de portefeuille validés et non secrets ;
-- des portefeuilles temporaires en mémoire ;
-- un stockage JSON Solana persistant pour le développement et les tests d’intégration ;
-- la signature de messages sans exposition des octets secrets ;
-- des permissions Unix privées (`0700` pour le répertoire, `0600` pour les fichiers) ;
-- le rejet des liens symboliques, fichiers non réguliers, permissions trop ouvertes et keypairs invalides ;
-- l’effacement explicite des buffers contenant des octets secrets via `zeroize`.
+La crate est une ébauche fonctionnelle, pas un gestionnaire de wallets complet.
 
-Cette crate ne décide pas si une transaction peut être envoyée. Les limites de dépense, la simulation et les politiques d’exécution restent dans `kb-lib` et les couches d’orchestration.
+Elle fournit :
+
+- alias validés ;
+- wallet temporaire en mémoire ;
+- stockage local JSON d’un keypair Solana ;
+- chargement ou création atomique ;
+- résumé non secret ;
+- accès au trait `Signer` sans exposition des octets ;
+- signature de messages ;
+- permissions Unix privées et contrôles de fichiers ;
+- effacement des buffers secrets utilisés lors de la lecture ou écriture.
+
+## Hors capacités actuelles
+
+Les fonctions suivantes ne sont pas encore implémentées :
+
+- chiffrement par mot de passe ;
+- plusieurs wallets gérés comme collection ;
+- sélection persistante du wallet actif ;
+- import/export contrôlé ;
+- changement de mot de passe ;
+- verrouillage et déverrouillage ;
+- sauvegarde et restauration ;
+- politiques de sécurité complètes.
+
+## Relations
+
+`kb-wallet` fournit un signer. Les limites de dépense, la simulation, l’autorisation opérateur et l’envoi sont gérés par `kb-lib`, `kb-pipeline-demo-scenarios` et les applications.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [ROADMAP général](../ROADMAP.md)

kb-wallet/TODO.md

@@ -0,0 +1,16 @@
+<!-- file: kb-wallet/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-wallet
+
+- [ ] Fonctionnalité - gérer plusieurs wallets persistants.
+- [ ] Fonctionnalité - ajouter la sélection et la persistance du wallet actif.
+- [ ] Sécurité - ajouter le chiffrement et le déchiffrement protégés par mot de passe.
+- [ ] Sécurité - ajouter le changement de mot de passe.
+- [ ] Sécurité - ajouter le verrouillage et le déverrouillage explicites.
+- [ ] Fonctionnalité - ajouter l’import et l’export contrôlés de wallets.
+- [ ] Fonctionnalité - ajouter la sauvegarde et la restauration.
+- [ ] Sécurité - définir des politiques de stockage, de session et d’autorisation de signature.
+- [ ] Intégration - relier la sélection du wallet aux profils et signers des scénarios.
+- [ ] Tests - ajouter les tests de corruption, concurrence et récupération pour les nouvelles fonctionnalités.
+- [ ] Documentation - produire un guide de sécurité avant tout usage hors démonstration.

kb-wallet/USAGE.md

@@ -0,0 +1,182 @@
+<!-- file: kb-wallet/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de kb-wallet
+
+## Objectif
+
+La crate fournit des wallets temporaires en mémoire ou persistés localement pour les démonstrations et tests d’intégration.
+
+## Valider un alias
+
+```rust
+let alias = match kb_wallet::WalletAlias::parse(
+    "devnet-operator",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+assert_eq!(alias.as_str(), "devnet-operator");
+```
+
+Un alias doit contenir entre 1 et 64 octets, commencer par un caractère alphanumérique ASCII et ne contenir ensuite que des caractères alphanumériques, `_` ou `-`.
+
+## Générer un wallet en mémoire
+
+```rust
+let alias = match kb_wallet::WalletAlias::parse(
+    "ephemeral",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let wallet =
+    kb_wallet::TemporaryWallet::generate(alias);
+let summary = wallet.summary();
+
+assert!(summary.storage_path.is_none());
+println!("public key={}", summary.public_key);
+```
+
+## Signer un message
+
+```rust
+let signature = match wallet.sign_message(
+    b"khadhroony demo authorization",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+println!("signature={signature}");
+```
+
+`as_signer()` retourne une référence au trait Solana `Signer` sans exposer les octets du keypair.
+
+## Créer un stockage local
+
+```rust
+let store = match kb_wallet::TemporaryWalletStore::new(
+    "./data/wallets",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+println!(
+    "wallet directory={}",
+    store.directory().display()
+);
+```
+
+## Créer un wallet persistant
+
+```rust
+let alias = match kb_wallet::WalletAlias::parse(
+    "devnet-payer",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let wallet = match store.create(alias).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let summary = wallet.summary();
+assert!(summary.storage_path.is_some());
+```
+
+`create` refuse d’écraser un fichier existant.
+
+## Charger ou créer atomiquement
+
+```rust
+let alias = match kb_wallet::WalletAlias::parse(
+    "shared-devnet",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let wallet = match store.load_or_create(alias).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+println!("wallet={}", wallet.public_key());
+```
+
+## Vérifier l’existence et le chemin
+
+```rust
+let path = store.wallet_path(&alias);
+let exists = match store.exists(&alias).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+println!("path={}, exists={exists}", path.display());
+```
+
+## Politique non secrète
+
+```rust
+let policy = kb_wallet::WalletPolicy {
+    signing_enabled: true,
+    lamport_spend_limit: std::option::Option::Some(
+        1_000_000,
+    ),
+};
+
+assert!(policy.signing_enabled);
+```
+
+`WalletPolicy` transporte une intention de politique. Son application effective appartient à la couche d’exécution.
+
+## Erreurs et invariants
+
+- les octets secrets ne sont jamais exposés par l’API publique ;
+- les résumés ne contiennent que l’alias, la clé publique et le chemin ;
+- un fichier existant n’est pas écrasé ;
+- les liens symboliques et fichiers non réguliers sont refusés ;
+- sur Unix, les permissions privées sont vérifiées ;
+- les buffers secrets temporaires sont effacés ;
+- cette crate ne décide pas si une transaction est autorisée.
+
+## Tests de référence
+
+- validation des alias ;
+- génération et signature sans persistance ;
+- création, chargement et `load_or_create` ;
+- refus d’écrasement ;
+- rejet des keypairs corrompus ;
+- vérification des permissions Unix privées ;
+- rejet des liens symboliques et permissions trop ouvertes.
+
+## Limites durables
+
+- le format persistant actuel est le tableau JSON standard du keypair Solana ;
+- la crate ne signe pas automatiquement une transaction ;
+- elle ne transmet aucun secret à une interface frontend.