concerns_on_rails 1.28.3 → 1.28.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3f06aad189272886038354ad98dfd58a84642d64e1313c4aac5d88e7d1ec90a
-  data.tar.gz: b38acca4cb5cd6a48496d0d4909da90782c14b6b71748af88b72df482a02ef62
+  metadata.gz: 5c6fcd158fd0dce6d1744e9ad6be5d921bf283e921e717a8327f04f53e8668f4
+  data.tar.gz: fe3b93a06be3a0cbb4b0e1904a976393b77d24c4075f1d8dccb98e13d3ac6597
 SHA512:
-  metadata.gz: 98d77a84da148195bdd1c013054b12bd3b8c4f6ce2bf5b7ae8ee7e91c0a24b4d5d45e6540c139456e1d51b91afbfaed5cf68d9faf9859399cb4ec2b76ccdd90b
-  data.tar.gz: 6852cb66a64150139c9625d765cd3f724881a6b35a9e5920140713c21b69f148c956353d587765f3ad1eca6018b38de70b98aa8aa9c40006ad0a6919242607c8
+  metadata.gz: 1a113631bd4810decc66aad97ba5fc9fe8866d92dcfd1ab1908c2cdafe7e990e961c3655933ad124ae8275f1a199c4275a7ba72a06cc172ecf248e2825eb42de
+  data.tar.gz: 7102f8a5cb83e21eabe46066f7a62956adf0950dbe926dc8706c9abd217a87577b6004d625c71d179dc2cf4083dc7fdefd25b47883e1a085fee1ec5bb691b41c

data/CHANGELOG.md

