From 7b996b552b7ec47d7ae5627501affb9702b7f65b Mon Sep 17 00:00:00 2001
From: Relism <itzdrekkopvp@gmail.com>
Date: Thu, 26 Mar 2026 14:10:53 +0100
Subject: [PATCH] pre-major refactoring + ext api.

---
 .idea/encodings.xml                           |  10 +
 .idea/jsLibraryMappings.xml                   |   6 +
 .idea/vcs.xml                                 |   1 -
 .idea/workspace.xml                           | 153 +++++---
 flash-extensions/flash-ext-jackson/README.md  | 102 +++++
 flash-extensions/flash-ext-jackson/pom.xml    |  34 ++
 .../relism/ext/jackson/JacksonExtension.java  |  72 ++++
 .../relism/ext/jackson/JacksonHandler.java    |  77 ++++
 flash-extensions/flash-ext-oidc/README.md     | 352 ++++++++++++++++++
 flash-extensions/flash-ext-oidc/pom.xml       |  43 +++
 .../dev/relism/ext/oidc/Authenticated.java    |  23 ++
 .../dev/relism/ext/oidc/ClaimsHolder.java     |  71 ++++
 .../dev/relism/ext/oidc/ClientAuthMethod.java |  18 +
 .../dev/relism/ext/oidc/DiscoveryClient.java  |  50 +++
 .../ext/oidc/InMemoryOidcSessionStore.java    |  20 +
 .../java/dev/relism/ext/oidc/JwtUtils.java    |  38 ++
 .../dev/relism/ext/oidc/JwtValidator.java     | 184 +++++++++
 .../java/dev/relism/ext/oidc/OidcConfig.java  | 250 +++++++++++++
 .../dev/relism/ext/oidc/OidcExtension.java    | 340 +++++++++++++++++
 .../dev/relism/ext/oidc/OidcMiddleware.java   | 203 ++++++++++
 .../relism/ext/oidc/OidcProviderMetadata.java |  15 +
 .../java/dev/relism/ext/oidc/OidcSession.java |  47 +++
 .../dev/relism/ext/oidc/OidcSessionStore.java |  14 +
 .../dev/relism/ext/oidc/OidcStateStore.java   |  39 ++
 .../relism/ext/oidc/OidcTokenResponse.java    |  10 +
 .../java/dev/relism/ext/oidc/OidcUser.java    | 106 ++++++
 .../ext/oidc/OidcValidationException.java     |  12 +
 .../java/dev/relism/ext/oidc/PkceUtils.java   |  36 ++
 .../dev/relism/ext/oidc/RolesAllowed.java     |  32 ++
 .../java/dev/relism/ext/oidc/TokenClient.java | 112 ++++++
 flash-extensions/flash-ext-openapi/README.md  | 160 ++++++++
 flash-extensions/flash-ext-openapi/pom.xml    |  34 ++
 .../dev/relism/ext/openapi/ApiOperation.java  |  26 ++
 .../java/dev/relism/ext/openapi/ApiParam.java |  27 ++
 .../dev/relism/ext/openapi/ApiParams.java     |  13 +
 .../dev/relism/ext/openapi/ApiResponse.java   |  23 ++
 .../dev/relism/ext/openapi/ApiResponses.java  |  13 +
 .../relism/ext/openapi/OpenApiBuilder.java    | 204 ++++++++++
 .../relism/ext/openapi/OpenApiExtension.java  | 139 +++++++
 .../openapi/OpenApiSecurityContributor.java   |  49 +++
 .../ext/openapi/OpenApiSecurityRegistry.java  |  31 ++
 flash-extensions/pom.xml                      |  52 +++
 .../src/main/java/dev/relism/HttpServer.java  |  41 +-
 .../dev/relism/exceptions/HttpException.java  |  53 +++
 .../relism/extension/AnnotationProcessor.java |  22 ++
 .../relism/extension/ExtensionContext.java    |  62 +++
 .../java/dev/relism/extension/FlashApp.java   | 182 +++++++++
 .../dev/relism/extension/FlashExtension.java  |  25 ++
 .../java/dev/relism/models/RequestHelper.java | 106 ++++++
 .../dev/relism/routing/AbstractRouter.java    |  71 ++--
 .../java/dev/relism/routing/RouteHandle.java  |  70 ++++
 .../dev/relism/HttpServerConcurrencyTest.java |   6 +-
 .../test/java/dev/relism/HttpServerTest.java  |  16 +-
 .../relism/routing/AbstractRouterTest.java    |  18 +-
 .../dev/relism/routing/GlobalRouterTest.java  |   2 +-
 .../FastPathRouterImplTest.java               |   8 +-
 pom.xml                                       |  17 +
 57 files changed, 3823 insertions(+), 117 deletions(-)
 create mode 100644 .idea/jsLibraryMappings.xml
 create mode 100644 flash-extensions/flash-ext-jackson/README.md
 create mode 100644 flash-extensions/flash-ext-jackson/pom.xml
 create mode 100644 flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
 create mode 100644 flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonHandler.java
 create mode 100644 flash-extensions/flash-ext-oidc/README.md
 create mode 100644 flash-extensions/flash-ext-oidc/pom.xml
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/Authenticated.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClaimsHolder.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClientAuthMethod.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/DiscoveryClient.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/InMemoryOidcSessionStore.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtUtils.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtValidator.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcProviderMetadata.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSession.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSessionStore.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcStateStore.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcTokenResponse.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcValidationException.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/PkceUtils.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/RolesAllowed.java
 create mode 100644 flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/TokenClient.java
 create mode 100644 flash-extensions/flash-ext-openapi/README.md
 create mode 100644 flash-extensions/flash-ext-openapi/pom.xml
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParam.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParams.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java
 create mode 100644 flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java
 create mode 100644 flash-extensions/pom.xml
 create mode 100644 flash/src/main/java/dev/relism/exceptions/HttpException.java
 create mode 100644 flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
 create mode 100644 flash/src/main/java/dev/relism/extension/ExtensionContext.java
 create mode 100644 flash/src/main/java/dev/relism/extension/FlashApp.java
 create mode 100644 flash/src/main/java/dev/relism/extension/FlashExtension.java
 create mode 100644 flash/src/main/java/dev/relism/models/RequestHelper.java
 create mode 100644 flash/src/main/java/dev/relism/routing/RouteHandle.java

diff --git a/.idea/encodings.xml b/.idea/encodings.xml
index a931d1c..0a645a4 100644
--- a/.idea/encodings.xml
+++ b/.idea/encodings.xml
@@ -3,6 +3,16 @@
   <component name="Encoding">
     <file url="file://$PROJECT_DIR$/flash-bench/src/main/java" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash-bench/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-api/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-api/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-jackson/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-oidc/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/flash-ext-openapi/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/flash-extensions/src/main/resources" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash/src/main/java" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/flash/src/main/resources" charset="UTF-8" />
     <file url="file://$PROJECT_DIR$/src/main/java" charset="UTF-8" />
diff --git a/.idea/jsLibraryMappings.xml b/.idea/jsLibraryMappings.xml
new file mode 100644
index 0000000..9182765
--- /dev/null
+++ b/.idea/jsLibraryMappings.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptLibraryMappings">
+    <excludedPredefinedLibrary name="Flash/nuxt-shadcn-dashboard/node_modules" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/vcs.xml b/.idea/vcs.xml
index d5975af..35eb1dd 100644
--- a/.idea/vcs.xml
+++ b/.idea/vcs.xml
@@ -2,6 +2,5 @@
 <project version="4">
   <component name="VcsDirectoryMappings">
     <mapping directory="" vcs="Git" />
-    <mapping directory="$PROJECT_DIR$/nuxt-shadcn-dashboard" vcs="Git" />
   </component>
 </project>
\ No newline at end of file
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index ed6e7a2..917c0db 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,19 +4,19 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="fc757130-fe3e-4ea9-8d69-c26ffb8545a4" name="Changes" comment="multipart parsing, request body access, and chunked input stream support">
+    <list default="true" id="fc757130-fe3e-4ea9-8d69-c26ffb8545a4" name="Changes" comment="enhanced router middleware support; added pre-fused middleware handling and improved handler registration">
+      <change afterPath="$PROJECT_DIR$/.idea/jsLibraryMappings.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/.idea/encodings.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/encodings.xml" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/vcs.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/vcs.xml" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-bench/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/flash-bench/pom.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash-bench/src/main/java/dev/relism/bench/Main.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash-bench/src/main/java/dev/relism/bench/Main.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/HttpServer.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/HttpServer.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/Main.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/Main.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/QueryParams.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/QueryParams.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Response.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/models/Response.java" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/AbstractRouter.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/AbstractRouter.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/GlobalRouter.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/GlobalRouter.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Route.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/Route.java" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImpl.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/main/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImpl.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/HttpServerTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java" beforeDir="false" afterPath="$PROJECT_DIR$/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/pom.xml" beforeDir="false" afterPath="$PROJECT_DIR$/pom.xml" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -30,7 +30,7 @@
     </persistenceIdMap>
   </component>
   <component name="EmbeddingIndexingInfo">
-    <option name="cachedIndexableFilesCount" value="86" />
+    <option name="cachedIndexableFilesCount" value="130" />
     <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
   </component>
   <component name="FileTemplateManagerImpl">
@@ -43,6 +43,7 @@
   </component>
   <component name="Git.Settings">
     <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+    <option name="ROOT_SYNC" value="DONT_SYNC" />
   </component>
   <component name="GitHubPullRequestSearchHistory">{
   &quot;lastFilter&quot;: {
@@ -68,48 +69,50 @@
     <option name="hideEmptyMiddlePackages" value="true" />
     <option name="showLibraryContents" value="true" />
   </component>
-  <component name="PropertiesComponent">{
-  &quot;keyToString&quot;: {
-    &quot;Application.ExternalBenchmark (1).executor&quot;: &quot;Run&quot;,
-    &quot;Application.ExternalBenchmark.executor&quot;: &quot;Run&quot;,
-    &quot;Application.Main.executor&quot;: &quot;Run&quot;,
-    &quot;Application.dev.relism.bench.Main.executor&quot;: &quot;Run&quot;,
-    &quot;JUnit.RequestParserTest.executor&quot;: &quot;Run&quot;,
-    &quot;JUnit.RequestParserTest.headers_caseInsensitive.executor&quot;: &quot;Debug&quot;,
-    &quot;Maven.FlashPractice [test].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [compile].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash [test].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [clean].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [package].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-bench [validate].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-parent [install].executor&quot;: &quot;Run&quot;,
-    &quot;Maven.flash-parent [package].executor&quot;: &quot;Run&quot;,
-    &quot;ModuleVcsDetector.initialDetectionPerformed&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.MCP Project settings loaded&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
-    &quot;RunOnceActivity.typescript.service.memoryLimit.init&quot;: &quot;true&quot;,
-    &quot;SHARE_PROJECT_CONFIGURATION_FILES&quot;: &quot;true&quot;,
-    &quot;git-widget-placeholder&quot;: &quot;master&quot;,
-    &quot;ignore.virus.scanning.warn.message&quot;: &quot;true&quot;,
-    &quot;kotlin-language-version-configured&quot;: &quot;true&quot;,
-    &quot;last_opened_file_path&quot;: &quot;C:/Users/elorc/Documents/Coding/Java/practice/Flash&quot;,
-    &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
-    &quot;node.js.detected.package.tslint&quot;: &quot;true&quot;,
-    &quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
-    &quot;node.js.selected.package.tslint&quot;: &quot;(autodetect)&quot;,
-    &quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
-    &quot;onboarding.tips.debug.path&quot;: &quot;C:/Users/elorc/Documents/Coding/Java/practice/FlashPractice/flash-bench/src/main/java/dev/relism/Main.java&quot;,
-    &quot;project.structure.last.edited&quot;: &quot;Modules&quot;,
-    &quot;project.structure.proportion&quot;: &quot;0.15&quot;,
-    &quot;project.structure.side.proportion&quot;: &quot;0.1150748&quot;,
-    &quot;settings.editor.selected.configurable&quot;: &quot;ml.llm.LLMThirdPartyAiProvidersConfigurable&quot;,
-    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "Application.ExternalBenchmark (1).executor": "Run",
+    "Application.ExternalBenchmark.executor": "Run",
+    "Application.Main.executor": "Run",
+    "Application.dev.relism.bench.Main.executor": "Run",
+    "JUnit.RequestParserTest.executor": "Run",
+    "JUnit.RequestParserTest.headers_caseInsensitive.executor": "Debug",
+    "Maven.FlashPractice [test].executor": "Run",
+    "Maven.flash [compile].executor": "Run",
+    "Maven.flash [install].executor": "Run",
+    "Maven.flash [test].executor": "Run",
+    "Maven.flash-bench [clean].executor": "Run",
+    "Maven.flash-bench [install].executor": "Run",
+    "Maven.flash-bench [package].executor": "Run",
+    "Maven.flash-bench [validate].executor": "Run",
+    "Maven.flash-parent [install].executor": "Run",
+    "Maven.flash-parent [package].executor": "Run",
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "SHARE_PROJECT_CONFIGURATION_FILES": "true",
+    "git-widget-placeholder": "master",
+    "ignore.virus.scanning.warn.message": "true",
+    "kotlin-language-version-configured": "true",
+    "last_opened_file_path": "C:/Users/elorc/Documents/Coding/Java/practice/Flash",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "npm.build.executor": "Run",
+    "onboarding.tips.debug.path": "C:/Users/elorc/Documents/Coding/Java/practice/FlashPractice/flash-bench/src/main/java/dev/relism/Main.java",
+    "project.structure.last.edited": "Modules",
+    "project.structure.proportion": "0.15",
+    "project.structure.side.proportion": "0.1150748",
+    "settings.editor.selected.configurable": "project.propVCSSupport.DirectoryMappings",
+    "ts.external.directory.path": "C:\\Users\\elorc\\Documents\\Coding\\Java\\practice\\Flash\\nuxt-shadcn-dashboard\\node_modules\\typescript\\lib",
+    "vue.rearranger.settings.migration": "true"
   }
-}</component>
+}]]></component>
   <component name="RecentsManager">
     <key name="MoveFile.RECENT_KEYS">
       <recent name="C:\Users\elorc\Documents\Coding\Java\practice\Flash" />
@@ -184,9 +187,20 @@
         <option name="Make" enabled="true" />
       </method>
     </configuration>
+    <configuration name="build" type="js.build_tools.npm" temporary="true" nameIsGenerated="true">
+      <package-json value="$PROJECT_DIR$/nuxt-shadcn-dashboard/package.json" />
+      <command value="run" />
+      <scripts>
+        <script value="build" />
+      </scripts>
+      <node-interpreter value="project" />
+      <envs />
+      <method v="2" />
+    </configuration>
     <recent_temporary>
       <list>
         <item itemvalue="Application.dev.relism.bench.Main" />
+        <item itemvalue="npm.build" />
         <item itemvalue="Application.Main" />
         <item itemvalue="Application.ExternalBenchmark (1)" />
         <item itemvalue="Application.ExternalBenchmark" />
@@ -229,7 +243,15 @@
       <workItem from="1773837116508" duration="4255000" />
       <workItem from="1773847734658" duration="911000" />
       <workItem from="1773875652058" duration="5481000" />
-      <workItem from="1773915392332" duration="24154000" />
+      <workItem from="1773915392332" duration="36877000" />
+      <workItem from="1773996650761" duration="101000" />
+      <workItem from="1774011413085" duration="2519000" />
+      <workItem from="1774033964550" duration="5379000" />
+      <workItem from="1774116033963" duration="1364000" />
+      <workItem from="1774136286683" duration="3816000" />
+      <workItem from="1774187096932" duration="25000" />
+      <workItem from="1774458099414" duration="14351000" />
+      <workItem from="1774523863906" duration="4441000" />
     </task>
     <task id="LOCAL-00001" summary="Initial">
       <option name="closed" value="true" />
@@ -279,7 +301,15 @@
       <option name="project" value="LOCAL" />
       <updated>1773920735659</updated>
     </task>
-    <option name="localTasksCounter" value="7" />
+    <task id="LOCAL-00007" summary="enhanced router middleware support; added pre-fused middleware handling and improved handler registration">
+      <option name="closed" value="true" />
+      <created>1773952556190</created>
+      <option name="number" value="00007" />
+      <option name="presentableId" value="LOCAL-00007" />
+      <option name="project" value="LOCAL" />
+      <updated>1773952556190</updated>
+    </task>
+    <option name="localTasksCounter" value="8" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -290,7 +320,19 @@
       <map>
         <entry key="MAIN">
           <value>
-            <State />
+            <State>
+              <option name="FILTERS">
+                <map>
+                  <entry key="branch">
+                    <value>
+                      <list>
+                        <option value="claude/distracted-spence" />
+                      </list>
+                    </value>
+                  </entry>
+                </map>
+              </option>
+            </State>
           </value>
         </entry>
       </map>
@@ -303,7 +345,8 @@
     <MESSAGE value="optimized dynamic body size impl, decluttering javadocs/comments" />
     <MESSAGE value="enhanced HTTP server configuration and response handling; added acceptorThreads, improved header management, and refined error page titles" />
     <MESSAGE value="multipart parsing, request body access, and chunked input stream support" />
-    <option name="LAST_COMMIT_MESSAGE" value="multipart parsing, request body access, and chunked input stream support" />
+    <MESSAGE value="enhanced router middleware support; added pre-fused middleware handling and improved handler registration" />
+    <option name="LAST_COMMIT_MESSAGE" value="enhanced router middleware support; added pre-fused middleware handling and improved handler registration" />
   </component>
   <component name="XSLT-Support.FileAssociations.UIState">
     <expand />
