# 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`.