sealed_id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41ea696b7074f6260ba635f6aa55a39afa9b5fc51b3a82a9464f3badd067465d
+  data.tar.gz: fbadd2d3167fef510767a7642d9c075bcae3f93b6301f494b785a3f42221806f
+SHA512:
+  metadata.gz: 18fe921c99644a7d79404db0f9eff6db8cba01e23b6c34152bbe3899fd63412d7054d85d49208944d779e7ae683d4be14cdede7ccd5116192881a7f3cfcc6185
+  data.tar.gz: ab22c99e7cdc8505a8863fad79b4ed669767b4f229849909a9020090cd63aba37fa0817fa97afa5d52ee7a671c37381e4c819580c39a9384b10290c2ad651c6c

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Encrypt integer primary keys into unique, UUID-shaped tokens with AES-256, with no new column or migration.
+- Refuse raw ids in `find` from requests, while integers, ActiveJob and GlobalID keep working.
+- Make `where`, `find_by`, `exists?`, `delete`, `delete_by` and `destroy_by` understand tokens.
+- Add `SealedId.model_for`, `locate` and `find` to resolve any token to its model and record.
+- Add `decode_params` for foreign keys in forms, and a `legacy` option for ids issued by an earlier scheme.
+- Read the secret from `SEALED_ID_SECRET`, and refuse short or repetitive secrets.
+- Finder behavior derives from [acts_as_hashids](https://github.com/dtaniwaki/acts_as_hashids).

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2014 Daisuke Taniwaki
+Copyright (c) 2026 Tamiru Hailu
+
+MIT License
+
+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,188 @@
+# sealed_id
+
+Unguessable, UUID-shaped public ids for ActiveRecord, with no new column or migration.
+
+Your tables keep their integer primary keys. URLs get an encrypted token that can't be guessed, and raw ids from requests are refused.
+
+```ruby
+class Foo < ApplicationRecord
+  sealed_id
+end
+
+foo = Foo.create
+foo.id                 # => 1, still your integer primary key
+foo.to_param           # => "d42fc60c-c23f-84e2-8a9c-7a3cd44e450c"
+
+Foo.find(foo.to_param) # => #<Foo id: 1>
+Foo.find("1")          # => ActiveRecord::RecordNotFound
+Foo.find("garbage")    # => ActiveRecord::RecordNotFound
+Foo.find(1)            # => #<Foo id: 1>
+```
+
+Your routes and `find` calls work unchanged, and invalid ids become a normal 404.
+
+## Requirements
+
+Ruby 2.7 or newer, and Rails or ActiveRecord 6.0 to 8.1. Primary keys must be integers up to 64 bits. Models with UUID or composite primary keys keep their normal behavior, so the macro can sit on `ApplicationRecord` alongside them.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "sealed_id", "~> 0.1"
+```
+
+### Set a secret
+
+Tokens are derived from a secret of at least 32 bytes. **Changing the secret changes every public URL**, so choose one you won't need to rotate.
+
+The simplest way is an environment variable, which the gem reads automatically. Generate a value with `bin/rails secret`, then set it wherever the app runs:
+
+```
+SEALED_ID_SECRET=<your generated value>
+```
+
+Environments with the same value produce the same tokens, so a link or database copy from one works in another. Machines that share the production value can also decode and forge production tokens, so give production its own value unless you need this.
+
+The order of precedence is `secret:` on the model, then `SealedId.secret = ...` in an initializer, then `SEALED_ID_SECRET`. In Rails, `secret_key_base` is the fallback, which differs per environment and would change your links if rotated, so set a dedicated value in production. Outside Rails, there's no fallback.
+
+## Usage
+
+Put the macro on one model, or on `ApplicationRecord` for all of them.
+
+```ruby
+foo.sealed_id                # the token
+Foo.unseal(token)            # the integer id, or nil if the token is invalid
+Foo.with_sealed_ids(a, b)    # a relation; raises SealedId::InvalidToken for an invalid token
+```
+
+`find` also accepts several tokens and respects scopes, so `current_user.foos.find(token)` only finds that user's records.
+
+### Finding the model from a token
+
+Every token records which model it belongs to, readable only with your secret:
+
+```ruby
+SealedId.model_for(token) # => Foo, or nil if the token isn't valid
+SealedId.locate(token)    # => the record, or nil
+SealedId.find(token)      # => the record, or raises ActiveRecord::RecordNotFound
+```
+
+`locate` and `find` search every model, so **always check that the caller may see the record they return**. For a request that should only reach one model, use `Foo.find(token)`, which refuses another model's token. With single-table inheritance, `model_for` returns the base class, and `locate` returns the actual subclass.
+
+### Options
+
+```ruby
+sealed_id secret: ENV.fetch("FOO_SECRET"), # overrides SealedId.secret; may be callable
+          scope: "foos"                    # defaults to the base class name
+```
+
+Tokens are tied to the `scope`, so a token for one model is never valid for another. Before renaming a model, set `scope` to its current class name, or its URLs will change. Each model needs its own scope: `SealedId.model_for` and the other lookups above raise `SealedId::Error` if two share one.
+
+### Decoding form params
+
+Forms send tokens for foreign keys too, so controllers get a private `decode_params` method. Pass the model and your permitted params:
+
+```ruby
+def student_params
+  decode_params(Student, params.require(:student).permit(:name, :program_id, course_ids: []))
+end
+```
+
+It handles `id`, `belongs_to` foreign keys (including custom `foreign_key:` names), `*_ids` and nested `*_attributes`, using your associations to choose the model for each key. Other keys and models without the macro are left alone, and blank values stay blank so forms can clear an association.
+
+An invalid token raises `SealedId::InvalidToken`, which Rails returns as a 404. It never becomes `nil`, which would silently clear the association, and it never stays a string, which ActiveRecord would cast to the wrong integer. Raw ids are refused too, including integers in a JSON body.
+
+Polymorphic keys raise `ArgumentError`, because the model can't be known safely. Check the type against an allow-list and call `Model.unseal` yourself.
+
+### Nested forms
+
+`fields_for` works unchanged. It adds a hidden field holding the nested record's raw id, and `decode_params` keeps that one raw value, because nested attributes only ever match records already inside the parent's association. Other ids in nested attributes must still be tokens.
+
+### Keeping old ids working
+
+If ids from an earlier scheme must survive, such as on printed documents or QR codes, pass a `legacy` decoder. Old ids keep resolving while every new link uses a sealed token. This example needs the `hashids` gem in your Gemfile:
+
+```ruby
+class Student < ApplicationRecord
+  OLD_IDS = Hashids.new("Student", 10) # the settings the old ids were issued with
+
+  sealed_id legacy: lambda { |token|
+    numbers = OLD_IDS.decode(token)
+    numbers.first if numbers.one?
+  }
+end
+```
+
+The decoder takes a string of up to 64 characters and returns an integer id or `nil`. Raising `ArgumentError` also counts as invalid.
+
+**Anything `legacy` accepts is only as hard to guess as the old scheme.** Use it only on models that need it, and remove it when the old ids no longer matter.
+
+### ActiveJob and GlobalID
+
+These keep working automatically. GlobalID stores the raw id, and sealed_id reads it as a raw id only on that internal path.
+
+To look up a raw id string you produced yourself, use `SealedId.with_raw_ids { Foo.find("3") }`. Never do this with ids from a request.
+
+## Security notes
+
+- **Some queries still don't understand tokens.** `find`, `where`, `find_by`, `exists?`, `delete`, `delete_by` and `destroy_by` all handle tokens for the primary key and `belongs_to` foreign keys. `where.not`, conditions on joined tables (`where(foos: { id: token })`) and raw SQL don't: they cast the string to an integer and act on **a different record**, so `"7a3d54ce-..."` becomes 7. The same applies to `legacy` ids in any query other than `find`. Decode first with `Foo.unseal`, which returns `nil` for an invalid token.
+- **This isn't access control.** Anyone holding a valid URL can use it, so always authorize access to the record you load.
+- **Decoding isn't authorization.** `decode_params` confirms a token is valid, not that this user may link to that record. Check that separately.
+- **`find` accepts integers.** A JSON body of `{"id": 3}` makes `params[:id]` an `Integer`, which `find` accepts because application code relies on it. Use `Foo.find(params[:id].to_s)` for ids from JSON. `decode_params` already refuses them.
+- **Raw ids appear elsewhere.** `as_json` and `to_json` include `id`, while `dom_id`, `cache_key`, nested-form hidden fields and global ids all use the raw value. Remove them from anything public if the id itself is sensitive.
+
+## How it works
+
+Each token is one AES-256 block holding the 64-bit id, a 32-bit tag naming the model and 32 zero bits, using a key derived from your secret with HMAC-SHA256, then written in UUID format. The mapping is deterministic, so a record always has the same token, with no storage needed.
+
+**Tokens are unique by construction.** All models using the same secret share one key, AES is one-to-one for a given key, and no two records have the same id and tag, so two records can't get the same token. This is a mathematical guarantee rather than a low probability, so there's no need for a unique index or for retrying on a collision. The exception is a model with its own `secret:`, where a clash with another model is only astronomically unlikely, as with random UUIDs.
+
+With a strong secret, tokens don't show ids, models, their order or how many records exist, knowing other id and token pairs doesn't help an attacker, and a guess is less likely to succeed than guessing a random UUIDv4. A changed token decrypts to random bits, which fail the tag and zero checks.
+
+There are three things to know:
+
+- **Tokens are shaped like UUIDs, but aren't valid under RFC 9562.** Their version and variant bits are random, because the full 128 bits hold the encrypted block. Databases and most parsers accept them, but a validator that checks for a specific UUID version will reject them.
+- **Your secret decides everything.** The gem refuses short or obviously repetitive secrets, but it can't measure randomness, so generate yours with `bin/rails secret`.
+- **This hasn't had an independent review.** AES is standard, but this gem's use of it hasn't been audited.
+
+| | sealed_id | Random UUID column |
+| --- | --- | --- |
+| Migration and backfill | Not needed | Required |
+| Works on existing records | Yes | After backfill |
+| If the secret leaks | All tokens can be decoded and forged | Nothing to leak |
+| Replace one record's token | Not possible | Update the column |
+| Change the secret | Every URL changes | Not applicable |
+| Query by token in SQL | No, decode it first | Yes |
+
+If a leaked secret or being unable to revoke a token isn't acceptable for your data, use a random UUID column instead.
+
+## Development
+
+```
+bundle install
+bundle exec rake
+```
+
+### Publishing
+
+A matching `v*.*.*` tag publishes the gem using trusted publishing (OIDC), so the repository needs no registry secrets. Register a trusted publisher on [RubyGems](https://rubygems.org/gems/sealed_id) with these values:
+
+| Field | Value |
+| --- | --- |
+| Repository | `tamiru/sealed_id` |
+| Workflow | `release.yml` |
+| Environment | `release` |
+
+```bash
+# Bump the version in lib/sealed_id/version.rb and update CHANGELOG.md, then
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+If a publish fails, re-run the failed jobs. A version already on RubyGems is skipped, so a partial release can be finished safely.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/sealed_id/codec.rb

@@ -0,0 +1,69 @@
+require 'openssl'
+
+module SealedId
+  # Encodes an integer id as a UUID-shaped token by encrypting a single AES block, which holds the 64-bit id, a 32-bit
+  # tag naming the model, and 32 zero bits.
+  #
+  # Every model shares one key, so tokens are unique by construction: AES is one-to-one for a given key, and no two
+  # records have the same id and tag. The tag also lets the server tell which model a token belongs to.
+  #
+  # AES is a pseudorandom permutation, so without the key every token looks like 128 random bits, and knowing other id
+  # and token pairs doesn't help. A guess hits an existing record with probability records / 2^128. The tag and zero
+  # bits authenticate the block: a changed token decrypts to random bits, which pass for a given model with probability
+  # 2^-64, and even then only count if that id exists.
+  #
+  # ECB is safe here because only one block is ever encrypted, and a repeatable token for each id is the point.
+  class Codec
+    MIN_SECRET_BYTES = 32
+    MIN_DISTINCT_BYTES = 8
+    MAX_ID = (2**64) - 1
+    # Lowercase only, so each id has exactly one valid token.
+    FORMAT = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/.freeze
+
+    attr_reader :tag
+
+    def initialize(secret, scope)
+      check_secret(secret.to_s)
+      @key = OpenSSL::HMAC.digest('SHA256', secret.to_s, 'sealed_id/v1/aes')
+      @tag = OpenSSL::Digest::SHA256.digest(scope.to_s).unpack1('N')
+    end
+
+    # Returns the token for an id, or nil if the id can't be encoded.
+    def encode(id)
+      return unless id.is_a?(Integer) && id.between?(0, MAX_ID)
+
+      hex = aes(:encrypt, [id, tag, 0].pack('Q>NN')).unpack1('H*')
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+
+    # Returns the id for a token issued to this model with this key, or nil for anything else.
+    def decode(token)
+      return unless token.is_a?(String) && token.valid_encoding? && FORMAT.match?(token)
+
+      id, token_tag, check = aes(:decrypt, [token.delete('-')].pack('H*')).unpack('Q>NN')
+      id if token_tag == tag && check.zero?
+    end
+
+    private
+
+    # A cipher object holds state, so each call builds its own to stay thread safe.
+    def aes(direction, block)
+      cipher = OpenSSL::Cipher.new('aes-256-ecb').public_send(direction)
+      cipher.key = @key
+      cipher.padding = 0
+      cipher.update(block) + cipher.final
+    end
+
+    # Can't measure randomness, but does catch placeholders such as "x" * 32 before tokens are issued with them.
+    def check_secret(secret)
+      if secret.bytesize < MIN_SECRET_BYTES
+        raise ArgumentError, "sealed_id needs a secret of at least #{MIN_SECRET_BYTES} bytes. " \
+                             'Set SealedId.secret, or pass secret: to the model.'
+      end
+      return if secret.bytes.uniq.size >= MIN_DISTINCT_BYTES
+
+      raise ArgumentError, 'sealed_id needs a random secret, but this one repeats too few characters. ' \
+                           'Generate one with `bin/rails secret`.'
+    end
+  end
+end

data/lib/sealed_id/core.rb

@@ -0,0 +1,195 @@
+require_relative 'codec'
+
+module SealedId
+  module Core
+    extend ActiveSupport::Concern
+
+    # Longer than any token, and bounds what reaches a legacy decoder, whose cost may grow with input length.
+    MAX_TOKEN_LENGTH = 64
+
+    # The public token for this record, or nil if it has no integer id yet.
+    def sealed_id
+      key = id
+      self.class.sealed_id_codec.encode(key) if key.is_a?(Integer)
+    end
+
+    def to_param
+      sealed_id || super
+    end
+
+    module FinderMethods
+      def find(*args, &block)
+        return (respond_to?(:detect) ? self : all).detect(&block) if block
+        return super unless respond_to?(:sealed_primary_key?) && sealed_primary_key?
+
+        ids = args.flatten
+        args.size > 1 || args.first.is_a?(Array) ? find_many_sealed(ids) : find_one_sealed(ids.first)
+      end
+
+      private
+
+      def find_one_sealed(id)
+        key = sealed_id_to_primary_key(id)
+        record = where(primary_key => key).take if key
+        record || raise_sealed_not_found([sealed_error_label(id, key)], 0, 1)
+      end
+
+      def find_many_sealed(ids)
+        keys = ids.map { |id| sealed_id_to_primary_key(id) }
+        wanted = keys.uniq
+        scope = where(primary_key => wanted.compact)
+        records = scope.to_a
+
+        if records.size != wanted.size
+          labels = ids.zip(keys).map { |id, key| sealed_error_label(id, key) }.uniq
+          raise_sealed_not_found(labels, records.size, wanted.size)
+        end
+
+        scope.order_values.any? ? records : records.index_by(&:id).values_at(*wanted)
+      end
+
+      # Never echoes a raw primary key, and bounds whatever the caller sent so it can't bloat logs.
+      def sealed_error_label(id, key)
+        (key && sealed_id_codec.encode(key)) || id.to_s.truncate(64)
+      end
+
+      def raise_sealed_not_found(ids, result_size, expected_size)
+        if ids.size == 1
+          error = "Couldn't find #{name} with '#{primary_key}'=#{ids.first.inspect}"
+        else
+          error = "Couldn't find all #{name.pluralize} with '#{primary_key}': "
+          error += "(#{ids.map(&:inspect).join(', ')}) (found #{result_size} results, but was looking for #{expected_size})"
+        end
+
+        raise ActiveRecord::RecordNotFound.new(error, name, primary_key, ids)
+      end
+    end
+
+    # Makes queries understand tokens. ActiveRecord would otherwise cast "7a3d54ce-..." to 7 and act on a different
+    # record, which is how Foo.delete(token) would remove the wrong row.
+    module RelationMethods
+      include FinderMethods
+
+      # Everything built on +where+ passes through here, including delete_by, destroy_by and Foo.delete.
+      def where!(opts, *rest)
+        opts = klass.sealed_conditions(opts) if opts.is_a?(Hash) && klass.respond_to?(:sealed_conditions)
+        super
+      end
+
+      def exists?(conditions = :none)
+        return super unless klass.respond_to?(:sealed_conditions)
+
+        conditions = { primary_key => conditions } if conditions.is_a?(String) && Codec::FORMAT.match?(conditions)
+        super(klass.sealed_conditions(conditions))
+      end
+    end
+
+    module ClassMethods
+      include FinderMethods
+
+      # Matches no record, for a token that isn't valid.
+      NO_RECORD = -1
+
+      # The class-level find_by has its own fast path, which skips +where+.
+      def find_by(arg, *args)
+        super(sealed_conditions(arg), *args)
+      end
+
+      # Replaces tokens in query conditions with the primary keys they stand for. A token is never right for an integer
+      # column, so this can't change what a correct query means.
+      def sealed_conditions(conditions)
+        return conditions unless conditions.is_a?(Hash)
+
+        conditions.to_h { |column, value| [column, sealed_condition_value(column.to_s, value)] }
+      end
+
+      # Building a codec derives keys, so keep the last one. It is keyed by secret because a callable secret may vary,
+      # and the pair is swapped in whole so concurrent readers never see a mismatch.
+      def sealed_id_codec
+        secret = sealed_id_secret
+        cached_secret, cached = @sealed_id_codec_cache
+        return cached if cached && cached_secret == secret
+
+        scope = sealed_id_options[:scope] || base_class.name
+        Codec.new(secret, scope).tap { |codec| @sealed_id_codec_cache = [secret, codec].freeze }
+      end
+
+      # Returns the primary key for a token, or nil if the token isn't valid for this model.
+      def unseal(token)
+        return unless token.is_a?(String) && token.valid_encoding? && token.length <= MAX_TOKEN_LENGTH
+
+        sealed_id_codec.decode(token) || unseal_legacy(token)
+      end
+
+      # A relation of the records with these tokens. Raises SealedId::InvalidToken if any token isn't valid.
+      def with_sealed_ids(*tokens)
+        tokens = tokens.flatten
+        keys = tokens.map { |token| unseal(token) }
+        raise InvalidToken, "Invalid sealed id: #{tokens.inspect.truncate(200)}" if keys.include?(nil)
+
+        where(primary_key => keys)
+      end
+
+      # Resolves a value given to +find+ to a primary key, or nil if it can't refer to a record.
+      #
+      # Numerics are trusted because application code and Rails itself pass them around. Strings may come from a URL,
+      # so they must be valid tokens, unless the caller opted in with SealedId.with_raw_ids.
+      def sealed_id_to_primary_key(value)
+        return value.to_i if value.is_a?(Numeric)
+        return unless value.is_a?(String) && value.valid_encoding?
+        return value.to_i if SealedId.raw_ids? && value.match?(/\A\d{1,20}\z/)
+
+        unseal(value)
+      end
+
+      # Only integer keys can be sealed. Others (UUIDs, composite keys) keep ActiveRecord's behavior, so the macro can
+      # sit on ApplicationRecord alongside such models.
+      def sealed_primary_key?
+        primary_key.is_a?(String) && type_for_attribute(primary_key).type == :integer
+      end
+
+      def has_many(*args, &block) # rubocop:disable Naming/PredicatePrefix
+        options = args.extract_options!
+        options[:extend] = Array(options[:extend]) + [RelationMethods]
+        super(*args, **options, &block)
+      end
+
+      def relation
+        r = super
+        r.extend RelationMethods
+        r
+      end
+
+      private
+
+      def sealed_condition_value(column, value)
+        return value.map { |item| sealed_condition_value(column, item) } if value.is_a?(Array)
+        return value unless value.is_a?(String) && Codec::FORMAT.match?(value)
+        return value unless type_for_attribute(column).type == :integer
+
+        target = column == primary_key ? self : sealed_foreign_key_target(column)
+        (target.respond_to?(:unseal) && target.unseal(value)) || NO_RECORD
+      end
+
+      def sealed_foreign_key_target(column)
+        reflection = reflect_on_all_associations(:belongs_to).find { |r| r.foreign_key.to_s == column }
+        reflection.klass if reflection && !reflection.polymorphic?
+      end
+
+      def unseal_legacy(token)
+        legacy = sealed_id_options[:legacy]
+        return if legacy.nil? || Codec::FORMAT.match?(token)
+
+        key = instance_exec(token, &legacy)
+        key if key.is_a?(Integer)
+      rescue ArgumentError
+        nil
+      end
+
+      def sealed_id_secret
+        secret = sealed_id_options[:secret] || SealedId.secret
+        secret.respond_to?(:call) ? instance_exec(&secret) : secret
+      end
+    end
+  end
+end

data/lib/sealed_id/decode_params.rb

@@ -0,0 +1,93 @@
+module SealedId
+  # Turns tokens in permitted params back into primary keys, using the model's associations to pick each key's model:
+  #
+  #   decode_params(Student, params.expect(student: [:name, :program_id, { course_ids: [] }]))
+  #
+  # Handles +id+, belongs_to foreign keys, +*_ids+ and nested +*_attributes+. Blank values stay as they are, so a form
+  # can still clear an association. An invalid token raises SealedId::InvalidToken rather than becoming nil, which
+  # would silently clear the association, or staying a string, which ActiveRecord would cast to the wrong integer.
+  # Integers are invalid too: this is the request boundary, and a raw id in a JSON body must not get through. The one
+  # exception is the +id+ of a nested record, see raw_id?.
+  module DecodeParams
+    private
+
+    def decode_params(model, params)
+      Decoder.call(model, params)
+    end
+
+    module Decoder
+      module_function
+
+      def call(model, params, nested: false)
+        attributes = ActiveSupport::HashWithIndifferentAccess.new(params)
+        attributes.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(key, value), decoded|
+          decoded[key] = decode_key(model, key.to_s, value, nested)
+        end
+      end
+
+      def decode_key(model, key, value, nested)
+        if key == 'id' then nested && raw_id?(value) ? value : decode_token(model, value)
+        elsif key.end_with?('_ids') then decode_many(model, key, value)
+        elsif key.end_with?('_id') then decode_foreign_key(model, key, value)
+        elsif key.end_with?('_attributes') then decode_nested(model, key, value)
+        else value
+        end
+      end
+
+      def decode_foreign_key(model, key, value)
+        reflection = model.reflect_on_all_associations(:belongs_to).find { |r| r.foreign_key.to_s == key }
+        return value unless reflection
+
+        if reflection.polymorphic?
+          raise ArgumentError, "decode_params can't tell which model #{model.name}##{key} refers to; decode it yourself"
+        end
+
+        decode_token(reflection.klass, value)
+      end
+
+      def decode_many(model, key, value)
+        reflection = model.reflect_on_association(key.delete_suffix('_ids').pluralize)
+        return value unless reflection
+
+        Array(value).map { |token| decode_token(reflection.klass, token) }
+      end
+
+      def decode_nested(model, key, value)
+        reflection = model.reflect_on_association(key.delete_suffix('_attributes'))
+        return value unless reflection
+
+        decode_nested_value(reflection.klass, value)
+      end
+
+      def decode_nested_value(klass, value)
+        case value
+        when Array then value.map { |attributes| call(klass, attributes, nested: true) }
+        when Hash
+          return call(klass, value, nested: true) unless indexed?(value)
+
+          value.transform_values { |attributes| call(klass, attributes, nested: true) }
+        else value
+        end
+      end
+
+      # Rails sends collections from forms as { "0" => {...}, "1" => {...} }.
+      def indexed?(hash)
+        hash.keys.all? { |key| key.to_s.match?(/\A\d+\z/) }
+      end
+
+      # fields_for emits the raw id of nested records. It is safe to keep, because nested attributes only ever match
+      # records already inside the parent's association, so it can't reach anyone else's.
+      def raw_id?(value)
+        value.to_s.match?(/\A\d+\z/)
+      end
+
+      def decode_token(klass, value)
+        return value if value.blank? && !value.is_a?(Numeric)
+        return value unless klass.respond_to?(:unseal)
+
+        klass.unseal(value) || raise(InvalidToken, "Invalid sealed id for #{klass.name}: #{value.inspect.truncate(100)}")
+      end
+    end
+    private_constant :Decoder
+  end
+end

data/lib/sealed_id/global_id_locator.rb

@@ -0,0 +1,13 @@
+module SealedId
+  # GlobalID stores the raw primary key and hands it to +find+ as a string, so ActiveJob arguments and signed ids would
+  # otherwise be refused as invalid tokens. Those strings come from the application, not from a URL.
+  module GlobalIdLocator
+    def locate(*args)
+      SealedId.with_raw_ids { super }
+    end
+
+    def locate_many(*args)
+      SealedId.with_raw_ids { super }
+    end
+  end
+end

data/lib/sealed_id/model.rb

@@ -0,0 +1,24 @@
+require_relative 'core'
+
+module SealedId
+  module Model
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Options:
+      #   secret: overrides SealedId.secret for this model. May be callable.
+      #   scope:  separates this model's tokens from other models'. Defaults to the base class name, so set it
+      #           before renaming a model to keep its URLs working.
+      #   legacy: a callable taking a string and returning an integer id or nil, so ids issued before adopting this
+      #           gem keep working, such as those printed on documents. New tokens are still sealed. Anything it
+      #           accepts is only as hard to guess as the old scheme, so use it only on models that need it.
+      def sealed_id(secret: nil, scope: nil, legacy: nil)
+        include SealedId::Core unless ancestors.include?(SealedId::Core)
+
+        options = { secret: secret, scope: scope, legacy: legacy }.freeze
+        define_singleton_method(:sealed_id_options) { options }
+        private_class_method :sealed_id_options
+      end
+    end
+  end
+end

data/lib/sealed_id/railtie.rb

@@ -0,0 +1,26 @@
+require 'sealed_id/model'
+
+module SealedId
+  class Railtie < Rails::Railtie
+    # Only applies when SEALED_ID_SECRET isn't set. Runs before the app's config/initializers, so an initializer
+    # setting SealedId.secret takes precedence.
+    initializer 'sealed_id.default_secret' do
+      SealedId.secret ||= -> { Rails.application.secret_key_base }
+    end
+
+    initializer 'sealed_id.include_model' do
+      ActiveSupport.on_load(:active_record) { include SealedId::Model }
+    end
+
+    initializer 'sealed_id.include_controller' do
+      ActiveSupport.on_load(:action_controller) do
+        require 'sealed_id/decode_params'
+        include SealedId::DecodeParams
+
+        ActionDispatch::ExceptionWrapper.rescue_responses['SealedId::InvalidToken'] = :not_found
+      end
+    end
+
+    config.after_initialize { SealedId.install_global_id_support }
+  end
+end

data/lib/sealed_id/version.rb

@@ -0,0 +1,3 @@
+module SealedId
+  VERSION = '0.1.0'.freeze
+end

data/lib/sealed_id.rb

@@ -0,0 +1,96 @@
+require 'sealed_id/version'
+
+module SealedId
+  class Error < StandardError; end
+  class InvalidToken < Error; end
+
+  RAW_IDS_KEY = :sealed_id_raw_ids
+  private_constant :RAW_IDS_KEY
+
+  class << self
+    attr_writer :secret
+
+    # The default secret for every model, from SealedId.secret= or else the SEALED_ID_SECRET environment variable.
+    # May be callable. At least 32 bytes.
+    def secret
+      return @secret if @secret
+
+      value = ENV.fetch('SEALED_ID_SECRET', nil)
+      value unless value.to_s.empty?
+    end
+
+    # Inside the block, +find+ reads digit-only strings as primary keys.
+    # Only use it for ids the application produced itself, never for ones taken from a request.
+    def with_raw_ids
+      previous = Thread.current[RAW_IDS_KEY]
+      Thread.current[RAW_IDS_KEY] = true
+      yield
+    ensure
+      Thread.current[RAW_IDS_KEY] = previous
+    end
+
+    def raw_ids?
+      Thread.current[RAW_IDS_KEY] == true
+    end
+
+    def install_global_id_support
+      return unless defined?(GlobalID::Locator)
+
+      require 'sealed_id/global_id_locator'
+      GlobalID::Locator.singleton_class.prepend(GlobalIdLocator)
+    end
+
+    # The model a token was issued for, or nil if it isn't a valid token.
+    def model_for(token)
+      models.find { |model| model.sealed_id_codec.decode(token) }
+    end
+
+    # The record a token stands for, whichever model it belongs to, or nil if there isn't one.
+    # This finds across every model, so always check the caller may see the record it returns.
+    def locate(token)
+      model = model_for(token)
+      model&.find_by(model.primary_key => model.sealed_id_codec.decode(token))
+    end
+
+    # Like +locate+, but raises ActiveRecord::RecordNotFound.
+    def find(token)
+      locate(token) || raise(ActiveRecord::RecordNotFound, 'No record for this sealed id')
+    end
+
+    # Every model using sealed_id. Raises if two share a tag, because their tokens could not be told apart.
+    def models
+      eager_load_application
+      found = ActiveRecord::Base.descendants.select { |model| sealed_root_model?(model) }
+      found.group_by { |model| model.sealed_id_codec.tag }.each_value do |same_tag|
+        next if same_tag.one?
+
+        raise Error,
+              "These models share a sealed_id scope, so their tokens would collide: #{same_tag.map(&:name).join(', ')}"
+      end
+      found
+    end
+
+    private
+
+    # Only named top-level models: subclasses share their base class's tokens through single-table inheritance.
+    def sealed_root_model?(model)
+      model.respond_to?(:sealed_id_codec) && !model.abstract_class? && model.base_class == model &&
+        model.name.to_s.safe_constantize.equal?(model)
+    end
+
+    # Models load on first use in development, so they wouldn't all be known yet.
+    def eager_load_application
+      return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      Rails.application.eager_load! unless Rails.application.config.eager_load
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require 'sealed_id/railtie'
+elsif defined?(ActiveRecord)
+  require 'sealed_id/model'
+  ActiveRecord::Base.include SealedId::Model
+  SealedId.install_global_id_support
+end

metadata

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: sealed_id
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tamiru Hailu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Encrypts integer primary keys into UUID-shaped tokens for URLs, and refuses
+  raw ids from requests.
+email:
+- tamiruhailu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sealed_id.rb
+- lib/sealed_id/codec.rb
+- lib/sealed_id/core.rb
+- lib/sealed_id/decode_params.rb
+- lib/sealed_id/global_id_locator.rb
+- lib/sealed_id/model.rb
+- lib/sealed_id/railtie.rb
+- lib/sealed_id/version.rb
+homepage: https://github.com/tamiru/sealed_id
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tamiru/sealed_id
+  changelog_uri: https://github.com/tamiru/sealed_id/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tamiru/sealed_id/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Unguessable, UUID-shaped public ids for ActiveRecord, with no migration.
+test_files: []