Release 0.5.0: Refactor session storage and client validation DSL

Major changes:
- Extract session storage to ktor-bearer-sessions module
- Refactor client validation into clients {} DSL block
  - registration {} for public clients via RFC 7591 dynamic registration
  - credentials {} for confidential clients at /token (RFC 6749)
- Move credentials validation from /authorize to /token per RFC 6749
- Simplify provision flow with native Ktor routing (call.provision)
- Add direct session access for SSE/WebSocket contexts
- Refactor claims: use AesGcmEncryption, simplify ProvisionClaims
- Separate flow identity vs client identity architecture

Breaking changes:
- Session storage APIs moved to ktor-bearer-sessions
- Client validation now uses clients { registration, credentials } DSL
- Provision route setup uses call.provision instead of custom DSL

Author: pmokbel

README.md

@@ -60,7 +60,7 @@ Many applications need user-provided configuration that OAuth alone can't handle
 
 ```kotlin
 dependencies {
-    implementation("com.vcontrol:ktor-server-oauth:0.4.10")
+    implementation("com.vcontrol:ktor-server-oauth:0.5.0")
 }
 ```
 
@@ -76,8 +76,10 @@ import io.ktor.server.routing.*
 fun Application.module() {
     // 1. Install OAuth plugin with local authorization server
     install(OAuth) {
-        authorizationServer(LocalAuthServer) {
-            openRegistration = true
+        server {
+            clients {
+                registration = true  // Accept all registrations
+            }
         }
     }
 
@@ -131,25 +133,72 @@ The plugin automatically configures these endpoints:
 | `GET /.well-known/oauth-authorization-server` | Authorization server metadata |
 | `GET /.well-known/oauth-protected-resource` | Protected resource metadata |
 
+## Error Responses
+
+All error responses follow [RFC 6749 Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2):
+
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "Invalid or expired authorization code"
+}
+```
+
+| Error Code | HTTP Status | When |
+|------------|-------------|------|
+| `invalid_request` | 400 | Missing or malformed parameters |
+| `invalid_client` | 401 | Bad client_id or client_secret |
+| `invalid_grant` | 400 | Expired/invalid auth code, PKCE failure, redirect_uri mismatch |
+| `unsupported_grant_type` | 400 | Grant type not enabled |
+
+For `invalid_client`, the response includes a `WWW-Authenticate: Bearer` header per RFC 6750.
+
+Protected routes (behind `authenticate { }`) return `401 Unauthorized` with `WWW-Authenticate: Bearer` for missing/invalid/expired tokens - this is standard Ktor JWT authentication behavior.
+
+## Defaults
+
+| Setting | Default | Notes                                  |
+|---------|---------|----------------------------------------|
+| Token expiration | 90 days | JWT `exp` claim                        |
+| Session TTL | 90 days | Matches token lifetime                 |
+| Session storage | File-based | `~/.ktor-oauth/sessions/`              |
+| Session encryption | Enabled | AES-256-GCM with per-client key in JWT |
+| Session cleanup | Enabled, 1 hour | Removes expired session files          |
+| Route prefix | `/.oauth` | All internal endpoints under this path |
+| Auth code storage | In-memory | Lost on restart (stateless by design)  |
+
+**Security notes:**
+- JWT signing key is auto-generated and stored at `~/.ktor-oauth/jwt.secret`
+- Session encryption keys are embedded in each JWT token, so sessions can only be decrypted by the token holder
+- Without cleanup, session files accumulate on disk (one file per session per type)
+
 ## Configuration
 
 ### Plugin Configuration
 
 ```kotlin
 install(OAuth) {
-    authorizationServer(LocalAuthServer) {
-        // Enable/disable dynamic client registration
-        openRegistration = true
+    server {
+        // Client validation
+        clients {
+            // Dynamic registration (RFC 7591)
+            // Has access to: origin, headers, resource, request
+            registration = true  // or:
+            // registration { clientId, clientName ->
+            //     origin.remoteHost in allowedIps
+            // }
+
+            // Client credentials grant
+            // Has access to: origin, headers, resource, request
+            credentials { clientId, secret ->
+                origin.remoteHost !in blockedIps && db.check(clientId, secret)
+            }
+            // Or static: credentials("app" to "secret", "app2" to "secret2")
+        }
 
         // Token lifetime
         tokenExpiration = 90.days
 
-        // Global client blocklist
-        client { clientId -> clientId !in blockedClients }
-
-        // Client credentials grant validation
-        clientCredentials { id, secret -> validateCredentials(id, secret) }
-
         // Custom JWT claims
         claims(SessionKeyClaimsProvider)
         claims { builder, clientId ->
@@ -223,8 +272,46 @@ Or via application.conf:
 oauth.sessions.cleanup.interval = "PT1H"
 ```
 
-Cleanup is disabled by default. The job runs on the configured interval and properly
-shuts down when the application stops.
+Cleanup is enabled by default (1 hour interval). The job runs on the configured interval
+and properly shuts down when the application stops.
+
+### Relationship with Ktor Sessions
+
+`OAuthSessions` internally installs Ktor's `Sessions` plugin - do not install both.
+
+```kotlin
+// ✅ Correct - OAuthSessions manages Sessions internally
+install(OAuthSessions) {
+    session<MySession>()
+}
+
+// ❌ Wrong - will conflict
+install(Sessions) { ... }  // Don't do this
+install(OAuthSessions) { ... }
+```
+
+**What OAuthSessions provides:**
+
+- Bearer-bound sessions (`session<T>()`) - stored server-side, keyed by JWT claims
+- Standard Ktor sessions (`cookie<T>()`, `header<T>()`) - available through the same DSL
+- Internal OAuth cookies (auth_request, provision_session)
+
+**Mixing session types:**
+
+```kotlin
+install(OAuthSessions) {
+    // Bearer-bound session (server-side, keyed by JWT)
+    session<UserPreferences>()
+
+    // Standard Ktor cookie session (for non-OAuth flows)
+    cookie<AdminSession>("admin_session") {
+        cookie.httpOnly = true
+        cookie.secure = true
+    }
+}
+```
+
+Both session types use `call.sessions.get<T>()` / `call.sessions.set<T>()` - the transport is determined by how they're registered.
 
 ### application.conf
 

build.gradle.kts

@@ -1,7 +1,7 @@
 plugins {
     id("buildsrc.convention.kotlin-jvm")
     `java-library`
-    alias(libs.plugins.kotlinPluginSerialization)
+    alias(libs.plugins.kotlin.plugin.serialization)
     id("com.vanniktech.maven.publish") version "0.30.0"
 }
 
@@ -11,38 +11,41 @@ version = file("version.properties")
 
 dependencies {
     // Ktor BOM for version alignment
-    api(platform(libs.ktorBom))
+    api(platform(libs.ktor.bom))
 
     // Coroutines
-    implementation(libs.kotlinxCoroutines)
+    implementation(libs.kotlinx.coroutines)
 
     // Kotlin serialization
-    implementation(libs.kotlinxSerialization)
+    implementation(libs.kotlinx.serialization)
 
     // Ktor server
-    implementation(libs.ktorServerCore)
-    api(libs.ktorServerAuth)
-    api(libs.ktorServerAuthJwt)
-    implementation(libs.ktorServerContentNegotiation)
-    implementation(libs.ktorSerializationJson)
-    implementation(libs.ktorServerStatusPages)
-    implementation(libs.ktorServerForwardedHeader)
-    api(libs.ktorServerSessions)
+    implementation(libs.ktor.server.core)
+    api(libs.ktor.server.auth)
+    api(libs.ktor.server.auth.jwt)
+    implementation(libs.ktor.server.content.negotiation)
+    implementation(libs.ktor.serialization.json)
+    implementation(libs.ktor.server.status.pages)
+    implementation(libs.ktor.server.forwarded.header)
+    api(libs.ktor.server.sessions)
+
+    // Bearer sessions (shared session storage infrastructure)
+    api("com.vcontrol:ktor-bearer-sessions:0.2.0")
 
     // JWT
-    implementation(libs.javaJwt)
+    implementation(libs.java.jwt)
 
     // Logging
-    api(libs.kotlinLogging)
+    api(libs.kotlin.logging)
 
     // Test dependencies
     testImplementation(kotlin("test"))
-    testImplementation(libs.kotlinxCoroutines)
-    testImplementation(libs.ktorServerTests)
-    testImplementation(libs.ktorServerCio)
-    testImplementation(libs.ktorClientContentNegotiation)
-    testImplementation(libs.ktorSerializationJson)
-    testImplementation(libs.slf4jSimple)
+    testImplementation(libs.kotlinx.coroutines)
+    testImplementation(libs.ktor.server.tests)
+    testImplementation(libs.ktor.server.cio)
+    testImplementation(libs.ktor.client.content.negotiation)
+    testImplementation(libs.ktor.serialization.json)
+    testImplementation(libs.slf4j.simple)
 }
 
 // Generate version file for runtime access

buildSrc/build.gradle.kts

@@ -11,5 +11,5 @@ kotlin {
 }
 
 dependencies {
-    implementation(libs.kotlinGradlePlugin)
+    implementation(libs.kotlin.gradle.plugin)
 }

gradle/libs.versions.toml

@@ -1,41 +1,41 @@
 [versions]
 kotlin = "2.2.20"
-kotlinxSerializationJSON = "1.8.1"
-kotlinxCoroutines = "1.10.2"
+kotlinx-serialization-json = "1.8.1"
+kotlinx-coroutines = "1.10.2"
 ktor = "3.3.0"
-kotlinLogging = "7.0.3"
-javaJwt = "4.4.0"
+kotlin-logging = "7.0.3"
+java-jwt = "4.4.0"
 slf4j = "2.0.16"
 
 [libraries]
-kotlinGradlePlugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
-kotlinxSerialization = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationJSON" }
-kotlinxCoroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinxCoroutines" }
+kotlin-gradle-plugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
+kotlinx-serialization = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization-json" }
+kotlinx-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
 
 # Ktor BOM for version alignment
-ktorBom = { module = "io.ktor:ktor-bom", version.ref = "ktor" }
+ktor-bom = { module = "io.ktor:ktor-bom", version.ref = "ktor" }
 
 # Ktor Server
-ktorServerCore = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
-ktorServerCio = { module = "io.ktor:ktor-server-cio", version.ref = "ktor" }
-ktorServerAuth = { module = "io.ktor:ktor-server-auth", version.ref = "ktor" }
-ktorServerAuthJwt = { module = "io.ktor:ktor-server-auth-jwt", version.ref = "ktor" }
-ktorServerContentNegotiation = { module = "io.ktor:ktor-server-content-negotiation", version.ref = "ktor" }
-ktorSerializationJson = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
-ktorServerStatusPages = { module = "io.ktor:ktor-server-status-pages", version.ref = "ktor" }
-ktorServerForwardedHeader = { module = "io.ktor:ktor-server-forwarded-header", version.ref = "ktor" }
-ktorServerSessions = { module = "io.ktor:ktor-server-sessions", version.ref = "ktor" }
-ktorServerTests = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor" }
+ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
+ktor-server-cio = { module = "io.ktor:ktor-server-cio", version.ref = "ktor" }
+ktor-server-auth = { module = "io.ktor:ktor-server-auth", version.ref = "ktor" }
+ktor-server-auth-jwt = { module = "io.ktor:ktor-server-auth-jwt", version.ref = "ktor" }
+ktor-server-content-negotiation = { module = "io.ktor:ktor-server-content-negotiation", version.ref = "ktor" }
+ktor-serialization-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+ktor-server-status-pages = { module = "io.ktor:ktor-server-status-pages", version.ref = "ktor" }
+ktor-server-forwarded-header = { module = "io.ktor:ktor-server-forwarded-header", version.ref = "ktor" }
+ktor-server-sessions = { module = "io.ktor:ktor-server-sessions", version.ref = "ktor" }
+ktor-server-tests = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor" }
 
 # Ktor Client (for tests)
-ktorClientContentNegotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
+ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
 
 # JWT
-javaJwt = { module = "com.auth0:java-jwt", version.ref = "javaJwt" }
+java-jwt = { module = "com.auth0:java-jwt", version.ref = "java-jwt" }
 
 # Logging
-slf4jSimple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }
-kotlinLogging = { module = "io.github.oshai:kotlin-logging-jvm", version.ref = "kotlinLogging" }
+slf4j-simple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }
+kotlin-logging = { module = "io.github.oshai:kotlin-logging-jvm", version.ref = "kotlin-logging" }
 
 [plugins]
-kotlinPluginSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+kotlin-plugin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

settings.gradle.kts

@@ -1,6 +1,7 @@
 dependencyResolutionManagement {
     @Suppress("UnstableApiUsage")
     repositories {
+        mavenLocal()
         mavenCentral()
     }
 }