better_auth 0.8.0 → 0.11.0

data/lib/better_auth/plugins/two_factor.rb

@@ -4,6 +4,7 @@ require "base64"
 require "json"
 require "openssl"
 require "securerandom"
+require "time"
 require "uri"
 
 module BetterAuth
@@ -17,6 +18,7 @@ module BetterAuth
       "INVALID_BACKUP_CODE" => "Invalid backup code",
       "INVALID_CODE" => "Invalid code",
       "TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE" => "Too many attempts. Please request a new code.",
+      "ACCOUNT_TEMPORARILY_LOCKED" => "Too many failed verification attempts. Your account is temporarily locked. Please try again later.",
       "INVALID_TWO_FACTOR_COOKIE" => "Invalid two factor cookie"
     }.freeze
 
@@ -25,6 +27,9 @@ module BetterAuth
     TRUST_DEVICE_COOKIE_MAX_AGE = 30 * 24 * 60 * 60
     TWO_FACTOR_COOKIE_MAX_AGE = 10 * 60
     TWO_FACTOR_MODEL = "twoFactor"
+    DEFAULT_TWO_FACTOR_ALLOWED_ATTEMPTS = 5
+    DEFAULT_ACCOUNT_LOCKOUT_MAX_FAILED_ATTEMPTS = 10
+    DEFAULT_ACCOUNT_LOCKOUT_DURATION_SECONDS = 15 * 60
 
     module_function
 
@@ -33,6 +38,11 @@ module BetterAuth
         two_factor_table: "twoFactor",
         trust_device_max_age: TRUST_DEVICE_COOKIE_MAX_AGE,
         two_factor_cookie_max_age: TWO_FACTOR_COOKIE_MAX_AGE,
+        account_lockout: {
+          enabled: true,
+          max_failed_attempts: DEFAULT_ACCOUNT_LOCKOUT_MAX_FAILED_ATTEMPTS,
+          duration_seconds: DEFAULT_ACCOUNT_LOCKOUT_DURATION_SECONDS
+        },
         backup_code_options: {store_backup_codes: "encrypted"},
         otp_options: {},
         totp_options: {}
@@ -40,6 +50,11 @@ module BetterAuth
       config[:backup_code_options] = {store_backup_codes: "encrypted"}.merge(normalize_hash(config[:backup_code_options]))
       config[:otp_options] = normalize_hash(config[:otp_options])
       config[:totp_options] = normalize_hash(config[:totp_options])
+      config[:account_lockout] = {
+        enabled: true,
+        max_failed_attempts: DEFAULT_ACCOUNT_LOCKOUT_MAX_FAILED_ATTEMPTS,
+        duration_seconds: DEFAULT_ACCOUNT_LOCKOUT_DURATION_SECONDS
+      }.merge(normalize_hash(config[:account_lockout]))
       config[:backup_code_options][:allow_passwordless] = config[:allow_passwordless] unless config[:backup_code_options].key?(:allow_passwordless)
       config[:totp_options][:allow_passwordless] = config[:allow_passwordless] unless config[:totp_options].key?(:allow_passwordless)
 
@@ -169,8 +184,22 @@ module BetterAuth
           raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["TOTP_NOT_ENABLED"])
         end
 
-        secret = Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: record["secret"])
-        raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_CODE"]) unless two_factor_totp_valid?(secret, body[:code], options: config[:totp_options])
+        sign_in = data[:session][:session].nil?
+        two_factor_assert_not_locked!(ctx, config, record) if sign_in
+        attempt = sign_in ? data[:begin_attempt].call(DEFAULT_TWO_FACTOR_ALLOWED_ATTEMPTS) : nil
+        valid_code = begin
+          secret = Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: record["secret"])
+          two_factor_totp_valid?(secret, body[:code], options: config[:totp_options])
+        rescue
+          attempt&.fetch(:restore)&.call
+          raise
+        end
+        unless valid_code
+          attempt&.fetch(:record_failure)&.call
+          two_factor_record_failure!(ctx, config, record) if sign_in
+          raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_CODE"])
+        end
+        two_factor_reset_failures!(ctx, config, record) if sign_in
 
         if record["verified"] != true
           if !data[:session][:user]["twoFactorEnabled"] && data[:session][:session]
