feat(spec): Add SecurityScheme sealed model + parser

Author: thced

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

@@ -0,0 +1,25 @@
+package com.retailsvc.http.spec.security;
+
+import java.util.Optional;
+
+public sealed interface SecurityScheme
+    permits SecurityScheme.ApiKey,
+        SecurityScheme.HttpBearer,
+        SecurityScheme.HttpBasic,
+        SecurityScheme.Unsupported {
+
+  record ApiKey(String name, Location location) implements SecurityScheme {
+    public enum Location {
+      HEADER,
+      QUERY,
+      COOKIE
+    }
+  }
+
+  record HttpBearer(Optional<String> bearerFormat) implements SecurityScheme {}
+
+  record HttpBasic() implements SecurityScheme {}
+
+  /** Parsed but unsupported in v1 (oauth2, openIdConnect, mutualTLS). */
+  record Unsupported(String type) implements SecurityScheme {}
+}

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

@@ -0,0 +1,47 @@
+package com.retailsvc.http.spec.security;
+
+import com.retailsvc.http.spec.security.SecurityScheme.ApiKey;
+import com.retailsvc.http.spec.security.SecurityScheme.ApiKey.Location;
+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.Locale;
+import java.util.Map;
+import java.util.Optional;
+
+public final class SecuritySchemeParser {
+  private SecuritySchemeParser() {}
+
+  public static SecurityScheme parse(Map<String, Object> raw) {
+    String type = (String) raw.get("type");
+    if (type == null) {
+      throw new IllegalArgumentException("securityScheme missing required 'type'");
+    }
+    return switch (type) {
+      case "apiKey" -> parseApiKey(raw);
+      case "http" -> parseHttp(raw);
+      default -> new Unsupported(type);
+    };
+  }
+
+  private static SecurityScheme parseApiKey(Map<String, Object> raw) {
+    String name = (String) raw.get("name");
+    String in = (String) raw.get("in");
+    if (name == null || in == null) {
+      throw new IllegalArgumentException("apiKey scheme requires 'name' and 'in'");
+    }
+    return new ApiKey(name, Location.valueOf(in.toUpperCase(Locale.ROOT)));
+  }
+
+  private static SecurityScheme parseHttp(Map<String, Object> raw) {
+    String scheme = (String) raw.get("scheme");
+    if (scheme == null) {
+      throw new IllegalArgumentException("http securityScheme requires 'scheme'");
+    }
+    return switch (scheme.toLowerCase(Locale.ROOT)) {
+      case "bearer" -> new HttpBearer(Optional.ofNullable((String) raw.get("bearerFormat")));
+      case "basic" -> new HttpBasic();
+      default -> new Unsupported("http:" + scheme);
+    };
+  }
+}

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

@@ -0,0 +1,39 @@
+package com.retailsvc.http.spec.security;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.retailsvc.http.spec.security.SecurityScheme.ApiKey;
+import com.retailsvc.http.spec.security.SecurityScheme.ApiKey.Location;
+import java.util.Map;
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+
+class SchemeParserTest {
+
+  @Test
+  void apiKeyHeaderParses() {
+    var scheme =
+        SecuritySchemeParser.parse(Map.of("type", "apiKey", "name", "X-API-Key", "in", "header"));
+    assertThat(scheme).isEqualTo(new ApiKey("X-API-Key", Location.HEADER));
+  }
+
+  @Test
+  void httpBearerParses() {
+    var scheme =
+        SecuritySchemeParser.parse(
+            Map.of("type", "http", "scheme", "bearer", "bearerFormat", "JWT"));
+    assertThat(scheme).isEqualTo(new SecurityScheme.HttpBearer(Optional.of("JWT")));
+  }
+
+  @Test
+  void httpBasicParses() {
+    var scheme = SecuritySchemeParser.parse(Map.of("type", "http", "scheme", "basic"));
+    assertThat(scheme).isEqualTo(new SecurityScheme.HttpBasic());
+  }
+
+  @Test
+  void unknownTypeMapsToUnsupported() {
+    var scheme = SecuritySchemeParser.parse(Map.of("type", "oauth2"));
+    assertThat(scheme).isEqualTo(new SecurityScheme.Unsupported("oauth2"));
+  }
+}