feat!: Add SecurityRequirement to the domain API

client/transport/jsonrpc/src/test/java/io/a2a/client/transport/jsonrpc/JSONRPCTransportTest.java

@@ -57,6 +57,7 @@
 import io.a2a.spec.OpenIdConnectSecurityScheme;
 import io.a2a.spec.Part;
 import io.a2a.spec.PushNotificationConfig;
+import io.a2a.spec.SecurityRequirement;
 import io.a2a.spec.SecurityScheme;
 import io.a2a.spec.Task;
 import io.a2a.spec.TaskIdParams;
@@ -376,9 +377,9 @@ public void testA2AClientGetExtendedAgentCard() throws Exception {
         assertNotNull(securitySchemes);
         OpenIdConnectSecurityScheme google = (OpenIdConnectSecurityScheme) securitySchemes.get("google");
         assertEquals("https://accounts.google.com/.well-known/openid-configuration", google.openIdConnectUrl());
-        List<Map<String, List<String>>> security = agentCard.securityRequirements();
+        List<SecurityRequirement> security = agentCard.securityRequirements();
         assertEquals(1, security.size());
-        Map<String, List<String>> securityMap = security.get(0);
+        Map<String, List<String>> securityMap = security.get(0).schemes();
         List<String> scopes = securityMap.get("google");
         List<String> expectedScopes = List.of("openid", "profile", "email");
         assertEquals(expectedScopes, scopes);

client/transport/spi/src/main/java/io/a2a/client/transport/spi/interceptors/auth/AuthInterceptor.java

@@ -13,6 +13,7 @@
 import io.a2a.spec.HTTPAuthSecurityScheme;
 import io.a2a.spec.OAuth2SecurityScheme;
 import io.a2a.spec.OpenIdConnectSecurityScheme;
+import io.a2a.spec.SecurityRequirement;
 import io.a2a.spec.SecurityScheme;
 import org.jspecify.annotations.Nullable;
 
@@ -38,8 +39,11 @@ public PayloadAndHeaders intercept(String methodName, @Nullable Object payload,
         if (agentCard == null || agentCard.securityRequirements()== null || agentCard.securitySchemes() == null) {
             return new PayloadAndHeaders(payload, updatedHeaders);
         }
-        for (Map<String, List<String>> requirement : agentCard.securityRequirements()) {
-            for (String securitySchemeName : requirement.keySet()) {
+        for (SecurityRequirement requirement : agentCard.securityRequirements()) {
+            if (requirement == null) {
+                continue;
+            }
+            for (String securitySchemeName : requirement.schemes().keySet()) {
                 String credential = credentialService.getCredential(securitySchemeName, clientCallContext);
                 if (credential != null && agentCard.securitySchemes().containsKey(securitySchemeName)) {
                     SecurityScheme securityScheme = agentCard.securitySchemes().get(securitySchemeName);

client/transport/spi/src/test/java/io/a2a/client/transport/spi/interceptors/auth/AuthInterceptorTest.java

@@ -18,6 +18,7 @@
 import io.a2a.spec.OAuth2SecurityScheme;
 import io.a2a.spec.OAuthFlows;
 import io.a2a.spec.OpenIdConnectSecurityScheme;
+import io.a2a.spec.SecurityRequirement;
 import io.a2a.spec.SecurityScheme;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -235,7 +236,7 @@ void testAvailableSecuritySchemeNotInAgentCardSecuritySchemes() {
             .defaultInputModes(List.of("text"))
             .defaultOutputModes(List.of("text"))
             .skills(List.of())
-            .securityRequirements(List.of(Map.of(schemeName, List.of())))
+            .securityRequirements(List.of(SecurityRequirement.builder().scheme(schemeName, List.of()).build()))
             .securitySchemes(Map.of()) // no security schemes
             .build();
 
@@ -321,7 +322,7 @@ private AgentCard createAgentCard(String schemeName, SecurityScheme securitySche
             .defaultInputModes(List.of("text"))
             .defaultOutputModes(List.of("text"))
             .skills(List.of())
-            .securityRequirements(List.of(Map.of(schemeName, List.of())))
+            .securityRequirements(List.of(SecurityRequirement.builder().scheme(schemeName, List.of()).build()))
             .securitySchemes(Map.of(schemeName, securityScheme))
             .build();
     }

jsonrpc-common/src/main/java/io/a2a/jsonrpc/common/json/JsonUtil.java

@@ -16,12 +16,17 @@
 import static io.a2a.spec.FilePart.FILE;
 import static io.a2a.spec.TextPart.TEXT;
 import static java.lang.String.format;
+import static java.util.Collections.emptyMap;
 
 import java.io.StringReader;
 import java.lang.reflect.Type;
 import java.time.OffsetDateTime;
 import java.time.format.DateTimeFormatter;
 import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
@@ -55,6 +60,7 @@
 import io.a2a.spec.OpenIdConnectSecurityScheme;
 import io.a2a.spec.Part;
 import io.a2a.spec.PushNotificationNotSupportedError;
+import io.a2a.spec.SecurityRequirement;
 import io.a2a.spec.SecurityScheme;
 import io.a2a.spec.StreamingEventKind;
 import io.a2a.spec.Task;
@@ -76,8 +82,10 @@ private static GsonBuilder createBaseGsonBuilder() {
         return new GsonBuilder()
                 .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
                 .registerTypeAdapter(OffsetDateTime.class, new OffsetDateTimeTypeAdapter())
+                .registerTypeAdapter(SecurityRequirement.class, new SecurityRequirementTypeAdapter())
                 .registerTypeHierarchyAdapter(A2AError.class, new A2AErrorTypeAdapter())
                 .registerTypeHierarchyAdapter(FileContent.class, new FileContentTypeAdapter());
+
     }
 
     /**
@@ -841,4 +849,123 @@ SecurityScheme read(JsonReader in) throws java.io.IOException {
             };
         }
     }
+
+    /**
+     * Gson TypeAdapter for serializing and deserializing {@link SecurityRequirement}.
+     * <p>
+     * This adapter handles the JSON structure where a SecurityRequirement is represented
+     * as an object with a "schemes" field containing a map of security scheme names to
+     * StringList objects (matching the protobuf representation).
+     * <p>
+     * Serialization format:
+     * <pre>{@code
+     * {
+     *   "schemes": {
+     *     "oauth2": { "list": ["read", "write"] },
+     *     "apiKey": { "list": [] }
+     *   }
+     * }
+     * }</pre>
+     *
+     * @see SecurityRequirement
+     */
+    static class SecurityRequirementTypeAdapter extends TypeAdapter<SecurityRequirement> {
+
+        private static final String SCHEMES_FIELD = "schemes";
+        private static final String LIST_FIELD = "list";
+
+        @Override
+        public void write(JsonWriter out, SecurityRequirement value) throws java.io.IOException {
+            if (value == null) {
+                out.nullValue();
+                return;
+            }
+
+            out.beginObject();
+            out.name(SCHEMES_FIELD);
+
+            Map<String, List<String>> schemes = value.schemes();
+            if (schemes == null || schemes.isEmpty()) {
+                out.beginObject();
+                out.endObject();
+            } else {
+                out.beginObject();
+                for (Map.Entry<String, List<String>> entry : schemes.entrySet()) {
+                    out.name(entry.getKey());
+                    out.beginObject();
+                    out.name(LIST_FIELD);
+                    out.beginArray();
+                    List<String> scopes = entry.getValue();
+                    if (scopes != null) {
+                        for (String scope : scopes) {
+                            out.value(scope);
+                        }
+                    }
+                    out.endArray();
+                    out.endObject();
+                }
+                out.endObject();
+            }
+
+            out.endObject();
+        }
+
+        @Override
+        public @Nullable SecurityRequirement read(JsonReader in) throws java.io.IOException {
+            if (in.peek() == JsonToken.NULL) {
+                in.nextNull();
+                return null;
+            }
+
+            Map<String, List<String>> schemes = emptyMap();
+
+            in.beginObject();
+            while (in.hasNext()) {
+                String fieldName = in.nextName();
+                if (SCHEMES_FIELD.equals(fieldName)) {
+                    schemes = readSchemesMap(in);
+                } else {
+                    in.skipValue();
+                }
+            }
+            in.endObject();
+
+            return new SecurityRequirement(schemes);
+        }
+
+        private Map<String, List<String>> readSchemesMap(JsonReader in) throws java.io.IOException {
+            Map<String, List<String>> schemes = new LinkedHashMap<>();
+
+            in.beginObject();
+            while (in.hasNext()) {
+                String schemeName = in.nextName();
+                List<String> scopes = readStringList(in);
+                schemes.put(schemeName, scopes);
+            }
+            in.endObject();
+
+            return schemes;
+        }
+
+        private List<String> readStringList(JsonReader in) throws java.io.IOException {
+            List<String> scopes = new ArrayList<>();
+
+            in.beginObject();
+            while (in.hasNext()) {
+                String fieldName = in.nextName();
+                if (LIST_FIELD.equals(fieldName)) {
+                    in.beginArray();
+                    while (in.hasNext()) {
+                        scopes.add(in.nextString());
+                    }
+                    in.endArray();
+                } else {
+                    in.skipValue();
+                }
+            }
+            in.endObject();
+
+            return scopes;
+        }
+    }
 }

jsonrpc-common/src/test/java/io/a2a/jsonrpc/common/json/SecurityRequirementSerializationTest.java

@@ -0,0 +1,85 @@
+package io.a2a.jsonrpc.common.json;
+
+import static java.util.Collections.emptyMap;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import io.a2a.spec.SecurityRequirement;
+
+/**
+ * Tests for SecurityRequirement serialization and deserialization with JSON.
+ */
+class SecurityRequirementSerializationTest {
+
+    @Test
+    void testSecurityRequirementSerializationWithSingleScheme() throws JsonProcessingException {
+        SecurityRequirement requirement = SecurityRequirement.builder()
+                .scheme("oauth2", List.of("read", "write"))
+                .build();
+
+        String json = JsonUtil.toJson(requirement);
+        assertNotNull(json);
+
+        String expected = """
+            {"schemes":{"oauth2":{"list":["read","write"]}}}""";
+        assertEquals(expected, json);
+
+        SecurityRequirement deserialized = JsonUtil.fromJson(json, SecurityRequirement.class);
+        assertEquals(requirement, deserialized);
+    }
+
+    @Test
+    void testSecurityRequirementSerializationWithMultipleSchemes() throws JsonProcessingException {
+        SecurityRequirement requirement = SecurityRequirement.builder()
+                .scheme("oauth2", List.of("profile"))
+                .scheme("apiKey", List.of())
+                .build();
+
+        String json = JsonUtil.toJson(requirement);
+        assertNotNull(json);
+
+        String expected = """
+            {"schemes":{"oauth2":{"list":["profile"]},"apiKey":{"list":[]}}}""";
+        assertEquals(expected, json);
+
+        SecurityRequirement deserialized = JsonUtil.fromJson(json, SecurityRequirement.class);
+        assertEquals(requirement, deserialized);
+    }
+
+    @Test
+    void testSecurityRequirementSerializationWithEmptyScopes() throws JsonProcessingException {
+        SecurityRequirement requirement = SecurityRequirement.builder()
+                .scheme("apiKey", List.of())
+                .build();
+
+        String json = JsonUtil.toJson(requirement);
+        assertNotNull(json);
+
+        String expected = """
+                {"schemes":{"apiKey":{"list":[]}}}""";
+        assertEquals(expected, json);
+
+        SecurityRequirement deserialized = JsonUtil.fromJson(json, SecurityRequirement.class);
+        assertEquals(requirement, deserialized);
+    }
+
+    @Test
+    void testSecurityRequirementSerializationWithNullSchemes() throws JsonProcessingException {
+        SecurityRequirement requirement = new SecurityRequirement(emptyMap());
+
+        String json = JsonUtil.toJson(requirement);
+
+        assertNotNull(json);
+        String expected = """
+              {"schemes":{}}""";
+        assertEquals(expected, json);
+
+        SecurityRequirement deserialized = JsonUtil.fromJson(json, SecurityRequirement.class);
+        assertNotNull(deserialized);
+        assertEquals(requirement, deserialized);
+    }
+}

spec-grpc/src/main/java/io/a2a/grpc/mapper/AgentCardMapper.java

@@ -14,7 +14,7 @@
             AgentCapabilitiesMapper.class,
             AgentSkillMapper.class,
             SecuritySchemeMapper.class,
-            SecurityMapper.class,
+            SecurityRequirementMapper.class,
             AgentInterfaceMapper.class,
             AgentCardSignatureMapper.class
         })

spec-grpc/src/main/java/io/a2a/grpc/mapper/AgentSkillMapper.java

@@ -8,7 +8,7 @@
  */
 @Mapper(config = A2AProtoMapperConfig.class,
         collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED,
-        uses = SecurityMapper.class)
+        uses = SecurityRequirementMapper.class)
 public interface AgentSkillMapper {
 
     AgentSkillMapper INSTANCE = A2AMappers.getMapper(AgentSkillMapper.class);