better_auth 0.8.0 → 0.10.0

data/lib/better_auth/plugins/mcp.rb

@@ -144,6 +144,7 @@ module BetterAuth
         openapi: {
           operationId: operation_id,
           description: description,
+          requestBody: mcp_request_body_for(operation_id),
           responses: {
             "200" => OpenAPI.json_response(response_description, response_schema)
           }
@@ -151,6 +152,46 @@ module BetterAuth
       }
     end
 
+    def mcp_request_body_for(operation_id)
+      schema = case operation_id
+      when "registerMcpClient", "legacyRegisterMcpClient"
+        OpenAPI.object_schema(
+          {
+            redirect_uris: {type: "array", items: {type: "string", format: "uri"}},
+            client_name: {type: "string"},
+            client_uri: {type: "string", format: "uri"},
+            logo_uri: {type: "string", format: "uri"},
+            grant_types: {type: "array", items: {type: "string"}},
+            response_types: {type: "array", items: {type: "string"}},
+            scope: {type: "string"},
+            contacts: {type: "array", items: {type: "string"}},
+            metadata: {type: "object", additionalProperties: true}
+          },
+          required: ["redirect_uris"]
+        )
+      when "mcpOAuthConsent"
+        OpenAPI.object_schema({consent_code: {type: "string"}, accept: {type: "boolean"}, scope: {type: "string"}, scopes: {type: "array", items: {type: "string"}}}, required: ["consent_code"])
+      when "mcpOAuthToken", "legacyMcpOAuthToken"
+        OpenAPI.object_schema(
+          {
+            grant_type: {type: "string", enum: [OAuthProtocol::AUTH_CODE_GRANT, OAuthProtocol::REFRESH_GRANT]},
+            code: {type: "string"},
+            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"]
+        )
+      when "mcpOAuthIntrospect", "mcpOAuthRevoke"
+        OpenAPI.object_schema({token: {type: "string"}, token_type_hint: {type: "string", enum: ["access_token", "refresh_token"]}}, required: ["token"])
+      end
+      schema ? OpenAPI.json_request_body(schema) : nil
+    end
+
     def mcp_client_schema
       OpenAPI.object_schema(
         {

data/lib/better_auth/plugins/oauth_protocol.rb

@@ -29,6 +29,12 @@ module BetterAuth
         parse_scopes(value).join(" ")
       end
 
+      def request_body!(value)
+        return stringify_keys(value || {}) if value.nil? || value.is_a?(Hash)
+
+        raise APIError.new("BAD_REQUEST", message: "request body must be an object")
+      end
+
       def issuer(ctx)
         ctx.context.options.base_url.to_s.empty? ? origin_for(ctx.context.base_url) : ctx.context.options.base_url
       end
@@ -100,7 +106,7 @@ module BetterAuth
       end
 
       def create_client(ctx, model:, body:, owner_session: nil, default_auth_method: "client_secret_basic", store_client_secret: "plain", unauthenticated: false, default_scopes: nil, allowed_scopes: nil, prefix: {}, dynamic_registration: false, admin: false, pairwise_secret: nil, strip_client_metadata: false, reference_id: nil)
-        body = stringify_keys(body || {})
+        body = request_body!(body || {})
         requested_auth_method = body["token_endpoint_auth_method"] || default_auth_method
         validate_client_metadata_enums!(requested_auth_method, body)
         validate_admin_only_fields!(body, admin: admin)
@@ -116,6 +122,7 @@ module BetterAuth
         grant_types = Array(body["grant_types"] || [AUTH_CODE_GRANT]).map(&:to_s)
         response_types = Array(body["response_types"] || ["code"]).map(&:to_s)
         validate_client_registration!(auth_method, grant_types, response_types, body, unauthenticated: unauthenticated, dynamic_registration: dynamic_registration)
+        validate_redirect_scheme_for_client!(auth_method, body, redirects)
         validate_pairwise_client!(body, redirects, pairwise_secret)
 
         scopes = parse_scopes(body["scope"] || body["scopes"])
@@ -237,6 +244,20 @@ module BetterAuth
         end
       end
 
+      def validate_redirect_scheme_for_client!(auth_method, body, redirects)
+        return if auth_method == "none" && body["type"] != "web"
+
+        redirects.each do |value|
+          uri = URI.parse(value.to_s)
+          next if uri.scheme == "https"
+          next if uri.scheme == "http" && loopback_host?(uri.hostname || uri.host)
+
+          raise APIError.new("BAD_REQUEST", message: "redirect_uris is invalid")
+        end
+      rescue URI::InvalidURIError
+        raise APIError.new("BAD_REQUEST", message: "redirect_uris is invalid")
+      end
+
       def validate_pairwise_client!(body, redirects, pairwise_secret)
         subject_type = body["subject_type"] || body["subjectType"]
         return unless subject_type == "pairwise"
@@ -266,7 +287,11 @@ module BetterAuth
       end
 
       def client_metadata(body, strip_unknown: false)
-        metadata = stringify_keys(body["metadata"] || {})
+        raw_metadata = body["metadata"]
+        unless raw_metadata.nil? || raw_metadata.is_a?(Hash)
+          raise APIError.new("BAD_REQUEST", message: "metadata must be an object")
+        end
+        metadata = stringify_keys(raw_metadata || {})
         metadata = metadata.slice("software_id", "software_version", "software_statement", "tos_uri", "policy_uri") if strip_unknown
         metadata["software_id"] = body["software_id"] if body["software_id"]
         metadata["software_version"] = body["software_version"] if body["software_version"]
@@ -313,15 +338,23 @@ module BetterAuth
         ctx.context.adapter.find_one(model: model, where: [{field: "clientId", value: client_id.to_s}])
       end
 
-      def authenticate_client!(ctx, model, store_client_secret: "plain", prefix: {})
-        body = stringify_keys(ctx.body || {})
+      def authenticate_client!(ctx, model, store_client_secret: "plain", prefix: {}, require_confidential: false)
+        body = request_body!(ctx.body || {})
         client_id = body["client_id"]
         client_secret = strip_prefix(body["client_secret"], prefix, :client_secret) || body["client_secret"]
 
         authorization = ctx.headers["authorization"]
-        if authorization.to_s.start_with?("Basic ") && client_id.to_s.empty?
-          decoded = Base64.decode64(authorization.delete_prefix("Basic "))
+        auth_method_used = client_secret.to_s.empty? ? nil : "client_secret_post"
+        if authorization.to_s.start_with?("Basic ")
+          decoded = Base64.strict_decode64(authorization.delete_prefix("Basic "))
+          unless decoded.include?(":")
+            raise APIError.new("BAD_REQUEST", message: "invalid authorization header format", body: {error: "invalid_client", error_description: "invalid authorization header format"})
+          end
           client_id, client_secret = decoded.split(":", 2)
+          if client_id.to_s.empty? || client_secret.to_s.empty?
+            raise APIError.new("BAD_REQUEST", message: "invalid authorization header format", body: {error: "invalid_client", error_description: "invalid authorization header format"})
+          end
+          auth_method_used = "client_secret_basic"
         end
 
         client = find_client(ctx, model, client_id)
@@ -332,20 +365,34 @@ module BetterAuth
 
         method = client_data["tokenEndpointAuthMethod"] || "client_secret_basic"
         if method == "none"
+          raise APIError.new("UNAUTHORIZED", message: "invalid_client") if require_confidential
           raise APIError.new("UNAUTHORIZED", message: "invalid_client") unless client_secret.to_s.empty?
           return client
         end
+        expected_method = (method == "client_secret_post") ? "client_secret_post" : "client_secret_basic"
+        raise APIError.new("UNAUTHORIZED", message: "invalid_client") unless auth_method_used == expected_method
+        if client_secret_expired?(client_data["clientSecretExpiresAt"])
+          raise APIError.new("UNAUTHORIZED", message: "invalid_client")
+        end
         if method != "none" && !verify_client_secret(ctx, stringify_keys(client)["clientSecret"], client_secret, store_client_secret)
           raise APIError.new("UNAUTHORIZED", message: "invalid_client")
         end
 
-        client
+        client.merge("__providedClientSecret" => client_secret)
       rescue ArgumentError
-        raise APIError.new("UNAUTHORIZED", message: "invalid_client")
+        raise APIError.new("BAD_REQUEST", message: "invalid authorization header format", body: {error: "invalid_client", error_description: "invalid authorization header format"})
       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, expires_in: 600)
-        store[:codes][code] = {
+      def client_secret_expired?(value)
+        return false if value.nil? || value.to_i == 0
+
+        seconds = timestamp_seconds(value)
+        seconds && seconds <= Time.now.to_i
+      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, expires_in: 600, store_tokens: "hashed")
+        stored_code = get_stored_token(store_tokens, code, "authorization_code")
+        store[:codes][stored_code] = {
           client_id: client_id,
           redirect_uri: redirect_uri,
           session: session,
@@ -359,8 +406,9 @@ module BetterAuth
         }
       end
 
-      def consume_code!(store, code, client_id:, redirect_uri:, code_verifier: nil)
-        data = store[:codes].delete(code.to_s)
+      def consume_code!(store, code, client_id:, redirect_uri:, code_verifier: nil, store_tokens: "hashed")
+        stored_code = get_stored_token(store_tokens, code.to_s, "authorization_code")
+        data = store[:codes].delete(stored_code) || store[:codes].delete(code.to_s)
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") if data[:expires_at] <= Time.now
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data[:client_id] == client_id.to_s
@@ -396,6 +444,7 @@ module BetterAuth
 
       def pkce_required?(client, scopes)
         data = stringify_keys(client)
+        return true if data["public"] || data["tokenEndpointAuthMethod"] == "none" || ["native", "user-agent-based"].include?(data["type"])
         return true if parse_scopes(scopes).include?("offline_access")
         require_pkce = client_require_pkce(data)
         return require_pkce unless require_pkce.nil?
@@ -403,7 +452,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_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)
+      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, store_tokens: "hashed")
         data = stringify_keys(session || {})
         user = stringify_keys(data["user"] || data[:user] || {})
         session_data = stringify_keys(data["session"] || data[:session] || {})
