feat!: Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security (#362)

# Description

This PR makes changes to our security representations in AgentCards:

1. Adds a new MutualTLSSecurityScheme type for indicating mTLS
connection requirements. This matches the same field in the OpenAPI
specification v3.1. This type is pretty lacking: there is no way to
indicate any requirements on the certificate that is presented by the
client. I expect we'll want to extend this in the future (for example,
we may want to allow an agent to indicate that a SPIFFE certificate must
be presented). For now, users are advised to put requirements in the
description field.
2. Adds a field for specifying a URL for OAuth2 provider metadata. This
is planned for OpenAPI Specification v3.2, which has not yet been
released. This allows clients to fetch additional information about the
OAuth provider, such as to discover if they support Dynamic Client
Registration.
3. Allows AgentSkills to specify a `security` field. This allows agents
to indicate security requirements for leveraging a particular skill.

I also clarified the usage and expectations for the `security` field in
the base AgentCard.

This change is marked backwards incompatible due to the addition of the
MutualTLSSecurityScheme, which adds a new type to an exhaustive enum
(the security scheme `anyOf`).

Release-As: 0.3.0

Protocol Update:
a2aproject/A2A@e162c0c

Author: a2a-bot

.github/actions/spelling/allow.txt

@@ -39,6 +39,7 @@ genai
 getkwargs
 gle
 GVsb
+ietf
 initdb
 inmemory
 INR

src/a2a/grpc/a2a_pb2.py

