better_auth 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d0edd237bbc32992ae24fec0305f09d55521add17768dceac160198e9a7d190
-  data.tar.gz: fb04ec9c038649e8fbf2dc34aecb92b5959342eedc598daefce06e3ae7f6131a
+  metadata.gz: b62f1d0f1e0fc4c774ab2d4907f9229f4cbcae46599cf8b72c03a4d5984aafcf
+  data.tar.gz: a02c36229e3d829a1d3c24d64e9e560fc9f592e9ad4ad915bcd6a962fd0f633a
 SHA512:
-  metadata.gz: 593471f2dee235f6f75d479c61f24a49a23e6d8fec8db00fe8fa5d20afadf179bb1cb6d62b07a668b6c1246b60c934626c5906e3ea965912806afd00bbda1ee4
-  data.tar.gz: 1742e7eb46663909392cf010e3ada3aa675f68cdcc5160c0019e561407c467c4831f7c19a22bf9a660ee0527db7131f768fad99528dbefb40d8be51ae6b5fc39
+  metadata.gz: 50d18b3901b1e7292b3b4089e1eb388dadb16836d88a6d8af35ecb8061005dc062712010865b0f131b768538fbc2e64042edfb5b652feaad979f93d03f6ca7fa
+  data.tar.gz: ce679e88e9e12dd1d36aab49a20bb6d2a8e55e95de6eeccbdc3b4bd3736924d9496fb5148e874132f6f07efb914035ed6ce0cd200216355390bfe86b016c6ff8

data/CHANGELOG.md

@@ -7,7 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-05
+
+### Added
+
+- Completed OpenAPI support with upstream v1.6.9 base-route schema parity, `/ok` and `/error` documentation, richer helper-generated schemas, plugin endpoint metadata coverage, and Scalar reference configuration parity.
+- Added shared join query handling for adapter-backed relation loading.
+
+### Changed
+
 - Modernized the MCP plugin to use OAuth Provider-style client, token, metadata, and protected-resource behavior while keeping legacy MCP routes as aliases.
+- Changed OAuth HS256 ID token signing to use non-public key material; existing ID tokens signed only with the public client id will no longer validate.
+
+### Fixed
+
+- Fixed OAuth refresh token rotation to reject refresh tokens presented by a different authenticated client.
+- Fixed OAuth client-secret verification to use constant-time comparison for encrypted and custom-hashed storage modes.
+- Hardened router and OAuth protocol behavior around path handling, issuer metadata, and public route coverage.
 
 ## [0.4.0] - 2026-04-30
 

data/README.md

@@ -378,6 +378,18 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Security
 
+### Trusted origins
+
+`trusted_origins` is merged with the resolved application origin and deployment
+configuration rather than acting as an adapter-local CORS switch. Upstream
+Better Auth also incorporates environment-driven origins and dynamic
+configuration, so an explicit empty array should not be assumed to mean "reject
+every browser origin" unless the deployed core configuration documents that full
+merge contract. Configure concrete origins for each environment and keep browser
+CORS headers in the host Rack stack or reverse proxy. See
+[`host-app-responsibilities.md`](../../.docs/features/host-app-responsibilities.md)
+for the boundary between origin validation, CORS, and CSRF ownership.
+
 If you discover a security vulnerability within Better Auth Ruby, please send an e-mail to [security@openparcel.dev](mailto:security@openparcel.dev).
 
 All reports will be promptly addressed, and you'll be credited accordingly.

data/lib/better_auth/adapters/join_support.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Adapters
+    module JoinSupport
+      private
+
+      def normalized_join(model, join)
+        return {} unless join
+
+        join.each_with_object({}) do |(join_model, config), result|
+          join_model = join_model.to_s
+          result[join_model] = normalize_join_config(model.to_s, join_model, config)
+        end
+      end
+
+      def normalize_join_config(model, join_model, config)
+        if config.is_a?(Hash) && (config.key?(:on) || config.key?("on"))
+          on = config[:on] || config["on"]
+          from = storage_key(fetch_key(on, :from))
+          to = storage_key(fetch_key(on, :to))
+          relation = config[:relation] || config["relation"]
+          limit = config[:limit] || config["limit"]
+          return {from: from, to: to, relation: relation, limit: limit, unique: unique_join_field?(join_model, to)}
+        end
+
+        inferred = inferred_join_config(model, join_model)
+        if config.is_a?(Hash)
+          relation = config[:relation] || config["relation"]
+          limit = config[:limit] || config["limit"]
+          inferred = inferred.merge(relation: relation) if relation
+          inferred = inferred.merge(limit: limit) if limit
+        end
+        inferred
+      end
+
+      def reference_model_matches?(attributes, model)
+        reference = attributes[:references]
+        return false unless reference
+
+        reference_model = reference[:model] || reference["model"]
+        reference_model.to_s == model.to_s || reference_model.to_s == table_for(model)
+      end
+
+      def unique_join_field?(model, field)
+        field = storage_key(field)
+        field == "id" || schema_for(model).fetch(:fields).dig(field, :unique) == true
+      end
+
+      def collection_join?(model, join)
+        normalized_join(model, join).any? do |_join_model, config|
+          if config.key?(:relation)
+            config[:relation] != "one-to-one" && config[:unique] != true
+          elsif config.key?(:collection)
+            config[:collection] == true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/adapters/memory.rb