diff --git a/flash-extensions/flash-ext-jackson/README.md b/flash-extensions/flash-ext-jackson/README.md
new file mode 100644
index 0000000..57ba650
--- /dev/null
+++ b/flash-extensions/flash-ext-jackson/README.md
@@ -0,0 +1,102 @@
+# flash-ext-jackson
+
+Jackson JSON integration for the Flash HTTP server.
+
+## What it provides
+
+| Component | Description |
+|---|---|
+| `JacksonExtension` | Installs Jackson into the extension layer |
+| `JacksonHandler` | Base class for handlers that need JSON I/O |
+| Global exception handler | Maps `HttpException` → JSON error; all other exceptions → 500 |
+
+## Installation
+
+```xml
+<dependency>
+    <groupId>dev.relism</groupId>
+    <artifactId>flash-ext-jackson</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+Install before any extension that needs JSON (e.g. `flash-ext-openapi`, `flash-ext-oidc`):
+
+```java
+FlashApp.of(new HttpServer(config))
+    .install(new JacksonExtension())
+    // ... other extensions
+```
+
+### Custom mapper
+
+```java
+ObjectMapper mapper = JsonMapper.builder()
+    .addModule(new JavaTimeModule())
+    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+    .build();
+
+FlashApp.of(new HttpServer(config))
+    .install(new JacksonExtension(mapper));
+```
+
+## JacksonHandler
+
+Extend `JacksonHandler` to get `bodyAs` and `json` helpers without constructor boilerplate.
+The `ObjectMapper` is injected once at startup and shared across all subclasses.
+
+```java
+@Route(method = HttpMethod.POST, path = "/api/blogs")
+@ApiOperation(summary = "Create blog")
+@ApiResponse(status = 201, description = "Created", schema = Blog.class)
+@ApiResponse(status = 400, description = "Invalid body")
+public class CreateBlog extends JacksonHandler {
+
+    @Override
+    public Object handle(Request req, Response res) throws Exception {
+        CreateBlogRequest body = bodyAs(req, CreateBlogRequest.class);
+        Blog created = service.create(body);
+        res.setStatusCode(201);
+        return json(res, created);         // sets Content-Type: application/json
+    }
+}
+```
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `bodyAs(req, Type.class)` | Deserializes the request body; throws `HttpException` 400 on parse errors |
+| `json(res, obj)` | Serializes `obj`, sets `Content-Type: application/json`, returns the JSON string |
+| `jsonView(res, obj, View.class)` | Like `json` but applies a Jackson `@JsonView` filter |
+
+## Exception handling
+
+`JacksonExtension` installs a global exception handler that applies to every route:
+
+```
+HttpException(status, message)  →  HTTP <status>  {"error": "<message>"}
+Any other Throwable             →  HTTP 500        {"error": "Internal Server Error"}
+```
+
+To throw a handled HTTP error from any handler:
+
+```java
+throw HttpException.notFound("Blog not found");
+throw HttpException.badRequest("Missing field: title");
+throw HttpException.unauthorized();
+throw HttpException.forbidden();
+```
+
+## Lambda routes
+
+For lambda-style routes, use the `ObjectMapper` directly from the context:
+
+```java
+ObjectMapper mapper = app.ctx().require(ObjectMapper.class);
+
+app.get("/api/status", (req, res) -> {
+    res.setContentType(ContentType.JSON);
+    return mapper.writeValueAsString(Map.of("status", "ok"));
+});
+```
diff --git a/flash-extensions/flash-ext-jackson/pom.xml b/flash-extensions/flash-ext-jackson/pom.xml
new file mode 100644
index 0000000..0d0354f
--- /dev/null
+++ b/flash-extensions/flash-ext-jackson/pom.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.relism</groupId>
+        <artifactId>flash-extensions</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>flash-ext-jackson</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>dev.relism</groupId>
+            <artifactId>flash</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>
diff --git a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
new file mode 100644
index 0000000..0fc0bfd
--- /dev/null
+++ b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonExtension.java
@@ -0,0 +1,72 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.json.JsonMapper;
+import dev.relism.exceptions.HttpException;
+import dev.relism.extension.ExtensionContext;
+import dev.relism.extension.FlashApp;
+import dev.relism.extension.FlashExtension;
+import dev.relism.http.ContentType;
+
+/**
+ * Registers Jackson into the extension layer.
+ *
+ * <p>What this installs:
+ * <ul>
+ *   <li>Exposes the {@link ObjectMapper} in {@link ExtensionContext} — consumed by
+ *       {@code flash-ext-openapi} and any extension that needs JSON serialization.</li>
+ *   <li>Sets a global exception handler that maps {@link HttpException} to a JSON
+ *       error body and catches all other exceptions as 500.</li>
+ *   <li>Injects the mapper into {@link JacksonHandler} so all subclasses gain
+ *       {@code bodyAs} and {@code json} without constructor boilerplate.</li>
+ * </ul>
+ *
+ * <pre>{@code
+ * FlashApp.of(new HttpServer(config))
+ *     .install(new JacksonExtension());
+ *
+ * // Custom mapper:
+ * ObjectMapper mapper = JsonMapper.builder()
+ *     .addModule(new JavaTimeModule())
+ *     .build();
+ * .install(new JacksonExtension(mapper));
+ * }</pre>
+ */
+public class JacksonExtension implements FlashExtension {
+
+    private final ObjectMapper mapper;
+
+    public JacksonExtension() {
+        this(JsonMapper.builder().build());
+    }
+
+    public JacksonExtension(ObjectMapper mapper) {
+        this.mapper = mapper;
+    }
+
+    @Override
+    public void install(FlashApp app, ExtensionContext ctx) {
+        ctx.provide(ObjectMapper.class, mapper);
+        JacksonHandler.mapper = mapper;
+
+        app.onException((ex, req, res) -> {
+            if (ex instanceof HttpException e) {
+                res.setStatusCode(e.status());
+                res.setContentType(ContentType.JSON);
+                return "{\"error\":\"" + escapeJson(e.getMessage()) + "\"}";
+            }
+            res.setStatusCode(500);
+            res.setContentType(ContentType.JSON);
+            return "{\"error\":\"Internal Server Error\"}";
+        });
+    }
+
+    private static String escapeJson(String s) {
+        if (s == null) return "";
+        return s.replace("\\", "\\\\")
+                .replace("\"", "\\\"")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t");
+    }
+}
diff --git a/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonHandler.java b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonHandler.java
new file mode 100644
index 0000000..31c693d
--- /dev/null
+++ b/flash-extensions/flash-ext-jackson/src/main/java/dev/relism/ext/jackson/JacksonHandler.java
@@ -0,0 +1,77 @@
+package dev.relism.ext.jackson;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.relism.exceptions.HttpException;
+import dev.relism.http.ContentType;
+import dev.relism.models.Request;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.Response;
+
+/**
+ * Base class for handlers that need JSON I/O via Jackson.
+ *
+ * <p>The {@link ObjectMapper} is injected by {@link JacksonExtension#install} once at
+ * startup — all subclasses share the same instance. If no {@code JacksonExtension} is
+ * installed the field remains {@code null} and the first call to {@link #bodyAs} or
+ * {@link #json} will throw an {@link IllegalStateException}.
+ *
+ * <pre>{@code
+ * @Route(method = HttpMethod.POST, path = "/api/blogs")
+ * public class CreateBlog extends JacksonHandler {
+ *     public Object handle(Request req, Response res) throws Exception {
+ *         CreateBlogRequest body = bodyAs(req, CreateBlogRequest.class);
+ *         Blog created = service.create(body);
+ *         res.setStatusCode(201);
+ *         return json(res, created);
+ *     }
+ * }
+ * }</pre>
+ */
+public abstract class JacksonHandler extends RequestHandler {
+
+    /**
+     * Shared mapper set by {@link JacksonExtension}. Package-visible so the extension
+     * can assign it; {@code volatile} ensures visibility across virtual threads.
+     */
+    static volatile ObjectMapper mapper;
+
+    /**
+     * Deserializes the request body bytes into {@code type}.
+     * Wraps Jackson parse errors as {@link HttpException} 400.
+     */
+    protected <T> T bodyAs(Request req, Class<T> type) throws Exception {
+        requireMapper();
+        try {
+            return mapper.readValue(req.body().bytes(), type);
+        } catch (JsonProcessingException e) {
+            throw HttpException.badRequest("Invalid request body: " + e.getOriginalMessage());
+        }
+    }
+
+    /**
+     * Serializes {@code obj} to JSON, sets {@code Content-Type: application/json},
+     * and returns the JSON string as the response body.
+     */
+    protected String json(Response res, Object obj) throws Exception {
+        requireMapper();
+        res.setContentType(ContentType.JSON);
+        return mapper.writeValueAsString(obj);
+    }
+
+    /**
+     * Like {@link #json} but serializes only fields visible under the given
+     * {@code view} class (see Jackson {@code @JsonView}).
+     */
+    protected String jsonView(Response res, Object obj, Class<?> view) throws Exception {
+        requireMapper();
+        res.setContentType(ContentType.JSON);
+        return mapper.writerWithView(view).writeValueAsString(obj);
+    }
+
+    private static void requireMapper() {
+        if (mapper == null)
+            throw new IllegalStateException(
+                    "JacksonExtension not installed: call FlashApp.install(new JacksonExtension()) first");
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/README.md b/flash-extensions/flash-ext-oidc/README.md
new file mode 100644
index 0000000..004cad2
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/README.md
@@ -0,0 +1,352 @@
+# flash-ext-oidc
+
+Full OIDC Authorization Code + PKCE flow for the Flash HTTP server.
+Supports Keycloak, Authelia, Auth0, Google, and any RFC 8414-compliant provider.
+
+## What it provides
+
+| Component | Description |
+|---|---|
+| `GET  {prefix}/login` | Starts the OIDC flow: builds the authorization URL with PKCE + state, redirects |
+| `GET  {prefix}/callback` | Exchanges the code, validates the ID token, creates a session, redirects |
+| `POST {prefix}/logout` | Invalidates the session, redirects to the provider's `end_session_endpoint` |
+| `@Authenticated` | Annotation: protects a class-based handler (redirects browsers, 401 for API clients) |
+| `@RolesAllowed(...)` | Annotation: protects with role check (OR semantics) |
+| `OidcMiddleware` | Programmatic middleware for lambda routes |
+| `ClaimsHolder` / `OidcUser` | Thread-local user info accessible from any protected handler |
+| `JwtValidator` | JWKS-backed JWT validator (PKCE + key rotation + caching) |
+
+## Dependencies
+
+```xml
+<dependency>
+    <groupId>dev.relism</groupId>
+    <artifactId>flash-ext-oidc</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+Transitive: `nimbus-jose-jwt`, `json-smart`.
+Optional: `flash-ext-openapi` — if present, OIDC security schemes are added to the OpenAPI spec automatically.
+
+## Installation
+
+```java
+FlashApp.of(new HttpServer(config))
+    .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()
+    ));
+```
+
+### 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 |
+| `.algorithm("RS256")` | `"RS256"` | JWS algorithm for token validation |
+| `.postLogoutRedirectUri("/")` | `"/"` | Where to redirect after logout |
+| `.sessionStore(store)` | `InMemoryOidcSessionStore` | Custom session store (see below) |
+| `.clientAuthMethod(ClientAuthMethod.POST)` | `POST` | `POST` = credentials in body; `BASIC` = `Authorization: Basic` |
+| `.insecureTls()` | `false` | Disables TLS certificate verification — **development only** |
+| `.schemeName("myscheme")` | derived from issuer | OpenAPI security scheme name |
+
+### Environment variables (`OidcConfig.fromEnv()`)
+
+```
+OIDC_ISSUER                required
+OIDC_CLIENT_ID             required
+OIDC_CLIENT_SECRET         required
+OIDC_REDIRECT_URI          required   e.g. /auth/callback
+OIDC_SCOPES                default: openid profile email
+OIDC_ROUTE_PREFIX          default: /auth
+OIDC_SELF_SCHEME           default: http
+OIDC_ROLES_CLAIM           default: realm_access.roles
+OIDC_ALGORITHM             default: RS256
+OIDC_POST_LOGOUT_REDIRECT  default: /
+OIDC_CLIENT_AUTH_METHOD    default: POST
+```
+
+## Protecting routes
+
+### Class-based handlers (annotations)
+
+```java
+@Route(method = HttpMethod.GET, path = "/me")
+@Authenticated
+public class MePage extends JacksonHandler {
+    @Override
+    public Object handle(Request req, Response res) {
+        OidcUser u = ClaimsHolder.user();
+        return json(res, Map.of("sub", u.sub(), "email", u.email()));
+    }
+}
+
+@Route(method = HttpMethod.GET, path = "/admin")
+@RolesAllowed("admin")           // OR semantics: "admin" OR "superuser"
+// @RolesAllowed({"admin", "superuser"})
+public class AdminPage extends JacksonHandler { ... }
+```
+
+The middleware is injected automatically by the annotation processor — no manual wiring needed.
+
+### Lambda routes (manual middleware)
+
+For lambda routes you must apply the middleware explicitly. Retrieve it from the context
+after `install()` completes:
+
+```java
+OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
+
+// Authentication only
+app.get("/api/me", (req, res) -> {
+    OidcUser u = ClaimsHolder.user();   // never null here
+    return Map.of("sub", u.sub(), "email", u.email());
+}, oidc.protect());
+
+// Authentication + role check
+app.delete("/api/admin/users/{id}", (req, res) -> {
+    OidcUser u = ClaimsHolder.user();
+    // ...
+}, oidc.requireRole("admin"));
+
+// Multiple roles (OR): passes if user holds any one of them
+app.get("/api/reports", (req, res) -> { ... },
+    oidc.requireRole("admin", "reports-viewer"));
+```
+
+`oidc.protect()` / `oidc.requireRole(...)` return a `Middleware` — a composable
+`Handler -> Handler` wrapper. Flash applies middleware right-to-left so the OIDC check
+runs before your handler.
+
+## Accessing the authenticated user
+
+`ClaimsHolder` holds the JWT claims for the current request in a `ThreadLocal`.
+It is populated by the OIDC middleware before your handler runs and cleared in the
+`finally` block afterward. It is safe with virtual threads (each request gets its
+own virtual thread, so `ThreadLocal` values are naturally isolated).
+
+### OidcUser (preferred)
+
+```java
+OidcUser u = ClaimsHolder.user();   // never null inside a protected handler
+
+String sub      = u.sub();          // unique user ID
+String email    = u.email();
+String username = u.username();     // preferred_username
+String name     = u.name();         // full display name
+
+// Roles — pass the dot-path matching your provider's claim structure
+List<String> roles = u.roles("realm_access.roles");   // Keycloak realm roles
+List<String> clientRoles = u.roles("resource_access.my-client.roles"); // Keycloak client roles
+List<String> groups = u.roles("groups");              // Authelia
+
+boolean isAdmin = u.hasRole("realm_access.roles", "admin");
+
+// Arbitrary claim
+String locale = (String) u.claim("locale");
+Long   exp    = u.claim("exp", Long.class);
+
+// Full raw map (escape hatch)
+Map<String, Object> all = u.claims();
+```
+
+### Raw access (escape hatch)
+
+```java
+Map<String, Object> claims = ClaimsHolder.get();
+String email = ClaimsHolder.claim("email");
+```
+
+## Performance
+
+The middleware adds negligible overhead on the hot path for authenticated requests:
+
+| Step | Cost |
+|---|---|
+| `Authorization` header check | `O(1)` map lookup |
+| Cookie parse | `O(cookie_count)` string split |
+| 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.
+
+## Authentication flow details
+
+On each request the middleware resolves credentials in this order:
+
+1. **Bearer token** (`Authorization: Bearer <jwt>`) — validated against JWKS.
+2. **Session cookie** (`oidc_session`) — looked up in the session store; transparently
+   refreshed if the access token is expired (silent refresh via refresh token).
+3. **No valid credentials**:
+   - Browser clients (no `Accept: application/json`) → redirect to `{prefix}/login?redirect={path}`
+   - API clients → `401 Unauthorized`
+
+### 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.
+
+## Session store
+
+The default `InMemoryOidcSessionStore` is sufficient for single-instance deployments.
+For clustered deployments, implement `OidcSessionStore`:
+
+```java
+public interface OidcSessionStore {
+    void              save(OidcSession session);
+    Optional<OidcSession> find(String sessionId);
+    void              delete(String sessionId);
+}
+```
+
+```java
+OidcConfig.builder(...)
+    .sessionStore(new RedisOidcSessionStore(redisClient))
+    .build()
+```
+
+`OidcSession` fields: `id`, `accessToken`, `idToken`, `refreshToken`, `expiresAt` (`Instant`), `claims` (merged map).
+
+## Logout
+
+Add a logout button anywhere in your UI — a `<form>` is sufficient (no JavaScript needed):
+
+```html
+<form method="POST" action="/auth/logout">
+    <button type="submit">Logout</button>
+</form>
+```
+
+The `POST {prefix}/logout` handler:
+1. Reads the `oidc_session` cookie, looks up the session, retrieves the `id_token`.
+2. Deletes the local session and clears the cookie (`Max-Age=0`).
+3. If the provider has an `end_session_endpoint` (standard IdPs do), redirects there with
+   `?id_token_hint=<idToken>&post_logout_redirect_uri=<postLogoutRedirectUri>` — this logs
+   the user out of the IdP as well.
+4. Otherwise redirects to `postLogoutRedirectUri` (default: `/`).
+
+## Bearer token (API clients)
+
+For API-to-API or SPA-to-API calls, pass a Bearer access token directly. The middleware
+validates the JWT signature against JWKS and extracts the claims — no session involved:
+
+```
+Authorization: Bearer <access_token>
+```
+
+The token must be a JWT (opaque tokens are not supported). Claims are available via
+`ClaimsHolder.user()` as usual.
+
+## Multi-tenant
+
+Multiple OIDC providers on one server — each `OidcExtension` instance is fully independent
+(its own PKCE state store, session store, validator, and middleware):
+
+```java
+OidcConfig tenantA = OidcConfig.builder("https://idp/realms/a", "clientA", "secretA", "/a/auth/callback")
+    .routePrefix("/a/auth").schemeName("tenantA").build();
+
+OidcConfig tenantB = OidcConfig.builder("https://idp/realms/b", "clientB", "secretB", "/b/auth/callback")
+    .routePrefix("/b/auth").schemeName("tenantB").build();
+
+app.install(new OidcExtension(tenantA))
+   .install(new OidcExtension(tenantB));
+```
+
+To reference a specific tenant's middleware on lambda routes, keep the extension reference
+and retrieve `OidcMiddleware` from context **after** each install:
+
+```java
+app.install(new OidcExtension(tenantA));
+OidcMiddleware mwA = app.ctx().require(OidcMiddleware.class);   // tenantA's middleware
+
+app.install(new OidcExtension(tenantB));
+OidcMiddleware mwB = app.ctx().require(OidcMiddleware.class);   // tenantB's middleware
+
+app.get("/a/dashboard", (req, res) -> { ... }, mwA.protect());
+app.get("/b/dashboard", (req, res) -> { ... }, mwB.protect());
+```
+
+Class-based handlers annotated with `@Authenticated` / `@RolesAllowed` get the last
+registered middleware injected. For multi-tenant class-based handlers, use lambdas or
+install tenant-specific annotation processors.
+
+## OpenAPI integration
+
+If `flash-ext-openapi` is on the classpath and installed **before** `flash-ext-oidc`,
+the extension automatically:
+
+- Adds a `components.securitySchemes` entry for the provider (OAuth2, authorizationCode flow)
+- Adds `security` requirements to every operation whose handler carries `@Authenticated`
+  or `@RolesAllowed`
+
+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-oidc/pom.xml b/flash-extensions/flash-ext-oidc/pom.xml
new file mode 100644
index 0000000..c705d1c
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/pom.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.relism</groupId>
+        <artifactId>flash-extensions</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>flash-ext-oidc</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>dev.relism</groupId>
+            <artifactId>flash</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>dev.relism</groupId>
+            <artifactId>flash-ext-openapi</artifactId>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>com.nimbusds</groupId>
+            <artifactId>nimbus-jose-jwt</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>net.minidev</groupId>
+            <artifactId>json-smart</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/Authenticated.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/Authenticated.java
new file mode 100644
index 0000000..812a9b2
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/Authenticated.java
@@ -0,0 +1,23 @@
+package dev.relism.ext.oidc;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a handler as requiring a valid JWT. Any bearer token that passes
+ * signature + expiry + issuer validation is accepted — no role check is performed.
+ *
+ * <p>For role-based access use {@link RolesAllowed} instead (it implies authentication).
+ *
+ * <pre>{@code
+ * @Route(method = HttpMethod.GET, path = "/api/profile")
+ * @Authenticated
+ * public class GetProfile extends JacksonHandler { ... }
+ * }</pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Authenticated {
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClaimsHolder.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClaimsHolder.java
new file mode 100644
index 0000000..d5debdb
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClaimsHolder.java
@@ -0,0 +1,71 @@
+package dev.relism.ext.oidc;
+
+import java.util.Map;
+
+/**
+ * Thread-local store for JWT claims, populated by the OIDC middleware before
+ * the handler runs and cleared in the {@code finally} block afterward.
+ *
+ * <p>Safe with virtual threads: each request gets its own virtual thread, so
+ * {@link ThreadLocal} values are naturally isolated per request.
+ *
+ * <pre>{@code
+ * // Inside any handler protected by @Authenticated or @RolesAllowed:
+ *
+ * // Preferred — typed wrapper:
+ * OidcUser user = ClaimsHolder.user();
+ * String email  = user.email();
+ * List<String> roles = user.roles("realm_access.roles");
+ *
+ * // Raw escape hatch:
+ * Map<String, Object> all = ClaimsHolder.get();
+ * }</pre>
+ */
+public final class ClaimsHolder {
+
+    private static final ThreadLocal<Map<String, Object>> HOLDER = new ThreadLocal<>();
+
+    private ClaimsHolder() {}
+
+    /** Called by the OIDC middleware after successful token validation. */
+    static void set(Map<String, Object> claims) {
+        HOLDER.set(claims);
+    }
+
+    /** Called by the OIDC middleware in the {@code finally} block. */
+    static void clear() {
+        HOLDER.remove();
+    }
+
+    /**
+     * Returns a type-safe {@link OidcUser} view of the current request's claims,
+     * or {@code null} if the route is not protected by OIDC middleware.
+     *
+     * <p>This is the preferred entry point for both lambda and class-based handlers.
+     */
+    public static OidcUser user() {
+        Map<String, Object> claims = HOLDER.get();
+        return claims != null ? new OidcUser(claims) : null;
+    }
+
+    /**
+     * Returns the raw claims map for the current request, or {@code null} if
+     * the route is not protected by OIDC middleware.
+     *
+     * @see #user() for the preferred type-safe accessor
+     */
+    public static Map<String, Object> get() {
+        return HOLDER.get();
+    }
+
+    /**
+     * Returns the value of a single claim as a String, or {@code null} if
+     * the claim is absent or the request is not authenticated.
+     */
+    public static String claim(String key) {
+        Map<String, Object> claims = HOLDER.get();
+        if (claims == null) return null;
+        Object v = claims.get(key);
+        return v != null ? v.toString() : null;
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClientAuthMethod.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClientAuthMethod.java
new file mode 100644
index 0000000..9e4510a
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/ClientAuthMethod.java
@@ -0,0 +1,18 @@
+package dev.relism.ext.oidc;
+
+/**
+ * OAuth2 client authentication method for the token endpoint (RFC 6749 §2.3).
+ *
+ * <ul>
+ *   <li>{@link #POST} — credentials sent as {@code client_id} / {@code client_secret}
+ *       form fields (default; most providers).</li>
+ *   <li>{@link #BASIC} — credentials sent as an {@code Authorization: Basic} header;
+ *       body contains only grant-specific parameters.</li>
+ * </ul>
+ */
+public enum ClientAuthMethod {
+    /** {@code client_secret_post} — credentials in the request body. */
+    POST,
+    /** {@code client_secret_basic} — credentials in the {@code Authorization} header. */
+    BASIC
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/DiscoveryClient.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/DiscoveryClient.java
new file mode 100644
index 0000000..8349f7f
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/DiscoveryClient.java
@@ -0,0 +1,50 @@
+package dev.relism.ext.oidc;
+
+import net.minidev.json.JSONValue;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.Map;
+
+/**
+ * Fetches and parses the OIDC provider discovery document at
+ * {@code {issuer}/.well-known/openid-configuration}.
+ */
+final class DiscoveryClient {
+
+    private DiscoveryClient() {}
+
+    static OidcProviderMetadata fetch(String issuer, HttpClient http) throws Exception {
+        String url = issuer.endsWith("/")
+                ? issuer + ".well-known/openid-configuration"
+                : issuer + "/.well-known/openid-configuration";
+
+        HttpResponse<String> resp = http.send(
+                HttpRequest.newBuilder().uri(URI.create(url)).GET().build(),
+                HttpResponse.BodyHandlers.ofString());
+
+        if (resp.statusCode() != 200)
+            throw new IllegalStateException(
+                    "OIDC discovery failed [" + resp.statusCode() + "]: " + url);
+
+        @SuppressWarnings("unchecked")
+        Map<String, Object> doc = (Map<String, Object>) JSONValue.parse(resp.body());
+
+        return new OidcProviderMetadata(
+                require(doc, "authorization_endpoint"),
+                require(doc, "token_endpoint"),
+                (String) doc.get("userinfo_endpoint"),      // optional
+                require(doc, "jwks_uri"),
+                (String) doc.get("end_session_endpoint")    // optional
+        );
+    }
+
+    private static String require(Map<String, Object> doc, String key) {
+        Object v = doc.get(key);
+        if (v == null) throw new IllegalStateException(
+                "Discovery doc missing required field: " + key);
+        return v.toString();
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/InMemoryOidcSessionStore.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/InMemoryOidcSessionStore.java
new file mode 100644
index 0000000..f5af0bb
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/InMemoryOidcSessionStore.java
@@ -0,0 +1,20 @@
+package dev.relism.ext.oidc;
+
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Thread-safe in-memory {@link OidcSessionStore}.
+ *
+ * <p>Sessions are lost on restart and not shared across instances. For
+ * production deployments with multiple nodes or restart-persistence requirements,
+ * supply a custom implementation via {@link OidcConfig.Builder#sessionStore}.
+ */
+public final class InMemoryOidcSessionStore implements OidcSessionStore {
+
+    private final ConcurrentHashMap<String, OidcSession> store = new ConcurrentHashMap<>();
+
+    @Override public void             save(OidcSession s)  { store.put(s.id(), s); }
+    @Override public Optional<OidcSession> find(String id) { return Optional.ofNullable(store.get(id)); }
+    @Override public void             delete(String id)    { store.remove(id); }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtUtils.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtUtils.java
new file mode 100644
index 0000000..627ed47
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtUtils.java
@@ -0,0 +1,38 @@
+package dev.relism.ext.oidc;
+
+import net.minidev.json.JSONValue;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.Map;
+
+/**
+ * Low-level JWT payload extraction — no signature or expiry validation.
+ *
+ * <p>Use only for tokens received directly from the provider over a trusted TLS
+ * connection (e.g. {@code id_token} from the token endpoint). Bearer tokens on
+ * incoming requests must go through {@link JwtValidator#validate(String)} instead.
+ */
+final class JwtUtils {
+
+    private JwtUtils() {}
+
+    /**
+     * Base64URL-decodes the JWT payload and returns the claims as a map.
+     * Signature, expiry, and issuer are NOT checked.
+     */
+    @SuppressWarnings("unchecked")
+    static Map<String, Object> parseClaims(String jwt) {
+        String[] parts = jwt.split("\\.");
+        if (parts.length < 2) throw new IllegalArgumentException("Malformed JWT: " + jwt);
+        // Pad to a multiple of 4 for the standard decoder
+        String padded = parts[1];
+        switch (padded.length() % 4) {
+            case 2 -> padded += "==";
+            case 3 -> padded += "=";
+        }
+        byte[] payload = Base64.getUrlDecoder().decode(padded);
+        return (Map<String, Object>) JSONValue.parse(
+                new String(payload, StandardCharsets.UTF_8));
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtValidator.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtValidator.java
new file mode 100644
index 0000000..b0c1ce1
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/JwtValidator.java
@@ -0,0 +1,184 @@
+package dev.relism.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.exceptions.HttpException;
+
+import java.io.IOException;
+import java.net.URL;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Validates JWTs against a remote JWKS endpoint using Nimbus JOSE+JWT.
+ *
+ * <p>Two validation modes:
+ * <ul>
+ *   <li>{@link #validate(String)} — access token bearer validation per request (hot path).
+ *       Checks signature, {@code iss}, {@code exp}, {@code iat}, {@code sub}.
+ *       Throws {@link HttpException} 401 so the middleware can short-circuit.</li>
+ *   <li>{@link #validateIdToken(String, String)} — ID token validation at callback time.
+ *       Checks signature, {@code iss}, {@code aud} == clientId, {@code exp}, {@code iat},
+ *       {@code sub}, and {@code nonce} (if provided).
+ *       Throws {@link OidcValidationException} (not 401 — it is a provider/protocol error).</li>
+ * </ul>
+ *
+ * <p>JWKS handling: the shared {@link JWKSource} uses caching + rate-limiting + automatic
+ * retry-on-key-miss (key rotation). Both processors share the same source — one JWKS
+ * fetch serves both token types.
+ */
+public class JwtValidator {
+
+    private final JWKSource<SecurityContext>                 jwkSource;
+    private final ConfigurableJWTProcessor<SecurityContext>  accessTokenProcessor;
+    private final ConfigurableJWTProcessor<SecurityContext>  idTokenProcessor;
+    private final String                                     algorithm;
+
+    /**
+     * @param jwksUri   JWKS endpoint URI
+     * @param issuer    Expected {@code iss} claim
+     * @param clientId  OAuth2 client ID — used as expected {@code aud} in ID tokens
+     * @param algorithm JWS algorithm (e.g. {@code "RS256"})
+     * @param http      Shared {@link HttpClient} used for all JWKS fetches — already configured
+     *                  with the correct TLS policy (trust-all or default trust store).
+     */
+    public JwtValidator(String jwksUri, String issuer, String clientId,
+                        String algorithm, HttpClient http) {
+        try {
+            // Use the caller-supplied HttpClient for JWKS retrieval so that TLS policy
+            // (insecureTls / custom trust store) is applied consistently everywhere.
+            this.jwkSource = JWKSourceBuilder
+                    .create(new URL(jwksUri), httpRetriever(http))
+                    .cache(true)
+                    .rateLimited(true)
+                    .retrying(true)
+                    .build();
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to init JWKS source: " + jwksUri, e);
+        }
+        this.algorithm            = algorithm;
+        this.accessTokenProcessor = buildAccessTokenProcessor(jwkSource, issuer, algorithm);
+        this.idTokenProcessor     = buildIdTokenProcessor(jwkSource, issuer, clientId, algorithm);
+    }
+
+    // -- Public API -----------------------------------------------------------
+
+    /**
+     * Validates a JWT access token (bearer on incoming request).
+     * Returns claims on success; throws {@link HttpException} 401 on any failure.
+     */
+    public Map<String, Object> validate(String token) {
+        if (!isJwt(token)) throw HttpException.unauthorized();   // opaque token — can't validate
+        try {
+            return accessTokenProcessor.process(token, null).getClaims();
+        } catch (Exception e) {
+            throw HttpException.unauthorized();
+        }
+    }
+
+    /**
+     * Validates an ID token received directly from the token endpoint.
+     *
+     * <p>Checks: signature (JWKS), {@code iss}, {@code aud} == clientId,
+     * {@code exp}, {@code iat}, {@code sub}, and {@code nonce} if provided.
+     *
+     * @param idToken  Raw ID token string
+     * @param nonce    Nonce sent in the authorization request; {@code null} to skip check
+     * @throws OidcValidationException on any validation failure
+     */
+    public Map<String, Object> validateIdToken(String idToken, String nonce) {
+        try {
+            Map<String, Object> claims = idTokenProcessor.process(idToken, null).getClaims();
+            if (nonce != null && !nonce.equals(claims.get("nonce")))
+                throw new OidcValidationException("ID token nonce mismatch", null);
+            return claims;
+        } catch (OidcValidationException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new OidcValidationException("ID token validation failed: " + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Returns {@code true} if {@code token} is a signed JWT (three dot-separated Base64URL parts).
+     * Used to detect opaque access tokens before attempting JWKS validation.
+     */
+    public static boolean isJwt(String token) {
+        if (token == null || token.isBlank()) return false;
+        int dots = 0;
+        for (int i = 0; i < token.length(); i++) if (token.charAt(i) == '.') dots++;
+        return dots == 2;
+    }
+
+    // -- Processors -----------------------------------------------------------
+
+    private static ConfigurableJWTProcessor<SecurityContext> buildAccessTokenProcessor(
+            JWKSource<SecurityContext> src, String issuer, String algorithm) {
+
+        ConfigurableJWTProcessor<SecurityContext> p = new DefaultJWTProcessor<>();
+        p.setJWSKeySelector(keySelector(src, algorithm));
+        // iss required; aud not enforced on ATs (varies by provider)
+        if (issuer != null && !issuer.isBlank()) {
+            p.setJWTClaimsSetVerifier(new DefaultJWTClaimsVerifier<>(
+                    new JWTClaimsSet.Builder().issuer(issuer).build(),
+                    Set.of("sub", "iat", "exp")));
+        }
+        return p;
+    }
+
+    private static ConfigurableJWTProcessor<SecurityContext> buildIdTokenProcessor(
+            JWKSource<SecurityContext> src, String issuer, String clientId, String algorithm) {
+
+        ConfigurableJWTProcessor<SecurityContext> p = new DefaultJWTProcessor<>();
+        p.setJWSKeySelector(keySelector(src, algorithm));
+        // iss + aud = clientId strictly required (OIDC Core §3.1.3.7)
+        JWTClaimsSet.Builder required = new JWTClaimsSet.Builder();
+        if (issuer   != null) required.issuer(issuer);
+        if (clientId != null) required.audience(clientId);
+        p.setJWTClaimsSetVerifier(new DefaultJWTClaimsVerifier<>(
+                required.build(), Set.of("sub", "iat", "exp")));
+        return p;
+    }
+
+    private static JWSKeySelector<SecurityContext> keySelector(
+            JWKSource<SecurityContext> src, String algorithm) {
+        return new JWSVerificationKeySelector<>(JWSAlgorithm.parse(algorithm), src);
+    }
+
+    /**
+     * Wraps a {@link HttpClient} as a Nimbus {@link ResourceRetriever}.
+     * The client already carries the correct TLS policy (trust-all or default),
+     * so JWKS fetches honour the same SSL configuration as discovery and token requests.
+     */
+    private static ResourceRetriever httpRetriever(HttpClient http) {
+        return url -> {
+            try {
+                HttpResponse<String> resp = http.send(
+                        HttpRequest.newBuilder().uri(url.toURI()).GET().build(),
+                        HttpResponse.BodyHandlers.ofString());
+                if (resp.statusCode() != 200)
+                    throw new IOException("JWKS fetch failed [" + resp.statusCode() + "]: " + url);
+                String contentType = resp.headers()
+                        .firstValue("Content-Type").orElse("application/json");
+                return new Resource(resp.body(), contentType);
+            } catch (IOException e) {
+                throw e;
+            } catch (Exception e) {
+                throw new IOException("JWKS retrieval error: " + e.getMessage(), e);
+            }
+        };
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
new file mode 100644
index 0000000..c8e0390
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcConfig.java
@@ -0,0 +1,250 @@
+package dev.relism.ext.oidc;
+
+/**
+ * Full OIDC client configuration. Build via
+ * {@link #builder(String, String, String, String)} or {@link #fromEnv()}.
+ *
+ * <p>Required fields: {@code issuer}, {@code clientId}, {@code clientSecret},
+ * {@code redirectUri}. Everything else has a sensible default.
+ *
+ * <p>If {@code redirectUri} starts with {@code /} it is treated as server-relative:
+ * the absolute URL is resolved at request time using {@link #selfScheme()} and the
+ * incoming {@code Host} header. Use {@link Builder#https()} when behind TLS.
+ *
+ * <pre>{@code
+ * // Keycloak
+ * OidcConfig.builder(
+ *         "https://keycloak.example.com/realms/myrealm",
+ *         "my-app", "secret", "/auth/callback")
+ *     .rolesClaimPath("realm_access.roles")   // Keycloak default
+ *     .build();
+ *
+ * // Authelia
+ * OidcConfig.builder(
+ *         "https://auth.example.com",
+ *         "my-app", "secret", "/auth/callback")
+ *     .rolesClaimPath("groups")
+ *     .build();
+ *
+ * // Two tenants on one server
+ * OidcConfig tenantA = OidcConfig.builder("https://idp/realms/a", ..., "/tenantA/auth/callback")
+ *     .routePrefix("/tenantA/auth").build();
+ * OidcConfig tenantB = OidcConfig.builder("https://idp/realms/b", ..., "/tenantB/auth/callback")
+ *     .routePrefix("/tenantB/auth").build();
+ * app.install(new OidcExtension(tenantA))
+ *    .install(new OidcExtension(tenantB));
+ * }</pre>
+ */
+public final class OidcConfig {
+
+    private final String           issuer;
+    private final String           clientId;
+    private final String           clientSecret;
+    private final String           redirectUri;
+    private final String           scopes;
+    private final String           routePrefix;
+    private final String           selfScheme;
+    private final String           rolesClaimPath;
+    private final String           algorithm;
+    private final String           postLogoutRedirectUri;
+    private final OidcSessionStore sessionStore;
+    private final boolean          insecureTls;
+    private final ClientAuthMethod clientAuthMethod;
+    private final String           schemeName;
+
+    private OidcConfig(Builder b) {
+        this.issuer                = require(b.issuer,       "issuer");
+        this.clientId              = require(b.clientId,     "clientId");
+        this.clientSecret          = require(b.clientSecret, "clientSecret");
+        this.redirectUri           = require(b.redirectUri,  "redirectUri");
+        this.scopes                = b.scopes;
+        this.routePrefix           = b.routePrefix;
+        this.selfScheme            = b.selfScheme;
+        this.rolesClaimPath        = b.rolesClaimPath;
+        this.algorithm             = b.algorithm;
+        this.postLogoutRedirectUri = b.postLogoutRedirectUri;
+        this.sessionStore          = b.sessionStore != null ? b.sessionStore
+                                                            : new InMemoryOidcSessionStore();
+        this.insecureTls           = b.insecureTls;
+        this.clientAuthMethod      = b.clientAuthMethod;
+        this.schemeName            = b.schemeName != null ? b.schemeName : deriveScheme(this.issuer);
+    }
+
+    // -- Getters --------------------------------------------------------------
+
+    public String           issuer()                { return issuer; }
+    public String           clientId()              { return clientId; }
+    public String           clientSecret()          { return clientSecret; }
+    public String           redirectUri()           { return redirectUri; }
+    public String           scopes()                { return scopes; }
+    public String           routePrefix()           { return routePrefix; }
+    public String           selfScheme()            { return selfScheme; }
+    public String           rolesClaimPath()        { return rolesClaimPath; }
+    public String           algorithm()             { return algorithm; }
+    public String           postLogoutRedirectUri() { return postLogoutRedirectUri; }
+    public OidcSessionStore sessionStore()          { return sessionStore; }
+    /** If {@code true}, TLS certificate validation is skipped. <b>Never use in production.</b> */
+    public boolean          insecureTls()           { return insecureTls; }
+    public ClientAuthMethod clientAuthMethod()       { return clientAuthMethod; }
+    /** OpenAPI security scheme name (derived from issuer if not set explicitly). */
+    public String           schemeName()            { return schemeName; }
+
+    // -- Factory --------------------------------------------------------------
+
+    /**
+     * Reads configuration from environment variables:
+     * <pre>
+     * OIDC_ISSUER               required
+     * OIDC_CLIENT_ID            required
+     * OIDC_CLIENT_SECRET        required
+     * OIDC_REDIRECT_URI         required  (e.g. /auth/callback)
+     * OIDC_SCOPES               default: openid profile email
+     * OIDC_ROUTE_PREFIX         default: /auth
+     * OIDC_SELF_SCHEME          default: http
+     * OIDC_ROLES_CLAIM          default: realm_access.roles
+     * OIDC_ALGORITHM            default: RS256
+     * OIDC_POST_LOGOUT_REDIRECT default: /
+     * </pre>
+     */
+    public static OidcConfig fromEnv() {
+        return builder(env("OIDC_ISSUER"), env("OIDC_CLIENT_ID"),
+                       env("OIDC_CLIENT_SECRET"), env("OIDC_REDIRECT_URI"))
+                .scopes               (envOr("OIDC_SCOPES",               "openid profile email"))
+                .routePrefix          (envOr("OIDC_ROUTE_PREFIX",          "/auth"))
+                .selfScheme           (envOr("OIDC_SELF_SCHEME",           "http"))
+                .rolesClaimPath       (envOr("OIDC_ROLES_CLAIM",           "realm_access.roles"))
+                .algorithm            (envOr("OIDC_ALGORITHM",             "RS256"))
+                .postLogoutRedirectUri(envOr("OIDC_POST_LOGOUT_REDIRECT",  "/"))
+                .clientAuthMethod(ClientAuthMethod.valueOf(
+                        envOr("OIDC_CLIENT_AUTH_METHOD", "POST").toUpperCase()))
+                .build();
+    }
+
+    public static Builder builder(String issuer, String clientId,
+                                  String clientSecret, String redirectUri) {
+        return new Builder(issuer, clientId, clientSecret, redirectUri);
+    }
+
+    /**
+     * Convenience factory for Keycloak: constructs the issuer as
+     * {@code {serverUrl}/realms/{realm}} automatically.
+     *
+     * <pre>{@code
+     * OidcConfig.keycloak(
+     *     "https://keycloak.example.com", "flashboard",
+     *     "my-app", "secret", "/auth/callback")
+     *   .https()
+     *   .build();
+     * }</pre>
+     */
+    public static Builder keycloak(String serverUrl, String realm,
+                                   String clientId, String clientSecret,
+                                   String redirectUri) {
+        String base   = serverUrl.endsWith("/") ? serverUrl.substring(0, serverUrl.length() - 1) : serverUrl;
+        String issuer = base + "/realms/" + realm;
+        return new Builder(issuer, clientId, clientSecret, redirectUri)
+                .rolesClaimPath("realm_access.roles");   // Keycloak default
+    }
+
+    // -- Helpers --------------------------------------------------------------
+
+    private static String require(String v, String name) {
+        if (v == null || v.isBlank())
+            throw new IllegalArgumentException("OidcConfig: " + name + " is required");
+        return v;
+    }
+
+    private static String env(String key) {
+        String v = System.getenv(key);
+        if (v == null || v.isBlank())
+            throw new IllegalArgumentException("Missing required env var: " + key);
+        return v;
+    }
+
+    private static String envOr(String key, String def) {
+        String v = System.getenv(key);
+        return (v != null && !v.isBlank()) ? v : def;
+    }
+
+    // -- Builder --------------------------------------------------------------
+
+    public static final class Builder {
+
+        private final String issuer;
+        private final String clientId;
+        private final String clientSecret;
+        private final String redirectUri;
+
+        private String           scopes                = "openid profile email";
+        private String           routePrefix           = "/auth";
+        private String           selfScheme            = "http";
+        private String           rolesClaimPath        = "realm_access.roles";
+        private String           algorithm             = "RS256";
+        private String           postLogoutRedirectUri = "/";
+        private OidcSessionStore sessionStore;
+        private boolean          insecureTls           = false;
+        private ClientAuthMethod clientAuthMethod       = ClientAuthMethod.POST;
+        private String           schemeName            = null;
+
+        private Builder(String issuer, String clientId, String clientSecret, String redirectUri) {
+            this.issuer       = issuer;
+            this.clientId     = clientId;
+            this.clientSecret = clientSecret;
+            this.redirectUri  = redirectUri;
+        }
+
+        /** Override requested scopes (default: {@code openid profile email}). */
+        public Builder scopes(String scopes)                        { this.scopes = scopes;                               return this; }
+        /** Route prefix for login/callback/logout (default: {@code /auth}). */
+        public Builder routePrefix(String prefix)                   { this.routePrefix = prefix;                          return this; }
+        /** Scheme used when resolving self-relative redirect URIs (default: {@code http}). */
+        public Builder selfScheme(String scheme)                    { this.selfScheme = scheme;                           return this; }
+        /** Shorthand for {@code selfScheme("https")}. */
+        public Builder https()                                      { return selfScheme("https"); }
+        /** Dot-separated path to the roles array in JWT claims (default: {@code realm_access.roles}). */
+        public Builder rolesClaimPath(String path)                  { this.rolesClaimPath = path;                         return this; }
+        /** JWS algorithm (default: {@code RS256}). */
+        public Builder algorithm(String algorithm)                  { this.algorithm = algorithm;                         return this; }
+        /** Where to redirect after logout (default: {@code /}). */
+        public Builder postLogoutRedirectUri(String uri)            { this.postLogoutRedirectUri = uri;                   return this; }
+        /** Custom session store (default: {@link InMemoryOidcSessionStore}). */
+        public Builder sessionStore(OidcSessionStore store)         { this.sessionStore = store;                          return this; }
+        /**
+         * Disables TLS certificate verification for all HTTP calls made by this extension.
+         * <b>Only use in development with self-signed certificates — never in production.</b>
+         */
+        public Builder insecureTls()                                { this.insecureTls = true;                            return this; }
+        /** Token endpoint client authentication method (default: {@link ClientAuthMethod#POST}). */
+        public Builder clientAuthMethod(ClientAuthMethod method)    { this.clientAuthMethod = method;                     return this; }
+        /** Override the OpenAPI security scheme name (default: derived from the issuer URI). */
+        public Builder schemeName(String name)                      { this.schemeName = name;                             return this; }
+
+        public OidcConfig build() { return new OidcConfig(this); }
+    }
+
+    /**
+     * Derives a short, human-readable scheme name from the issuer URI.
+     * Takes the last non-empty path segment; falls back to the host.
+     *
+     * <p>Examples:
+     * <ul>
+     *   <li>{@code https://keycloak.dev.home/realms/flashboard} → {@code "flashboard"}</li>
+     *   <li>{@code https://auth.example.com}                    → {@code "auth.example.com"}</li>
+     * </ul>
+     */
+    private static String deriveScheme(String issuer) {
+        try {
+            java.net.URI uri = new java.net.URI(issuer);
+            String path = uri.getPath();
+            if (path != null && !path.isEmpty()) {
+                String[] parts = path.split("/");
+                for (int i = parts.length - 1; i >= 0; i--) {
+                    if (!parts[i].isEmpty()) return parts[i];
+                }
+            }
+            return uri.getHost();
+        } catch (Exception e) {
+            return "oidc";
+        }
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
new file mode 100644
index 0000000..743047c
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcExtension.java
@@ -0,0 +1,340 @@
+package dev.relism.ext.oidc;
+
+import dev.relism.extension.ExtensionContext;
+import dev.relism.extension.FlashApp;
+import dev.relism.extension.FlashExtension;
+
+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.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * Full OIDC Authorization Code + PKCE flow for Flash.
+ *
+ * <p>On {@link #install}, the extension:
+ * <ol>
+ *   <li>Fetches the provider discovery document — fail-fast at startup.</li>
+ *   <li>Registers three routes on the {@link FlashApp}:
+ *     <ul>
+ *       <li>{@code GET  {prefix}/login}    — builds the authorization URL and redirects.</li>
+ *       <li>{@code GET  {prefix}/callback} — exchanges the code, creates a session, redirects.</li>
+ *       <li>{@code POST {prefix}/logout}   — invalidates the session, redirects to the provider's
+ *           end-session endpoint (if available) or to {@link OidcConfig#postLogoutRedirectUri()}.</li>
+ *     </ul>
+ *   </li>
+ *   <li>Provides {@link OidcMiddleware} and {@link JwtValidator} in the context.</li>
+ *   <li>Registers an annotation processor for {@link Authenticated} and {@link RolesAllowed}.</li>
+ * </ol>
+ *
+ * <pre>{@code
+ * // Keycloak
+ * app.install(new OidcExtension(
+ *     OidcConfig.builder(
+ *             "https://keycloak.example.com/realms/myrealm",
+ *             "my-app", "secret", "/auth/callback")
+ *         .rolesClaimPath("realm_access.roles")
+ *         .build()));
+ *
+ * // Two providers / tenants on one server
+ * app.install(new OidcExtension(tenantAConfig))
+ *    .install(new OidcExtension(tenantBConfig));
+ * }</pre>
+ */
+public class OidcExtension implements FlashExtension {
+
+    private final OidcConfig config;
+
+    public OidcExtension(OidcConfig config) {
+        this.config = config;
+    }
+
+    @Override
+    public void install(FlashApp app, ExtensionContext ctx) {
+
+        // 1. Build the shared HttpClient (optionally with TLS verification disabled)
+        HttpClient http = buildHttpClient(config);
+
+        // 2. Discover provider endpoints (blocking; fail fast at startup)
+        OidcProviderMetadata meta;
+        try {
+            meta = DiscoveryClient.fetch(config.issuer(), http);
+        } catch (Exception e) {
+            throw new IllegalStateException(
+                    "OIDC discovery failed for issuer: " + config.issuer(), e);
+        }
+
+        // 3. JWKS-backed access-token validator
+        JwtValidator validator = new JwtValidator(
+                meta.jwksUri(), config.issuer(), config.clientId(),
+                config.algorithm(), http);
+
+        // 4. PKCE state store (per extension instance — safe for multi-tenant)
+        OidcStateStore stateStore = new OidcStateStore();
+
+        // 5. Shared token client (injected into middleware for refresh)
+        TokenClient tokenClient = new TokenClient(http, config);
+
+        // 6. Middleware (also exposed in context for manual lambda-route protection)
+        OidcMiddleware oidcMw = new OidcMiddleware(validator, config, meta, tokenClient);
+        ctx.provide(OidcMiddleware.class, oidcMw);
+        ctx.provide(JwtValidator.class,   validator);
+
+        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(); // CSRF protection
+            String nonce     = UUID.randomUUID().toString(); // ID token replay protection
+
+            String redirect = req.query("redirect");
+            // Only allow relative paths — prevents open-redirect attacks
+            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.status(302).header("Location", authUrl);
+            return null;
+        }).with();
+
+        // ── GET {prefix}/callback ─────────────────────────────────────────────
+        // Validates state, exchanges code for tokens, creates session, redirects.
+        app.get(prefix + "/callback", (req, res) -> {
+            String error = req.query("error");
+            if (error != null) {
+                res.status(400);
+                return "Authentication error: " + error
+                        + (req.query("error_description") != null
+                           ? " — " + req.query("error_description") : "");
+            }
+
+            String code  = req.query("code");
+            String state = req.query("state");
+
+            OidcStateStore.Entry entry = stateStore.consumeAndRemove(state).orElse(null);
+            if (entry == null) {
+                res.status(400);
+                return "Invalid or expired state parameter";
+            }
+
+            OidcTokenResponse tokens = tokenClient.exchangeCode(
+                    meta.tokenEndpoint(), code, absoluteRedirectUri(req), entry.codeVerifier());
+
+            // Validate ID token: signature + iss + aud + exp + iat + sub + nonce (OIDC Core §3.1.3.7)
+            if (tokens.idToken() != null) {
+                try {
+                    validator.validateIdToken(tokens.idToken(), entry.nonce());
+                } catch (OidcValidationException e) {
+                    res.status(400);
+                    return "ID token validation failed: " + e.getMessage();
+                }
+            }
+
+            Map<String, Object> claims = mergeClaims(tokens);
+
+            OidcSession session = new OidcSession(
+                    UUID.randomUUID().toString(),
+                    tokens.accessToken(),
+                    tokens.idToken(),
+                    tokens.refreshToken(),
+                    Instant.now().plusSeconds(tokens.expiresIn()),
+                    claims
+            );
+            config.sessionStore().save(session);
+
+            res.status(302)
+               .header("Set-Cookie", sessionCookie(session.id()))
+               .header("Location",   entry.originalUrl());
+            return null;
+        }).with();
+
+        // ── POST {prefix}/logout ──────────────────────────────────────────────
+        // Invalidates the local session and redirects to the provider's
+        // end_session_endpoint (with id_token_hint) if available.
+        app.post(prefix + "/logout", (req, res) -> {
+            String sessionId   = OidcMiddleware.cookieValue(req, "oidc_session");
+            String idTokenHint = null;
+
+            if (sessionId != null) {
+                config.sessionStore().find(sessionId)
+                        .ifPresent(s -> {});          // capture id_token before delete
+                OidcSession session = config.sessionStore().find(sessionId).orElse(null);
+                if (session != null) idTokenHint = session.idToken();
+                config.sessionStore().delete(sessionId);
+            }
+
+            String clearCookie = "oidc_session=; HttpOnly; Path=/; Max-Age=0; SameSite=Lax";
+            String location;
+
+            if (meta.endSessionEndpoint() != null) {
+                String postLogout = absoluteSelf(req, config.postLogoutRedirectUri());
+                StringBuilder url = new StringBuilder(meta.endSessionEndpoint())
+                        .append("?post_logout_redirect_uri=").append(enc(postLogout));
+                if (idTokenHint != null)
+                    url.append("&id_token_hint=").append(enc(idTokenHint));
+                location = url.toString();
+            } else {
+                location = config.postLogoutRedirectUri();
+            }
+
+            res.status(302)
+               .header("Set-Cookie", clearCookie)
+               .header("Location",   location);
+            return null;
+        }).with();
+
+        // 5. Annotation processor for @Authenticated / @RolesAllowed
+        ctx.addAnnotationProcessor(handlerClass -> {
+            RolesAllowed roles = handlerClass.getAnnotation(RolesAllowed.class);
+            if (roles != null) return List.of(oidcMw.rolesMiddleware(roles.value()));
+
+            Authenticated auth = handlerClass.getAnnotation(Authenticated.class);
+            if (auth != null) return List.of(oidcMw.authenticatedMiddleware());
+
+            return List.of();
+        });
+
+        // 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.
+     * The access token carries provider-specific data like {@code realm_access.roles};
+     * the ID token carries standard identity claims (sub, email, name, …).
+     * ID token values win on conflict so that verified identity claims are authoritative.
+     */
+    private static Map<String, Object> mergeClaims(OidcTokenResponse tokens) {
+        Map<String, Object> merged = new HashMap<>();
+        // Access token first — provides roles, resource_access, etc.
+        if (tokens.accessToken() != null) {
+            merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
+        }
+        // ID token overrides — its identity claims (sub, email, name, …) take priority.
+        if (tokens.idToken() != null) {
+            merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
+        }
+        return Map.copyOf(merged);
+    }
+
+    /**
+     * Builds an {@link HttpClient}. If {@link OidcConfig#insecureTls()} is set,
+     * installs a trust-all {@link SSLContext} that accepts any certificate.
+     * <b>Only safe for development with self-signed certificates.</b>
+     */
+    private static HttpClient buildHttpClient(OidcConfig config) {
+        if (!config.insecureTls()) return HttpClient.newHttpClient();
+        try {
+            TrustManager[] trustAll = { new X509TrustManager() {
+                public X509Certificate[] getAcceptedIssuers()                          { return new X509Certificate[0]; }
+                public void checkClientTrusted(X509Certificate[] c, String a)          {}
+                public void checkServerTrusted(X509Certificate[] c, String a)          {}
+            }};
+            SSLContext ctx = SSLContext.getInstance("TLS");
+            ctx.init(null, trustAll, new SecureRandom());
+            return HttpClient.newBuilder().sslContext(ctx).build();
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to create trust-all SSLContext", e);
+        }
+    }
+
+    /**
+     * Resolves the configured {@code redirectUri}. If it starts with {@code /},
+     * prepends {@code selfScheme://Host} from the current request.
+     */
+    private String absoluteRedirectUri(dev.relism.models.Request req) {
+        return absoluteSelf(req, config.redirectUri());
+    }
+
+    private String absoluteSelf(dev.relism.models.Request req, String uri) {
+        if (!uri.startsWith("/")) return uri;
+        return config.selfScheme() + "://" + req.header("Host") + 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 dev.relism.ext.openapi.OpenApiSecurityRegistry} is actually on the classpath.
+     * If not present, the {@link NoClassDefFoundError} is caught at the call site.
+     */
+    private static final class OpenApiIntegration {
+        static void register(dev.relism.extension.ExtensionContext ctx,
+                             OidcConfig config, OidcProviderMetadata meta) {
+            ctx.find(dev.relism.ext.openapi.OpenApiSecurityRegistry.class)
+               .ifPresent(registry -> registry.add(new dev.relism.ext.openapi.OpenApiSecurityContributor() {
+
+                   @Override
+                   public String schemeName() { return config.schemeName(); }
+
+                   @Override
+                   public java.util.Map<String, Object> schemeDefinition() {
+                       // Declare only the authorizationCode flow so Swagger UI shows
+                       // a single clean "Authorize" dialog instead of expanding every
+                       // grant type from the discovery document.
+                       java.util.Map<String, String> scopesMap = new java.util.LinkedHashMap<>();
+                       for (String s : config.scopes().split("\\s+")) {
+                           if (!s.isBlank()) scopesMap.put(s, s);
+                       }
+                       java.util.Map<String, Object> flow = new java.util.LinkedHashMap<>();
+                       flow.put("authorizationUrl", meta.authorizationEndpoint());
+                       flow.put("tokenUrl",         meta.tokenEndpoint());
+                       flow.put("scopes",           scopesMap);
+
+                       java.util.Map<String, Object> scheme = new java.util.LinkedHashMap<>();
+                       scheme.put("type",  "oauth2");
+                       scheme.put("flows", java.util.Map.of("authorizationCode", flow));
+                       return scheme;
+                   }
+
+                   @Override
+                   public java.util.List<String> requiredFor(Class<?> handlerClass) {
+                       dev.relism.ext.oidc.RolesAllowed roles =
+                               handlerClass.getAnnotation(dev.relism.ext.oidc.RolesAllowed.class);
+                       if (roles != null) return java.util.Arrays.asList(roles.value());
+
+                       dev.relism.ext.oidc.Authenticated auth =
+                               handlerClass.getAnnotation(dev.relism.ext.oidc.Authenticated.class);
+                       if (auth != null) return java.util.List.of();
+
+                       return null; // not secured by this contributor
+                   }
+               }));
+        }
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
new file mode 100644
index 0000000..d3fb217
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcMiddleware.java
@@ -0,0 +1,203 @@
+package dev.relism.ext.oidc;
+
+import dev.relism.exceptions.HttpException;
+import dev.relism.models.Request;
+import dev.relism.routing.Middleware;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Request-level OIDC middleware. Exposed in the {@link dev.relism.extension.ExtensionContext}
+ * for manual use on lambda routes; injected automatically for handlers annotated with
+ * {@link Authenticated} or {@link RolesAllowed}.
+ *
+ * <p>Resolution order on each request:
+ * <ol>
+ *   <li>{@code Authorization: Bearer ...} header — validated via JWKS ({@link JwtValidator}).</li>
+ *   <li>{@code oidc_session} cookie — looked up in {@link OidcSessionStore}; transparently
+ *       refreshed if the access token is expired.</li>
+ *   <li>Browser clients (no {@code Accept: application/json}) → redirect to
+ *       {@code {routePrefix}/login?redirect={path}}.</li>
+ *   <li>API clients → 401.</li>
+ * </ol>
+ *
+ * <pre>{@code
+ * // Manual use on a lambda route:
+ * OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
+ * app.get("/api/me", (req, res) -> ClaimsHolder.claim("sub"), oidc.protect());
+ * app.delete("/admin/users/{id}", handler, oidc.requireRole("admin"));
+ * }</pre>
+ */
+public class OidcMiddleware {
+
+    private final JwtValidator         validator;
+    private final OidcConfig           config;
+    private final OidcProviderMetadata meta;
+    private final TokenClient          tokenClient;
+
+    OidcMiddleware(JwtValidator validator, OidcConfig config,
+                   OidcProviderMetadata meta, TokenClient tokenClient) {
+        this.validator   = validator;
+        this.config      = config;
+        this.meta        = meta;
+        this.tokenClient = tokenClient;
+    }
+
+    // -- Public API -----------------------------------------------------------
+
+    /**
+     * Validates the bearer token or session cookie. Browser clients are redirected
+     * to the login page on failure; API clients receive 401.
+     */
+    public Middleware protect() {
+        return next -> (req, res) -> {
+            Map<String, Object> claims = resolve(req, res);
+            if (claims == null) return null;    // redirect already written
+            ClaimsHolder.set(claims);
+            try {
+                return next.handle(req, res);
+            } finally {
+                ClaimsHolder.clear();
+            }
+        };
+    }
+
+    /**
+     * Like {@link #protect()} but also enforces that the caller holds at least one
+     * of the given roles (OR semantics). Roles are extracted via
+     * {@link OidcConfig#rolesClaimPath()}.
+     */
+    public Middleware requireRole(String... roles) {
+        return next -> (req, res) -> {
+            Map<String, Object> claims = resolve(req, res);
+            if (claims == null) return null;
+            checkRoles(claims, roles);
+            ClaimsHolder.set(claims);
+            try {
+                return next.handle(req, res);
+            } finally {
+                ClaimsHolder.clear();
+            }
+        };
+    }
+
+    // -- Package-private: AnnotationProcessor hooks ---------------------------
+
+    Middleware authenticatedMiddleware()          { return protect(); }
+    Middleware rolesMiddleware(String[] required) { return requireRole(required); }
+
+    // -- Internals ------------------------------------------------------------
+
+    /**
+     * Returns claims on success, or {@code null} if a redirect was already written to
+     * {@code res}. Throws {@link HttpException} 401/403 for API clients.
+     */
+    private Map<String, Object> resolve(Request req, dev.relism.models.Response res) {
+        // 1. Bearer token
+        String auth = req.header("Authorization");
+        if (auth != null && auth.startsWith("Bearer "))
+            return validator.validate(auth.substring(7));
+
+        // 2. Session cookie
+        String sessionId = cookieValue(req, "oidc_session");
+        if (sessionId != null) {
+            Optional<OidcSession> found = config.sessionStore().find(sessionId);
+            if (found.isPresent()) {
+                OidcSession session = found.get();
+
+                if (!session.isAccessTokenExpired())
+                    return session.claims();
+
+                // Access token expired — try silent refresh
+                if (session.refreshToken() != null) {
+                    try {
+                        OidcSession refreshed = doRefresh(session);
+                        config.sessionStore().save(refreshed);
+                        return refreshed.claims();
+                    } catch (Exception ignored) {
+                        // Refresh failed — fall through to re-authenticate
+                    }
+                }
+                config.sessionStore().delete(sessionId);
+            }
+        }
+
+        // 3. No valid credentials
+        String accept = req.header("Accept");
+        if (accept != null && accept.contains("application/json"))
+            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.status(302).header("Location", loginUrl);
+        return null;
+    }
+
+    private OidcSession doRefresh(OidcSession old) throws Exception {
+        OidcTokenResponse tokens = tokenClient.refresh(
+                meta.tokenEndpoint(), old.refreshToken());
+
+        Map<String, Object> claims = mergeRefreshedClaims(tokens, old);
+
+        return new OidcSession(
+                old.id(),
+                tokens.accessToken(),
+                tokens.idToken() != null ? tokens.idToken() : old.idToken(),
+                tokens.refreshToken() != null ? tokens.refreshToken() : old.refreshToken(),
+                Instant.now().plusSeconds(tokens.expiresIn()),
+                claims
+        );
+    }
+
+    private void checkRoles(Map<String, Object> claims, String[] required) {
+        List<String> actual = extractRoles(claims);
+        for (String role : required) {
+            if (actual.contains(role)) return;
+        }
+        throw HttpException.forbidden();
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<String> extractRoles(Map<String, Object> claims) {
+        String[] parts   = config.rolesClaimPath().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();
+    }
+
+    private static Map<String, Object> mergeRefreshedClaims(OidcTokenResponse tokens, OidcSession old) {
+        Map<String, Object> merged = new HashMap<>();
+        // Fall back to old claims first, then overlay fresh token claims
+        merged.putAll(old.claims());
+        if (tokens.accessToken() != null)
+            merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
+        if (tokens.idToken() != null)
+            merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
+        return Map.copyOf(merged);
+    }
+
+    // -- Shared cookie utility (also used by OidcExtension) -------------------
+
+    static String cookieValue(Request req, String name) {
+        String header = req.header("Cookie");
+        if (header == null || header.isBlank()) return null;
+        for (String part : header.split(";")) {
+            int eq = part.indexOf('=');
+            if (eq > 0 && part.substring(0, eq).strip().equals(name))
+                return part.substring(eq + 1).strip();
+        }
+        return null;
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcProviderMetadata.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcProviderMetadata.java
new file mode 100644
index 0000000..a646f42
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcProviderMetadata.java
@@ -0,0 +1,15 @@
+package dev.relism.ext.oidc;
+
+/**
+ * OIDC provider endpoints discovered from {@code {issuer}/.well-known/openid-configuration}.
+ *
+ * <p>{@link #endSessionEndpoint()} may be {@code null} — not all providers expose it
+ * (e.g. some Authelia configurations omit it).
+ */
+public record OidcProviderMetadata(
+        String authorizationEndpoint,
+        String tokenEndpoint,
+        String userinfoEndpoint,
+        String jwksUri,
+        String endSessionEndpoint       // nullable
+) {}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSession.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSession.java
new file mode 100644
index 0000000..fefdb17
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSession.java
@@ -0,0 +1,47 @@
+package dev.relism.ext.oidc;
+
+import java.time.Instant;
+import java.util.Map;
+
+/**
+ * An authenticated user's OIDC session — persisted in {@link OidcSessionStore} and
+ * looked up via the {@code oidc_session} cookie on every request.
+ *
+ * <p>Sessions are immutable; a refreshed access token produces a new instance
+ * that replaces the old one in the store (same {@link #id()}).
+ */
+public final class OidcSession {
+
+    private final String              id;
+    private final String              accessToken;
+    private final String              idToken;
+    private final String              refreshToken;        // may be null
+    private final Instant             accessTokenExpiresAt;
+    private final Map<String, Object> claims;              // decoded from id_token
+
+    public OidcSession(String id, String accessToken, String idToken,
+                       String refreshToken, Instant accessTokenExpiresAt,
+                       Map<String, Object> claims) {
+        this.id                   = id;
+        this.accessToken          = accessToken;
+        this.idToken              = idToken;
+        this.refreshToken         = refreshToken;
+        this.accessTokenExpiresAt = accessTokenExpiresAt;
+        this.claims               = Map.copyOf(claims);
+    }
+
+    /**
+     * Returns {@code true} if the access token has expired or will expire within
+     * the next 30 seconds (eager refresh to avoid mid-request expiry).
+     */
+    public boolean isAccessTokenExpired() {
+        return Instant.now().isAfter(accessTokenExpiresAt.minusSeconds(30));
+    }
+
+    public String              id()                   { return id; }
+    public String              accessToken()          { return accessToken; }
+    public String              idToken()              { return idToken; }
+    public String              refreshToken()         { return refreshToken; }
+    public Instant             accessTokenExpiresAt() { return accessTokenExpiresAt; }
+    public Map<String, Object> claims()               { return claims; }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSessionStore.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSessionStore.java
new file mode 100644
index 0000000..f7966c2
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcSessionStore.java
@@ -0,0 +1,14 @@
+package dev.relism.ext.oidc;
+
+import java.util.Optional;
+
+/**
+ * Backing store for {@link OidcSession} objects. The default implementation is
+ * {@link InMemoryOidcSessionStore}; supply a custom one via
+ * {@link OidcConfig.Builder#sessionStore(OidcSessionStore)} for Redis, JDBC, etc.
+ */
+public interface OidcSessionStore {
+    void save(OidcSession session);
+    Optional<OidcSession> find(String sessionId);
+    void delete(String sessionId);
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcStateStore.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcStateStore.java
new file mode 100644
index 0000000..d8954f4
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcStateStore.java
@@ -0,0 +1,39 @@
+package dev.relism.ext.oidc;
+
+import java.time.Instant;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Short-lived store mapping state nonces → (original URL, PKCE verifier).
+ *
+ * <p>Entries expire after {@value #TTL_SECONDS} seconds. Cleanup runs on every
+ * access to prevent unbounded growth without needing a background thread.
+ */
+final class OidcStateStore {
+
+    static final int TTL_SECONDS = 600; // 10 minutes
+
+    record Entry(String originalUrl, String codeVerifier, String nonce, Instant expiresAt) {}
+
+    private final ConcurrentHashMap<String, Entry> store = new ConcurrentHashMap<>();
+
+    void put(String state, String originalUrl, String codeVerifier, String nonce) {
+        cleanup();
+        store.put(state, new Entry(originalUrl, codeVerifier, nonce,
+                Instant.now().plusSeconds(TTL_SECONDS)));
+    }
+
+    /** Atomically retrieves and removes the entry; returns empty if absent or expired. */
+    Optional<Entry> consumeAndRemove(String nonce) {
+        cleanup();
+        Entry e = store.remove(nonce);
+        if (e == null || Instant.now().isAfter(e.expiresAt())) return Optional.empty();
+        return Optional.of(e);
+    }
+
+    private void cleanup() {
+        Instant now = Instant.now();
+        store.entrySet().removeIf(kv -> now.isAfter(kv.getValue().expiresAt()));
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcTokenResponse.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcTokenResponse.java
new file mode 100644
index 0000000..9ab5c54
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcTokenResponse.java
@@ -0,0 +1,10 @@
+package dev.relism.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-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
new file mode 100644
index 0000000..2d73f2e
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcUser.java
@@ -0,0 +1,106 @@
+package dev.relism.ext.oidc;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Type-safe view over the JWT claims stored in {@link ClaimsHolder}.
+ *
+ * <p>Obtainable from any protected context via {@link ClaimsHolder#user()}.
+ * Class-based handlers that extend the {@code SessionHandler} hierarchy already
+ * have a provisioned DB user in {@code currentUser}; {@code OidcUser} complements
+ * that by giving access to the raw OIDC claims when needed, and is the primary
+ * API for lambda routes.
+ *
+ * <pre>{@code
+ * // Lambda route (OidcMiddleware injected):
+ * app.get("/api/whoami", (req, res) -> {
+ *     OidcUser u = ClaimsHolder.user();
+ *     return Map.of("sub", u.sub(), "email", u.email(), "roles", u.roles());
+ * }, oidcMw.protect());
+ *
+ * // Class-based handler (currentUser is the DB entity; oidcUser() for raw claims):
+ * protected Object handleAuthenticated(Request req, Response res) throws Exception {
+ *     OidcUser u = oidcUser();           // same as ClaimsHolder.user()
+ *     return json(res, currentUser);     // DB entity — provisioned from OIDC sub
+ * }
+ * }</pre>
+ */
+public final class OidcUser {
+
+    private final Map<String, Object> claims;
+
+    OidcUser(Map<String, Object> claims) {
+        this.claims = claims;
+    }
+
+    // ── Common OIDC standard claims ───────────────────────────────────────────
+
+    /** Subject identifier — unique, stable user ID issued by the provider. */
+    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.
+     *
+     * <p>Example paths:
+     * <ul>
+     *   <li>{@code "realm_access.roles"} — Keycloak realm roles</li>
+     *   <li>{@code "resource_access.my-client.roles"} — Keycloak client roles</li>
+     *   <li>{@code "groups"} — Authelia / generic IdPs</li>
+     * </ul>
+     *
+     * @return list of role strings, or an empty list if the path doesn't exist
+     */
+    @SuppressWarnings("unchecked")
+    public List<String> 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);
+    }
+
+    // ── 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> T claim(String key, Class<T> 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<String, Object> claims() { return claims; }
+
+    // ── Internals ─────────────────────────────────────────────────────────
+
+    private String str(String key) {
+        Object v = claims.get(key);
+        return v != null ? v.toString() : null;
+    }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcValidationException.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcValidationException.java
new file mode 100644
index 0000000..459285c
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/OidcValidationException.java
@@ -0,0 +1,12 @@
+package dev.relism.ext.oidc;
+
+/**
+ * Thrown when OIDC token validation fails (signature, claims, nonce, expiry, etc.).
+ * Distinct from {@link dev.relism.exceptions.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-oidc/src/main/java/dev/relism/ext/oidc/PkceUtils.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/PkceUtils.java
new file mode 100644
index 0000000..70a0fed
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/PkceUtils.java
@@ -0,0 +1,36 @@
+package dev.relism.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-oidc/src/main/java/dev/relism/ext/oidc/RolesAllowed.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/RolesAllowed.java
new file mode 100644
index 0000000..3f6a05b
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/RolesAllowed.java
@@ -0,0 +1,32 @@
+package dev.relism.ext.oidc;
+
+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 JWT contains at least one of the
+ * specified roles. Authentication is implicitly required — no need to combine
+ * with {@link Authenticated}.
+ *
+ * <p>Roles are read from the claim configured in {@link OidcConfig#rolesClaimPath()}
+ * (default: {@code "roles"}). Nested paths like {@code "realm_access.roles"} are
+ * supported with dot notation.
+ *
+ * <pre>{@code
+ * @Route(method = HttpMethod.DELETE, path = "/api/admin/blogs/{id}")
+ * @RolesAllowed("admin")
+ * public class DeleteBlog extends JacksonHandler { ... }
+ *
+ * // Multiple accepted roles (OR semantics — any one role is sufficient):
+ * @RolesAllowed({"admin", "editor"})
+ * public class UpdateBlog extends JacksonHandler { ... }
+ * }</pre>
+ */
+@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-oidc/src/main/java/dev/relism/ext/oidc/TokenClient.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/TokenClient.java
new file mode 100644
index 0000000..88f949c
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/ext/oidc/TokenClient.java
@@ -0,0 +1,112 @@
+package dev.relism.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).
+ *
+ * <p>Supports two client authentication methods (RFC 6749 §2.3):
+ * <ul>
+ *   <li>{@link ClientAuthMethod#POST} — credentials in form body ({@code client_secret_post})</li>
+ *   <li>{@link ClientAuthMethod#BASIC} — credentials in {@code Authorization: Basic} header
+ *       ({@code client_secret_basic})</li>
+ * </ul>
+ */
+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<String, String> 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<String, String> 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<String, String> 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<String> 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<String, Object> json = (Map<String, Object>) 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<String, String> 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<String, Object> 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-openapi/README.md b/flash-extensions/flash-ext-openapi/README.md
new file mode 100644
index 0000000..d94be51
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/README.md
@@ -0,0 +1,160 @@
+# flash-ext-openapi
+
+OpenAPI 3.0 spec generation and Swagger UI for the Flash HTTP server.
+
+## What it provides
+
+| Route | Description |
+|---|---|
+| `GET /openapi.json` | OpenAPI 3.0.3 spec as JSON |
+| `GET /openapi.yaml` | OpenAPI 3.0.3 spec as YAML |
+| `GET /openapi/swagger` | Swagger UI (loaded from unpkg CDN) |
+
+The base path is configurable. Operations are collected automatically at handler-registration time
+from class-based handlers annotated with `@ApiOperation`.
+
+## Dependencies
+
+Requires `flash-ext-jackson` installed **before** this extension (shares its `ObjectMapper` from context).
+If `flash-ext-oidc` is installed **after** this extension, OIDC security schemes are injected automatically.
+
+```xml
+<dependency>
+    <groupId>dev.relism</groupId>
+    <artifactId>flash-ext-openapi</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+## Installation
+
+```java
+FlashApp.of(new HttpServer(config))
+    .install(new JacksonExtension())
+    .install(new OpenApiExtension("/openapi", "My API", "2.0.0", "Optional description"))
+    .register(new MyHandler());
+```
+
+### Constructors
+
+```java
+new OpenApiExtension()                                     // base path: /openapi, title: API, version: 1.0.0
+new OpenApiExtension("/docs")                              // custom base path
+new OpenApiExtension("/docs", "My API", "2.0.0")          // title + version
+new OpenApiExtension("/docs", "My API", "2.0.0", "desc")  // full
+```
+
+## Annotating handlers
+
+All annotations target the **handler class** (`@Target(ElementType.TYPE)`).
+
+### @ApiOperation
+
+```java
+@Route(method = HttpMethod.GET, path = "/api/blogs")
+@ApiOperation(
+    summary     = "List all blogs",
+    description = "Returns a paginated list of published blog posts.",
+    tags        = {"blogs"},
+    operationId = "listBlogs",
+    deprecated  = false
+)
+public class ListBlogs extends JacksonHandler { ... }
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `summary` | `""` | Short one-liner shown in the operation title |
+| `description` | `""` | Longer Markdown description |
+| `tags` | `{}` | Groups operations in the Swagger UI sidebar |
+| `operationId` | `""` | Unique machine-readable ID |
+| `deprecated` | `false` | Marks the operation with a strikethrough |
+
+### @ApiResponse
+
+Repeatable — annotate as many status codes as the handler can return.
+
+```java
+@ApiResponse(status = 200, description = "Blog created", schema = Blog.class)
+@ApiResponse(status = 400, description = "Invalid input")
+@ApiResponse(status = 409, description = "Slug already exists")
+public class CreateBlog extends JacksonHandler { ... }
+```
+
+`schema` references `#/components/schemas/<ClassName>` — you are responsible for populating
+`components.schemas` if you need full model documentation (not yet auto-generated).
+
+`@ApiResponse` is repeatable. The container `@ApiResponses({ @ApiResponse(...), ... })` is also available.
+
+### @ApiParam
+
+Repeatable — declare query, path, header, or cookie parameters explicitly.
+
+```java
+@ApiParam(name = "limit",  in = "query",   type = "integer", description = "Max results (default 20)")
+@ApiParam(name = "offset", in = "query",   type = "integer", description = "Pagination offset")
+@ApiParam(name = "slug",   in = "path",    type = "string",  required = true)
+@ApiParam(name = "X-Trace-Id", in = "header", type = "string")
+public class GetBlog extends JacksonHandler { ... }
+```
+
+> Path parameters declared in `@Route(path = "/blogs/{id}")` are extracted and added automatically
+> as required path parameters — you only need `@ApiParam` for query / header / cookie params.
+
+`@ApiParam` is repeatable. If you prefer grouping them, `@ApiParams({ @ApiParam(...), @ApiParam(...) })` is
+the container annotation.
+
+| Field | Default | Description |
+|---|---|---|
+| `name` | — | Parameter name |
+| `in` | `"query"` | Location: `"query"`, `"path"`, `"header"`, `"cookie"` |
+| `type` | `"string"` | OpenAPI primitive: `"string"`, `"integer"`, `"number"`, `"boolean"` |
+| `description` | `""` | Human-readable description |
+| `required` | `false` | Whether the parameter is mandatory |
+| `example` | `""` | Inline example value shown in Swagger UI |
+
+## Security integration
+
+`flash-ext-openapi` defines the `OpenApiSecurityContributor` / `OpenApiSecurityRegistry` contracts.
+Security extensions (e.g. `flash-ext-oidc`) register a contributor at install time; the spec
+builder picks it up automatically — no coupling between extensions.
+
+### How it works
+
+1. `OpenApiExtension` creates an `OpenApiSecurityRegistry` and exposes it in the `ExtensionContext`.
+2. `flash-ext-oidc` calls `ctx.find(OpenApiSecurityRegistry.class)` and registers its contributor.
+3. At spec build time, `OpenApiBuilder` iterates contributors and injects `security` entries on each
+   operation whose handler class carries `@Authenticated` or `@RolesAllowed`.
+
+### Implementing a custom contributor
+
+```java
+public class MyAuthContributor implements OpenApiSecurityContributor {
+
+    @Override
+    public String schemeName() { return "myScheme"; }
+
+    @Override
+    public Map<String, Object> schemeDefinition() {
+        return Map.of("type", "apiKey", "in", "header", "name", "X-API-Key");
+    }
+
+    @Override
+    public List<String> requiredFor(Class<?> handlerClass) {
+        if (handlerClass.isAnnotationPresent(MyAuth.class)) return List.of();
+        return null; // not secured by this contributor
+    }
+}
+
+// Register during extension install:
+ctx.find(OpenApiSecurityRegistry.class)
+   .ifPresent(r -> r.add(new MyAuthContributor()));
+```
+
+Return values from `requiredFor`:
+
+| Return | Meaning |
+|---|---|
+| `null` | Handler is not secured by this contributor — skip |
+| `List.of()` | Requires authentication, no specific scopes |
+| `List.of("admin", "user")` | Requires one of these scopes (OpenAPI OR semantics) |
diff --git a/flash-extensions/flash-ext-openapi/pom.xml b/flash-extensions/flash-ext-openapi/pom.xml
new file mode 100644
index 0000000..448ade5
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/pom.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.relism</groupId>
+        <artifactId>flash-extensions</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>flash-ext-openapi</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>dev.relism</groupId>
+            <artifactId>flash-ext-jackson</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.dataformat</groupId>
+            <artifactId>jackson-dataformat-yaml</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
new file mode 100644
index 0000000..8cb4c93
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiOperation.java
@@ -0,0 +1,26 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares OpenAPI operation metadata for a class-based handler.
+ * Picked up by {@link OpenApiExtension} via {@link FlashApp#register}.
+ *
+ * <pre>{@code
+ * @Route(method = HttpMethod.GET, path = "/api/blogs")
+ * @ApiOperation(summary = "List all blogs", tags = {"blogs"})
+ * public class ListBlogs extends JacksonHandler { ... }
+ * }</pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ApiOperation {
+    String summary() default "";
+    String description() default "";
+    String[] tags() default {};
+    boolean deprecated() default false;
+    String operationId() default "";
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParam.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParam.java
new file mode 100644
index 0000000..e6618f9
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParam.java
@@ -0,0 +1,27 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.*;
+
+/**
+ * Declares a single parameter (query, path, header, or cookie) for an operation.
+ * Repeatable — place multiple annotations on the same handler class.
+ *
+ * <pre>{@code
+ * @ApiParam(name = "limit",  in = "query", type = "integer", description = "Max results (default 20)")
+ * @ApiParam(name = "offset", in = "query", type = "integer", description = "Pagination offset")
+ * public class ListBlogs extends JacksonHandler { ... }
+ * }</pre>
+ */
+@Repeatable(ApiParams.class)
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ApiParam {
+    String name();
+    /** "query", "path", "header", or "cookie". */
+    String in()          default "query";
+    /** OpenAPI primitive type: "string", "integer", "number", "boolean". */
+    String type()        default "string";
+    String description() default "";
+    boolean required()   default false;
+    String example()     default "";
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParams.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParams.java
new file mode 100644
index 0000000..8aac0e3
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiParams.java
@@ -0,0 +1,13 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Container for repeated {@link ApiParam} annotations. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ApiParams {
+    ApiParam[] value();
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
new file mode 100644
index 0000000..282e1b6
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponse.java
@@ -0,0 +1,23 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.*;
+
+/**
+ * Declares a single response for an operation. Repeatable — use multiple
+ * {@code @ApiResponse} annotations on the same handler to document several status codes.
+ *
+ * <pre>{@code
+ * @ApiResponse(status = 200, description = "Blog created", schema = Blog.class)
+ * @ApiResponse(status = 400, description = "Invalid input")
+ * @ApiResponse(status = 409, description = "Slug already exists")
+ * public class CreateBlog extends JacksonHandler { ... }
+ * }</pre>
+ */
+@Repeatable(ApiResponses.class)
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ApiResponse {
+    int    status();
+    String description() default "";
+    Class<?> schema()    default Void.class;
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java
new file mode 100644
index 0000000..6182e1b
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/ApiResponses.java
@@ -0,0 +1,13 @@
+package dev.relism.ext.openapi;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Container for repeated {@link ApiResponse} annotations. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ApiResponses {
+    ApiResponse[] value();
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
new file mode 100644
index 0000000..499602e
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiBuilder.java
@@ -0,0 +1,204 @@
+package dev.relism.ext.openapi;
+
+import dev.relism.routing.Route;
+
+import java.util.*;
+
+/**
+ * Accumulates OpenAPI 3.0 operations and builds the spec document as a plain
+ * {@code Map} for Jackson to serialize. Operations are added at registration time
+ * via {@link OpenApiExtension}'s {@link dev.relism.AnnotationProcessor}.
+ */
+public class OpenApiBuilder {
+
+    private String title   = "API";
+    private String version = "1.0.0";
+    private String description = "";
+
+    private final Map<String, Map<String, Object>> paths = new LinkedHashMap<>();
+    private final Map<String, Map<String, Class<?>>> operationHandlers = new LinkedHashMap<>();
+    private OpenApiSecurityRegistry securityRegistry;
+
+    // ── Configuration ─────────────────────────────────────────────────────────
+
+    public OpenApiBuilder title(String title)             { this.title = title; return this; }
+    public OpenApiBuilder version(String version)         { this.version = version; return this; }
+    public OpenApiBuilder description(String description) { this.description = description; return this; }
+
+    void setSecurityRegistry(OpenApiSecurityRegistry registry) {
+        this.securityRegistry = registry;
+    }
+
+    // ── Operation registration ────────────────────────────────────────────────
+
+    /**
+     * Adds an operation derived from the handler's {@link Route}, {@link ApiOperation},
+     * {@link ApiResponse}, and {@link ApiParam} annotations.
+     */
+    public void addOperation(Route route, ApiOperation op, Class<?> handlerClass) {
+        String path   = normalizePath(route.path());
+        String method = route.method().name().toLowerCase();
+
+        Map<String, Object> pathItem  = paths.computeIfAbsent(path, k -> new LinkedHashMap<>());
+        Map<String, Object> operation = new LinkedHashMap<>();
+
+        if (!op.operationId().isEmpty())  operation.put("operationId", op.operationId());
+        if (!op.summary().isEmpty())      operation.put("summary", op.summary());
+        if (!op.description().isEmpty())  operation.put("description", op.description());
+        if (op.tags().length > 0)         operation.put("tags", Arrays.asList(op.tags()));
+        if (op.deprecated())              operation.put("deprecated", true);
+
+        buildParameters(operation, handlerClass, route);
+        buildResponses(operation, handlerClass);
+
+        pathItem.put(method, operation);
+        operationHandlers.computeIfAbsent(path, k -> new LinkedHashMap<>()).put(method, handlerClass);
+    }
+
+    // ── Spec build ────────────────────────────────────────────────────────────
+
+    /**
+     * Returns the complete OpenAPI 3.0.3 spec as a plain map ready for JSON
+     * serialization. Called on each request to {@code /openapi.json} so that
+     * handlers registered after the extension is installed are included.
+     */
+    public Map<String, Object> build() {
+        Map<String, Object> info = new LinkedHashMap<>();
+        info.put("title", title);
+        info.put("version", version);
+        if (!description.isEmpty()) info.put("description", description);
+
+        List<OpenApiSecurityContributor> contributors = securityRegistry != null
+                ? securityRegistry.contributors() : List.of();
+
+        // Build paths with security injected per-operation (fresh copy each time so
+        // repeated calls don't accumulate duplicate security entries)
+        Map<String, Object> renderedPaths = new LinkedHashMap<>();
+        for (var pathEntry : paths.entrySet()) {
+            Map<String, Object> renderedPathItem = new LinkedHashMap<>();
+            Map<String, Class<?>> handlers = operationHandlers.getOrDefault(pathEntry.getKey(), Map.of());
+            for (var methodEntry : pathEntry.getValue().entrySet()) {
+                @SuppressWarnings("unchecked")
+                Map<String, Object> original = (Map<String, Object>) methodEntry.getValue();
+                Map<String, Object> op = new LinkedHashMap<>(original); // shallow copy
+                Class<?> handler = handlers.get(methodEntry.getKey());
+                if (handler != null && !contributors.isEmpty()) {
+                    List<Map<String, List<String>>> security = buildOperationSecurity(contributors, handler);
+                    if (!security.isEmpty()) op.put("security", security);
+                }
+                renderedPathItem.put(methodEntry.getKey(), op);
+            }
+            renderedPaths.put(pathEntry.getKey(), renderedPathItem);
+        }
+
+        Map<String, Object> spec = new LinkedHashMap<>();
+        spec.put("openapi", "3.0.3");
+        spec.put("info", info);
+        spec.put("paths", renderedPaths);
+
+        if (!contributors.isEmpty()) {
+            Map<String, Object> schemes = new LinkedHashMap<>();
+            for (OpenApiSecurityContributor c : contributors) {
+                schemes.put(c.schemeName(), c.schemeDefinition());
+            }
+            spec.put("components", Map.of("securitySchemes", schemes));
+        }
+
+        return spec;
+    }
+
+    // ── Internals ─────────────────────────────────────────────────────────────
+
+    private void buildParameters(Map<String, Object> op, Class<?> cls, Route route) {
+        List<Map<String, Object>> params = new ArrayList<>();
+
+        // Path params from @Route path — add them automatically as required
+        String path = route.path();
+        int i = 0;
+        while (i < path.length()) {
+            int open = path.indexOf('{', i);
+            if (open < 0) break;
+            int close = path.indexOf('}', open);
+            if (close < 0) break;
+            String name = path.substring(open + 1, close);
+            Map<String, Object> p = new LinkedHashMap<>();
+            p.put("name", name);
+            p.put("in", "path");
+            p.put("required", true);
+            p.put("schema", Map.of("type", "string"));
+            params.add(p);
+            i = close + 1;
+        }
+
+        // Explicit @ApiParam annotations
+        ApiParam[] apiParams = cls.getAnnotationsByType(ApiParam.class);
+        for (ApiParam ann : apiParams) {
+            Map<String, Object> p = new LinkedHashMap<>();
+            p.put("name", ann.name());
+            p.put("in", ann.in());
+            p.put("required", ann.required());
+            if (!ann.description().isEmpty()) p.put("description", ann.description());
+            Map<String, Object> schema = new LinkedHashMap<>();
+            schema.put("type", ann.type());
+            if (!ann.example().isEmpty()) schema.put("example", ann.example());
+            p.put("schema", schema);
+            params.add(p);
+        }
+
+        if (!params.isEmpty()) op.put("parameters", params);
+    }
+
+    private void buildResponses(Map<String, Object> op, Class<?> cls) {
+        ApiResponse[] annotations = cls.getAnnotationsByType(ApiResponse.class);
+        Map<String, Object> responses = new LinkedHashMap<>();
+
+        if (annotations.length == 0) {
+            responses.put("200", Map.of("description", "OK"));
+        } else {
+            for (ApiResponse ann : annotations) {
+                Map<String, Object> r = new LinkedHashMap<>();
+                r.put("description", ann.description().isEmpty() ? httpPhrase(ann.status()) : ann.description());
+                if (ann.schema() != Void.class) {
+                    r.put("content", Map.of(
+                            "application/json", Map.of(
+                                    "schema", Map.of("$ref", "#/components/schemas/" + ann.schema().getSimpleName()))));
+                }
+                responses.put(String.valueOf(ann.status()), r);
+            }
+        }
+        op.put("responses", responses);
+    }
+
+    /** Converts Flash path params ({id}) to OpenAPI path params ({id}) — already compatible. */
+    private static String normalizePath(String path) {
+        return path.startsWith("/") ? path : "/" + path;
+    }
+
+    private static String httpPhrase(int status) {
+        return switch (status) {
+            case 200 -> "OK";
+            case 201 -> "Created";
+            case 204 -> "No Content";
+            case 400 -> "Bad Request";
+            case 401 -> "Unauthorized";
+            case 403 -> "Forbidden";
+            case 404 -> "Not Found";
+            case 409 -> "Conflict";
+            case 422 -> "Unprocessable Entity";
+            case 500 -> "Internal Server Error";
+            default  -> "";
+        };
+    }
+
+    private static List<Map<String, List<String>>> buildOperationSecurity(
+            List<OpenApiSecurityContributor> contributors, Class<?> handlerClass) {
+        List<Map<String, List<String>>> security = new ArrayList<>();
+        for (OpenApiSecurityContributor c : contributors) {
+            List<String> scopes = c.requiredFor(handlerClass);
+            if (scopes != null) {
+                security.add(Map.of(c.schemeName(), scopes));
+            }
+        }
+        return security;
+    }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
new file mode 100644
index 0000000..fea2a10
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiExtension.java
@@ -0,0 +1,139 @@
+package dev.relism.ext.openapi;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
+import dev.relism.extension.ExtensionContext;
+import dev.relism.extension.FlashApp;
+import dev.relism.extension.FlashExtension;
+import dev.relism.http.ContentType;
+import dev.relism.routing.Route;
+
+/**
+ * Generates and serves an OpenAPI 3.0 spec and Swagger UI under a configurable base path.
+ *
+ * <p>Given {@code basePath = "/openapi"} (the default), three routes are registered:
+ * <ul>
+ *   <li>{@code GET /openapi.json}    — OpenAPI 3.0 spec as JSON</li>
+ *   <li>{@code GET /openapi.yaml}    — OpenAPI 3.0 spec as YAML</li>
+ *   <li>{@code GET /openapi/swagger} — Swagger UI pointing at {@code /openapi.json}</li>
+ * </ul>
+ *
+ * <p><b>Requires</b> {@code flash-ext-jackson} to be installed first (shares its
+ * {@link ObjectMapper}). The YAML endpoint uses its own {@link YAMLMapper} instance.
+ *
+ * <p>Operations are collected automatically from handlers annotated with
+ * {@link ApiOperation} as they are registered via {@link FlashApp#register}.
+ *
+ * <pre>{@code
+ * FlashApp.of(new HttpServer(config))
+ *     .install(new JacksonExtension())
+ *     .install(new OpenApiExtension("/openapi", "My API", "2.0.0"))
+ *     .register(new BlogHandlers.Index())
+ *     .start();
+ * }</pre>
+ */
+public class OpenApiExtension implements FlashExtension {
+
+    private static final String YAML_CONTENT_TYPE = "application/yaml";
+
+    private final String basePath;
+    private final String title;
+    private final String version;
+    private final String description;
+
+    public OpenApiExtension() {
+        this("/openapi", "API", "1.0.0", "");
+    }
+
+    public OpenApiExtension(String basePath) {
+        this(basePath, "API", "1.0.0", "");
+    }
+
+    public OpenApiExtension(String basePath, String title, String version) {
+        this(basePath, title, version, "");
+    }
+
+    public OpenApiExtension(String basePath, String title, String version, String description) {
+        this.basePath    = basePath.endsWith("/") ? basePath.substring(0, basePath.length() - 1) : basePath;
+        this.title       = title;
+        this.version     = version;
+        this.description = description;
+    }
+
+    @Override
+    public void install(FlashApp app, ExtensionContext ctx) {
+        ObjectMapper jsonMapper = ctx.require(ObjectMapper.class);
+        YAMLMapper   yamlMapper = new YAMLMapper();
+
+        OpenApiBuilder builder = new OpenApiBuilder()
+                .title(title)
+                .version(version)
+                .description(description);
+
+        OpenApiSecurityRegistry secRegistry = new OpenApiSecurityRegistry();
+        ctx.provide(OpenApiSecurityRegistry.class, secRegistry);
+        builder.setSecurityRegistry(secRegistry);
+
+        ctx.provide(OpenApiBuilder.class, builder);
+
+        // Collect operation metadata at handler-registration time (no middleware injected)
+        ctx.addAnnotationProcessor(handlerClass -> {
+            ApiOperation op    = handlerClass.getAnnotation(ApiOperation.class);
+            Route        route = handlerClass.getAnnotation(Route.class);
+            if (op != null && route != null) {
+                builder.addOperation(route, op, handlerClass);
+            }
+            return java.util.List.of();
+        });
+
+        String jsonPath    = basePath + ".json";
+        String yamlPath    = basePath + ".yaml";
+        String swaggerPath = basePath + "/swagger";
+
+        // JSON spec
+        app.get(jsonPath, (req, res) -> {
+            res.setContentType(ContentType.JSON);
+            return jsonMapper.writeValueAsString(builder.build());
+        }).with();
+
+        // YAML spec
+        app.get(yamlPath, (req, res) -> {
+            res.type(YAML_CONTENT_TYPE);
+            return yamlMapper.writeValueAsString(builder.build());
+        }).with();
+
+        // Swagger UI — loads from CDN, points at the JSON spec
+        String swaggerHtml = buildSwaggerHtml(jsonPath);
+        app.get(swaggerPath, (req, res) -> {
+            res.setContentType(ContentType.TEXT_HTML);
+            return swaggerHtml;
+        }).with();
+    }
+
+    // ── Swagger UI HTML ───────────────────────────────────────────────────────
+
+    private static String buildSwaggerHtml(String specJsonPath) {
+        return "<!DOCTYPE html>\n" +
+               "<html lang=\"en\">\n" +
+               "<head>\n" +
+               "  <meta charset=\"UTF-8\">\n" +
+               "  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n" +
+               "  <title>Swagger UI</title>\n" +
+               "  <link rel=\"stylesheet\" href=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui.css\">\n" +
+               "</head>\n" +
+               "<body>\n" +
+               "<div id=\"swagger-ui\"></div>\n" +
+               "<script src=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js\"></script>\n" +
+               "<script>\n" +
+               "SwaggerUIBundle({\n" +
+               "  url: \"" + specJsonPath + "\",\n" +
+               "  dom_id: '#swagger-ui',\n" +
+               "  deepLinking: true,\n" +
+               "  presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],\n" +
+               "  layout: \"BaseLayout\"\n" +
+               "});\n" +
+               "</script>\n" +
+               "</body>\n" +
+               "</html>";
+    }
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java
new file mode 100644
index 0000000..e74c82a
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityContributor.java
@@ -0,0 +1,49 @@
+package dev.relism.ext.openapi;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Pluggable security scheme contributor for the OpenAPI spec.
+ *
+ * <p>Extensions that enforce authentication (e.g. {@code flash-ext-oidc}) implement
+ * this interface and register an instance into {@link OpenApiSecurityRegistry} via the
+ * {@link dev.relism.extension.ExtensionContext}. {@link OpenApiExtension} picks it up
+ * at spec-generation time — no coupling between the two extensions at install time.
+ *
+ * <p>Multi-tenant: multiple contributors may coexist. For handlers secured by
+ * {@code @Authenticated}/{@code @RolesAllowed}, each matching contributor adds its
+ * own entry to the operation's {@code security} array (OpenAPI OR semantics).
+ */
+public interface OpenApiSecurityContributor {
+
+    /**
+     * Unique scheme name used as a key in {@code components.securitySchemes}
+     * and referenced from each operation's {@code security} array.
+     */
+    String schemeName();
+
+    /**
+     * The OpenAPI security scheme definition object placed under
+     * {@code components.securitySchemes.<schemeName>}.
+     *
+     * <p>Example for OIDC:
+     * <pre>{@code
+     * Map.of("type", "openIdConnect",
+     *        "openIdConnectUrl", "https://idp.example.com/.well-known/openid-configuration")
+     * }</pre>
+     */
+    Map<String, Object> schemeDefinition();
+
+    /**
+     * Returns the scopes/roles required for the given handler class under this scheme,
+     * or {@code null} if this contributor does not secure the handler.
+     *
+     * <ul>
+     *   <li>{@code null}       — handler is not secured by this contributor (skip)</li>
+     *   <li>empty list         — handler requires authentication, no specific scopes</li>
+     *   <li>non-empty list     — handler requires these scopes/roles</li>
+     * </ul>
+     */
+    List<String> requiredFor(Class<?> handlerClass);
+}
diff --git a/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java
new file mode 100644
index 0000000..777ede7
--- /dev/null
+++ b/flash-extensions/flash-ext-openapi/src/main/java/dev/relism/ext/openapi/OpenApiSecurityRegistry.java
@@ -0,0 +1,31 @@
+package dev.relism.ext.openapi;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * Mutable registry of {@link OpenApiSecurityContributor}s.
+ *
+ * <p>Created and provided to the {@link dev.relism.extension.ExtensionContext} by
+ * {@link OpenApiExtension} at install time. Other extensions (e.g. {@code flash-ext-oidc})
+ * retrieve it via {@code ctx.find(OpenApiSecurityRegistry.class)} and register their
+ * contributor — the OpenAPI extension then picks it up lazily at spec-generation time.
+ *
+ * <p>Thread-safe: {@link CopyOnWriteArrayList} allows concurrent reads during spec
+ * generation without blocking registration.
+ */
+public final class OpenApiSecurityRegistry {
+
+    private final List<OpenApiSecurityContributor> contributors = new CopyOnWriteArrayList<>();
+
+    /** Registers a contributor. Safe to call concurrently. */
+    public void add(OpenApiSecurityContributor contributor) {
+        contributors.add(contributor);
+    }
+
+    /** Returns an unmodifiable snapshot of all registered contributors. */
+    public List<OpenApiSecurityContributor> contributors() {
+        return Collections.unmodifiableList(contributors);
+    }
+}
diff --git a/flash-extensions/pom.xml b/flash-extensions/pom.xml
new file mode 100644
index 0000000..2db5efc
--- /dev/null
+++ b/flash-extensions/pom.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>dev.relism</groupId>
+        <artifactId>flash-parent</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>flash-extensions</artifactId>
+    <packaging>pom</packaging>
+
+    <modules>
+        <module>flash-ext-jackson</module>
+        <module>flash-ext-openapi</module>
+        <module>flash-ext-oidc</module>
+    </modules>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-ext-jackson</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.core</groupId>
+                <artifactId>jackson-databind</artifactId>
+                <version>2.17.2</version>
+            </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.dataformat</groupId>
+                <artifactId>jackson-dataformat-yaml</artifactId>
+                <version>2.17.2</version>
+            </dependency>
+            <dependency>
+                <groupId>com.nimbusds</groupId>
+                <artifactId>nimbus-jose-jwt</artifactId>
+                <version>9.37.3</version>
+            </dependency>
+            <dependency>
+                <groupId>net.minidev</groupId>
+                <artifactId>json-smart</artifactId>
+                <version>2.5.1</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+</project>
diff --git a/flash/src/main/java/dev/relism/HttpServer.java b/flash/src/main/java/dev/relism/HttpServer.java
index 6f8fa42..ac1c2f5 100644
--- a/flash/src/main/java/dev/relism/HttpServer.java
+++ b/flash/src/main/java/dev/relism/HttpServer.java
@@ -125,18 +125,37 @@ public class HttpServer {
         return this;
     }
 
-    public HttpServer register(RequestHandler handler, Middleware... m) { globalRouter.register(handler, m); return this; }
+    // ── Direct registration (called by FlashApp via RouteHandle.with()) ──────
 
-    public HttpServer get    (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.get    (path, h, m); return this; }
-    public HttpServer post   (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.post   (path, h, m); return this; }
-    public HttpServer put    (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.put    (path, h, m); return this; }
-    public HttpServer delete (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.delete (path, h, m); return this; }
-    public HttpServer patch  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.patch  (path, h, m); return this; }
-    public HttpServer options(String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.options(path, h, m); return this; }
-    public HttpServer head   (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.head   (path, h, m); return this; }
-    public HttpServer trace  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.trace  (path, h, m); return this; }
-    public HttpServer connect(String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.connect(path, h, m); return this; }
-    public HttpServer purge  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { globalRouter.purge  (path, h, m); return this; }
+    public HttpServer doRegister(dev.relism.http.HttpMethod method, String path,
+                                 SimpleHandler.FunctionalHandler handler,
+                                 dev.relism.routing.Middleware[] middlewares) {
+        globalRouter.doRegister(method, path, handler, middlewares);
+        return this;
+    }
+
+    public HttpServer doRegister(RequestHandler handler,
+                                 dev.relism.routing.Middleware[] middlewares) {
+        globalRouter.doRegister(handler, middlewares);
+        return this;
+    }
+
+    // ── Fluent registration (delegates to globalRouter) ───────────────────────
+
+    public dev.relism.routing.RouteHandle<HttpServer> register(RequestHandler handler) {
+        return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(handler, m));
+    }
+
+    public dev.relism.routing.RouteHandle<HttpServer> get    (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.GET,     path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> post   (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.POST,    path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> put    (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.PUT,     path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> delete (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.DELETE,  path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> patch  (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.PATCH,   path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> options(String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.OPTIONS, path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> head   (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.HEAD,    path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> trace  (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.TRACE,   path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> connect(String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.CONNECT, path, h, m)); }
+    public dev.relism.routing.RouteHandle<HttpServer> purge  (String path, SimpleHandler.FunctionalHandler h) { return new dev.relism.routing.RouteHandle<>(this, m -> globalRouter.doRegister(dev.relism.http.HttpMethod.PURGE,   path, h, m)); }
 
 
     private void process(Socket socket) {
diff --git a/flash/src/main/java/dev/relism/exceptions/HttpException.java b/flash/src/main/java/dev/relism/exceptions/HttpException.java
new file mode 100644
index 0000000..439ce97
--- /dev/null
+++ b/flash/src/main/java/dev/relism/exceptions/HttpException.java
@@ -0,0 +1,53 @@
+package dev.relism.exceptions;
+
+/**
+ * Runtime exception carrying an HTTP status code. Extensions map this to a
+ * structured JSON error response via the global exception handler installed by
+ * {@code flash-ext-jackson}.
+ *
+ * <pre>{@code
+ * throw HttpException.notFound("Blog");
+ * throw new HttpException(422, "Validation failed: title is required");
+ * }</pre>
+ */
+public class HttpException extends RuntimeException {
+
+    private final int status;
+
+    public HttpException(int status, String message) {
+        super(message);
+        this.status = status;
+    }
+
+    public int status() { return status; }
+
+    // ── Factory methods ───────────────────────────────────────────────────────
+
+    public static HttpException badRequest(String message) {
+        return new HttpException(400, message);
+    }
+
+    public static HttpException unauthorized() {
+        return new HttpException(401, "Unauthorized");
+    }
+
+    public static HttpException forbidden() {
+        return new HttpException(403, "Forbidden");
+    }
+
+    public static HttpException notFound(String what) {
+        return new HttpException(404, what + " not found");
+    }
+
+    public static HttpException conflict(String message) {
+        return new HttpException(409, message);
+    }
+
+    public static HttpException unprocessable(String message) {
+        return new HttpException(422, message);
+    }
+
+    public static HttpException internal(String message) {
+        return new HttpException(500, message);
+    }
+}
diff --git a/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java b/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
new file mode 100644
index 0000000..2744c71
--- /dev/null
+++ b/flash/src/main/java/dev/relism/extension/AnnotationProcessor.java
@@ -0,0 +1,22 @@
+package dev.relism.extension;
+
+import dev.relism.models.RequestHandler;
+import dev.relism.routing.Middleware;
+
+import java.util.List;
+
+/**
+ * Inspects a handler class at registration time and returns zero or more
+ * {@link Middleware middlewares} to inject automatically.
+ *
+ * <p>Processors are called once per {@link FlashApp#register} call, before
+ * the handler is compiled into the router. Returning an empty list is always
+ * valid — processors may also use the call purely for side effects
+ * (e.g. collecting OpenAPI metadata).
+ *
+ * <p>Register processors via {@link ExtensionContext#addAnnotationProcessor}.
+ */
+@FunctionalInterface
+public interface AnnotationProcessor {
+    List<Middleware> process(Class<? extends RequestHandler> handlerClass);
+}
diff --git a/flash/src/main/java/dev/relism/extension/ExtensionContext.java b/flash/src/main/java/dev/relism/extension/ExtensionContext.java
new file mode 100644
index 0000000..b0dd098
--- /dev/null
+++ b/flash/src/main/java/dev/relism/extension/ExtensionContext.java
@@ -0,0 +1,62 @@
+package dev.relism.extension;
+
+import java.util.*;
+
+/**
+ * Shared registry passed to every extension during {@link FlashExtension#install}.
+ * Extensions use it in two ways:
+ * <ol>
+ *   <li><b>Service sharing</b> — provide/require typed objects (e.g. {@code ObjectMapper},
+ *       {@code OpenApiBuilder}) so extensions can build on each other.</li>
+ *   <li><b>Annotation processing</b> — register {@link AnnotationProcessor}s that
+ *       {@link FlashApp} calls for every handler, injecting middleware derived from
+ *       annotations ({@code @RolesAllowed}, {@code @Authenticated}, etc.).</li>
+ * </ol>
+ */
+public class ExtensionContext {
+
+    private final Map<Class<?>, Object>     registry   = new LinkedHashMap<>();
+    private final List<AnnotationProcessor> processors = new ArrayList<>();
+
+    // ── Service registry ─────────────────────────────────────────────────────
+
+    /** Stores {@code instance} under {@code type} for retrieval by other extensions. */
+    public <T> void provide(Class<T> type, T instance) {
+        registry.put(type, instance);
+    }
+
+    /**
+     * Retrieves the service registered under {@code type}.
+     * Throws {@link IllegalStateException} if not present — install order matters.
+     */
+    @SuppressWarnings("unchecked")
+    public <T> T require(Class<T> type) {
+        T val = (T) registry.get(type);
+        if (val == null)
+            throw new IllegalStateException(
+                    "Extension dependency not found: " + type.getSimpleName() +
+                    " — install the required extension first");
+        return val;
+    }
+
+    /** Returns the service under {@code type}, or empty if not installed. */
+    @SuppressWarnings("unchecked")
+    public <T> Optional<T> find(Class<T> type) {
+        return Optional.ofNullable((T) registry.get(type));
+    }
+
+    // ── Annotation processors ────────────────────────────────────────────────
+
+    /**
+     * Registers an {@link AnnotationProcessor}. Called by extensions during
+     * {@link FlashExtension#install}. Processors are invoked in registration order.
+     */
+    public void addAnnotationProcessor(AnnotationProcessor processor) {
+        processors.add(processor);
+    }
+
+    /** Returns an unmodifiable view of all registered processors. */
+    List<AnnotationProcessor> processors() {
+        return Collections.unmodifiableList(processors);
+    }
+}
diff --git a/flash/src/main/java/dev/relism/extension/FlashApp.java b/flash/src/main/java/dev/relism/extension/FlashApp.java
new file mode 100644
index 0000000..636f5e4
--- /dev/null
+++ b/flash/src/main/java/dev/relism/extension/FlashApp.java
@@ -0,0 +1,182 @@
+package dev.relism.extension;
+
+import dev.relism.HttpServer;
+import dev.relism.http.HttpMethod;
+import dev.relism.models.RequestHandler;
+import dev.relism.models.SimpleHandler;
+import dev.relism.routing.AbstractRouter;
+import dev.relism.routing.Middleware;
+import dev.relism.routing.RouteHandle;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Stream;
+
+/**
+ * Primary entry point for working with Flash. Wraps {@link HttpServer} and
+ * wires the extension layer.
+ *
+ * <p>The key addition over raw {@link HttpServer} is the annotation-aware
+ * {@link #register} override: before delegating to Flash it runs all registered
+ * {@link AnnotationProcessor}s and prepends any injected middlewares
+ * (e.g. from {@code @RolesAllowed}) to the explicit ones.
+ *
+ * <p>Route registration is lazy: calling {@code get()}, {@code post()}, or
+ * {@code register()} returns a {@link RouteHandle} that is not yet registered.
+ * The route is registered automatically before the next operation or at
+ * {@link #start()}. Call {@link RouteHandle#with} explicitly to add middleware:
+ *
+ * <pre>{@code
+ * FlashApp.of(new HttpServer(config))
+ *     .install(new JacksonExtension())
+ *     .install(new OidcExtension(OidcConfig.fromEnv()))
+ *     .install(new OpenApiExtension("/openapi"))
+ *     .start();
+ *
+ * // No middleware — .with() is optional
+ * app.get("/ping",  (req, res) -> "pong");
+ * app.get("/hello", (req, res) -> "Hello");
+ *
+ * // With middleware
+ * app.get("/me",    (req, res) -> ClaimsHolder.user().email()).with(oidc.protect());
+ * app.get("/admin", (req, res) -> "secret").with(oidc.requireRole("admin"));
+ *
+ * // Class-based — @Authenticated / @RolesAllowed auto-injected, .with() optional
+ * app.register(new HomePage());
+ * app.register(new MePage());      // @Authenticated handled by annotation processor
+ * app.register(new AdminPage());   // @RolesAllowed("admin") handled automatically
+ *
+ * app.start();
+ * }</pre>
+ */
+public class FlashApp {
+
+    private final HttpServer       server;
+    private final ExtensionContext ctx = new ExtensionContext();
+
+    /** The last returned RouteHandle that has not yet been registered. */
+    private RouteHandle<?> pending;
+
+    private FlashApp(HttpServer server) {
+        this.server = server;
+    }
+
+    public static FlashApp of(HttpServer server) {
+        return new FlashApp(server);
+    }
+
+    // ── Pending flush ─────────────────────────────────────────────────────────
+
+    /**
+     * Registers any pending route (returned by the previous {@code get/post/register}
+     * call) with no middleware, if it has not already been registered via
+     * {@link RouteHandle#with}.
+     */
+    private void flushPending() {
+        if (pending != null) {
+            pending.ensureRegistered();
+            pending = null;
+        }
+    }
+
+    private <P> RouteHandle<P> pending(RouteHandle<P> handle) {
+        flushPending();
+        pending = handle;
+        return handle;
+    }
+
+    // ── Extension installation ────────────────────────────────────────────────
+
+    public FlashApp install(FlashExtension ext) {
+        flushPending();
+        ext.install(this, ctx);
+        return this;
+    }
+
+    /** Exposes the context so callers can retrieve services installed by extensions. */
+    public ExtensionContext ctx() {
+        return ctx;
+    }
+
+    // ── Handler registration (annotation-aware) ───────────────────────────────
+
+    /**
+     * Begins registration of a class-based handler. Before registering, all
+     * {@link AnnotationProcessor}s are called (e.g. to inject OIDC middleware from
+     * {@code @Authenticated} / {@code @RolesAllowed}). Their middlewares are prepended
+     * outermost to any extra middlewares supplied via {@link RouteHandle#with}.
+     *
+     * <p>Calling {@link RouteHandle#with} is optional when no extra middleware is needed —
+     * the route is registered automatically before the next operation or at {@link #start()}.
+     *
+     * <p>Middleware execution order: injected (from annotations) → explicit (.with()) → handler.
+     */
+    public RouteHandle<FlashApp> register(RequestHandler handler) {
+        return pending(new RouteHandle<>(this, explicit -> {
+            List<Middleware> injected = ctx.processors().stream()
+                    .flatMap(p -> p.process(handler.getClass()).stream())
+                    .toList();
+            Middleware[] all = injected.isEmpty()
+                    ? explicit
+                    : Stream.concat(injected.stream(), Arrays.stream(explicit))
+                            .toArray(Middleware[]::new);
+            server.doRegister(handler, all);
+        }));
+    }
+
+    // ── Lambda route registration ─────────────────────────────────────────────
+
+    /**
+     * Begins registration of a lambda route. Calling {@link RouteHandle#with} is
+     * optional when no middleware is needed — the route is registered automatically
+     * before the next operation or at {@link #start()}.
+     *
+     * <pre>{@code
+     * app.get("/ping",  (req, res) -> "pong");                              // no middleware
+     * app.get("/me",    (req, res) -> ClaimsHolder.user().email())
+     *    .with(oidc.protect());                                             // with middleware
+     * }</pre>
+     */
+    public RouteHandle<FlashApp> get    (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.GET,     path, h, m))); }
+    public RouteHandle<FlashApp> post   (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.POST,    path, h, m))); }
+    public RouteHandle<FlashApp> put    (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.PUT,     path, h, m))); }
+    public RouteHandle<FlashApp> delete (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.DELETE,  path, h, m))); }
+    public RouteHandle<FlashApp> patch  (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.PATCH,   path, h, m))); }
+    public RouteHandle<FlashApp> options(String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.OPTIONS, path, h, m))); }
+    public RouteHandle<FlashApp> head   (String path, SimpleHandler.FunctionalHandler h) { return pending(new RouteHandle<>(this, m -> server.doRegister(HttpMethod.HEAD,    path, h, m))); }
+
+    public FlashApp mount(String namespace, AbstractRouter router) {
+        flushPending();
+        server.mount(namespace, router);
+        return this;
+    }
+
+    public FlashApp onException(AbstractRouter.ExceptionHandler handler) {
+        flushPending();
+        server.onException(handler);
+        return this;
+    }
+
+    public FlashApp onNotFound(SimpleHandler.FunctionalHandler handler) {
+        flushPending();
+        server.onNotFound(handler);
+        return this;
+    }
+
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    public CompletableFuture<Void> start() {
+        flushPending();
+        return server.start();
+    }
+
+    public CompletableFuture<Void> stop() {
+        return server.stop();
+    }
+
+    /** Direct access to the underlying server for advanced use cases. */
+    public HttpServer server() {
+        return server;
+    }
+}
diff --git a/flash/src/main/java/dev/relism/extension/FlashExtension.java b/flash/src/main/java/dev/relism/extension/FlashExtension.java
new file mode 100644
index 0000000..07615d6
--- /dev/null
+++ b/flash/src/main/java/dev/relism/extension/FlashExtension.java
@@ -0,0 +1,25 @@
+package dev.relism.extension;
+
+/**
+ * Contract for all Flash extensions. An extension receives the full {@link FlashApp}
+ * so it can both register handlers on the server and expose services through
+ * {@link ExtensionContext} for other extensions.
+ *
+ * <pre>{@code
+ * public class OpenApiExtension implements FlashExtension {
+ *     public void install(FlashApp app, ExtensionContext ctx) {
+ *         ObjectMapper mapper = ctx.require(ObjectMapper.class);
+ *         app.get("/openapi.json", (req, res) -> mapper.writeValueAsString(spec));
+ *     }
+ * }
+ *
+ * FlashApp.of(new HttpServer(config))
+ *     .install(new JacksonExtension())
+ *     .install(new OpenApiExtension("/openapi.json"))
+ *     .install(new OidcExtension(OidcConfig.fromEnv()));
+ * }</pre>
+ */
+@FunctionalInterface
+public interface FlashExtension {
+    void install(FlashApp app, ExtensionContext ctx);
+}
diff --git a/flash/src/main/java/dev/relism/models/RequestHelper.java b/flash/src/main/java/dev/relism/models/RequestHelper.java
new file mode 100644
index 0000000..0e71541
--- /dev/null
+++ b/flash/src/main/java/dev/relism/models/RequestHelper.java
@@ -0,0 +1,106 @@
+package dev.relism.models;
+
+import dev.relism.exceptions.HttpException;
+
+/**
+ * Typed accessors for request parameters. All methods throw
+ * {@link HttpException} (400) on missing or malformed input, so handlers
+ * do not need to write per-field validation boilerplate.
+ *
+ * <pre>{@code
+ * int  page = RequestHelper.queryInt(req, "page", 1, 100);
+ * long id   = RequestHelper.paramLong(req, "id");
+ * String q  = RequestHelper.queryRequired(req, "q");
+ * }</pre>
+ */
+public final class RequestHelper {
+
+    private RequestHelper() {}
+
+    // ── Query parameters ──────────────────────────────────────────────────────
+
+    /**
+     * Returns the query param as an int, or {@code defaultValue} if absent.
+     * Caps the result at {@code max}. Throws 400 on non-integer input.
+     */
+    public static int queryInt(Request req, String name, int defaultValue, int max) {
+        String v = req.query(name);
+        if (v == null || v.isEmpty()) return defaultValue;
+        try {
+            return Math.min(Integer.parseInt(v), max);
+        } catch (NumberFormatException e) {
+            throw HttpException.badRequest("Invalid integer for query param '" + name + "': " + v);
+        }
+    }
+
+    /**
+     * Returns the query param value. Throws 400 if absent or blank.
+     */
+    public static String queryRequired(Request req, String name) {
+        String v = req.query(name);
+        if (v == null || v.isBlank())
+            throw HttpException.badRequest("Missing required query param: " + name);
+        return v;
+    }
+
+    /**
+     * Returns the query param, or {@code null} if absent.
+     */
+    public static String queryOptional(Request req, String name) {
+        return req.query(name);
+    }
+
+    /**
+     * Returns the query param as a long, or {@code defaultValue} if absent.
+     * Throws 400 on non-long input.
+     */
+    public static long queryLong(Request req, String name, long defaultValue) {
+        String v = req.query(name);
+        if (v == null || v.isEmpty()) return defaultValue;
+        try {
+            return Long.parseLong(v);
+        } catch (NumberFormatException e) {
+            throw HttpException.badRequest("Invalid long for query param '" + name + "': " + v);
+        }
+    }
+
+    // ── Path parameters ───────────────────────────────────────────────────────
+
+    /**
+     * Returns the path parameter as a long. Throws 400 if absent or non-long.
+     */
+    public static long paramLong(Request req, String name) {
+        String v = req.param(name);
+        if (v == null)
+            throw HttpException.badRequest("Missing path param: " + name);
+        try {
+            return Long.parseLong(v);
+        } catch (NumberFormatException e) {
+            throw HttpException.badRequest("Invalid long for path param '" + name + "': " + v);
+        }
+    }
+
+    /**
+     * Returns the path parameter as an int. Throws 400 if absent or non-int.
+     */
+    public static int paramInt(Request req, String name) {
+        String v = req.param(name);
+        if (v == null)
+            throw HttpException.badRequest("Missing path param: " + name);
+        try {
+            return Integer.parseInt(v);
+        } catch (NumberFormatException e) {
+            throw HttpException.badRequest("Invalid int for path param '" + name + "': " + v);
+        }
+    }
+
+    /**
+     * Returns the path parameter as a String. Throws 400 if absent.
+     */
+    public static String paramRequired(Request req, String name) {
+        String v = req.param(name);
+        if (v == null)
+            throw HttpException.badRequest("Missing path param: " + name);
+        return v;
+    }
+}
diff --git a/flash/src/main/java/dev/relism/routing/AbstractRouter.java b/flash/src/main/java/dev/relism/routing/AbstractRouter.java
index dd75354..c3f61c7 100644
--- a/flash/src/main/java/dev/relism/routing/AbstractRouter.java
+++ b/flash/src/main/java/dev/relism/routing/AbstractRouter.java
@@ -90,8 +90,6 @@ public abstract class AbstractRouter {
         return compiled;
     }
 
-    private static final Middleware[] NO_MIDDLEWARES = new Middleware[0];
-
     // ── Error handler configuration ───────────────────────────────────────────
 
     public AbstractRouter onNotFound(SimpleHandler.FunctionalHandler handler) {
@@ -104,38 +102,23 @@ public abstract class AbstractRouter {
         return this;
     }
 
-    // ── Lambda handler registration ───────────────────────────────────────────
+    // ── Internal registration (package-private) ───────────────────────────────
 
     /**
-     * Registers a lambda handler with optional handler-level middlewares.
-     * Router-level middlewares are applied automatically on top.
+     * Registers a lambda handler immediately with a pre-built middleware array.
+     * Called by {@link RouteHandle#with} and by {@link dev.relism.extension.FlashApp}.
      */
-    public AbstractRouter register(HttpMethod method, String path,
-                                   SimpleHandler.FunctionalHandler handler,
-                                   Middleware... middlewares) {
+    public AbstractRouter doRegister(HttpMethod method, String path,
+                                     SimpleHandler.FunctionalHandler handler, Middleware[] middlewares) {
         return addRoute(method, PathUtils.sanitize(path),
                 compile(new SimpleHandler(handler), middlewares));
     }
 
-    public AbstractRouter get    (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.GET,     path, h, m); }
-    public AbstractRouter post   (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.POST,    path, h, m); }
-    public AbstractRouter put    (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.PUT,     path, h, m); }
-    public AbstractRouter delete (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.DELETE,  path, h, m); }
-    public AbstractRouter patch  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.PATCH,   path, h, m); }
-    public AbstractRouter options(String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.OPTIONS, path, h, m); }
-    public AbstractRouter head   (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.HEAD,    path, h, m); }
-    public AbstractRouter trace  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.TRACE,   path, h, m); }
-    public AbstractRouter connect(String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.CONNECT, path, h, m); }
-    public AbstractRouter purge  (String path, SimpleHandler.FunctionalHandler h, Middleware... m) { return register(HttpMethod.PURGE,   path, h, m); }
-
-    // ── Class-based handler registration ─────────────────────────────────────
-
     /**
-     * Registers a class-based handler with optional handler-level middlewares.
-     * The class must carry a {@link Route @Route} annotation declaring method and path.
-     * Router-level middlewares are applied automatically on top.
+     * Registers a class-based handler immediately with a pre-built middleware array.
+     * Called by {@link RouteHandle#with} and by {@link dev.relism.extension.FlashApp}.
      */
-    public AbstractRouter register(RequestHandler handler, Middleware... middlewares) {
+    public AbstractRouter doRegister(RequestHandler handler, Middleware[] middlewares) {
         Route annotation = handler.getClass().getAnnotation(Route.class);
         if (annotation != null)
             addRoute(annotation.method(), annotation.path(),
@@ -143,6 +126,44 @@ public abstract class AbstractRouter {
         return this;
     }
 
+    // ── Lambda handler registration ───────────────────────────────────────────
+
+    /**
+     * Begins registration of a lambda handler. Call {@link RouteHandle#with} on the
+     * returned handle to supply middlewares (if any) and complete the registration.
+     *
+     * <pre>{@code
+     * router.get("/ping",  (req, res) -> "pong").with();
+     * router.get("/admin", adminHandler).with(auth, logging);
+     * }</pre>
+     */
+    public RouteHandle<AbstractRouter> get    (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.GET,     path, h, m)); }
+    public RouteHandle<AbstractRouter> post   (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.POST,    path, h, m)); }
+    public RouteHandle<AbstractRouter> put    (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.PUT,     path, h, m)); }
+    public RouteHandle<AbstractRouter> delete (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.DELETE,  path, h, m)); }
+    public RouteHandle<AbstractRouter> patch  (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.PATCH,   path, h, m)); }
+    public RouteHandle<AbstractRouter> options(String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.OPTIONS, path, h, m)); }
+    public RouteHandle<AbstractRouter> head   (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.HEAD,    path, h, m)); }
+    public RouteHandle<AbstractRouter> trace  (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.TRACE,   path, h, m)); }
+    public RouteHandle<AbstractRouter> connect(String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.CONNECT, path, h, m)); }
+    public RouteHandle<AbstractRouter> purge  (String path, SimpleHandler.FunctionalHandler h) { return new RouteHandle<>(this, m -> doRegister(HttpMethod.PURGE,   path, h, m)); }
+
+    // ── Class-based handler registration ─────────────────────────────────────
+
+    /**
+     * Begins registration of a class-based handler. The class must carry a
+     * {@link Route @Route} annotation. Call {@link RouteHandle#with} to supply
+     * optional extra middlewares and complete the registration.
+     *
+     * <pre>{@code
+     * router.register(new BlogHandler()).with();
+     * router.register(new AdminHandler()).with(logging);
+     * }</pre>
+     */
+    public RouteHandle<AbstractRouter> register(RequestHandler handler) {
+        return new RouteHandle<>(this, m -> doRegister(handler, m));
+    }
+
     // ── Routing ───────────────────────────────────────────────────────────────
 
     public abstract RequestHandler route(Request request);
diff --git a/flash/src/main/java/dev/relism/routing/RouteHandle.java b/flash/src/main/java/dev/relism/routing/RouteHandle.java
new file mode 100644
index 0000000..20a1ffd
--- /dev/null
+++ b/flash/src/main/java/dev/relism/routing/RouteHandle.java
@@ -0,0 +1,70 @@
+package dev.relism.routing;
+
+import java.util.function.Consumer;
+
+/**
+ * Deferred route registration handle returned by {@code router.get()},
+ * {@code router.post()}, {@code app.get()}, {@code app.register()}, etc.
+ *
+ * <p>The route is <em>not</em> registered until {@link #with} is called.
+ * This separates the handler declaration from the middleware declaration,
+ * keeping the registration methods clean.
+ *
+ * <pre>{@code
+ * // No middleware
+ * app.get("/ping", (req, res) -> "pong").with();
+ *
+ * // With middleware
+ * app.get("/me",    (req, res) -> ClaimsHolder.user().email()).with(oidc.protect());
+ * app.get("/admin", (req, res) -> "admin").with(oidc.requireRole("admin"));
+ *
+ * // Class-based handler — annotations (@Authenticated, @RolesAllowed) are
+ * // processed automatically; .with() can add extra middleware on top.
+ * app.register(new MyHandler()).with();
+ * app.register(new SecuredHandler()).with(logging);
+ * }</pre>
+ *
+ * @param <P> the parent type returned by {@link #with} for further chaining
+ *            ({@link dev.relism.extension.FlashApp} or {@link AbstractRouter})
+ */
+public final class RouteHandle<P> {
+
+    private final P parent;
+    private final Consumer<Middleware[]> registerFn;
+    private boolean registered = false;
+
+    public RouteHandle(P parent, Consumer<Middleware[]> registerFn) {
+        this.parent = parent;
+        this.registerFn = registerFn;
+    }
+
+    /**
+     * Registers the route with the given middlewares and returns the parent
+     * for further chaining.
+     *
+     * <p>Calling without arguments is equivalent to registering with no middleware.
+     * When using {@link dev.relism.extension.FlashApp}, calling {@code .with()} is
+     * optional for routes that need no middleware — the route is registered
+     * automatically before the next operation or at {@code start()}.
+     *
+     * @param middlewares zero or more middlewares; first element executes outermost
+     * @return the parent ({@link dev.relism.extension.FlashApp} or
+     *         {@link AbstractRouter}) for further method chaining
+     */
+    public P with(Middleware... middlewares) {
+        if (!registered) {
+            registerFn.accept(middlewares);
+            registered = true;
+        }
+        return parent;
+    }
+
+    /**
+     * Registers the route with no middleware if it has not been registered yet.
+     * Called automatically by {@link dev.relism.extension.FlashApp} before each
+     * new route registration and at {@code start()}.
+     */
+    public void ensureRegistered() {
+        with();
+    }
+}
diff --git a/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java b/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
index b49b5d0..5d502e6 100644
--- a/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
+++ b/flash/src/test/java/dev/relism/HttpServerConcurrencyTest.java
@@ -38,11 +38,11 @@ class HttpServerConcurrencyTest {
                 .build();
 
         server = new HttpServer(config);
-        server.get("/ping", (req, res) -> "pong");
+        server.get("/ping", (req, res) -> "pong").with();
         server.post("/echo", (req, res) -> {
             byte[] body = req.body().bytes();
             return new Response(200, body, ContentType.TEXT_PLAIN);
-        });
+        }).with();
 
         server.start().get(5, TimeUnit.SECONDS);
 
