better_auth 0.3.0 → 0.5.0

data/lib/better_auth/plugins/username.rb

@@ -53,7 +53,34 @@ module BetterAuth
           allowed_media_types: [
             "application/x-www-form-urlencoded",
             "application/json"
-          ]
+          ],
+          openapi: {
+            operationId: "signInUsername",
+            description: "Sign in with username and password",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  username: {type: "string"},
+                  password: {type: "string"},
+                  callbackURL: {type: ["string", "null"]},
+                  rememberMe: {type: ["boolean", "null"]}
+                },
+                required: ["username", "password"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Signed in",
+                OpenAPI.object_schema(
+                  {
+                    token: {type: "string"},
+                    user: {type: "object", "$ref": "#/components/schemas/User"}
+                  },
+                  required: ["token", "user"]
+                )
+              )
+            }
+          }
         }
       ) do |ctx|
         body = normalize_hash(ctx.body)
@@ -115,7 +142,35 @@ module BetterAuth
     end
 
     def is_username_available_endpoint(config)
-      Endpoint.new(path: "/is-username-available", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/is-username-available",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "isUsernameAvailable",
+            description: "Check whether a username is available",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  username: {type: "string"}
+                },
+                required: ["username"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Username availability",
+                OpenAPI.object_schema(
+                  {
+                    available: {type: "boolean"}
+                  },
+                  required: ["available"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         username = body[:username].to_s
         raise APIError.new("UNPROCESSABLE_ENTITY", message: USERNAME_ERROR_CODES["INVALID_USERNAME"]) if username.empty?

data/lib/better_auth/rate_limiter.rb

@@ -4,6 +4,9 @@ require "json"
 
 module BetterAuth
   class RateLimiter
+    MISSING_CLIENT_IP_WARNING = "Rate limiting skipped: could not determine client IP address. " \
+      "Ensure your runtime forwards a trusted client IP header and configure `advanced.ipAddress.ipAddressHeaders` if needed."
+
     class MemoryStore
       def initialize
         @entries = {}
@@ -36,6 +39,7 @@ module BetterAuth
 
     def initialize
       @memory_store = MemoryStore.new
+      @warned_missing_client_ip = false
     end
 
     def call(request, context, path)
@@ -43,6 +47,7 @@ module BetterAuth
       return unless config[:enabled]
 
       ip = client_ip(request, context.options)
+      warn_missing_client_ip(context) unless ip
       return unless ip
 
       rule = rate_limit_rule(request, context, config, path)
@@ -137,6 +142,7 @@ module BetterAuth
 
     def storage_for(context, config)
       return [:custom, config[:custom_storage]] if config[:custom_storage]
+      return [:database, context.internal_adapter.adapter] if config[:storage] == "database"
 
       if config[:storage] == "secondary-storage" && context.options.secondary_storage
         return [:secondary, context.options.secondary_storage]
@@ -146,6 +152,8 @@ module BetterAuth
     end
 
     def read_storage((type, storage), key)
+      return read_database_storage(storage, key) if type == :database
+
       data = storage.get(key)
       data = JSON.parse(data) if type == :secondary && data.is_a?(String)
       normalize_rate_limit_data(symbolize_keys(data))
@@ -154,12 +162,29 @@ module BetterAuth
     end
 
     def write_storage((type, storage), key, data, ttl:, update:)
+      return write_database_storage(storage, key, data) if type == :database
+
       value = (type == :secondary) ? JSON.generate(secondary_storage_data(data)) : data
       return call_secondary_storage_set(storage, key, value, ttl: ttl, update: update) if type == :secondary
 
       call_storage_set(storage, key, value, ttl: ttl, update: update)
     end
 
+    def read_database_storage(adapter, key)
+      data = adapter.find_one(model: "rateLimit", where: [{field: "key", value: key}])
+      normalize_rate_limit_data(symbolize_keys(data))
+    end
+
+    def write_database_storage(adapter, key, data)
+      value = secondary_storage_data(data)
+      existing = adapter.find_one(model: "rateLimit", where: [{field: "key", value: key}])
+      if existing
+        adapter.update(model: "rateLimit", where: [{field: "key", value: key}], update: value)
+      else
+        adapter.create(model: "rateLimit", data: value)
+      end
+    end
+
     def secondary_storage_data(data)
       {
         key: data[:key],
@@ -213,6 +238,19 @@ module BetterAuth
       RequestIP.client_ip(request, options)
     end
 
+    def warn_missing_client_ip(context)
+      return if @warned_missing_client_ip
+      return if context.options.advanced.dig(:ip_address, :disable_ip_tracking)
+
+      @warned_missing_client_ip = true
+      logger = context.logger
+      if logger.respond_to?(:call)
+        logger.call(:warn, MISSING_CLIENT_IP_WARNING)
+      elsif logger.respond_to?(:warn)
+        logger.warn(MISSING_CLIENT_IP_WARNING)
+      end
+    end
+
     def matching_plugin_rule(context, path)
       context.options.plugins
         .flat_map { |plugin| Array(plugin[:rate_limit]) }

data/lib/better_auth/request_state.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module RequestState
+    THREAD_KEY = :better_auth_request_state_stack
+
+    State = Struct.new(:ref, :initializer) do
+      def get
+        store = RequestState.current_store
+        store[ref] = initializer.call unless store.key?(ref)
+        store[ref]
+      end
+
+      def set(value)
+        RequestState.current_store[ref] = value
+      end
+    end
+
+    module_function
+
+    def run(store = {}, &block)
+      stack.push(store)
+      block.call
+    ensure
+      stack.pop
+    end
+
+    def present?
+      !stack.empty?
+    end
+
+    def current_store
+      stack.last || raise("No request state found. Please make sure you are calling this function within a `run` callback.")
+    end
+
+    def define(&initializer)
+      State.new(Object.new.freeze, initializer || -> {})
+    end
+
+    def stack
+      Thread.current[THREAD_KEY] ||= []
+    end
+  end
+end

data/lib/better_auth/response.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BetterAuth
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers
+      @body = body
+    end
+
+    def self.from_rack(tuple)
+      status, headers, body = tuple
+      new(status: status, headers: headers, body: body)
+    end
+
+    def to_a
+      [status, headers, body]
+    end
+
+    alias_method :to_ary, :to_a
+
+    def each(&block)
+      to_a.each(&block)
+    end
+
+    def [](index)
+      to_a[index]
+    end
+
+    def first
+      status
+    end
+
+    def json(**options)
+      JSON.parse(body.join, **options)
+    end
+  end
+end

data/lib/better_auth/router.rb

@@ -88,6 +88,8 @@ module BetterAuth
       error_response(error)
     rescue JSON::ParserError
       error_response(APIError.new("BAD_REQUEST", message: "Invalid JSON body"))
+    ensure
+      context.clear_runtime! if context.respond_to?(:clear_runtime!)
     end
 
     def self.conflicting_methods(entries)
@@ -360,7 +362,11 @@ module BetterAuth
     end
 
     def server_only?(endpoint)
-      endpoint.metadata[:server_only] || endpoint.metadata[:SERVER_ONLY] || endpoint.metadata["SERVER_ONLY"]
+      endpoint.metadata[:server_only] ||
+        endpoint.metadata[:SERVER_ONLY] ||
+        endpoint.metadata["SERVER_ONLY"] ||
+        endpoint.metadata[:scope].to_s == "server" ||
+        endpoint.metadata["scope"].to_s == "server"
     end
 
     def error_response(error, headers: {})

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,16 +190,21 @@ 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"],
+          refreshToken: values["refreshToken"] || refresh_token,
           accessTokenExpiresAt: values["accessTokenExpiresAt"],
-          refreshTokenExpiresAt: values["refreshTokenExpiresAt"],
-          scope: Array(values["scopes"]).join(","),
+          refreshTokenExpiresAt: values["refreshTokenExpiresAt"] || account["refreshTokenExpiresAt"],
+          scope: values["scope"] || account["scope"],
           idToken: values["idToken"] || account["idToken"],
           providerId: account["providerId"],
           accountId: account["accountId"]
@@ -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
 
@@ -167,7 +333,10 @@ module BetterAuth
     def self.update_account_tokens(ctx, account, tokens)
       return nil if account["id"].to_s.empty?
 
-      ctx.context.internal_adapter.update_account(account["id"], token_hash_for_storage(ctx, tokens))
+      data = account_token_update_hash(ctx, tokens)
+      return nil if data.empty?
+
+      ctx.context.internal_adapter.update_account(account["id"], data)
     end
 
     def self.token_hash(tokens)
@@ -183,18 +352,27 @@ module BetterAuth
       data
     end
 
+    def self.account_token_update_hash(ctx, tokens)
+      account_storage_fields(token_hash_for_storage(ctx, tokens))
+    end
+
+    def self.account_storage_fields(data)
+      allowed = %w[accessToken refreshToken idToken accessTokenExpiresAt refreshTokenExpiresAt scope]
+      token_hash(data).select { |key, value| allowed.include?(key) && !value.nil? }
+    end
+
     def self.oauth_token_for_storage(ctx, token)
       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)