@@ -172,13 +172,13 @@ module BetterAuth
         when "ne"
           current != comparable
         when "gt"
-          !comparable.nil? && current > comparable
+          !current.nil? && !comparable.nil? && current > comparable
         when "gte"
-          !comparable.nil? && current >= comparable
+          !current.nil? && !comparable.nil? && current >= comparable
         when "lt"
-          !comparable.nil? && current < comparable
+          !current.nil? && !comparable.nil? && current < comparable
         when "lte"
-          !comparable.nil? && current <= comparable
+          !current.nil? && !comparable.nil? && current <= comparable
         else
           current == comparable
         end

data/lib/better_auth/adapters/sql.rb

@@ -7,6 +7,8 @@ require "time"
 module BetterAuth
   module Adapters
     class SQL < Base
+      include JoinSupport
+
       attr_reader :connection, :dialect
 
       def initialize(options, connection:, dialect:)
@@ -191,35 +193,6 @@ module BetterAuth
         end.join
       end
 
-      def normalized_join(model, join)
-        return {} unless join
-
-        join.each_with_object({}) do |(join_model, config), result|
-          join_model = join_model.to_s
-          result[join_model] = normalize_join_config(model.to_s, join_model, config)
-        end
-      end
-
-      def normalize_join_config(model, join_model, config)
-        if config.is_a?(Hash) && (config.key?(:on) || config.key?("on"))
-          on = config[:on] || config["on"]
-          from = storage_key(fetch_key(on, :from))
-          to = storage_key(fetch_key(on, :to))
-          relation = config[:relation] || config["relation"]
-          limit = config[:limit] || config["limit"]
-          return {from: from, to: to, relation: relation, limit: limit, unique: unique_join_field?(join_model, to)}
-        end
-
-        inferred = inferred_join_config(model, join_model)
-        if config.is_a?(Hash)
-          relation = config[:relation] || config["relation"]
-          limit = config[:limit] || config["limit"]
-          inferred = inferred.merge(relation: relation) if relation
-          inferred = inferred.merge(limit: limit) if limit
-        end
-        inferred
-      end
-
       def inferred_join_config(model, join_model)
         foreign_keys = schema_for(join_model).fetch(:fields).select do |_field, attributes|
           reference_model_matches?(attributes, model)
@@ -246,19 +219,6 @@ module BetterAuth
         end
       end
 
-      def reference_model_matches?(attributes, model)
-        reference = attributes[:references]
-        return false unless reference
-
-        reference_model = reference[:model] || reference["model"]
-        reference_model.to_s == model.to_s || reference_model.to_s == table_for(model)
-      end
-
-      def unique_join_field?(model, field)
-        field = storage_key(field)
-        field == "id" || schema_for(model).fetch(:fields).dig(field, :unique) == true
-      end
-
       def build_where(model, where, params)
         Array(where).each_with_index.map do |clause, index|
           field = storage_key(fetch_key(clause, :field))
@@ -277,13 +237,14 @@ module BetterAuth
             sql_operator = (operator == "not_in") ? "NOT IN" : "IN"
             "#{column} #{sql_operator} (#{placeholders})"
           when "contains", "starts_with", "ends_with"
+            escaped = escape_like(value)
             pattern = case operator
-            when "starts_with" then "#{value}%"
-            when "ends_with" then "%#{value}"
-            else "%#{value}%"
+            when "starts_with" then "#{escaped}%"
+            when "ends_with" then "%#{escaped}"
+            else "%#{escaped}%"
             end
             params << pattern
-            "#{column} LIKE #{placeholder(params.length)}"
+            "#{column} LIKE #{placeholder(params.length)} ESCAPE #{escape_literal}"
           else
             params << coerce_where_value(value, attributes)
             "#{column} #{sql_operator(operator)} #{placeholder(params.length)}"
@@ -379,12 +340,6 @@ module BetterAuth
         end
       end
 
-      def collection_join?(model, join)
-        normalized_join(model, join).any? do |_join_model, config|
-          config[:relation] != "one-to-one" && config[:unique] != true
-        end
-      end
-
       def aggregate_collection_joins(model, records, join)
         join_config = normalized_join(model, join)
         grouped = {}
@@ -450,6 +405,14 @@ module BetterAuth
         SecureRandom.hex(16)
       end
 
+      def escape_like(value)
+        value.to_s.gsub(/[\\%_]/) { |match| "\\#{match}" }
+      end
+
+      def escape_literal
+        (dialect == :postgres) ? "'\\\\'" : "'\\'"
+      end
+
       def resolve_default(default)
         default.respond_to?(:call) ? default.call : default
       end

data/lib/better_auth/endpoint.rb

@@ -12,9 +12,10 @@ module BetterAuth
       :metadata,
       :options,
       :use,
+      :disable_body,
       :handler
 
-    def initialize(path: nil, method: nil, body_schema: nil, query_schema: nil, params_schema: nil, headers_schema: nil, metadata: {}, use: [], &handler)
+    def initialize(path: nil, method: nil, body_schema: nil, query_schema: nil, params_schema: nil, headers_schema: nil, metadata: {}, use: [], disable_body: false, &handler)
       @path = path
       @methods = Array(method || "*").map { |value| value.to_s.upcase }
       @body_schema = body_schema
@@ -26,6 +27,7 @@ module BetterAuth
       apply_open_api_schemas!
       @options = endpoint_options
       @use = Array(use)