@@ -187,7 +187,7 @@ class HttpServerConcurrencyTest {
 
         for (int i = 0; i < 10; i++) {
             final int idx = i;
-            freshServer.get("/route" + idx, (req, res) -> "handler" + idx);
+            freshServer.get("/route" + idx, (req, res) -> "handler" + idx).with();
         }
 
         freshServer.start().get(5, TimeUnit.SECONDS);
diff --git a/flash/src/test/java/dev/relism/HttpServerTest.java b/flash/src/test/java/dev/relism/HttpServerTest.java
index ccbd298..3f40e1b 100644
--- a/flash/src/test/java/dev/relism/HttpServerTest.java
+++ b/flash/src/test/java/dev/relism/HttpServerTest.java
@@ -37,31 +37,31 @@ class HttpServerTest {
         server = new HttpServer(config);
         
         // Setup some routes
-        server.get("/api/ping", (req, res) -> "pong");
-        
+        server.get("/api/ping", (req, res) -> "pong").with();
+
         server.post("/api/echo", (req, res) -> {
             byte[] body = req.body().bytes();
             return res.status(201).body(body); // echo body & change status
-        });
+        }).with();
 
         server.get("/api/crash", (req, res) -> {
             throw new RuntimeException("Simulated Crash");
-        });
+        }).with();
 
         byte[] streamData = "streaming response body".getBytes(StandardCharsets.UTF_8);
         server.get("/api/stream", (req, res) ->
-                res.stream(new ByteArrayInputStream(streamData), streamData.length));
+                res.stream(new ByteArrayInputStream(streamData), streamData.length)).with();
 
         server.get("/api/chunked-out", (req, res) ->
-                res.chunked(new ByteArrayInputStream(streamData)));
+                res.chunked(new ByteArrayInputStream(streamData))).with();
 
         server.get("/api/custom-header", (req, res) ->
-                res.body("ok").header("X-Flash", "works"));
+                res.body("ok").header("X-Flash", "works")).with();
 
         server.post("/api/chunked-in", (req, res) -> {
             byte[] body = req.body().bytes();
             return res.body(body);
-        });
+        }).with();
 
         server.start().get(5, TimeUnit.SECONDS);
     }
