feat: Add Request.principals and withPrincipals immutable copy

Author: thced

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

@@ -29,6 +29,7 @@ public final class Request {
   private final Map<String, String> pathParameters;
   private final String rawQuery;
   private final UnaryOperator<String> headerLookup;
+  private final Map<String, Object> principals;
   private Map<String, String> queryParamCache;
 
   /**
@@ -52,13 +53,39 @@ public Request(
       Map<String, String> pathParameters,
       String rawQuery,
       UnaryOperator<String> headerLookup) {
+    this(body, parsed, bodyMapper, operationId, pathParameters, rawQuery, headerLookup, Map.of());
+  }
+
+  /**
+   * Builds a {@code Request} from transport-neutral primitives with an explicit principals map.
+   *
+   * @param body raw request body bytes; never {@code null}, may be empty
+   * @param parsed loose structural view of the body (Map / List / boxed primitive), or {@code null}
+   * @param bodyMapper {@link TypeMapper} that produced {@code parsed}, used for typed conversion;
+   *     may be {@code null} if there is no body
+   * @param operationId the OpenAPI {@code operationId} the request was routed to
+   * @param pathParameters path variables extracted by the router
+   * @param rawQuery raw (percent-encoded) query string, or {@code null} if absent
+   * @param headerLookup first-value, case-insensitive header lookup; returns {@code null} if absent
+   * @param principals principals stashed by the security filter, keyed by scheme name
+   */
+  public Request(
+      byte[] body,
+      Object parsed,
+      TypeMapper bodyMapper,
+      String operationId,
+      Map<String, String> pathParameters,
+      String rawQuery,
+      UnaryOperator<String> headerLookup,
+      Map<String, Object> principals) {
     this.body = body;
     this.parsed = parsed;
     this.bodyMapper = bodyMapper;
     this.operationId = operationId;
     this.pathParameters = pathParameters;
     this.rawQuery = rawQuery;
     this.headerLookup = headerLookup;
+    this.principals = Map.copyOf(principals);
   }
 
   public byte[] bytes() {
@@ -163,6 +190,29 @@ public Optional<String> queryParam(String name) {
     return raw == null || raw.isBlank() ? Optional.empty() : Optional.of(raw);
   }
 
+  /**
+   * Principals stashed by {@code SecurityFilter}, keyed by securityScheme name. Empty when the
+   * request had no security requirements or when {@code useExternalAuthentication()} is set.
+   */
+  public Map<String, Object> principals() {
+    return principals;
+  }
+
+  /** Convenience for the common single-scheme case. */
+  public Optional<Object> principal(String schemeName) {
+    return Optional.ofNullable(principals.get(schemeName));
+  }
+
+  /**
+   * Returns a new {@code Request} identical to this one except with the supplied principals. Used
+   * by {@code SecurityFilter} on success; the returned instance carries the principals through to
+   * the {@link RequestHandler}.
+   */
+  public Request withPrincipals(Map<String, Object> principals) {
+    return new Request(
+        body, parsed, bodyMapper, operationId, pathParameters, rawQuery, headerLookup, principals);
+  }
+
   private static Map<String, String> parseQuery(String query) {
     if (query == null || query.isBlank()) {
       return Map.of();

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

@@ -6,6 +6,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.retailsvc.http.internal.DispatchHandler;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.UnaryOperator;
@@ -199,6 +200,37 @@ void contentTypeEmptyWhenHeaderAbsent() {
     assertThat(req.contentType()).isEmpty();
   }
 
+  @Test
+  void principalsDefaultsEmpty() {
+    Request r = new Request(new byte[0], null, null, "op", Map.of(), null, NO_HEADERS);
+
+    assertThat(r.principals()).isEmpty();
+    assertThat(r.principal("anything")).isEmpty();
+  }
+
+  @Test
+  void withPrincipalsCreatesImmutableCopy() {
+    Request r = new Request(new byte[0], null, null, "op", Map.of(), null, NO_HEADERS);
+    Map<String, Object> principals = Map.of("bearerAuth", "user-123");
+    Request copy = r.withPrincipals(principals);
+
+    assertThat(copy).isNotSameAs(r);
+    assertThat(r.principals()).isEmpty();
+    assertThat(copy.principals()).isEqualTo(principals);
+    assertThat(copy.principal("bearerAuth")).contains("user-123");
+  }
+
+  @Test
+  void withPrincipalsDoesNotShareUnderlyingMap() {
+    Request r = new Request(new byte[0], null, null, "op", Map.of(), null, NO_HEADERS);
+    HashMap<String, Object> mutable = new HashMap<>();
+    mutable.put("a", "b");
+    Request copy = r.withPrincipals(mutable);
+    mutable.put("a", "MUTATED");
+
+    assertThat(copy.principal("a")).contains("b");
+  }
+
   @Test
   void headerReturnsOptionalAndBlankIsAbsent() {
     Request req =