khadhroony-solana-project/prompts/010-V0_2_5_START_PROMPT.md

<!-- file: prompts/010-V0_2_5_START_PROMPT.md -->
<!-- version: 1 -->

# 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<u8>` 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
<dependency>.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.