# Khadhroony Bot3 — `0.5.2` — restructuration de `ks-wallet` ## Mission Reprendre `khadhroony-bot3` après la clôture validée de `0.5.1` et restructurer `ks-wallet` comme composant Solana généraliste réutilisable par les futurs exécuteurs, workers et applications. `0.5.2` doit stabiliser les frontières entre : 1. identité publique d’un wallet ; 2. matériau secret persistant ; 3. état verrouillé/déverrouillé ; 4. capacité de signature ; 5. sélection/configuration d’un wallet par les consommateurs ; 6. migration du format legacy déjà utilisé par le workspace. Cette version est un chantier wallet/sécurité. Elle ne doit pas ouvrir `0.5.3` sur `ks-store`, `0.5.4` sur les scénarios/exécuteurs, ni une nouvelle couverture Anchor/DEX. ## Base validée héritée de `0.5.1` La base attendue possède notamment : - les dix crates Solana généralistes sous `ks-*` / `ks_*` ; - `kb-app-demo-desktop` dans le domaine Bot ; - variables Solana sous `KS_*` et contrats applicatifs Bot sous `KB_*` ; - documents spécialisés `logging.config.json`, `transport.config.json`, `listeners.config.json`, `store.config.json`, `wallet.config.json` et `execution.config.json` ; - exemples conformes sous `config/exemples/` et schémas sous `config/schemas/` ; - composition propre au desktop via `config/kb-app-demo-desktop.default.config.json` ; - classification `Secret > Internal > Public` ; - contrats source/runtime sensibles backend-only ; - TS-RS absent de `ks-config` et `ks-lib`, avec DTO Tauri possédés par les applications ; - URLs résolues retirées des snapshots transport et des surfaces Tauri. Ne pas réintroduire un type `ks-wallet` directement sérialisable vers le frontend par commodité. ## Invariants de namespace Le workspace, le dépôt et le répertoire racine restent `khadhroony-bot3`. `ks-wallet` appartient au domaine Khadhroony Solana. Ses variables utilisent donc `KS_*`. Une future application Bot peut utiliser `KB_*` uniquement pour ses propres choix applicatifs, jamais pour renommer artificiellement un contrat wallet généraliste. Les secrets wallet ne doivent jamais être placés dans : - un fichier de configuration source ; - `KS_PUBLIC_*` ou `KB_PUBLIC_*` ; - un payload Tauri ; - un diagnostic normal ; - un log ou une erreur ; - un `Debug` automatique ; - un binding TS-RS générique. ## Première prerelease obligatoire : plan et caractérisation `0.5.2-pre.001` doit être un plan/brainstorm/inventaire. Ne pas commencer par introduire un nouveau format chiffré. La première prerelease doit au minimum : - relire `ks-wallet/README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md` et tout son code ; - inventorier tous les consommateurs de `ks-wallet` dans le workspace ; - inventorier les chemins de configuration wallet et variables d’environnement ; - caractériser exactement le format legacy `.json` actuellement utilisé ; - caractériser les permissions de fichier et comportements Unix actuels ; - inventorier création temporaire, persistance, lecture, validation, signature et erreurs ; - relever toutes les dérivations `Clone`, `Debug`, `Serialize`, conversions ou getters pouvant copier/afficher du matériau sensible ; - inventorier les usages directs de `solana_keypair`, `solana_signer::Signer`, `Arc` ou équivalents ; - définir les besoins réels multi-wallets et multi-profils sans inventer une UI non demandée ; - définir un contrat de migration et de rollback avant toute écriture du nouveau format ; - proposer un découpage borné des prereleases de `0.5.2` ; - créer un plan temporaire `0.5.2` sous `docs/plans/`, qui sera archivé dans la dernière prerelease. Le plan doit être validé avant la première migration de format. ## Format legacy à préserver comme entrée de migration Le workspace possède actuellement un format persistant legacy basé sur le tableau JSON standard d’octets du keypair Solana. Avant de le remplacer : - écrire des tests de caractérisation à partir d’une fixture synthétique ; - vérifier le nommage `.json` et les contraintes d’alias ; - vérifier les permissions de fichier existantes ; - vérifier le comportement en cas de fichier absent, corrompu, incomplet ou déjà présent ; - vérifier que la clé publique obtenue après import correspond exactement à l’ancienne ; - interdire toute réécriture destructive sans preuve que la migration est complète. Ne jamais utiliser une vraie clé privée de l’opérateur comme fixture. ## Cible conceptuelle du nouveau contrat La solution exacte doit être décidée après audit, mais les frontières suivantes doivent être explicites. ### Identité publique Une identité publique peut contenir par exemple : - alias logique ; - clé publique ; - type/source de wallet ; - état disponible/verrouillé ; - métadonnées non sensibles strictement nécessaires. Elle ne contient jamais les octets secrets. ### Matériau secret Le matériau secret : - reste encapsulé ; - n’implémente pas `Debug` en clair ; - n’est pas sérialisé arbitrairement ; - doit pouvoir être zéroïsé lorsque le type et les dépendances le permettent ; - n’est jamais exposé par getter de bytes public sans justification explicite. ### Capacité de signature Les consommateurs doivent dépendre d’une capacité de signature bornée plutôt que d’un accès aux octets privés. Évaluer notamment : - trait propre à `ks-wallet` ou adaptation stricte à `solana_signer::Signer` ; - ownership et thread-safety ; - passage vers les exécuteurs sans rendre le secret clonable ; - session déverrouillée de durée bornée si un chiffrement persistant est introduit. ### État verrouillé/déverrouillé Si le stockage chiffré est retenu, définir explicitement : - état verrouillé ; - opération de déverrouillage ; - durée ou portée de la session ; - invalidation/lock ; - changement de secret ; - comportement après erreur ; - absence de secret dans les erreurs et logs. Ne pas faire du booléen `is_unlocked` une preuve suffisante si la capacité de signature peut être désynchronisée. ## Chiffrement persistant Ne choisir l’algorithme, le KDF, le nonce et le format de conteneur qu’après inventaire des dépendances déjà présentes et vérification des exigences de sécurité. Le workspace possède déjà notamment `argon2`, `chacha20poly1305` et `zeroize` dans ses dépendances. Cela ne signifie pas qu’ils doivent être utilisés aveuglément ni avec des paramètres arbitraires. Le format persistant, s’il change, doit être : - versionné ; - auto-identifiable ; - strictement validé ; - extensible sans ambiguïté ; - écrit atomiquement ; - compatible avec une stratégie de migration/rollback ; - documenté avant d’être considéré stable. Ne pas stocker le secret de chiffrement dans `wallet.config.json` ni dans un fichier versionné. ## Import, export, backup et restore Ces capacités ne sont pas automatiquement obligatoires dans la première tranche de code. Leur besoin et leur surface doivent être décidés dans le plan. Si elles sont retenues : - distinguer import legacy, import du nouveau conteneur et export public ; - éviter toute exportation privée implicite ; - définir les permissions de fichiers et écriture atomique ; - refuser l’écrasement silencieux ; - définir les collisions d’alias et de pubkey ; - tester rollback et corruption ; - ne jamais écrire de keypair secret dans les logs ou diagnostics. ## Multi-wallets et profils `wallet.config.json` possède déjà une racine globale et des profils. `0.5.2` doit décider proprement : - si un profil sélectionne un alias unique ou un ensemble de wallets ; - comment un futur worker choisit son wallet sans dépendre de `kb-app-demo-desktop` ; - comment un exécuteur demande un signer sans connaître le stockage ; - comment plusieurs wallets sont listés et sélectionnés sans exposer leur matériau secret ; - comment les wallets temporaires et persistants coexistent. Ne pas transformer `ks-config` en gestionnaire de secrets. `ks-config` peut sélectionner des identités/aliases publics ou internes, mais le matériau secret appartient à `ks-wallet` et/ou à la source de secret dédiée retenue. ## Tauri et surfaces publiques `ks-wallet` ne doit pas reprendre TS-RS simplement parce que le desktop souhaite afficher une liste de wallets. Si le desktop a besoin d’une surface UI : ```text ks-wallet runtime -> wrapper/DTO kb-app-demo-desktop -> TS-RS -> frontend ``` Les DTO applicatifs peuvent exposer uniquement les informations explicitement sûres, par exemple alias, pubkey et état logique. Prévoir des canaris de non-divulgation semblables à ceux de `0.5.1`. ## Erreurs, logs et diagnostics Toute nouvelle erreur liée au wallet doit être conçue pour être utile sans révéler : - octets de secret ; - phrase/password ; - contenu chiffré ; - chemin local complet si ce chemin n’est pas explicitement un diagnostic interne ; - valeur d’une variable `KS_SECRET_*` ; - représentation `Debug` d’un keypair/signer. Les logs peuvent identifier une opération et un alias/public key lorsque cette donnée est autorisée, mais ne doivent pas concaténer les structures runtime sensibles. ## Tests minimums à prévoir Le plan `pre.001` doit définir précisément les tranches, mais `0.5.2` devra couvrir au minimum : - caractérisation du format legacy ; - import legacy préservant la pubkey ; - corruption/troncature/version inconnue ; - permissions privées ; - écriture atomique et refus d’écrasement ; - collisions d’alias/pubkey ; - persistance et réouverture ; - état verrouillé/déverrouillé si applicable ; - signature correcte sans exposition des bytes ; - absence de secret dans `Debug`, `Display`, erreurs, logs et DTO ; - concurrence/thread-safety des signers réellement utilisés ; - API externe crate-root de `ks-wallet` ; - intégration avec `ks-config` sans dépendance inverse vers une application. Les tests avec fichiers doivent utiliser des répertoires temporaires et des clés synthétiques. Aucun secret réel ne doit être requis. ## Découpage indicatif à confirmer par `pre.001` Le numéro exact peut évoluer après inventaire, mais l’ordre conceptuel attendu est : 1. `pre.001` — plan, caractérisation legacy, threat model et inventaire des consommateurs ; 2. tranche de contrats publics/identité/signature avant modification du stockage ; 3. tranche de conteneur persistant versionné et migration legacy ; 4. tranche chiffrement/verrouillage si retenue après validation du format ; 5. tranche multi-wallet/import-export/backup uniquement si confirmée par le plan ; 6. intégration `ks-config` / consommateurs / desktop via DTO sûrs ; 7. dernière prerelease — documentation, audits, TODO, archivage du plan/prompt et préparation de `0.5.3`. Un correctif `fix-XXX` conserve le numéro de prerelease et sa numérotation recommence à `fix-001` pour chaque prerelease. ## Hors périmètre de `0.5.2` - migration SQL `kb_sol_*` -> `k_sol_*` ; - refonte temporelle/provenance de `ks-store` ; - centralisation générale des scénarios `0.5.4` ; - ajout de protocoles Anchor/DEX ; - stockage d’un secret wallet dans PostgreSQL sans décision architecturale dédiée ; - hardware wallets, remote signers, KMS/HSM ou Ledger tant qu’ils ne sont pas explicitement priorisés ; - mécanisme universel de secret manager pour toutes les crates. ## Validation de référence Après chaque delta Rust ou contractuel : ```bash cargo fmt --all cargo check --workspace cargo clippy --all-targets python3 scripts/audit_rust_workspace_rules.py cargo test --workspace ``` Lorsque le desktop est modifié : ```bash cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json ``` Les scripts npm de build/dev ne sont jamais lancés directement. ## Dernière prerelease de `0.5.2` La dernière prerelease doit : - réconcilier tous les contrats wallet et consommateurs ; - finaliser README/USAGE/TODO/changelogs/guides ; - supprimer les TODO réellement fermés et reporter les autres vers une version identifiée ; - exécuter les validations finales ; - reprendre les décisions durables dans le ROADMAP et les documents normatifs ; - archiver le plan `0.5.2` et ce prompt sous `olddocs/archivekbot3/` ; - préparer le prompt de `0.5.3` pour l’audit/normalisation de `ks-store`.