tokenize_attr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: abf1c8d9447a7b940dca5bd4759bf60c82ffb967dfcffa18d5df14b41512cfe2
+  data.tar.gz: c88d3236ac9fae09d5c9d879f4ac0baba43df11ebe8408db5d039fae58b2bd6c
+SHA512:
+  metadata.gz: f50afa2586d8689212b18a1577da21b372cf499fb1022279475ed609adc0dea4ddcfa712d7ecaa6d70a9fba38732886b68445737f82f8541cd0cf8ba620da4b5
+  data.tar.gz: d6e087c763c99973351e884a3cb81b7a13527b04e8664cbe15946fbb1bb77d7fe5bec4a49dfc1827271206f827681c68c3ca782f4386a3a0b76e023edee827b0

data/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md — tokenize_attr
+
+This file is the primary context document for AI agents and LLMs working on
+this gem. Read it fully before making any changes.
+
+---
+
+## What this gem does
+
+`tokenize_attr` provides a single public API — the `tokenize` class macro —
+available on any ActiveRecord model (or any class with `before_create` and
+a class-level `exists?` method).
+
+**When no prefix and no generator are given** and the including class responds
+to `has_secure_token` (Rails 5+), `tokenize` delegates entirely to that
+built-in. This gives Rails-idiomatic token generation for free and avoids
+duplicating Rails core behaviour.
+
+**When a prefix or a custom generator is given** (or `has_secure_token` is
+unavailable), `tokenize` installs a `before_create` callback that:
+
+1. Skips if the attribute already has a value (`present?` check).
+2. Calls `generator.call(size)` if a generator was provided, otherwise calls
+   `SecureRandom.base58(size)` to produce the random portion.
+3. Prepends `prefix-` to the random portion when `prefix:` is set.
+4. Checks uniqueness via `self.class.exists?(attribute => candidate)`.
+5. Retries up to `retries` times (default 3).
+6. Raises `TokenizeAttr::RetryExceededError` if all retries are exhausted.
+
+---
+
+## File map
+
+| File                              | Role                                                              |
+|-----------------------------------|-------------------------------------------------------------------|
+| `lib/tokenize_attr.rb`            | Entry point. Requires sub-files and registers the on_load hook.   |
+| `lib/tokenize_attr/version.rb`    | `TokenizeAttr::VERSION` constant.                                 |
+| `lib/tokenize_attr/errors.rb`     | `TokenizeAttr::Error` and `TokenizeAttr::RetryExceededError`.     |
+| `lib/tokenize_attr/tokenizer.rb`  | `TokenizeAttr::Tokenizer` — all token-generation logic (private). |
+| `lib/tokenize_attr/concern.rb`    | `TokenizeAttr::Concern` — thin concern with the `tokenize` macro. |
+| `test/test_helper.rb`             | In-memory SQLite setup, loads the gem.                            |
+| `test/test_tokenize_attr.rb`      | Full test suite.                                                  |
+| `sig/tokenize_attr.rbs`           | RBS type signatures.                                              |
+| `llms/overview.md`                | Internal design notes for LLMs.                                   |
+| `llms/usage.md`                   | Common usage patterns for LLMs.                                   |
+
+---
+
+## Design decisions
+
+### Why delegate to `has_secure_token`?
+Rails' `has_secure_token` is battle-tested and available in every Rails 5+
+app. Delegating when possible avoids reimplementing core Rails behaviour and
+ensures compatibility with any `regenerate_<attr>` helpers Rails adds.
+
+### Why `SecureRandom.base58`?
+Base58 produces URL-safe strings without ambiguous characters (no `0`, `O`,
+`I`, `l`). Combined with a meaningful prefix it creates tokens that are both
+human-readable and collision-resistant.
+
+### Why configurable `retries` with an explicit error?
+Silent token-generation failures are worse than loud ones. A configurable
+retry budget with an explicit error makes the failure mode observable and
+actionable. The default of 3 is generous given the token space size.
+
+### Why is `retries` ignored when delegating to `has_secure_token`?
+Rails does not perform uniqueness checks in `has_secure_token`; it relies on
+the DB constraint and the astronomically large token space. Retrying there
+would be misleading. Document the discrepancy clearly.
+
+### Why does a generator always bypass `has_secure_token`?
+The user has explicitly chosen a custom algorithm. Delegating to
+`has_secure_token` anyway would silently ignore the generator, which is
+surprising. Presence of a generator always routes through the callback path.
+
+### Why is `TokenizeAttr::Tokenizer` a separate class?
+Keeping all generation helpers in `Tokenizer` rather than in the
+`class_methods` block of `Concern` ensures that none of those methods are
+mixed into the user's model class. This eliminates any risk of method-name
+collisions for models that happen to define methods with similar names.
+`Concern` only exposes the single public `tokenize` macro.
+
+---
+
+## Guardrails
+
+- **Do not change the `tokenize` signature** without a major version bump.
+- **Do not add a hard runtime dependency on `activerecord`**. Only
+  `activesupport` is required. AR's `before_create` and `exists?` are
+  consumed via duck typing.
+- **Keep tests without the `rails` gem**. The suite uses bare `activerecord`
+  + in-memory SQLite — no full Rails boot.
+- **Do not swallow `RetryExceededError`**. It is intentionally raised so
+  callers can handle it.
+- **Keep `TokenizeAttr::Tokenizer` methods private** (except `apply`). The
+  class is `@api private`; only `apply` is the stable internal contract.
+
+---
+
+## Test conventions
+
+- One `Minitest::Test` subclass per behavioural group.
+- `setup` truncates the shared `records` table via a raw SQL DELETE.
+- Collision scenarios are tested using **anonymous subclasses** that override
+  `exists?` directly (e.g. `Class.new(ApiClient) { def self.exists?(*) = true }`).
+  Do **not** use minitest's `stub` on AR model classes — ActiveRecord 8.x
+  `method_missing` intercepts `stub` before minitest can install it.
+- Model classes share `self.table_name = "records"` so the schema stays flat.
+- All column names used by test models must exist in the `records` table
+  defined in `test/test_helper.rb`.

