api_keys 0.5.0 → 0.6.0

data/docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md

@@ -0,0 +1,36 @@
+# Security review of the 0.6.0 branch (Codex Astra, 2026-10-18, at 720e401, PR #66)
+
+Scope: `git diff origin/main..720e401` on the 0.5.1 main: ceiling-authoritative scopes (#28), refused-traffic stats (#38), the durable one-time handoff (`token_shown_at`), `ApiKey#scopes_after_form_edit`, migrations and docs, read-only, under the 0.5.0 threat model. Verdict: BLOCK on the durable handoff claim being undone by a host transaction that rolls back after the plaintext was released; four should-fixes (creation form still offers scope boxes for ceiling types; stats debouncing does not bound pending jobs; the retrieval result's inspect printed the token; reconciliation did not recheck revocation inside the lock) and two nits. All were applied in the next commits; see the disposition at the end.
+
+## Blocking
+
+- **The durable handoff can be rolled back after releasing the token.** The claim uses the caller’s database connection without ensuring its transaction has committed, and retrieval immediately returns the plaintext. Calling retrieval inside a transaction that subsequently rolls back restores `token_shown_at = NULL`. Verified in memory with `NullStore`: retrieval → rollback → copied-session replay returned the same token twice. A host controller wrapping display in a transaction can therefore violate the advertised guarantee. Fail closed inside an existing transaction, or ensure consumption commits independently before releasing plaintext. The unconditional durability claims must also be corrected. [api_key.rb:601](lib/api_keys/models/api_key.rb:601), [token_session.rb:167](lib/api_keys/helpers/token_session.rb:167), [README.md:514](README.md:514)
+
+## Should fix
+
+- **The creation form still offers ineffective scope checkboxes for ceiling types.** Only the persisted-key form suppresses them; the creation form always offers owner scopes, and its JavaScript handles restrictions and expiration only. An owner can clear every permission yet create a key authorized for the entire ceiling. Hide/disable those controls and display the live contract when selecting a ceiling type. Recommending `scopes: :ceiling` for publishable keys is appropriate under the initializer’s stated “users do not pick scopes” condition, but this form contradicts that condition. [_form.html.erb:73](app/views/api_keys/keys/_form.html.erb:73), [_form.html.erb:182](app/views/api_keys/keys/_form.html.erb:182), [initializer.rb:156](lib/generators/api_keys/templates/initializer.rb:156)
+
+- **Refusal debouncing does not bound pending jobs.** It checks only the persisted timestamp; enqueueing reserves nothing. With counting disabled and a one-minute interval, 100 requests carrying a revoked token queued 100 refusal jobs before worker execution. Prefix/last-four knowledge alone cannot stamp a key: verification checks the full token, and forged requests queued no stats jobs. Document the pending-job limitation and consider atomic enqueue deduplication; successful-use debouncing has the same limitation. [authentication.rb:172](lib/api_keys/authentication.rb:172), [authenticator.rb:260](lib/api_keys/services/authenticator.rb:260), [CHANGELOG.md:24](CHANGELOG.md:24)
+
+- **The new retrieval result exposes plaintext through inspection.** `Retrieval` inherits `Struct#inspect`/`to_s`, which includes its token on successful retrieval. Verified directly. Add credential-redacting inspection, consistent with the existing authentication result. The `already_shown` result itself correctly contains no token. [token_session.rb:83](lib/api_keys/helpers/token_session.rb:83), [authenticator.rb:46](lib/api_keys/services/authenticator.rb:46)
+
+- **Reconciliation does not recheck revocation after locking.** Selection filters `revoked_at: nil`, but a revocation between selection and `with_lock` is ignored after the row reloads. Verified that such a key still gains scopes and contributes to the changed count. Recheck eligibility inside the lock. This does not reactivate the key, but violates the documented exclusion of revoked keys. [api_key.rb:649](lib/api_keys/models/api_key.rb:649), [README.md:1312](README.md:1312)
+
+## Nits
+
+- The general statement that empty scopes grant nothing on typed keys needs an explicit ceiling-type exception. Ceiling keys intentionally receive their live permissions even with `scopes: []`. [README.md:889](README.md:889), [api_key.rb:388](lib/api_keys/models/api_key.rb:388)
+- The gem still identifies itself as `0.5.1`; bump it before publishing 0.6.0. The new runtime files are tracked and included by the gemspec. [version.rb:4](lib/api_keys/version.rb:4), [api_keys.gemspec:29](api_keys.gemspec:29)
+
+## Missing tests
+
+- **Committed, independent-connection handoff races and rollback replay.** The concurrent tests pin all threads to one SQLite connection and explicitly roll the transaction back afterward. They do not establish durability or independent-connection behavior across SQLite, PostgreSQL, and MySQL. Add those races with `NullStore`, followed by replay after commit/cache loss, plus the rollback regression above. [token_session_test.rb:40](test/helpers/token_session_test.rb:40)
+- **Refusal bursts before worker execution.** Current debounce coverage pre-populates `last_refused_at`; it misses pending-job amplification. Also exercise the forged-prefix/last-four refusal test with bcrypt, since the current test uses the default hashing configuration. [refusal_stats_test.rb:204](test/refusal_stats_test.rb:204), [refusal_stats_test.rb:176](test/refusal_stats_test.rb:176)
+
+VERDICT: BLOCK
+
+0.6.0 should not be published with its current unconditional durable-handoff guarantee: transaction rollback demonstrably permits a second release. Resolve that blocker and add the regression coverage before release. This review covered the full diff and used isolated in-memory checks without repository changes; the full suite was not run. Both requested GitHub issue fetches failed, and the two referenced `.cursor/rules` files were absent, so those sources could not be reviewed.
+## Disposition (lead)
+
+Applied in the six commits that followed (3a9b044 to 45afec4): the handoff claim is not trusted inside an open transaction (with a real cache the marker carries the guarantee; with none the token is withheld as `:inside_transaction`, nothing is recorded and the handoff stays for a retry outside the transaction; the dashboard opens no transaction; README, SECURITY.md and CHANGELOG corrected; the rollback replay tests and an 8-thread independent-connection race on a file-backed SQLite database); the creation form hides and disables scope boxes for a ceiling type and create ignores submitted scopes for it; success and refusal enqueues are deduplicated per key and kind with an atomic cache write when a real cache exists, documented otherwise; the retrieval result redacts the token in every representation; reconciliation rechecks revocation and type inside the lock; the README names the ceiling-type exception. Not available here: PostgreSQL and MySQL races (SQLite only). The version bump is the release step.
+
+Superseded in round 2: a retrieval inside an open transaction is now refused whatever the cache (a process-local cache could not stop another process after a rollback), and the README no longer says the dashboard always retrieves outside transactions, since its controller inherits the host's.

data/docs/reviews/2026-10-18-0-6-0/02-astra-re-review-of-0-6-0.md

@@ -0,0 +1,34 @@
+# Re-review of the 0.6.0 fixes, round 2 (Codex Astra, 2026-10-18, at fe28e9c, PR #66)
+
+Scope: `git diff 720e401..fe28e9c`, the six fixes answering review 01, read-only. Verdict: BLOCK on the handoff still releasing the plaintext inside a transaction whenever any non-NullStore cache was present (a process-local MemoryStore included), plus two should-fixes on the enqueue deduplication (a cache write answering nil treated as an existing reservation; a false `perform_later` not releasing the reservation) and docs nits. All applied in the five commits that followed (ab89492 to 497879e): retrieval inside any open Active Record transaction on the ApiKey pool is refused whatever the cache; suppression only on a confirmed reservation; release on a false enqueue; Solid Cache qualified in the stats section; the listed tests added. See 03.
+
+## Blocking
+
+- **Durable handoff: partially fixed, still open.** NullStore retrieval inside an Active Record transaction now withholds plaintext and preserves the handoff; the rollback tests genuinely exercise that scenario. But any non-NullStore cache enables release before commit—including process-local `MemoryStore`. After rollback, another process can release the token again without any cache flush. The new cache-loss test explicitly expects two releases. Documenting this limitation does not implement the requested fail-closed or independently committed consumption. Withhold inside transactions regardless of cache, or commit consumption independently. [token_session.rb:312](lib/api_keys/helpers/token_session.rb:312), [token_session.rb:395](lib/api_keys/helpers/token_session.rb:395), [token_session_test.rb:351](test/helpers/token_session_test.rb:351), [token_session_test.rb:420](test/helpers/token_session_test.rb:420)
+
+## Should fix
+
+- **Enqueue deduplication: partially closed, with a new failure mode.** Reservations address pending bursts when the cache supports atomic conditional writes. However, nil/false writes are treated as existing reservations, suppressing statistics even when nothing was reserved. Only exceptions trigger fallback. The failing-cache test raises `IOError`, so it misses this case; locally inspected RedisCacheStore returns nil for handled write failures. Check reservation presence before suppressing, and enqueue when reservation status is unavailable. [authentication.rb:234](lib/api_keys/authentication.rb:234), [refusal_stats_test.rb:289](test/refusal_stats_test.rb:289), [redis_cache_store.rb:397](rails source)
+
+- **Failed enqueues can retain reservations.** Both paths release only on exceptions, ignoring `perform_later` returning false. Active Job can return false after an enqueue error, suppressing subsequent attempts until expiration. The new tests cover raised exceptions only. [authentication.rb:160](lib/api_keys/authentication.rb:160), [authentication.rb:191](lib/api_keys/authentication.rb:191), [refusal_stats_test.rb:310](test/refusal_stats_test.rb:310), [enqueuing.rb:82](rails source)
+
+- **Creation form: closed in the inspected implementation.** JavaScript hides/disables scope controls and displays the selected ceiling. Server-side creation replaces submitted scopes with that ceiling, resolving omitted types through the configured default. Tests genuinely POST cleared, narrower, excessive, and ordinary-type scopes. No new authorization defect found; the rendering test does not execute selection changes. [keys_controller.rb:78](app/controllers/api_keys/keys_controller.rb:78), [keys_controller.rb:317](app/controllers/api_keys/keys_controller.rb:317), [_form.html.erb:230](app/views/api_keys/keys/_form.html.erb:230), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774)
+
+- **Retrieval inspection: closed.** Inspection, string conversion, pretty-printing, and JSON redact plaintext. The test obtains a successful retrieval and exercises those representations, including nested inspection. No new defect found in this change. [token_session.rb:111](lib/api_keys/helpers/token_session.rb:111), [token_session_test.rb:733](test/helpers/token_session_test.rb:733)
+
+- **Reconcile eligibility: closed.** Revocation and type are rechecked after the locked reload. The test performs a real database update after selection but before locking, leaving the selected object stale; it verifies unchanged scopes and exclusion from the count. This is a valid controlled interleaving, though not another connection. No new defect found. [api_key.rb:650](lib/api_keys/models/api_key.rb:650), [reconcile_scopes_test.rb:13](test/reconcile_scopes_test.rb:13), [reconcile_scopes_test.rb:48](test/reconcile_scopes_test.rb:48)
+
+## Nits
+
+- **Empty-scope wording: closed. Version bump: outstanding.** The ceiling exception is explicit; the gem still identifies as `0.5.1`. [README.md:890](README.md:890), [version.rb:4](lib/api_keys/version.rb:4)
+- **Documentation still overstates guarantees.** “The dashboard always” retrieves outside transactions is unsupported because its controller inherits the host controller. The stats section also promises atomic deduplication with Solid Cache while the handoff section describes its non-atomic absent-entry behavior. Qualify both, and update the filed disposition accordingly. [README.md:514](README.md:514), [application_controller.rb:10](app/controllers/api_keys/application_controller.rb:10), [README.md:1162](README.md:1162), [README.md:520](README.md:520), [review trace:34](docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md:34)
+
+## Missing tests
+
+- **Handoff coverage improved materially, but remains SQLite-only.** The file-backed test uses autocommit pool connections, NullStore, and post-race replay against the committed marker. Its gate precedes checkout, so it does not guarantee distinct simultaneous connections; it also accepts any nil-producing loser. Add a barrier after checkout, assert loser statuses, and cover PostgreSQL/MySQL. [token_session_test.rb:71](test/helpers/token_session_test.rb:71), [token_session_test.rb:318](test/helpers/token_session_test.rb:318)
+- **Transaction-check boundaries remain untested.** It correctly checks the ApiKey pool, avoiding unrelated-pool false positives; lazy transactions and savepoints legitimately count. Its boundary is Active Record’s transaction manager: raw SQL `BEGIN` is not detected. Add separate-pool and nested-transaction coverage, and document that boundary. [token_session.rb:299](lib/api_keys/helpers/token_session.rb:299), [database_statements.rb:398](rails source)
+- **Original burst and bcrypt gaps: closed by meaningful scenarios.** Bursts enqueue before workers execute; bcrypt forgery preserves prefix/last-four while changing the secret. Still missing: non-raising cache/enqueue failures, browser type-switch execution, default-ceiling POST with omitted scopes/type, and reconciliation after retyping. [refusal_stats_test.rb:192](test/refusal_stats_test.rb:192), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774), [reconcile_scopes_test.rb:48](test/reconcile_scopes_test.rb:48)
+
+VERDICT: BLOCK
+
+0.6.0 is not ready to publish: transactional token release remains replayable, and enqueue deduplication introduces silent statistics loss on non-raising failures. The form, redaction, reconciliation, and empty-scope fixes close their original findings. I read the entire delta through `fe28e9c` and checked every touched area; this was a static review, with no tests executed or repository changes. Both requested `.cursor/rules` files remain absent.