@@ -424,7 +473,7 @@ module BetterAuth
         refresh_record = nil
         if refresh_token_value
           refresh_record = {
-            "token" => refresh_token_value,
+            "token" => store_token_value(store_tokens, refresh_token_value, "refresh_token"),
             "clientId" => client_data["clientId"],
             "sessionId" => session_data["id"],
             "userId" => user["id"],
@@ -440,13 +489,13 @@ module BetterAuth
             "issuedAt" => Time.now
           }
           created_refresh = schema_model?(ctx, "oauthRefreshToken") ? ctx.context.adapter.create(model: "oauthRefreshToken", data: refresh_record) : nil
-          refresh_record = refresh_record.merge("id" => stringify_keys(created_refresh || {})["id"], "user" => user, "session" => session_data, "client" => client_data, "scope" => scope)
+          refresh_record = refresh_record.merge("id" => stringify_keys(created_refresh || {})["id"], "token" => refresh_token_value, "user" => user, "session" => session_data, "client" => client_data, "scope" => scope)
           store[:refresh_tokens][refresh_token_value] = refresh_record
           store[:refresh_tokens][refresh_token] = refresh_record
         end
         unless jwt_access_token && audience
           record = {
-            "token" => access_token_value,
+            "token" => store_token_value(store_tokens, access_token_value, "access_token"),
             "expiresAt" => expires_at,
             "clientId" => client_data["clientId"],
             "userId" => user["id"],
@@ -464,7 +513,7 @@ module BetterAuth
           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)