data/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md — tokenize_attr
+
+## Start here
+
+Before writing any code, read these files in order:
+
+1. **@AGENTS.md** — architecture, design decisions, guardrails, test conventions
+2. **@llms/overview.md** — class responsibilities and internal design notes
+3. **@llms/usage.md** — common patterns and recipes
+
+---
+
+## Project context

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pawel Niemczyk
+
+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,180 @@
+# tokenize_attr
+
+Declarative secure token generation for ActiveRecord model attributes.
+
+`tokenize_attr` adds a `tokenize` class macro to ActiveRecord models. When no
+prefix is needed it transparently delegates to Rails' built-in
+`has_secure_token` (Rails 5+). When a prefix is required — or when
+`has_secure_token` is unavailable — it installs a `before_create` callback
+backed by `SecureRandom.base58` with configurable size, prefix, and retry
+logic.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "tokenize_attr"
+```
+
+## Usage
+
+### Basic — delegates to `has_secure_token`
+
+When no prefix is provided and the model supports `has_secure_token` (every
+Rails 5+ `ApplicationRecord`), the built-in Rails implementation is used
+automatically.
+
+```ruby
+class User < ApplicationRecord
+  tokenize :api_token
+end
+
+user = User.create!
+user.api_token # => "aBcD1234..." (64 base58 chars by default)
+```
+
+### With prefix
+
+When a `prefix:` is given the gem installs its own `before_create` callback.
+
+```ruby
+class AccessToken < ApplicationRecord
+  tokenize :token, prefix: "tok", size: 32
+end
+
+AccessToken.create!.token # => "tok-aBcD1234..." ("tok-" + 32 random chars)
+```
+
+### Custom size (no prefix)
+
+```ruby
+class Session < ApplicationRecord
+  tokenize :session_id, size: 128
+end
+```
+
+### Custom retry budget
+
+```ruby
+class InviteCode < ApplicationRecord
+  # Retry up to 5 times before raising TokenizeAttr::RetryExceededError
+  tokenize :code, prefix: "inv", retries: 5
+end
+```
+
+### Custom generator
+
+Pass any callable as the second argument (or as a block) to replace
+`SecureRandom.base58` with your own algorithm. The callable receives `size`
+and must return a String.
+
+```ruby
+# Proc as second positional argument
+class Order < ApplicationRecord
+  tokenize :reference, proc { |size| SecureRandom.alphanumeric(size) },
+           prefix: "ord", size: 12
+end
+
+Order.create!.reference # => "ord-aB3cD4eF5gH6"
+```
+
+```ruby
+# Method reference via &
+class Order < ApplicationRecord
+  def self.reference_generator(size) = SecureRandom.alphanumeric(size)
+  tokenize :reference, &method(:reference_generator)
+end
+```
+
+```ruby
+# Inline block (parentheses required)
+class Order < ApplicationRecord
+  tokenize(:reference) { |size| SecureRandom.alphanumeric(size) }
+end
+```
+
+> **Note:** Providing a generator always uses the callback path — even when
+> no `prefix:` is given. The generator takes precedence over
+> `has_secure_token`.
+
+### Multiple tokenized attributes
+
+```ruby
+class ApiCredential < ApplicationRecord
+  tokenize :public_key,  prefix: "pk", size: 32
+  tokenize :private_key, prefix: "sk", size: 64
+end
+```
+
+## Options
+
+| Option      | Default | Description                                                      |
+|-------------|---------|------------------------------------------------------------------|
+| `generator` | `nil`   | Proc/block called as `generator.call(size)` → String.            |
+|             |         | Overrides the default `SecureRandom.base58` algorithm.           |
+| `size`      | `64`    | Length passed to the generator or to `SecureRandom.base58`.      |
+| `prefix`    | `nil`   | String prepended as `"prefix-<token>"`.                          |
+| `retries`   | `3`     | Max uniqueness-check attempts (custom callback path only).       |
+
+> **Note:** `retries` is ignored when delegating to `has_secure_token`
+> because Rails does not perform uniqueness checks there. Use a DB unique
+> index to enforce uniqueness and let the DB raise on collision.
+
+## Error handling
+
+When the custom callback exhausts all retry attempts it raises
+`TokenizeAttr::RetryExceededError` (a subclass of `TokenizeAttr::Error <
+StandardError`).
+
+```ruby
+begin
+  InviteCode.create!
+rescue TokenizeAttr::RetryExceededError => e
+  Rails.logger.error(e.message)
+  # => "Could not generate a unique token for :code after 5 retries"
+end
+```
+
+## Rails integration
+
+When loaded inside a Rails application `TokenizeAttr::Concern` is
+auto-included into `ActiveRecord::Base` via `ActiveSupport.on_load`, so
+every model gains the `tokenize` macro without an explicit include.
+
+Outside of Rails (or with non-AR classes that provide `before_create` and
+`exists?`) include the concern manually:
+
+```ruby
+class MyModel
+  include TokenizeAttr::Concern
+end
+```
+
+## Recommended migration
+
+Add a unique index on tokenized columns to enforce uniqueness at the DB
+level:
+
+```ruby
+add_column :access_tokens, :token, :string
+add_index  :access_tokens, :token, unique: true
+```
+
+## Development
+
+```bash
+bin/setup              # install dependencies
+bundle exec rake test  # run the test suite
+bin/console            # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/pniemczyk/tokenize_attr.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/tokenize_attr/concern.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module TokenizeAttr
+  # Include this concern in any ActiveRecord model (or any class that
+  # provides +before_create+ and a class-level +exists?+ predicate) to gain
+  # the +tokenize+ class macro.
+  #
+  # When Rails is loaded the concern is auto-included into
+  # +ActiveRecord::Base+ via an +ActiveSupport.on_load+ hook, so explicit
+  # inclusion is not needed in Rails apps.
+  #
+  # All generation logic is delegated to +TokenizeAttr::Tokenizer+ so that no
+  # internal helpers are mixed into the model class.
+  module Concern
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Configures secure token generation for +attribute+.
+      #
+      # When +prefix+ is +nil+ *and* no +generator+ is given *and* the
+      # including class responds to +has_secure_token+ (Rails 5+), the
+      # Rails built-in is used. Note: +retries+ is ignored in that path
+      # because +has_secure_token+ relies on DB constraints rather than
+      # an application-level uniqueness check.
+      #
+      # Otherwise a custom +before_create+ callback is installed. All
+      # implementation details live in +TokenizeAttr::Tokenizer+.
+      #
+      # @param attribute  [Symbol]            the attribute to assign the token to
+      # @param generator  [Proc, nil]         optional callable invoked as
+      #   +generator.call(size)+ to produce the random portion of the token.
+      #   May also be supplied as a block.  When present the custom callback
+      #   path is always used, even when +has_secure_token+ is available.
+      # @param size       [Integer]           length passed to the generator or
+      #   to +SecureRandom.base58+ (default 64)
+      # @param prefix     [String, nil]       optional prefix, joined as
+      #   +"prefix-<token>"+
+      # @param retries    [Integer]           max uniqueness-check retries
+      #   (default 3); ignored on the +has_secure_token+ path
+      #
+      # @raise [TokenizeAttr::RetryExceededError] when uniqueness cannot be
+      #   established within the retry budget
+      #
+      # @example Delegate to has_secure_token (no prefix, no generator)
+      #   class User < ApplicationRecord
+      #     tokenize :api_token
+      #   end
+      #
+      # @example Custom callback with prefix
+      #   class AccessToken < ApplicationRecord
+      #     tokenize :token, size: 32, prefix: "tok"
+      #   end
+      #
+      #   AccessToken.create!.token #=> "tok-aBcD1234..."
+      #
+      # @example Proc passed as second argument
+      #   class Order < ApplicationRecord
+      #     tokenize :reference, proc { |size| SecureRandom.alphanumeric(size) },
+      #              prefix: "ord", size: 12
+      #   end
+      #
+      # @example Method reference via &
+      #   class Order < ApplicationRecord
+      #     def self.reference_generator(size) = SecureRandom.alphanumeric(size)
+      #     tokenize :reference, &method(:reference_generator)
+      #   end
+      #
+      # @example Inline block
+      #   class Order < ApplicationRecord
+      #     tokenize(:reference) { |size| SecureRandom.alphanumeric(size) }
+      #   end
+      def tokenize(attribute, generator = nil, size: 64, prefix: nil, retries: 3, &block)
+        TokenizeAttr::Tokenizer.apply(
+          self, attribute,
+          generator: generator || block,
+          size: size,
+          prefix: prefix,
+          retries: retries
+        )
+      end
+    end
+  end
+end