data/docs/reviews/2026-10-18-0-6-0/03-sol-re-check-of-0-6-0.md

@@ -0,0 +1,41 @@
+# Re-check of the 0.6.0 fixes, round 3 (Codex Sol, 2026-10-18, at 497879e, PR #66)
+
+Scope: `git diff fe28e9c..497879e`, the answer to review 02, read-only. Verdict: PASS; the two small items (a README sentence that still said every retrieval attempt uses the handoff up; two transaction-boundary tests that did not create the state they named) were applied in the next commit. Open by nature of the environment: PostgreSQL and MySQL races, and a browser test of switching the key type.
+
+## Blocking
+
+- **Durable handoff: closed for Active Record transactions.** The guard checks the **ApiKey pool’s current connection**, before either consumption write, regardless of cache. An unconsumed handoff returns `:inside_transaction` and is restored; a previously committed claim returns `:already_shown` and stays removed. Commit, rollback, cache replacement and cache-flush tests meaningfully exercise those paths. Cache replacement simulates another process; it does not launch one. [token_session.rb:186](lib/api_keys/helpers/token_session.rb:186), [token_session.rb:286](lib/api_keys/helpers/token_session.rb:286), [token_session_test.rb:353](test/helpers/token_session_test.rb:353), [token_session_test.rb:382](test/helpers/token_session_test.rb:382), [token_session_test.rb:499](test/helpers/token_session_test.rb:499)
+
+- **Compatibility boundary: verified.** Without the column, or without a named key, transaction refusal is bypassed and the cache-only behavior remains. The unmigrated transaction test genuinely drops the column. Raw SQL `BEGIN` remains undetected; its test actually releases plaintext and then rolls back the claim. That limitation is now explicit. [token_session.rb:302](lib/api_keys/helpers/token_session.rb:302), [token_session_test.rb:484](test/helpers/token_session_test.rb:484), [token_session_test.rb:514](test/helpers/token_session_test.rb:514), [README.md:517](README.md:517)
+
+## Should fix
+
+- **Non-raising cache-write failures: closed.** Suppression requires both `written == false` and a present reservation. Nil, absent entries and exceptions enqueue. The added tests exercise nil writes, false writes without storage, and failing existence checks through both successful and refused authentication. Existing burst tests exercise genuine suppression before workers run. [authentication.rb:243](lib/api_keys/authentication.rb:243), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [refusal_stats_test.rb:303](test/refusal_stats_test.rb:303)
+
+- **False enqueue results: closed with a working cache.** Both paths release reservations on false results and exceptions. The four-call expectation genuinely requires another attempt for each kind after its first false result. Cleanup remains best effort: a failed cache deletion can retain the reservation until expiry, because false deletion results are ignored and exceptions swallowed. The enqueue failure itself is logged. [authentication.rb:162](lib/api_keys/authentication.rb:162), [authentication.rb:198](lib/api_keys/authentication.rb:198), [authentication.rb:262](lib/api_keys/authentication.rb:262), [refusal_stats_test.rb:359](test/refusal_stats_test.rb:359)
+
+- **Creation form: remains closed.** Server-side creation resolves the default type and replaces submitted ceiling scopes. The new test genuinely POSTs with **both type and scopes omitted**, then with omitted type and crafted scopes. [keys_controller.rb:79](app/controllers/api_keys/keys_controller.rb:79), [keys_controller_test.rb:826](test/controllers/keys_controller_test.rb:826)
+
+- **Retrieval inspection: remains closed.** The test obtains plaintext successfully before checking string, inspection, nested inspection, pretty-print and JSON representations. [token_session_test.rb:782](test/helpers/token_session_test.rb:782)
+
+- **Reconciliation eligibility: remains closed.** The new retyping test updates the database after selection and before `with_lock` reloads the stale object, then checks unchanged scopes and exclusion from the count. This is a meaningful controlled interleaving on one connection. [reconcile_scopes_test.rb:13](test/reconcile_scopes_test.rb:13), [reconcile_scopes_test.rb:62](test/reconcile_scopes_test.rb:62), [api_key.rb:650](lib/api_keys/models/api_key.rb:650)
+
+## Nits
+
+- **Solid Cache documentation: closed.** The stats section now distinguishes conditional writes from atomic absent-entry reservation and explicitly permits simultaneous extra jobs on Solid Cache/PostgreSQL. Cache failures still intentionally permit one job per request before timestamp persistence. [README.md:1162](README.md:1162), [CHANGELOG.md:26](CHANGELOG.md:26)
+
+- **Transaction documentation: substantially closed.** README, SECURITY and CHANGELOG acknowledge host controller transactions and raw SQL boundaries; the filed disposition explicitly supersedes the earlier cache-dependent answer. One remaining inconsistency: “Any retrieval attempt uses the handoff up” contradicts the new retry-preserving status. Qualify it. [README.md:489](README.md:489), [SECURITY.md:49](SECURITY.md:49), [CHANGELOG.md:29](CHANGELOG.md:29), [review trace:36](docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md:36)
+
+- **Empty-scope wording: closed. Version bump: outstanding.** The ceiling exception remains explicit; the runtime version remains `0.5.1`. [README.md:890](README.md:890), [version.rb:4](lib/api_keys/version.rb:4)
+
+## Missing tests
+
+- **SQLite races: closed; PostgreSQL/MySQL coverage remains open.** Both races now hold distinct autocommit connections before opening the barrier and require exactly one `:retrieved` plus seven `:already_shown` results. The NullStore race also checks committed state and later replay. [token_session_test.rb:46](test/helpers/token_session_test.rb:46), [token_session_test.rb:77](test/helpers/token_session_test.rb:77), [token_session_test.rb:309](test/helpers/token_session_test.rb:309)
+
+- **Transaction boundaries: partially closed.** Separate-pool and raw-SQL scenarios are real. However, the “non-joinable inner transaction” joins the existing joinable transaction because it omits `requires_new: true`. Also, on the inspected Rails 8.1.4 source, the untouched outer transaction lets the `requires_new` case use `RestartParentTransaction`, so it does not establish a physical savepoint. Add a real non-joinable transaction and dirty the outer transaction before testing a savepoint. The implementation’s `transaction_open?` check itself covers these states. [token_session_test.rb:433](test/helpers/token_session_test.rb:433), [token_session_test.rb:461](test/helpers/token_session_test.rb:461), [token_session_test.rb:465](test/helpers/token_session_test.rb:465), [database_statements.rb:372](rails source), [transaction.rb:538](rails source)
+
+- **Original burst/bcrypt gaps: remain closed. Browser type switching: still unexecuted.** The rendering test inspects markup/configuration and server-rendered defaults; it never executes the change listener. [refusal_stats_test.rb:192](test/refusal_stats_test.rb:192), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774)
+
+VERDICT: PASS
+
+The round-2 release blockers are closed under the documented Active Record transaction boundary. I found no new blocking defect across the complete five-commit delta. The remaining documentation and coverage gaps are nonblocking; bump the version before publishing 0.6.0. This was a static review: no tests executed or repository changes made. Both requested `.cursor/rules` files remain absent.

