better_auth-oauth-provider 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70854da8e71bdd4804aa18677e334cbe7b62a2b44f18223153ea3106e8cf389c
-  data.tar.gz: b1c6e8fe99ab5daa39b007ce5ac20ec18357d5d020e4aa979497215b9f4f2dba
+  metadata.gz: 0afe75d53fedd5aca49d956067e9c692c12422467b30c2344ed421bcbeb3ac50
+  data.tar.gz: dd9b3bfb6ee900376a1c98cf42ddc4db4044bd0a8838b8880dfe51e7d6799ee0
 SHA512:
-  metadata.gz: a7336740e04e0e0f0c7f775a27a2f1b2fbe682688a4b893dbfa1bb00c5a37641089b334275599d3b734c220ee232d6488bb602fc049098b512183ddd385281e8
-  data.tar.gz: 4b8b5b77f17240ae7351e1fe826b4400058854aec3e3f63e552a8c9bc5cb4ff9ea405f49d7132dc04c8f905ab2bdce0a7a1819e68c2176db2417d1ed615efe8f
+  metadata.gz: 3cd8ed966b7207a02dc8fad76f6e231084c43cee1e1fed5381d5bf1280b6b36e603220c848e74046ea6f6f2bb0a26ef94bb890bfed4a540649e6ac1642577be2
+  data.tar.gz: 8441b20dc28394bf3294d0527ff7818661cba1f485b83c218cdcf25a312cc0ac94d0b3825017305ad88b48d4131a4e867fb4f76d2d3bede870678f9361676b22

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-05-21
+
+- Changed OAuth provider defaults to hash stored client secrets and opaque OAuth tokens, with `store_tokens` support for custom token hashing.
+- Hardened token, introspection, and revocation client authentication to enforce the registered auth method and reject public-client introspection/revocation.
+- Aligned refresh-token issuance with upstream by requiring `offline_access`, and revoking descendant access tokens when a refresh token is revoked.
+- Added no-store token response headers, default JWKS discovery metadata, authorization-code session revalidation, prompt/request-uri validation, MCP verifier error normalization, and OAuth hot-path schema indexes.
+- Expanded adapter, authorization, registration, and rate-limit coverage for provider flows.
+
 ## 0.7.0 - 2026-05-05
 
 - Fixed OAuth provider consent approval, metadata, issuer normalization, revocation persistence, and endpoint-specific rate limits for hardening parity.

data/README.md

@@ -108,6 +108,7 @@ Common options accepted by `BetterAuth::Plugins.oauth_provider`:
 - `client_registration_allowed_scopes`
 - `client_credential_grant_default_scopes`
 - `store_client_secret`
+- `store_tokens`
 - `prefix`
 - `code_expires_in`
 - `id_token_expires_in`
@@ -131,6 +132,10 @@ Common options accepted by `BetterAuth::Plugins.oauth_provider`:
 - `disable_jwt_plugin`
 - `store`
 
+`store_client_secret` defaults to `"hashed"`. Set `store_client_secret: "plain"` only when migrating an existing app that still depends on plaintext client secrets. `store_tokens` defaults to `"hashed"` for opaque access tokens, refresh tokens, and authorization codes; custom hash callbacks may be supplied with `hash: ->(token, type) { ... }`.
+
+Token, introspection, and revocation client authentication is method-strict: `client_secret_basic` clients must authenticate with HTTP Basic credentials, `client_secret_post` clients must use body credentials, and public clients cannot authenticate to introspection or revocation. Authorization-code clients receive refresh tokens only when the granted scope includes `offline_access`.
+
 `rate_limit` accepts per-route overrides:
 
 ```ruby
@@ -150,6 +155,8 @@ Use `false` to disable a route-specific rule.
 
 `oauthAccessToken` now uses the upstream canonical columns `token`, `expiresAt`, `scopes`, `clientId`, `sessionId`, `userId`, `referenceId`, and `refreshId`. Legacy `access_token`, `refresh_token`, `access_token_expires_at`, and `scope` columns should be copied forward then dropped. `oauthConsent#consent_given` is also removed; a consent row means consent was granted.
 
+After enabling the hashed defaults, newly created OAuth client secrets and opaque tokens are stored hashed. Existing plaintext rows continue to require either a migration that re-registers/rotates secrets and tokens or a temporary explicit `store_client_secret: "plain"` setting for old clients during rollout.
+
 For non-Rails SQL apps, run the equivalent of:
 
 ```sql
@@ -166,7 +173,7 @@ Then drop the legacy access-token and consent columns. Rails apps using `better_
 
 ## Ruby Adaptations
 
-When the JWT plugin is registered, JWT access tokens and ID tokens use the JWT plugin's configured `jwks.key_pair_config.alg`, defaulting to `EdDSA` like upstream. If the JWT plugin is not registered, or `disable_jwt_plugin: true` is set, Ruby intentionally falls back to HS256 for compatibility.
+When the JWT plugin is registered, JWT access tokens and ID tokens use the JWT plugin's configured `jwks.key_pair_config.alg`, defaulting to `EdDSA` like upstream, and discovery metadata publishes the active JWKS URI. If the JWT plugin is not registered, or `disable_jwt_plugin: true` is set, Ruby intentionally falls back to HS256 for compatibility; with hashed client-secret storage, that fallback uses a server-derived per-client key.
 
 Upstream `oauthProviderResourceClient` and MCP protected-resource helpers remain future API-boundary work for Ruby. This gem currently hardens authorization-server behavior only.
 
@@ -175,3 +182,13 @@ Route OpenAPI metadata blocks from upstream TypeScript are intentionally not por
 The upstream `@better-auth/oauth-provider/client`, React/Solid client plugins, dashboard UI, and browser helpers are not ported. Ruby apps call the JSON endpoints directly or wrap `auth.api.*`.
 
 OIDC provider remains a core `better_auth` plugin because upstream still exposes it from `better-auth/plugins`. OAuth provider is the newer standalone provider package.
+
+## Development
+
+Run the package suite with:
+
+```sh
+rbenv exec bundle exec rake test
+```
+
+Adapter smoke tests skip when optional adapter gems or database services are not available. To install the optional adapter test bundle locally, enable Bundler's `adapter_test` group before running the suite.

data/lib/better_auth/oauth_provider/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module OAuthProvider
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/better_auth/plugins/oauth_provider/authorize.rb

@@ -40,6 +40,9 @@ module BetterAuth
       scopes = OAuthProtocol.parse_scopes(query["scope"])
       scopes = OAuthProtocol.parse_scopes(OAuthProtocol.stringify_keys(client)["scopes"] || config[:scopes]) if scopes.empty?
       prompts = OAuthProtocol.parse_scopes(query["prompt"])
