#281: cover registered authorization actions

AUDIT.md

@@ -1,76 +0,0 @@
-# Authorization entry-point audit
-
-Scope reviewed: every route registered in `FleetApp.build`, every tool handler
-registered in `FleetMcp`, and their shared `CallerResolver` and `Authz` gate.
-
-## Result
-
-No authorization-action mismatch was found. The only handler whose operation
-changes with its arguments is `fleet_poll`. It selects `DRAIN` when `target` is
-present and `READ` when it is absent, before it calls either service branch.
-
-`Fleetd` creates one `CallerResolver` and passes that same instance to both
-`FleetMcp` and `FleetApp` (`Fleetd.java:615-650`, `720-722`). REST resolves it
-in the Javalin pre-handler. MCP resolves it in the transport context extractor.
-
-## REST routes
-
-| Route | Gate and choice location | Branch/target review | Verdict |
-|---|---|---|---|
-| `GET /healthz` | None | Liveness probe only; intentionally open. | ok |
-| `GET /metrics` | `METRICS`, start of `metrics` | No branch or target. | ok |
-| `GET /sessions` | `READ`, start of `sessions` | No caller-selected target. | ok |
-| `GET /agents` | `READ`, start of `agents` | No caller-selected target. | ok |
-| `GET /members` | `READ`, start of `listMembers` | No caller-selected target. | ok |
-| `GET /profiles` | `READ`, start of `profiles` | No caller-selected target. | ok |
-| `GET /member-credentials` | `READ`, start of `memberCredentials` | No caller-selected target. The view exposes policy names and counts, not values. | ok |
-| `POST /members` | `SPAWN`, before query/body parsing in `spawnMember` | Arguments select role, profile, cwd, and worktree. They do not select a different authority type. | ok |
-| `DELETE /members/{paneId}` | `STOP`, after reading `paneId` in `stopMember` | Caller can select another pane, but only a primary has `STOP`. | ok |
-| `POST /sessions/{id}/message` | `SEND`, after reading path `id` in `sendMessage` | Normal send, async send, and `turnId` answer all deliver a turn/message. `turnId` does not widen the roles allowed to send. | ok |
-| `POST /sessions/{id}/reply` | `REPLY`, after reading path `id` in `replyMessage` | Caller can name a target, and `Authz` requires it to equal the connection-resolved terminal. | ok |
-| `GET /sessions/{id}/replies` | `DRAIN`, after reading path `id` in `drainReplies` | Removes inbox entries; only a primary has `DRAIN`. | ok |
-| `POST /sessions/{id}/ask` | `ASK`, after reading path `id` in `askMessage` | Caller can name a target, and `Authz` requires it to equal the connection-resolved terminal. | ok |
-| `GET /sessions/{id}/status` | `READ`, after reading path `id` in `sessionStatus` | Any authenticated role may observe any session. This matches the `READ` policy, which intentionally does not use target ownership. | ok |
-| `GET /tasks/{ticket}` | `READ`, start of `taskStatus` | Ticket polling is read-only; no service branch changes the action. | ok |
-
-## MCP tools
-
-| Tool | Gate and choice location | Branch/target review | Verdict |
-|---|---|---|---|
-| `fleet_send` | `SEND`, at the start of `sendHandler` | `coordId`, `turnId`, synchronous, and async forms all deliver a message or a turn answer. `sessionId` is read before the branch for audit target only. | ok |
-| `fleet_reply` | `REPLY`, after deriving the connection terminal in `replyHandler` | No target argument exists. The service always receives the caller's own terminal. | ok |
-| `fleet_ask` | `ASK`, after deriving the connection terminal in `askHandler` | No target argument exists. The service always receives the caller's own terminal. | ok |
-| `fleet_status` | `READ`, start of `statusHandler` | Any authenticated role may query any session. This is the same intentional `READ` policy as the REST route. | ok |
-| `fleet_poll` with `ticket` | `READ`, `pollAction(target)` before dispatch in `pollHandler` | Reads a task only. | ok |
-| `fleet_poll` with `target` | `DRAIN`, `pollAction(target)` before dispatch in `pollHandler` | Drains and removes a target inbox. Only a primary has `DRAIN`. | ok |
-| `fleet_ack` | `DRAIN`, start of `ackHandler` | Removes one target inbox entry. Only a primary has `DRAIN`. | ok |
-| `fleet_spawn` | `SPAWN`, start of `spawnHandler` | Arguments select member configuration only. | ok |
-| `fleet_list` | `READ`, start of `listHandler` | No caller-selected target. | ok |
-| `fleet_stop` | `STOP`, after reading `paneId` in `stopHandler` | Caller can select another pane, but only a primary has `STOP`. | ok |
-| `fleet_profiles` | `READ`, start of `profilesHandler` | No caller-selected target. | ok |
-| `fleet_whoami` | `READ`, start of `whoamiHandler` | Reports the connection-resolved caller, not an argument. | ok |
-
-## Surface parity
-
-The matching route/tool pairs use the same action:
-
-| Operation | REST | MCP | Result |
-|---|---|---|---|
-| spawn | `SPAWN` | `SPAWN` | match |
-| stop | `STOP` | `STOP` | match |
-| send and ask answer | `SEND` | `SEND` | match |
-| reply | `REPLY` | `REPLY` | match |
-| ask | `ASK` | `ASK` | match |
-| drain replies | `DRAIN` | `DRAIN` for `fleet_poll{target}` and `fleet_ack` | match |
-| status | `READ` | `READ` | match |
-| task/ticket polling | `READ` | `READ` | match |
-| list/profiles | `READ` | `READ` | match |
-
-## Test risk
-
-`FleetMcpAuthzTest` has a direct regression test for the argument-dependent
-`fleet_poll` action. It tests the shared role table for the other tools, but it
-does not pin each handler's chosen action. This is not a current defect because
-the reviewed handlers choose the matching action. A future change that adds an
-argument-dependent operation should add a handler-level action-selection test,
-like `pollingByTargetIsADrainAndPollingByTicketIsARead`.

fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java

@@ -257,7 +257,7 @@ public final class FleetMcp {
         // Each handler is built once and wired to its fleet_* tool below.
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> sendHandler =
                 (exchange, req) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.SEND,
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_send", req.arguments()),
                             str(req.arguments(), "sessionId"));
                     if (denied != null) return denied;
                     String caller = callerTerminal(exchange);
@@ -299,7 +299,7 @@ public final class FleetMcp {
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> replyHandler =
                 (exchange, req) -> {
                     String self = callerTerminal(exchange);
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.REPLY, self);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_reply", req.arguments()), self);
                     if (denied != null) return denied;
                     return reply(messages, self, str(req.arguments(), "content"));
                 };
@@ -307,13 +307,13 @@ public final class FleetMcp {
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> askHandler =
                 (exchange, req) -> {
                     String self = callerTerminal(exchange);
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.ASK, self);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_ask", req.arguments()), self);
                     if (denied != null) return denied;
                     return ask(messages, self, str(req.arguments(), "question"), timeoutMs(req.arguments()));
                 };
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> statusHandler =
                 (exchange, req) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_status", req.arguments()), null);
                     if (denied != null) return denied;
                     return status(messages, str(req.arguments(), "sessionId"));
                 };
@@ -322,7 +322,7 @@ public final class FleetMcp {
                     Map<String, Object> a = req.arguments();
                     String target = str(a, "target");
                     // The action depends on the ARGUMENTS, not on the tool name -- see pollAction.
-                    McpSchema.CallToolResult denied = deny(exchange, pollAction(target), target);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_poll", a), target);
                     if (denied != null) return denied;
                     return poll(messages, str(a, "ticket"), target);
                 };
@@ -331,14 +331,14 @@ public final class FleetMcp {
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> ackHandler =
                 (exchange, req) -> {
                     Map<String, Object> a = req.arguments();
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.DRAIN, str(a, "target"));
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_ack", a), str(a, "target"));
                     if (denied != null) return denied;
                     return ack(messages, str(a, "target"), str(a, "msgId"));
                 };
         // Fleet management (CB-108): spawn/list/stop over ClaudeCodeLauncher.
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> spawnHandler =
                 (exchange, req) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.SPAWN, null);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_spawn", req.arguments()), null);
                     if (denied != null) return denied;
                     String caller = callerTerminal(exchange);
                     // SPAWN is already auth-gated to PRIMARY (architects can never call it), but
