encoded_ids 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31d25d05fa2a21196dee435efb25c144e2cf90ee3837c8da263f49c22f1e8825
-  data.tar.gz: 54af5781a3455a70b96b5033e6dc9e58b1ea0c8cc3b64a0afc4b5dbe83fd5c35
+  metadata.gz: cc01cbbed877c526bd59169c2f74f183ef909fb2da4beecb9354ac0b48d0723a
+  data.tar.gz: ae607c87436672951ebed59c753a7e4c01ebd0f249a5a1d6c196c9b5ff6cdcb3
 SHA512:
-  metadata.gz: bebf4a30fd0307ad7514e57088cca68bfab718789ef7d5d13506bd6bf312caf3d3f02442e1d87186c3fc5e3c5c9dbbf2dbf84fd71188537af41472a1048a3583
-  data.tar.gz: b83f9254cae57f08270f9c4da0db06fef2883b07641ad20d0fe6f00b6e25d60b2a3ca1737d2cd993b84ea144140de382268f29bfd5af9bfdcc3bf8738dbbdd6e
+  metadata.gz: 3a203a1bf4c38e6652ad256aa668d319991be746b0b20e187ae3d9de26851650da8e7fb20dca7aecd0a4ee019d23be1ce402f8a83d9e5c9d3ea9fd66364be1ae
+  data.tar.gz: d9cea9e34f8b0e2816b0a509794b613fc47ae3159eb5c6add6f7b5e2fc789da51f7c88edb55b7ab52f65bb2d69c2204be5fc6c14fc0af31b8005c8af5bb0077d

data/CHANGELOG.md

@@ -5,12 +5,31 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-02-12
+
+### Added
+- Per-model salt override support via `salt:` parameter in `set_public_id_prefix`
+- Environment variable support (`ENV["HASHID_SALT"]`) in salt fallback chain
+- Development warning when no custom salt is configured
+- Enhanced security documentation in README
+- Security examples in models.rb showing salt override patterns
+
+### Changed
+- Improved salt fallback chain: config → credentials → ENV → secret_key_base
+- Enhanced initializer example with better security guidance
+- Updated documentation to emphasize importance of using a unique salt
+
+### Security
+- **IMPORTANT**: Without a unique salt, hash IDs can be calculated by anyone who knows your database IDs
+- Per-model salts allow for better security isolation between models
+- Empty salt option (`salt: ""`) available for backward compatibility with legacy systems
+
 ## [1.0.0] - 2026-02-09
 
 ### Added
 - Initial stable release
-- `HashidEncodedIds` concern for integer primary keys
-- `UuidEncodedIds` concern for UUID primary keys
+- `HashidIdentifiable` concern for integer primary keys
+- `UuidIdentifiable` concern for UUID primary keys
 - Automatic `to_param` override for Rails URL generation
 - Overridden `find` method to accept both internal and public IDs
 - `find_by_public_id` and `find_by_public_id!` class methods

data/README.md

@@ -158,7 +158,8 @@ Create an initializer at `config/initializers/encoded_ids.rb`:
 ```ruby
 EncodedIds.configure do |config|
   # Hashid configuration (for integer IDs)
-  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt)
+  # SECURITY IMPORTANT: Set a unique salt! See Security section below.
+  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt) || ENV["HASHID_SALT"]
   config.hashid_min_length = 8
   config.hashid_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
 
@@ -175,15 +176,48 @@ EncodedIds.configure do |config|
 end
 ```
 
-**Important:** For production, set a unique `hashid_salt` in your credentials:
+### Security: Configuring Your Salt
+
+**IMPORTANT:** Without a unique salt, hash IDs can be calculated by anyone who knows your database IDs, making them only marginally better than exposing raw IDs.
+
+The gem uses a fallback chain for the salt:
+1. `EncodedIds.configuration.hashid_salt` (set in initializer)
+2. `Rails.application.credentials.dig(:hashid, :salt)` (recommended)
+3. `ENV["HASHID_SALT"]`
+4. `Rails.application.secret_key_base` (not recommended - shows warning in development)
+
+**Recommended setup:**
 
 ```bash
+# Generate a unique salt
 rails credentials:edit
 ```
 
