concerns_on_rails 1.21.1 → 1.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87a3ceebf2b9eb0f8a00c9d6a8cc57d8f50c8b1ff698be887aef42da64eb08c3
-  data.tar.gz: 1a82dd3dbe363e65f3a0d91c66cb453d54415032def91e90a388663ce2e90dab
+  metadata.gz: ba3e5dc1bc6af51ec2bd4e29946973c5fc68736d4c1994fdbd472874f965c4bc
+  data.tar.gz: 16b2372635abe33484efabcae5407d1debe5a0627df9df0496a04e930c46ec65
 SHA512:
-  metadata.gz: ebfb6e59e582240aab7bc0fe18e64e48f1f291f482b38df2dac97c3cc843f5731857594724868484fee75b9269ccaca923f6d229d862b3ce4ddfdf49c3f9aa27
-  data.tar.gz: 53d1b47d39588d102a4b6527b43b1801a1f87c47c1da7a67b823fb2138160e0dc8e1de9ea6d3b16070a2a33ca247a88832556de01e512b8ac474a9b5de288b6e
+  metadata.gz: 8a159b0026bca1ebc72dbc11c45e875caaa19ad2ec0615ee658abd5b3e8ab53e0bb309d816a5371ddba6bad5c609b82a76228e66d678d3346d624021634eddf5
+  data.tar.gz: da89fb098f9e17fd9ae49662efdb027efb64958007bf790ee895c0faf39a1c9f2cb76d2e95a4b0b3b075bcb404fe926c36d970f78ca152bdd287be81e7a3a991

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 <!-- CHANGELOG.md -->
 
