sealed_trail 0.1.0

data/lib/sealed_trail/model.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SealedTrail
+  # Adds the +has_sealed_trail+ macro to Active Record models.
+  module Model
+    EVENTS = %i[create update destroy].freeze
+    OPTIONAL_EVENTS = %i[touch].freeze
+    BULK_EVENTS = %w[bulk_update bulk_delete bulk_insert bulk_upsert].freeze
+    ALL_EVENTS = (EVENTS + OPTIONAL_EVENTS).map(&:to_s) + BULK_EVENTS
+
+    # Per-model settings built by has_sealed_trail.
+    Options = Struct.new(:only, :ignore, :redact, :events, :meta, :bulk, keyword_init: true)
+
+    module ClassMethods
+      # Records an audit entry for every create, update and destroy.
+      #
+      #   class Patient < ApplicationRecord
+      #     has_sealed_trail ignore: [:last_seen_at], redact: { ssn: :mask, email: :fingerprint }
+      #   end
+      #
+      # Options:
+      # only::    record changes to these attributes only
+      # ignore::  never record these attributes (an update touching only
+      #           ignored attributes records nothing)
+      # redact::  attribute names/Regexps (Array), or a Hash of name/Regexp =>
+      #           strategy (:redact, :fingerprint, :mask, a callable, or false
+      #           to opt out of a global rule). Checked before the global rules.
+      # on::      events to record: any of :create, :update, :destroy (default:
+      #           all three) and :touch (opt-in)
+      # meta::    Hash of extra metadata stored with each entry; values may be
+      #           static, a Symbol (method called on the record) or a Proc
+      #           (called with the record)
+      # bulk::    record update_all/delete_all/insert_all/upsert_all summaries
+      #           (default: true)
+      # if/unless:: standard Active Record callback conditions (callbacks only)
+      def has_sealed_trail(only: nil, ignore: [], redact: [], on: EVENTS, meta: {}, bulk: true, **callback_options)
+        if respond_to?(:sealed_trail_options) && sealed_trail_options
+          raise ArgumentError, "has_sealed_trail is already declared on #{name}"
+        end
+
+        events = Array(on).map(&:to_sym)
+        unknown = events - EVENTS - OPTIONAL_EVENTS
+        raise ArgumentError, "Unknown has_sealed_trail event(s): #{unknown.join(", ")}" if unknown.any?
+
+        unknown_options = callback_options.keys - %i[if unless]
+        raise ArgumentError, "Unknown has_sealed_trail option(s): #{unknown_options.join(", ")}" if unknown_options.any?
+
+        Redactor.validate_rules!(redact)
+
+        class_attribute :sealed_trail_options, instance_writer: false
+        self.sealed_trail_options = Options.new(
+          only: only && Array(only).map(&:to_s),
+          ignore: Array(ignore).map(&:to_s),
+          redact: redact.is_a?(Hash) ? redact : Array(redact),
+          events: events,
+          meta: meta.to_h,
+          bulk: bulk
+        ).freeze
+
+        has_many :audit_entries,
+          -> { chronological },
+          as: :item,
+          class_name: "SealedTrail::Entry",
+          inverse_of: false
+
+        prepend SealedTrail::Model::InstanceHooks
+        singleton_class.prepend(SealedTrail::Bulk::InsertHooks) unless SealedTrail::Bulk.relation_inserts?
+
+        after_create(**callback_options) { SealedTrail::Recorder.new(self, :create).record } if events.include?(:create)
+        after_update(**callback_options) { SealedTrail::Recorder.new(self, :update).record } if events.include?(:update)
+        after_destroy(**callback_options) { SealedTrail::Recorder.new(self, :destroy).record } if events.include?(:destroy)
+      end
+
+      def sealed_trail?
+        respond_to?(:sealed_trail_options) && sealed_trail_options.present?
+      end
+    end
+
+    # Records the persistence methods that skip callbacks: update_column(s)
+    # and delete, plus touch when opted in with on: [:touch].
+    module InstanceHooks
+      def update_columns(attributes)
+        return super unless sealed_trail_event?(:update)
+
+        before = self.attributes
+        result = super
+        record_sealed_trail_diff(:update, before, "update_columns")
+        result
+      end
+
+      def touch(*names, time: nil)
+        return super unless sealed_trail_event?(:touch)
+
+        before = attributes
+        result = super
+        record_sealed_trail_diff(:touch, before, "touch") if result
+        result
+      end
+
+      def delete
+        return super unless persisted? && sealed_trail_event?(:destroy)
+
+        snapshot = attributes.compact.transform_values { |value| [ value, nil ] }
+        result = super
+        SealedTrail::Recorder.new(self, :destroy, changes: snapshot, via: "delete").record
+        result
+      end
+
+      private
+
+      def sealed_trail_event?(event)
+        SealedTrail.tracking? && sealed_trail_options.events.include?(event)
+      end
+
+      def record_sealed_trail_diff(event, before, via)
+        after = attributes
+        changes = after.each_with_object({}) do |(name, value), result|
+          result[name] = [ before[name], value ] unless before[name] == value
+        end
+        SealedTrail::Recorder.new(self, event, changes: changes, via: via).record
+      end
+    end
+  end
+end

