v0.2.6-pre.015
This commit is contained in:
435
deltas/0.2.6/pre.015.md
Normal file
435
deltas/0.2.6/pre.015.md
Normal file
@@ -0,0 +1,435 @@
|
||||
<!-- 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`.
|
||||
Reference in New Issue
Block a user