Sasedev/khadhroony-bot3

Fork 0

Files

SinuS Von SifriduS e3acb8ceb1 v0.5.2-pre.005

2026-08-10 19:12:13 +02:00

30 KiB

Raw Blame History

Plan `0.5.2` — restructuration de `ks-wallet`

1. Objet du plan

Ce document est le plan temporaire de 0.5.2.

0.5.2-pre.001 reste une prerelease de caractérisation et de cadrage. Elle ne modifie encore aucune API runtime, aucun wallet persistant et aucun format de stockage.

L'objectif fonctionnel de 0.5.2 est simple : faire de ks-wallet le composant Solana généraliste chargé de créer, conserver, ouvrir, signer avec, importer, exporter et gérer plusieurs wallets sans exposer directement leur matériau secret aux consommateurs.

Le plan doit rester centré sur ce besoin. Les détails cryptographiques ou de concurrence ne deviennent des choix d'implémentation qu'au moment où ils sont nécessaires.

2. Cible fonctionnelle

À la fin de 0.5.2, ks-wallet doit pouvoir couvrir les responsabilités suivantes.

2.1 Plusieurs wallets persistants

ks-wallet doit pouvoir :

créer plusieurs wallets ;
les identifier et y accéder par alias ;
lister leurs identités non sensibles ;
charger un wallet existant ;
refuser les collisions ou écrasements silencieux ;
supprimer un wallet uniquement via une opération explicite si cette surface est retenue pendant l'implémentation.

Un consommateur ne doit pas avoir besoin de connaître le chemin réel du fichier ou son format interne pour travailler avec un wallet.

La découverte des wallets persistants doit être faite par ks-wallet dans le répertoire de wallet résolu qu'il possède. Avec la configuration actuelle, la racine globale provient de wallet.config.json.wallets_directory, surchargeable par KS_WALLETS_DIRECTORY et valant wallets par défaut ; un profil peut encore résoudre un sous-répertoire.

Le store doit donc pouvoir scanner son répertoire résolu à la recherche des fichiers :

<alias>.kswallet

Le scan doit être borné au répertoire possédé par le store, non récursif par défaut, refuser les symlinks/fichiers non réguliers et ne considérer un candidat comme wallet qu'après validation de l'alias, du suffixe, du magic et de la version du conteneur. Le nom de fichier n'est pas à lui seul une preuve de validité.

Cette découverte automatique n'interdit pas l'ouverture explicite d'un fichier natif situé ailleurs. Un consommateur, par exemple kb-app-demo-desktop après sélection via un file browser, doit pouvoir fournir un chemin arbitraire vers un .kswallet à ks-wallet. Ce chemin explicite ne modifie pas le répertoire configuré, n'enregistre pas automatiquement le fichier dans le store et ne doit pas être projeté dans une identité publique ou un DTO frontend. L'ouverture réelle utilisera le mot de passe fourni au moment de l'appel ou dans l'étape d'ouverture immédiatement associée.

2.2 Wallets temporaires ou jetables

ks-wallet doit conserver la capacité actuelle de générer des wallets temporaires en mémoire pour :

tests synthétiques ;
scénarios Devnet ;
démonstrations ;
comptes intermédiaires ou jetables.

Un wallet temporaire n'a pas besoin d'être persisté ni protégé par mot de passe tant qu'il reste purement en mémoire.

La possibilité de convertir explicitement un wallet temporaire en wallet persistant pourra être retenue si elle simplifie l'API sans créer de nouveau risque.

2.3 Mot de passe par wallet persistant

Chaque wallet persistant géré nativement par ks-wallet doit être protégé par un mot de passe propre au conteneur ks-wallet.

Ce mot de passe n'est pas un « mot de passe Solana ». Il sert à protéger le matériau secret persistant géré par ks-wallet.

L'API doit permettre au minimum :

création d'un wallet avec mot de passe ;
ouverture/déverrouillage avec mot de passe ;
fermeture/verrouillage lorsqu'une capacité ouverte est conservée en mémoire ;
changement du mot de passe en fournissant l'ancien mot de passe ;
conservation exacte de la même clé publique après changement de mot de passe.

Le changement de mot de passe ne change pas la keypair Solana : il rechiffre le même matériau secret dans le conteneur .kswallet.