@@ -215,23 +244,34 @@ module BetterAuth
       Endpoint.new(path: "/two-factor/verify-otp", method: "POST", metadata: two_factor_openapi("verifyTwoFactorOTP", "Verify a two factor OTP", two_factor_verification_response_schema)) do |ctx|
         body = normalize_hash(ctx.body)
         data = two_factor_verification_context(ctx, config)
-        verification = ctx.context.internal_adapter.find_verification_value("2fa-otp-#{data[:key]}")
+        sign_in = data[:session][:session].nil?
+        record = nil
+        if sign_in
+          record = two_factor_record(ctx, config, data[:session][:user]["id"])
+          raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["TWO_FACTOR_NOT_ENABLED"]) unless record
+
+          two_factor_assert_not_locked!(ctx, config, record)
+        end
+        identifier = "2fa-otp-#{data[:key]}"
+        verification = ctx.context.internal_adapter.consume_verification_value(identifier)
         stored, counter = verification&.fetch("value", nil).to_s.split(":", 2)
-        if !verification || verification["expiresAt"] < Time.now
-          ctx.context.internal_adapter.delete_verification_value(verification["id"]) if verification
+        unless verification
           raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["OTP_HAS_EXPIRED"])
         end
 
         allowed = (config[:otp_options][:allowed_attempts] || 5).to_i
         if counter.to_i >= allowed
-          ctx.context.internal_adapter.delete_verification_value(verification["id"])
           raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE"])
         end
 
         unless two_factor_otp_matches?(ctx, stored, body[:code].to_s, config[:otp_options])
-          ctx.context.internal_adapter.update_verification_value(verification["id"], value: "#{stored}:#{counter.to_i + 1}")
+          rearmed = ctx.context.internal_adapter.create_verification_value(identifier: identifier, value: "#{stored}:#{counter.to_i + 1}", expiresAt: verification["expiresAt"])
+          raise Error, "Failed to re-arm two-factor OTP attempt counter" unless rearmed
+
+          two_factor_record_failure!(ctx, config, record) if sign_in
           raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_CODE"])
         end
+        two_factor_reset_failures!(ctx, config, record) if sign_in
 
         if !data[:session][:user]["twoFactorEnabled"] && data[:session][:session]
           updated_user = ctx.context.internal_adapter.update_user(data[:session][:user]["id"], twoFactorEnabled: true)
@@ -252,13 +292,28 @@ module BetterAuth
         record = two_factor_record(ctx, config, data[:session][:user]["id"])
         raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["BACKUP_CODES_NOT_ENABLED"]) unless record
 
-        codes = two_factor_read_backup_codes(ctx.context.secret_config, record["backupCodes"], config[:backup_code_options])
+        sign_in = data[:session][:session].nil?
+        two_factor_assert_not_locked!(ctx, config, record) if sign_in
+        attempt = sign_in ? data[:begin_attempt].call(DEFAULT_TWO_FACTOR_ALLOWED_ATTEMPTS) : nil
+        codes = begin
+          two_factor_read_backup_codes(ctx.context.secret_config, record["backupCodes"], config[:backup_code_options])
+        rescue
+          attempt&.fetch(:restore)&.call
+          raise
+        end
         unless codes.include?(body[:code].to_s)
+          attempt&.fetch(:record_failure)&.call
+          two_factor_record_failure!(ctx, config, record) if sign_in
           raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_BACKUP_CODE"])
         end
 
         remaining = codes.reject { |code| code == body[:code].to_s }
-        stored = two_factor_store_backup_codes(ctx.context.secret_config, remaining, config[:backup_code_options])
+        stored = begin
+          two_factor_store_backup_codes(ctx.context.secret_config, remaining, config[:backup_code_options])
+        rescue
+          attempt&.fetch(:restore)&.call
+          raise
+        end
         updated = ctx.context.adapter.update(
           model: TWO_FACTOR_MODEL,
           where: [{field: "id", value: record["id"]}, {field: "backupCodes", value: record["backupCodes"]}],
@@ -266,6 +321,7 @@ module BetterAuth
         )
         raise APIError.new("CONFLICT", message: "Failed to verify backup code. Please try again.") unless updated
 
