436 lines
12 KiB
Markdown
436 lines
12 KiB
Markdown
<!-- file: deltas/0.2.6/pre.015.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.6-pre.015` — wire binaire `.kspwallet` V2 et codec canonique
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.2.6-pre.014-fix.001 appliquée
|
|
workspace.package.version = 0.2.6-pre.14.fix.1
|
|
```
|
|
|
|
Le checkpoint opérateur de la base est intégralement vert :
|
|
|
|
```text
|
|
cargo fmt --all OK
|
|
python3 scripts/audit_rust_workspace_rules.py clean
|
|
cargo check --workspace OK
|
|
cargo clippy --workspace --all-targets OK
|
|
cargo test -p ksp-app-config-desk OK
|
|
cargo test -p ksp-app-wallet-desk OK
|
|
cargo test --workspace OK
|
|
Wallet Desk release_compliance 4/4 OK
|
|
smokes live toujours opt-in/ignored
|
|
Tauri Config Desk crate-local OK visuel
|
|
Tauri Wallet Desk crate-local OK visuel + import/balance Devnet manuel
|
|
```
|
|
|
|
Le correctif `pre.014-fix.001` est donc accepté comme base de `pre.015`.
|
|
|
|
## Type de livraison
|
|
|
|
Cette tranche est fournie sous forme de **delta uniquement**, à appliquer sur la base précédente :
|
|
|
|
```text
|
|
ksp-general-0.2.6-pre.015-delta.zip
|
|
```
|
|
|
|
Le signal technique devient :
|
|
|
|
```text
|
|
workspace.package.version = 0.2.6-pre.15
|
|
commit = v0.2.6-pre.015
|
|
```
|
|
|
|
Aucun tag prerelease.
|
|
|
|
Les `package.json` et `tauri.conf.json` des applications ne changent pas : `pre.015` ne modifie ni frontend, ni Tauri, ni contrat de build des Desks.
|
|
|
|
## Objectif de la tranche
|
|
|
|
`pre.015` fige le **format `.kspwallet` V2 binaire** et son codec structurel strict dans `ksp-wallet-lib`.
|
|
|
|
Cette tranche réalise :
|
|
|
|
```text
|
|
spécification normative V2
|
|
framing binaire KSP propriétaire
|
|
codec parse/serialize byte-exact
|
|
identifiants numériques stables
|
|
bornes structurelles avant crypto
|
|
transcripts/AAD V2 séparés de V1
|
|
fixture binaire canonique wire-only
|
|
tests déterministes du codec et des invariants
|
|
API publique du codec V2 depuis la racine de crate
|
|
documentation de la politique default != latest
|
|
réalignement du plan 0.2.6 et des releases 0.2.7+
|
|
```
|
|
|
|
Cette tranche **ne réalise pas encore** :
|
|
|
|
```text
|
|
create_wallet_file_v2
|
|
open_wallet_*_file_v2
|
|
façades génériques multi-version
|
|
basculement de Wallet Desk vers les façades génériques
|
|
migration V1 -> V2
|
|
réécriture automatique de wallets V1
|
|
second facteur / V3
|
|
build Tauri de production
|
|
```
|
|
|
|
Ces responsabilités restent réparties entre `pre.016`, `pre.017` et `pre.018`.
|
|
|
|
## Décision V1 / V2
|
|
|
|
V1 reste un format stable historique :
|
|
|
|
```text
|
|
format_version = 1
|
|
JSON UTF-8 strict
|
|
bytes -> Base64URL sans padding
|
|
APIs _v1 conservées
|
|
lecture durable obligatoire
|
|
```
|
|
|
|
V2 est un nouveau format explicite :
|
|
|
|
```text
|
|
format_version = 2
|
|
wire binaire KSP
|
|
aucune Base64
|
|
aucune compression
|
|
entiers multi-octets big-endian
|
|
ordre et cardinalité canoniques
|
|
aucun trailing byte
|
|
```
|
|
|
|
Le caractère binaire n'est pas présenté comme une mesure cryptographique. Les propriétés de confidentialité/authenticité restent possédées par Argon2id, XChaCha20-Poly1305, Ed25519 et les règles VIEW/OWNER.
|
|
|
|
## Wire V2
|
|
|
|
Le document commence par :
|
|
|
|
```text
|
|
magic 9 bytes = KSPWALLET
|
|
format_version u16 BE = 2
|
|
document_length u32 BE = taille totale exacte
|
|
flags u16 BE
|
|
owner_auth_public_key 32 bytes
|
|
view_slot_id 16 bytes si VIEW_ENABLED
|
|
```
|
|
|
|
Flags :
|
|
|
|
```text
|
|
bit 0 = VIEW_ENABLED
|
|
autres bits = réservés et obligatoirement zéro
|
|
```
|
|
|
|
Le body est strictement :
|
|
|
|
```text
|
|
OWNER key slot
|
|
VIEW key slot si VIEW_ENABLED
|
|
OWNER-CONTROL compartment
|
|
METADATA compartment
|
|
SECRET compartment
|
|
state signature
|
|
EOF immédiat
|
|
```
|
|
|
|
Les slots et compartiments transportent leurs IDs numériques de rôle/kind/algorithme, leurs longueurs explicites et leurs bytes directement.
|
|
|
|
Bornes et détails complets :
|
|
|
|
```text
|
|
docs/formats/KSPWALLET_V2.md
|
|
```
|
|
|
|
## Codec strict
|
|
|
|
Nouveau module :
|
|
|
|
```text
|
|
crates/ksp-wallet-lib/src/wire_v2.rs
|
|
```
|
|
|
|
Surface publique principale :
|
|
|
|
```rust
|
|
KspWalletEnvelopeV2::parse_binary(...)
|
|
KspWalletEnvelopeV2::to_binary_bytes(...)
|
|
```
|
|
|
|
Le parser rejette avant toute opération cryptographique :
|
|
|
|
```text
|
|
> 1 MiB
|
|
magic/version incorrects
|
|
document_length incohérent
|
|
flags réservés
|
|
troncature / longueur hors input
|
|
role/kind/algorithme inconnu
|
|
ordre OWNER/VIEW ou compartiments non canonique
|
|
VIEW descriptor incohérent
|
|
Argon2 structurellement invalide
|
|
salt/ciphertext hors bornes
|
|
payload_version non supporté
|
|
trailing bytes
|
|
```
|
|
|
|
Le codec n'authentifie ni ne déchiffre encore un wallet V2 ; cette composition avec les primitives Wallet existantes est réservée à `pre.016`.
|
|
|
|
## Transcripts et AAD V2
|
|
|
|
Nouveau module :
|
|
|
|
```text
|
|
crates/ksp-wallet-lib/src/transcript_v2.rs
|
|
```
|
|
|
|
V2 possède des domain separators distincts :
|
|
|
|
```text
|
|
KSPWALLET-V2-STATE
|
|
KSPWALLET-V2-AAD-OWNER-SLOT
|
|
KSPWALLET-V2-AAD-VIEW-SLOT
|
|
KSPWALLET-V2-AAD-OWNER-CONTROL
|
|
KSPWALLET-V2-AAD-METADATA
|
|
KSPWALLET-V2-AAD-SECRET
|
|
```
|
|
|
|
La discipline TLV déterministe de V1 est conservée mais les rôles, algorithmes et kinds V2 sont transcriptés sous leurs IDs numériques. Les domains V1/V2 restent séparés pour éviter toute interchangeabilité cryptographique entre versions.
|
|
|
|
Le VIEW wrap mutable reste hors du state transcript, comme en V1 ; le descriptor signé lie son identité stable et permet la self-rotation VIEW sans OWNER.
|
|
|
|
## Fixture canonique
|
|
|
|
Nouvelle fixture structurelle :
|
|
|
|
```text
|
|
crates/ksp-wallet-lib/tests/fixtures/kspwallet_v2_wire_only.bin
|
|
```
|
|
|
|
Mesure :
|
|
|
|
```text
|
|
V1 JSON wire-only = 2037 octets
|
|
V2 binary wire-only = 628 octets
|
|
réduction = 1409 octets, environ 69,2 %
|
|
```
|
|
|
|
Hash du fixture V2 :
|
|
|
|
```text
|
|
sha256 = cbacb37326c76e6dde8d614601cd765a8c0fd9744f891d640b8a3cd71cf60a93
|
|
```
|
|
|
|
Cette fixture valide framing/canonicalité ; elle n'est pas revendiquée comme un wallet V2 cryptographiquement authentifié tant que création/open V2 n'est pas matérialisé en `pre.016`.
|
|
|
|
## Politique API durable : default distinct de latest
|
|
|
|
La documentation fige dès `pre.015` la politique qui sera matérialisée en code dans `pre.016`.
|
|
|
|
Deux notions doivent rester distinctes :
|
|
|
|
```text
|
|
DEFAULT_WALLET_FORMAT
|
|
LATEST_SUPPORTED_WALLET_FORMAT
|
|
```
|
|
|
|
Après intégration runtime V2 :
|
|
|
|
```text
|
|
DEFAULT_WALLET_FORMAT = V2
|
|
LATEST_SUPPORTED_WALLET_FORMAT = V2
|
|
```
|
|
|
|
Si V3 existe plus tard :
|
|
|
|
```text
|
|
DEFAULT_WALLET_FORMAT = V2 # peut rester V2
|
|
LATEST_SUPPORTED_WALLET_FORMAT = V3
|
|
```
|
|
|
|
Une nouvelle version supportée ne change jamais automatiquement le default.
|
|
|
|
### Création
|
|
|
|
API générique :
|
|
|
|
```text
|
|
create_wallet_file(...) -> DEFAULT_WALLET_FORMAT, donc V2
|
|
```
|
|
|
|
APIs forcées :
|
|
|
|
```text
|
|
create_wallet_file_v1(...)
|
|
create_wallet_file_v2(...)
|
|
create_wallet_file_v3(...) si V3 existe un jour
|
|
```
|
|
|
|
Les fonctions `_vN` restent une possibilité explicite pour les applications qui veulent imposer un wire précis.
|
|
|
|
### Lecture / inspection
|
|
|
|
API générique :
|
|
|
|
```text
|
|
open_wallet_*_file(...)
|
|
inspect_locked_wallet_file(...)
|
|
```
|
|
|
|
doit détecter et dispatcher les versions supportées.
|
|
|
|
API versionnée :
|
|
|
|
```text
|
|
open_wallet_*_file_v1(...)
|
|
open_wallet_*_file_v2(...)
|
|
inspect_locked_wallet_file_v1(...)
|
|
inspect_locked_wallet_file_v2(...)
|
|
```
|
|
|
|
doit exiger exactement la version indiquée.
|
|
|
|
La même règle est appliquée aux autres opérations pour lesquelles la version native du fichier est pertinente.
|
|
|
|
## Future V3 / second facteur
|
|
|
|
V2 est volontairement **sans second facteur**.
|
|
|
|
Si un futur V3 introduit password + 2FA :
|
|
|
|
```text
|
|
ksp-wallet-lib possède la politique d'autorisation
|
|
ksp-wallet-lib décide si un second facteur est requis
|
|
ksp-wallet-lib possède challenge et validation cryptographique
|
|
WalletOwner est impossible tant que les facteurs exigés ne sont pas satisfaits
|
|
Wallet Desk ne décide jamais qu'une preuve 2FA est valide
|
|
```
|
|
|
|
Wallet Desk ou un autre client peut néanmoins évoluer pour l'UX interactive : OTP, push/attente, enrollment, recovery, hardware/WebAuthn ou consentement externe.
|
|
|
|
`ksp-wallet-lib` doit conserver sa frontière autonome vis-à-vis de Config/Transport/Tauri. Si un fournisseur réseau est nécessaire, une abstraction/provider KSP séparée peut obtenir la preuve tandis que Wallet reste propriétaire de la règle d'autorisation.
|
|
|
|
## Nouveau découpage de `0.2.6`
|
|
|
|
La documentation/candidate anciennement prévue en `pre.015` est repoussée afin de ne pas mélanger wire, runtime/migration et packaging :
|
|
|
|
```text
|
|
pre.015 wire binaire V2 + codec canonique
|
|
pre.016 APIs génériques/versionnées + création/open V2 + Wallet Desk sur API générique
|
|
pre.017 migration explicite V1 -> V2 + persistence/canaris + régression Wallet Desk
|
|
pre.018 documentation finale + candidate + stratégie release/bundle/CWD + build Tauri final
|
|
rel.001 publication stable v0.2.6
|
|
```
|
|
|
|
Le build Tauri reste interdit avant `pre.018` et devra être l'absolue dernière opération de validation de la candidate.
|
|
|
|
## Réalignement de la série
|
|
|
|
`pre.014` avait temporairement intercalé le chantier binaire en `0.2.7`. Cette décision est superseded puisque V2 est désormais traité dans `0.2.6`.
|
|
|
|
La suite redevient :
|
|
|
|
```text
|
|
0.2.7 WebSocket Solana standard
|
|
0.2.8 Helius LaserStream WebSocket
|
|
0.2.9 Yellowstone gRPC standard/provider-neutral
|
|
0.2.10 off-chain price transport
|
|
0.2.11 price visualization desk + intégration Wallet Desk
|
|
0.2.12 interface/wire foundation
|
|
0.2.13 program-api foundation
|
|
```
|
|
|
|
Le prompt `prompts/012-V0_2_7_START_PROMPT.md` est réaligné sur WebSocket Solana standard.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
crates/ksp-wallet-lib/src/transcript_v2.rs
|
|
crates/ksp-wallet-lib/src/wire_v2.rs
|
|
crates/ksp-wallet-lib/tests/fixtures/kspwallet_v2_wire_only.bin
|
|
crates/ksp-wallet-lib/unit_tests/transcript_v2.rs
|
|
crates/ksp-wallet-lib/unit_tests/wire_v2.rs
|
|
docs/formats/KSPWALLET_V2.md
|
|
deltas/0.2.6/pre.015.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
ROADMAP.md
|
|
crates/ksp-wallet-lib/README.md
|
|
crates/ksp-wallet-lib/USAGE.md
|
|
crates/ksp-wallet-lib/src/constants.rs
|
|
crates/ksp-wallet-lib/src/lib.rs
|
|
crates/ksp-wallet-lib/tests/public_api.rs
|
|
docs/000-README.md
|
|
docs/IDEAS.md
|
|
docs/architecture/004-COMPONENT_INVENTORY.md
|
|
docs/formats/000-README.md
|
|
docs/formats/KSPWALLET_V1.md
|
|
docs/plans/000-README.md
|
|
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
|
docs/plans/013-V0_2_6_WALLET_DESK_PLAN.md
|
|
docs/validation/009-V0_2_6_WALLET_DESK_COMPLIANCE.md
|
|
prompts/000-README.md
|
|
prompts/011-V0_2_6_START_PROMPT.md
|
|
prompts/012-V0_2_7_START_PROMPT.md
|
|
```
|
|
|
|
## Fichiers volontairement non modifiés
|
|
|
|
```text
|
|
CHANGELOG.md
|
|
crates/ksp-app-config-desk/*
|
|
crates/ksp-app-wallet-desk/*
|
|
```
|
|
|
|
Le CHANGELOG reste réservé à la clôture. Les Desks ne changent pas tant que la façade générique/runtime V2 n'est pas prête en `pre.016`.
|
|
|
|
## Contrôles assistant
|
|
|
|
L'environnement de génération ne fournit pas `cargo`, `rustc` ou `rustfmt`. Les contrôles exécutables disponibles sont donc structurels :
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py requis avant livraison
|
|
fixture V2 header/length/layout vérification indépendante
|
|
fixture V2 sha256 vérification indépendante
|
|
comparaison V1/V2 2037 / 628 octets
|
|
delta vérifié contre pre.014-fix.001
|
|
```
|
|
|
|
Compilation, Clippy et tests restent autoritatifs côté opérateur.
|
|
|
|
## Validation opérateur requise
|
|
|
|
Après application du delta :
|
|
|
|
```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
|
|
```
|
|
|
|
Points attendus :
|
|
|
|
```text
|
|
V1 reste intégralement vert
|
|
nouveaux tests wire_v2/transcript_v2 verts
|
|
public API V2 codec visible depuis crate root
|
|
aucune régression Wallet Desk
|
|
smokes réseau restent ignored sauf opt-in explicite
|
|
```
|
|
|
|
**Ne pas exécuter `cargo tauri build` en `pre.015`.** Le build final reste réservé à `pre.018` et doit demeurer l'ultime opération de validation de `0.2.6`.
|