better_auth-api-key 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dd667853c3c3130a0d0bcd0ebd00a5f15425de87979f2cdc00b2a2f5d9001fe
-  data.tar.gz: f7222b9e0c3a61aabe67ec70ddefbc428f2d39e2181b53586e275ef3b9a63867
+  metadata.gz: e054d9e429e2c199d594467dcc924a9ef44c22c0be63f96e240f47308e4444ef
+  data.tar.gz: d34741924ce2951654646c1127f0d3caa09d16cd765f58647220ff6c71221e57
 SHA512:
-  metadata.gz: a36b2eaee2a0128a50276eff4ccfbfa7604ea06364a041e7f039d6d10f7a3b17216ccb36fff7470e2918148a437ac0fce3801677ed3ca71dc843883c7d3e364d
-  data.tar.gz: 3ecc422678b620d01b9c6848d60609246c3194e479d629d60ec21d92f8f7be330eade4a96e6971104da7bb62422e334e31d8069816a847df46ded0da005bc89e
+  metadata.gz: b8220f1cc0645105e0666c7d8184d43c72bb4e050094f4aa6cfb411b61f0622e2b0c2c4c21d50b7c586b82a80d96b7855c36b6e93b0dbbb94db2d87fd0456f2d
+  data.tar.gz: 5c1d00a8dc01502bc6709d0419195548eec8ad816846f9be05f58a3fa8c477305df53ba3722344f268b223b19b7e4ededd4bd138d1c1eca36a060c42872f6e02

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+- Hardened API-key verification and counter updates where authoritative adapter
+  operations are available, with regression coverage for stale-write cases.
+- Added a checked upstream test inventory for this plugin's pinned reference
+  files.
+
+## [0.11.0](https://github.com/salasebas/better-auth-rb/compare/better_auth-api-key-v0.10.0...better_auth-api-key/v0.11.0) (2026-07-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* **release:** OpenAuth alias gems, the openauth executable, and the better_auth_rails alias gem and require path are removed.
+
+### Features
+
+* **schema:** align migration plugin schema parity ([c0261dc](https://github.com/salasebas/better-auth-rb/commit/c0261dc1e5fd649557cd8a57b92c0609620c3767))
+
+
+### Bug Fixes
+
+* **api-key:** load access plugin before permission checks ([985e56c](https://github.com/salasebas/better-auth-rb/commit/985e56cdc29298aac995ff7d0f04a7f1bf13a7cd))
+* **api-key:** make verification counters authoritative ([6550ae7](https://github.com/salasebas/better-auth-rb/commit/6550ae753f104f771e313360f56e6fdcff82d005))
+* **ci:** restore package .ruby-version files for setup-ruby ([c18d220](https://github.com/salasebas/better-auth-rb/commit/c18d220065f3cb7cd2504bef7aa407e2c0c027eb))
+* load external plugin gems without stub recursion ([4926bae](https://github.com/salasebas/better-auth-rb/commit/4926bae7520c17438de25e99cb2155839c177493))
+* **saml:** fail closed without response parser ([#35](https://github.com/salasebas/better-auth-rb/issues/35)) ([0f9a7a4](https://github.com/salasebas/better-auth-rb/commit/0f9a7a4fb841153951b5f00ce42f01eee41b3112))
+
+
+### Miscellaneous Chores
+
+* **release:** retire aliases and refresh parity tooling ([e099464](https://github.com/salasebas/better-auth-rb/commit/e0994643694267508a3c4d9be020bb1fd0e2e5a3))
+
+## 0.10.0 - 2026-05-21
+
+- Improved adapter coverage and Redis-backed storage behavior for API key flows.
+- Tightened API key listing behavior so responses stay consistent across supported adapters.
+
 ## 0.7.0 - 2026-05-05
 
 - Changed API-key-backed sessions to expose `tokenFingerprint` instead of storing the raw API key in `session["token"]`.

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2024 - present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -64,10 +64,10 @@ purge secondary-only keys.
 The scheduled expired-key cleanup throttle is per Ruby process. It is not
 coordinated across web workers, hosts, or background job runners.
 
-When `defer_updates` is combined with `advanced.background_tasks.handler`, usage
-updates such as request counts, remaining limits, refill state, and scheduled
-cleanup can be reordered under concurrency. Use database transactions or
-deployment-level coordination if strict counters are required.
+`defer_updates` can defer explicit API-key updates and cleanup when a background
+task handler is configured. Verification counter claims remain synchronous;
+database-backed claims use guarded atomic operations, while pure secondary-only
+claims retain the best-effort limitation described below.
 
 ## Configuration
 
@@ -119,7 +119,21 @@ BetterAuth::Plugins.api_key([
 
 Organization-owned keys require `BetterAuth::Plugins.organization` and use organization permissions for `apiKey` actions: `create`, `read`, `update`, and `delete`.
 
-Secondary-storage mode uses upstream storage keys such as `api-key:<hash>`, `api-key:by-id:<id>`, and `api-key:by-ref:<referenceId>`. When `fallback_to_database: true` is enabled, the reference list is treated as a cache and invalidated on writes/deletes so concurrent writers cannot lose IDs; listing falls back to the database source of truth.
+Secondary-storage mode uses upstream storage keys such as `api-key:<hash>`, `api-key:by-id:<id>`, and `api-key:by-ref:<referenceId>`. With `fallback_to_database: true`, the database is authoritative: verification re-reads the row after a cache hit, and a missing authoritative row invalidates the cache and can never authorize. A cache entry may remain stale, or be briefly re-created from a row, during the unavoidable cross-store window after a database update and before its cache write; that does not weaken verification because authorization always requires the authoritative row. Generic custom storage gets an in-process lock for reference-list updates only; RedisStorage uses atomic cross-process JSON-list scripts.
+
+Verification rate-limit failures return HTTP `429` with error code
+`RATE_LIMITED` and `details.tryAgainIn` (authentication failures remain `401`).
+An exhausted non-refillable key remains an inert authoritative row and returns
+`USAGE_EXCEEDED`; Ruby deliberately avoids eager deletion during verification
+because deletion cannot be made cross-process atomic with the winning counter
+update. Cleanup routes/jobs can remove such rows separately.
+Database-backed keys, including `secondary-storage` with
+`fallback_to_database: true`, consume remaining and rate-limit counters with
+guarded atomic updates; concurrent requests cannot drive `remaining` below zero
+or exceed the configured window. Pure secondary-storage deployments do not have
+a guarded JSON-record counter primitive and are therefore best-effort under
+cross-process concurrency. Use `fallback_to_database` when strict enforcement
+is required.
 
 ## Storage layout
 

data/lib/better_auth/api_key/adapter.rb

@@ -10,6 +10,8 @@ module BetterAuth
       HASH_STORAGE_PREFIX = "api-key:"
       ID_STORAGE_PREFIX = "api-key:by-id:"
       REFERENCE_STORAGE_PREFIX = "api-key:by-ref:"
+      REFERENCE_LOCKS_GUARD = Mutex.new
+      REFERENCE_LOCK_STRIPE_COUNT = 256
 
       module_function
 
@@ -84,8 +86,10 @@ module BetterAuth
           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)
+            return nil unless updated
+          else
+            updated = record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
           end
-          updated ||= record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
           set(ctx, updated, config) if config[:storage] == "secondary-storage"
           updated
         end
@@ -195,14 +199,40 @@ module BetterAuth
       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))
+        if storage_instance.respond_to?(:json_list_add)
+          storage_instance.json_list_add(reference_key, id)
+          return
+        end
+
+        with_reference_lock(reference_key) do
+          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
       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))
+        if storage_instance.respond_to?(:json_list_remove)
+          storage_instance.json_list_remove(reference_key, id)
+          return
+        end
+
+        with_reference_lock(reference_key) do
+          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
+      end
+
+      # Custom secondary-storage implementations expose only get/set/delete,
+      # so serialize reference-list read/modify/write operations within this
+      # Ruby process. This lock is deliberately not treated as distributed
+      # safety; RedisStorage uses its atomic JSON-list scripts above.
+      def with_reference_lock(reference_key)
+        lock = REFERENCE_LOCKS_GUARD.synchronize do
+          @reference_lock_stripes ||= Array.new(REFERENCE_LOCK_STRIPE_COUNT) { Mutex.new }
+          @reference_lock_stripes[reference_key.hash % REFERENCE_LOCK_STRIPE_COUNT]
+        end
+        lock.synchronize { yield }
       end
 
       def safe_parse_id_list(raw)

data/lib/better_auth/api_key/rate_limit.rb

@@ -5,6 +5,36 @@ module BetterAuth
     module RateLimit
       module_function
 
+      # Pure decision function used by the verifier before applying a guarded
+      # counter mutation. Keeping the decision separate from the write avoids
+      # persisting a stale snapshot when another verifier wins the race.
+      def evaluate(record, config, now = Time.now)
+        return {type: :skip, last_request: now} if config[:rate_limit][:enabled] == false
+        return {type: :skip, last_request: now} if record["rateLimitEnabled"] == false
+
+        window = record["rateLimitTimeWindow"]
+        max = record["rateLimitMax"]
+        return {type: :skip, last_request: nil} if window.nil? || max.nil?
+
+        last = Utils.normalize_time(record["lastRequest"])
+        return {type: :start, now: now} unless last
+
+        elapsed_ms = (now - last) * 1000
+        if elapsed_ms > window.to_i
+          return {type: :reset, now: now, window_start: now - (window.to_i / 1000.0)}
+        end
+
+        if record["requestCount"].to_i >= max.to_i
+          return {
+            type: :deny,
+            try_again_in: [(window.to_i - elapsed_ms).ceil, 0].max,
+            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"]
+          }
+        end
+
+        {type: :increment, now: now, max: max.to_i, window_start: now - (window.to_i / 1000.0)}
+      end
+
       def try_again_in(record, config, now)
         return nil if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
 

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

@@ -4,15 +4,21 @@ module BetterAuth
   module APIKey
     module Routes
       module CreateAPIKey
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/create-api-key.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(path: "/api-key/create", method: "POST", metadata: Routes.openapi_for(:create_api_key)) 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)
+            # API-key ownership and authorization are sensitive operations. A
+            # cookie-cache snapshot may outlive a revoked session, so force an
+            # authoritative session read whenever stateful storage is active.
+            session = BetterAuth::Routes.current_session(ctx, allow_nil: true, sensitive: true)
+            if !session && BetterAuth::Plugins.api_key_auth_required?(ctx)
+              raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+            end
             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?)

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

@@ -4,13 +4,13 @@ module BetterAuth
   module APIKey
     module Routes
       module DeleteAllExpiredAPIKeys
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/delete-all-expired-api-keys.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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)
+          BetterAuth::Endpoint.new(path: "/api-key/delete-all-expired-api-keys", method: "POST", metadata: Routes.openapi_for(:delete_all_expired_api_keys)) do |ctx|
+            BetterAuth::APIKey::Routes.delete_expired(ctx.context, config, bypass_last_check: true, raise_on_error: 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)

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

@@ -4,12 +4,12 @@ module BetterAuth
   module APIKey
     module Routes
       module DeleteAPIKey
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/delete-api-key.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(path: "/api-key/delete", method: "POST", metadata: Routes.openapi_for(:delete_api_key)) 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
 

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

@@ -4,12 +4,12 @@ module BetterAuth
   module APIKey
     module Routes
       module GetAPIKey
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/get-api-key.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(path: "/api-key/get", method: "GET", metadata: Routes.openapi_for(:get_api_key)) 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])

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

@@ -42,7 +42,7 @@ module BetterAuth
 
       @last_expired_check = nil
 
-      def delete_expired(context, config, bypass_last_check: false)
+      def delete_expired(context, config, bypass_last_check: false, raise_on_error: false)
         return unless config[:storage] == "database" || config[:fallback_to_database]
         unless bypass_last_check
           now = Time.now
@@ -59,6 +59,9 @@ module BetterAuth
             {field: "expiresAt", value: nil, operator: "ne"}
           ]
         )
+      rescue => error
+        context.logger.error("[API KEY PLUGIN] Failed to delete expired API keys: #{error.message}") if context.respond_to?(:logger) && context.logger.respond_to?(:error)
+        raise if raise_on_error
       end
 
       def schedule_cleanup(ctx, config)
@@ -69,6 +72,230 @@ module BetterAuth
           task.call
         end
       end
+
+      def openapi_for(route)
+        {
+          create_api_key: create_api_key_openapi,
+          verify_api_key: verify_api_key_openapi,
+          get_api_key: get_api_key_openapi,
+          update_api_key: update_api_key_openapi,
+          delete_api_key: delete_api_key_openapi,
+          list_api_keys: list_api_keys_openapi,
+          delete_all_expired_api_keys: delete_all_expired_api_keys_openapi
+        }.fetch(route)
+      end
+
+      def create_api_key_openapi
+        {
+          openapi: {
+            description: "Create a new API key for a user",
+            requestBody: BetterAuth::OpenAPI.json_request_body(api_key_create_body_schema, required: true),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key created successfully", api_key_record_schema(include_secret: true))
+            }
+          }
+        }
+      end
+
+      def verify_api_key_openapi
+        response_schema = BetterAuth::OpenAPI.object_schema(
+          {
+            valid: {type: "boolean"},
+            error: {type: ["object", "null"], additionalProperties: true},
+            key: api_key_record_schema(include_secret: false).merge(type: ["object", "null"])
+          },
+          required: ["valid", "error", "key"]
+        )
+        {
+          openapi: {
+            description: "Verify and rate-limit an API key",
+            requestBody: BetterAuth::OpenAPI.json_request_body(
+              BetterAuth::OpenAPI.object_schema(
+                {
+                  key: {type: "string", description: "The API key to verify"},
+                  configId: {type: "string", description: "Configuration ID to use for the lookup"},
+                  permissions: api_key_permissions_schema.merge(description: "Permissions required for the request")
+                },
+                required: ["key"]
+              )
+            ),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "API key verification result",
+                response_schema
+              ),
+              "401" => BetterAuth::OpenAPI.json_response("API key authentication failed", response_schema),
+              "429" => BetterAuth::OpenAPI.json_response("API key usage or rate limit exceeded", response_schema)
+            }
+          }
+        }
+      end
+
+      def get_api_key_openapi
+        {
+          openapi: {
+            description: "Get an API key by ID",
+            parameters: [
+              BetterAuth::OpenAPI.query_parameter("id", required: true, description: "The API key ID"),
+              BetterAuth::OpenAPI.query_parameter("configId", description: "Configuration ID to use for the lookup")
+            ],
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key retrieved successfully", api_key_record_schema(include_secret: false))
+            }
+          }
+        }
+      end
+
+      def update_api_key_openapi
+        {
+          openapi: {
+            description: "Update an existing API key by ID",
+            requestBody: BetterAuth::OpenAPI.json_request_body(api_key_update_body_schema, required: true),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key updated successfully", api_key_record_schema(include_secret: false))
+            }
+          }
+        }
+      end
+
+      def delete_api_key_openapi
+        {
+          openapi: {
+            description: "Delete an API key by ID",
+            requestBody: BetterAuth::OpenAPI.json_request_body(
+              BetterAuth::OpenAPI.object_schema(
+                {
+                  keyId: {type: "string", description: "The API key ID"},
+                  configId: {type: "string", description: "Configuration ID to use for the lookup"}
+                },
+                required: ["keyId"]
+              )
+            ),
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response("API key deleted successfully", BetterAuth::OpenAPI.success_response_schema)
+            }
+          }
+        }
+      end
+
+      def list_api_keys_openapi
+        {
+          openapi: {
+            description: "List all API keys for the authenticated user or for a specific organization",
+            parameters: [
+              BetterAuth::OpenAPI.query_parameter("configId", description: "Filter by configuration ID"),
+              BetterAuth::OpenAPI.query_parameter("organizationId", description: "Organization ID to list keys for"),
+              BetterAuth::OpenAPI.query_parameter("limit", schema: {type: "number"}, description: "The number of API keys to return"),
+              BetterAuth::OpenAPI.query_parameter("offset", schema: {type: "number"}, description: "The offset to start from"),
+              BetterAuth::OpenAPI.query_parameter("sortBy", description: "The field to sort by"),
+              BetterAuth::OpenAPI.query_parameter("sortDirection", schema: {type: "string", enum: ["asc", "desc"]}, description: "The direction to sort by")
+            ],
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "API keys retrieved successfully",
+                BetterAuth::OpenAPI.object_schema(
+                  {
+                    apiKeys: BetterAuth::OpenAPI.array_schema(api_key_record_schema(include_secret: false)),
+                    total: {type: "number"},
+                    limit: {type: ["number", "null"]},
+                    offset: {type: ["number", "null"]}
+                  },
+                  required: ["apiKeys", "total"]
+                )
+              )
+            }
+          }
+        }
+      end
+
+      def delete_all_expired_api_keys_openapi
+        {
+          openapi: {
+            description: "Delete all expired API keys",
+            requestBody: BetterAuth::OpenAPI.empty_request_body,
+            responses: {
+              "200" => BetterAuth::OpenAPI.json_response(
+                "Expired API key cleanup result",
+                BetterAuth::OpenAPI.object_schema(
+                  {
+                    success: {type: "boolean"},
+                    error: {type: ["object", "null"], additionalProperties: true}
+                  },
+                  required: ["success", "error"]
+                )
+              )
+            }
+          }
+        }
+      end
+
+      def api_key_create_body_schema
+        BetterAuth::OpenAPI.object_schema(
+          {
+            configId: {type: "string", description: "The configuration ID to use for the API key"},
+            name: {type: "string", description: "Name of the API key"},
+            expiresIn: {type: ["number", "null"], description: "Expiration time of the API key in seconds"},
+            prefix: {type: "string", description: "Prefix of the API key"},
+            remaining: {type: ["number", "null"], description: "Remaining number of requests"},
+            metadata: {nullable: true, description: "Metadata associated with the API key"},
+            refillAmount: {type: "number", description: "Amount to refill the remaining count"},
+            refillInterval: {type: "number", description: "Interval to refill the API key in milliseconds"},
+            rateLimitTimeWindow: {type: "number", description: "Rate limit time window in milliseconds"},
+            rateLimitMax: {type: "number", description: "Maximum requests allowed within a window"},
+            rateLimitEnabled: {type: "boolean", description: "Whether the key has rate limiting enabled"},
+            permissions: api_key_permissions_schema.merge(description: "Permissions of the API key"),
+            userId: {type: "string", description: "User ID that the API key belongs to"},
+            organizationId: {type: "string", description: "Organization ID that the API key belongs to"}
+          }
+        )
+      end
+
+      def api_key_update_body_schema
+        BetterAuth::OpenAPI.object_schema(
+          api_key_create_body_schema[:properties].merge(
+            keyId: {type: "string", description: "The API key ID"},
+            enabled: {type: "boolean", description: "Whether the API key is enabled"}
+          ).except(:prefix, :organizationId),
+          required: ["keyId"]
+        )
+      end
+
+      def api_key_permissions_schema
+        {
+          type: "object",
+          additionalProperties: {
+            type: "array",
+            items: {type: "string"}
+          }
+        }
+      end
+
+      def api_key_record_schema(include_secret:)
+        properties = {
+          id: {type: "string", description: "Unique identifier of the API key"},
+          createdAt: {type: "string", format: "date-time", description: "Creation timestamp"},
+          updatedAt: {type: "string", format: "date-time", description: "Last update timestamp"},
+          name: {type: ["string", "null"], description: "Name of the API key"},
+          start: {type: ["string", "null"], description: "Starting characters of the key"},
+          prefix: {type: ["string", "null"], description: "Prefix of the API key"},
+          enabled: {type: "boolean", description: "Whether the key is enabled"},
+          expiresAt: {type: ["string", "null"], format: "date-time", description: "Expiration timestamp"},
+          referenceId: {type: "string", description: "ID of the reference owning the key"},
+          lastRefillAt: {type: ["string", "null"], format: "date-time", description: "Last refill timestamp"},
+          lastRequest: {type: ["string", "null"], format: "date-time", description: "Last request timestamp"},
+          metadata: {type: ["object", "null"], additionalProperties: true, description: "Metadata associated with the key"},
+          rateLimitMax: {type: ["number", "null"], description: "Maximum requests in time window"},
+          rateLimitTimeWindow: {type: ["number", "null"], description: "Rate limit time window in milliseconds"},
+          rateLimitEnabled: {type: "boolean", description: "Whether rate limiting is enabled"},
+          remaining: {type: ["number", "null"], description: "Remaining number of requests"},
+          refillAmount: {type: ["number", "null"], description: "Amount to refill"},
+          refillInterval: {type: ["number", "null"], description: "Refill interval in milliseconds"},
+          permissions: api_key_permissions_schema.merge(nullable: true, description: "Permissions of the API key"),
+          userId: {type: ["string", "null"], description: "ID of the user owning the key"}
+        }
+        properties[:key] = {type: "string", description: "The full API key"} if include_secret
+        BetterAuth::OpenAPI.object_schema(properties)
+      end
     end
   end
 end

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

