find(String sessionId);
- void delete(String sessionId);
-}
-```
-
-`InMemorySessionStore` is the default: a `ConcurrentHashMap`, fine for a single instance, and it
-loses every session on restart. Supply your own for Redis or JDBC when sessions have to survive a
-deploy or be shared across nodes.
-
-Sessions are immutable. Renewing one builds a new instance with the same `id()` and `save`s it
-over the old — there is no mutate-in-place path, so a store can cache or serialise freely.
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthConfig.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthConfig.java
deleted file mode 100644
index 6df58af..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthConfig.java
+++ /dev/null
@@ -1,43 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-/**
- * Where authorization reads its inputs from. Deliberately small: everything about *obtaining* a
- * credential belongs to the {@link CredentialSource} that produced it, and everything about
- * *checking* one is right here.
- *
- * Defaults are the generic spelling, not any one provider's. A source that knows better —
- * {@code flash-ext-auth-oidc} defaults roles to Keycloak's {@code realm_access.roles} — builds
- * its own {@code AuthConfig} with the paths its provider actually uses.
- */
-public final class AuthConfig {
-
- private final String rolesClaimPath;
- private final String scopeClaimPaths;
-
- private AuthConfig(Builder b) {
- this.rolesClaimPath = b.rolesClaimPath;
- this.scopeClaimPaths = b.scopeClaimPaths;
- }
-
- /** Dot-separated path to the roles list in the claims (default: {@code roles}). */
- public String rolesClaimPath() { return rolesClaimPath; }
-
- /** Comma-separated claim paths scopes are read from, in order (default: {@code scope,scp}). */
- public String scopeClaimPaths() { return scopeClaimPaths; }
-
- public static Builder builder() { return new Builder(); }
-
- public static final class Builder {
- private String rolesClaimPath = "roles";
- private String scopeClaimPaths = "scope,scp";
-
- private Builder() {}
-
- /** Dot-separated path to the roles list — e.g. {@code realm_access.roles}, {@code groups}. */
- public Builder rolesClaimPath(String path) { this.rolesClaimPath = path; return this; }
- /** Comma-separated claim paths scopes are read from, tried in order. */
- public Builder scopeClaimPaths(String paths) { this.scopeClaimPaths = paths; return this; }
-
- public AuthConfig build() { return new AuthConfig(this); }
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java
deleted file mode 100644
index 2c4a104..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java
+++ /dev/null
@@ -1,309 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import dev.relism.flash.exceptions.HttpException;
-import dev.relism.flash.extension.FlashContext;
-import dev.relism.flash.models.Request;
-import dev.relism.flash.models.Response;
-import dev.relism.flash.routing.Middleware;
-import dev.relism.flash.routing.MiddlewareKey;
-import dev.relism.flash.routing.MiddlewareNode;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Map;
-
-/**
- * Turns claims into a yes or a no. Exposed in the {@link FlashContext} for manual use on lambda
- * routes, and injected automatically for handlers annotated with {@link Authenticated},
- * {@link RolesAllowed} or {@link ScopesAllowed}.
- *
- *
It knows nothing about how the caller proved who they are — that is the
- * {@link CredentialSource} it is built with. What lives here is the half that is the same for
- * every mechanism: publish the claims for the request, match roles and scopes against them, clear
- * up afterwards.
- *
- *
{@code
- * AuthMiddleware auth = app.ctx().require(AuthMiddleware.class);
- * app.get("/api/me", (req, res) -> ClaimsHolder.claim("sub"), auth.protect());
- * app.delete("/admin/users/{id}", handler, auth.requireRole("admin"));
- * }
- */
-public class AuthMiddleware {
-
- /**
- * Boot-time identity of the node annotation-driven authorization mounts under. Public so an
- * extension that contributes its own middleware can order itself around authentication —
- * {@code MiddlewareNode.of(...).afterIfPresent(AuthMiddleware.POLICY)}.
- */
- public static final MiddlewareKey POLICY = MiddlewareKey.of("flash.auth.policy");
-
- private final AuthConfig config;
- private final CredentialSource source;
- private final String[] roleClaimPathParts;
- private final String[][] scopeClaimPathParts;
-
- public AuthMiddleware(AuthConfig config, CredentialSource source) {
- this.config = config;
- this.source = source;
- this.roleClaimPathParts = splitClaimPath(config.rolesClaimPath());
- this.scopeClaimPathParts = splitClaimPaths(config.scopeClaimPaths());
- }
-
- /**
- * Builds the middleware for {@code source}, publishes it in the context and registers the
- * annotation processor that mounts {@link Authenticated}, {@link RolesAllowed} and
- * {@link ScopesAllowed} on scanned handlers.
- *
- * Every extension that contributes a {@link CredentialSource} calls this rather than
- * repeating the wiring — the processor and the {@link #POLICY} key belong to one place.
- */
- public static AuthMiddleware install(FlashContext ctx, AuthConfig config, CredentialSource source) {
- AuthMiddleware middleware = new AuthMiddleware(config, source);
- ctx.provide(AuthMiddleware.class, middleware);
- ctx.addAnnotationProcessor(handlerClass -> {
- AuthPolicy policy = AuthPolicy.compileFromAnnotations(handlerClass);
- return policy != null
- ? List.of(MiddlewareNode.of(POLICY, middleware.authorize(policy)))
- : List.of();
- });
- return middleware;
- }
-
- // -- Public API -----------------------------------------------------------
-
- /** The single configured claim path used by every transport for role checks. */
- public String rolesClaimPath() { return config.rolesClaimPath(); }
-
- /** The source this middleware authenticates with. */
- public CredentialSource source() { return source; }
-
- /**
- * The same authorization rules against a different credential source. Used where one route
- * needs a variant of an installed source — {@code flash-ext-mcp} protects {@code /mcp} with an
- * OIDC source whose challenges carry RFC 9728 resource metadata, while every other route keeps
- * the plain one.
- */
- public AuthMiddleware withSource(CredentialSource source) {
- return new AuthMiddleware(config, source);
- }
-
- /**
- * Rejects the request unless the caller is authenticated. How it is rejected — a 401 with a
- * challenge, a redirect into a sign-in flow — is the source's decision, not this one's.
- */
- public Middleware protect() {
- return next -> (req, res) -> {
- Map claims = source.authenticate(req, res);
- if (claims == null) return null; // the source already answered the request
- ClaimsHolder.set(claims);
- try {
- return next.handle(req, res);
- } finally {
- ClaimsHolder.clear();
- }
- };
- }
-
- /**
- * Publishes claims when the caller happens to be authenticated and never rejects anyone. Use
- * it on public routes that personalise their response for signed-in callers.
- *
- * {@code
- * app.get("/", handler, auth.optional());
- * // Inside handler: ClaimsHolder.current() is non-null iff the caller is signed in.
- * }
- */
- public Middleware optional() {
- return next -> (req, res) -> {
- Map claims = source.peek(req);
- if (claims != null) ClaimsHolder.set(claims);
- try {
- return next.handle(req, res);
- } finally {
- ClaimsHolder.clear();
- }
- };
- }
-
- /**
- * Applies a policy compiled once at boot from a handler's annotations. This is the path
- * annotation-driven mounting takes.
- */
- public Middleware authorize(AuthPolicy policy) {
- if (policy.optionalAuth()) return optional();
- return next -> (req, res) -> {
- Map claims = source.authenticate(req, res);
- if (claims == null) return null;
- enforcePolicy(claims, policy, res);
- ClaimsHolder.set(claims);
- try {
- return next.handle(req, res);
- } finally {
- ClaimsHolder.clear();
- }
- };
- }
-
- /** {@link #protect()} plus at least one of the given roles (OR semantics). */
- public Middleware requireRole(String... roles) {
- return authorize(AuthPolicy.rolesAny(roles));
- }
-
- /** {@link #protect()} plus every one of the given scopes. */
- public Middleware requireScopes(String... scopes) {
- return authorize(AuthPolicy.scopes(scopes, ScopesAllowed.Match.ALL));
- }
-
- /** {@link #protect()} plus at least one of the given scopes. */
- public Middleware requireAnyScope(String... scopes) {
- return authorize(AuthPolicy.scopes(scopes, ScopesAllowed.Match.ANY));
- }
-
- // -- Policy enforcement ---------------------------------------------------
-
- private void enforcePolicy(Map claims, AuthPolicy policy, Response res) {
- checkRoles(claims, policy.requiredRoles());
- checkScopes(claims, policy.requiredScopes(), policy.scopeMatch(), res);
- }
-
- private void checkRoles(Map claims, String[] required) {
- if (required.length == 0) return;
- if (rolesAllowed(claims, required)) return;
- throw HttpException.forbidden();
- }
-
- private void checkScopes(Map claims, String[] required, ScopesAllowed.Match match,
- Response res) {
- if (required.length == 0) return;
- if (scopesAllowed(claims, required, match)) return;
- String challenge = source.insufficientScopeChallenge(required);
- if (challenge != null) res.header("WWW-Authenticate", challenge);
- throw HttpException.forbidden();
- }
-
- // -- Claim matching -------------------------------------------------------
-
- boolean rolesAllowed(Map 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 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 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 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("Claim path cannot be blank");
- }
- List 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("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 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);
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthPolicy.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthPolicy.java
deleted file mode 100644
index 8cdb741..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthPolicy.java
+++ /dev/null
@@ -1,98 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-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.
- */
-public final class AuthPolicy {
-
- private static final String[] EMPTY = new String[0];
-
- private static final AuthPolicy AUTH_REQUIRED = new AuthPolicy(
- false, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
- private static final AuthPolicy AUTH_OPTIONAL = new AuthPolicy(
- true, EMPTY, EMPTY, ScopesAllowed.Match.ALL);
-
- private final boolean optionalAuth;
- private final String[] requiredRoles;
- private final String[] requiredScopes;
- private final ScopesAllowed.Match scopeMatch;
-
- private AuthPolicy(boolean optionalAuth,
- String[] requiredRoles,
- String[] requiredScopes,
- ScopesAllowed.Match scopeMatch) {
- this.optionalAuth = optionalAuth;
- this.requiredRoles = requiredRoles;
- this.requiredScopes = requiredScopes;
- this.scopeMatch = scopeMatch;
- }
-
- public static AuthPolicy authenticated() { return AUTH_REQUIRED; }
-
- public static AuthPolicy optional() { return AUTH_OPTIONAL; }
-
- public static AuthPolicy rolesAny(String... roles) {
- return new AuthPolicy(false, normalizeRequired("RolesAllowed", roles), EMPTY, ScopesAllowed.Match.ALL);
- }
-
- public static AuthPolicy scopes(String[] scopes, ScopesAllowed.Match match) {
- return new AuthPolicy(false, EMPTY, normalizeRequired("ScopesAllowed", scopes), match);
- }
-
- public static AuthPolicy 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 AuthPolicy(optionalAuth, requiredRoles, requiredScopes, scopeMatch);
- }
-
- public static List 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()));
- }
-
- public boolean optionalAuth() { return optionalAuth; }
-
- public String[] requiredRoles() { return requiredRoles; }
-
- public String[] requiredScopes() { return requiredScopes; }
-
- public 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 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);
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Authenticated.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Authenticated.java
deleted file mode 100644
index 7ef6faa..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Authenticated.java
+++ /dev/null
@@ -1,40 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-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 an authenticated caller. Any credential a registered source
- * accepts is enough — no role or scope check is performed.
- *
- * For role-based access use {@link RolesAllowed} instead (it implies authentication).
- *
- *
Set {@code optional = true} on public routes that personalise their response when the caller
- * happens to be signed in but should remain reachable by guests. The middleware populates
- * {@link ClaimsHolder} when a credential is present and silently skips it otherwise — the request
- * is never rejected.
- *
- *
{@code
- * // Hard auth — 401 or a redirect when unauthenticated:
- * @Route(method = HttpMethod.GET, path = "/api/profile")
- * @Authenticated
- * public class GetProfile extends JacksonHandler { ... }
- *
- * // Soft auth — guest-friendly, ClaimsHolder populated only when signed in:
- * @Route(method = HttpMethod.GET, path = "/")
- * @Authenticated(optional = true)
- * public class HomePage extends HtmlHandler { ... }
- * }
- */
-@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;
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java
deleted file mode 100644
index bc71286..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java
+++ /dev/null
@@ -1,230 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.util.List;
-import java.util.Map;
-import java.util.ArrayList;
-
-/**
- * A typed view over one request's claims — whatever the {@link CredentialSource} that
- * authenticated it produced. Obtained from {@link ClaimsHolder#current()}.
- *
- * The accessors name claim keys, not a protocol: {@code sub} is RFC 7519, and
- * {@code email}, {@code name} and {@code preferred_username} are spelled the same way by every
- * token issuer worth integrating. A source that uses different keys exposes them through
- * {@link #claim(String)} or {@link #roles(String)}.
- *
- *
{@code
- * app.get("/api/whoami", (req, res) -> {
- * Claims c = ClaimsHolder.current();
- * return Map.of("sub", c.sub(), "email", c.email(), "roles", c.roles("realm_access.roles"));
- * }, auth.protect());
- * }
- */
-public final class Claims {
-
- private final Map claims;
-
- Claims(Map claims) {
- this.claims = claims;
- }
-
- // ── Common claims ─────────────────────────────────────────────────────────
-
- /** Subject identifier — the stable, unique id of the caller. */
- public String sub() { return str("sub"); }
-
- /** User's email address ({@code email} claim). */
- public String email() { return str("email"); }
-
- /** Human-readable username ({@code preferred_username} claim). */
- public String username() { return str("preferred_username"); }
-
- /** Full display name ({@code name} claim). */
- public String name() { return str("name"); }
-
- // ── Roles ────────────────────────────────────────────────────────────────
-
- /**
- * Extracts the roles list by traversing a dot-separated claim path.
- *
- * Example paths:
- *
- * - {@code "realm_access.roles"} — Keycloak realm roles
- * - {@code "resource_access.my-client.roles"} — Keycloak client roles
- * - {@code "groups"} — Authelia / generic IdPs
- *
- *
- * @return list of role strings, or an empty list if the path doesn't exist
- */
- @SuppressWarnings("unchecked")
- public List roles(String claimPath) {
- String[] parts = claimPath.split("\\.");
- Object current = claims;
- for (String part : parts) {
- if (!(current instanceof Map m)) return List.of();
- current = m.get(part);
- }
- if (current instanceof List list)
- return list.stream().map(Object::toString).toList();
- return List.of();
- }
-
- /** Returns {@code true} if the user holds {@code role} at the given claim path. */
- public boolean hasRole(String claimPath, String role) {
- return roles(claimPath).contains(role);
- }
-
- // -- Scopes ---------------------------------------------------------------
-
- /**
- * Resolves scopes using the conventional fallback order:
- * {@code scope} then {@code scp}. Supports both space-separated string and list forms.
- */
- public List scopes() {
- return scopes("scope,scp");
- }
-
- /**
- * Resolves scopes from comma-separated claim paths (example: {@code "scope,scp,permissions.scopes"}).
- */
- public List scopes(String claimPaths) {
- List out = new ArrayList<>();
- for (String[] path : splitClaimPaths(claimPaths)) {
- Object value = valueAtPath(path);
- if (value == null) continue;
- if (value instanceof String s) {
- appendDelimitedTokens(out, s);
- continue;
- }
- if (value instanceof List list) {
- for (Object item : list) {
- if (item == null) continue;
- String token = item.toString().trim();
- if (!token.isEmpty()) out.add(token);
- }
- continue;
- }
- String token = value.toString().trim();
- if (!token.isEmpty()) out.add(token);
- }
- return out.isEmpty() ? List.of() : List.copyOf(out);
- }
-
- /** Returns {@code true} if the user has {@code scope}, searching default claim paths {@code scope,scp}. */
- public boolean hasScope(String scope) {
- return hasScope("scope,scp", scope);
- }
-
- /** Returns {@code true} if the user has {@code scope} in any of {@code claimPaths}. */
- public boolean hasScope(String claimPaths, String scope) {
- if (scope == null || scope.isBlank()) return false;
- String target = scope.trim();
- for (String[] path : splitClaimPaths(claimPaths)) {
- Object value = valueAtPath(path);
- if (value == null) continue;
- if (value instanceof String s && containsDelimitedToken(s, target)) return true;
- if (value instanceof List list) {
- for (Object item : list) {
- if (item == null) continue;
- if (target.equals(item.toString().trim())) return true;
- }
- continue;
- }
- if (target.equals(value.toString().trim())) return true;
- }
- return false;
- }
-
- // ── Arbitrary claim access ─────────────────────────────────────────────
-
- /**
- * Returns the value of any claim, cast to {@code T}.
- *
- * @throws ClassCastException if the stored value is not assignable to {@code type}
- */
- public T claim(String key, Class type) {
- return type.cast(claims.get(key));
- }
-
- /** Returns the raw claim value, or {@code null} if absent. */
- public Object claim(String key) { return claims.get(key); }
-
- /** Escape hatch — returns the full unmodified claims map. */
- public Map claims() { return claims; }
-
- // ── Internals ─────────────────────────────────────────────────────────
-
- private String str(String key) {
- Object v = claims.get(key);
- return v != null ? v.toString() : null;
- }
-
- private Object valueAtPath(String[] path) {
- Object current = claims;
- for (String part : path) {
- if (!(current instanceof Map m)) return null;
- current = m.get(part);
- if (current == null) return null;
- }
- return current;
- }
-
- private static String[][] splitClaimPaths(String claimPaths) {
- String source = (claimPaths == null || claimPaths.isBlank()) ? "scope,scp" : claimPaths;
- List 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(splitPath(raw));
- start = i + 1;
- }
- }
- return out.isEmpty() ? new String[][]{ splitPath("scope"), splitPath("scp") } : out.toArray(String[][]::new);
- }
-
- private static String[] splitPath(String path) {
- List out = new ArrayList<>(4);
- int start = 0;
- int len = path.length();
- for (int i = 0; i <= len; i++) {
- if (i == len || path.charAt(i) == '.') {
- String raw = path.substring(start, i).trim();
- if (!raw.isEmpty()) out.add(raw);
- start = i + 1;
- }
- }
- return out.isEmpty() ? new String[]{ path } : out.toArray(String[]::new);
- }
-
- private static void appendDelimitedTokens(List target, String source) {
- int len = source.length();
- int i = 0;
- while (i < len) {
- while (i < len && isDelimiter(source.charAt(i))) i++;
- int start = i;
- while (i < len && !isDelimiter(source.charAt(i))) i++;
- if (i > start) target.add(source.substring(start, i));
- }
- }
-
- private static boolean containsDelimitedToken(String source, String token) {
- int len = source.length();
- int i = 0;
- while (i < len) {
- while (i < len && isDelimiter(source.charAt(i))) i++;
- int start = i;
- while (i < len && !isDelimiter(source.charAt(i))) i++;
- int end = i;
- if (end > start && end - start == token.length() && source.regionMatches(start, token, 0, token.length())) {
- return true;
- }
- }
- return false;
- }
-
- private static boolean isDelimiter(char c) {
- return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == ',';
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java
deleted file mode 100644
index a8cf400..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java
+++ /dev/null
@@ -1,64 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.util.Map;
-
-/**
- * The current request's claims, published by {@link AuthMiddleware} before the handler runs and
- * cleared in a {@code finally} afterwards.
- *
- * Safe with virtual threads: each request gets its own, so a {@link ThreadLocal} is naturally
- * isolated per request.
- *
- *
Writing is deliberately not public. A {@link CredentialSource} returns claims and the
- * middleware publishes them, so no code outside this module can put claims on a request that did
- * not carry them.
- *
- *
{@code
- * // Inside any handler behind @Authenticated or @RolesAllowed:
- * Claims caller = ClaimsHolder.current();
- * String email = caller.email();
- * List roles = caller.roles("realm_access.roles");
- *
- * // Raw escape hatch:
- * Map all = ClaimsHolder.map();
- * }
- */
-public final class ClaimsHolder {
-
- private static final ThreadLocal> HOLDER = new ThreadLocal<>();
-
- private ClaimsHolder() {}
-
- /** Called by {@link AuthMiddleware} once a source has authenticated the request. */
- static void set(Map claims) {
- HOLDER.set(claims);
- }
-
- /** Called by {@link AuthMiddleware} in the {@code finally} block. */
- static void clear() {
- HOLDER.remove();
- }
-
- /**
- * A typed view of the current request's claims, or {@code null} when the route carries no
- * authentication middleware or the caller is anonymous under
- * {@link Authenticated}{@code (optional = true)}.
- */
- public static Claims current() {
- Map claims = HOLDER.get();
- return claims != null ? new Claims(claims) : null;
- }
-
- /** The raw claims map for the current request, or {@code null}. @see #current() */
- public static Map map() {
- return HOLDER.get();
- }
-
- /** A single claim as a String, or {@code null} when absent or the caller is anonymous. */
- public static String claim(String key) {
- Map claims = HOLDER.get();
- if (claims == null) return null;
- Object v = claims.get(key);
- return v != null ? v.toString() : null;
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java
deleted file mode 100644
index 4ceb2f5..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java
+++ /dev/null
@@ -1,48 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import dev.relism.flash.exceptions.HttpException;
-import dev.relism.flash.models.Request;
-import dev.relism.flash.models.Response;
-
-import java.util.Map;
-
-/**
- * Turns whatever a request carries — a bearer token, a session cookie, an API key — into the
- * claims authorization runs on. One is installed per authentication mechanism;
- * {@code flash-ext-auth-oidc} contributes the OpenID Connect one.
- *
- * Implementations never touch {@link ClaimsHolder}: they produce claims and {@link
- * AuthMiddleware} publishes them for the duration of the request. Nothing outside this module can
- * inject claims into a request, which is the point.
- */
-public interface CredentialSource {
-
- /**
- * Resolves the caller's claims, rejecting the request when it cannot.
- *
- *
Three outcomes, and the difference between the last two matters:
- *
- * - claims — the caller presented a valid credential;
- * - {@code null} — no credential was presented and this source has already answered the
- * request itself (typically a redirect into a sign-in flow). The middleware stops and
- * writes nothing more;
- * - {@link HttpException} — a credential was presented and is invalid. The source
- * sets any challenge header it owes the caller before throwing.
- *
- */
- Map authenticate(Request req, Response res);
-
- /**
- * Resolves claims without ever rejecting: {@code null} when no valid credential is present.
- * Backs {@link Authenticated}{@code (optional = true)}, where an anonymous caller is a normal
- * outcome rather than a failure.
- */
- Map peek(Request req);
-
- /**
- * The {@code WWW-Authenticate} value to send with a 403 caused by missing scopes, or
- * {@code null} when this source has no such concept. Only consulted after authentication has
- * already succeeded.
- */
- default String insufficientScopeChallenge(String[] requiredScopes) { return null; }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/InMemorySessionStore.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/InMemorySessionStore.java
deleted file mode 100644
index eff0fa1..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/InMemorySessionStore.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.util.Optional;
-import java.util.concurrent.ConcurrentHashMap;
-
-/**
- * Thread-safe in-memory {@link SessionStore}.
- *
- * Sessions are lost on restart and not shared across instances. For
- * production deployments with multiple nodes or restart-persistence requirements,
- * supply another implementation to whichever {@link CredentialSource} owns the session.
- */
-public final class InMemorySessionStore implements SessionStore {
-
- private final ConcurrentHashMap store = new ConcurrentHashMap<>();
-
- @Override public void save(Session s) { store.put(s.id(), s); }
- @Override public Optional find(String id) { return Optional.ofNullable(store.get(id)); }
- @Override public void delete(String id) { store.remove(id); }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java
deleted file mode 100644
index b37020d..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java
+++ /dev/null
@@ -1,31 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Restricts a handler to callers holding at least one of the named roles. Authentication is
- * implied — there is no need to combine it with {@link Authenticated}.
- *
- * Roles are read from the claim path the installed credential source is configured with
- * (Keycloak's is {@code realm_access.roles}; many providers use a flat {@code roles} or
- * {@code groups}). Nested paths use dot notation.
- *
- *
{@code
- * @Route(method = HttpMethod.DELETE, path = "/api/admin/blogs/{id}")
- * @RolesAllowed("admin")
- * public class DeleteBlog extends JacksonHandler { ... }
- *
- * // Multiple accepted roles (OR semantics — any one is sufficient):
- * @RolesAllowed({"admin", "editor"})
- * public class UpdateBlog extends JacksonHandler { ... }
- * }
- */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
-public @interface RolesAllowed {
- /** One or more role names. Access is granted if the caller has any of them. */
- String[] value();
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java
deleted file mode 100644
index 40cd8c5..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java
+++ /dev/null
@@ -1,45 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Restricts a handler to callers whose credential carries the required scopes.
- * Authentication is implicitly required.
- *
- * Scopes are resolved from the configured claim paths in
- * {@link AuthConfig#scopeClaimPaths()} (default: {@code "scope,scp"}) and support
- * both standard formats:
- *
- * - {@code scope}: space-separated string
- * - {@code scp}: string list (or string)
- *
- *
- * {@code
- * @Route(method = HttpMethod.GET, path = "/api/orders")
- * @ScopesAllowed("orders:read")
- * public class ListOrders extends JacksonHandler { ... }
- *
- * @Route(method = HttpMethod.POST, path = "/api/orders")
- * @ScopesAllowed(value = {"orders:write", "payments:write"}, match = ScopesAllowed.Match.ANY)
- * public class CreateOrder extends JacksonHandler { ... }
- * }
- */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
-public @interface ScopesAllowed {
- /** Required scopes. */
- String[] value();
-
- /** Matching mode for {@link #value()}. */
- Match match() default Match.ALL;
-
- enum Match {
- /** Any one required scope is sufficient. */
- ANY,
- /** All required scopes must be present. */
- ALL
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Session.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Session.java
deleted file mode 100644
index 0a77824..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Session.java
+++ /dev/null
@@ -1,53 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.time.Instant;
-import java.util.Map;
-
-/**
- * A signed-in caller's server-side session — saved in a {@link SessionStore} and looked up by a
- * cookie on every request.
- *
- * Immutable: renewing one produces a new instance that replaces the old under the same
- * {@link #id()}.
- *
- *
{@link #attributes()} is whatever the {@link CredentialSource} needs to keep alongside the
- * claims and nothing this module interprets — OpenID Connect stores its access, id and refresh
- * tokens there so that renewal is its business rather than core's.
- */
-public final class Session {
-
- /** Renew this far before the real expiry, so a session cannot lapse mid-request. */
- private static final long EAGER_RENEWAL_SECONDS = 30;
-
- private final String id;
- private final Map claims;
- private final Instant expiresAt;
- private final Map attributes;
-
- public Session(String id, Map claims, Instant expiresAt,
- Map attributes) {
- this.id = id;
- this.claims = Map.copyOf(claims);
- this.expiresAt = expiresAt;
- this.attributes = attributes == null ? Map.of() : Map.copyOf(attributes);
- }
-
- /** True once the session is within {@value #EAGER_RENEWAL_SECONDS} seconds of expiring. */
- public boolean isExpired() {
- return Instant.now().isAfter(expiresAt.minusSeconds(EAGER_RENEWAL_SECONDS));
- }
-
- /** One attribute, or {@code null} when the source never stored it. */
- public Object attribute(String key) { return attributes.get(key); }
-
- /** One attribute as a String, or {@code null}. */
- public String attributeAsString(String key) {
- Object v = attributes.get(key);
- return v != null ? v.toString() : null;
- }
-
- public String id() { return id; }
- public Map claims() { return claims; }
- public Instant expiresAt() { return expiresAt; }
- public Map attributes() { return attributes; }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/SessionStore.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/SessionStore.java
deleted file mode 100644
index 2e0a058..0000000
--- a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/SessionStore.java
+++ /dev/null
@@ -1,13 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import java.util.Optional;
-
-/**
- * Where {@link Session}s live between requests. {@link InMemorySessionStore} is the default;
- * supply another for Redis, JDBC, or anything that survives a restart or spans instances.
- */
-public interface SessionStore {
- void save(Session session);
- Optional find(String sessionId);
- void delete(String sessionId);
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java
deleted file mode 100644
index a2e8139..0000000
--- a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java
+++ /dev/null
@@ -1,94 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import org.junit.jupiter.api.Test;
-
-import java.util.List;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-class AuthPolicyTest {
-
- static class PlainHandler {}
-
- @Authenticated
- static class AuthenticatedHandler {}
-
- @Authenticated(optional = true)
- static class OptionalHandler {}
-
- @RolesAllowed({"admin", " editor ", "admin"})
- static class RolesHandler {}
-
- @ScopesAllowed(value = {"orders:write", " payments:write ", "orders:write"}, match = ScopesAllowed.Match.ANY)
- static class ScopesHandler {}
-
- @Authenticated
- @RolesAllowed("admin")
- @ScopesAllowed(value = {"orders:read", "payments:read"}, match = ScopesAllowed.Match.ALL)
- static class CombinedHandler {}
-
- @Authenticated(optional = true)
- @ScopesAllowed("orders:read")
- static class InvalidOptionalHandler {}
-
- @Test
- void compileFromAnnotations_noSecurityAnnotations_returnsNull() {
- assertNull(AuthPolicy.compileFromAnnotations(PlainHandler.class));
- }
-
- @Test
- void compileFromAnnotations_authenticated_createsRequiredAuthPolicy() {
- AuthPolicy policy = AuthPolicy.compileFromAnnotations(AuthenticatedHandler.class);
- assertNotNull(policy);
- assertFalse(policy.optionalAuth());
- assertEquals(0, policy.requiredRoles().length);
- assertEquals(0, policy.requiredScopes().length);
- }
-
- @Test
- void compileFromAnnotations_optionalAuth_createsOptionalPolicy() {
- AuthPolicy policy = AuthPolicy.compileFromAnnotations(OptionalHandler.class);
- assertNotNull(policy);
- assertTrue(policy.optionalAuth());
- }
-
- @Test
- void compileFromAnnotations_rolesAndScopes_areNormalizedAndMerged() {
- AuthPolicy policy = AuthPolicy.compileFromAnnotations(CombinedHandler.class);
- assertNotNull(policy);
- assertFalse(policy.optionalAuth());
- assertArrayEquals(new String[]{"admin"}, policy.requiredRoles());
- assertArrayEquals(new String[]{"orders:read", "payments:read"}, policy.requiredScopes());
- assertEquals(ScopesAllowed.Match.ALL, policy.scopeMatch());
- }
-
- @Test
- void compileFromAnnotations_scopesAny_preservesMatchModeAndDedupes() {
- AuthPolicy policy = AuthPolicy.compileFromAnnotations(ScopesHandler.class);
- assertNotNull(policy);
- assertArrayEquals(new String[]{"orders:write", "payments:write"}, policy.requiredScopes());
- assertEquals(ScopesAllowed.Match.ANY, policy.scopeMatch());
- }
-
- @Test
- void compileFromAnnotations_optionalCannotBeCombinedWithConstraints() {
- assertThrows(IllegalStateException.class,
- () -> AuthPolicy.compileFromAnnotations(InvalidOptionalHandler.class));
- }
-
- @Test
- void openApiScopesFor_returnsScopesWhenPresent() {
- assertEquals(List.of("orders:write", "payments:write"),
- AuthPolicy.openApiScopesFor(ScopesHandler.class));
- }
-
- @Test
- void openApiScopesFor_rolesOnly_returnsEmptyList() {
- assertEquals(List.of(), AuthPolicy.openApiScopesFor(RolesHandler.class));
- }
-
- @Test
- void openApiScopesFor_noSecurity_returnsNull() {
- assertNull(AuthPolicy.openApiScopesFor(PlainHandler.class));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java
deleted file mode 100644
index f74f63f..0000000
--- a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java
+++ /dev/null
@@ -1,209 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import org.junit.jupiter.api.Test;
-
-import java.util.Arrays;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * Characterisation tests for claim matching — the part of authorization that has nothing to do
- * with OIDC: given a claims map, does the caller hold a role or a scope.
- *
- * Written to pin the current behaviour, including the edges that are easy to change by
- * accident: which characters separate scopes in a string claim, whether a list entry is trimmed
- * before comparison, what an empty requirement means under each match mode, and how a claim path
- * that walks into a non-map resolves. Every assertion here reflects what the code does today, not
- * what it arguably should do.
- */
-class ClaimMatchingTest {
-
- /** No credential source: every assertion here is about claims that are already resolved. */
- private static AuthMiddleware middleware(String rolesPath, String scopePaths) {
- return new AuthMiddleware(AuthConfig.builder()
- .rolesClaimPath(rolesPath)
- .scopeClaimPaths(scopePaths)
- .build(), null);
- }
-
- private static AuthMiddleware middleware() {
- return middleware("realm_access.roles", "scope,scp");
- }
-
- // ── Claim path traversal ─────────────────────────────────────────────────
-
- @Test
- void aPathWalksNestedMaps() {
- Map claims = Map.of("a", Map.of("b", Map.of("c", List.of("x"))));
- assertTrue(middleware("a.b.c", "scope").rolesAllowed(claims, new String[]{"x"}));
- }
-
- @Test
- void aPathThatWalksIntoANonMapResolvesToNothing() {
- // "a" is a string, so "a.b" has nowhere to go — not an error, just no match.
- Map claims = Map.of("a", "not-a-map");
- assertFalse(middleware("a.b", "scope").rolesAllowed(claims, new String[]{"anything"}));
- }
-
- @Test
- void aMissingPathResolvesToNothing() {
- assertFalse(middleware().rolesAllowed(Map.of("other", "value"), new String[]{"admin"}));
- }
-
- @Test
- void emptySegmentsInAPathAreSkipped() {
- // "realm_access..roles" collapses to the same two segments.
- Map claims = Map.of("realm_access", Map.of("roles", List.of("admin")));
- assertTrue(middleware("realm_access..roles", "scope").rolesAllowed(claims, new String[]{"admin"}));
- }
-
- @Test
- void segmentsAreTrimmed() {
- Map claims = Map.of("realm_access", Map.of("roles", List.of("admin")));
- assertTrue(middleware(" realm_access . roles ", "scope").rolesAllowed(claims, new String[]{"admin"}));
- }
-
- @Test
- void aBlankRolesPathIsRejectedAtConstruction() {
- assertThrows(IllegalStateException.class, () -> middleware(" ", "scope"));
- }
-
- @Test
- void aNullClaimValueResolvesToNothing() {
- Map nested = new HashMap<>();
- nested.put("roles", null);
- Map claims = Map.of("realm_access", nested);
- assertFalse(middleware().rolesAllowed(claims, new String[]{"admin"}));
- }
-
- // ── Roles: ANY semantics ─────────────────────────────────────────────────
-
- @Test
- void anyOneOfTheRequiredRolesIsEnough() {
- Map claims = Map.of("realm_access", Map.of("roles", List.of("user")));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"admin", "user"}));
- assertFalse(middleware().rolesAllowed(claims, new String[]{"admin", "ops"}));
- }
-
- @Test
- void requiringNoRoleAtAllMatchesNothing() {
- // The loop never runs, so the answer is false even when the claim is present.
- Map claims = Map.of("realm_access", Map.of("roles", List.of("admin")));
- assertFalse(middleware().rolesAllowed(claims, new String[0]));
- }
-
- // ── What counts as "contains" ────────────────────────────────────────────
-
- @Test
- void aListClaimMatchesEntrywiseAndTrimsEachEntry() {
- Map claims = Map.of("realm_access", Map.of("roles", List.of(" admin ", "user")));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"admin"}));
- }
-
- @Test
- void aListEntryIsNeverSplitOnDelimiters() {
- // Unlike a string claim, a list entry is compared whole: "a b" is one role named "a b".
- Map claims = Map.of("realm_access", Map.of("roles", List.of("a b")));
- assertFalse(middleware().rolesAllowed(claims, new String[]{"a"}));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"a b"}));
- }
-
- @Test
- void nullEntriesInAListAreSkipped() {
- Map claims = Map.of("realm_access",
- Map.of("roles", Arrays.asList(null, "admin")));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"admin"}));
- }
-
- @Test
- void anArrayClaimBehavesLikeAList() {
- Map claims = Map.of("realm_access",
- Map.of("roles", (Object) new String[]{"admin", "user"}));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"user"}));
- }
-
- @Test
- void aScalarClaimIsComparedWhole() {
- Map claims = Map.of("realm_access", Map.of("roles", 42));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"42"}));
- }
-
- @Test
- void aStringClaimIsSplitOnSpacesTabsNewlinesAndCommas() {
- for (String separator : List.of(" ", "\t", "\n", "\r", ",")) {
- Map claims = Map.of("realm_access",
- Map.of("roles", "admin" + separator + "user"));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"user"}),
- "separator " + separator.strip().isEmpty() + " should split the claim");
- }
- }
-
- @Test
- void aStringClaimDoesNotMatchAPrefixOrASubstring() {
- Map claims = Map.of("realm_access", Map.of("roles", "administrator"));
- assertFalse(middleware().rolesAllowed(claims, new String[]{"admin"}));
- }
-
- @Test
- void repeatedDelimitersProduceNoEmptyTokens() {
- Map claims = Map.of("realm_access", Map.of("roles", " ,, admin ,, "));
- assertTrue(middleware().rolesAllowed(claims, new String[]{"admin"}));
- }
-
- // ── Scopes: ALL vs ANY, across several claim paths ───────────────────────
-
- @Test
- void allRequiresEveryScope() {
- Map claims = Map.of("scope", "openid orders:read");
- assertTrue(middleware().scopesAllowed(claims, new String[]{"openid", "orders:read"}, ScopesAllowed.Match.ALL));
- assertFalse(middleware().scopesAllowed(claims, new String[]{"openid", "orders:write"}, ScopesAllowed.Match.ALL));
- }
-
- @Test
- void anyRequiresOne() {
- Map claims = Map.of("scope", "openid");
- assertTrue(middleware().scopesAllowed(claims, new String[]{"nope", "openid"}, ScopesAllowed.Match.ANY));
- assertFalse(middleware().scopesAllowed(claims, new String[]{"nope", "neither"}, ScopesAllowed.Match.ANY));
- }
-
- @Test
- void requiringNoScopeIsVacuouslyTrueUnderAllAndFalseUnderAny() {
- // The asymmetry falls out of the loops and is load-bearing for @ScopesAllowed's validation,
- // which rejects an empty value list before it can ever reach here.
- Map claims = Map.of("scope", "openid");
- assertTrue(middleware().scopesAllowed(claims, new String[0], ScopesAllowed.Match.ALL));
- assertFalse(middleware().scopesAllowed(claims, new String[0], ScopesAllowed.Match.ANY));
- }
-
- @Test
- void scopesAreLookedForInEveryConfiguredPathUntilOneMatches() {
- AuthMiddleware mw = middleware("roles", "scope, scp , permissions.scopes");
- Map claims = Map.of(
- "scp", List.of("payments:write"),
- "permissions", Map.of("scopes", "orders:approve"));
-
- assertTrue(mw.scopesAllowed(claims, new String[]{"payments:write"}, ScopesAllowed.Match.ALL));
- assertTrue(mw.scopesAllowed(claims, new String[]{"orders:approve"}, ScopesAllowed.Match.ALL));
- // ALL is satisfied even when the two scopes come from different claims.
- assertTrue(mw.scopesAllowed(claims,
- new String[]{"payments:write", "orders:approve"}, ScopesAllowed.Match.ALL));
- }
-
- @Test
- void blankScopePathsFallBackToScopeAndScp() {
- AuthMiddleware mw = middleware("roles", " ");
- assertTrue(mw.scopesAllowed(Map.of("scope", "a"), new String[]{"a"}, ScopesAllowed.Match.ALL));
- assertTrue(mw.scopesAllowed(Map.of("scp", "b"), new String[]{"b"}, ScopesAllowed.Match.ALL));
- }
-
- @Test
- void aScopePathListOfOnlySeparatorsFallsBackToScopeAndScp() {
- AuthMiddleware mw = middleware("roles", " , , ");
- assertTrue(mw.scopesAllowed(Map.of("scp", "b"), new String[]{"b"}, ScopesAllowed.Match.ALL));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java
deleted file mode 100644
index 6e6fe1e..0000000
--- a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java
+++ /dev/null
@@ -1,47 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import org.junit.jupiter.api.Test;
-
-import java.util.List;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-class ClaimsScopesTest {
-
- @Test
- void scopes_readsStandardScopeString() {
- Claims user = new Claims(Map.of("scope", "openid profile orders:read"));
-
- assertEquals(List.of("openid", "profile", "orders:read"), user.scopes());
- assertTrue(user.hasScope("orders:read"));
- assertFalse(user.hasScope("orders:write"));
- }
-
- @Test
- void scopes_fallsBackToScpArray() {
- Claims user = new Claims(Map.of("scp", List.of("orders:write", "payments:write")));
-
- assertEquals(List.of("orders:write", "payments:write"), user.scopes());
- assertTrue(user.hasScope("payments:write"));
- }
-
- @Test
- void scopes_supportsCustomClaimPaths() {
- Claims user = new Claims(Map.of("permissions", Map.of("scopes", List.of("a", "b"))));
-
- assertEquals(List.of("a", "b"), user.scopes("permissions.scopes"));
- assertTrue(user.hasScope("permissions.scopes", "a"));
- assertFalse(user.hasScope("permissions.scopes", "x"));
- }
-
- @Test
- void scopes_combinesMultipleClaimPathsInOrder() {
- Claims user = new Claims(Map.of(
- "scope", "openid",
- "scp", List.of("profile", "orders:read")
- ));
-
- assertEquals(List.of("openid", "profile", "orders:read"), user.scopes("scope,scp"));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/SessionTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/SessionTest.java
deleted file mode 100644
index 6aef288..0000000
--- a/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/SessionTest.java
+++ /dev/null
@@ -1,58 +0,0 @@
-package dev.relism.flash.ext.auth;
-
-import org.junit.jupiter.api.Test;
-
-import java.time.Instant;
-import java.util.HashMap;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * The two things a session has to get right: it reports itself expired early enough that it
- * cannot lapse midway through a request, and it hands back what a credential source stored on it
- * without interpreting any of it.
- */
-class SessionTest {
-
- private static Session at(Instant expiry, Map attributes) {
- return new Session("s1", Map.of("sub", "u1"), expiry, attributes);
- }
-
- @Test
- void aSessionIsExpiredWellBeforeItsDeadline() {
- // The eager window is what stops a session from lapsing between the check and the handler.
- assertFalse(at(Instant.now().plusSeconds(120), Map.of()).isExpired());
- assertTrue(at(Instant.now().plusSeconds(10), Map.of()).isExpired());
- assertTrue(at(Instant.now().minusSeconds(1), Map.of()).isExpired());
- }
-
- @Test
- void attributesAreReturnedUninterpreted() {
- Session session = at(Instant.now().plusSeconds(60), Map.of("oidc.id_token", "abc", "n", 7));
- assertEquals("abc", session.attributeAsString("oidc.id_token"));
- assertEquals("7", session.attributeAsString("n"));
- assertEquals(7, session.attribute("n"));
- assertNull(session.attributeAsString("absent"));
- }
-
- @Test
- void aSessionWithoutAttributesIsUsableRatherThanNull() {
- assertNull(at(Instant.now().plusSeconds(60), null).attributeAsString("anything"));
- }
-
- @Test
- void claimsAndAttributesAreCopiedAndImmutable() {
- Map mutable = new HashMap<>(Map.of("k", "v"));
- Session session = at(Instant.now().plusSeconds(60), mutable);
- mutable.put("k", "changed");
-
- assertEquals("v", session.attributeAsString("k"));
- assertThrows(UnsupportedOperationException.class, () -> session.attributes().put("x", "y"));
- assertThrows(UnsupportedOperationException.class, () -> session.claims().put("x", "y"));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/README.md b/flash-extensions/flash-ext-auth-oidc/README.md
deleted file mode 100644
index 960d20e..0000000
--- a/flash-extensions/flash-ext-auth-oidc/README.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# flash-ext-auth-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).
-
-This extension is the OpenID Connect **credential source** for
-[`flash-ext-auth-core`](../flash-ext-auth-core/docs/README.md), which owns everything downstream of
-identifying the caller. Shorter guides live in [`docs/`](docs/README.md), including
-[migration notes](docs/interop.md#migrating-from-flash-ext-oidc) from `flash-ext-oidc`.
-
-## 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` |
-| `OidcCredentialSource` | The `CredentialSource` this extension contributes to `flash-ext-auth-core` |
-| `JwtValidator` | JWKS-backed JWT validator (PKCE + key rotation + caching) |
-
-`@Authenticated`, `@RolesAllowed`, `@ScopesAllowed`, `AuthMiddleware`, `ClaimsHolder` and `Claims`
-belong to [`flash-ext-auth-core`](../flash-ext-auth-core/docs/README.md) and work the same behind
-any credential source. Installing this extension brings them in and wires them up — you do not
-install auth-core yourself.
-
-## Dependencies
-
-```xml
-
- dev.relism
- flash-ext-auth-oidc
- 2.1.0-SNAPSHOT
-
-```
-
-Transitive: `flash-ext-auth-core`, `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)` | `InMemorySessionStore` | 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) {
- Claims u = ClaimsHolder.current();
- 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 `AuthMiddleware`
-from the context inside another extension's `routes()` phase, or after `start()`:
-
-```java
-AuthMiddleware auth = app.ctx().require(AuthMiddleware.class);
-
-// Authentication only
-app.get("/api/me", (req, res) -> {
- Claims u = ClaimsHolder.current(); // never null here
- return Map.of("sub", u.sub(), "email", u.email());
-}, auth.protect());
-
-// Authentication + role check
-app.delete("/api/admin/users/{id}", (req, res) -> {
- Claims u = ClaimsHolder.current();
- // ...
-}, auth.requireRole("admin"));
-
-// Multiple roles (OR): passes if user holds any one of them
-app.get("/api/reports", (req, res) -> { ... }, auth.requireRole("admin", "reports-viewer"));
-
-// Require all listed scopes
-app.post("/api/orders", (req, res) -> { ... }, auth.requireScopes("orders:write", "payments:write"));
-
-// Require at least one listed scope
-app.post("/api/payments", (req, res) -> { ... }, auth.requireAnyScope("payments:write", "payments:admin"));
-```
-
-`auth.protect()` / `auth.requireRole(...)` / `auth.requireScopes(...)` return a `Middleware` — a composable
-`Handler → Handler` wrapper. Flash applies middleware right-to-left so the authentication 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 `AuthMiddleware` — from `flash-ext-auth-core` — once this source has
-authenticated the request, and cleared in the `finally` block afterward. Nothing outside that
-module can write to it. It is safe with virtual threads (each request gets its
-own virtual thread, so `ThreadLocal` values are naturally isolated).
-
-### Claims (preferred)
-
-```java
-Claims u = ClaimsHolder.current(); // 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 roles = u.roles("realm_access.roles"); // Keycloak realm roles
-List clientRoles = u.roles("resource_access.my-client.roles"); // Keycloak client roles
-List groups = u.roles("groups"); // Authelia
-
-boolean isAdmin = u.hasRole("realm_access.roles", "admin");
-
-// Scopes (OIDC/OAuth2 generic): checks "scope" then "scp"
-List scopes = u.scopes();
-boolean canWrite = u.hasScope("orders:write");
-
-// Custom claim path resolution (for provider-specific payloads)
-List 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 all = u.claims();
-```
-
-### Raw access (escape hatch)
-
-```java
-Map claims = ClaimsHolder.map();
-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 `) — 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=""`
-- invalid bearer token: `Bearer realm="", error="invalid_token"`
-- insufficient scopes: `Bearer realm="", error="insufficient_scope", scope=""`
-
-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 -> `` -> 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 `auth.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
-
-Sessions live in `flash-ext-auth-core`'s `Session`/`SessionStore`; this extension keeps its
-access, id and refresh tokens in `Session.attributes()` under its own keys, so renewal stays here
-and core carries no OAuth2 vocabulary. See
-[`../flash-ext-auth-core/docs/sessions.md`](../flash-ext-auth-core/docs/sessions.md).
-
-The default `InMemorySessionStore` is sufficient for single-instance deployments.
-For clustered deployments, implement `SessionStore`:
-
-```java
-public interface SessionStore {
- void save(Session session);
- Optional find(String sessionId);
- void delete(String sessionId);
-}
-```
-
-```java
-OidcConfig.builder(...)
- .sessionStore(new RedisSessionStore(redisClient))
- .build()
-```
-
-`Session` fields: `id`, `accessToken`, `idToken`, `refreshToken`, `expiresAt` (`Instant`), `claims` (merged map).
-
-## Logout
-
-Add a logout button anywhere in your UI — a `
-```
-
-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=&post_logout_redirect_uri=` — 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
-```
-
-The token must be a JWT (opaque tokens are not supported). Claims are available via
-`ClaimsHolder.current()` 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 `AuthMiddleware` 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
-
-AuthMiddleware mwA = app.ctx().require(AuthMiddleware.class); // last registered = tenantB
-```
-
-> **Note:** because both extensions register `AuthMiddleware.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.
diff --git a/flash-extensions/flash-ext-auth-oidc/docs/README.md b/flash-extensions/flash-ext-auth-oidc/docs/README.md
deleted file mode 100644
index 5a64011..0000000
--- a/flash-extensions/flash-ext-auth-oidc/docs/README.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# flash-ext-auth-oidc
-
-OpenID Connect for Flash: the authorization-code flow with PKCE, JWKS-validated bearer tokens,
-server-side sessions with silent refresh, and single logout.
-
-It is a **credential source** for [`flash-ext-auth-core`](../../flash-ext-auth-core/docs/README.md),
-which owns everything downstream of "who is this caller" — `@Authenticated`, `@RolesAllowed`,
-`@ScopesAllowed`, `ClaimsHolder`. Installing this extension installs that machinery too; you do not
-install `flash-ext-auth-core` yourself.
-
-## Quick start
-
-```java
-app.install(new OidcExtension(
- OidcConfig.builder(
- "https://keycloak.example.com/realms/myrealm",
- "my-app", "secret", "/auth/callback")
- .rolesClaimPath("realm_access.roles")
- .https()
- .build()));
-```
-
-That is the whole integration. Discovery runs at boot and fails fast if the issuer is unreachable,
-so a misconfigured provider is a startup crash rather than a 500 on the first login.
-
-`OidcConfig.fromEnv()` reads the same settings from `OIDC_*` environment variables, and
-`OidcConfig.keycloak(serverUrl, realm, ...)` builds the issuer URL for you.
-
-## What it registers
-
-| | |
-|---|---|
-| `GET {prefix}/login` | Builds the authorization URL with PKCE + state and redirects |
-| `GET {prefix}/callback` | Validates state and nonce, exchanges the code, creates the session |
-| `POST {prefix}/logout` | Ends the session and redirects to the provider's end-session endpoint |
-
-`{prefix}` is `routePrefix` (default `/auth`). Logout is a `POST` on purpose — a `GET` logout is
-one `![]()
` tag away from being triggered by any page the user visits.
-
-In the context it provides `AuthMiddleware` (from auth-core), `OidcCredentialSource` and
-`JwtValidator`.
-
-## How a request is resolved
-
-1. `Authorization: Bearer …` — validated against the issuer's JWKS.
-2. `oidc_session` cookie — looked up in the `SessionStore`; if the access token has expired and a
- refresh token is present, refreshed transparently and the session replaced.
-3. Neither, and the client sent `Accept: application/json` → `401` with a
- `WWW-Authenticate: Bearer` challenge.
-4. Neither, and it looks like a browser → redirect to `{prefix}/login?redirect={path}`.
-
-Points 3 and 4 are why the source distinguishes "no credential" from "bad credential": an API
-client must not be redirected into an HTML sign-in page, and a browser must not be left staring at
-a bare 401.
-
-## Configuration
-
-| Setting | Default | Notes |
-|---|---|---|
-| `issuer`, `clientId`, `clientSecret`, `redirectUri` | — | required |
-| `scopes` | `openid profile email` | |
-| `routePrefix` | `/auth` | |
-| `selfScheme` | `http` | `https()` behind TLS; only used when no `X-Forwarded-Proto` |
-| `rolesClaimPath` | `realm_access.roles` | Keycloak's spelling; `groups` for Authelia |
-| `scopeClaimPaths` | `scope,scp` | comma-separated, tried in order |
-| `algorithm` | `RS256` | |
-| `postLogoutRedirectUri` | `/` | |
-| `sessionStore` | `InMemorySessionStore` | swap for Redis/JDBC across instances |
-| `clientAuthMethod` | `POST` | token endpoint client authentication |
-| `insecureTls()` | off | dev only, skips certificate validation |
-| `schemeName` | derived from the issuer | OpenAPI security scheme name |
-
-A relative `redirectUri` (starting with `/`) is resolved per request against the incoming `Host`,
-or `X-Forwarded-Host`/`-Proto` when behind a proxy — so one build works in dev and behind TLS
-without a second configuration.
-
-## Sessions
-
-A session holds the claims plus the access, id and refresh tokens, the last three in
-`Session.attributes()` under this extension's own keys. Core never reads them; renewal happens
-here. See [`../../flash-ext-auth-core/docs/sessions.md`](../../flash-ext-auth-core/docs/sessions.md).
-
-## Multiple providers
-
-Two issuers on one server, each with its own route prefix:
-
-```java
-app.install(new OidcExtension(tenantAConfig)) // routePrefix("/tenantA/auth")
- .install(new OidcExtension(tenantBConfig)); // routePrefix("/tenantB/auth")
-```
-
-Both are known at boot. Registering an issuer at runtime — a customer connecting their own IdP from
-a settings page — is not supported.
-
-## Interop
-
-See [`interop.md`](interop.md) for how this extension fits with `flash-ext-auth-core`,
-`flash-ext-openapi` and `flash-ext-mcp`.
diff --git a/flash-extensions/flash-ext-auth-oidc/docs/interop.md b/flash-extensions/flash-ext-auth-oidc/docs/interop.md
deleted file mode 100644
index d0970ea..0000000
--- a/flash-extensions/flash-ext-auth-oidc/docs/interop.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Interop
-
-## flash-ext-auth-core
-
-A hard dependency, and the reason this extension is as small as it is. The division:
-
-| Here | `flash-ext-auth-core` |
-|---|---|
-| Discovery, JWKS, PKCE, token endpoint | `@Authenticated`, `@RolesAllowed`, `@ScopesAllowed` |
-| `/login`, `/callback`, `/logout` | `ClaimsHolder`, `Claims` |
-| Bearer and cookie resolution, refresh | Role and scope matching |
-| RFC 6750 `WWW-Authenticate` challenges | `Session`, `SessionStore` |
-
-`OidcExtension` builds an `OidcCredentialSource`, hands it to `AuthMiddleware.install(...)`, and
-that publishes the middleware and registers the annotation processor. Everything a handler
-annotation does is core's code running against claims this extension produced.
-
-Consequence worth knowing: `@RolesAllowed` is not OIDC-specific and never was. An app that swaps
-this extension for another credential source keeps every annotation it had.
-
-## flash-ext-openapi
-
-Optional, and resolved lazily so this extension runs standalone when openapi is not on the
-classpath. When it is, an `OpenApiContributor` is registered that emits an `oauth2` security scheme
-with the `authorizationCode` flow, filled in from the discovery document:
-
-```json
-"securitySchemes": {
- "myrealm": {
- "type": "oauth2",
- "flows": { "authorizationCode": { "authorizationUrl": "…", "tokenUrl": "…", "scopes": {…} } }
- }
-}
-```
-
-Per-operation security comes from the same annotations the middleware reads, so the spec and the
-enforcement cannot drift: both call `AuthPolicy.compileFromAnnotations`.
-
-The scheme name is `schemeName`, derived from the last path segment of the issuer (a Keycloak realm
-name, usually) unless set explicitly.
-
-## flash-ext-mcp
-
-`McpSecurity` asks whether **this** extension is installed — `ctx.find(OidcCredentialSource.class)`
-— and not merely whether something authenticates:
-
-| Policy | this extension installed | absent |
-|---|---|---|
-| `REQUIRED` | protected | **boot fails** |
-| `AUTO` | protected | unprotected, warning logged |
-| `NONE` | never protected | unprotected |
-
-That distinction is deliberate. `REQUIRED` means "a real OAuth2 authorization server is protecting
-this endpoint", because everything it turns on — RFC 9728 Protected Resource Metadata, RFC 8707
-audience binding, `WWW-Authenticate` challenges carrying `resource_metadata` — is meaningless
-without an issuer. An app that authenticates some other way must not satisfy it by accident.
-
-When it is installed, `McpOidcIntegration` derives the whole resource-server configuration from the
-source with no extra `McpConfig` calls:
-
-- the MCP route is wrapped with `authMw.withSource(source.withResourceMetadata(path)).protect()` —
- the same validation every other route uses, plus the `resource_metadata` challenge parameter;
-- an audience guard runs after it and rejects any token whose `aud` does not include this
- endpoint's resource identifier;
-- the resource identifier is resolved per request from `X-Forwarded-Host`/`-Proto`, or the `Host`
- header and `selfScheme`.
-
-An app that does **not** use OAuth2 can still guard `/mcp`: set `McpSecurity.NONE` and pass its own
-guard to `McpConfig.middleware(...)`.
-
-## Migrating from flash-ext-oidc
-
-The module was renamed and its generic half moved. Mechanically:
-
-| Was | Now |
-|---|---|
-| `flash-ext-oidc` (artifact) | `flash-ext-auth-oidc` |
-| `dev.relism.flash.ext.oidc.Authenticated` (and `RolesAllowed`, `ScopesAllowed`) | `dev.relism.flash.ext.auth.…` |
-| `OidcMiddleware` | `AuthMiddleware` (`dev.relism.flash.ext.auth`) |
-| `ctx.find(OidcMiddleware.class)` | `ctx.find(AuthMiddleware.class)` |
-| `OidcUser` | `Claims` |
-| `ClaimsHolder.user()` | `ClaimsHolder.current()` |
-| `ClaimsHolder.get()` | `ClaimsHolder.map()` |
-| `OidcSession`, `OidcSessionStore`, `InMemoryOidcSessionStore` | `Session`, `SessionStore`, `InMemorySessionStore` |
-| `session.isAccessTokenExpired()` | `session.isExpired()` |
-| `session.idToken()` | `session.attributeAsString(OidcCredentialSource.ID_TOKEN)` |
-
-`OidcConfig`, `OidcExtension` and every setting on them are unchanged.
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/ClientAuthMethod.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/ClientAuthMethod.java
deleted file mode 100644
index 337039f..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/ClientAuthMethod.java
+++ /dev/null
@@ -1,18 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-/**
- * OAuth2 client authentication method for the token endpoint (RFC 6749 §2.3).
- *
- *
- * - {@link #POST} — credentials sent as {@code client_id} / {@code client_secret}
- * form fields (default; most providers).
- * - {@link #BASIC} — credentials sent as an {@code Authorization: Basic} header;
- * body contains only grant-specific parameters.
- *
- */
-public enum ClientAuthMethod {
- /** {@code client_secret_post} — credentials in the request body. */
- POST,
- /** {@code client_secret_basic} — credentials in the {@code Authorization} header. */
- BASIC
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/DiscoveryClient.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/DiscoveryClient.java
deleted file mode 100644
index 40b6b0c..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/DiscoveryClient.java
+++ /dev/null
@@ -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 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 doc = (Map) 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 doc, String key) {
- Object v = doc.get(key);
- if (v == null) throw new IllegalStateException(
- "Discovery doc missing required field: " + key);
- return v.toString();
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtUtils.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtUtils.java
deleted file mode 100644
index c456733..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtUtils.java
+++ /dev/null
@@ -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.
- *
- * 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 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) JSONValue.parse(
- new String(payload, StandardCharsets.UTF_8));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtValidator.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtValidator.java
deleted file mode 100644
index a0bde6f..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/JwtValidator.java
+++ /dev/null
@@ -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.
- *
- * Two validation modes:
- *
- * - {@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.
- * - {@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).
- *
- *
- * 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 jwkSource;
- private final ConfigurableJWTProcessor accessTokenProcessor;
- private final ConfigurableJWTProcessor 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 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.
- *
- * 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 validateIdToken(String idToken, String nonce) {
- try {
- Map 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 buildAccessTokenProcessor(
- JWKSource src, String issuer, String algorithm) {
-
- ConfigurableJWTProcessor 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 buildIdTokenProcessor(
- JWKSource src, String issuer, String clientId, String algorithm) {
-
- ConfigurableJWTProcessor 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 keySelector(
- JWKSource 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 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);
- }
- };
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcConfig.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcConfig.java
deleted file mode 100644
index 997b71a..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcConfig.java
+++ /dev/null
@@ -1,264 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import dev.relism.flash.ext.auth.InMemorySessionStore;
-import dev.relism.flash.ext.auth.SessionStore;
-
-/**
- * Full OIDC client configuration. Build via
- * {@link #builder(String, String, String, String)} or {@link #fromEnv()}.
- *
- * Required fields: {@code issuer}, {@code clientId}, {@code clientSecret},
- * {@code redirectUri}. Everything else has a sensible default.
- *
- *
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.
- *
- *
{@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));
- * }
- */
-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 SessionStore 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 InMemorySessionStore();
- 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 SessionStore sessionStore() { return sessionStore; }
- /** If {@code true}, TLS certificate validation is skipped. Never use in production. */
- 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:
- *
- * 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: /
- *
- */
- 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.
- *
- * {@code
- * OidcConfig.keycloak(
- * "https://keycloak.example.com", "flashboard",
- * "my-app", "secret", "/auth/callback")
- * .https()
- * .build();
- * }
- */
- 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 SessionStore 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 InMemorySessionStore}). */
- public Builder sessionStore(SessionStore store) { this.sessionStore = store; return this; }
- /**
- * Disables TLS certificate verification for all HTTP calls made by this extension.
- * Only use in development with self-signed certificates — never in production.
- */
- 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.
- *
- * Examples:
- *
- * - {@code https://keycloak.dev.home/realms/flashboard} → {@code "flashboard"}
- * - {@code https://auth.example.com} → {@code "auth.example.com"}
- *
- */
- 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";
- }
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java
deleted file mode 100644
index cd95e63..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java
+++ /dev/null
@@ -1,333 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import dev.relism.flash.exceptions.HttpException;
-import dev.relism.flash.ext.auth.CredentialSource;
-import dev.relism.flash.ext.auth.Session;
-import dev.relism.flash.models.Response;
-import dev.relism.flash.models.Request;
-
-import java.net.URLEncoder;
-import java.nio.charset.StandardCharsets;
-import java.time.Instant;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.Optional;
-
-/**
- * The OpenID Connect {@link CredentialSource}: it turns what a request carries into claims, and
- * rejects it the way OAuth2 says to when it cannot. Authorization on those claims is
- * {@code flash-ext-auth-core}'s job, not this class's.
- *
- * Resolution order on each request:
- *
- * - {@code Authorization: Bearer ...} header — validated via JWKS ({@link JwtValidator}).
- * - {@code oidc_session} cookie — looked up in {@link dev.relism.flash.ext.auth.SessionStore}; transparently
- * refreshed if the access token is expired.
- * - Browser clients (no {@code Accept: application/json}) → redirect to
- * {@code {routePrefix}/login?redirect={path}}.
- * - API clients → 401 with a {@code WWW-Authenticate: Bearer} challenge.
- *
- */
-public final class OidcCredentialSource implements CredentialSource {
-
- private static final String BEARER = "Bearer";
-
- /**
- * Keys this source stores its OAuth2 tokens under in {@link Session#attributes()}. Core keeps
- * the session; the tokens inside it are nobody else's business.
- */
- static final String ACCESS_TOKEN = "oidc.access_token";
- static final String ID_TOKEN = "oidc.id_token";
- static final String REFRESH_TOKEN = "oidc.refresh_token";
-
- /** The one place an OIDC session is built, so its attribute keys stay in one place too. */
- static Session newSession(String id, String accessToken, String idToken, String refreshToken,
- Instant expiresAt, Map claims) {
- Map attributes = new HashMap<>(3);
- if (accessToken != null) attributes.put(ACCESS_TOKEN, accessToken);
- if (idToken != null) attributes.put(ID_TOKEN, idToken);
- if (refreshToken != null) attributes.put(REFRESH_TOKEN, refreshToken);
- return new Session(id, claims, expiresAt, attributes);
- }
-
- private final JwtValidator validator;
- private final OidcConfig config;
- private final OidcProviderMetadata meta;
- private final TokenClient tokenClient;
- private final String resourceMetadataPath;
-
- OidcCredentialSource(JwtValidator validator, OidcConfig config,
- OidcProviderMetadata meta, TokenClient tokenClient) {
- this(validator, config, meta, tokenClient, null);
- }
-
- private OidcCredentialSource(JwtValidator validator, OidcConfig config,
- OidcProviderMetadata meta, TokenClient tokenClient,
- String resourceMetadataPath) {
- this.validator = validator;
- this.config = config;
- this.meta = meta;
- this.tokenClient = tokenClient;
- this.resourceMetadataPath = resourceMetadataPath;
- }
-
- // -- CredentialSource -----------------------------------------------------
-
- /** OIDC issuer this source 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(); }
-
- /**
- * A copy of this source whose 401 challenges also carry {@code resource_metadata}
- * (RFC 9728 §5.1), resolved against the request's own scheme and host exactly like
- * {@link OidcExtension}'s redirect URIs. {@code path} is absolute, e.g.
- * {@code "/.well-known/oauth-protected-resource/mcp"}.
- *
- * 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 OidcCredentialSource withResourceMetadata(String path) {
- return new OidcCredentialSource(validator, config, meta, tokenClient, path);
- }
-
- @Override
- public Map authenticate(Request req, Response res) {
- return resolve(req, res, resourceMetadataPath);
- }
-
- @Override
- public Map peek(Request req) {
- return resolveQuiet(req);
- }
-
- @Override
- public String insufficientScopeChallenge(String[] requiredScopes) {
- return bearerChallenge() + ", error=\"insufficient_scope\", scope=\""
- + quoted(spaceDelimited(requiredScopes)) + "\"";
- }
-
- // -- 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 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 found = config.sessionStore().find(sessionId);
- if (found.isPresent()) {
- Session session = found.get();
- if (!session.isExpired())
- return session.claims();
- if (session.attributeAsString(REFRESH_TOKEN) != null) {
- try {
- Session 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 resolve(Request req, Response res) {
- return resolve(req, res, null);
- }
-
- private Map 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 found = config.sessionStore().find(sessionId);
- if (found.isPresent()) {
- Session session = found.get();
-
- if (!session.isExpired())
- return session.claims();
-
- // Access token expired — try silent refresh
- if (session.attributeAsString(REFRESH_TOKEN) != null) {
- try {
- Session 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 Session doRefresh(Session old) throws Exception {
- OidcTokenResponse tokens = tokenClient.refresh(
- meta.tokenEndpoint(), old.attributeAsString(REFRESH_TOKEN));
-
- return newSession(
- old.id(),
- tokens.accessToken(),
- tokens.idToken() != null ? tokens.idToken() : old.attributeAsString(ID_TOKEN),
- tokens.refreshToken() != null ? tokens.refreshToken() : old.attributeAsString(REFRESH_TOKEN),
- Instant.now().plusSeconds(tokens.expiresIn()),
- mergeRefreshedClaims(tokens, old)
- );
- }
-
- 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\"";
- }
-
- 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();
- }
-
- private static Map mergeRefreshedClaims(OidcTokenResponse tokens, Session old) {
- Map 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;
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java
deleted file mode 100644
index 65605f0..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java
+++ /dev/null
@@ -1,343 +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.ext.auth.AuthConfig;
-import dev.relism.flash.ext.auth.Session;
-import dev.relism.flash.ext.auth.AuthMiddleware;
-import dev.relism.flash.ext.auth.AuthPolicy;
-import dev.relism.flash.ext.auth.Authenticated;
-import dev.relism.flash.ext.auth.RolesAllowed;
-import dev.relism.flash.ext.auth.ScopesAllowed;
-import dev.relism.flash.extension.FlashContext;
-import dev.relism.flash.extension.FlashExtension;
-import dev.relism.flash.extension.FlashRegistrar;
-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.
- *
- * At {@link #provide}, the extension:
- *
- * - Fetches the provider discovery document — fail-fast at startup.
- * - Provides {@link AuthMiddleware}, {@link OidcCredentialSource} and {@link JwtValidator}
- * in the context.
- * - Registers annotation processors for {@link Authenticated}, {@link RolesAllowed}
- * and {@link ScopesAllowed}.
- *
- *
- * At {@link #routes}, three routes are registered:
- *
- * - {@code GET {prefix}/login} — builds the authorization URL and redirects.
- * - {@code GET {prefix}/callback} — exchanges the code, creates a session, redirects.
- * - {@code POST {prefix}/logout} — invalidates the session, redirects to provider
- * end-session endpoint (if available) or to {@link OidcConfig#postLogoutRedirectUri()}.
- *
- *
- * {@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));
- * }
- */
-public class OidcExtension implements FlashExtension {
-
- 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 OidcCredentialSource source;
- private AuthMiddleware authMw;
-
- 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);
- source = new OidcCredentialSource(validator, config, meta, tokenClient);
- authMw = AuthMiddleware.install(ctx, AuthConfig.builder()
- .rolesClaimPath(config.rolesClaimPath())
- .scopeClaimPaths(config.scopeClaimPaths())
- .build(), source);
-
- ctx.provide(OidcCredentialSource.class, source);
- ctx.provide(JwtValidator.class, validator);
-
- 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 claims = mergeClaims(tokens);
- Session session = OidcCredentialSource.newSession(
- 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 = OidcCredentialSource.cookieValue(req, "oidc_session");
- String idTokenHint = null;
-
- if (sessionId != null) {
- Session session = config.sessionStore().find(sessionId).orElse(null);
- if (session != null) idTokenHint = session.attributeAsString(OidcCredentialSource.ID_TOKEN);
- 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 mergeClaims(OidcTokenResponse tokens) {
- Map 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.
- * Only safe for development with self-signed certificates.
- */
- 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 OidcCredentialSource.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 componentContributions() {
- Map scopesMap = new LinkedHashMap<>();
- for (String s : config.scopes().split("\\s+")) {
- if (!s.isBlank()) scopesMap.put(s, s);
- }
- Map flow = new LinkedHashMap<>();
- flow.put("authorizationUrl", meta.authorizationEndpoint());
- flow.put("tokenUrl", meta.tokenEndpoint());
- flow.put("scopes", scopesMap);
-
- Map scheme = new LinkedHashMap<>();
- scheme.put("type", "oauth2");
- scheme.put("flows", Map.of("authorizationCode", flow));
-
- Map 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 operationScopes = AuthPolicy.openApiScopesFor(handlerClass);
- if (operationScopes != null) {
- out.security(config.schemeName(), operationScopes);
- }
-
- AuthPolicy policy = AuthPolicy.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";
- }
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcProviderMetadata.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcProviderMetadata.java
deleted file mode 100644
index cc783af..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcProviderMetadata.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-/**
- * OIDC provider endpoints discovered from {@code {issuer}/.well-known/openid-configuration}.
- *
- * {@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
-) {}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcStateStore.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcStateStore.java
deleted file mode 100644
index 4918cbd..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcStateStore.java
+++ /dev/null
@@ -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).
- *
- *
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 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 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()));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcTokenResponse.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcTokenResponse.java
deleted file mode 100644
index 8afad32..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcTokenResponse.java
+++ /dev/null
@@ -1,10 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-/** Parsed response from an OAuth2 token endpoint. Package-private — internal use only. */
-record OidcTokenResponse(
- String accessToken,
- String idToken, // may be null on refresh if provider omits it
- String refreshToken, // may be null
- int expiresIn,
- int refreshExpiresIn
-) {}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcValidationException.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcValidationException.java
deleted file mode 100644
index 202f75f..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcValidationException.java
+++ /dev/null
@@ -1,14 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import dev.relism.flash.exceptions.HttpException;
-
-/**
- * Thrown when OIDC token validation fails (signature, claims, nonce, expiry, etc.).
- * Distinct from {@link HttpException}: this signals a protocol-level
- * failure, not an HTTP response — callers decide the appropriate status code.
- */
-public final class OidcValidationException extends RuntimeException {
- public OidcValidationException(String message, Throwable cause) {
- super(message, cause);
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/PkceUtils.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/PkceUtils.java
deleted file mode 100644
index 99fc632..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/PkceUtils.java
+++ /dev/null
@@ -1,36 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import java.nio.charset.StandardCharsets;
-import java.security.MessageDigest;
-import java.security.SecureRandom;
-import java.util.Base64;
-
-/**
- * PKCE (RFC 7636) utilities: code verifier generation and S256 challenge computation.
- * Package-private — used exclusively by {@link OidcExtension}.
- */
-final class PkceUtils {
-
- private static final SecureRandom RANDOM = new SecureRandom();
-
- private PkceUtils() {}
-
- /**
- * Generates a cryptographically random code verifier (43 URL-safe characters,
- * per RFC 7636 §4.1 — 32 bytes encoded as unpadded Base64URL).
- */
- static String generateVerifier() {
- byte[] bytes = new byte[32];
- RANDOM.nextBytes(bytes);
- return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
- }
-
- /**
- * Computes the S256 code challenge: {@code BASE64URL(SHA-256(ASCII(verifier)))}.
- */
- static String computeChallenge(String verifier) throws Exception {
- byte[] digest = MessageDigest.getInstance("SHA-256")
- .digest(verifier.getBytes(StandardCharsets.US_ASCII));
- return Base64.getUrlEncoder().withoutPadding().encodeToString(digest);
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/TokenClient.java b/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/TokenClient.java
deleted file mode 100644
index a6be2c2..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/main/java/dev/relism/flash/ext/oidc/TokenClient.java
+++ /dev/null
@@ -1,112 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import net.minidev.json.JSONValue;
-
-import java.net.URI;
-import java.net.URLEncoder;
-import java.net.http.HttpClient;
-import java.net.http.HttpRequest;
-import java.net.http.HttpResponse;
-import java.nio.charset.StandardCharsets;
-import java.util.Base64;
-import java.util.LinkedHashMap;
-import java.util.Map;
-
-/**
- * HTTP client for OAuth2 token endpoint operations (pure HTTP, no SDK).
- *
- * Supports two client authentication methods (RFC 6749 §2.3):
- *
- * - {@link ClientAuthMethod#POST} — credentials in form body ({@code client_secret_post})
- * - {@link ClientAuthMethod#BASIC} — credentials in {@code Authorization: Basic} header
- * ({@code client_secret_basic})
- *
- */
-final class TokenClient {
-
- private final HttpClient http;
- private final String clientId;
- private final String clientSecret;
- private final ClientAuthMethod authMethod;
-
- TokenClient(HttpClient http, OidcConfig config) {
- this.http = http;
- this.clientId = config.clientId();
- this.clientSecret = config.clientSecret();
- this.authMethod = config.clientAuthMethod();
- }
-
- /** Authorization Code + PKCE exchange. */
- OidcTokenResponse exchangeCode(String tokenEndpoint,
- String code, String redirectUri,
- String codeVerifier) throws Exception {
- Map params = new LinkedHashMap<>();
- params.put("grant_type", "authorization_code");
- params.put("code", code);
- params.put("redirect_uri", redirectUri);
- params.put("code_verifier", codeVerifier);
- return post(tokenEndpoint, params);
- }
-
- /** Refresh token grant. */
- OidcTokenResponse refresh(String tokenEndpoint, String refreshToken) throws Exception {
- Map params = new LinkedHashMap<>();
- params.put("grant_type", "refresh_token");
- params.put("refresh_token", refreshToken);
- return post(tokenEndpoint, params);
- }
-
- // -- Internals ------------------------------------------------------------
-
- private OidcTokenResponse post(String url, Map params) throws Exception {
- HttpRequest.Builder req = HttpRequest.newBuilder()
- .uri(URI.create(url))
- .header("Content-Type", "application/x-www-form-urlencoded");
-
- if (authMethod == ClientAuthMethod.BASIC) {
- String creds = Base64.getEncoder().encodeToString(
- (clientId + ":" + clientSecret).getBytes(StandardCharsets.UTF_8));
- req.header("Authorization", "Basic " + creds);
- } else {
- params.put("client_id", clientId);
- params.put("client_secret", clientSecret);
- }
-
- HttpResponse resp = http.send(
- req.POST(HttpRequest.BodyPublishers.ofString(form(params))).build(),
- HttpResponse.BodyHandlers.ofString());
-
- if (resp.statusCode() < 200 || resp.statusCode() >= 300)
- throw new IllegalStateException(
- "Token endpoint [" + resp.statusCode() + "]: " + resp.body());
-
- @SuppressWarnings("unchecked")
- Map json = (Map) JSONValue.parse(resp.body());
-
- return new OidcTokenResponse(
- (String) json.get("access_token"),
- (String) json.get("id_token"),
- (String) json.get("refresh_token"),
- numInt(json, "expires_in", 300),
- numInt(json, "refresh_expires_in", 1800)
- );
- }
-
- private static String form(Map params) {
- StringBuilder sb = new StringBuilder();
- params.forEach((k, v) -> {
- if (!sb.isEmpty()) sb.append('&');
- sb.append(enc(k)).append('=').append(enc(v));
- });
- return sb.toString();
- }
-
- private static String enc(String v) {
- return URLEncoder.encode(v, StandardCharsets.UTF_8);
- }
-
- private static int numInt(Map m, String key, int def) {
- Object v = m.get(key);
- return v instanceof Number n ? n.intValue() : def;
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcCredentialSourceTest.java b/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcCredentialSourceTest.java
deleted file mode 100644
index 7f7d6dd..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcCredentialSourceTest.java
+++ /dev/null
@@ -1,43 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * What stayed behind when authorization moved to {@code flash-ext-auth-core}: reading a bearer
- * token off the wire, and the RFC 6750 challenges this source answers with. The matching of
- * claims those credentials produce is {@code ClaimMatchingTest}'s job now.
- */
-class OidcCredentialSourceTest {
-
- private static OidcCredentialSource source() {
- return new OidcCredentialSource(null, OidcConfig
- .builder("https://idp.example.com", "client", "secret", "/auth/callback")
- .build(), null, null);
- }
-
- @Test
- void extractBearerToken_acceptsCaseInsensitiveBearerAndTrimsSpaces() {
- assertEquals("abc.def.ghi", OidcCredentialSource.extractBearerToken("Bearer abc.def.ghi"));
- assertEquals("abc", OidcCredentialSource.extractBearerToken(" bearer abc "));
- assertNull(OidcCredentialSource.extractBearerToken("Basic Zm9vOmJhcg=="));
- assertNull(OidcCredentialSource.extractBearerToken("Bearer"));
- }
-
- @Test
- void bearerChallenge_containsRealmAndRfcErrors() {
- OidcCredentialSource src = source();
-
- String basic = src.bearerChallenge();
- String invalid = src.invalidTokenChallenge();
- String insufficient = src.insufficientScopeChallenge(new String[]{"orders:read", "payments:write"});
-
- assertTrue(basic.startsWith("Bearer realm=\""));
- assertTrue(invalid.contains("error=\"invalid_token\""));
- assertTrue(insufficient.contains("error=\"insufficient_scope\""));
- assertTrue(insufficient.contains("scope=\"orders:read payments:write\""));
- }
-}
diff --git a/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcOpenApiInteropTest.java b/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcOpenApiInteropTest.java
deleted file mode 100644
index 2597e90..0000000
--- a/flash-extensions/flash-ext-auth-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcOpenApiInteropTest.java
+++ /dev/null
@@ -1,128 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-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.ext.openapi.OpenApiContributor;
-import dev.relism.flash.ext.auth.AuthPolicy;
-import dev.relism.flash.ext.auth.Authenticated;
-import dev.relism.flash.ext.auth.RolesAllowed;
-import dev.relism.flash.ext.auth.ScopesAllowed;
-import dev.relism.flash.extension.FlashContext;
-import org.junit.jupiter.api.Test;
-
-import java.lang.reflect.Constructor;
-import java.lang.reflect.Method;
-import java.util.List;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-class OidcOpenApiInteropTest {
-
- @Authenticated
- static class AuthOnly {}
-
- @Authenticated(optional = true)
- static class AuthOptional {}
-
- @RolesAllowed("admin")
- static class OneRole {}
-
- @RolesAllowed({"admin", "operator"})
- static class MultiRole {}
-
- @ScopesAllowed("orders:write")
- static class OneScope {}
-
- @ScopesAllowed({"orders:write", "payments:write"})
- static class MultiScope {}
-
- @RolesAllowed("admin")
- @ScopesAllowed("orders:write")
- static class RoleAndScope {}
-
- @Test
- void autoResponses_authOnly() throws Exception {
- Map responses = responses(AuthOnly.class);
- assertEquals("Authentication required", responses.get(401));
- assertFalse(responses.containsKey(403));
- }
-
- @Test
- void autoResponses_optionalAuth_addsNothing() throws Exception {
- Map responses = responses(AuthOptional.class);
- assertTrue(responses.isEmpty());
- }
-
- @Test
- void autoResponses_oneRole_formatsSingular() throws Exception {
- Map responses = responses(OneRole.class);
- assertEquals("Authentication required", responses.get(401));
- assertEquals("\"admin\" role required", responses.get(403));
- }
-
- @Test
- void autoResponses_multiRoles_formatsPlural() throws Exception {
- Map responses = responses(MultiRole.class);
- assertEquals("Roles \"admin, operator\" are required", responses.get(403));
- }
-
- @Test
- void autoResponses_oneScope_formatsSingular() throws Exception {
- Map responses = responses(OneScope.class);
- assertEquals("\"orders:write\" scope required", responses.get(403));
- }
-
- @Test
- void autoResponses_multiScopes_formatsPlural() throws Exception {
- Map responses = responses(MultiScope.class);
- assertEquals("Scopes \"orders:write, payments:write\" are required", responses.get(403));
- }
-
- @Test
- void autoResponses_roleAndScope_combinesMessages() throws Exception {
- Map responses = responses(RoleAndScope.class);
- assertEquals("\"admin\" role required; \"orders:write\" scope required", responses.get(403));
- }
-
- @Test
- void securityContribution_presentForAuthenticatedHandler() throws Exception {
- OpenApiOperationContribution operation = contributor().operationFor(AuthOnly.class);
- List>> security = operation.security();
- assertEquals(1, security.size());
- assertTrue(security.getFirst().containsKey("issuer"));
- }
-
- private static OpenApiContributor contributor() throws Exception {
- Class clazz = Class.forName("dev.relism.flash.ext.oidc.OidcExtension$OpenApiIntegration");
- Constructor ctor = clazz.getDeclaredConstructor();
- ctor.setAccessible(true);
- Object instance = ctor.newInstance();
-
- Method m = clazz.getDeclaredMethod("register", FlashContext.class, OidcConfig.class, OidcProviderMetadata.class);
- m.setAccessible(true);
-
- FlashContext ctx = new FlashContext();
- OpenApiContributorRegistry registry = new OpenApiContributorRegistry();
- ctx.provide(OpenApiContributorRegistry.class, registry);
- ctx.complete();
-
- OidcConfig config = OidcConfig.builder("https://issuer", "c", "s", "/cb").build();
- OidcProviderMetadata meta = new OidcProviderMetadata("a", "t", "u", "j", "e");
- m.invoke(instance, ctx, config, meta);
-
- return registry.contributors().getFirst();
- }
-
- private static Map responses(Class cls) throws Exception {
- Map byCode = contributor().operationFor(cls).responses();
- java.util.LinkedHashMap out = new java.util.LinkedHashMap<>();
- for (Map.Entry e : byCode.entrySet()) {
- out.put(e.getKey(), e.getValue().description());
- }
- return out;
- }
-}
diff --git a/flash-extensions/flash-ext-limiter/docs/README.md b/flash-extensions/flash-ext-limiter/docs/README.md
index 098b0d8..8f1568a 100644
--- a/flash-extensions/flash-ext-limiter/docs/README.md
+++ b/flash-extensions/flash-ext-limiter/docs/README.md
@@ -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))
diff --git a/flash-extensions/flash-ext-limiter/docs/key-resolvers.md b/flash-extensions/flash-ext-limiter/docs/key-resolvers.md
index 1b39d34..137d2cf 100644
--- a/flash-extensions/flash-ext-limiter/docs/key-resolvers.md
+++ b/flash-extensions/flash-ext-limiter/docs/key-resolvers.md
@@ -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
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/KeyResolver.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/KeyResolver.java
index 7fd678a..f8848e9 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/KeyResolver.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/KeyResolver.java
@@ -11,7 +11,7 @@ import dev.relism.flash.models.Request;
*
* {@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());
* }
*/
@FunctionalInterface
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterConfig.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterConfig.java
index 607db07..b6b93df 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterConfig.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterConfig.java
@@ -21,8 +21,8 @@ import java.util.Map;
* {@code
* LimiterConfig conf = new LimiterConfig()
* .registerResolver("auth_user", req -> {
- * // custom logic — e.g. extract sub from ClaimsHolder
- * return ClaimsHolder.exists() ? ClaimsHolder.user().sub() : "anonymous";
+ * // custom logic — e.g. key by the authenticated caller
+ * return SecurityIdentity.current() != null ? SecurityIdentity.current().principal().name() : "anonymous";
* });
*
* app.install(new LimiterExtension(conf));
diff --git a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterExtension.java b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterExtension.java
index 9f09e85..7e5c5b2 100644
--- a/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterExtension.java
+++ b/flash-extensions/flash-ext-limiter/src/main/java/dev/relism/flash/ext/limiter/LimiterExtension.java
@@ -43,7 +43,7 @@ import java.util.Map;
* Lambda routes (via Guard)
* {@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);
diff --git a/flash-extensions/flash-ext-mcp/docs/README.md b/flash-extensions/flash-ext-mcp/docs/README.md
index 4022668..5d9ee7f 100644
--- a/flash-extensions/flash-ext-mcp/docs/README.md
+++ b/flash-extensions/flash-ext-mcp/docs/README.md
@@ -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-auth-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-auth-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`
diff --git a/flash-extensions/flash-ext-mcp/docs/jackson-interop.md b/flash-extensions/flash-ext-mcp/docs/jackson-interop.md
index a968ad9..19873c4 100644
--- a/flash-extensions/flash-ext-mcp/docs/jackson-interop.md
+++ b/flash-extensions/flash-ext-mcp/docs/jackson-interop.md
@@ -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-auth-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)` 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
-already used for `McpSecurity.AUTO`. That would be purely additive on top of the
+`flash-ext-jackson` isn't installed. 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.
diff --git a/flash-extensions/flash-ext-mcp/docs/keycloak.md b/flash-extensions/flash-ext-mcp/docs/keycloak.md
deleted file mode 100644
index e930b77..0000000
--- a/flash-extensions/flash-ext-mcp/docs/keycloak.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Keycloak cookbook
-
-`security.md` covers the OAuth2 mechanics `McpOidcIntegration` implements against any
-`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.
-
-## 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= does not include expected
-resource identifier "" — ...
-```
-
-`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`.
diff --git a/flash-extensions/flash-ext-mcp/docs/security.md b/flash-extensions/flash-ext-mcp/docs/security.md
index f6fa0d0..917fc94 100644
--- a/flash-extensions/flash-ext-mcp/docs/security.md
+++ b/flash-extensions/flash-ext-mcp/docs/security.md
@@ -1,188 +1,47 @@
# Security
-Provider-specific setup steps (not generic OAuth2 mechanics) live in separate cookbooks —
-[`keycloak.md`](keycloak.md) for Keycloak: enabling Dynamic Client Registration, why the RFC 8707
-audience mapper needs to go on the built-in `basic` scope instead of a custom one, and the exact
-Allowed Client Scopes configuration `scopes_supported` needs to actually work.
+The MCP endpoint is secured by [`flash-ext-security-core`](../../flash-ext-security-core/docs/README.md):
+whatever mechanisms the application registers — OAuth2 bearer tokens, API keys, custom ones —
+authenticate `/mcp` exactly as they authenticate every other route.
-## `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-auth-oidc` being
-installed (`ctx.find(OidcMiddleware.class)`), resolved once at boot in `McpExtension.routes()`:
+## OAuth2 protected resource
-| Policy | `flash-ext-auth-oidc` installed | `flash-ext-auth-oidc` absent |
-|---|---|---|
-| `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 |
+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:
-### Guarding `/mcp` without OAuth2
+- `GET /.well-known/oauth-protected-resource/mcp` serves RFC 9728 metadata: the `resource` (derived per
+ request from `X-Forwarded-Proto`/`-Host` or `Host`), every issuer as `authorization_servers`, and
+ `scopes_supported` when `McpConfig.scopesSupported(...)` is set;
+- 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.
-`McpSecurity` only ever answers "is `flash-ext-auth-oidc` installed". An app that authenticates
-some other way sets `McpSecurity.NONE` and supplies its own guard:
+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.
+
+`McpConfig.requireTokenAudience(false)` drops that last check for an authorization server that cannot
+mint a resource audience at all — Keycloak ignores RFC 8707's `resource` parameter, so a deployment that
+cannot add the mapper has no other way in. Every token a registered issuer signs is then accepted on the
+endpoint, and the boot logs say so.
+
+## Tool policies
+
+The core annotations work on tools as on handlers, checked per `tools/call` against the caller the route
+authenticated:
```java
-McpConfig.builder("my-server")
- .toolsPackage("com.example.mcp")
- .security(McpSecurity.NONE)
- .middleware(myAuthMiddleware.protect())
- .build();
+@Tool(name = "approve", description = "Approves a pending proposal")
+@RolesAllowed(value = "REVIEWER", on = {"project", "locale"}) // read from the tool's arguments
+public class ApproveTool extends McpTool { … }
```
-`McpConfig.middleware(...)` runs after the transport guards and after whatever `McpSecurity`
-resolved to, so it composes with OAuth2 protection rather than replacing it — the same hook is how
-you add rate limiting, audit logging or tracing to the endpoint. It never satisfies `REQUIRED`,
-which still asks for a real authorization server.
+A denial is a tool result with `isError: true` — the call reached the server, the tool did not run.
-Use `REQUIRED` for anything you intend to run in production reachable over the network — it
-turns "someone forgot to wire up OAuth2" into a startup crash instead of a silently open
-endpoint. `AUTO` is meant for local development, where spinning up a real identity provider is
-friction you don't want yet.
-
-## Why `flash-ext-auth-oidc` is an *optional* Maven dependency, concretely
-
-Maven's `true` only affects **transitive** propagation: consumers of
-`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-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
-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
-
-When oidc is available and `security() != NONE`, `McpOidcIntegration` (an isolated,
-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-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.
-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-auth-oidc`'s `@RolesAllowed`/`@ScopesAllowed`:
-
-```java
-@Tool(name = "delete_route", description = "Delete a route")
-@RolesAllowed("admin")
-public class DeleteRouteTool extends McpTool {
- @Override public ToolResponse call(ToolArguments args) { ... }
-}
-```
-
-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,
-`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
-`"realm_access.roles"`, matching `OidcConfig`'s own default — set this explicitly if the two
-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
-tool call is already authenticated — there's no per-tool public/authenticated split the way
-there is for HTTP routes, so a bare `@Authenticated` on a tool can't mean anything and would
-silently do nothing if allowed to compile. Boot fails instead, with a message pointing at
-`@RolesAllowed`/`@ScopesAllowed` as the actual narrowing mechanism.
-
-**Annotating a tool without active OAuth2 also fails boot**, not silently at request time: if
-`@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
-
-`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
-`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.
+`McpConfig.middleware(...)` runs after authentication, for rate limiting, auditing or tracing.
diff --git a/flash-extensions/flash-ext-mcp/pom.xml b/flash-extensions/flash-ext-mcp/pom.xml
index b0a873f..314d91a 100644
--- a/flash-extensions/flash-ext-mcp/pom.xml
+++ b/flash-extensions/flash-ext-mcp/pom.xml
@@ -19,8 +19,7 @@
dev.relism
- flash-ext-auth-oidc
- true
+ flash-ext-security-core
com.fasterxml.jackson.core
@@ -43,6 +42,22 @@
flash-testing
test
+
+ dev.relism
+ flash-ext-security-test
+
+
+ dev.relism
+ flash-ext-security-oidc
+ ${project.version}
+ test
+
+
+ dev.relism
+ flash-ext-security-apikey
+ ${project.version}
+ test
+
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpAuthPolicy.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpAuthPolicy.java
deleted file mode 100644
index 6bdd880..0000000
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpAuthPolicy.java
+++ /dev/null
@@ -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.
- *
- * {@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-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}.
- *
- *
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 check) {}
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpConfig.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpConfig.java
index 805d53b..d8268a7 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpConfig.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpConfig.java
@@ -26,8 +26,7 @@ public final class McpConfig {
private final String rootPath;
private final String toolsPackage;
private final McpSecurity security;
- private final String resourceIdentifier;
- private final String authorizationServerIssuer;
+ private final boolean requireTokenAudience;
private final List allowedOrigins;
private final List scopesSupported;
private final List middleware;
@@ -39,8 +38,7 @@ public final class McpConfig {
this.rootPath = b.rootPath;
this.toolsPackage = b.toolsPackage;
this.security = b.security;
- this.resourceIdentifier = b.resourceIdentifier;
- this.authorizationServerIssuer = b.authorizationServerIssuer;
+ this.requireTokenAudience = b.requireTokenAudience;
this.allowedOrigins = List.copyOf(b.allowedOrigins);
this.scopesSupported = List.copyOf(b.scopesSupported);
this.middleware = List.copyOf(b.middleware);
@@ -52,8 +50,7 @@ public final class McpConfig {
String rootPath() { return rootPath; }
String toolsPackage() { return toolsPackage; }
McpSecurity security() { return security; }
- String resourceIdentifier() { return resourceIdentifier; }
- String authorizationServerIssuer() { return authorizationServerIssuer; }
+ boolean requireTokenAudience() { return requireTokenAudience; }
List allowedOrigins() { return allowedOrigins; }
List scopesSupported() { return scopesSupported; }
List middleware() { return middleware; }
@@ -66,9 +63,8 @@ public final class McpConfig {
private String instructions;
private String rootPath = "/mcp";
private String toolsPackage;
- private McpSecurity security = McpSecurity.AUTO;
- private String resourceIdentifier;
- private String authorizationServerIssuer;
+ private McpSecurity security = McpSecurity.REQUIRED;
+ private boolean requireTokenAudience = true;
private final List allowedOrigins = new ArrayList<>();
private final List scopesSupported = new ArrayList<>();
private final List middleware = new ArrayList<>();
@@ -91,28 +87,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
- * {@code aud} claim does not include this value are rejected. Optional — when
- * {@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
- * {@code X-Forwarded-Host} nor {@code X-Forwarded-Proto}.
+ * Whether a bearer token must name this endpoint in its {@code aud} (RFC 8707), as the MCP
+ * authorization spec requires. Default {@code true}. Turn it off for an authorization server
+ * that cannot mint a resource audience — every token a registered issuer signs is then
+ * accepted on the endpoint, and a warning is logged at boot.
*/
- public Builder resourceIdentifier(String resourceIdentifier) { this.resourceIdentifier = resourceIdentifier; 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-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).
- */
- public Builder authorizationServerIssuer(String issuer) { this.authorizationServerIssuer = issuer; return this; }
+ public Builder requireTokenAudience(boolean require) { this.requireTokenAudience = require; return this; }
/**
* Origins allowed to call the MCP endpoint (DNS-rebinding protection, per the Streamable
@@ -121,30 +105,10 @@ public final class McpConfig {
*/
public Builder allowedOrigins(String... origins) { this.allowedOrigins.addAll(List.of(origins)); return this; }
- /**
- * 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.
- */
+ /** Published as {@code scopes_supported} in the RFC 9728 metadata, so OAuth clients request them. */
public Builder scopesSupported(String... scopes) { this.scopesSupported.addAll(List.of(scopes)); return this; }
- /**
- * Middleware to run on the MCP route, in the order given, after the transport guards and
- * after whatever {@link McpSecurity} resolved to. Rate limiting, audit logging, tracing —
- * anything that is routine on every other Flash route and had no way in here.
- *
- * It runs on an authenticated request when OAuth2 protection is active, and is the only
- * thing standing in front of the endpoint when it is not: {@link McpSecurity#NONE} plus a
- * middleware of your own is how an app that authenticates some other way guards
- * {@code /mcp}. It never satisfies {@link McpSecurity#REQUIRED}, which still asks for a
- * real authorization server.
- */
+ /** 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;
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpDispatcher.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpDispatcher.java
index 86271d1..90fe905 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpDispatcher.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpDispatcher.java
@@ -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
- * OidcMiddleware}/audience-guard middleware chain, before this dispatcher ever runs.
+ * route-wide 401/403 already happened earlier, in the security middleware, before this
+ * 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 (denied != null) {
- result = ToolResponse.error("Tool \"" + name + "\" denied: " + denied);
+ if (policy != null && !policy.permitsScopes(SecurityIdentity.current())) {
+ result = ToolResponse.error("Tool \"" + name + "\" denied: missing scope");
+ } 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) {
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpExtension.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpExtension.java
index a7a81c8..82a1292 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpExtension.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpExtension.java
@@ -1,5 +1,10 @@
package dev.relism.flash.ext.mcp;
+import dev.relism.flash.exceptions.HttpException;
+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,38 +14,25 @@ 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
- * {@code POST} JSON-RPC endpoint, stateless in this revision (no session, no SSE stream; see
- * {@code docs/transport.md}) — dispatch precompiled at boot from classes annotated with
- * {@link Tool @Tool}/{@link Resource @Resource}/{@link Prompt @Prompt} under
+ * MCP (Model Context Protocol) server extension. Streamable HTTP transport — a single {@code POST}
+ * JSON-RPC endpoint, stateless in this revision (see {@code docs/transport.md}) — dispatching to
+ * {@link Tool @Tool}/{@link Resource @Resource}/{@link Prompt @Prompt} classes under
* {@link McpConfig#toolsPackage(String)}.
*
*
{@code
- * // Standalone, no OAuth2
- * FlashApp.create(8080)
- * .install(new McpExtension(McpConfig.builder("my-mcp-server")
- * .toolsPackage("com.example.tools")
- * .build()))
- * .start();
- *
- * // 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)
- * .install(new OidcExtension(oidcConfig))
- * .install(new McpExtension(McpConfig.builder("my-mcp-server")
- * .toolsPackage("com.example.tools")
- * .security(McpSecurity.REQUIRED)
- * .build()))
- * .start();
+ * app.install(new SecurityExtension())
+ * .install(new OidcExtension(OidcProvider.of("sso", issuer, clientId, secret)))
+ * .install(new McpExtension(McpConfig.builder("my-server").toolsPackage("com.example.tools").build()));
* }
*
- * One server per {@code McpExtension} instance — install multiple instances (distinct
- * {@code rootPath}, distinct {@code toolsPackage}) for multiple MCP servers on one app,
- * mirroring the {@code OidcExtension} multi-tenant pattern. See {@code docs/security.md} for
- * the full OAuth2 resolution rules.
+ *
Every call is authenticated by the application's security chain — OAuth2 bearer tokens, API
+ * keys, anything registered. When an OAuth2 issuer is among its schemes, the endpoint is also an
+ * OAuth2 protected resource: RFC 9728 metadata, a {@code resource_metadata} challenge, and RFC 8707
+ * 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 {
@@ -53,69 +45,54 @@ 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) {
- // Resolved before scanning so McpRegistry knows, per tool, whether @RolesAllowed/
- // @ScopesAllowed are backed by real OAuth2 protection or a boot-time misconfiguration
- // (see McpOidcIntegration#compileToolPolicy) — must run first, not after.
- McpOidcIntegration.Resolved secured = resolveSecurity(ctx);
- McpRegistry registry = McpRegistry.scan(config.toolsPackage(), ctx, secured != null,
- secured == null ? null : secured.rolesClaimPath());
- McpDispatcher dispatcher = new McpDispatcher(registry, config.name(), config.version(), config.instructions());
-
- List chain = new ArrayList<>(3 + config.middleware().size());
- chain.add(McpTransportGuards.httpExceptionGuard());
- chain.add(McpTransportGuards.originGuard(config.allowedOrigins()));
- if (secured != null) chain.add(secured.security());
- chain.addAll(config.middleware());
-
- 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-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-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-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;
- }
-
- /**
- * 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());
+ List chain = new ArrayList<>(List.of(
+ McpTransportGuards.httpExceptionGuard(), McpTransportGuards.originGuard(config.allowedOrigins())));
+ if (security != null) protect(app, security, chain);
+ chain.addAll(config.middleware());
+ app.post(config.rootPath(), (req, res) -> {
+ dispatcher.handle(req, res);
+ return null;
+ }, chain.toArray(Middleware[]::new));
});
}
+
+ private void protect(FlashRegistrar app, SecurityExtension security, List chain) {
+ String metadataPath = "/.well-known/oauth-protected-resource" + config.rootPath();
+ chain.add(security.enforce(SecurityPolicy.AUTHENTICATED, (req, res) -> {
+ List issuers = issuers(security);
+ res.header("WWW-Authenticate", issuers.isEmpty()
+ ? String.join(", ", security.schemes().stream().map(SecurityScheme::challenge).toList())
+ : "Bearer resource_metadata=\"" + req.origin() + metadataPath + "\"");
+ throw HttpException.unauthorized();
+ }));
+ if (config.requireTokenAudience()) {
+ chain.add(next -> (req, res) -> {
+ String resource = req.origin() + 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 issuers = issuers(security);
+ if (issuers.isEmpty()) throw HttpException.notFound("Protected resource metadata");
+ res.type(ContentType.JSON);
+ return McpResourceMetadata.build(req.origin() + config.rootPath(), issuers, config.scopesSupported());
+ });
+ }
+
+ private static List issuers(SecurityExtension security) {
+ return security.schemes().stream().map(SecurityScheme::issuer).filter(Objects::nonNull).toList();
+ }
}
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpJson.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpJson.java
index 64f3c4e..07636bd 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpJson.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpJson.java
@@ -19,7 +19,7 @@ import java.nio.charset.StandardCharsets;
*
* 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-auth-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.
*/
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java
deleted file mode 100644
index 5262bb4..0000000
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java
+++ /dev/null
@@ -1,186 +0,0 @@
-package dev.relism.flash.ext.mcp;
-
-import dev.relism.flash.ext.auth.AuthMiddleware;
-import dev.relism.flash.ext.auth.Authenticated;
-import dev.relism.flash.ext.auth.Claims;
-import dev.relism.flash.ext.auth.ClaimsHolder;
-import dev.relism.flash.ext.auth.RolesAllowed;
-import dev.relism.flash.ext.auth.ScopesAllowed;
-import dev.relism.flash.ext.oidc.OidcCredentialSource;
-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-auth-oidc} and {@code flash-ext-auth-core}.
- *
- *
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-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.
- *
- *
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.
- * {@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 resourceIdentifier) {}
-
- /** Returns the resolved security bundle, or {@code null} if oidc is not installed. */
- static Resolved resolve(FlashContext ctx, McpConfig config) {
- // Deliberately keyed on the OIDC source and not on AuthMiddleware: McpSecurity means
- // "a real OAuth2 authorization server is protecting this endpoint", and an app that
- // authenticates some other way must not satisfy REQUIRED by accident.
- Optional oidc = ctx.find(OidcCredentialSource.class);
- Optional auth = ctx.find(AuthMiddleware.class);
- if (oidc.isEmpty() || auth.isEmpty()) return null;
-
- OidcCredentialSource source = oidc.get();
- AuthMiddleware authMw = auth.get();
- String resourceMetadataPath = "/.well-known/oauth-protected-resource" + config.rootPath();
- String issuer = config.authorizationServerIssuer() != null
- ? config.authorizationServerIssuer() : source.issuer();
- Function resourceId = req -> config.resourceIdentifier() != null
- ? config.resourceIdentifier()
- : OidcCredentialSource.selfOrigin(req, source.selfScheme()) + config.rootPath();
-
- Middleware protect = authMw.withSource(source.withResourceMetadata(resourceMetadataPath)).protect();
- Middleware secured = Middleware.of(protect, audienceGuard(resourceId));
- return new Resolved(secured, issuer, authMw.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 resourceIdentifier) {
- return next -> (req, res) -> {
- Map claims = ClaimsHolder.map();
- 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 Claims#hasRole}/{@link Claims#hasScope} already do.
- *
- * 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 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-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() + ".");
- }
- 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 check = () -> {
- Claims user = ClaimsHolder.current();
- 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(Claims user, String claimPath, String[] roles) {
- for (String role : roles) if (user.hasRole(claimPath, role)) return true;
- return false;
- }
-
- private static boolean hasScopes(Claims 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 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);
- }
-}
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpRegistry.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpRegistry.java
index 61105d4..a109f6b 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpRegistry.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpRegistry.java
@@ -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 oidcActive whether this MCP server's route is actually OAuth2-protected right
- * 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) {
+ /** @param security {@code null} for a server running with {@link McpSecurity#NONE} */
+ static McpRegistry scan(String packageName, FlashContext ctx, SecurityExtension security) {
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-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
- * McpOidcIntegration#resolve} has already succeeded once this boot, which proves those
- * types resolve fine).
- */
- private static McpAuthPolicy compileToolPolicy(Class cls, boolean oidcActive,
- String rolesClaimPath) {
- try {
- return McpOidcIntegration.compileToolPolicy(cls, oidcActive, rolesClaimPath);
- } catch (NoClassDefFoundError e) {
- return null;
- }
- }
-
private static T instantiate(Class cls) {
try {
Constructor ctor = cls.getDeclaredConstructor();
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpResourceMetadata.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpResourceMetadata.java
index 55a7eb9..4fced75 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpResourceMetadata.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpResourceMetadata.java
@@ -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. */
- static String build(String resourceIdentifier, String authorizationServerIssuer, List scopesSupported) {
+ /** {@code scopesSupported} is optional — omitted when empty. */
+ static String build(String resource, List authorizationServers, List 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");
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpSecurity.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpSecurity.java
index 21ee37b..b8eedab 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpSecurity.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpSecurity.java
@@ -1,17 +1,11 @@
package dev.relism.flash.ext.mcp;
-/**
- * OAuth2 requirement policy for the MCP endpoint, resolved against whether
- * {@code flash-ext-auth-oidc} is installed ({@code ctx.find(OidcMiddleware.class)}).
- */
+/** Whether the MCP endpoint requires an authenticated caller. */
public enum McpSecurity {
- /** Fail fast at boot if {@code flash-ext-auth-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-auth-oidc} is installed; otherwise run unprotected and log a warning. */
- AUTO,
-
- /** Never protect the endpoint, even if {@code flash-ext-auth-oidc} is installed elsewhere in the app. */
+ /** A public endpoint. Tools declaring security annotations fail the boot. */
NONE
}
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpTransportGuards.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpTransportGuards.java
index af6be7b..c6447bf 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpTransportGuards.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpTransportGuards.java
@@ -19,7 +19,7 @@ final class McpTransportGuards {
* allowed through — only a present but disallowed value is rejected.
*
* 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 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-auth-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
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java
deleted file mode 100644
index 799a7a4..0000000
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java
+++ /dev/null
@@ -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-auth-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.auth.Claims#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); }
-}
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpAuthPolicyTest.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpAuthPolicyTest.java
deleted file mode 100644
index af42bdb..0000000
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpAuthPolicyTest.java
+++ /dev/null
@@ -1,141 +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 dev.relism.flash.extension.FlashConfiguration;
-import dev.relism.flash.testing.FlashResponse;
-import dev.relism.flash.testing.FlashTest;
-import org.junit.jupiter.api.AfterAll;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.RegisterExtension;
-
-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 static final FakeOidcProvider provider = newProvider();
-
- @RegisterExtension
- static FlashTest secured = FlashTest.of(app -> {
- 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.REQUIRED)
- .build()));
- });
-
- /** Tokens are audience-bound to this server, so the port has to be read back after boot. */
- private static String resourceId() {
- return "http://127.0.0.1:" + secured.port() + "/mcp";
- }
-
- @AfterAll
- static void closeProvider() {
- provider.close();
- }
-
- // ── Tool policy ──────────────────────────────────────────────────────────
-
- @Test
- void rolesAllowed_deniesWithoutRole_allowsWithRole() throws Exception {
- callTool("admin_only", provider.signToken("user-1", resourceId(), null))
- .expectStatus(200)
- .expectBodyContains("\"isError\":true")
- .expectBodyContains("missing required role");
-
- callTool("admin_only", provider.signToken("user-1", resourceId(), null, "admin"))
- .expectStatus(200)
- .expectBodyContains("\"isError\":false")
- .expectBodyContains("ok");
- }
-
- @Test
- void scopesAllowed_deniesWithoutScope_allowsWithScope() throws Exception {
- callTool("write_only", provider.signToken("user-1", resourceId(), "read"))
- .expectStatus(200)
- .expectBodyContains("\"isError\":true")
- .expectBodyContains("missing required scope");
-
- callTool("write_only", provider.signToken("user-1", resourceId(), "read write"))
- .expectStatus(200)
- .expectBodyContains("\"isError\":false")
- .expectBodyContains("written");
- }
-
- @Test
- void unannotatedTool_unaffectedByOtherToolsPolicies() throws Exception {
- callTool("open", provider.signToken("user-1", resourceId(), null))
- .expectStatus(200)
- .expectBodyContains("\"isError\":false")
- .expectBodyContains("open");
- }
-
- private static FlashResponse callTool(String toolName, String token) {
- return secured.request()
- .header("Accept", "application/json")
- .header("Authorization", "Bearer " + token)
- .json("{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\""
- + toolName + "\"}}")
- .post("/mcp");
- }
-
- // ── Boot-time rejection ──────────────────────────────────────────────────
- // These assert that start() throws, so they build the app directly rather than through
- // FlashTest — a harness whose job is to boot an app is the wrong tool for asserting that
- // booting fails. Port 0 still removes the old free-port dance.
-
- private FlashApp bootFailure;
-
- @AfterEach
- void releaseBootFailureListener() {
- if (bootFailure != null) bootFailure.stop().join();
- }
-
- @Test
- void toolAnnotated_butSecurityNone_failsAtBoot() {
- bootFailure = mcpApp(SECURED_TOOLS, McpSecurity.NONE);
-
- IllegalStateException error = assertThrows(IllegalStateException.class, bootFailure::start);
- assertTrue(error.getMessage().contains("no active OAuth2 protection"), error.getMessage());
- }
-
- @Test
- void bareAuthenticated_hasNoEffect_failsAtBoot() {
- bootFailure = mcpApp(AUTHENTICATED_ONLY_TOOLS, McpSecurity.REQUIRED);
-
- IllegalStateException error = assertThrows(IllegalStateException.class, bootFailure::start);
- assertTrue(error.getMessage().contains("no effect"), error.getMessage());
- }
-
- private static FlashApp mcpApp(String toolsPackage, McpSecurity security) {
- FlashApp app = FlashApp.create(FlashConfiguration.builder()
- .port(0).host("127.0.0.1").shutdownDrainTimeoutMs(250).build());
- 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(security)
- .build()));
- return app;
- }
-
- private static FakeOidcProvider newProvider() {
- try {
- return new FakeOidcProvider();
- } catch (Exception failure) {
- throw new IllegalStateException("Could not start the fake OIDC provider", failure);
- }
- }
-}
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpExtensionSecurityTest.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpExtensionSecurityTest.java
deleted file mode 100644
index 4b8f606..0000000
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpExtensionSecurityTest.java
+++ /dev/null
@@ -1,179 +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 dev.relism.flash.extension.FlashApplication;
-import dev.relism.flash.extension.FlashConfiguration;
-import dev.relism.flash.testing.FlashRequest;
-import dev.relism.flash.testing.FlashResponse;
-import dev.relism.flash.testing.FlashTest;
-import org.junit.jupiter.api.AfterAll;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.RegisterExtension;
-
-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-auth-oidc}
- * installation backed by {@link FakeOidcProvider} — real discovery, real JWKS, real RS256
- * tokens — plus the fail-fast/degrade behavior when oidc is absent.
- *
- * Four server configurations differ only in how MCP security is declared, so each gets its
- * own {@link FlashTest} and they share one provider.
- */
-class McpExtensionSecurityTest {
-
- private static final String TOOLS_PACKAGE = "dev.relism.flash.ext.mcp.fixtures";
- private static final String EXPLICIT_RESOURCE_ID = "https://mcp.example.com/mcp";
-
- private static final FakeOidcProvider provider = newProvider();
-
- /** MCP asked for AUTO security with no oidc installed — should degrade to public. */
- @RegisterExtension
- static FlashTest degraded = FlashTest.of(app -> app.install(new McpExtension(
- McpConfig.builder("auto-server")
- .toolsPackage(TOOLS_PACKAGE)
- .security(McpSecurity.AUTO)
- .build())));
-
- /** REQUIRED with oidc, resource identifier derived from the request. */
- @RegisterExtension
- static FlashTest secured = FlashTest.of(securedApp(null, null));
-
- /** REQUIRED with oidc and an explicitly declared resource identifier. */
- @RegisterExtension
- static FlashTest securedWithResourceId = FlashTest.of(securedApp(EXPLICIT_RESOURCE_ID, null));
-
- /** REQUIRED with oidc and advertised scopes. */
- @RegisterExtension
- static FlashTest securedWithScopes =
- FlashTest.of(securedApp(null, new String[] {"openid", "profile", "email"}));
-
- @AfterAll
- static void closeProvider() {
- provider.close();
- }
-
- // ── No oidc installed ────────────────────────────────────────────────────
-
- @Test
- void required_withoutOidc_throwsAtBoot() {
- // Asserting that boot fails, so this one builds its app directly rather than through
- // the harness; port(0) still removes the old free-port dance.
- FlashApp app = FlashApp.create(FlashConfiguration.builder()
- .port(0).host("127.0.0.1").shutdownDrainTimeoutMs(250).build());
- app.install(new McpExtension(McpConfig.builder("secure-server")
- .toolsPackage(TOOLS_PACKAGE)
- .security(McpSecurity.REQUIRED)
- .build()));
- try {
- assertThrows(IllegalStateException.class, app::start);
- } finally {
- app.stop().join();
- }
- }
-
- @Test
- void auto_withoutOidc_degradesToPublic() {
- post(degraded, initializeBody(), null).expectStatus(200);
- }
-
- // ── REQUIRED with oidc ───────────────────────────────────────────────────
-
- @Test
- void required_withOidc_rejectsMissingToken() {
- post(secured, initializeBody(), null).expectStatus(401);
- }
-
- @Test
- void required_withOidc_rejectsWrongAudience() throws Exception {
- String token = provider.signToken("user-1", "https://someone-else.example.com/resource");
-
- post(securedWithResourceId, initializeBody(), token).expectStatus(403);
- }
-
- @Test
- void required_withOidc_acceptsValidAudience() throws Exception {
- String token = provider.signToken("user-1", EXPLICIT_RESOURCE_ID);
-
- post(securedWithResourceId, initializeBody(), token)
- .expectStatus(200)
- .expectBodyContains("\"protocolVersion\"");
- }
-
- @Test
- void required_withOidc_noExplicitResourceIdentifier_derivesFromRequestAndEnforcesAudience() throws Exception {
- String derivedResourceId = "http://127.0.0.1:" + secured.port() + "/mcp";
-
- post(secured, initializeBody(), provider.signToken("user-1", derivedResourceId))
- .expectStatus(200);
- post(secured, initializeBody(), provider.signToken("user-1", "https://someone-else.example.com/resource"))
- .expectStatus(403);
- }
-
- @Test
- void required_withOidc_missingToken_challengeIncludesResourceMetadata() {
- FlashResponse response = post(secured, initializeBody(), null).expectStatus(401);
-
- String challenge = response.header("WWW-Authenticate");
- assertTrue(challenge != null && challenge.contains("resource_metadata=\"http://127.0.0.1:"
- + secured.port() + "/.well-known/oauth-protected-resource/mcp\""),
- "WWW-Authenticate: " + challenge);
- }
-
- // ── Protected resource metadata ──────────────────────────────────────────
-
- @Test
- void required_withOidc_noExplicitConfig_publishesProtectedResourceMetadata() {
- FlashResponse response = secured.get("/.well-known/oauth-protected-resource/mcp")
- .expectStatus(200)
- .expectBodyContains("\"resource\":\"http://127.0.0.1:" + secured.port() + "/mcp\"")
- .expectBodyContains("\"authorization_servers\":[\"" + provider.issuer() + "\"]");
-
- assertTrue(!response.body().contains("scopes_supported"),
- "scopes_supported must be omitted when unset: " + response.body());
- }
-
- @Test
- void scopesSupported_published_inProtectedResourceMetadata() {
- securedWithScopes.get("/.well-known/oauth-protected-resource/mcp")
- .expectStatus(200)
- .expectBodyContains("\"scopes_supported\":[\"openid\",\"profile\",\"email\"]");
- }
-
- // ── Helpers ──────────────────────────────────────────────────────────────
-
- private static FlashApplication securedApp(String resourceIdentifier, String[] scopesSupported) {
- return app -> {
- app.install(new OidcExtension(OidcConfig.builder(
- provider.issuer(), "mcp-client", "secret", "/auth/callback").build()));
-
- McpConfig.Builder mcp = McpConfig.builder("secure-server")
- .toolsPackage(TOOLS_PACKAGE)
- .security(McpSecurity.REQUIRED);
- if (resourceIdentifier != null) mcp.resourceIdentifier(resourceIdentifier);
- if (scopesSupported != null) mcp.scopesSupported(scopesSupported);
- app.install(new McpExtension(mcp.build()));
- };
- }
-
- private static FlashResponse post(FlashTest server, String body, String bearerToken) {
- FlashRequest request = server.request().header("Accept", "application/json").json(body);
- if (bearerToken != null) request.header("Authorization", "Bearer " + bearerToken);
- return request.post("/mcp");
- }
-
- private static String initializeBody() {
- return "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}";
- }
-
- private static FakeOidcProvider newProvider() {
- try {
- return new FakeOidcProvider();
- } catch (Exception failure) {
- throw new IllegalStateException("Could not start the fake OIDC provider", failure);
- }
- }
-}
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpRegistryTest.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpRegistryTest.java
index a3faa29..349b84a 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpRegistryTest.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpRegistryTest.java
@@ -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) {
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpSecurityTest.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpSecurityTest.java
new file mode 100644
index 0000000..a107b1b
--- /dev/null
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/McpSecurityTest.java
@@ -0,0 +1,109 @@
+package dev.relism.flash.ext.mcp;
+
+import dev.relism.flash.ext.security.SecurityExtension;
+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.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("mk", id -> null).generate();
+ static final ApiKeyExtension 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())));
+
+ /** 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 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");
+ }
+
+ /** 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 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"));
+ }
+}
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java
deleted file mode 100644
index 71934d9..0000000
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java
+++ /dev/null
@@ -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.auth.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"));
- }
-}
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
index 9da014e..ad3ef90 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
@@ -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.auth.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
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
index aa4a3c0..8526506 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
@@ -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.auth.ScopesAllowed;
+import dev.relism.flash.ext.security.ScopesAllowed;
@Tool(name = "write_only", description = "Only callable with the write scope")
@ScopesAllowed("write")
diff --git a/flash-extensions/flash-ext-openapi/README.md b/flash-extensions/flash-ext-openapi/README.md
index 977c86c..4d0c868 100644
--- a/flash-extensions/flash-ext-openapi/README.md
+++ b/flash-extensions/flash-ext-openapi/README.md
@@ -121,15 +121,11 @@ Merge policy:
- contributor collisions use **last-wins**
- manual `@APIResponse` description always wins over contributors for the same status
-## OIDC interop
+## Security interop
-When `flash-ext-auth-oidc` is installed, OpenAPI integrates automatically:
-
-- security scheme under `components.securitySchemes`
-- per-operation `security`
-- auto responses (class-based handlers):
- - `401 Authentication required`
- - `403` role/scope required messages when applicable
+With `flash-ext-security-core` installed, every registered mechanism's scheme lands under
+`components.securitySchemes`, and every operation carrying a security annotation lists them as
+`security` alternatives with automatic `401` and — for roles or scopes — `403` responses.
Manual `@APIResponse` for the same status code always wins.
diff --git a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/flash/ext/routeviewer/model/RouteRecord.java b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/flash/ext/routeviewer/model/RouteRecord.java
index 8e6e357..fb2415b 100644
--- a/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/flash/ext/routeviewer/model/RouteRecord.java
+++ b/flash-extensions/flash-ext-routeviewer/src/main/java/dev/relism/flash/ext/routeviewer/model/RouteRecord.java
@@ -102,7 +102,7 @@ public record RouteRecord(
/**
* Strips the synthetic lambda suffix ({@code $$Lambda/0x...}) from class names
- * so that {@code OidcMiddleware$$Lambda/0x0000019c381f} becomes {@code OidcMiddleware}.
+ * so that {@code SecurityExtension$$Lambda/0x0000019c381f} becomes {@code SecurityExtension}.
*/
private static List buildMiddlewareNames(List> chain) {
List names = new ArrayList<>(chain.size());
diff --git a/flash-extensions/flash-ext-security-apikey/docs/README.md b/flash-extensions/flash-ext-security-apikey/docs/README.md
new file mode 100644
index 0000000..c4cd271
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/docs/README.md
@@ -0,0 +1,20 @@
+# flash-ext-security-apikey
+
+API keys for [`flash-ext-security-core`](../../flash-ext-security-core/docs/README.md), sent as
+`Authorization: Bearer _.`.
+
+```java
+ApiKeyExtension apiKeys = new ApiKeyExtension<>("gk", id -> rows.find(id)); // ApiKeyStore
+app.install(new SecurityExtension().roles(...)).install(apiKeys);
+
+GeneratedApiKey key = apiKeys.generate(); // show key.token() once
+rows.save(key.id(), key.secretHash(), grant); // never the token
+```
+
+The store returns `ApiKey(id, secretHash, grant, expiresAt, revokedAt)`; `G` is whatever the
+application authorizes on. An authenticated caller is an `ApiKeyPrincipal` carrying that grant —
+read it in a `RoleResolver` with `identity.principal(ApiKeyPrincipal.class)`.
+
+A bearer token without this prefix is left to other mechanisms; one with it that fails — unknown id,
+wrong secret, expired, revoked — is a `401 invalid_token`. Only a SHA-256 of the secret is stored: the
+secret is 192 random bits, so a slow KDF would protect nothing and cost every request.
diff --git a/flash-extensions/flash-ext-security-apikey/pom.xml b/flash-extensions/flash-ext-security-apikey/pom.xml
new file mode 100644
index 0000000..38a31f2
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/pom.xml
@@ -0,0 +1,30 @@
+
+
+ 4.0.0
+
+
+ dev.relism
+ flash-extensions
+ 2.1.0-SNAPSHOT
+
+
+ flash-ext-security-apikey
+
+
+
+ dev.relism
+ flash-ext-security-core
+
+
+ org.junit.jupiter
+ junit-jupiter
+
+
+ dev.relism
+ flash-testing
+ test
+
+
+
diff --git a/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKey.java b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKey.java
new file mode 100644
index 0000000..7094246
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKey.java
@@ -0,0 +1,17 @@
+package dev.relism.flash.ext.security.apikey;
+
+import java.time.Instant;
+
+/**
+ * An API key as the application stores it: never the secret, only its hash, and the grant it was
+ * issued with — whatever the application authorizes on.
+ *
+ * @param expiresAt {@code null} for a key that does not expire
+ * @param revokedAt {@code null} for a key that has not been revoked
+ */
+public record ApiKey(String id, String secretHash, G grant, Instant expiresAt, Instant revokedAt) {
+
+ boolean isActive() {
+ return revokedAt == null && (expiresAt == null || expiresAt.toEpochMilli() > System.currentTimeMillis());
+ }
+}
diff --git a/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyExtension.java b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyExtension.java
new file mode 100644
index 0000000..87cf053
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyExtension.java
@@ -0,0 +1,97 @@
+package dev.relism.flash.ext.security.apikey;
+
+import dev.relism.flash.ext.security.AuthenticationFailedException;
+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.extension.FlashContext;
+import dev.relism.flash.extension.FlashExtension;
+import dev.relism.flash.extension.FlashRegistrar;
+import dev.relism.flash.models.Request;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.security.SecureRandom;
+import java.util.Base64;
+
+/**
+ * API keys sent as {@code Authorization: Bearer _.}. The prefix makes a key
+ * recognisable at a glance and to secret scanners; the id is what the store is queried by; only a
+ * SHA-256 of the secret is ever stored — a KDF would add nothing to 192 random bits.
+ *
+ * {@code
+ * app.install(new SecurityExtension())
+ * .install(new ApiKeyExtension<>("gk", keys::find));
+ * }
+ */
+public final class ApiKeyExtension implements FlashExtension, AuthenticationMechanism {
+
+ private static final AuthenticationFailedException INVALID = new AuthenticationFailedException("Bearer error=\"invalid_token\"");
+ private static final SecureRandom RANDOM = new SecureRandom();
+ private static final Base64.Encoder BASE64URL = Base64.getUrlEncoder().withoutPadding();
+
+ private final String prefix;
+ private final String bearer;
+ private final ApiKeyStore store;
+
+ /** @param prefix identifies this application's keys; letters and digits only */
+ public ApiKeyExtension(String prefix, ApiKeyStore store) {
+ if (!prefix.matches("[A-Za-z0-9]+")) throw new IllegalArgumentException("API key prefix must be alphanumeric: " + prefix);
+ this.prefix = prefix;
+ this.bearer = "Bearer " + prefix + "_";
+ this.store = store;
+ }
+
+ /** A new key: 72 bits of id, 192 bits of secret. */
+ public GeneratedApiKey generate() {
+ String id = random(9);
+ String secret = random(24);
+ return new GeneratedApiKey(id, prefix + "_" + id + "." + secret, hash(secret));
+ }
+
+ @Override
+ public Principal authenticate(Request req) {
+ String header = req.header("Authorization");
+ if (header == null || !header.startsWith(bearer)) return null;
+ int dot = header.indexOf('.', bearer.length());
+ if (dot < 0) throw INVALID;
+ ApiKey key = store.find(header.substring(bearer.length(), dot));
+ if (key == null || !matches(header.substring(dot + 1), key.secretHash()) || !key.isActive()) throw INVALID;
+ return new ApiKeyPrincipal<>(key.id(), key.grant());
+ }
+
+ @Override
+ public SecurityScheme scheme() {
+ return SecurityScheme.bearer("apiKey", prefix + "_.");
+ }
+
+ @Override
+ public void configure(FlashRegistrar app, FlashContext ctx) {
+ ctx.provide(ApiKeyExtension.class, this);
+ ctx.onReady(() -> ctx.require(SecurityExtension.class).mechanism(this));
+ }
+
+ private static boolean matches(String secret, String secretHash) {
+ return MessageDigest.isEqual(digest(secret), Base64.getUrlDecoder().decode(secretHash));
+ }
+
+ private static String hash(String secret) {
+ return BASE64URL.encodeToString(digest(secret));
+ }
+
+ private static byte[] digest(String secret) {
+ try {
+ return MessageDigest.getInstance("SHA-256").digest(secret.getBytes(StandardCharsets.US_ASCII));
+ } catch (NoSuchAlgorithmException impossible) {
+ throw new IllegalStateException(impossible);
+ }
+ }
+
+ private static String random(int bytes) {
+ byte[] value = new byte[bytes];
+ RANDOM.nextBytes(value);
+ return BASE64URL.encodeToString(value);
+ }
+}
diff --git a/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyPrincipal.java b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyPrincipal.java
new file mode 100644
index 0000000..580a66c
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyPrincipal.java
@@ -0,0 +1,6 @@
+package dev.relism.flash.ext.security.apikey;
+
+import dev.relism.flash.ext.security.Principal;
+
+/** A caller authenticated by an API key, carrying the grant the key was issued with. */
+public record ApiKeyPrincipal(String name, G grant) implements Principal {}
diff --git a/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyStore.java b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyStore.java
new file mode 100644
index 0000000..a047890
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/ApiKeyStore.java
@@ -0,0 +1,9 @@
+package dev.relism.flash.ext.security.apikey;
+
+/** Where the application keeps its API keys. */
+@FunctionalInterface
+public interface ApiKeyStore {
+
+ /** The key with this id, or {@code null}. */
+ ApiKey find(String id);
+}
diff --git a/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/GeneratedApiKey.java b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/GeneratedApiKey.java
new file mode 100644
index 0000000..401046d
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/main/java/dev/relism/flash/ext/security/apikey/GeneratedApiKey.java
@@ -0,0 +1,7 @@
+package dev.relism.flash.ext.security.apikey;
+
+/**
+ * A freshly generated key. {@code token} goes to the caller exactly once; the application stores
+ * {@code id} and {@code secretHash}, never the token.
+ */
+public record GeneratedApiKey(String id, String token, String secretHash) {}
diff --git a/flash-extensions/flash-ext-security-apikey/src/test/java/dev/relism/flash/ext/security/apikey/ApiKeyExtensionTest.java b/flash-extensions/flash-ext-security-apikey/src/test/java/dev/relism/flash/ext/security/apikey/ApiKeyExtensionTest.java
new file mode 100644
index 0000000..c584bb4
--- /dev/null
+++ b/flash-extensions/flash-ext-security-apikey/src/test/java/dev/relism/flash/ext/security/apikey/ApiKeyExtensionTest.java
@@ -0,0 +1,57 @@
+package dev.relism.flash.ext.security.apikey;
+
+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.testing.FlashTest;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+class ApiKeyExtensionTest {
+
+ static final Map> KEYS = new ConcurrentHashMap<>();
+ static final SecurityExtension security = new SecurityExtension();
+ static final ApiKeyExtension apiKeys = new ApiKeyExtension<>("fk", KEYS::get);
+
+ @RegisterExtension
+ static final FlashTest app = FlashTest.of(flash -> flash
+ .install(security)
+ .install(apiKeys)
+ .get("/grant", (req, res) -> SecurityIdentity.current().principal(ApiKeyPrincipal.class).grant(),
+ security.enforce(SecurityPolicy.AUTHENTICATED)));
+
+ static String issue(String grant, Instant expiresAt, Instant revokedAt) {
+ GeneratedApiKey key = apiKeys.generate();
+ KEYS.put(key.id(), new ApiKey<>(key.id(), key.secretHash(), grant, expiresAt, revokedAt));
+ return "Bearer " + key.token();
+ }
+
+ @Test
+ void anIssuedKeyAuthenticatesWithItsGrant() {
+ app.request().header("Authorization", issue("project-42", null, null)).get("/grant").expectStatus(200).expectBody("project-42");
+ }
+
+ @Test
+ void aWrongSecretAnExpiredKeyAndARevokedKeyAreRejectedAsInvalid() {
+ String valid = issue("x", null, null);
+ for (String token : new String[]{
+ valid.substring(0, valid.length() - 1) + (valid.endsWith("A") ? "B" : "A"),
+ issue("x", Instant.now().minusSeconds(1), null),
+ issue("x", null, Instant.now()),
+ "Bearer fk_no-secret-here"}) {
+ app.request().header("Authorization", token).get("/grant")
+ .expectStatus(401).expectHeader("WWW-Authenticate", "Bearer error=\"invalid_token\"");
+ }
+ }
+
+ /** Another application's bearer token is not a key of ours: it is left to other mechanisms, not rejected. */
+ @Test
+ void aForeignBearerTokenIsNotThisMechanisms() {
+ app.request().header("Authorization", "Bearer eyJhbGciOi.payload.signature").get("/grant")
+ .expectStatus(401).expectHeader("WWW-Authenticate", "Bearer realm=\"apiKey\"");
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/docs/README.md b/flash-extensions/flash-ext-security-core/docs/README.md
new file mode 100644
index 0000000..c5390ca
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/docs/README.md
@@ -0,0 +1,88 @@
+# flash-ext-security-core
+
+Authentication and authorization for Flash, independent of any credential. Mechanisms —
+[`-oidc`](../../flash-ext-security-oidc/docs/README.md), [`-apikey`](../../flash-ext-security-apikey/docs/README.md),
+[`-form`](../../flash-ext-security-form/docs/README.md), or your own — register into one chain;
+this module owns everything downstream of "who is the caller".
+
+```java
+app.install(new SecurityExtension()
+ .users(principal -> users.findOrProvision(principal)) // optional: principal → your user
+ .roles((identity, role, on) -> members.has(identity.user(User.class), role, on.get("project"))))
+ .install(new OidcExtension(OidcProvider.of("sso", issuer, clientId, secret)));
+```
+
+## The model
+
+| Type | Role |
+|---|---|
+| `AuthenticationMechanism` | reads one kind of credential: returns a `Principal`, `null` (not mine), or throws `AuthenticationFailedException` (mine, invalid) |
+| `Principal` | who the mechanism proved the caller to be — typed per mechanism (`OidcPrincipal`, `ApiKeyPrincipal`, …) |
+| `SecurityIdentity` | the current caller: `principal(OidcPrincipal.class)`, `user(User.class)`, `hasRole`, `hasScope` |
+| `UserResolver` | principal → application user, resolved lazily, once per request |
+| `RoleResolver` | whether a caller holds a role, optionally on a resource |
+| `AuthenticationEntryPoint` | the answer to a request that needs a caller and carries no credential |
+
+Mechanisms never write the response. That is what keeps the one mistake that matters impossible to
+make: a credential that was presented and rejected is always a 401, never a redirect into a sign-in
+page an API client cannot parse.
+
+## Annotations
+
+On a handler or an MCP tool class:
+
+| | |
+|---|---|
+| `@Authenticated` | any authenticated caller |
+| `@PermitAll` | anyone; a caller who authenticates is still identified, one who fails is anonymous |
+| `@RolesAllowed(value, on)` | any of the roles; `on` names the path/query parameters (tool arguments on MCP) identifying the resource |
+| `@ScopesAllowed(value)` | every one of the credential's scopes |
+
+`@RolesAllowed(value = "MANAGER", on = "project")` on `/projects/{project}/keys` asks the
+`RoleResolver` whether the caller is a manager *of that project*. A handler declaring roles with no
+`RoleResolver` configured fails the boot. Policies compile once; checking one allocates nothing.
+
+## The chain
+
+Mechanisms are tried in registration order, then the session cookie. The first to return a
+principal wins. When none does:
+
+- a browser (`Accept: text/html`) is redirected to the only login method, or to `loginPage` when there are several;
+- anything else gets `401` with every mechanism's challenge in `WWW-Authenticate`.
+
+`entryPoint(...)` replaces that, e.g. to pick an identity provider from the user's email domain.
+
+## Sessions
+
+`signIn(req, res, principal[, expiresAt])` stores the principal under a `flash_session` cookie;
+`POST /auth/logout` ends it and follows `Principal.logoutUrl()`. An expired session is handed to the
+`SessionRefresher` registered for its principal type, or ended. `InMemorySessionStore` is the
+default; `sessions(...)` swaps it for one that survives a restart or spans instances.
+
+`GET /auth/methods` lists every registered `LoginMethod` for a client to render.
+
+## OpenAPI
+
+With `flash-ext-openapi` present, every registered mechanism's `SecurityScheme` is published, and
+every protected operation lists them as alternatives, with its 401 and — for roles or scopes — its
+403 and what it requires. Nothing to write per mechanism.
+
+## Writing a mechanism
+
+```java
+security.mechanism(new AuthenticationMechanism() {
+ public Principal authenticate(Request req) {
+ String key = req.header("X-Key");
+ if (key == null) return null; // not mine
+ Principal p = keys.get(key);
+ if (p == null) throw new AuthenticationFailedException(null); // mine, and invalid
+ return p;
+ }
+ public SecurityScheme scheme() { return SecurityScheme.bearer("key", "opaque"); }
+});
+```
+
+## Testing
+
+[`flash-ext-security-test`](../../flash-ext-security-test/docs/README.md) authenticates requests as
+any principal without an identity provider.
diff --git a/flash-extensions/flash-ext-auth-oidc/pom.xml b/flash-extensions/flash-ext-security-core/pom.xml
similarity index 66%
rename from flash-extensions/flash-ext-auth-oidc/pom.xml
rename to flash-extensions/flash-ext-security-core/pom.xml
index 43aa29a..05c32db 100644
--- a/flash-extensions/flash-ext-auth-oidc/pom.xml
+++ b/flash-extensions/flash-ext-security-core/pom.xml
@@ -10,13 +10,9 @@
2.1.0-SNAPSHOT
- flash-ext-auth-oidc
+ flash-ext-security-core
-
- dev.relism
- flash-ext-auth-core
-
dev.relism
flash
@@ -26,22 +22,14 @@
flash-ext-openapi
true
-
- com.nimbusds
- nimbus-jose-jwt
-
-
- net.minidev
- json-smart
-
-
- org.projectlombok
- lombok
-
org.junit.jupiter
junit-jupiter
+
+ dev.relism
+ flash-testing
+ test
+
-
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Authenticated.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Authenticated.java
new file mode 100644
index 0000000..587f935
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Authenticated.java
@@ -0,0 +1,12 @@
+package dev.relism.flash.ext.security;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/** The handler or MCP tool requires an authenticated caller. */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@java.lang.annotation.Target(ElementType.TYPE)
+public @interface Authenticated {}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationEntryPoint.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationEntryPoint.java
new file mode 100644
index 0000000..ea56cb4
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationEntryPoint.java
@@ -0,0 +1,11 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.Response;
+
+/** Answers a request that needs a caller and carries no credential at all. */
+@FunctionalInterface
+public interface AuthenticationEntryPoint {
+
+ Object commence(Request req, Response res) throws Exception;
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationFailedException.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationFailedException.java
new file mode 100644
index 0000000..ae74a1f
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationFailedException.java
@@ -0,0 +1,24 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.exceptions.HttpException;
+
+/** A credential was presented and rejected. Stackless: turning away forged tokens stays cheap. */
+public final class AuthenticationFailedException extends HttpException {
+
+ private final String challenge;
+
+ /** @param challenge the {@code WWW-Authenticate} value to answer with, or {@code null} */
+ public AuthenticationFailedException(String challenge) {
+ super(401, "Unauthorized");
+ this.challenge = challenge;
+ }
+
+ public String challenge() {
+ return challenge;
+ }
+
+ @Override
+ public synchronized Throwable fillInStackTrace() {
+ return this;
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationMechanism.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationMechanism.java
new file mode 100644
index 0000000..263fe37
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/AuthenticationMechanism.java
@@ -0,0 +1,21 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.models.Request;
+
+/**
+ * Reads one kind of credential off a request. A mechanism never writes the response: an anonymous
+ * request is answered by the {@link AuthenticationEntryPoint}, a rejected one by the 401 its
+ * {@link AuthenticationFailedException} carries.
+ */
+public interface AuthenticationMechanism {
+
+ /**
+ * The caller, or {@code null} when the request carries no credential of this kind.
+ *
+ * @throws AuthenticationFailedException the request carries one, and it is invalid
+ */
+ Principal authenticate(Request req);
+
+ /** How OpenAPI documents the credential and a 401 challenges for it; {@code null} for neither. */
+ default SecurityScheme scheme() { return null; }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/InMemorySessionStore.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/InMemorySessionStore.java
new file mode 100644
index 0000000..459ffeb
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/InMemorySessionStore.java
@@ -0,0 +1,26 @@
+package dev.relism.flash.ext.security;
+
+import java.util.concurrent.ConcurrentHashMap;
+
+/** One instance's sessions, lost on restart. Expired ones are swept whenever a session is saved. */
+public final class InMemorySessionStore implements SessionStore {
+
+ private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
+
+ @Override
+ public void save(Session session) {
+ long now = System.currentTimeMillis();
+ sessions.values().removeIf(s -> s.expiresAt().toEpochMilli() <= now);
+ sessions.put(session.id(), session);
+ }
+
+ @Override
+ public Session find(String id) {
+ return sessions.get(id);
+ }
+
+ @Override
+ public void delete(String id) {
+ sessions.remove(id);
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/LoginMethod.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/LoginMethod.java
new file mode 100644
index 0000000..84721a8
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/LoginMethod.java
@@ -0,0 +1,12 @@
+package dev.relism.flash.ext.security;
+
+/** A way to sign in, listed at {@code GET /auth/methods} for a client to offer. */
+public record LoginMethod(String id, String name, String url, Kind kind) {
+
+ public enum Kind {
+ /** A browser navigates to {@code url} and comes back signed in — OpenID Connect, for instance. */
+ REDIRECT,
+ /** A client posts {@code username} and {@code password} to {@code url}. */
+ FORM
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/PermitAll.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/PermitAll.java
new file mode 100644
index 0000000..dc4efaf
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/PermitAll.java
@@ -0,0 +1,15 @@
+package dev.relism.flash.ext.security;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Anyone may call the handler. A caller who authenticates is still identified; one whose credential
+ * is rejected is treated as anonymous rather than refused.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@java.lang.annotation.Target(ElementType.TYPE)
+public @interface PermitAll {}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Principal.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Principal.java
new file mode 100644
index 0000000..e1972b2
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Principal.java
@@ -0,0 +1,20 @@
+package dev.relism.flash.ext.security;
+
+/**
+ * Who an {@link AuthenticationMechanism} proved the caller to be. Each mechanism has its own type;
+ * {@link SecurityIdentity#principal(Class)} reads it back.
+ */
+public interface Principal {
+
+ /** Unique within the mechanism that produced it. */
+ String name();
+
+ /** Whether the credential grants {@code scope}. One that carries no scopes grants every scope. */
+ default boolean hasScope(String scope) { return true; }
+
+ /** Whether the credential was issued for {@code audience} (RFC 8707). One bound to no audience was. */
+ default boolean hasAudience(String audience) { return true; }
+
+ /** Where signing out sends the browser; {@code null} for the application root. */
+ default String logoutUrl() { return null; }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RoleResolver.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RoleResolver.java
new file mode 100644
index 0000000..05abb0b
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RoleResolver.java
@@ -0,0 +1,11 @@
+package dev.relism.flash.ext.security;
+
+/**
+ * Whether a caller holds a role — read from a token, a database, anywhere. {@code on} identifies
+ * the resource for roles held per resource rather than globally.
+ */
+@FunctionalInterface
+public interface RoleResolver {
+
+ boolean hasRole(SecurityIdentity identity, String role, Target on);
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RolesAllowed.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RolesAllowed.java
new file mode 100644
index 0000000..65a60e9
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/RolesAllowed.java
@@ -0,0 +1,24 @@
+package dev.relism.flash.ext.security;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * The caller must hold at least one of these roles, as decided by the configured
+ * {@link RoleResolver}. Implies {@link Authenticated}.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@java.lang.annotation.Target(ElementType.TYPE)
+public @interface RolesAllowed {
+
+ String[] value();
+
+ /**
+ * Names of the path or query parameters (tool arguments on MCP) that identify the resource the
+ * role is held on — {@code on = "project"} checks the role on {@code /projects/{project}}.
+ */
+ String[] on() default {};
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/ScopesAllowed.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/ScopesAllowed.java
new file mode 100644
index 0000000..5bb26ba
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/ScopesAllowed.java
@@ -0,0 +1,15 @@
+package dev.relism.flash.ext.security;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/** The caller's credential must grant every one of these scopes. Implies {@link Authenticated}. */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@java.lang.annotation.Target(ElementType.TYPE)
+public @interface ScopesAllowed {
+
+ String[] value();
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityExtension.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityExtension.java
new file mode 100644
index 0000000..6713fef
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityExtension.java
@@ -0,0 +1,321 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.exceptions.HttpException;
+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.http.ContentType;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.Response;
+import dev.relism.flash.routing.Middleware;
+import dev.relism.flash.routing.MiddlewareKey;
+import dev.relism.flash.routing.MiddlewareNode;
+import dev.relism.fpr.core.ByteView;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.security.SecureRandom;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Arrays;
+import java.util.Base64;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Flash security: the authentication chain, the policies security annotations declare, sessions,
+ * and the {@code /auth/logout} and {@code /auth/methods} routes. Mechanisms register through
+ * {@link #mechanism}, directly or from their own extensions, and are tried in registration order
+ * before the session cookie.
+ *
+ * {@code
+ * app.install(new SecurityExtension().users(users).roles(roles))
+ * .install(new OidcExtension(OidcProvider.of("sso", issuer, clientId, secret)));
+ * }
+ */
+public class SecurityExtension implements FlashExtension {
+
+ /** The node security annotations mount under, for middleware that must run before or after it. */
+ public static final MiddlewareKey POLICY = MiddlewareKey.of("flash.security.policy");
+
+ private static final String WWW_AUTHENTICATE = "WWW-Authenticate";
+ private static final String COOKIE = "flash_session";
+ private static final SecureRandom RANDOM = new SecureRandom();
+
+ private final Map, SessionRefresher> refreshers = new ConcurrentHashMap<>();
+ private volatile AuthenticationMechanism[] mechanisms = {};
+ private volatile SecurityScheme[] schemes = {};
+ private volatile LoginMethod[] loginMethods = {};
+ private volatile String challenges;
+ private volatile String methodsJson = "[]";
+
+ UserResolver users = principal -> principal;
+ RoleResolver roles;
+ private AuthenticationEntryPoint entryPoint = this::commence;
+ private SessionStore sessions = new InMemorySessionStore();
+ private Duration sessionTimeout = Duration.ofHours(12);
+ private String loginPage = "/login";
+
+ // -- Configuration --------------------------------------------------------
+
+ /** Resolves {@link SecurityIdentity#user} — default: the principal itself. */
+ public SecurityExtension users(UserResolver users) {
+ this.users = users;
+ return this;
+ }
+
+ /** Required by {@link RolesAllowed}; a handler that declares roles without one fails the boot. */
+ public SecurityExtension roles(RoleResolver roles) {
+ this.roles = roles;
+ return this;
+ }
+
+ /** Replaces the default: a browser is redirected to sign in, anything else gets 401 with every challenge. */
+ public SecurityExtension entryPoint(AuthenticationEntryPoint entryPoint) {
+ this.entryPoint = entryPoint;
+ return this;
+ }
+
+ public SecurityExtension sessions(SessionStore sessions) {
+ this.sessions = sessions;
+ return this;
+ }
+
+ public SecurityExtension sessionTimeout(Duration sessionTimeout) {
+ this.sessionTimeout = sessionTimeout;
+ return this;
+ }
+
+ /** Where a browser signs in, unless the only {@link LoginMethod} is a redirect it can follow directly. */
+ public SecurityExtension loginPage(String loginPage) {
+ this.loginPage = loginPage;
+ return this;
+ }
+
+ // -- Registration (boot time) ---------------------------------------------
+
+ public synchronized SecurityExtension mechanism(AuthenticationMechanism mechanism) {
+ mechanisms = append(mechanisms, mechanism);
+ return mechanism.scheme() == null ? this : scheme(mechanism.scheme());
+ }
+
+ /** Documents and challenges for a credential beyond the one {@link AuthenticationMechanism#scheme()} names. */
+ public synchronized SecurityExtension scheme(SecurityScheme scheme) {
+ schemes = append(schemes, scheme);
+ challenges = challenges == null ? scheme.challenge() : challenges + ", " + scheme.challenge();
+ return this;
+ }
+
+ public synchronized SecurityExtension loginMethod(LoginMethod method) {
+ loginMethods = append(loginMethods, method);
+ StringBuilder json = new StringBuilder("[");
+ for (LoginMethod m : loginMethods) {
+ if (json.length() > 1) json.append(',');
+ json.append("{\"id\":\"").append(m.id()).append("\",\"name\":\"").append(m.name())
+ .append("\",\"url\":\"").append(m.url()).append("\",\"kind\":\"").append(m.kind().name().toLowerCase()).append("\"}");
+ }
+ methodsJson = json.append(']').toString();
+ return this;
+ }
+
+ public SecurityExtension refresher(Class type, SessionRefresher refresher) {
+ refreshers.put(type, refresher);
+ return this;
+ }
+
+ /** The schemes of every registered mechanism, in registration order. */
+ public List schemes() {
+ return List.of(schemes);
+ }
+
+ // -- Runtime --------------------------------------------------------------
+
+ /**
+ * The caller, or {@code null} when no mechanism recognises a credential.
+ *
+ * @throws AuthenticationFailedException a mechanism recognised one and rejected it
+ */
+ public SecurityIdentity authenticate(Request req) {
+ for (AuthenticationMechanism mechanism : mechanisms) {
+ Principal principal = mechanism.authenticate(req);
+ if (principal != null) return new SecurityIdentity(principal, this, req);
+ }
+ Principal principal = sessionPrincipal(req);
+ return principal == null ? null : new SecurityIdentity(principal, this, req);
+ }
+
+ /**
+ * The policy {@code type}'s annotations declare, checked against this configuration — declaring
+ * roles without a {@link RoleResolver} fails here, at boot. {@code null} for no annotations.
+ */
+ public SecurityPolicy policy(Class type) {
+ SecurityPolicy policy = SecurityPolicy.of(type);
+ if (policy != null && policy.requiresRoles() && roles == null) {
+ throw new IllegalStateException(type.getName() + " declares @RolesAllowed, but no RoleResolver is configured — SecurityExtension.roles(...)");
+ }
+ return policy;
+ }
+
+ public Middleware enforce(SecurityPolicy policy) {
+ return enforce(policy, entryPoint);
+ }
+
+ /** {@code anonymous} answers a caller without credentials on this route instead of the configured entry point. */
+ public Middleware enforce(SecurityPolicy policy, AuthenticationEntryPoint anonymous) {
+ return next -> (req, res) -> {
+ SecurityIdentity identity;
+ try {
+ identity = authenticate(req);
+ } catch (AuthenticationFailedException rejected) {
+ if (policy.required) {
+ if (rejected.challenge() != null) res.header(WWW_AUTHENTICATE, rejected.challenge());
+ throw rejected;
+ }
+ identity = null;
+ }
+ if (identity == null) {
+ if (policy.required) return anonymous.commence(req, res);
+ } else if (!policy.permitsScopes(identity)) {
+ res.header(WWW_AUTHENTICATE, policy.scopeChallenge);
+ throw HttpException.forbidden();
+ } else if (!policy.permitsRoles(identity, policy.on.length == 0 ? Target.NONE : name -> {
+ String value = req.param(name);
+ return value != null ? value : req.query(name);
+ })) {
+ throw HttpException.forbidden();
+ }
+ SecurityIdentity.CURRENT.set(identity);
+ try {
+ return next.handle(req, res);
+ } finally {
+ SecurityIdentity.CURRENT.remove();
+ }
+ };
+ }
+
+ /** Starts a session for {@code principal} lasting the configured timeout. */
+ public void signIn(Request req, Response res, Principal principal) {
+ signIn(req, res, principal, Instant.now().plus(sessionTimeout));
+ }
+
+ public void signIn(Request req, Response res, Principal principal, Instant expiresAt) {
+ byte[] id = new byte[24];
+ RANDOM.nextBytes(id);
+ Session session = new Session(Base64.getUrlEncoder().withoutPadding().encodeToString(id), principal, expiresAt);
+ sessions.save(session);
+ res.header("Set-Cookie", COOKIE + "=" + session.id() + "; Path=/; HttpOnly; SameSite=Lax" + (req.origin().startsWith("https") ? "; Secure" : ""));
+ }
+
+ /** Ends the caller's session and returns where the browser goes next. */
+ public String signOut(Request req, Response res) {
+ String id = req.cookie(COOKIE);
+ Session session = id == null ? null : sessions.find(id);
+ if (session != null) sessions.delete(id);
+ res.header("Set-Cookie", COOKIE + "=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax");
+ String next = session == null ? null : session.principal().logoutUrl();
+ return next == null ? "/" : next;
+ }
+
+ // -- Extension ------------------------------------------------------------
+
+ @Override
+ public void configure(FlashRegistrar app, FlashContext ctx) {
+ ctx.provide(SecurityExtension.class, this);
+ ctx.addAnnotationProcessor(handler -> {
+ SecurityPolicy policy = policy(handler);
+ return policy == null ? List.of() : List.of(MiddlewareNode.of(POLICY, enforce(policy)));
+ });
+ app.post("/auth/logout", (req, res) -> {
+ res.status(303).header("Location", signOut(req, res));
+ return null;
+ });
+ app.get("/auth/methods", (req, res) -> {
+ res.type(ContentType.JSON);
+ return methodsJson;
+ });
+ ctx.onReady(() -> {
+ try {
+ OpenApi.register(ctx, this);
+ } catch (NoClassDefFoundError absent) {
+ // flash-ext-openapi is not on the classpath
+ }
+ });
+ }
+
+ private Object commence(Request req, Response res) {
+ LoginMethod[] methods = loginMethods;
+ String accept = req.header("Accept");
+ if (methods.length > 0 && accept != null && accept.contains("text/html")) {
+ String login = methods.length == 1 && methods[0].kind() == LoginMethod.Kind.REDIRECT ? methods[0].url() : loginPage;
+ ByteView query = req.getRequestLine().getQuery();
+ byte[] raw = new byte[query == null ? 0 : query.length()];
+ for (int i = 0; i < raw.length; i++) raw[i] = query.byteAt(i);
+ String target = raw.length == 0 ? req.path() : req.path() + "?" + new String(raw, StandardCharsets.UTF_8);
+ res.redirect(login + "?redirect=" + URLEncoder.encode(target, StandardCharsets.UTF_8));
+ return null;
+ }
+ if (challenges != null) res.header(WWW_AUTHENTICATE, challenges);
+ throw HttpException.unauthorized();
+ }
+
+ private Principal sessionPrincipal(Request req) {
+ String id = req.cookie(COOKIE);
+ Session session = id == null ? null : sessions.find(id);
+ if (session == null) return null;
+ if (session.expiresAt().toEpochMilli() > System.currentTimeMillis()) return session.principal();
+ SessionRefresher refresher = refreshers.get(session.principal().getClass());
+ Session renewed = refresher == null ? null : refresher.refresh(session);
+ if (renewed == null) {
+ sessions.delete(id);
+ return null;
+ }
+ sessions.save(renewed);
+ return renewed.principal();
+ }
+
+ private static T[] append(T[] array, T element) {
+ T[] grown = Arrays.copyOf(array, array.length + 1);
+ grown[array.length] = element;
+ return grown;
+ }
+
+ /** Isolated so this extension loads without flash-ext-openapi on the classpath. */
+ private static final class OpenApi {
+
+ static void register(FlashContext ctx, SecurityExtension security) {
+ ctx.find(OpenApiContributorRegistry.class).ifPresent(registry -> registry.add(new OpenApiContributor() {
+ @Override
+ public Map componentContributions() {
+ Map definitions = new LinkedHashMap<>();
+ for (SecurityScheme scheme : security.schemes) definitions.put(scheme.name(), scheme.definition());
+ return definitions.isEmpty() ? Map.of() : Map.of("securitySchemes", definitions);
+ }
+
+ @Override
+ public OpenApiOperationContribution operationFor(Class handler) {
+ SecurityPolicy policy = SecurityPolicy.of(handler);
+ if (policy == null || !policy.required) return OpenApiOperationContribution.empty();
+ OpenApiOperationContribution.Builder operation = OpenApiOperationContribution.builder();
+ for (SecurityScheme scheme : security.schemes) {
+ operation.security(scheme.name(), scheme.issuer() != null ? List.of(policy.scopes) : List.of());
+ }
+ operation.response(401, OpenApiResponseContribution.of("Authentication required"));
+ String roles = policy.roles.length == 0 ? null : "Requires role " + String.join(" or ", policy.roles)
+ + (policy.on.length == 0 ? "" : " on " + String.join(", ", policy.on));
+ String scopes = policy.scopes.length == 0 ? null : "Requires scopes " + String.join(" ", policy.scopes);
+ if (roles != null || scopes != null) {
+ operation.response(403, OpenApiResponseContribution.of(
+ roles == null ? scopes : scopes == null ? roles : roles + "; " + scopes));
+ }
+ return operation.build();
+ }
+ }));
+ }
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityIdentity.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityIdentity.java
new file mode 100644
index 0000000..121d91c
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityIdentity.java
@@ -0,0 +1,65 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.models.Request;
+
+/**
+ * The authenticated caller of the current request: the {@link Principal} a mechanism produced, the
+ * application user it resolves to, and the roles and scopes it holds.
+ */
+public final class SecurityIdentity {
+
+ static final ThreadLocal CURRENT = new ThreadLocal<>();
+
+ private final Principal principal;
+ private final SecurityExtension security;
+ private final Request request;
+ private Object user;
+
+ SecurityIdentity(Principal principal, SecurityExtension security, Request request) {
+ this.principal = principal;
+ this.security = security;
+ this.request = request;
+ }
+
+ /** The caller of the request this thread is handling; {@code null} when it is anonymous. */
+ public static SecurityIdentity current() {
+ return CURRENT.get();
+ }
+
+ public Principal principal() {
+ return principal;
+ }
+
+ /**
+ * The request being authorized. {@link Target} carries what {@link RolesAllowed#on()} names, read
+ * from path and query parameters; a {@link RoleResolver} whose scope is somewhere else — a tenant
+ * header, say — reads it from here.
+ */
+ public Request request() {
+ return request;
+ }
+
+ /** The principal as {@code type}, or {@code null} when another mechanism authenticated the caller. */
+ public P principal(Class
type) {
+ return type.isInstance(principal) ? type.cast(principal) : null;
+ }
+
+ /** The application user, resolved once per request by the configured {@link UserResolver}. */
+ public U user(Class type) {
+ if (user == null) user = security.users.resolve(principal);
+ return type.cast(user);
+ }
+
+ public boolean hasScope(String scope) {
+ return principal.hasScope(scope);
+ }
+
+ public boolean hasRole(String role) {
+ return hasRole(role, Target.NONE);
+ }
+
+ public boolean hasRole(String role, Target on) {
+ if (security.roles == null) throw new IllegalStateException("No RoleResolver configured — SecurityExtension.roles(...)");
+ return security.roles.hasRole(this, role, on);
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityPolicy.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityPolicy.java
new file mode 100644
index 0000000..891bf43
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityPolicy.java
@@ -0,0 +1,63 @@
+package dev.relism.flash.ext.security;
+
+/** What a handler's or tool's security annotations require, compiled once at boot. Checks allocate nothing. */
+public final class SecurityPolicy {
+
+ /** Any authenticated caller. */
+ public static final SecurityPolicy AUTHENTICATED = new SecurityPolicy(true, new String[0], new String[0], new String[0]);
+
+ final boolean required;
+ final String[] roles;
+ final String[] on;
+ final String[] scopes;
+ final String scopeChallenge;
+
+ private SecurityPolicy(boolean required, String[] roles, String[] on, String[] scopes) {
+ this.required = required;
+ this.roles = roles;
+ this.on = on;
+ this.scopes = scopes;
+ this.scopeChallenge = "Bearer error=\"insufficient_scope\", scope=\"" + String.join(" ", scopes) + "\"";
+ }
+
+ /** The policy {@code type} declares, or {@code null} when it carries no security annotation. */
+ public static SecurityPolicy of(Class type) {
+ boolean permitAll = type.isAnnotationPresent(PermitAll.class);
+ boolean authenticated = type.isAnnotationPresent(Authenticated.class);
+ RolesAllowed roles = type.getAnnotation(RolesAllowed.class);
+ ScopesAllowed scopes = type.getAnnotation(ScopesAllowed.class);
+ if (!permitAll && !authenticated && roles == null && scopes == null) return null;
+ if (permitAll && (authenticated || roles != null || scopes != null)) {
+ throw new IllegalStateException("@PermitAll contradicts the other security annotations on " + type.getName());
+ }
+ return new SecurityPolicy(!permitAll,
+ roles == null ? AUTHENTICATED.roles : values(roles.value(), "@RolesAllowed", type),
+ roles == null ? AUTHENTICATED.on : roles.on(),
+ scopes == null ? AUTHENTICATED.scopes : values(scopes.value(), "@ScopesAllowed", type));
+ }
+
+ /** False only for {@link PermitAll}. */
+ public boolean required() {
+ return required;
+ }
+
+ public boolean requiresRoles() {
+ return roles.length > 0;
+ }
+
+ public boolean permitsScopes(SecurityIdentity identity) {
+ for (String scope : scopes) if (!identity.hasScope(scope)) return false;
+ return true;
+ }
+
+ public boolean permitsRoles(SecurityIdentity identity, Target target) {
+ if (roles.length == 0) return true;
+ for (String role : roles) if (identity.hasRole(role, target)) return true;
+ return false;
+ }
+
+ private static String[] values(String[] values, String annotation, Class type) {
+ if (values.length == 0) throw new IllegalStateException(annotation + " on " + type.getName() + " names nothing");
+ return values;
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityScheme.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityScheme.java
new file mode 100644
index 0000000..36c48b0
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SecurityScheme.java
@@ -0,0 +1,24 @@
+package dev.relism.flash.ext.security;
+
+import java.util.Map;
+
+/**
+ * A credential as OpenAPI names and defines it, the {@code WWW-Authenticate} challenge an anonymous
+ * API call receives for it, and — for OAuth — the issuer that grants it.
+ *
+ * @param definition the OpenAPI Security Scheme Object, verbatim
+ * @param issuer the authorization server's issuer identifier, {@code null} for anything else
+ */
+public record SecurityScheme(String name, Map definition, String challenge, String issuer) {
+
+ public static SecurityScheme bearer(String name, String bearerFormat) {
+ return new SecurityScheme(name, Map.of("type", "http", "scheme", "bearer", "bearerFormat", bearerFormat),
+ "Bearer realm=\"" + name + "\"", null);
+ }
+
+ public static SecurityScheme openIdConnect(String name, String issuer) {
+ return new SecurityScheme(name,
+ Map.of("type", "openIdConnect", "openIdConnectUrl", issuer + (issuer.endsWith("/") ? "" : "/") + ".well-known/openid-configuration"),
+ "Bearer realm=\"" + name + "\"", issuer);
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Session.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Session.java
new file mode 100644
index 0000000..478fe75
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Session.java
@@ -0,0 +1,6 @@
+package dev.relism.flash.ext.security;
+
+import java.time.Instant;
+
+/** A signed-in principal, kept server-side under the id its cookie carries. */
+public record Session(String id, Principal principal, Instant expiresAt) {}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionRefresher.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionRefresher.java
new file mode 100644
index 0000000..d4a08cd
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionRefresher.java
@@ -0,0 +1,8 @@
+package dev.relism.flash.ext.security;
+
+/** Renews an expired session — with a refresh token, typically. {@code null} ends it instead. */
+@FunctionalInterface
+public interface SessionRefresher {
+
+ Session refresh(Session expired);
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionStore.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionStore.java
new file mode 100644
index 0000000..3f21ad3
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/SessionStore.java
@@ -0,0 +1,12 @@
+package dev.relism.flash.ext.security;
+
+/** Where sessions live. {@link InMemorySessionStore} unless one that survives restarts is configured. */
+public interface SessionStore {
+
+ void save(Session session);
+
+ /** The session, or {@code null}. */
+ Session find(String id);
+
+ void delete(String id);
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Target.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Target.java
new file mode 100644
index 0000000..868c532
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/Target.java
@@ -0,0 +1,15 @@
+package dev.relism.flash.ext.security;
+
+/**
+ * The resource a role is checked on: the values {@link RolesAllowed#on()} names, read from path
+ * and query parameters on HTTP and from tool arguments on MCP.
+ */
+@FunctionalInterface
+public interface Target {
+
+ /** A role checked on nothing in particular. */
+ Target NONE = name -> null;
+
+ /** The value called {@code name}, or {@code null} when the call does not carry one. */
+ String get(String name);
+}
diff --git a/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/UserResolver.java b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/UserResolver.java
new file mode 100644
index 0000000..085981e
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/main/java/dev/relism/flash/ext/security/UserResolver.java
@@ -0,0 +1,8 @@
+package dev.relism.flash.ext.security;
+
+/** The application user a verified principal belongs to — typically found, or provisioned, by issuer and subject. */
+@FunctionalInterface
+public interface UserResolver {
+
+ U resolve(Principal principal);
+}
diff --git a/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityExtensionTest.java b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityExtensionTest.java
new file mode 100644
index 0000000..c84ffd5
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityExtensionTest.java
@@ -0,0 +1,132 @@
+package dev.relism.flash.ext.security;
+
+import dev.relism.flash.ext.openapi.OpenApiExtension;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.testing.FlashTest;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import java.time.Instant;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class SecurityExtensionTest {
+
+ /** {@code Authorization: Key [ ...]}; {@code Key !} is a presented, invalid credential. */
+ record KeyPrincipal(String name, Set scopes) implements Principal {
+ @Override public boolean hasScope(String scope) { return scopes.contains(scope); }
+ }
+
+ static final AuthenticationMechanism KEY = new AuthenticationMechanism() {
+ @Override
+ public Principal authenticate(Request req) {
+ String header = req.header("Authorization");
+ if (header == null || !header.startsWith("Key ")) return null;
+ String[] parts = header.substring(4).split(" ");
+ if (parts[0].equals("!")) throw new AuthenticationFailedException("Key error=\"invalid_token\"");
+ return new KeyPrincipal(parts[0], Set.of(java.util.Arrays.copyOfRange(parts, 1, parts.length)));
+ }
+
+ @Override
+ public SecurityScheme scheme() {
+ return SecurityScheme.bearer("key", "opaque");
+ }
+ };
+
+ static final SecurityExtension security = new SecurityExtension()
+ .roles((identity, role, on) -> identity.principal().name().equals(role + "@" + on.get("project")))
+ .mechanism(KEY)
+ .loginMethod(new LoginMethod("key", "Key", "/auth/key/login", LoginMethod.Kind.REDIRECT))
+ .refresher(KeyPrincipal.class, expired -> new Session(expired.id(), expired.principal(), Instant.now().plusSeconds(60)));
+
+ @RegisterExtension
+ static final FlashTest app = FlashTest.of(flash -> flash
+ .install(security)
+ .install(new OpenApiExtension("/openapi", "test", "1"))
+ .get("/me", (req, res) -> SecurityIdentity.current().principal().name(), security.enforce(SecurityPolicy.AUTHENTICATED))
+ .post("/login", (req, res) -> {
+ security.signIn(req, res, new KeyPrincipal("carol", Set.of()), Instant.now().minusSeconds(1));
+ return "signed in";
+ })
+ .scan("dev.relism.flash.ext.security.fixtures"));
+
+ @Test
+ void aValidCredentialIdentifiesTheCaller() {
+ app.request().header("Authorization", "Key alice").get("/me").expectStatus(200).expectBody("alice");
+ }
+
+ /** Rejected is never anonymous: a browser presenting a bad credential must not be sent to sign in. */
+ @Test
+ void aRejectedCredentialIs401WithItsOwnChallengeEvenForABrowser() {
+ app.request().header("Authorization", "Key !").header("Accept", "text/html").get("/me")
+ .expectStatus(401)
+ .expectHeader("WWW-Authenticate", "Key error=\"invalid_token\"");
+ }
+
+ @Test
+ void anApiCallWithoutCredentialsIsChallengedForEveryMechanism() {
+ app.get("/me").expectStatus(401).expectHeader("WWW-Authenticate", "Bearer realm=\"key\"");
+ }
+
+ @Test
+ void aBrowserWithoutCredentialsGoesStraightToTheOnlyLoginMethod() {
+ app.request().header("Accept", "text/html").get("/me?tab=keys")
+ .expectStatus(302)
+ .expectHeader("Location", "/auth/key/login?redirect=%2Fme%3Ftab%3Dkeys");
+ }
+
+ @Test
+ void permitAllIdentifiesWhoeverAuthenticatesAndToleratesEveryoneElse() {
+ app.request().header("Authorization", "Key bob").get("/open").expectBody("bob");
+ app.request().header("Authorization", "Key !").get("/open").expectStatus(200).expectBody("anonymous");
+ app.get("/open").expectBody("anonymous");
+ }
+
+ @Test
+ void rolesAreCheckedOnTheResourceThePathNames() {
+ app.request().header("Authorization", "Key MANAGER@42").get("/projects/42").expectStatus(200);
+ app.request().header("Authorization", "Key MANAGER@42").get("/projects/7").expectStatus(403);
+ }
+
+ @Test
+ void aMissingScopeIs403WithAnInsufficientScopeChallenge() {
+ app.request().header("Authorization", "Key dave write").post("/write").expectStatus(200);
+ app.request().header("Authorization", "Key dave").post("/write")
+ .expectStatus(403)
+ .expectHeader("WWW-Authenticate", "Bearer error=\"insufficient_scope\", scope=\"write\"");
+ }
+
+ /** The session is signed in already expired, so reaching /me proves the refresher ran. */
+ @Test
+ void aSessionIsRefreshedWhenExpiredAndEndedBySigningOut() {
+ String cookie = app.request().post("/login").expectStatus(200).header("Set-Cookie");
+ String session = cookie.substring(0, cookie.indexOf(';'));
+
+ app.request().header("Cookie", session).get("/me").expectStatus(200).expectBody("carol");
+ app.request().header("Cookie", session).post("/auth/logout").expectStatus(303).expectHeader("Location", "/");
+ app.request().header("Cookie", session).get("/me").expectStatus(401);
+ }
+
+ @Test
+ void loginMethodsAreListed() {
+ app.get("/auth/methods").expectStatus(200).expectBody("[{\"id\":\"key\",\"name\":\"Key\",\"url\":\"/auth/key/login\",\"kind\":\"redirect\"}]");
+ }
+
+ @Test
+ void openApiDocumentsEachSchemeAndWhatEachOperationRequires() {
+ app.get("/openapi.json").expectStatus(200)
+ .expectBodyContains("\"securitySchemes\"")
+ .expectBodyContains("\"bearerFormat\":\"opaque\"")
+ .expectBodyContains("Requires role MANAGER on project")
+ .expectBodyContains("Requires scopes write");
+ }
+
+ @Test
+ void declaringRolesWithoutAResolverFailsTheBoot() {
+ FlashTest broken = FlashTest.of(flash -> flash
+ .install(new SecurityExtension())
+ .scan("dev.relism.flash.ext.security.fixtures"));
+ assertThrows(Exception.class, () -> broken.get("/open"));
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityPolicyTest.java b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityPolicyTest.java
new file mode 100644
index 0000000..c733077
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/SecurityPolicyTest.java
@@ -0,0 +1,44 @@
+package dev.relism.flash.ext.security;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SecurityPolicyTest {
+
+ static class Unannotated {}
+
+ @PermitAll @RolesAllowed("ADMIN")
+ static class Contradictory {}
+
+ @RolesAllowed({})
+ static class NoRoles {}
+
+ @RolesAllowed("ADMIN") @ScopesAllowed("write")
+ static class RolesAndScopes {}
+
+ @Test
+ void anUnannotatedTypeHasNoPolicy() {
+ assertNull(SecurityPolicy.of(Unannotated.class));
+ }
+
+ @Test
+ void contradictionsAndEmptyRequirementsFailAtCompileTime() {
+ assertThrows(IllegalStateException.class, () -> SecurityPolicy.of(Contradictory.class));
+ assertThrows(IllegalStateException.class, () -> SecurityPolicy.of(NoRoles.class));
+ }
+
+ @Test
+ void rolesAndScopesBothRequireAuthentication() {
+ SecurityPolicy policy = SecurityPolicy.of(RolesAndScopes.class);
+ assertTrue(policy.required());
+ assertTrue(policy.requiresRoles());
+ assertFalse(SecurityPolicy.of(OpenAccess.class).required());
+ }
+
+ @PermitAll
+ static class OpenAccess {}
+}
diff --git a/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/OpenHandler.java b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/OpenHandler.java
new file mode 100644
index 0000000..a840ee3
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/OpenHandler.java
@@ -0,0 +1,18 @@
+package dev.relism.flash.ext.security.fixtures;
+
+import dev.relism.flash.ext.security.PermitAll;
+import dev.relism.flash.ext.security.SecurityIdentity;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.RequestHandler;
+import dev.relism.flash.models.Response;
+import dev.relism.flash.routing.GET;
+
+@GET("/open")
+@PermitAll
+public final class OpenHandler extends RequestHandler {
+ @Override
+ public Object handle(Request req, Response res) {
+ SecurityIdentity identity = SecurityIdentity.current();
+ return identity == null ? "anonymous" : identity.principal().name();
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/ProjectHandler.java b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/ProjectHandler.java
new file mode 100644
index 0000000..9454cb2
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/ProjectHandler.java
@@ -0,0 +1,19 @@
+package dev.relism.flash.ext.security.fixtures;
+
+import dev.relism.flash.ext.openapi.ApiOperation;
+import dev.relism.flash.ext.security.RolesAllowed;
+import dev.relism.flash.ext.security.SecurityIdentity;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.RequestHandler;
+import dev.relism.flash.models.Response;
+import dev.relism.flash.routing.GET;
+
+@GET("/projects/{project}")
+@ApiOperation(summary = "fixture")
+@RolesAllowed(value = "MANAGER", on = "project")
+public final class ProjectHandler extends RequestHandler {
+ @Override
+ public Object handle(Request req, Response res) {
+ return SecurityIdentity.current().principal().name();
+ }
+}
diff --git a/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/WriteHandler.java b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/WriteHandler.java
new file mode 100644
index 0000000..72ee52d
--- /dev/null
+++ b/flash-extensions/flash-ext-security-core/src/test/java/dev/relism/flash/ext/security/fixtures/WriteHandler.java
@@ -0,0 +1,18 @@
+package dev.relism.flash.ext.security.fixtures;
+
+import dev.relism.flash.ext.openapi.ApiOperation;
+import dev.relism.flash.ext.security.ScopesAllowed;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.RequestHandler;
+import dev.relism.flash.models.Response;
+import dev.relism.flash.routing.POST;
+
+@POST("/write")
+@ApiOperation(summary = "fixture")
+@ScopesAllowed("write")
+public final class WriteHandler extends RequestHandler {
+ @Override
+ public Object handle(Request req, Response res) {
+ return "written";
+ }
+}
diff --git a/flash-extensions/flash-ext-security-form/docs/README.md b/flash-extensions/flash-ext-security-form/docs/README.md
new file mode 100644
index 0000000..9838c09
--- /dev/null
+++ b/flash-extensions/flash-ext-security-form/docs/README.md
@@ -0,0 +1,17 @@
+# flash-ext-security-form
+
+Password sign-in for [`flash-ext-security-core`](../../flash-ext-security-core/docs/README.md).
+
+```java
+app.install(new SecurityExtension())
+ .install(new FormLoginExtension(username -> accounts.find(username))); // PasswordStore
+```
+
+`POST /auth/form/login` takes `username` and `password` form-encoded, starts a session and answers
+`303` to `?redirect=` (same-origin paths only) or `/`. A wrong password and an unknown account are the
+same `401`, and cost the same time. The method is listed at `/auth/methods` with `"kind":"form"`, and
+the entry point sends browsers to `SecurityExtension.loginPage` to render it.
+
+`PasswordEncoder.pbkdf2()` hashes (PBKDF2-HMAC-SHA256, 600k iterations, JDK only); use it to create
+accounts, or pass another encoder to `passwordEncoder(...)`. Rate-limit the route with
+`flash-ext-limiter`.
diff --git a/flash-extensions/flash-ext-auth-core/pom.xml b/flash-extensions/flash-ext-security-form/pom.xml
similarity index 72%
rename from flash-extensions/flash-ext-auth-core/pom.xml
rename to flash-extensions/flash-ext-security-form/pom.xml
index abc299f..2da0682 100644
--- a/flash-extensions/flash-ext-auth-core/pom.xml
+++ b/flash-extensions/flash-ext-security-form/pom.xml
@@ -10,16 +10,21 @@
2.1.0-SNAPSHOT
- flash-ext-auth-core
+ flash-ext-security-form
dev.relism
- flash
+ flash-ext-security-core
org.junit.jupiter
junit-jupiter
+
+ dev.relism
+ flash-testing
+ test
+
diff --git a/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/FormLoginExtension.java b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/FormLoginExtension.java
new file mode 100644
index 0000000..18c0f4d
--- /dev/null
+++ b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/FormLoginExtension.java
@@ -0,0 +1,74 @@
+package dev.relism.flash.ext.security.form;
+
+import dev.relism.flash.exceptions.HttpException;
+import dev.relism.flash.ext.security.LoginMethod;
+import dev.relism.flash.ext.security.SecurityExtension;
+import dev.relism.flash.extension.FlashContext;
+import dev.relism.flash.extension.FlashExtension;
+import dev.relism.flash.extension.FlashRegistrar;
+
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Password sign-in: {@code POST /auth/form/login} with {@code username} and {@code password}
+ * form-encoded — what an HTML form sends, and what {@code fetch} sends given {@code URLSearchParams}.
+ * Success starts a session and answers {@code 303} to {@code redirect} (same-origin paths only) or
+ * {@code /}; failure is a {@code 401}, identical for an unknown account and a wrong password.
+ *
+ * {@code
+ * app.install(new SecurityExtension())
+ * .install(new FormLoginExtension(accounts::byUsername));
+ * }
+ *
+ * Rate-limit the route with {@code flash-ext-limiter}; this extension does not.
+ */
+public final class FormLoginExtension implements FlashExtension {
+
+ public static final String LOGIN = "/auth/form/login";
+
+ private final PasswordStore store;
+ private PasswordEncoder encoder = PasswordEncoder.pbkdf2();
+ private String unknownAccountHash;
+
+ public FormLoginExtension(PasswordStore store) {
+ this.store = store;
+ }
+
+ public FormLoginExtension passwordEncoder(PasswordEncoder encoder) {
+ this.encoder = encoder;
+ return this;
+ }
+
+ @Override
+ public void configure(FlashRegistrar app, FlashContext ctx) {
+ // Checked against when no account matches, so an unknown username costs what a wrong password does.
+ unknownAccountHash = encoder.encode("unknown-account");
+ app.post(LOGIN, (req, res) -> {
+ String body = new String(req.body().bytes(), StandardCharsets.UTF_8);
+ String username = field(body, "username");
+ String password = field(body, "password");
+ if (username == null || password == null) throw HttpException.badRequest("username and password are required");
+
+ PasswordStore.Account account = store.find(username);
+ boolean matches = encoder.matches(password, account == null ? unknownAccountHash : account.passwordHash());
+ if (account == null || !matches) throw HttpException.unauthorized();
+
+ ctx.require(SecurityExtension.class).signIn(req, res, account.principal());
+ String redirect = req.query("redirect");
+ boolean local = redirect != null && redirect.startsWith("/") && !redirect.startsWith("//") && !redirect.startsWith("/\\");
+ res.status(303).header("Location", local ? redirect : "/");
+ return null;
+ });
+ ctx.onReady(() -> ctx.require(SecurityExtension.class)
+ .loginMethod(new LoginMethod("form", "Password", LOGIN, LoginMethod.Kind.FORM)));
+ }
+
+ private static String field(String body, String name) {
+ for (String pair : body.split("&")) {
+ int eq = pair.indexOf('=');
+ if (eq == name.length() && pair.startsWith(name)) return URLDecoder.decode(pair.substring(eq + 1), StandardCharsets.UTF_8);
+ }
+ return null;
+ }
+}
diff --git a/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordEncoder.java b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordEncoder.java
new file mode 100644
index 0000000..3b8210b
--- /dev/null
+++ b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordEncoder.java
@@ -0,0 +1,58 @@
+package dev.relism.flash.ext.security.form;
+
+import javax.crypto.SecretKeyFactory;
+import javax.crypto.spec.PBEKeySpec;
+import java.security.GeneralSecurityException;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.util.Base64;
+
+/** One-way password hashing. {@link #pbkdf2()} unless another is configured. */
+public interface PasswordEncoder {
+
+ String encode(CharSequence password);
+
+ /** Constant-time; {@code false} for anything this encoder did not produce. */
+ boolean matches(CharSequence password, String encoded);
+
+ /** PBKDF2-HMAC-SHA256, 600,000 iterations (OWASP 2023), a random 16-byte salt — JDK only. */
+ static PasswordEncoder pbkdf2() {
+ return Pbkdf2.INSTANCE;
+ }
+
+ enum Pbkdf2 implements PasswordEncoder {
+ INSTANCE;
+
+ private static final int ITERATIONS = 600_000;
+ private static final SecureRandom RANDOM = new SecureRandom();
+
+ @Override
+ public String encode(CharSequence password) {
+ byte[] salt = new byte[16];
+ RANDOM.nextBytes(salt);
+ return "pbkdf2$" + ITERATIONS + "$" + Base64.getEncoder().encodeToString(salt)
+ + "$" + Base64.getEncoder().encodeToString(derive(password, salt, ITERATIONS));
+ }
+
+ @Override
+ public boolean matches(CharSequence password, String encoded) {
+ String[] parts = encoded == null ? new String[0] : encoded.split("\\$");
+ if (parts.length != 4 || !parts[0].equals("pbkdf2")) return false;
+ byte[] salt = Base64.getDecoder().decode(parts[2]);
+ return MessageDigest.isEqual(derive(password, salt, Integer.parseInt(parts[1])), Base64.getDecoder().decode(parts[3]));
+ }
+
+ private static byte[] derive(CharSequence password, byte[] salt, int iterations) {
+ char[] chars = password.toString().toCharArray();
+ PBEKeySpec spec = new PBEKeySpec(chars, salt, iterations, 256);
+ try {
+ return SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256").generateSecret(spec).getEncoded();
+ } catch (GeneralSecurityException impossible) {
+ throw new IllegalStateException(impossible);
+ } finally {
+ spec.clearPassword();
+ java.util.Arrays.fill(chars, '\0');
+ }
+ }
+ }
+}
diff --git a/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordStore.java b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordStore.java
new file mode 100644
index 0000000..c4fd1ef
--- /dev/null
+++ b/flash-extensions/flash-ext-security-form/src/main/java/dev/relism/flash/ext/security/form/PasswordStore.java
@@ -0,0 +1,14 @@
+package dev.relism.flash.ext.security.form;
+
+import dev.relism.flash.ext.security.Principal;
+
+/** Where the application keeps the accounts that sign in with a password. */
+@FunctionalInterface
+public interface PasswordStore {
+
+ /** The account signing in as {@code username}, or {@code null}. */
+ Account find(String username);
+
+ /** @param passwordHash as produced by the configured {@link PasswordEncoder} */
+ record Account(Principal principal, String passwordHash) {}
+}
diff --git a/flash-extensions/flash-ext-security-form/src/test/java/dev/relism/flash/ext/security/form/FormLoginExtensionTest.java b/flash-extensions/flash-ext-security-form/src/test/java/dev/relism/flash/ext/security/form/FormLoginExtensionTest.java
new file mode 100644
index 0000000..9bd0280
--- /dev/null
+++ b/flash-extensions/flash-ext-security-form/src/test/java/dev/relism/flash/ext/security/form/FormLoginExtensionTest.java
@@ -0,0 +1,63 @@
+package dev.relism.flash.ext.security.form;
+
+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.testing.FlashResponse;
+import dev.relism.flash.testing.FlashTest;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class FormLoginExtensionTest {
+
+ static final String HASH = PasswordEncoder.pbkdf2().encode("s3cret");
+ static final SecurityExtension security = new SecurityExtension();
+
+ @RegisterExtension
+ static final FlashTest app = FlashTest.of(flash -> flash
+ .install(security)
+ .install(new FormLoginExtension(username -> username.equals("alice")
+ ? new PasswordStore.Account(() -> "alice", HASH) : null))
+ .get("/me", (req, res) -> SecurityIdentity.current().principal().name(), security.enforce(SecurityPolicy.AUTHENTICATED)));
+
+ static FlashResponse login(String form, String query) {
+ return app.request().header("content-type", "application/x-www-form-urlencoded").body(form)
+ .post(FormLoginExtension.LOGIN + query);
+ }
+
+ @Test
+ void theRightPasswordStartsASessionAndRedirectsToALocalPath() {
+ var response = login("username=alice&password=s3cret", "?redirect=%2Fprojects")
+ .expectStatus(303).expectHeader("Location", "/projects");
+ String cookie = response.header("Set-Cookie");
+ app.request().header("Cookie", cookie.substring(0, cookie.indexOf(';'))).get("/me").expectBody("alice");
+ }
+
+ @Test
+ void aForeignRedirectIsIgnored() {
+ login("username=alice&password=s3cret", "?redirect=%2F%2Fevil.example").expectHeader("Location", "/");
+ }
+
+ @Test
+ void aWrongPasswordAndAnUnknownAccountAreTheSame401() {
+ assertNull(login("username=alice&password=nope", "").expectStatus(401).header("Set-Cookie"));
+ login("username=mallory&password=s3cret", "").expectStatus(401);
+ }
+
+ @Test
+ void pbkdf2RoundTripsAndRejectsWhatItDidNotProduce() {
+ PasswordEncoder encoder = PasswordEncoder.pbkdf2();
+ assertTrue(encoder.matches("s3cret", HASH));
+ assertFalse(encoder.matches("s3cret", "plain"));
+ assertFalse(encoder.matches("s3cret", null));
+ }
+
+ @Test
+ void theFormIsListedAsALoginMethod() {
+ app.get("/auth/methods").expectBodyContains("\"kind\":\"form\"");
+ }
+}
diff --git a/flash-extensions/flash-ext-security-oidc/docs/README.md b/flash-extensions/flash-ext-security-oidc/docs/README.md
new file mode 100644
index 0000000..d186ba6
--- /dev/null
+++ b/flash-extensions/flash-ext-security-oidc/docs/README.md
@@ -0,0 +1,71 @@
+# flash-ext-security-oidc
+
+OpenID Connect for [`flash-ext-security-core`](../../flash-ext-security-core/docs/README.md): bearer
+access tokens, and browser sign-in through the authorization code flow with PKCE.
+
+```java
+app.install(new SecurityExtension())
+ .install(new OidcExtension(
+ OidcProvider.of("sso", "https://id.example.com/realms/acme", "app", secret).name("Acme SSO"),
+ OidcProvider.of("partner", "https://login.partner.example/", "app", partnerSecret)));
+```
+
+Discovery runs at boot, so an unreachable provider fails the start rather than the first sign-in.
+
+## Bearer tokens
+
+`Authorization: Bearer ` is matched to its provider by `iss`, then verified against that
+provider's keys (RS/PS/ES algorithms, `typ` `JWT` or `at+jwt`, `iss`, `sub`, `exp`). One parse, one map
+lookup, however many providers are configured. A token from an unconfigured issuer is left to other
+mechanisms; a token from a configured one that fails verification is `401 invalid_token`.
+
+## Sign-in
+
+| Route | |
+|---|---|
+| `GET /auth/oidc/{id}/login?redirect=/path` | redirects to the provider |
+| `GET /auth/oidc/{id}/callback` | exchanges the code, verifies the ID token and nonce, starts a session |
+
+The PKCE verifier, nonce and state travel in a short-lived `HttpOnly` cookie scoped to `/auth/oidc`,
+so sign-in needs no server-side state and works across instances. The session's principal is renewed
+with the refresh token when its access token expires; `POST /auth/logout` ends it and continues to the
+provider's `end_session_endpoint`. The client authenticates with `client_secret_basic`. Register
+`{origin}/auth/oidc/{id}/callback` as a redirect URI and `{origin}/` as a post-logout redirect URI;
+behind a proxy, forward `X-Forwarded-Proto` and `X-Forwarded-Host`.
+
+Each provider is listed at `/auth/methods` (`"kind":"redirect"`) and published to OpenAPI as an
+`openIdConnect` scheme.
+
+## Providers added at runtime
+
+```java
+OidcExtension oidc = new OidcExtension(central);
+oidc.register(OidcProvider.of("acme", "https://login.acme.example/", clientId, secret)); // an organization's own IdP
+oidc.unregister("acme");
+```
+
+Discovery runs inside `register`, which refuses a provider — or any endpoint its discovery names — that
+is not https on a public address: registration makes the server fetch URLs someone else chose.
+`allowLocalProviders()` lifts that for development. Registered providers serve bearer tokens and
+`/auth/oidc/{id}/login` immediately, but are not listed at `/auth/methods` or in OpenAPI: which provider
+a given user signs in with is the application's decision — typically an `AuthenticationEntryPoint` that
+picks one from the email domain. Their issuer is also a tenant boundary the application must enforce
+in its `UserResolver`: a user belongs to the organizations whose issuer vouched for them.
+
+## Principal and roles
+
+`OidcPrincipal` carries the verified claims (`issuer()`, `name()` = `sub`, `email()`, `claim(...)`),
+the access token and, for sessions, the refresh token. `hasScope` reads `scope`/`scp`; `hasAudience`
+reads `aud`.
+
+Roles are the application's decision. To take them from the token instead:
+
+```java
+new SecurityExtension().roles(ClaimRoles.at("realm_access.roles")) // Keycloak; "groups" for most others
+```
+
+## Testing
+
+`FakeOidcProvider` in [`flash-ext-security-test`](../../flash-ext-security-test/docs/README.md) serves
+discovery, keys and the code and refresh flows on a local port; `OidcTokens.passwordGrant(...)` gets a
+real token from a real provider such as Keycloak in Testcontainers.
diff --git a/flash-extensions/flash-ext-security-oidc/pom.xml b/flash-extensions/flash-ext-security-oidc/pom.xml
new file mode 100644
index 0000000..50cdd8d
--- /dev/null
+++ b/flash-extensions/flash-ext-security-oidc/pom.xml
@@ -0,0 +1,33 @@
+
+
+ 4.0.0
+
+
+ dev.relism
+ flash-extensions
+ 2.1.0-SNAPSHOT
+
+
+ flash-ext-security-oidc
+
+
+
+ dev.relism
+ flash-ext-security-core
+
+
+ com.nimbusds
+ nimbus-jose-jwt
+
+
+ org.junit.jupiter
+ junit-jupiter
+
+
+ dev.relism
+ flash-ext-security-test
+
+
+
diff --git a/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/ClaimRoles.java b/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/ClaimRoles.java
new file mode 100644
index 0000000..0af47cb
--- /dev/null
+++ b/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/ClaimRoles.java
@@ -0,0 +1,38 @@
+package dev.relism.flash.ext.security.oidc;
+
+import dev.relism.flash.ext.security.Principal;
+import dev.relism.flash.ext.security.RoleResolver;
+import dev.relism.flash.ext.security.SecurityIdentity;
+import dev.relism.flash.ext.security.Target;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+/** Roles read from the provider's token instead of the application's own data. */
+public final class ClaimRoles implements RoleResolver {
+
+ private final String[] path;
+
+ private ClaimRoles(String claimPath) {
+ this.path = claimPath.split("\\.");
+ }
+
+ /** Roles at a dot-separated claim path — {@code realm_access.roles} for Keycloak, {@code groups} for most others. */
+ public static ClaimRoles at(String claimPath) {
+ return new ClaimRoles(claimPath);
+ }
+
+ /** The roles {@code principal}'s token carries; none for a caller OIDC did not authenticate. */
+ @SuppressWarnings("unchecked")
+ public List of(Principal principal) {
+ Object value = principal instanceof OidcPrincipal oidc ? oidc.claims() : null;
+ for (int i = 0; i < path.length && value != null; i++) value = value instanceof Map map ? map.get(path[i]) : null;
+ return value instanceof List roles ? (List) roles : value instanceof Collection roles ? List.copyOf((Collection) roles) : List.of();
+ }
+
+ @Override
+ public boolean hasRole(SecurityIdentity identity, String role, Target on) {
+ return of(identity.principal()).contains(role);
+ }
+}
diff --git a/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/OidcExtension.java b/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/OidcExtension.java
new file mode 100644
index 0000000..5bda112
--- /dev/null
+++ b/flash-extensions/flash-ext-security-oidc/src/main/java/dev/relism/flash/ext/security/oidc/OidcExtension.java
@@ -0,0 +1,239 @@
+package dev.relism.flash.ext.security.oidc;
+
+import com.nimbusds.jwt.SignedJWT;
+import dev.relism.flash.exceptions.HttpException;
+import dev.relism.flash.ext.security.AuthenticationFailedException;
+import dev.relism.flash.ext.security.AuthenticationMechanism;
+import dev.relism.flash.ext.security.LoginMethod;
+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.ext.security.Session;
+import dev.relism.flash.extension.FlashContext;
+import dev.relism.flash.extension.FlashExtension;
+import dev.relism.flash.extension.FlashRegistrar;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.Response;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.time.Instant;
+import java.util.Base64;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * OpenID Connect: bearer access tokens from any configured provider, and browser sign-in through the
+ * authorization code flow with PKCE, which ends in a {@link SecurityExtension} session renewed with
+ * the refresh token.
+ *
+ * {@code
+ * app.install(new SecurityExtension())
+ * .install(new OidcExtension(OidcProvider.of("sso", "https://id.example.com/realms/acme", "app", secret)));
+ * }
+ *
+ * Routes: {@code GET /auth/oidc/{provider}/login?redirect=/path} and its callback. A bearer token
+ * is matched to its provider by {@code iss} before its signature is checked against that provider's
+ * keys, so any number of providers costs one lookup; a token from an issuer not configured here is
+ * left to other mechanisms.
+ */
+public final class OidcExtension implements FlashExtension, AuthenticationMechanism {
+
+ private static final AuthenticationFailedException INVALID = new AuthenticationFailedException("Bearer error=\"invalid_token\"");
+ private static final String FLOW = "flash_oidc";
+ private static final SecureRandom RANDOM = new SecureRandom();
+ private static final Base64.Encoder BASE64URL = Base64.getUrlEncoder().withoutPadding();
+
+ private final OidcProvider[] configured;
+ private final Map byId = new ConcurrentHashMap<>();
+ private final Map