api_keys 0.6.0 → 0.8.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/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/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)
 

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).
@@ -327,6 +332,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
   # ============================================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - rameerez
@@ -106,17 +106,21 @@ files:
 - 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
@@ -124,14 +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