+      if prompts.include?("none") && (prompts - ["none"]).any?
+        raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_request", "prompt none cannot be combined with other prompts"))
+      end
       client_data = OAuthProtocol.stringify_keys(client)
       if client_data["disabled"]
         raise ctx.redirect(oauth_authorize_error_redirect(ctx, query, "invalid_client", "client is disabled"))
@@ -65,7 +68,7 @@ module BetterAuth
         raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "login"))
       end
 
-      if prompts.include?("login") && !continue_post_login
+      if oauth_requires_login?(session, prompts, query) && !continue_post_login
         raise ctx.redirect(oauth_prompt_redirect(ctx, config, query, "login"))
       end
 
@@ -111,6 +114,21 @@ module BetterAuth
       oauth_redirect_with_code(ctx, config, query, session, client, scopes, reference_id: consent_reference_id)
     end
 
+    def oauth_requires_login?(session, prompts, query)
+      return true if prompts.include?("login")
+      return false unless query.key?("max_age")
+
+      max_age = Integer(query["max_age"])
+      return false if max_age.negative?
+
+      auth_time = OAuthProvider::Utils.resolve_session_auth_time(session)
+      return false unless auth_time
+
+      (Time.now - auth_time) > max_age
+    rescue ArgumentError, TypeError
+      false
+    end
+
     def oauth_prompt_redirect(ctx, config, query, type, page: nil)
       target = page || oauth_prompt_page(config, type)
 
@@ -204,7 +222,9 @@ module BetterAuth
       resolved = resolver.call({request_uri: query["request_uri"], client_id: query["client_id"], context: ctx})
       return oauth_invalid_request_uri!(ctx, query, "request_uri is invalid or expired") unless resolved
 
-      OAuthProtocol.stringify_keys(resolved)
+      resolved_query = OAuthProtocol.stringify_keys(resolved)
+      resolved_query["client_id"] = query["client_id"] if query["client_id"]
+      resolved_query
     end
 
     def oauth_invalid_request_uri!(ctx, query, description)

data/lib/better_auth/plugins/oauth_provider/consent.rb

@@ -5,7 +5,7 @@ module BetterAuth
     module_function
 
     def oauth_consent_endpoint(config)
-      Endpoint.new(path: "/oauth2/consent", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/consent", method: "POST", metadata: oauth_openapi_for(:consent)) do |ctx|
         current_session = Routes.current_session(ctx, allow_nil: true)
         body = OAuthProtocol.stringify_keys(ctx.body)
         consent = config[:store][:consents].delete(body["consent_code"].to_s)
@@ -49,7 +49,8 @@ module BetterAuth
         code_challenge_method: query["code_challenge_method"],
         nonce: query["nonce"],
         reference_id: reference_id || client_reference_id,
-        expires_in: config[:code_expires_in]
+        expires_in: config[:code_expires_in],
+        store_tokens: config[:store_tokens]
       )
       OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], code: code, state: query["state"], iss: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)))
     end

data/lib/better_auth/plugins/oauth_provider/continue.rb

@@ -5,7 +5,7 @@ module BetterAuth
     module_function
 
     def oauth_continue_endpoint(config)
-      Endpoint.new(path: "/oauth2/continue", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/continue", method: "POST", metadata: oauth_openapi_for(:continue)) do |ctx|
         Routes.current_session(ctx)
         body = OAuthProtocol.stringify_keys(ctx.body)
         action = if body["selected"] == true

data/lib/better_auth/plugins/oauth_provider/introspect.rb

@@ -5,8 +5,8 @@ module BetterAuth
     module_function
 
     def oauth_introspect_endpoint(config)
-      Endpoint.new(path: "/oauth2/introspect", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
-        client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix])
+      Endpoint.new(path: "/oauth2/introspect", method: "POST", metadata: oauth_openapi_for(:introspect).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])) do |ctx|
+        client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix], require_confidential: true)
         client_id = OAuthProtocol.stringify_keys(client)["clientId"]
         body = OAuthProtocol.stringify_keys(ctx.body)
         token_value = body["token"].to_s.sub(/\ABearer\s+/i, "")

data/lib/better_auth/plugins/oauth_provider/logout.rb

@@ -5,7 +5,7 @@ module BetterAuth
     module_function
 
     def oauth_end_session_endpoint
-      Endpoint.new(path: "/oauth2/end-session", method: ["GET", "POST"], metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(path: "/oauth2/end-session", method: ["GET", "POST"], metadata: oauth_openapi_for(:end_session).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])) do |ctx|
         input = OAuthProtocol.stringify_keys((ctx.method == "GET") ? ctx.query : ctx.body)
         id_token_hint = input["id_token_hint"].to_s
         raise APIError.new("UNAUTHORIZED", message: "invalid id token") if id_token_hint.empty?

data/lib/better_auth/plugins/oauth_provider/mcp.rb

@@ -58,6 +58,8 @@ module BetterAuth
             handler.call(request, jwt)
           rescue APIError => error
             handle_mcp_errors(error, resource, resource_metadata_mappings: resource_metadata_mappings)
+          rescue ::JWT::DecodeError
+            handle_mcp_errors(APIError.new("UNAUTHORIZED", message: "invalid token"), resource, resource_metadata_mappings: resource_metadata_mappings)
           end
         end
       end

data/lib/better_auth/plugins/oauth_provider/metadata.rb

@@ -24,7 +24,8 @@ module BetterAuth
           scopes_supported: config.dig(:advertised_metadata, :scopes_supported) || config[:scopes]
         }
         metadata[:registration_endpoint] = "#{base}/oauth2/register" if config[:allow_dynamic_client_registration]
-        metadata[:jwks_uri] = oauth_jwks_uri(config) if oauth_jwks_uri(config)
+        jwks_uri = oauth_jwks_uri(ctx, config)
+        metadata[:jwks_uri] = jwks_uri if jwks_uri
         ctx.json(metadata, headers: oauth_metadata_headers)
       end
     end
@@ -60,7 +61,8 @@ module BetterAuth
           claims_supported: config.dig(:advertised_metadata, :claims_supported) || config[:claims] || []
         }
         metadata[:registration_endpoint] = "#{base}/oauth2/register" if config[:allow_dynamic_client_registration]
-        metadata[:jwks_uri] = oauth_jwks_uri(config) if oauth_jwks_uri(config)
+        jwks_uri = oauth_jwks_uri(ctx, config)
+        metadata[:jwks_uri] = jwks_uri if jwks_uri
         ctx.json(metadata, headers: oauth_metadata_headers)
       end
     end
@@ -69,10 +71,21 @@ module BetterAuth
       {"Cache-Control" => "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400"}
     end
 
