api_keys 0.5.0 → 0.6.0

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/add_restrictions_generator.rb

@@ -41,8 +41,11 @@ module ApiKeys
         say "                        restrictions: [:origins] },"
         say "         secret:      { prefix: 'sk', permissions: :all, restrictions: [:ips] }"
         say "       }"
-        say "\n  4. Behind a CDN or proxy, make sure the client IP is truthful:"
+        say "\n  4. Make sure the client IP is truthful before relying on allowed_ips:"
+        say "       # Behind a proxy that is the only way in: list it in trusted_proxies, keep the default."
         say "       config.action_dispatch.trusted_proxies = ..."
+        say "       # Rails directly reachable: check the socket peer, or X-Forwarded-For can be forged."
+        say "       config.client_ip_resolver = ->(request) { request.remote_addr }"
         say "       # Trust a vendor header only when ingress blocks requests that bypass that vendor."
         say "\nSee the api_keys README for detailed usage and examples.", :cyan
       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
@@ -300,14 +309,22 @@ ApiKeys.configure do |config|
   #   rails generate api_keys:add_restrictions && rails db:migrate
   # ============================================================================
 
-  # How the client IP is resolved for `allowed_ips` checks.
-  # The default trusts Rails' own resolution, which honors
-  # config.action_dispatch.trusted_proxies. Behind a CDN that terminates the
-  # connection, configure trusted_proxies whenever possible. Trust a vendor
-  # header directly only when your network ingress rejects requests that
-  # bypass that vendor; otherwise callers can spoof the address being checked.
-  # Default: ->(request) { request.remote_ip }
+  # How the client IP is resolved for `allowed_ips` checks. Pick the line that
+  # matches how clients reach this Rails server:
   #
+  # Behind a load balancer, reverse proxy, or CDN that is the ONLY way in and
+  # that overwrites or appends X-Forwarded-For, with its addresses covered by
+  # config.action_dispatch.trusted_proxies: keep the default.
+  # config.client_ip_resolver = ->(request) { request.remote_ip } # default
+  #
+  # Directly reachable (no proxy, or a proxy that can be bypassed): check the
+  # socket peer. With remote_ip, a client could send
+  # `X-Forwarded-For: <an allowed address>` and pass the check.
+  # config.client_ip_resolver = ->(request) { request.remote_addr }
+  #
+  # trusted_proxies alone is not a boundary: it does not stop a client that
+  # bypasses the proxy from sending the header. Trust a vendor header only
+  # when your network ingress rejects requests that bypass that vendor:
   # config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
 
   # ============================================================================
@@ -336,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.0
+  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
@@ -95,6 +96,12 @@ files:
 - app/views/api_keys/security/best_practices.html.erb
 - app/views/layouts/api_keys/application.html.erb
 - config/routes.rb
+- 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
@@ -117,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