+        two_factor_reset_failures!(ctx, config, record) if sign_in
         body[:disable_session] ? ctx.json({token: data[:session][:session]&.fetch("token", nil), user: Schema.parse_output(ctx.context.options, "user", data[:session][:user])}) : data[:valid].call
       end
     end
@@ -300,6 +356,7 @@ module BetterAuth
         openapi: {
           operationId: operation_id,
           description: description,
+          requestBody: two_factor_request_body(operation_id),
           responses: {
             "200" => OpenAPI.json_response("Success", response_schema)
           }
@@ -307,6 +364,26 @@ module BetterAuth
       }
     end
 
+    def two_factor_request_body(operation_id)
+      schema = case operation_id
+      when "enableTwoFactor"
+        OpenAPI.object_schema({password: {type: "string"}, issuer: {type: "string"}})
+      when "disableTwoFactor", "getTOTPURI", "generateBackupCodes"
+        OpenAPI.object_schema({password: {type: "string"}})
+      when "generateTOTP"
+        OpenAPI.object_schema({secret: {type: "string"}}, required: ["secret"])
+      when "verifyTOTP", "verifyTwoFactorOTP"
+        OpenAPI.object_schema({code: {type: "string"}, trustDevice: {type: "boolean"}}, required: ["code"])
+      when "verifyBackupCode"
+        OpenAPI.object_schema({code: {type: "string"}, disableSession: {type: "boolean"}, trustDevice: {type: "boolean"}}, required: ["code"])
+      when "sendTwoFactorOTP"
+        OpenAPI.empty_request_body.dig(:content, "application/json", :schema)
+      else
+        {type: "object", properties: {}}
+      end
+      OpenAPI.json_request_body(schema)
+    end
+
     def two_factor_enable_response_schema
       OpenAPI.object_schema(
         {
@@ -350,7 +427,9 @@ module BetterAuth
             secret: {type: "string", required: true, returned: false, index: true},
             backupCodes: {type: "string", required: true, returned: false},
             userId: {type: "string", required: true, returned: false, index: true, references: {model: "user", field: "id"}},
-            verified: {type: "boolean", required: false, default_value: true, input: false}
+            verified: {type: "boolean", required: false, default_value: true, input: false},
+            failedVerificationCount: {type: "number", required: false, default_value: 0, input: false, returned: false},
+            lockedUntil: {type: "date", required: false, input: false, returned: false}
           }
         }
       }
@@ -370,10 +449,16 @@ module BetterAuth
       ctx.context.internal_adapter.delete_session(data[:session]["token"])
       cookie = ctx.context.create_auth_cookie(TWO_FACTOR_COOKIE_NAME, max_age: config[:two_factor_cookie_max_age])
       identifier = "2fa-#{Crypto.random_string(20)}"
+      expires_at = Time.now + config[:two_factor_cookie_max_age].to_i
       ctx.context.internal_adapter.create_verification_value(
         identifier: identifier,
         value: data[:user]["id"],
-        expiresAt: Time.now + config[:two_factor_cookie_max_age].to_i
+        expiresAt: expires_at
+      )
+      ctx.context.internal_adapter.create_verification_value(
+        identifier: "2fa-attempts-#{identifier}",
+        value: "0",
+        expiresAt: expires_at
       )
       ctx.set_signed_cookie(cookie.name, identifier, ctx.context.secret, cookie.attributes)
       ctx.json({twoFactorRedirect: true, twoFactorMethods: two_factor_methods(ctx, config, data[:user]["id"])})
@@ -383,7 +468,13 @@ module BetterAuth
       session = Routes.current_session(ctx, allow_nil: true)
       if session
         key = "#{session[:user]["id"]}!#{session[:session]["id"]}"
-        return {session: session, key: key, valid: -> { ctx.json({token: session[:session]["token"], user: Schema.parse_output(ctx.context.options, "user", session[:user])}) }}
+        no_op_attempt = ->(_allowed_attempts) { {record_failure: -> {}, restore: -> {}} }
+        return {
+          session: session,
+          key: key,
+          valid: -> { ctx.json({token: session[:session]["token"], user: Schema.parse_output(ctx.context.options, "user", session[:user])}) },
+          begin_attempt: no_op_attempt
+        }
       end
 
       cookie = ctx.context.create_auth_cookie(TWO_FACTOR_COOKIE_NAME)
