v0.2.6-pre.015
This commit is contained in:
@@ -1,268 +1,82 @@
|
||||
<!-- file: prompts/012-V0_2_7_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Prompt de démarrage `0.2.7` — conteneur binaire `.kspwallet`
|
||||
# Prompt de démarrage `0.2.7` — WebSocket Solana standard
|
||||
|
||||
## 1. Contexte de reprise
|
||||
|
||||
La base attendue est la release stable :
|
||||
Base attendue : tag stable `v0.2.6`.
|
||||
|
||||
```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.
|
||||
`0.2.6` a validé Wallet Desk puis intégré le wire binaire `.kspwallet` V2, les APIs Wallet génériques/versionnées, la compatibilité V1/V2 et les migrations explicites. `0.2.7` revient donc à la séquence Transport prévue avant l'intercalation temporaire du chantier binaire.
|
||||
|
||||
La release à ouvrir est :
|
||||
|
||||
```text
|
||||
0.2.7 — conteneur binaire de persistence .kspwallet
|
||||
0.2.7 — WebSocket Solana standard
|
||||
```
|
||||
|
||||
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.
|
||||
`0.2.7-pre.001` commence obligatoirement par audit officiel actuel + inventory exhaustif des subscriptions/unsubscriptions/notifications + threat-model/reconnexion + sizing avant implémentation lourde.
|
||||
|
||||
## 2. Motivation
|
||||
## 2. Mission
|
||||
|
||||
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.
|
||||
Étendre `ksp-onchain-transport-lib` à la surface WebSocket Solana standard retenue, sans déplacer Config dans Transport et sans introduire encore Helius LaserStream.
|
||||
|
||||
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 :
|
||||
Contrat de sessions :
|
||||
|
||||
```text
|
||||
container/framing version
|
||||
!=
|
||||
wallet logical/cryptographic format_version
|
||||
une même URL peut porter plusieurs sessions physiques
|
||||
une session peut porter plusieurs subscriptions
|
||||
pas de pool/scheduler automatique complexe sans besoin démontré
|
||||
reconnexion bornée et états de subscription explicites
|
||||
notifications typées sans fuite d'URL/secrets dans Debug/logs
|
||||
```
|
||||
|
||||
Le payload logique V1 doit pouvoir conserver ses invariants actuels :
|
||||
## 3. Frontières
|
||||
|
||||
Conserver :
|
||||
|
||||
```text
|
||||
VIEW / OWNER
|
||||
KDF / salts / slots
|
||||
AEAD / nonces / AAD
|
||||
OWNER signature/transcript
|
||||
metadata/secret compartments
|
||||
Solana keypair identity
|
||||
rotation / strong VIEW administration
|
||||
Transport -X-> Config
|
||||
Transport -X-> Wallet
|
||||
Transport -X-> Store
|
||||
Transport -X-> tracing direct
|
||||
Config -> Transport autorisé
|
||||
ksp-logging-lib seul propriétaire des émissions applicatives
|
||||
```
|
||||
|
||||
Un futur `format_version >= 2` reste disponible pour de vraies évolutions d'autorisation/crypto, notamment second facteur.
|
||||
## 4. Audit pre.001
|
||||
|
||||
## 4. Audit obligatoire `pre.001`
|
||||
Auditer au minimum :
|
||||
|
||||
Comparer au minimum :
|
||||
- documentation Solana/Agave actuelle ;
|
||||
- méthodes subscribe/unsubscribe courantes, deprecated/unstable et notifications associées ;
|
||||
- formes de paramètres/options et réponses ;
|
||||
- reconnexion, resubscribe, backpressure, cancellation et shutdown ;
|
||||
- plusieurs sessions pour une même URL ;
|
||||
- limites provider utiles sans les figer comme règles Solana universelles ;
|
||||
- dépendances WebSocket Rust actuelles et leur graphe ;
|
||||
- sizing « une release = une session ».
|
||||
|
||||
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 :
|
||||
## 5. Hors périmètre
|
||||
|
||||
```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
|
||||
Helius LaserStream WebSocket -> 0.2.8
|
||||
Yellowstone gRPC
|
||||
Store/materialization
|
||||
Wallet/2FA
|
||||
pool automatique sophistiqué de sessions WebSocket
|
||||
frontend réseau direct
|
||||
```
|
||||
|
||||
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 :
|
||||
## 6. Validation
|
||||
|
||||
```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 -p ksp-onchain-transport-lib
|
||||
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.
|
||||
Prévoir des fixtures déterministes et un smoke réseau opt-in seulement lorsqu'une composition réelle le justifie.
|
||||
|
||||
Reference in New Issue
Block a user