+## 1.23.0 (2026-07-26)
+
+Two new model concerns — the roadmap picks after 1.22's fixes round: the right-to-erasure capability that completes the sensitive-data suite, and the concern-aware deep copy that makes "duplicate this invoice" safe next to unique slugs, tokens, and sequence numbers. 1075 examples, 0 failures.
+
+### Added
+- **Models::Anonymizable**: declarative right-to-erasure ("GDPR-lite") for personal data — the fourth member of the sensitive-data suite (Maskable masks display, Sanitizable strips HTML, Encryptable protects at rest; Anonymizable DESTROYS). `anonymizable *fields, with:` declares an erasure strategy per field group (repeatable; rules merge): presets `:nullify`, `:redact`, `:hash` (SHA-256 — deterministic pseudonymization, joins keep working), `:email` (random unique `anon-…@anonymized.invalid`, so NOT NULL + unique email columns survive erasure), `:random_hex`, or a callable (`->(value)` / `->(value, record)`); presets pass nil through untouched. `anonymize!` runs `before_anonymize` + ONE `update_columns` UPDATE + `after_anonymize` in a single transaction — deliberately skipping validations (erasure must not be blocked by a presence check) and callbacks (nothing may copy the old values elsewhere; Auditable's capture hook is the canonical example) — then reloads. Values serialize through the model's attribute types, so a field that is also `encryptable` stores a fresh ciphertext envelope of the anonymized value, never plaintext (spec-verified). When an erased field is also `auditable_by`, the audit column (which holds its plaintext history) is cleared in the same UPDATE (`clear_audit_trail: false` opts out). `stamp:` column (default `:anonymized_at`; `false` opts out) powers `anonymized?`, the `anonymized`/`not_anonymized` scopes (affixable via `prefix:`/`suffix:`), and the idempotent batch `anonymize_all!` (Integer count, skips stamped records — the 1.22 batch contract). Macro-time `ArgumentError` validation for fields, presets, callables, and columns. Zero new dependencies.
+- **Models::Duplicable**: concern-aware deep copy ("clone this invoice/template"). A bare AR `dup` copies identity-bearing columns — slug, API token, invoice number, audit trail, even `created_at` (which AR preserves on save when present) — so naive copies collide with unique indexes or lie about their history. `duplicate` (unsaved) / `duplicate!(overrides)` (saved, one transaction, autosaved children) blank exactly those columns automatically: timestamps, Sluggable's slug, Tokenizable/Hashable columns, Sequenceable sequence + `into:` columns, Auditable's trail (the copy inherits no history; its own creation is then audited normally), SoftDeletable's timestamp (a copy of trash is live), and Lockable's attempts (0) / locked_at (nil) — each concern regenerates fresh values on the copy's save. Business state (Publishable/Stateable/…) is deliberately NOT auto-reset — list it in `reset:`. `duplicable_by associations:, reset:, suffix:` (optional — bare include works): the association allow-list is validated at macro time (declared-before, the CounterCacheable convention); `has_many`/`has_one` children deep-copy — a child whose class also includes Duplicable copies via ITS OWN rules, so nested graphs stay declarative; `has_and_belongs_to_many` re-links the same records; `belongs_to` and `has_many :through` are rejected with explanations. `suffix: { title: " (copy)" }` appends to present values; `on_duplicate(copy)` is the override hook. Zero new dependencies.
+
+### Internal
+- Top-level aliases `ConcernsOnRails::Anonymizable` / `ConcernsOnRails::Duplicable` registered alongside the existing set; docs site pages + registry entries added for both concerns.
+
+## 1.22.0 (2026-07-26)
+
+A fixes-and-optimizations release driven by a full-library review of all 40 concerns: one data-loss bug, three request-crashing 500s verified through real ActionController dispatch, security headers restored on rescued error responses, a fail-open authorization path closed, and the gem's largest performance defect (unmemoized PBKDF2 per encrypted-value access) eliminated. 1031 examples, 0 failures.
+
+### Fixed
+- **Models::SoftDeletable**: `really_destroy_all` now hard-deletes only the records matching the calling relation (soft-deleted included) — previously it ran `unscoped.delete_all` and deleted the ENTIRE table regardless of scope (`User.where(account_id: 1).really_destroy_all` wiped every account). Note `unscope` also drops a caller's own predicate on the soft-delete column, so `only_deleted.really_destroy_all` widens to the whole relation — use `soft_deleted.delete_all` to purge trash.
+- **Controllers::Includable**: sparse fieldsets (`?fields[articles]=id,title`) no longer 500 — in a real controller `params[:fields]` is an `ActionController::Parameters`, which has no `each_with_object`; every documented fieldsets request raised `NoMethodError`. Verified through a new real-ActionController integration harness.
+- **Controllers::Paginatable / CursorPaginatable**: `?page[]=1`, `?per_page[x]=5` and friends no longer 500 — untrusted param reads route through the new `Support::ScalarParam` (Filterable's guard, now shared; Filterable also rejects arrays *containing* nested hashes, the `?status[][x]=1` shape).
+- **Controllers::SecureHeadable**: security headers are now also applied via `prepend_before_action` — Rails skips `after_action` callbacks entirely when `rescue_from` handles an exception, so every handled 404/422/500 previously shipped with NO security headers. (Opting out now requires `skip_before_action :apply_secure_headers` alongside the existing `skip_after_action`.)
+- **Controllers::Cacheable**: `no_store` policies are likewise applied early, so rescued error responses on `no_store` endpoints carry `Cache-Control: no-store`; positive freshness deliberately stays post-action (a rescued 500 must never become CDN-cacheable). `stale_resource?` no longer writes ETag/Last-Modified validators for unsafe (non-GET/HEAD) requests, and the 304 path is a single write.
+- **Controllers::Authorizable**: fails CLOSED — a denial that cannot be rendered (no response object) now raises instead of silently letting the action run; `require_role` supports actors whose role method returns an Array (`roles: ["admin"]` previously stringified and was always denied).
+- **Controllers::Localizable**: regional locales match — `Accept-Language: fr-CA` now tries the full tag before falling back to the primary subtag (previously the region was discarded, so `available: [:"fr-CA"]` could never match).
+- **Controllers::Throttleable**: the first-hit seed uses `unless_exist:` so two concurrent first requests can't under-count the window; a nil/blank discriminator (e.g. `-> { current_user&.id }` on an anonymous request) raises instead of collapsing every client into one shared bucket.
+- **Controllers::Idempotentable**: the 409 conflict's `Retry-After` reports the remaining lock time (from the claim's `claimed_at`) instead of the full `lock_ttl`.
+- **Controllers::Deprecatable**: `link:`/`successor:` values are validated against control characters and `<`/`>` at macro time (Link-header injection).
+- **Support::ColumnGuard** (all 24 model concerns): macros no longer raise when the schema is unreachable — models using these concerns previously could not even load without a migrated database, breaking `db:create`, fresh `db:migrate`, `assets:precompile`, and CI bootstrap. Validation is skipped (never silently for a *reachable* schema with a missing column) and the guard is shared with CounterCacheable/Aliasable/Storable, which had each hand-rolled their own.
+- **Models::Sortable**: a bare `sortable_by` no longer crashes with `NoMethodError` (uses the documented `:position` default); the `default_scope` no longer re-validates the schema on every relation construction; new `default_scope: false` opt-out with a `sorted` scope for explicit ordering.
+- **Models::Monetizable**: the money setter casts garbage input (`"abc"`, `""`) to nil — ActiveModel convention — instead of raising `ArgumentError` out of a form assignment.
+- **Models::Encryptable**: `where_<field>(nil)` / `find_by_<field>(nil)` return `none`/nil instead of matching every row without a fingerprint; encrypted field names now register with Rails' parameter filtering through a live registry + railtie (`before: "active_record.set_filter_attributes"`), so redaction works with boot-time snapshots (ActiveRecord `filter_attributes`, lograge-style initializers) and lazily-loaded model classes.
+- **Models::Sequenceable**: with `reset:` enabled, `created_at` is pinned to the period-anchor instant during `before_create`, so a row can no longer be numbered for one year/month/day but timestamped into the next.
+- **Models::Sluggable**: the slug column itself is validated at macro time (a missing `slug` column previously failed at first save with an opaque friendly_id error).
+- **Models::Schedulable**: `reschedule!` accepts either/both keywords (single-column windows no longer fabricate the missing kwarg) and raises when a value targets an unconfigured column instead of silently dropping it.
+- **Models::CounterCacheable**: `touch: true` raises at macro time on Rails < 6.0 (`update_counters` lacks the option there and would read it as a column named `touch`).
+
+### Changed
+- **Models::SoftDeletable**: `soft_delete_all` / `restore_all` (and the `destroy_all` alias) now return the Integer count of records transitioned and raise `ActiveRecord::RecordNotSaved` (rolling the batch back) when a record fails — previously the rollback happened silently and the methods returned nil/records. With `touch: false` and no overridden hooks both collapse to a single `UPDATE`.
+- **Models::Publishable / Stateable**: lifecycle hooks now share one transaction with the state write (SoftDeletable's pattern) — a raising `after_publish`/`after_transition` rolls the change back instead of leaving it committed with the side effect half-done. `publish_at!` now fires the publish hooks.
+- **Models::Encryptable + Auditable**: the encrypted×audited overlap is rejected at macro time from BOTH declaration orders (Auditable gained the mirror guard); the per-save backstop callback is gone.
+- **Models::Hashable / Tokenizable**: `regenerate_<field>!` goes through the same uniqueness path as create-time assignment (precheck + bounded retry on `ActiveRecord::RecordNotUnique` via the new `Support::UniqueRetry`) — previously one blind `update!` with no collision handling. Hashable's `type: :integer` now generates fixed-width codes (`length: 6` is always 6 digits).
+- **Effective Rails support documented**: the gemspec keeps `rails >= 5.0, < 9`, but Ruby 3.2 (required) means Rails 7.0.4+ in practice; README updated accordingly.
+
+### Performance
+- **Support::Encryptor**: PBKDF2-derived keys are memoized (bounded, mutex-guarded, keyed by digest+salt+iterations) — previously EVERY encrypt/decrypt/blind-index call re-ran the 65,536-iteration KDF, turning a 200-row load of one encrypted column into seconds of key stretching. `configure_encryption` purges the cache.
+- **Models::Storable**: per-record decode memoization — readers/writers/dirty-checks/validation shared one `JSON.parse` per raw column value instead of re-parsing per key access (a ten-key form save cost dozens of parses). Read-back semantics are byte-identical (pinned by spec); the native-hash column detection is now mutex-guarded and never caches a negative result taken without a reachable schema.
+- **Models::Auditable**: saves that touch no tracked field skip building the changes hash (`will_save_change_to_attribute?` pre-check); `audit_trail` is memoized per raw column value (returns a fresh Array each call; entry hashes shared, treat as read-only).
+- **Controllers::Paginatable**: `paginated` + `pagination_meta` (no argument) now share one memoized COUNT — the documented records+meta composition ran the identical COUNT twice. The COUNT also strips `:select` and uses `count(:all)`, so custom SELECT lists and DISTINCT relations no longer produce invalid SQL or skewed totals.
+- **Models::Stateable**: the state default uses `attribute ... default:` instead of an `after_initialize` that ran for every row materialized from the database. (Edge: `Model.new(state_field => nil)` now keeps the explicit nil.)
+- **Models::CounterCacheable**: `recount_counter_caches!` runs in a transaction (a crash mid-repair could previously leave every counter zeroed) and groups parents by tally value — O(distinct counts) UPDATEs instead of one per parent row.
+- **Models::Normalizable / Addressable**: normalization skips fields that are not part of the current save on persisted records; `resolved_country` is memoized per raw value (was computed three times per validation cycle).
+- **Controllers::Localizable / Timezoneable / Deprecatable / CursorPaginatable**: per-request memoization of the resolved locale/zone/deprecation rule; the timezone wrapper is skipped when it would be a no-op; the row-predicate adapter check is cached per model class.
+- **Support::RandomValue / Money**: batched CSPRNG draws with rejection sampling (one `SecureRandom` call per token instead of per character); single-pass thousands delimiter.
+
+### Internal
+- New support modules: `ScalarParam` (shared untrusted-param coercion), `UniqueRetry` (bounded `RecordNotUnique` retry — also usable directly: `UniqueRetry.with_retries { Invoice.create!(attrs) }`), `ErrorEnvelope` (the `render_error`-or-inline dance, previously hand-copied across seven controller concerns — custom `render_error(message:, status:, code:)` overrides keep working), `FilterParameterRegistry` + `ConcernsOnRails::Railtie`.
+- `ConcernsOnRails.deprecator` / `.encryption` / `.filter_parameter_registry` memoization is now thread-safe; every concern file explicitly requires the support modules it uses (files are self-contained under direct `require`).
+- New real-ActionController integration harness (`spec/support/integration_harness.rb`) — the dependency-free FakeController cannot reproduce `ActionController::Parameters` or `rescue_from` semantics, which is how the fixed 500s previously stayed green; regression specs now assert mechanisms (statement counts, parse counts, KDF invocations) through real dispatch.
+
 ## 1.21.1 (2026-07-18)
 
 Blind-index support for Models::Encryptable, making encrypted fields queryable by exact match — the follow-up promised in 1.21.0. 991 examples, 0 failures.

data/README.md

@@ -65,6 +65,9 @@ Article.published.without_deleted.find("hello-world")
 | [🪞 Aliasable](#-aliasable) | Full read / write / query association aliases |
 | [⚙️ Storable](#-storable) | Typed accessors over one JSON column ("store_attribute-lite") |
 | [🧮 CounterCacheable](#-countercacheable) | Conditional denormalized counters ("counter_culture-lite") |
+| [🔏 Encryptable](#-encryptable) | Transparent field encryption (AES-256-GCM) + blind-index lookups |
+| [🕵️ Anonymizable](#-anonymizable) | GDPR right-to-erasure with per-field strategies |
+| [🧬 Duplicable](#-duplicable) | Concern-aware deep copy ("clone this invoice") |
 
 ### 🎮 Controller concerns
 
@@ -91,7 +94,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Twenty-three model concerns + sixteen controller concerns**, all production-ready
+- **Twenty-six model concerns + sixteen controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -104,7 +107,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.11"
+gem "concerns_on_rails", "~> 1.23"
 ```
 
 Or pull the latest from GitHub:
@@ -124,7 +127,7 @@ bundle install
 ## 🧪 Compatibility
 
 - **Ruby**: 3.2+
-- **Rails**: 5.0 through 8.x
+- **Rails**: declared 5.0 through 8.x — in practice the Ruby 3.2 requirement means Rails 7.0.4+ is what can actually install the gem; the test suite runs against Rails 7.1
 
 ---
 
@@ -325,13 +328,17 @@ User.unscoped             # everything (deleted + non-deleted)
 **Bulk operations**
 
 ```ruby
-User.soft_delete_all      # soft-deletes all matching records (explicit — preferred)
-User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility)
-User.really_destroy_all   # hard-deletes all matching records
-User.restore_all          # restores all soft-deleted records
+User.soft_delete_all      # soft-deletes all matching records; returns the count (explicit — preferred)
+User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility; returns a count, not records)
+User.really_destroy_all   # hard-deletes the records matching the CURRENT relation (soft-deleted included)
+User.restore_all          # restores the matching soft-deleted records; returns the count
 ```
 
-All of these run in a transaction, so a raising hook rolls the whole batch back.
+A record that fails to transition raises `ActiveRecord::RecordNotSaved` and rolls the whole
+batch back. With `touch: false` and no overridden hooks, `soft_delete_all` / `restore_all`
+collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-delete
+predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
+relation — purge trash with `User.soft_deleted.delete_all` instead.
 
 **Lifecycle hooks** — override these methods on the model:
 
@@ -1129,6 +1136,99 @@ Counters are adjusted with `update_counters` (a single atomic SQL `COALESCE(col,
 
 ---
 
+## 🔏 Encryptable
+
+Transparent per-field encryption for sensitive columns (SSN, DOB, cards) — AES-256-GCM on stdlib OpenSSL, zero new dependencies. Reads and writes stay plaintext in memory; the DB column holds a versioned, authenticated Base64 envelope.
+
+```ruby
+ConcernsOnRails.configure_encryption { |c| c.key = ENV["ENCRYPTION_KEY"] }
+
+class Patient < ApplicationRecord
+  include ConcernsOnRails::Models::Encryptable
+
+  encryptable :ssn, :notes                 # transparent string encryption
+  encryptable :dob, type: :date            # decrypts back to a Date
+  encryptable :email, blind_index: true    # + a queryable fingerprint column
+end
+
+patient.ssn                          # => "123-45-6789" (plaintext in memory)
+patient.ssn_ciphertext               # => "AQEA..." (what's actually at rest)
+patient.ssn_encrypted?               # => true
+Patient.find_by_email("a@b.com")     # exact-match lookup via the blind index
+Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
+```
+
+**Options** (`encryptable *fields, …`, repeatable): `type:` (cast the decrypted value — `:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`), `key:` (per-field override; a String or lazy Proc), `blind_index:` (`true`, or `{ column:, expression: }` — maintains a deterministic keyed-HMAC companion column, default `<field>_bidx`, for equality lookups; `expression:` normalizes symmetrically on write and query).
+
+**Notes**
+- The declared column must be `text`/binary (it stores an opaque envelope, not the logical type); a blind-index column holds a 64-char hex digest — add an index on it.
+- Ciphertext is non-deterministic (random IV), so `where(ssn: ...)` matches nothing — query through a blind index. `nil` stays `nil`; presence checks work normally.
+- Never `update_column(s)` an encrypted field — that bypasses the type and writes raw plaintext. Declaring a field with both `encryptable` and `auditable_by` raises (either order).
+- Wrong key / tampered ciphertext / malformed envelope raise `Encryption::DecryptionError`. Encrypted field names are auto-registered with Rails' `filter_parameters` (via the gem's railtie), so they're redacted from request logs.
+- Reach for [`lockbox`](https://github.com/ankane/lockbox) or Rails 7+ native `encrypts` when you need key rotation today or Rails-managed key infrastructure (rotation is planned — the envelope already reserves the `key_id` byte).
+
+---
+
+## 🕵️ Anonymizable
+
+Declarative right-to-erasure ("GDPR-lite"): each personal-data field gets an erasure strategy, and `anonymize!` rewrites them all in **one UPDATE** while stamping `anonymized_at`. Completes the sensitive-data suite — Maskable masks *display*, Sanitizable strips *HTML*, Encryptable protects *at rest*; Anonymizable **destroys**.
+
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::Models::Anonymizable
+
+  anonymizable :email, with: :email                 # unique fake address
+  anonymizable :first_name, :last_name, with: :redact
+  anonymizable :ssn, with: :nullify
+  anonymizable :bio, with: ->(value) { value && "removed by user request" }
+end
+
+user.anonymize!                    # hooks + single UPDATE + stamp, in one transaction
+user.anonymized?                   # => true
+User.not_anonymized                # scope (and .anonymized)
+User.where(...).anonymize_all!     # batch; returns the count, skips stamped records
+```
+
+**Strategies** (`with:`): `:nullify`, `:redact` (`"[REDACTED]"`), `:hash` (SHA-256 — deterministic *pseudonymization*, joins keep working), `:email` (random unique `anon-…@anonymized.invalid`, so NOT NULL + unique email columns survive), `:random_hex`, or a callable (`->(value)` / `->(value, record)`). Presets pass `nil` through untouched.
+
+**Options** (repeatable; field rules merge): `stamp:` (default `:anonymized_at`; `false` disables stamping + scopes), `clear_audit_trail:` (default `true` — when an erased field is also `auditable_by`, the trail holding its plaintext history is cleared in the same UPDATE), `prefix:`/`suffix:` (scope names).
+
+**Notes**
+- Deliberately `update_columns`: erasure is never blocked by validations and never runs callbacks that could copy old values elsewhere. Values still serialize through the attribute types, so an `encryptable` field stores a fresh ciphertext envelope — never plaintext.
+- `before_anonymize`/`after_anonymize` hooks run inside the transaction; the record reloads afterwards (erasure is terminal for the instance).
+- `:hash` is pseudonymization — use `:nullify`/`:random_hex` for true erasure. Backups/replicas/logs are out of scope.
+
+---
+
+## 🧬 Duplicable
+
+Concern-aware deep copy — the "clone this invoice / duplicate this template" feature. A bare `dup` copies identity-bearing columns (slug, token, invoice number, audit trail, even `created_at`, which AR preserves on save), so naive copies collide with unique indexes. Duplicable blanks exactly those columns and lets each sibling concern regenerate fresh values on save.
+
+```ruby
+class Invoice < ApplicationRecord
+  include ConcernsOnRails::Models::Duplicable
+
+  has_many :line_items
+  duplicable_by associations: %i[line_items],
+                reset: %i[issued_at],
+                suffix: { title: " (copy)" }
+end
+
+copy = invoice.duplicate                # unsaved deep copy
+copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved children)
+```
+
+**Auto-reset identity columns** (no configuration): `created_at`/`updated_at`, Sluggable slug, Tokenizable/Hashable tokens, Sequenceable sequence + `into:` columns, Auditable trail, SoftDeletable timestamp, Lockable attempts/locked_at. Business state (Publishable, Stateable, …) is a judgment call — list it in `reset:`.
+
+**Associations** (`associations:` allow-list, declared before the macro, validated at macro time): `has_many`/`has_one` children are deep-copied — a child that also includes Duplicable copies via **its own** rules, so nested graphs stay declarative; `has_and_belongs_to_many` re-links the *same* records; `belongs_to` and `has_many :through` are rejected with an explanation.
+
+**Notes**
+- The macro is optional — bare `include` gives `duplicate`/`duplicate!` with the auto resets.
+- Override `on_duplicate(copy)` for custom tweaks; it receives the unsaved copy last.
+- Reach for [`amoeba`](https://github.com/amoeba-rb/amoeba) when you need per-attribute regex/prepend rules or belongs_to graph copying.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1700,6 +1800,8 @@ Both forms reference the same module, so you can freely mix them.
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
 | Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
+| Field encryption with managed key rotation / Rails-native key infrastructure | [`lockbox`](https://github.com/ankane/lockbox) / Rails 7+ native `encrypts` |
+| Deep clone with per-attribute regex/prepend rules or belongs_to graph copying | [`amoeba`](https://github.com/amoeba-rb/amoeba) |
 
 `Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
 
@@ -1711,7 +1813,7 @@ Both forms reference the same module, so you can freely mix them.
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.11.2.gem      # install locally
+gem install ./concerns_on_rails-1.23.0.gem      # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/controllers/authorizable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 
 module ConcernsOnRails
   module Controllers
@@ -54,7 +55,11 @@ module ConcernsOnRails
             # a helper_method (which keeps it private on the instance), so the
             # default public-only check would resolve nil and deny everyone.
             actor = respond_to?(via, true) ? send(via) : nil
-            actor.respond_to?(role_method, true) && wanted.include?(actor.send(role_method).to_s)
+            # Array() handles both a scalar role and an array-valued `roles`
+            # method — pre-1.22 an actor with roles = ["admin"] stringified to
+            # '["admin"]' and was always denied.
+            actor.respond_to?(role_method, true) &&
+              Array(actor.send(role_method)).any? { |role| wanted.include?(role.to_s) }
           end
           add_authorization_rule(check: check, only: only, except: except, status: status, message: message)
         end
@@ -87,13 +92,16 @@ module ConcernsOnRails
         nil
       end
 
-      # Public override point for how a denial is rendered.
+      # Public override point for how a denial is rendered. Fails CLOSED: when
+      # there is no response object to render into, raise — returning nil here
+      # (the pre-1.22 behavior) let the action run unauthorized.
       def authorization_denied(status:, message:)
-        return unless respond_to?(:response) && response
-
-        return render_error(message: message, status: status, code: "forbidden") if respond_to?(:render_error)
+        unless respond_to?(:response) && response
+          raise "ConcernsOnRails::Controllers::Authorizable: denial for '#{authorization_action_name}' " \
+                "could not be rendered (no response object) — refusing to fail open"
+        end
 
-        render json: { success: false, error: { message: message, code: "forbidden" } }, status: status
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: status, code: "forbidden")
       end
 
       private

data/lib/concerns_on_rails/controllers/cacheable.rb

@@ -61,6 +61,13 @@ module ConcernsOnRails
 
       included do
         class_attribute :cacheable_rules, instance_accessor: false, default: []
+        # no_store is applied EARLY as well: rescue_from-rendered errors skip
+        # after_action entirely, and for a no_store endpoint (tokens, PII) even
+        # the error response must not be stored. Positive freshness policies
+        # deliberately do NOT move early — rescued errors already get Rails'
+        # safe `max-age=0, private` default, and emitting `public, max-age` on
+        # a rescued 500 would let shared caches serve the error.
+        prepend_before_action :apply_http_no_store if respond_to?(:prepend_before_action)
         after_action :apply_http_cache_headers
       end
 
@@ -143,12 +150,26 @@ module ConcernsOnRails
         nil
       end
 
+      # Early half of the policy (see the included block): only no_store, and
+      # idempotent with apply_http_cache_headers re-applying it after render.
+      def apply_http_no_store
+        rule = http_cache_rule_for_action
+        return unless rule && rule[:no_store]
+        return unless respond_to?(:response) && response
+
+        response.set_header("Cache-Control", "no-store")
+      end
+
       # Set ETag/Last-Modified validators for the resource, then — for a safe
       # request whose precondition matches — send 304 and return false. Returns
       # true when the client must be sent a fresh body. Mirrors Rails `stale?`.
       def stale_resource?(resource = nil, etag: nil, last_modified: nil)
-        validators = set_cache_validators(resource, etag: etag, last_modified: last_modified)
+        # Unsafe methods get neither a 304 nor validators: a POST response must
+        # not advertise an ETag a client could replay against GET (pre-1.22 the
+        # validators were written before the safe-method check).
         return true unless http_cache_safe_request?
+
+        validators = set_cache_validators(resource, etag: etag, last_modified: last_modified)
         return true unless request_matches_cache?(etag: validators[:etag], last_modified: validators[:last_modified])
 
         http_cache_send_not_modified
@@ -225,13 +246,10 @@ module ConcernsOnRails
       end
 
       def http_cache_send_not_modified
-        response.status = 304 if respond_to?(:response) && response
+        return head(:not_modified) if respond_to?(:head)
 
-        if respond_to?(:head)
-          head :not_modified
-        else
-          render(status: :not_modified)
-        end
+        response.status = 304 if respond_to?(:response) && response
+        render(status: :not_modified)
       end
 
       def http_cache_safe_request?

data/lib/concerns_on_rails/controllers/cursor_paginatable.rb

@@ -1,4 +1,6 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
+require "concerns_on_rails/support/scalar_param"
 require "json"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
@@ -56,6 +58,9 @@ module ConcernsOnRails
       CURSOR_DIRECTIONS = %w[next prev].freeze
       # Adapters whose SQL supports row-value (tuple) comparison: (a, b) > (x, y).
       ROW_PREDICATE_ADAPTERS = /postgres|mysql|trilogy|sqlite/i
+      # Deliberately mutable: memoizes adapter row-predicate support per model
+      # class — stable for the life of the process, benign write race.
+      ROW_PREDICATE_SUPPORT_CACHE = {} # rubocop:disable Style/MutableConstant
 
       # Raised when params[:cursor] is malformed, tampered with, or was minted
       # under a different table/order configuration. Auto-rescued to a 400 when
@@ -195,16 +200,16 @@ module ConcernsOnRails
       # Public override point (mirrors ErrorHandleable's public handlers):
       # delegates to Respondable#render_error when available.
       def render_invalid_cursor(error)
-        return render_error(message: error.message, status: :bad_request, code: "invalid_cursor") if respond_to?(:render_error)
-
-        render json: { success: false, error: { message: error.message, code: "invalid_cursor" } }, status: :bad_request
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: error.message, status: :bad_request, code: "invalid_cursor"
+        )
       end
 
       # Same override contract for unknown ?order= preset names.
       def render_invalid_order_preset(error)
-        return render_error(message: error.message, status: :bad_request, code: "invalid_order_preset") if respond_to?(:render_error)
-
-        render json: { success: false, error: { message: error.message, code: "invalid_order_preset" } }, status: :bad_request
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: error.message, status: :bad_request, code: "invalid_order_preset"
+        )
       end
 
       private
@@ -311,7 +316,9 @@ module ConcernsOnRails
       end
 
       def cursor_per_page(override)
-        requested = (override || params[:per_page]).to_i
+        # ScalarParam: `?per_page[]=50` arrives as an Array and .to_i on it was
+        # a 500 (mirrors Paginatable).
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(override || params[:per_page], default: 0)
         requested = self.class.cursor_paginatable_per_page if requested < 1
         cap = self.class.cursor_paginatable_max_per_page
         cap.positive? ? [requested, cap].min : requested
@@ -462,7 +469,15 @@ module ConcernsOnRails
 
           return true
         end
-        uniform && model.connection.adapter_name.match?(ROW_PREDICATE_ADAPTERS)
+        uniform && cursor_adapter_row_predicate?(model)
+      end
+
+      def cursor_adapter_row_predicate?(model)
+        key = model.name || model.table_name
+        cached = ROW_PREDICATE_SUPPORT_CACHE[key]
+        return cached unless cached.nil?
+
+        ROW_PREDICATE_SUPPORT_CACHE[key] = model.connection.adapter_name.match?(ROW_PREDICATE_ADAPTERS)
       end
 
       def cursor_row_predicate(model, pairs, values)

data/lib/concerns_on_rails/controllers/deprecatable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 require "active_support/notifications"
 require "date"
 require "time"
@@ -122,9 +123,14 @@ module ConcernsOnRails
 
         def validate_deprecation_link!(name, value)
           return if value.nil?
-          return if value.is_a?(String) && !value.strip.empty?
 
-          raise ArgumentError, "#{LABEL}: :#{name} must be a non-blank String"
+          raise ArgumentError, "#{LABEL}: :#{name} must be a non-blank String" unless value.is_a?(String) && !value.strip.empty?
+          return unless value.match?(/[[:cntrl:]<>]/)
+
+          # These values are interpolated into the Link header: a control
+          # character would split the header (response splitting), and <> would
+          # terminate or forge the URI-Reference delimiters.
+          raise ArgumentError, "#{LABEL}: :#{name} must not contain control characters or '<'/'>'"
         end
 
         # Eager parse to a UTC Time. A bare Date (or date-only String) becomes
@@ -194,14 +200,17 @@ module ConcernsOnRails
       private
 
       def deprecation_rule_for_action
-        action = deprecation_action_name
-        return nil unless action
+        # Memoized (nil included) — the before_action plus the two public
+        # predicates each re-scanned the rule list every request.
+        return @deprecation_rule_for_action if defined?(@deprecation_rule_for_action)
 
+        action = deprecation_action_name
         # Last match wins — see the module comment. reverse_each.find returns the
         # most recently declared rule covering this action (catch-all or not).
-        self.class.deprecatable_rules.reverse_each.find do |rule|
-          rule[:actions].empty? || rule[:actions].include?(action)
-        end
+        @deprecation_rule_for_action =
+          action && self.class.deprecatable_rules.reverse_each.find do |rule|
+            rule[:actions].empty? || rule[:actions].include?(action)
+          end
       end
 
       def emit_deprecation_headers(rule)
@@ -238,10 +247,9 @@ module ConcernsOnRails
         return unless deprecation_sunset_reached?(rule)
 
         message = "This endpoint was sunset on #{rule[:sunset_at].httpdate}."
-        return render_error(message: message, status: :gone, code: "endpoint_sunset") if respond_to?(:render_error)
-        return unless respond_to?(:response) && response
+        return unless respond_to?(:render_error) || (respond_to?(:response) && response)
 
-        render json: { success: false, error: { message: message, code: "endpoint_sunset" } }, status: :gone
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: :gone, code: "endpoint_sunset")
       end
 
       # Inclusive: the boundary instant itself counts as sunset.

data/lib/concerns_on_rails/controllers/error_handleable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 
 module ConcernsOnRails
   module Controllers
@@ -64,11 +65,9 @@ module ConcernsOnRails
       private
 
       def render_error_envelope(message:, code:, status:, errors: nil)
-        return render_error(message: message, code: code, status: status, errors: errors) if respond_to?(:render_error)
-
-        error = { message: message, code: code }
-        error[:details] = errors if errors
-        render json: { success: false, error: error }, status: status
+        ConcernsOnRails::Support::ErrorEnvelope.render(
+          self, message: message, code: code, status: status, details: errors
+        )
       end
     end
   end

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/scalar_param"
 
 module ConcernsOnRails
   module Controllers
@@ -70,13 +71,12 @@ module ConcernsOnRails
         end
       end
 
-      # Scalars (and arrays, which AR turns into `IN (...)`) are safe to pass to
-      # .where; a Hash / ActionController::Parameters is not.
+      # Scalars (and arrays of scalars, which AR turns into `IN (...)`) are safe
+      # to pass to .where; a Hash / ActionController::Parameters is not — and
+      # since 1.22 neither is an array CONTAINING one (`?status[][x]=1` used to
+      # slip through as [Parameters] and 500 with a TypeError).
       def filterable_scalar?(value)
-        return false if value.is_a?(Hash)
-        return false if defined?(ActionController::Parameters) && value.is_a?(ActionController::Parameters)
-
-        true
+        ConcernsOnRails::Support::ScalarParam.where_safe?(value)
       end
     end
   end

data/lib/concerns_on_rails/controllers/idempotentable.rb

@@ -1,4 +1,5 @@
 require "active_support/concern"
+require "concerns_on_rails/support/error_envelope"
 require "digest"
 require "json"
 
@@ -136,9 +137,7 @@ module ConcernsOnRails
       def idempotency_error_response(message:, status:, code:)
         return unless respond_to?(:response) && response
 
-        return render_error(message: message, status: status, code: code) if respond_to?(:render_error)
-
-        render json: { success: false, error: { message: message, code: code } }, status: status
+        ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: status, code: code)
       end
 
       private
@@ -209,15 +208,25 @@ module ConcernsOnRails
 
         # In flight — or the claim expired between our failed write and this
         # read (rare); answering 409 is the conservative, retry-safe choice.
-        idempotency_conflict_response(rule)
+        idempotency_conflict_response(rule, record)
       end
 
-      def idempotency_conflict_response(rule)
-        response.set_header("Retry-After", rule[:lock_ttl].to_s) if respond_to?(:response) && response
+      def idempotency_conflict_response(rule, record = nil)
+        response.set_header("Retry-After", idempotency_retry_after(rule, record).to_s) if respond_to?(:response) && response
         idempotency_error_response(message: "A request with this #{rule[:header]} is already in progress.",
                                    status: :conflict, code: "idempotency_conflict")
       end
 
+      # Remaining lock time (floored at 1s), not the full lock TTL — the claim
+      # record carries when it was taken, so clients don't back off for a lock
+      # that is about to expire.
+      def idempotency_retry_after(rule, record)
+        claimed_at = record.is_a?(Hash) ? record["claimed_at"] : nil
+        return rule[:lock_ttl] unless claimed_at
+
+        [rule[:lock_ttl] - (Time.now.to_i - claimed_at.to_i), 1].max
+      end
+
       def read_idempotency_header(rule)
         return nil unless respond_to?(:request) && request.respond_to?(:headers) && request.headers
 

data/lib/concerns_on_rails/controllers/includable.rb

@@ -65,7 +65,11 @@ module ConcernsOnRails
         return {} unless raw.respond_to?(:each_pair)
 
         allowed = self.class.includable_fields
-        raw.each_with_object({}) do |(table, cols), memo|
+        # Iterate via each_pair: in a real controller `raw` is an
+        # ActionController::Parameters, which has each_pair but no Enumerable —
+        # calling each_with_object directly on it was a guaranteed
+        # NoMethodError 500 for every ?fields[...]= request.
+        raw.each_pair.with_object({}) do |(table, cols), memo|
           key = table.to_sym
           next unless allowed.key?(key)