@@ -397,11 +488,15 @@ module BetterAuth
       raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_TWO_FACTOR_COOKIE"]) unless user
 
       valid = lambda do
+        consumed = ctx.context.internal_adapter.consume_verification_value(identifier)
+        unless consumed && consumed["value"] == user["id"]
+          raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_TWO_FACTOR_COOKIE"])
+        end
+
         dont_remember_me = Cookies.dont_remember?(ctx)
         new_session = ctx.context.internal_adapter.create_session(user["id"], dont_remember_me)
         raise APIError.new("INTERNAL_SERVER_ERROR", message: "failed to create session") unless new_session
 
-        ctx.context.internal_adapter.delete_verification_value(verification["id"])
         Cookies.set_session_cookie(ctx, {session: new_session, user: user}, dont_remember_me)
         Cookies.expire_cookie(ctx, cookie)
         if normalize_hash(ctx.body)[:trust_device]
@@ -411,7 +506,41 @@ module BetterAuth
         ctx.json({token: new_session["token"], user: Schema.parse_output(ctx.context.options, "user", user)})
       end
 
-      {session: {session: nil, user: user}, key: identifier, valid: valid}
+      begin_attempt = lambda do |allowed_attempts|
+        attempts_identifier = "2fa-attempts-#{identifier}"
+        consumed = begin
+          ctx.context.internal_adapter.consume_verification_value(attempts_identifier)
+        rescue
+          nil
+        end
+        raise APIError.new("UNAUTHORIZED", message: TWO_FACTOR_ERROR_CODES["INVALID_TWO_FACTOR_COOKIE"]) unless consumed
+
+        raw_count = consumed["value"].to_s
+        attempts = raw_count.match?(/\A\d+\z/) ? raw_count.to_i : allowed_attempts
+        if attempts >= allowed_attempts
+          begin
+            ctx.context.internal_adapter.consume_verification_value(identifier)
+          rescue
+            nil
+          end
+          Cookies.expire_cookie(ctx, cookie)
+          raise APIError.new("BAD_REQUEST", message: TWO_FACTOR_ERROR_CODES["TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE"])
+        end
+
+        rearm = lambda do |count|
+          created = ctx.context.internal_adapter.create_verification_value(
+            identifier: attempts_identifier,
+            value: count.to_s,
+            expiresAt: verification["expiresAt"]
+          )
+          raise Error, "Failed to re-arm two-factor attempt counter" unless created
+
+          created
+        end
+        {record_failure: -> { rearm.call(attempts + 1) }, restore: -> { rearm.call(attempts) }}
+      end
+
+      {session: {session: nil, user: user}, key: identifier, valid: valid, begin_attempt: begin_attempt}
     end
 
     def two_factor_set_trusted_device(ctx, config, user_id)
@@ -430,9 +559,10 @@ module BetterAuth
 
       token, identifier = value.split("!", 2)
       expected = Crypto.hmac_signature("#{user_id}!#{identifier}", ctx.context.secret, encoding: :base64url)
-      verification = identifier && ctx.context.internal_adapter.find_verification_value(identifier)
-      if token && identifier && Crypto.constant_time_compare(token, expected) && verification && verification["value"] == user_id && verification["expiresAt"] > Time.now
-        ctx.context.internal_adapter.delete_verification_value(verification["id"])
+      verification = if token && identifier && Crypto.constant_time_compare(token, expected)
+        ctx.context.internal_adapter.consume_verification_value(identifier)
+      end
+      if verification && verification["value"] == user_id
         two_factor_set_trusted_device(ctx, config, user_id)
         true
       else
@@ -445,6 +575,64 @@ module BetterAuth
       ctx.context.adapter.find_one(model: TWO_FACTOR_MODEL, where: [{field: "userId", value: user_id}])
     end
 