data/lib/tokenize_attr/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TokenizeAttr
+  # Base error class for all tokenize_attr exceptions.
+  class Error < StandardError; end
+
+  # Raised when a unique token cannot be generated within the configured
+  # number of retries.
+  #
+  # @example
+  #   begin
+  #     MyModel.create!
+  #   rescue TokenizeAttr::RetryExceededError => e
+  #     Rails.logger.error(e.message)
+  #   end
+  class RetryExceededError < Error
+    # @param attribute [Symbol, String] the attribute that failed to tokenize
+    # @param retries   [Integer]        the number of attempts that were made
+    def initialize(attribute, retries)
+      super("Could not generate a unique token for :#{attribute} after #{retries} retries")
+    end
+  end
+end

data/lib/tokenize_attr/tokenizer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module TokenizeAttr
+  # Internal class that holds all token-generation logic.
+  #
+  # Keeping this logic here — rather than inside +TokenizeAttr::Concern+'s
+  # +class_methods+ block — ensures that none of these methods are mixed
+  # into the including model class, eliminating any risk of method-name
+  # collisions on user models.
+  #
+  # @api private
+  class Tokenizer
+    class << self
+      # Determines which generation strategy to use and configures +klass+.
+      #
+      # Routes to +has_secure_token+ when all of the following are true:
+      # - +generator+ is +nil+
+      # - +prefix+ is +nil+
+      # - +klass+ responds to +has_secure_token+ (Rails 5+)
+      #
+      # Otherwise installs a custom +before_create+ callback.
+      #
+      # @param klass     [Class]         the model class to configure
+      # @param attribute [Symbol]        the attribute to assign the token to
+      # @param generator [Proc, nil]     optional callable invoked as
+      #   +generator.call(size)+ to produce the random portion
+      # @param size      [Integer]       length passed to the generator or to
+      #   +SecureRandom.base58+
+      # @param prefix    [String, nil]   optional prefix, joined as
+      #   +"prefix-<token>"+
+      # @param retries   [Integer]       max uniqueness-check attempts;
+      #   ignored on the +has_secure_token+ path
+      def apply(klass, attribute, generator:, size:, prefix:, retries:) # rubocop:disable Metrics/ParameterLists
+        if generator.nil? && prefix.nil? && has_secure_token?(klass)
+          via_has_secure_token(klass, attribute, size)
+        else
+          via_callback(klass, attribute, size: size, prefix: prefix,
+                                         retries: retries, generator: generator)
+        end
+      end
+
+      private
+
+      def has_secure_token?(klass) # rubocop:disable Naming/PredicatePrefix
+        klass.respond_to?(:has_secure_token)
+      end
+
+      # Delegates to Rails' has_secure_token. Passes +length:+ when supported
+      # (Rails 6.1+); falls back silently on older Rails versions.
+      def via_has_secure_token(klass, attribute, size)
+        klass.has_secure_token(attribute, length: size)
+      rescue ArgumentError
+        klass.has_secure_token(attribute)
+      end
+
+      # Installs a +before_create+ callback for custom token generation.
+      #
+      # When +generator+ is provided it is called as +generator.call(size)+
+      # to produce the random portion; otherwise +SecureRandom.base58(size)+
+      # is used.
+      def via_callback(klass, attribute, size:, prefix:, retries:, generator: nil) # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        klass.before_create do
+          next if send(attribute).present?
+
+          token_generated = false
+
+          retries.times do
+            random_part = generator ? generator.call(size) : SecureRandom.base58(size)
+            candidate   = [prefix, random_part].compact.join("-")
+            send(:"#{attribute}=", candidate)
+
+            unless self.class.exists?(attribute => candidate)
+              token_generated = true
+              break
+            end
+          end
+
+          raise TokenizeAttr::RetryExceededError.new(attribute, retries) unless token_generated
+        end
+      end
+    end
+  end
+end

