269 lines
8.7 KiB
Markdown
269 lines
8.7 KiB
Markdown
<!-- file: prompts/012-V0_2_7_START_PROMPT.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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.
|