api_keys 0.5.1 → 0.6.0

data/lib/api_keys.rb

@@ -42,6 +42,13 @@ module ApiKeys
     def reset_configuration!
       @configuration = ::ApiKeys::Configuration.new
     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.
+    def reconcile_scopes!(key_type:)
+      ::ApiKeys::ApiKey.reconcile_scopes!(key_type: key_type)
+    end
   end
 end
 

data/lib/generators/api_keys/add_key_activity_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for the columns api_keys 0.6.0 adds to the api_keys
+    # table, in one migration:
+    #
+    # - `last_refused_at`, `refusals_count`, `last_refusal_code`: requests that
+    #   presented a key's real token and were refused by a policy.
+    # - `token_shown_at`: when the key's token was released through the
+    #   one-time dashboard handoff, which makes that handoff durable.
+    #
+    # This generator is for existing installations; new installs get the
+    # columns from the install generator, so they never need to run this.
+    class AddKeyActivityGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      # Creates the migration file using the template.
+      def create_migration_file
+        migration_template "add_key_activity_to_api_keys.rb.erb",
+                           File.join(db_migrate_path, "add_key_activity_to_api_keys.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🚦 api_keys 0.6.0 key activity migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to add last_refused_at, refusals_count,"
+        say "     last_refusal_code and token_shown_at."
+        say "\n  2. That's it. Requests that present a key's real token and are refused"
+        say "     (origin/IP restrictions, environment, missing scope, revoked, expired...)"
+        say "     are now stamped on the key, through the same background stats job as"
+        say "     last_used_at, and the dashboard shows them on the key's page."
+        say "     A refusal never moves last_used_at or requests_count."
+        say "     refusals_count, like requests_count, is only kept with `config.track_requests_count = true`."
+        say "\n     The one-time token page now records the first retrieval in token_shown_at,"
+        say "     so a copied session cannot show a token twice, even after a cache flush."
+        say "\nSee the api_keys README for detailed usage and examples.", :cyan
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Migration to add the api_keys 0.6.0 columns to the api_keys table.
+#
+# `last_refused_at`, `refusals_count`, and `last_refusal_code` record requests
+# that presented a key's real token and were refused by a policy (origin or IP
+# restrictions, environment isolation, missing scope, revoked, expired...), so
+# the dashboard can say "requests are arriving but refused" instead of showing
+# a key nobody ever tried. They never touch `last_used_at` or `requests_count`.
+#
+# `token_shown_at` records when the key's token was released through the
+# one-time dashboard handoff. The first retrieval claims it with a single
+# conditional UPDATE, so a copy of the session cannot show the token again,
+# even after the cache is flushed. Existing keys keep NULL.
+#
+# Run this migration if you're upgrading from a version of api_keys before
+# 0.6.0. New installs get the columns from the install generator. Until it
+# runs, authentication works unchanged, refusals are simply not recorded, and
+# the token handoff relies on the cache marker alone, as in 0.5.1. The
+# migration is idempotent: columns that already exist are left alone.
+class AddKeyActivityToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :api_keys, :last_refused_at, :datetime unless column_exists?(:api_keys, :last_refused_at)
+    unless column_exists?(:api_keys, :refusals_count)
+      add_column :api_keys, :refusals_count, :bigint, default: 0, null: false
+    end
+    add_column :api_keys, :last_refusal_code, :string, limit: 64 unless column_exists?(:api_keys, :last_refusal_code)
+    add_column :api_keys, :token_shown_at, :datetime unless column_exists?(:api_keys, :token_shown_at)
+  end
+
+  def down
+    remove_column :api_keys, :token_shown_at if column_exists?(:api_keys, :token_shown_at)
+    remove_column :api_keys, :last_refusal_code if column_exists?(:api_keys, :last_refusal_code)
+    remove_column :api_keys, :refusals_count if column_exists?(:api_keys, :refusals_count)
+    remove_column :api_keys, :last_refused_at if column_exists?(:api_keys, :last_refused_at)
+  end
+end

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

@@ -45,6 +45,18 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       # Optional counter cache for total requests made with this key.
       t.bigint   :requests_count, default: 0, null: false
 
+      # Refused-but-identified traffic: requests that presented this key's real
+      # token and were refused by a policy (origin/IP lock, environment, scope,
+      # revoked, expired...). Kept apart from last_used_at, which a refusal never moves.
+      t.datetime :last_refused_at
+      t.bigint   :refusals_count, default: 0, null: false
+      t.string   :last_refusal_code, limit: 64
+
+      # When this key's token was released through the one-time dashboard
+      # handoff. The first retrieval claims it with a conditional UPDATE, so a
+      # copied session can never show the token twice.
+      t.datetime :token_shown_at
+
       # Timestamp when the key was revoked (null means active)
       t.datetime :revoked_at
 

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

@@ -148,11 +148,20 @@ ApiKeys.configure do |config|
   #                any subset of [:origins, :ips]. Omitted = both allowed.
   #                `restrictions: []` forbids restrictions for this type.
   #                See "REQUEST RESTRICTIONS" below.
+  # - scopes:      Where scope checks look. :stored (default) uses the scopes each
+  #                key saved at creation, so WIDENING `permissions` LATER DOES NOT
+  #                REACH EXISTING KEYS: they keep the old list and 403 new scopes.
+  #                :ceiling makes the live `permissions` list the contract for
+  #                every key of the type (widening and narrowing apply at once).
+  #                Use it for types whose users do not pick scopes; it requires a
+  #                finite, non-empty permissions list. For :stored types, backfill
+  #                after widening with ApiKeys.reconcile_scopes!(key_type: :name).
   #
   # config.key_types = {
   #   publishable: {
   #     prefix: "pk",                    # → pk_test_, pk_live_
   #     permissions: %w[read validate],  # Can ONLY have these scopes
+  #     scopes: :ceiling,                # Every pk key has exactly these, even after edits
   #     public: true,                    # Store token for later viewing in dashboard
   #     limit: 1,                        # Only 1 publishable key per environment
   #     restrictions: [:origins]         # Browser keys lock to domains, not IPs
@@ -344,9 +353,17 @@ ApiKeys.configure do |config|
 
   # Minimum interval between last_used_at jobs when exact request counting is
   # disabled. Set to 0 or nil to update on every successful authentication.
+  # The same interval debounces refusal stats (below).
   # Default: 1.minute
   # config.stats_update_interval = 1.minute
 
+  # Refused requests: when a request presents a key's real token and a policy
+  # refuses it (origin/IP lock, environment, missing scope, revoked, expired),
+  # the same stats job stamps last_refused_at and last_refusal_code (and
+  # refusals_count when track_requests_count is on). A refusal never moves
+  # last_used_at or requests_count. The dashboard shows it on the key's page.
+  # Existing installs: rails generate api_keys:add_key_activity && rails db:migrate
+
   # Queue names for background jobs.
   # Default: :default
   # config.stats_job_queue = :default

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - rameerez
@@ -84,6 +84,7 @@ files:
 - app/views/api_keys/keys/_key_status.html.erb
 - app/views/api_keys/keys/_keys_table.html.erb
 - app/views/api_keys/keys/_publishable_keys.html.erb
+- app/views/api_keys/keys/_refusal_notice.html.erb
 - app/views/api_keys/keys/_restriction_fields.html.erb
 - app/views/api_keys/keys/_secret_keys.html.erb
 - app/views/api_keys/keys/_show_token.html.erb
@@ -98,6 +99,9 @@ files:
 - docs/reviews/2026-10-18-0-5-1/01-astra-review-of-0-5-0.md
 - docs/reviews/2026-10-18-0-5-1/02-astra-re-review-of-0-5-1.md
 - docs/reviews/2026-10-18-0-5-1/03-opus-review-of-0-5-1.md
+- docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md
+- docs/reviews/2026-10-18-0-6-0/02-astra-re-review-of-0-6-0.md
+- docs/reviews/2026-10-18-0-6-0/03-sol-re-check-of-0-6-0.md
 - lib/api_keys.rb
 - lib/api_keys/authentication.rb
 - lib/api_keys/configuration.rb
@@ -120,10 +124,12 @@ files:
 - lib/api_keys/tenant_resolution.rb
 - lib/api_keys/version.rb
 - lib/generators/api_keys/add_authentication_index_generator.rb
+- lib/generators/api_keys/add_key_activity_generator.rb
 - lib/generators/api_keys/add_key_types_generator.rb
 - lib/generators/api_keys/add_restrictions_generator.rb
 - lib/generators/api_keys/install_generator.rb
 - lib/generators/api_keys/templates/add_authentication_index_to_api_keys.rb.erb
+- lib/generators/api_keys/templates/add_key_activity_to_api_keys.rb.erb
 - lib/generators/api_keys/templates/add_key_types_to_api_keys.rb.erb
 - lib/generators/api_keys/templates/add_restrictions_to_api_keys.rb.erb
 - lib/generators/api_keys/templates/create_api_keys_table.rb.erb