data/lib/tokenize_attr/version.rb

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

data/lib/tokenize_attr.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "securerandom"
+
+require_relative "tokenize_attr/version"
+require_relative "tokenize_attr/errors"
+require_relative "tokenize_attr/tokenizer"
+require_relative "tokenize_attr/concern"
+
+module TokenizeAttr
+  # When loaded inside a Rails application, auto-include the concern into
+  # ActiveRecord::Base so every model gains the +tokenize+ macro without
+  # an explicit include. If ActiveRecord is already loaded (e.g. in tests
+  # without a full Rails boot) the block executes immediately.
+  ActiveSupport.on_load(:active_record) { include TokenizeAttr::Concern }
+end

data/llms/overview.md

@@ -0,0 +1,81 @@
+# tokenize_attr — LLM Context Overview
+
+> Load this file before modifying or extending the gem.
+
+## Purpose
+
+`tokenize_attr` is a Ruby gem that provides declarative secure token generation
+for ActiveRecord model attributes via a single `tokenize` class macro.
+
+---
+
+## Public API
+
+```ruby
+# Full signature
+tokenize(attribute, generator = nil, size: 64, prefix: nil, retries: 3, &block)
+```
+
+| Param       | Type             | Default | Notes                                              |
+|-------------|------------------|---------|----------------------------------------------------|
+| `attribute` | Symbol           | —       | The attribute to tokenize                          |
+| `generator` | Proc / nil       | nil     | Called as `generator.call(size)` for random part.  |
+|             |                  |         | May also be supplied as a `&block`.                |
+| `size`      | Integer          | 64      | Passed to generator or to `SecureRandom.base58`    |
+| `prefix`    | String / nil     | nil     | Prepended as `"prefix-<token>"`                    |
+| `retries`   | Integer          | 3       | Max uniqueness-check attempts (callback path only) |
+
+---
+
+## Internal decision tree
+
+All logic below lives in `TokenizeAttr::Tokenizer` (see
+`lib/tokenize_attr/tokenizer.rb`). `TokenizeAttr::Concern#tokenize` is a thin
+delegator that calls `TokenizeAttr::Tokenizer.apply`.
+
+```
+tokenize called  →  TokenizeAttr::Tokenizer.apply(klass, attribute, ...)
+  └─ generator nil? AND prefix nil? AND has_secure_token available?
+       ├─ YES → Tokenizer.via_has_secure_token(klass, attribute, size)
+       │          tries: klass.has_secure_token(attribute, length: size)
+       │          rescue ArgumentError → klass.has_secure_token(attribute)
+       │          (retries param is IGNORED on this path)
+       │
+       └─ NO  → Tokenizer.via_callback(klass, attribute, size:, prefix:, retries:, generator:)
+                  klass.before_create:
+                    attribute.present? → skip
+                    loop retries times:
+                      random_part = generator ? generator.call(size)
+                                              : SecureRandom.base58(size)
+                      candidate = [prefix, random_part].compact.join("-")
+                      assign candidate to attribute
+                      exists?(attribute => candidate)? → next iteration
+                      else → token_generated = true; break
+                    token_generated? → done
+                    else → raise RetryExceededError
+```
+
+---
+
+## Error class hierarchy
+
+```
+StandardError
+  └── TokenizeAttr::Error
+        └── TokenizeAttr::RetryExceededError
+```
+
+---
+
+## Key constraints
+
+- Only `activesupport` is a hard runtime dependency.
+- `ActiveRecord::Base` receives the concern via `ActiveSupport.on_load(:active_record)`.
+- All generation helpers live in `TokenizeAttr::Tokenizer`, not in the model
+  class. This prevents method-name collisions on user models. Only the
+  `tokenize` macro is mixed in via `Concern`.
+- Tests use bare `activerecord` + SQLite3 — no `rails` gem.
+- `has_secure_token` delegation is skipped when `prefix:` is provided
+  because that built-in has no prefix support.
+- `has_secure_token` delegation is also skipped when a `generator` is
+  provided — the generator always routes through the callback path.