+          stored_record = record.merge("token" => access_token_value, "user" => user, "session" => session_data, "client" => client_data)
           store[:tokens][access_token_value] = stored_record
           store[:tokens][access_token] = stored_record
         end
@@ -478,7 +527,8 @@ 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, expires_in: id_token_expires_in, use_jwt_plugin: use_jwt_plugin) if parse_scopes(scope).include?("openid")
+        id_token_client_data = client_data.merge("clientSecret" => client_data["__providedClientSecret"] || client_data["clientSecret"])
+        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: id_token_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)
@@ -486,7 +536,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_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)
+      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, store_tokens: "hashed")
         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
@@ -532,7 +582,8 @@ module BetterAuth
           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
+          filter_id_token_claims_by_scope: filter_id_token_claims_by_scope,
+          store_tokens: store_tokens
         )
       end
 
@@ -757,6 +808,11 @@ module BetterAuth
       end
 
       def id_token_hs256_key(ctx, client_id, client_secret = nil)
+        oauth_provider = ctx&.context&.options&.plugins&.find { |plugin| plugin.id == "oauth-provider" }
+        if oauth_provider&.options&.fetch(:store_client_secret, nil).to_s == "hashed"
+          label = client_id.to_s.empty? ? "better-auth" : client_id.to_s
+          return OpenSSL::HMAC.hexdigest("SHA256", ctx.context.secret.to_s, "oidc.id_token.#{label}")
+        end
         return client_secret.to_s unless client_secret.to_s.empty?
 
         label = client_id.to_s.empty? ? "better-auth" : client_id.to_s