-    def oauth_jwks_uri(config)
+    def oauth_jwks_uri(ctx, config)
       config.dig(:advertised_metadata, :jwks_uri) ||
         config[:jwks_uri] ||
-        config.dig(:jwks, :remote_url)
+        config.dig(:jwks, :remote_url) ||
+        oauth_default_jwks_uri(ctx, config)
+    end
+
+    def oauth_default_jwks_uri(ctx, config)
+      return nil if config[:disable_jwt_plugin]
+
+      jwt_plugin = ctx.context.options.plugins.find { |plugin| plugin.id == "jwt" }
+      return nil unless jwt_plugin
+
+      path = jwt_plugin.options&.dig(:jwks, :jwks_path) || "/jwks"
+      "#{OAuthProtocol.endpoint_base(ctx)}#{path}"
     end
 
     def oauth_token_auth_methods(config)

data/lib/better_auth/plugins/oauth_provider/oauth_client/endpoints.rb

@@ -5,7 +5,7 @@ module BetterAuth
     module_function
 
     def oauth_create_client_endpoint(config)
-      Endpoint.new(path: "/oauth2/create-client", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/create-client", method: "POST", metadata: oauth_openapi_for(:create_client)) do |ctx|
         session = Routes.current_session(ctx)
         oauth_assert_client_privilege!(ctx, config, session, "create")
         body = OAuthProtocol.stringify_keys(ctx.body)
@@ -54,7 +54,12 @@ module BetterAuth
     end
 
     def oauth_get_client_public_prelogin_endpoint(config)
-      Endpoint.new(path: "/oauth2/public-client-prelogin", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/oauth2/public-client-prelogin",
+        method: "POST",
+        body_schema: ->(value) { value },
+        metadata: oauth_openapi_for(:public_client_prelogin)
+      ) do |ctx|
         input = OAuthProtocol.stringify_keys(ctx.body).merge(OAuthProtocol.stringify_keys(ctx.query))
         unless config[:allow_public_client_prelogin] || config[:allowPublicClientPrelogin]
           raise APIError.new("BAD_REQUEST")
@@ -86,7 +91,7 @@ module BetterAuth
     end
 
     def oauth_delete_client_endpoint(config)
-      Endpoint.new(path: "/oauth2/delete-client", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/delete-client", method: "POST", metadata: oauth_openapi_for(:delete_client)) do |ctx|
         session = Routes.current_session(ctx)
         oauth_assert_client_privilege!(ctx, config, session, "delete")
         body = OAuthProtocol.stringify_keys(ctx.body)
@@ -99,7 +104,7 @@ module BetterAuth
     end
 
     def oauth_update_client_endpoint(config)
-      Endpoint.new(path: "/oauth2/update-client", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/update-client", method: "POST", metadata: oauth_openapi_for(:update_client)) do |ctx|
         session = Routes.current_session(ctx)
         oauth_assert_client_privilege!(ctx, config, session, "update")
         body = OAuthProtocol.stringify_keys(ctx.body)
@@ -159,7 +164,7 @@ module BetterAuth
     end
 
     def oauth_rotate_client_secret_endpoint(config)
-      Endpoint.new(path: "/oauth2/client/rotate-secret", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/client/rotate-secret", method: "POST", metadata: oauth_openapi_for(:rotate_client_secret)) do |ctx|
         session = Routes.current_session(ctx)
         oauth_assert_client_privilege!(ctx, config, session, "rotate")
         body = OAuthProtocol.stringify_keys(ctx.body)
@@ -210,7 +215,7 @@ module BetterAuth
     end
 
     def oauth_legacy_update_client_endpoint(config)
-      Endpoint.new(path: "/oauth2/client", method: "PATCH") do |ctx|
+      Endpoint.new(path: "/oauth2/client", method: "PATCH", metadata: oauth_openapi_for(:update_client)) do |ctx|
         session = Routes.current_session(ctx)
         oauth_assert_client_privilege!(ctx, config, session, "update")
         body = OAuthProtocol.stringify_keys(ctx.body)

data/lib/better_auth/plugins/oauth_provider/oauth_consent/endpoints.rb

@@ -30,7 +30,7 @@ module BetterAuth
     end
 
     def oauth_update_consent_endpoint
-      Endpoint.new(path: "/oauth2/update-consent", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/update-consent", method: "POST", metadata: oauth_openapi_for(:update_consent)) do |ctx|
         session = Routes.current_session(ctx)
         body = OAuthProtocol.stringify_keys(ctx.body)
         id = body["id"]
@@ -61,7 +61,7 @@ module BetterAuth
     end
 
     def oauth_delete_consent_endpoint
-      Endpoint.new(path: "/oauth2/delete-consent", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/delete-consent", method: "POST", metadata: oauth_openapi_for(:delete_consent)) do |ctx|
         session = Routes.current_session(ctx)
         body = OAuthProtocol.stringify_keys(ctx.body)
         id = body["id"]
@@ -98,7 +98,7 @@ module BetterAuth
     end
 
     def oauth_legacy_update_consent_endpoint
-      Endpoint.new(path: "/oauth2/consent", method: "PATCH") do |ctx|
+      Endpoint.new(path: "/oauth2/consent", method: "PATCH", metadata: oauth_openapi_for(:update_consent)) do |ctx|
         session = Routes.current_session(ctx)
         body = OAuthProtocol.stringify_keys(ctx.body)
         consent = oauth_find_user_consent(ctx, session, body["client_id"])

data/lib/better_auth/plugins/oauth_provider/register.rb

@@ -5,7 +5,12 @@ module BetterAuth
     module_function
 
     def oauth_register_client_endpoint(config)
-      Endpoint.new(path: "/oauth2/register", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/oauth2/register",
+        method: "POST",
+        body_schema: ->(value) { value },
+        metadata: oauth_openapi_for(:register_client)
+      ) do |ctx|
         session = Routes.current_session(ctx, allow_nil: true)
         body = OAuthProtocol.stringify_keys(ctx.body)
         unless config[:allow_dynamic_client_registration]

data/lib/better_auth/plugins/oauth_provider/revoke.rb

@@ -5,8 +5,8 @@ module BetterAuth
     module_function
 
     def oauth_revoke_endpoint(config)
-      Endpoint.new(path: "/oauth2/revoke", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
-        client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix])
+      Endpoint.new(path: "/oauth2/revoke", method: "POST", metadata: oauth_openapi_for(:revoke).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])) do |ctx|
+        client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix], require_confidential: true)
         client_id = OAuthProtocol.stringify_keys(client)["clientId"]
         body = OAuthProtocol.stringify_keys(ctx.body)
         if body["token_type_hint"].to_s == "access_token" && OAuthProtocol.find_token_by_hint(config[:store], body["token"].to_s, "refresh_token", prefix: config[:prefix])
@@ -39,7 +39,20 @@ module BetterAuth
 
       if is_refresh && OAuthProtocol.schema_model?(ctx, "oauthRefreshToken")
         ctx.context.adapter.update(model: "oauthRefreshToken", where: [{field: "id", value: token["id"]}], update: {revoked: token["revoked"]})
+        oauth_revoke_refresh_access_tokens(ctx, config[:store], token)
       end
     end
+
+    def oauth_revoke_refresh_access_tokens(ctx, store, refresh_token)
+      refresh_id = refresh_token["id"]
+      return if refresh_id.to_s.empty?
+
+      store[:tokens].each_value do |record|
+        record["revoked"] = refresh_token["revoked"] if record["refreshId"].to_s == refresh_id.to_s
+      end
+      return unless OAuthProtocol.schema_model?(ctx, "oauthAccessToken")
+
+      ctx.context.adapter.update_many(model: "oauthAccessToken", where: [{field: "refreshId", value: refresh_id}], update: {revoked: refresh_token["revoked"]})
+    end
   end
 end

data/lib/better_auth/plugins/oauth_provider/schema.rb

@@ -7,7 +7,7 @@ module BetterAuth
     def oauth_provider_schema
       {
         oauthClient: {
-          modelName: "oauthClient",
+          model_name: "oauth_clients",
           fields: {
             clientId: {type: "string", unique: true, required: true},
             clientSecret: {type: "string", required: false},
@@ -16,7 +16,7 @@ module BetterAuth
             enableEndSession: {type: "boolean", required: false},
             clientSecretExpiresAt: {type: "number", required: false},
             scopes: {type: "string[]", required: false},
-            userId: {type: "string", required: false},
+            userId: {type: "string", required: false, index: true, references: {model: "user", field: "id"}},
             createdAt: {type: "date", required: true, default_value: -> { Time.now }},
             updatedAt: {type: "date", required: true, default_value: -> { Time.now }, on_update: -> { Time.now }},
             name: {type: "string", required: false},
@@ -37,17 +37,17 @@ module BetterAuth
             type: {type: "string", required: false},
             requirePKCE: {type: "boolean", required: false},
             subjectType: {type: "string", required: false},
-            referenceId: {type: "string", required: false},
+            referenceId: {type: "string", required: false, index: true},
             metadata: {type: "json", required: false}
           }
         },
         oauthRefreshToken: {
           fields: {
             token: {type: "string", required: true},
-            clientId: {type: "string", required: true},
-            sessionId: {type: "string", required: false},
-            userId: {type: "string", required: false},
-            referenceId: {type: "string", required: false},
+            clientId: {type: "string", required: true, index: true, references: {model: "oauthClient", field: "clientId"}},
+            sessionId: {type: "string", required: false, references: {model: "session", field: "id", on_delete: "set null"}},
+            userId: {type: "string", required: false, index: true, references: {model: "user", field: "id"}},
+            referenceId: {type: "string", required: false, index: true},
             authTime: {type: "date", required: false},
             expiresAt: {type: "date", required: false},
             createdAt: {type: "date", required: true, default_value: -> { Time.now }},
@@ -56,28 +56,28 @@ module BetterAuth
           }
         },
         oauthAccessToken: {
-          modelName: "oauthAccessToken",
+          model_name: "oauth_access_tokens",
           fields: {
             token: {type: "string", unique: true, required: true},
             expiresAt: {type: "date", required: true},
-            clientId: {type: "string", required: true},
-            userId: {type: "string", required: false},
-            sessionId: {type: "string", required: false},
+            clientId: {type: "string", required: true, index: true, references: {model: "oauthClient", field: "clientId"}},
+            userId: {type: "string", required: false, index: true, references: {model: "user", field: "id"}},
+            sessionId: {type: "string", required: false, references: {model: "session", field: "id", on_delete: "set null"}},
             scopes: {type: "string[]", required: true},
             revoked: {type: "date", required: false},
             referenceId: {type: "string", required: false},
             authTime: {type: "date", required: false},
-            refreshId: {type: "string", required: false},
+            refreshId: {type: "string", required: false, index: true, references: {model: "oauthRefreshToken", field: "id"}},
             createdAt: {type: "date", required: true, default_value: -> { Time.now }},
             updatedAt: {type: "date", required: true, default_value: -> { Time.now }, on_update: -> { Time.now }}
           }
         },
         oauthConsent: {
-          modelName: "oauthConsent",
+          model_name: "oauth_consents",
           fields: {
-            clientId: {type: "string", required: true},
-            userId: {type: "string", required: false},
-            referenceId: {type: "string", required: false},
+            clientId: {type: "string", required: true, index: true, references: {model: "oauthClient", field: "clientId"}},
+            userId: {type: "string", required: false, index: true, references: {model: "user", field: "id"}},
+            referenceId: {type: "string", required: false, index: true},
             scopes: {type: "string[]", required: true},
             createdAt: {type: "date", required: true, default_value: -> { Time.now }},
             updatedAt: {type: "date", required: true, default_value: -> { Time.now }, on_update: -> { Time.now }}

data/lib/better_auth/plugins/oauth_provider/token.rb

@@ -5,9 +5,15 @@ module BetterAuth
     module_function
 
     def oauth_token_endpoint(config)
-      Endpoint.new(path: "/oauth2/token", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
-        body = OAuthProtocol.stringify_keys(ctx.body)
+      Endpoint.new(
+        path: "/oauth2/token",
+        method: "POST",
+        body_schema: ->(value) { value },
+        metadata: oauth_openapi_for(:token).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
+        body = OAuthProtocol.request_body!(ctx.body)
         client = OAuthProtocol.authenticate_client!(ctx, "oauthClient", store_client_secret: config[:store_client_secret], prefix: config[:prefix])
+        client_id = OAuthProtocol.stringify_keys(client)["clientId"]
         client_grants = OAuthProtocol.parse_scopes(OAuthProtocol.stringify_keys(client)["grantTypes"])
         if client_grants.any? && !client_grants.include?(body["grant_type"].to_s)
           raise APIError.new("BAD_REQUEST", message: "unsupported_grant_type")
@@ -17,19 +23,21 @@ module BetterAuth
           code = OAuthProtocol.consume_code!(
             config[:store],
             body["code"],
-            client_id: body["client_id"],
+            client_id: client_id,
             redirect_uri: body["redirect_uri"],
-            code_verifier: body["code_verifier"]
+            code_verifier: body["code_verifier"],
+            store_tokens: config[:store_tokens]
           )
+          session = oauth_active_authorization_session!(ctx, code[:session])
           audience = oauth_validate_resource!(ctx, config, body, code[:scopes])
           OAuthProtocol.issue_tokens(
             ctx,
             config[:store],
             model: "oauthAccessToken",
             client: client,
-            session: code[:session],
+            session: session,
             scopes: code[:scopes],
-            include_refresh: code[:scopes].include?("offline_access") || OAuthProtocol.parse_scopes(OAuthProtocol.stringify_keys(client)["grantTypes"]).include?(OAuthProtocol::REFRESH_GRANT),
+            include_refresh: code[:scopes].include?("offline_access"),
             issuer: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)),
             prefix: config[:prefix],
             refresh_token_expires_in: config[:refresh_token_expires_in],
@@ -46,7 +54,8 @@ module BetterAuth
             nonce: code[:nonce],
             auth_time: code[:auth_time],
             reference_id: code[:reference_id],
-            filter_id_token_claims_by_scope: true
+            filter_id_token_claims_by_scope: true,
+            store_tokens: config[:store_tokens]
           )
         when OAuthProtocol::CLIENT_CREDENTIALS_GRANT
           requested = OAuthProtocol.parse_scopes(body["scope"])
@@ -66,19 +75,38 @@ module BetterAuth
           end
 
           audience = oauth_validate_resource!(ctx, config, body, requested)
-          OAuthProtocol.issue_tokens(ctx, config[:store], model: "oauthAccessToken", client: client, session: {"user" => {}, "session" => {}}, scopes: requested, include_refresh: false, issuer: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)), prefix: config[:prefix], audience: audience, grant_type: OAuthProtocol::CLIENT_CREDENTIALS_GRANT, custom_token_response_fields: config[:custom_token_response_fields], custom_access_token_claims: config[:custom_access_token_claims], custom_id_token_claims: config[:custom_id_token_claims], jwt_access_token: oauth_jwt_access_token?(config, audience), use_jwt_plugin: !config[:disable_jwt_plugin], pairwise_secret: config[:pairwise_secret], access_token_expires_in: oauth_access_token_expires_in(config, requested, machine: true), id_token_expires_in: config[:id_token_expires_in], filter_id_token_claims_by_scope: true)
+          OAuthProtocol.issue_tokens(ctx, config[:store], model: "oauthAccessToken", client: client, session: {"user" => {}, "session" => {}}, scopes: requested, include_refresh: false, issuer: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)), prefix: config[:prefix], audience: audience, grant_type: OAuthProtocol::CLIENT_CREDENTIALS_GRANT, custom_token_response_fields: config[:custom_token_response_fields], custom_access_token_claims: config[:custom_access_token_claims], custom_id_token_claims: config[:custom_id_token_claims], jwt_access_token: oauth_jwt_access_token?(config, audience), use_jwt_plugin: !config[:disable_jwt_plugin], pairwise_secret: config[:pairwise_secret], access_token_expires_in: oauth_access_token_expires_in(config, requested, machine: true), id_token_expires_in: config[:id_token_expires_in], filter_id_token_claims_by_scope: true, store_tokens: config[:store_tokens])
         when OAuthProtocol::REFRESH_GRANT
           refresh_record = OAuthProtocol.find_token_by_hint(config[:store], body["refresh_token"].to_s, "refresh_token", prefix: config[:prefix])
           refresh_scopes = OAuthProtocol.parse_scopes(body["scope"] || refresh_record&.fetch("scopes", nil))
           audience = oauth_validate_resource!(ctx, config, body, refresh_scopes)
