# Prompt de démarrage `0.2.5` — Wallet foundation ## 1. Contexte de reprise La base attendue est la release stable : ```text v0.2.4 ``` `0.2.1` à `0.2.4` ont stabilisé la foundation HTTP Solana puis complété toute la surface HTTP courante auditée : ```text 52/52 méthodes HTTP courantes avec wrapper typed 14/14 méthodes historiques Deprecated / runtime Removed conservées KSP-TRANSPORT-007 appliqué à la surface complète ``` La prochaine release est : ```text 0.2.5 — Wallet foundation ``` Sa mission n'est pas d'ajouter une UI ni de commencer l'exécution métier. Elle introduit le **cœur Wallet autonome** dont les applications et l'exécution future pourront dépendre. La première tranche est : ```text 0.2.5-pre.001 ``` et commence obligatoirement par **audit actuel + reprise de l'héritage utile + brainstorming + sizing** avant toute implémentation cryptographique ou format lourd. ## 2. Mission de `0.2.5` Créer : ```text crates/ksp-wallet-lib ``` et stabiliser le format natif : ```text .kspwallet ``` Le Wallet doit fournir au minimum les capacités conceptuelles suivantes : ```text création ouverture / déverrouillage identité publique / Pubkey protection du secret signature changement de mot de passe sans changement de keypair persistence atomique / no-clobber projection publique sûre import/export extensible ``` La release doit aboutir à une bibliothèque utilisable **sans Config, sans Transport, sans Tauri et sans execution policy**. ## 3. Frontières architecturales déjà décidées La direction attendue reste : ```text ksp-wallet-lib -> ksp-core-lib -> ksp-logging-lib -> primitives crypto/key/signature low-level explicitement retenues ``` Interdictions : ```text ksp-wallet-lib -X-> ksp-config-lib ksp-wallet-lib -X-> ksp-onchain-transport-lib ksp-wallet-lib -X-> ksp-execution-policy-api ksp-wallet-lib -X-> Store ksp-wallet-lib -X-> Tauri ``` Le Wallet **stocke, ouvre et signe**. Il ne décide pas si une transaction ou une dépense est autorisée. Les règles de dépense, programme, réseau, simulation, plafonds ou approbation appartiennent à la future frontière : ```text ksp-execution-policy-api ``` et non à `ksp-wallet-lib`. ## 4. Décisions Wallet déjà acquises Les décisions suivantes ne doivent pas être rouvertes sans raison nouvelle et documentée : 1. le format natif KSP se nomme `.kspwallet` ; 2. KSP ne crée pas de `ksp-wallet-api` séparée dans l'architecture actuelle ; 3. `WalletPolicy` est explicitement exclu du Wallet ; 4. le wallet JSON temporaire historique bot2/bot3 n'est pas migré ; 5. l'ancien nom `.kswallet` n'est pas le nom final KSP ; 6. les secrets wallet ne doivent jamais être déplacés dans Config par commodité ; 7. Wallet n'a pas besoin de Transport pour son cœur ; 8. l'import/export doit rester extensible, mais seules les conversions réellement nécessaires doivent être implémentées ; 9. les futurs scénarios doivent pouvoir utiliser de vrais `.kspwallet`, y compris des wallets dédiés Devnet/tests ; 10. Wallet Desk arrive séparément en `0.2.6`. Références KSP à relire avant le plan : ```text docs/rules/RULES_KSP.md docs/rules/RULES_DEPENDENCIES.md docs/architecture/002-LAYERS_AND_DEPENDENCIES.md docs/architecture/003-COMPONENT_CONTRACTS.md docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/007-EXECUTION_AND_POLICY.md docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md docs/plans/007-V0_2_0_SERIES_PLANNING.md docs/validation/002-V0_2_0_SERIES_PLANNING.md docs/IDEAS.md ``` ## 5. `pre.001` — audit officiel actuel + brainstorming + sizing `pre.001` ne doit pas démarrer directement par le chiffrement du fichier. Il doit d'abord produire un plan Wallet dédié et répondre explicitement aux questions suivantes. ### 5.1 Héritage bot3/bot2 Réauditer les implémentations historiques réellement disponibles de Wallet afin de classer chaque idée en : ```text réutiliser conceptuellement refondre abandonner reporter ``` Examiner notamment, lorsqu'ils existent dans les sources historiques : - création de keypair ; - lecture/écriture du format wallet ; - modèle de mot de passe ; - secret/public separation ; - changement de mot de passe ; - signature ; - import/export ; - aliases/metadata ; - atomicité/no-clobber ; - redaction ; - temporary wallet JSON ; - ancien `.kswallet` ; - `WalletPolicy`. Ne pas copier automatiquement une dépendance, un format ou une primitive cryptographique uniquement parce qu'elle existait dans bot3. ### 5.2 Primitives Solana actuelles Réaduiter les crates low-level Solana réellement nécessaires pour : ```text Pubkey keypair / secret material Signer Signature ``` Objectifs : - garder les dépendances au niveau le plus bas possible ; - ne pas tirer un client RPC Solana ; - ne pas recréer localement une primitive cryptographique standard bien maintenue ; - conserver toutes les dépendances tierces communes dans `[workspace.dependencies]`. L'audit doit vérifier les versions réellement actuelles au moment de la session, pas recopier les versions historiques bot3. ### 5.3 Protection cryptographique du fichier Comparer les primitives cryptographiques maintenues et adaptées au besoin réel du `.kspwallet`. Le plan doit décider explicitement, avec justification : ```text KDF mot de passe AEAD / chiffrement authentifié CSPRNG gestion salt / nonce paramètres KDF sérialisés versionnement du format stratégie de migration zeroization / secret memory handling ``` Ne pas inventer de cryptographie KSP. Ne pas figer dans ce prompt un choix tel qu'Argon2id, scrypt, AES-GCM ou XChaCha20-Poly1305 sans réaudit actuel ; `pre.001` doit sélectionner les primitives selon sécurité, maintenance, portabilité, dépendances et compatibilité Rust réellement observées. ### 5.4 Modèle de fichier `.kspwallet` Le plan doit définir les invariants du format avant l'API de persistence. Le format doit pouvoir identifier sans ambiguïté au minimum : ```text format/version KSP algorithmes/paramètres nécessaires au déchiffrement salt/nonce ou équivalents payload protégé metadata publique strictement autorisée intégrité/authenticité ``` Questions à trancher : - JSON, binaire ou enveloppe hybride ; - magic/version ; - représentation de la Pubkey ; - metadata publique lisible wallet verrouillé ou non ; - place de l'alias ; - champs obligatoires/optionnels ; - limites de taille ; - politique unknown-version ; - politique unknown-field ; - migrations futures ; - checksum séparé utile ou redondant avec AEAD ; - compatibilité endianness/encodage si format binaire. Le format doit être documentable et testable sans exposer le secret. ### 5.5 Secret en mémoire Définir explicitement l'ownership du secret déverrouillé. Au minimum : - pas de `Debug`/`Display` révélant le secret ; - pas de valeur secrète dans les erreurs/logs/contextes KSP ; - éviter `Copy` et les clones implicites de secret ; - zeroization des buffers possédés lorsque raisonnablement possible ; - durée de vie du secret déverrouillé explicitement contrôlée ; - distinction nette public metadata / encrypted payload / unlocked secret ; - aucune conservation du mot de passe en clair au-delà du besoin cryptographique. Le plan doit être honnête sur les limites réelles de zeroization dans Rust et des allocations/transcodages choisis ; ne pas promettre une garantie que la stack ne peut pas fournir. ### 5.6 Persistence Définir la stratégie : ```text create open/read atomic replace no-clobber create change password permissions filesystem recovery after interrupted write ``` Le changement de mot de passe doit : - conserver la même identité/keypair ; - produire un nouveau matériau de protection approprié ; - ne pas dégrader l'atomicité ; - ne jamais laisser un fichier partiellement remplacé comme nouveau wallet valide. Le plan doit distinguer comportement portable et durcissement spécifique Unix si nécessaire. ### 5.7 Import/export extensible Établir une architecture ouverte qui permette d'ajouter des formats sans enum central fermé imposant de modifier le cœur à chaque intégration. Auditer les formats réellement utiles maintenant parmi les pistes historiques, par exemple : ```text Solana CLI keypair JSON Backpack Phantom Solflare Trust Wallet autres formats réellement disponibles dans les sources/audits ``` Cette liste est une **liste d'audit**, pas un engagement d'implémentation complet. `pre.001` sélectionne le minimum de formats nécessaire pour prouver l'extensibilité et le round-trip utile de la release. Ne pas ajouter des dépendances « au cas où ». ### 5.8 Sizing Évaluer séparément : ```text crate/API foundation format wire crypto/KDF/AEAD persistence signing change-password import/export security tests docs/USAGE ``` Si le scope ne paraît plus clôturable proprement dans la session, découper **avant** l'implémentation lourde plutôt que réduire silencieusement les garanties de sécurité. ## 6. API publique à concevoir Les noms exacts sont décidés pendant le plan, mais les responsabilités doivent rester distinctes. Il doit exister des contrats clairs pour : ```text wallet public identity/info wallet locked/encrypted representation wallet unlocked/signing capability create/open/save/change-password import/export/inspect ``` Ne pas exposer directement un champ `secret: Vec` comme API publique de commodité. Une API explicitement dangereuse d'export du secret ne doit exister que si un format d'export retenu l'exige réellement et avec une sémantique qui évite l'exposition accidentelle. La capacité de signature doit permettre aux couches supérieures d'obtenir une signature sans devoir extraire le secret brut. ## 7. Erreurs Utiliser le type d'erreur commun KSP. Prévoir des catégories suffisamment précises pour distinguer au minimum : ```text format invalide version non supportée paramètres crypto invalides authentification/déchiffrement échoué password invalide ou secret non déverrouillable I/O no-clobber / destination existante persistence atomique import/export non supporté key material invalide signature ``` Les messages et contextes ne doivent pas contenir : ```text password secret bytes seed phrase private key payload chiffré complet KDF input ``` Éviter également de créer un oracle inutile en distinguant trop finement les causes d'échec d'authentification lorsque cela affaiblirait la sécurité. ## 8. Logging `ksp-wallet-lib` utilise exclusivement la façade `ksp-logging-lib`. Les événements utiles peuvent inclure : ```text opération create/open/import/export/change-password/sign format/version non secrète succès/échec catégorisé durée destination/path seulement selon politique sûre retenue ``` Ne jamais logger : ```text mot de passe secret seed private key signature payload arbitraire contenu complet du wallet ciphertext complet nonce/salt si le log n'en a aucun besoin opérationnel ``` Même `trace` ne constitue pas une exception. ## 9. Tests de sécurité et de contrat Les tests déterministes doivent couvrir au minimum les domaines suivants. ### Format - round-trip du format natif ; - magic/version corrects ; - unknown version rejetée ; - fichier tronqué/reformaté rejeté ; - champs/tailles invalides rejetés ; - corruption/tampering détectée ; - absence du secret en clair dans le fichier. ### Mot de passe / crypto - bon mot de passe ouvre le wallet ; - mauvais mot de passe échoue sans fuite ; - changement de mot de passe conserve la Pubkey/keypair ; - ancien mot de passe ne déverrouille plus le nouveau fichier ; - nouveau mot de passe fonctionne ; - salt/nonce/paramètres ne sont pas accidentellement réutilisés lorsque le design impose leur renouvellement. ### Secret / diagnostics - `Debug`/snapshots/projections publiques ne contiennent pas le secret ; - erreurs n'échoent pas password/secret ; - logs de test ne contiennent pas de secret ; - types secrets n'acquièrent pas `Copy` par accident ; - zeroization testable lorsqu'elle est réellement observable sans faux sentiment de sécurité. ### Persistence - create ; - destination existante/no-clobber ; - write atomique ; - remplacement lors du changement de mot de passe ; - échec intermédiaire ne détruisant pas le wallet précédent, dans la mesure testable par la couche ; - permissions/durcissement filesystem retenus. ### Signature - Pubkey dérivée correcte ; - signature produite et vérifiable ; - changement de mot de passe ne change pas la signature déterministe d'un même message si la primitive de signature est déterministe ; - le consumer peut signer sans extraction publique du secret brut. ### Import/export - format(s) retenu(s) ; - validation stricte ; - round-trip lorsque le format le permet ; - inspect sans import si cette capability est retenue ; - architecture extensible démontrée sans dépendance au format natif dans les adapters externes. ### Public API / architecture - canary publique depuis crate root ; - aucune dépendance Wallet -> Config/Transport/ExecutionPolicy ; - aucune dépendance crypto dupliquée injustifiée ; - aucun accès environnement direct ; - aucun `unsafe` ajouté. ## 10. Tests et fixtures contenant des secrets Les secrets de tests doivent être **explicitement des fixtures non réelles**. Ne jamais utiliser : - un wallet personnel ; - une seed Mainnet ; - une clé provenant d'un `.env` opérateur ; - un fichier `.kspwallet` réel. Si une fixture déterministe est nécessaire, son caractère test-only doit être évident et elle ne doit jamais être utilisable comme secret de production recommandé. ## 11. Dépendances Toutes les dépendances tierces communes sont déclarées au `Cargo.toml` racine sous `[workspace.dependencies]`. Les membres consomment : ```toml .workspace = true ``` Éviter : - crypto maison ; - deux crates concurrentes pour la même primitive sans justification ; - stack async ou sérialisation supplémentaire sans besoin ; - client Solana RPC ; - dépendance Tauri ; - Config ; - Store. Toute nouvelle dépendance liée au secret doit être auditée au minimum sur : ```text maintenance actuelle version Rust/MSRV pertinente features par défaut unsafe/transitifs importants zeroize support format/compatibilité duplications cargo tree ``` ## 12. Async / sync Les opérations I/O doivent respecter la règle async-first du projet. Le plan doit néanmoins distinguer : - calcul CPU KDF potentiellement coûteux ; - opérations filesystem ; - signature CPU locale. Ne pas bloquer naïvement un runtime async avec une dérivation de clé coûteuse. Décider explicitement si l'API de bas niveau est sync avec wrapper async, utilise `spawn_blocking`, ou adopte une autre frontière cohérente. Ce choix doit rester compatible avec l'usage futur Tauri sans introduire Tauri dans Wallet. ## 13. Publication sûre / identité publique Wallet doit pouvoir fournir une représentation sûre destinée aux consommateurs qui n'ont besoin que de l'identité publique. Cette représentation peut contenir les metadata explicitement retenues telles que : ```text Pubkey alias format/version état locked/unlocked si pertinent ``` mais jamais le secret ou des dérivés inutiles de secret. La terminologie « publication » signifie ici **exposition sûre de l'identité publique**, pas envoi réseau ni publication blockchain. ## 14. Hors périmètre `0.2.5` Sont exclus sauf décision de rescoping explicite pendant le gate `pre.001` : ```text ksp-app-wallet-desk lecture réseau du solde HTTP/WebSocket/gRPC WalletPolicy execution policy construction/simulation/envoi de transaction Store seed phrase UI hardware wallet / Ledger remote signer browser extension mobile app cloud key management custody service trading ``` Les pistes d'import/export peuvent être étudiées sans rendre leurs applications/providers propriétaires du cœur Wallet. ## 15. Relation avec `0.2.6 — Wallet Desk` `0.2.6` doit pouvoir composer : ```text Config + ksp-wallet-lib + ksp-onchain-transport-lib + ksp-logging-lib -> ksp-app-wallet-desk ``` Le premier flux réseau attendu est notamment : ```text ouvrir/sélectionner un .kspwallet -> obtenir sa Pubkey publique -> getBalance via Transport HTTP -> afficher identité + solde ``` Aucune logique réseau nécessaire à ce flux ne doit remonter dans `ksp-wallet-lib`. ## 16. Prévision souple des prereleases Prévision initiale à réévaluer par `pre.001` : ```text pre.001 audit bot3 + dépendances/crypto actuelles + brainstorming + format/API + sizing pre.002 crate foundation + contrats public/secret + erreurs + canaries architecture pre.003 enveloppe .kspwallet + versionnement + KDF/AEAD + fixtures déterministes pre.004 create/open + persistence atomique/no-clobber + durcissement filesystem retenu pre.005 signature + projection publique + changement de mot de passe pre.006 architecture import/export + premier(s) format(s) réellement retenu(s) pre.007 security/compliance audit + README/USAGE + graphes + tests complémentaires pre.008 clôture candidate + documentation finale + prompt 0.2.6 — Wallet Desk rel.001 publication strictement publicationnelle ``` Cette prévision est **souple**. Si un fil cryptographique ou de persistence exige une correction, ajouter une prerelease/fix plutôt que compresser les validations. Si `pre.001` conclut qu'un format/import particulier doit être reporté, le report doit être explicite et ne doit pas affaiblir les garanties du format natif. ## 17. Validation continue Après chaque changement Rust : ```bash cargo fmt --all cargo check --workspace cargo clippy --workspace --all-targets ``` Pendant le développement : ```bash cargo test -p ksp-wallet-lib ``` Aux checkpoints justifiés et à la clôture : ```bash cargo test --workspace ``` Réaduiter les graphes Cargo de Wallet et de ses consumers lorsqu'ils apparaissent. ## 18. Discipline des deltas Les deltas historiques sont immuables. Utiliser : ```text deltas/0.2.5/pre.001.md deltas/0.2.5/pre.002.md ... deltas/0.2.5/pre.NNN-fix.NNN.md deltas/0.2.5/rel.001.md ``` La dernière prerelease doit préparer une candidate complètement validable. `rel.001` doit rester strictement publicationnelle : ```text version stable ROADMAP CHANGELOG stable statut final du plan/validation commit rel tag stable ``` Aucune nouvelle capacité Wallet fonctionnelle ne doit être ajoutée à `rel.001`. ## 19. Livrables de `pre.001` Avant toute implémentation lourde, produire au minimum : 1. le plan détaillé `0.2.5` ; 2. l'audit des règles/frontières KSP ; 3. l'audit des implémentations historiques Wallet utiles ; 4. l'audit des primitives Solana/key/signature actuelles ; 5. l'audit comparatif des primitives KDF/AEAD/RNG ; 6. la proposition de format `.kspwallet` ; 7. le modèle de secret en mémoire ; 8. la stratégie de persistence/atomicité ; 9. la stratégie import/export ; 10. la matrice de risques sécurité ; 11. les dépendances pressenties et leur justification ; 12. les tests/canaries nécessaires ; 13. le sizing et la prévision de prereleases ; 14. les questions ouvertes réellement bloquantes. Le gate `pre.001` doit conclure explicitement : ```text GO ``` ou : ```text SPLIT / RESCOPE ``` avec justification. ## 20. Critère de sortie de `0.2.5` `0.2.5` ne peut être publié stable que si : - `ksp-wallet-lib` est autonome et documenté ; - `.kspwallet` est versionné et documenté ; - le secret n'est jamais stocké en clair dans le format natif ; - le secret/password ne fuit pas dans Debug/Display/logs/errors ; - create/open/sign/change-password sont validés ; - l'identité publique reste accessible par un contrat sûr ; - la persistence retenue est atomique/no-clobber selon son contrat ; - les corruptions/tampering sont détectées ; - import/export extensible est démontré avec le minimum de formats retenu ; - `WalletPolicy` est absent ; - Wallet ne dépend pas de Config/Transport/ExecutionPolicy ; - les graphes Cargo sont réaudités ; - les tests déterministes et le workspace passent ; - README/USAGE/validation sont synchronisés ; - le prompt `0.2.6 — Wallet Desk` est finalisé ; - `rel.001` reste publicationnelle. ## 21. Première action de la session Commencer par : ```text audit actuel -> brainstorming -> matrice des décisions -> sizing -> plan pre.001 ``` Ne pas commencer par coder le chiffrement du fichier.