diff --git a/.env.example b/.env.example index ee2b3c6..46f759b 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,5 @@ # file: .env.example -# version: 7 +# version: 8 # KSP Logging root directory. Used by config/std.logging.json for relative log output paths. # The current Config document fallback is "logs" when neither the process environment nor .env defines this variable. @@ -34,9 +34,13 @@ KSP_PUBLIC_SOLANA_MAINNET_WS_URL=wss://api.mainnet-beta.solana.com # Keep provider credentials in a KSP_SECRET_* variable; do not copy a real credential-bearing URL into committed JSON. # KSP_SECRET_SOLANA_HTTP_URL=https://provider.example/?api-key=replace-me -# PublicNode personal token used as secret x-token metadata by the committed Yellowstone gRPC profiles. -# Obtain/manage it through the PublicNode / Allnodes token flow; keep the real value only in the process environment or local .env. -# KSP_SECRET_PUBLICNODE_GRPC_X_TOKEN=replace-me +# PublicNode Mainnet personal token used as secret x-token metadata by the committed Mainnet Yellowstone gRPC profile. +# Keep the real value only in the process environment or local .env; do not assume that a Testnet token is authorized on Mainnet. +# KSP_SECRET_PUBLICNODE_MAINNET_GRPC_X_TOKEN=replace-me + +# PublicNode Testnet personal token used as secret x-token metadata by the committed Testnet Yellowstone gRPC profile. +# Keep the real value only in the process environment or local .env; do not assume that a Mainnet token is authorized on Testnet. +# KSP_SECRET_PUBLICNODE_TESTNET_GRPC_X_TOKEN=replace-me # Helius API key used by the LaserStream WebSocket endpoint in config/examples/std.transport.example.json. # Keep the real credential only in the process environment or local .env; never commit it. diff --git a/Cargo.toml b/Cargo.toml index 05f547c..84d6668 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 256 +# version: 257 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.2.9-pre.13.fix.2" +version = "0.2.9-pre.13.fix.3" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/config/std.transport.json b/config/std.transport.json index 189c76f..ef2b678 100644 --- a/config/std.transport.json +++ b/config/std.transport.json @@ -171,7 +171,7 @@ "secret_metadata": [ { "key": "x-token", - "value": "${KSP_SECRET_PUBLICNODE_GRPC_X_TOKEN}" + "value": "${KSP_SECRET_PUBLICNODE_MAINNET_GRPC_X_TOKEN}" } ] } @@ -228,7 +228,7 @@ "secret_metadata": [ { "key": "x-token", - "value": "${KSP_SECRET_PUBLICNODE_GRPC_X_TOKEN}" + "value": "${KSP_SECRET_PUBLICNODE_TESTNET_GRPC_X_TOKEN}" } ] } diff --git a/crates/ksp-config-lib/unit_tests/transport.rs b/crates/ksp-config-lib/unit_tests/transport.rs index 3d16b14..7d8dfae 100644 --- a/crates/ksp-config-lib/unit_tests/transport.rs +++ b/crates/ksp-config-lib/unit_tests/transport.rs @@ -1,5 +1,5 @@ // file: crates/ksp-config-lib/unit_tests/transport.rs -// version: 9 +// version: 10 #[test] fn fixture_transport_profile_maps_complete_runtime_contract() { @@ -134,22 +134,35 @@ fn committed_transport_document_maps_default_and_explicit_profiles() { } #[test] -fn committed_v3_publicnode_profiles_map_provider_neutral_yellowstone_grpc_with_secret_x_token() { +fn committed_v3_publicnode_profiles_map_provider_neutral_yellowstone_grpc_with_network_scoped_secret_x_tokens() { let engine = committed_engine(); let engine = match engine { std::result::Result::Ok(value) => value, std::result::Result::Err(_) => return, }; - let canary = "PUBLICNODE-GRPC-X-TOKEN-CANARY"; - let mut process = std::collections::BTreeMap::::new(); - process.insert("KSP_SECRET_PUBLICNODE_GRPC_X_TOKEN".to_owned(), canary.to_owned()); - let environment = crate::ConfigEnvironment::from_maps(process, std::collections::BTreeMap::new()); - for (profile_id, endpoint_name, cluster, url) in [ - ("publicnode_mainnet", "publicnode_solana_mainnet_yellowstone", "mainnet-beta", "https://solana-yellowstone-grpc.publicnode.com:443"), - ("publicnode_testnet", "publicnode_solana_testnet_yellowstone", "testnet", "https://solana-testnet-yellowstone-grpc.publicnode.com:443"), + for (profile_id, endpoint_name, cluster, url, environment_name, canary) in [ + ( + "publicnode_mainnet", + "publicnode_solana_mainnet_yellowstone", + "mainnet-beta", + "https://solana-yellowstone-grpc.publicnode.com:443", + "KSP_SECRET_PUBLICNODE_MAINNET_GRPC_X_TOKEN", + "PUBLICNODE-MAINNET-GRPC-X-TOKEN-CANARY", + ), + ( + "publicnode_testnet", + "publicnode_solana_testnet_yellowstone", + "testnet", + "https://solana-testnet-yellowstone-grpc.publicnode.com:443", + "KSP_SECRET_PUBLICNODE_TESTNET_GRPC_X_TOKEN", + "PUBLICNODE-TESTNET-GRPC-X-TOKEN-CANARY", + ), ] { + let mut process = std::collections::BTreeMap::::new(); + process.insert(environment_name.to_owned(), canary.to_owned()); + let environment = crate::ConfigEnvironment::from_maps(process, std::collections::BTreeMap::new()); let resolved = engine.load_resolved_transport_config(std::option::Option::Some(profile_id), &environment); - assert!(resolved.is_ok(), "committed PublicNode V3 profile {profile_id} should map: {resolved:?}"); + assert!(resolved.is_ok(), "committed PublicNode V3 profile {profile_id} should map from its network-scoped token: {resolved:?}"); let resolved = match resolved { std::result::Result::Ok(value) => value, std::result::Result::Err(_) => continue, @@ -170,7 +183,7 @@ fn committed_v3_publicnode_profiles_map_provider_neutral_yellowstone_grpc_with_s assert_eq!(endpoint.metadata()[0].key(), "x-token"); assert!(endpoint.metadata()[0].is_secret()); let endpoint_debug = format!("{endpoint:?}"); - assert!(!endpoint_debug.contains(canary), "PublicNode x-token must stay redacted from endpoint Debug"); + assert!(!endpoint_debug.contains(canary), "PublicNode {cluster} x-token must stay redacted from endpoint Debug"); assert_eq!(endpoint.session().connect_timeout(), std::time::Duration::from_millis(10_000)); assert_eq!(endpoint.session().unary_timeout(), std::time::Duration::from_millis(10_000)); assert_eq!(endpoint.session().close_timeout(), std::time::Duration::from_millis(5_000)); @@ -178,6 +191,7 @@ fn committed_v3_publicnode_profiles_map_provider_neutral_yellowstone_grpc_with_s assert!(grpc.validate().is_ok(), "Config-produced Yellowstone gRPC settings should satisfy Transport validation"); let debug = format!("{grpc:?}"); assert!(!debug.contains("publicnode.com"), "Transport settings Debug must not expose gRPC endpoint URLs"); + assert!(!debug.contains(canary), "Transport settings Debug must not expose the network-scoped PublicNode x-token"); } } } diff --git a/crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs b/crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs index 9c04c5f..ee12ae1 100644 --- a/crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs +++ b/crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs @@ -1,26 +1,33 @@ // file: crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs -// version: 3 +// version: 4 //! Opt-in live PublicNode Mainnet/Testnet smokes for authenticated provider-neutral Yellowstone gRPC Subscribe. use std::io::IsTerminal; // rust-rules: trait-import -static PUBLICNODE_X_TOKEN: std::sync::OnceLock = std::sync::OnceLock::new(); +struct PublicNodeTokens { + mainnet: std::string::String, + testnet: std::string::String, +} -fn publicnode_x_token() -> &'static str { - return PUBLICNODE_X_TOKEN - .get_or_init(|| { - assert!( - !std::io::stdin().is_terminal(), - "pipe the PublicNode personal x-token to this ignored smoke on stdin; never pass it as a command-line argument" - ); - let mut token = std::string::String::new(); - std::io::stdin().read_line(&mut token).expect("PublicNode x-token must be readable from smoke stdin"); - let token = token.trim().to_owned(); - assert!(!token.is_empty(), "PublicNode x-token provided on smoke stdin must not be empty"); - return token; - }) - .as_str(); +static PUBLICNODE_X_TOKENS: std::sync::OnceLock = std::sync::OnceLock::new(); + +fn read_token_line(label: &str) -> std::string::String { + let mut token = std::string::String::new(); + std::io::stdin().read_line(&mut token).expect("PublicNode x-token must be readable from smoke stdin"); + let token = token.trim().to_owned(); + assert!(!token.is_empty(), "PublicNode {label} x-token provided on smoke stdin must not be empty"); + return token; +} + +fn publicnode_x_tokens() -> &'static PublicNodeTokens { + return PUBLICNODE_X_TOKENS.get_or_init(|| { + assert!( + !std::io::stdin().is_terminal(), + "pipe two PublicNode personal x-tokens to this ignored smoke on stdin: Mainnet first, Testnet second; never pass them as command-line arguments" + ); + return PublicNodeTokens { mainnet: read_token_line("Mainnet"), testnet: read_token_line("Testnet") }; + }); } fn publicnode_endpoint( @@ -65,11 +72,10 @@ fn slot_request() -> ksp_core_lib::Result 0); - session.close().await.expect("PublicNode Yellowstone Subscribe must close cleanly"); + let close_result = tokio::time::timeout(std::time::Duration::from_secs(7), session.close()) + .await + .expect("KSP Yellowstone Subscribe close must remain bounded beyond the configured five-second provider half-close deadline"); + match close_result { + std::result::Result::Ok(()) => {}, + std::result::Result::Err(error) => { + assert_eq!( + error.code(), + ksp_onchain_transport_lib::ERROR_CODE_TIMEOUT, + "after a live slot was observed, PublicNode close may time out waiting for provider half-close but must not fail for another reason: {error:?}" + ); + }, + } } #[tokio::test(flavor = "current_thread")] -#[ignore = "opt-in live PublicNode Mainnet Yellowstone gRPC smoke; reads one personal x-token from stdin and performs an external TLS/Subscribe request"] -async fn publicnode_mainnet_yellowstone_streams_slots_with_secret_x_token() { - assert_publicnode_slot_stream("publicnode_mainnet_yellowstone", "mainnet-beta", "https://solana-yellowstone-grpc.publicnode.com:443").await; +#[ignore = "opt-in live PublicNode Mainnet Yellowstone gRPC smoke; reads the first personal x-token line from stdin and performs an external TLS/Subscribe request"] +async fn publicnode_mainnet_yellowstone_streams_slots_with_network_scoped_secret_x_token() { + let tokens = publicnode_x_tokens(); + assert_publicnode_slot_stream( + "publicnode_mainnet_yellowstone", + "mainnet-beta", + "https://solana-yellowstone-grpc.publicnode.com:443", + tokens.mainnet.as_str(), + ) + .await; } #[tokio::test(flavor = "current_thread")] -#[ignore = "opt-in live PublicNode Testnet Yellowstone gRPC smoke; reuses the personal x-token read from stdin and performs an external TLS/Subscribe request"] -async fn publicnode_testnet_yellowstone_streams_slots_with_secret_x_token() { - assert_publicnode_slot_stream("publicnode_testnet_yellowstone", "testnet", "https://solana-testnet-yellowstone-grpc.publicnode.com:443").await; +#[ignore = "opt-in live PublicNode Testnet Yellowstone gRPC smoke; reads the second personal x-token line from stdin and performs an external TLS/Subscribe request"] +async fn publicnode_testnet_yellowstone_streams_slots_with_network_scoped_secret_x_token() { + let tokens = publicnode_x_tokens(); + assert_publicnode_slot_stream( + "publicnode_testnet_yellowstone", + "testnet", + "https://solana-testnet-yellowstone-grpc.publicnode.com:443", + tokens.testnet.as_str(), + ) + .await; } diff --git a/deltas/0.2.9/pre.013-fix.003.md b/deltas/0.2.9/pre.013-fix.003.md new file mode 100644 index 0000000..ea4e8a8 --- /dev/null +++ b/deltas/0.2.9/pre.013-fix.003.md @@ -0,0 +1,116 @@ + + + +# Delta `0.2.9-pre.013-fix.003` — credentials PublicNode par réseau + fermeture live bornée + +## 1. Base + +```text +0.2.9-pre.013-fix.002 +``` + +Cette tranche reste strictement dans le couloir technique/live de fin de release. Elle ne modifie ni README/USAGE, ni plan/validation, ni CHANGELOG/ROADMAP, ni le prompt de la release suivante. + +## 2. Motif opérateur + +Deux exécutions live de `yellowstone_publicnode_smoke` avec deux personal tokens PublicNode différents ont montré que l'hypothèse de `fix.002` « un token commun Mainnet/Testnet » n'est pas suffisamment générale : + +- avec le premier token fourni au smoke, `SubscribeOpen` a retourné `PERMISSION_DENIED` sur Mainnet et Testnet ; +- avec le second token, Mainnet a encore retourné `PERMISSION_DENIED` ; +- avec ce même second token, Testnet a franchi `SubscribeOpen`, reçu le slot attendu, puis `close()` a retourné le timeout borné de cinq secondes parce que le provider n'a pas terminé son half-close avant la deadline KSP. + +Ces observations ne suffisent pas à affirmer que PublicNode documente des tokens obligatoirement liés à un réseau. Elles imposent en revanche que KSP puisse fournir des credentials distincts à Mainnet et Testnet et que le smoke ne suppose plus leur interchangeabilité. + +## 3. Version technique + +`workspace.package.version` devient : + +```text +0.2.9-pre.13.fix.3 +``` + +## 4. Config V3 — secrets PublicNode séparés + +Le placeholder partagé est supprimé au profit de deux variables indépendantes : + +```text +KSP_SECRET_PUBLICNODE_MAINNET_GRPC_X_TOKEN +KSP_SECRET_PUBLICNODE_TESTNET_GRPC_X_TOKEN +``` + +Le profil `publicnode_mainnet` consomme uniquement la première ; le profil `publicnode_testnet` consomme uniquement la seconde. Les deux restent injectées comme metadata gRPC secrète `x-token`, jamais dans l'URL. + +`.env.example` inventorie les deux noms sans valeur réelle. Le test Config construit chaque profil avec uniquement son propre canary d'environnement afin de vérifier cette séparation. + +## 5. Smoke PublicNode + +Le smoke Transport reste programmatique et indépendant de Config/env KSP. Son stdin contient maintenant exactement deux lignes : + +```text +ligne 1 = token Mainnet +ligne 2 = token Testnet +``` + +Les deux valeurs sont lues une seule fois dans un `OnceLock` et sont affectées explicitement au réseau correspondant. L'ordre d'exécution des deux tests n'influence donc pas l'association token/réseau. + +Après ouverture de `Subscribe` et réception d'un `YellowstoneSubscribeUpdate::Slot` avec `slot > 0`, la fermeture live accepte deux résultats : + +1. fermeture gracieuse `Ok(())` du provider ; +2. `ERROR_CODE_TIMEOUT` produit par la deadline KSP de half-close. + +Le second résultat ne masque pas un échec fonctionnel : il n'est accepté qu'après réception prouvée d'un slot et un `timeout` externe de sept secondes vérifie que `session.close()` reste lui-même borné. Toute autre erreur de fermeture reste un échec du smoke. + +Le runtime Yellowstone n'est pas modifié par cette adaptation provider/live ; ses contrats déterministes de fermeture restent inchangés. + +## 6. Gate opérateur ciblé + +```bash +cargo fmt --all +python3 scripts/audit_rust_workspace_rules.py +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.9 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-config-lib +cargo test -p ksp-onchain-transport-lib +cargo test -p ksp-core-lib --test workspace_dependencies +``` + +Puis, avec les deux personal tokens réellement générés : + +```bash +read -rsp 'PublicNode Mainnet Yellowstone x-token: ' PUBLICNODE_MAINNET_TOKEN +echo +read -rsp 'PublicNode Testnet Yellowstone x-token: ' PUBLICNODE_TESTNET_TOKEN +echo +printf '%s\n%s\n' "$PUBLICNODE_MAINNET_TOKEN" "$PUBLICNODE_TESTNET_TOKEN" \ + | cargo test -p ksp-onchain-transport-lib --test yellowstone_publicnode_smoke -- --ignored --nocapture +unset PUBLICNODE_MAINNET_TOKEN PUBLICNODE_TESTNET_TOKEN +``` + +Attendu : + +```text +2 passed +0 failed +0 ignored +``` + +Puis les graphes et le gate workspace de fermeture technique : + +```bash +cargo tree -p ksp-onchain-transport-lib +cargo tree -p ksp-onchain-transport-lib --duplicates +cargo tree --duplicates +cargo test --workspace +``` + +## 7. Fichiers modifiés/ajoutés + +```text +.env.example +Cargo.toml +config/std.transport.json +crates/ksp-config-lib/unit_tests/transport.rs +crates/ksp-onchain-transport-lib/tests/yellowstone_publicnode_smoke.rs +deltas/0.2.9/pre.013-fix.003.md +```