From 801ca0d0d1206a5886048a01262584c79bf33d60 Mon Sep 17 00:00:00 2001 From: ostepanian Date: Thu, 3 Sep 2026 19:34:18 +0000 Subject: [PATCH] Support trusted headers for remote exec WebSockets (#42606) ## What changed - Add `RemoteEnvironmentOptions` and `upsert_environment_with_options` so embedding hosts can attach trusted HTTP headers to remote exec-server WebSocket handshakes. - Preserve the headers across session reconnects while redacting them from debug output. - Reject invalid, duplicate, and WebSocket-controlled headers, and require `wss://` for non-loopback destinations. - Connect header-bearing loopback WebSockets directly, with DNS results restricted to loopback addresses. ## Testing - Cover header validation and redaction, delivery on initial connections and reconnects, and loopback destination enforcement. GitOrigin-RevId: f2e2b0456c8e33c13fd8ab4ee040a8b5c15e885d --- codex-rs/exec-server/src/client.rs | 6 + .../src/client/tests/network_policy_tests.rs | 2 + codex-rs/exec-server/src/client_api.rs | 5 + codex-rs/exec-server/src/client_transport.rs | 92 +++-- codex-rs/exec-server/src/environment.rs | 45 ++- .../src/environment/connect_options.rs | 115 ++++++ .../src/environment/connect_options_tests.rs | 328 ++++++++++++++++++ codex-rs/exec-server/src/environment_toml.rs | 3 + codex-rs/exec-server/src/lib.rs | 1 + codex-rs/websocket-client/src/dialer.rs | 40 ++- codex-rs/websocket-client/src/dialer_tests.rs | 29 ++ codex-rs/websocket-client/src/lib.rs | 58 ++++ codex-rs/websocket-client/src/lib_tests.rs | 34 ++ 13 files changed, 703 insertions(+), 55 deletions(-) create mode 100644 codex-rs/exec-server/src/environment/connect_options.rs create mode 100644 codex-rs/exec-server/src/environment/connect_options_tests.rs create mode 100644 codex-rs/websocket-client/src/lib_tests.rs diff --git a/codex-rs/exec-server/src/client.rs b/codex-rs/exec-server/src/client.rs index f33b21c137..918d4467c9 100644 --- a/codex-rs/exec-server/src/client.rs +++ b/codex-rs/exec-server/src/client.rs @@ -1724,6 +1724,7 @@ mod tests { use codex_utils_path_uri::PathUri; use futures::SinkExt; use futures::StreamExt; + use http::HeaderMap; use opentelemetry::trace::TracerProvider as _; use opentelemetry_sdk::trace::SdkTracerProvider; use pretty_assertions::assert_eq; @@ -2547,6 +2548,7 @@ mod tests { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ); @@ -2657,6 +2659,7 @@ mod tests { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ); @@ -2799,6 +2802,7 @@ mod tests { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ); @@ -2898,6 +2902,7 @@ mod tests { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ); @@ -2989,6 +2994,7 @@ mod tests { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ); diff --git a/codex-rs/exec-server/src/client/tests/network_policy_tests.rs b/codex-rs/exec-server/src/client/tests/network_policy_tests.rs index 5af5acf97f..1b3c20539a 100644 --- a/codex-rs/exec-server/src/client/tests/network_policy_tests.rs +++ b/codex-rs/exec-server/src/client/tests/network_policy_tests.rs @@ -14,6 +14,7 @@ use codex_network_proxy::NetworkPolicyDecider; use codex_network_proxy::NetworkPolicyRequest; use codex_network_proxy::NetworkProxyAuditMetadata; use codex_utils_path_uri::PathUri; +use http::HeaderMap; use opentelemetry::trace::TracerProvider as _; use opentelemetry_sdk::trace::InMemorySpanExporter; use opentelemetry_sdk::trace::SdkTracerProvider; @@ -430,6 +431,7 @@ async fn policy_requests_use_process_decider_and_cancel_on_unregister() { websocket_url, connect_timeout: Duration::from_secs(1), initialize_timeout: Duration::from_secs(1), + http_headers: HeaderMap::new(), }, HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault), ) diff --git a/codex-rs/exec-server/src/client_api.rs b/codex-rs/exec-server/src/client_api.rs index d07364c9ad..e870f12471 100644 --- a/codex-rs/exec-server/src/client_api.rs +++ b/codex-rs/exec-server/src/client_api.rs @@ -5,6 +5,7 @@ use std::time::Duration; use codex_http_client::HttpClientFactory; use futures::future::BoxFuture; +use http::HeaderMap; use tokio::sync::watch; use crate::ExecServerError; @@ -108,6 +109,7 @@ pub(crate) enum ExecServerTransportParams { websocket_url: String, connect_timeout: Duration, initialize_timeout: Duration, + http_headers: HeaderMap, }, NoiseRendezvous { provider: Arc, @@ -131,11 +133,13 @@ impl std::fmt::Debug for ExecServerTransportParams { websocket_url, connect_timeout, initialize_timeout, + .. } => f .debug_struct("WebSocketUrl") .field("websocket_url", websocket_url) .field("connect_timeout", connect_timeout) .field("initialize_timeout", initialize_timeout) + .field("http_headers", &"") .finish(), Self::NoiseRendezvous { .. } => { f.debug_struct("NoiseRendezvous").finish_non_exhaustive() @@ -158,6 +162,7 @@ impl ExecServerTransportParams { websocket_url, connect_timeout, initialize_timeout: DEFAULT_REMOTE_EXEC_SERVER_INITIALIZE_TIMEOUT, + http_headers: HeaderMap::new(), } } } diff --git a/codex-rs/exec-server/src/client_transport.rs b/codex-rs/exec-server/src/client_transport.rs index 766f2b0d32..0fd88bbbbc 100644 --- a/codex-rs/exec-server/src/client_transport.rs +++ b/codex-rs/exec-server/src/client_transport.rs @@ -19,6 +19,7 @@ use codex_protocol::shell_environment::scrub_non_inheritable_env_vars; use codex_utils_rustls_provider::ensure_rustls_crypto_provider; use codex_websocket_client::WebSocketConnector; use codex_websocket_client::WebSocketTlsMode; +use http::HeaderMap; use crate::ExecServerClient; use crate::ExecServerError; @@ -101,7 +102,10 @@ impl ReconnectAttempt { #[derive(Clone)] pub(crate) enum ExecServerReconnectStrategy { Accepted(AcceptedConnectionSource), - WebSocket(RemoteExecServerConnectArgs), + WebSocket { + args: RemoteExecServerConnectArgs, + http_headers: HeaderMap, + }, NoiseRendezvous { // The executor that created the session, not the latest recovery lookup. executor_public_key: crate::NoiseChannelPublicKey, @@ -121,10 +125,11 @@ impl ExecServerReconnectStrategy { ) -> Result { match self { Self::Accepted(source) => source.next_connection(session_id).await, - Self::WebSocket(args) => { + Self::WebSocket { args, http_headers } => { let mut args = args.clone(); args.resume_session_id = Some(session_id.to_string()); - let connection = ExecServerClient::open_websocket_connection(&args).await?; + let connection = + ExecServerClient::open_websocket_connection(&args, http_headers).await?; Ok(ReconnectAttempt::new(connection, args.into())) } Self::NoiseRendezvous { @@ -190,7 +195,7 @@ impl ExecServerClient { provisioning_result.map_err(ExecServerError::ProvisioningFailed)?; } - let (websocket_url, connect_timeout, initialize_timeout) = match transport_params { + let websocket = match transport_params { ExecServerTransportParams::Deferred(_) => { return Err(ExecServerError::Protocol( "nested deferred exec-server transports are unsupported".to_string(), @@ -200,7 +205,13 @@ impl ExecServerClient { websocket_url, connect_timeout, initialize_timeout, - } => (websocket_url, connect_timeout, initialize_timeout), + http_headers, + } => ( + websocket_url, + connect_timeout, + initialize_timeout, + http_headers, + ), ExecServerTransportParams::NoiseRendezvous { provider, identity } => { let (connection, options, executor_public_key) = Self::open_initial_noise_rendezvous_connection( @@ -234,14 +245,18 @@ impl ExecServerClient { .await; } }; - Self::connect_websocket(RemoteExecServerConnectArgs { - websocket_url, - client_name: ENVIRONMENT_CLIENT_NAME.to_string(), - connect_timeout, - initialize_timeout, - resume_session_id: None, - http_client_factory, - }) + let (websocket_url, connect_timeout, initialize_timeout, http_headers) = websocket; + Self::connect_websocket_with_headers( + RemoteExecServerConnectArgs { + websocket_url, + client_name: ENVIRONMENT_CLIENT_NAME.to_string(), + connect_timeout, + initialize_timeout, + resume_session_id: None, + http_client_factory, + }, + http_headers, + ) .await } @@ -339,50 +354,63 @@ impl ExecServerClient { pub async fn connect_websocket( args: RemoteExecServerConnectArgs, ) -> Result { - let connection = Self::open_websocket_connection(&args).await?; + Self::connect_websocket_with_headers(args, HeaderMap::new()).await + } + + async fn connect_websocket_with_headers( + args: RemoteExecServerConnectArgs, + http_headers: HeaderMap, + ) -> Result { + let connection = Self::open_websocket_connection(&args, &http_headers).await?; let options = args.clone().into(); Self::connect_with_recovery( connection, options, - Some(ExecServerReconnectStrategy::WebSocket(args)), + Some(ExecServerReconnectStrategy::WebSocket { args, http_headers }), ) .await } pub(crate) async fn open_websocket_connection( args: &RemoteExecServerConnectArgs, + http_headers: &HeaderMap, ) -> Result { ensure_rustls_crypto_provider(); let websocket_url = args.websocket_url.clone(); let connect_timeout = args.connect_timeout; - let request = websocket_url + let mut request = websocket_url .as_str() .into_client_request() .map_err(|source| ExecServerError::WebSocketConnect { url: websocket_url.clone(), source, })?; + request.headers_mut().extend(http_headers.clone()); let connector = WebSocketConnector::new_with_tls_mode( &args.http_client_factory, WebSocketTlsMode::TungsteniteDefault, ) .map_err(|error| ExecServerError::WebSocketConfiguration(error.to_string()))?; - let (stream, _) = timeout( - connect_timeout, - connector.connect( - request, - tokio_tungstenite::tungstenite::protocol::WebSocketConfig::default(), - ), - ) - .await - .map_err(|_| ExecServerError::WebSocketConnectTimeout { - url: websocket_url.clone(), - timeout: connect_timeout, - })? - .map_err(|source| ExecServerError::WebSocketConnect { - url: websocket_url.clone(), - source, - })?; + let websocket_config = tokio_tungstenite::tungstenite::protocol::WebSocketConfig::default(); + let connect = async { + if !http_headers.is_empty() && request.uri().scheme_str() == Some("ws") { + connector + .connect_loopback_direct(request, websocket_config) + .await + } else { + connector.connect(request, websocket_config).await + } + }; + let (stream, _) = timeout(connect_timeout, connect) + .await + .map_err(|_| ExecServerError::WebSocketConnectTimeout { + url: websocket_url.clone(), + timeout: connect_timeout, + })? + .map_err(|source| ExecServerError::WebSocketConnect { + url: websocket_url.clone(), + source, + })?; let connection_label = format!("exec-server websocket {websocket_url}"); let connection = if is_rendezvous_harness_url(&websocket_url) { diff --git a/codex-rs/exec-server/src/environment.rs b/codex-rs/exec-server/src/environment.rs index 96ea0de073..26b8825d72 100644 --- a/codex-rs/exec-server/src/environment.rs +++ b/codex-rs/exec-server/src/environment.rs @@ -1,3 +1,5 @@ +mod connect_options; + use std::collections::HashMap; use std::collections::HashSet; use std::sync::Arc; @@ -49,6 +51,8 @@ use tracing::instrument::WithSubscriber; #[path = "environment/accepted.rs"] mod accepted; +pub use connect_options::RemoteEnvironmentOptions; + pub const CODEX_EXEC_SERVER_URL_ENV_VAR: &str = "CODEX_EXEC_SERVER_URL"; pub const CODEX_EXEC_SERVER_NOISE_REGISTRY_URL_ENV_VAR: &str = "CODEX_EXEC_SERVER_NOISE_REGISTRY_URL"; @@ -466,13 +470,30 @@ impl EnvironmentManager { exec_server_url: String, connect_timeout: Option, ) -> Result<(), ExecServerError> { - validate_environment_id(&environment_id)?; - let exec_server_url = validate_remote_exec_server_url(exec_server_url)?; - let environment = Arc::new(Environment::remote_with_transport( - ExecServerTransportParams::websocket_url( + self.upsert_environment_with_options( + environment_id, + RemoteEnvironmentOptions { exec_server_url, - connect_timeout.unwrap_or(DEFAULT_REMOTE_EXEC_SERVER_CONNECT_TIMEOUT), - ), + connect_timeout, + http_headers: HashMap::new(), + }, + ) + } + + /// Adds or replaces a direct environment with trusted host-owned connection options. + /// + /// Invalid headers and WebSocket-controlled handshake headers are rejected + /// before the environment is registered. Valid headers are retained for + /// automatic reconnects without changing existing URL-only environment APIs. + pub fn upsert_environment_with_options( + &self, + environment_id: String, + options: RemoteEnvironmentOptions, + ) -> Result<(), ExecServerError> { + validate_environment_id(&environment_id)?; + let transport = options.into_transport_params()?; + let environment = Arc::new(Environment::remote_with_transport( + transport, self.local_runtime_paths.clone(), self.http_client_factory.clone(), )); @@ -591,18 +612,6 @@ fn validate_environment_id(environment_id: &str) -> Result<(), ExecServerError> Ok(()) } -fn validate_remote_exec_server_url(exec_server_url: String) -> Result { - let (exec_server_url, disabled) = normalize_exec_server_url(Some(exec_server_url)); - if disabled { - return Err(ExecServerError::Protocol( - "remote environment cannot use disabled exec-server url".to_string(), - )); - } - exec_server_url.ok_or_else(|| { - ExecServerError::Protocol("remote environment requires an exec-server url".to_string()) - }) -} - fn noise_environment_config_from_env() -> Result, ExecServerError> { noise_environment_config_from_values( diff --git a/codex-rs/exec-server/src/environment/connect_options.rs b/codex-rs/exec-server/src/environment/connect_options.rs new file mode 100644 index 0000000000..2fc3a15e6e --- /dev/null +++ b/codex-rs/exec-server/src/environment/connect_options.rs @@ -0,0 +1,115 @@ +//! Host-owned WebSocket connection options whose trusted headers remain private and redacted. + +use std::collections::HashMap; +use std::time::Duration; + +use http::HeaderMap; +use http::HeaderName; +use http::HeaderValue; + +use crate::ExecServerError; +use crate::client_api::DEFAULT_REMOTE_EXEC_SERVER_CONNECT_TIMEOUT; +use crate::client_api::DEFAULT_REMOTE_EXEC_SERVER_INITIALIZE_TIMEOUT; +use crate::client_api::ExecServerTransportParams; +use crate::environment_provider::normalize_exec_server_url; + +/// Host-owned connection settings for a named remote execution environment. +/// +/// Headers are sent only on the direct WebSocket upgrade request and subsequent +/// reconnects. The embedding host must derive them from trusted request or +/// session context; they are not exposed through the app-server protocol. +#[derive(Clone, Eq, PartialEq)] +pub struct RemoteEnvironmentOptions { + /// Direct `ws://` or `wss://` endpoint for the remote environment. + pub exec_server_url: String, + /// Optional connection timeout; the standard exec-server default applies when omitted. + pub connect_timeout: Option, + /// Additional trusted headers for every physical WebSocket connection. + pub http_headers: HashMap, +} + +impl std::fmt::Debug for RemoteEnvironmentOptions { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("RemoteEnvironmentOptions") + .field("exec_server_url", &self.exec_server_url) + .field("connect_timeout", &self.connect_timeout) + .field("http_headers", &"") + .finish() + } +} + +impl RemoteEnvironmentOptions { + pub(super) fn into_transport_params( + self, + ) -> Result { + let (exec_server_url, disabled) = normalize_exec_server_url(Some(self.exec_server_url)); + if disabled { + return Err(ExecServerError::Protocol( + "remote environment cannot use disabled exec-server url".to_string(), + )); + } + let exec_server_url = exec_server_url.ok_or_else(|| { + ExecServerError::Protocol("remote environment requires an exec-server url".to_string()) + })?; + + if !self.http_headers.is_empty() { + let url = url::Url::parse(&exec_server_url).map_err(|error| { + ExecServerError::Protocol(format!("invalid exec-server WebSocket URL: {error}")) + })?; + let is_loopback = match url.host() { + Some(url::Host::Domain(host)) => host.eq_ignore_ascii_case("localhost"), + Some(url::Host::Ipv4(address)) => address.is_loopback(), + Some(url::Host::Ipv6(address)) => address.is_loopback(), + None => false, + }; + if url.scheme() != "wss" && !is_loopback { + return Err(ExecServerError::Protocol( + "exec-server WebSocket headers require wss:// or a loopback destination" + .to_string(), + )); + } + } + + let mut http_headers = HeaderMap::with_capacity(self.http_headers.len()); + for (name, value) in self.http_headers { + let header_name = HeaderName::from_bytes(name.as_bytes()).map_err(|_| { + ExecServerError::Protocol(format!( + "invalid exec-server WebSocket header name `{name}`" + )) + })?; + if matches!( + header_name.as_str(), + "connection" | "content-length" | "host" | "transfer-encoding" | "upgrade" + ) || header_name.as_str().starts_with("sec-websocket-") + { + return Err(ExecServerError::Protocol(format!( + "exec-server WebSocket header `{header_name}` is controlled by the connection" + ))); + } + let header_value = HeaderValue::from_str(&value).map_err(|_| { + ExecServerError::Protocol(format!( + "invalid value for exec-server WebSocket header `{header_name}`" + )) + })?; + if http_headers.contains_key(&header_name) { + return Err(ExecServerError::Protocol(format!( + "duplicate exec-server WebSocket header `{header_name}`" + ))); + } + http_headers.insert(header_name, header_value); + } + + Ok(ExecServerTransportParams::WebSocketUrl { + websocket_url: exec_server_url, + connect_timeout: self + .connect_timeout + .unwrap_or(DEFAULT_REMOTE_EXEC_SERVER_CONNECT_TIMEOUT), + initialize_timeout: DEFAULT_REMOTE_EXEC_SERVER_INITIALIZE_TIMEOUT, + http_headers, + }) + } +} + +#[cfg(test)] +#[path = "connect_options_tests.rs"] +mod tests; diff --git a/codex-rs/exec-server/src/environment/connect_options_tests.rs b/codex-rs/exec-server/src/environment/connect_options_tests.rs new file mode 100644 index 0000000000..c1df5b2054 --- /dev/null +++ b/codex-rs/exec-server/src/environment/connect_options_tests.rs @@ -0,0 +1,328 @@ +use std::collections::HashMap; +use std::time::Duration; + +use codex_http_client::HttpClientFactory; +use codex_http_client::OutboundProxyPolicy; +use futures::SinkExt; +use futures::StreamExt; +use http::HeaderValue; +use pretty_assertions::assert_eq; +use tokio::net::TcpListener; +use tokio::net::TcpStream; +use tokio::sync::oneshot; +use tokio::time::timeout; +use tokio_tungstenite::WebSocketStream; +use tokio_tungstenite::accept_hdr_async; +use tokio_tungstenite::tungstenite::Message; +use tokio_tungstenite::tungstenite::handshake::server::Request; +use tokio_tungstenite::tungstenite::handshake::server::Response; + +use super::RemoteEnvironmentOptions; +use crate::EnvironmentManager; +use crate::InitializeParams; +use crate::InitializeResponse; +use crate::protocol::INITIALIZE_METHOD; +use crate::protocol::INITIALIZED_METHOD; +use crate::protocol::JSONRPCMessage; +use crate::protocol::JSONRPCResponse; + +#[test] +fn remote_environment_options_redact_header_values() { + let options = RemoteEnvironmentOptions { + exec_server_url: "wss://relay.example/environment".to_string(), + connect_timeout: Some(Duration::from_secs(5)), + http_headers: HashMap::from([( + "authorization".to_string(), + "Bearer secret-customer-token".to_string(), + )]), + }; + + let debug = format!("{options:?}"); + assert!(debug.contains("")); + assert!(!debug.contains("secret-customer-token")); +} + +#[test] +fn trusted_headers_require_tls_for_non_loopback_destinations() { + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + + let error = manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: "ws://relay.example/environment".to_string(), + connect_timeout: None, + http_headers: HashMap::from([( + "x-session-id".to_string(), + "customer-session".to_string(), + )]), + }, + ) + .expect_err("trusted headers must not be sent over an insecure remote connection"); + + assert_eq!( + error.to_string(), + "exec-server protocol error: exec-server WebSocket headers require wss:// or a loopback destination" + ); + assert!(manager.get_environment("customer-environment").is_none()); +} + +#[test] +fn duplicate_case_insensitive_websocket_headers_fail_before_registration() { + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + + let error = manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: "ws://127.0.0.1:8765".to_string(), + connect_timeout: None, + http_headers: HashMap::from([ + ("X-Session-Id".to_string(), "first-session".to_string()), + ("x-session-id".to_string(), "second-session".to_string()), + ]), + }, + ) + .expect_err("duplicate header names must fail regardless of case"); + + assert_eq!( + error.to_string(), + "exec-server protocol error: duplicate exec-server WebSocket header `x-session-id`" + ); + assert!(manager.get_environment("customer-environment").is_none()); +} + +#[test] +fn invalid_websocket_header_names_fail_before_registration() { + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + + let error = manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: "ws://127.0.0.1:8765".to_string(), + connect_timeout: None, + http_headers: HashMap::from([("bad header".to_string(), "value".to_string())]), + }, + ) + .expect_err("invalid header name should fail"); + + assert_eq!( + error.to_string(), + "exec-server protocol error: invalid exec-server WebSocket header name `bad header`" + ); + assert!(manager.get_environment("customer-environment").is_none()); +} + +#[test] +fn invalid_websocket_header_values_fail_before_registration() { + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + + let error = manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: "ws://127.0.0.1:8765".to_string(), + connect_timeout: None, + http_headers: HashMap::from([( + "x-session-id".to_string(), + "customer\nspoofed".to_string(), + )]), + }, + ) + .expect_err("invalid header value should fail"); + + assert_eq!( + error.to_string(), + "exec-server protocol error: invalid value for exec-server WebSocket header `x-session-id`" + ); + assert!(manager.get_environment("customer-environment").is_none()); +} + +#[test] +fn websocket_controlled_headers_fail_before_registration() { + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + + for header in ["host", "connection", "upgrade", "sec-websocket-key"] { + let error = manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: "ws://127.0.0.1:8765".to_string(), + connect_timeout: None, + http_headers: HashMap::from([(header.to_string(), "overridden".to_string())]), + }, + ) + .expect_err("connection-controlled header should fail"); + + assert_eq!( + error.to_string(), + format!( + "exec-server protocol error: exec-server WebSocket header `{header}` is controlled by the connection" + ) + ); + assert!(manager.get_environment("customer-environment").is_none()); + } +} + +#[tokio::test] +async fn trusted_headers_are_sent_on_initial_websocket_and_session_reconnect() { + let listener = TcpListener::bind("127.0.0.1:0") + .await + .expect("listener should bind"); + let websocket_url = format!( + "ws://{}", + listener.local_addr().expect("listener should have address") + ); + let (resumed_tx, resumed_rx) = oneshot::channel(); + let (finish_tx, finish_rx) = oneshot::channel(); + let server = tokio::spawn(async move { + let mut first = accept_routing_headers_websocket(&listener).await; + complete_websocket_initialize(&mut first, /*expected_resume_session_id*/ None).await; + first + .close(None) + .await + .expect("first websocket should close"); + + let mut resumed = accept_routing_headers_websocket(&listener).await; + complete_websocket_initialize(&mut resumed, Some("session-1")).await; + resumed_tx.send(()).expect("resume should signal"); + finish_rx.await.expect("test should finish"); + }); + + let manager = EnvironmentManager::without_environments(HttpClientFactory::new( + OutboundProxyPolicy::ReqwestDefault, + )); + manager + .upsert_environment_with_options( + "customer-environment".to_string(), + RemoteEnvironmentOptions { + exec_server_url: websocket_url, + connect_timeout: Some(Duration::from_secs(1)), + http_headers: HashMap::from([ + ( + "x-account-id".to_string(), + "customer-account-456".to_string(), + ), + ( + "x-session-id".to_string(), + "customer-session-123".to_string(), + ), + ( + "x-environment-id".to_string(), + "customer-environment-789".to_string(), + ), + ]), + }, + ) + .expect("environment with routing headers should register"); + + let environment = manager + .get_environment("customer-environment") + .expect("environment with routing headers should exist"); + environment + .wait_until_ready() + .await + .expect("environment with routing headers should initialize"); + timeout(Duration::from_secs(3), resumed_rx) + .await + .expect("routing-header session resume should not time out") + .expect("routing-header session resume should signal"); + + finish_tx.send(()).expect("test should finish"); + server.await.expect("server task should finish"); +} + +async fn accept_routing_headers_websocket(listener: &TcpListener) -> WebSocketStream { + let (stream, _) = listener.accept().await.expect("listener should accept"); + accept_hdr_async(stream, |request: &Request, response: Response| { + assert_eq!( + request.headers().get("x-account-id"), + Some(&HeaderValue::from_static("customer-account-456")) + ); + assert_eq!( + request.headers().get("x-session-id"), + Some(&HeaderValue::from_static("customer-session-123")) + ); + assert_eq!( + request.headers().get("x-environment-id"), + Some(&HeaderValue::from_static("customer-environment-789")) + ); + Ok(response) + }) + .await + .expect("routing-header websocket handshake should succeed") +} + +async fn complete_websocket_initialize( + websocket: &mut WebSocketStream, + expected_resume_session_id: Option<&str>, +) { + let message = websocket + .next() + .await + .expect("initialize request should arrive") + .expect("initialize websocket message should succeed"); + let Message::Text(encoded) = message else { + panic!("expected initialize text message"); + }; + let JSONRPCMessage::Request(request) = + serde_json::from_str::(&encoded).expect("initialize request should parse") + else { + panic!("expected initialize request"); + }; + assert_eq!(request.method, INITIALIZE_METHOD); + let params: InitializeParams = serde_json::from_value( + request + .params + .expect("initialize request should contain parameters"), + ) + .expect("initialize parameters should parse"); + assert_eq!( + params.resume_session_id.as_deref(), + expected_resume_session_id + ); + + let response = JSONRPCMessage::Response(JSONRPCResponse { + id: request.id, + result: serde_json::to_value(InitializeResponse { + session_id: "session-1".to_string(), + environment_info: None, + }) + .expect("initialize response should serialize"), + }); + websocket + .send(Message::Text( + serde_json::to_string(&response) + .expect("initialize response should encode") + .into(), + )) + .await + .expect("initialize response should send"); + + let message = websocket + .next() + .await + .expect("initialized notification should arrive") + .expect("initialized websocket message should succeed"); + let Message::Text(encoded) = message else { + panic!("expected initialized text message"); + }; + let JSONRPCMessage::Notification(notification) = + serde_json::from_str::(&encoded) + .expect("initialized notification should parse") + else { + panic!("expected initialized notification"); + }; + assert_eq!(notification.method, INITIALIZED_METHOD); +} diff --git a/codex-rs/exec-server/src/environment_toml.rs b/codex-rs/exec-server/src/environment_toml.rs index e754bce01a..e86c956fdf 100644 --- a/codex-rs/exec-server/src/environment_toml.rs +++ b/codex-rs/exec-server/src/environment_toml.rs @@ -4,6 +4,7 @@ use std::path::Path; use std::path::PathBuf; use std::time::Duration; +use http::HeaderMap; use serde::Deserialize; use tokio_tungstenite::tungstenite::client::IntoClientRequest; @@ -144,6 +145,7 @@ fn parse_environment_toml( websocket_url: url, connect_timeout, initialize_timeout, + http_headers: HeaderMap::new(), } } (None, Some(program)) => { @@ -620,6 +622,7 @@ mod tests { websocket_url, connect_timeout, initialize_timeout, + .. } = &provider.environments[0].1 else { panic!("expected websocket transport"); diff --git a/codex-rs/exec-server/src/lib.rs b/codex-rs/exec-server/src/lib.rs index aa61d220f2..36bd1cfdd1 100644 --- a/codex-rs/exec-server/src/lib.rs +++ b/codex-rs/exec-server/src/lib.rs @@ -99,6 +99,7 @@ pub use environment::EnvironmentReadyInfo; pub use environment::LOCAL_ENVIRONMENT_ID; pub use environment::MAX_SELECTED_CAPABILITY_ROOTS; pub use environment::REMOTE_ENVIRONMENT_ID; +pub use environment::RemoteEnvironmentOptions; pub use environment_bootstrap::PreparedEnvironmentManager; pub use environment_provider::DefaultEnvironmentProvider; pub use environment_provider::EnvironmentProvider; diff --git a/codex-rs/websocket-client/src/dialer.rs b/codex-rs/websocket-client/src/dialer.rs index 53d5b763b5..680b144aeb 100644 --- a/codex-rs/websocket-client/src/dialer.rs +++ b/codex-rs/websocket-client/src/dialer.rs @@ -39,6 +39,7 @@ pub(crate) async fn connect( tls_config: Option>, proxy_route: OutboundProxyRoute, tcp_nodelay: TcpNodelay, + loopback_direct: bool, ) -> Result<(ConnectionInner, Response), WebSocketError> { let disable_nagle = tcp_nodelay == TcpNodelay::Enabled; let proxy_url = match proxy_route { @@ -87,11 +88,14 @@ pub(crate) async fn connect( None => { let host = websocket_host(&request)?; let port = websocket_port(&request)?; - Box::new( - connect_tcp(host_port(host, port), tcp_nodelay) - .await - .map_err(WebSocketError::Io)?, - ) + let address = host_port(host, port); + let stream = if loopback_direct { + connect_loopback_tcp(address, tcp_nodelay).await + } else { + connect_tcp(address, tcp_nodelay).await + } + .map_err(WebSocketError::Io)?; + Box::new(stream) } Some(url) => { let proxy = ProxyEndpoint::parse(&url)?; @@ -194,6 +198,18 @@ fn host_port(host: &str, port: u16) -> String { async fn connect_tcp(address: String, tcp_nodelay: TcpNodelay) -> io::Result { let addresses = tokio::net::lookup_host(address).await?.collect::>(); + connect_resolved_tcp(addresses, tcp_nodelay).await +} + +async fn connect_loopback_tcp(address: String, tcp_nodelay: TcpNodelay) -> io::Result { + let addresses = tokio::net::lookup_host(address).await?.collect::>(); + connect_resolved_tcp(loopback_addresses(addresses)?, tcp_nodelay).await +} + +async fn connect_resolved_tcp( + addresses: Vec, + tcp_nodelay: TcpNodelay, +) -> io::Result { let stream = connect_happy_eyeballs(addresses, TcpStream::connect).await?; if tcp_nodelay == TcpNodelay::Enabled { stream.set_nodelay(/*nodelay*/ true)?; @@ -201,6 +217,20 @@ async fn connect_tcp(address: String, tcp_nodelay: TcpNodelay) -> io::Result) -> io::Result> { + let loopback_addresses = addresses + .into_iter() + .filter(|address| address.ip().is_loopback()) + .collect::>(); + if loopback_addresses.is_empty() { + return Err(io::Error::new( + io::ErrorKind::PermissionDenied, + "direct WebSocket connections must resolve to a loopback address", + )); + } + Ok(loopback_addresses) +} + async fn connect_happy_eyeballs( addresses: Vec, mut connect: F, diff --git a/codex-rs/websocket-client/src/dialer_tests.rs b/codex-rs/websocket-client/src/dialer_tests.rs index b8c3574305..8a8112bce7 100644 --- a/codex-rs/websocket-client/src/dialer_tests.rs +++ b/codex-rs/websocket-client/src/dialer_tests.rs @@ -194,6 +194,7 @@ async fn direct_route_connects_secure_websocket() { Some(tls_config), OutboundProxyRoute::Direct, TcpNodelay::Enabled, + /*loopback_direct*/ false, ) .await .expect("direct websocket handshake should succeed"); @@ -281,6 +282,7 @@ async fn no_proxy_subprocess_probe() { no_proxy: Some(no_proxy), }, TcpNodelay::Enabled, + /*loopback_direct*/ false, ) .await .expect("websocket handshake should succeed"); @@ -357,6 +359,32 @@ async fn happy_eyeballs_does_not_wait_for_stalled_preferred_family() { assert_eq!(connected, reachable); } +#[test] +fn loopback_direct_drops_non_loopback_resolved_addresses() { + let loopback = "127.0.0.1:8080" + .parse::() + .expect("loopback address should parse"); + let remote = "192.0.2.1:8080" + .parse::() + .expect("remote address should parse"); + + assert_eq!( + loopback_addresses(vec![remote, loopback]).expect("loopback result should remain"), + vec![loopback] + ); +} + +#[test] +fn loopback_direct_rejects_localhost_resolution_without_loopback_addresses() { + let remote = "192.0.2.1:8080" + .parse::() + .expect("remote address should parse"); + + let error = loopback_addresses(vec![remote]) + .expect_err("localhost resolution without loopback addresses must fail"); + assert_eq!(error.kind(), std::io::ErrorKind::PermissionDenied); +} + #[tokio::test] async fn routed_tcp_connections_only_enable_nodelay_when_requested() { let listener = TcpListener::bind("127.0.0.1:0") @@ -613,6 +641,7 @@ async fn assert_proxy_tunnels_secure_websocket(proxy_tls: bool) { no_proxy: None, }, TcpNodelay::Enabled, + /*loopback_direct*/ false, ) .await .expect("proxied websocket handshake should succeed"); diff --git a/codex-rs/websocket-client/src/lib.rs b/codex-rs/websocket-client/src/lib.rs index cd6bdc2288..c709320ec3 100644 --- a/codex-rs/websocket-client/src/lib.rs +++ b/codex-rs/websocket-client/src/lib.rs @@ -2,6 +2,8 @@ mod dialer; +use std::io; +use std::net::IpAddr; use std::pin::Pin; use std::sync::Arc; use std::task::Context; @@ -9,6 +11,7 @@ use std::task::Poll; use codex_http_client::BuildCustomCaTransportError; use codex_http_client::HttpClientFactory; +use codex_http_client::OutboundProxyRoute; use codex_http_client::build_rustls_client_config_with_custom_ca; use futures::FutureExt; use futures::Sink; @@ -23,6 +26,7 @@ use tokio_tungstenite::tungstenite::Error as WebSocketError; use tokio_tungstenite::tungstenite::Message; use tokio_tungstenite::tungstenite::handshake::client::Request; use tokio_tungstenite::tungstenite::handshake::client::Response; +use tokio_tungstenite::tungstenite::http::Uri; use tokio_tungstenite::tungstenite::protocol::WebSocketConfig; /// Connects WebSockets using the outbound proxy policy resolved by application configuration. @@ -99,12 +103,48 @@ impl WebSocketConnector { .resolve_proxy_route_async(request.uri().to_string()) .await .map_err(WebSocketError::Io)?; + self.connect_with_route(request, config, proxy_route, /*loopback_direct*/ false) + .await + } + + /// Connects to a validated loopback destination without consulting proxy settings. + /// + /// This is limited to loopback destinations because bypassing configured proxy policy is + /// only safe for local connections. + pub async fn connect_loopback_direct( + &self, + request: Request, + config: WebSocketConfig, + ) -> Result<(WebSocketConnection, Response), WebSocketError> { + if !is_loopback_destination(request.uri()) { + return Err(WebSocketError::Io(io::Error::new( + io::ErrorKind::PermissionDenied, + "direct WebSocket connections require a loopback destination", + ))); + } + self.connect_with_route( + request, + config, + OutboundProxyRoute::Direct, + /*loopback_direct*/ true, + ) + .await + } + + async fn connect_with_route( + &self, + request: Request, + config: WebSocketConfig, + proxy_route: OutboundProxyRoute, + loopback_direct: bool, + ) -> Result<(WebSocketConnection, Response), WebSocketError> { let (inner, response) = dialer::connect( request, config, self.tls_config.clone(), proxy_route, self.tcp_nodelay, + loopback_direct, ) .boxed() .await?; @@ -112,6 +152,20 @@ impl WebSocketConnector { } } +fn is_loopback_destination(uri: &Uri) -> bool { + let Some(host) = uri.host() else { + return false; + }; + let ip_address = host + .strip_prefix('[') + .and_then(|host| host.strip_suffix(']')) + .unwrap_or(host); + host.eq_ignore_ascii_case("localhost") + || ip_address + .parse::() + .is_ok_and(|address| address.is_loopback()) +} + /// An established WebSocket independent of its direct, proxy, and TLS transport layers. /// /// This implements [`Stream`] and [`Sink`] so protocol clients can process Tungstenite messages @@ -181,3 +235,7 @@ pub(crate) enum ConnectionInner { pub(crate) trait AsyncIo: AsyncRead + AsyncWrite + Send + Unpin {} impl AsyncIo for T where T: AsyncRead + AsyncWrite + Send + Unpin {} + +#[cfg(test)] +#[path = "lib_tests.rs"] +mod tests; diff --git a/codex-rs/websocket-client/src/lib_tests.rs b/codex-rs/websocket-client/src/lib_tests.rs new file mode 100644 index 0000000000..c519671adb --- /dev/null +++ b/codex-rs/websocket-client/src/lib_tests.rs @@ -0,0 +1,34 @@ +use tokio_tungstenite::tungstenite::http::Uri; + +use super::is_loopback_destination; + +#[test] +fn recognizes_loopback_websocket_destinations() { + for destination in [ + "ws://localhost:8080", + "ws://LOCALHOST:8080", + "ws://127.0.0.1:8080", + "ws://[::1]:8080", + ] { + let uri = destination.parse::().unwrap(); + assert!( + is_loopback_destination(&uri), + "expected loopback destination: {destination}; parsed host: {:?}", + uri.host() + ); + } +} + +#[test] +fn rejects_non_loopback_websocket_destinations() { + for destination in [ + "ws://relay.example:8080", + "ws://192.0.2.1:8080", + "ws://[2001:db8::1]:8080", + "/missing-host", + ] { + assert!(!is_loopback_destination( + &destination.parse::().unwrap() + )); + } +}