better_auth 0.3.0 → 0.5.0

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,12 +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_redirect_url!(ctx.context, redirect_to)
         found = ctx.context.internal_adapter.find_user_by_email(email, include_accounts: true)
         unless found
           SecureRandom.hex(12)
@@ -29,18 +63,48 @@ module BetterAuth
           expiresAt: Time.now + expires_in.to_i
         )
 
-        redirect_to = body["redirectTo"] || body["redirect_to"]
         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}")
 
@@ -53,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?
@@ -85,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"])
@@ -179,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

data/lib/better_auth/routes/session.rb

@@ -3,11 +3,34 @@
 module BetterAuth
   module Routes
     def self.get_session
-      Endpoint.new(path: "/get-session", method: "GET") do |ctx|
-        session = current_session(ctx, allow_nil: true)
+      Endpoint.new(
+        path: "/get-session",
+        method: ["GET", "POST"],
+        metadata: {
+          openapi: {
+            operationId: "getSession",
+            description: "Get the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Current session or null", OpenAPI.session_response_schema_pair.merge(nullable: true))
+            }
+          }
+        }
+      ) do |ctx|
+        defer_refresh = ctx.context.session_config[:defer_session_refresh]
+        if ctx.method == "POST" && !defer_refresh
+          raise APIError.new(
+            "METHOD_NOT_ALLOWED",
+            code: "METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED",
+            message: BASE_ERROR_CODES["METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED"]
+          )
+        end
+
+        session = current_session(ctx, allow_nil: true, disable_refresh: defer_refresh && ctx.method == "GET")
         next ctx.json(nil) unless session
 
-        ctx.json(parsed_session_response(ctx, session))
+        response = parsed_session_response(ctx, session)
+        response[:needsRefresh] = session_needs_refresh?(ctx, session[:session]) if defer_refresh && ctx.method == "GET"
+        ctx.json(response)
       rescue APIError
         raise
       rescue => error
@@ -17,7 +40,22 @@ module BetterAuth
     end
 
     def self.list_sessions
-      Endpoint.new(path: "/list-sessions", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/list-sessions",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "listSessions",
+            description: "List active sessions for the current user",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Active sessions",
+                {type: "array", items: {type: "object", "$ref": "#/components/schemas/Session"}}
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx)
         sessions = ctx.context.internal_adapter.list_sessions(session[:user]["id"])
         active = sessions
@@ -29,8 +67,22 @@ module BetterAuth
     end
 
     def self.update_session
-      Endpoint.new(path: "/update-session", method: "POST") do |ctx|
-        session = current_session(ctx, sensitive: true)
+      Endpoint.new(
+        path: "/update-session",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "updateSession",
+            description: "Update the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Updated session", OpenAPI.session_response_schema_pair)
+            }
+          }
+        }
+      ) do |ctx|
+        session = current_session(ctx)
+        raise APIError.new("BAD_REQUEST", code: "BODY_MUST_BE_AN_OBJECT", message: BASE_ERROR_CODES["BODY_MUST_BE_AN_OBJECT"]) unless ctx.body.is_a?(Hash)
+
         body = Routes.parse_declared_input(ctx, "session", ctx.body, allowed_base: [])
         raise APIError.new("BAD_REQUEST", message: "No fields to update") if body.empty?
 
@@ -38,12 +90,32 @@ module BetterAuth
         updated = ctx.context.internal_adapter.update_session(session[:session]["token"], update)
         merged = session[:session].merge(updated || update)
         Cookies.set_session_cookie(ctx, {session: merged, user: session[:user]}, Cookies.dont_remember?(ctx))
-        ctx.json(parsed_session_response(ctx, {session: merged, user: session[:user]}))
+        ctx.json({session: Schema.parse_output(ctx.context.options, "session", merged)})
       end
     end
 
     def self.revoke_session