data/lib/api_keys/authentication.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/cache"
 require "active_support/concern"
 require_relative "services/authenticator"
 require_relative "logging"
@@ -17,6 +18,9 @@ module ApiKeys
     # The key itself is fine, so these answer 403 rather than 401 — the same
     # distinction `:missing_scope` already makes.
     FORBIDDEN_ERROR_CODES = %i[origin_not_allowed ip_not_allowed restriction_misconfigured].freeze
+    # Names the per-key reservation that lets one stats job per kind be
+    # enqueued within a debounce interval (see reserve_stats_enqueue?).
+    STATS_ENQUEUE_NAMESPACE = "api_keys:v1:stats_enqueue"
 
     included do
       # Helper methods to access the authenticated key and its owner
@@ -78,6 +82,7 @@ module ApiKeys
           after_auth_context[:required_scope_check] = { required: scope, passed: false }
           after_auth_context[:success] = false
           after_auth_context[:error_code] = :missing_scope
+          refused_key = @current_api_key
           @current_api_key = nil
           render_unauthorized(
             error_code: :missing_scope,
@@ -85,6 +90,7 @@ module ApiKeys
             status: :forbidden,
             required_scope: scope
           )
+          record_key_refusal(refused_key, :missing_scope)
         else
           after_auth_context[:required_scope_check] = { required: scope, passed: true } if scope
           # Authentication and scope check successful, enqueue stats update
