khadhroony-bot3/ks-wallet/USAGE.md

Utilisation de ks-wallet

Statut

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

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

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

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

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 :

<alias>.json

Ce format est legacy pour 0.5.2.

Créer un wallet legacy persistant

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

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 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 :

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 :

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 :

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 :

<alias>.kswallet

Le fichier .kswallet sera un conteneur binaire versionné protégé par le mot de passe propre au wallet.

L'API cible doit permettre conceptuellement :

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 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

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.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.