-          OAuthProtocol.refresh_tokens(ctx, config[:store], model: "oauthAccessToken", client: client, refresh_token: body["refresh_token"], scopes: body["scope"], issuer: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)), prefix: config[:prefix], refresh_token_expires_in: config[:refresh_token_expires_in], audience: audience, custom_token_response_fields: config[:custom_token_response_fields], custom_access_token_claims: config[:custom_access_token_claims], custom_id_token_claims: config[:custom_id_token_claims], jwt_access_token: oauth_jwt_access_token?(config, audience), use_jwt_plugin: !config[:disable_jwt_plugin], pairwise_secret: config[:pairwise_secret], access_token_expires_in: oauth_access_token_expires_in(config, refresh_scopes, machine: false), id_token_expires_in: config[:id_token_expires_in], filter_id_token_claims_by_scope: true)
+          OAuthProtocol.refresh_tokens(ctx, config[:store], model: "oauthAccessToken", client: client, refresh_token: body["refresh_token"], scopes: body["scope"], issuer: OAuthProvider.validate_issuer_url(OAuthProtocol.issuer(ctx)), prefix: config[:prefix], refresh_token_expires_in: config[:refresh_token_expires_in], audience: audience, custom_token_response_fields: config[:custom_token_response_fields], custom_access_token_claims: config[:custom_access_token_claims], custom_id_token_claims: config[:custom_id_token_claims], jwt_access_token: oauth_jwt_access_token?(config, audience), use_jwt_plugin: !config[:disable_jwt_plugin], pairwise_secret: config[:pairwise_secret], access_token_expires_in: oauth_access_token_expires_in(config, refresh_scopes, machine: false), id_token_expires_in: config[:id_token_expires_in], filter_id_token_claims_by_scope: true, store_tokens: config[:store_tokens])
         else
           raise APIError.new("BAD_REQUEST", message: "unsupported_grant_type")
         end
