v0.5.2-pre.007
This commit is contained in:
@@ -0,0 +1,291 @@
|
||||
<!-- file: prompts/031_v0_5_2_ks_wallet_restructuring.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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é :
|
||||
|
||||
```bash
|
||||
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`.
|
||||
Reference in New Issue
Block a user