data/llms/usage.md

@@ -0,0 +1,181 @@
+# tokenize_attr — Usage Patterns
+
+> Common patterns and recipes for LLMs helping users work with this gem.
+
+---
+
+## Basic (no prefix) — delegates to `has_secure_token`
+
+```ruby
+class User < ApplicationRecord
+  tokenize :api_token
+end
+
+user = User.create!
+user.api_token # => "aBcD1234..." (64 base58 chars)
+```
+
+`has_secure_token` is used automatically. `retries` is ignored on this path.
+
+---
+
+## With prefix — uses custom callback
+
+```ruby
+class AccessToken < ApplicationRecord
+  tokenize :token, prefix: "tok", size: 32
+end
+
+token = AccessToken.create!
+token.token # => "tok-aBcD1234..." ("tok-" + 32 random chars)
+```
+
+---
+
+## Custom size (no prefix)
+
+```ruby
+class Session < ApplicationRecord
+  tokenize :session_id, size: 128
+end
+```
+
+---
+
+## Custom retry budget
+
+```ruby
+class InviteCode < ApplicationRecord
+  tokenize :code, prefix: "inv", retries: 5
+end
+```
+
+---
+
+## Handling `RetryExceededError`
+
+```ruby
+begin
+  InviteCode.create!
+rescue TokenizeAttr::RetryExceededError => e
+  Rails.logger.error("Token generation failed: #{e.message}")
+  # => "Could not generate a unique token for :code after 5 retries"
+end
+```
+
+---
+
+## Custom generator — proc as second argument
+
+```ruby
+class Order < ApplicationRecord
+  tokenize :reference, proc { |size| SecureRandom.alphanumeric(size) },
+           prefix: "ord", size: 12
+end
+
+Order.create!.reference # => "ord-aB3cD4eF5gH6"
+```
+
+The proc receives `size` and must return a String. The `prefix` is still
+applied on top of whatever the proc returns.
+
+---
+
+## Custom generator — method reference via `&`
+
+```ruby
+class Order < ApplicationRecord
+  def self.reference_generator(size)
+    SecureRandom.alphanumeric(size)
+  end
+
+  tokenize :reference, &method(:reference_generator)
+end
+```
+
+`method(:reference_generator)` converts the class method to a `Method`
+object which responds to `call(size)`. This is identical to passing a proc.
+
+---
+
+## Custom generator — inline block
+
+```ruby
+class Order < ApplicationRecord
+  # Parentheses required when passing a block to a method call inside a class
+  tokenize(:reference) { |size| SecureRandom.alphanumeric(size) }
+end
+```
+
+---
+
+## Custom generator with no prefix — bypasses `has_secure_token`
+
+Providing any generator always uses the callback path, even when no `prefix:`
+is given and `has_secure_token` is available:
+
+```ruby
+class User < ApplicationRecord
+  tokenize :api_token, proc { |size| "usr_#{SecureRandom.hex(size / 2)}" }
+end
+```
+
+---
+
+## Multiple tokenized attributes
+
+```ruby
+class ApiCredential < ApplicationRecord
+  tokenize :public_key,  prefix: "pk", size: 32
+  tokenize :private_key, prefix: "sk", size: 64
+end
+```
+
+---
+
+## Manual inclusion (non-Rails or non-AR classes)
+
+```ruby
+class MyModel
+  include TokenizeAttr::Concern
+
+  # Provide before_create and self.exists? for the concern to work.
+end
+```
+
+---
+
+## Recommended migration
+
+```ruby
+# db/migrate/YYYYMMDDHHMMSS_add_token_to_access_tokens.rb
+class AddTokenToAccessTokens < ActiveRecord::Migration[7.1]
+  def change
+    add_column :access_tokens, :token, :string
+    add_index  :access_tokens, :token, unique: true
+  end
+end
+```
+
+---
+
+## Checking which path `tokenize` will use
+
+```ruby
+# In a Rails console or script:
+MyModel.respond_to?(:has_secure_token) # => true/false
+# true  → tokenize without prefix will use has_secure_token
+# false → tokenize always uses the custom callback
+```
+
+---
+
+## Preserving a pre-set token
+
+The callback checks `present?` before generating, so a pre-set value is
+always preserved:
+
+```ruby
+token = AccessToken.create!(token: "tok-my-custom-value")
+token.token # => "tok-my-custom-value"
+```