@@ -4,33 +4,40 @@ module BetterAuth
   module APIKey
     module Routes
       module ListAPIKeys
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/list-api-keys.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(path: "/api-key/list", method: "GET", metadata: Routes.openapi_for(:list_api_keys)) 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])
+            configs = query[:config_id] ? [BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, query[:config_id])] : storage_groups(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))) }
+            pushed = database_paginated_records(ctx, configs.first, reference_id, expected_reference, query, limit, offset)
+            if pushed
+              records = pushed.fetch(:records)
+              total = pushed.fetch(:total)
+            else
+              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])
+              records = records.drop(offset) if offset
+              records = records.first(limit) if limit
+            end
+            cleanup_config = query[:config_id] ? configs.first : config
+            BetterAuth::Plugins.api_key_delete_expired(ctx.context, cleanup_config)
             migration_records = records.select { |record| BetterAuth::APIKey::Adapter.legacy_metadata_migration_needed?(record) }
             if migration_records.any?
               BetterAuth::APIKey::Utils.run_background_task(
@@ -50,6 +57,62 @@ module BetterAuth
             ctx.json({apiKeys: api_keys, total: total, limit: limit, offset: offset})
           end
         end
+
+        def storage_groups(configurations)
+          seen = {}
+          configurations.each_with_object([]) do |entry, groups|
+            key = storage_identifier(entry)
+            next if seen[key]
+
+            seen[key] = true
+            groups << entry
+          end
+        end
+
+        def storage_identifier(config)
+          return "database" if config[:storage].to_s == "database"
+          return "custom:#{config[:config_id] || "default"}" if config[:custom_storage]
+
+          config[:fallback_to_database] ? "secondary-storage-with-fallback" : "secondary-storage"
+        end
+
+        def database_paginated_records(ctx, config, reference_id, expected_reference, query, limit, offset)
+          return nil unless query[:config_id] && config
+          return nil unless config[:storage].to_s == "database"
+          return nil if BetterAuth::APIKey::Routes.default_config_id?(query[:config_id])
+          return nil unless config[:references].to_s == expected_reference
+          return nil if expected_reference == "user" && legacy_user_id_records?(ctx, reference_id, query[:config_id])
+
+          where = [
+            {field: "referenceId", value: reference_id},
+            {field: "configId", value: query[:config_id]}
+          ]
+          sort_by = query[:sort_by] ? {field: query[:sort_by].to_s, direction: (query[:sort_direction] || "asc").to_s} : nil
+          {
+            records: ctx.context.adapter.find_many(
+              model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+              where: where,
+              sort_by: sort_by,
+              limit: limit,
+              offset: offset
+            ),
+            total: ctx.context.adapter.count(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: where)
+          }
+        end
+
+        def legacy_user_id_records?(ctx, reference_id, config_id)
+          where = [
+            {field: "userId", value: reference_id},
+            {field: "configId", value: config_id}
+          ]
+          ctx.context.adapter.count(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: where).positive?
+        rescue KeyError, NoMethodError
+          false
+        rescue BetterAuth::Error => error
+          raise unless error.message.include?("Field userId not found")
+
+          false
+        end
       end
     end
   end

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

@@ -4,15 +4,19 @@ module BetterAuth
   module APIKey
     module Routes
       module UpdateAPIKey
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/update-api-key.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(path: "/api-key/update", method: "POST", metadata: Routes.openapi_for(:update_api_key)) 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)
+            # Updates must not authorize from a stale cookie-cache session.
+            session = BetterAuth::Routes.current_session(ctx, allow_nil: true, sensitive: true)
+            if !session && BetterAuth::Plugins.api_key_auth_required?(ctx)
+              raise BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"])
+            end
             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"]
