Serialize MCP OAuth refresh transactions

Author: stevenlee-oai

codex-rs/config/src/types.rs

@@ -103,7 +103,10 @@ pub enum AuthCredentialsStoreMode {
 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "lowercase")]
 pub enum OAuthCredentialsStoreMode {
-    /// `Keyring` when available; otherwise, `File`.
+    /// Prefer `Keyring` and use `File` when keyring storage is unavailable.
+    /// Once an MCP client loads credentials from one store, that client keeps the resolved store
+    /// for its lifetime: refresh reads and writes surface store failures instead of switching to
+    /// the other store and risking replay of an older rotating refresh token.
     /// Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.
     #[default]
     Auto,

codex-rs/core/config.schema.json

@@ -2123,7 +2123,7 @@
       "description": "Determine where Codex should store and read MCP credentials.",
       "oneOf": [
         {
-          "description": "`Keyring` when available; otherwise, `File`. Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.",
+          "description": "Prefer `Keyring` and use `File` when keyring storage is unavailable. Once an MCP client loads credentials from one store, that client keeps the resolved store for its lifetime: refresh reads and writes surface store failures instead of switching to the other store and risking replay of an older rotating refresh token. Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.",
           "enum": [
             "auto"
           ],

codex-rs/rmcp-client/Cargo.toml

@@ -87,7 +87,10 @@ keyring = { workspace = true, features = ["sync-secret-service"] }
 # This test is compiled through `#[path]` inside the inline `oauth::tests` module. Cargo-shear
 # cannot resolve that nested module path and otherwise reports the linked file as unlinked.
 [package.metadata.cargo-shear]
-ignored-paths = ["src/oauth/tests/store_lock_tests.rs"]
+ignored-paths = [
+    "src/oauth/tests/persistor_tests.rs",
+    "src/oauth/tests/store_lock_tests.rs",
+]
 
 [lib]
 doctest = false

codex-rs/rmcp-client/src/lib.rs

@@ -26,7 +26,6 @@ pub use in_process_transport::InProcessTransportFactory;
 pub use oauth::StoredOAuthTokens;
 pub use oauth::WrappedOAuthTokenResponse;
 pub use oauth::delete_oauth_tokens;
-pub(crate) use oauth::load_oauth_tokens;
 pub use oauth::save_oauth_tokens;
 pub use perform_oauth_login::OAuthProviderError;
 pub use perform_oauth_login::OauthLoginHandle;