Une rotation du secret Ed25519 tout en conservant la même pubkey n'est pas une fonctionnalité valide à prévoir. Pour une keypair Solana standard, la clé publique est dérivée du secret ; changer réellement le secret produit donc un autre wallet/public key. Une éventuelle rotation de clé future serait une opération distincte impliquant une nouvelle identité et, selon les usages, la migration des fonds/authorities.

La représentation runtime exacte d'un wallet ouvert sera décidée pendant l'implémentation. Le plan n'impose pas prématurément une hiérarchie complexe de sessions.

2.4 Signature sans exposition du secret

Les consommateurs doivent demander une capacité de signature à ks-wallet plutôt que les octets privés.

ks-lib utilise déjà solana_signer::Signer sans dépendre de ks-wallet. Cette frontière est saine et doit être préservée :

ks-wallet
    -> fournit/adapte une capacité de signature
ks-lib / exécuteurs
    -> utilisent Signer
    -> ne connaissent pas le stockage wallet

La manière exacte de fournir cette capacité doit respecter les contraintes Send/Sync réellement nécessaires, sans rendre le matériau secret clonable par commodité.

2.5 Import et export

ks-wallet doit servir d'intermédiaire entre son format natif et les formats externes explicitement supportés.

L'import doit obligatoirement couvrir le format fichier standard des binaires Solana (solana-keygen, solana, outils SPL), actuellement utilisé comme legacy par le workspace : tableau JSON des 64 octets de la keypair. L'export vers ce même format standard est également obligatoire dans 0.5.2.

Les formats des wallets tiers doivent être inventoriés à partir de documentation officielle ou d'une spécification/source officielle suffisamment précise. D'autres formats pourront être ajoutés uniquement après caractérisation de leurs contrats réels.

L'export doit distinguer :

les données strictement publiques, qui peuvent être exportées sans révéler de secret ;
tout format contenant ou permettant de reconstruire la clé privée.

Tout export secret doit obligatoirement demander et valider le mot de passe du wallet.

Il ne doit exister aucun export privé implicite simplement pour satisfaire un consommateur interne.

L'objectif est notamment de pouvoir exporter volontairement un wallet vers un format accepté par des outils ou wallets externes comme les formats Solana réellement compatibles avec Solflare ou d'autres logiciels. Chaque format doit être vérifié avant implémentation ; il ne faut pas inventer un format externe générique supposé universel.

3. Format natif persistant cible

Le format legacy <alias>.json ne doit pas rester le format natif de ks-wallet.

L'orientation retenue pour 0.5.2 est un fichier natif :

<alias>.kswallet

Le conteneur .kswallet doit être binaire, auto-identifiable et versionné.

Le caractère binaire n'est pas une mesure cryptographique en lui-même. La confidentialité doit venir d'un mécanisme de chiffrement authentifié standard et d'une dérivation de clé adaptée au mot de passe.

Le format binaire devra au minimum permettre d'identifier sans ambiguïté :

un magic/signature de format ;
une version ;
les paramètres nécessaires au déchiffrement ;
le payload protégé ;
les informations d'intégrité/authentification nécessaires.

pre.003 ferme cette décision technique pour le format v1 après vérification des dépendances et des références cryptographiques :

KDF : Argon2id version 19 ;
profil d'écriture par défaut : 64 MiB, 3 passes, 4 lanes, sel 16 octets, sortie 32 octets ;
AEAD : XChaCha20-Poly1305, clé 32 octets, nonce 24 octets, tag 16 octets ;
header fixe : 72 octets little-endian avant l'alias ;
plaintext v1 : exactement les 64 octets du keypair Solana ;
ciphertext v1 : exactement 80 octets avec le tag AEAD ;
taille totale v1 : 193 à 256 octets selon la longueur de l'alias ;
paramètres KDF acceptés : mémoire 64 à 256 MiB, 3 à 10 passes, 1 à 8 lanes, avec les relations Argon2 de mémoire validées ;
données authentifiées : header complet + alias + sel + nonce.

Le layout normatif exact est documenté dans docs/NATIVE_FORMAT.md. pre.003 a fermé la lecture/validation structurelle ; pre.004 active l'encodage, la publication, la dérivation Argon2id, le chiffrement XChaCha20-Poly1305 et l'ouverture authentifiée sans modifier ce wire.

