Merge pull request 'fix(ext-openapi): one shared answer per status, not a numbered family' (#24 ) from fix/openapi/one-shared-answer-per-status into master

fix(ext-openapi): one shared answer per status, not a numbered family
Hoisting named a shared response after its status and disambiguated with a counter, so a document with three wordings for 403 grew Forbidden, Forbidden2 and Forbidden3 in its components. Numbered names say nothing and move as soon as a route is added. The answer a status is usually given is now the one hoisted, under that status's own name, and a route that answers the same status differently keeps its wording inline where it belongs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-23 16:34:15 +00:00 · 2026-09-23 16:34:13 +00:00 · 2026-09-23 15:47:37 +00:00 · 2026-09-23 15:47:35 +00:00 · 2026-09-23 14:51:28 +00:00 · 2026-09-23 14:51:16 +00:00
343 changed files with 12842 additions and 7837 deletions
@@ -17,8 +17,8 @@
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-limiter/src/main/resources" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-security-oidc/src/main/java" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-security-oidc/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-routeviewer/src/main/java" charset="UTF-8" />
@@ -31,8 +31,8 @@
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-view-thymeleaf/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-view/src/main/resources" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-web-bundler/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-vite/src/main/java" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-web-bundler/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-vite/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash-extensions/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/flash/src/main/java" charset="UTF-8" />
@@ -36,9 +36,10 @@ Format: `<type>(<scope>): <short description>`
 | `chore` | Build, deps, tooling — no production code |
 | `ci` | Changes to GitHub Actions workflows |
-Allowed scopes: `core`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
+Allowed scopes: `core`, `testing`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
-`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-web-bundler`,
+`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-vite`,
-`ext-mcp`, `ext-data-core`, `ext-data-jdbc`, `ext-data-hibernate`, `release`, `deps`, `ci`.
+`ext-mcp`, `ext-validation`, `ext-scheduler`, `ext-data-core`, `ext-data-jdbc`, `ext-data-hibernate`,
 `ext-cache-core`, `ext-cache-caffeine`, `release`, `deps`, `ci`.
 Examples:
 ```
@@ -85,6 +86,9 @@ chore(release): 2.1.0
 - Root POM: `flash-parent` — defines all dependency versions and plugin config.
 - `flash` module: the core framework JAR.
 - `flash-testing` module: JUnit 5 harness for testing Flash applications. Deliberately not
  under `flash-extensions/` — it is not something you `install()`, and it carries
  `junit-jupiter-api` at compile scope.
 - `flash-extensions` POM: aggregator for all extension modules.
 - Extensions live under `flash-extensions/flash-ext-*/`.
 - When adding a new extension:
@@ -8,13 +8,26 @@ a zero-allocation FSM router, bounded protocol state, and one shared request/res
 | Module | Description |
 |---|---|
 | `flash` | Core server library — HTTP/1.1 and HTTP/2 transport, router, request/response model |
-| `flash-extensions/flash-ext-jackson` | Jackson JSON integration |
+| `flash-testing` | JUnit 5 harness — boot an app on an ephemeral port, fake its services, assert on responses |
 | `flash-extensions/flash-ext-jackson-core` | What every Jackson format shares: the codec, the body handler, the constraints a body is checked against |
 | `flash-extensions/flash-ext-jackson-json` | JSON bodies and responses |
 | `flash-extensions/flash-ext-jackson-xml` | XML bodies and responses |
 | `flash-extensions/flash-ext-openapi` | OpenAPI 3.0 spec + Swagger UI |
-| `flash-extensions/flash-ext-oidc` | OIDC Authorization Code + PKCE flow |
+| `flash-extensions/flash-ext-security-core` | Security: authentication chain, annotations, sessions, OpenAPI |
-| `flash-extensions/flash-ext-mcp` | MCP (Model Context Protocol) server — Streamable HTTP, optional OAuth2 via flash-ext-oidc |
+| `flash-extensions/flash-ext-security-oidc` | OpenID Connect: bearer tokens, code flow + PKCE |
 | `flash-extensions/flash-ext-security-apikey` | API keys |
 | `flash-extensions/flash-ext-security-form` | Password sign-in |
 | `flash-extensions/flash-ext-security-oauth-server` | OAuth 2.1 authorization server for the application's own users and resources |
 | `flash-extensions/flash-ext-security-test` | Test identities, fake OpenID Provider |
 | `flash-extensions/flash-ext-mcp` | MCP (Model Context Protocol) server — Streamable HTTP, secured by flash-ext-security-core |
 | `flash-extensions/flash-ext-view-core` | Minimal shared SSR runtime primitives |
 | `flash-extensions/flash-ext-view-jte` | Opinionated jte SSR extension |
 | `flash-extensions/flash-ext-view-thymeleaf` | Opinionated Thymeleaf SSR extension |
 | `flash-extensions/flash-ext-vite` | Vite frontend: dev server in DEV, the built SPA from the jar otherwise |
 | `flash-extensions/flash-ext-vite-maven-plugin` | Builds the Vite frontend into the jar during `mvn package` |
 | `flash-extensions/flash-ext-scheduler` | Interval and cron background jobs on virtual threads |
 | `flash-extensions/flash-ext-cache-core` | Caching contract — `Cache`, `CacheManager`, `CacheSpec` |
 | `flash-extensions/flash-ext-cache-caffeine` | In-process cache backed by Caffeine |
 ## Requirements
@@ -139,12 +152,21 @@ FlashApp.create(8080)
 ```
 See extension-specific READMEs for full details:
- [`flash-ext-jackson`](flash-extensions/flash-ext-jackson/README.md)
+- [`flash-ext-jackson-core`](flash-extensions/flash-ext-jackson-core/README.md)
 - [`flash-ext-jackson-json`](flash-extensions/flash-ext-jackson-json/README.md)
 - [`flash-ext-jackson-xml`](flash-extensions/flash-ext-jackson-xml/README.md)
 - [`flash-ext-openapi`](flash-extensions/flash-ext-openapi/README.md)
- [`flash-ext-oidc`](flash-extensions/flash-ext-oidc/README.md)
+- [`flash-ext-security-core`](flash-extensions/flash-ext-security-core/docs/README.md)
 - [`flash-ext-security-oidc`](flash-extensions/flash-ext-security-oidc/docs/README.md)
 - [`flash-ext-security-apikey`](flash-extensions/flash-ext-security-apikey/docs/README.md)
 - [`flash-ext-security-form`](flash-extensions/flash-ext-security-form/docs/README.md)
 - [`flash-ext-security-test`](flash-extensions/flash-ext-security-test/docs/README.md)
 - [`flash-ext-mcp`](flash-extensions/flash-ext-mcp/docs/README.md)
 - [`flash-ext-view-jte`](flash-extensions/flash-ext-view-jte/README.md)
 - [`flash-ext-view-thymeleaf`](flash-extensions/flash-ext-view-thymeleaf/README.md)
 - [`flash-ext-scheduler`](flash-extensions/flash-ext-scheduler/docs/README.md)
 - [`flash-ext-cache-caffeine`](flash-extensions/flash-ext-cache-caffeine/docs/README.md)
 - [`flash-testing`](flash-testing/docs/README.md)
 ## Error handlers
@@ -389,6 +411,110 @@ The API renders as chunked data and trailers on HTTP/1.1, and DATA plus trailing
 HTTP/2. Flash core supplies these transport primitives; a higher-level gRPC codec belongs in a
 future `flash-ext-grpc` extension.
 ## Testing
 `flash-testing` boots a real app on an OS-assigned port for the duration of a test, and hands you
 a client pointed at it. Add it with test scope:
 ```xml
 <dependency>
    <groupId>dev.relism</groupId>
    <artifactId>flash-testing</artifactId>
    <version>${flash.version}</version>
    <scope>test</scope>
 </dependency>
 ```
 ```java
 class UserRoutesTest {
    @RegisterExtension
    static FlashTest app = FlashTest.of(new BlogApp())
            .mock(UserService.class, new InMemoryUserService());
    @Test
    void listsUsers() {
        app.get("/api/users")
           .expectStatus(200)
           .expectHeader("content-type", "application/json")
           .expectBodyContains("alice");
    }
 }
 ```
 `FlashTest.of` takes a `FlashApplication` — your app's routes, extensions and services expressed
 independently of which port they run on:
 ```java
 public final class BlogApp implements FlashApplication {
    @Override public void configure(FlashApp app) {
        app.install(new JacksonExtension());
        app.mount("/api", scope -> scope.scan("dev.blog.api"));
    }
 }
 FlashApp.create(8080).apply(new BlogApp()).startAndBlock();   // production
 ```
 It is a functional interface, so a lambda works too:
 `FlashTest.of(app -> app.get("/ping", (req, res) -> "pong"))`.
 ### Requests
 The HTTP verb sends the request; `expect*` assertions chain and report the real response body on
 failure. `get` and `delete` skip the builder when there is nothing to add.
 ```java
 app.get("/api/users").expectStatus(200);
 app.request()
   .header("Authorization", "Bearer " + token)
   .json("{\"name\":\"bob\"}")
   .post("/api/users")
   .expectStatus(201);
 try (FlashWebSocket socket = app.ws("/live")) {
    socket.sendText("hello");
    assertEquals("echo:hello", socket.awaitText(Duration.ofSeconds(2)));
 }
 ```
 ### Replacing services
 `mock` installs replacements after everything your app and its extensions declare, so a fake always
 wins. Any object will do — `flash-testing` depends on no mocking library, so a hand-written fake and
 a Mockito mock are equally welcome.
 ### More than one server
 `FlashTest` is an ordinary object in a field, so a test class can hold as many as it needs and wire
 one from another in plain Java. Startup is lazy — reading `baseUri()` boots that server on the spot
 — so declaration order does the wiring:
 ```java
@RegisterExtension static FlashTest auth = FlashTest.of(new FakeOidcApp());
@RegisterExtension static FlashTest api  = FlashTest.of(new BlogApp(auth.baseUri()));
 ```
 ### Scope
 A `static` field boots once for the test class; a non-static field boots a fresh app for every test.
 That is stock JUnit field semantics — the isolation switch is the keyword, not an option.
 ### Configuration
 Full reference: [`flash-testing/docs`](flash-testing/docs/README.md), including the
 [limits](flash-testing/docs/limits.md) the harness deliberately does not cross.
 `profile` customises the `FlashConfiguration` — timeouts, HTTP/2 switches, buffer sizes. Host, port
 and the shutdown drain window are stamped afterwards, so a profile cannot break the harness;
 `listener(...)` and `tls(...)` are rejected because the harness owns the loopback listener it gives
 you a client for.
 ```java
 FlashTest.of(new BlogApp()).profile(cfg -> cfg.http2CleartextEnabled(true));
 ```
 ## Architecture
 ```
@@ -0,0 +1,85 @@
 # flash-ext-cache-caffeine
 In-process caching backed by [Caffeine](https://github.com/ben-manes/caffeine). Implements
 [`flash-ext-cache-core`](../../flash-ext-cache-core/docs/README.md).
 ## Dependency
 ```xml
 <dependency>
    <groupId>dev.relism</groupId>
    <artifactId>flash-ext-cache-caffeine</artifactId>
    <version>${flash.version}</version>
 </dependency>
 ```
 ## Quick start
 ```java
 FlashApp.create(8080)
    .install(new CaffeineCacheExtension())
    .scan("dev.example.api");
 ```
 ```java
@GET("/api/users/{id}")
 public final class GetUser extends RequestHandler {
    private Cache<String, User> users;
    private UserRepository repo;
    @Override protected void onInit() {
        repo  = require(UserRepository.class);
        users = require(CacheManager.class).build("users", spec -> spec
                .maxSize(10_000)
                .ttl(Duration.ofMinutes(10)));
    }
    @Override public Object handle(Request req, Response res) {
        return users.get(req.param("id"), repo::findById);
    }
 }
 ```
 The extension takes no configuration. Each cache declares its own size and TTL where it is built.
 ## Why Caffeine and not a `LinkedHashMap`
 An LRU on top of `LinkedHashMap` is about sixty lines, and for a cache that is genuinely
 low-traffic it is the right answer — `ConcurrentHashMap::computeIfAbsent` is one line and has no
 hit rate to get wrong.
 This module exists for the case where that stops being true. Caffeine's W-TinyLFU admission,
 striped frequency counters and amortised eviction are not a weekend's work to reproduce, and the
 failure mode of getting them wrong is a cache that is *slower* than no cache — lock contention on
 every lookup, or an eviction policy that throws away exactly the entries you were about to want.
 ## Lifecycle
 Caches are released through `FlashContext.onClose`, so `app.stop()` drops every entry. That is
 invisible in production with one app per process and matters immediately under test, where many
 apps start and stop in one JVM.
 ## Statistics
 ```java
 CacheStats stats = users.stats();
 stats.hitRate();   // 0.0 until something is looked up
 ```
 Requires `recordStats()` on the spec. Without it you get `CacheStats.DISABLED`, which is honest
 about being unmeasured rather than reporting zeroes that look like a cold cache.
 `manager.names()` lists every cache built so far, for an ops endpoint.
 ## What this is not
 **HTTP caching.** If what you want is for the *client* to stop asking — `Cache-Control`, `ETag`,
 `304 Not Modified` — that is a middleware, not an object cache, and it saves the whole request
 rather than the lookup inside it. Reach for that first: it is cheaper, and the two solve different
 problems.
 **A shared cache.** Every replica has its own. Two instances will hold different values for the
 same key, and an invalidation on one does not reach the other. When that becomes a problem the
 answer is a networked backend — see the note on `flash-ext-cache-redis` — and the semantics change
 with it: a cache that can fail is no longer transparent.
@@ -0,0 +1,39 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-cache-caffeine</artifactId>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-cache-core</artifactId>
        </dependency>
        <!--
          Caffeine rather than a hand-rolled LRU: W-TinyLFU admission, striped counters and
          amortised eviction are not a weekend's work to get right, and getting them wrong is a
          cache that is slower than no cache.
        -->
        <dependency>
            <groupId>com.github.ben-manes.caffeine</groupId>
            <artifactId>caffeine</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-testing</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
 </project>
@@ -0,0 +1,41 @@
 package dev.relism.flash.ext.cache.caffeine;
 import dev.relism.flash.ext.cache.Cache;
 import dev.relism.flash.ext.cache.CacheStats;
 import java.util.function.Function;
 /**
 * {@link Cache} over a Caffeine cache. A thin adapter by design: every method delegates directly,
 * adding no wrapper object, no copy and no synchronisation of its own.
 */
 final class CaffeineCache<K, V> implements Cache<K, V> {
    private final com.github.benmanes.caffeine.cache.Cache<K, V> delegate;
    private final boolean statsRecorded;
    CaffeineCache(com.github.benmanes.caffeine.cache.Cache<K, V> delegate, boolean statsRecorded) {
        this.delegate = delegate;
        this.statsRecorded = statsRecorded;
    }
    @Override
    public V get(K key, Function<? super K, ? extends V> loader) {
        // Caffeine's own get(key, mappingFunction) already guarantees the loader runs once per key
        // across concurrent callers; wrapping it in anything of ours would only add a race.
        return delegate.get(key, loader);
    }
    @Override public V getIfPresent(K key)      { return delegate.getIfPresent(key); }
    @Override public void put(K key, V value)   { delegate.put(key, value); }
    @Override public void invalidate(K key)     { delegate.invalidate(key); }
    @Override public void invalidateAll()       { delegate.invalidateAll(); }
    @Override public long estimatedSize()       { return delegate.estimatedSize(); }
    @Override
    public CacheStats stats() {
        if (!statsRecorded) return CacheStats.DISABLED;
        com.github.benmanes.caffeine.cache.stats.CacheStats snapshot = delegate.stats();
        return new CacheStats(snapshot.hitCount(), snapshot.missCount(), snapshot.evictionCount());
    }
 }
@@ -0,0 +1,33 @@
 package dev.relism.flash.ext.cache.caffeine;
 import dev.relism.flash.ext.cache.CacheManager;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.extension.FlashRegistrar;
 /**
 * Installs an in-process {@link CacheManager} backed by Caffeine.
 *
 * <pre>{@code
 * FlashApp.create(8080)
 *     .install(new CaffeineCacheExtension())
 *     .scan("dev.example.api");
 * }</pre>
 *
 * <p>No configuration. Each cache declares its own size and TTL where it is built, because those
 * are properties of what is being cached, not of the process caching it.
 *
 * <p>Caches are dropped through {@link FlashContext#onClose}, so a stopped app does not keep its
 * values alive — which matters when many apps start and stop in one JVM, as they do under test.
 */
 public final class CaffeineCacheExtension implements FlashExtension {
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        ctx.supply(CacheManager.class, services -> {
            CaffeineCacheManager manager = new CaffeineCacheManager();
            services.onClose(manager::clear);
            return manager;
        });
    }
 }
@@ -0,0 +1,66 @@
 package dev.relism.flash.ext.cache.caffeine;
 import com.github.benmanes.caffeine.cache.Caffeine;
 import dev.relism.flash.ext.cache.Cache;
 import dev.relism.flash.ext.cache.CacheManager;
 import dev.relism.flash.ext.cache.CacheSpec;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 /** In-process {@link CacheManager} backed by Caffeine. */
 final class CaffeineCacheManager implements CacheManager {
    private final Map<String, Entry> caches = new ConcurrentHashMap<>();
    @Override
    @SuppressWarnings("unchecked")
    public <K, V> Cache<K, V> build(String name, java.util.function.Consumer<CacheSpec> configure) {
        CacheSpec spec = CacheSpec.of();
        configure.accept(spec);
        Entry entry = caches.computeIfAbsent(name, key -> new Entry(describe(spec), create(spec)));
        // Two handlers sharing a cache is the point; two handlers disagreeing about its size or
        // TTL is a bug that would otherwise resolve to whichever one ran first.
        String requested = describe(spec);
        if (!entry.signature.equals(requested))
            throw new IllegalStateException("Cache '" + name + "' already exists as " + entry.signature
                    + " but was requested as " + requested);
        return (Cache<K, V>) entry.cache;
    }
    @Override
    @SuppressWarnings("unchecked")
    public <K, V> Cache<K, V> cache(String name) {
        Entry entry = caches.get(name);
        return entry == null ? null : (Cache<K, V>) entry.cache;
    }
    @Override
    public Set<String> names() {
        return Set.copyOf(caches.keySet());
    }
    /** Releases every entry so a stopped app does not keep its values alive. */
    void clear() {
        caches.values().forEach(entry -> entry.cache.invalidateAll());
        caches.clear();
    }
    private static CaffeineCache<Object, Object> create(CacheSpec spec) {
        Caffeine<Object, Object> builder = Caffeine.newBuilder();
        if (spec.bounded()) builder.maximumSize(spec.maxSize());
        if (spec.ttl() != null) builder.expireAfterWrite(spec.ttl());
        if (spec.ttlAfterAccess() != null) builder.expireAfterAccess(spec.ttlAfterAccess());
        if (spec.statsRecorded()) builder.recordStats();
        return new CaffeineCache<>(builder.build(), spec.statsRecorded());
    }
    private static String describe(CacheSpec spec) {
        return "maxSize=" + spec.maxSize() + " ttl=" + spec.ttl()
                + " ttlAfterAccess=" + spec.ttlAfterAccess() + " stats=" + spec.statsRecorded();
    }
    private record Entry(String signature, CaffeineCache<Object, Object> cache) {}
 }
@@ -0,0 +1,160 @@
 package dev.relism.flash.ext.cache.caffeine;
 import dev.relism.flash.ext.cache.Cache;
 import dev.relism.flash.ext.cache.CacheManager;
 import dev.relism.flash.ext.cache.CacheStats;
 import dev.relism.flash.extension.FlashApp;
 import dev.relism.flash.extension.FlashConfiguration;
 import dev.relism.flash.testing.FlashTest;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import java.time.Duration;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.atomic.AtomicInteger;
 import static org.junit.jupiter.api.Assertions.*;
 class CaffeineCacheTest {
    private static final AtomicInteger loads = new AtomicInteger();
    @RegisterExtension
    static FlashTest app = FlashTest.of(configured -> {
        configured.install(new CaffeineCacheExtension());
        configured.ctx().onReady(() -> {
            Cache<String, String> users = configured.ctx().require(CacheManager.class)
                    .build("users", spec -> spec.maxSize(100).ttl(Duration.ofMinutes(5)).recordStats());
            configured.get("/users/{id}", (req, res) ->
                    users.get(req.param("id"), id -> "loaded:" + id + ":" + loads.incrementAndGet()));
        });
    });
    private static CacheManager manager() {
        return app.app().ctx().require(CacheManager.class);
    }
    @Test
    void aRepeatedRequestIsServedFromCache() {
        String first = app.get("/users/alice").expectStatus(200).body();
        String second = app.get("/users/alice").expectStatus(200).body();
        assertEquals(first, second);
        assertTrue(first.startsWith("loaded:alice:"));
    }
    @Test
    void distinctKeysLoadSeparately() {
        assertNotEquals(app.get("/users/bob").body(), app.get("/users/carol").body());
    }
    @Test
    void statsCountHitsAndMisses() {
        Cache<String, String> cache = manager().build("stats-probe", spec -> spec.maxSize(10).recordStats());
        cache.get("k", key -> "v");
        cache.get("k", key -> "v");
        CacheStats stats = cache.stats();
        assertEquals(1, stats.misses());
        assertEquals(1, stats.hits());
        assertEquals(0.5, stats.hitRate());
    }
    @Test
    void statsAreDisabledUnlessAskedFor() {
        Cache<String, String> cache = manager().build("no-stats", spec -> spec.maxSize(10));
        cache.get("k", key -> "v");
        assertEquals(CacheStats.DISABLED, cache.stats());
    }
    @Test
    void theLoaderRunsOncePerKeyUnderConcurrency() throws Exception {
        Cache<String, String> cache = manager().build("single-flight", spec -> spec.maxSize(10));
        AtomicInteger invocations = new AtomicInteger();
        int threads = 16;
        CountDownLatch start = new CountDownLatch(1);
        CountDownLatch done = new CountDownLatch(threads);
        for (int i = 0; i < threads; i++) {
            Thread.ofVirtual().start(() -> {
                try {
                    start.await();
                    cache.get("hot", key -> {
                        invocations.incrementAndGet();
                        return "value";
                    });
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                } finally {
                    done.countDown();
                }
            });
        }
        start.countDown();
        assertTrue(done.await(5, java.util.concurrent.TimeUnit.SECONDS));
        assertEquals(1, invocations.get(), "concurrent callers must share one load, not race");
    }
    @Test
    void aNullLoaderResultStoresNothing() {
        Cache<String, String> cache = manager().build("nulls", spec -> spec.maxSize(10));
        assertNull(cache.get("missing", key -> null));
        assertNull(cache.getIfPresent("missing"));
    }
    @Test
    void invalidateDropsOneKeyAndInvalidateAllDropsEverything() {
        Cache<String, String> cache = manager().build("invalidation", spec -> spec.maxSize(10));
        cache.put("a", "1");
        cache.put("b", "2");
        cache.invalidate("a");
        assertNull(cache.getIfPresent("a"));
        assertEquals("2", cache.getIfPresent("b"));
        cache.invalidateAll();
        assertNull(cache.getIfPresent("b"));
    }
    @Test
    void buildIsIdempotentPerName() {
        Cache<String, String> first = manager().build("shared", spec -> spec.maxSize(10));
        Cache<String, String> second = manager().build("shared", spec -> spec.maxSize(10));
        assertSame(first, second, "two handlers asking for one cache must get one cache");
        assertSame(first, manager().cache("shared"));
    }
    @Test
    void disagreeingOnASharedCacheIsARejectedMistakeNotASilentWinner() {
        manager().build("contested", spec -> spec.maxSize(10));
        IllegalStateException conflict = assertThrows(IllegalStateException.class,
                () -> manager().build("contested", spec -> spec.maxSize(999)));
        assertTrue(conflict.getMessage().contains("contested"), conflict.getMessage());
    }
    @Test
    void unknownNameReturnsNullRatherThanBuildingOne() {
        assertNull(manager().cache("never-built"));
    }
    /** Why CaffeineCacheExtension registers onClose: values must not outlive the app holding them. */
    @Test
    void stoppingTheAppReleasesEveryCache() {
        FlashApp standalone = FlashApp.create(FlashConfiguration.builder()
                .port(0).host("127.0.0.1").shutdownDrainTimeoutMs(250).build())
                .install(new CaffeineCacheExtension());
        standalone.start();
        CacheManager manager = standalone.ctx().require(CacheManager.class);
        manager.build("scoped", spec -> spec.maxSize(10)).put("k", "v");
        assertEquals(1, manager.names().size());
        standalone.stop().join();
        assertTrue(manager.names().isEmpty(), "caches must be released when the app stops");
    }
 }
@@ -0,0 +1,64 @@
 # flash-ext-cache-core
 The caching contract, shared across backends. Like `flash-ext-data-core`, this module talks to
 nothing: it defines the abstractions and a backend implements them.
 ## Components
 - `Cache<K, V>` — a named cache. `get(key, loader)` is the method that matters.
 - `CacheManager` — creates and hands back named caches.
 - `CacheSpec` — size and expiry for one cache.
 - `CacheStats` — hit/miss/eviction counters.
 Install a backend, not this module: [`flash-ext-cache-caffeine`](../../flash-ext-cache-caffeine/docs/README.md)
 for in-process caching.
 ## The one shape that matters
 ```java
 User user = users.get(id, repo::findById);
 ```
 Compute-if-absent is the only cache operation most code needs, and the only one that is hard to
 get right — the loader runs **once per key** across concurrent callers, and the rest wait rather
 than each computing their own. `getIfPresent`, `put`, `invalidate` and `invalidateAll` exist for
 what it cannot express.
 A loader returning `null` stores nothing and returns `null`. Caching absence is a decision, not a
 default; wrap it in an `Optional` or a sentinel if you want it.
 ## Naming and sharing
 `CacheManager.build(name, spec)` is idempotent per name: two handlers asking for `"users"` get one
 cache, not two, so nobody has to coordinate who creates it first.
 If they disagree about the spec, that throws. The alternative is a cache whose size depends on
 which handler happened to initialise first, which is the kind of bug that only shows up under
 load.
 ## Specs
 ```java
 CacheSpec.of()
    .maxSize(10_000)
    .ttl(Duration.ofMinutes(10))
    .recordStats();
 ```
 Every field is optional, but a spec that sets neither `maxSize` nor `ttl` is an unbounded cache
 that never expires — a memory leak wearing a hat. Set at least one.
 `recordStats()` is off by default: counting costs a pair of atomic increments on every lookup, and
 a cache nobody is measuring should not pay for numbers nobody reads. Without it, `stats()` returns
 `CacheStats.DISABLED` rather than silently zero.
 ## Where the spec lives
 On the cache, at the point it is built — not in application config. Size and TTL are properties of
 *what is being cached*, not of the process doing the caching, and a TTL in a config file is a TTL
 nobody can relate back to the data it governs.
 ## Writing a backend
 Implement `CacheManager` and `Cache`, provide the manager from a `FlashExtension`, and register
 cleanup with `FlashContext.onClose` so a stopped app does not keep its values alive.
@@ -0,0 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-cache-core</artifactId>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
        </dependency>
    </dependencies>
 </project>
@@ -0,0 +1,50 @@
 package dev.relism.flash.ext.cache;
 import java.util.function.Function;
 /**
 * A named cache. Obtained from a {@link CacheManager}, safe to hold in a handler field and share
 * across threads.
 *
 * <pre>{@code
 * User user = users.get(id, repo::findById);
 * }</pre>
 *
 * <p>{@link #get} is the only method most code needs. The rest exist for the cases it cannot
 * express: reading without populating, writing a value computed elsewhere, and invalidating.
 *
 * @param <K> key type — must have a stable {@code hashCode}/{@code equals}
 * @param <V> value type
 */
 public interface Cache<K, V> {
    /**
     * Returns the cached value, computing and storing it with {@code loader} if absent.
     *
     * <p>The loader runs at most once per key across concurrent callers; the others wait for it
     * rather than each computing their own. A loader returning {@code null} stores nothing and
     * {@code null} is returned.
     */
    V get(K key, Function<? super K, ? extends V> loader);
    /** The cached value, or {@code null} if absent. Never invokes a loader. */
    V getIfPresent(K key);
    /** Stores {@code value}, replacing any existing entry. */
    void put(K key, V value);
    /** Drops {@code key}. Does nothing if it was absent. */
    void invalidate(K key);
    /** Drops every entry. */
    void invalidateAll();
    /** Approximate entry count. Approximate because eviction is asynchronous in most backends. */
    long estimatedSize();
    /**
     * Hit/miss counters since this cache was built, or {@link CacheStats#DISABLED} when the
     * backend was not asked to record them.
     */
    CacheStats stats();
 }
@@ -0,0 +1,31 @@
 package dev.relism.flash.ext.cache;
 import java.util.function.Consumer;
 /**
 * Creates and hands back named caches. Resolve it with {@code require(CacheManager.class)}; a
 * backend extension such as {@code flash-ext-cache-caffeine} provides the implementation.
 *
 * <pre>{@code
 * @Override protected void onInit() {
 *     users = require(CacheManager.class).build("users", spec -> spec
 *             .maxSize(10_000)
 *             .ttl(Duration.ofMinutes(10)));
 * }
 * }</pre>
 *
 * <p>{@link #build} is idempotent per name: calling it twice returns the same cache rather than
 * two, so several handlers can share one without coordinating who creates it. The spec of the
 * first call wins; a later call with a different spec is a configuration mistake and throws.
 */
 public interface CacheManager {
    /** Creates the named cache, or returns the existing one. */
    <K, V> Cache<K, V> build(String name, Consumer<CacheSpec> spec);
    /** The named cache, or {@code null} if {@link #build} has not been called for it. */
    <K, V> Cache<K, V> cache(String name);
    /** Every cache name built so far, for an ops endpoint. */
    java.util.Set<String> names();
 }
@@ -0,0 +1,64 @@
 package dev.relism.flash.ext.cache;
 import java.time.Duration;
 /**
 * How one cache should behave. Every field is optional — a spec that sets nothing gives an
 * unbounded cache that never expires, which is a memory leak wearing a hat, so set at least one
 * of {@link #maxSize} or {@link #ttl}.
 *
 * <pre>{@code
 * CacheSpec.of().maxSize(10_000).ttl(Duration.ofMinutes(10))
 * }</pre>
 *
 * <p>Mutable builder rather than a record with {@code withX} copies: it is constructed once at
 * boot inside a lambda and never shared.
 */
 public final class CacheSpec {
    private long maxSize = -1;
    private Duration ttl;
    private Duration ttlAfterAccess;
    private boolean recordStats;
    private CacheSpec() {}
    public static CacheSpec of() {
        return new CacheSpec();
    }
    /** Maximum entries before the backend starts evicting. Negative means unbounded. */
    public CacheSpec maxSize(long maxSize) {
        this.maxSize = maxSize;
        return this;
    }
    /** Entries expire this long after they were written. */
    public CacheSpec ttl(Duration ttl) {
        this.ttl = ttl;
        return this;
    }
    /** Entries expire this long after they were last read or written. */
    public CacheSpec ttlAfterAccess(Duration ttlAfterAccess) {
        this.ttlAfterAccess = ttlAfterAccess;
        return this;
    }
    /**
     * Records hit/miss counters for {@link Cache#stats()}.
     *
     * <p>Off by default: counting costs a pair of atomic increments on every lookup, and a cache
     * nobody is measuring should not pay for numbers nobody reads.
     */
    public CacheSpec recordStats() {
        this.recordStats = true;
        return this;
    }
    public long maxSize()            { return maxSize; }
    public Duration ttl()            { return ttl; }
    public Duration ttlAfterAccess() { return ttlAfterAccess; }
    public boolean statsRecorded()   { return recordStats; }
    public boolean bounded()         { return maxSize >= 0; }
 }
@@ -0,0 +1,20 @@
 package dev.relism.flash.ext.cache;
 /**
 * Hit/miss counters for one cache.
 *
 * @param hits      lookups that found a value
 * @param misses    lookups that had to load
 * @param evictions entries dropped to respect {@link CacheSpec#maxSize()}
 */
 public record CacheStats(long hits, long misses, long evictions) {
    /** Returned when {@link CacheSpec#recordStats()} was not set — all zero, and says so. */
    public static final CacheStats DISABLED = new CacheStats(0, 0, 0);
    /** Hits divided by lookups, or 0 when nothing has been looked up yet. */
    public double hitRate() {
        long total = hits + misses;
        return total == 0 ? 0 : (double) hits / total;
    }
 }
@@ -0,0 +1,39 @@
 # flash-ext-cache-redis — planned
 Not implemented. This directory holds the design so the decision is written down rather than
 rediscovered; there is deliberately **no module, no pom and no source**, because an empty module
 that builds an empty jar is dead weight in the reactor and in everyone's dependency tree.
 Add it when there is a second replica that actually needs shared state.
 ## What it would implement
 `CacheManager` and `Cache` from [`flash-ext-cache-core`](../../flash-ext-cache-core/docs/README.md),
 so switching backend is an install-line change:
 ```java
 .install(new RedisCacheExtension(RedisConfig.of("redis://localhost:6379")))
 ```
 ## The part that is not a drop-in
 `flash-ext-cache-caffeine` cannot fail. A networked cache can, and that changes the contract in
 ways an adapter cannot hide:
 - **`get(key, loader)` can fail before reaching the loader.** The honest default is to fall
  through to the loader and serve the value uncached, so Redis being down degrades throughput
  rather than taking the application with it. That has to be a decision, not an accident.
 - **Values must be serialized.** Caffeine stores references. A `byte[]` codec belongs in the spec,
  and the natural default is whatever `flash-ext-jackson` is already configured with.
 - **`invalidateAll()` is not free.** Against a shared keyspace it is either a scan or a key
  prefix per cache name. The prefix is the right answer, and it means cache names become part of
  the wire contract.
 - **Stats are per-client, not per-cache.** Hit rate stays meaningful; eviction count does not,
  because Redis evicts on its own policy.
 ## Why it is not built yet
 Nothing in the codebase has two replicas sharing cache state. Building it now would mean choosing
 a client library, a serialization format and a failure policy with no real usage to check them
 against — and the failure policy in particular is the kind of decision that is wrong until a
 production incident tells you otherwise.
@@ -112,6 +112,8 @@ public abstract class Repository<T, ID> {
 - `Tx` in the `FlashContext`
 - `TxManager` in the `FlashContext`
 - an annotation processor for `@Transactional`
 - `TxManager.close()` as an `onClose` callback, so stopping the app releases the manager's
  session factory and connection pool; give the manager a pool you want closed with the app
 This makes the data layer composable with Flash's extension system without global state.
@@ -34,6 +34,7 @@ public final class DataExtension implements FlashExtension {
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        ctx.onClose(txManager::close);
        ctx.provide(Tx.class, tx);
        ctx.provide(TxManager.class, txManager);
        if (data != null) ctx.provide(Data.class, data);
@@ -1,7 +1,11 @@
 package dev.relism.flash.ext.data.core;
-public interface TxManager {
+public interface TxManager extends AutoCloseable {
    TxStatus begin(TxDefinition definition);
    void commit(TxStatus status);
    void rollback(TxStatus status);
    /** Releases what this manager was built on, its connection pool included. {@link dev.relism.flash.ext.data.DataExtension} calls it when the app stops. */
    @Override
    void close();
 }
@@ -3,6 +3,10 @@ package dev.relism.flash.ext.data.hibernate;
 import dev.relism.flash.ext.data.core.*;
 import org.hibernate.Session;
 import org.hibernate.SessionFactory;
 import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
 import javax.sql.DataSource;
 import java.util.Objects;
@@ -16,6 +20,24 @@ public class HibernateTxManager implements TxManager {
        this.sf = Objects.requireNonNull(sessionFactory);
    }
    /**
     * Closes the session factory, then the data source it was given ({@code jakarta.persistence.nonJtaDataSource}
     * or {@code hibernate.connection.datasource}): Hibernate stops a pool it built itself, never one handed to it.
     */
    @Override
    public void close() {
        ConnectionProvider connections = sf.unwrap(SessionFactoryImplementor.class).getServiceRegistry().getService(ConnectionProvider.class);
        DataSource ds = connections != null && connections.isUnwrappableAs(DataSource.class) ? connections.unwrap(DataSource.class) : null;
        sf.close();
        if (ds instanceof AutoCloseable closeable) {
            try {
                closeable.close();
            } catch (Exception e) {
                throw new IllegalStateException("Failed to close the data source", e);
            }
        }
    }
    @Override
    public TxStatus begin(TxDefinition definition) {
        return switch (definition.propagation()) {
@@ -0,0 +1,48 @@
 package dev.relism.flash.ext.data.hibernate;
 import org.hibernate.SessionFactory;
 import org.hibernate.boot.MetadataSources;
 import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
 import org.hibernate.cfg.AvailableSettings;
 import org.junit.jupiter.api.Test;
 import javax.sql.DataSource;
 import java.io.PrintWriter;
 import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.SQLException;
 import java.util.logging.Logger;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 class HibernateTxManagerCloseTest {
    /** Stands in for a pool: closeable, and it records being closed. */
    static final class Pool implements DataSource, AutoCloseable {
        boolean closed;
        @Override public Connection getConnection() throws SQLException { return DriverManager.getConnection("jdbc:h2:mem:tx-close;DB_CLOSE_DELAY=-1"); }
        @Override public Connection getConnection(String user, String password) throws SQLException { return getConnection(); }
        @Override public void close() { closed = true; }
        @Override public <T> T unwrap(Class<T> type) { throw new UnsupportedOperationException(); }
        @Override public boolean isWrapperFor(Class<?> type) { return false; }
        @Override public PrintWriter getLogWriter() { return null; }
        @Override public void setLogWriter(PrintWriter out) {}
        @Override public void setLoginTimeout(int seconds) {}
        @Override public int getLoginTimeout() { return 0; }
        @Override public Logger getParentLogger() { throw new UnsupportedOperationException(); }
    }
    @Test
    void closingTheManagerClosesTheDataSourceHibernateWasGiven() {
        Pool pool = new Pool();
        SessionFactory sf = new MetadataSources(new StandardServiceRegistryBuilder()
                .applySetting(AvailableSettings.JAKARTA_NON_JTA_DATASOURCE, pool)
                .applySetting(AvailableSettings.DIALECT, "org.hibernate.dialect.H2Dialect")
                .build()).buildMetadata().buildSessionFactory();
        new HibernateTxManager(sf).close();
        assertTrue(sf.isClosed());
        assertTrue(pool.closed);
    }
 }
@@ -17,6 +17,18 @@ public class JdbcTxManager implements TxManager {
        this.ds = Objects.requireNonNull(ds);
    }
    /** Closes the data source when it is closeable, as a pool is; a plain {@code DataSource} holds nothing to release. */
    @Override
    public void close() {
        if (ds instanceof AutoCloseable closeable) {
            try {
                closeable.close();
            } catch (Exception e) {
                throw new IllegalStateException("Failed to close the data source", e);
            }
        }
    }
    @Override
    public TxStatus begin(TxDefinition definition) {
        return switch (definition.propagation()) {
@@ -0,0 +1,20 @@
 package dev.relism.flash.ext.data.jdbc;
 import com.zaxxer.hikari.HikariDataSource;
 import dev.relism.flash.ext.data.DataExtension;
 import dev.relism.flash.extension.FlashApp;
 import org.junit.jupiter.api.Test;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 class JdbcTxManagerCloseTest {
    /** A pool outlives its app unless someone closes it; the data extension does, once requests have drained. */
    @Test
    void stoppingTheAppClosesThePool() {
        HikariDataSource pool = new HikariDataSource();
        pool.setJdbcUrl(TestDataSource.URL);
        FlashApp.create(0).install(new DataExtension(new JdbcTxManager(pool))).start().stop().join();
        assertTrue(pool.isClosed());
    }
 }
@@ -0,0 +1,78 @@
 # flash-ext-jackson-core
 What every Jackson data format shares. Applications do not install this module directly: they
 install a format — [`flash-ext-jackson-json`](../flash-ext-jackson-json),
 [`flash-ext-jackson-xml`](../flash-ext-jackson-xml) — and get all of this with it.
 ## Why there is a core at all
 Every Jackson data format is the same databind model behind a different factory: `XmlMapper`,
 `YAMLMapper` and `CBORMapper` are all `ObjectMapper`s. So the annotations on a type, the
 constraints its fields declare and the schema it publishes are the same whatever writes it. Only
 the mapper and the content type differ, and that is all a format module has to say.
 ## Codec
 One mapper, in the shape a handler needs it.
 | | |
 |---|---|
 | `body(Request, Class<T>)` | Parses the body and verifies its constraints |
 | `write(Response, Object)` | Serializes and sets the format's content type |
 | `writeView(Response, Object, Class<?>)` | The same, through a Jackson `@JsonView` |
 | `mapper()` | The `ObjectMapper` itself, for everything else |
 `body` reads straight off the request's stream, which Flash reuses per connection: the body is
 never buffered into an array to be handed over. A malformed body is a 400, a body that breaks a
 constraint is a 422, and neither reaches the handler.
 ## Constraints
 A body is checked against the `jakarta.validation` annotations its own type declares — nothing to
 install, nothing to call:
 ```java
 public record NewUser(@NotBlank @Size(max = 80) String name, @Email String email, @Min(18) int age) {}
 ```
 Supported: `@NotNull`, `@NotBlank`, `@NotEmpty`, `@Size`, `@Min`, `@Max`, `@Email`, `@Pattern`.
 Jakarta semantics: only `@NotNull` rejects null, every other constraint passes it.
 A failure reads `<field> <message>`, and the message is the constraint's own when it sets one —
 which is how the person who sent the request is told something better than a regex:
 ```java
@Pattern(regexp = "[A-Za-z0-9_][A-Za-z0-9_.-]{0,254}", message = "uses up to 255 letters, digits, _, . and -")
 String key
 ```
 ```json
 {"error": "key uses up to 255 letters, digits, _, . and -", "status": 422}
 ```
 The constraints of a type are compiled the first time it is seen and kept in a `ClassValue`,
 beside the class itself — no map, no lock. A check reads the field through an exact-signature
 `MethodHandle`: no boxing, no argument array, no iterator, and nothing allocated at all unless
 something fails. A type that declares no constraints compiles to a validator that does nothing.
 Verify a value built by hand with `Validator.check(value)`.
 `flash-ext-openapi` reads the same annotations to publish `minLength`, `maximum`, `pattern` and
 the required fields, so a rule is written once and both enforced and documented.
 ## Writing a format module
 ```java
 public final class Yaml extends Codec {
    public Yaml(YAMLMapper mapper) { super(mapper, ContentType.TEXT_YAML); }
 }
@Consumes(ContentType.TEXT_YAML)
 public abstract class YamlHandler<B> extends JacksonHandler<B> {
    @Inject private Yaml yaml;
    @Override protected Codec codec() { return yaml; }
 }
 ```
 Plus an extension that provides the codec and, for outbound bodies,
 `Marshalling.of(mapper, contentType)`. That is the whole of it.
@@ -0,0 +1,47 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-jackson-core</artifactId>
    <name>flash-ext-jackson-core</name>
    <description>What every Jackson data format shares: the codec, the body handler and the constraints a body is checked against.</description>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
        </dependency>
        <!-- The constraint annotations a body is checked against; no implementation, no transitives. -->
        <dependency>
            <groupId>jakarta.validation</groupId>
            <artifactId>jakarta.validation-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
 </project>
@@ -0,0 +1,76 @@
 package dev.relism.flash.ext.jackson;
 import java.lang.invoke.MethodHandle;
 import java.util.regex.Pattern;
 /**
 * One constraint, compiled. Flattened into an opcode plus its operands rather than a class per
 * constraint type: the check loop becomes a {@code tableswitch} over a monomorphic array instead
 * of a megamorphic virtual call, and a passing check touches no allocation at all.
 *
 * <p>Field access goes through a {@link MethodHandle} adapted at compile time to an exact
 * signature — {@code (Object)Object} for reference fields, {@code (Object)long} for primitive
 * integrals — so {@code invokeExact} neither boxes nor allocates an argument array the way
 * {@code Field.get} and {@code Method.invoke} do.
 */
 final class Check {
    static final int NOT_NULL = 0;
    static final int NOT_BLANK = 1;
    static final int NOT_EMPTY = 2;
    static final int SIZE = 3;
    static final int RANGE_PRIMITIVE = 4;
    static final int RANGE_BOXED = 5;
    static final int EMAIL = 6;
    static final int PATTERN = 7;
    final int op;
    final String field;
    /** Pre-rendered at compile time, so even the failure path formats nothing. */
    final String message;
    /** {@code (Object)Object} — set for every op except {@link #RANGE_PRIMITIVE}. */
    final MethodHandle ref;
    /** {@code (Object)long} — set only for {@link #RANGE_PRIMITIVE}. */
    final MethodHandle num;
    final int min;
    final int max;
    final long lo;
    final long hi;
    final Pattern pattern;
    private Check(int op, String field, String message, MethodHandle ref, MethodHandle num,
                  int min, int max, long lo, long hi, Pattern pattern) {
        this.op = op;
        this.field = field;
        this.message = message;
        this.ref = ref;
        this.num = num;
        this.min = min;
        this.max = max;
        this.lo = lo;
        this.hi = hi;
        this.pattern = pattern;
    }
    static Check reference(int op, String field, String message, MethodHandle ref) {
        return new Check(op, field, message, ref, null, 0, 0, 0, 0, null);
    }
    static Check size(String field, String message, MethodHandle ref, int min, int max) {
        return new Check(SIZE, field, message, ref, null, min, max, 0, 0, null);
    }
    static Check rangePrimitive(String field, String message, MethodHandle num, long lo, long hi) {
        return new Check(RANGE_PRIMITIVE, field, message, null, num, 0, 0, lo, hi, null);
    }
    static Check rangeBoxed(String field, String message, MethodHandle ref, long lo, long hi) {
        return new Check(RANGE_BOXED, field, message, ref, null, 0, 0, lo, hi, null);
    }
    static Check pattern(String field, String message, MethodHandle ref, Pattern pattern) {
        return new Check(PATTERN, field, message, ref, null, 0, 0, 0, 0, pattern);
    }
 }
@@ -0,0 +1,72 @@
 package dev.relism.flash.ext.jackson;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.Response;
 /**
 * One Jackson mapper, in the shape a handler needs it.
 *
 * <p>Every Jackson data format is the same databind model behind a different factory, so this is
 * the whole of what a format module has to say: which mapper, and which content type it writes.
 * What the annotations mean, what a body is checked against and how a type is described are the
 * same for all of them.
 *
 * <p>Retrieve it once at boot — {@code @Inject private Json json;} — and call it on the hot path.
 * The underlying {@link ObjectMapper} is thread-safe once configured.
 */
 public abstract class Codec {
    private final ObjectMapper mapper;
    private final ContentType contentType;
    protected Codec(ObjectMapper mapper, ContentType contentType) {
        this.mapper = mapper;
        this.contentType = contentType;
    }
    /**
     * Reads the request body as {@code type} and verifies its constraints.
     *
     * <p>Read straight off the request's stream, which Flash reuses per connection: nothing
     * buffers the body to hand it over. A type that declares no constraints is not checked at all.
     *
     * @throws HttpException 400 if the body cannot be parsed as {@code type}
     * @throws ValidationException 422 if it parses but violates a constraint
     */
    public <T> T body(Request request, Class<T> type) throws Exception {
        T value;
        try {
            value = mapper.readValue(request.body().stream(), type);
        } catch (JsonProcessingException malformed) {
            throw HttpException.badRequest("Invalid request body: " + malformed.getOriginalMessage());
        }
        Validator.of(type).verify(value);
        return value;
    }
    /** Serializes {@code value} and sets this codec's content type on the response. */
    public String write(Response response, Object value) throws Exception {
        response.type(contentType);
        return mapper.writeValueAsString(value);
    }
    /** Like {@link #write}, restricted to the fields visible under a Jackson {@code @JsonView}. */
    public String writeView(Response response, Object value, Class<?> view) throws Exception {
        response.type(contentType);
        return mapper.writerWithView(view).writeValueAsString(value);
    }
    /** What this codec writes, for a handler that sets the response type itself. */
    public ContentType contentType() {
        return contentType;
    }
    /** The mapper itself, for everything these methods do not cover. */
    public ObjectMapper mapper() {
        return mapper;
    }
 }
@@ -0,0 +1,33 @@
 package dev.relism.flash.ext.jackson;
 import dev.relism.flash.models.BodyHandler;
 import dev.relism.flash.models.Request;
 /**
 * A handler whose body one Jackson format parses and whose constraints are checked before it
 * arrives.
 *
 * <p>Format modules extend this and name their codec — {@code JsonHandler}, {@code XmlHandler}.
 * An application extends those, never this one.
 *
 * @param <B> the body type, which is also what the published OpenAPI document describes
 */
 public abstract class JacksonHandler<B> extends BodyHandler<B> {
    private final Class<B> type = bodyType();
    protected JacksonHandler() {
        if (type == null) {
            throw new IllegalStateException(getClass().getSimpleName()
                    + " extends a body handler without naming its body type — write it as Handler<YourBody>");
        }
    }
    /** The format this handler speaks. Injected by the subclass, resolved once at boot. */
    protected abstract Codec codec();
    @Override
    protected final B body(Request request) throws Exception {
        return codec().body(request, type);
    }
 }
@@ -0,0 +1,32 @@
 package dev.relism.flash.ext.jackson;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.routing.Middleware;
 /**
 * Turns whatever a handler returns into a serialized body.
 *
 * <p>Pass-through for what is already a response: {@code null}, a {@link Response}, a
 * {@code byte[]} or a {@link CharSequence}. Everything else is serialized straight to bytes.
 */
 public final class Marshalling {
    private Marshalling() {}
    public static Middleware of(ObjectMapper mapper, ContentType contentType) {
        return next -> (req, res) -> {
            Object out = next.handle(req, res);
            if (out == null || out instanceof Response || out instanceof byte[] || out instanceof CharSequence) return out;
            res.type(contentType);
            try {
                return mapper.writeValueAsBytes(out);
            } catch (JsonProcessingException failure) {
                throw new IllegalStateException("Could not serialize " + out.getClass().getName(), failure);
            }
        };
    }
 }
@@ -0,0 +1,39 @@
 package dev.relism.flash.ext.jackson;
 import dev.relism.flash.exceptions.HttpException;
 import java.util.List;
 /**
 * Raised when a value fails its constraints. Extends {@link HttpException} with status 422, so
 * Flash's default exception handler renders it without this extension registering anything.
 *
 * <p>Allocated only on failure — a passing validation constructs nothing.
 */
 public final class ValidationException extends HttpException {
    private final transient List<Violation> violations;
    public ValidationException(List<Violation> violations) {
        super(422, describe(violations));
        this.violations = List.copyOf(violations);
    }
    /** The individual failures, in field declaration order. */
    public List<Violation> violations() {
        return violations;
    }
    private static String describe(List<Violation> violations) {
        StringBuilder out = new StringBuilder(32 * violations.size());
        for (int i = 0; i < violations.size(); i++) {
            if (i > 0) out.append("; ");
            Violation v = violations.get(i);
            out.append(v.field()).append(' ').append(v.message());
        }
        return out.toString();
    }
    /** One failed constraint. */
    public record Violation(String field, String message) {}
 }
@@ -0,0 +1,255 @@
 package dev.relism.flash.ext.jackson;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Pattern;
 import jakarta.validation.constraints.Size;
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodHandles;
 import java.lang.invoke.MethodType;
 import java.lang.reflect.Field;
 import java.lang.reflect.Modifier;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 /**
 * The compiled constraints of one type. Built once per class and reused for every request.
 *
 * <p>{@link #verify} allocates nothing when a value passes: the loop walks an array (no iterator),
 * reads fields through exact-signature {@link MethodHandle}s (no boxing, no argument array), and
 * compares against operands resolved at compile time. The violation list and the exception are
 * constructed only once something actually fails.
 */
 public final class Validator {
    private static final Check[] NONE = new Check[0];
    /**
     * One compiled validator per type, kept beside the class itself: no map lookup, no lock, and
     * the entry is collected with the class rather than pinning it.
     */
    private static final ClassValue<Validator> COMPILED = new ClassValue<>() {
        @Override protected Validator computeValue(Class<?> type) {
            return compile(type);
        }
    };
    private final Check[] checks;
    private Validator(Check[] checks) {
        this.checks = checks;
    }
    /** The constraints of {@code type}, compiled the first time it is seen and reused after. */
    public static Validator of(Class<?> type) {
        return COMPILED.get(type);
    }
    /**
     * Verifies a value against its own type's constraints.
     *
     * @return {@code value}, so it can be used inline
     * @throws ValidationException 422, listing every failure
     */
    public static <T> T check(T value) {
        of(value.getClass()).verify(value);
        return value;
    }
    /** True when the type declares no constraints at all — {@link #verify} is then a no-op. */
    public boolean isEmpty() {
        return checks.length == 0;
    }
    /**
     * Verifies every constraint on {@code target}.
     *
     * @throws ValidationException with all failures, never just the first
     */
    public void verify(Object target) {
        List<ValidationException.Violation> failures = null;
        for (Check check : checks) {
            if (passes(check, target)) continue;
            if (failures == null) failures = new ArrayList<>(4);
            failures.add(new ValidationException.Violation(check.field, check.message));
        }
        if (failures != null) throw new ValidationException(failures);
    }
    private static boolean passes(Check check, Object target) {
        try {
            if (check.op == Check.RANGE_PRIMITIVE) {
                long value = (long) check.num.invokeExact(target);
                return value >= check.lo && value <= check.hi;
            }
            Object value = (Object) check.ref.invokeExact(target);
            // Jakarta semantics: only @NotNull rejects null; every other constraint passes it.
            return switch (check.op) {
                case Check.NOT_NULL    -> value != null;
                case Check.NOT_BLANK   -> value instanceof String text && !text.isBlank();
                case Check.NOT_EMPTY   -> value != null && sizeOf(value) > 0;
                case Check.SIZE        -> value == null || withinSize(check, value);
                case Check.RANGE_BOXED -> value == null || withinRange(check, (Number) value);
                case Check.EMAIL       -> value == null || (value instanceof String text && isEmail(text));
                case Check.PATTERN     -> value == null
                        || (value instanceof String text && check.pattern.matcher(text).matches());
                default -> true;
            };
        } catch (Throwable failure) {
            throw new IllegalStateException("Could not read " + check.field + " for validation", failure);
        }
    }
    private static boolean withinSize(Check check, Object value) {
        int size = sizeOf(value);
        return size >= check.min && size <= check.max;
    }
    private static boolean withinRange(Check check, Number value) {
        long asLong = value.longValue();
        return asLong >= check.lo && asLong <= check.hi;
    }
    /** No copies: every branch reads a length the object already knows. */
    private static int sizeOf(Object value) {
        if (value instanceof CharSequence text) return text.length();
        if (value instanceof Collection<?> items) return items.size();
        if (value instanceof Map<?, ?> entries) return entries.size();
        if (value instanceof Object[] array) return array.length;
        return 1;
    }
    /**
     * Structural check rather than a regex: {@code Pattern.matcher} allocates a matcher, an int
     * array and a group array on every call, which is exactly the per-request cost this module
     * exists to avoid. {@code indexOf} allocates nothing.
     *
     * <p>Accepts what a mail server would plausibly route and rejects the shapes people actually
     * typo. Deliverability is the confirmation mail's job, not a validator's.
     */
    private static boolean isEmail(String value) {
        int at = value.indexOf('@');
        if (at <= 0 || at == value.length() - 1) return false;
        if (value.indexOf('@', at + 1) >= 0) return false;
        int dot = value.indexOf('.', at + 2);
        return dot > 0 && dot < value.length() - 1 && value.indexOf(' ') < 0;
    }
    // ── Compilation ──────────────────────────────────────────────────────────
    /**
     * Compiles {@code type}'s constraints once.
     *
     * <p>Reads declared fields rather than record accessors: a constraint on a record component
     * propagates to the backing field, so records and plain classes need one code path, not two.
     */
    static Validator compile(Class<?> type) {
        MethodHandles.Lookup lookup;
        try {
            lookup = MethodHandles.privateLookupIn(type, MethodHandles.lookup());
        } catch (IllegalAccessException denied) {
            throw new IllegalStateException(
                    "Cannot read " + type.getName() + " for validation — open its module or package", denied);
        }
        List<Check> checks = new ArrayList<>();
        for (Field field : type.getDeclaredFields()) {
            if (Modifier.isStatic(field.getModifiers())) continue;
            MethodHandle getter;
            try {
                getter = lookup.unreflectGetter(field);
            } catch (IllegalAccessException denied) {
                continue;
            }
            compileField(field, getter, checks);
        }
        return new Validator(checks.isEmpty() ? NONE : checks.toArray(new Check[0]));
    }
    private static void compileField(Field field, MethodHandle getter, List<Check> checks) {
        String name = field.getName();
        Class<?> type = field.getType();
        MethodHandle ref = type.isPrimitive() ? null : asReference(getter);
        NotNull notNull = field.getAnnotation(NotNull.class);
        if (notNull != null && ref != null)
            checks.add(Check.reference(Check.NOT_NULL, name, said(notNull.message(), "must not be null"), ref));
        NotBlank notBlank = field.getAnnotation(NotBlank.class);
        if (notBlank != null && ref != null)
            checks.add(Check.reference(Check.NOT_BLANK, name, said(notBlank.message(), "must not be blank"), ref));
        NotEmpty notEmpty = field.getAnnotation(NotEmpty.class);
        if (notEmpty != null && ref != null)
            checks.add(Check.reference(Check.NOT_EMPTY, name, said(notEmpty.message(), "must not be empty"), ref));
        Size size = field.getAnnotation(Size.class);
        if (size != null && ref != null)
            checks.add(Check.size(name, said(size.message(), sizeMessage(size)), ref, size.min(), size.max()));
        Min min = field.getAnnotation(Min.class);
        Max max = field.getAnnotation(Max.class);
        if (min != null || max != null) {
            long lo = min != null ? min.value() : Long.MIN_VALUE;
            long hi = max != null ? max.value() : Long.MAX_VALUE;
            String message = said(min != null ? min.message() : max.message(), rangeMessage(min, max));
            if (isIntegralPrimitive(type)) {
                checks.add(Check.rangePrimitive(name, message, asLong(getter), lo, hi));
            } else if (Number.class.isAssignableFrom(type) && ref != null) {
                checks.add(Check.rangeBoxed(name, message, ref, lo, hi));
            }
        }
        Email email = field.getAnnotation(Email.class);
        if (email != null && ref != null)
            checks.add(Check.reference(Check.EMAIL, name, said(email.message(), "must be a well-formed email address"), ref));
        Pattern pattern = field.getAnnotation(Pattern.class);
        if (pattern != null && ref != null) {
            // ponytail: the one allocating check — Pattern.matcher() per call. The regex itself is
            // compiled once here; swap for a structural check if a hot route ever needs it.
            checks.add(Check.pattern(name, said(pattern.message(), "must match " + pattern.regexp()), ref,
                    java.util.regex.Pattern.compile(pattern.regexp())));
        }
    }
    private static boolean isIntegralPrimitive(Class<?> type) {
        return type == int.class || type == long.class || type == short.class || type == byte.class;
    }
    private static MethodHandle asReference(MethodHandle getter) {
        return getter.asType(MethodType.methodType(Object.class, Object.class));
    }
    private static MethodHandle asLong(MethodHandle getter) {
        return getter.asType(MethodType.methodType(long.class, Object.class));
    }
    /**
     * What a failure says: the constraint's own {@code message} when it sets one, and otherwise a
     * plain description of the rule. Jakarta's defaults are bundle keys in braces, and a key is
     * not something to put in front of whoever sent the request.
     */
    private static String said(String message, String otherwise) {
        return message == null || message.isBlank() || message.startsWith("{") ? otherwise : message;
    }
    private static String sizeMessage(Size size) {
        if (size.min() == 0) return "size must be at most " + size.max();
        if (size.max() == Integer.MAX_VALUE) return "size must be at least " + size.min();
        return "size must be between " + size.min() + " and " + size.max();
    }
    private static String rangeMessage(Min min, Max max) {
        if (min == null) return "must be at most " + max.value();
        if (max == null) return "must be at least " + min.value();
        return "must be between " + min.value() + " and " + max.value();
    }
 }
@@ -0,0 +1,128 @@
 package dev.relism.flash.ext.jackson;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Pattern;
 import jakarta.validation.constraints.Size;
 import org.junit.jupiter.api.Test;
 import java.util.List;
 import static org.junit.jupiter.api.Assertions.*;
 class ValidatorTest {
    record CreateUser(
            @NotBlank @Size(max = 8) String name,
            @Email                   String email,
            @Min(18) @Max(120)       int    age,
            @NotNull                 String role) {}
    record Boxed(@Min(1) Integer count) {}
    record Sized(@NotEmpty List<String> tags, @Size(min = 2, max = 4) String code) {}
    record Patterned(@Pattern(regexp = "[a-z]+") String slug) {}
    record Plain(String anything) {}
    private static ValidationException failureOf(Object value) {
        return assertThrows(ValidationException.class, () -> Validator.compile(value.getClass()).verify(value));
    }
    @Test
    void aValidValuePasses() {
        assertDoesNotThrow(() ->
                Validator.compile(CreateUser.class).verify(new CreateUser("alice", "a@b.com", 30, "admin")));
    }
    @Test
    void reportsEveryViolationNotJustTheFirst() {
        ValidationException failure = failureOf(new CreateUser("  ", "nope", 5, null));
        assertEquals(List.of("name", "email", "age", "role"),
                failure.violations().stream().map(ValidationException.Violation::field).toList());
    }
    @Test
    void violationsCarryFieldAndMessage() {
        ValidationException failure = failureOf(new CreateUser("alice", "a@b.com", 5, "admin"));
        assertEquals(1, failure.violations().size());
        assertEquals("age", failure.violations().get(0).field());
        assertEquals("must be between 18 and 120", failure.violations().get(0).message());
        assertEquals(422, failure.status());
        assertEquals("age must be between 18 and 120", failure.getMessage());
    }
    @Test
    void sizeCountsCharactersWithoutCopying() {
        assertEquals("name", failureOf(new CreateUser("far-too-long", "a@b.com", 30, "x"))
                .violations().get(0).field());
    }
    @Test
    void onlyNotNullRejectsNull() {
        // @Email, @Size and @Min all accept null per Jakarta semantics; @NotNull is the one that does not.
        ValidationException failure = failureOf(new CreateUser("alice", null, 30, null));
        assertEquals(List.of("role"),
                failure.violations().stream().map(ValidationException.Violation::field).toList());
    }
    @Test
    void boxedNumbersUseTheReferencePathAndTolerateNull() {
        assertDoesNotThrow(() -> Validator.compile(Boxed.class).verify(new Boxed(null)));
        assertEquals("count", failureOf(new Boxed(0)).violations().get(0).field());
    }
    @Test
    void sizeAppliesToCollectionsAndStrings() {
        assertDoesNotThrow(() -> Validator.compile(Sized.class).verify(new Sized(List.of("a"), "abc")));
        ValidationException failure = failureOf(new Sized(List.of(), "x"));
        assertEquals(List.of("tags", "code"),
                failure.violations().stream().map(ValidationException.Violation::field).toList());
    }
    @Test
    void patternIsAnchoredLikeJakarta() {
        assertDoesNotThrow(() -> Validator.compile(Patterned.class).verify(new Patterned("abc")));
        assertEquals("slug", failureOf(new Patterned("Abc1")).violations().get(0).field());
    }
    @Test
    void emailAcceptsPlausibleAddressesAndRejectsTypos() {
        assertDoesNotThrow(() ->
                Validator.compile(CreateUser.class).verify(new CreateUser("a", "first.last@sub.example.co", 20, "x")));
        for (String bad : List.of("no-at", "@leading.com", "trailing@", "two@@at.com", "no dots@x", "a@b")) {
            assertThrows(ValidationException.class,
                    () -> Validator.compile(CreateUser.class).verify(new CreateUser("a", bad, 20, "x")),
                    bad);
        }
    }
    @Test
    void aTypeWithNoConstraintsCompilesToANoOp() {
        Validator validator = Validator.compile(Plain.class);
        assertTrue(validator.isEmpty());
        assertDoesNotThrow(() -> validator.verify(new Plain(null)));
    }
    record Keyed(@jakarta.validation.constraints.Pattern(regexp = "[a-z.]+",
            message = "uses lowercase letters and dots") String key) {}
    @org.junit.jupiter.api.Test
    void a_constraint_says_what_it_wants_in_its_own_words() {
        ValidationException refused = org.junit.jupiter.api.Assertions.assertThrows(
                ValidationException.class, () -> Validator.check(new Keyed("Not A Key")));
        org.junit.jupiter.api.Assertions.assertEquals("key uses lowercase letters and dots", refused.getMessage());
    }
 }
@@ -0,0 +1,60 @@
 # flash-ext-jackson-json
 JSON bodies and JSON responses.
 ## Install
 ```java
 JsonExtension json = new JsonExtension();
 FlashApp.create(8080)
    .install(json)
    .use(json.auto())
    .scan("com.acme.handlers")
    .startAndBlock();
 ```
 The default mapper discovers the modules on the classpath (Java Time among them) and writes dates
 as ISO strings; `new JsonExtension(mapper)` takes one of your own. `auto()` serializes whatever a
 handler returns, leaving alone what is already a response: `null`, a `Response`, a `byte[]` or a
 `CharSequence`.
 ## A handler with a body
 The body type is the handler's type argument, and that is the whole declaration — it is also what
 the OpenAPI document describes and what the constraints are read from:
 ```java
@POST("/users")
 public final class CreateUser extends JsonHandler<NewUser> {
    @Inject private UserService users;
    @Override protected Object handle(Request req, Response res, NewUser body) {
        return users.create(body);
    }
 }
 ```
 A malformed body never reaches it (400), nor does one that breaks a constraint (422).
 ## A handler that reads it itself
 ```java
 public final class Import extends RequestHandler {
    @Inject private Json json;
    @Override public Object handle(Request req, Response res) throws Exception {
        return archive.store(json.body(req, Manifest.class));
    }
 }
 ```
 `Json` is the [`Codec`](../flash-ext-jackson-core) for `application/json`: `body`, `write`,
 `writeView`, `mapper`.
 ## Notes
 - One mapper per application (or per scope), shared by every handler; `ObjectMapper` is
  thread-safe once configured.
 - Install `flash-ext-jackson-xml` beside this one when an application speaks both: a route picks
  its format by the handler it extends, not by negotiation.
@@ -0,0 +1,40 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-jackson-json</artifactId>
    <name>flash-ext-jackson-json</name>
    <description>JSON bodies and responses: the Json codec, JsonHandler and the marshalling middleware.</description>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-jackson-core</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-testing</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- The constraints a body declares are described by the published document too. -->
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-openapi</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
 </project>
@@ -0,0 +1,27 @@
 package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.ext.jackson.Codec;
 import dev.relism.flash.http.ContentType;
 /**
 * JSON in and out, checked against the body type's own constraints.
 *
 * <pre>{@code
 * public final class CreateItem extends RequestHandler {
 *     @Inject private Json json;
 *
 *     @Override public Object handle(Request req, Response res) throws Exception {
 *         return items.create(json.body(req, NewItem.class));
 *     }
 * }
 * }</pre>
 *
 * <p>A handler whose whole body is one type has nothing to write at all: see {@link JsonHandler}.
 */
 public final class Json extends Codec {
    public Json(ObjectMapper mapper) {
        super(mapper, ContentType.JSON);
    }
 }
@@ -0,0 +1,50 @@
 package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import dev.relism.flash.ext.jackson.Marshalling;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.extension.FlashRegistrar;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.routing.Middleware;
 /**
 * JSON for an application: the {@link Json} codec, the mapper behind it, and the middleware that
 * serializes whatever a handler returns.
 *
 * <pre>{@code
 * JsonExtension json = new JsonExtension();
 * app.install(json).use(json.auto());
 * }</pre>
 *
 * <p>The default mapper discovers the modules on the classpath (Java Time among them) and writes
 * dates as ISO strings. Hand it a mapper of your own to decide otherwise.
 */
 public class JsonExtension implements FlashExtension {
    private final ObjectMapper mapper;
    public JsonExtension() {
        this(JsonMapper.builder()
                .findAndAddModules()
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                .build());
    }
    public JsonExtension(ObjectMapper mapper) {
        this.mapper = mapper;
    }
    /** Serializes what a handler returns, unless it already returned a response, bytes or text. */
    public Middleware auto() {
        return Marshalling.of(mapper, ContentType.JSON);
    }
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        ctx.provide(Json.class, new Json(mapper));
        ctx.provide(ObjectMapper.class, mapper);
    }
 }
@@ -0,0 +1,35 @@
 package dev.relism.flash.ext.jackson.json;
 import dev.relism.flash.ext.jackson.Codec;
 import dev.relism.flash.ext.jackson.JacksonHandler;
 import dev.relism.flash.extension.Inject;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.routing.Consumes;
 /**
 * A handler that takes a JSON body of one type.
 *
 * <pre>{@code
 * @POST("/users")
 * public final class CreateUser extends JsonHandler<NewUser> {
 *     @Inject private UserService users;
 *
 *     @Override protected Object handle(Request req, Response res, NewUser body) {
 *         return users.create(body);
 *     }
 * }
 * }</pre>
 *
 * <p>The body is read off the request stream, verified against the constraints its type declares,
 * and handed over. A malformed body is a 400, a body that breaks a constraint is a 422, and
 * neither ever reaches the handler. The published OpenAPI document describes the same type.
 */
@Consumes(ContentType.JSON)
 public abstract class JsonHandler<B> extends JacksonHandler<B> {
    @Inject private Json json;
    @Override protected final Codec codec() {
        return json;
    }
 }
@@ -0,0 +1,67 @@
 package dev.relism.flash.ext.jackson.json;
 import dev.relism.flash.ext.jackson.json.JsonExtension;
 import dev.relism.flash.ext.openapi.APIResponse;
 import dev.relism.flash.ext.openapi.ApiOperation;
 import dev.relism.flash.ext.openapi.Content;
 import dev.relism.flash.ext.openapi.OpenApiExtension;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.RequestHandler;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.routing.GET;
 import dev.relism.flash.testing.FlashTest;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 /**
 * Constraints are declared once and read twice: the validator enforces them, the published schema
 * describes them. Nothing registers this bridge — flash-ext-openapi picks the annotations up on
 * its own when they are on the classpath.
 */
 class ConstraintsInTheDocumentTest {
    record Account(
            @NotBlank @Size(max = 40) String name,
            @Email                    String email,
            @Min(18) @Max(120)        int    age) {}
    @GET("/accounts")
    @ApiOperation(summary = "List accounts")
    @APIResponse(responseCode = "200", content = @Content(schema = Account.class))
    public static class ListAccounts extends RequestHandler {
        @Override public Object handle(Request request, Response response) {
            return new Account("alice", "a@b.com", 30);
        }
    }
    @RegisterExtension
    static FlashTest app = FlashTest.of(configured -> {
        configured.install(new JsonExtension());
                configured.install(new OpenApiExtension("/openapi", "Accounts", "1.0.0"));
        configured.scan("dev.relism.flash.ext.jackson.json");
    });
    @Test
    void constraintsAppearInTheGeneratedSchema() {
        app.get("/openapi.json")
                .expectStatus(200)
                .expectBodyContains("\"maxLength\":40")
                .expectBodyContains("\"format\":\"email\"")
                .expectBodyContains("\"minimum\":18")
                .expectBodyContains("\"maximum\":120");
    }
    @Test
    void notBlankMarksThePropertyRequiredAndNonEmpty() {
        app.get("/openapi.json")
                .expectStatus(200)
                .expectBodyContains("\"minLength\":1")
                .expectBodyContains("\"required\":[\"name\"]");
    }
 }
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.jackson;
+package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.extension.FlashContext;
@@ -16,26 +16,25 @@ import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertTrue;
-class JacksonExtensionTest {
+class JsonExtensionTest {
    @Test
    void configure_registers_json_mapper_and_middleware() {
        FlashContext ctx = new FlashContext();
        ObjectMapper mapper = new ObjectMapper();
-        JacksonExtension ext = new JacksonExtension(mapper);
+        JsonExtension ext = new JsonExtension(mapper);
        ext.configure(null, ctx);
        ctx.complete();
        assertNotNull(ctx.require(Json.class));
        assertNotNull(ctx.require(JacksonMiddleware.class));
        assertSame(mapper, ctx.require(ObjectMapper.class));
    }
    @Test
-    void autoJson_factory_delegates_to_middleware_policy() throws Exception {
+    void auto_marshals_what_a_handler_returns() throws Exception {
        ObjectMapper mapper = new ObjectMapper();
-        JacksonExtension ext = new JacksonExtension(mapper);
+        JsonExtension ext = new JsonExtension(mapper);
        RequestHandler next = new RequestHandler() {
            @Override
            public Object handle(Request request, Response response) {
@@ -43,7 +42,7 @@ class JacksonExtensionTest {
            }
        };
        RequestHandler wrapped = new RequestHandler() {
-            private final SimpleHandler.FunctionalHandler delegate = ext.autoJson().wrap(next);
+            private final SimpleHandler.FunctionalHandler delegate = ext.auto().wrap(next);
            @Override
            public Object handle(Request request, Response response) throws Exception {
@@ -0,0 +1,78 @@
 package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.http.HttpMethod;
 import dev.relism.flash.models.Http1HeaderMap;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.RequestLine;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.routing.routers.fastpathrouter.FastPathViews;
 import org.junit.jupiter.api.Test;
 import java.nio.charset.StandardCharsets;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 class JsonHandlerTest {
    public record NewUser(String name) {}
    static final class Create extends JsonHandler<NewUser> {
        @Override protected Object handle(Request request, Response response, NewUser body) {
            return body.name();
        }
    }
    @SuppressWarnings("rawtypes")
    static final class Untyped extends JsonHandler {
        @Override protected Object handle(Request request, Response response, Object body) {
            return null;
        }
    }
    @Test
    void theBodyArrivesParsedAsTheTypeTheHandlerDeclares() throws Exception {
        Create handler = new Create();
        handler.bind(context());
        Object answer = handler.handle(request("{\"name\":\"alice\"}"), new Response(200, ContentType.JSON));
        assertEquals("alice", answer);
    }
    @Test
    void aMalformedBodyIsTheUsualBadRequest() throws Exception {
        Create handler = new Create();
        handler.bind(context());
        dev.relism.flash.exceptions.HttpException refused = assertThrows(dev.relism.flash.exceptions.HttpException.class,
                () -> handler.handle(request("not json"), new Response(200, ContentType.JSON)));
        assertEquals(400, refused.status());
    }
    @Test
    void aHandlerThatNeverNamedItsBodyTypeIsRefusedAtBoot() {
        IllegalStateException refused = assertThrows(IllegalStateException.class, Untyped::new);
        assertTrue(refused.getMessage().contains("Handler<YourBody>"), refused.getMessage());
    }
    private static FlashContext context() {
        FlashContext ctx = new FlashContext();
        ctx.provide(Json.class, new Json(new ObjectMapper()));
        ctx.complete();
        return ctx;
    }
    private static Request request(String body) {
        return new Request(new RequestLine(HttpMethod.POST,
                new FastPathViews.StringByteView("/users"), null,
                new FastPathViews.StringByteView("HTTP/1.1"), new Http1HeaderMap()),
                body.getBytes(StandardCharsets.UTF_8));
    }
 }
@@ -1,11 +1,11 @@
-package dev.relism.flash.ext.jackson;
+package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.annotation.JsonView;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.http.HttpMethod;
-import dev.relism.flash.models.HeaderMap;
+import dev.relism.flash.models.Http1HeaderMap;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.RequestLine;
 import dev.relism.flash.models.Response;
@@ -37,16 +37,11 @@ class JsonTest {
    }
    @Test
-    void bodyFrom_parses_stream_and_maps_bad_payload_to_http_400() throws Exception {
+    void a_truncated_body_is_a_bad_request_too() throws Exception {
        Json json = new Json(new ObjectMapper());
-        Request ok = request("{\"id\":\"u2\",\"name\":\"bob\"}");
+        HttpException ex = assertThrows(HttpException.class, () -> json.body(request("["), UserDto.class));
        UserDto dto = json.bodyFrom(ok, UserDto.class);
        assertEquals("u2", dto.id);
        assertEquals("bob", dto.name);
        Request bad = request("[");
        HttpException ex = assertThrows(HttpException.class, () -> json.bodyFrom(bad, UserDto.class));
        assertEquals(400, ex.status());
    }
@@ -82,7 +77,7 @@ class JsonTest {
                new FastPathViews.StringByteView("/json"),
                null,
                new FastPathViews.StringByteView("HTTP/1.1"),
-                new HeaderMap()
+                new Http1HeaderMap()
        );
        return new Request(line, body);
    }
@@ -1,6 +1,8 @@
-package dev.relism.flash.ext.jackson;
+package dev.relism.flash.ext.jackson.json;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.ext.jackson.Marshalling;
 import dev.relism.flash.routing.Middleware;
 import dev.relism.flash.models.SimpleHandler;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Request;
@@ -16,13 +18,13 @@ import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
-class JacksonMiddlewareTest {
+class MarshallingTest {
    private static final Request REQ = null;
    @Test
-    void autoJson_marshalsPojo_toJsonBytes_and_setsJsonContentType() throws Exception {
+    void marshalling_marshalsPojo_toJsonBytes_and_setsJsonContentType() throws Exception {
-        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+        Middleware mw = Marshalling.of(new ObjectMapper(), ContentType.JSON);
        RequestHandler wrapped = wrap(mw, new UserDto("u1", "alice"));
        Response res = new Response(200, ContentType.TEXT_PLAIN);
@@ -34,8 +36,8 @@ class JacksonMiddlewareTest {
    }
    @Test
-    void autoJson_passThrough_for_response_string_charSequence_bytes_and_null() throws Exception {
+    void marshalling_passThrough_for_response_string_charSequence_bytes_and_null() throws Exception {
-        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+        Middleware mw = Marshalling.of(new ObjectMapper(), ContentType.JSON);
        Response payloadResponse = new Response(201, ContentType.TEXT_PLAIN).body("ok");
        RequestHandler wrappedResponse = wrap(mw, payloadResponse);
@@ -55,17 +57,17 @@ class JacksonMiddlewareTest {
    }
    @Test
-    void autoJson_wraps_serialization_errors_as_illegal_state() {
+    void marshalling_wraps_serialization_errors_as_illegal_state() {
-        JacksonMiddleware mw = new JacksonMiddleware(new ObjectMapper());
+        Middleware mw = Marshalling.of(new ObjectMapper(), ContentType.JSON);
        RequestHandler wrapped = wrap(mw, new CyclicDto());
        Response res = new Response(200, ContentType.TEXT_PLAIN);
        IllegalStateException ex = assertThrows(IllegalStateException.class, () -> wrapped.handle(REQ, res));
        assertEquals("application/json", new String(res.getContentType(), StandardCharsets.UTF_8));
-        assertTrue(ex.getMessage().startsWith("Failed to serialize handler result as JSON:"));
+        assertTrue(ex.getMessage().startsWith("Could not serialize"));
    }
-    private static RequestHandler wrap(JacksonMiddleware mw, Object fixedReturn) {
+    private static RequestHandler wrap(Middleware mw, Object fixedReturn) {
        RequestHandler next = new RequestHandler() {
            @Override
            public Object handle(Request request, Response response) {
@@ -73,7 +75,7 @@ class JacksonMiddlewareTest {
            }
        };
        return new RequestHandler() {
-            private final SimpleHandler.FunctionalHandler delegate = mw.autoJson().wrap(next);
+            private final SimpleHandler.FunctionalHandler delegate = mw.wrap(next);
            @Override
            public Object handle(Request request, Response response) throws Exception {
@@ -0,0 +1,67 @@
 package dev.relism.flash.ext.jackson.json;
 import dev.relism.flash.testing.FlashTest;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 /** The whole path: JSON in, constraints checked, status out — with no error handling wired up. */
 class ValidatedBodyTest {
    record CreateUser(@NotBlank @Size(max = 8) String name, @Email String email, @Min(18) int age) {}
    @RegisterExtension
    static FlashTest app = FlashTest.of(configured -> {
        configured.install(new JsonExtension());
        configured.ctx().onReady(() -> {
            Json json = configured.ctx().require(Json.class);
            configured.post("/users", (req, res) ->
                    res.status(201).body("created:" + json.body(req, CreateUser.class).name()));
        });
    });
    @Test
    void validBodyReachesTheHandler() {
        app.request().json("{\"name\":\"alice\",\"email\":\"a@b.com\",\"age\":30}").post("/users")
                .expectStatus(201)
                .expectBody("created:alice");
    }
    @Test
    void constraintViolationBecomes422WithEveryFailureListed() {
        app.request().json("{\"name\":\"\",\"email\":\"nope\",\"age\":5}").post("/users")
                .expectStatus(422)
                .expectHeader("Content-Type", "application/json")
                .expectBodyContains("name must not be blank")
                .expectBodyContains("email must be a well-formed email address")
                .expectBodyContains("age must be at least 18");
    }
    @Test
    void malformedJsonBecomes400NotAValidationFailure() {
        app.request().json("not json").post("/users")
                .expectStatus(400)
                .expectBodyContains("Invalid request body");
    }
    /** Regression guard: HttpException used to reach the catch-all and come back as 500. */
    @Test
    void statusCarriedByTheExceptionSurvivesToTheWire() {
        assertEquals(422, app.request().json("{\"name\":\"x\",\"email\":\"a@b.com\",\"age\":1}")
                .post("/users").status());
    }
    @Test
    void errorBodyIsValidJsonEvenWhenTheMessageContainsQuotes() {
        app.request().json("{\"name\":\"waaaaaaaaaay-too-long\",\"email\":\"a@b.com\",\"age\":30}").post("/users")
                .expectStatus(422)
                .expectBodyContains("\"status\":422")
                .expectBodyContains("size must be at most 8");
    }
 }
@@ -0,0 +1,30 @@
 # flash-ext-jackson-xml
 XML bodies and XML responses, over the same types as every other Jackson format.
 ```java
 XmlExtension xml = new XmlExtension();
 app.install(xml).use(xml.auto());
 ```
 ```java
@POST("/orders")
 public final class PlaceOrder extends XmlHandler<Order> {
    @Inject private OrderService orders;
    @Override protected Object handle(Request req, Response res, Order body) {
        return orders.place(body);
    }
 }
 ```
 Everything [`flash-ext-jackson-json`](../flash-ext-jackson-json) does, in XML: the body is read off
 the request stream, verified against the constraints its type declares, and handed over. A type
 annotated for JSON works here as is — `Order` can be a JSON body on one route and an XML body on
 another.
 What is specific to XML is Jackson's own: `@JacksonXmlRootElement` for the root name,
 `@JacksonXmlProperty(isAttribute = true)` for an attribute rather than an element, and
 `@JacksonXmlElementWrapper` for how a list is wrapped. This module adds no annotations of its own.
 Brings `jackson-dataformat-xml`, and with it Woodstox.
@@ -0,0 +1,43 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-jackson-xml</artifactId>
    <name>flash-ext-jackson-xml</name>
    <description>XML bodies and responses, over the same types and the same constraints as every other Jackson format.</description>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-jackson-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.dataformat</groupId>
            <artifactId>jackson-dataformat-xml</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.validation</groupId>
            <artifactId>jakarta.validation-api</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-testing</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
 </project>
@@ -0,0 +1,20 @@
 package dev.relism.flash.ext.jackson.xml;
 import com.fasterxml.jackson.dataformat.xml.XmlMapper;
 import dev.relism.flash.ext.jackson.Codec;
 import dev.relism.flash.http.ContentType;
 /**
 * XML in and out, checked against the body type's own constraints.
 *
 * <p>The same databind model as every other Jackson format: a type is annotated once and can be
 * read as XML here and as JSON elsewhere in the same application. XML's own concerns — a root
 * element name, an attribute rather than an element, how a list is wrapped — are Jackson's
 * {@code @JacksonXml*} annotations on the type.
 */
 public final class Xml extends Codec {
    public Xml(XmlMapper mapper) {
        super(mapper, ContentType.XML);
    }
 }
@@ -0,0 +1,44 @@
 package dev.relism.flash.ext.jackson.xml;
 import com.fasterxml.jackson.dataformat.xml.XmlMapper;
 import dev.relism.flash.ext.jackson.Marshalling;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.extension.FlashRegistrar;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.routing.Middleware;
 /**
 * XML for an application: the {@link Xml} codec and the middleware that serializes what a handler
 * returns.
 *
 * <pre>{@code
 * XmlExtension xml = new XmlExtension();
 * app.install(xml).use(xml.auto());
 * }</pre>
 *
 * <p>Install it beside {@code JsonExtension} when an application speaks both: each provides its
 * own codec, and a route picks one by the handler it extends.
 */
 public class XmlExtension implements FlashExtension {
    private final XmlMapper mapper;
    public XmlExtension() {
        this(XmlMapper.builder().findAndAddModules().build());
    }
    public XmlExtension(XmlMapper mapper) {
        this.mapper = mapper;
    }
    /** Serializes what a handler returns, unless it already returned a response, bytes or text. */
    public Middleware auto() {
        return Marshalling.of(mapper, ContentType.XML);
    }
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        ctx.provide(Xml.class, new Xml(mapper));
    }
 }
@@ -0,0 +1,24 @@
 package dev.relism.flash.ext.jackson.xml;
 import dev.relism.flash.ext.jackson.Codec;
 import dev.relism.flash.ext.jackson.JacksonHandler;
 import dev.relism.flash.extension.Inject;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.routing.Consumes;
 /**
 * A handler that takes an XML body of one type.
 *
 * <p>Everything {@code JsonHandler} does, in XML: the body is read off the request stream,
 * verified against its type's constraints, and handed over. Both can live in the same
 * application, on different routes, over the same types.
 */
@Consumes(ContentType.XML)
 public abstract class XmlHandler<B> extends JacksonHandler<B> {
    @Inject private Xml xml;
    @Override protected final Codec codec() {
        return xml;
    }
 }
@@ -0,0 +1,81 @@
 package dev.relism.flash.ext.jackson.xml;
 import com.fasterxml.jackson.dataformat.xml.XmlMapper;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.http.HttpMethod;
 import dev.relism.flash.models.Http1HeaderMap;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.RequestLine;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.routing.routers.fastpathrouter.FastPathViews;
 import jakarta.validation.constraints.NotBlank;
 import org.junit.jupiter.api.Test;
 import java.nio.charset.StandardCharsets;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 /** The same handler shape as JSON, over the same types and the same constraints. */
 class XmlHandlerTest {
    public record Order(@NotBlank String reference) {}
    static final class Place extends XmlHandler<Order> {
        @Override protected Object handle(Request request, Response response, Order body) {
            return body.reference();
        }
    }
    @Test
    void theBodyArrivesParsedAsTheTypeTheHandlerDeclares() throws Exception {
        Place handler = new Place();
        handler.bind(context());
        Object answer = handler.handle(request("<Order><reference>A-1</reference></Order>"), response());
        assertEquals("A-1", answer);
    }
    @Test
    void aBodyThatBreaksAConstraintNeverReachesTheHandler() throws Exception {
        Place handler = new Place();
        handler.bind(context());
        HttpException refused = assertThrows(HttpException.class,
                () -> handler.handle(request("<Order><reference></reference></Order>"), response()));
        assertEquals(422, refused.status());
    }
    @Test
    void aMalformedBodyIsABadRequest() throws Exception {
        Place handler = new Place();
        handler.bind(context());
        HttpException refused = assertThrows(HttpException.class,
                () -> handler.handle(request("<Order><reference>"), response()));
        assertEquals(400, refused.status());
    }
    private static FlashContext context() {
        FlashContext ctx = new FlashContext();
        ctx.provide(Xml.class, new Xml(XmlMapper.builder().build()));
        ctx.complete();
        return ctx;
    }
    private static Response response() {
        return new Response(200, ContentType.XML);
    }
    private static Request request(String body) {
        return new Request(new RequestLine(HttpMethod.POST,
                new FastPathViews.StringByteView("/orders"), null,
                new FastPathViews.StringByteView("HTTP/1.1"), new Http1HeaderMap()),
                body.getBytes(StandardCharsets.UTF_8));
    }
 }
@@ -1,116 +0,0 @@
 # flash-ext-jackson
 Jackson JSON integration for Flash with an opinionated auto-marshal middleware.
 ## What it provides
 | Component | Description |
 |---|---|
 | `JacksonExtension` | Registers JSON services into `FlashContext` |
 | `Json` | JSON read/write helper (`body`, `bodyFrom`, `write`, `writeView`) |
 | `ObjectMapper` | Raw mapper escape hatch for advanced usage |
 | `JacksonMiddleware` | `autoJson()` middleware for automatic outbound JSON marshalling |
 Default mapper behavior (`new JacksonExtension()`):
 - auto-discovers Jackson modules on classpath (`findAndAddModules()`)
 - includes Java Time support (`jackson-datatype-jsr310`)
 - writes date/time values as ISO-8601 strings (not numeric timestamps)
 ## Recommended default
 Install the extension, then apply `autoJson()` once at app or scope level.
 ```java
 JacksonExtension jackson = new JacksonExtension();
 FlashApp app = FlashApp.create(8080)
    .install(jackson)
    .use(jackson.autoJson());
 app.startAndBlock();
 ```
 Behavior of `autoJson()`:
 - pass-through: `null`, `Response`, `byte[]`, `String`, `CharSequence`
 - any other return value: serialize to JSON `byte[]`
 - sets `Content-Type: application/json` for marshalled responses
 - serialization failures throw `IllegalStateException`
 This keeps handlers concise while preserving Flash's direct byte write path.
 ## Installation
 ```xml
 <dependency>
    <groupId>dev.relism</groupId>
    <artifactId>flash-ext-jackson</artifactId>
    <version>1.1-indev2</version>
 </dependency>
 ```
 ## Json helper API
 Use `Json` when you want explicit, local control in a handler.
 ```java
@POST("/users")
 public final class CreateUser extends RequestHandler {
    private Json json;
    @Override
    protected void onInit() {
        json = require(Json.class);
    }
    @Override
    public Object handle(Request req, Response res) throws Exception {
        CreateUserBody body = json.body(req, CreateUserBody.class);
        UserDto created = service.create(body);
        res.status(201);
        return json.write(res, created);
    }
 }
 ```
 Methods:
 - `body(req, Type.class)` -> parse from `req.body().bytes()`
 - `bodyFrom(req, Type.class)` -> parse from `req.body().stream()`
 - `write(res, obj)` -> writes JSON string and sets JSON content type
 - `writeView(res, obj, View.class)` -> JSON with Jackson `@JsonView`
 - `mapper()` -> raw `ObjectMapper`
 ## Custom mapper
 ```java
 ObjectMapper mapper = JsonMapper.builder()
    .addModule(new JavaTimeModule())
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
    .build();
 FlashApp.create(8080)
    .install(new JacksonExtension(mapper));
 ```
 ## Scope usage
 `autoJson()` works the same at scope level:
 ```java
 JacksonExtension jackson = new JacksonExtension();
 app.mount("/api", api -> {
    api.use(jackson.autoJson());
    api.get("/health", (req, res) -> Map.of("ok", true));
 });
 ```
 If you need to pull it from context, `JacksonMiddleware` is also provided as a service
 after the app boots (same lifecycle model as other extension-provided services).
 ## Notes
 - Install order is irrelevant (Flash two-phase extension lifecycle).
 - `autoJson()` and OpenAPI are intentionally decoupled.
@@ -1,82 +0,0 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
        <version>2.1.0-SNAPSHOT</version>
    </parent>
    <artifactId>flash-ext-jackson</artifactId>
    <properties>
        <jacoco.version>0.8.12</jacoco.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>${jacoco.version}</version>
                <executions>
                    <execution>
                        <id>jacoco-prepare-agent</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>jacoco-report-and-check</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>report</goal>
                            <goal>check</goal>
                        </goals>
                        <configuration>
                            <rules>
                                <rule>
                                    <element>BUNDLE</element>
                                    <limits>
                                        <limit>
                                            <counter>LINE</counter>
                                            <value>COVEREDRATIO</value>
                                            <minimum>0.80</minimum>
                                        </limit>
                                    </limits>
                                </rule>
                            </rules>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
 </project>
@@ -1,94 +0,0 @@
 package dev.relism.flash.ext.jackson;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.databind.json.JsonMapper;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashRegistrar;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.routing.Middleware;
 /**
 * Registers JSON support into the Flash extension layer.
 *
 * <p>Exposes a {@link Json} utility instance in the {@link FlashContext} under
 * {@code Json.class}. Any handler or extension can retrieve it via {@code ctx.require(Json.class)}
 * inside {@code onInit()} (class-based) or from a {@link FlashContext#onReady(Runnable)}
 * callback (extensions).
 *
 * <p>The raw {@link ObjectMapper} is also registered under {@code ObjectMapper.class}
 * for extensions that need direct mapper access (e.g. OpenAPI schema generation).
 *
 * <p>{@link JacksonMiddleware} is provided under {@code JacksonMiddleware.class} and
 * exposes opinionated JSON auto-marshalling middleware via {@link JacksonMiddleware#autoJson()}.
 *
 * <h3>Usage — composition (preferred)</h3>
 * <pre>{@code
 * public class MyHandler extends RequestHandler {
 *     private Json json;
 *
 *     @Override protected void onInit() {
 *         json = require(Json.class);
 *     }
 *
 *     public Object handle(Request req, Response res) throws Exception {
 *         MyDto dto = json.body(req, MyDto.class);
 *         return json.write(res, 201, dto);
 *     }
 * }
 * }</pre>
 *
 * <h3>Custom mapper</h3>
 * <pre>{@code
 * ObjectMapper mapper = JsonMapper.builder()
 *         .addModule(new JavaTimeModule())
 *         .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
 *         .build();
 *
 * FlashApp.create(8080)
 *         .install(new JacksonExtension(mapper));
 * }</pre>
 */
 public class JacksonExtension implements FlashExtension {
    private final ObjectMapper mapper;
    private final JacksonMiddleware middleware;
    /**
     * Installs with an opinionated default {@link JsonMapper}:
     * auto-discovers modules on classpath (e.g. Java Time) and writes dates as ISO strings.
     */
    public JacksonExtension() {
        this(JsonMapper.builder()
                .findAndAddModules()
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                .build());
    }
    /** Installs with a fully configured custom {@link ObjectMapper}. */
    public JacksonExtension(ObjectMapper mapper) {
        this.mapper = mapper;
        this.middleware = new JacksonMiddleware(mapper);
    }
    /**
     * Opinionated outbound JSON middleware factory.
     *
     * <p>Use for app/scope-level registration:
     * <pre>{@code
     * JacksonExtension jackson = new JacksonExtension();
     * app.install(jackson).use(jackson.autoJson());
     * }</pre>
     */
    public Middleware autoJson() {
        return middleware.autoJson();
    }
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        Json json = new Json(mapper);
        ctx.provide(Json.class,               json);
        ctx.provide(ObjectMapper.class,       mapper);
        ctx.provide(JacksonMiddleware.class,  middleware);
    }
 }
@@ -1,62 +0,0 @@
 package dev.relism.flash.ext.jackson;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.routing.Middleware;
 /**
 * Outbound JSON marshalling middleware for class-based and lambda routes.
 *
 * <p>{@link #autoJson()} marshals any non-body-native return value to JSON bytes,
 * writes {@code Content-Type: application/json}, and returns {@code byte[]} so
 * the Flash write path stays direct.
 *
 * <p>Pass-through return types:
 * <ul>
 *   <li>{@code null}</li>
 *   <li>{@link Response}</li>
 *   <li>{@code byte[]}</li>
 *   <li>{@link String}</li>
 *   <li>{@link CharSequence}</li>
 * </ul>
 */
 public final class JacksonMiddleware {
    private final ObjectMapper mapper;
    JacksonMiddleware(ObjectMapper mapper) {
        this.mapper = mapper;
    }
    /**
     * Automatic JSON marshalling policy.
     *
     * <p>For non-pass-through return values, serializes with Jackson directly to
     * {@code byte[]} and sets response content type to JSON.
     *
     * @throws IllegalStateException when serialization fails
     */
    public Middleware autoJson() {
        return next -> (req, res) -> {
            Object out = next.handle(req, res);
            if (isPassThrough(out)) return out;
            res.type(ContentType.JSON);
            try {
                return mapper.writeValueAsBytes(out);
            } catch (JsonProcessingException e) {
                throw new IllegalStateException(
                        "Failed to serialize handler result as JSON: " + out.getClass().getName(), e);
            }
        };
    }
    private static boolean isPassThrough(Object out) {
        return out == null
                || out instanceof Response
                || out instanceof byte[]
                || out instanceof CharSequence;
    }
 }
@@ -1,117 +0,0 @@
 package dev.relism.flash.ext.jackson;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.Response;
 /**
 * Thread-safe JSON toolbox. Single point of access for all JSON I/O operations
 * within a Flash application.
 *
 * <p>Retrieve once at boot time via {@code require(Json.class)} inside
 * {@code onInit()}, cache in a private field, and call on the hot path
 * with zero lookup or allocation overhead:
 *
 * <pre>{@code
 * @Route(method = HttpMethod.POST, path = "/api/items")
 * public class CreateItemHandler extends RequestHandler {
 *
 *     private Json json;
 *
 *     @Override
 *     protected void onInit() {
 *         json = require(Json.class);
 *     }
 *
 *     public Object handle(Request req, Response res) throws Exception {
 *         CreateItemRequest body = json.body(req, CreateItemRequest.class);
 *         return json.write(res, itemService.create(body));
 *     }
 * }
 * }</pre>
 *
 * <p>The underlying {@link ObjectMapper} is shared across all handlers in the same
 * scope (one instance per app / per child scope). Jackson's {@code ObjectMapper}
 * is fully thread-safe after configuration — no synchronization is needed.
 *
 * <p>Install via {@link JacksonExtension} before calling {@code scan()} or
 * {@code register()}.
 */
 public final class Json {
    private final ObjectMapper mapper;
    /** Package-private — constructed exclusively by {@link JacksonExtension}. */
    Json(ObjectMapper mapper) {
        this.mapper = mapper;
    }
    // ── Input ─────────────────────────────────────────────────────────────────
    /**
     * Deserializes the full request body into an instance of {@code type}.
     *
     * <p>Reads {@code req.body().bytes()} in one shot. For streaming bodies
     * use {@link #bodyFrom(Request, Class)} instead.
     *
     * @throws HttpException 400 if the body cannot be parsed as {@code type}
     */
    public <T> T body(Request req, Class<T> type) throws Exception {
        try {
            return mapper.readValue(req.body().bytes(), type);
        } catch (JsonProcessingException e) {
            throw HttpException.badRequest("Invalid request body: " + e.getOriginalMessage());
        }
    }
    /**
     * Deserializes the request body via the raw {@link java.io.InputStream},
     * avoiding the intermediate {@code byte[]} allocation. Prefer this for
     * large bodies or when allocation budget is tight.
     *
     * @throws HttpException 400 on parse failure
     */
    public <T> T bodyFrom(Request req, Class<T> type) throws Exception {
        try {
            return mapper.readValue(req.body().stream(), type);
        } catch (JsonProcessingException e) {
            throw HttpException.badRequest("Invalid request body: " + e.getOriginalMessage());
        }
    }
    // ── Output ────────────────────────────────────────────────────────────────
    /**
     * Serializes {@code obj} to a JSON string and sets
     * {@code Content-Type: application/json} on the response.
     *
     * <p>The returned string is used as the response body by the Flash runtime.
     */
    public String write(Response res, Object obj) throws Exception {
        res.type(ContentType.JSON);
        return mapper.writeValueAsString(obj);
    }
    /**
     * Like {@link #write} but applies a Jackson {@code @JsonView} filter,
     * restricting serialization to fields visible under {@code view}.
     */
    public String writeView(Response res, Object obj, Class<?> view) throws Exception {
        res.type(ContentType.JSON);
        return mapper.writerWithView(view).writeValueAsString(obj);
    }
    // ── Escape hatch ──────────────────────────────────────────────────────────
    /**
     * Returns the underlying {@link ObjectMapper} for advanced operations
     * (custom serialization, schema generation, etc.) not covered by the
     * methods above.
     */
    public ObjectMapper mapper() {
        return mapper;
    }
 }
@@ -36,7 +36,7 @@ FlashApp.create(8080)
 // With custom resolvers
 LimiterConfig conf = new LimiterConfig()
    .registerResolver("auth_user", req ->
-        ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous");
+        SecurityIdentity.current() != null ? SecurityIdentity.current().principal().name() : "anonymous");
 FlashApp.create(8080)
    .install(new LimiterExtension(conf))
@@ -35,11 +35,11 @@ conf.registerResolver("ip", req -> {
 LimiterConfig conf = new LimiterConfig();
 ```
-### By authenticated user (OIDC / ClaimsHolder)
+### By authenticated user
 ```java
 conf.registerResolver("auth_user", req ->
-    ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous");
+    SecurityIdentity.current() != null ? SecurityIdentity.current().principal().name() : "anonymous");
 ```
 Requests from unauthenticated users share the `"anonymous"` bucket. If you want
@@ -88,7 +88,7 @@ returns the same key for the same user regardless of endpoint; the limit is set
 ```java
 conf.registerResolver("auth_user", req ->
-    ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anon");
+    SecurityIdentity.current() != null ? SecurityIdentity.current().principal().name() : "anon");
 ```
 ```java
@@ -11,7 +11,7 @@ import dev.relism.flash.models.Request;
 *
 * <pre>{@code
 * conf.registerResolver("ip",       req -> req.header("X-Forwarded-For"));
- * conf.registerResolver("auth_user", req -> ClaimsHolder.user().sub());
+ * conf.registerResolver("auth_user", req -> SecurityIdentity.current().principal().name());
 * }</pre>
 */
@FunctionalInterface
@@ -21,8 +21,8 @@ import java.util.Map;
 * <pre>{@code
 * LimiterConfig conf = new LimiterConfig()
 *     .registerResolver("auth_user", req -> {
- *         // custom logic — e.g. extract sub from ClaimsHolder
+ *         // custom logic — e.g. key by the authenticated caller
- *         return ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous";
+ *         return SecurityIdentity.current() != null ? SecurityIdentity.current().principal().name() : "anonymous";
 *     });
 *
 * app.install(new LimiterExtension(conf));
@@ -43,7 +43,7 @@ import java.util.Map;
 * <h3>Lambda routes (via Guard)</h3>
 * <pre>{@code
 * app.install(new LimiterExtension(
- *     new LimiterConfig().registerResolver("auth_user", req -> ClaimsHolder.user().sub())));
+ *     new LimiterConfig().registerResolver("auth_user", req -> SecurityIdentity.current().principal().name())));
 *
 * // inside a FlashContext.onReady(...) callback:
 * Guard guard = ctx.require(Guard.class);
@@ -3,7 +3,7 @@
 `flash-ext-mcp` turns a Flash5 app into an [MCP](https://modelcontextprotocol.io) (Model Context
 Protocol) server: JSON-RPC 2.0 over the Streamable HTTP transport, tools/resources/prompts
 declared as plain classes and discovered at boot, optional OAuth2 protection built on
-`flash-ext-oidc`.
+`flash-ext-security-core`.
 ## Quick Start
@@ -44,7 +44,7 @@ public class GetWeatherTool extends McpTool {
  `tools-resources-prompts.md`.
 - **Transport**: Streamable HTTP, `POST`-only, stateless in this revision — see `transport.md`
  for exactly what that means and why.
- **Security**: optional, policy-driven OAuth2 via `flash-ext-oidc` — see `security.md`.
+- **Security**: authenticated by `flash-ext-security-core`, an OAuth2 protected resource when OIDC is installed — see `security.md`.
 - **JSON**: this extension owns its JSON handling independently of `flash-ext-jackson` — see
  `jackson-interop.md` for why, and how a future opt-in reuse could work.
@@ -53,6 +53,4 @@ public class GetWeatherTool extends McpTool {
 - [`tools-resources-prompts.md`](tools-resources-prompts.md) — defining tools, resources, prompts
 - [`transport.md`](transport.md) — Streamable HTTP scope, session/SSE limitations, Origin validation
 - [`security.md`](security.md) — `McpSecurity` policy, OAuth2 resolution, RFC 9728 / RFC 8707
 - [`keycloak.md`](keycloak.md) — Keycloak-specific setup cookbook: Dynamic Client Registration,
  the RFC 8707 audience mapper gotcha, and how to verify/debug it
 - [`jackson-interop.md`](jackson-interop.md) — why this extension does not depend on `flash-ext-jackson`
@@ -24,7 +24,7 @@ see `tools-resources-prompts.md` — and the fixed `TextContent`/`TextResourceCo
 as a `JsonNode` tree, not as a databound class, for the same reason — a JSON-RPC tool call's
 arguments aren't a DTO with getters/setters, they're a dynamic, per-tool-defined bag of values.
-This mirrors how `flash-ext-oidc` already handles its own internal JSON needs (`json-smart` for
+This mirrors how `flash-ext-security-oidc` handles its own JSON needs (Nimbus's parser for
 token-endpoint responses) independently of `flash-ext-jackson` — extensions with protocol-level
 JSON needs that are shaped by a spec, not by user code, own that JSON handling themselves rather
 than routing it through the app's general-purpose JSON extension.
@@ -44,8 +44,7 @@ Nothing here rules out a later, additive convenience layer: `McpExtension.routes
 that shared mapper as the backing for an escape hatch such as `ToolArguments.as(Class<T>)` or
 for a tool that wants to `ToolResponse.success(someRecord)` and have it serialized with the
 app's own conventions — falling back to a locally-constructed default `ObjectMapper` when
-`flash-ext-jackson` isn't installed, the same "prefer shared, degrade to sane default" shape
+`flash-ext-jackson` isn't installed. That would be purely additive on top of the
 already used for `McpSecurity.AUTO`. That would be purely additive on top of the
 `JsonGenerator`-based envelope/content writing described above, not a replacement for it — the
 fixed-shape protocol plumbing has no reason to ever go through databinding, regardless of what
 convenience layer gets added around it.
@@ -1,107 +0,0 @@
 # Keycloak cookbook
 `security.md` covers the OAuth2 mechanics `McpOidcIntegration` implements against any
 `flash-ext-oidc`-compatible provider. This is the Keycloak-specific setup: the exact Admin
 Console configuration for a working MCP OAuth2 flow with open Dynamic Client Registration
 (DCR) — no pre-registered clients, any MCP client self-registers on first connect.
 ## 1. Allow Dynamic Client Registration
 MCP clients (Claude Desktop, Claude.ai, MCP Inspector, others) don't share one static OAuth
 client — each has its own `redirect_uri` and none know your realm in advance. They self-register
 on first connect via `POST {issuer}/clients-registrations/openid-connect` (the
 `registration_endpoint` from the AS metadata document, reached via the RFC 9728 Protected
 Resource Metadata document `McpExtension` publishes).
 **Clients → Client registration**: remove the **Trusted Hosts** policy — it rejects anonymous
 registration from hosts not on an explicit allowlist (`403` / `"Host not trusted"`), which
 doesn't scale to arbitrary future agents. This does not weaken end-user authentication — DCR
 only grants an app a `client_id`; every user still authenticates against Keycloak's real login
 screen regardless of which client asked. Lighter hygiene policies (**Max Clients Limit**,
 **Consent Required**) can stay, they don't interfere.
 ## 2. RFC 8707 audience: mapper on `basic`, not a custom scope
 `McpOidcIntegration` rejects (403) any token whose `aud` doesn't include the MCP endpoint's
 canonical URL. Keycloak doesn't add this by default. The obvious fix — a custom client scope
 with an Audience mapper, marked Default, added to Allowed Client Scopes — **does not work**:
 clients created via the `openid-connect` DCR endpoint only ever get scopes they explicitly
 request, and most MCP clients (including MCP Inspector) don't request anything beyond what a
 server tells them to via `scopes_supported` (step 3). Default-scope auto-attachment, which is
 how a normal manually-created client would pick up a custom Default scope, doesn't apply to
 DCR-created clients at all.
 `basic` is the one built-in scope Keycloak attaches to every client unconditionally, regardless
 of what it registered with. Put the audience mapper there:
 1. **Client scopes → `basic`** → **Mappers** → **Add mapper** → **By configuration** →
   **Audience**.
 2. **Included Custom Audience** = the exact value your server expects — check
   `GET {parent-of-rootPath}/.well-known/oauth-protected-resource{rootPath}` on the running
   server for the `resource` field it publishes (auto-derived from the request's
   forwarded/`Host` headers — see `security.md`). Leave **Included Client Audience** empty (that
   targets another Keycloak client, not a resource URL).
 3. **Add to access token** = ON.
 4. **Save.**
 This is unconditional and works regardless of client cooperation — keep it even after step 3
 below gets other claims flowing normally, since audience binding is a hard spec requirement
 that shouldn't depend on a client bothering to request the right scope.
 ## 3. Other claims (username, email...): `scopes_supported` + Allowed Client Scopes
 `OidcUser.username()`/`.email()`/`.name()` read `preferred_username`/`email`/`name` — normally
 from the `profile`/`email` client scopes, which DCR clients don't get either, same root cause.
 Unlike audience, this **is** fixable the "normal" way, because it doesn't need to survive a
 completely uncooperative client:
 `McpConfig.scopesSupported("openid", "profile", "email")` publishes those scopes in the PRM
 document. MCP clients that read it (confirmed for MCP Inspector) echo them back in their DCR
 registration request — `"scope": "openid profile email offline_access"` (`offline_access` is
 Inspector's own addition, for refresh tokens). For that request to actually succeed, **Allowed
 Client Scopes** needs, exactly:
 - **`openid` listed explicitly.** The one genuinely non-obvious step: `openid` is not covered by
  **Allow Default Scopes** (On by default) the way other realm-Default scopes are, even though
  every OIDC request includes it. Until it's listed here, registration fails with a generic
  `403 insufficient_scope` / `"Not permitted to use specified clientScope"` regardless of
  whether everything else is configured correctly.
 - **`offline_access` listed explicitly** — it's Optional, not Default, so `ALLOW_DEFAULT_SCOPES`
  doesn't cover it either.
 - **`profile`/`email` — do not list them here.** Mark them **Default** on the **Client scopes**
  page (Assigned Type column) instead, and leave **Allow Default Scopes** = On. Adding an
  already-Default scope to this list explicitly gets rejected on save
  (`"Client scopes not allowed: [...]"`) — the list is for *additional* Optional scopes only.
 With that, a real client's token comes back with `preferred_username`/`email` populated
 normally.
 ### Fallback for anything else
 For a claim not covered by `openid profile email` (a custom attribute, a role) — or for a client
 that ignores `scopes_supported` entirely — add a **User Property** mapper to `basic` too
 (Property `username` → Token Claim Name `preferred_username`, or whatever's needed), same as the
 audience mapper in step 2. Unconditional, works regardless of client cooperation, costs one
 mapper per claim, once, at the realm level — not per tool.
 ## Verifying without a full OAuth round-trip
 **Clients → (any client) → Client scopes → Evaluate**: pick a user, run it — Default scopes
 (including `basic`) apply automatically and won't appear in the "Select scope parameters"
 picker, which only lists Optional ones — and check the **Generated Access Token** preview.
 Confirms mappers work without a browser + real MCP client round-trip each time.
 ## If a real client still gets rejected
 `McpOidcIntegration.audienceGuard` logs the actual mismatch at `WARN`:
 ```
 [flash-ext-mcp] Rejecting token (RFC 8707): aud=<token's actual aud> does not include expected
 resource identifier "<what this server expects>" — ...
 ```
 `aud=null` → the `basic` mapper produced nothing (most common cause: **Included Custom
 Audience** left blank — the mapper saves fine and silently does nothing without it). A non-null
 `aud` that still doesn't match → compare byte-for-byte — the expected side is derived from the
 request's own forwarded/`Host` headers, so scheme/host/trailing-slash mismatches show up here
 directly, as does a proxy hop that drops `X-Forwarded-Host`.
@@ -1,170 +1,58 @@
 # Security
-Provider-specific setup steps (not generic OAuth2 mechanics) live in separate cookbooks —
+The MCP endpoint is secured by [`flash-ext-security-core`](../../flash-ext-security-core/docs/README.md):
-[`keycloak.md`](keycloak.md) for Keycloak: enabling Dynamic Client Registration, why the RFC 8707
+whatever mechanisms the application registers — OAuth2 bearer tokens, API keys, custom ones —
-audience mapper needs to go on the built-in `basic` scope instead of a custom one, and the exact
+authenticate `/mcp` exactly as they authenticate every other route.
 Allowed Client Scopes configuration `scopes_supported` needs to actually work.
-## `McpSecurity`
+| `McpConfig.security(...)` | |
 |---|---|
 | `REQUIRED` (default) | every call must be authenticated; boot fails without a `SecurityExtension` |
 | `NONE` | a public endpoint; a tool carrying security annotations fails the boot |
-`McpConfig.security(...)` controls how the MCP endpoint reacts to `flash-ext-oidc` being
+## OAuth2 protected resource
 installed (`ctx.find(OidcMiddleware.class)`), resolved once at boot in `McpExtension.routes()`:
-| Policy | `flash-ext-oidc` installed | `flash-ext-oidc` absent |
+When a registered mechanism publishes an OAuth2 issuer — `flash-ext-security-oidc` does — the endpoint
-|---|---|---|
+behaves as the MCP authorization spec requires, with nothing to configure:
 | `REQUIRED` | protected | **boot fails** (`IllegalStateException`) |
 | `AUTO` (default) | protected | runs unprotected, logs a warning |
 | `NONE` | never protected, even if oidc is installed elsewhere in the app | runs unprotected |
-Use `REQUIRED` for anything you intend to run in production reachable over the network — it
+- `GET /.well-known/oauth-protected-resource/mcp` serves RFC 9728 metadata: the `resource` (the
-turns "someone forgot to wire up OAuth2" into a startup crash instead of a silently open
+  application's `SecurityExtension.origin(...)` plus the path), every issuer as `authorization_servers`,
-endpoint. `AUTO` is meant for local development, where spinning up a real identity provider is
+  and `scopes_supported` when `McpConfig.scopesSupported(...)` is set;
-friction you don't want yet.
+- an anonymous call gets `401` with `WWW-Authenticate: Bearer resource_metadata="…"`;
 - a token whose `aud` does not include the resource is `403` (RFC 8707) and logged at `WARN`. Credentials
  that are not audience-bound, such as API keys, are unaffected.
-## Why `flash-ext-oidc` is an *optional* Maven dependency, concretely
+For Keycloak, the audience comes from an *Audience* protocol mapper whose included custom audience is
 the resource URL, attached to a client scope every MCP client receives (the built-in `basic` scope is the
 one that needs no client cooperation). Clients that register dynamically need Keycloak's anonymous
 client registration policies relaxed for the trusted hosts.
-Maven's `<optional>true</optional>` only affects **transitive** propagation: consumers of
+`McpConfig.requireTokenAudience(false)` drops that last check for an authorization server that cannot
-`flash-ext-mcp` don't get `flash-ext-oidc` pulled in automatically unless they add it themselves.
+mint a resource audience at all — Keycloak ignores RFC 8707's `resource` parameter, so a deployment that
-Within `flash-ext-mcp` itself, `flash-ext-oidc`'s classes are on the compile/test classpath as
+cannot add the mapper has no other way in. Every token a registered issuer signs is then accepted on the
-normal — this extension can (and does) reference `OidcMiddleware`/`ClaimsHolder` directly in
+endpoint, and the boot logs say so.
 source.
-That reference is isolated in its own class, `McpOidcIntegration`, invoked only from inside a
+## Which credentials
 `catch (NoClassDefFoundError)` block. A bare class-literal like `OidcMiddleware.class` (which
 `ctx.find(OidcMiddleware.class)` needs) forces the JVM to resolve that type the moment it's
 evaluated — if `flash-ext-oidc` is not on the *runtime* classpath at all (a genuinely
 MCP-only install, no OAuth2 anywhere in the app), the first such reference throws
 `NoClassDefFoundError`. Keeping that reference inside a separate, lazily-loaded class means
 `McpExtension` itself loads and works fine standalone; only the attempt to actually use OIDC
 fails, and only when there's something to fail. This mirrors `OidcExtension`'s own lazy bridge to
 `flash-ext-openapi` — same technique, same reason.
-## OAuth2 resolution details — zero-config by default
+By default every mechanism in the chain authenticates `/mcp`, and the session cookie too.
-
+`McpConfig.mechanisms(...)` narrows that to the ones named: nothing else is a credential on the endpoint,
-When oidc is available and `security() != NONE`, `McpOidcIntegration` (an isolated,
+and only their issuers are published — so a client is sent to exactly the authorization server the
-lazily-loaded bridge — see its javadoc) derives everything an MCP OAuth2 resource server needs
+endpoint trusts.
 straight from the installed `OidcMiddleware`, with no additional `McpConfig` calls required:
 1. The MCP route is wrapped with `flash-ext-oidc`'s own `OidcMiddleware.protect(resourceMetadataPath)`
   — the same Bearer-token/JWKS validation path used everywhere else in Flash5, plus a
   `resource_metadata` challenge parameter (see below). No JWT parsing or JWKS handling is
   reimplemented here.
 2. An audience guard always runs after `protect(...)`: it reads the validated claims from
   `ClaimsHolder` and rejects (`403`) any token whose `aud` claim does not include the resource
   identifier — **RFC 8707 Resource Indicators / audience binding**, enforced unconditionally,
   not opt-in. `OidcMiddleware` itself validates `aud` against its own `clientId` for ID
   tokens, but deliberately does not enforce audience on access tokens (it varies by provider)
   — the MCP extension adds that check on top, scoped to its own resource identifier.
 3. The resource identifier is the canonical URI of the MCP endpoint, resolved **per request** by
   `OidcMiddleware#selfOrigin` + `rootPath` — the same scheme/host resolution `OidcExtension`
   uses for its own redirect URIs: `X-Forwarded-Host`/`X-Forwarded-Proto` when the request came
   through a reverse proxy, otherwise `{selfScheme()}://{Host header}`. Behind a proxy the
   `Host` alone is the upstream address the proxy dialled, which would publish a resource
   identifier no client can reach. `McpConfig.resourceIdentifier(...)` still overrides it
   outright for a proxy that forwards neither header.
 4. The authorization server issuer is read from `OidcMiddleware#issuer()` unless
   `McpConfig.authorizationServerIssuer(...)` overrides it.
 ## RFC 9728 Protected Resource Metadata
 Whenever the endpoint ends up protected, `flash-ext-mcp` publishes a Protected Resource Metadata
 document at `/.well-known/oauth-protected-resource{rootPath}` — no explicit `resourceIdentifier`/
 `authorizationServerIssuer` configuration required, both are auto-derived as described above:
 ```json
 { "resource": "https://mcp.example.com/mcp", "authorization_servers": ["https://auth.example.com/realms/myrealm"] }
 ```
 `resource` is computed per request from the incoming request's forwarded/`Host` headers (see
 above), so the document is correct without hardcoding the server's own public URL.
 ### `scopes_supported`
 Optional per RFC 9728, omitted from the document entirely unless set via
 `McpConfig.scopesSupported("openid", "profile", "email")`:
 ```json
 { "resource": "...", "authorization_servers": ["..."], "scopes_supported": ["openid", "profile", "email"] }
 ```
 This is pure advertisement — token validation doesn't change based on it — but it matters in
 practice: a client that ignores it and requests no scope at all (many do — see `keycloak.md`)
 only gets back whatever the authorization server treats as always-included regardless of
 request, which for Keycloak is just its built-in `basic` scope. A client that *does* read
 `scopes_supported` and echoes it back in its authorization/token requests gets a token with the
 claims those scopes actually provide (`profile` → `preferred_username`/`name`, etc.), without
 needing every one of those claims hand-mapped onto `basic`. Set it to whatever scopes your
 `McpTool`s actually read off `ClaimsHolder`/`OidcUser` — there's no way to auto-derive this list,
 it depends entirely on what your tools do with the claims.
 ## `WWW-Authenticate: resource_metadata` (RFC 9728 §5.1)
 The MCP Authorization spec **requires** a `401` to carry `resource_metadata` in
 `WWW-Authenticate`, pointing at the Protected Resource Metadata document above — this is how a
 spec-compliant client discovers the authorization server without out-of-band configuration.
 `OidcMiddleware.protect(String resourceMetadataPath)` (an overload added specifically for this)
 builds that challenge automatically:
 ```
 WWW-Authenticate: Bearer realm="...", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
 ```
 The plain `OidcMiddleware.protect()` (no argument), used by every other Flash5 app, is
 unaffected — this parameter is additive and MCP-specific.
 ## Per-tool `@RolesAllowed`/`@ScopesAllowed`
 `McpTool` subclasses can carry `flash-ext-oidc`'s `@RolesAllowed`/`@ScopesAllowed`:
 ```java
-@Tool(name = "delete_route", description = "Delete a route")
+McpConfig.builder("app").toolsPackage("com.example.tools").mechanisms(authorizationServer).build();
@RolesAllowed("admin")
 public class DeleteRouteTool extends McpTool {
    @Override public ToolResponse call(ToolArguments args) { ... }
 }
 ```
-This does **not** reuse `flash-ext-oidc`'s per-route middleware mechanism (`ctx.addAnnotationProcessor`,
+## Tool policies
 the thing that makes these annotations work on a `RequestHandler`) — it can't: every tool shares
 one HTTP route (`POST {rootPath}`), already wrapped by whatever `McpSecurity` resolved above, so
 there is no per-tool route to attach a different middleware chain to. Instead,
 `McpOidcIntegration.compileToolPolicy` reads the annotations once at boot (`McpRegistry.scan`)
 and compiles them into a closure (`McpAuthPolicy`) that `McpDispatcher` runs *after* the
 route-wide auth has already succeeded and *before* invoking the specific tool named in the
 `tools/call` request — narrowing what's already-authenticated, not replacing it. A denial is a
 normal `isError: true` tool result (see `ToolResponse.error`), not an HTTP-level rejection — the
 model sees why, the same as any other tool failure.
