permittable 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddca88b2da7672d0995e338ab901188c4ba019f4d5928d7aaf0a5f73a7f8ba9c
-  data.tar.gz: 1a66ef88adc7ab843798f25c7a5e3444a3e550795d1353139d52b65e05ac5005
+  metadata.gz: 9f13494f2345ced22c261510fd65e89b855b263931a423e6abfb3acb9c3df605
+  data.tar.gz: b88b5cad51b572acabe91453a322869d3167671854f37f8ec27cd80b2454d361
 SHA512:
-  metadata.gz: 7288c663fd8a2d740ca1c1e7fe9ad61d50854fa47e0e9c4a75bb0922bd119d7c4ca9fe99b020b6ea03edfb456d0fe88322161d53cc1bdd71afb6b88f6cf6ccda
-  data.tar.gz: a9ecd5c620fac068991a0401d76f339163eb20b6bed73ab83a33f5c3895f8bfb82479a86ab9d6385d85321732ce8ebc6c332819b32174bc8d0494c6021d1623f
+  metadata.gz: f3255855aee7d875af804e0984e3b1939b4018a3d4e51134e15ea61ad53fbcc549e6ec9464ffcc158d5b0a64a0e140a34806b7e37abd24f1b66fa5fbec88bec1
+  data.tar.gz: 658e22032c03f6413ad6343d20a8d493c07158975fea4223cac3fcda3a3db71c119d17f4744f79e1c53982560019b8690be6b03dad7a1f7e3cfe1ca68672d414

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 <!-- CHANGELOG.md -->
 