+      @disable_body = !!disable_body
       @handler = handler || ->(_ctx) {}
     end
 
@@ -57,6 +59,7 @@ module BetterAuth
         query: query_schema,
         params: params_schema,
         headers: headers_schema,
+        disableBody: disable_body,
         metadata: metadata
       }.compact
     end
@@ -249,19 +252,21 @@ module BetterAuth
         :body,
         :params,
         :headers,
+        :raw_body,
         :context,
         :request,
         :status,
         :returned,
         :response_headers
 
-      def initialize(path:, method:, query:, body:, params:, headers:, context:, request: nil)
+      def initialize(path:, method:, query:, body:, params:, headers:, context:, request: nil, raw_body: nil)
         @path = path
         @method = method.to_s.upcase
         @query = query || {}
         @body = body || {}
         @params = params || {}
         @headers = normalize_headers(headers || {})
+        @raw_body = raw_body
         @context = context
         @request = request
         @status = 200

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

@@ -6,31 +6,35 @@ module BetterAuth
       module_function
 
       def legacy_register_endpoint(config)
-        Endpoint.new(path: "/mcp/register", method: "POST") do |ctx|
+        Endpoint.new(path: "/mcp/register", method: "POST", metadata: BetterAuth::Plugins.mcp_openapi("legacyRegisterMcpClient", "Register an OAuth2 application using the legacy MCP path", "OAuth2 application registered successfully", BetterAuth::Plugins.mcp_client_schema)) do |ctx|
           ctx.json(register_client(ctx, config), status: 201, headers: no_store_headers)
         end
       end
 
       def legacy_authorize_endpoint(config)
-        Endpoint.new(path: "/mcp/authorize", method: "GET") do |ctx|
+        Endpoint.new(path: "/mcp/authorize", method: "GET", metadata: BetterAuth::Plugins.mcp_openapi("legacyMcpOAuthAuthorize", "Authorize an OAuth2 request using the legacy MCP path", "Authorization response generated successfully", {type: "object", additionalProperties: true})) do |ctx|
           authorize(ctx, config)
         end
       end
 
       def legacy_token_endpoint(config)
