Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Support trusted headers for remote exec WebSockets (#42606)

ostepanian801ca0d0d120
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<dyn NoiseRendezvousConnectProvider>,
@@ -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", &"<redacted>")
.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<ReconnectAttempt, ExecServerError> {
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<Self, ExecServerError> {
- 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<Self, ExecServerError> {
+ 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<JsonRpcConnection, ExecServerError> {
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";
@@ -465,14 +469,31 @@ impl EnvironmentManager {
environment_id: String,
exec_server_url: String,
connect_timeout: Option<std::time::Duration>,
+ ) -> Result<(), ExecServerError> {
+ self.upsert_environment_with_options(
+ environment_id,
+ RemoteEnvironmentOptions {
+ exec_server_url,
+ 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 exec_server_url = validate_remote_exec_server_url(exec_server_url)?;
+ let transport = options.into_transport_params()?;
let environment = Arc::new(Environment::remote_with_transport(
- ExecServerTransportParams::websocket_url(
- exec_server_url,
- connect_timeout.unwrap_or(DEFAULT_REMOTE_EXEC_SERVER_CONNECT_TIMEOUT),
- ),
+ 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<String, ExecServerError> {
- 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<Option<NoiseRendezvousEnvironmentConfig>, 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<Duration>,
+ /// Additional trusted headers for every physical WebSocket connection.
+ pub http_headers: HashMap<String, String>,
+}
+
+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", &"<redacted>")
+ .finish()
+ }
+}
+
+impl RemoteEnvironmentOptions {
+ pub(super) fn into_transport_params(
+ self,
+ ) -> Result<ExecServerTransportParams, ExecServerError> {
+ 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("<redacted>"));
+ 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<TcpStream> {
+ 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<TcpStream>,
+ 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::<JSONRPCMessage>(&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::<JSONRPCMessage>(&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<Arc<ClientConfig>>,
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<TcpStream> {
let addresses = tokio::net::lookup_host(address).await?.collect::<Vec<_>>();
+ connect_resolved_tcp(addresses, tcp_nodelay).await
+}
+
+async fn connect_loopback_tcp(address: String, tcp_nodelay: TcpNodelay) -> io::Result<TcpStream> {
+ let addresses = tokio::net::lookup_host(address).await?.collect::<Vec<_>>();
+ connect_resolved_tcp(loopback_addresses(addresses)?, tcp_nodelay).await
+}
+
+async fn connect_resolved_tcp(
+ addresses: Vec<SocketAddr>,
+ tcp_nodelay: TcpNodelay,
+) -> io::Result<TcpStream> {
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<Tcp
Ok(stream)
}
+fn loopback_addresses(addresses: Vec<SocketAddr>) -> io::Result<Vec<SocketAddr>> {
+ let loopback_addresses = addresses
+ .into_iter()
+ .filter(|address| address.ip().is_loopback())
+ .collect::<Vec<_>>();
+ 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<T, F, Fut>(
addresses: Vec<SocketAddr>,
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::<SocketAddr>()
+ .expect("loopback address should parse");
+ let remote = "192.0.2.1:8080"
+ .parse::<SocketAddr>()
+ .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::<SocketAddr>()
+ .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::<IpAddr>()
+ .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<T> 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::<Uri>().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::<Uri>().unwrap()
+ ));
+ }
+}