v0.5.2-pre.001
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
# file: Cargo.toml
|
||||
# version: 54
|
||||
# version: 56
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
@@ -18,7 +18,7 @@ members = [
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.5.1"
|
||||
version = "0.5.2-pre.1"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-bot3"
|
||||
|
||||
586
docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md
Normal file
586
docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md
Normal file
@@ -0,0 +1,586 @@
|
||||
<!-- file: docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Plan `0.5.2` — restructuration de `ks-wallet`
|
||||
|
||||
## 1. Objet du plan
|
||||
|
||||
Ce document est le plan temporaire de `0.5.2`.
|
||||
|
||||
`0.5.2-pre.001` reste une prerelease de caractérisation et de cadrage. Elle ne modifie encore aucune API runtime, aucun wallet persistant et aucun format de stockage.
|
||||
|
||||
L'objectif fonctionnel de `0.5.2` est simple : faire de `ks-wallet` le composant Solana généraliste chargé de créer, conserver, ouvrir, signer avec, importer, exporter et gérer plusieurs wallets sans exposer directement leur matériau secret aux consommateurs.
|
||||
|
||||
Le plan doit rester centré sur ce besoin. Les détails cryptographiques ou de concurrence ne deviennent des choix d'implémentation qu'au moment où ils sont nécessaires.
|
||||
|
||||
## 2. Cible fonctionnelle
|
||||
|
||||
À la fin de `0.5.2`, `ks-wallet` doit pouvoir couvrir les responsabilités suivantes.
|
||||
|
||||
### 2.1 Plusieurs wallets persistants
|
||||
|
||||
`ks-wallet` doit pouvoir :
|
||||
|
||||
- créer plusieurs wallets ;
|
||||
- les identifier et y accéder par alias ;
|
||||
- lister leurs identités non sensibles ;
|
||||
- charger un wallet existant ;
|
||||
- refuser les collisions ou écrasements silencieux ;
|
||||
- supprimer un wallet uniquement via une opération explicite si cette surface est retenue pendant l'implémentation.
|
||||
|
||||
Un consommateur ne doit pas avoir besoin de connaître le chemin réel du fichier ou son format interne pour travailler avec un wallet.
|
||||
|
||||
La découverte des wallets persistants doit être faite par `ks-wallet` dans le répertoire de wallet résolu qu'il possède. Avec la configuration actuelle, la racine globale provient de `wallet.config.json.wallets_directory`, surchargeable par `KS_WALLETS_DIRECTORY` et valant `wallets` par défaut ; un profil peut encore résoudre un sous-répertoire.
|
||||
|
||||
Le store doit donc pouvoir scanner son répertoire résolu à la recherche des fichiers :
|
||||
|
||||
```text
|
||||
<alias>.kswallet
|
||||
```
|
||||
|
||||
Le scan doit être borné au répertoire possédé par le store, non récursif par défaut, refuser les symlinks/fichiers non réguliers et ne considérer un candidat comme wallet qu'après validation de l'alias, du suffixe, du magic et de la version du conteneur. Le nom de fichier n'est pas à lui seul une preuve de validité.
|
||||
|
||||
### 2.2 Wallets temporaires ou jetables
|
||||
|
||||
`ks-wallet` doit conserver la capacité actuelle de générer des wallets temporaires en mémoire pour :
|
||||
|
||||
- tests synthétiques ;
|
||||
- scénarios Devnet ;
|
||||
- démonstrations ;
|
||||
- comptes intermédiaires ou jetables.
|
||||
|
||||
Un wallet temporaire n'a pas besoin d'être persisté ni protégé par mot de passe tant qu'il reste purement en mémoire.
|
||||
|
||||
La possibilité de convertir explicitement un wallet temporaire en wallet persistant pourra être retenue si elle simplifie l'API sans créer de nouveau risque.
|
||||
|
||||
### 2.3 Mot de passe par wallet persistant
|
||||
|
||||
Chaque wallet persistant géré nativement par `ks-wallet` doit être protégé par un mot de passe propre au conteneur `ks-wallet`.
|
||||
|
||||
Ce mot de passe n'est pas un « mot de passe Solana ». Il sert à protéger le matériau secret persistant géré par `ks-wallet`.
|
||||
|
||||
L'API doit permettre au minimum :
|
||||
|
||||
- création d'un wallet avec mot de passe ;
|
||||
- ouverture/déverrouillage avec mot de passe ;
|
||||
- fermeture/verrouillage lorsqu'une capacité ouverte est conservée en mémoire ;
|
||||
- changement du mot de passe en fournissant l'ancien mot de passe ;
|
||||
- conservation exacte de la même clé publique après changement de mot de passe.
|
||||
|
||||
Le changement de mot de passe **ne change pas la keypair Solana** : il rechiffre le même matériau secret dans le conteneur `.kswallet`.
|
||||
|
||||
Une rotation du secret Ed25519 tout en conservant la même pubkey n'est pas une fonctionnalité valide à prévoir. Pour une keypair Solana standard, la clé publique est dérivée du secret ; changer réellement le secret produit donc un autre wallet/public key. Une éventuelle rotation de clé future serait une opération distincte impliquant une nouvelle identité et, selon les usages, la migration des fonds/authorities.
|
||||
|
||||
La représentation runtime exacte d'un wallet ouvert sera décidée pendant l'implémentation. Le plan n'impose pas prématurément une hiérarchie complexe de sessions.
|
||||
|
||||
### 2.4 Signature sans exposition du secret
|
||||
|
||||
Les consommateurs doivent demander une capacité de signature à `ks-wallet` plutôt que les octets privés.
|
||||
|
||||
`ks-lib` utilise déjà `solana_signer::Signer` sans dépendre de `ks-wallet`. Cette frontière est saine et doit être préservée :
|
||||
|
||||
```text
|
||||
ks-wallet
|
||||
-> fournit/adapte une capacité de signature
|
||||
ks-lib / exécuteurs
|
||||
-> utilisent Signer
|
||||
-> ne connaissent pas le stockage wallet
|
||||
```
|
||||
|
||||
La manière exacte de fournir cette capacité doit respecter les contraintes `Send`/`Sync` réellement nécessaires, sans rendre le matériau secret clonable par commodité.
|
||||
|
||||
### 2.5 Import et export
|
||||
|
||||
`ks-wallet` doit servir d'intermédiaire entre son format natif et les formats externes explicitement supportés.
|
||||
|
||||
L'import doit obligatoirement couvrir le format fichier standard des binaires Solana (`solana-keygen`, `solana`, outils SPL), actuellement utilisé comme legacy par le workspace : tableau JSON des 64 octets de la keypair. L'export vers ce même format standard est également obligatoire dans `0.5.2`.
|
||||
|
||||
Les formats des wallets tiers doivent être inventoriés à partir de documentation officielle ou d'une spécification/source officielle suffisamment précise. D'autres formats pourront être ajoutés uniquement après caractérisation de leurs contrats réels.
|
||||
|
||||
L'export doit distinguer :
|
||||
|
||||
- les données strictement publiques, qui peuvent être exportées sans révéler de secret ;
|
||||
- tout format contenant ou permettant de reconstruire la clé privée.
|
||||
|
||||
**Tout export secret doit obligatoirement demander et valider le mot de passe du wallet.**
|
||||
|
||||
Il ne doit exister aucun export privé implicite simplement pour satisfaire un consommateur interne.
|
||||
|
||||
L'objectif est notamment de pouvoir exporter volontairement un wallet vers un format accepté par des outils ou wallets externes comme les formats Solana réellement compatibles avec Solflare ou d'autres logiciels. Chaque format doit être vérifié avant implémentation ; il ne faut pas inventer un format externe générique supposé universel.
|
||||
|
||||
## 3. Format natif persistant cible
|
||||
|
||||
Le format legacy `<alias>.json` ne doit pas rester le format natif de `ks-wallet`.
|
||||
|
||||
L'orientation retenue pour `0.5.2` est un fichier natif :
|
||||
|
||||
```text
|
||||
<alias>.kswallet
|
||||
```
|
||||
|
||||
Le conteneur `.kswallet` doit être **binaire**, auto-identifiable et versionné.
|
||||
|
||||
Le caractère binaire n'est pas une mesure cryptographique en lui-même. La confidentialité doit venir d'un mécanisme de chiffrement authentifié standard et d'une dérivation de clé adaptée au mot de passe.
|
||||
|
||||
Le format binaire devra au minimum permettre d'identifier sans ambiguïté :
|
||||
|
||||
- un magic/signature de format ;
|
||||
- une version ;
|
||||
- les paramètres nécessaires au déchiffrement ;
|
||||
- le payload protégé ;
|
||||
- les informations d'intégrité/authentification nécessaires.
|
||||
|
||||
La disposition exacte des champs, l'algorithme AEAD, le KDF, les tailles de nonce/sel et leurs paramètres ne sont **pas** décidés dans `pre.001`. Ils doivent être choisis après vérification des versions réellement résolues des dépendances et des exigences de sécurité.
|
||||
|
||||
`argon2`, `chacha20poly1305` et `zeroize` existent déjà dans les dépendances du workspace, mais leur présence ne suffit pas à fixer le contrat.
|
||||
|
||||
## 4. Caractérisation du legacy actuel
|
||||
|
||||
Le stockage persistant actuel de `ks-wallet` utilise :
|
||||
|
||||
```text
|
||||
<alias>.json
|
||||
```
|
||||
|
||||
Le contenu est le tableau JSON standard des **64 octets** d'un keypair Solana.
|
||||
|
||||
### 4.1 Alias
|
||||
|
||||
Le contrat actuel impose :
|
||||
|
||||
- longueur de 1 à 64 octets ;
|
||||
- premier caractère ASCII alphanumérique ;
|
||||
- caractères suivants ASCII alphanumériques, `_` ou `-`.
|
||||
|
||||
Ces règles sont compatibles avec le futur nom `<alias>.kswallet` et doivent être conservées sauf raison explicite découverte pendant les tests de caractérisation.
|
||||
|
||||
### 4.2 Permissions Unix
|
||||
|
||||
Le comportement actuel impose :
|
||||
|
||||
- répertoire wallet privé en `0700` ;
|
||||
- fichier wallet privé en `0600` ;
|
||||
- refus des symlinks et fichiers non réguliers ;
|
||||
- refus des permissions trop ouvertes lors de la lecture.
|
||||
|
||||
Ces propriétés doivent rester au minimum aussi strictes pour `.kswallet` et les exports privés.
|
||||
|
||||
### 4.3 Création et écrasement
|
||||
|
||||
La création actuelle utilise `create_new`, donc réserve exclusivement le nom final et refuse l'écrasement.
|
||||
|
||||
En revanche, le contenu legacy est écrit directement dans le fichier final. La publication n'est donc pas encore une écriture atomique crash-safe par fichier temporaire + renommage.
|
||||
|
||||
Le nouveau format devra être écrit atomiquement et ne jamais écraser silencieusement un wallet existant.
|
||||
|
||||
### 4.4 Lecture et corruption
|
||||
|
||||
Les tests de caractérisation doivent figer le comportement actuel pour :
|
||||
|
||||
- fichier absent ;
|
||||
- fichier déjà présent ;
|
||||
- contenu corrompu ;
|
||||
- contenu tronqué/incomplet ;
|
||||
- mauvais nombre d'octets ;
|
||||
- permissions incorrectes ;
|
||||
- fichier non régulier ou symlink.
|
||||
|
||||
La fixture doit toujours utiliser une clé synthétique.
|
||||
|
||||
## 5. Migration du legacy
|
||||
|
||||
La migration doit être une **importation** du legacy vers le nouveau format `.kswallet`, pas une réécriture destructive in-place du `.json`.
|
||||
|
||||
Le contrat minimal est :
|
||||
|
||||
1. lire et valider le legacy ;
|
||||
2. reconstruire le keypair ;
|
||||
3. vérifier sa clé publique ;
|
||||
4. demander le mot de passe destiné au nouveau wallet ;
|
||||
5. construire le nouveau `.kswallet` ;
|
||||
6. l'écrire atomiquement dans un nouveau fichier ;
|
||||
7. rouvrir et vérifier le nouveau fichier ;
|
||||
8. confirmer que la clé publique est strictement identique ;
|
||||
9. conserver le legacy tant que la migration n'est pas prouvée complète.
|
||||
|
||||
Aucune migration ne doit transformer automatiquement le legacy en place.
|
||||
|
||||
Si un `.kswallet` existe mais est invalide, `ks-wallet` ne doit pas masquer cette corruption en basculant silencieusement sur un ancien `.json`.
|
||||
|
||||
Le nettoyage éventuel du legacy doit être une opération séparée et explicite, après validation de la migration.
|
||||
|
||||
## 6. Import et export : contrat attendu
|
||||
|
||||
### 6.1 Import
|
||||
|
||||
L'import reçoit une source externe, la valide, récupère le matériau secret uniquement en mémoire, puis crée un nouveau wallet natif `.kswallet` protégé par le mot de passe choisi.
|
||||
|
||||
Les collisions doivent être définies séparément pour :
|
||||
|
||||
- alias déjà utilisé ;
|
||||
- même clé publique déjà gérée sous un autre alias.
|
||||
|
||||
Aucun import ne doit écraser silencieusement un wallet existant.
|
||||
|
||||
### 6.2 Export public
|
||||
|
||||
Une identité publique peut exposer ou exporter uniquement des données sûres, par exemple :
|
||||
|
||||
- alias ;
|
||||
- clé publique ;
|
||||
- type/source si utile ;
|
||||
- état logique non sensible.
|
||||
|
||||
### 6.3 Export secret
|
||||
|
||||
Tout export permettant de reconstruire la clé privée doit :
|
||||
|
||||
- demander le mot de passe du wallet ;
|
||||
- vérifier ce mot de passe avant de produire l'export ;
|
||||
- viser un format explicitement demandé ;
|
||||
- appliquer des permissions privées ;
|
||||
- utiliser une écriture atomique ;
|
||||
- refuser l'écrasement silencieux ;
|
||||
- ne jamais loguer le matériau exporté ni le mot de passe.
|
||||
|
||||
Le mot de passe du conteneur `.kswallet` n'a pas à devenir le mot de passe d'un format externe. L'adaptateur d'export doit respecter le contrat du format cible.
|
||||
|
||||
### 6.4 Matrice de compatibilité externe à établir
|
||||
|
||||
`0.5.2` doit produire une matrice documentée des formats d'entrée/sortie réellement utilisables avec les principaux wallets Solana. L'inventaire doit au minimum examiner :
|
||||
|
||||
- Solana CLI / `solana-keygen` ;
|
||||
- Phantom ;
|
||||
- Solflare ;
|
||||
- Backpack ;
|
||||
- Trust Wallet ;
|
||||
- Coinbase Wallet / Base app ;
|
||||
- tout autre wallet Solana majeur dont un format d'import privé est officiellement documenté et techniquement exploitable à partir d'une keypair `ks-wallet`.
|
||||
|
||||
Pour chaque cible, la matrice doit distinguer :
|
||||
|
||||
- import par clé privée brute ;
|
||||
- import par fichier/keystore ;
|
||||
- import par recovery phrase ;
|
||||
- format/encodage exact lorsqu'il est documenté ;
|
||||
- possibilité réelle de produire ce format à partir d'une keypair Solana arbitraire ;
|
||||
- conservation garantie ou non de la même pubkey ;
|
||||
- disponibilité d'une documentation/spécification officielle suffisamment précise pour écrire et tester l'adaptateur.
|
||||
|
||||
Constats documentaires initiaux au `2026-08-10` :
|
||||
|
||||
| Cible | Surface officiellement documentée | Statut pour `ks-wallet` |
|
||||
|----------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Solana CLI | fichier keypair JSON standard | **obligatoire `0.5.2` en import + export** |
|
||||
| Phantom | import/export de private key Solana et recovery phrase | candidat direct ; encodage exact à figer avant implémentation |
|
||||
| Solflare | import par private key, recovery phrase et keystore | candidat direct ; format exact à figer avant implémentation |
|
||||
| Backpack | import avancé par private key ou recovery phrase | candidat direct ; format exact à figer avant implémentation |
|
||||
| Trust Wallet | restauration par recovery phrase et gestion/export de private keys | candidat à caractériser ; contrat Solana précis à vérifier |
|
||||
| Coinbase Wallet / Base app | restauration principalement documentée par recovery phrase ; Solana supporté | **ne pas fabriquer une recovery phrase supposée équivalente** à partir d'une keypair arbitraire ; faisabilité à caractériser |
|
||||
|
||||
Une recovery phrase n'est pas interchangeable avec une keypair arbitraire. Si `ks-wallet` ne possède que la keypair finale et pas la mnemonic/seed d'origine avec son chemin de dérivation, il ne doit pas inventer une phrase qui prétend restaurer la même pubkey.
|
||||
|
||||
Dans `0.5.2`, après l'adaptateur Solana CLI obligatoire, **un seul adaptateur vers un wallet tiers** doit être implémenté comme exemple de la mécanique d'interopérabilité. Le choix doit aller au format le plus simple et le mieux spécifié au moment de `pre.005`. Les autres formats jugés faisables sont ajoutés au `TODO.md` pour une version ultérieure non déterminée.
|
||||
|
||||
Tout adaptateur tiers reste soumis à la règle générale : un export contenant le secret est impossible sans validation du mot de passe du `.kswallet`.
|
||||
|
||||
## 7. Modèle public simple de `ks-wallet`
|
||||
|
||||
Le plan ne fixe pas encore les noms Rust définitifs, mais la responsabilité cible peut être représentée ainsi :
|
||||
|
||||
```text
|
||||
ks-wallet
|
||||
|
|
||||
+-- manager / store
|
||||
| +-- create persistent(alias, password)
|
||||
| +-- create temporary(...)
|
||||
| +-- scan/discover <alias>.kswallet
|
||||
| +-- list identities
|
||||
| +-- find/open by alias
|
||||
| +-- remove explicitement si retenu
|
||||
|
|
||||
+-- password
|
||||
| +-- unlock/open
|
||||
| +-- lock/close
|
||||
| +-- change password
|
||||
|
|
||||
+-- signing
|
||||
| +-- public key
|
||||
| +-- signer capability
|
||||
|
|
||||
+-- import
|
||||
| +-- legacy Solana JSON
|
||||
| +-- autres formats validés
|
||||
|
|
||||
+-- export
|
||||
+-- public
|
||||
+-- secret + password obligatoire
|
||||
```
|
||||
|
||||
Le stockage réel, les bytes privés et les paramètres cryptographiques restent internes à la crate.
|
||||
|
||||
## 8. Multi-wallet et configuration
|
||||
|
||||
`ks-wallet` doit être capable de gérer plusieurs wallets sans notion globale mutable de « wallet actif ».
|
||||
|
||||
La sélection appartient au consommateur :
|
||||
|
||||
```text
|
||||
worker A -> alias A
|
||||
worker B -> alias B
|
||||
application -> alias C
|
||||
```
|
||||
|
||||
`ks-config` peut transporter un alias ou une sélection non sensible, mais ne devient jamais gestionnaire du mot de passe ou du matériau secret.
|
||||
|
||||
Un profil peut continuer à sélectionner un alias lorsqu'un consommateur n'en attend qu'un, mais `ks-wallet` ne doit pas imposer qu'il existe un « alias principal » universel.
|
||||
|
||||
## 9. Consommateurs actuels
|
||||
|
||||
L'inventaire `pre.001` montre deux dépendants directs de `ks-wallet` :
|
||||
|
||||
- `ks-pipeline-demo-scenarios` ;
|
||||
- `kb-app-demo-desktop`.
|
||||
|
||||
`ks-lib` n'a pas de dépendance directe vers `ks-wallet` et consomme des `solana_signer::Signer`. Cette séparation doit être conservée.
|
||||
|
||||
Le desktop ne doit jamais recevoir directement un type runtime sensible de `ks-wallet` :
|
||||
|
||||
```text
|
||||
ks-wallet runtime
|
||||
-> DTO possédé par kb-app-demo-desktop
|
||||
-> TS-RS
|
||||
-> frontend
|
||||
```
|
||||
|
||||
Le DTO peut exposer alias, pubkey et état logique lorsque ces données sont explicitement sûres.
|
||||
|
||||
## 10. Compatibilité avec les outils Solana existants
|
||||
|
||||
Le workspace utilise encore le fichier keypair legacy brut avec certains outils externes, notamment les workflows Devnet autour de `solana-keygen` / `spl-token` et `KS_DEVNET_WALLET`.
|
||||
|
||||
Un `.kswallet` ne doit pas être présenté directement à ces outils.
|
||||
|
||||
La transition doit donc choisir explicitement entre :
|
||||
|
||||
- import/export volontaire vers le format keypair JSON standard accepté par les binaires Solana ;
|
||||
- adaptation d'un scénario pour signer directement via `ks-wallet` ;
|
||||
- maintien borné du legacy pour un workflow de transition.
|
||||
|
||||
Il ne faut pas créer un export privé automatique ou caché juste pour conserver un ancien script.
|
||||
|
||||
## 11. Sécurité et non-divulgation
|
||||
|
||||
Les contraintes suivantes restent non négociables :
|
||||
|
||||
- aucun secret wallet dans un fichier de configuration source ;
|
||||
- aucun secret dans `KS_PUBLIC_*` ou `KB_PUBLIC_*` ;
|
||||
- aucun secret dans Tauri ou TS-RS générique ;
|
||||
- aucun mot de passe, octet privé, payload chiffré ou keypair dans logs/erreurs/diagnostics normaux ;
|
||||
- aucun `Debug` automatique d'un type possédant du matériau secret ;
|
||||
- aucun getter public arbitraire des bytes privés ;
|
||||
- zéroïsation des buffers secrets temporaires lorsque les types et dépendances le permettent ;
|
||||
- les erreurs publiques ne doivent pas inclure inutilement le chemin local complet du wallet.
|
||||
|
||||
Le fait que `.kswallet` soit binaire ne remplace aucune de ces protections.
|
||||
|
||||
## 12. Tests minimums de `0.5.2`
|
||||
|
||||
### 12.1 Legacy
|
||||
|
||||
- fixture synthétique 64 octets ;
|
||||
- alias et nom `<alias>.json` ;
|
||||
- pubkey conservée après lecture/import ;
|
||||
- absent, déjà présent, corrompu, tronqué, longueur invalide ;
|
||||
- permissions Unix ;
|
||||
- symlink et fichier non régulier.
|
||||
|
||||
### 12.2 Format `.kswallet`
|
||||
|
||||
- magic et version ;
|
||||
- version inconnue ;
|
||||
- troncature/corruption ;
|
||||
- mauvais mot de passe ;
|
||||
- intégrité/authentification ;
|
||||
- permissions privées ;
|
||||
- écriture atomique ;
|
||||
- refus d'écrasement ;
|
||||
- persistance puis réouverture ;
|
||||
- absence de secret dans `Debug`, erreurs et logs.
|
||||
|
||||
### 12.3 Multi-wallet et password
|
||||
|
||||
- création de plusieurs aliases ;
|
||||
- lookup par alias ;
|
||||
- collision d'alias ;
|
||||
- collision de pubkey selon le contrat retenu ;
|
||||
- changement de mot de passe ;
|
||||
- ancien mot de passe refusé après changement ;
|
||||
- nouveau mot de passe accepté ;
|
||||
- pubkey inchangée ;
|
||||
- vérification que la keypair est strictement identique avant/après changement de mot de passe ;
|
||||
- absence d'API prétendant faire tourner le secret Ed25519 en conservant la pubkey.
|
||||
|
||||
### 12.4 Temporaire et signature
|
||||
|
||||
- génération purement mémoire ;
|
||||
- signature valide ;
|
||||
- aucune persistance involontaire ;
|
||||
- capacité de signature utilisable par les consommateurs réels sans exposition des bytes ;
|
||||
- contraintes thread-safety des chemins effectivement utilisés.
|
||||
|
||||
### 12.5 Import/export
|
||||
|
||||
- import du fichier Solana CLI JSON préservant la pubkey ;
|
||||
- export vers le fichier Solana CLI JSON avec mot de passe valide ;
|
||||
- round-trip `.kswallet` -> Solana CLI JSON -> import préservant la pubkey ;
|
||||
- import corrompu refusé ;
|
||||
- collision refusée ;
|
||||
- export secret impossible sans mot de passe valide ;
|
||||
- export secret avec mot de passe valide vers chaque format effectivement supporté ;
|
||||
- matrice Phantom/Solflare/Backpack/Trust/Coinbase-Base et autres cibles retenues ;
|
||||
- un adaptateur wallet tiers d'exemple implémenté et testé ;
|
||||
- autres adaptateurs faisables reportés explicitement au TODO ;
|
||||
- permissions privées et écriture atomique de l'export ;
|
||||
- aucun secret dans les erreurs/logs.
|
||||
|
||||
### 12.6 Configuration et desktop
|
||||
|
||||
- sélection d'un alias sans secret dans `ks-config` ;
|
||||
- aucune dépendance inverse vers une application ;
|
||||
- DTO desktop non sensible ;
|
||||
- canaris de non-divulgation des mots de passe, bytes privés, chemins internes et payloads protégés.
|
||||
|
||||
## 13. Découpage proposé des prereleases
|
||||
|
||||
Le découpage reste borné mais peut être ajusté si une tranche devient trop large après compilation/tests.
|
||||
|
||||
### `0.5.2-pre.001` — plan et caractérisation
|
||||
|
||||
- audit du code et des consommateurs ;
|
||||
- caractérisation legacy ;
|
||||
- besoins multi-wallet, temporary wallet, password, import/export ;
|
||||
- orientation `.kswallet` binaire ;
|
||||
- contrat migration/rollback ;
|
||||
- plan temporaire.
|
||||
|
||||
**Aucun nouveau format n'est écrit dans cette prerelease.**
|
||||
|
||||
### `0.5.2-pre.002` — caractérisation exécutable et API de base
|
||||
|
||||
- tests externes du legacy ;
|
||||
- identité publique minimale ;
|
||||
- manager/scan/listing/lookup multi-wallet ;
|
||||
- contrat de wallet temporaire ;
|
||||
- frontière de signature compatible avec `ks-lib`.
|
||||
|
||||
### `0.5.2-pre.003` — codec et stockage `.kswallet`
|
||||
|
||||
- spécification binaire versionnée ;
|
||||
- sélection et justification KDF/AEAD ;
|
||||
- encode/decode stricts ;
|
||||
- bornes de taille ;
|
||||
- permissions ;
|
||||
- écriture atomique ;
|
||||
- tests corruption/version/atomicité.
|
||||
|
||||
### `0.5.2-pre.004` — password et cycle de vie persistant
|
||||
|
||||
- création persistante avec password ;
|
||||
- ouverture/déverrouillage ;
|
||||
- fermeture/verrouillage selon le modèle runtime retenu ;
|
||||
- changement de mot de passe ;
|
||||
- signature après ouverture ;
|
||||
- non-divulgation et zéroïsation.
|
||||
|
||||
### `0.5.2-pre.005` — migration, import et export
|
||||
|
||||
- import legacy/Solana CLI JSON vers `.kswallet` ;
|
||||
- export `.kswallet` vers le format Solana CLI JSON ;
|
||||
- rollback et conservation du legacy ;
|
||||
- finalisation de la matrice des formats wallets tiers ;
|
||||
- implémentation d'un adaptateur wallet tiers d'exemple, choisi selon simplicité et qualité de spécification ;
|
||||
- report des autres adaptateurs faisables au TODO pour une version ultérieure non déterminée ;
|
||||
- password obligatoire pour tout export secret ;
|
||||
- collisions d'alias/pubkey ;
|
||||
- tests de compatibilité.
|
||||
|
||||
### `0.5.2-pre.006` — configuration et consommateurs
|
||||
|
||||
- sélection par alias dans `ks-config` sans secret ;
|
||||
- adaptation `ks-pipeline-demo-scenarios` ;
|
||||
- adaptation desktop uniquement via DTO sûrs ;
|
||||
- résolution explicite des workflows CLI legacy ;
|
||||
- tests d'intégration et canaris de non-divulgation.
|
||||
|
||||
Cette tranche ne doit pas devenir la refonte générale des scénarios prévue pour `0.5.4`.
|
||||
|
||||
### `0.5.2-pre.007` — finalisation
|
||||
|
||||
- réconciliation des contrats ;
|
||||
- validations finales ;
|
||||
- README/USAGE/TODO/changelogs/guides ;
|
||||
- report des tâches restantes vers une version identifiée ;
|
||||
- mise à jour du ROADMAP ;
|
||||
- archivage du plan et du prompt `0.5.2` sous `olddocs/archivekbot3/` ;
|
||||
- préparation du prompt `0.5.3` consacré à `ks-store`.
|
||||
|
||||
## 14. Critères de clôture
|
||||
|
||||
`0.5.2` est terminée lorsque :
|
||||
|
||||
- plusieurs wallets persistants peuvent être découverts dans le store et gérés par alias ;
|
||||
- les wallets temporaires restent disponibles pour tests/scénarios ;
|
||||
- le format natif persistant est `.kswallet`, binaire, versionné et protégé par mot de passe ;
|
||||
- le changement de mot de passe conserve exactement la même keypair et donc la pubkey ;
|
||||
- un consommateur peut signer sans obtenir les bytes privés ;
|
||||
- le legacy peut être importé sans perte ni écrasement destructif ;
|
||||
- le format Solana CLI JSON dispose d'un import/export testé ;
|
||||
- un adaptateur vers un wallet tiers documenté est implémenté et testé ;
|
||||
- les autres formats tiers faisables identifiés sont consignés au TODO ;
|
||||
- tout export secret exige un mot de passe valide ;
|
||||
- `ks-config` ne contient que de la sélection non sensible ;
|
||||
- `ks-lib` reste indépendant du stockage wallet ;
|
||||
- le desktop ne reçoit que des DTO sûrs ;
|
||||
- permissions, atomicité, corruption, collisions et non-divulgation sont testées ;
|
||||
- la documentation finale décrit le contrat réellement implémenté.
|
||||
|
||||
## 15. Hors périmètre
|
||||
|
||||
Restent hors `0.5.2` :
|
||||
|
||||
- migration SQL `kb_sol_*` -> `k_sol_*` ;
|
||||
- audit temporel/provenance de `ks-store` ;
|
||||
- centralisation générale des scénarios `0.5.4` ;
|
||||
- nouvelle couverture Anchor/DEX ;
|
||||
- stockage d'un secret wallet dans PostgreSQL ;
|
||||
- hardware wallets / Ledger ;
|
||||
- KMS/HSM ;
|
||||
- remote signers ;
|
||||
- secret manager universel ;
|
||||
- cloud backup ;
|
||||
- protection contre un utilisateur qui transfère volontairement un fichier `.kswallet` avec son mot de passe à une autre installation capable de comprendre ce format.
|
||||
|
||||
## 16. Décisions validées pour poursuivre après `pre.001`
|
||||
|
||||
Le plan est désormais centré sur les décisions suivantes :
|
||||
|
||||
1. `ks-wallet` gère plusieurs wallets accessibles par alias ;
|
||||
2. `ks-wallet` conserve des wallets temporaires/jetables ;
|
||||
3. chaque wallet persistant natif possède un mot de passe modifiable ;
|
||||
4. le format natif cible est un conteneur **binaire** `<alias>.kswallet` ;
|
||||
5. le format binaire utilise des primitives cryptographiques standard, pas une cryptographie propriétaire ;
|
||||
6. les consommateurs signent via une capacité contrôlée sans accéder aux bytes privés ;
|
||||
7. `ks-lib` reste indépendant de `ks-wallet` et du stockage ;
|
||||
8. import et export vers des formats externes font partie du périmètre `0.5.2` ;
|
||||
9. tout export secret exige le mot de passe valide du wallet ;
|
||||
10. la migration legacy crée un nouveau `.kswallet`, valide la pubkey et conserve le legacy jusqu'à preuve de réussite ;
|
||||
11. `ks-config` peut sélectionner des aliases mais ne gère aucun secret ;
|
||||
12. la découverte persistante scanne le répertoire wallet résolu pour les `<alias>.kswallet`, sans faire confiance au seul nom de fichier ;
|
||||
13. changer le password rechiffre la même keypair ; il n'existe pas de rotation du secret Ed25519 conservant la même pubkey ;
|
||||
14. le format keypair JSON des binaires Solana est obligatoire en import et en export dans `0.5.2` ;
|
||||
15. une matrice officielle des formats Phantom/Solflare/Backpack/Trust/Coinbase-Base et autres cibles pertinentes sera finalisée avant les adaptateurs ;
|
||||
16. un seul adaptateur wallet tiers est implémenté dans `0.5.2` comme exemple, les autres formats faisables étant reportés au TODO sans version déterminée ;
|
||||
17. les détails KDF/AEAD et le modèle runtime d'un wallet ouvert seront décidés dans leurs tranches techniques, après tests et vérification des dépendances.
|
||||
|
||||
Ces décisions suffisent pour ouvrir `0.5.2-pre.002` après validation du présent fix de `pre.001`.
|
||||
@@ -1,8 +1,34 @@
|
||||
<!-- file: ks-wallet/CHANGELOG.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# CHANGELOG — ks-wallet
|
||||
|
||||
## `0.5.2-pre.001`
|
||||
|
||||
- caractérise précisément le format legacy `<alias>.json`, ses permissions Unix, ses erreurs, sa publication directe dans le chemin final et ses limites d’atomicité/TOCTOU ;
|
||||
- inventorie les consommateurs `ks-wallet`, les usages directs de `solana_keypair` / `solana_signer`, les variables/configurations wallet et les workflows CLI qui dépendent encore du keypair Solana brut ;
|
||||
- définit le contrat fonctionnel `0.5.2` autour de la gestion multi-wallet par alias, des wallets temporaires/jetables, du mot de passe modifiable, de la signature sans exposition du secret et de l’import/export explicite ;
|
||||
- retient comme cible un conteneur natif binaire versionné `<alias>.kswallet`, sans fixer prématurément KDF/AEAD ou layout binaire ;
|
||||
- impose un mot de passe valide pour tout export contenant ou permettant de reconstruire le secret ;
|
||||
- définit la migration legacy comme import vers un nouveau `.kswallet` avec conservation de la pubkey, écriture atomique et rollback, sans réécriture destructive du `.json` ;
|
||||
- corrige README/USAGE/TODO afin d’aligner les objectifs sur ce contrat simplifié ;
|
||||
- ne modifie aucune API runtime, aucun fichier wallet et n’introduit encore aucun nouveau format persistant.
|
||||
|
||||
### `pre.001-delta-fix-001`
|
||||
|
||||
- corrige la version Cargo de `0.5.2-pre.001` vers le SemVer valide `0.5.2-pre.1` ;
|
||||
- simplifie profondément le plan initial, retire l’exclusion erronée de l’export privé contrôlé et supprime l’hypothèse d’un alias principal universel par profil ;
|
||||
- formalise l’extension native `.kswallet`, le wallet temporaire et l’obligation de password pour tout export secret.
|
||||
|
||||
### `pre.001-delta-fix-002`
|
||||
|
||||
- précise que `ks-wallet` découvrira les wallets persistants par scan borné des `<alias>.kswallet` dans son répertoire résolu, sans faire confiance au seul nom de fichier ;
|
||||
- distingue explicitement changement de password et rotation de keypair : le password rechiffre la même keypair, tandis qu’un nouveau secret Ed25519 implique une nouvelle pubkey ;
|
||||
- rend obligatoires l’import **et** l’export du format keypair JSON standard utilisé par les binaires Solana ;
|
||||
- ajoute une matrice de compatibilité à établir pour Phantom, Solflare, Backpack, Trust Wallet, Coinbase/Base et les autres wallets Solana techniquement documentés ;
|
||||
- borne `0.5.2` à un adaptateur wallet tiers d’exemple en plus du format Solana CLI obligatoire, avec report des autres adaptateurs faisables au TODO pour une version ultérieure non déterminée ;
|
||||
- interdit de synthétiser une recovery phrase supposée restaurer une keypair arbitraire lorsque la mnemonic/seed d’origine n’est pas disponible.
|
||||
|
||||
## `0.5.1-pre.002`
|
||||
|
||||
- renomme `kb-wallet` en `ks-wallet` et `kb_wallet` en `ks_wallet` ;
|
||||
|
||||
@@ -1,46 +1,58 @@
|
||||
<!-- file: ks-wallet/README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# ks-wallet
|
||||
|
||||
`ks-wallet` fournit actuellement une frontière locale minimale de portefeuille pour les démonstrations et tests d’intégration.
|
||||
`ks-wallet` fournit la frontière wallet Solana générale du workspace Khadhroony.
|
||||
|
||||
## État actuel
|
||||
|
||||
La crate est une ébauche fonctionnelle, pas un gestionnaire de wallets complet.
|
||||
En `0.5.2-pre.001`, la crate reste une ébauche fonctionnelle basée sur le format legacy Solana JSON. La restructuration `0.5.2` est encore au stade plan/caractérisation et ne modifie pas le runtime.
|
||||
|
||||
Elle fournit :
|
||||
La crate fournit actuellement :
|
||||
|
||||
- alias validés ;
|
||||
- wallet temporaire en mémoire ;
|
||||
- stockage local JSON d’un keypair Solana ;
|
||||
- chargement ou création atomique ;
|
||||
- résumé non secret ;
|
||||
- stockage local JSON d'un keypair Solana ;
|
||||
- création exclusive avec refus d'écrasement et reprise des courses `load_or_create` ;
|
||||
- résumé sans matériau cryptographique secret, mais contenant encore un chemin local interne ;
|
||||
- accès au trait `Signer` sans exposition des octets ;
|
||||
- signature de messages ;
|
||||
- permissions Unix privées et contrôles de fichiers ;
|
||||
- effacement des buffers secrets utilisés lors de la lecture ou écriture.
|
||||
- effacement des buffers secrets temporaires utilisés lors de la lecture ou écriture.
|
||||
|
||||
## Hors capacités actuelles
|
||||
La persistance legacy écrit encore directement le contenu dans le chemin final : elle n'est pas une publication atomique crash-safe par fichier temporaire + renommage.
|
||||
|
||||
Les fonctions suivantes ne sont pas encore implémentées :
|
||||
## Cible `0.5.2`
|
||||
|
||||
- chiffrement par mot de passe ;
|
||||
- plusieurs wallets gérés comme collection ;
|
||||
- sélection persistante du wallet actif ;
|
||||
- import/export contrôlé ;
|
||||
- changement de mot de passe ;
|
||||
- verrouillage et déverrouillage ;
|
||||
- sauvegarde et restauration ;
|
||||
- politiques de sécurité complètes.
|
||||
`ks-wallet` doit devenir capable de :
|
||||
|
||||
- découvrir dans le store les fichiers `<alias>.kswallet` valides et gérer plusieurs wallets persistants accessibles par alias ;
|
||||
- conserver des wallets temporaires/jetables pour tests et scénarios ;
|
||||
- stocker les wallets persistants dans un format natif binaire `<alias>.kswallet` ;
|
||||
- protéger chaque wallet persistant par un mot de passe modifiable ;
|
||||
- fournir une capacité de signature sans exposer les bytes privés ;
|
||||
- importer le format legacy et d'autres formats explicitement supportés ;
|
||||
- exporter volontairement vers des formats externes supportés ;
|
||||
- exiger un mot de passe valide pour tout export contenant le secret ;
|
||||
- préserver exactement la même keypair lors d'un changement de mot de passe ;
|
||||
- importer et exporter obligatoirement le format keypair JSON des binaires Solana ;
|
||||
- documenter les formats compatibles des principaux wallets Solana, implémenter un adaptateur tiers d'exemple et reporter les autres au TODO.
|
||||
|
||||
Le format `.kswallet` sera propre à `ks-wallet`, mais sa protection cryptographique utilisera des primitives standards. Changer le mot de passe ne change jamais la keypair : une modification réelle du secret Ed25519 produirait une autre pubkey et donc un autre wallet. Le détail du KDF, de l'AEAD et du layout binaire sera fixé dans les tranches techniques après validation du plan et des dépendances réellement résolues.
|
||||
|
||||
## Relations
|
||||
|
||||
`ks-wallet` fournit un signer. Les limites de dépense, la simulation, l’autorisation opérateur et l’envoi sont gérés par `ks-lib`, `ks-pipeline-demo-scenarios` et les applications.
|
||||
`ks-wallet` possède et gère le wallet. Les exécuteurs et `ks-lib` doivent dépendre d'une capacité de signature, pas du format de stockage ni des octets privés.
|
||||
|
||||
`ks-config` peut sélectionner un alias ou une identité non sensible, mais ne stocke aucun mot de passe ni matériau secret.
|
||||
|
||||
Une application desktop doit projeter les informations autorisées dans ses propres DTO Tauri ; `ks-wallet` ne réintroduit pas TS-RS.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [USAGE.md](USAGE.md)
|
||||
- [TODO.md](TODO.md)
|
||||
- [CHANGELOG.md](CHANGELOG.md)
|
||||
- [plan temporaire `0.5.2`](../docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md)
|
||||
- [ROADMAP général](../ROADMAP.md)
|
||||
|
||||
@@ -1,19 +1,29 @@
|
||||
<!-- file: ks-wallet/TODO.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# TODO — ks-wallet
|
||||
|
||||
## Série `0.5.x`
|
||||
## `0.5.2`
|
||||
|
||||
- [ ] `0.5.2` - caractériser le format legacy `<alias>.json` contenant le tableau JSON standard du keypair Solana.
|
||||
- [ ] `0.5.2` - définir un conteneur persistant versionné avant d’introduire le chiffrement.
|
||||
- [ ] `0.5.2` - séparer identité publique, matériau secret, état verrouillé/déverrouillé et capacité de signature.
|
||||
- [ ] Migration - définir import legacy, écriture atomique, rollback et conservation de la clé publique.
|
||||
- [ ] Fonctionnalité - gérer plusieurs wallets persistants et la sélection du wallet actif si retenue.
|
||||
- [ ] Sécurité - ajouter chiffrement/déchiffrement et changement de secret seulement après validation du format.
|
||||
- [ ] Sécurité - ajouter verrouillage/déverrouillage explicites et invalidation de session.
|
||||
- [ ] Fonctionnalité - ajouter import/export, sauvegarde/restauration avec contrats de sécurité explicites.
|
||||
- [ ] Sécurité - interdire tout secret wallet dans config générale, logs, erreurs, diagnostics ou Tauri.
|
||||
- [ ] Intégration - relier la sélection du wallet aux profils et signers sans exposer les octets secrets.
|
||||
- [ ] Tests - ajouter une API externe de caractérisation, corruption, concurrence, récupération et migration.
|
||||
- [ ] Documentation - produire un guide de sécurité avant tout usage hors démonstration.
|
||||
- [ ] caractériser par tests externes le format legacy `<alias>.json`, ses erreurs et ses permissions.
|
||||
- [ ] définir l'identité publique minimale d'un wallet et le lookup par alias.
|
||||
- [ ] gérer plusieurs wallets persistants sans wallet actif global mutable et les découvrir par scan borné des `<alias>.kswallet` du store résolu.
|
||||
- [ ] conserver/généraliser les wallets temporaires ou jetables purement en mémoire.
|
||||
- [ ] spécifier puis implémenter le format natif binaire versionné `<alias>.kswallet`.
|
||||
- [ ] sélectionner et documenter KDF/AEAD/paramètres après vérification des dépendances résolues.
|
||||
- [ ] créer/ouvrir un wallet persistant avec mot de passe sans exposer les bytes privés.
|
||||
- [ ] permettre le changement de mot de passe en rechiffrant exactement la même keypair et donc en conservant la même pubkey.
|
||||
- [ ] fournir une capacité de signature compatible avec les consommateurs sans dépendance de `ks-lib` vers `ks-wallet`.
|
||||
- [ ] importer le legacy Solana JSON vers `.kswallet` avec écriture atomique, rollback et vérification de pubkey.
|
||||
- [ ] importer et exporter le format keypair JSON standard des binaires Solana.
|
||||
- [ ] produire une matrice documentée des formats Phantom, Solflare, Backpack, Trust Wallet, Coinbase/Base et autres wallets Solana pertinents.
|
||||
- [ ] implémenter dans `0.5.2` un seul adaptateur wallet tiers d'exemple, choisi selon simplicité et qualité de la spécification officielle.
|
||||
- [ ] reporter les autres adaptateurs tiers faisables vers une version ultérieure non déterminée après validation de la matrice.
|
||||
- [ ] ne jamais synthétiser une recovery phrase supposée préserver une keypair arbitraire sans mnemonic/seed d'origine.
|
||||
- [ ] exiger le mot de passe valide pour tout export contenant le secret.
|
||||
- [ ] définir les collisions d'alias et de pubkey sans écrasement silencieux.
|
||||
- [ ] normaliser la sélection par alias dans `ks-config` sans secret.
|
||||
- [ ] adapter les consommateurs et le desktop uniquement via des surfaces non sensibles.
|
||||
- [ ] retirer secrets et chemins locaux inutiles des logs, erreurs, diagnostics et DTO.
|
||||
- [ ] tester permissions privées, atomicité, corruption, concurrence réellement utilisée et non-divulgation.
|
||||
- [ ] produire le guide de sécurité et la documentation finale avant clôture de `0.5.2`.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: ks-wallet/USAGE.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Utilisation de ks-wallet
|
||||
|
||||
## Objectif
|
||||
## Statut
|
||||
|
||||
La crate fournit des wallets temporaires en mémoire ou persistés localement pour les démonstrations et tests d’intégration.
|
||||
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.
|
||||
|
||||
## Valider un alias
|
||||
|
||||
@@ -24,7 +24,7 @@ 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
|
||||
## Générer un wallet temporaire en mémoire
|
||||
|
||||
```rust
|
||||
let alias = match ks_wallet::WalletAlias::parse(
|
||||
@@ -36,14 +36,15 @@ let alias = match ks_wallet::WalletAlias::parse(
|
||||
},
|
||||
};
|
||||
|
||||
let wallet =
|
||||
ks_wallet::TemporaryWallet::generate(alias);
|
||||
let wallet = ks_wallet::TemporaryWallet::generate(alias);
|
||||
let summary = wallet.summary();
|
||||
|
||||
assert!(summary.storage_path.is_none());
|
||||
println!("public key={}", summary.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
|
||||
@@ -61,9 +62,11 @@ 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.
|
||||
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.
|
||||
|
||||
## Créer un stockage local
|
||||
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(
|
||||
@@ -74,14 +77,17 @@ let store = match ks_wallet::TemporaryWalletStore::new(
|
||||
return std::result::Result::Err(error);
|
||||
},
|
||||
};
|
||||
|
||||
println!(
|
||||
"wallet directory={}",
|
||||
store.directory().display()
|
||||
);
|
||||
```
|
||||
|
||||
## Créer un wallet persistant
|
||||
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(
|
||||
@@ -104,9 +110,9 @@ let summary = wallet.summary();
|
||||
assert!(summary.storage_path.is_some());
|
||||
```
|
||||
|
||||
`create` refuse d’écraser un fichier existant.
|
||||
`create` refuse d'écraser un fichier existant.
|
||||
|
||||
## Charger ou créer atomiquement
|
||||
### Charger ou créer sans écrasement
|
||||
|
||||
```rust
|
||||
let alias = match ks_wallet::WalletAlias::parse(
|
||||
@@ -128,57 +134,67 @@ let wallet = match store.load_or_create(alias).await {
|
||||
println!("wallet={}", wallet.public_key());
|
||||
```
|
||||
|
||||
## Vérifier l’existence et le chemin
|
||||
`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.
|
||||
|
||||
```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);
|
||||
},
|
||||
};
|
||||
Le contenu legacy est toutefois écrit directement dans le chemin final. La publication n'est pas encore crash-safe/atomique par fichier temporaire + renommage.
|
||||
|
||||
println!("path={}, exists={exists}", path.display());
|
||||
## Cible persistante `0.5.2`
|
||||
|
||||
Le nouveau stockage natif doit utiliser :
|
||||
|
||||
```text
|
||||
<alias>.kswallet
|
||||
```
|
||||
|
||||
## Politique non secrète
|
||||
Le fichier `.kswallet` sera un conteneur binaire versionné protégé par le mot de passe propre au wallet.
|
||||
|
||||
```rust
|
||||
let policy = ks_wallet::WalletPolicy {
|
||||
signing_enabled: true,
|
||||
lamport_spend_limit: std::option::Option::Some(
|
||||
1_000_000,
|
||||
),
|
||||
};
|
||||
L'API cible doit permettre conceptuellement :
|
||||
|
||||
assert!(policy.signing_enabled);
|
||||
```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
|
||||
```
|
||||
|
||||
`WalletPolicy` transporte une intention de politique. Son application effective appartient à la couche d’exécution.
|
||||
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.
|
||||
|
||||
## Erreurs et invariants
|
||||
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 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 noms Rust définitifs et le modèle runtime exact seront décidés dans les prereleases d'implémentation.
|
||||
|
||||
## 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 ;
|
||||
- les résumés publics ne doivent pas exposer inutilement les chemins locaux ;
|
||||
- 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 ;
|
||||
- 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
|
||||
## Tests de référence actuels
|
||||
|
||||
- validation des alias ;
|
||||
- génération et signature sans persistance ;
|
||||
- création, chargement et `load_or_create` ;
|
||||
- refus d’écrasement ;
|
||||
- création exclusive, 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.
|
||||
- vérification des permissions Unix privées.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user