rails-uuid-pk 0.12.0 → 0.13.0

data/SECURITY.md

@@ -0,0 +1,321 @@
+# Security Considerations
+
+## Supported Versions
+
+We take security seriously and actively maintain this gem. The following versions are currently supported with security updates:
+
+| Version | Supported          | Security Support Until |
+| ------- | ------------------ | ---------------------- |
+| 0.13.x  | :white_check_mark: | Ongoing                |
+| 0.12.x  | :white_check_mark: | 6 months from 0.13.0  |
+| 0.11.x  | :white_check_mark: | 6 months from 0.12.0  |
+| < 0.11  | :x:                | None                   |
+
+## Reporting a Vulnerability
+
+**Please report security vulnerabilities responsibly.**
+
+If you discover a security vulnerability in rails-uuid-pk, please:
+
+1. **DO NOT** create a public GitHub issue
+2. Email security concerns to: **seouri@gmail.com**
+3. Include detailed information about:
+   - The vulnerability description
+   - Steps to reproduce
+   - Potential impact assessment
+   - Your contact information for follow-up
+
+**Response Time**: We will acknowledge receipt within 24 hours and provide a more detailed response within 72 hours indicating our next steps.
+
+## Cryptographic Security Analysis
+
+### UUIDv7 Cryptographic Properties
+
+This gem uses **UUIDv7** (RFC 9562) for primary key generation, which provides the following security characteristics:
+
+> **Privacy Consideration**: UUIDv7 includes a timestamp component that reveals approximate record creation time. Do not use if creation timestamp must be hidden.
+>
+> **Enhanced Privacy Documentation**: Added explicit warning about UUIDv7 timestamp exposure in SECURITY.md, clarifying that UUIDv7 includes a timestamp component that reveals approximate record creation time and advising against use when creation timestamps must be hidden.
+
+#### Strengths
+- **Cryptographically Secure Generation**: Uses Ruby's `SecureRandom.uuid_v7()` backed by system CSPRNG (OpenSSL or system entropy)
+- **Monotonic Ordering**: Time-based ordering prevents index fragmentation while maintaining unpredictability
+- **High Entropy**: 128-bit randomness with structured time component
+- **RFC 9562 Compliance**: Follows latest UUID standards
+
+#### Known Limitations
+- **Timestamp Exposure**: First 48 bits contain millisecond-precision timestamp
+- **Predictability Window**: Generated UUIDs reveal creation time ± milliseconds
+- **No Forward Secrecy**: Compromised keys don't affect future UUID security
+
+### Timestamp Exposure Considerations
+
+```ruby
+# Example: UUIDv7 reveals generation timestamp
+uuid = "017f22e2-79b0-7cc3-98c4-dc0c0c07398f"
+timestamp_ms = uuid[0..7].to_i(16) >> 4  # Extract 48-bit timestamp
+# This reveals the UUID was generated at: 2023-11-15 10:30:45.123 UTC
+```
+
+**Security Impact**: An attacker observing UUIDs can determine:
+- Approximate creation time of records
+- Rate of record generation
+- Potential correlation between UUID sequences and business activities
+
+**Mitigations**:
+- Use UUIDv4 for applications requiring maximum unpredictability
+- Implement rate limiting to prevent timing attacks
+- Avoid exposing UUIDs in public APIs when timing data is sensitive
+
+## Database Security Implications
+
+### Primary Key Security
+
+#### Sequential ID Vulnerabilities (Avoided)
+Traditional auto-incrementing IDs create security risks:
+- **Enumeration Attacks**: `SELECT * FROM users WHERE id > 1000` reveals user count
+- **Resource Discovery**: Predictable URLs enable scraping
+- **Race Conditions**: Concurrent requests can leak information
+
+#### UUIDv7 Advantages
+- **Non-Enumerability**: No predictable sequence for attackers to exploit
+- **Global Uniqueness**: No collision risks across distributed systems
+- **Index Efficiency**: Time-ordered UUIDs provide better B-tree performance
+
+### Foreign Key Security Considerations
+
+#### Polymorphic Associations
+When using polymorphic references with UUID primary keys:
+
+```ruby
+# Migration
+create_table :comments do |t|
+  t.references :commentable, polymorphic: true, type: :uuid
+end
+```
+
+**Security Implications**:
+- Foreign keys become non-guessable
+- Prevents enumeration of related records
+- Complicates unauthorized data access patterns
+
+#### Join Table Exposure
+Many-to-many relationships expose UUIDs in join tables:
+
+```ruby
+# users_posts join table contains UUID foreign keys
+# An attacker seeing these can correlate users with content
+```
+
+**Recommendations**:
+- Use appropriate access controls regardless of key type
+- Implement row-level security when needed
+- Consider UUID visibility in audit logs
+
+## Performance-Security Trade-offs
+
+### Index Performance vs Security
+
+| Aspect | Integer Keys | UUIDv7 Keys | Security Impact |
+|--------|-------------|-------------|-----------------|
+| **Index Size** | 4 bytes | 16 bytes | Neutral |
+| **Cache Efficiency** | Excellent | Good | Neutral |
+| **Predictability** | High Risk | Low Risk | Security Benefit |
+| **Fragmentation** | None | Low (monotonic) | Security Benefit |
+
+### Query Performance Considerations
+
+#### Range Queries on Time
+UUIDv7's time-based ordering enables efficient time-range queries:
+
+```ruby
+# Find records from last hour (efficient with UUIDv7)
+User.where("id >= ? AND id < ?", min_uuid_for_hour, max_uuid_for_hour)
+```
+
+**Security Benefit**: Enables efficient audit logging and temporal access controls
+
+#### Index Bloat Monitoring
+Large UUID indexes may require monitoring:
+
+```sql
+-- Monitor index bloat (PostgreSQL example)
+SELECT schemaname, tablename, attname, n_distinct, correlation
+FROM pg_stats
+WHERE tablename = 'users' AND attname = 'id';
+```
+
+**Recommendation**: Monitor index statistics and plan maintenance windows
+
+## Side-Channel Attack Vectors
+
+### Timing Attacks
+
+#### UUID Generation Timing
+UUID generation is fast and constant-time, but bulk operations may reveal system load:
+
+```ruby
+# Bulk UUID generation timing can reveal system capacity
+start = Time.now
+100.times { User.create!(name: "User") }
+duration = Time.now - start
+# Duration reveals concurrent load and system performance
+```
+
+**Mitigation**: Implement rate limiting and monitoring
+
+### Information Leakage Through Errors
+
+#### Database Error Messages
+UUID validation errors may leak information:
+
+```ruby
+# Potential information leakage
+User.find("invalid-uuid") # => ActiveRecord::RecordNotFound
+# vs
+User.find("550e8400-e29b-41d4-a716-446655440000") # => User or Not Found
+```
+
+**Mitigation**: Use consistent error messages regardless of UUID validity
+
+### Cross-Application Correlation
+
+#### UUID Reuse Across Services
+Using the same UUID generation in multiple applications can create correlation vectors:
+
+```ruby
+# Service A: User UUID
+# Service B: Order UUID with same timestamp
+# Correlation: Same user placed order at same millisecond
+```
+
+**Recommendation**: Use service-specific UUID namespaces or additional entropy
+
+## Dependency Security
+
+This gem has minimal dependencies with known security postures:
+
+### Runtime Dependencies
+- **rails (~> 8.0)**: Monitored via Rails security advisories
+- **Database adapters**: Follow respective project security practices
+  - **pg (~> 1.6.3)**: PostgreSQL adapter (compatible with PostgreSQL 18+)
+  - **mysql2 (~> 0.5.7)**: MySQL adapter (compatible with MySQL 9+)
+  - **sqlite3 (~> 2.9.0)**: SQLite adapter
+
+### Development Dependencies
+- Testing frameworks with regular security updates
+- Code quality tools (RuboCop, RuboCop-Rails)
+
+## Secure Usage Guidelines
+
+### 1. Application-Level Security
+```ruby
+# DO: Use UUIDs for public-facing identifiers
+class Post < ApplicationRecord
+  # UUID primary key is secure by default
+end
+
+# DON'T: Don't rely on UUID secrecy alone
+class User < ApplicationRecord
+  # Still need authentication and authorization
+  def visible_posts
+    posts.where(published: true) # Business logic access control
+  end
+end
+```
+
+### 2. API Security
+```ruby
+# DO: Use UUIDs in APIs
+get '/posts/:id' do
+  post = Post.find_by!(id: params[:id])
+  authorize! :read, post # Authorization still required
+  render post
+end
+
+# DON'T: Don't assume UUIDs prevent all attacks
+# Rate limiting, input validation still essential
+```
+
+### 3. Database Security
+```ruby
+# DO: Use appropriate access controls
+class ApplicationPolicy
+  def show?
+    user.admin? || record.user_id == user.id
+  end
+end
+
+# DON'T: Don't expose UUIDs unnecessarily
+# Consider using different identifiers for public APIs
+```
+
+## Security Testing Recommendations
+
+### Automated Security Testing
+```ruby
+# Add to test suite
+class SecurityTest < ActiveSupport::TestCase
+  test "UUIDs are not predictable" do
+    uuids = 1000.times.map { SecureRandom.uuid_v7 }
+    # Verify no obvious patterns
+    assert uuids.uniq.length == uuids.length
+  end
+
+  test "timing attack resistance" do
+    # Verify constant-time UUID generation
+    times = 100.times.map do
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      SecureRandom.uuid_v7
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    end
+
+    variance = times.max - times.min
+    assert variance < 0.001 # Less than 1ms variance
+  end
+end
+```
+
+### Penetration Testing Checklist
+- [ ] UUID enumeration attempts
+- [ ] Timing attack analysis
+- [ ] Information leakage through errors
+- [ ] Cross-service correlation analysis
+- [ ] Database access pattern analysis
+
+## Security Maintenance
+
+### Regular Security Reviews
+- **Monthly**: Dependency updates and vulnerability scans
+- **Quarterly**: Security architecture review
+- **Annually**: Full security assessment
+
+### Security Monitoring
+- Monitor for unusual UUID generation patterns
+- Alert on potential enumeration attacks
+- Track performance degradation that might indicate attacks
+
+## Compliance Considerations
+
+### GDPR and Privacy
+- UUIDs as personal data: Generally not considered personal information
+- Audit logging: UUIDs provide excellent audit trails
+- Data minimization: Consider if UUID exposure meets data minimization requirements
+
+### Industry-Specific Security
+- **Healthcare (HIPAA)**: UUIDs support proper access controls
+- **Financial Services**: Enhanced audit capabilities
+- **Government**: Supports classification and access controls
+
+## Conclusion
+
+Rails-UUID-PK provides a secure foundation for UUIDv7 primary keys with proper cryptographic properties and database security benefits. However, security is defense-in-depth: UUIDs enhance security but don't replace proper authentication, authorization, and access controls.
+
+**Key Takeaways**:
+1. UUIDv7 provides better security than sequential IDs
+2. Timestamp exposure is a known trade-off
+3. Application-level security controls remain essential
+4. Monitor performance and security metrics in production
+5. Regular security reviews and updates are critical
+
+For questions about security or to report vulnerabilities, contact the security team at seouri@gmail.com.