data/lib/sealed_trail/railtie.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SealedTrail
+  class Railtie < Rails::Railtie
+    initializer "sealed_trail.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend SealedTrail::Model::ClassMethods
+        ActiveRecord::Relation.prepend(SealedTrail::Bulk::RelationHooks)
+        ActiveRecord::Relation.prepend(SealedTrail::Bulk::InsertHooks) if SealedTrail::Bulk.relation_inserts?
+      end
+    end
+
+    initializer "sealed_trail.action_controller" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include SealedTrail::Controller if SealedTrail.config.auto_include_controller
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        include SealedTrail::Controller if SealedTrail.config.auto_include_controller
+      end
+    end
+
+    initializer "sealed_trail.active_job" do
+      ActiveSupport.on_load(:active_job) do
+        require "sealed_trail/job_context"
+        include SealedTrail::JobContext
+      end
+    end
+
+    console do
+      SealedTrail.process_actor_label ||= "console"
+    end
+
+    rake_tasks do
+      SealedTrail::RakeContext.install!
+    end
+  end
+end

data/lib/sealed_trail/rake_context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SealedTrail
+  # Labels entries recorded while a rake task runs as "rake:<task name>".
+  module RakeContext
+    module_function
+
+    def install!
+      return unless defined?(::Rake::Task)
+      return if ::Rake::Task.ancestors.include?(TaskHook)
+
+      ::Rake::Task.prepend(TaskHook)
+    end
+
+    module TaskHook
+      def execute(*args)
+        previous = SealedTrail.process_actor_label
+        SealedTrail.process_actor_label = "rake:#{name}"
+        super
+      ensure
+        SealedTrail.process_actor_label = previous
+      end
+    end
+  end
+end