4. Caractérisation du legacy actuel

Le stockage persistant actuel de ks-wallet utilise :

<alias>.json

Le contenu est le tableau JSON standard des 64 octets d'un keypair Solana.

4.1 Alias

Le contrat actuel impose :

longueur de 1 à 64 octets ;
premier caractère ASCII alphanumérique ;
caractères suivants ASCII alphanumériques, _ ou -.

Ces règles sont compatibles avec le futur nom <alias>.kswallet et doivent être conservées sauf raison explicite découverte pendant les tests de caractérisation.

4.2 Permissions Unix

Le comportement actuel impose :

répertoire wallet privé en 0700 ;
fichier wallet privé en 0600 ;
refus des symlinks et fichiers non réguliers ;
refus des permissions trop ouvertes lors de la lecture.

Ces propriétés doivent rester au minimum aussi strictes pour .kswallet et les exports privés.

4.3 Création et écrasement

La création actuelle utilise create_new, donc réserve exclusivement le nom final et refuse l'écrasement.

En revanche, le contenu legacy est écrit directement dans le fichier final. La publication n'est donc pas encore une écriture atomique crash-safe par fichier temporaire + renommage.

Le nouveau format devra être écrit atomiquement et ne jamais écraser silencieusement un wallet existant.

4.4 Lecture et corruption

Les tests de caractérisation doivent figer le comportement actuel pour :

fichier absent ;
fichier déjà présent ;
contenu corrompu ;
contenu tronqué/incomplet ;
mauvais nombre d'octets ;
permissions incorrectes ;
fichier non régulier ou symlink.

La fixture doit toujours utiliser une clé synthétique.

5. Migration du legacy

La migration doit être une importation du legacy vers le nouveau format .kswallet, pas une réécriture destructive in-place du .json.

Le contrat minimal est :

lire et valider le legacy ;
reconstruire le keypair ;
vérifier sa clé publique ;
demander le mot de passe destiné au nouveau wallet ;
construire le nouveau .kswallet ;
l'écrire atomiquement dans un nouveau fichier ;
rouvrir et vérifier le nouveau fichier ;
confirmer que la clé publique est strictement identique ;
conserver le legacy tant que la migration n'est pas prouvée complète.

Aucune migration ne doit transformer automatiquement le legacy en place.

Si un .kswallet existe mais est invalide, ks-wallet ne doit pas masquer cette corruption en basculant silencieusement sur un ancien .json.

Le nettoyage éventuel du legacy doit être une opération séparée et explicite, après validation de la migration.

6. Import et export : contrat attendu

6.1 Import

L'import reçoit une source externe, la valide, récupère le matériau secret uniquement en mémoire, puis crée un nouveau wallet natif .kswallet protégé par le mot de passe choisi.

Les collisions doivent être définies séparément pour :

alias déjà utilisé ;
même clé publique déjà gérée sous un autre alias.

Aucun import ne doit écraser silencieusement un wallet existant.

6.2 Export public

Une identité publique peut exposer ou exporter uniquement des données sûres, par exemple :

alias ;
clé publique ;
type/source si utile ;
état logique non sensible.

6.3 Export secret

Tout export permettant de reconstruire la clé privée doit :

demander le mot de passe du wallet ;
vérifier ce mot de passe avant de produire l'export ;
viser un format explicitement demandé ;
appliquer des permissions privées ;
utiliser une écriture atomique ;
refuser l'écrasement silencieux ;
ne jamais loguer le matériau exporté ni le mot de passe.

Le mot de passe du conteneur .kswallet n'a pas à devenir le mot de passe d'un format externe. L'adaptateur d'export doit respecter le contrat du format cible.

6.4 Matrice de compatibilité externe à établir

0.5.2 doit produire une matrice documentée des formats d'entrée/sortie réellement utilisables avec les principaux wallets Solana. L'inventaire doit au minimum examiner :

Solana CLI / solana-keygen ;
Phantom ;
Solflare ;
Backpack ;
Trust Wallet ;
Coinbase Wallet / Base app ;
tout autre wallet Solana majeur dont un format d'import privé est officiellement documenté et techniquement exploitable à partir d'une keypair ks-wallet.

