feat(spec): Add SecurityRequirement model + parser

Author: thced

src/main/java/com/retailsvc/http/spec/security/SecurityRequirement.java

@@ -0,0 +1,14 @@
+package com.retailsvc.http.spec.security;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * One OR-branch in a {@code security} list. Each entry in {@link #schemes} is AND-ed: every scheme
+ * name must be satisfied for the requirement to hold. Scopes are preserved but unused in v1.
+ */
+public record SecurityRequirement(Map<String, List<String>> schemes) {
+  public SecurityRequirement {
+    schemes = Map.copyOf(schemes);
+  }
+}

src/main/java/com/retailsvc/http/spec/security/SecuritySchemeParser.java

@@ -5,6 +5,9 @@
 import com.retailsvc.http.spec.security.SecurityScheme.HttpBasic;
 import com.retailsvc.http.spec.security.SecurityScheme.HttpBearer;
 import com.retailsvc.http.spec.security.SecurityScheme.Unsupported;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
@@ -33,6 +36,30 @@ private static SecurityScheme parseApiKey(Map<String, Object> raw) {
     return new ApiKey(name, Location.valueOf(in.toUpperCase(Locale.ROOT)));
   }
 
+  @SuppressWarnings("unchecked")
+  public static List<SecurityRequirement> parseRequirements(List<Object> raw) {
+    if (raw == null || raw.isEmpty()) {
+      return List.of();
+    }
+    List<SecurityRequirement> out = new ArrayList<>(raw.size());
+    for (Object entry : raw) {
+      if (!(entry instanceof Map<?, ?> map)) {
+        throw new IllegalArgumentException("security requirement entries must be objects");
+      }
+      Map<String, List<String>> schemes = new LinkedHashMap<>();
+      for (var e : map.entrySet()) {
+        String name = (String) e.getKey();
+        List<String> scopes =
+            e.getValue() instanceof List<?> list
+                ? list.stream().map(Object::toString).toList()
+                : List.of();
+        schemes.put(name, scopes);
+      }
+      out.add(new SecurityRequirement(schemes));
+    }
+    return List.copyOf(out);
+  }
+
   private static SecurityScheme parseHttp(Map<String, Object> raw) {
     String scheme = (String) raw.get("scheme");
     if (scheme == null) {

src/test/java/com/retailsvc/http/spec/security/SecurityRequirementParseTest.java

@@ -0,0 +1,39 @@
+package com.retailsvc.http.spec.security;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class SecurityRequirementParseTest {
+
+  @Test
+  void singleRequirementParses() {
+    List<Object> raw = List.of(Map.of("bearerAuth", List.of()));
+    List<SecurityRequirement> req = SecuritySchemeParser.parseRequirements(raw);
+    assertThat(req).containsExactly(new SecurityRequirement(Map.of("bearerAuth", List.of())));
+  }
+
+  @Test
+  void andGroupParses() {
+    List<Object> raw = List.of(Map.of("apiKey", List.of(), "bearer", List.of("admin")));
+    List<SecurityRequirement> req = SecuritySchemeParser.parseRequirements(raw);
+    assertThat(req).hasSize(1);
+    assertThat(req.get(0).schemes())
+        .containsEntry("apiKey", List.of())
+        .containsEntry("bearer", List.of("admin"));
+  }
+
+  @Test
+  void orGroupsParse() {
+    List<Object> raw = List.of(Map.of("apiKey", List.of()), Map.of("bearer", List.of()));
+    List<SecurityRequirement> req = SecuritySchemeParser.parseRequirements(raw);
+    assertThat(req).hasSize(2);
+  }
+
+  @Test
+  void nullReturnsEmptyList() {
+    assertThat(SecuritySchemeParser.parseRequirements(null)).isEmpty();
+  }
+}