v0.5.2-pre.005
This commit is contained in:
@@ -1,11 +1,11 @@
|
||||
<!-- file: ks-wallet/USAGE.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# 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`.
|
||||
En `0.5.2-pre.005`, le manager couvre aussi la migration non destructive du legacy, l'import/export du keypair JSON Solana CLI et le transfert Base58 d'une keypair Solana complète. Tout export secret repart d'un `.kswallet` authentifié avec son mot de passe.
|
||||
|
||||
## Valider un alias
|
||||
|
||||
@@ -308,6 +308,107 @@ 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.
|
||||
|
||||
## Migration et import/export secrets
|
||||
|
||||
`0.5.2-pre.005` expose deux formats de transfert explicites :
|
||||
|
||||
- `WalletTransferFormat::SolanaCliJson` : tableau JSON standard des 64 octets du keypair Solana ;
|
||||
- `WalletTransferFormat::SolanaPrivateKeyBase58` : Base58 du keypair Solana complet de 64 octets, utilisé comme adaptateur tiers de référence pour Phantom et compatible avec le flux Phantom -> Solflare documenté.
|
||||
|
||||
La matrice des formats vérifiés et reportés est maintenue dans [`../docs/WALLET_FORMAT_COMPATIBILITY.md`](../docs/WALLET_FORMAT_COMPATIBILITY.md).
|
||||
|
||||
### Migrer un legacy `<alias>.json`
|
||||
|
||||
```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.migrate_legacy(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());
|
||||
```
|
||||
|
||||
`migrate_legacy()` lit `<store>/<alias>.json`, crée `<store>/<alias>.kswallet`, vérifie la pubkey et **ne modifie ni ne supprime le legacy**. Une destination native déjà existante est refusée. Le `.json` reste donc disponible pour rollback jusqu'à suppression explicite par l'opérateur.
|
||||
|
||||
### Importer un fichier Solana CLI JSON
|
||||
|
||||
```rust
|
||||
let alias = match ks_wallet::WalletAlias::parse("imported-cli") {
|
||||
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
|
||||
.import_file(
|
||||
alias,
|
||||
password,
|
||||
source_path,
|
||||
ks_wallet::WalletTransferFormat::SolanaCliJson,
|
||||
)
|
||||
.await
|
||||
{
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => {
|
||||
return std::result::Result::Err(error);
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Une source d'import secret doit être un fichier régulier non symlink et privé sous Unix. L'import refuse les collisions de destination et les pubkeys déjà présentes sous un autre alias natif.
|
||||
|
||||
### Importer une private key Base58
|
||||
|
||||
Le même appel utilise :
|
||||
|
||||
```rust
|
||||
ks_wallet::WalletTransferFormat::SolanaPrivateKeyBase58
|
||||
```
|
||||
|
||||
La forme acceptée est strictement le Base58 du **keypair Solana complet de 64 octets**. Une seed de 32 octets ou une recovery phrase n'est pas interprétée implicitement.
|
||||
|
||||
### Exporter un secret
|
||||
|
||||
```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);
|
||||
},
|
||||
};
|
||||
match manager
|
||||
.export_file(
|
||||
&alias,
|
||||
password,
|
||||
destination_path,
|
||||
ks_wallet::WalletTransferFormat::SolanaCliJson,
|
||||
)
|
||||
.await
|
||||
{
|
||||
std::result::Result::Ok(()) => {},
|
||||
std::result::Result::Err(error) => {
|
||||
return std::result::Result::Err(error);
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
L'export secret **exige toujours le mot de passe valide du `.kswallet`**. La destination n'est créée qu'après authentification, n'est jamais écrasée silencieusement et est publiée en fichier privé (`0600` sous Unix). Le répertoire parent peut être un répertoire explicitement choisi par le consommateur, par exemple via un file browser ; il n'est pas assimilé au store wallet configuré.
|
||||
|
||||
Pour produire le Base58 tiers, remplacer le format par `WalletTransferFormat::SolanaPrivateKeyBase58`.
|
||||
|
||||
## 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.
|
||||
@@ -342,15 +443,13 @@ Le changement de mot de passe rechiffre la même keypair. Il n'existe pas de rot
|
||||
|
||||
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
|
||||
## Import/export implémenté
|
||||
|
||||
`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.
|
||||
`ks-wallet` importe et exporte désormais le format keypair JSON standard des binaires Solana ainsi que le Base58 du keypair complet de 64 octets. La migration legacy réutilise explicitement le codec `SolanaCliJson`.
|
||||
|
||||
Un export public peut exposer les données autorisées telles que l'alias et la pubkey.
|
||||
Un export public peut toujours exposer uniquement les données autorisées telles que l'alias et la pubkey. **Tout export contenant ou permettant de reconstruire la clé privée demande et valide le mot de passe du wallet.**
|
||||
|
||||
**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.
|
||||
Phantom est la cible tierce de référence du Base58 et Solflare documente l'import direct de cette private key depuis Phantom. Backpack, Trust Wallet, le keystore Solflare et Base app restent reportés tant qu'un contrat Solana précis et testable n'est pas suffisamment documenté pour la surface considérée. Aucune recovery phrase n'est synthétisée à partir d'une keypair arbitraire.
|
||||
|
||||
## Invariants
|
||||
|
||||
@@ -373,4 +472,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.
|
||||
|
||||
`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.
|
||||
`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 et le changement de password. `pre.005` ajoute la migration legacy, les deux formats de transfert testés, les collisions d'alias/pubkey et la matrice de compatibilité. La tranche suivante couvre la configuration et les consommateurs.
|
||||
|
||||
Reference in New Issue
Block a user