rails_api_keys 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a89bf64215fd1c3fcad121b300e716eeff78787be8f438e63dca2c399b6bf7
-  data.tar.gz: 2d4ec14c89eb7e8675d0036ff18d879532b74b93ff1311320b0d5f5a75531a50
+  metadata.gz: 5efd1a62dc4d875f9411e190b6cdeb33129d09c85790ea2f2c61cf12381b8123
+  data.tar.gz: 0bd1d07535c449f62b8a59517057a6f990b2524d57e4c5d6ab457e4b0636a850
 SHA512:
-  metadata.gz: 9552c48d8976f5b1df454460273d9616a9203d2bb9a6987b643981b99d0ac3b93b2cd21af5c948afdaf4b414a48ec091cc2eb8f3699b77240a371a42f16c02b7
-  data.tar.gz: f245f531718d6e288d1d108de0aee915f0f18a78dcbd743c0f44a1e7a86511446856719ef15b38370f7545c5e30104acbb7eab45fa65b4c4048d479f533f7ecf
+  metadata.gz: 2a106e93e5e874e58754bc2502845a6ef8f19ba78cba31806cbda95c52ab6721fc6600b78ad90c678c95d212675b070f0e1dbc4902f222dd2ee1d5c65d345872
+  data.tar.gz: 2d6ece664815bd002f8543789317e36f6dbe52490087fdd8a31d072ab1440eee975d1df94e7f8b209beab92d18515d30085a7426c460b66b1256dc24383c5047

data/CHANGELOG.md

@@ -3,10 +3,26 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-10
+
+### Added
+
+- `has_api_keys` — Active Record macro for owner models (`User`, `Company`, etc.); registers allowed polymorphic owners
+- `create_api_key!` — instance helper on owners that call `has_api_keys` (wraps `ApiKey.generate_for!`)
+
+### Changed
+
+- `authenticate_api_key!` now enforces permissions from the HTTP method: GET/HEAD require read; other methods require write
+
+### Removed
+
+- `require_api_permission!` — hosts no longer call this separately
+- `config.owner_class` — replaced by opt-in `has_api_keys` on each owner model
+
 ## [0.1.0] - 2026-08-10
 
 ### Added
@@ -16,5 +32,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `RailsApiKeys.configure` — optional `owner_class`, `token_prefix`, and `owner_active`
 - Install generator (`rails_api_keys:install`) for migration and initializer
 
-[Unreleased]: https://github.com/rubyroidlabs/rails_api_keys/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/rubyroidlabs/rails_api_keys/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/rubyroidlabs/rails_api_keys/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/rubyroidlabs/rails_api_keys/releases/tag/v0.1.0

data/README.md

@@ -9,6 +9,7 @@ Host apps own UI, routes, and domain APIs. This gem stays thin on purpose.
 ## What this gem includes
 
 - `RailsApiKeys::ApiKey` — issue, authenticate, revoke
+- `has_api_keys` — opt-in owner macro with `create_api_key!` (supports multiple models)
 - `RailsApiKeys::Authentication` — controller concern for Bearer tokens
 - Install generator (migration + initializer)
 
@@ -29,32 +30,28 @@ bin/rails generate rails_api_keys:install
 bin/rails db:migrate
 ```
 
-Until the gem is published on RubyGems, you can use git or a local path:
-
-```ruby
-gem "rails_api_keys", git: "https://github.com/rubyroidlabs/rails_api_keys.git"
-# or: gem "rails_api_keys", path: "../rails_api_keys"
-```
-
 ## Host setup
 
-On the owner model (defaults to `User`):
+Opt in on each owner model with `has_api_keys` (any number of models):
 
 ```ruby
 class User < ApplicationRecord
-  has_many :api_keys, as: :owner, class_name: "RailsApiKeys::ApiKey", dependent: :destroy
+  has_api_keys
+end
+
+class Company < ApplicationRecord
+  has_api_keys
 end
 ```
 
-Build your own controllers/UI to create keys (show the raw token once), list them, and revoke.
+That declares `has_many :api_keys` and allows the model to own keys. Build your own controllers/UI to create keys (show the raw token once), list them, and revoke.
 
 ## Configuration
 
-Defaults suit a typical Devise `User` host:
+Defaults suit a typical Devise `User` host; multiple owners are supported via `has_api_keys`:
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `owner_class` | `"User"` | Expected owner class name |
 | `token_prefix` | `"#{AppName.downcase}_ak_"` | Prefix on generated raw tokens |
 | `owner_active` | `active_for_authentication?` when present | Reject keys whose owner is inactive |
 
@@ -64,7 +61,6 @@ Override only what you need:
 # config/initializers/rails_api_keys.rb
 RailsApiKeys.configure do |config|
   # config.token_prefix = "myapp_ak_"
-  # config.owner_class = "Admin"
   # config.owner_active = ->(owner) { owner.active? }
 end
 ```
