opaque_id 1.1.0

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/generators/opaque_id/install_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module OpaqueId
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :table_name, type: :string, default: nil, banner: 'table_name'
+
+      class_option :column_name, type: :string, default: 'opaque_id',
+                                 desc: 'Name of the column to add'
+
+      def create_migration_file
+        if table_name.present?
+          migration_template 'migration.rb.tt',
+                             "db/migrate/add_opaque_id_to_#{table_name}.rb"
+
+          add_include_to_model
+        else
+          say 'Usage: rails generate opaque_id:install TABLE_NAME', :red
+          say 'Example: rails generate opaque_id:install posts', :green
+        end
+      end
+
+      private
+
+      def add_include_to_model
+        model_path = "app/models/#{table_name.singularize}.rb"
+
+        if File.exist?(model_path)
+          # Read existing model file
+          content = File.read(model_path)
+
+          # Check if already included
+          if content.include?('include OpaqueId::Model')
+            say "OpaqueId::Model already included in #{model_path}", :yellow
+          else
+            # Add include statement
+            content.gsub!(/class #{table_name.classify} < ApplicationRecord/,
+                          "class #{table_name.classify} < ApplicationRecord\n  include OpaqueId::Model")
+
+            # Write back to file
+            File.write(model_path, content)
+            say "Updated #{model_path}", :green
+          end
+        else
+          say "Model file #{model_path} not found. Please add 'include OpaqueId::Model' manually.", :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/opaque_id/templates/migration.rb.tt

@@ -0,0 +1,6 @@
+class AddOpaqueIdTo<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :<%= options[:column_name] %>, :string
+    add_index :<%= table_name %>, :<%= options[:column_name] %>, unique: true
+  end
+end

data/lib/opaque_id/model.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module OpaqueId
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      before_create :set_opaque_id
+    end
+
+    class_methods do
+      def find_by_opaque_id(opaque_id)
+        where(opaque_id_column => opaque_id).first
+      end
+
+      def find_by_opaque_id!(opaque_id)
+        find_by_opaque_id(opaque_id) || raise(ActiveRecord::RecordNotFound,
+                                              "Couldn't find #{name} with opaque_id=#{opaque_id}")
+      end
+
+      # Configuration options
+      def opaque_id_column
+        @opaque_id_column ||= :opaque_id
+      end
+
+      def opaque_id_column=(value)
+        @opaque_id_column = value
+      end
+
+      def opaque_id_length
+        @opaque_id_length ||= 21
+      end
+
+      def opaque_id_length=(value)
+        @opaque_id_length = value
+      end
+
+      def opaque_id_alphabet
+        @opaque_id_alphabet ||= OpaqueId::ALPHANUMERIC_ALPHABET
+      end
+
+      def opaque_id_alphabet=(value)
+        @opaque_id_alphabet = value
+      end
+
+      def opaque_id_require_letter_start
+        @opaque_id_require_letter_start ||= false
+      end
+
+      def opaque_id_require_letter_start=(value)
+        @opaque_id_require_letter_start = value
+      end
+
+      def opaque_id_purge_chars
+        @opaque_id_purge_chars ||= []
+      end
+
+      def opaque_id_purge_chars=(value)
+        @opaque_id_purge_chars = value
+      end
+
+      def opaque_id_max_retry
+        @opaque_id_max_retry ||= 3
+      end
+
+      def opaque_id_max_retry=(value)
+        @opaque_id_max_retry = value
+      end
+    end
+
+    private
+
+    def set_opaque_id
+      return if send(opaque_id_column).present?
+
+      opaque_id_max_retry.times do
+        generated_id = generate_opaque_id
+        send("#{opaque_id_column}=", generated_id)
+        return unless self.class.where(opaque_id_column => generated_id).exists?
+      end
+      raise GenerationError, "Failed to generate a unique opaque_id after #{opaque_id_max_retry} attempts"
+    end
+
+    def generate_opaque_id
+      loop do
+        id = OpaqueId.generate(
+          size: opaque_id_length,
+          alphabet: opaque_id_alphabet
+        )
+
+        # Apply letter start requirement
+        next if opaque_id_require_letter_start && !id.match?(/\A[A-Za-z]/)
+
+        # Apply character purging
+        if opaque_id_purge_chars.any?
+          id = id.chars.reject { |char| opaque_id_purge_chars.include?(char) }.join
+          next if id.length < opaque_id_length
+        end
+
+        return id
+      end
+    end
+
+    def opaque_id_column
+      self.class.opaque_id_column
+    end
+
+    def opaque_id_length
+      self.class.opaque_id_length
+    end
+
+    def opaque_id_alphabet
+      self.class.opaque_id_alphabet
+    end
+
+    def opaque_id_max_retry
+      self.class.opaque_id_max_retry
+    end
+
+    def opaque_id_require_letter_start
+      self.class.opaque_id_require_letter_start
+    end
+
+    def opaque_id_purge_chars
+      self.class.opaque_id_purge_chars
+    end
+  end
+end