@@ -857,10 +913,29 @@ module BetterAuth
         secret
       end
 
+      def store_token_value(storage_method, token, type)
+        case storage_method
+        when "hashed", :hashed
+          Crypto.sha256(token.to_s, encoding: :base64url)
+        else
+          mode = normalize_secret_storage_mode(storage_method)
+          return mode[:hash].call(token.to_s, type) if mode.is_a?(Hash) && mode[:hash].respond_to?(:call)
+
+          raise Error, "storeToken: unsupported storageMethod type '#{storage_method}'"
+        end
+      end
+
+      def get_stored_token(storage_method, token, type)
+        store_token_value(storage_method, token, type)
+      end
+
       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.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 == "encrypted"
+          decrypted = Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_secret)
+          return Crypto.constant_time_compare(decrypted.to_s, provided_secret.to_s)
+        end
 
         if mode.is_a?(Hash)
           return Crypto.constant_time_compare(mode[:hash].call(provided_secret).to_s, stored_secret.to_s) if mode[:hash].respond_to?(:call)
@@ -868,6 +943,8 @@ module BetterAuth
         end
 
         Crypto.constant_time_compare(stored_secret.to_s, provided_secret.to_s)
+      rescue Error, ArgumentError
+        false
       end
 
       def normalize_secret_storage_mode(mode)

data/lib/better_auth/plugins/oidc_provider.rb