@@ -72,11 +68,7 @@ end
 ## Usage
 
 ```ruby
-key, raw = RailsApiKeys::ApiKey.generate_for!(
-  owner: current_user,
-  name: "Zapier",
-  permission: :read
-)
+key, raw = current_user.create_api_key!(name: "Zapier", permission: :read)
 # Show `raw` once — it cannot be recovered later.
 
 RailsApiKeys::ApiKey.authenticate(raw) # => key or nil
@@ -88,7 +80,6 @@ class Api::V1::BaseController < ActionController::API
   include RailsApiKeys::Authentication
 
   before_action :authenticate_api_key!
-  before_action -> { require_api_permission!(:read) }
 
   # current_api_key / current_api_owner are available after authenticate
 end
@@ -100,18 +91,20 @@ Clients send:
 Authorization: Bearer <raw_token>
 ```
 
+`authenticate_api_key!` rejects missing/invalid tokens with 401, then enforces permission from the HTTP method: GET/HEAD require read; other methods require write (403 if the key lacks it).
+
 ## Permissions
 
-| Permission | `allows_read?` | `allows_write?` |
+| Permission | GET/HEAD | Other methods |
 | --- | --- | --- |
-| `read` | yes | no |
-| `read_write` | yes | yes |
+| `read` | allowed | forbidden |
+| `read_write` | allowed | allowed |
 
 Permissions are immutable after create. Revoke with `revoke!` (sets `revoked_at`).
 
 ## Security notes
 
-- Raw tokens are returned only from `generate_for!` and never stored
+- Raw tokens are returned only from `create_api_key!` / `generate_for!` and never stored
 - Digests use SHA-256 (`token_digest`); UI can show `token_display_prefix`
 - Soft revoke via `revoked_at`; authentication ignores revoked keys
 

data/app/models/rails_api_keys/api_key.rb

@@ -21,7 +21,7 @@ module RailsApiKeys
 
     validates :name, :token_digest, :token_display_prefix, :permission, presence: true
     validates :token_digest, uniqueness: true
-    validate :owner_matches_configured_class
+    validate :owner_declares_has_api_keys
     validate :permission_immutable, on: :update
 
     scope :active, -> { where(revoked_at: nil) }
@@ -92,13 +92,11 @@ module RailsApiKeys
 
     private
 
-    def owner_matches_configured_class
+    def owner_declares_has_api_keys
       return if owner.blank?
+      return if RailsApiKeys.owner_class?(owner.class)
 
-      expected = RailsApiKeys.configuration.owner_class_name
-      return if owner.class.name == expected
-
-      errors.add(:owner, "must be a #{expected}")
+      errors.add(:owner, "must declare has_api_keys")
     end
 
     def permission_immutable

data/lib/generators/rails_api_keys/install/templates/initializer.rb.tt

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-# Defaults: owner_class "User", token_prefix "<AppName>_ak_",
+# Defaults: token_prefix "<AppName>_ak_",
 # owner_active via active_for_authentication? when available.
+# Owner models opt in with +has_api_keys+.
 # Uncomment to override:
 #
 # RailsApiKeys.configure do |config|

data/lib/rails_api_keys/authentication.rb

@@ -5,9 +5,10 @@ require "active_support/concern"
 module RailsApiKeys
   # Controller concern for +ActionController::API+.
   #
-  # Include and call {#authenticate_api_key!} / {#require_api_permission!} from
-  # +before_action+. After a successful authenticate, +current_api_key+ and
-  # +current_api_owner+ are set.
+  # Include and call {#authenticate_api_key!} from +before_action+. After a
+  # successful authenticate, +current_api_key+ and +current_api_owner+ are set.
+  # Permission is enforced from the HTTP method: GET/HEAD require read; other
+  # methods require write.
   #
   # Expects +Authorization: Bearer <raw_token>+.
   module Authentication
@@ -19,7 +20,8 @@ module RailsApiKeys
 
     private
 
-    # Authenticates the Bearer token. Renders 401 and returns +false+ on failure.
+    # Authenticates the Bearer token and enforces method-based permission.
+    # Renders 401 on auth failure, 403 when the key lacks the required level.
     def authenticate_api_key!
       token = bearer_token
       key = RailsApiKeys::ApiKey.authenticate(token)
@@ -31,16 +33,15 @@ module RailsApiKeys
 
       @current_api_key = key
       @current_api_owner = key.owner
-      true
+      enforce_api_permission!
     end
 
-    # Requires +:read+ or +:write+. +read_write+ keys satisfy both. Renders 403 on failure.
-    def require_api_permission!(level)
+    def enforce_api_permission!
       allowed =