@@ -355,7 +355,7 @@ public final class FleetMcp {
                 };
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> listHandler =
                 (exchange, _) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_list", Map.of()), null);
                     if (denied != null) return denied;
                     return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, outage,
                             leadSeats, callers == null ? Map.of() : callers.leads(),
@@ -365,19 +365,19 @@ public final class FleetMcp {
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> stopHandler =
                 (exchange, req) -> {
                     String paneId = str(req.arguments(), "paneId");
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.STOP, paneId);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_stop", req.arguments()), paneId);
                     if (denied != null) return denied;
                     return stop(sessions, paneId);
                 };
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> profilesHandler =
                 (exchange, _) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_profiles", Map.of()), null);
                     if (denied != null) return denied;
                     return profiles(workers, quarantine, outage);
                 };
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> whoamiHandler =
                 (exchange, _) -> {
-                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_whoami", Map.of()), null);
                     if (denied != null) return denied;
                     return whoami(principal(exchange), sessions);
                 };
@@ -754,6 +754,25 @@ public final class FleetMcp {
         return isBlank(target) ? Authz.Action.READ : Authz.Action.DRAIN;
     }
 
+    /**
+     * The action a registered tool handler actually hands to the authorization gate.
+     * Keeping this choice beside the registered-tool inventory makes a new tool fail the coverage
+     * test until its action is pinned.
+     */
+    static Authz.Action toolAction(String toolName, Map<String, Object> arguments) {
+        return switch (toolName) {
+            case "fleet_send" -> Authz.Action.SEND;
+            case "fleet_reply" -> Authz.Action.REPLY;
+            case "fleet_ask" -> Authz.Action.ASK;
+            case "fleet_status", "fleet_list", "fleet_profiles", "fleet_whoami" -> Authz.Action.READ;
+            case "fleet_poll" -> pollAction(str(arguments, "target"));
+            case "fleet_ack" -> Authz.Action.DRAIN;
+            case "fleet_spawn" -> Authz.Action.SPAWN;
+            case "fleet_stop" -> Authz.Action.STOP;
+            default -> throw new IllegalArgumentException("unregistered tool: " + toolName);
+        };
+    }
+
     /** {@code fleet_poll}: check an async delegation by ticket, or drain a worker's inbox by target. */
     static McpSchema.CallToolResult poll(MessageService messages, String ticket, String target) {
         if (!isBlank(target)) {

fleetd/src/main/java/dev/ltms/fleet/rest/FleetApp.java

@@ -47,6 +47,22 @@ import java.util.stream.Collectors;
  */
 public final class FleetApp {
 
+    /** The authorization action the matching route handler hands to {@link #allow}. */
+    static Authz.Action routeAction(String route) {
+        return switch (route) {
+            case "GET /metrics" -> Authz.Action.METRICS;
+            case "POST /members" -> Authz.Action.SPAWN;
+            case "DELETE /members/{paneId}" -> Authz.Action.STOP;
+            case "POST /sessions/{id}/message" -> Authz.Action.SEND;
+            case "POST /sessions/{id}/reply" -> Authz.Action.REPLY;
+            case "GET /sessions/{id}/replies" -> Authz.Action.DRAIN;
+            case "POST /sessions/{id}/ask" -> Authz.Action.ASK;
+            case "GET /sessions", "GET /agents", "GET /members", "GET /profiles",
+                    "GET /member-credentials", "GET /sessions/{id}/status", "GET /tasks/{ticket}" -> Authz.Action.READ;
+            default -> throw new IllegalArgumentException("route has no authorization gate: " + route);
+        };
+    }
+
     /** Default blocking window for a message; kept under typical HTTP idle timeouts. */
     private static final long DEFAULT_MESSAGE_TIMEOUT_MS = 25_000;
     private static final long MAX_MESSAGE_TIMEOUT_MS = 120_000;
@@ -222,7 +238,7 @@ public final class FleetApp {
 
     /** Prometheus scrape endpoint (CB-502). */
     private void metrics(Context ctx) {
-        if (!allow(ctx, Authz.Action.METRICS, null)) {
+        if (!allow(ctx, routeAction("GET /metrics"), null)) {
             return;
         }
         ctx.status(200).contentType("text/plain; version=0.0.4; charset=utf-8").result(metrics.render());
@@ -294,7 +310,7 @@ public final class FleetApp {
      * member workspace (they live on the member daemon only).
      */
     private void sessions(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /sessions"), null)) {
             return;
         }
         List<Map<String, Object>> out = new ArrayList<>();
@@ -319,7 +335,7 @@ public final class FleetApp {
 
     /** Discovery: every agent herdr tracks, keyed by its Claude session UUID. */
     private void agents(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /agents"), null)) {
             return;
         }
         ctx.status(200).json(Map.of("agents",
@@ -328,7 +344,7 @@ public final class FleetApp {
 
     /** CB-304: bridge-owned roster merged with live herdr status by paneId. */
     private void listMembers(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /members"), null)) {
             return;
         }
         // CB-519: the registry key is a host-unique id, not the pane coordinate — join on terminal.
@@ -359,7 +375,7 @@ public final class FleetApp {
 
     /** The configured worker profiles and which one a no-argument spawn uses. */
     private void profiles(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /profiles"), null)) {
             return;
         }
         ctx.status(200).json(Map.of(
@@ -376,7 +392,7 @@ public final class FleetApp {
      * name list, which is exactly what let the list drift silently behind the real policy.
      */
     private void memberCredentials(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /member-credentials"), null)) {
             return;
         }
         MemberCredentialPolicyView view = memberCredentials.get();
@@ -396,7 +412,7 @@ public final class FleetApp {
      * the subscription boundary, 400 for an unknown profile.
      */
     private void spawnMember(Context ctx) {
-        if (!allow(ctx, Authz.Action.SPAWN, null)) {
+        if (!allow(ctx, routeAction("POST /members"), null)) {
             return;
         }
         String role = ctx.queryParam("role");
@@ -467,7 +483,7 @@ public final class FleetApp {
     /** Tear a worker down by pane id. */
     private void stopMember(Context ctx) {
         String paneId = ctx.pathParam("paneId");
-        if (!allow(ctx, Authz.Action.STOP, paneId)) {
+        if (!allow(ctx, routeAction("DELETE /members/{paneId}"), paneId)) {
             return;
         }
         sessions.release(paneId);
@@ -482,7 +498,7 @@ public final class FleetApp {
      */
     private void sendMessage(Context ctx) {
         String id = ctx.pathParam("id");
-        if (!allow(ctx, Authz.Action.SEND, id)) {
+        if (!allow(ctx, routeAction("POST /sessions/{id}/message"), id)) {
             return;
         }
         String content;
@@ -569,7 +585,7 @@ public final class FleetApp {
      */
     private void askMessage(Context ctx) {
         String id = ctx.pathParam("id");
-        if (!allow(ctx, Authz.Action.ASK, id)) {
+        if (!allow(ctx, routeAction("POST /sessions/{id}/ask"), id)) {
             return;
         }
         String question;
@@ -608,7 +624,7 @@ public final class FleetApp {
         // The rule that matters: a worker may reply only as itself. Over MCP this was already true
         // structurally (identity comes from the connection, never an argument); over REST the path
         // id was simply trusted, so this is where the invariant actually gets enforced.
-        if (!allow(ctx, Authz.Action.REPLY, id)) {
+        if (!allow(ctx, routeAction("POST /sessions/{id}/reply"), id)) {
             return;
         }
         String content;
@@ -629,7 +645,7 @@ public final class FleetApp {
      */
     private void drainReplies(Context ctx) {
         String id = ctx.pathParam("id");
-        if (!allow(ctx, Authz.Action.DRAIN, id)) {
+        if (!allow(ctx, routeAction("GET /sessions/{id}/replies"), id)) {
             return;
         }
         var replies = messages.drainReplies(id);
@@ -647,7 +663,7 @@ public final class FleetApp {
      */
     private void sessionStatus(Context ctx) {
         String id = ctx.pathParam("id");
-        if (!allow(ctx, Authz.Action.READ, id)) {
+        if (!allow(ctx, routeAction("GET /sessions/{id}/status"), id)) {
             return;
         }
         try {
@@ -672,7 +688,7 @@ public final class FleetApp {
 
     /** Poll an async (wait:false) delegation by ticket. 404 for an unknown/expired ticket. */
     private void taskStatus(Context ctx) {
-        if (!allow(ctx, Authz.Action.READ, null)) {
+        if (!allow(ctx, routeAction("GET /tasks/{ticket}"), null)) {
             return;
         }
         MessageService.TaskView v = messages.poll(ctx.pathParam("ticket"));

fleetd/src/test/java/dev/ltms/fleet/mcp/FleetMcpAuthzTest.java

@@ -24,8 +24,13 @@ import io.modelcontextprotocol.spec.McpSchema;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashSet;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -44,6 +49,9 @@ import static org.junit.jupiter.api.Assertions.*;
  */
 class FleetMcpAuthzTest {
 
+    private static final Path MCP_SOURCE = Path.of("src/main/java/dev/ltms/fleet/mcp/FleetMcp.java");
+    private static final Pattern TOOL_REGISTRATION = Pattern.compile("tool\\(\\\"(fleet_[a-z_]+)\\\"");
+
     private final FakeHerdr herdr = new FakeHerdr();
     private final AgentControl agents = new AgentControl(herdr);
     private Metrics metrics;
@@ -201,6 +209,42 @@ class FleetMcpAuthzTest {
                 "a blank target is an absent target");
     }
 
+    @Test
+    void everyRegisteredToolHasItsHandlerActionPinned() {
+        Set<String> registered = toolsTheServerRegisters();
+        assertTrue(registered.size() >= 10,
+                "scraped only " + registered.size() + " tool registrations from FleetMcp (" + registered
+                        + "); the server registers eleven, so the tool(\"…\") scrape has stopped matching");
+        registered.forEach(tool -> assertDoesNotThrow(() -> FleetMcp.toolAction(tool, Map.of()),
+                () -> tool + " is registered but has no pinned authorization action"));
+
+        assertEquals(Authz.Action.SEND, FleetMcp.toolAction("fleet_send", Map.of()));
+        assertEquals(Authz.Action.REPLY, FleetMcp.toolAction("fleet_reply", Map.of()));
+        assertEquals(Authz.Action.ASK, FleetMcp.toolAction("fleet_ask", Map.of()));
+        assertEquals(Authz.Action.READ, FleetMcp.toolAction("fleet_status", Map.of()));
+        assertEquals(Authz.Action.DRAIN, FleetMcp.toolAction("fleet_ack", Map.of()));
+        assertEquals(Authz.Action.SPAWN, FleetMcp.toolAction("fleet_spawn", Map.of()));
+        assertEquals(Authz.Action.READ, FleetMcp.toolAction("fleet_list", Map.of()));
+        assertEquals(Authz.Action.STOP, FleetMcp.toolAction("fleet_stop", Map.of()));
+        assertEquals(Authz.Action.READ, FleetMcp.toolAction("fleet_profiles", Map.of()));
+        assertEquals(Authz.Action.READ, FleetMcp.toolAction("fleet_whoami", Map.of()));
+        assertEquals(Authz.Action.READ, FleetMcp.toolAction("fleet_poll", Map.of("ticket", "task")));
+        assertEquals(Authz.Action.DRAIN, FleetMcp.toolAction("fleet_poll", Map.of("target", "term_b")));
+    }
+
+    private static Set<String> toolsTheServerRegisters() {
+        try {
+            Matcher matcher = TOOL_REGISTRATION.matcher(Files.readString(MCP_SOURCE));
+            Set<String> tools = new LinkedHashSet<>();
+            while (matcher.find()) {
+                tools.add(matcher.group(1));
+            }
+            return tools;
+        } catch (Exception e) {
+            throw new AssertionError("could not scrape FleetMcp tool registrations", e);
+        }
+    }
+
     @Test
     void aWorkerMayNotDrainAnotherSessionsInboxByPolling() {
         FleetMcp m = mcp(true);

fleetd/src/test/java/dev/ltms/fleet/rest/FleetAppAuthTest.java

@@ -1,6 +1,7 @@
 package dev.ltms.fleet.rest;
 
 import dev.ltms.fleet.auth.CallerResolver;
+import dev.ltms.fleet.auth.Authz;
 import dev.ltms.fleet.auth.MemberRegistry;
 import dev.ltms.fleet.config.FleetConfig;
 import dev.ltms.fleet.guard.SubscriptionGuard;
@@ -25,8 +26,15 @@ import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashSet;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -36,6 +44,10 @@ import static org.junit.jupiter.api.Assertions.*;
  */
 class FleetAppAuthTest {
 
+    private static final Path REST_SOURCE = Path.of("src/main/java/dev/ltms/fleet/rest/FleetApp.java");
+    private static final Pattern ROUTE_REGISTRATION =
+            Pattern.compile("app\\.(get|post|delete|put|patch)\\(\\s*\"([^\"]+)\"");
+
     private final HttpClient http = HttpClient.newHttpClient();
     private Javalin app;
     private Metrics metrics;
@@ -92,6 +104,49 @@ class FleetAppAuthTest {
         return http.send(b.build(), HttpResponse.BodyHandlers.ofString());
     }
 
+    @Test
+    void everyRegisteredRouteHasItsHandlerActionPinned() {
+        Set<String> registered = routesTheServerRegisters();
+        assertTrue(registered.size() >= 15,
+                "scraped only " + registered.size() + " route registrations from FleetApp (" + registered
+                        + "); the app.<verb>(\"…\") scrape has stopped matching");
+        // Liveness must work before credentials can be checked, so this route is deliberately open.
+        assertTrue(registered.remove("GET /healthz"), "GET /healthz must stay an explicit ungated exception");
+        registered.forEach(route -> assertDoesNotThrow(() -> FleetApp.routeAction(route),
+                () -> route + " is registered but has no pinned authorization action"));
+        assertEquals(Authz.Action.METRICS, FleetApp.routeAction("GET /metrics"));
+        assertEquals(Authz.Action.SPAWN, FleetApp.routeAction("POST /members"));
+        assertEquals(Authz.Action.STOP, FleetApp.routeAction("DELETE /members/{paneId}"));
+        assertEquals(Authz.Action.SEND, FleetApp.routeAction("POST /sessions/{id}/message"));
+        assertEquals(Authz.Action.REPLY, FleetApp.routeAction("POST /sessions/{id}/reply"));
+        assertEquals(Authz.Action.DRAIN, FleetApp.routeAction("GET /sessions/{id}/replies"));
+        assertEquals(Authz.Action.ASK, FleetApp.routeAction("POST /sessions/{id}/ask"));
+        for (String route : Set.of("GET /sessions", "GET /agents", "GET /members", "GET /profiles",
+                "GET /member-credentials", "GET /sessions/{id}/status", "GET /tasks/{ticket}")) {
+            assertEquals(Authz.Action.READ, FleetApp.routeAction(route), route);
+        }
+        assertThrows(IllegalArgumentException.class, () -> FleetApp.routeAction("GET /healthz"));
+    }
+
+    private static Set<String> routesTheServerRegisters() {
+        try {
+            String source = Files.readString(REST_SOURCE).lines()
+                    .filter(line -> {
+                        String stripped = line.stripLeading();
+                        return !(stripped.startsWith("//") || stripped.startsWith("*") || stripped.startsWith("/*"));
+                    })
+                    .collect(Collectors.joining("\n"));
+            Matcher matcher = ROUTE_REGISTRATION.matcher(source);
+            Set<String> routes = new LinkedHashSet<>();
+            while (matcher.find()) {
+                routes.add(matcher.group(1).toUpperCase(Locale.ROOT) + " " + matcher.group(2));
+            }
+            return routes;
+        } catch (Exception e) {
+            throw new AssertionError("could not scrape FleetApp route registrations", e);
+        }
+    }
+
     // --- loopback-trust: the caller is the primary -------------------------------------------
 
     @Test