feat: Security headers decorator (#89)

* feat: Add securityHeadersDecorator for browser hardening

Provide an opt-in ResponseDecorator that sets two browser-hardening
headers on every response routed through the OpenAPI dispatch chain:

- X-Content-Type-Options: nosniff
- Cross-Origin-Resource-Policy: same-origin

Both are skipped when the handler has already set the header, so
per-response overrides keep working. Wire in with
OpenApiServer.builder().responseDecorator(Handlers.securityHeadersDecorator()).

ServerLauncher now applies the decorator so the local demo and the
ZAP scan exercise it.

Note: ResponseDecorator runs in the dispatch chain, not in
ExceptionFilter, so 500 responses produced by the default exception
path remain unaffected. That's an intentional scope limit for this
change.

Author: thced

README.md

@@ -365,6 +365,24 @@ OpenApiServer.builder()
     .build();
 ```
 
+#### Built-in: browser security headers
+
+`Handlers.securityHeadersDecorator()` adds two browser-hardening headers to every response —
+`X-Content-Type-Options: nosniff` and `Cross-Origin-Resource-Policy: same-origin`. Handler-supplied
+values for either header are preserved, so individual responses can opt out by setting the header
+explicitly.
+
+``` java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .responseDecorator(Handlers.securityHeadersDecorator())
+    .build();
+```
+
+Decorators run on the dispatch path only — error responses produced by `ExceptionFilter` (e.g.
+the default 500) bypass them.
+
 ### Request interceptors
 
 `Builder.interceptor(...)` registers a `RequestInterceptor` that wraps every handler invocation.

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

@@ -28,6 +28,32 @@ public final class Handlers {
 
   private Handlers() {}
 
+  /**
+   * Response decorator that adds two browser-hardening headers to every response:
+   *
+   * <ul>
+   *   <li>{@code X-Content-Type-Options: nosniff} — prevents MIME sniffing.
+   *   <li>{@code Cross-Origin-Resource-Policy: same-origin} — blocks cross-origin reads of the
+   *       response body, mitigating Spectre-class side-channel attacks.
+   * </ul>
+   *
+   * <p>Existing headers with the same names are preserved, so a handler that sets either header
+   * keeps its value. Wire it in with {@code
+   * OpenApiServer.builder().responseDecorator(Handlers.securityHeadersDecorator())}.
+   */
+  public static ResponseDecorator securityHeadersDecorator() {
+    return (request, response) -> {
+      Response decorated = response;
+      if (!response.headers().containsKey("X-Content-Type-Options")) {
+        decorated = decorated.withHeader("X-Content-Type-Options", "nosniff");
+      }
+      if (!response.headers().containsKey("Cross-Origin-Resource-Policy")) {
+        decorated = decorated.withHeader("Cross-Origin-Resource-Policy", "same-origin");
+      }
+      return decorated;
+    };
+  }
+
   public static ExceptionHandler defaultExceptionHandler() {
     return t ->
         switch (t) {

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

@@ -0,0 +1,42 @@
+package com.retailsvc.http;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+class SecurityHeadersDecoratorTest {
+
+  private final ResponseDecorator decorator = Handlers.securityHeadersDecorator();
+
+  @Test
+  void addsBothHeadersWhenMissing() {
+    Response decorated = decorator.decorate(null, Response.status(200));
+
+    assertThat(decorated.headers())
+        .containsEntry("X-Content-Type-Options", "nosniff")
+        .containsEntry("Cross-Origin-Resource-Policy", "same-origin");
+  }
+
+  @Test
+  void preservesHandlerSuppliedNosniffValue() {
+    Response handlerResponse = Response.status(200).withHeader("X-Content-Type-Options", "custom");
+
+    Response decorated = decorator.decorate(null, handlerResponse);
+
+    assertThat(decorated.headers())
+        .containsEntry("X-Content-Type-Options", "custom")
+        .containsEntry("Cross-Origin-Resource-Policy", "same-origin");
+  }
+
+  @Test
+  void preservesHandlerSuppliedCorpValue() {
+    Response handlerResponse =
+        Response.status(200).withHeader("Cross-Origin-Resource-Policy", "cross-origin");
+
+    Response decorated = decorator.decorate(null, handlerResponse);
+
+    assertThat(decorated.headers())
+        .containsEntry("X-Content-Type-Options", "nosniff")
+        .containsEntry("Cross-Origin-Resource-Policy", "cross-origin");
+  }
+}

src/test/java/com/retailsvc/http/start/ServerLauncher.java

@@ -1,5 +1,6 @@
 package com.retailsvc.http.start;
 
+import com.retailsvc.http.Handlers;
 import com.retailsvc.http.OpenApiServer;
 import com.retailsvc.http.RequestHandler;
 import com.retailsvc.http.Response;
@@ -54,6 +55,7 @@ public ServerLauncher() throws IOException {
     OpenApiServer.builder()
         .spec(spec)
         .handlers(handlers)
+        .responseDecorator(Handlers.securityHeadersDecorator())
         .securityValidator("apiKeyAuth", (req, cred) -> Optional.empty())
         .securityValidator("bearerAuth", (req, cred) -> Optional.empty())
         .securityValidator("basicAuth", (req, cred) -> Optional.empty())