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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsindex 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].1else {panic!("expected websocket transport");diff --git a/codex-rs/exec-server/src/lib.rs b/codex-rs/exec-server/src/lib.rsindex 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.rsindex 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<TcpOk(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.rsindex 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.rsindex 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.rsnew file mode 100644index 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()+ ));+ }+}