active_record-undo 0.1.5 → 0.3.0

data/README.md

@@ -3,48 +3,114 @@
 [![Gem Version](https://img.shields.io/gem/v/active_record-undo.svg?color=blue)](https://rubygems.org/gems/active_record-undo)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**ActiveRecord::Undo** brings transactional, cascade-aware soft deletes and automatic restores to Rails applications.
+**ActiveRecord::Undo** brings transactional, cascade-aware soft deletes, instant single-line restores, and a mountable HTTP route engine to Ruby on Rails applications.
 
-Unlike conventional soft-deletion gems, `active_record-undo` automatically captures an audit snapshot of all records affected across associations (e.g., dependent `has_many` or `has_one` relations) and tracks them in a dedicated polymorphic undo log. Restoring a deleted record cleanly restores its entire deleted child tree in a single atomic database transaction.
+Unlike traditional soft-deletion gems that merely flip a timestamp on a single record, `active_record-undo` creates a polymorphic audit log capturing every affected child record across `dependent: :destroy` and `dependent: :delete_all` associations. Restoring a deleted record cleanly recovers the entire deleted subtree in a single atomic database transaction—with out-of-the-box support for multi-tenancy, user attribution, background purging, and zero-boilerplate HTTP endpoints.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation \& Migrations](#installation--migrations)
+    - [Database Migrations](#database-migrations)
+  - [Model Setup](#model-setup)
+    - [1. Add Timestamp Column to Tables](#1-add-timestamp-column-to-tables)
+    - [2. Declare `acts_as_undoable`](#2-declare-acts_as_undoable)
+  - [Basic Usage](#basic-usage)
+    - [Cascading Soft Deletes](#cascading-soft-deletes)
+    - [Restoring Records](#restoring-records)
+      - [Option A: Restore from the model (Recommended)](#option-a-restore-from-the-model-recommended)
+      - [Option B: Restore from the `UndoLog`](#option-b-restore-from-the-undolog)
+    - [Status \& Eligibility Helpers](#status--eligibility-helpers)
+    - [Query Scopes](#query-scopes)
+    - [Inspecting Deletion Logs](#inspecting-deletion-logs)
+  - [Mountable Route \& Controller Engine](#mountable-route--controller-engine)
+    - [Mounting the Engine](#mounting-the-engine)
+    - [Available Endpoints](#available-endpoints)
+    - [View Helpers (`undo_button_to` \& `undo_link_to`)](#view-helpers-undo_button_to--undo_link_to)
+    - [Cryptographic Signed Restore Tokens](#cryptographic-signed-restore-tokens)
+      - [Generating \& Using Signed Tokens](#generating--using-signed-tokens)
+      - [Key Security Properties](#key-security-properties)
+    - [Multi-Format Responses](#multi-format-responses)
+    - [Security \& Open-Redirect Protection](#security--open-redirect-protection)
+  - [Multi-Tenant Isolation \& User Attribution](#multi-tenant-isolation--user-attribution)
+    - [User Attribution (`whodunnit`)](#user-attribution-whodunnit)
+    - [Multi-Tenant Scoping](#multi-tenant-scoping)
+    - [Tenant Matching Security](#tenant-matching-security)
+    - [Configured Context Enforcement](#configured-context-enforcement)
+  - [Retention, Expiration \& Purging](#retention-expiration--purging)
+    - [Expiration Checks](#expiration-checks)
+    - [Purger Service](#purger-service)
+    - [ActiveJob Background Worker](#activejob-background-worker)
+    - [Rake Task](#rake-task)
+  - [Configuration Reference](#configuration-reference)
+  - [How It Works](#how-it-works)
+  - [Error Reference](#error-reference)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ---
 
 ## Features
 
-- 🔄 **Cascading Soft Deletes:** Soft deletes parent models along with dependent associations (`dependent: :destroy` / `:delete_all`).
-- ⏪ **Atomic Restores:** Reverses soft deletion for an entire object tree (`undo_log.restore!` or `record.restore!`) within a single database transaction.
-- 🔍 **Restoration Verification:** Provides `#undoable?` to check if a record is soft-deleted and has a valid undo log entry available for restoration.
-- 👤 **User Attribution (`whodunnit`):** Tracks who initiated soft deletions and restores automatically via ambient context (e.g. `Current.user`) or explicit arguments.
-- 🏢 **Multi-Tenant Isolation:** Scopes deletion audit logs to specific tenants/accounts and enforces strict tenant matching security on restoration.
-- ⚙️ **Configurable Columns:** Supports custom soft-delete columns (e.g., `:archived_at`, `:discarded_at`) per model while defaulting to `:deleted_at`.
-- 📦 **Polymorphic Tracking:** Records deletion events via native `UndoLog` and `UndoLogItem` models—no messy JSON payload parsing required.
-- 🚂 **Zero Generator Setup:** Built on top of `Rails::Engine`. Migrations automatically hook into `rails db:migrate`.
-- 🔍 **Default Scopes & Helpers:** Provides `.kept`, `.soft_deleted`, `#soft_deleted?`, and `#undoable?` query methods out of the box.
-- 🧹 **Automatic Expiration & Purging:** Configurable global retention window with automated background purging (`PurgeJob` and Rake task) to clean up old soft-deleted records and logs.
+- 🔄 **Cascading Soft Deletes:** Soft deletes parent records along with dependent associations (`dependent: :destroy` / `:delete_all`).
+- ⏪ **Atomic Restores:** Reverses soft deletion for an entire object tree (`record.restore!` or `undo_log.restore!`) within a single database transaction.
+- 🌐 **Mountable Engine & Endpoints:** Out-of-the-box controller actions for instant undo links with HTML flash redirects, Turbo Streams, and JSON responses.
+- 🔒 **Cryptographic Signed Links:** Direct undo restoration tokens (`undo_log.signed_token`) preventing ID enumeration on public or email links.
+- 🎨 **Clean View Helpers:** Drop-in `undo_button_to` and `undo_link_to` view helpers for seamless UI integration.
+- 🔍 **Restoration Verification (`#undoable?`):** Instantly check if a soft-deleted record is eligible for restore before rendering UI buttons.
+- 👤 **User Attribution (`whodunnit`):** Tracks who initiated soft deletes and restores automatically via ambient context or explicit parameters.
+- 🏢 **Multi-Tenant Isolation:** Scopes deletion logs to specific tenants with strict tenant-matching security.
+- ⚙️ **Custom Soft-Delete Columns:** Supports custom columns (e.g., `:archived_at`, `:discarded_at`) per model while defaulting to `:deleted_at`.
+- 🧹 **Retention & Auto-Purging:** Built-in expiration scopes, batch SQL purger, ActiveJob worker, and Rake task with foreign-key constraint protection.
+- 🚂 **Zero Generator Setup:** Built as a `Rails::Engine`. Migrations automatically hook into `rails db:migrate`.
 
 ---
 
-## Installation
+## Installation & Migrations
 
-Add this line to your application's `Gemfile`:
+Add the gem to your application's `Gemfile`:
 
 ```ruby
 gem "active_record-undo"
 ```
 
-Then execute:
+Then install dependencies:
 
 ```bash
 bundle install
 ```
 
-Run database migrations. The gem automatically appends its tables (`undo_logs` and `undo_log_items`) to your app's migration path:
+### Database Migrations
+
+`ActiveRecord::Undo` automatically appends its migrations (`undo_logs` and `undo_log_items`) to your application's migration path:
 
 ```bash
 rails db:migrate
 ```
 
-*(Optional)* If you need to customize the migration, copy it to your host application's `db/migrate` folder:
+*(Optional)* If you plan to use **Multi-Tenant Isolation** or **User Attribution**, add the polymorphic columns to `undo_logs`:
+
+```ruby
+# db/migrate/XXXXXX_add_tenant_and_whodunnit_to_undo_logs.rb
+class AddTenantAndWhodunnitToUndoLogs < ActiveRecord::Migration[7.0]
+  def change
+    change_table :undo_logs, bulk: true do |t|
+      t.string :whodunnit_type, null: true
+      t.bigint :whodunnit_id, null: true
+      t.string :tenant_type, null: true
+      t.bigint :tenant_id, null: true
+    end
+
+    add_index :undo_logs, [:whodunnit_type, :whodunnit_id], name: "index_undo_logs_on_whodunnit"
+    add_index :undo_logs, [:tenant_type, :tenant_id], name: "index_undo_logs_on_tenant"
+  end
+end
+```
+
+*(Optional)* If you wish to customize the gem's core migration directly:
 
 ```bash
 rails active_record_undo:install:migrations
@@ -52,14 +118,14 @@ rails active_record_undo:install:migrations
 
 ---
 
-## Usage
+## Model Setup
 
-### 1. Database Setup
+### 1. Add Timestamp Column to Tables
 
-Ensure models using soft deletion have a timestamp column in their underlying database table:
+Ensure every model using soft deletion has a timestamp column:
 
 ```ruby
-class AddSoftDeleteColumnsToModels < ActiveRecord::Migration[7.0]
+class AddDeletedAtToModels < ActiveRecord::Migration[7.0]
   def change
     add_column :posts, :deleted_at, :datetime
     add_column :comments, :deleted_at, :datetime
@@ -72,345 +138,556 @@ class AddSoftDeleteColumnsToModels < ActiveRecord::Migration[7.0]
 end
 ```
 
-### 2. Configure Models
+### 2. Declare `acts_as_undoable`
 
-Add `acts_as_undoable` to models where you want soft deletion enabled. By default, it uses `:deleted_at`, but you can pass a custom column name:
+Add `acts_as_undoable` to your models. By default, it uses the `:deleted_at` column:
 
 ```ruby
 class Post < ApplicationRecord
-  # Uses default :deleted_at column
   acts_as_undoable
 
   has_many :comments, dependent: :destroy
 end
 
 class Comment < ApplicationRecord
-  # Uses default :deleted_at column
   acts_as_undoable
 
   belongs_to :post
 end
 
 class ArchiveItem < ApplicationRecord
-  # Configured with a custom column
+  # Configured with a custom timestamp column
   acts_as_undoable column: :archived_at
 end
 ```
 
 ---
 
-## Quick Start Guide
+## Basic Usage
 
-### Soft Delete & Cascade
+### Cascading Soft Deletes
 
-Call `soft_delete!` on a record. It sets the configured soft-delete column across the record and its dependent relations inside a single transaction, returning an `ActiveRecord::Undo::UndoLog` instance:
+Call `soft_delete!` on any undoable record. It updates the timestamp column across the record and all dependent associations inside a single database transaction, returning an `ActiveRecord::Undo::UndoLog` instance:
 
 ```ruby
 post = Post.find(1)
 
-# Soft deletes post and all associated comments
+# Soft deletes post and cascades to all associated comments
 undo_log = post.soft_delete!
 
-post.soft_deleted? # => true
+post.soft_deleted?       # => true
 post.comments.kept.count # => 0
 ```
 
-### Custom Column Usage
+### Restoring Records
+
+You can restore an entire deleted tree either from the model instance or from the `UndoLog`:
+
+#### Option A: Restore from the model (Recommended)
+
+Calling `restore!` directly on the model automatically looks up its latest deletion log, executes the atomic restoration, destroys the log records, and reloads the model instance:
 
 ```ruby
-item = ArchiveItem.find(5)
-item.soft_delete!
+post.restore!
 
-item.soft_deleted? # => true
-item.archived_at   # => 2026-08-08 22:20:16 UTC
+post.soft_deleted?  # => false
+post.comments.count # => 2
 ```
 
-### Checking Restoration Eligibility (`#undoable?`)
+```ruby
+undo_log.restore!
 
-Use `#undoable?` to verify if a record is soft-deleted and has a corresponding `UndoLog` entry available in the database. This is ideal for conditionally rendering UI elements or validating controller actions:
+post.reload.soft_deleted? # => false
+```
 
-```ruby
-post = Post.unscoped.find(1)
+### Asynchronous Cascades (`soft_delete_later!` & `restore_later!`)
 
-if post.undoable?
-  # Render "Undo Deletion" button or execute restore
-  post.restore!
-end
+For deep or massive association trees (5,000+ items), synchronous processing can breach web request timeouts (e.g., Puma 30s limits, Cloudflare 524 timeouts). `active_record-undo` provides non-blocking asynchronous operations powered by ActiveJob, using batched DFS traversal to keep memory flat:
+
+```ruby
+# 1. Soft delete asynchronously: hides root record immediately and enqueues SoftDeleteJob
+undo_log = post.soft_delete_later!
+# Or specify a custom ActiveJob queue:
+undo_log = post.soft_delete_later!(queue: :low_priority)
+
+post.soft_deleted?            # => true (immediately hidden from Post.kept)
+post.soft_delete_status       # => "pending" -> "processing" -> "completed"
+post.soft_delete_processing?  # => true / false
+post.undoable?                # => false until SoftDeleteJob completes
+
+# 2. Restore asynchronously: enqueues RestoreJob to restore all cascaded items bottom-up
+post.restore_later!
+# Or call directly on the UndoLog:
+undo_log.restore_later!(queue: :critical)
+
+post.restore_status           # => "pending" -> "processing"
+post.restore_processing?      # => true / false
 ```
 
-`#undoable?` returns `false` if:
+### Asynchronous Failure Recovery & Execution Logging
 
-- The record is currently active (not soft deleted).
-- The record was soft deleted manually via direct SQL/column updates without generating an undo log.
-- The corresponding `UndoLog` record was purged or already restored.
+When running asynchronous cascades over thousands of associated records, background jobs can encounter transient failures such as database connection drops, lock acquisition timeouts, deadlocks, or worker restarts. `active_record-undo` provides robust failure tracking, persistent error logging, and idempotent recovery semantics.
 
-### Inspect Deletion Logs
+#### 1. Lifecycle State Machine
 
-Inspect affected records through standard Rails associations on the returned `UndoLog`:
+Every asynchronous operation updates execution state directly on the database `undo_logs` record:
 
-```ruby
-# List all items affected by this deletion event
-undo_log.undo_log_items.map(&:item)
-# => [#<Comment 101... id:>, #<Comment 102... id:>, #<Post 1... id:>]
+```
+[:pending] ────► [:processing] ────► [:completed] (Destroyed on restore completion)
+                       │
+                       ▼
+                   [:failed] (with persistent error_message)
 ```
 
-### Restoring Records
+- **`status`**: `:pending` (0), `:processing` (1), `:completed` (2), `:failed` (3).
+- **`action`**: `:soft_delete` (0), `:restore` (1).
+- **`error_message`**: Captures `exception.message` when a job fails.
+
+#### 2. Worker Re-raising & Queue Integration
+
+When an exception occurs during `SoftDeleteJob` or `RestoreJob`:
+1. The job catches `StandardError`.
+2. It immediately updates the `UndoLog` with `status: :failed` and `error_message: exception.message`.
+3. It **re-raises** the exception (`raise e`).
+
+Re-raising guarantees full integration with your ActiveJob backend (Sidekiq, Solid Queue, GoodJob, DelayedJob) and application monitoring:
+- **Queue Retries**: Native queue retries (e.g., `retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3`) function normally.
+- **Error Tracking**: Exceptions are automatically sent to Sentry, Honeybadger, Bugsnag, Datadog, etc., with full backtraces.
+- **Custom Base Job**: Set `config.base_job = 'ApplicationJob'` to inherit your application's logging tags, retry strategies, and discard handlers.
 
-To restore a deleted object tree, you can invoke `restore!` either on the corresponding `UndoLog` or directly on the model instance itself:
+#### 3. Idempotency & Safe Resumption
 
-#### Option A: Restore from the model instance (Recommended)
+Both jobs are engineered for safe re-entrancy, allowing failed or interrupted jobs to be retried without corrupting data or duplicating log items:
 
-Calling `restore!` directly on the soft-deleted model automatically resolves its latest deletion event log, performs the cascading restore, and cleans up the log database rows:
+- **Soft Delete Re-entrancy**: `CascadeHandler` uses `in_batches` and checks `associated.reload.soft_deleted?`. If a worker dies halfway or encounters a transient error, retrying the job safely skips already soft-deleted records and continues cascade processing for the remaining associations.
+- **Restore Batches & Row Locking**: `RestoreJob` acquires a database row lock using `undo_log.with_lock` (`SELECT FOR UPDATE`). This prevents duplicate or concurrent worker runs on the same log. Restorations update `deleted_at: nil` in batches (`find_each(batch_size: 1000)`). The `UndoLog` and its `undo_log_items` are only pruned after all batches finish. If an error interrupts restoration, the log and all un-restored items remain preserved in the database for inspection, retry, or manual recovery.
+
+#### 4. Inspecting & Retrying Failed Operations
+
+Engineers or automated recovery tasks can query and inspect failed jobs directly via ActiveRecord:
 
 ```ruby
-# Restores the post and all comments deleted in the same batch (automatically reloads in-memory)
-post.restore!
+# Query failed operations
+failed_logs = ActiveRecord::Undo::UndoLog.failed # or .where(status: :failed)
 
-post.soft_deleted?  # => false
-post.comments.count # => 2
+failed_logs.each do |log|
+  puts "UndoLog ##{log.id} (#{log.action}) failed: #{log.error_message}"
+
+  # Re-enqueue restoration
+  log.restore_later! if log.action == "restore"
+
+  # Or execute synchronously to inspect immediately
+  log.restore! if log.action == "restore"
+end
 ```
 
-#### Option B: Restore from the `UndoLog`
+#### 5. Frontend Polling & Error Observability
 
-```ruby
-# Reverses soft deletes for the post and comments
-undo_log.restore!
+Frontends can poll status endpoints using the numeric ID or signed token:
+- `GET /undo/logs/:id/status`
+- `GET /undo/status/:token`
 
-post.reload.soft_deleted? # => false
-post.comments.count       # => 2
+On failure, the endpoint returns a `200 OK` JSON payload with error details:
+
+```json
+{
+  "id": 42,
+  "status": "failed",
+  "action": "restore",
+  "error_message": "PG::QueryCanceled: canceling statement due to statement timeout",
+  "completed": false,
+  "failed": true
+}
 ```
 
----
+The view helpers (`undo_status_badge`, `soft_delete_status_badge`, `restore_status_badge`) automatically apply the `.undo-status-failed` CSS class so your UI can display a failure indicator or retry button.
+
+
+### Status & Eligibility Helpers
+
+`ActiveRecord::Undo` provides fast predicate methods and audit helpers on models:
+
+```ruby
+# Checks if the soft-delete column is set
+post.soft_deleted? # => true / false
+
+# Verifies record is soft-deleted AND has a completed undo log ready to restore
+post.undoable?     # => true / false (false while async soft-delete/restore is in progress)
+
+# Soft-delete & Restore operation statuses (for frontend badges / live polling)
+post.soft_delete_status       # => "pending", "processing", "completed", "failed", or nil
+post.restore_status           # => "pending", "processing", "completed", "failed", or nil
+post.soft_delete_pending?     # => true / false
+post.soft_delete_processing?  # => true / false
+post.soft_delete_completed?   # => true / false
+post.soft_delete_failed?      # => true / false
+post.restore_pending?         # => true / false
+post.restore_processing?      # => true / false
+post.restore_failed?          # => true / false
+
+# Checks if the soft-deleted record has exceeded the configured retention period
+post.expired?      # => true / false
+
+# Retrieves the latest UndoLog audit record associated with this model
+post.undo_log      # => #<ActiveRecord::Undo::UndoLog id: 14, status: "completed", ...>
+post.latest_undo_log # alias
+
+# Generates a cryptographic signed restoration token directly from the model
+post.signed_token  # => "eyJfcmFpbHMiOnsiZGF0YSI6..."
+```
+
+> [!TIP]
+> Use `#undoable?` to conditionally display restore buttons in your user interface, passing the model instance directly:
+>
+> ```erb
+> <% if post.undoable? %>
+>   <%= undo_button_to(post, text: "Restore") %>
+> <% end %>
+> ```
 
-## Scopes & Querying
+### Query Scopes
 
-`ActiveRecord::Undo` provides scopes and predicate helpers for filtering and checking records based on the configured column:
+Filter records easily without writing manual SQL:
 
 ```ruby
-# Fetch only active (non-deleted) records
+# Only active (non-deleted) records
 Post.kept
 
-# Fetch soft-deleted records
+# Only soft-deleted records
 Post.soft_deleted
 
-# Check if a record is soft-deleted
-post.soft_deleted?
+# Soft-deleted records past the retention limit
+Post.expired
 
-# Check if a record is soft-deleted AND can be restored via an undo log
-post.undoable?
+# Retrieve all records including soft-deleted ones
+Post.unscoped.all
+```
+
+### Inspecting Deletion Logs
+
+Inspect affected records through standard Rails associations on `UndoLog`:
 
-# Retrieve records including soft-deleted ones via unscoped
-Post.unscoped.where(id: 1)
+```ruby
+undo_log.undo_log_items.map(&:item)
+# => [#<Comment id: 101>, #<Comment id: 102>, #<Post id: 1>]
 ```
 
 ---
 
-## Expiration, Retention & Auto-Purging
+## Mountable Route & Controller Engine
 
-To prevent database bloat, `active_record-undo` supports automated retention periods, expiration checks, and background purging for both soft-deleted records and their associated `UndoLog` audit entries.
+`active_record-undo` provides a mountable Rails engine route and controller endpoints so host applications can handle undo/restore actions via HTTP requests without writing boilerplate controller logic.
 
-### 1. Global Configuration
+### Mounting the Engine
 
-You can configure a global retention period inside a Rails initializer:
+Mount the engine in your application routes:
 
 ```ruby
-# config/initializers/active_record_undo.rb
-ActiveRecord::Undo.configure do |config|
-  # Default retention period for all soft-deleted records and undo logs (defaults to 30.days)
-  config.retention_period = 30.days
+# config/routes.rb
+Rails.application.routes.draw do
+  mount ActiveRecord::Undo::Engine => "/undo"
 end
 ```
 
-If `retention_period` is set to `nil`, records and logs will never expire.
+### Available Endpoints
 
-### 2. Expiration Scopes & Helpers
+| Method | Route                    | Controller#Action                    | Description                                         |
+| :----- | :----------------------- | :----------------------------------- | :-------------------------------------------------- |
+| `POST` | `/undo/logs/:id/restore` | `active_record/undo/logs#restore`    | Restores an `UndoLog` by ID (supports `async: true`)|
+| `POST` | `/undo/restore/:token`   | `active_record/undo/restores#create` | Restores using signed token (supports `async: true`)|
+| `GET`  | `/undo/logs/:id/status`  | `active_record/undo/logs#status`     | Polls restoration or soft delete status JSON        |
+| `GET`  | `/undo/status/:token`    | `active_record/undo/restores#status` | Polls status JSON using signed token                |
 
-The gem provides query scopes and instance predicate helpers:
+### View Helpers (`undo_button_to`, `undo_link_to`, `undo_status_badge`, `soft_delete_status_badge` & `restore_status_badge`)
 
-- **Model `.expired` Scope**: Returns soft-deleted records older than the configured retention period.
+Clean view helpers are automatically available in all Rails views and forms:
 
-  ```ruby
-  Post.expired # => ActiveRecord::Relation of posts soft-deleted > 30 days ago
-  ```
+```erb
+<%# Standard button_to targeting /undo/logs/:id/restore %>
+<%= undo_button_to(@undo_log) %>
 
-- **Model `#expired?` Predicate**: Checks if a record is soft-deleted and past the retention period.
+<%# Pass model instances directly %>
+<%= undo_button_to(post, text: "Undo Delete", class: "btn btn-primary") %>
 
-  ```ruby
-  post.expired? # => true/false
-  ```
+<%# Asynchronous restore button %>
+<%= undo_button_to(post, params: { async: true }, text: "Restore Asynchronously") %>
 
-- **`UndoLog.expired` Scope**: Returns undo log entries older than the retention period.
+<%# Auto-detecting status badge helper for frontend progress %>
+<%= undo_status_badge(post) %>
+<!-- Renders: <span class="undo-status-badge undo-soft-delete-badge undo-status-processing">Processing</span> -->
 
-  ```ruby
-  ActiveRecord::Undo::UndoLog.expired # => logs created > 30 days ago
-  ```
+<%# Explicit status badge helpers for soft delete and restore %>
+<%= soft_delete_status_badge(post) %>
+<%= restore_status_badge(post) %>
+<%= soft_delete_status_badge(post, text: "Deleting...") %>
 
-### 3. Background Purging
+<%# Secure direct link with signed token (prevents ID enumeration in emails or public links) %>
+<%= undo_button_to(@undo_log, signed: true, class: "btn btn-success") %>
 
-#### Purger Service
+<%# Turbo Stream / Hotwire compatible link %>
+<%= undo_link_to(@undo_log, text: "Undo", class: "text-decoration-underline") %>
+<%= undo_link_to(@undo_log, signed: true) %>
+```
 
-The `ActiveRecord::Undo::Purger` class performs hard SQL deletes on expired records and logs using `delete_all` (bypassing callbacks and validations for efficiency):
+### Cryptographic Signed Restore Tokens
 
-```ruby
-# Purge all expired soft-deleted records and undo logs in batches
-ActiveRecord::Undo::Purger.purge_expired!(batch_size: 1000)
+When exposing restore actions in flash notifications, transactional emails, webhook alerts, or public interfaces, relying on sequential database IDs (e.g., `POST /undo/logs/42/restore`) can expose your application to ID enumeration attacks.
+
+`active_record-undo` provides signed tokens for restoration via tamper-proof, opaque URLs: `POST /undo/restore/:token`.
+
+#### Generating & Using Signed Tokens
+
+**In Views (using helpers):**
+
+```erb
+<%# Renders a form POST to /undo/restore/:token %>
+<%= undo_button_to(post, signed: true, text: "Undo Delete", class: "btn btn-outline-primary") %>
+
+<%# Renders an anchor tag for Turbo / Hotwire %>
+<%= undo_link_to(post, signed: true, text: "Undo") %>
 ```
 
-> [!NOTE]
-> **Relational Integrity & Constraint Protection**: To prevent database-level foreign key constraint failures (e.g. `FOREIGN KEY constraint failed`), `Purger` dynamically resolves dependent associations (such as `dependent: :destroy`, `dependent: :delete_all`, or `dependent: :soft_delete`) and recursively purges associated child records bottom-up before deleting the parent record. For associations configured with `dependent: :nullify`, it nullifies the foreign key (or cascades the deletion if the foreign key column is database-restricted to be `NOT NULL`).
+**In Controllers, Background Jobs & Mailers:**
+
+```ruby
+# Generate token directly from the model instance
+token = post.signed_token
 
-#### ActiveJob Background Job
+# Or with a custom expiration window
+token = post.signed_token(expires_in: 2.hours)
 
-The gem provides an ActiveJob class that calls the Purger service:
+# Or directly from an UndoLog instance
+token = undo_log.signed_token
+
+# Construct full URL for transactional emails or Slack webhooks
+restore_url = active_record_undo.signed_restore_url(token: token)
+```
+
+**Manual Verification & Retrieval:**
 
 ```ruby
-# Enqueue the purge job to run in the background
-ActiveRecord::Undo::PurgeJob.perform_later(batch_size: 1000)
+# Manually verify and retrieve the associated UndoLog
+undo_log = ActiveRecord::Undo::UndoLog.find_by_signed_token(params[:token])
 ```
 
-#### Engine Rake Task
+#### Key Security Properties
 
-You can run the purge task via Rake. This task is automatically loaded into host applications:
+1. **HMAC-SHA256 Cryptographic Tamper Resistance:** Tokens are signed using `Rails.application.message_verifier(:active_record_undo)` derived securely from your application's `secret_key_base`. Any payload alteration invalidates the cryptographic signature.
+2. **Purpose Isolation (`purpose: :restore`):** Tokens are strictly scoped to restoration. Tokens generated for other purposes (or by other verifiers) are rejected.
+3. **Time-Limited Lifespan:** Tokens include an embedded expiration timestamp (configurable via `config.token_expires_in`, defaults to `24.hours`). Expired tokens are rejected automatically.
+4. **Single-Use Replay Protection:** When `undo_log.restore!` succeeds, it automatically destroys the `UndoLog` and its associated items from the database (`destroy!`). Even if an attacker or user resubmits the signed token before its cryptographic expiration, the database lookup fails and returns `nil`, rendering a `404 Not Found`.
+5. **Multi-Tenant Authorization:** Cryptographic validity only proves the token was authentic. During execution, `undo_log.restore!` still enforces multi-tenant boundary matching against `ActiveRecord::Undo.current_tenant`. An authenticated user from Tenant B cannot use a token from Tenant A to restore data.
 
-```bash
-# Run with the default batch size of 1000
-$ rails active_record_undo:purge_expired
+### Multi-Format Responses
 
-# Run with a custom batch size
-$ BATCH_SIZE=500 rails active_record_undo:purge_expired
-```
+The engine controller seamlessly handles multiple response formats:
+
+- **HTML:** Redirects to `params[:redirect_to]` (if a validated safe URL), `request.referer`, or `config.default_redirect_path` with a flash notice (`flash[:notice] = "Record successfully restored."`).
+- **Turbo Stream (`text/vnd.turbo-stream.html`):** Renders inline `<turbo-stream>` notification elements with HTTP status `200 OK`.
+- **JSON:** Returns `{ "success": true, "restored_items_count": count }` with HTTP status `200 OK`.
+
+In error scenarios (missing record, expired action, or security mismatch):
+
+- **`403 Forbidden`:** Rendered on `ActiveRecord::Undo::SecurityError` (or HTML redirected with `flash[:alert]`).
+- **`404 Not Found`:** Rendered when the undo log does not exist or has already been restored.
+- **`422 Unprocessable Content`:** Rendered when the undo action has expired beyond the retention period.
+
+### Security & Open-Redirect Protection
+
+- **CSRF Protection:** Inherits from `ActionController::Base` (or your configured `base_controller`) with CSRF verification enabled.
+- **Open-Redirect Mitigation:** `params[:redirect_to]` and `request.referer` undergo strict URL validation. Only relative paths or URLs matching the request's exact host and port are accepted; foreign or protocol-relative URLs (e.g., `//evil.com`) are rejected in favor of the safe fallback.
+- **Signed Tokens:** `undo_log.signed_token` uses Rails' `message_verifier(:active_record_undo)` to sign tokens cryptographically, preventing tampering, replay, and ID enumeration.
 
 ---
 
 ## Multi-Tenant Isolation & User Attribution
 
-To support enterprise-grade Rails applications, `active_record-undo` provides native mechanisms for multi-tenant data isolation and user auditing.
+To support enterprise-grade Rails applications, `active_record-undo` natively integrates user auditing and tenant scoping.
 
-### 1. Database Setup
+### User Attribution (`whodunnit`)
 
-Add a migration to introduce polymorphic tenant and user attribution columns to the `undo_logs` table:
+Track which user initiated a soft deletion or restoration:
 
 ```ruby
-class AddTenantAndUserAttributionToUndoLogs < ActiveRecord::Migration[7.0]
-  def change
-    change_table :undo_logs, bulk: true do |t|
-      t.string :whodunnit_type, null: true
-      t.bigint :whodunnit_id, null: true
-      t.string :tenant_type, null: true
-      t.bigint :tenant_id, null: true
-    end
+# 1. Via explicit parameter
+post.soft_delete!(whodunnit: current_user)
+post.restore!(whodunnit: current_user)
 
-    add_index :undo_logs, [:whodunnit_type, :whodunnit_id], name: 'index_undo_logs_on_whodunnit'
-    add_index :undo_logs, [:tenant_type, :tenant_id], name: 'index_undo_logs_on_tenant'
-  end
+# 2. Via Thread / Fiber ambient context
+ActiveRecord::Undo.whodunnit = current_user
+post.soft_delete!
+
+# 3. Via global callable proc
+ActiveRecord::Undo.configure do |config|
+  config.current_user_method = -> { Current.user }
 end
 ```
 
-### 2. Global Configuration
+### Multi-Tenant Scoping
 
-Configure global procs (e.g. evaluating `CurrentAttributes`) in your initializer:
+Scope soft deletes and logs to accounts or organizations:
 
 ```ruby
-# config/initializers/active_record_undo.rb
+# 1. Via explicit parameter
+post.soft_delete!(tenant: current_account)
+
+# 2. Via Thread / Fiber ambient context
+ActiveRecord::Undo.current_tenant = current_account
+post.soft_delete!
+
+# 3. Via global callable proc
 ActiveRecord::Undo.configure do |config|
-  # Callable accessors to automatically resolve context
-  config.current_user_method   = -> { Current.user }
   config.current_tenant_method = -> { Current.account }
 end
 ```
 
-### 3. Usage & Thread Context
+### Tenant Matching Security
 
-You can set thread/fiber context explicitly:
+When restoring a log belonging to a tenant, the gem verifies that the executing context's tenant matches the log's tenant. If there is a mismatch or missing tenant context, an `ActiveRecord::Undo::SecurityError` is raised:
 
 ```ruby
-ActiveRecord::Undo.whodunnit = current_user
-ActiveRecord::Undo.current_tenant = current_account
+ActiveRecord::Undo.current_tenant = wrong_account
+post.restore! # => raises ActiveRecord::Undo::SecurityError (Tenant mismatch)
 ```
 
-Or pass values explicitly as parameters to model operations:
+### Configured Context Enforcement
 
-```ruby
-# Capture user and tenant during deletion
-post.soft_delete!(whodunnit: current_user, tenant: current_account)
+When `current_user_method` or `current_tenant_method` is configured via `ActiveRecord::Undo.configure`, operations ensure the context does not evaluate to `nil`:
 
-# Track who performed the restoration
-post.restore!(whodunnit: current_user)
+```ruby
+# If current_user_method evaluates to nil (e.g., unauthenticated request):
+post.soft_delete! # => raises ActiveRecord::Undo::SecurityError: Configured current_user_method returned nil.
 ```
 
-### 4. Tenant Matching Security & Context Enforcement
+*(If neither method is configured, operations proceed normally without requiring user or tenant context).*
 
-#### Tenant Matching Security
+---
+
+## Retention, Expiration & Purging
+
+To keep your database lean, `active_record-undo` provides retention management and automated background purging.
 
-When restoring a log that belongs to a tenant, the gem verifies that the initiating context's tenant matches the log's tenant. If there is a mismatch (or if no tenant is set in the context), the gem raises an `ActiveRecord::Undo::SecurityError`:
+### Expiration Checks
+
+Query and check expired records using the configured retention window (default: `30.days`):
 
 ```ruby
-ActiveRecord::Undo.current_tenant = wrong_account
-post.restore! # => raises ActiveRecord::Undo::SecurityError: Tenant mismatch
-```
+# Scopes
+Post.expired                        # Soft-deleted posts older than retention period
+ActiveRecord::Undo::UndoLog.expired # Undo logs older than retention period
 
-#### Configured Context Enforcement
+# Predicates
+post.expired?     # => true / false
+undo_log.expired? # => true / false
+```
 
-When `current_user_method` or `current_tenant_method` is configured via `ActiveRecord::Undo.configure`, operations enforce that the evaluated context is not `nil`:
+### Purger Service
 
-- Calling `soft_delete!` or `restore!` when a configured method evaluates to `nil` immediately raises an `ActiveRecord::Undo::SecurityError`.
-- If both user and tenant methods are configured, both must return valid non-nil objects for operations to proceed.
-- If neither method is configured, operations proceed normally without requiring user or tenant context.
+`ActiveRecord::Undo::Purger` performs batch SQL deletes bypassing model callbacks for peak efficiency:
 
 ```ruby
-# If current_user_method is configured (e.g. -> { Current.user }),
-# but the request is unauthenticated (evaluates to nil):
-post.soft_delete! # => raises ActiveRecord::Undo::SecurityError: Configured current_user_method returned nil.
-post.restore!     # => raises ActiveRecord::Undo::SecurityError: Configured current_user_method returned nil.
+# Purge all expired records and logs across registered models
+ActiveRecord::Undo::Purger.purge_expired!(batch_size: 1000)
+
+# Scoped purge for a specific tenant
+ActiveRecord::Undo.current_tenant = account_1
+ActiveRecord::Undo::Purger.purge_expired!
 ```
 
-### 5. Query Scopes & Purging
+> [!NOTE]
+> **Relational Integrity Protection:** To prevent foreign-key constraint violations (`FOREIGN KEY constraint failed`), `Purger` dynamically resolves dependent associations (`:destroy`, `:delete_all`, `:soft_delete`) and recursively cleans up child records bottom-up before purging parent records. For `:nullify` associations, foreign keys are nullified (or cascaded if restricted by a `NOT NULL` constraint).
 
-Query logs scoped to a specific user or tenant:
+### ActiveJob Background Worker
+
+Enqueue purges easily via ActiveJob:
 
 ```ruby
-ActiveRecord::Undo::UndoLog.for_whodunnit(user)
-ActiveRecord::Undo::UndoLog.for_tenant(account)
+ActiveRecord::Undo::PurgeJob.perform_later(batch_size: 1000)
 ```
 
-If `current_tenant` is set in the context when running the `Purger`, purging of both logs and model records will be strictly scoped to that tenant:
+### Rake Task
+
+Run purging from cron, cron-like schedulers, or CI:
+
+```bash
+# Default batch size (1000)
+rails active_record_undo:purge_expired
+
+# Custom batch size
+BATCH_SIZE=500 rails active_record_undo:purge_expired
+```
+
+---
+
+## Configuration Reference
+
+Configure all gem options in a single initializer:
 
 ```ruby
-# Scoped purge for account_1
-ActiveRecord::Undo.current_tenant = account_1
-ActiveRecord::Undo::Purger.purge_expired!
+# config/initializers/active_record_undo.rb
+ActiveRecord::Undo.configure do |config|
+  # Default retention period for soft-deleted records and undo logs (defaults to 30.days)
+  # Set to nil to disable expiration
+  config.retention_period = 30.days
+
+  # Callable procs to resolve ambient user and tenant context (defaults to nil)
+  config.current_user_method   = -> { Current.user }
+  config.current_tenant_method = -> { Current.account }
+
+  # Base controller for engine authentication and authorization hooks
+  # Defaults to "::ApplicationController" if defined, falling back to ActionController::Base
+  config.base_controller = "::ApplicationController"
+
+  # Base job class for asynchronous workers (SoftDeleteJob, RestoreJob, PurgeJob)
+  # Defaults to "::ActiveJob::Base"
+  config.base_job = "::ActiveJob::Base"
+
+  # Fallback redirect path after successful restore when no redirect_to or referer exists
+  config.default_redirect_path = ->(main_app) { main_app.root_path }
+
+  # Expiration duration for signed restore tokens (defaults to 24.hours)
+  config.token_expires_in = 24.hours
+
+  # Custom secret key for signed tokens (defaults to nil, utilizing Rails application verifier)
+  config.token_secret_key = nil
+
+  # Error handling strategy for HTML requests (:auto, :redirect, or :render)
+  # Defaults to :auto (redirects with flash alert if referer/redirect_to present, else renders status)
+  config.error_handling = :auto
+end
 ```
 
 ---
 
 ## How It Works
 
-1. **Cascade Inspection:** When `soft_delete!` is called, `ActiveRecord::Undo::CascadeHandler` reflects on `has_many`, `has_one`, and `belongs_to` associations configured with `dependent: :destroy` or `:delete_all`.
-2. **Dynamic Column Resolution:** The handler checks `record.class.undoable_column` to set the correct timestamp column (`:deleted_at`, `:archived_at`, etc.) across all affected models.
-3. **Polymorphic Logging:** An `ActiveRecord::Undo::UndoLog` record is created alongside multiple `ActiveRecord::Undo::UndoLogItem` entries mapping polymorphic references (`item_type`, `item_id`) to every affected record.
-4. **Restoration Verification:** Calling `#undoable?` executes an efficient SQL query joining `undo_log_items` and `undo_logs` to ensure the entity is soft-deleted and its associated log entry exists before restoration.
-5. **Atomic Operation:** All updates and log creations take place within an `ActiveRecord::Base.transaction`.
+1. **Cascade Inspection:** On calling `soft_delete!`, `ActiveRecord::Undo::CascadeHandler` reflects on `has_many`, `has_one`, and `belongs_to` associations configured with `dependent: :destroy` or `:delete_all`.
+2. **Column Resolution:** Identifies `record.class.undoable_column` to apply the correct timestamp column (`:deleted_at`, `:archived_at`, etc.) across all affected models.
+3. **Audit Logging:** Creates an `UndoLog` and individual `UndoLogItem` entries storing polymorphic references (`item_type`, `item_id`) for every soft-deleted record.
+4. **Atomic Operation:** Deletions and log creations execute within a single `ActiveRecord::Base.transaction`.
+5. **Reverse Restoration:** Calling `restore!` executes within a transaction, iterating over items in reverse order (`reverse_each`) so parent and dependent records are re-activated in the proper sequence before purging the log.
 
 ---
 
-## Error Handling
-
-To ensure database integrity and provide clear debugging context, the gem raises errors in the following scenarios:
+## Error Reference
 
-- **Missing Column at Runtime (`ActiveRecord::Undo::Error`):** If the configured soft-delete column is missing from the database table when calling `soft_delete!` or `restore!`.
-- **Missing Model Class (`ActiveRecord::Undo::Error`):** If a model class has been renamed or deleted, preventing the polymorphic log items from finding the target class during restore.
-- **Missing Column on Target Class (`ActiveRecord::Undo::Error`):** If a model class exists but no longer has the target soft-delete column during restore.
-- **Cross-Tenant Restoration Attempt (`ActiveRecord::Undo::SecurityError`):** If attempting to restore a record whose `UndoLog` belongs to a tenant different from the current context tenant.
-- **Missing Tenant Context on Restoration (`ActiveRecord::Undo::SecurityError`):** If attempting to restore a tenant-scoped record when no tenant is set in the context.
-- **Configured Context Evaluated to Nil (`ActiveRecord::Undo::SecurityError`):** If `current_user_method` or `current_tenant_method` is configured but returns `nil` during `soft_delete!` or `restore!`.
+| Error Class                         | Trigger Scenario                                                              |
+| :---------------------------------- | :---------------------------------------------------------------------------- |
+| `ActiveRecord::Undo::Error`         | The configured soft-delete column does not exist on the table.                |
+| `ActiveRecord::Undo::Error`         | A model class referenced by an `UndoLogItem` was renamed or deleted.          |
+| `ActiveRecord::Undo::SecurityError` | Attempted restore where the context's tenant does not match the log's tenant. |
+| `ActiveRecord::Undo::SecurityError` | Attempted restore of a tenant-scoped log when no tenant is set in context.    |
+| `ActiveRecord::Undo::SecurityError` | Configured `current_user_method` or `current_tenant_method` returned `nil`.   |
 
 ---
 
 ## Development
 
-After cloning the repository, install dependencies:
+Clone the repository and install dependencies:
 
 ```bash
+git clone https://github.com/saurabh-activecode/active_record-undo.git
+cd active_record-undo
 bundle install
 ```
 
@@ -420,11 +697,17 @@ Run test suite via RSpec:
 bundle exec rspec
 ```
 
+Run RuboCop linting:
+
+```bash
+bundle exec rubocop
+```
+
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at <https://github.com/saurabh-activecode/active_record-undo>.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/saurabh-activecode/active_record-undo](https://github.com/saurabh-activecode/active_record-undo).
 
 ## License