Pour chaque cible, la matrice doit distinguer :

import par clé privée brute ;
import par fichier/keystore ;
import par recovery phrase ;
format/encodage exact lorsqu'il est documenté ;
possibilité réelle de produire ce format à partir d'une keypair Solana arbitraire ;
conservation garantie ou non de la même pubkey ;
disponibilité d'une documentation/spécification officielle suffisamment précise pour écrire et tester l'adaptateur.

La matrice finalisée de pre.005 se trouve dans docs/WALLET_FORMAT_COMPATIBILITY.md. Les décisions retenues sont :

Cible	Surface officiellement documentée	Décision `pre.005`
Solana CLI / `solana-keygen`	fichier keypair JSON standard	import + export `SolanaCliJson`
Phantom	import/export d'une private key Solana ; private key Base58 documentée Solana	adaptateur tiers de référence `SolanaPrivateKeyBase58`
Solflare	import d'une private key copiée depuis Phantom	compatible avec le même wire Base58 ; pas de codec séparé
Solflare Keystore	import de fichier keystore	TODO version ultérieure non déterminée
Backpack	import avancé par private key ou recovery phrase	TODO : wire Solana exact à caractériser
Trust Wallet	restauration/export de private keys	TODO : wire Solana exact à caractériser
Base app / ex-Coinbase Wallet	restauration principalement documentée par recovery phrase	aucun adaptateur ; aucune mnemonic synthétique
Coinbase Developer Platform	API d'import/export de clés Solana, distincte de Base app	information de compatibilité seulement, hors adaptateur wallet

Une recovery phrase n'est pas interchangeable avec une keypair arbitraire. Si ks-wallet ne possède que la keypair finale et pas la mnemonic/seed d'origine avec son chemin de dérivation, il ne doit pas inventer une phrase qui prétend restaurer la même pubkey.

Dans 0.5.2, après l'adaptateur Solana CLI obligatoire, un seul adaptateur vers un wallet tiers est retenu comme exemple de la mécanique d'interopérabilité : SolanaPrivateKeyBase58, avec Phantom comme cible de référence documentée. Les autres formats jugés faisables sont ajoutés au TODO.md pour une version ultérieure non déterminée.

Tout adaptateur tiers reste soumis à la règle générale : un export contenant le secret est impossible sans validation du mot de passe du .kswallet.

7. Modèle public simple de `ks-wallet`

Les noms Rust principaux sont désormais stabilisés par les tranches exécutables ; la responsabilité peut être représentée ainsi :

ks-wallet
|
+-- manager / store
|   +-- create persistent(alias, password)
|   +-- create temporary(...)
|   +-- scan/discover <alias>.kswallet
|   +-- list identities
|   +-- find/open by alias
|   +-- remove explicitement si retenu
|
+-- password
|   +-- unlock/open
|   +-- lock/close
|   +-- change password
|
+-- signing
|   +-- public key
|   +-- signer capability
|
+-- import
|   +-- legacy Solana JSON
|   +-- autres formats validés
|
+-- export
    +-- public
    +-- secret + password obligatoire

Le stockage réel, les bytes privés et les paramètres cryptographiques restent internes à la crate.

8. Multi-wallet et configuration

ks-wallet doit être capable de gérer plusieurs wallets sans notion globale mutable de « wallet actif ».

La sélection appartient au consommateur :

worker A -> alias A
worker B -> alias B
application -> alias C

ks-config peut transporter un alias ou une sélection non sensible, mais ne devient jamais gestionnaire du mot de passe ou du matériau secret.

Un profil peut continuer à sélectionner un alias lorsqu'un consommateur n'en attend qu'un, mais ks-wallet ne doit pas imposer qu'il existe un « alias principal » universel.

9. Consommateurs actuels

L'inventaire pre.001 montre deux dépendants directs de ks-wallet :

ks-pipeline-demo-scenarios ;
kb-app-demo-desktop.

ks-lib n'a pas de dépendance directe vers ks-wallet et consomme des solana_signer::Signer. Cette séparation doit être conservée.

Le desktop ne doit jamais recevoir directement un type runtime sensible de ks-wallet :

ks-wallet runtime
    -> DTO possédé par kb-app-demo-desktop
    -> TS-RS
    -> frontend