+Add to your credentials:
 ```yaml
 hashid:
-  salt: your-unique-salt-here  # Generate with: SecureRandom.hex(32)
+  salt: <paste output of: SecureRandom.hex(32)>  # e.g., "a1b2c3d4e5f6..."
+```
+
+The initializer will automatically pick it up:
+```ruby
+config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt)
+```
+
+**Per-model salt override:**
+
+For models that need different salts (e.g., to maintain compatibility with legacy IDs):
+
+```ruby
+class LegacyUser < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :usr, salt: "" # Empty salt for backward compatibility
+end
+
+class SecureDocument < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :doc, salt: Rails.application.credentials.dig(:documents, :salt)
+end
 ```
 
 ## How It Works

data/examples/initializer.rb

@@ -7,11 +7,25 @@
 
 EncodedIds.configure do |config|
   # Hashid configuration (for integer IDs)
-  # IMPORTANT: Set a unique salt in production via credentials
-  # rails credentials:edit
-  # Add: hashid: { salt: "your-unique-salt-here" }
-  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt)
+  #
+  # SECURITY IMPORTANT: Set a unique salt for your application!
+  # Without a salt, hash IDs can be calculated by anyone who knows your database IDs.
+  #
+  # Method 1 (Recommended): Store in encrypted credentials
+  #   rails credentials:edit
+  #   Add: hashid: { salt: "your-unique-salt-here" }
+  #   Generate with: SecureRandom.hex(32)
+  #
+  # Method 2: Use environment variable
+  #   config.hashid_salt = ENV["HASHID_SALT"]
+  #
+  # Method 3: Mix of both (credentials preferred, ENV as fallback)
+  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt) || ENV["HASHID_SALT"]
+
+  # Minimum length of the hash portion (before prefix)
   config.hashid_min_length = 8
+
+  # Character set for hash generation (lowercase + numbers by default)
   config.hashid_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
 
   # Base62 alphabet (for UUID encoding)

data/examples/models.rb

@@ -4,7 +4,7 @@
 
 # Integer primary key with simple prefix
 class User < ApplicationRecord
-  include EncodedIds::HashidEncodedIds
+  include EncodedIds::HashidIdentifiable
   set_public_id_prefix :usr
 end
 # user.public_id => "usr_k5qx9z"
@@ -12,14 +12,14 @@ end
 
 # Integer primary key with longer hash for high-volume tables
 class Event < ApplicationRecord
-  include EncodedIds::HashidEncodedIds
+  include EncodedIds::HashidIdentifiable
   set_public_id_prefix :evt, min_hash_length: 12
 end
 # event.public_id => "evt_x5qp9z2m8n4k"
 
 # Integer primary key with compositional prefix
 class Intel::Tool::PhoneNumber < ApplicationRecord
-  include EncodedIds::HashidEncodedIds
+  include EncodedIds::HashidIdentifiable
   add_public_id_segment :int
   add_public_id_segment :tool
   add_public_id_segment :phn
@@ -28,22 +28,36 @@ end
 
 # UUID primary key
 class Organization < ApplicationRecord
-  include EncodedIds::UuidEncodedIds
+  include EncodedIds::UuidIdentifiable
   set_public_id_prefix "org"
 end
 # org.public_id => "org_4k8xJm2pN9qW"
 
 # UUID primary key with different prefix
 class Team < ApplicationRecord
-  include EncodedIds::UuidEncodedIds
+  include EncodedIds::UuidIdentifiable
   set_public_id_prefix "team"
 end
 # team.public_id => "team_7n2kLp4xMq8R"
 
 # Override per-model to include prefix in routes (Stripe style)
 class ApiKey < ApplicationRecord
