rails_api_keys 0.1.0

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-10
+
+### Added
+
+- `RailsApiKeys::ApiKey` — create (raw token once), SHA-256 digest storage, soft revoke, `read` / `read_write` permissions
+- `RailsApiKeys::Authentication` — Bearer token auth helpers for `ActionController::API`
+- `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
+[0.1.0]: https://github.com/rubyroidlabs/rails_api_keys/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rubyroid Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# rails_api_keys
+
+[![CI](https://github.com/rubyroidlabs/rails_api_keys/actions/workflows/ci.yml/badge.svg)](https://github.com/rubyroidlabs/rails_api_keys/actions/workflows/ci.yml)
+
+Reusable Rails engine for personal API keys: create (reveal once), hash at rest, revoke, and authenticate via `Authorization: Bearer <token>`.
+
+Host apps own UI, routes, and domain APIs. This gem stays thin on purpose.
+
+## What this gem includes
+
+- `RailsApiKeys::ApiKey` — issue, authenticate, revoke
+- `RailsApiKeys::Authentication` — controller concern for Bearer tokens
+- Install generator (migration + initializer)
+
+No mailers, jobs, views, assets, or mounted domain routes.
+
+## Installation
+
+Add the gem and install:
+
+```ruby
+# Gemfile
+gem "rails_api_keys"
+```
+
+```bash
+bundle install
+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`):
+
+```ruby
+class User < ApplicationRecord
+  has_many :api_keys, as: :owner, class_name: "RailsApiKeys::ApiKey", dependent: :destroy
+end
+```
+
+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:
+
+| 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 |
+
+Override only what you need:
+
+```ruby
+# 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
+```
+
+## Usage
+
+```ruby
+key, raw = RailsApiKeys::ApiKey.generate_for!(
+  owner: current_user,
+  name: "Zapier",
+  permission: :read
+)
+# Show `raw` once — it cannot be recovered later.
+
+RailsApiKeys::ApiKey.authenticate(raw) # => key or nil
+key.revoke!
+```
+
+```ruby
+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
+```
+
+Clients send:
+
+```http
+Authorization: Bearer <raw_token>
+```
+
+## Permissions
+
+| Permission | `allows_read?` | `allows_write?` |
+| --- | --- | --- |
+| `read` | yes | no |
+| `read_write` | yes | yes |
+
+Permissions are immutable after create. Revoke with `revoke!` (sets `revoked_at`).
+
+## Security notes
+
+- Raw tokens are returned only from `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
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bin/rubocop
+```
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes. Agent-oriented notes live in [`AGENTS.md`](./AGENTS.md).
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+---
+
+<p align="center">
+  <a href="https://rubyroidlabs.com">
+    <img src="./docs/logo.svg" alt="Rubyroid Labs" width="100%" />
+  </a>
+</p>
+
+**[Rubyroid Labs](https://rubyroidlabs.com)** — full-cycle software development company for businesses delivering scalable web and mobile apps, dedicated developers, and full-cycle teams in Ruby on Rails, React Native, and UX/UI. 98% on-time delivery.
+
+- Website: [rubyroidlabs.com](https://rubyroidlabs.com)
+- Email: [hi@rubyroidlabs.com](mailto:hi@rubyroidlabs.com)
+- References: [Clutch](https://clutch.co/profile/rubyroid-labs)

data/app/models/rails_api_keys/api_key.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module RailsApiKeys
+  # Persists personal API keys for a polymorphic owner.
+  #
+  # Raw tokens are returned only from {.generate_for!} and are never stored.
+  # Authentication matches against a SHA-256 digest and refuses revoked or
+  # inactive-owner keys.
+  class ApiKey < ApplicationRecord
+    self.table_name = "rails_api_keys_api_keys"
+
+    DISPLAY_PREFIX_LENGTH = 12
+    TOKEN_BYTES = 32
+
+    belongs_to :owner, polymorphic: true
+
+    enum :permission, { read: "read", read_write: "read_write" }, validate: true
+
+    validates :name, :token_digest, :token_display_prefix, :permission, presence: true
+    validates :token_digest, uniqueness: true
+    validate :owner_matches_configured_class
+    validate :permission_immutable, on: :update
+
+    scope :active, -> { where(revoked_at: nil) }
+
+    class << self
+      # Creates a key and returns +[record, raw_token]+. Show +raw_token+ once.
+      def generate_for!(owner:, name:, permission:)
+        raw_token = build_raw_token
+        record = create!(
+          owner: owner,
+          name: name,
+          permission: permission,
+          token_digest: digest(raw_token),
+          token_display_prefix: display_prefix_for(raw_token)
+        )
+        [ record, raw_token ]
+      end
+
+      # Returns an active key for +raw_token+, or +nil+. Touches +last_used_at+.
+      def authenticate(raw_token)
+        return if raw_token.blank?
+
+        key = active.find_by(token_digest: digest(raw_token))
+        return unless key
+        return unless RailsApiKeys.configuration.owner_active?(key.owner)
+
+        key.touch_last_used!
+        key
+      end
+
+      def digest(raw_token)
+        Digest::SHA256.hexdigest(raw_token.to_s)
+      end
+
+      def build_raw_token
+        "#{RailsApiKeys.configuration.resolved_token_prefix}#{SecureRandom.urlsafe_base64(TOKEN_BYTES)}"
+      end
+
+      def display_prefix_for(raw_token)
+        raw_token.to_s[0, DISPLAY_PREFIX_LENGTH]
+      end
+    end
+
+    # Soft-revokes the key so {.authenticate} no longer accepts it.
+    def revoke!
+      update!(revoked_at: Time.current)
+    end
+
+    def revoked?
+      revoked_at.present?
+    end
+
+    def active?
+      !revoked?
+    end
+
+    def allows_read?
+      read? || read_write?
+    end
+
+    def allows_write?
+      read_write?
+    end
+
+    def touch_last_used!
+      update_column(:last_used_at, Time.current)
+    end
+
+    private
+
+    def owner_matches_configured_class
+      return if owner.blank?
+
+      expected = RailsApiKeys.configuration.owner_class_name
+      return if owner.class.name == expected
+
+      errors.add(:owner, "must be a #{expected}")
+    end
+
+    def permission_immutable
+      return unless permission_changed? && persisted?
+
+      errors.add(:permission, "cannot be changed after creation")
+    end
+  end
+end

data/app/models/rails_api_keys/application_record.rb

@@ -0,0 +1,5 @@
+module RailsApiKeys
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+RailsApiKeys::Engine.routes.draw do
+  # No engine-mounted routes; host owns key management UI and API endpoints.
+end

data/db/migrate/20260810120000_create_rails_api_keys_api_keys.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateRailsApiKeysApiKeys < ActiveRecord::Migration[7.0]
+  def change
+    create_table :rails_api_keys_api_keys do |t|
+      t.string :name, null: false
+      t.string :token_digest, null: false
+      t.string :token_display_prefix, null: false
+      t.string :permission, null: false, default: "read"
+      t.references :owner, polymorphic: true, null: false, index: true
+      t.datetime :revoked_at
+      t.datetime :last_used_at
+      t.timestamps
+    end
+
+    add_index :rails_api_keys_api_keys, :token_digest, unique: true
+    add_index :rails_api_keys_api_keys, :revoked_at
+  end
+end

data/lib/generators/rails_api_keys/install/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module RailsApiKeys
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install RailsApiKeys migrations and initializer"
+
+      def self.next_migration_number(dirname)
+        next_number = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        if Dir.exist?(dirname)
+          while Dir.children(dirname).any? { |f| f.start_with?(next_number) }
+            next_number = (next_number.to_i + 1).to_s
+          end
+        end
+        next_number
+      end
+
+      def copy_migration
+        migration_template(
+          "create_rails_api_keys_api_keys.rb.tt",
+          "db/migrate/create_rails_api_keys_api_keys.rb"
+        )
+      end
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/rails_api_keys.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateRailsApiKeysApiKeys < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :rails_api_keys_api_keys do |t|
+      t.string :name, null: false
+      t.string :token_digest, null: false
+      t.string :token_display_prefix, null: false
+      t.string :permission, null: false, default: "read"
+      t.references :owner, polymorphic: true, null: false, index: true
+      t.datetime :revoked_at
+      t.datetime :last_used_at
+      t.timestamps
+    end
+
+    add_index :rails_api_keys_api_keys, :token_digest, unique: true
+    add_index :rails_api_keys_api_keys, :revoked_at
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Defaults: owner_class "User", token_prefix "<AppName>_ak_",
+# owner_active via active_for_authentication? when available.
+# Uncomment to override:
+#
+# RailsApiKeys.configure do |config|
+#   config.token_prefix = "myapp_ak_"
+# end

data/lib/rails_api_keys/authentication.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # Expects +Authorization: Bearer <raw_token>+.
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :current_api_key, :current_api_owner
+    end
+
+    private
+
+    # Authenticates the Bearer token. Renders 401 and returns +false+ on failure.
+    def authenticate_api_key!
+      token = bearer_token
+      key = RailsApiKeys::ApiKey.authenticate(token)
+
+      unless key
+        render_api_unauthorized
+        return false
+      end
+
+      @current_api_key = key
+      @current_api_owner = key.owner
+      true
+    end
+
+    # Requires +:read+ or +:write+. +read_write+ keys satisfy both. Renders 403 on failure.
+    def require_api_permission!(level)
+      allowed =
+        case level.to_sym
+        when :read then current_api_key&.allows_read?
+        when :write then current_api_key&.allows_write?
+        else false
+        end
+
+      return true if allowed
+
+      render json: { error: "Forbidden" }, status: :forbidden
+      false
+    end
+
+    def bearer_token
+      header = request.authorization.to_s
+      return unless header.match?(/\ABearer\s+/i)
+
+      header.split(/\s+/, 2).last.presence
+    end
+
+    def render_api_unauthorized
+      render json: { error: "Unauthorized" }, status: :unauthorized
+    end
+  end
+end

data/lib/rails_api_keys/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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.
+  class Configuration
+    attr_accessor :owner_class, :token_prefix, :owner_active
+
+    def initialize
+      @owner_class = "User"
+      @token_prefix = nil
+      @owner_active = ->(owner) {
+        if owner.respond_to?(:active_for_authentication?)
+          owner.active_for_authentication?
+        else
+          true
+        end
+      }
+    end
+
+    def resolved_token_prefix
+      return token_prefix.to_s if token_prefix.present?
+
+      "#{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
+  end
+end

data/lib/rails_api_keys/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsApiKeys
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsApiKeys
+  end
+end

data/lib/rails_api_keys/version.rb

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

data/lib/rails_api_keys.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails_api_keys/version"
+require "rails_api_keys/configuration"
+require "rails_api_keys/authentication"
+require "rails_api_keys/engine"
+
+# Thin Rails engine for personal API key authentication.
+#
+# @see file:README.md
+module RailsApiKeys
+  class << self
+    # @return [RailsApiKeys::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields {configuration} for host overrides in an initializer.
+    def configure
+      yield configuration
+    end
+
+    # Resets configuration to defaults (primarily for tests).
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: rails_api_keys
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pavel Pershko
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  Thin Rails engine for personal API keys: issue a raw token once, store a
+  SHA-256 digest, soft-revoke, and authenticate ActionController::API
+  requests with Authorization: Bearer. Host apps own UI, routes, and domain APIs.
+email:
+- pavel.pershko@rubyroidlabs.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/models/rails_api_keys/api_key.rb
+- app/models/rails_api_keys/application_record.rb
+- config/routes.rb
+- db/migrate/20260810120000_create_rails_api_keys_api_keys.rb
+- lib/generators/rails_api_keys/install/install_generator.rb
+- lib/generators/rails_api_keys/install/templates/create_rails_api_keys_api_keys.rb.tt
+- lib/generators/rails_api_keys/install/templates/initializer.rb.tt
+- lib/rails_api_keys.rb
+- lib/rails_api_keys/authentication.rb
+- lib/rails_api_keys/configuration.rb
+- lib/rails_api_keys/engine.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
+  bug_tracker_uri: https://github.com/rubyroidlabs/rails_api_keys/issues
+  documentation_uri: https://www.rubydoc.info/gems/rails_api_keys/0.1.0
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Reusable Rails engine for personal API key authentication.
+test_files: []