refactor(ext-auth): generic sessions, shared annotation wiring, rename to flash-ext-auth-oidc

AuthMiddleware.install(ctx, config, source) now owns the annotation processor and the flash.auth.policy key, so a second credential source gets annotation-driven authorization without copying the wiring. The key is public: an extension that contributes middleware can order itself around authentication. OidcSession becomes Session in auth-core, carrying claims, an expiry and an opaque attribute map. OpenID Connect keeps its access, id and refresh tokens in that map under its own keys, so renewal stays its business and core has no OAuth2 vocabulary in it. isAccessTokenExpired() becomes isExpired(), with the 30s eager-renewal window it always had and now a test for it. flash-ext-oidc is renamed flash-ext-auth-oidc, matching cache-core/cache-caffeine and data-core/data-hibernate.
2026-09-10 19:06:15 +00:00
parent c5be6ac7b8
commit 9d39e24ccb
45 changed files with 271 additions and 166 deletions
@@ -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-auth-oidc`.

 ## 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**: optional, policy-driven OAuth2 via `flash-ext-auth-oidc` — 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.

@@ -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-auth-oidc` already handles its own internal JSON needs (`json-smart` 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.
@@ -1,7 +1,7 @@
 # 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
+`flash-ext-auth-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.

@@ -7,10 +7,10 @@ Allowed Client Scopes configuration `scopes_supported` needs to actually work.

 ## `McpSecurity`

-`McpConfig.security(...)` controls how the MCP endpoint reacts to `flash-ext-oidc` being
+`McpConfig.security(...)` controls how the MCP endpoint reacts to `flash-ext-auth-oidc` being
 installed (`ctx.find(OidcMiddleware.class)`), resolved once at boot in `McpExtension.routes()`:

-| Policy | `flash-ext-oidc` installed | `flash-ext-oidc` absent |
+| Policy | `flash-ext-auth-oidc` installed | `flash-ext-auth-oidc` absent |
 |---|---|---|
 | `REQUIRED` | protected | **boot fails** (`IllegalStateException`) |
 | `AUTO` (default) | protected | runs unprotected, logs a warning |
@@ -21,18 +21,18 @@ turns "someone forgot to wire up OAuth2" into a startup crash instead of a silen
 endpoint. `AUTO` is meant for local development, where spinning up a real identity provider is
 friction you don't want yet.

-## Why `flash-ext-oidc` is an *optional* Maven dependency, concretely
+## Why `flash-ext-auth-oidc` is an *optional* Maven dependency, concretely

 Maven's `<optional>true</optional>` only affects **transitive** propagation: consumers of
-`flash-ext-mcp` don't get `flash-ext-oidc` pulled in automatically unless they add it themselves.
-Within `flash-ext-mcp` itself, `flash-ext-oidc`'s classes are on the compile/test classpath as
+`flash-ext-mcp` don't get `flash-ext-auth-oidc` pulled in automatically unless they add it themselves.
+Within `flash-ext-mcp` itself, `flash-ext-auth-oidc`'s classes are on the compile/test classpath as
 normal — this extension can (and does) reference `OidcMiddleware`/`ClaimsHolder` directly in
 source.

 That reference is isolated in its own class, `McpOidcIntegration`, invoked only from inside a
 `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
+evaluated — if `flash-ext-auth-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
@@ -45,7 +45,7 @@ When oidc is available and `security() != NONE`, `McpOidcIntegration` (an isolat
 lazily-loaded bridge — see its javadoc) derives everything an MCP OAuth2 resource server needs
 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)`
+1. The MCP route is wrapped with `flash-ext-auth-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.
@@ -114,7 +114,7 @@ unaffected — this parameter is additive and MCP-specific.

 ## Per-tool `@RolesAllowed`/`@ScopesAllowed`

-`McpTool` subclasses can carry `flash-ext-oidc`'s `@RolesAllowed`/`@ScopesAllowed`:
+`McpTool` subclasses can carry `flash-ext-auth-oidc`'s `@RolesAllowed`/`@ScopesAllowed`:

 ```java
@Tool(name = "delete_route", description = "Delete a route")
@@ -124,7 +124,7 @@ public class DeleteRouteTool extends McpTool {
 }
 ```

-This does **not** reuse `flash-ext-oidc`'s per-route middleware mechanism (`ctx.addAnnotationProcessor`,
+This does **not** reuse `flash-ext-auth-oidc`'s per-route middleware mechanism (`ctx.addAnnotationProcessor`,
 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,
@@ -156,7 +156,7 @@ at `app.start()`.

 ## The `HttpException` safety net

-`flash-ext-oidc`'s middleware throws `HttpException.unauthorized()`/`forbidden()` on auth
+`flash-ext-auth-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
@@ -19,7 +19,7 @@
        </dependency>
        <dependency>
            <groupId>dev.relism</groupId>
-            <artifactId>flash-ext-oidc</artifactId>
+            <artifactId>flash-ext-auth-oidc</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
@@ -10,7 +10,7 @@ import java.util.function.Supplier;
 *
 * <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
+ * flash-ext-auth-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}.
@@ -91,7 +91,7 @@ public final class McpConfig {
        /**
         * Canonical URI of this MCP endpoint, used for RFC 8707 audience binding: tokens whose
         * {@code aud} claim does not include this value are rejected. Optional — when
-         * {@code flash-ext-oidc} is installed, this is auto-derived per request from the
+         * {@code flash-ext-auth-oidc} is installed, this is auto-derived per request from the
         * forwarded/{@code Host} headers (same resolution {@code OidcExtension} uses for its own
         * redirect URIs) and audience binding is enforced unconditionally. Set this explicitly
         * only to override that guess — a reverse proxy that forwards neither
@@ -102,7 +102,7 @@ public final class McpConfig {
        /**
         * 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
+         * — when {@code flash-ext-auth-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).
         */
@@ -25,7 +25,7 @@ import java.util.List;
 *         .build()))
 *     .start();
 *