data/sig/tokenize_attr.rbs

@@ -0,0 +1,35 @@
+module TokenizeAttr
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class RetryExceededError < Error
+    def initialize: (Symbol | String attribute, Integer retries) -> void
+  end
+
+  # @api private
+  class Tokenizer
+    def self.apply: (
+      Class klass,
+      Symbol attribute,
+      generator: Proc?,
+      size: Integer,
+      prefix: String?,
+      retries: Integer
+    ) -> void
+  end
+
+  module Concern
+    module ClassMethods
+      # generator may be passed as a positional Proc OR as a block.
+      def tokenize: (
+        Symbol attribute,
+        ?Proc? generator,
+        ?size: Integer,
+        ?prefix: String?,
+        ?retries: Integer
+      ) ?{ (Integer) -> String } -> void
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: tokenize_attr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pawel Niemczyk
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: |
+  tokenize_attr adds a `tokenize` class macro to ActiveRecord models. When no
+  prefix is needed it transparently delegates to Rails' built-in
+  has_secure_token (Rails 5+). When a prefix is required it installs a
+  before_create callback backed by SecureRandom.base58 with configurable
+  size, prefix, and retry logic.
+email:
+- pniemczyk.info@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tokenize_attr.rb
+- lib/tokenize_attr/concern.rb
+- lib/tokenize_attr/errors.rb
+- lib/tokenize_attr/tokenizer.rb
+- lib/tokenize_attr/version.rb
+- llms/overview.md
+- llms/usage.md
+- sig/tokenize_attr.rbs
+homepage: https://github.com/pniemczyk/tokenize_attr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pniemczyk/tokenize_attr
+  source_code_uri: https://github.com/pniemczyk/tokenize_attr
+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: 3.6.9
+specification_version: 4
+summary: Declarative secure token generation for ActiveRecord model attributes.
+test_files: []