@@ -95,6 +101,8 @@ module ApiKeys
         log_debug "[ApiKeys Auth] Authentication failed. Error: #{result.error_code}, Message: #{result.message}"
         status = FORBIDDEN_ERROR_CODES.include?(result.error_code) ? :forbidden : :unauthorized
         render_unauthorized(error_code: result.error_code, message: result.message, status: status)
+        # Only identified refusals carry a key; lookup failures have none to stamp.
+        record_key_refusal(result.api_key, result.error_code) if result.api_key
       end
 
       # Enqueue after_authentication callback asynchronously regardless of success/failure
@@ -129,10 +137,14 @@ module ApiKeys
       return unless ApiKeys.configuration.enable_async_operations
       return unless current_api_key
 
-      if stats_update_debounced?
+      if stats_update_debounced?(current_api_key.last_used_at)
         log_debug "[ApiKeys Auth] Skipping a recently recorded last-used update for ApiKey ID: #{current_api_key.id}"
         return
       end
+      unless reserve_stats_enqueue?(:used, current_api_key.id)
+        log_debug "[ApiKeys Auth] Skipping a last-used update already enqueued for ApiKey ID: #{current_api_key.id}"
+        return
+      end
 
       # Check ActiveJob configuration and warn if using suboptimal adapters
       adapter = ActiveJob::Base.queue_adapter
