better_auth-api-key 0.2.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ac9db4e9d87c466c1bf8ecb7be2978d8ffc17fa168b5a626e82b29ddf36c4c2
-  data.tar.gz: 90f8b579bdf6fd84d7d0d2b0360f479c50800bc5ac724b0fdde6c721a8290e3a
+  metadata.gz: fcc6f211dc2f80b2524e48f5fff897caf734ee3316ba5620379820571d2f0729
+  data.tar.gz: 1f111ffa2b175c3ea04c356c1afbc18d361b9b02717c9dea3dd32954b4ac57dc
 SHA512:
-  metadata.gz: 970bf80895c95174c91e269560260f6b90281dcc5f3a1be4cd708bcdb53a12dd5d567874a3b046b86867b069000009238982bbd22b980edfa990ed7c68a04b6b
-  data.tar.gz: c52b6d7e9d2b98e77754e9105681bd1c1f8e619b1a0819ab93798a7eacc62cd10a40e11a32debe1a119578de868e76f3982dd366f745d4eb7abb60eab97a4332
+  metadata.gz: fa1c89732eaeba2c8d7d064664d9a34e23287744c534dc19d45254837bd7481b0271b536364e64835b4f750e14d95c3f118bd7ddc0947f02077cbb8d35675034
+  data.tar.gz: 8146aca0fd1ad983d0285eedcc707bcfff2336bac8b64c91141af93ca9e231d8d42b67899a405beef304785464ddedf8fdb06ad5e1dad7d74ac7bc754b5981f2

