Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add ephemeral runtime registration and signed assertions (#55402)

cooper-oai79a19cbb3008
diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock
index 30d567b26b..1016bb7ec3 100644
--- a/codex-rs/Cargo.lock
+++ b/codex-rs/Cargo.lock
@@ -4578,11 +4578,22 @@ dependencies = [
name = "codex-runtime-agent-instance"
version = "0.0.0"
dependencies = [
+ "base64 0.22.1",
+ "codex-agent-identity",
+ "codex-http-client",
"codex-utils-redacted-string",
+ "ed25519-dalek",
+ "http 1.4.0",
"pretty_assertions",
+ "rand 0.9.3",
"serde",
"serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+ "url",
"uuid",
+ "wiremock",
+ "zeroize",
]
[[package]]
diff --git a/codex-rs/runtime-agent-instance/Cargo.toml b/codex-rs/runtime-agent-instance/Cargo.toml
index 1398925d35..1fcd6b99a4 100644
--- a/codex-rs/runtime-agent-instance/Cargo.toml
+++ b/codex-rs/runtime-agent-instance/Cargo.toml
@@ -11,10 +11,21 @@ doctest = false
workspace = true
[dependencies]
+base64 = { workspace = true }
+codex-agent-identity = { workspace = true }
+codex-http-client = { workspace = true }
codex-utils-redacted-string = { workspace = true }
+ed25519-dalek = { workspace = true }
+http = { workspace = true }
+rand = { workspace = true }
serde = { workspace = true, features = ["derive"] }
-uuid = { workspace = true, features = ["serde"] }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+url = { workspace = true }
+uuid = { workspace = true, features = ["serde", "v4"] }
+zeroize = { workspace = true }
[dev-dependencies]
pretty_assertions = { workspace = true }
-serde_json = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+wiremock = { workspace = true }
diff --git a/codex-rs/runtime-agent-instance/src/lib.rs b/codex-rs/runtime-agent-instance/src/lib.rs
index 3fceaf5c10..fb583460ef 100644
--- a/codex-rs/runtime-agent-instance/src/lib.rs
+++ b/codex-rs/runtime-agent-instance/src/lib.rs
@@ -1,6 +1,8 @@
-//! OpenAI runtime registration types, independent of credential storage and model providers.
+//! Ephemeral OpenAI runtimes: composite registration and per-request assertions.
mod bootstrap;
+mod registration;
+mod runtime;
pub use bootstrap::ActorInfo;
pub use bootstrap::AgentHostAuthorization;
@@ -9,3 +11,10 @@ pub use bootstrap::RuntimeRegistrationMetadata;
pub use bootstrap::RuntimeRegistrationRequest;
pub use bootstrap::RuntimeRegistrationResponse;
pub use bootstrap::RuntimeRole;
+
+pub use registration::DEFAULT_REGISTRATION_URL;
+pub use registration::RegistrationError;
+pub use registration::RegistrationErrorCode;
+pub use registration::RuntimeRegistrationClient;
+pub use runtime::RuntimeAgentInstance;
+pub use runtime::RuntimeRegistration;
diff --git a/codex-rs/runtime-agent-instance/src/registration.rs b/codex-rs/runtime-agent-instance/src/registration.rs
new file mode 100644
index 0000000000..22763e4731
--- /dev/null
+++ b/codex-rs/runtime-agent-instance/src/registration.rs
@@ -0,0 +1,160 @@
+//! Direct composite bootstrap. Credentials are sent only in the body, never through redirects.
+
+use crate::RuntimeAgentInstance;
+use crate::RuntimeRegistration;
+use codex_http_client::ClientRouteClass;
+use codex_http_client::HttpClientFactory;
+use codex_http_client::HttpError;
+use codex_http_client::NetworkPolicyDenied;
+use codex_http_client::RouteAwareClientPool;
+use codex_http_client::RouteAwareRequestError;
+use http::StatusCode;
+use serde::Deserialize;
+use std::time::Duration;
+use url::Url;
+
+pub const DEFAULT_REGISTRATION_URL: &str = "https://auth.openai.com/agent/register";
+const MAX_BODY_BYTES: usize = 64 * 1024;
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Makes one bounded attempt. Callers reuse the pending registration when retrying.
+pub struct RuntimeRegistrationClient {
+ http: RouteAwareClientPool,
+ url: Url,
+}
+
+impl RuntimeRegistrationClient {
+ pub fn new(factory: HttpClientFactory, url: Url) -> Result<Self, RegistrationError> {
+ let loopback = url.host_str().is_some_and(|host| {
+ host == "localhost"
+ || host == "[::1]"
+ || host
+ .parse::<std::net::IpAddr>()
+ .is_ok_and(|ip| ip.is_loopback())
+ });
+ if !(url.scheme() == "https" || (url.scheme() == "http" && loopback))
+ || !url.username().is_empty()
+ || url.password().is_some()
+ || url.query().is_some()
+ || url.fragment().is_some()
+ {
+ return Err(RegistrationError::InvalidEndpoint);
+ }
+ Ok(Self {
+ http: RouteAwareClientPool::with_chatgpt_cloudflare_cookies_without_redirects_or_request_logging(
+ factory,
+ ClientRouteClass::Auth,
+ ),
+ url,
+ })
+ }
+
+ pub async fn register(
+ &self,
+ registration: &RuntimeRegistration,
+ ) -> Result<RuntimeAgentInstance, RegistrationError> {
+ let body = serde_json::to_vec(&registration.request)
+ .map_err(|_| RegistrationError::InvalidRequest)?;
+ if body.len() > MAX_BODY_BYTES {
+ return Err(RegistrationError::InvalidRequest);
+ }
+ let mut response = self
+ .http
+ .post(self.url.as_str())
+ .header("Content-Type", "application/json")
+ .header(
+ "Idempotency-Key",
+ registration.initialization_id.to_string(),
+ )
+ .timeout(REQUEST_TIMEOUT)
+ .body(body)
+ .send()
+ .await
+ .map_err(|error| match error {
+ RouteAwareRequestError::Policy(denied) => RegistrationError::Policy(denied),
+ _ => RegistrationError::Transport,
+ })?;
+ let status = response.status();
+ let mut body = Vec::new();
+ while let Some(chunk) = response.chunk().await.map_err(|error| match error {
+ HttpError::Policy(denied) => RegistrationError::Policy(denied),
+ _ => RegistrationError::Transport,
+ })? {
+ if chunk.len() > MAX_BODY_BYTES - body.len() {
+ return Err(RegistrationError::InvalidResponse);
+ }
+ body.extend_from_slice(&chunk);
+ }
+ if status != StatusCode::OK {
+ let code = serde_json::from_slice::<ErrorEnvelope>(&body)
+ .ok()
+ .map(|e| e.error.code);
+ return Err(RegistrationError::Rejected { status, code });
+ }
+ let info: crate::RuntimeRegistrationResponse =
+ serde_json::from_slice(&body).map_err(|_| RegistrationError::InvalidResponse)?;
+ if info.runtime_agent_instance_id.is_empty() || info.agent_host_id.is_empty() {
+ return Err(RegistrationError::InvalidResponse);
+ }
+ Ok(RuntimeAgentInstance {
+ info,
+ signing_key: registration.signing_key.clone(),
+ })
+ }
+}
+
+/// Errors intentionally omit raw transport details and server messages, which can contain secrets.
+#[derive(Debug, thiserror::Error)]
+pub enum RegistrationError {
+ #[error(
+ "runtime registration requires a secure endpoint without credentials or query parameters"
+ )]
+ InvalidEndpoint,
+ #[error("invalid runtime registration request")]
+ InvalidRequest,
+ #[error(transparent)]
+ Policy(#[from] NetworkPolicyDenied),
+ #[error("runtime registration transport failed")]
+ Transport,
+ #[error("invalid runtime registration response")]
+ InvalidResponse,
+ #[error("runtime registration rejected ({status}, {code:?})")]
+ Rejected {
+ status: StatusCode,
+ code: Option<RegistrationErrorCode>,
+ },
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum RegistrationErrorCode {
+ TokenExpired,
+ RuntimeActorInvalid,
+ RuntimeInstanceRevoked,
+ RuntimeActorSourceInactive,
+ RuntimeInputInvalid,
+ RuntimeIdempotencyKeyInvalid,
+ RuntimeActorConflict,
+ RuntimeHostConflict,
+ RuntimeRegistrationConflict,
+ RuntimeInputTooLarge,
+ RuntimeRateLimited,
+ RuntimeVerificationUnavailable,
+ NotFound,
+ #[serde(other)]
+ Unknown,
+}
+
+#[derive(Deserialize)]
+struct ErrorEnvelope {
+ error: ErrorDetail,
+}
+
+#[derive(Deserialize)]
+struct ErrorDetail {
+ code: RegistrationErrorCode,
+}
+
+#[cfg(test)]
+#[path = "registration_tests.rs"]
+mod tests;
diff --git a/codex-rs/runtime-agent-instance/src/registration_tests.rs b/codex-rs/runtime-agent-instance/src/registration_tests.rs
new file mode 100644
index 0000000000..1770d41fb7
--- /dev/null
+++ b/codex-rs/runtime-agent-instance/src/registration_tests.rs
@@ -0,0 +1,268 @@
+//! Exercise bootstrap and signing through a real HTTP server without changing process auth.
+
+use super::*;
+use crate::AgentHostAuthorization;
+use crate::AuthenticatedActorAuthorization;
+use crate::RuntimeRegistrationMetadata;
+use crate::RuntimeRole;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use codex_http_client::DestinationPolicy;
+use codex_http_client::NetworkPolicyController;
+use codex_http_client::OutboundProxyPolicy;
+use ed25519_dalek::Signature;
+use ed25519_dalek::VerifyingKey;
+use pretty_assertions::assert_eq;
+use serde_json::Value;
+use serde_json::json;
+use uuid::Uuid;
+use wiremock::Mock;
+use wiremock::MockServer;
+use wiremock::ResponseTemplate;
+use wiremock::matchers::method;
+use wiremock::matchers::path;
+
+fn pending() -> RuntimeRegistration {
+ RuntimeRegistration::new(
+ AuthenticatedActorAuthorization::PlatformApiKey {
+ credential: "actor-secret".into(),
+ },
+ AgentHostAuthorization::InstallationId {
+ installation_id: Uuid::nil(),
+ },
+ RuntimeRegistrationMetadata {
+ harness: Some("codex".into()),
+ harness_version: Some("1.0.0".into()),
+ role: RuntimeRole::OrchestratorAndExecutor,
+ },
+ )
+ .unwrap()
+}
+
+fn client(server: &MockServer) -> RuntimeRegistrationClient {
+ let registration_url = Url::parse(DEFAULT_REGISTRATION_URL).unwrap();
+ let endpoint = Url::parse(&server.uri())
+ .unwrap()
+ .join(registration_url.path())
+ .unwrap();
+ RuntimeRegistrationClient::new(
+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+ endpoint,
+ )
+ .unwrap()
+}
+
+fn registered() -> Value {
+ json!({
+ "runtime_agent_instance_id": "agent-instance-test",
+ "agent_host_id": "host-test",
+ "actor": {
+ "kind": "platform",
+ "user_id": "user-test",
+ "organization_id": "org-test",
+ "project_id": "proj-test"
+ }
+ })
+}
+
+#[tokio::test]
+async fn registration_retries_keep_the_key_and_sign_fresh_assertions() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/agent/register"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(registered()))
+ .expect(2)
+ .mount(&server)
+ .await;
+ let pending = pending();
+ let client = client(&server);
+ let runtime = client.register(&pending).await.unwrap();
+ let retry = client.register(&pending).await.unwrap();
+ assert_eq!(runtime.info(), retry.info());
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 2);
+ assert_eq!(requests[0].body, requests[1].body);
+ for request in &requests {
+ assert!(!request.headers.contains_key("authorization"));
+ assert!(!request.headers.contains_key("x-openai-agent-assertion"));
+ assert_eq!(
+ request.headers["idempotency-key"],
+ pending.initialization_id.to_string()
+ );
+ }
+ let request: Value = requests[0].body_json().unwrap();
+ assert_eq!(request, serde_json::to_value(&pending.request).unwrap());
+ let key = STANDARD
+ .decode(
+ request["public_key"]
+ .as_str()
+ .unwrap()
+ .split_once(' ')
+ .unwrap()
+ .1,
+ )
+ .unwrap();
+ let key = VerifyingKey::from_bytes(key[19..].try_into().unwrap()).unwrap();
+ let before = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap()
+ .as_secs();
+ let first = verify_assertion(&runtime, &key);
+ let second = verify_assertion(&retry, &key);
+ let after = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap()
+ .as_secs();
+ assert_ne!(first["id"], second["id"]);
+ for payload in [first, second] {
+ assert!(Uuid::parse_str(payload["id"].as_str().unwrap()).is_ok());
+ assert!((before..=after).contains(&payload["iat"].as_u64().unwrap()));
+ assert_eq!(
+ payload,
+ json!({
+ "version": 1, "runtime_agent_instance": "agent-instance-test",
+ "iat": payload["iat"], "id": payload["id"]
+ })
+ );
+ }
+}
+
+fn verify_assertion(runtime: &RuntimeAgentInstance, key: &VerifyingKey) -> Value {
+ let assertion = runtime.assertion().unwrap();
+ let parts: Vec<_> = assertion.split('.').collect();
+ assert_eq!(parts.len(), 4);
+ assert_eq!(parts[0], "1");
+ assert!(!assertion.contains('='));
+ let protected: Value =
+ serde_json::from_slice(&URL_SAFE_NO_PAD.decode(parts[1]).unwrap()).unwrap();
+ assert_eq!(
+ protected,
+ json!({"alg": "EdDSA", "typ": "openai-agent-assertion+jws"})
+ );
+ let signature = Signature::from_slice(&URL_SAFE_NO_PAD.decode(parts[3]).unwrap()).unwrap();
+ key.verify_strict(format!("{}.{}", parts[1], parts[2]).as_bytes(), &signature)
+ .unwrap();
+ serde_json::from_slice(&URL_SAFE_NO_PAD.decode(parts[2]).unwrap()).unwrap()
+}
+
+#[test]
+fn new_initializations_use_new_keys_and_retry_ids() {
+ let first = pending();
+ let second = pending();
+ assert_ne!(first.initialization_id, second.initialization_id);
+ assert_ne!(first.request.public_key, second.request.public_key);
+}
+
+#[tokio::test]
+async fn rejected_registration_preserves_only_status_and_known_error_codes() {
+ for (status, code, expected) in [
+ (401, "token_expired", RegistrationErrorCode::TokenExpired),
+ (
+ 403,
+ "runtime_instance_revoked",
+ RegistrationErrorCode::RuntimeInstanceRevoked,
+ ),
+ (500, "secret-from-server", RegistrationErrorCode::Unknown),
+ ] {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .respond_with(ResponseTemplate::new(status).set_body_json(json!({
+ "error": {"code": code, "message": "secret-from-server"}
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+ let error = client(&server).register(&pending()).await.unwrap_err();
+ assert!(!format!("{error} {error:?}").contains("secret-from-server"));
+ assert!(
+ matches!(error, RegistrationError::Rejected { status: actual, code: Some(actual_code) }
+ if actual.as_u16() == status && actual_code == expected)
+ );
+ }
+}
+
+#[tokio::test]
+async fn registration_preserves_policy_revocation() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/agent/register"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(registered()))
+ .expect(1)
+ .mount(&server)
+ .await;
+ let controller = NetworkPolicyController::default();
+ let policy = controller.policy();
+ assert!(controller.publish(policy.revision(), DestinationPolicy::Unrestricted));
+ let client = RuntimeRegistrationClient::new(
+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault)
+ .with_network_policy(policy.clone().for_current_account()),
+ format!("{}/agent/register", server.uri()).parse().unwrap(),
+ )
+ .unwrap();
+ let pending = pending();
+ client.register(&pending).await.unwrap();
+
+ policy.invalidate();
+ assert!(controller.publish(policy.revision(), DestinationPolicy::Unrestricted));
+ assert!(matches!(
+ client.register(&pending).await,
+ Err(RegistrationError::Policy(NetworkPolicyDenied::Revoked))
+ ));
+ assert_eq!(server.received_requests().await.unwrap().len(), 1);
+}
+
+#[tokio::test]
+async fn registration_rejects_incomplete_or_oversized_responses() {
+ for body in [
+ json!({"runtime_agent_instance_id": "old-response"}).to_string(),
+ "x".repeat(MAX_BODY_BYTES + 1),
+ ] {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .respond_with(ResponseTemplate::new(200).set_body_string(body))
+ .expect(1)
+ .mount(&server)
+ .await;
+ assert!(matches!(
+ client(&server).register(&pending()).await,
+ Err(RegistrationError::InvalidResponse)
+ ));
+ }
+}
+
+#[tokio::test]
+async fn registration_never_forwards_credentials_through_a_redirect() {
+ let server = MockServer::start().await;
+ let destination = MockServer::start().await;
+ Mock::given(method("POST"))
+ .respond_with(ResponseTemplate::new(307).insert_header("Location", destination.uri()))
+ .expect(1)
+ .mount(&server)
+ .await;
+ assert!(matches!(
+ client(&server).register(&pending()).await,
+ Err(RegistrationError::Rejected {
+ status: StatusCode::TEMPORARY_REDIRECT,
+ ..
+ })
+ ));
+ assert!(destination.received_requests().await.unwrap().is_empty());
+}
+
+#[test]
+fn registration_rejects_unsafe_endpoints() {
+ for endpoint in [
+ "http://auth.example.com/register",
+ "https://user:[email protected]/register",
+ "https://auth.example.com/register?token=secret",
+ ] {
+ assert!(matches!(
+ RuntimeRegistrationClient::new(
+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+ endpoint.parse().unwrap(),
+ ),
+ Err(RegistrationError::InvalidEndpoint)
+ ));
+ }
+}
diff --git a/codex-rs/runtime-agent-instance/src/runtime.rs b/codex-rs/runtime-agent-instance/src/runtime.rs
new file mode 100644
index 0000000000..967302dd5f
--- /dev/null
+++ b/codex-rs/runtime-agent-instance/src/runtime.rs
@@ -0,0 +1,102 @@
+//! A pending registration keeps its key and retry ID; a registered runtime signs v1 assertions.
+
+use crate::RuntimeRegistrationRequest;
+use crate::RuntimeRegistrationResponse;
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use codex_agent_identity::encode_ssh_ed25519_public_key;
+use codex_utils_redacted_string::RedactedString;
+use ed25519_dalek::Signer;
+use ed25519_dalek::SigningKey;
+use rand::TryRngCore;
+use rand::rngs::OsRng;
+use serde_json::json;
+use std::fmt;
+use std::io;
+use std::sync::Arc;
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+use uuid::Uuid;
+use zeroize::Zeroizing;
+
+/// One initialization, including retries. Neither this key nor the resulting runtime is persisted.
+pub struct RuntimeRegistration {
+ pub(crate) initialization_id: Uuid,
+ pub(crate) request: RuntimeRegistrationRequest,
+ pub(crate) signing_key: Arc<SigningKey>,
+}
+
+impl RuntimeRegistration {
+ pub fn new(
+ actor: crate::AuthenticatedActorAuthorization,
+ host: crate::AgentHostAuthorization,
+ metadata: crate::RuntimeRegistrationMetadata,
+ ) -> io::Result<Self> {
+ let mut seed = Zeroizing::new([0u8; 32]);
+ OsRng
+ .try_fill_bytes(seed.as_mut())
+ .map_err(|_| io::Error::other("failed to generate runtime signing key"))?;
+ let signing_key = SigningKey::from_bytes(&seed);
+ Ok(Self {
+ initialization_id: Uuid::new_v4(),
+ request: RuntimeRegistrationRequest {
+ actor_auth: actor,
+ agent_host_auth: host,
+ public_key: encode_ssh_ed25519_public_key(&signing_key.verifying_key()),
+ metadata,
+ },
+ signing_key: Arc::new(signing_key),
+ })
+ }
+}
+
+/// A server-registered identity and its memory-only signer, shared for this runtime's lifetime.
+pub struct RuntimeAgentInstance {
+ pub(crate) info: RuntimeRegistrationResponse,
+ pub(crate) signing_key: Arc<SigningKey>,
+}
+
+impl RuntimeAgentInstance {
+ pub fn info(&self) -> &RuntimeRegistrationResponse {
+ &self.info
+ }
+
+ /// Make a fresh assertion for each request attempt or connection handshake.
+ pub fn assertion(&self) -> io::Result<RedactedString> {
+ let issued_at = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map_err(|_| io::Error::other("system clock is before the Unix epoch"))?
+ .as_secs();
+ let protected =
+ URL_SAFE_NO_PAD.encode(br#"{"alg":"EdDSA","typ":"openai-agent-assertion+jws"}"#);
+ let payload = URL_SAFE_NO_PAD.encode(
+ json!({
+ "version": 1,
+ "runtime_agent_instance": self.info.runtime_agent_instance_id,
+ "iat": issued_at,
+ "id": Uuid::new_v4(),
+ })
+ .to_string(),
+ );
+ let signing_input = format!("{protected}.{payload}");
+ let signature =
+ URL_SAFE_NO_PAD.encode(self.signing_key.sign(signing_input.as_bytes()).to_bytes());
+ // The outer version routes the assertion; it is not part of the JWS signing input.
+ let assertion = format!("1.{signing_input}.{signature}");
+ if assertion.len() > 8192 {
+ return Err(io::Error::other("runtime assertion exceeds the size limit"));
+ }
+ Ok(assertion.into())
+ }
+}
+
+impl fmt::Debug for RuntimeAgentInstance {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("RuntimeAgentInstance")
+ .field(
+ "runtime_agent_instance_id",
+ &self.info.runtime_agent_instance_id,
+ )
+ .finish_non_exhaustive()
+ }
+}