refactor(xaa): consolidate save methods into OAuthDiscoveryState

Remove individual saveAuthorizationServerUrl/saveResourceUrl methods
from OAuthClientProvider in favor of adding resourceUrl to
OAuthDiscoveryState. CrossAppAccessProvider now reads both URLs from
the discovery state, eliminating redundant save calls in auth().

The single saveDiscoveryState call is moved after selectResourceURL
so it can include the resolved resource URL.

Author: pcarleton

packages/client/src/client/auth.ts

@@ -184,50 +184,6 @@ export interface OAuthClientProvider {
      */
     prepareTokenRequest?(scope?: string): URLSearchParams | Promise<URLSearchParams | undefined> | undefined;
 
-    /**
-     * Saves the authorization server URL after RFC 9728 discovery.
-     * This method is called by {@linkcode auth} after successful discovery of the
-     * authorization server via protected resource metadata.
-     *
-     * Providers implementing Cross-App Access or other flows that need access to
-     * the discovered authorization server URL should implement this method.
-     *
-     * @param authorizationServerUrl - The authorization server URL discovered via RFC 9728
-     */
-    saveAuthorizationServerUrl?(authorizationServerUrl: string): void | Promise<void>;
-
-    /**
-     * Returns the previously saved authorization server URL, if available.
-     *
-     * Providers implementing Cross-App Access can use this to access the
-     * authorization server URL discovered during the OAuth flow.
-     *
-     * @returns The authorization server URL, or `undefined` if not available
-     */
-    authorizationServerUrl?(): string | undefined | Promise<string | undefined>;
-
-    /**
-     * Saves the resource URL after RFC 9728 discovery.
-     * This method is called by {@linkcode auth} after successful discovery of the
-     * resource metadata.
-     *
-     * Providers implementing Cross-App Access or other flows that need access to
-     * the discovered resource URL should implement this method.
-     *
-     * @param resourceUrl - The resource URL discovered via RFC 9728
-     */
-    saveResourceUrl?(resourceUrl: string): void | Promise<void>;
-
-    /**
-     * Returns the previously saved resource URL, if available.
-     *
-     * Providers implementing Cross-App Access can use this to access the
-     * resource URL discovered during the OAuth flow.
-     *
-     * @returns The resource URL, or `undefined` if not available
-     */
-    resourceUrl?(): string | undefined | Promise<string | undefined>;
-
     /**
      * Saves the OAuth discovery state after RFC 9728 and authorization server metadata
      * discovery. Providers can persist this state to avoid redundant discovery requests
@@ -267,6 +223,9 @@ export interface OAuthClientProvider {
 export interface OAuthDiscoveryState extends OAuthServerInfo {
     /** The URL at which the protected resource metadata was found, if available. */
     resourceMetadataUrl?: string;
+
+    /** The resolved resource URL from {@linkcode selectResourceURL}, if available. */
+    resourceUrl?: string;
 }
 
 export type AuthResult = 'AUTHORIZED' | 'REDIRECT';
@@ -489,6 +448,7 @@ async function authInternal(
     let resourceMetadata: OAuthProtectedResourceMetadata | undefined;
     let authorizationServerUrl: string | URL;
     let metadata: AuthorizationServerMetadata | undefined;
+    let needsDiscoveryStateSave = false;
 
     // If resourceMetadataUrl is not provided, try to load it from cached state
     // This handles browser redirects where the URL was saved before navigation
@@ -518,43 +478,31 @@ async function authInternal(
         }
 
         // Re-save if we enriched the cached state with missing metadata
-        if (metadata !== cachedState.authorizationServerMetadata || resourceMetadata !== cachedState.resourceMetadata) {
-            await provider.saveDiscoveryState?.({
-                authorizationServerUrl: String(authorizationServerUrl),
-                resourceMetadataUrl: effectiveResourceMetadataUrl?.toString(),
-                resourceMetadata,
-                authorizationServerMetadata: metadata
-            });
-        }
+        needsDiscoveryStateSave = metadata !== cachedState.authorizationServerMetadata || resourceMetadata !== cachedState.resourceMetadata;
     } else {
         // Full discovery via RFC 9728
         const serverInfo = await discoverOAuthServerInfo(serverUrl, { resourceMetadataUrl: effectiveResourceMetadataUrl, fetchFn });
         authorizationServerUrl = serverInfo.authorizationServerUrl;
         metadata = serverInfo.authorizationServerMetadata;
         resourceMetadata = serverInfo.resourceMetadata;
+        needsDiscoveryStateSave = true;
+    }
 
-        // Persist discovery state for future use
+    const resource: URL | undefined = await selectResourceURL(serverUrl, provider, resourceMetadata);
+
+    if (needsDiscoveryStateSave) {
         // TODO: resourceMetadataUrl is only populated when explicitly provided via options
         // or loaded from cached state. The URL derived internally by
         // discoverOAuthProtectedResourceMetadata() is not captured back here.
         await provider.saveDiscoveryState?.({
             authorizationServerUrl: String(authorizationServerUrl),
             resourceMetadataUrl: effectiveResourceMetadataUrl?.toString(),
             resourceMetadata,
-            authorizationServerMetadata: metadata
+            authorizationServerMetadata: metadata,
+            resourceUrl: resource?.toString()
         });
     }
 
