0.5.1-pre.002

ks-wallet/USAGE.md

@@ -0,0 +1,184 @@
+<!-- file: ks-wallet/USAGE.md -->
+<!-- version: 3 -->
+
+# Utilisation de ks-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 ks_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 ks_wallet::WalletAlias::parse(
+    "ephemeral",
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => {
+        return std::result::Result::Err(error);
+    },
+};
+
+let wallet =
+    ks_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.
+
+Pour une API async qui conserve la référence au travers d’un `await` et impose un futur `Send`, `as_sync_signer()` préserve explicitement le marqueur `Sync` du keypair concret. Cette vue ne change ni la clé utilisée ni les règles d’autorisation de la couche d’exécution.
+
+## Créer un stockage local
+
+```rust
+let store = match ks_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 ks_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 ks_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 = ks_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.