enforcing URI-ness of SecurityScheme URLs

Author: brandonh-msft

src/A2A/Models/SecurityScheme.cs

@@ -108,14 +108,14 @@ public sealed class OAuth2SecurityScheme(OAuthFlows flows, string? description =
 /// </remarks>
 /// <param name="openIdConnectUrl">Well-known URL to discover the [[OpenID-Connect-Discovery]] provider metadata.</param>
 /// <param name="description">A short description for the security scheme. CommonMark syntax MAY be used for rich text representation.</param>
-public sealed class OpenIdConnectSecurityScheme(string openIdConnectUrl, string? description = null) : SecurityScheme(description)
+public sealed class OpenIdConnectSecurityScheme(Uri openIdConnectUrl, string? description = null) : SecurityScheme(description)
 {
     /// <summary>
     /// Well-known URL to discover the [[OpenID-Connect-Discovery]] provider metadata.
     /// </summary>
     [JsonPropertyName("openIdConnectUrl")]
     [JsonRequired]
-    public string OpenIdConnectUrl { get; init; } = openIdConnectUrl;
+    public Uri OpenIdConnectUrl { get; init; } = openIdConnectUrl;
 }
 
 /// <summary>
@@ -163,48 +163,25 @@ public sealed class OAuthFlows
 }
 
 /// <summary>
-/// Configuration details for a supported OAuth Authorization Code Flow.
+/// Configuration details applicable to all OAuth Flows.
 /// </summary>
 /// <remarks>
-/// Initializes a new instance of the <see cref="AuthorizationCodeOAuthFlow"/> class.
+/// Initializes a new instance of the <see cref="BaseOauthFlow"/> class.
 /// </remarks>
-/// <param name="authorizationUrl">
-/// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-/// </param>
-/// <param name="tokenUrl">
-/// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-/// </param>
 /// <param name="scopes">
 /// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
 /// </param>
 /// <param name="refreshUrl">
 /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 /// </param>
-public sealed class AuthorizationCodeOAuthFlow(
-    string authorizationUrl,
-    string tokenUrl,
-    IDictionary<string, string> scopes,
-    string? refreshUrl = null)
+public abstract class BaseOauthFlow(IDictionary<string, string> scopes,
+    Uri? refreshUrl = null)
 {
-    /// <summary>
-    /// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("authorizationUrl")]
-    [JsonRequired]
-    public string AuthorizationUrl { get; init; } = authorizationUrl;
-
-    /// <summary>
-    /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("tokenUrl")]
-    [JsonRequired]
-    public string TokenUrl { get; init; } = tokenUrl;
-
     /// <summary>
     /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     /// </summary>
     [JsonPropertyName("refreshUrl")]
-    public string? RefreshUrl { get; init; } = refreshUrl;
+    public Uri? RefreshUrl { get; init; } = refreshUrl;
 
     /// <summary>
     /// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
@@ -215,10 +192,10 @@ public sealed class AuthorizationCodeOAuthFlow(
 }
 
 /// <summary>
-/// Configuration details for a supported OAuth Client Credentials Flow.
+/// Configuration details for an OAuth Flow requiring a Token URL.
 /// </summary>
 /// <remarks>
-/// Initializes a new instance of the <see cref="ClientCredentialsOAuthFlow"/> class.
+/// Initializes a new instance of the <see cref="TokenUrlOauthFlow"/> class.
 /// </remarks>
 /// <param name="tokenUrl">
 /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
@@ -229,38 +206,54 @@ public sealed class AuthorizationCodeOAuthFlow(
 /// <param name="refreshUrl">
 /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 /// </param>
-public sealed class ClientCredentialsOAuthFlow(
-    string tokenUrl,
+public abstract class TokenUrlOauthFlow(Uri tokenUrl,
     IDictionary<string, string> scopes,
-    string? refreshUrl = null)
+    Uri? refreshUrl = null) : BaseOauthFlow(scopes, refreshUrl)
 {
     /// <summary>
     /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     /// </summary>
     [JsonPropertyName("tokenUrl")]
     [JsonRequired]
-    public string TokenUrl { get; init; } = tokenUrl;
-
-    /// <summary>
-    /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("refreshUrl")]
-    public string? RefreshUrl { get; init; } = refreshUrl;
+    public Uri TokenUrl { get; init; } = tokenUrl;
+}
 