- * // With flash-ext-oidc as the OAuth2 resource server — zero extra config: issuer, canonical
+ * // With flash-ext-auth-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)
@@ -83,20 +83,20 @@ public class McpExtension implements FlashExtension {
        try {
            resolved = McpOidcIntegration.resolve(ctx, config);
        } catch (NoClassDefFoundError e) {
-            resolved = null; // flash-ext-oidc not on the classpath at all
+            resolved = null; // flash-ext-auth-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() +
+                    "McpSecurity.REQUIRED but flash-ext-auth-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.",
+                "flash-ext-auth-oidc is not installed and McpSecurity.AUTO degrades to unprotected. " +
+                "Install flash-ext-auth-oidc or set McpSecurity.REQUIRED to make this a hard failure instead.",
                config.name());
        return null;
    }
@@ -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 — same reasoning {@code flash-ext-auth-oidc} 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.
 */
@@ -20,19 +20,19 @@ import java.util.function.Function;
 import java.util.function.Supplier;

 /**
- * Lazy, isolated bridge to {@code flash-ext-oidc} and {@code flash-ext-auth-core}.
+ * Lazy, isolated bridge to {@code flash-ext-auth-oidc} and {@code flash-ext-auth-core}.
 *
 * <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
+ * OAuth2) when {@code flash-ext-auth-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
+ * <p>Zero-config by design: when {@code flash-ext-auth-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 OidcCredentialSource}, with no additional {@link McpConfig} calls.
@@ -123,7 +123,7 @@ final class McpOidcIntegration {
        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 " +
+                    "@ScopesAllowed, but this MCP server has no active OAuth2 protection — flash-ext-auth-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() + ".");
@@ -175,7 +175,7 @@ final class McpRegistry {

    /**
     * Isolated the same way {@link McpOidcIntegration#resolve} is — {@code
-     * NoClassDefFoundError} here means {@code flash-ext-oidc} genuinely isn't on the runtime
+     * NoClassDefFoundError} here means {@code flash-ext-auth-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
@@ -2,16 +2,16 @@ package dev.relism.flash.ext.mcp;

 /**
 * OAuth2 requirement policy for the MCP endpoint, resolved against whether
- * {@code flash-ext-oidc} is installed ({@code ctx.find(OidcMiddleware.class)}).
+ * {@code flash-ext-auth-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. */
+    /** Fail fast at boot if {@code flash-ext-auth-oidc} is not installed — never expose an unprotected MCP endpoint. */
    REQUIRED,

-    /** Protect the endpoint if {@code flash-ext-oidc} is installed; otherwise run unprotected and log a warning. */
+    /** Protect the endpoint if {@code flash-ext-auth-oidc} is installed; otherwise run unprotected and log a warning. */
    AUTO,

-    /** Never protect the endpoint, even if {@code flash-ext-oidc} is installed elsewhere in the app. */
+    /** Never protect the endpoint, even if {@code flash-ext-auth-oidc} is installed elsewhere in the app. */
    NONE
 }
@@ -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-auth-oidc}'s middleware) 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
@@ -26,7 +26,7 @@ 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.
+ * framework. Exercises {@code flash-ext-auth-oidc}'s actual discovery + JWKS + JWT validation path.
 */
 final class FakeOidcProvider implements AutoCloseable {

@@ -16,7 +16,7 @@ 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}
+ * Exercises the actual OAuth2 resolution rules against a real {@code flash-ext-auth-oidc}
 * installation backed by {@link FakeOidcProvider} — real discovery, real JWKS, real RS256
 * tokens — plus the fail-fast/degrade behavior when oidc is absent.
 *