@@ -34,6 +38,13 @@ module BetterAuth
             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)
+            unless updated
+              raise BetterAuth::APIError.new(
+                "INTERNAL_SERVER_ERROR",
+                message: BetterAuth::Plugins::API_KEY_ERROR_CODES["FAILED_TO_UPDATE_API_KEY"],
+                code: "FAILED_TO_UPDATE_API_KEY"
+              )
+            end
             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))

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

@@ -4,39 +4,71 @@ module BetterAuth
   module APIKey
     module Routes
       module VerifyAPIKey
-        UPSTREAM_SOURCE = "upstream/packages/api-key/src/routes/verify-api-key.ts"
+        UPSTREAM_SOURCE = "reference/upstream-src/1.6.9/repository/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|
+          BetterAuth::Endpoint.new(
+            path: "/api-key/verify",
+            method: "POST",
+            body_schema: ->(value) { value },
+            metadata: Routes.openapi_for(:verify_api_key)
+          ) 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",
+                "UNAUTHORIZED",
                 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})
+            validation_config = body[:config_id] ? resolved_config : config_for_key(ctx, key, config)
+            validation_config ||= resolved_config
+            validator = validation_config[:custom_api_key_validator]
+            if validator.respond_to?(:call) && !validator.call({ctx: ctx, key: key})
+              raise BetterAuth::APIError.new(
+                "UNAUTHORIZED",
+                message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"],
+                code: "KEY_NOT_FOUND"
+              )
             else