data/lib/opaque_id/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpaqueId
+  VERSION = '1.1.0'
+end

data/lib/opaque_id.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'opaque_id/version'
+require_relative 'opaque_id/model'
+
+module OpaqueId
+  class Error < StandardError; end
+  class GenerationError < Error; end
+  class ConfigurationError < Error; end
+
+  # Standard URL-safe alphabet (64 characters)
+  STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
+
+  # Alphanumeric alphabet (62 characters)
+  ALPHANUMERIC_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+
+  class << self
+    # Generate a cryptographically secure random ID
+    def generate(size: 21, alphabet: ALPHANUMERIC_ALPHABET)
+      raise ConfigurationError, 'Size must be positive' unless size.positive?
+      raise ConfigurationError, 'Alphabet cannot be empty' if alphabet.nil? || alphabet.empty?
+
+      alphabet_size = alphabet.size
+
+      # Handle edge case: single character alphabet
+      return alphabet * size if alphabet_size == 1
+
+      return generate_fast(size, alphabet) if alphabet_size == 64
+
+      generate_unbiased(size, alphabet, alphabet_size)
+    end
+
+    private
+
+    def generate_fast(size, alphabet)
+      bytes = SecureRandom.random_bytes(size).bytes
+      size.times.map { |i| alphabet[bytes[i] & 63] }.join
+    end
+
+    def generate_unbiased(size, alphabet, alphabet_size)
+      mask = (2 << Math.log2(alphabet_size - 1).floor) - 1
+      step = (1.6 * mask * size / alphabet_size).ceil
+      id = String.new(capacity: size)
+
+      loop do
+        bytes = SecureRandom.random_bytes(step).bytes
+        bytes.each do |byte|
+          masked_byte = byte & mask
+          if masked_byte < alphabet_size
+            id << alphabet[masked_byte]
+            return id if id.size == size
+          end
+        end
+      end
+    end
+  end
+end

data/release-please-config.json

@@ -0,0 +1,55 @@
+{
+  "release-type": "ruby",
+  "packages": {
+    ".": {
+      "package-name": "opaque_id",
+      "version-file": "lib/opaque_id/version.rb"
+    }
+  },
+  "changelog-sections": [
+    {
+      "type": "feat",
+      "section": "Features"
+    },
+    {
+      "type": "fix",
+      "section": "Bug Fixes"
+    },
+    {
+      "type": "perf",
+      "section": "Performance Improvements"
+    },
+    {
+      "type": "revert",
+      "section": "Reverts"
+    },
+    {
+      "type": "docs",
+      "section": "Documentation"
+    },
+    {
+      "type": "style",
+      "section": "Styles"
+    },
+    {
+      "type": "chore",
+      "section": "Miscellaneous Chores"
+    },
+    {
+      "type": "refactor",
+      "section": "Code Refactoring"
+    },
+    {
+      "type": "test",
+      "section": "Tests"
+    },
+    {
+      "type": "build",
+      "section": "Build System"
+    },
+    {
+      "type": "ci",
+      "section": "Continuous Integration"
+    }
+  ]
+}

data/sig/opaque_id.rbs

@@ -0,0 +1,4 @@
+module OpaqueId
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tasks/0001-prd-opaque-id-gem.md

