auditron 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44f360e57980c1ff2fd3b0c87daefd2bad45eb643b588cd38dea1e5912f2af80
+  data.tar.gz: 1f14c7d53bd1689b5ee39e5b5bc1fc99d05bf58d2e5f0426287193a95b3edb72
+SHA512:
+  metadata.gz: 278d96b4441fa49d9f4124dff4ac5917c4ab38b09265e53d2346bea57140771dece7d3f70e0049ea6d33f31aa53b7d0e08541f3521e7a233e9f2821a55e5ddf9
+  data.tar.gz: 56c8b00ff1b7d71f7b6a7942039fd19c70c4a7716a9cafdf9f54545bcdaf2898741a2610b088c6f844625e8ba0a6fd4d4123c5830498efeff30372e7ffd3e5a3

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to Auditron 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.0.0] - 2026-04-04
+
+### Added
+
+- **Core audit logging** — tracks `created`, `updated`, and `deleted` on any ActiveRecord model
+- **Diff-only storage** — stores only changed fields with before/after values, not full snapshots
+- **`auditable` DSL** — include `Auditron::Auditable` and call `auditable` on any model
+  - `auditable` — track all fields
+  - `auditable only: [:email, :role]` — track specific fields only
+  - `auditable except: [:last_sign_in_at]` — exclude specific fields
+- **Thread-safe actor tracking** — set `Auditron.current_actor = @current_user` in any controller
+  - Works with JWT, Devise, session-based auth, or any custom auth system
+  - Automatically cleared after every request — no leaking between requests
+- **Custom metadata** — attach any extra context to a log entry via `audit_with`
+  - `account.audit_with(reason: "GDPR request").destroy`
+  - Stored as JSON, returned as Hash
+- **Chainable query DSL** on `Auditron::AuditLog`
+  - `.for(record)` — all logs for a specific record
+  - `.by(actor)` — all changes made by a specific actor
+  - `.action(:updated)` — filter by action
+  - `.since(1.week.ago)` — filter by time
+  - Fully chainable: `.by(admin).action(:deleted).since(1.week.ago)`
+- **`log.actor`** — polymorphic association returns the full actor object directly
+- **`log.summary`** — human readable description e.g. `"Account #8 was updated by Account #1"`
+- **`log.changed_fields`** — parses JSON automatically, returns Hash
+- **`log.metadata`** — parses JSON automatically, returns Hash or nil
+- **Built-in log retention** via `config.retention_days`
+  - `Auditron::Sweeper.purge!` — deletes all logs older than configured retention days
+  - Safe to call from Sidekiq, GoodJob, cron, or any background job
+- **Request IP tracking** — opt-in via `config.store_ip = true`
+  - Handled automatically by Rack middleware — no extra setup needed
+- **Global ignored fields** — `config.ignored_fields` excludes fields across all models
+- **Install generator** — `rails generate auditron:install`
+  - Interactive CLI with step-by-step guidance
+  - Generates `audit_logs` migration with indexes
+  - Shows next steps after install
+- **Migration** — creates `audit_logs` table with indexes on
+  `auditable`, `actor`, `action`, and `created_at`
+- **Railtie** — auto-integrates into Rails apps, no manual setup needed
+- **Database agnostic** — works with PostgreSQL, MySQL, and SQLite
+- **Zero hard dependencies** beyond `activerecord`
+- **Rails optional** — works in plain Ruby + ActiveRecord projects
+
+### Notes
+
+- `actor_type` and `actor_id` will be `nil` on unauthenticated requests
+  (e.g. signup) — this is correct behavior, not a bug
+- Do not set `current_actor` in the initializer — set it in the controller
+  after authentication so the actor is always the authenticated user
+
+---
+
+## Compatibility
+
+- Ruby `>= 3.0`
+- ActiveRecord `>= 7.0`
+- Rails `>= 7.0` (optional)
+- PostgreSQL, MySQL, SQLite

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"auditron" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["shailendrapatidar00@gmail.com"](mailto:"shailendrapatidar00@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Shailendra Patidar
+
+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,395 @@
+# Auditron
+
+> Audit logging for API-first Rails apps — built-in retention, flexible actor tracking, and a clean query DSL.
+
+---
+
+## Why Auditron?
+
+Most audit gems were built for traditional Rails apps with session-based auth.
+If you are building an API with JWT, service objects, or background jobs — they
+get in your way fast.
+
+`paper_trail` stores full object snapshots on every change. Change one column
+on a model with 30 attributes and it writes all 30 to the database, every time.
+At scale, this becomes a serious storage problem.
+
+`audited` and `paper_trail` both assume controller-based actor tracking tied to
+`current_user` — which does not exist in JWT or service-layer contexts.
+
+Neither gem ships with log retention. You always end up writing your own cleanup job.
+
+**Auditron was designed for how modern Rails APIs are actually built:**
+
+- JWT and service-layer friendly — set the actor anywhere, not just in controllers
+- Diff-only storage — stores only what changed, not the full object
+- Built-in retention — configure once, run a job, logs clean themselves up
+- Chainable query DSL — find exactly what you need without writing raw SQL
+
+---
+
+## Who needs this?
+
+- API-first Rails apps using JWT or token-based auth
+- Apps under **GDPR, HIPAA, or SOC2** compliance requirements that need audit trails
+- Teams tired of paper_trail bloating their database
+- Apps that need to answer **"who changed this, when, and why?"**
+
+---
+
+## At a glance
+
+```ruby
+class Account < ApplicationRecord
+  include Auditron::Auditable
+  auditable only: [:email, :role, :status]
+end
+
+# someone updates their profile...
+account.update!(first_name: "Jane")
+
+# now you know exactly what happened
+account.audit_logs.last
+# => #<AuditLog
+#      action:         "updated"
+#      changed_fields: { "first_name" => ["John", "Jane"] }
+#      actor_type:     "Account"
+#      actor_id:       1
+#      ip_address:     "192.168.1.1"
+#      created_at:     "2026-04-04T08:00:00Z"
+#    >
+```
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "auditron"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Generate and run the migration:
+
+```bash
+rails generate auditron:install
+rails db:migrate
+```
+
+---
+
+## Configuration
+
+Create an initializer at `config/initializers/auditron.rb`:
+
+```ruby
+Auditron.configure do |config|
+  # Fields to never log across all models
+  config.ignored_fields = %i[updated_at created_at]
+
+  # Include request IP in every log entry (default: false)
+  config.store_ip = true
+
+  # Auto-purge logs older than N days (default: nil — keep forever)
+  # Call Auditron::Sweeper.purge! from a scheduled job
+  config.retention_days = 90
+end
+```
+
+> **Note:** Do not set `current_actor` in the initializer.
+> Instance variables like `@current_user` are not available there —
+> they only exist during a request. See Controller Setup below.
+
+---
+
+## Controller Setup
+
+Auditron needs to know who is making changes. Set the current actor
+in your controller after authentication — works with **any auth system**.
+
+Auditron stores it in a **thread-safe variable** and clears it
+automatically after every request. Safe for Puma and any threaded server.
+
+### JWT (API apps)
+
+```ruby
+class ApplicationController < ActionController::API
+  private
+
+  def authenticate_account!
+    token   = request.headers["Authorization"]&.split(" ")&.last
+    payload = JsonAuthToken.decode(token)
+    @current_user = Account.find_by(id: payload[:account_id])
+
+    render json: { error: "Invalid token" }, status: :unauthorized and return unless @current_user
+
+    # Set the actor — Auditron reads this on every model change
+    Auditron.current_actor = @current_user
+  end
+end
+```
+
+### Devise
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_audit_actor
+
+  private
+
+  def set_audit_actor
+    Auditron.current_actor = current_user
+  end
+end
+```
+
+### Session based (no Devise)
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_audit_actor
+
+  private
+
+  def current_user
+    @current_user ||= User.find_by(id: session[:user_id])
+  end
+
+  def set_audit_actor
+    Auditron.current_actor = current_user
+  end
+end
+```
+
+### Service objects or background jobs
+
+```ruby
+# Set and clear manually — Auditron does not clear this automatically
+# outside of a request cycle
+Auditron.current_actor = admin_user
+account.update!(status: "suspended")
+Auditron.current_actor = nil
+```
+
+> **Important:** On signup or any unauthenticated request, `actor_type`
+> and `actor_id` will be `nil` — this is correct behavior.
+> The user does not exist yet so there is no actor to record.
+
+---
+
+## Usage
+
+### Track all changes on a model
+
+```ruby
+class Account < ApplicationRecord
+  include Auditron::Auditable
+  auditable
+end
+```
+
+### Track only specific fields
+
+```ruby
+class Account < ApplicationRecord
+  include Auditron::Auditable
+  auditable only: [:email, :role, :status]
+end
+```
+
+### Exclude specific fields
+
+```ruby
+class Account < ApplicationRecord
+  include Auditron::Auditable
+  auditable except: [:last_sign_in_at, :login_count]
+end
+```
+
+### Attach custom metadata to a log entry
+
+Pass any extra context you want stored alongside the log:
+
+```ruby
+# Simple reason
+account.audit_with(reason: "user requested name change").update!(first_name: "Jane")
+
+# Support ticket reference
+account.audit_with(
+  reason: "admin override",
+  ticket: "SUPPORT-1234",
+  note:   "user forgot old email"
+).update!(email: "new@example.com")
+
+# GDPR deletion
+account.audit_with(reason: "GDPR deletion request").destroy
+```
+
+Metadata is stored as JSON and returned as a Hash:
+
+```ruby
+account.audit_logs.last.metadata
+# => { "reason" => "admin override", "ticket" => "SUPPORT-1234" }
+```
+
+---
+
+## Querying audit logs
+
+```ruby
+# All logs for a specific record
+account.audit_logs
+
+# Same, via class method
+Auditron::AuditLog.for(account)
+
+# All changes made by a specific actor
+Auditron::AuditLog.by(admin)
+
+# Filter by action
+Auditron::AuditLog.action(:updated)
+Auditron::AuditLog.action(:deleted)
+Auditron::AuditLog.action(:created)
+
+# Filter by time
+Auditron::AuditLog.since(1.week.ago)
+Auditron::AuditLog.since(1.month.ago)
+
+# Chain them
+Auditron::AuditLog.by(admin).action(:deleted).since(1.week.ago)
+
+# Get actor object directly from log
+log = account.audit_logs.last
+log.actor        # => full Account/User/Admin object
+log.actor_type   # => "Account"
+log.actor_id     # => 1
+
+# Human readable summary
+log.summary
+# => "Account #8 was updated by Account #1"
+```
+
+---
+
+## Log retention (Sweeper)
+
+No other major audit gem ships with built-in log retention.
+Configure once and run from any scheduled job:
+
+```ruby
+# config/initializers/auditron.rb
+config.retention_days = 90  # keep logs for 90 days
+
+# Call from a scheduled job (Sidekiq, GoodJob, cron)
+Auditron::Sweeper.purge!  # deletes all logs older than retention_days
+```
+
+Example with a background job:
+
+```ruby
+class AuditLogCleanupJob < ApplicationJob
+  def perform
+    Auditron::Sweeper.purge!
+  end
+end
+```
+
+---
+
+## Log entry structure
+
+Every `AuditLog` record contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `auditable_type` | String | Model class name e.g. `"Account"` |
+| `auditable_id` | Integer | Record ID |
+| `action` | String | `created`, `updated`, or `deleted` |
+| `changed_fields` | JSON | Only changed fields with before/after values |
+| `actor_id` | Integer | ID of the actor who made the change |
+| `actor_type` | String | Class name of the actor e.g. `"Account"` |
+| `ip_address` | String | Request IP (when `store_ip: true`) |
+| `metadata` | JSON | Custom data attached via `audit_with` |
+| `created_at` | DateTime | When the change happened |
+
+### Example log entry
+
+```ruby
+#<Auditron::AuditLog
+  id:             7,
+  auditable_type: "Account",
+  auditable_id:   8,
+  action:         "updated",
+  changed_fields: { "first_name" => ["John", "Jane"] },
+  actor_type:     "Account",
+  actor_id:       1,
+  ip_address:     "::1",
+  metadata:       { "reason" => "user requested name change" },
+  created_at:     Sat, 04 Apr 2026 13:38:08 UTC
+>
+```
+
+---
+
+## How it compares
+
+This is an honest comparison. Every gem has strengths — pick the right tool for your use case.
+
+| Feature | Auditron | PaperTrail | Audited | Logidze |
+|---------|----------|------------|---------|---------|
+| Storage model | Diff only | Full snapshot | Diff (changes) | Diff (JSONB) |
+| PostgreSQL | ✅ | ✅ | ✅ | ✅ |
+| MySQL | ✅ | ✅ | ✅ | ❌ |
+| SQLite | ✅ | ✅ | ✅ | ❌ |
+| Built-in retention | ✅ | ❌ | ❌ | ❌ |
+| Custom metadata | ✅ clean DSL | ⚠️ via `meta` config | ⚠️ limited | ❌ |
+| Actor tracking | Thread-local, set anywhere | `whodunnit` (controller) | `current_user` (controller) | Custom |
+| JWT / API friendly | ✅ | ⚠️ needs workaround | ⚠️ needs workaround | ⚠️ moderate |
+| Background job support | ✅ set manually | ⚠️ manual wiring | ⚠️ manual wiring | ⚠️ manual |
+| Chainable query DSL | ✅ | ❌ raw AR queries | ❌ raw AR queries | ❌ raw JSON ops |
+| Rails required | ⚠️ ActiveRecord required | ✅ Rails required | ✅ Rails required | ✅ Rails required |
+| Performance (large data) | ⚠️ unverified | ❌ heavy (full snapshots) | ⚠️ medium | ✅ optimized (JSONB) |
+| Maturity | 🆕 new | ✅ battle-tested | ✅ battle-tested | ✅ stable |
+
+**When to choose Auditron:**
+- You are building an API-first app with JWT or token-based auth
+- You need built-in log retention without writing your own cleanup
+- You want a clean query DSL instead of raw ActiveRecord queries
+- You set the actor from service objects or background jobs
+
+**When to choose PaperTrail:**
+- You need full version history and the ability to revert records
+- You are on a traditional session-based Rails app
+- You need a battle-tested, widely supported gem
+
+**When to choose Logidze:**
+- You are on PostgreSQL and need maximum query performance
+- You want diff storage backed by native JSONB operations
+
+---
+
+## Compatibility
+
+- Ruby `>= 3.0`
+- ActiveRecord `>= 7.0`
+- Rails `>= 7.0` (optional — works with ActiveRecord outside Rails)
+- PostgreSQL, MySQL, SQLite
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+---
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/auditron/audit_log.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Auditron
+  class AuditLog < ActiveRecord::Base
+    self.table_name = "audit_logs"
+
+    # Polymorphic — belongs to any audited model
+    belongs_to :auditable, polymorphic: true, optional: true
+
+    # Polymorphic — belongs to any actor (User, AdminUser, etc.)
+    belongs_to :actor, polymorphic: true, optional: true
+
+    validates :action, presence: true
+    validates :action, inclusion: { in: %w[created updated deleted] }
+
+    # -----------------------------------------------------------------------
+    # Scopes
+    # -----------------------------------------------------------------------
+
+    # Filter by audited record
+    # @example AuditLog.for(user)
+    scope :for, ->(record) {
+      where(auditable_type: record.class.name, auditable_id: record.id)
+    }
+
+    # Filter by actor
+    # @example AuditLog.by(admin)
+    scope :by, ->(actor) {
+      where(actor_type: actor.class.name, actor_id: actor.id)
+    }
+
+    # Filter by action
+    # @example AuditLog.action(:updated)
+    scope :action, ->(action) { where(action: action.to_s) }
+
+    # Filter by time
+    # @example AuditLog.since(1.week.ago)
+    scope :since, ->(time) { where("created_at >= ?", time) }
+
+    # -----------------------------------------------------------------------
+    # Helpers
+    # -----------------------------------------------------------------------
+
+    def changed_fields
+      value = self[:changed_fields]
+      return value if value.is_a?(Hash)
+      JSON.parse(value.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def metadata
+      value = self[:metadata]
+      return nil if value.nil?
+      return value if value.is_a?(Hash)
+      JSON.parse(value.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Returns a human readable summary of the log entry
+    # @example log.summary
+    # => "Account #1 was updated by Account #2"
+    def summary
+      actor_info    = actor   ? "#{actor_type} ##{actor_id}"     : "anonymous"
+      subject_info  = auditable ? "#{auditable_type} ##{auditable_id}" : "#{auditable_type} ##{auditable_id}"
+      "#{subject_info} was #{action} by #{actor_info}"
+    end
+  end
+end

data/lib/auditron/auditable.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Auditron
+  module Auditable
+    extend ActiveSupport::Concern
+
+    included do
+      # Stores options passed to auditable — :only, :except
+      class_attribute :_auditron_options, default: {}
+
+      has_many :audit_logs,
+               class_name:  "Auditron::AuditLog",
+               as:          :auditable,
+               dependent:   :destroy
+    end
+
+    class_methods do
+      # @param only   [Array<Symbol>] track only these fields
+      # @param except [Array<Symbol>] track all fields except these
+      def auditable(only: nil, except: nil)
+        self._auditron_options = { only: only, except: except }
+
+        after_create  :auditron_log_create
+        after_update  :auditron_log_update
+        after_destroy :auditron_log_destroy
+      end
+    end
+
+    # Dev calls this manually to attach metadata to the next audit log
+    # @example account.audit_with(reason: "admin override")
+    def audit_with(metadata = {})
+      @_auditron_metadata = metadata
+      self
+    end
+
+    private
+
+    def auditron_log_create
+      write_audit_log("created", {})
+    end
+
+    def auditron_log_update
+      diff = filtered_changes
+      return if diff.empty?
+      write_audit_log("updated", diff)
+    end
+
+    def auditron_log_destroy
+      write_audit_log("deleted", {})
+    end
+
+    def write_audit_log(action, changed_fields)
+      actor = resolve_actor
+      metadata = @_auditron_metadata.presence
+
+      Auditron::AuditLog.create!(
+        auditable:      self,
+        action:         action,
+        changed_fields: changed_fields.to_json,
+        actor_id:       actor&.respond_to?(:id) ? actor.id : nil,
+        actor_type:     actor&.class&.name,
+        ip_address:     resolve_ip,
+        metadata: metadata&.to_json
+      )
+    ensure
+      # Always clear after write — prevents metadata leaking to next operation
+      @_auditron_metadata = nil
+    end
+
+    # Build a diff hash of only the fields that changed
+    # Format: { field: [old_value, new_value] }
+    def filtered_changes
+      opts            = self.class._auditron_options
+      global_ignored  = Auditron.config.ignored_fields.map(&:to_s)
+      raw_changes     = saved_changes.except(*global_ignored)
+
+      # Apply :only filter
+      if opts[:only].present?
+        allowed = opts[:only].map(&:to_s)
+        raw_changes = raw_changes.slice(*allowed)
+      end
+
+      # Apply :except filter
+      if opts[:except].present?
+        excluded = opts[:except].map(&:to_s)
+        raw_changes = raw_changes.except(*excluded)
+      end
+
+      raw_changes
+    end
+
+    def resolve_actor
+      # Priority 1: thread-local set directly in controller
+      return Auditron.current_actor if Auditron.current_actor
+
+      # Priority 2: lambda fallback from config
+      Auditron.config.current_actor&.call
+    rescue StandardError
+      nil
+    end
+
+    def resolve_ip
+      return nil unless Auditron.config.store_ip
+      Auditron.current_request&.remote_ip
+    end
+  end
+end

data/lib/auditron/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Auditron
+  class Configuration
+    # Lambda that returns the current actor
+    # @example config.current_actor = -> { Current.user }
+    attr_accessor :current_actor
+
+    # Fields to never log across all models
+    # @example config.ignored_fields = [:updated_at, :created_at]
+    attr_accessor :ignored_fields
+
+    # When true, stores request IP in every log entry
+    attr_accessor :store_ip
+
+    # Auto-purge logs older than N days. nil = keep forever
+    attr_accessor :retention_days
+
+    def initialize
+      @current_actor  = -> { nil }
+      @ignored_fields = %i[updated_at created_at]
+      @store_ip       = false
+      @retention_days = nil
+    end
+  end
+end

data/lib/auditron/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Auditron
+  class Railtie < Rails::Railtie
+    # Store current request so auditable concern can read IP
+    initializer "auditron.request_store" do |app|
+      app.middleware.use(Auditron::RequestMiddleware)
+    end
+  end
+
+  # Minimal Rack middleware — stores the current request thread-locally
+  class RequestMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Auditron.current_request = ActionDispatch::Request.new(env)
+      @app.call(env)
+    ensure
+      # Clear both after every request — prevents leaking between requests
+      Auditron.current_actor   = nil
+      Auditron.current_request = nil
+    end
+  end
+end

data/lib/auditron/sweeper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Auditron
+  module Sweeper
+    # Delete all logs older than config.retention_days
+    # Call this from a scheduled job e.g. daily Sidekiq/GoodJob cron
+    #
+    # @example
+    #   Auditron::Sweeper.purge!
+    def self.purge!
+      days = Auditron.config.retention_days
+      return unless days.is_a?(Integer) && days.positive?
+
+      cutoff = Time.current - days.days
+      deleted = Auditron::AuditLog.where("created_at < ?", cutoff).delete_all
+      deleted
+    end
+  end
+end

data/lib/auditron/version.rb

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

data/lib/auditron.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/core_ext/module/attribute_accessors_per_thread"
+require "auditron/version"
+require "auditron/configuration"
+require "auditron/audit_log"
+require "auditron/auditable"
+require "auditron/sweeper"
+
+module Auditron
+  # Explicitly require active_support thread accessor
+  thread_mattr_accessor :current_actor
+  thread_mattr_accessor :current_request
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end
+
+require "auditron/railtie" if defined?(Rails::Railtie)

data/lib/generators/auditron/install/install_generator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Auditron
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def install
+        display_banner
+        display_intro
+        return cancel_install unless confirm_install?
+
+        say ""
+        say "  Creating migration...", :cyan
+        migration_template(
+          "create_audit_logs.rb.erb",
+          "db/migrate/create_audit_logs.rb"
+        )
+        say ""
+
+        display_initializer_hint
+        display_success
+      end
+
+      private
+
+      def display_banner
+        say ""
+        say "  +===================================================+", :cyan
+        say "  |                                                   |", :cyan
+        say "  |       AUDITRON  --  Audit Logging Gem             |", :cyan
+        say "  |                    v#{Auditron::VERSION.ljust(6)}                        |", :cyan
+        say "  |                                                   |", :cyan
+        say "  +===================================================+", :cyan
+        say ""
+      end
+
+      def display_intro
+        say "  Auditron will set up audit logging for your Rails app.", :white
+        say ""
+        say "  This installer will:", :white
+        say ""
+        say "    [+]  Create the audit_logs migration", :green
+        say "    [+]  Add indexes for fast querying", :green
+        say "    [+]  Track: auditable, actor, action, changed fields, IP", :green
+        say ""
+        say "  ---------------------------------------------------", :cyan
+        say ""
+        say "  After install, add to any model:", :yellow
+        say ""
+        say "    class User < ApplicationRecord", :white
+        say "      auditable only: [:email, :role, :status]", :green
+        say "    end", :white
+        say ""
+        say "  ---------------------------------------------------", :cyan
+        say ""
+      end
+
+      def confirm_install?
+        answer = ask(
+          "  Ready to install? This will create the audit_logs migration. [Y/n]:",
+          :yellow
+        ).strip.downcase
+
+        answer == "y" || answer == "yes" || answer == ""
+      end
+
+      def display_initializer_hint
+        say "  ---------------------------------------------------", :cyan
+        say ""
+        say "  Next steps:", :white
+        say ""
+        say "    1.  Run the migration:", :yellow
+        say "          rails db:migrate", :green
+        say ""
+        say "    2.  Create config/initializers/auditron.rb:", :yellow
+        say "          Auditron.configure do |config|", :green
+        say "            config.ignored_fields = %i[updated_at created_at]", :green
+        say "            config.store_ip       = false", :green
+        say "            config.retention_days = nil", :green
+        say "          end", :green
+        say ""
+        say "    3.  Set current actor in ApplicationController:", :yellow
+        say "          before_action :set_audit_actor", :green
+        say "          def set_audit_actor", :green
+        say "            Auditron.current_actor = @current_user", :green
+        say "          end", :green
+        say ""
+        say "    4.  Add auditable to your models:", :yellow
+        say "          auditable only: [:email, :role]", :green
+        say ""
+        say "    5.  Query your logs:", :yellow
+        say "          user.audit_logs", :green
+        say "          AuditLog.by(admin).action(:deleted).since(1.week.ago)", :green
+        say ""
+        say "  ---------------------------------------------------", :cyan
+        say ""
+      end
+
+      def display_success
+        say "  [OK]  Auditron installed successfully!", :green
+        say "  [OK]  Run 'rails db:migrate' to complete setup.", :green
+        say ""
+        say "  Happy auditing!", :cyan
+        say ""
+      end
+
+      def cancel_install
+        say ""
+        say "  [CANCELLED]  Installation cancelled.", :red
+        say "  Run 'rails generate auditron:install' again when ready.", :yellow
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/auditron/install/templates/create_audit_logs.rb.erb

@@ -0,0 +1,21 @@
+class CreateAuditLogs < ActiveRecord::Migration[7.0]
+  def change
+    create_table :audit_logs do |t|
+      t.string  :auditable_type, null: false
+      t.bigint  :auditable_id,   null: false
+      t.string  :action,         null: false
+      t.text    :changed_fields
+      t.string  :actor_type
+      t.bigint  :actor_id
+      t.string  :ip_address
+      t.text    :metadata
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :audit_logs, [:auditable_type, :auditable_id]
+    add_index :audit_logs, [:actor_type, :actor_id]
+    add_index :audit_logs, :action
+    add_index :audit_logs, :created_at
+  end
+end

data/sig/auditron.rbs

@@ -0,0 +1,44 @@
+module Auditron
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.config: () -> Configuration
+
+  self.current_request: untyped
+
+  class Configuration
+    attr_accessor current_actor: Proc
+    attr_accessor ignored_fields: Array[Symbol]
+    attr_accessor store_ip: bool
+    attr_accessor retention_days: Integer?
+
+    def initialize: () -> void
+  end
+
+  module Auditable
+    module ClassMethods
+      def auditable: (?only: Array[Symbol]?, ?except: Array[Symbol]?) -> void
+    end
+  end
+
+  class AuditLog < ActiveRecord::Base
+    def self.for: (untyped record) -> ActiveRecord::Relation
+    def self.by: (untyped actor) -> ActiveRecord::Relation
+    def self.action: (Symbol | String action) -> ActiveRecord::Relation
+    def self.since: (Time time) -> ActiveRecord::Relation
+    def changed_fields: () -> Hash[String, untyped]
+  end
+
+  module Sweeper
+    def self.purge!: () -> Integer
+  end
+
+  class Railtie < Rails::Railtie
+  end
+
+  class RequestMiddleware
+    def initialize: (untyped app) -> void
+    def call: (untyped env) -> untyped
+  end
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: auditron
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Shailendra Kumar
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !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.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |
+  Auditron tracks who changed what on any ActiveRecord model — storing only
+  the fields that changed, not full snapshots. Ships with a chainable query
+  DSL, built-in log retention, a simple actor lambda, and works with
+  PostgreSQL, MySQL, and SQLite. Zero hard dependencies beyond ActiveRecord.
+email:
+- shailendrapatidar00@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/auditron.rb
+- lib/auditron/audit_log.rb
+- lib/auditron/auditable.rb
+- lib/auditron/configuration.rb
+- lib/auditron/railtie.rb
+- lib/auditron/sweeper.rb
+- lib/auditron/version.rb
+- lib/generators/auditron/install/install_generator.rb
+- lib/generators/auditron/install/templates/create_audit_logs.rb.erb
+- sig/auditron.rbs
+homepage: https://github.com/spatelpatidar/auditron
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/spatelpatidar/auditron
+  source_code_uri: https://github.com/spatelpatidar/auditron
+  changelog_uri: https://github.com/spatelpatidar/auditron/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/spatelpatidar/auditron/auditron/issues
+  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.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Lightweight, diff-only audit logging for ActiveRecord models.
+test_files: []