data/lib/sealed_trail/recorder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module SealedTrail
+  # Builds and saves one Entry for one record event.
+  class Recorder
+    # +changes+ overrides the changes read from the record (used for
+    # update_columns, touch and delete); +via+ is stored in the metadata.
+    def initialize(record, event, changes: nil, via: nil)
+      @record = record
+      @event = event.to_sym
+      @options = record.class.sealed_trail_options
+      @changes = changes
+      @via = via
+    end
+
+    # Returns the saved Entry, or nil when nothing was recorded.
+    def record
+      return unless SealedTrail.tracking?
+
+      changes = AttributeFilter.new(@record.class).call(raw_changes)
+      return if %i[update touch].include?(@event) && changes.empty?
+
+      Writer.write(
+        item_type: @record.class.polymorphic_name,
+        item_id: @record.id,
+        event: @event,
+        object_changes: changes,
+        metadata: metadata
+      )
+    end
+
+    private
+
+    def raw_changes
+      return @changes if @changes
+
+      case @event
+      when :create then @record.attributes.compact.transform_values { |value| [ nil, value ] }
+      when :update then @record.saved_changes
+      when :destroy then @record.attributes.compact.transform_values { |value| [ value, nil ] }
+      end
+    end
+
+    def metadata
+      model_meta = @options.meta.to_h do |key, value|
+        [ key.to_s, resolve_meta(value) ]
+      end
+      model_meta["via"] = @via if @via
+      model_meta
+    end
+
+    def resolve_meta(value)
+      case value
+      when Proc then value.arity.zero? ? @record.instance_exec(&value) : value.call(@record)
+      when Symbol then @record.public_send(value)
+      else value
+      end
+    end
+  end
+
+  # Applies a model's only/ignore and redaction rules to a changes hash of
+  # {"attribute" => [before, after]}.
+  class AttributeFilter
+    def initialize(model)
+      @model = model
+      @options = model.sealed_trail_options
+    end
+
+    def call(changes)
+      redactor = self.redactor
+      changes.each_with_object({}) do |(name, values), result|
+        name = name.to_s
+        next unless tracked?(name)
+
+        result[name] = values.map { |value| redactor.apply(name, value) }
+      end
+    end
+
+    def tracked?(name)
+      name = name.to_s
+      return false if @options.only && !@options.only.include?(name)
+      return false if @options.ignore.include?(name)
+
+      !SealedTrail.config.ignore_attributes.map(&:to_s).include?(name)
+    end
+
+    def redactor
+      global = Array(SealedTrail.config.redact_attributes)
+      if SealedTrail.config.redact_encrypted_attributes && @model.respond_to?(:encrypted_attributes)
+        global += Array(@model.encrypted_attributes).map(&:to_s)
+      end
+      Redactor.new(@options.redact, global)
+    end
+  end
+end

data/lib/sealed_trail/redactor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SealedTrail
+  # Decides whether an attribute is redacted, and how.
+  #
+  # Rules are attribute names (exact match), Regexps, or Hashes mapping either
+  # to a strategy. A strategy of +false+ means "do not redact", which lets a
+  # model opt out of a global rule. Earlier rule sets win.
+  class Redactor
+    STRATEGIES = %i[redact fingerprint mask].freeze
+
+    def self.validate_rules!(rules)
+      normalize(rules).each do |_, strategy|
+        next if strategy.nil? || strategy == false || STRATEGIES.include?(strategy) || strategy.respond_to?(:call)
+
+        raise ArgumentError, "Unknown redaction strategy: #{strategy.inspect} (use #{STRATEGIES.map(&:inspect).join(", ")}, false or a callable)"
+      end
+    end
+
+    def self.normalize(rules)
+      case rules
+      when Hash then rules.to_a
+      when nil then []
+      else Array(rules).flat_map { |rule| rule.is_a?(Hash) ? rule.to_a : [ [ rule, nil ] ] }
+      end
+    end
+
+    def initialize(*rule_sets)
+      @rules = rule_sets.flat_map { |rules| self.class.normalize(rules) }
+    end
+
+    # The strategy for +name+, or nil when it is not redacted.
+    def strategy_for(name)
+      name = name.to_s
+      rule = @rules.find { |matcher, _| matches?(matcher, name) }
+      return nil if rule.nil? || rule.last == false
+
+      rule.last || SealedTrail.config.redaction_strategy
+    end
+
+    def redact?(name)
+      !strategy_for(name).nil?
+    end
+
+    # The value to store for +name+.
+    def apply(name, value)
+      strategy = strategy_for(name)
+      strategy ? self.class.transform(strategy, value, name) : value
+    end
+
+    def self.transform(strategy, value, name = nil)
+      return nil if value.nil?
+
+      case strategy
+      when :redact then REDACTED
+      when :fingerprint then SealedTrail.fingerprint(value)
+      when :mask then mask(value)
+      else
+        raise ArgumentError, "Unknown redaction strategy: #{strategy.inspect}" unless strategy.respond_to?(:call)
+
+        strategy.arity == 1 ? strategy.call(value) : strategy.call(value, name.to_s)
+      end
+    end
+
+    EMAIL = /\A([^@\s]+)@([^@\s]+)\z/
+
+    # "jane@example.com" => "j***@example.com"; "+1 555 0100" => "*******0100";
+    # values shorter than 8 characters are fully masked.
+    def self.mask(value)
+      string = stringify(value)
+      if (match = EMAIL.match(string))
+        "#{match[1][0]}***@#{match[2]}"
+      elsif string.length < 8
+        "*" * string.length
+      else
+        ("*" * (string.length - 4)) + string[-4..]
+      end
+    end
+
+    def self.stringify(value)
+      value.is_a?(String) ? value : value.to_json
+    end
+
+    private
+
+    def matches?(matcher, name)
+      matcher.is_a?(Regexp) ? matcher.match?(name) : matcher.to_s == name
+    end
+  end
+end