Le DTO peut exposer alias, pubkey et état logique lorsque ces données sont explicitement sûres.

10. Compatibilité avec les outils Solana existants

Le workspace utilise encore le fichier keypair legacy brut avec certains outils externes, notamment les workflows Devnet autour de solana-keygen / spl-token et KS_DEVNET_WALLET.

Un .kswallet ne doit pas être présenté directement à ces outils.

La transition doit donc choisir explicitement entre :

import/export volontaire vers le format keypair JSON standard accepté par les binaires Solana ;
adaptation d'un scénario pour signer directement via ks-wallet ;
maintien borné du legacy pour un workflow de transition.

Il ne faut pas créer un export privé automatique ou caché juste pour conserver un ancien script.

11. Sécurité et non-divulgation

Les contraintes suivantes restent non négociables :

aucun secret wallet dans un fichier de configuration source ;
aucun secret dans KS_PUBLIC_* ou KB_PUBLIC_* ;
aucun secret dans Tauri ou TS-RS générique ;
aucun mot de passe, octet privé, payload chiffré ou keypair dans logs/erreurs/diagnostics normaux ;
aucun Debug automatique d'un type possédant du matériau secret ;
aucun getter public arbitraire des bytes privés ;
zéroïsation des buffers secrets temporaires lorsque les types et dépendances le permettent ;
les erreurs publiques ne doivent pas inclure inutilement le chemin local complet du wallet.

Le fait que .kswallet soit binaire ne remplace aucune de ces protections.

12. Tests minimums de `0.5.2`

12.1 Legacy

fixture synthétique 64 octets ;
alias et nom <alias>.json ;
pubkey conservée après lecture/import ;
absent, déjà présent, corrompu, tronqué, longueur invalide ;
permissions Unix ;
symlink et fichier non régulier.

12.2 Format `.kswallet`

magic et version ;
version inconnue ;
troncature/corruption ;
mauvais mot de passe ;
intégrité/authentification ;
permissions privées ;
écriture atomique ;
refus d'écrasement ;
persistance puis réouverture ;
absence de secret dans Debug, erreurs et logs.

12.3 Multi-wallet et password

création de plusieurs aliases ;
lookup par alias ;
collision d'alias ;
collision de pubkey selon le contrat retenu ;
changement de mot de passe ;
ancien mot de passe refusé après changement ;
nouveau mot de passe accepté ;
pubkey inchangée ;
vérification que la keypair est strictement identique avant/après changement de mot de passe ;
absence d'API prétendant faire tourner le secret Ed25519 en conservant la pubkey.

12.4 Temporaire et signature

génération purement mémoire ;
signature valide ;
aucune persistance involontaire ;
capacité de signature utilisable par les consommateurs réels sans exposition des bytes ;
contraintes thread-safety des chemins effectivement utilisés.

12.5 Import/export

import du fichier Solana CLI JSON préservant la pubkey ;
export vers le fichier Solana CLI JSON avec mot de passe valide ;
round-trip .kswallet -> Solana CLI JSON -> import préservant la pubkey ;
import corrompu refusé ;
collision refusée ;
export secret impossible sans mot de passe valide ;
export secret avec mot de passe valide vers chaque format effectivement supporté ;
matrice Phantom/Solflare/Backpack/Trust/Coinbase-Base et autres cibles retenues ;
un adaptateur wallet tiers d'exemple implémenté et testé ;
autres adaptateurs faisables reportés explicitement au TODO ;
permissions privées et écriture atomique de l'export ;
aucun secret dans les erreurs/logs.

12.6 Configuration et desktop

sélection d'un alias sans secret dans ks-config ;
aucune dépendance inverse vers une application ;
DTO desktop non sensible ;
canaris de non-divulgation des mots de passe, bytes privés, chemins internes et payloads protégés.

13. Découpage proposé des prereleases

Le découpage reste borné mais peut être ajusté si une tranche devient trop large après compilation/tests.

`0.5.2-pre.001` — plan et caractérisation

audit du code et des consommateurs ;
caractérisation legacy ;
besoins multi-wallet, temporary wallet, password, import/export ;
orientation .kswallet binaire ;
contrat migration/rollback ;
plan temporaire.