-Roles are read via `OidcUser#hasRole` against `McpConfig.rolesClaimPath(...)` (default
+The core annotations work on tools as on handlers, checked per `tools/call` against the caller the route
-`"realm_access.roles"`, matching `OidcConfig`'s own default — set this explicitly if the two
+authenticated:
 diverge; there's no way to read `OidcConfig`'s actual configured value from here). Scopes use
 `OidcUser#hasScope`'s built-in default claim paths (`scope`/`scp`), no extra config needed.
 `@ScopesAllowed(match = ScopesAllowed.Match.ANY)` and multi-role `@RolesAllowed({"admin",
 "editor"})` (OR semantics) both work exactly as they do on a `RequestHandler`.
-**`@Authenticated` alone has no effect and fails boot.** Once oidc is active for a server, every
+```java
-tool call is already authenticated — there's no per-tool public/authenticated split the way
+@Tool(name = "approve", description = "Approves a pending proposal")
-there is for HTTP routes, so a bare `@Authenticated` on a tool can't mean anything and would
+@RolesAllowed(value = "REVIEWER", on = {"project", "locale"})   // read from the tool's arguments
-silently do nothing if allowed to compile. Boot fails instead, with a message pointing at
+public class ApproveTool extends McpTool { … }
-`@RolesAllowed`/`@ScopesAllowed` as the actual narrowing mechanism.
+```
-**Annotating a tool without active OAuth2 also fails boot**, not silently at request time: if
+A denial is a tool result with `isError: true` — the call reached the server, the tool did not run.
 `@RolesAllowed`/`@ScopesAllowed`/`@Authenticated` shows up on a tool while `McpSecurity` resolved
 to unprotected (`NONE`, or `AUTO` with no oidc installed), that's very likely a forgotten
 `OidcExtension` install or a `McpSecurity.NONE` left over from local dev — `IllegalStateException`
 at `app.start()`.
