api_keys 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62087b06751cfbfe1b08bc1db54179fa1ce72844da86166a5198887d7b834a3f
-  data.tar.gz: 51ddeccbaee055eaf9d1cec6677b9514b478bf0ff4764768dee7e40e731c8685
+  metadata.gz: dca5913a99885ff5a5560a108e15d1ed8c81ef82347f6bdc3606559cf5a47ef2
+  data.tar.gz: 574b8fa3df8e307bbe24c03292acb754ef44f8453dbda17719b3e3b36eae74a5
 SHA512:
-  metadata.gz: 5b8adba5c3631e272a77bfd600f4667981bf91048e529aeac7b5f6f0c6d9b1967c989edff1ee23ee9d2a2bb9da3d83a9206e7b0a20ca26f741ebb8bae5abc586
-  data.tar.gz: e0bbcb9c1bf0be08bdbe9ffe035e7dbe60a2cddc0520474fb94c40ca6cba53c46fc8f4ce5cb9537fd14ab4392149ac294a89d7599a61ba95e66a5f8e1864fd6b
+  metadata.gz: ab7dcee45ad1c6efae2156ee2c3e1e10745ad09f4a2d4b4eed1e2d120bf78e91fe9bfdb9919aeba87b91c2ad13720bf93f9e98802053fd73f3032c1033c4f945
+  data.tar.gz: 45672849171455b8bdb2c4af0df5413fe0f693d36556e35a053cb64c184e239ee646d11776ac9d9f169b82891839ff5ab30a867ca20d5eb3037a740c8baec826

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [0.8.1] - 2026-10-26
+
+Two fixes found when an app on the fleet upgraded from 0.5 to 0.8.0. The second one now covers every upgrade generator.
+
+### Fixed
+
+- The one-time token is readable in transactional tests again, once, as in production. Since 0.6.0 a retrieval inside any open transaction was refused, and Rails' transactional tests run each test inside one, so a test that created a key and read its token got nil (`:inside_transaction`), and the dashboard's token page redirected. When `Rails.env` is test and the only open transaction is an outer, non-joinable one (what Rails' transactional tests, rspec-rails and DatabaseCleaner's `:transaction` strategy open, and what a system test's server thread shares), the claim of `token_shown_at` runs in it: the first retrieval returns the token, and a second one, or one from a copy of the session, does not. A transaction opened on top of it is still refused. Outside the test environment nothing changes. Unlike `config.idempotency_in_test_transactions`, this needs no switch: apps whose tests broke on 0.6.0 must get them back without new configuration, and the exemption covers only the test's own transaction, not every depth. The check reads the shape of the transaction, so in a test without a transaction of its own, an outer `transaction(joinable: false)` that the app opens is exempt too; the README lists the cases. Apps can remove their test-only workarounds.
+- Every upgrade generator now writes a migration that strong_migrations accepts on PostgreSQL. Before, it refused three of them. Those three now run with `disable_ddl_transaction!`, and each step checks what exists, so a run that stopped half way can run again. An invalid index that a failed concurrent build left on PostgreSQL counts as absent: the next run removes it and builds it again (`add_created_by`, `add_key_types`, `add_authentication_index`). On MySQL and SQLite they run as before, except where this list says otherwise. A migration that an earlier version generated and that already ran needs nothing.
+  - `add_created_by` (0.7.0) built the polymorphic index inside the migration's transaction, which blocks writes to `api_keys`. It now adds the columns, then builds `index_api_keys_on_created_by` with `algorithm: :concurrently` on PostgreSQL (and PostGIS).
+  - `add_key_types` (0.3.0) built its three indexes inside the transaction. They are now built concurrently on PostgreSQL. strong_migrations calls the four-column index a best-practice problem on every database. The install migration has the same index, so the migration keeps it inside `safety_assured` when the app uses strong_migrations.
+  - `add_restrictions` (0.5.0) added its check constraint and checked every row under a lock that blocks reads and writes. On PostgreSQL it now adds the constraint without that check (`validate: false`), then validates it, which does not block reads and writes. On MySQL, which refuses a literal default on a JSON column, the column now defaults to the expression `JSON_OBJECT()` (MySQL 8.0.13 or later), so the migration runs and existing keys get an empty object. On MySQL strong_migrations still refuses this migration twice: at `add_column`, for the callable default, and at the check constraint, which MySQL adds by copying the table. There, check the size of `api_keys`, then wrap the whole body of `up` in `safety_assured`, and run it when the table can be locked for the copy.
+  - `add_authentication_index` (0.4.0) already built its index concurrently. It now also does so on PostGIS.
+  - `add_key_activity`, `add_device_authorizations` and `add_idempotency_keys` already passed strong_migrations.
+- Every generated migration, the install included, passes rubocop-rails-omakase, the Rails default style. Array literals of symbols are `%i[]`, the key types are two methods instead of an array, and each `case` has its own line under `expression =`. Before, four files had 16 offenses.
+
+### Changed
+
+- `ApiKeys.test_environment?` says whether `Rails.env` is test. The token handoff and `config.idempotency_in_test_transactions` both use it.
+
+### Tests
+
+- The database check (`test/databases/check.rb`, in CI on PostgreSQL, MySQL and SQLite) now runs all seven upgrade migrations as `rails db:migrate` runs them, with strong_migrations, from an install made before 0.3.0 that has a key. It runs them down and up again, and again after a run that stopped half way. On PostgreSQL it also leaves an invalid index from a failed concurrent build and shows that the next run builds it again.
+- A generator test generates all eight migrations and runs RuboCop with the omakase config on them.
+- The token handoff is tested in transactional tests (the helper and the dashboard) and with real commits.
+
+## [0.8.0] - 2026-10-25
+
+### Added
+
+- `config.require_bearer_scheme`. When true, the authentication header is accepted only as `Bearer <token>` (any case, spaces or tabs after the scheme); a bare token, another scheme such as `Basic`, or a lone `Bearer` gets the ordinary 401 `invalid_token`, is never looked up, and never falls back to `config.query_param`. It applies to whichever header `config.header` names. The default, false, keeps accepting a bare token as every earlier version did. Asked for by ReplyBrain, whose public API should parse one credential shape only.
+
 ## [0.7.0] - 2026-10-24
 
 Four features that an invoicing app on the fleet runs in production today, moved into the gem with their tests so that apps on the fleet can delete their own copies. Each one is opt-in: an app that does not use it sees no change.

data/README.md

@@ -32,6 +32,8 @@ And you're done!
 
 ### Upgrading an existing installation
 
+Every upgrade generator below writes a migration that strong_migrations accepts on PostgreSQL (0.8.1). There the indexes on `api_keys` are built concurrently, and the restrictions check constraint is validated apart, outside a transaction, so writes to `api_keys` go on. If a concurrent build fails (a lock or statement timeout, for example), PostgreSQL keeps an invalid index; the next run of the migration removes it and builds it again. On MySQL strong_migrations accepts all of them except `add_restrictions`, which it refuses twice: first at `add_column`, for the callable `JSON_OBJECT()` default (`add_column_default_callable`), then at the check constraint, which MySQL adds by copying the table. On MySQL with strong_migrations, check the size of `api_keys` first. Then wrap the whole body of `up` in the generated migration (the column and the constraint) in `safety_assured do ... end`, and run it when `api_keys` can be locked for the copy, for example in a maintenance window.
+
 Install the bounded bcrypt authentication lookup index before deploying the current hardening changes:
 
 ```bash
@@ -66,6 +68,8 @@ rails generate api_keys:add_created_by
 rails db:migrate
 ```
 
+On PostgreSQL this migration builds its index concurrently, outside a transaction, so it does not block writes to `api_keys` and strong_migrations accepts it (0.8.1). Each step checks what exists, so a run that stopped half way can run again, and an invalid index from a failed concurrent build is built again.
+
 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
@@ -91,7 +95,7 @@ On 0.6.x, nothing changes until you opt in to a 0.7.0 feature. A 0.6.0 job worke
 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.
+- 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. The transaction of a transactional test does not count (0.8.1).
 - 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
@@ -554,6 +558,7 @@ The database applies it atomically, and the claim commits before the token is re
 
 - **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.
+- **In a transactional test, the token is released once, as in production (0.8.1).** Rails' transactional tests (also rspec-rails and DatabaseCleaner's `:transaction` strategy) open one outer, non-joinable transaction around each test, and a system test's server thread shares it. When `Rails.env` is test and that is the only open transaction, the claim runs in it: the first retrieval in the test returns the token, and a second one, or one from a copy of the session, does not. The rollback at the end of the test removes the key with its claim. A transaction that the app or the test opens on top of it still refuses the retrieval, as in production, so a test sees a host `around_action` that would break the token page. From 0.6.0 to 0.8.0 every retrieval in a transactional test was refused. The check reads the shape of the transaction, not where it came from, so three cases follow. In a test without a transaction of its own (`use_transactional_tests = false`, or truncation), an outer `transaction(joinable: false)` that the app opens is exempt too, where production refuses it. An environment with another name (`ci`, `staging`) is never exempt: only `Rails.env` test is. A test transaction inside another one (fixtures and DatabaseCleaner's `:transaction` strategy together) is two deep, so it is refused, as in 0.8.0. No setting turns this on: apps whose tests broke on 0.6.0 need no new configuration.
 - **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.