@@ -145,22 +157,126 @@ module ApiKeys
       begin
         timestamp = Time.current # Capture time once for the job
         log_debug "[ApiKeys Auth] Enqueuing UpdateStatsJob for ApiKey ID: #{current_api_key.id} at #{timestamp}"
-        ApiKeys::Jobs::UpdateStatsJob.perform_later(current_api_key.id, timestamp)
+        # Active Job answers false (instead of raising) when the adapter
+        # failed to enqueue; either way the reservation is freed.
+        unless ApiKeys::Jobs::UpdateStatsJob.perform_later(current_api_key.id, timestamp)
+          release_stats_enqueue(:used, current_api_key.id)
+          log_error "[ApiKeys Auth] UpdateStatsJob was not enqueued for key #{current_api_key.id}."
+        end
       rescue StandardError => error
+        release_stats_enqueue(:used, current_api_key.id)
         log_error "[ApiKeys Auth] Failed to enqueue UpdateStatsJob for key #{current_api_key.id} (#{error.class})."
       end
     end
 
-    def stats_update_debounced?
+    # Enqueues the refusal half of UpdateStatsJob for a key that presented its
+    # real token and was refused by a policy. It moves only last_refused_at,
+    # last_refusal_code and (with track_requests_count) refusals_count; a
+    # refusal never counts as a use. Debounced exactly like last_used_at, so a
+    # client hammering a refused key costs no more writes than a working one.
+    # Never raises: the refusal response has already been rendered.
+    def record_key_refusal(api_key, error_code)
+      return unless ApiKeys.configuration.enable_async_operations
+      return unless api_key&.id
+
+      code = error_code.to_s
+      return unless ApiKeys::ApiKey::REFUSAL_CODES.include?(code)
+      return unless ApiKeys::ApiKey.refusal_stats_columns?
+
+      if stats_update_debounced?(api_key.last_refused_at)
+        log_debug "[ApiKeys Auth] Skipping a recently recorded refusal update for ApiKey ID: #{api_key.id}"
+        return
+      end
+      unless reserve_stats_enqueue?(:refused, api_key.id)
+        log_debug "[ApiKeys Auth] Skipping a refusal update already enqueued for ApiKey ID: #{api_key.id}"
+        return
+      end
+
+      begin
+        # Active Job answers false (instead of raising) when the adapter
+        # failed to enqueue; either way the reservation is freed.
+        unless ApiKeys::Jobs::UpdateStatsJob.perform_later(api_key.id, Time.current, refusal_code: code)
+          release_stats_enqueue(:refused, api_key.id)
+          log_error "[ApiKeys Auth] A refusal stats update was not enqueued for key #{api_key.id}."
+        end
+      rescue StandardError
+        release_stats_enqueue(:refused, api_key.id)
+        raise
+      end
+    rescue StandardError => error
+      log_error "[ApiKeys Auth] Failed to enqueue a refusal stats update for key #{api_key&.id} (#{error.class})."
+    end
+
+    def stats_update_debounced?(last_recorded_at)
+      seconds = stats_debounce_seconds
+      return false unless seconds && last_recorded_at
+
+      last_recorded_at >= Time.current - seconds
+    end
+
+    # The debounce interval in seconds, or nil when every request must be
+    # recorded (exact counting with track_requests_count, or no interval).
+    def stats_debounce_seconds
       config = ApiKeys.configuration
