khadhroony-bot3/prompts/031_v0_5_2_ks_wallet_restructuring.md

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 <alias>.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<dyn Signer> 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 <alias>.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 :

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 :

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

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.