concerns_on_rails 1.7.0 → 1.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bdaf4512b253a9c3b7307ace69f16d616f180d38ce3a3f5292099f0c97dedb5
-  data.tar.gz: de2843d32ebd1cea0e3c9fce3e8f5d6d18adaa6eb6e92ce4056af3bb2ab4d368
+  metadata.gz: 5126c79ca466ff1a85a20eb0d4a29f7a2d471bc4186e7b4762481bfad2084f42
+  data.tar.gz: '086922bf94b7efa7ef99699e4d96ab4e24ae2e731c2308bd1b0a8471e1f065a2'
 SHA512:
-  metadata.gz: 315ff80a677ef032630d0b81f8c0b5c3b88d132a288ad075ed00732e2d676ccef954725c8966231af793ee89dc2485cb48e6b0c1de03ea93d47c7f283545815d
-  data.tar.gz: 13c59b78fc2b9dbd8dfca9877550a3a7fcd778fca493dd1b97c9151f9c4d111f94aa8eb3d8692b9b7e0299ccd52bf270944dee2a6987aae3c88917532cce2404
+  metadata.gz: 6b3e968d8cf97c9d11b14ff1d8374a64731ed3416d114ca0acf525a64f65843a35f0261da219d9f725e539eba7ac6460ba331a3aaf2b701b88627d841ac70a2a
+  data.tar.gz: 61f80dadd2112d36c1c1ceaf88fe01fb5dcf68f22911e1535e68414ecdbaca07ca363365c7ec3032c2698aec1cb0929d054036d2b8ebf73d1c347093976f3bb4

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 <!-- CHANGELOG.md -->
 
+## 1.8.2 (2026-05-22)
+
+### Internal
+- Regenerated `Gemfile.lock` so the pinned `concerns_on_rails` version matches the gemspec. No behavior change.
+
+### Notes
+- The `v1.8.1` tag was pushed but failed CI (`bundle install --deployment` rejected the stale `Gemfile.lock`); `1.8.2` is the first usable release of the Tokenizable concern.
+
+## 1.8.1 (2026-05-22)
+
+### Internal
+- Refactored `Models::Tokenizable` `class_methods` blocks to satisfy `Metrics/BlockLength`. No behavior change.
+
+### Notes
+- The `v1.8.0` tag was pushed but failed RuboCop; `1.8.1` is the first usable release of the Tokenizable concern.
+
+## 1.8.0 (2026-05-22)
+
+### Added
+- **Models::Tokenizable**: Security-token generation for API keys, invite codes, share links, password-reset tokens. Each `tokenizable_by` call adds an independently-configured field (one model can hold many tokens). Defaults to 32-char URL-safe values; also supports `:hex`, `:alphanumeric`, and `:numeric` types with a configurable `length:`. Auto-generates on create with best-effort uniqueness retry, and provides `regenerate_<field>!`, `revoke_<field>!`, `<field>?`, and a timing-safe `.authenticate_by_<field>` class method.
+
 ## 1.7.0 (2026-05-21)
 
 ### Added

data/README.md

