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

.github/actions/spelling/allow.txt

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

src/a2a/grpc/a2a_pb2.pyi

@@ -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/types.py

@@ -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
     """