-        ctx.json(response)
+        ctx.json(response, headers: oauth_no_store_headers)
       end
     end
 
+    def oauth_no_store_headers
+      {"Cache-Control" => "no-store", "Pragma" => "no-cache"}
+    end
+
+    def oauth_active_authorization_session!(ctx, stored_session)
+      data = OAuthProtocol.stringify_keys(stored_session || {})
+      session_snapshot = OAuthProtocol.stringify_keys(data["session"] || data[:session] || {})
+      user_snapshot = OAuthProtocol.stringify_keys(data["user"] || data[:user] || {})
+      session_id = session_snapshot["id"]
+      stored = session_id && ctx.context.adapter.find_one(model: "session", where: [{field: "id", value: session_id}])
+      raise APIError.new("BAD_REQUEST", message: "session no longer exists") unless stored
+      raise APIError.new("BAD_REQUEST", message: "session no longer exists") if stored["expiresAt"] && stored["expiresAt"] <= Time.now
+
+      user = ctx.context.internal_adapter.find_user_by_id(stored["userId"] || user_snapshot["id"])
+      raise APIError.new("BAD_REQUEST", message: "missing user, user may have been deleted") unless user
+
+      {"user" => user, "session" => stored}
+    end
+
     def oauth_validate_resource!(ctx, config, body, scopes)
       resources = Array(body["resource"]).compact.map(&:to_s)
       return nil if resources.empty?