data/lib/sealed_trail/version.rb

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

data/lib/sealed_trail/writer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SealedTrail
+  # Saves entries, adding the actor and request context, and applies
+  # config.on_failure when a write fails.
+  module Writer
+    FAILURE_EVENT = "write_failed.sealed_trail"
+
+    module_function
+
+    # Returns the saved Entry, or nil when the write failed and the failure was
+    # handled (:log or a callable).
+    def write(item_type:, item_id:, event:, object_changes: nil, metadata: nil)
+      attributes = { item_type: item_type, item_id: item_id.to_s, event: event.to_s }
+
+      begin
+        actor_type, actor_id = actor_columns(SealedTrail.actor)
+        attributes.merge!(
+          object_changes: object_changes.presence&.as_json,
+          metadata: (Current.metadata || {}).merge(metadata || {}).presence&.as_json,
+          actor_type: actor_type,
+          actor_id: actor_id,
+          request_id: Current.request_id,
+          remote_ip: Current.remote_ip
+        )
+
+        if SealedTrail.config.on_failure == :raise
+          SealedTrail::Entry.create!(attributes)
+        else
+          # A savepoint, so a failed INSERT does not abort the caller's
+          # transaction (PostgreSQL); still rolled back with it.
+          SealedTrail::Entry.transaction(requires_new: true) { SealedTrail::Entry.create!(attributes) }
+        end
+      rescue StandardError => error
+        handle_failure(error, attributes)
+      end
+    end
+
+    def handle_failure(error, attributes)
+      payload = { error: error, entry: attributes }
+      ActiveSupport::Notifications.instrument(FAILURE_EVENT, payload)
+
+      mode = SealedTrail.config.on_failure
+      case mode
+      when :raise
+        raise error
+      when :log
+        log(error, attributes)
+        notify_error_handler(error, payload)
+      else
+        raise ConfigurationError, "config.on_failure must be :log, :raise or a callable" unless mode.respond_to?(:call)
+
+        mode.call(error, payload)
+      end
+      nil
+    end
+
+    def log(error, attributes)
+      SealedTrail.config.logger&.error(
+        "[SealedTrail] Failed to write audit entry for #{attributes[:item_type]}##{attributes[:item_id]} " \
+        "(#{attributes[:event]}): #{error.class}: #{error.message}"
+      )
+    end
+
+    def notify_error_handler(error, payload)
+      SealedTrail.config.error_handler&.call(error, payload)
+    rescue StandardError => handler_error
+      SealedTrail.config.logger&.error("[SealedTrail] error_handler raised #{handler_error.class}: #{handler_error.message}")
+    end
+
+    def actor_columns(actor)
+      case actor
+      when nil then [ nil, nil ]
+      when ActiveRecord::Base then [ actor.class.polymorphic_name, actor.id.to_s ]
+      else [ nil, actor.to_s ]
+      end
+    end
+  end
+end