Aucun nouveau format n'est écrit dans cette prerelease.

`0.5.2-pre.002` — caractérisation exécutable et API de base

tests externes du legacy ;
identité publique minimale sans chemin local ;
manager/scan/listing/lookup multi-wallet sur le répertoire configuré ;
inspection explicite d'un .kswallet hors store sans mutation de la configuration ni auto-enregistrement ;
préambule d'identification natif minimal magic + version, uniquement pour rendre la découverte exécutable ;
contrat de wallet temporaire ;
frontière de signature compatible avec ks-lib.

Le préambule d'identification introduit ici ne définit pas encore le payload protégé : le codec complet, les bornes du conteneur, KDF et AEAD restent dans pre.003.

`0.5.2-pre.003` — format et décodage `.kswallet`

spécification binaire v1 documentée dans docs/NATIVE_FORMAT.md ;
Argon2id v19 + XChaCha20-Poly1305 retenus et identifiés explicitement dans le header ;
profil KDF par défaut 64 MiB / 3 passes / 4 lanes et bornes anti-DoS ;
décodage/validation stricts avec rejet des versions, flags, algorithmes, réserves et longueurs inconnus ;
plaintext keypair v1 fixé à 64 octets, ciphertext/tag à 80 octets et fichier total à 193..256 octets ;
lecture bornée avant allocation et détection d'une croissance concurrente ;
alias du header vérifié contre le nom <alias>.kswallet ;
WalletFileHandle enrichi de la pubkey déclarée et de la version sans exposer le chemin ;
validation des permissions privées à la lecture ;
encodage de création et publication atomique/no-clobber explicitement reportés à pre.004 ;
tests du wire v1, truncation, trailing bytes, KDF hors bornes, alias mismatch et réouverture bornée.

La tranche pre.003 reste structurelle ; le cycle de vie protégé est activé par pre.004 ci-dessous.

`0.5.2-pre.004` — password et cycle de vie persistant

WalletPassword possédé, non clonable, redacted et consommé par une opération ;
création persistante avec password et publication atomique/no-clobber ;
dérivation Argon2id et XChaCha20-Poly1305 effectifs hors du runtime async ;
ouverture/déverrouillage par alias ;
ouverture authentifiée d'un WalletFileHandle sélectionné hors store ;
UnlockedWallet comme capacité de signature non clonable ;
fermeture/verrouillage par consommation explicite ou fin de portée de UnlockedWallet ;
changement de mot de passe après authentification de l'ancien, avec nouveau sel/nonce et même keypair/pubkey ;
contrat explicite : la rotation du mot de passe reprotège le fichier mais ne révoque pas une UnlockedWallet déjà remise à un consommateur ;
vérification de la pubkey déchiffrée contre le header authentifié avant exposition du signer ;
zéroïsation des buffers secrets possédés et activation de la zéroïsation du cipher ;
tests d'ancien/nouveau mot de passe, signature, ouverture externe, AAD altéré et canaris de non-divulgation.

`0.5.2-pre.005` — migration, import et export

import legacy/Solana CLI JSON vers .kswallet sans modification de la source ;
export .kswallet vers le format Solana CLI JSON après authentification du mot de passe ;
rollback d'une destination native nouvelle si la vérification post-publication échoue et conservation du legacy ;
matrice officielle finalisée dans docs/WALLET_FORMAT_COMPATIBILITY.md ;
adaptateur tiers SolanaPrivateKeyBase58, avec Phantom comme cible de référence et compatibilité Phantom -> Solflare documentée ;
report Backpack/Trust/Solflare Keystore/Base app au TODO pour une version ultérieure non déterminée ;
password obligatoire pour tout export secret ;
collisions d'alias et de pubkey refusées sans écrasement ;
tests de round-trip Solana CLI JSON/Base58, migration non destructive, permissions privées, collision et mauvais mot de passe.

`0.5.2-pre.006` — configuration et consommateurs

sélection par alias dans ks-config sans secret ;
adaptation ks-pipeline-demo-scenarios ;
adaptation desktop uniquement via DTO sûrs ;
résolution explicite des workflows CLI legacy ;
tests d'intégration et canaris de non-divulgation.

Cette tranche ne doit pas devenir la refonte générale des scénarios prévue pour 0.5.4.