@@ -441,6 +441,8 @@ module BetterAuth
           openapi: {
             operationId: "oauth2EndSession",
             description: "RP-Initiated Logout endpoint",
+            parameters: oidc_end_session_schema[:properties].keys.map { |name| OpenAPI.query_parameter(name.to_s, schema: oidc_end_session_schema[:properties][name]) },
+            requestBody: OpenAPI.json_request_body(oidc_end_session_schema, required: false),
             responses: {
               "302" => {description: "Redirects after clearing the session cookie"}
             }
@@ -470,6 +472,7 @@ module BetterAuth
         openapi: {
           operationId: operation_id,
           description: description,
+          requestBody: oidc_request_body_for(operation_id),
           responses: {
             "200" => OpenAPI.json_response(response_description, response_schema)
           }
@@ -477,6 +480,62 @@ module BetterAuth
       }
     end
 
+    def oidc_request_body_for(operation_id)
+      schema = case operation_id
+      when "registerOAuthApplication", "updateOAuthApplication"
+        oidc_client_registration_schema
+      when "rotateOAuthApplicationSecret"
+        OpenAPI.empty_request_body.dig(:content, "application/json", :schema)
+      when "oauth2Consent"
+        OpenAPI.object_schema({consent_code: {type: "string"}, accept: {type: "boolean"}}, required: ["consent_code"])
+      when "oauth2Token"
+        OpenAPI.object_schema(
+          {
+            grant_type: {type: "string", enum: [OAuthProtocol::AUTH_CODE_GRANT, OAuthProtocol::REFRESH_GRANT]},
+            code: {type: "string"},
+            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"}
+          },
+          required: ["grant_type"]
+        )
+      when "oauth2Introspect", "oauth2Revoke"
+        OpenAPI.object_schema({token: {type: "string"}, token_type_hint: {type: "string", enum: ["access_token", "refresh_token"]}}, required: ["token"])
+      end
+      schema ? OpenAPI.json_request_body(schema) : nil
+    end
+
+    def oidc_client_registration_schema
+      OpenAPI.object_schema(
+        {
+          redirect_uris: {type: "array", items: {type: "string", format: "uri"}},
+          post_logout_redirect_uris: {type: "array", items: {type: "string", format: "uri"}},
+          client_name: {type: "string"},
+          client_uri: {type: "string", format: "uri"},
+          logo_uri: {type: "string", format: "uri"},
+          grant_types: {type: "array", items: {type: "string"}},
+          response_types: {type: "array", items: {type: "string"}},
+          scope: {type: "string"},
+          scopes: {type: "array", items: {type: "string"}},
+          metadata: {type: "object", additionalProperties: true}
+        }
+      )
+    end
+
+    def oidc_end_session_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
+
     def oidc_client_schema
       OpenAPI.object_schema(
         {
@@ -541,7 +600,7 @@ module BetterAuth
     def oidc_provider_schema
       {
         oauthApplication: {
-          modelName: "oauthApplication",
+          model_name: "oauth_applications",
           fields: {
             name: {type: "string"},
             icon: {type: "string", required: false},
@@ -565,7 +624,7 @@ module BetterAuth
           }
         },
         oauthAccessToken: {
-          modelName: "oauthAccessToken",
+          model_name: "oauth_access_tokens",
           fields: {
             accessToken: {type: "string", unique: true, required: false},
             token: {type: "string", unique: true, required: false},
@@ -583,7 +642,7 @@ module BetterAuth
           }
         },
         oauthConsent: {
-          modelName: "oauthConsent",
+          model_name: "oauth_consents",
           fields: {
             clientId: {type: "string", required: true},
             userId: {type: "string", required: true},

data/lib/better_auth/plugins/one_tap.rb

@@ -32,6 +32,14 @@ module BetterAuth
             operationId: "oneTapCallback",
             summary: "One tap callback",
             description: "Use this endpoint to authenticate with Google One Tap",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  id_token: {type: "string", description: "Google One Tap ID token"}
+                },
+                required: ["id_token"]
+              )
+            ),
             responses: {
               "200" => OpenAPI.json_response("Success", OpenAPI.session_response_schema_pair)
             }
@@ -105,16 +113,20 @@ module BetterAuth
         options[:aud] = audience
         options[:verify_aud] = true
       end
-      payload, = JWT.decode(id_token, nil, true, options.merge(jwks: jwks))
+      payload, = ::JWT.decode(id_token, nil, true, options.merge(jwks: jwks))
       payload
     end
 
     def one_tap_google_jwks
-      uri = URI("https://www.googleapis.com/oauth2/v3/certs")
-      response = Net::HTTP.get_response(uri)
-      raise "Unable to fetch Google JWKS" unless response.is_a?(Net::HTTPSuccess)
+      cached = @one_tap_google_jwks_cache
+      return cached[:jwks] if cached && cached[:expires_at] > Time.now
 
-      JWT::JWK::Set.new(JSON.parse(response.body))
+      payload = HTTPClient.get_json("https://www.googleapis.com/oauth2/v3/certs")
+      raise "Unable to fetch Google JWKS" unless payload
+
+      jwks = ::JWT::JWK::Set.new(payload)
+      @one_tap_google_jwks_cache = {jwks: jwks, expires_at: Time.now + 300}
+      jwks
     end
 
     def one_tap_link_account_unless_present!(ctx, _config, user, payload, id_token)

data/lib/better_auth/plugins/open_api.rb

@@ -128,6 +128,21 @@ module BetterAuth
       }
     end
 
+    def default_request_body
+      {
+        required: true,
+        content: {
+          "application/json" => {
+            schema: {
+              type: "object",
+              properties: {},
+              additionalProperties: true
+            }
+          }
+        }
+      }
+    end
+
     def responses(responses = nil)
       {"200" => success_response}.merge(default_error_responses).merge(responses || {})
     end
@@ -142,6 +157,17 @@ module BetterAuth
       )
     end
 
+    def default_success_response
+      json_response(
+        "Success",
+        {
+          type: "object",
+          properties: {},
+          additionalProperties: true
+        }
+      )
+    end
+
     def default_error_responses
       {
         "400" => error_response("Bad Request. Usually due to missing parameters, or invalid parameters.", required: true),
@@ -168,10 +194,16 @@ module BetterAuth
 
     def default_metadata(path, methods)
       method = Array(methods).reject { |value| value.to_s == "*" }.first.to_s.upcase
-      {
+      metadata = {
         operationId: operation_id(path, method),
-        description: "#{method} #{path}"
+        description: "Execute the #{operation_id(path, method)} endpoint.",
+        parameters: default_path_parameters(path),
+        responses: {
+          "200" => default_success_response
+        }
       }
+      metadata[:requestBody] = default_request_body if %w[POST PUT PATCH].include?(method)
+      metadata
     end
 
     def operation_id(path, method)
@@ -183,6 +215,14 @@ module BetterAuth
 
       "#{method.to_s.downcase}#{base}"
     end
+
+    def default_path_parameters(path)
+      path.to_s.split("/").filter_map do |part|
+        next unless part.start_with?(":")
+
+        path_parameter(part.delete_prefix(":"))
+      end
+    end
   end
 
   module Plugins