-        Endpoint.new(path: "/mcp/token", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+        Endpoint.new(
+          path: "/mcp/token",
+          method: "POST",
+          metadata: BetterAuth::Plugins.mcp_openapi("legacyMcpOAuthToken", "Exchange OAuth2 code for MCP tokens using the legacy path", "OAuth2 tokens issued successfully", BetterAuth::Plugins.mcp_token_response_schema).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+        ) do |ctx|
           ctx.json(token(ctx, config), headers: no_store_headers)
         end
       end
 
       def legacy_userinfo_endpoint(config)
-        Endpoint.new(path: "/mcp/userinfo", method: "GET") do |ctx|
+        Endpoint.new(path: "/mcp/userinfo", method: "GET", metadata: BetterAuth::Plugins.mcp_openapi("legacyMcpOAuthUserinfo", "Get MCP OAuth2 user information using the legacy path", "User information retrieved successfully", BetterAuth::Plugins.mcp_userinfo_schema)) do |ctx|
           ctx.json(userinfo(ctx, config))
         end
       end
 
       def legacy_jwks_endpoint(config)
-        Endpoint.new(path: "/mcp/jwks", method: "GET") do |ctx|
+        Endpoint.new(path: "/mcp/jwks", method: "GET", metadata: BetterAuth::Plugins.mcp_openapi("legacyMcpJSONWebKeySet", "Get the MCP JSON Web Key Set using the legacy path", "JSON Web Key Set retrieved successfully", BetterAuth::Plugins.mcp_jwks_response_schema)) do |ctx|
           ctx.json(jwks(ctx, config))
         end
       end

data/lib/better_auth/plugins/mcp.rb

@@ -86,7 +86,7 @@ module BetterAuth
     end
 
     def mcp_consent_endpoint(config)
-      Endpoint.new(path: "/oauth2/consent", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/consent", method: "POST", metadata: mcp_openapi("mcpOAuthConsent", "Handle MCP OAuth2 consent", "OAuth2 consent handled successfully", {type: "object", additionalProperties: true})) do |ctx|
         ctx.json(MCP.consent(ctx, config))
       end
     end
@@ -120,13 +120,21 @@ module BetterAuth
     end
 
     def mcp_introspect_endpoint(config)
-      Endpoint.new(path: "/oauth2/introspect", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/introspect",
+        method: "POST",
+        metadata: mcp_openapi("mcpOAuthIntrospect", "Introspect an MCP OAuth2 token", "OAuth2 token introspection result", mcp_introspection_schema).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         ctx.json(MCP.introspect(ctx, config))
       end
     end
 
     def mcp_revoke_endpoint(config)
-      Endpoint.new(path: "/oauth2/revoke", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/revoke",
+        method: "POST",
+        metadata: mcp_openapi("mcpOAuthRevoke", "Revoke an MCP OAuth2 token", "OAuth2 token revoked successfully", OpenAPI.object_schema({revoked: {type: "boolean"}}, required: ["revoked"])).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         ctx.json(MCP.revoke(ctx, config))
       end
     end
@@ -186,5 +194,22 @@ module BetterAuth
         required: ["keys"]
       )
     end
+
+    def mcp_introspection_schema
+      OpenAPI.object_schema(
+        {
+          active: {type: "boolean"},
+          client_id: {type: ["string", "null"]},
+          scope: {type: ["string", "null"]},
+          sub: {type: ["string", "null"]},
+          iss: {type: ["string", "null"]},
+          iat: {type: ["number", "null"]},
+          exp: {type: ["number", "null"]},
+          sid: {type: ["string", "null"]},
+          aud: {type: ["string", "array", "null"], items: {type: "string"}}
+        },
+        required: ["active"]
+      )
+    end
   end
 end

data/lib/better_auth/plugins/oauth_protocol.rb

@@ -344,7 +344,7 @@ module BetterAuth
         raise APIError.new("UNAUTHORIZED", message: "invalid_client")
       end
 
-      def store_code(store, code:, client_id:, redirect_uri:, session:, scopes:, code_challenge: nil, code_challenge_method: nil, nonce: nil, reference_id: nil, auth_time: nil)
+      def store_code(store, code:, client_id:, redirect_uri:, session:, scopes:, code_challenge: nil, code_challenge_method: nil, nonce: nil, reference_id: nil, auth_time: nil, expires_in: 600)
         store[:codes][code] = {
           client_id: client_id,
           redirect_uri: redirect_uri,
@@ -355,7 +355,7 @@ module BetterAuth
           nonce: nonce,
           reference_id: reference_id,
           auth_time: auth_time || session_auth_time(session),
-          expires_at: Time.now + 600
+          expires_at: Time.now + expires_in.to_i
         }
       end
 
@@ -403,7 +403,7 @@ module BetterAuth
         true
       end
 
-      def issue_tokens(ctx, store, model:, client:, session:, scopes:, include_refresh: false, issuer: nil, jwt_audience: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_signer: nil, prefix: {}, audience: nil, grant_type: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, pairwise_secret: nil, nonce: nil, auth_time: nil, reference_id: nil, filter_id_token_claims_by_scope: false)
+      def issue_tokens(ctx, store, model:, client:, session:, scopes:, include_refresh: false, issuer: nil, jwt_audience: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, grant_type: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, nonce: nil, auth_time: nil, reference_id: nil, filter_id_token_claims_by_scope: false)
         data = stringify_keys(session || {})
         user = stringify_keys(data["user"] || data[:user] || {})
         session_data = stringify_keys(data["session"] || data[:session] || {})
@@ -417,7 +417,7 @@ module BetterAuth
         scope = scope_string(scopes)
         expires_at = Time.now + access_token_expires_in.to_i
         access_token = if jwt_access_token && audience
-          build_jwt_access_token(ctx, client_data, user, session_data, scope, audience, issuer || issuer(ctx), expires_at, custom_access_token_claims, reference_id: token_reference_id)
+          build_jwt_access_token(ctx, client_data, user, session_data, scope, audience, issuer || issuer(ctx), expires_at, custom_access_token_claims, reference_id: token_reference_id, use_jwt_plugin: use_jwt_plugin)
         else
           apply_prefix(access_token_value, prefix, :access_token)
         end
@@ -461,7 +461,9 @@ module BetterAuth
             "issuer" => issuer || issuer(ctx),
             "issuedAt" => Time.now
           }
-          ctx.context.adapter.create(model: model, data: record)
+          created_access = ctx.context.adapter.create(model: model, data: record)
+          created = stringify_keys(created_access || {})
+          record = record.merge("id" => created["id"]) if created["id"]
           stored_record = record.merge("user" => user, "session" => session_data, "client" => client_data)
           store[:tokens][access_token_value] = stored_record
           store[:tokens][access_token] = stored_record
@@ -476,7 +478,7 @@ module BetterAuth
         }
         response[:audience] = audience if audience
         response[:refresh_token] = refresh_token if refresh_token
-        response[:id_token] = id_token(user.merge("id" => subject), client_data["clientId"], issuer || issuer(ctx), jwt_audience || client_data["clientId"], ctx: ctx, signer: id_token_signer, session_id: session_data["id"], include_sid: !!client_data["enableEndSession"], nonce: nonce, auth_time: token_auth_time, custom_claims: custom_id_token_claims, scopes: parse_scopes(scope), client: client_data, filter_claims_by_scope: filter_id_token_claims_by_scope) if parse_scopes(scope).include?("openid")
+        response[:id_token] = id_token(user.merge("id" => subject), client_data["clientId"], issuer || issuer(ctx), jwt_audience || client_data["clientId"], ctx: ctx, signer: id_token_signer, session_id: session_data["id"], include_sid: !!client_data["enableEndSession"], nonce: nonce, auth_time: token_auth_time, custom_claims: custom_id_token_claims, scopes: parse_scopes(scope), client: client_data, filter_claims_by_scope: filter_id_token_claims_by_scope, expires_in: id_token_expires_in, use_jwt_plugin: use_jwt_plugin) if parse_scopes(scope).include?("openid")
         if custom_token_response_fields.respond_to?(:call)
           extra = custom_token_response_fields.call({grant_type: grant_type, user: user.empty? ? nil : user, scopes: parse_scopes(scope), metadata: stringify_keys(client_data["metadata"] || {})})
           response.merge!(stringify_keys(extra).reject { |key, _value| standard_token_response_field?(key) }.transform_keys(&:to_sym)) if extra.is_a?(Hash)
@@ -484,7 +486,7 @@ module BetterAuth
         response
       end
 
-      def refresh_tokens(ctx, store, model:, client:, refresh_token:, scopes: nil, issuer: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_signer: nil, prefix: {}, audience: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, pairwise_secret: nil, filter_id_token_claims_by_scope: false)
+      def refresh_tokens(ctx, store, model:, client:, refresh_token:, scopes: nil, issuer: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, filter_id_token_claims_by_scope: false)
         refresh_token_value = strip_prefix(refresh_token, prefix, :refresh_token)
         data = refresh_token_value ? store[:refresh_tokens][refresh_token_value] : nil
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data
@@ -494,6 +496,11 @@ module BetterAuth
         end
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") if data["expiresAt"] && data["expiresAt"] <= Time.now
 
+        client_data = stringify_keys(client)
+        unless data["clientId"].to_s == client_data["clientId"].to_s
+          raise APIError.new("BAD_REQUEST", message: "invalid_grant")
+        end
+
         requested = scopes ? parse_scopes(scopes) : data["scopes"]
         unless requested.all? { |scope| data["scopes"].include?(scope) }
           raise APIError.new("BAD_REQUEST", message: "invalid_scope")
@@ -520,7 +527,9 @@ module BetterAuth
           custom_access_token_claims: custom_access_token_claims,
           custom_id_token_claims: custom_id_token_claims,
           jwt_access_token: jwt_access_token,
+          use_jwt_plugin: use_jwt_plugin,
           pairwise_secret: pairwise_secret,
+          id_token_expires_in: id_token_expires_in,
           auth_time: data["authTime"],
           reference_id: data["referenceId"],
           filter_id_token_claims_by_scope: filter_id_token_claims_by_scope
@@ -537,13 +546,13 @@ module BetterAuth
         data
       end
 
-      def build_jwt_access_token(ctx, client, user, session, scope, audience, issuer_value, expires_at, custom_claims, reference_id: nil)
+      def build_jwt_access_token(ctx, client, user, session, scope, audience, issuer_value, expires_at, custom_claims, reference_id: nil, use_jwt_plugin: false)
         scopes = parse_scopes(scope)
         extra = if custom_claims.respond_to?(:call)
           custom_claims.call({user: user.empty? ? nil : user, scopes: scopes, resource: audience, reference_id: reference_id, metadata: stringify_keys(client["metadata"] || {})})
         end
         payload = (extra.is_a?(Hash) ? stringify_keys(extra) : {}).merge(
-          "sub" => user["id"],
+          "sub" => user["id"] || client["clientId"],
           "aud" => audience,
           "azp" => client["clientId"],
           "scope" => scope,
@@ -555,10 +564,15 @@ module BetterAuth
           "iat" => Time.now.to_i,
           "exp" => expires_at.to_i
         ).compact
+        if use_jwt_plugin
+          signed = sign_oauth_jwt(ctx, payload, issuer: issuer_value, audience: audience)
+          return signed if signed
+        end
+
         ::JWT.encode(payload, ctx.context.secret, "HS256")
       end
 
-      def userinfo(store, authorization, additional_claim: nil, prefix: {}, jwt_secret: nil)
+      def userinfo(store, authorization, additional_claim: nil, prefix: {}, jwt_secret: nil, ctx: nil, issuer: nil)
         if authorization.to_s.strip.empty?
           raise APIError.new(
             "UNAUTHORIZED",
@@ -568,7 +582,7 @@ module BetterAuth
         end
         token = authorization.to_s.delete_prefix("Bearer ").strip
         record = token_record(store, token, prefix: prefix)
-        return jwt_userinfo(token, jwt_secret, additional_claim: additional_claim) unless record
+        return jwt_userinfo(token, jwt_secret, additional_claim: additional_claim, ctx: ctx, issuer: issuer) unless record
         user = stringify_keys(record["user"])
         scopes = parse_scopes(record["scopes"])
         raise userinfo_openid_scope_error unless scopes.include?("openid")
@@ -593,8 +607,12 @@ module BetterAuth
         response
       end
 
-      def jwt_userinfo(token, jwt_secret, additional_claim: nil)
-        payload = ::JWT.decode(token, jwt_secret.to_s, true, algorithm: "HS256").first
+      def jwt_userinfo(token, jwt_secret, additional_claim: nil, ctx: nil, issuer: nil)
+        payload = if ctx
+          verify_oauth_jwt(ctx, token, issuer: issuer || issuer(ctx), hs256_secret: jwt_secret)
+        else
+          ::JWT.decode(token, jwt_secret.to_s, true, algorithm: "HS256").first
+        end
         scopes = parse_scopes(payload["scope"])
         raise userinfo_openid_scope_error unless scopes.include?("openid")
 
@@ -700,7 +718,7 @@ module BetterAuth
         end
       end
 
-      def id_token(user, client_id, issuer_value, audience, ctx: nil, signer: nil, session_id: nil, include_sid: false, nonce: nil, auth_time: nil, custom_claims: nil, scopes: [], client: {}, filter_claims_by_scope: false)
+      def id_token(user, client_id, issuer_value, audience, ctx: nil, signer: nil, session_id: nil, include_sid: false, nonce: nil, auth_time: nil, custom_claims: nil, scopes: [], client: {}, filter_claims_by_scope: false, expires_in: 3600, use_jwt_plugin: false)
         requested_scopes = parse_scopes(scopes)
         payload = {
           sub: user["id"],
@@ -726,13 +744,54 @@ module BetterAuth
         end
         return signer.call(ctx, payload) if signer.respond_to?(:call)
 
+        if use_jwt_plugin && ctx
+          signed = sign_oauth_jwt(ctx, payload, issuer: issuer_value, audience: audience)
+          return signed if signed
+        end
+
         Crypto.sign_jwt(
           payload,
-          client_id.to_s.empty? ? "better-auth" : client_id.to_s,
-          expires_in: 3600
+          id_token_hs256_key(ctx, client_id, stringify_keys(client)["clientSecret"] || stringify_keys(client)["client_secret"]),
+          expires_in: expires_in
         )
       end
 
+      def id_token_hs256_key(ctx, client_id, client_secret = nil)
+        return client_secret.to_s unless client_secret.to_s.empty?
+
+        label = client_id.to_s.empty? ? "better-auth" : client_id.to_s
+        OpenSSL::HMAC.hexdigest("SHA256", ctx.context.secret.to_s, "oidc.id_token.#{label}")
+      end
+
+      def jwt_plugin_options(ctx)
+        plugin = ctx.context.options.plugins.find { |entry| entry.id == "jwt" }
+        plugin&.options
+      end
+
+      def oauth_jwt_config(ctx, issuer:, audience:)
+        options = jwt_plugin_options(ctx)
+        return nil unless options
+
+        BetterAuth::Plugins.deep_merge(options, jwt: {issuer: issuer, audience: audience})
+      end
+
+      def sign_oauth_jwt(ctx, payload, issuer:, audience:)
+        config = oauth_jwt_config(ctx, issuer: issuer, audience: audience)
+        return nil unless config
+
+        BetterAuth::Plugins.sign_jwt_payload(ctx, stringify_keys(payload), config)
+      end
+
+      def verify_oauth_jwt(ctx, token, issuer:, hs256_secret:)
+        payload = ::JWT.decode(token.to_s, nil, false).first
+        audience = payload["aud"]
+        config = oauth_jwt_config(ctx, issuer: issuer, audience: audience.is_a?(Array) ? audience.first : audience)
+        verified = BetterAuth::Plugins.verify_jwt_token(ctx, token, config) if config
+        return verified if verified
+
+        ::JWT.decode(token, hs256_secret.to_s, true, algorithm: "HS256").first
+      end
+
       def standard_token_response_field?(key)
         %w[access_token token_type expires_in scope refresh_token id_token audience].include?(key.to_s)
       end
@@ -801,11 +860,11 @@ module BetterAuth
       def verify_client_secret(ctx, stored_secret, provided_secret, mode)
         mode = normalize_secret_storage_mode(mode)
         return Crypto.constant_time_compare(Crypto.sha256(provided_secret, encoding: :base64url), stored_secret.to_s) if mode == "hashed"
-        return Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_secret) == provided_secret.to_s if mode == "encrypted"
+        return Crypto.constant_time_compare(Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_secret).to_s, provided_secret.to_s) if mode == "encrypted"
 
         if mode.is_a?(Hash)
-          return mode[:hash].call(provided_secret).to_s == stored_secret.to_s if mode[:hash].respond_to?(:call)
-          return mode[:decrypt].call(stored_secret).to_s == provided_secret.to_s if mode[:decrypt].respond_to?(:call)
+          return Crypto.constant_time_compare(mode[:hash].call(provided_secret).to_s, stored_secret.to_s) if mode[:hash].respond_to?(:call)
+          return Crypto.constant_time_compare(mode[:decrypt].call(stored_secret).to_s, provided_secret.to_s) if mode[:decrypt].respond_to?(:call)
         end
 
         Crypto.constant_time_compare(stored_secret.to_s, provided_secret.to_s)

data/lib/better_auth/plugins/oidc_provider.rb

@@ -437,7 +437,16 @@ module BetterAuth
       Endpoint.new(
         path: "/oauth2/endsession",
         method: ["GET", "POST"],
-        metadata: oidc_openapi("oauth2EndSession", "RP-Initiated Logout endpoint", "Logout request handled").merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+        metadata: {
+          openapi: {
+            operationId: "oauth2EndSession",
+            description: "RP-Initiated Logout endpoint",
+            responses: {
+              "302" => {description: "Redirects after clearing the session cookie"}
+            }
+          },
+          allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]
+        }
       ) do |ctx|
         input_source = (ctx.method == "GET") ? ctx.query : ctx.body
         input = OAuthProtocol.stringify_keys(input_source)