@@ -277,22 +277,24 @@ class AgentExtension(_message.Message):
     def __init__(self, uri: _Optional[str] = ..., description: _Optional[str] = ..., required: bool = ..., params: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...
 
 class AgentSkill(_message.Message):
-    __slots__ = ("id", "name", "description", "tags", "examples", "input_modes", "output_modes")
+    __slots__ = ("id", "name", "description", "tags", "examples", "input_modes", "output_modes", "security")
     ID_FIELD_NUMBER: _ClassVar[int]
     NAME_FIELD_NUMBER: _ClassVar[int]
     DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
     TAGS_FIELD_NUMBER: _ClassVar[int]
     EXAMPLES_FIELD_NUMBER: _ClassVar[int]
     INPUT_MODES_FIELD_NUMBER: _ClassVar[int]
     OUTPUT_MODES_FIELD_NUMBER: _ClassVar[int]
+    SECURITY_FIELD_NUMBER: _ClassVar[int]
     id: str
     name: str
     description: str
     tags: _containers.RepeatedScalarFieldContainer[str]
     examples: _containers.RepeatedScalarFieldContainer[str]
     input_modes: _containers.RepeatedScalarFieldContainer[str]
     output_modes: _containers.RepeatedScalarFieldContainer[str]
-    def __init__(self, id: _Optional[str] = ..., name: _Optional[str] = ..., description: _Optional[str] = ..., tags: _Optional[_Iterable[str]] = ..., examples: _Optional[_Iterable[str]] = ..., input_modes: _Optional[_Iterable[str]] = ..., output_modes: _Optional[_Iterable[str]] = ...) -> None: ...
+    security: _containers.RepeatedCompositeFieldContainer[Security]
+    def __init__(self, id: _Optional[str] = ..., name: _Optional[str] = ..., description: _Optional[str] = ..., tags: _Optional[_Iterable[str]] = ..., examples: _Optional[_Iterable[str]] = ..., input_modes: _Optional[_Iterable[str]] = ..., output_modes: _Optional[_Iterable[str]] = ..., security: _Optional[_Iterable[_Union[Security, _Mapping]]] = ...) -> None: ...
 
 class AgentCardSignature(_message.Message):
     __slots__ = ("protected", "signature", "header")
@@ -332,16 +334,18 @@ class Security(_message.Message):
     def __init__(self, schemes: _Optional[_Mapping[str, StringList]] = ...) -> None: ...
 
 class SecurityScheme(_message.Message):
-    __slots__ = ("api_key_security_scheme", "http_auth_security_scheme", "oauth2_security_scheme", "open_id_connect_security_scheme")
+    __slots__ = ("api_key_security_scheme", "http_auth_security_scheme", "oauth2_security_scheme", "open_id_connect_security_scheme", "mtls_security_scheme")
     API_KEY_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     HTTP_AUTH_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     OAUTH2_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     OPEN_ID_CONNECT_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
+    MTLS_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     api_key_security_scheme: APIKeySecurityScheme
     http_auth_security_scheme: HTTPAuthSecurityScheme
     oauth2_security_scheme: OAuth2SecurityScheme
     open_id_connect_security_scheme: OpenIdConnectSecurityScheme
-    def __init__(self, api_key_security_scheme: _Optional[_Union[APIKeySecurityScheme, _Mapping]] = ..., http_auth_security_scheme: _Optional[_Union[HTTPAuthSecurityScheme, _Mapping]] = ..., oauth2_security_scheme: _Optional[_Union[OAuth2SecurityScheme, _Mapping]] = ..., open_id_connect_security_scheme: _Optional[_Union[OpenIdConnectSecurityScheme, _Mapping]] = ...) -> None: ...
+    mtls_security_scheme: MutualTlsSecurityScheme
+    def __init__(self, api_key_security_scheme: _Optional[_Union[APIKeySecurityScheme, _Mapping]] = ..., http_auth_security_scheme: _Optional[_Union[HTTPAuthSecurityScheme, _Mapping]] = ..., oauth2_security_scheme: _Optional[_Union[OAuth2SecurityScheme, _Mapping]] = ..., open_id_connect_security_scheme: _Optional[_Union[OpenIdConnectSecurityScheme, _Mapping]] = ..., mtls_security_scheme: _Optional[_Union[MutualTlsSecurityScheme, _Mapping]] = ...) -> None: ...
 
 class APIKeySecurityScheme(_message.Message):
     __slots__ = ("description", "location", "name")
@@ -364,12 +368,14 @@ class HTTPAuthSecurityScheme(_message.Message):
     def __init__(self, description: _Optional[str] = ..., scheme: _Optional[str] = ..., bearer_format: _Optional[str] = ...) -> None: ...
 
 class OAuth2SecurityScheme(_message.Message):
-    __slots__ = ("description", "flows")
+    __slots__ = ("description", "flows", "oauth2_metadata_url")
     DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
     FLOWS_FIELD_NUMBER: _ClassVar[int]
+    OAUTH2_METADATA_URL_FIELD_NUMBER: _ClassVar[int]
     description: str
     flows: OAuthFlows
-    def __init__(self, description: _Optional[str] = ..., flows: _Optional[_Union[OAuthFlows, _Mapping]] = ...) -> None: ...
+    oauth2_metadata_url: str
+    def __init__(self, description: _Optional[str] = ..., flows: _Optional[_Union[OAuthFlows, _Mapping]] = ..., oauth2_metadata_url: _Optional[str] = ...) -> None: ...
 
 class OpenIdConnectSecurityScheme(_message.Message):
     __slots__ = ("description", "open_id_connect_url")
@@ -379,6 +385,12 @@ class OpenIdConnectSecurityScheme(_message.Message):
     open_id_connect_url: str
     def __init__(self, description: _Optional[str] = ..., open_id_connect_url: _Optional[str] = ...) -> None: ...
 
+class MutualTlsSecurityScheme(_message.Message):
+    __slots__ = ("description",)
+    DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
+    description: str
+    def __init__(self, description: _Optional[str] = ...) -> None: ...
+
 class OAuthFlows(_message.Message):
     __slots__ = ("authorization_code", "client_credentials", "implicit", "password")
     AUTHORIZATION_CODE_FIELD_NUMBER: _ClassVar[int]

src/a2a/grpc/a2a_pb2.pyi

@@ -164,6 +164,15 @@ class AgentSkill(A2ABaseModel):
     """
     The set of supported output MIME types for this skill, overriding the agent's defaults.
     """
+    security: list[dict[str, list[str]]] | None = Field(
+        default=None, examples=[[{'google': ['oidc']}]]
+    )
+    """
+    Security schemes necessary for the agent to leverage this skill.
+    As in the overall AgentCard.security, this list represents a logical OR of security
+    requirement objects. Each object is a set of security schemes that must be used together
+    (a logical AND).
+    """
     tags: list[str] = Field(
         ..., examples=[['cooking', 'customer support', 'billing']]
     )
@@ -730,6 +739,21 @@ class MethodNotFoundError(A2ABaseModel):
     """
 
 
+class MutualTLSSecurityScheme(A2ABaseModel):
+    """
+    Defines a security scheme using mTLS authentication.
+    """
+
+    description: str | None = None
+    """
+    An optional description for the security scheme.
+    """
+    type: Literal['mutualTLS'] = 'mutualTLS'
+    """
+    The type of the security scheme. Must be 'mutualTLS'.
+    """
+
+
 class OpenIdConnectSecurityScheme(A2ABaseModel):
     """
     Defines a security scheme using OpenID Connect.
@@ -1486,6 +1510,11 @@ class OAuth2SecurityScheme(A2ABaseModel):
     """
     An object containing configuration information for the supported OAuth 2.0 flows.
     """
+    oauth2_metadata_url: str | None = None
+    """
+    URL to the oauth2 authorization server metadata
+    [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
+    """
     type: Literal['oauth2'] = 'oauth2'
     """
     The type of the security scheme. Must be 'oauth2'.
@@ -1498,13 +1527,15 @@ class SecurityScheme(
         | HTTPAuthSecurityScheme
         | OAuth2SecurityScheme
         | OpenIdConnectSecurityScheme
+        | MutualTLSSecurityScheme
     ]
 ):
     root: (
         APIKeySecurityScheme
         | HTTPAuthSecurityScheme
         | OAuth2SecurityScheme
         | OpenIdConnectSecurityScheme
+        | MutualTLSSecurityScheme
     )
     """
     Defines a security scheme that can be used to secure an agent's endpoints.
@@ -1762,10 +1793,16 @@ class AgentCard(A2ABaseModel):
     """
     Information about the agent's service provider.
     """
-    security: list[dict[str, list[str]]] | None = None
+    security: list[dict[str, list[str]]] | None = Field(
+        default=None,
+        examples=[[{'oauth': ['read']}, {'api-key': [], 'mtls': []}]],
+    )
     """
     A list of security requirement objects that apply to all agent interactions. Each object
     lists security schemes that can be used. Follows the OpenAPI 3.0 Security Requirement Object.
+    This list can be seen as an OR of ANDs. Each object in the list describes one possible
+    set of security requirements that must be present on a request. This allows specifying,
+    for example, "callers must either use OAuth OR an API Key AND mTLS."
     """
     security_schemes: dict[str, SecurityScheme] | None = None
     """