-    // Save authorization server URL for providers that need it (e.g., CrossAppAccessProvider)
-    await provider.saveAuthorizationServerUrl?.(String(authorizationServerUrl));
-
-    const resource: URL | undefined = await selectResourceURL(serverUrl, provider, resourceMetadata);
-
-    // Save resource URL for providers that need it (e.g., CrossAppAccessProvider)
-    if (resource) {
-        await provider.saveResourceUrl?.(String(resource));
-    }
-
     // Apply scope selection strategy (SEP-835):
     // 1. WWW-Authenticate scope (passed via `scope` param)
     // 2. PRM scopes_supported

packages/client/src/client/authExtensions.ts

@@ -8,7 +8,7 @@
 import type { FetchLike, OAuthClientInformation, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/core';
 import type { CryptoKey, JWK } from 'jose';
 
-import type { AddClientAuthentication, OAuthClientProvider } from './auth.js';
+import type { AddClientAuthentication, OAuthClientProvider, OAuthDiscoveryState } from './auth.js';
 
 /**
  * Helper to produce a `private_key_jwt` client authentication function.
@@ -545,8 +545,7 @@ export class CrossAppAccessProvider implements OAuthClientProvider {
     private _clientMetadata: OAuthClientMetadata;
     private _assertionCallback: AssertionCallback;
     private _fetchFn: FetchLike;
-    private _authorizationServerUrl?: string;
-    private _resourceUrl?: string;
+    private _discoveryState?: OAuthDiscoveryState;
     private _scope?: string;
 
     constructor(options: CrossAppAccessProviderOptions) {
@@ -600,40 +599,17 @@ export class CrossAppAccessProvider implements OAuthClientProvider {
         throw new Error('codeVerifier is not used for jwt-bearer flow');
     }
 
-    /**
-     * Saves the authorization server URL discovered during OAuth flow.
-     * This is called by the auth() function after RFC 9728 discovery.
-     */
-    saveAuthorizationServerUrl?(authorizationServerUrl: string): void {
-        this._authorizationServerUrl = authorizationServerUrl;
-    }
-
-    /**
-     * Returns the cached authorization server URL if available.
-     */
-    authorizationServerUrl?(): string | undefined {
-        return this._authorizationServerUrl;
+    saveDiscoveryState(state: OAuthDiscoveryState): void {
+        this._discoveryState = state;
     }
 
-    /**
-     * Saves the resource URL discovered during OAuth flow.
-     * This is called by the auth() function after RFC 9728 discovery.
-     */
-    saveResourceUrl?(resourceUrl: string): void {
-        this._resourceUrl = resourceUrl;
-    }
-
-    /**
-     * Returns the cached resource URL if available.
-     */
-    resourceUrl?(): string | undefined {
-        return this._resourceUrl;
+    discoveryState(): OAuthDiscoveryState | undefined {
+        return this._discoveryState;
     }
 
     async prepareTokenRequest(scope?: string): Promise<URLSearchParams> {
-        // Get the authorization server URL and resource URL from cached state
-        const authServerUrl = this._authorizationServerUrl;
-        const resourceUrl = this._resourceUrl;
+        const authServerUrl = this._discoveryState?.authorizationServerUrl;
+        const resourceUrl = this._discoveryState?.resourceUrl;
 
         if (!authServerUrl) {
             throw new Error('Authorization server URL not available. Ensure auth() has been called first.');

packages/client/test/client/authExtensions.test.ts

@@ -467,38 +467,33 @@ describe('CrossAppAccessProvider', () => {
             clientSecret: 'secret'
         });
 
-        // Manually set authorization server URL but not resource URL
-        provider.saveAuthorizationServerUrl?.(AUTH_SERVER_URL);
+        // Save discovery state without resourceUrl
+        provider.saveDiscoveryState({
+            authorizationServerUrl: AUTH_SERVER_URL
+        });
 
         await expect(provider.prepareTokenRequest()).rejects.toThrow(
             'Resource URL not available — server may not implement RFC 9728 Protected Resource Metadata'
         );
     });
 
-    it('stores and retrieves authorization server URL', () => {
+    it('stores and retrieves discovery state', () => {
         const provider = new CrossAppAccessProvider({
             assertion: async () => 'jwt-grant',
             clientId: 'client',
             clientSecret: 'secret'
         });
 
-        expect(provider.authorizationServerUrl?.()).toBeUndefined();
-
-        provider.saveAuthorizationServerUrl?.(AUTH_SERVER_URL);
-        expect(provider.authorizationServerUrl?.()).toBe(AUTH_SERVER_URL);
-    });
+        expect(provider.discoveryState()).toBeUndefined();
 
-    it('stores and retrieves resource URL', () => {
-        const provider = new CrossAppAccessProvider({
-            assertion: async () => 'jwt-grant',
-            clientId: 'client',
-            clientSecret: 'secret'
+        provider.saveDiscoveryState({
+            authorizationServerUrl: AUTH_SERVER_URL,
+            resourceUrl: RESOURCE_SERVER_URL
         });
 
-        expect(provider.resourceUrl?.()).toBeUndefined();
-
-        provider.saveResourceUrl?.(RESOURCE_SERVER_URL);
-        expect(provider.resourceUrl?.()).toBe(RESOURCE_SERVER_URL);
+        const state = provider.discoveryState();
+        expect(state?.authorizationServerUrl).toBe(AUTH_SERVER_URL);
+        expect(state?.resourceUrl).toBe(RESOURCE_SERVER_URL);
     });
 
     it('has correct client metadata', () => {