data/lib/better_auth/plugins/open_api.rb

@@ -90,6 +90,31 @@ module BetterAuth
       )
     end
 
+    def ref_schema(name, type: "object")
+      {type: type, "$ref": "#/components/schemas/#{name}"}
+    end
+
+    def array_schema(items)
+      {type: "array", items: items}
+    end
+
+    def nullable(type)
+      types = Array(type)
+      (types.include?("null") ? types : types + ["null"])
+    end
+
+    def query_parameter(name, required: false, schema: {type: "string"}, description: nil)
+      parameter = {name: name, in: "query", required: required, schema: schema}
+      parameter[:description] = description if description
+      parameter
+    end
+
+    def path_parameter(name, schema: {type: "string"}, description: nil)
+      parameter = {name: name, in: "path", required: true, schema: schema}
+      parameter[:description] = description if description
+      parameter
+    end
+
     def empty_request_body
       {
         content: {
@@ -243,10 +268,12 @@ module BetterAuth
 
     def open_api_paths(endpoints, options)
       disabled_paths = Array(options.disabled_paths).map(&:to_s)
-      endpoints.each_with_object({}) do |(_key, endpoint, tag), paths|
+      endpoints.each_with_object({}) do |(key, endpoint, tag), paths|
         next unless endpoint.path
-        next if endpoint.metadata[:hide] || endpoint.metadata[:SERVER_ONLY] || endpoint.metadata[:server_only]
+        next if endpoint.metadata[:exclude_from_openapi] || endpoint.metadata[:SERVER_ONLY] || endpoint.metadata[:server_only]
+        next if endpoint.metadata[:hide] && !open_api_documented_hidden_endpoint?(key, endpoint, tag)
         next if disabled_paths.include?(endpoint.path)
+        next if key == :set_password
 
         path = open_api_path(endpoint.path)
         paths[path] ||= {}
@@ -260,6 +287,10 @@ module BetterAuth
       path.split("/").map { |part| part.start_with?(":") ? "{#{part.delete_prefix(":")}}" : part }.join("/")
     end
 
+    def open_api_documented_hidden_endpoint?(key, endpoint, tag)
+      tag == "Default" && [:ok, :error].include?(key) && endpoint.metadata[:openapi]
+    end
+
     def open_api_operation(endpoint, method, tag)
       metadata = endpoint.metadata[:openapi] || {}
       operation = {
@@ -314,6 +345,8 @@ module BetterAuth
 
     def open_api_html(schema, config)
       nonce = config[:nonce] ? " nonce=\"#{config[:nonce]}\"" : ""
+      nonce_attr = config[:nonce] ? "nonce=\"#{config[:nonce]}\"" : ""
+      encoded_logo = open_api_encode_uri_component(open_api_logo)
       <<~HTML
         <!doctype html>
         <html>
@@ -323,12 +356,45 @@ module BetterAuth
             <meta name="viewport" content="width=device-width, initial-scale=1" />
           </head>
           <body>
-            <script id="api-reference" type="application/json">#{JSON.generate(schema)}</script>
-            <script#{nonce}>window.scalarTheme = "#{config[:theme]}";</script>
+            <script
+              id="api-reference"
+              type="application/json">
+            #{JSON.generate(schema)}
+            </script>
+            <script #{nonce_attr}>
+              var configuration = {
+                favicon: "data:image/svg+xml;utf8,#{encoded_logo}",
+                theme: "#{config[:theme] || "default"}",
+                metaData: {
+                  title: "Better Auth API",
+                  description: "API Reference for your Better Auth Instance",
+                }
+              }
+
+              document.getElementById('api-reference').dataset.configuration =
+                JSON.stringify(configuration)
+            </script>
             <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"#{nonce}></script>
           </body>
         </html>
       HTML
     end
+
+    def open_api_logo
+      <<~SVG
+        <svg width="75" height="75" viewBox="0 0 75 75" fill="none" xmlns="http://www.w3.org/2000/svg">
+          <rect width="75" height="75" rx="14" fill="#050505"/>
+          <path d="M19 50V25h15.5c5.5 0 9 2.6 9 6.6 0 2.7-1.6 4.7-4.1 5.7 3.2.9 5.2 3 5.2 6.1 0 4.2-3.7 6.6-9.6 6.6H19Zm7.1-14.8h7.2c2.1 0 3.2-.9 3.2-2.4s-1.1-2.4-3.2-2.4h-7.2v4.8Zm0 9.5h7.9c2.2 0 3.5-.9 3.5-2.5s-1.3-2.6-3.5-2.6h-7.9v5.1Z" fill="white"/>
+          <path d="M47 50V25h7.1v25H47Z" fill="white"/>
+        </svg>
+      SVG
+    end
+
+    def open_api_encode_uri_component(value)
+      value.to_s.bytes.map do |byte|
+        char = byte.chr
+        char.match?(/[A-Za-z0-9\-_.!~*'()]/) ? char : "%%%02X" % byte
+      end.join
+    end
   end
 end

data/lib/better_auth/router.rb

@@ -62,8 +62,9 @@ module BetterAuth
       return run_on_response_chain(method_not_allowed(allowed_methods)) unless endpoint.matches_method?(request.request_method)
       return run_on_response_chain(unsupported_media_type) unless allowed_media_type?(request, endpoint)
 
-      body = parse_body(request)
-      endpoint_context = build_endpoint_context(request, route_path, query, body, params)
+      raw_body = read_raw_body(request)
+      body = parse_body(request, raw_body: raw_body, disable_body: endpoint.disable_body)
+      endpoint_context = build_endpoint_context(request, route_path, query, body, params, raw_body)
       return run_on_response_chain(forbidden) if server_only?(endpoint)
 
       response = @origin_check.call(endpoint_context)
@@ -80,7 +81,7 @@ module BetterAuth
       response = rate_limiter.call(request, context, route_path)
       return run_on_response_chain(response) if response
 
-      endpoint_context = rebuild_endpoint_context(endpoint_context, request, route_path, params)
+      endpoint_context = rebuild_endpoint_context(endpoint_context, request, route_path, params, endpoint)
       result = API.new(context, endpoints).execute(endpoint, endpoint_context)
       response = result.response.is_a?(APIError) ? error_response(result.response, headers: result.headers) : result.to_rack_response
       run_on_response_chain(response)
@@ -161,12 +162,19 @@ module BetterAuth
       path.empty? ? "/" : path
     end
 
-    def parse_body(request)
-      return {} unless request.body
+    def read_raw_body(request)
+      return "" unless request.body
 
       request.body.rewind
       raw = request.body.read.to_s
       request.body.rewind
+      raw
+    end
+
+    def parse_body(request, raw_body:, disable_body: false)
+      return {} if disable_body
+
+      raw = raw_body.to_s
       return {} if raw.empty?
 
       if json_media_type?(request.media_type)
@@ -203,7 +211,7 @@ module BetterAuth
       request.GET
     end
 
-    def build_endpoint_context(request, path, query, body, params)
+    def build_endpoint_context(request, path, query, body, params, raw_body)
       Endpoint::Context.new(
         path: path,
         method: request.request_method,
@@ -212,12 +220,14 @@ module BetterAuth
         params: params,
         headers: headers_from(request.env),
         context: context,
-        request: request
+        request: request,
+        raw_body: raw_body
       )
     end
 
-    def rebuild_endpoint_context(previous_context, request, route_path, params)
-      fresh_context = build_endpoint_context(request, route_path, parse_query(request), parse_body(request), params)
+    def rebuild_endpoint_context(previous_context, request, route_path, params, endpoint)
+      raw_body = read_raw_body(request)
+      fresh_context = build_endpoint_context(request, route_path, parse_query(request), parse_body(request, raw_body: raw_body, disable_body: endpoint.disable_body), params, raw_body)
       fresh_context.headers = merge_hashes(previous_context.headers, fresh_context.headers)
       fresh_context.query = merge_hashes(previous_context.query, fresh_context.query)
       fresh_context.body = merge_hashes(previous_context.body, fresh_context.body)

data/lib/better_auth/routes/account.rb

@@ -229,7 +229,29 @@ module BetterAuth
               }
             ],
             responses: {
-              "200" => OpenAPI.json_response("Provider user info", {type: "object"})
+              "200" => OpenAPI.json_response(
+                "Success",
+                OpenAPI.object_schema(
+                  {
+                    user: OpenAPI.object_schema(
+                      {
+                        id: {type: "string"},
+                        name: {type: "string"},
+                        email: {type: "string"},
+                        image: {type: "string"},
+                        emailVerified: {type: "boolean"}
+                      },
+                      required: ["id", "emailVerified"]
+                    ),
+                    data: {
+                      type: "object",
+                      properties: {},
+                      additionalProperties: true
+                    }
+                  },
+                  required: ["user", "data"]
+                ).merge(additionalProperties: false)
+              )
             }
           }
         }

data/lib/better_auth/routes/error.rb

@@ -8,7 +8,26 @@ module BetterAuth
       Endpoint.new(
         path: "/error",
         method: "GET",
-        metadata: {hide: true}
+        metadata: {
+          hide: true,
+          openapi: {
+            description: "Displays an error page",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Success",
+                OpenAPI.object_schema(
+                  {
+                    html: {
+                      type: "string",
+                      description: "The HTML content of the error page"
+                    }
+                  },
+                  required: ["html"]
+                )
+              )
+            }
+          }
+        }
       ) do |ctx|
         query = ctx.query || {}
         raw_code = query["error"] || query[:error] || "UNKNOWN"