-        case level.to_sym
-        when :read then current_api_key&.allows_read?
-        when :write then current_api_key&.allows_write?
-        else false
+        if request.get? || request.head?
+          current_api_key.allows_read?
+        else
+          current_api_key.allows_write?
         end
 
       return true if allowed

data/lib/rails_api_keys/configuration.rb

@@ -3,14 +3,13 @@
 module RailsApiKeys
   # Optional host overrides. Set via {RailsApiKeys.configure}.
   #
-  # Defaults: +owner_class+ is +"User"+, +token_prefix+ derives from the app
-  # name, and +owner_active+ uses Devise-style +active_for_authentication?+
-  # when available.
+  # Defaults: +token_prefix+ derives from the app name, and +owner_active+ uses
+  # Devise-style +active_for_authentication?+ when available.
+  # Owner models opt in with {Owner.has_api_keys}.
   class Configuration
-    attr_accessor :owner_class, :token_prefix, :owner_active
+    attr_accessor :token_prefix, :owner_active
 
     def initialize
-      @owner_class = "User"
       @token_prefix = nil
       @owner_active = ->(owner) {
         if owner.respond_to?(:active_for_authentication?)
@@ -27,10 +26,6 @@ module RailsApiKeys
       "#{Rails.application.class.module_parent_name.downcase}_ak_"
     end
 
-    def owner_class_name
-      owner_class.to_s
-    end
-
     def owner_active?(owner)
       owner_active.call(owner)
     end

data/lib/rails_api_keys/engine.rb

@@ -3,5 +3,11 @@
 module RailsApiKeys
   class Engine < ::Rails::Engine
     isolate_namespace RailsApiKeys
+
+    initializer "rails_api_keys.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include RailsApiKeys::Owner
+      end
+    end
   end
 end

data/lib/rails_api_keys/owner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsApiKeys
+  # Mixes {.has_api_keys} into Active Record so host models can opt in as key owners.
+  module Owner
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declares a polymorphic +has_many :api_keys+ and registers this class as an
+      # allowed owner for {RailsApiKeys::ApiKey}.
+      def has_api_keys(dependent: :destroy)
+        has_many :api_keys,
+                 as: :owner,
+                 class_name: "RailsApiKeys::ApiKey",
+                 dependent: dependent
+
+        RailsApiKeys.register_owner_class!(self)
+
+        # Creates a key for this owner and returns +[record, raw_token]+.
+        define_method(:create_api_key!) do |name:, permission:|
+          RailsApiKeys::ApiKey.generate_for!(owner: self, name: name, permission: permission)
+        end
+      end
+    end
+  end
+end

data/lib/rails_api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsApiKeys
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/rails_api_keys.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "set"
 require "rails_api_keys/version"
 require "rails_api_keys/configuration"
 require "rails_api_keys/authentication"
+require "rails_api_keys/owner"
 require "rails_api_keys/engine"
 
 # Thin Rails engine for personal API key authentication.
@@ -21,8 +23,25 @@ module RailsApiKeys
     end
 
     # Resets configuration to defaults (primarily for tests).
+    # Does not clear {.owner_class_names}; those are registered at model load via {Owner#has_api_keys}.
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # Records +klass+ as an allowed API key owner (idempotent).
+    def register_owner_class!(klass)
+      owner_class_names << klass.name
+    end
+
+    # @return [Boolean] whether +klass+ (or its name) called {Owner#has_api_keys}
+    def owner_class?(klass)
+      name = klass.is_a?(Module) ? klass.name : klass.to_s
+      owner_class_names.include?(name)
+    end
+
+    # @return [Set<String>] registered owner class names
+    def owner_class_names
+      @owner_class_names ||= Set.new
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_keys
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pavel Pershko
@@ -50,16 +50,17 @@ files:
 - lib/rails_api_keys/authentication.rb
 - lib/rails_api_keys/configuration.rb
 - lib/rails_api_keys/engine.rb
+- lib/rails_api_keys/owner.rb
 - lib/rails_api_keys/version.rb
 homepage: https://github.com/rubyroidlabs/rails_api_keys
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/rubyroidlabs/rails_api_keys
-  source_code_uri: https://github.com/rubyroidlabs/rails_api_keys/tree/v0.1.0
-  changelog_uri: https://github.com/rubyroidlabs/rails_api_keys/blob/v0.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/rubyroidlabs/rails_api_keys/tree/v0.2.0
+  changelog_uri: https://github.com/rubyroidlabs/rails_api_keys/blob/v0.2.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/rubyroidlabs/rails_api_keys/issues
-  documentation_uri: https://www.rubydoc.info/gems/rails_api_keys/0.1.0
+  documentation_uri: https://www.rubydoc.info/gems/rails_api_keys/0.2.0
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
 rdoc_options: []