-              record = BetterAuth::Plugins.api_key_validate!(ctx, key, resolved_config, permissions: body[:permissions])
+              record = BetterAuth::Plugins.api_key_validate!(ctx, key, validation_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})
+            payload = BetterAuth::Plugins.api_key_error_payload(error)
+            payload[:code] = error.code if error.code == "KEY_NOT_FOUND"
+            ctx.json(
+              {valid: false, error: payload, key: nil},
+              status: error.status_code,
+              headers: error.headers
+            )
           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
+
+        def config_for_key(ctx, key, config)
+          config.fetch(:configurations, [config]).each do |entry|
+            hashed = BetterAuth::Plugins.api_key_hash(key, entry)
+            record = BetterAuth::Plugins.api_key_find_by_hash(ctx, hashed, entry)
+            next unless record
+
+            record_config_id = BetterAuth::Plugins.api_key_record_config_id(record)
+            return entry if BetterAuth::Plugins.api_key_config_id_matches?(record_config_id, entry[:config_id])
+
+            return BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, record_config_id)
+          end
+          nil
+        end
       end
     end
   end

data/lib/better_auth/api_key/schema.rb

@@ -8,6 +8,7 @@ module BetterAuth
       def schema(config, custom_schema = nil)
         base = {
           apikey: {
+            model_name: "api_keys",
             fields: {
               configId: {type: "string", required: true, default_value: "default", index: true},
               name: {type: "string", required: false},

data/lib/better_auth/api_key/validation.rb

@@ -24,6 +24,9 @@ module BetterAuth
           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.key?(:refill_amount) && !body[:refill_amount].nil? && body[:refill_amount].to_i < 1
+          raise BetterAuth::APIError.new("BAD_REQUEST", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_REMAINING"])
+        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)
@@ -69,63 +72,258 @@ module BetterAuth
       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
+
+        # In fallback mode the database is authoritative. A cache hit must be
+        # re-read so revocation, expiry, permission, and counter updates cannot
+        # be hidden by a stale secondary snapshot.
+        if record && config[:storage] == "secondary-storage" && config[:fallback_to_database]
+          authoritative = ctx.context.adapter.find_one(
+            model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+            where: [{field: "key", value: hashed}]
+          )
+          unless authoritative
+            BetterAuth::APIKey::Adapter.delete(ctx, record, config)
+            record = nil
+          end
+          record = authoritative if authoritative
+        end
+
+        raise invalid_api_key_error unless record
+        # Adapters are expected to return row snapshots. The in-memory test
+        # adapter exposes its backing hash directly, so copy the top-level row
+        # before evaluating guards to avoid one request mutating another's
+        # decision snapshot.
+        record = record.dup
         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"])
+          raise invalid_api_key_error
         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
+        if record["expiresAt"] && BetterAuth::APIKey::Utils.normalize_time(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"])
+        # Keep an exhausted row inert until an explicit cleanup pass. Eager
+        # deletion here can race a concurrent winner between its guarded quota
+        # decrement and final row refresh, causing a valid request to observe a
+        # missing row. The database remains authoritative and the next request
+        # is still rejected with USAGE_EXCEEDED.
+        if record["remaining"].to_i <= 0 && !record["remaining"].nil? && record["refillAmount"].to_i <= 0
+          raise usage_exceeded_error
         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)
+        updated = if config[:storage] == "database" || config[:fallback_to_database]
+          claim_usage_in_database(ctx, record, config)
+        else
+          warn_best_effort_secondary(ctx, config)
+          claim_usage_in_secondary(ctx, record, config, hashed)
+        end
+
+        BetterAuth::APIKey::Adapter.migrate_legacy_metadata(ctx, updated, config)
       end
 
-      def usage_update(record, config)
+      def claim_usage_in_database(ctx, record, config)
+        row = record
+        row = consume_remaining_database(ctx, row) unless row["remaining"].nil?
+        row = consume_rate_limit_database(ctx, row, config)
+
+        final_row = ctx.context.adapter.update(
+          model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+          where: [{field: "id", value: row["id"]}],
+          update: {updatedAt: Time.now}
+        )
+        unless final_row
+          if ctx.context.adapter.find_one(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: row["id"]}])
+            raise BetterAuth::APIError.new(
+              "INTERNAL_SERVER_ERROR",
+              message: BetterAuth::Plugins::API_KEY_ERROR_CODES["FAILED_TO_UPDATE_API_KEY"],
+              code: "FAILED_TO_UPDATE_API_KEY"
+            )
+          end
+          BetterAuth::APIKey::Adapter.delete(ctx, record, config)
+          raise invalid_api_key_error
+        end
+
+        if config[:storage] == "secondary-storage"
+          BetterAuth::APIKey::Adapter.set(ctx, final_row, config)
+          # A delete can commit after the counter update but before this cache
+          # publication. Re-check after publishing so that interleaving cannot
+          # leave a non-expiring ghost entry behind.
+          authoritative = ctx.context.adapter.find_one(
+            model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+            where: [{field: "id", value: final_row["id"]}]
+          )
+          unless authoritative
+            BetterAuth::APIKey::Adapter.delete(ctx, final_row, config)
+            raise invalid_api_key_error
+          end
+        end
+        final_row
+      end
+
+      def consume_remaining_database(ctx, record)
         now = Time.now
-        update = {lastRequest: now, updatedAt: now}
+        refill_interval = record["refillInterval"]
+        refill_amount = record["refillAmount"]
+        if refill_interval && refill_amount.to_i.positive?
+          last_refill = BetterAuth::APIKey::Utils.normalize_time(record["lastRefillAt"] || record["createdAt"])
+          if last_refill && ((now - last_refill) * 1000) > refill_interval.to_i
+            refilled = ctx.context.adapter.increment_one(
+              model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+              where: [
+                {field: "id", value: record["id"]},
+                {field: "lastRefillAt", value: record["lastRefillAt"]}
+              ],
+              increment: {},
+              set: {remaining: refill_amount.to_i - 1, lastRefillAt: now},
+              allow_server_managed: true
+            )
+            return refilled if refilled
+          end
+        end
 
-        if (try_again_in = BetterAuth::APIKey::RateLimit.try_again_in(record, config, now))
+        decremented = ctx.context.adapter.increment_one(
+          model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+          where: [{field: "id", value: record["id"]}, {field: "remaining", operator: "gt", value: 0}],
+          increment: {remaining: -1},
+          allow_server_managed: true
+        )
+        return decremented if decremented
+
+        raise usage_exceeded_error
+      end
+
+      def consume_rate_limit_database(ctx, record, config)
+        now = Time.now
+        decision = BetterAuth::APIKey::RateLimit.evaluate(record, config, now)
+        if decision[:type] == :deny
           raise BetterAuth::APIError.new(
-            "UNAUTHORIZED",
-            message: BetterAuth::Plugins::API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+            "TOO_MANY_REQUESTS",
+            message: decision[:message],
             code: "RATE_LIMITED",
             body: {
-              message: BetterAuth::Plugins::API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+              message: decision[:message],
               code: "RATE_LIMITED",
-              details: {tryAgainIn: try_again_in}
+              details: {tryAgainIn: decision[:try_again_in]}
             }
           )
         end
-        update[:requestCount] = BetterAuth::APIKey::RateLimit.next_request_count(record, now) if BetterAuth::APIKey::RateLimit.counts_requests?(record, config)
+
+        case decision[:type]
+        when :skip
+          return record unless decision[:last_request]
+
+          updated = ctx.context.adapter.update(
+            model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+            where: [{field: "id", value: record["id"]}],
+            update: {lastRequest: decision[:last_request]}
+          )
+          return updated || record
+        when :start, :reset
+          guard = if decision[:type] == :reset
+            {field: "lastRequest", operator: "lte", value: decision[:window_start]}
+          else
+            {field: "lastRequest", value: nil}
+          end
+          started = ctx.context.adapter.increment_one(
+            model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+            where: [{field: "id", value: record["id"]}, guard],
+            increment: {},
+            set: {requestCount: 1, lastRequest: decision[:now]},
+            allow_server_managed: true
+          )
+          return started if started
+        when :increment
+          incremented = ctx.context.adapter.increment_one(
+            model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+            where: [
+              {field: "id", value: record["id"]},
+              {field: "lastRequest", operator: "gt", value: decision[:window_start]},
+              {field: "requestCount", operator: "lt", value: decision[:max]}
+            ],
+            increment: {requestCount: 1},
+            set: {lastRequest: decision[:now]},
+            allow_server_managed: true
+          )
+          return incremented if incremented
+        end
+
+        fresh = ctx.context.adapter.find_one(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}])
+        raise invalid_api_key_error unless fresh
+
+        # One concurrent writer may have opened/reset the window. Re-evaluate
+        # against the fresh row; this recursion is bounded by the finite race.
+        consume_rate_limit_database(ctx, fresh, config)
+      end
+
+      def claim_usage_in_secondary(ctx, record, config, hashed)
+        now = Time.now
+        fresh = BetterAuth::APIKey::Adapter.find_by_hash(ctx, hashed, config)
+        raise invalid_api_key_error unless fresh
+
+        update = usage_update(fresh, config, now)
+        merged = fresh.merge(update.transform_keys { |key_name| BetterAuth::Schema.storage_key(key_name) })
+        BetterAuth::APIKey::Adapter.set(ctx, merged, config)
+        merged
+      end
+
+      def usage_update(record, config, now = Time.now)
+        update = {lastRequest: now, updatedAt: now}
+        decision = BetterAuth::APIKey::RateLimit.evaluate(record, config, now)
+        if decision[:type] == :deny
+          raise BetterAuth::APIError.new(
+            "TOO_MANY_REQUESTS",
+            message: decision[:message],
+            code: "RATE_LIMITED",
+            body: {message: decision[:message], code: "RATE_LIMITED", details: {tryAgainIn: decision[:try_again_in]}}
+          )
+        end
+        case decision[:type]
+        when :start, :reset
+          update[:requestCount] = 1
+        when :increment
+          update[:requestCount] = record["requestCount"].to_i + 1
+        when :skip
+          update[:lastRequest] = decision[:last_request] if decision[:last_request]
+        end
 
         remaining = record["remaining"]
         if !remaining.nil?
