feat: Add securityValidator and useExternalAuthentication builder methods

Author: thced

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

@@ -139,6 +139,8 @@ public static final class Builder {
     private int port = DEFAULT_PORT;
     private int shutdownTimeoutSeconds = 0;
     private final LinkedHashMap<String, HttpHandler> extras = new LinkedHashMap<>();
+    private final Map<String, SchemeValidator> securityValidators = new LinkedHashMap<>();
+    private boolean externalAuth = false;
 
     private Builder() {}
 
@@ -182,6 +184,30 @@ public Builder interceptor(RequestInterceptor interceptor) {
       return this;
     }
 
+    /**
+     * Registers a {@link SchemeValidator} for the OpenAPI security scheme named {@code schemeName}.
+     * The library extracts a {@link Credential} per request and hands it to this callback; return a
+     * non-empty {@link Optional} carrying the principal on success, or {@link Optional#empty()} to
+     * deny. Library renders 401/403 on denial.
+     */
+    public Builder securityValidator(String schemeName, SchemeValidator validator) {
+      requireNonNull(schemeName, "schemeName must not be null");
+      requireNonNull(validator, "validator must not be null");
+      securityValidators.put(schemeName, validator);
+      return this;
+    }
+
+    /**
+     * Opts out of in-process security enforcement. Use when an external sidecar (OPA/Envoy etc.)
+     * authenticates requests upstream. The library still parses {@code securitySchemes} into the
+     * {@link Spec}, but {@code SecurityFilter} short-circuits and the boot-time
+     * validator-registration check is skipped.
+     */
+    public Builder useExternalAuthentication() {
+      this.externalAuth = true;
+      return this;
+    }
+
     public Builder exceptionHandler(ExceptionHandler exceptionHandler) {
       this.exceptionHandler = exceptionHandler;
       return this;

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

@@ -0,0 +1,33 @@
+package com.retailsvc.http;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+
+class SecurityBuilderTest {
+
+  @Test
+  void securityValidatorRequiresNonNullName() {
+    var builder = OpenApiServer.builder();
+    assertThatThrownBy(() -> builder.securityValidator(null, (r, c) -> Optional.empty()))
+        .isInstanceOf(NullPointerException.class)
+        .hasMessageContaining("schemeName");
+  }
+
+  @Test
+  void securityValidatorRequiresNonNullValidator() {
+    var builder = OpenApiServer.builder();
+    assertThatThrownBy(() -> builder.securityValidator("x", null))
+        .isInstanceOf(NullPointerException.class)
+        .hasMessageContaining("validator");
+  }
+
+  @Test
+  void useExternalAuthenticationIsFluent() {
+    var builder = OpenApiServer.builder();
+    var returned = builder.useExternalAuthentication();
+    assertThat(returned).isSameAs(builder);
+  }
+}