v0.5.2-pre.002

ks-wallet/USAGE.md

@@ -1,11 +1,11 @@
 <!-- file: ks-wallet/USAGE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Utilisation de ks-wallet
 
 ## Statut
 
-En `0.5.2-pre.001`, cette page décrit l'API runtime **actuelle**. La cible multi-wallet/password/`.kswallet` est planifiée mais n'est pas encore implémentée.
+En `0.5.2-pre.002`, l'API multi-wallet de découverte est introduite, tandis que le password, le codec complet et la création persistante `.kswallet` restent planifiés pour les prereleases suivantes.
 
 ## Valider un alias
 
@@ -37,10 +37,13 @@ let alias = match ks_wallet::WalletAlias::parse(
 };
 
 let wallet = ks_wallet::TemporaryWallet::generate(alias);
-let summary = wallet.summary();
+let identity = wallet.identity();
 
-assert!(summary.storage_path.is_none());
-println!("public key={}", summary.public_key);
+assert_eq!(
+    identity.persistence,
+    ks_wallet::WalletPersistence::Temporary,
+);
+println!("public key={}", identity.public_key);
 ```
 
 Cette capacité est durable : `0.5.2` doit continuer à permettre des wallets temporaires/jetables pour tests, démonstrations et scénarios sans imposer une persistance ou un mot de passe.
@@ -106,8 +109,11 @@ let wallet = match store.create(alias).await {
     },
 };
 
-let summary = wallet.summary();
-assert!(summary.storage_path.is_some());
+let identity = wallet.identity();
+assert_eq!(
+    identity.persistence,
+    ks_wallet::WalletPersistence::Persistent,
+);
 ```
 
 `create` refuse d'écraser un fichier existant.
@@ -138,6 +144,56 @@ println!("wallet={}", wallet.public_key());
 
 Le contenu legacy est toutefois écrit directement dans le chemin final. La publication n'est pas encore crash-safe/atomique par fichier temporaire + renommage.
 
+## Manager multi-wallet introduit en `pre.002`
+
+Le manager reçoit le répertoire déjà résolu par le consommateur/configuration. Son scan automatique ne sort jamais de cette racine :
+
+```rust
+let manager = match ks_wallet::WalletManager::new(
+    configured_wallet_directory,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let wallets = match manager.scan().await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+```
+
+`scan()` est non récursif et ne traite que les `<alias>.kswallet`. En `pre.002`, l'identification vérifie le suffixe, l'alias, le type de fichier, les permissions Unix, le magic ASCII `KSWALLET` et la version `1` encodée en `u16` little-endian. La validation complète du payload arrivera avec le codec `pre.003`.
+
+Le lookup par alias reste limité à la racine configurée :
+
+```rust
+let wallet = match manager.lookup(&alias).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+```
+
+Pour un fichier choisi explicitement par l'utilisateur, par exemple via un file browser Tauri, le chemin peut être extérieur au store :
+
+```rust
+let handle = match manager.inspect_file(selected_path).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+println!("alias={}", handle.alias().as_str());
+```
+
+`WalletFileHandle` conserve le chemin en interne mais ne fournit aucun getter public vers ce chemin et son `Debug` ne l'affiche pas. `inspect_file()` ne modifie pas la configuration et n'ajoute pas le fichier sélectionné au résultat de `scan()`. Le handle servira à l'ouverture par mot de passe dans la tranche correspondante.
+
 ## Cible persistante `0.5.2`
 
 Le nouveau stockage natif doit utiliser :
@@ -164,7 +220,7 @@ Le store découvrira les wallets persistants en scannant son répertoire résolu
 
 Le changement de mot de passe rechiffre la même keypair. Il n'existe pas de rotation normale du secret Ed25519 conservant la même pubkey : une nouvelle clé secrète signifie une nouvelle identité Solana.
 
-Les noms Rust définitifs et le modèle runtime exact seront décidés dans les prereleases d'implémentation.
+Le modèle runtime exact du wallet ouvert sera décidé dans les prereleases d'implémentation. Les noms `WalletManager`, `WalletFileHandle`, `WalletIdentity` et `WalletPersistence` font désormais partie de l'API de base.
 
 ## Import/export cible
 
@@ -181,7 +237,7 @@ L'export vers Solana CLI utilise son tableau JSON de 64 octets. Pour Phantom, So
 - les octets secrets ne sont pas exposés par l'API publique par commodité ;
 - aucun mot de passe ni secret n'est projeté vers Tauri ;
 - `ks-config` ne stocke pas les mots de passe ;
-- les résumés publics ne doivent pas exposer inutilement les chemins locaux ;
+- `WalletIdentity`, `WalletSummary`, `WalletFileHandle::Debug` et les erreurs natives normales n'exposent pas le chemin local ;
 - un fichier existant n'est pas écrasé silencieusement ;
 - les liens symboliques et fichiers non réguliers sont refusés ;
 - sur Unix, les permissions privées sont vérifiées ;
@@ -197,4 +253,4 @@ L'export vers Solana CLI utilise son tableau JSON de 64 octets. Pour Phantom, So
 - rejet des keypairs corrompus ;
 - vérification des permissions Unix privées.
 
-La matrice `0.5.2` ajoutera notamment : legacy externalisé, `.kswallet`, password/changement de password, multi-wallet, migration, import/export, atomicité et canaris de non-divulgation.
+`pre.002` ajoute la caractérisation legacy externalisée ainsi que les tests du manager, du scan, du lookup, de l'inspection hors store, du magic/version et de la non-divulgation du chemin par le handle. La suite de la matrice ajoutera le codec `.kswallet`, le password/changement de password, la migration, l'import/export, l'atomicité complète et les canaris de non-divulgation.