data/lib/better_auth/api_key/adapter.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module BetterAuth
+  module APIKey
+    module Adapter
+      HASH_STORAGE_PREFIX = "api-key:"
+      ID_STORAGE_PREFIX = "api-key:by-id:"
+      REFERENCE_STORAGE_PREFIX = "api-key:by-ref:"
+
+      module_function
+
+      def storage_key_by_hash(hashed_key)
+        "#{HASH_STORAGE_PREFIX}#{hashed_key}"
+      end
+
+      def storage_key_by_id(id)
+        "#{ID_STORAGE_PREFIX}#{id}"
+      end
+
+      def storage_key_by_reference(reference_id)
+        "#{REFERENCE_STORAGE_PREFIX}#{reference_id}"
+      end
+
+      def store(ctx, data, config)
+        record = nil
+        if config[:storage] == "database" || config[:fallback_to_database]
+          record = ctx.context.adapter.create(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, data: data)
+        end
+        record ||= data.transform_keys { |key| BetterAuth::Schema.storage_key(key) }.merge("id" => SecureRandom.hex(16))
+        set(ctx, record, config) if config[:storage] == "secondary-storage"
+        record
+      end
+
+      def find_by_hash(ctx, hashed, config)
+        if config[:storage] == "secondary-storage"
+          record = get(ctx, storage_key_by_hash(hashed), config) || get(ctx, "api-key:key:#{hashed}", config)
+          return record if record
+          return nil unless config[:fallback_to_database]
+        end
+        record = ctx.context.adapter.find_one(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "key", value: hashed}])
+        set(ctx, record, config) if record && config[:storage] == "secondary-storage" && config[:fallback_to_database]
+        record
+      end
+
+      def find_by_id(ctx, id, config)
+        if config[:storage] == "secondary-storage"
+          record = get(ctx, storage_key_by_id(id), config) || get(ctx, "api-key:id:#{id}", config)
+          return record if record
+          return nil unless config[:fallback_to_database]
+        end
+        record = ctx.context.adapter.find_one(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: id}])
+        set(ctx, record, config) if record && config[:storage] == "secondary-storage" && config[:fallback_to_database]
+        record
+      end
+
+      def list_for_reference(ctx, reference_id, config)
+        if config[:storage] == "secondary-storage"
+          begin
+            storage_instance = storage(config, ctx.context)
+            ids = JSON.parse((storage_instance&.get(storage_key_by_reference(reference_id)) || storage_instance&.get("api-key:user:#{reference_id}")).to_s)
+            records = ids.filter_map { |id| find_by_id(ctx, id, config) }
+            return records unless records.empty? && config[:fallback_to_database]
+          rescue JSON::ParserError, NoMethodError
+            return [] unless config[:fallback_to_database]
+          end
+        end
+        records = ctx.context.adapter.find_many(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "referenceId", value: reference_id}])
+        legacy = ctx.context.adapter.find_many(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "userId", value: reference_id}])
+        combined = (records + legacy).uniq { |record| record["id"] }
+        populate_reference(ctx, reference_id, combined, config) if config[:storage] == "secondary-storage" && config[:fallback_to_database]
+        combined
+      end
+
+      def update_record(ctx, record, update, config, defer: false)
+        performer = lambda do
+          updated = nil
+          if config[:storage] == "database" || config[:fallback_to_database]
+            updated = ctx.context.adapter.update(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}], update: update)
+          end
+          updated ||= record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
+          set(ctx, updated, config) if config[:storage] == "secondary-storage"
+          updated
+        end
+
+        if defer && config[:defer_updates] && BetterAuth::Plugins.api_key_background_tasks?(ctx)
+          scheduled = record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
+          ctx.context.run_in_background(performer)
+          scheduled
+        else
+          performer.call
+        end
+      end
+
+      def delete_record(ctx, record, config)
+        ctx.context.adapter.delete(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}]) if config[:storage] == "database" || config[:fallback_to_database]
+        delete(ctx, record, config) if config[:storage] == "secondary-storage"
+      end
+
+      def schedule_record_delete(ctx, record, config)
+        task = -> { delete_record(ctx, record, config) }
+        if config[:defer_updates] && BetterAuth::APIKey::Utils.background_tasks?(ctx)
+          ctx.context.run_in_background(task)
+        else
+          task.call
+        end
+      end
+
+      def migrate_legacy_metadata(ctx, record, config)
+        parsed = BetterAuth::APIKey::Utils.decode_json(record["metadata"])
+        return record unless parsed.is_a?(Hash)
+
+        encoded = BetterAuth::APIKey::Utils.encode_json(parsed)
+        return record.merge("metadata" => encoded) if record["metadata"] == encoded
+
+        updated = record.merge("metadata" => encoded)
+        if config[:storage] == "database" || config[:fallback_to_database]
+          ctx.context.adapter.update(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}], update: {metadata: encoded})
+        end
+        set(ctx, updated, config) if config[:storage] == "secondary-storage"
+        updated
+      end
+
+      def storage(config, context = nil)
+        config[:custom_storage] || context&.options&.secondary_storage
+      end
+
+      def get(ctx, key, config)
+        raw = storage(config, ctx.context)&.get(key)
+        raw && deserialize_record(JSON.parse(raw))
+      rescue JSON::ParserError
+        nil
+      end
+
+      def set(ctx, record, config)
+        storage_instance = storage(config, ctx.context)
+        unless storage_instance
+          raise BetterAuth::APIError.new("INTERNAL_SERVER_ERROR", message: "Secondary storage is required when storage mode is 'secondary-storage'")
+        end
+
+        serialized = JSON.generate(storage_record(record))
+        expires_at = BetterAuth::APIKey::Utils.normalize_time(record["expiresAt"])
+        ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
+        reference_id = BetterAuth::Plugins.api_key_record_reference_id(record)
+        reference_key = storage_key_by_reference(reference_id)
+
+        batch(storage_instance) do
+          operations = [
+            -> { storage_instance.set(storage_key_by_hash(record["key"]), serialized, ttl) },
+            -> { storage_instance.set(storage_key_by_id(record["id"]), serialized, ttl) }
+          ]
+          operations << if config[:fallback_to_database]
+            -> { storage_instance.delete(reference_key) }
+          else
+            -> { ref_list_add(storage_instance, reference_key, record["id"]) }
+          end
+          operations.each(&:call)
+        end
+      end
+
+      def delete(ctx, record, config)
+        storage_instance = storage(config, ctx.context)
+        return unless storage_instance
+
+        reference_id = BetterAuth::Plugins.api_key_record_reference_id(record)
+        reference_key = storage_key_by_reference(reference_id)
+
+        batch(storage_instance) do
+          operations = [
+            -> { storage_instance.delete(storage_key_by_hash(record["key"])) },
+            -> { storage_instance.delete(storage_key_by_id(record["id"])) },
+            # Ruby-only legacy storage layout cleanup; upstream never wrote here.
+            -> { storage_instance.delete("api-key:key:#{record["key"]}") },
+            -> { storage_instance.delete("api-key:id:#{record["id"]}") }
+          ]
+          operations << if config[:fallback_to_database]
+            -> { storage_instance.delete(reference_key) }
+          else
+            -> { ref_list_remove(storage_instance, reference_key, record["id"]) }
+          end
+          operations.each(&:call)
+        end
+      end
+
+      def ref_list_add(storage_instance, reference_key, id)
+        ids = safe_parse_id_list(storage_instance.get(reference_key))
+        ids << id unless ids.include?(id)
+        storage_instance.set(reference_key, JSON.generate(ids))
+      end
+
+      def ref_list_remove(storage_instance, reference_key, id)
+        ids = safe_parse_id_list(storage_instance.get(reference_key)).reject { |existing| existing == id }
+        ids.empty? ? storage_instance.delete(reference_key) : storage_instance.set(reference_key, JSON.generate(ids))
+      end
+
+      def safe_parse_id_list(raw)
+        return [] if raw.nil?
+
+        parsed = JSON.parse(raw.to_s)
+        parsed.is_a?(Array) ? parsed : []
+      rescue JSON::ParserError
+        []
+      end
+
+      def batch(storage_instance, &block)
+        if storage_instance.respond_to?(:batch)
+          storage_instance.batch(&block)
+        else
+          block.call
+        end
+      end
+
+      def populate_reference(ctx, reference_id, records, config)
+        storage_instance = storage(config, ctx.context)
+        return unless storage_instance
+
+        ids = []
+        records.each do |record|
+          serialized = JSON.generate(storage_record(record))
+          expires_at = BetterAuth::APIKey::Utils.normalize_time(record["expiresAt"])
+          ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
+          storage_instance.set(storage_key_by_hash(record["key"]), serialized, ttl)
+          storage_instance.set(storage_key_by_id(record["id"]), serialized, ttl)
+          ids << record["id"]
+        end
+        reference_key = storage_key_by_reference(reference_id)
+        ids.empty? ? storage_instance.delete(reference_key) : storage_instance.set(reference_key, JSON.generate(ids))
+      end
+
+      def storage_record(record)
+        record.transform_values { |value| value.is_a?(Time) ? value.iso8601 : value }
+      end
+
+      def deserialize_record(record)
+        %w[createdAt updatedAt expiresAt lastRefillAt lastRequest].each do |field|
+          record[field] = BetterAuth::APIKey::Utils.normalize_time(record[field]) if record[field]
+        end
+        record
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/configuration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Configuration
+      module_function
+
+      def normalize(configurations, options = nil)
+        if configurations.is_a?(Array)
+          normalized_configs = configurations.map { |config| single(config) }
+          if normalized_configs.any? { |config| config[:config_id].to_s.empty? }
+            raise BetterAuth::Error, "configId is required for each API key configuration in the api-key plugin."
+          end
+          config_ids = normalized_configs.map { |config| config[:config_id] }
+          raise BetterAuth::Error, "configId must be unique for each API key configuration in the api-key plugin." if config_ids.uniq.length != config_ids.length
+
+          plugin_options = BetterAuth::Plugins.normalize_hash(options || {})
+          default_config = normalized_configs.find { |config| BetterAuth::APIKey::Routes.default_config_id?(config[:config_id]) }
+          default_config ||= normalized_configs.first
+          default_config.merge(
+            configurations: normalized_configs,
+            schema: plugin_options[:schema] || default_config[:schema]
+          )
+        else
+          config = single(configurations)
+          config[:config_id] ||= "default"
+          config.merge(configurations: [config])
+        end
+      end
+
+      def single(options)
+        data = BetterAuth::Plugins.normalize_hash(options || {})
+        rate_limit_options = data[:rate_limit] || {}
+        starting_characters_options = data[:starting_characters_config] || {}
+        {
+          config_id: data[:config_id],
+          api_key_headers: data[:api_key_headers] || "x-api-key",
+          default_key_length: data[:default_key_length] || 64,
+          default_prefix: data[:default_prefix],
+          maximum_prefix_length: data.key?(:maximum_prefix_length) ? data[:maximum_prefix_length] : 32,
+          minimum_prefix_length: data.key?(:minimum_prefix_length) ? data[:minimum_prefix_length] : 1,
+          maximum_name_length: data.key?(:maximum_name_length) ? data[:maximum_name_length] : 32,
+          minimum_name_length: data.key?(:minimum_name_length) ? data[:minimum_name_length] : 1,
+          enable_metadata: data[:enable_metadata] || false,
+          disable_key_hashing: data[:disable_key_hashing] || false,
+          require_name: data[:require_name] || false,
+          storage: data[:storage] || "database",
+          rate_limit: {
+            enabled: rate_limit_options.fetch(:enabled, true),
+            time_window: rate_limit_options[:time_window] || 86_400_000,
+            max_requests: rate_limit_options[:max_requests] || 10
+          },
+          key_expiration: {
+            default_expires_in: data.dig(:key_expiration, :default_expires_in),
+            disable_custom_expires_time: data.dig(:key_expiration, :disable_custom_expires_time) || false,
+            max_expires_in: data.dig(:key_expiration, :max_expires_in) || 365,
+            min_expires_in: data.dig(:key_expiration, :min_expires_in) || 1
+          },
+          starting_characters_config: {
+            should_store: starting_characters_options.fetch(:should_store, true),
+            characters_length: starting_characters_options[:characters_length] || 6
+          },
+          enable_session_for_api_keys: data[:enable_session_for_api_keys] || false,
+          fallback_to_database: data[:fallback_to_database] || false,
+          custom_storage: data[:custom_storage],
+          custom_key_generator: data[:custom_key_generator],
+          custom_api_key_getter: data[:custom_api_key_getter],
+          custom_api_key_validator: data[:custom_api_key_validator],
+          default_permissions: data[:default_permissions],
+          permissions: data[:permissions] || {},
+          references: data[:references] || "user",
+          defer_updates: data[:defer_updates] || false,
+          schema: data[:schema]
+        }
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/error_codes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    ERROR_CODES = {
+      "INVALID_METADATA_TYPE" => "metadata must be an object or undefined",
+      "REFILL_AMOUNT_AND_INTERVAL_REQUIRED" => "refillAmount is required when refillInterval is provided",
+      "REFILL_INTERVAL_AND_AMOUNT_REQUIRED" => "refillInterval is required when refillAmount is provided",
+      "USER_BANNED" => "User is banned",
+      "UNAUTHORIZED_SESSION" => "Unauthorized or invalid session",
+      "KEY_NOT_FOUND" => "API Key not found",
+      "KEY_DISABLED" => "API Key is disabled",
+      "KEY_EXPIRED" => "API Key has expired",
+      "USAGE_EXCEEDED" => "API Key has reached its usage limit",
+      "KEY_NOT_RECOVERABLE" => "API Key is not recoverable",
+      "EXPIRES_IN_IS_TOO_SMALL" => "The expiresIn is smaller than the predefined minimum value.",
+      "EXPIRES_IN_IS_TOO_LARGE" => "The expiresIn is larger than the predefined maximum value.",
+      "INVALID_REMAINING" => "The remaining count is either too large or too small.",
+      "INVALID_PREFIX_LENGTH" => "The prefix length is either too large or too small.",
+      "INVALID_NAME_LENGTH" => "The name length is either too large or too small.",
+      "METADATA_DISABLED" => "Metadata is disabled.",
+      "RATE_LIMIT_EXCEEDED" => "Rate limit exceeded.",
+      "NO_VALUES_TO_UPDATE" => "No values to update.",
+      "KEY_DISABLED_EXPIRATION" => "Custom key expiration values are disabled.",
+      "INVALID_API_KEY" => "Invalid API key.",
+      "INVALID_USER_ID_FROM_API_KEY" => "The user id from the API key is invalid.",
+      "INVALID_REFERENCE_ID_FROM_API_KEY" => "The reference id from the API key is invalid.",
+      "INVALID_API_KEY_GETTER_RETURN_TYPE" => "API Key getter returned an invalid key type. Expected string.",
+      "SERVER_ONLY_PROPERTY" => "The property you're trying to set can only be set from the server auth instance only.",
+      "FAILED_TO_UPDATE_API_KEY" => "Failed to update API key",
+      "NAME_REQUIRED" => "API Key name is required.",
+      "ORGANIZATION_ID_REQUIRED" => "Organization ID is required for organization-owned API keys.",
+      "USER_NOT_MEMBER_OF_ORGANIZATION" => "You are not a member of the organization that owns this API key.",
+      "INSUFFICIENT_API_KEY_PERMISSIONS" => "You do not have permission to perform this action on organization API keys.",
+      "NO_DEFAULT_API_KEY_CONFIGURATION_FOUND" => "No default api-key configuration found.",
+      "ORGANIZATION_PLUGIN_REQUIRED" => "Organization plugin is required for organization-owned API keys. Please install and configure the organization plugin."
+    }.freeze
+  end
+end