@@ -0,0 +1,202 @@
+# Product Requirements Document: OpaqueId Ruby Gem
+
+## Introduction/Overview
+
+The OpaqueId gem is a Ruby library that generates cryptographically secure, collision-free opaque identifiers for ActiveRecord models. This gem replaces the existing `nanoid.rb` dependency by implementing the same functionality using Ruby's built-in `SecureRandom` methods, eliminating external dependencies while maintaining the same security and performance characteristics.
+
+The primary problem this gem solves is preventing the exposure of incremental database IDs in public URLs and APIs, which can reveal business metrics, enable enumeration attacks, and expose internal system architecture. Instead, it provides opaque, non-sequential identifiers that are URL-friendly and cryptographically secure.
+
+## Goals
+
+1. **Replace nanoid.rb dependency** - Implement equivalent functionality using Ruby's built-in SecureRandom
+2. **Maintain security standards** - Provide cryptographically secure ID generation with unbiased distribution
+3. **Ensure performance** - Achieve 1M+ IDs/sec for 64-character alphabets, 180K+ IDs/sec for 36-character alphabets
+4. **Simplify integration** - Provide seamless ActiveRecord integration with minimal configuration
+5. **Enable wide adoption** - Create comprehensive documentation accessible to all Rails developers
+6. **Ensure reliability** - Implement robust collision detection and retry logic
+7. **Maintain compatibility** - Support Rails 8.0+ and Ruby 3.2+ environments
+
+## User Stories
+
+### Primary Users: Rails Developers
+
+**As a Rails developer**, I want to generate opaque IDs for my models so that I can expose public identifiers without revealing database structure.
+
+**As a Rails developer**, I want to easily integrate opaque ID generation into my existing models so that I don't have to manually implement ID generation logic.
+
+**As a Rails developer**, I want to configure ID generation parameters (length, alphabet, column name) so that I can customize the behavior for different use cases.
+
+**As a Rails developer**, I want to find records by their opaque ID so that I can build public-facing APIs and URLs.
+
+**As a Rails developer**, I want the gem to handle collision detection automatically so that I don't have to worry about duplicate IDs.
+
+**As a Rails developer**, I want comprehensive documentation and examples so that I can quickly understand and implement the gem in my project.
+
+### Secondary Users: Security-Conscious Teams
+
+**As a security-conscious developer**, I want cryptographically secure ID generation so that my public identifiers cannot be predicted or enumerated.
+
+**As a security-conscious developer**, I want unbiased character distribution so that my IDs have maximum entropy and cannot be analyzed for patterns.
+
+## Functional Requirements
+
+### Core ID Generation
+
+1. The system must generate cryptographically secure random IDs using Ruby's `SecureRandom`
+2. The system must implement rejection sampling algorithm to ensure unbiased character distribution
+3. The system must provide optimized fast path for 64-character alphabets using bitwise operations
+4. The system must support custom alphabet configurations
+5. The system must support custom ID length configurations
+6. The system must provide two predefined alphabets: ALPHANUMERIC_ALPHABET (36 chars) and STANDARD_ALPHABET (64 chars)
+
+### ActiveRecord Integration
+
+7. The system must provide `OpaqueId::Model` concern for easy ActiveRecord integration
+8. The system must automatically generate opaque IDs on model creation via `before_create` callback
+9. The system must provide `find_by_opaque_id` and `find_by_opaque_id!` class methods
+10. The system must support custom column names via `opaque_id_column` configuration
+11. The system must implement collision detection with configurable retry attempts
+12. The system must raise appropriate errors when collision resolution fails
+
+### Rails Generator (Optional Convenience Tool)
+
+13. The system must provide optional Rails generator `opaque_id:install` for creating migrations and updating models
+14. The system must generate migration files that add opaque_id column with unique index
+15. The system must automatically add `include OpaqueId::Model` to the corresponding model file
+16. The system must support custom column names via generator options
+17. The system must require explicit table name argument and show clear usage instructions when run without arguments
+18. The system must work with any existing table (new or existing models)
+19. The system must handle edge cases gracefully (missing model file, already included, different class names)
+
+### Configuration Options
+
+20. The system must support `opaque_id_column` configuration (default: `:opaque_id`)
+21. The system must support `opaque_id_length` configuration (default: `18`)
+22. The system must support `opaque_id_alphabet` configuration (default: `ALPHANUMERIC_ALPHABET`)
+23. The system must support `opaque_id_require_letter_start` configuration (default: `true`)
+24. The system must support `opaque_id_purge_chars` configuration (default: `nil`)
+25. The system must support `opaque_id_max_retry` configuration (default: `1000`)
+
+### Error Handling
+
+26. The system must raise `OpaqueId::ConfigurationError` for invalid size or empty alphabet
+27. The system must raise `OpaqueId::GenerationError` when collision resolution fails
+28. The system must provide clear error messages for debugging
+
+### Standalone Usage
+
+29. The system must provide `OpaqueId.generate` method for standalone ID generation
+30. The system must support all configuration options in standalone generation
+31. The system must maintain the same security and performance characteristics in standalone mode
+
+## Non-Goals (Out of Scope)
+
+1. **Other ORM Support** - Will not support Mongoid, Sequel, or other ORMs in initial release
+2. **Non-Rails Usage** - Will not provide standalone Ruby usage without ActiveRecord dependency
+3. **Custom Algorithms** - Will not implement alternative ID generation algorithms beyond rejection sampling
+4. **Database Migrations** - Will not provide automatic database migration for existing records
+5. **ID Validation** - Will not provide built-in ID format validation (users can implement their own)
+6. **Bulk Generation** - Will not provide optimized bulk ID generation methods
+7. **ID Prefixes/Suffixes** - Will not support adding prefixes or suffixes to generated IDs
+8. **Custom Random Sources** - Will not support custom random number generators beyond SecureRandom
+9. **Interactive Generator Mode** - Will not provide interactive prompts for generator arguments
+10. **Backward Compatibility** - Will not maintain compatibility with existing `public_id` implementations
+
+## Design Considerations
+
+### API Design
+
+- Follow Rails conventions for ActiveRecord concerns and generators
+- Use descriptive method names that clearly indicate functionality
+- Provide both safe (`find_by_opaque_id`) and unsafe (`find_by_opaque_id!`) lookup methods
+- Use class-level configuration options for easy customization
+- Follow Devise-style generator pattern for seamless integration
+
+### Performance Optimization
+
+- Implement fast path for 64-character alphabets using bitwise operations (`byte & 63`)
+- Use rejection sampling with optimal mask calculation for unbiased distribution
+- Pre-allocate string capacity to avoid memory reallocation during generation
+- Batch random byte generation to minimize SecureRandom calls
+
+### Security Considerations
+
+- Use only cryptographically secure random number generation
+- Implement proper rejection sampling to avoid modulo bias
+- Provide sufficient entropy through configurable alphabet sizes
+- Ensure IDs cannot be predicted or enumerated
+
+## Technical Considerations
+
+### Dependencies
+
+- **ActiveRecord**: >= 6.0 (targeting Rails 8.0+ compatibility)
+- **ActiveSupport**: >= 6.0 (for concern functionality)
+- **Ruby**: >= 3.2 (for modern Ruby features and performance)
+
+### Testing Framework
+
+- Use **Minitest** instead of RSpec for consistency with Rails conventions
+- Implement comprehensive unit tests for all public methods
+- Include statistical tests for character distribution uniformity
+- Add performance benchmarks to ensure performance requirements are met
+- Test edge cases including collision scenarios and error conditions
+
+### File Structure
+
+```
+lib/
+├── opaque_id.rb                 # Main module with generator
+├── opaque_id/
+│   ├── version.rb               # Version constant
+│   └── model.rb                 # ActiveRecord concern
+└── generators/
+    └── opaque_id/
+        ├── install_generator.rb  # Migration generator
+        └── templates/
+            └── migration.rb.tt   # Migration template
+```
+
+### Error Classes
+
+- `OpaqueId::Error` - Base error class
+- `OpaqueId::GenerationError` - ID generation failures
+- `OpaqueId::ConfigurationError` - Invalid configuration
+
+## Success Metrics
+
+### Performance Metrics
+
+- **Standard alphabet (64 chars)**: Achieve ~1.2M IDs/sec generation rate
+- **Alphanumeric alphabet (36 chars)**: Achieve ~180K IDs/sec generation rate
+- **Custom alphabet (20 chars)**: Achieve ~150K IDs/sec generation rate
+
+### Quality Metrics
+
+- **Test Coverage**: Achieve 95%+ code coverage
+- **Documentation**: Provide comprehensive README with examples
+- **Error Handling**: All error conditions properly tested and documented
+
+### Adoption Metrics
+
+- **Gem Downloads**: Target 1000+ downloads in first month
+- **GitHub Stars**: Target 50+ stars within 6 months
+- **Community Feedback**: Positive reception from Rails community
+
+## Open Questions
+
+1. **Version Strategy**: Should we follow semantic versioning strictly, or use a different versioning strategy for a utility gem?
+
+2. **Backward Compatibility**: How should we handle potential breaking changes in future versions, especially regarding default configurations?
+
+3. **Performance Testing**: Should we include automated performance regression testing in CI/CD, or rely on manual benchmarking?
+
+4. **Documentation Hosting**: Should we create a dedicated documentation site, or rely on GitHub README and inline documentation?
+
+5. **Community Contributions**: What level of community contribution should we expect, and how should we structure the project to encourage contributions?
+
+6. **Integration Testing**: Should we test against multiple Rails versions in CI, or focus on the target Rails 8.0+ range?
+
+7. **Security Auditing**: Should we implement any security auditing tools or processes for the random number generation?
+
+8. **Migration Path**: How should we help users migrate from nanoid.rb to opaque_id, if at all?