+    def two_factor_assert_not_locked!(ctx, config, record)
+      lockout = config[:account_lockout]
+      return unless lockout && lockout[:enabled] != false && record["lockedUntil"]
+
+      locked_until = two_factor_lock_time(record["lockedUntil"])
+      if locked_until > Time.now
+        raise APIError.new("TOO_MANY_REQUESTS", message: TWO_FACTOR_ERROR_CODES["ACCOUNT_TEMPORARILY_LOCKED"])
+      end
+
+      cleared = ctx.context.adapter.increment_one(
+        model: TWO_FACTOR_MODEL,
+        where: [
+          {field: "id", value: record["id"]},
+          {field: "lockedUntil", operator: "lte", value: Time.now}
+        ],
+        increment: {},
+        set: {failedVerificationCount: 0, lockedUntil: nil}
+      )
+      raise Error, "Failed to clear expired two-factor account lock" unless cleared
+    end
+
+    def two_factor_record_failure!(ctx, config, record)
+      lockout = config[:account_lockout]
+      return unless lockout && lockout[:enabled] != false
+
+      updated = ctx.context.adapter.increment_one(
+        model: TWO_FACTOR_MODEL,
+        where: [{field: "id", value: record["id"]}],
+        increment: {failedVerificationCount: 1},
+        allow_server_managed: true
+      )
+      raise Error, "Failed to record two-factor verification failure" unless updated
+      return if updated["failedVerificationCount"].to_i < lockout[:max_failed_attempts].to_i
+
+      locked = ctx.context.adapter.update(
+        model: TWO_FACTOR_MODEL,
+        where: [{field: "id", value: record["id"]}],
+        update: {lockedUntil: Time.now + lockout[:duration_seconds].to_i}
+      )
+      raise Error, "Failed to lock two-factor account" unless locked
+    end
+
+    def two_factor_reset_failures!(ctx, config, record)
+      lockout = config[:account_lockout]
+      return unless lockout && lockout[:enabled] != false
+
+      reset = ctx.context.adapter.update(
+        model: TWO_FACTOR_MODEL,
+        where: [{field: "id", value: record["id"]}],
+        update: {failedVerificationCount: 0, lockedUntil: nil}
+      )
+      raise Error, "Failed to reset two-factor verification failures" unless reset
+    end
+
+    def two_factor_lock_time(value)
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+
     def two_factor_methods(ctx, config, user_id)
       methods = []
       unless config[:totp_options][:disable]
@@ -536,8 +724,6 @@ module BetterAuth
         stored
       end
       JSON.parse(data.to_s)
-    rescue JSON::ParserError
-      []
     end
 
     def two_factor_random_digits(length)

data/lib/better_auth/plugins/username.rb

@@ -73,10 +73,12 @@ module BetterAuth
                 "Signed in",
                 OpenAPI.object_schema(
                   {
+                    redirect: {type: "boolean"},
                     token: {type: "string"},
+                    url: {type: ["string", "null"]},
                     user: {type: "object", "$ref": "#/components/schemas/User"}
                   },
-                  required: ["token", "user"]
+                  required: ["redirect", "token", "user"]
                 )
               )
             }
@@ -88,17 +90,18 @@ module BetterAuth
         password = body[:password].to_s
         callback_url = body[:callback_url] || body[:callbackURL]
         remember_me = body.key?(:remember_me) ? body[:remember_me] : body[:rememberMe]
+        Routes.preflight_sign_in_token_link!(ctx)
 
         if raw_username.empty? || password.empty?
           raise APIError.new("UNAUTHORIZED", message: USERNAME_ERROR_CODES["INVALID_USERNAME_OR_PASSWORD"])
         end
 
-        username = username_for_validation(raw_username, config)
+        username = username_for_sign_in_validation(raw_username, config)
         validate_username!(username, config, status: "UNPROCESSABLE_ENTITY")
 
         user = ctx.context.adapter.find_one(
           model: "user",
-          where: [{field: "username", value: normalize_username(username, config)}]
+          where: [{field: "username", value: normalize_username(raw_username, config)}]
         )
         unless user
           Routes.hash_password(ctx, password)
@@ -134,8 +137,11 @@ module BetterAuth
         raise APIError.new("INTERNAL_SERVER_ERROR", message: BASE_ERROR_CODES["FAILED_TO_CREATE_SESSION"]) unless session
 
         Cookies.set_session_cookie(ctx, {session: session, user: user}, dont_remember_me)
+        ctx.set_header("location", callback_url) if callback_url
         ctx.json({
+          redirect: !callback_url.nil?,
           token: session["token"],
+          url: callback_url,
           user: Schema.parse_output(ctx.context.options, "user", user)
         })
       end
