12 KiB
Delta 0.2.6-pre.015 — wire binaire .kspwallet V2 et codec canonique
Base requise
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 :
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 :
ksp-general-0.2.6-pre.015-delta.zip
Le signal technique devient :
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 :
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 :
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 :
format_version = 1
JSON UTF-8 strict
bytes -> Base64URL sans padding
APIs _v1 conservées
lecture durable obligatoire
V2 est un nouveau format explicite :
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 :
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 :
bit 0 = VIEW_ENABLED
autres bits = réservés et obligatoirement zéro
Le body est strictement :
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 :
docs/formats/KSPWALLET_V2.md
Codec strict
Nouveau module :
crates/ksp-wallet-lib/src/wire_v2.rs
Surface publique principale :
KspWalletEnvelopeV2::parse_binary(...)
KspWalletEnvelopeV2::to_binary_bytes(...)
Le parser rejette avant toute opération cryptographique :
> 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 :
crates/ksp-wallet-lib/src/transcript_v2.rs
V2 possède des domain separators distincts :
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 :
crates/ksp-wallet-lib/tests/fixtures/kspwallet_v2_wire_only.bin
Mesure :
V1 JSON wire-only = 2037 octets
V2 binary wire-only = 628 octets
réduction = 1409 octets, environ 69,2 %
Hash du fixture V2 :
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 :
DEFAULT_WALLET_FORMAT
LATEST_SUPPORTED_WALLET_FORMAT
Après intégration runtime V2 :
DEFAULT_WALLET_FORMAT = V2
LATEST_SUPPORTED_WALLET_FORMAT = V2
Si V3 existe plus tard :
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 :
create_wallet_file(...) -> DEFAULT_WALLET_FORMAT, donc V2
APIs forcées :
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 :
open_wallet_*_file(...)
inspect_locked_wallet_file(...)
doit détecter et dispatcher les versions supportées.
API versionnée :
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 :
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 :
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 :
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
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
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
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 :
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 :
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 :
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.