khadhroony-solana-project/prompts/012-V0_2_7_START_PROMPT.md

Prompt de démarrage 0.2.7 — conteneur binaire .kspwallet

1. Contexte de reprise

La base attendue est la release stable :

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 :

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 :

container/framing version
    !=
wallet logical/cryptographic format_version

Le payload logique V1 doit pouvoir conserver ses invariants actuels :

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 :

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 :

framing déterministe
non-textual persistence
parsing/versioning physique explicite
meilleure séparation container/payload
préparation des futures migrations

Pas :

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 :

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 :

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 :

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

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 :

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.