data/lib/better_auth/plugins/oauth_provider.rb

@@ -36,6 +36,7 @@ module BetterAuth
     singleton_class.remove_method(:oauth_provider) if singleton_class.method_defined?(:oauth_provider) || singleton_class.private_method_defined?(:oauth_provider)
 
     def oauth_provider(options = {})
+      raw_options = normalize_hash(options)
       config = {
         login_page: "/login",
         consent_page: "/oauth2/consent",
@@ -48,7 +49,8 @@ module BetterAuth
         signup: {},
         select_account: {},
         post_login: {},
-        store_client_secret: "plain",
+        store_client_secret: "hashed",
+        store_tokens: "hashed",
         prefix: {},
         code_expires_in: 600,
         id_token_expires_in: 36_000,
@@ -58,12 +60,15 @@ module BetterAuth
         client_credential_grant_default_scopes: nil,
         scope_expirations: {},
         store: OAuthProtocol.stores
-      }.merge(normalize_hash(options))
+      }.merge(raw_options)
+
+      oauth_provider_validate_config!(config, raw_options)
 
       Plugin.new(
         id: "oauth-provider",
         version: BetterAuth::OAuthProvider::VERSION,
         init: oauth_provider_init(config),
+        hooks: oauth_provider_hooks(config),
         endpoints: oauth_provider_endpoints(config),
         schema: oauth_provider_schema,
         rate_limit: oauth_provider_rate_limits(config),
@@ -71,6 +76,101 @@ module BetterAuth
       )
     end
 
+    def oauth_provider_validate_config!(config, raw_options = {})
+      provider_scopes = OAuthProtocol.parse_scopes(config[:scopes])
+      [
+        [:client_registration_allowed_scopes, config[:client_registration_allowed_scopes]],
+        [:client_registration_default_scopes, config[:client_registration_default_scopes]]
+      ].each do |key, value|
+        next if value.nil?
+
+        missing = OAuthProtocol.parse_scopes(value) - provider_scopes
+        unless missing.empty?
+          raise APIError.new("BAD_REQUEST", message: "#{key} #{missing.first} not found in scopes")
+        end
+      end
+
+      grant_types = Array(config[:grant_types]).map(&:to_s)
+      if grant_types.include?(OAuthProtocol::REFRESH_GRANT) && !grant_types.include?(OAuthProtocol::AUTH_CODE_GRANT)
+        raise APIError.new("BAD_REQUEST", message: "refresh_token grant requires authorization_code grant")
+      end
+
+      store_client_secret = config[:store_client_secret]
+      if config[:disable_jwt_plugin] && raw_options.key?(:store_client_secret) && oauth_hashed_secret_storage?(store_client_secret)
+        raise APIError.new("BAD_REQUEST", message: "unable to store hashed secrets because id tokens will be signed with client secret")
+      end
+      if !config[:disable_jwt_plugin] && oauth_encrypted_secret_storage?(store_client_secret)
+        raise APIError.new("BAD_REQUEST", message: "encrypted secret storage is not recommended, please use hashed secret storage with the JWT plugin")
+      end
+    end
+
+    def oauth_hashed_secret_storage?(value)
+      mode = value.is_a?(Hash) ? normalize_hash(value) : value.to_s
+      mode == "hashed" || (mode.is_a?(Hash) && mode[:hash].respond_to?(:call))
+    end
+
+    def oauth_encrypted_secret_storage?(value)
+      mode = value.is_a?(Hash) ? normalize_hash(value) : value.to_s
+      mode == "encrypted" || (mode.is_a?(Hash) && (mode[:encrypt].respond_to?(:call) || mode[:decrypt].respond_to?(:call)))
+    end
+
+    def oauth_provider_hooks(config)
+      {
+        before: [
+          {
+            matcher: ->(ctx) { ctx.path.start_with?("/sign-in/", "/sign-up/") && !!oauth_query_from_body(ctx.body) },
+            handler: ->(ctx) { oauth_validate_query_hook!(ctx) }
+          }
+        ],
+        after: [
+          {
+            matcher: ->(ctx) { oauth_resume_after_session_cookie?(ctx) },
+            handler: ->(ctx) { oauth_resume_after_session_cookie(ctx, config) }
+          }
+        ]
+      }
+    end
+
+    def oauth_validate_query_hook!(ctx)
+      oauth_query = oauth_query_from_body(ctx.body)
+      return unless oauth_query
+
+      unless OAuthProvider::Utils.verify_oauth_query_params(oauth_query, ctx.context.secret)
+        raise APIError.new("BAD_REQUEST", message: "invalid_signature", body: {error: "invalid_signature"})
+      end
+
+      nil
+    end
+
+    def oauth_resume_after_session_cookie?(ctx)
+      return false unless oauth_query_from_body(ctx.body)
+      return false unless ctx.path.start_with?("/sign-in/", "/sign-up/")
+
+      ctx.response_headers["set-cookie"].to_s.include?(ctx.context.auth_cookies[:session_token].name)
+    end
+
+    def oauth_resume_after_session_cookie(ctx, config)
+      query = oauth_verified_query!(ctx, oauth_query_from_body(ctx.body))
+      ctx.context.set_current_session(ctx.context.new_session) if ctx.context.respond_to?(:set_current_session) && ctx.context.new_session
+      location = oauth_redirect_location { oauth_authorize_flow(ctx, config, query, continue_post_login: true) }
+      [302, Endpoint::Result.merge_headers(ctx.response_headers, {"location" => location}), [""]]
+    rescue APIError => error
+      raise APIError.new(
+        error.status,
+        message: error.message,
+        headers: Endpoint::Result.merge_headers(ctx.response_headers, error.headers),
+        code: error.code,
+        body: error.body
+      )
+    end
+
+    def oauth_query_from_body(body)
+      return nil unless body.is_a?(Hash)
+
+      data = OAuthProtocol.stringify_keys(body || {})
+      data["oauth_query"] || data["oauthQuery"]
+    end
+
     def oauth_provider_init(config)
       lambda do |context|
         advertised_scopes = Array(config.dig(:advertised_metadata, :scopes_supported)).map(&:to_s)
@@ -129,5 +229,419 @@ module BetterAuth
         o_auth2_end_session: oauth_end_session_endpoint
       }
     end