+/// <summary>
+/// Configuration details for an OAuth Flow requiring an Authorization URL.
+/// </summary>
+/// <remarks>
+/// Initializes a new instance of the <see cref="AuthUrlOauthFlow"/> class.
+/// </remarks>
+/// <param name="authorizationUrl">
+/// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+/// <param name="scopes">
+/// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+/// </param>
+/// <param name="refreshUrl">
+/// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+public abstract class AuthUrlOauthFlow(Uri authorizationUrl,
+    IDictionary<string, string> scopes,
+    Uri? refreshUrl = null) : BaseOauthFlow(scopes, refreshUrl)
+{
     /// <summary>
-    /// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+    /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     /// </summary>
-    [JsonPropertyName("scopes")]
+    [JsonPropertyName("authorizationUrl")]
     [JsonRequired]
-    public IDictionary<string, string> Scopes { get; init; } = scopes;
+    public Uri AuthorizationUrl { get; init; } = authorizationUrl;
 }
 
 /// <summary>
-/// Configuration details for a supported OAuth Resource Owner Password Flow.
+/// Configuration details for a supported OAuth Authorization Code Flow.
 /// </summary>
 /// <remarks>
-/// Initializes a new instance of the <see cref="PasswordOAuthFlow"/> class.
+/// Initializes a new instance of the <see cref="AuthorizationCodeOAuthFlow"/> class.
 /// </remarks>
+/// <param name="authorizationUrl">
+/// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
 /// <param name="tokenUrl">
 /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 /// </param>
@@ -270,31 +263,61 @@ public sealed class ClientCredentialsOAuthFlow(
 /// <param name="refreshUrl">
 /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 /// </param>
-public sealed class PasswordOAuthFlow(
-    string tokenUrl,
+public sealed class AuthorizationCodeOAuthFlow(
+    Uri authorizationUrl,
+    Uri tokenUrl,
     IDictionary<string, string> scopes,
-    string? refreshUrl = null)
+    Uri? refreshUrl = null) : TokenUrlOauthFlow(tokenUrl, scopes, refreshUrl)
 {
     /// <summary>
-    /// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    /// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     /// </summary>
-    [JsonPropertyName("tokenUrl")]
+    [JsonPropertyName("authorizationUrl")]
     [JsonRequired]
-    public string TokenUrl { get; init; } = tokenUrl;
+    public Uri AuthorizationUrl { get; init; } = authorizationUrl;
+}
 
-    /// <summary>
-    /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("refreshUrl")]
-    public string? RefreshUrl { get; init; } = refreshUrl;
+/// <summary>
+/// Configuration details for a supported OAuth Client Credentials Flow.
+/// </summary>
+/// <remarks>
+/// Initializes a new instance of the <see cref="ClientCredentialsOAuthFlow"/> class.
+/// </remarks>
+/// <param name="tokenUrl">
+/// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+/// <param name="scopes">
+/// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+/// </param>
+/// <param name="refreshUrl">
+/// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+public sealed class ClientCredentialsOAuthFlow(
+    Uri tokenUrl,
+    IDictionary<string, string> scopes,
+    Uri? refreshUrl = null) : TokenUrlOauthFlow(tokenUrl, scopes, refreshUrl)
+{ }
 
-    /// <summary>
-    /// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
-    /// </summary>
-    [JsonPropertyName("scopes")]
-    [JsonRequired]
-    public IDictionary<string, string> Scopes { get; init; } = scopes;
-}
+/// <summary>
+/// Configuration details for a supported OAuth Resource Owner Password Flow.
+/// </summary>
+/// <remarks>
+/// Initializes a new instance of the <see cref="PasswordOAuthFlow"/> class.
+/// </remarks>
+/// <param name="tokenUrl">
+/// The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+/// <param name="scopes">
+/// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+/// </param>
+/// <param name="refreshUrl">
+/// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+/// </param>
+public sealed class PasswordOAuthFlow(
+    Uri tokenUrl,
+    IDictionary<string, string> scopes,
+    Uri? refreshUrl = null) : TokenUrlOauthFlow(tokenUrl, scopes, refreshUrl)
+{ }
 
 /// <summary>
 /// Configuration details for a supported OAuth Implicit Flow.
