better_auth-api-key 0.2.1 → 0.6.2

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module DeleteAPIKey
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/delete-api-key.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/delete", method: "POST") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USER_BANNED"]) if session[:user]["banned"] == true
+
+            body = BetterAuth::Plugins.normalize_hash(ctx.body)
+            resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
+            key_id = body[:key_id]
+            record = BetterAuth::Plugins.api_key_find_by_id(ctx, key_id, resolved_config)
+            unless record && BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), resolved_config[:config_id])
+              raise BetterAuth::APIError.new("NOT_FOUND", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"])
+            end
+
+            record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+            BetterAuth::Plugins.api_key_authorize_reference!(ctx, record_config, session[:user]["id"], BetterAuth::Plugins.api_key_record_reference_id(record), "delete")
+
+            BetterAuth::Plugins.api_key_delete_record(ctx, record, record_config)
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, record_config)
+            ctx.json({success: true})
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module GetAPIKey
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/get-api-key.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/get", method: "GET") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            query = BetterAuth::Plugins.normalize_hash(ctx.query)
+            resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])
+            id = query[:id]
+            record = BetterAuth::Plugins.api_key_find_by_id(ctx, id, resolved_config)
+            unless record && BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), resolved_config[:config_id])
+              raise BetterAuth::APIError.new("NOT_FOUND", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"])
+            end
+
+            record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+            BetterAuth::Plugins.api_key_authorize_reference!(ctx, record_config, session[:user]["id"], BetterAuth::Plugins.api_key_record_reference_id(record), "read")
+
+            record = BetterAuth::Plugins.api_key_migrate_legacy_metadata(ctx, record, record_config)
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, record_config)
+            ctx.json(BetterAuth::Plugins.api_key_public(record, include_key_field: false))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      ROUTE_NAMES = %i[
+        create_api_key
+        verify_api_key
+        get_api_key
+        update_api_key
+        delete_api_key
+        list_api_keys
+        delete_all_expired_api_keys
+      ].freeze
+
+      module_function
+
+      def resolve_config(context, config, config_id = nil)
+        configurations = config.fetch(:configurations, [config])
+        return configurations.find { |entry| default_config_id?(entry[:config_id]) } || configurations.first if config_id.to_s.empty?
+
+        configurations.find { |entry| entry[:config_id].to_s == config_id.to_s } ||
+          begin
+            default = configurations.find { |entry| default_config_id?(entry[:config_id]) }
+            unless default
+              context.logger.error(BetterAuth::Plugins::API_KEY_ERROR_CODES["NO_DEFAULT_API_KEY_CONFIGURATION_FOUND"]) if context.respond_to?(:logger) && context.logger.respond_to?(:error)
+              raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["NO_DEFAULT_API_KEY_CONFIGURATION_FOUND"])
+            end
+            default
+          end
+      end
+
+      def default_config_id?(value)
+        value.nil? || value.to_s.empty? || value.to_s == "default"
+      end
+
+      def config_id_matches?(record_config_id, expected_config_id)
+        return true if default_config_id?(record_config_id) && default_config_id?(expected_config_id)
+
+        record_config_id.to_s == expected_config_id.to_s
+      end
+
+      @last_expired_check = nil
+
+      def delete_expired(context, config, bypass_last_check: false)
+        return unless config[:storage] == "database" || config[:fallback_to_database]
+        unless bypass_last_check
+          now = Time.now
+          return if @last_expired_check && ((now - @last_expired_check) * 1000) < 10_000
+
+          @last_expired_check = now
+        end
+
+        expired = context.adapter.find_many(model: BetterAuth::Plugins::API_KEY_TABLE_NAME).select do |record|
+          record["expiresAt"] && record["expiresAt"] < Time.now
+        end
+        expired.each do |record|
+          context.adapter.delete(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}])
+        end
+      end
+
+      def schedule_cleanup(ctx, config)
+        task = -> { delete_expired(ctx.context, config) }
+        if config[:defer_updates] && BetterAuth::APIKey::Utils.background_tasks?(ctx)
+          ctx.context.run_in_background(task)
+        else
+          task.call
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module ListAPIKeys
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/list-api-keys.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/list", method: "GET") do |ctx|
+            session = BetterAuth::Routes.current_session(ctx)
+            query = BetterAuth::Plugins.normalize_hash(ctx.query)
+            BetterAuth::Plugins.api_key_validate_list_query!(query)
+            configs = query[:config_id] ? [BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])] : config.fetch(:configurations, [config])
+            reference_id = query[:organization_id] || session[:user]["id"]
+            expected_reference = query[:organization_id] ? "organization" : "user"
+            BetterAuth::Plugins.api_key_check_org_permission!(ctx, session[:user]["id"], reference_id, "read") if query[:organization_id]
+            records = configs.flat_map { |entry| BetterAuth::Plugins.api_key_list_for_reference(ctx, reference_id, entry) }.uniq { |record| record["id"] }
+            records = records.select do |record|
+              record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+              record_config[:references].to_s == expected_reference &&
+                BetterAuth::Plugins.api_key_record_reference_id(record) == reference_id &&
+                (!query[:config_id] || BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), query[:config_id]))
+            end
+            total = records.length
+            records = BetterAuth::Plugins.api_key_sort_records(records, query[:sort_by], query[:sort_direction])
+            offset = query.key?(:offset) ? query[:offset].to_i : nil
+            limit = query.key?(:limit) ? query[:limit].to_i : nil
+            records = records.drop(offset) if offset
+            records = records.first(limit) if limit
+            records.each { |record| BetterAuth::Plugins.api_key_delete_expired(ctx.context, BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))) }
+            api_keys = records.map do |record|
+              record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+              BetterAuth::Plugins.api_key_public(BetterAuth::Plugins.api_key_migrate_legacy_metadata(ctx, record, record_config), include_key_field: false)
+            end
+            ctx.json({apiKeys: api_keys, total: total, limit: limit, offset: offset})
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module UpdateAPIKey
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/update-api-key.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/update", 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)
+            user_id = session&.dig(:user, "id") || body[:user_id]
+            raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"]) unless user_id
+            if session && body[:user_id] && body[:user_id] != session[:user]["id"]
+              raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+            end
+
+            key_id = body[:key_id]
+            record = BetterAuth::Plugins.api_key_find_by_id(ctx, key_id, resolved_config)
+            raise BetterAuth::APIError.new("NOT_FOUND", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"]) unless record
+            unless BetterAuth::Plugins.api_key_config_id_matches?(BetterAuth::Plugins.api_key_record_config_id(record), resolved_config[:config_id])
+              raise BetterAuth::APIError.new("NOT_FOUND", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"])
+            end
+
+            record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+            BetterAuth::Plugins.api_key_authorize_reference!(ctx, record_config, user_id, BetterAuth::Plugins.api_key_record_reference_id(record), "update")
+
+            BetterAuth::Plugins.api_key_validate_create_update!(body, record_config, create: false, client: BetterAuth::Plugins.api_key_auth_required?(ctx))
+            update = BetterAuth::Plugins.api_key_update_payload(body, record_config)
+            raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["NO_VALUES_TO_UPDATE"]) if update.empty?
+
+            updated = BetterAuth::Plugins.api_key_update_record(ctx, record, update.merge(updatedAt: Time.now), record_config)
+            updated = BetterAuth::Plugins.api_key_migrate_legacy_metadata(ctx, updated, record_config)
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, record_config)
+            ctx.json(BetterAuth::Plugins.api_key_public(updated, include_key_field: false))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Routes
+      module VerifyAPIKey
+        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/verify-api-key.ts"
+
+        module_function
+
+        def endpoint(config)
+          BetterAuth::Endpoint.new(path: "/api-key/verify", method: "POST") do |ctx|
+            body = BetterAuth::Plugins.normalize_hash(ctx.body)
+            resolved_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, body[:config_id])
+            key = body[:key]
+            if key.to_s.empty?
+              raise BetterAuth::APIError.new(
+                "FORBIDDEN",
+                message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"],
+                code: "INVALID_API_KEY"
+              )
+            end
+
+            if resolved_config[:custom_api_key_validator].respond_to?(:call) && !resolved_config[:custom_api_key_validator].call({ctx: ctx, key: key})
+              ctx.json({valid: false, error: {message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "KEY_NOT_FOUND"}, key: nil})
+            else
+              record = BetterAuth::Plugins.api_key_validate!(ctx, key, resolved_config, permissions: body[:permissions])
+              record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+              BetterAuth::Plugins.api_key_schedule_cleanup(ctx, record_config)
+              ctx.json({valid: true, error: nil, key: BetterAuth::Plugins.api_key_public(record, include_key_field: false)})
+            end
+          rescue BetterAuth::APIError => error
+            ctx.context.logger.error("Failed to validate API key: #{error.message}") if ctx.context.logger.respond_to?(:error)
+            ctx.json({valid: false, error: BetterAuth::Plugins.api_key_error_payload(error), key: nil})
+          rescue => error
+            ctx.context.logger.error("Failed to validate API key: #{error.message}") if ctx.context.logger.respond_to?(:error)
+            ctx.json({valid: false, error: {message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "INVALID_API_KEY"}, key: nil})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/schema.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module SchemaDefinition
+      module_function
+
+      def schema(config, custom_schema = nil)
+        base = {
+          apikey: {
+            fields: {
+              configId: {type: "string", required: true, default_value: "default", index: true},
+              name: {type: "string", required: false},
+              start: {type: "string", required: false},
+              prefix: {type: "string", required: false},
+              key: {type: "string", required: true, index: true},
+              referenceId: {type: "string", required: true, index: true},
+              refillInterval: {type: "number", required: false},
+              refillAmount: {type: "number", required: false},
+              lastRefillAt: {type: "date", required: false},
+              enabled: {type: "boolean", required: false, default_value: true},
+              rateLimitEnabled: {type: "boolean", required: false, default_value: true},
+              rateLimitTimeWindow: {type: "number", required: false, default_value: config[:rate_limit][:time_window]},
+              rateLimitMax: {type: "number", required: false, default_value: config[:rate_limit][:max_requests]},
+              requestCount: {type: "number", required: false, default_value: 0},
+              remaining: {type: "number", required: false},
+              lastRequest: {type: "date", required: false},
+              expiresAt: {type: "date", required: false},
+              createdAt: {type: "date", required: true},
+              updatedAt: {type: "date", required: true},
+              permissions: {type: "string", required: false},
+              metadata: {type: "string", required: false}
+            }
+          }
+        }
+        BetterAuth::Plugins.deep_merge_hashes(base, BetterAuth::Plugins.normalize_hash(custom_schema || {}))
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/session.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Session
+      module_function
+
+      def header_config(ctx, config)
+        config.fetch(:configurations, [config]).find do |entry|
+          entry[:enable_session_for_api_keys] && BetterAuth::APIKey::Keys.from_headers(ctx, entry)
+        end
+      end
+
+      def hook(ctx, config)
+        config = header_config(ctx, config) || config
+        key = BetterAuth::APIKey::Keys.from_headers(ctx, config)
+        unless key.is_a?(String)
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY_GETTER_RETURN_TYPE"])
+        end
+        raise BetterAuth::APIError.new("FORBIDDEN", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"]) if key.length < config[:default_key_length].to_i
+
+        if config[:custom_api_key_validator].respond_to?(:call) && !config[:custom_api_key_validator].call({ctx: ctx, key: key})
+          raise BetterAuth::APIError.new("FORBIDDEN", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"])
+        end
+
+        record = BetterAuth::Plugins.api_key_validate!(ctx, key, config)
+        BetterAuth::APIKey::Routes.schedule_cleanup(ctx, config)
+        if config[:references].to_s != "user"
+          raise BetterAuth::APIError.new(
+            "UNAUTHORIZED",
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"],
+            code: "INVALID_REFERENCE_ID_FROM_API_KEY"
+          )
+        end
+        reference_id = BetterAuth::APIKey::Types.record_reference_id(record)
+        user = ctx.context.internal_adapter.find_user_by_id(reference_id)
+        unless user
+          raise BetterAuth::APIError.new(
+            "UNAUTHORIZED",
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"],
+            code: "INVALID_REFERENCE_ID_FROM_API_KEY"
+          )
+        end
+
+        session = {
+          user: user,
+          session: {
+            "id" => record["id"],
+            "token" => key,
+            "userId" => reference_id,
+            "userAgent" => ctx.headers["user-agent"],
+            "ipAddress" => BetterAuth::RequestIP.client_ip(ctx.request || ctx.headers, ctx.context.options),
+            "createdAt" => Time.now,
+            "updatedAt" => Time.now,
+            "expiresAt" => record["expiresAt"] || (Time.now + ctx.context.options.session[:expires_in].to_i)
+          }
+        }
+        ctx.context.set_current_session(session)
+        nil
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/types.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Types
+      API_KEY_TABLE_NAME = "apikey"
+
+      module_function
+
+      def record_reference_id(record)
+        record["referenceId"] || record[:referenceId] || record["userId"] || record[:userId]
+      end
+
+      def record_user_id(record)
+        record["userId"] || record[:userId] || (BetterAuth::APIKey::Routes.default_config_id?(record["configId"] || record[:configId]) && (record["referenceId"] || record[:referenceId]))
+      end
+
+      def record_config_id(record)
+        record["configId"] || record[:configId] || "default"
+      end
+
+      def default_permissions(config, reference_id, ctx)
+        permissions = config.dig(:permissions, :default_permissions) || config[:default_permissions]
+        return permissions.call(reference_id, ctx) if permissions.respond_to?(:call)
+
+        permissions
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/utils.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module BetterAuth
+  module APIKey
+    module Utils
+      module_function
+
+      def encode_json(value)
+        return nil if value.nil?
+
+        JSON.generate(value)
+      end
+
+      def decode_json(value)
+        return nil if value.nil?
+        return value if value.is_a?(Hash)
+
+        parsed = JSON.parse(value.to_s)
+        parsed.is_a?(String) ? decode_json(parsed) : parsed
+      rescue JSON::ParserError
+        nil
+      end
+
+      def normalize_time(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def public_record(record, reveal_key: nil, include_key_field: false)
+        data = record.transform_keys(&:to_sym)
+        output = data.except(:key)
+        output[:configId] ||= BetterAuth::APIKey::Types.record_config_id(record)
+        output[:referenceId] ||= BetterAuth::APIKey::Types.record_reference_id(record)
+        output[:key] = reveal_key if include_key_field && reveal_key
+        output[:metadata] = decode_json(data[:metadata])
+        output[:permissions] = decode_json(data[:permissions])
+        output
+      end
+
+      def sort_records(records, sort_by, direction)
+        return records unless sort_by
+
+        key = BetterAuth::Schema.storage_key(sort_by)
+        sorted = records.sort_by { |record| record[key] || record[key.to_sym] || "" }
+        if direction.to_s.downcase == "desc"
+          sorted.reverse
+        else
+          sorted
+        end
+      end
+
+      def validate_list_query!(query)
+        %i[limit offset].each do |key|
+          next unless query.key?(key)
+
+          value = query[key]
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: "Invalid #{key}") unless value.to_s.match?(/\A\d+\z/)
+        end
+
+        direction = query[:sort_direction]
+        return if direction.nil? || %w[asc desc].include?(direction.to_s.downcase)
+
+        raise BetterAuth::APIError.new("BAD_REQUEST", message: "Invalid sortDirection")
+      end
+
+      def error_code(error)
+        BetterAuth::Plugins::API_KEY_ERROR_CODES.key(error.message) || error.code.to_s
+      end
+
+      def error_payload(error)
+        payload = error.to_h
+        return payload if payload.is_a?(Hash) && payload.key?(:details)
+
+        {message: error.message, code: error_code(error)}
+      end
+
+      def background_tasks?(ctx)
+        ctx.context.options.advanced.dig(:background_tasks, :handler).respond_to?(:call)
+      end
+
+      def auth_required?(ctx)
+        !!(ctx.request || (ctx.headers && !ctx.headers.empty?))
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/validation.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module APIKey
+    module Validation
+      module_function
+
+      def validate_create_update!(body, config, create:, client:)
+        name = body[:name]
+        if create && config[:require_name] && name.to_s.empty?
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["NAME_REQUIRED"])
+        end
+        if name && !name.to_s.length.between?(config[:minimum_name_length].to_i, config[:maximum_name_length].to_i)
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_NAME_LENGTH"])
+        end
+        prefix = body[:prefix]
+        if prefix && !prefix.to_s.length.between?(config[:minimum_prefix_length].to_i, config[:maximum_prefix_length].to_i)
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_PREFIX_LENGTH"])
+        end
+        if prefix && !prefix.to_s.match?(/\A[a-zA-Z0-9_-]+\z/)
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_PREFIX_LENGTH"])
+        end
+        if body.key?(:remaining) && !body[:remaining].nil?
+          minimum = create ? 0 : 1
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_REMAINING"]) if body[:remaining].to_i < minimum
+        end
+        if body[:metadata] && (create || config[:enable_metadata])
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["METADATA_DISABLED"]) unless config[:enable_metadata]
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_METADATA_TYPE"]) unless body[:metadata].nil? || body[:metadata].is_a?(Hash)
+        end
+        server_only_keys = %i[refill_amount refill_interval rate_limit_max rate_limit_time_window rate_limit_enabled remaining permissions]
+        if client && server_only_keys.any? { |key| (create && key == :remaining) ? !body[:remaining].nil? : body.key?(key) }
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["SERVER_ONLY_PROPERTY"])
+        end
+        amount_present = body.key?(:refill_amount)
+        interval_present = body.key?(:refill_interval)
+        if amount_present && !interval_present
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["REFILL_AMOUNT_AND_INTERVAL_REQUIRED"])
+        end
+        if interval_present && !amount_present
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["REFILL_INTERVAL_AND_AMOUNT_REQUIRED"])
+        end
+        if body.key?(:expires_in)
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_DISABLED_EXPIRATION"]) if config[:key_expiration][:disable_custom_expires_time]
+          return if body[:expires_in].nil?
+
+          days = body[:expires_in].to_f / 86_400
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["EXPIRES_IN_IS_TOO_SMALL"]) if days < config[:key_expiration][:min_expires_in].to_f
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["EXPIRES_IN_IS_TOO_LARGE"]) if days > config[:key_expiration][:max_expires_in].to_f
+        end
+      end
+
+      def update_payload(body, config)
+        update = {}
+        update[:name] = body[:name] if body.key?(:name)
+        update[:enabled] = body[:enabled] unless body[:enabled].nil?
+        update[:remaining] = body[:remaining] if body.key?(:remaining)
+        update[:refillAmount] = body[:refill_amount] if body.key?(:refill_amount)
+        update[:refillInterval] = body[:refill_interval] if body.key?(:refill_interval)
+        update[:rateLimitEnabled] = body[:rate_limit_enabled] if body.key?(:rate_limit_enabled)
+        update[:rateLimitTimeWindow] = body[:rate_limit_time_window] if body.key?(:rate_limit_time_window)
+        update[:rateLimitMax] = body[:rate_limit_max] if body.key?(:rate_limit_max)
+        update[:expiresAt] = body[:expires_in].nil? ? nil : Time.now + body[:expires_in].to_i if body.key?(:expires_in)
+        update[:metadata] = BetterAuth::APIKey::Utils.encode_json(body[:metadata]) if body.key?(:metadata) && config[:enable_metadata]
+        update[:permissions] = BetterAuth::APIKey::Utils.encode_json(body[:permissions]) if body.key?(:permissions)
+        update
+      end
+
+      def validate_api_key!(ctx, key, config, permissions: nil)
+        hashed = BetterAuth::APIKey::Keys.hash(key, config)
+        record = BetterAuth::APIKey::Adapter.find_by_hash(ctx, hashed, config)
+        raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless record
+        unless BetterAuth::APIKey::Routes.config_id_matches?(BetterAuth::APIKey::Types.record_config_id(record), config[:config_id])
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"])
+        end
+        raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_DISABLED"]) if record["enabled"] == false
+        if record["expiresAt"] && record["expiresAt"] <= Time.now
+          BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_EXPIRED"])
+        end
+        if record["remaining"].to_i <= 0 && !record["remaining"].nil? && record["refillAmount"].nil?
+          BetterAuth::APIKey::Adapter.schedule_record_delete(ctx, record, config)
+          raise BetterAuth::APIError.new("TOO_MANY_REQUESTS", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
+        end
+
+        check_permissions!(record, permissions)
+        update = usage_update(record, config)
+        updated = BetterAuth::APIKey::Adapter.update_record(ctx, record, update, config, defer: true)
+        BetterAuth::APIKey::Adapter.migrate_legacy_metadata(ctx, updated || record.merge(update.transform_keys { |key_name| BetterAuth::Schema.storage_key(key_name) }), config)
+      end
+
+      def usage_update(record, config)
+        now = Time.now
+        update = {lastRequest: now, updatedAt: now}
+
+        if (try_again_in = BetterAuth::APIKey::RateLimit.try_again_in(record, config, now))
+          raise BetterAuth::APIError.new(
+            "UNAUTHORIZED",
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+            code: "RATE_LIMITED",
+            body: {
+              message: BetterAuth::Plugins::API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+              code: "RATE_LIMITED",
+              details: {tryAgainIn: try_again_in}
+            }
+          )
+        end
+        update[:requestCount] = BetterAuth::APIKey::RateLimit.next_request_count(record, now) if BetterAuth::APIKey::RateLimit.counts_requests?(record, config)
+
+        remaining = record["remaining"]
+        if !remaining.nil?
+          if remaining.to_i <= 0 && record["refillAmount"] && record["refillInterval"]
+            last_refill = BetterAuth::APIKey::Utils.normalize_time(record["lastRefillAt"] || record["createdAt"])
+            if !last_refill || ((now - last_refill) * 1000) > record["refillInterval"].to_i
+              remaining = record["refillAmount"].to_i
+              update[:lastRefillAt] = now
+            end
+          end
+          raise BetterAuth::APIError.new("TOO_MANY_REQUESTS", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USAGE_EXCEEDED"]) if remaining.to_i <= 0
+
+          update[:remaining] = remaining.to_i - 1
+        end
+        update
+      end
+
+      def check_permissions!(record, required)
+        return if required.nil? || required == {}
+
+        actual = BetterAuth::APIKey::Utils.decode_json(record["permissions"]) || {}
+        result = BetterAuth::Plugins::Role.new(actual).authorize(required)
+        unless result[:success]
+          raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["KEY_NOT_FOUND"], code: "KEY_NOT_FOUND")
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/api_key/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module APIKey
-    VERSION = "0.2.1"
+    VERSION = "0.6.2"
   end
 end