`0.5.2-pre.007` — finalisation

réconciliation des contrats ;
validations finales ;
README/USAGE/TODO/changelogs/guides ;
report des tâches restantes vers une version identifiée ;
mise à jour du ROADMAP ;
archivage du plan et du prompt 0.5.2 sous olddocs/archivekbot3/ ;
préparation du prompt 0.5.3 consacré à ks-store.

14. Critères de clôture

0.5.2 est terminée lorsque :

plusieurs wallets persistants peuvent être découverts dans le store et gérés par alias ;
les wallets temporaires restent disponibles pour tests/scénarios ;
le format natif persistant est .kswallet, binaire, versionné et protégé par mot de passe ;
le changement de mot de passe conserve exactement la même keypair et donc la pubkey ;
un consommateur peut signer sans obtenir les bytes privés ;
le legacy peut être importé sans perte ni écrasement destructif ;
le format Solana CLI JSON dispose d'un import/export testé ;
un adaptateur vers un wallet tiers documenté est implémenté et testé ;
les autres formats tiers faisables identifiés sont consignés au TODO ;
tout export secret exige un mot de passe valide ;
ks-config ne contient que de la sélection non sensible ;
ks-lib reste indépendant du stockage wallet ;
le desktop ne reçoit que des DTO sûrs ;
permissions, atomicité, corruption, collisions et non-divulgation sont testées ;
la documentation finale décrit le contrat réellement implémenté.

15. Hors périmètre

Restent hors 0.5.2 :

migration SQL kb_sol_* -> k_sol_* ;
audit temporel/provenance de ks-store ;
centralisation générale des scénarios 0.5.4 ;
nouvelle couverture Anchor/DEX ;
stockage d'un secret wallet dans PostgreSQL ;
hardware wallets / Ledger ;
KMS/HSM ;
remote signers ;
secret manager universel ;
cloud backup ;
protection contre un utilisateur qui transfère volontairement un fichier .kswallet avec son mot de passe à une autre installation capable de comprendre ce format.

16. Décisions validées pour poursuivre après `pre.001`

Le plan est désormais centré sur les décisions suivantes :

ks-wallet gère plusieurs wallets accessibles par alias ;
ks-wallet conserve des wallets temporaires/jetables ;
chaque wallet persistant natif possède un mot de passe modifiable ;
le format natif cible est un conteneur binaire <alias>.kswallet ;
le format binaire utilise des primitives cryptographiques standard, pas une cryptographie propriétaire ;
les consommateurs signent via une capacité contrôlée sans accéder aux bytes privés ;
ks-lib reste indépendant de ks-wallet et du stockage ;
import et export vers des formats externes font partie du périmètre 0.5.2 ;
tout export secret exige le mot de passe valide du wallet ;
la migration legacy crée un nouveau .kswallet, valide la pubkey et conserve le legacy jusqu'à preuve de réussite ;
ks-config peut sélectionner des aliases mais ne gère aucun secret ;
la découverte persistante scanne le répertoire wallet résolu pour les <alias>.kswallet, sans faire confiance au seul nom de fichier ;
changer le password rechiffre la même keypair ; il n'existe pas de rotation du secret Ed25519 conservant la même pubkey ;
le format keypair JSON des binaires Solana est obligatoire en import et en export dans 0.5.2 ;
la matrice officielle des formats Phantom/Solflare/Backpack/Trust/Coinbase-Base est finalisée dans docs/WALLET_FORMAT_COMPATIBILITY.md ;
SolanaPrivateKeyBase58 est l'adaptateur tiers unique de 0.5.2, avec Phantom comme référence ; les autres formats faisables sont reportés au TODO sans version déterminée ;
le format v1 utilise Argon2id v19 et XChaCha20-Poly1305 selon docs/NATIVE_FORMAT.md, et pre.004 ferme le modèle runtime avec WalletPassword + UnlockedWallet ;
le scan automatique reste limité au répertoire configuré, tandis qu'un consommateur peut fournir explicitement un autre chemin .kswallet à ks-wallet sans modifier le store ni enregistrer ce fichier automatiquement.

Ces décisions ont permis d'ouvrir 0.5.2-pre.002.

30 KiB Raw Blame History

Plan 0.5.2 — restructuration de ks-wallet