-      return false if config.track_requests_count
+      return nil if config.track_requests_count
 
       interval = config.stats_update_interval
       seconds = interval.to_f if interval.respond_to?(:to_f)
-      return false unless seconds&.finite? && seconds.positive?
-      return false unless current_api_key.last_used_at
+      seconds&.finite? && seconds.positive? ? seconds : nil
+    end
+
+    # The persisted timestamp only debounces once a worker has written it, so
+    # a burst of requests arriving before that would each enqueue a job. With
+    # a shared cache, the first request in an interval reserves the enqueue
+    # for its key and kind (:used or :refused) atomically, with
+    # `write(..., unless_exist: true, expires_in: interval)`, and the rest of
+    # the burst is skipped.
+    #
+    # A request is skipped only when the reservation is confirmed to exist:
+    # the write answered false (not stored) and the key is then present.
+    # Stores also answer false or nil when the write itself failed (Redis
+    # returns nil on a handled error, Memcached false), and suppressing the
+    # job then would lose statistics silently. So a nil answer, an absent
+    # key, or any error enqueues. It also enqueues when debouncing does not
+    # apply or there is no shared cache (`NullStore`, or no Rails.cache):
+    # the persisted timestamp is then the only debounce, as before 0.6.0.
+    def reserve_stats_enqueue?(kind, api_key_id)
+      seconds = stats_debounce_seconds
+      return true unless seconds
+
+      cache = stats_enqueue_cache
+      return true unless cache
+
+      key = stats_enqueue_key(kind, api_key_id)
+      written = cache.write(key, true, unless_exist: true, expires_in: seconds)
+      return true unless written == false
+
+      cache.exist?(key) ? false : true
+    rescue StandardError => error
+      log_debug "[ApiKeys Auth] Stats enqueue reservation unavailable (#{error.class}); relying on the persisted timestamp."
+      true
+    end
+
+    # Frees a reservation whose job could not be enqueued, so the next
+    # request can try again.
+    def release_stats_enqueue(kind, api_key_id)
+      return unless stats_debounce_seconds
+
+      stats_enqueue_cache&.delete(stats_enqueue_key(kind, api_key_id))
+    rescue StandardError
+      nil
+    end
+
+    def stats_enqueue_key(kind, api_key_id)
+      "#{STATS_ENQUEUE_NAMESPACE}:#{kind}:#{api_key_id}"
+    end
+
+    # A cache every process shares can deduplicate; NullStore remembers nothing.
+    def stats_enqueue_cache
+      cache = Rails.cache if defined?(Rails) && Rails.respond_to?(:cache)
+      return nil if cache.nil? || cache.is_a?(ActiveSupport::Cache::NullStore)
 