+## 0.7.0 (2026-09-16)
+<!-- title: sensitive: redaction, uncorruptible defaults, and stricter class load -->
+
+Two silent disclosures and three silent corruptions, all in code that was doing its job wrongly rather than not at all: `sensitive:` redacted nothing unless the value was a String, a swapped filter registry stopped being consulted, a mutable `default:` was shared by every request in the process, `normalize:` could manufacture an empty value that walked past `required`, and `unknown: :error` rejected the keys Rails itself adds to a form POST. Contract mistakes that could only ever fail at request time now fail at class load instead.
+
+### Fixed
+- **Swapping `Permittable.filter_parameter_registry` silently stopped `sensitive:` redaction.** `Permittable::Railtie` appended `filter_parameter_registry.to_proc` — a proc bound to whichever registry instance existed **at boot**. Rails runs railtie initializers *before* `config/initializers`, so a host gem or app that swaps the registry necessarily does so afterwards, leaving Rails filtering through the old instance: `sensitive:` fields registered themselves in the new registry, and the appended proc went on consulting an empty one. The parameter was logged in the clear, with nothing to indicate it. That swap is the reason the writer exists — the gem's own comment names `concerns_on_rails` as doing exactly this — so the broken ordering was the normal case rather than an exotic one. The Railtie now appends `Permittable.filter_parameter_proc`, which resolves the registry at **filter time**; it is one frozen object for the life of the process, so the Railtie's idempotence check still holds across repeated initializer runs.
+- **`sensitive:` redacted nothing unless the value was a String.** The mechanism was a proc filter, and ActiveSupport's `ParameterFilter` dups the value before invoking one and expects in-place mutation — so `optional :pin, :integer, sensitive: true` logged `1234` in the clear, and `sensitive: true` on a nested block logged the whole hash, since `ParameterFilter` checks `value.is_a?(Hash)` *before* the proc filters and recurses into it instead of ever calling them. Both are silent disclosures of exactly the fields a contract marked as the ones not to print. Each registered name is now **also added to `config.filter_parameters` by name**, which redacts a value of any type, while the proc stays for what only it can reach (consumers that snapshot the array at boot). A real Rails boot covers an `:integer` field, a sensitive nested block, and `#inspect`, with `precompile_filter_parameters` on — the modern default, and the reason the mechanism has to be a name rather than a live matcher object: precompilation joins filters by pattern source and discards anything whose matching is decided at filter time. `Permittable.on_sensitive_parameter` is the seam the Railtie installs, so the registry itself stays free of Rails.
+- **A mutable `default:` was shared by every request.** Field declarations are frozen data, but the *value* an author wrote for `default:` was not, and `HashWithIndifferentAccess` hands a non-frozen Array — and any String — to the result **by reference**. So `array :tags, of: :string, default: []` gave every request the same Array: one request appending to `permitted_params[:tags]` corrupted the default for every later request in the process, and `Model.new(tags: …)` assigns that same object, so `record.tags << x` was enough to trigger it. The corruption outlived the request and lasted for the life of the process. A `default:` (and a documentation `example:`) is now **deep-copied and frozen at class load**, so the contract cannot be corrupted, and each request is handed its own copy. The copy is the point: the object the host app passed in is never frozen, in case it is still using it.
+- **`normalize:` could manufacture an empty value that walked past `required`.** `""` is documented as absent, so a required field must violate — but normalization ran *after* absence had already been decided. `required :name, :string, normalize: :squish` therefore rejected `""` as `missing` and **accepted `"   "` as `""`**, writing an empty string into the column: exactly the silent corruption strict coercion exists to refuse, delivered by the gem's own preset. `normalize:` now runs **first**, before the absence rule, so a value that normalizes to empty is absent like any other empty value — it takes the `nullable:` / `default:` / `missing` branch. There is still exactly one reading of absence, and a `normalize:` Proc is still called exactly once per value. Relatedly, a `default:` is now **stored** in the form it was validated in: `default: "  free  "` with `normalize: :squish` was checked as `"free"` and used to be handed to requests as `"  free  "`.
+- **`unknown: :error` rejected ordinary form submissions.** Only the router's `controller`/`action`/`format` were exempt from the top-level unknown-key check, but Rails also merges `authenticity_token`, `_method`, `utf8` and `commit` into a form POST — so the strictest setting was unusable outside a JSON API, and every browser form failed on four of the framework's own keys rather than on anything the client got wrong. Those four are now exempt at the top level too. The exemption covers the *check* only, and only at the top level: a form key smuggled inside a `root:` or a nested hash is still `unknown`, a standalone `Permittable::Contract` still exempts nothing (it has neither a router nor a form), and monitor mode still passes the form keys through in its raw hash, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `_method` itself.
+- **An exported `pattern` could be stricter than the rule the server enforces.** Ruby's `^` and `$` anchor a **line**; ECMA-262's, without the `m` flag, anchor the whole string. So `format: /^\d{5}$/` accepts `"evil\n12345"` at runtime while the exported `"pattern": "^\\d{5}$"` rejects it — the documentation and the enforcement disagreeing, which is the one thing an export from contract data is meant to make impossible. Such a regexp now joins the constructs that stay visible as `x-permittable-pattern` instead of being mistranslated, alongside `\Z`, `\h` and the POSIX classes. Straight after `[` neither one is an anchor — `^` is class negation and `$` a literal — so `[^a]` and `[$]` still translate, as does an escaped `\$` or `\^`. `\A`/`\z` translate exactly and remain the anchors to reach for.
+
+- **A block array's `default:` was checked against a different reading of absence than the request it stands in for.** `""` is absent, so a client sending `items: [{ "sku" => "" }]` is refused with `items[0].sku missing` — but the class-load check for a block array's `default:` treated only `nil` as absent, so `default: [{ "sku" => "" }]` was accepted, and a `default:` is applied **without revalidation**: every request that omitted the key was handed the exact value the contract refuses from a client. The same held for a value that normalizes to empty, because the check normalized *after* deciding absence rather than before. That check now reads absence the way the walker does — normalize first, then `nil`/`""`, with `nullable:` splitting the rule for an explicitly-empty value exactly as it does at request time — and the value half of that rule is now one shared predicate rather than two spellings of it.
+
+Contracts that declare no `default:`, no `normalize:`, and no `unknown: :error` are unaffected.
+
+### Added
+- **Swapping the registry now carries the entries it already holds into the new one.** Late-binding the proc fixes redaction for contracts that load *after* a swap, but on its own it breaks the other half: nothing consults the outgoing registry again, so a `sensitive:` field registered by a contract that loaded *before* the swap would have stopped being redacted — the exact mirror image of the bug above, and the case a host gem pooling registrations is most likely to hit, since eager loading in production loads plenty of controllers before `config/initializers` runs. `Permittable.filter_parameter_registry=` now re-adds each name from the outgoing registry (read through a new duck-typed `#names`) to the incoming one, and a real Rails boot covers both halves.
+- **`Permittable.filter_parameter_registry=` validates what it is given.** A registry with no `#to_proc` used to be accepted silently and simply never consulted; with the proc late-bound it would instead have raised `NoMethodError` inside `process_action` on every request. It now raises `ArgumentError` at the point of the swap, naming the class. The registry's callable may take Rails' two-argument (`key, value`) or three-argument (`key, value, original_params`) proc-filter shape; both are dispatched by arity.
+
+### Changed
+- **A bound that no value could satisfy now fails at class load.** A reversed or empty `Range` excludes every value there is, so the field it bounds could never validate — and that surfaced as every request to the action failing on that field: a contract mistake reported to clients as their error, once per request, forever. `in: 65..18`, `length: 5..2`, `length: 3...3`, an empty `in: []`, a negative `length:`, and a `length:` of 0 on a `required` field (where `""` is absent and already violates as `missing`, so nothing is left to accept) are now `ArgumentError` at class load, naming the bound. Endless and beginless Ranges are legitimate and unaffected, as are endpoints that cannot be compared. **Breaking** for a contract that ships such a field, but only for one that was already failing 100% of the requests that reached it.
+- **An array declared with a block now checks its `default:` too.** `validate_array_authored_value!` only checked elements against `of:`, which is nil for a block array — so `array :items, default: [{ "nonsense" => true }] do required :sku, :string end` was accepted at class load and handed to every request that omitted the key, bypassing the contract the block declares. Elements are now checked against the block's own fields (required sub-fields present, scalar ones satisfying their own contract), the same shallow check `of:` gets. **Breaking** for a contract whose block-array default was already wrong, which previously returned that value rather than rejecting it.
+
+
 ## 0.6.0 (2026-09-08)
 <!-- title: nullable fields, :json, and strict dates -->
 

data/README.md

@@ -210,7 +210,7 @@ Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live
 request params
    │
    ├─ 1  unwrap root:        params[:user]                missing or not a hash → 400
