Return a specific reason in Core 401 responses

A 401 from /attest (and other auth-gated endpoints) previously returned a bare "Unauthorized", giving operators no way to distinguish a mistyped/unknown key from a disabled key or a role problem. GenericFailureHandler now returns a JSON body with a reason (unrecognized_key / key_disabled / insufficient_role) and an actionable message, inferred from the resolved auth profile. The body surfaces in the operator's attestation log.

Adds GenericFailureHandlerTest covering all three reasons and the non-401 passthrough.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: swibi-ttd

src/main/java/com/uid2/core/handler/GenericFailureHandler.java

@@ -6,11 +6,14 @@
 import io.vertx.core.Handler;
 import io.vertx.core.http.HttpClosedException;
 import io.vertx.core.http.HttpServerResponse;
+import io.vertx.core.json.JsonObject;
 import io.vertx.ext.web.RoutingContext;
 import org.apache.http.impl.EnglishReasonPhraseCatalog;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.net.HttpURLConnection;
+
 public class GenericFailureHandler implements Handler<RoutingContext> {
     private static final Logger LOGGER = LoggerFactory.getLogger(GenericFailureHandler.class);
 
@@ -38,8 +41,36 @@ public void handle(RoutingContext ctx) {
         }
 
         if (!response.ended() && !response.closed()) {
-            response.setStatusCode(statusCode)
-                    .end(EnglishReasonPhraseCatalog.INSTANCE.getReason(statusCode, null));
+            if (statusCode == HttpURLConnection.HTTP_UNAUTHORIZED) {
+                // Return the specific reason so the caller (e.g. a private operator at startup) 
+                // gets an actionable message.
+                response.putHeader("Content-Type", "application/json")
+                        .setStatusCode(statusCode)
+                        .end(buildUnauthorizedBody(profile).encode());
+            } else {
+                response.setStatusCode(statusCode)
+                        .end(EnglishReasonPhraseCatalog.INSTANCE.getReason(statusCode, null));
+            }
+        }
+    }
+
+    private static JsonObject buildUnauthorizedBody(IAuthorizable profile) {
+        final String reason;
+        final String message;
+        if (profile == null) {
+            // Key did not resolve to any record - the most common operator-onboarding mistake.
+            reason = "unrecognized_key";
+            message = "Operator key not recognized.";
+        } else if (profile.isDisabled()) {
+            reason = "key_disabled";
+            message = "Operator key is recognized but has been disabled.";
+        } else {
+            reason = "insufficient_role";
+            message = "Operator key is recognized but is not authorized for this operation.";
         }
+        return new JsonObject()
+                .put("status", "unauthorized")
+                .put("reason", reason)
+                .put("message", message);
     }
 }

src/test/java/com/uid2/core/handler/GenericFailureHandlerTest.java

@@ -0,0 +1,93 @@
+package com.uid2.core.handler;
+
+import com.uid2.shared.auth.IAuthorizable;
+import com.uid2.shared.middleware.AuthMiddleware;
+import io.vertx.core.http.HttpServerResponse;
+import io.vertx.core.json.JsonObject;
+import io.vertx.ext.web.RoutingContext;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.net.HttpURLConnection;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+class GenericFailureHandlerTest {
+
+    // Drives the handler for a given status code + resolved auth profile, returning the response body written.
+    private static String handleAndCaptureBody(int statusCode, IAuthorizable profile) {
+        RoutingContext ctx = mock(RoutingContext.class);
+        HttpServerResponse response = mock(HttpServerResponse.class);
+
+        Map<String, Object> data = new HashMap<>();
+        if (profile != null) {
+            data.put(AuthMiddleware.API_CLIENT_PROP, profile);
+        }
+
+        when(ctx.statusCode()).thenReturn(statusCode);
+        when(ctx.response()).thenReturn(response);
+        when(ctx.normalizedPath()).thenReturn("/attest");
+        when(ctx.failure()).thenReturn(null);
+        when(ctx.data()).thenReturn(data);
+
+        when(response.ended()).thenReturn(false);
+        when(response.closed()).thenReturn(false);
+        when(response.putHeader(anyString(), anyString())).thenReturn(response);
+        when(response.setStatusCode(anyInt())).thenReturn(response);
+
+        new GenericFailureHandler().handle(ctx);
+
+        ArgumentCaptor<String> bodyCaptor = ArgumentCaptor.forClass(String.class);
+        verify(response).end(bodyCaptor.capture());
+        return bodyCaptor.getValue();
+    }
+
+    @Test
+    void unknownKeyReturnsUnrecognizedKeyReason() {
+        // No auth profile resolved -> key was not recognized (the 4eyes.ai transcription-error case).
+        JsonObject body = new JsonObject(handleAndCaptureBody(HttpURLConnection.HTTP_UNAUTHORIZED, null));
+
+        assertEquals("unauthorized", body.getString("status"));
+        assertEquals("unrecognized_key", body.getString("reason"));
+        assertTrue(body.getString("message").toLowerCase().contains("not recognized"));
+    }
+
+    @Test
+    void disabledKeyReturnsKeyDisabledReason() {
+        IAuthorizable disabledKey = mock(IAuthorizable.class);
+        when(disabledKey.isDisabled()).thenReturn(true);
+
+        JsonObject body = new JsonObject(handleAndCaptureBody(HttpURLConnection.HTTP_UNAUTHORIZED, disabledKey));
+
+        assertEquals("unauthorized", body.getString("status"));
+        assertEquals("key_disabled", body.getString("reason"));
+        assertTrue(body.getString("message").toLowerCase().contains("disabled"));
+    }
+
+    @Test
+    void recognizedButUnauthorizedKeyReturnsInsufficientRoleReason() {
+        IAuthorizable wrongRoleKey = mock(IAuthorizable.class);
+        when(wrongRoleKey.isDisabled()).thenReturn(false);
+
+        JsonObject body = new JsonObject(handleAndCaptureBody(HttpURLConnection.HTTP_UNAUTHORIZED, wrongRoleKey));
+
+        assertEquals("unauthorized", body.getString("status"));
+        assertEquals("insufficient_role", body.getString("reason"));
+    }
+
+    @Test
+    void nonUnauthorizedStatusKeepsPlainReasonPhrase() {
+        // Non-401 failures must keep the existing bare reason-phrase body (no behaviour change).
+        String body = handleAndCaptureBody(HttpURLConnection.HTTP_BAD_REQUEST, null);
+
+        assertEquals("Bad Request", body);
+    }
+}