data/lib/generators/rails_uuid_pk/add_opt_outs_generator.rb

@@ -0,0 +1,183 @@
+require "rails/generators/base"
+
+module RailsUuidPk
+  # Rails generators for the rails-uuid-pk gem.
+  #
+  # This module contains Rails generator classes that help with migration
+  # and setup tasks for applications using UUID primary keys.
+  #
+  # @see RailsUuidPk::Generators::AddOptOutsGenerator
+  module Generators
+    # Rails generator that scans all ActiveRecord models in a Rails application
+    # and adds `use_integer_primary_key` to models that have integer primary keys
+    # in the database schema.
+    #
+    # This generator helps migrate existing Rails applications that use integer
+    # primary keys to work correctly with the rails-uuid-pk gem, which assumes
+    # UUID primary keys by default.
+    #
+    # @example Run the generator
+    #   rails generate rails_uuid_pk:add_opt_outs
+    #
+    # @example Run with dry-run to see what would be changed
+    #   rails generate rails_uuid_pk:add_opt_outs --dry-run
+    #
+    # @see RailsUuidPk::HasUuidv7PrimaryKey
+    # @see https://github.com/seouri/rails-uuid-pk
+    class AddOptOutsGenerator < Rails::Generators::Base
+      include Thor::Actions
+
+      desc "Scans all ActiveRecord models and adds use_integer_primary_key to models with integer primary keys"
+
+      class_option :dry_run, type: :boolean, default: false, desc: "Show what would be changed without modifying files"
+      class_option :verbose, type: :boolean, default: true, desc: "Provide detailed output for each model processed"
+
+
+
+      # Analyzes all ActiveRecord models and modifies those with integer primary keys.
+      #
+      # This is the main generator method that orchestrates the entire process:
+      # 1. Finds all model files in the application
+      # 2. Analyzes each model for integer primary keys
+      # 3. Modifies model files to add opt-out calls
+      # 4. Reports results to the user
+      #
+      # @return [void]
+      def analyze_and_modify_models
+        say_status :info, "Analyzing ActiveRecord models for integer primary keys...", :blue
+
+        results = analyze_models
+
+        modified_count = 0
+        analyzed_count = results.size
+
+        results.each do |result|
+          if options[:verbose]
+            status = case
+            when result[:modified] then :modified
+            when result[:needs_opt_out] && !result[:already_has_opt_out] then :pending
+            else :skipped
+            end
+            say_status status, "#{result[:model_class].name} (table: #{result[:table_name]}, pk: #{result[:primary_key_type]})", :green
+          end
+
+          modified_count += 1 if result[:modified]
+        end
+
+        say_status :success, "Analyzed #{analyzed_count} models, modified #{modified_count} files", :green
+      end
+
+      private
+
+      def analyze_models
+        model_files = find_model_files
+        connection = ActiveRecord::Base.connection
+
+        model_files.map do |file_path|
+          class_name = extract_class_name_from_file(file_path)
+          next unless class_name
+
+          model_class = class_name.constantize
+          next unless model_class < ActiveRecord::Base
+
+          table_name = model_class.table_name
+          next unless connection.table_exists?(table_name)
+
+          primary_key_type = check_primary_key_type(table_name, connection)
+          already_has_opt_out = model_file_has_opt_out?(file_path)
+
+          needs_opt_out = primary_key_type == :integer && !already_has_opt_out
+
+          modified = false
+          if needs_opt_out && !options[:dry_run]
+            modified = add_opt_out_to_model(file_path, class_name)
+          end
+
+          {
+            model_class: model_class,
+            table_name: table_name,
+            primary_key_type: primary_key_type,
+            needs_opt_out: needs_opt_out,
+            already_has_opt_out: already_has_opt_out,
+            file_path: file_path,
+            modified: modified
+          }
+        end.compact
+      end
+
+      def find_model_files
+        Dir.glob(File.join(destination_root, "app/models/**/*.rb"))
+      end
+
+      def extract_class_name_from_file(file_path)
+        content = File.read(file_path)
+        # Simple regex to find class definition - this is a basic implementation
+        # In a real scenario, you'd want to use a Ruby parser for accuracy
+        match = content.match(/class\s+([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*)/)
+        match[1] if match
+      end
+
+      def check_primary_key_type(table_name, connection)
+        columns = connection.columns(table_name)
+        pk_column = columns.find { |col| col.name == "id" }
+        return :unknown unless pk_column
+
+        # Map database types to our categories
+        case pk_column.type
+        when :integer then :integer
+        when :string then pk_column.limit == 36 ? :uuid : :string
+        when :uuid then :uuid
+        else :unknown
+        end
+      end
+
+      def model_file_has_opt_out?(file_path)
+        content = File.read(file_path)
+        content.include?("use_integer_primary_key")
+      end
+
+      def add_opt_out_to_model(file_path, class_name)
+        content = File.read(file_path)
+
+        # Find the class definition line
+        class_match = content.match(/^(\s*)class\s+#{Regexp.escape(class_name)}/)
+        return false unless class_match
+
+        indent = class_match[1]
+
+        # Find where to insert - after the class definition and any initial comments/constants
+        lines = content.lines
+        insert_index = nil
+
+        lines.each_with_index do |line, index|
+          if line.match?(/^#{Regexp.escape(indent)}class\s+#{Regexp.escape(class_name)}/)
+            # Start looking for insertion point after this line
+            (index + 1..lines.size - 1).each do |i|
+              current_line = lines[i]
+              next if current_line.strip.empty? || current_line.match?(/^#{Regexp.escape(indent)}\s*#/)
+
+              # Insert before the first indented content or end of class
+              if current_line.match?(/^#{Regexp.escape(indent)}\s+\S/) || current_line.match?(/^#{Regexp.escape(indent)}end$/) || i == lines.size - 1
+                insert_index = i
+                break
+              end
+            end
+            break
+          end
+        end
+
+        return false unless insert_index
+
+        # Insert the opt-out method call
+        opt_out_line = "\n#{indent}  use_integer_primary_key\n"
+        new_content = lines.insert(insert_index, opt_out_line).join
+
+        File.write(file_path, new_content)
+        true
+      rescue => e
+        say_status :error, "Failed to modify #{file_path}: #{e.message}", :red
+        false
+      end
+    end
+  end
+end

data/lib/rails_uuid_pk/migration_helpers.rb

@@ -190,7 +190,10 @@ module RailsUuidPk
         return false unless conn.respond_to?(:table_exists?) && conn.table_exists?(table_name)
 
         pk_column = find_primary_key_column(table_name, conn)
-        @uuid_pk_cache[table_name] = !!(pk_column && pk_column.sql_type.downcase.match?(/\A(uuid|varchar\(36\))\z/))
+        @uuid_pk_cache[table_name] = !!(pk_column && pk_column.sql_type&.downcase&.match?(/\A(uuid|varchar\(36\))\z/))
+      rescue StandardError
+        # Handle database connection errors gracefully
+        @uuid_pk_cache[table_name] = false
       end
 
       # Finds the primary key column for a given table.
@@ -200,7 +203,8 @@ module RailsUuidPk
       # @return [ActiveRecord::ConnectionAdapters::Column, nil] The primary key column or nil
       def find_primary_key_column(table_name, conn)
         pk_name = conn.primary_key(table_name)
-        return nil unless pk_name
+        # Only consider standard Rails primary keys named 'id' for UUID detection
+        return nil unless pk_name == "id"
 
         conn.columns(table_name).find { |c| c.name == pk_name }
       end

data/lib/rails_uuid_pk/mysql2_adapter_extension.rb

@@ -7,10 +7,16 @@ module RailsUuidPk
   # type support. It includes the shared UUID adapter extension functionality
   # and provides MySQL-specific connection configuration.
   #
-  # @example Automatic type mapping
-  #   # MySQL tables with VARCHAR(36) columns are automatically treated as UUIDs
-  #   create_table :users do |t|
-  #     t.column :id, :uuid  # Maps to VARCHAR(36) in MySQL
+  # @example UUID primary key and foreign key references
+  #   # Primary key uses UUID type
+  #   create_table :users, id: :uuid do |t|
+  #     t.string :name
+  #   end
+  #
+  #   # Foreign key automatically detects and uses UUID type
+  #   create_table :posts do |t|
+  #     t.references :user  # Automatically uses :uuid type
+  #     t.string :title
   #   end
   #
   # @see RailsUuidPk::UuidAdapterExtension

data/lib/rails_uuid_pk/railtie.rb

@@ -33,13 +33,14 @@ module RailsUuidPk
       end
     end
 
-    # Configures type mappings for SQLite and MySQL adapters.
+    # Configures type mappings for SQLite, MySQL, and Trilogy adapters.
     #
     # Registers the custom UUID type for adapters that don't have native UUID support.
+    # Supports both mysql2 and trilogy adapters for MySQL.
     initializer "rails-uuid-pk.configure_type_map", after: "active_record.initialize_database" do
       ActiveSupport.on_load(:active_record) do
         adapter_name = ActiveRecord::Base.connection.adapter_name
-        if %w[SQLite MySQL].include?(adapter_name)
+        if %w[SQLite MySQL Trilogy].include?(adapter_name)
           RailsUuidPk::Railtie.register_uuid_type(adapter_name.downcase.to_sym)
         end
       end
@@ -57,6 +58,10 @@ module RailsUuidPk
       ActiveSupport.on_load(:active_record_mysql2adapter) do
         prepend RailsUuidPk::Mysql2AdapterExtension
       end
+
+      ActiveSupport.on_load(:active_record_trilogyadapter) do
+        prepend RailsUuidPk::TrilogyAdapterExtension
+      end
     end
 
     # Ensures UUID types are registered on all database connections.

data/lib/rails_uuid_pk/trilogy_adapter_extension.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RailsUuidPk
+  # Trilogy adapter extension for UUID type support.
+  #
+  # This module extends ActiveRecord's Trilogy adapter to provide native UUID
+  # type support. It includes the shared UUID adapter extension functionality
+  # and provides Trilogy-specific connection configuration.
+  #
+  # Trilogy is GitHub's high-performance MySQL adapter that offers significant
+  # performance improvements over the standard mysql2 adapter, particularly for
+  # high-traffic Rails applications.
+  #
+  # @example UUID primary key and foreign key references
+  #   # Primary key uses UUID type
+  #   create_table :users, id: :uuid do |t|
+  #     t.string :name
+  #   end
+  #
+  #   # Foreign key automatically detects and uses UUID type
+  #   create_table :posts do |t|
+  #     t.references :user  # Automatically uses :uuid type
+  #     t.string :title
+  #   end
+  #
+  # @see RailsUuidPk::UuidAdapterExtension
+  # @see RailsUuidPk::Type::Uuid
+  # @see https://github.com/trilogy-libraries/trilogy
+  module TrilogyAdapterExtension
+    include RailsUuidPk::UuidAdapterExtension
+
+    # Configures the database connection with UUID type support.
+    #
+    # @return [void]
+    def configure_connection
+      super
+    end
+  end
+end

data/lib/rails_uuid_pk/version.rb

@@ -7,6 +7,6 @@ module RailsUuidPk
   #
   # @return [String] The current version
   # @example
-  #   RailsUuidPk::VERSION # => "0.12.0"
-  VERSION = "0.12.0"
+  #   RailsUuidPk::VERSION # => "0.13.0"
+  VERSION = "0.13.0"
 end

data/lib/rails_uuid_pk.rb

@@ -6,8 +6,12 @@ require "rails_uuid_pk/type"
 require "rails_uuid_pk/uuid_adapter_extension"
 require "rails_uuid_pk/sqlite3_adapter_extension"
 require "rails_uuid_pk/mysql2_adapter_extension"
+require "rails_uuid_pk/trilogy_adapter_extension"
 require "rails_uuid_pk/railtie"
 
+# Load generators
+require "generators/rails_uuid_pk/add_opt_outs_generator" if defined?(Rails::Generators)
+
 # Rails UUID Primary Key
 #
 # A Rails gem that automatically uses UUIDv7 for all primary keys in Rails applications.