api_keys 0.5.1 → 0.7.0

data/README.md

@@ -50,6 +50,50 @@ rails db:migrate
 
 New installations get this column from the start, so this is only for upgrades.
 
+To record refused requests on each key (see [Refused requests](#refused-requests-why-a-key-is-not-working)) and make the one-time token page durable (see [What "one-time" guarantees](#what-one-time-guarantees)), add the 0.6.0 columns in one migration:
+
+```bash
+rails generate api_keys:add_key_activity
+rails db:migrate
+```
+
+New installations get these columns from the start too. Until an existing app runs the migration, authentication keeps working exactly as before, refusals are simply not recorded, and the one-time token page relies on the cache marker alone, as in 0.5.1.
+
+To name the person behind each key (see [The person behind a key](#the-person-behind-a-key)), add the 0.7.0 `created_by` column. New installations get it from the start:
+
+```bash
+rails generate api_keys:add_created_by
+rails db:migrate
+```
+
+The device flow and Idempotency-Key each need a table of their own. New and existing installations run these only if they use the feature:
+
+```bash
+rails generate api_keys:add_device_authorizations  # for ApiKeys::DeviceFlow
+rails generate api_keys:add_idempotency_keys       # for ApiKeys::Idempotency
+rails db:migrate
+```
+
+#### Upgrading to 0.7.0 from 0.4.x or 0.6.x
+
+Change the Gemfile line to `gem "api_keys", "~> 0.7.0"` and run `bundle update api_keys`. No migration is required: every migration since 0.5.0 adds an optional column or table, and the gem works without it. Run the ones for the features you want, in any order.
+
+| From | Optional migrations | What they turn on |
+|------|---------------------|-------------------|
+| 0.4.x | `add_restrictions` | Origin and IP locks (0.5.0) |
+| 0.4.x | `add_key_activity` | Refused-request stats and the durable one-time token page (0.6.0) |
+| 0.4.x, 0.6.x | `add_created_by` | The person behind a key (0.7.0) |
+| 0.4.x, 0.6.x | `add_device_authorizations` | The device flow (0.7.0) |
+| 0.4.x, 0.6.x | `add_idempotency_keys` | Idempotency-Key for writes (0.7.0) |
+
+On 0.6.x, nothing changes until you opt in to a 0.7.0 feature. A 0.6.0 job worker ignores the new `untrusted_key` refusal code with a warning, so a rolling deploy is safe.
+
+On 0.4.x, the calls of a custom key controller keep working unchanged: `create_api_key!(name:, key_type:, expires_at:)`, `ApiKeys::TokenSession.store(session, @api_key)` and `ApiKeys::TokenSession.retrieve_once(session)`. A handoff stored by 0.4.x stays readable after the deploy. Read the [CHANGELOG](CHANGELOG.md) for 0.5.0 to 0.6.0 before you upgrade. These changes are the ones a 0.4.x app sees:
+
+- `api_key_scopes_checkboxes` renders an empty `api_key[scopes][]` field before the boxes (0.5.1). A form with every box cleared now saves no scopes, where 0.4.x kept the old ones. If an edit form offers only some scopes, save `ApiKey#scopes_after_form_edit` (see [Form Builder Extensions](#form-builder-extensions-opt-in)).
+- A token's one-time handoff is one-time across copies of the session (0.5.1), and once ever per key after `add_key_activity` (0.6.0). A retrieval inside an open database transaction is refused (0.6.0): exclude the token page from a host `around_action` that wraps requests in a transaction.
+- Deploy job workers with the web processes. A refusal job from 0.6.0 or later errors on a 0.4.x worker.
+
 ## Quick Start
 
 Just add `has_api_keys` to your desired model. For example, if you want your `User` records to have API keys, you'd have:
@@ -159,11 +203,12 @@ config.authenticate_owner_method = :ensure_team_access!
 Once configured, your users can:
 - self-issue new API keys
 - set expiration dates
-- attach scopes / permissions to individual keys (the edit form changes only the scopes it shows, the owner's default scopes, and keeps any other scope a key holds)
+- attach scopes / permissions to individual keys (the edit form changes only the scopes it shows, the owner's default scopes, keeps any other scope a key holds, and drops a held scope its type no longer allows; keys of a `scopes: :ceiling` type show their live permissions instead, on the creation form as soon as such a type is selected, and the dashboard never takes scopes for them)
 - add and edit the key names
 - lock a key to specific web origins or IP addresses
 - revoke instantly
 - see the status of all their keys
+- see when a key's requests are arriving but being refused, and why
 
 It provides an UI with everything you'd expect from an API keys dashboard, working right out of the box:
 
@@ -398,7 +443,8 @@ current_org.can_create_api_key?(key_type: :publishable)
   environment: :live,                   # Defaults to current_environment
   metadata: { team: "backend" },        # Optional JSON metadata
   allowed_origins: "example.com",       # Optional: lock to web origins
-  allowed_ips: "10.0.0.0/8"             # Optional: lock to IP addresses
+  allowed_ips: "10.0.0.0/8",            # Optional: lock to IP addresses
+  created_by: current_user              # Optional: the person behind the key
 )
 ```
 
@@ -433,6 +479,7 @@ Methods available on `ApiKeys::ApiKey` instances:
 # Scopes
 @api_key.scopes                   # => ["read", "write"]
 @api_key.allows_scope?("read")    # => true
+@api_key.scopes_follow_ceiling?   # => true for `scopes: :ceiling` key types
 
 # Request restrictions (where the key may be used from)
 @api_key.allowed_origins          # => ["example.com", "*.example.com"]
@@ -440,12 +487,20 @@ Methods available on `ApiKeys::ApiKey` instances:
 @api_key.restricted?              # => true if either list has entries
 @api_key.restrictions             # => ApiKeys::Restrictions value object
 
+# The person behind the key (needs the created_by column)
+@api_key.created_by               # => #<User id: 1, ...>, or nil
+
 # Metadata
 @api_key.name                     # => "Production Server"
 @api_key.created_at
 @api_key.expires_at
 @api_key.last_used_at
 @api_key.requests_count           # If tracking enabled
+
+# Refused requests (the key's real token, refused by a policy)
+@api_key.last_refused_at          # => 2026-10-18 12:00:00 UTC, or nil
+@api_key.last_refusal_code        # => "origin_not_allowed", or nil
+@api_key.refusals_count           # If tracking enabled
 ```
 
 ---
@@ -470,21 +525,40 @@ ApiKeys::TokenSession.store(session, @api_key, key: :my_custom_key)
 )
 ```
 
-Treat the session payload as private implementation detail; use `store`, `available?`, and `retrieve_once` rather than reading it directly. A failed, expired, tampered, mismatched, or reused handoff returns `nil` and fails closed. Any retrieval attempt uses the handoff up, including one bound to the wrong key.
+Treat the session payload as private implementation detail; use `store`, `available?`, and `retrieve_once` rather than reading it directly. A failed, expired, tampered, mismatched, or reused handoff returns `nil` and fails closed. Every retrieval attempt outside a database transaction uses the handoff up, including one bound to the wrong key; an attempt refused inside a transaction (`:inside_transaction`, below) leaves it in the session for a retry outside it.
+
+To tell the owner *why* no token came back, use `retrieve_once_with_status`. It consumes the handoff exactly like `retrieve_once` and also returns a status: `:retrieved`, `:already_shown` (an earlier retrieval released this key's token, for example a replayed copy of the session), `:withheld` (the database or cache could not record the retrieval), `:inside_transaction` (see below), or `:missing`:
+
+```ruby
+retrieval = ApiKeys::TokenSession.retrieve_once_with_status(session, api_key: @api_key)
+if retrieval.retrieved?
+  @token = retrieval.token
+elsif retrieval.already_shown? || @api_key.token_shown?
+  redirect_to keys_path, alert: "This key's token was already shown."
+else
+  redirect_to keys_path, alert: "The token can only be shown right after creation."
+end
+```
 
 #### What "one-time" guarantees
 
 Deleting the payload makes the handoff one-time within that session: a refresh, or a second visit with the same session, shows nothing. A copy of the session taken *before* the token was shown is a different session. That is what a copied `CookieStore` cookie is, and what two requests racing with the same cookie are. Deleting the payload from one copy does nothing to the other.
 
-So each handoff also carries a random ID inside its encrypted payload, and the first retrieval records that ID in `Rails.cache` with `write(key, true, unless_exist: true, expires_in: 10.minutes)`. While the cache still holds that record, any later retrieval of the same handoff, from any copy of the session, finds it and returns `nil`.
+So from 0.6.0 the first retrieval also claims the key's `token_shown_at` column with one conditional statement:
+
+```sql
+UPDATE api_keys SET token_shown_at = <now> WHERE id = <key id> AND token_shown_at IS NULL
+```
 
-- **The token is released at most once only when both conditions hold:** every application process shares a store that implements `unless_exist:` atomically (Redis, Memcached), and that store keeps the record for the whole ten-minute handoff lifetime.
-- **The record lives only in the cache.** If the cache is flushed, restarted without persistence, or evicts the record within those ten minutes, a copy of the session taken before retrieval can recover the token again for the rest of that window. Recording consumption durably, in a database column, is the stronger design and is planned for 0.6.0.
-- **`MemoryStore`** only covers the process that holds it. **`FileStore`** checks and then writes, so it stops a later replay on the same host but not two requests that arrive at the same instant.
-- **Solid Cache** (Rails 8's default production store) implements `unless_exist:` as a `SELECT … FOR UPDATE` followed by an upsert. On PostgreSQL that locks nothing while the key does not exist yet, so two simultaneous first retrievals can both succeed. Sequential replays are still stopped.
-- **With `ActiveSupport::Cache::NullStore`** (what Rails' generated development and test environments use unless you toggle caching on), or with no `Rails.cache` at all, nothing can be recorded. The gem keeps the pre-0.5.1 behaviour: the session deletion is the only protection, and a copy of the session taken before retrieval can show the token again during its ten-minute lifetime.
-- **If the cache raises or refuses the write**, the token is withheld. The owner sees the "shown only once" message and creates a new key, which is safer than risking a second release.
-- **With a shared cache, a second request for the token page with the same cookie gets nothing**, even if the first response never reached the browser. A client that drops the first response (a timeout or a cancelled load) sees "shown only once" and needs a new key. That is the intended trade-off: a token can be lost, never shown twice.
+The database applies it atomically, and the claim commits before the token is returned, so exactly one retrieval of a key's handoff ever succeeds, across processes and across copies of the session, whatever happens to the cache. A later retrieval from any copy changes no row and returns `nil` (the dashboard says the token was already shown).
+
+- **With the column, the token is released at most once per key.** A cache flush, a restart, or an eviction changes nothing, and two simultaneous first retrievals are serialized by the database: one wins. `ApiKey#token_shown_at` and `#token_shown?` report it. A key whose row no longer exists gets nothing: zero rows claimed fails closed.
+- **A retrieval attempted inside a database transaction is refused, and can be retried outside it.** Inside a transaction the claim would commit only with it, after the token had been returned, and a rollback would undo it. No cache can stand in for that (a process-local store protects one process), so whatever the cache, the token is withheld with `:inside_transaction`, nothing is recorded, and the handoff stays in the session for a retrieval outside the transaction. The check is Active Record's transaction manager on the `ApiKey` connection: a transaction opened with raw SQL (`BEGIN`) is not detected, and one on another database's connection does not matter. The dashboard opens no transaction itself, but its controller inherits from your `ApplicationController` (or the configured parent): a host `around_action` that wraps requests in a transaction will see the refusal and must exclude the token page.
+- **The column is written only by that claim.** The model marks it read-only, so no form, mass assignment, or `update` can clear it and reopen a handoff.
+- **The cache marker from 0.5.1 stays as a second layer.** Each handoff carries a random ID inside its encrypted payload, and retrieval records it in `Rails.cache` with `write(key, true, unless_exist: true, expires_in: 10.minutes)`. With the column it refuses a release the claim did not see (a 0.5.1 process that served the token during a rolling deploy), and it is the only cross-copy layer for a handoff that names no key (`TokenSession.store(session, "a token string")`).
+- **Without the column** (an existing install that has not run `rails generate api_keys:add_key_activity`), the gem behaves as 0.5.1 and the marker is the only cross-copy layer. The token is then released at most once only when every application process shares a store that implements `unless_exist:` atomically (Redis, Memcached), and that store keeps the marker for the whole ten-minute handoff lifetime. If the cache is flushed, restarted without persistence, or evicts the marker within those ten minutes, a copy of the session taken before retrieval can recover the token again for the rest of that window. **`MemoryStore`** only covers the process that holds it. **`FileStore`** checks and then writes, so it stops a later replay on the same host but not two requests that arrive at the same instant. **Solid Cache** (Rails 8's default production store) implements `unless_exist:` as a `SELECT … FOR UPDATE` followed by an upsert; on PostgreSQL that locks nothing while the key does not exist yet, so two simultaneous first retrievals can both succeed. **`ActiveSupport::Cache::NullStore`** (Rails' generated development and test default), or no `Rails.cache` at all, records nothing, so the session deletion is the only protection.
+- **If the database or the cache raises or refuses the write**, the token is withheld. The owner sees the "shown only once" message and creates a new key, which is safer than risking a second release.
+- **A second request for the token page with the same cookie gets nothing**, even if the first response never reached the browser. A client that drops the first response (a timeout or a cancelled load) sees the "already shown" message and needs a new key. That is the intended trade-off: a token can be lost, never shown twice.
 
 None of this protects a session that has been stolen. Whoever holds a copy of the owner's session cookie can use the dashboard as that owner; the handoff is one-time, the session is not.
 
@@ -543,7 +617,7 @@ Renders a select dropdown with all expiration presets:
 
 #### `api_key_scopes_checkboxes`
 
-Renders scope checkboxes with a block for custom markup. Before the boxes it can render one empty `api_key[scopes][]` field: browsers omit unchecked boxes, so without it a form with every box cleared would send no scopes at all, and a new key would silently get the default scopes while an edited key would keep its old ones. With it, clearing every box submits `[""]`, which `create_api_key!` and `ApiKey#scopes=` read as "no scopes". The submitted list replaces the key's scopes, so render a box for every scope the key may hold.
+Renders scope checkboxes with a block for custom markup. Before the boxes it can render one empty `api_key[scopes][]` field: browsers omit unchecked boxes, so without it a form with every box cleared would send no scopes at all, and a new key would silently get the default scopes while an edited key would keep its old ones. With it, clearing every box submits `[""]`, which `create_api_key!` and `ApiKey#scopes=` 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` (below).
 
 By default the field is rendered only when there is at least one box and the form's key enforces its scopes (`@api_key.scopes_enforced?`). That is true for typed keys, whenever `key_types` or the global `config.default_scopes` are configured, and when the owner model's `has_api_keys` declares `default_scopes`. The key reads that last setting through its owner, so build it from the owner (`current_organization.api_keys.build`). A form with no object (`form_with scope: :api_key`) or on a bare `ApiKeys::ApiKey.new` cannot see per-owner defaults and renders no field: pass `include_hidden: true` there to render it whenever there is at least one box. Where scopes are not enforced at all, an empty list still means "unrestricted", so the default leaves the key's scopes as they were rather than widening it. Pass `include_hidden: false` only if you render the field yourself. When you iterate the returned data without a block, render `hidden_field_tag "api_key[scopes][]", "", id: nil` before the boxes under the same conditions.
 
@@ -567,6 +641,16 @@ By default the field is rendered only when there is at least one box and the for
 <%# checked options: :all, :none, or an array of specific scopes %>
 ```
 
+If your edit form offers only some scopes, saving the submitted list as is would strip every scope the form did not show. Save `ApiKey#scopes_after_form_edit(offered:, checked:)` instead, the rule the built-in dashboard uses: offered scopes follow their boxes, every other scope the key holds is kept, a submitted value that was never offered is ignored, and held scopes outside the key's current ceiling are dropped. Pass `checked: nil` when the request carried no scopes parameter at all. A `scopes: :ceiling` key gets its stored scopes back unchanged.
+
+```ruby
+def update
+  submitted = params.require(:api_key).permit(:name, scopes: [])
+  scopes = @api_key.scopes_after_form_edit(offered: @available_scopes, checked: submitted[:scopes])
+  @api_key.update(name: submitted[:name], scopes: scopes)
+end
+```
+
 #### `api_key_token_data`
 
 Returns structured data for building token display UIs:
@@ -637,6 +721,14 @@ end
 <%# => "Test mode", "Live mode", or "Default" %>
 ```
 
+#### Refusal Helper
+
+```erb
+<%# Why the key's latest recorded refusal happened (nil if none) %>
+<%= api_key_refusal_reason(@key) %>
+<%# => "the request came from a web origin the key does not allow" %>
+```
+
 ---
 
 ### View Examples
@@ -834,7 +926,7 @@ You can check if an API key is allowed to do actions by checking its scopes:
 # => true
 ```
 
-An empty scope list grants nothing whenever scopes are enforced: on typed keys, and when `key_types` or `default_scopes` are configured. On an untyped key in an app that configures neither, an empty list keeps its legacy meaning and allows every scope. So a key saved from the dashboard with every permission cleared becomes unrestricted if you later remove the owner's `default_scopes` (and the global ones) without using key types.
+An empty scope list grants nothing whenever scopes are enforced: on typed keys, and when `key_types` or `default_scopes` are configured. The exception is a key whose type uses `scopes: :ceiling`: its stored scopes are not consulted, so even with `scopes: []` it has exactly its type's live `permissions:` (see [Widening a ceiling does not reach existing keys](#widening-a-ceiling-does-not-reach-existing-keys)). On an untyped key in an app that configures neither, an empty list keeps its legacy meaning and allows every scope. So a key saved from the dashboard with every permission cleared becomes unrestricted if you later remove the owner's `default_scopes` (and the global ones) without using key types.
 
 ## Controllers: secure your API endpoints
 
@@ -899,6 +991,39 @@ def write_action
 end
 ```
 
+### Require read or write by HTTP method
+
+Most APIs give reads one scope and writes another. Pass both by HTTP method, in one line:
+
+```ruby
+before_action -> { authenticate_api_key!(scope: { read: "read", write: "write" }) }
+```
+
+GET and HEAD requests need the `read` scope. Every other method needs the `write` scope. Each side takes what `scope:` takes: a scope, a list of scopes, or `nil` for none. Both sides are required, so a forgotten one never leaves its requests unchecked.
+
+An action that needs another scope names it. Put the rule in a method, and let a controller override it:
+
+```ruby
+class Api::BaseController < ActionController::API
+  include ApiKeys::Controller
+  before_action -> { authenticate_api_key!(scope: required_scope) }
+
+  private
+
+  def required_scope
+    { read: "read", write: "write" }
+  end
+end
+
+class Api::InvoicesController < Api::BaseController
+  private
+
+  def required_scope
+    action_name == "pdf" ? "downloads" : super
+  end
+end
+```
+
 ### Rate limit your API endpoints
 
 Rails 8 introduced the native, built-in `rate_limit` to easily rate limit your endpoints, so `Rack::Attack` is no longer necessary! While this is not an `api_keys` feature per se, I thought it'd be nice to include an example here because it pairs so well with `api_keys`.
@@ -922,6 +1047,209 @@ This `rate_limit` feature depends on Rails 8+ and an active, well-configured cac
 If you're still on early versions of Rails, you can still use `api_keys`! No need to implement `rate_limit` – just an idea if you're already on Rails 8!
 
 
+## The person behind a key
+
+When keys belong to an organization, a key keeps working after the person who created it has left. Name that person when you create the key:
+
+```ruby
+current_organization.create_api_key!(name: "CI", scopes: %w[read], created_by: current_user)
+```
+
+Then tell the gem when a key stops being trusted:
+
+```ruby
+# config/initializers/api_keys.rb
+config.trusted_key_check = ->(api_key) { api_key.owner.managed_by?(api_key.created_by) }
+```
+
+After authentication and the scope check, `authenticate_api_key!` calls the lambda with the key. When it answers `false` or `nil`, the request gets `403` with `error: "untrusted_key"`, the key is not set as `current_api_key`, and the refusal is recorded on the key like every other refusal (with the 0.6.0 columns), never as a use. An error in the lambda fails the request; it never passes as trusted. Without a lambda (the default), every valid key is trusted, as before.
+
+- `created_by` is polymorphic and optional. It cannot change after the key is created (a validation, and `attr_readonly`), so no update can make another person stand behind a key.
+- The mounted dashboard leaves `created_by` nil: it knows the key's owner, not the person. An app that needs the person behind each key creates its keys in its own controller and passes `created_by:` there (see [Building Custom Integrations](#building-custom-integrations)).
+- Keys created before you set `created_by` have none. Decide what the lambda does with them, or backfill the columns in a migration with SQL (`update_all`): the columns are read-only for a saved key, so no save, `update_column` or form can change them.
+- The refusal renders through `render_unauthorized`, so if you override it to render your own error shape, `untrusted_key` uses that shape too. Change the message with I18n: `api_keys.errors.untrusted_key`.
+- New installs get the columns from the start. Existing installs run `rails generate api_keys:add_created_by`; until then, passing `created_by:` raises `ApiKeys::Errors::CreatedByMigrationRequiredError`.
+
+## Idempotent writes (Idempotency-Key)
+
+A client that retries a write after a timeout must not create a second record. With `ApiKeys::Idempotency`, every write carries an `Idempotency-Key` header and runs once per key ([draft-ietf-httpapi-idempotency-key-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)):
+
+```bash
+rails generate api_keys:add_idempotency_keys
+rails db:migrate
+```
+
+```ruby
+class Api::BaseController < ActionController::API
+  include ApiKeys::Controller
+  include ApiKeys::Idempotency
+
+  before_action :authenticate_api_key!
+  around_action :run_once_per_idempotency_key # after authentication
+
+  private
+
+  # The JSON for a record. The first answer and every retry use it.
+  def resource_json(record, **options)
+    record.as_json(only: %i[id name]).merge(options)
+  end
+
+  # Whether this API key may read the record now. A retry runs no action,
+  # so this is the check before a record's current state goes back.
+  def idempotent_replay_allowed?(record)
+    record.owner == current_api_owner
+  end
+end
+
+class Api::WebhooksController < Api::BaseController
+  def create
+    webhook = current_api_owner.webhooks.create!(url: params.require(:url))
+    render_resource webhook, status: :created, secret: webhook.secret # the secret is in this answer only
+  end
+end
+```
+
+How it works:
+
+- GET and HEAD run as they are. Every other request needs the header: a text of 1 to 255 characters, the same when the client retries.
+- A write answers with `render_resource(record, status:, **options)`. The key keeps the status and the record, never the response body, so a secret shown once is never stored.
+- The write, any rows it adds (an audit entry), and the key's answer commit in one transaction, or nothing does. A write that answers anything but 2xx, or raises, commits nothing and leaves the key free, so the corrected request can use it. That transaction is on the database of the `api_keys` tables: a write to another database does not join it.
+- A retry with the same key and the same request answers the record **as it is now**, through `resource_json` without the first answer's options, with the header `Idempotent-Replayed: true`. Before that, `idempotent_replay_allowed?(record)` must answer true: a record that moved to another owner, or no longer exists, raises `ActiveRecord::RecordNotFound` (Rails answers 404). Both methods are required, and the first write raises `NotImplementedError` without them.
+- The request is the method, the path, the query and the body. The query and the body count apart, so a name that moves from one to the other makes another request. The order of names does not matter. An uploaded file counts by its bytes, its file name and its content type, and never encodes like an ordinary value.
+- The around_action runs outside every open transaction: the key's claim must commit on its own, so `ApiKeys::IdempotencyKey.hold` raises inside one. Transactional tests, which open a transaction around each test, set a test-only switch in `config/environments/test.rb` or the test helper: `ApiKeys.configuration.idempotency_in_test_transactions = true`. It takes `true` only when `Rails.env` is test, and counts only while it is test.
+- Keys are per API key and kept for a day. Run `ApiKeys::IdempotencyKey.prune!` once a day, for example from a recurring job.
+
+The refusals follow the draft (section 2.7). They render through `render_unauthorized`, like the gem's other refusals, and their messages change with I18n (`api_keys.errors.<code>`):
+
+| Status | `error` | When |
+|--------|---------|------|
+| 400 | `idempotency_key_required` | A write without the header, or with one longer than 255 characters |
+| 409 | `idempotency_key_in_use` | A request with this key is still running |
+| 422 | `idempotency_key_reused` | The key was used for another request |
+
+A retry waits at most two seconds for the request that holds the key, then answers 409, and two first requests with the same key wait for each other's claim at most as long. On PostgreSQL (`lock_timeout`) and MySQL (`innodb_lock_wait_timeout`) the gem sets that timeout for the claim and the lock, then puts the old value back. SQLite has no row locks: a retry waits for the database's write lock, as long as the database's busy timeout. CI checks this on PostgreSQL, MySQL and SQLite with real concurrent connections (`test/databases/check.rb`). Every successful write must answer with `render_resource`; one that does not raises and commits nothing.
+
+The model works outside a controller too, for example in a tool that shares the API's keys:
+
+```ruby
+digest = ApiKeys::IdempotencyKey.digest_of("TOOL", "create_webhook", arguments)
+ApiKeys::IdempotencyKey.hold(api_key, key) do |record|
+  next replay(record) if record.answered? # compare record.request_digest with digest first
+
+  record.update!(request_digest: digest)
+  webhook = create_webhook(arguments)
+  record.answer!(200, webhook)
+end
+# raises ApiKeys::IdempotencyKey::Busy while another call holds the key
+```
+
+## Let an agent ask for a key: the device flow (RFC 8628)
+
+An agent or a CLI should not ask a person to copy a key into it. With the OAuth 2.0 Device Authorization Grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)), the agent asks for a key, the person approves in your app, and the agent receives an ordinary API key:
+
+1. The agent asks for codes and shows the person one link and a user code like `BCDF-GHJK`.
+2. The person opens the link in your app, signs in, compares the code, sees the agent's name, its device and the scopes, and approves or denies.
+3. The agent polls. The first poll after the approval creates the key for the owner the person chose, named "client on device", and answers with its token, once.
+
+```bash
+rails generate api_keys:add_device_authorizations
+rails db:migrate
+```
+
+**The agent's two endpoints.** Include `ApiKeys::DeviceFlow` in an API controller, name your approval page, and route the two actions:
+
+```ruby
+class Api::DeviceAuthorizationsController < ActionController::API
+  include ApiKeys::DeviceFlow
+
+  private
+
+  # The approval page, with the user code filled in when one is given
+  def device_verification_uri(user_code = nil)
+    device_approval_url(user_code: user_code)
+  end
+end
+
+# config/routes.rb
+post "api/device", to: "api/device_authorizations#create"
+post "api/token", to: "api/device_authorizations#token"
+```
+
+The agent sends `client_id` (its name), `device_name` (optional) and `scope` (space-separated), and gets the [RFC 8628 §3.2](https://www.rfc-editor.org/rfc/rfc8628#section-3.2) answer:
+
+```json
+{ "device_code": "…", "user_code": "BCDF-GHJK",
+  "verification_uri": "https://example.com/device",
+  "verification_uri_complete": "https://example.com/device?user_code=BCDF-GHJK",
+  "expires_in": 600, "interval": 5 }
+```
+
+It polls `token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, the `device_code` and the same `client_id`. Until the person decides, it gets the [§3.5](https://www.rfc-editor.org/rfc/rfc8628#section-3.5) errors as `{ "error": …, "error_description": … }` with status 400: `authorization_pending`, `slow_down` (a poll sooner than the interval, which then grows by 5 seconds), `access_denied`, `expired_token`, and `invalid_grant` for an unknown or used device code or another `client_id`. After the approval it gets the key once:
+
+```json
+{ "access_token": "ak_…", "token_type": "Bearer", "scope": "read write" }
+```
+
+No answer may be cached: every answer has `Cache-Control: no-store`. An agent may ask for any scope in `config.default_scopes`. A request without `scope` fails with `invalid_scope`, unless the controller defines `device_default_scope` (for example `"read"`).
+
+The engine adds `device_code`, `user_code` and `token` to `config.filter_parameters`, so request logs never show the codes or a token. If your approval page takes the user code under another parameter name, add that name too.
+
+**Key types.** Every request names the type of the key it asks for: `device_key_type` in the controller, `config.default_key_type` by default. With key types configured and no type named, the request raises, because that is the app's error, not the client's. The scopes an agent may ask for are then the ones of `config.default_scopes` that the type's `permissions` allow. A type with `scopes: :ceiling` gives every key its whole ceiling, so a request must ask for all of it. The type is stored with the request and is the type of the key: an untyped request stays untyped, and a new default type never applies to it.
+
+If the configuration changes after the approval so that the key can no longer be made as the person approved it, the poll answers `invalid_scope` (RFC 6749 §5.2) and closes the request (state `void`): key types turned on for an untyped request, the request's type removed or renamed, or a ceiling that grew. Any other failure to make the key closes it too. An owner at its key limit is the one case that waits: the poll answers `authorization_pending`.
+
+**The person's page** stays in your app, behind your sign-in. Find the request by the code the person typed or followed, show what the agent asks for, and decide:
+
+```ruby
+class DeviceApprovalsController < ApplicationController
+  before_action :authenticate_user!
+  # Look-ups and approvals share one budget, so a guess sent straight to
+  # update costs the same as one typed on the page (RFC 8628 §5.1).
+  rate_limit to: 10, within: 10.minutes, by: -> { current_user.id }, only: %i[show update]
+
+  def show
+    @authorization = ApiKeys::DeviceAuthorization.find_undecided_by_user_code(params[:user_code]) if params[:user_code].present?
+    # Show @authorization.client_id, .device_name, .scopes, .requested_from and the code,
+    # and ask the person to compare the code with the one the agent shows (RFC 8628 §5.4).
+  end
+
+  def update
+    authorization = ApiKeys::DeviceAuthorization.find_undecided_by_user_code(params[:user_code])
+    return redirect_to(device_approval_path) unless authorization
+
+    if params[:decision] == "approve"
+      authorization.approve!(current_organization, by: current_user)
+    else
+      authorization.deny!(by: current_user)
+    end
+    redirect_to device_approval_path, notice: "Done. Go back to the agent."
+  rescue ApiKeys::DeviceAuthorization::Closed
+    redirect_to device_approval_path, alert: "This request expired or was decided already."
+  rescue ApiKeys::DeviceAuthorization::KeyLimitReached
+    redirect_to device_approval_path(user_code: params[:user_code]), alert: "You have the most API keys you may have. Revoke one, then approve again."
+  end
+end
+```
+
+The rules the model keeps:
+
+- Both codes are stored as SHA-256 digests. The key's token is never stored: the poll that creates the key is the only answer that carries it.
+- A request lives ten minutes. The user code is eight letters from twenty consonants ([§6.1](https://www.rfc-editor.org/rfc/rfc8628#section-6.1)), and case, spaces and dashes do not matter when the person types it.
+- Polls and decisions take the request's row lock. A decided or expired request cannot be decided again: `approve!` and `deny!` raise `ApiKeys::DeviceAuthorization::Closed`.
+- `approve!` checks the owner's key limit first (`max_keys`, and the `limit` of the request's key type). At the limit it raises `ApiKeys::DeviceAuthorization::KeyLimitReached` and the request stays pending, so the person can revoke a key and approve again before it expires. It also checks the scopes against the configuration as it is now, and raises `ActiveRecord::RecordInvalid` for scopes that a key of the type no longer grants.
+- A poll never raises because the key cannot be made. If the owner reached its limit after the approval, the poll answers `authorization_pending`, nothing is kept, and a later poll makes the key once there is room. Every other failure closes the request with `invalid_scope`.
+- A poll with another `client_id` changes nothing ([§3.4](https://www.rfc-editor.org/rfc/rfc8628#section-3.4)), so the grant waits for its own client.
+- The approving person becomes the key's `created_by` when the column exists, so `config.trusted_key_check` applies to these keys too. Characters a key name cannot hold become hyphens in the key's name.
+
+What stays in your app:
+
+- **Rate limits.** Limit the code look-ups and the approvals on the approval page together, per person, so codes cannot be guessed ([§5.1](https://www.rfc-editor.org/rfc/rfc8628#section-5.1)), and the agent's requests per address. A rate limit's `with:` can answer in the RFC's shape: `with: -> { render_oauth_error("slow_down", "Too many requests.", status: :too_many_requests) }`.
+- **Who may approve,** and for which owner. When a person can switch between organizations, put the owner the page showed in the form and refuse an approval for another one.
+- **More fields in the token answer,** or an audit row: override `device_token_response(authorization, api_key)` and call `super`. It runs in the transaction that creates the key, so a row it writes to the same database commits with the key, or neither does.
+- **Housekeeping:** run `ApiKeys::DeviceAuthorization.prune!` once a day.
+
+Error descriptions change with I18n: `api_keys.device_flow.errors.<error>`.
+
 ## Configuration and settings
 
 The gem installation creates an initializer at `config/initializers/api_keys.rb`
@@ -1106,6 +1434,27 @@ config.stats_update_interval = 0         # record every successful request
 
 Enabling `track_requests_count` bypasses this debounce because every successful request must be counted. Set `enable_async_operations = false` if the application handles statistics and callbacks elsewhere and wants the gem to enqueue no background jobs.
 
+The debounce reads the stored `last_used_at`, which only moves once a worker has run the job. So that a burst of requests arriving before then does not enqueue one job each, the first request in an interval also reserves the enqueue for its key in `Rails.cache` with a conditional `write(..., unless_exist: true, expires_in: stats_update_interval)`, and the rest of the burst is skipped. That needs a cache every process shares whose `unless_exist:` is atomic, such as Redis or Memcached. Solid Cache implements `unless_exist:` as a `SELECT … FOR UPDATE` followed by an upsert, which on PostgreSQL locks nothing while the entry is absent (see [What "one-time" guarantees](#what-one-time-guarantees)), so requests that arrive at the same instant can each reserve and enqueue a job there. That costs a few extra stats jobs and nothing else: the rest of the interval is still deduplicated. A request is skipped only when its reservation is confirmed to exist, so a write that fails quietly (Redis answers `nil` on a handled error, Memcached `false`) never suppresses statistics. With `NullStore`, no `Rails.cache`, or a cache that fails, the stored timestamp is the only debounce, and a burst that arrives before the worker runs still enqueues one job per request.
+
+### Refused requests: why a key is not working
+
+A key can be perfectly valid and still be refused: an origin or IP lock, the wrong environment, a missing scope, a revoked or expired key. Refusals never touch `last_used_at` or `requests_count` (a refused request must not look like a working integration), so without anything else a key that is being used and refused would look exactly like a key nobody ever tried.
+
+The gem therefore records them separately, through the same background stats job as `last_used_at`:
+
+| Column | Meaning |
+|---|---|
+| `last_refused_at` | When the most recently recorded refusal happened |
+| `last_refusal_code` | Why: the `error_code` the client received, such as `origin_not_allowed`, `ip_not_allowed`, `environment_mismatch`, `missing_scope`, `revoked_key`, or `expired_key` |
+| `refusals_count` | How many refusals. Like `requests_count`, it is only kept with `track_requests_count = true` |
+
+The dashboard's key page then says *"Requests are arriving but refused: last at X, because Y"*, and the key list shows the latest refusal under "Last Used".
+
+- Only refusals of an identified key are recorded: the request presented the key's real token and a policy said no. A missing, malformed, or unknown token names no key and is never recorded, so nobody can write to a key's statistics without holding its token.
+- Refusal updates are debounced by `stats_update_interval` exactly like `last_used_at` (so within one interval you see the first refusal's code), including the cache reservation that stops a burst from enqueueing one job per request before the worker runs, and every refusal is recorded when `track_requests_count` is on. A client hammering a refused key costs no more writes than a working one; without a shared cache it can still queue one job per request until the first job has run.
+- `enable_async_operations = false` turns them off with every other job.
+- New installs get the columns from the start. Existing installs run `rails generate api_keys:add_key_activity`; until then, authentication is unchanged and refusals are not recorded.
+
 ## Key Types: Stripe-style Publishable & Secret Keys
 
 For applications that distribute software with embedded API keys (desktop apps, mobile apps, CLI tools), you may want to differentiate between key types with different permission levels. The `api_keys` gem supports Stripe-style publishable/secret key types with optional test/live environment isolation.
@@ -1131,6 +1480,7 @@ ApiKeys.configure do |config|
     publishable: {
       prefix: "pk",                    # Token prefix → pk_test_, pk_live_
       permissions: %w[read validate],  # Scope ceiling (max permissions allowed)
+      # scopes: :ceiling,              # Optional: see "Widening a ceiling" below
       public: true,                    # Store token so it remains viewable
       limit: 1,                        # Max 1 per owner per environment
       restrictions: [:origins]         # May be locked to domains, not to IPs
@@ -1200,6 +1550,45 @@ sk = user.create_api_key!(
 sk.scopes  # => ["read", "validate", "issue_license", "admin"]
 ```
 
+### Widening a ceiling does not reach existing keys
+
+> [!WARNING]
+> Each key stores its `scopes` when it is created. **Widening a key type's `permissions:` later does not touch the keys that already exist.** Add `heartbeat` to your publishable keys and every existing publishable key keeps its old list: it answers `403 missing_scope` on the new endpoint while freshly created keys work. Nothing fails loudly, and the key itself is valid, so it looks like a bug in your client. (Narrowing is safe either way: a scope above the current ceiling is denied at request time.)
+
+There are two ways out.
+
+**Make the ceiling the contract.** For key types whose users do not pick scopes (auto-created keys, `limit: 1`, the publishable-key pattern), opt the type into ceiling-authoritative scopes:
+
+```ruby
+config.key_types = {
+  publishable: {
+    prefix: "pk",
+    permissions: %w[read validate heartbeat],
+    scopes: :ceiling,    # every pk key has exactly these permissions, now and after you edit them
+    public: true,
+    limit: 1
+  },
+  secret: { prefix: "sk", permissions: :all }   # stored scopes, as before
+}
+```
+
+With `scopes: :ceiling`, every scope check for keys of that type (`authenticate_api_key!(scope:)`, `allows_scope?`, `allows_permission?`) reads the live `permissions:` list instead of the key's stored scopes:
+
+- Widening `permissions:` reaches every existing key on its next request, and narrowing it takes effect just as fast.
+- Every key of the type has exactly the ceiling, including a key created with an empty or narrower scope list. Do not opt in a type whose users choose scopes per key: their choices would stop mattering.
+- Stored `scopes` stay on the row as metadata and are still validated against the ceiling whenever they are written. The dashboard shows the live permissions for these keys and stops offering scope checkboxes, both on the edit form and on the creation form once such a type is selected. It never takes scopes for them: on create, submitted scopes are ignored and the key stores the type's current ceiling; on edit, submitted scopes are ignored and stored scopes above a narrowed ceiling stay as they are (other types drop them on the next save). Renaming such a key or tightening its restrictions still saves.
+- `scopes: :ceiling` requires a finite, non-empty `permissions` list. `permissions: :all` raises when the configuration loads.
+- Removing `scopes: :ceiling` later can only narrow: keys go back to their stored scopes, still capped by the ceiling.
+- Every other key type, untyped legacy keys, and keys whose type is no longer configured behave exactly as before.
+
+**Or backfill the stored scopes** right after widening a type that keeps stored scopes, for example in the same deploy:
+
+```ruby
+ApiKeys.reconcile_scopes!(key_type: :publishable) # => number of keys that gained scopes
+```
+
+It adds the type's current `permissions:` to the stored scopes of every non-revoked key of that type and never removes anything. Because it also re-adds permissions a user removed on purpose, only run it for types whose users do not curate scopes. It raises for an unknown type or a `permissions: :all` ceiling, and skips any row whose stored scopes are malformed.
+
 ### Non-Revocable Keys
 
 Keys with `revocable: false` protect against accidental deletion. Configure

data/SECURITY.md

@@ -24,7 +24,7 @@ Do not open a public issue for an undisclosed vulnerability. We will acknowledge
 Applications remain responsible for:
 
 - trusted TLS/proxy configuration, including a `client_ip_resolver` that matches how clients reach the Rails server (see below), endpoint authorization, and request rate limiting;
-- encrypted, `Secure`, `HttpOnly`, appropriately `SameSite` session cookies for the one-time dashboard token handoff, and a shared cache store if that handoff must be one-time across copies of a session (see below);
+- encrypted, `Secure`, `HttpOnly`, appropriately `SameSite` session cookies for the one-time dashboard token handoff, and the 0.6.0 `token_shown_at` column (or, until it is migrated, a shared cache store) if that handoff must be one-time across copies of a session (see below);
 - database, cache, queue, log, backup, and observability access controls;
 - filtering any query-parameter credential name from application and proxy logs if that opt-in transport is enabled;
 - classifying every permission on a `public: true` key type as safe for an untrusted public client and maintaining a disable/replacement procedure for non-revocable identifiers; and
@@ -43,10 +43,11 @@ Configuring `trusted_proxies` alone is not a boundary: it tells Rails which hops
 
 ### What the one-time token handoff guarantees
 
-The dashboard shows a new secret key once, through an encrypted session handoff that expires after ten minutes and is deleted on first retrieval. Deletion covers only the session that retrieved it. From 0.5.1 the first retrieval also records the handoff's random ID in `Rails.cache` with an atomic `write(..., unless_exist: true)`, so a copy of the session taken before retrieval (a copied cookie, or concurrent requests) gets nothing while the cache keeps that record.
+The dashboard shows a new secret key once, through an encrypted session handoff that expires after ten minutes and is deleted on first retrieval. Deletion covers only the session that retrieved it, so two more layers stop a copy of the session taken before retrieval (a copied cookie, or concurrent requests).
 
-- That holds only when both conditions are met: every application process shares a cache store that implements `unless_exist:` atomically, such as Redis or Memcached, and the store retains the record for the ten-minute handoff lifetime. The record exists only in the cache, so a flush, a restart without persistence, or an eviction within that window lets a copy of the session taken before retrieval recover the token again until the handoff expires. Durable consumption state (a database column) is the stronger design and is planned for 0.6.0.
-- `MemoryStore` covers one process; `FileStore` stops later replays on one host but not simultaneous requests. Solid Cache (Rails 8's default production store) implements `unless_exist:` as `SELECT … FOR UPDATE` then an upsert, which on PostgreSQL locks nothing while the key is absent, so two simultaneous first retrievals can both succeed; sequential replays are still stopped.
-- With `ActiveSupport::Cache::NullStore`, or no `Rails.cache`, the gem cannot record anything and the session deletion is the only protection, as before 0.5.1.
-- If the cache raises or refuses the write, the token is withheld rather than risk a second release.
+- **Durable, from 0.6.0.** The first retrieval claims the key's `token_shown_at` column with `UPDATE api_keys SET token_shown_at = now WHERE id = ? AND token_shown_at IS NULL`, and the claim commits before the token is returned, so exactly one retrieval of a key's handoff ever succeeds, across processes and whatever happens to the cache. Zero rows changed (already shown, or the key no longer exists) withholds the token. The model marks the column read-only, so only that claim writes it.
+- **A retrieval attempted inside a database transaction is refused and can be retried outside it.** There the claim would commit only with the enclosing transaction, after the token was returned, and a rollback would undo it, so whatever the cache the token is withheld (`:inside_transaction`), nothing is recorded, and the handoff stays in the session. The check is Active Record's transaction manager on the `ApiKey` connection; a raw SQL `BEGIN` is not detected. The dashboard opens no transaction, but it inherits the host's controller: a host `around_action` that wraps requests in a transaction will see the refusal and must exclude the token page.
+- **Cache marker, from 0.5.1, kept as a second layer.** Retrieval also records the handoff's random ID in `Rails.cache` with an atomic `write(..., unless_exist: true)`. With the column it refuses a release the claim did not see (a 0.5.1 process during a rolling deploy) and covers handoffs that name no key.
+- **Without the column** (not migrated yet), the gem behaves as 0.5.1: the cache marker is the only cross-copy layer. It holds only when every application process shares a cache store that implements `unless_exist:` atomically, such as Redis or Memcached, and the store retains the marker for the ten-minute handoff lifetime; a flush, a restart without persistence, or an eviction within that window lets a copy of the session taken before retrieval recover the token again until the handoff expires. `MemoryStore` covers one process; `FileStore` stops later replays on one host but not simultaneous requests; Solid Cache on PostgreSQL can let two simultaneous first retrievals both succeed; with `ActiveSupport::Cache::NullStore`, or no `Rails.cache`, the session deletion is the only protection. Run `rails generate api_keys:add_key_activity` to make the handoff durable.
+- If the database or the cache raises or refuses the write, the token is withheld rather than risk a second release.
 - It does not protect a stolen session: whoever holds the owner's session cookie can use the dashboard as that owner.