+
+    def oauth_openapi_for(route)
+      {
+        register_client: oauth_client_registration_openapi("Register a new OAuth2 client", include_secret: true),
+        create_client: oauth_client_registration_openapi("Create a new OAuth2 client", include_secret: true),
+        public_client_prelogin: oauth_public_client_prelogin_openapi,
+        delete_client: oauth_delete_client_openapi,
+        update_client: oauth_update_client_openapi,
+        rotate_client_secret: oauth_rotate_client_secret_openapi,
+        update_consent: oauth_update_consent_openapi,
+        delete_consent: oauth_delete_consent_openapi,
+        continue: oauth_continue_openapi,
+        consent: oauth_consent_openapi,
+        token: oauth_token_openapi,
+        introspect: oauth_introspect_openapi,
+        revoke: oauth_revoke_openapi,
+        end_session: oauth_end_session_openapi
+      }.fetch(route)
+    end
+
+    def oauth_client_registration_openapi(description, include_secret:)
+      {
+        openapi: {
+          description: description,
+          requestBody: OpenAPI.json_request_body(oauth_client_registration_schema),
+          responses: {
+            "201" => OpenAPI.json_response("OAuth2 client created successfully", oauth_client_response_schema(include_secret: include_secret))
+          }
+        }
+      }
+    end
+
+    def oauth_public_client_prelogin_openapi
+      {
+        openapi: {
+          description: "Get public OAuth2 client metadata before login",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                client_id: {type: "string", description: "OAuth2 client ID"},
+                oauth_query: {type: "string", description: "Signed OAuth query string"}
+              },
+              required: ["client_id", "oauth_query"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("Public OAuth2 client metadata", oauth_public_client_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_delete_client_openapi
+      {
+        openapi: {
+          description: "Delete an OAuth2 client",
+          requestBody: OpenAPI.json_request_body(oauth_client_id_body_schema),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 client deleted", OpenAPI.object_schema({deleted: {type: "boolean"}}, required: ["deleted"]))
+          }
+        }
+      }
+    end
+
+    def oauth_update_client_openapi
+      {
+        openapi: {
+          description: "Update an OAuth2 client",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                client_id: {type: "string", description: "OAuth2 client ID"},
+                update: oauth_client_registration_schema.merge(description: "Client metadata to update")
+              },
+              required: ["client_id", "update"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 client updated", oauth_client_response_schema(include_secret: false))
+          }
+        }
+      }
+    end
+
+    def oauth_rotate_client_secret_openapi
+      {
+        openapi: {
+          description: "Rotate an OAuth2 client secret",
+          requestBody: OpenAPI.json_request_body(oauth_client_id_body_schema),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 client secret rotated", oauth_client_response_schema(include_secret: true))
+          }
+        }
+      }
+    end
+
+    def oauth_update_consent_openapi
+      {
+        openapi: {
+          description: "Update OAuth2 consent scopes",
+          requestBody: OpenAPI.json_request_body(oauth_consent_mutation_schema(required_update: false)),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 consent updated", oauth_consent_response_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_delete_consent_openapi
+      {
+        openapi: {
+          description: "Delete OAuth2 consent",
+          requestBody: OpenAPI.json_request_body(oauth_consent_identifier_schema),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 consent deleted", OpenAPI.object_schema({deleted: {type: "boolean"}}, required: ["deleted"]))
+          }
+        }
+      }
+    end
+
+    def oauth_continue_openapi
+      {
+        openapi: {
+          description: "Continue an OAuth2 authorization interaction",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                oauth_query: {type: "string", description: "Signed OAuth query string"},
+                selected: {type: "boolean", description: "Continue after account selection"},
+                created: {type: "boolean", description: "Continue after account creation"},
+                postLogin: {type: "boolean", description: "Continue after post-login flow"},
+                post_login: {type: "boolean", description: "Continue after post-login flow"}
+              },
+              required: ["oauth_query"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 authorization redirect", oauth_redirect_response_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_consent_openapi
+      {
+        openapi: {
+          description: "Submit an OAuth2 consent decision",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                consent_code: {type: "string", description: "Consent code issued by the authorization flow"},
+                accept: {type: "boolean", description: "Whether the user accepted the consent request"},
+                scope: {type: "string", description: "Granted scopes as a space-delimited string"},
+                scopes: {type: "array", items: {type: "string"}, description: "Granted scopes"}
+              },
+              required: ["consent_code"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 consent redirect", OpenAPI.object_schema({redirectURI: {type: "string"}}, required: ["redirectURI"]))
+          }
+        }
+      }
+    end
+
+    def oauth_token_openapi
+      {
+        openapi: {
+          description: "Exchange an OAuth2 grant for tokens",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                grant_type: {type: "string", enum: [OAuthProtocol::AUTH_CODE_GRANT, OAuthProtocol::CLIENT_CREDENTIALS_GRANT, OAuthProtocol::REFRESH_GRANT]},
+                code: {type: "string", description: "Authorization code"},
+                redirect_uri: {type: "string", format: "uri"},
+                code_verifier: {type: "string"},
+                client_id: {type: "string"},
+                client_secret: {type: "string"},
+                refresh_token: {type: "string"},
+                scope: {type: "string"},
+                resource: {oneOf: [{type: "string"}, {type: "array", items: {type: "string"}}]}
+              },
+              required: ["grant_type"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 tokens issued", oauth_token_response_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_introspect_openapi
+      {
+        openapi: {
+          description: "Introspect an OAuth2 token",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                token: {type: "string", description: "Token to introspect"},
+                token_type_hint: {type: "string", enum: ["access_token", "refresh_token"]}
+              },
+              required: ["token"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 token introspection result", oauth_introspection_response_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_revoke_openapi
+      {
+        openapi: {
+          description: "Revoke an OAuth2 token",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                token: {type: "string", description: "Token to revoke"},
+                token_type_hint: {type: "string", enum: ["access_token", "refresh_token"]}
+              },
+              required: ["token"]
+            )
+          ),
+          responses: {
+            "200" => OpenAPI.json_response("OAuth2 token revoked", OpenAPI.object_schema({revoked: {type: "boolean"}}, required: ["revoked"]))
+          }
+        }
+      }
+    end
+
+    def oauth_end_session_openapi
+      {
+        openapi: {
+          description: "End an OpenID Connect session",
+          parameters: oauth_end_session_parameters,
+          requestBody: OpenAPI.json_request_body(oauth_end_session_body_schema, required: false),
+          responses: {
+            "200" => OpenAPI.json_response("OpenID Connect session ended", OpenAPI.status_response_schema)
+          }
+        }
+      }
+    end
+
+    def oauth_client_registration_schema
+      OpenAPI.object_schema(
+        {
+          redirect_uris: {type: "array", items: {type: "string", format: "uri"}, description: "Allowed redirect URIs"},
+          post_logout_redirect_uris: {type: "array", items: {type: "string", format: "uri"}, description: "Allowed post logout redirect URIs"},
+          client_name: {type: "string", description: "OAuth2 client name"},
+          client_uri: {type: "string", format: "uri"},
+          logo_uri: {type: "string", format: "uri"},
+          contacts: {type: "array", items: {type: "string"}},
+          tos_uri: {type: "string", format: "uri"},
+          policy_uri: {type: "string", format: "uri"},
+          software_id: {type: "string"},
+          software_version: {type: "string"},
+          software_statement: {type: "string"},
+          token_endpoint_auth_method: {type: "string", enum: ["client_secret_basic", "client_secret_post", "none"]},
+          grant_types: {type: "array", items: {type: "string", enum: [OAuthProtocol::AUTH_CODE_GRANT, OAuthProtocol::CLIENT_CREDENTIALS_GRANT, OAuthProtocol::REFRESH_GRANT]}},
+          response_types: {type: "array", items: {type: "string", enum: ["code"]}},
+          scope: {type: "string"},
+          scopes: {type: "array", items: {type: "string"}},
+          type: {type: "string", enum: ["web", "native", "user-agent-based"]},
+          require_pkce: {type: "boolean"},
+          requirePKCE: {type: "boolean"},
+          subject_type: {type: "string", enum: ["public", "pairwise"]},
+          subjectType: {type: "string", enum: ["public", "pairwise"]},
+          enable_end_session: {type: "boolean"},
+          enableEndSession: {type: "boolean"},
+          skip_consent: {type: "boolean"},
+          skipConsent: {type: "boolean"},
+          metadata: {type: "object", additionalProperties: true}
+        },
+        required: ["redirect_uris"]
+      )
+    end
+
+    def oauth_client_id_body_schema
+      OpenAPI.object_schema(
+        {
+          client_id: {type: "string", description: "OAuth2 client ID"}
+        },
+        required: ["client_id"]
+      )
+    end
+
+    def oauth_client_response_schema(include_secret:)
+      properties = oauth_public_client_schema[:properties].merge(
+        redirect_uris: {type: "array", items: {type: "string", format: "uri"}},
+        post_logout_redirect_uris: {type: "array", items: {type: "string", format: "uri"}},
+        token_endpoint_auth_method: {type: "string"},
+        grant_types: {type: "array", items: {type: "string"}},
+        response_types: {type: "array", items: {type: "string"}},
+        scope: {type: "string"},
+        public: {type: "boolean"},
+        type: {type: ["string", "null"]},
+        user_id: {type: ["string", "null"]},
+        reference_id: {type: ["string", "null"]},
+        require_pkce: {type: ["boolean", "null"]},
+        subject_type: {type: ["string", "null"]},
+        metadata: {type: "object", additionalProperties: true},
+        client_id_issued_at: {type: "number"},
+        client_secret_expires_at: {type: "number"}
+      )
+      properties[:client_secret] = {type: "string", description: "OAuth2 client secret"} if include_secret
+      OpenAPI.object_schema(properties)
+    end
+
+    def oauth_public_client_schema
+      OpenAPI.object_schema(
+        {
+          client_id: {type: "string"},
+          client_name: {type: "string"},
+          client_uri: {type: ["string", "null"], format: "uri"},
+          logo_uri: {type: ["string", "null"], format: "uri"},
+          contacts: {type: "array", items: {type: "string"}},
+          tos_uri: {type: ["string", "null"], format: "uri"},
+          policy_uri: {type: ["string", "null"], format: "uri"}
+        }
+      )
+    end
+
+    def oauth_consent_identifier_schema
+      OpenAPI.object_schema(
+        {
+          id: {type: "string", description: "OAuth2 consent ID"},
+          client_id: {type: "string", description: "OAuth2 client ID"}
+        }
+      )
+    end
+
+    def oauth_consent_mutation_schema(required_update:)
+      OpenAPI.object_schema(
+        oauth_consent_identifier_schema[:properties].merge(
+          update: OpenAPI.object_schema({scopes: {type: "array", items: {type: "string"}}}),
+          scope: {type: "string"},
+          scopes: {type: "array", items: {type: "string"}}
+        ),
+        required: required_update ? ["update"] : []
+      )
+    end
+
+    def oauth_consent_response_schema
+      OpenAPI.object_schema(
+        {
+          id: {type: "string"},
+          clientId: {type: "string"},
+          userId: {type: "string"},
+          scopes: {type: "array", items: {type: "string"}},
+          createdAt: {type: "string", format: "date-time"},
+          updatedAt: {type: "string", format: "date-time"}
+        }
+      )
+    end
+
+    def oauth_redirect_response_schema
+      OpenAPI.object_schema(
+        {
+          redirect: {type: "boolean", enum: [true]},
+          url: {type: "string", format: "uri"}
+        },
+        required: ["redirect", "url"]
+      )
+    end
+
+    def oauth_token_response_schema
+      OpenAPI.object_schema(
+        {
+          access_token: {type: "string"},
+          token_type: {type: "string"},
+          expires_in: {type: "number"},
+          refresh_token: {type: "string"},
+          scope: {type: "string"},
+          id_token: {type: "string"}
+        },
+        required: ["access_token", "token_type"]
+      )
+    end
+
+    def oauth_introspection_response_schema
+      OpenAPI.object_schema(
+        {
+          active: {type: "boolean"},
+          client_id: {type: "string"},
+          scope: {type: "string"},
+          sub: {type: "string"},
+          iss: {type: "string"},
+          iat: {type: "number"},
+          exp: {type: "number"},
+          sid: {type: "string"},
+          aud: {oneOf: [{type: "string"}, {type: "array", items: {type: "string"}}]}
+        },
+        required: ["active"]
+      )
+    end
+
+    def oauth_end_session_parameters
+      oauth_end_session_body_schema[:properties].keys.map do |name|
+        OpenAPI.query_parameter(name.to_s, required: false, schema: oauth_end_session_body_schema[:properties][name])
+      end
+    end
+
+    def oauth_end_session_body_schema
+      OpenAPI.object_schema(
+        {
+          id_token_hint: {type: "string"},
+          client_id: {type: "string"},
+          post_logout_redirect_uri: {type: "string", format: "uri"},
+          state: {type: "string"}
+        }
+      )
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-oauth-provider
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -119,14 +119,14 @@ files:
 - lib/better_auth/plugins/oauth_provider/types/zod.rb
 - lib/better_auth/plugins/oauth_provider/userinfo.rb
 - lib/better_auth/plugins/oauth_provider/utils/index.rb
-homepage: https://github.com/sebasxsala/better-auth
+homepage: https://github.com/sebasxsala/better-auth-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sebasxsala/better-auth
-  source_code_uri: https://github.com/sebasxsala/better-auth
-  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-oauth-provider/CHANGELOG.md
-  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-oauth-provider/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
 rdoc_options: []
 require_paths:
 - lib