@@ -1,5 +1,173 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.5 (2026-09-17)
+
+Eight feature PRs deepening existing concerns, released as a patch by request:
+no new concerns and no dependency changes, though several add an optional
+column or option. Every PR was reviewed before merge and carries the review's
+fixes; the notes below call out the ones that change a documented behaviour.
+1522 examples, 0 failures.
+
+### Added
+- **Models::Schedulable**: `overlapping(from, to)` scope and `overlaps?`
+  predicate for booking-clash checks. Open-ended windows (a `NULL` start or
+  end), touching intervals, reversed arguments and Range forms behave
+  identically in SQL and in Ruby. Affixable like the other scopes. (#58)
+- **Models::Duplicable**: per-call `only:` / `except:` association selection —
+  `invoice.duplicate!(except: :line_items)`. The macro's list stays the
+  ceiling, so a controller param cannot smuggle in an undeclared association.
+  An explicit `nil` counts as passed, not absent, so an empty checkbox list
+  copies nothing rather than everything. (#73)
+- **Models::Monetizable**: scope-aware `sum_`, `average_`, `minimum_` and
+  `maximum_<name>` aggregates plus their `formatted_` twins, with per-call
+  formatting overrides. BigDecimal throughout; a grouped relation returns a
+  Hash of converted values instead of raising. (#67)
+- **Models::Taggable**: `tag_counts` — tag to record count in one `GROUP BY`
+  query, relation-aware, with `limit:` for the top N. A `select`, `group` or
+  `order` on the relation is stripped; a `limit`/`offset` window is honoured by
+  resolving it to ids first. (#56)
+- **Models::Expirable**: `before_expire` / `after_expire` lifecycle hooks,
+  `expire_in!(duration)` and `clear_expiry!`. The hooks fire when a write
+  actually expires the record; a future time only schedules expiry and fires
+  nothing, so `after_expire { account.downgrade! }` is safe next to
+  `trial.expire_in!(14.days)`. Overriding either hook moves `expire_all` to the
+  per-record path. (#54)
+- **Controllers::SecureHeadable**: HSTS, cross-origin (COOP/COEP/CORP) and
+  Permissions-Policy presets, plus the `:recommended` and
+  `:cross_origin_isolation` bundles. `:recommended` uses `(self)`-scoped
+  permission values, so it denies third-party frames without disabling the
+  app's own camera, microphone, geolocation or Payment Request. HSTS is skipped
+  on a plaintext request (RFC 6797 §7.2) and never overwrites a stricter value
+  already on the response. (#55)
+- **Models::Addressable**: `address_fingerprint` (SHA-256 of the normalized
+  address), `same_address_as?`, `address_parts_changed?` and a `fingerprint:`
+  column option with a `with_address` finder for deduplication reports. The
+  column is stamped in `before_save`, after every `before_validation`, so a
+  sibling concern rewriting a mapped column cannot desync it. (#79)
+- **Controllers::Localizable**: `Content-Language` response header and
+  `Vary: Accept-Language`, both written before the action so a
+  `rescue_from`-rendered error carries them. Rails' own `Vary: Accept` is
+  preserved rather than suppressed, and `Vary` is advertised only when
+  `Accept-Language` can actually change the resolved locale. (#53)
+
+### Notes
+- **Addressable** defines `address_changed?` only when the model has no
+  `address` column of its own, so it never shadows ActiveModel's dirty
+  predicate; `address_parts_changed?` is always available.
+- Existing rows keep a `NULL` address fingerprint until they are re-saved.
+  Backfill with `Model.find_each(&:save)`; `update_columns`, `insert_all` and
+  `upsert_all` bypass callbacks and leave it stale.
+- The address digest is unkeyed, so treat the column as revealing the address.
+  Do not pair it with an `encryptable` address column.
+
+## 1.28.4 (2026-09-16)
+
+Eleven bug-fix PRs (#91–#101) from the audit of the shipped gem, released as a
+patch: no new concerns, no new options, no migrations, no dependency changes.
+Two close fail-open holes (WebhookVerifiable, Encryptable); the rest are
+correctness fixes for behaviour the docs already promised. Every fix ships with
+a regression spec that fails on 1.28.3. 1460 examples, 0 failures.
+
+### Security
+- **Controllers::WebhookVerifiable**: verification could be skipped entirely,
+  leaving the action to run on an unverified — possibly forged — payload. Two
+  paths: `webhook_verification_failed` returned `nil` when there was no response
+  object to render into, which left the `before_action` chain unhalted; and
+  `webhook_rule_for_action` returned `nil` (read as "no rule applies, carry on")
+  when `action_name` was unresolvable or `""`. Both fail closed now — the first
+  raises, the second falls back to the catch-all rule, or to a lone declared
+  rule, and verifies. With several action-specific rules and no catch-all it
+  raises rather than verifying against an arbitrary provider's secret, which
+  would reject a valid delivery as "signature invalid". The render guard also
+  honours a `render_error` override on its own, so a controller supplying one
+  but no response object renders its rejection instead of raising. Mirrors the
+  fix Authorizable got in 1.22. A resolvable action simply not covered by any
+  rule still passes through untouched. (#92)
+- **Models::Encryptable**: `<field>_ciphertext` — documented for "asserting no
+  plaintext is at rest" — returned the caller's **plaintext** whenever the value
+  had not round-tripped through the database (a new record, or any pending
+  assignment: exactly the state inside a `before_save`, a validator, or an
+  error-reporting path), so `log.info(user.ssn_ciphertext)` wrote the SSN
+  straight to the log. It returns `nil` in that state now. `<field>_encrypted?`
+  used a bare `.present?`, true for plaintext too; it now checks that what is
+  stored really is an encryption envelope, via the new
+  `Support::Encryptor.envelope?`. (#97)
+
+### Fixed
+- **Models::Aliasable**: an aliased `belongs_to` carrying `counter_cache:`
+  double-counted. The alias copy kept the `:counter_cache` option, and because
+  the `#association` override maps the alias back to the same association
+  object, ActiveRecord's counter-cache pass fired once per name — the parent's
+  count came out doubled on create and doubled on destroy, drifting permanently
+  negative once rows predating the alias were removed. The copy no longer
+  carries the option; the source reflection still owns the counter. (#93)
+- **Controllers::Paginatable**: `?page=99999999999999999999` was an
+  unauthenticated 500 — `(page - 1) * per_page` produced an offset no backend
+  accepts (`StatementInvalid` on a relation, `RangeError` on an Array). `page`
+  is now clamped to `MAX_PAGE` (1,000,000) and comes back as an empty page past
+  the end; `per_page` is held under the matching `MAX_PER_PAGE`, since with
+  `max_per_page: 0` ("no cap") the identical value overflowed `LIMIT` instead.
+  `paginate_by` also validates `per_page` now: 0 and negatives raise
+  `ArgumentError` at class-load time instead of misbehaving on every request
+  (`per_page: -1` means `LIMIT -1`, i.e. NO LIMIT on SQLite and MySQL —
+  serialising the whole table; `per_page: 0` made every page permanently empty).
+  A negative `max_per_page` still means "no cap", as documented. (#94)
+- **Models::Taggable**: `all_tags` raised on PostgreSQL for any model that also
+  includes `Models::Sortable` — `SELECT DISTINCT` cannot be ordered by a column
+  outside the select list, and Sortable installs exactly such a `default_scope`.
+  The inherited `ORDER BY` is dropped with `reorder(nil)`; the result is sorted
+  in Ruby anyway. Passed on SQLite, which permits it. (#95)
+- **Models::Lockable, Models::Stateable**: `ActiveRecord::Rollback` raised from
+  an `after_lock` / `after_transition` hook did nothing when the call was nested
+  inside a caller's own transaction — a bare `transaction` joins the enclosing
+  one and Rails swallows `Rollback` without rolling anything back. Both open a
+  savepoint now (`requires_new: true`), so the documented abort works: Lockable
+  no longer leaves a row locked in the database while reporting `false` in
+  memory (with `lock_access!`'s idempotency guard then making every retry a
+  no-op), and Stateable no longer commits a state change its hook asked to
+  abort. Stateable's `<event>!` also took its return value from `update!`, which
+  runs *before* the hook, so an aborted transition reported success —
+  `raise unless ticket.archive!` never fired and `transition_all` counted a row
+  it had rolled back. It reports `false` now, which `transition_all` treats as
+  the documented failed-record signal. Note `transition_all` opens one savepoint
+  per record. (#96)
+- **Support::ErrorEnvelope**: the `render_error` lookup was public-only, but
+  `render_error` is very often declared under `private` — the idiomatic way to
+  keep a controller helper from becoming a routable action. Those overrides were
+  silently ignored and the gem's inline envelope rendered instead, so an app
+  rendering RFC 9457 problem+json got the wrong shape for every Authorizable
+  403, WebhookVerifiable 401, Throttleable 429 and CursorPaginatable 400, with
+  no error or warning. Now `respond_to?(:render_error, true)`, the spelling
+  Authorizable already used for `current_user`. Controllers::Deprecatable keeps
+  its own copy of that check before rendering a sunset 410, and it had the same
+  blind spot — a private `render_error` with no response object skipped the 410
+  and served the sunset action. (#98)
+- **Controllers::Deprecatable**: `deprecate_actions` mutated the caller's own
+  `Time`. `Time#utc` is an alias of `#gmtime` and converts the receiver IN
+  PLACE, so a host passing a frozen constant (`SUNSET = Time.new(...).freeze`)
+  got a `FrozenError` while the controller class body was still loading — the
+  app would not boot — and an unfrozen `Time` was silently rewritten to UTC
+  behind the caller's back. Now `getutc`. (#99)
+- **Controllers::Filterable**: a boolean `false` read as "filter not supplied",
+  so `filter_by :active` could never select the inactive rows — `false.blank?`
+  is true, the rule was skipped and the UNFILTERED relation came back. Only JSON
+  request bodies were affected; a query string carries the String `"false"`,
+  which is not blank. Everything genuinely empty — `nil`, `""`, `"   "`, `[]`,
+  `{}` — is still skipped, and in `scope:` mode (which discards the value) an
+  explicit `false` still means "do not apply this scope". (#100)
+- **Models::Stateable**: `transition_all` silently skipped rows whose state is
+  NULL. `where.not(state: to)` compiles to `NOT (state = 'x')`, which SQL
+  three-valued logic evaluates to NULL — never TRUE — for a NULL state, so those
+  rows were dropped from the batch and from the returned count even though they
+  ARE eligible (`may_<event>?` returns true for them and the per-record
+  `<event>!` succeeds). The predicate is NULL-safe now. (#101)
+
+### Internal
+- **Specs**: the Aliasable join-alias SQL assertion accepts both the Rails 8.1
+  `AS`-qualified table alias and the older unqualified form, so the suite passes
+  on Rails 8.1 — unblocking the pending Rails 8.1 dependency bumps. No library
+  change. (#91)
+
 ## 1.28.3 (2026-09-16)
 
 Three merged PRs from the September loop (#41, #43, #52), shipped as a patch at

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,396 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,522 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -601,6 +601,9 @@ Promotion.current                    # WHERE starts_at <= NOW AND (ends_at IS NU
 Promotion.upcoming                   # WHERE starts_at > NOW
 Promotion.expired                    # WHERE ends_at <= NOW
 Promotion.active_at(time)            # active at an arbitrary time
+Promotion.overlapping(from, to)      # windows intersecting [from, to) — clashing bookings, a calendar page
+Promotion.overlapping(from..to)      # Range form; `..` makes the end inclusive; nil on either side = unbounded
+promo.overlaps?(from, to)            # the instance-side predicate
 ```
 
 **Configuration**
@@ -667,13 +670,21 @@ ApiToken.expiring_within(1.day)  # future expiry within the next 1 day
 ```ruby
 token.expire!                       # expires_at = now
 token.expire!(2.hours.from_now)     # explicit time
+token.expire_in!(15.minutes)        # absolute lifetime from now, whatever the current expiry
 token.extend_expiry!(by: 1.day)     # pushes expiry forward
+token.clear_expiry!                 # never expires (nil)
 ```
 
 `extend_expiry!` is smart about the base:
 - If `expires_at` is `nil` or in the past → new value is `now + by`
 - If `expires_at` is still in the future → `by` is added to the existing value
 
+**Lifecycle hooks** — override `before_expire` / `after_expire` on the model; they fire around a write that
+actually expires the record (`expire!` with a past-or-now time, and `expire_all`) inside one transaction, so
+a raising `after_expire` rolls the expiry back. A future time only *schedules* expiry, so `expire_in!(14.days)`
+fires nothing — as with renewals (`extend_expiry!`) and `clear_expiry!`. Overriding either hook moves
+`expire_all` from its single `UPDATE` to the per-record path so the hooks run for every row.
+
 **Bulk operations**
 
 ```ruby
@@ -681,7 +692,7 @@ ApiToken.expiring_within(1.day).expire_all   # => 12
 ```
 
 `expire_all(time = Time.zone.now)` expires every currently-active record in the relation and
-returns the Integer count, in a transaction. With `expire!` unoverridden and no validations on
+returns the Integer count, in a transaction. With `expire!` and both hooks unoverridden and no validations on
 the model — neither `validates`/`validates_with`, a custom `validate :method`, nor an
 association's autosave validation (a bare `has_many` registers one, so most models with
 associations take the streaming path) — it collapses
@@ -1042,6 +1053,7 @@ end
 | `allow_blank:`    | `false`                              | Per-field opt-out for the length check: an Array of parts (e.g. `%i[line2 state]`), or `true` for all parts. A blank value for an allowed part skips its length check. Independent of `required:`. |
 | `normalize_country:` | `false`                           | When `true`, canonicalize the country to its ISO 3166-1 alpha-2 code: an English name (`"Canada"`, `"United States"`) or a 3-letter alpha-3 (`"CAN"`, `"USA"`) maps to the alpha-2 (`"CA"`, `"US"`); unrecognized values are left untouched. This also lets postal/state validation recognize a named country. |
 | `verify_with:`    | `nil`                                | A callable for real-world verification (see below).                 |
+| `fingerprint:`    | `nil`                                | A `string` column to store `address_fingerprint` in (stamped in `before_validation`, after normalization) so duplicates are one indexed query away: `Location.with_address(record)`. |
 | `if:` / `unless:` | `nil`                                | Standard Rails validation conditions (Symbol, Proc, or Array) gating the address **validations** — e.g. `if: :on_addresses?`. Normalization still runs unconditionally. |
 
 **What it normalizes** (in `before_validation`)
@@ -1065,6 +1077,18 @@ end
 | `String`          | added as a `:base` error                        |
 | `Array`           | each element added as a `:base` error           |
 
+**Dedupe helpers**
+
+```ruby
+loc.address_fingerprint        # => "9f2c…" — SHA-256 of the normalized parts: case, whitespace, postal spacing
+                               #    and a blank country (→ default_country) don't change it; nil for a blank address
+loc.same_address_as?(other)    # fingerprints equal (never true for two blanks)
+loc.address_changed?           # any mapped column dirty (address_parts_changed? when you have an `address` column)
+
+addressable_by fingerprint: :address_fingerprint     # add a string column + index
+Location.with_address(loc).where.not(id: loc.id)     # the duplicates of loc (or pass a fingerprint)
+```
+
 **Notes**
 - Scope is **format/structure only** — it checks shape, not real-world deliverability. Plug a USPS/Google/Smarty client into `verify_with:` for that.
 - Error messages are plain English strings — no host-app i18n setup required.
@@ -1096,6 +1120,7 @@ article.save!
 Article.tagged_with("ruby", "rails")          # records carrying BOTH tags
 Article.tagged_with("ruby", "go", any: true)  # records carrying ANY tag
 Article.all_tags                               # => sorted unique tags in use
+Article.published.tag_counts(limit: 20)        # => { "ruby" => 12, "rails" => 7, ... } — a tag cloud, relation-aware
 ```
 
 **Options**
@@ -1108,7 +1133,8 @@ Article.all_tags                               # => sorted unique tags in use
 **Notes**
 - Matching is **boundary-safe** — searching `rail` does not match `rails`. An explicit SQL `ESCAPE` clause makes tags containing `_` / `%` match literally on every adapter.
 - Tags are normalized in `before_validation`, so a direct `record.tags = "a, b"` assignment is cleaned too. An empty list stores `NULL`.
-- Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, counts/clouds, or polymorphic tags shared across models.
+- `tag_counts` runs one `GROUP BY` on the raw column — identical tag strings ship once with their row count and are split in Ruby — so it scales with distinct tag strings, not rows; ordered by count desc then name, `limit:` keeps the top N.
+- Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, or polymorphic tags shared across models.
 
 ---
 
@@ -1206,9 +1232,17 @@ product.formatted_price # => "$19.99"
 |-------------------|-----------------------------------------------|
 | `price`           | the amount as a `BigDecimal` (cents ÷ 100)    |
 | `price=`          | assign in major units; rounded to whole cents |
-| `formatted_price` | a display string (`"$1,234.56"`)              |
+| `formatted_price` | a display string (`"$1,234.56"`); accepts per-call overrides: `formatted_price(unit: "€", delimiter: ".", separator: ",")` |
 
-**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all three methods.
+**Aggregates** — class methods that follow the current scope, exact and float-free:
+
+```ruby
+Product.sum_price                      # => BigDecimal   SUM(price_cents) / 100
+Product.in_stock.average_price         # average_ / minimum_ / maximum_ too — nil on an empty set (sum is 0)
+Order.paid.formatted_sum_total         # => "€3.500,50"  every aggregate has a formatted_ twin (overrides accepted)
+```
+
+**Options**: `as:` (explicit method name — required when the column does not end in `_cents`), `unit:` (`"$"`), `precision:` (`2`), `delimiter:` (`","`), `separator:` (`"."`), `subunit_to_unit:` (`100`). `nil` stays `nil` across all the accessors.
 
 ---
 
@@ -1417,6 +1451,7 @@ Patient.where_email("a@b.com")       # chainable Relation (accepts arrays too)
 **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.
+- `ssn_ciphertext` is `nil` while the field has an unsaved change (so it can never return the plaintext you just assigned), and `ssn_encrypted?` asks whether what is stored really is an envelope.
 - 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).
@@ -1470,6 +1505,8 @@ end
 
 copy = invoice.duplicate                # unsaved deep copy
 copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved children)
+copy = invoice.duplicate!(except: :line_items)          # this copy skips the line items
+copy = invoice.duplicate!(only: [])                     # shallow copy — attributes only
 ```
 
 **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:`.
@@ -1478,6 +1515,7 @@ copy = invoice.duplicate!(title: "Q3")  # saved (one transaction, autosaved chil
 
 **Notes**
 - The macro is optional — bare `include` gives `duplicate`/`duplicate!` with the auto resets.
+- `only:` / `except:` on `duplicate` / `duplicate!` pick which of the declared associations this particular copy carries ("Duplicate with line items?" checkbox); names outside the allow-list raise. They are reserved keys — pass overrides for attributes literally named `only`/`except` as a braced Hash.
 - 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.
 
@@ -1867,6 +1905,9 @@ class ApplicationController < ActionController::Base
   # Preset headers, plus any custom "Header-Name" => "value" pairs:
   secure_headers :nosniff, :sameorigin_frame, :no_referrer_leak, :disable_legacy_xss
   secure_headers "Permissions-Policy" => "geolocation=()"
+  # ...or the break-nothing baseline in one line, then relax what you must (later wins):
+  secure_headers :recommended
+  secure_headers :sameorigin_frame
 
   # Delegates to Rails' native CSP DSL — roll out report-only FIRST:
   content_security_policy_for(report_only: true) do |policy|
@@ -1887,6 +1928,14 @@ end
 | `:no_referrer_leak`   | `Referrer-Policy: strict-origin-when-cross-origin`     |
 | `:no_cross_domain`    | `X-Permitted-Cross-Domain-Policies: none`              |
 | `:disable_legacy_xss` | `X-XSS-Protection: 0` (the only correct modern value)  |
+| `:hsts`               | `Strict-Transport-Security: max-age=31536000; includeSubDomains` (no `preload` — opt in via a custom pair) |
+| `:same_origin_opener` / `:same_origin_opener_allow_popups` | `Cross-Origin-Opener-Policy: same-origin` / `same-origin-allow-popups` |
+| `:require_corp_embedder` | `Cross-Origin-Embedder-Policy: require-corp`        |
+| `:same_origin_resource` | `Cross-Origin-Resource-Policy: same-origin`          |
+| `:no_sensitive_permissions` | `Permissions-Policy` denying camera, microphone, geolocation, payment, usb and motion sensors to everyone, your own pages included |
+| `:self_sensitive_permissions` | The same list scoped to `(self)` — denies third-party frames, keeps first-party use |
+
+**Bundles** (expand to presets in place, so a later preset or custom pair still wins): `:recommended` = nosniff, deny_frame, no_referrer_leak, no_cross_domain, disable_legacy_xss, same_origin_opener_allow_popups, self_sensitive_permissions — deliberately *without* COEP/CORP (they block cross-origin embeds of your resources and CDN assets lacking CORP headers) and HSTS (belongs with `force_ssl`); relax `deny_frame` with `:sameorigin_frame` if the app frames itself; `:cross_origin_isolation` = same_origin_opener + require_corp_embedder + same_origin_resource (what SharedArrayBuffer / high-resolution timers require).
 
 **Notes**
 - Headers are applied in an `after_action`, so they reinforce Rails' middleware defaults; later `secure_headers` declarations win on a colliding name.
@@ -1911,7 +1960,9 @@ end
 
 Resolution order: `params[param]` → first match in `Accept-Language` → `default` → `I18n.default_locale`. The chosen locale is always validated against `I18n.available_locales`, so a stray param or a mismatched `available:` list can never raise `I18n::InvalidLocale`.
 
-**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`).
+Every response carries **`Content-Language: <resolved locale>`** (BCP 47 form — `pt_BR` → `pt-BR`) and, when `Accept-Language` is a locale source, **`Vary: Accept-Language`** appended to any existing `Vary` (de-duplicated) so shared caches key on the header. Both are written *before* the action runs, so a `rescue_from`-rendered error still carries them; `response_headers: false` turns them off.
+
+**Options**: `available:` (allow-list for matching; defaults to `I18n.available_locales`), `default:`, `param:` (default `:locale`), `header:` (default `true`), `response_headers:` (default `true`).
 
 ---
 
@@ -2249,9 +2300,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,396 examples)
+bundle exec rspec                               # run the test suite (1,522 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.3.gem      # install locally
+gem install ./concerns_on_rails-1.28.5.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/deprecatable.rb

@@ -141,8 +141,15 @@ module ConcernsOnRails
           # Module#=== checks the real ancestry, so `when Time` alone would
           # miss it — and Time.current / 1.month.from_now are exactly the
           # values Rails hosts pass.
-          when ActiveSupport::TimeWithZone, Time then value.utc
-          when DateTime then value.to_time.utc
+          # getutc, NOT utc: Time#utc is an alias of #gmtime, which converts the
+          # receiver IN PLACE and returns self. A host passing a frozen
+          # constant (SUNSET = Time.new(...).freeze) got a FrozenError while
+          # the controller class body was still loading — the app would not
+          # boot — and an unfrozen Time was silently rewritten to UTC behind
+          # the caller's back. TimeWithZone#utc is a harmless reader, but
+          # getutc is correct for both, so the branch stays single.
+          when ActiveSupport::TimeWithZone, Time then value.getutc
+          when DateTime then value.to_time.getutc
           when Date then Time.utc(value.year, value.month, value.day)
           when String then parse_deprecation_string(value)
           end
@@ -247,7 +254,12 @@ module ConcernsOnRails
         return unless deprecation_sunset_reached?(rule)
 
         message = "This endpoint was sunset on #{rule[:sunset_at].httpdate}."
-        return unless respond_to?(:render_error) || (respond_to?(:response) && response)
+        # respond_to?(..., true) for the same reason Support::ErrorEnvelope
+        # uses it: render_error is very often declared under `private`. The
+        # public-only check skipped the 410 for exactly those controllers and
+        # let the sunset action run — a fail-open on the branch whose job is to
+        # stop serving the endpoint.
+        return unless respond_to?(:render_error, true) || (respond_to?(:response) && response)
 
         ConcernsOnRails::Support::ErrorEnvelope.render(self, message: message, status: :gone, code: "endpoint_sunset")
       end

data/lib/concerns_on_rails/controllers/filterable.rb

@@ -42,12 +42,12 @@ module ConcernsOnRails
         end
       end
 
-      # Apply all declared filters to a relation based on params. Blank values
-      # are skipped so unset filters don't narrow the relation.
+      # Apply all declared filters to a relation based on params. Unset values
+      # are skipped so absent filters don't narrow the relation.
       def filtered(relation)
         self.class.filterable_rules.each do |field, options|
           value = params[field]
-          next if value.blank?
+          next if filterable_unset?(value)
 
           relation = apply_filter(relation, field, value, options)
         end
@@ -56,11 +56,29 @@ module ConcernsOnRails
 
       private
 
+      # NOT `value.blank?`: `false.blank?` is true, so a genuine boolean false
+      # read as "filter not supplied" and the relation came back UNFILTERED —
+      # `filter_by :active` could never select the inactive rows. Query strings
+      # were unaffected (they carry the String "false", which is not blank), so
+      # this only bit JSON request bodies, where the value really is `false`.
+      # Everything actually empty — nil, "", "   ", [], {} — is still skipped.
+      def filterable_unset?(value)
+        return false if value == false
+        return true if value.nil?
+
+        value.respond_to?(:blank?) ? value.blank? : false
+      end
+
       def apply_filter(relation, field, value, options)
         if options[:with]
           options[:with].call(relation, value)
         elsif options[:scope]
-          relation.public_send(options[:scope])
+          # Scope mode discards the value, so an explicit `false` can only mean
+          # "do not apply this scope" — applying it would hand the client the
+          # exact opposite of what it asked for. (A query string still carries
+          # the String "false", which has always triggered the scope; only a
+          # real boolean is read as a negation.)
+          value == false ? relation : relation.public_send(options[:scope])
         elsif filterable_scalar?(value)
           relation.where(field => value)
         else

data/lib/concerns_on_rails/controllers/localizable.rb

@@ -18,9 +18,15 @@ module ConcernsOnRails
     # against `I18n.available_locales` before use, so a stray param or a
     # mismatched `available:` list can never raise `I18n::InvalidLocale`.
     #
+    # Every response carries `Content-Language: <resolved locale>` (BCP 47
+    # form, `pt_BR` → `pt-BR`) and, when the header is a locale source,
+    # `Vary: Accept-Language` appended to any existing Vary — written before
+    # the action runs, so a rescued error still carries them. Both are behind
+    # `response_headers:` (default `true`).
+    #
     # Options: `available:` (allow-list for param/header matching; defaults to
     # `I18n.available_locales`), `default:`, `param:` (default `:locale`),
-    # `header:` (default `true`).
+    # `header:` (default `true`), `response_headers:` (default `true`).
     module Localizable
       extend ActiveSupport::Concern
 
@@ -30,19 +36,23 @@ module ConcernsOnRails
       end
 
       class_methods do
-        def localizable(available: nil, default: nil, param: :locale, header: true)
+        def localizable(available: nil, default: nil, param: :locale, header: true, response_headers: true)
           self.localizable_options = {
             available: available&.map(&:to_sym),
             default: default&.to_sym,
             param: param&.to_sym,
-            header: header
+            header: header,
+            response_headers: response_headers ? true : false
           }
         end
       end
 
-      # Public so subclasses can override; runs the action under the resolved locale.
+      # Public so subclasses can override; writes the response headers, then
+      # runs the action under the resolved locale.
       def switch_locale(&)
-        I18n.with_locale(resolved_locale, &)
+        locale = resolved_locale
+        apply_locale_response_headers(locale)
+        I18n.with_locale(locale, &)
       end
 
       # The locale chosen for this request — always one I18n can switch to.
@@ -60,6 +70,49 @@ module ConcernsOnRails
 
       private
 
+      # Content-Language always; Vary: Accept-Language only when the header can
+      # influence the choice (a param-only setup already differs by URL).
+      # Vary is appended and de-duplicated, never clobbered (Cacheable, the
+      # paginators' Link header — same rule).
+      def apply_locale_response_headers(locale)
+        return unless locale_response_headers?
+
+        response.set_header("Content-Language", locale.to_s.tr("_", "-"))
+        # Only advertise the dimension the resolver actually consults: with
+        # `header: false` (or no `localizable` call at all) Accept-Language
+        # cannot change the answer.
+        append_vary_accept_language if self.class.localizable_options[:header]
+      end
+
+      def locale_response_headers?
+        opts = self.class.localizable_options
+        return false if opts.key?(:response_headers) && !opts[:response_headers]
+
+        respond_to?(:response) && response.respond_to?(:set_header)
+      end
+
+      def append_vary_accept_language
+        existing = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+        return if existing.include?("*")
+
+        # Rails adds its own `Vary: Accept` during render, but ONLY while the
+        # header is still blank (ActionController::Rendering#_set_vary_header).
+        # Writing ours before the action would therefore SUPPRESS it and cost a
+        # cache dimension, so seed Accept ourselves whenever Rails would have.
+        merged = existing + vary_accept_dimension + ["Accept-Language"]
+        deduped = merged.each_with_object([]) do |value, list|
+          list << value unless list.any? { |seen| seen.casecmp?(value) }
+        end
+        response.set_header("Vary", deduped.join(", "))
+      end
+
+      def vary_accept_dimension
+        return [] unless respond_to?(:request, true) && (req = request)
+        return [] unless req.respond_to?(:should_apply_vary_header?) && req.should_apply_vary_header?
+
+        ["Accept"]
+      end
+
       def locale_from_param(opts, allowed)
         return nil unless opts[:param] && respond_to?(:params) && params
 

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -36,6 +36,21 @@ module ConcernsOnRails
       LABEL = "ConcernsOnRails::Controllers::Paginatable".freeze
       DEFAULT_PER_PAGE = 25
       DEFAULT_MAX_PER_PAGE = 200
+      # Upper bound on the requested page. `page` is untrusted input and its
+      # only job is to become `(page - 1) * per_page`, so an unbounded value
+      # produced an offset no backend can take: the relation branch raised
+      # StatementInvalid and Array#[] raised RangeError ("bignum too big to
+      # convert into `long'") — a 500 from `?page=99999999999999999999`.
+      # Clamping keeps the request in range; the page is far past any real
+      # dataset, so it simply comes back empty. Deep pagination at this depth
+      # wants Controllers::CursorPaginatable instead.
+      MAX_PAGE = 1_000_000
+      # The same guard for per_page. `max_per_page: 0` is documented as "no
+      # cap", and with no cap the identical untrusted value overflowed LIMIT
+      # instead of OFFSET — the same unauthenticated 500, one option away. "No
+      # cap" means no CONFIGURED cap, not an unbounded LIMIT; a page of a
+      # million records is already far past what any client can render.
+      MAX_PER_PAGE = 1_000_000
 
       included do
         class_attribute :paginatable_per_page, default: DEFAULT_PER_PAGE
@@ -59,8 +74,8 @@ module ConcernsOnRails
         #   paginate_by per_page: 50, max_per_page: 500, link_header: false
         def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE, link_header: true,
                         page_param: nil, per_page_param: nil, style: :flat, window: nil)
-          self.paginatable_per_page = per_page.to_i
-          self.paginatable_max_per_page = max_per_page.to_i
+          self.paginatable_per_page = paginatable_per_page!(per_page)
+          self.paginatable_max_per_page = paginatable_max_per_page!(max_per_page)
           self.paginatable_link_header = link_header ? true : false
           self.paginatable_window = paginatable_window!(window)
           defaults = paginatable_style_params!(style)
@@ -79,6 +94,29 @@ module ConcernsOnRails
           end
         end
 
+        # per_page must be positive. A bare `.to_i` let a negative through, and
+        # `LIMIT -1` means NO LIMIT on SQLite and MySQL — so `per_page: -1`
+        # silently serialized the entire table on every request, while
+        # `per_page: 0` made every page permanently empty. Both are broken
+        # configuration with no sane reading, so they raise at class-load time
+        # rather than misbehaving on every request.
+        def paginatable_per_page!(value)
+          size = value.to_i
+          return size if size.positive?
+
+          raise ArgumentError, "#{LABEL}: per_page: must be a positive integer (got #{value.inspect})"
+        end
+
+        # max_per_page does NOT raise: "0 or a negative integer disables the
+        # cap" is this option's documented contract, so rejecting a negative
+        # would fail the boot of an app that is configured exactly as written —
+        # and on a patch upgrade at that. Normalize to 0 instead; the reader's
+        # guard only asks whether the cap is positive.
+        def paginatable_max_per_page!(value)
+          size = value.to_i
+          size.negative? ? 0 : size
+        end
+
         # nil / false disable the window (no `pages:` key). `0` is meaningful:
         # first, current and last only.
         def paginatable_window!(value)
@@ -206,14 +244,18 @@ module ConcernsOnRails
       # Both readers route through ScalarParam: `?page[]=1` / `?page[x]=1`
       # arrive as Array/Parameters, and calling .to_i on those was a 500.
       def pagination_page
-        [ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0), 1].max
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0)
+        requested.clamp(1, MAX_PAGE)
       end
 
       def pagination_per_page
         requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_per_page_param), default: 0)
         requested = self.class.paginatable_per_page if requested < 1
         cap = self.class.paginatable_max_per_page
-        cap.positive? ? [requested, cap].min : requested
+        requested = [requested, cap].min if cap.positive?
+        # Applied even when a cap IS configured: `max_per_page: 10**30` is its
+        # own way of asking for the overflow back.
+        [requested, MAX_PER_PAGE].min
       end
 
       # Dig the configured path out of params: `["page"]` → params[:page];