377 lines
14 KiB
Markdown
377 lines
14 KiB
Markdown
<!-- file: ks-wallet/USAGE.md -->
|
|
<!-- version: 10 -->
|
|
|
|
# Utilisation de ks-wallet
|
|
|
|
## Statut
|
|
|
|
En `0.5.2-pre.004`, le manager gère le premier cycle de vie natif complet : création `.kswallet`, ouverture authentifiée, ouverture d'un fichier explicitement sélectionné et changement de mot de passe. La migration legacy et l'import/export restent pour `pre.005`.
|
|
|
|
## 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 temporaire 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 identity = wallet.identity();
|
|
|
|
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.
|
|
|
|
## 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 frontière de signature doit rester disponible après restructuration : les consommateurs ne doivent pas connaître le format persistant.
|
|
|
|
## Stockage legacy actuel
|
|
|
|
```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);
|
|
},
|
|
};
|
|
```
|
|
|
|
Le store actuel persiste un keypair au format Solana JSON dans :
|
|
|
|
```text
|
|
<alias>.json
|
|
```
|
|
|
|
Ce format est **legacy** pour `0.5.2`.
|
|
|
|
### Créer un wallet legacy 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 identity = wallet.identity();
|
|
assert_eq!(
|
|
identity.persistence,
|
|
ks_wallet::WalletPersistence::Persistent,
|
|
);
|
|
```
|
|
|
|
`create` refuse d'écraser un fichier existant.
|
|
|
|
### Charger ou créer sans écrasement
|
|
|
|
```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());
|
|
```
|
|
|
|
`load_or_create` utilise une création exclusive et reprend la lecture lorsqu'une création concurrente a déjà réservé le même alias.
|
|
|
|
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 et codec v1
|
|
|
|
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`. Chaque candidat doit décoder entièrement selon le format v1 : magic/version, flags, IDs crypto, paramètres KDF, pubkey déclarée, alias, sel, nonce et ciphertext de taille exacte. Le nom du fichier et l'alias encodé doivent correspondre.
|
|
|
|
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());
|
|
println!("pubkey={}", handle.public_key());
|
|
println!("format={}", handle.format_version());
|
|
```
|
|
|
|
`WalletFileHandle` conserve le chemin en interne mais ne fournit aucun getter public vers ce chemin et son `Debug` ne l'affiche pas. Sa pubkey reste une identité **déclarée** tant que le fichier n'a pas été ouvert : `unlock()`/`unlock_file()` authentifient l'AEAD puis vérifient que la pubkey de la keypair déchiffrée correspond exactement au header avant de retourner `UnlockedWallet`. `inspect_file()` ne modifie pas la configuration et n'ajoute pas le fichier sélectionné au résultat de `scan()`.
|
|
|
|
|
|
## Cycle de vie natif protégé par mot de passe
|
|
|
|
`WalletPassword` prend possession du mot de passe pour **une seule opération**. Il n'est ni clonable ni sérialisable et son `Debug` est toujours redacted. L'appelant construit donc une nouvelle valeur pour chaque création, ouverture ou changement de mot de passe.
|
|
|
|
### Créer un wallet persistant natif
|
|
|
|
```rust
|
|
let alias = match ks_wallet::WalletAlias::parse("operator") {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let password = match ks_wallet::WalletPassword::new(password_string) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let wallet = match manager.create(alias.clone(), password).await {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
println!("pubkey={}", wallet.public_key());
|
|
```
|
|
|
|
`create()` génère une keypair Solana, la protège avec Argon2id + XChaCha20-Poly1305, publie `<alias>.kswallet` sans écraser une destination existante et retourne une capacité `UnlockedWallet`. Aucun getter public ne fournit les bytes privés.
|
|
|
|
### Ouvrir par alias
|
|
|
|
```rust
|
|
let password = match ks_wallet::WalletPassword::new(password_string) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let wallet = match manager.unlock(&alias, password).await {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let signature = match wallet.sign_message(b"authenticated operation") {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
println!("signature={signature}");
|
|
wallet.lock();
|
|
```
|
|
|
|
Un mauvais mot de passe ou une altération des données authentifiées échoue avant la création de la capacité de signature. `lock()` consomme explicitement `UnlockedWallet`; laisser la valeur sortir de portée a le même effet de durée de vie.
|
|
|
|
### Ouvrir un fichier choisi hors du 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);
|
|
},
|
|
};
|
|
let password = match ks_wallet::WalletPassword::new(password_string) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let wallet = match manager.unlock_file(&handle, password).await {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
```
|
|
|
|
Le handle est revalidé contre le fichier avant l'ouverture authentifiée. Le fichier externe reste extérieur au scan/configuration du manager.
|
|
|
|
### Changer le mot de passe
|
|
|
|
```rust
|
|
let current_password = match ks_wallet::WalletPassword::new(current_password_string) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let new_password = match ks_wallet::WalletPassword::new(new_password_string) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
let handle = match manager
|
|
.change_password(&alias, current_password, new_password)
|
|
.await
|
|
{
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => {
|
|
return std::result::Result::Err(error);
|
|
},
|
|
};
|
|
println!("pubkey={}", handle.public_key());
|
|
```
|
|
|
|
`change_password()` n'altère pas la keypair : il authentifie l'ancien conteneur, rechiffre exactement le même matériau avec un nouveau sel/nonce et remplace atomiquement le `.kswallet`. La pubkey reste identique. Cette opération ne peut pas révoquer rétroactivement une `UnlockedWallet` déjà remise à un consommateur ; cette capacité doit être `lock()`/dropée par son propriétaire.
|
|
|
|
## Format binaire v1
|
|
|
|
Le layout exact, les bornes et la politique de publication sont documentés dans [`../docs/NATIVE_FORMAT.md`](../docs/NATIVE_FORMAT.md). `pre.004` implémente désormais l'encodage, la lecture, la protection et la publication. Le payload secret v1 est strictement borné à une keypair Solana de 64 octets et produit un ciphertext/tag de 80 octets.
|
|
|
|
Le format exécute Argon2id v19 avec un profil d'écriture par défaut de 64 MiB / 3 passes / 4 lanes et XChaCha20-Poly1305 avec nonce 24 octets. Les paramètres lus depuis un fichier restent bornés avant toute exécution du KDF.
|
|
|
|
## Cible persistante `0.5.2`
|
|
|
|
Le nouveau stockage natif doit utiliser :
|
|
|
|
```text
|
|
<alias>.kswallet
|
|
```
|
|
|
|
Le fichier `.kswallet` est un conteneur binaire versionné protégé par le mot de passe propre au wallet.
|
|
|
|
L'API cible doit permettre conceptuellement :
|
|
|
|
```text
|
|
create persistent(alias, password)
|
|
open/unlock(alias, password)
|
|
change password(alias, old password, new password)
|
|
scan/discover <alias>.kswallet
|
|
list identities
|
|
lookup by alias
|
|
sign without exposing private bytes
|
|
```
|
|
|
|
Le store découvrira les wallets persistants en scannant son répertoire résolu (racine `KS_WALLETS_DIRECTORY`, `wallets` par défaut, puis éventuel sous-répertoire configuré) pour les `<alias>.kswallet` valides. Le scan ne doit pas faire confiance au seul nom du fichier.
|
|
|
|
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.
|
|
|
|
Le modèle runtime ouvert est `UnlockedWallet`, capacité non clonable possédant le signer authentifié. `WalletManager`, `WalletFileHandle`, `WalletIdentity`, `WalletPersistence`, `WalletPassword` et `UnlockedWallet` font désormais partie de l'API de base.
|
|
|
|
## Import/export cible
|
|
|
|
`ks-wallet` doit obligatoirement importer **et exporter** le format keypair JSON standard des binaires Solana, en plus de son import legacy qui correspond actuellement à ce même wire format. Il doit aussi pouvoir convertir vers/depuis les autres formats explicitement supportés.
|
|
|
|
Un export public peut exposer les données autorisées telles que l'alias et la pubkey.
|
|
|
|
**Tout export contenant ou permettant de reconstruire la clé privée doit obligatoirement demander et valider le mot de passe du wallet.**
|
|
|
|
L'export vers Solana CLI utilise son tableau JSON de 64 octets. Pour Phantom, Solflare, Backpack, Trust Wallet, Coinbase/Base et les autres wallets examinés, une matrice de compatibilité doit d'abord confirmer le contrat exact depuis des sources officielles. Un seul adaptateur wallet tiers sera implémenté dans `0.5.2` à titre d'exemple ; les autres formats techniquement faisables seront reportés au TODO. Aucun format universel externe n'est supposé, et une recovery phrase ne doit jamais être synthétisée en prétendant représenter une keypair arbitraire si la seed/mnemonic d'origine n'est pas disponible.
|
|
|
|
## Invariants
|
|
|
|
- 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 ;
|
|
- `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 ;
|
|
- les buffers secrets temporaires sont effacés lorsque possible ;
|
|
- cette crate ne décide pas si une transaction est autorisée.
|
|
|
|
## Tests de référence actuels
|
|
|
|
- validation des alias ;
|
|
- génération et signature sans persistance ;
|
|
- création exclusive, chargement et `load_or_create` ;
|
|
- refus d'écrasement ;
|
|
- rejet des keypairs corrompus ;
|
|
- vérification des permissions Unix privées.
|
|
|
|
`pre.003` ajoute le décodage/validation v1 stricts et les bornes KDF/fichier. `pre.004` ajoute l'encodage, la publication atomique, le password, la dérivation/chiffrement effectifs, l'ouverture authentifiée, le changement de password et les tests de non-divulgation associés. Les tranches suivantes couvrent migration et import/export puis l'intégration des consommateurs.
|