data/lib/better_auth/api_key/keys.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module BetterAuth
+  module APIKey
+    module Keys
+      module_function
+
+      def default_hasher(key)
+        BetterAuth::Crypto.sha256(key.to_s, encoding: :base64url)
+      end
+
+      def generate(config, prefix)
+        generator = config[:custom_key_generator]
+        return generator.call({length: config[:default_key_length], prefix: prefix}) if generator.respond_to?(:call)
+
+        alphabet = [*("a".."z"), *("A".."Z")]
+        "#{prefix}#{Array.new(config[:default_key_length].to_i) { alphabet[SecureRandom.random_number(alphabet.length)] }.join}"
+      end
+
+      def hash(key, config)
+        config[:disable_key_hashing] ? key.to_s : default_hasher(key)
+      end
+
+      def normalize_body(raw)
+        body = BetterAuth::Plugins.normalize_hash(raw)
+        return body unless raw.is_a?(Hash)
+
+        metadata_key = raw.key?(:metadata) ? :metadata : ("metadata" if raw.key?("metadata"))
+        body[:metadata] = raw[metadata_key] if metadata_key
+        body
+      end
+
+      def expires_at(body, config)
+        if body.key?(:expires_in)
+          Time.now + body[:expires_in].to_i unless body[:expires_in].nil?
+        elsif config[:key_expiration][:default_expires_in]
+          Time.now + config[:key_expiration][:default_expires_in].to_i
+        end
+      end
+
+      def from_headers(ctx, config)
+        getter = config[:custom_api_key_getter]
+        return getter.call(ctx) if getter.respond_to?(:call)
+
+        Array(config[:api_key_headers]).each do |header|
+          value = ctx.headers[header.to_s.downcase]
+          return value if value
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/org_authorization.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module OrgAuthorization
+      PERMISSIONS = {
+        apiKey: %w[create read update delete]
+      }.freeze
+
+      module_function
+
+      def check_permission!(ctx, user_id, organization_id, action)
+        org_plugin = ctx.context.options.plugins.find { |plugin| plugin.id == "organization" }
+        unless org_plugin
+          raise BetterAuth::APIError.new(
+            "INTERNAL_SERVER_ERROR",
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["ORGANIZATION_PLUGIN_REQUIRED"],
+            code: "ORGANIZATION_PLUGIN_REQUIRED"
+          )
+        end
+
+        member = ctx.context.adapter.find_one(model: "member", where: [{field: "userId", value: user_id}, {field: "organizationId", value: organization_id}])
+        unless member
+          raise BetterAuth::APIError.new(
+            "FORBIDDEN",
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USER_NOT_MEMBER_OF_ORGANIZATION"],
+            code: "USER_NOT_MEMBER_OF_ORGANIZATION"
+          )
+        end
+
+        return member if member["role"].to_s == (org_plugin.options[:creator_role] || "owner").to_s
+
+        permissions = {"apiKey" => [action]}
+        return member if BetterAuth::Plugins.organization_permission?(ctx, org_plugin.options, member["role"], permissions, organization_id)
+
+        raise BetterAuth::APIError.new(
+          "FORBIDDEN",
+          message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INSUFFICIENT_API_KEY_PERMISSIONS"],
+          code: "INSUFFICIENT_API_KEY_PERMISSIONS"
+        )
+      end
+
+      def authorize_reference!(ctx, config, user_id, reference_id, action)
+        if config[:references].to_s == "organization"
+          check_permission!(ctx, user_id, reference_id, action)
+        elsif reference_id != user_id
+          raise BetterAuth::APIError.new("NOT_FOUND", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"])
+        end
+      end
+
+      def create_reference_id!(ctx, body, session, config)
+        if config[:references].to_s == "organization"
+          organization_id = body[:organization_id]
+          if organization_id.to_s.empty?
+            raise BetterAuth::APIError.new(
+              "BAD_REQUEST",
+              message: BetterAuth::Plugins::API_KEY_ERROR_CODES["ORGANIZATION_ID_REQUIRED"],
+              code: "ORGANIZATION_ID_REQUIRED"
+            )
+          end
+
+          user_id = session&.dig(:user, "id") || body[:user_id]
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"]) if user_id.to_s.empty?
+
+          check_permission!(ctx, user_id, organization_id, "create")
+          organization_id
+        elsif session && body[:user_id] && body[:user_id] != session[:user]["id"]
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+        elsif session
+          session[:user]["id"]
+        else
+          user_id = body[:user_id]
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"]) if user_id.to_s.empty?
+
+          user_id
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/plugin_factory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module PluginFactory
+      module_function
+
+      def build(configurations = {}, options = nil)
+        config = BetterAuth::APIKey::Configuration.normalize(configurations, options)
+        BetterAuth::Plugin.new(
+          id: "api-key",
+          version: BetterAuth::APIKey::VERSION,
+          hooks: {
+            before: [
+              {
+                matcher: ->(ctx) { !!BetterAuth::APIKey::Session.header_config(ctx, config) },
+                handler: ->(ctx) { BetterAuth::APIKey::Session.hook(ctx, config) }
+              }
+            ]
+          },
+          endpoints: {
+            create_api_key: BetterAuth::APIKey::Routes::CreateAPIKey.endpoint(config),
+            verify_api_key: BetterAuth::APIKey::Routes::VerifyAPIKey.endpoint(config),
+            get_api_key: BetterAuth::APIKey::Routes::GetAPIKey.endpoint(config),
+            update_api_key: BetterAuth::APIKey::Routes::UpdateAPIKey.endpoint(config),
+            delete_api_key: BetterAuth::APIKey::Routes::DeleteAPIKey.endpoint(config),
+            list_api_keys: BetterAuth::APIKey::Routes::ListAPIKeys.endpoint(config),
+            delete_all_expired_api_keys: BetterAuth::APIKey::Routes::DeleteAllExpiredAPIKeys.endpoint(config)
+          },
+          schema: BetterAuth::APIKey::SchemaDefinition.schema(config, config[:schema]),
+          error_codes: BetterAuth::APIKey::ERROR_CODES,
+          options: config
+        )
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/rate_limit.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module RateLimit
+      module_function
+
+      def try_again_in(record, config, now)
+        return nil if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
+
+        window = record["rateLimitTimeWindow"]
+        max = record["rateLimitMax"]
+        return nil if window.nil? || max.nil?
+
+        last = Utils.normalize_time(record["lastRequest"])
+        return nil unless last
+
+        elapsed_ms = (now - last) * 1000
+        return nil if elapsed_ms > window.to_i
+        return nil if record["requestCount"].to_i < max.to_i
+
+        (window.to_i - elapsed_ms).ceil
+      end
+
+      def counts_requests?(record, config)
+        return false if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
+
+        !record["rateLimitTimeWindow"].nil? && !record["rateLimitMax"].nil?
+      end
+
+      def next_request_count(record, now)
+        last = Utils.normalize_time(record["lastRequest"])
+        window = record["rateLimitTimeWindow"].to_i
+        return 1 unless last && window.positive?
+
+        elapsed_ms = (now - last) * 1000
+        (elapsed_ms <= window) ? record["requestCount"].to_i + 1 : 1
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/routes/create_api_key.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module CreateAPIKey
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/create-api-key.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/create", method: "POST") do |ctx|
+            body = BetterAuth::Plugins.api_key_normalize_body(ctx.body)
+            resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
+            session = BetterAuth::Routes.current_session(ctx, allow_nil: true)
+            reference_id = BetterAuth::Plugins.api_key_create_reference_id!(ctx, body, session, resolved_config)
+
+            BetterAuth::Plugins.api_key_validate_create_update!(body, resolved_config, create: true, client: !ctx.headers.empty?)
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, resolved_config)
+            key_prefix = body.key?(:prefix) ? body[:prefix] : resolved_config[:default_prefix]
+            key = BetterAuth::Plugins.api_key_generate_key(resolved_config, key_prefix)
+            now = Time.now
+            hashed = BetterAuth::Plugins.api_key_hash(key, resolved_config)
+            data = {
+              configId: resolved_config[:config_id] || "default",
+              name: body[:name],
+              start: resolved_config[:starting_characters_config][:should_store] ? key[0, resolved_config[:starting_characters_config][:characters_length].to_i] : nil,
+              prefix: key_prefix,
+              key: hashed,
+              referenceId: reference_id,
+              enabled: true,
+              rateLimitEnabled: body.key?(:rate_limit_enabled) ? body[:rate_limit_enabled] : resolved_config[:rate_limit][:enabled],
+              rateLimitTimeWindow: body[:rate_limit_time_window] || resolved_config[:rate_limit][:time_window],
+              rateLimitMax: body[:rate_limit_max] || resolved_config[:rate_limit][:max_requests],
+              requestCount: 0,
+              remaining: body.key?(:remaining) ? body[:remaining] : nil,
+              refillAmount: body[:refill_amount],
+              refillInterval: body[:refill_interval],
+              lastRefillAt: nil,
+              expiresAt: BetterAuth::Plugins.api_key_expires_at(body, resolved_config),
+              createdAt: now,
+              updatedAt: now,
+              permissions: BetterAuth::Plugins.api_key_encode_json(body[:permissions] || BetterAuth::Plugins.api_key_default_permissions(resolved_config, reference_id, ctx)),
+              metadata: body.key?(:metadata) ? BetterAuth::Plugins.api_key_encode_json(body[:metadata]) : nil
+            }
+            record = BetterAuth::Plugins.api_key_store(ctx, data, resolved_config)
+            BetterAuth::Plugins.api_key_public(record, reveal_key: key, include_key_field: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/routes/delete_all_expired_api_keys.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module DeleteAllExpiredAPIKeys
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/delete-all-expired-api-keys.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/delete-all-expired-api-keys", method: "POST") do |ctx|
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, config, bypass_last_check: true)
+            ctx.json({success: true, error: nil})
+          rescue => error
+            ctx.context.logger.error("[API KEY PLUGIN] Failed to delete expired API keys: #{error.message}") if ctx.context.logger.respond_to?(:error)
+            ctx.json({success: false, error: error})
+          end
+        end
+      end
+    end
+  end
+end