-      Endpoint.new(path: "/revoke-session", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-session",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeSession",
+            description: "Revoke a session by token",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  token: {type: "string", description: "The session token to revoke"}
+                },
+                required: ["token"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Session revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         body = normalize_hash(ctx.body)
         token = body["token"].to_s
@@ -58,7 +130,19 @@ module BetterAuth
     end
 
     def self.revoke_sessions
-      Endpoint.new(path: "/revoke-sessions", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-sessions",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeSessions",
+            description: "Revoke all sessions for the current user",
+            responses: {
+              "200" => OpenAPI.json_response("Sessions revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         ctx.context.internal_adapter.delete_sessions(session[:user]["id"])
         Cookies.delete_session_cookie(ctx)
@@ -67,7 +151,19 @@ module BetterAuth
     end
 
     def self.revoke_other_sessions
-      Endpoint.new(path: "/revoke-other-sessions", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-other-sessions",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeOtherSessions",
+            description: "Revoke all sessions except the current one",
+            responses: {
+              "200" => OpenAPI.json_response("Other sessions revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         current_token = session[:session]["token"]
         sessions = ctx.context.internal_adapter.list_sessions(session[:user]["id"])
@@ -81,11 +177,11 @@ module BetterAuth
       end
     end
 
-    def self.current_session(ctx, allow_nil: false, sensitive: false)
+    def self.current_session(ctx, allow_nil: false, sensitive: false, fresh: false, disable_refresh: false)
       data = Session.find_current(
         ctx,
         disable_cookie_cache: truthy_query?(ctx.query, "disableCookieCache"),
-        disable_refresh: truthy_query?(ctx.query, "disableRefresh"),
+        disable_refresh: disable_refresh || truthy_query?(ctx.query, "disableRefresh"),
         sensitive: sensitive
       )
       return nil if allow_nil && data.nil?
@@ -93,7 +189,7 @@ module BetterAuth
       raise APIError.new("UNAUTHORIZED") unless data
 
       session = stringify_keys(data[:session] || data["session"])
-      ensure_fresh_session!(ctx, session) if sensitive
+      ensure_fresh_session!(ctx, session) if fresh
 
       {
         session: session,
@@ -101,6 +197,15 @@ module BetterAuth
       }
     end
 
+    def self.request_only_session(ctx)
+      session = current_session(ctx, allow_nil: true)
+      if !session && (ctx.request || !ctx.headers.empty?)
+        raise APIError.new("UNAUTHORIZED", code: "UNAUTHORIZED", message: "Unauthorized")
+      end
+
+      session
+    end
+
     def self.ensure_fresh_session!(ctx, session)
       fresh_age = ctx.context.session_config[:fresh_age].to_i
       return if fresh_age.zero?
@@ -111,6 +216,16 @@ module BetterAuth
       raise APIError.new("FORBIDDEN", code: "SESSION_NOT_FRESH", message: BASE_ERROR_CODES.fetch("SESSION_NOT_FRESH"))
     end
 
+    def self.session_needs_refresh?(ctx, session)
+      return false if truthy_query?(ctx.query, "disableRefresh") || ctx.context.session_config[:disable_session_refresh]
+
+      update_age = ctx.context.session_config[:update_age].to_i
+      return true if update_age.zero?
+
+      updated_at = normalize_time(session["updatedAt"])
+      updated_at && updated_at + update_age <= Time.now
+    end
+
     def self.normalize_time(value)
       return value if value.is_a?(Time)
       return nil if value.nil? || value.to_s.empty?

data/lib/better_auth/routes/sign_in.rb

@@ -8,17 +8,39 @@ module BetterAuth
       Endpoint.new(
         path: "/sign-in/email",
         method: "POST",
+        body_schema: request_body_schema(required_strings: %w[email password]),
         metadata: {
           allowed_media_types: [
             "application/x-www-form-urlencoded",
             "application/json"
-          ]
+          ],
+          openapi: {
+            operationId: "signInEmail",
+            description: "Sign in with email and password",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string", description: "Email of the user"},
+                  password: {type: "string", description: "Password of the user"},
+                  callbackURL: {type: ["string", "null"], description: "Callback URL to use as a redirect for email verification"},
+                  rememberMe: {type: ["boolean", "null"], default: true, description: "If this is false, the session will not be remembered. Default is `true`."}
+                },
+                required: ["email", "password"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Success - Returns either session details or redirect URL",
+                OpenAPI.session_response_schema(description: "Session response when idToken is provided", nullable_url: true)
+              )
+            }
+          }
         }
       ) do |ctx|
         options = ctx.context.options
         email_config = options.email_and_password
         if email_config[:enabled] != true
-          raise APIError.new("BAD_REQUEST", message: "Email and password is not enabled")
+          raise APIError.new("BAD_REQUEST", code: "EMAIL_PASSWORD_DISABLED", message: BASE_ERROR_CODES["EMAIL_PASSWORD_DISABLED"])
         end
 
         body = normalize_hash(ctx.body)
@@ -27,6 +49,8 @@ module BetterAuth
         callback_url = body["callbackURL"] || body["callbackUrl"] || body["callback_url"]
         remember_me = body.key?("rememberMe") ? body["rememberMe"] : body["remember_me"]
 
+        validate_auth_callback_url!(ctx.context, callback_url, "callbackURL")
+
         unless EMAIL_PATTERN.match?(email)
           raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["INVALID_EMAIL"])
         end

data/lib/better_auth/routes/sign_out.rb

@@ -3,7 +3,19 @@
 module BetterAuth
   module Routes
     def self.sign_out
-      Endpoint.new(path: "/sign-out", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/sign-out",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "signOut",
+            description: "Sign out the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Successfully signed out", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         token_cookie = ctx.context.auth_cookies[:session_token]
         token = ctx.get_signed_cookie(token_cookie.name, ctx.context.secret)
         ctx.context.internal_adapter.delete_session(token) if token