fix(llm-auth): class-level constraint for the auth-check request, 422 for validation

Author: miguelgrc

apps/opik-backend/src/main/java/com/comet/opik/api/ProviderAuthCheck.java

@@ -1,5 +1,6 @@
 package com.comet.opik.api;
 
+import com.comet.opik.api.validation.ProviderAuthCheckValidation;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;
 import com.fasterxml.jackson.databind.annotation.JsonNaming;
@@ -18,6 +19,7 @@
 @Builder(toBuilder = true)
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
+@ProviderAuthCheckValidation
 public record ProviderAuthCheck(
         @Schema(description = "Test the stored auth config of this provider; also the sentinel-resolution target when auth_config is sent") UUID providerId,
         @Valid @Schema(description = "Auth config to test as-submitted; omit to test the stored one") ProviderAuthConfig authConfig) {

apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/priv/LlmProviderApiKeyResource.java

@@ -161,7 +161,8 @@ public Response updateApiKey(@PathParam("id") UUID id,
             +
             "Send provider_id to test the stored config, auth_config to test submitted values, or both to resolve secret sentinels against the stored config.", responses = {
                     @ApiResponse(responseCode = "200", description = "Token fetched", content = @Content(schema = @Schema(implementation = ProviderAuthCheck.Result.class))),
-                    @ApiResponse(responseCode = "400", description = "Bad Request", content = @Content(schema = @Schema(implementation = ErrorMessage.class))),
+                    @ApiResponse(responseCode = "400", description = "Bad Request — the token fetch itself failed (unreachable URL, rejected credentials, malformed reply)", content = @Content(schema = @Schema(implementation = ErrorMessage.class))),
+                    @ApiResponse(responseCode = "422", description = "Unprocessable Content — the request is invalid (neither provider_id nor auth_config, or an invalid auth_config)", content = @Content(schema = @Schema(implementation = ErrorMessage.class))),
                     @ApiResponse(responseCode = "403", description = "Access forbidden", content = @Content(schema = @Schema(implementation = ErrorMessage.class))),
                     @ApiResponse(responseCode = "404", description = "Not found", content = @Content(schema = @Schema(implementation = ErrorMessage.class)))
             })

apps/opik-backend/src/main/java/com/comet/opik/api/validation/ProviderAuthCheckValidation.java

@@ -0,0 +1,24 @@
+package com.comet.opik.api.validation;
+
+import jakarta.validation.Constraint;
+import jakarta.validation.Payload;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target({ElementType.TYPE, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Constraint(validatedBy = {ProviderAuthCheckValidator.class})
+@Documented
+public @interface ProviderAuthCheckValidation {
+
+    String message() default "invalid auth check request";
+
+    Class<?>[] groups() default {};
+
+    Class<? extends Payload>[] payload() default {};
+
+}

apps/opik-backend/src/main/java/com/comet/opik/api/validation/ProviderAuthCheckValidator.java

@@ -0,0 +1,35 @@
+package com.comet.opik.api.validation;
+
+import com.comet.opik.api.ProviderAuthCheck;
+import jakarta.validation.ConstraintValidator;
+import jakarta.validation.ConstraintValidatorContext;
+
+/**
+ * Request-only rules of the auth-config test endpoint. What stays in the service is the pair
+ * that reads the DB: "the provider has no auth_config to test" and the secret-sentinel merge.
+ */
+public class ProviderAuthCheckValidator implements ConstraintValidator<ProviderAuthCheckValidation, ProviderAuthCheck> {
+
+    @Override
+    public boolean isValid(ProviderAuthCheck request, ConstraintValidatorContext context) {
+        context.disableDefaultConstraintViolation();
+
+        var authConfig = request.authConfig();
+        if ((authConfig == null || authConfig.isEmpty()) && request.providerId() == null) {
+            context.buildConstraintViolationWithTemplate("either provider_id or auth_config must be provided")
+                    .addConstraintViolation();
+            return false;
+        }
+
+        if (authConfig != null && !authConfig.isEmpty()) {
+            var errors = ProviderAuthConfigValidator.validationErrors(authConfig);
+            if (!errors.isEmpty()) {
+                errors.forEach(error -> context.buildConstraintViolationWithTemplate(error)
+                        .addPropertyNode("authConfig")
+                        .addConstraintViolation());
+                return false;
+            }
+        }
+        return true;
+    }
+}

apps/opik-backend/src/main/java/com/comet/opik/domain/LlmProviderApiKeyService.java

@@ -200,36 +200,27 @@ public ProviderAuthCheck.Result testAuthConfig(@NonNull ProviderAuthCheck reques
         }
     }
 
+    /**
+     * Request-only validation (provider_id-or-auth_config, recipe validity) lives in
+     * {@link com.comet.opik.api.validation.ProviderAuthCheckValidator} at the API boundary; only
+     * the rules that read the DB remain here.
+     */
     private ProviderAuthConfig resolveAuthConfigForTest(ProviderAuthCheck request, String workspaceId) {
         ProviderAuthConfig incoming = request.authConfig();
         if (incoming == null || incoming.isEmpty()) {
-            if (request.providerId() == null) {
-                throw new BadRequestException("either provider_id or auth_config must be provided");
-            }
             ProviderAuthConfig stored = find(request.providerId(), workspaceId).authConfig();
             if (stored == null) {
                 throw new BadRequestException("the provider has no auth_config to test");
             }
             return stored;
         }
 
-        var errors = ProviderAuthConfigValidator.validationErrors(incoming);
-        if (!errors.isEmpty()) {
-            throw new BadRequestException(String.join("; ", errors));
-        }
         ProviderAuthConfig stored = request.providerId() != null
                 ? find(request.providerId(), workspaceId).authConfig()
                 : null;
         return mergeSecretSentinels(incoming, stored);
     }
 
-    /**
-     * The resolved auth_config decision plus the effective update to persist. The api_key /
-     * auth_config mutual exclusion is enforced entirely inside
-     * {@link #resolveAuthConfigUpdate}: it both validates the incoming pair and blanks the
-     * stored key when the update switches to token auth, so callers persist
-     * {@code effectiveUpdate} as-is and cannot hold the invariant wrong.
-     */
     private record AuthConfigUpdate(ProviderApiKeyUpdate effectiveUpdate, boolean clear,
             ProviderAuthConfig authConfig) {
     }

apps/opik-backend/src/main/java/com/comet/opik/infrastructure/llm/customllm/AuthTokenProvider.java

@@ -330,7 +330,7 @@ private HttpRequest buildRequest(ProviderAuthConfig authConfig) {
                 String clientSecret = credentialValue(credentials, CLIENT_SECRET_KEY);
                 if (clientId == null || clientSecret == null) {
                     throw new AuthTokenException(
-                            "basic auth mode requires '%s' and '%s' credentials".formatted(CLIENT_ID_KEY,
+                            "requires '%s' and '%s' credentials".formatted(CLIENT_ID_KEY,
                                     CLIENT_SECRET_KEY));
                 }
                 var bodyCredentials = credentials.stream()

apps/opik-backend/src/test/java/com/comet/opik/api/resources/v1/priv/LlmProviderApiKeyResourceTest.java

@@ -1034,9 +1034,8 @@ void testInvalidRequestsAreRejected() {
 
             try (var response = llmProviderApiKeyResourceClient.callTestAuthConfig(
                     ProviderAuthCheck.builder().build(), apiKey, workspaceName)) {
-                assertThat(response.getStatus()).isEqualTo(HttpStatus.SC_BAD_REQUEST);
-                assertThat(response.readEntity(ErrorMessage.class).getMessage())
-                        .contains("either provider_id or auth_config");
+                assertThat(response.getStatus()).isEqualTo(HttpStatus.SC_UNPROCESSABLE_CONTENT);
+                assertThat(response.readEntity(String.class)).contains("either provider_id or auth_config");
             }
 
             var staticProvider = llmProviderApiKeyResourceClient.createProviderApiKey(