-          if remaining.to_i <= 0 && record["refillAmount"] && record["refillInterval"]
+          if remaining.to_i <= 0 && record["refillAmount"].to_i.positive? && 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
+          raise usage_exceeded_error if remaining.to_i <= 0
 
           update[:remaining] = remaining.to_i - 1
         end
         update
       end
 
+      def invalid_api_key_error
+        BetterAuth::APIError.new("UNAUTHORIZED", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["INVALID_API_KEY"])
+      end
+
+      def usage_exceeded_error
+        BetterAuth::APIError.new("TOO_MANY_REQUESTS", message: BetterAuth::Plugins::API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
+      end
+
+      def warn_best_effort_secondary(ctx, config)
+        return if config[:storage] != "secondary-storage" || config[:fallback_to_database]
+        return if ctx.context.respond_to?(:runtime_fetch) && ctx.context.runtime_fetch(:api_key_secondary_warning, false)
+
+        logger = ctx.context.logger if ctx.context.respond_to?(:logger)
+        logger.warn("[API KEY PLUGIN] Secondary-storage-only API-key counters are best-effort; use fallback_to_database for atomic enforcement.") if logger.respond_to?(:warn)
+        ctx.context.runtime_store(:api_key_secondary_warning, true) if ctx.context.respond_to?(:runtime_store)
+      end
+
       def check_permissions!(record, required)
         return if required.nil? || required == {}
 
+        BetterAuth::Plugins.load_plugin!(:access)
         actual = BetterAuth::APIKey::Utils.decode_json(record["permissions"]) || {}
         result = BetterAuth::Plugins::Role.new(actual).authorize(required)
         unless result[:success]

data/lib/better_auth/api_key/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module APIKey
-    VERSION = "0.8.0"
+    VERSION = "0.11.0"
   end
 end

data/lib/better_auth/plugins/api_key.rb

@@ -43,6 +43,8 @@ module BetterAuth
       BetterAuth::APIKey::PluginFactory.build(configurations, options)
     end
 
+    API_KEY_PLUGIN_IMPLEMENTATION = true
+
     def api_key_config(configurations, options = nil)
       BetterAuth::APIKey::Configuration.normalize(configurations, options)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-api-key
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: better_auth-mongodb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: better_auth-redis-storage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +121,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.83'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.83'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: standardrb
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +177,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tiny_tds
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 description: Adds API key creation, verification, management, quotas, metadata, and
   permissions for Better Auth Ruby. Includes storage modes. Also supports API-key-backed
   sessions. Better Auth Ruby is an independent modern authentication framework for
@@ -90,6 +202,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- LICENSE.md
 - README.md
 - lib/better_auth/api_key.rb
 - lib/better_auth/api_key/adapter.rb
@@ -114,14 +227,14 @@ files:
 - lib/better_auth/api_key/validation.rb
 - lib/better_auth/api_key/version.rb
 - lib/better_auth/plugins/api_key.rb
-homepage: https://github.com/sebasxsala/better-auth
+homepage: https://github.com/sebasxsala/better-auth-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sebasxsala/better-auth
-  source_code_uri: https://github.com/sebasxsala/better-auth
-  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-api-key/CHANGELOG.md
-  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-api-key/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
 rdoc_options: []
 require_paths:
 - lib