feat(app-server): enforce managed remote control disable (#27961)

## Why

Managed deployments need a reliable deny gate for remote control.
Persisted enablement and explicit startup requests currently remain able
to start the transport, while the removed `features.remote_control` key
is intentionally only a compatibility no-op.

This adds a dedicated requirement that administrators can use to force
remote control off without deleting the user's persisted preference.
Removing the requirement and restarting restores the prior choice.

## What Changed

- Added top-level `allow_remote_control` requirements parsing, sourced
layer precedence, debug output, and `configRequirements/read` exposure
as `allowRemoteControl`.
- Added a typed transport policy captured from the startup requirements
snapshot. Managed disable forces the initial state to disabled and
prevents enrollment, refresh, connection, and persisted-preference
mutation.
- Rejected every `remoteControl/*` RPC before parameter deserialization
with JSON-RPC `-32600` and `remote control is disabled by managed
requirements`.
- Preserved the existing disabled status notification and the previous
behavior when the requirement is `true` or omitted.
- Regenerated app-server protocol schemas and documented the new
requirement.

## Verification

- Confirmed all remote-control RPCs, including a malformed request,
return the managed-policy error while the initial status notification
remains `disabled`.
- Confirmed explicit ephemeral startup and persisted enablement make no
backend connection and leave the SQLite preference unchanged.
- Confirmed `allow_remote_control = true` does not enable or block
remote control and `configRequirements/read` returns
`allowRemoteControl: false` for the deny policy.

Related issue: N/A (managed-policy hardening).

codex-rs/app-server-transport/src/lib.rs

@@ -12,7 +12,10 @@ pub use transport::AppServerTransportParseError;
 pub use transport::CHANNEL_CAPACITY;
 pub use transport::ConnectionOrigin;
 pub use transport::REMOTE_CONTROL_DISABLED_ENV_VAR;
+pub use transport::RemoteControlDisabledByRequirements;
+pub use transport::RemoteControlEnableError;
 pub use transport::RemoteControlHandle;
+pub use transport::RemoteControlPolicy;
 pub use transport::RemoteControlStartConfig;
 pub use transport::RemoteControlStartupMode;
 pub use transport::RemoteControlUnavailable;

codex-rs/app-server-transport/src/transport/mod.rs

@@ -31,7 +31,10 @@ mod unix_socket_tests;
 mod websocket;
 
 pub use remote_control::REMOTE_CONTROL_DISABLED_ENV_VAR;
+pub use remote_control::RemoteControlDisabledByRequirements;
+pub use remote_control::RemoteControlEnableError;
 pub use remote_control::RemoteControlHandle;
+pub use remote_control::RemoteControlPolicy;
 pub use remote_control::RemoteControlStartConfig;
 pub use remote_control::RemoteControlStartupMode;
 pub use remote_control::RemoteControlUnavailable;

codex-rs/app-server-transport/src/transport/remote_control/desired_state.rs

@@ -1,3 +1,4 @@
+use super::RemoteControlEnableError;
 use super::RemoteControlHandle;
 use super::RemoteControlUnavailable;
 use super::enroll::update_persisted_remote_control_enrollment;
@@ -51,6 +52,9 @@ impl RemoteControlHandle {
         &self,
         app_server_client_name: Option<&str>,
     ) -> io::Result<bool> {
+        if self.ensure_remote_control_allowed().is_err() {
+            return Ok(false);
+        }
         let _transition = self
             .desired_state_rpc_lock
             .acquire()
@@ -93,6 +97,8 @@ impl RemoteControlHandle {
         &self,
         app_server_client_name: Option<&str>,
     ) -> io::Result<RemoteControlStatusChangedNotification> {
+        self.ensure_remote_control_allowed()
+            .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err))?;
         let _transition = self
             .desired_state_rpc_lock
             .acquire()
@@ -149,8 +155,15 @@ impl RemoteControlHandle {
             .await?;
         }
         publish_current_enrollment(&mut current_enrollment, &enrollment);
-        self.enable_with_preference(Some(true))
-            .map_err(|err| io::Error::new(io::ErrorKind::NotFound, err))?;
+        self.enable_with_preference(Some(true)).map_err(|err| {
+            let kind = match err {
+                RemoteControlEnableError::Unavailable(_) => io::ErrorKind::NotFound,
+                RemoteControlEnableError::DisabledByRequirements(_) => {
+                    io::ErrorKind::PermissionDenied
+                }
+            };
+            io::Error::new(kind, err)
+        })?;
         RemoteControlStatusPublisher::new(self.status_tx.as_ref().clone())
             .publish_environment_id(Some(enrollment.environment_id));
         Ok(self.status())

codex-rs/app-server-transport/src/transport/remote_control/mod.rs

@@ -64,6 +64,14 @@ use tracing::warn;
 pub struct RemoteControlStartConfig {
     pub remote_control_url: String,
     pub installation_id: String,
+    pub policy: RemoteControlPolicy,
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlPolicy {
+    #[default]
+    Allowed,
+    DisabledByRequirements,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -95,6 +103,7 @@ pub(super) struct QueuedServerEnvelope {
 
 #[derive(Clone)]
 pub struct RemoteControlHandle {
+    policy: RemoteControlPolicy,
     desired_state_tx: Arc<watch::Sender<RemoteControlDesiredState>>,
     desired_state_rpc_lock: Arc<Semaphore>,
     desired_state_persistence_lock: Arc<Semaphore>,
@@ -195,20 +204,64 @@ impl fmt::Display for RemoteControlUnavailable {
 
 impl Error for RemoteControlUnavailable {}
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteControlDisabledByRequirements;
+
+impl fmt::Display for RemoteControlDisabledByRequirements {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "remote control is disabled by managed requirements")
+    }
+}
+
+impl Error for RemoteControlDisabledByRequirements {}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteControlEnableError {
+    Unavailable(RemoteControlUnavailable),
+    DisabledByRequirements(RemoteControlDisabledByRequirements),
+}
+
+impl fmt::Display for RemoteControlEnableError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Unavailable(err) => err.fmt(f),
+            Self::DisabledByRequirements(err) => err.fmt(f),
+        }
+    }
+}
+
+impl Error for RemoteControlEnableError {}
+
 impl RemoteControlHandle {
+    pub fn ensure_remote_control_allowed(&self) -> Result<(), RemoteControlDisabledByRequirements> {
+        match self.policy {
+            RemoteControlPolicy::Allowed => Ok(()),
+            RemoteControlPolicy::DisabledByRequirements => Err(RemoteControlDisabledByRequirements),
+        }
+    }
+
+    fn ensure_remote_control_allowed_io(&self) -> io::Result<()> {
+        self.ensure_remote_control_allowed()
+            .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err))
+    }
+
     pub fn enable_ephemeral(
         &self,
-    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlUnavailable> {
+    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError> {
         self.enable_with_preference(/*persistence_preference*/ None)
     }
 
     fn enable_with_preference(
         &self,
         persistence_preference: Option<bool>,
-    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlUnavailable> {
+    ) -> Result<RemoteControlStatusChangedNotification, RemoteControlEnableError> {
+        self.ensure_remote_control_allowed()
+            .map_err(RemoteControlEnableError::DisabledByRequirements)?;
         if self.state_db.is_none() {
             warn!("remote control cannot be enabled because sqlite state db is unavailable");
-            return Err(RemoteControlUnavailable);
+            return Err(RemoteControlEnableError::Unavailable(
+                RemoteControlUnavailable,
+            ));
         }
 
         let mut effective_persistence_preference = persistence_preference;
@@ -255,6 +308,7 @@ impl RemoteControlHandle {
         &self,
         app_server_client_name: Option<&str>,
     ) -> io::Result<RemoteControlStatusChangedNotification> {
+        self.ensure_remote_control_allowed_io()?;
         let _transition = self
             .desired_state_rpc_lock
             .acquire()
@@ -334,6 +388,7 @@ impl RemoteControlHandle {
         params: RemoteControlPairingStartParams,
         app_server_client_name: Option<&str>,
     ) -> io::Result<RemoteControlPairingStartResponse> {
+        self.ensure_remote_control_allowed_io()?;
         if !self.desired_state_tx.borrow().is_enabled() {
             return Err(Self::pairing_disabled_error());
         }
@@ -564,6 +619,7 @@ impl RemoteControlHandle {
         &self,
         params: RemoteControlPairingStatusParams,
     ) -> io::Result<RemoteControlPairingStatusResponse> {
+        self.ensure_remote_control_allowed_io()?;
         if !self.desired_state_tx.borrow().is_enabled() {
             return Err(Self::pairing_disabled_error());
         }
@@ -663,6 +719,7 @@ impl RemoteControlHandle {
         &self,
         params: RemoteControlClientsListParams,
     ) -> io::Result<RemoteControlClientsListResponse> {
+        self.ensure_remote_control_allowed_io()?;
         clients::list_remote_control_clients(&self.remote_control_url, &self.auth_manager, params)
             .await
     }
@@ -671,6 +728,7 @@ impl RemoteControlHandle {
         &self,
         params: RemoteControlClientsRevokeParams,
     ) -> io::Result<RemoteControlClientsRevokeResponse> {
+        self.ensure_remote_control_allowed_io()?;
         clients::revoke_remote_control_client(&self.remote_control_url, &self.auth_manager, params)
             .await
     }
@@ -867,19 +925,21 @@ pub async fn start_remote_control(
     app_server_client_name_rx: Option<oneshot::Receiver<String>>,
     startup_mode: RemoteControlStartupMode,
 ) -> io::Result<(JoinHandle<()>, RemoteControlHandle)> {
+    let policy = config.policy;
     let state_db_available = state_db.is_some();
     let requested_initial_enabled = startup_mode == RemoteControlStartupMode::EnabledEphemeral;
-    let desired_state = if !state_db_available {
-        RemoteControlDesiredState::Disabled
-    } else {
-        match startup_mode {
-            RemoteControlStartupMode::ResolvePersisted => RemoteControlDesiredState::Unknown,
-            RemoteControlStartupMode::DisabledEphemeral => RemoteControlDesiredState::Disabled,
-            RemoteControlStartupMode::EnabledEphemeral => RemoteControlDesiredState::Enabled {
-                persistence_preference: None,
-            },
-        }
-    };
+    let desired_state =
+        if policy == RemoteControlPolicy::DisabledByRequirements || !state_db_available {
+            RemoteControlDesiredState::Disabled
+        } else {
+            match startup_mode {
+                RemoteControlStartupMode::ResolvePersisted => RemoteControlDesiredState::Unknown,
+                RemoteControlStartupMode::DisabledEphemeral => RemoteControlDesiredState::Disabled,
+                RemoteControlStartupMode::EnabledEphemeral => RemoteControlDesiredState::Enabled {
+                    persistence_preference: None,
+                },
+            }
+        };
     let initial_enabled = desired_state.is_enabled();
     if requested_initial_enabled && !state_db_available {
         warn!("remote control disabled because sqlite state db is unavailable");
@@ -995,6 +1055,7 @@ pub async fn start_remote_control(
     Ok((
         join_handle,
         RemoteControlHandle {
+            policy,
             desired_state_tx,
             desired_state_rpc_lock,
             desired_state_persistence_lock,

codex-rs/app-server-transport/src/transport/remote_control/tests.rs

@@ -230,6 +230,7 @@ async fn explicit_disabled_start_ignores_persisted_enable() {
         RemoteControlStartConfig {
             remote_control_url: TEST_REMOTE_CONTROL_URL.to_string(),
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager(),
@@ -261,6 +262,105 @@ async fn explicit_disabled_start_ignores_persisted_enable() {
     remote_task.await.expect("remote control task should join");
 }
 
+#[tokio::test]
+async fn managed_disable_overrides_startup_and_persisted_enablement() {
+    let listener = TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("listener should bind");
+    let remote_control_url = remote_control_url_for_listener(&listener);
+    let codex_home = TempDir::new().expect("temp dir should create");
+    let state_db = remote_control_state_runtime(&codex_home).await;
+    let remote_control_target = normalize_remote_control_url(&remote_control_url)
+        .expect("remote control target should normalize");
+    let enrollment = RemoteControlEnrollmentRecord {
+        websocket_url: remote_control_target.websocket_url,
+        account_id: "account_id".to_string(),
+        app_server_client_name: None,
+        server_id: "server-id".to_string(),
+        environment_id: "environment-id".to_string(),
+        server_name: "server-name".to_string(),
+        remote_control_enabled: Some(true),
+    };
+    state_db
+        .upsert_remote_control_enrollment(&enrollment)
+        .await
+        .expect("enrollment should persist");
+    let (transport_event_tx, _transport_event_rx) = mpsc::channel(CHANNEL_CAPACITY);
+    let shutdown_token = CancellationToken::new();
+
+    let (remote_task, remote_handle) = start_remote_control(
+        RemoteControlStartConfig {
+            remote_control_url,
+            installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::DisabledByRequirements,
+        },
+        Some(state_db.clone()),
+        remote_control_auth_manager(),
+        transport_event_tx,
+        shutdown_token.clone(),
+        /*app_server_client_name_rx*/ None,
+        RemoteControlStartupMode::EnabledEphemeral,
+    )
+    .await
+    .expect("remote control should start disabled");
+
+    assert_eq!(
+        remote_handle.status().status,
+        RemoteControlConnectionStatus::Disabled
+    );
+    assert_eq!(
+        remote_handle.ensure_remote_control_allowed(),
+        Err(RemoteControlDisabledByRequirements)
+    );
+    assert!(
+        !remote_handle
+            .resolve_persisted_preference(/*app_server_client_name*/ None)
+            .await
+            .expect("managed disable should resolve without loading persistence")
+    );
+    assert_eq!(
+        remote_handle
+            .enable_ephemeral()
+            .expect_err("managed requirements should reject ephemeral enable"),
+        RemoteControlEnableError::DisabledByRequirements(RemoteControlDisabledByRequirements)
+    );
+    let enable_error = remote_handle
+        .enable(/*app_server_client_name*/ None)
+        .await
+        .expect_err("managed requirements should reject durable enable");
+    assert_eq!(enable_error.kind(), std::io::ErrorKind::PermissionDenied);
+    assert_eq!(
+        enable_error.to_string(),
+        "remote control is disabled by managed requirements"
+    );
+    let disable_error = remote_handle
+        .disable(/*app_server_client_name*/ None)
+        .await
+        .expect_err("managed requirements should reject durable disable");
+    assert_eq!(disable_error.kind(), std::io::ErrorKind::PermissionDenied);
+    assert_eq!(
+        disable_error.to_string(),
+        "remote control is disabled by managed requirements"
+    );
+    assert_eq!(
+        state_db
+            .get_remote_control_enrollment(
+                &enrollment.websocket_url,
+                &enrollment.account_id,
+                /*app_server_client_name*/ None,
+            )
+            .await
+            .expect("enrollment should load"),
+        Some(enrollment)
+    );
+    timeout(Duration::from_millis(100), listener.accept())
+        .await
+        .expect_err("managed requirements should prevent backend contact");
+
+    shutdown_token.cancel();
+    remote_task.await.expect("remote control task should join");
+}
+
 fn remote_control_url_for_listener(listener: &TcpListener) -> String {
     let addr = listener
         .local_addr()
@@ -303,6 +403,7 @@ fn remote_control_handle_with_current_enrollment(
         },
     )));
     RemoteControlHandle {
+        policy: RemoteControlPolicy::Allowed,
         desired_state_tx: Arc::new(desired_state_tx),
         desired_state_rpc_lock: Arc::new(Semaphore::new(1)),
         desired_state_persistence_lock: Arc::new(Semaphore::new(1)),
@@ -430,6 +531,7 @@ async fn remote_control_transport_manages_virtual_clients_and_routes_messages()
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager(),
@@ -723,6 +825,7 @@ async fn remote_control_transport_reconnects_after_disconnect() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         remote_control_auth_manager(),
@@ -824,6 +927,7 @@ async fn remote_control_transport_refreshes_server_token_after_websocket_unautho
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         remote_control_auth_manager(),
@@ -904,6 +1008,7 @@ async fn remote_control_start_allows_remote_control_invalid_url_when_disabled()
         RemoteControlStartConfig {
             remote_control_url: "https://internal.example.com/backend-api/".to_string(),
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         /*state_db*/ None,
         remote_control_auth_manager(),
@@ -944,6 +1049,7 @@ async fn remote_control_start_allows_missing_auth_when_enabled() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         auth_manager,
@@ -979,6 +1085,7 @@ async fn remote_control_start_reports_missing_state_db_as_disabled_when_enabled(
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         /*state_db*/ None,
         remote_control_auth_manager(),
@@ -1008,7 +1115,7 @@ async fn remote_control_start_reports_missing_state_db_as_disabled_when_enabled(
         remote_handle
             .enable_ephemeral()
             .expect_err("enable should fail"),
-        super::RemoteControlUnavailable
+        RemoteControlEnableError::Unavailable(super::RemoteControlUnavailable)
     );
     timeout(Duration::from_millis(100), listener.accept())
         .await
@@ -1038,6 +1145,7 @@ async fn remote_control_handle_enable_disable_stops_and_restarts_connections() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         remote_control_auth_manager(),
@@ -1157,6 +1265,7 @@ async fn remote_control_transport_clears_outgoing_buffer_when_backend_acks() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         remote_control_auth_manager(),
@@ -1339,6 +1448,7 @@ async fn remote_control_http_mode_enrolls_before_connecting() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(remote_control_state_runtime(&codex_home).await),
         remote_control_auth_manager(),
@@ -1587,6 +1697,7 @@ async fn remote_control_http_mode_refreshes_persisted_enrollment_before_connecti
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),
@@ -1695,6 +1806,7 @@ async fn remote_control_stdio_mode_waits_for_client_name_before_connecting() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),
@@ -1778,6 +1890,7 @@ async fn remote_control_waits_for_account_id_before_enrolling() {
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         auth_manager.clone(),
@@ -1881,6 +1994,7 @@ async fn persisted_enable_does_not_follow_auth_to_an_account_without_a_preferenc
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         auth_manager.clone(),
@@ -1996,6 +2110,7 @@ async fn remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollmen
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),
@@ -2118,6 +2233,7 @@ async fn remote_control_http_mode_reenrolls_after_explicit_missing_server_404()
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),
@@ -2254,6 +2370,7 @@ async fn remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_f
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),
@@ -2356,6 +2473,7 @@ async fn remote_control_http_mode_preserves_enrollment_after_generic_websocket_4
         RemoteControlStartConfig {
             remote_control_url,
             installation_id: TEST_INSTALLATION_ID.to_string(),
+            policy: RemoteControlPolicy::Allowed,
         },
         Some(state_db.clone()),
         remote_control_auth_manager_with_home(&codex_home),

codex-rs/app-server-transport/src/transport/remote_control/tests/clients_tests.rs

@@ -22,6 +22,7 @@ fn client_management_handle(
         environment_id: None,
     });
     RemoteControlHandle {
+        policy: RemoteControlPolicy::Allowed,
         desired_state_tx: Arc::new(desired_state_tx),
         desired_state_rpc_lock: Arc::new(Semaphore::new(1)),
         desired_state_persistence_lock: Arc::new(Semaphore::new(1)),