@@ -1298,9 +1303,19 @@ See the [Key Types](#key-types-stripe-style-publishable--secret-keys) section be
 
 Some highlights:
 
+### Require the `Bearer` scheme
+
+Clients send `Authorization: Bearer ak_123abc...`. For compatibility, a bare `Authorization: ak_123abc...` is accepted too. A public API should accept one shape only, so turn the bare token off:
+
+```ruby
+config.require_bearer_scheme = true
+```
+
+Now a header without the scheme (a bare token, `Basic …`, `Token …`) gets the same 401 `invalid_token` as any wrong key, and is never looked up. It applies to whichever header you configured in `config.header`, and a refused header never falls back to the query parameter.
+
 ### Accept API keys via query params instead of Authentication HTTP headers
 
-By default, the `api_key` gem expects API keys to come *exclusively* as HTTP Authentication Bearer tokens, for security purposes. But you can allow users to make requests to your endpoints with the API key token passed as a URL query param too, like this:
+By default, the `api_key` gem expects API keys to come *exclusively* in the `Authorization` header, for security purposes. But you can allow users to make requests to your endpoints with the API key token passed as a URL query param too, like this:
 
 ```
 https://example.com/api/endpoint?api_key=ak_123abc...
@@ -1869,6 +1884,12 @@ bundle exec appraisal rails-8.0 rake test
 bundle exec appraisal rails-8.1 rake test
 ```
 
+`test/databases/check.rb` runs the generated upgrade migrations as `rails db:migrate` runs them, with strong_migrations, and the row locks of Idempotency-Key and the device flow, on a real database. CI runs it on PostgreSQL, MySQL and SQLite:
+
+```bash
+BUNDLE_GEMFILE=test/databases/Gemfile DB_ADAPTER=postgresql bundle exec ruby test/databases/check.rb
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then run `bundle exec rake test`. You can also run `bin/console` for an interactive prompt.

data/lib/api_keys/configuration.rb

@@ -16,7 +16,13 @@ module ApiKeys
     # == Accessors ==
 
     # Core Authentication
-    attr_reader :header, :query_param
+    #
+    # @!attribute [rw] require_bearer_scheme
+    #   @return [Boolean] Accept the header only as "Bearer <token>". A value
+    #     without the scheme is refused like any invalid token (401
+    #     `invalid_token`). false (the default) also accepts the bare token,
+    #     as every earlier version did.
+    attr_reader :header, :query_param, :require_bearer_scheme
 
     # Token Generation
     attr_reader :token_prefix, :token_length, :token_alphabet
@@ -192,7 +198,7 @@ module ApiKeys
     BOOLEAN_SETTINGS = %i[
       require_key_name track_requests_count https_only_production https_strict_mode
       enable_async_operations debug_logging strict_environment_isolation
-      dashboard_allow_cross_environment
+      dashboard_allow_cross_environment require_bearer_scheme
     ].freeze
 
     def header=(value)
@@ -301,7 +307,7 @@ module ApiKeys
 
     def idempotency_in_test_transactions=(value)
       raise ArgumentError, "idempotency_in_test_transactions must be true or false" unless [true, false].include?(value)
-      if value && !test_environment?
+      if value && !ApiKeys.test_environment?
         raise ArgumentError, "idempotency_in_test_transactions is for transactional tests only: Rails.env must be test"
       end
 
@@ -311,7 +317,7 @@ module ApiKeys
     # Whether hold may run inside an open transaction: the switch is on, and
     # Rails.env is still test when it is used.
     def idempotency_in_test_transactions?
-      @idempotency_in_test_transactions == true && test_environment?
+      @idempotency_in_test_transactions == true && ApiKeys.test_environment?
     end
 
     def trusted_key_check=(value)
@@ -448,10 +454,6 @@ module ApiKeys
 
     private
 
-    def test_environment?
-      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test? ? true : false
-    end
-
     def validate_resolved_prefix!(prefix)
       valid = prefix.is_a?(String) && prefix.present? && prefix.valid_encoding? && prefix.bytesize <= 64 &&
         prefix.each_codepoint.none? { |codepoint| codepoint <= 0x20 || codepoint == 0x7f }
@@ -633,6 +635,7 @@ module ApiKeys
       # Core Authentication
       @header = "Authorization" # Expects "Bearer <token>"
       @query_param = nil # No query param lookup by default
+      @require_bearer_scheme = false # Also accept a bare token in the header
 
       # Token Generation
       @token_prefix = -> { "ak_" }

data/lib/api_keys/helpers/token_session.rb

@@ -43,6 +43,12 @@ module ApiKeys
     #    opened with raw SQL (`BEGIN`) is not detected. The dashboard opens no
     #    transaction itself; a host `around_action` that wraps its requests in
     #    one sees the refusal.
+    #
+    #    The transaction that a transactional test opens around each test does
+    #    not count (0.8.1): when Rails.env is test and the only open
+    #    transaction is an outer, non-joinable one, the claim runs in it. The
+    #    first retrieval in the test returns the token and a second one does
+    #    not, as in production. A transaction opened on top of it is refused.
     # 2. Cache marker (0.5.1): each handoff has a random ID, and retrieval
     #    records it in `Rails.cache` with `write(..., unless_exist: true)`;
     #    a later retrieval of the same handoff finds the marker and gets nil.
@@ -94,7 +100,8 @@ module ApiKeys
       #   transaction on the ApiKey connection, where its one-time claim could
       #   be rolled back after the token was shown. The token is withheld,
       #   nothing is recorded, and the handoff stays in the session for a
-      #   retry outside the transaction.
+      #   retry outside the transaction. The transaction of a transactional
+      #   test does not count; one opened on top of it does.
       # - `:missing`: no usable handoff for this key (none stored, expired,
       #   tampered, or bound to another key).
       #
@@ -303,7 +310,36 @@ module ApiKeys
           return false if stored_id.nil? || !defined?(::ApiKeys::ApiKey)
           return false unless ::ApiKeys::ApiKey.column_names.include?(::ApiKeys::ApiKey::TOKEN_SHOWN_AT_COLUMN)
 
-          ::ApiKeys::ApiKey.connection_pool.with_connection(&:transaction_open?)
+          ::ApiKeys::ApiKey.connection_pool.with_connection do |connection|
+            connection.transaction_open? && !only_test_transaction_open?(connection)
+          end
+        end
+
+        # Whether the only open transaction on +connection+ is the one a
+        # transactional test opens around each test. Rails' transactional
+        # tests (and rspec-rails, and DatabaseCleaner's :transaction strategy)
+        # open it as one outer, non-joinable transaction, and a system test's
+        # server thread shares it. A claim in it is as durable as every other
+        # write of the test: the test sees it, a second retrieval in the same
+        # test is refused, and the rollback at the end of the test removes the
+        # key with it. A transaction that the app or the test opens on top of
+        # it still refuses the retrieval, as in production.
+        #
+        # The check reads the shape of the transaction, not where it came
+        # from, so three cases follow:
+        # - In a test without a transaction of its own, an outer
+        #   `transaction(joinable: false)` that the app opens is exempt too.
+        #   Production refuses it.
+        # - An environment with another name (`ci`, `staging`) is never
+        #   exempt: only Rails.env test is.
+        # - A test transaction inside another one (fixtures and
+        #   DatabaseCleaner's :transaction strategy together) is two deep, so
+        #   it is not exempt, as in 0.8.0.
+        def only_test_transaction_open?(connection)
+          return false unless ApiKeys.test_environment?
+          return false unless connection.open_transactions == 1
+
+          !connection.current_transaction.joinable?
         end
 
         # Inside a transaction the claim is not durable until the host commits,

data/lib/api_keys/services/authenticator.rb

@@ -18,8 +18,9 @@ module ApiKeys
       # The longest authentication header that can still carry a valid token:
       # the token plus the "Bearer" scheme and generous separator whitespace.
       MAX_CREDENTIAL_HEADER_BYTESIZE = MAX_TOKEN_BYTESIZE + 64
-      # Stands in for a header refused before parsing. It is not a String, so
-      # it can never match a key and always yields :invalid_token.
+      # Stands in for a refused header: malformed, or without the Bearer
+      # scheme the app requires. It is not a String, so it can never match a
+      # key and always yields :invalid_token.
       MALFORMED_CREDENTIAL = Object.new.freeze
       MAX_BCRYPT_CANDIDATES = 32
       MAX_KNOWN_PREFIXES = 1_024
@@ -146,7 +147,13 @@ module ApiKeys
               log_debug "[ApiKeys Auth] Extracted token from Bearer scheme."
               return match[1]
             end
-            # Fallback: return the raw header value if no Bearer scheme
+            # A bare token is accepted unless the app requires the scheme.
+            # Refused, it is an invalid token: the header was present, so it
+            # never falls through to the query parameter.
+            if config.require_bearer_scheme
+              log_debug "[ApiKeys Auth] Refused a header without the Bearer scheme."
+              return MALFORMED_CREDENTIAL
+            end
             log_debug "[ApiKeys Auth] No Bearer scheme, using raw header value as token."
             return header_value
           end

data/lib/api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  VERSION = "0.7.0"
+  VERSION = "0.8.1"
 end

data/lib/api_keys.rb

@@ -43,6 +43,14 @@ module ApiKeys
       @configuration = ::ApiKeys::Configuration.new
     end
 
+    # Whether Rails.env is test, read at each call. The test-only exemptions
+    # use it: config.idempotency_in_test_transactions, and the one-time token
+    # handoff inside a transactional test's own transaction.
+    # @return [Boolean]
+    def test_environment?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test? ? true : false
+    end
+
     # Add-only backfill after widening a key type's `permissions:` ceiling, for
     # types that keep stored scopes. See ApiKeys::ApiKey.reconcile_scopes!.
     # @return [Integer] How many keys gained scopes.

data/lib/generators/api_keys/templates/add_authentication_index_to_api_keys.rb.erb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# On PostgreSQL the index is built concurrently, outside a transaction, so
+# api_keys takes writes while it builds, and strong_migrations accepts the
+# migration. If a concurrent build fails, PostgreSQL keeps an invalid index;
+# the next run removes it and builds it again.
 class AddAuthenticationIndexToApiKeys < ActiveRecord::Migration<%= migration_version %>
   INDEX_NAME = "index_api_keys_authentication_lookup"
   COLUMNS = %i[prefix last4 digest_algorithm].freeze
@@ -7,18 +11,35 @@ class AddAuthenticationIndexToApiKeys < ActiveRecord::Migration<%= migration_ver
   disable_ddl_transaction!
 
   def up
+    remove_invalid_index
     return if index_exists?(:api_keys, COLUMNS, name: INDEX_NAME)
 
-    options = { name: INDEX_NAME }
-    options[:algorithm] = :concurrently if connection.adapter_name.downcase.include?("postgres")
-    add_index :api_keys, COLUMNS, **options
+    add_index :api_keys, COLUMNS, name: INDEX_NAME, **index_algorithm
   end
 
   def down
     return unless index_exists?(:api_keys, COLUMNS, name: INDEX_NAME)
 
-    options = { name: INDEX_NAME }
-    options[:algorithm] = :concurrently if connection.adapter_name.downcase.include?("postgres")
-    remove_index :api_keys, **options
+    remove_index :api_keys, name: INDEX_NAME, **index_algorithm
+  end
+
+  private
+
+  # Concurrently on PostgreSQL (and PostGIS). MySQL and SQLite have no
+  # concurrent build and refuse the option.
+  def index_algorithm
+    connection.adapter_name.downcase.include?("postg") ? { algorithm: :concurrently } : {}
+  end
+
+  # A concurrent build that fails (a lock or statement timeout, for example)
+  # leaves an invalid index on PostgreSQL, which index_exists? still finds.
+  # Treat it as absent: remove it, so that the next step builds it again.
+  # (IndexDefinition#valid? exists from Rails 7.1. The migrator's lock keeps
+  # a second run from removing an index that another run still builds.)
+  def remove_invalid_index
+    index = connection.indexes(:api_keys).find { |candidate| candidate.name == INDEX_NAME }
+    return unless index.respond_to?(:valid?) && !index.valid?
+
+    remove_index :api_keys, name: INDEX_NAME, **index_algorithm
   end
 end

data/lib/generators/api_keys/templates/add_created_by_to_api_keys.rb.erb

@@ -9,13 +9,29 @@
 #
 # Run this migration if you're upgrading from a version of api_keys before
 # 0.7.0. New installs get the columns from the install generator. Existing
-# keys keep NULL. The migration is idempotent: columns that already exist are
-# left alone.
+# keys keep NULL.
+#
+# On PostgreSQL the index is built concurrently, so api_keys takes writes
+# while it builds, and strong_migrations accepts the migration. A concurrent
+# build cannot run inside a transaction, so this migration runs without one.
+# Each step checks what exists, so a run that stopped half way can run
+# again. If a concurrent build fails, PostgreSQL keeps an invalid index; the
+# next run removes it and builds it again. MySQL and SQLite build the
+# index as usual.
 class AddCreatedByToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  INDEX_NAME = "index_api_keys_on_created_by"
+  INDEX_COLUMNS = %i[created_by_type created_by_id].freeze
+
+  disable_ddl_transaction!
+
   def up
-    return if column_exists?(:api_keys, :created_by_id)
+    unless column_exists?(:api_keys, :created_by_id)
+      add_reference :api_keys, :created_by, polymorphic: true, null: true, type: foreign_key_type, index: false
+    end
+    remove_invalid_index(INDEX_COLUMNS)
+    return if index_exists?(:api_keys, INDEX_COLUMNS)
 
-    add_reference :api_keys, :created_by, polymorphic: true, null: true, type: foreign_key_type
+    add_index :api_keys, INDEX_COLUMNS, name: INDEX_NAME, **index_algorithm
   end
 
   def down
@@ -30,4 +46,22 @@ class AddCreatedByToApiKeys < ActiveRecord::Migration<%= migration_version %>
     generators = Rails.application&.config&.generators
     generators&.options&.dig(generators.orm, :primary_key_type) || :bigint
   end
+
+  # Concurrently on PostgreSQL (and PostGIS). MySQL and SQLite have no
+  # concurrent build and refuse the option.
+  def index_algorithm
+    connection.adapter_name.downcase.include?("postg") ? { algorithm: :concurrently } : {}
+  end
+
+  # A concurrent build that fails (a lock or statement timeout, for example)
+  # leaves an invalid index on PostgreSQL, which index_exists? still finds.
+  # Treat it as absent: remove it, so that the next step builds it again.
+  # (IndexDefinition#valid? exists from Rails 7.1. The migrator's lock keeps
+  # a second run from removing an index that another run still builds.)
+  def remove_invalid_index(columns)
+    index = connection.indexes(:api_keys).find { |candidate| candidate.columns == Array(columns).map(&:to_s) }
+    return unless index.respond_to?(:valid?) && !index.valid?
+
+    remove_index :api_keys, name: index.name, **index_algorithm
+  end
 end

data/lib/generators/api_keys/templates/add_key_types_to_api_keys.rb.erb

@@ -5,14 +5,71 @@
 #
 # Run this migration if you're upgrading from a version of api_keys that
 # didn't have key types support.
+#
+# On PostgreSQL the indexes are built concurrently, so api_keys takes writes
+# while they build, and strong_migrations accepts the migration. A concurrent
+# build cannot run inside a transaction, so this migration runs without one.
+# Each step checks what exists, so a run that stopped half way can run
+# again. If a concurrent build fails, PostgreSQL keeps an invalid index; the
+# next run removes it and builds it again. MySQL and SQLite build the
+# indexes as usual.
 class AddKeyTypesToApiKeys < ActiveRecord::Migration<%= migration_version %>
-  def change
-    add_column :api_keys, :key_type, :string
-    add_column :api_keys, :environment, :string
-
-    add_index :api_keys, :key_type
-    add_index :api_keys, :environment
-    add_index :api_keys, [:owner_type, :owner_id, :key_type, :environment],
-              name: "index_api_keys_owner_type_env"
+  OWNER_TYPE_ENV_INDEX = "index_api_keys_owner_type_env"
+  OWNER_TYPE_ENV_COLUMNS = %i[owner_type owner_id key_type environment].freeze
+
+  disable_ddl_transaction!
+
+  def up
+    add_column :api_keys, :key_type, :string unless column_exists?(:api_keys, :key_type)
+    add_column :api_keys, :environment, :string unless column_exists?(:api_keys, :environment)
+
+    %i[key_type environment].each do |column|
+      remove_invalid_index(column)
+      add_index :api_keys, column, **index_algorithm unless index_exists?(:api_keys, column)
+    end
+    remove_invalid_index(OWNER_TYPE_ENV_COLUMNS)
+    return if index_exists?(:api_keys, OWNER_TYPE_ENV_COLUMNS)
+
+    # strong_migrations calls a non-unique index of more than three columns
+    # a best-practice problem. The install migration has the same index, so
+    # this migration keeps it and tells strong_migrations so.
+    with_safety_assured do
+      add_index :api_keys, OWNER_TYPE_ENV_COLUMNS, name: OWNER_TYPE_ENV_INDEX, **index_algorithm
+    end
+  end
+
+  def down
+    if index_exists?(:api_keys, OWNER_TYPE_ENV_COLUMNS)
+      remove_index :api_keys, name: OWNER_TYPE_ENV_INDEX, **index_algorithm
+    end
+    remove_index :api_keys, :environment, **index_algorithm if index_exists?(:api_keys, :environment)
+    remove_index :api_keys, :key_type, **index_algorithm if index_exists?(:api_keys, :key_type)
+    remove_column :api_keys, :environment if column_exists?(:api_keys, :environment)
+    remove_column :api_keys, :key_type if column_exists?(:api_keys, :key_type)
+  end
+
+  private
+
+  # Concurrently on PostgreSQL (and PostGIS). MySQL and SQLite have no
+  # concurrent build and refuse the option.
+  def index_algorithm
+    connection.adapter_name.downcase.include?("postg") ? { algorithm: :concurrently } : {}
+  end
+
+  # A concurrent build that fails (a lock or statement timeout, for example)
+  # leaves an invalid index on PostgreSQL, which index_exists? still finds.
+  # Treat it as absent: remove it, so that the next step builds it again.
+  # (IndexDefinition#valid? exists from Rails 7.1. The migrator's lock keeps
+  # a second run from removing an index that another run still builds.)
+  def remove_invalid_index(columns)
+    index = connection.indexes(:api_keys).find { |candidate| candidate.columns == Array(columns).map(&:to_s) }
+    return unless index.respond_to?(:valid?) && !index.valid?
+
+    remove_index :api_keys, name: index.name, **index_algorithm
+  end
+
+  # strong_migrations' safety_assured when the app uses strong_migrations.
+  def with_safety_assured(&block)
+    respond_to?(:safety_assured) ? safety_assured(&block) : yield
   end
 end

data/lib/generators/api_keys/templates/add_restrictions_to_api_keys.rb.erb

@@ -8,47 +8,86 @@
 # Run this migration if you're upgrading from a version of api_keys that
 # didn't have request restrictions support. The column defaults to an empty
 # object, which means "unrestricted", so existing keys are unaffected.
+#
+# On PostgreSQL the check constraint is added first without a check of the
+# existing rows, then validated, which does not block reads and writes, so
+# strong_migrations accepts the migration. It runs without a transaction, so
+# the validation holds no lock from the earlier steps. Each step checks what
+# exists, so a run that stopped half way can run again. MySQL refuses a
+# literal default on a JSON column, so there the default is the expression
+# JSON_OBJECT() (MySQL 8.0.13 or later). On MySQL strong_migrations refuses
+# this migration twice: first the column, for its callable default, then the
+# check constraint, which MySQL adds by copying the table. Check the size of
+# api_keys first. Then wrap the whole body of up (the column and the
+# constraint) in `safety_assured do ... end`, and run it when api_keys can be
+# locked for the copy, for example in a maintenance window.
 class AddRestrictionsToApiKeys < ActiveRecord::Migration<%= migration_version %>
   CONSTRAINT_NAME = "api_keys_restrictions_is_object"
 
+  disable_ddl_transaction!
+
   def up
-    add_column :api_keys, :restrictions, json_column_type, default: {}, null: false
+    unless column_exists?(:api_keys, :restrictions)
+      add_column :api_keys, :restrictions, json_column_type, default: restrictions_default, null: false
+    end
     add_restrictions_object_constraint
   end
 
   def down
-    remove_column :api_keys, :restrictions
+    remove_check_constraint :api_keys, name: CONSTRAINT_NAME if restrictions_constraint_exists?
+    remove_column :api_keys, :restrictions if column_exists?(:api_keys, :restrictions)
   end
 
   private
 
   # Helper method to determine the appropriate JSON column type based on the database adapter.
-  # Uses :jsonb for PostgreSQL for better performance and indexing, :json otherwise.
+  # Uses :jsonb for PostgreSQL (and PostGIS) for better performance and indexing, :json otherwise.
   def json_column_type
-    # Check connection availability for adapter name inspection
-    if ActiveRecord::Base.connection.adapter_name.downcase.include?('postgresql')
-      :jsonb
-    else
-      :json
-    end
+    postgresql? ? :jsonb : :json
   rescue ActiveRecord::ConnectionNotEstablished
     # Fallback during initial setup or if connection isn't available
     :text
   end
 
+  # MySQL refuses a literal default on a JSON column, but takes an
+  # expression, which also fills the existing rows with an empty object.
+  def restrictions_default
+    connection.adapter_name.downcase.match?(/mysql|trilogy/) ? -> { "(JSON_OBJECT())" } : {}
+  end
+
   # JSON columns can also hold arrays and scalars. The application requires an
   # object so damaged or validation-bypassing writes cannot erase a policy.
   def add_restrictions_object_constraint
     return unless connection.supports_check_constraints?
 
-    expression = case connection.adapter_name.downcase
-                 when /postgres/
-                   "jsonb_typeof(restrictions) = 'object'"
-                 when /sqlite/
-                   "json_valid(restrictions) AND json_type(restrictions) = 'object'"
-                 when /mysql|trilogy/
-                   "JSON_TYPE(restrictions) = 'OBJECT'"
-                 end
-    add_check_constraint :api_keys, expression, name: CONSTRAINT_NAME if expression
+    expression =
+      case connection.adapter_name.downcase
+      when /postg/
+        "jsonb_typeof(restrictions) = 'object'"
+      when /sqlite/
+        "json_valid(restrictions) AND json_type(restrictions) = 'object'"
+      when /mysql|trilogy/
+        "JSON_TYPE(restrictions) = 'OBJECT'"
+      end
+    return unless expression
+
+    unless restrictions_constraint_exists?
+      # On PostgreSQL, add the constraint without a check of the existing
+      # rows: this takes a short lock only.
+      add_check_constraint :api_keys, expression, name: CONSTRAINT_NAME, **(postgresql? ? { validate: false } : {})
+    end
+    # Checks the existing rows without blocking reads and writes. Nothing
+    # happens when the constraint is valid already.
+    validate_check_constraint :api_keys, name: CONSTRAINT_NAME if postgresql?
+  end
+
+  def restrictions_constraint_exists?
+    return false unless connection.supports_check_constraints?
+
+    connection.check_constraints(:api_keys).any? { |constraint| constraint.name == CONSTRAINT_NAME }
+  end
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postg")
   end
 end

data/lib/generators/api_keys/templates/create_api_keys_device_authorizations.rb.erb

@@ -10,8 +10,6 @@
 # Only apps that use the device flow need this table.
 class CreateApiKeysDeviceAuthorizations < ActiveRecord::Migration<%= migration_version %>
   def change
-    primary_key_type, foreign_key_type = primary_and_foreign_key_types
-
     create_table :api_keys_device_authorizations, id: primary_key_type do |t|
       t.string :device_code_digest, null: false, index: { unique: true }
       t.string :user_code_digest, null: false, index: { unique: true }
@@ -42,16 +40,23 @@ class CreateApiKeysDeviceAuthorizations < ActiveRecord::Migration<%= migration_v
 
   # The key types the install generator gives the api_keys table: the app's
   # `primary_key_type` generator setting, else Rails' defaults.
-  def primary_and_foreign_key_types
+  def primary_key_type
+    primary_key_type_setting || :primary_key
+  end
+
+  def foreign_key_type
+    primary_key_type_setting || :bigint
+  end
+
+  def primary_key_type_setting
     generators = Rails.application&.config&.generators
-    setting = generators&.options&.dig(generators.orm, :primary_key_type)
-    [setting || :primary_key, setting || :bigint]
+    generators&.options&.dig(generators.orm, :primary_key_type)
   end
 
   # The type of api_keys.id, so that the foreign key matches it exactly.
   def api_key_id_type
     column = connection.columns(:api_keys).find { |candidate| candidate.name == "id" }
-    return primary_and_foreign_key_types.last unless column
+    return foreign_key_type unless column
 
     sql_type = column.sql_type.to_s.downcase
     if sql_type.include?("uuid")

data/lib/generators/api_keys/templates/create_api_keys_idempotency_keys.rb.erb

@@ -10,8 +10,6 @@
 # Only apps that use ApiKeys::Idempotency need this table.
 class CreateApiKeysIdempotencyKeys < ActiveRecord::Migration<%= migration_version %>
   def change
-    primary_key_type, foreign_key_type = primary_and_foreign_key_types
-
     create_table :api_keys_idempotency_keys, id: primary_key_type do |t|
       # Each API key has its own keys. A deleted API key takes them with it.
       t.references :api_key, null: false, type: api_key_id_type, foreign_key: { on_delete: :cascade }, index: false
@@ -21,7 +19,7 @@ class CreateApiKeysIdempotencyKeys < ActiveRecord::Migration<%= migration_versio
       t.references :resource, polymorphic: true, null: true, type: foreign_key_type, index: false
       t.timestamps
       t.index :created_at
-      t.index [:api_key_id, :key], unique: true
+      t.index %i[api_key_id key], unique: true
     end
   end
 
@@ -29,16 +27,23 @@ class CreateApiKeysIdempotencyKeys < ActiveRecord::Migration<%= migration_versio
 
   # The key types the install generator gives the api_keys table: the app's
   # `primary_key_type` generator setting, else Rails' defaults.
-  def primary_and_foreign_key_types
+  def primary_key_type
+    primary_key_type_setting || :primary_key
+  end
+
+  def foreign_key_type
+    primary_key_type_setting || :bigint
+  end
+
+  def primary_key_type_setting
     generators = Rails.application&.config&.generators
-    setting = generators&.options&.dig(generators.orm, :primary_key_type)
-    [setting || :primary_key, setting || :bigint]
+    generators&.options&.dig(generators.orm, :primary_key_type)
   end
 
   # The type of api_keys.id, so that the foreign key matches it exactly.
   def api_key_id_type
     column = connection.columns(:api_keys).find { |candidate| candidate.name == "id" }
-    return primary_and_foreign_key_types.last unless column
+    return foreign_key_type unless column
 
     sql_type = column.sql_type.to_s.downcase
     if sql_type.include?("uuid")

data/lib/generators/api_keys/templates/create_api_keys_table.rb.erb

@@ -5,8 +5,6 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
   RESTRICTIONS_CONSTRAINT_NAME = "api_keys_restrictions_is_object"
 
   def change
-    primary_key_type, foreign_key_type = primary_and_foreign_key_types
-
     create_table :api_keys, id: primary_key_type do |t|
       # Identifiable prefix (e.g., "ak_live_", "ak_test_") for env/debugging
       t.string   :prefix,        null: false
@@ -76,8 +74,8 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       t.index :token_digest, unique: true
 
       # Index to optimize prefix-based lookups (especially for bcrypt)
-      t.index [:prefix, :digest_algorithm], name: "index_api_keys_on_prefix_and_digest_algorithm"
-      t.index [:prefix, :last4, :digest_algorithm], name: "index_api_keys_authentication_lookup"
+      t.index %i[prefix digest_algorithm], name: "index_api_keys_on_prefix_and_digest_algorithm"
+      t.index %i[prefix last4 digest_algorithm], name: "index_api_keys_authentication_lookup"
 
       # Optional indexes
       t.index :prefix
@@ -87,7 +85,7 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       t.index :last_used_at
       t.index :key_type
       t.index :environment
-      t.index [:owner_type, :owner_id, :key_type, :environment], name: "index_api_keys_owner_type_env"
+      t.index %i[owner_type owner_id key_type environment], name: "index_api_keys_owner_type_env"
     end
 
     add_restrictions_object_constraint
@@ -95,14 +93,19 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
 
   private
 
-  # Helper method to determine the appropriate primary and foreign key types
+  # Helper methods to determine the appropriate primary and foreign key types
   # based on the Rails application's configuration.
-  def primary_and_foreign_key_types
+  def primary_key_type
+    primary_key_type_setting || :primary_key
+  end
+
+  def foreign_key_type
+    primary_key_type_setting || :bigint # Assuming bigint is a safe default for foreign keys
+  end
+
+  def primary_key_type_setting
     config = Rails.configuration.generators
-    setting = config.options[config.orm][:primary_key_type]
-    primary_key_type = setting || :primary_key
-    foreign_key_type = setting || :bigint # Assuming bigint is a safe default for foreign keys
-    [primary_key_type, foreign_key_type]
+    config.options[config.orm][:primary_key_type]
   end
 
   # Helper method to determine the appropriate JSON column type based on the database adapter.
@@ -122,14 +125,15 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
   def add_restrictions_object_constraint
     return unless connection.supports_check_constraints?
 
-    expression = case connection.adapter_name.downcase
-                 when /postgres/
-                   "jsonb_typeof(restrictions) = 'object'"
-                 when /sqlite/
-                   "json_valid(restrictions) AND json_type(restrictions) = 'object'"
-                 when /mysql|trilogy/
-                   "JSON_TYPE(restrictions) = 'OBJECT'"
-                 end
+    expression =
+      case connection.adapter_name.downcase
+      when /postgres/
+        "jsonb_typeof(restrictions) = 'object'"
+      when /sqlite/
+        "json_valid(restrictions) AND json_type(restrictions) = 'object'"
+      when /mysql|trilogy/
+        "JSON_TYPE(restrictions) = 'OBJECT'"
+      end
     add_check_constraint :api_keys, expression, name: RESTRICTIONS_CONSTRAINT_NAME if expression
   end
 end

data/lib/generators/api_keys/templates/initializer.rb

@@ -9,6 +9,11 @@ ApiKeys.configure do |config|
   # Default: "Authorization" (expects "Bearer <token>")
   # config.header = "Authorization"
 
+  # Accept the header only as "Bearer <token>", refusing a bare token with
+  # 401 invalid_token. Recommended for public APIs.
+  # Default: false (a bare token is accepted too)
+  # config.require_bearer_scheme = true
+
   # The query parameter name to check as a fallback if the header is missing.
   # WARNING: Query parameters appear in logs, browser history, and Referer headers.
   # Only enable for development/testing. Set to nil to disable (recommended).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - rameerez