data/lib/better_auth/routes/ok.rb

@@ -6,7 +6,26 @@ module BetterAuth
       Endpoint.new(
         path: "/ok",
         method: "GET",
-        metadata: {hide: true}
+        metadata: {
+          hide: true,
+          openapi: {
+            description: "Check if the API is working",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "API is working",
+                OpenAPI.object_schema(
+                  {
+                    ok: {
+                      type: "boolean",
+                      description: "Indicates if the API is working"
+                    }
+                  },
+                  required: ["ok"]
+                )
+              )
+            }
+          }
+        }
       ) do |ctx|
         ctx.json({ok: true})
       end

data/lib/better_auth/routes/session.rb

@@ -11,7 +11,7 @@ module BetterAuth
             operationId: "getSession",
             description: "Get the current session",
             responses: {
-              "200" => OpenAPI.json_response("Current session or null", OpenAPI.session_response_schema_pair.merge(nullable: true))
+              "200" => OpenAPI.json_response("Current session or null", OpenAPI.session_response_schema_pair.merge(type: ["object", "null"]))
             }
           }
         }

data/lib/better_auth/routes/user.rb

@@ -101,6 +101,7 @@ module BetterAuth
         path: "/set-password",
         method: "POST",
         metadata: {
+          exclude_from_openapi: true,
           openapi: {
             operationId: "setPassword",
             description: "Set a password for the current user",

data/lib/better_auth/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BetterAuth
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/better_auth.rb

@@ -21,6 +21,7 @@ require_relative "better_auth/configuration"
 require_relative "better_auth/schema"
 require_relative "better_auth/schema/sql"
 require_relative "better_auth/adapters/base"
+require_relative "better_auth/adapters/join_support"
 require_relative "better_auth/adapters/memory"
 require_relative "better_auth/adapters/sql"
 require_relative "better_auth/adapters/postgres"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -259,6 +259,7 @@ files:
 - lib/better_auth.rb
 - lib/better_auth/adapters/base.rb
 - lib/better_auth/adapters/internal_adapter.rb
+- lib/better_auth/adapters/join_support.rb
 - lib/better_auth/adapters/memory.rb
 - lib/better_auth/adapters/mongodb.rb
 - lib/better_auth/adapters/mssql.rb