data/lib/sealed_trail.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_record"
+
+require "sealed_trail/version"
+require "sealed_trail/configuration"
+require "sealed_trail/current"
+require "sealed_trail/redactor"
+require "sealed_trail/writer"
+require "sealed_trail/recorder"
+require "sealed_trail/model"
+require "sealed_trail/bulk"
+require "sealed_trail/controller"
+require "sealed_trail/rake_context"
+
+# SealedTrail records an audit trail of changes to Active Record models: what
+# changed, who changed it, when, and from which request.
+module SealedTrail
+  REDACTED = "[REDACTED]"
+
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  autoload :Entry, "sealed_trail/entry"
+
+  class << self
+    # Global configuration. See SealedTrail::Configuration.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the global configuration, typically from
+    # config/initializers/sealed_trail.rb.
+    def configure
+      yield config
+    end
+
+    # Restores the default configuration. Mostly useful in tests.
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # Process-wide fallback actor label, set to "console" in rails console and
+    # "rake:<task>" while a rake task runs.
+    attr_accessor :process_actor_label
+
+    # True unless tracking is switched off globally (config.enabled = false)
+    # or for the current block (SealedTrail.without_tracking).
+    def tracking?
+      config.enabled && !Current.tracking_disabled
+    end
+
+    # Runs the block without recording any audit entries on the current
+    # thread/fiber. Returns the block's value.
+    def without_tracking(&)
+      Current.set(tracking_disabled: true, &)
+    end
+
+    # Runs the block with tracking forced back on, even inside
+    # without_tracking. Returns the block's value.
+    def with_tracking(&)
+      Current.set(tracking_disabled: false, &)
+    end
+
+    # Attributes every entry recorded inside the block to +actor+. The actor
+    # can be an Active Record object (stored polymorphically) or a String or
+    # Symbol label such as "system" or :nightly_import. Returns the block's
+    # value.
+    def with_actor(actor, &)
+      Current.set(actor: actor, &)
+    end
+
+    # Merges +metadata+ into the metadata of every entry recorded inside the
+    # block. Nested calls are merged. Returns the block's value.
+    def with_metadata(metadata, &)
+      merged = (Current.metadata || {}).merge(metadata.to_h.stringify_keys)
+      Current.set(metadata: merged, &)
+    end
+
+    # The actor that will be recorded right now. In order: the explicit actor
+    # (with_actor / Current.actor), the request's actor, the request or job
+    # label ("anonymous", "job:<JobClass>"), the console/rake label, then
+    # config.default_actor.
+    def actor
+      identified = Current.identified_actor
+      return identified unless identified.nil?
+      return Current.context_label if Current.context_label.present?
+      return process_actor_label if config.detect_process_context && process_actor_label.present?
+
+      default = config.default_actor
+      default.respond_to?(:call) ? default.call : default
+    end
+
+    # The HMAC-SHA256 fingerprint stored by the :fingerprint redaction
+    # strategy, e.g. "hmac:3f2a...". Use it to find entries for a value
+    # without storing the value:
+    #
+    #   SealedTrail::Entry.with_fingerprint("jane@example.com")
+    def fingerprint(value)
+      return nil if value.nil?
+
+      digest = OpenSSL::HMAC.hexdigest("SHA256", config.fingerprint_secret, Redactor.stringify(value))
+      "hmac:#{digest}"
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require "sealed_trail/railtie"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: sealed_trail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Steadybyte
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: SealedTrail records create, update and destroy events on Active Record
+  models with before/after values, the acting user, request id and IP address, and
+  redacts sensitive attributes by default. It helps Rails teams produce audit evidence
+  for security reviews.
+email:
+- steadybyte.hq@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/sealed_trail/install/install_generator.rb
+- lib/generators/sealed_trail/install/templates/create_sealed_trail_entries.rb.tt
+- lib/generators/sealed_trail/install/templates/sealed_trail.rb.tt
+- lib/sealed_trail.rb
+- lib/sealed_trail/bulk.rb
+- lib/sealed_trail/configuration.rb
+- lib/sealed_trail/controller.rb
+- lib/sealed_trail/current.rb
+- lib/sealed_trail/entry.rb
+- lib/sealed_trail/job_context.rb
+- lib/sealed_trail/model.rb
+- lib/sealed_trail/railtie.rb
+- lib/sealed_trail/rake_context.rb
+- lib/sealed_trail/recorder.rb
+- lib/sealed_trail/redactor.rb
+- lib/sealed_trail/version.rb
+- lib/sealed_trail/writer.rb
+homepage: https://steadybytehq.github.io/sealedtrail/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://steadybytehq.github.io/sealedtrail/
+  source_code_uri: https://github.com/steadybytehq/sealed_trail
+  changelog_uri: https://github.com/steadybytehq/sealed_trail/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/steadybytehq/sealed_trail/issues
+  documentation_uri: https://github.com/steadybytehq/sealed_trail#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Audit trail of who changed what, when, for Rails models.
+test_files: []