better_auth 0.4.0 → 0.6.0

data/lib/better_auth/routes/account.rb

@@ -3,7 +3,22 @@
 module BetterAuth
   module Routes
     def self.list_accounts
-      Endpoint.new(path: "/list-accounts", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/list-accounts",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "listUserAccounts",
+            description: "List linked accounts for the current user",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Linked accounts",
+                {type: "array", items: {type: "object", "$ref": "#/components/schemas/Account"}}
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx)
         accounts = ctx.context.internal_adapter.find_accounts(session[:user]["id"]).map do |account|
           parsed = Schema.parse_output(ctx.context.options, "account", account)
@@ -15,8 +30,33 @@ module BetterAuth
     end
 
     def self.unlink_account
-      Endpoint.new(path: "/unlink-account", method: "POST") do |ctx|
-        session = current_session(ctx, sensitive: true)
+      Endpoint.new(
+        path: "/unlink-account",
+        method: "POST",
+        body_schema: request_body_schema(
+          required_strings: %w[providerId],
+          optional_strings: %w[accountId]
+        ),
+        metadata: {
+          openapi: {
+            operationId: "unlinkAccount",
+            description: "Unlink an account from the current user",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  providerId: {type: "string"},
+                  accountId: {type: ["string", "null"]}
+                },
+                required: ["providerId"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Account unlinked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
+        session = current_session(ctx, sensitive: true, fresh: true)
         body = normalize_hash(ctx.body)
         accounts = ctx.context.internal_adapter.find_accounts(session[:user]["id"])
         if accounts.length == 1 && !ctx.context.options.account.dig(:account_linking, :allow_unlinking_all)
@@ -24,6 +64,8 @@ module BetterAuth
         end
 
         provider_id = body["providerId"] || body["provider_id"]
+        raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["VALIDATION_ERROR"]) if provider_id.to_s.empty?
+
         account_id = body["accountId"] || body["account_id"]
         account = accounts.find do |entry|
           entry["providerId"] == provider_id && (account_id.to_s.empty? || entry["accountId"] == account_id)
@@ -36,44 +78,108 @@ module BetterAuth
     end
 
     def self.get_access_token
-      Endpoint.new(path: "/get-access-token", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/get-access-token",
+        method: "POST",
+        body_schema: request_body_schema(
+          required_strings: %w[providerId],
+          optional_strings: %w[accountId userId]
+        ),
+        metadata: {
+          openapi: {
+            operationId: "getAccessToken",
+            description: "Get an access token for a linked provider account",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  providerId: {type: "string"},
+                  accountId: {type: ["string", "null"]},
+                  userId: {type: ["string", "null"]}
+                },
+                required: ["providerId"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Provider access token",
+                OpenAPI.object_schema(
+                  {
+                    accessToken: {type: ["string", "null"]},
+                    accessTokenExpiresAt: {type: ["string", "null"], format: "date-time"},
+                    scopes: {type: "array", items: {type: "string"}},
+                    idToken: {type: ["string", "null"]}
+                  },
+                  required: ["scopes"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, allow_nil: true)
         body = normalize_hash(ctx.body)
         user_id = session&.dig(:user, "id") || body["userId"] || body["user_id"]
         raise APIError.new("UNAUTHORIZED") if user_id.to_s.empty?
 
         provider_id = body["providerId"] || body["provider_id"]
-        provider = social_provider(ctx.context, provider_id)
-        raise APIError.new("BAD_REQUEST", message: "Provider #{provider_id} is not supported.") unless provider
+        raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["VALIDATION_ERROR"]) if provider_id.to_s.empty?
 
         account_id = body["accountId"] || body["account_id"]
-        account = account_cookie(ctx, provider_id, account_id, user_id) || find_provider_account(ctx, user_id, provider_id, account_id)
-        raise APIError.new("BAD_REQUEST", message: "Account not found") unless account
-
-        if account["refreshToken"] && access_token_expired?(account) && provider_callable(provider, :refresh_access_token)
-          tokens = call_provider(provider, :refresh_access_token, oauth_token_value(ctx, account["refreshToken"]))
-          updated = update_account_tokens(ctx, account, tokens)
-          account = account.merge(token_hash(tokens))
-          Cookies.set_account_cookie(ctx, updated || account.merge(token_hash_for_storage(ctx, tokens)))
-        end
-
-        ctx.json({
-          accessToken: oauth_token_value(ctx, account["accessToken"]),
-          accessTokenExpiresAt: account["accessTokenExpiresAt"],
-          scopes: account["scopes"] || (account["scope"].to_s.empty? ? [] : account["scope"].to_s.split(",")),
-          idToken: account["idToken"]
-        })
+        ctx.json(access_token_response(ctx, user_id: user_id, provider_id: provider_id, account_id: account_id))
       end
     end
 
     def self.refresh_token
-      Endpoint.new(path: "/refresh-token", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/refresh-token",
+        method: "POST",
+        body_schema: request_body_schema(
+          required_strings: %w[providerId],
+          optional_strings: %w[accountId userId]
+        ),
+        metadata: {
+          openapi: {
+            operationId: "refreshToken",
+            description: "Refresh an OAuth provider access token",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  providerId: {type: "string"},
+                  accountId: {type: ["string", "null"]},
+                  userId: {type: ["string", "null"]}
+                },
+                required: ["providerId"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Refreshed provider tokens",
+                OpenAPI.object_schema(
+                  {
+                    accessToken: {type: ["string", "null"]},
+                    refreshToken: {type: ["string", "null"]},
+                    accessTokenExpiresAt: {type: ["string", "null"], format: "date-time"},
+                    refreshTokenExpiresAt: {type: ["string", "null"], format: "date-time"},
+                    scope: {type: ["string", "null"]},
+                    idToken: {type: ["string", "null"]},
+                    providerId: {type: "string"},
+                    accountId: {type: "string"}
+                  },
+                  required: ["providerId", "accountId"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, allow_nil: true)
         body = normalize_hash(ctx.body)
         user_id = session&.dig(:user, "id") || body["userId"] || body["user_id"]
         raise APIError.new("BAD_REQUEST", message: "Either userId or session is required") if user_id.to_s.empty?
 
         provider_id = body["providerId"] || body["provider_id"]
+        raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["VALIDATION_ERROR"]) if provider_id.to_s.empty?
+
         provider = social_provider(ctx.context, provider_id)
         raise APIError.new("BAD_REQUEST", message: "Provider #{provider_id} not found.") unless provider
         raise APIError.new("BAD_REQUEST", message: "Provider #{provider_id} does not support token refreshing.") unless provider_callable(provider, :refresh_access_token)
@@ -84,10 +190,15 @@ module BetterAuth
         refresh_token = oauth_token_value(ctx, account["refreshToken"])
         raise APIError.new("BAD_REQUEST", message: "Refresh token not found") if refresh_token.to_s.empty?
 
-        tokens = call_provider(provider, :refresh_access_token, refresh_token)
-        updated = update_account_tokens(ctx, account, tokens)
-        values = token_hash(tokens)
-        Cookies.set_account_cookie(ctx, updated || account.merge(token_hash_for_storage(ctx, tokens)))
+        begin
+          tokens = call_provider(provider, :refresh_access_token, refresh_token)
+          updated = update_account_tokens(ctx, account, tokens)
+          values = token_hash(tokens)
+          Cookies.set_account_cookie(ctx, updated || account.merge(token_hash_for_storage(ctx, tokens)))
+        rescue => error
+          log(ctx.context, :error, "FAILED_TO_REFRESH_ACCESS_TOKEN #{error.message}")
+          raise APIError.new("BAD_REQUEST", code: "FAILED_TO_REFRESH_ACCESS_TOKEN", message: "Failed to refresh access token")
+        end
         ctx.json({
           accessToken: values["accessToken"],
           refreshToken: values["refreshToken"] || refresh_token,
@@ -102,31 +213,85 @@ module BetterAuth
     end
 
     def self.account_info
-      Endpoint.new(path: "/account-info", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/account-info",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "accountInfo",
+            description: "Get user info from a linked provider account",
+            parameters: [
+              {
+                name: "accountId",
+                in: "query",
+                required: false,
+                schema: {type: "string"}
+              }
+            ],
+            responses: {
+              "200" => OpenAPI.json_response("Provider user info", {type: "object"})
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx)
         account_id = fetch_value(ctx.query, "accountId")
         account = if account_id
           ctx.context.internal_adapter.find_accounts(session[:user]["id"]).find do |entry|
             entry["id"] == account_id || entry["accountId"] == account_id
           end
+        else
+          account_cookie(ctx, nil, nil, session[:user]["id"])
         end
         raise APIError.new("BAD_REQUEST", message: "Account not found") unless account && account["userId"] == session[:user]["id"]
 
         provider = social_provider(ctx.context, account["providerId"])
         raise APIError.new("INTERNAL_SERVER_ERROR", message: "Provider account provider is #{account["providerId"]} but it is not configured") unless provider
-        raise APIError.new("BAD_REQUEST", message: "Access token not found") if account["accessToken"].to_s.empty?
 
-        info = call_provider(provider, :get_user_info, {
-          accessToken: oauth_token_value(ctx, account["accessToken"]),
-          access_token: oauth_token_value(ctx, account["accessToken"]),
-          idToken: account["idToken"],
-          scopes: account["scope"].to_s.split(",")
-        })
+        tokens = access_token_response(
+          ctx,
+          user_id: session[:user]["id"],
+          provider_id: account["providerId"],
+          account_id: account["accountId"],
+          provider: provider
+        )
+        raise APIError.new("BAD_REQUEST", message: "Access token not found") if tokens[:accessToken].to_s.empty?
+
+        info = call_provider(provider, :get_user_info, tokens.merge(access_token: tokens[:accessToken]))
         ctx.json(info)
       end
     end
 
+    def self.access_token_response(ctx, user_id:, provider_id:, account_id: nil, provider: nil)
+      provider ||= social_provider(ctx.context, provider_id)
+      raise APIError.new("BAD_REQUEST", message: "Provider #{provider_id} is not supported.") unless provider
+
+      account = account_cookie(ctx, provider_id, account_id, user_id) || find_provider_account(ctx, user_id, provider_id, account_id)
+      raise APIError.new("BAD_REQUEST", message: "Account not found") unless account
+
+      if account["refreshToken"] && access_token_expired?(account) && provider_callable(provider, :refresh_access_token)
+        begin
+          tokens = call_provider(provider, :refresh_access_token, oauth_token_value(ctx, account["refreshToken"]))
+          updated = update_account_tokens(ctx, account, tokens)
+          account = account.merge(token_hash(tokens))
+          Cookies.set_account_cookie(ctx, updated || account.merge(token_hash_for_storage(ctx, tokens)))
+        rescue => error
+          log(ctx.context, :error, "FAILED_TO_GET_ACCESS_TOKEN #{error.message}")
+          raise APIError.new("BAD_REQUEST", code: "FAILED_TO_GET_ACCESS_TOKEN", message: "Failed to get a valid access token")
+        end
+      end
+
+      {
+        accessToken: oauth_token_value(ctx, account["accessToken"]),
+        accessTokenExpiresAt: account["accessTokenExpiresAt"],
+        scopes: account["scopes"] || (account["scope"].to_s.empty? ? [] : account["scope"].to_s.split(",")),
+        idToken: account["idToken"]
+      }
+    end
+
     def self.social_provider(context, provider_id)
+      return nil if provider_id.to_s.empty?
+
       provider = context.social_providers[provider_id.to_sym] || context.social_providers[provider_id.to_s]
       return provider.merge(id: provider_id.to_s) if provider.is_a?(Hash) && !provider.key?(:id) && !provider.key?("id")
 
@@ -143,7 +308,8 @@ module BetterAuth
       return nil unless ctx.context.options.account[:store_account_cookie]
 
       account = Cookies.get_account_cookie(ctx)
-      return nil unless account && account["providerId"] == provider_id
+      return nil unless account
+      return nil if provider_id && account["providerId"] != provider_id
       return nil unless account_id.to_s.empty? || account["id"] == account_id || account["accountId"] == account_id
       return nil unless user_id.to_s.empty? || account["userId"].to_s.empty? || account["userId"] == user_id
 
@@ -199,14 +365,14 @@ module BetterAuth
       return token if token.to_s.empty?
       return token unless ctx.context.options.account[:encrypt_oauth_tokens]
 
-      Crypto.symmetric_encrypt(key: ctx.context.secret, data: token)
+      Crypto.symmetric_encrypt(key: ctx.context.secret_config, data: token)
     end
 
     def self.oauth_token_value(ctx, token)
       return token if token.to_s.empty?
       return token unless ctx.context.options.account[:encrypt_oauth_tokens]
 
-      Crypto.symmetric_decrypt(key: ctx.context.secret, data: token) || token
+      Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: token) || token
     end
 
     def self.provider_callable(provider, key)

data/lib/better_auth/routes/email_verification.rb

@@ -5,7 +5,28 @@ require "uri"
 module BetterAuth
   module Routes
     def self.send_verification_email
-      Endpoint.new(path: "/send-verification-email", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/send-verification-email",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "sendVerificationEmail",
+            description: "Send an email verification link",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string", description: "The email address to verify"},
+                  callbackURL: {type: ["string", "null"], description: "The URL to redirect to after verification"}
+                },
+                required: ["email"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Verification email sent", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         sender = ctx.context.options.email_verification[:send_verification_email]
         raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["VERIFICATION_EMAIL_NOT_ENABLED"]) unless sender.respond_to?(:call)
 
@@ -32,7 +53,42 @@ module BetterAuth
     end
 
     def self.verify_email
-      Endpoint.new(path: "/verify-email", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/verify-email",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "verifyEmail",
+            description: "Verify an email address by token",
+            parameters: [
+              {
+                name: "token",
+                in: "query",
+                required: true,
+                schema: {type: "string"}
+              },
+              {
+                name: "callbackURL",
+                in: "query",
+                required: false,
+                schema: {type: "string"}
+              }
+            ],
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Email verified",
+                OpenAPI.object_schema(
+                  {
+                    status: {type: "boolean"},
+                    user: {type: ["object", "null"], "$ref": "#/components/schemas/User"}
+                  },
+                  required: ["status"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         token = fetch_value(ctx.query, "token").to_s
         callback_url = fetch_value(ctx.query, "callbackURL")
         validate_callback_url!(ctx.context, callback_url)
@@ -44,11 +100,27 @@ module BetterAuth
 
         user = user_data[:user]
         if update_to
-          updated = ctx.context.internal_adapter.update_user_by_email(email, email: update_to, emailVerified: false)
-          updated_user = updated || user.merge("email" => update_to, "emailVerified" => false)
-          send_verification_email_payload(ctx, updated_user, callback_url) if ctx.context.options.email_verification[:send_verification_email].respond_to?(:call)
-          set_verified_session_cookie(ctx, updated_user)
-          next redirect_or_json(ctx, callback_url, {status: true, user: Schema.parse_output(ctx.context.options, "user", updated)})
+          session = current_session(ctx, allow_nil: true)
+          return redirect_or_error(ctx, callback_url, "invalid_user") if session && session[:user]["email"] != email
+
+          request_type = payload["requestType"] || payload["request_type"]
+          case request_type
+          when "change-email-confirmation"
+            send_change_email_verification_payload(ctx, user, update_to, callback_url)
+            next redirect_or_json(ctx, callback_url, {status: true})
+          when "change-email-verification"
+            updated = ctx.context.internal_adapter.update_user_by_email(email, email: update_to, emailVerified: true)
+            updated_user = updated || user.merge("email" => update_to, "emailVerified" => true)
+            call_option(ctx.context.options.email_verification[:after_email_verification], updated_user, ctx.request)
+            set_verified_session_cookie(ctx, updated_user)
+            next redirect_or_json(ctx, callback_url, {status: true, user: Schema.parse_output(ctx.context.options, "user", updated_user)})
+          else
+            updated = ctx.context.internal_adapter.update_user_by_email(email, email: update_to, emailVerified: false)
+            updated_user = updated || user.merge("email" => update_to, "emailVerified" => false)
+            send_verification_email_payload(ctx, updated_user, callback_url) if ctx.context.options.email_verification[:send_verification_email].respond_to?(:call)
+            set_verified_session_cookie(ctx, updated_user)
+            next redirect_or_json(ctx, callback_url, {status: true, user: Schema.parse_output(ctx.context.options, "user", updated)})
+          end
         end
 
         if user["emailVerified"]
@@ -71,6 +143,16 @@ module BetterAuth
       ctx.context.options.email_verification[:send_verification_email].call({user: user, url: url, token: token}, ctx.request)
     end
 
+    def self.send_change_email_verification_payload(ctx, user, update_to, callback_url)
+      sender = ctx.context.options.email_verification[:send_verification_email]
+      return unless sender.respond_to?(:call)
+
+      token = create_email_verification_token(ctx, user["email"], update_to: update_to, extra: {"requestType" => "change-email-verification"})
+      callback = URI.encode_www_form_component(callback_url || "/")
+      url = "#{ctx.context.base_url}/verify-email?token=#{URI.encode_www_form_component(token)}&callbackURL=#{callback}"
+      sender.call({user: user.merge("email" => update_to), url: url, token: token}, ctx.request)
+    end
+
     def self.create_email_verification_token(ctx, email, update_to: nil, extra: {})
       payload = {"email" => email.to_s.downcase}.merge(extra)
       payload["updateTo"] = update_to if update_to
@@ -78,18 +160,20 @@ module BetterAuth
     end
 
     def self.verify_email_token(ctx, token, callback_url)
-      payload = Crypto.verify_jwt(token, ctx.context.secret)
-      return payload if payload
-
-      redirect_or_error(ctx, callback_url, "invalid_token")
+      decoded, = JWT.decode(token.to_s, ctx.context.secret.to_s, true, algorithm: "HS256")
+      decoded
+    rescue JWT::ExpiredSignature
+      redirect_or_error(ctx, callback_url, BASE_ERROR_CODES["TOKEN_EXPIRED"], code: "TOKEN_EXPIRED")
+    rescue JWT::DecodeError
+      redirect_or_error(ctx, callback_url, BASE_ERROR_CODES["INVALID_TOKEN"], code: "INVALID_TOKEN")
     end
 
-    def self.redirect_or_error(ctx, callback_url, error)
+    def self.redirect_or_error(ctx, callback_url, error, code: nil)
       if callback_url
         separator = callback_url.include?("?") ? "&" : "?"
-        raise ctx.redirect("#{callback_url}#{separator}error=#{error}")
+        raise ctx.redirect("#{callback_url}#{separator}error=#{code || error}")
       end
-      raise APIError.new("UNAUTHORIZED", message: error)
+      raise APIError.new("UNAUTHORIZED", code: code, message: error)
     end
 
     def self.redirect_or_json(ctx, callback_url, data)

data/lib/better_auth/routes/password.rb

@@ -8,14 +8,46 @@ module BetterAuth
     PASSWORD_RESET_MESSAGE = "If this email exists in our system, check your email for the reset link"
 
     def self.request_password_reset
-      Endpoint.new(path: "/request-password-reset", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/request-password-reset",
+        method: "POST",
+        body_schema: request_body_schema(email_strings: %w[email]),
+        metadata: {
+          openapi: {
+            operationId: "requestPasswordReset",
+            description: "Request a password reset link",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string", description: "The email address of the user"},
+                  redirectTo: {type: ["string", "null"], description: "The URL to redirect to after reset"}
+                },
+                required: ["email"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Password reset request processed",
+                OpenAPI.status_response_schema(
+                  {
+                    message: {type: "string"}
+                  },
+                  required: ["status", "message"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         sender = ctx.context.options.email_and_password[:send_reset_password]
-        raise APIError.new("BAD_REQUEST", message: "Reset password isn't enabled") unless sender.respond_to?(:call)
+        unless sender.respond_to?(:call)
+          raise APIError.new("BAD_REQUEST", code: "RESET_PASSWORD_DISABLED", message: BASE_ERROR_CODES["RESET_PASSWORD_DISABLED"])
+        end
 
         body = normalize_hash(ctx.body)
         email = body["email"].to_s.downcase
         redirect_to = body["redirectTo"] || body["redirect_to"]
-        validate_callback_url!(ctx.context, redirect_to)
+        validate_redirect_url!(ctx.context, redirect_to)
         found = ctx.context.internal_adapter.find_user_by_email(email, include_accounts: true)
         unless found
           SecureRandom.hex(12)
@@ -33,15 +65,46 @@ module BetterAuth
 
         callback = redirect_to ? URI.encode_www_form_component(redirect_to) : ""
         url = "#{ctx.context.base_url}/reset-password/#{token}?callbackURL=#{callback}"
-        sender.call({user: found[:user], url: url, token: token}, ctx.request)
+        begin
+          sender.call({user: found[:user], url: url, token: token}, ctx.request)
+        rescue => error
+          log(ctx.context, :error, "RESET_PASSWORD_EMAIL_ERROR #{error.message}")
+        end
         ctx.json({status: true, message: PASSWORD_RESET_MESSAGE})
       end
     end
 
     def self.request_password_reset_callback
-      Endpoint.new(path: "/reset-password/:token", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/reset-password/:token",
+        method: "GET",
+        query_schema: request_query_schema(required_strings: %w[callbackURL]),
+        metadata: {
+          openapi: {
+            operationId: "requestPasswordResetCallback",
+            description: "Validate a password reset token and redirect to the callback URL",
+            parameters: [
+              {
+                name: "token",
+                in: "path",
+                required: true,
+                schema: {type: "string"}
+              },
+              {
+                name: "callbackURL",
+                in: "query",
+                required: true,
+                schema: {type: "string"}
+              }
+            ],
+            responses: {
+              "302" => {description: "Redirects to callback URL with token or error"}
+            }
+          }
+        }
+      ) do |ctx|
         token = ctx.params[:token].to_s
-        callback_url = fetch_value(ctx.query, "callbackURL") || "/error"
+        callback_url = fetch_value(ctx.query, "callbackURL")
         validate_callback_url!(ctx.context, callback_url)
         verification = ctx.context.internal_adapter.find_verification_value("reset-password:#{token}")
 
@@ -54,7 +117,33 @@ module BetterAuth
     end
 
     def self.reset_password
-      Endpoint.new(path: "/reset-password", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/reset-password",
+        method: "POST",
+        body_schema: request_body_schema(
+          required_strings: %w[newPassword],
+          optional_strings: %w[token]
+        ),
+        query_schema: request_query_schema(optional_strings: %w[token]),
+        metadata: {
+          openapi: {
+            operationId: "resetPassword",
+            description: "Reset a password using a reset token",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  token: {type: "string", description: "The password reset token"},
+                  newPassword: {type: "string", description: "The new password to set"}
+                },
+                required: ["token", "newPassword"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Password reset successfully", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         token = body["token"] || fetch_value(ctx.query, "token")
         raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["INVALID_TOKEN"]) if token.to_s.empty?
@@ -86,7 +175,27 @@ module BetterAuth
     end
 
     def self.verify_password
-      Endpoint.new(path: "/verify-password", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/verify-password",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "verifyPassword",
+            description: "Verify the current user's password",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  password: {type: "string", description: "The password to verify"}
+                },
+                required: ["password"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Password verified", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         password = normalize_hash(ctx.body)["password"].to_s
         account = credential_account(ctx, session[:user]["id"])
@@ -180,5 +289,13 @@ module BetterAuth
 
       raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["INVALID_CALLBACK_URL"])
     end
+
+    def self.validate_redirect_url!(context, redirect_url)
+      validate_callback_url!(context, redirect_url)
+    rescue APIError => error
+      raise error unless error.message == BASE_ERROR_CODES["INVALID_CALLBACK_URL"]
+
+      raise APIError.new("FORBIDDEN", message: BASE_ERROR_CODES["INVALID_REDIRECT_URL"])
+    end
   end
 end