Authorization Server & Protected Resource Metadata inspection

从 ClientOAuthOptions 以及获取授权服务器和受保护资源元数据的 MCP 客户端路径开始。检查现有的 AuthorizationRedirectDelegate 和相关的身份验证代码，然后比较提议的 delegate 和 ClientOAuthEvents 设计，包括缓存问题。完成的标准是，所选的公共 API 能够一致地提供对所请求元数据的访问，并且为所选 callbacks 提供覆盖。

Sometimes we need access to the AS metadata & PRM. For example, if we want to implement logout we need access to the logout endpoint which resides on the AS metadata, and this AS metadata is already fetched by the MCP client. Another use case is to conditionally inspect the claims in the access token based on the AS that was used for the authentication (e.g getting the user name & display name claims etc.)

a.

One design might be to add a few more delegates to ClientOAuthOptions:

namespace ModelContextProtocol.Authentication;

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the delegate called when authorization server metadata is retrieved.
    /// </summary>
    public Action<AuthorizationServerMetadata> OnAuthorizationServerMetadataRetrieved { get; set; }

    /// <summary>
    /// Gets or sets the delegate called when protected resource metadata is retrieved.
    /// </summary>
    public Action<ProtectedResourceMetadata> OnProtectedResourceMetadataRetrieved { get; set; }

    ...
}

Having them as delegates/events avoids having to manage and expose state on the McpClient instance.

b.

Another design might be to use something similar to the pattern in used by ASP.NET Core auth.

namespace ModelContextProtocol.Authentication;

public sealed class RetrievingAuthorizationServerMetadataContext ...;
public sealed class RetrievedAuthorizationServerMetadataContext ...;

public sealed class RetrievingProtectedResourceMetadataContext ...;
public sealed class RetrievedProtectedResourceMetadataContext ...;

public sealed class ClientOAuthEvents
{
    /// <summary>
    /// Gets or sets the delegate called before authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievingAuthorizationServerMetadataContext, Task> OnRetrievingAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievedAuthorizationServerMetadataContext, Task> OnRetrievedAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called before protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievingProtectedResourceMetadataContext, Task> OnRetrievingProtectedResourceMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievedProtectedResourceMetadataContext, Task> OnRetrievedProtectedResourceMetadata { get; set; } = ...;
}

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the <see cref="ClientOAuthEvents" />.
    /// </summary>
    public ClientOAuthEvents Events { get; set; } = new();

    ...
}

The idea behind the "Retrieving" variants is that it allows the user to implement metadata caching, although it also expands the ability for the user to shoot themselves in the foot. I suppose it depends on if caching is a user level concern or a library level concern.

The AuthorizationRedirectDelegate on ClientOAuthOptions can also be moved into the ClientOAuthEvents class to make the surface more uniform.

The overall surface may be reduced if we combine them into a single OnRetrievedMetadata and OnRetrievingMetadata, but trickiness in the contexts I suppose.