-  include EncodedIds::HashidEncodedIds
+  include EncodedIds::HashidIdentifiable
   set_public_id_prefix :key, use_prefix_in_routes: true
 end
 # api_key.public_id => "key_abc123"
 # api_key.to_param => "key_abc123" (includes prefix)
+
+# Security: Custom salt for specific model
+class SecureDocument < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :doc, salt: Rails.application.credentials.dig(:documents, :salt)
+end
+# Uses a different salt than the global default for added security
+
+# Security: Empty salt for backward compatibility with legacy IDs
+class LegacyUser < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :leg, salt: ""
+end
+# Maintains compatibility with existing hash IDs generated without a salt

data/lib/encoded_ids/hashid_identifiable.rb

@@ -54,13 +54,19 @@ module EncodedIds
 
     module ClassMethods
       # Simple approach: set the full prefix directly
-      def set_public_id_prefix(prefix, min_hash_length: 8, use_prefix_in_routes: nil)
+      # Options:
+      #   - min_hash_length: Minimum length of the encoded hash (default: 8)
+      #   - use_prefix_in_routes: Include prefix in to_param URLs (default: nil, inherits from config)
+      #   - salt: Custom salt for this model (default: nil, uses global config)
+      def set_public_id_prefix(prefix, min_hash_length: 8, use_prefix_in_routes: nil, salt: nil)
         self.public_id_prefix = prefix.to_s.downcase
         self.hashid_min_length = min_hash_length
         self.use_prefix_in_routes = use_prefix_in_routes
 
-        # Configure hashid-rails for this model with custom length
-        hashid_config(min_hash_length: min_hash_length)
+        # Configure hashid-rails for this model with custom length and optional salt
+        config_options = { min_hash_length: min_hash_length }
+        config_options[:salt] = salt if salt
+        hashid_config(config_options)
       end
 
       # Compositional approach: add segments that get joined with underscores

data/lib/encoded_ids/railtie.rb

@@ -5,9 +5,41 @@ module EncodedIds
     initializer "encoded_ids.configure_hashid_rails" do
       # Configure hashid-rails with gem settings
       Hashid::Rails.configure do |config|
-        config.salt = EncodedIds.configuration.hashid_salt ||
-                      Rails.application.credentials.dig(:hashid, :salt) ||
-                      Rails.application.secret_key_base
+        # Project-wide salt fallback chain:
+        # 1. Explicitly configured via EncodedIds.configure
+        # 2. Rails credentials hashid.salt
+        # 3. ENV["HASHID_SALT"]
+        # 4. Rails secret_key_base (not recommended for production)
+        salt = EncodedIds.configuration.hashid_salt ||
+               Rails.application.credentials.dig(:hashid, :salt) ||
+               ENV["HASHID_SALT"] ||
+               Rails.application.secret_key_base
+
+        # Warn in development if using secret_key_base as salt
+        if Rails.env.development? &&
+           EncodedIds.configuration.hashid_salt.nil? &&
+           Rails.application.credentials.dig(:hashid, :salt).nil? &&
+           ENV["HASHID_SALT"].nil?
+          Rails.logger.warn <<~WARNING
+            [EncodedIds] No hashid_salt configured. Using secret_key_base as fallback.
+
+            For better security, set a unique salt in config/credentials.yml.enc:
+              hashid:
+                salt: #{SecureRandom.hex(32)}
+
+            Or via environment variable:
+              HASHID_SALT=#{SecureRandom.hex(32)}
+
+            Or in config/initializers/encoded_ids.rb:
+              EncodedIds.configure do |config|
+                config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt) || ENV["HASHID_SALT"]
+              end
+
+            Using the default salt makes hash IDs predictable if someone knows your model IDs.
+          WARNING
+        end
+
+        config.salt = salt
         config.min_hash_length = EncodedIds.configuration.hashid_min_length
         config.alphabet = EncodedIds.configuration.hashid_alphabet
       end

data/lib/encoded_ids/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EncodedIds
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: encoded_ids
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jasper Mayone