# Prompt de démarrage `0.2.7` — conteneur binaire `.kspwallet` ## 1. Contexte de reprise La base attendue est la release stable : ```text v0.2.6 ``` `0.2.5` a stabilisé `ksp-wallet-lib` et le format logique/cryptographique `.kspwallet` V1 : capacités VIEW/OWNER indépendantes, Argon2id, XChaCha20-Poly1305, autorité OWNER Ed25519, persistence atomique/no-clobber, rotations, révocation VIEW forte, signature et transferts Solana CLI JSON/Base58. `0.2.6` a validé cette surface au travers de `ksp-app-wallet-desk` sans déplacer la propriété du format ou des secrets hors de Wallet. La release à ouvrir est : ```text 0.2.7 — conteneur binaire de persistence .kspwallet ``` La première tranche est `0.2.7-pre.001` et commence obligatoirement par **audit + threat-model + options de framing/codec + compatibilité/migration + sizing**, avant toute modification du wire de persistence. ## 2. Motivation Le document `.kspwallet` V1 actuellement persisté est un JSON strict. Ses valeurs sensibles restent cryptographiquement protégées, mais le fichier peut être ouvert et lu comme texte par un éditeur ordinaire. L'objectif de `0.2.7` est de rendre la **persistence physique** binaire et explicitement framed, sans prétendre que cette transformation ajoute une protection cryptographique supplémentaire. ### Non-solution explicite : Base64 seul Base64 seul n'est pas une solution acceptable : - il reste textuel/ASCII ; - il est trivialement réversible ; - il ne fournit aucune confidentialité ni intégrité supplémentaire ; - il augmente typiquement la taille d'environ un tiers. Le changement recherché est un vrai **conteneur binaire de persistence**, pas une obfuscation textuelle. ## 3. Séparation normative : conteneur vs format logique Ne pas consommer artificiellement `format_version = 2` uniquement parce que la persistence devient binaire. Distinguer explicitement : ```text container/framing version != wallet logical/cryptographic format_version ``` Le payload logique V1 doit pouvoir conserver ses invariants actuels : ```text VIEW / OWNER KDF / salts / slots AEAD / nonces / AAD OWNER signature/transcript metadata/secret compartments Solana keypair identity rotation / strong VIEW administration ``` Un futur `format_version >= 2` reste disponible pour de vraies évolutions d'autorisation/crypto, notamment second facteur. ## 4. Audit obligatoire `pre.001` Comparer au minimum : 1. framing binaire custom KSP avec grammar explicite ; 2. codecs binaires Serde adaptés et stables ; 3. formats self-describing éventuels ; 4. éventuelle compression du payload si elle apporte une vraie valeur ; 5. impact interop externe Rust/Python/Go/C ; 6. complexité de parsing borné et rejet des inputs adversariaux ; 7. dépendances nouvelles et leur maturité/maintenance ; 8. capacité à préserver les test vectors cryptographiques V1 ; 9. migration et détection sûre du JSON V1 legacy ; 10. règles d'unknown container version / taille / trailing bytes / canonicalité. Ne choisir aucun codec uniquement parce qu'il est pratique dans Rust : le format doit rester spécifiable indépendamment de l'implémentation. ## 5. Compatibilité obligatoire `ksp-wallet-lib` doit rester capable de lire les `.kspwallet` JSON V1 déjà créés. Le candidat doit définir explicitement : ```text legacy JSON V1 read new binary container read new binary container write default migration explicite legacy -> binary no-clobber / atomic replace rollback/interruption behavior ``` Une simple ouverture d'un legacy wallet ne doit pas le réécrire silencieusement sans contrat explicite. ## 6. Sécurité Le conteneur binaire n'est **pas** présenté comme une nouvelle couche de chiffrement. Le threat model V1 reste notamment : - attaquant possédant le fichier ; - connaissance complète de la spec ; - essais offline illimités sur les passwords ; - connaissance éventuelle d'un seul credential VIEW ou OWNER ; - capacité à modifier/remplacer/rollback le fichier. Les gains de `0.2.7` sont : ```text framing déterministe non-textual persistence parsing/versioning physique explicite meilleure séparation container/payload préparation des futures migrations ``` Pas : ```text obscurity = security Base64 = encryption binaire = protection contre attaque offline ``` ## 7. Frontière `ksp-wallet-lib` Le changement doit rester possédé par `ksp-wallet-lib`. `ksp-app-wallet-desk` ne doit pas connaître : - le codec du conteneur ; - sa magic/version physique ; - son layout ; - ses offsets ; - la distinction legacy/new lors des opérations ordinaires. Les APIs de haut niveau Wallet doivent absorber cette évolution autant que possible. ## 8. Wallet Desk comme canari consommateur Aucune modification fonctionnelle de `ksp-app-wallet-desk` n'est attendue uniquement pour ce changement de persistence. Après modification de Wallet, rejouer au minimum : ```bash cargo test -p ksp-wallet-lib cargo test -p ksp-app-wallet-desk cargo test --workspace ``` Puis un parcours fonctionnel Wallet Desk doit prouver au minimum : ```text inventory create locked inspect VIEW unlock OWNER unlock metadata rotation strong VIEW disable/recreate export/import balance HTTP ``` Si le Desk doit être modifié pour comprendre le conteneur physique, considérer cela comme un signal d'abstraction insuffisante et réauditer la frontière Wallet avant d'accepter le changement. ## 9. Interop et test vectors Mettre à jour la spec `.kspwallet` avec une grammar byte-level du conteneur : - magic ; - version du conteneur ; - longueur(s) ; - codec/payload kind ; - endianess ; - bornes ; - trailing bytes ; - canonicalité ; - unknown-version policy. Conserver les test vectors cryptographiques V1 lorsque les transcripts/AAD ne changent pas, et ajouter des fixtures déterministes container + payload. Prévoir au moins un parseur externe de canari afin d'éviter un format binaire « Rust-only » accidentel. ## 10. Futur `format_version >= 2` / second facteur Ce chantier **ne réalise pas** password + OTP/2FA. Pour une future version logique : - `ksp-wallet-lib` possède le format, les facteurs, challenges et vérifications ; - un client interactif tel que Wallet Desk devra évoluer lorsqu'un OTP, enrollment/recovery, hardware/WebAuthn ou consentement externe doit être saisi/présenté ; - un seed TOTP enfermé uniquement dans le même fichier ne doit pas être assimilé automatiquement à un second facteur indépendant contre un attaquant qui possède ce fichier. Le conteneur `0.2.7` doit simplement laisser cette évolution possible sans la pré-concevoir excessivement. ## 11. Dépendances Toute nouvelle dépendance externe commune est déclarée dans `[workspace.dependencies]` puis consommée avec `.workspace = true`. Avant ajout : - vérifier la version actuelle ; - auditer maintenance/licence/graphe ; - éviter les générations obsolètes inutiles ; - vérifier qu'une petite grammar custom n'est pas plus durable qu'un codec lourd, ou inversement. ## 12. Discipline Rust / tests Conserver toutes les règles KSP actuelles : Rust 2024, async-first, pas de `unsafe`, `unwrap`, `expect`, `panic` runtime, audits structurels, dépendance Logging via `ksp-logging-lib`, Config hors Wallet. Validation générale : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-wallet-lib cargo test -p ksp-app-wallet-desk cargo test --workspace ``` ## 13. Forecast souple à recalibrer en `pre.001` Point de départ recommandé : ```text pre.001 audit framing/codec/threat-model/interop/sizing pre.002 spec container + parser bounded + fixtures pre.003 writer binary + persistence integration pre.004 legacy JSON read + migration explicite pre.005 adversarial/interop/test vectors pre.006 Wallet Desk regression + live functional smoke pre.007 compliance/docs/prompt suivant rel.001 ``` Ce découpage est indicatif ; le gate `pre.001` doit le recalibrer selon le choix de format réel. ## 14. Résultat attendu À la clôture stable : ```text les nouveaux .kspwallet sont persistés dans un conteneur binaire spécifié les anciens JSON V1 restent lisibles aucune sécurité fictive n'est attribuée au binaire/Base64 les semantics cryptographiques V1 restent intactes sauf défaut démontré les migrations sont explicites et testées Wallet Desk fonctionne sans connaissance du format physique interop externe et parsing adversarial sont prouvés ``` ## 15. Instruction d'ouverture Commencer par relire la spec `.kspwallet` V1, les modules `wire`, `transcript`, `persistence`, `wallet`, `owner`, `transfer` et tous les test vectors actuels. Ensuite produire l'audit `0.2.7-pre.001` avant de coder le nouveau conteneur.