feat: Fail fast at boot if security validators are missing

Builder.build() now calls validateSecurityWiring() before constructing
the server when externalAuth is false. It collects all scheme names
referenced by any operation's effective security, and throws
IllegalStateException for unknown, Unsupported, or validator-less schemes.

Author: thced

src/main/java/com/retailsvc/http/OpenApiServer.java

@@ -14,6 +14,8 @@
 import com.retailsvc.http.internal.TextTypeMapper;
 import com.retailsvc.http.spec.Operation;
 import com.retailsvc.http.spec.Spec;
+import com.retailsvc.http.spec.security.SecurityRequirement;
+import com.retailsvc.http.spec.security.SecurityScheme;
 import com.retailsvc.http.validate.DefaultValidator;
 import com.sun.net.httpserver.HttpContext;
 import com.sun.net.httpserver.HttpHandler;
@@ -22,10 +24,12 @@
 import java.net.InetSocketAddress;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.stream.Collectors;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -274,6 +278,9 @@ public OpenApiServer build() throws IOException {
               "extra handler path " + path + " conflicts with spec basePath " + basePath);
         }
       }
+      if (!externalAuth) {
+        validateSecurityWiring(spec, securityValidators);
+      }
       Map<String, TypeMapper> resolved = resolveBodyMappers(bodyMappers);
       HandlerConfig handlerConfig =
           new HandlerConfig(
@@ -287,6 +294,30 @@ public OpenApiServer build() throws IOException {
       return new OpenApiServer(spec, resolved, handlerConfig, port, shutdownTimeoutSeconds);
     }
 
+    private static void validateSecurityWiring(Spec spec, Map<String, SchemeValidator> validators) {
+      Set<String> referenced = new LinkedHashSet<>();
+      for (Operation op : spec.operations()) {
+        for (SecurityRequirement req : op.security().orElse(spec.security())) {
+          referenced.addAll(req.schemes().keySet());
+        }
+      }
+      for (String name : referenced) {
+        SecurityScheme scheme = spec.securitySchemes().get(name);
+        if (scheme == null) {
+          throw new IllegalStateException(
+              "security requirement references unknown scheme '" + name + "'");
+        }
+        if (scheme instanceof SecurityScheme.Unsupported u) {
+          throw new IllegalStateException(
+              "scheme '" + name + "' uses unsupported type '" + u.type() + "'");
+        }
+        if (!validators.containsKey(name)) {
+          throw new IllegalStateException(
+              "no SchemeValidator registered for security scheme '" + name + "'");
+        }
+      }
+    }
+
     private static Map<String, TypeMapper> resolveBodyMappers(
         Map<String, TypeMapper> userSupplied) {
       LinkedHashMap<String, TypeMapper> out = new LinkedHashMap<>();

src/test/java/com/retailsvc/http/SecurityBootValidationTest.java

@@ -0,0 +1,127 @@
+package com.retailsvc.http;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.retailsvc.http.spec.Spec;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class SecurityBootValidationTest {
+
+  private static Map<String, Object> raw(
+      Map<String, Object> securitySchemes, List<Object> rootSecurity, List<Object> opSecurity) {
+    return Map.of(
+        "openapi",
+        "3.1.0",
+        "info",
+        Map.of("title", "T", "version", "1"),
+        "servers",
+        List.of(Map.of("url", "/v1")),
+        "security",
+        rootSecurity == null ? List.of() : rootSecurity,
+        "components",
+        securitySchemes == null ? Map.of() : Map.of("securitySchemes", securitySchemes),
+        "paths",
+        Map.of(
+            "/x",
+            Map.of(
+                "get",
+                opSecurity == null
+                    ? Map.of(
+                        "operationId",
+                        "getX",
+                        "responses",
+                        Map.of("200", Map.of("description", "ok")))
+                    : Map.of(
+                        "operationId",
+                        "getX",
+                        "security",
+                        opSecurity,
+                        "responses",
+                        Map.of("200", Map.of("description", "ok"))))));
+  }
+
+  @Test
+  void missingValidatorThrows() {
+    Map<String, Object> r =
+        raw(
+            Map.of("bearerAuth", Map.of("type", "http", "scheme", "bearer")),
+            List.of(),
+            List.of(Map.of("bearerAuth", List.of())));
+    Spec spec = Spec.from(r);
+
+    assertThatThrownBy(
+            () ->
+                OpenApiServer.builder()
+                    .spec(spec)
+                    .handlers(Map.of("getX", req -> Response.ok(Map.of())))
+                    .port(0)
+                    .build())
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("bearerAuth");
+  }
+
+  @Test
+  void unsupportedSchemeThrowsWhenReferenced() {
+    Map<String, Object> r =
+        raw(
+            Map.of("oauth", Map.of("type", "oauth2")),
+            List.of(),
+            List.of(Map.of("oauth", List.of())));
+    Spec spec = Spec.from(r);
+
+    assertThatThrownBy(
+            () ->
+                OpenApiServer.builder()
+                    .spec(spec)
+                    .handlers(Map.of("getX", req -> Response.ok(Map.of())))
+                    .port(0)
+                    .build())
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("unsupported");
+  }
+
+  @Test
+  void unknownSchemeReferenceThrows() {
+    Map<String, Object> r =
+        raw(
+            Map.of(), // no schemes defined
+            List.of(),
+            List.of(Map.of("missingScheme", List.of())));
+    Spec spec = Spec.from(r);
+
+    assertThatThrownBy(
+            () ->
+                OpenApiServer.builder()
+                    .spec(spec)
+                    .handlers(Map.of("getX", req -> Response.ok(Map.of())))
+                    .port(0)
+                    .build())
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("missingScheme");
+  }
+
+  @Test
+  void externalAuthSkipsAllChecks() throws Exception {
+    Map<String, Object> r =
+        raw(
+            Map.of("bearerAuth", Map.of("type", "http", "scheme", "bearer")),
+            List.of(),
+            List.of(Map.of("bearerAuth", List.of())));
+    Spec spec = Spec.from(r);
+
+    // No validator registered, but externalAuth → must succeed.
+    OpenApiServer server =
+        OpenApiServer.builder()
+            .spec(spec)
+            .useExternalAuthentication()
+            .handlers(Map.of("getX", req -> Response.ok(Map.of())))
+            .port(0)
+            .build();
+
+    assertThat(server).isNotNull();
+    server.close();
+  }
+}