From c89a978f5ef3f6a66fd65834a8119b56dfbb3d32 Mon Sep 17 00:00:00 2001 From: Luomu Date: Wed, 18 Nov 2026 00:17:46 +0800 Subject: [PATCH] feat(providers): support subtree path credential templates Allow a terminal /** in path_template so one path-placed credential serves multiple API methods while preserving exact templates and endpoint authorization. Keep the credential slot anchored and reject duplicate, misplaced, and traversal-bearing references. Cover long-polling getUpdates alongside sendMessage using one HTTP client and one credential through the production REST relay. Update provider documentation and CLI guidance. Closes #5544 Signed-off-by: Luomu --- .../src/provider_credentials.rs | 59 +++- crates/openshell-core/src/secrets.rs | 254 +++++++++++++++++- .../src/l7/rest.rs | 81 ++++++ .../src/l7/rest/tests/path_credentials.rs | 154 +++++++++++ .../openshell-supervisor-network/src/proxy.rs | 73 +++++ docs/how-it-works/providers/overview.mdx | 2 +- docs/how-it-works/providers/profiles.mdx | 5 +- skills/openshell-cli/SKILL.md | 6 +- 8 files changed, 617 insertions(+), 17 deletions(-) create mode 100644 crates/openshell-supervisor-network/src/l7/rest/tests/path_credentials.rs diff --git a/crates/openshell-core/src/provider_credentials.rs b/crates/openshell-core/src/provider_credentials.rs index ab9bd26195..8de6ccd086 100644 --- a/crates/openshell-core/src/provider_credentials.rs +++ b/crates/openshell-core/src/provider_credentials.rs @@ -3,7 +3,7 @@ //! Runtime provider credential snapshots. -use crate::secrets::{CredentialPlacement, SecretResolver}; +use crate::secrets::{CredentialPlacement, PathTemplate, SecretResolver}; use crate::{ endpoint_path::EndpointPathPattern, host_pattern::HostPattern, @@ -101,8 +101,6 @@ impl std::error::Error for StaticCredentialBindingError {} /// Reserved entries in the existing credential map carry static placement only. pub const STATIC_CREDENTIAL_METADATA_PREFIX: &str = "static-env:"; -const CREDENTIAL_PATH_SLOT: &str = "{credential}"; - fn split_static_credential_metadata( credentials: HashMap, ) -> ( @@ -1175,14 +1173,7 @@ fn compile_credential_placement( { CredentialPlacement::QueryParam(metadata.query_param.trim().to_string()) } - "path" - if metadata.path_template.starts_with('/') - && metadata.path_template.matches(CREDENTIAL_PATH_SLOT).count() == 1 - && !metadata - .path_template - .chars() - .any(|c| c.is_control() || "?#".contains(c)) => - { + "path" if PathTemplate::parse(&metadata.path_template).is_some() => { CredentialPlacement::PathTemplate(metadata.path_template.clone()) } _ => { @@ -1687,6 +1678,52 @@ mod tests { } } + #[test] + fn subtree_path_template_serves_every_method_with_one_credential() { + let env = HashMap::from([("API_KEY".into(), "123456:synthetic".into())]); + let bindings = + HashMap::from([("API_KEY".into(), binding("bot-api.example.com", 443, "/**"))]); + let state = ProviderCredentialState::from_bound_environment( + 7, + env.clone(), + HashMap::new(), + HashMap::new(), + bindings.clone(), + vec![], + ) + .unwrap(); + let mut metadata = placement_metadata("path"); + metadata.values_mut().next().unwrap().path_template = "/bot{credential}/**".into(); + assert_eq!( + state + .install_bound_environment(8, env, HashMap::new(), metadata, bindings, vec![]) + .unwrap(), + 1 + ); + let reference = state.snapshot().child_env["API_KEY"].clone(); + for method in ["sendMessage", "getUpdates", "editMessageText"] { + let target = format!("/bot{reference}/{method}"); + let resolver = state + .resolver_for_endpoint("bot-api.example.com", 443, &target) + .unwrap(); + assert_eq!( + crate::secrets::rewrite_target_for_eval(&target, &resolver) + .unwrap() + .resolved, + format!("/bot123456:synthetic/{method}") + ); + } + let moved = format!("/v1/{reference}/getMe"); + let resolver = state + .resolver_for_endpoint("bot-api.example.com", 443, &moved) + .unwrap(); + assert!( + crate::secrets::rewrite_target_for_eval(&moved, &resolver) + .unwrap_err() + .is_placement_mismatch() + ); + } + #[test] fn malformed_static_metadata_revokes_static_material_and_preserves_real_grants() { for malformed in 0..11 { diff --git a/crates/openshell-core/src/secrets.rs b/crates/openshell-core/src/secrets.rs index 6f4856be4c..93dfe4fc76 100644 --- a/crates/openshell-core/src/secrets.rs +++ b/crates/openshell-core/src/secrets.rs @@ -198,6 +198,76 @@ pub enum CredentialPlacement { PathTemplate(String), } +/// Authored `path_template` of a credential placed in the request path. +/// +/// A template is a request path with exactly one `{credential}` slot. It +/// matches only that path, unless it ends in `/**`. The terminal `/**` also +/// matches everything below the path through the slot, so one credential serves +/// every method of an API that keeps its token in a path prefix. A `*` anywhere +/// else is an ordinary character. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PathTemplate { + /// The template without a terminal `/**`. + prefix: String, + /// Byte offset of the credential slot within `prefix`. + slot_offset: usize, + subtree: bool, +} + +impl PathTemplate { + /// The slot a credential placeholder occupies. + pub const SLOT: &'static str = "{credential}"; + const SUBTREE_SUFFIX: &'static str = "/**"; + + /// Parse an authored template, or `None` when it cannot place a credential. + #[must_use] + pub fn parse(template: &str) -> Option { + if !template.starts_with('/') + || template.matches(Self::SLOT).count() != 1 + || template.chars().any(|c| c.is_control() || "?#".contains(c)) + { + return None; + } + let (prefix, subtree) = template + .strip_suffix(Self::SUBTREE_SUFFIX) + .map_or((template, false), |prefix| (prefix, true)); + Some(Self { + slot_offset: prefix.find(Self::SLOT)?, + prefix: prefix.to_string(), + subtree, + }) + } + + /// Whether the template ends in `/**`. + #[must_use] + pub fn is_subtree(&self) -> bool { + self.subtree + } + + /// Match a request path whose own credential token was replaced by the slot. + /// + /// `slot_at` is where that replacement happened in `normalized`. It must + /// equal the declared slot: `{credential}` text the client wrote itself is + /// not a slot, and would otherwise let the real token sit in the wildcard. + fn permits_subtree(&self, normalized: &str, slot_at: usize) -> bool { + if slot_at != self.slot_offset { + return false; + } + let Some(tail) = normalized.strip_prefix(self.prefix.as_str()) else { + return false; + }; + if tail.is_empty() { + return true; + } + // Descendants only: the slot's segment cannot continue past the template. + tail.strip_prefix('/').is_some_and(|descendants| { + descendants + .split('/') + .all(|segment| segment != "." && segment != "..") + }) + } +} + /// The actual destination of a workload-provided credential placeholder. #[derive(Debug, Clone, PartialEq, Eq)] pub enum RequestCredentialLocation { @@ -513,9 +583,11 @@ impl SecretResolver { Some(RequestCredentialLocation::Path(actual)), ) => { // Normalize only this credential's slot; all other path text must match. + let subtree = PathTemplate::parse(expected).filter(PathTemplate::is_subtree); let mut normalized = String::new(); let mut pos = 0; let mut slots = 0; + let mut slot_at = 0; while pos < actual.len() { let next_canonical = actual[pos..] .find(PLACEHOLDER_PREFIX) @@ -533,14 +605,19 @@ impl SecretResolver { return false; }; if placeholder_env_key(token) == Some(key) { - normalized.push_str("{credential}"); + slot_at = normalized.len(); + normalized.push_str(PathTemplate::SLOT); slots += 1; } else { normalized.push_str(token); } pos = end; } - slots == 1 && normalized == *expected + slots == 1 + && subtree.as_ref().map_or_else( + || normalized == *expected, + |template| template.permits_subtree(&normalized, slot_at), + ) } _ => false, } @@ -1862,6 +1939,179 @@ mod tests { ); } + #[test] + fn path_subtree_template_permits_the_base_and_every_descendant() { + let resolver = placement_resolver(CredentialPlacement::PathTemplate( + "/bot{credential}/**".into(), + )); + let token = "openshell:resolve:env:v1_TOKEN"; + for (suffix, resolved) in [ + ("/sendMessage", "/botsecret-value/sendMessage"), + ("/getUpdates", "/botsecret-value/getUpdates"), + ("/files/a/b", "/botsecret-value/files/a/b"), + ("/", "/botsecret-value/"), + ("", "/botsecret-value"), + ] { + let result = rewrite_target_for_eval(&format!("/bot{token}{suffix}"), &resolver) + .unwrap_or_else(|error| panic!("{suffix:?} must be permitted: {error}")); + assert_eq!(result.resolved, resolved); + assert_eq!(result.redacted, format!("/bot[CREDENTIAL]{suffix}")); + } + let encoded = format!("/bot{}/getMe", fully_percent_encoded(token)); + assert!(rewrite_target_for_eval(&encoded, &resolver).is_ok()); + } + + #[test] + fn path_subtree_template_keeps_the_credential_in_its_declared_slot() { + let resolver = placement_resolver(CredentialPlacement::PathTemplate( + "/bot{credential}/**".into(), + )); + let token = "openshell:resolve:env:v1_TOKEN"; + let forged_slot = "{credential}"; + let encoded_forged_slot = "%7Bcredential%7D"; + for target in [ + // The fixed text around the slot must match. + format!("/other{token}/getMe"), + format!("/prefix/bot{token}/getMe"), + // The slot ends at a path boundary, so a sibling segment is not a descendant. + format!("/bot{token}.suffix/getMe"), + format!("/bot{token}-extra/getMe"), + // One occurrence only, even when the second one is in the wildcard tail. + format!("/bot{token}/echo/{token}"), + // Literal `{credential}` text is not a credential slot. The real token + // would otherwise land in the wildcard tail. + format!("/bot{forged_slot}/echo/{token}"), + format!("/bot{encoded_forged_slot}/echo/{token}"), + // The credential may not appear where the template declares no slot. + format!("/{token}/getMe"), + ] { + assert!( + rewrite_target_for_eval(&target, &resolver) + .unwrap_err() + .is_placement_mismatch(), + "{target} must be a placement mismatch" + ); + } + } + + #[test] + fn path_subtree_template_rejects_dot_segments_in_the_wildcard_tail() { + let resolver = placement_resolver(CredentialPlacement::PathTemplate( + "/bot{credential}/**".into(), + )); + let token = "openshell:resolve:env:v1_TOKEN"; + for target in [ + format!("/bot{token}/../admin"), + format!("/bot{token}/a/./b"), + format!("/bot{token}/%2e%2e/admin"), + ] { + assert!( + rewrite_target_for_eval(&target, &resolver) + .unwrap_err() + .is_placement_mismatch(), + "{target} must be a placement mismatch" + ); + } + // A dot inside a segment name is an ordinary character. + assert!(rewrite_target_for_eval(&format!("/bot{token}/file..txt"), &resolver).is_ok()); + } + + #[test] + fn path_subtree_template_does_not_widen_other_credentials() { + let (_, resolver) = SecretResolver::from_provider_env_for_revision( + HashMap::from([ + ("TOKEN".to_string(), "secret-value".to_string()), + ("OTHER".to_string(), "other-value".to_string()), + ]), + HashMap::new(), + 1, + ); + let resolver = resolver.unwrap().with_placements(HashMap::from([ + ( + "TOKEN".to_string(), + CredentialPlacement::PathTemplate("/bot{credential}/**".into()), + ), + ( + "OTHER".to_string(), + CredentialPlacement::Header("x-other".into()), + ), + ])); + // OTHER declares a header, so the TOKEN wildcard tail cannot carry it. + assert!( + rewrite_target_for_eval( + "/botopenshell:resolve:env:v1_TOKEN/openshell:resolve:env:v1_OTHER", + &resolver + ) + .unwrap_err() + .is_placement_mismatch() + ); + } + + #[test] + fn path_template_grammar_recognizes_only_a_terminal_subtree_marker() { + let exact = PathTemplate::parse("/bot{credential}/sendMessage").unwrap(); + assert!(!exact.is_subtree()); + + let subtree = PathTemplate::parse("/bot{credential}/**").unwrap(); + assert!(subtree.is_subtree()); + assert!( + PathTemplate::parse("/{credential}/**") + .unwrap() + .is_subtree() + ); + + // `*` elsewhere, and a single `*`, are ordinary characters. + for template in [ + "/bot{credential}/*", + "/bot{credential}/**/x", + "/*/{credential}", + "/bot{credential}**", + ] { + assert!( + !PathTemplate::parse(template).unwrap().is_subtree(), + "{template}" + ); + } + + // The slot appears exactly once and the path stays a bare path. + for template in [ + "/bot/**", + "/bot{credential}/{credential}/**", + "bot{credential}/**", + "/bot{credential}/**?x=1", + "/bot{credential}/**#x", + "/bot{credential}/\n**", + "", + ] { + assert!(PathTemplate::parse(template).is_none(), "{template:?}"); + } + } + + #[test] + fn literal_star_in_an_exact_path_template_stays_literal() { + // Only a terminal `/**` is a wildcard. Every other template keeps its + // exact meaning, including the `*` characters it already contained. + for template in [ + "/bot{credential}/*", + "/bot{credential}/a*", + "/*/{credential}", + ] { + let resolver = placement_resolver(CredentialPlacement::PathTemplate(template.into())); + let token = "openshell:resolve:env:v1_TOKEN"; + let literal = template.replace("{credential}", token); + assert!( + rewrite_target_for_eval(&literal, &resolver).is_ok(), + "{template} must still match itself literally" + ); + assert!( + rewrite_target_for_eval(&format!("/bot{token}/sendMessage"), &resolver) + .unwrap_err() + .is_placement_mismatch(), + "{template} must not match other paths" + ); + } + } + fn fully_percent_encoded(marker: &str) -> String { const HEX: &[u8; 16] = b"0123456789ABCDEF"; let mut encoded = String::with_capacity(marker.len() * 3); diff --git a/crates/openshell-supervisor-network/src/l7/rest.rs b/crates/openshell-supervisor-network/src/l7/rest.rs index caec858eaf..12fa0b4aff 100644 --- a/crates/openshell-supervisor-network/src/l7/rest.rs +++ b/crates/openshell-supervisor-network/src/l7/rest.rs @@ -4248,6 +4248,8 @@ fn is_benign_close(err: &std::io::Error) -> bool { reason = "Test code: test fixtures and explicit value-shape assertions are idiomatic in tests." )] mod tests { + mod path_credentials; + use super::*; use crate::opa::OpaEngine; use flate2::{Compress, Compression, Decompress, FlushCompress, FlushDecompress, Status}; @@ -12029,6 +12031,85 @@ mod tests { assert!(!forwarded.contains("openshell:resolve:env:")); } + #[tokio::test] + async fn relay_injects_subtree_path_credential_for_every_method() { + let (child_env, resolver) = placed_test_resolver( + [( + "TELEGRAM_TOKEN".to_string(), + "123456:ABC-DEF1234ghIkl".to_string(), + )] + .into_iter() + .collect(), + "api.telegram.org", + &[("TELEGRAM_TOKEN", "path", "/bot{credential}/**")], + ); + let placeholder = child_env.get("TELEGRAM_TOKEN").unwrap(); + + for method in ["sendMessage", "getUpdates", "answerCallbackQuery"] { + let raw = format!( + "POST /bot{placeholder}/{method} HTTP/1.1\r\n\ + Host: api.telegram.org\r\n\ + Content-Length: 2\r\n\r\n{{}}" + ); + let forwarded = relay_and_capture( + raw.into_bytes(), + BodyLength::ContentLength(2), + resolver.as_ref(), + ) + .await + .expect("every method below the credential prefix should relay"); + + assert!( + forwarded.contains(&format!( + "POST /bot123456:ABC-DEF1234ghIkl/{method} HTTP/1.1" + )), + "Upstream should see the real token for {method}, got: {forwarded}" + ); + assert!(!forwarded.contains("openshell:resolve:env:")); + } + } + + #[tokio::test] + async fn relay_rejects_subtree_path_credential_outside_the_declared_slot() { + let (child_env, resolver) = placed_test_resolver( + [( + "TELEGRAM_TOKEN".to_string(), + "123456:ABC-DEF1234ghIkl".to_string(), + )] + .into_iter() + .collect(), + "api.telegram.org", + &[("TELEGRAM_TOKEN", "path", "/bot{credential}/**")], + ); + let placeholder = child_env.get("TELEGRAM_TOKEN").unwrap(); + + for target in [ + // The client wrote `{credential}` itself, so the real token would + // land in the wildcard tail. + format!("/bot%7Bcredential%7D/echo/{placeholder}"), + format!("/bot{placeholder}/echo/{placeholder}"), + format!("/echo/bot{placeholder}/getMe"), + ] { + let raw = format!( + "POST {target} HTTP/1.1\r\n\ + Host: api.telegram.org\r\n\ + Content-Length: 2\r\n\r\n{{}}" + ); + let error = relay_and_capture( + raw.into_bytes(), + BodyLength::ContentLength(2), + resolver.as_ref(), + ) + .await + .expect_err("a credential outside its declared slot must not relay"); + + assert!( + !format!("{error:?}").contains("123456:ABC-DEF1234ghIkl"), + "the rejection must not carry the credential" + ); + } + } + #[tokio::test] async fn relay_injects_url_path_credential_standalone_segment() { let (child_env, resolver) = placed_test_resolver( diff --git a/crates/openshell-supervisor-network/src/l7/rest/tests/path_credentials.rs b/crates/openshell-supervisor-network/src/l7/rest/tests/path_credentials.rs new file mode 100644 index 0000000000..a6c557b44f --- /dev/null +++ b/crates/openshell-supervisor-network/src/l7/rest/tests/path_credentials.rs @@ -0,0 +1,154 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +use super::*; +use openshell_core::net::{connect_tcp_nodelay_best_effort, set_tcp_nodelay_best_effort}; +use tokio::net::{TcpListener, TcpStream}; +use tokio::sync::oneshot; +use tokio::task::JoinSet; + +async fn respond_json(stream: &mut TcpStream, body: &str) { + let response = format!( + "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len(), + ); + stream.write_all(response.as_bytes()).await.unwrap(); + stream.shutdown().await.unwrap(); +} + +#[tokio::test] +async fn subtree_path_credential_sends_while_the_same_client_long_polls() { + openshell_crypto::tls::ensure_default_provider(); + // Without subtree matching, getUpdates is rejected before reaching upstream. + // Serializing requests by credential would instead block sendMessage until + // the poll is released, and fail the bounded send below. + tokio::time::timeout(std::time::Duration::from_secs(10), async { + const MESSAGE_BODY: &str = r#"{"chat_id":42,"text":"hello"}"#; + const SEND_RESPONSE: &str = r#"{"ok":true,"result":{"message_id":1}}"#; + const POLL_RESPONSE: &str = r#"{"ok":true,"result":[]}"#; + + let (child_env, resolver) = placed_test_resolver( + HashMap::from([("TELEGRAM_TOKEN".into(), "123456:synthetic".into())]), + "api.telegram.org", + &[("TELEGRAM_TOKEN", "path", "/bot{credential}/**")], + ); + let resolver = Arc::new(resolver.unwrap()); + let upstream_listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let upstream_address = upstream_listener.local_addr().unwrap(); + let proxy_listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let proxy_address = proxy_listener.local_addr().unwrap(); + let (poll_started_tx, poll_started_rx) = oneshot::channel(); + let (release_poll_tx, release_poll_rx) = oneshot::channel(); + + // Only the external Bot API is simulated; request parsing, placement, + // substitution, body forwarding, and response relay use production code. + let upstream = tokio::spawn(async move { + let (mut poll, _) = upstream_listener.accept().await.unwrap(); + set_tcp_nodelay_best_effort(&poll); + let request = RestProvider::default() + .parse_request(&mut poll) + .await + .unwrap() + .unwrap(); + assert!( + String::from_utf8_lossy(&request.raw_header) + .starts_with("GET /bot123456:synthetic/getUpdates?timeout=30 HTTP/1.1\r\n") + ); + poll_started_tx.send(()).unwrap(); + + let (mut send, _) = upstream_listener.accept().await.unwrap(); + set_tcp_nodelay_best_effort(&send); + let request = RestProvider::default() + .parse_request(&mut send) + .await + .unwrap() + .unwrap(); + assert!( + String::from_utf8_lossy(&request.raw_header) + .starts_with("POST /bot123456:synthetic/sendMessage HTTP/1.1\r\n") + ); + let header_end = request + .raw_header + .windows(4) + .position(|window| window == b"\r\n\r\n") + .unwrap() + + 4; + let mut body = request.raw_header[header_end..].to_vec(); + let received = body.len(); + assert!(received <= MESSAGE_BODY.len()); + body.resize(MESSAGE_BODY.len(), 0); + send.read_exact(&mut body[received..]).await.unwrap(); + assert_eq!(body, MESSAGE_BODY.as_bytes()); + respond_json(&mut send, SEND_RESPONSE).await; + + release_poll_rx.await.unwrap(); + respond_json(&mut poll, POLL_RESPONSE).await; + }); + let proxy = tokio::spawn(async move { + let mut requests = JoinSet::new(); + for _ in 0..2 { + let (mut client, _) = proxy_listener.accept().await.unwrap(); + set_tcp_nodelay_best_effort(&client); + let resolver = Arc::clone(&resolver); + requests.spawn(async move { + let request = RestProvider::default() + .parse_request(&mut client) + .await + .unwrap() + .unwrap(); + let mut upstream = connect_tcp_nodelay_best_effort(upstream_address) + .await + .unwrap(); + relay_http_request_with_resolver( + &request, + &mut client, + &mut upstream, + Some(&resolver), + ) + .await + .expect("relay must permit both methods with the same credential"); + }); + } + while let Some(result) = requests.join_next().await { + result.unwrap(); + } + }); + + let client = reqwest::Client::builder() + .no_proxy() + .http1_only() + .build() + .unwrap(); + let base_url = format!("http://{proxy_address}/bot{}", child_env["TELEGRAM_TOKEN"]); + // Client::clone shares the same client and its connection pool. + let poll_client = client.clone(); + let poll_url = format!("{base_url}/getUpdates?timeout=30"); + let poll = tokio::spawn(async move { poll_client.get(poll_url).send().await.unwrap() }); + poll_started_rx + .await + .expect("upstream must receive the credential-bearing long poll"); + + let sent = client + .post(format!("{base_url}/sendMessage")) + .header("content-type", "application/json") + .body(MESSAGE_BODY) + .send() + .await + .unwrap(); + assert_eq!(sent.status(), reqwest::StatusCode::OK); + assert_eq!(sent.text().await.unwrap(), SEND_RESPONSE); + assert!( + !poll.is_finished(), + "send must finish before the poll returns" + ); + + release_poll_tx.send(()).unwrap(); + let updates = poll.await.unwrap(); + assert_eq!(updates.status(), reqwest::StatusCode::OK); + assert_eq!(updates.text().await.unwrap(), POLL_RESPONSE); + upstream.await.unwrap(); + proxy.await.unwrap(); + }) + .await + .expect("sending must finish without waiting for the pending long poll"); +} diff --git a/crates/openshell-supervisor-network/src/proxy.rs b/crates/openshell-supervisor-network/src/proxy.rs index be255a423b..9069fc7ef2 100644 --- a/crates/openshell-supervisor-network/src/proxy.rs +++ b/crates/openshell-supervisor-network/src/proxy.rs @@ -14993,6 +14993,79 @@ network_policies: assert!(!result_str.contains("openshell:resolve:env:ANTHROPIC_API_KEY")); } + #[test] + fn forward_rewrite_resolves_a_subtree_path_credential_only_in_its_slot() { + use openshell_core::proto::{ + ProviderProfileCredential, StaticCredentialBinding, StaticCredentialEndpointBinding, + }; + use openshell_core::provider_credentials::STATIC_CREDENTIAL_METADATA_PREFIX; + let state = ProviderCredentialState::from_bound_environment( + 1, + TestHashMap::from([("BOT_TOKEN".into(), "123456:synthetic".into())]), + TestHashMap::new(), + TestHashMap::from([( + format!("{STATIC_CREDENTIAL_METADATA_PREFIX}BOT_TOKEN"), + ProviderProfileCredential { + env_vars: vec!["BOT_TOKEN".into()], + auth_style: "path".into(), + path_template: "/bot{credential}/**".into(), + ..Default::default() + }, + )]), + TestHashMap::from([( + "BOT_TOKEN".into(), + StaticCredentialBinding { + credential_identity: "provider:BOT_TOKEN".into(), + workload_credential_handle: String::new(), + endpoints: vec![StaticCredentialEndpointBinding { + host: "bot-api.example.com".into(), + port: 80, + path: "/**".into(), + }], + }, + )]), + Vec::new(), + ) + .unwrap(); + let placeholder = state.snapshot().child_env["BOT_TOKEN"].clone(); + let resolver = state + .resolver_for_endpoint("bot-api.example.com", 80, "/") + .unwrap(); + + for method in ["sendMessage", "getUpdates"] { + let path = format!("/bot{placeholder}/{method}"); + let raw = format!( + "POST http://bot-api.example.com{path} HTTP/1.1\r\nHost: bot-api.example.com\r\n\r\n" + ); + let rewritten = rewrite_forward_request( + raw.as_bytes(), + raw.len(), + &path, + "bot-api.example.com", + Some(&resolver), + ) + .expect("every method below the credential prefix should resolve"); + assert!( + String::from_utf8_lossy(&rewritten) + .starts_with(&format!("POST /bot123456:synthetic/{method} HTTP/1.1\r\n")) + ); + } + + let moved = format!("/echo/bot{placeholder}/getMe"); + let raw = format!( + "POST http://bot-api.example.com{moved} HTTP/1.1\r\nHost: bot-api.example.com\r\n\r\n" + ); + let error = rewrite_forward_request( + raw.as_bytes(), + raw.len(), + &moved, + "bot-api.example.com", + Some(&resolver), + ) + .expect_err("a credential outside its declared slot must not resolve"); + assert!(error.is_placement_mismatch()); + } + #[tokio::test] async fn forward_initial_body_is_classified_separately_from_auth_headers() { use openshell_core::proto::{StaticCredentialBinding, StaticCredentialEndpointBinding}; diff --git a/docs/how-it-works/providers/overview.mdx b/docs/how-it-works/providers/overview.mdx index 5cb1f82e94..7af0c82f88 100644 --- a/docs/how-it-works/providers/overview.mdx +++ b/docs/how-it-works/providers/overview.mdx @@ -495,7 +495,7 @@ declaration. Older supervisors keep their previous behavior. | Declared header value | Agent reads `$API_KEY` from env and places it in the declared header. | `Authorization: Bearer ` | | Header value (Basic auth) | Agent base64-encodes `user:` in an `Authorization: Basic` header. The proxy decodes, resolves, and re-encodes. | `Authorization: Basic ` | | Declared query parameter value | Agent uses the profile's `query_param`. | `GET /api?key=` | -| Declared URL path slot | Agent uses the profile's `path_template`, including concatenated patterns. | `POST /bot/sendMessage` | +| Declared URL path slot | Agent uses the profile's `path_template`, including concatenated patterns. A terminal `/**` also accepts every path below the slot. | `POST /bot/sendMessage` | | AWS SigV4 signing | An endpoint configures `credential_signing`, and the proxy signs with the endpoint-bound AWS credentials. | `credential_signing: sigv4` | The proxy does not rewrite cookies, response content, unsupported request diff --git a/docs/how-it-works/providers/profiles.mdx b/docs/how-it-works/providers/profiles.mdx index 39799e0f45..ea98816ddb 100644 --- a/docs/how-it-works/providers/profiles.mdx +++ b/docs/how-it-works/providers/profiles.mdx @@ -425,7 +425,8 @@ credentials: auth_style: bearer header_name: authorization # For auth_style: query, set query_param: api_key instead. - # For auth_style: path, set path_template: /v1/{credential}/resources instead. + # For auth_style: path, set path_template: /v1/{credential}/resources instead, + # or /v1/{credential}/** to match every path below the credential's segment. refresh: # Accepted values: @@ -531,7 +532,7 @@ import for compatibility. `category` supplies the `CATEGORY` column in `openshell profile list`. Use one of the values in the category enum. -`credentials` declares the credential names, environment variables, auth metadata, optional refresh metadata, and optional dynamic token grant metadata for the provider type. The `auth_style` field accepts `basic`, `bearer`, `header`, `query`, or `path`. When `auth_style` is `path`, set `path_template` to a URL path containing the `{credential}` placeholder exactly once (for example, `/v1/{credential}/resources`). Static credentials are exposed as placeholder environment variables and resolved in outbound HTTP requests only at their binding endpoints. Every static credential environment key receives the full profile endpoint set when the profile defines endpoints. An endpointless profile requires explicit sandbox policy bindings for each attached provider instance. Dynamic token grants are resolved by the sandbox proxy on demand for matching profile endpoints and support `bearer` or `header` placement. Credential environment variable names must not use the reserved `v_` prefix, such as `v10_GITHUB_TOKEN`, because OpenShell uses that namespace for revision-scoped placeholders. +`credentials` declares the credential names, environment variables, auth metadata, optional refresh metadata, and optional dynamic token grant metadata for the provider type. The `auth_style` field accepts `basic`, `bearer`, `header`, `query`, or `path`. When `auth_style` is `path`, set `path_template` to a URL path containing the `{credential}` placeholder exactly once (for example, `/v1/{credential}/resources`). A template matches only that path. End it with `/**` to also match every path below the slot's segment, so one credential works for every method of an API that keeps its token in a path prefix. For example, `/bot{credential}/**` matches `/bot/sendMessage` and `/bot/getUpdates`, but not `/other/bot/sendMessage` or a request that repeats the placeholder. Only a terminal `/**` is a wildcard; a `*` anywhere else is an ordinary character. Static credentials are exposed as placeholder environment variables and resolved in outbound HTTP requests only at their binding endpoints. Every static credential environment key receives the full profile endpoint set when the profile defines endpoints. An endpointless profile requires explicit sandbox policy bindings for each attached provider instance. Dynamic token grants are resolved by the sandbox proxy on demand for matching profile endpoints and support `bearer` or `header` placement. Credential environment variable names must not use the reserved `v_` prefix, such as `v10_GITHUB_TOKEN`, because OpenShell uses that namespace for revision-scoped placeholders. Credential names must not contain control characters such as tabs or newlines. Dynamic token-grant endpoint and audience-override selectors have the same restriction. diff --git a/skills/openshell-cli/SKILL.md b/skills/openshell-cli/SKILL.md index 1265b8a610..ff94c001ff 100644 --- a/skills/openshell-cli/SKILL.md +++ b/skills/openshell-cli/SKILL.md @@ -161,7 +161,11 @@ slots, update the imported profile with explicit placement and upgrade the gateway before the supervisor. Older gateways cannot forward placement metadata; older supervisors retain their previous behavior. Updating example YAML does not update an imported profile. Check provider readiness after changing placement and -launch a new process if retained references were revoked. +launch a new process if retained references were revoked. For path-based APIs +that use one token across multiple methods, a terminal `/**` in `path_template` +permits the fixed path and its descendants, such as `/bot{credential}/**`. +Templates without that suffix still match exactly, and endpoint bindings remain +independently enforced. When an inspected request receives `request_authority_mismatch`, compare its HTTP authority with the CONNECT tunnel endpoint. The host and effective port