# 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==` ; - 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 Transport V1/V2 vers `HttpTransportSettings` et, en V2, `WsTransportSettings`, 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 : ```text 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 : ```text ./.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 accepte les valeurs secrètes pour les URLs HTTP/WebSocket et, en V3, pour `grpc_endpoints[].secret_metadata[]` : la valeur réelle est transmise au runtime légitime, tandis que la projection sûre et les `Debug` restent redacted. Les metadata gRPC publiques et secrètes sont séparées et leur provenance Config est contrôlée avant mapping. `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`](USAGE.md) — construction du moteur, résolution runtime et management ; - [`TODO.md`](TODO.md) — points explicitement différés ; - [`../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](../../docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan historique détaillé de la fondation Config ; - [`../../config/std.logging.json`](../../config/std.logging.json) — document standard Logging ; - [`../../config/std.transport.json`](../../config/std.transport.json) — document standard Transport V3 HTTP + WebSocket + Yellowstone gRPC, avec lecture backward des V1/V2 ; - [`../../config/std.wallet.json`](../../config/std.wallet.json) — racine Wallet globale et sous-répertoire optionnel par profil ; - [`../../config/composite.ksp-app-wallet-desk.json`](../../config/composite.ksp-app-wallet-desk.json) — composition Logging/Transport/Wallet de Wallet Desk ; - [`../../.env.example`](../../.env.example) — inventaire versionné des variables d'environnement runtime.