chore: refactor OAuth client authorization api

`OAuthState::start_authorization` now accepts a declarative `AuthorizationRequest` describing the client's available identity material and selects the highest-priority mechanism the server supports: pre-registered client information → Client ID Metadata Documents (SEP-991) → Dynamic Client Registration.

This replaces the three mechanism-specific entry points (`start_authorization`, `start_authorization_with_metadata_url`, `start_authorization_with_preregistered_client`), where callers previously had to know which mechanism to pick. `AuthorizationSession::new` is consolidated the same way, and the failure-recovery pattern from #994 (returning the manager alongside the error so `OAuthState` recovers to `Unauthorized` on transient failures) is now applied across all registration paths. Includes new `RecordingOAuthHttpClient`-based tests covering the priority matrix and recovery semantics, plus updated docs, examples, and conformance client.

Author: jamadeo

conformance/src/bin/client.rs

@@ -4,7 +4,7 @@ use rmcp::{
     service::RequestContext,
     transport::{
         AuthClient, AuthorizationManager, StreamableHttpClientTransport,
-        auth::{AuthorizationCallback, OAuthState},
+        auth::{AuthorizationCallback, AuthorizationRequest, OAuthState},
         streamable_http_client::StreamableHttpClientTransportConfig,
     },
 };
@@ -205,11 +205,10 @@ async fn perform_oauth_flow(
 
     // Discover + register + get auth URL
     oauth
-        .start_authorization_with_metadata_url(
-            &[],
-            REDIRECT_URI,
-            Some("conformance-client"),
-            Some(CIMD_CLIENT_METADATA_URL),
+        .start_authorization(
+            AuthorizationRequest::new(REDIRECT_URI)
+                .with_client_name("conformance-client")
+                .with_client_metadata_url(CIMD_CLIENT_METADATA_URL),
         )
         .await?;
 
@@ -254,10 +253,12 @@ async fn perform_oauth_flow_preregistered(
 ) -> anyhow::Result<AuthClient<reqwest::Client>> {
     let mut oauth = OAuthState::new(server_url, None).await?;
 
-    let config = rmcp::transport::auth::OAuthClientConfig::new(client_id, REDIRECT_URI)
-        .with_client_secret(client_secret);
     oauth
-        .start_authorization_with_preregistered_client(config)
+        .start_authorization(
+            AuthorizationRequest::new(REDIRECT_URI)
+                .with_preregistered_client(client_id)
+                .with_client_secret(client_secret),
+        )
         .await?;
 
     let auth_url = oauth.get_authorization_url().await?;
@@ -313,11 +314,10 @@ async fn run_auth_scope_step_up_client(
     // First auth
     let mut oauth = OAuthState::new(server_url, None).await?;
     oauth
-        .start_authorization_with_metadata_url(
-            &[],
-            REDIRECT_URI,
-            Some("conformance-client"),
-            Some(CIMD_CLIENT_METADATA_URL),
+        .start_authorization(
+            AuthorizationRequest::new(REDIRECT_URI)
+                .with_client_name("conformance-client")
+                .with_client_metadata_url(CIMD_CLIENT_METADATA_URL),
         )
         .await?;
 
@@ -363,11 +363,11 @@ async fn run_auth_scope_step_up_client(
 
                 let mut oauth2 = OAuthState::new(server_url, None).await?;
                 oauth2
-                    .start_authorization_with_metadata_url(
-                        SCOPE_STEP_UP_ESCALATED_SCOPES,
-                        REDIRECT_URI,
-                        Some("conformance-client"),
-                        Some(CIMD_CLIENT_METADATA_URL),
+                    .start_authorization(
+                        AuthorizationRequest::new(REDIRECT_URI)
+                            .with_scopes(SCOPE_STEP_UP_ESCALATED_SCOPES.iter().copied())
+                            .with_client_name("conformance-client")
+                            .with_client_metadata_url(CIMD_CLIENT_METADATA_URL),
                     )
                     .await?;
                 let auth_url2 = oauth2.get_authorization_url().await?;
@@ -413,11 +413,10 @@ async fn run_auth_scope_retry_limit_client(
     loop {
         let mut oauth = OAuthState::new(server_url, None).await?;
         oauth
-            .start_authorization_with_metadata_url(
-                &[],
-                REDIRECT_URI,
-                Some("conformance-client"),
-                Some(CIMD_CLIENT_METADATA_URL),
+            .start_authorization(
+                AuthorizationRequest::new(REDIRECT_URI)
+                    .with_client_name("conformance-client")
+                    .with_client_metadata_url(CIMD_CLIENT_METADATA_URL),
             )
             .await?;
         let auth_url = oauth.get_authorization_url().await?;

crates/rmcp/src/transport.rs

@@ -99,11 +99,12 @@ pub mod auth;
 pub use auth::JwtSigningAlgorithm;
 #[cfg(feature = "auth")]
 pub use auth::{
-    AuthClient, AuthError, AuthorizationManager, AuthorizationSession, AuthorizedHttpClient,
-    ClientCredentialsConfig, CredentialStore, EXTENSION_OAUTH_CLIENT_CREDENTIALS,
-    InMemoryCredentialStore, InMemoryStateStore, OAuthHttpClient, OAuthHttpClientError,
-    OAuthHttpClientFuture, OAuthHttpRedirectPolicy, OAuthHttpRequest, ScopeUpgradeConfig,
-    StateStore, StoredAuthorizationState, StoredCredentials, WWWAuthenticateParams,
+    AuthClient, AuthError, AuthorizationManager, AuthorizationRequest, AuthorizationSession,
+    AuthorizedHttpClient, ClientCredentialsConfig, CredentialStore,
+    EXTENSION_OAUTH_CLIENT_CREDENTIALS, InMemoryCredentialStore, InMemoryStateStore,
+    OAuthHttpClient, OAuthHttpClientError, OAuthHttpClientFuture, OAuthHttpRedirectPolicy,
+    OAuthHttpRequest, ScopeUpgradeConfig, StateStore, StoredAuthorizationState, StoredCredentials,
+    WWWAuthenticateParams,
 };
 
 // #[cfg(feature = "transport-ws")]