better_auth-api-key 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0644878a04c3b9f3489304b324a9636aed5411eefc8b8f51ec89f15a5b978cf1'
-  data.tar.gz: fc6aa4568b7831ec89a1fbab0abd5191b0d27bf5f5afc84615c038748dce9bd0
+  metadata.gz: e054d9e429e2c199d594467dcc924a9ef44c22c0be63f96e240f47308e4444ef
+  data.tar.gz: d34741924ce2951654646c1127f0d3caa09d16cd765f58647220ff6c71221e57
 SHA512:
-  metadata.gz: 2790364cbe835dd0c368aa9a035a57653370ab5d7f06c13fe1967ef04442a1cf3554a61056c920d80d0834ba9fd1c4963206ba46cb9b5f2bea77d46bcef59f42
-  data.tar.gz: 170f42d1487f231cb0302a63cd26e90d72f0560f0c0cc9ad5cbb05a7863d842c70517699432afa800c9070a6d1cbbf44e924dfca361972568a0dddae8759cfd8
+  metadata.gz: b8220f1cc0645105e0666c7d8184d43c72bb4e050094f4aa6cfb411b61f0622e2b0c2c4c21d50b7c586b82a80d96b7855c36b6e93b0dbbb94db2d87fd0456f2d
+  data.tar.gz: 5c1d00a8dc01502bc6709d0419195548eec8ad816846f9be05f58a3fa8c477305df53ba3722344f268b223b19b7e4ededd4bd138d1c1eca36a060c42872f6e02

data/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## 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.

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
 
@@ -197,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,7 +4,7 @@ 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
 
@@ -12,7 +12,10 @@ module BetterAuth
           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

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

@@ -4,7 +4,7 @@ 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
 

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

@@ -4,7 +4,7 @@ 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
 

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

@@ -4,7 +4,7 @@ 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
 

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

@@ -98,6 +98,14 @@ module BetterAuth
       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",
@@ -114,15 +122,10 @@ module BetterAuth
             responses: {
               "200" => BetterAuth::OpenAPI.json_response(
                 "API key verification result",
-                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"]
-                )
-              )
+                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)
             }
           }
         }

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

@@ -4,7 +4,7 @@ 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
 

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

@@ -4,7 +4,7 @@ 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
 
@@ -12,7 +12,8 @@ module BetterAuth
           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

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

@@ -4,7 +4,7 @@ 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
 
@@ -20,7 +20,7 @@ module BetterAuth
             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"
               )
@@ -30,7 +30,11 @@ module BetterAuth
             validation_config ||= resolved_config
             validator = validation_config[:custom_api_key_validator]
             if validator.respond_to?(:call) && !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})
+              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, validation_config, permissions: body[:permissions])
               record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
@@ -39,7 +43,13 @@ module BetterAuth
             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})

data/lib/better_auth/api_key/validation.rb

@@ -5,13 +5,6 @@ module BetterAuth
     module Validation
       module_function
 
-      USAGE_LOCK_STRIPE_COUNT = 256
-
-      def usage_lock_for(key)
-        @usage_lock_stripes ||= Array.new(USAGE_LOCK_STRIPE_COUNT) { Mutex.new }
-        @usage_lock_stripes[key.hash % USAGE_LOCK_STRIPE_COUNT]
-      end
-
       def validate_create_update!(body, config, create:, client:)
         name = body[:name]
         if create && config[:require_name] && name.to_s.empty?
@@ -31,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)
@@ -75,73 +71,259 @@ module BetterAuth
 
       def validate_api_key!(ctx, key, config, permissions: nil)
         hashed = BetterAuth::APIKey::Keys.hash(key, config)
-        usage_lock_for(hashed).synchronize do
-          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"])
+        record = BetterAuth::APIKey::Adapter.find_by_hash(ctx, hashed, config)
+
+        # 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 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"] && 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
+        # 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)
+        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
 
-          check_permissions!(record, permissions)
-          update = usage_update(record, config)
-          updated = BetterAuth::APIKey::Adapter.update_record(ctx, record, update, config, defer: false)
-          unless updated
+        BetterAuth::APIKey::Adapter.migrate_legacy_metadata(ctx, updated, config)
+      end
+
+      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.migrate_legacy_metadata(ctx, updated || record.merge(update.transform_keys { |key_name| BetterAuth::Schema.storage_key(key_name) }), config)
+          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 usage_update(record, config)
+      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
+
+        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
 
-        if (try_again_in = BetterAuth::APIKey::RateLimit.try_again_in(record, config, now))
+      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.10.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.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -202,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