@@ -207,12 +213,36 @@ module BetterAuth
     end
 
     def username_database_hooks(config)
-      before_hook = lambda do |user, _context|
+      before_hook = lambda do |user, endpoint_context|
         data = user.dup
-        if data["username"].is_a?(String) && !data["username"].empty?
-          data["username"] = normalize_username(data["username"], config)
+        raw_username = data["username"]
+        raw_display_username = data["displayUsername"]
+        if raw_username.is_a?(String) && !raw_username.empty?
+          unless endpoint_context && username_mutation_path?(endpoint_context.path)
+            username = username_for_validation(raw_username, config)
+            validate_username!(username, config, status: "BAD_REQUEST")
+            adapter = endpoint_context&.context&.adapter
+            if adapter
+              existing = adapter.find_one(model: "user", where: [{field: "username", value: normalize_username(username, config)}])
+              current_user_id = endpoint_context&.context&.current_session&.dig(:user, "id")
+              if existing && existing["id"] != current_user_id
+                raise APIError.new("BAD_REQUEST", code: "USERNAME_IS_ALREADY_TAKEN", message: USERNAME_ERROR_CODES["USERNAME_IS_ALREADY_TAKEN"])
+              end
+            end
+          end
+          data["username"] = normalize_username(raw_username, config)
+          data["displayUsername"] = raw_username unless raw_display_username.is_a?(String) && !raw_display_username.empty?
         end
         if data["displayUsername"].is_a?(String) && !data["displayUsername"].empty?
+          display_username = if validation_order(config, :display_username) == "post-normalization"
+            normalize_display_username(data["displayUsername"], config)
+          else
+            data["displayUsername"]
+          end
+          validator = config[:display_username_validator]
+          unless !validator.respond_to?(:call) || validator.call(display_username)
+            raise APIError.new("BAD_REQUEST", code: "INVALID_DISPLAY_USERNAME", message: USERNAME_ERROR_CODES["INVALID_DISPLAY_USERNAME"])
+          end
           data["displayUsername"] = normalize_display_username(data["displayUsername"], config)
         end
         {data: data}
@@ -229,6 +259,15 @@ module BetterAuth
     def validate_username_mutation!(ctx, config)
       body = normalize_hash(ctx.body)
       raw_username = body.key?(:username) ? body[:username] : nil
+      if raw_username.nil? && present?(body[:display_username])
+        begin
+          validate_username!(username_for_validation(body[:display_username], config), config, status: "BAD_REQUEST")
+          body[:username] = body[:display_username]
+          raw_username = body[:username]
+        rescue APIError
+          # A display-only value that cannot be a username remains display-only.
+        end
+      end
       username = if raw_username.is_a?(String) && validation_order(config, :username) == "post-normalization"
         normalize_username(raw_username, config)
       else
@@ -242,11 +281,11 @@ module BetterAuth
         same_user = existing && current && existing["id"] == current[:session]["userId"]
 
         if existing && ctx.path == "/sign-up/email"
-          raise APIError.new("UNPROCESSABLE_ENTITY", message: USERNAME_ERROR_CODES["USERNAME_IS_ALREADY_TAKEN"])
+          raise APIError.new("UNPROCESSABLE_ENTITY", code: "USERNAME_IS_ALREADY_TAKEN", message: USERNAME_ERROR_CODES["USERNAME_IS_ALREADY_TAKEN"])
         end
 
         if existing && ctx.path == "/update-user" && !same_user
-          raise APIError.new("BAD_REQUEST", message: USERNAME_ERROR_CODES["USERNAME_IS_ALREADY_TAKEN"])
+          raise APIError.new("BAD_REQUEST", code: "USERNAME_IS_ALREADY_TAKEN", message: USERNAME_ERROR_CODES["USERNAME_IS_ALREADY_TAKEN"])
         end
       end
 
@@ -260,35 +299,39 @@ module BetterAuth
       if display_username.is_a?(String)
         validator = config[:display_username_validator]
         unless !validator.respond_to?(:call) || validator.call(display_username)
