Add external header auth for existing realtime calls (#62114)

## What changed

Add `RealtimeExistingCallAuth` to `RealtimeAttachmentOptions`, with model-provider authentication as the default. Embedding hosts can explicitly select `ExternalHeaders` for existing calls to use header-based credentials and the host's transport without adding model-provider headers or performing runtime agent registration.

Require an explicit, nonempty sideband URL and header-based authentication for this mode. Destination authorization remains the trusted host's responsibility, and application network policy still applies.

## Testing

Add integration coverage for external-header and model-provider authentication through event delivery, reconnect, and detach. Verify that model-provider credentials are excluded in external-header mode and that invalid authentication, missing URLs, and network policy denials reject the attachment before a WebSocket handshake.

GitOrigin-RevId: 2c915e1cf76a3563f58f751272db1ec50718d925
This commit is contained in:
Shuo
2026-11-17 22:00:20 +00:00
committed by copyberry
parent 39a7b53fa4
commit 8dcd56d0cb
6 changed files with 470 additions and 20 deletions
+24 -1
View File
@@ -59,6 +59,7 @@ use codex_protocol::protocol::RealtimeConversationClosedEvent;
use codex_protocol::protocol::RealtimeConversationRealtimeEvent;
use codex_protocol::protocol::RealtimeConversationSdpEvent;
use codex_protocol::protocol::RealtimeConversationStartedEvent;
use codex_protocol::protocol::RealtimeExistingCallAuth;
use codex_protocol::protocol::RealtimeHandoffRequested;
use codex_protocol::protocol::RealtimeOutputModality;
use codex_protocol::protocol::RealtimeTranscriptEntry;
@@ -695,7 +696,7 @@ impl RealtimeConversationManager {
attachment_control,
sideband,
auth_context,
api_provider,
mut api_provider,
http_client_factory,
realtime_sideband_base_url,
extra_headers,
@@ -758,6 +759,13 @@ impl RealtimeConversationManager {
let sideband_base_url =
realtime_sideband_base_url.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
if attachment_control.options.existing_call_auth
== RealtimeExistingCallAuth::ExternalHeaders
{
// Model-provider headers may contain inference authentication. The
// host-selected observer uses only its external auth and session headers.
api_provider.headers.clear();
}
let client = RealtimeWebsocketClient::new(api_provider, http_client_factory.clone())
.with_webrtc_sideband_base_url(sideband_base_url.clone());
let transcript_tail_flush = RealtimeTranscriptTailFlush {
@@ -821,6 +829,7 @@ impl RealtimeConversationManager {
} else if let Some(call_id) = existing_call_id {
let task = existing_call::attach(existing_call::ExistingCallAttachment {
attachment_cancellation: attachment_control.token.clone(),
existing_call_auth: attachment_control.options.existing_call_auth,
client,
model_client,
auth_context,
@@ -2244,6 +2253,20 @@ pub(crate) async fn handle_attach(
params: ConversationStartParams,
options: RealtimeAttachmentOptions,
) -> CodexResult<()> {
if options.existing_call_auth == RealtimeExistingCallAuth::ExternalHeaders
&& !matches!(
&params.transport,
Some(ConversationStartTransport::ExistingCall {
sideband_base_url: Some(base_url),
..
}) if !base_url.trim().is_empty()
)
{
return Err(CodexErr::InvalidRequest(
"external header authentication requires an existing call with an explicit sideband URL"
.into(),
));
}
let attachment_control = RealtimeAttachmentControl {
token: CancellationToken::new(),
options,
@@ -15,8 +15,11 @@ use codex_api::RealtimeWebsocketClient;
use codex_api::map_api_error;
use codex_async_utils::OrCancelExt;
use codex_http_client::HttpClientFactory;
use codex_login::CodexAuth;
use codex_login::default_client::default_headers;
use codex_protocol::error::CodexErr;
use codex_protocol::error::Result as CodexResult;
use codex_protocol::protocol::RealtimeExistingCallAuth;
use http::HeaderMap;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
@@ -25,6 +28,7 @@ use tokio_util::sync::CancellationToken;
pub(super) struct ExistingCallAttachment {
pub(super) attachment_cancellation: CancellationToken,
pub(super) existing_call_auth: RealtimeExistingCallAuth,
pub(super) client: RealtimeWebsocketClient,
pub(super) model_client: ModelClient,
pub(super) auth_context: codex_model_provider::ProviderAuthContext,
@@ -46,6 +50,7 @@ pub(super) struct ExistingCallAttachment {
pub(super) async fn attach(attachment: ExistingCallAttachment) -> CodexResult<JoinHandle<()>> {
let ExistingCallAttachment {
attachment_cancellation,
existing_call_auth,
client,
model_client,
auth_context,
@@ -63,15 +68,36 @@ pub(super) async fn attach(attachment: ExistingCallAttachment) -> CodexResult<Jo
transcript_tail_flush,
stop_token,
} = attachment;
let (auth, sideband_headers, factory) = model_client
.realtime_sideband_auth(
extra_headers,
&sideband_base_url,
&auth_context,
http_client_factory,
)
.or_cancel(&attachment_cancellation)
.await??;
let (auth, sideband_headers, factory) = match existing_call_auth {
RealtimeExistingCallAuth::ModelProvider => {
model_client
.realtime_sideband_auth(
extra_headers,
&sideband_base_url,
&auth_context,
http_client_factory,
)
.or_cancel(&attachment_cancellation)
.await??
}
RealtimeExistingCallAuth::ExternalHeaders => {
let Some(auth @ CodexAuth::Headers(_)) = auth_context
.credentials
.auth()
.or_cancel(&attachment_cancellation)
.await?
else {
return Err(CodexErr::InvalidRequest(
"external header authentication requires header-based authentication".into(),
));
};
(
codex_model_provider::auth_provider_from_auth(&auth),
extra_headers,
http_client_factory,
)
}
};
let client = client.with_http_client_factory(factory).with_auth(auth);
let transcript_state = RealtimeTranscriptState::default();
let connection = client