-      current_api_key.last_used_at >= Time.current - seconds
+      cache
     end
 
     # Helper to safely enqueue callback jobs.

data/lib/api_keys/configuration.rb

@@ -46,12 +46,17 @@ module ApiKeys
     #
     # @!attribute [rw] client_ip_resolver
     #   @return [#call] Callable receiving the request and returning the client
-    #     IP address used to evaluate a key's `allowed_ips` list. The default
-    #     honors Rails' trusted-proxy handling via `request.remote_ip`; behind a
-    #     CDN, configure `config.action_dispatch.trusted_proxies` whenever
-    #     possible. A resolver that trusts a vendor header is safe only when
-    #     network ingress rejects requests that bypass that vendor.
-    #   @example
+    #     IP address used to evaluate a key's `allowed_ips` list. The default,
+    #     `request.remote_ip`, is right only behind a proxy that is the sole way
+    #     in, rewrites `X-Forwarded-For`, and is covered by
+    #     `config.action_dispatch.trusted_proxies`. When the Rails server is
+    #     directly reachable, a client can forge `X-Forwarded-For`; resolve the
+    #     socket peer with `request.remote_addr` instead. A resolver that trusts
+    #     a vendor header is safe only when network ingress rejects requests
+    #     that bypass that vendor.
+    #   @example Directly reachable server
+    #     config.client_ip_resolver = ->(request) { request.remote_addr }
+    #   @example Behind Cloudflare, with direct origin access blocked
     #     config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
     attr_reader :client_ip_resolver
 
@@ -102,6 +107,13 @@ module ApiKeys
     #     - :restrictions [Array<Symbol>] Which request-restriction kinds keys of this
     #       type may carry: any subset of [:origins, :ips]. Omitted means both are
     #       allowed; `[]` forbids restrictions entirely for this type.
+    #     - :scopes [Symbol] Where scope checks for keys of this type look.
+    #       `:stored` (default) checks the scopes each key stored at creation,
+    #       capped by the type's permissions. `:ceiling` makes the type's live
+    #       `permissions` list the contract: every key of the type is authorized
+    #       for exactly that list, so widening or narrowing it applies to existing
+    #       keys immediately, and stored scopes become metadata. `:ceiling`
+    #       requires a finite, non-empty permissions list (never `:all`).
     #   @example
     #     config.key_types = {
     #       publishable: { prefix: "pk", permissions: %w[read], public: true, limit: 1,
@@ -142,6 +154,9 @@ module ApiKeys
     VALID_HASH_STRATEGIES = %i[sha256 bcrypt].freeze
     VALID_TOKEN_ALPHABETS = %i[base58 hex].freeze
     VALID_DASHBOARD_CONTENT_SECURITY_POLICIES = [:default, :strict, false, nil].freeze
+    # Where a key type's scope checks look: the scopes each key stored at
+    # creation (default), or the type's live permission ceiling.
+    KEY_TYPE_SCOPE_SOURCES = %w[stored ceiling].freeze
     TOKEN_LENGTH_RANGE = (16..64)
     MAX_CONFIGURED_SCOPES = 100
     CONFIG_NAME_PATTERN = /\A[a-zA-Z0-9_-]{1,64}\z/
@@ -429,6 +444,7 @@ module ApiKeys
         end
 
         validate_restriction_kinds!(name, type_config[:restrictions]) if type_config.key?(:restrictions)
+        validate_scope_source!(name, type_config[:scopes], permissions) if type_config.key?(:scopes)
 
         next unless type_config[:public] == true
 
@@ -452,6 +468,21 @@ module ApiKeys
             "Key type '#{name}' restrictions must be an Array containing any of: #{ApiKeys::Restrictions::KIND_NAMES.join(', ')}"
     end
 