-          raise APIError.new("BAD_REQUEST", message: USERNAME_ERROR_CODES["INVALID_DISPLAY_USERNAME"])
+          raise APIError.new("BAD_REQUEST", code: "INVALID_DISPLAY_USERNAME", message: USERNAME_ERROR_CODES["INVALID_DISPLAY_USERNAME"])
         end
       end
+      ctx.body = body
       nil
     end
 
     def mirror_username_fields!(ctx)
       body = normalize_hash(ctx.body)
       body[:display_username] = body[:username] if present?(body[:username]) && !present?(body[:display_username])
-      body[:username] = body[:display_username] if present?(body[:display_username]) && !present?(body[:username])
       ctx.body = body
       nil
     end
 
     def validate_username!(username, config, status:)
       if username.length < min_username_length(config)
-        raise APIError.new(status, message: USERNAME_ERROR_CODES["USERNAME_TOO_SHORT"])
+        raise APIError.new(status, code: "USERNAME_TOO_SHORT", message: USERNAME_ERROR_CODES["USERNAME_TOO_SHORT"])
       end
 
       if username.length > max_username_length(config)
-        raise APIError.new(status, message: USERNAME_ERROR_CODES["USERNAME_TOO_LONG"])
+        raise APIError.new(status, code: "USERNAME_TOO_LONG", message: USERNAME_ERROR_CODES["USERNAME_TOO_LONG"])
       end
 
       validator = config[:username_validator]
       valid = validator.respond_to?(:call) ? validator.call(username) : default_username_valid?(username)
-      raise APIError.new(status, message: USERNAME_ERROR_CODES["INVALID_USERNAME"]) unless valid
+      raise APIError.new(status, code: "INVALID_USERNAME", message: USERNAME_ERROR_CODES["INVALID_USERNAME"]) unless valid
     end
 
     def username_for_validation(username, config)
+      (validation_order(config, :username) == "post-normalization") ? normalize_username(username, config) : username
+    end
+
+    def username_for_sign_in_validation(username, config)
       (validation_order(config, :username) == "pre-normalization") ? normalize_username(username, config) : username
     end
 

data/lib/better_auth/plugins.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "plugin_loader"
+
 module BetterAuth
   module Plugins
     module_function
@@ -39,8 +41,63 @@ module BetterAuth
       data[key] || data[key.to_s] || data[Schema.storage_key(key)] || data[Schema.storage_key(key).to_sym] || data[normalize_key(key)]
     end
 
+    def deep_merge_hashes(base, override)
+      base.merge(override) do |_key, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge_hashes(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
+
     def cookie_header_from_set_cookie(set_cookie)
       set_cookie.to_s.lines.map { |line| line.split(";").first }.join("; ")
     end
+
+    PLUGIN_FACTORY_LOADERS = {
+      create_access_control: :access,
+      createAccessControl: :access
+    }.freeze
+
+    REMOVED_PLUGIN_FACTORIES = {
+      oidc_provider: "BetterAuth::Plugins.oauth_provider (require \"better_auth/oauth_provider\")",
+      mcp: "BetterAuth::Plugins.oauth_provider (require \"better_auth/oauth_provider\")"
+    }.freeze
+
+    def method_missing(name, ...)
+      if (replacement = REMOVED_PLUGIN_FACTORIES[name.to_sym])
+        raise ArgumentError, "BetterAuth::Plugins.#{name} was removed. Use #{replacement} instead."
+      end
+
+      if (loader = plugin_loader_for_method(name))
+        load_plugin!(loader)
+        return public_send(name, ...) if respond_to?(name, true)
+
+        raise NoMethodError, "plugin file for #{loader} did not define BetterAuth::Plugins.#{name}"
+      end
+
+      if (loader = PLUGIN_FACTORY_LOADERS[name.to_sym])
+        load_plugin!(loader)
+        return public_send(name, ...) if respond_to?(name, true)
+
+        raise NoMethodError, "plugin file for #{loader} did not define BetterAuth::Plugins.#{name}"
+      end
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      return false if REMOVED_PLUGIN_FACTORIES.key?(name.to_sym)
+
+      PLUGIN_FACTORY_LOADERS.key?(name.to_sym) || !plugin_loader_for_method(name).nil? || super
+    end
+
+    def const_missing(name)
+      load_plugin_for_constant!(name)
+      return const_get(name) if const_defined?(name, false)
+
+      super
+    end
   end
 end