diff --git a/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java b/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
index 0821722..3ef8e61 100644
--- a/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
+++ b/flash/src/test/java/dev/relism/routing/AbstractRouterTest.java
@@ -34,7 +34,7 @@ class AbstractRouterTest {
         }
     }
 
-    @Route(method = "POST", path = "/profile")
+    @Route(method = dev.relism.http.HttpMethod.POST, path = "/profile")
     static class ProfileHandler extends RequestHandler {
         @Override
         public Object handle(Request request, Response response) {
@@ -68,18 +68,18 @@ class AbstractRouterTest {
         DummyRouter router = new DummyRouter();
         SimpleHandler.FunctionalHandler func = (req, res) -> "OK";
 
-        router.get("users/", func);
+        router.get("users/", func).with();
         assertEquals(HttpMethod.GET, router.lastAddedMethod);
         assertEquals("/users", router.lastAddedPath);
         assertTrue(router.lastAddedHandler instanceof SimpleHandler);
 
-        router.post("/items", func);
+        router.post("/items", func).with();
         assertEquals(HttpMethod.POST, router.lastAddedMethod);
 
-        router.put("update", func);
+        router.put("update", func).with();
         assertEquals(HttpMethod.PUT, router.lastAddedMethod);
 
-        router.delete("//delete//", func);
+        router.delete("//delete//", func).with();
         assertEquals(HttpMethod.DELETE, router.lastAddedMethod);
         assertEquals("/delete", router.lastAddedPath);
     }
@@ -90,9 +90,9 @@ class AbstractRouterTest {
     void register_annotatedHandler_addsRoute() {
         DummyRouter router = new DummyRouter();
         ProfileHandler handler = new ProfileHandler();
-        
-        router.register(handler);
-        
+
+        router.register(handler).with();
+
         assertEquals(HttpMethod.POST, router.lastAddedMethod);
         assertEquals("/profile", router.lastAddedPath);
         assertEquals(handler, router.lastAddedHandler);
@@ -101,7 +101,7 @@ class AbstractRouterTest {
     @Test
     void register_unannotatedHandler_doesNothing() {
         DummyRouter router = new DummyRouter();
-        router.register(new UnannotatedHandler());
+        router.register(new UnannotatedHandler()).with();
         assertNull(router.lastAddedMethod); // Nothing added
     }
 
diff --git a/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java b/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java
index 3309270..976fe3b 100644
--- a/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java
+++ b/flash/src/test/java/dev/relism/routing/GlobalRouterTest.java
@@ -75,7 +75,7 @@ class GlobalRouterTest {
         GlobalRouter global = new GlobalRouter();
         RequestHandler internalHandler = new SimpleHandler((req, res) -> "internal");
         
-        global.get("/hello", (req, res) -> "internal");
+        global.get("/hello", (req, res) -> "internal").with();
         // We know it routes to internal. Let's send a request.
         RequestHandler resolved = global.route(mockRequest("/hello"));
         assertNotNull(resolved);
diff --git a/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java b/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java
index 5f0e226..56a7d5e 100644
--- a/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java
+++ b/flash/src/test/java/dev/relism/routing/routers/fastpathrouter/FastPathRouterImplTest.java
@@ -34,8 +34,8 @@ class FastPathRouterImplTest {
     void route_lazyCompilationAndMatch() throws Exception {
         FastPathRouterImpl router = new FastPathRouterImpl();
         
-        router.get("/a", (req, res) -> "A");
-        router.post("/b", (req, res) -> "B");
+        router.get("/a", (req, res) -> "A").with();
+        router.post("/b", (req, res) -> "B").with();
 
         RequestHandler res1 = router.route(mockRequest(HttpMethod.GET, "/a"));
         assertNotNull(res1);
@@ -49,7 +49,7 @@ class FastPathRouterImplTest {
     @Test
     void route_noMatch_returnsNull() {
         FastPathRouterImpl router = new FastPathRouterImpl();
-        router.get("/a", (req, res) -> "A");
+        router.get("/a", (req, res) -> "A").with();
 
         assertNull(router.route(mockRequest(HttpMethod.GET, "/b")));
         // Wrong method
@@ -60,7 +60,7 @@ class FastPathRouterImplTest {
     void route_extractsPathParams() throws Exception {
         FastPathRouterImpl router = new FastPathRouterImpl();
         
-        router.get("/users/{id}/items/{itemId}", (req, res) -> "Extract");
+        router.get("/users/{id}/items/{itemId}", (req, res) -> "Extract").with();
 
         Request request = mockRequest(HttpMethod.GET, "/users/123/items/456");
         RequestHandler handler = router.route(request);
diff --git a/pom.xml b/pom.xml
index 61f2318..ab5a12d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -11,6 +11,8 @@
 
     <modules>
         <module>flash</module>
+        <module>flash-extensions</module>
+        <module>flash-bench</module>
     </modules>
 
     <properties>
@@ -36,6 +38,21 @@
                 <artifactId>flash</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-ext-jackson</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-ext-openapi</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>dev.relism</groupId>
+                <artifactId>flash-ext-oidc</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>dev.relism</groupId>
                 <artifactId>fpr-core</artifactId>