@@ -312,27 +335,7 @@ public sealed class PasswordOAuthFlow(
 /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 /// </param>
 public sealed class ImplicitOAuthFlow(
-    string authorizationUrl,
+    Uri authorizationUrl,
     IDictionary<string, string> scopes,
-    string? refreshUrl = null)
-{
-    /// <summary>
-    /// The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("authorizationUrl")]
-    [JsonRequired]
-    public string AuthorizationUrl { get; init; } = authorizationUrl;
-
-    /// <summary>
-    /// The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
-    /// </summary>
-    [JsonPropertyName("refreshUrl")]
-    public string? RefreshUrl { get; init; } = refreshUrl;
-
-    /// <summary>
-    /// The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
-    /// </summary>
-    [JsonPropertyName("scopes")]
-    [JsonRequired]
-    public IDictionary<string, string> Scopes { get; init; } = scopes;
-}
+    Uri? refreshUrl = null) : AuthUrlOauthFlow(authorizationUrl, scopes, refreshUrl)
+{ }

tests/A2A.UnitTests/Models/SecuritySchemeTests.cs

@@ -87,7 +87,7 @@ public void OAuth2SecurityScheme_SerializesAndDeserializesCorrectly()
         // Arrange
         var flows = new OAuthFlows
         {
-            Password = new("https://example.com/token", scopes: new Dictionary<string, string>() { ["read"] = "Read access", ["write"] = "Write access" }),
+            Password = new(new("https://example.com/token"), scopes: new Dictionary<string, string>() { ["read"] = "Read access", ["write"] = "Write access" }),
         };
         SecurityScheme scheme = new OAuth2SecurityScheme(flows, "OAuth2 authentication");
 
@@ -105,7 +105,7 @@ public void OAuth2SecurityScheme_SerializesAndDeserializesCorrectly()
         Assert.Null(deserialized.Flows.Implicit);
         Assert.Null(deserialized.Flows.AuthorizationCode);
         Assert.NotNull(deserialized.Flows.Password);
-        Assert.Equal("https://example.com/token", deserialized.Flows.Password.TokenUrl);
+        Assert.Equal("https://example.com/token", deserialized.Flows.Password.TokenUrl.ToString());
         Assert.NotNull(deserialized.Flows.Password.Scopes);
         Assert.Equal(2, deserialized.Flows.Password.Scopes.Count);
         Assert.Contains("read", deserialized.Flows.Password.Scopes.Keys);
@@ -118,7 +118,7 @@ public void OAuth2SecurityScheme_SerializesAndDeserializesCorrectly()
     public void OpenIdConnectSecurityScheme_SerializesAndDeserializesCorrectly()
     {
         // Arrange
-        SecurityScheme scheme = new OpenIdConnectSecurityScheme("https://example.com/.well-known/openid_configuration", "OpenID Connect authentication");
+        SecurityScheme scheme = new OpenIdConnectSecurityScheme(new("https://example.com/.well-known/openid_configuration"), "OpenID Connect authentication");
 
         // Act
         var json = JsonSerializer.Serialize(scheme, s_jsonOptions);
@@ -129,7 +129,7 @@ public void OpenIdConnectSecurityScheme_SerializesAndDeserializesCorrectly()
         Assert.Contains("\"description\": \"OpenID Connect authentication\"", json);
         Assert.NotNull(deserialized);
         Assert.Equal("OpenID Connect authentication", deserialized.Description);
-        Assert.Equal("https://example.com/.well-known/openid_configuration", deserialized.OpenIdConnectUrl);
+        Assert.Equal("https://example.com/.well-known/openid_configuration", deserialized.OpenIdConnectUrl.ToString());
     }
 
     [Fact]