-   ├─ 2  each field          normalize → cast → validate → transform
+   ├─ 2  each field          normalize → absent? → cast → validate → transform
    ├─ 3  unknown-key check   at every nesting level       (unknown: :ignore | :log | :error)
    ├─ 4  finalize            only when nothing violated
    │
@@ -290,8 +290,8 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `in:` | ✅ | — | — | Allowed values: a `Range` (bounds-checked with `cover?`) or an `Array` |
 | `format:` | ✅¹ | — | — | Regexp the value must match |
 | `length:` | ✅¹ | ✅ | — | `Range` or `Integer`. Character count on strings, **element count** on arrays |
-| `normalize:` | ✅¹ | — | — | `:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc. Runs **before** the cast |
-| `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load |
+| `normalize:` | ✅¹ | — | — | `:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc. Runs **first** — before the absence rule, so a value that normalizes to `""` is absent |
+| `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load, then stored normalized and frozen (each request gets its own copy) |
 | `validate:` | ✅ | ✅ | — | Callable. Falsy fails as `"invalid"`; a returned `Symbol` becomes the violation code |
 | `transform:` | ✅ | ✅ | — | Callable applied **after** cast and validation — see [output reshaping](#output-reshaping-transform-and-finalize) |
 | `virtual:` | ✅ | ✅ | ✅ | Exempt this field from the schema-drift guard |
@@ -365,7 +365,7 @@ In [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) the field is `{
 
 ### Absence, defaults, and partial updates
 
-`nil` and `""` are **both treated as absent** — the query-parameter convention, where an untouched form field arrives as an empty string. Boolean `false` is present.
+`nil` and `""` are **both treated as absent** — the query-parameter convention, where an untouched form field arrives as an empty string. Boolean `false` is present. `normalize:` runs *before* this rule, so a field declared `normalize: :squish` treats `"   "` as absent too: whitespace cannot satisfy a `required` field by becoming `""`.
 
 That single rule produces the behaviour you want from a `PATCH`:
 
@@ -487,7 +487,9 @@ Resolution order per violation: the field's own `message:` (String, or the Hash
 | `:log` | Dropped, with a `logger.warn` naming the full paths |
 | `:error` | Each undeclared key becomes an `unknown` violation |
 
-Rails merges `controller`, `action`, and `format` into `params`; these are exempt at the top level so `unknown: :error` doesn't flag the router's own bookkeeping. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there.
+Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token`, `_method`, `utf8`, and `commit` from an ordinary form POST. All seven are exempt at the top level, so `unknown: :error` flags what the *client* got wrong rather than what the framework added. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there — and a standalone `Contract` exempts nothing at all, having neither a router nor a form.
+
+The exemption covers the *check* only. Monitor mode still hands back the form keys in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `_method` itself; only the router's three are dropped there.
 
 ### Output reshaping (`transform:` and `finalize`)
 
@@ -553,9 +555,15 @@ Mark a field `sensitive: true` and its name is registered with `Permittable.filt
 optional :ssn, :string, sensitive: true
 ```
 
-The indirection is deliberate. Appending plain symbols to `config.filter_parameters` at class-load time misses every consumer that snapshots the list at boot — ActiveRecord's `filter_attributes` copy, lograge-style initializers, precompiled filters. A **single proc appended once at boot, consulting a live registry at filter time**, means fields registered when a controller loads later (lazy loading in development) are still redacted. The initializer runs before `active_record.set_filter_attributes`, so values are redacted from both request logs and `#inspect`.
+Two mechanisms, because neither covers the ground alone.
+
+A **single proc appended once at boot, consulting a live registry at filter time**, is what reaches consumers that snapshot `config.filter_parameters` at boot — ActiveRecord's `filter_attributes` copy, lograge-style initializers — so a field registered when a controller loads later (lazy loading in development) is still redacted there. The initializer runs before `active_record.set_filter_attributes`, so values are redacted from both request logs and `#inspect`.
+
+But a proc filter can only redact **String** values: ActiveSupport dups the value and expects in-place mutation, and for a `Hash` value it never calls the proc at all, recursing into it instead. So each name is **also registered as a name** in `config.filter_parameters`, which redacts a value of any type — an `:integer` field, or a whole sensitive nested block. Appending later still works: Rails' `precompile_filter_parameters` replaces that array *in place*, and `ActionDispatch` reads the same object on every request, so a name registered at class-load time is seen by the next request. (This is also why the mechanism is a name and not a live matcher object: precompilation joins patterns by source, which discards anything whose matching is decided at filter time.)
+
+Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring match on the parameter key. The registry is fully duck-typed (`#add`, `#include?`, `#to_proc`, `#names`, `#reset!`) and swappable via `Permittable.filter_parameter_registry=`, so a host gem can pool registrations into its own. `#to_proc` must return a callable of arity 2 (`key, value`) or 3 (`key, value, original_params`), matching what Rails' own parameter filtering accepts; anything that does not respond to `#to_proc` is refused at the point of the swap rather than on the next request.
 
-Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring match on the parameter key. The registry is fully duck-typed (`#add`, `#include?`, `#to_proc`, `#reset!`) and swappable via `Permittable.filter_parameter_registry=`, so a host gem can pool registrations into its own.
+**The swap works at any point**, including from `config/initializers` — which matters, because Rails runs railtie initializers *before* those, so a swap always happens after `Permittable::Railtie` has appended its filter. Two things make that safe. The appended proc (`Permittable.filter_parameter_proc`) resolves the registry at **filter time** rather than closing over whichever instance existed at boot, so whichever registry is current does the redacting. And the swap **carries the previous registry's names into the new one**, so a `sensitive:` field registered by a contract that loaded before the swap keeps being redacted afterwards. Without that, the two halves of an app would each redact only what the other did not.
 
 ### Instrumentation
 
@@ -728,7 +736,7 @@ Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 
 Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern` — including one anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
 
 Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
 
@@ -782,7 +790,8 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | Constant | Purpose |
 |---|---|
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
-| `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
+| `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry; entries already registered are carried across |
+| `Permittable.filter_parameter_proc` | The single proc `Permittable::Railtie` appends to `config.filter_parameters`; consults the current registry at filter time |
 | `Permittable.mode` / `Permittable.mode=` | App-wide default (`:enforce`) for rules that don't declare their own `mode:` |
 | `Permittable::InvalidParameters` | Raised on violation; carries `#details` and `#status` |
 | `Permittable::JsonSchema` | Contract data → JSON Schema fragments (`.rule`, `.object`, `.field`) |
@@ -805,9 +814,10 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - An unknown type, listing the supported ones
 - An unknown `normalize:` preset, listing the presets
 - `format:`, `length:`, or `normalize:` on a non-`:string` field
-- `length:` that isn't a `Range` or `Integer`; `in:` that doesn't respond to `include?`
+- `length:` that isn't a non-negative `Integer` or a `Range`; `in:` that doesn't respond to `include?`
+- A bound **no value could satisfy**: a reversed or empty `Range` (`in: 65..18`, `length: 5..2`, `length: 3...3`), an empty `in:` set, or a `length:` of 0 on a `required` field (where `""` already violates as `missing`)
 - `validate:` or `transform:` that isn't callable
-- A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:`
+- A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:` — or, for an array declared with a **block**, an element that isn't a hash the block would accept
 - A `default: nil` or `example: nil` on a field that isn't `nullable:`
 - A `:json` field's `default:`/`example:` that isn't a Hash, or that its own `length:`/`max_depth:` would reject
 - A `max_depth:` that isn't a positive Integer

data/lib/permittable/filter_parameter_registry.rb

@@ -10,8 +10,9 @@ module Permittable
   #
   # Matching mirrors Rails symbol-filter semantics: case-insensitive substring
   # match on the parameter key. The whole object is duck-typed (#add,
-  # #include?, #to_proc, #reset!) so a host can swap in its own registry via
-  # `Permittable.filter_parameter_registry=` and pool registrations.
+  # #include?, #to_proc, #names, #reset!) so a host can swap in its own
+  # registry via `Permittable.filter_parameter_registry=` and pool
+  # registrations.
   class FilterParameterRegistry
     FILTERED = "[FILTERED]".freeze
 
@@ -55,6 +56,14 @@ module Permittable
       @proc
     end
 
+    # The names registered so far. Permittable.filter_parameter_registry=
+    # reads this off the outgoing registry and re-adds each name to the
+    # incoming one, so a swap never un-redacts a field that a contract
+    # loaded before it had already registered.
+    def names
+      @mutex.synchronize { @fields.to_a }
+    end
+
     # Spec hygiene — the registry is process-global.
     def reset!
       @mutex.synchronize do

data/lib/permittable/json_schema.rb

@@ -33,16 +33,23 @@ module Permittable
 
     # Ruby regexp constructs with no ECMA-262 equivalent (\Z, \h, \K, \R, \G,
     # inline flag groups, absence operator, conditionals, POSIX classes,
-    # possessive quantifiers). A source matching this is left untranslated —
-    # the scan is deliberately over-eager on escaped lookalikes because a
-    # wrong pattern in published docs is worse than a missing one.
+    # possessive quantifiers) — and Ruby's ^ and $, which anchor a LINE where
+    # ECMA-262 without the m flag anchors the whole string. /^\d{5}$/ accepts
+    # "evil\n12345" at runtime, so emitting its source as `pattern` would
+    # publish a rule stricter than the server enforces, and an export from
+    # contract data is supposed to make that impossible. Straight after a [
+    # neither is an anchor — ^ is class negation and $ is a literal — so both
+    # stay translatable there. Otherwise the scan is deliberately over-eager
+    # on escaped lookalikes, because a wrong pattern in published docs is
+    # worse than a missing one.
     UNTRANSLATABLE = /
       \\[ZhHKRG]          |
       \(\?[a-z-]+[:)]     |
       \(\?~               |
       \(\?\(              |
       \[\[:               |
-      [*+?]\+
+      [*+?]\+             |
+      (?<![\\\[])[\^$]
     /x
 
     # Request-body schema for one rule from `permittable_contracts` /

data/lib/permittable/railtie.rb

@@ -9,8 +9,24 @@ module Permittable
   class Railtie < Rails::Railtie
     initializer "permittable.filter_parameters",
                 before: "active_record.set_filter_attributes" do |app|
-      filter = ::Permittable.filter_parameter_registry.to_proc
+      # Late-bound on purpose — see Permittable.filter_parameter_proc. This
+      # initializer runs before config/initializers, so a registry swapped
+      # there must still be the one consulted at filter time.
+      filter = ::Permittable.filter_parameter_proc
       app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
+
+      # The proc above redacts Strings, live, and survives precompilation.
+      # What it cannot reach is a value that is not a String — ParameterFilter
+      # mutates values in place for proc filters, and skips them entirely for
+      # a Hash — so each registered name is ALSO added by name, which redacts
+      # any value type. Appending later still works: precompilation `replace`s
+      # this array in place and ActionDispatch reads the same object per
+      # request, so a name registered when a controller loads is seen by the
+      # next request. It is the array, not a snapshot, that has to be fed.
+      ::Permittable.on_sensitive_parameter do |name|
+        filters = app.config.filter_parameters
+        filters << name unless filters.include?(name)
+      end
     end
 
     rake_tasks do

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.6.0".freeze
+  VERSION = "0.7.0".freeze
 end

data/lib/permittable.rb

@@ -4,6 +4,7 @@ require "active_support/notifications"
 require "active_support/hash_with_indifferent_access"
 require "active_support/core_ext/hash/indifferent_access" # nested plain Hashes inside HWIA.new
 require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/deep_dup" # authored default:/example: values are copied before freezing
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/string/filters"
 require "bigdecimal"
@@ -98,7 +99,12 @@ require "permittable/filter_parameter_registry"
 # guess. nil and "" are both treated as ABSENT (the query-param convention):
 # absent optional fields are OMITTED from the result (so partial updates never
 # nil-out columns), absent required fields violate, and `default:` fills
-# absence.
+# absence. `normalize:` runs BEFORE that rule rather than inside the cast, so
+# there is exactly one reading of absence and a value that normalizes to empty
+# ("   " under :squish) cannot satisfy a required field by becoming "". An
+# authored `default:`/`example:` is stored normalized — the form it was
+# validated in — and deep-frozen on a copy, so no request can corrupt it for
+# the next.
 #
 # `nullable: true` splits that rule in two for one field, which is how a PATCH
 # clears a column: a key the client never sent stays absent (defaults apply,
@@ -127,7 +133,12 @@ require "permittable/filter_parameter_registry"
 # `sensitive: true` registers the field name with
 # Permittable.filter_parameter_registry (swappable — a host gem can point it
 # at its own registry), consulted at filter time by the proc
-# Permittable::Railtie appends to `config.filter_parameters`.
+# Permittable::Railtie appends to `config.filter_parameters`. The name is
+# ALSO published to that Railtie by name (see register_sensitive_parameter),
+# because a proc filter can only redact String values — ActiveSupport dups
+# the value and expects in-place mutation, and never calls the proc at all
+# for a Hash — so a name in config.filter_parameters is what covers an
+# :integer field or a sensitive nested block.
 #
 # OUTPUT RESHAPING — the safe replacement for params-mutating before_actions.
 # Two layers, both operating on the validated COPY (the request's `params` is
@@ -162,6 +173,31 @@ module Permittable
   # Rails merges routing bookkeeping into params; a top-level (root: false)
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
+  # Nor the keys an ordinary form POST carries — the CSRF token, the verb
+  # override, the encoding probe, and the submit button's name. Without this
+  # `unknown: :error` was unusable outside a JSON API: every browser form
+  # failed on the framework's own keys rather than on anything the client got
+  # wrong. Exempt from the CHECK only: unlike the routing keys these are NOT
+  # stripped from monitor mode's raw pass-through, where handing back an
+  # untouched params hash is the whole promise and a legacy action may well
+  # read `_method` itself.
+  FORM_KEYS = %w[authenticity_token _method utf8 commit].freeze
+  # ROUTING_KEYS/FORM_KEYS name where the keys come FROM; these two name what
+  # is DECIDED with them, which is what the call sites care about — and the
+  # asymmetry between them is the deliberate point, so spell it once here
+  # rather than leaving a bare ROUTING_KEYS to read like an oversight.
+  UNCHECKED_TOP_LEVEL_KEYS = (ROUTING_KEYS + FORM_KEYS).freeze
+  MONITOR_DROPPED_KEYS = ROUTING_KEYS
+
+  # The single proc Permittable::Railtie appends to config.filter_parameters.
+  # Declared with an optional third parameter so its own arity is -3 and Rails
+  # passes `original_params`; the registry's callable is then invoked by ITS
+  # arity, so both the 2- and 3-argument proc-filter shapes Rails accepts work
+  # as a swapped-in registry's #to_proc.
+  FILTER_PARAMETER_PROC = lambda do |key, value, original = nil|
+    inner = filter_parameter_registry.to_proc
+    inner.arity == 2 ? inner.call(key, value) : inner.call(key, value, original)
+  end.freeze
 
   NORMALIZERS = {
     squish: ->(v) { v.squish },
@@ -183,7 +219,84 @@ module Permittable
       end
     end
 
-    attr_writer :filter_parameter_registry
+    # Swapping registries must not un-redact anything. Contracts that loaded
+    # BEFORE the swap registered on the outgoing registry, and after the swap
+    # nothing consults it any more — so its entries are carried into the new
+    # one, which is the mirror image of the bug that made the proc late-bound
+    # in the first place. Validated here rather than at filter time: a
+    # registry with no #to_proc used to be silently never consulted, and
+    # late-binding it would instead raise NoMethodError on every request.
+    def filter_parameter_registry=(registry)
+      unless registry.nil? || registry.respond_to?(:to_proc)
+        raise ArgumentError,
+              "#{LABEL}: filter_parameter_registry must respond to #to_proc (got #{registry.class})"
+      end
+
+      @registry_mutex.synchronize do
+        previous = @filter_parameter_registry
+        @filter_parameter_registry = registry
+        next unless registry && previous.respond_to?(:names) && registry.respond_to?(:add)
+
+        previous.names.each { |name| registry.add(name) }
+      end
+      registry
+    end
+
+    # The proc Permittable::Railtie appends to config.filter_parameters.
+    #
+    # It resolves the registry at FILTER time rather than closing over
+    # whichever instance existed at boot. Rails runs railtie initializers
+    # BEFORE config/initializers, so an app or host gem that swaps the
+    # registry — the pooling the writer exists for — necessarily does so
+    # after the Railtie has already appended its proc. A proc bound to the old
+    # instance would go on consulting an empty registry and silently redact
+    # nothing, while `sensitive:` fields registered themselves in the new one.
+    #
+    # One frozen object for the life of the process, so the Railtie's
+    # idempotence check (include? before <<) holds across repeated initializer
+    # runs with no memo to synchronise.
+    def filter_parameter_proc
+      FILTER_PARAMETER_PROC
+    end
+
+    # Every `sensitive:` registration, published to whatever is listening.
+    #
+    # A proc filter cannot be the whole mechanism: ActiveSupport's
+    # ParameterFilter dups the value and expects in-place mutation, so a proc
+    # can only redact Strings — and it is never even CALLED for a Hash value,
+    # because ParameterFilter checks `value.is_a?(Hash)` first and recurses.
+    # So `optional :pin, :integer, sensitive: true` and `sensitive:` on a
+    # nested block both logged in the clear. What redacts any value type is a
+    # NAME in config.filter_parameters, which only Rails can be told about —
+    # hence a sink, installed by Permittable::Railtie, rather than Rails
+    # knowledge in this file or in the registry.
+    def register_sensitive_parameter(name)
+      filter_parameter_registry.add(name)
+      # Normalized the way the registry normalizes, so the name a sink sees is
+      # the same whether it arrives here or through on_sensitive_parameter's
+      # replay of #names — otherwise a sink deduplicating by value would hold
+      # both :ssn and "ssn".
+      name = name.to_s.downcase
+      sensitive_parameter_sinks.each { |sink| sink.call(name) } unless name.empty?
+      nil
+    end
+
+    # Install a sink. It is replayed over the names already registered, since
+    # a contract can be declared before the Railtie's initializer runs (a
+    # Permittable::Contract at require time, an eager-loaded controller) and
+    # would otherwise never reach it.
+    def on_sensitive_parameter(&sink)
+      @registry_mutex.synchronize { sensitive_parameter_sinks << sink }
+      registry = filter_parameter_registry
+      registry.names.each { |name| sink.call(name) } if registry.respond_to?(:names)
+      sink
+    end
+
+    # The installed sinks. Process-global, like the registry — specs that
+    # install one `.clear` this afterwards.
+    def sensitive_parameter_sinks
+      @sensitive_parameter_sinks ||= []
+    end
 
     # App-wide default for rules that don't declare their own mode:.
     # :enforce (the default) rejects violating requests; :monitor reports
@@ -250,10 +363,12 @@ module Permittable
     TRUE_VALUES = [true, "true", "1", 1].freeze
     FALSE_VALUES = [false, "false", "0", 0].freeze
 
-    # Full pipeline for one scalar field: normalize → cast → in / format /
-    # length / validate.
+    # Pipeline for one scalar field: cast → in / format / length / validate.
+    # `normalize:` is NOT applied here — it is its own stage, run by the
+    # caller before the absence rule (a value that normalizes to "" is absent
+    # like any other empty value), so normalizing again here would call a
+    # host's `normalize:` proc twice per value.
     def check_scalar(field, value)
-      value = apply_normalize(field[:normalize], value)
       status, value = cast(field[:type], value)
       return [status, value] unless status == :ok
 
@@ -429,6 +544,14 @@ module Permittable
       normalizer.call(value)
     end
 
+    # nil and "" are both ABSENT — see the module comment. The VALUE half of
+    # that rule (the walker adds the key-presence half), shared with
+    # macro-time `default:`/`example:` checking so a default cannot be held
+    # to a different reading of absence than the request it stands in for.
+    def absent_value?(value)
+      value.nil? || (value.is_a?(String) && value.empty?)
+    end
+
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
     # and the right semantics for validation.
     def included_in?(allowed, value)
@@ -575,12 +698,18 @@ module Permittable
       if field[:required] && field.key?(:default)
         raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
       end
-      if field.key?(:in) && !field[:in].respond_to?(:include?)
-        raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+
+      if field.key?(:in)
+        unless field[:in].respond_to?(:include?)
+          raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+        end
+
+        assert_satisfiable!(name, :in, field[:in])
       end
 
       validate_string_only_opts!(field)
       validate_length!(name, field[:length]) if field.key?(:length)
+      validate_required_length!(field)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
       resolve_normalizer!(field)
@@ -618,9 +747,9 @@ module Permittable
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
       status, code = Coercion.check_json(field, field[opt])
-      return if status == :ok
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
 
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+      field[opt] = freeze_authored(field[opt])
     end
 
     # format / length / normalize reason about characters; on any other
@@ -636,9 +765,49 @@ module Permittable
     end
 
     def validate_length!(name, length)
-      return if length.is_a?(Range) || length.is_a?(Integer)
+      unless length.is_a?(Range) || (length.is_a?(Integer) && !length.negative?)
+        raise ArgumentError, "#{LABEL}: :length for :#{name} must be a non-negative Integer or a Range " \
+                             "(got #{length.inspect})"
+      end
+
+      assert_satisfiable!(name, :length, length)
+    end
 
-      raise ArgumentError, "#{LABEL}: :length for :#{name} must be a Range or Integer"
+    # A reversed Range (5..2), an exclusive Range with equal endpoints
+    # (3...3), or an empty set (in: []) excludes every value there is, so the
+    # field it bounds can never validate. That used to surface as every
+    # request to the action failing on that field — a contract mistake
+    # reported as a client error, once per request, forever. Endless and
+    # beginless Ranges are legitimate bounds, and endpoints that cannot be
+    # compared are left alone rather than guessed at.
+    def assert_satisfiable!(name, opt, bound)
+      return unless unsatisfiable?(bound)
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for :#{name} is empty (#{bound.inspect}) — no value can satisfy it"
+    end
+
+    def unsatisfiable?(bound)
+      return bound.empty? if bound.respond_to?(:empty?)
+      return false unless bound.is_a?(Range) && bound.begin && bound.end
+
+      comparison = bound.begin <=> bound.end
+      return false if comparison.nil?
+
+      bound.exclude_end? ? !comparison.negative? : comparison.positive?
+    end
+
+    # "" is ABSENT and an absent required field violates as missing, so a
+    # required string can never validly be empty: a maximum length of 0
+    # leaves it nothing at all to accept. The exported schema already said
+    # so — minLength 1 alongside maxLength 0 — while nothing refused the
+    # declaration that produced it.
+    def validate_required_length!(field)
+      spec = field[:length]
+      return unless field[:required] && spec
+      return unless Coercion.length_ok?(spec, 0) && !Coercion.length_ok?(spec, 1)
+
+      raise ArgumentError, "#{LABEL}: :length for :#{field[:name]} is 0 on a required field — an absent or " \
+                           "empty value already violates as missing, so nothing could satisfy it"
     end
 
     def validate_callable!(name, opt, value)
@@ -661,22 +830,75 @@ module Permittable
     # An authored value (`default:`, or a documentation `example:`) must
     # satisfy the field's own contract — catching a lie at class load beats
     # shipping it to every request (or publishing it in generated docs).
+    # The authored value is STORED normalized, because that is the form it was
+    # validated in: `default: "  free  "` with `normalize: :squish` was
+    # checked as "free" and used to be handed to requests as "  free  ".
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
 
-      status, code = Coercion.check_scalar(field, field[opt])
-      return if status == :ok
+      value = Coercion.apply_normalize(field[:normalize], field[opt])
+      status, code = Coercion.check_scalar(field, value)
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
 
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+      field[opt] = freeze_authored(value)
     end
 
     def validate_array_authored_value!(field, opt)
       value = field[opt]
       return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
-      return unless field[:of]
 
+      validate_array_elements!(field, opt, value) if field[:of]
+      validate_array_element_hashes!(field, opt, value) if field[:fields]
+      field[opt] = freeze_authored(value)
+    end
+
+    # The nested-block counterpart of the of: element check below. Without it
+    # `field[:of]` was nil for a block array, so its `default:` skipped
+    # validation entirely and whatever was authored went straight to every
+    # request that omitted the key. Shallow in the same way the of: check is:
+    # required sub-fields must be present and scalar ones must satisfy their
+    # own contract, which is what an authored value gets wrong.
+    def validate_array_element_hashes!(field, opt, value)
+      value.each do |element|
+        unless element.is_a?(Hash)
+          raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains #{element.class} " \
+                               "where the block declares a hash"
+        end
+
+        # Wrapped the way permittable_check_element wraps an element at
+        # request time, so class load reads keys exactly as a request does.
+        indifferent = ActiveSupport::HashWithIndifferentAccess.new(element)
+        field[:fields].each { |sub| validate_array_element_field!(field, opt, indifferent, sub) }
+      end
+    end
+
+    def validate_array_element_field!(field, opt, element, sub)
+      # Normalized before absence is read, and absence read with the runtime's
+      # own rule: a default: is applied WITHOUT revalidation, so anything this
+      # check waves through is handed to the app unexamined — and "" here used
+      # to mean a default could carry the very value a client is refused.
+      value = Coercion.apply_normalize(sub[:normalize], element[sub[:name]])
+      if Coercion.absent_value?(value)
+        # nullable: splits that rule exactly as permittable_explicit_null?
+        # does — a key present but empty is an explicit null, not an absence.
+        return if sub[:nullable] && element.key?(sub[:name])
+        return unless sub[:required]
+
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} is missing :#{sub[:name]}, " \
+                             "which the block declares as required"
+      end
+      return unless sub[:kind] == :scalar
+
+      status, code = Coercion.check_scalar(sub, value)
+      return if status == :ok
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} has :#{sub[:name]} " \
+                           "violating its own contract (#{code})"
+    end
+
+    def validate_array_elements!(field, opt, value)
       value.each do |element|
         status, code = Coercion.cast(field[:of], element)
         next if status == :ok
@@ -685,6 +907,29 @@ module Permittable
       end
     end
 
+    # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
+    # field hashes — an authored `default:` or `example:` value stayed
+    # mutable, and HashWithIndifferentAccess hands a non-frozen Array (and
+    # any String) to the result BY REFERENCE. So one request appending to
+    # `permitted_params[:tags]` corrupted the default for every later request
+    # in the process. Freezing a COPY fixes that without freezing an object
+    # the host app passed in and may still be using.
+    def freeze_authored(value)
+      deep_freeze(value.deep_dup)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_pair do |key, element|
+          deep_freeze(key)
+          deep_freeze(element)
+        end
+      when Array then value.each { |element| deep_freeze(element) }
+      end
+      value.freeze
+    end
+
     # An authored nil is only meaningful on a nullable field, where it says
     # "absent means clear" (PUT semantics) rather than "no default". On any
     # other field it is a value nil could never satisfy, so it fails at class
@@ -848,7 +1093,7 @@ module Permittable
 
     def register_sensitive_params(fields)
       fields.each do |field|
-        Permittable.filter_parameter_registry.add(field[:name]) if field[:sensitive]
+        Permittable.register_sensitive_parameter(field[:name]) if field[:sensitive]
         register_sensitive_params(field[:fields]) if field[:fields]
       end
     end
@@ -957,7 +1202,7 @@ module Permittable
     return ActiveSupport::HashWithIndifferentAccess.new unless source
 
     passed = ActiveSupport::HashWithIndifferentAccess.new(source)
-    rule[:root] ? passed : passed.except(*ROUTING_KEYS)
+    rule[:root] ? passed : passed.except(*MONITOR_DROPPED_KEYS)
   end
 
   def raise_invalid_parameters!(violations, status:)
@@ -1039,13 +1284,13 @@ module Permittable
     fields.each do |field|
       key = field[:name].to_s
       full = permittable_path(path, key)
-      value = hash[key]
+      value = permittable_normalized(field, hash[key])
 
       if permittable_absent?(value, hash, key)
         if permittable_explicit_null?(field, hash, key)
           result[key] = nil
         elsif field.key?(:default)
-          result[key] = field[:default]
+          result[key] = permittable_default(field)
         elsif field[:required]
           violations << permittable_violation(field, full, "missing")
         end
@@ -1062,6 +1307,7 @@ module Permittable
     key = field[:name].to_s
     case field[:kind]
     when :scalar
+      # Already normalized by permittable_normalized, before the absence rule.
       permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
     when :json
       permittable_check_whole(field, Coercion.check_json(field, value), full, result, violations: violations)
@@ -1127,9 +1373,30 @@ module Permittable
     nil
   end
 
+  # `normalize:` runs BEFORE the absence rule, not inside the cast, so there
+  # stays exactly ONE reading of absence. Otherwise a value that normalizes to
+  # empty walked straight past it: `required :name, :string, normalize:
+  # :squish` rejected "" as missing but accepted "   " as "" — the silent
+  # corruption strict coercion exists to refuse, delivered by the gem's own
+  # preset. Only scalars take normalize:, and apply_normalize is itself a
+  # no-op without one, so it owns that decision for every caller.
+  def permittable_normalized(field, value)
+    Coercion.apply_normalize(field[:normalize], value)
+  end
+
+  # An authored default belongs to the contract, which is frozen data (see
+  # ContractBuilder#freeze_authored). HashWithIndifferentAccess copies a
+  # frozen Array or Hash as it assigns it, but stores a String as-is — so
+  # that one is copied here, leaving every value in the result the app's own
+  # to mutate.
+  def permittable_default(field)
+    value = field[:default]
+    value.is_a?(String) ? value.dup : value
+  end
+
   # nil and "" are both ABSENT — see the module comment.
   def permittable_absent?(value, hash, key)
-    !hash.key?(key) || value.nil? || (value.is_a?(String) && value.empty?)
+    !hash.key?(key) || Coercion.absent_value?(value)
   end
 
   # `nullable: true` splits the one absence rule in two: a key the client
@@ -1146,7 +1413,7 @@ module Permittable
 
     declared = fields.map { |f| f[:name].to_s }
     extra = hash.keys.map(&:to_s) - declared
-    extra -= ROUTING_KEYS if top_level
+    extra -= UNCHECKED_TOP_LEVEL_KEYS if top_level
     return if extra.empty?
 
     if unknown == :error

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport