api_keys 0.5.1 → 0.7.0

data/lib/generators/api_keys/add_idempotency_keys_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApiKeys
+  module Generators
+    # Rails generator for the Idempotency-Keys table (api_keys 0.7.0), which
+    # ApiKeys::Idempotency needs: each write under an Idempotency-Key runs
+    # once per API key, and a retry answers the record as it is now. New and
+    # existing installations run it alike.
+    class AddIdempotencyKeysGenerator < 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 "create_api_keys_idempotency_keys.rb.erb",
+                           File.join(db_migrate_path, "create_api_keys_idempotency_keys.rb")
+      end
+
+      # Displays helpful information to the user after installation.
+      def display_post_install_message
+        say "\n🔁 api_keys Idempotency-Keys migration created!", :green
+        say "\nNext steps:"
+        say "  1. Run `rails db:migrate` to create the api_keys_idempotency_keys table."
+        say "\n  2. In your API base controller, after authenticate_api_key!:"
+        say "       include ApiKeys::Idempotency"
+        say "       around_action :run_once_per_idempotency_key"
+        say "\n  3. Answer every write with render_resource(record, status: ...), and define"
+        say "     resource_json(record, **options) to render a record and"
+        say "     idempotent_replay_allowed?(record) to say whether current_api_key may read it."
+        say "     Keep the around_action outside any transaction your app opens."
+        say "\n  4. Run ApiKeys::IdempotencyKey.prune! once a day."
+        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_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_created_by_to_api_keys.rb.erb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Migration to add the person behind each key to the api_keys table
+# (api_keys 0.7.0): `created_by_type` and `created_by_id`, a polymorphic
+# reference, for keys whose owner is not a person (an organization).
+# `create_api_key!(created_by: current_user)` sets it, and
+# `config.trusted_key_check` can refuse a key once that person no longer
+# stands behind it.
+#
+# 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.
+class AddCreatedByToApiKeys < ActiveRecord::Migration<%= migration_version %>
+  def up
+    return if column_exists?(:api_keys, :created_by_id)
+
+    add_reference :api_keys, :created_by, polymorphic: true, null: true, type: foreign_key_type
+  end
+
+  def down
+    remove_reference :api_keys, :created_by, polymorphic: true if column_exists?(:api_keys, :created_by_id)
+  end
+
+  private
+
+  # The key type the install generator gives api_keys.owner_id: the app's
+  # `primary_key_type` generator setting, else :bigint.
+  def foreign_key_type
+    generators = Rails.application&.config&.generators
+    generators&.options&.dig(generators.orm, :primary_key_type) || :bigint
+  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_device_authorizations.rb.erb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Migration to create the table of device authorizations (api_keys 0.7.0).
+# Each row is a client's request for an API key on the OAuth 2.0 Device
+# Authorization Grant (RFC 8628), which a person approves or denies in your
+# app (ApiKeys::DeviceFlow, ApiKeys::DeviceAuthorization). Both codes are
+# kept as SHA-256 digests, never as text, and the key's token is never
+# stored.
+#
+# 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 }
+      # The client names itself, and every poll repeats it (RFC 8628 §3.4).
+      t.string :client_id, null: false
+      t.string :device_name
+      t.string :requested_from
+      # No default here: MySQL refuses a literal default on a JSON column.
+      # The model defaults scopes to [].
+      t.send(json_column_type, :scopes, null: false)
+      # The type of the key the approval makes, when key types are configured.
+      t.string :key_type
+      t.string :state, default: "pending", null: false
+      t.integer :interval, default: 5, null: false
+      t.datetime :expires_at, null: false, index: true
+      t.datetime :last_polled_at
+      # Who the key is for, and who decided: set when the person decides.
+      t.references :owner, polymorphic: true, null: true, type: foreign_key_type
+      t.references :decided_by, polymorphic: true, null: true, type: foreign_key_type
+      t.datetime :decided_at
+      # The key that the first poll after the approval created.
+      t.references :api_key, null: true, type: api_key_id_type, foreign_key: { on_delete: :nullify }
+      t.timestamps
+    end
+  end
+
+  private
+
+  # 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
+    generators = Rails.application&.config&.generators
+    setting = generators&.options&.dig(generators.orm, :primary_key_type)
+    [setting || :primary_key, setting || :bigint]
+  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
+
+    sql_type = column.sql_type.to_s.downcase
+    if sql_type.include?("uuid")
+      :uuid
+    elsif column.type == :integer
+      sql_type.include?("bigint") || column.limit == 8 ? :bigint : :integer
+    else
+      column.type
+    end
+  end
+
+  # :jsonb on PostgreSQL, :json elsewhere, as on the api_keys table.
+  def json_column_type
+    connection.adapter_name.downcase.include?("postg") ? :jsonb : :json
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Migration to create the table of Idempotency-Keys (api_keys 0.7.0). Each
+# row is one write under one API key's Idempotency-Key header
+# (ApiKeys::Idempotency, ApiKeys::IdempotencyKey): the request it stands for
+# as a digest, and, committed with the write itself, its status and a
+# reference to the record the write made or changed. A row never keeps a
+# response body, so a secret shown once is never stored.
+#
+# 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
+      t.string :key, null: false
+      t.string :request_digest
+      t.integer :response_status
+      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
+    end
+  end
+
+  private
+
+  # 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
+    generators = Rails.application&.config&.generators
+    setting = generators&.options&.dig(generators.orm, :primary_key_type)
+    [setting || :primary_key, setting || :bigint]
+  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
+
+    sql_type = column.sql_type.to_s.downcase
+    if sql_type.include?("uuid")
+      :uuid
+    elsif column.type == :integer
+      sql_type.include?("bigint") || column.limit == 8 ? :bigint : :integer
+    else
+      column.type
+    end
+  end
+end

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

@@ -26,6 +26,10 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
       # Who owns this key? Can be null for ownerless keys.
       t.references :owner, polymorphic: true, null: true, type: foreign_key_type
 
+      # Who created this key: the person behind it, for keys whose owner is
+      # not a person (an organization). Optional.
+      t.references :created_by, polymorphic: true, null: true, type: foreign_key_type
+
       # Optional list of permissions granted to this key (array of strings)
       t.send(json_column_type, :scopes, default: [], null: false)
 
@@ -45,6 +49,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
@@ -318,6 +327,24 @@ ApiKeys.configure do |config|
   # when your network ingress rejects requests that bypass that vendor:
   # config.client_ip_resolver = ->(request) { request.headers.fetch("CF-Connecting-IP") }
 
+  # ============================================================================
+  # THE PERSON BEHIND A KEY
+  # ============================================================================
+  #
+  # When keys belong to an organization, name the person who creates each one:
+  #
+  #   current_organization.create_api_key!(name: "CI", created_by: current_user)
+  #
+  # Then the check below can stop a key once that person no longer stands
+  # behind it (they left, or lost the right to manage keys). It runs after the
+  # scope check, on every authenticated request. A false or nil answer refuses
+  # the request with 403 `untrusted_key`. Keys made before you set created_by
+  # have none: decide what the check does with them.
+  #
+  # Existing installs: rails generate api_keys:add_created_by && rails db:migrate
+  # Default: nil (every valid key is trusted)
+  # config.trusted_key_check = ->(api_key) { api_key.owner.managed_by?(api_key.created_by) }
+
   # ============================================================================
   # BACKGROUND JOBS & CALLBACKS
   # ============================================================================
@@ -344,9 +371,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.7.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,21 +99,28 @@ 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
 - lib/api_keys/controller.rb
+- lib/api_keys/device_flow.rb
 - lib/api_keys/engine.rb
 - lib/api_keys/errors.rb
 - lib/api_keys/form_builder_extensions.rb
 - lib/api_keys/helpers/expiration_options.rb
 - lib/api_keys/helpers/token_session.rb
 - lib/api_keys/helpers/view_helpers.rb
+- lib/api_keys/idempotency.rb
 - lib/api_keys/jobs/callbacks_job.rb
 - lib/api_keys/jobs/update_stats_job.rb
 - lib/api_keys/logging.rb
 - lib/api_keys/models/api_key.rb
 - lib/api_keys/models/concerns/has_api_keys.rb
+- lib/api_keys/models/device_authorization.rb
+- lib/api_keys/models/idempotency_key.rb
 - lib/api_keys/restrictions.rb
 - lib/api_keys/services/authenticator.rb
 - lib/api_keys/services/digestor.rb
@@ -120,12 +128,20 @@ 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_created_by_generator.rb
+- lib/generators/api_keys/add_device_authorizations_generator.rb
+- lib/generators/api_keys/add_idempotency_keys_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_created_by_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_device_authorizations.rb.erb
+- lib/generators/api_keys/templates/create_api_keys_idempotency_keys.rb.erb
 - lib/generators/api_keys/templates/create_api_keys_table.rb.erb
 - lib/generators/api_keys/templates/initializer.rb
 homepage: https://github.com/rameerez/api_keys