+    # `scopes: :ceiling` makes the type's permission list authoritative for every
+    # existing key of the type. Against `:all` (or an empty list) that would turn
+    # each key into an unbounded or useless credential, so only a finite,
+    # non-empty ceiling may be the contract.
+    def validate_scope_source!(name, source, permissions)
+      unless (source.is_a?(Symbol) || source.is_a?(String)) && KEY_TYPE_SCOPE_SOURCES.include?(source.to_s)
+        raise ArgumentError, "Key type '#{name}' scopes must be :stored or :ceiling"
+      end
+      return unless source.to_s == "ceiling"
+      return if permissions.is_a?(Array) && permissions.any?
+
+      raise ArgumentError,
+            "Key type '#{name}' uses scopes: :ceiling, so its permissions must be a finite, non-empty list (never :all)"
+    end
+
     def validate_config_name!(value, label)
       return if valid_config_name?(value)
 

data/lib/api_keys/form_builder_extensions.rb

@@ -21,6 +21,8 @@ module ApiKeys
   #       <%= scope %>
   #     </label>
   #   <% end %>
+  #   (The helper prepends an empty `api_key[scopes][]` sentinel so that
+  #   clearing every box submits "no scopes" instead of nothing.)
   #
   module FormBuilderExtensions
     # Renders a select field for API key expiration presets.
@@ -62,6 +64,27 @@ module ApiKeys
     #   - :none - no scopes checked
     #   - Array - specific scopes to check
     #   - nil - uses the object's current scopes
+    # @param include_hidden [Boolean, nil] With a block, whether to render an
+    #   empty `name="api_key[scopes][]" value=""` sentinel before the boxes.
+    #   Browsers omit unchecked boxes, so without it clearing every box submits
+    #   no scopes parameter at all, and a create would silently get the default
+    #   scopes while an update would keep the old ones. With the sentinel the
+    #   server receives `[""]`, which `ApiKey#scopes=` and `create_api_key!`
+    #   read as "no scopes". The submitted list replaces the key's scopes, so
+    #   render a box for every scope the key may hold, or save it through
+    #   `ApiKey#scopes_after_form_edit(offered:, checked:)`, which edits only
+    #   the offered scopes and keeps the rest.
+    #   - nil (default): render it when there is at least one box and the
+    #     form's key enforces its scopes (`ApiKey#scopes_enforced?`). Elsewhere
+    #     an empty list would mean "unrestricted" and clearing the boxes would
+    #     widen the key. Per-owner default scopes are read through the key's
+    #     `owner`, so build the form's key from its owner
+    #     (`owner.api_keys.build`): a form with no object, or on a bare
+    #     `ApiKey.new`, cannot see them and renders no sentinel.
+    #   - true: render it whenever there is at least one box, without asking
+    #     the key. Use it on those ownerless forms when an empty list grants
+    #     nothing in your app.
+    #   - false: never render it.
     # @return [String, Array] HTML if block given, otherwise array of scope data
     #
     # @example With block (recommended for custom styling)
@@ -72,27 +95,30 @@ module ApiKeys
     #     </label>
     #   <% end %>
     #
-    # @example Simple rendering without block
+    # @example Simple rendering without block (render the sentinel yourself)
+    #   <%= hidden_field_tag "api_key[scopes][]", "", id: nil %>
     #   <% form.api_key_scopes_checkboxes(@scopes).each do |scope_data| %>
     #     <%= check_box_tag "api_key[scopes][]", scope_data[:value], scope_data[:checked] %>
     #     <%= scope_data[:value] %>
     #   <% end %>
     #
-    def api_key_scopes_checkboxes(scopes, checked: nil, &block)
+    def api_key_scopes_checkboxes(scopes, checked: nil, include_hidden: nil, &block)
       # Determine which scopes should be checked
       checked_scopes = resolve_checked_scopes(scopes, checked)
+      field_name = "#{object_name}[scopes][]"
 
       scope_data = scopes.map do |scope|
         {
           value: scope,
           checked: checked_scopes.include?(scope),
-          field_name: "#{object_name}[scopes][]"
+          field_name: field_name
         }
       end
 
       if block_given?
         # Yield each scope for custom rendering
         safe_buffer = ActiveSupport::SafeBuffer.new
+        safe_buffer << @template.hidden_field_tag(field_name, "", id: nil) if render_scope_sentinel?(scopes, include_hidden)
         scope_data.each do |data|
           safe_buffer << @template.capture { yield(data[:value], data[:checked]) }
         end
@@ -135,6 +161,19 @@ module ApiKeys
 
     private
 
+    # The sentinel is only safe where an empty list grants nothing. With no
+    # boxes there is nothing to clear, so it is never rendered then. By
+    # default it also needs a key that enforces its scopes; where the key does
+    # not, an empty list would mean "unrestricted", so the parameter is left
+    # out and the key keeps the scopes it has. `include_hidden: true` skips
+    # that question for forms whose key cannot answer it.
+    def render_scope_sentinel?(scopes, include_hidden)
+      return false if include_hidden == false || scopes.empty?
+      return true if include_hidden == true
+
+      object.respond_to?(:scopes_enforced?) && object.scopes_enforced?
+    end
+
     def safe_key_type(value)
       case value.to_s
       when "publishable" then :publishable