@@ -35,6 +35,7 @@ Article.published.without_deleted.find("hello-world")
   - [Normalizable](#-normalizable) — attribute normalization (`:email`, `:phone`, …)
   - [Searchable](#-searchable) — LIKE/ILIKE search across configured columns
   - [Activatable](#-activatable) — boolean active/inactive toggle
+  - [Tokenizable](#-tokenizable) — security tokens with timing-safe lookup
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -50,7 +51,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Ten model concerns + five controller concerns**, all production-ready
+- **Eleven model concerns + five controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -63,7 +64,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.7"
+gem "concerns_on_rails", "~> 1.8"
 ```
 
 Or pull the latest from GitHub:
@@ -485,6 +486,46 @@ Subscription.inactive   # WHERE active = FALSE OR active IS NULL
 
 ---
 
+## 🔑 Tokenizable
+
+Generate and manage security tokens — API keys, invite codes, share links, password-reset tokens. One model can declare any number of independently-configured token fields.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Tokenizable
+
+  tokenizable_by :api_token                                  # 32-char URL-safe
+  tokenizable_by :reset_password_token, length: 24
+  tokenizable_by :invite_code, type: :alphanumeric, length: 8
+end
+
+user = User.create!                       # all three tokens auto-generated
+user.api_token                            # => "k3Jf...g2" (32 URL-safe chars)
+user.api_token?                           # => true
+
+user.regenerate_api_token!                # rotates and persists
+user.revoke_api_token!                    # nils the column
+
+User.find_by_api_token(token)             # Rails default
+User.authenticate_by_api_token(token)     # timing-safe; returns user or nil
+```
+
+**Options**
+
+| Option   | Default     | Notes                                                         |
+| -------- | ----------- | ------------------------------------------------------------- |
+| `type:`  | `:urlsafe`  | One of `:urlsafe`, `:hex`, `:alphanumeric`, `:numeric`        |
+| `length:`| `32`        | Character length of the generated token                       |
+
+**Notes**
+- URL-safe by default (`A–Z`, `a–z`, `0–9`, `-`, `_`) — drop straight into URLs and headers.
+- Caller-supplied values are respected: `User.create!(api_token: "preset")` won't be overwritten.
+- Generation does a best-effort uniqueness check before insert and retries up to 10 times. Pair with a `unique` DB index for real safety, especially for short alphanumeric/numeric codes.
+- `.authenticate_by_<field>` uses `ActiveSupport::SecurityUtils.secure_compare` to avoid leaking partial matches via response timing.
+- Distinct from `Hashable`: Hashable handles a single random field; Tokenizable focuses on security tokens (multi-field, URL-safe default, timing-safe lookup, revocation).
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -12,4 +12,5 @@ module ConcernsOnRails
   Normalizable  = Models::Normalizable
   Searchable    = Models::Searchable
   Activatable   = Models::Activatable
+  Tokenizable   = Models::Tokenizable
 end

data/lib/concerns_on_rails/models/tokenizable.rb

@@ -0,0 +1,145 @@
+require "active_support/concern"
+require "active_support/security_utils"
+require "securerandom"
+
+module ConcernsOnRails
+  module Models
+    # Generates and manages security tokens (API keys, invite codes, share links).
+    #
+    #   class User < ApplicationRecord
+    #     include ConcernsOnRails::Tokenizable
+    #
+    #     tokenizable_by :api_token                              # 32-char URL-safe
+    #     tokenizable_by :reset_password_token, length: 24
+    #     tokenizable_by :invite_code, type: :alphanumeric, length: 8
+    #   end
+    #
+    #   user = User.create!                       # tokens auto-generated on create
+    #   user.regenerate_api_token!                # new value, persisted
+    #   user.revoke_api_token!                    # sets the column to nil
+    #   user.api_token?                           # true if present
+    #
+    #   User.find_by_api_token(token)             # Rails default
+    #   User.authenticate_by_api_token(token)     # timing-safe lookup, returns record or nil
+    #
+    # Unlike Hashable, one model can declare multiple token fields, generation is
+    # URL-safe by default, and `assign_tokenizable_value` retries on uniqueness
+    # collisions before insert (best-effort; pair with a unique DB index).
+    module Tokenizable
+      extend ActiveSupport::Concern
+
+      VALID_TYPES = %i[urlsafe hex alphanumeric numeric].freeze
+      ALPHANUMERIC_ALPHABET = (("A".."Z").to_a + ("a".."z").to_a + ("0".."9").to_a).freeze
+      NUMERIC_ALPHABET = ("0".."9").to_a.freeze
+      MAX_GENERATION_ATTEMPTS = 10
+
+      included do
+        class_attribute :tokenizable_fields, instance_accessor: false, default: {}
+      end
+
+      class_methods do
+        # Configure a tokenizable field.
+        #
+        # Options:
+        #   type:   one of :urlsafe (default), :hex, :alphanumeric, :numeric
+        #   length: character length of the generated token (default 32)
+        def tokenizable_by(field, type: :urlsafe, length: 32)
+          field = field.to_sym
+          type = type.to_sym
+          length = length.to_i
+
+          validate_tokenizable_options!(field, type, length)
+
+          # Build a fresh hash so subclasses don't mutate the parent's config.
+          self.tokenizable_fields = tokenizable_fields.merge(field => { type: type, length: length })
+
+          before_create -> { assign_tokenizable_value(field) }
+
+          define_tokenizable_methods(field)
+        end
+
+        # Generate a new random value for the given field using its configured type/length.
+        def generate_tokenizable_value(field)
+          config = tokenizable_fields.fetch(field) do
+            raise ArgumentError, "ConcernsOnRails::Models::Tokenizable: '#{field}' is not a tokenizable field"
+          end
+
+          length = config[:length]
+
+          case config[:type]
+          when :urlsafe      then SecureRandom.urlsafe_base64(length)[0, length]
+          when :hex          then SecureRandom.hex((length + 1) / 2)[0, length]
+          when :alphanumeric then random_string_from_alphabet(ALPHANUMERIC_ALPHABET, length)
+          when :numeric      then random_string_from_alphabet(NUMERIC_ALPHABET, length)
+          end
+        end
+      end
+
+      class_methods do
+        private
+
+        def define_tokenizable_methods(field)
+          define_method("regenerate_#{field}!") { update!(field => self.class.generate_tokenizable_value(field)) }
+          define_method("revoke_#{field}!")     { update!(field => nil) }
+          define_method("#{field}?")            { self[field].present? }
+          define_singleton_method("authenticate_by_#{field}") { |value| timing_safe_find(field, value) }
+        end
+
+        def timing_safe_find(field, value)
+          return nil if value.blank?
+
+          candidate = find_by(field => value)
+          return nil unless candidate
+
+          stored = candidate[field].to_s
+          given = value.to_s
+          return nil unless stored.bytesize == given.bytesize
+
+          ActiveSupport::SecurityUtils.secure_compare(stored, given) ? candidate : nil
+        end
+      end
+
+      class_methods do
+        def validate_tokenizable_options!(field, type, length)
+          unless column_names.include?(field.to_s)
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Tokenizable: tokenizable field '#{field}' does not exist in the database"
+          end
+
+          unless VALID_TYPES.include?(type)
+            raise ArgumentError,
+                  "ConcernsOnRails::Models::Tokenizable: unknown type '#{type}'. Valid types: #{VALID_TYPES.join(', ')}"
+          end
+
+          return if length.positive?
+
+          raise ArgumentError, "ConcernsOnRails::Models::Tokenizable: length must be a positive integer"
+        end
+
+        def random_string_from_alphabet(alphabet, length)
+          Array.new(length) { alphabet[SecureRandom.random_number(alphabet.size)] }.join
+        end
+
+        private :validate_tokenizable_options!, :random_string_from_alphabet
+      end
+
+      # Assigns the generated value only when blank, so callers can pass an explicit one.
+      # Retries up to MAX_GENERATION_ATTEMPTS times if the in-Ruby uniqueness check hits a
+      # collision — useful for short codes; a unique DB index is still the real guarantee.
+      def assign_tokenizable_value(field)
+        return if self[field].present?
+
+        MAX_GENERATION_ATTEMPTS.times do
+          candidate = self.class.generate_tokenizable_value(field)
+          unless self.class.unscoped.exists?(field => candidate)
+            self[field] = candidate
+            return
+          end
+        end
+
+        raise "ConcernsOnRails::Models::Tokenizable: could not generate a unique value for '#{field}' " \
+              "after #{MAX_GENERATION_ATTEMPTS} attempts — consider a longer length or a larger alphabet"
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.7.0".freeze
+  VERSION = "1.8.2".freeze
 end

data/lib/concerns_on_rails.rb

@@ -17,6 +17,7 @@ require "concerns_on_rails/models/expirable"
 require "concerns_on_rails/models/normalizable"
 require "concerns_on_rails/models/searchable"
 require "concerns_on_rails/models/activatable"
+require "concerns_on_rails/models/tokenizable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.2
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-21 00:00:00.000000000 Z
+date: 2026-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -86,6 +86,7 @@ files:
 - lib/concerns_on_rails/models/sluggable.rb
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb
+- lib/concerns_on_rails/models/tokenizable.rb
 - lib/concerns_on_rails/version.rb
 homepage: https://github.com/VSN2015/concerns_on_rails
 licenses: