khadhroony-solana-project/crates/ksp-config-lib

ksp-config-lib

ksp-config-lib est le propriétaire unique de la configuration applicative KSP.

La crate centralise les documents JSON, leurs schemas, les profils et compositions, les variables d'environnement KSP_* / KSPB_*, le fichier .env, la résolution effective et les mutations persistantes explicitement autorisées.

Responsabilités

ksp-config-lib possède :

• le bootstrap non récursif config/ / config/schemas/ et les overrides --cfgpath / --schemapath ;
• le registre logique file_id -> filename, son inventaire public read-only ordonné par file_id et les overrides --filemap=<file_id>=<filename> ;
• la lecture JSON et la validation JSON Schema Draft 2020-12 ;
• les invariants sémantiques KSP des documents connus ;
• les globals, default_profile, profils nommés et leur provenance ;
• les compositions génériques par file_id, sans dépendance à un filename physique ;
• le snapshot des variables process KSP/KSPB et la lecture de ./.env ;
• la priorité process > .env > fallback > missing ;
• les placeholders ${NAME} et ${NAME:-fallback} ;
• la classification Public, Internal, Secret ;
• les représentations réelle et sûre/redacted ainsi que la provenance des valeurs résolues ;
• l'adapter du document Logging effectif vers ksp_logging_lib::LoggingSettings ;
• l'adapter du document HTTP Transport effectif vers ksp_onchain_transport_lib::HttpTransportSettings, y compris redaction/provenance des URLs KSP_SECRET_* ;
• la surface de management pour inspecter et réparer les sources Config enregistrées, modifier std.logging.json, consulter les rapports d'environnement, révéler explicitement une valeur réelle et modifier .env ;
• les écritures atomiques JSON/.env et la protection des permissions .env ;
• les audits workspace empêchant les bypass d'ownership Config et les oublis dans .env.example.

Ressources gérées

Le registre par défaut connaît :

cfg.composite.ksp-app-wallet-desk -> config/composite.ksp-app-wallet-desk.json
cfg.std.logging                    -> config/std.logging.json
cfg.std.transport                  -> config/std.transport.json
cfg.std.wallet                     -> config/std.wallet.json
schema.composite                   -> config/schemas/composite.schema.json
schema.std.logging                 -> config/schemas/std.logging.schema.json
schema.std.transport               -> config/schemas/std.transport.schema.json
schema.std.wallet                  -> config/schemas/std.wallet.schema.json

ConfigFileRegistry::descriptors() expose ces descripteurs en lecture seule et dans un ordre déterministe par file_id. Une application de management peut ainsi découvrir les fichiers connus sans maintenir une liste parallèle ni dépendre de leurs filenames physiques.

ConfigManagement::read_source() permet d'inspecter le texte brut d'un document Config enregistré même lorsque ce document est invalide. save_source_candidate() complète cette frontière : le candidat brut est parsé, validé contre son schema et les invariants sémantiques KSP, puis persisté atomiquement uniquement après validation complète. Le file_id doit appartenir au registre et désigner un document Config ; aucun path arbitraire n'est accepté.

config/examples/composite.example.json conserve l’exemple générique. config/composite.ksp-app-wallet-desk.json est le premier composite runtime concret : il sélectionne Logging, Transport et Wallet par file_id, sans dépendre de leurs filenames physiques.

Le fichier local d'environnement est :

./.env

Il n'est ni versionné ni livré. Le dépôt maintient /.env.example comme inventaire versionné des variables runtime utilisées. Toute nouvelle variable KSP/KSPB concrète doit y être ajoutée avec un commentaire d'usage dans le même delta que sa première utilisation.

Frontières

Les autres crates et applications KSP ne doivent pas :

• lire directement les variables applicatives KSP_* / KSPB_* ;
• parser ou écrire directement .env ;
• ouvrir directement les documents Config connus par leur filename physique ;
• réimplémenter la sélection de profils, les compositions ou les placeholders ;
• reconstruire elles-mêmes la configuration Logging, Transport ou Wallet depuis le JSON.

ksp-config-lib dépend de ksp-core-lib pour Error/Result, de ksp-logging-lib pour les événements Config utiles et le contrat LoggingSettings, et de ksp-onchain-transport-lib pour construire le contrat runtime Transport dans la direction Config -> Transport. Le document Wallet reste un contrat de chemins/profils Config et n’introduit aucune dépendance Config -> ksp-wallet-lib.

La dépendance inverse est interdite : ksp-core-lib, ksp-logging-lib et ksp-onchain-transport-lib ne dépendent pas de Config.

Config ne possède pas le LoggingGuard. L'application ou le service qui orchestre le runtime construit la configuration effective puis possède le lifecycle ksp_logging_lib::initialize/reinitialize.

Tauri et les DTO TS-RS restent hors de cette crate. ksp-app-config-desk reste une frontière applicative mince au-dessus des APIs Config et découvre les documents standards via le registre Config sans déplacer leur logique métier dans l'application.

Secrets

Un secret reste accessible au runtime ou au management lorsqu'un consumer autorisé en a réellement besoin, mais les vues ordinaires utilisent la représentation sûre.

Les méthodes reveal_* constituent un opt-in explicite au réel. L'authentification/autorisation de l'utilisateur humain appartient à l'application appelante et les valeurs retournées par ces méthodes ne doivent jamais être journalisées.

Le document Logging refuse les valeurs de sensibilité Secret dans sa configuration effective. Le document Transport les accepte pour les URLs endpoint : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les Debug restent redacted. std.wallet refuse également toute sensibilité Secret pour wallets_directory/wallets_subdirectory; les passwords Wallet restent un autre flux Config et ne sont jamais stockés dans ce JSON.

Documentation

• USAGE.md — construction du moteur, résolution runtime et management ;
• TODO.md — points explicitement différés après 0.1.3 ;
• ../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md — plan historique détaillé de la fondation Config ;
• ../../config/std.logging.json — document standard Logging ;
• ../../config/std.transport.json — document standard HTTP Transport ;
• ../../config/std.wallet.json — racine Wallet globale et sous-répertoire optionnel par profil ;
• ../../config/composite.ksp-app-wallet-desk.json — composition Logging/Transport/Wallet de Wallet Desk ;
• ../../.env.example — inventaire versionné des variables d'environnement runtime.