-## The `HttpException` safety net
+`McpConfig.middleware(...)` runs after authentication, for rate limiting, auditing or tracing.
 `flash-ext-oidc`'s middleware throws `HttpException.unauthorized()`/`forbidden()` on auth
 failure. Flash5's core does **not** special-case `HttpException` in the default exception
 handler — the out-of-the-box `AbstractRouter` default always returns a generic `500`, regardless
 of the thrown exception's embedded status code; only an app that explicitly calls
 `FlashApp#onException(...)` (or installs something that does) gets `HttpException.status()`
 honored.
 To keep the MCP endpoint correct regardless of what the rest of the app configures,
 `McpTransportGuards.httpExceptionGuard()` wraps the whole route and translates `HttpException`
 into the right HTTP status itself, rather than letting it fall through to the app's (possibly
 unconfigured) global handler. This is scoped entirely to the MCP route — it does not touch or
 override the app's `onException` for any other route.
@@ -19,8 +19,7 @@
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
-            <artifactId>flash-ext-oidc</artifactId>
+            <artifactId>flash-ext-security-core</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
@@ -38,6 +37,27 @@
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-testing</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-security-test</artifactId>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-security-oidc</artifactId>
            <version>${project.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
            <artifactId>flash-ext-security-apikey</artifactId>
            <version>${project.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
 </project>
@@ -1,23 +0,0 @@
 package dev.relism.flash.ext.mcp;
 import java.util.function.Supplier;
 /**
 * Compiled per-tool authorization requirement, built once at boot by {@link McpOidcIntegration}
 * from {@code @RolesAllowed}/{@code @ScopesAllowed} on an {@link McpTool} subclass — {@code null}
 * on {@link McpRegistry.RegisteredTool} means no restriction beyond whatever {@link McpSecurity}
 * already enforces route-wide.
 *
 * <p>{@code check} is a closure, not a raw role/scope list — this is what lets this record (and
 * its only caller, {@link McpDispatcher}) stay free of any compile-time reference to a {@code
 * flash-ext-oidc} type, preserving the same classload isolation {@link McpOidcIntegration}'s
 * javadoc describes for the rest of the OIDC bridge. Only the plain-JDK {@link Supplier}
 * signature crosses the boundary; the closure itself, built once inside {@code
 * McpOidcIntegration}, is the only place that ever touches {@code OidcUser}/{@code ClaimsHolder}.
 *
 * <p>Returns {@code null} from {@link #check()}{@code .get()} when authorized, or a
 * human-readable denial reason otherwise — invoked once per {@code tools/call} against an
 * annotated tool, never allocated on that path (the closure and its captured role/scope arrays
 * are built exactly once, at boot).
 */
 record McpAuthPolicy(Supplier<String> check) {}
@@ -1,5 +1,8 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.ext.security.AuthenticationMechanism;
 import dev.relism.flash.routing.Middleware;
 import java.util.ArrayList;
 import java.util.List;
@@ -24,10 +27,11 @@ public final class McpConfig {
    private final String rootPath;
    private final String toolsPackage;
    private final McpSecurity security;
-    private final String resourceIdentifier;
+    private final boolean requireTokenAudience;
    private final String authorizationServerIssuer;
    private final List<String> allowedOrigins;
    private final List<String> scopesSupported;
    private final List<Middleware> middleware;
    private final List<AuthenticationMechanism> mechanisms;
    private McpConfig(Builder b) {
        this.name = b.name;
@@ -36,10 +40,11 @@ public final class McpConfig {
        this.rootPath = b.rootPath;
        this.toolsPackage = b.toolsPackage;
        this.security = b.security;
-        this.resourceIdentifier = b.resourceIdentifier;
+        this.requireTokenAudience = b.requireTokenAudience;
        this.authorizationServerIssuer = b.authorizationServerIssuer;
        this.allowedOrigins = List.copyOf(b.allowedOrigins);
        this.scopesSupported = List.copyOf(b.scopesSupported);
        this.middleware = List.copyOf(b.middleware);
        this.mechanisms = List.copyOf(b.mechanisms);
    }
    String name()                     { return name; }
@@ -48,10 +53,11 @@ public final class McpConfig {
    String rootPath()                 { return rootPath; }
    String toolsPackage()             { return toolsPackage; }
    McpSecurity security()            { return security; }
-    String resourceIdentifier()       { return resourceIdentifier; }
+    boolean requireTokenAudience()    { return requireTokenAudience; }
    String authorizationServerIssuer() { return authorizationServerIssuer; }
    List<String> allowedOrigins()     { return allowedOrigins; }
    List<String> scopesSupported()    { return scopesSupported; }
    List<Middleware> middleware()     { return middleware; }
    List<AuthenticationMechanism> mechanisms() { return mechanisms; }
    public static Builder builder(String name) { return new Builder(name); }
@@ -61,11 +67,12 @@ public final class McpConfig {
        private String instructions;
        private String rootPath = "/mcp";
        private String toolsPackage;
-        private McpSecurity security = McpSecurity.AUTO;
+        private McpSecurity security = McpSecurity.REQUIRED;
-        private String resourceIdentifier;
+        private boolean requireTokenAudience = true;
        private String authorizationServerIssuer;
        private final List<String> allowedOrigins = new ArrayList<>();
        private final List<String> scopesSupported = new ArrayList<>();
        private final List<Middleware> middleware = new ArrayList<>();
        private final List<AuthenticationMechanism> mechanisms = new ArrayList<>();
        private Builder(String name) {
            if (name == null || name.isBlank())
@@ -85,28 +92,16 @@ public final class McpConfig {
        /** Package scanned for {@link Tool @Tool}/{@link Resource @Resource}/{@link Prompt @Prompt} classes. Required. */
        public Builder toolsPackage(String toolsPackage) { this.toolsPackage = toolsPackage; return this; }
-        /** OAuth2 requirement policy. Default {@link McpSecurity#AUTO}. */
+        /** Default {@link McpSecurity#REQUIRED}. */
        public Builder security(McpSecurity security) { this.security = security; return this; }
        /**
-         * Canonical URI of this MCP endpoint, used for RFC 8707 audience binding: tokens whose
+         * Whether a bearer token must name this endpoint in its {@code aud} (RFC 8707), as the MCP
-         * {@code aud} claim does not include this value are rejected. Optional — when
+         * authorization spec requires. Default {@code true}. Turn it off for an authorization server
-         * {@code flash-ext-oidc} is installed, this is auto-derived per request from the
+         * that cannot mint a resource audience — every token a registered issuer signs is then
-         * forwarded/{@code Host} headers (same resolution {@code OidcExtension} uses for its own
+         * accepted on the endpoint, and a warning is logged at boot.
         * redirect URIs) and audience binding is enforced unconditionally. Set this explicitly
         * only to override that guess — a reverse proxy that forwards neither
         * {@code X-Forwarded-Host} nor {@code X-Forwarded-Proto}.
         */
-        public Builder resourceIdentifier(String resourceIdentifier) { this.resourceIdentifier = resourceIdentifier; return this; }
+        public Builder requireTokenAudience(boolean require) { this.requireTokenAudience = require; return this; }
        /**
         * Authorization server issuer URL, published in the RFC 9728 Protected Resource
         * Metadata document at {@code /.well-known/oauth-protected-resource{rootPath}}. Optional
         * — when {@code flash-ext-oidc} is installed, this is auto-derived from its configured
         * issuer. Set this explicitly only to override that (e.g. publishing a different issuer
         * than the one actually validating tokens).
         */
        public Builder authorizationServerIssuer(String issuer) { this.authorizationServerIssuer = issuer; return this; }
        /**
         * Origins allowed to call the MCP endpoint (DNS-rebinding protection, per the Streamable
@@ -115,19 +110,24 @@ public final class McpConfig {
         */
        public Builder allowedOrigins(String... origins) { this.allowedOrigins.addAll(List.of(origins)); return this; }
-        /**
+        /** Published as {@code scopes_supported} in the RFC 9728 metadata, so OAuth clients request them. */
         * OAuth2 scopes this server expects clients to request, published as {@code
         * scopes_supported} in the RFC 9728 Protected Resource Metadata document. Optional per
         * the spec — omitted from the document entirely if never set. A spec-compliant client
         * reads this to know what to put in its authorization/token requests instead of
         * requesting nothing; see {@code docs/keycloak.md}'s "same story for any other claim"
         * section for why this matters in practice (a client that requests no scope only gets
         * whatever your authorization server treats as always-included, e.g. Keycloak's `basic`).
         * Purely advertisement — this server still validates whatever token it actually receives
         * the same way regardless of what a client requested.
         */
        public Builder scopesSupported(String... scopes) { this.scopesSupported.addAll(List.of(scopes)); return this; }
        /**
         * The only mechanisms that authenticate the endpoint, and the only issuers its RFC 9728 metadata
         * names: any other credential, the session cookie included, is none here. Default: the whole chain.
         */
        public Builder mechanisms(AuthenticationMechanism... mechanisms) {
            this.mechanisms.addAll(List.of(mechanisms));
            return this;
        }
        /** Runs on the MCP route after the transport guards and authentication — rate limiting, auditing, tracing. */
        public Builder middleware(Middleware... middleware) {
            this.middleware.addAll(List.of(middleware));
            return this;
        }
        public McpConfig build() {
            if (toolsPackage == null || toolsPackage.isBlank())
                throw new IllegalStateException(
@@ -3,6 +3,8 @@ package dev.relism.flash.ext.mcp;
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.JsonNode;
 import dev.relism.flash.http.ContentType;
 import dev.relism.flash.ext.security.SecurityIdentity;
 import dev.relism.flash.ext.security.SecurityPolicy;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.models.Response;
@@ -18,10 +20,10 @@ import java.io.IOException;
 * tool/resource/prompt name, resource/prompt handler exceptions) is a JSON-RPC error object,
 * always returned with HTTP 200: the HTTP request itself succeeded, only the RPC did not. Only
 * malformed HTTP-level input (unparsable JSON, not a JSON object) gets HTTP 400. A
- * {@code @RolesAllowed}/{@code @ScopesAllowed} denial (see {@link McpAuthPolicy}) is the same
+ * {@code @RolesAllowed}/{@code @ScopesAllowed} denial (see {@link SecurityPolicy}) is the same
 * category — {@code isError: true}, tool never invoked — not a transport-level rejection; the
- * route-wide 401/403 for "not authenticated at all" already happened earlier, in the {@code
+ * route-wide 401/403 already happened earlier, in the security middleware, before this
- * OidcMiddleware}/audience-guard middleware chain, before this dispatcher ever runs.
+ * dispatcher ever runs.
 */
 final class McpDispatcher {
@@ -136,12 +138,14 @@ final class McpDispatcher {
        if (tool == null)
            throw McpProtocolException.invalidParams("Unknown tool: " + name);
        ToolArguments args = new ToolArguments(params.path("arguments"));
        SecurityPolicy policy = tool.policy();
        ToolResponse result;
-        String denied = tool.policy() != null ? tool.policy().check().get() : null;
+        if (policy != null && !policy.permitsScopes(SecurityIdentity.current())) {
-        if (denied != null) {
+            result = ToolResponse.error("Tool \"" + name + "\" denied: missing scope");
-            result = ToolResponse.error("Tool \"" + name + "\" denied: " + denied);
+        } else if (policy != null && !policy.permitsRoles(SecurityIdentity.current(), args::getString)) {
            result = ToolResponse.error("Tool \"" + name + "\" denied: missing role");
        } else {
            ToolArguments args = new ToolArguments(params.path("arguments"));
            try {
                result = tool.instance().call(args);
            } catch (Exception e) {
@@ -1,5 +1,12 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.ext.security.AuthenticationEntryPoint;
 import dev.relism.flash.ext.security.AuthenticationMechanism;
 import dev.relism.flash.ext.security.SecurityExtension;
 import dev.relism.flash.ext.security.SecurityIdentity;
 import dev.relism.flash.ext.security.SecurityPolicy;
 import dev.relism.flash.ext.security.SecurityScheme;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.extension.FlashRegistrar;
@@ -9,43 +16,31 @@ import lombok.extern.slf4j.Slf4j;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
 /**
- * MCP (Model Context Protocol) server extension. Streamable HTTP transport — a single
+ * MCP (Model Context Protocol) server extension. Streamable HTTP transport — a single {@code POST}
- * {@code POST} JSON-RPC endpoint, stateless in this revision (no session, no SSE stream; see
+ * JSON-RPC endpoint, stateless in this revision (see {@code docs/transport.md}) — dispatching to
- * {@code docs/transport.md}) — dispatch precompiled at boot from classes annotated with
+ * {@link Tool @Tool}/{@link Resource @Resource}/{@link Prompt @Prompt} classes under
 * {@link Tool @Tool}/{@link Resource @Resource}/{@link Prompt @Prompt} under
 * {@link McpConfig#toolsPackage(String)}.
 *
 * <pre>{@code
- * // Standalone, no OAuth2
+ * app.install(new SecurityExtension())
- * FlashApp.create(8080)
+ *    .install(new OidcExtension(OidcProvider.of("sso", issuer, clientId, secret)))
- *     .install(new McpExtension(McpConfig.builder("my-mcp-server")
+ *    .install(new McpExtension(McpConfig.builder("my-server").toolsPackage("com.example.tools").build()));
 *         .toolsPackage("com.example.tools")
 *         .build()))
 *     .start();
 *
 * // With flash-ext-oidc as the OAuth2 resource server — zero extra config: issuer, canonical
 * // resource identifier, RFC 8707 audience binding and RFC 9728 metadata are all derived from
 * // the installed OidcExtension.
 * FlashApp.create(8080)
 *     .install(new OidcExtension(oidcConfig))
 *     .install(new McpExtension(McpConfig.builder("my-mcp-server")
 *         .toolsPackage("com.example.tools")
 *         .security(McpSecurity.REQUIRED)
 *         .build()))
 *     .start();
 * }</pre>
 *
- * <p>One server per {@code McpExtension} instance — install multiple instances (distinct
+ * <p>Every call is authenticated by the application's security chain — OAuth2 bearer tokens, API
- * {@code rootPath}, distinct {@code toolsPackage}) for multiple MCP servers on one app,
+ * keys, anything registered. When an OAuth2 issuer is among its schemes, the endpoint is also an
- * mirroring the {@code OidcExtension} multi-tenant pattern. See {@code docs/security.md} for
+ * OAuth2 protected resource: RFC 9728 metadata, a {@code resource_metadata} challenge, and RFC 8707
- * the full OAuth2 resolution rules.
+ * audience binding for audience-bound tokens. Tool annotations are enforced per call, with
 * {@code @RolesAllowed(on = ...)} reading tool arguments.
 */
@Slf4j
 public class McpExtension implements FlashExtension {
    private final McpConfig config;
    private volatile List<SecurityScheme> schemes;
    public McpExtension(McpConfig config) {
        this.config = config;
@@ -53,68 +48,67 @@ public class McpExtension implements FlashExtension {
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
-        ctx.onReady(() -> registerRoutes(app, ctx));
+        ctx.onReady(() -> {
-    }
+            SecurityExtension security = config.security() == McpSecurity.NONE ? null : ctx.find(SecurityExtension.class)
                    .orElseThrow(() -> new IllegalStateException("MCP server \"" + config.name()
                            + "\" requires flash-ext-security-core: install a SecurityExtension, or set McpSecurity.NONE for a public server"));
            McpDispatcher dispatcher = new McpDispatcher(McpRegistry.scan(config.toolsPackage(), ctx, security),
                    config.name(), config.version(), config.instructions());
-    private void registerRoutes(FlashRegistrar<?> app, FlashContext ctx) {
+            List<Middleware> chain = new ArrayList<>(List.of(
-        // Resolved before scanning so McpRegistry knows, per tool, whether @RolesAllowed/
+                    McpTransportGuards.httpExceptionGuard(), McpTransportGuards.originGuard(config.allowedOrigins())));
-        // @ScopesAllowed are backed by real OAuth2 protection or a boot-time misconfiguration
+            if (security != null) protect(app, security, chain);
-        // (see McpOidcIntegration#compileToolPolicy) — must run first, not after.
+            chain.addAll(config.middleware());
-        McpOidcIntegration.Resolved secured = resolveSecurity(ctx);
+            app.post(config.rootPath(), (req, res) -> {
-        McpRegistry registry = McpRegistry.scan(config.toolsPackage(), ctx, secured != null,
+                dispatcher.handle(req, res);
-                secured == null ? null : secured.rolesClaimPath());
+                return null;
-        McpDispatcher dispatcher = new McpDispatcher(registry, config.name(), config.version(), config.instructions());
+            }, chain.toArray(Middleware[]::new));
        List<Middleware> chain = new ArrayList<>(3);
        chain.add(McpTransportGuards.httpExceptionGuard());
        chain.add(McpTransportGuards.originGuard(config.allowedOrigins()));
        if (secured != null) chain.add(secured.security());
        app.post(config.rootPath(), (req, res) -> { dispatcher.handle(req, res); return null; },
                chain.toArray(Middleware[]::new));
        registerResourceMetadata(app, secured);
    }
    private McpOidcIntegration.Resolved resolveSecurity(FlashContext ctx) {
        if (config.security() == McpSecurity.NONE) return null;
        McpOidcIntegration.Resolved resolved;
        try {
            resolved = McpOidcIntegration.resolve(ctx, config);
        } catch (NoClassDefFoundError e) {
            resolved = null; // flash-ext-oidc not on the classpath at all
        }
        if (resolved != null) return resolved;
        if (config.security() == McpSecurity.REQUIRED) {
            throw new IllegalStateException(
                    "McpSecurity.REQUIRED but flash-ext-oidc is not installed for MCP server \"" + config.name() +
                    "\" — install an OidcExtension before this McpExtension, or relax security to " +
                    "McpSecurity.AUTO/NONE if this server is meant to be public.");
        }
        log.warn("[flash-ext-mcp] MCP server \"{}\" is running WITHOUT OAuth2 protection — " +
                "flash-ext-oidc is not installed and McpSecurity.AUTO degrades to unprotected. " +
                "Install flash-ext-oidc or set McpSecurity.REQUIRED to make this a hard failure instead.",
                config.name());
        return null;
    }
    /**
     * RFC 9728 Protected Resource Metadata, built once security is resolved — no longer
     * conditioned on {@code resourceIdentifier}/{@code authorizationServerIssuer} being set
     * explicitly, since {@link McpOidcIntegration#resolve} now derives both by default. The
     * {@code resource} field is computed per request (it depends on that request's own
     * forwarded/{@code Host} headers) via {@link McpOidcIntegration.Resolved#resourceIdentifier()}.
     */
    private void registerResourceMetadata(FlashRegistrar<?> app, McpOidcIntegration.Resolved secured) {
        if (secured == null) return;
        String path = "/.well-known/oauth-protected-resource" + config.rootPath();
        app.get(path, (req, res) -> {
            res.type(ContentType.JSON);
            return McpResourceMetadata.build(
                    secured.resourceIdentifier().apply(req), secured.issuer(), config.scopesSupported());
        });
    }
    private void protect(FlashRegistrar<?> app, SecurityExtension security, List<Middleware> chain) {
        String metadataPath = "/.well-known/oauth-protected-resource" + config.rootPath();
        List<AuthenticationMechanism> only = config.mechanisms();
        AuthenticationEntryPoint anonymous = (req, res) -> {
            List<SecurityScheme> schemes = schemes(security);
            res.header("WWW-Authenticate", issuers(schemes, null).isEmpty()
                    ? String.join(", ", schemes.stream().map(SecurityScheme::challenge).toList())
                    : "Bearer resource_metadata=\"" + security.origin(req) + metadataPath + "\"");
            throw HttpException.unauthorized();
        };
        chain.add(only.isEmpty() ? security.enforce(SecurityPolicy.AUTHENTICATED, anonymous)
                : security.enforce(SecurityPolicy.AUTHENTICATED, anonymous, only));
        if (config.requireTokenAudience()) {
            chain.add(next -> (req, res) -> {
                String resource = security.origin(req) + config.rootPath();
                if (!SecurityIdentity.current().principal().hasAudience(resource)) {
                    log.warn("[flash-ext-mcp] Rejected a token not issued for {} (RFC 8707) — the authorization server must put it in aud", resource);
                    throw HttpException.forbidden();
                }
                return next.handle(req, res);
            });
        } else {
            log.warn("[flash-ext-mcp] Token audience validation (RFC 8707) is DISABLED for {} — every token a registered issuer signs is accepted.", config.rootPath());
        }
        app.get(metadataPath, (req, res) -> {
            List<String> issuers = issuers(schemes(security), security.origin(req));
            if (issuers.isEmpty()) throw HttpException.notFound("Protected resource metadata");
            res.type(ContentType.JSON);
            return McpResourceMetadata.build(security.origin(req) + config.rootPath(), issuers, config.scopesSupported());
        });
    }
    /** Resolved at the first request, once every mechanism has registered — which may be after this extension was ready. */
    private List<SecurityScheme> schemes(SecurityExtension security) {
        if (schemes == null) {
            schemes = config.mechanisms().isEmpty() ? security.schemes()
                    : config.mechanisms().stream().flatMap(mechanism -> mechanism.schemes().stream()).toList();
        }
        return schemes;
    }
    /** {@code "/"} is the application's own authorization server, at {@code origin}. */
    private static List<String> issuers(List<SecurityScheme> schemes, String origin) {
        return schemes.stream().map(SecurityScheme::issuer).filter(Objects::nonNull).map(issuer -> issuer.equals("/") ? origin : issuer).toList();
    }
 }
@@ -19,7 +19,7 @@ import java.nio.charset.StandardCharsets;
 *
 * <p>Not wired to {@code flash-ext-jackson} on purpose: the MCP JSON-RPC envelope is internal
 * protocol plumbing, not a user-facing serialization concern, so this extension owns its
- * mapper independently — same reasoning {@code flash-ext-oidc} applies to its own JSON needs
+ * mapper independently — the same reasoning any protocol-level extension applies to its own JSON needs
 * (see {@code json-smart} there). See {@code docs/jackson-interop.md} for the full rationale
 * and how a future opt-in reuse of a shared {@code ObjectMapper} could work.
 */
@@ -1,180 +0,0 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.ext.oidc.Authenticated;
 import dev.relism.flash.ext.oidc.ClaimsHolder;
 import dev.relism.flash.ext.oidc.OidcMiddleware;
 import dev.relism.flash.ext.oidc.OidcUser;
 import dev.relism.flash.ext.oidc.RolesAllowed;
 import dev.relism.flash.ext.oidc.ScopesAllowed;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.routing.Middleware;
 import lombok.extern.slf4j.Slf4j;
 import java.util.LinkedHashSet;
 import java.util.Map;
 import java.util.Optional;
 import java.util.function.Function;
 import java.util.function.Supplier;
 /**
 * Lazy, isolated bridge to {@code flash-ext-oidc}.
 *
 * <p>References to OIDC types only ever resolve when {@link #resolve}/{@link #compileToolPolicy}
 * are actually invoked — never at {@link McpExtension} class-load time — because they live in
 * this separate nested class. The caller wraps the invocation in {@code catch
 * (NoClassDefFoundError)}, exactly like {@code OidcExtension}'s own lazy bridge to {@code
 * flash-ext-openapi}. This is what lets {@code flash-ext-mcp} run standalone (MCP-only, no
 * OAuth2) when {@code flash-ext-oidc} is not even on the classpath. {@link Resolved}/{@link
 * McpAuthPolicy} carry only oidc-free types back out ({@link Middleware}, {@link String}, a
 * {@link Function}, a {@link Supplier}) so no other class in this package ever has to reference
 * an OIDC type.
 *
 * <p>Zero-config by design: when {@code flash-ext-oidc} is installed, everything an MCP OAuth2
 * resource server needs — issuer, canonical resource identifier, RFC 8707 audience binding, and
 * a spec-compliant {@code WWW-Authenticate} challenge (RFC 9728 §5.1) — is derived straight from
 * the installed {@link OidcMiddleware}, with no additional {@link McpConfig} calls.
 * {@link McpConfig#resourceIdentifier(String)}/{@link McpConfig#authorizationServerIssuer(String)}
 * remain as explicit overrides for the rare case where that guess is wrong.
 */
@Slf4j
 final class McpOidcIntegration {
    private static final String[] NO_VALUES = new String[0];
    private McpOidcIntegration() {}
    /** Everything {@link McpExtension} needs once oidc security is resolved. */
    record Resolved(Middleware security, String issuer, String rolesClaimPath,
                    Function<Request, String> resourceIdentifier) {}
    /** Returns the resolved security bundle, or {@code null} if oidc is not installed. */
    static Resolved resolve(FlashContext ctx, McpConfig config) {
        Optional<OidcMiddleware> oidc = ctx.find(OidcMiddleware.class);
        if (oidc.isEmpty()) return null;
        OidcMiddleware oidcMw = oidc.get();
        String resourceMetadataPath = "/.well-known/oauth-protected-resource" + config.rootPath();
        String issuer = config.authorizationServerIssuer() != null
                ? config.authorizationServerIssuer() : oidcMw.issuer();
        Function<Request, String> resourceId = req -> config.resourceIdentifier() != null
                ? config.resourceIdentifier()
                : OidcMiddleware.selfOrigin(req, oidcMw.selfScheme()) + config.rootPath();
        Middleware protect = oidcMw.protect(resourceMetadataPath);
        Middleware secured = Middleware.of(protect, audienceGuard(resourceId));
        return new Resolved(secured, issuer, oidcMw.rolesClaimPath(), resourceId);
    }
    /**
     * RFC 8707 audience binding, unconditionally enforced once oidc is protecting the MCP
     * route — no longer opt-in behind an explicit {@code resourceIdentifier(...)} call.
     */
    private static Middleware audienceGuard(Function<Request, String> resourceIdentifier) {
        return next -> (req, res) -> {
            Map<String, Object> claims = ClaimsHolder.get();
            String expected = resourceIdentifier.apply(req);
            if (claims != null && !audienceMatches(claims.get("aud"), expected)) {
                log.warn("[flash-ext-mcp] Rejecting token (RFC 8707): aud={} does not include expected " +
                        "resource identifier \"{}\" — the authorization server must include this exact " +
                        "value in the access token's aud claim (e.g. an Audience protocol mapper in " +
                        "Keycloak) for this MCP server to accept it.", claims.get("aud"), expected);
                throw HttpException.forbidden();
            }
            return next.handle(req, res);
        };
    }
    private static boolean audienceMatches(Object aud, String expected) {
        if (aud instanceof String s) return s.equals(expected);
        if (aud instanceof Iterable<?> it) {
            for (Object o : it) if (expected.equals(String.valueOf(o))) return true;
        }
        return false;
    }
    /**
     * Compiles {@code @RolesAllowed}/{@code @ScopesAllowed} on a tool class into a {@link
     * McpAuthPolicy}, or returns {@code null} if the tool carries none of the three OIDC
     * annotations. Called once per tool at boot ({@link McpRegistry#scan}), never on the
     * request hot path — the {@link Supplier} it returns is what runs per {@code tools/call},
     * closing over the already-normalized role/scope arrays so the hot path itself allocates
     * nothing beyond what {@link OidcUser#hasRole}/{@link OidcUser#hasScope} already do.
     *
     * <p>Fails fast at boot, not silently at request time, for the two ways this can be
     * misconfigured: the annotation present without OAuth2 actually protecting this MCP server
     * ({@code oidcActive == false}), and {@code @Authenticated} — which has no per-tool meaning
     * here (see below) — used at all.
     */
    static McpAuthPolicy compileToolPolicy(Class<? extends McpTool> toolClass, boolean oidcActive,
                                            String rolesClaimPath) {
        Authenticated auth = toolClass.getAnnotation(Authenticated.class);
        RolesAllowed roles = toolClass.getAnnotation(RolesAllowed.class);
        ScopesAllowed scopes = toolClass.getAnnotation(ScopesAllowed.class);
        if (auth == null && roles == null && scopes == null) return null;
        if (!oidcActive) {
            throw new IllegalStateException(
                    "MCP tool \"" + toolClass.getSimpleName() + "\" declares @Authenticated/@RolesAllowed/" +
                    "@ScopesAllowed, but this MCP server has no active OAuth2 protection — flash-ext-oidc " +
                    "is not installed for it, or McpSecurity is NONE. These annotations require " +
                    "McpSecurity.AUTO/REQUIRED with an OidcExtension installed; install one, or remove the " +
                    "annotation from " + toolClass.getSimpleName() + ".");
        }
        if (auth != null) {
            throw new IllegalStateException(
                    "MCP tool \"" + toolClass.getSimpleName() + "\" is annotated @Authenticated, which has " +
                    "no effect on an McpTool: the whole MCP endpoint is already all-or-nothing " +
                    "authenticated once oidc is active (McpSecurity.AUTO/REQUIRED) — unlike a RequestHandler " +
                    "route, there is no per-tool public/authenticated split to opt into. Remove it, or use " +
                    "@RolesAllowed/@ScopesAllowed to narrow further.");
        }
        String[] requiredRoles = roles != null ? normalizeRequired("RolesAllowed", roles.value()) : NO_VALUES;
        String[] requiredScopes = scopes != null ? normalizeRequired("ScopesAllowed", scopes.value()) : NO_VALUES;
        ScopesAllowed.Match scopeMatch = scopes != null ? scopes.match() : ScopesAllowed.Match.ALL;
        Supplier<String> check = () -> {
            OidcUser user = ClaimsHolder.user();
            if (user == null) return "not authenticated";
            if (requiredRoles.length > 0 && !hasAnyRole(user, rolesClaimPath, requiredRoles))
                return "missing required role (any of: " + String.join(", ", requiredRoles) + ")";
            if (requiredScopes.length > 0 && !hasScopes(user, requiredScopes, scopeMatch))
                return "missing required scope (" + scopeMatch + " of: " + String.join(", ", requiredScopes) + ")";
            return null;
        };
        return new McpAuthPolicy(check);
    }
    private static boolean hasAnyRole(OidcUser user, String claimPath, String[] roles) {
        for (String role : roles) if (user.hasRole(claimPath, role)) return true;
        return false;
    }
    private static boolean hasScopes(OidcUser user, String[] scopes, ScopesAllowed.Match match) {
        if (match == ScopesAllowed.Match.ALL) {
            for (String scope : scopes) if (!user.hasScope(scope)) return false;
            return true;
        }
        for (String scope : scopes) if (user.hasScope(scope)) return true;
        return false;
    }
    /** Mirrors {@code OidcAuthPolicy}'s own normalization — trim, dedupe, require non-blank. */
    private static String[] normalizeRequired(String annotationName, String[] values) {
        if (values == null || values.length == 0)
            throw new IllegalStateException("@" + annotationName + " requires at least one value");
        LinkedHashSet<String> normalized = new LinkedHashSet<>(values.length);
        for (String raw : values) {
            if (raw == null) continue;
            String trimmed = raw.trim();
            if (!trimmed.isEmpty()) normalized.add(trimmed);
        }
        if (normalized.isEmpty())
            throw new IllegalStateException("@" + annotationName + " requires at least one non-empty value");
        return normalized.toArray(String[]::new);
    }
 }
@@ -2,6 +2,8 @@ package dev.relism.flash.ext.mcp;
 import com.fasterxml.jackson.core.JsonGenerator;
 import dev.relism.flash.exceptions.InitializationException;
 import dev.relism.flash.ext.security.SecurityExtension;
 import dev.relism.flash.ext.security.SecurityPolicy;
 import dev.relism.flash.extension.FlashContext;
 import java.io.IOException;
@@ -25,7 +27,7 @@ final class McpRegistry {
    private static final String EMPTY_ARRAY = "[]";
    /** {@code policy} is {@code null} unless the tool carries @RolesAllowed/@ScopesAllowed. */
-    record RegisteredTool(String name, McpTool instance, McpAuthPolicy policy) {}
+    record RegisteredTool(String name, McpTool instance, SecurityPolicy policy) {}
    record RegisteredResource(String uri, McpResource instance) {}
    record RegisteredPrompt(String name, McpPrompt instance) {}
@@ -39,15 +41,8 @@ final class McpRegistry {
    private McpRegistry() {}
-    /**
+    /** @param security {@code null} for a server running with {@link McpSecurity#NONE} */
-     * @param oidcActive    whether this MCP server's route is actually OAuth2-protected right
+    static McpRegistry scan(String packageName, FlashContext ctx, SecurityExtension security) {
     *                      now (see {@link McpOidcIntegration#resolve}) — gates whether
     *                      {@code @RolesAllowed}/{@code @ScopesAllowed} on a tool are honored or
     *                      rejected at boot as a misconfiguration; see
     *                      {@link McpOidcIntegration#compileToolPolicy}.
     * @param rolesClaimPath claim path resolved from the installed OIDC extension.
     */
    static McpRegistry scan(String packageName, FlashContext ctx, boolean oidcActive, String rolesClaimPath) {
        McpPackageScanner.ScanResult found = McpPackageScanner.scan(packageName);
        McpRegistry registry = new McpRegistry();
@@ -55,7 +50,9 @@ final class McpRegistry {
            Tool ann = cls.getAnnotation(Tool.class);
            McpTool instance = instantiate(cls);
            instance.bind(ctx);
-            McpAuthPolicy policy = compileToolPolicy(cls, oidcActive, rolesClaimPath);
+            if (security == null && SecurityPolicy.of(cls) != null)
                throw new InitializationException("MCP tool \"" + ann.name() + "\" declares security annotations, but the server runs with McpSecurity.NONE");
            SecurityPolicy policy = security == null ? null : security.policy(cls);
            if (registry.tools.putIfAbsent(ann.name(), new RegisteredTool(ann.name(), instance, policy)) != null)
                throw new InitializationException("Duplicate MCP tool name: \"" + ann.name() + "\"");
        }
@@ -173,24 +170,6 @@ final class McpRegistry {
        gen.writeEndArray();
    }
    /**
     * Isolated the same way {@link McpOidcIntegration#resolve} is — {@code
     * NoClassDefFoundError} here means {@code flash-ext-oidc} genuinely isn't on the runtime
     * classpath, in which case a tool couldn't have been compiled against
     * {@code @RolesAllowed}/{@code @ScopesAllowed} in the first place, so there's nothing to
     * check (and nothing lost: {@code oidcActive} is only ever {@code true} once {@link
     * McpOidcIntegration#resolve} has already succeeded once this boot, which proves those
     * types resolve fine).
     */
    private static McpAuthPolicy compileToolPolicy(Class<? extends McpTool> cls, boolean oidcActive,
                                                     String rolesClaimPath) {
        try {
            return McpOidcIntegration.compileToolPolicy(cls, oidcActive, rolesClaimPath);
        } catch (NoClassDefFoundError e) {
            return null;
        }
    }
    private static <T> T instantiate(Class<T> cls) {
        try {
            Constructor<T> ctor = cls.getDeclaredConstructor();
@@ -2,18 +2,18 @@ package dev.relism.flash.ext.mcp;
 import java.util.List;
-/** RFC 9728 OAuth 2.0 Protected Resource Metadata document, built once at boot. */
+/** RFC 9728 OAuth 2.0 Protected Resource Metadata. */
 final class McpResourceMetadata {
    private McpResourceMetadata() {}
-    /** {@code scopesSupported} is optional per RFC 9728 — omitted from the document if empty. */
+    /** {@code scopesSupported} is optional — omitted when empty. */
-    static String build(String resourceIdentifier, String authorizationServerIssuer, List<String> scopesSupported) {
+    static String build(String resource, List<String> authorizationServers, List<String> scopesSupported) {
        return McpJson.buildString(gen -> {
            gen.writeStartObject();
-            gen.writeStringField("resource", resourceIdentifier);
+            gen.writeStringField("resource", resource);
            gen.writeArrayFieldStart("authorization_servers");
-            gen.writeString(authorizationServerIssuer);
+            for (String issuer : authorizationServers) gen.writeString(issuer);
            gen.writeEndArray();
            if (!scopesSupported.isEmpty()) {
                gen.writeArrayFieldStart("scopes_supported");
@@ -1,17 +1,11 @@
 package dev.relism.flash.ext.mcp;
-/**
+/** Whether the MCP endpoint requires an authenticated caller. */
 * OAuth2 requirement policy for the MCP endpoint, resolved against whether
 * {@code flash-ext-oidc} is installed ({@code ctx.find(OidcMiddleware.class)}).
 */
 public enum McpSecurity {
-    /** Fail fast at boot if {@code flash-ext-oidc} is not installed — never expose an unprotected MCP endpoint. */
+    /** The default: every call is authenticated by {@code flash-ext-security-core}, which must be installed. */
    REQUIRED,
-    /** Protect the endpoint if {@code flash-ext-oidc} is installed; otherwise run unprotected and log a warning. */
+    /** A public endpoint. Tools declaring security annotations fail the boot. */
    AUTO,
    /** Never protect the endpoint, even if {@code flash-ext-oidc} is installed elsewhere in the app. */
    NONE
 }
@@ -19,7 +19,7 @@ final class McpTransportGuards {
     * allowed through — only a <em>present but disallowed</em> value is rejected.
     *
     * <p>If {@code allowedOrigins} is empty, validation is skipped and a boot-time warning is
-     * logged — same graceful-degradation shape as {@link McpSecurity#AUTO}.
+     * logged.
     */
    static Middleware originGuard(List<String> allowedOrigins) {
        if (allowedOrigins.isEmpty()) {
@@ -38,7 +38,7 @@ final class McpTransportGuards {
    /**
     * Safety net around the whole MCP route: translates {@link HttpException} (thrown by
-     * {@link #originGuard} or by {@code flash-ext-oidc}'s middleware) into a proper HTTP status
+     * {@link #originGuard} or by {@code flash-ext-security-core}) into a proper HTTP status
     * directly, instead of relying on the app's global exception handler — which defaults to a
     * generic 500 for every exception type unless the app owner overrides it (see
     * {@code AbstractRouter}'s default {@code exceptionHandler}). Keeps the MCP endpoint
@@ -1,109 +0,0 @@
 package dev.relism.flash.ext.mcp;
 import com.nimbusds.jose.JWSAlgorithm;
 import com.nimbusds.jose.JWSHeader;
 import com.nimbusds.jose.crypto.RSASSASigner;
 import com.nimbusds.jose.jwk.JWKSet;
 import com.nimbusds.jose.jwk.KeyUse;
 import com.nimbusds.jose.jwk.RSAKey;
 import com.nimbusds.jwt.JWTClaimsSet;
 import com.nimbusds.jwt.SignedJWT;
 import com.sun.net.httpserver.HttpServer;
 import java.io.OutputStream;
 import java.net.InetSocketAddress;
 import java.nio.charset.StandardCharsets;
 import java.security.KeyPair;
 import java.security.KeyPairGenerator;
 import java.security.interfaces.RSAPrivateKey;
 import java.security.interfaces.RSAPublicKey;
 import java.time.Instant;
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 /**
 * Minimal, self-contained fake OIDC provider for tests: real discovery document, real JWKS
 * endpoint, real RS256-signed tokens — no network dependency beyond localhost, no mocking
 * framework. Exercises {@code flash-ext-oidc}'s actual discovery + JWKS + JWT validation path.
 */
 final class FakeOidcProvider implements AutoCloseable {
    private final HttpServer server;
    private final String issuer;
    private final RSAKey rsaKey;
    FakeOidcProvider() throws Exception {
        KeyPairGenerator gen = KeyPairGenerator.getInstance("RSA");
        gen.initialize(2048);
        KeyPair kp = gen.generateKeyPair();
        this.rsaKey = new RSAKey.Builder((RSAPublicKey) kp.getPublic())
                .privateKey((RSAPrivateKey) kp.getPrivate())
                .keyUse(KeyUse.SIGNATURE)
                .algorithm(JWSAlgorithm.RS256)
                .keyID(UUID.randomUUID().toString())
                .build();
        this.server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        this.issuer = "http://127.0.0.1:" + server.getAddress().getPort();
        server.createContext("/.well-known/openid-configuration", ex -> respond(ex, discoveryDocument()));
        server.createContext("/jwks", ex -> respond(ex, new JWKSet(rsaKey.toPublicJWK()).toJSONObject().toString()));
        server.setExecutor(null);
        server.start();
    }
    String issuer() { return issuer; }
    /** Mints a valid RS256 access token — bearer-validation only, no full authorization-code round-trip needed. */
    String signToken(String subject, String audience) {
        return signToken(subject, audience, null, NO_ROLES);
    }
    /**
     * Same as {@link #signToken(String, String)}, plus a {@code scope} claim (space-delimited,
     * matching {@link dev.relism.flash.ext.oidc.OidcUser#hasScope}'s default claim path) and a
     * Keycloak-shaped {@code realm_access.roles} claim (matching {@code McpConfig}'s default
     * {@code rolesClaimPath}) when {@code roles} is non-empty.
     */
    String signToken(String subject, String audience, String scope, String... roles) {
        try {
            JWTClaimsSet.Builder builder = new JWTClaimsSet.Builder()
                    .issuer(issuer)
                    .subject(subject)
                    .audience(audience)
                    .issueTime(Date.from(Instant.now()))
                    .expirationTime(Date.from(Instant.now().plusSeconds(300)));
            if (scope != null) builder.claim("scope", scope);
            if (roles.length > 0) builder.claim("realm_access", Map.of("roles", List.of(roles)));
            SignedJWT jwt = new SignedJWT(
                    new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaKey.getKeyID()).build(), builder.build());
            jwt.sign(new RSASSASigner(rsaKey));
            return jwt.serialize();
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }
    private static final String[] NO_ROLES = new String[0];
    private String discoveryDocument() {
        return "{"
                + "\"issuer\":\"" + issuer + "\","
                + "\"authorization_endpoint\":\"" + issuer + "/auth\","
                + "\"token_endpoint\":\"" + issuer + "/token\","
                + "\"jwks_uri\":\"" + issuer + "/jwks\""
                + "}";
    }
    private static void respond(com.sun.net.httpserver.HttpExchange ex, String body) throws java.io.IOException {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        ex.getResponseHeaders().add("Content-Type", "application/json");
        ex.sendResponseHeaders(200, bytes.length);
        try (OutputStream os = ex.getResponseBody()) { os.write(bytes); }
    }
    @Override
    public void close() { server.stop(0); }
 }
@@ -1,150 +0,0 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.ext.oidc.OidcConfig;
 import dev.relism.flash.ext.oidc.OidcExtension;
 import dev.relism.flash.extension.FlashApp;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import java.net.ServerSocket;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 /**
 * {@code @RolesAllowed}/{@code @ScopesAllowed} on an {@link McpTool} — see
 * {@link McpOidcIntegration#compileToolPolicy}. Same real-discovery/real-JWKS/real-RS256-token
 * approach as {@link McpExtensionSecurityTest}, against {@code fixtures.secured}'s tools.
 */
 class McpAuthPolicyTest {
    private static final String SECURED_TOOLS = "dev.relism.flash.ext.mcp.authfixtures.secured";
    private static final String AUTHENTICATED_ONLY_TOOLS = "dev.relism.flash.ext.mcp.authfixtures.authenticatedonly";
    private FlashApp app;
    private FakeOidcProvider provider;
    @AfterEach
    void tearDown() {
        if (app != null) app.stop();
        if (provider != null) provider.close();
    }
    @Test
    void rolesAllowed_deniesWithoutRole_allowsWithRole() throws Exception {
        int port = bootSecuredApp(SECURED_TOOLS);
        String resourceId = "http://127.0.0.1:" + port + "/mcp";
        String noRole = provider.signToken("user-1", resourceId, null);
        HttpResponse<String> denied = callTool(port, "admin_only", noRole);
        assertEquals(200, denied.statusCode());
        assertTrue(denied.body().contains("\"isError\":true"), denied.body());
        assertTrue(denied.body().contains("missing required role"), denied.body());
        String withRole = provider.signToken("user-1", resourceId, null, "admin");
        HttpResponse<String> allowed = callTool(port, "admin_only", withRole);
        assertEquals(200, allowed.statusCode());
        assertTrue(allowed.body().contains("\"isError\":false"), allowed.body());
        assertTrue(allowed.body().contains("ok"), allowed.body());
    }
    @Test
    void scopesAllowed_deniesWithoutScope_allowsWithScope() throws Exception {
        int port = bootSecuredApp(SECURED_TOOLS);
        String resourceId = "http://127.0.0.1:" + port + "/mcp";
        String noScope = provider.signToken("user-1", resourceId, "read");
        HttpResponse<String> denied = callTool(port, "write_only", noScope);
        assertEquals(200, denied.statusCode());
        assertTrue(denied.body().contains("\"isError\":true"), denied.body());
        assertTrue(denied.body().contains("missing required scope"), denied.body());
        String withScope = provider.signToken("user-1", resourceId, "read write");
        HttpResponse<String> allowed = callTool(port, "write_only", withScope);
        assertEquals(200, allowed.statusCode());
        assertTrue(allowed.body().contains("\"isError\":false"), allowed.body());
        assertTrue(allowed.body().contains("written"), allowed.body());
    }
    @Test
    void unannotatedTool_unaffectedByOtherToolsPolicies() throws Exception {
        int port = bootSecuredApp(SECURED_TOOLS);
        String resourceId = "http://127.0.0.1:" + port + "/mcp";
        String plain = provider.signToken("user-1", resourceId, null);
        HttpResponse<String> resp = callTool(port, "open", plain);
        assertEquals(200, resp.statusCode());
        assertTrue(resp.body().contains("\"isError\":false"), resp.body());
        assertTrue(resp.body().contains("open"), resp.body());
    }
    @Test
    void toolAnnotated_butSecurityNone_failsAtBoot() throws Exception {
        provider = new FakeOidcProvider();
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new OidcExtension(OidcConfig.builder(
                provider.issuer(), "mcp-client", "secret", "/auth/callback").build()));
        app.install(new McpExtension(McpConfig.builder("secure-server")
                .toolsPackage(SECURED_TOOLS)
                .security(McpSecurity.NONE)
                .build()));
        IllegalStateException e = assertThrows(IllegalStateException.class, () -> app.start());
        assertTrue(e.getMessage().contains("no active OAuth2 protection"), e.getMessage());
    }
    @Test
    void bareAuthenticated_hasNoEffect_failsAtBoot() throws Exception {
        provider = new FakeOidcProvider();
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new OidcExtension(OidcConfig.builder(
                provider.issuer(), "mcp-client", "secret", "/auth/callback").build()));
        app.install(new McpExtension(McpConfig.builder("secure-server")
                .toolsPackage(AUTHENTICATED_ONLY_TOOLS)
                .security(McpSecurity.REQUIRED)
                .build()));
        IllegalStateException e = assertThrows(IllegalStateException.class, () -> app.start());
        assertTrue(e.getMessage().contains("no effect"), e.getMessage());
    }
    // ── Helpers ──────────────────────────────────────────────────────────────
    private int bootSecuredApp(String toolsPackage) throws Exception {
        provider = new FakeOidcProvider();
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new OidcExtension(OidcConfig.builder(
                provider.issuer(), "mcp-client", "secret", "/auth/callback").build()));
        app.install(new McpExtension(McpConfig.builder("secure-server")
                .toolsPackage(toolsPackage)
                .security(McpSecurity.REQUIRED)
                .build()));
        app.start();
        return port;
    }
    private static HttpResponse<String> callTool(int port, String toolName, String token) throws Exception {
        String body = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"" + toolName + "\"}}";
        HttpRequest.Builder req = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + "/mcp"))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .header("Authorization", "Bearer " + token)
                .POST(HttpRequest.BodyPublishers.ofString(body));
        return HttpClient.newHttpClient().send(req.build(), HttpResponse.BodyHandlers.ofString());
    }
    private static int freePort() throws Exception {
        try (ServerSocket s = new ServerSocket(0)) {
            return s.getLocalPort();
        }
    }
 }
@@ -0,0 +1,61 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.testing.FlashTest;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import java.util.concurrent.atomic.AtomicInteger;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 /**
 * Application middleware on the MCP route. Until this existed a consumer had no way to put rate
 * limiting, audit logging or tracing in front of {@code /mcp} — the chain was assembled entirely
 * inside the extension.
 */
 class McpConfigMiddlewareTest {
    private static final AtomicInteger CALLS = new AtomicInteger();
    @RegisterExtension
    static FlashTest mcp = FlashTest.of(app -> app.install(new McpExtension(
            McpConfig.builder("middleware-server")
                    .version("1.0.0")
                    .toolsPackage("dev.relism.flash.ext.mcp.fixtures")
                    .security(McpSecurity.NONE)
                    .middleware(
                            next -> (req, res) -> {
                                CALLS.incrementAndGet();
                                return next.handle(req, res);
                            },
                            next -> (req, res) -> {
                                if ("deny".equals(req.header("X-Test-Gate"))) throw HttpException.forbidden();
                                return next.handle(req, res);
                            })
                    .build())));
    @Test
    void appMiddlewareRunsOnTheMcpRoute() {
        int before = CALLS.get();
        mcp.request()
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}")
                .post("/mcp")
                .expectStatus(200);
        assertEquals(before + 1, CALLS.get());
    }
    /**
     * The point of the hook: with {@link McpSecurity#NONE}, an app's own guard is the only thing
     * in front of the endpoint — which is how an app that does not authenticate with OAuth2
     * protects {@code /mcp} at all.
     */
    @Test
    void appMiddlewareCanRejectTheRequest() {
        mcp.request()
                .header("X-Test-Gate", "deny")
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}")
                .post("/mcp")
                .expectStatus(403);
    }
 }
@@ -2,16 +2,10 @@ package dev.relism.flash.ext.mcp;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import dev.relism.flash.extension.FlashApp;
+import dev.relism.flash.testing.FlashResponse;
-import org.junit.jupiter.api.AfterEach;
+import dev.relism.flash.testing.FlashTest;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
-
+import org.junit.jupiter.api.extension.RegisterExtension;
 import java.net.ServerSocket;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -22,34 +16,15 @@ class McpExtensionIntegrationTest {
    private static final ObjectMapper MAPPER = new ObjectMapper();
-    private FlashApp app;
+    // Every test here is a stateless JSON-RPC call against the same server, so one boot for
-    private String mcpUrl;
+    // the class rather than one per test.
-    private HttpClient client;
+    @RegisterExtension
-
+    static FlashTest mcp = FlashTest.of(app -> app.install(new McpExtension(
-    @BeforeEach
+            McpConfig.builder("test-server")
-    void setUp() throws Exception {
+                    .version("9.9.9")
-        int port;
+                    .toolsPackage("dev.relism.flash.ext.mcp.fixtures")
-        try (ServerSocket s = new ServerSocket(0)) {
+                    .security(McpSecurity.NONE)
-            port = s.getLocalPort();
+                    .build())));
        }
        mcpUrl = "http://127.0.0.1:" + port + "/mcp";
        client = HttpClient.newHttpClient();
        McpConfig config = McpConfig.builder("test-server")
                .version("9.9.9")
                .toolsPackage("dev.relism.flash.ext.mcp.fixtures")
                .security(McpSecurity.NONE)
                .build();
        app = FlashApp.create(port);
        app.install(new McpExtension(config));
        app.start();
    }
    @AfterEach
    void tearDown() {
        if (app != null) app.stop();
    }
    @Test
    void initialize_returnsProtocolVersionCapabilitiesAndServerInfo() throws Exception {
@@ -104,17 +79,13 @@ class McpExtensionIntegrationTest {
    }
    @Test
-    void notification_returns202WithEmptyBody() throws Exception {
+    void notification_returns202WithEmptyBody() {
-        String body = "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}";
+        post("{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}").expectStatus(202);
        HttpResponse<String> resp = post(body);
        assertEquals(202, resp.statusCode());
    }
    @Test
    void malformedJson_returns400ParseError() throws Exception {
-        HttpResponse<String> resp = post("not json");
+        JsonNode json = MAPPER.readTree(post("not json").expectStatus(400).body());
        assertEquals(400, resp.statusCode());
        JsonNode json = MAPPER.readTree(resp.body());
        assertEquals(-32700, json.get("error").get("code").asInt());
    }
@@ -128,16 +99,10 @@ class McpExtensionIntegrationTest {
    private JsonNode call(int id, String method, String paramsJson) throws Exception {
        String body = "{\"jsonrpc\":\"2.0\",\"id\":" + id + ",\"method\":\"" + method + "\",\"params\":" + paramsJson + "}";
-        HttpResponse<String> resp = post(body);
+        return MAPPER.readTree(post(body).expectStatus(200).body());
        assertEquals(200, resp.statusCode());
        return MAPPER.readTree(resp.body());
    }
-    private HttpResponse<String> post(String body) throws Exception {
+    private FlashResponse post(String body) {
-        HttpRequest req = HttpRequest.newBuilder(URI.create(mcpUrl))
+        return mcp.request().json(body).post("/mcp");
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
        return client.send(req, HttpResponse.BodyHandlers.ofString());
    }
 }
@@ -1,194 +0,0 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.ext.oidc.OidcConfig;
 import dev.relism.flash.ext.oidc.OidcExtension;
 import dev.relism.flash.extension.FlashApp;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import java.net.ServerSocket;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 /**
 * Exercises the actual OAuth2 resolution rules against a real {@code flash-ext-oidc}
 * installation backed by {@link FakeOidcProvider} — real discovery, real JWKS, real RS256
 * tokens — plus the fail-fast/degrade behavior when oidc is absent.
 */
 class McpExtensionSecurityTest {
    private static final String TOOLS_PACKAGE = "dev.relism.flash.ext.mcp.fixtures";
    private FlashApp app;
    private FakeOidcProvider provider;
    @AfterEach
    void tearDown() {
        if (app != null) app.stop();
        if (provider != null) provider.close();
    }
    @Test
    void required_withoutOidc_throwsAtBoot() throws Exception {
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new McpExtension(McpConfig.builder("secure-server")
                .toolsPackage(TOOLS_PACKAGE)
                .security(McpSecurity.REQUIRED)
                .build()));
        assertThrows(IllegalStateException.class, () -> app.start());
    }
    @Test
    void auto_withoutOidc_degradesToPublic() throws Exception {
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new McpExtension(McpConfig.builder("auto-server")
                .toolsPackage(TOOLS_PACKAGE)
                .security(McpSecurity.AUTO)
                .build()));
        app.start();
        HttpResponse<String> resp = post(port, initializeBody(), null);
        assertEquals(200, resp.statusCode());
    }
    @Test
    void required_withOidc_rejectsMissingToken() throws Exception {
        int port = bootSecuredApp(null);
        HttpResponse<String> resp = post(port, initializeBody(), null);
        assertEquals(401, resp.statusCode());
    }
    @Test
    void required_withOidc_rejectsWrongAudience() throws Exception {
        int port = bootSecuredApp("https://mcp.example.com/mcp");
        String token = provider.signToken("user-1", "https://someone-else.example.com/resource");
        HttpResponse<String> resp = post(port, initializeBody(), token);
        assertEquals(403, resp.statusCode());
    }
    @Test
    void required_withOidc_acceptsValidAudience() throws Exception {
        String resourceId = "https://mcp.example.com/mcp";
        int port = bootSecuredApp(resourceId);
        String token = provider.signToken("user-1", resourceId);
        HttpResponse<String> resp = post(port, initializeBody(), token);
        assertEquals(200, resp.statusCode());
        assertTrue(resp.body().contains("\"protocolVersion\""));
    }
    @Test
    void required_withOidc_noExplicitResourceIdentifier_derivesFromRequestAndEnforcesAudience() throws Exception {
        int port = bootSecuredApp(null);
        String derivedResourceId = "http://127.0.0.1:" + port + "/mcp";
        String matching = provider.signToken("user-1", derivedResourceId);
        assertEquals(200, post(port, initializeBody(), matching).statusCode());
        String mismatched = provider.signToken("user-1", "https://someone-else.example.com/resource");
        assertEquals(403, post(port, initializeBody(), mismatched).statusCode());
    }
    @Test
    void required_withOidc_missingToken_challengeIncludesResourceMetadata() throws Exception {
        int port = bootSecuredApp(null);
        HttpResponse<String> resp = post(port, initializeBody(), null);
        assertEquals(401, resp.statusCode());
        String challenge = resp.headers().firstValue("WWW-Authenticate").orElse("");
        assertTrue(challenge.contains(
                "resource_metadata=\"http://127.0.0.1:" + port + "/.well-known/oauth-protected-resource/mcp\""),
                "WWW-Authenticate: " + challenge);
    }
    @Test
    void required_withOidc_noExplicitConfig_publishesProtectedResourceMetadata() throws Exception {
        int port = bootSecuredApp(null);
        HttpResponse<String> resp = HttpClient.newHttpClient().send(
                HttpRequest.newBuilder(URI.create(
                        "http://127.0.0.1:" + port + "/.well-known/oauth-protected-resource/mcp")).GET().build(),
                HttpResponse.BodyHandlers.ofString());
        assertEquals(200, resp.statusCode());
        assertTrue(resp.body().contains("\"resource\":\"http://127.0.0.1:" + port + "/mcp\""), resp.body());
        assertTrue(resp.body().contains("\"authorization_servers\":[\"" + provider.issuer() + "\"]"), resp.body());
        assertTrue(!resp.body().contains("scopes_supported"), "scopes_supported must be omitted when unset: " + resp.body());
    }
    @Test
    void scopesSupported_published_inProtectedResourceMetadata() throws Exception {
        provider = new FakeOidcProvider();
        int port = freePort();
        app = FlashApp.create(port);
        app.install(new OidcExtension(OidcConfig.builder(
                provider.issuer(), "mcp-client", "secret", "/auth/callback").build()));
        app.install(new McpExtension(McpConfig.builder("secure-server")
                .toolsPackage(TOOLS_PACKAGE)
                .security(McpSecurity.REQUIRED)
                .scopesSupported("openid", "profile", "email")
                .build()));
        app.start();
        HttpResponse<String> resp = HttpClient.newHttpClient().send(
                HttpRequest.newBuilder(URI.create(
                        "http://127.0.0.1:" + port + "/.well-known/oauth-protected-resource/mcp")).GET().build(),
                HttpResponse.BodyHandlers.ofString());
        assertEquals(200, resp.statusCode());
        assertTrue(resp.body().contains("\"scopes_supported\":[\"openid\",\"profile\",\"email\"]"), resp.body());
    }
    // ── Helpers ──────────────────────────────────────────────────────────────
    private int bootSecuredApp(String resourceIdentifier) throws Exception {
        provider = new FakeOidcProvider();
        int port = freePort();
        OidcConfig oidcConfig = OidcConfig.builder(
                        provider.issuer(), "mcp-client", "secret", "/auth/callback")
                .build();
        var mcpBuilder = McpConfig.builder("secure-server")
                .toolsPackage(TOOLS_PACKAGE)
                .security(McpSecurity.REQUIRED);
        if (resourceIdentifier != null) mcpBuilder.resourceIdentifier(resourceIdentifier);
        app = FlashApp.create(port);
        app.install(new OidcExtension(oidcConfig));
        app.install(new McpExtension(mcpBuilder.build()));
        app.start();
        return port;
    }
    private static String initializeBody() {
        return "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}";
    }
    private static int freePort() throws Exception {
        try (ServerSocket s = new ServerSocket(0)) {
            return s.getLocalPort();
        }
    }
    private static HttpResponse<String> post(int port, String body, String bearerToken) throws Exception {
        HttpRequest.Builder req = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + "/mcp"))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body));
        if (bearerToken != null) req.header("Authorization", "Bearer " + bearerToken);
        return HttpClient.newHttpClient().send(req.build(), HttpResponse.BodyHandlers.ofString());
    }
 }
@@ -16,7 +16,7 @@ class McpRegistryTest {
    @Test
    void scan_findsAndPrecompilesToolsResourcesPrompts() throws Exception {
-        McpRegistry registry = McpRegistry.scan("dev.relism.flash.ext.mcp.fixtures", new FlashContext(), false, "realm_access.roles");
+        McpRegistry registry = McpRegistry.scan("dev.relism.flash.ext.mcp.fixtures", new FlashContext(), null);
        assertTrue(registry.hasTools());
        assertTrue(registry.hasResources());
@@ -47,7 +47,7 @@ class McpRegistryTest {
    @Test
    void scan_emptyPackage_throwsInitializationException() {
        assertThrows(InitializationException.class,
-                () -> McpRegistry.scan("dev.relism.flash.ext.mcp.doesnotexist", new FlashContext(), false, "realm_access.roles"));
+                () -> McpRegistry.scan("dev.relism.flash.ext.mcp.doesnotexist", new FlashContext(), null));
    }
    private static JsonNode findByField(JsonNode array, String field, String value) {
@@ -0,0 +1,157 @@
 package dev.relism.flash.ext.mcp;
 import dev.relism.flash.ext.security.AuthenticationMechanism;
 import dev.relism.flash.ext.security.Principal;
 import dev.relism.flash.ext.security.SecurityExtension;
 import dev.relism.flash.ext.security.SecurityScheme;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.ext.security.apikey.ApiKey;
 import dev.relism.flash.ext.security.apikey.ApiKeyExtension;
 import dev.relism.flash.ext.security.apikey.GeneratedApiKey;
 import dev.relism.flash.ext.security.oidc.OidcExtension;
 import dev.relism.flash.ext.security.oidc.OidcProvider;
 import dev.relism.flash.ext.security.test.FakeOidcProvider;
 import dev.relism.flash.testing.FlashRequest;
 import dev.relism.flash.testing.FlashResponse;
 import dev.relism.flash.testing.FlashTest;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Consumer;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 class McpSecurityTest {
    static final FakeOidcProvider provider = start();
    static final GeneratedApiKey KEY = new ApiKeyExtension<String>("mk", id -> null).generate();
    static final ApiKeyExtension<String> apiKeys = new ApiKeyExtension<>("mk", id -> id.equals(KEY.id()) ? new ApiKey<>(KEY.id(), KEY.secretHash(), "agent", null, null) : null);
    @RegisterExtension
    static final FlashTest app = FlashTest.of(flash -> flash
            .install(new SecurityExtension().roles((identity, role, on) -> identity.principal().name().equals(role + "@" + on.get("project"))))
            .install(new OidcExtension(OidcProvider.of("fake", provider.issuer(), "app", "secret")))
            .install(apiKeys)
            .install(new McpExtension(McpConfig.builder("secure").toolsPackage("dev.relism.flash.ext.mcp.authfixtures.secured")
                    .scopesSupported("openid", "email").build())));
    static final OidcExtension oidc = new OidcExtension(OidcProvider.of("fake", provider.issuer(), "app", "secret"));
    /** Another issuer the application trusts, which the restricted endpoint below must neither accept nor advertise. */
    static final AuthenticationMechanism elsewhere = new AuthenticationMechanism() {
        @Override public Principal authenticate(Request req) {
            return "Other".equals(req.header("Authorization")) ? () -> "other" : null;
        }
        @Override public List<SecurityScheme> schemes() {
            return List.of(SecurityScheme.openIdConnect("other", "https://other.example"));
        }
    };
    /** Only the OIDC provider authenticates this endpoint, however many mechanisms the application has. */
    @RegisterExtension
    static final FlashTest restricted = FlashTest.of(flash -> flash
            .install(new SecurityExtension().mechanism(elsewhere))
            .install(oidc)
            .install(apiKeys)
            .install(new McpExtension(McpConfig.builder("restricted").toolsPackage("dev.relism.flash.ext.mcp.fixtures")
                    .mechanisms(oidc).requireTokenAudience(false).build())));
    /** The same chain with the RFC 8707 check turned off, for an authorization server that cannot mint a resource audience. */
    @RegisterExtension
    static final FlashTest relaxed = FlashTest.of(flash -> flash
            .install(new SecurityExtension().roles((identity, role, on) -> false))
            .install(new OidcExtension(OidcProvider.of("fake", provider.issuer(), "app", "secret")))
            .install(new McpExtension(McpConfig.builder("relaxed").toolsPackage("dev.relism.flash.ext.mcp.authfixtures.secured")
                    .requireTokenAudience(false).build())));
    static FakeOidcProvider start() {
        try {
            return new FakeOidcProvider();
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }
    static String resource() {
        return "http://127.0.0.1:" + app.port() + "/mcp";
    }
    static FlashResponse call(Consumer<FlashRequest> credential, String method, String params) {
        return app.request().with(credential).header("Accept", "application/json")
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"" + method + "\",\"params\":" + params + "}")
                .post("/mcp");
    }
    @Test
    void anAnonymousCallIsChallengedWithTheResourceMetadata() {
        call(request -> {}, "initialize", "{}").expectStatus(401)
                .expectHeader("WWW-Authenticate", "Bearer resource_metadata=\"http://127.0.0.1:" + app.port() + "/.well-known/oauth-protected-resource/mcp\"");
    }
    @Test
    void theProtectedResourceMetadataNamesTheIssuer() {
        app.get("/.well-known/oauth-protected-resource/mcp").expectStatus(200)
                .expectBody("{\"resource\":\"" + resource() + "\",\"authorization_servers\":[\"" + provider.issuer() + "\"],\"scopes_supported\":[\"openid\",\"email\"]}");
    }
    @Test
    void aTokenIsAcceptedOnlyForThisResource() {
        call(provider.bearer("u", Map.of("aud", resource())), "initialize", "{}").expectStatus(200).expectBodyContains("protocolVersion");
        call(provider.bearer("u", Map.of("aud", "https://elsewhere.example/mcp")), "initialize", "{}").expectStatus(403);
    }
    @Test
    void aTokenWithoutTheResourceAudienceIsAcceptedWhenTheCheckIsOff() {
        relaxed.request().with(provider.bearer("u", Map.of("aud", "https://elsewhere.example/mcp"))).header("Accept", "application/json")
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}")
                .post("/mcp").expectStatus(200).expectBodyContains("protocolVersion");
    }
    /** The resource is the application's own origin: a forwarded header naming another host cannot make its tokens good here. */
    @Test
    void aForwardedHostCannotChooseTheResource() {
        app.request().with(provider.bearer("u", Map.of("aud", "https://evil.example/mcp")))
                .header("X-Forwarded-Proto", "https").header("X-Forwarded-Host", "evil.example").header("Accept", "application/json")
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}").post("/mcp").expectStatus(403);
    }
    @Test
    void anEndpointRestrictedToSomeMechanismsAcceptsAndAdvertisesOnlyThem() {
        restricted.get("/.well-known/oauth-protected-resource/mcp").expectStatus(200)
                .expectBody("{\"resource\":\"http://127.0.0.1:" + restricted.port() + "/mcp\",\"authorization_servers\":[\"" + provider.issuer() + "\"]}");
        Consumer<FlashRequest> key = request -> request.header("Authorization", "Bearer " + KEY.token());
        Consumer<FlashRequest> other = request -> request.header("Authorization", "Other");
        for (Consumer<FlashRequest> refused : List.of(key, other)) {
            restricted.request().with(refused).header("Accept", "application/json")
                    .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}").post("/mcp").expectStatus(401);
        }
        restricted.request().with(provider.bearer("u", Map.of())).header("Accept", "application/json")
                .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}").post("/mcp").expectStatus(200);
    }
    /** An API key is not audience-bound: the same chain authenticates agents that never saw an authorization server. */
    @Test
    void anApiKeyIsAcceptedBesideOAuth() {
        call(request -> request.header("Authorization", "Bearer " + KEY.token()), "initialize", "{}").expectStatus(200);
    }
    @Test
    void toolPoliciesReadTheirTargetFromTheArguments() {
        Consumer<FlashRequest> admin = provider.bearer("admin@42", Map.of("aud", resource()));
        call(admin, "tools/call", "{\"name\":\"admin_only\",\"arguments\":{\"project\":\"42\"}}").expectBodyContains("\"isError\":false");
        call(admin, "tools/call", "{\"name\":\"admin_only\",\"arguments\":{\"project\":\"7\"}}").expectBodyContains("denied: missing role");
        call(provider.bearer("u", Map.of("aud", resource(), "scope", "write")), "tools/call", "{\"name\":\"write_only\"}").expectBodyContains("written");
        call(provider.bearer("u", Map.of("aud", resource())), "tools/call", "{\"name\":\"write_only\"}").expectBodyContains("denied: missing scope");
    }
    @Test
    void securityIsRequiredUnlessDeclaredOff() {
        FlashTest unsecured = FlashTest.of(flash -> flash.install(new McpExtension(McpConfig.builder("x").toolsPackage("dev.relism.flash.ext.mcp.fixtures").build())));
        assertThrows(Exception.class, () -> unsecured.get("/mcp"));
        FlashTest contradictory = FlashTest.of(flash -> flash.install(new McpExtension(McpConfig.builder("x")
                .toolsPackage("dev.relism.flash.ext.mcp.authfixtures.secured").security(McpSecurity.NONE).build())));
        assertThrows(Exception.class, () -> contradictory.get("/mcp"));
    }
 }
@@ -1,20 +0,0 @@
 package dev.relism.flash.ext.mcp.authfixtures.authenticatedonly;
 import dev.relism.flash.ext.mcp.McpTool;
 import dev.relism.flash.ext.mcp.TextContent;
 import dev.relism.flash.ext.mcp.Tool;
 import dev.relism.flash.ext.mcp.ToolArguments;
 import dev.relism.flash.ext.mcp.ToolResponse;
 import dev.relism.flash.ext.oidc.Authenticated;
 /** Deliberately misconfigured fixture: bare @Authenticated has no effect on an McpTool — see
 *  McpOidcIntegration#compileToolPolicy. Boot must fail with a clear message, not silently no-op. */
@Tool(name = "pointless", description = "Exists only to prove @Authenticated alone fails boot")
@Authenticated
 public class PointlessAuthTool extends McpTool {
    @Override
    public ToolResponse call(ToolArguments args) {
        return ToolResponse.success(new TextContent("unreachable"));
    }
 }
@@ -5,10 +5,10 @@ import dev.relism.flash.ext.mcp.TextContent;
 import dev.relism.flash.ext.mcp.Tool;
 import dev.relism.flash.ext.mcp.ToolArguments;
 import dev.relism.flash.ext.mcp.ToolResponse;
-import dev.relism.flash.ext.oidc.RolesAllowed;
+import dev.relism.flash.ext.security.RolesAllowed;
@Tool(name = "admin_only", description = "Only callable with the admin role")
-@RolesAllowed("admin")
+@RolesAllowed(value = "admin", on = "project")
 public class AdminOnlyTool extends McpTool {
    @Override
@@ -5,7 +5,7 @@ import dev.relism.flash.ext.mcp.TextContent;
 import dev.relism.flash.ext.mcp.Tool;
 import dev.relism.flash.ext.mcp.ToolArguments;
 import dev.relism.flash.ext.mcp.ToolResponse;
-import dev.relism.flash.ext.oidc.ScopesAllowed;
+import dev.relism.flash.ext.security.ScopesAllowed;
@Tool(name = "write_only", description = "Only callable with the write scope")
@ScopesAllowed("write")
@@ -1,462 +0,0 @@
 # flash-ext-oidc
 Full OIDC Authorization Code + PKCE flow for the Flash HTTP server.
 Supports Keycloak, Authelia, Auth0, Google, and any RFC 8414-compliant provider.
 Standards alignment focuses on OIDC Core + OAuth2 bearer APIs while preserving Flash's
 hot-path model (middleware compiled at mount time, no heavy runtime work).
 ## What it provides
 | Component | Description |
 |---|---|
 | `GET  {prefix}/login` | Starts the OIDC flow: builds the authorization URL with PKCE + state, redirects |
 | `GET  {prefix}/callback` | Exchanges the code, validates the ID token, creates a session, redirects |
 | `POST {prefix}/logout` | Invalidates the session, redirects to the provider's `end_session_endpoint` |
 | `@Authenticated` | Annotation: protects a class-based handler (redirects browsers, 401 for API clients) |
 | `@RolesAllowed(...)` | Annotation: protects with role check (OR semantics) |
 | `@ScopesAllowed(...)` | Annotation: protects with scope check (`ALL` default, `ANY` optional) |
 | `OidcMiddleware` | Programmatic middleware for lambda routes |
 | `ClaimsHolder` / `OidcUser` | Thread-local user info accessible from any protected handler |
 | `JwtValidator` | JWKS-backed JWT validator (PKCE + key rotation + caching) |
 ## Dependencies
 ```xml
 <dependency>
    <groupId>dev.relism</groupId>
    <artifactId>flash-ext-oidc</artifactId>
    <version>1.0-SNAPSHOT</version>
 </dependency>
 ```
 Transitive: `nimbus-jose-jwt`, `json-smart`.
 Optional: `flash-ext-openapi` — if present, OIDC security schemes are added to the OpenAPI spec automatically.
 ## Installation
 ```java
 FlashApp.create(8080)
    .install(new JacksonExtension())
    .install(new OpenApiExtension(...))   // optional — enables Swagger security
    .install(new OidcExtension(
        OidcConfig.builder(
                "https://idp.example.com",
                "my-client", "my-secret", "/auth/callback")
            .build()
    ))
    .start();
 ```
 Install order is irrelevant. The two-phase extension model guarantees all services
 (including `OpenApiSecurityRegistry` from `flash-ext-openapi`) are registered before
 any extension's routes phase runs.
 ### Keycloak shortcut
 ```java
 OidcConfig.keycloak(
        "https://keycloak.example.com",   // server URL (no realm)
        "myrealm",                         // realm
        "my-client", "my-secret",          // client credentials
        "/auth/callback")                  // redirect URI (server-relative)
    .https()                               // behind TLS
    .build()
 ```
 `keycloak()` pre-sets `rolesClaimPath("realm_access.roles")` and constructs the issuer as
 `{serverUrl}/realms/{realm}`.
 ### Authelia / generic IdP
 ```java
 OidcConfig.builder("https://auth.example.com", "my-client", "secret", "/auth/callback")
    .rolesClaimPath("groups")
    .build()
 ```
 ## OidcConfig reference
 ### Required fields
 | Field | Description |
 |---|---|
 | `issuer` | Provider base URL — also used for OIDC discovery |
 | `clientId` | OAuth2 client ID |
 | `clientSecret` | OAuth2 client secret |
 | `redirectUri` | Callback URI; server-relative paths (starting with `/`) are resolved at request time |
 ### Builder options
 | Method | Default | Description |
 |---|---|---|
 | `.scopes("openid profile email")` | `"openid profile email"` | Space-separated requested scopes |
 | `.routePrefix("/auth")` | `"/auth"` | Prefix for login/callback/logout routes |
 | `.selfScheme("http")` | `"http"` | Scheme used when resolving server-relative redirect URIs |
 | `.https()` | — | Shorthand for `.selfScheme("https")` |
 | `.rolesClaimPath("realm_access.roles")` | `"realm_access.roles"` | Dot-path to the roles array in JWT claims |
 | `.scopeClaimPaths("scope,scp")` | `"scope,scp"` | Comma-separated claim paths used to resolve OAuth scopes |
 | `.algorithm("RS256")` | `"RS256"` | JWS algorithm for token validation |
 | `.postLogoutRedirectUri("/")` | `"/"` | Where to redirect after logout |
 | `.sessionStore(store)` | `InMemoryOidcSessionStore` | Custom session store (see below) |
 | `.clientAuthMethod(ClientAuthMethod.POST)` | `POST` | `POST` = credentials in body; `BASIC` = `Authorization: Basic` |
 | `.insecureTls()` | `false` | Disables TLS certificate verification — **development only** |
 | `.schemeName("myscheme")` | derived from issuer | OpenAPI security scheme name |
 ### Environment variables (`OidcConfig.fromEnv()`)
 ```
 OIDC_ISSUER                required
 OIDC_CLIENT_ID             required
 OIDC_CLIENT_SECRET         required
 OIDC_REDIRECT_URI          required   e.g. /auth/callback
 OIDC_SCOPES                default: openid profile email
 OIDC_ROUTE_PREFIX          default: /auth
 OIDC_SELF_SCHEME           default: http
 OIDC_ROLES_CLAIM           default: realm_access.roles
 OIDC_SCOPE_CLAIMS          default: scope,scp
 OIDC_ALGORITHM             default: RS256
 OIDC_POST_LOGOUT_REDIRECT  default: /
 OIDC_CLIENT_AUTH_METHOD    default: POST
 ```
 ## Protecting routes
 ### Class-based handlers (annotations)
 ```java
@Route(method = HttpMethod.GET, path = "/me")
@Authenticated
 public class MePage extends JacksonHandler {
    @Override
    public Object handle(Request req, Response res) {
        OidcUser u = ClaimsHolder.user();
        return json(res, Map.of("sub", u.sub(), "email", u.email()));
    }
 }
@Route(method = HttpMethod.GET, path = "/admin")
@RolesAllowed("admin")           // OR semantics: "admin" OR "superuser"
 // @RolesAllowed({"admin", "superuser"})
 public class AdminPage extends JacksonHandler { ... }
@Route(method = HttpMethod.POST, path = "/orders")
@ScopesAllowed("orders:write")   // default = ALL semantics
 public class CreateOrder extends JacksonHandler { ... }
@Route(method = HttpMethod.POST, path = "/payments")
@ScopesAllowed(value = {"payments:write", "payments:admin"}, match = ScopesAllowed.Match.ANY)
 public class PayOrder extends JacksonHandler { ... }
@Route(method = HttpMethod.DELETE, path = "/admin/users/{id}")
@RolesAllowed("admin")
@ScopesAllowed("users:delete")   // combined with AND semantics
 public class DeleteUser extends JacksonHandler { ... }
 ```
 The middleware is injected automatically by the annotation processor — no manual wiring needed.
 Annotation composition rules:
 - `@Authenticated` requires auth only
 - `@RolesAllowed` implies authentication + role OR-check
 - `@ScopesAllowed` implies authentication + scope check (`ALL`/`ANY`)
 - combining `@RolesAllowed` + `@ScopesAllowed` uses AND semantics
 - `@Authenticated(optional = true)` cannot be combined with role/scope constraints
 ### Lambda routes (manual middleware)
 For lambda routes, pass the middleware as a varargs argument. Retrieve `OidcMiddleware`
 from the context inside another extension's `routes()` phase, or after `start()`:
 ```java
 OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
 // Authentication only
 app.get("/api/me", (req, res) -> {
    OidcUser u = ClaimsHolder.user();   // never null here
    return Map.of("sub", u.sub(), "email", u.email());
 }, oidc.protect());
 // Authentication + role check
 app.delete("/api/admin/users/{id}", (req, res) -> {
    OidcUser u = ClaimsHolder.user();
    // ...
 }, oidc.requireRole("admin"));
 // Multiple roles (OR): passes if user holds any one of them
 app.get("/api/reports", (req, res) -> { ... }, oidc.requireRole("admin", "reports-viewer"));
 // Require all listed scopes
 app.post("/api/orders", (req, res) -> { ... }, oidc.requireScopes("orders:write", "payments:write"));
 // Require at least one listed scope
 app.post("/api/payments", (req, res) -> { ... }, oidc.requireAnyScope("payments:write", "payments:admin"));
 ```
 `oidc.protect()` / `oidc.requireRole(...)` / `oidc.requireScopes(...)` return a `Middleware` — a composable
 `Handler → Handler` wrapper. Flash applies middleware right-to-left so the OIDC check
 runs before your handler.
 ## Accessing the authenticated user
 `ClaimsHolder` holds the JWT claims for the current request in a `ThreadLocal`.
 It is populated by the OIDC middleware before your handler runs and cleared in the
 `finally` block afterward. It is safe with virtual threads (each request gets its
 own virtual thread, so `ThreadLocal` values are naturally isolated).
 ### OidcUser (preferred)
 ```java
 OidcUser u = ClaimsHolder.user();   // never null inside a protected handler
 String sub      = u.sub();          // unique user ID
 String email    = u.email();
 String username = u.username();     // preferred_username
 String name     = u.name();         // full display name
 // Roles — pass the dot-path matching your provider's claim structure
 List<String> roles = u.roles("realm_access.roles");   // Keycloak realm roles
 List<String> clientRoles = u.roles("resource_access.my-client.roles"); // Keycloak client roles
 List<String> groups = u.roles("groups");              // Authelia
 boolean isAdmin = u.hasRole("realm_access.roles", "admin");
 // Scopes (OIDC/OAuth2 generic): checks "scope" then "scp"
 List<String> scopes = u.scopes();
 boolean canWrite = u.hasScope("orders:write");
 // Custom claim path resolution (for provider-specific payloads)
 List<String> customScopes = u.scopes("scope,scp,permissions.scopes");
 boolean canApprove = u.hasScope("permissions.scopes", "orders:approve");
 // Arbitrary claim
 String locale = (String) u.claim("locale");
 Long   exp    = u.claim("exp", Long.class);
 // Full raw map (escape hatch)
 Map<String, Object> all = u.claims();
 ```
 ### Raw access (escape hatch)
 ```java
 Map<String, Object> claims = ClaimsHolder.get();
 String email = ClaimsHolder.claim("email");
 ```
 ## Performance
 The middleware adds negligible overhead on the hot path for authenticated requests:
 | Step | Cost |
 |---|---|
 | `Authorization` header check | `O(1)` map lookup |
 | Cookie parse | `O(cookie_length)` single pass scan |
 | Session lookup | `O(1)` `ConcurrentHashMap.get()` |
 | Token expiry check | `O(1)` `Instant` comparison |
 | `ClaimsHolder.set()` | `O(1)` `ThreadLocal.set()` |
 No network calls, no cryptography, no JSON parsing on the happy path (valid session).
 JWKS key fetching only happens for Bearer token validation and is cached + rate-limited by
 Nimbus's `JWKSourceBuilder`. Silent token refresh only triggers when the access token expires.
 Role/scope claim paths are compiled once during middleware construction (mount time), not per request.
 ## Authentication flow details
 On each request the middleware resolves credentials in this order:
 1. **Bearer token** (`Authorization: Bearer <jwt>`) — validated against JWKS.
 2. **Session cookie** (`oidc_session`) — looked up in the session store; transparently
   refreshed if the access token is expired (silent refresh via refresh token).
 3. **No valid credentials**:
   - Browser clients (no `Accept: application/json`) → redirect to `{prefix}/login?redirect={path}`
   - API clients → `401 Unauthorized`
 ### API error semantics (RFC 6750)
 For API clients (`Accept: application/json`) the middleware includes `WWW-Authenticate`:
 - missing credentials: `Bearer realm="<schemeName>"`
 - invalid bearer token: `Bearer realm="<schemeName>", error="invalid_token"`
 - insufficient scopes: `Bearer realm="<schemeName>", error="insufficient_scope", scope="<required scopes>"`
 This enables interoperable client-side handling and proper OAuth2 challenge semantics.
 ### Token validation (OIDC Core §3.1.3.7)
 | Check | Access token | ID token |
 |---|---|---|
 | Signature (JWKS) | yes | yes |
 | `iss` | yes | yes |
 | `aud` = clientId | no (varies by provider) | yes |
 | `exp`, `iat`, `sub` | yes | yes |
 | `nonce` | — | yes |
 JWKS keys are cached, rate-limited, and retried on cache-miss (handles key rotation).
 ### Claim merge strategy
 At callback time the extension merges access token + ID token claims:
 - Access token claims first (contains provider-specific data like `realm_access.roles`)
 - ID token claims override (contains verified identity: `sub`, `email`, `name`, …)
 This is provider-agnostic: authorization claims live in the AT per RFC 9068,
 identity claims live in the IT per OIDC Core.
 ## Standards & compliance notes
 This extension is designed to be compliant with the most relevant OIDC/OAuth2 RFCs:
 - RFC 8414 (Authorization Server Metadata): discovery via `/.well-known/openid-configuration`
 - OpenID Connect Core 1.0: Authorization Code flow + PKCE + `nonce` validation on ID token
 - RFC 7636 (PKCE): S256 challenge/verifier flow
 - RFC 6750 (Bearer Token Usage): `WWW-Authenticate` challenges with standard error codes
 - RFC 9068 (JWT Profile for Access Tokens): JWT bearer access-token validation path
 - RFC 7519 / RFC 7517 / RFC 7515 family: JWT/JWK/JWS validation via Nimbus + JWKS caching/rotation
 Provider interoperability details:
 - scope extraction supports both standard forms: `scope` (space-delimited string) and `scp` (list/string)
 - roles remain configurable via `rolesClaimPath` (`realm_access.roles`, `groups`, etc.)
 - scope claim fallback chain is configurable via `scopeClaimPaths`
 ## Testing scopes with Keycloak
 Quick path to test `@ScopesAllowed` end-to-end:
 1. **Create a client scope**
   - Realm -> Client scopes -> Create
   - Name: `orders:write` (or any scope name you want to enforce)
 2. **Attach it to your client**
   - Clients -> `<your-client>` -> Client scopes
   - Add the scope as `Default` (always in token) or `Optional` (requested via `scope` param)
 3. **Ensure scope mapper reaches the token**
   - For most Keycloak setups this is automatic via built-in `microprofile-jwt`/scope mappers
   - Verify the access token contains either `scope` string or `scp` list
 4. **Request the scope in Flash config**
   - Include it in `OidcConfig.scopes(...)`, e.g. `"openid profile email orders:write"`
 5. **Protect a handler**
   - `@ScopesAllowed("orders:write")` on class-based handlers
   - or `oidc.requireScopes("orders:write")` for lambda routes
 6. **Verify behavior**
   - token with scope -> 200
   - token without scope -> 403 + `WWW-Authenticate: ... insufficient_scope`
 Useful token inspection flow while testing:
 - Obtain a token from Keycloak
 - Decode payload (`jwt.io` or local tool)
 - check `scope` / `scp` claims
 - call your protected endpoint and inspect status + `WWW-Authenticate`
 ## Session store
 The default `InMemoryOidcSessionStore` is sufficient for single-instance deployments.
 For clustered deployments, implement `OidcSessionStore`:
 ```java
 public interface OidcSessionStore {
    void              save(OidcSession session);
    Optional<OidcSession> find(String sessionId);
    void              delete(String sessionId);
 }
 ```
 ```java
 OidcConfig.builder(...)
    .sessionStore(new RedisOidcSessionStore(redisClient))
    .build()
 ```
 `OidcSession` fields: `id`, `accessToken`, `idToken`, `refreshToken`, `expiresAt` (`Instant`), `claims` (merged map).
 ## Logout
 Add a logout button anywhere in your UI — a `<form>` is sufficient (no JavaScript needed):
 ```html
 <form method="POST" action="/auth/logout">
    <button type="submit">Logout</button>
 </form>
 ```
 The `POST {prefix}/logout` handler:
 1. Reads the `oidc_session` cookie, looks up the session, retrieves the `id_token`.
 2. Deletes the local session and clears the cookie (`Max-Age=0`).
 3. If the provider has an `end_session_endpoint` (standard IdPs do), redirects there with
   `?id_token_hint=<idToken>&post_logout_redirect_uri=<postLogoutRedirectUri>` — this logs
   the user out of the IdP as well.
 4. Otherwise redirects to `postLogoutRedirectUri` (default: `/`).
 ## Bearer token (API clients)
 For API-to-API or SPA-to-API calls, pass a Bearer access token directly. The middleware
 validates the JWT signature against JWKS and extracts the claims — no session involved:
 ```
 Authorization: Bearer <access_token>
 ```
 The token must be a JWT (opaque tokens are not supported). Claims are available via
 `ClaimsHolder.user()` as usual.
 ## Multi-tenant
 Multiple OIDC providers on one server — each `OidcExtension` instance is fully independent
 (its own PKCE state store, session store, validator, and middleware):
 ```java
 OidcConfig tenantA = OidcConfig.builder("https://idp/realms/a", "clientA", "secretA", "/a/auth/callback")
    .routePrefix("/a/auth").schemeName("tenantA").build();
 OidcConfig tenantB = OidcConfig.builder("https://idp/realms/b", "clientB", "secretB", "/b/auth/callback")
    .routePrefix("/b/auth").schemeName("tenantB").build();
 app.install(new OidcExtension(tenantA))
   .install(new OidcExtension(tenantB));
 ```
 To reference a specific tenant's middleware on lambda routes, keep the extension instances
 and retrieve `OidcMiddleware` from context after `start()`:
 ```java
 OidcExtension extA = new OidcExtension(tenantA);
 OidcExtension extB = new OidcExtension(tenantB);
 FlashApp app = FlashApp.create(8080)
    .install(extA)
    .install(extB)
    .start()
    .join();    // wait for bind
 OidcMiddleware mwA = app.ctx().require(OidcMiddleware.class);  // last registered = tenantB
 ```
 > **Note:** because both extensions register `OidcMiddleware.class` in the same context,
 > only the last one wins under that key. For multi-tenant setups, use distinct context
 > keys or provide middleware under a wrapper/alias type, or use lambda routes with explicit
 > middleware captured from the extension instance before `install()`.
 Class-based handlers annotated with `@Authenticated` / `@RolesAllowed` get the last
 registered processor's middleware. For true multi-tenant class-based routing, install
 tenant-specific annotation processors with different annotations.
 ## OpenAPI integration
 If `flash-ext-openapi` is on the classpath and installed (order irrelevant),
 the extension automatically:
 - Adds a `components.securitySchemes` entry for the provider (OAuth2, authorizationCode flow)
 - Adds `security` requirements to every operation whose handler carries `@Authenticated`
  , `@RolesAllowed`, or `@ScopesAllowed`
 No extra code needed. To customize the scheme name:
 ```java
 OidcConfig.builder(...).schemeName("keycloak").build()
 ```
 If `flash-ext-openapi` is absent the integration is silently skipped.
@@ -1,40 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 /**
 * Marks a handler as requiring a valid JWT. Any bearer token that passes
 * signature + expiry + issuer validation is accepted — no role check is performed.
 *
 * <p>For role-based access use {@link RolesAllowed} instead (it implies authentication).
 *
 * <p>Set {@code optional = true} on public routes that personalise their response when
 * the user happens to be logged in but should remain accessible to guests. The middleware
 * will populate {@link ClaimsHolder} if credentials are present and silently skip it
 * otherwise — the request is never rejected.
 *
 * <pre>{@code
 * // Hard auth — redirects / 401 when unauthenticated:
 * @Route(method = HttpMethod.GET, path = "/api/profile")
 * @Authenticated
 * public class GetProfile extends JacksonHandler { ... }
 *
 * // Soft auth — guest-friendly, ClaimsHolder populated only when logged in:
 * @Route(method = HttpMethod.GET, path = "/")
 * @Authenticated(optional = true)
 * public class HomePage extends HtmlHandler { ... }
 * }</pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
 public @interface Authenticated {
    /**
     * When {@code true} the middleware never rejects unauthenticated requests — it only
     * populates {@link ClaimsHolder} when valid credentials are present.
     * Defaults to {@code false} (hard authentication required).
     */
    boolean optional() default false;
 }
@@ -1,71 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.util.Map;
 /**
 * Thread-local store for JWT claims, populated by the OIDC middleware before
 * the handler runs and cleared in the {@code finally} block afterward.
 *
 * <p>Safe with virtual threads: each request gets its own virtual thread, so
 * {@link ThreadLocal} values are naturally isolated per request.
 *
 * <pre>{@code
 * // Inside any handler protected by @Authenticated or @RolesAllowed:
 *
 * // Preferred — typed wrapper:
 * OidcUser user = ClaimsHolder.user();
 * String email  = user.email();
 * List<String> roles = user.roles("realm_access.roles");
 *
 * // Raw escape hatch:
 * Map<String, Object> all = ClaimsHolder.get();
 * }</pre>
 */
 public final class ClaimsHolder {
    private static final ThreadLocal<Map<String, Object>> HOLDER = new ThreadLocal<>();
    private ClaimsHolder() {}
    /** Called by the OIDC middleware after successful token validation. */
    static void set(Map<String, Object> claims) {
        HOLDER.set(claims);
    }
    /** Called by the OIDC middleware in the {@code finally} block. */
    static void clear() {
        HOLDER.remove();
    }
    /**
     * Returns a type-safe {@link OidcUser} view of the current request's claims,
     * or {@code null} if the route is not protected by OIDC middleware.
     *
     * <p>This is the preferred entry point for both lambda and class-based handlers.
     */
    public static OidcUser user() {
        Map<String, Object> claims = HOLDER.get();
        return claims != null ? new OidcUser(claims) : null;
    }
    /**
     * Returns the raw claims map for the current request, or {@code null} if
     * the route is not protected by OIDC middleware.
     *
     * @see #user() for the preferred type-safe accessor
     */
    public static Map<String, Object> get() {
        return HOLDER.get();
    }
    /**
     * Returns the value of a single claim as a String, or {@code null} if
     * the claim is absent or the request is not authenticated.
     */
    public static String claim(String key) {
        Map<String, Object> claims = HOLDER.get();
        if (claims == null) return null;
        Object v = claims.get(key);
        return v != null ? v.toString() : null;
    }
 }
@@ -1,18 +0,0 @@
 package dev.relism.flash.ext.oidc;
 /**
 * OAuth2 client authentication method for the token endpoint (RFC 6749 §2.3).
 *
 * <ul>
 *   <li>{@link #POST} — credentials sent as {@code client_id} / {@code client_secret}
 *       form fields (default; most providers).</li>
 *   <li>{@link #BASIC} — credentials sent as an {@code Authorization: Basic} header;
 *       body contains only grant-specific parameters.</li>
 * </ul>
 */
 public enum ClientAuthMethod {
    /** {@code client_secret_post} — credentials in the request body. */
    POST,
    /** {@code client_secret_basic} — credentials in the {@code Authorization} header. */
    BASIC
 }
@@ -1,50 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import net.minidev.json.JSONValue;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.util.Map;
 /**
 * Fetches and parses the OIDC provider discovery document at
 * {@code {issuer}/.well-known/openid-configuration}.
 */
 final class DiscoveryClient {
    private DiscoveryClient() {}
    static OidcProviderMetadata fetch(String issuer, HttpClient http) throws Exception {
        String url = issuer.endsWith("/")
                ? issuer + ".well-known/openid-configuration"
                : issuer + "/.well-known/openid-configuration";
        HttpResponse<String> resp = http.send(
                HttpRequest.newBuilder().uri(URI.create(url)).GET().build(),
                HttpResponse.BodyHandlers.ofString());
        if (resp.statusCode() != 200)
            throw new IllegalStateException(
                    "OIDC discovery failed [" + resp.statusCode() + "]: " + url);
        @SuppressWarnings("unchecked")
        Map<String, Object> doc = (Map<String, Object>) JSONValue.parse(resp.body());
        return new OidcProviderMetadata(
                require(doc, "authorization_endpoint"),
                require(doc, "token_endpoint"),
                (String) doc.get("userinfo_endpoint"),      // optional
                require(doc, "jwks_uri"),
                (String) doc.get("end_session_endpoint")    // optional
        );
    }
    private static String require(Map<String, Object> doc, String key) {
        Object v = doc.get(key);
        if (v == null) throw new IllegalStateException(
                "Discovery doc missing required field: " + key);
        return v.toString();
    }
 }
@@ -1,20 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 /**
 * Thread-safe in-memory {@link OidcSessionStore}.
 *
 * <p>Sessions are lost on restart and not shared across instances. For
 * production deployments with multiple nodes or restart-persistence requirements,
 * supply a custom implementation via {@link OidcConfig.Builder#sessionStore}.
 */
 public final class InMemoryOidcSessionStore implements OidcSessionStore {
    private final ConcurrentHashMap<String, OidcSession> store = new ConcurrentHashMap<>();
    @Override public void             save(OidcSession s)  { store.put(s.id(), s); }
    @Override public Optional<OidcSession> find(String id) { return Optional.ofNullable(store.get(id)); }
    @Override public void             delete(String id)    { store.remove(id); }
 }
@@ -1,38 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import net.minidev.json.JSONValue;
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 import java.util.Map;
 /**
 * Low-level JWT payload extraction — no signature or expiry validation.
 *
 * <p>Use only for tokens received directly from the provider over a trusted TLS
 * connection (e.g. {@code id_token} from the token endpoint). Bearer tokens on
 * incoming requests must go through {@link JwtValidator#validate(String)} instead.
 */
 final class JwtUtils {
    private JwtUtils() {}
    /**
     * Base64URL-decodes the JWT payload and returns the claims as a map.
     * Signature, expiry, and issuer are NOT checked.
     */
    @SuppressWarnings("unchecked")
    static Map<String, Object> parseClaims(String jwt) {
        String[] parts = jwt.split("\\.");
        if (parts.length < 2) throw new IllegalArgumentException("Malformed JWT: " + jwt);
        // Pad to a multiple of 4 for the standard decoder
        String padded = parts[1];
        switch (padded.length() % 4) {
            case 2 -> padded += "==";
            case 3 -> padded += "=";
        }
        byte[] payload = Base64.getUrlDecoder().decode(padded);
        return (Map<String, Object>) JSONValue.parse(
                new String(payload, StandardCharsets.UTF_8));
    }
 }
@@ -1,184 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import com.nimbusds.jose.JWSAlgorithm;
 import com.nimbusds.jose.jwk.source.JWKSource;
 import com.nimbusds.jose.jwk.source.JWKSourceBuilder;
 import com.nimbusds.jose.proc.JWSKeySelector;
 import com.nimbusds.jose.proc.JWSVerificationKeySelector;
 import com.nimbusds.jose.proc.SecurityContext;
 import com.nimbusds.jose.util.Resource;
 import com.nimbusds.jose.util.ResourceRetriever;
 import com.nimbusds.jwt.JWTClaimsSet;
 import com.nimbusds.jwt.proc.ConfigurableJWTProcessor;
 import com.nimbusds.jwt.proc.DefaultJWTClaimsVerifier;
 import com.nimbusds.jwt.proc.DefaultJWTProcessor;
 import dev.relism.flash.exceptions.HttpException;
 import java.io.IOException;
 import java.net.URL;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.util.Map;
 import java.util.Set;
 /**
 * Validates JWTs against a remote JWKS endpoint using Nimbus JOSE+JWT.
 *
 * <p>Two validation modes:
 * <ul>
 *   <li>{@link #validate(String)} — access token bearer validation per request (hot path).
 *       Checks signature, {@code iss}, {@code exp}, {@code iat}, {@code sub}.
 *       Throws {@link HttpException} 401 so the middleware can short-circuit.</li>
 *   <li>{@link #validateIdToken(String, String)} — ID token validation at callback time.
 *       Checks signature, {@code iss}, {@code aud} == clientId, {@code exp}, {@code iat},
 *       {@code sub}, and {@code nonce} (if provided).
 *       Throws {@link OidcValidationException} (not 401 — it is a provider/protocol error).</li>
 * </ul>
 *
 * <p>JWKS handling: the shared {@link JWKSource} uses caching + rate-limiting + automatic
 * retry-on-key-miss (key rotation). Both processors share the same source — one JWKS
 * fetch serves both token types.
 */
 public class JwtValidator {
    private final JWKSource<SecurityContext>                 jwkSource;
    private final ConfigurableJWTProcessor<SecurityContext>  accessTokenProcessor;
    private final ConfigurableJWTProcessor<SecurityContext>  idTokenProcessor;
    private final String                                     algorithm;
    /**
     * @param jwksUri   JWKS endpoint URI
     * @param issuer    Expected {@code iss} claim
     * @param clientId  OAuth2 client ID — used as expected {@code aud} in ID tokens
     * @param algorithm JWS algorithm (e.g. {@code "RS256"})
     * @param http      Shared {@link HttpClient} used for all JWKS fetches — already configured
     *                  with the correct TLS policy (trust-all or default trust store).
     */
    public JwtValidator(String jwksUri, String issuer, String clientId,
                        String algorithm, HttpClient http) {
        try {
            // Use the caller-supplied HttpClient for JWKS retrieval so that TLS policy
            // (insecureTls / custom trust store) is applied consistently everywhere.
            this.jwkSource = JWKSourceBuilder
                    .create(new URL(jwksUri), httpRetriever(http))
                    .cache(true)
                    .rateLimited(true)
                    .retrying(true)
                    .build();
        } catch (Exception e) {
            throw new IllegalStateException("Failed to init JWKS source: " + jwksUri, e);
        }
        this.algorithm            = algorithm;
        this.accessTokenProcessor = buildAccessTokenProcessor(jwkSource, issuer, algorithm);
        this.idTokenProcessor     = buildIdTokenProcessor(jwkSource, issuer, clientId, algorithm);
    }
    // -- Public API -----------------------------------------------------------
    /**
     * Validates a JWT access token (bearer on incoming request).
     * Returns claims on success; throws {@link HttpException} 401 on any failure.
     */
    public Map<String, Object> validate(String token) {
        if (!isJwt(token)) throw HttpException.unauthorized();   // opaque token — can't validate
        try {
            return accessTokenProcessor.process(token, null).getClaims();
        } catch (Exception e) {
            throw HttpException.unauthorized();
        }
    }
    /**
     * Validates an ID token received directly from the token endpoint.
     *
     * <p>Checks: signature (JWKS), {@code iss}, {@code aud} == clientId,
     * {@code exp}, {@code iat}, {@code sub}, and {@code nonce} if provided.
     *
     * @param idToken  Raw ID token string
     * @param nonce    Nonce sent in the authorization request; {@code null} to skip check
     * @throws OidcValidationException on any validation failure
     */
    public Map<String, Object> validateIdToken(String idToken, String nonce) {
        try {
            Map<String, Object> claims = idTokenProcessor.process(idToken, null).getClaims();
            if (nonce != null && !nonce.equals(claims.get("nonce")))
                throw new OidcValidationException("ID token nonce mismatch", null);
            return claims;
        } catch (OidcValidationException e) {
            throw e;
        } catch (Exception e) {
            throw new OidcValidationException("ID token validation failed: " + e.getMessage(), e);
        }
    }
    /**
     * Returns {@code true} if {@code token} is a signed JWT (three dot-separated Base64URL parts).
     * Used to detect opaque access tokens before attempting JWKS validation.
     */
    public static boolean isJwt(String token) {
        if (token == null || token.isBlank()) return false;
        int dots = 0;
        for (int i = 0; i < token.length(); i++) if (token.charAt(i) == '.') dots++;
        return dots == 2;
    }
    // -- Processors -----------------------------------------------------------
    private static ConfigurableJWTProcessor<SecurityContext> buildAccessTokenProcessor(
            JWKSource<SecurityContext> src, String issuer, String algorithm) {
        ConfigurableJWTProcessor<SecurityContext> p = new DefaultJWTProcessor<>();
        p.setJWSKeySelector(keySelector(src, algorithm));
        // iss required; aud not enforced on ATs (varies by provider)
        if (issuer != null && !issuer.isBlank()) {
            p.setJWTClaimsSetVerifier(new DefaultJWTClaimsVerifier<>(
                    new JWTClaimsSet.Builder().issuer(issuer).build(),
                    Set.of("sub", "iat", "exp")));
        }
        return p;
    }
    private static ConfigurableJWTProcessor<SecurityContext> buildIdTokenProcessor(
            JWKSource<SecurityContext> src, String issuer, String clientId, String algorithm) {
        ConfigurableJWTProcessor<SecurityContext> p = new DefaultJWTProcessor<>();
        p.setJWSKeySelector(keySelector(src, algorithm));
        // iss + aud = clientId strictly required (OIDC Core §3.1.3.7)
        JWTClaimsSet.Builder required = new JWTClaimsSet.Builder();
        if (issuer   != null) required.issuer(issuer);
        if (clientId != null) required.audience(clientId);
        p.setJWTClaimsSetVerifier(new DefaultJWTClaimsVerifier<>(
                required.build(), Set.of("sub", "iat", "exp")));
        return p;
    }
    private static JWSKeySelector<SecurityContext> keySelector(
            JWKSource<SecurityContext> src, String algorithm) {
        return new JWSVerificationKeySelector<>(JWSAlgorithm.parse(algorithm), src);
    }
    /**
     * Wraps a {@link HttpClient} as a Nimbus {@link ResourceRetriever}.
     * The client already carries the correct TLS policy (trust-all or default),
     * so JWKS fetches honour the same SSL configuration as discovery and token requests.
     */
    private static ResourceRetriever httpRetriever(HttpClient http) {
        return url -> {
            try {
                HttpResponse<String> resp = http.send(
                        HttpRequest.newBuilder().uri(url.toURI()).GET().build(),
                        HttpResponse.BodyHandlers.ofString());
                if (resp.statusCode() != 200)
                    throw new IOException("JWKS fetch failed [" + resp.statusCode() + "]: " + url);
                String contentType = resp.headers()
                        .firstValue("Content-Type").orElse("application/json");
                return new Resource(resp.body(), contentType);
            } catch (IOException e) {
                throw e;
            } catch (Exception e) {
                throw new IOException("JWKS retrieval error: " + e.getMessage(), e);
            }
        };
    }
 }
@@ -1,98 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.util.LinkedHashSet;
 import java.util.List;
 /**
 * Compiled authorization policy derived from handler annotations at mount time.
 * Immutable and allocation-free on the request hot path.
 */
 final class OidcAuthPolicy {
    private static final String[] EMPTY = new String[0];
    private static final OidcAuthPolicy AUTH_REQUIRED = new OidcAuthPolicy(
            false, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
    private static final OidcAuthPolicy AUTH_OPTIONAL = new OidcAuthPolicy(
            true, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
    private final boolean optionalAuth;
    private final String[] requiredRoles;
    private final String[] requiredScopes;
    private final ScopesAllowed.Match scopeMatch;
    private OidcAuthPolicy(boolean optionalAuth,
                           String[] requiredRoles,
                           String[] requiredScopes,
                           ScopesAllowed.Match scopeMatch) {
        this.optionalAuth   = optionalAuth;
        this.requiredRoles  = requiredRoles;
        this.requiredScopes = requiredScopes;
        this.scopeMatch     = scopeMatch;
    }
    static OidcAuthPolicy authenticated() { return AUTH_REQUIRED; }
    static OidcAuthPolicy optional() { return AUTH_OPTIONAL; }
    static OidcAuthPolicy rolesAny(String... roles) {
        return new OidcAuthPolicy(false, normalizeRequired("RolesAllowed", roles), EMPTY, ScopesAllowed.Match.ALL);
    }
    static OidcAuthPolicy scopes(String[] scopes, ScopesAllowed.Match match) {
        return new OidcAuthPolicy(false, EMPTY, normalizeRequired("ScopesAllowed", scopes), match);
    }
    static OidcAuthPolicy compileFromAnnotations(Class<?> handlerClass) {
        Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
        RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
        ScopesAllowed scopes = handlerClass.getAnnotation(ScopesAllowed.class);
        if (auth == null && roles == null && scopes == null) return null;
        boolean optionalAuth = auth != null && auth.optional();
        String[] requiredRoles = roles != null ? normalizeRequired("RolesAllowed", roles.value()) : EMPTY;
        String[] requiredScopes = scopes != null ? normalizeRequired("ScopesAllowed", scopes.value()) : EMPTY;
        ScopesAllowed.Match scopeMatch = scopes != null ? scopes.match() : ScopesAllowed.Match.ALL;
        if (optionalAuth && (requiredRoles.length > 0 || requiredScopes.length > 0)) {
            throw new IllegalStateException("@Authenticated(optional = true) cannot be combined with @RolesAllowed/@ScopesAllowed on "
                    + handlerClass.getName());
        }
        return new OidcAuthPolicy(optionalAuth, requiredRoles, requiredScopes, scopeMatch);
    }
    static List<String> openApiScopesFor(Class<?> handlerClass) {
        Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
        RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
        ScopesAllowed scopes = handlerClass.getAnnotation(ScopesAllowed.class);
        if (auth == null && roles == null && scopes == null) return null;
        if (scopes == null) return List.of();
        return List.of(normalizeRequired("ScopesAllowed", scopes.value()));
    }
    boolean optionalAuth() { return optionalAuth; }
    String[] requiredRoles() { return requiredRoles; }
    String[] requiredScopes() { return requiredScopes; }
    ScopesAllowed.Match scopeMatch() { return scopeMatch; }
    private static String[] normalizeRequired(String annotation, String[] values) {
        if (values == null || values.length == 0)
            throw new IllegalStateException("@" + annotation + " requires at least one value");
        LinkedHashSet<String> normalized = new LinkedHashSet<>(values.length);
        for (String raw : values) {
            if (raw == null) continue;
            String trimmed = raw.trim();
            if (!trimmed.isEmpty()) normalized.add(trimmed);
        }
        if (normalized.isEmpty())
            throw new IllegalStateException("@" + annotation + " requires at least one non-empty value");
        return normalized.toArray(String[]::new);
    }
 }
@@ -1,261 +0,0 @@
 package dev.relism.flash.ext.oidc;
 /**
 * Full OIDC client configuration. Build via
 * {@link #builder(String, String, String, String)} or {@link #fromEnv()}.
 *
 * <p>Required fields: {@code issuer}, {@code clientId}, {@code clientSecret},
 * {@code redirectUri}. Everything else has a sensible default.
 *
 * <p>If {@code redirectUri} starts with {@code /} it is treated as server-relative:
 * the absolute URL is resolved at request time using {@link #selfScheme()} and the
 * incoming {@code Host} header. Use {@link Builder#https()} when behind TLS.
 *
 * <pre>{@code
 * // Keycloak
 * OidcConfig.builder(
 *         "https://keycloak.example.com/realms/myrealm",
 *         "my-app", "secret", "/auth/callback")
 *     .rolesClaimPath("realm_access.roles")   // Keycloak default
 *     .scopeClaimPaths("scope,scp")           // default; supports many IdPs
 *     .build();
 *
 * // Authelia
 * OidcConfig.builder(
 *         "https://auth.example.com",
 *         "my-app", "secret", "/auth/callback")
 *     .rolesClaimPath("groups")
 *     .scopeClaimPaths("scope,scp")
 *     .build();
 *
 * // Two tenants on one server
 * OidcConfig tenantA = OidcConfig.builder("https://idp/realms/a", ..., "/tenantA/auth/callback")
 *     .routePrefix("/tenantA/auth").build();
 * OidcConfig tenantB = OidcConfig.builder("https://idp/realms/b", ..., "/tenantB/auth/callback")
 *     .routePrefix("/tenantB/auth").build();
 * app.install(new OidcExtension(tenantA))
 *    .install(new OidcExtension(tenantB));
 * }</pre>
 */
 public final class OidcConfig {
    private final String           issuer;
    private final String           clientId;
    private final String           clientSecret;
    private final String           redirectUri;
    private final String           scopes;
    private final String           routePrefix;
    private final String           selfScheme;
    private final String           rolesClaimPath;
    private final String           scopeClaimPaths;
    private final String           algorithm;
    private final String           postLogoutRedirectUri;
    private final OidcSessionStore sessionStore;
    private final boolean          insecureTls;
    private final ClientAuthMethod clientAuthMethod;
    private final String           schemeName;
    private OidcConfig(Builder b) {
        this.issuer                = require(b.issuer,       "issuer");
        this.clientId              = require(b.clientId,     "clientId");
        this.clientSecret          = require(b.clientSecret, "clientSecret");
        this.redirectUri           = require(b.redirectUri,  "redirectUri");
        this.scopes                = b.scopes;
        this.routePrefix           = b.routePrefix;
        this.selfScheme            = b.selfScheme;
        this.rolesClaimPath        = b.rolesClaimPath;
        this.scopeClaimPaths       = b.scopeClaimPaths;
        this.algorithm             = b.algorithm;
        this.postLogoutRedirectUri = b.postLogoutRedirectUri;
        this.sessionStore          = b.sessionStore != null ? b.sessionStore
                                                            : new InMemoryOidcSessionStore();
        this.insecureTls           = b.insecureTls;
        this.clientAuthMethod      = b.clientAuthMethod;
        this.schemeName            = b.schemeName != null ? b.schemeName : deriveScheme(this.issuer);
    }
    // -- Getters --------------------------------------------------------------
    public String           issuer()                { return issuer; }
    public String           clientId()              { return clientId; }
    public String           clientSecret()          { return clientSecret; }
    public String           redirectUri()           { return redirectUri; }
    public String           scopes()                { return scopes; }
    public String           routePrefix()           { return routePrefix; }
    public String           selfScheme()            { return selfScheme; }
    public String           rolesClaimPath()        { return rolesClaimPath; }
    /** Comma-separated claim paths used to read OAuth2 scopes (default: {@code "scope,scp"}). */
    public String           scopeClaimPaths()       { return scopeClaimPaths; }
    public String           algorithm()             { return algorithm; }
    public String           postLogoutRedirectUri() { return postLogoutRedirectUri; }
    public OidcSessionStore sessionStore()          { return sessionStore; }
    /** If {@code true}, TLS certificate validation is skipped. <b>Never use in production.</b> */
    public boolean          insecureTls()           { return insecureTls; }
    public ClientAuthMethod clientAuthMethod()       { return clientAuthMethod; }
    /** OpenAPI security scheme name (derived from issuer if not set explicitly). */
    public String           schemeName()            { return schemeName; }
    // -- Factory --------------------------------------------------------------
    /**
     * Reads configuration from environment variables:
     * <pre>
     * OIDC_ISSUER               required
     * OIDC_CLIENT_ID            required
     * OIDC_CLIENT_SECRET        required
     * OIDC_REDIRECT_URI         required  (e.g. /auth/callback)
     * OIDC_SCOPES               default: openid profile email
     * OIDC_ROUTE_PREFIX         default: /auth
     * OIDC_SELF_SCHEME          default: http
     * OIDC_ROLES_CLAIM          default: realm_access.roles
     * OIDC_SCOPE_CLAIMS         default: scope,scp
     * OIDC_ALGORITHM            default: RS256
     * OIDC_POST_LOGOUT_REDIRECT default: /
     * </pre>
     */
    public static OidcConfig fromEnv() {
        return builder(env("OIDC_ISSUER"), env("OIDC_CLIENT_ID"),
                       env("OIDC_CLIENT_SECRET"), env("OIDC_REDIRECT_URI"))
                .scopes               (envOr("OIDC_SCOPES",               "openid profile email"))
                .routePrefix          (envOr("OIDC_ROUTE_PREFIX",          "/auth"))
                .selfScheme           (envOr("OIDC_SELF_SCHEME",           "http"))
                .rolesClaimPath       (envOr("OIDC_ROLES_CLAIM",           "realm_access.roles"))
                .scopeClaimPaths      (envOr("OIDC_SCOPE_CLAIMS",          "scope,scp"))
                .algorithm            (envOr("OIDC_ALGORITHM",             "RS256"))
                .postLogoutRedirectUri(envOr("OIDC_POST_LOGOUT_REDIRECT",  "/"))
                .clientAuthMethod(ClientAuthMethod.valueOf(
                        envOr("OIDC_CLIENT_AUTH_METHOD", "POST").toUpperCase()))
                .build();
    }
    public static Builder builder(String issuer, String clientId,
                                  String clientSecret, String redirectUri) {
        return new Builder(issuer, clientId, clientSecret, redirectUri);
    }
    /**
     * Convenience factory for Keycloak: constructs the issuer as
     * {@code {serverUrl}/realms/{realm}} automatically.
     *
     * <pre>{@code
     * OidcConfig.keycloak(
     *     "https://keycloak.example.com", "flashboard",
     *     "my-app", "secret", "/auth/callback")
     *   .https()
     *   .build();
     * }</pre>
     */
    public static Builder keycloak(String serverUrl, String realm,
                                   String clientId, String clientSecret,
                                   String redirectUri) {
        String base   = serverUrl.endsWith("/") ? serverUrl.substring(0, serverUrl.length() - 1) : serverUrl;
        String issuer = base + "/realms/" + realm;
        return new Builder(issuer, clientId, clientSecret, redirectUri)
                .rolesClaimPath("realm_access.roles");   // Keycloak default
    }
    // -- Helpers --------------------------------------------------------------
    private static String require(String v, String name) {
        if (v == null || v.isBlank())
            throw new IllegalArgumentException("OidcConfig: " + name + " is required");
        return v;
    }
    private static String env(String key) {
        String v = System.getenv(key);
        if (v == null || v.isBlank())
            throw new IllegalArgumentException("Missing required env var: " + key);
        return v;
    }
    private static String envOr(String key, String def) {
        String v = System.getenv(key);
        return (v != null && !v.isBlank()) ? v : def;
    }
    // -- Builder --------------------------------------------------------------
    public static final class Builder {
        private final String issuer;
        private final String clientId;
        private final String clientSecret;
        private final String redirectUri;
        private String           scopes                = "openid profile email";
        private String           routePrefix           = "/auth";
        private String           selfScheme            = "http";
        private String           rolesClaimPath        = "realm_access.roles";
        private String           scopeClaimPaths       = "scope,scp";
        private String           algorithm             = "RS256";
        private String           postLogoutRedirectUri = "/";
        private OidcSessionStore sessionStore;
        private boolean          insecureTls           = false;
        private ClientAuthMethod clientAuthMethod       = ClientAuthMethod.POST;
        private String           schemeName            = null;
        private Builder(String issuer, String clientId, String clientSecret, String redirectUri) {
            this.issuer       = issuer;
            this.clientId     = clientId;
            this.clientSecret = clientSecret;
            this.redirectUri  = redirectUri;
        }
        /** Override requested scopes (default: {@code openid profile email}). */
        public Builder scopes(String scopes)                        { this.scopes = scopes;                               return this; }
        /** Route prefix for login/callback/logout (default: {@code /auth}). */
        public Builder routePrefix(String prefix)                   { this.routePrefix = prefix;                          return this; }
        /** Scheme used when resolving self-relative redirect URIs (default: {@code http}). */
        public Builder selfScheme(String scheme)                    { this.selfScheme = scheme;                           return this; }
        /** Shorthand for {@code selfScheme("https")}. */
        public Builder https()                                      { return selfScheme("https"); }
        /** Dot-separated path to the roles array in JWT claims (default: {@code realm_access.roles}). */
        public Builder rolesClaimPath(String path)                  { this.rolesClaimPath = path;                         return this; }
        /** Comma-separated claim paths used to resolve OAuth2 scopes (default: {@code scope,scp}). */
        public Builder scopeClaimPaths(String paths)                { this.scopeClaimPaths = paths;                       return this; }
        /** JWS algorithm (default: {@code RS256}). */
        public Builder algorithm(String algorithm)                  { this.algorithm = algorithm;                         return this; }
        /** Where to redirect after logout (default: {@code /}). */
        public Builder postLogoutRedirectUri(String uri)            { this.postLogoutRedirectUri = uri;                   return this; }
        /** Custom session store (default: {@link InMemoryOidcSessionStore}). */
        public Builder sessionStore(OidcSessionStore store)         { this.sessionStore = store;                          return this; }
        /**
         * Disables TLS certificate verification for all HTTP calls made by this extension.
         * <b>Only use in development with self-signed certificates — never in production.</b>
         */
        public Builder insecureTls()                                { this.insecureTls = true;                            return this; }
        /** Token endpoint client authentication method (default: {@link ClientAuthMethod#POST}). */
        public Builder clientAuthMethod(ClientAuthMethod method)    { this.clientAuthMethod = method;                     return this; }
        /** Override the OpenAPI security scheme name (default: derived from the issuer URI). */
        public Builder schemeName(String name)                      { this.schemeName = name;                             return this; }
        public OidcConfig build() { return new OidcConfig(this); }
    }
    /**
     * Derives a short, human-readable scheme name from the issuer URI.
     * Takes the last non-empty path segment; falls back to the host.
     *
     * <p>Examples:
     * <ul>
     *   <li>{@code https://keycloak.dev.home/realms/flashboard} → {@code "flashboard"}</li>
     *   <li>{@code https://auth.example.com}                    → {@code "auth.example.com"}</li>
     * </ul>
     */
    private static String deriveScheme(String issuer) {
        try {
            java.net.URI uri = new java.net.URI(issuer);
            String path = uri.getPath();
            if (path != null && !path.isEmpty()) {
                String[] parts = path.split("/");
                for (int i = parts.length - 1; i >= 0; i--) {
                    if (!parts[i].isEmpty()) return parts[i];
                }
            }
            return uri.getHost();
        } catch (Exception e) {
            return "oidc";
        }
    }
 }
@@ -1,337 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import dev.relism.flash.ext.openapi.OpenApiContributor;
 import dev.relism.flash.ext.openapi.OpenApiContributorRegistry;
 import dev.relism.flash.ext.openapi.OpenApiOperationContribution;
 import dev.relism.flash.ext.openapi.OpenApiResponseContribution;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.extension.FlashExtension;
 import dev.relism.flash.extension.FlashRegistrar;
 import dev.relism.flash.routing.MiddlewareKey;
 import dev.relism.flash.routing.MiddlewareNode;
 import dev.relism.flash.models.Request;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.TrustManager;
 import javax.net.ssl.X509TrustManager;
 import java.net.URLEncoder;
 import java.net.http.HttpClient;
 import java.nio.charset.StandardCharsets;
 import java.security.SecureRandom;
 import java.security.cert.X509Certificate;
 import java.time.Instant;
 import java.util.*;
 /**
 * Full OIDC Authorization Code + PKCE flow for Flash.
 *
 * <p>At {@link #provide}, the extension:
 * <ol>
 *   <li>Fetches the provider discovery document — fail-fast at startup.</li>
 *   <li>Provides {@link OidcMiddleware} and {@link JwtValidator} in the context.</li>
 *   <li>Registers annotation processors for {@link Authenticated}, {@link RolesAllowed}
 *       and {@link ScopesAllowed}.</li>
 * </ol>
 *
 * <p>At {@link #routes}, three routes are registered:
 * <ul>
 *   <li>{@code GET  {prefix}/login}    — builds the authorization URL and redirects.</li>
 *   <li>{@code GET  {prefix}/callback} — exchanges the code, creates a session, redirects.</li>
 *   <li>{@code POST {prefix}/logout}   — invalidates the session, redirects to provider
 *       end-session endpoint (if available) or to {@link OidcConfig#postLogoutRedirectUri()}.</li>
 * </ul>
 *
 * <pre>{@code
 * // Keycloak
 * app.install(new OidcExtension(
 *     OidcConfig.builder(
 *             "https://keycloak.example.com/realms/myrealm",
 *             "my-app", "secret", "/auth/callback")
 *         .rolesClaimPath("realm_access.roles")
 *         .build()));
 *
 * // Two providers / tenants on one server
 * app.install(new OidcExtension(tenantAConfig))
 *    .install(new OidcExtension(tenantBConfig));
 * }</pre>
 */
 public class OidcExtension implements FlashExtension {
    private static final MiddlewareKey POLICY = MiddlewareKey.of("flash.oidc.policy");
    private final OidcConfig config;
    // Initialized in provide(), used in routes() — private to this extension instance.
    private OidcProviderMetadata meta;
    private OidcStateStore       stateStore;
    private TokenClient          tokenClient;
    private JwtValidator         validator;
    private OidcMiddleware       oidcMw;
    public OidcExtension(OidcConfig config) {
        this.config = config;
    }
    // ── Phase 1: services ─────────────────────────────────────────────────────
    @Override
    public void configure(FlashRegistrar<?> app, FlashContext ctx) {
        HttpClient http = buildHttpClient(config);
        // Discover provider endpoints (blocking; fail fast at startup).
        try {
            meta = DiscoveryClient.fetch(config.issuer(), http);
        } catch (Exception e) {
            throw new IllegalStateException("OIDC discovery failed for issuer: " + config.issuer(), e);
        }
        validator   = new JwtValidator(meta.jwksUri(), config.issuer(), config.clientId(), config.algorithm(), http);
        stateStore  = new OidcStateStore();
        tokenClient = new TokenClient(http, config);
        oidcMw      = new OidcMiddleware(validator, config, meta, tokenClient);
        ctx.provide(OidcMiddleware.class, oidcMw);
        ctx.provide(JwtValidator.class,   validator);
        ctx.addAnnotationProcessor(handlerClass -> {
            OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
            return policy != null ? List.of(MiddlewareNode.of(POLICY, oidcMw.policyMiddleware(policy))) : List.of();
        });
        ctx.onReady(() -> registerRoutes(app, ctx));
    }
    private void registerRoutes(FlashRegistrar<?> app, FlashContext ctx) {
        String prefix = config.routePrefix();
        // ── GET {prefix}/login ────────────────────────────────────────────────
        // Builds the provider authorization URL with PKCE + state and redirects.
        // Optional query param: ?redirect={relative-url}  (default: /)
        app.get(prefix + "/login", (req, res) -> {
            String verifier  = PkceUtils.generateVerifier();
            String challenge = PkceUtils.computeChallenge(verifier);
            String state     = UUID.randomUUID().toString();
            String nonce     = UUID.randomUUID().toString();
            String redirect = req.query("redirect");
            if (redirect == null || !redirect.startsWith("/")) redirect = "/";
            stateStore.put(state, redirect, verifier, nonce);
            String authUrl = meta.authorizationEndpoint()
                    + "?response_type=code"
                    + "&client_id="              + enc(config.clientId())
                    + "&redirect_uri="           + enc(absoluteRedirectUri(req))
                    + "&scope="                  + enc(config.scopes())
                    + "&state="                  + state
                    + "&nonce="                  + enc(nonce)
                    + "&code_challenge="         + challenge
                    + "&code_challenge_method=S256";
            res.redirect(authUrl);
            return null;
        });
        // ── GET {prefix}/callback ─────────────────────────────────────────────
        // Validates state, exchanges code for tokens, creates session, redirects.
        app.get(prefix + "/callback", (req, res) -> {
            String error = req.query("error");
            if (error != null) {
                res.status(400);
                return "Authentication error: " + error
                        + (req.query("error_description") != null
                           ? " — " + req.query("error_description") : "");
            }
            String code  = req.query("code");
            String state = req.query("state");
            OidcStateStore.Entry entry = stateStore.consumeAndRemove(state).orElse(null);
            if (entry == null) {
                res.status(400);
                return "Invalid or expired state parameter";
            }
            OidcTokenResponse tokens = tokenClient.exchangeCode(
                    meta.tokenEndpoint(), code, absoluteRedirectUri(req), entry.codeVerifier());
            // Validate ID token: signature + iss + aud + exp + iat + sub + nonce (OIDC Core §3.1.3.7)
            if (tokens.idToken() != null) {
                try {
                    validator.validateIdToken(tokens.idToken(), entry.nonce());
                } catch (OidcValidationException e) {
                    res.status(400);
                    return "ID token validation failed: " + e.getMessage();
                }
            }
            Map<String, Object> claims = mergeClaims(tokens);
            OidcSession session = new OidcSession(
                    UUID.randomUUID().toString(),
                    tokens.accessToken(), tokens.idToken(), tokens.refreshToken(),
                    Instant.now().plusSeconds(tokens.expiresIn()), claims);
            config.sessionStore().save(session);
            res.header("Set-Cookie", sessionCookie(session.id()))
               .redirect(entry.originalUrl());
            return null;
        });
        // ── POST {prefix}/logout ──────────────────────────────────────────────
        // Invalidates the local session and redirects to end_session_endpoint.
        app.post(prefix + "/logout", (req, res) -> {
            String sessionId   = OidcMiddleware.cookieValue(req, "oidc_session");
            String idTokenHint = null;
            if (sessionId != null) {
                OidcSession session = config.sessionStore().find(sessionId).orElse(null);
                if (session != null) idTokenHint = session.idToken();
                config.sessionStore().delete(sessionId);
            }
            String clearCookie = "oidc_session=; HttpOnly; Path=/; Max-Age=0; SameSite=Lax";
            String location;
            if (meta.endSessionEndpoint() != null) {
                String postLogout = absoluteSelf(req, config.postLogoutRedirectUri());
                StringBuilder url = new StringBuilder(meta.endSessionEndpoint())
                        .append("?post_logout_redirect_uri=").append(enc(postLogout));
                if (idTokenHint != null)
                    url.append("&id_token_hint=").append(enc(idTokenHint));
                location = url.toString();
            } else {
                location = config.postLogoutRedirectUri();
            }
            res.header("Set-Cookie", clearCookie).redirect(location);
            return null;
        });
        // Register OpenAPI security scheme if flash-ext-openapi is on the classpath.
        try {
            OpenApiIntegration.register(ctx, config, meta);
        } catch (NoClassDefFoundError ignored) {
            // flash-ext-openapi not available — OpenAPI integration disabled
        }
    }
    // ── Helpers ───────────────────────────────────────────────────────────────
    /**
     * Merges claims from both the access token and the ID token.
     * ID token values win on conflict so that verified identity claims are authoritative.
     */
    private static Map<String, Object> mergeClaims(OidcTokenResponse tokens) {
        Map<String, Object> merged = new HashMap<>();
        if (tokens.accessToken() != null) merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
        if (tokens.idToken()     != null) merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
        return Map.copyOf(merged);
    }
    /**
     * Builds an {@link HttpClient}. If {@link OidcConfig#insecureTls()} is set,
     * installs a trust-all {@link SSLContext} that accepts any certificate.
     * <b>Only safe for development with self-signed certificates.</b>
     */
    private static HttpClient buildHttpClient(OidcConfig config) {
        if (!config.insecureTls()) return HttpClient.newHttpClient();
        try {
            TrustManager[] trustAll = { new X509TrustManager() {
                public X509Certificate[] getAcceptedIssuers()                 { return new X509Certificate[0]; }
                public void checkClientTrusted(X509Certificate[] c, String a) {}
                public void checkServerTrusted(X509Certificate[] c, String a) {}
            }};
            SSLContext sslCtx = SSLContext.getInstance("TLS");
            sslCtx.init(null, trustAll, new SecureRandom());
            return HttpClient.newBuilder().sslContext(sslCtx).build();
        } catch (Exception e) {
            throw new IllegalStateException("Failed to create trust-all SSLContext", e);
        }
    }
    private String absoluteRedirectUri(Request req) {
        return absoluteSelf(req, config.redirectUri());
    }
    private String absoluteSelf(Request req, String uri) {
        if (!uri.startsWith("/")) return uri;
        return OidcMiddleware.selfOrigin(req, config.selfScheme()) + uri;
    }
    private static String enc(String v) {
        return URLEncoder.encode(v, StandardCharsets.UTF_8);
    }
    private static String sessionCookie(String id) {
        return "oidc_session=" + id + "; HttpOnly; Path=/; SameSite=Lax";
    }
    /**
     * Loaded lazily so that {@code flash-ext-openapi} classes are only resolved at
     * runtime when {@link OpenApiContributorRegistry} is actually on the classpath.
     */
    private static final class OpenApiIntegration {
        static void register(FlashContext ctx,
                             OidcConfig config, OidcProviderMetadata meta) {
            ctx.find(OpenApiContributorRegistry.class)
               .ifPresent(registry -> registry.add(new OpenApiContributor() {
                    @Override
                    public Map<String, Object> componentContributions() {
                        Map<String, String> scopesMap = new LinkedHashMap<>();
                        for (String s : config.scopes().split("\\s+")) {
                            if (!s.isBlank()) scopesMap.put(s, s);
                        }
                        Map<String, Object> flow = new LinkedHashMap<>();
                        flow.put("authorizationUrl", meta.authorizationEndpoint());
                        flow.put("tokenUrl",         meta.tokenEndpoint());
                        flow.put("scopes",           scopesMap);
                        Map<String, Object> scheme = new LinkedHashMap<>();
                        scheme.put("type",  "oauth2");
                        scheme.put("flows", Map.of("authorizationCode", flow));
                        Map<String, Object> securitySchemes = new LinkedHashMap<>();
                        securitySchemes.put(config.schemeName(), scheme);
                        return Map.of("securitySchemes", securitySchemes);
                    }
                     @Override
                     public OpenApiOperationContribution operationFor(Class<?> handlerClass) {
                        OpenApiOperationContribution.Builder out =
                                OpenApiOperationContribution.builder();
                        List<String> operationScopes = OidcAuthPolicy.openApiScopesFor(handlerClass);
                        if (operationScopes != null) {
                            out.security(config.schemeName(), operationScopes);
                        }
                        OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
                        if (policy == null || policy.optionalAuth()) return out.build();
                        out.response(401, OpenApiResponseContribution.of("Authentication required"));
                        String[] roles = policy.requiredRoles();
                        String[] scopes = policy.requiredScopes();
                        if (roles.length == 0 && scopes.length == 0) return out.build();
                        String roleMessage = roles.length == 0 ? null : roleRequiredMessage(roles);
                        String scopeMessage = scopes.length == 0 ? null : scopeRequiredMessage(scopes);
                        if (roleMessage != null && scopeMessage != null) {
                            out.response(403, OpenApiResponseContribution.of(roleMessage + "; " + scopeMessage));
                        } else
                            out.response(403, OpenApiResponseContribution.of(Objects.requireNonNullElse(roleMessage, scopeMessage)));
                        return out.build();
                     }
                }));
        }
        private static String roleRequiredMessage(String[] roles) {
            if (roles.length == 1) return "\"" + roles[0] + "\" role required";
            return "Roles \"" + String.join(", ", roles) + "\" are required";
        }
        private static String scopeRequiredMessage(String[] scopes) {
            if (scopes.length == 1) return "\"" + scopes[0] + "\" scope required";
            return "Scopes \"" + String.join(", ", scopes) + "\" are required";
        }
    }
 }
@@ -1,550 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import dev.relism.flash.exceptions.HttpException;
 import dev.relism.flash.extension.FlashContext;
 import dev.relism.flash.models.Response;
 import dev.relism.flash.models.Request;
 import dev.relism.flash.routing.Middleware;
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 /**
 * Request-level OIDC middleware. Exposed in the {@link FlashContext}
 * for manual use on lambda routes; injected automatically for handlers annotated with
 * {@link Authenticated}, {@link RolesAllowed} or {@link ScopesAllowed}.
 *
 * <p>Resolution order on each request:
 * <ol>
 *   <li>{@code Authorization: Bearer ...} header — validated via JWKS ({@link JwtValidator}).</li>
 *   <li>{@code oidc_session} cookie — looked up in {@link OidcSessionStore}; transparently
 *       refreshed if the access token is expired.</li>
 *   <li>Browser clients (no {@code Accept: application/json}) → redirect to
 *       {@code {routePrefix}/login?redirect={path}}.</li>
 *   <li>API clients → 401.</li>
 * </ol>
 *
 * <pre>{@code
 * // Manual use on a lambda route:
 * OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
 * app.get("/api/me", (req, res) -> ClaimsHolder.claim("sub"), oidc.protect());
 * app.delete("/admin/users/{id}", handler, oidc.requireRole("admin"));
 * }</pre>
 */
 public class OidcMiddleware {
    private static final String BEARER = "Bearer";
    private final JwtValidator         validator;
    private final OidcConfig           config;
    private final OidcProviderMetadata meta;
    private final TokenClient          tokenClient;
    private final String[]             roleClaimPathParts;
    private final String[][]           scopeClaimPathParts;
    OidcMiddleware(JwtValidator validator, OidcConfig config,
                   OidcProviderMetadata meta, TokenClient tokenClient) {
        this.validator   = validator;
        this.config      = config;
        this.meta        = meta;
        this.tokenClient = tokenClient;
        this.roleClaimPathParts = splitClaimPath(config.rolesClaimPath());
        this.scopeClaimPathParts = splitClaimPaths(config.scopeClaimPaths());
    }
    // -- Public API -----------------------------------------------------------
    /** The single configured claim path used by every transport for role checks. */
    public String rolesClaimPath() { return config.rolesClaimPath(); }
    /**
     * Validates the bearer token or session cookie. Browser clients are redirected
     * to the login page on failure; API clients receive 401.
     */
    public Middleware protect() {
        return protect(null);
    }
    /**
     * Like {@link #protect()}, but a 401 challenge also carries {@code resource_metadata}
     * (RFC 9728 §5.1), resolved against this request's own scheme/host exactly like
     * {@link OidcExtension}'s redirect URIs. {@code resourceMetadataPath} is an absolute path
     * (e.g. {@code "/.well-known/oauth-protected-resource/mcp"}); pass {@code null} for plain
     * challenges. Used by {@code flash-ext-mcp} to make its Protected Resource Metadata
     * document discoverable straight from the {@code WWW-Authenticate} header, per the MCP
     * Authorization spec.
     */
    public Middleware protect(String resourceMetadataPath) {
        return next -> (req, res) -> {
            Map<String, Object> claims = resolve(req, res, resourceMetadataPath);
            if (claims == null) return null;    // redirect already written
            ClaimsHolder.set(claims);
            try {
                return next.handle(req, res);
            } finally {
                ClaimsHolder.clear();
            }
        };
    }
    /** OIDC issuer this middleware validates tokens against — the {@code iss} claim it enforces. */
    public String issuer() { return config.issuer(); }
    /** Scheme used to build this app's own absolute URLs — see {@link OidcConfig#selfScheme()}. */
    public String selfScheme() { return config.selfScheme(); }
    /**
     * Silently populates {@link ClaimsHolder} if a valid bearer token or session cookie
     * is present, but never rejects or redirects unauthenticated requests. Use this on
     * public routes that want to personalise the response when the user happens to be
     * logged in (e.g. showing a username on a landing page).
     *
     * <pre>{@code
     * app.get("/", handler, oidc.optional());
     * // Inside handler: ClaimsHolder.user() is non-null iff the user is logged in.
     * }</pre>
     */
    public Middleware optional() {
        return next -> (req, res) -> {
            Map<String, Object> claims = resolveQuiet(req);
            if (claims != null) ClaimsHolder.set(claims);
            try {
                return next.handle(req, res);
            } finally {
                ClaimsHolder.clear();
            }
        };
    }
    /**
     * Compiled authorization policy path used by annotation-driven mounting.
     * The policy is immutable and built once at boot.
     */
    public Middleware authorize(OidcAuthPolicy policy) {
        if (policy.optionalAuth()) return optional();
        return next -> (req, res) -> {
            Map<String, Object> claims = resolve(req, res);
            if (claims == null) return null;
            enforcePolicy(claims, policy, res);
            ClaimsHolder.set(claims);
            try {
                return next.handle(req, res);
            } finally {
                ClaimsHolder.clear();
            }
        };
    }
    /**
     * Like {@link #protect()} but also enforces that the caller holds at least one
     * of the given roles (OR semantics). Roles are extracted via
     * {@link OidcConfig#rolesClaimPath()}.
     */
    public Middleware requireRole(String... roles) {
        return authorize(OidcAuthPolicy.rolesAny(roles));
    }
    /**
     * Requires all listed scopes to be present in the token.
     * Scopes are resolved from configured claim paths (default: {@code scope,scp}).
     */
    public Middleware requireScopes(String... scopes) {
        return authorize(OidcAuthPolicy.scopes(scopes, ScopesAllowed.Match.ALL));
    }
    /**
     * Requires at least one of the listed scopes to be present in the token.
     * Scopes are resolved from configured claim paths (default: {@code scope,scp}).
     */
    public Middleware requireAnyScope(String... scopes) {
        return authorize(OidcAuthPolicy.scopes(scopes, ScopesAllowed.Match.ANY));
    }
    // -- Package-private: AnnotationProcessor hooks ---------------------------
    Middleware authenticatedMiddleware()          { return protect(); }
    Middleware optionalMiddleware()               { return optional(); }
    Middleware rolesMiddleware(String[] required) { return requireRole(required); }
    Middleware scopesMiddleware(String[] required, ScopesAllowed.Match match) {
        return authorize(OidcAuthPolicy.scopes(required, match));
    }
    Middleware policyMiddleware(OidcAuthPolicy policy) { return authorize(policy); }
    // -- Internals ------------------------------------------------------------
    /**
     * Like {@link #resolve} but never redirects or throws — returns {@code null} silently
     * when no valid credentials are present. Used by {@link #optional()}.
     */
    private Map<String, Object> resolveQuiet(Request req) {
        String bearerToken = extractBearerToken(req.header("Authorization"));
        if (bearerToken != null) {
            try {
                return validator.validate(bearerToken);
            } catch (Exception ignored) {
                return null;
            }
        }
        String sessionId = cookieValue(req, "oidc_session");
        if (sessionId != null) {
            Optional<OidcSession> found = config.sessionStore().find(sessionId);
            if (found.isPresent()) {
                OidcSession session = found.get();
                if (!session.isAccessTokenExpired())
                    return session.claims();
                if (session.refreshToken() != null) {
                    try {
                        OidcSession refreshed = doRefresh(session);
                        config.sessionStore().save(refreshed);
                        return refreshed.claims();
                    } catch (Exception ignored) { }
                }
                config.sessionStore().delete(sessionId);
            }
        }
        return null;
    }
    /**
     * Returns claims on success, or {@code null} if a redirect was already written to
     * {@code res}. Throws {@link HttpException} 401/403 for API clients.
     */
    private Map<String, Object> resolve(Request req, Response res) {
        return resolve(req, res, null);
    }
    private Map<String, Object> resolve(Request req, Response res, String resourceMetadataPath) {
        // 1. Bearer token
        String bearerToken = extractBearerToken(req.header("Authorization"));
        if (bearerToken != null) {
            try {
                return validator.validate(bearerToken);
            } catch (HttpException e) {
                res.header("WWW-Authenticate", invalidTokenChallenge(req, resourceMetadataPath));
                throw e;
            }
        }
        // 2. Session cookie
        String sessionId = cookieValue(req, "oidc_session");
        if (sessionId != null) {
            Optional<OidcSession> found = config.sessionStore().find(sessionId);
            if (found.isPresent()) {
                OidcSession session = found.get();
                if (!session.isAccessTokenExpired())
                    return session.claims();
                // Access token expired — try silent refresh
                if (session.refreshToken() != null) {
                    try {
                        OidcSession refreshed = doRefresh(session);
                        config.sessionStore().save(refreshed);
                        return refreshed.claims();
                    } catch (Exception ignored) {
                        // Refresh failed — fall through to re-authenticate
                    }
                }
                config.sessionStore().delete(sessionId);
            }
        }
        // 3. No valid credentials
        String accept = req.header("Accept");
        if (accept != null && accept.contains("application/json")) {
            res.header("WWW-Authenticate", bearerChallenge(req, resourceMetadataPath));
            throw HttpException.unauthorized();
        }
        // Browser — redirect to login, preserving the original URL in state
        String loginUrl = config.routePrefix() + "/login?redirect="
                + URLEncoder.encode(req.path(), StandardCharsets.UTF_8);
        res.redirect(loginUrl);
        return null;
    }
    private OidcSession doRefresh(OidcSession old) throws Exception {
        OidcTokenResponse tokens = tokenClient.refresh(
                meta.tokenEndpoint(), old.refreshToken());
        Map<String, Object> claims = mergeRefreshedClaims(tokens, old);
        return new OidcSession(
                old.id(),
                tokens.accessToken(),
                tokens.idToken() != null ? tokens.idToken() : old.idToken(),
                tokens.refreshToken() != null ? tokens.refreshToken() : old.refreshToken(),
                Instant.now().plusSeconds(tokens.expiresIn()),
                claims
        );
    }
    private void enforcePolicy(Map<String, Object> claims, OidcAuthPolicy policy, Response res) {
        checkRoles(claims, policy.requiredRoles());
        checkScopes(claims, policy.requiredScopes(), policy.scopeMatch(), res);
    }
    private void checkRoles(Map<String, Object> claims, String[] required) {
        if (required.length == 0) return;
        if (rolesAllowed(claims, required)) return;
        throw HttpException.forbidden();
    }
    private void checkScopes(Map<String, Object> claims, String[] required, ScopesAllowed.Match match,
                             Response res) {
        if (required.length == 0) return;
        if (scopesAllowed(claims, required, match)) return;
        res.header("WWW-Authenticate", insufficientScopeChallenge(required));
        throw HttpException.forbidden();
    }
    static String extractBearerToken(String authorizationHeader) {
        if (authorizationHeader == null) return null;
        int len = authorizationHeader.length();
        int start = 0;
        while (start < len && Character.isWhitespace(authorizationHeader.charAt(start))) start++;
        int schemeEnd = start + BEARER.length();
        if (schemeEnd > len || !authorizationHeader.regionMatches(true, start, BEARER, 0, BEARER.length())) {
            return null;
        }
        if (schemeEnd == len || !Character.isWhitespace(authorizationHeader.charAt(schemeEnd))) {
            return null;
        }
        int tokenStart = schemeEnd;
        while (tokenStart < len && Character.isWhitespace(authorizationHeader.charAt(tokenStart))) tokenStart++;
        if (tokenStart >= len) return null;
        int tokenEnd = len;
        while (tokenEnd > tokenStart && Character.isWhitespace(authorizationHeader.charAt(tokenEnd - 1))) tokenEnd--;
        return tokenEnd > tokenStart ? authorizationHeader.substring(tokenStart, tokenEnd) : null;
    }
    String bearerChallenge() {
        return bearerChallenge(null, null);
    }
    private String bearerChallenge(Request req, String resourceMetadataPath) {
        String base = BEARER + " realm=\"" + quoted(config.schemeName()) + "\"";
        if (resourceMetadataPath == null) return base;
        return base + ", resource_metadata=\"" + quoted(absoluteSelf(req, resourceMetadataPath)) + "\"";
    }
    String invalidTokenChallenge() {
        return invalidTokenChallenge(null, null);
    }
    private String invalidTokenChallenge(Request req, String resourceMetadataPath) {
        return bearerChallenge(req, resourceMetadataPath) + ", error=\"invalid_token\"";
    }
    String insufficientScopeChallenge(String[] requiredScopes) {
        return bearerChallenge() + ", error=\"insufficient_scope\", scope=\""
                + quoted(spaceDelimited(requiredScopes)) + "\"";
    }
    private String absoluteSelf(Request req, String path) {
        if (!path.startsWith("/")) return path;
        return selfOrigin(req, config.selfScheme()) + path;
    }
    /**
     * {@code scheme://host} clients actually reach this app on — the basis for every absolute
     * URL it publishes about itself (OAuth2 {@code redirect_uri}, the RFC 9728 resource
     * identifier and the {@code resource_metadata} challenge). Behind a reverse proxy the
     * request's own {@code Host} is the upstream address the proxy dialled, so
     * {@code X-Forwarded-Host}/{@code -Proto} win whenever present: without them the app would
     * name an address no client can resolve, and OAuth2 discovery fails with no error anyone
     * can trace back to here. Trusted unconditionally — a caller able to reach this app without
     * passing the proxy can do worse than spoof a self URL.
     */
    public static String selfOrigin(Request req, String fallbackScheme) {
        String forwardedHost = req.header("X-Forwarded-Host");
        if (forwardedHost == null) return fallbackScheme + "://" + req.header("Host");
        String forwardedProto = req.header("X-Forwarded-Proto");
        return (forwardedProto != null ? forwardedProto : fallbackScheme) + "://" + forwardedHost;
    }
    private static String spaceDelimited(String[] values) {
        if (values == null || values.length == 0) return "";
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < values.length; i++) {
            if (i > 0) sb.append(' ');
            sb.append(values[i]);
        }
        return sb.toString();
    }
    private static String quoted(String value) {
        StringBuilder out = new StringBuilder(value.length() + 8);
        for (int i = 0; i < value.length(); i++) {
            char c = value.charAt(i);
            if (c == '"' || c == '\\') out.append('\\');
            out.append(c);
        }
        return out.toString();
    }
    boolean rolesAllowed(Map<String, Object> claims, String[] required) {
        Object actual = valueAtPath(claims, roleClaimPathParts);
        if (actual == null) return false;
        for (String role : required) {
            if (containsToken(actual, role)) return true;
        }
        return false;
    }
    boolean scopesAllowed(Map<String, Object> claims, String[] required, ScopesAllowed.Match match) {
        if (match == ScopesAllowed.Match.ALL) {
            for (String scope : required) {
                if (!hasScope(claims, scope)) return false;
            }
            return true;
        }
        for (String scope : required) {
            if (hasScope(claims, scope)) return true;
        }
        return false;
    }
    private boolean hasScope(Map<String, Object> claims, String scope) {
        for (String[] pathParts : scopeClaimPathParts) {
            Object value = valueAtPath(claims, pathParts);
            if (value != null && containsToken(value, scope)) return true;
        }
        return false;
    }
    private static Object valueAtPath(Map<String, Object> claims, String[] pathParts) {
        Object current = claims;
        for (String part : pathParts) {
            if (!(current instanceof Map<?, ?> map)) return null;
            current = map.get(part);
            if (current == null) return null;
        }
        return current;
    }
    private static boolean containsToken(Object source, String token) {
        if (source instanceof String s) return containsDelimitedToken(s, token);
        if (source instanceof List<?> list) {
            for (Object item : list) {
                if (item == null) continue;
                if (tokenEquals(item.toString(), token)) return true;
            }
            return false;
        }
        if (source instanceof Object[] arr) {
            for (Object item : arr) {
                if (item == null) continue;
                if (tokenEquals(item.toString(), token)) return true;
            }
            return false;
        }
        return tokenEquals(source.toString(), token);
    }
    private static boolean containsDelimitedToken(String value, String token) {
        int len = value.length();
        int i = 0;
        while (i < len) {
            while (i < len && isScopeDelimiter(value.charAt(i))) i++;
            int start = i;
            while (i < len && !isScopeDelimiter(value.charAt(i))) i++;
            int end = i;
            if (end > start && end - start == token.length() && value.regionMatches(start, token, 0, token.length())) {
                return true;
            }
        }
        return false;
    }
    private static boolean tokenEquals(String value, String token) {
        int start = 0;
        int end = value.length();
        while (start < end && Character.isWhitespace(value.charAt(start))) start++;
        while (end > start && Character.isWhitespace(value.charAt(end - 1))) end--;
        return end - start == token.length() && value.regionMatches(start, token, 0, token.length());
    }
    private static boolean isScopeDelimiter(char c) {
        return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == ',';
    }
    private static String[] splitClaimPath(String path) {
        if (path == null || path.isBlank()) {
            throw new IllegalStateException("OIDC claim path cannot be blank");
        }
        List<String> parts = new ArrayList<>(4);
        int start = 0;
        int len = path.length();
        for (int i = 0; i <= len; i++) {
            if (i == len || path.charAt(i) == '.') {
                String p = path.substring(start, i).trim();
                if (!p.isEmpty()) parts.add(p);
                start = i + 1;
            }
        }
        if (parts.isEmpty()) {
            throw new IllegalStateException("OIDC claim path cannot be blank");
        }
        return parts.toArray(String[]::new);
    }
    private static String[][] splitClaimPaths(String paths) {
        String source = (paths == null || paths.isBlank()) ? "scope,scp" : paths;
        List<String[]> out = new ArrayList<>(4);
        int start = 0;
        int len = source.length();
        for (int i = 0; i <= len; i++) {
            if (i == len || source.charAt(i) == ',') {
                String raw = source.substring(start, i).trim();
                if (!raw.isEmpty()) out.add(splitClaimPath(raw));
                start = i + 1;
            }
        }
        if (out.isEmpty()) {
            return new String[][]{ splitClaimPath("scope"), splitClaimPath("scp") };
        }
        return out.toArray(String[][]::new);
    }
    private static Map<String, Object> mergeRefreshedClaims(OidcTokenResponse tokens, OidcSession old) {
        Map<String, Object> merged = new HashMap<>();
        // Fall back to old claims first, then overlay fresh token claims
        merged.putAll(old.claims());
        if (tokens.accessToken() != null)
            merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
        if (tokens.idToken() != null)
            merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
        return Map.copyOf(merged);
    }
    // -- Shared cookie utility (also used by OidcExtension) -------------------
    static String cookieValue(Request req, String name) {
        String header = req.header("Cookie");
        if (header == null || header.isBlank()) return null;
        int len   = header.length();
        int start = 0;
        while (start < len) {
            int semi = header.indexOf(';', start);
            int end  = semi < 0 ? len : semi;
            int eq   = header.indexOf('=', start);
            if (eq > start && eq < end) {
                int ns = start, ne = eq;
                while (ns < ne && header.charAt(ns)   == ' ') ns++;
                while (ne > ns && header.charAt(ne-1) == ' ') ne--;
                if (ne - ns == name.length() && header.regionMatches(ns, name, 0, name.length()))
                    return header.substring(eq + 1, end).strip();
            }
            start = end + 1;
        }
        return null;
    }
 }
@@ -1,15 +0,0 @@
 package dev.relism.flash.ext.oidc;
 /**
 * OIDC provider endpoints discovered from {@code {issuer}/.well-known/openid-configuration}.
 *
 * <p>{@link #endSessionEndpoint()} may be {@code null} — not all providers expose it
 * (e.g. some Authelia configurations omit it).
 */
 public record OidcProviderMetadata(
        String authorizationEndpoint,
        String tokenEndpoint,
        String userinfoEndpoint,
        String jwksUri,
        String endSessionEndpoint       // nullable
 ) {}
@@ -1,47 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.time.Instant;
 import java.util.Map;
 /**
 * An authenticated user's OIDC session — persisted in {@link OidcSessionStore} and
 * looked up via the {@code oidc_session} cookie on every request.
 *
 * <p>Sessions are immutable; a refreshed access token produces a new instance
 * that replaces the old one in the store (same {@link #id()}).
 */
 public final class OidcSession {
    private final String              id;
    private final String              accessToken;
    private final String              idToken;
    private final String              refreshToken;        // may be null
    private final Instant             accessTokenExpiresAt;
    private final Map<String, Object> claims;              // decoded from id_token
    public OidcSession(String id, String accessToken, String idToken,
                       String refreshToken, Instant accessTokenExpiresAt,
                       Map<String, Object> claims) {
        this.id                   = id;
        this.accessToken          = accessToken;
        this.idToken              = idToken;
        this.refreshToken         = refreshToken;
        this.accessTokenExpiresAt = accessTokenExpiresAt;
        this.claims               = Map.copyOf(claims);
    }
    /**
     * Returns {@code true} if the access token has expired or will expire within
     * the next 30 seconds (eager refresh to avoid mid-request expiry).
     */
    public boolean isAccessTokenExpired() {
        return Instant.now().isAfter(accessTokenExpiresAt.minusSeconds(30));
    }
    public String              id()                   { return id; }
    public String              accessToken()          { return accessToken; }
    public String              idToken()              { return idToken; }
    public String              refreshToken()         { return refreshToken; }
    public Instant             accessTokenExpiresAt() { return accessTokenExpiresAt; }
    public Map<String, Object> claims()               { return claims; }
 }
@@ -1,14 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.util.Optional;
 /**
 * Backing store for {@link OidcSession} objects. The default implementation is
 * {@link InMemoryOidcSessionStore}; supply a custom one via
 * {@link OidcConfig.Builder#sessionStore(OidcSessionStore)} for Redis, JDBC, etc.
 */
 public interface OidcSessionStore {
    void save(OidcSession session);
    Optional<OidcSession> find(String sessionId);
    void delete(String sessionId);
 }
@@ -1,39 +0,0 @@
 package dev.relism.flash.ext.oidc;
 import java.time.Instant;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 /**
 * Short-lived store mapping state nonces → (original URL, PKCE verifier).
 *
 * <p>Entries expire after {@value #TTL_SECONDS} seconds. Cleanup runs on every
 * access to prevent unbounded growth without needing a background thread.
 */
 final class OidcStateStore {
    static final int TTL_SECONDS = 600; // 10 minutes
    record Entry(String originalUrl, String codeVerifier, String nonce, Instant expiresAt) {}
    private final ConcurrentHashMap<String, Entry> store = new ConcurrentHashMap<>();
    void put(String state, String originalUrl, String codeVerifier, String nonce) {
        cleanup();
        store.put(state, new Entry(originalUrl, codeVerifier, nonce,
                Instant.now().plusSeconds(TTL_SECONDS)));
    }
    /** Atomically retrieves and removes the entry; returns empty if absent or expired. */
    Optional<Entry> consumeAndRemove(String nonce) {
        cleanup();
        Entry e = store.remove(nonce);
        if (e == null || Instant.now().isAfter(e.expiresAt())) return Optional.empty();
        return Optional.of(e);
    }
    private void cleanup() {
        Instant now = Instant.now();
        store.entrySet().removeIf(kv -> now.isAfter(kv.getValue().expiresAt()));
    }
 }
--- a/Show More
+++ b/Show More